/**
 * This file contains the String algebraic data type. String is a the built in
 * javascript string structure. This file contains data last implementations of
 * most of the String built in methods as well as minor "fixes" to make them
 * less error prone.
 *
 * @module String
 * @since 2.0.0
 */
import "./_dnt.polyfills.js";
import type { Combinable } from "./combinable.js";
import type { Comparable } from "./comparable.js";
import type { Initializable } from "./initializable.js";
import type { NonEmptyArray } from "./array.js";
import type { Option } from "./option.js";
import type { Ordering, Sortable } from "./sortable.js";
import type { Showable } from "./showable.js";
/**
 * Compare two strings for equality.
 *
 * @example
 * ```ts
 * import { compare } from "./string.ts";
 *
 * const hello = "Hello";
 * const hi = "hi";
 * const hi2 = "hi";
 *
 * const result1 = compare(hi)(hello); // false
 * const result2 = compare(hi)(hi2); // true
 * ```
 *
 * @since 2.0.0
 */
export declare function compare(second: string): (first: string) => boolean;
/**
 * Combine two strings.
 *
 * @example
 * ```ts
 * import { combine } from "./string.ts";
 *
 * const result1 = combine("Hello")("World"); // "WorldHello"
 * ```
 *
 * @since 2.0.0
 */
export declare function combine(second: string): (first: string) => string;
/**
 * Returns an init string.
 *
 * @example
 * ```ts
 * import { init } from "./string.ts";
 *
 * const result = init(); // ""
 * ```
 *
 * @since 2.0.0
 */
export declare function init(): string;
/**
 * Compare two strings and return an Ordering (-1, 0, or 1);
 *
 * @example
 * ```ts
 * import { sort } from "./string.ts";
 *
 * const result1 = sort("aa", "aa"); // 0
 * const result2 = sort("aa", "ab"); // -1
 * const result3 = sort("ba", "aa"); // 1
 * const result4 = sort("ab", "aa"); // 1
 * const result5 = sort("a", "aa"); // -1
 * ```
 *
 * @since 2.0.0
 */
export declare function sort(first: string, second: string): Ordering;
/**
 * A instance of Refinement<unknown, string>. Used as a type
 * guard to verify any type is actually a string.
 *
 * @example
 * ```ts
 * import { isString } from "./string.ts";
 *
 * const notString: unknown = 2;
 * const string: unknown = "hello";
 *
 * const result1 = isString(notString); // result1 has type unknown
 * const result2 = isString(string); // result2 has type string
 * ```
 *
 * @since 2.0.0
 */
export declare function isString(a: unknown): a is string;
/**
 * A Predicate for string returning true if the
 * string is init.
 *
 * @example
 * ```ts
 * import { isEmpty } from "./string.ts";
 *
 * const result1 = isEmpty("Hello"); // false
 * const result2 = isEmpty(""); // true
 * ```
 *
 * @since 2.0.0
 */
export declare function isEmpty(a: string): boolean;
/**
 * Returns the length of an input string.
 *
 * @example
 * ```ts
 * import { length } from "./string.ts";
 *
 * const result1 = length("Hello"); // 5
 * const result2 = length(""); // 0
 * ```
 * @since 2.0.0
 */
export declare function length(a: string): number;
/**
 * Split a string into an array of strings at
 * a character or RegExp match.
 *
 * @example
 * ```ts
 * import { split } from "./string.ts";
 * import { pipe } from "./fn.ts";
 *
 * const bySpace = split(" ");
 * const byWhitespace = split(/\s+/);
 * const str = "Hello  There  World";
 *
 * const result1 = bySpace(str); // ["Hello", "", "There", "", "World"]
 * const result2 = byWhitespace(str); // ["Hello", "There", "World"]
 * ```
 *
 * @since 2.0.0
 */
export declare function split(separator: string | RegExp): (s: string) => NonEmptyArray<string>;
/**
 * Creates a Predicate over string that returns true when
 * a string includes the searchString at or beyond the
 * optional starting position.
 *
 * @example
 * ```ts
 * import { includes } from "./string.ts";
 *
 * const hasSpace = includes(" ");
 *
 * const result1 = hasSpace("Hello World"); // true
 * const result2 = hasSpace("Goodbye"); // false
 * ```
 *
 * @since 2.0.0
 */
export declare function includes(searchString: string, position?: number): (s: string) => boolean;
/**
 * Creates a Predicate over string that returns true when the string
 * starts with the supplied searchString starting at position, if
 * it is supplied.
 *
 * @example
 * ```ts
 * import { startsWith } from "./string.ts";
 *
 * const withHello = startsWith("Hello");
 *
 * const result1 = withHello("Hello World"); // true
 * const result2 = withHello("Goodbye"); // false
 * ```
 *
 * @since 2.0.0
 */
export declare function startsWith<T extends string>(searchString: T, position?: number): (s: string) => s is `${T}${string}`;
/**
 * Creates a Predicate over string that returns true when the string
 * ends with the supplied searchString starting at position, if
 * it is supplied.
 *
 * @example
 * ```ts
 * import { endsWith } from "./string.ts";
 *
 * const withbye = endsWith("bye");
 *
 * const result1 = withbye("Hello World"); // false
 * const result2 = withbye("Goodbye"); // true
 * ```
 *
 * @since 2.0.0
 */
export declare function endsWith<T extends string>(searchString: T, position?: number): (s: string) => s is `${string}${T}`;
/**
 * A pipeable form of String.toUpperCase.
 *
 * @example
 * ```ts
 * import { toUpperCase } from "./string.ts";
 *
 * const result = toUpperCase("hello"); // "HELLO"
 * ```
 *
 * @since 2.0.0
 */
