role Mixy

Collection of distinct objects with Real weights

A role for collections of weighted values. See Mix and MixHash. `Mixy` objects differ from Baggy objects in that the weights of `Mixy` are Reals rather than Ints.

Methods

method total

Returns the sum of all the weights

method roll

Similar to a Bag.roll, but with `Real` weights rather than integral ones.

Sets, Bags, and Mixes

Routines supplied by role Baggy

Mixy does role Baggy, which provides the following routines:

(Baggy) method new-from-pairs

Defined as:

Constructs a Baggy objects from a list of `Pair` objects given as positional arguments:

Note: be sure you aren't accidentally passing the Pairs as positional arguments; the quotes around the keys in the above example are significant.

(Baggy) method grab

Defined as:

Like pick, a `grab` returns a random selection of elements, weighted by the values corresponding to each key. Unlike `pick`, it works only on mutable structures, e.g. BagHash. Use of `grab` on an immutable structure results in an `X::Immutable` exception. If `*` is passed as `\$count`, or `\$count` is greater than or equal to the total of the invocant, then `total` elements from the invocant are returned in a random sequence; i.e. they are returned shuffled.

Grabbing decrements the grabbed key's weight by one (deleting the key when it reaches 0). By definition, the `total` of the invocant also decreases by one, so the probabilities stay consistent through subsequent `grab` operations.

(Baggy) method grabpairs

Defined as:

Returns a `Pair` or a `Seq` of `Pair`s depending on the version of the method being invoked. Each `Pair` returned has an element of the invocant as its key and the elements weight as its value. Unlike pickpairs, it works only on mutable structures, e.g. BagHash. Use of `grabpairs` on 'an immutable structure results in an `X::Immutable` exception. If `*` is passed as `\$count`, or `\$count` is greater than or equal to the number of elements of the invocant, then all element/weight `Pair`s from the invocant are returned in a random sequence.

What makes `grabpairs` different from pickpairs is that the 'grabbed' elements are in fact removed from the invocant.

(Baggy) method pick

Defined as:

Like an ordinary list pick, but returns keys of the invocant weighted by their values, as if the keys were replicated the number of times indicated by the corresponding value and then list pick used. The underlying metaphor for picking is that you're pulling colored marbles out a bag. (For "picking with replacement" see roll instead). If `*` is passed as `\$count`, or `\$count` is greater than or equal to the total of the invocant, then `total` elements from the invocant are returned in a random sequence.

Note that each `pick` invocation maintains its own private state and has no effect on subsequent `pick` invocations.

(Baggy) method pickpairs

Defined as:

Returns a `Pair` or a `Seq` of `Pair`s depending on the version of the method being invoked. Each `Pair` returned has an element of the invocant as its key and the elements weight as its value. 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/weight `Pair`s from the invocant are returned in a random sequence.

Note that each `pickpairs` invocation maintains its own private state and has no effect on subsequent `pickpairs` invocations.

(Baggy) method roll

Defined as:

Like an ordinary list roll, but returns keys of the invocant weighted by their values, as if the keys were replicated the number of times indicated by the corresponding value and then list roll used. The underlying metaphor for rolling is that you're throwing `\$count` dice that are independent of each other, which (in bag terms) is equivalent to picking a colored marble out your bag and then putting it back, and doing this `\$count` times. In dice terms, the number of marbles corresponds to the number of sides, and the number of marbles of the same color corresponds to the number of sides with the same color. (For "picking without replacement" see pick instead).

If `*` is passed to `\$count`, returns a lazy, infinite sequence of randomly chosen elements from the invocant.

(Baggy) method pairs

Defined as:

Returns all elements and their respective weights as a Seq of `Pair`s where the key is the element itself and the value is the weight of that element.

(Baggy) method antipairs

Defined as:

Returns all elements and their respective weights as a Seq of Pairs, where the element itself is the value and the weight of that element is the key, i.e. the opposite of method pairs.

(Baggy) method invert

Defined as:

Returns all elements and their respective weights as a Seq of Pairs, where the element itself is the value and the weight of that element is the key, i.e. the opposite of method pairs. Except for some esoteric cases `invert` on a Baggy type returns the same result as antipairs.

