path: root/devdocs/go/encoding%2Fbinary%2Findex.html

<h1> Package binary  </h1>     <ul id="short-nav">
<li><code>import "encoding/binary"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
<li><a href="#pkg-examples" class="examplesLink">Examples</a></li>
</ul>     <h2 id="pkg-overview">Overview </h2> <p>Package binary implements simple translation between numbers and byte sequences and encoding and decoding of varints. </p>
<p>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. </p>
<p>The varint functions encode and decode single integer values using a variable-length encoding; smaller values require fewer bytes. For a specification, see <a href="https://developers.google.com/protocol-buffers/docs/encoding">https://developers.google.com/protocol-buffers/docs/encoding</a>. </p>
<p>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 <span>encoding/gob</span> package or <span>google.golang.org/protobuf</span> for protocol buffers. </p>     <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
<li><a href="#pkg-constants">Constants</a></li>
<li><a href="#pkg-variables">Variables</a></li>
<li><a href="#AppendUvarint">func AppendUvarint(buf []byte, x uint64) []byte</a></li>
<li><a href="#AppendVarint">func AppendVarint(buf []byte, x int64) []byte</a></li>
<li><a href="#PutUvarint">func PutUvarint(buf []byte, x uint64) int</a></li>
<li><a href="#PutVarint">func PutVarint(buf []byte, x int64) int</a></li>
<li><a href="#Read">func Read(r io.Reader, order ByteOrder, data any) error</a></li>
<li><a href="#ReadUvarint">func ReadUvarint(r io.ByteReader) (uint64, error)</a></li>
<li><a href="#ReadVarint">func ReadVarint(r io.ByteReader) (int64, error)</a></li>
<li><a href="#Size">func Size(v any) int</a></li>
<li><a href="#Uvarint">func Uvarint(buf []byte) (uint64, int)</a></li>
<li><a href="#Varint">func Varint(buf []byte) (int64, int)</a></li>
<li><a href="#Write">func Write(w io.Writer, order ByteOrder, data any) error</a></li>
<li><a href="#AppendByteOrder">type AppendByteOrder</a></li>
<li><a href="#ByteOrder">type ByteOrder</a></li>
</ul> <div id="pkg-examples"> <h3>Examples</h3>  <dl> <dd><a class="exampleLink" href="#example_ByteOrder_get">ByteOrder (Get)</a></dd> <dd><a class="exampleLink" href="#example_ByteOrder_put">ByteOrder (Put)</a></dd> <dd><a class="exampleLink" href="#example_PutUvarint">PutUvarint</a></dd> <dd><a class="exampleLink" href="#example_PutVarint">PutVarint</a></dd> <dd><a class="exampleLink" href="#example_Read">Read</a></dd> <dd><a class="exampleLink" href="#example_Read_multi">Read (Multi)</a></dd> <dd><a class="exampleLink" href="#example_Uvarint">Uvarint</a></dd> <dd><a class="exampleLink" href="#example_Varint">Varint</a></dd> <dd><a class="exampleLink" href="#example_Write">Write</a></dd> <dd><a class="exampleLink" href="#example_Write_multi">Write (Multi)</a></dd> </dl> </div> <h3>Package files</h3> <p>  <span>binary.go</span> <span>native_endian_little.go</span> <span>varint.go</span>  </p>   <h2 id="pkg-constants">Constants</h2> <p>MaxVarintLenN is the maximum length of a varint-encoded N-bit integer. </p>
<pre data-language="go">const (
    MaxVarintLen16 = 3
    MaxVarintLen32 = 5
    MaxVarintLen64 = 10
)</pre> <h2 id="pkg-variables">Variables</h2> <p>BigEndian is the big-endian implementation of <a href="#ByteOrder">ByteOrder</a> and <a href="#AppendByteOrder">AppendByteOrder</a>. </p>
<pre data-language="go">var BigEndian bigEndian</pre> <p>LittleEndian is the little-endian implementation of <a href="#ByteOrder">ByteOrder</a> and <a href="#AppendByteOrder">AppendByteOrder</a>. </p>
<pre data-language="go">var LittleEndian littleEndian</pre> <p>NativeEndian is the native-endian implementation of <a href="#ByteOrder">ByteOrder</a> and <a href="#AppendByteOrder">AppendByteOrder</a>. </p>
<pre data-language="go">var NativeEndian nativeEndian</pre> <h2 id="AppendUvarint">func <span>AppendUvarint</span>  <span title="Added in Go 1.19">1.19</span> </h2> <pre data-language="go">func AppendUvarint(buf []byte, x uint64) []byte</pre> <p>AppendUvarint appends the varint-encoded form of x, as generated by <a href="#PutUvarint">PutUvarint</a>, to buf and returns the extended buffer. </p>
<h2 id="AppendVarint">func <span>AppendVarint</span>  <span title="Added in Go 1.19">1.19</span> </h2> <pre data-language="go">func AppendVarint(buf []byte, x int64) []byte</pre> <p>AppendVarint appends the varint-encoded form of x, as generated by <a href="#PutVarint">PutVarint</a>, to buf and returns the extended buffer. </p>
<h2 id="PutUvarint">func <span>PutUvarint</span>  </h2> <pre data-language="go">func PutUvarint(buf []byte, x uint64) int</pre> <p>PutUvarint encodes a uint64 into buf and returns the number of bytes written. If the buffer is too small, PutUvarint will panic. </p>   <h4 id="example_PutUvarint"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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])
}
</pre> <p>Output:</p> <pre class="output" data-language="go">01
02
7f
8001
ff01
8002
</pre>   <h2 id="PutVarint">func <span>PutVarint</span>  </h2> <pre data-language="go">func PutVarint(buf []byte, x int64) int</pre> <p>PutVarint encodes an int64 into buf and returns the number of bytes written. If the buffer is too small, PutVarint will panic. </p>   <h4 id="example_PutVarint"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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])
}
</pre> <p>Output:</p> <pre class="output" data-language="go">8101
7f
03
01
00
02
04
7e
8001
</pre>   <h2 id="Read">func <span>Read</span>  </h2> <pre data-language="go">func Read(r io.Reader, order ByteOrder, data any) error</pre> <p>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. </p>
<p>The error is <span>io.EOF</span> only if no bytes were read. If an <span>io.EOF</span> happens after reading some but not all the bytes, Read returns <span>io.ErrUnexpectedEOF</span>. </p>   <h4 id="example_Read"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">var pi float64
b := []byte{0x18, 0x2d, 0x44, 0x54, 0xfb, 0x21, 0x09, 0x40}
buf := bytes.NewReader(b)
err := binary.Read(buf, binary.LittleEndian, &amp;pi)
if err != nil {
    fmt.Println("binary.Read failed:", err)
}
fmt.Print(pi)
</pre> <p>Output:</p> <pre class="output" data-language="go">3.141592653589793
</pre>      <h4 id="example_Read_multi"> <span class="text">Example (Multi)</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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, &amp;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)
</pre> <p>Output:</p> <pre class="output" data-language="go">3.141592653589793
255
01 02 03
61374
</pre>   <h2 id="ReadUvarint">func <span>ReadUvarint</span>  </h2> <pre data-language="go">func ReadUvarint(r io.ByteReader) (uint64, error)</pre> <p>ReadUvarint reads an encoded unsigned integer from r and returns it as a uint64. The error is <span>io.EOF</span> only if no bytes were read. If an <span>io.EOF</span> happens after reading some but not all the bytes, ReadUvarint returns <span>io.ErrUnexpectedEOF</span>. </p>
<h2 id="ReadVarint">func <span>ReadVarint</span>  </h2> <pre data-language="go">func ReadVarint(r io.ByteReader) (int64, error)</pre> <p>ReadVarint reads an encoded signed integer from r and returns it as an int64. The error is <span>io.EOF</span> only if no bytes were read. If an <span>io.EOF</span> happens after reading some but not all the bytes, ReadVarint returns <span>io.ErrUnexpectedEOF</span>. </p>
<h2 id="Size">func <span>Size</span>  </h2> <pre data-language="go">func Size(v any) int</pre> <p>Size returns how many bytes <a href="#Write">Write</a> 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. </p>
<h2 id="Uvarint">func <span>Uvarint</span>  </h2> <pre data-language="go">func Uvarint(buf []byte) (uint64, int)</pre> <p>Uvarint decodes a uint64 from buf and returns that value and the number of bytes read (&gt; 0). If an error occurred, the value is 0 and the number of bytes n is &lt;= 0 meaning: </p>
<pre data-language="go">n == 0: buf too small
n  &lt; 0: value larger than 64 bits (overflow)
        and -n is the number of bytes read
