# foundations Foundational types and functions. Here, you'll find documentation for basic data types like integers and strings as well as details about core computational functions. # arguments Captured arguments to a function. ## Argument Sinks Like built-in functions, custom functions can also take a variable number of arguments. You can specify an argument sink which collects all excess arguments as `..sink`. The resulting `sink` value is of the `arguments` type. It exposes methods to access the positional and named arguments. #let format(title, ..authors) = { let by = authors .pos() .join(", ", last: " and ") [*#title* \ _Written by #by;_] } #format("ArtosFlow", "Jane", "Joe") ## Spreading Inversely to an argument sink, you can spread arguments, arrays and dictionaries into a function call with the `..spread` operator: #let array = (2, 3, 5) #calc.min(..array) #let dict = (fill: blue) #text(..dict)[Hello] # arguments Construct spreadable arguments in place. This function behaves like `let args(..sink) = sink`. arguments The arguments to construct. # at Returns the positional argument at the specified index, or the named argument with the specified name. If the key is an integer, this is equivalent to first calling `pos` and then `array.at`. If it is a string, this is equivalent to first calling `named` and then `dictionary.at`. key The index or name of the argument to get. default A default value to return if the key is invalid. # pos Returns the captured positional arguments as an array. # named Returns the captured named arguments as a dictionary. # array A sequence of values. You can construct an array by enclosing a comma-separated sequence of values in parentheses. The values do not have to be of the same type. You can access and update array items with the `.at()` method. Indices are zero-based and negative indices wrap around to the end of the array. You can iterate over an array using a for loop. Arrays can be added together with the `+` operator, joined together and multiplied with integers. Note: An array of length one needs a trailing comma, as in `(1,)`. This is to disambiguate from a simple parenthesized expressions like `(1 + 2) * 3`. An empty array is written as `()`. ## Example #let values = (1, 7, 4, -3, 2) #values.at(0) \ #(values.at(0) = 3) #values.at(-1) \ #values.find(calc.even) \ #values.filter(calc.odd) \ #values.map(calc.abs) \ #values.rev() \ #(1, (2, 3)).flatten() \ #(("A", "B", "C") .join(", ", last: " and ")) # array Converts a value to an array. Note that this function is only intended for conversion of a collection-like value to an array, not for creation of an array from individual items. Use the array syntax `(1, 2, 3)` (or `(1,)` for a single-element array) instead. value The value that should be converted to an array. # len The number of values in the array. # first Returns the first item in the array. May be used on the left-hand side of an assignment. Fails with an error if the array is empty. # last Returns the last item in the array. May be used on the left-hand side of an assignment. Fails with an error if the array is empty. # at Returns the item at the specified index in the array. May be used on the left-hand side of an assignment. Returns the default value if the index is out of bounds or fails with an error if no default value was specified. index The index at which to retrieve the item. If negative, indexes from the back. default A default value to return if the index is out of bounds. # push Adds a value to the end of the array. value The value to insert at the end of the array. # pop Removes the last item from the array and returns it. Fails with an error if the array is empty. # insert Inserts a value into the array at the specified index, shifting all subsequent elements to the right. Fails with an error if the index is out of bounds. To replace an element of an array, use `at`. index The index at which to insert the item. If negative, indexes from the back. value The value to insert into the array. # remove Removes the value at the specified index from the array and return it. index The index at which to remove the item. If negative, indexes from the back. default A default value to return if the index is out of bounds. # slice Extracts a subslice of the array. Fails with an error if the start or end index is out of bounds. start The start index (inclusive). If negative, indexes from the back. end The end index (exclusive). If omitted, the whole slice until the end of the array is extracted. If negative, indexes from the back. count The number of items to extract. This is equivalent to passing `start + count` as the `end` position. Mutually exclusive with `end`. # contains Whether the array contains the specified value. This method also has dedicated syntax: You can write `2 in (1, 2, 3)` instead of `(1, 2, 3).contains(2)`. value The value to search for. # find Searches for an item for which the given function returns `true` and returns the first match or `none` if there is no match. searcher The function to apply to each item. Must return a boolean. # position Searches for an item for which the given function returns `true` and returns the index of the first match or `none` if there is no match. searcher The function to apply to each item. Must return a boolean. # range Create an array consisting of a sequence of numbers. If you pass just one positional parameter, it is interpreted as the `end` of the range. If you pass two, they describe the `start` and `end` of the range. This function is available both in the array function's scope and globally. start The start of the range (inclusive). end The end of the range (exclusive). step The distance between the generated numbers. # filter Produces a new array with only the items from the original one for which the given function returns true. test The function to apply to each item. Must return a boolean. # map Produces a new array in which all items from the original one were transformed with the given function. mapper The function to apply to each item. # enumerate Returns a new array with the values alongside their indices. The returned array consists of `(index, value)` pairs in the form of length-2 arrays. These can be destructured with a let binding or for loop. start The index returned for the first pair of the returned list. # zip Zips the array with other arrays. Returns an array of arrays, where the `i`th inner array contains all the `i`th elements from each original array. If the arrays to be zipped have different lengths, they are zipped up to the last element of the shortest array and all remaining elements are ignored. This function is variadic, meaning that you can zip multiple arrays together at once: `(1, 2).zip(("A", "B"), (10, 20))` yields `((1, "A", 10), (2, "B", 20))`. exact Whether all arrays have to have the same length. For example, `(1, 2).zip((1, 2, 3), exact: true)` produces an error. others The arrays to zip with. # fold Folds all items into a single value using an accumulator function. init The initial value to start with. folder The folding function. Must have two parameters: One for the accumulated value and one for an item. # sum Sums all items (works for all types that can be added). default What to return if the array is empty. Must be set if the array can be empty. # product Calculates the product all items (works for all types that can be multiplied). default What to return if the array is empty. Must be set if the array can be empty. # any Whether the given function returns `true` for any item in the array. test The function to apply to each item. Must return a boolean. # all Whether the given function returns `true` for all items in the array. test The function to apply to each item. Must return a boolean. # flatten Combine all nested arrays into a single flat one. # rev Return a new array with the same items, but in reverse order. # split Split the array at occurrences of the specified value. at The value to split at. # join Combine all items in the array into one. separator A value to insert between each item of the array. last An alternative separator between the last two items. # intersperse Returns an array with a copy of the separator value placed between adjacent elements. separator The value that will be placed between each adjacent element. # chunks Splits an array into non-overlapping chunks, starting at the beginning, ending with a single remainder chunk. All chunks but the last have `chunk-size` elements. If `exact` is set to `true`, the remainder is dropped if it contains less than `chunk-size` elements. chunk-size How many elements each chunk may at most contain. exact Whether to keep the remainder if its size is less than `chunk-size`. # windows Returns sliding windows of `window-size` elements over an array. If the array length is less than `window-size`, this will return an empty array. window-size How many elements each window will contain. # sorted Return a sorted version of this array, optionally by a given key function. The sorting algorithm used is stable. Returns an error if two values could not be compared or if the key function (if given) yields an error. To sort according to multiple criteria at once, e.g. in case of equality between some criteria, the key function can return an array. The results are in lexicographic order. key If given, applies this function to the elements in the array to determine the keys to sort by. # dedup Deduplicates all items in the array. Returns a new array with all duplicate items removed. Only the first element of each duplicate is kept. key If given, applies this function to the elements in the array to determine the keys to deduplicate by. # to-dict Converts an array of pairs into a dictionary. The first value of each pair is the key, the second the value. If the same key occurs multiple times, the last value is selected. # reduce Reduces the elements to a single one, by repeatedly applying a reducing operation. If the array is empty, returns `none`, otherwise, returns the result of the reduction. The reducing function is a closure with two arguments: an "accumulator", and an element. For arrays with at least one element, this is the same as `array.fold` with the first element of the array as the initial accumulator value, folding every subsequent element into it. reducer The reducing function. Must have two parameters: One for the accumulated value and one for an item. # assert Ensures that a condition is fulfilled. Fails with an error if the condition is not fulfilled. Does not produce any output in the document. If you wish to test equality between two values, see `assert.eq` and `assert.ne`. ## Example #assert(1 < 2, message: "math broke") condition The condition that must be true for the assertion to pass. message The error message when the assertion fails. # eq Ensures that two values are equal. Fails with an error if the first value is not equal to the second. Does not produce any output in the document. left The first value to compare. right The second value to compare. message An optional message to display on error instead of the representations of the compared values. # ne Ensures that two values are not equal. Fails with an error if the first value is equal to the second. Does not produce any output in the document. left The first value to compare. right The second value to compare. message An optional message to display on error instead of the representations of the compared values. # auto A value that indicates a smart default. The auto type has exactly one value: `auto`. Parameters that support the `auto` value have some smart default or contextual behaviour. A good example is the text direction parameter. Setting it to `auto` lets Typst automatically determine the direction from the text language. # bool A type with two states. The boolean type has two values: `true` and `false`. It denotes whether something is active or enabled. ## Example #false \ #true \ #(1 < 2) # bytes A sequence of bytes. This is conceptually similar to an array of integers between `0` and `255`, but represented much more efficiently. You can iterate over it using a for loop. You can convert * a string or an array of integers to bytes with the `bytes` constructor * bytes to a string with the `str` constructor, with UTF-8 encoding * bytes to an array of integers with the `array` constructor When reading data from a file, you can decide whether to load it as a string or as raw bytes. #bytes((123, 160, 22, 0)) \ #bytes("Hello 😃") #let data = read( "rhino.png", encoding: none, ) // Magic bytes. #array(data.slice(0, 4)) \ #str(data.slice(1, 4)) # bytes Converts a value to bytes. * Strings are encoded in UTF-8. * Arrays of integers between `0` and `255` are converted directly. The dedicated byte representation is much more efficient than the array representation and thus typically used for large byte buffers (e.g. image data). value The value that should be converted to bytes. # len The length in bytes. # at Returns the byte at 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. index The index at which to retrieve the byte. default A default value to return if the index is out of bounds. # slice Extracts a subslice of the bytes. Fails with an error if the start or end index is out of bounds. start The start index (inclusive). end The end index (exclusive). If omitted, the whole slice until the end is extracted. count The number of items to extract. This is equivalent to passing `start + count` as the `end` position. Mutually exclusive with `end`. # calc Module for calculations and processing of numeric values. These definitions are part of the `calc` module and not imported by default. In addition to the functions listed below, the `calc` module also defines the constants `pi`, `tau`, `e`, and `inf`. # abs Calculates the absolute value of a numeric value. value The value whose absolute value to calculate. # pow Raises a value to some exponent. base The base of the power. If this is a `decimal`, the exponent can only be an integer. exponent The exponent of the power. # exp Raises a value to some exponent of e. exponent The exponent of the power. # sqrt Calculates the square root of a number. value The number whose square root to calculate. Must be non-negative. # root Calculates the real nth root of a number. If the number is negative, then n must be odd. radicand The expression to take the root of index Which root of the radicand to take # sin Calculates the sine of an angle. When called with an integer or a float, they will be interpreted as radians. angle The angle whose sine to calculate. # cos Calculates the cosine of an angle. When called with an integer or a float, they will be interpreted as radians. angle The angle whose cosine to calculate. # tan Calculates the tangent of an angle. When called with an integer or a float, they will be interpreted as radians. angle The angle whose tangent to calculate. # asin Calculates the arcsine of a number. value The number whose arcsine to calculate. Must be between -1 and 1. # acos Calculates the arccosine of a number. value The number whose arcsine to calculate. Must be between -1 and 1. # atan Calculates the arctangent of a number. value The number whose arctangent to calculate. # atan2 Calculates the four-quadrant arctangent of a coordinate. The arguments are `(x, y)`, not `(y, x)`. x The X coordinate. y The Y coordinate. # sinh Calculates the hyperbolic sine of a hyperbolic angle. value The hyperbolic angle whose hyperbolic sine to calculate. # cosh Calculates the hyperbolic cosine of a hyperbolic angle. value The hyperbolic angle whose hyperbolic cosine to calculate. # tanh Calculates the hyperbolic tangent of an hyperbolic angle. value The hyperbolic angle whose hyperbolic tangent to calculate. # log Calculates the logarithm of a number. If the base is not specified, the logarithm is calculated in base 10. value The number whose logarithm to calculate. Must be strictly positive. base The base of the logarithm. May not be zero. # ln Calculates the natural logarithm of a number. value The number whose logarithm to calculate. Must be strictly positive. # fact Calculates the factorial of a number. number The number whose factorial to calculate. Must be non-negative. # perm Calculates a permutation. Returns the `k`-permutation of `n`, or the number of ways to choose `k` items from a set of `n` with regard to order. base The base number. Must be non-negative. numbers The number of permutations. Must be non-negative. # binom Calculates a binomial coefficient. Returns the `k`-combination of `n`, or the number of ways to choose `k` items from a set of `n` without regard to order. n The upper coefficient. Must be non-negative. k The lower coefficient. Must be non-negative. # gcd Calculates the greatest common divisor of two integers. a The first integer. b The second integer. # lcm Calculates the least common multiple of two integers. a The first integer. b The second integer. # floor Rounds a number down to the nearest integer. If the number is already an integer, it is returned unchanged. Note that this function will always return an integer, and will error if the resulting `float` or `decimal` is larger than the maximum 64-bit signed integer or smaller than the minimum for that type. value The number to round down. # ceil Rounds a number up to the nearest integer. If the number is already an integer, it is returned unchanged. Note that this function will always return an integer, and will error if the resulting `float` or `decimal` is larger than the maximum 64-bit signed integer or smaller than the minimum for that type. value The number to round up. # trunc Returns the integer part of a number. If the number is already an integer, it is returned unchanged. Note that this function will always return an integer, and will error if the resulting `float` or `decimal` is larger than the maximum 64-bit signed integer or smaller than the minimum for that type. value The number to truncate. # fract Returns the fractional part of a number. If the number is an integer, returns `0`. value The number to truncate. # round Rounds a number to the nearest integer away from zero. Optionally, a number of decimal places can be specified. If the number of digits is negative, its absolute value will indicate the amount of significant integer digits to remove before the decimal point. Note that this function will return the same type as the operand. That is, applying `round` to a `float` will return a `float`, and to a `decimal`, another `decimal`. You may explicitly convert the output of this function to an integer with `int`, but note that such a conversion will error if the `float` or `decimal` is larger than the maximum 64-bit signed integer or smaller than the minimum integer. In addition, this function can error if there is an attempt to round beyond the maximum or minimum integer or `decimal`. If the number is a `float`, such an attempt will cause `float.inf` or `-float.inf` to be returned for maximum and minimum respectively. value The number to round. digits If positive, the number of decimal places. If negative, the number of significant integer digits that should be removed before the decimal point. # clamp Clamps a number between a minimum and maximum value. value The number to clamp. min The inclusive minimum value. max The inclusive maximum value. # min Determines the minimum of a sequence of values. values The sequence of values from which to extract the minimum. Must not be empty. # max Determines the maximum of a sequence of values. values The sequence of values from which to extract the maximum. Must not be empty. # even Determines whether an integer is even. value The number to check for evenness. # odd Determines whether an integer is odd. value The number to check for oddness. # rem Calculates the remainder of two numbers. The value `calc.rem(x, y)` always has the same sign as `x`, and is smaller in magnitude than `y`. This can error if given a `decimal` input and the dividend is too small in magnitude compared to the divisor. dividend The dividend of the remainder. divisor The divisor of the remainder. # div-euclid Performs euclidean division of two numbers. The result of this computation is that of a division rounded to the integer `n` such that the dividend is greater than or equal to `n` times the divisor. dividend The dividend of the division. divisor The divisor of the division. # rem-euclid This calculates the least nonnegative remainder of a division. Warning: Due to a floating point round-off error, the remainder may equal the absolute value of the divisor if the dividend is much smaller in magnitude than the divisor and the dividend is negative. This only applies for floating point inputs. In addition, this can error if given a `decimal` input and the dividend is too small in magnitude compared to the divisor. dividend The dividend of the remainder. divisor The divisor of the remainder. # quo Calculates the quotient (floored division) of two numbers. Note that this function will always return an integer, and will error if the resulting `float` or `decimal` is larger than the maximum 64-bit signed integer or smaller than the minimum for that type. dividend The dividend of the quotient. divisor The divisor of the quotient. # norm Calculates the p-norm of a sequence of values. p The p value to calculate the p-norm of. values The sequence of values from which to calculate the p-norm. Returns `0.0` if empty. # content A piece of document content. This type is at the heart of Typst. All markup you write and most functions you call produce content values. You can create a content value by enclosing markup in square brackets. This is also how you pass content to functions. ## Example Type of *Hello!* is #type([*Hello!*]) Content can be added with the `+` operator, joined together and multiplied with integers. Wherever content is expected, you can also pass a string or `none`. ## Representation Content consists of elements with fields. When constructing an element with its element function, you provide these fields as arguments and when you have a content value, you can access its fields with field access syntax. Some fields are required: These must be provided when constructing an element and as a consequence, they are always available through field access on content of that type. Required fields are marked as such in the documentation. Most fields are optional: Like required fields, they can be passed to the element function to configure them for a single element. However, these can also be configured with set rules to apply them to all elements within a scope. Optional fields are only available with field access syntax when they were explicitly passed to the element function, not when they result from a set rule. Each element has a default appearance. However, you can also completely customize its appearance with a show rule. The show rule is passed the element. It can access the element's field and produce arbitrary content from it. In the web app, you can hover over a content variable to see exactly which elements the content is composed of and what fields they have. Alternatively, you can inspect the output of the `repr` function. # func The content's element function. This function can be used to create the element contained in this content. It can be used in set and show rules for the element. Can be compared with global functions to check whether you have a specific kind of element. # has Whether the content has the specified field. field The field to look for. # at Access the specified field on the content. Returns the default value if the field does not exist or fails with an error if no default value was specified. field The field to access. default A default value to return if the field does not exist. # fields Returns the fields of this content. # location The location of the content. This is only available on content returned by query or provided by a show rule, for other content it will be `none`. The resulting location can be used with counters, state and queries. # datetime Represents a date, a time, or a combination of both. Can be created by either specifying a custom datetime using this type's constructor function or getting the current date with `datetime.today`. ## Example #let date = datetime( year: 2020, month: 10, day: 4, ) #date.display() \ #date.display( "y:[year repr:last_two]" ) #let time = datetime( hour: 18, minute: 2, second: 23, ) #time.display() \ #time.display( "h:[hour repr:12][period]" ) ## Datetime and Duration You can get a duration by subtracting two datetime: #let first-of-march = datetime(day: 1, month: 3, year: 2024) #let first-of-jan = datetime(day: 1, month: 1, year: 2024) #let distance = first-of-march - first-of-jan #distance.hours() You can also add/subtract a datetime and a duration to retrieve a new, offset datetime: #let date = datetime(day: 1, month: 3, year: 2024) #let two-days = duration(days: 2) #let two-days-earlier = date - two-days #let two-days-later = date + two-days #date.display() \ #two-days-earlier.display() \ #two-days-later.display() ## Format You can specify a customized formatting using the `display` method. The format of a datetime is specified by providing components with a specified number of modifiers. A component represents a certain part of the datetime that you want to display, and with the help of modifiers you can define how you want to display that component. In order to display a component, you wrap the name of the component in square brackets (e.g. `[year]` will display the year). In order to add modifiers, you add a space after the component name followed by the name of the modifier, a colon and the value of the modifier (e.g. `[month repr:short]` will display the short representation of the month). The possible combination of components and their respective modifiers is as follows: * `year`: Displays the year of the datetime. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the year is padded. * `repr` Can be either `full` in which case the full year is displayed or `last_two` in which case only the last two digits are displayed. * `sign`: Can be either `automatic` or `mandatory`. Specifies when the sign should be displayed. * `month`: Displays the month of the datetime. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the month is padded. * `repr`: Can be either `numerical`, `long` or `short`. Specifies if the month should be displayed as a number or a word. Unfortunately, when choosing the word representation, it can currently only display the English version. In the future, it is planned to support localization. * `day`: Displays the day of the datetime. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the day is padded. * `week_number`: Displays the week number of the datetime. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the week number is padded. * `repr`: Can be either `ISO`, `sunday` or `monday`. In the case of `ISO`, week numbers are between 1 and 53, while the other ones are between 0 and 53. * `weekday`: Displays the weekday of the date. * `repr` Can be either `long`, `short`, `sunday` or `monday`. In the case of `long` and `short`, the corresponding English name will be displayed (same as for the month, other languages are currently not supported). In the case of `sunday` and `monday`, the numerical value will be displayed (assuming Sunday and Monday as the first day of the week, respectively). * `one_indexed`: Can be either `true` or `false`. Defines whether the numerical representation of the week starts with 0 or 1. * `hour`: Displays the hour of the date. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the hour is padded. * `repr`: Can be either `24` or `12`. Changes whether the hour is displayed in the 24-hour or 12-hour format. * `period`: The AM/PM part of the hour * `case`: Can be `lower` to display it in lower case and `upper` to display it in upper case. * `minute`: Displays the minute of the date. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the minute is padded. * `second`: Displays the second of the date. * `padding`: Can be either `zero`, `space` or `none`. Specifies how the second is padded. Keep in mind that not always all components can be used. For example, if you create a new datetime with `datetime(year: 2023, month: 10, day: 13)`, it will be stored as a plain date internally, meaning that you cannot use components such as `hour` or `minute`, which would only work on datetimes that have a specified time. # datetime Creates a new datetime. You can specify the datetime using a year, month, day, hour, minute, and second. Note: Depending on which components of the datetime you specify, Typst will store it in one of the following three ways: * If you specify year, month and day, Typst will store just a date. * If you specify hour, minute and second, Typst will store just a time. * If you specify all of year, month, day, hour, minute and second, Typst will store a full datetime. Depending on how it is stored, the `display` method will choose a different formatting by default. year The year of the datetime. month The month of the datetime. day The day of the datetime. hour The hour of the datetime. minute The minute of the datetime. second The second of the datetime. # today Returns the current date. offset An offset to apply to the current UTC date. If set to `auto`, the offset will be the local offset. # display Displays the datetime in a specified format. Depending on whether you have defined just a date, a time or both, the default format will be different. If you specified a date, it will be `[year]-[month]-[day]`. If you specified a time, it will be `[hour]:[minute]:[second]`. In the case of a datetime, it will be `[year]-[month]-[day] [hour]:[minute]:[second]`. See the format syntax for more information. pattern The format used to display the datetime. # year The year if it was specified, or `none` for times without a date. # month The month if it was specified, or `none` for times without a date. # weekday The weekday (counting Monday as 1) or `none` for times without a date. # day The day if it was specified, or `none` for times without a date. # hour The hour if it was specified, or `none` for dates without a time. # minute The minute if it was specified, or `none` for dates without a time. # second The second if it was specified, or `none` for dates without a time. # ordinal The ordinal (day of the year), or `none` for times without a date. # decimal A fixed-point decimal number type. This type should be used for precise arithmetic operations on numbers represented in base 10. A typical use case is representing currency. ## Example Decimal: #(decimal("0.1") + decimal("0.2")) \ Float: #(0.1 + 0.2) ## Construction and casts To create a decimal number, use the `decimal(string)` constructor, such as in `decimal("3.141592653")` (note the double quotes!). This constructor preserves all given fractional digits, provided they are representable as per the limits specified below (otherwise, an error is raised). You can also convert any integer to a decimal with the `decimal(int)` constructor, e.g. `decimal(59)`. However, note that constructing a decimal from a floating-point number, while supported, is an imprecise conversion and therefore discouraged. A warning will be raised if Typst detects that there was an accidental `float` to `decimal` cast through its constructor, e.g. if writing `decimal(3.14)` (note the lack of double quotes, indicating this is an accidental `float` cast and therefore imprecise). It is recommended to use strings for constant decimal values instead (e.g. `decimal("3.14")`). The precision of a `float` to `decimal` cast can be slightly improved by rounding the result to 15 digits with `calc.round`, but there are still no precision guarantees for that kind of conversion. ## Operations Basic arithmetic operations are supported on two decimals and on pairs of decimals and integers. Built-in operations between `float` and `decimal` are not supported in order to guard against accidental loss of precision. They will raise an error instead. Certain `calc` functions, such as trigonometric functions and power between two real numbers, are also only supported for `float` (although raising `decimal` to integer exponents is supported). You can opt into potentially imprecise operations with the `float(decimal)` constructor, which casts the `decimal` number into a `float`, allowing for operations without precision guarantees. ## Displaying decimals To display a decimal, simply insert the value into the document. To only display a certain number of digits, round the decimal first. Localized formatting of decimals and other numbers is not yet supported, but planned for the future. You can convert decimals to strings using the `str` constructor. This way, you can post-process the displayed representation, e.g. to replace the period with a comma (as a stand-in for proper built-in localization to languages that use the comma). ## Precision and limits A `decimal` number has a limit of 28 to 29 significant base-10 digits. This includes the sum of digits before and after the decimal point. As such, numbers with more fractional digits have a smaller range. The maximum and minimum `decimal` numbers have a value of `79228162514264337593543950335` and `-79228162514264337593543950335` respectively. In contrast with `float`, this type does not support infinity or NaN, so overflowing or underflowing operations will raise an error. Typical operations between `decimal` numbers, such as addition, multiplication, and power to an integer, will be highly precise due to their fixed-point representation. Note, however, that multiplication and division may not preserve all digits in some edge cases: while they are considered precise, digits past the limits specified above are rounded off and lost, so some loss of precision beyond the maximum representable digits is possible. Note that this behavior can be observed not only when dividing, but also when multiplying by numbers between 0 and 1, as both operations can push a number's fractional digits beyond the limits described above, leading to rounding. When those two operations do not surpass the digit limits, they are fully precise. # decimal Converts a value to a `decimal`. It is recommended to use a string to construct the decimal number, or an integer (if desired). The string must contain a number in the format `"3.14159"` (or `"-3.141519"` for negative numbers). The fractional digits are fully preserved; if that's not possible due to the limit of significant digits (around 28 to 29) having been reached, an error is raised as the given decimal number wouldn't be representable. While this constructor can be used with floating-point numbers to cast them to `decimal`, doing so is discouraged as this cast is inherently imprecise. It is easy to accidentally perform this cast by writing `decimal(1.234)` (note the lack of double quotes), which is why Typst will emit a warning in that case. Please write `decimal("1.234")` instead for that particular case (initialization of a constant decimal). Also note that floats that are NaN or infinite cannot be cast to decimals and will raise an error. value The value that should be converted to a decimal. # dictionary A map from string keys to values. You can construct a dictionary by enclosing comma-separated `key: value` pairs in parentheses. The values do not have to be of the same type. Since empty parentheses already yield an empty array, you have to use the special `(:)` syntax to create an empty dictionary. A dictionary is conceptually similar to an array, but it is indexed by strings instead of integers. You can access and create dictionary entries with the `.at()` method. If you know the key statically, you can alternatively use field access notation (`.key`) to access the value. Dictionaries can be added with the `+` operator and joined together. To check whether a key is present in the dictionary, use the `in` keyword. You can iterate over the pairs in a dictionary using a for loop. This will iterate in the order the pairs were inserted / declared. ## Example #let dict = ( name: "Typst", born: 2019, ) #dict.name \ #(dict.launch = 20) #dict.len() \ #dict.keys() \ #dict.values() \ #dict.at("born") \ #dict.insert("city", "Berlin ") #("name" in dict) # dictionary Converts a value into a dictionary. Note that this function is only intended for conversion of a dictionary-like value to a dictionary, not for creation of a dictionary from individual pairs. Use the dictionary syntax `(key: value)` instead. value The value that should be converted to a dictionary. # len The number of pairs in the dictionary. # at Returns the value associated with the specified key in the dictionary. May be used on the left-hand side of an assignment if the key is already present in the dictionary. Returns the default value if the key is not part of the dictionary or fails with an error if no default value was specified. key The key at which to retrieve the item. default A default value to return if the key is not part of the dictionary. # insert Inserts a new pair into the dictionary. If the dictionary already contains this key, the value is updated. key The key of the pair that should be inserted. value The value of the pair that should be inserted. # remove Removes a pair from the dictionary by key and return the value. key The key of the pair to remove. default A default value to return if the key does not exist. # keys Returns the keys of the dictionary as an array in insertion order. # values Returns the values of the dictionary as an array in insertion order. # pairs Returns the keys and values of the dictionary as an array of pairs. Each pair is represented as an array of length two. # duration Represents a positive or negative span of time. # duration Creates a new duration. You can specify the duration using weeks, days, hours, minutes and seconds. You can also get a duration by subtracting two datetimes. seconds The number of seconds. minutes The number of minutes. hours The number of hours. days The number of days. weeks The number of weeks. # seconds The duration expressed in seconds. This function returns the total duration represented in seconds as a floating-point number rather than the second component of the duration. # minutes The duration expressed in minutes. This function returns the total duration represented in minutes as a floating-point number rather than the second component of the duration. # hours The duration expressed in hours. This function returns the total duration represented in hours as a floating-point number rather than the second component of the duration. # days The duration expressed in days. This function returns the total duration represented in days as a floating-point number rather than the second component of the duration. # weeks The duration expressed in weeks. This function returns the total duration represented in weeks as a floating-point number rather than the second component of the duration. # eval Evaluates a string as Typst code. This function should only be used as a last resort. ## Example #eval("1 + 1") \ #eval("(1, 2, 3, 4)").len() \ #eval("*Markup!*", mode: "markup") \ source A string of Typst code to evaluate. mode The syntactical mode in which the string is parsed. #eval("= Heading", mode: "markup") #eval("1_2^3", mode: "math") scope A scope of definitions that are made available. #eval("x + 1", scope: (x: 2)) \ #eval( "abc/xyz", mode: "math", scope: ( abc: $a + b + c$, xyz: $x + y + z$, ), ) # float A floating-point number. A limited-precision representation of a real number. Typst uses 64 bits to store floats. Wherever a float is expected, you can also pass an integer. You can convert a value to a float with this type's constructor. NaN and positive infinity are available as `float.nan` and `float.inf` respectively. ## Example #3.14 \ #1e4 \ #(10 / 4) # float Converts a value to a float. * Booleans are converted to `0.0` or `1.0`. * Integers are converted to the closest 64-bit float. For integers with absolute value less than `calc.pow(2, 53)`, this conversion is exact. * Ratios are divided by 100%. * Strings are parsed in base 10 to the closest 64-bit float. Exponential notation is supported. value The value that should be converted to a float. # is-nan Checks if a float is not a number. In IEEE 754, more than one bit pattern represents a NaN. This function returns `true` if the float is any of those bit patterns. # is-infinite Checks if a float is infinite. Floats can represent positive infinity and negative infinity. This function returns `true` if the float is an infinity. # signum Calculates the sign of a floating point number. * If the number is positive (including `+0.0`), returns `1.0`. * If the number is negative (including `-0.0`), returns `-1.0`. * If the number is NaN, returns `float.nan`. # from-bytes Interprets bytes as a float. bytes The bytes that should be converted to a float. Must have a length of either 4 or 8. The bytes are then interpreted in IEEE 754's binary32 (single-precision) or binary64 (double-precision) format depending on the length of the bytes. endian The endianness of the conversion. # to-bytes Converts a float to bytes. endian The endianness of the conversion. size The size of the resulting bytes. This must be either 4 or 8. The call will return the representation of this float in either IEEE 754's binary32 (single-precision) or binary64 (double-precision) format depending on the provided size. # function A mapping from argument values to a return value. You can call a function by writing a comma-separated list of function arguments enclosed in parentheses directly after the function name. Additionally, you can pass any number of trailing content blocks arguments to a function after the normal argument list. If the normal argument list would become empty, it can be omitted. Typst supports positional and named arguments. The former are identified by position and type, while the latter are written as `name: value`. Within math mode, function calls have special behaviour. See the math documentation for more details. ## Example // Call a function. #list([A], [B]) // Named arguments and trailing // content blocks. #enum(start: 2)[A][B] // Version without parentheses. #list[A][B] Functions are a fundamental building block of Typst. Typst provides functions for a variety of typesetting tasks. Moreover, the markup you write is backed by functions and all styling happens through functions. This reference lists all available functions and how you can use them. Please also refer to the documentation about set and show rules to learn about additional ways you can work with functions in Typst. ## Element functions Some functions are associated with elements like headings or tables. When called, these create an element of their respective kind. In contrast to normal functions, they can further be used in set rules, show rules, and selectors. ## Function scopes Functions can hold related definitions in their own scope, similar to a module. Examples of this are `assert.eq` or `list.item`. However, this feature is currently only available for built-in functions. ## Defining functions You can define your own function with a let binding that has a parameter list after the binding's name. The parameter list can contain mandatory positional parameters, named parameters with default values and argument sinks. The right-hand side of a function binding is the function body, which can be a block or any other expression. It defines the function's return value and can depend on the parameters. If the function body is a code block, the return value is the result of joining the values of each expression in the block. Within a function body, the `return` keyword can be used to exit early and optionally specify a return value. If no explicit return value is given, the body evaluates to the result of joining all expressions preceding the `return`. Functions that don't return any meaningful value return `none` instead. The return type of such functions is not explicitly specified in the documentation. (An example of this is `array.push`). #let alert(body, fill: red) = { set text(white) set align(center) rect( fill: fill, inset: 8pt, radius: 4pt, [*Warning:\ #body*], ) } #alert[ Danger is imminent! ] #alert(fill: blue)[ KEEP OFF TRACKS ] ## Importing functions Functions can be imported from one file (`module`) into another using `import`. For example, assume that we have defined the `alert` function from the previous example in a file called `foo.typ`. We can import it into another file by writing `import "foo.typ": alert`. ## Unnamed functions You can also created an unnamed function without creating a binding by specifying a parameter list followed by `=>` and the function body. If your function has just one parameter, the parentheses around the parameter list are optional. Unnamed functions are mainly useful for show rules, but also for settable properties that take functions like the page function's `footer` property. #show "once?": it => [#it #it] once? ## Note on function purity In Typst, all functions are pure. This means that for the same arguments, they always return the same result. They cannot "remember" things to produce another value when they are called a second time. The only exception are built-in methods like `array.push(value)`. These can modify the values they are called on. # with Returns a new function that has the given arguments pre-applied. arguments The arguments to apply to the function. # where Returns a selector that filters for elements belonging to this function whose fields have the values of the given arguments. fields The fields to filter for. # int A whole number. The number can be negative, zero, or positive. As Typst uses 64 bits to store integers, integers cannot be smaller than `-9223372036854775808` or larger than `9223372036854775807`. Integer literals are always positive, so a negative integer such as `-1` is semantically the negation `-` of the positive literal `1`. A positive integer greater than the maximum value and a negative integer less than or equal to the minimum value cannot be represented as an integer literal, and are instead parsed as a `float`. The minimum integer value can still be obtained through integer arithmetic. The number can also be specified as hexadecimal, octal, or binary by starting it with a zero followed by either `x`, `o`, or `b`. You can convert a value to an integer with this type's constructor. ## Example #(1 + 2) \ #(2 - 5) \ #(3 + 4 < 8) #0xff \ #0o10 \ #0b1001 # int Converts a value to an integer. Raises an error if there is an attempt to produce an integer larger than the maximum 64-bit signed integer or smaller than the minimum 64-bit signed integer. * Booleans are converted to `0` or `1`. * Floats and decimals are truncated to the next 64-bit integer. * Strings are parsed in base 10. value The value that should be converted to an integer. # signum Calculates the sign of an integer. * If the number is positive, returns `1`. * If the number is negative, returns `-1`. * If the number is zero, returns `0`. # bit-not Calculates the bitwise NOT of an integer. For the purposes of this function, the operand is treated as a signed integer of 64 bits. # bit-and Calculates the bitwise AND between two integers. For the purposes of this function, the operands are treated as signed integers of 64 bits. rhs The right-hand operand of the bitwise AND. # bit-or Calculates the bitwise OR between two integers. For the purposes of this function, the operands are treated as signed integers of 64 bits. rhs The right-hand operand of the bitwise OR. # bit-xor Calculates the bitwise XOR between two integers. For the purposes of this function, the operands are treated as signed integers of 64 bits. rhs The right-hand operand of the bitwise XOR. # bit-lshift Shifts the operand's bits to the left by the specified amount. For the purposes of this function, the operand is treated as a signed integer of 64 bits. An error will occur if the result is too large to fit in a 64-bit integer. shift The amount of bits to shift. Must not be negative. # bit-rshift Shifts the operand's bits to the right by the specified amount. Performs an arithmetic shift by default (extends the sign bit to the left, such that negative numbers stay negative), but that can be changed by the `logical` parameter. For the purposes of this function, the operand is treated as a signed integer of 64 bits. shift The amount of bits to shift. Must not be negative. Shifts larger than 63 are allowed and will cause the return value to saturate. For non-negative numbers, the return value saturates at `0`, while, for negative numbers, it saturates at `-1` if `logical` is set to `false`, or `0` if it is `true`. This behavior is consistent with just applying this operation multiple times. Therefore, the shift will always succeed. logical Toggles whether a logical (unsigned) right shift should be performed instead of arithmetic right shift. If this is `true`, negative operands will not preserve their sign bit, and bits which appear to the left after the shift will be `0`. This parameter has no effect on non-negative operands. # from-bytes Converts bytes to an integer. bytes The bytes that should be converted to an integer. Must be of length at most 8 so that the result fits into a 64-bit signed integer. endian The endianness of the conversion. signed Whether the bytes should be treated as a signed integer. If this is `true` and the most significant bit is set, the resulting number will negative. # to-bytes Converts an integer to bytes. endian The endianness of the conversion. size The size in bytes of the resulting bytes (must be at least zero). If the integer is too large to fit in the specified size, the conversion will truncate the remaining bytes based on the endianness. To keep the same resulting value, if the endianness is big-endian, the truncation will happen at the rightmost bytes. Otherwise, if the endianness is little-endian, the truncation will happen at the leftmost bytes. Be aware that if the integer is negative and the size is not enough to make the number fit, when passing the resulting bytes to `int.from-bytes`, the resulting number might be positive, as the most significant bit might not be set to 1. # label A label for an element. Inserting a label into content attaches it to the closest preceding element that is not a space. The preceding element must be in the same scope as the label, which means that `Hello #[