fmt

Module for string parsing and formatting.

This module provides a universal format function for creating formatted strings. It accepts up to 5 typed arguments.

Supported placeholders:

• {}: default formatting
• {:x}: integer formatted as hexadecimal without 0x
• {:ton}: integer nanotons formatted as <value> TON

Format rules and edge cases:

• Escape literal braces with {{ and }}.
• Extra arguments are ignored.
• Missing arguments leave placeholders unchanged in output ({}, {:x}, {:ton}).
• Invalid format strings (unknown modifier, unsupported placeholder, unmatched braces) fail at runtime with a parser error that includes a byte offset.
• For non-int arguments, {:x} and {:ton} fall back to default formatting.
• {:ton} uses f64 internally, so very large values can lose precision.

Examples:

// Simple string substitution
val greeting = format("Hello, {}!", "Tolk");

// Formatting numbers
val hex = format("Value in hex: 0x{:x}", 255); // "Value in hex: 0xff"

// Formatting TON amounts
val balance = format("Balance: {:ton}", 500_000_000); // "Balance: 0.5 TON"

// Escaping braces
val escaped = format("Use {{}} to print braces", 0); // "Use {} to print braces"

// Missing argument keeps placeholder as-is
val partial = format("{} {}", "left"); // "left {}"

// Multiple arguments
val info = format("User {} has {} items worth {:ton}", "Alice", 5, 1_000_000_000);

// Parse an integer from a string
val num = parseInt("42");

Definitions

format

fun format<T1 = void, T2 = void, T3 = void, T4 = void, T5 = void>(
    fmt: string,
    arg1: T1,
    arg2: T2,
    arg3: T3,
    arg4: T4,
    arg5: T5,
): string

Formats a string with up to 5 arguments.

Uses the module-level format rules, including escaping ({{/}}), mismatch behavior, and runtime parser errors for invalid format strings.

Example:

val a = format("Hello {}", "world");
val b = format("{} + {} = {}", 2, 3, 5);
val c = format("hello");

Non-int fallback examples:

format("{:x}", "abc");   // "abc"
format("{:ton}", true);  // "true"

parseInt

fun parseInt(x: string): int

Parse a decimal string into an int value.

Leading and trailing whitespace is ignored before parsing. After trimming, accepts optional leading - sign followed by decimal digits. Invalid input (non-numeric characters, empty string, whitespace-only string) fails with an error.

Example:

val n = parseInt("12345");
val negative = parseInt("-42");
val withWhitespace = parseInt(" 42 ");

parseAddress

fun parseAddress(addr: string): address

Convert a string representation of address to an internal address value.

Accepted forms include raw addresses (0:...) and user-friendly TON addresses (base64/base64url with flags). Inputs copied from CLI output like <address> (<name>) are also accepted; the symbolic suffix is ignored. The returned value is normalized as an internal address; rendered formatting may differ from input flags, while representing the same account. Invalid input fails with an error like Failed to convert address from <input>.

Example:

val address = parseAddress("kQCPFJYFqhowz0BRAfqNPdLOC1_Rlupki_0BezWU6rHk5lbt");

parseCellFromHex

fun parseCellFromHex(cellHex: string): cell

Decode a root cell from hex-encoded BOC bytes.

cellHex must be a valid BOC serialized as hex. Invalid or malformed input (including non-BOC payloads) fails with an error like Failed to decode cell hex <input>.