# Built-in functions¶

## Logical¶

### and(x, y, …)¶

Perform logical “and” between given boolean values, i.e. return `true` if all arguments are equivalent to `true` (see `Value` type for details about conversion to boolean).

Cottle template
```{and(2 < 3, 5 > 1)}
```
Rendering output
```true
```

Note

This function is equivalent to operator `&&`.

### cmp(x, y)¶

Compare `x` against `y`, and return -1 if `x` is lower than `y`, 0 if they’re equal, or 1 otherwise. When used on numeric values, the `cmp` function uses numerical order. When used on strings, it uses alphabetical order. When used on maps, it first performs numerical comparison on their length then compares keys and values two by two. Two values of different types are always different, but the order between them is undefined.

Cottle template
```{cmp("abc", "bcd")}
{cmp(9, 6)}
{cmp([2, 4], [2, 4])}
```
Rendering output
```-1
1
0
```

### default(primary, fallback)¶

Return `primary` if `primary` is equivalent to `true` (see `Value` type for details about conversion to boolean) or `fallback` otherwise.

Cottle template
```{set x to 3}
{default(x, "invisible")}
{default(y, "visible")}
```
Rendering output
```3
visible
```

### defined(x)¶

Check whether value `x` is defined by checking it has a non-void type.

This is different than checking whether a value is equivalent to `true` (see `Value` type for details about conversion to boolean), for example integer `0` is equivalent to `false` when used as a boolean expression but `defined(0)` is `true`. This function is mostly useful for testing whether a variable has been assigned a value or not.

Cottle template
```{dump defined(undefined)}
{set a to 0}
{dump defined(a)}
```
Rendering output
```<false>
<true>
```

### eq(x, y, …)¶

Return `true` if all arguments are equal or `false` otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
```{eq(7, 7)}
{eq(1, 4)}
{eq("test", "test")}
{eq(1 = 1, 2 = 2, 3 = 3)}
```
Rendering output
```true
false
true
true
```

Note

This function is equivalent to operator `=` when used with 2 arguments.

### ge(x, y)¶

Return `true` if `x` has a value greater than or equal to `y` or `false` otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
```{ge(7, 3)}
{ge(2, 2)}
{ge("abc", "abx")}
```
Rendering output
```true
true
false
```

Note

This function is equivalent to operator `>=`.

### gt(x, y)¶

Return `true` if `x` has a value greater than `y` or `false` otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
```{gt(7, 3)}
{gt(2, 2)}
{gt("abc", "abx")}
```
Rendering output
```true
false
false
```

Note

This function is equivalent to operator `>`.

### has(map, key)¶

Return `true` if given map has a value associated to given key or `false` otherwise.

Cottle template
```{has(["name": "Paul", "age": 37, "sex": "M"], "age")}
```
Rendering output
```true
```

Note

Result of this function is close to but not strictly equivalent to `defined(map[key])` as the former will return `true` if `map` contains a key `key` associated to an undefined value while the later will return `false`.

### le(x, y)¶

Return `true` if `x` has a value lower than or equal to `y` or `false` otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
```{le(3, 7)}
{le(2, 2)}
{le("abc", "abx")}
```
Rendering output
```true
true
true
```

Note

This function is equivalent to operator `<=`.

### lt(x, y)¶

Return `true` if `x` has a value lower than `y` or `false` otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
```{lt(3, 7)}
{lt(2, 2)}
{lt("abc", "abx")}
```
Rendering output
```true
false
true
```

Note

This function is equivalent to operator `<`.

### ne(x, y)¶

Return `true` if `x` equals `y` or `false` otherwise. It uses the same comparison algorithm than function cmp(x, y).

Cottle template
```{ne(7, 7)}
{ne(1, 4)}
{ne("test", "test")}
```
Rendering output
```false true false
```

Note

This function is equivalent to operator `!=` when used with 2 arguments.

### not(x)¶

Perform logical “not” on given boolean value, i.e return `false` if value was equivalent to `true` (see `Value` type for details about conversion to boolean) or `false` otherwise.

Cottle template
```{not(1 = 2)}
```
Rendering output
```true
```

Note

This function is equivalent to operator `!`.

### or(x, y, …)¶

Perform logical “or” between given boolean values, i.e. return `true` if at least one argument is equivalent to `true` (see `Value` type for details about conversion to boolean).

Cottle template
```{or(2 = 3, 5 > 1)}
```
Rendering output
```true
```

Note

This function is equivalent to operator `||`.

### xor(x, y, …)¶

Perform logical “xor” between given boolean values, i.e. return `true` if exactly one argument is `true` and all the others are `false`.

