1Elixir UUID 2=========== 3 4[![hex.pm version](https://img.shields.io/hexpm/v/uuid.svg?style=flat)](https://hex.pm/packages/uuid) 5[![hex.pm downloads](https://img.shields.io/hexpm/dt/uuid.svg?style=flat)](https://hex.pm/packages/uuid) 6[![travis.ci build status](https://img.shields.io/travis/zyro/elixir-uuid.svg?style=flat)](https://travis-ci.org/zyro/elixir-uuid) 7 8UUID generator and utilities for [Elixir](http://elixir-lang.org/). See [RFC 4122](http://www.ietf.org/rfc/rfc4122.txt). 9 10### Installation 11 12The latest version is `1.1.8` and requires Elixir `~> 1.0`. New releases may change this minimum compatible version depending on breaking language changes. The [changelog](https://github.com/zyro/elixir-uuid/blob/master/CHANGELOG.md) lists every available release and its corresponding language version requirement. 13 14Releases are published through [hex.pm](https://hex.pm/packages/uuid). Add as a dependency in your `mix.exs` file: 15```elixir 16defp deps do 17 [ { :uuid, "~> 1.1" } ] 18end 19``` 20 21### UUID v1 22 23Generated using a combination of time since the west adopted the gregorian calendar and the node id MAC address. 24 25```elixir 26iex> UUID.uuid1() 27"5976423a-ee35-11e3-8569-14109ff1a304" 28``` 29 30### UUID v3 31 32Generated using the MD5 hash of a name and either a namespace atom or an existing UUID. Valid namespaces are: `:dns`, `:url`, `:oid`, `:x500`, `:nil`. 33 34```elixir 35iex> UUID.uuid3(:dns, "my.domain.com") 36"03bf0706-b7e9-33b8-aee5-c6142a816478" 37 38iex> UUID.uuid3("5976423a-ee35-11e3-8569-14109ff1a304", "my.domain.com") 39"0609d667-944c-3c2d-9d09-18af5c58c8fb" 40``` 41 42### UUID v4 43 44Generated based on pseudo-random bytes. 45 46```elixir 47iex> UUID.uuid4() 48"fcfe5f21-8a08-4c9a-9f97-29d2fd6a27b9" 49``` 50 51### UUID v5 52 53Generated using the SHA1 hash of a name and either a namespace atom or an existing UUID. Valid namespaces are: `:dns`, `:url`, `:oid`, `:x500`, `:nil`. 54 55```elixir 56iex> UUID.uuid5(:dns, "my.domain.com") 57"016c25fd-70e0-56fe-9d1a-56e80fa20b82" 58 59iex> UUID.uuid5("fcfe5f21-8a08-4c9a-9f97-29d2fd6a27b9", "my.domain.com") 60"b8e85535-761a-586f-9c04-0fb0df2cbe84" 61``` 62 63### Formatting 64 65All UUID generator functions have an optional format parameter as the last argument. 66 67Possible values: `:default`, `:hex`, `:urn`. Default value is `:default` and can be omitted. 68 69`:default` is a standard UUID representation: 70```elixir 71iex> UUID.uuid1() 72"3c69679f-774b-4fb1-80c1-7b29c6e7d0a0" 73 74iex> UUID.uuid4(:default) 75"3c69679f-774b-4fb1-80c1-7b29c6e7d0a0" 76 77iex> UUID.uuid3(:dns, "my.domain.com") 78"03bf0706-b7e9-33b8-aee5-c6142a816478" 79 80iex> UUID.uuid5(:dns, "my.domain.com", :default) 81"016c25fd-70e0-56fe-9d1a-56e80fa20b82" 82``` 83 84`:hex` is a valid hex string, corresponding to the standard UUID without the `-` (dash) characters: 85```elixir 86iex> UUID.uuid4(:hex) 87"19be859d0c1f4a7f95ddced995037350" 88 89iex> UUID.uuid4(:weak, :hex) 90"ebeff765ddc843e486c287fb668d5d37" 91``` 92 93`:urn` is a standard UUID representation prefixed with the UUID URN: 94```elixir 95iex> UUID.uuid1(:urn) 96"urn:uuid:b7483bde-ee35-11e3-8daa-14109ff1a304" 97``` 98 99### Utility functions 100 101Use `UUID.info/1` and `UUID.info!/1` to get a [keyword list](http://elixir-lang.org/getting_started/7.html#toc_1) containing information about the given UUID. `UUID.info/1` returns a tuple of `{:ok, info}` for valid cases or `{:error, reason}` if the argument is not a UUID string. `UUID.info!/1` directly returns the info keyword list when successful or raises an `ArgumentError` for error cases. 102```elixir 103iex> UUID.info!("870df8e8-3107-4487-8316-81e089b8c2cf") 104[uuid: "870df8e8-3107-4487-8316-81e089b8c2cf", 105 binary: <<135, 13, 248, 232, 49, 7, 68, 135, 131, 22, 129, 224, 137, 184, 194, 207>>, 106 type: :default, 107 version: 4, 108 variant: :rfc4122] 109 110iex> UUID.info!("8ea1513df8a14dea9bea6b8f4b5b6e73") 111[uuid: "8ea1513df8a14dea9bea6b8f4b5b6e73", 112 binary: <<142, 161, 81, 61, 248, 161, 77, 234, 155, 234, 107, 143, 75, 91, 110, 115>>, 113 type: :hex, 114 version: 4, 115 variant: :rfc4122] 116 117iex> UUID.info!("urn:uuid:ef1b1a28-ee34-11e3-8813-14109ff1a304") 118[uuid: "urn:uuid:ef1b1a28-ee34-11e3-8813-14109ff1a304", 119 binary: <<239, 27, 26, 40, 238, 52, 17, 227, 136, 19, 20, 16, 159, 241, 163, 4>>, 120 type: :urn, 121 version: 1, 122 variant: :rfc4122] 123``` 124 125Use `UUID.string_to_binary!/1` to convert a valid UUID string to its raw binary equivalent. An `ArgumentError` is raised if the argument is not a valid UUID string. 126```elixir 127iex> UUID.string_to_binary!("870df8e8-3107-4487-8316-81e089b8c2cf") 128<<135, 13, 248, 232, 49, 7, 68, 135, 131, 129 22, 129, 224, 137, 184, 194, 207>> 130 131iex> UUID.string_to_binary!("8ea1513df8a14dea9bea6b8f4b5b6e73") 132<<142, 161, 81, 61, 248, 161, 77, 234, 155, 133 234, 107, 143, 75, 91, 110, 115>> 134 135 136iex> UUID.string_to_binary!("urn:uuid:ef1b1a28-ee34-11e3-8813-14109ff1a304") 137<<239, 27, 26, 40, 238, 52, 17, 227, 136, 138 19, 20, 16, 159, 241, 163, 4>> 139``` 140 141Use `UUID.binary_to_string!/2` to convert valid UUID binary data to a String representation, with an optional format similar to the generator functions above. An `ArgumentError` is raised if the argument is not valid UUID binary data. 142```elixir 143iex> UUID.binary_to_string!(<<135, 13, 248, 232, 49, 7, 68, 135, 131, 144 22, 129, 224, 137, 184, 194, 207>>) 145"870df8e8-3107-4487-8316-81e089b8c2cf" 146 147iex> UUID.binary_to_string!(<<142, 161, 81, 61, 248, 161, 77, 234, 155, 148 234, 107, 143, 75, 91, 110, 115>>, :hex) 149"8ea1513df8a14dea9bea6b8f4b5b6e73" 150 151iex> UUID.binary_to_string!(<<239, 27, 26, 40, 238, 52, 17, 227, 136, 152 19, 20, 16, 159, 241, 163, 4>>, :urn) 153"urn:uuid:ef1b1a28-ee34-11e3-8813-14109ff1a304" 154``` 155 156### Attribution 157 158Some code ported from [avtobiff/erlang-uuid](https://github.com/avtobiff/erlang-uuid). 159 160Some helper functions from [rjsamson/hexate](https://github.com/rjsamson/hexate). 161 162### License 163 164``` 165Copyright 2014-2016 Andrei Mihu 166 167Licensed under the Apache License, Version 2.0 (the "License"); 168you may not use this file except in compliance with the License. 169You may obtain a copy of the License at 170 171 http://www.apache.org/licenses/LICENSE-2.0 172 173Unless required by applicable law or agreed to in writing, software 174distributed under the License is distributed on an "AS IS" BASIS, 175WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 176See the License for the specific language governing permissions and 177limitations under the License. 178``` 179