1Set::Array(3)         User Contributed Perl Documentation        Set::Array(3)
2
3
4

NAME

6       Set::Array - Arrays as objects with lots of handy methods
7

SYNOPSIS

9       "my $sao1 = Set::Array->new(1,2,4,"hello",undef);"
10
11       "my $sao2 = Set::Array->new(qw(a b c a b c));"
12
13       "print $sao1->length; # prints 5"
14
15       "$sao2->unique->length->print; # prints 3"
16

PREREQUISITES

18       Perl 5.6 or later
19
20       The 'Want' module by Robin Houston.  Available on CPAN.
21

DESCRIPTION

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

OBJECT BEHAVIOR

37       The exact behavior of the methods depends largely on the calling
38       context.
39
40       Here are the rules:
41
42       * If a method is called in void context, the object itself is modified.
43
44       * 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
50       * 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
54       Here is a quick example:
55
56       "my $sao = Set::Array->new(1,2,3,2,3);"
57
58       "my @uniq = $sao->unique(); # Object unmodified.  '@uniq' contains 3
59       values."
60
61       "$sao->unique(); # Object modified, now contains 3 values"
62
63       Here are the exceptions:
64
65       * 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
68       * 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
74       * 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
82       * 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
89       * The join() method always returns a string and is really meant for use
90         in conjunction with the print() method.
91

BOOLEAN METHODS

93       In the following sections, the brackets in [val] indicate that val is a
94       optional parameter.
95
96   exists([val])
97       Returns 1 if val exists within the array, 0 otherwise.
98
99       If no value (or undef) is passed, then this method will test for the
100       existence of undefined values within the array.
101
102   is_empty()
103       Returns 1 if the array is empty, 0 otherwise.  Empty is defined as
104       having a length of 0.
105

STANDARD METHODS

