core/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();
assert size == 6;
let iter = text.chars();
assert iter.next() == ?'H';
assert iter.next() == ?'e';
assert iter.next() == ?'l';
assert iter.next() == ?'l';
assert iter.next() == ?'o';
assert iter.next() == ?'!';
assert iter.next() == null;
let concat = text # " 👋";
assert concat == "Hello! 👋";

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

Import the module from the core library:

import Text "mo:core/Text";

Note: 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;
assert concat == "Hello! 👋";

Function fromChar

func fromChar(c : Char) : Text

Converts the given Char to a Text value.

let text = Text.fromChar('A');
assert text == "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']);
assert text == "Avocado";

Runtime: O(a.size()) Space: 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']);
assert text == "Eggplant";

Runtime: O(a.size()) Space: 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.

let chars = Text.toIter("abc");
assert chars.next() == ?'a';
assert chars.next() == ?'b';
assert chars.next() == ?'c';
assert chars.next() == null;

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: O(t.size()) Space: 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()).

import VarArray "mo:core/VarArray";
import Char "mo:core/Char";

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

Runtime: O(t.size()) Space: 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'].values());
assert text == "abc";

Function isEmpty

func isEmpty(t : Text) : Bool

Returns whether the given Text is empty (has a size of zero).

let text1 = "";
let text2 = "example";
assert Text.isEmpty(text1);
assert not Text.isEmpty(text2);

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");
assert size == 3;

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;
assert together == "HelloThere";
let withSpace = a # " " # b;
assert withSpace == "Hello There";
let togetherAgain = Text.concat(a, b);
assert togetherAgain == "HelloThere";

Function equal

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

Returns true if two text values are equal.

import Text "mo:core/Text";

assert Text.equal("hello", "hello");
assert not Text.equal("hello", "world");

Function notEqual

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

Returns true if two text values are not equal.

import Text "mo:core/Text";

assert Text.notEqual("hello", "world");
assert not Text.notEqual("hello", "hello");

Function less

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

Returns true if the first text value is lexicographically less than the second.

import Text "mo:core/Text";

assert Text.less("apple", "banana");
assert not Text.less("banana", "apple");

Function lessOrEqual

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

Returns true if the first text value is lexicographically less than or equal to the second.

import Text "mo:core/Text";

assert Text.lessOrEqual("apple", "banana");
assert Text.lessOrEqual("apple", "apple");
assert not Text.lessOrEqual("banana", "apple");

Function greater

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

Returns true if the first text value is lexicographically greater than the second.

import Text "mo:core/Text";

assert Text.greater("banana", "apple");
assert not Text.greater("apple", "banana");

Function greaterOrEqual

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

Returns true if the first text value is lexicographically greater than or equal to the second.

import Text "mo:core/Text";

assert Text.greaterOrEqual("banana", "apple");
assert Text.greaterOrEqual("apple", "apple");
assert not Text.greaterOrEqual("apple", "banana");

Function compare

func compare(t1 : Text, t2 : Text) : Order.Order

Compares t1 and t2 lexicographically.

assert Text.compare("abc", "abc") == #equal;
assert Text.compare("abc", "def") == #less;
assert 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"].values());
assert joined == "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
});
assert result == "Motoko!";

Function flatMap

func flatMap(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.flatMap("Motoko?", func(c) {
  if (c == '?') "!!"
  else Text.fromChar(c)
});
assert result == "Motoko!!";

Type Pattern

type Pattern = Types.Pattern

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' });
assert Text.contains("A", predicatePattern);
assert Text.contains("B", predicatePattern);

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 ' ');
assert 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' }));
assert 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.

assert Text.contains("Motoko", #text "oto");
assert not Text.contains("Motoko", #text "xyz");

Function startsWith

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

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

assert Text.startsWith("Motoko", #text "Mo");

Function endsWith

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

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

assert Text.endsWith("Motoko", #char 'o');

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");
assert result == "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 '-');
assert none == null;
// Strip just one '-'
let one = Text.stripStart("--abc", #char '-');
assert one == ?"-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 '-');
assert none == null;
// Strip just one '-'
let one = Text.stripEnd("xyz--", #char '-');
assert one == ?"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 '-');
assert trimmed == "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 '-');
assert trimmed == "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 '-');
assert trimmed == "abcxyz";

Function compareWith

func compareWith(t1 : Text, t2 : Text, cmp : (Char, Char) -> Order.Order) : Order.Order

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

import Char "mo:core/Char";

assert 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");
assert blob == "\48\65\6C\6C\6F";

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");
assert text == ?"Hello";

Function toLower

func toLower(_ : Text) : Text

Returns the text argument in lowercase. WARNING: Unicode compliant only when compiled, not interpreted.

let text = Text.toLower("Good Day");
assert text == "good day";

Function toUpper

func toUpper(_ : Text) : Text

Returns the text argument in uppercase. Unicode compliant. WARNING: Unicode compliant only when compiled, not interpreted.

let text = Text.toUpper("Good Day");
assert text == "GOOD DAY";

Function toText

func toText(t : Text) : Text

Returns the given text value unchanged. This function is provided for consistency with other modules.

assert Text.toText("Hello") == "Hello";