base/Text

Utility functions for Text values.

A Text value represents human-readable text as a sequence of characters of type Char.

let text = "Hello!";
let size = text.size(); // 6
let iter = text.chars(); // iterator ('H', 'e', 'l', 'l', 'o', '!')
let concat = text # " 👋"; // "Hello! 👋"

The "mo:base/Text" module defines additional operations on Text values.

Import the module from the base library:

import Text "mo:base/Text";

Text values are represented as ropes of UTF-8 character sequences with O(1) concatenation.

Type Text

type Text = Prim.Types.Text

The type corresponding to primitive Text values.

let hello = "Hello!";
let emoji = "👋";
let concat = hello # " " # emoji; // "Hello! 👋"

Function fromChar

func fromChar(c : Char) : Text

Converts the given Char to a Text value.

let text = Text.fromChar('A'); // "A"

Function fromArray

func fromArray(a : [Char]) : Text

Converts the given [Char] to a Text value.

let text = Text.fromArray(['A', 'v', 'o', 'c', 'a', 'd', 'o']); // "Avocado"

Runtime	Space
O(a.size())	O(a.size())

Function fromVarArray

func fromVarArray(a : [var Char]) : Text

Converts the given [var Char] to a Text value.

let text = Text.fromVarArray([var 'E', 'g', 'g', 'p', 'l', 'a', 'n', 't']); // "Eggplant"

Runtime	Space
O(a.size())	O(a.size())

Function toIter

func toIter(t : Text) : Iter.Iter<Char>

Iterates over each Char value in the given Text.

Equivalent to calling the t.chars() method where t is a Text value.

import { print } "mo:base/Debug";

for (c in Text.toIter("abc")) {
  print(debug_show c);
}

Function toArray

func toArray(t : Text) : [Char]

Creates a new Array containing characters of the given Text.

Equivalent to Iter.toArray(t.chars()).

assert Text.toArray("Café") == ['C', 'a', 'f', 'é'];

Runtime	Space
O(t.size())	O(t.size())

Function toVarArray

func toVarArray(t : Text) : [var Char]

Creates a new mutable Array containing characters of the given Text.

Equivalent to Iter.toArrayMut(t.chars()).

assert Text.toVarArray("Café") == [var 'C', 'a', 'f', 'é'];

Runtime	Space
O(t.size())	O(t.size())

Function fromIter

func fromIter(cs : Iter.Iter<Char>) : Text

Creates a Text value from a Char iterator.

let text = Text.fromIter(['a', 'b', 'c'].vals()); // "abc"

Function fromList

func fromList(cs : List.List<Char>) : Text

Create a text from a character list. Example:

fromList(?('H', ?('e', ?('l', ?('l', ?('o', null))))));
// => "Hello"

Runtime	Space
O(size cs)	O(size cs)

Function toList

func toList(t : Text) : List.List<Char>

Create a character list from a text. Example:

toList("Hello");
// => ?('H', ?('e', ?('l', ?('l', ?('o', null)))))

Runtime	Space
O(t.size())	O(t.size())

Function size

func size(t : Text) : Nat

Returns the number of characters in the given Text.

Equivalent to calling t.size() where t is a Text value.

let size = Text.size("abc"); // 3

Function hash

func hash(t : Text) : Hash.Hash

Returns a hash obtained by using the djb2 algorithm (more details).

let hash = Text.hash("abc");

This algorithm is intended for use in data structures rather than as a cryptographic hash function.

Function concat

func concat(t1 : Text, t2 : Text) : Text

Returns t1 # t2, where # is the Text concatenation operator.

let a = "Hello";
let b = "There";
let together = a # b; // "HelloThere"
let withSpace = a # " " # b; // "Hello There"
let togetherAgain = Text.concat(a, b); // "HelloThere"

Function equal

func equal(t1 : Text, t2 : Text) : Bool

Returns t1 == t2.

Function notEqual

func notEqual(t1 : Text, t2 : Text) : Bool

Returns t1 != t2.

Function less

func less(t1 : Text, t2 : Text) : Bool

Returns t1 < t2.

Function lessOrEqual

func lessOrEqual(t1 : Text, t2 : Text) : Bool

Returns t1 <= t2.

Function greater

func greater(t1 : Text, t2 : Text) : Bool

Returns t1 > t2.

Function greaterOrEqual

func greaterOrEqual(t1 : Text, t2 : Text) : Bool

Returns t1 >= t2.

Function compare

