Custom Subscripts in Swift

Custom subscripts are a powerful language feature that enhance the convenience factor and readability of your code.

Like operator overloading, custom subscripts let you use native Swift constructs. You can use something concise like checkerBoard[2][3] rather than the more verbose checkerBoard.objectAt(x: 2, y: 3).

In this tutorial, you’ll explore custom subscripts by building the foundations for a basic checkers game in a playground. You’ll see how easy it is to use subscripting to move pieces around the board. When you’re done, you’ll be well on your way to building a new game to keep your fingers occupied during all your spare time.

Oh, and you’ll know a lot more about subscripts too! :]

Getting Started

To start, create a new playground. Go to File ▸ New ▸ Playground…, choose the iOS ▸ Blank template and click Next. Name the file Subscripts.playground and click Create.

Replace the default text with:

import Foundation

struct Checkerboard {
  enum Square: String {
    case empty = "▪️"
    case red = "🔴"
    case white = "⚪️"
  }

  typealias Coordinate = (x: Int, y: Int)

  private var squares: [[Square]] = [
    [ .empty, .red,   .empty, .red,   .empty, .red,   .empty, .red   ],
    [ .red,   .empty, .red,   .empty, .red,   .empty, .red,   .empty ],
    [ .empty, .red,   .empty, .red,   .empty, .red,   .empty, .red   ],
    [ .empty, .empty, .empty, .empty, .empty, .empty, .empty, .empty ],
    [ .empty, .empty, .empty, .empty, .empty, .empty, .empty, .empty ],
    [ .white, .empty, .white, .empty, .white, .empty, .white, .empty ],
    [ .empty, .white, .empty, .white, .empty, .white, .empty, .white ],
    [ .white, .empty, .white, .empty, .white, .empty, .white, .empty ]
  ]
}

Checkerboard contains three definitions:

• Square represents the state of an individual square on the board. .empty represents an empty square while .red and .white represent the presence of a red or white piece on that square.
• Coordinate is an alias for a tuple of two integers. You’ll use this type to access the squares on the board.
• squares is the two-dimensional array that stores the state of the board.

Next, add:

extension Checkerboard: CustomStringConvertible {
  var description: String {
    return squares.map { row in row.map { $0.rawValue }.joined(separator: "") }
        .joined(separator: "\n") + "\n"
  }
}

This is an extension to add CustomStringConvertible conformance. With a custom description, you can print a checkerboard to the console.

Open the console using View ▸ Debug Area ▸ Show Debug Area, then enter the following lines at the bottom of the playground:

var checkerboard = Checkerboard()
print(checkerboard)

This code initializes an instance of Checkerboard. Then it prints the description property to the console using the CustomStringConvertible implementation.

After pressing the Execute Playground button, the output in your console should look like this:

▪️🔴▪️🔴▪️🔴▪️🔴
🔴▪️🔴▪️🔴▪️🔴▪️
▪️🔴▪️🔴▪️🔴▪️🔴
▪️▪️▪️▪️▪️▪️▪️▪️
▪️▪️▪️▪️▪️▪️▪️▪️
⚪️▪️⚪️▪️⚪️▪️⚪️▪️
▪️⚪️▪️⚪️▪️⚪️▪️⚪️
⚪️▪️⚪️▪️⚪️▪️⚪️▪️

Getting and Setting Pieces

Looking at the console, it’s pretty easy for you to know what piece occupies a given square, but your program doesn’t have that power yet. It can’t know which player is at a specified coordinate because the squares array is private.

There’s an important point to make here: The squares array is the implementation of the the board. However, the user of a Checkerboard shouldn’t know anything about the implementation of that type.

A type should shield its users from its internal implementation details; that’s why the squares array is private.

With that in mind, you’re going to add two methods to Checkerboard to find and change a piece at a given coordinate.

Add the following methods to Checkerboard, after the spot where you assign the squares array:

func piece(at coordinate: Coordinate) -> Square {
  return squares[coordinate.y][coordinate.x]
}

mutating func setPiece(at coordinate: Coordinate, to newValue: Square) {
  squares[coordinate.y][coordinate.x] = newValue
}

Notice how you access squares – using a Coordinate tuple – rather than accessing the array directly. The actual storage mechanism is an array-of-arrays. That is exactly the kind of implementation detail you should shield the user from!

Defining Custom Subscripts

You may have noticed that these methods look an awful lot like a property getter and setter combination. Maybe you should implement them as a computed property instead?

Unfortunately, that won’t work. These methods require a Coordinate parameter, and computed properties can’t have parameters. Does that mean you’re stuck with methods?

Well, no – this special case is exactly what subscripts are for! :]

Look at how you define a subscript:

subscript(parameterList) -> ReturnType {
  get {
    // return someValue of ReturnType
  }

  set (newValue) {
    // set someValue of ReturnType to newValue
  }
}

Subscript definitions mix both function and computed property definition syntax:

• The first part looks a lot like a function definition, with a parameter list and a return type. Instead of the func keyword and a function name, you use the special subscript keyword.
• The main body looks a lot like a computed property with a getter and a setter.

The combination of function and property syntax highlights the power of subscripts. It provides a shortcut for accessing the elements of an indexed collection. You’ll learn more about that soon but, first, consider the following example.

Replace piece(at:) and setPiece(at:to:) with the following subscript:

subscript(coordinate: Coordinate) -> Square {
  get {
    return squares[coordinate.y][coordinate.x]
  }
  set {
    squares[coordinate.y][coordinate.x] = newValue
  }
}

You implement the getter and setter of this subscript exactly the same way as you implement the methods they replace:

• Given a Coordinate, the getter returns the square at the column and row.
• Given a Coordinate and value, the setter accesses the square at the column and row and replaces its value.

Give your new subscript a test drive by adding the following code to the end of the playground:

let coordinate = (x: 3, y: 2)
print(checkerboard[coordinate])
checkerboard[coordinate] = .white
print(checkerboard)

The playground will tell you the piece at (3, 2) is red. After changing it to white, the output in the console will be:

▪️🔴▪️🔴▪️🔴▪️🔴
🔴▪️🔴▪️🔴▪️🔴▪️
▪️🔴▪️⚪️▪️🔴▪️🔴
▪️▪️▪️▪️▪️▪️▪️▪️
▪️▪️▪️▪️▪️▪️▪️▪️
⚪️▪️⚪️▪️⚪️▪️⚪️▪️
▪️⚪️▪️⚪️▪️⚪️▪️⚪️
⚪️▪️⚪️▪️⚪️▪️⚪️▪️

You can now find out which piece is at a given coordinate, and set it, by using checkerboard[coordinate] in both cases. A shortcut indeed!