Slices: The Three-Word Header

"A slice is a descriptor of an array segment. It consists of a pointer to the array, the length of the segment, and its capacity." — Go Blog, "Go Slices: usage and internals"

Part I established that a slice is "a value containing a pointer", which was enough to explain why copying one shares data. It is not enough to explain append, and append is where slices get their reputation.

Three fields. That is the whole data structure: a pointer to an array, a length, and a capacity. Every behaviour that has ever surprised you about slices falls out of those three fields and one rule about what append does when the capacity runs out — and once you can predict that rule, the surprises stop.

Consider the two facts that seem to contradict each other. Pass a slice to a function, write to s[0], and the caller sees it. Pass a slice to a function, append to it, and the caller usually does not. Both follow from the header. Writing to s[0] goes through the pointer, which the copy shares. append may need a bigger array, and when it allocates one it returns a new header pointing somewhere else — which the caller never receives, because the caller's header was copied on the way in.

"Usually does not" is the part that makes this dangerous rather than merely confusing. Whether the caller sees an appended element depends on whether there was spare capacity, which depends on how the slice was built, which is not visible at the call site. Code that works with one input silently breaks with another.

So this chapter takes the header apart: what the three fields do, exactly when append reallocates, how slicing shares an array and how to stop it, what actually copies, and the memory leak that a three-field header makes possible. It is the most mechanical chapter in the volume and the one that pays off most often.

Three fields

Start by making the header visible, because len and cap are the only windows onto it.

The distinction at the end matters more than it looks. A nil slice and an empty slice have the same length, the same capacity, and behave identically for len, range, and append — but they are different values, and == nil can tell them apart. Part I noted that encoding/json renders one as null and the other as []. This is where that difference lives: in the pointer field.

The c[3] panic is the clearest demonstration that len and cap are genuinely separate. Capacity is not a permission to read; it is a promise about how much room exists before append needs new memory. Indexing is bounded by length.

When append reallocates

Here is the rule, and it is short: if there is spare capacity, append writes into the existing array and returns a header with a longer length. If there is not, it allocates a bigger array, copies everything across, and returns a header pointing at the new one.

The addBroken demonstration is worth reading twice, because the failure is worse than "the caller does not see it". With spare capacity, the append genuinely writes a 99 into the caller's array at index 1 — a slot the caller's header does not cover. The caller sees nothing now. But if the caller later appends its own element, it overwrites that 99, or worse, another slice over the same array with a longer length can see it.

That is the whole argument for the convention: a function that grows a slice must return it. Not because returning is tidier, but because the alternative is correct only when capacity happens to be exhausted, and silently corrupting when it is not.

Slicing shares, and how to stop it

A slice expression makes a new header over the same array. That is cheap and usually what you want, and occasionally it is a bug with teeth.

The three-index slice expression is the least-known genuinely important piece of slice syntax. s[low:high:max] sets the capacity explicitly, and s[a:b:b] produces a slice with zero spare capacity — so any append to it must allocate, and therefore cannot reach into the original array.

The use case to remember is returning a subslice of internal state. If a method returns s.buf[0:n], the caller receives a slice whose capacity extends across the rest of your buffer, and a single append on their side writes into your data. Returning s.buf[0:n:n] costs one character and makes that impossible.

What actually copies

Three idioms produce an independent slice, and one thing that looks like it does, does not.

The make([]T, 0, n) followed by copy mistake is worth committing to memory because it produces an empty slice with no error and no panic. copy is bounded by the length of the destination, and a destination of length 0 copies nothing regardless of its capacity. The fix is make([]T, len(src)) — length, not capacity.

The delete idiom in the last block is the standard one, and the comment on it is the important part: it shifts the tail left inside the existing array, so the final element remains in memory beyond the new length. For a slice of ints that is harmless. For a slice of pointers it is a leak, which is the next section.

The leak a three-field header allows

Because a slice keeps a pointer into an array, a small slice can keep a large array alive. The garbage collector frees arrays, not ranges.

This is the subtlest slice problem and the one most likely to appear as "our memory usage grows and we cannot see why". A slice of length 2 over an array of ten thousand keeps all ten thousand alive, along with everything they point at. Nothing in len, in printing, or in reading the code makes that visible — the only tell is cap.

The pointer-zeroing version of the delete idiom is the one to remember for slices of pointers. append(s[:i], s[i+1:]...) shifts the tail left and leaves a duplicate of the last pointer in the slot beyond the new length, keeping that object alive indefinitely. Setting the vacated slot to nil before shrinking costs one line.

Common Mistakes

1. A function that appends without returning the slice. Correct only when capacity happened to be exhausted, and silently writing into the caller's array when it was not.

2. Assuming t := append(s, x) gives an independent slice. Whether t and s share an array depends on cap(s), which is decided elsewhere.

3. Appending to a subslice. arr[2:5] has capacity to the end of the array, so append overwrites arr[5].

4. Returning a subslice of internal state without the third index. buf[0:n] hands the caller capacity across the rest of your buffer; buf[0:n:n] does not.

5. make([]T, 0, n) followed by copy. copy is bounded by destination length, so this copies nothing. Use make([]T, len(src)).

6. Confusing cap with permission to index. Reading past len panics however much capacity exists.

7. Keeping a small slice of a large array. The array cannot be freed while any slice points into it; copy if you are keeping only a part.

8. Using append(s[:i], s[i+1:]...) on a slice of pointers. The vacated slot beyond the new length still holds a pointer; nil it first.

9. Treating nil and empty slices as identical. They behave the same for len, range and append, differ under == nil, and marshal to null versus [].

10. Relying on the growth factor. It is implementation-defined and has changed; rely only on "append may reallocate".

Interview Corner

Summary

• A slice is three fields: a pointer to an array, a length and a capacity. Every surprise follows from those.

• len bounds indexing; cap bounds append before reallocation. Reading past len panics however much capacity exists.

• append writes in place when there is spare capacity and allocates a new array when there is not, returning a header pointing at whichever.

• So a function that appends must return the slice — the no-return version is correct only by accident of capacity, and writes into the caller's array otherwise.

• A slice expression shares the array, and capacity extends to the end of it, so appending to arr[2:5] overwrites arr[5].

• s[low:high:max] sets capacity explicitly, and s[a:b:b] gives no spare room — the right form for returning a subslice of internal state.

• copy is bounded by destination length, so make([]T, 0, n) then copy copies nothing.

• make+copy, append([]T(nil), s...) and append([]T{}, s...) all produce independent slices; assignment and slicing do not.

• A small slice keeps its whole array alive — a leak only cap reveals — and deleting from a slice of pointers should nil the vacated slot, or the removed object stays reachable past the new length.

• The growth factor is implementation-defined and has changed between releases.

Slices are a window onto an array. The next structure has no array to point at, no addressable elements, and an iteration order that is deliberately randomised so you cannot depend on it — and its zero value, as Part I established, is readable but not writable. The next chapter is Maps and Their Rules.