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