+
+Note that there are both real and fake AVs; see the beginning of this file and
+'av.c'
+
+=for apidoc newAV
+=for apidoc_item newAV_alloc_x
+=for apidoc_item newAV_alloc_xz
+
+These all create a new AV, setting the reference count to 1. If you also know
+the initial elements of the array with, see L</C<av_make>>.
+
+As background, an array consists of three things:
+
+=over
+
+=item 1.
+
+A data structure containing information about the array as a whole, such as its
+size and reference count.
+
+=item 2.
+
+A C language array of pointers to the individual elements. These are treated
+as pointers to SVs, so all must be castable to SV*.
+
+=item 3.
+
+The individual elements themselves. These could be, for instance, SVs and/or
+AVs and/or HVs, etc.
+
+=back
+
+An empty array need only have the first data structure, and all these functions
+create that. They differ in what else they do, as follows:
+
+=over
+
+=item C<newAV> form
+
+=for comment
+'form' above and below is because otherwise have two =items with the same name,
+can't link to them.
+
+This does nothing beyond creating the whole-array data structure.
+The Perl equivalent is approximately S<C<my @array;>>
+
+This is useful when the minimum size of the array could be zero (perhaps there
+are likely code paths that will entirely skip using it).
+
+If the array does get used, the pointers data structure will need to be
+allocated at that time. This will end up being done by L</av_extend>>,
+either explicitly:
+
+ av_extend(av, len);
+
+or implicitly when the first element is stored:
+
+ (void)av_store(av, 0, sv);
+
+Unused array elements are typically initialized by C<av_extend>.
+
+=item C<newAV_alloc_x> form
+
+This effectively does a C<newAV> followed by also allocating (uninitialized)
+space for the pointers array. This is used when you know ahead of time the
+likely minimum size of the array. It is more efficient to do this than doing a
+plain C<newAV> followed by an C<av_extend>.
+
+Of course the array can be extended later should it become necessary.
+
+C<size> must be at least 1.
+
+=item C<newAV_alloc_xz> form
+
+This is C<newAV_alloc_x>, but initializes each pointer in it to NULL. This
+gives added safety to guard against them being read before being set.
+
+C<size> must be at least 1.
+
+=back
+
+The following examples all result in an array that can fit four elements
+(indexes 0 .. 3):
+
+ AV *av = newAV();
+ av_extend(av, 3);
+
+ AV *av = newAV_alloc_x(4);
+
+ AV *av = newAV_alloc_xz(4);
+
+In contrast, the following examples allocate an array that is only guaranteed
+to fit one element without extending:
+
+ AV *av = newAV_alloc_x(1);
+ AV *av = newAV_alloc_xz(1);
+
+=cut
+
+*/
+
+#define newAV() MUTABLE_AV(newSV_type(SVt_PVAV))
+#define newAV_alloc_x(size) av_new_alloc(size,0)
+#define newAV_alloc_xz(size) av_new_alloc(size,1)
+
+/*
+ * ex: set ts=8 sts=4 sw=4 et: