finish stdlib documentation

xrstf · xrstf · commit bcec278deacb · 2023-12-02T20:59:12.000+01:00
diff --git a/.golangci.yml b/.golangci.yml
@@ -1,16 +1,5 @@
-# Copyright 2020 The Kubermatic Kubernetes Platform contributors.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+# SPDX-FileCopyrightText: 2023 Christoph Mewes
+# SPDX-License-Identifier: MIT
 
 run:
   modules-download-mode: readonly
diff --git a/.typos.toml b/.typos.toml
@@ -0,0 +1,4 @@
+# configuration for https://github.com/crate-ci/typos
+
+[default.extend-words]
+fo = "fo"
diff --git a/docs/coalescing.md b/docs/coalescing.md
@@ -129,9 +129,9 @@ Let's look closer at each type's conversion logic:
 * **string**: works as expected; floats have their trailing zeros trimmed (`3.12000` becomes
   `"3.12"`). `true` becomes `"true"` and `false` becomes `"false"`. `null` becomes an empty string.
 * **vector**: `null` turns into an empty vector and objects can only be converted to an empty vector
-  if they are empty, otherwise an error is retuned.
+  if they are empty, otherwise an error is returned.
 * **object**: `null` turns into an empty object and vectors can only be converted to an empty object
-  if they are empty, otherwise an error is retuned.
+  if they are empty, otherwise an error is returned.
 
 ## Conversion Functions
 
