> For the complete documentation index, see [llms.txt](https://docs.dbnetsoft.com/dbnetsoft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/functions.md).

# Functions

FinalScore's own functions and every general function for text, numbers, times, dates and lists.

Every expression can call

* **FinalScore's functions** - `iif`, `ifEmpty`, `formatTime`, `countWhere`, ...;
* **the general functions** of the dbnetsoft scripting library: a few at the top level (`toTimeSpan`, `format`, ...) and groups such as `string.*`, `math.*`, `array.*`, `timespan.*`. Each group is built on the matching group of the Scriban language and adds dbnetsoft's own functions to it - the tables below list both and mark where each comes from.

**Spelling:** names ignore case, and functions can also be written in PascalCase or snake\_case - `formatTime`, `FormatTime` and `format_time` are the same function, as are `string.padLeft` and `string.pad_left`. This documentation and the editor use camelCase.

A function is called with brackets or with a pipe - `x | f a` is `f(x, a)`:

```
formatTime(timeValue, 1)
timeValue | formatTime 1
lastName | string.upcase
```

## FinalScore functions

| Function                                 | What it does                                                                                                                              | Example                                        |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `iif(condition, whenTrue, whenFalse)`    | `whenTrue` when the condition is true, else `whenFalse` (empty when left out). `null`, `false`, `""`, `"false"`, `"0"` and `0` are false. | `iif(finished, time, status)`                  |
| `ifEmpty(value, fallback)`               | the fallback when the value is empty (`null` or `""`); `0` is kept                                                                        | `ifEmpty(team?.name, club)`                    |
| `formatTime(seconds, decimals = 2)`      | seconds as a run time, 0 - 4 decimals, cut off (not rounded)                                                                              | `formatTime(3723.456, 1)` → `1:02:03.4`        |
| `formatTimeOfDay(seconds, decimals = 4)` | seconds since midnight as a time of day; the next day with `+1d`                                                                          | `formatTimeOfDay(45296.12, 2)` → `12:34:56.12` |
| `ordinal(value)`                         | "3."; empty for an empty value                                                                                                            | `ordinal(ranks.class)`                         |

{% hint style="info" %}
The earlier names `nz` (now `ifEmpty`), `fmtTime` (now `formatTime`) and `fmtTod` (now `formatTimeOfDay`) still work in existing lists, rankings and formulas; the editor only offers the new ones.
{% endhint %}

### Counting and adding up values

These take any number of values. A list among them counts with its items; empty values are left out.

| Function                                 | What it does                           | Example                                                                       |
| ---------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------- |
| `countTrue(v1, v2, ...)`                 | how many values are true               | `countTrue(heats.run1.rank == 1, heats.run2.rank == 1, heats.run3.rank == 1)` |
| `countOf(v1, v2, ...)`                   | how many values are not empty          | `countOf(1, "", null, 4)` → 2                                                 |
| `sumOf(v1, v2, ...)`                     | the numbers added up                   | `sumOf(results.run1?.timeValue, results.run2?.timeValue)`                     |
| `minOf(...)`, `maxOf(...)`, `avgOf(...)` | the smallest, the largest, the average | `minOf(results.run1?.timeValue, results.run2?.timeValue)`                     |

`sumOf`, `minOf`, `maxOf` and `avgOf` give an empty value when there is no number at all.

### Counting and adding up over a collection

These go through a collection - a round's runs (`rounds.final.runs`), the splits (`splits`), a list - and look at each item with a **condition** and a **value**, written as text in quotes. Inside the quotes you write the item's own fields (`rank`, `timeValue`, `status`, `finished`, `counted`, ...); `it` is the item itself.

| Function                                          | What it does                                                       | Example                                                             |
| ------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `countWhere(items, "condition")`                  | how many items the condition is true for (all without a condition) | `countWhere(rounds.final.runs, "rank == 1")` - runs won             |
| `sumWhere(items, "value", "condition")`           | the value of those items added up (the condition is optional)      | `sumWhere(rounds.q.runs, "timeValue", "status == 'OK'")`            |
| `minWhere(...)`, `maxWhere(...)`, `avgWhere(...)` | the smallest, the largest, the average value                       | `maxWhere(splits, "speedSincePreviousSplit")` - the fastest section |

The pipe works too: `rounds.final.runs | countWhere "rank == 1"`. Use single quotes for text inside the condition: `"status == 'OK'"`.

## Top level

From dbnetsoft.

| Function                             | What it does                                                                                                                                | Example                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `toTimeSpan(value)`                  | seconds or a text time as a time span; empty when it cannot be read                                                                         | `toTimeSpan(timeValue)`, `toTimeSpan("1:02:03.45")`     |
| `toSeconds(value)`                   | a time span, a date and time (its time of day), a text run time (`,` or `.` as decimal separator) or a number as seconds                    | `toSeconds("1:02:03,45")` → 3723.45                     |
| `toNumber(value)`                    | a value as a number (text in the server's language settings - for text prefer `string.toDouble`)                                            | `toNumber(laps)`                                        |
| `toDateTime(value)`                  | text as a date and time                                                                                                                     | `toDateTime("2026-10-17 10:00:00")`                     |
| `format(value, format, culture)`     | a time span or date in the [time format](#time-format); a number in a .NET number format - in the given culture (`"en-US"`) or the server's | `format(toTimeSpan(timeValue), "HH:mm:ss.f")`           |
| `formatRuntime(timeSpan, decimals)`  | a run time with 0 - 4 decimals                                                                                                              | `formatRuntime(toTimeSpan(65.43), 1)` → `1:05.4`        |
| `formatRaceResult(timeSpan, format)` | a run time in a format of `h`, `m`, `s` and one `k` per decimal                                                                             | `formatRaceResult(toTimeSpan(timeValue), "h:mm:ss.kk")` |
| `httpGet(url)`                       | calls a web address from the server and gives `.response`, `.statusCode`, `.isValid` - **not for lists**, it holds up the list              |                                                         |

## string

| Function                                                              | From      | What it does                                                                 | Example                                      |
| --------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------- | -------------------------------------------- |
| `string.append(text, with)`                                           | Scriban   | text added at the end                                                        |                                              |
| `string.prepend(text, by)`                                            | Scriban   | text added at the front                                                      | `bib \| string.prepend "#"`                  |
| `string.base64Encode(text)`, `string.base64Decode(text)`              | Scriban   | Base64                                                                       |                                              |
| `string.capitalize(text)`                                             | Scriban   | the first letter in capitals                                                 |                                              |
| `string.capitalizewords(text)`                                        | Scriban   | every word's first letter in capitals                                        |                                              |
| `string.contains(text, value)`                                        | Scriban   | true when the text holds the value                                           | `string.contains(club, "LC")`                |
| `string.downcase(text)`, `string.upcase(text)`                        | Scriban   | small letters / capitals                                                     | `lastName \| string.upcase`                  |
| `string.empty(text)`                                                  | Scriban   | true when empty (or null)                                                    |                                              |
| `string.whitespace(text)`                                             | Scriban   | true when empty or only spaces                                               |                                              |
| `string.startsWith(text, value)`, `string.endsWith(text, value)`      | Scriban   | true when the text starts / ends with the value                              | `string.startsWith(bib, "A")`                |
| `string.equalsIgnoreCase(text, value)`                                | Scriban   | equal, ignoring capitals                                                     |                                              |
| `string.escape(text)`                                                 | Scriban   | special characters escaped (`\n`, `\"`)                                      |                                              |
| `string.handleize(text)`                                              | Scriban   | a web-address-friendly form (`"Lauf 10 km"` → `lauf-10-km`)                  |                                              |
| `string.hmacSha1`, `hmacSha256`, `hmacSha512(text, key)`              | Scriban   | keyed hash                                                                   |                                              |
| `string.md5`, `sha1`, `sha256`, `sha512(text)`                        | Scriban   | hash                                                                         |                                              |
| `string.indexOf(text, search, startIndex, count, comparison)`         | Scriban   | where the search starts, -1 when it is not there                             |                                              |
| `string.literal(text)`                                                | Scriban   | the text as a quoted literal                                                 |                                              |
| `string.padLeft(text, width)`, `string.padRight(text, width)`         | Scriban   | filled up with spaces to the width                                           | `bib \| string.padLeft 4`                    |
| `string.pluralize(number, singular, plural)`                          | Scriban   | the singular or the plural                                                   | `string.pluralize(laps, "Lap", "Laps")`      |
| `string.remove(text, remove)`                                         | Scriban   | every occurrence removed                                                     |                                              |
| `string.removeFirst(text, remove)`, `string.removeLast(text, remove)` | Scriban   | the first / last occurrence removed                                          |                                              |
| `string.replace(text, match, replace)`                                | Scriban   | every occurrence replaced                                                    | `string.replace(club, "e.V.", "")`           |
| `string.replaceFirst(text, match, replace, fromEnd = false)`          | Scriban   | the first (or last) occurrence replaced                                      |                                              |
| `string.size(text)`                                                   | Scriban   | length                                                                       |                                              |
| `string.slice(text, start, length)`                                   | Scriban   | a part, from 0                                                               | `string.slice(lastName, 0, 3)`               |
| `string.slice1(text, start, length = 1)`                              | Scriban   | one character (or a part)                                                    | `firstName \| string.slice1 0` → the initial |
| `string.split(text, separator)`                                       | Scriban   | a list of parts                                                              |                                              |
| `string.strip(text)`, `string.lStrip`, `string.rStrip`                | Scriban   | spaces removed at both ends / the front / the end                            |                                              |
| `string.stripNewlines(text)`                                          | Scriban   | line breaks removed                                                          |                                              |
| `string.toInt`, `toLong`, `toFloat`, `toDouble(text)`                 | Scriban   | text as a number (`.` as decimal separator)                                  | `bib \| string.toInt`                        |
| `string.truncate(text, length, ellipsis = "...")`                     | Scriban   | shortened to the length (the ellipsis included)                              |                                              |
| `string.truncatewords(text, count, ellipsis = "...")`                 | Scriban   | shortened to a number of words                                               |                                              |
| `string.removeAccents(text)`                                          | dbnetsoft | letters without accents                                                      | `string.removeAccents("Müller")` → `Muller`  |
| `string.trimPad(text, length, alignment = 0)`                         | dbnetsoft | cut or filled with spaces to the length; alignment 0 left, 1 centre, 2 right | `string.trimPad(lastName, 12)`               |

## math

| Function                                                   | From      | What it does                                                                                                          | Example                                      |
| ---------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `math.abs(x)`                                              | Scriban   | without sign                                                                                                          |                                              |
| `math.ceil(x)`, `math.floor(x)`                            | Scriban   | up / down to a whole number                                                                                           |                                              |
| `math.round(x, decimals = 0)`                              | Scriban   | rounded (a 5 to the even digit: 2.5 → 2)                                                                              | `math.round(splits.km10.speedSinceStart, 1)` |
| `math.trim(x, decimals = 0)`                               | dbnetsoft | cut off after the decimals, never rounded                                                                             | `math.trim(3723.456, 1)` → 3723.4            |
| `math.format(x, format, culture)`                          | Scriban   | a number as text: `"0.0"`, `"0.00"`, `"N1"` (thousands separator); `.` as decimal separator unless a culture is given | `timeValue \| math.format "0.0"`             |
| `math.isNumber(x)`                                         | Scriban   | true for a number                                                                                                     |                                              |
| `math.plus`, `minus`, `times`, `dividedBy`, `modulo(x, y)` | Scriban   | + - × ÷ and remainder, for pipes (two whole numbers divide to a whole number)                                         | `laps \| math.times 400`                     |
| `math.random(min, max)`                                    | Scriban   | a random whole number                                                                                                 |                                              |
| `math.uuid`                                                | Scriban   | a new unique id                                                                                                       |                                              |

{% hint style="info" %}
Use `math.format` for numbers as text: it always writes `.` as the decimal separator. `format(number, ...)` and `toNumber(text)` follow the server's language settings.
{% endhint %}

## array

For lists such as `lapTimes`, `heat.runs`, `rounds.qf1.runs`, `members` or what `string.split` gives. An item is also read with `[n]`, counting from 0: `lapTimes[0]` is lap 1.

| Function                                                                                    | From      | What it does                                                                                              | Example                                    |
| ------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `array.size(list)`                                                                          | Scriban   | number of items (also `list.size`)                                                                        | `array.size(heat.runs)`                    |
| `array.count(list)`, `array.length(list)`                                                   | dbnetsoft | number of items                                                                                           |                                            |
| `array.first(list)`, `array.last(list)`                                                     | Scriban   | the first / last item                                                                                     | `lapTimes \| array.last`                   |
| `array.getAtIndex(list, index)`                                                             | dbnetsoft | the item at an index from 0; empty when there is none                                                     | `array.getAtIndex(lapTimes, 2)` - lap 3    |
| `array.getAtPosition(list, position)`                                                       | dbnetsoft | the item at a position from 1                                                                             | `array.getAtPosition(lapTimes, 3)` - lap 3 |
| `array.limit(list, n)`                                                                      | Scriban   | the first n items                                                                                         |                                            |
| `array.offset(list, n)`                                                                     | Scriban   | all items after the first n                                                                               |                                            |
| `array.take(list, index, count)`                                                            | dbnetsoft | count items from an index on                                                                              | `array.take(lapTimes, 1, 3)` - laps 2 to 4 |
| `array.join(list, separator)`                                                               | Scriban   | the items as one text                                                                                     | `lapTimes \| array.join " / "`             |
| `array.map(list, "member")`                                                                 | Scriban   | one member of each item                                                                                   | `heat.runs \| array.map "resultOrState"`   |
| `array.sort(list, "member")`                                                                | Scriban   | sorted, by a member when given                                                                            | `array.sort(members, "time")`              |
| `array.reverse(list)`                                                                       | Scriban   | the other way round                                                                                       |                                            |
| `array.uniq(list)`                                                                          | Scriban   | without duplicates                                                                                        |                                            |
| `array.compact(list)`                                                                       | Scriban   | without empty items                                                                                       |                                            |
| `array.contains(list, item)`                                                                | Scriban   | true when it holds the item                                                                               |                                            |
| `array.concat(list1, list2)`, `array.addRange`                                              | Scriban   | both lists in one                                                                                         |                                            |
| `array.add(list, item)`, `array.insertAt(list, index, item)`, `array.removeAt(list, index)` | Scriban   | an item added / inserted / removed                                                                        |                                            |
| `array.cycle(list, group)`                                                                  | Scriban   | the next item each time it is called (in loops)                                                           |                                            |
| `array.each`, `array.filter`, `array.any`                                                   | Scriban   | a function applied to / tested on each item - for a condition on FinalScore items `countWhere` is simpler |                                            |

## timespan

A time span has `.totalSeconds`, `.totalMinutes`, `.totalHours`, `.hours`, `.minutes`, `.seconds`.

| Function                                                                              | From      | What it does                                       | Example                                      |
| ------------------------------------------------------------------------------------- | --------- | -------------------------------------------------- | -------------------------------------------- |
| `timespan.parse(value)`                                                               | dbnetsoft | seconds or text as a time span                     | `timespan.parse(65)`                         |
| `timespan.parseRuntime(text)`                                                         | dbnetsoft | reads a run time (`,` or `.` as decimal separator) | `timespan.parseRuntime("1:12,5")`            |
| `timespan.parseTimeOfDay(text)`                                                       | dbnetsoft | reads a time of day                                | `timespan.parseTimeOfDay("12,5")` → 12:05:00 |
| `timespan.format(timeSpan, format)`                                                   | dbnetsoft | in the [time format](#time-format)                 |                                              |
| `timespan.formatDbnetsoft(timeSpan, format)`                                          | dbnetsoft | the same                                           |                                              |
| `timespan.formatRuntime(timeSpan, decimals)`                                          | dbnetsoft | as `formatRuntime`                                 |                                              |
| `timespan.formatRaceResult(timeSpan, format)`                                         | dbnetsoft | as `formatRaceResult`                              |                                              |
| `timespan.add(a, b)`, `timespan.subtract(a, b)`                                       | dbnetsoft | added / subtracted; an empty side counts as 0      |                                              |
| `timespan.now`                                                                        | dbnetsoft | the server's time of day                           |                                              |
| `timespan.fromDays`, `fromHours`, `fromMinutes`, `fromSeconds`, `fromMilliseconds(n)` | Scriban   | a time span of n days, hours, ...                  | `timespan.fromMinutes(5)`                    |
| `timespan.zero`                                                                       | Scriban   | no time                                            |                                              |

### Time format

Used by `format`, `timespan.format` and `datetime.format`:

* `HH`, `MM`, `SS` (capitals) always show two digits; `hh`, `mm`, `ss` (small letters) are left out, with their separator, while they are zero at the front.
* `f` or `k` - one decimal each, cut off.
* `\` shows the next character as it is.
* `MM` means **minutes** - this format has no date parts.

For 65.43 seconds: `"hh:mm:ss.ff"` → `1:05.43`, `"HH:mm:ss.ff"` → `00:01:05.43`.

{% hint style="warning" %}
A format without hours drops them: 3723.456 s with `"mm:ss.ff"` gives `2:03.45`. Include `hh` for times that can be over an hour. For results `formatTime(seconds, decimals)` is usually simpler.
{% endhint %}

## datetime and date

Event times in FinalScore (`startTime`, `finishTod`, `splits.x.tod`) are already text; these are for the rare cases that need a real date.

| Function                                                                                                    | From                | What it does                                                         |
| ----------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------- |
| `datetime.now`, `date.now`                                                                                  | dbnetsoft / Scriban | the server's date and time                                           |
| `date.utcNow`, `datetime.utcNow`                                                                            | Scriban             | the same in UTC                                                      |
| `datetime.parse(value)`                                                                                     | dbnetsoft           | text as a date and time                                              |
| `date.parse(text, pattern, culture)`                                                                        | Scriban             | text as a date and time, optionally by a pattern                     |
| `date.parseToString(text, outputPattern, outputCulture, inputPattern, inputCulture)`                        | Scriban             | reads a date and writes it in another pattern                        |
| `datetime.add(dateTime, timeSpan)`                                                                          | dbnetsoft           | plus a time span (with a second date and time: plus its time of day) |
| `datetime.subtract(dateTime, timeSpan)`                                                                     | dbnetsoft           | minus a time span                                                    |
| `datetime.subtract(dateTime, dateTime)`                                                                     | dbnetsoft           | the time span between the two                                        |
| `date.addDays`, `addHours`, `addMinutes`, `addSeconds`, `addMilliseconds`, `addMonths`, `addYears(date, n)` | Scriban             | plus n days, hours, ... (also as `datetime.addDays`, ...)            |
| `datetime.format(value, format)`, `datetime.formatDateTime`, `datetime.formatDateTimeOffset`                | dbnetsoft           | the time of day in the [time format](#time-format)                   |
| `datetime.formatRaceResult(value, format)`                                                                  | dbnetsoft           | the time of day as `formatRaceResult`                                |

## object, html, regex

From Scriban.

| Function                                                                         | What it does                                | Example                                           |
| -------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------- |
| `object.default(value, fallback)`                                                | the fallback for null or `""`               | `club \| object.default "-"`                      |
| `object.format(value, format, culture)`                                          | a value as text in a .NET format            |                                                   |
| `object.typeof(value)`, `object.kind(value)`                                     | the kind of value (`string`, `number`, ...) |                                                   |
| `object.size(value)`                                                             | its size (text length, number of items)     |                                                   |
| `object.keys(value)`, `object.values(value)`, `object.hasKey`, `object.hasValue` | an object's names and values                | `object.keys(splits)`                             |
| `object.toJson(value)`, `object.fromJson(text)`                                  | to / from JSON                              |                                                   |
| `object.eval(text)`, `object.evalTemplate(text)`                                 | evaluates text as an expression / template  |                                                   |
| `html.escape(text)`                                                              | safe text for the HTML layout               | `lastName \| html.escape`                         |
| `html.strip(text)`                                                               | HTML tags removed                           |                                                   |
| `html.newlineToBr(text)`                                                         | line breaks as `<br />`                     |                                                   |
| `html.urlEncode(text)`, `html.urlEscape(text)`                                   | for web addresses                           |                                                   |
| `regex.match(text, pattern)`, `regex.matches(text, pattern)`                     | the first / every match                     |                                                   |
| `regex.replace(text, pattern, replace)`                                          | matches replaced                            | `regex.replace(bib, "\\D", "")` - only the digits |
| `regex.split(text, pattern)`                                                     | split at the matches                        |                                                   |
| `regex.escape(text)`, `regex.unescape(text)`                                     | special characters escaped / back           |                                                   |

## Scoreboard helpers

The groups `gaz`, `dline`, `mled`, `hl980`, `microtab` and `micrograph` (from dbnetsoft) build protocol text for scoreboards and displays - e.g. `gaz.createProtocol(address, bib, rank, time)`, `gaz.formatTime(value, precision)`, `mled.createProtocol(content, lineNr, brightness)`. They are not meant for lists.
