obsidian-dev-utils/dist/lib/cjs/String.d.cts

This is the collection of useful functions that you can use for your Obsidian plugin development

/**
 * @packageDocumentation
 *
 * Contains utility functions for string operations.
 */
import type { MaybeReturn } from './Type.cjs';
import type { ValueProvider } from './ValueProvider.cjs';
/**
 * A synchronous/asynchronous function that generates replacement strings, or a string to replace with.
 */
export type AsyncReplacer<ReplaceGroupArgs extends string[]> = ValueProvider<StringReplacement, [ReplaceCommonArgs, ...ReplaceGroupArgs]>;
/**
 * Common arguments for the `replaceAll`/`replaceAllAsync` functions.
 */
export interface ReplaceCommonArgs {
    /**
     * Groups of the match.
     */
    groups: Record<string, string | undefined> | undefined;
    /**
     * Indices of the groups that were not found in the match.
     */
    missingGroupIndices: number[];
    /**
     * An offset of the match.
     */
    offset: number;
    /**
     * A source of the match.
     */
    source: string;
    /**
     * A substring of the match.
     */
    substring: string;
}
/**
 * A synchronous function that generates replacement strings, or a string to replace with.
 */
export type Replacer<ReplaceGroupArgs extends string[]> = ((...args: [ReplaceCommonArgs, ...ReplaceGroupArgs]) => StringReplacement) | StringReplacement;
type StringReplacement = MaybeReturn<string>;
/**
 * Ensures that a string ends with the specified suffix, adding it if necessary.
 *
 * @param str - The string to check.
 * @param suffix - The suffix to ensure.
 * @returns The string that ends with the suffix.
 */
export declare function ensureEndsWith(str: string, suffix: string): string;
/**
 * Ensures that a string has `LF` line endings.
 *
 * It replaces `CRLF` line endings with `LF`.
 *
 * @param str - The string.
 * @returns The string with `LF` line endings.
 */
export declare function ensureLfEndings(str: string): string;
/**
 * Ensures that a string starts with the specified prefix, adding it if necessary.
 *
 * @param str - The string to check.
 * @param prefix - The prefix to ensure.
 * @returns The string that starts with the prefix.
 */
export declare function ensureStartsWith(str: string, prefix: string): string;
/**
 * Escapes special characters in a string.
 *
 * @param str - The string to escape.
 * @returns The escaped string.
 */
export declare function escape(str: string): string;
/**
 * Returns a function that maps LF-normalized offsets to original offsets.
 *
 * @param str - The string to get the LF-normalized indices from.
 * @returns A function that maps LF-normalized offsets to original offsets.
 */
export declare function getLfNormalizedOffsetToOriginalOffsetMapper(str: string): (lfOffset: number) => number;
/**
 * Checks if a string has a single occurrence of a search value.
 *
 * @param str - The string to check.
 * @param searchValue - The search value to check for.
 * @returns `true` if the string has a single occurrence of the search value, `false` otherwise.
 */
export declare function hasSingleOccurrence(str: string, searchValue: string): boolean;
/**
 * Indents a string by adding a prefix to each line.
 *
 * @param text - The string to indent.
 * @param prefix - The prefix to add to each line.
 * @returns The indented string.
 */
export declare function indent(text: string, prefix: string): string;
/**
 * Inserts a substring at a specified position in a string.
 *
 * @param str - The string to insert the substring into.
 * @param substring - The substring to insert.
 * @param startIndex - The index to insert the substring at.
 * @param endIndex - The index to end the substring at.
 * @returns The modified string with the substring inserted.
 */
export declare function insertAt(str: string, substring: string, startIndex: number, endIndex?: number): string;
/**
 * Converts a string into a valid JavaScript variable name by replacing invalid characters with underscores.
 *
 * @param str - The string to convert.
 * @returns The valid variable name.
 */
export declare function makeValidVariableName(str: string): string;
/**
 * Normalizes a string by converting it to the NFC form and replacing non-breaking spaces with regular spaces.
 *
 * @param str - The string to normalize.
 * @returns The normalized string.
 */
export declare function normalize(str: string): string;
/**
 * Replaces occurrences of strings in a given string based on a replacements map.
 *
 * @param str - The string to perform replacements on.
 * @param replacementsMap - An object mapping strings to their replacement values.
 * @returns The modified string with replacements applied.
 */
export declare function replace(str: string, replacementsMap: Record<string, string>): string;
/**
 * Replaces all occurrences of a search string or pattern with the results of an replacer function.
 *
 * @typeParam ReplaceGroupArgs - The type of additional arguments passed to the replacer function.
 * @param str - The string in which to perform replacements.
 * @param searchValue - The string or regular expression to search for.
 * @param replacer - A replacer function that generates replacement strings, or a string to replace with.
 * @returns The string with all replacements made.
 */
export declare function replaceAll<ReplaceGroupArgs extends string[]>(str: string, searchValue: RegExp | string, replacer: Replacer<ReplaceGroupArgs>): string;
/**
 * Asynchronously replaces all occurrences of a search string or pattern with the results of an asynchronous replacer function.
 *
 * @typeParam ReplaceGroupArgs - The type of additional arguments passed to the replacer function.
 * @param str - The string in which to perform replacements.
 * @param searchValue - The string or regular expression to search for.
 * @param replacer - A synchronous/asynchronous function that generates replacement strings, or a string to replace with.
 * @param abortSignal - The abort signal to control the execution of the function.
 * @returns A {@link Promise} that resolves to the string with all replacements made.
 */
export declare function replaceAllAsync<ReplaceGroupArgs extends string[]>(str: string, searchValue: RegExp | string, replacer: AsyncReplacer<ReplaceGroupArgs>, abortSignal?: AbortSignal): Promise<string>;
/**
 * Trims the specified suffix from the end of a string.
 *
 * @param str - The string to trim.
 * @param suffix - The suffix to remove from the end of the string.
 * @param shouldValidate - If true, throws an error if the string does not end with the suffix.
 * @returns The trimmed string.
 * @throws If `validate` is true and the string does not end with the suffix.
 */
export declare function trimEnd(str: string, suffix: string, shouldValidate?: boolean): string;
/**
 * Trims the specified prefix from the start of a string.
 *
 * @param str - The string to trim.
 * @param prefix - The prefix to remove from the start of the string.
 * @param validate - If true, throws an error if the string does not start with the prefix.
 * @returns The trimmed string.
 * @throws If `validate` is true and the string does not start with the prefix.
 */
export declare function trimStart(str: string, prefix: string, validate?: boolean): string;
/**
 * Unescapes a string by replacing escape sequences with their corresponding characters.
 *
 * @param str - The string to unescape.
 * @returns The unescaped string.
 */
export declare function unescape(str: string): string;
/**
 * Unindents a string by removing a prefix from each line.
 *
 * @param text - The string to unindent.
 * @param prefix - The prefix to remove from each line.
 * @param shouldThrowIfNotIndented - If `true`, throws an error if a line is not indented with the prefix.
 * @returns The unindented string.
 */
export declare function unindent(text: string, prefix: string, shouldThrowIfNotIndented?: boolean): string;
export {};