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