blib/lib/SPVM/DoubleList.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::DoubleList;
2  
3 1;
4  
5 =head1 Name
6  
7 SPVM::DoubleList - Dynamic double Arrays
8  
9 =head1 Description
10  
11 The DoubleList class in L<SPVM> has methods to manipulate dynamic double arrays.
12  
13 =head1 Usage
14
15 use DoubleList;
16
17 # Create a double list
18 my $list = DoubleList->new;
19 my $list = DoubleList->new([(double)1, 2, 3]);
20
21 # Create a double list with array length
22 my $list = DoubleList->new_len(10);
23
24 # Get list length
25 my $length = $list->length;
26
27 # Push value
28 $list->push((double)3);
29
30 # Pop value.
31 my $element = $list->pop;
32
33 # Unshift value.
34 $list->unshift((double)3);
35
36 # Shift value.
37 my $element = $list->shift;
38
39 # Set value.
40 $list->set(2, (double)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 DoubleList 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 : double[];>
89  
90 The internal array stored in the DoubleList object.
91  
92 =head1 Class Methods
93  
94 =head2 new
95  
96 C<static method new : L<DoubleList|SPVM::DoubleList> ($array : double[] = undef, $capacity : int = -1);>
97  
98 Create a new C<DoubleList> 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 = DoubleList->new;
107 my $list = DoubleList->new([(double)1, 2, 3]);
108  
109 =head2 new_len
110  
111 C<static method new_len : L<DoubleList|SPVM::DoubleList> ($length : int, $capacity : int = -1);>
112  
113 Creates a new L<DoubleList|SPVM::DoubleList> 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<DoubleList|SPVM::DoubleList> ($array : double[]);>
126  
127 Creates a new L<DoubleList|SPVM::DoubleList> 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 : double ($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.
148  
149 =head2 insert
150  
151 C<method insert : void ($index : int, $element : double);>
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.
160  
161 =head2 pop
162  
163 C<method pop : double ();>
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 : double);>
174  
175 Adds an $element after the end of the list.
176  
177 =head2 remove
178  
179 C<method remove : double ($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 : double[] = 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 : double[] ($offset : int, $remove_length : int, $replace : double[] = undef);>
202  
203  
204 Replaces the elements of the range specified by $offset and $length with $replace array, and returns removed elements creating a new array.
205  
206 If $replace is not defined, the replacemnet is not performed.
207  
208 Exceptions:
209  
210 $offset must be greater than or equal to 0. Otherwise an exception is thrown.
211  
212 $remove_length must be greater than or equal to 0. Otherwise an exception is thrown.
213  
214 $offset + $removing length must be less than or equal to the length of $list. Otherwise an exception is thrown.
215  
216 =head2 reserve
217  
218 C<method reserve : void ($new_capacity : int);>
219  
220 Reserves the elements with $new_capacity.
221  
222 If $new_capacity is greater than the capacity of the list, the capacity of the list is extended to $new_capacity.
223  
224 Exceptions:
225  
226 $new_capacity must be greater than or equal to 0. Otherwise an exception is thrown.
227  
228 =head2 resize
229  
230 C<method resize : void ($new_length : int);>
231  
232 Resize the list with $new_length.
233  
234 Exceptions:
235  
236 $new_length must be greater than or equal to 0. Otherwise an exception is thrown.
237  
238 =head2 set
239  
240 C<method set : void ($index : int, $element : double);>
241  
242 Sets $element at the position of $index.
243  
244 If $index is a netative value, $index is set to L</"length"> plus $index.
245  
246 Exceptions:
247  
248 $index must be greater than or equal to 0. Otherwise an exception is thrown.
249  
250 $index must be less than the length of $list. Otherwise an exception is thrown.
251  
252 =head2 shift
253  
254 C<method shift : double ();>
255  
256 Removes the first element and return it.
257  
258 Exceptions:
259  
260 The length of $list must be greater than 0. Otherwise an exception is thrown.
261  
262 =head2 to_array
263  
264 C<method to_array : double[] ();>
265  
266 Creates a new array with the length of the list and copies all elements of the list into the new array, and returns it.
267  
268 =head2 get_array
269  
270 C<method get_array : double[] ();>
271  
272 Returns the internal L</"array">.
273  
274 =head2 unshift
275  
276 C<method unshift : void ($element : double);>
277  
278 Inserts an $element at the beginning of the list.
279  
280 =head2 clone
281  
282 C<method clone : L<DoubleList|SPVM::DoubleList> ();>
283  
284 Clones this instance and returns it.
285  
286 =head2 push_
287  
288 C<method push_ : void ($elements : double[]);>
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 : double[]);>
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 =head1 Copyright & License
313  
314 Copyright (c) 2023 Yuki Kimoto
315  
316 MIT License