\HeaderA{RangesList-utils}{RangesList utility functions}{RangesList.Rdash.utils}
\aliasA{disjoin,RangesList-method}{RangesList-utils}{disjoin,RangesList.Rdash.method}
\aliasA{flank,CompressedIRangesList-method}{RangesList-utils}{flank,CompressedIRangesList.Rdash.method}
\aliasA{flank,RangesList-method}{RangesList-utils}{flank,RangesList.Rdash.method}
\aliasA{gaps,CompressedIRangesList-method}{RangesList-utils}{gaps,CompressedIRangesList.Rdash.method}
\aliasA{gaps,RangesList-method}{RangesList-utils}{gaps,RangesList.Rdash.method}
\aliasA{intersect,RangesList,RangesList-method}{RangesList-utils}{intersect,RangesList,RangesList.Rdash.method}
\aliasA{narrow,CompressedIRangesList-method}{RangesList-utils}{narrow,CompressedIRangesList.Rdash.method}
\aliasA{narrow,RangesList-method}{RangesList-utils}{narrow,RangesList.Rdash.method}
\aliasA{range,RangesList-method}{RangesList-utils}{range,RangesList.Rdash.method}
\aliasA{reduce,CompressedIRangesList-method}{RangesList-utils}{reduce,CompressedIRangesList.Rdash.method}
\aliasA{reduce,RangesList-method}{RangesList-utils}{reduce,RangesList.Rdash.method}
\aliasA{resize,CompressedIRangesList-method}{RangesList-utils}{resize,CompressedIRangesList.Rdash.method}
\aliasA{resize,RangesList-method}{RangesList-utils}{resize,RangesList.Rdash.method}
\aliasA{restrict,CompressedIRangesList-method}{RangesList-utils}{restrict,CompressedIRangesList.Rdash.method}
\aliasA{restrict,RangesList-method}{RangesList-utils}{restrict,RangesList.Rdash.method}
\aliasA{setdiff,RangesList,RangesList-method}{RangesList-utils}{setdiff,RangesList,RangesList.Rdash.method}
\aliasA{shift,CompressedIRangesList-method}{RangesList-utils}{shift,CompressedIRangesList.Rdash.method}
\aliasA{shift,RangesList-method}{RangesList-utils}{shift,RangesList.Rdash.method}
\aliasA{union,RangesList,RangesList-method}{RangesList-utils}{union,RangesList,RangesList.Rdash.method}
\keyword{utilities}{RangesList-utils}
\begin{Description}\relax
Utility functions for manipulating \code{\LinkA{RangesList}{RangesList.Rdash.class}}
objects.
\end{Description}
\begin{Usage}
\begin{verbatim}
# Intra-interval operations
## S4 method for signature 'RangesList':
flank(x, width, start=TRUE, both=FALSE, use.names=TRUE)
## S4 method for signature 'RangesList':
narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
## S4 method for signature 'RangesList':
resize(x, width, fix="start", use.names=TRUE)
## S4 method for signature 'RangesList':
restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
## S4 method for signature 'RangesList':
shift(x, shift, use.names=TRUE)

# Inter-interval operations
## S4 method for signature 'RangesList':
disjoin(x)
## S4 method for signature 'RangesList':
gaps(x, start=NA, end=NA)
## S4 method for signature 'RangesList':
range(x, ..., na.rm = FALSE)
## S4 method for signature 'RangesList':
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
                              with.inframe.attrib=FALSE)

# Set operations
## S4 method for signature 'RangesList, RangesList':
union(x, y)
## S4 method for signature 'RangesList, RangesList':
intersect(x, y)
## S4 method for signature 'RangesList, RangesList':
setdiff(x, y)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] A \code{RangesList}
\item[\code{start, end}] For \code{flank}, \code{start} must be either a logical vector or a
LogicalList object indicating whether \code{x} should be flanked at the
start (\code{TRUE}) or the end (\code{FALSE}). Recycled as necessary so
that each element corresponds to a range in \code{x}.

For \code{narrow}, \code{start} and \code{end} must be either an integer
vector or a IntegerList object containing coordinates relative to the
current ranges.

For \code{restrict}, \code{start} and \code{end} must be either a single
integer or \code{NA}.

For \code{gaps}, \code{start} and \code{end} must be an integer vector
containing the coordinate bounds for each RangesList element.

\item[\code{width}] For \code{flank} and \code{resize}, either an integer vector or an
IntegerList object containing the width of the flanking or resized
regions. Recycled as necessary so that each element corresponds to a
range in \code{x}. (Note for \code{flank}: if \code{both} is \code{TRUE},
this is effectively doubled.) 

For \code{narrow}, either an integer vector or a IntegerList object
containing the widths to narrow to. See the SEW (Start/End/Width)
interface for the details (\code{?solveUserSEW}).

\item[\code{both}] If \code{TRUE}, extends the flanking region \code{width} positions
\emph{into} the range. The resulting range thus straddles the end
point, with \code{width} positions on either side.

