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, the $ currency symbol is used), 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, see the relevant reference section.

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 types 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

map each (x, y) among (lst1, lst2) to x + y

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 access the n-th element of a tuple, starting at 1, with the syntax <tuple>.n.

Optional values

The type optional of <type> can be used to hold a value of <type> that could be absent. For instance, optional of integer equivalent to the enumeration:

declaration enumeration OptionalInteger:
  -- Absent
  -- Present content integer

But the advantage of optional of integer over such an OptionalInteger is that doesn't need to be declared for each type that it is used with. Like an enumeration, values of type optional can be created using Present content <expr>, and used in the forms match <expr> with pattern and <expr> with pattern <constr>, e.g.

if foo with pattern Present of bar and bar > 3 then ...

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.

Polymorphic functions

A key feature of a programming language is its ability to avoid code duplication; the programmer should reuse as much code as possible through abstractions, such as functions and modules. Moreover, a standard feature of modern software engineering is polymorphism, i.e. writing pieces of code that can operate on multiple types of values at once, saving the programmer the necessity to duplicate the same code multiple times depending on the type of the arguments.

Concretely, when defining a function in Catala, you can give the anything type to an argument or the return type. This means that when you call the function, you can call it with an argument that has any of the possible types. We can call such an argument "generic", or say it has a "wildcard" type. For instance, it is convenient to be able to write the is_empty function once for lists of elements of any type:

declaration is_empty content boolean
  depends on argument content list of anything
  equals (number of argument = 0)

While generic arguments are powerful, they also have the downside that you cannot really "do" anything with a value that has anything type since you don't know what type it has. In particular, it is impossible to use the operators like +, *, -, /, <=, etc. since these operators only work for the basic types (integer, decimal, etc.) and not all the other types that can be defined by the user (structures, enumerations, etc.).

Sometimes, there are multiple generic arguments or return types in the same function but you want them to share the same generic type. For instance, if a function reverses the elements of a list, the type of the list elements will be the same in and out the function. The anything types can be named for this purpose, using anything of type <name>. For example:

declaration reverse content list of anything of type element_type
  depends on argument content list of anything of type element_type

If you don't name the anything type explicitly, it will be assumed that each anything is a fresh, independent anything from the other anythings. This may lead to complex error messages from the compiler, so remember to give the same name to anything types that you know have to be linked together.

Polymorphic function signatures can be really useful when defining interfaces to externally-implemented modules.