Byte Order with encoding/binary

## The problem byte order solves A number larger than one byte has to be split across several bytes when it travels over a wire or lands in a file. The value 256 is `0x0100` in hex: one byte holding `0x01` and one holding `0x00`. Nothing in the bytes themselves says which of the two comes first. That choice is the **byte order**, or *endianness*. - **Big-endian** puts the most significant byte first: 256 as four bytes is `00 00 01 00`. - **Little-endian** puts the least significant byte first: 256 as four bytes is `00 01 00 00`. So the byte sequence `00 00 01 00` does not have one correct interpretation. Read big-endian it is `0x00000100` = **256**. Read little-endian it is `0x00010000` = **65536**. Both readings are valid; only the format's specification says which one is intended. ## What `encoding/binary` gives you The package exposes two package-level values, `binary.BigEndian` and `binary.LittleEndian`. They are values, not functions, and both satisfy the `binary.ByteOrder` interface: - `Uint16(b []byte) uint16`, `Uint32(b []byte) uint32`, `Uint64(b []byte) uint64` — decode from a byte slice. - `PutUint16(b []byte, v uint16)`, `PutUint32`, `PutUint64` — encode into a byte slice the caller already allocated. Because they are ordinary values, you can pass one around as a `binary.ByteOrder` parameter and let a single decoder handle a format that comes in both flavours: ```go func readHeader(b []byte, order binary.ByteOrder) uint32 { return order.Uint32(b) } ``` ## Bounds, not errors The accessors return no error. `Uint32` requires at least 4 bytes and `Uint64` at least 8; hand it a shorter slice and it **panics with an index out of range**. Likewise `PutUint32` writes into the slice you give it and never grows it — `make([]byte, 4)` first, or use the `AppendUint32` form to append onto an existing slice. This is a deliberate design: these are the fast path, so the checks are the ones the runtime already performs on a slice index. ## Choosing an order You do not choose based on your CPU. You choose based on the format you are speaking: - Internet protocol headers are conventionally big-endian, which is why big-endian is often called *network byte order*. - Plenty of device protocols, sensor frames and on-disk formats are little-endian because the hardware that produced them was. The practical rule is that both ends must name the same order explicitly. Two programs that each "just use the natural one" agree only by luck, and the failure is silent: you do not get an error, you get a plausible-looking wrong number. ## Floats and signed values There is no `PutFloat64`. Convert the bit pattern yourself with `math.Float64bits` and write it as a `uint64`, then read it back with `math.Float64frombits`. Signed integers are handled the same way — write the two's-complement bit pattern as the unsigned type of the same width and convert on the way out (`int32(binary.BigEndian.Uint32(b))`). ## A worked round trip ```go b := []byte{0x00, 0x00, 0x01, 0x00} binary.BigEndian.Uint32(b) // 256 binary.LittleEndian.Uint32(b) // 65536 out := make([]byte, 4) binary.LittleEndian.PutUint32(out, 256) // out is now 00 01 00 00 — the same number, the other order ``` Encoding 256 with one order and decoding with the other gives you 16777216, not 256. That asymmetry — a number that comes back multiplied or divided by a power of 256, or byte-swapped into something absurd — is the fingerprint of a byte-order mistake, and recognising it on sight is most of the value of understanding this.