.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Class::MethodMaker::array 3pm"
.TH Class::MethodMaker::array 3pm "2014-08-15" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::Method::array \- Create methods for handling an array value.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Class::MethodMaker
\&    [ array => [qw/ x /] ];
\&
\&  $instance\->x;                # empty
\&  $instance\->x(1, 1, 2, 3, 5, 8);
\&  $instance\->x_count == 6;     # true
\&  $instance\->x = (13, 21, 34);
\&  $instance\->x_index(1) == 21; # true
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Creates methods to handle array values in an object.  For a component named
\&\f(CW\*(C`x\*(C'\fR, by default creates methods \f(CW\*(C`x\*(C'\fR, \f(CW\*(C`x_reset\*(C'\fR, \f(CW\*(C`x_clear\*(C'\fR, \f(CW\*(C`x_isset\*(C'\fR,
\&\f(CW\*(C`x_count\*(C'\fR, \f(CW\*(C`x_index\*(C'\fR, \f(CW\*(C`x_push\*(C'\fR, \f(CW\*(C`x_pop\*(C'\fR, \f(CW\*(C`x_unshift\*(C'\fR, \f(CW\*(C`x_shift\*(C'\fR,
\&\f(CW\*(C`x_splice\*(C'\fR.
.PP
Methods available are:
.PP
\fI\f(CI\*(C`*\*(C'\fI\fR
.IX Subsection "*"
.PP
\&\fICreated by default.\fR This method returns the list of values stored in the
slot.  If any arguments are provided to this method, they \fBreplace\fR the
current list contents.  In an array context it returns the values as an array
and in a scalar context as a reference to an array.  Note that this reference
is no longer a direct reference to the storage, in contrast to
Class::MethodMaker v1.  This is to protect encapsulation.  See x_ref if you
need that functionality (and are prepared to take the associated risk.)  This
function no longer auto-expands arrayrefs input as arguments, since that makes
it awkward to set individual values to arrayrefs.  See x_setref for that
functionality.
.PP
If a default value is in force, then that value will be auto-vivified (and
therefore set) for each otherwise \fIunset\fR (not \fInot defined\fR) value up to
the array max (so new items will not be appended)
.PP
\fI\f(CI*_reset\fI\fR
.IX Subsection "*_reset"
.PP
\&\fICreated by default.\fR Called without an argument, this resets the component
as a whole; deleting any associated storage, and returning the component to
its default state.  Normally, this means that \f(CW*_isset\fR will return false,
and \f(CW\*(C`*\*(C'\fR will return undef.  If \f(CW\*(C`\-default\*(C'\fR is in effect, then the component
will be set to the default value, and \f(CW*_isset\fR will return true.  If
\&\f(CW\*(C`\-default_ctor\*(C'\fR is in effect, then the default subr will be invoked, and its
return value used to set the value of the component, and \f(CW*_isset\fR will
return true.
.PP
If called with arguments, these arguments are treated as indexes into the
component, and the individual elements thus referenced are reset (their
storage deleted, so that \f(CW*_isset(n)\fR will return false for appropriate \fIn\fR,
except where \f(CW\*(C`\-default\*(C'\fR or \f(CW\*(C`\-default_ctor\*(C'\fR are in force, as above).  As with
perl arrays, resetting the highest set value implicitly decreases the count
(but x_reset(n) never unsets the aggregate itself, even if all the elements
are not set).
.PP
\fI\f(CI*_clear\fI\fR
.IX Subsection "*_clear"
.PP
.Vb 4
\&  package MyClass;
\&  use Class::MethodMaker
\&    [ scalar => [{\*(Aq*_clear\*(Aq => \*(Aq*_clear\*(Aq}, \*(Aqa\*(Aq],
\&      new    => new, ];
\&
\&  package main;
\&  my $m = MyClass\->new;
\&  $m\->a(5);
\&  $a = $m\->a;       # 5
\&  $x = $m\->a_isset; # true
\&  $m\->a_clear;
\&  $a = $m\->a;       # *undef*
\&  $x = $m\->a_isset; # true
.Ve
.PP
\&\fICreated on request\fR.  A shorthand for setting to undef.  Note that the
component will be set to undef, not reset, so \f(CW*_isset\fR will return true.
.PP
\fI\f(CI*_isset\fI\fR
.IX Subsection "*_isset"
.PP
\&\fICreated by default.\fR Whether the component is currently set.  This is
different from being defined; initially, the component is not set (and if
read, will return undef); it can be set to undef (which is a set value, which
also returns undef).  Having been set, the only way to unset the component is
with <*_reset>.
.PP
If a default value is in effect, then <*_isset> will always return true.
.PP
\&\f(CW\*(C`*_isset()\*(C'\fR tests the component as a whole.  \f(CW*_isset(a)\fR tests the element
indexed by \fIa\fR.  \f(CW\*(C`*_isset(a,b)\*(C'\fR tests the elements indexed by \fIa\fR, \fIb\fR,
and returns the logical conjunction (\fIand\fR) of the tests.
.PP
\fI\f(CI*_count\fI\fR
.IX Subsection "*_count"
.PP
\&\fICreated by default.\fR Returns the number of elements in this component.  This
is not affected by presence (or lack) of a \f(CW\*(C`default\*(C'\fR (or \f(CW\*(C`default_ctor\*(C'\fR).
Returns \f(CW\*(C`undef\*(C'\fR if whole component not set (as per \f(CW*_isset\fR).
.PP
\fI\f(CI*_index\fI\fR
.IX Subsection "*_index"
.PP
\&\fICreated by default.\fR Takes a list of indices, returns a list of the
corresponding values.
.PP
If a default (or a default ctor) is in force, then a lookup by
index will vivify & set to the default the respective elements (and
therefore the aggregate data-structure also, if it's not already).
.PP
Beware of a bug in perl 5.6.1 that will sometimes invent values in
previously unset slots of arrays that previously contained a value.
So, vivifying a value (e.g. by \fIx_index\fR\|(2)) where \fIx_index\fR\|(1) was
previously unset might cause \fIx_index\fR\|(1) to be set spuriously.  This
is fixed in 5.8.0.
.PP
\fI\f(CI*_push\fI\fR
.IX Subsection "*_push"
.PP
\&\fICreated by default.\fR Push item(s) onto the end of the list.  No return
value.
.PP
\fI\f(CI*_pop\fI\fR
.IX Subsection "*_pop"
.PP
\&\fICreated by default.\fR Given a number, pops that many items off the end of the
list, and returns them (as a ref in scalar context, as a list in list
context).  Without an arg, always returns a single element.  Given a number,
returns them in array order (not in reverse order as multiple pops would).
.PP
\fI\f(CI*_unshift\fI\fR
.IX Subsection "*_unshift"
.PP
\&\fICreated by default.\fR Push item(s) onto the start of the list.  No return
value.
.PP
\fI\f(CI*_shift\fI\fR
.IX Subsection "*_shift"
.PP
\&\fICreated by default.\fR Given a number, shifts that many items off the start of
the list, and returns them (as a ref in scalar context, as a list in list
context).  Without an arg, always returns a single element.  Given a number,
returns them in array order.
.PP
\fI\f(CI*_splice\fI\fR
.IX Subsection "*_splice"
.PP
\&\fICreated by default.\fR Arguments as for perldoc perlfunc splice.
Returns an arrayref in scalar context (even if a single item is spliced), and
a list in list context.
.PP
\fI\f(CI*_get\fI\fR
.IX Subsection "*_get"
.PP
\&\fICreated on request\fR.  Retrieves the value of the component without setting
(ignores any arguments passed).
.PP
\fI\f(CI*_set\fI\fR
.IX Subsection "*_set"
.PP
.Vb 3
\&  @n = $x\->a; # (1,2,3)
\&  $x\->a_set(1=>4,3=>7);
\&  @n = $x\->a; # (1,4,3,7)
.Ve
.PP
\&\fICreated by default.\fR Takes a list, treated as pairs of index => value; each
given index is set to the corresponding value.  No return.
.PP
If two arguments are given, of which the first is an arrayref, then it is
treated as a list of indices of which the second argument (which must also be
an arrayref) are the corresponding values.  Thus the following two commands
are equivalent:
.PP
.Vb 2
\&  $x\->a_set(1=>4,3=>7);
\&  $x\->a_set([1,3],[4,7]);
.Ve