1Set::Array(3) User Contributed Perl Documentation Set::Array(3)
2
6 Set::Array - Arrays as objects with lots of handy methods
7
9 "my $sao1 = Set::Array->new(1,2,4,"hello",undef);"
10 "my $sao2 = Set::Array->new(qw(a b c a b c));"
12 "print $sao1->length; # prints 5"
14 "$sao2->unique->length->print; # prints 3"
16
18 Perl 5.6 or later
19 The 'Want' module by Robin Houston. Available on CPAN.
21
23 Set::Array allows you to create arrays as objects and use OO-style
24 methods on them. Many convenient methods are provided here that appear
25 in the FAQs, the Perl Cookbook or posts from comp.lang.perl.misc. In
26 addition, there are Set methods with corresponding (overloaded)
27 operators for the purpose of Set comparison, i.e. +, ==, etc.
28 The purpose is to provide built-in methods for operations that people
30 are always asking how to do, and which already exist in languages like
31 Ruby. This should (hopefully) improve code readability and/or
32 maintainability. The other advantage to this module is method-chaining
33 by which any number of methods may be called on a single object in a
34 single statement.
35
37 The exact behavior of the methods depends largely on the calling
38 context.
39 Here are the rules:
41 * If a method is called in void context, the object itself is modified.
43 * If the method called is not the last method in a chain (i.e. it is
45 called
46 in object context), the object itself is modified by that method
47 regardless
48 of the 'final' context or method call.
49 * If a method is called in list or scalar context, a list or list
51 refererence
52 is returned, respectively. The object itself is NOT modified.
53 Here is a quick example:
55 "my $sao = Set::Array->new(1,2,3,2,3);"
57 "my @uniq = $sao->unique(); # Object unmodified. '@uniq' contains 3
59 values."
60 "$sao->unique(); # Object modified, now contains 3 values"
62 Here are the exceptions:
64 * Methods that report a value, such as boolean methods like exists() or
66 other methods such as at() or as_hash(), never modify the object.
67 * The methods clear(), delete(), delete_at(), and splice will
69 always modify the object. It seemed much too counterintuitive to call
70 these
71 methods in any context without actually
72 deleting/clearing/substituting the items!
73 * The methods shift() and pop() will modify the object AND return
75 the value that was shifted or popped from the array. Again, it
76 seemed
77 much too counterintuitive for something like "$val = $sao->shift" to
78 return a value while leaving the object unchanged. If you
79 really want the first or last value without modifying the object, you
80 can always use the first() or last() method, respectively.
81 * The methods cshift() and cpop() (for chainable-shift and chainable-
83 pop)
84 will modify the object and return the object. I.e. the value shifted
85 or popped
86 is discarded. See the docs below or the code at the end of t/test.t
87 for examples.
88 * The join() method always returns a string and is really meant for use
90 in conjunction with the print() method.
91
93 In the following sections, the brackets in [val] indicate that val is a
94 optional parameter.
95 exists([val])
97 Returns 1 if val exists within the array, 0 otherwise.
98 If no value (or undef) is passed, then this method will test for the
100 existence of undefined values within the array.
101 is_empty()
103 Returns 1 if the array is empty, 0 otherwise. Empty is defined as
104 having a length of 0.
105
107 at(index)
108 Returns the item at the given index (or undef).
109 A negative index may be used to count from the end of the array.
111 If no value (or undef) is specified, it will look for the first item
113 that is not defined.
114 bag($other_set, $reverse)
116 Returns the union of both sets, including duplicates (i.e. everything).
117 Setting $reverse to 1 reverses the sets as the first step in the
119 method.
120 Note: It does not reverse the contents of the sets.
122 See "General Notes" for the set of such methods, including a list of
124 overloaded operators.
125 clear([1])
127 Empties the array (i.e. length becomes 0).
128 You may pass a 1 to this method to set each element of the array to
130 undef rather than truly empty it.
131 compact()
133 o In scalar context
134 Returns an array ref of defined items.
135 The object is not modified.
137 o In list context
139 Returns an array of defined items.
140 The object is not modified.
142 o In chained context
144 Returns the object.
145 The object is modified if it contains undefined items.
147 count([val])
149 Returns the number of instances of val within the array.
150 If val is not specified (or is undef), the method will return the
152 number of undefined values within the array.
153 cpop()
155 The 'c' stands for 'chainable' pop.
156 Removes and discards the last element of the array.
158 Returns the object.
160 Set::Array -> new(1, 2, 3, 4, 5) -> cpop -> join -> print;
162 prints 1,2,3,4.
164 See also cshift(), pop() and shift().
166 cshift()
168 The 'c' stands for 'chainable' shift.
169 Removes and discards the first element of the array.
171 Returns the object.
173 Set::Array -> new(1, 2, 3, 4, 5) -> cshift -> join -> print;
175 prints 2,3,4,5.
177 See also cpop(), pop() and shift().
179 delete(@list)
181 Deletes all items within the object that match @list.
182 This method will die if @list is not defined.
184 If your goal is to delete undefined values from your object, use the
186 "compact()" method instead.
187 This method always modifies the object, if elements in @list match
189 elements in the object.
190 o In scalar context
192 Returns an array ref of unique items.
193 o In list context
195 Returns an array of unique items.
196 o In chained context
198 Returns the object.
199 delete_at(index, [index])
201 Deletes the item at the specified index.
202 If a second index is specified, a range of items is deleted.
204 You may use -1 or the string 'end' to refer to the last element of the
206 array.
207 difference($one, $two, $reverse)
209 Returns all elements in the left set that are not in the right set.
210 Setting $reverse to 1 reverses the sets as the first step in the
212 method.
213 Note: It does not reverse the contents of the sets.
215 See "General Notes" for the set of such methods, including a list of
217 overloaded operators.
218 Study the sample code below carefully, since all of $set1, $set8 and
220 $set9 get changed, perhaps when you were not expecting them to be.
221 There is a problem however, with 2 bugs in the Want module (V 0.20),
223 relating to want('OBJECT') and wantref() both causing segfaults.
224 So, I have used Try::Tiny to capture a call to want('OBJECT') in sub
226 difference().
227 If an error is thrown, I just ignore it. This is horribly tacky, but
229 after waiting 7 years (it is now 2012-03-07) I have given up on
230 expecting patches to Want.
231 Sample code:
233 #!/usr/bin/env perl
235 use strict;
237 use warnings;
238 use Set::Array;
240 # -------------
242 my($set1) = Set::Array -> new(qw(abc def ghi jkl mno) );
244 my($set8) = Set::Array -> new(@$set1); # Duplicate for later.
245 my($set9) = Set::Array -> new(@$set1); # Duplicate for later.
246 my($set2) = Set::Array -> new(qw(def jkl pqr));
247 my($set3) = $set1 - $set2; # Changes $set1. $set3 is a set.
248 my($set4) = Set::Array -> new(@{$set8 - $set2}); # Changes $set8. $set4 is a set.
249 my(@set5) = $set9 -> difference($set2); # Changes $set9. $set5 is an array.
250 print '1: ', join(', ', @$set3), ". \n";
252 print '2: ', join(', ', @{$set4 -> print}), ". \n";
253 print '3: ', join(', ', $set4 -> print), ". \n";
254 print '4: ', join(', ', @set5), ". \n";
255 The last 4 lines all produce the same, correct, output, so any of
257 $set3, $set4 or $set5 is what you want.
258 See t/difference.pl.
260 duplicates()
262 Returns a list of N-1 elements for each element which appears N times
263 in the set.
264 For example, if you have set "X X Y Y Y", this method would return the
266 list "X Y Y".
267 If you want the output to be "X Y", see "unique()".
269 o In scalar context
271 Returns an array ref of duplicated items.
272 The object is not modified.
274 o In list context
276 Returns an array of duplicated items.
277 The object is not modified.
279 o In chained context
281 Returns the object.
282 The object is modified if it contains duplicated items.
284 fill(val, [start], [length])
286 Sets the selected elements of the array (which may be the entire array)
287 to val.
288 The default value for start is 0.
290 If length is not specified the entire array, however long it may be,
292 will be filled.
293 A range may also be used for the start parameter. A range must be a
295 quoted string in '0..999' format.
296 E.g. "$sao->fill('x', '3..65535');"
298 The array length/size may not be expanded with this call - it is only
300 meant to fill in already-existing elements.
301 first()
303 Returns the first element of the array (or undef).
304 flatten()
306 Causes a one-dimensional flattening of the array, recursively.
307 That is, for every element that is an array (or hash, or a ref to
309 either an array or hash), extract its elements into the array.
310 E.g. "my $sa = Set::Array->new([1,3,2],{one=>'a',two=>'b'},x,y,z);"
312 "$sao->flatten->join(',')->print; # prints "1,3,2,one,a,two,b,x,y,z""
314 foreach(sub ref)
316 Iterates over an array, executing the subroutine for each element in
317 the array.
318 If you wish to modify or otherwise act directly on the contents of the
320 array, use $_ within your sub reference.
321 E.g. To increment all elements in the array by one...
323 "$sao->foreach(sub{ ++$_ });"
325 get()
327 This is an alias for the indices() method.
328 index(val)
330 Returns the index of the first element of the array object that
331 contains val.
332 Returns undef if no value is found.
334 Note that there is no dereferencing here so if you are looking for an
336 item nested within a ref, use the flatten method first.
337 indices(val1, [val2], [valN])
339 Returns an array consisting of the elements at the specified indices,
340 or undef if the element is out of range.
341 A range may also be used for each of the <valN> parameters. A range
343 must be a quoted string in '0..999' format.
344 intersection($other_set)
346 Returns all elements common to both sets.
347 Note: It does not eliminate duplicates. Call "unique()" if that is what
349 you want.
350 You are strongly encouraged to examine line 19 of both
352 t/intersection.1.pl and t/intersection.2.pl.
353 Setting $reverse to 1 reverses the sets as the first step in the
355 method.
356 Note: It does not reverse the contents of the sets.
358 See "General Notes" for the set of such methods, including a list of
360 overloaded operators.
361 is_equal($other_set)
363 Tests to see if the 2 sets are equal (regardless of order). Returns 1
364 for equal and 0 for not equal.
365 Setting $reverse to 1 reverses the sets as the first step in the
367 method.
368 Since order is ignored, this parameter is irrelevant.
370 Note: It does not reverse the contents of the sets.
372 See "General Notes" for the set of such methods, including a list of
374 overloaded operators.
375 See also "not_equal($other_set)".
377 join([string])
379 Joins the elements of the list into a single string with the elements
380 separated by the value of string.
381 Useful in conjunction with the print() method.
383 If no string is specified, then string defaults to a comma.
385 e.g. "$sao->join('-')->print;"
387 last()
389 Returns the last element of the array (or undef).
390 length()
392 Returns the number of elements within the array.
393 max()
395 Returns the maximum value of an array.
396 No effort is made to check for non-numeric data.
398 new()
400 This is the constructor.
401 See "difference($one, $two, $reverse)" for sample code.
403 See also "flatten()" for converting arrayrefs and hashrefs into lists.
405 not_equal($other_set)
407 Tests to see if the 2 sets are not equal (regardless of order). Returns
408 1 for not equal and 0 for equal.
409 Setting $reverse to 1 reverses the sets as the first step in the
411 method.
412 Since order is ignored, this parameter is irrelevant.
414 Note: It does not reverse the contents of the sets.
416 See "General Notes" for the set of such methods, including a list of
418 overloaded operators.
419 See also "is_equal($other_set)".
421 pack(template)
423 Packs the contents of the array into a string (in scalar context) or a
424 single array element (in object or void context).
425 pop()
427 Removes the last element from the array.
428 Returns the popped element.
430 See also cpop(), cshift() and shift().
432 print([1])
434 Prints the contents of the array.
435 If a 1 is provided as an argument, the output will automatically be
437 terminated with a newline.
438 This also doubles as a 'contents' method, if you just want to make a
440 copy of the array, e.g. my @copy = $sao->print;
441 Can be called in void or list context, e.g.
443 "$sao->print(); # or..." "print "Contents of array are: ",
445 $sao->print();"
446 push(list)
448 Adds list to the end of the array, where list is either a scalar value
449 or a list.
450 Returns an array or array reference in list or scalar context,
452 respectively.
453 Note that it does not return the length in scalar context. Use the
455 length method for that.
456 reverse()
458 o In scalar context
459 Returns an array ref of the items in the object, reversed.
460 The object is not modified.
462 o In list context
464 Returns an array of the items in the object, reversed.
465 The object is not modified.
467 o In chained context
469 Returns the object.
470 The object is modified, with its items being reversed.
472 rindex(val)
474 Similar to the index() method, except that it returns the index of the
475 last val found within the array.
476 Returns undef if no value is found.
478 set(index, value)
480 Sets the element at index to value, replacing whatever may have already
481 been there.
482 shift()
484 Shifts off the first element of the array and returns the shifted
485 element.
486 See also cpop(), cshift() and pop().
488 sort([coderef])
490 Sorts the contents of the array in alphabetical order, or in the order
491 specified by the optional coderef.
492 o In scalar context
494 Returns an array ref of the items in the object, sorted.
495 The object is not modified.
497 o In list context
499 Returns an array of the items in the object, sorted.
500 The object is not modified.
502 o In chained context
504 Returns the object.
505 The object is modified by sorting its items.
507 Use your standard $a and $b variables within your sort sub:
509 Program:
511 #!/usr/bin/env perl
513 use Set::Array;
515 # -------------
517 my $s = Set::Array->new(
519 { name => 'Berger', salary => 15000 },
520 { name => 'Berger', salary => 20000 },
521 { name => 'Vera', salary => 25000 },
522 );
523 my($subref) = sub{ $b->{name} cmp $a->{name} || $b->{salary} <=> $a->{salary} };
525 my(@h) = $s->sort($subref);
526 for my $h (@h)
528 {
529 print "Name: $$h{name}. Salary: $$h{salary}. \n";
530 }
531 Output (because the sort subref puts $b before $a for name and salary):
533 Name: Vera. Salary: 25000.
535 Name: Berger. Salary: 20000.
536 Name: Berger. Salary: 15000.
537 splice([offset], [length], [list])
539 Splice the array starting at position offset up to length elements, and
540 replace them with list.
541 If no list is provided, all elements are deleted.
543 If length is omitted, everything from offset onward is removed.
545 Returns an array or array ref in list or scalar context, respectively.
547 This method always modifies the object, regardless of context.
549 If your goal was to grab a range of values without modifying the
551 object, use the indices method instead.
552 unique()
554 Returns a list of 1 element for each element which appears N times in
555 the set.
556 For example, if you have set "X X Y Y Y", this method would return the
558 list "X Y".
559 If you want the output to be "X Y Y", see "duplicates()".
561 o In scalar context
563 Returns an array ref of unique items.
564 The object is not modified.
566 o In list context
568 Returns an array of unique items.
569 The object is not modified.
571 o In chained context
573 Returns the object.
574 The object is modified if it contains duplicated items.
576 unshift(list)
578 Prepends a scalar or list to array.
579 Note that this method returns an array or array reference in list or
581 scalar context, respectively.
582 It does not return the length of the array in scalar context. Use the
584 length method for that.
585
587 as_hash([$option])
588 Returns a hash based on the current array, with each even numbered
589 element (including 0) serving as the key, and each odd element serving
590 as the value.
591 This can be switched by using $option, and setting it to odd, in which
593 case the even values serve as the values, and the odd elements serve as
594 the keys.
595 The default value of $option is even.
597 Of course, if you do not care about insertion order, you could just as
599 well do something like, "$sao->reverse->as_hash;"
600 This method does not actually modify the object itself in any way. It
602 just returns a plain hash in list context or a hash reference in scalar
603 context. The reference is not blessed, therefore if this method is
604 called as part of a chain, it must be the last method called.
605 $option can be specified in various ways:
607 undef
609 When you do not supply a value for this parameter, the default is
610 even.
611 'odd' or 'even'
613 The value may be a string.
614 This possibility was added in V 0.18.
616 This is now the recommended alternative.
618 {key_option => 'odd'} or {key_option => 'even'}
620 The value may be a hash ref, with 'key_option' as the hash key.
621 This possibility was added in V 0.18.
623 (key_option => 'odd') or (key_option => 'even')
625 The value may be a hash, with 'key_option' as the hash key.
626 This was the original (badly-documented) alternative to undef, and
628 it still supported in order to make the code backwards-compatible.
629 impose([append/prepend], string)
631 Appends or prepends the specified string to each element in the array.
632 Specify the method with either 'append' or 'prepend'.
634 The default is 'append'.
636 randomize()
638 Randomizes the order of the elements within the array.
639 rotate(direction)
641 Moves the last item of the list to the front and shifts all other
642 elements one to the right, or vice-versa, depending on what you pass as
643 the direction - 'ftol' (first to last) or 'ltof' (last to first).
644 The default is 'ltof'.
646 e.g. my $sao = Set::Array->new(1,2,3);
648 $sao->rotate(); # order is now 3,1,2
650 $sao->rotate('ftol'); # order is back to 1,2,3
652 to_hash()
654 This is an alias for as_hash().
655
657 General Notes
658 For overloaded operators you may pass a Set::Array object, or just a
659 normal array reference (blessed or not) in any combination, so long as
660 one is a Set::Array object. You may use either the operator or the
661 equivalent method call.
662 Warning: You should always experiment with these methods before using
664 them in production. Why? Because you may have unrealistic expectations
665 that they automatially eliminate duplicates, for example. See the
666 "FAQ" for more.
667 Examples (using the '==' operator or 'is_equal' method):
669 my $sao1 = Set::Array->new(1,2,3,4,5);
671 my $sao2 = Set::Array->new(1,2,3,4,5);
673 my $ref1 = [1,2,3,4,5];
675 if($sao1 == $sao2)... # valid
677 if($sao1 == $ref1)... # valid
679 if($ref1 == $sao2)... # valid
681 if($sao1->is_equal($sao2))... # valid
683 if($sao1->is_equal($ref1))... # valid
685 All of these operations return either a boolean value (for equality
687 operators) or an array (in list context) or array reference (in scalar
688 context).
689 & or bag - The union of both sets, including duplicates.
691 - or difference - Returns all elements in the left set that are not in
693 the right set. See "difference($one, $two)" for details.
694 == or is_equal - This tests for equality of the content of the sets,
696 though ignores order. Thus, comparing (1,2,3) and (3,1,2) will yield a
697 true result.
698 != or not_equal - Tests for inequality of the content of the sets.
700 Again, order is ignored.
701 * or intersection - Returns all elements that are common to both sets.
703 Be warned that that line says 'all elements', not 'unique elements'.
705 You can call "unique" is you need just the unique elements.
706 See t/intersection.*.pl for sample code with and without calling
708 unique().
709 % or symmetric_difference or symm_diff - Returns all elements that are
711 in one set or the other, but not both. Opposite of intersection.
712 + or union - Returns the union of both sets. Duplicates excluded.
714
716 Why does the intersection() method include duplicates in the output?
717 Because it is documented to do that. The docs above say:
718 "Returns all elements that are common to both sets.
720 Be warned that that line says 'all elements', not 'unique elements'.
722 You can call "unique()" is you need just the unique elements."
723 Those statements means what they says!
725 See t/intersection.*.pl for sample code with and without calling
727 unique().
728 The following section, "EXAMPLES", contains other types of FAQ items.
730
732 For our examples, I will create 3 different objects
733 my $sao1 = Set::Array->new(1,2,3,a,b,c,1,2,3);
735 my $sao2 = Set::Array->new(1,undef,2,undef,3,undef);
737 my $sao3 = Set::Array->new(1,2,3,['a','b','c'],{name=>"Dan"});
739 How do I...
741 get the number of unique elements within the array?
743 "$sao1->unique()->length();"
745 count the number of non-undef elements within the array?
747 "$sao2->compact()->length();"
749 count the number of unique elements within an array, excluding undef?
751 "$sao2->compact()->unique()->length();"
753 print a range of indices?
755 "$sao1->indices('0..2')->print();"
757 test to see if two Set::Array objects are equal?
759 "if($sao1 == $sao2){ ... }"
761 "if($sao1->is_equal($sao2){ ... } # Same thing"
763 fill an array with a value, but only if it is not empty?
765 "if(!$sao1->is_empty()){ $sao1->fill('x') }"
767 shift an element off the array and return the shifted value?
769 "my $val = $sao1->shift())"
771 shift an element off the array and return the array?
773 "my @array = $sao1->delete_at(0)"
775 flatten an array and return a hash based on now-flattened array?, with
777 odd elements as the key?
778 "my %hash = $sao3->flatten()->reverse->as_hash();"
780 delete all elements within an array?
782 "$sao3->clear();"
784 "$sao3->splice();"
786 modify the object AND assign a value at the same time?
788 "my @unique = $sao1->unique->print;"
790
792 There is a bug in the Want-0.05 module that currently prevents the use
793 of most of the overloaded operators, though you can still use the
794 corresponding method names. The equality operators == and != should
795 work, however.
796 There are still bugs in Want V 0.20. See the discussion of
798 "difference($one, $two)" for details.
799
801 Anyone want a built-in 'permute()' method?
802 I am always on the lookout for faster algorithms. If you heve looked
804 at the code for a particular method and you know of a faster way,
805 please email me. Be prepared to backup your claims with benchmarks
806 (and the benchmark code you used). Tests on more than one operating
807 system are preferable. No, map is not always faster - foreach loops
808 usually are in my experience.
809 More flexibility with the foreach method (perhaps with iterators?).
811 More tests.
813
815 Thanks to all the kind (and sometimes grumpy) folks at
816 comp.lang.perl.misc who helped me with problems and ideas I had.
817 Thanks also to Robin Houston for the 'Want' module! Where would method
819 chaining be without it?
820
822 Original author: Daniel Berger djberg96 at hotmail dot com imperator on
823 IRC (freenode)
824 Maintainer since V 0.12: Ron Savage <ron@savage.net.au> (in 2005).
826 Home page: http://savage.net.au/index.html
828perl v5.36.0 2023-01-20 Set::Array(3)