encoding/unicode/unicode.go - third_party/github.com/golang/text - Git at Google

 // Copyright 2013 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // Package unicode provides Unicode encodings such as UTF-16.
 package unicode // import "golang.org/x/text/encoding/unicode"

 import (
 	"errors"
 	"unicode/utf16"
 	"unicode/utf8"

 	"golang.org/x/text/encoding"
 	"golang.org/x/text/encoding/internal"
 	"golang.org/x/text/encoding/internal/identifier"
 	"golang.org/x/text/internal/utf8internal"
 	"golang.org/x/text/runes"
 	"golang.org/x/text/transform"
 )

 // TODO: I think the Transformers really should return errors on unmatched
 // surrogate pairs and odd numbers of bytes. This is not required by RFC 2781,
 // which leaves it open, but is suggested by WhatWG. It will allow for all error
 // modes as defined by WhatWG: fatal, HTML and Replacement. This would require
 // the introduction of some kind of error type for conveying the erroneous code
 // point.

 // UTF8 is the UTF-8 encoding.
 var UTF8 encoding.Encoding = utf8enc

 var utf8enc = &internal.Encoding{
 	&internal.SimpleEncoding{utf8Decoder{}, runes.ReplaceIllFormed()},
 	"UTF-8",
 	identifier.UTF8,
 }

 type utf8Decoder struct{ transform.NopResetter }

 func (utf8Decoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
 	var pSrc int // point from which to start copy in src
 	var accept utf8internal.AcceptRange

 	// The decoder can only make the input larger, not smaller.
 	n := len(src)
 	if len(dst) < n {
 		err = transform.ErrShortDst
 		n = len(dst)
 		atEOF = false
 	}
 	for nSrc < n {
 		c := src[nSrc]
 		if c < utf8.RuneSelf {
 			nSrc++
 			continue
 		}
 		first := utf8internal.First[c]
 		size := int(first & utf8internal.SizeMask)
 		if first == utf8internal.FirstInvalid {
 			goto handleInvalid // invalid starter byte
 		}
 		accept = utf8internal.AcceptRanges[first>>utf8internal.AcceptShift]
 		if nSrc+size > n {
 			if !atEOF {
 				// We may stop earlier than necessary here if the short sequence
 				// has invalid bytes. Not checking for this simplifies the code
 				// and may avoid duplicate computations in certain conditions.
 				if err == nil {
 					err = transform.ErrShortSrc
 				}
 				break
 			}
 			// Determine the maximal subpart of an ill-formed subsequence.
 			switch {
 			case nSrc+1 >= n || src[nSrc+1] < accept.Lo || accept.Hi < src[nSrc+1]:
 				size = 1
 			case nSrc+2 >= n || src[nSrc+2] < utf8internal.LoCB || utf8internal.HiCB < src[nSrc+2]:
 				size = 2
 			default:
 				size = 3 // As we are short, the maximum is 3.
 			}
 			goto handleInvalid
 		}
 		if c = src[nSrc+1]; c < accept.Lo || accept.Hi < c {
 			size = 1
 			goto handleInvalid // invalid continuation byte
 		} else if size == 2 {
 		} else if c = src[nSrc+2]; c < utf8internal.LoCB || utf8internal.HiCB < c {
 			size = 2
 			goto handleInvalid // invalid continuation byte
 		} else if size == 3 {
 		} else if c = src[nSrc+3]; c < utf8internal.LoCB || utf8internal.HiCB < c {
 			size = 3
 			goto handleInvalid // invalid continuation byte
 		}
 		nSrc += size
 		continue

 	handleInvalid:
 		// Copy the scanned input so far.
 		nDst += copy(dst[nDst:], src[pSrc:nSrc])

 		// Append RuneError to the destination.
 		const runeError = "\ufffd"
 		if nDst+len(runeError) > len(dst) {
 			return nDst, nSrc, transform.ErrShortDst
 		}
 		nDst += copy(dst[nDst:], runeError)

 		// Skip the maximal subpart of an ill-formed subsequence according to
 		// the W3C standard way instead of the Go way. This Transform is
 		// probably the only place in the text repo where it is warranted.
 		nSrc += size
 		pSrc = nSrc

 		// Recompute the maximum source length.
 		if sz := len(dst) - nDst; sz < len(src)-nSrc {
 			err = transform.ErrShortDst
 			n = nSrc + sz
 			atEOF = false
 		}
 	}
 	return nDst + copy(dst[nDst:], src[pSrc:nSrc]), nSrc, err
 }

 // UTF16 returns a UTF-16 Encoding for the given default endianness and byte
 // order mark (BOM) policy.
 //
 // When decoding from UTF-16 to UTF-8, if the BOMPolicy is IgnoreBOM then
 // neither BOMs U+FEFF nor noncharacters U+FFFE in the input stream will affect
 // the endianness used for decoding, and will instead be output as their
 // standard UTF-8 encodings: "\xef\xbb\xbf" and "\xef\xbf\xbe". If the BOMPolicy
 // is UseBOM or ExpectBOM a staring BOM is not written to the UTF-8 output.
 // Instead, it overrides the default endianness e for the remainder of the
 // transformation. Any subsequent BOMs U+FEFF or noncharacters U+FFFE will not
 // affect the endianness used, and will instead be output as their standard
 // UTF-8 encodings. For UseBOM, if there is no starting BOM, it will proceed
 // with the default Endianness. For ExpectBOM, in that case, the transformation
 // will return early with an ErrMissingBOM error.
 //
 // When encoding from UTF-8 to UTF-16, a BOM will be inserted at the start of
 // the output if the BOMPolicy is UseBOM or ExpectBOM. Otherwise, a BOM will not
 // be inserted. The UTF-8 input does not need to contain a BOM.
 //
 // There is no concept of a 'native' endianness. If the UTF-16 data is produced
 // and consumed in a greater context that implies a certain endianness, use
 // IgnoreBOM. Otherwise, use ExpectBOM and always produce and consume a BOM.
 //
 // In the language of https://www.unicode.org/faq/utf_bom.html#bom10, IgnoreBOM
 // corresponds to "Where the precise type of the data stream is known... the
 // BOM should not be used" and ExpectBOM corresponds to "A particular
 // protocol... may require use of the BOM".
 func UTF16(e Endianness, b BOMPolicy) encoding.Encoding {
 	return utf16Encoding{config{e, b}, mibValue[e][b&bomMask]}
 }

 // mibValue maps Endianness and BOMPolicy settings to MIB constants. Note that
 // some configurations map to the same MIB identifier. RFC 2781 has requirements
 // and recommendations. Some of the "configurations" are merely recommendations,
 // so multiple configurations could match.
 var mibValue = map[Endianness][numBOMValues]identifier.MIB{
 	BigEndian: [numBOMValues]identifier.MIB{
 		IgnoreBOM: identifier.UTF16BE,
 		UseBOM:    identifier.UTF16, // BigEnding default is preferred by RFC 2781.
 		// TODO: acceptBOM | strictBOM would map to UTF16BE as well.
 	},
 	LittleEndian: [numBOMValues]identifier.MIB{
 		IgnoreBOM: identifier.UTF16LE,
 		UseBOM:    identifier.UTF16, // LittleEndian default is allowed and preferred on Windows.
 		// TODO: acceptBOM | strictBOM would map to UTF16LE as well.
 	},
 	// ExpectBOM is not widely used and has no valid MIB identifier.
 }

 // All lists a configuration for each IANA-defined UTF-16 variant.
 var All = []encoding.Encoding{
 	UTF8,
 	UTF16(BigEndian, UseBOM),
 	UTF16(BigEndian, IgnoreBOM),
 	UTF16(LittleEndian, IgnoreBOM),
 }

 // BOMPolicy is a UTF-16 encoding's byte order mark policy.
 type BOMPolicy uint8

 const (
 	writeBOM   BOMPolicy = 0x01
 	acceptBOM  BOMPolicy = 0x02
 	requireBOM BOMPolicy = 0x04
 	bomMask    BOMPolicy = 0x07

 	// HACK: numBOMValues == 8 triggers a bug in the 1.4 compiler (cannot have a
 	// map of an array of length 8 of a type that is also used as a key or value
 	// in another map). See golang.org/issue/11354.
 	// TODO: consider changing this value back to 8 if the use of 1.4.* has
 	// been minimized.
 	numBOMValues = 8 + 1

 	// IgnoreBOM means to ignore any byte order marks.
 	IgnoreBOM BOMPolicy = 0
 	// Common and RFC 2781-compliant interpretation for UTF-16BE/LE.

 	// UseBOM means that the UTF-16 form may start with a byte order mark, which
 	// will be used to override the default encoding.
 	UseBOM BOMPolicy = writeBOM | acceptBOM
 	// Common and RFC 2781-compliant interpretation for UTF-16.

 	// ExpectBOM means that the UTF-16 form must start with a byte order mark,
 	// which will be used to override the default encoding.
 	ExpectBOM BOMPolicy = writeBOM | acceptBOM | requireBOM
 	// Used in Java as Unicode (not to be confused with Java's UTF-16) and
 	// ICU's UTF-16,version=1. Not compliant with RFC 2781.

 	// TODO (maybe): strictBOM: BOM must match Endianness. This would allow:
 	// - UTF-16(B|L)E,version=1: writeBOM | acceptBOM | requireBOM | strictBOM
 	//    (UnicodeBig and UnicodeLittle in Java)
 	// - RFC 2781-compliant, but less common interpretation for UTF-16(B|L)E:
 	//    acceptBOM | strictBOM (e.g. assigned to CheckBOM).
 	// This addition would be consistent with supporting ExpectBOM.
 )

 // Endianness is a UTF-16 encoding's default endianness.
 type Endianness bool

 const (
 	// BigEndian is UTF-16BE.
 	BigEndian Endianness = false
 	// LittleEndian is UTF-16LE.
 	LittleEndian Endianness = true
 )

 // ErrMissingBOM means that decoding UTF-16 input with ExpectBOM did not find a
 // starting byte order mark.
 var ErrMissingBOM = errors.New("encoding: missing byte order mark")

 type utf16Encoding struct {
 	config
 	mib identifier.MIB
 }

 type config struct {
 	endianness Endianness
 	bomPolicy  BOMPolicy
 }

 func (u utf16Encoding) NewDecoder() *encoding.Decoder {
 	return &encoding.Decoder{Transformer: &utf16Decoder{
 		initial: u.config,
 		current: u.config,
 	}}
 }

 func (u utf16Encoding) NewEncoder() *encoding.Encoder {
 	return &encoding.Encoder{Transformer: &utf16Encoder{
 		endianness:       u.endianness,
 		initialBOMPolicy: u.bomPolicy,
 		currentBOMPolicy: u.bomPolicy,
 	}}
 }

 func (u utf16Encoding) ID() (mib identifier.MIB, other string) {
 	return u.mib, ""
 }

 func (u utf16Encoding) String() string {
 	e, b := "B", ""
 	if u.endianness == LittleEndian {
 		e = "L"
 	}
 	switch u.bomPolicy {
 	case ExpectBOM:
 		b = "Expect"
 	case UseBOM:
 		b = "Use"
 	case IgnoreBOM:
 		b = "Ignore"
 	}
 	return "UTF-16" + e + "E (" + b + " BOM)"
 }

 type utf16Decoder struct {
 	initial config
 	current config
 }

 func (u *utf16Decoder) Reset() {
 	u.current = u.initial
 }

 func (u *utf16Decoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
 	if len(src) == 0 {
 		if atEOF && u.current.bomPolicy&requireBOM != 0 {
 			return 0, 0, ErrMissingBOM
 		}
 		return 0, 0, nil
 	}
 	if u.current.bomPolicy&acceptBOM != 0 {
 		if len(src) < 2 {
 			return 0, 0, transform.ErrShortSrc
 		}
 		switch {
 		case src[0] == 0xfe && src[1] == 0xff:
 			u.current.endianness = BigEndian
 			nSrc = 2
 		case src[0] == 0xff && src[1] == 0xfe:
 			u.current.endianness = LittleEndian
 			nSrc = 2
 		default:
 			if u.current.bomPolicy&requireBOM != 0 {
 				return 0, 0, ErrMissingBOM
 			}
 		}
 		u.current.bomPolicy = IgnoreBOM
 	}

 	var r rune
 	var dSize, sSize int
 	for nSrc < len(src) {
 		if nSrc+1 < len(src) {
 			x := uint16(src[nSrc+0])<<8 | uint16(src[nSrc+1])
 			if u.current.endianness == LittleEndian {
 				x = x>>8 | x<<8
 			}
 			r, sSize = rune(x), 2
 			if utf16.IsSurrogate(r) {
 				if nSrc+3 < len(src) {
 					x = uint16(src[nSrc+2])<<8 | uint16(src[nSrc+3])
 					if u.current.endianness == LittleEndian {
 						x = x>>8 | x<<8
 					}
 					// Save for next iteration if it is not a high surrogate.
 					if isHighSurrogate(rune(x)) {
 						r, sSize = utf16.DecodeRune(r, rune(x)), 4
 					}
 				} else if !atEOF {
 					err = transform.ErrShortSrc
 					break
 				}
 			}
 			if dSize = utf8.RuneLen(r); dSize < 0 {
 				r, dSize = utf8.RuneError, 3
 			}
 		} else if atEOF {
 			// Single trailing byte.
 			r, dSize, sSize = utf8.RuneError, 3, 1
 		} else {
 			err = transform.ErrShortSrc
 			break
 		}
 		if nDst+dSize > len(dst) {
 			err = transform.ErrShortDst
 			break
 		}
 		nDst += utf8.EncodeRune(dst[nDst:], r)
 		nSrc += sSize
 	}
 	return nDst, nSrc, err
 }

 func isHighSurrogate(r rune) bool {
 	return 0xDC00 <= r && r <= 0xDFFF
 }

 type utf16Encoder struct {
 	endianness       Endianness
 	initialBOMPolicy BOMPolicy
 	currentBOMPolicy BOMPolicy
 }

 func (u *utf16Encoder) Reset() {
 	u.currentBOMPolicy = u.initialBOMPolicy
 }

 func (u *utf16Encoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
 	if u.currentBOMPolicy&writeBOM != 0 {
 		if len(dst) < 2 {
 			return 0, 0, transform.ErrShortDst
 		}
 		dst[0], dst[1] = 0xfe, 0xff
 		u.currentBOMPolicy = IgnoreBOM
 		nDst = 2
 	}

 	r, size := rune(0), 0
 	for nSrc < len(src) {
 		r = rune(src[nSrc])

 		// Decode a 1-byte rune.
 		if r < utf8.RuneSelf {
 			size = 1

 		} else {
 			// Decode a multi-byte rune.
 			r, size = utf8.DecodeRune(src[nSrc:])
 			if size == 1 {
 				// All valid runes of size 1 (those below utf8.RuneSelf) were
 				// handled above. We have invalid UTF-8 or we haven't seen the
 				// full character yet.
 				if !atEOF && !utf8.FullRune(src[nSrc:]) {
 					err = transform.ErrShortSrc
 					break
 				}
 			}
 		}

 		if r <= 0xffff {
 			if nDst+2 > len(dst) {
 				err = transform.ErrShortDst
 				break
 			}
 			dst[nDst+0] = uint8(r >> 8)
 			dst[nDst+1] = uint8(r)
 			nDst += 2
 		} else {
 			if nDst+4 > len(dst) {
 				err = transform.ErrShortDst
 				break
 			}
 			r1, r2 := utf16.EncodeRune(r)
 			dst[nDst+0] = uint8(r1 >> 8)
 			dst[nDst+1] = uint8(r1)
 			dst[nDst+2] = uint8(r2 >> 8)
 			dst[nDst+3] = uint8(r2)
 			nDst += 4
 		}
 		nSrc += size
 	}

 	if u.endianness == LittleEndian {
 		for i := 0; i < nDst; i += 2 {
 			dst[i], dst[i+1] = dst[i+1], dst[i]
 		}
 	}
 	return nDst, nSrc, err
 }
	// Copyright 2013 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// Package unicode provides Unicode encodings such as UTF-16.
	package unicode // import "golang.org/x/text/encoding/unicode"

	import (
	"errors"
	"unicode/utf16"
	"unicode/utf8"

	"golang.org/x/text/encoding"
	"golang.org/x/text/encoding/internal"
	"golang.org/x/text/encoding/internal/identifier"
	"golang.org/x/text/internal/utf8internal"
	"golang.org/x/text/runes"
	"golang.org/x/text/transform"
	)

	// TODO: I think the Transformers really should return errors on unmatched
	// surrogate pairs and odd numbers of bytes. This is not required by RFC 2781,
	// which leaves it open, but is suggested by WhatWG. It will allow for all error
	// modes as defined by WhatWG: fatal, HTML and Replacement. This would require
	// the introduction of some kind of error type for conveying the erroneous code
	// point.

	// UTF8 is the UTF-8 encoding.
	var UTF8 encoding.Encoding = utf8enc

	var utf8enc = &internal.Encoding{
	&internal.SimpleEncoding{utf8Decoder{}, runes.ReplaceIllFormed()},
	"UTF-8",
	identifier.UTF8,
	}

	type utf8Decoder struct{ transform.NopResetter }

	func (utf8Decoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
	var pSrc int // point from which to start copy in src
	var accept utf8internal.AcceptRange

	// The decoder can only make the input larger, not smaller.
	n := len(src)
	if len(dst) < n {
	err = transform.ErrShortDst
	n = len(dst)
	atEOF = false
	}
	for nSrc < n {
	c := src[nSrc]
	if c < utf8.RuneSelf {
	nSrc++
	continue
	}
	first := utf8internal.First[c]
	size := int(first & utf8internal.SizeMask)
	if first == utf8internal.FirstInvalid {
	goto handleInvalid // invalid starter byte
	}
	accept = utf8internal.AcceptRanges[first>>utf8internal.AcceptShift]
	if nSrc+size > n {
	if !atEOF {
	// We may stop earlier than necessary here if the short sequence
	// has invalid bytes. Not checking for this simplifies the code
	// and may avoid duplicate computations in certain conditions.
	if err == nil {
	err = transform.ErrShortSrc
	}
	break
	}
	// Determine the maximal subpart of an ill-formed subsequence.
	switch {
	case nSrc+1 >= n \|\| src[nSrc+1] < accept.Lo \|\| accept.Hi < src[nSrc+1]:
	size = 1
	case nSrc+2 >= n \|\| src[nSrc+2] < utf8internal.LoCB \|\| utf8internal.HiCB < src[nSrc+2]:
	size = 2
	default:
	size = 3 // As we are short, the maximum is 3.
	}
	goto handleInvalid
	}
	if c = src[nSrc+1]; c < accept.Lo \|\| accept.Hi < c {
	size = 1
	goto handleInvalid // invalid continuation byte
	} else if size == 2 {
	} else if c = src[nSrc+2]; c < utf8internal.LoCB \|\| utf8internal.HiCB < c {
	size = 2
	goto handleInvalid // invalid continuation byte
	} else if size == 3 {
	} else if c = src[nSrc+3]; c < utf8internal.LoCB \|\| utf8internal.HiCB < c {
	size = 3
	goto handleInvalid // invalid continuation byte
	}
	nSrc += size
	continue

	handleInvalid:
	// Copy the scanned input so far.
	nDst += copy(dst[nDst:], src[pSrc:nSrc])

	// Append RuneError to the destination.
	const runeError = "\ufffd"
	if nDst+len(runeError) > len(dst) {
	return nDst, nSrc, transform.ErrShortDst
	}
	nDst += copy(dst[nDst:], runeError)

	// Skip the maximal subpart of an ill-formed subsequence according to
	// the W3C standard way instead of the Go way. This Transform is
	// probably the only place in the text repo where it is warranted.
	nSrc += size
	pSrc = nSrc

	// Recompute the maximum source length.
	if sz := len(dst) - nDst; sz < len(src)-nSrc {
	err = transform.ErrShortDst
	n = nSrc + sz
	atEOF = false
	}
	}
	return nDst + copy(dst[nDst:], src[pSrc:nSrc]), nSrc, err
	}

	// UTF16 returns a UTF-16 Encoding for the given default endianness and byte
	// order mark (BOM) policy.
	//
	// When decoding from UTF-16 to UTF-8, if the BOMPolicy is IgnoreBOM then
	// neither BOMs U+FEFF nor noncharacters U+FFFE in the input stream will affect
	// the endianness used for decoding, and will instead be output as their
	// standard UTF-8 encodings: "\xef\xbb\xbf" and "\xef\xbf\xbe". If the BOMPolicy
	// is UseBOM or ExpectBOM a staring BOM is not written to the UTF-8 output.
	// Instead, it overrides the default endianness e for the remainder of the
	// transformation. Any subsequent BOMs U+FEFF or noncharacters U+FFFE will not
	// affect the endianness used, and will instead be output as their standard
	// UTF-8 encodings. For UseBOM, if there is no starting BOM, it will proceed
	// with the default Endianness. For ExpectBOM, in that case, the transformation
	// will return early with an ErrMissingBOM error.
	//
	// When encoding from UTF-8 to UTF-16, a BOM will be inserted at the start of
	// the output if the BOMPolicy is UseBOM or ExpectBOM. Otherwise, a BOM will not
	// be inserted. The UTF-8 input does not need to contain a BOM.
	//
	// There is no concept of a 'native' endianness. If the UTF-16 data is produced
	// and consumed in a greater context that implies a certain endianness, use
	// IgnoreBOM. Otherwise, use ExpectBOM and always produce and consume a BOM.
	//
	// In the language of https://www.unicode.org/faq/utf_bom.html#bom10, IgnoreBOM
	// corresponds to "Where the precise type of the data stream is known... the
	// BOM should not be used" and ExpectBOM corresponds to "A particular
	// protocol... may require use of the BOM".
	func UTF16(e Endianness, b BOMPolicy) encoding.Encoding {
	return utf16Encoding{config{e, b}, mibValue[e][b&bomMask]}
	}

	// mibValue maps Endianness and BOMPolicy settings to MIB constants. Note that
	// some configurations map to the same MIB identifier. RFC 2781 has requirements
	// and recommendations. Some of the "configurations" are merely recommendations,
	// so multiple configurations could match.
	var mibValue = map[Endianness][numBOMValues]identifier.MIB{
	BigEndian: [numBOMValues]identifier.MIB{
	IgnoreBOM: identifier.UTF16BE,
	UseBOM: identifier.UTF16, // BigEnding default is preferred by RFC 2781.
	// TODO: acceptBOM \| strictBOM would map to UTF16BE as well.
	},
	LittleEndian: [numBOMValues]identifier.MIB{
	IgnoreBOM: identifier.UTF16LE,
	UseBOM: identifier.UTF16, // LittleEndian default is allowed and preferred on Windows.
	// TODO: acceptBOM \| strictBOM would map to UTF16LE as well.
	},
	// ExpectBOM is not widely used and has no valid MIB identifier.
	}

	// All lists a configuration for each IANA-defined UTF-16 variant.
	var All = []encoding.Encoding{
	UTF8,
	UTF16(BigEndian, UseBOM),
	UTF16(BigEndian, IgnoreBOM),
	UTF16(LittleEndian, IgnoreBOM),
	}

	// BOMPolicy is a UTF-16 encoding's byte order mark policy.
	type BOMPolicy uint8

	const (
	writeBOM BOMPolicy = 0x01
	acceptBOM BOMPolicy = 0x02
	requireBOM BOMPolicy = 0x04
	bomMask BOMPolicy = 0x07

	// HACK: numBOMValues == 8 triggers a bug in the 1.4 compiler (cannot have a
	// map of an array of length 8 of a type that is also used as a key or value
	// in another map). See golang.org/issue/11354.
	// TODO: consider changing this value back to 8 if the use of 1.4.* has
	// been minimized.
	numBOMValues = 8 + 1

	// IgnoreBOM means to ignore any byte order marks.
	IgnoreBOM BOMPolicy = 0
	// Common and RFC 2781-compliant interpretation for UTF-16BE/LE.

	// UseBOM means that the UTF-16 form may start with a byte order mark, which
	// will be used to override the default encoding.
	UseBOM BOMPolicy = writeBOM \| acceptBOM
	// Common and RFC 2781-compliant interpretation for UTF-16.

	// ExpectBOM means that the UTF-16 form must start with a byte order mark,
	// which will be used to override the default encoding.
	ExpectBOM BOMPolicy = writeBOM \| acceptBOM \| requireBOM
	// Used in Java as Unicode (not to be confused with Java's UTF-16) and
	// ICU's UTF-16,version=1. Not compliant with RFC 2781.

	// TODO (maybe): strictBOM: BOM must match Endianness. This would allow:
	// - UTF-16(B\|L)E,version=1: writeBOM \| acceptBOM \| requireBOM \| strictBOM
	// (UnicodeBig and UnicodeLittle in Java)
	// - RFC 2781-compliant, but less common interpretation for UTF-16(B\|L)E:
	// acceptBOM \| strictBOM (e.g. assigned to CheckBOM).
	// This addition would be consistent with supporting ExpectBOM.
	)

	// Endianness is a UTF-16 encoding's default endianness.
	type Endianness bool

	const (
	// BigEndian is UTF-16BE.
	BigEndian Endianness = false
	// LittleEndian is UTF-16LE.
	LittleEndian Endianness = true
	)

	// ErrMissingBOM means that decoding UTF-16 input with ExpectBOM did not find a
	// starting byte order mark.
	var ErrMissingBOM = errors.New("encoding: missing byte order mark")

	type utf16Encoding struct {
	config
	mib identifier.MIB
	}

	type config struct {
	endianness Endianness
	bomPolicy BOMPolicy
	}

	func (u utf16Encoding) NewDecoder() *encoding.Decoder {
	return &encoding.Decoder{Transformer: &utf16Decoder{
	initial: u.config,
	current: u.config,
	}}
	}

	func (u utf16Encoding) NewEncoder() *encoding.Encoder {
	return &encoding.Encoder{Transformer: &utf16Encoder{
	endianness: u.endianness,
	initialBOMPolicy: u.bomPolicy,
	currentBOMPolicy: u.bomPolicy,
	}}
	}

	func (u utf16Encoding) ID() (mib identifier.MIB, other string) {
	return u.mib, ""
	}

	func (u utf16Encoding) String() string {
	e, b := "B", ""
	if u.endianness == LittleEndian {
	e = "L"
	}
	switch u.bomPolicy {
	case ExpectBOM:
	b = "Expect"
	case UseBOM:
	b = "Use"
	case IgnoreBOM:
	b = "Ignore"
	}
	return "UTF-16" + e + "E (" + b + " BOM)"
	}

	type utf16Decoder struct {
	initial config
	current config
	}

	func (u *utf16Decoder) Reset() {
	u.current = u.initial
	}

	func (u *utf16Decoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
	if len(src) == 0 {
	if atEOF && u.current.bomPolicy&requireBOM != 0 {
	return 0, 0, ErrMissingBOM
	}
	return 0, 0, nil
	}
	if u.current.bomPolicy&acceptBOM != 0 {
	if len(src) < 2 {
	return 0, 0, transform.ErrShortSrc
	}
	switch {
	case src[0] == 0xfe && src[1] == 0xff:
	u.current.endianness = BigEndian
	nSrc = 2
	case src[0] == 0xff && src[1] == 0xfe:
	u.current.endianness = LittleEndian
	nSrc = 2
	default:
	if u.current.bomPolicy&requireBOM != 0 {
	return 0, 0, ErrMissingBOM
	}
	}
	u.current.bomPolicy = IgnoreBOM
	}

	var r rune
	var dSize, sSize int
	for nSrc < len(src) {
	if nSrc+1 < len(src) {
	x := uint16(src[nSrc+0])<<8 \| uint16(src[nSrc+1])
	if u.current.endianness == LittleEndian {
	x = x>>8 \| x<<8
	}
	r, sSize = rune(x), 2
	if utf16.IsSurrogate(r) {
	if nSrc+3 < len(src) {
	x = uint16(src[nSrc+2])<<8 \| uint16(src[nSrc+3])
	if u.current.endianness == LittleEndian {
	x = x>>8 \| x<<8
	}
	// Save for next iteration if it is not a high surrogate.
	if isHighSurrogate(rune(x)) {
	r, sSize = utf16.DecodeRune(r, rune(x)), 4
	}
	} else if !atEOF {
	err = transform.ErrShortSrc
	break
	}
	}
	if dSize = utf8.RuneLen(r); dSize < 0 {
	r, dSize = utf8.RuneError, 3
	}
	} else if atEOF {
	// Single trailing byte.
	r, dSize, sSize = utf8.RuneError, 3, 1
	} else {
	err = transform.ErrShortSrc
	break
	}
	if nDst+dSize > len(dst) {
	err = transform.ErrShortDst
	break
	}
	nDst += utf8.EncodeRune(dst[nDst:], r)
	nSrc += sSize
	}
	return nDst, nSrc, err
	}

	func isHighSurrogate(r rune) bool {
	return 0xDC00 <= r && r <= 0xDFFF
	}

	type utf16Encoder struct {
	endianness Endianness
	initialBOMPolicy BOMPolicy
	currentBOMPolicy BOMPolicy
	}

	func (u *utf16Encoder) Reset() {
	u.currentBOMPolicy = u.initialBOMPolicy
	}

	func (u *utf16Encoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
	if u.currentBOMPolicy&writeBOM != 0 {
	if len(dst) < 2 {
	return 0, 0, transform.ErrShortDst
	}
	dst[0], dst[1] = 0xfe, 0xff
	u.currentBOMPolicy = IgnoreBOM
	nDst = 2
	}

	r, size := rune(0), 0
	for nSrc < len(src) {
	r = rune(src[nSrc])

	// Decode a 1-byte rune.
	if r < utf8.RuneSelf {
	size = 1

	} else {
	// Decode a multi-byte rune.
	r, size = utf8.DecodeRune(src[nSrc:])
	if size == 1 {
	// All valid runes of size 1 (those below utf8.RuneSelf) were
	// handled above. We have invalid UTF-8 or we haven't seen the
	// full character yet.
	if !atEOF && !utf8.FullRune(src[nSrc:]) {
	err = transform.ErrShortSrc
	break
	}
	}
	}

	if r <= 0xffff {
	if nDst+2 > len(dst) {
	err = transform.ErrShortDst
	break
	}
	dst[nDst+0] = uint8(r >> 8)
	dst[nDst+1] = uint8(r)
	nDst += 2
	} else {
	if nDst+4 > len(dst) {
	err = transform.ErrShortDst
	break
	}
	r1, r2 := utf16.EncodeRune(r)
	dst[nDst+0] = uint8(r1 >> 8)
	dst[nDst+1] = uint8(r1)
	dst[nDst+2] = uint8(r2 >> 8)
	dst[nDst+3] = uint8(r2)
	nDst += 4
	}
	nSrc += size
	}

	if u.endianness == LittleEndian {
	for i := 0; i < nDst; i += 2 {
	dst[i], dst[i+1] = dst[i+1], dst[i]
	}
	}
	return nDst, nSrc, err
	}