github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs/content/functions/conv.md (about) 1 --- 2 title: conversion functions 3 menu: 4 main: 5 parent: functions 6 --- 7 8 These are a collection of functions that mostly help converting from one type 9 to another - generally from a `string` to something else, and vice-versa. 10 11 ## `conv.Bool` 12 13 **Alias:** `bool` 14 15 **Note:** See also [`conv.ToBool`](#conv-tobool) for a more flexible variant. 16 17 Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input. 18 19 ### Usage 20 21 ```go 22 conv.Bool in 23 ``` 24 ```go 25 in | conv.Bool 26 ``` 27 28 ### Arguments 29 30 | name | description | 31 |------|-------------| 32 | `in` | _(required)_ the input string | 33 34 ### Examples 35 36 _`input.tmpl`:_ 37 ``` 38 {{if bool (getenv "FOO")}}foo{{else}}bar{{end}} 39 ``` 40 41 ```console 42 $ gomplate < input.tmpl 43 bar 44 $ FOO=true gomplate < input.tmpl 45 foo 46 ``` 47 48 ## `conv.Default` 49 50 **Alias:** `default` 51 52 Provides a default value given an empty input. Empty inputs are `0` for numeric 53 types, `""` for strings, `false` for booleans, empty arrays/maps, and `nil`. 54 55 Note that this will not provide a default for the case where the input is undefined 56 (i.e. referencing things like `.foo` where there is no `foo` field of `.`), but 57 [`conv.Has`](#conv-has) can be used for that. 58 59 ### Usage 60 61 ```go 62 conv.Default default in 63 ``` 64 ```go 65 in | conv.Default default 66 ``` 67 68 ### Arguments 69 70 | name | description | 71 |------|-------------| 72 | `default` | _(required)_ the default value | 73 | `in` | _(required)_ the input | 74 75 ### Examples 76 77 ```console 78 $ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}' 79 foo bar 80 ``` 81 82 ## `conv.Dict` _(deprecated)_ 83 **Deprecation Notice:** Renamed to [`coll.Dict`](#coll-dict) 84 85 **Alias:** `dict` 86 87 Dict is a convenience function that creates a map with string keys. 88 Provide arguments as key/value pairs. If an odd number of arguments 89 is provided, the last is used as the key, and an empty string is 90 set as the value. 91 92 All keys are converted to strings. 93 94 This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict) 95 function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#template-functions-and-pipelines). 96 97 For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml). 98 99 For creating arrays, see [`conv.Slice`](#conv-slice). 100 101 ### Usage 102 103 ```go 104 conv.Dict in... 105 ``` 106 107 ### Arguments 108 109 | name | description | 110 |------|-------------| 111 | `in...` | _(required)_ The key/value pairs | 112 113 ### Examples 114 115 ```console 116 $ gomplate -i '{{ conv.Dict "name" "Frank" "age" 42 | data.ToYAML }}' 117 age: 42 118 name: Frank 119 $ gomplate -i '{{ dict 1 2 3 | toJSON }}' 120 {"1":2,"3":""} 121 ``` 122 ```console 123 $ cat <<EOF| gomplate 124 {{ define "T1" }}Hello {{ .thing }}!{{ end -}} 125 {{ template "T1" (dict "thing" "world")}} 126 {{ template "T1" (dict "thing" "everybody")}} 127 EOF 128 Hello world! 129 Hello everybody! 130 ``` 131 132 ## `conv.Slice` _(deprecated)_ 133 **Deprecation Notice:** Renamed to [`coll.Slice`](#coll-slice) 134 135 **Alias:** `slice` 136 137 Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables. 138 139 ### Usage 140 141 ```go 142 conv.Slice in... 143 ``` 144 145 ### Arguments 146 147 | name | description | 148 |------|-------------| 149 | `in...` | _(required)_ the elements of the slice | 150 151 ### Examples 152 153 ```console 154 $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}' 155 Hello, Bart 156 Hello, Lisa 157 Hello, Maggie 158 ``` 159 160 ## `conv.Has` _(deprecated)_ 161 **Deprecation Notice:** Renamed to [`coll.Has`](#coll-has) 162 163 **Alias:** `has` 164 165 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. 166 167 ### Usage 168 169 ```go 170 conv.Has in item 171 ``` 172 173 ### Arguments 174 175 | name | description | 176 |------|-------------| 177 | `in` | _(required)_ The object or list to search | 178 | `item` | _(required)_ The item to search for | 179 180 ### Examples 181 182 ```console 183 $ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar' 184 there is a bar 185 ``` 186 ```console 187 $ export DATA='{"foo": "bar"}' 188 $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} 189 {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' 190 bar 191 ``` 192 ```console 193 $ export DATA='{"baz": "qux"}' 194 $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}} 195 {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}' 196 THERE IS NO FOO 197 ``` 198 199 ## `conv.Join` 200 201 **Alias:** `join` 202 203 Concatenates the elements of an array to create a string. The separator string `sep` is placed between elements in the resulting string. 204 205 ### Usage 206 207 ```go 208 conv.Join in sep 209 ``` 210 211 ### Arguments 212 213 | name | description | 214 |------|-------------| 215 | `in` | _(required)_ the array or slice | 216 | `sep` | _(required)_ the separator | 217 218 ### Examples 219 220 ```console 221 $ gomplate -i '{{ $a := slice 1 2 3 }}{{ join $a "-" }}' 222 1-2-3 223 ``` 224 225 ## `conv.URL` 226 227 **Alias:** `urlParse` 228 229 Parses a string as a URL for later use. Equivalent to [url.Parse](https://golang.org/pkg/net/url/#Parse) 230 231 ### Usage 232 233 ```go 234 conv.URL in 235 ``` 236 237 ### Arguments 238 239 | name | description | 240 |------|-------------| 241 | `in` | _(required)_ the URL string to parse | 242 243 ### Examples 244 245 _`input.tmpl`:_ 246 ``` 247 {{ $u := conv.URL "https://example.com:443/foo/bar" }} 248 The scheme is {{ $u.Scheme }} 249 The host is {{ $u.Host }} 250 The path is {{ $u.Path }} 251 ``` 252 253 ```console 254 $ gomplate < input.tmpl 255 The scheme is https 256 The host is example.com:443 257 The path is /foo/bar 258 ``` 259 260 ## `conv.ParseInt` 261 262 _**Note:**_ See [`conv.ToInt64`](#conv-toint64) instead for a simpler and more flexible variant of this function. 263 264 Parses a string as an int64. Equivalent to [strconv.ParseInt](https://golang.org/pkg/strconv/#ParseInt) 265 266 ### Usage 267 268 ```go 269 conv.ParseInt 270 ``` 271 272 273 ### Examples 274 275 _`input.tmpl`:_ 276 ``` 277 {{ $val := conv.ParseInt (getenv "HEXVAL") 16 32 }} 278 The value in decimal is {{ $val }} 279 ``` 280 281 ```console 282 $ HEXVAL=7C0 gomplate < input.tmpl 283 284 The value in decimal is 1984 285 ``` 286 287 ## `conv.ParseFloat` 288 289 _**Note:**_ See [`conv.ToFloat`](#conv-tofloat) instead for a simpler and more flexible variant of this function. 290 291 Parses a string as an float64 for later use. Equivalent to [strconv.ParseFloat](https://golang.org/pkg/strconv/#ParseFloat) 292 293 ### Usage 294 295 ```go 296 conv.ParseFloat 297 ``` 298 299 300 ### Examples 301 302 _`input.tmpl`:_ 303 ``` 304 {{ $pi := conv.ParseFloat (getenv "PI") 64 }} 305 {{- if (gt $pi 3.0) -}} 306 pi is greater than 3 307 {{- end }} 308 ``` 309 310 ```console 311 $ PI=3.14159265359 gomplate < input.tmpl 312 pi is greater than 3 313 ``` 314 315 ## `conv.ParseUint` 316 317 Parses a string as an uint64 for later use. Equivalent to [strconv.ParseUint](https://golang.org/pkg/strconv/#ParseUint) 318 319 ### Usage 320 321 ```go 322 conv.ParseUint 323 ``` 324 325 326 ### Examples 327 328 _`input.tmpl`:_ 329 ``` 330 {{ conv.ParseInt (getenv "BIG") 16 64 }} is max int64 331 {{ conv.ParseUint (getenv "BIG") 16 64 }} is max uint64 332 ``` 333 334 ```console 335 $ BIG=FFFFFFFFFFFFFFFF gomplate < input.tmpl 336 9223372036854775807 is max int64 337 18446744073709551615 is max uint64 338 ``` 339 340 ## `conv.Atoi` 341 342 _**Note:**_ See [`conv.ToInt`](#conv-toint) and [`conv.ToInt64`](#conv-toint64) instead for simpler and more flexible variants of this function. 343 344 Parses a string as an int for later use. Equivalent to [strconv.Atoi](https://golang.org/pkg/strconv/#Atoi) 345 346 ### Usage 347 348 ```go 349 conv.Atoi 350 ``` 351 352 353 ### Examples 354 355 _`input.tmpl`:_ 356 ``` 357 {{ $number := conv.Atoi (getenv "NUMBER") }} 358 {{- if (gt $number 5) -}} 359 The number is greater than 5 360 {{- else -}} 361 The number is less than 5 362 {{- end }} 363 ``` 364 365 ```console 366 $ NUMBER=21 gomplate < input.tmpl 367 The number is greater than 5 368 ``` 369 370 ## `conv.ToBool` 371 372 Converts the input to a boolean value. 373 Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"` 374 (any capitalizations). All other values are considered `false`. 375 376 ### Usage 377 378 ```go 379 conv.ToBool input 380 ``` 381 ```go 382 input | conv.ToBool 383 ``` 384 385 ### Arguments 386 387 | name | description | 388 |------|-------------| 389 | `input` | _(required)_ The input to convert | 390 391 ### Examples 392 393 ```console 394 $ gomplate -i '{{ conv.ToBool "yes" }} {{ conv.ToBool true }} {{ conv.ToBool "0x01" }}' 395 true true true 396 $ gomplate -i '{{ conv.ToBool false }} {{ conv.ToBool "blah" }} {{ conv.ToBool 0 }}' 397 false false false 398 ``` 399 400 ## `conv.ToBools` 401 402 Converts a list of inputs to an array of boolean values. 403 Possible `true` values are: `1` or the strings `"t"`, `"true"`, or `"yes"` 404 (any capitalizations). All other values are considered `false`. 405 406 ### Usage 407 408 ```go 409 conv.ToBools input 410 ``` 411 ```go 412 input | conv.ToBools 413 ``` 414 415 ### Arguments 416 417 | name | description | 418 |------|-------------| 419 | `input` | _(required)_ The input array to convert | 420 421 ### Examples 422 423 ```console 424 $ gomplate -i '{{ conv.ToBools "yes" true "0x01" }}' 425 [true true true] 426 $ gomplate -i '{{ conv.ToBools false "blah" 0 }}' 427 [false false false] 428 ``` 429 430 ## `conv.ToInt64` 431 432 Converts the input to an `int64` (64-bit signed integer). 433 434 This function attempts to convert most types of input (strings, numbers, 435 and booleans), but behaviour when the input can not be converted is 436 undefined and subject to change. Unconvertable inputs may result in 437 errors, or `0` or `-1`. 438 439 Floating-point numbers (with decimal points) are truncated. 440 441 ### Usage 442 443 ```go 444 conv.ToInt64 in 445 ``` 446 447 ### Arguments 448 449 | name | description | 450 |------|-------------| 451 | `in` | _(required)_ the value to convert | 452 453 ### Examples 454 455 ```console 456 $ gomplate -i '{{conv.ToInt64 "9223372036854775807"}}' 457 9223372036854775807 458 ``` 459 ```console 460 $ gomplate -i '{{conv.ToInt64 "0x42"}}' 461 66 462 ``` 463 ```console 464 $ gomplate -i '{{conv.ToInt64 true }}' 465 1 466 ``` 467 468 ## `conv.ToInt` 469 470 Converts the input to an `int` (signed integer, 32- or 64-bit depending 471 on platform). This is similar to [`conv.ToInt64`](#conv-toint64) on 64-bit 472 platforms, but is useful when input to another function must be provided 473 as an `int`. 474 475 See also [`conv.ToInt64`](#conv-toint64). 476 477 ### Usage 478 479 ```go 480 conv.ToInt in 481 ``` 482 483 ### Arguments 484 485 | name | description | 486 |------|-------------| 487 | `in` | _(required)_ the value to convert | 488 489 ### Examples 490 491 ```console 492 $ gomplate -i '{{conv.ToInt "9223372036854775807"}}' 493 9223372036854775807 494 ``` 495 ```console 496 $ gomplate -i '{{conv.ToInt "0x42"}}' 497 66 498 ``` 499 ```console 500 $ gomplate -i '{{conv.ToInt true }}' 501 1 502 ``` 503 504 ## `conv.ToInt64s` 505 506 Converts the inputs to an array of `int64`s. 507 508 This delegates to [`conv.ToInt64`](#conv-toint64) for each input argument. 509 510 ### Usage 511 512 ```go 513 conv.ToInt64s in... 514 ``` 515 516 ### Arguments 517 518 | name | description | 519 |------|-------------| 520 | `in...` | _(required)_ the inputs to be converted | 521 522 ### Examples 523 524 ```console 525 gomplate -i '{{ conv.ToInt64s true 0x42 "123,456.99" "1.2345e+3"}}' 526 [1 66 123456 1234] 527 ``` 528 529 ## `conv.ToInts` 530 531 Converts the inputs to an array of `int`s. 532 533 This delegates to [`conv.ToInt`](#conv-toint) for each input argument. 534 535 ### Usage 536 537 ```go 538 conv.ToInts in... 539 ``` 540 541 ### Arguments 542 543 | name | description | 544 |------|-------------| 545 | `in...` | _(required)_ the inputs to be converted | 546 547 ### Examples 548 549 ```console 550 gomplate -i '{{ conv.ToInts true 0x42 "123,456.99" "1.2345e+3"}}' 551 [1 66 123456 1234] 552 ``` 553 554 ## `conv.ToFloat64` 555 556 Converts the input to a `float64`. 557 558 This function attempts to convert most types of input (strings, numbers, 559 and booleans), but behaviour when the input can not be converted is 560 undefined and subject to change. Unconvertable inputs may result in 561 errors, or `0` or `-1`. 562 563 ### Usage 564 565 ```go 566 conv.ToFloat64 in 567 ``` 568 569 ### Arguments 570 571 | name | description | 572 |------|-------------| 573 | `in` | _(required)_ the value to convert | 574 575 ### Examples 576 577 ```console 578 $ gomplate -i '{{ conv.ToFloat64 "8.233e-1"}}' 579 0.8233 580 $ gomplate -i '{{ conv.ToFloat64 "9,000.09"}}' 581 9000.09 582 ``` 583 584 ## `conv.ToFloat64s` 585 586 Converts the inputs to an array of `float64`s. 587 588 This delegates to [`conv.ToFloat64`](#conv-tofloat64) for each input argument. 589 590 ### Usage 591 592 ```go 593 conv.ToFloat64s in... 594 ``` 595 596 ### Arguments 597 598 | name | description | 599 |------|-------------| 600 | `in...` | _(required)_ the inputs to be converted | 601 602 ### Examples 603 604 ```console 605 $ gomplate -i '{{ conv.ToFloat64s true 0x42 "123,456.99" "1.2345e+3"}}' 606 [1 66 123456.99 1234.5] 607 ``` 608 609 ## `conv.ToString` 610 611 Converts the input (of any type) to a `string`. 612 613 The input will always be represented in _some_ way. 614 615 ### Usage 616 617 ```go 618 conv.ToString in 619 ``` 620 621 ### Arguments 622 623 | name | description | 624 |------|-------------| 625 | `in` | _(required)_ the value to convert | 626 627 ### Examples 628 629 ```console 630 $ gomplate -i '{{ conv.ToString 0xFF }}' 631 255 632 $ gomplate -i '{{ dict "foo" "bar" | conv.ToString}}' 633 map[foo:bar] 634 $ gomplate -i '{{ conv.ToString nil }}' 635 nil 636 ``` 637 638 ## `conv.ToStrings` 639 640 Converts the inputs (of any type) to an array of `string`s 641 642 This delegates to [`conv.ToString`](#conv-tostring) for each input argument. 643 644 ### Usage 645 646 ```go 647 conv.ToStrings in... 648 ``` 649 650 ### Arguments 651 652 | name | description | 653 |------|-------------| 654 | `in...` | _(required)_ the inputs to be converted | 655 656 ### Examples 657 658 ```console 659 $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}' 660 [nil 42 true 15 [1 2 3]] 661 ```