Adding more math functions

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

1 files changed, 265 insertions, 39 deletions

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 - _b<sup>n</sup>_. 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 - _b<sup>n</sup>_. 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
+```