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 bytes. Indices are zero-based and negative indices wrap around to the end of the string.

You can convert a value to a string with the str constructor.

Example

Escape sequences

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

• \\ for a backslash
• \" for a quote
• \n for a newline
• \r for a carriage return
• \t for a tab
• \u\{1f600\} for a hexadecimal Unicode escape sequence

Constructor

Converts a value to a string.

• Integers are formatted in base 10. This can be overridden with the optional base parameter.
• Floats are formatted in base 10 and never in exponential notation.
• Negative integers and floats are formatted with the Unicode minus sign ("−" U+2212) instead of the ASCII minus sign ("-" U+002D).
• From labels the name is extracted.
• Bytes are decoded as UTF-8.

If you wish to convert from and to Unicode code points, see the to-unicode and from-unicode functions.

#str(
  value,
  base: int
) -> str

Parameters

Methods

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

Extracts the first grapheme cluster of the string.

Returns the provided default value if the string is empty or fails with an error if no default value was specified.

#str.first(
  default: str
) -> str

Parameters

Extracts the last grapheme cluster of the string.

Returns the provided default value if the string is empty or fails with an error if no default value was specified.

#str.last(
  default: str
) -> str

Parameters

Extracts 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.

#str.at(
  index,
  default: any
) -> any

Parameters

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

#str.slice(
  start,
  end,
  count: int
) -> str

Parameters

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

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

Converts a character into its corresponding code point.

#str.to-unicode(
  character
) -> int

Parameters

Converts a unicode code point into its corresponding string.

#str.from-unicode(
  value
) -> str

Parameters

Normalizes the string to the given Unicode normal form.

This is useful when manipulating strings containing Unicode combining characters.

#assert.eq("é".normalize(form: "nfd"), "e\u{0301}")
#assert.eq("ſ́".normalize(form: "nfkc"), "ś")

#str.normalize(
  form: str
) -> str

Parameters

Whether the string contains the specified pattern.

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

#str.contains(
  pattern
) -> bool

Parameters

Whether the string starts with the specified pattern.

#str.starts-with(
  pattern
) -> bool

Parameters

Whether the string ends with the specified pattern.

#str.ends-with(
  pattern
) -> bool

Parameters

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

#str.find(
  pattern
) -> none str

Parameters

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.

#str.position(
  pattern
) -> none int

Parameters

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:

• start: The start offset of the match
• end: The end offset of the match
• text: The text that matched.
• captures: An array containing a string for each matched capturing group. The first item of the array contains the first matched capturing, not the whole match! This is empty unless the pattern was a regex with capturing groups.

#str.match(
  pattern
) -> none dictionary

Parameters

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.

#str.matches(
  pattern
) -> array

Parameters

Replace at most count occurrences of the given pattern with a replacement string or function (beginning from the start). If no count is given, all occurrences are replaced.

#str.replace(
  pattern,
  replacement,
  count: int
) -> str

Parameters

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

#str.trim(
  pattern,
  at: alignment,
  repeat: bool
) -> str

Parameters

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

When the empty string is used as a separator, it separates every character (i.e., Unicode code point) in the string, along with the beginning and end of the string. In practice, this means that the resulting list of parts will contain the empty string at the start and end of the list.

#str.split(
  pattern
) -> array

Parameters

Reverse the string.