#37813

Committed 20 Jun 2024 03:55AM UTC coverage: 87.073% (-0.4%) from 87.495%

Build # #37813

Build Type

push

local

Committed by

web-flow

Commit Message

Update NEWS.md introducing FieldError exception (#54843)

A new Fielderror exception is introduced in #54504 to raise/handle
exceptions from `getfield`.

Run Details

76812 of 88216 relevant lines covered (87.07%)

15347676.52 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

10.26

/stdlib/UUIDs/src/UUIDs.jl

# This file is a part of Julia. License is MIT: https://julialang.org/license

"""
This module provides universally unique identifiers (UUIDs),
along with functions creating the different variants.
"""
module UUIDs

using Random

import SHA

export UUID, uuid1, uuid4, uuid5, uuid7, 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)

# Some UUID namespaces provided in the appendix of RFC 4122
# https://tools.ietf.org/html/rfc4122.html#appendix-C
const namespace_dns  = UUID(0x6ba7b8109dad11d180b400c04fd430c8) # 6ba7b810-9dad-11d1-80b4-00c04fd430c8
const namespace_url  = UUID(0x6ba7b8119dad11d180b400c04fd430c8) # 6ba7b811-9dad-11d1-80b4-00c04fd430c8
const namespace_oid  = UUID(0x6ba7b8129dad11d180b400c04fd430c8) # 6ba7b812-9dad-11d1-80b4-00c04fd430c8
const namespace_x500 = UUID(0x6ba7b8149dad11d180b400c04fd430c8) # 6ba7b814-9dad-11d1-80b4-00c04fd430c8

"""
    uuid1([rng::AbstractRNG]) -> 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.

The default rng used by `uuid1` is not `Random.default_rng()` and every invocation of `uuid1()` without
an argument should be expected to return a unique identifier. Importantly, the outputs of
`uuid1` do not repeat even when `Random.seed!(seed)` is called. Currently (as of Julia 1.6),
`uuid1` uses `Random.RandomDevice` as the default rng. However, this is an implementation
detail that may change in the future.

!!! compat "Julia 1.6"
    The output of `uuid1` does not depend on `Random.default_rng()` as of Julia 1.6.

# Examples
```jldoctest; filter = r"[a-z0-9]{8}-([a-z0-9]{4}-){3}[a-z0-9]{12}"
julia> using Random

julia> rng = MersenneTwister(1234);

julia> uuid1(rng)
UUID("cfc395e8-590f-11e8-1f13-43a2532b2fa8")
```
"""
function uuid1(rng::AbstractRNG=Random.RandomDevice())
    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]) -> UUID

Generates a version 4 (random or pseudo-random) universally unique identifier (UUID),
as specified by RFC 4122.

The default rng used by `uuid4` is not `Random.default_rng()` and every invocation of `uuid4()` without
an argument should be expected to return a unique identifier. Importantly, the outputs of
`uuid4` do not repeat even when `Random.seed!(seed)` is called. Currently (as of Julia 1.6),
`uuid4` uses `Random.RandomDevice` as the default rng. However, this is an implementation
detail that may change in the future.

!!! compat "Julia 1.6"
    The output of `uuid4` does not depend on `Random.default_rng()` as of Julia 1.6.

# Examples
```jldoctest
julia> using Random

julia> rng = Xoshiro(123);

julia> uuid4(rng)
UUID("856e446e-0c6a-472a-9638-f7b8557cd282")
```
"""
function uuid4(rng::AbstractRNG=Random.RandomDevice())
    u = rand(rng, UInt128)
    u &= 0xffffffffffff0fff3fffffffffffffff
    u |= 0x00000000000040008000000000000000
    UUID(u)
end

"""
    uuid5(ns::UUID, name::String) -> UUID

Generates a version 5 (namespace and domain-based) universally unique identifier (UUID),
as specified by RFC 4122.

!!! compat "Julia 1.1"
    This function requires at least Julia 1.1.

# Examples
```jldoctest
julia> using Random

julia> rng = Xoshiro(123);

julia> u4 = uuid4(rng)
UUID("856e446e-0c6a-472a-9638-f7b8557cd282")

julia> u5 = uuid5(u4, "julia")
UUID("2df91e3f-da06-5362-a6fe-03772f2e14c9")
```
"""
function uuid5(ns::UUID, name::String)
    nsbytes = zeros(UInt8, 16)
    nsv = ns.value
    for idx in Base.OneTo(16)
        nsbytes[idx] = nsv >> 120
        nsv = nsv << 8
    end
    hash_result = SHA.sha1(append!(nsbytes, convert(Vector{UInt8}, codeunits(unescape_string(name)))))
    # set version number to 5
    hash_result[7] = (hash_result[7] & 0x0F) | (0x50)
    hash_result[9] = (hash_result[9] & 0x3F) | (0x80)
    v = zero(UInt128)
    #use only the first 16 bytes of the SHA1 hash
    for idx in Base.OneTo(16)
        v = (v << 0x08) | hash_result[idx]
    end
    return UUID(v)
end

"""
    uuid7([rng::AbstractRNG]) -> UUID

