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

View as plain text