# uuid 3.0.7

RFC4122 (v1, v4, v5) UUID Generator and Parser for all Dart platforms (Web, VM, Flutter)





## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'uuid:3.0.7'
```
Published: 2022-11-13T09:50:24.238593Z
Expected archive SHA-256: 648e103079f7c64a36dc7d39369cabb358d377078a051d6ae2ad3aa539519313

Available in cache; verification: upstream_checksum
## Direct dependencies
- crypto: ^3.0.0

## Package README (untrusted upstream documentation)
**Version 3.0.x has breaking changes, please review changelog and documentation.**
**UuidValue is still Experimental and the API for it is in flux, please pay attention to changelogs and versions.**

[![Build Status](https://github.com/Daegalus/dart-uuid/workflows/Dart/badge.svg?branch=nullsafety&event=push)](https://github.com/Daegalus/dart-uuid/actions)

# uuid

Simple, fast generation of [RFC4122](https://www.ietf.org/rfc/rfc4122.txt) UUIDs.

Features:

* Generate RFC4122 version 1, version 4, or version 5 UUIDs
* Runs in web, server, and flutter
* Cryptographically strong random number generation on all platforms
  * **Defaults to non-crypto generator, see UuidUtil for cryptoRNG**
* [Documentation](https://daegalus.github.io/dart-uuid/index.html)

## Getting Started

### Instructions

1.  Open a command line and cd to your projects root folder
2.  In your pubspec, add an entry for dart-uuid to your dependencies (example below)
3.  pub install
4.  If you wish to run tests, go into packages/dart-uuid/ and run 'dart test/uuid_test.dart'

### Pubspec

There are 2 options. Directly from git, or from pub.dartlang.org

pub.dartlang.org: (you can use 'any' instead of a version if you just want the latest always)

```yaml
dependencies:
  uuid: ^3.0.6
```

```dart
import 'package:uuid/uuid.dart';

var uuid = Uuid();
```

Then create some ids ...

```dart
// Generate a v1 (time-based) id
uuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'

// Generate a v4 (random) id
uuid.v4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'

// Generate a v5 (namespace-name-sha1-based) id
uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com'); // -> 'c74a196f-f19d-5ea9-bffd-a2742432fc9c'
```

## API

### Uuid({Map<String, dynamic> options: null}) -> Uuid (Constructor)

Constructor supports setting some global RNG sertings so you don't have to specify them on each function call for v4 or v5

* `options` - (Map<String, dynamic>) Optional uuid state to apply. Properties may include:

  * `grng` - (Function) Random # generator to use as a global rng function. A Custom function that returns an list[16] of byte values or 1 of 2 provided.
  * `gNamedArgs` - (Map<Symbol, dynamic>) The arguments and values you want to pass to your global rng function.
  * `gPositionalArgs` - (List) The positional arguments for your global rng functions, if any.
  * `v1rng` - (Function) Random # generator to use as a rng function for v1 seed. A Custom function that returns an list[16] of byte values or 1 of 2 provided.
  * `v1rngNamedArgs` - (Map<Symbol, dynamic>) The arguments and values you want to pass to your v1 rng function.
  * `v1rngPositionalArgs` - (List) The positional arguments for your v1 rng functions, if any.

Defaults are `Uuid.mathRNG`

Example: Using CryptoRNG globally

```dart
var uuid = Uuid(options: {
  'grng': UuidUtil.cryptoRNG
})

