Summary

###########################################################################

	File:     printf.icn

	Subject:  Procedures for printf-style formatting

	Author:   William H. Mitchell

	Date:     March 18, 2021 

###########################################################################

   This file is in the public domain.

###########################################################################

	Contributors:   Cheyenne Wills, Phillip Lee Thomas,
			Michael Glass, Gregg M. Townsend,
			Clinton Jeffery

###########################################################################

 This module provides a family of formatted output functions
 modeled on those found in the C language.

 printf(fmt:string, args[]) formats and writes arguments to &output.
 fprintf(f:file,fmt:string,args[]) formats and writes arguments to f.
 sprintf(fmt:string, args[]) : string formats arguments and returns a string.

 The format string fmt is modified by substituting arguments
 in place of the ``format specifiers'' within it, consisting of a
 percent sign followed by a specifier code.  Specifier codes include

 specifier     arg is printed the form of
 %d		decimal integer
 %e		scientific notation
 %i		image
 %o		octal
 %r		real number. Exponential format if number is larger than int
 %s		string
 %c		character. Like %s only it only prints first letter.
 %x		hexadecimal

 An hyphen after the percent sign indicates left justification,
 otherwise right justification is used. A number of digits after the
 percent sign may specify the width of the field to use, or after a
 period they specify a number of digits of precision. For example,
 printf("%-5.2r", x) specifies that real number x be
 formatted as a string of at least 5 characters, left justified,
 with two digits after the decimal point.

     Code contributions for %f and %g formats that work like 
  C's printf() would be welcome.

     Possible new formats:

	   %t -- print a real number as a time in hh:mm
	   %R -- roman numerals
	   %w -- integers in English
	   %b -- binary

###########################################################################

This file is part of the (main) package.

_basestr(n, b)

_doprnt(format, args)

adjustfracprec(fracpart, prec)

  Zero-extend or round the fractional part to 'prec' digits.

  Returns a list: 

     [ fracpart, carry ]

  where the fracpart has been adjusted to the requested
  precision, and the carry (result of possible rounding)
  is to be added into the whole number.

eformatstr(x, prec, width)

 e-format:  [-]m.dddddde(+|-)xx

 Differs from C and Fortran E formats primarily in the
 details, among them:

 - Single-digit exponents are not padded out to two digits.

 - The precision (number of digits after the decimal point)
   is reduced if needed to make the number fit in the available
   width, if possible.  The precision is never reduced-to-fit
   below 1 digit after the decimal point.

fixnum(x, prec)

fprintf(file, format, args)

hexstr(n)

octstr(n)

printf(format, args)

sprintf(format, args)