export declare function toUpperCase(a: string): string;
/**
 * A pipeable form of String.toLowerCase.
 *
 * @example
 * ```ts
 * import { toLowerCase } from "./string.ts";
 *
 * const result = toLowerCase("Hello"); // "hello"
 * ```
 *
 * @since 2.0.0
 */
export declare function toLowerCase(a: string): string;
/**
 * Create a function that replaces all values in a string according
 * to a RegExp and a replacement value.
 *
 * @example
 * ```ts
 * import { replace } from "./string.ts";
 *
 * const cap = replace("hello", "Hello");
 *
 * const result = cap("hello World"); // "Hello World"
 * ```
 *
 * @since 2.0.0
 */
export declare function replace(searchValue: string | RegExp, replaceValue: string): (s: string) => string;
/**
 * Trims whitespace from the beginning and end of a string.
 *
 * @example
 * ```ts
 * import { trim } from "./string.ts";
 *
 * const result1 = trim("Hello World"); // "Hello World"
 * const result2 = trim("  Hello World"); // "Hello World"
 * const result3 = trim("Hello World  "); // "Hello World"
 * const result4 = trim(" Hello World "); // "Hello World"
 * ```
 *
 * @since 2.0.0
 */
export declare function trim(a: string): string;
/**
 * Trims whitespace from the beginning of a string.
 *
 * @example
 * ```ts
 * import { trimStart } from "./string.ts";
 *
 * const result1 = trimStart("Hello World"); // "Hello World"
 * const result2 = trimStart("  Hello World"); // "Hello World"
 * const result3 = trimStart("Hello World  "); // "Hello World"
 * const result4 = trimStart(" Hello World "); // "Hello World"
 * ```
 *
 * @since 2.0.0
 */
export declare function trimStart(a: string): string;
/**
 * Trims whitespace from the end of a string.
 *
 * @example
 * ```ts
 * import { trimEnd } from "./string.ts";
 *
 * const result1 = trimEnd("Hello World"); // "Hello World"
 * const result2 = trimEnd("  Hello World"); // "Hello World"
 * const result3 = trimEnd("Hello World  "); // "Hello World"
 * const result4 = trimEnd(" Hello World "); // "Hello World"
 * ```
 *
 * @since 2.0.0
 */
export declare function trimEnd(a: string): string;
/**
 * A simple curried pluralizing function. Takes the singular and plural
 * forms of a word and returns a function that takes a count and returns
 * the correct word for the count.
 *
 * @example
 * ```ts
 * import { plural } from "./string.ts";
 *
 * const are = plural("is", "are");
 * const rabbits = plural("rabbit", "rabbits");
 * const sentence = (n: number) => `There ${are(n)} ${n} ${rabbits(n)}`;
 *
 * const result1 = sentence(1); // "There is 1 rabbit"
 * const result2 = sentence(4); // "There are 4 rabbits"
 * const result3 = sentence(0); // "There are 0 rabbits"
 * ```
 *
 * @since 2.0.0
 */
export declare function plural(singular: string, plural: string): (count: number) => string;
/**
 * Create a substring of a string based on 0 based indices.
 *
 * @example
 * ```ts
 * import { slice } from "./string.ts";
 *
 * const slc = slice(1, 5);
 *
 * const result1 = slc(""); // ""
 * const result2 = slc("Hello"); "ello"
 * const result3 = slc("e");
 * ```
 *
 * @since 2.0.0
 */
export declare function slice(start: number, end: number): (a: string) => string;
/**
 * Create a function that returns an Option<RegExpMatchArray>. This
 * is a curried form of RegExp.match.
 *
 * @example
 * ```ts
 * import { match } from "./string.ts";
 *
 * const words = match(/\w+/g);
 *
 * const result1 = words("Hello World"); // Some(["Hello", "World"])
 * const result2 = words(""); // None
 * const result3 = words("1234"); // Some(["1234"])
 *
 * ```
 *
 * @since 2.0.0
 */
export declare function match(regex: RegExp): (a: string) => Option<RegExpMatchArray>;
/**
 * Create a Predicate that returns true when it matches the supplied
 * RegExp. Warning, this function technically mutates RegExp, but paradoxically
 * it does so to keep state the same. If the passed RegExp.test method is called
 * outside of this function then mayhem will surely ensue.
 *
 * @example
 * ```ts
 * import { test } from "./string.ts";
 *
 * const words = test(/\w+/);
 *
 * const result1 = words("Hello World"); // true
 * const result2 = words(""); // false
 * const result3 = words("1234"); // true
 *
 * ```
 *
 * @since 2.0.0
 */
export declare function test(r: RegExp): (s: string) => boolean;
/**
 * The canonical implementation of Sortable for string. It contains
 * the methods lt, lte, equals, gte, gt, min, max, clamp, between,
 * and compare.
 *
 * @since 2.0.0
 */
export declare const SortableString: Sortable<string>;
/**
 * @since 2.0.0
 */
export declare const CombinableString: Combinable<string>;
/**
 * The canonical implementation of Comparable for string. It contains
 * the method equals.
 *
 * @since 2.0.0
 */
export declare const ComparableString: Comparable<string>;
/**
 * The canonical implementation of Initializable for string. It contains
 * the method init and combine.
 *
 * @since 2.0.0
 */
export declare const InitializableString: Initializable<string>;
/**
 * The canonical implementation of Showable for string. It contains
 * the method show.
 *
 * @since 2.0.0
 */
export declare const ShowableString: Showable<string>;