8.3. String Functions - 8.3.15. RPAD() - 《Firebird 2.5 Language Reference》

8.3.15. RPAD()

8.3.15. `RPAD()`

Available in

DSQL, PSQL

Changed in

2.5 (backported to 2.1.4)

Possible name conflict

YES → Read details

Syntax

RPAD (str, endlen [, padstr])

Table 137. `RPAD` Function Parameters
Parameter	Description
str	An expression of a string type
endlen	Output string length
endlen	The character or string to be used to pad the source string up to the specified length. Default is space (`‘ ‘`)

Result type

VARCHAR or BLOB

Description

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

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(*endlen*).
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.

In Firebird 2.1-2.1.3, all non-BLOB results were of type VARCHAR(32765), which made it advisable to cast them to a more modest size. This is no longer the case.

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'

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.