$Center

From m204wiki
Revision as of 00:00, 13 September 2013 by JALWiccan (talk | contribs) (Automatically generated page update)
Jump to navigation Jump to search

Center string

Note: Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $Center function is the Center function or alias Centre.

This function builds a string of an indicated length containing a centered input string.

The $Center function accepts three arguments and returns a string result that contains the first argument string, centered in an area with leading and trailing pad characters.

The first argument is the string to be centered.

The second argument is the length of the output string. If this argument is negative or greater than 255, the request is canceled. Omitting this argument invokes a special usage of $Center, as described at the end of this section.

The third argument is a pad character to be used for centering the result string. This is an optional argument and defaults to blank.

Syntax

%STRING = $Center(string, length, [pad])

%STRING is a string containing the first argument string.

For example

%JUNK = $Center('PAGE TITLE', 12)

sets %JUNK to ' PAGE TITLE ' and

%JUNK = $Center('PAGE', 5)

sets %JUNK to 'PAGE ' and

%JUNK = $Center('PAGE', 1)

sets %JUNK to 'A' and

%JUNK = $Center('PAGE', 2)

sets %JUNK to 'AG' and

%JUNK = $Center('PAGE TITLE', 17, '-')

sets %JUNK to '---PAGE TITLE----'.

There is also an alternate usage for $Center, if the second argument (length is omitted. In this case, the third argument is ignored, and the first argument must be of the form:

lenpstring

Where:

len The first three bytes of the argument must be a decimal number which is at least as long as the string (trailing) portion of the argument. This number is used as the result length, containing the centered string.
p The fourth byte of the argument is the pad character for the output. The pad characters just before and just after the centered string in the output are each replaced by a blank.
string The string to be centered; this can be from 1 to 251 bytes in length.

If this form of $Center is used and any of the above restrictions are not met, the value returned by $Center is a single digit '1'. Note that this error return value is indistinguishable only to the valid invocation $Center('001p1'), where p is any pad character.

Products authorizing $Center