Golang Multiple Return Values: (value, error), Named Results

Returning more than one value

List the result types in parentheses. Return the values separated by commas, and receive them the same way.

package main

import "fmt"

func minMax(xs []int) (int, int) {
	lo, hi := xs[0], xs[0]
	for _, x := range xs[1:] {
		lo = min(lo, x)
		hi = max(hi, x)
	}
	return lo, hi
}

func main() {
	lo, hi := minMax([]int{4, 9, 1, 7})
	fmt.Println("min:", lo, "max:", hi)
}

The built-in min and max exist since Go 1.21. The caller must receive every result: x := minMax(nums) fails to compile with assignment mismatch: 1 variable but minMax returns 2 values.

The (value, error) convention

The most common reason to return two values is to report failure. By convention the error comes last, and when it is non-nil the other results should be treated as meaningless.

package main

import (
	"errors"
	"fmt"
	"strconv"
)

func parsePort(s string) (int, error) {
	n, err := strconv.Atoi(s)
	if err != nil {
		return 0, fmt.Errorf("port %q: %w", s, err)
	}
	if n < 1 || n > 65535 {
		return 0, errors.New("port out of range")
	}
	return n, nil
}

func main() {
	for _, in := range []string{"8080", "http", "70000"} {
		port, err := parsePort(in)
		if err != nil {
			fmt.Println("error:", err)
			continue
		}
		fmt.Println("port:", port)
	}
}

Output:

port: 8080
error: port "http": strconv.Atoi: parsing "http": invalid syntax
error: port out of range

On failure return the zero value for every other result (0, "", nil). The full pattern, including wrapping and checking, is on the error handling page.

The comma-ok idiom

Several built-in operations return an optional second bool that says whether the first value is real. The variable is conventionally named ok.

package main

import "fmt"

func main() {
	ages := map[string]int{"ana": 31}

	age, ok := ages["bob"]
	fmt.Println(age, ok) // 0 false: missing key, not a zero age

	var v any = "hello"
	s, ok := v.(string)
	fmt.Println(s, ok)

	ch := make(chan int, 1)
	ch <- 5
	close(ch)
	x, ok := <-ch
	fmt.Println(x, ok) // 5 true: a buffered value is still delivered
	x, ok = <-ch
	fmt.Println(x, ok) // 0 false: closed and drained
}

These three forms (map lookup, type assertion, channel receive) are special: they return one value or two depending on how many variables you assign to. Your own functions cannot do that. A function declared with two results always returns two.

The blank identifier

_ receives a value and throws it away. Use it for results you do not need:

_, err := fmt.Sscan(input, &n)
key, _ := parseLine(line)

Ignoring an error with _ compiles, so do it only when you know the call cannot fail or failure does not matter. strings.Builder.WriteString always returns a nil error, for example; a file close after writing does not.

Named results

Result parameters can have names. They are declared at the start of the function, initialized to their zero values, and a return with no values returns whatever they hold.

package main

import "fmt"

func split(total int) (quotient, remainder int) {
	quotient = total / 7
	remainder = total % 7
	return
}

func main() {
	weeks, days := split(45)
	fmt.Println(weeks, "weeks and", days, "days")
}

The names appear in go doc output, which helps when two results share a type: (quotient, remainder int) says more than (int, int).

A bare return in a long function is hard to read, because the reader has to scan back to see what the results hold. The usual advice: name results when the names document something, and still write return quotient, remainder explicitly unless the function is a few lines long.

Named results and defer

A deferred function runs after the return statement has set the results and before the caller receives them. With named results, the deferred function can read and change them. This is how you add context to any error a function returns, or turn a panic into an error.

package main

import (
	"errors"
	"fmt"
)

func load(name string) (err error) {
	defer func() {
		if err != nil {
			err = fmt.Errorf("load %s: %w", name, err)
		}
	}()
	if name == "" {
		return errors.New("empty name")
	}
	return nil
}

func main() {
	fmt.Println(load(""))
	fmt.Println(load("config.json"))
}

This prints load : empty name and then <nil>. return errors.New(...) first assigns to err, then the deferred function wraps it. More on this in defer.

Shadowing a named result

Named results live in the function's outermost scope. A := inside a nested block creates a new variable with the same name, and a bare return then returns the outer one.

func find() (n int, err error) {
	if true {
		n, err := compute() // new n and err, shadowing the results
		_ = n
		_ = err
	}
	return // returns 0, nil
}

The compiler catches the worst case: a bare return inside the block where a result is shadowed fails with result parameter err not in scope at return. It does not catch the version above, where the return sits outside the block. Use = instead of := when you mean the result variables.

Common mistakes

• Using the value when err is non-nil. Check err first. A function is free to return garbage alongside an error.
• Returning a typed nil pointer as an error. var e *MyErr; return e returns a non-nil error. Return a literal nil on success.
• Too many results. Three or more results of mixed meaning are hard to use. Return a struct instead.