String

Functions for interacting with JavaScript strings. See: String.

make(value) converts the given value to a string.

Examples

RESCRIPT
String.make(3.5) == "3.5"
String.make([1, 2, 3]) == "1,2,3"

fromCharCode(n) creates a string containing the character corresponding to that number, n ranges from 0 to 65535. If out of range, the lower 16 bits of the value are used. Thus, fromCharCode(0x1F63A) gives the same result as fromCharCode(0xF63A). See String.fromCharCode on MDN.

Examples

RESCRIPT
String.fromCharCode(65) == "A"
String.fromCharCode(0x3c8) == `ψ`
String.fromCharCode(0xd55c) == `한`
String.fromCharCode(-64568) == `ψ`

fromCharCodeMany([n1, n2, n3]) creates a string from the characters corresponding to the given numbers, using the same rules as fromCharCode. See String.fromCharCode on MDN.

Examples

RESCRIPT
String.fromCharCodeMany([189, 43, 190, 61]) == "½+¾="
String.fromCharCodeMany([65, 66, 67]) == "ABC"

fromCodePoint(n) creates a string containing the character corresponding to that numeric code point. See String.fromCodePoint on MDN.

Examples

RESCRIPT
String.fromCodePoint(65) == "A"
String.fromCodePoint(0x3c8) == `ψ`
String.fromCodePoint(0xd55c) == `한`
String.fromCodePoint(0x1f63a) == `😺`

Exceptions

• RangeError: If the number is not a valid code point, like fromCharCode(-5).

fromCodePointMany([n1, n2, n3]) creates a string from the characters corresponding to the given code point numbers, using the same rules as fromCodePoint. See String.fromCodePoint on MDN.

Examples

RESCRIPT
String.fromCodePointMany([0xd55c, 0xae00, 0x1f63a]) == `한글😺`

Exceptions

• RangeError: If one of the number is not a valid code point, like fromCharCode([1, -5]).

length(str) returns the length of the given string. See String.length on MDN.

Examples

RESCRIPT
String.length("abcd") == 4

get(str, index) returns an option<string> at the given index number. If index is out of range, this function returns None.

Examples

RESCRIPT
String.get("ReScript", 0) == Some("R")
String.get("Hello", 4) == Some("o")
String.get(`JS`, 4) == None

getUnsafe(str, index) returns an string at the given index number.

This is unsafe, meaning it will return undefined value if index does not exist in string.

Use String.getUnsafe only when you are sure the index exists.

Examples

RESCRIPT
String.getUnsafe("ReScript", 0) == "R"
String.getUnsafe("Hello", 4) == "o"

charAt(str, index) gets the character at index within string str. If index is negative or greater than the length of str, it returns the empty string. If the string contains characters outside the range \u0000-\uffff, it will return the first 16-bit value at that position in the string. See String.charAt on MDN.

Examples

RESCRIPT
String.charAt("ReScript", 0) == "R"
String.charAt("Hello", 12) == ""
String.charAt(`JS`, 5) == ""

charCodeAt(str, index) returns the character code at position index in string str the result is in the range 0-65535, unlike codePointAt, so it will not work correctly for characters with code points greater than or equal to 0x10000. The return type is float because this function returns NaN if index is less than zero or greater than the length of the string. See String.charCodeAt on MDN.

Examples

RESCRIPT
String.charCodeAt(`😺`, 0) == 0xd83d->Int.toFloat
String.codePointAt(`😺`, 0) == Some(0x1f63a)

codePointAt(str, index) returns the code point at position index within string str as a Some(value). The return value handles code points greater than or equal to 0x10000. If there is no code point at the given position, the function returns None. See String.codePointAt on MDN.

Examples

RESCRIPT
String.codePointAt(`¿😺?`, 1) == Some(0x1f63a)
String.codePointAt("abc", 5) == None

concat(original, append) returns a new string with append added after original. See String.concat on MDN.

Examples

RESCRIPT
String.concat("cow", "bell") == "cowbell"
String.concat("Re", "Script") == "ReScript"

concatMany(original, arr) returns a new string consisting of each item of an array of strings added to the original string. See String.concat on MDN.

Examples

RESCRIPT
String.concatMany("1st", ["2nd", "3rd", "4th"]) == "1st2nd3rd4th"

endsWith(str, substr) returns true if the str ends with substr, false otherwise. See String.endsWith on MDN.

Examples

RESCRIPT
String.endsWith("BuckleScript", "Script") == true
String.endsWith("BuckleShoes", "Script") == false

