@tellahq/rescript 10.1.0-alpha.1

package/lib/ocaml/js_string2.ml

@@ -0,0 +1,912 @@
+(* Copyright (C) 2015-2016 Bloomberg Finance L.P.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * In addition to the permissions granted to you by the LGPL, you may combine
+ * or link a "work that uses the Library" with a publicly distributed version
+ * of this file to produce a combined library or application, then distribute
+ * that combined work under the terms of your choosing, with no requirement
+ * to comply with the obligations normally placed on you by section 4 of the
+ * LGPL version 3 (or the corresponding section of a later version of the LGPL
+ * should you choose to use a later version).
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
+
+(** Provide bindings to JS string. Optimized for pipe-first. *)
+
+type t = string
+
+external make : 'a -> t = "String"
+  [@@bs.val]
+(**
+`make(value)` converts the given value to a `string`.
+
+```res example
+Js.String2.make(3.5) == "3.5"
+Js.String2.make([1, 2, 3]) == "1,2,3"
+```
+*)
+
+external fromCharCode : int -> t = "String.fromCharCode"
+  [@@bs.val]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCharCode)
+on MDN.
+
+```res example
+Js.String2.fromCharCode(65) == "A"
+Js.String2.fromCharCode(0x3c8) == `ψ`
+Js.String2.fromCharCode(0xd55c) == `한`
+Js.String2.fromCharCode(-64568) == `ψ`
+```
+*)
+
+external fromCharCodeMany : int array -> t = "String.fromCharCode"
+  [@@bs.val] [@@bs.splice]
+(**
+`fromCharCodeMany([n1, n2, n3])` creates a `string` from the characters
+corresponding to the given numbers, using the same rules as `fromCharCode`.
+
+See [`String.fromCharCode`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCharCode)
+on MDN.
+*)
+
+external fromCodePoint : int -> t = "String.fromCodePoint"
+  [@@bs.val]
+(**
+`fromCodePoint(n)` creates a `string` containing the character corresponding to
+that numeric code point. If the number is not a valid code point, it raises
+`RangeError`. Thus, `fromCodePoint(0x1F63A)` will produce a correct value,
+unlike `fromCharCode(0x1F63A)`, and `fromCodePoint(-5)` will raise a
+`RangeError`.
+
+See [`String.fromCodePoint`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint)
+on MDN.
+
+```res example
+Js.String2.fromCodePoint(65) == "A"
+Js.String2.fromCodePoint(0x3c8) == `ψ`
+Js.String2.fromCodePoint(0xd55c) == `한`
+Js.String2.fromCodePoint(0x1f63a) == `😺`
+```
+*)
+
+external fromCodePointMany : int array -> t = "String.fromCodePoint"
+  [@@bs.val] [@@bs.splice]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint)
+on MDN.
+
+```res example
+Js.String2.fromCodePointMany([0xd55c, 0xae00, 0x1f63a]) == `한글😺`
+```
+*)
+
+(* String.raw: ES2015, meant to be used with template strings, not directly *)
+
+external length : t -> int = "length"
+  [@@bs.get]
+(**
+`length(s)` returns the length of the given `string`.
+
+See [`String.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length)
+on MDN.
+
+```res example
+Js.String2.length("abcd") == 4
+```
+*)
+
+external get : t -> int -> t = ""
+  [@@bs.get_index]
+(**
+`get(s, n)` returns as a `string` the character at the given index number. If
+`n` is out of range, this function returns `undefined`,so at some point this
+function may be modified to return `option(string)`.
+
+```res example
+Js.String2.get("Reason", 0) == "R"
+Js.String2.get("Reason", 4) == "o"
+Js.String2.get(`Rẽasöń`, 5) == `ń`
+```
+*)
+
+external charAt : t -> int -> t = "charAt"
+  [@@bs.send]
+(**
+`charAt(s, n)` gets the character at index `n` within string `s`. If `n` is
+negative or greater than the length of `s`, 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt)
+on MDN.
+
+```res example
+Js.String2.charAt("Reason", 0) == "R"
+Js.String2.charAt("Reason", 12) == ""
+Js.String2.charAt(`Rẽasöń`, 5) == `ń`
+```
+*)
+
+external charCodeAt : t -> int -> float = "charCodeAt"
+  [@@bs.send]
+(**
+`charCodeAt(s, n)` returns the character code at position `n` in string `s`;
+the result is in the range 0-65535, unlke `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 `n` is less than
+zero or greater than the length of the string.
+
+See [`String.charCodeAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charCodeAt)
+on MDN.
+
+```res example
+Js.String2.charCodeAt(`😺`, 0) == 0xd83d->Belt.Int.toFloat
+Js.String2.codePointAt(`😺`, 0) == Some(0x1f63a)
+```
+*)
+
+external codePointAt : t -> int -> int option = "codePointAt"
+  [@@bs.send]
+(**
+`codePointAt(s, n)` returns the code point at position `n` within string `s` 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt)
+on MDN.
+
+```res example
+Js.String2.codePointAt(`¿😺?`, 1) == Some(0x1f63a)
+Js.String2.codePointAt("abc", 5) == None
+```
+*)
+
+external concat : t -> t -> t = "concat"
+  [@@bs.send]
+(**
+`concat(original, append)` returns a new `string` with `append` added after
+`original`.
+
+See [`String.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat)
+on MDN.
+
+```res example
+Js.String2.concat("cow", "bell") == "cowbell"
+```
+*)
+
+external concatMany : t -> t array -> t = "concat"
+  [@@bs.send] [@@bs.splice]
+(**
+`concatMany(original, arr)` returns a new `string` consisting of each item of an
+array of strings added to the `original` string.
+
+See [`String.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/concat)
+on MDN.
+
+```res example
+Js.String2.concatMany("1st", ["2nd", "3rd", "4th"]) == "1st2nd3rd4th"
+```
+*)
+
+external endsWith : t -> t -> bool = "endsWith"
+  [@@bs.send]
+(**
+ES2015: `endsWith(str, substr)` returns `true` if the `str` ends with `substr`,
+`false` otherwise.
+
+See [`String.endsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith)
+on MDN.
+
+```res example
+Js.String2.endsWith("BuckleScript", "Script") == true
+Js.String2.endsWith("BuckleShoes", "Script") == false
+```
+*)
+
+external endsWithFrom : t -> t -> int -> bool = "endsWith"
+  [@@bs.send]
+(**
+`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`. (Honestly, this should
+have been named endsWithAt, but oh well).
+
+See [`String.endsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith)
+on MDN.
+
+```res example
+Js.String2.endsWithFrom("abcd", "cd", 4) == true
+Js.String2.endsWithFrom("abcde", "cd", 3) == false
+Js.String2.endsWithFrom("abcde", "cde", 99) == true
+Js.String2.endsWithFrom("example.dat", "ple", 7) == true
+```
+*)
+
+external includes : t -> t -> bool = "includes"
+  [@@bs.send]
+(**
+ES2015: `includes(str, searchValue)` returns `true` if `searchValue` is found
+anywhere within `str`, false otherwise.
+
+See [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes)
+on MDN.
+
+```res example
+Js.String2.includes("programmer", "gram") == true
+Js.String2.includes("programmer", "er") == true
+Js.String2.includes("programmer", "pro") == true
+Js.String2.includes("programmer.dat", "xyz") == false
+```
+*)
+
+external includesFrom : t -> t -> int -> bool = "includes"
+  [@@bs.send]
+(**
+ES2015: `includes(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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes)
+on MDN.
+
+```res example
+Js.String2.includesFrom("programmer", "gram", 1) == true
+Js.String2.includesFrom("programmer", "gram", 4) == false
+Js.String2.includesFrom(`대한민국`, `한`, 1) == true
+```
+*)
+
+external indexOf : t -> t -> int = "indexOf"
+  [@@bs.send]
+(**
+ES2015: `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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf)
+on MDN.
+
+```res example
+Js.String2.indexOf("bookseller", "ok") == 2
+Js.String2.indexOf("bookseller", "sell") == 4
+Js.String2.indexOf("beekeeper", "ee") == 1
+Js.String2.indexOf("bookseller", "xyz") == -1
+```
+*)
+
+external indexOfFrom : t -> t -> int -> int = "indexOf"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf)
+on MDN.
+
+```res example
+Js.String2.indexOfFrom("bookseller", "ok", 1) == 2
+Js.String2.indexOfFrom("bookseller", "sell", 2) == 4
+Js.String2.indexOfFrom("bookseller", "sell", 5) == -1
+```
+*)
+
+external lastIndexOf : t -> t -> int = "lastIndexOf"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf)
+on MDN.
+
+```res example
+Js.String2.lastIndexOf("bookseller", "ok") == 2
+Js.String2.lastIndexOf("beekeeper", "ee") == 4
+Js.String2.lastIndexOf("abcdefg", "xyz") == -1
+```
+*)
+
+external lastIndexOfFrom : t -> t -> int -> int = "lastIndexOf"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/lastIndexOf)
+on MDN.
+
+```res example
+Js.String2.lastIndexOfFrom("bookseller", "ok", 6) == 2
+Js.String2.lastIndexOfFrom("beekeeper", "ee", 8) == 4
+Js.String2.lastIndexOfFrom("beekeeper", "ee", 3) == 1
+Js.String2.lastIndexOfFrom("abcdefg", "xyz", 4) == -1
+```
+*)
+
+(* extended by ECMA-402 *)
+
+external localeCompare : t -> t -> float = "localeCompare"
+  [@@bs.send]
+(**
+`localeCompare(reference, comparison)` returns
+- a negative value if reference comes before comparison in sort order
+- zero if reference and comparison have the same sort order
+- a positive value if reference comes after comparison in sort order
+
+See [`String.localeCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) on MDN.
+
+```res example
+Js.String2.localeCompare("zebra", "ant") > 0.0
+Js.String2.localeCompare("ant", "zebra") < 0.0
+Js.String2.localeCompare("cat", "cat") == 0.0
+Js.String2.localeCompare("CAT", "cat") > 0.0
+```
+*)
+
+external match_ : t -> Js_re.t -> t option array option = "match"
+  [@@bs.send] [@@bs.return { null_to_opt }]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+on MDN.
+
+```res example
+Js.String2.match_("The better bats", %re("/b[aeiou]t/")) == Some(["bet"])
+Js.String2.match_("The better bats", %re("/b[aeiou]t/g")) == Some(["bet", "bat"])
+Js.String2.match_("Today is 2018-04-05.", %re("/(\d+)-(\d+)-(\d+)/")) ==
+  Some(["2018-04-05", "2018", "04", "05"])
+Js.String2.match_("The large container.", %re("/b[aeiou]g/")) == None
+```
+*)
+
+external normalize : t -> t = "normalize"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize)
+on MDN. See also [Unicode technical report
+#15](https://unicode.org/reports/tr15/) for details.
+*)
+
+external normalizeByForm : t -> t -> t = "normalize"
+  [@@bs.send]
+(**
+ES2015: `normalize(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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) on MDN.
+See also [Unicode technical report #15](https://unicode.org/reports/tr15/) for details.
+*)
+
+external repeat : t -> int -> t = "repeat"
+  [@@bs.send]
+(**
+`repeat(str, n)` returns a `string` that consists of `n` repetitions of `str`.
+Raises `RangeError` if `n` is negative.
+
+See [`String.repeat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat)
+on MDN.
+
+```res example
+Js.String2.repeat("ha", 3) == "hahaha"
+Js.String2.repeat("empty", 0) == ""
+```
+*)
+
+external replace : t -> t -> t -> t = "replace"
+  [@@bs.send]
+(**
+ES2015: `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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+on MDN.
+
+```res example
+Js.String2.replace("old string", "old", "new") == "new string"
+Js.String2.replace("the cat and the dog", "the", "this") == "this cat and the dog"
+```
+*)
+
+external replaceByRe : t -> Js_re.t -> t -> t = "replace"
+  [@@bs.send]
+(**
+`replaceByRe(str, regex, replacement)` returns a new `string` where occurrences
+matching regex have been replaced by `replacement`.
+
+See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+on MDN.
+
+```res example
+Js.String2.replaceByRe("vowels be gone", %re("/[aeiou]/g"), "x") == "vxwxls bx gxnx"
+Js.String2.replaceByRe("Juan Fulano", %re("/(\w+) (\w+)/"), "$2, $1") == "Fulano, Juan"
+```
+*)
+
+external unsafeReplaceBy0 :
+  t -> Js_re.t -> ((t -> int -> t -> t)[@bs.uncurry]) -> t = "replace"
+  [@@bs.send]
+(**
+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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+on MDN.
+
+```res example
+let str = "beautiful vowels"
+let re = %re("/[aeiou]/g")
+let matchFn = (matchPart, _offset, _wholeString) => Js.String2.toUpperCase(matchPart)
+
+Js.String2.unsafeReplaceBy0(str, re, matchFn) == "bEAUtIfUl vOwEls"
+```
+*)
+
+external unsafeReplaceBy1 :
+  t -> Js_re.t -> ((t -> t -> int -> t -> t)[@bs.uncurry]) -> t = "replace"
+  [@@bs.send]
+(**
+Returns a new `string` with some or all matches of a pattern with one set of
+capturing parentheses replaced by the value returned from the given function.
+The function receives as its parameters the matched string, the captured
+string, the offset at which the match begins, and the whole string being
+matched.
+
+See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+on MDN.
+
+```res example
+let str = "Jony is 40"
+let re = %re("/(Jony is )\d+/g")
+let matchFn = (_match, part1, _offset, _wholeString) => {
+  part1 ++ "41"
+}
+
+Js.String2.unsafeReplaceBy1(str, re, matchFn) == "Jony is 41"
+```
+*)
+
+external unsafeReplaceBy2 :
+  t -> Js_re.t -> ((t -> t -> t -> int -> t -> t)[@bs.uncurry]) -> t = "replace"
+  [@@bs.send]
+(**
+Returns a new `string` with some or all matches of a pattern with two sets of
+capturing parentheses replaced by the value returned from the given function.
+The function receives as its parameters the matched string, the captured
+strings, the offset at which the match begins, and the whole string being
+matched.
+
+See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+on MDN.
+
+```res example
+let str = "7 times 6"
+let re = %re("/(\d+) times (\d+)/")
+let matchFn = (_match, p1, p2, _offset, _wholeString) => {
+  switch (Belt.Int.fromString(p1), Belt.Int.fromString(p2)) {
+  | (Some(x), Some(y)) => Belt.Int.toString(x * y)
+  | _ => "???"
+  }
+}
+
+Js.String2.unsafeReplaceBy2(str, re, matchFn) == "42"
+```
+*)
+
+external unsafeReplaceBy3 :
+  t -> Js_re.t -> ((t -> t -> t -> t -> int -> t -> t)[@bs.uncurry]) -> t
+  = "replace"
+  [@@bs.send]
+(**
+Returns a new `string` with some or all matches of a pattern with three sets of
+capturing parentheses replaced by the value returned from the given function.
+The function receives as its parameters the matched string, the captured
+strings, the offset at which the match begins, and the whole string being
+matched.
+
+See [`String.replace`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)
+on MDN.
+*)
+
+external search : t -> Js_re.t -> int = "search"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search)
+on MDN.
+
+```res example
+Js.String2.search("testing 1 2 3", %re("/\d+/")) == 8
+Js.String2.search("no numbers", %re("/\d+/")) == -1
+```
+*)
+
+external slice : t -> from:int -> to_:int -> t = "slice"
+  [@@bs.send]
+(**
+`slice(str, from:n1, to_:n2)` 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.
+
+See [`String.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) on MDN.
+
+```res example
+Js.String2.slice("abcdefg", ~from=2, ~to_=5) == "cde"
+Js.String2.slice("abcdefg", ~from=2, ~to_=9) == "cdefg"
+Js.String2.slice("abcdefg", ~from=-4, ~to_=-2) == "de"
+Js.String2.slice("abcdefg", ~from=5, ~to_=1) == ""
+```
+*)
+
+external sliceToEnd : t -> from:int -> t = "slice"
+  [@@bs.send]
+(**
+`sliceToEnd(str, from:n)` 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.
+
+See [`String.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice) on MDN.
+
+```res example
+Js.String2.sliceToEnd("abcdefg", ~from=4) == "efg"
+Js.String2.sliceToEnd("abcdefg", ~from=-2) == "fg"
+Js.String2.sliceToEnd("abcdefg", ~from=7) == ""
+```
+*)
+
+external split : t -> t -> t array = "split"
+  [@@bs.send]
+(**
+`split(str, delimiter)` splits the given `str` at every occurrence of
+`delimiter` and returns an array of the resulting substrings.
+
+See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+on MDN.
+
+```res example
+Js.String2.split("2018-01-02", "-") == ["2018", "01", "02"]
+Js.String2.split("a,b,,c", ",") == ["a", "b", "", "c"]
+Js.String2.split("good::bad as great::awful", "::") == ["good", "bad as great", "awful"]
+Js.String2.split("has-no-delimiter", ";") == ["has-no-delimiter"]
+```
+*)
+
+external splitAtMost : t -> t -> limit:int -> t array = "split"
+  [@@bs.send]
+(**
+  `splitAtMost delimiter ~limit: n str` splits the given `str` at every occurrence of `delimiter` and returns an array of the first `n` resulting substrings. If `n` is negative or greater than the number of substrings, the array will contain all the substrings.
+
+```
+splitAtMost "ant/bee/cat/dog/elk" "/" ~limit: 3 = [|"ant"; "bee"; "cat"|];;
+splitAtMost "ant/bee/cat/dog/elk" "/" ~limit: 0 = [| |];;
+splitAtMost "ant/bee/cat/dog/elk" "/" ~limit: 9 = [|"ant"; "bee"; "cat"; "dog"; "elk"|];;
+```
+*)
+
+external splitByRe : t -> Js_re.t -> t option array = "split"
+  [@@bs.send]
+(**
+`splitByRe(str, regex)` splits the given `str` at every occurrence of `regex`
+and returns an array of the resulting substrings.
+
+See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+on MDN.
+
+```res example
+Js.String2.splitByRe("art; bed , cog ;dad", %re("/\s*[,;]\s*/")) == [
+    Some("art"),
+    Some("bed"),
+    Some("cog"),
+    Some("dad"),
+  ]
+```
+*)
+
+external splitByReAtMost : t -> Js_re.t -> limit:int -> t option array = "split"
+  [@@bs.send]
+(**
+`splitByReAtMost(str, regex, ~limit:n)` splits the given `str` at every
+occurrence of `regex` and returns an array of the first `n` resulting
+substrings. If `n` is negative or greater than the number of substrings, the
+array will contain all the substrings.
+
+See [`String.split`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+on MDN.
+
+```res example
+Js.String2.splitByReAtMost("one: two: three: four", %re("/\s*:\s*/"), ~limit=3) == [
+    Some("one"),
+    Some("two"),
+    Some("three"),
+  ]
+
+Js.String2.splitByReAtMost("one: two: three: four", %re("/\s*:\s*/"), ~limit=0) == []
+
+Js.String2.splitByReAtMost("one: two: three: four", %re("/\s*:\s*/"), ~limit=8) == [
+    Some("one"),
+    Some("two"),
+    Some("three"),
+    Some("four"),
+  ]
+```
+*)
+
+external startsWith : t -> t -> bool = "startsWith"
+  [@@bs.send]
+(**
+ES2015: `startsWith(str, substr)` returns `true` if the `str` starts with
+`substr`, `false` otherwise.
+
+See [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith)
+on MDN.
+
+```res example
+Js.String2.startsWith("BuckleScript", "Buckle") == true
+Js.String2.startsWith("BuckleScript", "") == true
+Js.String2.startsWith("JavaScript", "Buckle") == false
+```
+*)
+
+external startsWithFrom : t -> t -> int -> bool = "startsWith"
+  [@@bs.send]
+(**
+ES2015: `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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith)
+on MDN.
+
+```res example
+Js.String2.startsWithFrom("BuckleScript", "kle", 3) == true
+Js.String2.startsWithFrom("BuckleScript", "", 3) == true
+Js.String2.startsWithFrom("JavaScript", "Buckle", 2) == false
+```
+*)
+
+external substr : t -> from:int -> t = "substr"
+  [@@bs.send]
+(**
+`substr(str, ~from:n)` returns the substring of `str` from position `n` to the
+end of the string.
+- If `n` is less than zero, the starting position is the length of `str - n`.
+- If `n` is greater than or equal to the length of `str`, returns the empty string.
+
+JavaScript’s `String.substr()` is a legacy function. When possible, use
+`substring()` instead.
+
+See [`String.substr`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr)
+on MDN.
+
+```res example
+Js.String2.substr("abcdefghij", ~from=3) == "defghij"
+Js.String2.substr("abcdefghij", ~from=-3) == "hij"
+Js.String2.substr("abcdefghij", ~from=12) == ""
+```
+*)
+
+external substrAtMost : t -> from:int -> length:int -> t = "substr"
+  [@@bs.send]
+(**
+`substrAtMost(str, ~from: pos, ~length: n)` returns the substring of `str` of
+length `n` starting at position `pos`.
+- If `pos` is less than zero, the starting position is the length of `str - pos`.
+- If `pos` is greater than or equal to the length of `str`, returns the empty string.
+- If `n` is less than or equal to zero, returns the empty string.
+
+JavaScript’s `String.substr()` is a legacy function. When possible, use
+`substring()` instead.
+
+See [`String.substr`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substr)
+on MDN.
+
+```res example
+Js.String2.substrAtMost("abcdefghij", ~from=3, ~length=4) == "defg"
+Js.String2.substrAtMost("abcdefghij", ~from=-3, ~length=4) == "hij"
+Js.String2.substrAtMost("abcdefghij", ~from=12, ~length=2) == ""
+```
+*)
+
+external substring : t -> from:int -> to_:int -> t = "substring"
+  [@@bs.send]
+(**
+`substring(str, ~from: start, ~to_: finish)` returns characters `start` up to
+but not including finish from `str`.
+- If `start` is less than zero, it is treated as zero.
+- If `finish` is zero or negative, the empty string is returned.
+- If `start` is greater than `finish`, the `start` and `finish` points are swapped.
+
+See [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN.
+
+```res example
+Js.String2.substring("playground", ~from=3, ~to_=6) == "ygr"
+Js.String2.substring("playground", ~from=6, ~to_=3) == "ygr"
+Js.String2.substring("playground", ~from=4, ~to_=12) == "ground"
+```
+*)
+
+external substringToEnd : t -> from:int -> t = "substring"
+  [@@bs.send]
+(**
+`substringToEnd(str, ~from: 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN.
+
+```res example
+Js.String2.substringToEnd("playground", ~from=4) == "ground"
+Js.String2.substringToEnd("playground", ~from=-3) == "playground"
+Js.String2.substringToEnd("playground", ~from=12) == ""
+```
+*)
+
+external toLowerCase : t -> t = "toLowerCase"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase)
+on MDN.
+
+```res example
+Js.String2.toLowerCase("ABC") == "abc"
+Js.String2.toLowerCase(`ΣΠ`) == `σπ`
+Js.String2.toLowerCase(`ΠΣ`) == `πς`
+```
+*)
+
+external toLocaleLowerCase : t -> t = "toLocaleLowerCase"
+  [@@bs.send]
+(**
+`toLocaleLowerCase(str)` converts `str` to lower case using the current locale.
+See [`String.toLocaleLowerCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleLowerCase)
+on MDN.
+*)
+
+external toUpperCase : t -> t = "toUpperCase"
+  [@@bs.send]
+(**
+`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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase)
+on MDN.
+
+```res example
+Js.String2.toUpperCase("abc") == "ABC"
+Js.String2.toUpperCase(`Straße`) == `STRASSE`
+Js.String2.toUpperCase(`πς`) == `ΠΣ`
+```
+*)
+
+external toLocaleUpperCase : t -> t = "toLocaleUpperCase"
+  [@@bs.send]
+(**
+`toLocaleUpperCase(str)` converts `str` to upper case using the current locale.
+See [`String.to:LocaleUpperCase`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLocaleUpperCase)
+on MDN.
+*)
+
+external trim : t -> t = "trim"
+  [@@bs.send]
+(**
+`trim(str)` returns a string that is `str` with whitespace stripped from both
+ends. Internal whitespace is not removed.
+
+See [`String.trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/trim)
+on MDN.
+
+```res example
+Js.String2.trim("   abc def   ") == "abc def"
+Js.String2.trim("\n\r\t abc def \n\n\t\r ") == "abc def"
+```
+*)
+
+(* HTML wrappers *)
+
+external anchor : t -> t -> t = "anchor"
+  [@@bs.send]
+(**
+`anchor(anchorText, anchorName)` creates a string with an HTML `<a>` element
+with name attribute of `anchorName` and `anchorText` as its content. Please do
+not use this method, as it has been removed from the relevant web standards.
+
+See [`String.anchor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/anchor)
+on MDN.
+
+```res example
+Js.String2.anchor("Page One", "page1") == "<a name=\"page1\">Page One</a>"
+```
+*)
+
+external link : t -> t -> t = "link"
+  [@@bs.send]
+(**
+ES2015: `link(linkText, urlText)` creates a string with an HTML `<a>` element
+with href attribute of `urlText` and `linkText` as its content. Please do not
+use this method, as it has been removed from the relevant web standards. See
+[`String.link`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/link)
+on MDN.
+
+```res example
+Js.String2.link("Go to page two", "page2.html") == "<a href=\"page2.html\">Go to page two</a>"
+```
+*)
+
+(* FIXME: we should not encourage people to use [%identity], better
+    to provide something using [@@bs.val] so that we can track such
+    casting
+*)
+external castToArrayLike : t -> t Js_array2.array_like = "%identity"
+(**
+Casts its argument to an `array_like` entity that can be processed by functions
+such as `Js.Array2.fromMap()`
+
+```res example
+let s = "abcde"
+let arr = Js.Array2.fromMap(Js.String2.castToArrayLike(s), x => x)
+arr == ["a", "b", "c", "d", "e"]
+```
+*)