Struct DuckDbUuid

DuckDB's (RFC 4122) encoding of a UUID (Universally Unique Identifier) as a 128-bit integer.

Implements
Inherited Members
Namespace: Mallard.Types
Assembly: Mallard.dll
Syntax
public readonly struct DuckDbUuid : ISpanFormattable, IFormattable, IUtf8SpanFormattable
Remarks

The information content this type represents is the same as the standard Guid type used in most of .NET, but in a different internal format. This type offers methods to convert between the formats.

For clarity, we describe the formats involved:

  • The canonical representation of a UUID, for the purposes here, shall be considered to be the string consisting of 32 hexadecimal digits, which is usually interpreted by humans as a big-endian 128-bit integer.
  • The DuckDB encoding splits the UUID, as a string, in the middle, into two groups of 16 hexadecimal digits. Each group is separately interpreted as a 64-bit integer in big-endian notation. Then the first group is set as the upper 64-bit word of UInt128; the second group is set as the lower 64-bit word of UInt128. Thus, the UUID is essentially read as a 128-bit integer in big-endian encoding. (See source/common/types/uuid.cpp in DuckDB's source code.)
  • The Microsoft GUID encoding is a mixed-endian encoding. For a UUID of the form aa aa aa aa - xx xx - yy yy - zz zz - bb bb bb bb bb bb (spaces and hyphens added for clarity), the first 3 groups of hexadecimal digits, namely, aa aa aa aa, xx xx and yy yy, are individually encoded as little-endian 32-bit, 16-bit and 16-bit integers, respectively. The last 2 groups of hexadecimal digits are individually encoded as big-endian 16-bit and 48-bit integers respectively.
  • The RFC 4122 format for a UUID splits the 32 hexadecimal digits into 6 fields of the following lengths in bits: 32, 16, 16, 16, 48 separated by hyphen. (This looks the same as Microsoft's GUID when formatted as a string.) Each group is interpreted as a big-endian integer. (Since there is no mixed byte-ordering, the whole UUID could be interpreted as a 128-bit big-endian integer. Thus the bit representation of a UUID in RFC 4122 is identical to DuckDB's.)

Constructors

| Edit this page View Source

DuckDbUuid(UInt128)

DuckDB's (RFC 4122) encoding of a UUID (Universally Unique Identifier) as a 128-bit integer.

Declaration
public DuckDbUuid(UInt128 value)
Parameters
Type Name Description
UInt128 value
Remarks

The information content this type represents is the same as the standard Guid type used in most of .NET, but in a different internal format. This type offers methods to convert between the formats.

For clarity, we describe the formats involved:

  • The canonical representation of a UUID, for the purposes here, shall be considered to be the string consisting of 32 hexadecimal digits, which is usually interpreted by humans as a big-endian 128-bit integer.
  • The DuckDB encoding splits the UUID, as a string, in the middle, into two groups of 16 hexadecimal digits. Each group is separately interpreted as a 64-bit integer in big-endian notation. Then the first group is set as the upper 64-bit word of UInt128; the second group is set as the lower 64-bit word of UInt128. Thus, the UUID is essentially read as a 128-bit integer in big-endian encoding. (See source/common/types/uuid.cpp in DuckDB's source code.)
  • The Microsoft GUID encoding is a mixed-endian encoding. For a UUID of the form aa aa aa aa - xx xx - yy yy - zz zz - bb bb bb bb bb bb (spaces and hyphens added for clarity), the first 3 groups of hexadecimal digits, namely, aa aa aa aa, xx xx and yy yy, are individually encoded as little-endian 32-bit, 16-bit and 16-bit integers, respectively. The last 2 groups of hexadecimal digits are individually encoded as big-endian 16-bit and 48-bit integers respectively.
  • The RFC 4122 format for a UUID splits the 32 hexadecimal digits into 6 fields of the following lengths in bits: 32, 16, 16, 16, 48 separated by hyphen. (This looks the same as Microsoft's GUID when formatted as a string.) Each group is interpreted as a big-endian integer. (Since there is no mixed byte-ordering, the whole UUID could be interpreted as a 128-bit big-endian integer. Thus the bit representation of a UUID in RFC 4122 is identical to DuckDB's.)

Methods

| Edit this page View Source

FromGuid(in Guid)

Convert from a standard .NET GUID instance.

Declaration
public static DuckDbUuid FromGuid(in Guid guid)
Parameters
Type Name Description
Guid guid

The source value to convert from.
Returns
Type Description
DuckDbUuid

An instance of DuckDbUuid that represents the same value (as a UUID) as guid.
| Edit this page View Source

GetHashCode()

Returns the hash code for this instance.

Declaration
public override int GetHashCode()
Returns
Type Description
int

A 32-bit signed integer that is the hash code for this instance.
Overrides
| Edit this page View Source

ToGuid()

Convert to a standard .NET GUID instance.

Declaration
public Guid ToGuid()
Returns
Type Description
Guid

An instance of Guid that represents the same value (as a UUID) as this instance.
| Edit this page View Source

ToString()

Returns the fully qualified type name of this instance.

Declaration
public override string ToString()
Returns
Type Description
string

The fully qualified type name.
Overrides
| Edit this page View Source

ToString(string?)

Format this UUID as a string.

Declaration
public string ToString(string? format)
Parameters
Type Name Description
string format

Format string. All of the options for formatting a Guid may be used.
Returns
Type Description
string
| Edit this page View Source

TryFormat(Span<byte>, out int, ReadOnlySpan<char>)

Format this UUID as a UTF-8 string.

Declaration
public bool TryFormat(Span<byte> utf8Destination, out int bytesWritten, ReadOnlySpan<char> format)
Parameters
Type Name Description
Span<byte> utf8Destination

The buffer to put the UTF-8 bytes into.
int bytesWritten

The number of bytes written into the buffer.
ReadOnlySpan<char> format

Format string. All of the options for formatting a Guid may be used.
Returns
Type Description
bool

True if formatting is successful. False if the buffer is too small; the caller should retry with a larger buffer.
| Edit this page View Source

TryFormat(Span<char>, out int, ReadOnlySpan<char>)

Format this UUID into a character buffer.

Declaration
public bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format)
Parameters
Type Name Description
Span<char> destination

The buffer to format into.
int charsWritten

The number of characters written into the buffer.
ReadOnlySpan<char> format

Format string. All of the options for formatting a Guid may be used.
Returns
Type Description
bool

True if formatting is successful. False if the buffer is too small; the caller should retry with a larger buffer.

Implements