1 // Copyright 2016 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.
5 // Package utf32 provides the UTF-32 Unicode encoding.
7 // Please note that support for UTF-32 is discouraged as it is a rare and
8 // inefficient encoding, unfit for use as an interchange format. For use
9 // on the web, the W3C strongly discourages its use
10 // (https://www.w3.org/TR/html5/document-metadata.html#charset)
11 // while WHATWG directly prohibits supporting it
12 // (https://html.spec.whatwg.org/multipage/syntax.html#character-encodings).
13 package utf32 // import "golang.org/x/text/encoding/unicode/utf32"
19 "golang.org/x/text/encoding"
20 "golang.org/x/text/encoding/internal/identifier"
21 "golang.org/x/text/transform"
24 // All lists a configuration for each IANA-defined UTF-32 variant.
25 var All = []encoding.Encoding{
26 UTF32(BigEndian, UseBOM),
27 UTF32(BigEndian, IgnoreBOM),
28 UTF32(LittleEndian, IgnoreBOM),
31 // ErrMissingBOM means that decoding UTF-32 input with ExpectBOM did not
32 // find a starting byte order mark.
33 var ErrMissingBOM = errors.New("encoding: missing byte order mark")
35 // UTF32 returns a UTF-32 Encoding for the given default endianness and
36 // byte order mark (BOM) policy.
38 // When decoding from UTF-32 to UTF-8, if the BOMPolicy is IgnoreBOM then
39 // neither BOMs U+FEFF nor ill-formed code units 0xFFFE0000 in the input
40 // stream will affect the endianness used for decoding. Instead BOMs will
41 // be output as their standard UTF-8 encoding "\xef\xbb\xbf" while
42 // 0xFFFE0000 code units will be output as "\xef\xbf\xbd", the standard
43 // UTF-8 encoding for the Unicode replacement character. If the BOMPolicy
44 // is UseBOM or ExpectBOM a starting BOM is not written to the UTF-8
45 // output. Instead, it overrides the default endianness e for the remainder
46 // of the transformation. Any subsequent BOMs U+FEFF or ill-formed code
47 // units 0xFFFE0000 will not affect the endianness used, and will instead
48 // be output as their standard UTF-8 (replacement) encodings. For UseBOM,
49 // if there is no starting BOM, it will proceed with the default
50 // Endianness. For ExpectBOM, in that case, the transformation will return
51 // early with an ErrMissingBOM error.
53 // When encoding from UTF-8 to UTF-32, a BOM will be inserted at the start
54 // of the output if the BOMPolicy is UseBOM or ExpectBOM. Otherwise, a BOM
55 // will not be inserted. The UTF-8 input does not need to contain a BOM.
57 // There is no concept of a 'native' endianness. If the UTF-32 data is
58 // produced and consumed in a greater context that implies a certain
59 // endianness, use IgnoreBOM. Otherwise, use ExpectBOM and always produce
62 // In the language of http://www.unicode.org/faq/utf_bom.html#bom10,
63 // IgnoreBOM corresponds to "Where the precise type of the data stream is
64 // known... the BOM should not be used" and ExpectBOM corresponds to "A
65 // particular protocol... may require use of the BOM".
66 func UTF32(e Endianness, b BOMPolicy) encoding.Encoding {
67 return utf32Encoding{config{e, b}, mibValue[e][b&bomMask]}
70 // mibValue maps Endianness and BOMPolicy settings to MIB constants for UTF-32.
71 // Note that some configurations map to the same MIB identifier.
72 var mibValue = map[Endianness][numBOMValues]identifier.MIB{
73 BigEndian: [numBOMValues]identifier.MIB{
74 IgnoreBOM: identifier.UTF32BE,
75 UseBOM: identifier.UTF32,
77 LittleEndian: [numBOMValues]identifier.MIB{
78 IgnoreBOM: identifier.UTF32LE,
79 UseBOM: identifier.UTF32,
81 // ExpectBOM is not widely used and has no valid MIB identifier.
84 // BOMPolicy is a UTF-32 encodings's byte order mark policy.
88 writeBOM BOMPolicy = 0x01
89 acceptBOM BOMPolicy = 0x02
90 requireBOM BOMPolicy = 0x04
91 bomMask BOMPolicy = 0x07
93 // HACK: numBOMValues == 8 triggers a bug in the 1.4 compiler (cannot have a
94 // map of an array of length 8 of a type that is also used as a key or value
95 // in another map). See golang.org/issue/11354.
96 // TODO: consider changing this value back to 8 if the use of 1.4.* has
100 // IgnoreBOM means to ignore any byte order marks.
101 IgnoreBOM BOMPolicy = 0
102 // Unicode-compliant interpretation for UTF-32BE/LE.
104 // UseBOM means that the UTF-32 form may start with a byte order mark,
105 // which will be used to override the default encoding.
106 UseBOM BOMPolicy = writeBOM | acceptBOM
107 // Unicode-compliant interpretation for UTF-32.
109 // ExpectBOM means that the UTF-32 form must start with a byte order mark,
110 // which will be used to override the default encoding.
111 ExpectBOM BOMPolicy = writeBOM | acceptBOM | requireBOM
112 // Consistent with BOMPolicy definition in golang.org/x/text/encoding/unicode
115 // Endianness is a UTF-32 encoding's default endianness.
119 // BigEndian is UTF-32BE.
120 BigEndian Endianness = false
121 // LittleEndian is UTF-32LE.
122 LittleEndian Endianness = true
126 endianness Endianness
130 type utf32Encoding struct {
135 func (u utf32Encoding) NewDecoder() *encoding.Decoder {
136 return &encoding.Decoder{Transformer: &utf32Decoder{
142 func (u utf32Encoding) NewEncoder() *encoding.Encoder {
143 return &encoding.Encoder{Transformer: &utf32Encoder{
144 endianness: u.endianness,
145 initialBOMPolicy: u.bomPolicy,
146 currentBOMPolicy: u.bomPolicy,
150 func (u utf32Encoding) ID() (mib identifier.MIB, other string) {
154 func (u utf32Encoding) String() string {
156 if u.endianness == LittleEndian {
167 return "UTF-32" + e + "E (" + b + " BOM)"
170 type utf32Decoder struct {
175 func (u *utf32Decoder) Reset() {
176 u.current = u.initial
179 func (u *utf32Decoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
181 if atEOF && u.current.bomPolicy&requireBOM != 0 {
182 return 0, 0, ErrMissingBOM
186 if u.current.bomPolicy&acceptBOM != 0 {
188 return 0, 0, transform.ErrShortSrc
191 case src[0] == 0x00 && src[1] == 0x00 && src[2] == 0xfe && src[3] == 0xff:
192 u.current.endianness = BigEndian
194 case src[0] == 0xff && src[1] == 0xfe && src[2] == 0x00 && src[3] == 0x00:
195 u.current.endianness = LittleEndian
198 if u.current.bomPolicy&requireBOM != 0 {
199 return 0, 0, ErrMissingBOM
202 u.current.bomPolicy = IgnoreBOM
207 for nSrc < len(src) {
208 if nSrc+3 < len(src) {
209 x := uint32(src[nSrc+0])<<24 | uint32(src[nSrc+1])<<16 |
210 uint32(src[nSrc+2])<<8 | uint32(src[nSrc+3])
211 if u.current.endianness == LittleEndian {
212 x = x>>24 | (x >> 8 & 0x0000FF00) | (x << 8 & 0x00FF0000) | x<<24
214 r, sSize = rune(x), 4
215 if dSize = utf8.RuneLen(r); dSize < 0 {
216 r, dSize = utf8.RuneError, 3
219 // 1..3 trailing bytes.
220 r, dSize, sSize = utf8.RuneError, 3, len(src)-nSrc
222 err = transform.ErrShortSrc
225 if nDst+dSize > len(dst) {
226 err = transform.ErrShortDst
229 nDst += utf8.EncodeRune(dst[nDst:], r)
232 return nDst, nSrc, err
235 type utf32Encoder struct {
236 endianness Endianness
237 initialBOMPolicy BOMPolicy
238 currentBOMPolicy BOMPolicy
241 func (u *utf32Encoder) Reset() {
242 u.currentBOMPolicy = u.initialBOMPolicy
245 func (u *utf32Encoder) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error) {
246 if u.currentBOMPolicy&writeBOM != 0 {
248 return 0, 0, transform.ErrShortDst
250 dst[0], dst[1], dst[2], dst[3] = 0x00, 0x00, 0xfe, 0xff
251 u.currentBOMPolicy = IgnoreBOM
255 r, size := rune(0), 0
256 for nSrc < len(src) {
259 // Decode a 1-byte rune.
260 if r < utf8.RuneSelf {
264 // Decode a multi-byte rune.
265 r, size = utf8.DecodeRune(src[nSrc:])
267 // All valid runes of size 1 (those below utf8.RuneSelf) were
268 // handled above. We have invalid UTF-8 or we haven't seen the
269 // full character yet.
270 if !atEOF && !utf8.FullRune(src[nSrc:]) {
271 err = transform.ErrShortSrc
277 if nDst+4 > len(dst) {
278 err = transform.ErrShortDst
282 dst[nDst+0] = uint8(r >> 24)
283 dst[nDst+1] = uint8(r >> 16)
284 dst[nDst+2] = uint8(r >> 8)
285 dst[nDst+3] = uint8(r)
290 if u.endianness == LittleEndian {
291 for i := 0; i < nDst; i += 4 {
292 dst[i], dst[i+1], dst[i+2], dst[i+3] = dst[i+3], dst[i+2], dst[i+1], dst[i]
295 return nDst, nSrc, err