create UUIDs stdlib package (#25819)

closes #25590

Author: JeffBezanson

base/deprecated.jl

@@ -496,6 +496,9 @@ end
 # related items to remove in: abstractarray.jl, dates/periods.jl, compiler.jl
 # also remove all uses of is_default_method
 
+@deprecate convert(::Type{UInt128},     u::UUID)     UInt128(u)
+@deprecate convert(::Type{UUID}, s::AbstractString)  UUID(s)
+
 # Issue #19923
 @deprecate ror                  circshift
 @deprecate ror!                 circshift!

base/uuid.jl

@@ -23,23 +23,6 @@ function convert(::Type{NTuple{4, UInt32}}, uuid::UUID)
     return (hh, hl, lh, ll)
 end
 
-# TODO: update documentation for new location
-"""
-    uuid_version(u::UUID) -> Int
-
-Inspects the given UUID and returns its version
-(see [RFC 4122](https://www.ietf.org/rfc/rfc4122)).
-
-# Examples
-```jldoctest
-julia> rng = MersenneTwister(1234);
-
-julia> Random.uuid_version(Random.uuid4(rng))
-4
-```
-"""
-uuid_version(u::UUID) = Int((u.value >> 76) & 0xf)
-
 UInt128(u::UUID) = u.value
 
 let groupings = [1:8; 10:13; 15:18; 20:23; 25:36]

stdlib/Random/src/deprecated.jl

@@ -16,9 +16,6 @@ end
 
 @deprecate randjump(mt::MersenneTwister, jumps::Integer)  randjump(mt, big(10)^20, jumps)
 
-@deprecate convert(::Type{UInt128},     u::UUID)     UInt128(u)
-@deprecate convert(::Type{UUID}, s::AbstractString)  UUID(s)
-
 # PR #25429
 @deprecate rand(r::AbstractRNG, dims::Dims) rand(r, Float64, dims)
 @deprecate rand(                dims::Dims) rand(Float64, dims)

stdlib/Random/src/misc.jl

@@ -341,67 +341,3 @@ function randcycle!(r::AbstractRNG, a::Array{<:Integer})
 end
 
 randcycle!(a::Array{<:Integer}) = randcycle!(GLOBAL_RNG, a)
-
-
-## random UUID generation
-
-import Base: UUID, uuid_version
-
-"""
-    uuid1([rng::AbstractRNG=GLOBAL_RNG]) -> UUID
-
-Generates a version 1 (time-based) universally unique identifier (UUID), as specified
-by RFC 4122. Note that the Node ID is randomly generated (does not identify the host)
-according to section 4.5 of the RFC.
-
-# Examples
-```jldoctest
-julia> rng = MersenneTwister(1234);
-
-julia> Random.uuid1(rng)
-2cc938da-5937-11e7-196e-0f4ef71aa64b
-```
-"""
-function uuid1(rng::AbstractRNG=GLOBAL_RNG)
-    u = rand(rng, UInt128)
-
-    # mask off clock sequence and node
-    u &= 0x00000000000000003fffffffffffffff
-
-    # set the unicast/multicast bit and version
-    u |= 0x00000000000010000000010000000000
-
-    # 0x01b21dd213814000 is the number of 100 nanosecond intervals
-    # between the UUID epoch and Unix epoch
-    timestamp = round(UInt64, time() * 1e7) + 0x01b21dd213814000
-    ts_low = timestamp & typemax(UInt32)
-    ts_mid = (timestamp >> 32) & typemax(UInt16)
-    ts_hi = (timestamp >> 48) & 0x0fff
-
-    u |= UInt128(ts_low) << 96
-    u |= UInt128(ts_mid) << 80
-    u |= UInt128(ts_hi) << 64
-
-    UUID(u)
-end
-
-"""
-    uuid4([rng::AbstractRNG=GLOBAL_RNG]) -> UUID
-
-Generates a version 4 (random or pseudo-random) universally unique identifier (UUID),
-as specified by RFC 4122.
-
-# Examples
-```jldoctest
-julia> rng = MersenneTwister(1234);
-
-julia> Random.uuid4(rng)
-82015f10-44cc-4827-996e-0f4ef71aa64b
-```
-"""
-function uuid4(rng::AbstractRNG=GLOBAL_RNG)
-    u = rand(rng, UInt128)
-    u &= 0xffffffffffff0fff3fffffffffffffff
-    u |= 0x00000000000040008000000000000000
-    UUID(u)
-end

stdlib/Random/test/runtests.jl

@@ -236,22 +236,6 @@ for U in (Int64, UInt64)
 end
 
 
-import Random: uuid1, uuid4, UUID, uuid_version
-
-# UUID
-u1 = uuid1()
-u4 = uuid4()
-@test uuid_version(u1) == 1
-@test uuid_version(u4) == 4
-@test u1 == UUID(string(u1)) == UUID(GenericString(string(u1)))
-@test u4 == UUID(string(u4)) == UUID(GenericString(string(u4)))
-@test u1 == UUID(UInt128(u1))
-@test u4 == UUID(UInt128(u4))
-@test uuid4(MersenneTwister(0)) == uuid4(MersenneTwister(0))
-@test_throws ArgumentError UUID("550e8400e29b-41d4-a716-446655440000")
-@test_throws ArgumentError UUID("550e8400e29b-41d4-a716-44665544000098")
-@test_throws ArgumentError UUID("z50e8400-e29b-41d4-a716-446655440000")
-
 #issue 8257
 let i8257 = 1:1/3:100
     for i = 1:100

stdlib/UUIDs/docs/src/index.md

@@ -0,0 +1,7 @@
+# UUIDs
+
+```@docs
+UUIDs.uuid1
+UUIDs.uuid4
+UUIDs.uuid_version
+```

stdlib/UUIDs/src/UUIDs.jl

@@ -0,0 +1,82 @@
+module UUIDs
+
+using Random
+
+export UUID, uuid1, uuid4, uuid_version
+
+import Base: UUID
+
+"""
+    uuid_version(u::UUID) -> Int
+
+Inspects the given UUID and returns its version
+(see [RFC 4122](https://www.ietf.org/rfc/rfc4122)).
+
+# Examples
+```jldoctest
+julia> uuid_version(uuid4())
+4
+```
+"""
+uuid_version(u::UUID) = Int((u.value >> 76) & 0xf)
+
+"""
+    uuid1([rng::AbstractRNG=GLOBAL_RNG]) -> UUID
+
+Generates a version 1 (time-based) universally unique identifier (UUID), as specified
+by RFC 4122. Note that the Node ID is randomly generated (does not identify the host)
+according to section 4.5 of the RFC.
+
+# Examples
+```jldoctest
+julia> rng = MersenneTwister(1234);
+
+julia> uuid1(rng)
+2cc938da-5937-11e7-196e-0f4ef71aa64b
+```
+"""
+function uuid1(rng::AbstractRNG=Random.GLOBAL_RNG)
+    u = rand(rng, UInt128)
+
+    # mask off clock sequence and node
+    u &= 0x00000000000000003fffffffffffffff
+
+    # set the unicast/multicast bit and version
+    u |= 0x00000000000010000000010000000000
+
+    # 0x01b21dd213814000 is the number of 100 nanosecond intervals
+    # between the UUID epoch and Unix epoch
+    timestamp = round(UInt64, time() * 1e7) + 0x01b21dd213814000
+    ts_low = timestamp & typemax(UInt32)
+    ts_mid = (timestamp >> 32) & typemax(UInt16)
+    ts_hi = (timestamp >> 48) & 0x0fff
+
+    u |= UInt128(ts_low) << 96
+    u |= UInt128(ts_mid) << 80
+    u |= UInt128(ts_hi) << 64
+
+    UUID(u)
+end
+
+"""
+    uuid4([rng::AbstractRNG=GLOBAL_RNG]) -> UUID
+
+Generates a version 4 (random or pseudo-random) universally unique identifier (UUID),
+as specified by RFC 4122.
+
+# Examples
+```jldoctest
+julia> rng = MersenneTwister(1234);
+
+julia> uuid4(rng)
+82015f10-44cc-4827-996e-0f4ef71aa64b
+```
+"""
+function uuid4(rng::AbstractRNG=Random.GLOBAL_RNG)
+    u = rand(rng, UInt128)
+    u &= 0xffffffffffff0fff3fffffffffffffff
+    u |= 0x00000000000040008000000000000000
+    UUID(u)
+end
+
+end

stdlib/UUIDs/test/runtests.jl

@@ -0,0 +1,14 @@
+using UUIDs, Random
+
+u1 = uuid1()
+u4 = uuid4()
+@test uuid_version(u1) == 1
+@test uuid_version(u4) == 4
+@test u1 == UUID(string(u1)) == UUID(GenericString(string(u1)))
+@test u4 == UUID(string(u4)) == UUID(GenericString(string(u4)))
+@test u1 == UUID(UInt128(u1))
+@test u4 == UUID(UInt128(u4))
+@test uuid4(MersenneTwister(0)) == uuid4(MersenneTwister(0))
+@test_throws ArgumentError UUID("550e8400e29b-41d4-a716-446655440000")
+@test_throws ArgumentError UUID("550e8400e29b-41d4-a716-44665544000098")
+@test_throws ArgumentError UUID("z50e8400-e29b-41d4-a716-446655440000")