| 1 | package SPVM::Sort; | ||
| 2 | |||
| 3 | 1; | ||
| 4 | |||
| 5 | =encoding utf8 | ||
| 6 | |||
| 7 | =head1 Name | ||
| 8 | |||
| 9 | SPVM::Sort - Sorting Functions | ||
| 10 | |||
| 11 | =head1 Usage | ||
| 12 | |||
| 13 | # Sort a byte array in-place by asc order | ||
| 14 | my $array = [(byte)2, 3, 1]; | ||
| 15 | Sort->sort_byte($array, method : int ($a : int, $b : int) { | ||
| 16 | return $a <=> $b; | ||
| 17 | }); | ||
| 18 | |||
| 19 | # Sort short array in-place by asc order | ||
| 20 | my $array = [(short)2, 3, 1]; | ||
| 21 | Sort->sort_short($array, method : int ($a : int, $b : int) { | ||
| 22 | return $a <=> $b; | ||
| 23 | }); | ||
| 24 | |||
| 25 | # Sort int array in-place by asc order | ||
| 26 | my $array = [2, 3, 1]; | ||
| 27 | Sort->sort_int($array, method : int ($a : int, $b : int) { | ||
| 28 | return $a <=> $b; | ||
| 29 | }); | ||
| 30 | |||
| 31 | # Sort long array in-place by asc order | ||
| 32 | my $array = [(long)2, 3, 1]; | ||
| 33 | Sort->sort_long($array, method : int ($a : long, $b : long) { | ||
| 34 | return $a <=> $b; | ||
| 35 | }); | ||
| 36 | |||
| 37 | # Sort float array in-place by asc order | ||
| 38 | my $array = [(float)2, 3, 1]; | ||
| 39 | Sort->sort_float($array, method : int ($a : float, $b : float) { | ||
| 40 | return $a <=> $b; | ||
| 41 | }); | ||
| 42 | |||
| 43 | # Sort double array in-place by asc order | ||
| 44 | my $array = [(double)2, 3, 1]; | ||
| 45 | Sort->sort_double($array, method : int ($a : double, $b : double) { | ||
| 46 | return $a <=> $b; | ||
| 47 | }); | ||
| 48 | |||
| 49 | # Sort string array in-place by asc order | ||
| 50 | my $array = ["11", "1", "2", undef, ""]; | ||
| 51 | Sort->sort_string($array, method : int ($a : string, $b : string) { | ||
| 52 | return $a cmp $b; | ||
| 53 | }); | ||
| 54 | |||
| 55 | # Sort object array in-place by asc order | ||
| 56 | my $minimals = new TestCase::Minimal[3]; | ||
| 57 | $minimals->[0] = TestCase::Minimal->new; | ||
| 58 | $minimals->[0]{x} = 3; | ||
| 59 | $minimals->[0]{y} = 5; | ||
| 60 | $minimals->[1] = TestCase::Minimal->new; | ||
| 61 | $minimals->[1]{x} = 3; | ||
| 62 | $minimals->[1]{y} = 7; | ||
| 63 | $minimals->[2] = TestCase::Minimal->new; | ||
| 64 | $minimals->[2]{x} = 2; | ||
| 65 | $minimals->[2]{y} = 9; | ||
| 66 | Sort->sort_object($minimals, method : int ($object1 : object, $object2 : object) { | ||
| 67 | my $minimal1 = (TestCase::Minimal)$object1; | ||
| 68 | my $minimal2 = (TestCase::Minimal)$object2; | ||
| 69 | |||
| 70 | return $minimal1->{x} <=> $minimal2->{x} || $minimal1->{y} <=> $minimal2->{y}; | ||
| 71 | }; | ||
| 72 | |||
| 73 | =head1 Description | ||
| 74 | |||
| 75 | C<Sort> provides sorting functions. The sorting algorithm is a stable merge sort. | ||
| 76 | |||
| 77 | =head1 Class Methods | ||
| 78 | |||
| 79 | =head2 sort_byte | ||
| 80 | |||
| 81 | C<static method sort_byte : void ($array : byte[], $comparator : L<Comparator::Int|SPVM::Comparator::Int>, $offset : int = 0, $length : int = -1);> | ||
| 82 | |||
| 83 | Sorts the range of the elements of C<byte> $array in-place. | ||
| 84 | |||
| 85 | The sorted range is from $offset to the position proceeded by $length. | ||
| 86 | |||
| 87 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 88 | |||
| 89 | The L<Comparator::Int|SPVM::Comparator::Int> comparator is used to compare each element. | ||
| 90 | |||
| 91 | Exceptions: | ||
| 92 | |||
| 93 | $array must be defined. | ||
| 94 | |||
| 95 | $offset must be greater than or equal to 0. | ||
| 96 | |||
| 97 | $comparator must be defined. | ||
| 98 | |||
| 99 | $offset + length must be less than or equal to the length of $elements. | ||
| 100 | |||
| 101 | =head2 sort_byte_asc | ||
| 102 | |||
| 103 | C<method sort_byte_asc : void ($array : byte[], $offset : int = 0, $length : int = -1);> | ||
| 104 | |||
| 105 | The alias for the following code using L</"sort_byte"> | ||
| 106 | |||
| 107 | Sort->sort_byte($array, method : int ($a : int, $b : int) { return $a <=> $b; }, $offset, $length); | ||
| 108 | |||
| 109 | =head2 sort_byte_desc | ||
| 110 | |||
| 111 | C<static method sort_byte_desc : void ($array : byte[], $offset : int = 0, $length : int = -1);> | ||
| 112 | |||
| 113 | The alias for the following code using L</"sort_byte"> | ||
| 114 | |||
| 115 | Sort->sort_byte($array, method : int ($a : int, $b : int) { return $b <=> $a; }, $offset, $length); | ||
| 116 | |||
| 117 | =head2 sort_double | ||
| 118 | |||
| 119 | C<static method sort_double : void ($array : double[], $comparator : L<Comparator::Double|SPVM::Comparator::Double>, $offset : int = 0, $length : int = -1);> | ||
| 120 | |||
| 121 | Sorts the range of the elements of C<double> $array in-place. | ||
| 122 | |||
| 123 | The sorted range is from $offset to the position proceeded by $length. | ||
| 124 | |||
| 125 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 126 | |||
| 127 | The L<Comparator::Double|SPVM::Comparator::Double> comparator is used to compare each element. | ||
| 128 | |||
| 129 | Exceptions: | ||
| 130 | |||
| 131 | $array must be defined. | ||
| 132 | |||
| 133 | $offset must be greater than or equal to 0. | ||
| 134 | |||
| 135 | $comparator must be defined. | ||
| 136 | |||
| 137 | $offset + length must be less than or equal to the length of $elements. | ||
| 138 | |||
| 139 | =head2 sort_double_asc | ||
| 140 | |||
| 141 | C<static method sort_double_asc : void ($array : double[], $offset : int = 0, $length : int = -1);> | ||
| 142 | |||
| 143 | The alias for the following code using L</"sort_double"> | ||
| 144 | |||
| 145 | Sort->sort_double($array, method : int ($a : double, $b : double) { return $a <=> $b; }, $offset, $length); | ||
| 146 | |||
| 147 | =head2 sort_double_desc | ||
| 148 | |||
| 149 | C<static method sort_double_desc : void ($array : double[], $offset : int = 0, $length : int = -1);> | ||
| 150 | |||
| 151 | The alias for the following code using L</"sort_double"> | ||
| 152 | |||
| 153 | Sort->sort_double($array, method : int ($a : double, $b : double) { return $b <=> $a; }, $offset, $length); | ||
| 154 | |||
| 155 | =head2 sort_float | ||
| 156 | |||
| 157 | C<static method sort_float : void ($array : float[], $comparator : L<Comparator::Float|SPVM::Comparator::Float>, $offset : int = 0, $length : int = -1);> | ||
| 158 | |||
| 159 | Sorts the range of the elements of C<float> $array in-place. | ||
| 160 | |||
| 161 | The sorted range is from $offset to the position proceeded by $length. | ||
| 162 | |||
| 163 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 164 | |||
| 165 | The L<Comparator::Float|SPVM::Comparator::Float> comparator is used to compare each element. | ||
| 166 | |||
| 167 | Exceptions: | ||
| 168 | |||
| 169 | $array must be defined. | ||
| 170 | |||
| 171 | $offset must be greater than or equal to 0. | ||
| 172 | |||
| 173 | $comparator must be defined. | ||
| 174 | |||
| 175 | $offset + length must be less than or equal to the length of $elements. | ||
| 176 | |||
| 177 | =head2 sort_float_asc | ||
| 178 | |||
| 179 | C<static method sort_float_asc : void ($array : float[], $offset : int = 0, $length : int = -1);> | ||
| 180 | |||
| 181 | The alias for the following code using L</"sort_float"> | ||
| 182 | |||
| 183 | Sort->sort_float($array, method : int ($a : float, $b : float) { return $a <=> $b; }, $offset, $length); | ||
| 184 | |||
| 185 | =head2 sort_float_desc | ||
| 186 | |||
| 187 | C<static method sort_float_desc : void ($array : float[], $offset : int = 0, $length : int = -1);> | ||
| 188 | |||
| 189 | The alias for the following code using L</"sort_float"> | ||
| 190 | |||
| 191 | Sort->sort_float($array, method : int ($a : float, $b : float) { return $b <=> $a; }, $offset, $length); | ||
| 192 | |||
| 193 | =head2 sort_float | ||
| 194 | |||
| 195 | C<static method sort_float : void ($array : float[], $comparator : L<Comparator::Float|SPVM::Comparator::Float>, $offset : int = 0, $length : int = -1);> | ||
| 196 | |||
| 197 | Sorts the range of the elements of C<float> $array in-place. | ||
| 198 | |||
| 199 | The sorted range is from $offset to the position proceeded by $length. | ||
| 200 | |||
| 201 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 202 | |||
| 203 | The L<Comparator::Float|SPVM::Comparator::Float> comparator is used to compare each element. | ||
| 204 | |||
| 205 | Exceptions: | ||
| 206 | |||
| 207 | $array must be defined. | ||
| 208 | |||
| 209 | $offset must be greater than or equal to 0. | ||
| 210 | |||
| 211 | $comparator must be defined. | ||
| 212 | |||
| 213 | $offset + length must be less than or equal to the length of $elements. | ||
| 214 | |||
| 215 | =head2 sort_float_asc | ||
| 216 | |||
| 217 | C<static method sort_float_asc : void ($array : float[], $offset : int = 0, $length : int = -1);> | ||
| 218 | |||
| 219 | The alias for the following code using L</"sort_float"> | ||
| 220 | |||
| 221 | Sort->sort_float($array, method : int ($a : float, $b : float) { return $a <=> $b; }, $offset, $length); | ||
| 222 | |||
| 223 | =head2 sort_float_desc | ||
| 224 | |||
| 225 | C<static method sort_float_desc : void ($array : float[], $offset : int = 0, $length : int = -1);> | ||
| 226 | |||
| 227 | The alias for the following code using L</"sort_float"> | ||
| 228 | |||
| 229 | Sort->sort_float($array, method : int ($a : float, $b : float) { return $b <=> $a; }, $offset, $length); | ||
| 230 | |||
| 231 | =head2 sort_int | ||
| 232 | |||
| 233 | C<static method sort_int : void ($array : int[], $comparator : L<Comparator::Int|SPVM::Comparator::Int>, $offset : int = 0, $length : int = -1);> | ||
| 234 | |||
| 235 | Sorts the range of the elements of C<int> $array in-place. | ||
| 236 | |||
| 237 | The sorted range is from $offset to the position proceeded by $length. | ||
| 238 | |||
| 239 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 240 | |||
| 241 | The L<Comparator::Int|SPVM::Comparator::Int> comparator is used to compare each element. | ||
| 242 | |||
| 243 | Exceptions: | ||
| 244 | |||
| 245 | $array must be defined. | ||
| 246 | |||
| 247 | $offset must be greater than or equal to 0. | ||
| 248 | |||
| 249 | $comparator must be defined. | ||
| 250 | |||
| 251 | $offset + length must be less than or equal to the length of $elements. | ||
| 252 | |||
| 253 | =head2 sort_int_asc | ||
| 254 | |||
| 255 | C<static method sort_int_asc : void ($array : int[], $offset : int = 0, $length : int = -1);> | ||
| 256 | |||
| 257 | The alias for the following code using L</"sort_int"> | ||
| 258 | |||
| 259 | Sort->sort_int($array, method : int ($a : int, $b : int) { return $a <=> $b; }, $offset, $length); | ||
| 260 | |||
| 261 | =head2 sort_int_desc | ||
| 262 | |||
| 263 | C<static method sort_int_desc : void ($array : int[], $offset : int = 0, $length : int = -1);> | ||
| 264 | |||
| 265 | The alias for the following code using L</"sort_int"> | ||
| 266 | |||
| 267 | Sort->sort_int($array, method : int ($a : int, $b : int) { return $b <=> $a; }, $offset, $length); | ||
| 268 | |||
| 269 | =head2 sort_long | ||
| 270 | |||
| 271 | C<static method sort_long : void ($array : long[], $comparator : L<Comparator::Long|SPVM::Comparator::Long>, $offset : int = 0, $length : int = -1);> | ||
| 272 | |||
| 273 | Sorts the range of the elements of C<long> $array in-place. | ||
| 274 | |||
| 275 | The sorted range is from $offset to the position proceeded by $length. | ||
| 276 | |||
| 277 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 278 | |||
| 279 | The L<Comparator::Long|SPVM::Comparator::Long> comparator is used to compare each element. | ||
| 280 | |||
| 281 | Exceptions: | ||
| 282 | |||
| 283 | $array must be defined. | ||
| 284 | |||
| 285 | $offset must be greater than or equal to 0. | ||
| 286 | |||
| 287 | $comparator must be defined. | ||
| 288 | |||
| 289 | $offset + length must be less than or equal to the length of $elements. | ||
| 290 | |||
| 291 | =head2 sort_long_asc | ||
| 292 | |||
| 293 | C<method sort_long_asc : void ($array : long[], $offset : int = 0, $length : int = -1);> | ||
| 294 | |||
| 295 | The alias for the following code using L</"sort_long"> | ||
| 296 | |||
| 297 | Sort->sort_long($array, method : int ($a : long, $b : long) { return $a <=> $b; }, $offset, $length); | ||
| 298 | |||
| 299 | =head2 sort_long_desc | ||
| 300 | |||
| 301 | C<static method sort_long_desc : void ($array : long[], $offset : int = 0, $length : int = -1);> | ||
| 302 | |||
| 303 | The alias for the following code using L</"sort_long"> | ||
| 304 | |||
| 305 | Sort->sort_long($array, method : int ($a : long, $b : long) { return $b <=> $a; }, $offset, $length); | ||
| 306 | |||
| 307 | =head2 sort_object | ||
| 308 | |||
| 309 | C<static method sort_object : void ($array : object[], $comparator : L<Comparator|SPVM::Comparator>, $offset : int = 0, $length : int = -1);> | ||
| 310 | |||
| 311 | Sorts the range of the elements of object array in-place. | ||
| 312 | |||
| 313 | The sorted range is from $offset to the position proceeded by $length. | ||
| 314 | |||
| 315 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 316 | |||
| 317 | The L<Comparator|SPVM::Comparator> comparator is used to compare each element. | ||
| 318 | |||
| 319 | Exceptions: | ||
| 320 | |||
| 321 | $offset must be greater than or equal to 0. | ||
| 322 | |||
| 323 | $comparator must be defined. | ||
| 324 | |||
| 325 | $offset + length must be less than or equal to the length of $elements. | ||
| 326 | |||
| 327 | =head2 sort_short | ||
| 328 | |||
| 329 | C<static method sort_short : void ($array : short[], $comparator : L<Comparator::Int|SPVM::Comparator::Int>, $offset : int = 0, $length : int = -1);> | ||
| 330 | |||
| 331 | Sorts the range of the elements of C<short> $array in-place. | ||
| 332 | |||
| 333 | The sorted range is from $offset to the position proceeded by $length. | ||
| 334 | |||
| 335 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 336 | |||
| 337 | The L<Comparator::Int|SPVM::Comparator::Int> comparator is used to compare each element. | ||
| 338 | |||
| 339 | Exceptions: | ||
| 340 | |||
| 341 | $array must be defined. | ||
| 342 | |||
| 343 | $offset must be greater than or equal to 0. | ||
| 344 | |||
| 345 | $comparator must be defined. | ||
| 346 | |||
| 347 | $offset + length must be less than or equal to the length of $elements. | ||
| 348 | |||
| 349 | =head2 sort_short_asc | ||
| 350 | |||
| 351 | C<static method sort_short_asc : void ($array : short[], $offset : int = 0, $length : int = -1);> | ||
| 352 | |||
| 353 | The alias for the following code using L</"sort_short"> | ||
| 354 | |||
| 355 | Sort->sort_short($array, method : int ($a : short, $b : short) { return $a <=> $b; }, $offset, $length); | ||
| 356 | |||
| 357 | =head2 sort_short_desc | ||
| 358 | |||
| 359 | C<static method sort_short_desc : void ($array : short[], $offset : int = 0, $length : int = -1);> | ||
| 360 | |||
| 361 | The alias for the following code using L</"sort_short"> | ||
| 362 | |||
| 363 | Sort->sort_short($array, method : int ($a : int, $b : int) { return $b <=> $a; }, $offset, $length); | ||
| 364 | |||
| 365 | =head2 sort_string | ||
| 366 | |||
| 367 | C<static method sort_string : void ($array : string[], $comparator : L<Comparator::String|SPVM::Comparator::String>, $offset : int = 0, $length : int = -1);> | ||
| 368 | |||
| 369 | Sorts the range of the elements of C<string> $array in-place. | ||
| 370 | |||
| 371 | The sorted range is from $offset to the position proceeded by $length. | ||
| 372 | |||
| 373 | If the length is less than 0, the length to the end of the string is calculated from the length of the array and the offset. | ||
| 374 | |||
| 375 | The L<Comparator::Int|SPVM::Comparator::Int> comparator is used to compare each element. | ||
| 376 | |||
| 377 | Exceptions: | ||
| 378 | |||
| 379 | $array must be defined. | ||
| 380 | |||
| 381 | $offset must be greater than or equal to 0. | ||
| 382 | |||
| 383 | $comparator must be defined. | ||
| 384 | |||
| 385 | $offset + length must be less than or equal to the length of $elements. | ||
| 386 | |||
| 387 | =head2 sort_string_asc | ||
| 388 | |||
| 389 | C<static method sort_string_asc : void ($array : string[], $offset : int = 0, $length : int = -1);> | ||
| 390 | |||
| 391 | The alias for the following code using L</"sort_string"> | ||
| 392 | |||
| 393 | Sort->sort_string($array, method : int ($a : string, $b : string) { return $a cmp $b; }, $offset, $length); | ||
| 394 | |||
| 395 | =head2 sort_string_desc | ||
| 396 | |||
| 397 | C<static method sort_string_desc : void ($array : string[], $offset : int = 0, $length : int = -1);> | ||
| 398 | |||
| 399 | The alias for the following code using L</"sort_string"> | ||
| 400 | |||
| 401 | Sort->sort_string($array, method : int ($a : string, $b : string) { return $b cmp $a; }, $offset, $length); | ||
| 402 | |||
| 403 | =head2 sort_options_asc | ||
| 404 | |||
| 405 | C<static method sort_options_asc : void ($options : object[]);> | ||
| 406 | |||
| 407 | Sorts $options by the dictionaly asc order of the key. | ||
| 408 | |||
| 409 | Exceptions: | ||
| 410 | |||
| 411 | $options must be defined. Otherwise an exception is thrown. | ||
| 412 | |||
| 413 | The length of $options must be an even number. Otherwise an exception is thrown. | ||
| 414 | |||
| 415 | The key of $options must be defined. Otherwise an exception is thrown. | ||
| 416 | |||
| 417 | The key of $options must be string type. Otherwise an exception is thrown. | ||
| 418 | |||
| 419 | Examples: | ||
| 420 | |||
| 421 | Sort->sort_options({key2 => 1, key3 => 2, key1 => 3}); | ||
| 422 | |||
| 423 | =head1 Copyright & License | ||
| 424 | |||
| 425 | Copyright (c) 2023 Yuki Kimoto | ||
| 426 | |||
| 427 | MIT License |