// Generate a v4 (random) id that will use cryptRNG for its rng function
uuid.v4();
```

### uuid.v1({Map<String, dynamic> options: null) -> String
### uuid.v1obj({Map<String, dynamic> options: null) -> UuidValue
### uuid.v1buffer(List<int> buffer, {Map<String, dynamic> options: null, int offset: 0}) -> List<int>

Generate and return a RFC4122 v1 (timestamp-based) UUID.

* `options` - (Map<String, dynamic>) Optional uuid state to apply. Properties may include:

  * `node` - (List<int>) Node id as List of 6 bytes (per 4.1.6). Default: Randomnly generated ID.
  * `clockseq` - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used.
  * `msecs` - (Number) Time in milliseconds since unix Epoch. Default: The current time is used.
  * `nsecs` - (Number between 0-9999) additional time, in 100-nanosecond units. Ignored if `msecs` is unspecified. Default: internal uuid counter is used, as per 4.2.1.2.

* `buffer` - (List<int>) Array or buffer where UUID bytes are to be written.
* `offset` - (Int) Starting index in `buffer` at which to begin writing.

v1() returns a string representation of the uuid.

v1buffer() Returns a List<int> `buffer`, if specified, also writes the data to the provided buffer.

v1obj() Returns a UuidValue, which has a validation check and some internal functions wrapping the string.

Example: Generate string UUID with fully-specified options

```dart
uuid.v1(options: {
    'node': [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
    'clockSeq': 0x1234,
    'mSecs': new DateTime.utc(2011,11,01).millisecondsSinceEpoch,
    'nSecs': 5678
})   // -> "710b962e-041c-11e1-9234-0123456789ab"
```

Example: In-place generation of two binary IDs

```dart
// Generate two ids in an array
var myBuffer = new List(32); // -> []
uuid.v1buffer(myBuffer);
// -> [115, 189, 5, 128, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null]
uuid.v1buffer(myBuffer, offset: 16);  
// -> [115, 189, 5, 128, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128, 115, 189, 5, 129, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128]

// Optionally use uuid.unparse() to get stringify the ids
uuid.unparse(myBuffer);    // -> '73bd0580-c95b-11e1-9234-6d0009003480'
uuid.unparse(myBuffer, offset: 16) // -> '73bd0581-c95b-11e1-9234-6d0009003480'
```

Example: UuidValue usage

```dart
uuidValue = uuid.v1Obj(options: {
    'node': [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
    'clockSeq': 0x1234,
    'mSecs': new DateTime.utc(2011,11,01).millisecondsSinceEpoch,
    'nSecs': 5678
}) // -> UuidValue{uuid: '710b962e-041c-11e1-9234-0123456789ab'}

print(uuidValue) -> // -> '710b962e-041c-11e1-9234-0123456789ab'
uuidValue.toBytes() -> // -> [...]
```

### uuid.v4({Map<String, dynamic> options: null}) -> String
### uuid.v4obj({Map<String, dynamic> options: null}) -> UuidValue
### uuid.v4buffer(List<int> buffer, {Map<String, dynamic> options: null, int offset: 0}) -> List<int>
Generate and return a RFC4122 v4 UUID.

* `options` - (Map<String, dynamic>) Optional uuid state to apply. Properties may include:

  * `random` - (Number[16]) List of 16 numbers (0-255) to use in place of randomly generated values
  * `rng` - (Function) Random # generator to use. A Custom function that returns an list[16] of byte values or 1 of 2 provided.
  * `namedArgs` - (Map<Symbol, dynamic>) The arguments and values you want to pass to your function.
  * `positionalArgs` - (List) The positional arguments for your functions. if any.

* `buffer` - (List<int>) Array or buffer where UUID bytes are to be written.
* `offset` - (Number) Starting index in `buffer` at which to begin writing.

v4() returns a string representation of the uuid.

v4buffer() Returns a List<int> `buffer`, if specified, also writes the data to the provided buffer.

v4obj() Returns a UuidValue, which has a validation check and some internal functions wrapping the string.

Example: Generate string UUID with different RNG method

```dart
import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.cryptoRNG
});
// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"
```

Example: Generate string UUID with different RNG method and named parameters

```dart
import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.mathRNG,
  'namedArgs': new Map.fromIterables([const Symbol('seed')],[1])
});
// -> "09a91894-e93f-4141-a3ec-82eb32f2a3ef"
```

Example: Generate string UUID with different RNG method and positional parameters

```dart
import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.cryptoRNG,
  'positionalArgs': [1]
});
// -> "09a91894-e93f-4141-a3ec-82eb32f2a3ef"
```

Example: Generate string UUID with fully-specified options

```dart
uuid.v4(options: {
  'random': [
    0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
    0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
  ]
});
// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"
```

Example: Generate two IDs in a single buffer

```dart
var myBuffer = new List(32);
uuid.v4buffer(myBuffer);
uuid.v4buffer(myBuffer, offset: 16);
```

Example: UuidValue usage

```dart
uuidValue = uuid.v4obj(options: {
  'random': [
    0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
    0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
  ]
}) // -> UuidValue{uuid: '109156be-c4fb-41ea-b1b4-efe1671c5836'}

