Grijjy Foundation

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

record TgoObjectId

DescriptionHierarchyFieldsMethodsProperties

Unit

Grijjy.Bson

Declaration

type TgoObjectId = record

Description

Represents an ObjectId. This is a 12-byte (96-bit) value that is regularly used for (unique) primary keys in MongoDB databases.

Internally, an ObjectId is composed of:

  • A 4-byte value containing the number of seconds since the Unix epoch.

  • A 3-byte machine identifier

  • A 2-byte process identifier

  • A 3-byte counter, starting from a random value

This makes ObjectId's fairly unique (but not as unique as GUID's though)

Overview

Fields

FData: array [0..2] of UInt32
FBytes: array [0..11] of Byte

Methods

class function Create(const ABytes: TBytes): TgoObjectId; overload; static;
class function Create(const ABytes: array of Byte): TgoObjectId; overload; static;
class function Create(const ATimestamp, AMachine: Integer; const APid: UInt16; const AIncrement: Integer): TgoObjectId; overload; static;
class function Create(const ATimestamp: TDateTime; const ATimestampIsUTC: Boolean; const AMachine: Integer; const APid: UInt16; const AIncrement: Integer): TgoObjectId; overload; static;
class function Create(const AString: String): TgoObjectId; overload; static;
class function GenerateNewId: TgoObjectId; overload; static;
class function GenerateNewId(const ATimestamp: TDateTime; const ATimestampIsUTC: Boolean): TgoObjectId; overload; static;
class function GenerateNewId(const ATimestamp: Integer): TgoObjectId; overload; static;
class function Parse(const AString: String): TgoObjectId; overload; static;
class function TryParse(const AString: String; out AObjectId: TgoObjectId): Boolean; overload; static;
class function Empty: TgoObjectId; static;
class operator Implicit(const A: String): TgoObjectId;
class operator Implicit(const A: TgoObjectId): String;
class operator Equal(const A, B: TgoObjectId): Boolean; static;
class operator NotEqual(const A, B: TgoObjectId): Boolean; static;
class operator GreaterThan(const A, B: TgoObjectId): Boolean; static;
class operator GreaterThanOrEqual(const A, B: TgoObjectId): Boolean; static;
class operator LessThan(const A, B: TgoObjectId): Boolean; static;
class operator LessThanOrEqual(const A, B: TgoObjectId): Boolean; static;
function ToByteArray: TBytes; overload;
procedure ToByteArray(const ADestination: TBytes; const AOffset: Integer); overload;
function ToString: String;
function CompareTo(const AOther: TgoObjectId): Integer;

Properties

property IsEmpty: Boolean read GetIsEmpty;
property Timestamp: Integer read GetTimestamp;
property Machine: Integer read GetMachine;
property Pid: UInt16 read GetPid;
property Increment: Integer read GetIncrement;
property CreationTime: TDateTime read GetCreationTime;

Description

Fields

FData: array [0..2] of UInt32
 
FBytes: array [0..11] of Byte
 

Methods

class function Create(const ABytes: TBytes): TgoObjectId; overload; static;

Creates an ObjectId from a byte array.

Parameters
ABytes
the array of bytes to use for the ObjectId. Must be 12 bytes long.
Returns

The ObjectId.

Exceptions raised
EArgumentException
if ABytes is not 12 bytes long
class function Create(const ABytes: array of Byte): TgoObjectId; overload; static;

Creates an ObjectId from a byte array.

Parameters
ABytes
the array of bytes to use for the ObjectId. Must be 12 bytes long.
Returns

The ObjectId.

Exceptions raised
EArgumentException
if ABytes is not 12 bytes long
class function Create(const ATimestamp, AMachine: Integer; const APid: UInt16; const AIncrement: Integer): TgoObjectId; overload; static;

Creates an ObjectId from its components.

Parameters
ATimestamp
32-bit number of seconds since Unix epoch.
AMachine
24-bit machine identifier. Must be >= 0 and < $01000000.
APid
16-bit process identifier.
AIncrement
24-bit counter. Must be >= 0 and < $01000000.
Returns

The ObjectId.

Exceptions raised
EArgumentOutOfRangeException
if AMachine or AIncrement are out of range.
class function Create(const ATimestamp: TDateTime; const ATimestampIsUTC: Boolean; const AMachine: Integer; const APid: UInt16; const AIncrement: Integer): TgoObjectId; overload; static;

Creates an ObjectId from its components.

Parameters
ATimestamp
the date/time to use as a timestamp.
ATimestampIsUTC
whether ATimestamp is in universal time.
AMachine
24-bit machine identifier. Must be >= 0 and < $01000000.
APid
16-bit process identifier.
AIncrement
24-bit counter. Must be >= 0 and < $01000000.
Returns

The ObjectId.

Exceptions raised
EArgumentOutOfRangeException
if AMachine or AIncrement are out of range.
class function Create(const AString: String): TgoObjectId; overload; static;

Creates an ObjectId from its string representation (see ToString).

Note: this constructor is equal to the Parse method.

Parameters
AString
the string representation of the ObjectId. Must contain 24 hex digits.
Returns

The ObjectId.

