summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorShlomi Fish <shlomif@iglu.org.il>2011-07-18 22:07:28 -0700
committerFather Chrysostomos <sprout@cpan.org>2011-07-18 22:09:18 -0700
commitf0b90de1127cfd7f88a667aff4553d624d6e451d (patch)
treef1d08770b909c164ddcc9bcf5945cf47caadfe41
parent1fcb0052e32fe8c260e83b2ece033e2ca2f30a92 (diff)
downloadperl-f0b90de1127cfd7f88a667aff4553d624d6e451d.tar.gz
perlapi.pod Enhancements
This is a patch to enhance perlapi.pod by providing Perl equivalents and clarifying documentation where appropriate.
-rw-r--r--av.c16
-rw-r--r--av.h2
-rw-r--r--cv.h7
-rw-r--r--perl.c12
4 files changed, 31 insertions, 6 deletions
diff --git a/av.c b/av.c
index 9dd4a76b29..e6b9d22767 100644
--- a/av.c
+++ b/av.c
@@ -275,11 +275,15 @@ Perl_av_fetch(pTHX_ register AV *av, I32 key, I32 lval)
Stores an SV in an array. The array index is specified as C<key>. The
return value will be NULL if the operation failed or if the value did not
need to be actually stored within the array (as in the case of tied
-arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
-that the caller is responsible for suitably incrementing the reference
+arrays). Otherwise, it can be dereferenced to get the C<SV*> that was stored
+there (= C<val>)).
+
+Note that the caller is responsible for suitably incrementing the reference
count of C<val> before the call, and decrementing it if the function
returned NULL.
+Approximate Perl equivalent: C<$myarray[$key] = $val;>.
+
See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
more information on how to use this function on tied arrays.
@@ -529,6 +533,8 @@ Perl_av_create_and_push(pTHX_ AV **const avp, SV *const val)
Pushes an SV onto the end of the array. The array will grow automatically
to accommodate the addition. This takes ownership of one reference count.
+Perl equivalent: C<push @myarray, $elem;>.
+
=cut
*/
@@ -558,6 +564,8 @@ Perl_av_push(pTHX_ register AV *av, SV *val)
Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
is empty.
+Perl equivalent: C<pop(@myarray);>
+
=cut
*/
@@ -617,6 +625,8 @@ Unshift the given number of C<undef> values onto the beginning of the
array. The array will grow automatically to accommodate the addition. You
must then use C<av_store> to assign values to these new elements.
+Perl equivalent: C<unshift @myarray, ( (undef) x $n );>
+
=cut
*/
@@ -679,6 +689,8 @@ Perl_av_unshift(pTHX_ register AV *av, register I32 num)
Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the
array is empty.
+Perl equivalent: C<shift(@myarray);>
+
=cut
*/
diff --git a/av.h b/av.h
index 5231c4d4ce..8b0e6563cb 100644
--- a/av.h
+++ b/av.h
@@ -83,6 +83,8 @@ Same as C<av_len()>. Deprecated, use C<av_len()> instead.
Creates a new AV. The reference count is set to 1.
+Perl equivalent: C<my @array;>.
+
=cut
*/
diff --git a/cv.h b/cv.h
index 6fdf5cbaf2..b2fe16d888 100644
--- a/cv.h
+++ b/cv.h
@@ -26,8 +26,13 @@ Null CV pointer.
=head1 CV Manipulation Functions
+This section documents functions to manipulate CVs which are code-values,
+or subroutines. For more information, see L<perlguts>.
+
=for apidoc Am|HV*|CvSTASH|CV* cv
-Returns the stash of the CV.
+Returns the stash of the CV. A stash is the symbol table hash, containing
+the package-scoped variables in the package where the subroutine was defined.
+For more information, see L<perlguts>.
=cut
*/
diff --git a/perl.c b/perl.c
index 4878f9ca8b..ef4b4623b0 100644
--- a/perl.c
+++ b/perl.c
@@ -2382,11 +2382,14 @@ Perl_get_sv(pTHX_ const char *name, I32 flags)
=for apidoc p||get_av
-Returns the AV of the specified Perl array. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
+Returns the AV of the specified Perl global or package array with the given
+name (so it won't work on lexical variables). C<flags> are passed
+to C<gv_fetchpv>. If C<GV_ADD> is set and the
Perl variable does not exist then it will be created. If C<flags> is zero
and the variable does not exist then NULL is returned.
+Perl equivalent: C<@{"$name"}>.
+
=cut
*/
@@ -2488,7 +2491,10 @@ Perl_get_cv(pTHX_ const char *name, I32 flags)
=for apidoc p||call_argv
-Performs a callback to the specified Perl sub. See L<perlcall>.
+Performs a callback to the specified named and package-scoped Perl subroutine
+with C<argv> (a NULL-terminated array of strings) as arguments. See L<perlcall>.
+
+Approximate Perl equivalent: C<&{"$sub_name"}(@$argv)>.
=cut
*/