new repository

1 files changed, 217 insertions, 0 deletions

diff --git a/devdocs/go/encoding%2Fbinary%2Findex.html b/devdocs/go/encoding%2Fbinary%2Findex.html
new file mode 100644
index 00000000..d018b748
--- /dev/null
+++ b/devdocs/go/encoding%2Fbinary%2Findex.html
@@ -0,0 +1,217 @@
+<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>