Cottle template
```{xor(2 < 3, 1 = 2)}
```
Rendering output
```true
```

### when(condition[, truthy[, falsy]])¶

Return `truthy` if `condition` is equivalent to `true` (see `Value` type for details about conversion to boolean) or `falsy` otherwise (or an undefined value if `falsy` is missing). This function is intended to act as the ternary operator you can find in some programming languages.

Cottle template
```{set x to 3}
{set y to 0}
{when(x, "x is true", "x is false")}
{when(y, "y is true", "y is false")}
```
Rendering output
```x is true
y is false
```

## Mathematical¶

### abs(x)¶

Return the absolute value of given numeric value `x`.

Cottle template
```{abs(-3)}
{abs(5)}
```
Rendering output
```3
5
```

Return the sum of two numeric values.

Cottle template
```{add(3, 7)}
```
Rendering output
```10
```

Note

This function is equivalent to operator `+`.

### ceil(x)¶

Returns the smallest integer greater than or equal to number value `x`.

Cottle template
```{ceil(2.7)}
```
Rendering output
```3
```

### cos(x)¶

Get the cosine of angle `x` in radians.

Cottle template
```{cos(-1.57)}
```
Rendering output
```0.000796326710733263
```

### div(x, y)¶

Return the numeric value of `x` divided by the numeric value of `y`, or an undefined value if `y` was equal to zero.

Cottle template
```{div(5, 2)}
```
Rendering output
```2.5
```

Note

This function is equivalent to operator `/`.

### floor(x)¶

Returns the largest integer less than or equal to number value `x`.

Cottle template
```{floor(2.7)}
```
Rendering output
```2
```

### max(x[, y[, z, …]])¶

Return the highest numeric value among given ones.

Cottle template
```{max(7, 5)}
{max(6, 8, 5, 7, 1, 2)}
```
Rendering output
```7
8
```

Note

Combine with function call(func, map) if you want to get the highest numeric value from an array.

### min(x[, y[, z, …]])¶

Return the lowest numeric value among given ones.

Cottle template
```{min(9, 3)}
{min(6, 8, 5, 7, 1, 2)}
```
Rendering output
```3
1
```

Note

Combine with function call(func, map) if you want to get the lowest numeric value from an array.

### mod(x, y)¶

Return the value of `x` modulo `y`, or an undefined value if `y` was equal to zero.

Cottle template
```{mod(7, 3)}
```
Rendering output
```1
```

Note

This function is equivalent to operator `%`.

### mul(x, y)¶

Return the numeric value of `x` times `y`.

Cottle template
```{mul(3, 4)}
```
Rendering output
```12
```

Note

This function is equivalent to operator `*`.

### pow(x, y)¶

Get specified number `x` raised to the power `y`.

Cottle template
```{pow(2, 10)}
```
Rendering output
```1024
```

### rand([a[, b]])¶

Get a pseudo-random numeric value between 0 and 2.147.483.647 inclusive. If numeric `a` value is specified, return a pseudo-random numeric value between 0 and `a` exclusive. If both numeric values `a` and `b` are specified, return a pseudo-random numeric value between `a` inclusive and `b` exclusive.

Cottle template
```{rand()}
{rand(1, 7)}
```
Rendering output
```542180393
5
```

### round(x[, digits])¶

Rounds number value `x` to a specified number of fractional digits `digits`, or to the nearest integral value if `digits` is not specified.

Cottle template
```{round(1.57)}
{round(1.57, 1)}
```
Rendering output
```2
1.6
```

### sin(x)¶

Get the sine of angle `x` in radians.

Cottle template
```{sin(1.57)}
```
Rendering output
```0.999999682931835
```

### sub(x, y)¶

Return the numeric value of `x` minus `y`.

Cottle template
```{sub(3, 5)}
```
Rendering output
```-2
```

Note

This function is equivalent to operator `-`.

## Collection¶

### cat(a, b, …)¶

Concatenate all input maps or strings into a single one. Keys are not preserved when this function used on map values.

Cottle template
```{dump cat("Hello, ", "World!")}
{dump cat([1, 2], [3])}
```
Rendering output
```"Hello, World!"
[1, 2, 3]
```

Warning

All arguments must share the same type than first one, either map or string.

### cross(map1, map2, …)¶

Return a map containing all pairs from `map1` having a key that also exists in `map2` and all following maps. Output pair values will always be taken from `map1`.

Cottle template
```{dump cross([1: "a", 2: "b", 3: "c"], [1: "x", 3: "y"])}
```
Rendering output
```[1: "a", 3: "c"]
```

### except(map1, map2, …)¶

