Struct Func

pub struct Func { /* private fields */ }

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 { #unnamed }

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.

Implementations

impl Func

pub fn name(&self) -> Option<&str>

The function’s name (e.g. min).

Returns None if this is an anonymous closure.

pub fn title(&self) -> Option<&'static str>

The function’s title case name, for use in documentation (e.g. Minimum).

Returns None if this is a closure.

pub fn docs(&self) -> Option<&'static str>

Documentation for the function (as Markdown).

pub fn contextual(&self) -> Option<bool>

Whether the function is known to be contextual.

pub fn params(&self) -> Option<&'static [ParamInfo]>

Get details about this function’s parameters if available.

pub fn param(&self, name: &str) -> Option<&'static ParamInfo>

Get the parameter info for a parameter with the given name if it exist.

pub fn returns(&self) -> Option<&'static CastInfo>

Get details about the function’s return type.

pub fn keywords(&self) -> &'static [&'static str]

Search keywords for the function.

pub fn scope(&self) -> Option<&'static Scope>

The function’s associated scope of sub-definition.

pub fn field(&self, field: &str) -> StrResult<&'static Value>

Get a field from this function’s scope, if possible.

pub fn element(&self) -> Option<Element>

Extract the element function, if it is one.

pub fn call<A: IntoArgs>( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, args: A, ) -> SourceResult<Value>

Call the function with the given context and arguments.

pub fn span(&self) -> Span

The function’s span.

pub fn spanned(self, span: Span) -> Self

Attach a span to this function if it doesn’t already have one.

impl Func

pub fn with(self, args: &mut Args) -> Func

Returns a new function that has the given arguments pre-applied.

pub fn where_(self, args: &mut Args) -> StrResult<Selector>

Returns a selector that filters for elements belonging to this function whose fields have the values of the given arguments.

#show heading.where(level: 2): set text(blue)
= Section
== Subsection
=== Sub-subsection

Trait Implementations

impl Clone for Func

fn clone(&self) -> Func

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Func

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<&'static NativeFuncData> for Func

fn from(data: &'static NativeFuncData) -> Self

Converts to this type from the input type.

impl From<Closure> for Func

fn from(closure: Closure) -> Self

Converts to this type from the input type.

impl From<Element> for Func

fn from(func: Element) -> Self

Converts to this type from the input type.

impl FromValue for Func

fn from_value(value: Value) -> HintedStrResult<Self>

Try to cast the value into an instance of Self.

impl Hash for Func

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for Func

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Func

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl NativeType for Func

const NAME: &'static str = "function"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq<&NativeFuncData> for Func

fn eq(&self, other: &&NativeFuncData) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Func

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reflect for Func

fn input() -> CastInfo

Describe what can be cast into this value.

fn output() -> CastInfo

Describe what this value can be cast into.

fn castable(value: &Value) -> bool

Whether the given value can be converted to T.

fn error(found: &Value) -> HintedString

Produce an error message for an unacceptable value type.

impl Repr for Func

fn repr(&self) -> EcoString

Return the debug representation of the value.