107   at(index)
108       Returns the item at the given index (or undef).
109
110       A negative index may be used to count from the end of the array.
111
112       If no value (or undef) is specified, it will look for the first item
113       that is not defined.
114
115   bag($other_set, $reverse)
116       Returns the union of both sets, including duplicates (i.e. everything).
117
118       Setting $reverse to 1 reverses the sets as the first step in the
119       method.
120
121       Note: It does not reverse the contents of the sets.
122
123       See "General Notes" for the set of such methods, including a list of
124       overloaded operators.
125
126   clear([1])
127       Empties the array (i.e. length becomes 0).
128
129       You may pass a 1 to this method to set each element of the array to
130       undef rather than truly empty it.
131
132   compact()
133       o In scalar context
134           Returns an array ref of defined items.
135
136           The object is not modified.
137
138       o In list context
139           Returns an array of defined items.
140
141           The object is not modified.
142
143       o In chained context
144           Returns the object.
145
146           The object is modified if it contains undefined items.
147
148   count([val])
149       Returns the number of instances of val within the array.
150
151       If val is not specified (or is undef), the method will return the
152       number of undefined values within the array.
153
154   cpop()
155       The 'c' stands for 'chainable' pop.
156
157       Removes and discards the last element of the array.
158
159       Returns the object.
160
161               Set::Array -> new(1, 2, 3, 4, 5) -> cpop -> join -> print;
162
163       prints 1,2,3,4.
164
165       See also cshift(), pop() and shift().
166
167   cshift()
168       The 'c' stands for 'chainable' shift.
169
170       Removes and discards the first element of the array.
171
172       Returns the object.
173
174               Set::Array -> new(1, 2, 3, 4, 5) -> cshift -> join -> print;
175
176       prints 2,3,4,5.
177
178       See also cpop(), pop() and shift().
179
180   delete(@list)
181       Deletes all items within the object that match @list.
182
183       This method will die if @list is not defined.
184
185       If your goal is to delete undefined values from your object, use the
186       "compact()" method instead.
187
188       This method always modifies the object, if elements in @list match
189       elements in the object.
190
191       o In scalar context
192           Returns an array ref of unique items.
193
194       o In list context
195           Returns an array of unique items.
196
197       o In chained context
198           Returns the object.
199
200   delete_at(index, [index])
201       Deletes the item at the specified index.
202
203       If a second index is specified, a range of items is deleted.
204
205       You may use -1 or the string 'end' to refer to the last element of the
206       array.
207
208   difference($one, $two, $reverse)
209       Returns all elements in the left set that are not in the right set.
210
211       Setting $reverse to 1 reverses the sets as the first step in the
212       method.
213
214       Note: It does not reverse the contents of the sets.
215
216       See "General Notes" for the set of such methods, including a list of
217       overloaded operators.
218
219       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
222       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
225       So, I have used Try::Tiny to capture a call to want('OBJECT') in sub
226       difference().
227
228       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
232       Sample code:
233
234               #!/usr/bin/env perl
235
236               use strict;
237               use warnings;
238
239               use Set::Array;
240
241               # -------------
242
243               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
251               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
256       The last 4 lines all produce the same, correct, output, so any of
257       $set3, $set4 or $set5 is what you want.
258
259       See t/difference.pl.
260
261   duplicates()
262       Returns a list of N-1 elements for each element which appears N times
263       in the set.
264
265       For example, if you have set "X X Y Y Y", this method would return the
266       list "X Y Y".
267
268       If you want the output to be "X Y", see "unique()".
269
270       o In scalar context
271           Returns an array ref of duplicated items.
272
273           The object is not modified.
274
275       o In list context
276           Returns an array of duplicated items.
277
278           The object is not modified.
279
280       o In chained context
281           Returns the object.
282
283           The object is modified if it contains duplicated items.
284
285   fill(val, [start], [length])
286       Sets the selected elements of the array (which may be the entire array)
287       to val.
288
289       The default value for start is 0.
290
291       If length is not specified the entire array, however long it may be,
292       will be filled.
293
294       A range may also be used for the start parameter. A range must be a
295       quoted string in '0..999' format.
296
297       E.g. "$sao->fill('x', '3..65535');"
298
299       The array length/size may not be expanded with this call - it is only
300       meant to fill in already-existing elements.
301
302   first()
303       Returns the first element of the array (or undef).
304
305   flatten()
306       Causes a one-dimensional flattening of the array, recursively.
307
308       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
311       E.g. "my $sa = Set::Array->new([1,3,2],{one=>'a',two=>'b'},x,y,z);"
312
313       "$sao->flatten->join(',')->print; # prints "1,3,2,one,a,two,b,x,y,z""
314
315   foreach(sub ref)
316       Iterates over an array, executing the subroutine for each element in
317       the array.
318
319       If you wish to modify or otherwise act directly on the contents of the
320       array, use $_ within your sub reference.
321
322       E.g. To increment all elements in the array by one...
323
324       "$sao->foreach(sub{ ++$_ });"
325
326   get()
327       This is an alias for the indices() method.
328
329   index(val)
330       Returns the index of the first element of the array object that
331       contains val.
332
333       Returns undef if no value is found.
334
335       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
338   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
342       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
345   intersection($other_set)
346       Returns all elements common to both sets.
347
348       Note: It does not eliminate duplicates. Call "unique()" if that is what
349       you want.
350
351       You are strongly encouraged to examine line 19 of both
352       t/intersection.1.pl and t/intersection.2.pl.
353
354       Setting $reverse to 1 reverses the sets as the first step in the
355       method.
356
357       Note: It does not reverse the contents of the sets.
358
359       See "General Notes" for the set of such methods, including a list of
360       overloaded operators.
361
362   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
366       Setting $reverse to 1 reverses the sets as the first step in the
367       method.
368
369       Since order is ignored, this parameter is irrelevant.
370
371       Note: It does not reverse the contents of the sets.
372
373       See "General Notes" for the set of such methods, including a list of
374       overloaded operators.
375
376       See also "not_equal($other_set)".
377
378   join([string])
379       Joins the elements of the list into a single string with the elements
380       separated by the value of string.
381
382       Useful in conjunction with the print() method.
383
384       If no string is specified, then string defaults to a comma.
385
386       e.g. "$sao->join('-')->print;"
387
388   last()
389       Returns the last element of the array (or undef).
390
391   length()
392       Returns the number of elements within the array.
393
394   max()
395       Returns the maximum value of an array.
396
397       No effort is made to check for non-numeric data.
398
399   new()
400       This is the constructor.
401
402       See "difference($one, $two, $reverse)" for sample code.
403
404       See also "flatten()" for converting arrayrefs and hashrefs into lists.
405
406   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
410       Setting $reverse to 1 reverses the sets as the first step in the
411       method.
412
413       Since order is ignored, this parameter is irrelevant.
414
415       Note: It does not reverse the contents of the sets.
416
417       See "General Notes" for the set of such methods, including a list of
418       overloaded operators.
419
420       See also "is_equal($other_set)".
421
422   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
426   pop()
427       Removes the last element from the array.
428
429       Returns the popped element.
430
431       See also cpop(), cshift() and shift().
432
433   print([1])
434       Prints the contents of the array.
435
436       If a 1 is provided as an argument, the output will automatically be
437       terminated with a newline.
438
439       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
442       Can be called in void or list context, e.g.
443
444       "$sao->print(); # or..."  "print "Contents of array are: ",
445       $sao->print();"
446
447   push(list)
448       Adds list to the end of the array, where list is either a scalar value
449       or a list.
450
451       Returns an array or array reference in list or scalar context,
452       respectively.
453
454       Note that it does not return the length in scalar context. Use the
455       length method for that.
456
457   reverse()
458       o In scalar context
459           Returns an array ref of the items in the object, reversed.
460
461           The object is not modified.
462
463       o In list context
464           Returns an array of the items in the object, reversed.
465
466           The object is not modified.
467
468       o In chained context
469           Returns the object.
470
471           The object is modified, with its items being reversed.
472
473   rindex(val)
474       Similar to the index() method, except that it returns the index of the
475       last val found within the array.
476
477       Returns undef if no value is found.
478
479   set(index, value)
480       Sets the element at index to value, replacing whatever may have already
481       been there.
482
483   shift()
484       Shifts off the first element of the array and returns the shifted
485       element.
486
487       See also cpop(), cshift() and pop().
488
489   sort([coderef])
490       Sorts the contents of the array in alphabetical order, or in the order
491       specified by the optional coderef.
492
493       o In scalar context
494           Returns an array ref of the items in the object, sorted.
495
496           The object is not modified.
497
498       o In list context
499           Returns an array of the items in the object, sorted.
500
501           The object is not modified.
502
503       o In chained context
504           Returns the object.
505
506           The object is modified by sorting its items.
507
508       Use your standard $a and $b variables within your sort sub:
509
510       Program:
511
512               #!/usr/bin/env perl
513
514               use Set::Array;
515
516               # -------------
517
518               my $s = Set::Array->new(
519                       { name => 'Berger', salary => 15000 },
520                       { name => 'Berger', salary => 20000 },
521                       { name => 'Vera', salary => 25000 },
522               );
523
524               my($subref) = sub{ $b->{name} cmp $a->{name} || $b->{salary} <=> $a->{salary} };
525               my(@h)      = $s->sort($subref);
526
527               for my $h (@h)
528               {
529                       print "Name: $$h{name}. Salary: $$h{salary}. \n";
530               }
531
532       Output (because the sort subref puts $b before $a for name and salary):
533
534               Name: Vera. Salary: 25000.
535               Name: Berger. Salary: 20000.
536               Name: Berger. Salary: 15000.
537
538   splice([offset], [length], [list])
539       Splice the array starting at position offset up to length elements, and
540       replace them with list.
541
542       If no list is provided, all elements are deleted.
543
544       If length is omitted, everything from offset onward is removed.
545
546       Returns an array or array ref in list or scalar context, respectively.
547
548       This method always modifies the object, regardless of context.
549
550       If your goal was to grab a range of values without modifying the
551       object, use the indices method instead.
552
553   unique()
554       Returns a list of 1 element for each element which appears N times in
555       the set.
556
557       For example, if you have set "X X Y Y Y", this method would return the
558       list "X Y".
559
560       If you want the output to be "X Y Y", see "duplicates()".
561
562       o In scalar context
563           Returns an array ref of unique items.
564
565           The object is not modified.
566
567       o In list context
568           Returns an array of unique items.
569
570           The object is not modified.
571
572       o In chained context
573           Returns the object.
574
575           The object is modified if it contains duplicated items.
576
577   unshift(list)
578       Prepends a scalar or list to array.
579
580       Note that this method returns an array or array reference in list or
581       scalar context, respectively.
582
583       It does not return the length of the array in scalar context. Use the
584       length method for that.
585

