core.strings

StringBuilder : struct {
    data : []u8
    capacity : i64
    allocator : ^Allocator
}

Utf8DecodeResult : struct {
    codepoint : rune
    byte_count : i64 = 0
    status : Utf8Status = Utf8Status.End
}

StringBuilder : func() -> StringBuilder

StringBuilder : func(capacity : i64) -> StringBuilder

StringBuilder : func(capacity : i64, allocator : ^Allocator) -> StringBuilder

StringBuilderDeinit : func(self : ^StringBuilder)

Frees a StringBuilder's backing storage and resets its fields.

Parameters:
  self : ^StringBuilder - builder to deinitialize. May be null.

Notes:
  - This frees only the builder's internal buffer. Strings returned by
    to_string() remain owned by their callers.

reserve : func(self : ^StringBuilder, needed : i64) -> bool

append : func(self : ^StringBuilder, value : string) -> bool

append : func(self : ^StringBuilder, value : []u8) -> bool

Appends a borrowed byte range to the builder without constructing a
temporary string. The bytes are copied into the builder's owned storage.

Parameters:
  self  : ^StringBuilder - builder to mutate.
  value : []u8           - borrowed bytes to copy.

Returns:
  true when the bytes were appended or the range is valid and empty; false
  for an invalid range, integer overflow, or allocation failure.

append : func(self : ^StringBuilder, value : char) -> bool

clear : func(self : ^StringBuilder)

to_string : func(self : ^StringBuilder) -> [string, StringStatus]

Copies the builder's bytes into an independently-owned, terminated string.

Returns:
  [string, StringStatus]
    - StringStatus.Ok for a successful copy or a valid empty builder.
    - StringStatus.InvalidArg for a null or internally invalid builder.
    - StringStatus.InvalidAllocator when the builder has no allocator.
    - StringStatus.OutOfMemory when copying non-empty contents fails.

Notes:
  - A valid empty builder returns the canonical empty string with Ok.
  - The caller owns a non-empty returned string and must release it with the
    builder's allocator.

make_string : func(src : cstring, allocator : ^Allocator) -> string

Constructs an owned string by copying the contents of a null-terminated C string.

Parameters:
  src       - Source null-terminated C string to copy. May be null.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string containing a copy of src. Returns an empty string
  if src is null, has zero length, or the allocation fails.

The returned string owns its buffer and must be released via free_string
using the same allocator.

make_string : func(src : cstring) -> string

Copies a null-terminated C string using context.allocator.

Parameters:
  src - Source null-terminated C string to copy. May be null.

Returns:
  A newly-allocated owned string, or an empty string when src is null,
  empty, or allocation fails. The result must be released via free_string
  using the allocator active in context when this function was called.

make_string : func(src : ^u8, length : i64, allocator : ^Allocator) -> string

Constructs an owned string by copying a raw byte range.

Parameters:
  src       - Pointer to the first byte to copy. May be null.
  length    - Number of bytes to copy.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string containing a copy of the requested bytes.
  Returns an empty string if src is null, length is non-positive, or the
  allocation fails.

The allocation reserves one additional byte and stores a trailing zero at
data[length]. The terminator is not included in the returned string's length.

The returned string owns its buffer and must be released via free_string
using the same allocator.

This overload selects allocator in its function-scoped Context and delegates
the allocation and copy to the compiler intrinsic. The caller's Context is
restored when this function returns.

make_string : func(length : i64) -> string

Allocates an uninitialized string using context.allocator.

Parameters:
  length - Number of bytes to allocate for the string's buffer.

Returns:
  A newly-allocated string of `length` bytes. The buffer's contents are
  undefined and must be initialized by the caller before use. One additional
  byte is allocated and initialized to zero at data[length]; the terminator
  is not included in length.

The returned string owns its buffer and must be released via free_string
using the allocator active in context when this function was called.

make_string : func(length : i64, allocator : ^Allocator) -> string

Allocates a string of the requested length with uninitialized contents.

Parameters:
  length    - Number of bytes to allocate for the string's buffer.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string of `length` bytes. The buffer's contents are
  undefined and must be initialized by the caller before use. One additional
  byte is allocated and initialized to zero at data[length]; the terminator
  is not included in length.

The returned string owns its buffer and must be released via free_string
using the same allocator.

make_string : func(slice : []u8, allocator : ^Allocator) -> string

Constructs an owned string by copying the contents of a byte slice.

Parameters:
  slice     - Source byte slice to copy.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string containing a copy of slice's bytes. Returns an
  empty string if slice.data is null, slice.length is non-positive, or the
  allocation fails.

The returned string owns its buffer and must be released via free_string
using the same allocator. The returned string does not alias the source
slice, so later changes to slice.data do not affect the returned string.

make_string : func(slice : []u8) -> string

Copies a byte slice using context.allocator.

Parameters:
  slice - Source byte slice to copy.

Returns:
  A newly-allocated owned string, or an empty string when slice is invalid,
  empty, or allocation fails. The result does not alias slice.data and must
  be released via free_string using the allocator active in context when
  this function was called.

free_string : func(str : ^string, allocator : ^Allocator) -> void

