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

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO