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 sequencet
.#predicate p
matches any single character sequencec
satisfying predicatep(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";