format                 package:base                 R Documentation

Encode in a Common Format

Description:

     Format an R object for pretty printing: `format.pval' is intended
     for formatting p-values.

Usage:

     format(x, ...)
     format.AsIs(x, width = 12, ...)
     format.data.frame(x, ..., justify = "none") 
     format.default(x, trim = FALSE, digits = getOption("digits"),
                    nsmall = 0, justify = c("left", "right", "none"), ...)
     format.factor(x, ...)
     format.pval(pv, digits = max(1, getOption("digits") - 2),
                 eps = .Machine$double.eps, na.form = "NA")

Arguments:

       x: any R object (conceptually); typically numeric.

    trim: logical; if `TRUE', leading blanks are trimmed off the
          strings.

  digits: how many significant digits are to be used for `numeric x'.
          This is a suggestion: enough decimal places will be used so
          that the smallest (in magnitude) number has this many
          significant digits.

  nsmall: number of digits which will always appear to the right of the
          decimal point in formatting real/complex numbers in
          non-scientific formats. Allowed values `0 <= nsmall <= 20'.

 justify: should character vector be left-justified, right-justified or
          left alone.  When justifying, the field width is that of the
          longest string.

      pv: a numeric vector.

     eps: a numerical tolerance: see Details.

 na.form: character representation of `NA's.

   width: the returned vector has elements of at most `width'.

     ...: further arguments passed to or from other methods.

Details:

     These functions convert their first argument to a vector (or
     array) of character strings which have a common format (as is done
     by `print'), fulfilling `length(format*(x, *)) ==  length(x)'. 
     The trimming with `trim = TRUE' is useful when the strings are to
     be used for plot `axis' annotation.

     `format.AsIs' deals with columns of complicated objects that have
     been extracted from a data frame.

     `format.pval' is mainly an auxiliary function for
     `print.summary.lm' etc., does separate formatting for fixed,
     floating point and very small values (those `< eps').

     The function `formatC' provides a rather more flexible formatting
     facility for numbers, but does not provide a common format for
     several numbers, nor it is platform-independent.

     `format.data.frame' formats the data frame column by column,
     applying the appropriate method of `format' for each column.

Note:

     Currently `format' drops trailing zeroes, so `format(6.001,
     digits=2)' gives `"6"' and `format(c(6.0, 13.1), digits=2)' gives
     `c(" 6", "13")'.

     Character(s) `"' in input strings `x' are escaped to `\"'.

See Also:

     `formatC', `paste', `as.character'.

Examples:

     format(1:10)

     zz <- data.frame("(row names)"= c("aaaaa", "b"), check.names=FALSE)
     format(zz)
     format(zz, justify="left")

     ## use of nsmall
     format(13.7)
     format(13.7, nsmall=3)

     ## handling of quotes
     zz <- data.frame(a=I("abc"), b=I("def\"gh"))
     format(zz)

     p <- c(47,13,2,.1,.023,.0045, 1e-100)/1000
     format.pval(p)
     format.pval(p / 0.9)
     format.pval(p / 0.9, dig=3)