</pre>    <h4 id="example_Uvarint"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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)
}
</pre> <p>Output:</p> <pre class="output" data-language="go">1
2
127
128
255
256
</pre>   <h2 id="Varint">func <span>Varint</span>  </h2> <pre data-language="go">func Varint(buf []byte) (int64, int)</pre> <p>Varint decodes an int64 from buf and returns that value and the number of bytes read (&gt; 0). If an error occurred, the value is 0 and the number of bytes n is &lt;= 0 with the following meaning: </p>
<pre data-language="go">n == 0: buf too small
n  &lt; 0: value larger than 64 bits (overflow)
        and -n is the number of bytes read
</pre>    <h4 id="example_Varint"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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)
}
</pre> <p>Output:</p> <pre class="output" data-language="go">-65
-64
-2
-1
0
1
2
63
64
</pre>   <h2 id="Write">func <span>Write</span>  </h2> <pre data-language="go">func Write(w io.Writer, order ByteOrder, data any) error</pre> <p>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. </p>   <h4 id="example_Write"> <span class="text">Example</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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())
</pre> <p>Output:</p> <pre class="output" data-language="go">18 2d 44 54 fb 21 09 40
</pre>      <h4 id="example_Write_multi"> <span class="text">Example (Multi)</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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())
</pre> <p>Output:</p> <pre class="output" data-language="go">beefcafe
</pre>   <h2 id="AppendByteOrder">type <span>AppendByteOrder</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>AppendByteOrder specifies how to append 16-, 32-, or 64-bit unsigned integers into a byte slice. </p>
<p>It is implemented by <a href="#LittleEndian">LittleEndian</a>, <a href="#BigEndian">BigEndian</a>, and <a href="#NativeEndian">NativeEndian</a>. </p>
<pre data-language="go">type AppendByteOrder interface {
    AppendUint16([]byte, uint16) []byte
    AppendUint32([]byte, uint32) []byte
    AppendUint64([]byte, uint64) []byte
    String() string
}</pre> <h2 id="ByteOrder">type <span>ByteOrder</span>  </h2> <p>A ByteOrder specifies how to convert byte slices into 16-, 32-, or 64-bit unsigned integers. </p>
<p>It is implemented by <a href="#LittleEndian">LittleEndian</a>, <a href="#BigEndian">BigEndian</a>, and <a href="#NativeEndian">NativeEndian</a>. </p>
<pre data-language="go">type ByteOrder interface {
    Uint16([]byte) uint16
    Uint32([]byte) uint32
    Uint64([]byte) uint64
    PutUint16([]byte, uint16)
    PutUint32([]byte, uint32)
    PutUint64([]byte, uint64)
    String() string
}</pre>    <h4 id="example_ByteOrder_get"> <span class="text">Example (Get)</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">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)
</pre> <p>Output:</p> <pre class="output" data-language="go">0x03e8 0x07d0
</pre>      <h4 id="example_ByteOrder_put"> <span class="text">Example (Put)</span>
</h4> <p>Code:</p> <pre class="code" data-language="go">b := make([]byte, 4)
binary.LittleEndian.PutUint16(b[0:], 0x03e8)
binary.LittleEndian.PutUint16(b[2:], 0x07d0)
fmt.Printf("% x\n", b)
</pre> <p>Output:</p> <pre class="output" data-language="go">e8 03 d0 07
</pre><div class="_attribution">
  <p class="_attribution-p">
    &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
    <a href="http://golang.org/pkg/encoding/binary/" class="_attribution-link">http://golang.org/pkg/encoding/binary/</a>
  </p>
</div>