1Class::MethodMaker::arrUasye(r3)Contributed Perl DocumenCtlaatsiso:n:MethodMaker::array(3)
2
3
4

NAME

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

SYNOPSIS

9         use Class::MethodMaker
10           [ array => [qw/ x /] ];
11
12         $instance->x;                # empty
13         $instance->x(1, 1, 2, 3, 5, 8);
14         $instance->x_count == 6;     # true
15         $instance->x = (13, 21, 34);
16         $instance->x_index(1) == 21; # true
17

DESCRIPTION

19       Creates methods to handle array values in an object.  For a component
20       named "x", by default creates methods "x", "x_reset", "x_clear",
21       "x_isset", "x_count", "x_index", "x_push", "x_pop", "x_unshift",
22       "x_shift", "x_splice".
23
24       Methods available are:
25
26       "*"
27
28       Created by default. This method returns the list of values stored in
29       the slot.  If any arguments are provided to this method, they replace
30       the current list contents.  In an array context it returns the values
31       as an array and in a scalar context as a reference to an array.  Note
32       that this reference is no longer a direct reference to the storage, in
33       contrast to Class::MethodMaker v1.  This is to protect encapsulation.
34       See x_ref if you need that functionality (and are prepared to take the
35       associated risk.)  This function no longer auto-expands arrayrefs input
36       as arguments, since that makes it awkward to set individual values to
37       arrayrefs.  See x_setref for that functionality.
38
39       If a default value is in force, then that value will be auto-vivified
40       (and therefore set) for each otherwise unset (not not defined) value up
41       to the array max (so new items will not be appended)
42
43       *_reset
44
45       Created by default. Called without an argument, this resets the
46       component as a whole; deleting any associated storage, and returning
47       the component to its default state.  Normally, this means that *_isset
48       will return false, and "*" will return undef.  If "-default" is in
49       effect, then the component will be set to the default value, and
50       *_isset will return true.  If "-default_ctor" is in effect, then the
51       default subr will be invoked, and its return value used to set the
52       value of the component, and *_isset will return true.
53
54       If called with arguments, these arguments are treated as indexes into
55       the component, and the individual elements thus referenced are reset
56       (their storage deleted, so that *_isset(n) will return false for
57       appropriate n, except where "-default" or "-default_ctor" are in force,
58       as above).  As with perl arrays, resetting the highest set value
59       implicitly decreases the count (but x_reset(n) never unsets the
60       aggregate itself, even if all the elements are not set).
61
62       *_clear
63
64         package MyClass;
65         use Class::MethodMaker
66           [ scalar => [{'*_clear' => '*_clear'}, 'a'],
67             new    => new, ];
68
69         package main;
70         my $m = MyClass->new;
71         $m->a(5);
72         $a = $m->a;       # 5
73         $x = $m->a_isset; # true
74         $m->a_clear;
75         $a = $m->a;       # *undef*
76         $x = $m->a_isset; # true
77
78       Created on request.  A shorthand for setting to undef.  Note that the
79       component will be set to undef, not reset, so *_isset will return true.
80
81       *_isset
82
83       Created by default. Whether the component is currently set.  This is
84       different from being defined; initially, the component is not set (and
85       if read, will return undef); it can be set to undef (which is a set
86       value, which also returns undef).  Having been set, the only way to
87       unset the component is with <*_reset>.
88
89       If a default value is in effect, then <*_isset> will always return
90       true.
91
92       "*_isset()" tests the component as a whole.  *_isset(a) tests the
93       element indexed by a.  "*_isset(a,b)" tests the elements indexed by a,
94       b, and returns the logical conjunction (and) of the tests.
95
96       *_count
97
98       Created by default. Returns the number of elements in this component.
99       This is not affected by presence (or lack) of a "default" (or
100       "default_ctor").  Returns "undef" if whole component not set (as per
101       *_isset).
102
103       *_index
104
105       Created by default. Takes a list of indices, returns a list of the
106       corresponding values.
107
108       If a default (or a default ctor) is in force, then a lookup by index
109       will vivify & set to the default the respective elements (and therefore
110       the aggregate data-structure also, if it's not already).
111
112       Beware of a bug in perl 5.6.1 that will sometimes invent values in
113       previously unset slots of arrays that previously contained a value.
114       So, vivifying a value (e.g. by x_index(2)) where x_index(1) was
115       previously unset might cause x_index(1) to be set spuriously.  This is
116       fixed in 5.8.0.
117
118       *_push
119
120       Created by default. Push item(s) onto the end of the list.  No return
121       value.
122
123       *_pop
124
125       Created by default. Given a number, pops that many items off the end of
126       the list, and returns them (as a ref in scalar context, as a list in
127       list context).  Without an arg, always returns a single element.  Given
128       a number, returns them in array order (not in reverse order as multiple
129       pops would).
130
131       *_unshift
132
133       Created by default. Push item(s) onto the start of the list.  No return
134       value.
135
136       *_shift
137
138       Created by default. Given a number, shifts that many items off the
139       start of the list, and returns them (as a ref in scalar context, as a
140       list in list context).  Without an arg, always returns a single
141       element.  Given a number, returns them in array order.
142
143       *_splice
144
145       Created by default. Arguments as for perldoc perlfunc splice.  Returns
146       an arrayref in scalar context (even if a single item is spliced), and a
147       list in list context.
148
149       *_get
150
151       Created on request.  Retrieves the value of the component without
152       setting (ignores any arguments passed).
153
154       *_set
155
156         @n = $x->a; # (1,2,3)
157         $x->a_set(1=>4,3=>7);
158         @n = $x->a; # (1,4,3,7)
159
160       Created by default. Takes a list, treated as pairs of index => value;
161       each given index is set to the corresponding value.  No return.
162
163       If two arguments are given, of which the first is an arrayref, then it
164       is treated as a list of indices of which the second argument (which
165       must also be an arrayref) are the corresponding values.  Thus the
166       following two commands are equivalent:
167
168         $x->a_set(1=>4,3=>7);
169         $x->a_set([1,3],[4,7]);
170
171
172
173perl v5.32.1                      2021-01-27      Class::MethodMaker::array(3)
Impressum