@ayonli/jsext/types/string.d.ts

A JavaScript extension package for building strong and modern applications.

/**
 * Functions for dealing with strings.
 * @module
 */
import { ByteArray } from "./bytes.ts";
/**
 * Compares two strings, returns `-1` if `a < b`, `0` if `a === b` and `1` if `a > b`.
 *
 * @example
 * ```ts
 * import { compare } from "@ayonli/jsext/string";
 *
 * console.log(compare("a", "b")); // -1
 * console.log(compare("b", "a")); // 1
 * console.log(compare("a", "a")); // 0
 * ```
 */
export declare function compare(str1: string, str2: string): -1 | 0 | 1;
/**
 * Returns a random string restricted by `length` (character-wise).
 *
 * @param chars Default value: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`.
 *
 * @example
 * ```ts
 * import { random } from "@ayonli/jsext/string";
 *
 * console.log(random(8)); // "2n8G3z1A" for example
 * console.log(random(8, "01")); // "10010101" for example
 * ```
 */
export declare function random(length: number, chars?: string): string;
/**
 * Counts the occurrence of the sub-string in the string.
 *
 * @example
 * ```ts
 * import { count } from "@ayonli/jsext/string";
 *
 * console.log(count("hello world", "o")); // 2
 * console.log(count("hello world", "i")); // 0
 * ```
 */
export declare function count(str: string, sub: string): number;
/**
 * Capitalizes the string, if `all` is true, all words are capitalized, otherwise only
 * the first word will be capitalized.
 *
 * @example
 * ```ts
 * import { capitalize } from "@ayonli/jsext/string";
 *
 * console.log(capitalize("hello world")); // Hello world
 * console.log(capitalize("hello world", true)); // Hello World
 * ```
 */
export declare function capitalize(str: string, all?: boolean): string;
/**
 * Replaces the spaces between non-empty characters of the string with hyphens (`-`).
 *
 * @example
 * ```ts
 * import { hyphenate } from "@ayonli/jsext/string";
 *
 * console.log(hyphenate("hello world")); // hello-world
 * console.log(hyphenate("hello   world")); // hello-world
 * ```
 */
export declare function hyphenate(str: string): string;
/**
 * Returns the bytes of the given string.
 * @deprecated use the `bytes` module instead.
 */
export declare function bytes(str: string): ByteArray;
/**
 * Returns the characters of the string (emojis are supported).
 *
 * @example
 * ```ts
 * import { chars } from "@ayonli/jsext/string";
 *
 * console.log(chars("Hello, World!")); // ["H", "e", "l", "l", "o", ",", " ", "W", "o", "r", "l", "d", "!"]
 * console.log(chars("你好，世界！")) // ["你", "好", "，", "世", "界", "！"]
 * console.log(chars("😴😄⛔🎠🚓🚇👨‍👨‍👧‍👧👦🏾")); // ["😴", "😄", "⛔", "🎠", "🚓", "🚇", "👨‍👨‍👧‍👧", "👦🏾"]
 * ```
 */
export declare function chars(str: string): string[];
/**
 * Extracts words (in latin characters) from the string.
 *
 * @example
 * ```ts
 * import { words } from "@ayonli/jsext/string";
 *
 * console.log(words("hello world")); // ["hello", "world"]
 * console.log(words("hello, world")); // ["hello", "world"]
 * console.log(words("hello-world")); // ["hello", "world"]
 * console.log(words("hello_world")); // ["hello", "world"]
 * ```
 */
export declare function words(str: string): string[];
/**
 * Splits the string into lines by `\n` or `\r\n`.
 *
 * @example
 * ```ts
 * import { lines } from "@ayonli/jsext/string";
 *
 * console.log(lines("hello\nworld")); // ["hello", "world"]
 * console.log(lines("hello\r\nworld")); // ["hello", "world"]
 * ```
 */
