Module `Relude_String`

type t = string;

let empty: string;: String.empty is the empty string value "".

let length: string => int;

String.length returns the length of the string. Since this function calls the JavaScript String.length function, it works properly with Unicode characters.

String.length("example") == 7;
String.length({js|Glück|js}) == 5;
String.length({js|대한민국|js}) == 4;

let isEmpty: string => bool;: String.isEmpty returns true if the provided string is the empty string "", and returns false otherwise.

let isNonEmpty: string => bool;: isNotEmpty(str) returns true if str is not the empty string ""; false if it is empty.

let isNotEmpty: string => bool;: Alias for isNonEmpty

let toNonEmpty: string => option(string);

toNonEmpty(str) returns Some(str) if str is not the empty string "". It returns None if str is the empty string.

toNonEmpty("abc") == Some("abc");
toNonEmpty("") == None;

let trim: string => string;

trim(str) returns a new string with leading and trailing whitespace (blank, tab, newline, non-breaking space and others as described in <https://www.ecma-international.org/ecma-262/5.1/#sec-7.2>) removed from s.

trim("  abc  ") == "abc";
trim("  abc def  ") == "abc def";
trim({js|\n\u00a0 \t abc \f\r \t|js}) == "abc";

let isWhitespace: string => bool;

isWhitespace(str) returns true if the string consists entirely of whitespace characters as described in <https://www.ecma-international.org/ecma-262/5.1/#sec-7.2>

isWhitespace(" \n \t \r  ") == true;
isWhitespace(" \n \t X \r ") == false;

let isNonWhitespace: string => bool;: Indicates if the string contains any non-whitespace characters

let toNonWhitespace: string => option(string);

toNonWhiteSpace(str) returns Some(str) if str has any non-whitespace characters in it. The function returns None if str consists entirely of whitespace.

toNonWhitespace("\n\t abc \t\r") == Some("\n\t abc \t\r");
toNonWhitespace("\t\n  \r") == None;

let concat: string => string => string;

concat(str1, str2) concatenate the two strings, returning a new string.

concat("door", "bell") == "doorbell";
concat("", "next") == "next";
concat("first", "") == "first";

module Semigroup: BsBastet.Interface.SEMIGROUP with type Semigroup.t = string;

include { ... };

let concatNamed: prefix:Semigroup.t => Semigroup.t => Semigroup.t;

module Monoid: BsBastet.Interface.MONOID with type Monoid.t = string;

include { ... };

module BsMonoidExtensions: { ... };

let guard: bool => Monoid.t => Monoid.t;
let power: Monoid.t => int => Monoid.t;

let concatArray: array(string) => string;

concatArray(xs) returns a new string that is the result of concatenating all the strings in xs.

concatArray([|"cat", "en", "ate"|]) == "catenate";
concatArray([|"chair", "", "person"|]) == "chairperson";
concatArray([| |]) == "";

let concatList: list(string) => string;: String.concatList is the list version of concatArray.

let make: 'a => string;

make(x) converts x to a string. If x is not a primitive type such as integer, float, string, or boolean, the result will reflect ReasonML’s internal format for that data type.

make(32.5) == "32.5";
make(1.0e3) == "1000";
make(true) == "true";
make("already a string") == "already a string";
make([1, 2, 3, 4]) == "1,2,3,4,0";
make([|1, 2, 3, 4|]) == "1,2,3,4";

let makeWithIndex: int => (int => string) => string;

makeWithIndex(n, f) returns a string that is the result of concatenating f(0), f(1), ... f(n - 1), where function f() takes an integer argument and returns a string.

let squareChar = (n) => {fromCharCode(97 + n * n)};
makeWithIndex(4, squareChar) == "abej";

let repeat: int => string => string;

repeat(n, str) returns a string consisting of n repetitions of str.

repeat(3, "ha") == "hahaha";
repeat(0, "ha") == "";
repeat(-1, "ha") == "";
repeat(3, "") == "";

let toUpperCase: string => string;

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 "S"es in a row.

toUpperCase("abc") == "ABC";
toUpperCase({js|Straße|js}) == {js|STRASSE|js};
toUpperCase({js|σπ|js}) == {js|ΣΠ|js};
toUpperCase({js|πς|js}) == {js|ΠΣ|js}; // sigma in final position

let toLowerCase: string => string;

toLowerCase(str) converts str to lower case using the locale-insensitive case mappings in the Unicode Character Database.

Note that the conversion might not lessen the number of letters in the result; for example, in some German words, two "S"es in a row can convert to the single lowercase glyph ß, but toLowerCase() will not do this transformation.

toLowerCase("ABC") == "abc";
toLowerCase({js|STRASSE|js}) == {js|strasse|js};
toLowerCase({js|ΣΠ|js}) == {js|σπ|js};
toLowerCase({js|ΠΣ|js}) == {js|πς|js}; // sigma in final position

let fromCharCode: int => string;

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

fromCharCode(65) == "A";
fromCharCode(0x0920) == {js|ठ|js};
fromCharCode(0x3c8) == {js|ψ|js};
fromCharCode(-64568) == {js|ψ|js};

let charCodeAt: int => string => option(int);

charCodeAt(n, str) returns (optionally) the numeric character code at the given 0-based position in a string. If the provided position is out of the range of the size of the string (too high or negative), None is returned.

charCodeAt(0, "abc") == Some(97);
charCodeAt(-1, "abc") == None;
charCodeAt(0, "") == None;

let charAt: int => string => option(string);

charAt(n, str) returns Some(chStr), where chStr is a string consisting of the character at location n in the string. The first character in a string has position zero.

If n is out of bounds, charAt() returns None.

charAt(0, "abc") == Some("a");
charAt(2, "abc") == Some("c");
charAt(1, {js|대한민국|js}) == Some({js|한|js});
charAt(-1, "abc") == None;
charAt(3, "abc") == None;

let charAtOrEmpty: int => string => string;

charAtOrEmpty(n, str) returns the string containing the character at the given index or the empty string if the index is out of range.

charAtOrEmpty(0, "abc") == "a";
charAtOrEmpty(0, "") == "";
charAtOrEmpty(2, "a") == "";
charAtOrEmpty(-1, "abc") == "";

let charAtNullable: int => string => Js.Nullable.t(string);

charAtNullable(n, str) returns Js.Nullable.return(chStr), where chStr is a string consisting of the character at location n in the string. The first character in a string has position zero.

If n is out of bounds, charAtNullable() returns Js.Nullable.undefined.

charAtNullable(0, "abc") == Js.Nullable.return("a");
charAtNullable(2, "abc") == Js.Nullable.return("c");
charAtNullable(1, {js|대한민국|js}) == Js.Nullable.return({js|한|js});
charAtNullable(-1, "abc") == Js.Nullable.undefined;
charAtNullable(3, "abc") == Js.Nullable.undefined;

let charAtOrThrow: int => string => string;

charAtOrThrow(n, str) returns a string consisting of the character at location n in the string. The first character in a string has position zero.

If n is out of bounds, charAtOrThrow() throws a RangeError.

charAtOrThrow(0, "abc") == "a";
charAtOrThrow(2, "abc") == "c";
charAtOrThrow(1, {js|대한민국|js}) == {js|한|js};
try (charAtOrThrow(-1, "abc")) {
  | Js.Exn.Error(_) => "Invalid index"
} == "Invalid index";

let toList: string => list(string);

toList(str) creates a list with one character of str per element.

toList("abc") == ["a", "b", "c"];
toList({js|日本|js}) == [{js|日|js}, {js|本|js}];
toList("") == [];

let toArray: string => array(string);

toArray(str) creates an array with one character of str per element.

toArray("abc") == [|"a", "b", "c"|];
toArray({js|日本|js}) == [|{js|日|js}, {js|本|js}|];
toArray("") == [| |];

let foldLeft: ('b => string => 'b) => 'b => string => 'b;

In foldLeft(f, init, str), f() is a function that takes an accumulated value and a string as its arguments. foldLeft starts with init as the value of an accumulator. It then calls f repeatedly with each character in the string, moving from left to right, with the result f(accumulator, chStr) becoming the new value of the accumulator. When all characters have been processed, the return value is the value of the accumulator.

let valueOfChar = (chStr) => {int_of_float(Js.String.charCodeAt(0, chStr))};
foldLeft( (acc, chStr) => {acc + valueOfChar(chStr)}, 0, "abc") == 97 + 98 + 99;
foldLeft( (acc, chStr) => {acc ++ "-" ++ chStr}, "", "abc") == "-a-b-c";

let foldRight: (string => 'b => 'b) => 'b => string => 'b;

In foldRight(f, init, str), f() is a function that takes a string and an accumulator as its arguments. foldRight starts with init as the value of an accumulator. It then calls f repeatedly with each character in the string, moving from right to left, with the result f(chStr, accumulator) becoming the new value of the accumulator. When all characters have been processed, the return value is the value of the accumulator.

let valueOfChar = (chStr) => {int_of_float(Js.String.charCodeAt(0, chStr))};
foldRight( (chStr, acc) => {acc + valueOfChar(chStr)}, 0, "abc") == 97 + 98 + 99;
foldRight( (chStr, acc) => {acc ++ "-" ++ chStr}, "", "abc") == "-c-b-a";

let show: string => string;: Show function for string (identity)

module Show: BsBastet.Interface.SHOW with type Show.t = string;: SHOW module for string

let eq: string => string => bool;: eq(s1, s2) is a synonym for s1 == s2

module Eq: BsBastet.Interface.EQ with type Eq.t = string;

include { ... };

let eqWithConversion: ('b => Eq.t) => Relude_Eq.eq('b);
let notEq: Relude_Eq.eq(Eq.t);
let eqInverted: Relude_Eq.eq(Eq.t);

module EqInverted: { ... };

module type EQ_BY_F = (A: { ... }) => { ... };

module EqBy: (A: { ... }) => { ... };

let compare: BsBastet.String.Ord.t => BsBastet.String.Ord.t => BsBastet.Interface.ordering;: Compares two strings

module Ord: BsBastet.Interface.ORD with type Ord.t = string;

include { ... };

let compareWithConversion: ('b => Ord.t) => Relude_Ord.compare('b);
let compareReversed: Relude_Ord.compare(Ord.t);

module OrdReversed: { ... };

let compareAsInt: Ord.t => Ord.t => int;
let min: Ord.t => Ord.t => Ord.t;
let max: Ord.t => Ord.t => Ord.t;
let lessThan: Ord.t => Ord.t => bool;
let lt: Ord.t => Ord.t => bool;
let lessThanOrEq: Ord.t => Ord.t => bool;
let lte: Ord.t => Ord.t => bool;
let greaterThan: Ord.t => Ord.t => bool;
let gt: Ord.t => Ord.t => bool;
let greaterThanOrEq: Ord.t => Ord.t => bool;
let gte: Ord.t => Ord.t => bool;
let clamp: min:Ord.t => max:Ord.t => Ord.t => Ord.t;
let between: min:Ord.t => max:Ord.t => Ord.t => bool;

module OrdRingExtensions: (R: { ... }) => { ... };

module OrdNamed: { ... };

module type ORD_BY_F = (A: { ... }) => { ... };

module OrdBy: (A: { ... }) => { ... };

module Map: { ... };: Map module with a string key

module Set: { ... };: Set module for strings

let endsWith: search:string => string => bool;

endsWith(~search, input) returns true if input ends with the characters in target; false otherwise.

endsWith(~search="ing", "programming") == true;
endsWith(~search="ing", "program") == false;
endsWith(~search="ing", "in") == false;
endsWith(~search="", "everything") == true;

let startsWith: search:string => string => bool;

startsWith(~search, input) returns true if input starts with the characters in search; false otherwise.

startsWith(~search="pro", "programming") == true;
startsWith(~search="pre", "program") == false;
startsWith(~search="pre", "pr") == false;
startsWith(~search="", "everything") == true;

let contains: search:string => string => bool;

contains(~search, input) returns true if search appears anywhere in input; false otherwise.

contains(~search="cat", "catalog") == true;
contains(~search="cat", "scatter") == true;
contains(~search="log", "catalog") == true;
contains(~search="ato", "fraction") == false;

let indexOf: search:string => string => option(int);

indexOf(test, str) returns Some(n), where n is the starting position of the first occurrence of test within str. If test is not in str, the return value is None.

indexOf("cat", "catalog") == Some(0);
indexOf("cat", "scatter") == Some(1);
indexOf("in", "stringing") == Some(3);
indexOf("xyz", "blah") == None;

let lastIndexOf: search:string => string => option(int);

lastIndexOf(test, str) returns Some(n), where n is the starting position of the last occurrence of test within str. If test is not in str, the return value is false.

lastIndexOf("cat", "catalog") == Some(0);
lastIndexOf("cat", "scatter") == Some(1);
lastIndexOf("in", "stringing") == Some(6);
lastIndexOf("xyz", "blah") == None;

let slice: int => int => string => string;

slice(n1, n2, str) returns the substring of str starting at character n1 up to but not including n2.

If either n1 or n2 is negative, then it is evaluated as length(str) - n1 (or length(str) - n2).

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

If n1 is greater than n2, slice() returns the empty string.

slice(2, 5, "abcdefg") == "cde";
slice(2, 9, "abcdefg") == "cdefg";
slice(-4, -2, "abcdefg") == "de";
slice(5, 1, "abcdefg") == "";

let sliceToEnd: int => string => string;

sliceToEnd(n, str) returns the substring of str starting at character n to the end of the string

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

If n is greater than the length of str, then sliceToEnd() returns the empty string.

sliceToEnd(4, "abcdefg") == "efg";
sliceToEnd(-2, "abcdefg") == "fg";
sliceToEnd(7, "abcdefg") == "";

let splitArray: delimiter:string => string => array(string);

splitArray(delimiter, str) splits the given str at every occurrence of delimiter and returns an array of the resulting substrings.

splitArray("-", "2019-01-02") == [|"2019", "01", "02"|];
splitArray(",", "a,b,,c") == [|"a", "b", "", "c"|];
splitArray("::", "good::better::best") == [|"good", "better", "best"|];
splitArray(";", "has-no-delimiter") == [|"has-no-delimiter"|];

let splitAsArray: delimiter:string => string => array(string);: String.splitAsArray is an alias for splitArray.

let splitList: delimiter:string => string => list(string);

splitList(delimiter, str) splits the given str at every occurrence of delimiter and returns a list of the resulting substrings.

splitList("-", "2019-01-02") == ["2019", "01", "02"];
splitList(",", "a,b,,c") == ["a", "b", "", "c"];
splitList("::", "good::better::best") == ["good", "better", "best"];
splitList(";", "has-no-delimiter") == ["has-no-delimiter"];

let splitAsList: delimiter:string => string => list(string);: String.splitAsList is an alias for splitList.

let splitAt: int => string => (string, string);

splitAt(index, str) splits the string at the given index, returning a tuple of the parts. If index is negative, it is evaluated as length(str) - index.

splitAt(4, "abcdefg") == ("abcd", "efg");
splitAt(0, "abcdefg") == ("", "abcdefg");
splitAt(7, "abcdefg") == ("abcdefg", "");
splitAt(8, "abcdefg") == ("abcdefg", "");
splitAt(-3, "abcdefg") == ("abcd", "efg");
splitAt(-9, "abcdefg") == ("", "abcdefg");

let mapChars: (string => string) => string => string;

mapChars(f, str) applies the function f() to each character of the string, returning a new string.

let duplicate = (ch) => {ch ++ ch};
mapChars(duplicate, "abcde") == "aabbccddee";
let capsOnly = (ch) => {(ch >= "A" && ch <= "Z") ? ch : ""};
mapChars(capsOnly, "AbCdE") == "ACE";

let padStart: targetLength:int => ?⁠padWith:string => string => string;: Pads the string to targetLength using padWith as a repeated padding on the left side of the input string

let padEnd: targetLength:int => ?⁠padWith:string => string => string;: Pads the string to targetLength using padWith as a repeated padding on the right side of the input string

let replaceFirst: search:string => replaceWith:string => string => string;

replaceFirst(target, newValue, str) replaces the first occurrence of target with newValue in str, returning a new string.

replaceFirst("in", "t", "the rain in spain") == "the rat in spain";
replaceFirst("in", "t", "playground") == "playground";

let replaceEach: search:string => replaceWith:string => string => string;

replaceEach(target, newValue, str)replaces each occurrence of target with newValue in str, returning a new string.

replaceEach("in", "t", "the rain in spain") == "the rat t spat";
replaceEach("in", "t", "playground") == "playground";

let replaceRegex: search:Js.Re.t => replaceWith:string => string => string;

replaceRegex(targetRe, newValue, str) replaces the matched regular expression targetRe with newValue in str, returning a new string.

If you use parentheses to store matching substrings in your pattern (as in the last two examples), you may refer to them as $1, $2 etc. in your replacement pattern.

replaceRegex([%re"/b[aeiou]g/"], "---", "The big bog bug") == "The --- bog bug";
replaceRegex([%re"/b[aeiou]g/g"], "---", "The big bog bug") == "The --- --- ---";
replaceRegex([%re"/b([aeiou])g/g"], "$1", "The big bog bug") == "The i o u";
replaceRegex([%re"/(\\w+)\\s+(\\w+)/"], "$2, $1", "Clyde Tolson") == "Tolson, Clyde";

let removeFirst: search:string => string => string;

removeFirst(target, str) returns a new string with the first occurrence of target removed from str.

removeFirst("the ", "Paris in the the spring") == "Paris in the spring";
removeFirst("the ", "ReasonML is cool") == "ReasonML is cool";

let removeEach: search:string => string => string;

removeEach(target, str) returns a new string with every occurrence of target removed from str.

removeEach("the ", "Paris in the the spring") == "Paris in spring";
removeEach("the ", "ReasonML is cool") == "ReasonML is cool";

let fromInt: int => string;: fromInt(n) returns n as a string. This function is a synonym for the built-in string_of_int().

let toInt: string => option(int);

toInt(str) returns Some(n) if str is a valid string representation of the integer n. Otherwise, the return value is None.

toInt("42") == Some(42);
toInt("42.3") == None;
toInt("four") == None;
toInt("") == None;

let fromFloat: float => string;

fromFloat(x) converts the value to a string representation. Note that, as in the last examples, it may not be exactly the same as the representation you used when specifying x.

fromFloat(-3.5) == "-3.5";
fromFloat(6.02E23) == "6.02e+23";
fromFloat(1.0e3) == "1000";

let toFloat: string => option(float);

toFloat(str) returns Some(x) if str is a valid string representation of the float value x. Otherwise, the return value is None.

toFloat("42") == Some(42.0);
toFloat("42.3") == Some(42.3);
toFloat("123400000") == Some(123400000.0);
toFloat("four") == None;
toFloat("") == None;