print(uuidValue) -> // -> '109156be-c4fb-41ea-b1b4-efe1671c5836'
uuidValue.toBytes() -> // -> [...]
```

### uuid.v5(String namespace, String name, {Map<String, dynamic> options: null}) -> String
### uuid.v5obj(String namespace, String name, {Map<String, dynamic> options: null}) -> UuidValue
### uuid.v5buffer(String namespace, String name, List<int> buffer, {Map<String, dynamic> options: null, int offset: 0}) -> List<int>
Generate and return a RFC4122 v5 UUID.

* `options` - (Map<String, dynamic>) Optional uuid state to apply. Properties may include:

  * `randomNamespace` - (Boolean) Default True. Returns if you want a v4 generated namespace (true) or NAMESPACE_NIL (false)

* `buffer` - (List<int>) Array or buffer where UUID bytes are to be written.
* `offset` - (Number) Starting index in `buffer` at which to begin writing.

v5() returns a string representation of the uuid.

v5buffer() Returns a List<int> `buffer`, if specified, also writes the data to the provided buffer.

v5obj() Returns a UuidValue, which has a validation check and some internal functions wrapping the string.

Example: Generate string UUID with fully-specified options

```dart
uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com');
// -> "c74a196f-f19d-5ea9-bffd-a2742432fc9c"
```

Example: Generate two IDs in a single buffer

```dart
var myBuffer = new List(32);
uuid.v5buffer(Uuid.NAMESPACE_URL, 'www.google.com', myBuffer);
uuid.v5buffer(Uuid.NAMESPACE_URL, 'www.google.com', myBuffer, offset: 16);
```

Example: UuidValue usage

```dart
uuidValue = uuid.v5obj(Uuid.NAMESPACE_URL, 'www.google.com'); 
// -> UuidValue(uuid: "c74a196f-f19d-5ea9-bffd-a2742432fc9c")

