Strings

Overview

String verbs manipulate, inspect, search, and convert string values.

String operands may be string literals or string registers unless otherwise specified. Instructions that produce strings require a string register as their destination; instructions that produce numeric results require an integer register.

Strings are stored internally as UTF-16, but lengths and positions are measured in Unicode characters rather than UTF-16 code units. Characters represented by multiple UTF-16 code units therefore count as a single character.

CHAR and ORD convert between characters and UTF-32 Unicode codepoints.

Unless otherwise specified, string instructions do not modify any registers other than their destination.

Basic string operations

SUPR — String Upper

SUPR <dst> <str>

Converts a string to uppercase and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to convert.

Modified registers

Register Description
dst Uppercase string.

Examples

-- Convert a string to uppercase.
SUPR s0 "Hello, world!"
-- > s0 = "HELLO, WORLD!"

SLWR — String Lower

SLWR <dst> <str>

Converts a string to lowercase and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to convert.

Modified registers

Register Description
dst Lowercase string.

Examples

-- Convert a string to lowercase.
SLWR s0 "Hello, world!"
-- > s0 = "hello, world!"

SLEN — String Length

SLEN <dst> <str>

Calculates the length of a string and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.
2 str String value — String to measure.

Modified registers

Register Description
dst String length.

Examples

-- Measure a string.
SLEN r0 "Hello"
-- > r0 = 5

Search & manipulation

SFIND — String Find

SFIND <dst> <haystack> <needle>

Searches a string for another string and stores the position of the match in the destination register.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.
2 haystack String value — String to search.
3 needle String value — String to search for.

Modified registers

Register Description
dst Position of match.

Examples

-- Find a substring.
SFIND r0 "Hello, world!" "world"
-- > r0 = 7

Notes

  • Returns -1 if no match is found.

SJOIN — String Join

SJOIN <dst> <lhs> <rhs>

Joins two strings together and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 lhs String value — Left-hand string.
3 rhs String value — Right-hand string.

Modified registers

Register Description
dst Joined string.

Examples

-- Join two strings.
SJOIN s0 "Hello, " "world!"
-- > s0 = "Hello, world!"

-- Append to an existing string.
SJOIN s0 s0 "!"
-- > s0 = s0 + "!"

SINS — String Insert

SINS <dst> <str> <ins> <pos>

Inserts a string into another string at the specified position and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — Original string.
3 ins String value — String to insert.
4 pos Integer value — Insertion position.

Modified registers

Register Description
dst Modified string.

Examples

-- Insert text into a string.
SINS s0 "Hello!" ", world" 5
-- > s0 = "Hello, world!"

SSUB — Substring

SSUB <dst> <str> <start> <end>

Extracts a range from a string and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — Source string.
3 start Integer value — Starting position.
4 end Integer value — Ending position.

Modified registers

Register Description
dst Extracted substring.

Examples

-- Extract part of a string.
SSUB s0 "Hello, world!" 0 4
-- > s0 = "Hello"

-- Extract the last 5 characters.
SSUB s0 "Hello, world!" -5 -1
-- > s0 = "orld!"

-- Positions before the beginning of the string are clamped.
SSUB s0 "Hello" -9 3
-- > s0 = "Hell"

-- Positions beyond the end of the string are clamped.
SSUB s0 "Hello" 2 999
-- > s0 = "llo"

-- A range entirely outside the string is empty.
SSUB s0 "Hello" 7 10
-- > s0 = ""

-- A reversed range is empty.
SSUB s0 "Hello" 4 2
-- > s0 = ""

Notes

  • start and end are inclusive.
  • Negative positions index from the end of the string, where -1 is the final character.
  • If start resolves before the beginning of the string, it is clamped to the beginning.
  • If end extends beyond the end of the string, it is clamped to the end.
  • If end resolves before the beginning of the string, the result is an empty string.
  • If start is beyond the end of the string, the result is an empty string.
  • If the resolved start position is greater than the resolved end position, the result is an empty string.

SREP — String Replace

SREP <dst> <str> <old> <new> <count>

Replaces occurrences of a string and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to modify.
3 old String value — String to search for.
4 new String value — Replacement string.
5 count Integer value — Number and direction to replace.

Modified registers

Register Description
dst Modified string.

Examples

-- Replace one occurrence from the left.
SREP s0 "one two two" "two" "three" 1
-- > s0 = "one three two"

-- Replace one occurrence from the right.
SREP s0 "one two two" "two" "three" -1
-- > s0 = "one two three"