(Baggy) method classify-list

Defined as:

Populates a mutable `Baggy` by classifying the possibly-empty `@list` of values using the given `mapper`. The `@list` cannot be lazy.

The mapper can be a `Callable` that takes a single argument, an `Associative`, or an `Iterable`. With `Associative` and an `Iterable` mappers, the values in the `@list` represent the key and index of the mapper's value respectively. A `Callable` mapper will be executed once per each item in the `@list`, with that item as the argument and its return value will be used as the mapper's value.

The mapper's value is used as the key of the `Baggy` that will be incremented by `1`. See `.categorize-list` if you wish to classify an item into multiple categories at once.

Note: unlike the `Hash`'s `.classify-list`, returning an `Iterable` mapper's value will throw, as `Baggy` types do not support nested classification. For the same reason, `Baggy`'s `.classify-list` does not accept `:&as` parameter.

(Baggy) method categorize-list

Defined as:

Populates a mutable `Baggy` by categorizing the possibly-empty `@list` of values using the given `mapper`. The `@list` cannot be lazy.

The mapper can be a `Callable` that takes a single argument, an `Associative`, or an `Iterable`. With `Associative` and an `Iterable` mappers, the values in the `@list` represent the key and index of the mapper's value respectively. A `Callable` mapper will be executed once per each item in the `@list`, with that item as the argument and its return value will be used as the mapper's value.

The mapper's value is used as a possibly-empty list of keys of the `Baggy` that will be incremented by `1`.

Note: unlike the `Hash`'s `.categorize-list`, returning a list of `Iterables` as mapper's value will throw, as `Baggy` types do not support nested categorization. For the same reason, `Baggy`'s `.categorize-list` does not accept `:&as` parameter.

(Baggy) method keys

Defined as:

Returns a `Seq` of all keys in the `Baggy` object without taking their individual weights into account as opposed to kxxv.

(Baggy) method values

Defined as:

Returns a `Seq` of all values, i.e. weights, in the `Baggy` object.

(Baggy) method kv

Defined as:

Returns a `Seq` of keys and values interleaved.

(Baggy) method kxxv

Defined as:

Returns a `Seq` of the keys of the invocant, with each key multiplied by its weight. Note that `kxxv` only works for `Baggy` types which have integer weights, i.e. Bag and BagHash.

(Baggy) method elems

Defined as:

Returns the number of elements in the `Baggy` object without taking the individual elements weight into account.

(Baggy) method total

Defined as:

Returns the sum of weights for all elements in the `Baggy` object.

Defined as:

Returns zero.

(Baggy) method hash

Defined as:

Returns a Hash where the elements of the invocant are the keys and their respective weights the values.

(Baggy) method Bool

Defined as:

Returns `True` if the invocant contains at least one element.

(Baggy) method Set

Defined as:

Returns a Set whose elements are the keys of the invocant.

(Baggy) method SetHash

Defined as:

Returns a SetHash whose elements are the keys of the invocant.

(Baggy) method ACCEPTS

Defined as:

Used in smartmatching if the right-hand side is a `Baggy`.

If the right-hand side is the type object, i.e. `Baggy`, the method returns `True` if `\$other` does `Baggy` otherwise `False` is returned.

If the right-hand side is a `Baggy` object, `True` is returned only if `\$other` has the same elements, with the same weights, as the invocant.

Routines supplied by role QuantHash

Mixy does role QuantHash, which provides the following routines:

(QuantHash) 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

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

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

Returns the type of value a key of this `QuantHash` may have. This is typically Mu.

(QuantHash) method 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.

(QuantHash) method 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.

(QuantHash) method Mixy

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

Routines supplied by role Associative

Mixy does role Associative, which provides the following routines:

(Associative) method of

Defined as:

`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.

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

(Associative) method keyof

Defined as:

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.

(Associative) method AT-KEY

Should return the value / container at the given key.

(Associative) method EXISTS-KEY

Should return a `Bool` indicating whether the given key actually has a value.

(Associative) method STORE

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

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.