SnowBank SDK SnowBank SDK
EN

VersionStamp

Namespace: System · struct

Implements: IEquatable<VersionStamp>, IComparable<VersionStamp>, IComparable, IJsonSerializable, IJsonPackable, IJsonDeserializable<VersionStamp>, ISpanEncodable, IEquatable<Uuid80>, IComparable<Uuid80>, IEquatable<Uuid96>, IComparable<Uuid96>, ISpanFormattable, IFormattable, ISpanParsable<VersionStamp>, IParsable<VersionStamp>, IUtf8SpanFormattable, IUtf8SpanParsable<VersionStamp>

VersionStamp

Remarks

A VersionStamp is unique, monotonically (but not sequentially) increasing value for each committed transaction. Its size can either be 10 bytes (80-bits) or 12-bytes (96-bits). The first 8 bytes are the committed version of the database. The next 2 bytes are monotonic in the serialization order for transactions. The optional last 2 bytes can contain a user-provider version number used to allow multiple stamps inside the same transaction.

Properties

HasUserVersion

bool HasUserVersion { get; }

Test if the stamp has a user version (96-bits) or not (80-bits)

IsIncomplete

bool IsIncomplete { get; }

Test if the stamp is marked as incomplete (true), or has already been resolved by the database (false)

Methods

CompareTo

int CompareTo(Uuid80 other)

int CompareTo(Uuid96 other)

int CompareTo(object other)

int CompareTo(VersionStamp other)

Complete

static VersionStamp Complete(ulong version, ushort order)

Creates an 80-bit VersionStamp, obtained from the database.

Returns: Complete stamp, without user version.

static VersionStamp Complete(ulong version, ushort order, int userVersion)

Creates a 96-bit VersionStamp, obtained from the database.

Returns: Complete stamp, with a user version.

static VersionStamp Complete(ulong version, ushort order, ushort userVersion)

Creates a 96-bit VersionStamp, obtained from the database.

Returns: Complete stamp, with a user version.

Custom

static VersionStamp Custom(Uuid80 uuid, bool incomplete)

Creates an 80-bit VersionStamp.

Returns: Complete stamp, with a user version.

static VersionStamp Custom(Uuid96 uuid, bool incomplete)

Creates a 96-bit VersionStamp.

Returns: Complete stamp, with a user version.

static VersionStamp Custom(ulong version, ushort order, bool incomplete)

Creates an 80-bit VersionStamp.

Returns: Complete stamp, with a user version.

static VersionStamp Custom(Uuid80 uuid, ushort userVersion, bool incomplete)

Creates a 96-bit VersionStamp.

Returns: Complete stamp, with a user version.

static VersionStamp Custom(ulong version, ushort order, int userVersion, bool incomplete)

Creates a 96-bit VersionStamp.

Returns: Complete stamp, with a user version.

Equals

bool Equals(object obj)

bool Equals(VersionStamp other)

bool Equals(Uuid80 other)

bool Equals(Uuid96 other)

FromUuid80

static VersionStamp FromUuid80(Uuid80 value)

Converts an 80-bits UUID into an 80-bits VersionStamp

FromUuid96

static VersionStamp FromUuid96(Uuid96 value)

Converts a 96-bits UUID into a 96-bits VersionStamp

GetHashCode

int GetHashCode()

GetLength

int GetLength()

Return the length (in bytes) of the VersionStamp when serialized in binary format

Returns: Returns 12 bytes for stamps with a user version, and 10 bytes without.

Incomplete

static VersionStamp Incomplete()

Creates an incomplete 80-bit VersionStamp with no user version.

Returns: Placeholder that will be serialized as FF FF FF FF FF FF FF FF FF FF (10 bytes).

This stamp contains a temporary marker that will be later filled by the database with the actual VersionStamp at transaction commit time.

If you need to create multiple distinct stamps within the same transaction, please use Incomplete instead.

static VersionStamp Incomplete(int userVersion)

Creates an incomplete 96-bit VersionStamp with the given user version.

  • userVersion — Value between 0 and 65535 that will be appended at the end of the VersionStamp, making it unique within the transaction.