Return a map containing all pairs from `map1` having a key that does not exist in `map2` and any of following maps. This function can also be used to remove a single pair from a map (if you are sure that it’s key is not used by any other pair, otherwise all pairs using that key would be removed also).

Cottle template
```{dump except([1: "a", 2: "b", 3: "c"], [2: "x", 4: "y"])}
```
Rendering output
```[1: "a", 3: "c"]
```

### find(subject, search[, start])¶

Find index of given `search` value in a map or sub-string in a string. Returns 0-based index of match if found or -1 otherwise. Search starts at index 0 unless `start` argument is specified.

Cottle template
```{find([89, 3, 572, 35, 7], 35)}
{find("hello, world!", "o", 5)}
{find("abc", "d")}
```
Rendering output
```3
8
-1
```

### filter(map, predicate[, a, b, …])¶

Return a map containing all pairs having a value that satisfies given predicate. Function `predicate` is invoked for each value from `map` with this value as its first argument, and pair is added to output map if predicate result is equivalent to `true` (see `Value` type for details about conversion to boolean).

Optional arguments can be specified when calling `filter` and will be passed to each invocation of `predicate` as second, third, forth argument and so on.

Cottle template
```{dump filter(["a", "", "b", "", "c"], len)}

{declare multiple_of(x, y) as:
{return x % y = 0}
}

{dump filter([1, 6, 7, 4, 9, 5, 0], multiple_of, 3)}
```
Rendering output
```["a", "b", "c"]
[6, 9, 0]
```

### flip(map)¶

Return a map were pairs are created by swapping each key and value pair from input map. Using resulting map with the `for` command will still iterate through each pair even if there was duplicates, but only the last occurrence of each duplicate can be accessed by key.

Cottle template
```{dump flip([1: "hello,", 2: "world!"])}
{dump flip(["a": 0, "b": 0])}
```
Rendering output
```["hello,": 1, "world!": 2]
["a", 0: "b"]
```

### join(map[, string])¶

Concatenate all values from given map pairs, using given string as a separator (or empty string if no separator is provided).

Cottle template
```{join(["2011", "01", "01"], "/")}
```
Rendering output
```2011/01/01
```

### len(x)¶

Return number of elements in given value, which means the number of pairs for a map or the number of character for a string.

Cottle template
```{len("Hello!")}
{len([17, 22, 391, 44])}
```
Rendering output
```6
4
```

### map(source, modifier[, a, b, …])¶

Return a map where values are built by applying given modifier to map values, while preserving keys. Function `modifier` is invoked for each value in `source` with this value as its first argument.

Optional arguments can be specified when calling `map` and will be passed to each invocation of `modifier` as second, third, forth argument and so on.

Cottle template
```{declare square(x) as:
{return x * x}
}

{dump map([1, 2, 3, 4], square)}
{dump map(["a": 1, "b": 7, "c": 4, "d": 5, "e": 3, "f": 2, "g": 6], lt, 4)}
```
Rendering output
```[1, 4, 9, 16]
["a": 1, "b": 0, "c": 0, "d": 0, "e": 1, "f": 1, "g": 0]
```

### range([start, ]stop[, step])¶

Generate a map where value of the i-th pair is start + step * i and last value is lower (or higher if `step` is a negative integer) than `stop`. Default base index is 0 if the `start` argument is omitted, and default value for `step` is 1 if `start` < `stop` or -1 otherwise.

Cottle template
```{for v in range(5): {v}}
{for v in range(2, 20, 3): {v}}
```
Rendering output
```0 1 2 3 4
2 5 8 11 14 17
```

### slice(subject, index[, count])¶

Extact sub-string from a string or elements from a map (keys are not preserved when used with maps). `count` items or characters are extracted from given 0-based numeric `index`. If no `count` argument is specified, all elements starting from given `index` are extracted.

Cottle template
```{for v in slice([68, 657, 54, 3, 12, 9], 3, 2): {v}}
{slice("abchello", 4)}
```
Rendering output
```3 12
hello
```

### sort(map[, callback])¶

Return a sorted copy of given map. First argument is the input map, and will be sorted using natural order (numerical or alphabetical, depending on value types) by default. You can specify a second argument as comparison delegate, that should accept two arguments and return -1 if the first should be placed “before” the second, 0 if they are equal, or 1 otherwise.

Cottle template
```{set shuffled to ["in", "order", "elements" "natural"]}
{for item in sort(shuffled):
{item}
}

{declare by_length(a, b) as:
{return cmp(len(b), len(a))}
}
{set shuffled to ["by their", "are sorted", "length", "these strings"]}
{for item in sort(shuffled, by_length):
{item}
}
```
Rendering output
```elements in natural order
these strings are sorted by their length
```

### union(map1, map2, …)¶

