Module uuid
ballerina/uuid Ballerina library
Overview
This module provides APIs to generate and inspect UUIDs (Universally Unique Identifiers) based on the RFC 4122 standard, supporting four UUID versions.
Key Features
- Generate UUIDs using four different versions (MAC address/time, MD5 hash, random, SHA-1 hash)
- Validate UUID strings and determine their version
The UUIDs are generated based on the RFC 4122 standard. This module supports generating 4 versions of UUIDs.
Version 1
Generated using the MAC address of the computer and the time of generation.
Version 3
Cryptographic hashing and application-provided text strings are used to generate a UUID. MD5 hashing is used.
Version 4
Uses a pseudo-random number generator to generate the UUID. Every bit of the string is randomly generated.
Version 5
Similar to Version 3 but uses SHA-1 instead of MD5.
Other operations include validating a given UUID string and getting the version of a UUID string.
Functions
createRandomUuid
function createRandomUuid() returns stringReturns a UUID of type 4 as a string. This function provides a convenient alias for 'createType4AsString()'.
string newUUID = uuid:createRandomUuid();
Return Type
- string - UUID of type 4 as a string
createType1AsRecord
Returns a UUID of type 1 as a UUID record.
uuid:Uuid uuid1 = check uuid:createType1AsRecord();
createType1AsString
function createType1AsString() returns stringReturns a UUID of type 1 as a string.
string uuid1 = uuid:createType1AsString();
Return Type
- string - UUID of type 1 as a string
createType3AsRecord
function createType3AsRecord(NamespaceUUID namespace, string name) returns Uuid|ErrorReturns a UUID of type 3 as a UUID record.
uuid:Uuid uuid3 = check uuid:createType3AsRecord(uuid:NAME_SPACE_DNS, “ballerina.io”);
Parameters
- namespace NamespaceUUID - String representation for a pre-defined namespace UUID
- name string - A name within the namespace
createType3AsString
function createType3AsString(NamespaceUUID namespace, string name) returns string|ErrorReturns a UUID of type 3 as a string.
string uuid3 = check uuid:createType3AsString(uuid:NAME_SPACE_DNS, “ballerina.io”);
Parameters
- namespace NamespaceUUID - String representation for a pre-defined namespace UUID
- name string - A name within the namespace
createType4AsRecord
Returns a UUID of type 4 as a UUID record.
uuid:Uuid uuid4 = check uuid:createType4AsRecord();
createType4AsString
function createType4AsString() returns stringReturns a UUID of type 4 as a string.
string uuid4 = uuid:createType4AsString();
Return Type
- string - UUID of type 4 as a string
createType5AsRecord
function createType5AsRecord(NamespaceUUID namespace, string name) returns Uuid|ErrorReturns a UUID of type 5 as a UUID record.
uuid:Uuid uuid5 = check uuid:createType5AsRecord(uuid:NAME_SPACE_DNS, “ballerina.io”);
Parameters
- namespace NamespaceUUID - String representation for a pre-defined namespace UUID
- name string - A name within the namespace
createType5AsString
function createType5AsString(NamespaceUUID namespace, string name) returns string|ErrorReturns a UUID of type 5 as a string.
string uuid5 = check uuid:createType5AsString(uuid:NAME_SPACE_DNS, “ballerina.io”);
Parameters
- namespace NamespaceUUID - String representation for a pre-defined namespace UUID
- name string - A name within the namespace
getVersion
Detect RFC version of a UUID. Returns an error if the UUID is invalid.
uuid:Version v = check uuid:getVersion("4397465e-35f9-11eb-adc1-0242ac120002");
Parameters
- uuid string - UUID string to be checked
nilAsRecord
function nilAsRecord() returns UuidReturns a nil UUID as a UUID record.
uuid:Uuid nilUUID = uuid:nilAsRecord();
Return Type
- Uuid - nil UUID as a UUID record
nilAsString
function nilAsString() returns stringReturns a nil UUID as a string.
string nilUUID = uuid:nilAsString();
Return Type
- string - nil UUID as a string
toBytes
Converts to an array of bytes. Returns an error if the UUID is invalid.
byte[] b = check uuid:toBytes(“6ec0bd7f-11c0-43da-975e-2aesass0b”);
Return Type
- byte[]|Error - UUID as bytes, or else a
uuid:Error
toRecord
Converts to a UUID record. Returns an error if the UUID is invalid.
uuid:Uuid r1 = check uuid:toRecord("4397465e-35f9-11eb-adc1-0242ac120002"); uuid:Uuid r2 = check uuid:toRecord([10, 20, 30]);
Parameters
- uuid string|byte[] - UUID to be converted
toString
Converts to a UUID string. Returns an error if the UUID is invalid.
string s = check uuid:toString([5, 12, 16, 35]);
Parameters
- uuid byte[]|Uuid - UUID to be converted
validate
Test a string to see if it is a valid UUID.
boolean valid = uuid:validate("4397465e-35f9-11eb-adc1-0242ac120002");
Parameters
- uuid string - UUID string to be validated
Return Type
- boolean - true if a valid UUID, false if not
Enums
uuid: NamespaceUUID
Represents UUIDs strings of well known namespace IDs.
Members
uuid: Version
Represents the UUID versions.
Members
Records
uuid: Uuid
Represents a UUID.
Fields
- timeLow Unsigned32 - The low field of the timestamp
- timeMid Unsigned16 - The middle field of the timestamp
- timeHiAndVersion Unsigned16 - The high field of the timestamp multiplexed with the version number
- clockSeqHiAndReserved Unsigned8 - The high field of the clock sequence multiplexed with the variant
- clockSeqLo Unsigned8 - The low field of the clock sequence
- node int - The spatially unique node identifier
Errors
uuid: Error
Represents UUID module related errors.