hex.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 hex implements hexadecimal encoding and decoding.
     6  package hex
     7  
     8  import (
     9  	"errors"
    10  	"fmt"
    11  	"io"
    12  	"strings"
    13  )
    14  
    15  const hextable = "0123456789abcdef"
    16  
    17  // EncodedLen returns the length of an encoding of n source bytes.
    18  // Specifically, it returns n * 2.
    19  func EncodedLen(n int) int { return n * 2 }
    20  
    21  // Encode encodes src into EncodedLen(len(src))
    22  // bytes of dst. As a convenience, it returns the number
    23  // of bytes written to dst, but this value is always EncodedLen(len(src)).
    24  // Encode implements hexadecimal encoding.
    25  func Encode(dst, src []byte) int {
    26  	j := 0
    27  	for _, v := range src {
    28  		dst[j] = hextable[v>>4]
    29  		dst[j+1] = hextable[v&0x0f]
    30  		j += 2
    31  	}
    32  	return len(src) * 2
    33  }
    34  
    35  // ErrLength reports an attempt to decode an odd-length input
    36  // using Decode or DecodeString.
    37  // The stream-based Decoder returns io.ErrUnexpectedEOF instead of ErrLength.
    38  var ErrLength = errors.New("encoding/hex: odd length hex string")
    39  
    40  // InvalidByteError values describe errors resulting from an invalid byte in a hex string.
    41  type InvalidByteError byte
    42  
    43  func (e InvalidByteError) Error() string {
    44  	return fmt.Sprintf("encoding/hex: invalid byte: %#U", rune(e))
    45  }
    46  
    47  // DecodedLen returns the length of a decoding of x source bytes.
    48  // Specifically, it returns x / 2.
    49  func DecodedLen(x int) int { return x / 2 }
    50  
    51  // Decode decodes src into DecodedLen(len(src)) bytes,
    52  // returning the actual number of bytes written to dst.
    53  //
    54  // Decode expects that src contains only hexadecimal
    55  // characters and that src has even length.
    56  // If the input is malformed, Decode returns the number
    57  // of bytes decoded before the error.
    58  func Decode(dst, src []byte) (int, error) {
    59  	i, j := 0, 1
    60  	for ; j < len(src); j += 2 {
    61  		a, ok := fromHexChar(src[j-1])
    62  		if !ok {
    63  			return i, InvalidByteError(src[j-1])
    64  		}
    65  		b, ok := fromHexChar(src[j])
    66  		if !ok {
    67  			return i, InvalidByteError(src[j])
    68  		}
    69  		dst[i] = (a << 4) | b
    70  		i++
    71  	}
    72  	if len(src)%2 == 1 {
    73  		// Check for invalid char before reporting bad length,
    74  		// since the invalid char (if present) is an earlier problem.
    75  		if _, ok := fromHexChar(src[j-1]); !ok {
    76  			return i, InvalidByteError(src[j-1])
    77  		}
    78  		return i, ErrLength
    79  	}
    80  	return i, nil
    81  }
    82  
    83  // fromHexChar converts a hex character into its value and a success flag.
    84  func fromHexChar(c byte) (byte, bool) {
    85  	switch {
    86  	case '0' <= c && c <= '9':
    87  		return c - '0', true
    88  	case 'a' <= c && c <= 'f':
    89  		return c - 'a' + 10, true
    90  	case 'A' <= c && c <= 'F':
    91  		return c - 'A' + 10, true
    92  	}
    93  
    94  	return 0, false
    95  }
    96  
    97  // EncodeToString returns the hexadecimal encoding of src.
    98  func EncodeToString(src []byte) string {
    99  	dst := make([]byte, EncodedLen(len(src)))
   100  	Encode(dst, src)
   101  	return string(dst)
   102  }
   103  
   104  // DecodeString returns the bytes represented by the hexadecimal string s.
   105  //
   106  // DecodeString expects that src contains only hexadecimal
   107  // characters and that src has even length.
   108  // If the input is malformed, DecodeString returns
   109  // the bytes decoded before the error.
   110  func DecodeString(s string) ([]byte, error) {
   111  	src := []byte(s)
   112  	// We can use the source slice itself as the destination
   113  	// because the decode loop increments by one and then the 'seen' byte is not used anymore.
   114  	n, err := Decode(src, src)
   115  	return src[:n], err
   116  }
   117  
   118  // Dump returns a string that contains a hex dump of the given data. The format
   119  // of the hex dump matches the output of `hexdump -C` on the command line.
   120  func Dump(data []byte) string {
   121  	if len(data) == 0 {
   122  		return ""
   123  	}
   124  
   125  	var buf strings.Builder
   126  	// Dumper will write 79 bytes per complete 16 byte chunk, and at least
   127  	// 64 bytes for whatever remains. Round the allocation up, since only a
   128  	// maximum of 15 bytes will be wasted.
   129  	buf.Grow((1 + ((len(data) - 1) / 16)) * 79)
   130  
   131  	dumper := Dumper(&buf)
   132  	dumper.Write(data)
   133  	dumper.Close()
   134  	return buf.String()
   135  }
   136  
   137  // bufferSize is the number of hexadecimal characters to buffer in encoder and decoder.
   138  const bufferSize = 1024
   139  
   140  type encoder struct {
   141  	w   io.Writer
   142  	err error
   143  	out [bufferSize]byte // output buffer
   144  }
   145  
   146  // NewEncoder returns an io.Writer that writes lowercase hexadecimal characters to w.
   147  func NewEncoder(w io.Writer) io.Writer {
   148  	return &encoder{w: w}
   149  }
   150  
   151  func (e *encoder) Write(p []byte) (n int, err error) {
   152  	for len(p) > 0 && e.err == nil {
   153  		chunkSize := bufferSize / 2
   154  		if len(p) < chunkSize {
   155  			chunkSize = len(p)
   156  		}
   157  
   158  		var written int
   159  		encoded := Encode(e.out[:], p[:chunkSize])
   160  		written, e.err = e.w.Write(e.out[:encoded])
   161  		n += written / 2
   162  		p = p[chunkSize:]
   163  	}
   164  	return n, e.err
   165  }
   166  
   167  type decoder struct {
   168  	r   io.Reader
   169  	err error
   170  	in  []byte           // input buffer (encoded form)
   171  	arr [bufferSize]byte // backing array for in
   172  }
   173  
   174  // NewDecoder returns an io.Reader that decodes hexadecimal characters from r.
   175  // NewDecoder expects that r contain only an even number of hexadecimal characters.
   176  func NewDecoder(r io.Reader) io.Reader {
   177  	return &decoder{r: r}
   178  }
   179  
   180  func (d *decoder) Read(p []byte) (n int, err error) {
   181  	// Fill internal buffer with sufficient bytes to decode
   182  	if len(d.in) < 2 && d.err == nil {
   183  		var numCopy, numRead int
   184  		numCopy = copy(d.arr[:], d.in) // Copies either 0 or 1 bytes
   185  		numRead, d.err = d.r.Read(d.arr[numCopy:])
   186  		d.in = d.arr[:numCopy+numRead]
   187  		if d.err == io.EOF && len(d.in)%2 != 0 {
   188  			if _, ok := fromHexChar(d.in[len(d.in)-1]); !ok {
   189  				d.err = InvalidByteError(d.in[len(d.in)-1])
   190  			} else {
   191  				d.err = io.ErrUnexpectedEOF
   192  			}
   193  		}
   194  	}
   195  
   196  	// Decode internal buffer into output buffer
   197  	if numAvail := len(d.in) / 2; len(p) > numAvail {
   198  		p = p[:numAvail]
   199  	}
   200  	numDec, err := Decode(p, d.in[:len(p)*2])
   201  	d.in = d.in[2*numDec:]
   202  	if err != nil {
   203  		d.in, d.err = nil, err // Decode error; discard input remainder
   204  	}
   205  
   206  	if len(d.in) < 2 {
   207  		return numDec, d.err // Only expose errors when buffer fully consumed
   208  	}
   209  	return numDec, nil
   210  }
   211  
   212  // Dumper returns a WriteCloser that writes a hex dump of all written data to
   213  // w. The format of the dump matches the output of `hexdump -C` on the command
   214  // line.
   215  func Dumper(w io.Writer) io.WriteCloser {
   216  	return &dumper{w: w}
   217  }
   218  
   219  type dumper struct {
   220  	w          io.Writer
   221  	rightChars [18]byte
   222  	buf        [14]byte
   223  	used       int  // number of bytes in the current line
   224  	n          uint // number of bytes, total
   225  	closed     bool
   226  }
   227  
   228  func toChar(b byte) byte {
   229  	if b < 32 || b > 126 {
   230  		return '.'
   231  	}
   232  	return b
   233  }
   234  
   235  func (h *dumper) Write(data []byte) (n int, err error) {
   236  	if h.closed {
   237  		return 0, errors.New("encoding/hex: dumper closed")
   238  	}
   239  
   240  	// Output lines look like:
   241  	// 00000010  2e 2f 30 31 32 33 34 35  36 37 38 39 3a 3b 3c 3d  |./0123456789:;<=|
   242  	// ^ offset                          ^ extra space              ^ ASCII of line.
   243  	for i := range data {
   244  		if h.used == 0 {
   245  			// At the beginning of a line we print the current
   246  			// offset in hex.
   247  			h.buf[0] = byte(h.n >> 24)
   248  			h.buf[1] = byte(h.n >> 16)
   249  			h.buf[2] = byte(h.n >> 8)
   250  			h.buf[3] = byte(h.n)
   251  			Encode(h.buf[4:], h.buf[:4])
   252  			h.buf[12] = ' '
   253  			h.buf[13] = ' '
   254  			_, err = h.w.Write(h.buf[4:])
   255  			if err != nil {
   256  				return
   257  			}
   258  		}
   259  		Encode(h.buf[:], data[i:i+1])
   260  		h.buf[2] = ' '
   261  		l := 3
   262  		if h.used == 7 {
   263  			// There's an additional space after the 8th byte.
   264  			h.buf[3] = ' '
   265  			l = 4
   266  		} else if h.used == 15 {
   267  			// At the end of the line there's an extra space and
   268  			// the bar for the right column.
   269  			h.buf[3] = ' '
   270  			h.buf[4] = '|'
   271  			l = 5
   272  		}
   273  		_, err = h.w.Write(h.buf[:l])
   274  		if err != nil {
   275  			return
   276  		}
   277  		n++
   278  		h.rightChars[h.used] = toChar(data[i])
   279  		h.used++
   280  		h.n++
   281  		if h.used == 16 {
   282  			h.rightChars[16] = '|'
   283  			h.rightChars[17] = '\n'
   284  			_, err = h.w.Write(h.rightChars[:])
   285  			if err != nil {
   286  				return
   287  			}
   288  			h.used = 0
   289  		}
   290  	}
   291  	return
   292  }
   293  
   294  func (h *dumper) Close() (err error) {
   295  	// See the comments in Write() for the details of this format.
   296  	if h.closed {
   297  		return
   298  	}
   299  	h.closed = true
   300  	if h.used == 0 {
   301  		return
   302  	}
   303  	h.buf[0] = ' '
   304  	h.buf[1] = ' '
   305  	h.buf[2] = ' '
   306  	h.buf[3] = ' '
   307  	h.buf[4] = '|'
   308  	nBytes := h.used
   309  	for h.used < 16 {
   310  		l := 3
   311  		if h.used == 7 {
   312  			l = 4
   313  		} else if h.used == 15 {
   314  			l = 5
   315  		}
   316  		_, err = h.w.Write(h.buf[:l])
   317  		if err != nil {
   318  			return
   319  		}
   320  		h.used++
   321  	}
   322  	h.rightChars[nBytes] = '|'
   323  	h.rightChars[nBytes+1] = '\n'
   324  	_, err = h.w.Write(h.rightChars[:nBytes+2])
   325  	return
   326  }
   327
View as plain text