\item[\code{use.names}] \code{TRUE} or \code{FALSE}. Should names be preserved?

\item[\code{fix}] For \code{resize}, a character vector of length 1, a CharacterList object,
or a 'character' RleList object containing the values \code{"start"},
\code{"end"}, and \code{"center"} denoting what to use as an anchor for
each element in \code{x}.

\item[\code{keep.all.ranges}] \code{TRUE} or \code{FALSE}. Should ranges that don't overlap with
the interval specified by \code{start} and \code{end} be kept?
Note that "don't overlap" means that they end strictly before
\code{start - 1} or start strictly after \code{end + 1}.
Ranges that end at \code{start - 1} or start at \code{end + 1}
are always kept and their width is set to zero in the returned
\LinkA{RangesList}{RangesList} object.

\item[\code{shift}] Either an integer vector or a IntegerList object containing the shift
information. Recycled as necessary so that each element corresponds to
a range in \code{x}.

\item[\code{drop.empty.ranges}] \code{TRUE} or \code{FALSE}. Should empty ranges be dropped?

\item[\code{min.gapwidth}] Ranges separated by a gap of at least \code{min.gapwidth} positions
won't be merged in the \LinkA{Ranges}{Ranges} object returned by \code{reduce}.
Otherwise, they will.

\item[\code{with.inframe.attrib}] \code{TRUE} or \code{FALSE}. For internal use.

\item[\code{...}] For \code{range}, additional \code{RangesList} to consider.

\item[\code{na.rm}] Ignored
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{flank} method generates flanking ranges for each range in
\code{x}.

The \code{narrow} method narrows the ranges in \code{x} i.e. each range
in the returned \LinkA{RangesList}{RangesList} object is a subrange of the corresponding
range in \code{x}.

The \code{resize} method resizes the ranges to the specified width where
either the start or end is used as an anchor.

The \code{restrict} method restricts the ranges in \code{x} to the
interval specified by the \code{start} and \code{end} arguments.

The \code{shift} method shifts all the ranges in \code{x}.

The \code{disjoin} method returns disjoint ranges by finding the 
within element union of the end points of \code{x}.

The \code{gaps} method takes the complement (via \code{\LinkA{gaps}{gaps}})
of each element in the list and returns the result as a
\code{RangesList}.

\code{range} finds the \code{\LinkA{range}{range,Ranges.Rdash.method}}, i.e.
a \code{Ranges} with one range, from the minimum start to the maximum
end, on each element in \code{x} and returns the result as a
\code{RangesList}. If there are additional \code{RangesList} objects
in \code{...}, they are merged into \code{x} by name, if all objects
have names, otherwise, if they are all of the same length, by
position. Else, an exception is thrown.

The \code{reduce} method merges (via \code{\LinkA{reduce}{reduce}}) each of the
elements in the list and returns the result as a \code{RangesList}.

The \code{union} method performs elementwise \code{union} operations
for two \code{RangesList} objects.

The \code{intersect} method performs elementwise \code{intersect}
operations for two \code{RangesList} objects.

The \code{setdiff} method performs elementwise \code{setdiff} operations
for two \code{RangesList} objects.
\end{Details}
\begin{Value}
A \code{RangesList} object. For \code{flank}, \code{narrow}, \code{resize},
\code{restrict}, and \code{shift}, the length is the same as that of
\code{x}.
\end{Value}
\begin{Author}\relax
Michael Lawrence, H. Pages, P. Aboyoun
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{RangesList}{RangesList.Rdash.class}}, \code{\LinkA{Ranges-utils}{Ranges.Rdash.utils}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  range1 <- IRanges(start=c(1,2,3), end=c(5,2,8))
  range2 <- IRanges(start=c(15,45,20,1), end=c(15,100,80,5))
  range3 <- IRanges(start=c(-2,6,7), width=c(8,0,0))  # with empty ranges
  collection <- RangesList(one = range1, range2, range3)

  shift(collection, shift=5)
  restrict(collection, start=2, end=8)
  resize(collection, width=200)
  flank(collection, width=10)
  disjoin(collection)

  # these three are the same
  reduce(collection)
  RangesList(one = reduce(range1), reduce(range2), reduce(range3))
  do.call(RangesList, lapply(collection, reduce))

  # drop empty ranges
  reduce(collection, drop.empty.ranges=TRUE)

  # these three are the same
  gaps(collection)
  RangesList(one = gaps(range1), gaps(range2), gaps(range3))
  do.call(RangesList, lapply(collection, gaps))

  # 'range'
  rl <- RangesList(a = IRanges(c(1,2),c(4,3)), b = IRanges(c(4,6),c(10,7)))
  rl2 <- RangesList(c = IRanges(c(0,2),c(4,5)), a = IRanges(c(4,5),c(6,7)))
  range(rl, rl2) # matched by names
  names(rl2) <- NULL
  range(rl, rl2) # now by position

  # set operations
  union(rl, rl2)
  intersect(rl, rl2)
  setdiff(rl, rl2)
\end{ExampleCode}
\end{Examples}

