Strings and StringBuilders

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

To be able to concatenate strings in a gas-efficient way, use a StringBuilder.

To use String literals directly, see: String literals.

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 like NFT or Jetton.

Usage example:

let fizz: StringBuilder = beginTailString();

beginStringFromBuilder

fun beginStringFromBuilder(b: StringBuilder): StringBuilder;

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

Usage example:

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

StringBuilder.append

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

Extension mutation function for the StringBuilder.

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.

Returns a new StringBuilder after concatinating it with a String s. Can be chained, unlike StringBuilder.append().

Usage example:

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

StringBuilder.toString

extends fun toString(self: StringBuilder): String;

Extension function for the StringBuilder.

Returns a built String from a StringBuilder.

Usage example:

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

StringBuilder.toCell

extends fun toCell(self: StringBuilder): Cell;

Extension function for the StringBuilder.

Returns an assembled Cell from a StringBuilder.

Usage example:

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

StringBuilder.toSlice

extends fun toSlice(self: StringBuilder): Slice;

Extension function for the StringBuilder.

Returns an assembled Cell as a Slice from a StringBuilder. 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.asSlice

extends fun asSlice(self: String): Slice;

Extension function for the String.

Returns a Slice from a String by trying to pack all of its bits into a continuous list of Cells, each referencing the next one and opening them all for future parsing.

Note, that there's no indication of how many bytes a particular character could take in the Slice or how deep the list of references is going to be, so use this function only if you know what you're doing.

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, but be careful as it's not always the case

String.asComment

extends fun asComment(self: String): Cell;

Extension function for the String.

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

extends fun fromBase64(self: String): Slice;

Extension function for the String.

Returns a Slice out of the decoded Base64 (opens in a new tab) String. 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).

Usage example:

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

Slice.asString

extends fun asString(self: Slice): String;

Extension function for the Slice.

Returns a String from a Slice by trying to load all of its bits without looking for its references, if any.

Note, that this function doesn't look at the references at all and is truncates its output to $1023$ bits, so use it only if you know what you're doing.

Usage example:

let s: String = "Keep your Slices close, but your Strings closer.";
let fizz: String = s;
let buzz: String = s.asSlice().asString();
 
fizz == buzz; // true, but be careful as it's not always the case

Slice.fromBase64

extends fun fromBase64(self: Slice): Slice;

Extension function for the Slice.

Returns a new Slice out of the decoded Base64 (opens in a new tab) Slice.

Note, that this function is limited and only takes the first $1023$ bits of data from the given Slice, without throwing an exception if the Slice has more data (i.e., when it has any references).

Usage example:

let s: Slice = "SSBhbSBHcm9vdC4=".asSlice();
let fizz: Slice = s.fromBase64();

Int.toString

extends fun toString(self: Int): String;

Extension function for the Int.

Returns a String from an Int value.

Usage example:

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

Int.toFloatString

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

Extension function for the Int.

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

More precisely, digits is an exponentiation parameter of $10^{-\mathrm{digits}}$ expression, which gives the represented fractional number when multiplied by the actual Int value. Parameter digits is required to be in the semi-closed interval: $0 <=$ 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

extends fun toCoinsString(self: Int): String;

Extension function for the Int.

Returns a String from an Int value using a fixed-point representation (opens in a new tab) of a fractional number. 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"

Address.toString

extends fun toString(self: Address): String;

Extension function for the Address.

Returns a String from an Address.

Usage example:

let community: Address = address("UQDpXLZKrkHsOuE_C1aS69C697wE568vTnqSeRfBXZfvmVOo");
let fizz: String = community.toString();