String16 Type Support (lestring16 / bestring16)#

lestring16 and bestring16 are magic(5) type keywords for reading UCS-2 16-bit encoded strings from binary files. They are the primary way magic rules match Windows-style wide-character strings (e.g., NTLDR, PE resource strings, registry data).

AST Representation#

Both keywords map to the TypeKind::String16 variant in src/parser/ast.rs:

String16 {
    endian: Endianness,
}

lestring16 produces Endianness::Little; bestring16 produces Endianness::Big. There is no bare string16 keyword — magic(5) only defines the explicitly-endian forms 1.

Parser Support#

Keyword recognition is in parse_type_keyword in src/parser/types.rs. lestring16 and bestring16 are listed before string in the alt() combinator so the longer keyword wins 2.

Keyword-to-kind mapping is handled by string16_family, which is called from type_keyword_to_kind. Unlike regex and search, the String16 variant is fully constructed from the keyword alone — no suffix parsing is needed.

Evaluator Support#

Reading#

The evaluator dispatches TypeKind::String16 { endian } to read_string16 in src/evaluator/types/string.rs 3.

read_string16 behavior:

• Reads 2-byte code units starting at offset, interpreting them with the given Endianness
• Stops at a U+0000 terminator (0x00 0x00), buffer end, or after STRING16_MAX_UNITS (8192) code units 4
• Surrogate-pair code units (U+D800–U+DFFF) are replaced with U+FFFD — UCS-2 does not resolve surrogates 5
• A trailing odd byte (buffer length not even) is silently ignored 6
• Returns TypeReadError::BufferOverrun when offset >= buffer.len() 7
• Returns Ok(Value::String(decoded)) on success, with non-ASCII BMP characters preserved

Anchor Advancement#

For relative-offset child rules (&N), the evaluator calls string16_bytes_consumed 8. This mirrors read_string16's walk and returns the byte count consumed, including the 2-byte NUL terminator when one is found 9. The count is always a multiple of 2.

Serialization#

Code generation for built-in rules handles TypeKind::String16 in src/parser/codegen.rs 10, emitting the endian field via serialize_endianness.

Key Constraints#

Related Source Files#