\HeaderA{icuSetCollate}{Setup Collation by ICU}{icuSetCollate}
\keyword{utilities}{icuSetCollate}
\begin{Description}\relax
Controls the way collation is done by ICU (an optional part of the \R{}
build).
\end{Description}
\begin{Usage}
\begin{verbatim}
icuSetCollate(...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] Named arguments, see \sQuote{Details}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Optionally, \R{} can be built to collate character strings by ICU
(\url{http://www.icu-project.org}).  For such systems,
\code{icuSetCollate} can be used to tune the way collation is done.
On other builds calling this function does nothing, with a warning.

Possible arguments are
\describe{
\item[\code{locale}:] A character string such as \code{"da\_DK"} giving the
country whose collation rules are to be used.  If present, this
should be the first argument.
\item[\code{case\_first}:] \code{"upper"}, \code{"lower"} or
\code{"default"}, asking for upper- or lower-case characters to be
sorted first.  The default is usually lower-case first, but not in
all languages (see the Danish example).
\item[\code{alternate\_handling}:] Controls the handling of
\sQuote{variable} characters (mainly punctuation and symbols).
Possible values are \code{"non\_ignorable"} (primary strength) and
\code{"shifted"} (quaternary strength).
\item[\code{strength}:] Which components should be used?  Possible
values \code{"primary"}, \code{"secondary"}, \code{"tertiary"}
(default), \code{"quaternary"} and \code{"identical"}. 
\item[\code{french\_collation}:] In a French locale the way accents
affect collation is from right to left, whereas in most other locales
it is from left to right.  Possible values \code{"on"}, \code{"off"}
and \code{"default"}.
\item[\code{normalization}:] Should strings be normalized? Possible values
\code{"on"} and \code{"off"} (default). This affects the
collation of composite characters.
\item[\code{case\_level}:] An additional level between secondary and
tertiary, used to distinguish large and small Japanese Kana
characters. Possible values \code{"on"} and \code{"off"} (default).
\item[\code{hiragana\_quaternary}:] Possible values \code{"on"} (sort
Hiragana first at quaternary level) and \code{"off"}.
}
Only the first three are likely to be of interest except to those with a 
detailed understanding of collation and specialized requirements.

Some examples are \code{case\_level="on", strength="primary"} to ignore
accent differences, \code{alternate\_handling="shifted"} to ignore
space and punctuation characters.
\end{Details}
\begin{SeeAlso}\relax
\LinkA{Comparison}{Comparison}, \code{\LinkA{sort}{sort}}

The ICU user guide chapter on collation
(\url{http://www.icu-project.org/userguide/Collate_Intro.html}).
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- c("Aarhus", "aarhus", "safe", "test", "Zoo")
sort(x)
icuSetCollate(case_first="upper"); sort(x)
icuSetCollate(case_first="lower"); sort(x)

icuSetCollate(locale="da_DK", case_first="default"); sort(x)
icuSetCollate(locale="et_EE"); sort(x)
\end{ExampleCode}
\end{Examples}

