github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs/content/functions/math.md (about) 1 --- 2 title: math functions 3 menu: 4 main: 5 parent: functions 6 --- 7 8 A set of basic math functions to be able to perform simple arithmetic operations with `gomplate`. 9 10 ### Supported input 11 12 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. 13 14 In addition to regular base-10 numbers, integers can be 15 [specified](https://golang.org/ref/spec#Integer_literals) as octal (prefix with 16 `0`) or hexadecimal (prefix with `0x`). 17 18 Decimal/floating-point numbers can be [specified](https://golang.org/ref/spec#Floating-point_literals) 19 with optional exponents. 20 21 Some examples demonstrating this: 22 23 ```console 24 $ NUM=50 gomplate -i '{{ div (getenv "NUM") 10 }}' 25 5 26 $ gomplate -i '{{ add "0x2" "02" "2.0" "2e0" }}' 27 8 28 $ gomplate -i '{{ add 2.5 2.5 }}' 29 5.0 30 ``` 31 32 ## `math.Abs` 33 34 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`. 35 36 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 37 ### Usage 38 39 ``` 40 math.Abs num 41 ``` 42 43 ### Arguments 44 45 | name | description | 46 |------|-------------| 47 | `num` | _(required)_ The input number | 48 49 ### Examples 50 51 ```console 52 $ gomplate -i '{{ math.Abs -3.5 }} {{ math.Abs 3.5 }} {{ math.Abs -42 }}' 53 3.5 3.5 42 54 ``` 55 56 ## `math.Add` 57 58 **Alias:** `add` 59 60 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`. 61 62 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 63 ### Usage 64 65 ``` 66 math.Add n... 67 ``` 68 69 ### Arguments 70 71 | name | description | 72 |------|-------------| 73 | `n...` | _(required)_ The numbers to add together | 74 75 ### Examples 76 77 ```console 78 $ gomplate -i '{{ math.Add 1 2 3 4 }} {{ math.Add 1.5 2 3 }}' 79 10 6.5 80 ``` 81 82 ## `math.Ceil` 83 84 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). 85 86 **Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. 87 88 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 89 ### Usage 90 91 ``` 92 math.Ceil num 93 ``` 94 95 ### Arguments 96 97 | name | description | 98 |------|-------------| 99 | `num` | _(required)_ The input number. Will be converted to a `float64`, or `0` if not convertible | 100 101 ### Examples 102 103 ```console 104 $ gomplate -i '{{ range (coll.Slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}ceil {{ printf "%#v" . }} = {{ math.Ceil . }}{{"\n"}}{{ end }}' 105 ceil 5.1 = 6 106 ceil 42 = 42 107 ceil "3.14" = 4 108 ceil "0xFF" = 255 109 ceil "NaN" = NaN 110 ceil "Inf" = +Inf 111 ceil "-0" = 0 112 ``` 113 114 ## `math.Div` 115 116 **Alias:** `div` 117 118 Divide the first number by the second. Division by zero is disallowed. The result will be a `float64`. 119 120 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 121 ### Usage 122 123 ``` 124 math.Div a b 125 ``` 126 ``` 127 b | math.Div a 128 ``` 129 130 ### Arguments 131 132 | name | description | 133 |------|-------------| 134 | `a` | _(required)_ The divisor | 135 | `b` | _(required)_ The dividend | 136 137 ### Examples 138 139 ```console 140 $ gomplate -i '{{ math.Div 8 2 }} {{ math.Div 3 2 }}' 141 4 1.5 142 ``` 143 144 ## `math.Floor` 145 146 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). 147 148 **Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. 149 150 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 151 ### Usage 152 153 ``` 154 math.Floor num 155 ``` 156 157 ### Arguments 158 159 | name | description | 160 |------|-------------| 161 | `num` | _(required)_ The input number. Will be converted to a `float64`, or `0` if not convertable | 162 163 ### Examples 164 165 ```console 166 $ gomplate -i '{{ range (coll.Slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}floor {{ printf "%#v" . }} = {{ math.Floor . }}{{"\n"}}{{ end }}' 167 floor 5.1 = 4 168 floor 42 = 42 169 floor "3.14" = 3 170 floor "0xFF" = 255 171 floor "NaN" = NaN 172 floor "Inf" = +Inf 173 floor "-0" = 0 174 ``` 175 176 ## `math.IsFloat` 177 178 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). 179 180 **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`. 181 182 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 183 ### Usage 184 185 ``` 186 math.IsFloat num 187 ``` 188 189 ### Arguments 190 191 | name | description | 192 |------|-------------| 193 | `num` | _(required)_ The value to test | 194 195 ### Examples 196 197 ```console 198 $ gomplate -i '{{ range (coll.Slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsFloat .) }}{{.}} is a float{{"\n"}}{{ end }}{{end}}' 199 1 is a float 200 -1.0 is a float 201 5.1 is a float 202 3.14 is a float 203 NaN is a float 204 Inf is a float 205 ``` 206 207 ## `math.IsInt` 208 209 Returns whether or not the given number is an integer. 210 211 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 212 ### Usage 213 214 ``` 215 math.IsInt num 216 ``` 217 218 ### Arguments 219 220 | name | description | 221 |------|-------------| 222 | `num` | _(required)_ The value to test | 223 224 ### Examples 225 226 ```console 227 $ gomplate -i '{{ range (coll.Slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsInt .) }}{{.}} is an integer{{"\n"}}{{ end }}{{end}}' 228 42 is an integer 229 0xFF is an integer 230 -0 is an integer 231 ``` 232 233 ## `math.IsNum` 234 235 Returns whether the given input is a number. Useful for `if` conditions. 236 237 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 238 ### Usage 239 240 ``` 241 math.IsNum in 242 ``` 243 244 ### Arguments 245 246 | name | description | 247 |------|-------------| 248 | `in` | _(required)_ The value to test | 249 250 ### Examples 251 252 ```console 253 $ gomplate -i '{{ math.IsNum "foo" }} {{ math.IsNum 0xDeadBeef }}' 254 false true 255 ``` 256 257 ## `math.Max` 258 259 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. 260 261 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 262 ### Usage 263 264 ``` 265 math.Max nums... 266 ``` 267 268 ### Arguments 269 270 | name | description | 271 |------|-------------| 272 | `nums...` | _(required)_ One or more numbers to compare | 273 274 ### Examples 275 276 ```console 277 $ gomplate -i '{{ math.Max 0 8.0 4.5 "-1.5e-11" }}' 278 8 279 ``` 280 281 ## `math.Min` 282 283 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. 284 285 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 286 ### Usage 287 288 ``` 289 math.Min nums... 290 ``` 291 292 ### Arguments 293 294 | name | description | 295 |------|-------------| 296 | `nums...` | _(required)_ One or more numbers to compare | 297 298 ### Examples 299 300 ```console 301 $ gomplate -i '{{ math.Min 0 8 4.5 "-1.5e-11" }}' 302 -1.5e-11 303 ``` 304 305 ## `math.Mul` 306 307 **Alias:** `mul` 308 309 Multiply all given operators together. 310 311 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 312 ### Usage 313 314 ``` 315 math.Mul n... 316 ``` 317 318 ### Arguments 319 320 | name | description | 321 |------|-------------| 322 | `n...` | _(required)_ The numbers to multiply | 323 324 ### Examples 325 326 ```console 327 $ gomplate -i '{{ math.Mul 8 8 2 }}' 328 128 329 ``` 330 331 ## `math.Pow` 332 333 **Alias:** `pow` 334 335 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. 336 337 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 338 ### Usage 339 340 ``` 341 math.Pow b n 342 ``` 343 344 ### Arguments 345 346 | name | description | 347 |------|-------------| 348 | `b` | _(required)_ The base | 349 | `n` | _(required)_ The exponent | 350 351 ### Examples 352 353 ```console 354 $ gomplate -i '{{ math.Pow 10 2 }}' 355 100 356 $ gomplate -i '{{ math.Pow 2 32 }}' 357 4294967296 358 $ gomplate -i '{{ math.Pow 1.5 2 }}' 359 2.2 360 ``` 361 362 ## `math.Rem` 363 364 **Alias:** `rem` 365 366 Return the remainder from an integer division operation. 367 368 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 369 ### Usage 370 371 ``` 372 math.Rem a b 373 ``` 374 ``` 375 b | math.Rem a 376 ``` 377 378 ### Arguments 379 380 | name | description | 381 |------|-------------| 382 | `a` | _(required)_ The divisor | 383 | `b` | _(required)_ The dividend | 384 385 ### Examples 386 387 ```console 388 $ gomplate -i '{{ math.Rem 5 3 }}' 389 2 390 $ gomplate -i '{{ math.Rem -5 3 }}' 391 -2 392 ``` 393 394 ## `math.Round` 395 396 Returns the nearest integer, rounding half away from zero. 397 398 **Note:** the return value of this function is a `float64` so that the special-cases `NaN` and `Inf` can be returned appropriately. 399 400 _Added in gomplate [v2.6.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.6.0)_ 401 ### Usage 402 403 ``` 404 math.Round num 405 ``` 406 407 ### Arguments 408 409 | name | description | 410 |------|-------------| 411 | `num` | _(required)_ The input number. Will be converted to a `float64`, or `0` if not convertable | 412 413 ### Examples 414 415 ```console 416 $ gomplate -i '{{ range (coll.Slice -6.5 5.1 42.9 "3.5" 6.5) }}round {{ printf "%#v" . }} = {{ math.Round . }}{{"\n"}}{{ end }}' 417 round -6.5 = -7 418 round 5.1 = 5 419 round 42.9 = 43 420 round "3.5" = 4 421 round 6.5 = 7 422 ``` 423 424 ## `math.Seq` 425 426 **Alias:** `seq` 427 428 Return a sequence from `start` to `end`, in steps of `step`. Can handle counting 429 down as well as up, including with negative numbers. 430 431 Note that the sequence _may_ not end at `end`, if `end` is not divisible by `step`. 432 433 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 434 ### Usage 435 436 ``` 437 math.Seq [start] end [step] 438 ``` 439 440 ### Arguments 441 442 | name | description | 443 |------|-------------| 444 | `start` | _(optional)_ The first number in the sequence (defaults to `1`) | 445 | `end` | _(required)_ The last number in the sequence | 446 | `step` | _(optional)_ The amount to increment between each number (defaults to `1`) | 447 448 ### Examples 449 450 ```console 451 $ gomplate -i '{{ range (math.Seq 5) }}{{.}} {{end}}' 452 1 2 3 4 5 453 ``` 454 ```console 455 $ gomplate -i '{{ conv.Join (math.Seq 10 -3 2) ", " }}' 456 10, 8, 6, 4, 2, 0, -2 457 ``` 458 459 ## `math.Sub` 460 461 **Alias:** `sub` 462 463 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`. 464 465 _Added in gomplate [v2.2.0](https://github.com/hairyhenderson/gomplate/releases/tag/v2.2.0)_ 466 ### Usage 467 468 ``` 469 math.Sub a b 470 ``` 471 ``` 472 b | math.Sub a 473 ``` 474 475 ### Arguments 476 477 | name | description | 478 |------|-------------| 479 | `a` | _(required)_ The minuend (the number to subtract from) | 480 | `b` | _(required)_ The subtrahend (the number being subtracted) | 481 482 ### Examples 483 484 ```console 485 $ gomplate -i '{{ math.Sub 3 1 }}' 486 2 487 ```