Merge pull request #443 from ImeshBalasuriya/main

Add a more intuitive `createRandomUuid()` function

changelog.md

@@ -1,8 +1,11 @@
 # Change Log
-This file contains all the notable changes done to the Ballerina TCP package through the releases.
+This file contains all the notable changes done to the Ballerina UUID package through the releases.
 
 ## [Unreleased]
 
+### Added
+- [Add a more intuitive `createRandomUuid()` function](https://github.com/ballerina-platform/ballerina-standard-library/issues/4147)
+
 ### Changed
 - [API docs updated](https://github.com/ballerina-platform/ballerina-standard-library/issues/3463)
 

ballerina/Ballerina.toml

@@ -1,7 +1,7 @@
 [package]
 org = "ballerina"
 name = "uuid"
-version = "1.7.0"
+version = "1.7.1"
 authors = ["Ballerina"]
 keywords = ["version", "unique"]
 repository = "https://github.com/ballerina-platform/module-ballerina-uuid"

ballerina/Dependencies.toml

@@ -90,7 +90,7 @@ modules = [
 [[package]]
 org = "ballerina"
 name = "uuid"
-version = "1.7.0"
+version = "1.7.1"
 dependencies = [
 	{org = "ballerina", name = "crypto"},
 	{org = "ballerina", name = "jballerina.java"},

ballerina/tests/uuid-test.bal

@@ -82,6 +82,13 @@ isolated function testCreateType5AsRecord() {
     test:assertEquals(actualUUID, expcectedUUID);
 }
 
+@test:Config {}
+isolated function testCreateRandomUuid() {
+    string uuid = createRandomUuid();
+    test:assertEquals(uuid.length(), 36);
+    test:assertEquals(getVersion(uuid), V4);
+}
+
 @test:Config {}
 isolated function testNilAsString() {
     test:assertEquals(nilAsString(), "00000000-0000-0000-0000-000000000000");

ballerina/uuid.bal

@@ -148,6 +148,17 @@ public isolated function createType5AsRecord(NamespaceUUID namespace, string nam
     }
 }
 
+# Returns a UUID of type 4 as a string.
+# This function provides a convenient alias for 'createType4AsString()'.
+# ```ballerina
+# string newUUID = uuid:createRandomUuid();
+# ```
+#
+# + return - UUID of type 4 as a string
+public isolated function createRandomUuid() returns string {
+    return createType4AsString();
+}
+
 # Returns a nil UUID as a string.
 # ```ballerina
 # string nilUUID = uuid:nilAsString();

docs/spec/spec.md

@@ -3,7 +3,7 @@
 _Owners_: @daneshk @MadhukaHarith92  
 _Reviewers_: @daneshk  
 _Created_: 2021/11/16  
-_Updated_: 2022/02/08  
+_Updated_: 2023/10/04  
 _Edition_: Swan Lake   
 
 ## Introduction
@@ -17,16 +17,19 @@ The conforming implementation of the specification is released and included in t
 
 ## Contents
 
-1. [Overview](#1-overview)
-2. [Generating UUIDs](#2-generating-uuids)
-    * 2.1. [Version 1](#21-version-1)
-    * 2.2. [Version 3](#22-version-3)
-    * 2.3. [Version 4](#23-version-4)
-    * 2.4. [Version 5](#24-version-5)
-    * 2.5. [Nil UUID](#25-nil-uuid)
-3. [Checking the Version of UUIDs](#3-checking-the-version-of-uuids)
-4. [Validating UUIDs](#4-validating-uuids)
-5. [UUID Operations](#5-uuid-operations)
+- [Specification: Ballerina UUID Library](#specification-ballerina-uuid-library)
+  - [Introduction](#introduction)
+  - [Contents](#contents)
+  - [1. Overview](#1-overview)
+  - [2. Generating UUIDs](#2-generating-uuids)
+    - [2.1. Version 1](#21-version-1)
+    - [2.2. Version 3](#22-version-3)
+    - [2.3. Version 4](#23-version-4)
+    - [2.4. Version 5](#24-version-5)
+    - [2.5. Nil UUID](#25-nil-uuid)
+  - [3. Checking the Version of UUIDs](#3-checking-the-version-of-uuids)
+  - [4. Validating UUIDs](#4-validating-uuids)
+  - [5. UUID operations](#5-uuid-operations)
 
 ## 1. Overview
 This specification elaborates on the functions available in the UUID library.
@@ -52,6 +55,14 @@ public type Uuid readonly & record {
 };
 ```
 
+The `uuid:createRandomUuid()` function is a convenient alias for `uuid:createType4AsString()` 
+that returns a random UUID as a string.
+```ballerina
+string uuid = uuid:createRandomUuid();
+```
+This function is sufficient for most use cases. However, if a specific UUID type is required, 
+the following APIs are also available.
+
 ### 2.1. Version 1
 This is generated using the MAC address of the computer and the time of generation.