Frees the memory associated with the given string.

Parameters:
  str       - Pointer to the string to free. May be null, in which case the call is a no-op.
  allocator - Allocator used to release str.data. Must match the allocator that produced it.

On return, str.data is set to null and str.length is set to -1.

free_string : func(str : ^string) -> void

Frees an owned string using context.allocator.

Parameters:
  str - Pointer to the string to free. May be null.

The allocator active in context must match the allocator that produced
str.data. On return, str.data is null and str.length is -1.

split : func(str : ^string, delimeter : char) -> containers.ArrayList<string>

Splits a string into independently-owned strings.

Parameters:
  str       - Pointer to the string to split.
  delimeter - Delimiter byte to search for.
  The allocator active in context is used for both the returned ArrayList
  storage and every non-empty string element.

Returns:
  An containers.ArrayList<string> containing allocated copies of the spans between
  delimiters. Empty spans are preserved as empty strings. Returns an empty
  list when str is null, str.length is negative, a non-empty string has null
  data, context.allocator is null, or an allocation fails. A valid empty
  string produces one empty element regardless of whether its data pointer
  is null or points at a terminator.

The caller owns both levels of storage. Release each non-empty element with
free_string using the allocator active in context when split was called,
then call DeinitArrayList on the returned list.

to_bytes : func(self : ^string) -> []u8

Returns a byte-slice view over the string's contents.

Parameters:
  self - Pointer to the string to view.

Returns:
  A []u8 slice aliasing self.data with length self.length. No allocation
  or copy is performed. Use this when byte-level iteration is intended;
  plain string iteration yields char values.

make_cstring : func(value : string) -> cstring

Copies the string into a newly-allocated, null-terminated C string.

Parameters:
  value - String to copy.

Returns:
  A malloc-allocated cstring containing value's bytes followed by a null
  terminator. Returns null if value is non-empty with null data, if value
  has a negative length, or if allocation fails. The returned pointer must
  be released with free().

to_slice : func(self : ^string) -> []u8

Returns a byte-slice view over the string's contents.

Parameters:
  self - Pointer to the string to view.

Returns:
  A []u8 slice aliasing self.data with length self.length. No allocation
  or copy is performed; the slice remains valid only as long as self.data
  is live.

to_slice : func(self: ^string, len : i32) -> []u8

Returns a byte-slice view over the first `len` bytes of the string.

Parameters:
  self - Pointer to the string to view.
  len  - Maximum number of bytes to include in the returned slice.

Returns:
  A []u8 slice aliasing self.data. If `len` is greater than or equal to
  self.length, the full string is returned; otherwise the slice is
  truncated to `len` bytes. No allocation or copy is performed; the slice
  remains valid only as long as self.data is live.

clone : func(self : ^string, allocator : ^Allocator) -> string

Produces an independently-allocated copy of the string.

Parameters:
  self  - Pointer to the string to copy. May be null.
  alloc - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string containing a copy of self's bytes. Returns an
  empty string if self is null, self.data is null, self.length is
  non-positive, or the allocation fails.

The returned string owns its buffer and must be released via free_string
using the same allocator.

clone : func(self : ^string) -> string

Copies the string using context.allocator.

Returns:
  A newly-allocated owned copy, or an empty string when self is null,
  empty, or allocation fails. The result must be released via free_string
  using the allocator active in context when this function was called.

to_upper : func(self : ^string, allocator : ^Allocator) -> string

Copies the string and converts ASCII letters to uppercase.

Parameters:
  self      - Pointer to the source string. Left unchanged.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string with bytes `a` through `z` converted to `A`
  through `Z`. Returns an empty string when self is null, self.data is
  null, self.length is non-positive, or allocation fails.

This function performs ASCII case conversion only; it does not apply
Unicode case mappings. Non-ASCII UTF-8 sequences are copied byte-for-byte,
so `é` remains `é` and emoji remain unchanged. Valid UTF-8 input therefore
remains valid UTF-8. The returned string owns its buffer and must be
released via free_string using the same allocator.

to_upper : func(self : ^string) -> string

Copies the string and converts ASCII letters to uppercase using
context.allocator.

Returns:
  A newly-allocated owned string. This is ASCII-only; non-ASCII UTF-8
  sequences are copied unchanged and no Unicode case mapping is performed.
  The result must be released via free_string using the allocator that was
  active in context when this function was called.

to_lower : func(self : ^string, allocator : ^Allocator) -> string

Copies the string and converts ASCII letters to lowercase.

Parameters:
  self      - Pointer to the source string. Left unchanged.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string with bytes `A` through `Z` converted to `a`
  through `z`. Returns an empty string when self is null, self.data is
  null, self.length is non-positive, or allocation fails.

This function performs ASCII case conversion only; it does not apply
Unicode case mappings. Non-ASCII UTF-8 sequences are copied byte-for-byte,
so `É` remains `É` and emoji remain unchanged. Valid UTF-8 input therefore
remains valid UTF-8. The returned string owns its buffer and must be
released via free_string using the same allocator.

to_lower : func(self : ^string) -> string

Copies the string and converts ASCII letters to lowercase using
context.allocator.

