-
Notifications
You must be signed in to change notification settings - Fork 292
/
Baggy.pod
203 lines (129 loc) · 6.22 KB
/
Baggy.pod
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
=begin pod
=TITLE role Baggy
=SUBTITLE Collection of distinct weighted objects
class Baggy does QuantHash { }
A role for collections of weighted objects. See L<Bag>, L<BagHash>, and
L<Mixy>.
=head1 Methods
=head2 method grab
=comment TODO
=head2 method grabpairs
=comment TODO
=head2 method pick
Defined as:
multi method pick(Baggy:D:) returns Any
multi method pick(Baggy:D: $count) returns Seq:D
Like an ordinary list L<pick|/type/List#routine_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
L<roll|#method roll> instead). If C<*> is passed as C<$count>, or C<$count> is
greater than or equal to the L<total|#method total> of the invocant, then
C<total> elements from the invocant are returned in a random sequence.
Note that each C<pick> invocation maintains its own private state and has
no effect on subsequent C<pick> invocations.
my $breakfast = bag <eggs bacon bacon bacon>;
say $breakfast.pick; # eggs
say $breakfast.pick(2); # (eggs bacon)
say $breakfast.total; # 4
say $breakfast.pick(*); # (bacon bacon bacon eggs)
=head2 method pickpairs
Defined as:
multi method pickpairs(Baggy:D:) returns Pair:D
multi method pickpairs(Baggy:D: $count) returns List:D
Returns a C<Pair> or a C<List> of C<Pair>s depending on the version of the method
being invoked. Each C<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 C<*>
is passed as C<$count>, or C<$count> is greater than or equal to the number of
L<elements|#method elems> of the invocant, then all element/weight C<Pair>s from
the invocant are returned in a random sequence.
Note that each C<pickpairs> invocation maintains its own private state and has
no effect on subsequent C<pickpairs> invocations.
my $breakfast = bag <eggs bacon bacon bacon>;
say $breakfast.pickpairs; # eggs => 1
say $breakfast.pickpairs(1); # (bacon => 3)
say $breakfast.pickpairs(*); # (eggs => 1 bacon => 3)
=head2 method roll
Defined as:
multi method roll(Baggy:D:) returns Any:D
multi method roll(Baggy:D: $count) returns Seq:D
Like an ordinary list L<roll|/type/List#routine_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 C<$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
C<$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 L<pick|#method pick> instead).
If C<*> is passed to C<$count>, returns a lazy, infinite sequence of randomly
chosen elements from the invocant.
my $breakfast = bag <eggs bacon bacon bacon>;
say $breakfast.roll; # bacon
say $breakfast.roll(3); # (bacon eggs bacon)
my $random_dishes := $breakfast.roll(*);
say $random_dishes[^5]; # (bacon eggs bacon bacon bacon)
=head2 method classify-list
=comment TODO
=head2 method categorize-list
=comment TODO
=head2 method keys
Defined as:
method keys(Baggy:D:) returns List:D
Returns a list of all keys in the C<Baggy> object without taking
their individual weights into account as opposed to L<kxxv|#method kxxv>.
my $breakfast = bag <eggs spam spam spam>;
say $breakfast.keys.sort; # (eggs spam)
my $n = ("a" => 5, "b" => 2).BagHash;
say $n.keys.sort; # (a b)
=head2 method values
Defined as:
method values(Baggy:D:) returns List:D
Returns a list of all values, i.e. weights, in the C<Baggy> object.
my $breakfast = bag <eggs spam spam spam>;
say $breakfast.values.sort; # (1 3)
my $n = ("a" => 5, "b" => 2, "a" => 1).BagHash;
say $n.values.sort; # (2 6)
=head2 method kv
Defined as:
method kv(Baggy:D:) returns List:D
Returns a list of keys and values interleaved.
my $breakfast = bag <eggs spam spam spam>;
say $breakfast.kv; # (spam 3 eggs 1)
my $n = ("a" => 5, "b" => 2, "a" => 1).BagHash;
say $n.kv; # (a 6 b 2)
=head2 method kxxv
Defined as:
method kxxv(Baggy:D:) returns List:D
Returns a list of the keys of the invocant, with each key multiplied by its
weight. Note that C<kxxv> only works for C<Baggy> types which have integer
weights, i.e. L<Bag> and L<BagHash>.
my $breakfast = bag <spam eggs spam spam bacon>;
say $breakfast.kxxv.sort; # (bacon eggs spam spam spam)
my $n = ("a" => 0, "b" => 1, "b" => 2).BagHash;
say $n.kxxv; # (b b b)
=head2 method elems
Defined as:
method elems(Baggy:D:) returns Int:D
Returns the number of elements in the C<Baggy> object without
taking the individual elements weight into account.
my $breakfast = bag <eggs spam spam spam>;
say $breakfast.elems; # 2
my $n = ("b" => 9.4, "b" => 2).MixHash;
say $n.elems; # 1
=head2 method total
Defined as:
method total(Baggy:D:)
Returns the sum of weights for all elements in the C<Baggy>
object.
my $breakfast = bag <eggs spam spam bacon>;
say $breakfast.total; # 4
my $n = ("a" => 5, "b" => 1, "b" => 2).BagHash;
say $n.total; # 8
=head2 method ACCEPTS
=comment TODO
=head1 See Also
L<Sets, Bags, and Mixes|/language/setbagmix>
=end pod