| 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 |