v0.29.0—Sharper bug analysis, reliable resource cleanup, and stronger test and CI checks.See what's new

Documentation

String Operations

Calor string operations use the same prefix notation as other expressions and emit the corresponding .NET operations.

Core Operations

OperationSyntaxC# equivalent
Length(len s)s.Length
Case(upper s), (lower s)s.ToUpper(), s.ToLower()
Trim(trim s)s.Trim()
Search(contains s sub), (starts s prefix), (ends s suffix)Matching string methods
Index(indexof s sub)s.IndexOf(sub)
Index from(indexof s sub start), (indexof s sub start count)s.IndexOf(sub, start), s.IndexOf(sub, start, count)
Slice(substr s start len)s.Substring(start, len)
Replace(replace s old new)s.Replace(old, new)
Concatenate(concat a b)a + b
Equality(equals a b)a.Equals(b)
Calor
§B{length:i32} (len "hello")
§B{found:bool} (contains "hello world" "world")
§B{sub:str} (substr "hello" 1 3)

Operand counts

Every built-in operation checks its operand count. Too many or too few operands is error Calor0110, which names the allowed count. Before 0.27, extra operands to contains, starts, ends, equals, indexof and str were accepted and silently dropped, so (indexof s "@" 3) compiled to s.IndexOf("@"). Comparison operators (==, !=, <, <=, >, >=) and ** take exactly two operands; (< a b c) is Calor0110 rather than (a < b) < c.

Comparison Modes

contains, starts, ends, indexof, and equals accept an optional mode:

Mode.NET comparison
:ordinalStringComparison.Ordinal
:ignore-caseStringComparison.OrdinalIgnoreCase
:invariantStringComparison.InvariantCulture
:invariant-ignore-caseStringComparison.InvariantCultureIgnoreCase

Omitting a mode is not uniform in .NET. contains and instance equals are ordinal, while starts, ends, and indexof use the current culture. Specify :ordinal when culture-independent runtime behavior is required.

Verification boundary

The verifier refuses non-ordinal comparison modes. It also refuses bare starts, ends, and indexof, because those overloads are culture-sensitive. Those obligations are unsupported, and their runtime checks remain.

Even ordinal string obligations cannot produce an elision-authorizing proof in 0.13.2. Z3 strings are null-free and measure UTF-8 units, while .NET strings are nullable references whose Length counts UTF-16 code units. Any otherwise modeled proof that depends on the Z3 string sort is therefore demoted to assumed, which does not authorize proof-based guard removal. Checks still require an enabled contract mode and supported lowering. See verification guarantees.

Regex, Character, and StringBuilder Operations

  • Regex: regex-test, regex-match, regex-replace, regex-split
  • Character access and classification: char-at, char-code, char-from-code, is-letter, is-digit, is-whitespace, is-upper, is-lower, char-upper, char-lower
  • StringBuilder: sb-new, sb-append, sb-appendline, sb-insert, sb-remove, sb-clear, sb-tostring, sb-length

Backslashes in regex patterns must be escaped in Calor strings, so regex \d is written as "\\d".

Interpolated Strings

A ${...} hole inside a string literal is an interpolation hole. The hole holds a Calor expression, optionally followed by an alignment (,10) and a format specifier (:F2), as in C#. The compiler emits a C# interpolated string ($"..."), so formatting uses the same .NET rules, including the current culture.

Calor
§M{m001:Receipt}
  §F{f001:Line:pub} (str:item, f64:amount) -> str
    §E{}
    §R "${item,-8}|${amount,10:F2}|${(* amount 2):F1}"

  §F{f002:Main:pub} () -> void
    §E{cw}
    §P §C{Line} §A "coffee" §A 3.5 §/C

Under the invariant or en-US culture this prints coffee | 3.50|7.0. Under de-DE it prints coffee | 3,50|7,0, exactly as the same C# would.

To write the characters ${ as text, escape the dollar sign: "\${x}" is the five characters ${x}.

Holes are checked like other expressions

Names in a hole are bound, and calls in a hole are effect-checked. An undefined name is reported at the hole's own line and column. A call written in C# form, such as ${Console.ReadLine()}, is analyzed as an ordinary call when its target is a dotted name and each argument is a literal, a name or a Calor expression. This function must declare cr (console read). With §E{} it fails with Calor0410, the "undeclared effect" error:

Calor
§M{m001:Greeting}
  §F{f001:Greet:pub} () -> str
    §E{cr}
    §R "hello ${Console.ReadLine()}"

A hole that is not in that form, for example a call with named arguments, stays raw C#. Its effects are then assumed, and the compiler says so with warning Calor0419.

Converting C# interpolated strings

In C#, the type an interpolated string converts to (its target type) can change which overload runs. calor convert keeps that choice:

C# targetConversion
string, object, or a return of eitherNative Calor string with ${...} holes. Format specifiers, alignment, culture and left-to-right hole order are kept.
FormattableString or IFormattable, with at least one holeNative, wrapped in an explicit cast such as (cast global::System.FormattableString "x=${x}"). The cast keeps the overload C# selected, for example Kind(FormattableString) over Kind(object).
An [InterpolatedStringHandler] parameter: custom logging and assertion APIs, and .NET overloads such as StringBuilder.Append($"...") and string.Create(provider, $"...")Not representable. The enclosing statement (as §RAW) or member (as §CSHARP) is kept as C# interop, so the call still builds its handler, and the report counts it as string-interpolation-handler. With fallback disabled (--no-fallback) the conversion fails and names that feature instead.

A FormattableString target with no holes, such as FormattableString.Invariant($"text"), has no Calor form either, so its statement is kept as C#.

Holes convert natively when they are names, string, character, bool and int literals, double literals with a fractional part, dotted member access (order.Total), operators, nameof, typeof, or calls with a dotted target and positional arguments (Math.Max(a, b)). Any other hole, for example {items[i]}, {customer?.Name} or {value.GetType().Name}, keeps its original C# text as §CS{...} inside the hole. The conversion report counts it as interop, and its effects are assumed (Calor0419). A call argument that is null or a member of something other than a name (typeof(T).Name) also keeps the hole as C#. A verbatim or raw interpolated string ($@"...", $"""...""") whose format clause contains a backslash keeps its whole statement as C#.

For example, this C# selects Kind(FormattableString), and so does the converted program:

C#
public static string Kind(FormattableString f) => "fs:" + f.Format;
public static string Kind(object o) => "object:" + o;
public static string Run(int x) => Kind($"k={x}");   // "fs:k={0}"

calor feature-check string-interpolation reports Partial because of the handler row. Interpolation is converted using the C# semantic model of the single file being converted. If a target type cannot be resolved there, for example a method from an assembly the converter was not given, the literal converts as a string-target literal and C# applies target typing again when the generated code is compiled.