endsWithFrom(str, ending, len) returns true if the first len characters of str end with ending, false otherwise. If len is greater than or equal to the length of str, then it works like endsWith. See String.endsWith on MDN.

Examples

RESCRIPT
String.endsWithFrom("abcd", "cd", 4) == true
String.endsWithFrom("abcde", "cd", 3) == false
String.endsWithFrom("abcde", "cde", 99) == true
String.endsWithFrom("example.dat", "ple", 7) == true

includes(str, searchValue) returns true if searchValue is found anywhere within str, false otherwise. See String.includes on MDN.

Examples

RESCRIPT
String.includes("programmer", "gram") == true
String.includes("programmer", "er") == true
String.includes("programmer", "pro") == true
String.includes("programmer.dat", "xyz") == false

includesFrom(str, searchValue, start) returns true if searchValue is found anywhere within str starting at character number start (where 0 is the first character), false otherwise. See String.includes on MDN.

Examples

RESCRIPT
String.includesFrom("programmer", "gram", 1) == true
String.includesFrom("programmer", "gram", 4) == false
String.includesFrom(`대한민국`, `한`, 1) == true

indexOf(str, searchValue) returns the position at which searchValue was first found within str, or -1 if searchValue is not in str. See String.indexOf on MDN.

Examples

RESCRIPT
String.indexOf("bookseller", "ok") == 2
String.indexOf("bookseller", "sell") == 4
String.indexOf("beekeeper", "ee") == 1
String.indexOf("bookseller", "xyz") == -1

indexOfOpt(str, searchValue). Like indexOf, but return an option<int>.

Examples

RESCRIPT
String.indexOfOpt("bookseller", "ok") == Some(2)
String.indexOfOpt("bookseller", "xyz") == None

indexOfFrom(str, searchValue, start) returns the position at which searchValue was found within str starting at character position start, or -1 if searchValue is not found in that portion of str. The return value is relative to the beginning of the string, no matter where the search started from. See String.indexOf on MDN.

Examples

RESCRIPT
String.indexOfFrom("bookseller", "ok", 1) == 2
String.indexOfFrom("bookseller", "sell", 2) == 4
String.indexOfFrom("bookseller", "sell", 5) == -1

lastIndexOf(str, searchValue) returns the position of the last occurrence of searchValue within str, searching backwards from the end of the string. Returns -1 if searchValue is not in str. The return value is always relative to the beginning of the string. See String.lastIndexOf on MDN.

Examples

RESCRIPT
String.lastIndexOf("bookseller", "ok") == 2
String.lastIndexOf("beekeeper", "ee") == 4
String.lastIndexOf("abcdefg", "xyz") == -1

lastIndexOfOpt(str, searchValue). Like lastIndexOfOpt, but return an option<int>.

Examples

RESCRIPT
String.lastIndexOfOpt("bookseller", "ok") == Some(2)
String.lastIndexOfOpt("beekeeper", "ee") == Some(4)
String.lastIndexOfOpt("abcdefg", "xyz") == None

lastIndexOfFrom(str, searchValue, start) returns the position of the last occurrence of searchValue within str, searching backwards from the given start position. Returns -1 if searchValue is not in str. The return value is always relative to the beginning of the string. See String.lastIndexOf on MDN.

Examples

RESCRIPT
String.lastIndexOfFrom("bookseller", "ok", 6) == 2
String.lastIndexOfFrom("beekeeper", "ee", 8) == 4
String.lastIndexOfFrom("beekeeper", "ee", 3) == 1
String.lastIndexOfFrom("abcdefg", "xyz", 4) == -1

match(str, regexp) matches a string against the given regexp. If there is no match, it returns None. For regular expressions without the g modifier, if there is a match, the return value is Some(array) where the array contains:

• The entire matched string

• Any capture groups if the regexp had parentheses For regular expressions with the g modifier, a matched expression returns Some(array) with all the matched substrings and no capture groups. See String.match on MDN.

Examples

RESCRIPT
String.match("The better bats", %re("/b[aeiou]t/")) == Some([Some("bet")])
String.match("The better bats", %re("/b[aeiou]t/g")) == Some([Some("bet"), Some("bat")])
String.match("Today is 2018-04-05.", %re("/(\d+)-(\d+)-(\d+)/")) ==
  Some([Some("2018-04-05"), Some("2018"), Some("04"), Some("05")])
