package binary

Import Path
	encoding/binary (on go.dev)

Dependency Relation
	imports 6 packages, and imported by 26 packages


Involved Source Files

	
		Package binary implements simple translation between numbers and byte
		sequences and encoding and decoding of varints.
		
		Numbers are translated by reading and writing fixed-size values.
		A fixed-size value is either a fixed-size arithmetic
		type (bool, int8, uint8, int16, float32, complex64, ...)
		or an array or struct containing only fixed-size values.
		
		The varint functions encode and decode single integer values using
		a variable-length encoding; smaller values require fewer bytes.
		For a specification, see
		https://developers.google.com/protocol-buffers/docs/encoding.
		
		This package favors simplicity over efficiency. Clients that require
		high-performance serialization, especially for large data structures,
		should look at more advanced solutions such as the [encoding/gob]
		package or [google.golang.org/protobuf] for protocol buffers.

	    native_endian_little.go
	    varint.go


Code Examples

	
		package main
		
		import (
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			b := []byte{0xe8, 0x03, 0xd0, 0x07}
			x1 := binary.LittleEndian.Uint16(b[0:])
			x2 := binary.LittleEndian.Uint16(b[2:])
			fmt.Printf("%#04x %#04x\n", x1, x2)
		}

	
		package main
		
		import (
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			b := make([]byte, 4)
			binary.LittleEndian.PutUint16(b[0:], 0x03e8)
			binary.LittleEndian.PutUint16(b[2:], 0x07d0)
			fmt.Printf("% x\n", b)
		}

	
		package main
		
		import (
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			buf := make([]byte, binary.MaxVarintLen64)
		
			for _, x := range []uint64{1, 2, 127, 128, 255, 256} {
				n := binary.PutUvarint(buf, x)
				fmt.Printf("%x\n", buf[:n])
			}
		}

	
		package main
		
		import (
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			buf := make([]byte, binary.MaxVarintLen64)
		
			for _, x := range []int64{-65, -64, -2, -1, 0, 1, 2, 63, 64} {
				n := binary.PutVarint(buf, x)
				fmt.Printf("%x\n", buf[:n])
			}
		}

	
		package main
		
		import (
			"bytes"
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			var pi float64
			b := []byte{0x18, 0x2d, 0x44, 0x54, 0xfb, 0x21, 0x09, 0x40}
			buf := bytes.NewReader(b)
			err := binary.Read(buf, binary.LittleEndian, &pi)
			if err != nil {
				fmt.Println("binary.Read failed:", err)
			}
			fmt.Print(pi)
		}

	
		package main
		
		import (
			"bytes"
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			b := []byte{0x18, 0x2d, 0x44, 0x54, 0xfb, 0x21, 0x09, 0x40, 0xff, 0x01, 0x02, 0x03, 0xbe, 0xef}
			r := bytes.NewReader(b)
		
			var data struct {
				PI   float64
				Uate uint8
				Mine [3]byte
				Too  uint16
			}
		
			if err := binary.Read(r, binary.LittleEndian, &data); err != nil {
				fmt.Println("binary.Read failed:", err)
			}
		
			fmt.Println(data.PI)
			fmt.Println(data.Uate)
			fmt.Printf("% x\n", data.Mine)
			fmt.Println(data.Too)
		}

	
		package main
		
		import (
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			inputs := [][]byte{
				{0x01},
				{0x02},
				{0x7f},
				{0x80, 0x01},
				{0xff, 0x01},
				{0x80, 0x02},
			}
			for _, b := range inputs {
				x, n := binary.Uvarint(b)
				if n != len(b) {
					fmt.Println("Uvarint did not consume all of in")
				}
				fmt.Println(x)
			}
		}

	
		package main
		
		import (
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			inputs := [][]byte{
				{0x81, 0x01},
				{0x7f},
				{0x03},
				{0x01},
				{0x00},
				{0x02},
				{0x04},
				{0x7e},
				{0x80, 0x01},
			}
			for _, b := range inputs {
				x, n := binary.Varint(b)
				if n != len(b) {
					fmt.Println("Varint did not consume all of in")
				}
				fmt.Println(x)
			}
		}

	
		package main
		
		import (
			"bytes"
			"encoding/binary"
			"fmt"
			"math"
		)
		
		func main() {
			buf := new(bytes.Buffer)
			var pi float64 = math.Pi
			err := binary.Write(buf, binary.LittleEndian, pi)
			if err != nil {
				fmt.Println("binary.Write failed:", err)
			}
			fmt.Printf("% x", buf.Bytes())
		}

	
		package main
		
		import (
			"bytes"
			"encoding/binary"
			"fmt"
		)
		
		func main() {
			buf := new(bytes.Buffer)
			var data = []any{
				uint16(61374),
				int8(-54),
				uint8(254),
			}
			for _, v := range data {
				err := binary.Write(buf, binary.LittleEndian, v)
				if err != nil {
					fmt.Println("binary.Write failed:", err)
				}
			}
			fmt.Printf("%x", buf.Bytes())
		}




