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