$Justify()

Returns a formatted string.

The format for the $JUSTIFY function is:

$J[USTIFY](expr,intexpr1[,intexpr2])

The expression specifies the string to be formatted by $JUSTIFY().
The first integer expression (second argument) specifies the minimum size of the resulting string. If the first integer expression is larger than the length of the expression, $JUSTIFY() right justifies the expression to a string of the specified length by adding leading spaces. Otherwise, $JUSTIFY() returns the expression unmodified unless specified by the second integer argument.
The optional second integer expression (third argument) specifies the number of digits to follow the decimal point in the result, and forces $JUSTIFY() to evaluate the expression as numeric. If the numeric expression has more digits than this argument specifies, $JUSTIFY() rounds to obtain the result. If the expression had fewer digits than this argument specifies, $JUSTIFY() zero-fills to obtain the result.
When the second argument is specified and the first argument evaluates to a fraction between -1 and 1, $JUSTIFY() returns a number with a leading zero (0) before the decimal point (.).

$JUSTIFY() fills expressions to create fixed length values. However, if the length of the specified expression exceeds the specified field size, $JUSTIFY() does not truncate the result (although it may still round based on the third argument). When required, use $EXTRACT() to perform truncation.

$JUSTIFY() optionally rounds the portion of the result after the decimal point. In the absence of the third argument, $JUSTIFY() does not restrict the evaluation of the expression. In the presence of the third (rounding) argument, $JUSTIFY() evaluates the expression as a numeric value. The rounding algorithm can be understood as follows:

If necessary, the rounding algorithm extends the expression to the right with 0s (zeros) to have at least one more digit than specified by the rounding argument.
Then, it adds 5 (five) to the digit position after the digit specified by the rounding argument.
Finally, it truncates the result to the specified number of digits. The algorithm rounds up when excess digits specify a half or more of the last retained digit and rounds down when they specify less than a half.
For a process started in UTF-8 mode, $JUSTIFY() interprets the string argument as UTF-8 encoded. With VIEW “BADCHAR” enabled, $JUSTIFY() produces a run-time error when it encounters a malformed character.
$ZJUSTIFY() is the parallel function of $JUSTIFY(). Irrespective of the settings of VIEW “BADCHAR” and $ZCHSET, $ZJUSTIFY() interprets argument as a sequence of bytes (rather than a sequence of characters) and can perform all byte-oriented $JUSTIFY() operations. For more information, refer to “$ZJustify()”.

Examples of $JUSTIFY()

Example:

GTM>write ":",$justify("HELLO",10),":",!,":",$justify("GOODBYE",5),":"
:     HELLO:
:GOODBYE:
GTM>

This uses $JUSTIFY() to display “HELLO” in a field of 10 spaces and “GOODBYE” in a field of 5 spaces. Because the length of “GOODBYE” exceeds five spaces, the result overflows the specification.

Example:

GTM>write "1234567890",!,$justify(10.545,10,2)
1234567890
     10.55
GTM>

This uses $JUSTIFY() to WRITE a rounded value right justified in a field of 10 spaces. Notice that the result has been rounded up.

Example:

GTM>write "1234567890",!,$justify(10.544,10,2)
1234567890
     10.54
GTM>

Again, this uses $JUSTIFY() to WRITE a rounded value right justified in a field of 10 spaces. Notice that the result has been rounded down.

Example:

GTM>write "1234567890",!,$justify(10.5,10,2)
1234567890
     10.50
GTM>

Once again, this uses $JUSTIFY() to WRITE a rounded value right justified in a field of 10 spaces. Notice that the result has been zero-filled to 2 places.

Example:

GTM>write $justify(.34,0,2)
0.34
GTM>

This example uses $JUSTIFY to ensure that the fraction has a leading zero. Note the use of a second argument of zero in the case that rounding is the only function that $JUSTIFY is to perform.