@tempots/std/string.d.ts

Std library for TypeScript. Natural complement to the Tempo libraries.

/**
 * Utility functions to manipulate string values.
 *
 * Use by importing the desired utility from "@tempots/std" or directly from "@tempots/std/string".
 * @public
 */
/**
 * `substringAfter` searches for the first occurrance of `searchFor` and returns the text after that.
 * If `searchFor` is not found, an empty string is returned.
 *
 * @param value - The string to search in.
 * @param searchFor - The string to search for.
 * @returns The text after the first occurrance of `searchFor` or an empty string if `searchFor` is not found.
 * @public
 */
export declare const substringAfter: (value: string, searchFor: string) => string;
/**
 * `substringAfterLast` searches for the last occurrance of `searchFor` and returns the text after that.
 * If `searchFor` is not found, an empty string is returned.
 *
 * @param value - The string to search in.
 * @param searchFor - The string to search for.
 * @returns The text after the last occurrance of `searchFor` or an empty string if `searchFor` is not found.
 * @public
 */
export declare const substringAfterLast: (value: string, searchFor: string) => string;
/**
 * `substringBefore` searches for the first occurrance of `searchFor` and returns the text before that.
 * If `searchFor` is not found, an empty string is returned.
 *
 * @param value - The string to search in.
 * @param searchFor - The string to search for.
 * @returns The text before the first occurrance of `searchFor` or an empty string if `searchFor` is not found.
 * @public
 */
export declare const substringBefore: (value: string, searchFor: string) => string;
/**
 * `substringBeforeLast` searches for the last occurrance of `searchFor` and returns the text before that.
 * If `searchFor` is not found, an empty string is returned.
 *
 * @param value - The string to search in.
 * @param searchFor - The string to search for.
 * @returns The text before the last occurrance of `searchFor` or an empty string if `searchFor` is not found.
 * @public
 */
export declare const substringBeforeLast: (value: string, searchFor: string) => string;
/**
 * `capitalize` returns a string with the first character convert to upper case.
 *
 * @param s - The string to capitalize.
 * @returns The capitalized string.
 * @public
 */
export declare const capitalize: (s: string) => string;
/**
 * Capitalize the first letter of every word in `value`. If `whiteSpaceOnly` is set to `true`
 * the process is limited to whitespace separated words.
 *
 * @param value - The string to capitalize.
 * @param whiteSpaceOnly - If `true`, only whitespace separated words will be capitalized.
 * @returns The string with the first letter of each word capitalized.
 * @public
 */
export declare const capitalizeWords: (value: string, whiteSpaceOnly?: boolean) => string;
/**
 * Replaces occurrances of `\r\n`, `\n\r`, `\r` with `\n`
 *
 * @param value - The string to normalize.
 * @returns The string with normalized line endings.
 * @public
 */
export declare const canonicalizeNewlines: (value: string) => string;
/**
 * Compares two strings ignoring their case.
 *
 * @param a - The first string to compare.
 * @param b - The second string to compare.
 * @returns A negative number if `a` is less than `b`, zero if they are equal, or a positive number if `a` is greater than `b`.
 * @public
 */
export declare const compareCaseInsensitive: (a: string | null | undefined, b: string | null | undefined) => number;
/**
 * Checks if a string ends with another string in a case-insensitive manner.
 *
 * @param s - The string to check.
 * @param end - The string to check if it is the ending of `s`.
 * @returns `true` if `s` ends with `end` (case-insensitive), otherwise `false`.
 * @public
 */
export declare const textEndsWithCaseInsensitive: (s: string, end: string) => boolean;
/**
 * Checks if a string starts with another string in a case-insensitive manner.
 *
 * @param s - The string to check.
 * @param start - The string to compare with the start of `s`.
 * @returns `true` if `s` starts with `start` (case-insensitive), `false` otherwise.
 * @public
 */
export declare const textStartsWithCaseInsensitive: (s: string, start: string) => boolean;
/**
 * Compares a string `s` with many `values` and see if one of them matches its end ignoring their case.
 *
 * @param s - The string to compare.
 * @param values - The values to compare with the end of `s`.
 * @returns `true` if `s` ends with any of the values in `values` (case-insensitive), `false` otherwise.
 * @public
 */
