record TgoBsonDocument

DescriptionHierarchyInternal Classes and RecordsFieldsMethodsProperties

Unit

Declaration

type TgoBsonDocument = record

Description

A BSON document. A BSON document contains key/value pairs, where the key is a String and the value can be any BSON value. It is similar to a Delphi dictionary or a JSON object. However, unlike Delphi dictionaries, a documents maintains insertion order and you can access values both by name and by index.

Overview

Internal Classes and Records

_IDocument = interface(TgoBsonValue._IValue)

Methods

class function Create: TgoBsonDocument; overload; static;
class function Create(const AAllowDuplicateNames: Boolean): TgoBsonDocument; overload; static;
class function Create(const AElement: TgoBsonElement): TgoBsonDocument; overload; static;
class function Create(const AName: String; const AValue: TgoBsonValue): TgoBsonDocument; overload; static;
class function Parse(const AJson: String): TgoBsonDocument; static;
class function TryParse(const AJson: String; out ADocument: TgoBsonDocument): Boolean; static;
class function Load(const ABson: TBytes): TgoBsonDocument; static;
class function TryLoad(const ABson: TBytes; out ADocument: TgoBsonDocument): Boolean; static;
class function LoadFromJsonFile(const AFilename: String): TgoBsonDocument; static;
class function LoadFromJsonStream(const AStream: TStream): TgoBsonDocument; static;
class function LoadFromBsonFile(const AFilename: String): TgoBsonDocument; static;
class function LoadFromBsonStream(const AStream: TStream): TgoBsonDocument; static;
procedure SaveToJsonFile(const AFilename: String); overload;
procedure SaveToJsonFile(const AFilename: String; const ASettings: TgoJsonWriterSettings); overload;
procedure SaveToJsonStream(const AStream: TStream); overload;
procedure SaveToJsonStream(const AStream: TStream; const ASettings: TgoJsonWriterSettings); overload;
procedure SaveToBsonFile(const AFilename: String);
procedure SaveToBsonStream(const AStream: TStream);
class operator Implicit(const A: TgoBsonDocument): TgoBsonValue; static;
class operator Equal(const A, B: TgoBsonDocument): Boolean; static;
class operator NotEqual(const A, B: TgoBsonDocument): Boolean; static;
function IsNil: Boolean; inline;
procedure SetNil; inline;
function Clone: TgoBsonDocument; inline;
function DeepClone: TgoBsonDocument; inline;
function ToBson: TBytes; inline;
function ToJson: String; overload; inline;
function ToJson(const ASettings: TgoJsonWriterSettings): String; overload; inline;
function Add(const AName: String; const AValue: TgoBsonValue): TgoBsonDocument; overload; inline;
function Add(const AElement: TgoBsonElement): TgoBsonDocument; overload; inline;
function Get(const AName: String; const ADefault: TgoBsonValue): TgoBsonValue;
function IndexOfName(const AName: String): Integer; inline;
function Contains(const AName: String): Boolean; inline;
function ContainsValue(const AValue: TgoBsonValue): Boolean; inline;
function TryGetElement(const AName: String; out AElement: TgoBsonElement): Boolean; inline;
function TryGetValue(const AName: String; out AValue: TgoBsonValue): Boolean; inline;
procedure Remove(const AName: String); inline;
procedure Delete(const AIndex: Integer); inline;
procedure Clear; inline;
function Merge(const AOtherDocument: TgoBsonDocument; const AOverwriteExistingElements: Boolean): TgoBsonDocument;
function ToArray: TArray<TgoBsonElement>; inline;
function GetEnumerator: TEnumerator; inline;

Properties

property AllowDuplicateNames: Boolean read GetAllowDuplicateNames write SetAllowDuplicateNames;
property Count: Integer read GetCount;
property Elements[constAIndex:Integer]: TgoBsonElement read GetElement;
property Values[constAIndex:Integer]: TgoBsonValue read GetValue write SetValue;
property ValuesByName[constAName:String]: TgoBsonValue read GetValueByName write SetValueByName;

Description

Methods

class function Create: TgoBsonDocument; overload; static;

Creates an empty BSON document.

Returns

The empty BSON document

class function Create(const AAllowDuplicateNames: Boolean): TgoBsonDocument; overload; static;