print(uuidValue) -> // -> 'c74a196f-f19d-5ea9-bffd-a2742432fc9c'
uuidValue.toBytes() -> // -> [...]
```

### uuid.parse(String uuid, {List<int> buffer: null, int offset: 0, bool validate: true, ValidationMode validationMode: ValidationMode.strictRFC4122}) -> List<int>

### uuid.parseAsByteList(String uuid, {List<int> buffer: null, int offset: 0, bool validate: true, ValidationMode validationMode: ValidationMode.strictRFC4122}) -> Uint8List

### uuid.unparse(List<int> buffer, {int offset: 0}) -> String

Parse and unparse UUIDs

* `id` - (String) UUID(-like) string
* `buffer` - (List) Array or buffer where UUID bytes are to be written. Default: A new Array or Buffer is used
* `offset` - (Int | Number) Starting index in `buffer` at which to begin writing. Default: 0
* `validate` - (bool, default: true) Allows you to disable UUID validation, mostly useful for Microsoft GUID nonsense.

**Throws**: 
parse() -> FormatException - when not a valid UUID
unparse() -> Exception - when length of list contents is not 16

Example parsing and unparsing a UUID string

```dart
var bytes = uuid.parse('797ff043-11eb-11e1-80d6-510998755d10'); // -> [121, 127, 240, 67, 17, 235, 17, 225, 128, 214, 81, 9, 152, 117, 93, 16]
var string = uuid.unparse(bytes); // -> '797ff043-11eb-11e1-80d6-510998755d10'
```

For more examples or usage, check my test implementations.

## Testing

In dartvm

```
dart test\uuid_test.dart
```

In Browser/flutter

No in browser testing, but I know many use it in Web and Flutter projects.

### Dart2js output size (minified, optimized with -O2)

* v1 only: 59kb
* v4 only: 54kb
* v4 crypto only: 61kb
* v5 only: 69kb
* v1 + v4: 66kb (includes crypto)
* v4 + v5: 76kb (includes crypto)

* ALL: 76kb
* v1 + v5: 77kb

## Release notes

See CHANGELOG

## Changelog
v3.0.7

* Fixed parse to allow buffers larger than 16 bytes to be used.

v3.0.6

* Enable `avoid_dynamic_calls` linting and fix appropriately. (Thanks @devoncarew)

v3.0.5

* Global options were incorrectly being ignored. #76 (Thanks @Skycoder42)
* V4 Global Options were incorrectly named. #76 (Thanks @Skycoder42)
* Global state was static, not per instance. #76 (Thanks @Skycoder42)
* Additional tests to make sure the above doesn't regress. #76 (Thanks @Skycoder42)

v3.0.4

* `isValidUUID` now handles some Microsoft GUIDs better that only deviate in the Variant setting. (Thanks @FluentChange)
* Improve error output so that it better explains how to handle the above change in your code if you encounter it. (Thanks @FluentChange)
* Improve validation logic to better handle multiple validation cases, error output, and feedback to developers. (Thanks @FluentChange)

v3.0.3

* [Experimental] Fixed UuidValue to properly check things are valid. (Thanks @FlorianUlivi)
* [Experimental] Added new constructors `fromByteList` and `fromList` to `UuidValue`
* [Experimental] Added `==` operator override and hashcode override. (Thanks @giorgiofran for suggestion)
* Added `parseAsByteList` to offer a direct output to `Uint8List`
* [Experimental][BREAKING CHANGE] Change `toBytes` in `UuidValue` to return `Uint8List` instead of `List<int>`
* [Experimental][BREAKING CHANGE] `isValidUuid` function signature has changed, now takes 2 optional parameters `fromString` and `fromList` that will do the appropriate validation on different sources.

v3.0.2

* [Experimental] Add flags to UuidValue constructor and parse to disable validation of the UUID, primarily to allow Microsoft GUIDs to not break things.

v3.0.1

* Fix RNG to not need shuffling and improve performance/memory usage (Thanks @julemand101)

v3.0.0

* Release nullsafety version 

v3.0.0-nullsafety.1

* [BREAKING CHANGE] Changed `parse()` to throw a FormatException instead of returning NIL uuids or partially handled UUIDs.
* Changed `Uuid` constructor to be constant, and adjusted all the code accordingly.
* New `isValidUUID` function for validating UUIDs.
* [BREAKING CHANGE] `parse` and `unparse` are now static functions.
* [Exprimental] Object version of the UUID instead of a string or list of bytes.

v3.0.0-nullsafety.0

* Migrate package to null-safety, increase minimum SDK version to 2.12 (Thanks @simolus3)

v2.2.1 & v2.2.2

* Update pedantic analyzer options, fix linting issues, and increase SDK minimium to 2.2 to support set literals

v2.2.0

* fix v1 clock high to properly ignore c and d variants. (fixes #47)
* update example

v2.1.0

* Shuffle mathRNG bytes so that they don't generate duplicates. Will affect codes generated by a static seed.

v2.0.4

* Remove new keyword where not needed. (forgot to rerun before releasing 2.0.3)

v2.0.3

* Do some analyzer fixes and formatting/renaming.

v2.0.2

* Merge fix for time precision loss in V1 time based UUIDs.

v2.0.1

* Fix regression where CryptoRNG was default, moved back to MathRNG
* Added ability to set RNG globally to skip having to set it in every function call
* Allows you to set the v1 clock sequence, nodeID, and seed bytes to use cryptoRNG separately from globalRNG.

v2.0.0

* Fixup the API to split out Buffer and Non-buffer usages.
* Switch to build in Random.secure() and remove custom AES implementation.
* Less dependencies.
* Docs
* Cleanup

v1.0.3

* Fix SDK constraints to allow Dart 2.0 stable.

v1.0.2

* Fix constants breaking in Dart 1.x, need to be backwards compatible. 

v1.0.1

* Fix constants to match Dart 2.0 spec

v1.0.0

* Cleanup and prep for dart 2.0
* Has been stable for a long time, upgrading to 1.0 version

v0.5.3

* Merged pull request to support crypto 2.0.0
* Support convert 2.0.0

v0.5.2

* Merged pull request to upgrade crypto library to 1.0.0.

v0.5.1

* Merged pull request for various updates and cleanup.

v0.5.0

* Reverted back to custom AES implementation. Moved RNG methods to UuidUtil (import 'package:uuid/uuid_util.dart')
* Fixed a potential bug with custom RNG method passing and added more ways to pass in custom RNG functions.
* Cleaned up and refactored some stuff. Using only v1 is only 67kb of js, Using only v4 is 97kb. Using crypt v4 is 118kb. Using both v1 and non-crypto v4 is 126kb.
* Default RNG for v4 is now the mathRNG function. If you wish to use cryptoRNG, import UuidUtil and pass in cryptoRNG.
* Updated README.md with more examples and usages.
* Updated Tests.

v0.4.1

* Changed initCipher location so that if you ever only use v1 UUIDs, you will get a very small Dart2JS output compared to v4 or v5 that do load it.

v0.4.0

* Use Cipher base.dart, as I don't need entropy generators, and this allows me to merge client/server together again
  and fix many issues this caused.

v0.3.2

* Fix import/library bug.

v0.3.1

* Update pubspec to allow installation of the latest Cipher 0.7.

v0.3.0

* Updated to latest Cipher at 0.6.0. This created a breaking change in the imports. Please make sure you update your code.
* Fixed problem when creating v4 UUIDs too fast, it would create duplicate UUIDs.

v0.2.2

* Pegging cipher to 0.4.0 temporarily for browser support

v0.2.1

* Using new version of cipher.

v0.2.0

* Dart 1.0 Readiness
* Switched from custom AES to [cipher](https://github.com/izaera/cipher) package AES.

v0.1.6

* Adjusting usage of constants.
* Fixing tests.

v0.1.5

* Stupid typo on import.

v0.1.4

* Fixing Crypto package move.

v0.1.3

* Fixing language changes.

v0.1.2

* Fix change of charCodes to codeUnits

v0.1.1

* Fixing syntax for upcoming breaking changes.

v0.1.0

* Cleanup, changes, and prep for M3.

v0.0.9

* Minor fix with a const RegExp
* Made sure everything builds on latest dart.
* Fixed pubspec to now import unittest from pub instead of sdk.

v0.0.8

* Changed to the new optional paramater syntaxes and usages.
* Adjusted tests for the new function call style due to parameter change.
* Fixed Import/Source/Library statements to the new format.

v0.0.7

* Made changes requested by the Google team to get my package up on pub.dartlang.org

v0.0.6

* Fixed up some code to make it possibly faster and using better Dart practices.
* Cleaned up some documentation.

v0.0.5

* Added Initial AES for Dart (untested if it actually works/matches other AES encryptors)
* Use AES cipher to create crypto strong bytes.

v0.0.4

* Issue wasn't Math.Random() but a bad reseed by me.
* Cleaned up for new Pub layout.

v0.0.3

* Added UUIDv5
* Fixed UUIDv4 bugs
* Added more unit tests
* Found bug in dart's Math.Random(), reported, waiting for fix to fix my code.

v0.0.2

* Initial tests
* Fixed some parser bugs.

v0.0.1

* Initial Release
* No tests