Source file src/pkg/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	// or Read may panic.
   157	//
   158	// The error is EOF only if no bytes were read.
   159	// If an EOF happens after reading some but not all the bytes,
   160	// Read returns ErrUnexpectedEOF.
   161	func Read(r io.Reader, order ByteOrder, data interface{}) error {
   162		// Fast path for basic types and slices.
   163		if n := intDataSize(data); n != 0 {
   164			bs := make([]byte, n)
   165			if _, err := io.ReadFull(r, bs); err != nil {
   166				return err
   167			}
   168			switch data := data.(type) {
   169			case *bool:
   170				*data = bs[0] != 0
   171			case *int8:
   172				*data = int8(bs[0])
   173			case *uint8:
   174				*data = bs[0]
   175			case *int16:
   176				*data = int16(order.Uint16(bs))
   177			case *uint16:
   178				*data = order.Uint16(bs)
   179			case *int32:
   180				*data = int32(order.Uint32(bs))
   181			case *uint32:
   182				*data = order.Uint32(bs)
   183			case *int64:
   184				*data = int64(order.Uint64(bs))
   185			case *uint64:
   186				*data = order.Uint64(bs)
   187			case []bool:
   188				for i, x := range bs { // Easier to loop over the input for 8-bit values.
   189					data[i] = x != 0
   190				}
   191			case []int8:
   192				for i, x := range bs {
   193					data[i] = int8(x)
   194				}
   195			case []uint8:
   196				copy(data, bs)
   197			case []int16:
   198				for i := range data {
   199					data[i] = int16(order.Uint16(bs[2*i:]))
   200				}
   201			case []uint16:
   202				for i := range data {
   203					data[i] = order.Uint16(bs[2*i:])
   204				}
   205			case []int32:
   206				for i := range data {
   207					data[i] = int32(order.Uint32(bs[4*i:]))
   208				}
   209			case []uint32:
   210				for i := range data {
   211					data[i] = order.Uint32(bs[4*i:])
   212				}
   213			case []int64:
   214				for i := range data {
   215					data[i] = int64(order.Uint64(bs[8*i:]))
   216				}
   217			case []uint64:
   218				for i := range data {
   219					data[i] = order.Uint64(bs[8*i:])
   220				}
   221			}
   222			return nil
   223		}
   224	
   225		// Fallback to reflect-based decoding.
   226		v := reflect.ValueOf(data)
   227		size := -1
   228		switch v.Kind() {
   229		case reflect.Ptr:
   230			v = v.Elem()
   231			size = dataSize(v)
   232		case reflect.Slice:
   233			size = dataSize(v)
   234		}
   235		if size < 0 {
   236			return errors.New("binary.Read: invalid type " + reflect.TypeOf(data).String())
   237		}
   238		d := &decoder{order: order, buf: make([]byte, size)}
   239		if _, err := io.ReadFull(r, d.buf); err != nil {
   240			return err
   241		}
   242		d.value(v)
   243		return nil
   244	}
   245	
   246	// Write writes the binary representation of data into w.
   247	// Data must be a fixed-size value or a slice of fixed-size
   248	// values, or a pointer to such data.
   249	// Boolean values encode as one byte: 1 for true, and 0 for false.
   250	// Bytes written to w are encoded using the specified byte order
   251	// and read from successive fields of the data.
   252	// When writing structs, zero values are written for fields
   253	// with blank (_) field names.
   254	func Write(w io.Writer, order ByteOrder, data interface{}) error {
   255		// Fast path for basic types and slices.
   256		if n := intDataSize(data); n != 0 {
   257			bs := make([]byte, n)
   258			switch v := data.(type) {
   259			case *bool:
   260				if *v {
   261					bs[0] = 1
   262				} else {
   263					bs[0] = 0
   264				}
   265			case bool:
   266				if v {
   267					bs[0] = 1
   268				} else {
   269					bs[0] = 0
   270				}
   271			case []bool:
   272				for i, x := range v {
   273					if x {
   274						bs[i] = 1
   275					} else {
   276						bs[i] = 0
   277					}
   278				}
   279			case *int8:
   280				bs[0] = byte(*v)
   281			case int8:
   282				bs[0] = byte(v)
   283			case []int8:
   284				for i, x := range v {
   285					bs[i] = byte(x)
   286				}
   287			case *uint8:
   288				bs[0] = *v
   289			case uint8:
   290				bs[0] = v
   291			case []uint8:
   292				bs = v // TODO(josharian): avoid allocating bs in this case?
   293			case *int16:
   294				order.PutUint16(bs, uint16(*v))
   295			case int16:
   296				order.PutUint16(bs, uint16(v))
   297			case []int16:
   298				for i, x := range v {
   299					order.PutUint16(bs[2*i:], uint16(x))
   300				}
   301			case *uint16:
   302				order.PutUint16(bs, *v)
   303			case uint16:
   304				order.PutUint16(bs, v)
   305			case []uint16:
   306				for i, x := range v {
   307					order.PutUint16(bs[2*i:], x)
   308				}
   309			case *int32:
   310				order.PutUint32(bs, uint32(*v))
   311			case int32:
   312				order.PutUint32(bs, uint32(v))
   313			case []int32:
   314				for i, x := range v {
   315					order.PutUint32(bs[4*i:], uint32(x))
   316				}
   317			case *uint32:
   318				order.PutUint32(bs, *v)
   319			case uint32:
   320				order.PutUint32(bs, v)
   321			case []uint32:
   322				for i, x := range v {
   323					order.PutUint32(bs[4*i:], x)
   324				}
   325			case *int64:
   326				order.PutUint64(bs, uint64(*v))
   327			case int64:
   328				order.PutUint64(bs, uint64(v))
   329			case []int64:
   330				for i, x := range v {
   331					order.PutUint64(bs[8*i:], uint64(x))
   332				}
   333			case *uint64:
   334				order.PutUint64(bs, *v)
   335			case uint64:
   336				order.PutUint64(bs, v)
   337			case []uint64:
   338				for i, x := range v {
   339					order.PutUint64(bs[8*i:], x)
   340				}
   341			}
   342			_, err := w.Write(bs)
   343			return err
   344		}
   345	
   346		// Fallback to reflect-based encoding.
   347		v := reflect.Indirect(reflect.ValueOf(data))
   348		size := dataSize(v)
   349		if size < 0 {
   350			return errors.New("binary.Write: invalid type " + reflect.TypeOf(data).String())
   351		}
   352		buf := make([]byte, size)
   353		e := &encoder{order: order, buf: buf}
   354		e.value(v)
   355		_, err := w.Write(buf)
   356		return err
   357	}
   358	
   359	// Size returns how many bytes Write would generate to encode the value v, which
   360	// must be a fixed-size value or a slice of fixed-size values, or a pointer to such data.
   361	// If v is neither of these, Size returns -1.
   362	func Size(v interface{}) int {
   363		return dataSize(reflect.Indirect(reflect.ValueOf(v)))
   364	}
   365	
   366	// dataSize returns the number of bytes the actual data represented by v occupies in memory.
   367	// For compound structures, it sums the sizes of the elements. Thus, for instance, for a slice
   368	// it returns the length of the slice times the element size and does not count the memory
   369	// occupied by the header. If the type of v is not acceptable, dataSize returns -1.
   370	func dataSize(v reflect.Value) int {
   371		if v.Kind() == reflect.Slice {
   372			if s := sizeof(v.Type().Elem()); s >= 0 {
   373				return s * v.Len()
   374			}
   375			return -1
   376		}
   377		return sizeof(v.Type())
   378	}
   379	
   380	// sizeof returns the size >= 0 of variables for the given type or -1 if the type is not acceptable.
   381	func sizeof(t reflect.Type) int {
   382		switch t.Kind() {
   383		case reflect.Array:
   384			if s := sizeof(t.Elem()); s >= 0 {
   385				return s * t.Len()
   386			}
   387	
   388		case reflect.Struct:
   389			sum := 0
   390			for i, n := 0, t.NumField(); i < n; i++ {
   391				s := sizeof(t.Field(i).Type)
   392				if s < 0 {
   393					return -1
   394				}
   395				sum += s
   396			}
   397			return sum
   398	
   399		case reflect.Bool,
   400			reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64,
   401			reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
   402			reflect.Float32, reflect.Float64, reflect.Complex64, reflect.Complex128:
   403			return int(t.Size())
   404		}
   405	
   406		return -1
   407	}
   408	
   409	type coder struct {
   410		order  ByteOrder
   411		buf    []byte
   412		offset int
   413	}
   414	
   415	type decoder coder
   416	type encoder coder
   417	
   418	func (d *decoder) bool() bool {
   419		x := d.buf[d.offset]
   420		d.offset++
   421		return x != 0
   422	}
   423	
   424	func (e *encoder) bool(x bool) {
   425		if x {
   426			e.buf[e.offset] = 1
   427		} else {
   428			e.buf[e.offset] = 0
   429		}
   430		e.offset++
   431	}
   432	
   433	func (d *decoder) uint8() uint8 {
   434		x := d.buf[d.offset]
   435		d.offset++
   436		return x
   437	}
   438	
   439	func (e *encoder) uint8(x uint8) {
   440		e.buf[e.offset] = x
   441		e.offset++
   442	}
   443	
   444	func (d *decoder) uint16() uint16 {
   445		x := d.order.Uint16(d.buf[d.offset : d.offset+2])
   446		d.offset += 2
   447		return x
   448	}
   449	
   450	func (e *encoder) uint16(x uint16) {
   451		e.order.PutUint16(e.buf[e.offset:e.offset+2], x)
   452		e.offset += 2
   453	}
   454	
   455	func (d *decoder) uint32() uint32 {
   456		x := d.order.Uint32(d.buf[d.offset : d.offset+4])
   457		d.offset += 4
   458		return x
   459	}
   460	
   461	func (e *encoder) uint32(x uint32) {
   462		e.order.PutUint32(e.buf[e.offset:e.offset+4], x)
   463		e.offset += 4
   464	}
   465	
   466	func (d *decoder) uint64() uint64 {
   467		x := d.order.Uint64(d.buf[d.offset : d.offset+8])
   468		d.offset += 8
   469		return x
   470	}
   471	
   472	func (e *encoder) uint64(x uint64) {
   473		e.order.PutUint64(e.buf[e.offset:e.offset+8], x)
   474		e.offset += 8
   475	}
   476	
   477	func (d *decoder) int8() int8 { return int8(d.uint8()) }
   478	
   479	func (e *encoder) int8(x int8) { e.uint8(uint8(x)) }
   480	
   481	func (d *decoder) int16() int16 { return int16(d.uint16()) }
   482	
   483	func (e *encoder) int16(x int16) { e.uint16(uint16(x)) }
   484	
   485	func (d *decoder) int32() int32 { return int32(d.uint32()) }
   486	
   487	func (e *encoder) int32(x int32) { e.uint32(uint32(x)) }
   488	
   489	func (d *decoder) int64() int64 { return int64(d.uint64()) }
   490	
   491	func (e *encoder) int64(x int64) { e.uint64(uint64(x)) }
   492	
   493	func (d *decoder) value(v reflect.Value) {
   494		switch v.Kind() {
   495		case reflect.Array:
   496			l := v.Len()
   497			for i := 0; i < l; i++ {
   498				d.value(v.Index(i))
   499			}
   500	
   501		case reflect.Struct:
   502			t := v.Type()
   503			l := v.NumField()
   504			for i := 0; i < l; i++ {
   505				// Note: Calling v.CanSet() below is an optimization.
   506				// It would be sufficient to check the field name,
   507				// but creating the StructField info for each field is
   508				// costly (run "go test -bench=ReadStruct" and compare
   509				// results when making changes to this code).
   510				if v := v.Field(i); v.CanSet() || t.Field(i).Name != "_" {
   511					d.value(v)
   512				} else {
   513					d.skip(v)
   514				}
   515			}
   516	
   517		case reflect.Slice:
   518			l := v.Len()
   519			for i := 0; i < l; i++ {
   520				d.value(v.Index(i))
   521			}
   522	
   523		case reflect.Bool:
   524			v.SetBool(d.bool())
   525	
   526		case reflect.Int8:
   527			v.SetInt(int64(d.int8()))
   528		case reflect.Int16:
   529			v.SetInt(int64(d.int16()))
   530		case reflect.Int32:
   531			v.SetInt(int64(d.int32()))
   532		case reflect.Int64:
   533			v.SetInt(d.int64())
   534	
   535		case reflect.Uint8:
   536			v.SetUint(uint64(d.uint8()))
   537		case reflect.Uint16:
   538			v.SetUint(uint64(d.uint16()))
   539		case reflect.Uint32:
   540			v.SetUint(uint64(d.uint32()))
   541		case reflect.Uint64:
   542			v.SetUint(d.uint64())
   543	
   544		case reflect.Float32:
   545			v.SetFloat(float64(math.Float32frombits(d.uint32())))
   546		case reflect.Float64:
   547			v.SetFloat(math.Float64frombits(d.uint64()))
   548	
   549		case reflect.Complex64:
   550			v.SetComplex(complex(
   551				float64(math.Float32frombits(d.uint32())),
   552				float64(math.Float32frombits(d.uint32())),
   553			))
   554		case reflect.Complex128:
   555			v.SetComplex(complex(
   556				math.Float64frombits(d.uint64()),
   557				math.Float64frombits(d.uint64()),
   558			))
   559		}
   560	}
   561	
   562	func (e *encoder) value(v reflect.Value) {
   563		switch v.Kind() {
   564		case reflect.Array:
   565			l := v.Len()
   566			for i := 0; i < l; i++ {
   567				e.value(v.Index(i))
   568			}
   569	
   570		case reflect.Struct:
   571			t := v.Type()
   572			l := v.NumField()
   573			for i := 0; i < l; i++ {
   574				// see comment for corresponding code in decoder.value()
   575				if v := v.Field(i); v.CanSet() || t.Field(i).Name != "_" {
   576					e.value(v)
   577				} else {
   578					e.skip(v)
   579				}
   580			}
   581	
   582		case reflect.Slice:
   583			l := v.Len()
   584			for i := 0; i < l; i++ {
   585				e.value(v.Index(i))
   586			}
   587	
   588		case reflect.Bool:
   589			e.bool(v.Bool())
   590	
   591		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
   592			switch v.Type().Kind() {
   593			case reflect.Int8:
   594				e.int8(int8(v.Int()))
   595			case reflect.Int16:
   596				e.int16(int16(v.Int()))
   597			case reflect.Int32:
   598				e.int32(int32(v.Int()))
   599			case reflect.Int64:
   600				e.int64(v.Int())
   601			}
   602	
   603		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
   604			switch v.Type().Kind() {
   605			case reflect.Uint8:
   606				e.uint8(uint8(v.Uint()))
   607			case reflect.Uint16:
   608				e.uint16(uint16(v.Uint()))
   609			case reflect.Uint32:
   610				e.uint32(uint32(v.Uint()))
   611			case reflect.Uint64:
   612				e.uint64(v.Uint())
   613			}
   614	
   615		case reflect.Float32, reflect.Float64:
   616			switch v.Type().Kind() {
   617			case reflect.Float32:
   618				e.uint32(math.Float32bits(float32(v.Float())))
   619			case reflect.Float64:
   620				e.uint64(math.Float64bits(v.Float()))
   621			}
   622	
   623		case reflect.Complex64, reflect.Complex128:
   624			switch v.Type().Kind() {
   625			case reflect.Complex64:
   626				x := v.Complex()
   627				e.uint32(math.Float32bits(float32(real(x))))
   628				e.uint32(math.Float32bits(float32(imag(x))))
   629			case reflect.Complex128:
   630				x := v.Complex()
   631				e.uint64(math.Float64bits(real(x)))
   632				e.uint64(math.Float64bits(imag(x)))
   633			}
   634		}
   635	}
   636	
   637	func (d *decoder) skip(v reflect.Value) {
   638		d.offset += dataSize(v)
   639	}
   640	
   641	func (e *encoder) skip(v reflect.Value) {
   642		n := dataSize(v)
   643		zero := e.buf[e.offset : e.offset+n]
   644		for i := range zero {
   645			zero[i] = 0
   646		}
   647		e.offset += n
   648	}
   649	
   650	// intDataSize returns the size of the data required to represent the data when encoded.
   651	// It returns zero if the type cannot be implemented by the fast path in Read or Write.
   652	func intDataSize(data interface{}) int {
   653		switch data := data.(type) {
   654		case bool, int8, uint8, *bool, *int8, *uint8:
   655			return 1
   656		case []bool:
   657			return len(data)
   658		case []int8:
   659			return len(data)
   660		case []uint8:
   661			return len(data)
   662		case int16, uint16, *int16, *uint16:
   663			return 2
   664		case []int16:
   665			return 2 * len(data)
   666		case []uint16:
   667			return 2 * len(data)
   668		case int32, uint32, *int32, *uint32:
   669			return 4
   670		case []int32:
   671			return 4 * len(data)
   672		case []uint32:
   673			return 4 * len(data)
   674		case int64, uint64, *int64, *uint64:
   675			return 8
   676		case []int64:
   677			return 8 * len(data)
   678		case []uint64:
   679			return 8 * len(data)
   680		}
   681		return 0
   682	}
   683	

View as plain text