...
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	// When reading into a struct, all non-blank fields must be exported.
   137	func Read(r io.Reader, order ByteOrder, data interface{}) error {
   138		// Fast path for basic types and slices.
   139		if n := intDataSize(data); n != 0 {
   140			var b [8]byte
   141			var bs []byte
   142			if n > len(b) {
   143				bs = make([]byte, n)
   144			} else {
   145				bs = b[:n]
   146			}
   147			if _, err := io.ReadFull(r, bs); err != nil {
   148				return err
   149			}
   150			switch data := data.(type) {
   151			case *int8:
   152				*data = int8(b[0])
   153			case *uint8:
   154				*data = b[0]
   155			case *int16:
   156				*data = int16(order.Uint16(bs))
   157			case *uint16:
   158				*data = order.Uint16(bs)
   159			case *int32:
   160				*data = int32(order.Uint32(bs))
   161			case *uint32:
   162				*data = order.Uint32(bs)
   163			case *int64:
   164				*data = int64(order.Uint64(bs))
   165			case *uint64:
   166				*data = order.Uint64(bs)
   167			case []int8:
   168				for i, x := range bs { // Easier to loop over the input for 8-bit values.
   169					data[i] = int8(x)
   170				}
   171			case []uint8:
   172				copy(data, bs)
   173			case []int16:
   174				for i := range data {
   175					data[i] = int16(order.Uint16(bs[2*i:]))
   176				}
   177			case []uint16:
   178				for i := range data {
   179					data[i] = order.Uint16(bs[2*i:])
   180				}
   181			case []int32:
   182				for i := range data {
   183					data[i] = int32(order.Uint32(bs[4*i:]))
   184				}
   185			case []uint32:
   186				for i := range data {
   187					data[i] = order.Uint32(bs[4*i:])
   188				}
   189			case []int64:
   190				for i := range data {
   191					data[i] = int64(order.Uint64(bs[8*i:]))
   192				}
   193			case []uint64:
   194				for i := range data {
   195					data[i] = order.Uint64(bs[8*i:])
   196				}
   197			}
   198			return nil
   199		}
   200	
   201		// Fallback to reflect-based decoding.
   202		var v reflect.Value
   203		switch d := reflect.ValueOf(data); d.Kind() {
   204		case reflect.Ptr:
   205			v = d.Elem()
   206		case reflect.Slice:
   207			v = d
   208		default:
   209			return errors.New("binary.Read: invalid type " + d.Type().String())
   210		}
   211		size, err := dataSize(v)
   212		if err != nil {
   213			return errors.New("binary.Read: " + err.Error())
   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, err := dataSize(v)
   327		if err != nil {
   328			return errors.New("binary.Write: " + err.Error())
   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	func Size(v interface{}) int {
   340		n, err := dataSize(reflect.Indirect(reflect.ValueOf(v)))
   341		if err != nil {
   342			return -1
   343		}
   344		return n
   345	}
   346	
   347	// dataSize returns the number of bytes the actual data represented by v occupies in memory.
   348	// For compound structures, it sums the sizes of the elements. Thus, for instance, for a slice
   349	// it returns the length of the slice times the element size and does not count the memory
   350	// occupied by the header.
   351	func dataSize(v reflect.Value) (int, error) {
   352		if v.Kind() == reflect.Slice {
   353			elem, err := sizeof(v.Type().Elem())
   354			if err != nil {
   355				return 0, err
   356			}
   357			return v.Len() * elem, nil
   358		}
   359		return sizeof(v.Type())
   360	}
   361	
   362	func sizeof(t reflect.Type) (int, error) {
   363		switch t.Kind() {
   364		case reflect.Array:
   365			n, err := sizeof(t.Elem())
   366			if err != nil {
   367				return 0, err
   368			}
   369			return t.Len() * n, nil
   370	
   371		case reflect.Struct:
   372			sum := 0
   373			for i, n := 0, t.NumField(); i < n; i++ {
   374				s, err := sizeof(t.Field(i).Type)
   375				if err != nil {
   376					return 0, err
   377				}
   378				sum += s
   379			}
   380			return sum, nil
   381	
   382		case reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64,
   383			reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64,
   384			reflect.Float32, reflect.Float64, reflect.Complex64, reflect.Complex128:
   385			return int(t.Size()), nil
   386		}
   387		return 0, errors.New("invalid type " + t.String())
   388	}
   389	
   390	type coder struct {
   391		order ByteOrder
   392		buf   []byte
   393	}
   394	
   395	type decoder coder
   396	type encoder coder
   397	
   398	func (d *decoder) uint8() uint8 {
   399		x := d.buf[0]
   400		d.buf = d.buf[1:]
   401		return x
   402	}
   403	
   404	func (e *encoder) uint8(x uint8) {
   405		e.buf[0] = x
   406		e.buf = e.buf[1:]
   407	}
   408	
   409	func (d *decoder) uint16() uint16 {
   410		x := d.order.Uint16(d.buf[0:2])
   411		d.buf = d.buf[2:]
   412		return x
   413	}
   414	
   415	func (e *encoder) uint16(x uint16) {
   416		e.order.PutUint16(e.buf[0:2], x)
   417		e.buf = e.buf[2:]
   418	}
   419	
   420	func (d *decoder) uint32() uint32 {
   421		x := d.order.Uint32(d.buf[0:4])
   422		d.buf = d.buf[4:]
   423		return x
   424	}
   425	
   426	func (e *encoder) uint32(x uint32) {
   427		e.order.PutUint32(e.buf[0:4], x)
   428		e.buf = e.buf[4:]
   429	}
   430	
   431	func (d *decoder) uint64() uint64 {
   432		x := d.order.Uint64(d.buf[0:8])
   433		d.buf = d.buf[8:]
   434		return x
   435	}
   436	
   437	func (e *encoder) uint64(x uint64) {
   438		e.order.PutUint64(e.buf[0:8], x)
   439		e.buf = e.buf[8:]
   440	}
   441	
   442	func (d *decoder) int8() int8 { return int8(d.uint8()) }
   443	
   444	func (e *encoder) int8(x int8) { e.uint8(uint8(x)) }
   445	
   446	func (d *decoder) int16() int16 { return int16(d.uint16()) }
   447	
   448	func (e *encoder) int16(x int16) { e.uint16(uint16(x)) }
   449	
   450	func (d *decoder) int32() int32 { return int32(d.uint32()) }
   451	
   452	func (e *encoder) int32(x int32) { e.uint32(uint32(x)) }
   453	
   454	func (d *decoder) int64() int64 { return int64(d.uint64()) }
   455	
   456	func (e *encoder) int64(x int64) { e.uint64(uint64(x)) }
   457	
   458	func (d *decoder) value(v reflect.Value) {
   459		switch v.Kind() {
   460		case reflect.Array:
   461			l := v.Len()
   462			for i := 0; i < l; i++ {
   463				d.value(v.Index(i))
   464			}
   465	
   466		case reflect.Struct:
   467			t := v.Type()
   468			l := v.NumField()
   469			for i := 0; i < l; i++ {
   470				// Note: Calling v.CanSet() below is an optimization.
   471				// It would be sufficient to check the field name,
   472				// but creating the StructField info for each field is
   473				// costly (run "go test -bench=ReadStruct" and compare
   474				// results when making changes to this code).
   475				if v := v.Field(i); v.CanSet() || t.Field(i).Name != "_" {
   476					d.value(v)
   477				} else {
   478					d.skip(v)
   479				}
   480			}
   481	
   482		case reflect.Slice:
   483			l := v.Len()
   484			for i := 0; i < l; i++ {
   485				d.value(v.Index(i))
   486			}
   487	
   488		case reflect.Int8:
   489			v.SetInt(int64(d.int8()))
   490		case reflect.Int16:
   491			v.SetInt(int64(d.int16()))
   492		case reflect.Int32:
   493			v.SetInt(int64(d.int32()))
   494		case reflect.Int64:
   495			v.SetInt(d.int64())
   496	
   497		case reflect.Uint8:
   498			v.SetUint(uint64(d.uint8()))
   499		case reflect.Uint16:
   500			v.SetUint(uint64(d.uint16()))
   501		case reflect.Uint32:
   502			v.SetUint(uint64(d.uint32()))
   503		case reflect.Uint64:
   504			v.SetUint(d.uint64())
   505	
   506		case reflect.Float32:
   507			v.SetFloat(float64(math.Float32frombits(d.uint32())))
   508		case reflect.Float64:
   509			v.SetFloat(math.Float64frombits(d.uint64()))
   510	
   511		case reflect.Complex64:
   512			v.SetComplex(complex(
   513				float64(math.Float32frombits(d.uint32())),
   514				float64(math.Float32frombits(d.uint32())),
   515			))
   516		case reflect.Complex128:
   517			v.SetComplex(complex(
   518				math.Float64frombits(d.uint64()),
   519				math.Float64frombits(d.uint64()),
   520			))
   521		}
   522	}
   523	
   524	func (e *encoder) value(v reflect.Value) {
   525		switch v.Kind() {
   526		case reflect.Array:
   527			l := v.Len()
   528			for i := 0; i < l; i++ {
   529				e.value(v.Index(i))
   530			}
   531	
   532		case reflect.Struct:
   533			t := v.Type()
   534			l := v.NumField()
   535			for i := 0; i < l; i++ {
   536				// see comment for corresponding code in decoder.value()
   537				if v := v.Field(i); v.CanSet() || t.Field(i).Name != "_" {
   538					e.value(v)
   539				} else {
   540					e.skip(v)
   541				}
   542			}
   543	
   544		case reflect.Slice:
   545			l := v.Len()
   546			for i := 0; i < l; i++ {
   547				e.value(v.Index(i))
   548			}
   549	
   550		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
   551			switch v.Type().Kind() {
   552			case reflect.Int8:
   553				e.int8(int8(v.Int()))
   554			case reflect.Int16:
   555				e.int16(int16(v.Int()))
   556			case reflect.Int32:
   557				e.int32(int32(v.Int()))
   558			case reflect.Int64:
   559				e.int64(v.Int())
   560			}
   561	
   562		case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
   563			switch v.Type().Kind() {
   564			case reflect.Uint8:
   565				e.uint8(uint8(v.Uint()))
   566			case reflect.Uint16:
   567				e.uint16(uint16(v.Uint()))
   568			case reflect.Uint32:
   569				e.uint32(uint32(v.Uint()))
   570			case reflect.Uint64:
   571				e.uint64(v.Uint())
   572			}
   573	
   574		case reflect.Float32, reflect.Float64:
   575			switch v.Type().Kind() {
   576			case reflect.Float32:
   577				e.uint32(math.Float32bits(float32(v.Float())))
   578			case reflect.Float64:
   579				e.uint64(math.Float64bits(v.Float()))
   580			}
   581	
   582		case reflect.Complex64, reflect.Complex128:
   583			switch v.Type().Kind() {
   584			case reflect.Complex64:
   585				x := v.Complex()
   586				e.uint32(math.Float32bits(float32(real(x))))
   587				e.uint32(math.Float32bits(float32(imag(x))))
   588			case reflect.Complex128:
   589				x := v.Complex()
   590				e.uint64(math.Float64bits(real(x)))
   591				e.uint64(math.Float64bits(imag(x)))
   592			}
   593		}
   594	}
   595	
   596	func (d *decoder) skip(v reflect.Value) {
   597		n, _ := dataSize(v)
   598		d.buf = d.buf[n:]
   599	}
   600	
   601	func (e *encoder) skip(v reflect.Value) {
   602		n, _ := dataSize(v)
   603		for i := range e.buf[0:n] {
   604			e.buf[i] = 0
   605		}
   606		e.buf = e.buf[n:]
   607	}
   608	
   609	// intDataSize returns the size of the data required to represent the data when encoded.
   610	// It returns zero if the type cannot be implemented by the fast path in Read or Write.
   611	func intDataSize(data interface{}) int {
   612		switch data := data.(type) {
   613		case int8, *int8, *uint8:
   614			return 1
   615		case []int8:
   616			return len(data)
   617		case []uint8:
   618			return len(data)
   619		case int16, *int16, *uint16:
   620			return 2
   621		case []int16:
   622			return 2 * len(data)
   623		case []uint16:
   624			return 2 * len(data)
   625		case int32, *int32, *uint32:
   626			return 4
   627		case []int32:
   628			return 4 * len(data)
   629		case []uint32:
   630			return 4 * len(data)
   631		case int64, *int64, *uint64:
   632			return 8
   633		case []int64:
   634			return 8 * len(data)
   635		case []uint64:
   636			return 8 * len(data)
   637		}
   638		return 0
   639	}
   640	

View as plain text