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