home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d110 / pdc.lha / Pdc / lib / format.doc < prev    next >
Text File  |  1987-10-28  |  4KB  |  106 lines
  1. This package is a set of routines for formatting data in a more flexible
  2. way than UNIX's printf routines.  In the simplest case:
  3.  
  4.          format("This is a test.\n");
  5.  
  6. works the way
  7.  
  8.          printf("This is a test.\n");
  9.  
  10. does.  However, printf uses percents (%) to denote substitutions.  Format
  11. encloses substitutions with braces ({ and }).  I.E. {s} denotes "substitute
  12. the next argument as a string."  After the letter denoting the substitution
  13. type, modifiers may be supplied.  {sl5} means print a string left justified
  14. to 5 characters.  If the value is not supplied, it is taken from the
  15. argument list.  The EBNF for this is:
  16.  
  17.          '{' <type-letter> { <modifier-character> [ <modifier-value> ] } '}'
  18.  
  19. Available type letters so far are:
  20.  
  21.          s         string (Char *)
  22.          i         int
  23.          l         long
  24.          c         character
  25.          f         float (double)
  26.          S         Another format string (I smell recursion)
  27.  
  28. Available modifers (and their defaults) are:
  29.  
  30.          l(0)      Number of columns to take up, value will be left justified
  31.          r(0)      Number of columns to take up, value will be right justified
  32.          c(0)      Number of columns to take up, value will be centered
  33.          m(0)      Maximum number of columns display of data
  34.          .(6)      Number of places to display to the right of the decimal point
  35.          b(10)     Base of number
  36.          p(32)     Ascii value of pad character for l, r or c.
  37.          u(0)      Unsigned status (signed=0, unsigned!=0)
  38.          n(1)      Count of times to repeat string
  39.  
  40. If a modifer value is followed by a string of digits then that string is
  41. converted to an integer and used as the modifier's value, else the value will
  42. be taken from the next argument to format.
  43.  
  44. Some ridiculous variable type/modifer combinations exist:
  45.          What is an unsigned string (or character) of base 8 with 4 trailing
  46.              decimal places? (All three modifiers are ignored)
  47.          Do you really want to see floating point variables in base 3?  (Yes!)
  48.          What does centering a left or right justifed variable look like?
  49.              (The last justification character is the one used)
  50.  
  51. Now, an example program:
  52.  
  53.          main()
  54.          {
  55.          int i;
  56.  
  57.          format("Left justified integer:  '{il10}'\n",1234);
  58.          format("###{f.1c}###\n",123.4,20);
  59.          format("Octal:  {lb8r11pu1}\n",01234L,'0');
  60.          format("Truncate this:  {sm10}\n", "This is a test" );
  61.          format("Print 5 arfs:  {sn5}\n","arf");
  62.          i = 1;
  63.          format("Do it {i} time{sn}.\n",i,"s",i!=1);
  64.          i = 2;
  65.          format("Do it {i} time{sn}.\n",i,"s",i!=1);
  66.          format("Center this: ###{Sc20p}###\n","Answer={i}",'$',1234);
  67.          exit(0);
  68.          }
  69.  
  70. and its standard output:
  71.  
  72.          Left justified integer:  '1234      '
  73.          ###        123.4       ###
  74.          Octal:  00000001234
  75.          Truncate this:  This is a
  76.          Print 5 arfs:  arfarfarfarfarf
  77.          Do it 1 time.
  78.          Do it 2 times.
  79.          Center this: ###$$$$$Answer=1234$$$$###
  80.  
  81. The following flavors of format are available:
  82.  
  83.          format( formatstring, args... )                   Send to standard out
  84.          fformat( stream, formatstring, args... )Send to specified stream
  85.          i = cformat( formatstring, args... )    Calculate number of chars
  86.          sformat( buf, formatstring, args... )   Send to the character array buf
  87.          ptr = mformat( formatstring, args... )  Malloc enough space for result
  88.                                                            (and trailing 0), put the
  89.                                                            result in malloced space, and
  90.                                                            return pointer to it
  91.                                  Also, as a kluge:
  92.          ptr = sformat( NULL, formatstring, args... )
  93.  
  94. mformat (and sformat with a NULL array), perform the format twice,
  95. once to find out how many characters needed to malloc, and the next
  96. time to fill up the array.
  97.  
  98. Advantages:
  99.          Easier to understand justification
  100.          Centering available
  101.          More flexible padding (instead of just spaces or zeros)
  102.          Arbitrary base output (2 to 36)
  103.          Complex formats available ("S")
  104.          Arbitrarily lengthed everything (up do what you can malloc)
  105.          And from my point of view, I have the source!
  106.