Struct Counter

pub struct Counter(/* private fields */);

Counts through pages, elements, and more.

With the counter function, you can access and modify counters for pages, headings, figures, and more. Moreover, you can define custom counters for other things you want to count.

Since counters change throughout the course of the document, their current value is contextual. It is recommended to read the chapter on [context] before continuing here.

Accessing a counter { #accessing }

To access the raw value of a counter, we can use the get function. This function returns an array: Counters can have multiple levels (in the case of headings for sections, subsections, and so on), and each item in the array corresponds to one level.

#set heading(numbering: "1.")

= Introduction
Raw value of heading counter is
#context counter(heading).get()

Displaying a counter { #displaying }

Often, we want to display the value of a counter in a more human-readable way. To do that, we can call the display function on the counter. This function retrieves the current counter value and formats it either with a provided or with an automatically inferred [numbering].

#set heading(numbering: "1.")

= Introduction
Some text here.

= Background
The current value is: #context {
  counter(heading).display()
}

Or in roman numerals: #context {
  counter(heading).display("I")
}

Modifying a counter { #modifying }

To modify a counter, you can use the step and update methods:

• The step method increases the value of the counter by one. Because counters can have multiple levels , it optionally takes a level argument. If given, the counter steps at the given depth.

• The update method allows you to arbitrarily modify the counter. In its basic form, you give it an integer (or an array for multiple levels). For more flexibility, you can instead also give it a function that receives the current value and returns a new value.

The heading counter is stepped before the heading is displayed, so Analysis gets the number seven even though the counter is at six after the second update.

#set heading(numbering: "1.")

= Introduction
#counter(heading).step()

= Background
#counter(heading).update(3)
#counter(heading).update(n => n * 2)

= Analysis
Let's skip 7.1.
#counter(heading).step(level: 2)

== Analysis
Still at #context {
  counter(heading).display()
}

Page counter

The page counter is special. It is automatically stepped at each pagebreak. But like other counters, you can also step it manually. For example, you could have Roman page numbers for your preface, then switch to Arabic page numbers for your main content and reset the page counter to one.

>>> #set page(
>>>   height: 100pt,
>>>   margin: (bottom: 24pt, rest: 16pt),
>>> )
#set page(numbering: "(i)")

= Preface
The preface is numbered with
roman numerals.

#set page(numbering: "1 / 1")
#counter(page).update(1)

= Main text
Here, the counter is reset to one.
We also display both the current
page and total number of pages in
Arabic numbers.

Custom counters

To define your own counter, call the counter function with a string as a key. This key identifies the counter globally.

#let mine = counter("mycounter")
#context mine.display() \
#mine.step()
#context mine.display() \
#mine.update(c => c * 3)
#context mine.display()

How to step

When you define and use a custom counter, in general, you should first step the counter and then display it. This way, the stepping behaviour of a counter can depend on the element it is stepped for. If you were writing a counter for, let’s say, theorems, your theorem’s definition would thus first include the counter step and only then display the counter and the theorem’s contents.

#let c = counter("theorem")
#let theorem(it) = block[
  #c.step()
  *Theorem #context c.display():*
  #it
]

#theorem[$1 = 1$]
#theorem[$2 < 3$]

The rationale behind this is best explained on the example of the heading counter: An update to the heading counter depends on the heading’s level. By stepping directly before the heading, we can correctly step from 1 to 1.1 when encountering a level 2 heading. If we were to step after the heading, we wouldn’t know what to step to.

Because counters should always be stepped before the elements they count, they always start at zero. This way, they are at one for the first display (which happens after the first step).

Time travel

Counters can travel through time! You can find out the final value of the counter before it is reached and even determine what the value was at any particular location in the document.

#let mine = counter("mycounter")

= Values
#context [
  Value here: #mine.get() \
  At intro: #mine.at(<intro>) \
  Final value: #mine.final()
]

#mine.update(n => n + 3)

= Introduction <intro>
#lorem(10)

#mine.step()
#mine.step()

Other kinds of state { #other-state }

The counter type is closely related to [state] type. Read its documentation for more details on state management in Typst and why it doesn’t just use normal variables for counters.

Implementations

impl Counter

pub fn new(key: CounterKey) -> Counter

Create a new counter identified by a key.

pub fn of(func: Element) -> Self

The counter for the given element.

pub fn both( &self, engine: &mut Engine<'_>, location: Location, ) -> SourceResult<CounterState>

Gets the current and final value of the state combined in one state.

pub fn at_loc( &self, engine: &mut Engine<'_>, location: Location, ) -> SourceResult<CounterState>

Gets the value of the counter at the given location. Always returns an array of integers, even if the counter has just one number.

pub fn display_at_loc( &self, engine: &mut Engine<'_>, loc: Location, styles: StyleChain<'_>, numbering: &Numbering, ) -> SourceResult<Content>

Displays the value of the counter at the given location.

pub fn select_any() -> Selector

Selects all state updates.

impl Counter

pub fn construct(key: CounterKey) -> Counter

Create a new counter identified by a key.

pub fn get( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, span: Span, ) -> SourceResult<CounterState>

Retrieves the value of the counter at the current location. Always returns an array of integers, even if the counter has just one number.

This is equivalent to {counter.at(here())}.

pub fn display( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, span: Span, numbering: Smart<Numbering>, both: bool, ) -> SourceResult<Value>

Displays the current value of the counter with a numbering and returns the formatted output.

pub fn at( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, span: Span, selector: LocatableSelector, ) -> SourceResult<CounterState>

Retrieves the value of the counter at the given location. Always returns an array of integers, even if the counter has just one number.

The selector must match exactly one element in the document. The most useful kinds of selectors for this are labels and locations.

pub fn final_( &self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, span: Span, ) -> SourceResult<CounterState>

Retrieves the value of the counter at the end of the document. Always returns an array of integers, even if the counter has just one number.

pub fn step(self, span: Span, level: NonZeroUsize) -> Content

Increases the value of the counter by one.

The update will be in effect at the position where the returned content is inserted into the document. If you don’t put the output into the document, nothing happens! This would be the case, for example, if you write {let _ = counter(page).step()}. Counter updates are always applied in layout order and in that case, Typst wouldn’t know when to step the counter.

pub fn update(self, span: Span, update: CounterUpdate) -> Content

Updates the value of the counter.

Just like with step, the update only occurs if you put the resulting content into the document.

Trait Implementations

impl Clone for Counter

fn clone(&self) -> Counter

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Counter

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

Formats the value using the given formatter.

impl FromValue for Counter

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

Try to cast the value into an instance of Self.

impl Hash for Counter

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 Counter

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Counter

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 Counter

const NAME: &'static str = "counter"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Counter

fn eq(&self, other: &Counter) -> 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 Counter

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 Counter

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl StructuralPartialEq for Counter