diff options
| author | David Mitchell <davem@iabyn.com> | 2016-09-27 09:51:45 +0100 |
|---|---|---|
| committer | David Mitchell <davem@iabyn.com> | 2016-09-27 11:19:00 +0100 |
| commit | 17b0bd7713345613d9d19e31a82f42fc48ddcfc5 (patch) | |
| tree | 9b9518f46b95e8c86e99ec64a7586c1b84304ca8 /av.c | |
| parent | 8944d2e9909e3336200cbf2ead2a819cc78f4986 (diff) | |
| download | perl-17b0bd7713345613d9d19e31a82f42fc48ddcfc5.tar.gz | |
fixup some AV API pod descriptions.
In particular:
* improve some of the "perl equivalent" entries; for example
av_store() is *not* like $myarray[$key] = $val, since it replaces the
stored SV with a different SV, rather than just updating the current
SV's value.
* Also change the "perl equivalent" variable names to match the function
parameter names, e.g. $key rather than $idx.
* Don't use 'delete' as a perl equivalent, since delete is discouraged on
arrays.
* You don't *have* to use av_store() to change undef values inserted by
av_unshift; e.g. you could do av_fetch() then modify the returned
undef SV; so just delete that sentence
Diffstat (limited to 'av.c')
| -rw-r--r-- | av.c | 23 |
1 files changed, 12 insertions, 11 deletions
@@ -210,7 +210,7 @@ value is non-null before dereferencing it to a C<SV*>. See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more information on how to use this function on tied arrays. -The rough perl equivalent is C<$myarray[$idx]>. +The rough perl equivalent is C<$myarray[$key]>. =cut */ @@ -305,7 +305,7 @@ 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 C<NULL>. -Approximate Perl equivalent: C<$myarray[$key] = $val;>. +Approximate Perl equivalent: C<splice(@myarray, $key, 1, $val)>. See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more information on how to use this function on tied arrays. @@ -573,7 +573,7 @@ Perl_av_create_and_push(pTHX_ AV **const avp, SV *const val) Pushes an SV (transferring control of one reference count) onto the end of the array. The array will grow automatically to accommodate the addition. -Perl equivalent: C<push @myarray, $elem;>. +Perl equivalent: C<push @myarray, $val;>. =cut */ @@ -661,10 +661,9 @@ Perl_av_create_and_unshift_one(pTHX_ AV **const avp, SV *const val) =for apidoc av_unshift 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. +array. The array will grow automatically to accommodate the addition. -Perl equivalent: S<C<unshift @myarray, ( (undef) x $n );>> +Perl equivalent: S<C<unshift @myarray, ((undef) x $num);>> =cut */ @@ -848,11 +847,13 @@ Perl_av_fill(pTHX_ AV *av, SSize_t fill) /* =for apidoc av_delete -Deletes the element indexed by C<key> from the array, makes the element mortal, -and returns it. If C<flags> equals C<G_DISCARD>, the element is freed and null -is returned. Perl equivalent: S<C<my $elem = delete($myarray[$idx]);>> for the -non-C<G_DISCARD> version and a void-context S<C<delete($myarray[$idx]);>> for the -C<G_DISCARD> version. +Deletes the element indexed by C<key> from the array, makes the element +mortal, and returns it. If C<flags> equals C<G_DISCARD>, the element is +freed and NULL is returned. NULL is also returned if C<key> is out of +range. + +Perl equivalent: S<C<splice(@myarray, $key, 1, undef)>> (with the +C<splice> in void context if C<G_DISCARD> is present). =cut */ |