effect 4.0.1 → 4.0.2

package/src/String.ts

@@ -6,6 +6,7 @@
  * padding, replacement, normalization, safe character access, search helpers
  * that return `Option`, and joining strings through a reducer.
  *
+ * @stability stable
  * @since 2.0.0
  */
 
@@ -37,6 +38,7 @@ import * as Reducer from "./Reducer.ts"
  *
  * @see {@link isString} for checking whether a value is a primitive string
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -54,6 +56,7 @@ export const String = globalThis.String
  * String.isString(1) // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -73,6 +76,7 @@ export const isString: Refinement<unknown, string> = predicate.isString
  * String.Order("apple", "apple") // => 0
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -90,6 +94,7 @@ export const Order: order.Order<string> = order.String
  * String.Equivalence("hello", "world") // => false
  * ```
  *
+ * @stability stable
  * @category instances
  * @since 2.0.0
  */
@@ -111,6 +116,7 @@ export const Equivalence: Equ.Equivalence<string> = Equ.String
  * String.isEmpty(String.empty) // => true
  * ```
  *
+ * @stability stable
  * @category constants
  * @since 2.0.0
  */
@@ -130,6 +136,7 @@ export const empty: "" = "" as const
  * const witness: Result = "helloworld"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -147,6 +154,7 @@ export type Concat<A extends string, B extends string> = `${A}${B}`
  * pipe("hello", String.concat("world")) // => "helloworld"
  * ```
  *
+ * @stability stable
  * @category combining
  * @since 2.0.0
  */
@@ -163,6 +171,7 @@ export const concat: {
    * pipe("hello", String.concat("world")) // => "helloworld"
    * ```
    *
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -179,6 +188,7 @@ export const concat: {
    * pipe("hello", String.concat("world")) // => "helloworld"
    * ```
    *
+   * @stability stable
    * @category combining
    * @since 2.0.0
    */
@@ -197,6 +207,7 @@ export const concat: {
  * String.toUpperCase("hello") // => "HELLO"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -214,6 +225,7 @@ export const toUpperCase = <S extends string>(self: S): Uppercase<S> => self.toU
  * String.toLowerCase("HELLO") // => "hello"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -231,6 +243,7 @@ export const toLowerCase = <T extends string>(self: T): Lowercase<T> => self.toL
  * String.capitalize("hello") // => "Hello"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -252,6 +265,7 @@ export const capitalize = <T extends string>(self: T): Capitalize<T> => {
  * String.uncapitalize("Hello") // => "hello"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -278,6 +292,7 @@ export const uncapitalize = <T extends string>(self: T): Uncapitalize<T> => {
  * pipe("hello world", String.replace("world", "Effect")) // => "hello Effect"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -297,6 +312,7 @@ export const replace = (searchValue: string | RegExp, replaceValue: string) => (
  * const witness: Result = "hello"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -314,6 +330,7 @@ export type Trim<A extends string> = TrimEnd<TrimStart<A>>
  * String.trim("  hello world  ") // => "hello world"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -332,6 +349,7 @@ export const trim = <A extends string>(self: A): Trim<A> => self.trim() as Trim<
  * const witness: Result = "hello"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -349,6 +367,7 @@ export type TrimStart<A extends string> = A extends `${" " | "\n" | "\t" | "\r"}
  * String.trimStart("  hello world") // => "hello world"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -367,6 +386,7 @@ export const trimStart = <A extends string>(self: A): TrimStart<A> => self.trimS
  * const witness: Result = "hello"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -384,6 +404,7 @@ export type TrimEnd<A extends string> = A extends `${infer B}${" " | "\n" | "\t"
  * String.trimEnd("hello world  ") // => "hello world"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -401,6 +422,7 @@ export const trimEnd = <A extends string>(self: A): TrimEnd<A> => self.trimEnd()
  * pipe("hello world", String.slice(0, 5)) // => "hello"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -418,6 +440,7 @@ export const slice = (start?: number, end?: number) => (self: string): string =>
  * String.isEmpty("a") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -435,6 +458,7 @@ export const isEmpty = (self: string): self is "" => self.length === 0
  * String.isNonEmpty("a") // => true
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -451,6 +475,7 @@ export const isNonEmpty = (self: string): boolean => self.length > 0
  * String.length("abc") // => 3
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -469,6 +494,7 @@ export const length = (self: string): number => self.length
  * String.split("hello,world", ",") // => ["hello", "world"]
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -486,6 +512,7 @@ export const split: {
    * String.split("hello,world", ",") // => ["hello", "world"]
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -503,6 +530,7 @@ export const split: {
    * String.split("hello,world", ",") // => ["hello", "world"]
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -525,6 +553,7 @@ export const split: {
  * pipe("hello world", String.includes("foo")) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -543,6 +572,7 @@ export const includes = (searchString: string, position?: number) => (self: stri
  * pipe("hello world", String.startsWith("world")) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -561,6 +591,7 @@ export const startsWith = (searchString: string, position?: number) => (self: st
  * pipe("hello world", String.endsWith("hello")) // => false
  * ```
  *
+ * @stability stable
  * @category predicates
  * @since 2.0.0
  */
@@ -579,6 +610,7 @@ export const endsWith = (searchString: string, position?: number) => (self: stri
  * String.charCodeAt("abc", 4) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -595,6 +627,7 @@ export const charCodeAt: {
    * String.charCodeAt("abc", 4) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -611,6 +644,7 @@ export const charCodeAt: {
    * String.charCodeAt("abc", 4) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -633,6 +667,7 @@ export const charCodeAt: {
  * pipe("abcd", String.substring(1, 3)) // => "bc"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -650,6 +685,7 @@ export const substring = (start: number, end?: number) => (self: string): string
  * pipe("abc", String.at(4)) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -666,6 +702,7 @@ export const at: {
    * pipe("abc", String.at(4)) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -682,6 +719,7 @@ export const at: {
    * pipe("abc", String.at(4)) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -700,6 +738,7 @@ export const at: {
  * pipe("abc", String.charAt(4)) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -716,6 +755,7 @@ export const charAt: {
    * pipe("abc", String.charAt(4)) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -732,6 +772,7 @@ export const charAt: {
    * pipe("abc", String.charAt(4)) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -753,6 +794,7 @@ export const charAt: {
  * pipe("abc", String.codePointAt(10)) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -769,6 +811,7 @@ export const codePointAt: {
    * pipe("abc", String.codePointAt(10)) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -785,6 +828,7 @@ export const codePointAt: {
    * pipe("abc", String.codePointAt(10)) // => Option.none()
    * ```
    *
+   * @stability stable
    * @category getters
    * @since 2.0.0
    */
@@ -803,6 +847,7 @@ export const codePointAt: {
  * pipe("abbbc", String.indexOf("z")) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category searching
  * @since 2.0.0
  */
@@ -821,6 +866,7 @@ export const indexOf = (searchString: string) => (self: string): Option.Option<n
  * pipe("abbbc", String.lastIndexOf("d")) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category searching
  * @since 2.0.0
  */
@@ -842,6 +888,7 @@ export const lastIndexOf = (searchString: string) => (self: string): Option.Opti
  * pipe("a", String.localeCompare("a")) // => 0
  * ```
  *
+ * @stability stable
  * @category comparisons
  * @since 2.0.0
  */
@@ -866,6 +913,7 @@ export const localeCompare =
  * pipe("hello", String.match(/x/)) // => Option.none()
  * ```
  *
+ * @stability stable
  * @category searching
  * @since 2.0.0
  */
@@ -886,6 +934,7 @@ export const match = (regExp: RegExp | string) => (self: string): Option.Option<
  * Array.from(matches, (match) => [match[0], match.index]) // => [["l", 2], ["l", 3], ["l", 9]]
  * ```
  *
+ * @stability stable
  * @category searching
  * @since 2.0.0
  */
@@ -913,6 +962,7 @@ export const matchAll = (regExp: RegExp) => (self: string): IterableIterator<Reg
  * ) // => [0x73, 0x323, 0x307]
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -930,6 +980,7 @@ export const normalize = (form?: "NFC" | "NFD" | "NFKC" | "NFKD") => (self: stri
  * pipe("a", String.padEnd(5, "_")) // => "a____"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -948,6 +999,7 @@ export const padEnd = (maxLength: number, fillString?: string) => (self: string)
  * pipe("a", String.padStart(5, "_")) // => "____a"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -970,6 +1022,7 @@ export const padStart = (maxLength: number, fillString?: string) => (self: strin
  * pipe("hello", String.repeat(3)) // => "hellohellohello"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -987,6 +1040,7 @@ export const repeat = (count: number) => (self: string): string => self.repeat(C
  * pipe("ababb", String.replaceAll(/ba/g, "cc")) // => "accbb"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1007,6 +1061,7 @@ export const replaceAll = (searchValue: string | RegExp, replaceValue: string) =
  * String.search("ababb", "d") // => Option.none()
  * ```
  *
+ * @stability stable
  * @category searching
  * @since 2.0.0
  */
@@ -1025,6 +1080,7 @@ export const search: {
    * String.search("ababb", "d") // => Option.none()
    * ```
    *
+   * @stability stable
    * @category searching
    * @since 2.0.0
    */
@@ -1043,6 +1099,7 @@ export const search: {
    * String.search("ababb", "d") // => Option.none()
    * ```
    *
+   * @stability stable
    * @category searching
    * @since 2.0.0
    */
@@ -1065,6 +1122,7 @@ export const search: {
  * pipe(str, String.toLocaleLowerCase("tr")) // => "i"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1083,6 +1141,7 @@ export const toLocaleLowerCase = (locale?: string | Array<string>) => (self: str
  * pipe(str, String.toLocaleUpperCase("lt-LT")) // => "I"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1110,6 +1169,7 @@ export const toLocaleUpperCase = (locale?: string | Array<string>) => (self: str
  * String.takeLeft("Hello World", 5) // => "Hello"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1135,6 +1195,7 @@ export const takeLeft: {
    * String.takeLeft("Hello World", 5) // => "Hello"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -1160,6 +1221,7 @@ export const takeLeft: {
    * String.takeLeft("Hello World", 5) // => "Hello"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -1187,6 +1249,7 @@ export const takeLeft: {
  * String.takeRight("Hello World", 5) // => "World"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1212,6 +1275,7 @@ export const takeRight: {
    * String.takeRight("Hello World", 5) // => "World"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -1237,6 +1301,7 @@ export const takeRight: {
    * String.takeRight("Hello World", 5) // => "World"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -1261,6 +1326,7 @@ const LF = 0x0a
  * Array.from(String.linesIterator("hello\nworld\n")) // => ["hello", "world"]
  * ```
  *
+ * @stability stable
  * @category splitting
  * @since 2.0.0
  */
@@ -1278,6 +1344,7 @@ export const linesIterator = (self: string): LinesIterator => linesSeparated(sel
  * Array.from(String.linesWithSeparators("hello\nworld\n")) // => ["hello\n", "world\n"]
  * ```
  *
+ * @stability stable
  * @category splitting
  * @since 2.0.0
  */
@@ -1295,6 +1362,7 @@ export const linesWithSeparators = (s: string): LinesIterator => linesSeparated(
  * String.stripMarginWith("  |hello\n  |world", "|") // => "hello\nworld"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1311,6 +1379,7 @@ export const stripMarginWith: {
    * String.stripMarginWith("  |hello\n  |world", "|") // => "hello\nworld"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -1327,6 +1396,7 @@ export const stripMarginWith: {
    * String.stripMarginWith("  |hello\n  |world", "|") // => "hello\nworld"
    * ```
    *
+   * @stability stable
    * @category transforming
    * @since 2.0.0
    */
@@ -1362,6 +1432,7 @@ export const stripMarginWith: {
  * String.stripMargin("  |hello\n  |world") // => "hello\nworld"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1379,6 +1450,7 @@ export const stripMargin = (self: string): string => stripMarginWith(self, "|")
  * String.snakeToCamel("foo_bar_baz") // => "fooBarBaz"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1403,6 +1475,7 @@ export const snakeToCamel = (self: string): string => {
  * String.snakeToPascal("foo_bar_baz") // => "FooBarBaz"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1427,6 +1500,7 @@ export const snakeToPascal = (self: string): string => {
  * String.snakeToKebab("foo_bar_baz") // => "foo-bar-baz"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1444,6 +1518,7 @@ export const snakeToKebab = (self: string): string => self.replace(/_/g, "-")
  * String.camelToSnake("fooBarBaz") // => "foo_bar_baz"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1461,6 +1536,7 @@ export const camelToSnake = (self: string): string => self.replace(/([A-Z])/g, "
  * String.pascalToSnake("FooBarBaz") // => "foo_bar_baz"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1479,6 +1555,7 @@ export const pascalToSnake = (self: string): string =>
  * String.kebabToSnake("foo-bar-baz") // => "foo_bar_baz"
  * ```
  *
+ * @stability stable
  * @category transforming
  * @since 2.0.0
  */
@@ -1563,6 +1640,7 @@ const linesSeparated = (self: string, stripped: boolean): LinesIterator => new L
  * @see {@link kebabCase} for fixed lowercase hyphen-separated output
  * @see {@link snakeCase} for fixed lowercase underscore-separated output
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1582,6 +1660,7 @@ export const noCase: {
    * @see {@link kebabCase} for fixed lowercase hyphen-separated output
    * @see {@link snakeCase} for fixed lowercase underscore-separated output
    *
+   * @stability stable
    * @category transforming
    * @since 4.0.0
    */
@@ -1608,6 +1687,7 @@ export const noCase: {
    * @see {@link kebabCase} for fixed lowercase hyphen-separated output
    * @see {@link snakeCase} for fixed lowercase underscore-separated output
    *
+   * @stability stable
    * @category transforming
    * @since 4.0.0
    */
@@ -1692,6 +1772,7 @@ const pascalCaseTransform = (input: string): string => {
  * @see {@link noCase} for configurable delimiters and part transforms
  * @see {@link snakeToPascal} for converting known snake_case input only
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1719,6 +1800,7 @@ const camelCaseTransform = (input: string, index: number): string =>
  * @see {@link kebabCase} for lowercase hyphen-separated output
  * @see {@link constantCase} for uppercase underscore-separated output
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1742,6 +1824,7 @@ export const camelCase: (self: string) => string = noCase({
  * @see {@link configCase} for configuration key casing that preserves numeric word groups
  * @see {@link noCase} for configurable delimiters and part transforms
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1765,6 +1848,7 @@ export const constantCase: (self: string) => string = noCase({
  * example, `"api-v2 xml"` becomes `"API_V2_XML"`.
  *
  * @see {@link constantCase} for standard uppercase underscore-separated output
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1785,6 +1869,7 @@ export const configCase: (self: string) => string = (self) =>
  * @see {@link camelCase} for lower-initial camelCase output
  * @see {@link pascalCase} for upper-initial PascalCase output
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1804,6 +1889,7 @@ export const kebabCase: (self: string) => string = noCase({
  * @see {@link kebabCase} for lowercase hyphen-separated output
  * @see {@link constantCase} for uppercase underscore-separated output
  *
+ * @stability stable
  * @category transforming
  * @since 4.0.0
  */
@@ -1824,6 +1910,7 @@ export const snakeCase: (self: string) => string = noCase({
  *
  * @see {@link concat} for concatenating two strings directly
  *
+ * @stability stable
  * @category combining
  * @since 4.0.0
  */