Package-Level Type Names (total 8, in which 2 are exported)


	/* sort exporteds by:  |  */
	
		AppendByteOrder specifies how to append 16-, 32-, or 64-bit unsigned integers
		into a byte slice.
		
		It is implemented by [LittleEndian], [BigEndian], and [NativeEndian].

		
			( AppendByteOrder) AppendUint16([]byte, uint16) []byte
			( AppendByteOrder) AppendUint32([]byte, uint32) []byte
			( AppendByteOrder) AppendUint64([]byte, uint64) []byte
			( AppendByteOrder) String() string
		
			
		
			 AppendByteOrder : expvar.Var
			 AppendByteOrder : fmt.Stringer
			


	
		A ByteOrder specifies how to convert byte slices into
		16-, 32-, or 64-bit unsigned integers.
		
		It is implemented by [LittleEndian], [BigEndian], and [NativeEndian].

		
			( ByteOrder) PutUint16([]byte, uint16)
			( ByteOrder) PutUint32([]byte, uint32)
			( ByteOrder) PutUint64([]byte, uint64)
			( ByteOrder) String() string
			( ByteOrder) Uint16([]byte) uint16
			( ByteOrder) Uint32([]byte) uint32
			( ByteOrder) Uint64([]byte) uint64
		
			
		
			 ByteOrder : expvar.Var
			 ByteOrder : fmt.Stringer
			
		
			func Append(buf []byte, order ByteOrder, data any) ([]byte, error)
			func Decode(buf []byte, order ByteOrder, data any) (int, error)
			func Encode(buf []byte, order ByteOrder, data any) (int, error)
			func Read(r io.Reader, order ByteOrder, data any) error
			func Write(w io.Writer, order ByteOrder, data any) error
			


	


Package-Level Functions (total 20, in which 14 are exported)


	
		Append appends the binary representation of data to buf.
		buf may be nil, in which case a new buffer will be allocated.
		See [Write] on which data are acceptable.
		It returns the (possibly extended) buffer containing data or an error.


	
		AppendUvarint appends the varint-encoded form of x,
		as generated by [PutUvarint], to buf and returns the extended buffer.


	
		AppendVarint appends the varint-encoded form of x,
		as generated by [PutVarint], to buf and returns the extended buffer.


	
		Decode decodes binary data from buf into data according to
		the given byte order.
		It returns an error if buf is too small, otherwise the number of
		bytes consumed from buf.


	
		Encode encodes the binary representation of data into buf according to
		the given byte order.
		It returns an error if buf is too small, otherwise the number of
		bytes written into buf.


	
		PutUvarint encodes a uint64 into buf and returns the number of bytes written.
		If the buffer is too small, PutUvarint will panic.


	
		PutVarint encodes an int64 into buf and returns the number of bytes written.
		If the buffer is too small, PutVarint will panic.


	
		Read reads structured binary data from r into data.
		Data must be a pointer to a fixed-size value or a slice
		of fixed-size values.
		Bytes read from r are decoded using the specified byte order
		and written to successive fields of the data.
		When decoding boolean values, a zero byte is decoded as false, and
		any other non-zero byte is decoded as true.
		When reading into structs, the field data for fields with
		blank (_) field names is skipped; i.e., blank field names
		may be used for padding.
		When reading into a struct, all non-blank fields must be exported
		or Read may panic.
		
		The error is [io.EOF] only if no bytes were read.
		If an [io.EOF] happens after reading some but not all the bytes,
		Read returns [io.ErrUnexpectedEOF].


	
		ReadUvarint reads an encoded unsigned integer from r and returns it as a uint64.
		The error is [io.EOF] only if no bytes were read.
		If an [io.EOF] happens after reading some but not all the bytes,
		ReadUvarint returns [io.ErrUnexpectedEOF].


	
		ReadVarint reads an encoded signed integer from r and returns it as an int64.
		The error is [io.EOF] only if no bytes were read.
		If an [io.EOF] happens after reading some but not all the bytes,
		ReadVarint returns [io.ErrUnexpectedEOF].


	
		Size returns how many bytes [Write] would generate to encode the value v, which
		must be a fixed-size value or a slice of fixed-size values, or a pointer to such data.
		If v is neither of these, Size returns -1.


	
		Uvarint decodes a uint64 from buf and returns that value and the
		number of bytes read (> 0). If an error occurred, the value is 0
		and the number of bytes n is <= 0 meaning:
		  - n == 0: buf too small;
		  - n < 0: value larger than 64 bits (overflow) and -n is the number of
		    bytes read.


	
		Varint decodes an int64 from buf and returns that value and the
		number of bytes read (> 0). If an error occurred, the value is 0
		and the number of bytes n is <= 0 with the following meaning:
		  - n == 0: buf too small;
		  - n < 0: value larger than 64 bits (overflow)
		    and -n is the number of bytes read.


	
		Write writes the binary representation of data into w.
		Data must be a fixed-size value or a slice of fixed-size
		values, or a pointer to such data.
		Boolean values encode as one byte: 1 for true, and 0 for false.
		Bytes written to w are encoded using the specified byte order
		and read from successive fields of the data.
		When writing structs, zero values are written for fields
		with blank (_) field names.


	


Package-Level Variables (total 6, in which 3 are exported)


	
		BigEndian is the big-endian implementation of [ByteOrder] and [AppendByteOrder].


	
		LittleEndian is the little-endian implementation of [ByteOrder] and [AppendByteOrder].


	
		NativeEndian is the native-endian implementation of [ByteOrder] and [AppendByteOrder].


	


Package-Level Constants (total 3, all are exported)


	
		MaxVarintLenN is the maximum length of a varint-encoded N-bit integer.


	
		MaxVarintLenN is the maximum length of a varint-encoded N-bit integer.


	
		MaxVarintLenN is the maximum length of a varint-encoded N-bit integer.