String.match("The optional example", %re("/(foo)?(example)/")) == Some([Some("example"), None, Some("example")])
String.match("The large container.", %re("/b[aeiou]g/")) == None

normalize(str) returns the normalized Unicode string using Normalization Form Canonical (NFC) Composition. Consider the character ã, which can be represented as the single codepoint \u00e3 or the combination of a lower case letter A \u0061 and a combining tilde \u0303. Normalization ensures that both can be stored in an equivalent binary representation. See String.normalize on MDN. See also Unicode technical report #15 for details.

Examples

RESCRIPT
let string1 = "\uFB00"
let string2 = "\u0066\u0066"
Console.log(string1 === string2) // false

let normalizeString1 = String.normalize(string1)
let normalizeString2 = String.normalize(string2)
assert(normalizeString1 === normalizeString2)

normalizeByForm(str, form) returns the normalized Unicode string using the specified form of normalization, which may be one of:

• "NFC" — Normalization Form Canonical Composition.

• "NFD" — Normalization Form Canonical Decomposition.

• "NFKC" — Normalization Form Compatibility Composition.

• "NFKD" — Normalization Form Compatibility Decomposition. See String.normalize on MDN. See also Unicode technical report #15 for details.

Examples

RESCRIPT
let string1 = "\uFB00"
let string2 = "\u0066\u0066"
Console.log(string1 == string2) // false

