Skip to main content Link Search Menu Expand Document (external link)
effect

String overview

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.

Added in v2.0.0

Table of contents

guards

isString

Tests if a value is a string.

Signature

export declare const isString: Refinement<unknown, string>

Example

import { isString } from "effect/String"

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

Added in v2.0.0

instances

Equivalence

Signature

export declare const Equivalence: equivalence.Equivalence<string>

Added in v2.0.0

Order

Signature

export declare const Order: order.Order<string>

Added in v2.0.0

utils

Concat (type alias)

Concatenates two strings at the type level.

Signature

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

Added in v2.0.0

Trim (type alias)

Signature

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

Added in v2.0.0

TrimEnd (type alias)

Signature

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

Added in v2.0.0

TrimStart (type alias)

Signature

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

Added in v2.0.0

at

Signature

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

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

camelToSnake

Signature

export declare const camelToSnake: (self: string) => string

Added in v2.0.0

capitalize

Signature

export declare const capitalize: <T extends string>(self: T) => Capitalize<T>

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("abc", S.capitalize), "Abc")

Added in v2.0.0

charAt

Signature

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

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

charCodeAt

Signature

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

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

codePointAt

Signature

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

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

concat

Concatenates two strings at runtime.

Signature

export 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}`
}

Added in v2.0.0

empty

The empty string "".

Signature

export declare const empty: ""

Added in v2.0.0

endsWith

Signature

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

Added in v2.0.0

includes

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

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

Added in v2.0.0

indexOf

Signature

export declare const indexOf: (searchString: string) => (self: string) => Option.Option<number>

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

isEmpty

Test whether a string is empty.

Signature

export declare const isEmpty: (self: string) => self is ""

Example

import * as S from "effect/String"

assert.deepStrictEqual(S.isEmpty(""), true)
assert.deepStrictEqual(S.isEmpty("a"), false)

Added in v2.0.0

isNonEmpty

Test whether a string is non empty.

Signature

export declare const isNonEmpty: (self: string) => boolean

Added in v2.0.0

kebabToSnake

Signature

export declare const kebabToSnake: (self: string) => string

Added in v2.0.0

lastIndexOf

Signature

export declare const lastIndexOf: (searchString: string) => (self: string) => Option.Option<number>

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

length

Calculate the number of characters in a string.

Signature

export declare const length: (self: string) => number

Example

import * as S from "effect/String"

assert.deepStrictEqual(S.length("abc"), 3)

Added in v2.0.0

linesIterator

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

Signature

export declare const linesIterator: (self: string) => LinesIterator

Added in v2.0.0

linesWithSeparators

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

Signature

export declare const linesWithSeparators: (s: string) => LinesIterator

Added in v2.0.0

localeCompare

Signature

export declare const localeCompare: (
  that: string,
  locales?: Array<string>,
  options?: Intl.CollatorOptions
) => (self: string) => Ordering.Ordering

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

match

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

Signature

export declare const match: (regexp: RegExp | string) => (self: string) => Option.Option<RegExpMatchArray>

Added in v2.0.0

matchAll

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

Signature

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

Added in v2.0.0

normalize

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

padEnd

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

padStart

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

pascalToSnake

Signature

export declare const pascalToSnake: (self: string) => string

Added in v2.0.0

repeat

Signature

export declare const repeat: (count: number) => (self: string) => string

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

replace

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("abc", S.replace("b", "d")), "adc")

Added in v2.0.0

replaceAll

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

Signature

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

Example

import * as S from "effect/String"
import * as Option from "effect/Option"
import { pipe } from "effect/Function"

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

Added in v2.0.0

slice

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("abcd", S.slice(1, 3)), "bc")

Added in v2.0.0

snakeToCamel

Signature

export declare const snakeToCamel: (self: string) => string

Added in v2.0.0

snakeToKebab

Signature

export declare const snakeToKebab: (self: string) => string

Added in v2.0.0

snakeToPascal

Signature

export declare const snakeToPascal: (self: string) => string

Added in v2.0.0

split

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("abc", S.split("")), ["a", "b", "c"])
assert.deepStrictEqual(pipe("", S.split("")), [""])

Added in v2.0.0

startsWith

Signature

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

Added in v2.0.0

stripMargin

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

Signature

export declare const stripMargin: (self: string) => string

Added in v2.0.0

stripMarginWith

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

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

Added in v2.0.0

substring

Signature

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

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

takeLeft

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

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

Example

import * as S from "effect/String"

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

Added in v2.0.0

takeRight

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

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

Example

import * as S from "effect/String"

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

Added in v2.0.0

toLocaleLowerCase

Signature

export declare const toLocaleLowerCase: (locale?: string | Array<string>) => (self: string) => string

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

toLocaleUpperCase

Signature

export declare const toLocaleUpperCase: (locale?: string | Array<string>) => (self: string) => string

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

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

Added in v2.0.0

toLowerCase

Signature

export declare const toLowerCase: <T extends string>(self: T) => Lowercase<T>

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("A", S.toLowerCase), "a")

Added in v2.0.0

toUpperCase

Signature

export declare const toUpperCase: <S extends string>(self: S) => Uppercase<S>

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("a", S.toUpperCase), "A")

Added in v2.0.0

trim

Signature

export declare const trim: <A extends string>(self: A) => TrimEnd<TrimStart<A>>

Example

import * as S from "effect/String"

assert.deepStrictEqual(S.trim(" a "), "a")

Added in v2.0.0

trimEnd

Signature

export declare const trimEnd: <A extends string>(self: A) => TrimEnd<A>

Example

import * as S from "effect/String"

assert.deepStrictEqual(S.trimEnd(" a "), " a")

Added in v2.0.0

trimStart

Signature

export declare const trimStart: <A extends string>(self: A) => TrimStart<A>

Example

import * as S from "effect/String"

assert.deepStrictEqual(S.trimStart(" a "), "a ")

Added in v2.0.0

uncapitalize

Signature

export declare const uncapitalize: <T extends string>(self: T) => Uncapitalize<T>

Example

import * as S from "effect/String"
import { pipe } from "effect/Function"

assert.deepStrictEqual(pipe("ABC", S.uncapitalize), "aBC")

Added in v2.0.0