diff options
Diffstat (limited to 'devdocs/go/encoding%2Fbinary%2Findex.html')
| -rw-r--r-- | devdocs/go/encoding%2Fbinary%2Findex.html | 217 |
1 files changed, 0 insertions, 217 deletions
diff --git a/devdocs/go/encoding%2Fbinary%2Findex.html b/devdocs/go/encoding%2Fbinary%2Findex.html deleted file mode 100644 index d018b748..00000000 --- a/devdocs/go/encoding%2Fbinary%2Findex.html +++ /dev/null @@ -1,217 +0,0 @@ -<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, &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, &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 (> 0). If an error occurred, the value is 0 and the number of bytes n is <= 0 meaning: </p> -<pre data-language="go">n == 0: buf too small -n < 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 (> 0). If an error occurred, the value is 0 and the number of bytes n is <= 0 with the following meaning: </p> -<pre data-language="go">n == 0: buf too small -n < 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"> - © 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> |