Table of Contents
diff --git a/tplx/sprigx/README.md b/tplx/sprigx/README.md
index 970a999..e5e3c49 100644
--- a/tplx/sprigx/README.md
+++ b/tplx/sprigx/README.md
@@ -6,7 +6,7 @@
Brent Saner
-
Last rendered 2026-02-11 10:21:41 -0500
+
Last rendered 2026-02-20 12:41:34 -0500
diff --git a/uuidx/funcs.go b/uuidx/funcs.go
index 659f095..eaacdbc 100644
--- a/uuidx/funcs.go
+++ b/uuidx/funcs.go
@@ -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