# parsefail :(

sub ∅ returns Set { set(); }

NAME

Set - Sets for Perl 6

SYNOPSIS

  # WARNING - this manual page contains substantial use of Unicode
  # characters.  They may not be rendered correctly.  ASCII versions
  # are supplied nearby.
  use Set;

  my $set = set 23, 42, $some_object;

  say "42 is in the set" if $set.includes(42);
  say "The set contains {$set.size} items";

  $set.insert(13);
  $set.remove(23);

  my @members = $set.members;

  # various common set operations
  my $set2 = set(1..10);

  # various set operations
  my $union        = $set ∪ $set2;  # or "+"
  my $intersection = $set ∩ $set2;  # or "*"
  my $difference   = $set ∖ $set2;  # or "-"

  # symmetric difference doesn't have a maths operator
  my $sym_difference = $set % $set2;

  # same as
  $sym_difference = ( $set ∖ $set2 ) ∪ ( $set2 ∖ $set );
  $sym_difference = ( $set - $set2 ) + ( $set2 - $set );

  # sets support subset, superset, etc operators
  my $is_proper_superset = $set ⊃ $set2;  # or ">"
  my $is_proper_subset   = $set ⊂ $set2;  # or "<"
  my $is_superset        = $set ⊇ $set2;  # or ">="
  my $is_subset          = $set ⊆ $set2;  # or "<="

  # other comparison operators available: ⊄, ⊅, ⊈, ⊉
  # ⊊ is the same as ⊂, and ⊋ is the same as ⊃

  # to test membership
  my $contains_7  = $set2 ∋ 7;  # or  7 ∈ $set2
  my $contains_11 = $set2 ∌ 11; # or 11 ¬in; $set2

  # smartmatch may also be used
  $contains_7     = $set2 ~~ 7;

  # Set arithmetic with arrays
  say ~([1,2,3] +# [1,2,6])    # 1 2 3 6  (in no particular order)
  say ~([1,2,3] -# [1,2,6])    # 3        (in no particular order)
  say ~([1,2,3] *# [1,2,6])    # 1 2      (in no particular order)
  say ~([1,2,3] %# [1,2,6])    # 3 6      (in no particular order)

CONSTRUCTORS

set(...)

Returns a new set containing all parameters.

Set.new()

Returns a new, empty set.

∅

Also returns a new, empty set.

METHODS

$set.insert(...)

Inserts the specifiend items into the set. Returns the number of items inserted.

It is not fatal to insert an item which is already inserted. In fact, this is commonly used for directed graph traversal;

  my @to_do = ($object);
  my $seen = set(@to_do);

  while my $item = @to_do.shift {

      # ... do something with $item ...

      if ($item.isa(Container)) {
          @to_do.push($item.members.grep:{ $seen.insert($_) });
      }
  }

You can also use the `+=' operator to add new values into a set;

  $set += (1,2,3,4);

Note that in this instance, the information about how many members were actually new is discarded.

$set.remove(...)

Removes the specified items from the set. Returns the number of items removed.

It is not fatal to remove an item which is not in the set.

$set.includes(...), $set.has(...)

Returns true if all given items are in the set. has is an alias for includes.

$set ~~ $item, $item ~~ $set

Operator version of .includes().

$set ∋ $item, $item ∈ $set

Unicode versions of .includes().

$set ∌ $item, $item ¬in; $set

Complemented unicode versions of .includes().

$set.member($item)

Returns the specified item if it's in the set.

$set.size(), $set.count()

Returns the number of elements in the set. count is an alias for size.

$set.invert(...)

Removes the given items if they are already in the set, or inserts the items if they're not in the set.

Returns the number of items removed.

$set.clear()

Clears the set.

COMPARISION METHODS

$set1.equal($set2)

$set1 == $set2

Returns true if $set1 equals $set2, i.e. if $set1 contains all the items of $set2 and $set1 and $set2 have the same size.

$set1.not_equal($set2)

$set1 != $set2

$set1 ≠ $set2

Returns true if $set1 does not equal $set2.

$set1.subset($set2)

$set1 <= $set2)

$set1 ⊆ $set2)

Returns true if $set1 is a subset of $set2.

$set1.superset($set2)

$set1 >= $set2)

$set1 ⊇ $set2

Returns true if $set1 is a superset of $set2.

$set1.proper_subset($set2)

$set1 ⊂ $set2

$set1 ⊊ $set2

$set1 < $set2)

$set1.proper_superset($set2)

$set1 ⊃ $set2

$set1 ⊋ $set2

$set1 > $set2)

Returns true if $set1 is a proper subset (superset) of $set2, i.e. if $set1 has at least one element less (more) than $set2.

$set1.union($set2)

$set1 ∪ $set2

$set1 + $set2

Returns a new set containing all the elements of $set1 and $set2

$set1.intersection($set2)

$set1 ∩ $set2

$set1 * $set2

Returns a new set containing all the elements of $set1 which are in $set2, too.

$set1.difference($set2)

$set1 ∖ $set2

$set1 * $set2

Returns a new set containing all the elements of $set1 which are not in $set2. Note that "∖" (\x{2216} - set minus) is not the same character as "\" (\x{005C} - backslash).

$set1.symmetric_difference($set2)

$set1 % $set2

Returns all items that are only in one of the two sets. This is equivalent to any of the below:

   ( $set1 ∪ $set2 ) ∖ ( $set1 ∩ $set2 )
   ( $set1 ∖ $set2 ) ∪ ( $set2 ∖ $set1 )

   ( $set1 + $set2 ) - ( $set1 * $set2 )
   ( $set1 - $set2 ) + ( $set2 - $set1 )

BUGS

Currently, no operators are overloaded. This will change as soon Pugs supports overload operators.

AUTHORS

Sam "mugwump" Vilain (Code)

Ingo "iblech" Blechschmidt (Documentation)

Stevan "stevan" Little (misc. ugly hacks to make things work for now)

SEE ALSO

You might want to read the tests of Set.

cpanm Perl6::Pugs

perl -MCPAN -e shell
install Perl6::Pugs