String

GitHub   Edit on GitHub

Utilities for working with strings.

Added in 0.2.0
versionchanges
0.1.0Originally named `strings`
0.2.0Renamed to `string`
1
from "string" include String

Types

Type declarations included in the String module.

String.Encoding

1
2
3
4
5
6
7
enum Encoding {
UTF8,
UTF16_BE,
UTF16_LE,
UTF32_BE,
UTF32_LE,
}

Byte encodings


Values

Functions and constants included in the String module.

String.concat

Added in 0.2.0 No other changes yet.
1
concat : (str1: String, str2: String) => String

Concatenate two strings.

Parameters:

param type description
str1 String The beginning string
str2 String The ending string

Returns:

type description
String The combined string

Examples:

1
String.concat("Foo", "Bar") == "FooBar"

String.length

Added in 0.1.0 No other changes yet.
1
length : (string: String) => Number

Returns the character length of the input string.

Parameters:

param type description
string String The string to inspect

Returns:

type description
Number The number of characters in the string

Examples:

1
String.length("Hello world") == 11

String.byteLength

Added in 0.1.0 No other changes yet.
1
byteLength : (string: String) => Number

Returns the byte length of the input string.

Parameters:

param type description
string String The string to inspect

Returns:

type description
Number The number of bytes in the string

Examples:

1
String.byteLength("🌾") == 4

String.isEmpty

Added in 0.6.0 No other changes yet.
1
isEmpty : (string: String) => Bool

Determines if the string contains no characters.

Parameters:

param type description
string String The string to inspect

Returns:

type description
Bool true if the string is empty and false otherwise

String.indexOf

Added in 0.3.0 No other changes yet.
1
indexOf : (search: String, string: String) => Option<Number>

Finds the first position of a substring in the input string.

Parameters:

param type description
search String The substring to find
string String The string to inspect

Returns:

type description
Option<Number> Some(position) containing the starting position of the substring if found or None otherwise

Examples:

1
String.indexOf("world", "Hello world") == Some(6)

String.lastIndexOf

Added in 0.5.3 No other changes yet.
1
lastIndexOf : (search: String, string: String) => Option<Number>

Finds the last position of a substring in the input string.

Parameters:

param type description
search String The substring to find
string String The string to inspect

Returns:

type description
Option<Number> Some(position) containing the starting position of the substring if found or None otherwise

Examples:

1
String.lastIndexOf("world", "Hello world world") == Some(12)

String.charCodeAt

Added in 0.5.3 No other changes yet.
1
charCodeAt : (position: Number, string: String) => Number

Get the Unicode code point at the position in the input string.

Parameters:

param type description
position Number The position to check
string String The string to search

Returns:

type description
Number The character code at the provided position

Throws:

Failure(String)

  • When the position is out of bounds

MalformedUnicode

  • When the string is malformed

Examples:

1
String.charCodeAt(5, "Hello world") == 32

String.charAt

Added in 0.4.0 No other changes yet.
1
charAt : (position: Number, string: String) => Char

Get the character at the position in the input string.

Parameters:

param type description
position Number The position to check
string String The string to search

Returns:

type description
Char The character at the provided position

Throws:

Failure(String)

  • When the position is out of bounds

MalformedUnicode

  • When the string is malformed

Examples:

1
String.charAt(5, "Hello world") == ' '

String.explode

Added in 0.3.0 No other changes yet.
1
explode : (string: String) => Array<Char>

Split a string into its Unicode characters.

Parameters:

param type description
string String The string to split

Returns:

type description
Array<Char> An array containing all characters in the string

Throws:

MalformedUnicode

  • When the string is malformed

Examples:

1
String.explode("Hello") == [> 'H', 'e', 'l', 'l', 'o']

String.implode

Added in 0.3.0 No other changes yet.
1
implode : (arr: Array<Char>) => String

Create a string from an array of characters.

Parameters:

param type description
arr Array<Char> The array to combine

Returns:

type description
String A string representation of the array of characters

Examples:

1
String.implode([> 'H', 'e', 'l', 'l', 'o']) == "Hello"

String.reverse

Added in 0.4.5 No other changes yet.
1
reverse : (string: String) => String

Create a string that is the given string reversed.

Parameters:

param type description
string String The string to reverse

Returns:

type description
String A string whose characters are in the reverse order of the given string

Examples:

1
String.reverse("olleH") == "Hello"

String.split

1
split : (separator: String, string: String) => Array<String>

Split a string by the given separator.

Parameters:

param type description
separator String The separator to split on
string String The string to split

Returns:

type description
Array<String> An array of substrings from the initial string

Throws:

MalformedUnicode

  • When the string is malformed

Examples:

1
String.split(" ", "Hello world") == [> "Hello", "world"]

String.slice

