EVOLUTION-MANAGER
Edit File: format.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Encode in a Common Format</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for format {base}"><tr><td>format {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Encode in a Common Format</h2> <h3>Description</h3> <p>Format an <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> object for pretty printing. </p> <h3>Usage</h3> <pre> format(x, ...) ## Default S3 method: format(x, trim = FALSE, digits = NULL, nsmall = 0L, justify = c("left", "right", "centre", "none"), width = NULL, na.encode = TRUE, scientific = NA, big.mark = "", big.interval = 3L, small.mark = "", small.interval = 5L, decimal.mark = getOption("OutDec"), zero.print = NULL, drop0trailing = FALSE, ...) ## S3 method for class 'data.frame' format(x, ..., justify = "none") ## S3 method for class 'factor' format(x, ...) ## S3 method for class 'AsIs' format(x, width = 12, ...) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>any <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> object (conceptually); typically numeric.</p> </td></tr> <tr valign="top"><td><code>trim</code></td> <td> <p>logical; if <code>FALSE</code>, logical, numeric and complex values are right-justified to a common width: if <code>TRUE</code> the leading blanks for justification are suppressed.</p> </td></tr> <tr valign="top"><td><code>digits</code></td> <td> <p>how many significant digits are to be used for numeric and complex <code>x</code>. The default, <code>NULL</code>, uses <code><a href="options.html">getOption</a>("digits")</code>. This is a suggestion: enough decimal places will be used so that the smallest (in magnitude) number has this many significant digits, and also to satisfy <code>nsmall</code>. (For the interpretation for complex numbers see <code><a href="Round.html">signif</a></code>.)</p> </td></tr> <tr valign="top"><td><code>nsmall</code></td> <td> <p>the minimum number of digits to the right of the decimal point in formatting real/complex numbers in non-scientific formats. Allowed values are <code>0 <= nsmall <= 20</code>.</p> </td></tr> <tr valign="top"><td><code>justify</code></td> <td> <p>should a <em>character</em> vector be left-justified (the default), right-justified, centred or left alone. Can be abbreviated.</p> </td></tr> <tr valign="top"><td><code>width</code></td> <td> <p><code>default</code> method: the <em>minimum</em> field width or <code>NULL</code> or <code>0</code> for no restriction. </p> <p><code>AsIs</code> method: the <em>maximum</em> field width for non-character objects. <code>NULL</code> corresponds to the default <code>12</code>. </p> </td></tr> <tr valign="top"><td><code>na.encode</code></td> <td> <p>logical: should <code>NA</code> strings be encoded? Note this only applies to elements of character vectors, not to numerical, complex nor logical <code>NA</code>s, which are always encoded as <code>"NA"</code>.</p> </td></tr> </table> <table summary="R argblock"> <tr valign="top"><td><code>scientific</code></td> <td> <p>Either a logical specifying whether elements of a real or complex vector should be encoded in scientific format, or an integer penalty (see <code><a href="options.html">options</a>("scipen")</code>). Missing values correspond to the current default penalty.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>further arguments passed to or from other methods.</p> </td></tr> <tr valign="top"><td><code>big.mark, big.interval, small.mark, small.interval, decimal.mark, zero.print, drop0trailing</code></td> <td> <p>used for prettying (longish) numerical and complex sequences. Passed to <code><a href="formatc.html">prettyNum</a></code>: that help page explains the details.</p> </td></tr> </table> <h3>Details</h3> <p><code>format</code> is a generic function. Apart from the methods described here there are methods for dates (see <code><a href="as.Date.html">format.Date</a></code>), date-times (see <code><a href="strptime.html">format.POSIXct</a></code>) and for other classes such as <code>format.octmode</code> and <code>format.dist</code>. </p> <p><code>format.data.frame</code> formats the data frame column by column, applying the appropriate method of <code>format</code> for each column. Methods for columns are often similar to <code>as.character</code> but offer more control. Matrix and data-frame columns will be converted to separate columns in the result, and character columns (normally all) will be given class <code>"<a href="AsIs.html">AsIs</a>"</code>. </p> <p><code>format.factor</code> converts the factor to a character vector and then calls the default method (and so <code>justify</code> applies). </p> <p><code>format.AsIs</code> deals with columns of complicated objects that have been extracted from a data frame. Character objects and (atomic) matrices are passed to the default method (and so <code>width</code> does not apply). Otherwise it calls <code><a href="toString.html">toString</a></code> to convert the object to character (if a vector or list, element by element) and then right-justifies the result. </p> <p>Justification for character vectors (and objects converted to character vectors by their methods) is done on display width (see <code><a href="nchar.html">nchar</a></code>), taking double-width characters and the rendering of special characters (as escape sequences, including escaping backslash but not double quote: see <code><a href="print.default.html">print.default</a></code>) into account. Thus the width is as displayed by <code>print(quote = FALSE)</code> and not as displayed by <code><a href="cat.html">cat</a></code>. Character strings are padded with blanks to the display width of the widest. (If <code>na.encode = FALSE</code> missing character strings are not included in the width computations and are not encoded.) </p> <p>Numeric vectors are encoded with the minimum number of decimal places needed to display all the elements to at least the <code>digits</code> significant digits. However, if all the elements then have trailing zeroes, the number of decimal places is reduced until <code>nsmall</code> is reached or at least one element has a non-zero final digit; see also the argument documentation for <code>big.*</code>, <code>small.*</code> etc, above. See the note in <code><a href="print.default.html">print.default</a></code> about <code>digits >= 16</code>. </p> <p>Raw vectors are converted to their 2-digit hexadecimal representation by <code><a href="character.html">as.character</a></code>. </p> <p><code>format.default(x)</code> now provides a “minimal” string when <code><a href="isS4.html">isS4</a>(x)</code> is true. </p> <p>The internal code respects the option <code><a href="options.html">getOption</a>("OutDec")</code> for the ‘decimal mark’, so if this is set to something other than <code>"."</code> then it takes precedence over argument <code>decimal.mark</code>. </p> <h3>Value</h3> <p>An object of similar structure to <code>x</code> containing character representations of the elements of the first argument <code>x</code> in a common format, and in the current locale's encoding. </p> <p>For character, numeric, complex or factor <code>x</code>, dims and dimnames are preserved on matrices/arrays and names on vectors: no other attributes are copied. </p> <p>If <code>x</code> is a list, the result is a character vector obtained by applying <code>format.default(x, ...)</code> to each element of the list (after <code><a href="unlist.html">unlist</a></code>ing elements which are themselves lists), and then collapsing the result for each element with <code>paste(collapse = ", ")</code>. The defaults in this case are <code>trim = TRUE, justify = "none"</code> since one does not usually want alignment in the collapsed strings. </p> <h3>References</h3> <p>Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) <em>The New S Language</em>. Wadsworth & Brooks/Cole. </p> <h3>See Also</h3> <p><code><a href="format.info.html">format.info</a></code> indicates how an atomic vector would be formatted. </p> <p><code><a href="formatc.html">formatC</a></code>, <code><a href="paste.html">paste</a></code>, <code><a href="character.html">as.character</a></code>, <code><a href="sprintf.html">sprintf</a></code>, <code><a href="print.html">print</a></code>, <code><a href="formatc.html">prettyNum</a></code>, <code><a href="toString.html">toString</a></code>, <code><a href="encodeString.html">encodeString</a></code>. </p> <h3>Examples</h3> <pre> format(1:10) format(1:10, trim = TRUE) 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) format(c(6.0, 13.1), digits = 2) format(c(6.0, 13.1), digits = 2, nsmall = 1) ## use of scientific format(2^31-1) format(2^31-1, scientific = TRUE) ## a list z <- list(a = letters[1:3], b = (-pi+0i)^((-2:2)/2), c = c(1,10,100,1000), d = c("a", "longer", "character", "string"), q = quote( a + b ), e = expression(1+x)) ## can you find the "2" small differences? (f1 <- format(z, digits = 2)) (f2 <- format(z, digits = 2, justify = "left", trim = FALSE)) f1 == f2 ## 2 FALSE, 4 TRUE ## A "minimal" format() for S4 objects without their own format() method: cc <- methods::getClassDef("standardGeneric") format(cc) ## "<S4 class ......>" </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>