path: root/docs-src/content/functions/conv.yml

ns: conv
title: conversion functions
preamble: |
  These are a collection of functions that mostly help converting from one type
  to another - generally from a `string` to something else, and vice-versa.
funcs:
  - name: conv.Bool
    alias: bool
    released: v0.2.0
    description: |
      **Note:** See also [`conv.ToBool`](#convtobool) for a more flexible variant.

      Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input.
    pipeline: true
    arguments:
      - name: in
        required: true
        description: the input string
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{if bool (getenv "FOO")}}foo{{else}}bar{{end}}
        ```

        ```console
        $ gomplate < input.tmpl
        bar
        $ FOO=true gomplate < input.tmpl
        foo
        ```
  - name: conv.Default
    alias: default
    released: v2.5.0
    description: |
      Provides a default value given an empty input. Empty inputs are `0` for numeric
      types, `""` for strings, `false` for booleans, empty arrays/maps, and `nil`.

      Note that this will not provide a default for the case where the input is undefined
      (i.e. referencing things like `.foo` where there is no `foo` field of `.`), but
      [`coll.Has`](../coll/#collhas) can be used for that.
    pipeline: true
    arguments:
      - name: default
        required: true
        description: the default value
      - name: in
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}'
        foo bar
  - name: conv.Dict
    deprecated: Renamed to [`coll.Dict`](../coll/#colldict)
    alias: dict
    released: v3.0.0
    description: |
      Dict is a convenience function that creates a map with string keys.
      Provide arguments as key/value pairs. If an odd number of arguments
      is provided, the last is used as the key, and an empty string is
      set as the value.

      All keys are converted to strings.

      This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict)
      function, as used in [Helm templates](https://helm.sh/docs/chart_template_guide/functions_and_pipelines/).

      For creating more complex maps, see [`data.JSON`](../data/#datajson) or [`data.YAML`](../data/#datayaml).

      For creating arrays, see [`coll.Slice`](../coll/#collslice-_deprecated_).
    arguments:
      - name: in...
        required: true
        description: The key/value pairs
    examples:
      - |
        $ gomplate -i '{{ conv.Dict "name" "Frank" "age" 42 | data.ToYAML }}'
        age: 42
        name: Frank
        $ gomplate -i '{{ dict 1 2 3 | toJSON }}'
        {"1":2,"3":""}
      - |
        $ cat <<EOF| gomplate
        {{ define "T1" }}Hello {{ .thing }}!{{ end -}}
        {{ template "T1" (dict "thing" "world")}}
        {{ template "T1" (dict "thing" "everybody")}}
        EOF
        Hello world!
        Hello everybody!
  - name: conv.Slice
    deprecated: Renamed to [`coll.Slice`](../coll/#collslice-_deprecated_)
    alias: slice
    released: v0.3.0
    description: |
      Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables.
    pipeline: false
    arguments:
      - name: in...
        required: true
        description: the elements of the slice
    examples:
      - |
        $ gomplate -i '{{ range coll.Slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
        Hello, Bart
        Hello, Lisa
        Hello, Maggie
  - name: conv.Has
    deprecated: Renamed to [`coll.Has`](../coll/#collhas)
    alias: has
    released: v1.5.0
    description: |
      Reports whether a given object has a property with the given key, or whether a given array/slice contains the given value. Can be used with `if` to prevent the template from trying to access a non-existent property in an object.
    pipeline: false
    arguments:
      - name: in
        required: true
        description: The object or list to search
      - name: item
        required: true
        description: The item to search for
    examples:
      - |
        $ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
        there is a bar
      - |
        $ export DATA='{"foo": "bar"}'
        $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
        {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
        bar
      - |
        $ export DATA='{"baz": "qux"}'
        $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
        {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
        THERE IS NO FOO
  - name: conv.Join
    alias: join
    released: v0.4.0
    description: |
      Concatenates the elements of an array to create a string. The separator string `sep` is placed between elements in the resulting string.
    arguments:
      - name: in
        required: true
        description: the array or slice
      - name: sep
        required: true
        description: the separator
    examples:
      - |
        $ gomplate -i '{{ $a := coll.Slice 1 2 3 }}{{ join $a "-" }}'
        1-2-3
  - name: conv.URL
    alias: urlParse
    released: v2.0.0
    description: |
      Parses a string as a URL for later use. Equivalent to [url.Parse](https://pkg.go.dev/net/url/#Parse)

      Any of `url.URL`'s methods can be called on the result.
    arguments:
      - name: in
        required: true
        description: the URL string to parse
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ $u := conv.URL "https://example.com:443/foo/bar" }}
        The scheme is {{ $u.Scheme }}
        The host is {{ $u.Host }}
        The path is {{ $u.Path }}
        ```

        ```console
        $ gomplate < input.tmpl
        The scheme is https
        The host is example.com:443
        The path is /foo/bar
        ```
      - |
        _Call `Redacted` to hide the password in the output:_
        ```
        $ gomplate -i '{{ (conv.URL "https://user:supersecret@example.com").Redacted }}'
        https://user:xxxxx@example.com
        ```
  - name: conv.ParseInt
    released: v1.4.0
    description: |
      _**Note:**_ See [`conv.ToInt64`](#convtoint64) instead for a simpler and more flexible variant of this function.

      Parses a string as an int64. Equivalent to [strconv.ParseInt](https://pkg.go.dev/strconv/#ParseInt)
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ $val := conv.ParseInt (getenv "HEXVAL") 16 32 }}
        The value in decimal is {{ $val }}
        ```

        ```console
        $ HEXVAL=7C0 gomplate < input.tmpl

        The value in decimal is 1984
        ```
  - name: conv.ParseFloat
    released: v1.4.0
    description: |
      _**Note:**_ See [`conv.ToFloat64`](#convtofloat64) instead for a simpler and more flexible variant of this function.

      Parses a string as an float64 for later use. Equivalent to [strconv.ParseFloat](https://pkg.go.dev/strconv/#ParseFloat)
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ $pi := conv.ParseFloat (getenv "PI") 64 }}
        {{- if (gt $pi 3.0) -}}
        pi is greater than 3
        {{- end }}
        ```

        ```console
        $ PI=3.14159265359 gomplate < input.tmpl
        pi is greater than 3
        ```
  - name: conv.ParseUint
    released: v1.4.0
    description: |
      Parses a string as an uint64 for later use. Equivalent to [strconv.ParseUint](https://pkg.go.dev/strconv/#ParseUint)
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ conv.ParseInt (getenv "BIG") 16 64 }} is max int64
        {{ conv.ParseUint (getenv "BIG") 16 64 }} is max uint64
        ```

        ```console
        $ BIG=FFFFFFFFFFFFFFFF gomplate < input.tmpl
        9223372036854775807 is max int64
        18446744073709551615 is max uint64
        ```
  - name: conv.Atoi
    released: v1.4.0
    description: |
      _**Note:**_ See [`conv.ToInt`](#convtoint) and [`conv.ToInt64`](#convtoint64) instead for simpler and more flexible variants of this function.

      Parses a string as an int for later use. Equivalent to [strconv.Atoi](https://pkg.go.dev/strconv/#Atoi)
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ $number := conv.Atoi (getenv "NUMBER") }}
        {{- if (gt $number 5) -}}
        The number is greater than 5
        {{- else -}}
        The number is less than 5
        {{- end }}
        ```

        ```console
        $ NUMBER=21 gomplate < input.tmpl
        The number is greater than 5
        ```
  - name: conv.ToBool
    released: v2.7.0
    description: |
      Converts the input to a boolean value.
      Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"`
      (any capitalizations). All other values are considered `false`.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: The input to convert
    examples:
      - |
        $ gomplate -i '{{ conv.ToBool "yes" }} {{ conv.ToBool true }} {{ conv.ToBool "0x01" }}'
        true true true
        $ gomplate -i '{{ conv.ToBool false }} {{ conv.ToBool "blah" }} {{ conv.ToBool 0 }}'
        false false false
  - name: conv.ToBools
    released: v2.7.0
    description: |
      Converts a list of inputs to an array of boolean values.
      Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"`
      (any capitalizations). All other values are considered `false`.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: The input array to convert
    examples:
      - |
        $ gomplate -i '{{ conv.ToBools "yes" true "0x01" }}'
        [true true true]
        $ gomplate -i '{{ conv.ToBools false "blah" 0 }}'
        [false false false]
  - name: conv.ToInt64
    released: v2.2.0
    description: |
      Converts the input to an `int64` (64-bit signed integer).

      This function attempts to convert most types of input (strings, numbers,
      and booleans).

      Unconvertible inputs will result in errors.

      Floating-point numbers (with decimal points) are truncated.
    arguments:
      - name: in
        required: true
        description: the value to convert
    examples:
      - |
        $ gomplate -i '{{conv.ToInt64 "9223372036854775807"}}'
        9223372036854775807
      - |
        $ gomplate -i '{{conv.ToInt64 "0x42"}}'
        66
      - |
        $ gomplate -i '{{conv.ToInt64 true }}'
        1
  - name: conv.ToInt
    released: v2.2.0
    description: |
      Converts the input to an `int` (signed integer, 32- or 64-bit depending
      on platform). This is similar to [`conv.ToInt64`](#convtoint64) on 64-bit
      platforms, but is useful when input to another function must be provided
      as an `int`.

      Unconvertible inputs will result in errors.

      On 32-bit systems, given a number that is too large to fit in an `int`,
      the result is `-1`. This is done to protect against
      [CWE-190](https://cwe.mitre.org/data/definitions/190.html) and
      [CWE-681](https://cwe.mitre.org/data/definitions/681.html).

      See also [`conv.ToInt64`](#convtoint64).
    arguments:
      - name: in
        required: true
        description: the value to convert
    examples:
      - |
        $ gomplate -i '{{conv.ToInt "9223372036854775807"}}'
        9223372036854775807
      - |
        $ gomplate -i '{{conv.ToInt "0x42"}}'
        66
      - |
        $ gomplate -i '{{conv.ToInt true }}'
        1
  - name: conv.ToInt64s
    released: v2.2.0
    description: |
      Converts the inputs to an array of `int64`s.

      Unconvertible inputs will result in errors.

      This delegates to [`conv.ToInt64`](#convtoint64) for each input argument.
    arguments:
      - name: in...
        required: true
        description: the inputs to be converted
    examples:
      - |
        gomplate -i '{{ conv.ToInt64s true 0x42 "123,456.99" "1.2345e+3"}}'
        [1 66 123456 1234]
  - name: conv.ToInts
    released: v2.2.0
    description: |
      Converts the inputs to an array of `int`s.

      Unconvertible inputs will result in errors.

      This delegates to [`conv.ToInt`](#convtoint) for each input argument.
    arguments:
      - name: in...
        required: true
        description: the inputs to be converted
    examples:
      - |
        gomplate -i '{{ conv.ToInts true 0x42 "123,456.99" "1.2345e+3"}}'
        [1 66 123456 1234]
  - name: conv.ToFloat64
    released: v2.2.0
    description: |
      Converts the input to a `float64`.

      This function attempts to convert most types of input (strings, numbers,
      and booleans).
      
      Unconvertible inputs will result in errors.
    arguments:
      - name: in
        required: true
        description: the value to convert
    examples:
      - |
        $ gomplate -i '{{ conv.ToFloat64 "8.233e-1"}}'
        0.8233
        $ gomplate -i '{{ conv.ToFloat64 "9,000.09"}}'
        9000.09
  - name: conv.ToFloat64s
    released: v2.2.0
    description: |
      Converts the inputs to an array of `float64`s.

      Unconvertible inputs will result in errors.

      This delegates to [`conv.ToFloat64`](#convtofloat64) for each input argument.
    arguments:
      - name: in...
        required: true
        description: the inputs to be converted
    examples:
      - |
        $ gomplate -i '{{ conv.ToFloat64s true 0x42 "123,456.99" "1.2345e+3"}}'
        [1 66 123456.99 1234.5]
  - name: conv.ToString
    released: v2.5.0
    description: |
      Converts the input (of any type) to a `string`.

      The input will always be represented in _some_ way.
    arguments:
      - name: in
        required: true
        description: the value to convert
    examples:
      - |
        $ gomplate -i '{{ conv.ToString 0xFF }}'
        255
        $ gomplate -i '{{ dict "foo" "bar" | conv.ToString}}'
        map[foo:bar]
        $ gomplate -i '{{ conv.ToString nil }}'
        nil
  - name: conv.ToStrings
    released: v2.5.0
    description: |
      Converts the inputs (of any type) to an array of `string`s

      This delegates to [`conv.ToString`](#convtostring) for each input argument.
    arguments:
      - name: in...
        required: true
        description: the inputs to be converted
    examples:
      - |
        $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (coll.Slice 1 2 3) }}'
        [nil 42 true 15 [1 2 3]]