lpad

<< lower | FB 2.0 Language Reference | ltrim >>

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 endlength 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).

back to top of page
<< lower | FB 2.0 Language Reference | ltrim >>