Merge pull request #3760 from dkorpel/hexstring-revive

Document hex strings

Signed-off-by: Petar Kirov <PetarKirov@users.noreply.github.com>
Merged-on-behalf-of: Petar Kirov <PetarKirov@users.noreply.github.com>

Author: dlang-bot

spec/expression.dd

@@ -2006,6 +2006,43 @@ $(H3 $(LEGACY_LNAME2 StringLiteral, string_literals, String Literals))
         C style implicit concatenation without an intervening operator is
         error prone and not supported in D.)
 
+
+$(H3 $(LNAME2 hex_string_literals, Hex String Literals))
+    $(P Because hex string literals contain binary data not limited to textual data, they allow additional conversions over other string literals.)
+
+    $(P A hex string literal implicitly converts to a constant `byte[]` or `ubyte[]`.)
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
+        -------------
+        immutable ubyte[] b = x"3F 80 00 00";
+        const byte[] c = x"3F 80 00 00";
+        -------------
+        )
+
+    $(P A hex string literal can be explicitly cast to an array of integers with a larger size than 1.
+        A big endian byte order in the hex string will be assumed.)
+
+        $(SPEC_RUNNABLE_EXAMPLE_RUN
+        -------------
+        static immutable uint[] data = cast(immutable uint[]) x"AABBCCDD";
+        static assert(data[0] == 0xAABBCCDD);
+        -------------
+        )
+
+    $(P This requires the length of the hex string to be a multiple of the array element's size in bytes.)
+        $(SPEC_RUNNABLE_EXAMPLE_FAIL
+        -------------
+        static e = cast(immutable ushort[]) x"AA BB CC";
+        // Error, length of 3 bytes is not a multiple of 2, the size of a `ushort`
+        -------------
+        )
+
+    $(P When a hex string literal gets constant folded, the result is no longer considered a hex string literal)
+        $(SPEC_RUNNABLE_EXAMPLE_FAIL
+        -------------
+        static immutable byte[] b = x"AA" ~ "G"; // Error: cannot convert `string` to `immutable byte[]`
+        -------------
+        )
+
 $(H3 $(LNAME2 array_literals, Array Literals))
 
 $(GRAMMAR

spec/lex.dd

@@ -291,10 +291,11 @@ $(GNAME StringLiteral):
     $(GLINK DoubleQuotedString)
     $(GLINK DelimitedString)
     $(GLINK TokenString)
+    $(GLINK HexString)
 )
 $(P
 A string literal is either a wysiwyg quoted string, a double quoted
-string, a delimited string, or a token string.
+string, a delimited string, a token string, or a hex string.
 )
 
 $(P In all string literal forms, an $(GLINK EndOfLine) is regarded as a single
@@ -491,6 +492,33 @@ $(GNAME TokenStringToken):
                                 // __EOF__ is not a token, it's end of file
         ---
 
+$(H3 $(LNAME2 hex_strings, Hex Strings))
+$(GRAMMAR
+$(GNAME HexString):
+    $(B x") $(GLINK HexStringChars)$(OPT) $(B ") $(GLINK StringPostfix)$(OPT)
+
+$(GNAME HexStringChars):
+    $(GLINK HexStringChar)
+    $(GLINK HexStringChar) $(GSELF HexStringChars)
+
+$(GNAME HexStringChar):
+    $(GLINK HexDigit)
+    $(GLINK WhiteSpace)
+    $(GLINK EndOfLine)
+)
+
+        $(P Hex strings allow string literals to be created using hex data.
+        The hex data need not form valid UTF characters.
+        )
+
+        ---
+        x"0A"              // same as "\x0A"
+        x"00 FBCD 32FD 0A" // same as "\x00\xFB\xCD\x32\xFD\x0A"
+        ---
+
+        $(P Whitespace and newlines are ignored, so the hex data can be easily
+        formatted. The number of hex characters must be a multiple of 2.)
+
 $(H3 $(LNAME2 string_postfix, String Postfix))
 
 $(GRAMMAR_LEX