Interfaces you will meet: Stringer to Handler

Three methods, Len, Less and Swap, let sort.Sort order any collection of yours, and two more turn the same type into a priority queue that always hands out the most urgent of eight deliveries first. The standard library is built on small interfaces like these: you write the methods, and a package you did not write does the rest.

You will implement error and fmt.Stringer, order deliveries with sort.Interface and container/heap, and serve requests through http.Handler, the interfaces you will meet in nearly every Go program. Every program here was run with Go 1.27.1, and its output appears beneath it.

A few methods connect your type to the library

Each of these interfaces is a promise: give your type its methods, and the package on the right will call them.

Here is a seat with a String method, an error type, and a type with both:

// print_methods.go: a String method, an Error method, and a type with both, printed by fmt.
package main

import (
	"errors"
	"fmt"
)

// Seat prints as coach and berth.
type Seat struct {
	Coach string
	Berth int
}

func (s Seat) String() string { return fmt.Sprintf("%s-%d", s.Coach, s.Berth) }

// BerthError is an error: its Error method satisfies the error interface.
type BerthError struct{ Seat Seat }

func (e BerthError) Error() string { return "berth " + e.Seat.String() + " is taken" }

// Fault has both methods.
type Fault struct{}

func (Fault) String() string { return "the String method" }
func (Fault) Error() string  { return "the Error method" }

func main() {
	s := Seat{Coach: "B2", Berth: 34}
	fmt.Println(s, []Seat{s, {Coach: "S1", Berth: 7}})
	var err error = BerthError{Seat: s}
	fmt.Println(err)
	var be BerthError
	fmt.Println(errors.As(err, &be), be.Seat.Berth)
	fmt.Println(Fault{})
}

B2-34 [B2-34 S1-7]
berth B2-34 is taken
true 34
the Error method

A fmt.Stringer controls how fmt prints a value: the Seat printed as B2-34, inside a slice too. A type with an Error method is an error, the predeclared interface of the specification, so BerthError went into an error variable and errors.As found it again. Fault has both methods, and fmt printed the Error method, because fmt, as its documentation says, checks for error before Stringer. Formatted output with fmt covers String methods in depth.

sort.Interface and heap.Interface: an order you supply

sort.Interface asks for three methods: Len, Less, which reports whether element i sorts before element j, and Swap. container/heap asks for those three plus Push and Pop, and keeps the smallest element, by your Less, at index 0. One type of eight deliveries does both:

// deliveries.go: eight deliveries sorted by sort.Sort, and the same eight in a container/heap queue.
package main

import (
	"container/heap"
	"fmt"
	"sort"
)

// Delivery is an order and the minutes left before it is due.
type Delivery struct {
	Order   int
	DueMins int
}

// ByDue implements sort.Interface and, with Push and Pop, heap.Interface.
type ByDue []Delivery

func (q ByDue) Len() int           { return len(q) }
func (q ByDue) Less(i, j int) bool { return q[i].DueMins < q[j].DueMins }
func (q ByDue) Swap(i, j int)      { q[i], q[j] = q[j], q[i] }

// Push and Pop are for package heap to call; they add and remove at the end.
func (q *ByDue) Push(x any) { *q = append(*q, x.(Delivery)) }
func (q *ByDue) Pop() any {
	old := *q
	last := old[len(old)-1]
	*q = old[:len(old)-1]
	return last
}

func dues(q ByDue) []int {
	out := make([]int, len(q))
	for i, d := range q {
		out[i] = d.DueMins
	}
	return out
}

func main() {
	orders := ByDue{{1041, 35}, {1042, 12}, {1043, 50}, {1044, 8}, {1045, 41}, {1046, 27}, {1047, 19}, {1048, 60}}

	sorted := append(ByDue(nil), orders...)
	sort.Sort(sorted)
	fmt.Println("sorted:      ", dues(sorted))

	q := append(ByDue(nil), orders...)
	heap.Init(&q)
	fmt.Println("heap array:  ", dues(q))
	for range 3 {
		d := heap.Pop(&q).(Delivery)
		fmt.Printf("next: order %d, due in %d min\n", d.Order, d.DueMins)
	}
	fmt.Println("left in heap:", dues(q))
}

