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

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, Order, Semigroup, and Monoid.

Added in v1.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/data/String'

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

Added in v1.0.0

instances

Equivalence

Signature

export declare const Equivalence: equivalence.Equivalence<string>

Added in v1.0.0

Order

Signature

export declare const Order: order.Order<string>

Added in v1.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 v1.0.0

Trim (type alias)

Signature

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

Added in v1.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 v1.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 v1.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/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

capitalize

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/Function'

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

Added in v1.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 v1.0.0

empty

The empty string "".

Signature

export declare const empty: ''

Added in v1.0.0

endsWith

Signature

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

Added in v1.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 v1.0.0

indexOf

Signature

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

Example

import * as S from '@effect/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

isEmpty

Test whether a string is empty.

Signature

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

Example

import * as S from '@effect/data/String'

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

Added in v1.0.0

isNonEmpty

Test whether a string is non empty.

Signature

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

Added in v1.0.0

lastIndexOf

Signature

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

Example

import * as S from '@effect/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'

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

Added in v1.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 v1.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/data/String'
import { pipe } from '@effect/data/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 v1.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 v1.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 v1.0.0

normalize

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/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 v1.0.0

padEnd

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

padStart

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

repeat

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

replace

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

replaceAll

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'
import * as Option from '@effect/data/Option'
import { pipe } from '@effect/data/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 v1.0.0

slice

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

startsWith

Signature

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

Added in v1.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 v1.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 v1.0.0

substring

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.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/data/String'

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

Added in v1.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/data/String'

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

Added in v1.0.0

toLocaleLowerCase

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

toLocaleUpperCase

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

toLowerCase

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

toUpperCase

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0

trim

Signature

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

Example

import * as S from '@effect/data/String'

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

Added in v1.0.0

trimEnd

Signature

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

Example

import * as S from '@effect/data/String'

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

Added in v1.0.0

trimStart

Signature

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

Example

import * as S from '@effect/data/String'

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

Added in v1.0.0

uncapitalize

Signature

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

Example

import * as S from '@effect/data/String'
import { pipe } from '@effect/data/Function'

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

Added in v1.0.0