Creates an empty BSON document.

Parameters
AAllowDuplicateNames
whether to allow duplicate names in the document. This should generally be False.
Returns

The empty BSON document

class function Create(const AElement: TgoBsonElement): TgoBsonDocument; overload; static;

Creates a BSON document with a single element.

Parameters
AElement
the element to add to the document.
Returns

The BSON document

Exceptions raised
EArgumentNilException
if AElement.Value has not been assigned (if IsNil returns True)
class function Create(const AName: String; const AValue: TgoBsonValue): TgoBsonDocument; overload; static;

Creates a BSON document with a single element.

Parameters
AName
the name of the element to add to the document.
AValue
the value of the element.
Returns

The BSON document

Exceptions raised
EArgumentNilException
if AValue has not been assigned (if IsNil returns True)
class function Parse(const AJson: String): TgoBsonDocument; static;

See TgoBsonValue.Parse

class function TryParse(const AJson: String; out ADocument: TgoBsonDocument): Boolean; static;

See TgoBsonValue.TryParse

class function Load(const ABson: TBytes): TgoBsonDocument; static;

See TgoBsonValue.Load

class function TryLoad(const ABson: TBytes; out ADocument: TgoBsonDocument): Boolean; static;

See TgoBsonValue.TryLoad

class function LoadFromJsonFile(const AFilename: String): TgoBsonDocument; static;

See TgoBsonValue.LoadFromJsonFile

class function LoadFromJsonStream(const AStream: TStream): TgoBsonDocument; static;

See TgoBsonValue.LoadFromJsonStream

class function LoadFromBsonFile(const AFilename: String): TgoBsonDocument; static;

See TgoBsonValue.LoadFromBsonFile

class function LoadFromBsonStream(const AStream: TStream): TgoBsonDocument; static;

See TgoBsonValue.LoadFromBsonStream

procedure SaveToJsonFile(const AFilename: String); overload;

See TgoBsonValue.SaveToJsonFile

procedure SaveToJsonFile(const AFilename: String; const ASettings: TgoJsonWriterSettings); overload;

See TgoBsonValue.SaveToJsonFile

procedure SaveToJsonStream(const AStream: TStream); overload;

See TgoBsonValue.SaveToJsonStream

procedure SaveToJsonStream(const AStream: TStream; const ASettings: TgoJsonWriterSettings); overload;

See TgoBsonValue.SaveToJsonStream

procedure SaveToBsonFile(const AFilename: String);

See TgoBsonValue.SaveToBsonFile

procedure SaveToBsonStream(const AStream: TStream);

See TgoBsonValue.SaveToBsonStream

class operator Implicit(const A: TgoBsonDocument): TgoBsonValue; static;

Implicitly casts a BSON document to a BSON value.

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

See TgoBsonValue.Equal

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

See TgoBsonValue.NotEqual

function IsNil: Boolean; inline;

See TgoBsonValue.IsNil

procedure SetNil; inline;

See TgoBsonValue.SetNil

function Clone: TgoBsonDocument; inline;

See TgoBsonValue.Clone

function DeepClone: TgoBsonDocument; inline;

See TgoBsonValue.DeepClone

function ToBson: TBytes; inline;

See TgoBsonValue.ToBson

function ToJson: String; overload; inline;

See TgoBsonValue.ToJson

function ToJson(const ASettings: TgoJsonWriterSettings): String; overload; inline;

See TgoBsonValue.ToJson

function Add(const AName: String; const AValue: TgoBsonValue): TgoBsonDocument; overload; inline;

Adds an element to the document.

Note: Names are case-sensitive

Parameters
AName
the name of the element to add to the document.
AValue
the value of the element.
Returns

The document itself, so you can use it for chaining.

Exceptions raised
EArgumentNilException
if AValue has not been assigned (IsNil returns True). EInvalidOperation if AllowDuplicateNames = False and document already contains element with given name.
function Add(const AElement: TgoBsonElement): TgoBsonDocument; overload; inline;

Adds an element to the document.

Note: Names are case-sensitive

Parameters
AElement
the element to add to the document.
Returns

The document itself, so you can use it for chaining.

