What pointers may be used for in Go?

I think I understand what pointer is but I don't quite understand when to use it.<br>
The below snippet is from "A Tour of Go".<br>
What is the purpose of "*Vertex" and "&Vertex"? <br>
I replaced them with "Vertex" and it run fine.<br>

package main

import (
    "fmt"
    "math"
)

type Vertex struct {
    X, Y float64
}

func (v *Vertex) Abs() float64 {
    return math.Sqrt(v.X*v.X + v.Y*v.Y)
}

func main() {
    v := &Vertex{3, 4}
    fmt.Println(v.Abs())
}

That's not a particularly good example of the pointer/value distinction, because in that case they're interchangeable! Pointers are useful when you need to mutate data "remotely" (from another function).

func (v Vertex) SetX(x int) {
    v.X = x
}

func main() {
    v := Vertex{3, 4}
    fmt.Println(v)
    v.SetX(1)
    fmt.Println(v)
}

As you'll note, this doesn't change anything (strictly speaking, it changes a copy of the vertex, but that's just semantics in most cases)! The value of v is still {3,4}. Trying instead with:

func (v *Vertex) SetX(x int) {
    v.X = x
}

func main() {
    v := &Vertex{3, 4}
    fmt.Println(v)
    v.SetX(1)
    fmt.Println(v)
}

And suddenly, it works, the second time it prints {1,4}. Now, if you're curious, you may decide to experiment and change v := &Vertex{3, 4} to v := Vertex{3, 4}. Indeed, the above snippet still works. Strange. Likewise, if you change the same line in the second snippet to contain a pointer, it also works the same way.

Why? Go has "transparent" pointers. In other languages with explicit pointer values like C or C++, you have to explicitly use the operators & and * to dereference a pointer. C and C++ even have special syntax for pointer chasing on field access and method calls v->SetX.

For better or worse, Go hides this from you. If you have a value and need to call a pointer method, Go will happily do (&v).Method() for you, if you need to dereference to call a value method, it happily does (*v).Method() automatically. This is true in most cases, there are a few corner cases with things like maps where this doesn't apply, but in general this holds.

So, when it comes down to it, when should you use a pointer receiver on a method? The answer, really, is "most of the time." The Go Style Guide generally recommends using pointer type method receivers except when the receiver is a direct alias for a map, func, or chan, it's a slice that doesn't need reslicing, or you're doing optimizations on small, immutable data types (because pointer chasing is a little bit slower than copying). I'd add to that that you generally shouldn't use direct pointers to pointers.

Generally, when you have no idea which to use, use a pointer receiver. 99% of the time using a pointer will give you the behavior you expect, especially if you're used to languages like Python or C#. It's comparatively rare that incorrectly using a pointer causes a bug, compared the probability of getting a bug because your Setter method isn't actually setting anything.

This particular example is bad because the method defined on pointer type, *Vertex, does not attempt to mutate the value of its receiver (the value the method is called on).

In Go, everything is ever passed/assigned by value &mdash; including pointers. So, when you have a method

func (v Vertex) Abs() float64 {
    return math.Sqrt(v.X*v.X + v.Y*v.Y)
}

(notice there's no * in front of Vertex in the receiver's type specification), it works just OK because when you do

v := Vertex{2, 3}
x := v.Abs()

the value of v at the v.Abs() call site is copied to the value the Abs() method receives.

Now suppose you want to change (mutate) some of the Vertex's variables using a method call. A naive approach, like in,

func (v Vertex) SetX(x float64) {
    v.X = x
}

v := Vertex{2, 3}
v.SetX(-5)
// Here, v.X is still 2

won't work because it will change X of the value v which has been copied to the callee when the call was made; the method changed the X of the copy&mdash;a change only seen in the method's scope.

On the other hand, if you were to define that method on the pointer (which holds the address of an actual variable holding a value instead of the value itself), that would work:

func (v *Vertex) SetX(x float64) {
    v.X = x
}

v := Vertex{2, 3}
v.SetX(-5)

Here, the compiler would take the address of v at the point SetX() is called and pass it to the method. The method would then use that address to refer to the value in the caller's scope.

The syntactic confusion is because Go (in most cases) allows you to not use operators to take address of a value and dereference that address.

If you're coming from one of popular languages like PHP, Python etc the chief difference is that in many of them objects are "special" and are always passed by reference. Go is more low-level and tries not to use magic behind programmer's back, so you have to be explicit about whether you want to pass a pointer or a copy of the value to a method.

Note that this is not only about whether a method is able or is not able to mutate its receiver; performance things might also play a role here.