blib/lib/SPVM/Sort.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::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