String

This module provides utility functions and type class instances for working with the string type in TypeScript. It includes functions for basic string manipulation, as well as type class instances for Equivalence and Order.

55 exports Added in v2.0.0 Source

Guards

isString

Added in v2.0.0 Source

Tests if a value is a string.

Signature

declare const isString: Refinement<unknown, string>

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.isString("a"), true)
assert.deepStrictEqual(String.isString(1), false)

Instances

Equivalence

Added in v2.0.0 Source

Signature

declare const Equivalence: equivalence.Equivalence<string>

Order

Added in v2.0.0 Source

Signature

declare const Order: order.Order<string>

Other

at

Added in v2.0.0 Source

Signature

declare const at: {
  (index: number): (self: string) => Option<string>;
  (self: string, index: number): Option<string>;
}

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abc", String.at(1)), Option.some("b"))
assert.deepStrictEqual(pipe("abc", String.at(4)), Option.none())

camelToSnake

Added in v2.0.0 Source

Signature

declare function camelToSnake(self: string): string

capitalize

Added in v2.0.0 Source

Signature

declare function capitalize<T extends string>(self: T): Capitalize<T>

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('abc', String.capitalize), 'Abc')

charAt

Added in v2.0.0 Source

Signature

declare const charAt: {
  (index: number): (self: string) => Option<string>;
  (self: string, index: number): Option<string>;
}

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abc", String.charAt(1)), Option.some("b"))
assert.deepStrictEqual(pipe("abc", String.charAt(4)), Option.none())

charCodeAt

Added in v2.0.0 Source

Signature

declare const charCodeAt: {
  (index: number): (self: string) => Option<number>;
  (self: string, index: number): Option<number>;
}

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abc", String.charCodeAt(1)), Option.some(98))
assert.deepStrictEqual(pipe("abc", String.charCodeAt(4)), Option.none())

codePointAt

Added in v2.0.0 Source

Signature

declare const codePointAt: {
  (index: number): (self: string) => Option<number>;
  (self: string, index: number): Option<number>;
}

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abc", String.codePointAt(1)), Option.some(98))

concat

Added in v2.0.0 Source

Concatenates two strings at runtime.

Signature

declare const concat: {
  <B extends string>(that: B): <A extends string>(self: A) => `${A}${B}`;
  <A extends string, B extends string>(self: A, that: B): `${A}${B}`;
}

Concat type

Added in v2.0.0 Source

Concatenates two strings at the type level.

Signature

type Concat<A extends string, B extends string> = `${A}${B}`

empty

Added in v2.0.0 Source

The empty string "".

Signature

declare const empty: ""

endsWith

Added in v2.0.0 Source

Signature

declare function endsWith(searchString: string, position?: number): (self: string) => boolean

includes

Added in v2.0.0 Source

Returns true if searchString appears as a substring of self, at one or more positions that are greater than or equal to position; otherwise, returns false.

Signature

declare function includes(searchString: string, position?: number): (self: string) => boolean

indexOf

Added in v2.0.0 Source

Signature

declare function indexOf(searchString: string): (self: string) => Option<number>

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abbbc", String.indexOf("b")), Option.some(1))

isEmpty

Added in v2.0.0 Source

Test whether a string is empty.

Signature

declare function isEmpty(self: string): self is ""

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.isEmpty(''), true)
assert.deepStrictEqual(String.isEmpty('a'), false)

isNonEmpty

Added in v2.0.0 Source

Test whether a string is non empty.

Signature

declare function isNonEmpty(self: string): boolean

kebabToSnake

Added in v2.0.0 Source

Signature

declare function kebabToSnake(self: string): string

lastIndexOf

Added in v2.0.0 Source

Signature

declare function lastIndexOf(searchString: string): (self: string) => Option<number>

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abbbc", String.lastIndexOf("b")), Option.some(3))
assert.deepStrictEqual(pipe("abbbc", String.lastIndexOf("d")), Option.none())

length

Added in v2.0.0 Source

Calculate the number of characters in a string.

Signature

declare function length(self: string): number

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.length('abc'), 3)

linesIterator

Added in v2.0.0 Source

Returns an IterableIterator which yields each line contained within the string, trimming off the trailing newline character.

