@tempots/std 0.10.7 → 0.12.0

package/string.d.ts

@@ -1,60 +1,104 @@
 /**
  * Utility functions to manipulate string values.
+ * @public
  */
 /**
  * Replaces all occurrances of `placeholder` in `subject` with the value `replacement`.
- * @param subject
- * @param placeholder
- * @param replacement
+ * @param subject -
+ * @param placeholder -
+ * @param replacement -
+ * @public
  */
 export declare function replace(subject: string, placeholder: string, replacement: string): string;
 /**
  * `after` searches for the first occurrance of `searchFor` and returns the text after that.
  * If `searchFor` is not found, an empty string is returned.
+ * @public
  */
 export declare function after(value: string, searchFor: string): string;
 /**
  * `afterLast` searches for the last occurrance of `searchFor` and returns the text after that.
  * If `searchFor` is not found, an empty string is returned.
+ * @public
  */
 export declare function afterLast(value: string, searchFor: string): string;
 /**
  * `before` searches for the first occurrance of `searchFor` and returns the text before that.
  * If `searchFor` is not found, an empty string is returned.
+ * @public
  */
 export declare function before(value: string, searchFor: string): string;
 /**
  * `beforeLast` searches for the last occurrance of `searchFor` and returns the text before that.
  * If `searchFor` is not found, an empty string is returned.
+ * @public
  */
 export declare function beforeLast(value: string, searchFor: string): string;
 /**
  * `capitalize` returns a string with the first character convert to upper case.
+ * @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.
+ * @public
  */
 export declare function capitalizeWords(value: string, whiteSpaceOnly?: boolean): string;
 /**
  * Replaces occurrances of `\r\n`, `\n\r`, `\r` with `\n`
+ * @public
  */
 export declare function canonicalizeNewlines(value: string): string;
 /**
  * Compares two strings ignoring their case.
+ * @public
  */
 export declare function compareCaseInsensitive(a: string, b: string): 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 endsWith(s: string, end: string): boolean;
+/**
+ * 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 endsWithCaseInsensitive(s: string, end: string): boolean;
+/**
+ * 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 startsWith(s: string, start: 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 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.
+ * @public
  */
 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.
+ * @public
  */
 export declare function startsWithAnyCaseInsensitive(s: string, values: string[]): boolean;
 /**
@@ -62,50 +106,63 @@ export declare function startsWithAnyCaseInsensitive(s: string, values: string[]
  * - 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`.
+ * @public
  */
 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.
+ * @public
  */