export declare const textEndsWithAnyCaseInsensitive: (s: string, values: string[]) => boolean;
/**
 * Compares a string `s` with many `values` and see if one of them matches its beginning ignoring their case.
 *
 * @param s - The string to compare.
 * @param values - The values to compare with the start of `s`.
 * @returns `true` if `s` starts with any of the values in `values` (case-insensitive), `false` otherwise.
 * @public
 */
export declare const textStartsWithAnyCaseInsensitive: (s: string, values: string[]) => boolean;
/**
 * It cleans up all the whitespaces in the passed `value`. `collapse` does the following:
 * - remove trailing/leading whitespaces
 * - within the string, it collapses seqeunces of whitespaces into a single space character
 * For whitespaces in this description, it is intended to be anything that is matched by the regular expression `\s`.
 *
 * @param value - The string to collapse.
 * @returns The string with all whitespaces collapsed.
 * @public
 */
export declare const collapseText: (value: string) => string;
/**
 * It compares to string and it returns a negative number if `a` is inferior to `b`, zero if they are the same,
 * or otherwise a positive non-sero number.
 *
 * @param a - The first string to compare.
 * @param b - The second string to compare.
 * @returns A negative number if `a` is less than `b`, zero if they are equal, or a positive number if `a` is greater than `b`.
 * @public
 */
export declare const compareStrings: (a: string, b: string) => number;
/**
 * `textContainsCaseInsensitive` returns `true` if `s` contains one or more occurrences of `test` regardless of the text case.
 *
 * @param s - The string to search in.
 * @param test - The string to search for.
 * @returns `true` if `s` contains `test` (case-insensitive), `false` otherwise.
 * @public
 */
export declare const textContainsCaseInsensitive: (s: string, test: string) => boolean;
/**
 * Return the number of occurrences of `test` in `s`.
 *
 * @param s - The string to search in.
 * @param test - The string to search for.
 * @returns The number of occurrences of `test` in `s`.
 * @public
 */
export declare const countStringOccurrences: (s: string, test: string) => number;
/**
 * `containsAnyTextCaseInsensitive` returns `true` if `s` contains any of the strings in `tests` regardless of the text case
 *
 * @param s - The string to search in.
 * @param tests - The strings to search for.
 * @returns `true` if `s` contains any of the strings in `tests` (case-insensitive), `false` otherwise.
 * @public
 */
export declare const containsAnyTextCaseInsensitive: (s: string, tests: string[]) => boolean;
/**
 * `containsAnyText` returns `true` if `s` contains any of the strings in `tests`
 *
 * @param s - The string to search in.
 * @param tests - The strings to search for.
 * @returns `true` if `s` contains any of the strings in `tests`, `false` otherwise.
 * @public
 */
export declare const containsAnyText: (s: string, tests: string[]) => boolean;
/**
 * `containsAllTextCaseInsensitive` returns `true` if `s` contains all of the strings in `tests` regardless of the text case
 *
 * @param s - The string to search in.
 * @param tests - The strings to search for.
 * @returns `true` if `s` contains all of the strings in `tests` (case-insensitive), `false` otherwise.
 * @public
 */
export declare const containsAllTextCaseInsensitive: (s: string, tests: string[]) => boolean;
/**
 * `containsAllText` returns `true` if `s` contains all of the strings in `tests`
 *
 * @param s - The string to search in.
 * @param tests - The strings to search for.
 * @returns `true` if `s` contains all of the strings in `tests`, `false` otherwise.
 * @public
 */
export declare const containsAllText: (s: string, tests: string[]) => boolean;
/**
 * `dasherize` replaces all the occurrances of `_` with `-`
 *
 * @param s - The string to dasherize.
 * @returns The dasherized string.
 * @public
 */
