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 Since v2.0.0 Source

Guards

isString

Since v2.0.0

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

Since v2.0.0

Signature

declare const Equivalence: equivalence.Equivalence<string>

Order

Since v2.0.0

Signature

declare const Order: order.Order<string>

Other

at

Since v2.0.0

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

Since v2.0.0

Signature

declare function camelToSnake(self: string): string

capitalize

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

Concatenates two strings at the type level.

Signature

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

empty

Since v2.0.0

The empty string "".

Signature

declare const empty: ""

endsWith

Since v2.0.0

Signature

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

includes

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

Test whether a string is non empty.

Signature

declare function isNonEmpty(self: string): boolean

kebabToSnake

Since v2.0.0

Signature

declare function kebabToSnake(self: string): string

lastIndexOf

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Signature

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

matchAll

Since v2.0.0

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

Signature

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

normalize

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

Signature

declare function pascalToSnake(self: string): string

repeat

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

Signature

declare function snakeToCamel(self: string): string

snakeToKebab

Since v2.0.0

Signature

declare function snakeToKebab(self: string): string

snakeToPascal

Since v2.0.0

Signature

declare function snakeToPascal(self: string): string

split

Since v2.0.0

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

Since v2.0.0

Signature

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

stripMargin

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

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

Since v2.0.0

Signature

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

trimEnd

Since v2.0.0

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

Since v2.0.0

Signature

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

trimStart

Since v2.0.0

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

Since v2.0.0

Signature

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

uncapitalize

Since v2.0.0

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')