ARROW-13886 [R] Expand documentation for decimal()

r/R/type.R

@@ -180,15 +180,30 @@ NestedType <- R6Class("NestedType", inherit = DataType)
 #' types, this conversion can be disabled (so that `int64` always yields a
 #' `bit64::integer64` object) by setting `options(arrow.int64_downcast =
 #' FALSE)`.
+#' `decimal()` creates a `decimal128` type. Arrow decimals are fixed-point
+#' decimal numbers encoded as a scalar integer. The `precision` is the number of
+#' significant digits that the decimal type can represent; the `scale` is the
+#' number of digits after the decimal point. For example, the number 1234.567
+#' has a precision of 7 and a scale of 3. Note that `scale` can be negative.
+#'
+#' As an example, `decimal(7, 3)` can exactly represent the numbers 1234.567 and
+#' -1234.567 (encoded internally as the 128-bit integers 1234567 and -1234567,
+#' respectively), but neither 12345.67 nor 123.4567.
+#'
+#' `decimal(5, -3)` can exactly represent the number 12345000 (encoded
+#' internally as the 128-bit integer 12345), but neither 123450000 nor 1234500.
 #'
 #' @param unit For time/timestamp types, the time unit. `time32()` can take
 #' either "s" or "ms", while `time64()` can be "us" or "ns". `timestamp()` can
 #' take any of those four values.
 #' @param timezone For `timestamp()`, an optional time zone string.
 #' @param byte_width byte width for `FixedSizeBinary` type.
 #' @param list_size list size for `FixedSizeList` type.
-#' @param precision For `decimal()`, precision
-#' @param scale For `decimal()`, scale
+#' @param precision For `decimal()`, the number of significant digits
+#'    the arrow `decimal` type can represent. Currently `decimal()` is mapped
+#'    to `DecimalType128`, having a maximum precision of 38 significant digits.
+#' @param scale For `decimal()`, the number of digits after the decimal
+#'    point. It can be negative.
 #' @param type For `list_of()`, a data type to make a list-of-type
 #' @param ... For `struct()`, a named list of types to define the struct columns
 #'
@@ -360,6 +375,12 @@ decimal <- function(precision, scale) {
   } else {
     stop('"precision" must be an integer', call. = FALSE)
   }
+  if (precision > 38) {
+    stop('"precision" must be less than or equal to 38', call. = FALSE)
+  }
+  if (precision < 1) {
+    stop('"precision" must be greater than 0', call. = FALSE)
+  }
   if (is.numeric(scale)) {
     scale <- as.integer(scale)
   } else {

r/tests/testthat/test-data-type.R

@@ -390,8 +390,8 @@ test_that("decimal type and validation", {
   expect_error(decimal(4))
   expect_error(decimal(4, "two"), '"scale" must be an integer')
   expect_error(decimal(NA, 2), '"precision" must be an integer')
-  expect_error(decimal(0, 2), "Invalid: Decimal precision out of range: 0")
-  expect_error(decimal(100, 2), "Invalid: Decimal precision out of range: 100")
+  expect_error(decimal(0, 2), "\"precision\" must be greater than 0")
+  expect_error(decimal(100, 2), "\"precision\" must be less than or equal to 38")
   expect_error(decimal(4, NA), '"scale" must be an integer')
 
   expect_r6_class(decimal(4, 2), "Decimal128Type")