Text
Strings and the operations over them — measuring, comparing, searching, slicing, changing case,
trimming, splitting and joining, padding, validating against character sets, formatting numbers, hashing,
and URL encoding. Text values are the native Text type, which also groups these functions;
every one is reactive, so a derived string recomputes whenever the values it reads change. Predicates such
as Text.Contains return a
Logic.Maybe, and the character-set constants pair with
Text.AllowChars to sanitise input.
Contents
Types
Constants
Functions
- Text.AllowChars
- Text.Append
- Text.AppendOptional
- Text.CharAt
- Text.Contains
- Text.ContainsOnly
- Text.Emit
- Text.Empty
- Text.Encode.Url
- Text.EndsWith
- Text.Equal
- Text.FormatNumber
- Text.Gather
- Text.GatherJoin
- Text.GetBetween
- Text.GetEverythingAfter
- Text.GetEverythingBefore
- Text.IndexOf
- Text.Interpolate
- Text.IsLower
- Text.IsWhitespace
- Text.Join
- Text.Length
- Text.Lower
- Text.Matches
- Text.NotEmpty
- Text.NotEqual
- Text.Option
- Text.PadLeft
- Text.RemoveChars
- Text.RemoveFromEnd
- Text.RemoveFromStart
- Text.Replace
- Text.ReplaceAll
- Text.Select
- Text.Sha1
- Text.Split
- Text.Start
- Text.StartsWith
- Text.Substring
- Text.Trim
- Text.TrimEnd
- Text.TrimStart
- Text.Upper
- Text.UpperFirst
Types
Text
A string of characters: the built-in text type, which also groups the text functions and character-set constants.
Definition
TYPE Text
NATIVE js "string"
NATIVE dart "String"
NATIVE swift "String"
NATIVE go "string"Example
LET Text greeting = "Hello, world"Constants
Text.Characters.Alpha
The ASCII letters, upper and lower case.
Definition
LET Alpha = "ABC…XYZabc…xyz"Text.Characters.Alphanumeric
The ASCII letters and digits.
Definition
LET Alphanumeric = "ABC…XYZabc…xyz0123456789"Text.Characters.DatabaseName
The characters allowed in a database name.
Definition
LET DatabaseName = "A…Za…z0…9_"Text.Characters.Hex
The hexadecimal digits, upper and lower case.
Definition
LET Hex = "0123456789ABCDEFabcdef"Text.Characters.HexLower
The lowercase hexadecimal digits.
Definition
LET HexLower = "0123456789abcdef"Text.Characters.HexUpper
The uppercase hexadecimal digits.
Definition
LET HexUpper = "0123456789ABCDEF"Text.Characters.Lower
The lowercase ASCII letters a to z.
Definition
LET Lower = "abc…xyz"Text.Characters.Numeric
The decimal digits 0 to 9.
Definition
LET Numeric = "0123456789"Text.Characters.Upper
The uppercase ASCII letters A to Z.
Definition
LET Upper = "ABC…XYZ"Text.Characters.Urlname
The characters allowed in a URL-safe name.
Definition
LET Urlname = "A…Za…z0…9-._"Functions
Text.AllowChars
Keeps only the characters in an allowed set.
Parameters
| Name | Type | Description |
|---|---|---|
string | Text | The string to filter. |
allowedChars | Text | The characters to keep. |
Returns
Returns Text — string with every character not in allowedChars removed.
Example
LET Text safe = Text.AllowChars input Text.Characters.AlphanumericText.Append
Joins two or more strings end to end.
Parameters
| Name | Type | Description |
|---|---|---|
a | Text | The leading string. |
b | Text | The next string. |
c | Collection.Optional(Text) | Third string, appended when present. |
d | Collection.Optional(Text) | Fourth string, appended when present. |
e | Collection.Optional(Text) | Fifth string, appended when present. |
f | Collection.Optional(Text) | Sixth string, appended when present. |
g | Collection.Optional(Text) | Seventh string, appended when present. |
Returns
Returns Text — a and b joined end to end, followed by each of c through g that holds a value, in order.
Example
LET Text url = Text.Append base path queryOptionalpath to base, then queryOptional when it holds a value.Text.AppendOptional
Appends a second string only when it is present.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The base string. |
optionalText | Collection.Optional(Text) | The string to append when present. |
Returns
Returns Text — text, with optionalText appended when it holds a value.
Text.CharAt
The character at a position.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The source string. |
pos | Maths.Integer | Zero-based index. |
optionalDefaultChar | Collection.Optional(Text) | Returned when pos is out of range; empty when absent. |
Returns
Returns Text — the character at pos, or optionalDefaultChar when out of range.
Text.Contains
Yes when a substring occurs anywhere.
Parameters
| Name | Type | Description |
|---|---|---|
haystack | Text | The string to search. |
needle | Text | The substring to look for. |
Returns
Returns Logic.Maybe — yes when needle occurs anywhere in haystack.
Example
LET Logic.Maybe hit = Text.Contains haystack "cat"Text.ContainsOnly
Yes when every character is allowed.
Parameters
| Name | Type | Description |
|---|---|---|
string | Text | The string to test. |
allowedChars | Text | The permitted characters. |
Returns
Returns Logic.Maybe — yes when every character of string is in allowedChars.
Text.Emit
Emits a piece to the enclosing Gather.
Parameters
| Name | Type | Description |
|---|---|---|
piece | Text | The string piece to contribute. |
Returns
Returns nothing — it adds piece to the enclosing Text.Gather.
Text.Empty
Yes when the text has no characters.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to test. |
Returns
Returns Logic.Maybe — yes when text has no characters.
Example
LET Logic.Maybe blank = Text.Empty inputText.Encode.Url
Percent-encodes text for use in a URL.
Parameters
| Name | Type | Description |
|---|---|---|
input | Text | The string to encode. |
Returns
Returns Text — input percent-encoded so it is safe inside a URL.
Example
LET Text q = Text.Encode.Url queryText.EndsWith
Yes when the text ends with a suffix.
Parameters
| Name | Type | Description |
|---|---|---|
haystack | Text | The string to test. |
needle | Text | The suffix to look for. |
Returns
Returns Logic.Maybe — yes when haystack ends with needle.
Text.Equal
Yes when two strings are equal.
Parameters
| Name | Type | Description |
|---|---|---|
a | Text | First string. |
b | Text | Second string. |
Returns
Returns Logic.Maybe — yes when a and b are exactly equal.
Text.FormatNumber
Formats a number with decimals and separators.
Parameters
| Name | Type | Description |
|---|---|---|
n | Maths.Real | The number to format. |
optionalDecimalPlaces | Collection.Optional(Maths.Integer) | Decimal places to show; 0 when absent. |
optionalAddThousandsSep | Collection.Optional(Logic.Maybe) | Whether to group thousands; yes when absent. |
Returns
Returns Text — n formatted with the given decimal places and optional thousands separators.
Example
LET Text price = Text.FormatNumber amount 2 yesText.Gather
Collects emitted pieces and joins them.
Block
The block whose Text.Emit calls contribute the pieces to join.
Returns
Returns Text — the pieces emitted within its block, concatenated in order.
Example
LET Text line = Text.Gather
Text.Emit "Hello"
Text.Emit " world"Text.GatherJoin
Collects emitted pieces and joins them with a separator.
Parameters
| Name | Type | Description |
|---|---|---|
separator | Text | Text placed between the gathered pieces. |
Block
The block whose Text.Emit calls contribute the pieces to join.
Returns
Returns Text — the pieces emitted within its block, joined by separator.
Text.GetBetween
The text between two markers.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to search. |
a | Text | The opening marker. |
b | Text | The closing marker. |
Returns
Returns Collection.Optional(Text) — the text between the first a and the next b, or nothing when a is absent.
Text.GetEverythingAfter
The text after the first marker.
Parameters
| Name | Type | Description |
|---|---|---|
str | Text | The string to search. |
substr | Text | The marker to start after. |
Returns
Returns Collection.Optional(Text) — the part of str after the first substr, or nothing when absent.
Text.GetEverythingBefore
The text before the first marker.
Parameters
| Name | Type | Description |
|---|---|---|
haystack | Text | The string to search. |
needle | Text | The marker to stop at. |
Returns
Returns Text — the part of haystack before the first needle.
Text.IndexOf
The position of a substring, or -1.
Parameters
| Name | Type | Description |
|---|---|---|
haystack | Text | The string to search in. |
needle | Text | The substring to find. |
optionalOffset | Collection.Optional(Maths.Integer) | Index to start searching from; the start when absent. |
Returns
Returns Maths.Integer — the index of the first needle at or after optionalOffset, or -1 when not found.
Text.Interpolate
Blends one string into another by progress.
Parameters
| Name | Type | Description |
|---|---|---|
start | Text | The string at progress 0. |
target | Text | The string at progress 1. |
progress | Maths.Real | How far between, 0 to 1. |
Returns
Returns Text — a blend of start and target set by progress.
Example
LET Text tween = Text.Interpolate from to progressText.IsLower
Yes when the text is all lowercase letters.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to test. |
Returns
Returns Logic.Maybe — yes when every character of text is a lowercase ASCII letter.
Text.IsWhitespace
Yes when the text is empty or only whitespace.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to test. |
Returns
Returns Logic.Maybe — yes when text is empty or contains only whitespace.
Text.Join
Joins an array of strings into one.
Parameters
| Name | Type | Description |
|---|---|---|
elements | Collection.Array(Text) | The strings to join. |
optionalSeparator | Collection.Optional(Text) | Text placed between elements; none when absent. |
Returns
Returns Text — the elements concatenated, separated by optionalSeparator when given.
Example
LET Text csv = Text.Join parts ","Text.Length
The number of characters in the text.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to measure. |
Returns
Returns Maths.Integer — the number of characters in text.
Example
LET Maths.Integer size = Text.Length messageText.Lower
The text in lower case.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to convert. |
Returns
Returns Text — text with every letter lower-cased.
Text.Matches
Yes when the text matches a regular expression.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to test. |
pattern | Text | The regular expression. |
Returns
Returns Logic.Maybe — yes when text matches the regular expression pattern.
Text.NotEmpty
Yes when the text has at least one character.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to test. |
Returns
Returns Logic.Maybe — yes when text has at least one character.
Text.NotEqual
Yes when two strings differ.
Parameters
| Name | Type | Description |
|---|---|---|
a | Text | First string. |
b | Text | Second string. |
Returns
Returns Logic.Maybe — yes when a and b are not equal.
Text.Option
Runs its block when its value matches the enclosing Select.
Parameters
| Name | Type | Description |
|---|---|---|
optionValue | Text | The value this option matches. |
Block
The content to run when optionValue equals the value selected by the enclosing Text.Select.
Returns
Returns nothing — it runs its block only on a match.
Text.PadLeft
Pads a string on the left to a length.
Parameters
| Name | Type | Description |
|---|---|---|
string | Text | The string to pad. |
length | Maths.Integer | The target length. |
optionalPadString | Collection.Optional(Text) | The padding text; a space when absent. |
Returns
Returns Text — string padded on the left to length with optionalPadString.
Example
LET Text code = Text.PadLeft digits 4 "0"Text.RemoveChars
Removes characters from the start or end.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The source string. |
num | Maths.Integer | Characters to drop from the start, or from the end when negative. |
Returns
Returns Text — text with num characters removed from the start, or from the end when negative.
Text.RemoveFromEnd
Removes a suffix if present.
Parameters
| Name | Type | Description |
|---|---|---|
haystack | Text | The source string. |
needle | Text | The suffix to remove. |
Returns
Returns Text — haystack with a trailing needle removed when present.
Text.RemoveFromStart
Removes a prefix if present.
Parameters
| Name | Type | Description |
|---|---|---|
haystack | Text | The source string. |
needle | Text | The prefix to remove. |
Returns
Returns Text — haystack with a leading needle removed when present.
Text.Replace
Replaces the first occurrence of a substring.
Parameters
| Name | Type | Description |
|---|---|---|
search | Text | The substring to find. |
replace | Text | The replacement. |
haystack | Text | The string to search in. |
Returns
Returns Text — haystack with the first search replaced by replace.
Text.ReplaceAll
Replaces every occurrence of a substring.
Parameters
| Name | Type | Description |
|---|---|---|
search | Text | The substring to find. |
replace | Text | The replacement. |
haystack | Text | The string to search in. |
Returns
Returns Text — haystack with every search replaced by replace.
Text.Select
Opens a group that runs the matching Option for a string value.
Parameters
| Name | Type | Description |
|---|---|---|
value | Text | The string the options are matched against. |
Block
An indented block of Text.Option entries; the one whose value equals value runs.
Returns
Returns nothing — it publishes value to the enclosed options over its block.
Example
Text.Select role
Text.Option "admin"
Ui.Content.Text "Welcome, admin"
Text.Option "guest"
Ui.Content.Text "Please sign in"role.Text.Sha1
A hexadecimal digest of the text.
Parameters
| Name | Type | Description |
|---|---|---|
input | Text | The string to digest. |
Returns
Returns Text — a hexadecimal digest string derived from input.
Text.Split
Divides a string into an array on a delimiter.
Parameters
| Name | Type | Description |
|---|---|---|
string | Text | The string to split. |
delimiter | Text | The separator to split on. |
Returns
Returns Collection.Array(Text) — the pieces of string divided at each delimiter.
Example
LET Collection.Array(Text) parts = Text.Split line ","Text.Start
The first characters of a string.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The source string. |
length | Maths.Integer | How many leading characters to take. |
Returns
Returns Text — the first length characters of text.
Text.StartsWith
Yes when the text begins with a prefix.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to test. |
startsWith | Text | The prefix to look for. |
Returns
Returns Logic.Maybe — yes when text begins with startsWith.
Text.Substring
Extracts part of a string by position and length.
Parameters
| Name | Type | Description |
|---|---|---|
string | Text | The source string. |
start | Maths.Integer | Zero-based start index. |
optionalLength | Collection.Optional(Maths.Integer) | How many characters to take; to the end when absent. |
Returns
Returns Text — the slice of string from start, up to optionalLength characters.
Example
LET Text head = Text.Substring text 0 5Text.Trim
Removes whitespace from both ends.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to trim. |
Returns
Returns Text — text with leading and trailing whitespace removed.
Text.TrimEnd
Removes trailing whitespace.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to trim. |
Returns
Returns Text — text with trailing whitespace removed.
Text.TrimStart
Removes leading whitespace.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to trim. |
Returns
Returns Text — text with leading whitespace removed.
Text.Upper
The text in upper case.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to convert. |
Returns
Returns Text — text with every letter upper-cased.
Example
LET Text shout = Text.Upper nameText.UpperFirst
Capitalises the first letter of each word.
Parameters
| Name | Type | Description |
|---|---|---|
text | Text | The string to convert. |
Returns
Returns Text — text with each word's first letter capitalised and the rest lower-cased.