@handy-common-utils/misc-utils/dist/string.d.ts

Miscellaneous utilities

export declare class StringUtils {
    /**
     * Preserve basic casing from a template single word and apply it to another word.
     *
     * Rules:
     * - If `casingTemplate` is all upper-case, return `word` in all upper-case.
     * - If `casingTemplate` is Title Case (first letter uppercase, rest lowercase), return
     *   `word` in Title Case.
     * - Otherwise return `word` as-is.
     *
     * This helper focuses on single-word tokens only and intentionally does not handle
     * complex multi-word or mixed-case patterns. Use for word-level casing preservation
     * (for example, to preserve input casing when returning a pluralized form).
     *
     * @param casingTemplate A word whose casing should be copied (e.g. 'Cat' or 'CAT')
     * @param word The word to apply casing to (usually a transformed/lowercased form)
     * @returns The `word` adjusted to match the template's basic casing
     */
    static applyWordCasing(casingTemplate: string, word: string): string;
    /**
     * Truncates a string to a specified length, optionally adding a suffix.
     * @param str The string to truncate
     * @param length Maximum length of the resulting string (including suffix if provided)
     * @param suffix Optional suffix to add to truncated string (default: '...')
     * @returns Truncated string
     */
    static truncate(str: string, length: number, suffix?: string): string;
    /**
     * Capitalises the first letter of a string, making the rest lowercase.
     * @param str The string to capitalise
     * @returns Capitalised string
     */
    static capitalise(str: string): string;
    /**
     * Capitalizes the first letter of a string, making the rest lowercase.
     * @param str The string to capitalize
     * @returns Capitalized string
     */
    static capitalize(str: string): string;
    /**
     * Converts a camelCase string to snake_case.
     * @param str The camelCase string to convert
     * @returns snake_case string
     */
    static camelToSnake(str: string): string;
    /**
     * Converts a snake_case string to camelCase.
     * @param str The snake_case string to convert
     * @returns camelCase string
     */
    static snakeToCamel(str: string): string;
    /**
     * Returns the plural form of a single English word based on the supplied count.
     *
     * Capabilities:
     * - Preserves basic input casing (using `applyWordCasing`) so e.g. "Cat" -> "Cats",
     *   "CAT" -> "CATS".
     * - Handles common irregular plurals (person->people, child->children, mouse->mice, etc.).
     * - Treats a number of nouns as uncountable (sheep, fish, species, series, news, etc.).
     * - Applies common rules: f/fe -> ves (knife->knives), consonant+y -> ies (baby->babies),
     *   words ending with s/x/z/ch/sh -> add 'es'.
     * - For words ending with 'o' there is a small exceptions list that will add 'es' (hero,
     *   potato, tomato, echo, torpedo); otherwise 's' is added.
     *
     * Limitations and notes:
     * - This is a pragmatic, rule-based implementation covering the most common English cases,
     *   not a complete linguistic solution. It does not support locales or full irregular/exception
     *   lists (many English words have irregular forms not included here).
     * - The function expects a single word token. It does not pluralize multi-word phrases or
     *   attempt to inflect verbs. Use a dedicated library (for example, the 'pluralize' npm
     *   package) if you need comprehensive, production-grade pluralization.
     * - Casing preservation is basic (all-caps and Title Case); mixed/mid-word casing (camelCase,
     *   acronyms inside words) is not fully reconstructed.
     *
     * @param word The single English word to pluralize (may be mixed case)
     * @param count The numeric count; if equal to 1 the original word is returned
     * @returns The pluralized word with basic casing preserved
     */
    static pluralise(word: string, count: number): string;
    /**
     * Returns the plural form of a single English word based on the supplied count.
     *
     * Capabilities:
     * - Preserves basic input casing (using `applyWordCasing`) so e.g. "Cat" -> "Cats",
     *   "CAT" -> "CATS".
     * - Handles common irregular plurals (person->people, child->children, mouse->mice, etc.).
     * - Treats a number of nouns as uncountable (sheep, fish, species, series, news, etc.).
     * - Applies common rules: f/fe -> ves (knife->knives), consonant+y -> ies (baby->babies),
     *   words ending with s/x/z/ch/sh -> add 'es'.
     * - For words ending with 'o' there is a small exceptions list that will add 'es' (hero,
     *   potato, tomato, echo, torpedo); otherwise 's' is added.
     *
     * Limitations and notes:
     * - This is a pragmatic, rule-based implementation covering the most common English cases,
     *   not a complete linguistic solution. It does not support locales or full irregular/exception
     *   lists (many English words have irregular forms not included here).
     * - The function expects a single word token. It does not pluralize multi-word phrases or
     *   attempt to inflect verbs. Use a dedicated library (for example, the 'pluralize' npm
     *   package) if you need comprehensive, production-grade pluralization.
     * - Casing preservation is basic (all-caps and Title Case); mixed/mid-word casing (camelCase,
     *   acronyms inside words) is not fully reconstructed.
     *
     * @param word The single English word to pluralize (may be mixed case)
     * @param count The numeric count; if equal to 1 the original word is returned
     * @returns The pluralized word with basic casing preserved
     */
    static pluralize(word: string, count: number): string;
    /**
     * Escapes special XML entities/characters in a string.
     * Replaces &, <, >, ", and ' with their corresponding XML entities.
     * Designed for performance using a single pass and lookup table.
     * @param str The string to escape for XML
     * @returns The escaped XML string
     */
    static escapeXml<T extends string | null | undefined>(str: T): T;
    /**
     * Unescapes XML entities/characters in a string.
     * Converts &amp;, &lt;, &gt;, &quot;, &apos; back to their original characters.
     * @param str The string to unescape from XML
     * @returns The unescaped string
     */
    static unescapeXml<T extends string | null | undefined>(str: T): T;
}
/**
 * Truncates a string to a specified length, optionally adding a suffix.
 * @param str The string to truncate
 * @param length Maximum length of the resulting string (including suffix if provided)
 * @param suffix Optional suffix to add to truncated string (default: '...')
 * @returns Truncated string
 */
