{"route":"/en-US-v0.14.1/reference/foundations/str/","title":"String","description":"Documentation for the String type.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"example","name":"Example","children":[]},{"id":"escapes","name":"Escapes","children":[]},{"id":"constructor","name":"Constructor","children":[{"id":"constructor-value","name":"value","children":[]},{"id":"constructor-base","name":"base","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-len","name":"Length","children":[]},{"id":"definitions-first","name":"First","children":[{"id":"definitions-first-default","name":"default","children":[]}]},{"id":"definitions-last","name":"Last","children":[{"id":"definitions-last-default","name":"default","children":[]}]},{"id":"definitions-at","name":"At","children":[{"id":"definitions-at-index","name":"index","children":[]},{"id":"definitions-at-default","name":"default","children":[]}]},{"id":"definitions-slice","name":"Slice","children":[{"id":"definitions-slice-start","name":"start","children":[]},{"id":"definitions-slice-end","name":"end","children":[]},{"id":"definitions-slice-count","name":"count","children":[]}]},{"id":"definitions-clusters","name":"Clusters","children":[]},{"id":"definitions-codepoints","name":"Codepoints","children":[]},{"id":"definitions-to-unicode","name":"To Unicode","children":[{"id":"definitions-to-unicode-character","name":"character","children":[]}]},{"id":"definitions-from-unicode","name":"From Unicode","children":[{"id":"definitions-from-unicode-value","name":"value","children":[]}]},{"id":"definitions-normalize","name":"Normalize","children":[{"id":"definitions-normalize-form","name":"form","children":[]}]},{"id":"definitions-contains","name":"Contains","children":[{"id":"definitions-contains-pattern","name":"pattern","children":[]}]},{"id":"definitions-starts-with","name":"Starts With","children":[{"id":"definitions-starts-with-pattern","name":"pattern","children":[]}]},{"id":"definitions-ends-with","name":"Ends With","children":[{"id":"definitions-ends-with-pattern","name":"pattern","children":[]}]},{"id":"definitions-find","name":"Find","children":[{"id":"definitions-find-pattern","name":"pattern","children":[]}]},{"id":"definitions-position","name":"Position","children":[{"id":"definitions-position-pattern","name":"pattern","children":[]}]},{"id":"definitions-match","name":"Match","children":[{"id":"definitions-match-pattern","name":"pattern","children":[]}]},{"id":"definitions-matches","name":"Matches","children":[{"id":"definitions-matches-pattern","name":"pattern","children":[]}]},{"id":"definitions-replace","name":"Replace","children":[{"id":"definitions-replace-pattern","name":"pattern","children":[]},{"id":"definitions-replace-replacement","name":"replacement","children":[]},{"id":"definitions-replace-count","name":"count","children":[]}]},{"id":"definitions-trim","name":"Trim","children":[{"id":"definitions-trim-pattern","name":"pattern","children":[]},{"id":"definitions-trim-at","name":"at","children":[]},{"id":"definitions-trim-repeat","name":"repeat","children":[]}]},{"id":"definitions-split","name":"Split","children":[{"id":"definitions-split-pattern","name":"pattern","children":[]}]},{"id":"definitions-rev","name":"Reverse","children":[]}]}],"body":{"kind":"type","content":{"name":"str","title":"String","keywords":[],"oneliner":"A sequence of Unicode codepoints.","details":"

A sequence of Unicode codepoints.

\n

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

\n

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

\n

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

\n

You can convert a value to a string with this type's constructor.

\n

Example

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

Escape sequences

\n

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

\n","constructor":{"path":[],"name":"str","title":"Construct","keywords":[],"oneliner":"Converts a value to a string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Converts a value to a string.

\n\n

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

"},{"kind":"example","content":{"body":"
#str(10) \\\n#str(4000, base: 16) \\\n#str(2.7) \\\n#str(1e8) \\\n#str(<intro>)\n
\"Preview\"
","title":null}}],"self":false,"params":[{"name":"value","details":[{"kind":"html","content":"

The value that should be converted to a string.

"}],"types":["int","float","str","bytes","label","decimal","version","type"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"base","details":[{"kind":"html","content":"

The base (radix) to display integers in, between 2 and 36.

"}],"types":["int"],"strings":[],"default":"10","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},"scope":[{"path":["str"],"name":"len","title":"Length","keywords":[],"oneliner":"The length of the string in UTF-8 encoded bytes.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["int"],"scope":[]},{"path":["str"],"name":"first","title":"First","keywords":[],"oneliner":"Extracts the first grapheme cluster of the string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Extracts the first grapheme cluster of the string.

\n

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

"}],"self":true,"params":[{"name":"default","details":[{"kind":"html","content":"

A default value to return if the string is empty.

"}],"types":["str"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"last","title":"Last","keywords":[],"oneliner":"Extracts the last grapheme cluster of the string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Extracts the last grapheme cluster of the string.

\n

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

"}],"self":true,"params":[{"name":"default","details":[{"kind":"html","content":"

A default value to return if the string is empty.

"}],"types":["str"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"at","title":"At","keywords":[],"oneliner":"Extracts the first grapheme cluster after the specified index.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[{"name":"index","details":[{"kind":"html","content":"

The byte index. If negative, indexes from the back.

"}],"types":["int"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"default","details":[{"kind":"html","content":"

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

"}],"types":["any"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["any"],"scope":[]},{"path":["str"],"name":"slice","title":"Slice","keywords":[],"oneliner":"Extracts a substring of the string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[{"name":"start","details":[{"kind":"html","content":"

The start byte index (inclusive). If negative, indexes from the\nback.

"}],"types":["int"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"end","details":[{"kind":"html","content":"

The end byte index (exclusive). If omitted, the whole slice until\nthe end of the string is extracted. If negative, indexes from the\nback.

"}],"types":["none","int"],"strings":[],"default":"none","positional":true,"named":false,"required":false,"variadic":false,"settable":false},{"name":"count","details":[{"kind":"html","content":"

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

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"clusters","title":"Clusters","keywords":[],"oneliner":"Returns the grapheme clusters of the string as an array of substrings.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["array"],"scope":[]},{"path":["str"],"name":"codepoints","title":"Codepoints","keywords":[],"oneliner":"Returns the Unicode codepoints of the string as an array of substrings.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["array"],"scope":[]},{"path":["str"],"name":"to-unicode","title":"To Unicode","keywords":[],"oneliner":"Converts a character into its corresponding code point.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Converts a character into its corresponding code point.

"},{"kind":"example","content":{"body":"
#"a".to-unicode() \\\n#("a\\u{0300}"\n   .codepoints()\n   .map(str.to-unicode))\n
\"Preview\"
","title":null}}],"self":false,"params":[{"name":"character","details":[{"kind":"html","content":"

The character that should be converted.

"}],"types":["str"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["int"],"scope":[]},{"path":["str"],"name":"from-unicode","title":"From Unicode","keywords":[],"oneliner":"Converts a unicode code point into its corresponding string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Converts a unicode code point into its corresponding string.

"},{"kind":"example","content":{"body":"
#str.from-unicode(97)\n
\"Preview\"
","title":null}}],"self":false,"params":[{"name":"value","details":[{"kind":"html","content":"

The code point that should be converted.

"}],"types":["int"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"normalize","title":"Normalize","keywords":[],"oneliner":"Normalizes the string to the given Unicode normal form.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Normalizes the string to the given Unicode normal form.

\n

This is useful when manipulating strings containing Unicode combining\ncharacters.

"},{"kind":"example","content":{"body":"
#assert.eq("é".normalize(form: "nfd"), "e\\u{0301}")\n#assert.eq("ſ́".normalize(form: "nfkc"), "ś")\n
","title":null}}],"self":true,"params":[{"name":"form","details":[],"types":["str"],"strings":[{"string":"nfc","details":"

Canonical composition where e.g. accented letters are turned into a\nsingle Unicode codepoint.

"},{"string":"nfd","details":"

Canonical decomposition where e.g. accented letters are split into a\nseparate base and diacritic.

"},{"string":"nfkc","details":"

Like NFC, but using the Unicode compatibility decompositions.

"},{"string":"nfkd","details":"

Like NFD, but using the Unicode compatibility decompositions.

"}],"default":""nfc"","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"contains","title":"Contains","keywords":[],"oneliner":"Whether the string contains the specified pattern.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Whether the string contains the specified pattern.

\n

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

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["bool"],"scope":[]},{"path":["str"],"name":"starts-with","title":"Starts With","keywords":[],"oneliner":"Whether the string starts with the specified pattern.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Whether the string starts with the specified pattern.

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern the string might start with.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["bool"],"scope":[]},{"path":["str"],"name":"ends-with","title":"Ends With","keywords":[],"oneliner":"Whether the string ends with the specified pattern.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Whether the string ends with the specified pattern.

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern the string might end with.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["bool"],"scope":[]},{"path":["str"],"name":"find","title":"Find","keywords":[],"oneliner":"Searches for the specified pattern in the string and returns the first match as a string or `{none}` if there is no match.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["none","str"],"scope":[]},{"path":["str"],"name":"position","title":"Position","keywords":[],"oneliner":"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.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["none","int"],"scope":[]},{"path":["str"],"name":"match","title":"Match","keywords":[],"oneliner":"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.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

\n

The returned dictionary has the following keys:

\n"},{"kind":"example","content":{"body":"
#let pat = regex("not (a|an) (apple|cat)")\n#"I'm a doctor, not an apple.".match(pat) \\\n#"I am not a cat!".match(pat)\n
\"Preview\"
","title":"Shape of the returned dictionary"}},{"kind":"example","content":{"body":"
#assert.eq("Is there a".match("for this?"), none)\n#"The time of my life.".match(regex("[mit]+e"))\n
\"Preview\"
","title":"Different kinds of patterns"}}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["none","dictionary"],"scope":[]},{"path":["str"],"name":"matches","title":"Matches","keywords":[],"oneliner":"Searches for the specified pattern in the string and returns an array of dictionaries with details about all matches.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"},{"kind":"example","content":{"body":"
#"Day by Day.".matches("Day")\n
\"Preview\"
","title":null}}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["array"],"scope":[]},{"path":["str"],"name":"replace","title":"Replace","keywords":[],"oneliner":"Replace at most `count` occurrences of the given pattern with a replacement string or function (beginning from the start).","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for.

"}],"types":["str","regex"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"replacement","details":[{"kind":"html","content":"

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

\n

The dictionary passed to the function has the same shape as the\ndictionary returned by match.

"}],"types":["str","function"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"count","details":[{"kind":"html","content":"

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

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"trim","title":"Trim","keywords":[],"oneliner":"Removes matches of a pattern from one or both sides of the string, once or repeatedly and returns the resulting string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to search for. If none, trims white spaces.

"}],"types":["none","str","regex"],"strings":[],"default":"none","positional":true,"named":false,"required":false,"variadic":false,"settable":false},{"name":"at","details":[{"kind":"html","content":"

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

"}],"types":["alignment"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"repeat","details":[{"kind":"html","content":"

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

"}],"types":["bool"],"strings":[],"default":"true","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["str"],"name":"split","title":"Split","keywords":[],"oneliner":"Splits a string at matches of a specified pattern and returns an array of the resulting parts.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

\n

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

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The pattern to split at. Defaults to whitespace.

"}],"types":["none","str","regex"],"strings":[],"default":"none","positional":true,"named":false,"required":false,"variadic":false,"settable":false}],"returns":["array"],"scope":[]},{"path":["str"],"name":"rev","title":"Reverse","keywords":[],"oneliner":"Reverse the string.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Reverse the string.

"}],"self":true,"params":[],"returns":["str"],"scope":[]}]}}}