...
Run Format

Source file src/encoding/binary/binary.go

     1	// Copyright 2009 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	// Package binary implements simple translation between numbers and byte
     6	// sequences and encoding and decoding of varints.
     7	//
     8	// Numbers are translated by reading and writing fixed-size values.
     9	// A fixed-size value is either a fixed-size arithmetic
    10	// type (bool, int8, uint8, int16, float32, complex64, ...)
    11	// or an array or struct containing only fixed-size values.
    12	//
    13	// The varint functions encode and decode single integer values using
    14	// a variable-length encoding; smaller values require fewer bytes.
    15	// For a specification, see
    16	// https://developers.google.com/protocol-buffers/docs/encoding.
    17	//
    18	// This package favors simplicity over efficiency. Clients that require
    19	// high-performance serialization, especially for large data structures,
    20	// should look at more advanced solutions such as the encoding/gob
    21	// package or protocol buffers.
    22	package binary
    23	
    24	import (
    25		"errors"
    26		"io"
    27		"math"
    28		"reflect"
    29	)
    30	
    31	// A ByteOrder specifies how to convert byte sequences into
    32	// 16-, 32-, or 64-bit unsigned integers.
    33	type ByteOrder interface {
    34		Uint16([]byte) uint16
    35		Uint32([]byte) uint32
    36		Uint64([]byte) uint64
    37		PutUint16([]byte, uint16)
    38		PutUint32([]byte, uint32)
    39		PutUint64([]byte, uint64)
    40		String() string
    41	}
    42	
    43	// LittleEndian is the little-endian implementation of ByteOrder.
    44	var LittleEndian littleEndian
    45	
    46	// BigEndian is the big-endian implementation of ByteOrder.
    47	var BigEndian bigEndian
    48	
    49	type littleEndian struct{}
    50	
    51	func (littleEndian) Uint16(b []byte) uint16 {
    52		_ = b[1] // bounds check hint to compiler; see golang.org/issue/14808
    53		return uint16(b[0]) | uint16(b[1])<<8
    54	}
    55	
    56	func (littleEndian) PutUint16(b []byte, v uint16) {
    57		_ = b[1] // early bounds check to guarantee safety of writes below
    58		b[0] = byte(v)
    59		b[1] = byte(v >> 8)
    60	}
    61	
    62	func (littleEndian) Uint32(b []byte) uint32 {
    63		_ = b[3] // bounds check hint to compiler; see golang.org/issue/14808
    64		return uint32(b[0]) | uint32(b[1])<<8 | uint32(b[2])<<16 | uint32(b[3])<<24
    65	}
    66	
    67	func (littleEndian) PutUint32(b []byte, v uint32) {
    68		_ = b[3] // early bounds check to guarantee safety of writes below
    69		b[0] = byte(v)
    70		b[1] = byte(v >> 8)
    71		b[2] = byte(v >> 16)
    72		b[3] = byte(v >> 24)
    73	}
    74	
    75	func (littleEndian) Uint64(b []byte) uint64 {
    76		_ = b[7] // bounds check hint to compiler; see golang.org/issue/14808
    77		return uint64(b[0]) | uint64(b[1])<<8 | uint64(b[2])<<16 | uint64(b[3])<<24 |
    78			uint64(b[4])<<32 | uint64(b[5])<<40 | uint64(b[6])<<48 | uint64(b[7])<<56
    79	}
    80	
    81	func (littleEndian) PutUint64(b []byte, v uint64) {
    82		_ = b[7] // early bounds check to guarantee safety of writes below
    83		b[0] = byte(v)
    84		b[1] = byte(v >> 8)
    85		b[2] = byte(v >> 16)
    86		b[3] = byte(v >> 24)
    87		b[4] = byte(v >> 32)
    88		b[5] = byte(v >> 40)
    89		b[6] = byte(v >> 48)
    90		b[7] = byte(v >> 56)
    91	}
    92	
    93	func (littleEndian) String() string { return "LittleEndian" }
    94	
    95	func (littleEndian) GoString() string { return "binary.LittleEndian" }
    96	
    97	type bigEndian struct{}
    98	
    99	func (bigEndian) Uint16(b []byte) uint16 {
   100		_ = b[1] // bounds check hint to compiler; see golang.org/issue/14808
   101		return uint16(b[1]) | uint16(b[0])<<8
   102	}
   103	
   104	func (bigEndian) PutUint16(b []byte, v uint16) {
   105		_ = b[1] // early bounds check to guarantee safety of writes below
   106		b[0] = byte(v >> 8)
   107		b[1] = byte(v)
   108	}
   109	
   110	func (bigEndian) Uint32(b []byte) uint32 {
   111		_ = b[3] // bounds check hint to compiler; see golang.org/issue/14808
   112		return uint32(b[3]) | uint32(b[2])<<8 | uint32(b[1])<<16 | uint32(b[0])<<24
   113	}
   114	
   115	func (bigEndian) PutUint32(b []byte, v uint32) {
   116		_ = b[3] // early bounds check to guarantee safety of writes below
   117		b[0] = byte(v >> 24)
   118		b[1] = byte(v >> 16)
   119		b[2] = byte(v >> 8)
   120		b[3] = byte(v)
   121	}
   122	
   123	func (bigEndian) Uint64(b []byte) uint64 {
   124		_ = b[7] // bounds check hint to compiler; see golang.org/issue/14808
   125		return uint64(b[7]) | uint64(b[6])<<8 | uint64(b[5])<<16 | uint64(b[4])<<24 |
   126			uint64(b[3])<<32 | uint64(b[2])<<40 | uint64(b[1])<<48 | uint64(b[0])<<56
   127	}
   128	
   129	func (bigEndian) PutUint64(b []byte, v uint64) {
   130		_ = b[7] // early bounds check to guarantee safety of writes below
   131		b[0] = byte(v >> 56)
   132		b[1] = byte(v >> 48)
   133		b[2] = byte(v >> 40)
   134		b[3] = byte(v >> 32)
   135		b[4] = byte(v >> 24)
   136		b[5] = byte(v >> 16)
   137		b[6] = byte(v >> 8)
   138		b[7] = byte(v)
   139	}
   140	
   141	func (bigEndian) String() string { return "BigEndian" }
   142	
   143	func (bigEndian) GoString() string { return "binary.BigEndian" }
   144	
   145	// Read reads structured binary data from r into data.
   146	// Data must be a pointer to a fixed-size value or a slice
   147	// of fixed-size values.
   148	// Bytes read from r are decoded using the specified byte order
   149	// and written to successive fields of the data.
   150	// When decoding boolean values, a zero byte is decoded as false, and
   151	// any other non-zero byte is decoded as true.
   152	// When reading into structs, the field data for fields with
   153	// blank (_) field names is skipped; i.e., blank field names
   154	// may be used for padding.
   155	// When reading into a struct, all non-blank fields must be exported.
   156	//
   157	// The error is EOF only if no bytes were read.
   158	// If an EOF happens after reading some but not all the bytes,
   159	// Read returns ErrUnexpectedEOF.
   160	func Read(r io.Reader, order ByteOrder, data interface{}) error {
   161		// Fast path for basic types and slices.
   162		if n := intDataSize(data); n != 0 {
   163			var b [8]byte
   164			var bs []byte
   165			if n > len(b) {
   166				bs = make([]byte, n)
   167			} else {
   168				bs = b[:n]
   169			}
   170			if _, err := io.ReadFull(r, bs); err != nil {
   171				return err
   172			}
   173			switch data := data.(type) {
   174			case *bool:
   175				*data = b[0] != 0
   176			case *int8:
   177				*data = int8(b[0])
   178			case *uint8:
   179				*data = b[0]
   180			case *int16:
   181				*data = int16(order.Uint16(bs))
   182			case *uint16:
   183				*data = order.Uint16(bs)
   184			case *int32:
   185				*data = int32(order.Uint32(bs))
   186			case *uint32:
   187				*data = order.Uint32(bs)
   188			case *int64:
   189				*data = int64(order.Uint64(bs))
   190			case *uint64:
   191				*data = order.Uint64(bs)
   192			case []bool:
   193				for i, x := range bs { // Easier to loop over the input for 8-bit values.
   194					data[i] = x != 0
   195				}
   196			case []int8:
   197				for i, x := range bs {
   198					data[i] = int8(x)
   199				}
   200			case []uint8:
   201				copy(data, bs)
   202			case []int16:
   203				for i := range data {
   204					data[i] = int16(order.Uint16(bs[2*i:]))
   205				}
   206			case []uint16:
   207				for i := range data {
   208					data[i] = order.Uint16(bs[2*i:])
   209				}
   210			case []int32:
   211				for i := range data {
   212					data[i] = int32(order.Uint32(bs[4*i:]))
   213				}
   214			case []uint32:
   215				for i := range data {
   216					data[i] = order.Uint32(bs[4*i:])
   217				}
   218			case []int64:
   219				for i := range data {
   220					data[i] = int64(order.Uint64(bs[8*i:]))
   221				}
   222			case []uint64:
   223				for i := range data {
   224					data[i] = order.Uint64(bs[8*i:])
   225				}
   226			}
   227			return nil
   228		}
   229	
   230		// Fallback to reflect-based decoding.
   231		v := reflect.ValueOf(data)
   232		size := -1
   233		switch v.Kind() {
   234		case reflect.Ptr:
   235			v = v.Elem()
   236			size = dataSize(v)
   237		case reflect.Slice:
   238			size = dataSize(v)
   239		}
   240		if size < 0 {
   241			return errors.New("binary.Read: invalid type " + reflect.TypeOf(data).String())
   242		}
   243		d := &decoder{order: order, buf: make([]byte, size)}
   244		if _, err := io.ReadFull(r, d.buf); err != nil {
   245			return err
   246		}
   247		d.value(v)
   248		return nil
   249	}
   250	
   251	// Write writes the binary representation of data into w.
   252	// Data must be a fixed-size value or a slice of fixed-size
   253	// values, or a pointer to such data.
   254	// Boolean values encode as one byte: 1 for true, and 0 for false.
   255	// Bytes written to w are encoded using the specified byte order
   256	// and read from successive fields of the data.
   257	// When writing structs, zero values are written for fields
   258	// with blank (_) field names.
   259	func Write(w io.Writer, order ByteOrder, data interface{}) error {
   260		// Fast path for basic types and slices.
   261		if n := intDataSize(data); n != 0 {
   262			var b [8]byte
   263			var bs []byte
   264			if n > len(b) {
   265				bs = make([]byte, n)
   266			} else {
   267				bs = b[:n]
   268			}
   269			switch v := data.(type) {
   270			case *bool:
   271				if *v {
   272					b[0] = 1
   273				} else {
   274					b[0] = 0
   275				}
   276			case bool:
   277				if v {
   278					b[0] = 1
   279				} else {
   280					b[0] = 0
   281				}
   282			case []bool:
   283				for i, x := range v {
   284					if x {
   285						bs[i] = 1
   286					} else {
   287						bs[i] = 0
   288					}
   289				}
   290			case *int8:
   291				b[0] = byte(*v)
   292			case int8:
   293				b[0] = byte(v)
   294			case []int8:
   295				for i, x := range v {
   296					bs[i] = byte(x)
   297				}
   298			case *uint8:
   299				b[0] = *v
   300			case uint8:
   301				b[0] = v
   302			case []uint8:
   303				bs = v
   304			case *int16:
   305				order.PutUint16(bs, uint16(*v))
   306			case int16:
   307				order.PutUint16(bs, uint16(v))
   308			case []int16:
   309				for i, x := range v {
   310					order.PutUint16(bs[2*i:], uint16(x))
   311				}
   312			case *uint16:
   313				order.PutUint16(bs, *v)
   314			case uint16:
   315				order.PutUint16(bs, v)
   316			case []uint16:
   317				for i, x := range v {
   318					order.PutUint16(bs[2*i:], x)
   319				}
   320			case *int32:
   321				order.PutUint32(bs, uint32(*v))
   322			case int32:
   323				order.PutUint32(bs, uint32(v))
   324			case []int32:
   325				for i, x := range v {
   326					order.PutUint32(bs[4*i:], uint32(x))
   327				}
   328			case *uint32:
   329				order.PutUint32(bs, *v)
   330			case uint32:
   331				order.PutUint32(bs, v)
   332			case []uint32:
   333				for i, x := range v {
   334					order.PutUint32(bs[4*i:], x)
   335				}
   336			case *int64:
   337				order.PutUint64(bs, uint64(*v))
   338			case int64:
   339				order.PutUint64(bs, uint64(v))
   340			case []int64:
   341				for i, x := range v {
   342					order.PutUint64(bs[8*i:], uint64(x))
   343				}
   344			case *uint64:
   345				order.PutUint64(bs, *v)
   346			case uint64:
   347				order.PutUint64(bs, v)
   348			case []uint64:
   349				for i, x := range v {
   350					order.PutUint64(bs[8*i:], x)
   351				}
   352			}
   353			_, err := w.Write(bs)
   354			return err
   355		}
   356	
   357		// Fallback to reflect-based encoding.
   358		v := reflect.Indirect(reflect.ValueOf(data))
   359		size := dataSize(v)
   360		if size < 0 {
   361			return errors.New("binary.Write: invalid type " + reflect.TypeOf(data).String())
   362		}
   363		buf := make([]byte, size)
   364		e := &encoder{order: order, buf: buf}
   365		e.value(v)
   366		_, err := w.Write(buf)
   367		return err
   368	}
   369	
   370	// Size returns how many bytes Write would generate to encode the value v, which
   371	// must be a fixed-size value or a slice of fixed-size values, or a pointer to such data.
   372	// If v is neither of these, Size returns -1.
   373	func Size(v interface{}) int {
   374		return dataSize(reflect.Indirect(reflect.ValueOf(v)))
   375	}
   376	
   377	// dataSize returns the number of bytes the actual data represented by v occupies in memory.
   378	// For compound structures, it sums the sizes of the elements. Thus, for instance, for a slice
   379	// it returns the length of the slice times the element size and does not count the memory
   380	// occupied by the header. If the type of v is not acceptable, dataSize returns -1.
   381	func dataSize(v reflect.Value) int {
   382		if v.Kind() == reflect.Slice {
   383			if s := sizeof(v.Type().Elem()); s >= 0 {
   384				return s * v.Len()
   385			}
   386			return -1
   387		}
   388		return sizeof(v.Type())
   389	}
   390	
   391	// sizeof returns the size >= 0 of variables for the given type or -1 if the type is not acceptable.
   392	func sizeof(t reflect.Type) int {
   393		switch t.Kind() {
   394		case reflect.Array:
   395			if s := sizeof(t.Elem()); s >= 0 {
   396				return s * t.Len()
   397			}
   398	
   399		case reflect.Struct:
   400			sum := 0
   401			for i, n := 0, t.NumField(); i < n; i++ {
   402				s := sizeof(t.Field(i).Type)
   403				if s < 0 {
   404					return -1
   405				}
   406				sum += s
   407			}
   408			return sum
   409	
   410		case reflect.Bool,
   411			reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64,
   412			reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
   413			reflect.Float32, reflect.Float64, reflect.Complex64, reflect.Complex128:
   414			return int(t.Size())
   415		}
   416	
   417		return -1
   418	}
   419	
   420	type coder struct {
   421		order ByteOrder
   422		buf   []byte
   423	}
   424	
   425	type decoder coder
   426	type encoder coder
   427	
   428	func (d *decoder) bool() bool {
   429		x := d.buf[0]
   430		d.buf = d.buf[1:]
   431		return x != 0
   432	}
   433	
   434	func (e *encoder) bool(x bool) {
   435		if x {
   436			e.buf[0] = 1
   437		} else {
   438			e.buf[0] = 0
   439		}
   440		e.buf = e.buf[1:]
   441	}
   442	
   443	func (d *decoder) uint8() uint8 {
   444		x := d.buf[0]
   445		d.buf = d.buf[1:]
   446		return x
   447	}
   448	
   449	func (e *encoder) uint8(x uint8) {
   450		e.buf[0] = x
   451		e.buf = e.buf[1:]
   452	}
   453	
   454	func (d *decoder) uint16() uint16 {
   455		x := d.order.Uint16(d.buf[0:2])
   456		d.buf = d.buf[2:]
   457		return x
   458	}
   459	
   460	func (e *encoder) uint16(x uint16) {
   461		e.order.PutUint16(e.buf[0:2], x)
   462		e.buf = e.buf[2:]
   463	}
   464	
   465	func (d *decoder) uint32() uint32 {
   466		x := d.order.Uint32(d.buf[0:4])
   467		d.buf = d.buf[4:]
   468		return x
   469	}
   470	
   471	func (e *encoder) uint32(x uint32) {
   472		e.order.PutUint32(e.buf[0:4], x)
   473		e.buf = e.buf[4:]
   474	}
   475	
   476	func (d *decoder) uint64() uint64 {
   477		x := d.order.Uint64(d.buf[0:8])
   478		d.buf = d.buf[8:]
   479		return x
   480	}
   481	
   482	func (e *encoder) uint64(x uint64) {
   483		e.order.PutUint64(e.buf[0:8], x)
   484		e.buf = e.buf[8:]
   485	}
   486	
   487	func (d *decoder) int8() int8 { return int8(d.uint8()) }
   488	
   489	func (e *encoder) int8(x int8) { e.uint8(uint8(x)) }
   490	
   491	func (d *decoder) int16() int16 { return int16(d.uint16()) }
   492	
   493	func (e *encoder) int16(x int16) { e.uint16(uint16(x)) }
   494	
   495	func (d *decoder) int32() int32 { return int32(d.uint32()) }
   496	
   497	func (e *encoder) int32(x int32) { e.uint32(uint32(x)) }
   498	
   499	func (d *decoder) int64() int64 { return int64(d.uint64()) }
   500	
   501	func (e *encoder) int64(x int64) { e.uint64(uint64(x)) }
   502	
   503	func (d *decoder) value(v reflect.Value) {
   504		switch v.Kind() {
   505		case reflect.Array:
   506			l := v.Len()
   507			for i := 0; i < l; i++ {
   508				d.value(v.Index(i))
   509			}
   510	
   511		case reflect.Struct:
   512			t := v.Type()
   513			l := v.NumField()
   514			for i := 0; i < l; i++ {
   515				// Note: Calling v.CanSet() below is an optimization.
   516				// It would be sufficient to check the field name,
   517				// but creating the StructField info for each field is
   518				// costly (run "go test -bench=ReadStruct" and compare
   519				// results when making changes to this code).
   520				if v := v.Field(i); v.CanSet() || t.Field(i).Name != "_" {
   521					d.value(v)
   522				} else {
   523					d.skip(v)
   524				}
   525			}
   526	
   527		case reflect.Slice:
   528			l := v.Len()
   529			for i := 0; i < l; i++ {
   530				d.value(v.Index(i))
   531			}
   532	
   533		case reflect.Bool:
   534			v.SetBool(d.bool())
   535	
   536		case reflect.Int8:
   537			v.SetInt(int64(d.int8()))
   538		case reflect.Int16:
   539			v.SetInt(int64(d.int16()))
   540		case reflect.Int32:
   541			v.SetInt(int64(d.int32()))
   542		case reflect.Int64:
   543			v.SetInt(d.int64())
   544	
   545		case reflect.Uint8:
   546			v.SetUint(uint64(d.uint8()))
   547		case reflect.Uint16:
   548			v.SetUint(uint64(d.uint16()))
   549		case reflect.Uint32:
   550			v.SetUint(uint64(d.uint32()))
   551		case reflect.Uint64:
   552			v.SetUint(d.uint64())
   553	
   554		case reflect.Float32:
   555			v.SetFloat(float64(math.Float32frombits(d.uint32())))
   556		case reflect.Float64:
   557			v.SetFloat(math.Float64frombits(d.uint64()))
   558	
   559		case reflect.Complex64:
   560			v.SetComplex(complex(
   561				float64(math.Float32frombits(d.uint32())),
   562				float64(math.Float32frombits(d.uint32())),
   563			))
   564		case reflect.Complex128:
   565			v.SetComplex(complex(
   566				math.Float64frombits(d.uint64()),
   567				math.Float64frombits(d.uint64()),
   568			))
   569		}
   570	}
   571	
   572	func (e *encoder) value(v reflect.Value) {
   573		switch v.Kind() {
   574		case reflect.Array:
   575			l := v.Len()
   576			for i := 0; i < l; i++ {
   577				e.value(v.Index(i))
   578			}
   579	
   580		case reflect.Struct:
   581			t := v.Type()
   582			l := v.NumField()
   583			for i := 0; i < l; i++ {
   584				// see comment for corresponding code in decoder.value()
   585				if v := v.Field(i); v.CanSet() || t.Field(i).Name != "_" {
   586					e.value(v)
   587				} else {
   588					e.skip(v)
   589				}
   590			}
   591	
   592		case reflect.Slice:
   593			l := v.Len()
   594			for i := 0; i < l; i++ {
   595				e.value(v.Index(i))
   596			}
   597	
   598		case reflect.Bool:
   599			e.bool(v.Bool())
   600	
   601		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
   602			switch v.Type().Kind() {
   603			case reflect.Int8:
   604				e.int8(int8(v.Int()))
   605			case reflect.Int16:
   606				e.int16(int16(v.Int()))
   607			case reflect.Int32:
   608				e.int32(int32(v.Int()))
   609			case reflect.Int64:
   610				e.int64(v.Int())
   611			}
   612	
   613		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
   614			switch v.Type().Kind() {
   615			case reflect.Uint8:
   616				e.uint8(uint8(v.Uint()))
   617			case reflect.Uint16:
   618				e.uint16(uint16(v.Uint()))
   619			case reflect.Uint32:
   620				e.uint32(uint32(v.Uint()))
   621			case reflect.Uint64:
   622				e.uint64(v.Uint())
   623			}
   624	
   625		case reflect.Float32, reflect.Float64:
   626			switch v.Type().Kind() {
   627			case reflect.Float32:
   628				e.uint32(math.Float32bits(float32(v.Float())))
   629			case reflect.Float64:
   630				e.uint64(math.Float64bits(v.Float()))
   631			}
   632	
   633		case reflect.Complex64, reflect.Complex128:
   634			switch v.Type().Kind() {
   635			case reflect.Complex64:
   636				x := v.Complex()
   637				e.uint32(math.Float32bits(float32(real(x))))
   638				e.uint32(math.Float32bits(float32(imag(x))))
   639			case reflect.Complex128:
   640				x := v.Complex()
   641				e.uint64(math.Float64bits(real(x)))
   642				e.uint64(math.Float64bits(imag(x)))
   643			}
   644		}
   645	}
   646	
   647	func (d *decoder) skip(v reflect.Value) {
   648		d.buf = d.buf[dataSize(v):]
   649	}
   650	
   651	func (e *encoder) skip(v reflect.Value) {
   652		n := dataSize(v)
   653		for i := range e.buf[0:n] {
   654			e.buf[i] = 0
   655		}
   656		e.buf = e.buf[n:]
   657	}
   658	
   659	// intDataSize returns the size of the data required to represent the data when encoded.
   660	// It returns zero if the type cannot be implemented by the fast path in Read or Write.
   661	func intDataSize(data interface{}) int {
   662		switch data := data.(type) {
   663		case bool, int8, uint8, *bool, *int8, *uint8:
   664			return 1
   665		case []int8:
   666			return len(data)
   667		case []uint8:
   668			return len(data)
   669		case int16, uint16, *int16, *uint16:
   670			return 2
   671		case []int16:
   672			return 2 * len(data)
   673		case []uint16:
   674			return 2 * len(data)
   675		case int32, uint32, *int32, *uint32:
   676			return 4
   677		case []int32:
   678			return 4 * len(data)
   679		case []uint32:
   680			return 4 * len(data)
   681		case int64, uint64, *int64, *uint64:
   682			return 8
   683		case []int64:
   684			return 8 * len(data)
   685		case []uint64:
   686			return 8 * len(data)
   687		}
   688		return 0
   689	}
   690	

View as plain text