let normalizeString1 = String.normalizeByForm(string1, #NFKD)
let normalizeString2 = String.normalizeByForm(string2, #NFKD)
Console.log(normalizeString1 == normalizeString2) // true

repeat(str, n) returns a string that consists of n repetitions of str. See String.repeat on MDN.

Examples

RESCRIPT
String.repeat("ha", 3) == "hahaha"
String.repeat("empty", 0) == ""

Exceptions

• RangeError: if n is negative.

replace(str, substr, newSubstr) returns a new string which is identical to str except with the first matching instance of substr replaced by newSubstr. substr is treated as a verbatim string to match, not a regular expression. See String.replace on MDN.

Examples

RESCRIPT
String.replace("old string", "old", "new") == "new string"
String.replace("the cat and the dog", "the", "this") == "this cat and the dog"

replaceRegExp(str, regex, replacement) returns a new string where occurrences matching regex have been replaced by replacement. See String.replace on MDN.

Examples

RESCRIPT
String.replaceRegExp("vowels be gone", %re("/[aeiou]/g"), "x") == "vxwxls bx gxnx"
String.replaceRegExp("Juan Fulano", %re("/(\w+) (\w+)/"), "$2, $1") == "Fulano, Juan"

replaceAll(str, substr, newSubstr) returns a new string which is identical to str except with all matching instances of substr replaced by newSubstr. substr is treated as a verbatim string to match, not a regular expression. See String.replaceAll on MDN.

Examples

RESCRIPT
String.replaceAll("old old string", "old", "new") == "new new string"
String.replaceAll("the cat and the dog", "the", "this") == "this cat and this dog"

replaceAllRegExp(str, regex, replacement) returns a new string where all occurrences matching regex have been replaced by replacement. The pattern must include the global (g) flag or a runtime TypeError will be thrown. See String.replaceAll on MDN.

Examples

RESCRIPT
String.replaceAllRegExp("vowels be gone", %re("/[aeiou]/g"), "x") == "vxwxls bx gxnx"
String.replaceAllRegExp("aabbcc", %re("/b/g"), ".") == "aa..cc"

unsafeReplaceRegExpBy0(str, regex, f) returns a new string with some or all matches of a pattern with no capturing parentheses replaced by the value returned from the given function. The function receives as its parameters the matched string, the offset at which the match begins, and the whole string being matched. See String.replace on MDN.

Examples

RESCRIPT
let str = "beautiful vowels"
let re = %re("/[aeiou]/g")
let matchFn = (~match, ~offset as _, ~input as _) => String.toUpperCase(match)
String.unsafeReplaceRegExpBy0(str, re, matchFn) == "bEAUtIfUl vOwEls"

unsafeReplaceRegExpBy1(str, regexp, f). Like unsafeReplaceRegExpBy0, but f has group1 parameter. See String.replace on MDN.

Examples

RESCRIPT
let str = "Jony is 40"
let re = %re("/(Jony is )\d+/g")
let matchFn = (~match as _, ~group1, ~offset as _, ~input as _) => {
  group1 ++ "41"
}
String.unsafeReplaceRegExpBy1(str, re, matchFn) == "Jony is 41"

unsafeReplaceRegExpBy2(str, regexp, f). Like unsafeReplaceRegExpBy1, but f has two group parameters. See String.replace on MDN.

Examples

RESCRIPT
let str = "7 times 6"
let re = %re("/(\d+) times (\d+)/")
let matchFn = (~match as _, ~group1, ~group2, ~offset as _, ~input as _) => {
  switch (Int.fromString(group1), Int.fromString(group2)) {
  | (Some(x), Some(y)) => Int.toString(x * y)
  | _ => "???"
  }
}
String.unsafeReplaceRegExpBy2(str, re, matchFn) == "42"

unsafeReplaceRegExpBy3(str, regexp, f). Like unsafeReplaceRegExpBy1, but f has three group parameters. See String.replace on MDN.

search(str, regexp) returns the starting position of the first match of regexp in the given str, or -1 if there is no match. See String.search on MDN.

Examples

RESCRIPT
String.search("testing 1 2 3", %re("/\d+/")) == 8
String.search("no numbers", %re("/\d+/")) == -1

searchOpt(str, regexp). Like search, but return an option<int>.

Examples

RESCRIPT
String.searchOpt("testing 1 2 3", %re("/\d+/")) == Some(8)
String.searchOpt("no numbers", %re("/\d+/")) == None

slice(str, ~start, ~end) returns the substring of str starting at character start up to but not including end.

• If either start or end is negative, then it is evaluated as length(str - start) or length(str - end).

• If end is greater than the length of str, then it is treated as length(str).

• If start is greater than end, slice returns the empty string. See String.slice on MDN.

Examples

RESCRIPT
String.slice("abcdefg", ~start=2, ~end=5) == "cde"
String.slice("abcdefg", ~start=2, ~end=9) == "cdefg"
String.slice("abcdefg", ~start=-4, ~end=-2) == "de"
String.slice("abcdefg", ~start=5, ~end=1) == ""

sliceToEnd(str, ~start) returns the substring of str starting at character start to the end of the string.

• If start is negative, then it is evaluated as length(str - start).

• If start is greater than the length of str, then sliceToEnd returns the empty string. See String.slice on MDN.

Examples

RESCRIPT
String.sliceToEnd("abcdefg", ~start=4) == "efg"
String.sliceToEnd("abcdefg", ~start=-2) == "fg"
String.sliceToEnd("abcdefg", ~start=7) == ""

split(str, delimiter) splits the given str at every occurrence of delimiter and returns an array of the resulting substrings. See String.split on MDN.

Examples

RESCRIPT
String.split("2018-01-02", "-") == ["2018", "01", "02"]
String.split("a,b,,c", ",") == ["a", "b", "", "c"]
String.split("good::bad as great::awful", "::") == ["good", "bad as great", "awful"]
String.split("has-no-delimiter", ";") == ["has-no-delimiter"]

splitAtMost(str, delimiter, ~limit) splits the given str at every occurrence of delimiter and returns an array of the first limit resulting substrings. If limit is negative or greater than the number of substrings, the array will contain all the substrings.

Examples

RESCRIPT
String.splitAtMost("ant/bee/cat/dog/elk", "/", ~limit=3) == ["ant", "bee", "cat"]
String.splitAtMost("ant/bee/cat/dog/elk", "/", ~limit=0) == []
String.splitAtMost("ant/bee/cat/dog/elk", "/", ~limit=9) == ["ant", "bee", "cat", "dog", "elk"]

splitByRegExp(str, regexp) splits the given str at every occurrence of regexp and returns an array of the resulting substrings. See String.split on MDN.

Examples

RESCRIPT
String.splitByRegExp("Jan,Feb,Mar", %re("/,/")) == [Some("Jan"), Some("Feb"), Some("Mar")]

splitByRegExpAtMost(str, regexp, ~limit) splits the given str at every occurrence of regexp and returns an array of the first limit resulting substrings. If limit is negative or greater than the number of substrings, the array will contain all the substrings. See String.split on MDN.

Examples

RESCRIPT
String.splitByRegExpAtMost("Hello World. How are you doing?", %re("/ /"), ~limit=3) == [
  Some("Hello"),
  Some("World."),
  Some("How"),
]

startsWith(str, substr) returns true if the str starts with substr, false otherwise. See String.startsWith on MDN.

Examples

RESCRIPT
String.startsWith("BuckleScript", "Buckle") == true
String.startsWith("BuckleScript", "") == true
String.startsWith("JavaScript", "Buckle") == false

startsWithFrom(str, substr, n) returns true if the str starts with substr starting at position n, false otherwise. If n is negative, the search starts at the beginning of str. See String.startsWith on MDN.

Examples

RESCRIPT
String.startsWithFrom("BuckleScript", "kle", 3) == true
String.startsWithFrom("BuckleScript", "", 3) == true
String.startsWithFrom("JavaScript", "Buckle", 2) == false

substring(str, ~start, ~end) returns characters start up to but not including end from str.

• If start is less than zero, it is treated as zero.

• If end is zero or negative, the empty string is returned.

• If start is greater than end, the start and end points are swapped. See String.substring on MDN.

Examples

RESCRIPT
String.substring("playground", ~start=3, ~end=6) == "ygr"
String.substring("playground", ~start=6, ~end=3) == "ygr"
String.substring("playground", ~start=4, ~end=12) == "ground"

substringToEnd(str, ~start) returns the substring of str from position start to the end.

• If start is less than or equal to zero, the entire string is returned.

• If start is greater than or equal to the length of str, the empty string is returned. See String.substring on MDN.

Examples

RESCRIPT
String.substringToEnd("playground", ~start=4) == "ground"
String.substringToEnd("playground", ~start=-3) == "playground"
String.substringToEnd("playground", ~start=12) == ""

toLowerCase(str) converts str to lower case using the locale-insensitive case mappings in the Unicode Character Database. Notice that the conversion can give different results depending upon context, for example with the Greek letter sigma, which has two different lower case forms, one when it is the last character in a string and another when it is not. See String.toLowerCase on MDN.

Examples

RESCRIPT
String.toLowerCase("ABC") == "abc"
String.toLowerCase(`ΣΠ`) == `σπ`
String.toLowerCase(`ΠΣ`) == `πς`

toLocaleLowerCase(str) converts str to lower case using the current locale. See String.toLocaleLowerCase on MDN.

toUpperCase(str) converts str to upper case using the locale-insensitive case mappings in the Unicode Character Database. Notice that the conversion can expand the number of letters in the result, for example the German ß capitalizes to two Ses in a row. See String.toUpperCase on MDN.

Examples

RESCRIPT
String.toUpperCase("abc") == "ABC"
String.toUpperCase(`Straße`) == `STRASSE`
String.toUpperCase(`πς`) == `ΠΣ`

toLocaleUpperCase(str) converts str to upper case using the current locale. See String.toLocaleUpperCase on MDN.

trim(str) returns a string that is str with whitespace stripped from both ends. Internal whitespace is not removed. See String.trim on MDN.

Examples

RESCRIPT
String.trim("   abc def   ") == "abc def"
String.trim("\n\r\t abc def \n\n\t\r ") == "abc def"

trimStart(str) returns a string that is str with whitespace stripped from the beginning of a string. Internal whitespace is not removed. See String.trimStart on MDN.

Examples

RESCRIPT
String.trimStart("   Hello world!   ") == "Hello world!   "
String.trimStart("   Hello   world!   ") == "Hello   world!   "

trinEnd(str) returns a string that is str with whitespace stripped from the end of a string. Internal whitespace is not removed. See String.trimEnd on MDN.

Examples

RESCRIPT
String.trimEnd("   Hello world!   ") == "   Hello world!"
String.trimEnd("   Hello   world!   ") == "   Hello   world!"

padStart(str, n, padStr) returns a string that has been padded with padStr (multiple times, if needed) until the resulting string reaches the given n length. The padding is applied from the start of the current string. See String.padStart on MDN.

Examples

RESCRIPT
String.padStart("abc", 5, " ") == "  abc"
String.padStart("abc", 6, "123465") == "123abc"

padEnd(str, n, padStr) returns a string that has been padded with padStr (multiple times, if needed) until the resulting string reaches the given n length. The padding is applied from the end of the current string. See String.padEnd on MDN.

Examples

RESCRIPT
String.padEnd("Hello", 10, ".") == "Hello....."
String.padEnd("abc", 1, "") == "abc"

localeCompare(referenceStr, compareStr) returns a float than indicatings whether a reference string comes before or after, or is the same as the given string in sort order. If referenceStr occurs before compareStr positive if the referenceStr occurs after compareStr, 0 if they are equivalent. Do not rely on exact return values of -1 or 1 See String.localeCompare on MDN.

Examples

RESCRIPT
String.localeCompare("a", "c") < 0.0 == true
String.localeCompare("a", "a") == 0.0