@tempots/std 0.11.0 → 0.13.0

package/string.d.ts

@@ -1,314 +1,751 @@
 /**
  * Utility functions to manipulate string values.
+ *
+ * Use by importing the desired utility from "@tempots/std" or directly from "@tempots/std/string".
+ * @public
  */
 /**
  * Replaces all occurrances of `placeholder` in `subject` with the value `replacement`.
- * @param subject
- * @param placeholder
- * @param replacement
+ * @param subject - The string to search in.
+ * @param placeholder - The string to search for.
+ * @param replacement - The string to replace `placeholder` with.
+ * @returns The string with all occurrances of `placeholder` replaced by `replacement`.
+ * @public
  */
-export declare function replace(subject: string, placeholder: string, replacement: string): string;
+export declare function replaceAll(subject: string, placeholder: string, replacement: string): string;
 /**
- * `after` searches for the first occurrance of `searchFor` and returns the text after that.
+ * `afterText` 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 function after(value: string, searchFor: string): string;
+export declare function afterText(value: string, searchFor: string): string;
 /**
- * `afterLast` searches for the last occurrance of `searchFor` and returns the text after that.
+ * `afterLastText` 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 function afterLast(value: string, searchFor: string): string;
+export declare function afterLastText(value: string, searchFor: string): string;
 /**
- * `before` searches for the first occurrance of `searchFor` and returns the text before that.
+ * `beforeText` 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 function before(value: string, searchFor: string): string;
+export declare function beforeText(value: string, searchFor: string): string;
 /**
- * `beforeLast` searches for the last occurrance of `searchFor` and returns the text before that.
+ * `beforeLastText` 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 function beforeLast(value: string, searchFor: string): string;
+export declare function beforeLastText(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 function 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 function 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 function 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 function compareCaseInsensitive(a: string, b: string): number;
-export declare function endsWith(s: string, end: string): boolean;
-export declare function endsWithCaseInsensitive(s: string, end: string): boolean;
-export declare function startsWith(s: string, start: string): boolean;
-export declare function startsWithCaseInsensitive(s: string, start: string): boolean;
 /**
- * Compares a string `s` with many `values` and see if one of them matches its end ignoring their case.
- */
-export declare function endsWithAnyCaseInsensitive(s: string, values: string[]): boolean;
-/**
- * Compares a string `s` with many `values` and see if one of them matches its beginning ignoring their case.
- */
-export declare function startsWithAnyCaseInsensitive(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`.
- */
-export declare function collapse(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.
+ * Checks if a string ends with a specified suffix.
+ *
+ * @param s - The string to check.
+ * @param end - The suffix to check against.
+ * @returns `true` if the string ends with the specified suffix, `false` otherwise.
+ * @public
  */
-export declare function compare(a: string, b: string): number;
+export declare function textEndsWith(s: string, end: string): boolean;
 /**
- * `contains` returns `true` if `s` contains one or more occurrences of `test` regardless of the text case.
+ * 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 function containsCaseInsensitive(s: string, test: string): boolean;
+export declare function textEndsWithCaseInsensitive(s: string, end: string): boolean;
 /**
- * `contains` returns `true` if `s` contains one or more occurrences of `test`.
+ * Checks if a string starts with a specified substring.
+ *
+ * @param s - The string to check.
+ * @param start - The substring to check for at the beginning of the string.
+ * @returns `true` if the string starts with the specified substring, `false` otherwise.
+ * @public
  */
-export declare function contains(s: string, test: string): boolean;
+export declare function textStartsWith(s: string, start: string): boolean;
 /**
- * Return the number of occurances of `test` in `s`.
+ * 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 function count(s: string, test: string): number;
+export declare function textStartsWithCaseInsensitive(s: string, start: string): boolean;
 /**
- * `contains` returns `true` if `s` contains any of the strings in `tests` regardless of the text case
+ * 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 function containsAnyCaseInsensitive(s: string, tests: string[]): boolean;
+export declare function textEndsWithAnyCaseInsensitive(s: string, values: string[]): boolean;
 /**
- * `contains` returns `true` if `s` contains any of the strings in `tests`
+ * 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 function containsAny(s: string, tests: string[]): boolean;
+export declare function textStartsWithAnyCaseInsensitive(s: string, values: string[]): boolean;
 /**
- * `contains` returns `true` if `s` contains all of the strings in `tests` regardless of the text case
+ * 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 function containsAllCaseInsensitive(s: string, tests: string[]): boolean;
+export declare function textCollapse(value: string): string;
 /**
- * `contains` returns `true` if `s` contains all of the strings in `tests`
- */
-export declare function containsAll(s: string, tests: string[]): boolean;
+ * 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 function 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 function textContainsCaseInsensitive(s: string, test: string): boolean;
+/**
+ * `textContains` returns `true` if `s` contains one or more occurrences of `test`.
+ *
+ * @param s - The string to search in.
+ * @param test - The string to search for.
+ * @returns `true` if `s` contains `test`, `false` otherwise.
+ * @public
+ */
+export declare function textContains(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 function countTextOccurrences(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 function 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 function 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 function 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 function 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 function dasherize(s: string): string;
 /**
  * Compares strings `a` and `b` and returns the position where they differ.
+ * If the strings are equal, it returns `-1`.
+ *
+ * @remarks
+ * @example
  * ```ts
- * diffIndex('abcdef', 'abc123') // returns 3
+ * 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 function diffIndex(a: string, b: string): number;
+export declare function stringsDifferAtIndex(a: string, b: string): number;
 /**
  * `ellipsis` truncates `s` at len `maxlen` replaces the last characters with the content
  * of `symbol`.
+ *
+ * @remarks
+ * @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 function 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.
+ *
+ * @remarks
+ * @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 function 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 function endsWithAny(s: string, values: string[]): boolean;
+export declare function endsWithAnyText(s: string, values: string[]): boolean;
 /**
- * `filter` applies `predicate` character by character to `s` and it returns a filtered
+ * `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 function filter(s: string, predicate: (s: string) => boolean): string;
+export declare function filterText(s: string, predicate: (s: string) => boolean): string;
 /**
- * Same as `filter` but `predicate` operates on integer char codes instead of string characters.
+ * Same as `filterCharcode` 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 function filterCharcode(s: string, predicate: (n: number) => boolean): string;
 /**
- * `from` searches for the first occurrance of `searchFor` and returns the text from that point on.
- * If `searchFor` is not found, an empty string is returned.
+ * 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 function from(value: string, searchFor: string): string;
-export declare function hashCode(value: string, seed?: number): number;
+export declare function 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 function hasContent(value: string): boolean;
+export declare function 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 function 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 function 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 function 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 function 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 function 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 function 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 function ifEmpty(value: string, alt: string): string;
+export declare function 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 function 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 function isEmpty(value: string): boolean;
+export declare function 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 function 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 function random(value: string, length?: number): string;
+export declare function randomString(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 function randomSequence(alphabet: string, length: number): string;
+export declare function 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 function randomSequence64(length: number): string;
+export declare function 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 function map<T>(callback: (c: string) => T, value: string): T[];
+export declare function 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 function remove(value: string, toremove: string): string;
+export declare function removeFromString(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 function removeAfter(value: string, toremove: string): string;
+export declare function removeFromStringAfter(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 function removeAt(value: string, index: number, length: number): string;
+export declare function removeSliceFromString(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 function removeBefore(value: string, toremove: string): string;
+export declare function removeFromStringBefore(value: string, toremove: string): string;
 /**
  * If present, it removes the first occurrence of `toremove` from `value`.
- */
-export declare function removeOne(value: string, toremove: string): string;
-/**
- * `repeat` builds a new string by repeating the argument `s`, n `times`.
+ *
+ * @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 function removeFirstFromString(value: string, toremove: string): string;
+/**
+ * `repeatString` builds a new string by repeating the argument `s`, n `times`.
+ *
+ * @remarks
+ * @example
  * ```ts
- * repeat('Xy', 3) // generates 'XyXyXy'
+ * repeatString('Xy', 3) // generates 'XyXyXy'
  * ```
+ *
+ * @param s - The string to repeat.
+ * @param times - The number of times to repeat the string.
+ * @returns The repeated string.
+ * @public
  */
-export declare function repeat(s: string, times: number): string;
+export declare function repeatString(s: string, times: number): string;
 /**
  * Returns a new string whose characters are in reverse order.
+ *
+ * @param s - The string to reverse.
+ * @returns The reversed string.
+ * @public
  */
-export declare function reverse(s: string): string;
+export declare function 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 function 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 function 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 function 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 function splitOnce(s: string, separator: string): [string] | [string, string];
+export declare function 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 function startsWithAny(s: string, values: string[]): boolean;
-/**
- * `stripTags` removes any HTML/XML markup from the string leaving only the concatenation
- * of the existing text nodes.
- */
-export declare function stripTags(s: string): string;
+export declare function textStartsWithAny(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 function surround(s: string, left: string, right?: string): string;
+export declare function surroundText(s: string, left: string, right?: string): string;
 /**
  * It transforms a string into an `Array` of characters.
+ *
+ * @param s - The string to transform.
+ * @returns An array of characters.
+ * @public
  */
-export declare function toArray(s: string): string[];
+export declare function stringToChars(s: 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 function toCharcodes(s: string): number[];
+export declare function 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 function toChunks(s: string, len: number): string[];
+export declare function chunkText(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 function toLines(s: string): string[];
+export declare function stringToLines(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 function 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 function 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 function 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 function 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 function upperCaseFirst(value: string): string;
-/**
- * `upTo` searches for the first occurrance of `searchFor` and returns the text up to that point.
- * If `searchFor` is not found, the entire string is returned.
- */
-export declare function upTo(value: string, searchFor: string): string;
 /**
  * `wrapColumns` splits a long string into lines that are at most `columns` long.
- * Words whose length exceeds `columns` are not split.
+ * 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 function 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 function isSpaceAt(s: string, pos: number): boolean;
+/**
+ * Encodes a string to base64.
+ *
+ * @param s - The string to encode.
+ * @returns The base64 encoded string.
+ * @throws Error if no implementation is found for base64 encoding.
+ * @public
+ */
 export declare function encodeBase64(s: string): string;
+/**
+ * Decodes a base64 encoded string.
+ *
+ * @param s - The base64 encoded string to decode.
+ * @returns The decoded string.
+ * @throws An error if no implementation is found for base64 decoding.
+ * @public
+ */
 export declare function 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 function 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 function 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 function 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 function splitOnLast(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 function splitOnFirst(s: string, find: string): [string] | [string, string];