export declare const dasherize: (s: string) => string;
/**
 * Compares strings `a` and `b` and returns the position where they differ.
 * If the strings are equal, it returns `-1`.
 *
 * @example
 * ```ts
 * stringsDifferAtIndex('abcdef', 'abc123') // returns 3
 * ```
 * @public
 *
 * @param a - The first string to compare.
 * @param b - The second string to compare.
 * @returns The position where the strings differ, or `-1` if they are equal.
 *
 */
export declare const stringsDifferAtIndex: (a: string, b: string) => number;
/**
 * `ellipsis` truncates `s` at len `maxlen` replaces the last characters with the content
 * of `symbol`.
 *
 * @example
 * ```ts
 * ellipsis('tempo is a nice library', 9) // returns 'tempo is …'
 * ```
 *
 * @param s - The string to truncate.
 * @param maxlen - The maximum length of the string.
 * @param symbol - The symbol to replace the truncated characters with.
 * @returns The truncated string.
 * @public
 */
export declare const ellipsis: (s: string, maxlen?: number, symbol?: string) => string;
/**
 * Same as `ellipsis` but puts the symbol in the middle of the string and not to the end.
 *
 * @example
 * ```ts
 * ellipsisMiddle('tempo is a nice library', 18) // returns 'tempo is … library'
 * ```
 *
 * @param s - The string to truncate.
 * @param maxlen - The maximum length of the string.
 * @param symbol - The symbol to replace the truncated characters with.
 * @returns The truncated string.
 * @public
 */
export declare const ellipsisMiddle: (s: string, maxlen?: number, symbol?: string) => string;
/**
 * Returns `true` if `s` ends with any of the values in `values`.
 *
 * @param s - The string to compare.
 * @param values - The values to compare with the end of `s`.
 * @returns `true` if `s` ends with any of the values in `values`, `false` otherwise.
 * @public
 */
export declare const stringEndsWithAny: (s: string, values: string[]) => boolean;
/**
 * `filterString` applies `predicate` character by character to `s` and it returns a filtered
 * version of the string.
 *
 * @param s - The string to filter.
 * @param predicate - The function to apply to each character in the string.
 * @returns The filtered string.
 * @public
 */
export declare const filterChars: (s: string, predicate: (s: string) => boolean) => string;
/**
 * Same as `filterCharcodes` but `predicate` operates on integer char codes instead of string characters.
 *
 * @param s - The string to filter.
 * @param predicate - The function to apply to each character code in the string.
 * @returns The filtered string.
 * @public
 */
export declare const filterCharcodes: (s: string, predicate: (n: number) => boolean) => string;
/**
 * Calculates the hash code for a given string.
 *
 * @param value - The string to calculate the hash code for.
 * @param seed - The seed value for the hash code calculation. Default is 0x811c9dc5.
 * @returns The calculated hash code as a number.
 * @public
 */
export declare const stringHashCode: (value: string, seed?: number) => number;
/**
 * Returns `true` if `value` is not `null` and contains at least one character.
 *
 * @param value - The string to check.
 * @returns `true` if the string is not `null` and contains at least one character, `false` otherwise.
 * @public
 */
export declare const stringHasContent: (value: string) => boolean;
/**
 * Works the same as `underscore` but also replaces underscores with whitespaces.
 *
 * @param s - The string to convert.
 * @returns The converted string.
 * @public
 */
export declare const humanize: (s: string) => string;
/**
 * Checks if `s` contains only (and at least one) alphabetical characters.
 *
 * @param s - The string to check.
 * @returns `true` if the string contains only alphabetical characters, `false` otherwise.
 * @public
 */
export declare const isAlpha: (s: string) => boolean;
/**
 * `isAlphaNum` returns `true` if the string only contains alpha-numeric characters.
 *
 * @param value - The string to check.
 * @returns `true` if the string contains only alpha-numeric characters, `false` otherwise.
 * @public
 */
export declare const isAlphaNum: (value: string) => boolean;
/**
 * Checks if a string contains any breaking whitespace characters.
 *
 * @param value - The string to check.
 * @returns `true` if the string contains breaking whitespace characters, `false` otherwise.
 * @public
 */
