Skip to content

String

Overview

Cera has four string storage modes, all sharing the same CeraString binary layout ([capacity:4][length:4][data:N]):

DeclarationStorageCapacityBehavior
stringStack (CeraString)24 (default)Fixed, truncates on overflow
string<N>Stack (CeraString)NFixed, truncates on overflow
string?GC heapAuto-sizedGrowable, reallocates on overflow
string!GC heapAuto-sizedGrowable, non-null
string<N>?GC heapNFixed, truncates on overflow
string<N>!GC heapNFixed, non-null, truncates
string*Manual heap24 (default)Fixed, requires unsafe, manual lifetime
string<N>*Manual heapNFixed, requires unsafe, manual lifetime
string&Manual heap(non-null)Fixed, requires unsafe, manual lifetime

A runtime capacity of 0 marks an interned (read-only) string — all mutating operations are no-ops or produce a mutable copy.

Value Strings (string, string<N>)

Stack-allocated with fixed capacity. Plain string is equivalent to string<24> (32 bytes total: 8-byte header + 24 data).

string s = "Hello"; // string<24> on stack
string<64> big = "Lots of room"; // 64-byte capacity
s.Length; // 5
s.Capacity; // 24
big.Capacity; // 64

Appending beyond capacity silently truncates:

string<8> small = "Hello";
small += " World"; // truncated to 8 bytes
small.Length; // 8

GC Strings (string?, string!)

Heap-allocated via the garbage collector. Without explicit <N>, they are growable — capacity auto-sizes to content and grows on overflow using a tiered strategy (<8→8, <64→2×, ≥64→1.5×).

string? s = "Hello"; // auto-sized capacity (≥5)
s += " World! And more text that grows the buffer";
s.Length; // grows as needed — no truncation
string? nullable = null; // nullable, defaults to null
string! required = "Must exist"; // non-null, allocated even without initializer

With explicit <N>, GC strings have fixed capacity (same truncation as value strings):

string<32>? fixed = "Hello"; // fixed 32-byte capacity on GC heap
fixed.Capacity; // 32

Raw Pointer Strings (string*, string&)

Manually managed strings allocated with new* and freed with delete*. Require unsafe blocks. No GCHeader — just raw CeraString in heap memory.

unsafe {
string* p = new* string("Hello"); // 24-byte capacity (default)
string<64>* big = new* string<64>(); // 64-byte capacity
p.Length; // 5
p += " World"; // Append in-place
delete* p; // Manual cleanup required
delete* big;
}

string* is nullable, string& is non-null. Both have fixed capacity with truncation on overflow. All CeraString operations (.Length, .Capacity, .Append(), .Clear(), +=) work identically to value strings.

Properties

string s = "hello";
int len = s.Length; // 5
int cap = s.Capacity; // 24 (or N for string<N>)

Mutation Methods

Available on value strings and GC strings (not on const char* results from methods):

s.Append("text"); // Append in-place (grows for GC strings)
s.Clear(); // Reset length to 0
s += "text"; // Shorthand for Append

Indexing

int ch = s[0]; // 104 ('h') - returns character code
int bad = s[100]; // Returns -1 for out of bounds

Instance Methods

These return new strings (do not mutate the original):

s.SubString(start, len) // Extract substring
s.Trim() // Trim whitespace from both ends
s.TrimLeft() // Trim left whitespace
s.TrimRight() // Trim right whitespace
s.ToLower() // Convert to lowercase
s.ToUpper() // Convert to uppercase
s.StartsWith(prefix) // Returns 1 or 0
s.EndsWith(suffix) // Returns 1 or 0
s.Contains(substr) // Returns 1 or 0
s.IndexOf(substr) // Returns position or -1
s.IndexOf('x') // Returns position or -1 (char overload)
s.Replace(old, new) // Replace all occurrences
s.Replace('x', new) // Replace character (char overload)

Static Methods

String.Concat(a, b) // Concatenate two strings
String.FromInt(val) // Convert int64 to string
String.FromFloat(val) // Convert float64 to string
String.Join(delim, arr) // Join string array

Concatenation

string s = "Value: " + 42; // Implicit int conversion
string s = 3.14 + " is pi"; // Implicit float conversion

String Conversion

Any type with a string conversion operator (explicit string() or implicit string()) can be used in string interpolation, concatenation, and (string) casts. Primitives (int, float, bool, char) are converted automatically:

type Point(int x, int y)
{
explicit string() $"({this.x}, {this.y})";
}
Point p = Point(3, 4);
Console.WriteLine((string)p); // (3, 4)
Console.WriteLine($"Point is {p}"); // Point is (3, 4)

Interpolation

string msg = $"x={x}, pi={pi}"; // Variable interpolation
string expr = $"Sum: {x + 10}"; // Expression interpolation

Escape Sequences

"\n" // newline
"\t" // tab
"\r" // carriage return
"\\" // backslash
"\"" // double quote
"\0" // null
"\b" // backspace
"\f" // form feed

Comparison

Strings are compared by value with == and !=:

"hello" == "hello"; // true
"abc" < "abd"; // true (lexicographic)

Null Comparison (GC strings)

string? s = null;
if (s == null) { ... } // pointer comparison
s = "hello";
if (s == "hello") { ... } // value comparison