What Is a Tuple in Code? Pairs of Values, Explained

What is a tuple in code? It is a small, fixed group of values kept together as one thing. The simplest tuple holds two values, like the row and column of a tile, and the idea reaches from Python to C#. This post shows you how to make a tuple, read it, compare it with a list and spot where real code uses one, with examples from a browser tank game.

What is a tuple in code?

A tuple is an ordered group of values. Ordered means position matters, so the first value stays first. Group means you can pass the whole bundle around as a single value.

Wikipedia defines a tuple as a finite ordered list of elements. An n-tuple has n elements, a 2-tuple is commonly called an ordered pair, and a 1-tuple a singleton. There is only one empty tuple, with no elements at all.

The values in a tuple can be of different kinds. This tuple holds a name, an age and a flag: ("Ada", 36, True). That is why tuples exist. A list usually holds many things of the same kind. A tuple usually holds a few things that belong together but mean different things.

Pairs: the simplest tuple

The most common tuple has two items. Anything that naturally comes in two parts fits:

• A point on a map: row and column.
• A key and its value.
• A minimum and a maximum.
• A distance and the place it measures to.

Take a map that is 13 rows of 13 tiles, like the stages in Tank City Reboot. One tile is two numbers, how far down and how far across, so tile (11, 4) is a single value you can hand to a function that asks "is this tile blocked?" You do not pass two loose numbers and hope they stay in the right order.

Make and read a tuple in Python

Python builds tuples with commas. Parentheses are usual, but the commas do the work.

• point = (3, 4) makes a pair.
• point = 3, 4 makes the same pair.
• empty = () makes an empty tuple.
• single = (5,) makes a one-item tuple. The trailing comma is required, because (5) is just the number 5 in brackets.

You read a tuple by position, counting from zero. point[0] is 3, point[1] is 4, and len(point) is 2.

Unpacking

Unpacking splits a tuple into named variables in one line: x, y = point. Now x is 3 and y is 4. The names on the left must match the number of items, or Python raises an error. That strictness catches mistakes early.

The same trick swaps two variables: a, b = b, a. Python builds a pair on the right, then unpacks it on the left.

Trying to change one

Write point[0] = 10 and Python stops you with a TypeError. To "change" a tuple you build a new one, point = (10, point[1]), and the old tuple is untouched. That is what immutable means.

Tuples vs lists

A list looks similar, with square brackets: [3, 4]. The difference is that you can change a list after you make it: append, remove, reassign. Python's own tutorial says tuples are immutable and usually hold a mix of kinds read by unpacking or position, while lists are mutable and usually hold items of one kind read by looping.

• Use a tuple for one record with a fixed shape: a point, a color (r, g, b), a result with two parts.
• Use a list for a collection that grows, shrinks or gets sorted, like every enemy on the map right now.

Fixed shape pays off in three ways. A function you hand a tuple cannot quietly change it. A reader who sees a tuple knows the shape will not move. And a tuple whose items are themselves unchangeable can be a dictionary key or a set member, which a list cannot.

One catch: a tuple is only shallowly unchangeable. If a tuple holds a list, the tuple keeps pointing at the same list, but the list's contents can still change.

Tuples in C#

Tank City Reboot and Tank City Zero Day are written in C#, so that is the language to look at for the real code. C# tuples group several values in a lightweight structure, and you can name the fields: (double Sum, int Count) t = (4.5, 3); lets you write t.Sum instead of remembering which comes first.

There is a twist. Microsoft's reference says C# tuples are value types whose elements are public fields, which makes them mutable. So the Python rule "tuples cannot change" does not carry over to C#. What carries over is the shape: a few values, bundled, with a known size.

Real examples from a tank game

The arena's fairness check

Zero Day builds a fresh arena for every wave, 13 rows of 13 tiles. Before it accepts one, a check called Arena.Fair asks whether a tank starting beside the core can reach all three enemy gates on the top row, going round silicon and coolant. If it cannot, the arena is drawn again.

Every tile in that code is a pair. The check keeps a queue of (int r, int c) pairs, row and column. It starts from a list of pairs beside the core such as (10, 6) and (12, 4), then repeatedly takes one off the queue and splits it with var (r, c) = queue.Dequeue();, which is unpacking in C# clothes. For each tile it tries four neighbours, and those four steps are pairs too: (1, 0), (-1, 0), (0, 1) and (0, -1), added to the row and column.

Written with loose numbers, every one of those lines would carry two variables that have to stay in step. As pairs, the code reads like the idea: a tile, a direction, a new tile.

A second example: pairs that sort themselves

Enemy tanks find their way to your core with a route search. Its open list holds cells waiting to be looked at, and each entry is a pair, (int d, int k): the distance so far and the cell's number on a 25 by 25 grid. A step costs 1, and a step onto firewall costs 4, because it has to be shot through first.

The pairs are kept in a sorted set, and a pair sorts by its first value, then its second. So the smallest distance always comes out first, and two cells at the same distance are told apart by their cell number. The code gets that ordering for free from the pair, with no comparison function. The structure behind it is in what a priority queue is, and the algorithm is in what Dijkstra's algorithm is.

Common mistakes

• Forgetting the comma in a one-item tuple. (5) is a number; (5,) is a tuple.
• Assigning to an item in Python. point[0] = 10 fails. Build a new tuple.
• Unpacking the wrong count. x, y, z = (3, 4) raises an error because there are too few values.
• Thinking a tuple is deeply frozen. A list inside a tuple can still change.
• Using a tuple for a long record. If you write row[7], you will not remember what index 7 means next week. Name the fields instead, with a C# named tuple, Python's namedtuple or a small class.

Frequently asked questions

Is a tuple the same as a pair?

A pair is a tuple with exactly two items. A tuple can hold any fixed number of items, including none or one.

Can you change a tuple after you make it?

In Python, no: you build a new tuple. In C#, a tuple's items are public fields, so they can be changed.

What is the difference between a tuple and a list?

A tuple has a fixed size and suits one record, like a point. A list can grow, shrink and change, so it suits a collection.

Why are tuples handy for grid games?

A tile, a direction and a step cost each come as a small fixed group of numbers, and a tuple keeps them together as one value.

Get started

Tuples stick fastest when you can see them. Tank City Reboot is a free game that runs in your browser on a computer or a phone, with no account needed to play. Its stages are 13 by 13 tile maps, so every wall and gate sits at a pair of numbers.

1. Play one stage and notice where the enemies come in along the top row and where your core sits at the bottom.
2. In Python, write those spots as (row, column) tuples.
3. Put the blocked tiles in a dictionary keyed by tuple.
4. Write a function that takes a tile and returns True if it is blocked.

Then try Tank City Zero Day, where every wave gets a freshly drawn arena, and think about how you would store one as a set of tuples.