-- Replace all occurrences.
SREP s0 "one two two" "two" "three" 0
-- > s0 = "one three three"

Notes

  • If count is 0, all matching substrings are replaced.
  • If count is positive, up to count matches are replaced starting from the beginning of the string.
  • If count is negative, up to |count| matches are replaced starting from the end of the string.

Padding & trimming

SPADL — String Pad Left

SPADL <dst> <str> <pad> <len>

Pads the left side of a string until it reaches or exceeds the specified length.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to pad.
3 pad String value — Padding string.
4 len Integer value ≥ 0 Desired length.

Modified registers

Register Description
dst Padded string.

Examples

-- Pad a number with zeroes.
SPADL s0 "42" "0" 5
-- > s0 = "00042"

-- Pad using a multi-character string.
SPADL s0 "42" "ab" 5
-- > s0 = "abab42"

Notes

  • If pad contains multiple characters, the result may exceed len.

SPADR — String Pad Right

SPADR <dst> <str> <pad> <len>

Pads the right side of a string until it reaches or exceeds the specified length.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to pad.
3 pad String value — Padding string.
4 len Integer value ≥ 0 Desired length.

Modified registers

Register Description
dst Padded string.

Examples

-- Pad a label with spaces.
SPADR s0 "READY" " " 8
-- > s0 = "READY   "

-- Pad using a multi-character string.
SPADR s0 "42" "ab" 5
-- > s0 = "42abab"

Notes

  • If pad contains multiple characters, the result may exceed len.

STRIML — String Trim Left

STRIML <dst> <str> <trim>

Repeatedly removes the specified string from the left side of another string and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to trim.
3 trim String value — String to remove.

Modified registers

Register Description
dst Trimmed string.

Examples

-- Trim characters from the left.
STRIML s0 "00042" "0"
-- > s0 = "42"

-- Trim a multi-character string.
STRIML s0 ".....@" ".."
-- > s0 = ".@"

Notes

  • Trimming stops when the start of the string no longer matches trim.

STRIMR — String Trim Right

STRIMR <dst> <str> <trim>

Repeatedly removes the specified string from the right side of another string and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 str String value — String to trim.
3 trim String value — String to remove.

Modified registers

Register Description
dst Trimmed string.

Examples

-- Trim characters from the right.
STRIMR s0 "Hello..." "."
-- > s0 = "Hello"

-- Trim a multi-character string.
STRIMR s0 "@....." ".."
-- > s0 = "@."

Notes

  • Trimming stops when the end of the string no longer matches trim.

Character conversion

Strings are stored internally as UTF-16, while CHAR and ORD operate on complete UTF-32 Unicode codepoints.

This allows characters outside the Basic Multilingual Plane to be handled without exposing UTF-16 surrogate pairs to NCL programs.

CHAR — Codepoint to Character

CHAR <dst> <cp>

Converts a UTF-32 Unicode codepoint to a single-character string and stores the result in the destination register.

Operands

Position Name Type Range Description
1 dst String register — Destination register.
2 cp Integer value 0–0x10FFFF Unicode codepoint.

Modified registers

Register Description
dst Character.

Examples

-- Convert a codepoint to a character.
CHAR s0 65
-- > s0 = "A"

-- Characters outside the Basic Multilingual Plane are supported.
CHAR s0 128640 -- 0x1F680
-- > s0 = "🚀"

Notes

  • A value of 0 produces an empty string.
  • Valid characters range from 0x1 through 0x10FFFF.
  • Invalid codepoints, surrogate values, and unsupported noncharacters produce the Unicode replacement character (�).

ORD — Character to Codepoint

ORD <dst> <str> <pos>

Returns the UTF-32 Unicode codepoint of the character at the specified position.

Operands

Position Name Type Range Description
1 dst Integer register — Destination register.
2 str String value — Source string.
3 pos Integer value — Character position.

Modified registers

Register Description
dst Unicode codepoint.

Examples

-- Get a character's codepoint.
ORD r0 "ABC" 1
-- > r0 = 66

-- Negative positions index from the end.
ORD r0 "ABC" -1
-- > r0 = 67

-- Characters outside the Basic Multilingual Plane are returned
-- as complete UTF-32 codepoints.
ORD r0 "🚀" 0
-- > r0 = 128640 -- 0x1F680

Notes

  • pos may be negative to index from the end of the string.
  • If pos is outside the bounds of the string, 0 is returned.
  • Unpaired UTF-16 surrogate values return 63 (0x3F).