From 9e726a06e5f2cb587d04225b4be8934ba7fe217f Mon Sep 17 00:00:00 2001 From: Dave Henderson Date: Tue, 17 Apr 2018 16:03:07 -0400 Subject: Adding more math functions Signed-off-by: Dave Henderson --- docs/content/functions/math.md | 304 +++++++++++++++++++++++++++++++++++------ 1 file changed, 265 insertions(+), 39 deletions(-) (limited to 'docs') diff --git a/docs/content/functions/math.md b/docs/content/functions/math.md index 85e0f5f8..5a19c738 100644 --- a/docs/content/functions/math.md +++ b/docs/content/functions/math.md @@ -9,13 +9,7 @@ A set of basic math functions to be able to perform simple arithmetic operations ### Supported input -_**Note:** currently, `gomplate` supports only integer arithmetic. All functions -return 64-bit integers (`int64` type). Floating point support will be added in -later releases._ - -In general, any input will be converted to the correct input type by the various -functions in this package. For integer-based functions, floating-point inputs will -be truncated (not rounded). +In general, any input will be converted to the correct input type by the various functions in this package, and an appropriately-typed value will be returned type. Special cases are documented. In addition to regular base-10 numbers, integers can be [specified](https://golang.org/ref/spec#Integer_literals) as octal (prefix with @@ -31,15 +25,37 @@ $ NUM=50 gomplate -i '{{ div (getenv "NUM") 10 }}' 5 $ gomplate -i '{{ add "0x2" "02" "2.0" "2e0" }}' 8 -$ gomplate -i '{{ add 2.5 2.5 }}' # decimals are truncated! -4 +$ gomplate -i '{{ add 2.5 2.5 }}' +5.0 +``` + +## `math.Abs` + +Returns the absolute value of a given number. When the input is an integer, , the result will be an `int64`, otherwise it will be an `float64`. + +### Usage +```go +math.Abs num +``` + +### Arguments + +| name | description | +|--------|-------| +| `num` | _(required)_ The input number | + +### Examples + +```console +$ gomplate -i '{{ math.Abs -3.5 }} {{ math.Abs 3.5 }} {{ math.Abs -42 }}' +3.5 3.5 42 ``` ## `math.Add` **Alias:** `add` -Adds all given operators. +Adds all given operators. When one of the inputs is a floating-point number, the result will be a `float64`, otherwise it will be an `int64`. ### Usage ```go @@ -52,29 +68,209 @@ x | math.Add.Add n... ### Example ```console -$ gomplate -i '{{ math.Add 1 2 3 4 }} -10 +$ gomplate -i '{{ math.Add 1 2 3 4 }} {{ math.Add 1.5 2 3 }}' +10 6.5 ``` -## `math.Sub` +## `math.Ceil` -**Alias:** `sub` +Returns the least integer value greater than or equal to a given floating-point number. This wraps Go's [`math.Ceil`](https://golang.org/pkg/math/#Ceil). -Subtract the second from the first of the given operators. +**Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. ### Usage ```go -math.Sub a b +math.Ceil num ``` + +### Arguments + +| name | description | +|--------|-------| +| `num` | _(required)_ The input number. Will be converted to a `float64`, or `0` if not convertable | + +### Examples + +```console +$ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}ceil {{ printf "%#v" . }} = {{ math.Ceil . }}{{"\n"}}{{ end }}' +ceil 5.1 = 6 +ceil 42 = 42 +ceil "3.14" = 4 +ceil "0xFF" = 255 +ceil "NaN" = NaN +ceil "Inf" = +Inf +ceil "-0" = 0 +``` + +## `math.Div` + +**Alias:** `div` + +Divide the first number by the second. Division by zero is disallowed. The result will be a `float64`. + +### Usage ```go -b | math.Sub a +math.Div a b +``` +```go +b | math.Div a ``` ### Example ```console -$ gomplate -i '{{ math.Sub 3 1 }}' -2 +$ gomplate -i '{{ math.Div 8 2 }} {{ math.Div 3 2 }}' +4 1.5 +``` + +## `math.Floor` + +Returns the greatest integer value less than or equal to a given floating-point number. This wraps Go's [`math.Floor`](https://golang.org/pkg/math/#Floor). + +**Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. + +### Usage +```go +math.Floor num +``` + +### Arguments + +| name | description | +|--------|-------| +| `num` | _(required)_ The input number. Will be converted to a `float64`, or `0` if not convertable | + +### Examples + +```console +$ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}floor {{ printf "%#v" . }} = {{ math.Floor . }}{{"\n"}}{{ end }}' +floor 5.1 = 4 +floor 42 = 42 +floor "3.14" = 3 +floor "0xFF" = 255 +floor "NaN" = NaN +floor "Inf" = +Inf +floor "-0" = 0 +``` + +## `math.IsFloat` + +Returns whether or not the given number can be interpreted as a floating-point literal, as defined by the [Go language reference](https://golang.org/ref/spec#Floating-point_literals). + +**Note:** If a decimal point is part of the input number, it will be considered a floating-point number, even if the decimal is `0`. + +### Usage +```go +math.IsFloat num +``` + +### Arguments + +| name | description | +|--------|-------| +| `num` | _(required)_ The value to test | + +### Examples + +```console +$ gomplate -i '{{ range (slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsFloat .) }}{{.}} is a float{{"\n"}}{{ end }}{{end}}' +1 is a float +-1.0 is a float +5.1 is a float +3.14 is a float +NaN is a float +Inf is a float +``` + +## `math.IsInt` + +Returns whether or not the given number is an integer. +Returns whether or not the given number can be interpreted as a floating-point literal, as defined by the [Go language reference](https://golang.org/ref/spec#Integer_literals). + +### Usage +```go +math.IsInt num +``` + +### Arguments + +| name | description | +|--------|-------| +| `num` | _(required)_ The value to test | + +### Examples + +```console +$ gomplate -i '{{ range (slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsInt .) }}{{.}} is an integer{{"\n"}}{{ end }}{{end}}' +42 is an integer +0xFF is an integer +-0 is an integer +``` + +## `math.IsNum` + +Returns whether the given input is a number. Useful for `if` conditions. + +### Usage +```go +math.IsNum in +``` + +### Arguments + +| name | description | +|--------|-------| +| `in` | _(required)_ The value to test | + +### Examples + +```console +$ gomplate -i '{{ math.IsNum "foo" }} {{ math.IsNum 0xDeadBeef }}' +false true +``` + +## `math.Max` + +Returns the largest number provided. If any values are floating-point numbers, a `float64` is returned, otherwise an `int64` is returned. The same special-cases as Go's [`math.Max`](https://golang.org/pkg/math/#Max) are followed. + +### Usage +```go +math.Max nums... +``` + +### Arguments + +| name | description | +|--------|-------| +| `nums` | _(required)_ One or more numbers to compare | + +### Examples + +```console +$ gomplate -i '{{ math.Max 0 8.0 4.5 "-1.5e-11" }}' +8 +``` + +## `math.Min` + +Returns the smallest number provided. If any values are floating-point numbers, a `float64` is returned, otherwise an `int64` is returned. The same special-cases as Go's [`math.Min`](https://golang.org/pkg/math/#Min) are followed. + +### Usage +```go +math.Min nums... +``` + +### Arguments + +| name | description | +|--------|-------| +| `nums` | _(required)_ One or more numbers to compare | + +### Examples + +```console +$ gomplate -i '{{ math.Min 0 8 4.5 "-1.5e-11" }}' +-1.5e-11 ``` ## `math.Mul` @@ -98,25 +294,29 @@ $ gomplate -i '{{ math.Mul 8 8 2 }}' 128 ``` -## `math.Div` +## `math.Pow` -**Alias:** `div` +**Alias:** `pow` -Divide the first number by the second. Division by zero is disallowed. +Calculate an exponent - _bn_. This wraps Go's [`math.Pow`](https://golang.org/pkg/math/#Pow). If any values are floating-point numbers, a `float64` is returned, otherwise an `int64` is returned. ### Usage ```go -math.Div a b +math.Pow b n ``` ```go -b | math.Div a +n | math.Pow b ``` ### Example ```console -$ gomplate -i '{{ math.Div 8 2 }}' -4 +$ gomplate -i '{{ math.Pow 10 2 }}' +100 +$ gomplate -i '{{ math.Pow 2 32 }}' +4294967296 +$ gomplate -i '{{ math.Pow 1.5 2 }}' +2.2 ``` ## `math.Rem` @@ -142,27 +342,32 @@ $ gomplate -i '{{ math.Rem -5 3 }}' -2 ``` -## `math.Pow` +## `math.Round` -**Alias:** `pow` +Returns the nearest integer, rounding half away from zero. -Calculate an exponent - _bn_. This wraps Go's [`math.Pow`](https://golang.org/pkg/math/#Pow). +**Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. ### Usage ```go -math.Pow b n -``` -```go -n | math.Pow b +math.Round num ``` -### Example +### Arguments + +| name | description | +|--------|-------| +| `num` | _(required)_ The input number. Will be converted to a `float64`, or `0` if not convertable | + +### Examples ```console -$ gomplate -i '{{ math.Pow 10 2 }}' -100 -$ gomplate -i '{{ math.Pow 2 32 }}' -4294967296 +$ gomplate -i '{{ range (slice -6.5 5.1 42.9 "3.5" 6.5) }}round {{ printf "%#v" . }} = {{ math.Round . }}{{"\n"}}{{ end }}' +round -6.5 = -7 +round 5.1 = 5 +round 42.9 = 43 +round "3.5" = 4 +round 6.5 = 7 ``` ## `math.Seq` @@ -197,4 +402,25 @@ $ gomplate -i '{{ range (math.Seq 5) }}{{.}} {{end}}' ```console $ gomplate -i '{{ conv.Join (math.Seq 10 -3 2) ", " }}' 10, 8, 6, 4, 2, 0, -2 -``` \ No newline at end of file +``` + +## `math.Sub` + +**Alias:** `sub` + +Subtract the second from the first of the given operators. When one of the inputs is a floating-point number, the result will be a `float64`, otherwise it will be an `int64`. + +### Usage +```go +math.Sub a b +``` +```go +b | math.Sub a +``` + +### Example + +```console +$ gomplate -i '{{ math.Sub 3 1 }}' +2 +``` -- cgit v1.2.3