Strings and StringBuilders

Strings are immutable sequences of characters, which means that once a String is created, it cannot be changed. Strings are useful for storing text, so they can be converted to a Cell type to be used as message bodies.

To concatenate strings use a StringBuilder.

To use String literals directly, see: String literals.

Note

Strings on-chain are represented as slices, which are expensive for handling Unicode strings and quite costly even for ASCII ones. Prefer not to manipulate strings on-chain.

beginString

fun beginString(): StringBuilder;

Creates and returns an empty StringBuilder.

Usage example:

let fizz: StringBuilder = beginString();

beginComment

fun beginComment(): StringBuilder;

Creates and returns an empty StringBuilder for building a comment string, which prefixes the resulting String with four null bytes. This format is used for passing text comments as message bodies.

Usage example:

let fizz: StringBuilder = beginComment();

beginTailString

fun beginTailString(): StringBuilder;

Creates and returns an empty StringBuilder for building a tail string, which prefixes the resulting String with a single null byte. This format is used in various standards such as NFT or Jetton.

Usage example:

let fizz: StringBuilder = beginTailString();

beginStringFromBuilder

fun beginStringFromBuilder(b: StringBuilder): StringBuilder;

Creates and returns a new StringBuilder from an existing StringBuilder b. Useful when you need to serialize an existing String to a Cell along with other data.

Usage example:

let fizz: StringBuilder = beginStringFromBuilder(beginString());

StringBuilder

StringBuilder.append

extends mutates fun append(self: StringBuilder, s: String);

Extension mutation function for the StringBuilder type.

Appends a String s to the StringBuilder.

Usage example:

let fizz: StringBuilder = beginString();
fizz.append("oh");
fizz.append("my");
fizz.append("Tact!");

StringBuilder.concat

extends fun concat(self: StringBuilder, s: String): StringBuilder;

Extension function for the StringBuilder type.

Returns a new StringBuilder after concatenating it with a String s. It can be chained, unlike StringBuilder.append().

Usage example:

let fizz: StringBuilder = beginString()
    .concat("oh")
    .concat("my")
    .concat("Tact!");

StringBuilder.toString

Gas-expensive

extends fun toString(self: StringBuilder): String;

Extension function for the StringBuilder type.

Returns a built String from a StringBuilder.

Usage example:

let fizz: StringBuilder = beginString();
let buzz: String = fizz.toString();

StringBuilder.toCell

Gas-expensive

extends fun toCell(self: StringBuilder): Cell;

Extension function for the StringBuilder type.

Returns an assembled Cell from a StringBuilder.

Usage example:

let fizz: StringBuilder = beginString();
let buzz: Cell = fizz.toCell();

StringBuilder.toSlice

Gas-expensive

extends fun toSlice(self: StringBuilder): Slice;

Extension function for the StringBuilder type.

Returns an assembled Cell as a Slice from a StringBuilder. An alias to self.toCell().asSlice().

Usage example:

let s: StringBuilder = beginString();
let fizz: Slice = s.toSlice();
let buzz: Slice = s.toCell().asSlice();

fizz == buzz; // true

String

String.hashData

Available since Tact 1.6

extends fun hashData(self: String): Int;

Extension function for the String type.

Calculates and returns an Int value of the SHA-256 hash of the data bits from the given String, which should have a number of bits divisible by 8.

Unlike sha256(), this function is gas-efficient and only hashes up to 127 bytes of the given string. Using longer strings will cause collisions if their first 127 bytes are the same.

Attempts to specify a String with a number of bits not divisible by 8 throw an exception with exit code 9: Cell underflow.

Usage example:

let roll: Int = "Never gonna give you up!".hashData(); // just the hash of the data

String.asSlice

extends fun asSlice(self: String): Slice;

Extension function for the String type.

Casts the String back to the underlying Slice and returns it. The inverse of Slice.asString().

Usage example:

let s: String = "It's alive! It's alive!!!";
let fizz: Slice = s.asSlice();
let buzz: Slice = s.asSlice().asString().asSlice();

fizz == buzz; // true

Note

See how the String.asSlice function can be used in practice: How to convert a String to an Int.

String.asComment

Gas-expensive

extends fun asComment(self: String): Cell;

Extension function for the String type.

Returns a Cell from a String by prefixing the latter with four null bytes. This format is used for passing text comments as message bodies.

Usage example:

let s: String = "When life gives you lemons, call them 'yellow oranges' and sell them for double the price.";
let fizz: Cell = s.asComment();

let b: StringBuilder = beginComment();
b.append(s);
let buzz: Cell = b.toCell();

fizz == buzz; // true

String.fromBase64

Gas-expensive

extends fun fromBase64(self: String): Slice;

Extension function for the String type.

Returns a Slice from the decoded Base64 String. An alias to self.asSlice().fromBase64().

Note that this function is limited and only takes the first 1023 bits of data from the given String, without throwing an exception when the String is larger (i.e., contains more than 1023 bits of data).

If the given String contains characters not from the Base64 set, an exception with exit code 134 will be thrown: Invalid argument.

Usage example:

let s: String = "SGVyZSdzIEpvaG5ueSE=";
let fizz: Slice = s.fromBase64();
let buzz: Slice = s.asSlice().fromBase64();

fizz == buzz; // true

Int.toString

Gas-expensive

extends fun toString(self: Int): String;

Extension function for the Int type.

Returns a String from an Int value.

Usage example:

let fizz: String = (84 - 42).toString();

Int.toFloatString

Gas-expensive

extends fun toFloatString(self: Int, digits: Int): String;

Extension function for the Int type.

Returns a String from an Int value using a fixed-point representation of a fractional number, where self is the significant part of the number and digits is the number of digits in the fractional part.

More precisely, digits is an exponentiation parameter of the expression $10^{-\mathrm{digits}}$, which gives the represented fractional number when multiplied by the actual Int value. Parameter digits is required to be in the closed interval: $0 < \mathrm{digits} < 78$. Otherwise, an exception with exit code 134 will be thrown: Invalid argument.

Usage example:

let fizz: String = (42).toFloatString(9); // "0.000000042"

Int.toCoinsString

Gas-expensive

extends fun toCoinsString(self: Int): String;

Extension function for the Int type.

Returns a String from an Int value using a fixed-point representation of a fractional number. An alias to self.toFloatString(9).

This is used to represent nanoToncoin Int values using strings.

Usage example:

let nanotons: Int = 42;
let fizz: String = nanotons.toCoinsString();
let buzz: String = nanotons.toFloatString(9);

fizz == buzz; // true, both store "0.000000042"