Source file src/encoding/json/internal/jsonflags/flags.go
1 // Copyright 2023 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 //go:build goexperiment.jsonv2 6 7 // jsonflags implements all the optional boolean flags. 8 // These flags are shared across both "json", "jsontext", and "jsonopts". 9 package jsonflags 10 11 import "encoding/json/internal" 12 13 // Bools represents zero or more boolean flags, all set to true or false. 14 // The least-significant bit is the boolean value of all flags in the set. 15 // The remaining bits identify which particular flags. 16 // 17 // In common usage, this is OR'd with 0 or 1. For example: 18 // - (AllowInvalidUTF8 | 0) means "AllowInvalidUTF8 is false" 19 // - (Multiline | Indent | 1) means "Multiline and Indent are true" 20 type Bools uint64 21 22 func (Bools) JSONOptions(internal.NotForPublicUse) {} 23 24 const ( 25 // AllFlags is the set of all flags. 26 AllFlags = AllCoderFlags | AllArshalV2Flags | AllArshalV1Flags 27 28 // AllCoderFlags is the set of all encoder/decoder flags. 29 AllCoderFlags = (maxCoderFlag - 1) - initFlag 30 31 // AllArshalV2Flags is the set of all v2 marshal/unmarshal flags. 32 AllArshalV2Flags = (maxArshalV2Flag - 1) - (maxCoderFlag - 1) 33 34 // AllArshalV1Flags is the set of all v1 marshal/unmarshal flags. 35 AllArshalV1Flags = (maxArshalV1Flag - 1) - (maxArshalV2Flag - 1) 36 37 // NonBooleanFlags is the set of non-boolean flags, 38 // where the value is some other concrete Go type. 39 // The value of the flag is stored within jsonopts.Struct. 40 NonBooleanFlags = 0 | 41 Indent | 42 IndentPrefix | 43 ByteLimit | 44 DepthLimit | 45 Marshalers | 46 Unmarshalers 47 48 // DefaultV1Flags is the set of booleans flags that default to true under 49 // v1 semantics. None of the non-boolean flags differ between v1 and v2. 50 DefaultV1Flags = 0 | 51 AllowDuplicateNames | 52 AllowInvalidUTF8 | 53 EscapeForHTML | 54 EscapeForJS | 55 PreserveRawStrings | 56 Deterministic | 57 FormatNilMapAsNull | 58 FormatNilSliceAsNull | 59 MatchCaseInsensitiveNames | 60 CallMethodsWithLegacySemantics | 61 FormatByteArrayAsArray | 62 FormatBytesWithLegacySemantics | 63 FormatDurationAsNano | 64 MatchCaseSensitiveDelimiter | 65 MergeWithLegacySemantics | 66 OmitEmptyWithLegacySemantics | 67 ParseBytesWithLooseRFC4648 | 68 ParseTimeWithLooseRFC3339 | 69 ReportErrorsWithLegacySemantics | 70 StringifyWithLegacySemantics | 71 UnmarshalArrayFromAnyLength 72 73 // AnyWhitespace reports whether the encoded output might have any whitespace. 74 AnyWhitespace = Multiline | SpaceAfterColon | SpaceAfterComma 75 76 // WhitespaceFlags is the set of flags related to whitespace formatting. 77 // In contrast to AnyWhitespace, this includes Indent and IndentPrefix 78 // as those settings take no effect if Multiline is false. 79 WhitespaceFlags = AnyWhitespace | Indent | IndentPrefix 80 81 // AnyEscape is the set of flags related to escaping in a JSON string. 82 AnyEscape = EscapeForHTML | EscapeForJS 83 84 // CanonicalizeNumbers is the set of flags related to raw number canonicalization. 85 CanonicalizeNumbers = CanonicalizeRawInts | CanonicalizeRawFloats 86 ) 87 88 // Encoder and decoder flags. 89 const ( 90 initFlag Bools = 1 << iota // reserved for the boolean value itself 91 92 AllowDuplicateNames // encode or decode 93 AllowInvalidUTF8 // encode or decode 94 WithinArshalCall // encode or decode; for internal use by json.Marshal and json.Unmarshal 95 OmitTopLevelNewline // encode only; for internal use by json.Marshal and json.MarshalWrite 96 PreserveRawStrings // encode only 97 CanonicalizeRawInts // encode only 98 CanonicalizeRawFloats // encode only 99 ReorderRawObjects // encode only 100 EscapeForHTML // encode only 101 EscapeForJS // encode only 102 Multiline // encode only 103 SpaceAfterColon // encode only 104 SpaceAfterComma // encode only 105 Indent // encode only; non-boolean flag 106 IndentPrefix // encode only; non-boolean flag 107 ByteLimit // encode or decode; non-boolean flag 108 DepthLimit // encode or decode; non-boolean flag 109 110 maxCoderFlag 111 ) 112 113 // Marshal and Unmarshal flags (for v2). 114 const ( 115 _ Bools = (maxCoderFlag >> 1) << iota 116 117 StringifyNumbers // marshal or unmarshal 118 Deterministic // marshal only 119 FormatNilMapAsNull // marshal only 120 FormatNilSliceAsNull // marshal only 121 OmitZeroStructFields // marshal only 122 MatchCaseInsensitiveNames // marshal or unmarshal 123 RejectUnknownMembers // unmarshal only 124 Marshalers // marshal only; non-boolean flag 125 Unmarshalers // unmarshal only; non-boolean flag 126 127 maxArshalV2Flag 128 ) 129 130 // Marshal and Unmarshal flags (for v1). 131 const ( 132 _ Bools = (maxArshalV2Flag >> 1) << iota 133 134 CallMethodsWithLegacySemantics // marshal or unmarshal 135 FormatByteArrayAsArray // marshal or unmarshal 136 FormatBytesWithLegacySemantics // marshal or unmarshal 137 FormatDurationAsNano // marshal or unmarshal 138 MatchCaseSensitiveDelimiter // marshal or unmarshal 139 MergeWithLegacySemantics // unmarshal 140 OmitEmptyWithLegacySemantics // marshal 141 ParseBytesWithLooseRFC4648 // unmarshal 142 ParseTimeWithLooseRFC3339 // unmarshal 143 ReportErrorsWithLegacySemantics // marshal or unmarshal 144 StringifyWithLegacySemantics // marshal or unmarshal 145 StringifyBoolsAndStrings // marshal or unmarshal; for internal use by jsonv2.makeStructArshaler 146 UnmarshalAnyWithRawNumber // unmarshal; for internal use by jsonv1.Decoder.UseNumber 147 UnmarshalArrayFromAnyLength // unmarshal 148 149 maxArshalV1Flag 150 ) 151 152 // bitsUsed is the number of bits used in the 64-bit boolean flags 153 const bitsUsed = 41 154 155 // Static compile check that bitsUsed and maxArshalV1Flag are in sync. 156 const _ = uint64((1<<bitsUsed)-maxArshalV1Flag) + uint64(maxArshalV1Flag-(1<<bitsUsed)) 157 158 // Flags is a set of boolean flags. 159 // If the presence bit is zero, then the value bit must also be zero. 160 // The least-significant bit of both fields is always zero. 161 // 162 // Unlike Bools, which can represent a set of bools that are all true or false, 163 // Flags represents a set of bools, each individually may be true or false. 164 type Flags struct{ Presence, Values uint64 } 165 166 // Join joins two sets of flags such that the latter takes precedence. 167 func (dst *Flags) Join(src Flags) { 168 // Copy over all source presence bits over to the destination (using OR), 169 // then invert the source presence bits to clear out source value (using AND-NOT), 170 // then copy over source value bits over to the destination (using OR). 171 // e.g., dst := Flags{Presence: 0b_1100_0011, Values: 0b_1000_0011} 172 // e.g., src := Flags{Presence: 0b_0101_1010, Values: 0b_1001_0010} 173 dst.Presence |= src.Presence // e.g., 0b_1100_0011 | 0b_0101_1010 -> 0b_110_11011 174 dst.Values &= ^src.Presence // e.g., 0b_1000_0011 & 0b_1010_0101 -> 0b_100_00001 175 dst.Values |= src.Values // e.g., 0b_1000_0001 | 0b_1001_0010 -> 0b_100_10011 176 } 177 178 // Set sets both the presence and value for the provided bool (or set of bools). 179 func (fs *Flags) Set(f Bools) { 180 // Select out the bits for the flag identifiers (everything except LSB), 181 // then set the presence for all the identifier bits (using OR), 182 // then invert the identifier bits to clear out the values (using AND-NOT), 183 // then copy over all the identifier bits to the value if LSB is 1. 184 // e.g., fs := Flags{Presence: 0b_0101_0010, Values: 0b_0001_0010} 185 // e.g., f := 0b_1001_0001 186 id := uint64(f) &^ uint64(1) // e.g., 0b_1001_0001 & 0b_1111_1110 -> 0b_1001_0000 187 fs.Presence |= id // e.g., 0b_0101_0010 | 0b_1001_0000 -> 0b_1101_0011 188 fs.Values &= ^id // e.g., 0b_0001_0010 & 0b_0110_1111 -> 0b_0000_0010 189 fs.Values |= uint64(f&1) * id // e.g., 0b_0000_0010 | 0b_1001_0000 -> 0b_1001_0010 190 } 191 192 // Get reports whether the bool (or any of the bools) is true. 193 // This is generally only used with a singular bool. 194 // The value bit of f (i.e., the LSB) is ignored. 195 func (fs Flags) Get(f Bools) bool { 196 return fs.Values&uint64(f) > 0 197 } 198 199 // Has reports whether the bool (or any of the bools) is set. 200 // The value bit of f (i.e., the LSB) is ignored. 201 func (fs Flags) Has(f Bools) bool { 202 return fs.Presence&uint64(f) > 0 203 } 204 205 // Clear clears both the presence and value for the provided bool or bools. 206 // The value bit of f (i.e., the LSB) is ignored. 207 func (fs *Flags) Clear(f Bools) { 208 // Invert f to produce a mask to clear all bits in f (using AND). 209 // e.g., fs := Flags{Presence: 0b_0101_0010, Values: 0b_0001_0010} 210 // e.g., f := 0b_0001_1000 211 mask := uint64(^f) // e.g., 0b_0001_1000 -> 0b_1110_0111 212 fs.Presence &= mask // e.g., 0b_0101_0010 & 0b_1110_0111 -> 0b_0100_0010 213 fs.Values &= mask // e.g., 0b_0001_0010 & 0b_1110_0111 -> 0b_0000_0010 214 } 215