{"route":"/en-US-v0.13.1/reference/foundations/dictionary/","title":"Dictionary","description":"Documentation for the Dictionary type.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"example","name":"Example","children":[]},{"id":"constructor","name":"Constructor","children":[{"id":"constructor-value","name":"value","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-len","name":"Length","children":[]},{"id":"definitions-at","name":"At","children":[{"id":"definitions-at-key","name":"key","children":[]},{"id":"definitions-at-default","name":"default","children":[]}]},{"id":"definitions-insert","name":"Insert","children":[{"id":"definitions-insert-key","name":"key","children":[]},{"id":"definitions-insert-value","name":"value","children":[]}]},{"id":"definitions-remove","name":"Remove","children":[{"id":"definitions-remove-key","name":"key","children":[]},{"id":"definitions-remove-default","name":"default","children":[]}]},{"id":"definitions-keys","name":"Keys","children":[]},{"id":"definitions-values","name":"Values","children":[]},{"id":"definitions-pairs","name":"Pairs","children":[]}]}],"body":{"kind":"type","content":{"name":"dictionary","title":"Dictionary","keywords":[],"oneliner":"A map from string keys to values.","details":"

A map from string keys to values.

\n

You can construct a dictionary by enclosing comma-separated key: value\npairs in parentheses. The values do not have to be of the same type. Since\nempty parentheses already yield an empty array, you have to use the special\n(:) syntax to create an empty dictionary.

\n

A dictionary is conceptually similar to an array, but it is indexed by\nstrings instead of integers. You can access and create dictionary entries\nwith the .at() method. If you know the key statically, you can\nalternatively use field access notation (.key) to\naccess the value. Dictionaries can be added with the + operator and\njoined together. To check whether a key is present in\nthe dictionary, use the in keyword.

\n

You can iterate over the pairs in a dictionary using a for\nloop. This will iterate in the order the pairs were\ninserted / declared.

\n

Example

\n
#let dict = (\n  name: "Typst",\n  born: 2019,\n)\n\n#dict.name \\\n#(dict.launch = 20)\n#dict.len() \\\n#dict.keys() \\\n#dict.values() \\\n#dict.at("born") \\\n#dict.insert("city", "Berlin ")\n#("name" in dict)\n
\"Preview\"
","constructor":{"path":[],"name":"dictionary","title":"Construct","keywords":[],"oneliner":"Converts a value into a dictionary.","element":false,"contextual":false,"deprecation":null,"details":"

Converts a value into a dictionary.

\n

Note that this function is only intended for conversion of a\ndictionary-like value to a dictionary, not for creation of a dictionary\nfrom individual pairs. Use the dictionary syntax (key: value) instead.

","example":"
#dictionary(sys).at("version")\n
\"Preview\"
","self":false,"params":[{"name":"value","details":"

The value that should be converted to a dictionary.

","example":null,"types":["module"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["dictionary"],"scope":[]},"scope":[{"path":["dictionary"],"name":"len","title":"Length","keywords":[],"oneliner":"The number of pairs in the dictionary.","element":false,"contextual":false,"deprecation":null,"details":"

The number of pairs in the dictionary.

","example":null,"self":true,"params":[],"returns":["int"],"scope":[]},{"path":["dictionary"],"name":"at","title":"At","keywords":[],"oneliner":"Returns the value associated with the specified key in the dictionary.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the value associated with the specified key in the dictionary.\nMay be used on the left-hand side of an assignment if the key is already\npresent in the dictionary. Returns the default value if the key is not\npart of the dictionary or fails with an error if no default value was\nspecified.

","example":null,"self":true,"params":[{"name":"key","details":"

The key at which to retrieve the item.

","example":null,"types":["str"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"default","details":"

A default value to return if the key is not part of the dictionary.

","example":null,"types":["any"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["any"],"scope":[]},{"path":["dictionary"],"name":"insert","title":"Insert","keywords":[],"oneliner":"Inserts a new pair into the dictionary. If the dictionary already","element":false,"contextual":false,"deprecation":null,"details":"

Inserts a new pair into the dictionary. If the dictionary already\ncontains this key, the value is updated.

","example":null,"self":true,"params":[{"name":"key","details":"

The key of the pair that should be inserted.

","example":null,"types":["str"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"value","details":"

The value of the pair that should be inserted.

","example":null,"types":["any"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":[],"scope":[]},{"path":["dictionary"],"name":"remove","title":"Remove","keywords":[],"oneliner":"Removes a pair from the dictionary by key and return the value.","element":false,"contextual":false,"deprecation":null,"details":"

Removes a pair from the dictionary by key and return the value.

","example":null,"self":true,"params":[{"name":"key","details":"

The key of the pair to remove.

","example":null,"types":["str"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false},{"name":"default","details":"

A default value to return if the key does not exist.

","example":null,"types":["any"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["any"],"scope":[]},{"path":["dictionary"],"name":"keys","title":"Keys","keywords":[],"oneliner":"Returns the keys of the dictionary as an array in insertion order.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the keys of the dictionary as an array in insertion order.

","example":null,"self":true,"params":[],"returns":["array"],"scope":[]},{"path":["dictionary"],"name":"values","title":"Values","keywords":[],"oneliner":"Returns the values of the dictionary as an array in insertion order.","element":false,"contextual":false,"deprecation":null,"details":"

Returns the values of the dictionary as an array in insertion order.

","example":null,"self":true,"params":[],"returns":["array"],"scope":[]},{"path":["dictionary"],"name":"pairs","title":"Pairs","keywords":[],"oneliner":"Returns the keys and values of the dictionary as an array of pairs. Each","element":false,"contextual":false,"deprecation":null,"details":"

Returns the keys and values of the dictionary as an array of pairs. Each\npair is represented as an array of length two.

","example":null,"self":true,"params":[],"returns":["array"],"scope":[]}]}}}