Returns:
  A newly-allocated owned string. This is ASCII-only; non-ASCII UTF-8
  sequences are copied unchanged and no Unicode case mapping is performed.
  The result must be released via free_string using the allocator that was
  active in context when this function was called.

compare : func(self : string, other : string, ignore_case : bool = false) -> bool

Compares two strings, optionally ignoring ASCII letter case.

Parameters:
  self        - Pointer to the first string.
  other       - Second string value.
  ignore_case - When true, ASCII letters `A` through `Z` are treated as
                equivalent to `a` through `z`.

Returns:
  true when both strings have equal lengths and matching bytes; otherwise
  false. When ignore_case is true, matching is ASCII case-insensitive;
  non-ASCII UTF-8 bytes are still compared exactly. Valid zero-length strings
  compare equal regardless of whether their data pointer is null or points at
  a terminator. No allocation is performed.

are_equals : func(s1 : string, s2 : string) -> bool

compare : func(slice : []u8, other : string, ignore_case : bool = false) -> bool

Compares a byte slice with a string, optionally ignoring ASCII
letter case.

Parameters:
  slice       - Byte slice to compare. Left unchanged.
  other       - String value to compare against the slice.
  ignore_case - When true, ASCII letters `A` through `Z` are treated as
                equivalent to `a` through `z`.

Returns:
  true when the slice and string have equal lengths and matching bytes;
  otherwise false. When ignore_case is true, matching is ASCII
  case-insensitive; non-ASCII UTF-8 bytes are still compared exactly.
  No allocation is performed.

substring : func(self : ^string, start_index : i64, count : i64) -> string

Copies a byte range into a newly-allocated string.

Parameters:
  self     - Pointer to the string to slice.
  start_index - Zero-based byte offset where the substring begins.
  count    - Number of bytes to include.

Returns:
  A newly-allocated string containing a copy of the requested byte range.
  Returns an empty string when self is null, self.data is null,
  start_index/count are negative, count is zero, the requested range
  exceeds self.length, or allocation fails.

The returned string owns its buffer and must be released via free_string.

concat : func(self : ^string, s1 : string, allocator : ^Allocator ) -> string

Joins the string with another, producing a newly-allocated result.

Parameters:
  self      - Pointer to the leading string. Left unchanged.
  s1        - Trailing string to append after self. Left unchanged.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string containing self followed by s1.

The returned string owns its buffer and must be released via free_string
using the same allocator.

concat : func(self : ^string, s1 : cstring, allocator : ^Allocator ) -> string

Appends a null-terminated C string to this string.

Parameters:
  self      - Pointer to the leading string. Left unchanged.
  s1        - Null-terminated C string to append.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated owned string containing self followed by s1. The result
  must be released via free_string using the same allocator.

concat : func(self : ^string, s1 : string, s2 : string, allocator : ^Allocator) -> string

Joins the string with two others, producing a newly-allocated result.

Parameters:
  self      - Pointer to the leading string. Left unchanged.
  s1        - Second string, appended after self. Left unchanged.
  s2        - Third string, appended after s1. Left unchanged.
  allocator - Allocator used to provision the returned string's buffer.

Returns:
  A newly-allocated string containing self followed by s1 followed by s2.

The returned string owns its buffer and must be released via free_string
using the same allocator.

starts_with : func(self : ^string, c : char) -> bool

Reports whether the string's first byte matches the given character.

Parameters:
  self - Pointer to the string to test.
  c    - Character to compare against the first byte of self.

Returns:
  true if self's leading byte equals c; false otherwise.

starts_with : func(self : ^string, s1 : string ) -> bool

Reports whether the string begins with the given prefix.

Parameters:
  self - Pointer to the string to test.
  s1   - Candidate prefix to match against the start of self.

Returns:
  true if s1 is a prefix of self; false otherwise. Returns false when
  s1.length is greater than self.length. Equal-length strings match
  when their contents are identical.

get_hash : func(self : ^string) -> i64

Produces a 64-bit hash for a string key by hashing each byte in order.

Parameters:
  x : string - string value to hash. Null or empty strings hash to the
               initial seed value.

Returns:
  u64 - hash value suitable for Map slot selection.

Notes:
  - This is a DJB2-style byte hash chosen because the current integer
    literal parser cannot represent the standard 64-bit FNV offset literal.

utf8_is_valid_rune : func(value : rune) -> bool

utf8_decode : func(text : []u8, byte_offset : i64) -> Utf8DecodeResult

utf8_decode : func(text : string, byte_offset : i64) -> Utf8DecodeResult

utf8_encode : func(value : rune, output : []u8) -> [i64, Utf8Status]

utf8_next : func(text : []u8, byte_offset : i64) -> i64

utf8_next : func(text : string, byte_offset : i64) -> i64

utf8_previous : func(text : []u8, byte_offset : i64) -> i64

utf8_previous : func(text : string, byte_offset : i64) -> i64

utf8_count : func(text : []u8) -> i64

utf8_count : func(text : string) -> i64

utf8_is_valid : func(text : []u8) -> bool

utf8_is_valid : func(text : string) -> bool