APIRecord
JavaJavascriptPerlSwift

Record

A record is a tree of byte sequences with optional hashes:

(root) pressure location 45976389 7658333 picture 3a295f... addInteger(...) addInteger(...) 859000 addInteger(...) 4478000 addText('location') addReference(...) addText('picture') addText('pressure') addInteger(859000) #44... nthChild(0).asInteger() nthChild(2).asInteger() nthChild(1).asInteger() childWithText('location') referenceValue() childWithText('picture') childWithText('pressure') integerValue() Construction Querying

Each tree node is a record instance:

RecordBytesBbytesHash | NullHhash ?List of RecordsLchildrenList of RecordsRecordRchild 0RecordRchild 1...RecordBytesBbytesHash | NullHhash ?List of RecordsLchildren

Record instances are mutable. Due to the nature of Condensation, however, records are rarely modified in-place. Most often, they are either constructed or queried.

Byte sequences may contain any type of data. The record type provides functions to deal with UTF-8 text, numbers, boolean values, and references. Other data must be encoded and decoded by the application.

Records can be serialized and deserialized very efficiently and compactly, and are therefore the data structure of choice for most applications. The root node of a record is not serialized.

Creation

Record record = new Record();
Record record = new Record(bytes);
Record record = new Record(bytes, hash);

Creates a record.

Record record = Record.from(object);

Parses an object. If the object is null, or does not contain a valid record, null is returned.

Record construction

record.add(bytes, hash);
record.add(text, hash);
record.add(booleanValue, hash);
record.add(integerValue, hash);
record.addUnsigned(integerValue, hash);
record.add(hash);
record.add(hashAndKey);
record.add(record);
record.add(records);

Adds a child node to the record and returns that child. The value is converted to a byte sequence. The second hash argument is optional.

Signed integers are supported up to a size of 52 bits. Unsigned integers are discouraged, as they are easily confused with signed integers, which may lead to errors that go unnoticed for a long time. Put this in a chapter under "notes" with examples, why text and integer are not easily mistaken, but unsigned and integer are.

A piece of record construction code may look as follows:

record.add("pressure").add(859000);
record.add("picture").add(pictureHashAndKey);
Record location = record.add("location");
location.add(latitude);
location.add(longitude);
location.add(altitude);

Querying

boolean result = record.contains(bytes);
boolean result = record.contains(text);

Returns true if the record contains a child with the given bytes.

Record child = record.child(bytes);
Record child = record.child(text);
Record child = record.firstChild();
Record child = record.child(i);

Returns the respective child, or an empty record node. This is useful for records that are used as dictionaries or arrays.

Bytes value = record.bytes;
Hash hash = record.hash;                           // may be null
boolean value = record.asBoolean();
long value = record.asInteger();
long value = record.asUnsigned();
String text = record.asText();
HashAndKey hashAndKey = record.asHashAndKey();     // may be null

Returns the node's value converted to the respective type.

Bytes value = record.bytesValue();
Hash hash = record.hashValue();                    // may be null
boolean value = record.booleanValue();
long value = record.integerValue();
long value = record.unsignedValue();
String text = record.textValue();
HashAndKey hashAndKey = record.hashAndKeyValue();  // may be null

Returns the value of the first child converted to the respective type. This is useful to retrieve values from dictionary-style records:

long value = record.child("pressure").integerValue();

and a shortcut for:

long value = record.child("pressure").firstChild().asInteger();

Serialization and encryption

CondensationObject object = record.toObject();

Serializes the record to an object.

CondensationObject object = record.toObject();
Bytes key = object.cryptInplace();
HashAndKey hashAndKey = new HashAndKey(object.calculateHash(), key);

Serializes and encrypts a record, and prepares the hash and key of the resulting object.

Threading

Records are not synchronized. However, they may be passed from one thread to another as long as they are accessed from a single thread at a time only.