Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 40 ยท Types and Dispatch

Interfaces and Iteration Protocols

Learn how Julia interfaces work without interface keywords: implement iterate, length and getindex, extend Base methods, and design abstract type contracts.

Julia has no interface keyword and no implements clause. Instead, an interface is a set of functions that a type agrees to provide. If your type defines the right methods, everything built on that interface starts working: for loops, collect, sum, map, indexing, printing. The agreement is informal, written in documentation, and enforced only by the fact that a missing method raises a MethodError.

This lesson shows the most important interfaces in the language: iteration (iterate), collection size (length, eltype), and indexing (size, getindex). You will learn how to extend Base functions for your own types, and how to write abstract types that document a contract. The Julia code is read-only on this site; the Python stand-ins simulate the protocol so you can see exactly what a for loop does.

Interfaces are informal contracts

Consider what you know about the function sum(xs). It works for any collection you can loop over. It does not check that xs inherits from some base class. It just calls iterate, the function behind for. So to make your own type work with sum, collect, maximum, zip and every other iteration-based function, you implement one method.

Three common interfaces

Iteration Implement iterate to work in for loops.
Size length and eltype describe the collection.
Indexing size and getindex make an array-like type.
1 / 2

The iteration protocol

A for loop is syntactic sugar over iterate. The loop

JULIA
for x in collection
    body
end

is equivalent to this:

JULIA
next = iterate(collection)
while next !== nothing
    (x, state) = next
    body
    next = iterate(collection, state)
end

So the protocol has two methods: iterate(c) starts the iteration, and iterate(c, state) continues it. Each returns either nothing (finished) or a tuple (value, next_state). The state is yours to define: an index, a node, a counter.

Here is a countdown type:

JULIA
struct Countdown
    start::Int
end

function Base.iterate(c::Countdown, state = c.start)
    state < 1 && return nothing
    return (state, state - 1)
end

Base.length(c::Countdown) = c.start
Base.eltype(::Type{Countdown}) = Int

for n in Countdown(3)
    println(n)
end
# 3
# 2
# 1

collect(Countdown(4))      # [4, 3, 2, 1]
sum(Countdown(4))          # 10
maximum(Countdown(4))      # 4

A default argument state = c.start lets one method serve both call forms. Defining length and eltype is not required for a for loop, but collect uses them to allocate the result. If you cannot know the length cheaply, declare that with Base.IteratorSize(::Type{Countdown}) = Base.SizeUnknown() and collect will grow the result as it goes.

This is also why the standard library can have lazy iterators like zip, enumerate, Iterators.take and generators (x^2 for x in 1:10). They are just structs with an iterate method.

Extending Base methods

To give your own type behavior from Base, add a method to the Base function. Two forms:

JULIA
# Qualified name: always works, no import needed
Base.length(c::Countdown) = c.start
Base.:+(a::Money, b::Money) = Money(a.cents + b.cents)

# Import the name, then extend by its short name
import Base: length, show
length(c::Countdown) = c.start

Writing just length(c::Countdown) = ... without importing it would define a brand-new function named length in your module and shadow the original one. This is the most frequent source of "my for loop doesn't see my method" confusion. When in doubt, qualify the name with Base. as shown above. Modules and Scope explains why.

The indexing interface

An array-like type needs size and getindex. If you also declare it as a subtype of AbstractVector, you inherit a huge amount of behavior (printing, sum, map, slicing, broadcasting, linear algebra) for free:

JULIA
struct Squares <: AbstractVector{Int}
    n::Int
end

Base.size(s::Squares) = (s.n,)
Base.getindex(s::Squares, i::Int) = i^2

s = Squares(5)
s[3]            # 9
length(s)       # 5 (derived from size)
sum(s)          # 55
collect(s)      # [1, 4, 9, 16, 25]
s[2:4]          # [4, 9, 16]
s .+ 1          # [2, 5, 10, 17, 26]

No data is stored: the values are computed on demand, so a Squares(10^9) costs nothing until you ask for elements. A write interface works the same way: define setindex! to make the type mutable, and Base.IndexStyle if it should be linear or Cartesian. The full "array interface" is documented in the Julia manual under Interfaces, but the two-method core above is enough to start.

Abstract types as contracts

An abstract type can describe a family and its required functions. Julia has no way to force subtypes to implement them, but you can make the error friendly by providing a fallback method:

JULIA
abstract type Shape end

area(s::Shape) = error("area is not implemented for $(typeof(s))")
perimeter(s::Shape) = error("perimeter is not implemented for $(typeof(s))")

struct Square <: Shape
    side::Float64
end
area(s::Square) = s.side^2

area(Square(3))         # 9.0
perimeter(Square(3))    # ERROR: perimeter is not implemented for Square

Anyone adding a new Shape sees exactly which methods are missing. Package authors usually document the contract in the abstract type's docstring and may add a test helper that checks it. Behavior that depends on a capability rather than a family of types is often expressed with a "trait" function, such as Base.IteratorSize or Base.IndexStyle. A trait is a function that takes a type and returns a small marker value, used to dispatch on a property the type hierarchy cannot express:

JULIA
Base.IteratorSize(Countdown)        # Base.HasLength()
Base.IteratorSize(typeof(1:3))      # Base.HasShape{1}()

Seeing the protocol in Python

Python's iterator protocol uses exceptions where Julia uses nothing. This stand-in recreates Julia's version: a function returns None to stop or a (value, state) pair to continue, and a small julia_for plays the role of the loop.

Python What a for loop really does

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The state is passed back in, not stored inside the object. That keeps the collection itself unchanged while it is being iterated, so you can loop over it in two places at once.

The second stand-in builds the indexing interface: a class that defines only __len__ and __getitem__, which is enough for Python to offer slicing, iteration and sum.

Python Two methods, many features

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python has no abstract array base class that supplies these extras for free the way AbstractVector does in Julia. Here we wrote sum by hand to keep the example small.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does iterate(c, state) return when the iteration is finished?

    Each call returns either nothing to stop or a (value, next_state) tuple. A for loop ends when it sees nothing.
  2. 2. You write length(c::Countdown) = c.start in your own module without importing Base.length. What happens?

    To add a method to a Base function, write Base.length(...) or import Base: length first.
  3. 3. Which two methods are the core of an array-like type that subtypes AbstractVector?

    With size and getindex defined, AbstractVector supplies printing, slicing, sum, map, broadcasting and much more.
  4. 4. How are Julia interfaces enforced?

    There is no formal declaration. A missing method simply fails when the function is called, so good packages document the contract.

Summary

  • A Julia interface is a set of functions a type implements, not a keyword or base class.
  • for loops call iterate(c) and iterate(c, state); return nothing to stop, or (value, next_state).
  • length, eltype and IteratorSize describe the collection so functions like collect can prepare.
  • For array-like types, define size and getindex and subtype AbstractVector (or AbstractArray).
  • Extend Base functions with Base.name(...) or import Base: name; otherwise you shadow them.
  • Abstract types can describe a contract, with fallback methods that give helpful errors.

Next, see how code is organized into namespaces and how variables are scoped in Modules and Scope.