molstar/lib/mol-io/common/string-like.d.ts

A comprehensive macromolecular library.

/**
 * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
 *
 * @author Adam Midlik <midlik@gmail.com>
 */
/**
 * Essential subset of `string` functionality.
 * Can be builtin `string` or `String` type or a class instance implementing necessary methods.
 * Add more string methods if needed.
 */
export interface StringLike {
    /** Returns the length of a String object. */
    readonly length: number;
    /**
     * Returns the character at the specified index, or `undefined` if the index is out of range. Supports relative indexing from the end of the string when passed a negative index.
     * @param pos The zero-based index of the desired character.
     */
    at(index: number): string | undefined;
    /**
     * Returns the character at the specified index, or an empty string if the index is out of range.
     * @param pos The zero-based index of the desired character.
     */
    charAt(pos: number): string;
    /**
     * Returns the Unicode value of the character at the specified location.
     * @param index The zero-based index of the desired character. If the specified index is out of range, NaN is returned.
     */
    charCodeAt(index: number): number;
    /**
     * Returns the substring at the specified location within a String object.
     * @param start The zero-based index number indicating the beginning of the substring.
     * @param end Zero-based index number indicating the end of the substring. The substring includes the characters up to, but not including, the character indicated by end.
     * If end is omitted, the characters from start through the end of the original string are returned.
     */
    substring(start: number, end?: number): string;
    /**
     * Returns the position of the first occurrence of a substring, or -1 if not found.
     * @param searchString The substring to search for in the string
     * @param position The index at which to begin searching the String object. If omitted, search starts at the beginning of the string.
     */
    indexOf(searchString: string, position?: number): number;
    /**
     * Returns true if searchString appears as a substring of the result of converting this
     * object to a String, at one or more positions that are
     * greater than or equal to position; otherwise, returns false.
     * @param searchString search string
     * @param position If position is undefined, 0 is assumed, so as to search all of the String.
     */
    includes(searchString: string, position?: number): boolean;
    /**
     * Returns true if the sequence of elements of searchString converted to a String is the
     * same as the corresponding elements of this object (converted to a String) starting at
     * position. Otherwise returns false.
     */
    startsWith(searchString: string, position?: number): boolean;
    /** Returns a string representation of a string. */
    toString(): string;
}
export declare const StringLike: {
    /** Return true if `obj` is instance of `StringLike` */
    is(obj: unknown): obj is StringLike;
    /** Try to convert `StringLike` to a primitive `string`. Might fail if the content is longer that max allowed string length. */
    toString(str: StringLike): string;
};
/** Maximum allowed string length (might be bigger for some engines, but in Chrome 136 and Node 22 it is this). */
export declare const MAX_STRING_LENGTH = 536870888;
/** Implementation of `CustomString`, based on an array of fixed-length strings (chunks). */
export declare class ChunkedBigString implements StringLike {
    private _chunks;
    /** Length of string chunks (default 2**28). */
    private readonly STRING_CHUNK_SIZE;
    /** Bit shift to get chunk index from char index (default 28) */
    private readonly STRING_CHUNK_SHIFT;
    /** Bit mask to get index within chunk index from char index (default 2**28 - 1) */
    private readonly STRING_CHUNK_MASK;
    private _length;
    get length(): number;
    constructor(logStringChunkSize?: number);
    static fromString(content: string, logStringChunkSize?: number): ChunkedBigString;
    static fromStrings(content: string[], logStringChunkSize?: number): ChunkedBigString;
    /** Create instance from UTF8 data. (Do not call directly, prefer `utf8ReadLong` in utf8.ts.) */
    static fromUtf8Data(data: Uint8Array, start?: number, end?: number, logStringChunkSize?: number): ChunkedBigString;
    private _append;
    private _getChunkIndex;
    private _getIndexInChunk;
    private _isOutOfRange;
    at(index: number): string | undefined;
    charAt(index: number): string;
    charCodeAt(index: number): number;
    substring(start?: number, end?: number): string;
    private readonly _tmpArray;
    private _getTmpArray;
    indexOf(searchString: string, position?: number): number;
    includes(searchString: string, position?: number): boolean;
    startsWith(searchString: string, position?: number): boolean;
    toString(): string;
}