LTRIM

Start of change The LTRIM function removes bytes from the beginning of a string expression based on the content of a trim expression. End of change


>>-LTRIM--(--string-expression--+--------------------+--)------><
                                '-,--trim-expression-'

The schema is SYSIBM.

Start of change The LTRIM function removes all of the characters that are contained in trim-expression from the beginning of string-expression. The search is done by comparing the binary representation of each character (which consists of one or more bytes) in trim-expression to the bytes at the beginning of string-expression. If the string-expression is defined as FOR BIT DATA, the search is done by comparing each byte in trim-expression to the byte at the beginning of string-expression. End of change

string-expression

An expression that specifies the source string. The argument must be an expression that returns a value that is a built-in string data type that is not a LOB, or a numeric data type. If the value is not a string data type, it is implicitly cast to VARCHAR before the function is evaluated. If string-expression is not FOR BIT DATA, trim-expression must not be FOR BIT DATA. End of change

trim-expression

An expression that specifies the characters to remove from the beginning of string-expression. The expression must return a value that is a built-in string data type that is not a LOB, or a numeric data type. If the value is not a string data type, it is implicitly cast to VARCHAR before the function is evaluated.

The default for trim-expression depends on the data type of string-expression:

A DBCS blank if string-expression is a DBCS graphic string. For ASCII, the CCSID determines the hex value that represents a DBCS blank. For example, for Japanese (CCSID 301), X'8140' represents a DBCS blank, while for Simplified Chinese, X'A1A1' represents a DBCS blank. For EBCDIC, X'4040' represents a DBCS blank.
A UTF-16 or UCS-2 blank (X'0020') if string-expression is a Unicode graphic string.
A value of X'00' if string-expression is a binary string.
Otherwise, a single byte blank. For EBCDIC, X'40' represents a blank. If not EBCDIC, X'20' represents a blank.

string-expression and trim-expression must have compatible data types. If string-expression and trim-expression have different CCSID sets, trim-expression is converted to the CCSID of string-expression.

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

VARCHAR if string-expression is a character string. If string-expression is defined as FOR BIT DATA the result is FOR BIT DATA.
VARGRAPHIC if string-expression is a graphic string.
VARBINARY if string-expression is a binary string.

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

The actual length of the result for a character or binary string is the length of string-expression minus the number of bytes that are removed. The actual length of the result for a graphic string is the length (in the number of double byte characters) of string-expression minus the number of double byte characters removed. If all of the characters bytes are removed, the result is an empty string (the length is zero).

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

The CCSID of the result is the same as that of string-expression.

Example: Use the LTRIM function to remove individual numbers in the second argument from the beginning (left side) of the first argument:

SELECT LTRIM ('123DEFG123', '321'),
			 LTRIM ('12DEFG123', '321'),
			 LTRIM ('123123222XYZ22', '123'),
			 LTRIM ('12321', '213'),
			 LTRIM ('XYX123 ', '321')
   FROM SYSIBM.SYSDUMMY1

The result is 'DEFG123', 'DEFG123', 'XYZ22', '' (an empty string - all characters removed), and 'XYX123' (no characters removed).

The LTRIM function does not remove instances of '1', '2', and '3' on the right side of the string, following characters that are not '1', '2', or '3'.

Example: Use the LTRIM function to remove individual special characters in the second argument from the beginning (left side) of the first argument:

SELECT LTRIM ('[[ -78]]', '- []')
   FROM SYSIBM.SYSDUMMY1

The result is '78]]'.

Example: Use the LTRIM function to remove dollar signs and periods in the second argument from the beginning (left side) of the first argument:

SELECT LTRIM ('...$V..$AR', '$.')
   FROM SYSIBM.SYSDUMMY1

The result is 'V..$AR'.

Example: Use the LTRIM function to trim full multi-byte X'D090' characters:

Assume that these strings are encoded in UTF-8.

SELECT LTRIM (X'D090D091D092', X'D090')  
   FROM SYSIBM.SYSDUMMY1

The result is X'D091D092'.

Note that the function does not remove individual bytes x'D0' and x'90'.