mORMot模糊概念--FormatSQL-第1部分

mORMot 的 Fast Format 到底是% 还是 ？ 作为参数！，先看看关键代码。

下面是代码原始注释

function FormatSql(const Format: RawUtf8;  const Args, Params: array of const): RawUtf8;

fast Format() function replacement, handling % but also ? inlined parameters

• will include Args[] for every % in Format
• will include Params[] for every ? in Format, as "inlined" ORM or DB values,
  e.g. :(1234): for numbers, and ????'quoted '' string'): for text
• note that, due to a Delphi compiler limitation, cardinal values should be
  type-casted to Int64() (otherwise the integer mapped value will be converted)
• is a wrapper around FormatParams(Format, Args, Params, false, result);

快速Format()函数替代，处理%和?内联参数

• Format中每个%都将包含Args[]
• Format中每个?都将包含Params[]，作为“内联”ORM或DB值，
  例如，数字用:(1234):表示，文本用:('quoted '' string'):表示
• 请注意，由于Delphi编译器的限制，基数值应转换为Int64()（否则映射的整数值将被转换）
• 是FormatParams(Format, Args, Params, false, result)的包装函数；

注：

1. “Args[] for every % in Format” 指的是，在Format字符串中，每一个百分号（%）都将对应一个Args数组中的元素，用于替换该百分号。
2. “Params[] for every ? in Format” 指的是，在Format字符串中，每一个问号（?）都将对应一个Params数组中的元素，这个元素可能是一个ORM（对象关系映射）值或者数据库值。
3. “cardinal values should be type-casted to Int64()” 指的是，由于Delphi编译器的某些限制，需要将基数值（无符号整数值）显式转换为Int64类型，以避免整数值的自动转换可能引发的问题。
4. “wrapper around FormatParams” 指的是，这个函数实质上是对另一个函数FormatParams的封装，使得调用更加简便，或者增加了额外的功能。

function FormatJson(const Format: RawUtf8; const Args, Params: array of const): RawUtf8;

fast Format() function replacement, handling % but also ? parameters as JSON

• will include Args[] for every % in Format
• will include Params[] for every ? in Format, as their JSON value, with
  proper JSON double quotes and escaping for strings
• note that, due to a Delphi compiler limitation, cardinal values should be
  type-casted to Int64() (otherwise the integer mapped value will be converted)
• is a wrapper around FormatParams(Format, Args, Params, true, result);

快速Format()函数的替代品，处理%同时也处理?参数作为JSON

• 将为每个在Format中出现的%包含Args[]
• 将为每个在Format中出现的?包含Params[]，作为它们的JSON值，字符串会使用适当的JSON双引号和转义字符
• 注意，由于Delphi编译器的限制，基数值应该被类型转换为Int64()（否则映射的整数值将被转换）
• 是FormatParams(Format, Args, Params, true, result)的包装函数；

{$ifndef PUREMORMOT2} 
   // rather call FormatSql() and FormatJson() functions
   // 更应该调用 FormatSql() and FormatJson() 使代码清晰
function FormatUtf8(const Format: RawUtf8; const Args, Params: array of const; JsonFormat: boolean = false): RawUtf8; overload;
{$endif PUREMORMOT2}

fast Format() function replacement, handling % and ? parameters

• call rather FormatSql() and FormatJson() wrappers instead
• resulting string has no length limit and uses fast concatenation
• any supplied TObject instance will be written as their class name

快速Format()函数替代，处理%和?参数

• 请改用FormatSql()和FormatJson()包装函数
• 生成的字符串没有长度限制，并使用快速连接
• 任何提供的TObject实例都将以其类名写入

从下面两段示例可以看出他们的区别

procedure TForm1.Button1Click(Sender :TObject);
var
  SearchPhrase :RawUtf8;
begin  //sql 文字替换
  SearchPhrase:='abcde' ;
  Edit2.Caption := mormot.core.json.FormatUtf8(' %   MATCH ? ORDER BY rank DESC ', ['SearchTable'], [SearchPhrase]);    SearchPhrase:='abcde' ;
  Edit1.Caption := mormot.core.json.FormatUtf8(' %   MATCH ? ORDER BY rank DESC ', ['SearchTable'], [123]);
end;

procedure TForm1.Button2Click(Sender :TObject);
var
  SearchPhrase :RawUtf8;
begin  //json 文字替换
  SearchPhrase:='abcde' ;
  Edit2.Caption := mormot.core.json.FormatUtf8(' %   MATCH ? ORDER BY rank DESC ', ['SearchTable'], [SearchPhrase],True);    SearchPhrase:='abcde' ;
  Edit1.Caption := mormot.core.json.FormatUtf8(' %   MATCH ? ORDER BY rank DESC ', ['SearchTable'], [123],True);
end;

上面的输出是：
SearchTable MATCH :('abcde'): ORDER BY rank DESC
SearchTable MATCH :(123): ORDER BY rank DESC

据说mormot 带上 :( ): 是为了优化数据查询，估计是内存中吧！这并不是数据库的特性。

下面的输出是：
SearchTable MATCH 123 ORDER BY rank DESC
SearchTable MATCH "abcde" ORDER BY rank DESC