Parse options

TParseOptions is a set of TParseOption flags passed to ParseInput to control processing after tokenization. The default is [] (no options).

Option reference

Option	Applies to	Effect
opTrim	All types	Trim leading/trailing whitespace from each token before any other processing.
opRequired	All types	Reject empty input; sets ERR_EMPTY_NOT_ALLOWED.
opNotNull	All types	Reject any token that resolved to NULL; sets ERR_NULL_NOT_ALLOWED.
opEmptyStringNull	itString only	Empty string tokens produce NULL instead of ''.
opUpperCase	itString only	Convert token values to upper case.
opLowerCase	itString only	Convert token values to lower case.

opTrim

Strips leading and trailing whitespace from each token value before any other processing. For non-string types (itInteger through itDateTime), spaces are already stripped globally from the entire input before tokenisation. opTrim has no additional effect on those types; it is silently accepted. For itString, spaces are significant by default and are preserved as part of the value. opTrim is the only way to remove them:

Input: "  hello  ", itString, no options
  Values[0]: "  hello  "    (spaces preserved)

Input: "  hello  ", itString, [opTrim]
  Values[0]: "hello"        (spaces stripped)

When opRequired is also set, opTrim is applied first. An input of spaces only becomes empty after trimming and triggers ERR_EMPTY_NOT_ALLOWED.

opRequired

The whole input (after opTrim when present) must not be empty. This check runs before tokenization, so it applies to the entire input string rather than to individual tokens. When the input is empty, ResultType is set to otInvalid and ErrorCode is ERR_EMPTY_NOT_ALLOWED.

Input: "", itInteger, [opRequired]
  ResultType: otInvalid
  ErrorCode:  ERR_EMPTY_NOT_ALLOWED

Input: "  ", itString, [opRequired, opTrim]
  ResultType: otInvalid
  ErrorCode:  ERR_EMPTY_NOT_ALLOWED

opRequired is checked before opNotNull. When both are set and the input is empty, only ERR_EMPTY_NOT_ALLOWED is returned.

opNotNull

After the full token loop, any token whose SQLValues[] entry is NULL causes ErrorCode to be set to ERR_NULL_NOT_ALLOWED. ResultType is set to otInvalid. This option is useful when empty list positions or empty range bounds should be rejected rather than silently translated to NULL.

Input: "1,,3", itInteger, [opNotNull]
  ResultType: otInvalid
  ErrorCode:  ERR_NULL_NOT_ALLOWED   (middle token is NULL)

Input: "1,,3", itInteger, []
  ResultType: otList
  SQLExpression: IN (1, NULL, 3)     (NULL accepted)

opNotNull is not checked when ERR_EMPTY_NOT_ALLOWED has already been set. For itString without opEmptyStringNull, empty tokens produce '' (notNULL), so opNotNull does not trigger for them. Combine opEmptyStringNull with opNotNull to reject both empty strings and null-mapped tokens.

opEmptyStringNull

Applies only to itString. Empty tokens — originally empty input, empty list positions, and quoted empty strings '' — produce NULL in SQLValues[] instead of an empty quoted string ''.

Input: "hello;;world", itString, [opEmptyStringNull]
  SQLValues: ['hello', NULL, 'world']
  SQLExpression: IN ('hello', NULL, 'world')

Input: "hello;;world", itString, []
  SQLValues: ["'hello'", "''", "'world'"]
  SQLExpression: IN ('hello', '', 'world')

When combined with opNotNull, empty string tokens trigger ERR_NULL_NOT_ALLOWED.

opUpperCase / opLowerCase

Convert itString token values to upper or lower case. The conversion is applied to both Values[] and to the content inside SQLValues[] (inside the quotes). SQL keywords such as BETWEEN, IN, NULL, DATE, and TIME are not affected.

Input: "hello", itString, [opUpperCase]
  Values[0]: "HELLO"
  SQLValues[0]: "'HELLO'"

Input: "hello", itString, [opLowerCase]
  Values[0]: "hello"
  SQLValues[0]: "'hello'"

If both opUpperCase and opLowerCase are set, opUpperCase takes precedence. opUpperCase and opLowerCase are silently ignored for all non-string types. Conversion is skipped for tokens that resolved to NULL (e.g. via opEmptyStringNull); the NULL keyword is preserved as-is.

Precedence and interaction summary

Processing order within a ParseInput call:

1. opTrim (when set) — applied to the whole input before any other step.
2. opRequired — checked against the (possibly trimmed) input; aborts with ERR_EMPTY_NOT_ALLOWED if empty.
3. Tokenization — input is split into tokens.
4. Per-token processing — type parsing, opTrim per token (for lists), opEmptyStringNull, opUpperCase/opLowerCase.
5. opNotNull — scanned after the full token loop; aborts with ERR_NULL_NOT_ALLOWED if any SQLValues[] entry is NULL.
6. Range order check — applied after opNotNull.