Returns: Placeholder that will be serialized as FF FF FF FF FF FF FF FF FF FF vv vv (12 bytes) where 'vv vv' is the user version encoded in little-endian.

This stamp contains a temporary marker that will be later filled by the database with the actual VersionStamp at transaction commit time.

static VersionStamp Incomplete(ushort userVersion)

Creates an incomplete 96-bit VersionStamp with the given user version.

  • userVersion — Value between 0 and 65535 that will be appended at the end of the VersionStamp, making it unique within the transaction.

Returns: Placeholder that will be serialized as FF FF FF FF FF FF FF FF FF FF vv vv (12 bytes) where 'vv vv' is the user version encoded in little-endian.

JsonDeserialize

static VersionStamp JsonDeserialize(JsonValue value, ICrystalJsonTypeResolver resolver = null)

Parse

static VersionStamp Parse(string s, IFormatProvider provider)

Parses the specified ReadOnlySpan of characters into a VersionStamp.

  • s — The span of characters to parse.
  • provider — This parameter is ignored.

Returns: VersionStamp value equivalent to the characters contained in s.

This method can parse the result of calling

static VersionStamp Parse(ReadOnlySpan<char> s, IFormatProvider provider = null)

Parses a span of characters into a VersionStamp.

  • s — The span of characters to parse.
  • provider — This parameter is ignored.

Returns: VersionStamp value equivalent to the characters contained in s.

This method can parse the result of calling or

static VersionStamp Parse(ReadOnlySpan<byte> s, IFormatProvider provider = null)

Parses a span of UTF-8 characters into a VersionStamp.

  • s — The span of characters to parse.
  • provider — This parameter is ignored.

Returns: VersionStamp value equivalent to the characters contained in s.

This method can parse the result of calling or

ParseBase1024

static VersionStamp ParseBase1024(string source)

static VersionStamp ParseBase1024(ReadOnlySpan<char> source)

ReadFrom

static VersionStamp ReadFrom(Slice data)

Reads a VersionStamp from a sequence of bytes

static VersionStamp ReadFrom(ReadOnlySpan<byte> data)

Reads a VersionStamp from a span of bytes

ReadUnsafe

static void ReadUnsafe(ReadOnlySpan<byte> buf, out VersionStamp vs)

[DANGEROUS] Reads a VersionStamp from a source buffer, that must be large enough.

ToSlice

Slice ToSlice()

Returns a newly allocated Slice that represents this VersionStamp

The slice with have a length of either 10 or 12 bytes.

ToString

string ToString()

string ToString(string format, IFormatProvider provider = null)

ToUuid80

Uuid80 ToUuid80()

Converts this 80-bits VersionStamp into an 80-bits UUID

ToUuid96

Uuid96 ToUuid96()

Converts this 96-bits VersionStamp into a 96-bits UUID

TryFormat

bool TryFormat(Span<char> destination, out int charsWritten, ReadOnlySpan<char> format = null, IFormatProvider provider = null)

Tries to format the value of the current instance into the provided span of characters.

  • destination — The span in which to write this instance's value formatted as a span of characters.
  • charsWritten — When this method returns, contains the number of characters that were written in destination.
  • format — A span containing the characters that represent a standard or custom format string that defines the acceptable format for destination.
  • provider — This parameter is ignored.

Returns: true if the formatting was successful; otherwise, false.

bool TryFormat(Span<byte> utf8Destination, out int bytesWritten, ReadOnlySpan<char> format = null, IFormatProvider provider = null)

Tries to format the value of the current instance UTF-8 into the provided span of bytes.

  • utf8Destination — The span in which to write this instance's value formatted as a span of bytes.
  • bytesWritten — When this method returns, contains the number of bytes that were written in utf8Destination.
  • format — A span containing the characters that represent a standard or custom format string that defines the acceptable format for utf8Destination.
  • provider — This parameter is ignored.

Returns: true if the formatting was successful; otherwise, false.

TryFormatBase1024

bool TryFormatBase1024(Span<char> destination, out int charsWritten)

Try formatting this VersionStamp into Base-1024 string literal

  • destination — Buffer that must have a size of at least 8 or 10 characters (depending on the value of HasUserVersion)
  • charsWritten — Number of bytes written to destination, always equal to 10

