Golang Methods: Value vs Pointer Receivers Explained

Declaring a method

A method is a function with a receiver: an extra parameter written before the method name. The receiver ties the method to a type.

package main

import (
	"fmt"
	"math"
)

type Circle struct {
	Radius float64
}

func (c Circle) Area() float64 {
	return math.Pi * c.Radius * c.Radius
}

func (c Circle) String() string {
	return fmt.Sprintf("Circle(r=%.1f)", c.Radius)
}

func main() {
	c := Circle{Radius: 2}
	fmt.Printf("%.2f\n", c.Area())
	fmt.Println(c) // uses the String method
}

The receiver name is usually one or two letters taken from the type (c for Circle). Go does not use this or self, and style guides discourage those names.

Because Circle has a String() string method, it satisfies fmt.Stringer, and fmt.Println prints the result instead of {2}.

Value receivers and pointer receivers

A value receiver (c Circle) gets a copy. A pointer receiver (c *Circle) gets the address, so changes to fields stick.

package main

import "fmt"

type Counter struct {
	n int
}

func (c Counter) IncByValue() {
	c.n++ // changes the copy only
}

func (c *Counter) Inc() {
	c.n++
}

func (c Counter) Value() int {
	return c.n
}

func main() {
	var c Counter
	c.IncByValue()
	fmt.Println(c.Value()) // 0

	c.Inc() // Go takes &c automatically
	c.Inc()
	fmt.Println(c.Value()) // 2

	p := &c
	fmt.Println(p.Value()) // Go dereferences p automatically
}

IncByValue compiles and does nothing visible, a classic bug. If a method is meant to modify its receiver, it needs a pointer receiver.

The calls also show the two conveniences Go gives you. c.Inc() on an addressable variable is rewritten to (&c).Inc(), and p.Value() on a pointer is rewritten to (*p).Value(). You rarely write & or * just to call a method.

The automatic & needs something addressable. A map element or a composite literal is not:

m := map[string]Counter{"a": {}}
m["a"].Inc()    // compile error: cannot call pointer method Inc on Counter
Counter{}.Inc() // same error: a composite literal is not addressable

Store pointers in the map (map[string]*Counter) or copy the value out, change it, and write it back.

Which receiver to choose

The Go FAQ and the standard library follow one rule of thumb: be consistent. If any method needs a pointer receiver, give all methods pointer receivers, so the method set is predictable. go vet flags a struct holding a sync.Mutex that is copied through a value receiver (passes lock by value).

Method sets and interfaces

The distinction matters most for interfaces. The method set of T contains the value-receiver methods. The method set of *T contains both value- and pointer-receiver methods.

package main

import "fmt"

type Shape interface {
	Area() float64
}

type Square struct{ Side float64 }

func (s *Square) Area() float64 { return s.Side * s.Side }

type Rect struct{ W, H float64 }

func (r Rect) Area() float64 { return r.W * r.H }

func main() {
	shapes := []Shape{
		&Square{Side: 3},  // *Square has Area
		Rect{W: 2, H: 5},  // Rect has Area
		&Rect{W: 1, H: 1}, // *Rect has it too
	}
	for _, s := range shapes {
		fmt.Printf("%T %.0f\n", s, s.Area())
	}
}

Writing Square{Side: 3} without the & in that slice fails to compile:

cannot use Square{…} (value of struct type Square) as Shape value in array or slice literal: Square does not implement Shape (method Area has pointer receiver)

The reason: an interface can hold a copy of a Square that is not addressable, so Go cannot take its address to call a pointer method. See interfaces for the rest of that story.

Methods on non-struct types

Any named type declared in your package can have methods, not only structs.

package main

import (
	"fmt"
	"strings"
)

type Celsius float64

func (c Celsius) Fahrenheit() float64 {
	return float64(c)*9/5 + 32
}

type Tags []string

func (t Tags) String() string {
	return "#" + strings.Join(t, " #")
}

type Status int

func (s Status) String() string {
	switch s {
	case 0:
		return "pending"
	case 1:
		return "done"
	}
	return fmt.Sprintf("Status(%d)", int(s))
}

func main() {
	fmt.Println(Celsius(100).Fahrenheit())
	fmt.Println(Tags{"go", "backend"})
	fmt.Println(Status(1), Status(7))
}

The limits: the type must be defined in the same package as the method, and its underlying type cannot be a pointer or an interface. You cannot add methods to int, string, or time.Time from your own package. Wrapping in a new named type is the Go way. String() on an integer type is also how enums get readable output; see enums with iota.

Method values and method expressions

A method bound to a specific receiver is a function value:

package main

import "fmt"

type Greeter struct{ Name string }

func (g Greeter) Hello(to string) string {
	return g.Name + " says hi to " + to
}

func main() {
	g := Greeter{Name: "Ana"}

	f := g.Hello // method value: receiver bound now
	g.Name = "Bob"
	fmt.Println(f("Cy")) // still Ana: the receiver was copied

	h := Greeter.Hello // method expression: receiver becomes the first parameter
	fmt.Println(h(g, "Dee"))
}

A method value with a value receiver copies the receiver when it is created, which is why f still says Ana. With a pointer receiver it would store the pointer and see later changes. Method values are handy for callbacks: http.HandleFunc("/", srv.handleIndex).

Common mistakes

• Value receiver on a mutating method. Compiles, silently changes a copy.
• Mixing receiver kinds. Makes it unclear whether T or *T satisfies an interface. Pick one per type.
• Calling a pointer method on a nil pointer. Allowed, and the method runs with a nil receiver. It panics only when it touches a field. Some types (like a nil-safe linked list) use this on purpose; most do not expect it.