Deal - Maple Help

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 Deal( Container, numhands, handsreturned )

Parameters

 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)].

Description

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

Examples

 > $\mathrm{with}\left(\mathrm{ListTools}\right):$
 > $\mathrm{randomize}\left(\right):$

Simple Examples

Example 1

 > $A≔\left[a,b,c,d,e\right]$
 ${A}{≔}\left[{a}{,}{b}{,}{c}{,}{d}{,}{e}\right]$ (1)
 > $\mathrm{Deal}\left(A,3\right)$
 $\left[{a}{,}{d}\right]{,}\left[{b}{,}{e}\right]{,}\left[{c}\right]$ (2)

Example 2

 > $B≔\left[\mathrm{seq}\left(1..10\right)\right]$
 ${B}{≔}\left[{1}{,}{2}{,}{3}{,}{4}{,}{5}{,}{6}{,}{7}{,}{8}{,}{9}{,}{10}\right]$ (3)
 > $\mathrm{Deal}\left(B,2\right)$
 $\left[{1}{,}{3}{,}{5}{,}{7}{,}{9}\right]{,}\left[{2}{,}{4}{,}{6}{,}{8}{,}{10}\right]$ (4)
 > $\mathrm{Deal}\left(B,2,1\right)$
 $\left[{1}{,}{3}{,}{5}{,}{7}{,}{9}\right]$ (5)

Example 3

 > $C≔\left["x","y","z"\right]$
 ${C}{≔}\left[{"x"}{,}{"y"}{,}{"z"}\right]$ (6)
 > $\mathrm{Deal}\left(C,5\right)$
 $\left[{"x"}\right]{,}\left[{"y"}\right]{,}\left[{"z"}\right]{,}\left[\right]{,}\left[\right]$ (7)

Example 4

 > $L≔\left[\mathrm{seq}\left(1..5\right)\right]$
 ${L}{≔}\left[{1}{,}{2}{,}{3}{,}{4}{,}{5}\right]$ (8)
 > $\mathrm{Deal}\left(L,3,\left[1,3\right]\right)$
 $\left[{1}{,}{4}\right]{,}\left[{3}\right]$ (9)

Example 5

 > $S≔\left\{a,b,c,d,e,f\right\}$
 ${S}{≔}\left\{{a}{,}{b}{,}{c}{,}{d}{,}{e}{,}{f}\right\}$ (10)
 > $\mathrm{Deal}\left(S,3\right)$
 $\left\{{a}{,}{d}\right\}{,}\left\{{b}{,}{e}\right\}{,}\left\{{c}{,}{f}\right\}$ (11)
 > $\mathrm{Deal}\left(S,3,\left[1,-1\right]\right)$
 $\left\{{a}{,}{d}\right\}{,}\left\{{c}{,}{f}\right\}$ (12)

Example 6

 > $R≔\mathrm{Vector}\left(1..10,i→{i}^{2}\right)$
 ${R}{≔}\left[\begin{array}{c}{1}\\ {4}\\ {9}\\ {16}\\ {25}\\ {36}\\ {49}\\ {64}\\ {81}\\ {100}\end{array}\right]$ (13)
 > $\mathrm{Deal}\left(R,4\right)$
 $\left[\begin{array}{c}{1}\\ {25}\\ {81}\end{array}\right]{,}\left[\begin{array}{c}{4}\\ {36}\\ {100}\end{array}\right]{,}\left[\begin{array}{c}{9}\\ {49}\end{array}\right]{,}\left[\begin{array}{c}{16}\\ {64}\end{array}\right]$ (14)
 > $\mathrm{Deal}\left(R,4,\left[2,-1\right]\right)$
 $\left[\begin{array}{c}{4}\\ {36}\\ {100}\end{array}\right]{,}\left[\begin{array}{c}{16}\\ {64}\end{array}\right]$ (15)

