Run Format

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

View as plain text