ListTools
Deal
deal the elements of a 1-D container into a sequence of sub-containers with the number of elements in each sub-container differing by at most one
Calling Sequence
Parameters
Description
Examples
Compatibility
Deal( Container, numhands, handsreturned )
Container
-
any container (list, set, 1-D rtable), to be dealt into sub-containers
numhands
positive integer, specifying the target number of sub-containers
handsreturned
(optional) positive or negative integer, or list/set of positive or negative integers, specifying which hands are to be returned. The default is [seq(1..numhands)].
The command deals (in a manner analogous to a deck of cards) the elements of a container into a sequence of sub-containers with the number of elements in each sub-container differing by at most one.
As the name of the command suggests, elements of the original container are dealt one-by-one to each sub-container in order, and this process is repeated until no more elements remain.
If the specified number of sub-containers is greater than the number of elements in the original container, then the result is a sequence of sub-containers consisting of single elements, followed by empty sub-containers.
When the optional parameter handsreturned is passed, only the specified sub-containers are computed and returned. Note that an error will be thrown if 0, or any number larger than numhands or smaller than -numhands, is passed.
with⁡ListTools:
randomize⁡:
Simple Examples
Example 1
A≔a,b,c,d,e
Deal⁡A,3
a,d,b,e,c
Example 2
B≔seq⁡1..10
B≔1,2,3,4,5,6,7,8,9,10
Deal⁡B,2
1,3,5,7,9,2,4,6,8,10
Deal⁡B,2,1
1,3,5,7,9
Example 3
C≔x,y,z
Deal⁡C,5
x,y,z,,
Example 4
L≔seq⁡1..5
L≔1,2,3,4,5
Deal⁡L,3,1,3
1,4,3
Example 5
S≔a,b,c,d,e,f
Deal⁡S,3
a,d,b,e,c,f
Deal⁡S,3,1,−1
a,d,c,f
Example 6
R≔Vector⁡1..10,i↦i2
R≔149162536496481100
Deal⁡R,4
12581,436100,949,1664
Deal⁡R,4,2,−1
436100,1664
Example 7
The Deal command can be used to amend a flat list in order to initialize a Matrix:
L≔seq⁡1..12
L≔1,2,3,4,5,6,7,8,9,10,11,12
Matrix⁡Deal⁡L,3
147102581136912
Matrix⁡Deal⁡L,4
159261037114812
Comparison with the Slice command
The Deal command differs from the Slice command in how the elements are ordered. Specifically, Slice keeps the elements in the same order. For example:
A≔Deal⁡L,3
A≔1,4,2,5,3
B≔Slice⁡L,3
B≔1,2,3,4,5
Application 1
Here, we will randomly construct a deck of cards (with typesetting!), and then deal five cards each to four players.
First, define a list for the card ranks:
Ranks≔seq⁡2..10,J,Q,K,A
Ranks≔2,3,4,5,6,7,8,9,10,J,Q,K,A
Second, assemble typeset versions of all the cards available for each suit:
Clubs≔map⁡z↦Typesetting:−mo⁡cat⁡z,♣,mathcolor=Green,Ranks
Clubs≔2♣,3♣,4♣,5♣,6♣,7♣,8♣,9♣,10♣,J♣,Q♣,K♣,A♣
Diamonds≔map⁡z↦Typesetting:−mo⁡cat⁡z,♦,mathcolor=Blue,Ranks
Diamonds≔2♦,3♦,4♦,5♦,6♦,7♦,8♦,9♦,10♦,J♦,Q♦,K♦,A♦
Hearts≔map⁡z↦Typesetting:−mo⁡cat⁡z,♥,mathcolor=Red,Ranks
Hearts≔2♥,3♥,4♥,5♥,6♥,7♥,8♥,9♥,10♥,J♥,Q♥,K♥,A♥
Spades≔map⁡z↦Typesetting:−mo⁡cat⁡z,♠,mathcolor=Black,Ranks
Spades≔2♠,3♠,4♠,5♠,6♠,7♠,8♠,9♠,10♠,J♠,Q♠,K♠,A♠
Third, create a shuffled deck of the above cards:
Deck≔Statistics:-Shuffle⁡seq⁡Clubs,seq⁡Diamonds,seq⁡Hearts,seq⁡Spades
Deck≔8♦,2♦,5♥,9♠,7♥,10♣,Q♦,3♣,7♣,Q♠,6♠,10♠,K♠,6♣,Q♥,A♥,4♦,J♥,2♥,Q♣,9♣,10♦,7♦,A♦,8♠,5♦,K♣,2♠,3♥,K♦,6♦,J♣,9♦,4♥,A♠,4♠,5♣,K♥,J♦,3♦,9♥,A♣,4♣,J♠,6♥,3♠,8♣,8♥,10♥,7♠,2♣,5♠
Finally, deal 5 cards each to the four players:
Deal⁡Deck..20,4
8♦,7♥,7♣,K♠,4♦,2♦,10♣,Q♠,6♣,J♥,5♥,Q♦,6♠,Q♥,2♥,9♠,3♣,10♠,A♥,Q♣
Application 2
Consider the following string:
str≔I was born in the year 1950, graduated university in 1973, and retired in 2010.
Suppose we want to extract the years from this string. One way to accomplish this is to use regular expressions and split the string at the sub-strings that consist of four consecutive digits:
Splits≔StringTools:-RegSplit⁡[0-9]{4},str,keepsplits
Splits≔I was born in the year ,1950,, graduated university in ,1973,, and retired in ,2010,.
This list stores the strings between the matches (years) and, since keepsplits=true, the years as well. Since the years are stored in the elements with even indices:
Years≔Deal⁡Splits,2,2
Years≔1950,1973,2010
The ListTools[Deal] command was introduced in Maple 2021.
For more information on Maple 2021 changes, see Updates in Maple 2021.
See Also
ListTools[Slice]
Statistics[Shuffle]
StringTools
StringTools[RegSplit]
Typesetting
Download Help Document