Automation Engine Script Guide > Ordered by Function > Strings > STR_PAD

STR_PAD

Script Function: Extends a string to a certain length.

Syntax

STR_PAD(String, [Character], Total Length, Position)

Syntax	Description/Format
String	The string that should be extended. Format: script literal or script variable
Character	Any character that will be used to extend the string. Format: AE name, script literal or script variable Default value: " "
Total Length	The length to which the string should be extended. Format: a number without inverted commas, script literal or script variable
Position	The string's position. Format: script literal or script variable Allowed values: "LEFT" - The string will be positioned to the left. "RIGHT" - The string will be positioned to the right. "CENTER" - The string will be positioned in the center.

Return codes
The extended string.

Comments

This script function extends a string to a certain length. You specify the character that should be used for the extension in the parameter Character. By default, blanks are used.

You can also define the order in which the string should be shown in the result (parameter Position). The possible values are left, right and center.
Center means that the required characters will be equally positioned to the left and to the right of the string. If the number of characters that are required to extend the string is not even, the position to the right of the string will include one character more than the position to the string's left.

Examples

The following example increases one and the same string in three different ways and writes the result to the activation protocol.

:SET &STRING# = "UC4 String"
:SET &STRLEN# = 15
:SET &STRNEW# = STR_PAD(&STRING#, ".", &STRLEN#, "LEFT")
:PRINT &STRNEW#
:SET &STRNEW# = STR_PAD(&STRING#,, &STRLEN#, "CENTER")
:PRINT &STRNEW#
:SET &STRNEW# = STR_PAD(&STRING#, "_", &STRLEN#, "RIGHT")
:PRINT &STRNEW#

The following result is written to the activation protocol:

UC4 String.....
UC4 String
_____UC4 String