@contextjs/text/api/index.d.ts

String manipulation utilities for ContextJS applications

/**
 * @license
 * Copyright ContextJS All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found at https://github.com/contextjs/context/blob/main/LICENSE
 */

/**
 * @license
 * Copyright ContextJS All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found at https://github.com/contextjs/context/blob/main/LICENSE
 */

export declare class StringBuilder {
    /**
     * Appends the given string to the builder.
     *
     * @param value The string to append.
     * @returns The current instance for chaining.
     */
    append(value: string): this;

    /**
     * Appends the given string followed by a newline.
     *
     * @param text The string to append before the newline. Defaults to an empty string.
     * @returns The current instance for chaining.
     */
    appendLine(text?: string): this;

    /**
     * Appends a formatted string where placeholders {0}, {1}, ... are replaced by args.
     *
     * @param format The format string containing placeholders.
     * @param args The values to replace placeholders with.
     * @returns The current instance for chaining.
     * @throws {ArgumentNullException} If the format string is null, empty, or whitespace.
     */
    appendFormat(format: string, ...args: any[]): this;

    /**
     * Inserts the given value at the specified segment index.
     *
     * @param index The position at which to insert the value.
     * @param value The string to insert.
     * @returns The current instance for chaining.
     * @throws {ArgumentOutOfRangeException} If the index is out of range.
     */
    insert(index: number, value: string): this;

    /**
     * Removes a number of segments starting at the specified index.
     *
     * @param index The starting index of the segment to remove.
     * @param count The number of segments to remove.
     * @returns The current instance for chaining.
     * @throws {ArgumentOutOfRangeException} If the index is out of range.
     */
    removeSegment(index: number, count?: number): this;

    /**
     * Replaces the segment at the specified index with a new value.
     *
     * @param index The index of the segment to replace.
     * @param value The new string to replace the segment with.
     * @returns The current instance for chaining.
     * @throws {ArgumentOutOfRangeException} If the index is out of range.
     */
    replaceSegment(index: number, value: string): this;

    /**
     * Clears all content from the builder.
     */
    clear(): void;

    /**
     * Converts the builder to a single string.
     *
     * @returns The concatenated string.
     */
    toString(): string;

    /**
     * Returns a copy of the internal segment array.
     *
     * @returns An array of all segments.
     */
    toArray(): string[];

    /**
     * Creates a clone of the current StringBuilder instance.
     * The internal segments are copied to ensure isolated mutation.
     *
     * @returns A new StringBuilder with the same content.
     */
    clone(): StringBuilder;

    /**
     * Total number of characters in the builder.
     */
    readonly length: number;

    /**
     * Number of segments appended.
     */
    readonly segmentCount: number;

    /**
     * Indicates whether the builder is empty.
     */
    readonly isEmpty: boolean;

    /**
     * Allows implicit conversion to string (e.g., `${builder}`).
     *
     * @param hint The type hint provided by the JavaScript engine.
     * @returns The string representation of the builder.
     */
    [Symbol.toPrimitive](hint: string): string;
}