Generates a version 7 (random or pseudo-random) universally unique identifier (UUID),
as specified by RFC 9652.

The default rng used by `uuid7` is not `Random.default_rng()` and every invocation of `uuid7()` without
an argument should be expected to return a unique identifier. Importantly, the outputs of
`uuid7` do not repeat even when `Random.seed!(seed)` is called. Currently (as of Julia 1.12),
`uuid7` uses `Random.RandomDevice` as the default rng. However, this is an implementation
detail that may change in the future.

!!! compat "Julia 1.12"
    `uuid7()` is available as of Julia 1.12.

# Examples
```jldoctest; filter = r"[a-z0-9]{8}-([a-z0-9]{4}-){3}[a-z0-9]{12}"
julia> using Random

julia> rng = Xoshiro(123);

julia> uuid7(rng)
UUID("019026ca-e086-772a-9638-f7b8557cd282")
```
"""
function uuid7(rng::AbstractRNG=Random.RandomDevice())
    bytes = rand(rng, UInt128)
    # make space for the timestamp
    bytes &= 0x0000000000000fff3fffffffffffffff
    # version & variant
    bytes |= 0x00000000000070008000000000000000

    # current time in ms, rounded to an Integer
    timestamp = round(UInt128, time() * 1e3)
    bytes |= timestamp << UInt128(80)

    return UUID(bytes)
end

end

1	# This file is a part of Julia. License is MIT: https://julialang.org/license
2
3	"""
4	This module provides universally unique identifiers (UUIDs),
5	along with functions creating the different variants.
6	"""
7	module UUIDs
8
9	using Random
10
11	import SHA
12
13	export UUID, uuid1, uuid4, uuid5, uuid7, uuid_version
14
15	import Base: UUID
16
17	"""
18	uuid_version(u::UUID) -> Int
19
20	Inspects the given UUID and returns its version
21	(see [RFC 4122](https://www.ietf.org/rfc/rfc4122)).
22
23	# Examples
24	```jldoctest
25	julia> uuid_version(uuid4())
26	4
27	```
28	"""
29	uuid_version(u::UUID) = Int((u.value >> 76) & 0xf)	×
30
31	# Some UUID namespaces provided in the appendix of RFC 4122
32	# https://tools.ietf.org/html/rfc4122.html#appendix-C
33	const namespace_dns = UUID(0x6ba7b8109dad11d180b400c04fd430c8) # 6ba7b810-9dad-11d1-80b4-00c04fd430c8
34	const namespace_url = UUID(0x6ba7b8119dad11d180b400c04fd430c8) # 6ba7b811-9dad-11d1-80b4-00c04fd430c8
35	const namespace_oid = UUID(0x6ba7b8129dad11d180b400c04fd430c8) # 6ba7b812-9dad-11d1-80b4-00c04fd430c8
36	const namespace_x500 = UUID(0x6ba7b8149dad11d180b400c04fd430c8) # 6ba7b814-9dad-11d1-80b4-00c04fd430c8
37
38	"""
39	uuid1([rng::AbstractRNG]) -> UUID
40
41	Generates a version 1 (time-based) universally unique identifier (UUID), as specified
42	by RFC 4122. Note that the Node ID is randomly generated (does not identify the host)
43	according to section 4.5 of the RFC.
44
45	The default rng used by `uuid1` is not `Random.default_rng()` and every invocation of `uuid1()` without
46	an argument should be expected to return a unique identifier. Importantly, the outputs of
47	`uuid1` do not repeat even when `Random.seed!(seed)` is called. Currently (as of Julia 1.6),
48	`uuid1` uses `Random.RandomDevice` as the default rng. However, this is an implementation
49	detail that may change in the future.
50
51	!!! compat "Julia 1.6"
52	The output of `uuid1` does not depend on `Random.default_rng()` as of Julia 1.6.
53
54	# Examples
55	```jldoctest; filter = r"[a-z0-9]{8}-([a-z0-9]{4}-){3}[a-z0-9]{12}"
56	julia> using Random
57
58	julia> rng = MersenneTwister(1234);
59
60	julia> uuid1(rng)
61	UUID("cfc395e8-590f-11e8-1f13-43a2532b2fa8")
62	```
63	"""
64	function uuid1(rng::AbstractRNG=Random.RandomDevice())	×
65	u = rand(rng, UInt128)	×
66
67	# mask off clock sequence and node
68	u &= 0x00000000000000003fffffffffffffff	×
69
70	# set the unicast/multicast bit and version
71	u \|= 0x00000000000010000000010000000000	×
72
73	# 0x01b21dd213814000 is the number of 100 nanosecond intervals
74	# between the UUID epoch and Unix epoch
75	timestamp = round(UInt64, time() * 1e7) + 0x01b21dd213814000	×
76	ts_low = timestamp & typemax(UInt32)	×
77	ts_mid = (timestamp >> 32) & typemax(UInt16)	×
78	ts_hi = (timestamp >> 48) & 0x0fff	×
79
80	u \|= UInt128(ts_low) << 96	×
81	u \|= UInt128(ts_mid) << 80	×
82	u \|= UInt128(ts_hi) << 64	×
83
84	UUID(u)	×
85	end
86
87	"""
88	uuid4([rng::AbstractRNG]) -> UUID
89
90	Generates a version 4 (random or pseudo-random) universally unique identifier (UUID),
91	as specified by RFC 4122.
92
93	The default rng used by `uuid4` is not `Random.default_rng()` and every invocation of `uuid4()` without
94	an argument should be expected to return a unique identifier. Importantly, the outputs of
95	`uuid4` do not repeat even when `Random.seed!(seed)` is called. Currently (as of Julia 1.6),
96	`uuid4` uses `Random.RandomDevice` as the default rng. However, this is an implementation
97	detail that may change in the future.
98
99	!!! compat "Julia 1.6"
100	The output of `uuid4` does not depend on `Random.default_rng()` as of Julia 1.6.
101
102	# Examples
103	```jldoctest
104	julia> using Random
105
106	julia> rng = Xoshiro(123);
107
108	julia> uuid4(rng)
109	UUID("856e446e-0c6a-472a-9638-f7b8557cd282")
110	```
111	"""
112	function uuid4(rng::AbstractRNG=Random.RandomDevice())
113	u = rand(rng, UInt128)	86✔
114	u &= 0xffffffffffff0fff3fffffffffffffff	43✔
115	u \|= 0x00000000000040008000000000000000	43✔
116	UUID(u)	43✔
117	end
118
119	"""
120	uuid5(ns::UUID, name::String) -> UUID
121
122	Generates a version 5 (namespace and domain-based) universally unique identifier (UUID),
123	as specified by RFC 4122.
124
125	!!! compat "Julia 1.1"
126	This function requires at least Julia 1.1.
127
128	# Examples
129	```jldoctest
130	julia> using Random
131
132	julia> rng = Xoshiro(123);
133
134	julia> u4 = uuid4(rng)
135	UUID("856e446e-0c6a-472a-9638-f7b8557cd282")
136
137	julia> u5 = uuid5(u4, "julia")
138	UUID("2df91e3f-da06-5362-a6fe-03772f2e14c9")
139	```
140	"""
141	function uuid5(ns::UUID, name::String)	×
142	nsbytes = zeros(UInt8, 16)	×
143	nsv = ns.value	×
144	for idx in Base.OneTo(16)	×
145	nsbytes[idx] = nsv >> 120	×
146	nsv = nsv << 8	×
147	end	×
148	hash_result = SHA.sha1(append!(nsbytes, convert(Vector{UInt8}, codeunits(unescape_string(name)))))	×
149	# set version number to 5
150	hash_result[7] = (hash_result[7] & 0x0F) \| (0x50)	×
151	hash_result[9] = (hash_result[9] & 0x3F) \| (0x80)	×
152	v = zero(UInt128)	×
153	#use only the first 16 bytes of the SHA1 hash
154	for idx in Base.OneTo(16)	×
155	v = (v << 0x08) \| hash_result[idx]	×
156	end	×
157	return UUID(v)	×
158	end
159
160	"""
161	uuid7([rng::AbstractRNG]) -> UUID
162
163	Generates a version 7 (random or pseudo-random) universally unique identifier (UUID),
164	as specified by RFC 9652.
165
166	The default rng used by `uuid7` is not `Random.default_rng()` and every invocation of `uuid7()` without
167	an argument should be expected to return a unique identifier. Importantly, the outputs of
168	`uuid7` do not repeat even when `Random.seed!(seed)` is called. Currently (as of Julia 1.12),
169	`uuid7` uses `Random.RandomDevice` as the default rng. However, this is an implementation
170	detail that may change in the future.
171
172	!!! compat "Julia 1.12"
173	`uuid7()` is available as of Julia 1.12.
174
175	# Examples
176	```jldoctest; filter = r"[a-z0-9]{8}-([a-z0-9]{4}-){3}[a-z0-9]{12}"
177	julia> using Random
178
179	julia> rng = Xoshiro(123);
180
181	julia> uuid7(rng)
182	UUID("019026ca-e086-772a-9638-f7b8557cd282")
183	```
184	"""
185	function uuid7(rng::AbstractRNG=Random.RandomDevice())	×
186	bytes = rand(rng, UInt128)	×
187	# make space for the timestamp
188	bytes &= 0x0000000000000fff3fffffffffffffff	×
189	# version & variant
190	bytes \|= 0x00000000000070008000000000000000	×
191
192	# current time in ms, rounded to an Integer
193	timestamp = round(UInt128, time() * 1e3)	×
194	bytes \|= timestamp << UInt128(80)	×
195
196	return UUID(bytes)	×
197	end
198
199	end

JuliaLang / julia / #37813

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous