\HeaderA{IRanges-setops}{Set operations on IRanges objects}{IRanges.Rdash.setops}
\aliasA{gaps}{IRanges-setops}{gaps}
\aliasA{gaps,IRanges-method}{IRanges-setops}{gaps,IRanges.Rdash.method}
\aliasA{gaps,Ranges-method}{IRanges-setops}{gaps,Ranges.Rdash.method}
\aliasA{intersect,IRanges,IRanges-method}{IRanges-setops}{intersect,IRanges,IRanges.Rdash.method}
\aliasA{pgap}{IRanges-setops}{pgap}
\aliasA{pgap,IRanges,IRanges-method}{IRanges-setops}{pgap,IRanges,IRanges.Rdash.method}
\aliasA{pintersect}{IRanges-setops}{pintersect}
\aliasA{pintersect,IRanges,IRanges-method}{IRanges-setops}{pintersect,IRanges,IRanges.Rdash.method}
\aliasA{psetdiff}{IRanges-setops}{psetdiff}
\aliasA{psetdiff,IRanges,IRanges-method}{IRanges-setops}{psetdiff,IRanges,IRanges.Rdash.method}
\aliasA{punion}{IRanges-setops}{punion}
\aliasA{punion,IRanges,IRanges-method}{IRanges-setops}{punion,IRanges,IRanges.Rdash.method}
\aliasA{setdiff,IRanges,IRanges-method}{IRanges-setops}{setdiff,IRanges,IRanges.Rdash.method}
\aliasA{union,IRanges,IRanges-method}{IRanges-setops}{union,IRanges,IRanges.Rdash.method}
\keyword{utilities}{IRanges-setops}
\begin{Description}\relax
Performs set operations on \LinkA{IRanges}{IRanges} objects.
\end{Description}
\begin{Usage}
\begin{verbatim}
  ## Vector-wise operations:
  gaps(x, start=NA, end=NA)
  ## S4 method for signature 'IRanges, IRanges':
  union(x, y)
  ## S4 method for signature 'IRanges, IRanges':
  intersect(x, y)
  ## S4 method for signature 'IRanges, IRanges':
  setdiff(x, y)

  ## Element-wise (aka "parallel") operations:
  ## S4 method for signature 'IRanges, IRanges':
  punion(x, y, fill.gap=FALSE, ...)
  ## S4 method for signature 'IRanges, IRanges':
  pintersect(x, y, resolve.empty=c("none", "max.start", "start.x"), ...)
  ## S4 method for signature 'IRanges, IRanges':
  psetdiff(x, y, ...)
  ## S4 method for signature 'IRanges, IRanges':
  pgap(x, y, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] \LinkA{IRanges}{IRanges} objects.

\item[\code{start, end}] A single integer or \code{NA}. Use these arguments to specify the
interval of reference i.e. which interval the returned gaps
should be relative to.

\item[\code{fill.gap}] Logical indicating whether or not to force a union by using the rule
\code{start = min(start(x), start(y)), end = max(end(x), end(y))}.

\item[\code{resolve.empty}] One of \code{"none"}, \code{"max.start"}, or \code{"start.x"} denoting
how to handle ambiguous empty ranges formed by intersections.
\code{"none"} - throw an error if an ambiguous empty range is formed,
\code{"max.start"} - associate the maximum start value with any
ambiguous empty range, and \code{"start.x"} - associate the start value
of \code{x} with any ambiguous empty range. (See Details section
below for the definition of an ambiguous range.)

\item[\code{...}] Further arguments to be passed to or from other methods.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{gaps} returns the "normal" \LinkA{IRanges}{IRanges} object (of the same
class as \code{x}) representing the set of integers that remain
after the set of integers represented by \code{x} has been removed
from the interval specified by the \code{start} and \code{end} arguments.

The \code{union}, \code{intersect} and \code{setdiff} methods
for \LinkA{IRanges}{IRanges} objects return a "normal" \LinkA{IRanges}{IRanges}
object (of the same class as \code{x}) representing the union,
intersection and (asymmetric!) difference of the sets of integers
represented by \code{x} and \code{y}.

\code{punion}, \code{pintersect}, \code{psetdiff} and \code{pgap}
are generic functions that compute the element-wise (aka "parallel")
union, intersection, (asymmetric!) difference and gap between
each element in \code{x} and its corresponding element in \code{y}.
Methods for \LinkA{IRanges}{IRanges} objects are defined. For these methods,
\code{x} and \code{y} must have the same length (i.e. same number
of ranges) and they return an \LinkA{IRanges}{IRanges} instance of the
same length as \code{x} and \code{y} where each range represents
the union/intersection/difference/gap of/between the corresponding
ranges in \code{x} and \code{y}.

By default, \code{pintersect} will throw an error when an "ambiguous
empty range" is formed. An ambiguous empty range can occur three
different ways:  1) when corresponding non-empty ranges elements \code{x}
and \code{y} have an empty intersection, 2) if the position of an empty
range element does not fall within the corresponding limits of a non-empty
range element, or 3) if two corresponding empty range elements do not have
the same position. For example if empty range element [22,21] is intersected
with non-empty range element [1,10], an error will be produced; but if
it is intersected with the range [22,28], it will produce [22,21].
As mentioned in the Arguments section above, this behavior can be
changed using the \code{resolve.empty} argument.
\end{Details}
\begin{Author}\relax
H. Pages and M. Lawrence
\end{Author}
\begin{SeeAlso}\relax
\code{pintersect} is similar to \code{\LinkA{narrow}{narrow}}, except the
end points are absolute, not relative. \code{pintersect} is also
similar to \code{\LinkA{restrict}{restrict}}, except ranges outside of the
restriction become empty and are not discarded.

\LinkA{union}{union}, \LinkA{intersect}{intersect}, \LinkA{setdiff}{setdiff},
\LinkA{Ranges-class}{Ranges.Rdash.class},
\LinkA{Ranges-utils}{Ranges.Rdash.utils},
\LinkA{IRanges-class}{IRanges.Rdash.class},
\LinkA{IRanges-utils}{IRanges.Rdash.utils}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  x0 <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 10),
                width=c( 5, 0, 6,  1, 4, 3,  2,  3))
  gaps(x0)
  gaps(x0, start=-6, end=20)  # Regions of the -6:20 range that are not masked by 'x0'.

  x <- IRanges(c(1, 5, -2, 0, 14), c(10, 9, 3, 11, 17))
  y <- Views(as(4:-17, "XInteger"), start=c(14, 0, -5, 6, 18), end=c(20, 2, 2, 8, 20))

  ## Vector-wise operations:
  union(x, y)
  union(y, x)

  intersect(x, y)
  intersect(y, x)

  setdiff(x, y)
  setdiff(y, x)

  ## Element-wise (aka "parallel") operations:
  try(punion(x, y))
  punion(x[3:5], y[3:5])
  punion(x, y, fill.gap=TRUE)
  try(pintersect(x, y))
  pintersect(x[3:4], y[3:4])
  pintersect(x, y, resolve.empty="max.start")
  psetdiff(y, x)
  try(psetdiff(x, y))
  start(x)[4] <- -99
  end(y)[4] <- 99
  psetdiff(x, y)
  pgap(x, y)
\end{ExampleCode}
\end{Examples}