export declare const isBreakingWhitespace: (value: string) => boolean;
/**
 * Returns `true` if the value string is composed of only lower cased characters
 * or case neutral characters.
 *
 * @param value - The string to check.
 * @returns `true` if the string contains only lower case characters, `false` otherwise.
 * @public
 */
export declare const isLowerCase: (value: string) => boolean;
/**
 * Returns `true` if the value string is composed of only upper cased characters
 * or case neutral characters.
 *
 * @param value - The string to check.
 * @returns `true` if the string contains only upper case characters, `false` otherwise.
 * @public
 */
export declare const isUpperCase: (value: string) => boolean;
/**
 * `ifEmpty` returns `value` if it is neither `null` or empty, otherwise it returns `alt`
 *
 * @param value - The string to check.
 * @param alt - The alternative value to return if `value` is `null` or empty.
 * @returns The original string if it is not `null` or empty, otherwise the alternative value.
 * @public
 */
export declare const ifEmptyString: (value: string, alt: string) => string;
/**
 * `isDigitsOnly` returns `true` if the string only contains digits.
 *
 * @param value - The string to check.
 * @returns `true` if the string contains only digits, `false` otherwise.
 * @public
 */
export declare const isDigitsOnly: (value: string) => boolean;
/**
 * `isEmpty` returns true if either `value` is null or is an empty string.
 *
 * @param value - The string to check.
 * @returns `true` if the string is `null` or empty, `false` otherwise.
 * @public
 */
export declare const isEmptyString: (value: string) => boolean;
/**
 * Convert first letter in `value` to lower case.
 *
 * @param value - The string to convert.
 * @returns The string with the first letter in lower case.
 * @public
 */
export declare const lowerCaseFirst: (value: string) => string;
/**
 * Returns a random substring from the `value` argument. The length of such value is by default `1`.
 *
 * @param value - The string to extract the random substring from.
 * @param length - The length of the random substring to extract.
 * @returns The random substring.
 * @public
 */
export declare const randomSubString: (value: string, length?: number) => string;
/**
 * Returns a random sampling of the specified length from the seed string.
 *
 * @param alphabet - The seed string to sample from.
 * @param length - The length of the random string to generate.
 * @returns The random string.
 * @public
 */
export declare const randomStringSequence: (alphabet: string, length: number) => string;
/**
 * Like `randomSequence`, but automatically uses the base64 sequence as the seed string.
 *
 * @param length - The length of the random string to generate.
 * @returns The random string.
 * @public
 */
export declare const randomStringSequenceBase64: (length: number) => string;
/**
 * It maps a string character by character using `callback`.
 *
 * @param callback - The function to apply to each character in the string.
 * @param value - The string to map.
 * @returns An array of the mapped characters.
 * @public
 */
export declare const mapChars: <T>(callback: (c: string) => T, value: string) => T[];
/**
 * If present, it removes all the occurrences of `toremove` from `value`.
 *
 * @param value - The string to remove the occurrences from.
 * @param toremove - The string to remove from `value`.
 * @returns The string with all occurrences of `toremove` removed.
 * @public
 */
export declare const deleteSubstring: (value: string, toremove: string) => string;
/**
 * If present, it removes the `toremove` text from the end of `value`.
 *
 * @param value - The string to remove the text from.
 * @param toremove - The text to remove from the end of `value`.
 * @returns The string with the text removed.
 * @public
 */
export declare const deleteStringAfter: (value: string, toremove: string) => string;
/**
 * Removes a slice from `index` to `index + length` from `value`.
 *
 * @param value - The string to remove the slice from.
 * @param index - The starting index of the slice to remove.
 * @param length - The length of the slice to remove.
 * @returns The string with the slice removed.
 * @public
 */
export declare const trimStringSlice: (value: string, index: number, length: number) => string;
/**
 * If present, it removes the `toremove` text from the beginning of `value`.
 *
 * @param value - The string to remove the text from.
 * @param toremove - The text to remove from the beginning of `value`.
 * @returns The string with the text removed.
 * @public
 */