ODDBALL METHODS

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
592       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
596       The default value of $option is even.
597
598       Of course, if you do not care about insertion order, you could just as
599       well do something like, "$sao->reverse->as_hash;"
600
601       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
606       $option can be specified in various ways:
607
608       undef
609           When you do not supply a value for this parameter, the default is
610           even.
611
612       'odd' or 'even'
613           The value may be a string.
614
615           This possibility was added in V 0.18.
616
617           This is now the recommended alternative.
618
619       {key_option => 'odd'} or {key_option => 'even'}
620           The value may be a hash ref, with 'key_option' as the hash key.
621
622           This possibility was added in V 0.18.
623
624       (key_option => 'odd') or (key_option => 'even')
625           The value may be a hash, with 'key_option' as the hash key.
626
627           This was the original (badly-documented) alternative to undef, and
628           it still supported in order to make the code backwards-compatible.
629
630   impose([append/prepend], string)
631       Appends or prepends the specified string to each element in the array.
632
633       Specify the method with either 'append' or 'prepend'.
634
635       The default is 'append'.
636
637   randomize()
638       Randomizes the order of the elements within the array.
639
640   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
645       The default is 'ltof'.
646
647       e.g.  my $sao = Set::Array->new(1,2,3);
648
649       $sao->rotate(); # order is now 3,1,2
650
651       $sao->rotate('ftol'); # order is back to 1,2,3
652
653   to_hash()
654       This is an alias for as_hash().
655

