txt: ## setty.md
  role Setty
  
  Collection of distinct objects
  
  ```raku
  role Setty does QuantHash { }
  ```
  
  A role for collections which make sure that each element can only appear once. See [`Set`](/type/Set) and [`SetHash`](/type/SetHash).
  
  # [Methods](#role_Setty "go to top of document")[§](#Methods "direct link")
  
  ## [method new-from-pairs](#role_Setty "go to top of document")[§](#method_new-from-pairs "direct link")
  
  ```raku
  method new-from-pairs(*@pairs --> Setty:D)
  ```
  
  Constructs a Setty object from a list of [`Pair` objects](/type/Pair) given as positional arguments:
  
  ```raku
  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.
  
  ## [method grab](#role_Setty "go to top of document")[§](#method_grab "direct link")
  
  ```raku
  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.
  
  ## [method grabpairs](#role_Setty "go to top of document")[§](#method_grabpairs "direct link")
  
  ```raku
  method grabpairs($count = 1)
  ```
  
  Removes `$count` elements chosen at random (without repetition) from the set, and returns a list of [`Pair`](/type/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`](/type/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.
  
  ## [method pick](#role_Setty "go to top of document")[§](#method_pick "direct link")
  
  ```raku
  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).
  
  ## [method pickpairs](#role_Setty "go to top of document")[§](#method_pickpairs "direct link")
  
  ```raku
  multi method pickpairs(Setty:D: --> Pair:D)
  multi method pickpairs(Setty:D: $count --> Seq:D)
  ```
  
  Returns a [`Pair`](/type/Pair) or a [`Seq`](/type/Seq) of [`Pair`](/type/Pair)s depending on the candidate of the method being invoked. Each [`Pair`](/type/Pair) returned has an element of the invocant as its key and `True` as its value. In contrast to [grabpairs](#method_grabpairs), the elements are 'picked' without replacement.
  
  If `*` is passed as `$count`, or `$count` is greater than or equal to the number of [elements](#method_elems) of the invocant, then all element/`True` [`Pair`](/type/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.
  
  ```raku
  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)␤»
  ```
  
  ## [method roll](#role_Setty "go to top of document")[§](#method_roll "direct link")
  
  ```raku
  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.
  
  ## [method antipairs](#role_Setty "go to top of document")[§](#method_antipairs "direct link")
  
  ```raku
  multi method antipairs(Setty:D: --> Seq:D)
  ```
  
  Returns all elements in the set and `True` as a [`Seq`](/type/Seq) of [`Pair`](/type/Pair)s, where the element itself is the value, i.e. the opposite of method `pairs`.
  
  ```raku
  my $s = Set.new(1, 2, 3, 1);
  say $s.antipairs.sort;                            # OUTPUT: «(True => 1 True => 2 True => 3)␤»
  ```
  
  ## [method keys](#role_Setty "go to top of document")[§](#method_keys "direct link")
  
  ```raku
  multi method keys(Setty:D: --> Seq:D)
  ```
  
  Returns a [`Seq`](/type/Seq) of all elements of the set.
  
  ```raku
  my $s = Set.new(1, 2, 3);
  say $s.keys;                                      # OUTPUT: «(3 1 2)␤»
  ```
  
  ## [method values](#role_Setty "go to top of document")[§](#method_values "direct link")
  
  ```raku
  multi method values(Setty:D: --> Seq:D)
  ```
  
  Returns a [`Seq`](/type/Seq) containing as many `True` values as the set has elements.
  
  ```raku
  my $s = Set.new(1, 2, 3);
  say $s.values;                                    # OUTPUT: «(True True True)␤»
  ```
  
  ## [method kv](#role_Setty "go to top of document")[§](#method_kv "direct link")
  
  ```raku
  multi method kv(Setty:D: --> Seq:D)
  ```
  
  Returns a [`Seq`](/type/Seq) of the set's elements and `True` values interleaved.
  
  ```raku
  my $s = Set.new(1, 2, 3);
  say $s.kv;                                        # OUTPUT: «(3 True 1 True 2 True)␤»
  ```
  
  ## [method elems](#role_Setty "go to top of document")[§](#method_elems "direct link")
  
  ```raku
  method elems(Setty:D: --> Int)
  ```
  
  The number of elements of the set.
  
  ## [method total](#role_Setty "go to top of document")[§](#method_total "direct link")
  
  ```raku
  method total(Setty:D: --> Int)
  ```
  
  The total of all the values of the [`QuantHash`](/type/QuantHash) object. For a `Setty` object, this is just the number of elements.
  
  ## [method minpairs](#role_Setty "go to top of document")[§](#method_minpairs "direct link")
  
  ```raku
  multi method minpairs(Setty:D: --> Seq:D)
  ```
  
  Returns the value of [`self.pairs`](/routine/pairs) (as all Pairs have minimum values). See also [`Any.minpairs`](/routine/minpairs)
  
  ## [method maxpairs](#role_Setty "go to top of document")[§](#method_maxpairs "direct link")
  
  ```raku
  multi method maxpairs(Setty:D: --> Seq:D)
  ```
  
  Returns the value of [`self.pairs`](/routine/pairs) (as all Pairs have maximum values). See also [`Any.maxpairs`](/routine/maxpairs)
  
  ## [method default](#role_Setty "go to top of document")[§](#method_default "direct link")
  
  ```raku
  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`](/type/Nil) or `False`.
  
  ```raku
  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␤»
  ```
  
  ## [method ACCEPTS](#role_Setty "go to top of document")[§](#method_ACCEPTS "direct link")
  
  ```raku
  method ACCEPTS($other)
  ```
  
  Returns `True` if `$other` and `self` contain all the same elements, and no others.
  
  ## [method Bag](#role_Setty "go to top of document")[§](#method_Bag "direct link")
  
  ```raku
  method Bag(Setty:D: --> Bag:D)
  ```
  
  Returns a [`Bag`](/type/Bag) containing the elements of the invocant.
  
  ```raku
  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:
  
  ```raku
  say (1,2,3).Bag{1};                              # OUTPUT: «1␤»
  ```
  
  ## [method BagHash](#role_Setty "go to top of document")[§](#method_BagHash "direct link")
  
  ```raku
  method BagHash(Setty:D: --> BagHash:D)
  ```
  
  Returns a [`BagHash`](/type/BagHash) containing the elements of the invocant.
  
  ```raku
  my BagHash $b = Set.new(1, 2, 3).BagHash;
  say $b;                                           # OUTPUT: «BagHash(1 2 3)␤»
  ```
  
  ## [method Bool](#role_Setty "go to top of document")[§](#method_Bool "direct link")
  
  ```raku
  multi method Bool(Setty:D: --> Bool:D)
  ```
  
  Returns `True` if the invocant contains at least one element.
  
  ```raku
  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␤»
  ```
  
  ## [method Mix](#role_Setty "go to top of document")[§](#method_Mix "direct link")
  
  ```raku
  method Mix(Setty:D: --> Mix:D)
  ```
  
  Returns a [`Mix`](/type/Mix) containing the elements of the invocant.
  
  ```raku
  my Mix $b = Set.new(1, 2, 3).Mix;
  say $b;                                           # OUTPUT: «Mix(3 1 2)␤»
  ```
  
  The elements of the returned [`Mix`](/type/Mix) will have weights equal to 1:
  
  ```raku
  say (1,2,3).Mix{3};                               # OUTPUT: «1␤»
  ```
  
  ## [method MixHash](#role_Setty "go to top of document")[§](#method_MixHash "direct link")
  
  ```raku
  method MixHash(Setty:D: --> MixHash:D)
  ```
  
  Returns a [`MixHash`](/type/MixHash) containing the elements of the invocant.
  
  ```raku
  my MixHash $b = Set.new(1, 2, 3).MixHash;
  say $b;                                           # OUTPUT: «MixHash(1 2 3)␤»
  ```
  
  # [See Also](#role_Setty "go to top of document")[§](#See_Also "direct link")
  
  [Sets, Bags, and Mixes](/language/setbagmix)
  
  # [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")
  
  Type relations for `Setty`
  
  
  
  raku-type-graph
  
  
  
  Setty
  Setty
  
  
  QuantHash
  QuantHash
  
  
  Setty->QuantHash
  
  
  
  Associative
  Associative
  
  
  QuantHash->Associative
  
  
  
  Mu
  Mu
  
  
  Any
  Any
  
  
  Any->Mu
  
  
  
  Set
  Set
  
  
  Set->Setty
  
  
  
  Set->Any
  
  
  
  SetHash
  SetHash
  
  
  SetHash->Setty
  
  
  
  SetHash->Any
  
  [Expand chart above](/assets/typegraphs/Setty.svg)
  