class SetHash does Setty { }

A SetHash is a mutable set, meaning a collection of distinct elements in no particular order. (For immutable sets, see Set 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 $fruits = <peach apple orange apple apple>.SetHash;
 
say $fruits.elems;      # OUTPUT: «3␤» 
say $fruits.keys.sort;  # OUTPUT: «apple orange peach␤» 

Just like Sets, SetHashes 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 $fruits = <peach apple orange apple apple>.SetHash;
 
say $fruits<apple>;     # OUTPUT: «True␤» 
say $fruits<kiwi>;      # OUTPUT: «False␤» 

Unlike Sets, SetHashes are mutable. You can add an item or list of items to the SetHash with the set method and can remove an item or list of items with the unset method:

my $fruits = <peach>.SetHash;
$fruits.set('apple');
say $fruits;            # OUTPUT: «SetHash(apple peach)␤» 
 
$fruits.unset('peach');
say $fruits;            # OUTPUT: «SetHash(apple)␤» 
 
$fruits.set(<kiwi banana apple>);
say $fruits;            # OUTPUT: «SetHash(apple banana kiwi)␤» 
 
$fruits.unset(<apple banana kiwi>);
say $fruits;            # OUTPUT: «SetHash()␤» 

Be careful not to confuse the set method, which adds an item to a SetHash with the Set method, which converts the mutable SetHash into an immutable Set.

As an alternative to using the set and unset methods, you can also add or remove set elements by assigning a value that boolifies to True or False, respectively:

my $fruits = <peach apple orange>.SetHash;
 
$fruits<apple kiwi> = False, True;
say $fruits.keys.sort;  # OUTPUT: «kiwi orange peach␤» 

Here is a convenient shorthand idiom for adding and removing SetHash elements using assignment:

my SetHash $fruits .= new;
say $fruits<cherry>;      # OUTPUT: «False␤» 
$fruits<cherry>++;
say $fruits<cherry>;      # OUTPUT: «True␤» 
$fruits<apple banana kiwi>»++; # Add multiple elements 
 
$fruits<cherry>--;
say $fruits<cherry>;      # OUTPUT: «False␤» 
$fruits<banana kiwi>»--; # Remove multiple elements 
 

Creating SetHash objects §

SetHashes can be composed using SetHash.new. Any positional parameters, regardless of their type, become elements of the set:

my $n = SetHash.new: "zero" => 0, "one" => 1, "two" => 2;
say $n.keys.raku;        # OUTPUT: «(:two(2), :zero(0), :one(1)).Seq␤» 
say $n.keys.map(&WHAT);  # OUTPUT: «((Pair) (Pair) (Pair))␤»

Alternatively, the .SetHash coercer (or its functional form, SetHash()) can be called on an existing object to coerce it to a SetHash. 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 $n = ("zero" => 0, "one" => 1, "two" => 2).SetHash;
say $n.keys.raku;        # OUTPUT: «("one", "two").Seq␤» 
say $n.keys.map(&WHAT);  # OUTPUT: «((Str) (Str))␤»

It is also possible to initialize a single key with the use of {}:

my $sh = SetHash.new;
$sh{ 'key1' } = True;
$sh{ 'key2' } = 'Hello World!';
$sh{ 'key3' } = 0;  # does not store the key since 0.Bool is False 
say $sh;            # OUTPUT: «SetHash(key1 key2)␤» 
say $sh.keys.raku;  # OUTPUT: «("key1", "key2").Seq␤»

or, in order to initialize more than one key at the same time, use a list assignment:

my $sh = SetHash.new;
$sh{ 'a', 'b', 'c' } = True, False, True;
say $sh.keys.raku;  # OUTPUT: «("a", "c").Seq␤»

You can also create SetHash masquerading as a hash by using the is trait:

my %sh is SetHash = <a b c>;
say %sh<a>;  # True 
say %sh<d>;  # False

Since 6.d (2019.03 and later) it is also possible to specify the type of values you would like to allow in a SetHash. This can either be done when calling .new:

# only allow Pairs 
my $n = SetHash[Pair].new: "zero" => 0, "one" => 1, "two" => 2;

or using the masquerading syntax:

# only allow strings 
my %sh is SetHash[Str] = <a b c>;
say %sh<a>;  # True 
say %sh<d>;  # False 
 
# only allow whole numbers 
my %sh is SetHash[Int] = <a b c>;
# Type check failed in binding; expected Int but got Str ("a")

Operators §

See Operators with set semantics for a complete list of "set operators" applicable to, among other types, SetHash.

Examples:

my ($a, $b) = SetHash.new(1, 2, 3), SetHash.new(2, 4);
 
say $a (<) $b;  # OUTPUT: «False␤» 
say $a (&) $b;  # OUTPUT: «SetHash(2)␤» 
say $a (^) $b;  # OUTPUT: «SetHash(1 3 4)␤» 
say $a (|) $b;  # OUTPUT: «SetHash(1 2 3 4)␤» 
 
# Unicode versions: 
say $a ⊂ $b;  # OUTPUT: «False␤» 
say $a ∩ $b;  # OUTPUT: «SetHash(2)␤» 
say $a ⊖ $b;  # OUTPUT: «SetHash(1 3 4)␤» 
say $a ∪ $b;  # OUTPUT: «SetHash(1 2 3 4)␤» 

Methods §

method set §

Defined as:

method set(SetHash:D: \to-set --> Nil)

When given single key, set adds it to the SetHash. When given a List, Array, Seq, or any other type that does the Iterator Role, set adds each element of the Iterator as key to the SetHash.

Note: since version 2020.02.

method unset §

Defined as:

method unset(SetHash:D: \to-unset --> Nil)

When given single key, unset removes it from the SetHash. When given a List, Array, Seq, or any other type that does the Iterator Role, unset removes each element of the Iterator from the SetHash (if it was present as a key).

Note: since version 2020.02.

See Also §

Sets, Bags, and Mixes

Type Graph §

Routines supplied by role Setty §

SetHash does role Setty, which provides the following routines:

(Setty) method new-from-pairs §

Defined as:

method new-from-pairs(*@pairs --> Setty:D)

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($count = 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($count = 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 Pairs 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($count = 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:D: --> Pair:D)
multi method pickpairs(Setty:D: $count --> Seq:D)

Returns a Pair or a Seq of Pairs 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 Pairs 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 $numbers = set (4, 2, 3);
say $numbers.pickpairs;                           # OUTPUT: «4 => True␤» 
say $numbers.pickpairs(1);                        # OUTPUT: «(3 => True)␤» 
say $numbers.pickpairs(*);                        # OUTPUT: «(2 => True 4 => True 3 => True)␤»

(Setty) method roll §

multi method roll($count = 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:D: --> Seq:D)

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 $s = Set.new(1, 2, 3, 1);
say $s.antipairs.sort;                            # OUTPUT: «(True => 1 True => 2 True => 3)␤»

(Setty) method keys §

Defined as:

multi method keys(Setty:D: --> Seq:D)

Returns a Seq of all elements of the set.

my $s = Set.new(1, 2, 3);
say $s.keys;                                      # OUTPUT: «(3 1 2)␤»

(Setty) method values §

Defined as:

multi method values(Setty:D: --> Seq:D)

Returns a Seq containing as many True values as the set has elements.

my $s = Set.new(1, 2, 3);
say $s.values;                                    # OUTPUT: «(True True True)␤»

(Setty) method kv §

Defined as:

multi method kv(Setty:D: --> Seq:D)

Returns a Seq of the set's elements and True values interleaved.

my $s = Set.new(1, 2, 3);
say $s.kv;                                        # OUTPUT: «(3 True 1 True 2 True)␤»

(Setty) method elems §

method elems(Setty:D: --> Int)

The number of elements of the set.

(Setty) method total §

method total(Setty:D: --> 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:D: --> Seq:D)

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:D: --> Seq:D)

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 $s1 = SetHash.new(1, 2, 3);
say $s1{2};                                           # OUTPUT: «True␤» 
$s1{2} = Nil;
say $s1{2};                                           # OUTPUT: «False␤» 
# access non initialized element 
say $s1{4};                                           # OUTPUT: «False␤»

(Setty) method ACCEPTS §

method ACCEPTS($other)

Returns True if $other and self contain all the same elements, and no others.

(Setty) method Bag §

Defined as:

method Bag(Setty:D: --> Bag:D)

Returns a Bag containing the elements of the invocant.

my Bag $b = Set.new(1, 2, 3).Bag;
say $b;                                           # OUTPUT: «Bag(3 1 2)␤»

The quantity of the elements in this created bag will be set to one:

say (1,2,3).Bag{1};                              # OUTPUT: «1␤»

(Setty) method BagHash §

Defined as:

method BagHash(Setty:D: --> BagHash:D)

Returns a BagHash containing the elements of the invocant.

my BagHash $b = Set.new(1, 2, 3).BagHash;
say $b;                                           # OUTPUT: «BagHash(1 2 3)␤»

(Setty) method Bool §

Defined as:

multi method Bool(Setty:D: --> Bool:D)

Returns True if the invocant contains at least one element.

my $s1 = Set.new(1, 2, 3);
say $s1.Bool;                                     # OUTPUT: «True␤» 
 
my $s2 = $s1 ∩ Set.new(4, 5);                     # set intersection operator 
say $s2.Bool;                                     # OUTPUT: «False␤»

(Setty) method Mix §

Defined as:

method Mix(Setty:D: --> Mix:D)

Returns a Mix containing the elements of the invocant.

my Mix $b = Set.new(1, 2, 3).Mix;
say $b;                                           # OUTPUT: «Mix(3 1 2)␤»

The elements of the returned Mix will have weights equal to 1:

say (1,2,3).Mix{3};                               # OUTPUT: «1␤»

(Setty) method MixHash §

Defined as:

method MixHash(Setty:D: --> MixHash:D)

Returns a MixHash containing the elements of the invocant.

my MixHash $b = Set.new(1, 2, 3).MixHash;
say $b;                                           # OUTPUT: «MixHash(1 2 3)␤»

Routines supplied by role QuantHash §

SetHash 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 subclass of QuantHash may have. This is typically Mu, which is also the default for punned QuantHashes.

(QuantHash) method Capture §

Defined as

method Capture()

Returns the object as a Capture by previously coercing it to a Hash.

(QuantHash) method list §

Defined as:

multi method list(QuantHash:D:)

Returns a list of Pair objects of all keys and values in the QuantHash.

(QuantHash) method Setty §

method Setty(--> Setty:D)

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 %b is Bag = one => 1, two => 2;
say %b.Setty; # OUTPUT: «Set(one two)␤» 
my %m is Mix = one => 1, minus => -1;
say %m.Setty; # OUTPUT: «Set(one)␤»

(QuantHash) method Baggy §

method Baggy(--> Baggy:D)

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 %s is Set = <one two>;
say %s.Baggy; # OUTPUT: «Bag(one two)␤» 
my %m is Mix = one => 1, minus => -1;
say %m.Baggy; # OUTPUT: «Bag(one)␤»

(QuantHash) method Mixy §

method Mixy(--> Mixy:D)

Coerce the QuantHash object to the equivalent object that uses the Mixy role.

my %s is Set = <one two>;
say %s.Mixy; # OUTPUT: «Mix(one two)␤» 
my %b is Bag = one => 1, two => 2;
say %b.Mixy; # OUTPUT: «Mix(one two(2))␤»

Routines supplied by role Associative §

SetHash does role Associative, which provides the following routines:

(Associative) method of §

Defined as:

method of()

Associative, as the definition above shows, 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 the key to Str and uses a very generic Mu for value.

my %any-hash;
say %any-hash.of; # OUTPUT: «(Mu)␤»

The value is the first parameter you use when instantiating Associative with particular classes:

class DateHash is Hash does Associative[Cool,DateTime] {};
my %date-hash := DateHash.new;
say %date-hash.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 %any-hash;
%any-hash.keyof; # OUTPUT: «(Str(Any))␤»

(Associative) method AT-KEY §

method AT-KEY(\key)

Should return the value / container at the given key.

class What { method AT-KEY(\key) { 42 }};
say What.new{33}; # OUTPUT: «42␤» 

(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, :$INITIALIZE)

This method should only be supplied if you want to support the:

my %h 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 Pairs, 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.