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):$

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 consisting of 20 cards (for simplicity), and then deal five cards each to four players.
 • First, define lists for the card values and suits:
 > $\mathrm{Values}≔\left[\mathrm{seq}\left(1..10\right),"J","Q","K","A"\right]$
 ${\mathrm{Values}}{≔}\left[{1}{,}{2}{,}{3}{,}{4}{,}{5}{,}{6}{,}{7}{,}{8}{,}{9}{,}{10}{,}{"J"}{,}{"Q"}{,}{"K"}{,}{"A"}\right]$ (22)
 > $\mathrm{Suits}≔\left["C","D","H","S"\right]$
 ${\mathrm{Suits}}{≔}\left[{"C"}{,}{"D"}{,}{"H"}{,}{"S"}\right]$ (23)
 • Second, using random number generators, create a unique deck of 20 cards:
 > $\mathrm{randomize}\left(\right):$
 > $f≔\mathrm{rand}\left(1..\mathrm{numelems}\left(\mathrm{Values}\right)\right):$
 > $g≔\mathrm{rand}\left(1..\mathrm{numelems}\left(\mathrm{Suits}\right)\right):$
 > $\mathbf{do}\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\phantom{\rule[-0.0ex]{2.0em}{0.0ex}}\mathrm{Deck}≔\left[\mathrm{seq}\left(\mathrm{cat}\left("",\mathrm{Values}\left[f\left(\right)\right],\mathrm{Suits}\left[g\left(\right)\right]\right),1..20\right)\right]\phantom{\rule[-0.0ex]{0.0em}{0.0ex}}\mathbf{until}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}\mathrm{ListTools}:-\mathrm{FindRepetitions}\left(\mathrm{Deck}\right)=\left[\right]:$
 > $'\mathrm{Deck}'=\mathrm{Deck}$
 ${\mathrm{Deck}}{=}\left[{"1S"}{,}{"2S"}{,}{"8C"}{,}{"3D"}{,}{"KS"}{,}{"QH"}{,}{"AH"}{,}{"1C"}{,}{"AD"}{,}{"10D"}{,}{"3H"}{,}{"8D"}{,}{"4S"}{,}{"JH"}{,}{"1H"}{,}{"6D"}{,}{"AC"}{,}{"5H"}{,}{"JC"}{,}{"3C"}\right]$ (24)
 • Finally, deal 5 cards each to the four players:
 > $\mathrm{Deal}\left(\mathrm{Deck},4\right)$
 $\left[{"1S"}{,}{"KS"}{,}{"AD"}{,}{"4S"}{,}{"AC"}\right]{,}\left[{"2S"}{,}{"QH"}{,}{"10D"}{,}{"JH"}{,}{"5H"}\right]{,}\left[{"8C"}{,}{"AH"}{,}{"3H"}{,}{"1H"}{,}{"JC"}\right]{,}\left[{"3D"}{,}{"1C"}{,}{"8D"}{,}{"6D"}{,}{"3C"}\right]$ (25)

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."}$ (26)
 • 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]$ (27)
 • 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]$ (28)

Compatibility

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