The mORMot 2 framework uses custom low-level types, classes, and functions instead of relying solely on the standard Delphi RTL. This design choice provides:

• Cross-platform and cross-compiler support (Delphi 7 through 12.2, FPC 3.2+)
• Unicode support via native UTF-8 encoding for all versions
• Optimized performance for speed, multi-threading, and memory efficiency
• Consistent KISS design with shared common features

4.3.2. Cross-Platform Integer Types

4.4. TDynArray: Dynamic Array Wrapper

TDynArray (in mormot.core.data) provides TList-like functionality for any dynamic array:

4.4.1. Basic Usage

uses
  mormot.core.base,
  mormot.core.data;

type
  TIntegerArray = array of Integer;

var
  arr: TIntegerArray;
  da: TDynArray;
  v: Integer;
begin
  da.Init(TypeInfo(TIntegerArray), arr);  // Associate wrapper with array

  for v := 1 to 1000 do
    da.Add(v);  // TList-like Add method

  da.Sort(SortDynArrayInteger);  // In-place sorting

  v := 500;
  if da.Find(v) >= 0 then  // Binary search (after sorting)
    WriteLn('Found 500');

  da.Delete(0);  // Delete by index
  WriteLn('Count: ', da.Count);
end;

4.4.2. External Count for Performance

For high-performance scenarios, use an external count variable to avoid reallocation on every Add/Delete:

var
  arr: TIntegerArray;
  da: TDynArray;
  count: Integer;
begin
  da.Init(TypeInfo(TIntegerArray), arr, @count);  // External count
  da.Capacity := 10000;  // Pre-allocate memory

  // Now Add/Delete modify 'count' without reallocating 'arr'
  for i := 1 to 10000 do
    da.Add(i);  // Much faster with external count
end;

4.4.3. Serialization

TDynArray supports both binary and JSON serialization:

var
  binary: RawByteString;
  json: RawUtf8;
begin
  // Binary (fast, compact)
  binary := da.SaveTo;
  da.LoadFrom(binary);

  // JSON (interoperable)
  json := da.SaveToJson;
  da.LoadFromJson(json);
end;

4.4.4. TDynArrayHashed for Dictionary-Like Access

TDynArrayHashed adds O(1) hash-based lookup:

type
  TNameValue = record
    Name: RawUtf8;
    Value: Integer;
  end;
  TNameValueArray = array of TNameValue;

var
  arr: TNameValueArray;
  hash: TDynArrayHashed;
  added: Boolean;
  idx: Integer;
begin
  hash.Init(TypeInfo(TNameValueArray), arr);  // Auto-detects RawUtf8 key

  // Add or find existing
  idx := hash.FindHashedForAdding('MyKey', added);
  if added then
  begin
    arr[idx].Name := 'MyKey';
    arr[idx].Value := 42;
  end;

  // Fast lookup
  idx := hash.FindHashed('MyKey');  // O(1) instead of O(n)
end;

4.4.5. TSynDictionary

TSynDictionary (in mormot.core.data) is a thread-safe dictionary storing key-value pairs as two dynamic arrays:

uses
  mormot.core.data;

var
  dict: TSynDictionary;
begin
  dict := TSynDictionary.Create(TypeInfo(TRawUtf8DynArray), TypeInfo(TIntegerDynArray));
  try
    dict.Add('key1', 100);
    dict.Add('key2', 200);

    if dict.Exists('key1') then
      WriteLn('Value: ', dict.FindAndCopy('key1', v));

    // Thread-safe by default (no external locking needed)
  finally
    dict.Free;
  end;
end;

4.5. TDocVariant: Schema-less Documents

TDocVariant (in mormot.core.variants) is a custom variant type for storing JSON-like documents:

4.5.1. Creating Documents

uses
  mormot.core.variants;

var
  doc: Variant;
begin
  // Object document
  doc := _Obj(['name', 'John', 'age', 30]);
  // or from JSON
  doc := _Json('{"name":"John","age":30}');

  // Array document
  doc := _Arr(['apple', 'banana', 'cherry']);
  // or from JSON
  doc := _Json('["apple","banana","cherry"]');
end;

4.5.2. Late-Binding Access

var
  doc: Variant;
begin
  doc := _Json('{"name":"John","address":{"city":"NYC","zip":"10001"}}');

  // Read properties via late-binding
  WriteLn(doc.name);           // 'John'
  WriteLn(doc.address.city);   // 'NYC'

  // Modify properties
  doc.name := 'Jane';
  doc.address.state := 'NY';   // Add new property

  // Convert to JSON
  WriteLn(doc);  // '{"name":"Jane","address":{"city":"NYC","zip":"10001","state":"NY"}}'
end;

4.5.3. Direct TDocVariantData Access

For better performance, use direct transtyping:

var
  doc: Variant;
begin
  doc := _Json('{"a":1,"b":2,"c":3}');

  // Safe access via _Safe()
  with _Safe(doc)^ do
  begin
    WriteLn('Count: ', Count);
    for i := 0 to Count - 1 do
      WriteLn(Names[i], '=', Values[i]);
  end;

  // Typed property access
  WriteLn(_Safe(doc)^.I['a']);  // Integer access
  WriteLn(_Safe(doc)^.U['b']);  // RawUtf8 access
