github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs-src/content/functions/math.yml (about) 1 ns: math 2 preamble: | 3 A set of basic math functions to be able to perform simple arithmetic operations with `gomplate`. 4 5 ### Supported input 6 7 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. 8 9 In addition to regular base-10 numbers, integers can be 10 [specified](https://golang.org/ref/spec#Integer_literals) as octal (prefix with 11 `0`) or hexadecimal (prefix with `0x`). 12 13 Decimal/floating-point numbers can be [specified](https://golang.org/ref/spec#Floating-point_literals) 14 with optional exponents. 15 16 Some examples demonstrating this: 17 18 ```console 19 $ NUM=50 gomplate -i '{{ div (getenv "NUM") 10 }}' 20 5 21 $ gomplate -i '{{ add "0x2" "02" "2.0" "2e0" }}' 22 8 23 $ gomplate -i '{{ add 2.5 2.5 }}' 24 5.0 25 ``` 26 funcs: 27 - name: math.Abs 28 description: | 29 Returns the absolute value of a given number. When the input is an integer, the result will be an `int64`, otherwise it will be a `float64`. 30 arguments: 31 - name: num 32 required: true 33 description: The input number 34 examples: 35 - | 36 $ gomplate -i '{{ math.Abs -3.5 }} {{ math.Abs 3.5 }} {{ math.Abs -42 }}' 37 3.5 3.5 42 38 - name: math.Add 39 alias: add 40 description: | 41 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`. 42 arguments: 43 - name: n... 44 required: true 45 description: The numbers to add together 46 examples: 47 - | 48 $ gomplate -i '{{ math.Add 1 2 3 4 }} {{ math.Add 1.5 2 3 }}' 49 10 6.5 50 - name: math.Ceil 51 description: | 52 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). 53 54 **Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. 55 arguments: 56 - name: num 57 required: true 58 description: The input number. Will be converted to a `float64`, or `0` if not convertible 59 examples: 60 - | 61 $ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}ceil {{ printf "%#v" . }} = {{ math.Ceil . }}{{"\n"}}{{ end }}' 62 ceil 5.1 = 6 63 ceil 42 = 42 64 ceil "3.14" = 4 65 ceil "0xFF" = 255 66 ceil "NaN" = NaN 67 ceil "Inf" = +Inf 68 ceil "-0" = 0 69 - name: math.Div 70 alias: div 71 description: | 72 Divide the first number by the second. Division by zero is disallowed. The result will be a `float64`. 73 pipeline: true 74 arguments: 75 - name: a 76 required: true 77 description: The divisor 78 - name: b 79 required: true 80 description: The dividend 81 examples: 82 - | 83 $ gomplate -i '{{ math.Div 8 2 }} {{ math.Div 3 2 }}' 84 4 1.5 85 - name: math.Floor 86 description: | 87 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). 88 89 **Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. 90 arguments: 91 - name: num 92 required: true 93 description: The input number. Will be converted to a `float64`, or `0` if not convertable 94 examples: 95 - | 96 $ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}floor {{ printf "%#v" . }} = {{ math.Floor . }}{{"\n"}}{{ end }}' 97 floor 5.1 = 4 98 floor 42 = 42 99 floor "3.14" = 3 100 floor "0xFF" = 255 101 floor "NaN" = NaN 102 floor "Inf" = +Inf 103 floor "-0" = 0 104 - name: math.IsFloat 105 description: | 106 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). 107 108 **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`. 109 arguments: 110 - name: num 111 required: true 112 description: The value to test 113 examples: 114 - | 115 $ 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}}' 116 1 is a float 117 -1.0 is a float 118 5.1 is a float 119 3.14 is a float 120 NaN is a float 121 Inf is a float 122 - name: math.IsInt 123 description: | 124 Returns whether or not the given number is an integer. 125 arguments: 126 - name: num 127 required: true 128 description: The value to test 129 examples: 130 - | 131 $ 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}}' 132 42 is an integer 133 0xFF is an integer 134 -0 is an integer 135 - name: math.IsNum 136 description: | 137 Returns whether the given input is a number. Useful for `if` conditions. 138 arguments: 139 - name: in 140 required: true 141 description: The value to test 142 examples: 143 - | 144 $ gomplate -i '{{ math.IsNum "foo" }} {{ math.IsNum 0xDeadBeef }}' 145 false true 146 - name: math.Max 147 description: | 148 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. 149 arguments: 150 - name: nums... 151 required: true 152 description: One or more numbers to compare 153 examples: 154 - | 155 $ gomplate -i '{{ math.Max 0 8.0 4.5 "-1.5e-11" }}' 156 8 157 - name: math.Min 158 description: | 159 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. 160 arguments: 161 - name: nums... 162 required: true 163 description: One or more numbers to compare 164 examples: 165 - | 166 $ gomplate -i '{{ math.Min 0 8 4.5 "-1.5e-11" }}' 167 -1.5e-11 168 - name: math.Mul 169 alias: mul 170 description: | 171 Multiply all given operators together. 172 arguments: 173 - name: n... 174 required: true 175 description: The numbers to multiply 176 examples: 177 - | 178 $ gomplate -i '{{ math.Mul 8 8 2 }}' 179 128 180 - name: math.Pow 181 alias: pow 182 description: | 183 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. 184 arguments: 185 - name: b 186 required: true 187 description: The base 188 - name: 'n' 189 required: true 190 description: The exponent 191 examples: 192 - | 193 $ gomplate -i '{{ math.Pow 10 2 }}' 194 100 195 $ gomplate -i '{{ math.Pow 2 32 }}' 196 4294967296 197 $ gomplate -i '{{ math.Pow 1.5 2 }}' 198 2.2 199 - name: math.Rem 200 alias: rem 201 description: | 202 Return the remainder from an integer division operation. 203 pipeline: true 204 arguments: 205 - name: a 206 required: true 207 description: The divisor 208 - name: b 209 required: true 210 description: The dividend 211 examples: 212 - | 213 $ gomplate -i '{{ math.Rem 5 3 }}' 214 2 215 $ gomplate -i '{{ math.Rem -5 3 }}' 216 -2 217 - name: math.Round 218 description: | 219 Returns the nearest integer, rounding half away from zero. 220 221 **Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. 222 arguments: 223 - name: num 224 required: true 225 description: The input number. Will be converted to a `float64`, or `0` if not convertable 226 examples: 227 - | 228 $ gomplate -i '{{ range (slice -6.5 5.1 42.9 "3.5" 6.5) }}round {{ printf "%#v" . }} = {{ math.Round . }}{{"\n"}}{{ end }}' 229 round -6.5 = -7 230 round 5.1 = 5 231 round 42.9 = 43 232 round "3.5" = 4 233 round 6.5 = 7 234 - name: math.Seq 235 alias: seq 236 description: | 237 Return a sequence from `start` to `end`, in steps of `step`. Can handle counting 238 down as well as up, including with negative numbers. 239 240 Note that the sequence _may_ not end at `end`, if `end` is not divisible by `step`. 241 arguments: 242 - name: start 243 required: false 244 description: The first number in the sequence (defaults to `1`) 245 - name: end 246 required: true 247 description: The last number in the sequence 248 - name: step 249 required: false 250 description: The amount to increment between each number (defaults to `1`) 251 examples: 252 - | 253 $ gomplate -i '{{ range (math.Seq 5) }}{{.}} {{end}}' 254 1 2 3 4 5 255 - | 256 $ gomplate -i '{{ conv.Join (math.Seq 10 -3 2) ", " }}' 257 10, 8, 6, 4, 2, 0, -2 258 - name: math.Sub 259 alias: sub 260 description: | 261 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`. 262 pipeline: true 263 arguments: 264 - name: a 265 required: true 266 description: The minuend (the number to subtract from) 267 - name: b 268 required: true 269 description: The subtrahend (the number being subtracted) 270 examples: 271 - | 272 $ gomplate -i '{{ math.Sub 3 1 }}' 273 2