r00t2/go_goutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

v1.16.8

Browse Source 
CLEANUP:
* Docs for uuidx needed to be tweaked/clarified a little bit.
This commit is contained in:
brent saner
2026-02-20 12:41:29 -05:00
parent 1eea0c2672
commit 4770052b52
3 changed files with 40 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
uuidx/funcs.go
View File

@@ -42,9 +42,10 @@ COM interfaces are all OVER the place in UUID version, but usually *not* UUIDv4.
A target/expected UUID version can be provided via tgtVer. To disable version analysis, use 0 (or 0x00, etc.).
It is *highly* recommended to provide a tgtVer if it is known; it can significantly boost confidence in the correct direction.
A warning, though - if a *wrong* tgtVer IS specified, it can negatively affect confidence accuracy.
A warning, though - if a tgtVer IS specified but is wrong (e.g. a UUIDv1 was passed in but tgtVer was specified as 4 for UUIDv4),
it can *negatively* affect confidence accuracy.
Thus if you aren't ABSOLUTELY certain of the target UUID version, it's better to use 0/0x00 to disable the check.
Providing a target version is key to breaking some ties (e.g. both cs and csFlip are equal).
Providing a target version can be key to breaking some "ties" (e.g. both cs and csFlip are equal).
For example, the given RFC-compliant UUIDv4:
8d8e35ae-58d2-4d28-b09d-ffffffffffff
@@ -67,21 +68,22 @@ which results in a cs == 1 and csFlip == 0 - not very high confidence (but at le
Providing a tgtVer == 4 changes this to cs == 7 and csFlip == 0, which is *much* more decisive.
UUIDs/GUIDs found to be strictly RFC-conforming (via [IsRfc], which returns false for Microsoft GUIDs)
are *heavily* weighted negatively.
are *heavily* weighted negatively in their respective scoring forms.
Confidence levels can be generally considered as the following:
cs >= 7: Likely Microsoft GUID (mixed-endian)
cs >= 4: Likely Microsoft GUID
0 < cs < 4: Leans Microsoft GUID, but untrusted
cs == 0: Entirely ambiguous/indeterminate
-4 < cs < 0: Leans UUID/non-Microsoft GUID but untrusted
cs <= -5: Likely UUID/not Microsoft GUID
csFlip >=cs && csFlip >= 4: Likely a pre-flipped (ToggleUuidMsGuid'd) Microsoft GUID
* cs >= 7: Likely Microsoft GUID (mixed-endian)
* cs >= 4: Likely Microsoft GUID
* 0 < cs < 4: Leans Microsoft GUID, but untrusted/ambiguous
* cs == 0: Entirely and completely ambiguous/indeterminate
* -4 < cs < 0: Leans UUID/non-Microsoft GUID but untrusted/ambiguous
* cs <= -5: Likely UUID/not Microsoft GUID
* csFlip >= cs && csFlip >= 4: u is likely a pre-flipped (ToggleUuidMsGuid'd) Microsoft GUID
(i.e. u is likely directly from a Microsoft API/ data source
and no normalization has occurred yet)
[§ 4.2]: https://datatracker.ietf.org/doc/html/rfc9562#section-4.2
*/
func DetectMsGuid(u uuid.UUID, tgtVer uuid.Version) (cs, csFlip int) {
var isRfc bool
@@ -168,7 +170,7 @@ func DetectMsGuid(u uuid.UUID, tgtVer uuid.Version) (cs, csFlip int) {
}
/*
Equal returns `true` if [uuid.UUID] the two provided [uuid.UUID] are the same.
Equal returns `true` if the two provided [uuid.UUID] are the same.
Currently it just wraps:
@@ -228,7 +230,9 @@ and in MODERN implementations do the endianness flip [ToggleUuidMsGuid] of (USUA
See [DetectMsGuid] for a more in-depth result that will let you use the confidence level directly,
and for details on the weird things that can go wrong with this guesswork.
Note that this won't be 100% reliable due to math things, but it should be reliable enough most of the time.
Note that this won't be 100% reliable due to math things, but it should be ...somewhat reliable
enough most of the time. Maybe. But you are *strongly* recommended to use [DetectMsGuid] instead
wherever possible.
See also [MsGuidToUuid] and [UuidToMsGuid].
*/
@@ -282,9 +286,10 @@ of an RFC UUID. Use [IsMsGuid] for that.
In the special case of u being a valid NCS UUID, rfc will be false but gen will be [Rfc4122].
This is because RFC 9652 deprecates the NCS UUID. See [IsNcs].
(You are highly unlikely to encounter an NCS UUID "in the wild" unless you are receiving
a UUID from someone who severely misunderstands that UUIDs are structured/versioned/typed
and thinks they're just random byes in hex with hyphens in certain places.)
(You are highly unlikely to encounter an NCS UUID "in the wild" unless you are working
with VERY old systems/data or are receiving a UUID from someone who severely
misunderstands that UUIDs are structured/versioned/typed and thinks they're
just random byes in hex with hyphens in certain places.)
(They aren't that, if you're one of those someones.)
Nil UUID ([IsNilUUID]) and Max UUID ([IsMaxUUID]) return true with RFCs 4122 and RFC 9562 respectively.
@@ -391,6 +396,9 @@ If [IsMsGuid] is false for msGUID, u will be equal to msGUID.
See [UuidToMsGuid] for the inverse, and [IsRfc] to check
if the result is a strictly conforming UUID.
Use [ToggleUuidMsGuid] if you want msGUID explicitly flipped
with no gating from [IsMsGuid].
*/
func MsGuidToUuid(msGUID uuid.UUID) (u uuid.UUID) {
@@ -441,10 +449,18 @@ func ToggleUuidMsGuid(orig uuid.UUID) (converted uuid.UUID) {
UuidToMsGuid converts a UUID to a Microsoft GUID.
If [DetectMsGuid] indicates a good likelihood for u already being a Microsoft GUID
(greater than or equal) to [MsGuidThreshold], msGUID will be equal to u.
(If it detects it as unflipped endianness, it will automatically be flipped by this function.)
(cs being greater than or equal to [MsGuidThreshold]), msGUID will be equal to u.
If [DetectMsGuid] detects it as a Microsoft unflipped endianness (i.e. csFlip > cs),
msGUID will be the [ToggleUuidMsGuid]-flipped format of u UNLESS u.Variant == [uuid.Microsoft].
Thus this function *should* (with plenty of caveats mentioned elsewhere in other functions/documentation)
be usable for flipping a purely non-Microsoft-tainted RFC-conforming UUID, and not flipping it otherwise
as it's already a "Microsoft GUID" of some generation (either legacy or newer).
See [MsGuidToUuid] for the inverse.
Use [ToggleUuidMsGuid] if you want u explicitly flipped with no gating from [DetectMsGuid] or
via u's [uuid.Variant].
*/
func UuidToMsGuid(u uuid.UUID) (msGUID uuid.UUID) {
@@ -455,6 +471,10 @@ func UuidToMsGuid(u uuid.UUID) (msGUID uuid.UUID) {
msGUID = u
return
}
if u.Variant == uuid.Microsoft {
msGUID = u
return
}
msGUID = ToggleUuidMsGuid(u)
return