Merge pull request #232 from Bi0T1N/docu

small enhancements for documentation

SQLite3/Documentation/Synopse SQLite3 Framework.pro

@@ -2356,7 +2356,7 @@ You can optionally specify the associated table, using a custom {\f1\fs20 TID} t
 !   property OrderedByCascade: TSQLRecordClientToBeDeletedID
 !     read fOrderedByCascade write fOrderedByCascade;
 !   ...
-Those three published fields will be able to store a {\f1\fs20 Int64} foreign key, and the ORM will ensure a corresponding {\i index} is created on the database, to speedup search on their values.\line But their type - {\f1\fs20 TID}, {\f1\fs20 TSQLRecordClientID}, or TSQLRecordClientToBeDeletedID - will define how the deletion process will be processed.
+Those three published fields will be able to store a {\f1\fs20 Int64} foreign key, and the ORM will ensure a corresponding {\i index} is created on the database, to speedup search on their values.\line But their type - {\f1\fs20 TID}, {\f1\fs20 TSQLRecordClientID}, or {\f1\fs20 TSQLRecordClientToBeDeletedID} - will define how the deletion process will be processed.
 By using the generic {\f1\fs20 TID} type, the first {\f1\fs20 Client} property won't have any reference to any table, so no deletion tracking will take place.
 On the other hand, {\i following the type naming convention}, the others {\f1\fs20 OrderedBy} and {\f1\fs20 OrderedByCascade} properties will be associated with the {\f1\fs20 TSQLRecordClient} table of the data model.\line In fact, the ORM will retrieve the {\f1\fs20 'TSQLRecordClientID'} or {\f1\fs20 'TSQLRecordClientToBeDeletedID'}  type names, and search for a {\f1\fs20 TSQLRecord} associated by trimming {\f1\fs20 *[ToBeDeleted]ID}, which is {\f1\fs20 TSQLRecordClient} in this case.\line As a result, the ORM will be able to track any {\f1\fs20 TSQLRecordClient} deletion: for any row pointing to the deleted record, it will ensure that this {\f1\fs20 OrderedBy} property will be reset to 0, or that the row containing the {\f1\fs20 OrderedByCascade} property will be deleted. Note that the framework won't define a {\f1\fs20 ON DELETE SET DEFAULT} or {\f1\fs20 ON DELETE CASCADE} foreign key via SQL, but emulate them {\i at ORM level}.
 :148  TRecordReference and TRecordReferenceToBeDeleted
@@ -13969,7 +13969,7 @@ Of course, you can use so-called {\i Promises} and some nice libraries - mainly
 #      console.error("Error with the twitterverse:", error);
 #    }
 #  );
-Taken from @http://domenic.me/2012/10/14/youre-missing-the-point-of-promises
+Taken from @https://blog.domenic.me/youre-missing-the-point-of-promises/
 This kind of code will be perfectly readable for a {\i JavaScript} daily user, or someone fluent with functional languages.
 But the following blocking/synchronous code may sound much more familiar, safer and less verbose, to most {\i Delphi} / Java / C# programmer:
 #try {

SQLite3/mORMot.pas

@@ -7715,7 +7715,7 @@   TSQLRecord = class(TObject)
     // SQLite3 RowID)
     // - AnsiString are created as TEXT COLLATE NOCASE (fast SQLite3 7bits compare)
     // - RawUnicode and RawUTF8 are created as TEXT COLLATE SYSTEMNOCASE
-    // (i.e. use our fast UTF8IComp() for comparaison)
+    // (i.e. use our fast UTF8IComp() for comparison)
     // - TDateTime are created as TEXT COLLATE ISO8601
     // (which calls our very fast ISO TEXT to Int64 conversion routine)
     // - an individual bit set in UniqueField forces the corresponding field to
@@ -8118,6 +8118,12 @@   TSQLRecord = class(TObject)
     procedure FillValue(PropName, Value: PUTF8Char; wasString: boolean;
       FieldBits: PSQLFieldBits=nil);
 
+    /// return true if all published properties values in Other are identical to
+    // the published properties of this object
+    // - instances must be of the same class type
+    // - only simple fields (i.e. not TSQLRawBlob/TSQLRecordMany) are compared
+    // - comparison is much faster than SameValues() below
+    function SameRecord(Reference: TSQLRecord): boolean;
     /// return true if all published properties values in Other are identical to
     // the published properties of this object
     // - work with different classes: Reference properties name must just be
