# $EPIC: pad.txt,v 1.3 2007/03/02 02:32:04 jnelson Exp $
======Synopsis:======
$__pad__(<width> <char> <text>)

======Technical:======
   * The <char> argument is a [[what is a word|dword]] which is different from most function arguments.
   * If the <width> argument is omitted the empty string is returned.
   * If the <char> argument is omitted the empty string is returned.
   * The <width> argument may be positive or negative.
   * Although the <char> argument can be a string, only the first character is actually used.
   * If the absolute value of <width> is less than the length of <text>, then <text> is returned.
   * The number of "neccesary repetitions" is ([[abs]](<width>) - [[strlen]](<text>)).
   * If <width> is negative, then the return value is "neccesary repetitions" of the first character in <char> prepended to <text>.
   * If <width> is positive, then the return value is "neccesary repetitions" of the first character in <char> appended to <text>.

======Practical:======
This function is especially useful for forcing strings to a minimum
length, possibly for a script that hooks and displays a /[[names]] reply.

======Returns:======
<text> padded with a number of <char>s until its length is <length>

======Examples:======
<file>
$pad(8 ! test)                       returns "test!!!!"
</file>

======History:======
This function first appeared in EPIC4pre1.046