Str

const Str: object

Defined in: Data/Str.ts:62

Type Declaration

capitalize

capitalize: (text) => string

Converts the first character of a string to uppercase.

Parameters

text

string

Returns

string

See

uncapitalize for converting the first character to lowercase.

Example

pipe("hello", Str.capitalize); // "Hello"

endsWith

endsWith: (suffix) => (text) => boolean

Returns true when the string ends with the given suffix.

Parameters

suffix

string

Returns

(text) => boolean

See

startsWith for checking prefix matches.

Example

pipe("hello world", Str.endsWith("world")); // true
pipe("hello world", Str.endsWith("hello")); // false

graphemeSize

graphemeSize: (text) => number

Returns the number of user-perceived characters (grapheme clusters) in the string, correctly counting emojis and complex Unicode sequences.

Parameters

text

string

Returns

number

See

size for fast UTF-16 code-unit length.

Example

pipe("👨‍👩‍👧‍👦", Str.graphemeSize); // 1
pipe("👨‍👩‍👧‍👦", Str.size);         // 11

includes

includes: (substring) => (text) => boolean

Returns true when the string contains the given substring.

Parameters

substring

string

Returns

(text) => boolean

Example

pipe("hello world", Str.includes("world")); // true
pipe("hello world", Str.includes("xyz"));   // false

is

is: object

Predicates and type guards for strings.

is.blank

blank: (text) => boolean = isBlank

Returns true when the string is empty or contains only whitespace.

Parameters

text

string

Returns

boolean

See

empty for checking zero length without trimming whitespace.

Example

pipe("   ", Str.is.blank); // true
pipe("hi", Str.is.blank);  // false

is.empty

empty: (text) => boolean = isEmpty

Returns true when the string is empty.

Parameters

text

string

Returns

boolean

See

nonEmpty for checking if a string contains at least one character.

Example

pipe("", Str.is.empty);   // true
pipe("hi", Str.is.empty); // false

is.nonEmpty

nonEmpty: (text) => text is NonEmptyString = isNonEmpty

Type guard to check if a string is non-empty.

Parameters

text

string

Returns

text is NonEmptyString

See

empty for checking if a string has zero length.

lines

lines: (text) => readonly string[]

Splits a string into lines, normalising \r\n and \r line endings.

Parameters

text

string

Returns

readonly string[]

Example

Str.lines("one\ntwo\nthree"); // ["one", "two", "three"]
Str.lines("a\r\nb");         // ["a", "b"]

match

match: (pattern) => (text) => Maybe<RegExpMatchArray>

Matches a string against a regular expression. Pure and safe: resets pattern.lastIndex = 0 to prevent bugs with stateful /g and /y regexes.

Parameters

pattern

RegExp

Returns

(text) => Maybe<RegExpMatchArray>

See

test for boolean validation without extracting capture groups.

Example

pipe("hello 42", Str.match(/\d+/)); // Some(["42"])
pipe("hello", Str.match(/\d+/));    // None

NonEmpty

NonEmpty: object = StrNonEmptyConst

Utilities for working with guaranteed non-empty strings (NonEmptyString).

NonEmpty.from

from: object

NonEmpty.from.string

string: (text) => Maybe<NonEmptyString>

Returns Some containing NonEmptyString if the string is not empty, None otherwise.

Parameters

text

string

Returns

Maybe<NonEmptyString>

Example

Str.NonEmpty.from.string("hello"); // Some("hello")
Str.NonEmpty.from.string("");      // None

padEnd

padEnd: (maxLength, fillString?) => (text) => string

Pads the end of a string to a specified length. Data-last: use in pipe.

Parameters

maxLength

number

fillString?

string

Returns

(text) => string

See

padStart for padding the left side of a string.

Example

pipe("hi", Str.padEnd(5, "."));  // "hi..."
pipe("hi", Str.padEnd(5));       // "hi   "

padStart

padStart: (maxLength, fillString?) => (text) => string

Pads the start of a string to a specified length. Data-last: use in pipe.

Parameters

maxLength

number

fillString?

string

Returns

(text) => string

See

padEnd for padding the right side of a string.

Example

pipe("5", Str.padStart(3, "0")); // "005"
pipe("hi", Str.padStart(5));     // "   hi"

parse

parse: object

Safe number parsers that return Maybe instead of NaN.

parse.float

float: (text) => Maybe<number>

Parses a string as a floating-point number. Returns None if the result is NaN.

Parameters

text

string

Returns

Maybe<number>

See

int for parsing base-10 integers.

Example

Str.parse.float("3.14"); // Some(3.14)
Str.parse.float("42");   // Some(42)
Str.parse.float("abc");  // None

