lpad

`lpad`

Library: ib_udf

Added in: 1.5

Changed in: 1.5.2, 2.0

Description: Returns the input string left-padded with padchars until endlength is reached.

Result type: VARCHAR(n)

Syntax:

lpad (str, endlength, padchar)

Declaration:

DECLARE EXTERNAL FUNCTION lpad
   CSTRING(255) NULL, INTEGER, CSTRING(1) NULL
   RETURNS CSTRING(255) FREE_IT
   ENTRY_POINT 'IB_UDF_lpad' MODULE_NAME 'ib_udf'
The above declaration is from the file ib_udf2.sql. The NULLs after the CSTRING arguments are an optional addition that became available in Firebird 2. If an argument is declared with the NULL keyword, the engine will pass a NULL argument value unchanged to the function. This leads to a NULL result, which is correct. Without the NULL keyword (your only option in pre-2.0 versions), NULLs are passed to the function as empty strings and the result is a string with endlengh padchars (if str is NULL) or a copy of str itself (if padchar is NULL).

For more information about passing NULLs to UDFs, see the note at the end of this book.

Notes:

Depending on how you declare it (see CSTRING note), this function can accept and return strings of up to 32767 characters.
When calling this function, make sure endlength does not exceed the declared result length.
If endlength is less than str's length, str is truncated to endlength. If endlength is negative, the result is NULL.
A NULL endlength is treated as if it were 0.
If padchar is empty, or if padchar is NULL and the function has been declared without the NULL keyword after the last argument, str is returned unchanged (or truncated to endlength).
Before Firebird 2.0, the result type was CHAR(n).
A bug that caused an endless loop if padchar was empty or NULL has been fixed in 2.0.
In Firebird 1.5.1 and below, the default declaration used CSTRING(80) instead of CSTRING(255).