Exceptions raised
EArgumentException
if AString does not contain 24 hex digits.
class function GenerateNewId: TgoObjectId; overload; static;

Generates a new ObjectId using the current timestamp, machine, process and counter settings.

Note: the returned ObjectId is guaranteed to be unique on the current system, even if this function is called at the same time from the same or other processes on the machine. However, the ObjectId is not neccesarily globally unique since another machine with the same hostname or computer name can theoretically generate the same Id.

Returns

The newly generated ObjectId.

class function GenerateNewId(const ATimestamp: TDateTime; const ATimestampIsUTC: Boolean): TgoObjectId; overload; static;

Generates a new ObjectId using a given timestamp and the current machine, process and counter settings.

Note: the returned ObjectId is guaranteed to be unique on the current system, even if this function is called at the same time from the same or other processes on the machine. However, the ObjectId is not neccesarily globally unique since another machine with the same hostname or computer name can theoretically generate the same Id.

Parameters
ATimestamp
the date/time to use as a timestamp.
ATimestampIsUTC
whether ATimestamp is in universal time.
Returns

The newly generated ObjectId.

class function GenerateNewId(const ATimestamp: Integer): TgoObjectId; overload; static;

Generates a new ObjectId using a given timestamp and the current machine, process and counter settings.

Note: the returned ObjectId is guaranteed to be unique on the current system, even if this function is called at the same time from the same or other processes on the machine. However, the ObjectId is not neccesarily globally unique since another machine with the same hostname or computer name can theoretically generate the same Id.

Parameters
ATimestamp
32-bit number of seconds since Unix epoch.
Returns

The newly generated ObjectId.

class function Parse(const AString: String): TgoObjectId; overload; static;

Parses an ObjectId from its string representation (see ToString).

Parameters
AString
the string representation of the ObjectId. Must contain 24 hex digits.
Returns

The ObjectId.

Exceptions raised
EArgumentException
if AString does not contain 24 hex digits
class function TryParse(const AString: String; out AObjectId: TgoObjectId): Boolean; overload; static;

Tries to parse an ObjectId from its string representation (see ToString).

Parameters
AString
the string representation of the ObjectId. Must contain 24 hex digits.
AObjectId
is set to the parsed ObjectId, or all zeros if AString could not be parsed.
Returns

True if AString could be successfully parsed.

class function Empty: TgoObjectId; static;

Returns an empty ObjectId (with all zeros)

Returns

The empty ObjectId.

class operator Implicit(const A: String): TgoObjectId;

Implicitly converts a string to an ObjectId. The string must contain 24 hex digits. An EArgumentException will be raised if this is not the case

class operator Implicit(const A: TgoObjectId): String;

Implicitly convers an ObjectId to a string

class operator Equal(const A, B: TgoObjectId): Boolean; static;

Tests 2 ObjectId's for equality

class operator NotEqual(const A, B: TgoObjectId): Boolean; static;

Tests 2 ObjectId's for inequality

class operator GreaterThan(const A, B: TgoObjectId): Boolean; static;

Compares 2 ObjectId's using the ">" operator

class operator GreaterThanOrEqual(const A, B: TgoObjectId): Boolean; static;

Compares 2 ObjectId's using the ">=" operator

class operator LessThan(const A, B: TgoObjectId): Boolean; static;

Compares 2 ObjectId's using the "<" operator

class operator LessThanOrEqual(const A, B: TgoObjectId): Boolean; static;

Compares 2 ObjectId's using the "<=" operator

function ToByteArray: TBytes; overload;

Converts the ObjectId to an array of 12 bytes.

Returns

The ObjectId as 12 bytes.

procedure ToByteArray(const ADestination: TBytes; const AOffset: Integer); overload;

Converts the ObjectId to an array of bytes.

Parameters
ADestination
byte array to store the ObjectId into.
AOffset
starting offset in ADestination to use.
Exceptions raised
EArgumentException
if ADestination does not have room enough to store (AOffset+12) bytes.
function ToString: String;

Converts the ObjectId to its string representation. This is a string containing 24 hex digits.

Returns

The string representation of the ObjectId.

function CompareTo(const AOther: TgoObjectId): Integer;

Compare this ObjectId to another one.

Parameters
AOther
the other ObjectId.
Returns

* -1 if Self < AOther

  • 0 if Self = AOther

  • 1 if Self > AOther

Properties

property IsEmpty: Boolean read GetIsEmpty;

Returns True if this ObjectId is empty (all zeros)

property Timestamp: Integer read GetTimestamp;

Timestamp component of the ObjectId. If the 32-bit number of seconds since Unix epoch.

property Machine: Integer read GetMachine;

Machine component of the ObjectId. Is a 24-bit machine identifier.

property Pid: UInt16 read GetPid;

Process component of the ObjectId. Is a 16-bit process identifier.

property Increment: Integer read GetIncrement;

Counter component of the ObjectId. Is a 32-bit increment.

property CreationTime: TDateTime read GetCreationTime;

The creation time of the ObjectId, as stored inside its Timestamp component. The time is in UTC.

Generated by P2PasDoc 0.13.0 on 2017-04-25 12:54:26