Exceptions raised
EArgumentNilException
if AElement.Value has not been assigned (IsNil returns True). EInvalidOperation if AllowDuplicateNames = False and document already contains element with given name.
function Get(const AName: String; const ADefault: TgoBsonValue): TgoBsonValue;

Gets a value from the document by name, or a default value if the document does not contain an element with the given name.

Parameters
AName
the name of the value to get.
ADefault
the default value to return in case the document does not contain an element named AName.
Returns

The value associated with AName, or ADefault in case the document does not contain an element named AName.

function IndexOfName(const AName: String): Integer; inline;

Returns the index of the element with a given name.

Note: Names are case-sensitive

Parameters
AName
the name of the element to find.
Returns

The index of the element, or -1 of the document does not contain an element with the given name.

function Contains(const AName: String): Boolean; inline;

Checks whether the document contains an element with a given name.

Note: Names are case-sensitive

Parameters
AName
the name of the element to find.
Returns

True if the document contains an element with the given name.

function ContainsValue(const AValue: TgoBsonValue): Boolean; inline;

Checks whether the document contains an element with a given value.

Note: the Equal operator of AValue is used to check if the value is in the document.

Parameters
AValue
the value of the element to find.
Returns

True if the document contains an element with the given value.

function TryGetElement(const AName: String; out AElement: TgoBsonElement): Boolean; inline;

Tries to retrieve an element by name.

Parameters
AName
the name of the element to find.
AELement
is set to the corresponding element if found.
Returns

True if the document contains an element with the given name.

function TryGetValue(const AName: String; out AValue: TgoBsonValue): Boolean; inline;

Tries to retrieve a value by name.

Parameters
AName
the name of the value to find.
AValue
is set to the corresponding value if found.
Returns

True if the document contains an element with the given name.

procedure Remove(const AName: String); inline;

Removes an element by name.

Note: In case AllowDuplicateNames = True, then all elements with this name are removed. The method does nothing if the document does not contain an element with the given name.

Parameters
AName
the name of the element to remove.
procedure Delete(const AIndex: Integer); inline;

Deletes an element by index.

Parameters
AIndex
the index of the element to delete.
Exceptions raised
EArgumentOutOfRangeException
in AIndex is out of bounds.
procedure Clear; inline;

Clears the document

function Merge(const AOtherDocument: TgoBsonDocument; const AOverwriteExistingElements: Boolean): TgoBsonDocument;

Merges another document into this one.

Parameters
AOtherDocument
the other document to merge with this one.
AOverwriteExistingElements
whether to overwrite existing element.
Returns

The document itself, so you can use it for chaining.

Exceptions raised
EArgumentNilException
if AOtherDocument has not been assigned (IsNil returns True).
function ToArray: TArray<TgoBsonElement>; inline;

Returns the elements in then document as an array.

Returns

The array of elements

function GetEnumerator: TEnumerator; inline;

Allow for..in enumeration of the elements in the document.

Properties

property AllowDuplicateNames: Boolean read GetAllowDuplicateNames write SetAllowDuplicateNames;

Whether duplicate element names are allowed. Should generally be False (the default).

property Count: Integer read GetCount;

Number of elements in the document. Could be larger than the number of names in the document in case AllowDuplicateNames = True

property Elements[constAIndex:Integer]: TgoBsonElement read GetElement;

The elements in the document by index.

Parameters
AIndex
the index of the element to get.
Exceptions raised
EArgumentOutOfRangeException
in AIndex is out of bounds.
property Values[constAIndex:Integer]: TgoBsonValue read GetValue write SetValue;

The values in the document by index.

Parameters
AIndex
the index of the value to get or set.
Exceptions raised
EArgumentOutOfRangeException
in AIndex is out of bounds. EArgumentNilException when setting the value and AValue is not assigned (IsNil returns True)
property ValuesByName[constAName:String]: TgoBsonValue read GetValueByName write SetValueByName;

The values in the document by name.

Note: when getting a value and the name is not found, a TgoBsonNull value is returned.

Note: when setting a value, it will replace an existing value with the same name if found, or otherwise add it.

Parameters
AName
the name of the value to get or set.
Exceptions raised
EArgumentNilException
when setting the value and AValue is not assigned (IsNil returns True)

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