# 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`.