String Manipulation Opcodes

This section documents the strings instructions available in CandleVM.

For operand encodings, see the executable format reference.

Strings

String objects contain UTF-8 text.

Opcode byte	Opcode	Operand bytes	Behavior
50	NewString	destination: register, string: string	Creates a String from the UTF-8 text operand and stores its ObjectRef value.
51	StringLen	destination: register, string: register	Stores the number of Unicode scalar values as a numeric value (Byte for lengths 0–255, otherwise Number).
52	StringConcat	destination: register, left: register, right: register	Concatenates two ObjectRef values to a String and stores a newly allocated String. Other types or references to non-String objects fail.
53	StringFromChars	destination: register, array: register	Builds and stores a String from an Array whose every element is a Char; a non-Char element raises ArrayTypeMismatch.
54	StringToChars	destination: register, string: register	Allocates an Array of Char values from the String's Unicode scalar values.
55	StringFromBytes	destination: register, buffer: register	Decodes the entire buffer as UTF-8 and stores a string; invalid UTF-8 raises InvalidString.
56	StringToBytes	destination: register, string: register	Copies the String's UTF-8 bytes into a newly allocated buffer.
57	StringOf	destination: register, value: register	Formats a value as a string. ObjectRef values format the referenced heap object; other values use their runtime display representation. The result is allocated as a new String.
58	StringLowercase	destination: register, string: register	Converts the String to lowercase using Unicode-aware casing and allocates the result as a new String.
59	StringUppercase	destination: register, string: register	Converts the String to uppercase using Unicode-aware casing and allocates the result as a new String.
60	StringToNumber	destination: register, string: register	Parses a trimmed decimal or optionally signed hexadecimal String. Invalid input, NaN, and infinity raise InvalidNumber.