Signature

declare function linesIterator(self: string): LinesIterator

linesWithSeparators

Added in v2.0.0 Source

Returns an IterableIterator which yields each line contained within the string as well as the trailing newline character.

Signature

declare function linesWithSeparators(s: string): LinesIterator

localeCompare

Added in v2.0.0 Source

Signature

declare function localeCompare(that: string, locales?: LocalesArgument, options?: CollatorOptions): (self: string) => Ordering

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe("a", String.localeCompare("b")), -1)
assert.deepStrictEqual(pipe("b", String.localeCompare("a")), 1)
assert.deepStrictEqual(pipe("a", String.localeCompare("a")), 0)

match

Added in v2.0.0 Source

It is the pipe-able version of the native match method.

Signature

declare function match(regexp: string | RegExp): (self: string) => Option<RegExpMatchArray>

matchAll

Added in v2.0.0 Source

It is the pipe-able version of the native matchAll method.

Signature

declare function matchAll(regexp: RegExp): (self: string) => IterableIterator<RegExpMatchArray>

normalize

Added in v2.0.0 Source

Signature

declare function normalize(form?: "NFC" | "NFD" | "NFKC" | "NFKD"): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

const str = "\u1E9B\u0323";
assert.deepStrictEqual(pipe(str, String.normalize()), "\u1E9B\u0323")
assert.deepStrictEqual(pipe(str, String.normalize("NFC")), "\u1E9B\u0323")
assert.deepStrictEqual(pipe(str, String.normalize("NFD")), "\u017F\u0323\u0307")
assert.deepStrictEqual(pipe(str, String.normalize("NFKC")), "\u1E69")
assert.deepStrictEqual(pipe(str, String.normalize("NFKD")), "\u0073\u0323\u0307")

padEnd

Added in v2.0.0 Source

Signature

declare function padEnd(maxLength: number, fillString?: string): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe("a", String.padEnd(5)), "a    ")
assert.deepStrictEqual(pipe("a", String.padEnd(5, "_")), "a____")

padStart

Added in v2.0.0 Source

Signature

declare function padStart(maxLength: number, fillString?: string): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe("a", String.padStart(5)), "    a")
assert.deepStrictEqual(pipe("a", String.padStart(5, "_")), "____a")

pascalToSnake

Added in v2.0.0 Source

Signature

declare function pascalToSnake(self: string): string

repeat

Added in v2.0.0 Source

Signature

declare function repeat(count: number): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe("a", String.repeat(5)), "aaaaa")

replace

Added in v2.0.0 Source

Signature

declare function replace(searchValue: string | RegExp, replaceValue: string): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('abc', String.replace('b', 'd')), 'adc')

replaceAll

Added in v2.0.0 Source

Signature

declare function replaceAll(searchValue: string | RegExp, replaceValue: string): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe("ababb", String.replaceAll("b", "c")), "acacc")
assert.deepStrictEqual(pipe("ababb", String.replaceAll(/ba/g, "cc")), "accbb")

search

Added in v2.0.0 Source

Signature

declare const search: {
  (regexp: string | RegExp): (self: string) => Option<number>;
  (self: string, regexp: string | RegExp): Option<number>;
}

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("ababb", String.search("b")), Option.some(1))
assert.deepStrictEqual(pipe("ababb", String.search(/abb/)), Option.some(2))
assert.deepStrictEqual(pipe("ababb", String.search("d")), Option.none())

slice

Added in v2.0.0 Source

Signature

declare function slice(start?: number, end?: number): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('abcd', String.slice(1, 3)), 'bc')

snakeToCamel

Added in v2.0.0 Source

Signature

declare function snakeToCamel(self: string): string

snakeToKebab

Added in v2.0.0 Source

Signature

declare function snakeToKebab(self: string): string

snakeToPascal

Added in v2.0.0 Source

Signature

declare function snakeToPascal(self: string): string

split

Added in v2.0.0 Source

Signature

declare const split: {
  (separator: string | RegExp): (self: string) => [string, ...Array<string>];
  (self: string, separator: string | RegExp): [string, ...Array<string>];
}

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('abc', String.split('')), ['a', 'b', 'c'])
assert.deepStrictEqual(pipe('', String.split('')), [''])