-export declare function compare(a: string, b: string): number;
+export declare function compareStrings(a: string, b: string): number;
 /**
  * `contains` returns `true` if `s` contains one or more occurrences of `test` regardless of the text case.
+ * @public
  */
 export declare function containsCaseInsensitive(s: string, test: string): boolean;
 /**
  * `contains` returns `true` if `s` contains one or more occurrences of `test`.
+ * @public
  */
 export declare function contains(s: string, test: string): boolean;
 /**
  * Return the number of occurances of `test` in `s`.
+ * @public
  */
 export declare function count(s: string, test: string): number;
 /**
  * `contains` returns `true` if `s` contains any of the strings in `tests` regardless of the text case
+ * @public
  */
 export declare function containsAnyCaseInsensitive(s: string, tests: string[]): boolean;
 /**
  * `contains` returns `true` if `s` contains any of the strings in `tests`
+ * @public
  */
 export declare function containsAny(s: string, tests: string[]): boolean;
 /**
  * `contains` returns `true` if `s` contains all of the strings in `tests` regardless of the text case
+ * @public
  */
 export declare function containsAllCaseInsensitive(s: string, tests: string[]): boolean;
 /**
  * `contains` returns `true` if `s` contains all of the strings in `tests`
+ * @public
  */
 export declare function containsAll(s: string, tests: string[]): boolean;
 /**
  * `dasherize` replaces all the occurrances of `_` with `-`
+ * @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`.
+ *
  * ```ts
  * diffIndex('abcdef', 'abc123') // returns 3
  * ```
+ * @public
  */
 export declare function diffIndex(a: string, b: string): number;
 /**
@@ -114,6 +171,7 @@ export declare function diffIndex(a: string, b: string): number;
  * ```ts
  * ellipsis('tempo is a nice library', 9) // returns 'tempo is …'
  * ```
+ * @public
  */
 export declare function ellipsis(s: string, maxlen?: number, symbol?: string): string;
 /**
@@ -121,104 +179,147 @@ export declare function ellipsis(s: string, maxlen?: number, symbol?: string): s
  * ```ts
  * ellipsisMiddle('tempo is a nice library', 18) // returns 'tempo is … library'
  * ```
+ * @public
  */
 export declare function ellipsisMiddle(s: string, maxlen?: number, symbol?: string): string;
 /**
  * Returns `true` if `s` ends with any of the values in `values`.
+ * @public
  */
 export declare function endsWithAny(s: string, values: string[]): boolean;
 /**
  * `filter` applies `predicate` character by character to `s` and it returns a filtered
  * version of the string.
+ * @public
  */
 export declare function filter(s: string, predicate: (s: string) => boolean): string;
 /**
  * Same as `filter` but `predicate` operates on integer char codes instead of string characters.
+ * @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.
+ * @public
  */
 export declare function from(value: string, searchFor: string): 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 function hashCode(value: string, seed?: number): number;
 /**
  * Returns `true` if `value` is not `null` and contains at least one character.
+ * @public
  */
 export declare function hasContent(value: string): boolean;
 /**
  * Works the same as `underscore` but also replaces underscores with whitespaces.
+ * @public
  */
 export declare function humanize(s: string): string;
 /**
  * Checks if `s` contains only (and at least one) alphabetical characters.
+ * @public
  */
 export declare function isAlpha(s: string): boolean;
 /**
  * `isAlphaNum` returns `true` if the string only contains alpha-numeric characters.
+ * @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.
+ * @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.
+ * @public
  */
 export declare function isUpperCase(value: string): boolean;
 /**
  * `ifEmpty` returns `value` if it is neither `null` or empty, otherwise it returns `alt`
+ * @public
  */
 export declare function ifEmpty(value: string, alt: string): string;
 /**
  * `isDigitsOnly` returns `true` if the string only contains digits.
+ * @public
  */
 export declare function isDigitsOnly(value: string): boolean;
 /**
  * `isEmpty` returns true if either `value` is null or is an empty string.
+ * @public
  */
 export declare function isEmpty(value: string): boolean;
 /**
  * Convert first letter in `value` to 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`.
+ * @public
  */
 export declare function random(value: string, length?: number): string;
 /**
  * Returns a random sampling of the specified length from the seed string.
+ * @public
  */
 export declare function randomSequence(alphabet: string, length: number): string;
 /**
  * Like `randomSequence`, but automatically uses the base64 sequence as the seed string.
+ * @public
  */
 export declare function randomSequence64(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[];
 /**
  * If present, it removes all the occurrences of `toremove` from `value`.
+ * @public
  */
 export declare function remove(value: string, toremove: string): string;
 /**
  * If present, it removes the `toremove` text from the end of `value`.
+ * @public
  */
 export declare function removeAfter(value: string, toremove: string): string;
 /**
  * Removes a slice from `index` to `index + length` from `value`.
+ * @public
  */
 export declare function removeAt(value: string, index: number, length: number): string;
 /**
  * If present, it removes the `toremove` text from the beginning of `value`.
+ * @public
  */
 export declare function removeBefore(value: string, toremove: string): string;
 /**
  * If present, it removes the first occurrence of `toremove` from `value`.
+ * @public
  */
 export declare function removeOne(value: string, toremove: string): string;
 /**
@@ -226,87 +327,196 @@ export declare function removeOne(value: string, toremove: string): string;
  * ```ts
  * repeat('Xy', 3) // generates 'XyXyXy'
  * ```
+ * @public
  */
 export declare function repeat(s: string, times: number): string;
 /**
  * Returns a new string whose characters are in reverse order.
+ * @public
  */
 export declare function reverse(s: string): string;
 /**
  * Converts a string in a 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 quote(s: string): string;
+export declare function jsQuote(s: string, prefer?: string): string;
 /**
  * It only splits on the first occurrance of separator.
+ * @public
  */
 export declare function splitOnce(s: string, separator: string): [string] | [string, string];
 /**
  * Returns `true` if `s` starts with any of the values in `values`.
+ * @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;
 /**
  * Surrounds a string with the contents of `left` and `right`. If `right` is omitted,
  * `left` will be used on both sides
+ * @public
  */
 export declare function surround(s: string, left: string, right?: string): string;
 /**
  * It transforms a string into an `Array` of characters.
+ * @public
  */
 export declare function toArray(s: string): string[];
 /**
  * It transforms a string into an `Array` of char codes in integer format.
+ * @public
  */
 export declare function toCharcodes(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.
+ * @public
  */
 export declare function toChunks(s: string, len: number): string[];
 /**
  * Returns an array of `string` split by line breaks.
+ * @public
  */
 export declare function toLines(s: string): string[];
 /**
  * `trimChars` removes from the beginning and the end of the string any character that is present in `charlist`.
+ * @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`.
+ * @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`.
+ * @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.
+ * @public
  */
 export declare function underscore(s: string): string;
 /**
  * Convert first letter in `value` to 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.
+ * @public
  */
 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.
+ * @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];