\HeaderA{IRanges-utils}{IRanges utility functions}{IRanges.Rdash.utils}
\aliasA{asNormalIRanges}{IRanges-utils}{asNormalIRanges}
\aliasA{coerce,IRanges,NormalIRanges-method}{IRanges-utils}{coerce,IRanges,NormalIRanges.Rdash.method}
\aliasA{successiveIRanges}{IRanges-utils}{successiveIRanges}
\aliasA{whichAsIRanges}{IRanges-utils}{whichAsIRanges}
\keyword{utilities}{IRanges-utils}
\begin{Description}\relax
Utility functions for creating or modifying \LinkA{IRanges}{IRanges} objects.
\end{Description}
\begin{Usage}
\begin{verbatim}
## Create an IRanges instance:
successiveIRanges(width, gapwidth=0, from=1)

## Turn a logical vector into a set of ranges:
whichAsIRanges(x)

## Coercion:
asNormalIRanges(x, force=TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{width}] A vector of non-negative integers (with no NAs) specifying the widths
of the ranges to create.

\item[\code{gapwidth}] A single integer or an integer vector with one less element than
the \code{width} vector specifying the widths of the gaps separating
one range from the next one.

\item[\code{from}] A single integer specifying the starting position of the first range.

\item[\code{x}] A logical vector for \code{whichAsIRanges}.
An \LinkA{IRanges}{IRanges} object for \code{asNormalIRanges}.

\item[\code{force}] \code{TRUE} or \code{FALSE}. Should \code{x} be turned into a
\LinkA{NormalIRanges}{NormalIRanges} object even if \code{isNormal(x)} is \code{FALSE}?

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{successiveIRanges} returns an IRanges instance containing the
ranges that have the widths specified in the \code{width} vector
and are separated by the gaps specified in \code{gapwidth}.
The first range starts at position \code{from}.
When \code{gapwidth=0} and \code{from=1} (the defaults), the returned
IRanges can be seen as a partitioning of the 1:sum(width) interval.
See \code{?Partitioning} for more details on this.

\code{whichAsIRanges} returns an \LinkA{IRanges}{IRanges} instance containing all of
the ranges where \code{x} is \code{TRUE}.

If \code{force=TRUE} (the default), then \code{asNormalIRanges} will
turn \code{x} into a \LinkA{NormalIRanges}{NormalIRanges} instance by reordering and
reducing the set of ranges if necessary (i.e. only if \code{isNormal(x)}
is \code{FALSE}, otherwise the set of ranges will be untouched).
If \code{force=FALSE}, then \code{asNormalIRanges} will turn \code{x}
into a \LinkA{NormalIRanges}{NormalIRanges} instance only if \code{isNormal(x)} is
\code{TRUE}, otherwise it will raise an error.
Note that when \code{force=FALSE}, the returned object is guaranteed
to contain exactly the same set of ranges than \code{x}.
\code{as(x, "NormalIRanges")} is equivalent to \code{asNormalIRanges(x, force=TRUE)}.
\end{Details}
\begin{Author}\relax
H. Pages
\end{Author}
\begin{SeeAlso}\relax
\LinkA{Ranges-class}{Ranges.Rdash.class},
\LinkA{Ranges-utils}{Ranges.Rdash.utils},
\LinkA{IRanges-class}{IRanges.Rdash.class},
\LinkA{IRanges-setops}{IRanges.Rdash.setops},
\code{\LinkA{solveUserSEW}{solveUserSEW}},
\code{\LinkA{successiveViews}{successiveViews}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  vec <- as.integer(c(19, 5, 0, 8, 5))
  whichAsIRanges(vec >= 5)
  x <- successiveIRanges(vec)
  x

  asNormalIRanges(x)   # 3 ranges ordered from left to right and separated by
                       # gaps of width >= 1.

  ## More on normality:
  example(`IRanges-class`)
  isNormal(x16)                        # FALSE
  if (interactive())
      x16 <- asNormalIRanges(x16)      # Error!
  whichFirstNotNormal(x16)             # 57
  isNormal(x16[1:56])                  # TRUE
  xx <- asNormalIRanges(x16[1:56])
  class(xx)
  max(xx)
  min(xx)
\end{ExampleCode}
\end{Examples}

