*! version 1.0.0 25sep2025
help tuplesget()

tuplesget() -- Obtain tuples, one at a time

Syntax

t =
tuplessetup(transmorphic vector v
[, real vector k])

transmorphic vector
tuplesget(t)

real scalar
tuplesdone(t)

real scalar
tupleskount(t
[, real scalar all])

real scalar
tupleskountrest(t
[, real scalar all])

where t should be declared transmorphic

Description

These functions complement the tuples command
and implement a tuple-combination generator in Mata.

tuplesget()
returns all k-tuples of the elements of vector v, one at a time.
Vector v is specified by calling tuplessetup() as

t = tuplessetup(v, k)

and t is passed to tuplesget().
To obtain the tuples, tuplesget() is called repeatedly.
Omitting k from tuplessetup()
is equivalent to specifying k=(1..length(v)).

If v is a rowvetor or scalar,
tuplesget()
returns 1 x c vectors;
if v is a colvector,
tuplesget()
returns r x 1 vectors.
tuplesget()
returns J(1,0,missingof(v))
(v a rowvector or scalar)
or returns J(0,1,missingof(v))
(v a colvector)
after the last k-tuple has been obtained.
tuplesget()
returns J(0,0,missingof(v))
when k<1 or k>length(v).

tuplesdone()
returns 1 if all k-tuples have been obtained, and 0 otherwise.
tuplesdone()
is the recommended way to obtain all k-tuples:

t = tuplessetup(v, k)
while ( !tuplesdone(t) ) {
tuple = tuplesget(t)
... tuple ...
}

tupleskount()
returns the sequence number of the most recently obtained tuple.
If all is omitted or all!=0, the count includes all tuples,
including missing tuples for k<1 or k>length(v).
If all=0, the count only refers to non-missing tuples.

tupleskountrest()
returns the number of remaining tuples in v.
If all is omitted or all!=0, the count includes all tuples,
including missing tuples for k<1 or k>length(v).
If all=0, the count only refers to non-missing tuples.

Remarks

Remarks are presented under the following headings:

Example
Obtaining all k-tuples
Technical note
Methods and formulas

Example

: t = tuplessetup(("frog","toad","newt"))
: while( !tuplesdone(t) ) {
> tuplesget(t)
> }
frog
toad
newt
1 2
+
+
1 | frog toad |
+
+
1 2
+
+
1 | frog newt |
+
+
1 2
+
+
1 | toad newt |
+
+
1 2 3
+
+
1 | frog toad newt |
+
+

Obtaining all k-tuples

Following

t = tuplessetup(v, k)

the recommended way to obtain all k-tuples is tuplesdone():

while ( !tuplesdone(t) ) {
tuple = tuplesget(t)
... tuple ...
}

Alternative approaches are often slightly slower or more error-prone.
For example,

while ( tupleskountrest(t) ) {
tuple = tuplesget(t)
... tuple ...
}

is functionally equivalent to tuplesdone()
but repeatedly counting the remaining tuples adds unnecessary overhead.

Another way to obtain all k-tuples is by checking for the empty tuple:

while ((tuple=tuplesget(t)) != J(1,0,"")) {
... tuple ...
}

Unlike the previous two approaches,
this one assigns the empty tuple, J(1,0,""),
to the variable tuple before the loop terminates.
More importantly, there's a caveat:
The empty tuple varies with the
eltype
and
orgtype
of v,
meaning that
tuplesget()
may never return
J(1,0,""),
creating an infinite loop.

Technical note

When you
tuplessetup(v, k),
the contents of v and k are not stored.
Instead, pointers to v and k are stored.
This approach saves memory and time,
but it means that if you change v or k after setting them,
you will change the subsequent behavior of the other
tuples*()
functions.

Methods and formulas

tuplesget()
implements algorithm AS 88 (Gentleman, 1975).

Conformability

tuplessetup(v, k):

v: 1 x c or r x 1
k: 1 x c or r x 1 (optional)
result: transmorphic

tuplesget(t):

t: transmorphic
result: 1 x c or r x 1 or 0 x 0

tuplesdone(t):

t: transmorphic
result: 1 x 1

tupleskount(t):

t: transmorphic
result: 1 x 1

tupleskountrest(t):

t: transmorphic
result: 1 x 1

Diagnostics

tuplesget()
returns
J(1,0,missingof(v))
(v a rowvector or scalar)
or
J(0,1,missingof(v))
(v a colvector)
when there are no more tuples.

tuplesget()
returns
J(0,0,missingof(v))
when k<1 or k>length(v).

Source code

tuplesget.mata
for all functions.

References

Gentleman, J. F. 1975.
Algorithm AS 88: Generation of All NCR Combinations by Simulating Nested Fortran DO Loops.
Journal of the Royal Statistical Society.
Series C (Applied Statistics), 24(3), pp. 374--376.

Support

Daniel Klein, German Centre for Higher Education Research and Science Studies

klein.daniel.81@gmail.com

Joseph N. Luchman, Fors Marsh Group LLC

jluchman@forsmarshgroup.com

Nicholas J. Cox, Durham University

n.j.cox@durham.ac.uk

Also see

Online: mata

if installed: mm_subset() (moremata)