% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fmt-text.R
\name{formatting}
\alias{formatting}
\alias{fmt_digits}
\alias{fmt_count}
\alias{fmt_corr}
\alias{fmt_prop}
\alias{fmt_pct}
\alias{fmt_prop_pct}
\title{Text and Number Formatting}
\usage{
fmt_digits(
  x,
  digits = 1,
  big_mark = ",",
  min_value = -Inf,
  max_value = Inf,
  sub_threshold = 1/(10^digits),
  keep_boundary = FALSE,
  ...
)

fmt_count(x, ...)

fmt_corr(x, digits = 3, ...)

fmt_prop(x, digits = 2, ...)

fmt_pct(x, digits = 0, ...)

fmt_prop_pct(x, digits = 0, ...)
}
\arguments{
\item{x}{Number to be formatted.}

\item{digits}{Number of decimal places to retain.}

\item{big_mark}{Character used between every 3 digits to separate thousands.}

\item{min_value}{The minimum value \code{x} can take.}

\item{max_value}{The maximum value \code{x} can take.}

\item{sub_threshold}{The threshold to use when replacing value extremely
close to \code{min_value} or \code{max_value}. By default, this is determined by the
\code{digits} specified.}

\item{keep_boundary}{Whether to preserve true values of boundaries (i.e.,
\code{min_value} and \code{max_value}). For example if \code{digits = 3}, \code{min_value = 0},
and \code{keep_boundary = FALSE}, a value exactly equal to 0 will become
"<.001". If \code{keep_boundary = TRUE}, then a value of 0 will remain "0.000",
and other small values (e.g., 0.000001) will continue to be replaced with
"<.001".}

\item{...}{Additional arguments passed to \code{\link[scales:comma]{scales::number_format()}} or
\code{\link[=fmt_digits]{fmt_digits()}}. See Details for additional information.}
}
\value{
The updated character object of the same length as \code{x}.
}
\description{
These formatting functions are used to format numerical values in a
consistent manner. This is useful for printing numbers inline with text, as
well as for formatting tables.
}
\details{
\code{\link[=fmt_digits]{fmt_digits()}} is a wrapper for \code{\link[scales:comma]{scales::number_format()}} and prints a number
with the specified number of digits, suppressing values close to the minimum
and maximum values as necessary.

Several helper functions are provided that wrap \code{\link[=fmt_digits]{fmt_digits()}} with common
patterns of \code{min_value}, \code{max_value}, and \code{digits}.
\itemize{
\item \code{\link[=fmt_count]{fmt_count()}} is used for formatting integer values. Prints whole numbers
with no decimals.
\item \code{\link[=fmt_corr]{fmt_corr()}} is used to format correlations or similar indices that are
bounded between [-1, 1]. By default, these values report 3 decimal
places, and the leading 0 is removed as required by APA (2020; section
6.36).
\item \code{\link[=fmt_prop]{fmt_prop()}} is used to format proportions or similar indices that are
bounded between [0, 1]. Similar to \code{\link[=fmt_corr]{fmt_corr()}}, leading 0s are removed.
By default, 2 decimal places are reported.
\item \code{\link[=fmt_pct]{fmt_pct()}} is used to format percentage values that are bounded
[0, 100]. By default, no decimal places are reported.
\item \code{\link[=fmt_prop_pct]{fmt_prop_pct()}} formats proportions bounded by [0, 1] as percentages.
That is, we first take \code{x * 100} and then apply \code{\link[=fmt_pct]{fmt_pct()}}.
}
}
\examples{
fmt_digits(runif(5, min = 5, max = 15), digits = 1)
fmt_digits(runif(5, min = 5, max = 15), digits = 3)

fmt_count(sample(10000:99999, size = 5))

fmt_corr(runif(5, min = -1, max = 1))

fmt_prop(runif(5, min = 0, max = 1))

fmt_pct(runif(5, min = 0, max = 100))

fmt_prop_pct(runif(5, min = 0, max = 1))

}
\references{
American Psychological Association. (2020). \emph{Publication manual
of the American Psychological Association} (7th ed.).
\doi{doi:10.1037/0000165-000}
}
\seealso{
Other formatters: 
\code{\link{apa_words}()}
}
\concept{formatters}
