## This file is part of the 'stringi' package for R.
## Copyright (c) 2013-2019, Marek Gagolewski and other contributors.
## All rights reserved.
##
## Redistribution and use in source and binary forms, with or without
## modification, are permitted provided that the following conditions are met:
##
## 1. Redistributions of source code must retain the above copyright notice,
## this list of conditions and the following disclaimer.
##
## 2. Redistributions in binary form must reproduce the above copyright notice,
## this list of conditions and the following disclaimer in the documentation
## and/or other materials provided with the distribution.
##
## 3. Neither the name of the copyright holder nor the names of its
## contributors may be used to endorse or promote products derived from
## this software without specific prior written permission.
##
## THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
## "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
## BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
## FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
## HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
## PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
## OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
## WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
## OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
## EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


#' @title
#' Locales and \pkg{stringi}
#'
#' @description
#' In this section we explain how we deal with locales in \pkg{stringi}.
#' Locale is a fundamental concept in \pkg{ICU}.
#' It identifies a specific user community, i.e., a group of users
#' who have similar culture and language expectations
#' for human-computer interaction.
#'
#'
#' @details
#' Because a locale is just an identifier of a region,
#' no validity check is performed when you specify a Locale.
#' \pkg{ICU} is implemented as a set of services.
#' If you want to verify whether particular resources are available
#' in the locale you asked for, you must query those resources.
#' Note: when you ask for a resource for a particular locale, you get back
#' the best available match, not necessarily precisely the one you requested.
#'
#' @section Locale Identifiers:
#'
#' \pkg{ICU} services are parametrized by locale,
#' to deliver culturally correct results.
#' Locales are identified by character strings
#' of the form \code{Language} code,
#' \code{Language_Country} code, or \code{Language_Country_Variant}
#' code, e.g., "en_US".
#'
#' The two-letter \code{Language} code uses the ISO-639-1 standard,
#' e.g., "en" stands for English, "pl" -- Polish, "fr" -- French,
#' and "de" for German.
#'
#' \code{Country} is a two-letter code following the ISO-3166 standard.
#' This is to reflect different language conventions within the same language,
#' for example in US-English ("en_US") and Australian-English ("en_AU").
#'
#' Differences may also appear in language conventions used within
#' the same country. For example, the Euro currency may be used in several European
#' countries while the individual country's currency is still in circulation.
#' In such a case, \pkg{ICU} \code{Variant} "_EURO" could be used for selecting
#' locales that support the Euro currency.
#'
#' The final (optional) element of a locale is a list of
#' keywords together with their values. Keywords must be unique.
#' Their order is not significant. Unknown keywords are ignored.
#' The handling of keywords depends on the specific services that
#' utilize them. Currently, the following keywords are recognized:
#' \code{calendar}, \code{colation}, \code{currency}, and \code{numbers},
#' e.g., \code{fr@@collation=phonebook;}\code{calendar=islamic-civil} is a valid
#' French locale specifier together with keyword arguments. For
#' more information, refer to the ICU user guide.
#'
#' For a list of locales that are recognized by \pkg{ICU},
#' call \code{\link{stri_locale_list}}.
#'
#'
#' @section A Note on Default Locales:
#'
#' Each locale-sensitive function in \pkg{stringi}
#' selects the current default locale if an empty string or \code{NULL}
#' is provided as its \code{locale} argument. Default locales are available
#' to all the functions:
#' they are initially set to be the system locale on that platform,
#' and may be changed with \code{\link{stri_locale_set}},
#' for example, if automatic  detection fails to recognize
#' your locale properly.
#'
#' It is suggested that your program should avoid changing
#' the default locale.
#' All locale-sensitive functions may request
#' any desired locale per-call (by specifying the \code{locale} argument),
#' i.e., without referencing to the default locale.
#' During many tests, however, we did not observe any improper
#' behavior of \pkg{stringi} while using a modified default locale.
#'
#' @section Locale-Sensitive Functions in \pkg{stringi}:
#'
#' One of many examples of locale-dependent services is the Collator, which
#' performs a locale-aware string comparison. It is used for string comparing,
#' ordering, sorting, and searching. See \code{\link{stri_opts_collator}}
#' for the description on how to tune its settings, and its \code{locale}
#' argument in particular.
#'
#' Other locale-sensitive functions include, e.g.,
#'  \code{\link{stri_trans_tolower}} (that does character case mapping).
#'
#' @references
#' \emph{Locale} -- ICU User Guide, \url{http://userguide.icu-project.org/locale}
#'
#' \emph{ISO 639: Language Codes},
#' \url{http://www.iso.org/iso/home/standards/language_codes.htm}
#'
#' \emph{ISO 3166: Country Codes}, \url{http://www.iso.org/iso/country_codes}
#' @name stringi-locale
#' @rdname stringi-locale
#' @family locale_management
#' @family locale_sensitive
#' @family stringi_general_topics
invisible(NULL)