NAME

       Class::Method::array - Create methods for handling an array value.

SYNOPSIS

         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

DESCRIPTION

       Creates methods to handle array values in an object.  For a component named "x", by default creates
       methods "x", "x_reset", "x_clear", "x_isset", "x_count", "x_index", "x_push", "x_pop", "x_unshift",
       "x_shift", "x_splice".

       Methods available are:

       "*"

       Created by default. This method returns the list of values stored in the slot.  If any arguments are
       provided to this method, they replace 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.

       If a default value is in force, then that value will be auto-vivified (and therefore set) for each
       otherwise unset (not not defined) value up to the array max (so new items will not be appended)

       *_reset

       Created by default. 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 *_isset
       will return false, and "*" will return undef.  If "-default" is in effect, then the component will be set
       to the default value, and *_isset will return true.  If "-default_ctor" is in effect, then the default
       subr will be invoked, and its return value used to set the value of the component, and *_isset will
       return true.

       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 *_isset(n) will return false for
       appropriate n, except where "-default" or "-default_ctor" 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).

       *_clear

         package MyClass;
         use Class::MethodMaker
           [ scalar => [{'*_clear' => '*_clear'}, 'a'],
             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

       Created on request.  A shorthand for setting to undef.  Note that the component will be set to undef, not
       reset, so *_isset will return true.

       *_isset

       Created by default. 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>.

       If a default value is in effect, then <*_isset> will always return true.

       *_isset() tests the component as a whole.  *_isset(a) tests the element indexed by a.  "*_isset(a,b)"
       tests the elements indexed by a, b, and returns the logical conjunction (and) of the tests.

       *_count

       Created by default. Returns the number of elements in this component.  This is not affected by presence
       (or lack) of a "default" (or "default_ctor").  Returns "undef" if whole component not set (as per
       *_isset).

       *_index

       Created by default. Takes a list of indices, returns a list of the corresponding values.

       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).

       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 x_index(2)) where x_index(1) was previously
       unset might cause x_index(1) to be set spuriously.  This is fixed in 5.8.0.

       *_push

       Created by default. Push item(s) onto the end of the list.  No return value.

       *_pop

       Created by default. 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).

       *_unshift

       Created by default. Push item(s) onto the start of the list.  No return value.

       *_shift

       Created by default. 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.

       *_splice

       Created by default. 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.

       *_get

       Created on request.  Retrieves the value of the component without setting (ignores any arguments passed).

       *_set

         @n = $x->a; # (1,2,3)
         $x->a_set(1=>4,3=>7);
         @n = $x->a; # (1,4,3,7)

       Created by default. Takes a list, treated as pairs of index => value; each given index is set to the
       corresponding value.  No return.

       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:

         $x->a_set(1=>4,3=>7);
         $x->a_set([1,3],[4,7]);

perl v5.38.2                                       2024-03-31                     Class::MethodMaker::array(3pm)