Added in 0.1.0
versionchanges
0.6.0Default `end` to the String length
1
slice : (start: Number, ?end: Number, string: String) => String

Get a portion of a string.

Parameters:

param type description
start Number The start position of the substring
?end Number The end position of the substring, exclusive
string String The input string

Returns:

type description
String The substring from the initial string

Throws:

IndexOutOfBounds

  • When start is out of bounds
  • When end is out of bounds

InvalidArgument(String)

  • When the start index is not an integer
  • When the to index is not an integer
  • When start is greater than end

Examples:

1
String.slice(0, end=5, "Hello world") == "Hello"
1
String.slice(0, "Hello world") == "Hello world"

String.contains

Added in 0.1.0 No other changes yet.
1
contains : (search: String, string: String) => Bool

Check if a string contains a substring.

Parameters:

param type description
search String The substring to check
string String The string to search

Returns:

type description
Bool true if the input string contains the search value or false otherwise

Examples:

1
String.contains("world", "Hello world") == true

String.startsWith

Added in 0.1.0 No other changes yet.
1
startsWith : (search: String, string: String) => Bool

Check if a string begins with another string.

Parameters:

param type description
search String The string to compare to the start
string String The string to search

Returns:

type description
Bool true if the input string starts with the search value or false otherwise

Examples:

1
String.startsWith("Hello", "Hello world") == true

String.endsWith

Added in 0.1.0 No other changes yet.
1
endsWith : (search: String, string: String) => Bool

Check if a string ends with another string.

Parameters:

param type description
search String The string to compare to the end
string String The string to search

Returns:

type description
Bool true if the input string ends with the search value or false otherwise

Examples:

1
String.endsWith("world", "Hello world") == true

String.replaceFirst

Added in 0.5.4 No other changes yet.
1
2
replaceFirst :
(searchPattern: String, replacement: String, string: String) => String

Replaces the first appearance of the search pattern in the string with the replacement value.

Parameters:

param type description
searchPattern String The string to replace
replacement String The replacement
string String The string to change

Returns:

type description
String A new string with the first occurrence of the search pattern replaced

Examples:

