import { type ArrayOrValue } from '../array/array';
import { type Maybe } from '../value/maybe.type';
import { type MapSameFunction } from '../value/map';
/**
 * Function that replaces target substrings within an input string.
 */
export type ReplaceStringsFunction = MapSameFunction<string>;
/**
 * Configuration for creating a {@link ReplaceStringsFunction}.
 */
export interface ReplaceStringsConfig {
    /**
     * Strings to target/replace.
     */
    readonly replace: ArrayOrValue<string>;
    /**
     * Value to replace all recurrences with.
     */
    readonly replaceWith: string;
}
/**
 * Creates a function that replaces all occurrences of the configured target strings with a replacement value.
 *
 * @param config - Configuration specifying strings to find and the replacement value.
 * @returns A function that performs the configured replacements on an input string.
 */
export declare function replaceStringsFunction(config: ReplaceStringsConfig): (input: string) => string;
/**
 * Array of characters that have special meaning in regular expressions and need escaping.
 */
export declare const REGEX_SPECIAL_CHARACTERS: string[];
/**
 * Set of regex special characters for efficient lookup.
 */
export declare const REGEX_SPECIAL_CHARACTERS_SET: Set<string>;
/**
 * Creates an escaped regex string that matches any of the input values, joined with the OR (`|`) operator.
 *
 * @param find - One or more strings to create a matching regex pattern for.
 * @returns A regex-compatible string with special characters escaped and values joined by `|`.
 */
export declare function findStringsRegexString(find: ArrayOrValue<string>): string;
/**
 * Configuration for creating an {@link EscapeStringCharactersFunction}.
 */
export interface EscapeStringCharactersFunctionConfig {
    /**
     * The set of characters to find and use the escapeCharacter() function on.
     *
     * Targets should be individual characters. Strings of more than one character are ignored.
     */
    readonly escapeTargets: Iterable<string> | Set<string>;
    /**
     * Escapes the target character. Can return any string to properly "escape" the character.
     *
     * @param char
     * @returns
     */
    readonly escapeCharacter: (char: string) => string;
}
/**
 * Function that properly "escapes" specific characters in a string.
 *
 * How the characters are escaped is determined by the function.
 */
export type EscapeStringCharactersFunction = (input: string) => string;
/**
 * Creates an {@link EscapeStringCharactersFunction} that escapes specific characters in a string using the configured escape strategy.
 *
 * @param config - Configuration specifying which characters to escape and how to escape them.
 * @returns A function that escapes the configured characters in any input string.
 */
export declare function escapeStringCharactersFunction(config: EscapeStringCharactersFunctionConfig): EscapeStringCharactersFunction;
/**
 * Escapes the input string so it can be safely used as a literal value in a regular expression.
 *
 * For instance, `'hello.world'` will be escaped to `'hello\\.world'`.
 *
 * @param input - The string to escape for regex use.
 * @returns The escaped string with all regex special characters prefixed with a backslash.
 */
export declare const escapeStringForRegex: EscapeStringCharactersFunction;
/**
 * Function that finds all indices of characters from a pre-configured set within an input string.
 *
 * @param input - The string to search through.
 * @param max - Optional maximum number of occurrences to return.
 * @returns An array of zero-based indices where matching characters were found.
 */
export type FindAllCharacterOccurencesFunction = (input: string, max?: Maybe<number>) => number[];
/**
 * Creates a {@link FindAllCharacterOccurencesFunction} that searches for characters from the given set.
 *
 * @param characterSet - The set of characters to search for.
 * @returns A function that finds all occurrences of the configured characters in an input string.
 */
export declare function findAllCharacterOccurencesFunction(characterSet: Set<string>): FindAllCharacterOccurencesFunction;
/**
 * Finds all indices of characters from the set that appear in the input string.
 *
 * @param set - The set of characters to search for.
 * @param input - The string to search through.
 * @param max - Optional maximum number of occurrences to return.
 * @returns An array of zero-based indices where matching characters were found.
 */
export declare function findAllCharacterOccurences(set: Set<string>, input: string, max?: number): number[];
/**
 * Finds the index of the first occurrence of any character from the set in the input string.
 *
 * @param set - The set of characters to search for.
 * @param input - The string to search through.
 * @returns The zero-based index of the first matching character, or `undefined` if none found.
 */
export declare function findFirstCharacterOccurence(set: Set<string>, input: string): Maybe<number>;
/**
 * The result of splitting a string at the first character occurence.
 *
 * The first element is the string before the split character(s).
 * The second element is the string after the split character(s), or is undefined if no split occured.
 */
export type SplitStringAtFirstCharacterOccurenceResult = [string, string | undefined];
/**
 * Splits the input string at the configured split character(s).
 */
export type SplitStringAtFirstCharacterOccurenceFunction = (input: string) => SplitStringAtFirstCharacterOccurenceResult;
/**
 * Creates a function that splits a string into two parts at the first occurrence of any character in the configured set.
 *
 * @param splitAt - A single character or set of characters to split on.
 * @returns A function that splits input strings at the first matching character.
 */
export declare function splitStringAtFirstCharacterOccurenceFunction(splitAt: string | Set<string>): SplitStringAtFirstCharacterOccurenceFunction;
/**
 * Splits the input string into two parts at the first occurrence of any character in the split set.
 *
 * @param input - The string to split.
 * @param splitAt - A single character or set of characters to split on.
 * @returns A tuple of [before, after], where `after` is `undefined` if no split character was found.
 */
export declare function splitStringAtFirstCharacterOccurence(input: string, splitAt: string | Set<string>): [string, string | undefined];
/**
 * Keeps all characters from the input string after the first character occurence pre-determined by the function.
 *
 * If no trigger characters exist, returns an empty string.
 */
export type KeepCharactersAfterFirstCharacterOccurenceFunction = (input: string) => string;
/**
 * Creates a function that returns only the characters after the first occurrence of any character in the configured set.
 *
 * @param findCharacters - A single character or set of characters to search for.
 * @returns A function that extracts the substring after the first matching character, or an empty string if none found.
 */
export declare function keepCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): KeepCharactersAfterFirstCharacterOccurenceFunction;
/**
 * Returns only the characters after the first occurrence of any character from the find set.
 *
 * @param input - The string to search through.
 * @param findCharacters - A single character or set of characters to search for.
 * @returns The substring after the first matching character, or an empty string if none found.
 */
export declare function keepCharactersAfterFirstCharacterOccurence(input: string, findCharacters: string | Set<string>): string;
/**
 * Removes all characters from the input string after the first character occurence pre-determined by the function.
 */
export type RemoveCharactersAfterFirstCharacterOccurenceFunction = (input: string) => string;
/**
 * Creates a function that removes all characters after (and including) the first occurrence of any character in the configured set.
 *
 * @param findCharacters - A single character or set of characters to search for.
 * @returns A function that truncates input strings at the first matching character.
 */
export declare function removeCharactersAfterFirstCharacterOccurenceFunction(findCharacters: string | Set<string>): RemoveCharactersAfterFirstCharacterOccurenceFunction;
/**
 * Removes all characters after (and including) the first occurrence of any character from the find set.
 *
 * @param input - The string to truncate.
 * @param findCharacters - A single character or set of characters to search for.
 * @returns The substring before the first matching character, or the full string if none found.
 */
export declare function removeCharactersAfterFirstCharacterOccurence(input: string, findCharacters: string | Set<string>): string;