sorted:       [8 12 19 27 35 41 50 60]
heap array:   [8 12 19 35 41 27 50 60]
next: order 1044, due in 8 min
next: order 1042, due in 12 min
next: order 1047, due in 19 min
left in heap: [27 35 50 60 41]

sort.Sort put all eight in order. heap.Init only arranged them as a binary heapbinary heap: A tree stored in an array, in which every element is at most its children, at positions 2i + 1 and 2i + 2, so the smallest is at index 0. container/heap keeps a slice in this order through its Less method.: in the array [8 12 19 35 41 27 50 60] each element is at most its children at positions 2i + 1 and 2i + 2, which is enough to find the minimum at once. Each heap.Pop removed the most urgent delivery and repaired the heap. Step through the three pops on the same eight due times:

The figure took out 8, 12 and 19 and left [27 35 50 60 41], exactly what deliveries.go printed. Push and Pop on the type itself only add and remove at the end of the slice; container/heap’s documentation says they are for the package to call, and you call heap.Push and heap.Pop.

http.Handler: one method between your code and the server

An http.Handler is any type with ServeHTTP(w http.ResponseWriter, r *http.Request). The server calls it once per request; httptest lets a program, or a test, make the same call without a network:

// handler.go: a Handler type with state, a HandlerFunc, and both called through httptest.
package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
)

// Stock answers how many units of an item are left. It is an http.Handler: it has ServeHTTP.
type Stock struct{ units map[string]int }

func (s *Stock) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	item := r.URL.Query().Get("item")
	n, ok := s.units[item]
	if !ok {
		http.Error(w, "unknown item "+item, http.StatusNotFound)
		return
	}
	fmt.Fprintf(w, "%s: %d left\n", item, n)
}

func main() {
	stock := &Stock{units: map[string]int{"atta-5kg": 14}}
	health := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "ok") // an ordinary function, adapted into a Handler
	})

	for _, c := range []struct {
		h    http.Handler
		path string
	}{{stock, "/stock?item=atta-5kg"}, {stock, "/stock?item=ghee-1l"}, {health, "/healthz"}} {
		rec := httptest.NewRecorder()
		c.h.ServeHTTP(rec, httptest.NewRequest("GET", c.path, nil))
		fmt.Printf("%-22s %d %q\n", c.path, rec.Code, rec.Body.String())
	}
}

/stock?item=atta-5kg   200 "atta-5kg: 14 left\n"
/stock?item=ghee-1l    404 "unknown item ghee-1l\n"
/healthz               200 "ok\n"

*Stock is a Handler because it has ServeHTTP, and it answered 200 for atta and 404 for ghee. The health check was an ordinary function, which http.HandlerFunc(…) converted into a Handler: HandlerFunc is a function type whose ServeHTTP calls the function. Step through the first request:

Two more tools build on these interfaces. A container/heap queue can also change or cancel an item in place, with heap.Fix and heap.Remove. And encoding.TextMarshaler lets a type write and read itself as text for JSON keys, flags and logs.

A delivery queue on container/heap, measured Pro: opens with a Pro, Premium or Ultimate pass

TextMarshaler: one pair of methods for JSON keys, flags and text Pro: opens with a Pro, Premium or Ultimate pass

Practise

Practice asks about Stringer and error, the ordering interfaces and Handler, beginning with whichever your answers show is weakest:

Interview questions

Warm-up (fresher): Which methods does sort.Interface ask for, and what must Less promise?

Len, the number of elements; Less(i, j), whether element i must sort before element j; and Swap(i, j). Less must describe a strict weak ordering, and the sort documentation gives two of its rules as examples: if Less(i, j) and Less(j, k) are both true, so is Less(i, k), and if both are false, Less(i, k) is false too. Two elements count as equal when Less is false both ways, so write Less with less than: with less than or equal, each of two equal elements would sort before the other, which no strict weak ordering allows.

Three longer questions of the module bank build on this lesson:

Key takeaways

• error and fmt.Stringer are one method each; fmt prints with Error before String when a value has both.
• sort.Interface needs Len, Less and Swap, and heap.Interface adds Push and Pop for container/heap to call; the heap keeps the smallest element by Less at index 0.
• Any type with ServeHTTP is an http.Handler, HandlerFunc turns a function into one, and httptest calls handlers without a network.