RPAD()

Tip

Find a more recent version at Firebird 5.0 Language Reference: RPAD()

Available in: DSQL, PSQL

Added in: 2.1

Changed in: 2.1.4

Description: Right-pads a string with spaces or with a user-supplied string until a given length is reached.

Result type: VARCHAR or BLOB

Syntax:

RPAD (str, endlen [, padstr])
This function fully supports text BLOBs of any length and character set.

If str is a BLOB, the result is a BLOB. Otherwise, the result is a VARCHAR(32765) in versions 2.1–2.1.3, and a VARCHAR(endlen) in versions 2.1.4 and up.

If padstr is given and equals '' (empty string), no padding takes place.

If endlen is less than the current string length, the string is truncated to endlen, even if padstr is the empty string.

Important

If the external function RPAD is declared in your database, it will override the internal function. To make the internal function available, DROP or ALTER the external function (UDF).

Tip

In versions 2.1–2.1.3, it is generally wise to cast VARCHAR(32765) results to a smaller size, especially in queries that return more than one column. Otherwise, a “block size exceeds implementation restriction” error may occur. In Firebird 2.1.4 and up, where the formal size matches the actual length, this is no longer an issue.

Examples:

rpad ('Hello', 12)                 -- returns 'Hello       '
rpad ('Hello', 12, '-')            -- returns 'Hello-------'
rpad ('Hello', 12, '')             -- returns 'Hello'
rpad ('Hello', 12, 'abc')          -- returns 'Helloabcabca'
rpad ('Hello', 12, 'abcdefghij')   -- returns 'Helloabcdefg'
rpad ('Hello', 2)                  -- returns 'He'
rpad ('Hello', 2, '-')             -- returns 'He'
rpad ('Hello', 2, '')              -- returns 'He'

Warning

When used on a BLOB, this function may need to load the entire object into memory. Although it does try to limit memory consumption, this may affect performance if huge BLOBs are involved.