3 * Copyright (c) 1991-2002, Larry Wall
5 * You may distribute under the terms of either the GNU General Public
6 * License or the Artistic License, as specified in the README file.
11 * "...for the Entwives desired order, and plenty, and peace (by which they
12 * meant that things should remain where they had set them)." --Treebeard
16 =head1 Array Manipulation Functions
24 Perl_av_reify(pTHX_ AV *av)
32 if (SvTIED_mg((SV*)av, PERL_MAGIC_tied) && ckWARN_d(WARN_DEBUGGING))
33 Perl_warner(aTHX_ packWARN(WARN_DEBUGGING), "av_reify called on tied array");
36 while (key > AvFILLp(av) + 1)
37 AvARRAY(av)[--key] = &PL_sv_undef;
39 sv = AvARRAY(av)[--key];
41 if (sv != &PL_sv_undef)
42 (void)SvREFCNT_inc(sv);
44 key = AvARRAY(av) - AvALLOC(av);
46 AvALLOC(av)[--key] = &PL_sv_undef;
54 Pre-extend an array. The C<key> is the index to which the array should be
61 Perl_av_extend(pTHX_ AV *av, I32 key)
64 if ((mg = SvTIED_mg((SV*)av, PERL_MAGIC_tied))) {
68 PUSHSTACKi(PERLSI_MAGIC);
71 PUSHs(SvTIED_obj((SV*)av, mg));
72 PUSHs(sv_2mortal(newSViv(key+1)));
74 call_method("EXTEND", G_SCALAR|G_DISCARD);
80 if (key > AvMAX(av)) {
85 if (AvALLOC(av) != AvARRAY(av)) {
86 ary = AvALLOC(av) + AvFILLp(av) + 1;
87 tmp = AvARRAY(av) - AvALLOC(av);
88 Move(AvARRAY(av), AvALLOC(av), AvFILLp(av)+1, SV*);
90 SvPVX(av) = (char*)AvALLOC(av);
93 ary[--tmp] = &PL_sv_undef;
96 if (key > AvMAX(av) - 10) {
97 newmax = key + AvMAX(av);
103 #if !defined(STRANGE_MALLOC) && !defined(MYMALLOC)
109 newmax = malloced_size((void*)AvALLOC(av))/sizeof(SV*) - 1;
114 newmax = key + AvMAX(av) / 5;
116 #if defined(STRANGE_MALLOC) || defined(MYMALLOC)
117 Renew(AvALLOC(av),newmax+1, SV*);
119 bytes = (newmax + 1) * sizeof(SV*);
120 #define MALLOC_OVERHEAD 16
121 itmp = MALLOC_OVERHEAD;
122 while ((MEM_SIZE)(itmp - MALLOC_OVERHEAD) < bytes)
124 itmp -= MALLOC_OVERHEAD;
126 assert(itmp > newmax);
128 assert(newmax >= AvMAX(av));
129 New(2,ary, newmax+1, SV*);
130 Copy(AvALLOC(av), ary, AvMAX(av)+1, SV*);
132 offer_nice_chunk(AvALLOC(av), (AvMAX(av)+1) * sizeof(SV*));
134 Safefree(AvALLOC(av));
140 ary = AvALLOC(av) + AvMAX(av) + 1;
141 tmp = newmax - AvMAX(av);
142 if (av == PL_curstack) { /* Oops, grew stack (via av_store()?) */
143 PL_stack_sp = AvALLOC(av) + (PL_stack_sp - PL_stack_base);
144 PL_stack_base = AvALLOC(av);
145 PL_stack_max = PL_stack_base + newmax;
149 newmax = key < 3 ? 3 : key;
150 New(2,AvALLOC(av), newmax+1, SV*);
151 ary = AvALLOC(av) + 1;
153 AvALLOC(av)[0] = &PL_sv_undef; /* For the stacks */
157 ary[--tmp] = &PL_sv_undef;
160 SvPVX(av) = (char*)AvALLOC(av);
169 Returns the SV at the specified index in the array. The C<key> is the
170 index. If C<lval> is set then the fetch will be part of a store. Check
171 that the return value is non-null before dereferencing it to a C<SV*>.
173 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
174 more information on how to use this function on tied arrays.
180 Perl_av_fetch(pTHX_ register AV *av, I32 key, I32 lval)
187 if (SvRMAGICAL(av)) {
188 MAGIC *tied_magic = mg_find((SV*)av, PERL_MAGIC_tied);
189 if (tied_magic || mg_find((SV*)av, PERL_MAGIC_regdata)) {
190 U32 adjust_index = 1;
192 if (tied_magic && key < 0) {
193 /* Handle negative array indices 20020222 MJD */
194 SV **negative_indices_glob =
195 hv_fetch(SvSTASH(SvRV(SvTIED_obj((SV *)av,
197 NEGATIVE_INDICES_VAR, 16, 0);
199 if (negative_indices_glob
200 && SvTRUE(GvSV(*negative_indices_glob)))
204 if (key < 0 && adjust_index) {
205 key += AvFILL(av) + 1;
211 mg_copy((SV*)av, sv, 0, key);
213 return &PL_av_fetch_sv;
218 key += AvFILL(av) + 1;
223 if (key > AvFILLp(av)) {
227 return av_store(av,key,sv);
229 if (AvARRAY(av)[key] == &PL_sv_undef) {
233 return av_store(av,key,sv);
238 && (!AvARRAY(av)[key] /* eg. @_ could have freed elts */
239 || SvTYPE(AvARRAY(av)[key]) == SVTYPEMASK)) {
240 AvARRAY(av)[key] = &PL_sv_undef; /* 1/2 reify */
243 return &AvARRAY(av)[key];
249 Stores an SV in an array. The array index is specified as C<key>. The
250 return value will be NULL if the operation failed or if the value did not
251 need to be actually stored within the array (as in the case of tied
252 arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
253 that the caller is responsible for suitably incrementing the reference
254 count of C<val> before the call, and decrementing it if the function
257 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
258 more information on how to use this function on tied arrays.
264 Perl_av_store(pTHX_ register AV *av, I32 key, SV *val)
273 if (SvRMAGICAL(av)) {
274 MAGIC *tied_magic = mg_find((SV*)av, PERL_MAGIC_tied);
276 /* Handle negative array indices 20020222 MJD */
278 unsigned adjust_index = 1;
279 SV **negative_indices_glob =
280 hv_fetch(SvSTASH(SvRV(SvTIED_obj((SV *)av,
282 NEGATIVE_INDICES_VAR, 16, 0);
283 if (negative_indices_glob
284 && SvTRUE(GvSV(*negative_indices_glob)))
287 key += AvFILL(av) + 1;
292 if (val != &PL_sv_undef) {
293 mg_copy((SV*)av, val, 0, key);
301 key += AvFILL(av) + 1;
306 if (SvREADONLY(av) && key >= AvFILL(av))
307 Perl_croak(aTHX_ PL_no_modify);
309 if (!AvREAL(av) && AvREIFY(av))
314 if (AvFILLp(av) < key) {
316 if (av == PL_curstack && key > PL_stack_sp - PL_stack_base)
317 PL_stack_sp = PL_stack_base + key; /* XPUSH in disguise */
319 ary[++AvFILLp(av)] = &PL_sv_undef;
320 while (AvFILLp(av) < key);
325 SvREFCNT_dec(ary[key]);
327 if (SvSMAGICAL(av)) {
328 if (val != &PL_sv_undef) {
329 MAGIC* mg = SvMAGIC(av);
330 sv_magic(val, (SV*)av, toLOWER(mg->mg_type), 0, key);
340 Creates a new AV. The reference count is set to 1.
350 av = (AV*)NEWSV(3,0);
351 sv_upgrade((SV *)av, SVt_PVAV);
355 AvMAX(av) = AvFILLp(av) = -1;
362 Creates a new AV and populates it with a list of SVs. The SVs are copied
363 into the array, so they may be freed after the call to av_make. The new AV
364 will have a reference count of 1.
370 Perl_av_make(pTHX_ register I32 size, register SV **strp)
376 av = (AV*)NEWSV(8,0);
377 sv_upgrade((SV *) av,SVt_PVAV);
378 AvFLAGS(av) = AVf_REAL;
379 if (size) { /* `defined' was returning undef for size==0 anyway. */
382 SvPVX(av) = (char*)ary;
383 AvFILLp(av) = size - 1;
384 AvMAX(av) = size - 1;
385 for (i = 0; i < size; i++) {
388 sv_setsv(ary[i], *strp);
396 Perl_av_fake(pTHX_ register I32 size, register SV **strp)
401 av = (AV*)NEWSV(9,0);
402 sv_upgrade((SV *)av, SVt_PVAV);
403 New(4,ary,size+1,SV*);
405 Copy(strp,ary,size,SV*);
406 AvFLAGS(av) = AVf_REIFY;
407 SvPVX(av) = (char*)ary;
408 AvFILLp(av) = size - 1;
409 AvMAX(av) = size - 1;
421 Clears an array, making it empty. Does not free the memory used by the
428 Perl_av_clear(pTHX_ register AV *av)
434 if (SvREFCNT(av) == 0 && ckWARN_d(WARN_DEBUGGING)) {
435 Perl_warner(aTHX_ packWARN(WARN_DEBUGGING), "Attempt to clear deleted array");
443 Perl_croak(aTHX_ PL_no_modify);
445 /* Give any tie a chance to cleanup first */
454 key = AvFILLp(av) + 1;
456 SvREFCNT_dec(ary[--key]);
457 ary[key] = &PL_sv_undef;
460 if ((key = AvARRAY(av) - AvALLOC(av))) {
462 SvPVX(av) = (char*)AvALLOC(av);
471 Undefines the array. Frees the memory used by the array itself.
477 Perl_av_undef(pTHX_ register AV *av)
485 /* Give any tie a chance to cleanup first */
486 if (SvTIED_mg((SV*)av, PERL_MAGIC_tied))
487 av_fill(av, -1); /* mg_clear() ? */
490 key = AvFILLp(av) + 1;
492 SvREFCNT_dec(AvARRAY(av)[--key]);
494 Safefree(AvALLOC(av));
497 AvMAX(av) = AvFILLp(av) = -1;
499 SvREFCNT_dec(AvARYLEN(av));
507 Pushes an SV onto the end of the array. The array will grow automatically
508 to accommodate the addition.
514 Perl_av_push(pTHX_ register AV *av, SV *val)
520 Perl_croak(aTHX_ PL_no_modify);
522 if ((mg = SvTIED_mg((SV*)av, PERL_MAGIC_tied))) {
524 PUSHSTACKi(PERLSI_MAGIC);
527 PUSHs(SvTIED_obj((SV*)av, mg));
531 call_method("PUSH", G_SCALAR|G_DISCARD);
536 av_store(av,AvFILLp(av)+1,val);
542 Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
549 Perl_av_pop(pTHX_ register AV *av)
557 Perl_croak(aTHX_ PL_no_modify);
558 if ((mg = SvTIED_mg((SV*)av, PERL_MAGIC_tied))) {
560 PUSHSTACKi(PERLSI_MAGIC);
562 XPUSHs(SvTIED_obj((SV*)av, mg));
565 if (call_method("POP", G_SCALAR)) {
566 retval = newSVsv(*PL_stack_sp--);
568 retval = &PL_sv_undef;
576 retval = AvARRAY(av)[AvFILLp(av)];
577 AvARRAY(av)[AvFILLp(av)--] = &PL_sv_undef;
584 =for apidoc av_unshift
586 Unshift the given number of C<undef> values onto the beginning of the
587 array. The array will grow automatically to accommodate the addition. You
588 must then use C<av_store> to assign values to these new elements.
594 Perl_av_unshift(pTHX_ register AV *av, register I32 num)
604 Perl_croak(aTHX_ PL_no_modify);
606 if ((mg = SvTIED_mg((SV*)av, PERL_MAGIC_tied))) {
608 PUSHSTACKi(PERLSI_MAGIC);
611 PUSHs(SvTIED_obj((SV*)av, mg));
617 call_method("UNSHIFT", G_SCALAR|G_DISCARD);
625 if (!AvREAL(av) && AvREIFY(av))
627 i = AvARRAY(av) - AvALLOC(av);
635 SvPVX(av) = (char*)(AvARRAY(av) - i);
639 /* Create extra elements */
640 slide = i > 0 ? i : 0;
642 av_extend(av, i + num);
645 Move(ary, ary + num, i + 1, SV*);
647 ary[--num] = &PL_sv_undef;
649 /* Make extra elements into a buffer */
651 AvFILLp(av) -= slide;
652 SvPVX(av) = (char*)(AvARRAY(av) + slide);
659 Shifts an SV off the beginning of the array.
665 Perl_av_shift(pTHX_ register AV *av)
673 Perl_croak(aTHX_ PL_no_modify);
674 if ((mg = SvTIED_mg((SV*)av, PERL_MAGIC_tied))) {
676 PUSHSTACKi(PERLSI_MAGIC);
678 XPUSHs(SvTIED_obj((SV*)av, mg));
681 if (call_method("SHIFT", G_SCALAR)) {
682 retval = newSVsv(*PL_stack_sp--);
684 retval = &PL_sv_undef;
692 retval = *AvARRAY(av);
694 *AvARRAY(av) = &PL_sv_undef;
695 SvPVX(av) = (char*)(AvARRAY(av) + 1);
706 Returns the highest index in the array. Returns -1 if the array is
713 Perl_av_len(pTHX_ register AV *av)
721 Ensure than an array has a given number of elements, equivalent to
722 Perl's C<$#array = $fill;>.
727 Perl_av_fill(pTHX_ register AV *av, I32 fill)
731 Perl_croak(aTHX_ "panic: null array");
734 if ((mg = SvTIED_mg((SV*)av, PERL_MAGIC_tied))) {
738 PUSHSTACKi(PERLSI_MAGIC);
741 PUSHs(SvTIED_obj((SV*)av, mg));
742 PUSHs(sv_2mortal(newSViv(fill+1)));
744 call_method("STORESIZE", G_SCALAR|G_DISCARD);
750 if (fill <= AvMAX(av)) {
751 I32 key = AvFILLp(av);
752 SV** ary = AvARRAY(av);
756 SvREFCNT_dec(ary[key]);
757 ary[key--] = &PL_sv_undef;
762 ary[++key] = &PL_sv_undef;
770 (void)av_store(av,fill,&PL_sv_undef);
774 =for apidoc av_delete
776 Deletes the element indexed by C<key> from the array. Returns the
777 deleted element. C<flags> is currently ignored.
782 Perl_av_delete(pTHX_ AV *av, I32 key, I32 flags)
789 Perl_croak(aTHX_ PL_no_modify);
791 if (SvRMAGICAL(av)) {
792 MAGIC *tied_magic = mg_find((SV*)av, PERL_MAGIC_tied);
794 if ((tied_magic || mg_find((SV*)av, PERL_MAGIC_regdata))) {
795 /* Handle negative array indices 20020222 MJD */
797 unsigned adjust_index = 1;
799 SV **negative_indices_glob =
800 hv_fetch(SvSTASH(SvRV(SvTIED_obj((SV *)av,
802 NEGATIVE_INDICES_VAR, 16, 0);
803 if (negative_indices_glob
804 && SvTRUE(GvSV(*negative_indices_glob)))
808 key += AvFILL(av) + 1;
813 svp = av_fetch(av, key, TRUE);
817 if (mg_find(sv, PERL_MAGIC_tiedelem)) {
818 sv_unmagic(sv, PERL_MAGIC_tiedelem); /* No longer an element */
827 key += AvFILL(av) + 1;
832 if (key > AvFILLp(av))
835 sv = AvARRAY(av)[key];
836 if (key == AvFILLp(av)) {
837 AvARRAY(av)[key] = &PL_sv_undef;
840 } while (--key >= 0 && AvARRAY(av)[key] == &PL_sv_undef);
843 AvARRAY(av)[key] = &PL_sv_undef;
847 if (flags & G_DISCARD) {
855 =for apidoc av_exists
857 Returns true if the element indexed by C<key> has been initialized.
859 This relies on the fact that uninitialized array elements are set to
865 Perl_av_exists(pTHX_ AV *av, I32 key)
871 if (SvRMAGICAL(av)) {
872 MAGIC *tied_magic = mg_find((SV*)av, PERL_MAGIC_tied);
873 if (tied_magic || mg_find((SV*)av, PERL_MAGIC_regdata)) {
874 SV *sv = sv_newmortal();
876 /* Handle negative array indices 20020222 MJD */
878 unsigned adjust_index = 1;
880 SV **negative_indices_glob =
881 hv_fetch(SvSTASH(SvRV(SvTIED_obj((SV *)av,
883 NEGATIVE_INDICES_VAR, 16, 0);
884 if (negative_indices_glob
885 && SvTRUE(GvSV(*negative_indices_glob)))
889 key += AvFILL(av) + 1;
895 mg_copy((SV*)av, sv, 0, key);
896 mg = mg_find(sv, PERL_MAGIC_tiedelem);
898 magic_existspack(sv, mg);
899 return (bool)SvTRUE(sv);
906 key += AvFILL(av) + 1;
911 if (key <= AvFILLp(av) && AvARRAY(av)[key] != &PL_sv_undef