github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs/content/functions/uuid.md (about)

     1  ---
     2  title: uuid functions
     3  menu:
     4    main:
     5      parent: functions
     6  ---
     7  
     8  Functions for generating, parsing, and manipulating UUIDs.
     9  
    10  A UUID is a 128 bit (16 byte) _Universal Unique IDentifier_ as defined
    11  in [RFC 4122][]. Only RFC 4112-variant UUIDs can be generated, but all variants
    12  (even invalid ones) can be parsed and manipulated. Also, gomplate only supports
    13  generating version 1 and 4 UUIDs (with 4 being the most commonly-used variety
    14  these days). Versions 2, 3, and 5 are able to be supported: [log an issue][] if
    15  this is required for your use-case.
    16  
    17  [RFC 4122]: https://en.wikipedia.org/wiki/Universally_unique_identifier
    18  [log an issue]: https://github.com/hairyhenderson/gomplate/issues/new
    19  
    20  ## `uuid.V1`
    21  
    22  Create a version 1 UUID (based on the current MAC address and the current date/time).
    23  
    24  Use [`uuid.V4`](#uuid-v4) instead in most cases.
    25  
    26  _Added in gomplate [v3.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v3.4.0)_
    27  ### Usage
    28  
    29  ```
    30  uuid.V1
    31  ```
    32  
    33  
    34  ### Examples
    35  
    36  ```console
    37  $ gomplate -i '{{ uuid.V1 }}'
    38  4d757e54-446d-11e9-a8fa-72000877c7b0
    39  ```
    40  
    41  ## `uuid.V4`
    42  
    43  Create a version 4 UUID (randomly generated).
    44  
    45  This function consumes entropy.
    46  
    47  _Added in gomplate [v3.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v3.4.0)_
    48  ### Usage
    49  
    50  ```
    51  uuid.V4
    52  ```
    53  
    54  
    55  ### Examples
    56  
    57  ```console
    58  $ gomplate -i '{{ uuid.V4 }}'
    59  40b3c2d2-e491-4b19-94cd-461e6fa35a60
    60  ```
    61  
    62  ## `uuid.Nil`
    63  
    64  Returns the _nil_ UUID, that is, `00000000-0000-0000-0000-000000000000`,
    65  mostly for testing scenarios.
    66  
    67  _Added in gomplate [v3.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v3.4.0)_
    68  ### Usage
    69  
    70  ```
    71  uuid.Nil
    72  ```
    73  
    74  
    75  ### Examples
    76  
    77  ```console
    78  $ gomplate -i '{{ uuid.Nil }}'
    79  00000000-0000-0000-0000-000000000000
    80  ```
    81  
    82  ## `uuid.IsValid`
    83  
    84  Checks that the given UUID is in the correct format. It does not validate
    85  whether the version or variant are correct.
    86  
    87  _Added in gomplate [v3.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v3.4.0)_
    88  ### Usage
    89  
    90  ```
    91  uuid.IsValid uuid
    92  ```
    93  ```
    94  uuid | uuid.IsValid
    95  ```
    96  
    97  ### Arguments
    98  
    99  | name | description |
   100  |------|-------------|
   101  | `uuid` | _(required)_ The uuid to check |
   102  
   103  ### Examples
   104  
   105  ```console
   106  $ gomplate -i '{{ if uuid.IsValid "totally invalid" }}valid{{ else }}invalid{{ end }}'
   107  invalid
   108  ```
   109  ```console
   110  $ gomplate -i '{{ uuid.IsValid "urn:uuid:12345678-90ab-cdef-fedc-ba9876543210" }}'
   111  true
   112  ```
   113  
   114  ## `uuid.Parse`
   115  
   116  Parse a UUID for further manipulation or inspection.
   117  
   118  This function returns a `UUID` struct, as defined in the [github.com/google/uuid](https://godoc.org/github.com/google/uuid#UUID) package. See the docs for examples of functions or fields you can call.
   119  
   120  Both the standard UUID forms of `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` and
   121  `urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` are decoded as well as the
   122  Microsoft encoding `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}` and the raw hex
   123  encoding (`xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).
   124  
   125  _Added in gomplate [v3.4.0](https://github.com/hairyhenderson/gomplate/releases/tag/v3.4.0)_
   126  ### Usage
   127  
   128  ```
   129  uuid.Parse uuid
   130  ```
   131  ```
   132  uuid | uuid.Parse
   133  ```
   134  
   135  ### Arguments
   136  
   137  | name | description |
   138  |------|-------------|
   139  | `uuid` | _(required)_ The uuid to parse |
   140  
   141  ### Examples
   142  
   143  ```console
   144  $ gomplate -i '{{ $u := uuid.Parse uuid.V4 }}{{ $u.Version }}, {{ $u.Variant}}'
   145  VERSION_4, RFC4122
   146  ```
   147  ```console
   148  $ gomplate -i '{{ (uuid.Parse "000001f5-4470-21e9-9b00-72000877c7b0").Domain }}'
   149  Person
   150  ```