1
String.replaceFirst("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌎🌾"

String.replaceLast

Added in 0.5.4 No other changes yet.
1
2
replaceLast :
(searchPattern: String, replacement: String, string: String) => String

Replaces the last appearance of the search pattern in the string with the replacement value.

Parameters:

param type description
searchPattern String The string to replace
replacement String The replacement
string String The string to change

Returns:

type description
String A new string with the last occurrence of the search pattern replaced

Examples:

1
String.replaceLast("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌾🌎"

String.replaceAll

Added in 0.5.4 No other changes yet.
1
2
replaceAll :
(searchPattern: String, replacement: String, string: String) => String

Replaces every appearance of the search pattern in the string with the replacement value.

Parameters:

param type description
searchPattern String The string to replace
replacement String The replacement
string String The string to change

Returns:

type description
String A new string with each occurrence of the search pattern replaced

Examples:

1
String.replaceAll("🌾", "🌎", "Hello 🌾🌾") == "Hello 🌎🌎"

String.encodeAt

Added in 0.4.0
versionchanges
0.6.0Added `includeBom` default argument
1
2
3
encodeAt :
(string: String, encoding: Encoding, dest: Bytes, destPos: Number,
?includeBom: Bool) => Bytes

Encodes the given string into a byte sequence at the supplied position using the encoding scheme provided.

Parameters:

param type description
string String The input string
encoding Encoding The encoding to use
dest Bytes The byte sequence that will be copied
destPos Number The location in the byte sequence to write the output
?includeBom Bool Whether or not to include a byte order marker (false by default)

Returns:

type description
Bytes A copy of the input bytes with the encoded string replaced at the given position

Throws:

InvalidArgument(String)

  • When destPos is not an integer
  • When destPos is negative

String.encode

Added in 0.4.0
versionchanges
0.6.0Added `includeBom` default argument
1
encode : (string: String, encoding: Encoding, ?includeBom: Bool) => Bytes

Encodes the given string using the given encoding scheme.

Parameters:

param type description
string String The input string
encoding Encoding The encoding to use
?includeBom Bool Whether or not to include a byte order marker (false by default)

Returns:

type description
Bytes The byte representation of the string in the given encoding

String.decodeRange

Added in 0.4.0
versionchanges
0.6.0Added `keepBom` default argument
1
2
3
decodeRange :
(bytes: Bytes, encoding: Encoding, start: Number, size: Number,
?keepBom: Bool) => String

Decodes the given byte sequence of the specified range into a string using the encoding scheme provided.

Parameters:

param type description
bytes Bytes The input bytes
encoding Encoding The encoding to use
start Number The byte offset to begin decoding from
size Number The maximum number of bytes to decode
?keepBom Bool Whether or not to include a byte order marker (false by default)

Returns:

type description
String The decoded string

Throws:

InvalidArgument(String)

  • When start is not an integer
  • When start is negative
  • When size is not an integer
  • When size is negative

String.decode

Added in 0.4.0
versionchanges
0.6.0Added `keepBom` default argument
1
decode : (bytes: Bytes, encoding: Encoding, ?keepBom: Bool) => String

Decodes the given byte sequence into a string using the given encoding scheme.

Parameters:

param type description
bytes Bytes The input bytes
encoding Encoding The encoding to use
?keepBom Bool Whether or not to include a byte order marker (false by default)

Returns:

type description
String The decoded string

String.forEachCodePoint

Added in 0.4.0 No other changes yet.
1
forEachCodePoint : (fn: (Number => Void), str: String) => Void

Iterates over Unicode code points in a string.

Parameters:

param type description
fn Number => Void The iterator function
str String The string to iterate

Examples:

1
String.forEachCodePoint(print, "Hello world")

String.forEachCodePointi

Added in 0.4.0 No other changes yet.
1
forEachCodePointi : (fn: ((Number, Number) => Void), str: String) => Void

Iterates over Unicode code points in a string. This is the same as forEachCodePoint, but provides the code point’s index in the string as the second argument to the iterator function.

Parameters:

param type description
fn (Number, Number) => Void The iterator function
str String The string to iterate

Examples:

1
String.forEachCodePointi((codepoint, index) => print((codepoint, index)), "Hello world")

String.forEachChar

Added in 0.6.5 No other changes yet.
1
forEachChar : (fn: (Char => Void), str: String) => Void

Iterates over Unicode characters in a string.

Parameters:

param type description
fn Char => Void The iterator function
str String The string to iterate

Examples:

1
String.forEachChar(print, "Hello world")

String.forEachChari

Added in 0.6.5 No other changes yet.
1
forEachChari : (fn: ((Char, Number) => Void), str: String) => Void

Iterates over Unicode characters in a string. This is the same as forEachChar, but provides the characters’s index in the string as the second argument to the iterator function.

Parameters:

param type description
fn (Char, Number) => Void The iterator function
str String The string to iterate

Examples:

1
String.forEachChari((char, index) => print((char, index)), "Hello world")

String.map

Added in 0.6.5 No other changes yet.
1
map : (fn: (Char => Char), str: String) => String

Builds a new string by mapping Unicode characters.

Parameters:

param type description
fn Char => Char The mapping function
str String The string to map

Examples:

1
assert String.map((c) => 'a', "Hello world") == "aaaaaaaaaaa"

String.mapi

Added in 0.6.5 No other changes yet.
1
mapi : (fn: ((Char, Number) => Char), str: String) => String

Builds a new string by mapping Unicode characters. This is the same as mapChar, but provides the characters’s index in the string as the second argument to the mapping function.

Parameters:

param type description
fn (Char, Number) => Char The mapping function
str String The string to map

Examples:

1
assert String.mapi((char, index) => String.charAt(0, toString(index)), "Hello world") == "01234567891"

String.trimStart

Added in 0.4.2 No other changes yet.
1
trimStart : (string: String) => String

Trims the beginning of a string—removing any leading whitespace characters.

Parameters:

param type description
string String The string to be trimmed

Returns:

type description
String The trimmed string

Examples:

1
String.trimStart("   Hello World") == "Hello World"

String.trimEnd

Added in 0.4.2 No other changes yet.
1
trimEnd : (string: String) => String

Trims the end of a string—removing any trailing whitespace characters.

Parameters:

param type description
string String The string to be trimmed

Returns:

type description
String The trimmed string

Examples:

1
String.trimEnd("Hello World   ") == "Hello World"

String.trim

Added in 0.4.2 No other changes yet.
1
trim : (string: String) => String

Trims a string—removing all leading and trailing whitespace characters.

Parameters:

param type description
string String The string to be trimmed

Returns:

type description
String The trimmed string

Examples:

1
String.trim("   Hello World   ") == "Hello World"

String.toAsciiLowercase

Added in 0.6.0 No other changes yet.
1
toAsciiLowercase : (string: String) => String

Converts all ASCII uppercase characters in the string to lowercase.

Parameters:

param type description
string String The string to convert

Returns:

type description
String The lowercased string

Examples:

1
assert String.toAsciiLowercase("aBc123") == "abc123"

String.toAsciiUppercase

Added in 0.6.0 No other changes yet.
1
toAsciiUppercase : (string: String) => String

Converts all ASCII lowercase characters in the string to uppercase.

Parameters:

param type description
string String The string to convert

Returns:

type description
String The uppercased string

Examples:

1
assert String.toAsciiUppercase("aBc123") == "ABC123"
This is a notification!