export declare const deleteStringBefore: (value: string, toremove: string) => string;
/**
 * If present, it removes the first occurrence of `toremove` from `value`.
 *
 * @param value - The string to remove the text from.
 * @param toremove - The text to remove from `value`.
 * @returns The string with the text removed.
 * @public
 */
export declare const deleteFirstFromString: (value: string, toremove: string) => string;
/**
 * Returns a new string whose characters are in reverse order.
 *
 * @param s - The string to reverse.
 * @returns The reversed string.
 * @public
 */
export declare const reverseString: (s: string) => string;
/**
 * Converts a string in a quoted string.
 *
 * @param s - The string to quote.
 * @param prefer - The preferred quote character. Defaults to single quote (`'`).
 * @returns The quoted string.
 * @public
 */
export declare const smartQuote: (s: string, prefer?: string) => string;
/**
 * Returns a quoted version of the input string.
 *
 * @param s - The input string to be quoted.
 * @param quoteChar - The character used for quoting. Defaults to single quote (').
 * @returns The quoted string.
 * @public
 */
export declare const quote: (s: string, quoteChar?: string) => string;
/**
 * Quotes a string for use in JavaScript code.
 * If the string contains a newline character, it will be quoted using backticks.
 * Otherwise, it will be quoted using single quotes (`'`) or double quotes (`"`) based on the `prefer` parameter.
 *
 * @param s - The string to be quoted.
 * @param prefer - The preferred quote character. Defaults to single quote (`'`).
 * @returns The quoted string.
 * @public
 */
export declare const jsQuote: (s: string, prefer?: string) => string;
/**
 * It only splits on the first occurrance of separator.
 *
 * @param s - The string to split.
 * @param separator - The separator to split the string on.
 * @returns An array with the split string.
 * @public
 */
export declare const splitStringOnce: (s: string, separator: string) => [string] | [string, string];
/**
 * Returns `true` if `s` starts with any of the values in `values`.
 *
 * @param s - The string to compare.
 * @param values - The values to compare with the start of `s`.
 * @returns `true` if `s` starts with any of the values in `values`, `false` otherwise.
 * @public
 */
export declare const stringStartsWithAny: (s: string, values: string[]) => boolean;
/**
 * Surrounds a string with the contents of `left` and `right`. If `right` is omitted,
 * `left` will be used on both sides
 *
 * @param s - The string to surround.
 * @param left - The left side of the surrounding text.
 * @param right - The right side of the surrounding text. Defaults to `left`.
 * @returns The surrounded string.
 * @public
 */
export declare const surroundString: (s: string, left: string, right?: string) => string;
/**
 * It transforms a string into an `Array` of char codes in integer format.
 *
 * @param s - The string to transform.
 * @returns An array of char codes.
 * @public
 */
export declare const stringToCharcodes: (s: string) => number[];
/**
 * Returns an array of `string` whose elements are equally long (using `len`). If the string `s`
 * is not exactly divisible by `len` the last element of the array will be shorter.
 *
 * @param s - The string to chunk.
 * @param len - The length of each chunk.
 * @returns An array of chunks.
 * @public
 */
export declare const chunkString: (s: string, len: number) => string[];
/**
 * Returns an array of `string` split by line breaks.
 *
 * @param s - The string to split.
 * @returns An array of lines.
 * @public
 */
export declare const textToLines: (s: string) => string[];
/**
 * `trimChars` removes from the beginning and the end of the string any character that is present in `charlist`.
 *
 * @param value - The string to trim.
 * @param charlist - The characters to remove from the beginning and end of the string.
 * @returns The trimmed string.
 * @public
 */
export declare const trimChars: (value: string, charlist: string) => string;
/**
 * `trimCharsLeft` removes from the beginning of the string any character that is present in `charlist`.
 *
 * @param value - The string to trim.
 * @param charlist - The characters to remove from the beginning of the string.
 * @returns The trimmed string.
 * @public
 */
export declare const trimCharsLeft: (value: string, charlist: string) => string;
/**
 * `trimCharsRight` removes from the end of the string any character that is present in `charlist`.
 *
 * @param value - The string to trim.
 * @param charlist - The characters to remove from the end of the string.
 * @returns The trimmed string.
 * @public
 */
