blib/lib/SPVM/LongList.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 package SPVM::LongList;
2  
3 1;
4  
5 =head1 Name
6  
7 SPVM::LongList - Dynamic long Arrays
8  
9 =head1 Description
10  
11 The LongList class in L<SPVM> has methods to manipulate dynamic long arrays.
12  
13 =head1 Usage
14
15 use LongList;
16
17 # Create a long list
18 my $list = LongList->new;
19 my $list = LongList->new([(long)1, 2, 3]);
20
21 # Create a long list with array length
22 my $list = LongList->new_len(10);
23
24 # Get list length
25 my $length = $list->length;
26
27 # Push value
28 $list->push((long)3);
29
30 # Pop value.
31 my $element = $list->pop;
32
33 # Unshift value.
34 $list->unshift((long)3);
35
36 # Shift value.
37 my $element = $list->shift;
38
39 # Set value.
40 $list->set(2, (long)3);
41
42 # Get value.
43 my $element = $list->get(2);
44
45 # Insert value
46 $list->insert(1, 3);
47
48 # Remove value
49 my $element = $list->remove(1);
50
51 # Convert list to array.
52 my $array = $list->to_array;
53
54 =head1 Details
55  
56 =head2 Internal Data Structure
57  
58 The L</"array"> stored in a LongList object always starts at index 0.
59  
60 The elements in the range that is greater than or equal to L</"length"> field and less than L</"capacity"> field are filled with 0.
61  
62 =head1 Interfaces
63  
64 =over 2
65  
66 =item * L<Cloneable|SPVM::Cloneable>
67  
68 =item * L<Countable|SPVM::Countable>
69  
70 =back
71  
72 =head1 Fields
73  
74 =head2 capacity
75  
76 C<has capacity : virtual ro int;>
77  
78 The capacity. This is the length of the internally reserved elements to extend the length of the list.
79  
80 =head2 length
81  
82 C<has length : virtual ro int;>
83  
84 The length of the list.
85  
86 =head2 array
87  
88 C<has array : long[];>
89  
90 The internal array stored in the LongList object.
91  
92 =head1 Class Methods
93  
94 =head2 new
95  
96 C<static method new : L<LongList|SPVM::LongList> ($array : long[] = undef, $capacity : int = -1);>
97  
98 Create a new C<LongList> object using L</"new_len">.
99  
100 The passed length to L</"new_len"> is the length of the array. If the array is undef, the length is 0.
101  
102 The elements of the array are copied to the elements of the the created array.
103  
104 Examples:
105  
106 my $list = LongList->new;
107 my $list = LongList->new([(long)1, 2, 3]);
108  
109 =head2 new_len
110  
111 C<static method new_len : L<LongList|SPVM::LongList> ($length : int, $capacity : int = -1);>
112  
113 Creates a new C<LongList> object with $length and $capacity.
114  
115 If $capacity is less than 0, the capacity is set to the default value.
116  
117 If $length is greater than $capacity, $capacity is set to $length.
118  
119 Exceptions:
120  
121 $length must be greater than or equal to 0. Otherwise an exception is thrown.
122  
123 =head2 new_ref
124  
125 C<static method new_ref : L<LongList|SPVM::LongList> ($array : long[]);>
126  
127 Creates a new L<LongList|SPVM::LongList> object, and set L</"array"> field to the array $array, and return the new object.
128  
129 Exceptions:
130  
131 The array $array must be defined. Otherwise an exception is thrown.
132  
133 =head1 Instance Methods
134  
135 =head2 get
136  
137 C<method get : long ($index : int);>
138  
139 Gets the element of the position of $index.
140  
141 If $index is a netative value, $index is set to L</"length"> plus $index.
142  
143 Exceptions:
144  
145 $index must be greater than or equal to 0. Otherwise an exception is thrown.
146  
147 $index must be less than the length of $list. Otherwise an exception is thrown.
148  
149 =head2 insert
150  
151 C<method insert : void ($index : int, $element : long);>
152  
153 Inserts an $element to the position of $index.
154  
155 Exceptions:
156  
157 $index must be greater than or equal to 0. Otherwise an exception is thrown.
158  
159 $index must be less than or equal to the length of $list. Otherwise an exception is thrown.
160  
161 =head2 pop
162  
163 C<method pop : long ();>
164  
165 Removes the last element and return it.
166  
167 Exceptions:
168  
169 The length of $list must be greater than 0. Otherwise an exception is thrown.
170  
171 =head2 push
172
173 C<method push : void ($element : long);>
174  
175 Adds an $element after the end of the list.
176  
177 =head2 remove
178  
179 C<method remove : long ($index : int);>
180  
181 Removes the element at the position of $index and return it.
182  
183 Exceptions:
184  
185 $index must be greater than or equal to 0. Otherwise an exception is thrown.
186  
187 $index must be less than the length of $list. Otherwise an exception is thrown.
188  
189 =head2 replace
190  
191 C<method replace : void ($offset : int, $remove_length : int, $replace : long[] = undef);>
192  
193 Same as L</"splice"> method, but the return vlaue is not returned.
194  
195 Exceptions:
196  
197 Exceptions thrown by L</"splice"> method could be thrown.
198  
199 =head2 splice
200  
201 C<method splice : long[] ($offset : int, $remove_length : int, $replace : long[] = undef);>
202  
203 Replaces the elements of the range specified by $offset and $length with $replace array, and returns removed elements creating a new array.
204  
205 If $replace is not defined, the replacemnet is not performed.
206  
207 Exceptions:
208  
209 $offset must be greater than or equal to 0. Otherwise an exception is thrown.
210  
211 $remove_length must be greater than or equal to 0. Otherwise an exception is thrown.
212  
213 $offset + $removing length must be less than or equal to the length of $list. Otherwise an exception is thrown.
214  
215 =head2 reserve
216  
217 C<method reserve : void ($new_capacity : int);>
218  
219 Reserves the elements with $new_capacity.
220  
221 If $new_capacity is greater than the capacity of the list, the capacity of the list is extended to $new_capacity.
222  
223 Exceptions:
224  
225 $new_capacity must be greater than or equal to 0. Otherwise an exception is thrown.
226  
227 =head2 resize
228  
229 C<method resize : void ($new_length : int);>
230  
231 Resize the list with $new_length.
232  
233 Exceptions:
234  
235 $new_length must be greater than or equal to 0. Otherwise an exception is thrown.
236  
237 =head2 set
238  
239 C<method set : void ($index : int, $element : long);>
240  
241 Sets $element at the position of $index.
242  
243 If $index is a netative value, $index is set to L</"length"> plus $index.
244  
245 Exceptions:
246  
247 $index must be greater than or equal to 0. Otherwise an exception is thrown.
248  
249 $index must be less than the length of $list. Otherwise an exception is thrown.
250  
251 =head2 shift
252  
253 C<method shift : long ();>
254  
255 Removes the first element and return it.
256  
257 Exceptions:
258  
259 The length of $list must be greater than 0. Otherwise an exception is thrown.
260  
261 =head2 to_array
262  
263 C<method to_array : long[] ();>
264  
265 Creates a new array with the length of the list and copies all elements of the list into the new array, and returns it.
266  
267 =head2 get_array
268  
269 C<method get_array : long[] ();>
270  
271 Returns the internal L</"array">.
272  
273 =head2 unshift
274  
275 C<method unshift : void ($element : long);>
276  
277 Inserts an $element at the beginning of the list.
278  
279 =head2 clone
280  
281 C<method clone : L<LongList|SPVM::LongList> ();>
282  
283 Clones this instance and returns it.
284  
285 =head2 push_
286  
287 C<method push_ : void ($elements : long[]);>
288  
289 Adds the elements $elements after the end of this list.
290  
291 This method calls L</"push"> method internally.
292  
293 Exceptions:
294  
295 The elements $elements must be defined.
296  
297 Exceptions thrown by L</"push"> method could be thrown.
298  
299 =head2 unshift_
300  
301 C<method unshift_ : void ($elements : long[]);>
302  
303 Inserts the elemnets $elements at the beginning of the list.
304  
305 Exceptions:
306  
307 The elements $elements must be defined.
308  
309 Exceptions thrown by L</"unshift"> method could be thrown.
310  
311 =head1 Copyright & License
312  
313 Copyright (c) 2023 Yuki Kimoto
314  
315 MIT License