Types, values and operations

Base types

The following types and values are built-in Catala, relying on keywords of the language.

Booleans

The type boolean has only two values, true and false.

Boolean operations

Comparisons

Integer operations

The type integer represents mathematical integers, like 564,614 or -2. Note that you can optionally use the number separator , to make large integers more readable.

Decimals

The type decimal represents mathematical decimal numbers (or rationals), like 0.21 or -988,453.6842541. Note that you can optionally use the number separator , to make large decimals more readable. Decimal numbers are stored with infinite precision in Catala, but you can round them at will.

Decimal operations

Money

The type money represents an amount of money, positive or negative, in a currency unit (in the English version of Catala, we use the $ currency symbol), with a precision down to the cent and not below. Money values are noted like decimal values with maximum two fractional digits and the currency symbol, like $12.36 or -$871,84.1.

Money operations

Dates

The type date represents dates in the gregorian calendar. This type cannot represent invalid dates like 2025-02-31. Values of this type are noted following the ISO8601 notation (YYYY-MM-DD) enclosed by vertical bars, like |1930-09-11| or |2012-02-03|.

Semantic of date addition

Date addition in Catala is adding a duration to a date, yielding a new date in the past or in the future depending whether the duration is negative or positive. The value of this new date depends on the content of the duration:

• if the duration is a number of days, then Catala will simply add or subtract this amount of days to the day in the original date, wrapping to previous or next months if need be;
• if the duration is a number of years (say, x), then Catala will behave as if the duration was 12 * x months;
• if the duration is a number of months, Catala will simply add or subtract this amount of months to the month in the original date, wrapping to previous or next year if need be; but this operation might yield an invalid date (like Jan 31st + 1 month -> Feb 31st), which needs to be rounded.

There are three rounding modes in Catala, whose description is below:

By default, Catala is in the "No rounding" mode. To set the rounding mode to either up or down, for all the date operations inside a whole scope, use this syntax:

# Let us suppose you want to set the rounding more for date operations
# inside scope Foo declared elsewhere
scope Foo:
  date round decreasing # rounding down
  # or
  date round increasing # rounding up

Lastly, if the duration to add is comprised of multiple units (like 2 month + 21 day), then Catala will start by adding the component with the largest unit (here, month), then the component with the smallest unit (here, day).

Date operations

Durations

The type duration represents durations in terms of days, months and/or years, like 254 day, 4 month or 1 year. Durations can be negative and combine a number of days and months together, like 1 month + 15 day.

Duration operations

Casting base number types

Casting between base type is explicit; the syntax is <name of desired type> of <argument>.

User-declared types

User-declared types have to be declared before being used in the rest of the program. However, the declaration needs not be placed before the use in textual order.

Structures

Structures combine multiple pieces of data together into a single type. Each piece of data is a "field" of the structure. If you have a structure, you can access each of its fields, but you need all the fields to build the structure value.

Structure types are declared by the user, and each structure type has a name chosen by the user. Structure names begin by a capital letter and should follow the CamlCase naming convention. An example of structure declaration is:

declaration structure Individual:
  data birth_date content date
  data income content money
  data number_of_children content integer

The type of each field of the structure is mandatory and introduced by content. It is possible to nest structures (declaring the type of a field of a structure as another structure or enumeration), but not recursively.

Structure values are built with the following syntax:

Individual {
    -- birth_date: |1930-09-11|
    -- income: $100,000
    -- number_of_children: 2
}

To access the field of a structure, simply use the syntax <struct value>.<field name>, like individual.income.

Enumerations

Enumerations represent an alternative between different choices, each encapsulating a specific pattern of data. In this sense, enumerations are fully-fledged "sum types" like in functional programming languages, and more powerful than C-like enumerations that just list alternative codes a value can have. Each choice or alternative of the enumeration is called a "case" or a "variant".

Enumeration types are declared by the user, and each enumeration type has a name chosen by the user. Enumeration names begin by a capital letter and should follow the CamlCase naming convention. An example of enumeration declaration is:

declaration enumeration NoTaxCredit:
  -- NoTaxCredit
  -- TaxCreditForIndividual content Individual
  -- TaxCreditAfterDate content date

The type of each case of the enumeration is mandatory and introduced by content. It is possible to nest enumerations (declaring the type of a field of an enumeration as another enumeration or structure), but not recursively.

Enumeration values are built with the following syntax:

# First case
NoTaxCredit
# Second case
TaxCreditForIndividual content (Individual {
    -- birth_date: |1930-09-11|
    -- income: $100,000
    -- number_of_children: 2
})
# Third case
TaxCreditAfterDate content |2000-01-01|

To inspect enumeration values, see in which case you are and use the associated data, use pattern matching.

Lists

The type list of <another type> represents a fixed-size array of another type. For instance, list of integer represents a fixed-size array of integers.

You can build list values using the following syntax:

[1; 6; -4; 846645; 0]

List operations

Note that these operations support multiple lists being iterated upon, like (x + y) for (x, y) among (lst1, lst2), as long as they have the same length.

Tuples

The type (<type 1>, <type 2>) represents a pair of elements, the first being of type 1, the second being type 2. It is possible to extend the pair type into a triplet type, or even an n-uplet for an arbitrary number n by repeating elements after ,.

You can build tuple values with the following syntax:

(|2024-04-01|, $30, 1%) # This values has type (date, money, decimal)

You can acess the n-th element of a tuple, starting at 1, with the syntax <tuple>.n.

Functions

Function types represent function values, i.e values that require being called with some arguments to yield a result. Functions are first-class values because Catala is a functional programming language.

The general syntax for describing a function type is :

<type of result> depends on
  <name of argument 1> content <type of argument 1>,
  <name of argument 2> content <type of argument 2>,
  ...

For instance, money depends on income content money, number_of_children content integer can be the type of a tax-computing function.

However, unlike most programming language, it is not possible to directly build a function as a value; functions are created and passed around with other language mechanisms.