export declare const trimCharsRight: (value: string, charlist: string) => string;
/**
 * `underscore` finds UpperCase characters and turns them into LowerCase and prepends them with a whtiespace.
 * Sequences of more than one UpperCase character are left untouched.
 *
 * @param s - The string to underscore.
 * @returns The underscored string.
 * @public
 */
export declare const underscore: (s: string) => string;
/**
 * Convert first letter in `value` to upper case.
 *
 * @param value - The string to convert.
 * @returns The string with the first letter in upper case.
 * @public
 */
export declare const upperCaseFirst: (value: string) => string;
/**
 * `wrapColumns` splits a long string into lines that are at most `columns` long.
 * Individual words whose length exceeds `columns` are not split.
 *
 * @param s - The string to wrap.
 * @param columns - The number of columns per line.
 * @param indent - The indentation string to prepend to each line.
 * @param newline - The newline character to use for line breaks.
 * @returns The wrapped string.
 * @public
 */
export declare const wrapColumns: (s: string, columns?: number, indent?: string, newline?: string) => string;
/**
 * Checks if the character at the specified position in a string is a whitespace character.
 *
 * @param s - The input string.
 * @param pos - The position of the character to check.
 * @returns A boolean indicating whether the character at the specified position is a whitespace character.
 * @public
 */
export declare const isSpaceAt: (s: string, pos: number) => boolean;
/**
 * Encodes a string to base64.
 *
 * @param s - The string to encode.
 * @returns The base64 encoded string.
 * @throws Throws `MissingImplementationError` if no implementation is found for base64 encoding.
 * @public
 */
export declare const encodeBase64: (s: string) => string;
/**
 * Decodes a base64 encoded string.
 *
 * @param s - The base64 encoded string to decode.
 * @returns The decoded string.
 * @throws Throws a `MissingImplementationError` if no implementation is found for base64 decoding.
 * @public
 */
export declare const decodeBase64: (s: string) => string;
/**
 * Wraps a string into multiple lines based on the specified number of columns,
 * indentation, and newline character.
 *
 * @param s - The string to wrap.
 * @param columns - The number of columns per line.
 * @param indent - The indentation string to prepend to each line.
 * @param newline - The newline character to use for line breaks.
 * @returns The wrapped string.
 * @public
 */
export declare const wrapLine: (s: string, columns: number, indent: string, newline: string) => string;
/**
 * Pads a string on the left with a specified character until it reaches a specified length.
 * If the string is already longer than the specified length, it is returned as is.
 *
 * @param s - The string to pad.
 * @param char - The character to use for padding.
 * @param length - The desired length of the padded string.
 * @returns The padded string.
 * @public
 */
export declare const lpad: (s: string, char: string, length: number) => string;
/**
 * Pads a string on the right with a specified character until it reaches a specified length.
 * If the string is already longer than the specified length, it is returned as is.
 *
 * @param s - The string to pad.
 * @param char - The character to use for padding.
 * @param length - The desired length of the padded string.
 * @returns The padded string.
 * @public
 */
export declare const rpad: (s: string, char: string, length: number) => string;
/**
 * Splits a string into two parts at the last occurrence of a specified substring.
 * If the substring is found, the function returns an array with two elements:
 * the part of the string before the substring and the part after the substring.
 * If the substring is not found, the function returns an array with a single element,
 * which is the original string.
 *
 * @param s - The string to split.
 * @param find - The substring to search for.
 * @returns An array containing the split parts of the string.
 * @public
 */
export declare const splitStringOnLast: (s: string, find: string) => [string] | [string, string];
/**
 * Splits a string into two parts based on the first occurrence of a specified substring.
 * If the substring is found, returns an array with two elements: the part of the string before the substring and the part after the substring.
 * If the substring is not found, returns an array with a single element: the original string.
 *
 * @param s - The string to split.
 * @param find - The substring to search for.
 * @returns An array containing the split parts of the string.
 * @public
 */
export declare const splitStringOnFirst: (s: string, find: string) => [string] | [string, string];