hex.go

Documentation: encoding/hex

		 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