String
Overview
Cera has four string storage modes, all sharing the same CeraString binary layout ([capacity:4][length:4][data:N]):
| Declaration | Storage | Capacity | Behavior |
|---|---|---|---|
string | Stack (CeraString) | 24 (default) | Fixed, truncates on overflow |
string<N> | Stack (CeraString) | N | Fixed, truncates on overflow |
string? | GC heap | Auto-sized | Growable, reallocates on overflow |
string! | GC heap | Auto-sized | Growable, non-null |
string<N>? | GC heap | N | Fixed, truncates on overflow |
string<N>! | GC heap | N | Fixed, non-null, truncates |
string* | Manual heap | 24 (default) | Fixed, requires unsafe, manual lifetime |
string<N>* | Manual heap | N | Fixed, 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 stackstring<64> big = "Lots of room"; // 64-byte capacitys.Length; // 5s.Capacity; // 24big.Capacity; // 64Appending beyond capacity silently truncates:
string<8> small = "Hello";small += " World"; // truncated to 8 bytessmall.Length; // 8GC 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 nullstring! required = "Must exist"; // non-null, allocated even without initializerWith explicit <N>, GC strings have fixed capacity (same truncation as value strings):
string<32>? fixed = "Hello"; // fixed 32-byte capacity on GC heapfixed.Capacity; // 32Raw 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; // 5int 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 0s += "text"; // Shorthand for AppendIndexing
int ch = s[0]; // 104 ('h') - returns character codeint bad = s[100]; // Returns -1 for out of boundsInstance Methods
These return new strings (do not mutate the original):
s.SubString(start, len) // Extract substrings.Trim() // Trim whitespace from both endss.TrimLeft() // Trim left whitespaces.TrimRight() // Trim right whitespaces.ToLower() // Convert to lowercases.ToUpper() // Convert to uppercases.StartsWith(prefix) // Returns 1 or 0s.EndsWith(suffix) // Returns 1 or 0s.Contains(substr) // Returns 1 or 0s.IndexOf(substr) // Returns position or -1s.IndexOf('x') // Returns position or -1 (char overload)s.Replace(old, new) // Replace all occurrencess.Replace('x', new) // Replace character (char overload)Static Methods
String.Concat(a, b) // Concatenate two stringsString.FromInt(val) // Convert int64 to stringString.FromFloat(val) // Convert float64 to stringString.Join(delim, arr) // Join string arrayConcatenation
string s = "Value: " + 42; // Implicit int conversionstring s = 3.14 + " is pi"; // Implicit float conversionString 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 interpolationstring expr = $"Sum: {x + 10}"; // Expression interpolationEscape Sequences
"\n" // newline"\t" // tab"\r" // carriage return"\\" // backslash"\"" // double quote"\0" // null"\b" // backspace"\f" // form feedComparison
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 comparisons = "hello";if (s == "hello") { ... } // value comparison