The LTRIM function removes any of the specified characters from the beginning of a string.

The character search compares the binary representation of each character (consisting of one or more bytes) in the trim expression to the binary representation of each character (consisting of one or more bytes) at the beginning of the string expression. The database collation does not affect the search. If the string expression is defined as FOR BIT DATA or is a binary string, the search compares each byte in the trim expression to the byte at the beginning of the string expression.

The schema is SYSIBM. (The SYSFUN version of this function is also available.
That version uses a single parameter, removes leading blanks only, and accepts CLOB arguments.)

string-expression

An expression that specifies the string to be trimmed.

• If only one argument is specified, the expression must return a built-in character string, graphic string, binary string, CLOB or DBCLOB value, numeric value, Boolean value, or datetime value.
  If the value is:
  • A CLOB, numeric, Boolean, or datetime value, it is implicitly cast to VARCHAR before the function is evaluated
  • A DBCLOB value, it is implicitly cast to VARGRAPHIC before the function is evaluated
  The data type of the value cannot be a BLOB (SQLSTATE 42815).
• If both arguments are specified, the expression must return a value that is a built-in character string, numeric value, Boolean value, or datetime value.
  If the data type of the value is numeric or datetime, the value is implicitly cast to VARCHAR before the function is evaluated.
  The actual length of a CLOB value is limited to the maximum size of a VARCHAR data type (SQLSTATE 22001).
  The actual length of a BLOB value is limited to the maximum size of a VARBINARY (SQLSTATE 22001).
  The actual length of a DBCLOB value is limited to the maximum size of a VARGRAPHIC data type (SQLSTATE 22001).

trim-expression

An expression that specifies the characters that are to be removed from the beginning of a string expression.
The expression must return a built-in character string, numeric value, Boolean value, or datetime value.

• If the data type of the trim expression is not a string, then the value is implicitly cast to VARCHAR before the function is evaluated.
• If the data type of the trim expression is a CLOB, then the actual length of the value is limited to the maximum size of a VARCHAR (SQLSTATE 22001).
• If the data type of the trim expression is a DBCLOB, then the actual length of the value is limited to the maximum size of a VARGRAPHIC (SQLSTATE 22001).
• If the data type of the trim expression is BLOB, then the actual length of the value is limited to the maximum size of a VARBINARY (SQLSTATE 22001).
• If the string expression is not defined as FOR BIT DATA, then the trim expression cannot be defined as FOR BIT DATA (SQLSTATE 42815).

The data type of the string expression determines the default trim expression:

• A double byte blank, if the string expression is a graphic string in a DBCS or EUC database
• A UCS-2 blank, if the string expression is a graphic string in a Unicode database
• The value X'20', if the string expression is a FOR BIT DATA string
• The value X'00', if the string expression is a binary string
• A single-byte blank in all other cases

The values for the string expression and trim expression must have compatible data types.
If one function argument is character FOR BIT DATA, then the other argument cannot be a graphic (SQLSTATE 42846).
A combination of character string and graphic string arguments can be used only in a Unicode database (SQLSTATE 42815).

Result

The data type of the result depends on the data type of the string expression:

• VARCHAR if the data type is VARCHAR or CHAR
• CLOB if the data type is CLOB
• VARBINARY if the data type is VARBINARY or BINARY
• BLOB if the data type is BLOB
• VARGRAPHIC if the data type is VARGRAPHIC or GRAPHIC
• DBCLOB if the data type is DBCLOB

The length attribute of the result data type is the same as the length attribute of the data type of the string expression.

The actual length of the result is the length of string-expression minus the number of string units removed.
If all of the characters are removed, the result is an empty string with a length of zero.

If any argument can be null, the result can be null; if any argument is null, the result is the null value.

Examples

1. Use the LTRIM function when the host variable HELLO is defined as CHAR(6) and has a value of " Hello".

      VALUES LTRIM(:HELLO)

   The result is 'Hello'. When a trim-expression is not specified only blanks are removed.


2. Use the LTRIM function to remove the characters specified in the trim-expression from the beginning of the string-expression.

      VALUES LTRIM('...$V..$AR', '$.')

   The result is 'V..$AR'.
   The function stops when it encounters a character not in the trim-expression.


3. Use the LTRIM function to remove the characters specified in the trim-expression from the beginning of the string-expression

      VALUES LTRIM('[[ -78]]', '- []')

   The result is '78]]'.
   When removing characters and blanks, you must include a blank in the trim-expression.