end;

4.5.4. Per-Value vs Per-Reference

By default, _Obj()/_Arr()/_Json() create per-value documents (deep copy on assignment):

var
  v1, v2: Variant;
begin
  v1 := _Obj(['name', 'John']);
  v2 := v1;        // Creates a copy
  v2.name := 'Jane';
  WriteLn(v1.name);  // 'John' (unchanged)
  WriteLn(v2.name);  // 'Jane'
end;

Use _ObjFast()/_ArrFast()/_JsonFast() for per-reference documents (shared):

var
  v1, v2: Variant;
begin
  v1 := _ObjFast(['name', 'John']);
  v2 := v1;        // Reference, not copy
  v2.name := 'Jane';
  WriteLn(v1.name);  // 'Jane' (both changed!)
  WriteLn(v2.name);  // 'Jane'
end;

4.6. Date and Time

4.6.1. ISO 8601 Encoding

Dates are encoded as ISO 8601 text (YYYY-MM-DDThh:mm:ss), which provides:

• Lexicographical ordering equals chronological ordering
• Natural sorting in file systems and databases
• Cross-platform compatibility

4.6.2. Time Types

4.6.3. TTimeLog

TTimeLog (in mormot.core.datetime) is a proprietary 64-bit format optimized for fast comparison and compact storage:

uses
  mormot.core.datetime;

var
  t: TTimeLog;
  dt: TDateTime;
begin
  t := TimeLogNow;                    // Current time
  t := TimeLogFromDateTime(Now);      // From TDateTime
  dt := TimeLogToDateTime(t);         // Back to TDateTime

  // Direct comparison works (chronological order)
  if t1 > t2 then
    WriteLn('t1 is later');

  // ISO 8601 conversion
  WriteLn(TimeLogToIso8601(t, true));  // '2025-01-15T10:30:45'
end;

4.6.4. Time Zones

TSynTimeZone (in mormot.core.datetime) handles time zone conversions:

uses
  mormot.core.datetime;

var
  local: TDateTime;
begin
  // Convert UTC to local time for a specific zone
  local := TSynTimeZone.Default.UtcToLocal(NowUtc, 'Eastern Standard Time');

  // Get current local time for a zone
  local := TSynTimeZone.Default.NowToLocal('Pacific Standard Time');
end;

4.7. Thread Safety: TSynLocker

TSynLocker (in mormot.core.os) provides CPU cache-friendly critical sections:

4.7.1. Basic Usage

uses
  mormot.core.os;

var
  Lock: TSynLocker;
  Counter: Integer;
begin
  Lock.Init;
  try
    // In thread code:
    Lock.Lock;
    try
      Inc(Counter);  // Protected access
    finally
      Lock.UnLock;
    end;
  finally
    Lock.Done;
  end;
end;

4.7.2. Automatic Unlocking

Use ProtectMethod for RAII-style protection:

procedure TMyClass.ThreadSafeMethod;
begin
  fLock.ProtectMethod;  // Returns IUnknown, auto-unlocks at method end
  // ... protected code ...
end;  // Automatically unlocks here

4.7.3. Built-in Storage

TSynLocker includes 7 variant slots for thread-safe value storage:

var
  Lock: TSynLocker;
begin
  Lock.Init;
  // Thread-safe integer storage
  Lock.LockedInt64[0] := 100;
  Lock.LockedInt64Increment(0, 1);  // Atomic increment

  // Thread-safe string storage
  Lock.LockedUtf8[1] := 'value';

  // Thread-safe variant storage
  Lock.Locked[2] := _Obj(['count', 42]);
end;

4.7.4. Thread-Safe Base Classes

Inherit from these for built-in TSynLocker:

4.8. Core Units Reference

4.8.1. Foundation Layer

4.8.2. Data Layer

4.8.3. Application Layer

4.9. Dependency Order

Core units have strict dependencies (lower never depends on higher):

mormot.core.base (RTL types, ASM - no dependencies)
  └─► mormot.core.os (OS abstraction)
      └─► mormot.core.unicode (encoding)
          └─► mormot.core.text (parsing)
              └─► mormot.core.datetime (dates)
                  └─► mormot.core.rtti (RTTI)
                      └─► mormot.core.buffers (compression)
                          └─► mormot.core.data (TDynArray)
                              └─► mormot.core.json (JSON)
                                  └─► [variants, log, threads, etc.]

Critical Rule: When modifying units, respect this hierarchy. Adding references that create circular dependencies will break compilation.

4.10. Migration from SynCommons.pas

4.10.1. Type Mapping

4.10.2. Backward Compatibility

By default, mORMot 2 provides compatibility aliases. Define PUREMORMOT2 to disable them and use only new names.

4.10.3. Minimal Uses Clause

uses
  mormot.core.base,      // Foundation
  mormot.core.os,        // OS abstraction
  mormot.core.text,      // Text utilities
  mormot.core.json,      // JSON
  mormot.core.variants;  // TDocVariant

Next Chapter: Object-Relational Mapping (TOrm, TOrmModel)

Navigation