func compare(t1 : Text, t2 : Text) : {#less; #equal; #greater}

Compares t1 and t2 lexicographically.

import { print } "mo:base/Debug";

print(debug_show Text.compare("abc", "abc")); // #equal
print(debug_show Text.compare("abc", "def")); // #less
print(debug_show Text.compare("abc", "ABC")); // #greater

Function join

func join(sep : Text, ts : Iter.Iter<Text>) : Text

Join an iterator of Text values with a given delimiter.

let joined = Text.join(", ", ["a", "b", "c"].vals()); // "a, b, c"

Function map

func map(t : Text, f : Char -> Char) : Text

Applies a function to each character in a Text value, returning the concatenated Char results.

// Replace all occurrences of '?' with '!'
let result = Text.map("Motoko?", func(c) {
  if (c == '?') '!'
  else c
});

Function translate

func translate(t : Text, f : Char -> Text) : Text

Returns the result of applying f to each character in ts, concatenating the intermediate text values.

// Replace all occurrences of '?' with "!!"
let result = Text.translate("Motoko?", func(c) {
  if (c == '?') "!!"
  else Text.fromChar(c)
}); // "Motoko!!"

Type Pattern

type Pattern = {#char : Char; #text : Text; #predicate : (Char -> Bool)}

A pattern p describes a sequence of characters. A pattern has one of the following forms:

• #char c matches the single character sequence, c.
• #text t matches multi-character text sequence t.
• #predicate p matches any single character sequence c satisfying predicate p(c).

A match for p is any sequence of characters matching the pattern p.

let charPattern = #char 'A';
let textPattern = #text "phrase";
let predicatePattern : Text.Pattern = #predicate (func(c) { c == 'A' or c == 'B' }); // matches "A" or "B"

Function split

func split(t : Text, p : Pattern) : Iter.Iter<Text>

Splits the input Text with the specified Pattern.

Two fields are separated by exactly one match.

let words = Text.split("This is a sentence.", #char ' ');
Text.join("|", words) // "This|is|a|sentence."

Function tokens

func tokens(t : Text, p : Pattern) : Iter.Iter<Text>

Returns a sequence of tokens from the input Text delimited by the specified Pattern, derived from start to end. A "token" is a non-empty maximal subsequence of t not containing a match for pattern p. Two tokens may be separated by one or more matches of p.

let tokens = Text.tokens("this needs\n an   example", #predicate (func(c) { c == ' ' or c == '\n' }));
Text.join("|", tokens) // "this|needs|an|example"

Function contains

func contains(t : Text, p : Pattern) : Bool

Returns true if the input Text contains a match for the specified Pattern.

Text.contains("Motoko", #text "oto") // true

Function startsWith

func startsWith(t : Text, p : Pattern) : Bool

Returns true if the input Text starts with a prefix matching the specified Pattern.

Text.startsWith("Motoko", #text "Mo") // true

Function endsWith

func endsWith(t : Text, p : Pattern) : Bool

Returns true if the input Text ends with a suffix matching the specified Pattern.

Text.endsWith("Motoko", #char 'o') // true

Function replace

func replace(t : Text, p : Pattern, r : Text) : Text

Returns the input text t with all matches of pattern p replaced by text r.

let result = Text.replace("abcabc", #char 'a', "A"); // "AbcAbc"

Function stripStart

func stripStart(t : Text, p : Pattern) : ?Text

Strips one occurrence of the given Pattern from the beginning of the input Text. If you want to remove multiple instances of the pattern, use Text.trimStart() instead.

// Try to strip a nonexistent character
let none = Text.stripStart("abc", #char '-'); // null
// Strip just one '-'
let one = Text.stripStart("--abc", #char '-'); // ?"-abc"

Function stripEnd

func stripEnd(t : Text, p : Pattern) : ?Text

Strips one occurrence of the given Pattern from the end of the input Text. If you want to remove multiple instances of the pattern, use Text.trimEnd() instead.

// Try to strip a nonexistent character
let none = Text.stripEnd("xyz", #char '-'); // null
// Strip just one '-'
let one = Text.stripEnd("xyz--", #char '-'); // ?"xyz-"

Function trimStart

func trimStart(t : Text, p : Pattern) : Text

Trims the given Pattern from the start of the input Text. If you only want to remove a single instance of the pattern, use Text.stripStart() instead.

let trimmed = Text.trimStart("---abc", #char '-'); // "abc"

Function trimEnd

func trimEnd(t : Text, p : Pattern) : Text

Trims the given Pattern from the end of the input Text. If you only want to remove a single instance of the pattern, use Text.stripEnd() instead.

let trimmed = Text.trimEnd("xyz---", #char '-'); // "xyz"

Function trim

func trim(t : Text, p : Pattern) : Text

Trims the given Pattern from both the start and end of the input Text.

let trimmed = Text.trim("---abcxyz---", #char '-'); // "abcxyz"

Function compareWith

func compareWith(t1 : Text, t2 : Text, cmp : (Char, Char) -> {#less; #equal; #greater}) : {#less; #equal; #greater}

Compares t1 and t2 using the provided character-wise comparison function.

import Char "mo:base/Char";

Text.compareWith("abc", "ABC", func(c1, c2) { Char.compare(c1, c2) }) // #greater

Function encodeUtf8

func encodeUtf8(_ : Text) : Blob

Returns a UTF-8 encoded Blob from the given Text.

let blob = Text.encodeUtf8("Hello");

Function decodeUtf8

func decodeUtf8(_ : Blob) : ?Text

Tries to decode the given Blob as UTF-8. Returns null if the blob is not valid UTF-8.

let text = Text.decodeUtf8("\48\65\6C\6C\6F"); // ?"Hello"

Function toLowercase

func toLowercase(_ : Text) : Text

Returns the text argument in lowercase.

Compliance

Unicode compliant only when compiled, not interpreted.

let text = Text.toLowercase("Good Day"); // ?"good day"

Function toUppercase

func toUppercase(_ : Text) : Text

Returns the text argument in uppercase. Unicode compliant.

Compliance

Unicode compliant only when compiled, not interpreted.

let text = Text.toUppercase("Good Day"); // ?"GOOD DAY"