class Set
Immutable collection of distinct objects
does Setty
A Set
is an immutable set, meaning a collection of distinct elements in no particular order. (For mutable sets, see SetHash instead.)
Objects/values of any type are allowed as set elements. Within a Set
, every element is guaranteed to be unique (in the sense that no two elements would compare positively with the === operator):
my = set <peach apple orange apple apple>;say .elems; # OUTPUT: «3»say .keys.sort; # OUTPUT: «apple orange peach»
Set
s can be treated as object hashes using the { }
postcircumfix operator, which returns the value True
for keys that are elements of the set, and False
for keys that aren't:
my = set <peach apple orange apple apple>;say <apple>; # OUTPUT: «True»say <kiwi>; # OUTPUT: «False»
Creating Set
objects
Set
s can be composed using the set subroutine (or Set.new
, for which it is a shorthand). Any positional parameters, regardless of their type, become elements of the set:
my = set "zero" => 0, "one" => 1, "two" => 2;say .keys.perl; # OUTPUT: «(:two(2), :zero(0), :one(1)).Seq»say .keys.map(); # OUTPUT: «((Pair) (Pair) (Pair))»
Alternatively, the .Set
coercer (or its functional form, Set()
) can be called on an existing object to coerce it to a Set
. Its semantics depend on the type and contents of the object. In general it evaluates the object in list context and creates a set with the resulting items as elements, although for Hash-like objects or Pair items, only the keys become elements of the set - and keys mapped to values which boolify to False
are skipped:
my = ("zero" => 0, "one" => 1, "two" => 2).Set;say .keys.perl; # OUTPUT: «("one", "two").Seq»say .keys.map(); # OUTPUT: «((Str) (Str))»
Furthermore, you can get a Set
by using set operators (see next section) on objects of other types such as List, which will act like they internally call .Set
on them before performing the operation. Be aware of the tight precedence of those operators though, which may require you to use parentheses around arguments:
say (1..5) (^) 4; # OUTPUT: «set(1, 2, 3, 5)»
Of course, you can also create a Set
with the .new
method.
my = Set.new( <peach apple orange apple apple> );
Since 6.d (2019.03 and later) you can also use this syntax for parameterization of the Set
, to specify which type of values are acceptable:
# only allow strings (Str) in the Setmy = Set[Str].new( <peach apple orange apple apple> );# only allow whole numbers (Int) in the Setmy = Set[Int].new( <peach apple orange apple apple> );# Type check failed in binding; expected Int but got Str ("peach")
Finally, you can create Set masquerading as a hash by using the is
trait:
my is Set = <a b c>;say <a>; # Truesay <d>; # False
Since 6.d (2019.03 and later), this syntax also allows you to specify the type of values you would like to allow:
# limit to stringsmy is Set[Str] = <a b c>;say <a>; # Truesay <d>; # False# limit to whole numbersmy is Set[Int] = <a b c>;# Type check failed in binding; expected Int but got Str ("a")
Operators
Perl 6 provides common set operators, which can take Set
s (or any other collections) as input, and return result sets as new Set
objects. For example:
my (, ) = set(1, 2, 3), set(2, 4);say (<) ; # OUTPUT: «False»say (&) ; # OUTPUT: «set(2)»say (^) ; # OUTPUT: «set(1, 3, 4)»# Unicode versions:say ⊂ ; # OUTPUT: «False»say ∩ ; # OUTPUT: «set(2)»say ⊖ ; # OUTPUT: «set(1, 3, 4)»
See Set/Bag Operators for a complete list of set operators with detailed explanations.
Subroutines
sub set
sub set(* --> Set)
Creates a Set
from the given @args
See Also
Type Graph
Routines supplied by role Setty
Set does role Setty, which provides the following routines:
(Setty) method new-from-pairs
Defined as:
method new-from-pairs(* --> Setty)
Constructs a Setty object from a list of Pair
objects given as positional arguments:
say Set.new-from-pairs: 'butter' => 0.22, 'salt' => 0, 'sugar' => 0.02;# OUTPUT: «set(butter, sugar)»
Note: be sure you aren't accidentally passing the Pairs as positional arguments; the quotes around the keys in the above example are significant.
(Setty) method grab
method grab( = 1)
Removes and returns $count
elements chosen at random (without repetition) from the set.
If *
is passed as $count
, or $count
is greater than or equal to the size of the set, then all its elements are removed and returned in random order.
Only works on mutable sets; When used on an immutable set, it results in an exception.
(Setty) method grabpairs
method grabpairs( = 1)
Removes $count
elements chosen at random (without repetition) from the set, and returns a list of Pair
objects whose keys are the grabbed elements and whose values are True
.
If *
is passed as $count
, or $count
is greater than or equal to the size of the set, then all its elements are removed and returned as Pair
s in the aforementioned way in random order.
Only works on mutable sets; When used on an immutable set, it results in an exception.
(Setty) method pick
multi method pick( = 1)
Returns $count
elements chosen at random (without repetition) from the set.
If *
is passed as $count
, or $count
is greater than or equal to the size of the set, then all its elements are returned in random order (shuffled).
(Setty) method pickpairs
Defined as:
multi method pickpairs(Setty: --> Pair)multi method pickpairs(Setty: --> Seq)
Returns a Pair
or a Seq
of Pair
s depending on the candidate of the method being invoked. Each Pair
returned has an element of the invocant as its key and True
as its value. In contrast to grabpairs, the elements are 'picked' without replacement.
If *
is passed as $count
, or $count
is greater than or equal to the number of elements of the invocant, then all element/True
Pair
s from the invocant are returned in a random sequence; i.e. they are returned shuffled;
Note that each pickpairs
invocation maintains its own private state and has no effect on subsequent pickpairs
invocations.
my = set (4, 2, 3);say .pickpairs; # OUTPUT: «4 => True»say .pickpairs(1); # OUTPUT: «(3 => True)»say .pickpairs(*); # OUTPUT: «(2 => True 4 => True 3 => True)»
(Setty) method roll
multi method roll( = 1)
Returns a lazy list of $count
elements, each randomly selected from the set. Each random choice is made independently, like a separate die roll where each die face is a set element.
If *
is passed as $count
, the list is infinite.
(Setty) method antipairs
Defined as:
multi method antipairs(Setty: --> Seq)
Returns all elements in the set and True
as a Seq of Pairs, where the element itself is the value, i.e. the opposite of method pairs
.
my = Set.new(1, 2, 3, 1);say .antipairs.sort; # OUTPUT: «(True => 1 True => 2 True => 3)»
(Setty) method keys
Defined as:
multi method keys(Setty: --> Seq)
Returns a Seq of all elements of the set.
my = Set.new(1, 2, 3);say .keys; # OUTPUT: «(3 1 2)»
(Setty) method values
Defined as:
multi method values(Setty: --> Seq)
Returns a Seq containing as many True
values as the set has elements.
my = Set.new(1, 2, 3);say .values; # OUTPUT: «(True True True)»
(Setty) method kv
Defined as:
multi method kv(Setty: --> Seq)
Returns a Seq of the set's elements and True
values interleaved.
my = Set.new(1, 2, 3);say .kv; # OUTPUT: «(3 True 1 True 2 True)»
(Setty) method elems
method elems(--> Int)
The number of elements of the set.
(Setty) method total
method total(--> Int)
The total of all the values of the QuantHash
object. For a Setty
object, this is just the number of elements.
(Setty) method minpairs
Defined As:
multi method minpairs(Setty: --> Seq)
Returns the value of self.pairs
(as all Pairs have minimum values). See also Any.minpairs
(Setty) method maxpairs
Defined As:
multi method maxpairs(Setty: --> Seq)
Returns the value of self.pairs
(as all Pairs have maximum values). See also Any.maxpairs
(Setty) method default
Defined as:
method default(--> False)
Returns the default value of the invocant, i.e. the value which is returned when trying to access an element in the Setty
object which has not been previously initialized or when accessing an element which has explicitly been set to Nil
or False
.
my = SetHash.new(1, 2, 3);say ; # OUTPUT: «True»= Nil;say ; # OUTPUT: «False»# access non initialized elementsay ; # OUTPUT: «False»
(Setty) method ACCEPTS
method ACCEPTS()
Returns True
if $other
and self
contain all the same elements, and no others.
(Setty) method Bag
Defined as:
method Bag(Setty: --> Bag)
Returns a Bag containing the elements of the invocant.
my Bag = Set.new(1, 2, 3).Bag;say ; # OUTPUT: «bag(3, 1, 2)»
(Setty) method BagHash
Defined as:
method BagHash(Setty: --> BagHash)
Returns a BagHash containing the elements of the invocant.
my BagHash = Set.new(1, 2, 3).BagHash;say ; # OUTPUT: «BagHash.new(3, 1, 2)»
(Setty) method Bool
Defined as:
multi method Bool(Setty: --> Bool)
Returns True
if the invocant contains at least one element.
my = Set.new(1, 2, 3);say .Bool; # OUTPUT: «True»my = ∩ Set.new(4, 5); # set intersection operatorsay .Bool; # OUTPUT: «False»
(Setty) method Mix
Defined as:
method Mix(Setty: --> Mix)
Returns a Mix containing the elements of the invocant.
my Mix = Set.new(1, 2, 3).Mix;say ; # OUTPUT: «mix(3, 1, 2)»
(Setty) method MixHash
Defined as:
method MixHash(Setty: --> MixHash)
Returns a MixHash containing the elements of the invocant.
my MixHash = Set.new(1, 2, 3).MixHash;say ; # OUTPUT: «MixHash.new(3, 1, 2)»
Routines supplied by role QuantHash
Set does role QuantHash, which provides the following routines:
(QuantHash) method hash
method hash()
Coerces the QuantHash
object to a Hash (by stringifying the objects for the keys) with the values of the hash limited to the same limitation as QuantHash
, and returns that.
(QuantHash) method Hash
method Hash()
Coerces the QuantHash
object to a Hash (by stringifying the objects for the keys) without any limitations on the values, and returns that.
(QuantHash) method of
method of()
Returns the type of value a value of this QuantHash
may have. This is typically Bool for Setty, UInt for Baggy or Real for Mixy roles.
(QuantHash) method keyof
method keyof()
Returns the type of value a key of this QuantHash
may have. This is typically Mu.
(QuantHash) method Setty
method Setty(--> Setty)
Coerce the QuantHash
object to the equivalent object that uses the Setty role. Note that for Mixy type coercion items with negative values will be skipped.
my is Bag = one => 1, two => 2;say .Setty; # OUTPUT: «set(one two)»my is Mix = one => 1, minus => -1;say .Setty; # OUTPUT: «set(one)»
(QuantHash) method Baggy
method Baggy(--> Baggy)
Coerce the QuantHash
object to the equivalent object that uses the Baggy role. Note that for Mixy type coercion items with negative values will be skipped.
my is Set = <one two>;say .Baggy; # OUTPUT: «Bag(one, two)»my is Mix = one => 1, minus => -1;say .Baggy; # OUTPUT: «Bag(one)»
(QuantHash) method Mixy
method Mixy(--> Mixy)
Coerce the QuantHash
object to the equivalent object that uses the Mixy role.
my is Set = <one two>;say .Mixy; # OUTPUT: «Mix(one, two)»my is Bag = one => 1, two => 2;say .Mixy; # OUTPUT: «Mix(one, two)»
Routines supplied by role Associative
Set does role Associative, which provides the following routines:
(Associative) method of
Defined as:
method of()
Associative
is actually a parameterized role which can use different classes for keys and values. As seen at the top of the document, by default it coerces to Str
for the key and uses a very generic Mu
for value.
my ;say .of;# OUTPUT: «(Mu)»
The value is the first parameter you use when instantiating Associative
with particular classes:
is Hash does Associative[Cool,DateTime] ;my := DateHash.new;say .of; # OUTPUT: «(Cool)»
(Associative) method keyof
Defined as:
method keyof()
Returns the parameterized key used for the Associative role, which is Any
coerced to Str
by default. This is the class used as second parameter when you use the parameterized version of Associative.
my ;.keyof; #OUTPUT: «(Str(Any))»
(Associative) method AT-KEY
method AT-KEY(\key)
Should return the value / container at the given key.
(Associative) method EXISTS-KEY
method EXISTS-KEY(\key)
Should return a Bool
indicating whether the given key actually has a value.
(Associative) method STORE
method STORE(\values, :)
This method should only be supplied if you want to support the:
my is Foo = a => 42, b => 666;
syntax for binding your implementation of the Associative
role.
Should accept the values to (re-)initialize the object with, which either could consist of Pair
s, or separate key/value pairs. The optional named parameter will contain a True
value when the method is called on the object for the first time. Should return the invocant.