|
NAMESet::Scalar - basic set operationsSYNOPSISuse Set::Scalar; $s = Set::Scalar->new; $s->insert('a', 'b'); $s->delete('b'); $t = Set::Scalar->new('x', 'y', $z); DESCRIPTIONCreating$s = Set::Scalar->new; $s = Set::Scalar->new(@members); $t = $s->clone; $t = $s->copy; # Clone of clone. $t = $s->empty_clone; # Like clone() but with no members. Modifying$s->insert(@members); $s->delete(@members); $s->invert(@members); # Insert if hasn't, delete if has. $s->clear; # Removes all the elements. Note that clear() only releases the memory used by the set to be reused by Perl; it will not reduce the overall memory use. Displayingprint $s, "\n"; The display format of a set is the members of the set separated by spaces and enclosed in parentheses (), for example: my $s = Set::Scalar->new(); $s->insert("a".."e"); print $s, "\n"; will output a b c d e You can even display recursive sets. See "Customising Display" for customising the set display. QueryingAssuming a set $s:@members = $s->members; @elements = $s->elements; # Alias for members. @$s # Overloaded alias for members. $size = $s->size; # The number of members. $s->has($m) # Return true if has that member. $s->contains($m) # Alias for has(). if ($s->has($member)) { ... } $s->member($m) # Returns the member if has that member. $s->element($m) # Alias for member. $s->is_null # Returns true if the set is empty. $s->is_empty # Alias for is_null. $s->is_universal # Returns true if the set is universal. $s->null # The null set. $s->empty # Alias for null. $s->universe # The universe of the set. Deriving$u = $s->union($t); $i = $s->intersection($t); $d = $s->difference($t); $e = $s->symmetric_difference($t); $v = $s->unique($t); $c = $s->complement; These methods have operator overloads: $u = $s + $t; # union $i = $s * $t; # intersection $d = $s - $t; # difference $e = $s % $t; # symmetric_difference $v = $s / $t; # unique $c = -$s; # complement Both the "symmetric_difference" and "unique" are symmetric on all their arguments. For two sets they are identical but for more than two sets beware: "symmetric_difference" returns true for elements that are in an odd number (1, 3, 5, ...) of sets, "unique" returns true for elements that are in one set. Some examples of the various set differences below (the _ is just used to align the elements): set or difference value $a (a b c d e _ _ _ _) $b (_ _ c d e f g _ _) $c (_ _ _ _ e f g h i) $a->difference($b) (a b _ _ _ _ _ _ _) $a->symmetric_difference($b) (a b _ _ _ f g _ _) $a->unique($b) (a b _ _ _ f g _ _) $b->difference($a) (_ _ _ _ _ f g _ _) $b->symmetric_difference($a) (a b _ _ _ f g _ _) $b->unique($a) (a b _ _ _ f g _ _) $a->difference($b, $c) (a b _ _ _ _ _ _ _) $a->symmetric_difference($b, $c) (a b _ _ e _ _ h i) $a->unique($b, $c) (a b _ _ _ _ _ h i) Comparing$eq = $s->is_equal($t); $dj = $s->is_disjoint($t); $pi = $s->is_properly_intersecting($t); $ps = $s->is_proper_subset($t); $pS = $s->is_proper_superset($t); $is = $s->is_subset($t); $iS = $s->is_superset($t); $cmp = $s->compare($t); The "compare" method returns a string from the following list: "equal", "disjoint", "proper subset", "proper superset", "proper intersect", and in future (once I get around implementing it), "disjoint universes". These methods have operator overloads: $eq = $s == $t; # is_equal $dj = $s != $t; # is_disjoint # No operator overload for is_properly_intersecting. $ps = $s < $t; # is_proper_subset $pS = $s > $t; # is_proper_superset $is = $s <= $t; # is_subset $iS = $s >= $t; # is_superset $cmp = $s <=> $t; Boolean contextsIn Boolean contexts such asif ($set) { ... } while ($set1 && $set2) { ... } the size of the $set is tested, so empty sets test as false, and non-empty sets as true. Iteratingwhile (defined(my $e = $s->each)) { ... } This is more memory-friendly than for my $e ($s->elements) { ... } which would first construct the full list of elements and then walk through it: the "$s->each" handles one element at a time. Analogously to using normal "each(%hash)" in scalar context, using "$s->each" has the following caveats:
Cartesian Product and Power Set
Customising DisplayIf you want to customise the display routine you will have to modify the "as_string" callback. You can modify it either for all sets by using "as_string_callback()" as a class method:my $class_callback = sub { ... }; Set::Scalar->as_string_callback($class_callback); or for specific sets by using "as_string_callback()" as an object method: my $callback = sub { ... }; $s1->as_string_callback($callback); $s2->as_string_callback($callback); The anonymous subroutine gets as its first (and only) argument the set to display as a string. For example to display the set $s as "a-b-c-d-e" instead of "(a b c d e)" $s->as_string_callback(sub{join("-",sort $_[0]->elements)}); If called without an argument, the current callback is returned. If called as a class method with undef as the only argument, the original callback (the one returning "(a b c d e)") for all the sets is restored, or if called for a single set the callback is removed (and the callback for all the sets will be used). CAVEATSThe first priority of Set::Scalar is to be a convenient interface to sets. While not designed to be slow or big, neither has it been designed to be fast or compact.Using references (or objects) as set members has not been extensively tested. The desired semantics are not always clear: what should happen when the elements behind the references change? Especially unclear is what should happen when the objects start having their own stringification overloads. SEE ALSOSet::Bag for bags (multisets, counted sets), and Bit::Vector for fast set operations (you have to take care of the element name to bit number and back mappings yourself), or Set::Infinite for sets of intervals, and many more. CPAN is your friend.AUTHORJarkko Hietaniemi <jhi@iki.fi> David Oswald <davido@cpan.org> is the current maintainer. The GitHub repo is at <https://github.com/daoswald/Set-Scalar>COPYRIGHT AND LICENSECopyright 2001,2002,2003,2004,2005,2007,2009,2013 by Jarkko HietaniemiThis library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Visit the GSP FreeBSD Man Page Interface. |