TypstDocumentation

string

A sequence of Unicode codepoints.

You can iterate over the grapheme clusters of the string using a for loop. Grapheme clusters are basically characters but keep together things that belong together, e.g. multiple codepoints that together form a flag emoji. Strings can be added with the + operator, joined together and multiplied with integers.

Typst provides utility methods for string manipulation. Many of these methods (e.g., split, trim and replace) operate on patterns: A pattern can be either a string or a regular expression. This makes the methods quite versatile.

All lengths and indices are expressed in terms of UTF-8 characters. Indices are zero-based and negative indices wrap around to the end of the string.

Example

#"hello world!" \
#"\"hello\n  world\"!" \
#"1 2 3".split() \
#"1,2;3".split(regex("[,;]")) \
#(regex("\d+") in "ten euros") \
#(regex("\d+") in "10 euros")
Preview

Escape sequences

Just like in markup, you can escape a few symbols in strings:

Methods
Question mark

len method

The length of the string in UTF-8 encoded bytes.

value.len(
) -> integer

first method

Extract the first grapheme cluster of the string. Fails with an error if the string is empty.

value.first(
) -> any

last method

Extract the last grapheme cluster of the string. Fails with an error if the string is empty.

value.last(
) -> any

at method

Extract the first grapheme cluster after the specified index. Returns the default value if the index is out of bounds or fails with an error if no default value was specified.

value.at(
integer,default: any,
) -> string

index
integer
RequiredPositional
Question mark

The byte index.

default
any

A default value to return if the index is out of bounds.

slice method

Extract a substring of the string. Fails with an error if the start or end index is out of bounds.

value.slice(
integer,integer,count: integer,
) -> string

start
integer
RequiredPositional
Question mark

The start byte index (inclusive).

end
integer
Positional
Question mark

The end byte index (exclusive). If omitted, the whole slice until the end of the string is extracted.

count
integer

The number of bytes to extract. This is equivalent to passing start + count as the end position. Mutually exclusive with end.

clusters method

Returns the grapheme clusters of the string as an array of substrings.

value.clusters(
) -> array

codepoints method

Returns the Unicode codepoints of the string as an array of substrings.

value.codepoints(
) -> array

contains method

Whether the string contains the specified pattern.

This method also has dedicated syntax: You can write "bc" in "abcd" instead of "abcd".contains("bc").

value.contains(
stringregex
) -> boolean

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

starts-with method

Whether the string starts with the specified pattern.

value.starts-with(
stringregex
) -> boolean

pattern
string or regex
RequiredPositional
Question mark

The pattern the string might start with.

ends-with method

Whether the string ends with the specified pattern.

value.ends-with(
stringregex
) -> boolean

pattern
string or regex
RequiredPositional
Question mark

The pattern the string might end with.

find method

Searches for the specified pattern in the string and returns the first match as a string or none if there is no match.

value.find(
stringregex
) -> stringnone

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

position method

Searches for the specified pattern in the string and returns the index of the first match as an integer or none if there is no match.

value.position(
stringregex
) -> integernone

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

match method

Searches for the specified pattern in the string and returns a dictionary with details about the first match or none if there is no match.

The returned dictionary has the following keys:

value.match(
stringregex
) -> dictionarynone

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

matches method

Searches for the specified pattern in the string and returns an array of dictionaries with details about all matches. For details about the returned dictionaries, see above.

value.matches(
stringregex
) -> array

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

replace method

Replaces all or a specified number of matches of a pattern with a replacement string and returns the resulting string.

value.replace(
stringregex,stringfunction,count: integer,
) -> string

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

replacement
string or function
RequiredPositional
Question mark

The string to replace the matches with or a function that gets a dictionary for each match and can return individual replacement strings.

count
integer

If given, only the first count matches of the pattern are placed.

trim method

Removes matches of a pattern from one or both sides of the string, once or repeatedly and returns the resulting string.

value.trim(
stringregex,at: alignment,repeat: boolean,
) -> string

pattern
string or regex
RequiredPositional
Question mark

The pattern to search for.

at
alignment

Can be start or end to only trim the start or end of the string. If omitted, both sides are trimmed.

repeat
boolean

Whether to repeatedly removes matches of the pattern or just once. Defaults to true.

split method

Splits a string at matches of a specified pattern and returns an array of the resulting parts.

value.split(
stringregex
) -> array

pattern
string or regex
Positional
Question mark

The pattern to split at. Defaults to whitespace.