blib/lib/SPVM/ByteList.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::ByteList;
2  
3 1;
4  
5 =head1 Name
6  
7 SPVM::ByteList - Dynamic byte Arrays
8  
9 =head1 Description
10  
11 The ByteList class in L<SPVM> has methods to manipulate dynamic byte arrays.
12  
13 =head1 Usage
14
15 use ByteList;
16
17 # Create a byte list
18 my $list = ByteList->new;
19 my $list = ByteList->new([(byte)1, 2, 3]);
20
21 # Create a byte list with array length
22 my $list = ByteList->new_len(10);
23
24 # Get list length
25 my $length = $list->length;
26
27 # Push value
28 $list->push(3);
29
30 # Pop value.
31 my $element = $list->pop;
32
33 # Unshift value.
34 $list->unshift(3);
35
36 # Shift value.
37 my $element = $list->shift;
38
39 # Set value.
40 $list->set(2, 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 ByteList 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 : byte[];>
89  
90 The internal array stored in the ByteList object.
91  
92 =head1 Class Methods
93  
94 =head2 new
95  
96 C<static method new : L<ByteList|SPVM::ByteList> ($array : byte[] = undef, $capacity : int = -1);>
97  
98 Creates a new C<ByteList> object using L</"new_len">.
99  
100 The passed length to L</"new_len"> is the length of $array. If the array is undef, the length is 0.
101  
102 The elements of $array are copied to the elements of the the created array.
103  
104 Examples:
105  
106 my $list = ByteList->new;
107 my $list = ByteList->new([(byte)1, 2, 3]);
108  
109 =head2 new_len
110  
111 C<static method new_len : L<ByteList|SPVM::ByteList> ($length : int, $capacity : int = -1);>
112  
113 Creates a new C<ByteList> 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<ByteList|SPVM::> ($array : byte[]);>
126  
127 Creates a new L<ByteList|SPVM::> 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 : int ($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 : int);>
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 : int ();>
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 : int);>
174  
175 Adds an $element after the end of the list.
176  
177 =head2 remove
178  
179 C<method remove : int ($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 : byte[] = 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 : byte[] ($offset : int, $remove_length : int, $replace : byte[] = 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 Resizes 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 : int);>
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.
250  
251 =head2 shift
252  
253 C<method shift : int ();>
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 : byte[] ();>
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 : byte[] ();>
270  
271 Returns the internal L</"array">.
272  
273 =head2 unshift
274  
275 C<method unshift : void ($element : int);>
276  
277 Inserts an $element at the beginning of the list.
278  
279 =head2 clone
280  
281 C<method clone : L<ByteList|SPVM::ByteList> ();>
282  
283 Clones this instance and returns it.
284  
285 =head2 push_
286  
287 C<method push_ : void ($elements : byte[]);>
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 : byte[]);>
302  
303 Inserts the elements $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