Class::MakeMethods::Utility::ArraySplicer(3pm)

1MakeMethods::Utility::AUrsrearySCpolnitcreirb(u3t)ed PerMlakDeoMceutmheondtsa:t:iUotnility::ArraySplicer(3)
2
3
4

NAME

6       Class::MakeMethods::Utility::ArraySplicer - Common array ops
7

SYNOPSIS

9         use Class::MakeMethods::Utility::ArraySplicer;
10
11         # Get one or more values
12         $value = array_splicer( $array_ref, $index );
13         @values = array_splicer( $array_ref, $index_array_ref );
14
15         # Set one or more values
16         array_splicer( $array_ref, $index => $new_value, ... );
17
18         # Splice selected values in or out
19         array_splicer( $array_ref, [ $start_index, $end_index], [ @values ]);
20

DESCRIPTION

22       This module provides a utility function and several associated con‐
23       stants which support a general purpose array-splicer interface, used by
24       several of the Standard and Composite method generators.
25
26       array_splicer
27
28       This is a general-purpose array accessor function. Depending on the
29       arguments passed to it, it will get, set, slice, splice, or otherwise
30       modify your array.
31
32       ·   If called without any arguments, returns the contents of the array
33           in list context, or an array reference in scalar context (or
34           undef).
35
36             # Get all values
37             $value_ref = array_splicer( $array_ref );
38             @values = array_splicer( $array_ref );
39
40       ·   If called with a single numeric argument, uses that argument as an
41           index to retrieve from the referenced array, and returns that value
42           (or undef).
43
44             # Get one value
45             $value = array_splicer( $array_ref, $index );
46
47       ·   If called with a single array ref argument, sets the contents of
48           the array to match the contents of the provided one.
49
50             # Set contents of array
51             array_splicer( $array_ref, [ $value1, $value2, ... ] );
52
53             # Reset the array contents to empty
54             array_splicer( $array_ref, [] );
55
56       ·   If called with a two arguments, the first undefined and the second
57           an array ref argument, uses that array's contents as a list of
58           indexes to return a slice of the referenced array.
59
60             # Get slice of values
61             @values = array_splicer( $array_ref, undef, [ $index1, $index2, ... ] );
62
63       ·   If called with a list of argument pairs, each with a numeric index
64           and an associated value, stores the value at the given index in the
65           referenced array. The current value in each position will be over‐
66           written, and later arguments with the same index will override ear‐
67           lier ones. Returns the current array-ref value.
68
69             # Set one or more values by index
70             array_splicer( $array_ref, $index1 => $value1, $index2 => $value2, ... );
71
72       ·   If called with a list of argument pairs, each with the first item
73           being a reference to an array of up to two numbers, loops over each
74           pair and uses those numbers to splice the value array.
75
76             # Splice selected values in or out
77             array_splicer( $array_ref, [ $start_index, $count], [ @values ]);
78
79           The first controlling number is the position at which the splice
80           will begin. Zero will start before the first item in the list. Neg‐
81           ative numbers count backwards from the end of the array.
82
83           The second number is the number of items to be removed from the
84           list. If it is omitted, or undefined, or zero, no items are
85           removed. If it is a positive integer, that many items will be
86           returned.
87
88           If both numbers are omitted, or are both undefined, they default to
89           containing the entire value array.
90
91           If the second argument is undef, no values will be inserted; if it
92           is a non-reference value, that one value will be inserted; if it is
93           an array-ref, its values will be copied.
94
95           The method returns the items that removed from the array, if any.
96
97           Here are some examples of common splicing operations.
98
99             # Insert an item at position in the array
100             $obj->bar([3], 'Potatoes' );
101
102             # Remove 1 item from position 3 in the array
103             $obj->bar([3, 1], undef );
104
105             # Set a new value at position 2, and return the old value
106             print $obj->bar([2, 1], 'Froth' );
107
108             # Unshift an item onto the front of the list
109             array_splicer( $array_ref, [0], 'Bubbles' );
110
111             # Shift the first item off of the front of the list
112             print array_splicer( $array_ref, [0, 1], undef );
113
114             # Push an item onto the end of the list
115             array_splicer( $array_ref, [undef], 'Bubbles' );
116
117             # Pop the last item off of the end of the list
118             print array_splicer( $array_ref, [undef, 1], undef );
119
120       Constants
121
122       There are also constants symbols to facilitate some common combinations
123       of splicing arguments:
124
125         # Reset the array contents to empty
126         array_splicer( $array_ref, array_clear );
127
128         # Set the array contents to provided values
129         array_splicer( $array_ref, array_splice, [ 2, 3 ] );
130
131         # Unshift an item onto the front of the list
132         array_splicer( $array_ref, array_unshift, 'Bubbles' );
133
134         # Shift it back off again
135         print array_splicer( $array_ref, array_shift );
136
137         # Push an item onto the end of the list
138         array_splicer( $array_ref, array_push, 'Bubbles' );
139
140         # Pop it back off again
141         print array_splicer( $array_ref, array_pop );
142

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO