effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/String.d.ts

@@ -21,7 +21,8 @@ export declare const String: StringConstructor;
 /**
  * Tests if a value is a `string`.
  *
- * @example
+ * **Example** (Checking for strings)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -37,7 +38,8 @@ export declare const isString: Refinement<unknown, string>;
 /**
  * `Order` instance for comparing strings using lexicographic ordering.
  *
- * @example
+ * **Example** (Comparing strings lexicographically)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -53,7 +55,8 @@ export declare const Order: order.Order<string>;
 /**
  * An `Equivalence` instance for strings using strict equality (`===`).
  *
- * @example
+ * **Example** (Comparing strings for equality)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -68,7 +71,8 @@ export declare const Equivalence: Equ.Equivalence<string>;
 /**
  * The empty string `""`.
  *
- * @example
+ * **Example** (Using the empty string)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -83,7 +87,8 @@ export declare const empty: "";
 /**
  * Concatenates two strings at the type level.
  *
- * @example
+ * **Example** (Concatenating string literal types)
+ *
  * ```ts
  * import type { String } from "effect"
  *
@@ -98,7 +103,8 @@ export type Concat<A extends string, B extends string> = `${A}${B}`;
 /**
  * Concatenates two strings at runtime.
  *
- * @example
+ * **Example** (Concatenating strings)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  *
@@ -116,7 +122,8 @@ export declare const concat: {
     /**
      * Concatenates two strings at runtime.
      *
-     * @example
+     * **Example** (Concatenating strings)
+     *
      * ```ts
      * import { pipe, String } from "effect"
      *
@@ -134,7 +141,8 @@ export declare const concat: {
     /**
      * Concatenates two strings at runtime.
      *
-     * @example
+     * **Example** (Concatenating strings)
+     *
      * ```ts
      * import { pipe, String } from "effect"
      *
@@ -153,7 +161,8 @@ export declare const concat: {
 /**
  * Converts a string to uppercase.
  *
- * @example
+ * **Example** (Converting strings to uppercase)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -169,7 +178,8 @@ export declare const toUpperCase: <S extends string>(self: S) => Uppercase<S>;
 /**
  * Converts a string to lowercase.
  *
- * @example
+ * **Example** (Converting strings to lowercase)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -185,7 +195,8 @@ export declare const toLowerCase: <T extends string>(self: T) => Lowercase<T>;
 /**
  * Capitalizes the first character of a string.
  *
- * @example
+ * **Example** (Capitalizing a string)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -201,7 +212,8 @@ export declare const capitalize: <T extends string>(self: T) => Capitalize<T>;
 /**
  * Uncapitalizes the first character of a string.
  *
- * @example
+ * **Example** (Uncapitalizing a string)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -215,9 +227,13 @@ export declare const capitalize: <T extends string>(self: T) => Capitalize<T>;
  */
 export declare const uncapitalize: <T extends string>(self: T) => Uncapitalize<T>;
 /**
- * Replaces the first occurrence of a substring or pattern in a string.
+ * Replaces matches in a string using `String.prototype.replace`.
+ *
+ * String search values and non-global regular expressions replace the first
+ * match; global regular expressions replace every match.
+ *
+ * **Example** (Replacing a substring)
  *
- * @example
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -236,7 +252,8 @@ export declare const replace: (searchValue: string | RegExp, replaceValue: strin
 /**
  * Type-level representation of trimming whitespace from both ends of a string.
  *
- * @example
+ * **Example** (Trimming whitespace at the type level)
+ *
  * ```ts
  * import type { String } from "effect"
  *
@@ -250,7 +267,8 @@ export type Trim<A extends string> = TrimEnd<TrimStart<A>>;
 /**
  * Removes whitespace from both ends of a string.
  *
- * @example
+ * **Example** (Trimming whitespace)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -266,7 +284,8 @@ export declare const trim: <A extends string>(self: A) => Trim<A>;
 /**
  * Type-level representation of trimming whitespace from the start of a string.
  *
- * @example
+ * **Example** (Trimming leading whitespace at the type level)
+ *
  * ```ts
  * import type { String } from "effect"
  *
@@ -280,7 +299,8 @@ export type TrimStart<A extends string> = A extends `${" " | "\n" | "\t" | "\r"}
 /**
  * Removes whitespace from the start of a string.
  *
- * @example
+ * **Example** (Trimming leading whitespace)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -296,7 +316,8 @@ export declare const trimStart: <A extends string>(self: A) => TrimStart<A>;
 /**
  * Type-level representation of trimming whitespace from the end of a string.
  *
- * @example
+ * **Example** (Trimming trailing whitespace at the type level)
+ *
  * ```ts
  * import type { String } from "effect"
  *
@@ -310,7 +331,8 @@ export type TrimEnd<A extends string> = A extends `${infer B}${" " | "\n" | "\t"
 /**
  * Removes whitespace from the end of a string.
  *
- * @example
+ * **Example** (Trimming trailing whitespace)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -326,7 +348,8 @@ export declare const trimEnd: <A extends string>(self: A) => TrimEnd<A>;
 /**
  * Extracts a section of a string and returns it as a new string.
  *
- * @example
+ * **Example** (Slicing strings)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -342,7 +365,8 @@ export declare const slice: (start?: number, end?: number) => (self: string) =>
 /**
  * Test whether a `string` is empty.
  *
- * @example
+ * **Example** (Checking for empty strings)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -358,7 +382,8 @@ export declare const isEmpty: (self: string) => self is "";
 /**
  * Test whether a `string` is non empty.
  *
- * @example
+ * **Example** (Checking for non-empty strings)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -372,9 +397,10 @@ export declare const isEmpty: (self: string) => self is "";
  */
 export declare const isNonEmpty: (self: string) => boolean;
 /**
- * Calculate the number of characters in a `string`.
+ * Returns the JavaScript string length, measured in UTF-16 code units.
+ *
+ * **Example** (Getting string length)
  *
- * @example
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -389,7 +415,8 @@ export declare const length: (self: string) => number;
 /**
  * Splits a string into an array of substrings using a separator.
  *
- * @example
+ * **Example** (Splitting strings)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -406,7 +433,8 @@ export declare const split: {
     /**
      * Splits a string into an array of substrings using a separator.
      *
-     * @example
+     * **Example** (Splitting strings)
+     *
      * ```ts
      * import { pipe, String } from "effect"
      * import * as assert from "node:assert"
@@ -423,7 +451,8 @@ export declare const split: {
     /**
      * Splits a string into an array of substrings using a separator.
      *
-     * @example
+     * **Example** (Splitting strings)
+     *
      * ```ts
      * import { pipe, String } from "effect"
      * import * as assert from "node:assert"
@@ -442,7 +471,8 @@ export declare const split: {
  * Returns `true` if `searchString` appears as a substring of `self`, at one or more positions that are
  * greater than or equal to `position`; otherwise, returns `false`.
  *
- * @example
+ * **Example** (Checking for substrings)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -458,7 +488,8 @@ export declare const includes: (searchString: string, position?: number) => (sel
 /**
  * Returns `true` if the string starts with the specified search string.
  *
- * @example
+ * **Example** (Checking string prefixes)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -474,7 +505,8 @@ export declare const startsWith: (searchString: string, position?: number) => (s
 /**
  * Returns `true` if the string ends with the specified search string.
  *
- * @example
+ * **Example** (Checking string suffixes)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -490,7 +522,7 @@ export declare const endsWith: (searchString: string, position?: number) => (sel
 /**
  * Returns the character code at the specified index, or `None` if the index is out of bounds.
  *
- * **Example**
+ * **Example** (Reading character codes)
  *
  * ```ts
  * import { String } from "effect"
@@ -506,7 +538,7 @@ export declare const charCodeAt: {
     /**
      * Returns the character code at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Reading character codes)
      *
      * ```ts
      * import { String } from "effect"
@@ -522,7 +554,7 @@ export declare const charCodeAt: {
     /**
      * Returns the character code at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Reading character codes)
      *
      * ```ts
      * import { String } from "effect"
@@ -539,7 +571,7 @@ export declare const charCodeAt: {
 /**
  * Extracts characters from a string between two specified indices.
  *
- * **Example**
+ * **Example** (Extracting substrings)
  *
  * ```ts
  * import { pipe, String } from "effect"
@@ -555,7 +587,7 @@ export declare const substring: (start: number, end?: number) => (self: string)
 /**
  * Returns the character at the specified index, or `None` if the index is out of bounds.
  *
- * **Example**
+ * **Example** (Accessing characters safely)
  *
  * ```ts
  * import { pipe, String } from "effect"
@@ -571,7 +603,7 @@ export declare const at: {
     /**
      * Returns the character at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Accessing characters safely)
      *
      * ```ts
      * import { pipe, String } from "effect"
@@ -587,7 +619,7 @@ export declare const at: {
     /**
      * Returns the character at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Accessing characters safely)
      *
      * ```ts
      * import { pipe, String } from "effect"
@@ -604,7 +636,7 @@ export declare const at: {
 /**
  * Returns the character at the specified index, or `None` if the index is out of bounds.
  *
- * **Example**
+ * **Example** (Reading characters safely)
  *
  * ```ts
  * import { pipe, String } from "effect"
@@ -620,7 +652,7 @@ export declare const charAt: {
     /**
      * Returns the character at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Reading characters safely)
      *
      * ```ts
      * import { pipe, String } from "effect"
@@ -636,7 +668,7 @@ export declare const charAt: {
     /**
      * Returns the character at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Reading characters safely)
      *
      * ```ts
      * import { pipe, String } from "effect"
@@ -653,7 +685,7 @@ export declare const charAt: {
 /**
  * Returns the Unicode code point at the specified index, or `None` if the index is out of bounds.
  *
- * **Example**
+ * **Example** (Reading code points)
  *
  * ```ts
  * import { pipe, String } from "effect"
@@ -669,7 +701,7 @@ export declare const codePointAt: {
     /**
      * Returns the Unicode code point at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Reading code points)
      *
      * ```ts
      * import { pipe, String } from "effect"
@@ -685,7 +717,7 @@ export declare const codePointAt: {
     /**
      * Returns the Unicode code point at the specified index, or `None` if the index is out of bounds.
      *
-     * **Example**
+     * **Example** (Reading code points)
      *
      * ```ts
      * import { pipe, String } from "effect"
@@ -702,7 +734,7 @@ export declare const codePointAt: {
 /**
  * Returns the index of the first occurrence of a substring, or `None` if not found.
  *
- * **Example**
+ * **Example** (Finding the first substring index)
  *
  * ```ts
  * import { pipe, String } from "effect"
@@ -718,7 +750,7 @@ export declare const indexOf: (searchString: string) => (self: string) => Option
 /**
  * Returns the index of the last occurrence of a substring, or `None` if not found.
  *
- * **Example**
+ * **Example** (Finding the last substring index)
  *
  * ```ts
  * import { pipe, String } from "effect"
@@ -732,9 +764,12 @@ export declare const indexOf: (searchString: string) => (self: string) => Option
  */
 export declare const lastIndexOf: (searchString: string) => (self: string) => Option.Option<number>;
 /**
- * Compares two strings according to the current locale.
+ * Compares two strings using locale-aware collation, with optional locales and
+ * collator options, and returns the result as an `Ordering` (`-1`, `0`, or
+ * `1`).
+ *
+ * **Example** (Comparing strings by locale)
  *
- * @example
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -749,15 +784,21 @@ export declare const lastIndexOf: (searchString: string) => (self: string) => Op
  */
 export declare const localeCompare: (that: string, locales?: Array<string>, options?: Intl.CollatorOptions) => (self: string) => Ordering.Ordering;
 /**
- * A `pipe`-able version of the native `match` method.
+ * Matches a string against a pattern and returns `Option.some` with the match
+ * array, or `Option.none` when the pattern does not match.
  *
- * **Example**
+ * **Example** (Matching regular expressions)
  *
  * ```ts
- * import { pipe, String } from "effect"
+ * import { Option, pipe, String } from "effect"
+ *
+ * const match = pipe("hello", String.match(/l+/))
  *
- * pipe("hello", String.match(/l+/)) // Option.some(["ll"])
- * pipe("hello", String.match(/x/)) // Option.none()
+ * if (Option.isSome(match)) {
+ *   console.log(`${match.value[0]}@${match.value.index}`) // "ll@2"
+ * }
+ *
+ * console.log(Option.isNone(pipe("hello", String.match(/x/)))) // true
  * ```
  *
  * @category searching
@@ -765,14 +806,18 @@ export declare const localeCompare: (that: string, locales?: Array<string>, opti
  */
 export declare const match: (regExp: RegExp | string) => (self: string) => Option.Option<RegExpMatchArray>;
 /**
- * It is the `pipe`-able version of the native `matchAll` method.
+ * Returns an iterator over all regular expression matches in the string using
+ * native `String.prototype.matchAll` semantics.
+ *
+ * **Example** (Iterating regular expression matches)
  *
- * @example
  * ```ts
  * import { pipe, String } from "effect"
  *
  * const matches = pipe("hello world", String.matchAll(/l/g))
- * console.log(Array.from(matches)) // [["l"], ["l"], ["l"]]
+ * console.log(
+ *   Array.from(matches, (match) => `${match[0]}@${match.index}`).join(", ")
+ * ) // "l@2, l@3, l@9"
  * ```
  *
  * @category searching
@@ -782,7 +827,8 @@ export declare const matchAll: (regExp: RegExp) => (self: string) => IterableIte
 /**
  * Normalizes a string according to the specified Unicode normalization form.
  *
- * @example
+ * **Example** (Normalizing Unicode strings)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -805,7 +851,8 @@ export declare const normalize: (form?: "NFC" | "NFD" | "NFKC" | "NFKD") => (sel
 /**
  * Pads the string from the end with a given fill string to a specified length.
  *
- * @example
+ * **Example** (Padding strings at the end)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -821,7 +868,8 @@ export declare const padEnd: (maxLength: number, fillString?: string) => (self:
 /**
  * Pads the string from the start with a given fill string to a specified length.
  *
- * @example
+ * **Example** (Padding strings at the start)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -837,7 +885,8 @@ export declare const padStart: (maxLength: number, fillString?: string) => (self
 /**
  * Repeats the string the specified number of times.
  *
- * @example
+ * **Example** (Repeating strings)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -853,7 +902,8 @@ export declare const repeat: (count: number) => (self: string) => string;
 /**
  * Replaces all occurrences of a substring or pattern in a string.
  *
- * @example
+ * **Example** (Replacing all matches)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -867,9 +917,10 @@ export declare const repeat: (count: number) => (self: string) => string;
  */
 export declare const replaceAll: (searchValue: string | RegExp, replaceValue: string) => (self: string) => string;
 /**
- * Searches for a match between a regular expression and the string.
+ * Returns the index of the first match for a string or regular expression, or
+ * `Option.none` when no match is found.
  *
- * **Example**
+ * **Example** (Searching strings)
  *
  * ```ts
  * import { String } from "effect"
@@ -884,9 +935,10 @@ export declare const replaceAll: (searchValue: string | RegExp, replaceValue: st
  */
 export declare const search: {
     /**
-     * Searches for a match between a regular expression and the string.
+     * Returns the index of the first match for a string or regular expression, or
+     * `Option.none` when no match is found.
      *
-     * **Example**
+     * **Example** (Searching strings)
      *
      * ```ts
      * import { String } from "effect"
@@ -901,9 +953,10 @@ export declare const search: {
      */
     (regExp: RegExp | string): (self: string) => Option.Option<number>;
     /**
-     * Searches for a match between a regular expression and the string.
+     * Returns the index of the first match for a string or regular expression, or
+     * `Option.none` when no match is found.
      *
-     * **Example**
+     * **Example** (Searching strings)
      *
      * ```ts
      * import { String } from "effect"
@@ -921,7 +974,8 @@ export declare const search: {
 /**
  * Converts the string to lowercase according to the specified locale.
  *
- * @example
+ * **Example** (Lowercasing strings by locale)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -937,7 +991,8 @@ export declare const toLocaleLowerCase: (locale?: string | Array<string>) => (se
 /**
  * Converts the string to uppercase according to the specified locale.
  *
- * @example
+ * **Example** (Uppercasing strings by locale)
+ *
  * ```ts
  * import { pipe, String } from "effect"
  * import * as assert from "node:assert"
@@ -960,7 +1015,8 @@ export declare const toLocaleUpperCase: (locale?: string | Array<string>) => (se
  *
  * If `n` is a float, it will be rounded down to the nearest integer.
  *
- * @example
+ * **Example** (Taking characters from the start)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -982,7 +1038,8 @@ export declare const takeLeft: {
      *
      * If `n` is a float, it will be rounded down to the nearest integer.
      *
-     * @example
+     * **Example** (Taking characters from the start)
+     *
      * ```ts
      * import { String } from "effect"
      * import * as assert from "node:assert"
@@ -1004,7 +1061,8 @@ export declare const takeLeft: {
      *
      * If `n` is a float, it will be rounded down to the nearest integer.
      *
-     * @example
+     * **Example** (Taking characters from the start)
+     *
      * ```ts
      * import { String } from "effect"
      * import * as assert from "node:assert"
@@ -1027,7 +1085,8 @@ export declare const takeLeft: {
  *
  * If `n` is a float, it will be rounded down to the nearest integer.
  *
- * @example
+ * **Example** (Taking characters from the end)
+ *
  * ```ts
  * import { String } from "effect"
  * import * as assert from "node:assert"
@@ -1049,7 +1108,8 @@ export declare const takeRight: {
      *
      * If `n` is a float, it will be rounded down to the nearest integer.
      *
-     * @example
+     * **Example** (Taking characters from the end)
+     *
      * ```ts
      * import { String } from "effect"
      * import * as assert from "node:assert"
@@ -1071,7 +1131,8 @@ export declare const takeRight: {
      *
      * If `n` is a float, it will be rounded down to the nearest integer.
      *
-     * @example
+     * **Example** (Taking characters from the end)
+     *
      * ```ts
      * import { String } from "effect"
      * import * as assert from "node:assert"
@@ -1088,7 +1149,8 @@ export declare const takeRight: {
  * Returns an `IterableIterator` which yields each line contained within the
  * string, trimming off the trailing newline character.
  *
- * @example
+ * **Example** (Iterating lines without separators)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1104,7 +1166,8 @@ export declare const linesIterator: (self: string) => LinesIterator;
  * Returns an `IterableIterator` which yields each line contained within the
  * string as well as the trailing newline character.
  *
- * @example
+ * **Example** (Iterating lines with separators)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1121,7 +1184,8 @@ export declare const linesWithSeparators: (s: string) => LinesIterator;
  * or control characters followed by the character specified by `marginChar`
  * from the line.
  *
- * @example
+ * **Example** (Stripping custom margins)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1139,7 +1203,8 @@ export declare const stripMarginWith: {
      * or control characters followed by the character specified by `marginChar`
      * from the line.
      *
-     * @example
+     * **Example** (Stripping custom margins)
+     *
      * ```ts
      * import { String } from "effect"
      *
@@ -1157,7 +1222,8 @@ export declare const stripMarginWith: {
      * or control characters followed by the character specified by `marginChar`
      * from the line.
      *
-     * @example
+     * **Example** (Stripping custom margins)
+     *
      * ```ts
      * import { String } from "effect"
      *
@@ -1175,7 +1241,8 @@ export declare const stripMarginWith: {
  * For every line in this string, strip a leading prefix consisting of blanks
  * or control characters followed by the `"|"` character from the line.
  *
- * @example
+ * **Example** (Stripping pipe margins)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1191,7 +1258,8 @@ export declare const stripMargin: (self: string) => string;
 /**
  * Converts a snake_case string to camelCase.
  *
- * @example
+ * **Example** (Converting snake_case to camelCase)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1206,7 +1274,8 @@ export declare const snakeToCamel: (self: string) => string;
 /**
  * Converts a snake_case string to PascalCase.
  *
- * @example
+ * **Example** (Converting snake_case to PascalCase)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1221,7 +1290,8 @@ export declare const snakeToPascal: (self: string) => string;
 /**
  * Converts a snake_case string to kebab-case.
  *
- * @example
+ * **Example** (Converting snake_case to kebab-case)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1236,7 +1306,8 @@ export declare const snakeToKebab: (self: string) => string;
 /**
  * Converts a camelCase string to snake_case.
  *
- * @example
+ * **Example** (Converting camelCase to snake_case)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1251,7 +1322,8 @@ export declare const camelToSnake: (self: string) => string;
 /**
  * Converts a PascalCase string to snake_case.
  *
- * @example
+ * **Example** (Converting PascalCase to snake_case)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1266,7 +1338,8 @@ export declare const pascalToSnake: (self: string) => string;
 /**
  * Converts a kebab-case string to snake_case.
  *
- * @example
+ * **Example** (Converting kebab-case to snake_case)
+ *
  * ```ts
  * import { String } from "effect"
  *
@@ -1289,14 +1362,16 @@ declare class LinesIterator implements IterableIterator<string> {
     private get done();
 }
 /**
- * Normalize a string to a specific case format
+ * Normalizes a string by splitting it into word parts, transforming each part,
+ * and joining the parts with a configurable delimiter.
  *
  * @category transforming
  * @since 4.0.0
  */
 export declare const noCase: {
     /**
-     * Normalize a string to a specific case format
+     * Normalizes a string by splitting it into word parts, transforming each part,
+     * and joining the parts with a configurable delimiter.
      *
      * @category transforming
      * @since 4.0.0
@@ -1308,7 +1383,8 @@ export declare const noCase: {
         readonly transform?: (part: string, index: number, parts: ReadonlyArray<string>) => string;
     }): (self: string) => string;
     /**
-     * Normalize a string to a specific case format
+     * Normalizes a string by splitting it into word parts, transforming each part,
+     * and joining the parts with a configurable delimiter.
      *
      * @category transforming
      * @since 4.0.0
@@ -1323,36 +1399,36 @@ export declare const noCase: {
 /**
  * Converts a string to PascalCase.
  *
- * @since 4.0.0
  * @category transforming
+ * @since 4.0.0
  */
 export declare const pascalCase: (self: string) => string;
 /**
  * Converts a string to camelCase.
  *
- * @since 4.0.0
  * @category transforming
+ * @since 4.0.0
  */
 export declare const camelCase: (self: string) => string;
 /**
  * Converts a string to CONSTANT_CASE (uppercase with underscores).
  *
- * @since 4.0.0
  * @category transforming
+ * @since 4.0.0
  */
 export declare const constantCase: (self: string) => string;
 /**
  * Converts a string to kebab-case (lowercase with hyphens).
  *
- * @since 4.0.0
  * @category transforming
+ * @since 4.0.0
  */
 export declare const kebabCase: (self: string) => string;
 /**
  * Converts a string to snake_case (lowercase with underscores).
  *
- * @since 4.0.0
  * @category transforming
+ * @since 4.0.0
  */
 export declare const snakeCase: (self: string) => string;
 /**