% File src/library/base/man/Comparison.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2020 R Core Team
% Distributed under GPL 2 or later

\name{Comparison}
\alias{<}
\alias{<=}
\alias{==}
\alias{!=}
\alias{>=}
\alias{>}
\alias{Comparison}
\alias{collation}
\title{Relational Operators}
\description{
  Binary operators which allow the comparison of values in atomic vectors.
}
\usage{
x < y
x > y
x <= y
x >= y
x == y
x != y
}
\arguments{
  \item{x, y}{atomic vectors, symbols, calls, or other objects for which
    methods have been written.}
}
\details{
  The binary comparison operators are generic functions: methods can be
  written for them individually or via the
  \code{\link[=S3groupGeneric]{Ops}} group generic function.  (See
  \code{\link[=S3groupGeneric]{Ops}} for how dispatch is computed.)

  Comparison of strings in character vectors is lexicographic within the
  strings using the collating sequence of the locale in use: see
  \code{\link{locales}}.  The collating sequence of locales such as
  \samp{en_US} is normally different from \samp{C} (which should use
  ASCII) and can be surprising.  Beware of making \emph{any} assumptions
  about the collation order: e.g.\sspace{}in Estonian \code{Z} comes between
  \code{S} and \code{T}, and collation is not necessarily
  character-by-character -- in Danish \code{aa} sorts as a single
  letter, after \code{z}.  In Welsh \code{ng} may or may not be a single
  sorting unit: if it is it follows \code{g}.  Some platforms may
  not respect the locale and always sort in numerical order of the bytes
  in an 8-bit locale, or in Unicode code-point order for a UTF-8 locale (and
  may not sort in the same order for the same language in different
  character sets).  Collation of non-letters (spaces, punctuation signs,
  hyphens, fractions and so on) is even more problematic.

  Character strings can be compared  with different marked encodings
  (see \code{\link{Encoding}}): they are translated to UTF-8 before
  comparison.

  Raw vectors should not really be considered to have an order, but the
  numeric order of the byte representation is used.

  At least one of \code{x} and \code{y} must be an atomic vector, but if
  the other is a list \R attempts to coerce it to the type of the atomic
  vector: this will succeed if the list is made up of elements of length
  one that can be coerced to the correct type.

  If the two arguments are atomic vectors of different types, one is
  coerced to the type of the other, the (decreasing) order of precedence
  being character, complex, numeric, integer, logical and raw.

  Missing values (\code{\link{NA}}) and \code{\link{NaN}} values are
  regarded as non-comparable even to themselves, so comparisons
  involving them will always result in \code{NA}.  Missing values can
  also result when character strings are compared and one is not valid
  in the current collation locale.

  Language objects such as symbols and calls are deparsed to
  character strings before comparison.
}
\value{
  A logical vector indicating the result of the element by element
  comparison.  The elements of shorter vectors are recycled as
  necessary.

  Objects such as arrays or time-series can be compared this way
  provided they are conformable.
}
\note{
  Do not use \code{==} and \code{!=} for tests, such as in \code{if}
  expressions, where you must get a single \code{TRUE} or
  \code{FALSE}.  Unless you are absolutely sure that nothing unusual
  can happen, you should use the \code{\link{identical}} function
  instead.

  For numerical and complex values, remember \code{==} and \code{!=} do
  not allow for the finite representation of fractions, nor for rounding
  error.  Using \code{\link{all.equal}} with \code{identical} or
  \code{\link{isTRUE}} is almost always preferable; see the examples.
  (This also applies to the other comparison operators.)

  These operators are sometimes called as functions as
  e.g.\sspace{}\code{`<`(x, y)}: see the description of how
  argument-matching is done in \code{\link[base:groupGeneric]{Ops}}.
}
\section{S4 methods}{
  These operators are members of the S4 \code{\link{Compare}} group generic,
  and so methods can be written for them individually as well as for the
  group generic (or the \code{Ops} group generic), with arguments
  \code{c(e1, e2)}.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.

  Collation of character strings is a complex topic.  For an
  introduction see
  \url{https://en.wikipedia.org/wiki/Collating_sequence}.  The
  \emph{Unicode Collation Algorithm}
  (\url{https://unicode.org/reports/tr10/}) is likely to be increasingly
  influential.  Where available \R by default makes use of ICU
  (\url{https://icu.unicode.org/}) for collation (except in a C
  locale).
}
\seealso{
  \code{\link{Logic}} on how to \emph{combine} results of comparisons,
  i.e., logical vectors.

  \code{\link{factor}} for the behaviour with factor arguments.

  \code{\link{Syntax}} for operator precedence.

  \code{\link{capabilities}} for whether ICU is available, and
  \code{\link{icuSetCollate}} to tune the string collation algorithm
  when it is.
}
\examples{
x <- stats::rnorm(20)
x < 1
x[x > 0]

x1 <- 0.5 - 0.3
x2 <- 0.3 - 0.1
x1 == x2                   # FALSE on most machines
isTRUE(all.equal(x1, x2))  # TRUE everywhere

\donttest{
# range of most 8-bit charsets, as well as of Latin-1 in Unicode
z <- c(32:126, 160:255)
x <- if(l10n_info()$MBCS) {
    intToUtf8(z, multiple = TRUE)
} else rawToChar(as.raw(z), multiple = TRUE)
## by number
writeLines(strwrap(paste(x, collapse=" "), width = 60))
## by locale collation
writeLines(strwrap(paste(sort(x), collapse=" "), width = 60))
}}
\keyword{logic}