**CIGAL Reference Manual, Chapter 3 (Functions): FORMAT**
===== FORMAT -- Convert data values to character string, specifying format =====
**usage: str = format(fmtstring,varb1,varb2,...)**

The FORMAT function converts data variables to a character string according to the
conversion format specified in the FMTSTRING argument.  This function converts single-valued
variables to a character string.  To convert multi-valued variables to text use the FTYPE
command (the output of FTYPE can be displayed on the screen, stored in a text file, or
stored in a string list variable (see [[jvs:cigal:manual:chapter2:ftype|FTYPE(2)]])).

The format command string FMTSTRING specifies the output string according to the following rules:
   1) FMTSTRING characters not preceded by \ or % copy directly to the output
      string.
   2) the character \ followed by one or more characters convert according
      to the following table:
        \b   BACKSPACE character (10o)      \t   spaces to next TAB (see [TAB][4])
        \e   ESCAPE character (33o)         \\   \ character
        \f   FORMFEED character (14o)       \'   ' character
        \n   NEWLINE character (12o)        \"   " character
        \r   RETURN character (15o)
        \nnn where nnn are digits 0-7, results in the ascii character with
             value NNN (octal)
   3) 2 % characters (%%) are converted to a single % character on output.
   4) the character % followed by character(s) of the form:
                         %N.M<charcode>
      (where N and M are optional numbers and CHARCODE is a letter), are replaced
      with the ascii string for the value of the next element in the data list.
      Unless otherwise indicated, if N is specified it indicates the number of
      characters in the output string.  If N is negative, the converted output is
      left justified within the N space field, otherwise it is right justified.
      If the number N starts with a 0 and the output converts to a number, the
      justified field is padded with 0's instead of blanks.  The type of data
      conversion and the meaning of M depend upon the CHARCODE, as follows:
          s   copy character string variable to output
          d   convert an integer in base 10 (decimal)
          b   convert an integer in base 2 (binary)
          q   convert an integer in base 4
          o   convert an integer in base 8 (octal)
          h   convert an integer in base 16 (hexidecimal)
          x   convert an integer in base 16 (hexidecimal)
          i   convert an integer using the current value of the system variable
              OBASE as the number base
          f   convert a floating point value with M digits to the right of the
              decimal point (Note: you can use any of the characters .,:;_/ to
              separate the integral and decimal parts; see examples)
          v   convert a vector variable to 6 output values
          c   convert a value to the single character with that ascii code
          C   convert an array of values as a string of ascii characters
          (   repeat the format between here and the corresponding %), N times
          )   paired with a %( for repeating format specifications
          t   space over to the N'th output character
  
     Note: CHARCODEs FIDBQOHX and # are also recognized as format codes by
          the FTYPE command, but not by the FORMAT command.
  
Examples:
     Assume variables  a=123.654  b=92.123  d=12  m=2  i1={113,97,48,49}
  
      format("Val=%5.2f degrees",a)       -->    Val=12.65 degrees
      format("%d/%d/%d\n",d,m,b)          -->    12/2/92<Newline>
      format("%3(%3o %)\n",a,b,d)         -->    173 134  14 <Newline>
      format("%C %c",i1,d)                -->    qb01 <Formfeed>
      format("%5:2f %05/2f",hour,day)     -->    15:05 09/04

**See Also:**\\
[[jvs:cigal:manual:chapter2:ftype|FTYPE(2)]], 
[[jvs:cigal:manual:chapter4:obase|OBASE(4)]], 
[[jvs:cigal:manual:chapter4:tab|TAB(4)]], 
[[jvs:cigal:manual:chapter4:tabs|TABS(4)]], 
[[jvs:cigal:manual:chapter1:variables|VARIABLES(1)]]

[[jvs:cigal|CIGAL Home]], 
[[jvs:cigal:manual|CIGAL Manual]], 
[[jvs:cigal:manual:chapter3|Functions List]], 
[[jvs:cigal:manual:help|Manual Help]]