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! 👋";

public let fromChar : (c : Char) -> Text

Converts the given Char to a Text value.

motoko include=import
let text = Text.fromChar('A');
assert text == "A";

public func fromArray(a : [Char]) : Text

Converts the given [Char] to a Text value.

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

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

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

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

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

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

public 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.

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

public func toArray(t : Text) : [Char]

Creates a new Array containing characters of the given Text.

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

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

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

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

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

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

motoko include=import
import VarArray "mo:base/VarArray";
import Char "mo:base/Char";

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

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

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

Creates a Text value from a Char iterator.

motoko include=import
let text = Text.fromIter(['a', 'b', 'c'].values());
assert text == "abc";

public func isEmpty(t : Text) : Bool

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

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

public 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.

motoko include=import
let size = Text.size("abc");
assert size == 3;

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

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

motoko include=import
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";

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

Returns true if two text values are equal.

import Text "mo:base/Text";

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

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

Returns true if two text values are not equal.

import Text "mo:base/Text";

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

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

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

import Text "mo:base/Text";

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

public 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:base/Text";

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

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

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

import Text "mo:base/Text";

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

public 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:base/Text";

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

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

Compares t1 and t2 lexicographically.

motoko include=import
assert Text.compare("abc", "abc") == #equal;
assert Text.compare("abc", "def") == #less;
assert Text.compare("abc", "ABC") == #greater;

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

Join an iterator of Text values with a given delimiter.

motoko include=import
let joined = Text.join(", ", ["a", "b", "c"].values());
assert joined == "a, b, c";

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

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

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

public func flatMap(t : Text, f : Char -> Text) : Text

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

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

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.

motoko include=import
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);

public 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.

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

public 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.

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

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

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

motoko include=import
assert Text.contains("Motoko", #text "oto");
assert not Text.contains("Motoko", #text "xyz");

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

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

motoko include=import
assert Text.startsWith("Motoko", #text "Mo");

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

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

motoko include=import
assert Text.endsWith("Motoko", #char 'o');

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

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

motoko include=import
let result = Text.replace("abcabc", #char 'a', "A");
assert result == "AbcAbc";

public 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.

motoko include=import
// 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";

public 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.

motoko include=import
// 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-";

public 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.

motoko include=import
let trimmed = Text.trimStart("---abc", #char '-');
assert trimmed == "abc";

public 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.

motoko include=import
let trimmed = Text.trimEnd("xyz---", #char '-');
assert trimmed == "xyz";

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

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

motoko include=import
let trimmed = Text.trim("---abcxyz---", #char '-');
assert trimmed == "abcxyz";

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

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

motoko include=import
import Char "mo:base/Char";

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

public let encodeUtf8 : Text -> Blob

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

motoko include=import
let blob = Text.encodeUtf8("Hello");
assert blob == "\48\65\6C\6C\6F";

public let decodeUtf8 : Blob -> ?Text

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

motoko include=import
let text = Text.decodeUtf8("\48\65\6C\6C\6F");
assert text == ?"Hello";

public let toLower : Text -> Text

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

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

public let toUpper : Text -> Text

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

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

public func toText(t : Text) : Text

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

motoko include=import
assert Text.toText("Hello") == "Hello";