OVERLOADED (COMPARISON) OPERATORS

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
663       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
668       Examples (using the '==' operator or 'is_equal' method):
669
670       my $sao1 = Set::Array->new(1,2,3,4,5);
671
672       my $sao2 = Set::Array->new(1,2,3,4,5);
673
674       my $ref1 = [1,2,3,4,5];
675
676       if($sao1 == $sao2)...         # valid
677
678       if($sao1 == $ref1)...         # valid
679
680       if($ref1 == $sao2)...         # valid
681
682       if($sao1->is_equal($sao2))... # valid
683
684       if($sao1->is_equal($ref1))... # valid
685
686       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
690       & or bag - The union of both sets, including duplicates.
691
692       - or difference - Returns all elements in the left set that are not in
693       the right set. See "difference($one, $two)" for details.
694
695       == 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
699       != or not_equal - Tests for inequality of the content of the sets.
700       Again, order is ignored.
701
702       * or intersection - Returns all elements that are common to both sets.
703
704       Be warned that that line says 'all elements', not 'unique elements'.
705       You can call "unique" is you need just the unique elements.
706
707       See t/intersection.*.pl for sample code with and without calling
708       unique().
709
710       % 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
713       + or union - Returns the union of both sets.  Duplicates excluded.
714

FAQ

716   Why does the intersection() method include duplicates in the output?
717       Because it is documented to do that. The docs above say:
718
719       "Returns all elements that are common to both sets.
720
721       Be warned that that line says 'all elements', not 'unique elements'.
722       You can call "unique()" is you need just the unique elements."
723
724       Those statements means what they says!
725
726       See t/intersection.*.pl for sample code with and without calling
727       unique().
728
729       The following section, "EXAMPLES", contains other types of FAQ items.
730

EXAMPLES

732       For our examples, I will create 3 different objects
733
734       my $sao1 = Set::Array->new(1,2,3,a,b,c,1,2,3);
735
736       my $sao2 = Set::Array->new(1,undef,2,undef,3,undef);
737
738       my $sao3 = Set::Array->new(1,2,3,['a','b','c'],{name=>"Dan"});
739
740       How do I...
741
742       get the number of unique elements within the array?
743
744       "$sao1->unique()->length();"
745
746       count the number of non-undef elements within the array?
747
748       "$sao2->compact()->length();"
749
750       count the number of unique elements within an array, excluding undef?
751
752       "$sao2->compact()->unique()->length();"
753
754       print a range of indices?
755
756       "$sao1->indices('0..2')->print();"
757
758       test to see if two Set::Array objects are equal?
759
760       "if($sao1 == $sao2){ ... }"
761
762       "if($sao1->is_equal($sao2){ ... } # Same thing"
763
764       fill an array with a value, but only if it is not empty?
765
766       "if(!$sao1->is_empty()){ $sao1->fill('x') }"
767
768       shift an element off the array and return the shifted value?
769
770       "my $val = $sao1->shift())"
771
772       shift an element off the array and return the array?
773
774       "my @array = $sao1->delete_at(0)"
775
776       flatten an array and return a hash based on now-flattened array?, with
777       odd elements as the key?
778
779       "my %hash = $sao3->flatten()->reverse->as_hash();"
780
781       delete all elements within an array?
782
783       "$sao3->clear();"
784
785       "$sao3->splice();"
786
787       modify the object AND assign a value at the same time?
788
789       "my @unique = $sao1->unique->print;"
790

KNOWN BUGS

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
797       There are still bugs in Want V 0.20. See the discussion of
798       "difference($one, $two)" for details.
799

FUTURE PLANS

801       Anyone want a built-in 'permute()' method?
802
803       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
810       More flexibility with the foreach method (perhaps with iterators?).
811
812       More tests.
813

THANKS

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
818       Thanks also to Robin Houston for the 'Want' module!  Where would method
819       chaining be without it?
820

AUTHOR

822       Original author: Daniel Berger djberg96 at hotmail dot com imperator on
823       IRC (freenode)
824
825       Maintainer since V 0.12: Ron Savage <ron@savage.net.au> (in 2005).
826
827       Home page: http://savage.net.au/index.html
828
829
830
831perl v5.34.0                      2022-01-21                     Set::Array(3)
Impressum