parse.int

int: (text) => Maybe<number>

Parses a string as an integer (base 10). Returns None if the result is NaN.

Parameters

text

string

Returns

Maybe<number>

See

float for parsing floating-point numbers.

Example

Str.parse.int("42");   // Some(42)
Str.parse.int("3.7");  // Some(3)
Str.parse.int("abc");  // None

replace

replace: (pattern, replacement) => (text) => string

Replaces the first occurrence of a pattern in a string. Data-last: use in pipe.

Parameters

pattern

string | RegExp

replacement

string

Returns

(text) => string

See

replaceAll for substituting every occurrence instead of only the first.

Example

pipe("foo foo foo", Str.replace("foo", "bar")); // "bar foo foo"
pipe("Hello World", Str.replace(/world/i, "Earth")); // "Hello Earth"

replaceAll

replaceAll: (pattern, replacement) => (text) => string

Replaces all occurrences of a pattern in a string. Data-last: use in pipe.

Parameters

pattern

string | RegExp

replacement

string

Returns

(text) => string

See

replace for substituting only the first occurrence.

Example

pipe("foo foo foo", Str.replaceAll("foo", "bar")); // "bar bar bar"
pipe("aAbBaA", Str.replaceAll(/a/gi, "x")); // "xxBBxx"

size

size: (text) => number

Returns the UTF-16 code-unit length of the string.

Parameters

text

string

Returns

number

See

graphemeSize for counting user-perceived characters/emojis.

Example

pipe("hello", Str.size); // 5
pipe("", Str.size);      // 0

slice

slice: (start, end?) => (text) => string

Extracts a substring between two indices. Data-last: use in pipe.

Parameters

start

number

end?

number

Returns

(text) => string

Example

pipe("hello", Str.slice(1, 3)); // "el"
pipe("hello", Str.slice(2));    // "llo"

split

split: (separator) => (text) => readonly string[]

Splits a string by a separator. Data-last: use in pipe.

Parameters

separator

string | RegExp

Returns

(text) => readonly string[]

Example

pipe("a,b,c", Str.split(",")); // ["a", "b", "c"]

startsWith

startsWith: (prefix) => (text) => boolean

Returns true when the string starts with the given prefix.

Parameters

prefix

string

Returns

(text) => boolean

See

endsWith for checking suffix matches.

Example

pipe("hello world", Str.startsWith("hello")); // true
pipe("hello world", Str.startsWith("world")); // false

test

test: (pattern) => (text) => boolean

Tests whether a string matches a regular expression. Pure and safe: resets pattern.lastIndex = 0 to prevent bugs with stateful /g and /y regexes.

Parameters

pattern

RegExp

Returns

(text) => boolean

See

match for extracting capture groups into a Maybe.

Example

pipe("user@example.com", Str.test(/^[^@]+@[^@]+$/)); // true
pipe("invalid-email", Str.test(/^[^@]+@[^@]+$/));    // false

toLowerCase

toLowerCase: (text) => string

Converts a string to lowercase.

Parameters

text

string

Returns

string

See

toUpperCase for uppercasing characters.

Example

pipe("HELLO", Str.toLowerCase); // "hello"

toUpperCase

toUpperCase: (text) => string

Converts a string to uppercase.

Parameters

text

string

Returns

string

See

toLowerCase for lowercasing characters.

Example

pipe("hello", Str.toUpperCase); // "HELLO"

trim

trim: (text) => string

Removes leading and trailing whitespace from a string.

Parameters

text

string

Returns

string

Example

pipe("  hello  ", Str.trim); // "hello"

truncate

truncate: (options) => (text) => string

Truncates a string to a maximum length, appending an optional suffix (default "..."). Data-last curried signature.

Parameters

options

length

number

suffix?

string

Returns

(text) => string

Example

pipe("Hello, world!", Str.truncate({ length: 8 })); // "Hello..."
pipe("Hello", Str.truncate({ length: 10 }));        // "Hello"
pipe("Hello, world!", Str.truncate({ length: 8, suffix: "…" })); // "Hello, w…"

uncapitalize

uncapitalize: (text) => string

Converts the first character of a string to lower case.

Parameters

text

string

Returns

string

See

capitalize for converting the first character to uppercase.

Example

pipe("Hello", Str.uncapitalize); // "hello"
pipe("", Str.uncapitalize);      // ""

words

words: (text) => readonly string[]

Splits a string into words on any whitespace boundary, filtering out empty strings.

Parameters

text

string

Returns

readonly string[]

Example

Str.words("  hello   world  "); // ["hello", "world"]