# The Standard Library

Corgi also comes with a standard library, providing a handful of useful mixins:

{% hint style="info" %}
**Implementation Note:** The version of the standard library is tied directly to the installed corgi compiler.

If the standard library gets updated, all you need to do is update your corgi compiler.
{% endhint %}

## fmt

### mixin [Grouped](https://github.com/mavolin/corgi/blob/develop/std/fmt/grouped.corgil#L14)

```pug
mixin Grouped(val any, size=4, sep=" ", trailRem=false, minSize=0)
```

Grouped formats the stringified version of `val` in groups of `size` runes.

Each group is separated by `sep`.

If `trailRem` is set, the remainder group, i.e. the group that has less than `size` elements, will be the last group. Otherwise, the first group will be that group. 

If `minSize` is set and `val` is shorter than `minSize`, Grouped will print it as is.

### mixin [Num](https://github.com/mavolin/corgi/blob/develop/std/fmt/grouped.corgil#L67)

```pug
mixin Num(val any, size=3, groupSep string = digitGroupSep, 
    decimalSep string = decimalSep, minSize=5, useWords=false)
```

Num is used for grouping numbers in groups of 3, if they are greater or equal to 10 000, or smaller or equal to -10 000.

Num handles three special cases that Grouped doesn't.

1. The sign isn't counted towards any group. Where Grouped would print `- 123 456`, Num will print `-123 456`.
2. Num correctly handles decimal points: `123456.7891` will be printed as `123 456.7891` and `12345.67891` will be printed as `12 345.67 890`. 
3. If `useWords` is set to `true`, Num will write out the number if it is in the range of 0-9. This means instead of printing `7`, Num will print `seven`. That range and those numbers can be changed using [SetNumWords](#mixin-setnumwords).

By default, Num will separate groups with spaces, however, you may change this using `groupSep` or by setting a global default using [SetDigitGroupSep](#mixin-setdigitgroupsep).

Num does not validate if val is actually a number. Instead, it operates on val's stringified version, scanning for `.` as a decimal separator. When printing, Num uses that same separator, unless `decimalSep` is set, or the global default was changed by calling [SetDecimalSep](#mixin-setdecimalsep).

### mixin [SetDigitGroupSep](https://github.com/mavolin/corgi/blob/develop/std/fmt/grouped.corgil#L117)

```pug
mixin SetDigitGroupSep(sep string)
```

SetDigitGroupSep sets the global default for the digit group separator used by [Num](#mixin-num).

SetDigitGroupSep may be called at any time, only affecting the calls to [Num](#mixin-num) made after updating the separator.

If SetDigitGroupSep's `_` block is set, the group separator will only be changed inside the block. Further calls to SetDigitGroupSep inside the block, even if without a `_` block, will also be reverted.

### mixin [SetDecimalSep](https://github.com/mavolin/corgi/blob/develop/std/fmt/grouped.corgil#L135)

```pug
mixin SetDecimalSep(sep string)
```

SetDecimalSep sets the global default for the decimal separator used by [Num](#mixin-num).

SetDecimalSep may be called at any time, only affecting the calls to [Num](#mixin-num) made after updating the separator.

If SetDecimalSep's `_` block is set, the decimal separator will only be changed inside the block. Further calls to SetDecimalSep inside the block, even if without a `_` block, will also be reverted.

### mixin [SetNumWords](https://github.com/mavolin/corgi/blob/develop/std/fmt/grouped.corgil#L157)

```pug
mixin SetNumWords(start=0, words []string)
```

SetNumWords sets the global default for the spelled-out numbers used by [Num](#mixin-num), if `useWords` is set to true.

SetNumWords may be called at any time, only affecting the calls to [Num](#mixin-num) made after updating the words.

If SetNumWords's `_` block is set, the spelled-out words will only be changed inside the block. Further calls to SetNumWords inside the block, even if without a `_` block, will also be reverted.

By default, `words[0]` will be assumed to be zero. This can be changed by setting the `start` param.

### mixin [List](https://github.com/mavolin/corgi/blob/develop/std/fmt/list.corgil#L30)

```pug
mixin List(val any, sep string = listSep, lastSep string = listLastSep)
```

List formats the stringified elements of `val`, which must be a slice, as a list.

If `val` is not a slice, List will return from the generated function with an error.

The list will be constructed as follows:

If the slice is empty or nil, nothing will be printed.

If the slice contains a single element, only that will be printed.

If the slice contains two elements they will both be printed, separated by `lastSep`. 

If the slice contains more than two elements, all but the last will be printed, separated by `sep`. Then, the last element will be printed, separated from the rest by `lastSep`.

You can change the defaults of `sep` and `lastSep` by calling [SetListSep](#mixin-setlistsep). 

By default sep is `,` , and lastSep is `, and` .

### mixin [SetListSep](https://github.com/mavolin/corgi/blob/develop/std/fmt/list.corgil#L59)

```pug
mixin SetListSep(sep="", lastSep="")
```

SetListSep updates the global default for the `sep` and `lastSep` values used by [List](#mixin-list). If you don't specify `sep` or `lastSep`, or assign them an empty value, they won't get updated.

SetListSep may be called at any time, only affecting the calls to [List](#mixin-list) made after updating the separator.

If SetListSeps's `_` block is set, the spelled-out words will only be changed inside the block. Further calls to SetNumWords inside the block, even if without a `_` block, will also be reverted.

### mixin [SetLocation](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L8)

```pug
mixin SetLocation(loc time.Location)
```

SetLocation updates the default location used for [Time](#mixin-time), [Date](#mixin-date), and [DateTime](#mixin-datetime).

### mixin [Time](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L21)

```pug
mixin Time(t time.Time, format string = timeFormat, in time.Location = location,
    asIs=false)
```

Time formats `t` according to `format`, which defaults to the global time format, changeable through [SetTimeFormat](#mixin-settimeformat).

By default, the time is printed in the global default location, which by default is `time.Local`, changeable trough [SetLocation](#mixin-setlocation).

If `asIs` is true, the time won't be converted to another timezone.

### mixin [SetTimeFormat](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L30)

```pug
mixin SetTimeFormat(format string)
```

SetTimeFormat sets the default global time format. 

If left unchanged, it will be `15:04`.

### mixin [Date](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L47)

```pug
mixin Date(t time.Time, format string = dateFormat, in time.Location = location,
asIs=true)
```

Date formats `t` according to format, which defaults to the global time format, changeable through [SetDateFormat](#mixin-setdateformat).

Unlike [Time](#mixin-time) and [DateTime](#mixin-datetime), the date will be printed in the timezone that `t` is already in. 

This can be changed by setting `asIs` to true, after which, the date is printed in the global default location, which by default is `time.Local`, changeable trough [SetLocation](#mixin-setlocation). This is usually only desired if `t` is a datetime and you only want to print the date.

### mixin [SetDateFormat](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L47)

```pug
mixin SetDateFormat(format string)
```

SetDateFormat sets the default global date format. 

If left unchanged, it will be `2006-01-02`.

### mixin [DateTime](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L69)

```pug
mixin DateTime(t time.Time, format string = dateTimeFormat,
    in time.Location = location, asIs=false)
```

DateTime formats `t` according to format, which defaults to the global time format, changeable through [SetDateTimeFormat](#mixin-setdatetimeformat).

By default, the datetime is printed in the global default location, which by default is `time.Local`, changeable trough [SetLocation](#mixin-setlocation).

If `asIs` is true, the time won't be converted to another timezone.

### mixin [SetDateTimeFormat](https://github.com/mavolin/corgi/blob/develop/std/fmt/time.corgil#L78)

```pug
mixin SetDateTimeFormat(format string)
```

SetDateTimeFormat sets the default global date time format. 

If left unchanged, it will be `2006-01-02 15:04`.

## html

### mixin [Breaked](https://github.com/mavolin/corgi/blob/develop/std/html/html.corgil#L31)

```pug
mixin Breaked(val any, maxAdjacent=-1)
```

Breaked replaces each newline in the stringified version of `val` with a `<br>` and prints it.

The optional `maxAdjacent` arg allows to limit the number of adjacent `<br>`s, to an arbitrary number. This means groups of more than `maxAdjacent` consecutive newlines are replaced with only `maxAdjacent` \* `<br>`.

Setting `maxAdjacent` to `0` effectively removes all newlines from `val`.&#x20;

A negative value is the default and causes all `<br>`s to be printed.

## strings

### mixin [Trunc](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L20)

```pug
mixin Trunc(val any, at int)
```

Trunc truncates the stringified version of val after the `at`-th rune.

If `at` is negative, Trunc will truncate the `at`-th rune starting from the last rune.

If $$|at|$$ is bigger than or equal to the rune length of `val`, then all of `val` will be printed.&#x20;

#### Examples&#x20;

```pug
+Trunc(val="abcdef", at=3) -> abc
+Trunc(val="abcdef", at=-3) -> def
```

### mixin [TruncWords](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L52)

```pug
mixin TruncWords(val any, max int)
```

TruncWords truncates the stringified version of `val` after `max` words.

A word is a sequence of one or more characters that is separated from another such sequence by one or more of `[ \t\r\n]`.

If `max` is negative, TruncWords will truncate from the end of `val` instead of from the beginning.

If $$|max| \ge \text{numWords}(val)$$, the stringified version of `val` will be printed as is.

### mixin [Abbrev](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L123)

```pug
mixin Abbrev(val any, at int, replacement="…")
```

Abbrev truncates the stringified version of `val` according to the rules of [Trunc](#mixin-trunc) and then appends `replacement`, if it truncated anything.

If `at` is negative, Abbrev prepends `replacement` instead of appending it.

By default, `replacement` is `U+2026` Horizontal Ellipsis.

### mixin [AbbrevWords](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L146)

```pug
mixin AbbrevWords(val any, max int, replacement="…")
```

AbbrevWords is the [TruncWords](#mixin-truncwords) version of [Abbrev](#mixin-abbrev).

### mixin [Initials](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L226)

```pug
mixin Initials(val any, max=0, upper=false, lower=false)
```

Initials prints the first letter of each word in the stringified version of `val`.

A word is a sequence of one or more characters that is separated from another such sequence by one or more of `[ \t\r\n]`.

If `max` is set to a number higher than `0`, Initials will print at most `max` initials.

If `upper` is set to `true`, the initials will be uppercased before printing.

Similarly, if `lower` is set to `true`, the initials will be lowercase.

If both are `false`, the initials will be printed as is, and if both are `true`, `upper` takes precedence.

### mixin [Wrap](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L254)

```pug
mixin Wrap(val any, after int, with __corgi_std_woof.HTMLBody = "<br>")
```

Wrap wraps the stringified version of `val` by printing `with` unescaped every `after` runes.

### mixin [Nbsp](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L268)

```pug
mixin Nbsp(val any)
```

Nbsp replaces all spaces in the stringified version of `val` with non-breaking spaces.

### mixin [RandText](https://github.com/mavolin/corgi/blob/develop/std/strings/strings.corgil#L287)

```pug
mixin RandText(charset="a-zA-Z", length int)
```

RandText produces a string of `length` runes generated from the passed `charset`.&#x20;

The `charset` may consist of character ranges such as `a-z`, or literal characters.

If charset is set to an empty or invalid string, RandText returns with an error from the generated function.&#x20;

If `length` is negative or zero, RandText prints nothing. The generated text is cryptographically secure, utilizing `crypto/rand`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mavolin.gitbook.io/corgi/learning-corgi/the-standard-library.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.