export declare const truncate: typeof StringUtils.truncate;
/**
 * Capitalizes the first letter of a string, making the rest lowercase.
 * @param str The string to capitalize
 * @returns Capitalized string
 */
export declare const capitalize: typeof StringUtils.capitalize;
/**
 * Capitalises the first letter of a string, making the rest lowercase.
 * @param str The string to capitalise
 * @returns Capitalised string
 */
export declare const capitalise: typeof StringUtils.capitalise;
/**
 * Converts a camelCase string to snake_case.
 * @param str The camelCase string to convert
 * @returns snake_case string
 */
export declare const camelToSnake: typeof StringUtils.camelToSnake;
/**
 * Converts a snake_case string to camelCase.
 * @param str The snake_case string to convert
 * @returns camelCase string
 */
export declare const snakeToCamel: typeof StringUtils.snakeToCamel;
/**
 * Returns the plural form of a single English word based on the supplied count.
 *
 * Capabilities:
 * - Preserves basic input casing (using `applyWordCasing`) so e.g. "Cat" -> "Cats",
 *   "CAT" -> "CATS".
 * - Handles common irregular plurals (person->people, child->children, mouse->mice, etc.).
 * - Treats a number of nouns as uncountable (sheep, fish, species, series, news, etc.).
 * - Applies common rules: f/fe -> ves (knife->knives), consonant+y -> ies (baby->babies),
 *   words ending with s/x/z/ch/sh -> add 'es'.
 * - For words ending with 'o' there is a small exceptions list that will add 'es' (hero,
 *   potato, tomato, echo, torpedo); otherwise 's' is added.
 *
 * Limitations and notes:
 * - This is a pragmatic, rule-based implementation covering the most common English cases,
 *   not a complete linguistic solution. It does not support locales or full irregular/exception
 *   lists (many English words have irregular forms not included here).
 * - The function expects a single word token. It does not pluralize multi-word phrases or
 *   attempt to inflect verbs. Use a dedicated library (for example, the 'pluralize' npm
 *   package) if you need comprehensive, production-grade pluralization.
 * - Casing preservation is basic (all-caps and Title Case); mixed/mid-word casing (camelCase,
 *   acronyms inside words) is not fully reconstructed.
 *
 * @param word The single English word to pluralize (may be mixed case)
 * @param count The numeric count; if equal to 1 the original word is returned
 * @returns The pluralized word with basic casing preserved
 */
export declare const pluralize: typeof StringUtils.pluralize;
/**
 * Returns the plural form of a single English word based on the supplied count (alias).
 *
 * See `pluralize` for capabilities and limitations.
 *
 * @param word The single English word to pluralize (may be mixed case)
 * @param count The numeric count; if equal to 1 the original word is returned
 * @returns The pluralized word with basic casing preserved
 */
export declare const pluralise: typeof StringUtils.pluralise;
/**
 * Preserve basic casing from a template single word and apply it to another word.
 *
 * Rules:
 * - If `casingTemplate` is all upper-case, return `word` in all upper-case.
 * - If `casingTemplate` is Title Case (first letter uppercase, rest lowercase), return
 *   `word` in Title Case.
 * - Otherwise return `word` as-is.
 *
 * This helper focuses on single-word tokens only and intentionally does not handle
 * complex multi-word or mixed-case patterns. Use for word-level casing preservation
 * (for example, to preserve input casing when returning a pluralized form).
 *
 * @param casingTemplate A word whose casing should be copied (e.g. 'Cat' or 'CAT')
 * @param word The word to apply casing to (usually a transformed/lowercased form)
 * @returns The `word` adjusted to match the template's basic casing
 */
export declare const applyWordCasing: typeof StringUtils.applyWordCasing;
/**
 * Escapes special XML entities/characters in a string.
 * Replaces &, <, >, ", and ' with their corresponding XML entities.
 * Designed for performance using a single pass and lookup table.
 * @param str The string to escape for XML
 * @returns The escaped XML string
 */
export declare const escapeXml: typeof StringUtils.escapeXml;
/**
 * Unescapes XML entities/characters in a string.
 * Converts &amp;, &lt;, &gt;, &quot;, &apos; back to their original characters.
 * @param str The string to unescape from XML
 * @returns The unescaped string
 */
export declare const unescapeXml: typeof StringUtils.unescapeXml;
//# sourceMappingURL=string.d.ts.map