@@ -8126,12 +8132,6 @@   TSQLRecord = class(TObject)
     // - compare the text representation of the values: fields may be of different
     // type, encoding or precision, but still have same values
     function SameValues(Reference: TSQLRecord): boolean;
-    /// return true if all published properties values in Other are identical to
-    // the published properties of this object
-    // - instances must be of the same class type
-    // - only simple fields (i.e. not TSQLRawBlob/TSQLRecordMany) are compared
-    // - comparaison is much faster than SameValues() above
-    function SameRecord(Reference: TSQLRecord): boolean;
     /// clear the values of all published properties, and also the ID property
     procedure ClearProperties; overload;
     /// clear the values of specified published properties
@@ -8689,7 +8689,7 @@   TSQLTable = class
     // - you can specify a Row index to be updated during the sort in PCurrentRow
     // - sort is very fast, even for huge tables (more faster than any indexed
     // SQL query): 500,000 rows are sorted instantly
-    // - this optimized sort implementation does the comparaison first by the
+    // - this optimized sort implementation does the comparison first by the
     // designed field, and, if the field value is identical, the ID value is
     // used (it will therefore sort by time all identical values)
     procedure SortFields(Field: integer; Asc: boolean=true;
@@ -8728,7 +8728,7 @@   TSQLTable = class
     // (X'53514C697465' e.g.)
     // - since TSQLTable data is PUTF8Char, string type is sftUTF8Text only
     function FieldType(Field: integer; out FieldTypeInfo: PSQLTableFieldType): TSQLFieldType; overload;
-    /// get the appropriate Sort comparaison function for a field,
+    /// get the appropriate Sort comparison function for a field,
     // nil if not available (bad field index or field is blob)
     // - field type is guessed from first data row
     function SortCompare(Field: integer): TUTF8Compare;
@@ -20588,32 +20588,32 @@   TSQLRecordVirtualTableForcedID = class(TSQLRecordVirtual);
   // ! Model.VirtualTableRegister(TSQLRecordDali1,TSQLVirtualTableJSON);
   TSQLRecordVirtualTableAutoID = class(TSQLRecordVirtual);
 
-/// special comparaison function for sorting ftRecord (TRecordReference/RecordRef)
+/// special comparison function for sorting ftRecord (TRecordReference/RecordRef)
 // UTF-8 encoded values in the SQLite3 database or JSON content
 function UTF8CompareRecord(P1,P2: PUTF8Char): PtrInt;
 
-/// special comparaison function for sorting sftBoolean
+/// special comparison function for sorting sftBoolean
 // UTF-8 encoded values in the SQLite3 database or JSON content
 function UTF8CompareBoolean(P1,P2: PUTF8Char): PtrInt;
 
-/// special comparaison function for sorting sftEnumerate, sftSet or sftID
+/// special comparison function for sorting sftEnumerate, sftSet or sftID
 // UTF-8 encoded values in the SQLite3 database or JSON content
 function UTF8CompareUInt32(P1,P2: PUTF8Char): PtrInt;
 
-/// special comparaison function for sorting sftInteger, sftTID, sftRecordVersion
+/// special comparison function for sorting sftInteger, sftTID, sftRecordVersion
 // sftTimeLog/sftModTime/sftCreateTime or sftUnixTime/sftUnixMSTime UTF-8 encoded
 // values in the SQLite3 database or JSON content
 function UTF8CompareInt64(P1,P2: PUTF8Char): PtrInt;
 
-/// special comparaison function for sorting sftCurrency
+/// special comparison function for sorting sftCurrency
 // UTF-8 encoded values in the SQLite3 database or JSON content
 function UTF8CompareCurr64(P1,P2: PUTF8Char): PtrInt;
 
-/// special comparaison function for sorting sftFloat
+/// special comparison function for sorting sftFloat
 // UTF-8 encoded values in the SQLite3 database or JSON content
 function UTF8CompareDouble(P1,P2: PUTF8Char): PtrInt;
 
-/// special comparaison function for sorting sftDateTime or sftDateTimeMS
+/// special comparison function for sorting sftDateTime or sftDateTimeMS
 // UTF-8 encoded values in the SQLite3 database or JSON content
 function UTF8CompareISO8601(P1,P2: PUTF8Char): PtrInt;
 
@@ -26934,7 +26934,7 @@ function UTF8CompareISO8601(P1,P2: PUTF8Char): PtrInt;
 
 type
   /// a static object is used for smaller recursive stack size and faster code
-  // - these special sort implementation do the comparaison first by the
+  // - these special sort implementation do the comparison first by the
   // designed field, and, if the field value is identical, the ID value is
   // used (it will therefore sort by time all identical values)
   // - code generated is very optimized: stack and memory usage, CPU registers
@@ -27064,7 +27064,7 @@ procedure TUTF8QuickSort.QuickSort(L, R: Integer);
     SetPP(@Results[P*Params.FieldCount+Params.FieldIndex],P);
     repeat
       // this loop has no multiplication -> most of the time is spent in compIJ
-      if Params.Asc then begin // ascending order comparaison
+      if Params.Asc then begin // ascending order comparison
         while compI<0 do begin
           inc(I);
           inc(PByte(CI),FieldCountNextPtr); // next row
@@ -27073,7 +27073,7 @@ procedure TUTF8QuickSort.QuickSort(L, R: Integer);
           dec(J);
           dec(PByte(CJ),FieldCountNextPtr); // previous row
         end;
-      end else begin // descending order comparaison
+      end else begin // descending order comparison
         while compI>0 do begin
           inc(I);
           inc(PByte(CI),FieldCountNextPtr); // next row
@@ -32889,6 +32889,22 @@ class function TSQLRecord.CaptionNameFromRTTI(Action: PShortString): string;
   end;
 end;
 
+function TSQLRecord.SameRecord(Reference: TSQLRecord): boolean;
+var i: integer;
+begin
+  result := false;
+  if (self=nil) or (Reference=nil) or
+     (PSQLRecordClass(Reference)^<>PSQLRecordClass(Self)^) or (Reference.fID<>fID) then
+    exit;
+  with RecordProps do
+    for i := 0 to high(SimpleFields) do
+      // compare not TSQLRawBlob/TSQLRecordMany fields
+      with SimpleFields[i] do
+        if CompareValue(self,Reference,false)<>0 then
+          exit; // properties don't have the same value
+  result := true;
+end;
+
 function TSQLRecord.SameValues(Reference: TSQLRecord): boolean;
 var O: TSQLPropInfo;
     i: integer;
@@ -32908,7 +32924,7 @@ function TSQLRecord.SameValues(Reference: TSQLRecord): boolean;
         if CompareValue(self,Reference,false)<>0 then
           exit; // properties don't have the same value
   end else begin
-    // comparaison of all properties of Reference against self
+    // comparison of all properties of Reference against self
     This := RecordProps;
     Ref := Reference.RecordProps;
     for i := 0 to high(Ref.SimpleFields) do
@@ -32924,22 +32940,6 @@ function TSQLRecord.SameValues(Reference: TSQLRecord): boolean;
   result := true;
 end;
 
-function TSQLRecord.SameRecord(Reference: TSQLRecord): boolean;
-var i: integer;
-begin
-  result := false;
-  if (self=nil) or (Reference=nil) or
-     (PSQLRecordClass(Reference)^<>PSQLRecordClass(Self)^) or (Reference.fID<>fID) then
-    exit;
-  with RecordProps do
-    for i := 0 to high(SimpleFields) do
-      // compare not TSQLRawBlob/TSQLRecordMany fields
-      with SimpleFields[i] do
-        if CompareValue(self,Reference,false)<>0 then
-          exit; // properties don't have the same value
-  result := true;
-end;
-
 procedure TSQLRecord.ClearProperties;
 var i: integer;
 begin

SQLite3/mORMoti18n.pas

@@ -1315,7 +1315,7 @@ procedure SetCurrentLanguage(aLanguage: TLanguages; aForceEnglishIfNoMsgFile: bo
       (LanguageCharSet[LCIDToLanguage(GetUserDefaultLCID)]=CharSet) then begin
       // NormToUpper/Lower[] was filled with LOCALE_USER_DEFAULT values
       // -> OK if same CHARSET, and not multi-byte
-      i18nCompareStr := // not MBCS strict comparaison is always valid
+      i18nCompareStr := // not MBCS strict comparison is always valid
         {$ifdef ENHANCEDRTL}CompareStr{$else}i18nInnerCompareStr{$endif};
       // CompareText in SysUtils.pas uses NormToUpper[], this uses i18nToUpper[]:
       i18nCompareText := i18nInnerCompareText;

SynCommons.pas

@@ -1377,7 +1377,7 @@ function ToUTF8({$IFDEF FPC_HAS_CONSTREF}constref{$ELSE}const{$ENDIF} guid: TGUI
 {$ifndef NOVARIANTS}
 
 type
-  /// function prototype used internally for variant comparaison
+  /// function prototype used internally for variant comparison
   // - used in mORMot.pas unit e.g. by TDocVariantData.SortByValue
   TVariantCompare = function(const V1,V2: variant): PtrInt;
 
@@ -1772,7 +1772,7 @@ function VarRecAsChar(const V: TVarRec): integer;
   {$ifdef HASINLINE}inline;{$endif}
 
 type
-  /// function prototype used internally for UTF-8 buffer comparaison
+  /// function prototype used internally for UTF-8 buffer comparison
   // - used in mORMot.pas unit during TSQLTable rows sort and by TSQLQuery
   TUTF8Compare = function(P1,P2: PUTF8Char): PtrInt;
 
@@ -2814,7 +2814,7 @@ function UpperCopyShort(dest: PAnsiChar; const source: shortstring): PAnsiChar;
 
 {$ifdef USENORMTOUPPER}
 
-/// fast UTF-8 comparaison using the NormToUpper[] array for all 8 bits values
+/// fast UTF-8 comparison using the NormToUpper[] array for all 8 bits values
 // - this version expects u1 and u2 to be zero-terminated
 // - this version will decode each UTF-8 glyph before using NormToUpper[]
 // - current implementation handles UTF-16 surrogates
@@ -2834,15 +2834,15 @@ function UTF8UpperCopy(Dest, Source: PUTF8Char; SourceChars: Cardinal): PUTF8Cha
 function UTF8UpperCopy255(dest: PAnsiChar; const source: RawUTF8): PUTF8Char;
   {$ifdef HASINLINE}inline;{$endif}
 
-/// fast UTF-8 comparaison using the NormToUpper[] array for all 8 bits values
+/// fast UTF-8 comparison using the NormToUpper[] array for all 8 bits values
 // - this version expects u1 and u2 not to be necessary zero-terminated, but
 // uses L1 and L2 as length for u1 and u2 respectively
 // - use this function for SQLite3 collation (TSQLCollateFunc)
 // - this version will decode the UTF-8 content before using NormToUpper[]
 // - current implementation handles UTF-16 surrogates
 function UTF8ILComp(u1, u2: PUTF8Char; L1,L2: cardinal): PtrInt;
 
-/// fast case-insensitive Unicode comparaison
+/// fast case-insensitive Unicode comparison
 // - use the NormToUpperAnsi7Byte[] array, i.e. compare 'a'..'z' as 'A'..'Z'
 // - this version expects u1 and u2 to be zero-terminated
 function AnsiICompW(u1, u2: PWideChar): PtrInt;
@@ -2944,7 +2944,7 @@ function TrimLeft(const S: RawUTF8): RawUTF8;
 // newline, space, and tab characters
 function TrimRight(const S: RawUTF8): RawUTF8;
 
-/// fast WinAnsi comparaison using the NormToUpper[] array for all 8 bits values
+/// fast WinAnsi comparison using the NormToUpper[] array for all 8 bits values
 function AnsiIComp(Str1, Str2: PWinAnsiChar): PtrInt;
   {$ifndef USENORMTOUPPER} {$ifdef PUREPASCAL}
   {$ifdef HASINLINE}inline;{$endif} {$endif} {$endif}
@@ -11259,7 +11259,7 @@ function UInt2DigitsToShortFast(Value: byte): TShort4;
 // - this version is not optimized for speed, but for correctness
 function crc16(Data: PAnsiChar; Len: integer): cardinal;
 
-// our custom hash/checksum function, specialized for Text comparaison
+// our custom hash/checksum function, specialized for Text comparison
 // - it is a checksum algorithm, not a hash function: has less colision than
 // Adler32 for short strings, but more than xxhash32 or crc32/crc32c
 // - written in simple plain pascal, with no L1 CPU cache pollution
@@ -11288,7 +11288,7 @@ function crc16(Data: PAnsiChar; Len: integer): cardinal;
 // $ hash32 9.7KB in 487us i.e. 1,026,694/s, aver. 0us, 9.5 GB/s
 function Hash32(Data: PCardinalArray; Len: integer): cardinal; overload;
 
-// our custom hash/checsum function, specialized for Text comparaison
+// our custom hash/checsum function, specialized for Text comparison
 // - it is a checksum algorithm, not a hash function: has less colision than
 // Adler32 for short strings, but more than xxhash32 or crc32/crc32c
 // - is faster than CRC32 or Adler32, since uses DQWord (128-bit) aligned read
@@ -12152,7 +12152,7 @@ function TimeLogToUnixTime(const Timestamp: TTimeLog): TUnixTime;
 
 /// convert a Iso8601 encoded string into a TTimeLog value
 // - handle TTimeLog bit-encoded Int64 format
-// - use this function only for fast comparaison between two Iso8601 date/time
+// - use this function only for fast comparison between two Iso8601 date/time
 // - conversion is faster than Iso8601ToDateTime: use only binary integer math
 // - ContainsNoTime optional pointer can be set to a boolean, which will be
 // set according to the layout in P (e.g. TRUE for '2012-05-26')
@@ -12161,7 +12161,7 @@ function Iso8601ToTimeLogPUTF8Char(P: PUTF8Char; L: integer; ContainsNoTime: PBo
 
 /// convert a Iso8601 encoded string into a TTimeLog value
 // - handle TTimeLog bit-encoded Int64 format
-// - use this function only for fast comparaison between two Iso8601 date/time
+// - use this function only for fast comparison between two Iso8601 date/time
 // - conversion is faster than Iso8601ToDateTime: use only binary integer math
 function Iso8601ToTimeLog(const S: RawByteString): TTimeLog;
   {$ifdef PUREPASCAL} {$ifdef HASINLINE}inline;{$endif} {$endif}
@@ -26698,7 +26698,7 @@ function AnsiIComp(Str1, Str2: PWinAnsiChar): PtrInt;
 end;
 {$else}
 function AnsiIComp(Str1, Str2: PWinAnsiChar): PtrInt;
-asm // fast 8 bits WinAnsi comparaison using the NormToUpper[] array
+asm // fast 8 bits WinAnsi comparison using the NormToUpper[] array
         cmp     eax, edx
         je      @2
         test    eax, edx // is either of the strings perhaps nil?
@@ -26817,7 +26817,7 @@ function LowerCaseU(const S: RawUTF8): RawUTF8;
 function UTF8IComp(u1, u2: PUTF8Char): PtrInt;
 var c2: PtrInt;
     table: {$ifdef CPUX86NOTPIC}TNormTableByte absolute NormToUpperByte{$else}PNormTableByte{$endif};
-begin // fast UTF-8 comparaison using the NormToUpper[] array for all 8 bits values
+begin // fast UTF-8 comparison using the NormToUpper[] array for all 8 bits values
   {$ifndef CPUX86NOTPIC}table := @NormToUpperByte;{$endif}
   if u1<>u2 then
   if u1<>nil then
@@ -26869,7 +26869,7 @@ function UTF8ILComp(u1, u2: PUTF8Char; L1,L2: cardinal): PtrInt;
     extra,i: integer;
     table: {$ifdef CPUX86NOTPIC}TNormTableByte absolute NormToUpperByte{$else}PNormTableByte{$endif};
 label neg,pos;
-begin // fast UTF-8 comparaison using the NormToUpper[] array for all 8 bits values
+begin // fast UTF-8 comparison using the NormToUpper[] array for all 8 bits values
   {$ifndef CPUX86NOTPIC}table := @NormToUpperByte;{$endif}
   if u1<>u2 then
   if (u1<>nil) and (L1<>0) then

SynLZO.pas

@@ -52,7 +52,7 @@
       written in optimized pascal code for Delphi 3 up to Delphi 2009
       with a tuned asm version available
     * offers *extremely* fast compression and decompression
-      with good compression rate, in comparaison with its speed
+      with good compression rate, in comparison with its speed
     * original LZO written in ANSI C - pascal+asm conversion by A.Bouchez
     * simple but very fast direct file compression:
       SynLZO compressed files read/write is faster than copying plain files!

SynSQLite3.pas

@@ -525,8 +525,8 @@ interface
   // TObject(p).Free
   TSQLDestroyPtr = procedure(p: pointer); cdecl;
 
-  /// SQLite3 collation (i.e. sort and comparaison) function prototype
-  // - this function MUST use s1Len and s2Len parameters during the comparaison:
+  /// SQLite3 collation (i.e. sort and comparison) function prototype
+  // - this function MUST use s1Len and s2Len parameters during the comparison:
   // s1 and s2 are not zero-terminated
   // - used by sqlite3.create_collation low-level function
   TSQLCollateFunc = function(CollateParam: pointer; s1Len: integer; s1: pointer;