Return a map containing all pairs from input maps, but without duplicating any key. If a key exists more than once in all input maps, the last one will overwrite any previous pair using it.

Cottle template
```{dump union([1: "a", 2: "b"], [2: "x", 3: "c"], [4: "d"])}
```
Rendering output
```[1: "a", 2: "x", 3: "c", 4: "d"]
```

### zip(k, v)¶

Combine given maps of same length to create a new one. The n-th pair in result map will use the n-th value from `k` as its key and the n-th value from `v` as its value.

Cottle template
```{set k to ["key1", "key2", "key3"]}
{set v to ["value1", "value2", "value3"]}
{dump zip(k, v)}
```
Rendering output
```["key1": "value1", "key2": "value2", "key3": "value3"]
```

## Text¶

### char(codepoint)¶

Get a 1-character string from its Unicode code point integer value. See more about Unicode and code points on Wikipedia.

Cottle template
```{char(97)}
{char(916)}
```
Rendering output
```a
Δ
```

### format(value, format[, culture])¶

Convert any `value` to a string using given formatting from `format` string expression. Format should use syntax `str` or `t:str` where `t` indicates the type of the formatter to use and `str` is the associated .NET format string. Available formatter types are:

• `a`: automatic (default, used if `t` is omitted)
• `b`: System.Boolean
• `d` or `du`: System.DateTime (UTC)
• `dl`: System.DateTime (local)
• `i`: System.Int64
• `n`: System.Double
• `s`: System.String

Cottle template
```{format(1339936496, "d:yyyy-MM-dd HH:mm:ss")}
{format(0.165, "n:p2", "fr-FR")}
{format(1, "b:n2")}
```
Rendering output
```2012-06-17 12:34:56
16,50 %
True
```

Formatters use current culture, unless a culture name is specified in the `culture` argument. See documentation of CultureInfo.GetCultureInfo method to read more about culture names.

### lcase(string)¶

Return a lowercase conversion of given string value.

Cottle template
```{lcase("Mixed Case String"}
```
Rendering output
```mixed case string
```

### match(subject, pattern)¶

Match `subject` against given regular expression pattern. If match is successful, a map containing full match followed by captured groups is returned, otherwise result is an undefined value. See .NET Framework Regular Expressions for more information.

Cottle template
```{dump match("abc123", "^[a-z]+([0-9]+)\$")}
{dump match("xyz", "^[a-z]+([0-9]+)\$")}
```
Rendering output
```["abc123", "123"]
<void>
```

### ord(character)¶

Get the Unicode code point value of the first character of given string. See more about Unicode and code points on Wikipedia.

Cottle template
```{ord("a")}
{ord("Δ")}
```
Rendering output
```97
916
```

### split(subject, separator)¶

Split `subject` string according to given string separator `separator`. Result is an map where pair values contain split sub-strings.

Cottle template
```{dump split("2011/01/01", "/")}
```
Rendering output
```["2011", "01", "01"]
```

### token(subject, search, index[, replace])¶

Either return the n-th section of a string delimited by separator substring `search` if no `replace` argument is provided, or replace this section by `replace` else. This function can be used as a faster alternative to combined split/slice/join calls in some cases.

Cottle template
```{token("First.Second.Third", ".", 1)}
{token("A//B//C//D", "//", 2)}
{token("XX-??-ZZ", "-", 1, "YY")}
{token("1;2;3", ";", 3, "4")}
```
Rendering output
```Second
C
XX-YY-ZZ
1;2;3;4
```

### ucase(string)¶

Return an uppercase conversion of given string value.

Cottle template
```{ucase("Mixed Case String"}
```
Rendering output
```MIXED CASE STRING
```

## Type¶

### cast(value, type)¶

Get value converted to requested scalar type. Type must be a string value specifying desired type:

• `"b"` or `"boolean"`: convert to boolean value
• `"n"` or `"number"`: convert to numeric value
• `"s"` or `"string"`: convert to string value
Cottle template
```{dump cast("2", "n") = 2}
{dump ["value for key 0"][cast("0", "n")]}
{dump cast("some string", "b")}
```
Rendering output
```<true>
"value for key 0"
<true>
```

### type(value)¶

Retrieve type of given value as a string. Possible return values are `"boolean"`, `"function"`, `"map"`, `"number"`, `"string"` or `"void"`.

Cottle template
```{type(15)}
{type("test")}
```
Rendering output
```number
string
```

## Dynamic¶

### call(func, map)¶

Call function `func` with values from `map` as arguments (keys are ignored).

Cottle template
```{call(cat, ["Hello", ", ", "World", "!"])}
{call(max, [3, 8, 2, 7])}
```
Rendering output
```Hello, World!
8
```