cnum: Chinese Numerals Processing

#' Chinese Numerals Conversion
#'
#' Functions to convert between Chinese and Arabic numerals.
#'
#' @param x the Arabic/Chinese numerals to be converted, or a vector of them.
#'   The absolute value must not be greater than 1e+18.
#'
#' @param lang the language of the Chinese numerals. \code{"tc"} for Traditional
#'   Chinese. \code{"sc"} for Simplified Chinese. The default is \code{"tc"},
#'   but this can be changed by setting \code{\link[base]{options}(cnum.lang =
#'   "sc")}.
#'
#' @param mode the scale naming system to be enforced. See the ‘Details’ section
#'   for the list of supported modes.
#'
#' @param financial logical: should the financial numerals be used (\emph{daxie
#'   shuzi})?
#'
#' @param literal logical: should the numerals be converted literally? (e.g. 721
#'   to be converted to "\emph{qi er yi}" instead of "\emph{qibai ershiyi}" and
#'   vice versa)
#'
#' @param single logical: should the return result with one scale character
#'   only? (e.g. 1.5e+08 as "\emph{yi dian wuyi}" instead of "\emph{yiyi
#'   wuqianwan}")
#'
#' @section Details: The following scale naming systems are supported: \itemize{
#'   \item \code{"casual"}: the casual naming system used outside of mainland
#'   China, i.e. 1e+09 is referred to as "\emph{yi zhao}". \item
#'   \code{"casualPRC"}: the casual naming system used in mainland China,
#'   i.e. 1e+9 is referred to as "\emph{yi wanyi}". \item \code{"SIprefix"}:
#'   the SI prefix system used in Taiwan as stipulated in the document
#'   \emph{Names, Definitions and Symbols of the Legal Units of Measurement and
#'   the Decimal Multiples and Submultiples}. \item \code{"SIprefixPRC"}:
#'   the SI prefix system used in mainland China as stipulated in the document
#'   \emph{China Statutory Measurement Units}. \item \code{"SIprefixPRClong"}:
#'   a variant of \code{"SIprefixPRC"} with long prefixes, e.g. 1e+09 is
#'   referred to as "\emph{yi jika}" instead of "\emph{yi ji}". }
#'
#' @inheritSection cnum-package Warnings
#' @section Warnings: The modes \code{"casual"} and \code{"casualPRC"}
#'   implements a “myriad scale” with an interval of 1e+04 for large numbers,
#'   i.e. "\emph{yi}" is 10,000 times of "\emph{wan}", which is different from
#'   some of the interval systems used in ancient Chinese writings.
#'
#' @references The standard for mode \code{"SIprefix"} \emph{Names, Definitions
#'   and Symbols of the Legal Units of Measurement and the Decimal Multiples and
#'   Submultiples} is available from
#'   \url{https://gazette.nat.gov.tw/egFront/detail.do?metaid=108965} (in
#'   Traditional Chinese).
#'
#'   The standard for mode \code{"SIprefixPRC"} \emph{The State Council's Order
#'   on the Unified Implementation of Legal Measurement Units in Our Country}
#'   is available from the PRC State Council's website (in Simplified Chinese).
#'
#' @seealso \link[=tools]{Functions for detetction and extraction}
#'
#' @name conversion
#' @order 1
#'
NULL