startsWith

Added in v2.0.0 Source

Signature

declare function startsWith(searchString: string, position?: number): (self: string) => boolean

stripMargin

Added in v2.0.0 Source

For every line in this string, strip a leading prefix consisting of blanks or control characters followed by the "|" character from the line.

Signature

declare function stripMargin(self: string): string

stripMarginWith

Added in v2.0.0 Source

For every line in this string, strip a leading prefix consisting of blanks or control characters followed by the character specified by marginChar from the line.

Signature

declare const stripMarginWith: {
  (marginChar: string): (self: string) => string;
  (self: string, marginChar: string): string;
}

substring

Added in v2.0.0 Source

Signature

declare function substring(start: number, end?: number): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String, Option } from "effect"

assert.deepStrictEqual(pipe("abcd", String.substring(1)), "bcd")
assert.deepStrictEqual(pipe("abcd", String.substring(1, 3)), "bc")

takeLeft

Added in v2.0.0 Source

Keep the specified number of characters from the start of a string.

If n is larger than the available number of characters, the string will be returned whole.

If n is not a positive number, an empty string will be returned.

If n is a float, it will be rounded down to the nearest integer.

Signature

declare const takeLeft: {
  (n: number): (self: string) => string;
  (self: string, n: number): string;
}

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.takeLeft("Hello World", 5), "Hello")

takeRight

Added in v2.0.0 Source

Keep the specified number of characters from the end of a string.

If n is larger than the available number of characters, the string will be returned whole.

If n is not a positive number, an empty string will be returned.

If n is a float, it will be rounded down to the nearest integer.

Signature

declare const takeRight: {
  (n: number): (self: string) => string;
  (self: string, n: number): string;
}

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.takeRight("Hello World", 5), "World")

toLocaleLowerCase

Added in v2.0.0 Source

Signature

declare function toLocaleLowerCase(locale?: LocalesArgument): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

const str = "\u0130"
assert.deepStrictEqual(pipe(str, String.toLocaleLowerCase("tr")), "i")

toLocaleUpperCase

Added in v2.0.0 Source

Signature

declare function toLocaleUpperCase(locale?: LocalesArgument): (self: string) => string

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

const str = "i\u0307"
assert.deepStrictEqual(pipe(str, String.toLocaleUpperCase("lt-LT")), "I")

toLowerCase

Added in v2.0.0 Source

Signature

declare function toLowerCase<T extends string>(self: T): Lowercase<T>

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('A', String.toLowerCase), 'a')

toUpperCase

Added in v2.0.0 Source

Signature

declare function toUpperCase<S extends string>(self: S): Uppercase<S>

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('a', String.toUpperCase), 'A')

trim

Added in v2.0.0 Source

Signature

declare function trim<A extends string>(self: A): TrimEnd<TrimStart<A>>

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.trim(' a '), 'a')

Trim type

Added in v2.0.0 Source

Signature

type Trim<A extends string> = TrimEnd<TrimStart<A>>

trimEnd

Added in v2.0.0 Source

Signature

declare function trimEnd<A extends string>(self: A): TrimEnd<A>

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.trimEnd(' a '), ' a')

TrimEnd type

Added in v2.0.0 Source

Signature

type TrimEnd<A extends string> = A extends `${infer B}${" " | "\n" | "\t" | "\r"}` ? TrimEnd<B> : A

trimStart

Added in v2.0.0 Source

Signature

declare function trimStart<A extends string>(self: A): TrimStart<A>

Example

import * as assert from "node:assert"
import { String } from "effect"

assert.deepStrictEqual(String.trimStart(' a '), 'a ')

TrimStart type

Added in v2.0.0 Source

Signature

type TrimStart<A extends string> = A extends `${" " | "\n" | "\t" | "\r"}${infer B}` ? TrimStart<B> : A

uncapitalize

Added in v2.0.0 Source

Signature

declare function uncapitalize<T extends string>(self: T): Uncapitalize<T>

Example

import * as assert from "node:assert"
import { pipe, String } from "effect"

assert.deepStrictEqual(pipe('ABC', String.uncapitalize), 'aBC')