This will write 16 characters into destination that each represent a 10-bit chunk of the combined prefix and version stamp.

Each 10-bit chunk is offset by 48, so that 0b0000000000 is mapped to the '0' character.

The resulting string should preserver the sort order of the 160-bit input.

bool TryFormatBase1024(Span<byte> utf8Destination, out int bytesWritten)

TryParse

static bool TryParse(string s, IFormatProvider provider, out VersionStamp result)

Attempts to parse the specified ReadOnlySpan of characters into a VersionStamp.

  • s — The span of characters to parse.
  • provider — This parameter is ignored.
  • result — When this method returns, contains the VersionStamp value equivalent to the characters contained in s, if the conversion succeeded, or the default value if the conversion failed.

Returns: true if the s was successfully parsed; otherwise, true.

This method can parse the result of calling

static bool TryParse(ReadOnlySpan<char> s, IFormatProvider provider, out VersionStamp result)

Attempts to parse the span characters into a VersionStamp.

  • s — The span of characters to parse.
  • provider — This parameter is ignored.
  • result — When this method returns, contains the VersionStamp value equivalent to the characters contained in s, if the conversion succeeded, or the default value if the conversion failed.

Returns: true if the s was successfully parsed; otherwise, true.

This method can parse the result of calling or

static bool TryParse(ReadOnlySpan<byte> s, IFormatProvider provider, out VersionStamp result)

Attempts to parse a span of UTF-8 characters into a VersionStamp.

  • s — The span of characters to parse.
  • provider — This parameter is ignored.
  • result — When this method returns, contains the VersionStamp value equivalent to the characters contained in s, if the conversion succeeded, or the default value if the conversion failed.

Returns: true if the s was successfully parsed; otherwise, true.

This method can parse the result of calling or

TryParseBase1024

static bool TryParseBase1024(string source, out VersionStamp result)

static bool TryParseBase1024(ReadOnlySpan<char> source, out VersionStamp result)

TryReadFrom

static bool TryReadFrom(Slice data, out VersionStamp vs)

Try reading a VersionStamp from a sequence of bytes

static bool TryReadFrom(ReadOnlySpan<byte> data, out VersionStamp vs)

Attempts to read a VersionStamp from a span of bytes.

  • data — The byte sequence to parse.
  • vs — When this method returns, contains the parsed VersionStamp if the parsing succeeded, or the default value if it failed.

Returns: true if the parsing was successful; otherwise, false.

A valid is either 10 or 12 bytes long.

TryWriteTo

bool TryWriteTo(Span<byte> buffer)

Writes this VersionStamp to the specified buffer, if it is large enough.

  • buffer — Destination buffer, that must have a length of at least 10 or 12 bytes

Returns: true if the buffer was large enough; otherwise, false

bool TryWriteTo(Span<byte> buffer, out int bytesWritten)

Writes this VersionStamp to the specified buffer, if it is large enough.

  • buffer — Destination buffer, that must have a length of at least 10 or 12 bytes
  • bytesWritten — Receives the number of bytes written to buffer (either 10 or 12), if the operation is successful

Returns: true if the buffer was large enough; otherwise, false

WriteTo

int WriteTo(Span<byte> buffer)

Writes this VersionStamp to the specified buffer, if it is large enough.

  • buffer — Destination buffer, that must have a length of at least 10 or 12 bytes

int WriteTo(ref SliceWriter writer)

Writes this VersionStamp to the specified destination

Fields

None

static readonly VersionStamp None

The "empty" VersionStamp

This value will never be observed in the database, and can be used to represent the concept of null, none or empty

Please note that this is different from the Incomplete stamp, which corresponds to a stamp whose value is not yet known, but will be replaced by concrete value in the near future (usually when the transaction commits).

TransactionOrder

readonly ushort TransactionOrder

Transaction Batch Order

This value is determined by the database at commit time.

TransactionVersion

readonly ulong TransactionVersion

Commit version of the transaction

This value is determined by the database at commit time.

UserVersion

readonly ushort UserVersion

User-provided version (between 0 and 65535)

For 80-bits VersionStamps, this value will be 0 and will not be part of the serialized key. You can use to distinguish between both types of stamps.