Module jit-uuid
jit-uuid Fast and dependency-free UUID library for LuaJIT/ngx_lua.
Info:
- Release: 0.0.7
- License: MIT
- Author: Thibault Charbonnier
Functions
| seed (seed) | Seed the random number generator. |
| is_valid (str) | Validate a string as a UUID. |
| generate_v4 () | Generate a v4 UUID. |
| factory_v3 (namespace) | Instanciate a v3 UUID factory. |
| factory_v5 (namespace) | Instanciate a v5 UUID factory. |
| generate_v3 (namespace, name) | Generate a v3 UUID. |
| generate_v5 (namespace, name) | Generate a v5 UUID. |
Functions
- seed (seed)
-
Seed the random number generator.
Under the hood, this function calls math.randomseed.
It makes sure to use the most appropriate seeding technique for
the current environment, guaranteeing a unique seed.
To guarantee unique UUIDs, you must have correctly seeded the Lua pseudo-random generator (with math.randomseed). You are free to seed it any way you want, but this function can do it for you if you'd like, with some added guarantees.
Parameters:
- seed number (Optional) A seed to use. If none given, will generate one trying to use the most appropriate technique.
Returns:
-
number
seed: the seed given to math.randomseed.
Usage:
local uuid = require 'resty.jit-uuid' uuid.seed() -- in ngx_lua, seed in the init_worker context: init_worker_by_lua { local uuid = require 'resty.jit-uuid' uuid.seed() }
- is_valid (str)
-
Validate a string as a UUID.
To be considered valid, a UUID must be given in its canonical
form (hexadecimal digits including the hyphen characters).
This function validates UUIDs disregarding their generation algorithm,
and in a case-insensitive manner, but checks the variant field.
Use JIT PCRE if available in OpenResty or fallbacks on Lua patterns.
Parameters:
- str string String to verify.
Returns:
-
boolean
valid: true if valid UUID, false otherwise.Usage:
local uuid = require 'resty.jit-uuid' uuid.is_valid 'cbb297c0-a956-486d-ad1d-f9bZZZZZZZZZ' --> false uuid.is_valid 'cbb297c0-a956-486d-dd1d-f9b42df9465a' --> false (invalid variant) uuid.is_valid 'cbb297c0a956486dad1df9b42df9465a' --> false (no dashes) uuid.is_valid 'cbb297c0-a956-486d-ad1d-f9b42df9465a' --> true
- generate_v4 ()
-
Generate a v4 UUID.
v4 UUIDs are created from randomly generated numbers.
Returns:
-
string
uuid: a v4 (randomly generated) UUID.Usage:
local uuid = require 'resty.jit-uuid' local u1 = uuid() ---> __call metamethod local u2 = uuid.generate_v4()
- factory_v3 (namespace)
-
Instanciate a v3 UUID factory.
Parameters:
Returns:
-
function
factory: a v3 UUID generator. -
string
err: a string describing an error
Usage:
local uuid = require 'resty.jit-uuid' local fact = assert(uuid.factory_v3('e6ebd542-06ae-11e6-8e82-bba81706b27d')) local u1 = fact('hello') ---> 3db7a435-8c56-359d-a563-1b69e6802c78 local u2 = fact('foobar') ---> e8d3eeba-7723-3b72-bbc5-8f598afa6773
-
function
- factory_v5 (namespace)
-
Instanciate a v5 UUID factory.
Parameters:
Returns:
-
function
factory: a v5 UUID generator. -
string
err: a string describing an error
Usage:
local uuid = require 'resty.jit-uuid' local fact = assert(uuid.factory_v5('e6ebd542-06ae-11e6-8e82-bba81706b27d')) local u1 = fact('hello') ---> 4850816f-1658-5890-8bfd-1ed14251f1f0 local u2 = fact('foobar') ---> c9be99fc-326b-5066-bdba-dcd31a6d01ab
-
function
- generate_v3 (namespace, name)
-
Generate a v3 UUID.
v3 UUIDs are created from a namespace and a name (a UUID and a string).
The same name and namespace result in the same UUID. The same name and
different namespaces result in different UUIDs, and vice-versa.
The resulting UUID is derived using MD5 hashing.
This is a sugar function which instanciates a short-lived v3 UUID factory. It is an expensive operation, and intensive generation using the same namespaces should prefer allocating their own long-lived factory with factory_v3.
Parameters:
Returns:
Usage:
local uuid = require 'resty.jit-uuid' local u = uuid.generate_v3('e6ebd542-06ae-11e6-8e82-bba81706b27d', 'hello') ---> 3db7a435-8c56-359d-a563-1b69e6802c78
- generate_v5 (namespace, name)
-
Generate a v5 UUID.
v5 UUIDs are created from a namespace and a name (a UUID and a string).
The same name and namespace result in the same UUID. The same name and
different namespaces result in different UUIDs, and vice-versa.
The resulting UUID is derived using SHA-1 hashing.
This is a sugar function which instanciates a short-lived v5 UUID factory. It is an expensive operation, and intensive generation using the same namespaces should prefer allocating their own long-lived factory with factory_v5.
Parameters:
Returns:
Usage:
local uuid = require 'resty.jit-uuid' local u = uuid.generate_v5('e6ebd542-06ae-11e6-8e82-bba81706b27d', 'hello') ---> 4850816f-1658-5890-8bfd-1ed14251f1f0