export declare function lines(str: string): string[];
/**
 * Breaks the string into smaller chunks according to the given length.
 *
 * @example
 * ```ts
 * import { chunk } from "@ayonli/jsext/string";
 *
 * console.log(chunk("hello world", 3)); // ["hel", "lo ", "wor", "ld"]
 * ```
 */
export declare function chunk(str: string, length: number): string[];
/**
 * Truncates the string to the given length (including the ending `...`).
 *
 * @example
 * ```ts
 * import { truncate } from "@ayonli/jsext/string";
 *
 * console.log(truncate("hello world", 8)); // hello...
 * console.log(truncate("hello world", 11)); // hello world
 * ```
 */
export declare function truncate(str: string, length: number): string;
/**
 * Removes leading and trailing spaces or custom characters of the string.
 *
 * @example
 * ```ts
 * import { trim } from "@ayonli/jsext/string";
 *
 * console.log(trim("  hello world  ")); // "hello world"
 * console.log(trim("  hello world!  ", " !")); // "hello world"
 * ```
 */
export declare function trim(str: string, chars?: string): string;
/**
 * Removes trailing spaces or custom characters of the string.
 *
 * @example
 * ```ts
 * import { trimEnd } from "@ayonli/jsext/string";
 *
 * console.log(trimEnd("  hello world  ")); // "  hello world"
 * console.log(trimEnd("  hello world!  ", " !")); // "  hello world"
 * ```
 */
export declare function trimEnd(str: string, chars?: string): string;
/**
 * Removes leading spaces or custom characters of the string.
 *
 * @example
 * ```ts
 * import { trimStart } from "@ayonli/jsext/string";
 *
 * console.log(trimStart("  hello world  ")); // "hello world  "
 * console.log(trimStart("  !hello world!  ", " !")); // "hello world!  "
 * ```
 */
export declare function trimStart(str: string, chars?: string): string;
/**
 * Removes the given suffix of the string if present.
 *
 * @example
 * ```ts
 * import { stripEnd } from "@ayonli/jsext/string";
 *
 * console.log(stripEnd("hello world", "world")); // "hello "
 * console.log(stripEnd("hello world", "hello")); // "hello world"
 * ```
 */
export declare function stripEnd(str: string, suffix: string): string;
/**
 * Removes the given prefix of the string if present.
 *
 * @example
 * ```ts
 * import { stripStart } from "@ayonli/jsext/string";
 *
 * console.log(stripStart("hello world", "hello")); // " world"
 * console.log(stripStart("hello world", "hi")); // "hello world"
 * ```
 */
export declare function stripStart(str: string, prefix: string): string;
/**
 * Removes extra indentation from the string.
 *
 * **NOTE:** This function also removes leading and trailing newlines.
 *
 * @example
 * ```ts
 * import { dedent } from "@ayonli/jsext/string";
 *
 * class MyClass {
 *     print() {
 *         console.log(dedent(`
 *             create table student(
 *                 id int primary key,
 *                 name text
 *             )
 *        `));
 *     }
 * }
 *
 * new MyClass().print();
 * // Output:
 * // create table student(
 * //     id int primary key,
 * //     name text
 * // )
 * ```
 */
export declare function dedent(str: string): string;
/**
 * This function can also be used as a template literal tag.
 *
 * @see https://github.com/tc39/proposal-string-dedent
 */
export declare function dedent(str: TemplateStringsArray, ...values: any[]): string;
/**
 * Returns the byte length of the string.
 *
 * @example
 * ```ts
 * import { byteLength } from "@ayonli/jsext/string";
 *
 * console.log(byteLength("hello world")); // 11
 * console.log(byteLength("你好，世界！")); // 18
 * ```
 */
export declare function byteLength(str: string): number;
/** Checks if all characters in the string are within the ASCII range. */
export declare function isAscii(str: string, printableOnly?: boolean): boolean;
/** Checks if all characters in the string are emojis. */
export declare function isEmoji(str: string): boolean;