From bbe1f17c8017ec99fc5d3c1d8c85eb5616cd89b0 Mon Sep 17 00:00:00 2001 From: Jan Marvin Garbuszus Date: Fri, 1 Nov 2024 11:05:01 +0100 Subject: [PATCH] [docs] extend `wb_add_numfmt()` details with more detailed guides (#1175) * [docs] extend `wb_add_numfmt()` details with more detailed guides * [styles] avoid escaping forward slashes unless in dates --- R/class-workbook-wrappers.R | 54 ++++++++++++++++++++++++++-- R/wb_styles.R | 7 ++-- man/wb_add_numfmt.Rd | 72 ++++++++++++++++++++++++++++++++++++- 3 files changed, 128 insertions(+), 5 deletions(-) diff --git a/R/class-workbook-wrappers.R b/R/class-workbook-wrappers.R index c04f0fbdd..6bcaae284 100644 --- a/R/class-workbook-wrappers.R +++ b/R/class-workbook-wrappers.R @@ -3400,11 +3400,61 @@ wb_add_font <- function( #' Add number formatting to a cell region. You can use a number format created #' by [create_numfmt()]. #' -#' The list of number formats ID is located in the **Details** section of [create_cell_style()]. #' @param wb A Workbook #' @param sheet the worksheet #' @param dims the cell range -#' @param numfmt either an id or a character +#' @param numfmt either an integer id for a builtin numeric font or a character string as described in the ***Details*** +#' +#' @details +#' The list of number formats ID is located in the **Details** section of [create_cell_style()]. +#' +#' ### General Number Formatting +#' - `"0"`: Displays numbers as integers without decimal places. +#' - `"0.00"`: Displays numbers with two decimal places (e.g., `123.45`). +#' - `"#,##0"`: Displays thousands separators without decimals (e.g., `1,000`). +#' - `"#,##0.00"`: Displays thousands separators with two decimal places (e.g., `1,000.00`). +#' +#' ### Currency Formatting +#' - `"$#,##0.00"`: Formats numbers as currency with two decimal places (e.g., `$1,000.00`). +#' - `"[$$-409]#,##0.00"`: Localized currency format in U.S. dollars. +#' - `"¥#,##0"`: Custom currency format (e.g., for Japanese yen) without decimals. +#' - `"£#,##0.00"`: GBP currency format with two decimal places. +#' +#' ### Percentage Formatting +#' - `"0%"`: Displays numbers as percentages with no decimal places (e.g., `50%`). +#' - `"0.00%"`: Displays numbers as percentages with two decimal places (e.g., `50.00%`). +#' +#' ### Scientific Formatting +#' - `"0.00E+00"`: Scientific notation with two decimal places (e.g., `1.23E+03` for `1230`). +#' +#' ### Date and Time Formatting +#' - `"yyyy-mm-dd"`: Year-month-day format (e.g., `2023-10-31`). +#' - `"dd/mm/yyyy"`: Day/month/year format (e.g., `31/10/2023`). +#' - `"mmm d, yyyy"`: Month abbreviation with day and year (e.g., `Oct 31, 2023`). +#' - `"h:mm AM/PM"`: Time with AM/PM format (e.g., `1:30 PM`). +#' - `"h:mm:ss"`: Time with seconds (e.g., `13:30:15` for `1:30:15 PM`). +#' - `"yyyy-mm-dd h:mm:ss"`: Full date and time format. +#' +#' ### Fraction Formatting +#' - `"# ?/?"`: Displays numbers as a fraction with a single digit denominator (e.g., `1/2`). +#' - `"# ??/??"`: Displays numbers as a fraction with a two-digit denominator (e.g., `1 12/25`). +#' +#' ### Custom Formatting +#' - `"_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)`: +#' Custom currency format with parentheses for negative values and dashes for zero values. +#' - `"[Red]0.00;[Blue](0.00);0"`: Displays positive numbers in red, negatives in blue, and zeroes as plain. +#' - `"@"`: Text placeholder format (e.g., for cells with mixed text and numeric values). +#' +#' ### Formatting Symbols Reference +#' - `0`: Digit placeholder, displays a digit or zero. +#' - `#`: Digit placeholder, does not display extra zeroes. +#' - `.`: Decimal point. +#' - `,`: Thousands separator. +#' - `E+`, `E-`: Scientific notation. +#' - `_` (underscore): Adds a space equal to the width of the next character. +#' - `"text"`: Displays literal text within quotes. +#' - `*`: Repeat character to fill the cell width. +#' #' @examples #' wb <- wb_workbook() %>% wb_add_worksheet("S1") %>% wb_add_data("S1", mtcars) #' wb %>% wb_add_numfmt("S1", dims = "F1:F33", numfmt = "#.0") diff --git a/R/wb_styles.R b/R/wb_styles.R index f1107b6f3..d2eaae167 100644 --- a/R/wb_styles.R +++ b/R/wb_styles.R @@ -173,8 +173,11 @@ create_border <- function( #' @export create_numfmt <- function(numFmtId, formatCode) { - # maybe only required in dates - formatCode <- escape_forward_slashes(formatCode) + # in dates a slash does not indicate a fraction, but can be used to + # separate year, month, day + if (grepl("(y{2,4}|m{1,4}|d{1,2})", tolower(formatCode)) && grepl("/", formatCode)) { + formatCode <- escape_forward_slashes(formatCode) + } df_numfmt <- data.frame( numFmtId = as_xml_attr(numFmtId), diff --git a/man/wb_add_numfmt.Rd b/man/wb_add_numfmt.Rd index f2b22b91f..9c2fcdac3 100644 --- a/man/wb_add_numfmt.Rd +++ b/man/wb_add_numfmt.Rd @@ -13,7 +13,7 @@ wb_add_numfmt(wb, sheet = current_sheet(), dims = "A1", numfmt) \item{dims}{the cell range} -\item{numfmt}{either an id or a character} +\item{numfmt}{either an integer id for a builtin numeric font or a character string as described in the \emph{\strong{Details}}} } \value{ The \code{wbWorkbook} object, invisibly. @@ -24,6 +24,76 @@ by \code{\link[=create_numfmt]{create_numfmt()}}. } \details{ The list of number formats ID is located in the \strong{Details} section of \code{\link[=create_cell_style]{create_cell_style()}}. +\subsection{General Number Formatting}{ +\itemize{ +\item \code{"0"}: Displays numbers as integers without decimal places. +\item \code{"0.00"}: Displays numbers with two decimal places (e.g., \code{123.45}). +\item \code{"#,##0"}: Displays thousands separators without decimals (e.g., \verb{1,000}). +\item \code{"#,##0.00"}: Displays thousands separators with two decimal places (e.g., \verb{1,000.00}). +} +} + +\subsection{Currency Formatting}{ +\itemize{ +\item \code{"$#,##0.00"}: Formats numbers as currency with two decimal places (e.g., \verb{$1,000.00}). +\item \code{"[$$-409]#,##0.00"}: Localized currency format in U.S. dollars. +\item \code{"¥#,##0"}: Custom currency format (e.g., for Japanese yen) without decimals. +\item \code{"£#,##0.00"}: GBP currency format with two decimal places. +} +} + +\subsection{Percentage Formatting}{ +\itemize{ +\item \code{"0\%"}: Displays numbers as percentages with no decimal places (e.g., \verb{50\%}). +\item \code{"0.00\%"}: Displays numbers as percentages with two decimal places (e.g., \verb{50.00\%}). +} +} + +\subsection{Scientific Formatting}{ +\itemize{ +\item \code{"0.00E+00"}: Scientific notation with two decimal places (e.g., \code{1.23E+03} for \code{1230}). +} +} + +\subsection{Date and Time Formatting}{ +\itemize{ +\item \code{"yyyy-mm-dd"}: Year-month-day format (e.g., \code{2023-10-31}). +\item \code{"dd/mm/yyyy"}: Day/month/year format (e.g., \code{31/10/2023}). +\item \code{"mmm d, yyyy"}: Month abbreviation with day and year (e.g., \verb{Oct 31, 2023}). +\item \code{"h:mm AM/PM"}: Time with AM/PM format (e.g., \verb{1:30 PM}). +\item \code{"h:mm:ss"}: Time with seconds (e.g., \code{13:30:15} for \verb{1:30:15 PM}). +\item \code{"yyyy-mm-dd h:mm:ss"}: Full date and time format. +} +} + +\subsection{Fraction Formatting}{ +\itemize{ +\item \code{"# ?/?"}: Displays numbers as a fraction with a single digit denominator (e.g., \code{1/2}). +\item \code{"# ??/??"}: Displays numbers as a fraction with a two-digit denominator (e.g., \verb{1 12/25}). +} +} + +\subsection{Custom Formatting}{ +\itemize{ +\item \verb{"_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)}: +Custom currency format with parentheses for negative values and dashes for zero values. +\item \code{"[Red]0.00;[Blue](0.00);0"}: Displays positive numbers in red, negatives in blue, and zeroes as plain. +\item \code{"@"}: Text placeholder format (e.g., for cells with mixed text and numeric values). +} +} + +\subsection{Formatting Symbols Reference}{ +\itemize{ +\item \code{0}: Digit placeholder, displays a digit or zero. +\item \verb{#}: Digit placeholder, does not display extra zeroes. +\item \code{.}: Decimal point. +\item \verb{,}: Thousands separator. +\item \verb{E+}, \verb{E-}: Scientific notation. +\item \verb{_} (underscore): Adds a space equal to the width of the next character. +\item \code{"text"}: Displays literal text within quotes. +\item \code{*}: Repeat character to fill the cell width. +} +} } \examples{ wb <- wb_workbook() \%>\% wb_add_worksheet("S1") \%>\% wb_add_data("S1", mtcars)