What does hash.Hash's Sum(b []byte) method do to b and to the hash's internal state?

## The signature that surprises people ```go type Hash interface { io.Writer Sum(b []byte) []byte Reset() Size() int BlockSize() int } ``` Read naively, `Sum(b []byte)` looks like it hashes `b`. It does not. The doc comment is precise: *Sum appends the current hash to b and returns the resulting slice. It does not change the underlying hash state.* Two independent facts live in that sentence, and both are load-bearing. ### Fact one: the argument is a destination `Sum` behaves like `append`. It writes the digest onto the end of whatever slice you pass and returns the grown slice. ```go h := sha256.New() h.Write(body) d := h.Sum(nil) // 32 bytes: just the digest out := h.Sum([]byte("v1:")) // "v1:" + 32 raw bytes, one slice ``` The `nil` form is overwhelmingly the common one: `nil` is a perfectly good empty slice to append to, so `Sum(nil)` allocates a fresh 32-byte result. The non-nil form exists so you can build a framed value without a second allocation, or reuse a scratch buffer across a loop (`buf = h.Sum(buf[:0])`). Ordinary `append` rules apply: if the destination has spare capacity the digest lands in place, otherwise a new array is allocated. The reason the API is shaped this way at all is allocation control. `hash.Hash` is used in hot paths, and a method that always allocated its own return value would be impossible to tune. ### Fact two: the hash keeps running `Sum` computes the finalisation - the padding and length encoding SHA-256 appends before producing its output - on a **copy** of the internal state. Your hash is untouched. ```go h := sha256.New() h.Write([]byte("a")) d1 := h.Sum(nil) // digest of "a" h.Write([]byte("b")) d2 := h.Sum(nil) // digest of "ab", not of "b" ``` This is genuinely useful: you can emit a running digest at checkpoints while continuing to consume a stream. It is also the source of a quiet class of bugs. A loop that hashes many inputs with one reused hash: ```go h := sha256.New() for _, item := range items { h.Write(item) digests = append(digests, h.Sum(nil)) // wrong: each covers all prior items } ``` Every digest after the first is over a growing concatenation. Nothing errors. Every value is a well-formed 32-byte digest and encodes to plausible hex. The fix is one line - `h.Reset()` at the top of each iteration - and `Reset` is a separate method precisely because `Sum` deliberately does not do it. ### Reset, Size and BlockSize - `Reset()` returns the hash to the state it had immediately after construction. For a keyed hash built by `hmac.New`, it resets to the initial **keyed** state - the key is not forgotten. - `Size()` tells you how many bytes `Sum` will append: 32 for SHA-256, matching the `sha256.Size` constant. Write generic code against `h.Size()` rather than a literal. - `BlockSize()` is the algorithm's internal block width (64 for SHA-256) and matters mainly to constructions layered on top of a hash. ### What Sum is not - It is not a comparison, an encoder, or a reset. - It does not consume its argument as input. `h.Sum(data)` is a common misreading and produces a digest that ignores `data` entirely while prepending it to the output. - Its result is not a fixed-size array. If you want a comparable value you must copy into one, or use the one-shot `sha256.Sum256` instead. ### The habit to build Read `h.Sum(x)` as "give me `x` with the digest stuck on the end, and leave the hash alone." Then, whenever a `hash.Hash` outlives a single message - a loop, a long-lived struct field, a pooled value - ask where the `Reset()` is. If you cannot point at it, the digests are wrong.