diff --git a/docs/functions/strings-has-prefix.md b/docs/functions/strings-has-prefix.md
@@ -0,0 +1,25 @@
+# has-prefix?
+
+`has-prefix?` checks whether a given string begins with another string.
+
+## Examples
+
+* `(has-prefix? "hello" "hell")` -> `true`
+* `(has-prefix? "hallo" "halloween")` -> `false`
+* `(has-prefix? "foo" "bar")` -> `false`
+
+## Forms
+
+### `(has-prefix? base prefix)`
+
+* `base` is an arbitrary expression.
+* `prefix` is an arbitrary expression.
+
+`has-prefix?` evaluates the first argument and coalesces it into a string. If
+successful, it evalates the prefix the same way. If both values are strings,
+the function returns true if `base` begins with `prefix`.
+
+## Context
+
+`has-prefix?` executes all expressions in their own contexts, so nothing is
+shared.
diff --git a/docs/functions/strings-has-suffix.md b/docs/functions/strings-has-suffix.md
@@ -0,0 +1,24 @@
+# has-suffix?
+
+`has-suffix?` checks whether a given string ends with another string.
+
+## Examples
+
+* `(has-suffix? "foobar" "bar")` -> `true`
+* `(has-suffix? "foobar" "f")` -> `false`
+
+## Forms
+
+### `(has-suffix? base suffix)`
+
+* `base` is an arbitrary expression.
+* `suffix` is an arbitrary expression.
+
+`has-suffix?` evaluates the first argument and coalesces it into a string. If
+successful, it evalates the suffix the same way. If both values are strings,
+the function returns true if `base` ends with `suffix`.
+
+## Context
+
+`has-suffix?` executes all expressions in their own contexts, so nothing is
+shared.
diff --git a/docs/functions/strings-to-lower.md b/docs/functions/strings-to-lower.md
@@ -0,0 +1,21 @@
+# to-lower
+
+`to-lower` removes a copy of a string with all uppercase characters replaced
+with their lowercase equivalent. This function uses Go's regular strings
+package and so this function should not be used where Unicode characters are
+involved, unexpected results might happen.
+
+See also [`to-upper`](strings-to-upper.md).
+
+## Examples
+
+* `(to-lower "FOO")` -> `"foo"`
+
+## Forms
+
+### `(to-lower string)`
+
+* `string` is an arbitrary expression.
+
+`to-lower` evaluates the first argument and coalesces the result into a string.
+When successful, the lowercased version of the string is returned.
diff --git a/docs/functions/strings-to-upper.md b/docs/functions/strings-to-upper.md
@@ -0,0 +1,21 @@
+# to-upper
+
+`to-upper` removes a copy of a string with all lowercase characters replaced
+with their uppercase equivalent. This function uses Go's regular strings
+package and so this function should not be used where Unicode characters are
+involved, unexpected results might happen.
+
+See also [`to-lower`](strings-to-lower.md).
+
+## Examples
+
+* `(to-upper "foo")` -> `"FOO"`
+
+## Forms
+
+### `(to-upper string)`
+
+* `string` is an arbitrary expression.
+
+`to-upper` evaluates the first argument and coalesces the result into a string.
+When successful, the uppercased version of the string is returned.
diff --git a/docs/functions/strings-trim-prefix.md b/docs/functions/strings-trim-prefix.md
@@ -0,0 +1,28 @@
+# trim-prefix?
+
+`trim-prefix?` checks whether a given string begins with another string and if
+it does, returns a copy of the string with the prefix removed. Note that this
+removal is done once, so removing the prefix `"o"` from `"oof"` will yield
+`"of"`.
+
+## Examples
+
+* `(trim-prefix? "11234" "1")` -> `"1234"`
+* `(trim-prefix? "11234" "x")` -> `"11234"`
+
+## Forms
+
+### `(trim-prefix? base prefix)`
+
+* `base` is an arbitrary expression.
+* `prefix` is an arbitrary expression.
+
+`trim-prefix?` evaluates the first argument and coalesces it into a string. If
+successful, it evalates the prefix the same way. If both values are strings,
+the function checks if the base string has the prefix, and if so removes it once
+and returns the resulting string.
+
+## Context
+
+`trim-prefix?` executes all expressions in their own contexts, so nothing is
+shared.
diff --git a/docs/functions/strings-trim-suffix.md b/docs/functions/strings-trim-suffix.md
@@ -0,0 +1,28 @@
+# trim-suffix?
+
+`trim-suffix?` checks whether a given string ends with another string and if
+it does, returns a copy of the string with the suffix removed. Note that this
+removal is done once, so removing the suffix `"o"` from `"foo"` will yield
+`"fo"`.
+
+## Examples
+
+* `(trim-suffix? "12344" "4")` -> `"1234"`
+* `(trim-suffix? "12344" "x")` -> `"12344"`
+
+## Forms
+
+### `(trim-suffix? base suffix)`
+
+* `base` is an arbitrary expression.
+* `suffix` is an arbitrary expression.
+
+`trim-suffix?` evaluates the first argument and coalesces it into a string. If
+successful, it evalates the suffix the same way. If both values are strings,
+the function checks if the base string has the suffix, and if so removes it once
+and returns the resulting string.
+
+## Context
+
+`trim-suffix?` executes all expressions in their own contexts, so nothing is
+shared.
diff --git a/docs/functions/strings-trim.md b/docs/functions/strings-trim.md
@@ -0,0 +1,19 @@
+# trim
+
+`trim` removes all whitepace from the beginning and end of a string. This
+includes linebreaks.
+
+## Examples
+
+* `(trim " hello\nworld ")` -> `"hello\nworld"`
+* `(trim "\n")` -> `""`
+
+## Forms
+
+### `(trim string)`
+
+* `string` is an arbitrary expression.
+
+`trim` evaluates the first argument and coalesces the result into a string. When
+successful, leading and trailing whitespace is removed from the string and then
+the resulting string is returned.
diff --git a/docs/functions/types-to-bool.md b/docs/functions/types-to-bool.md
@@ -0,0 +1,22 @@
+# to-bool
+
+`to-bool` converts the given value to a boolean. The function always uses
+[humane coalescing](../coalescing.md#humane-coalescer).
+
+## Examples
+
+* `(to-bool 0)` -> `false`
+* `(to-bool "0")` -> `false`
+* `(to-bool 1)` -> `true`
+* `(to-bool [])` -> `false`
+* `(to-bool [0])` -> `true`
+
+## Forms
+
+### `(to-bool value)`
+
+* `value` is an arbitrary expression.
+
+`to-bool` evaluates the given expression and then coalesces the result into a
+boolean value. See the documentation for the humane coalescer for the exact
+conversion rules.
diff --git a/docs/functions/types-to-float.md b/docs/functions/types-to-float.md
@@ -0,0 +1,21 @@
+# to-float
+
+`to-float` converts the given value to a floating point number. The function
+always uses [humane coalescing](../coalescing.md#humane-coalescer).
+
+## Examples
+
+* `(to-float 0)` -> `0.0`
+* `(to-float "0")` -> `0.0`
+* `(to-float 1)` -> `1.0`
+* `(to-float [])` -> error
+
+## Forms
+
+### `(to-float value)`
+
+* `value` is an arbitrary expression.
+
+`to-float` evaluates the given expression and then coalesces the result into a
+floating point value. See the documentation for the humane coalescer for the
+exact conversion rules.
diff --git a/docs/functions/types-to-int.md b/docs/functions/types-to-int.md
@@ -0,0 +1,21 @@
+# to-int
+
+`to-int` converts the given value to an integer number. The function always uses
+[humane coalescing](../coalescing.md#humane-coalescer).
+
+## Examples
+
+* `(to-int "0")` -> `0`
+* `(to-int 1.0)` -> `1`
+* `(to-int 1.2)` -> error, no lossless conversion possible
+* `(to-int [])` -> error
+
+## Forms
+
+### `(to-int value)`
+
+* `value` is an arbitrary expression.
+
+`to-int` evaluates the given expression and then coalesces the result into an
+integer value. See the documentation for the humane coalescer for the exact
+conversion rules.
diff --git a/docs/functions/types-to-string.md b/docs/functions/types-to-string.md
@@ -0,0 +1,23 @@
+# to-string
+
+`to-string` converts the given value to a string. The function always uses
+[humane coalescing](../coalescing.md#humane-coalescer).
+
+## Examples
+
+* `(to-string null)` -> `""`
+* `(to-string true)` -> `"true"`
+* `(to-string false)` -> `"false"`
+* `(to-string 0)` -> `"0"`
+* `(to-string 1.1)` -> `"1.1"`
+* `(to-string [])` -> error
+
+## Forms
+
+### `(to-string value)`
+
+* `value` is an arbitrary expression.
+
+`to-string` evaluates the given expression and then coalesces the result into a
+string value. See the documentation for the humane coalescer for the exact
+conversion rules.
diff --git a/docs/functions/types-type-of.md b/docs/functions/types-type-of.md
@@ -0,0 +1,22 @@
+# type-of
+
+`type-of` returns the type name of a given value.
+
+## Examples
+
+* `(type-of null)` -> `"null"`
+* `(type-of true)` -> `"bool"`
+* `(type-of 1)` -> `"number"`
+* `(type-of 1.2)` -> `"number"`
+* `(type-of "")` -> `"string"`
+* `(type-of [])` -> `"vector"`
+* `(type-of {})` -> `"object"`
+
+## Forms
+
+### `(type-of value)`
+
+* `value` is an arbitrary expression.
+
+`type-of` evaluates the given expression and then returns the datatype name of
+the resulting value.
