uuid.go

Documentation: github.com/pborman/uuid

     1  // Copyright 2011 Google Inc.  All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package uuid
     6  
     7  import (
     8  	"bytes"
     9  	"crypto/rand"
    10  	"encoding/hex"
    11  	"io"
    12  
    13  	guuid "github.com/google/uuid"
    14  )
    15  
    16  // Array is a pass-by-value UUID that can be used as an effecient key in a map.
    17  type Array [16]byte
    18  
    19  // UUID converts uuid into a slice.
    20  func (uuid Array) UUID() UUID {
    21  	return uuid[:]
    22  }
    23  
    24  // String returns the string representation of uuid,
    25  // xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
    26  func (uuid Array) String() string {
    27  	return guuid.UUID(uuid).String()
    28  }
    29  
    30  // A UUID is a 128 bit (16 byte) Universal Unique IDentifier as defined in RFC
    31  // 4122.
    32  type UUID []byte
    33  
    34  // A Version represents a UUIDs version.
    35  type Version = guuid.Version
    36  
    37  // A Variant represents a UUIDs variant.
    38  type Variant = guuid.Variant
    39  
    40  // Constants returned by Variant.
    41  const (
    42  	Invalid   = guuid.Invalid   // Invalid UUID
    43  	RFC4122   = guuid.RFC4122   // The variant specified in RFC4122
    44  	Reserved  = guuid.Reserved  // Reserved, NCS backward compatibility.
    45  	Microsoft = guuid.Microsoft // Reserved, Microsoft Corporation backward compatibility.
    46  	Future    = guuid.Future    // Reserved for future definition.
    47  )
    48  
    49  var rander = rand.Reader // random function
    50  
    51  // New returns a new random (version 4) UUID as a string.  It is a convenience
    52  // function for NewRandom().String().
    53  func New() string {
    54  	return NewRandom().String()
    55  }
    56  
    57  // Parse decodes s into a UUID or returns nil. See github.com/google/uuid for
    58  // the formats parsed.
    59  func Parse(s string) UUID {
    60  	gu, err := guuid.Parse(s)
    61  	if err == nil {
    62  		return gu[:]
    63  	}
    64  	return nil
    65  }
    66  
    67  // ParseBytes is like Parse, except it parses a byte slice instead of a string.
    68  func ParseBytes(b []byte) (UUID, error) {
    69  	gu, err := guuid.ParseBytes(b)
    70  	if err == nil {
    71  		return gu[:], nil
    72  	}
    73  	return nil, err
    74  }
    75  
    76  // Equal returns true if uuid1 and uuid2 are equal.
    77  func Equal(uuid1, uuid2 UUID) bool {
    78  	return bytes.Equal(uuid1, uuid2)
    79  }
    80  
    81  // Array returns an array representation of uuid that can be used as a map key.
    82  // Array panics if uuid is not valid.
    83  func (uuid UUID) Array() Array {
    84  	if len(uuid) != 16 {
    85  		panic("invalid uuid")
    86  	}
    87  	var a Array
    88  	copy(a[:], uuid)
    89  	return a
    90  }
    91  
    92  // String returns the string form of uuid, xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    93  // , or "" if uuid is invalid.
    94  func (uuid UUID) String() string {
    95  	if len(uuid) != 16 {
    96  		return ""
    97  	}
    98  	var buf [36]byte
    99  	encodeHex(buf[:], uuid)
   100  	return string(buf[:])
   101  }
   102  
   103  // URN returns the RFC 2141 URN form of uuid,
   104  // urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,  or "" if uuid is invalid.
   105  func (uuid UUID) URN() string {
   106  	if len(uuid) != 16 {
   107  		return ""
   108  	}
   109  	var buf [36 + 9]byte
   110  	copy(buf[:], "urn:uuid:")
   111  	encodeHex(buf[9:], uuid)
   112  	return string(buf[:])
   113  }
   114  
   115  func encodeHex(dst []byte, uuid UUID) {
   116  	hex.Encode(dst[:], uuid[:4])
   117  	dst[8] = '-'
   118  	hex.Encode(dst[9:13], uuid[4:6])
   119  	dst[13] = '-'
   120  	hex.Encode(dst[14:18], uuid[6:8])
   121  	dst[18] = '-'
   122  	hex.Encode(dst[19:23], uuid[8:10])
   123  	dst[23] = '-'
   124  	hex.Encode(dst[24:], uuid[10:])
   125  }
   126  
   127  // Variant returns the variant encoded in uuid.  It returns Invalid if
   128  // uuid is invalid.
   129  func (uuid UUID) Variant() Variant {
   130  	if len(uuid) != 16 {
   131  		return Invalid
   132  	}
   133  	switch {
   134  	case (uuid[8] & 0xc0) == 0x80:
   135  		return RFC4122
   136  	case (uuid[8] & 0xe0) == 0xc0:
   137  		return Microsoft
   138  	case (uuid[8] & 0xe0) == 0xe0:
   139  		return Future
   140  	default:
   141  		return Reserved
   142  	}
   143  }
   144  
   145  // Version returns the version of uuid.  It returns false if uuid is not
   146  // valid.
   147  func (uuid UUID) Version() (Version, bool) {
   148  	if len(uuid) != 16 {
   149  		return 0, false
   150  	}
   151  	return Version(uuid[6] >> 4), true
   152  }
   153  
   154  // SetRand sets the random number generator to r, which implements io.Reader.
   155  // If r.Read returns an error when the package requests random data then
   156  // a panic will be issued.
   157  //
   158  // Calling SetRand with nil sets the random number generator to the default
   159  // generator.
   160  func SetRand(r io.Reader) {
   161  	guuid.SetRand(r)
   162  }
   163
View as plain text