Example 7

 • The Deal command can be used to amend a flat list in order to initialize a Matrix:
 > $L≔\left[\mathrm{seq}\left(1..12\right)\right]$
 ${L}{≔}\left[{1}{,}{2}{,}{3}{,}{4}{,}{5}{,}{6}{,}{7}{,}{8}{,}{9}{,}{10}{,}{11}{,}{12}\right]$ (16)
 > $\mathrm{Matrix}\left(\left[\mathrm{Deal}\left(L,3\right)\right]\right)$
 $\left[\begin{array}{cccc}{1}& {4}& {7}& {10}\\ {2}& {5}& {8}& {11}\\ {3}& {6}& {9}& {12}\end{array}\right]$ (17)
 > $\mathrm{Matrix}\left(\left[\mathrm{Deal}\left(L,4\right)\right]\right)$
 $\left[\begin{array}{ccc}{1}& {5}& {9}\\ {2}& {6}& {10}\\ {3}& {7}& {11}\\ {4}& {8}& {12}\end{array}\right]$ (18)

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:
 > $L≔\left[\mathrm{seq}\left(1..5\right)\right]$
 ${L}{≔}\left[{1}{,}{2}{,}{3}{,}{4}{,}{5}\right]$ (19)
 > $A≔\mathrm{Deal}\left(L,3\right)$
 ${A}{≔}\left[{1}{,}{4}\right]{,}\left[{2}{,}{5}\right]{,}\left[{3}\right]$ (20)
 > $B≔\mathrm{Slice}\left(L,3\right)$
 ${B}{≔}\left[{1}{,}{2}\right]{,}\left[{3}{,}{4}\right]{,}\left[{5}\right]$ (21)

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:
 > $\mathrm{Ranks}≔\left[\mathrm{seq}\left(2..10\right),"J","Q","K","A"\right]$
 ${\mathrm{Ranks}}{≔}\left[{2}{,}{3}{,}{4}{,}{5}{,}{6}{,}{7}{,}{8}{,}{9}{,}{10}{,}{"J"}{,}{"Q"}{,}{"K"}{,}{"A"}\right]$ (22)
 • Second, assemble typeset versions of all the cards available for each suit:
 > $\mathrm{Clubs}≔\mathrm{map}\left(z→,\mathrm{Ranks}\right)$
 ${\mathrm{Clubs}}{≔}\left[{2♣}{,}{3♣}{,}{4♣}{,}{5♣}{,}{6♣}{,}{7♣}{,}{8♣}{,}{9♣}{,}{10♣}{,}{J♣}{,}{Q♣}{,}{K♣}{,}{A♣}\right]$ (23)
 > $\mathrm{Diamonds}≔\mathrm{map}\left(z→,\mathrm{Ranks}\right)$
 ${\mathrm{Diamonds}}{≔}\left[{2♦}{,}{3♦}{,}{4♦}{,}{5♦}{,}{6♦}{,}{7♦}{,}{8♦}{,}{9♦}{,}{10♦}{,}{J♦}{,}{Q♦}{,}{K♦}{,}{A♦}\right]$ (24)
 > $\mathrm{Hearts}≔\mathrm{map}\left(z→,\mathrm{Ranks}\right)$
 ${\mathrm{Hearts}}{≔}\left[{2♥}{,}{3♥}{,}{4♥}{,}{5♥}{,}{6♥}{,}{7♥}{,}{8♥}{,}{9♥}{,}{10♥}{,}{J♥}{,}{Q♥}{,}{K♥}{,}{A♥}\right]$ (25)
 > $\mathrm{Spades}≔\mathrm{map}\left(z→,\mathrm{Ranks}\right)$
 ${\mathrm{Spades}}{≔}\left[2♠{,}3♠{,}4♠{,}5♠{,}6♠{,}7♠{,}8♠{,}9♠{,}10♠{,}J♠{,}Q♠{,}K♠{,}A♠\right]$ (26)
 • Third, create a shuffled deck of the above cards:
 > $\mathrm{Deck}≔\mathrm{Statistics}:-\mathrm{Shuffle}\left(\left[\mathrm{seq}\left(\mathrm{Clubs}\right),\mathrm{seq}\left(\mathrm{Diamonds}\right),\mathrm{seq}\left(\mathrm{Hearts}\right),\mathrm{seq}\left(\mathrm{Spades}\right)\right]\right)$
 ${\mathrm{Deck}}{≔}\left[{4♥}{,}A♠{,}{K♣}{,}{8♦}{,}{A♣}{,}5♠{,}{2♦}{,}2♠{,}{9♦}{,}K♠{,}{2♣}{,}4♠{,}{A♦}{,}{4♦}{,}{K♥}{,}{9♣}{,}{3♥}{,}{Q♦}{,}{8♣}{,}{8♥}{,}{6♥}{,}3♠{,}{6♣}{,}{7♥}{,}10♠{,}J♠{,}{10♦}{,}{3♦}{,}{J♥}{,}{10♥}{,}{7♣}{,}{4♣}{,}7♠{,}{Q♥}{,}{5♣}{,}8♠{,}{Q♣}{,}{3♣}{,}{J♦}{,}{5♥}{,}{9♥}{,}{5♦}{,}{A♥}{,}{10♣}{,}9♠{,}{7♦}{,}{6♦}{,}6♠{,}{J♣}{,}Q♠{,}{K♦}{,}{2♥}\right]$ (27)
 • Finally, deal 5 cards each to the four players:
 > $\mathrm{Deal}\left({\mathrm{Deck}}_{\left(\right)..20},4\right)$
 $\left[{4♥}{,}{A♣}{,}{9♦}{,}{A♦}{,}{3♥}\right]{,}\left[A♠{,}5♠{,}K♠{,}{4♦}{,}{Q♦}\right]{,}\left[{K♣}{,}{2♦}{,}{2♣}{,}{K♥}{,}{8♣}\right]{,}\left[{8♦}{,}2♠{,}4♠{,}{9♣}{,}{8♥}\right]$ (28)

Application 2

 • Consider the following string:
 > $\mathrm{str}≔"I was born in the year 1950, graduated university in 1973, and retired in 2010."$
 ${\mathrm{str}}{≔}{"I was born in the year 1950, graduated university in 1973, and retired in 2010."}$ (29)
 • 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:
 > $\mathrm{Splits}≔\left[\mathrm{StringTools}:-\mathrm{RegSplit}\left("\left[0-9\right]\left\{4\right\}",\mathrm{str},\mathrm{keepsplits}\right)\right]$
 ${\mathrm{Splits}}{≔}\left[{"I was born in the year"}{,}{"1950"}{,}{", graduated university in"}{,}{"1973"}{,}{", and retired in"}{,}{"2010"}{,}{"."}\right]$ (30)
 • 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:
 > $\mathrm{Years}≔\mathrm{Deal}\left(\mathrm{Splits},2,2\right)$
 ${\mathrm{Years}}{≔}\left[{"1950"}{,}{"1973"}{,}{"2010"}\right]$ (31)

Compatibility

 • The ListTools[Deal] command was introduced in Maple 2021.