String

UTF-8 string with value semantics and Kotlin-style API

It

self {
  std::string handle;
  It();
  It(const I8* s) : handle(s ? s : "") {}
  It(const std::string& s) : handle(s) {}
  It operator+(const It& o) { return It(handle + o.handle); }
  It operator+(const I8* s) { return It(handle + (s ? s : "")); }
  friend It operator+(const I8* s, const It& o) { return It(std::string(s ? s : "") + o.handle); }
  U8 operator==(const It& o) const { return handle == o.handle ? 1 : 0; }
  U8 operator!=(const It& o) const { return handle != o.handle ? 1 : 0; }
}

from

Create a String from a C string literal or pointer — null becomes empty string

String from(const I8* s)

Parameters

s — Source C string (may be null)

Returns — New String value

fromI32

Create a String from a signed 32-bit integer

String fromI32(I32 n)

Parameters

n — Integer to convert

Returns — Decimal string representation

fromI64

Create a String from a signed 64-bit integer

String fromI64(I64 n)

Parameters

n — Integer to convert

Returns — Decimal string representation

fromF32

Create a String from a 32-bit float

String fromF32(F32 f)

Parameters

f — Float to convert

Returns — Decimal string representation

fromF64

Create a String from a 64-bit float

String fromF64(F64 f)

Parameters

f — Float to convert

Returns — Decimal string representation

c

Return the underlying C string pointer — valid only while the String is alive

const I8* c(const String s)

Parameters

s — Source string

Returns — Read-only C string pointer

strdup

Return a heap-allocated copy of the C string — caller must free()

I8* strdup(const String s)

Parameters

s — Source string

Returns — Owned C string pointer

length

Return the number of bytes in the string (not Unicode code points)

U64 length(const String s)

Parameters

s — Source string

Returns — Byte count

isEmpty

Return 1 if the string has zero bytes, 0 otherwise

U8 isEmpty(const String s)

Parameters

s — Source string

Returns — 1 if empty, 0 if not

charAt

Return the byte at the given index — no bounds checking

I8 charAt(const String s, I32 i)

Parameters

s — Source string
i — Zero-based byte index

Returns — Byte value at that position

equals

Return 1 if both strings have identical content

U8 equals(const String a, const String b)

Parameters

a — First string
b — Second string

Returns — 1 if equal, 0 if not

contains

Return 1 if sub appears anywhere inside s

U8 contains(const String s, const String sub)

Parameters

s — String to search in
sub — Substring to find

Returns — 1 if found, 0 if not

startsWith

Return 1 if s begins with prefix

U8 startsWith(const String s, const String prefix)

Parameters

s — String to test
prefix — Prefix to look for

Returns — 1 if s starts with prefix, 0 if not

endsWith

Return 1 if s ends with suffix

U8 endsWith(const String s, const String suffix)

Parameters

s — String to test
suffix — Suffix to look for

Returns — 1 if s ends with suffix, 0 if not

indexOf

Return the byte offset of the first occurrence of sub, or -1 if not found

I64 indexOf(const String s, const String sub)

Parameters

s — String to search in
sub — Substring to find

Returns — Zero-based offset, or -1

lastIndexOf

Return the byte offset of the last occurrence of sub, or -1 if not found

I64 lastIndexOf(const String s, const String sub)

Parameters

s — String to search in
sub — Substring to find

Returns — Zero-based offset, or -1

toUpperCase

Return a copy of s with all ASCII letters uppercased

String toUpperCase(const String s)

Parameters

s — Source string

Returns — Uppercased string

toLowerCase

Return a copy of s with all ASCII letters lowercased

String toLowerCase(const String s)

Parameters

s — Source string

Returns — Lowercased string

trim

Return a copy of s with leading and trailing ASCII whitespace removed

String trim(const String s)

Parameters

s — Source string

Returns — Trimmed string

trimStart

Return a copy of s with leading ASCII whitespace removed

String trimStart(const String s)

Parameters

s — Source string

Returns — Left-trimmed string

trimEnd

Return a copy of s with trailing ASCII whitespace removed

String trimEnd(const String s)

Parameters

s — Source string

Returns — Right-trimmed string

replace

Return a copy of s with every occurrence of from replaced by to

String replace(const String s, const String from, const String to)

Parameters

s — Source string
from — Substring to find
to — Replacement value

Returns — Modified string

substring

Return the substring from start to the end of the string

String substring(const String s, I32 start)

Parameters

s — Source string
start — Zero-based start index (inclusive)

Returns — Substring

substring

Return the substring from start (inclusive) to end (exclusive)

String substring(const String s, I32 start, I32 end)

Parameters

s — Source string
start — Zero-based start index (inclusive)
end — Zero-based end index (exclusive)

Returns — Substring

repeat

Return the string repeated n times

String repeat(const String s, I32 n)

Parameters

s — Source string
n — Number of repetitions

Returns — Repeated string

reverse

Return a copy of s with its bytes in reverse order

String reverse(const String s)

Parameters

s — Source string

Returns — Reversed string

toI32

Parse the string as a signed 32-bit integer — throws on failure

I32 toI32(const String s)

Parameters

s — Source string

Returns — Parsed integer

toI64

Parse the string as a signed 64-bit integer — throws on failure

I64 toI64(const String s)

Parameters

s — Source string

Returns — Parsed integer

toF32

Parse the string as a 32-bit float — throws on failure

F32 toF32(const String s)

Parameters

s — Source string

Returns — Parsed float

toF64

Parse the string as a 64-bit float — throws on failure

F64 toF64(const String s)

Parameters

s — Source string

Returns — Parsed float

format

Build a String using printf-style formatting

String format(const I8* fmt, ...)

Parameters

fmt — Format string (same specifiers as printf)

Returns — Formatted string (capped at 4096 bytes)

split

Split s on every occurrence of delim and return all parts as a list

List<String> split(const String s, const String delim)

Parameters

s — Source string
delim — Delimiter to split on

Returns — List of substrings (always at least one element)

join

Concatenate all strings in parts, inserting sep between each pair

String join(List<String> parts, const String sep)

Parameters

parts — List of strings to join
sep — Separator inserted between elements

Returns — Joined string

toString

Return the underlying C string pointer — used by %T format specifier

const I8* toString(const String s)

Parameters

s — Source string

Returns — Read-only C string pointer