\HeaderA{Views-class}{Views objects}{Views.Rdash.class}
\aliasA{class:Views}{Views-class}{class:Views}
\aliasA{coerce,Sequence,Views-method}{Views-class}{coerce,Sequence,Views.Rdash.method}
\aliasA{coerce,Views,NormalIRanges-method}{Views-class}{coerce,Views,NormalIRanges.Rdash.method}
\aliasA{gaps,Views-method}{Views-class}{gaps,Views.Rdash.method}
\aliasA{newViews}{Views-class}{newViews}
\aliasA{subject}{Views-class}{subject}
\aliasA{subject,Views-method}{Views-class}{subject,Views.Rdash.method}
\aliasA{subviews}{Views-class}{subviews}
\aliasA{subviews,Views-method}{Views-class}{subviews,Views.Rdash.method}
\aliasA{successiveViews}{Views-class}{successiveViews}
\aliasA{trim}{Views-class}{trim}
\aliasA{trim,Views-method}{Views-class}{trim,Views.Rdash.method}
\aliasA{Views}{Views-class}{Views}
\aliasA{views}{Views-class}{views}
\aliasA{[[,Views-method}{Views-class}{[[,Views.Rdash.method}
\keyword{methods}{Views-class}
\keyword{classes}{Views-class}
\begin{Description}\relax
The Views virtual class is a general container for storing a set of
views on an arbitrary \LinkA{Sequence}{Sequence} object, called the "subject".

Its primary purpose is to introduce concepts and provide some facilities
that can be shared by the concrete classes that derive from it.

Some direct subclasses of the Views class are: \LinkA{XIntegerViews}{XIntegerViews},
\LinkA{RleViews}{RleViews}, \LinkA{XStringViews}{XStringViews}
(defined in the Biostrings package), etc...
\end{Description}
\begin{Section}{Constructor}
\describe{
\item[] \code{Views(subject, start=NULL, end=NULL, width=NULL, names=NULL)}:
This constructor is a generic function with dispatch on argument
\code{subject}. Specific methods must be defined for the subclasses
of the Views class. For example a method for
\LinkA{XString}{XString} subjects is defined
in the Biostrings package that returns an
\LinkA{XStringViews}{XStringViews}
object. There is no default method.

The treatment of the \code{start}, \code{end} and \code{width}
arguments is the same as with the \code{\LinkA{IRanges}{IRanges}} constructor,
except that, in addition, \code{Views} allows \code{start} to be a
\LinkA{Ranges}{Ranges} object. With this feature,
\code{Views(subject, IRanges(my\_starts, my\_ends, my\_widths, my\_names))}
and \code{Views(subject, my\_starts, my\_ends, my\_widths, my\_names)}
are equivalent (except when \code{my\_starts} is itself a
\LinkA{Ranges}{Ranges} object).

}
\end{Section}
\begin{Section}{Coercion}
In the code snippets below, \code{from} is a Views object:

\describe{
\item[] \code{as(from, "IRanges")}: Creates an \code{IRanges} object
containing the view locations in \code{from}.

}
\end{Section}
\begin{Section}{Accessor-like methods}
All the accessor-like methods defined for \code{IRanges} objects
work on Views objects. In addition, the following accessors are defined
for Views objects:

\describe{
\item[] \code{subject(x)}:
Return the subject of the views.

}
\end{Section}
\begin{Section}{Subsetting and appending}
\code{"["}, \code{c} and \code{"[["} work on a Views object.
The first two operations are just inherited from the
\code{IRanges} class but now they return a Views object.
However, the \code{"[["} method for Views objects has a
different semantic than the method for \code{IRanges} objects.

\describe{
\item[] \code{x[[i]]}:
Extracts the view selected by \code{i} as an object of the same class
as \code{subject(x)}. Subscript \code{i} can be a single integer
or a character string.
The result is the subsequence of \code{subject(x)} defined by
\code{window(subject(x), start=start(x)[i], end=end(x)[i])}
or an error if the view is "out of limits" (i.e. \code{start(x)[i] < 1}
or \code{end(x)[i] > length(subject(x))}).

}
\end{Section}
\begin{Section}{Other methods}
\describe{
\item[] \code{trim(x, use.names=TRUE)}:
Equivalent to
\code{restrict(x, start=1L, end=length(subject(x)), keep.all.ranges=TRUE,
                      use.names=use.names)}.

\item[] \code{subviews(x, start=NA, end=NA, width=NA, use.names=TRUE)}:
\code{start}, \code{end}, and \code{width} arguments must be vectors
of integers, eventually with NAs, that contain coordinates relative
to the current ranges. Equivalent to
\code{trim(narrow(x, start=start, end=end, width=width, use.names=use.names))}.

\item[] \code{gaps(x, start=NA, end=NA)}:
\code{start} and \code{end} can be single integers or NAs.
The gap extraction will be restricted to the window specified by
\code{start} and \code{end}. \code{start=NA} and \code{end=NA}
are interpreted as \code{start=1} and \code{end=length(subject(x))},
respectively, so, if \code{start} and \code{end} are not specified,
then gaps are extracted with respect to the entire subject.

\item[] \code{successiveViews(subject, width, gapwidth=0, from=1)}:
Equivalent to \code{Views(subject, successiveIRanges(width, gapwidth, from))}.
See \code{?successiveIRanges} for a description of the \code{width},
\code{gapwidth} and \code{from} arguments.

}
\end{Section}
\begin{Author}\relax
H. Pages
\end{Author}
\begin{SeeAlso}\relax
\LinkA{IRanges-class}{IRanges.Rdash.class},
\LinkA{Sequence-class}{Sequence.Rdash.class},
\LinkA{IRanges-utils}{IRanges.Rdash.utils},
\LinkA{XVector}{XVector}.

Some direct subclasses of the Views class:
\LinkA{XIntegerViews-class}{XIntegerViews.Rdash.class},
\LinkA{RleViews-class}{RleViews.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  showClass("Views")  # shows (some of) the known subclasses

  ## Create a set of 4 views on an XInteger subject of length 10:
  subject <- XInteger(10, 3:-6)
  v1 <- Views(subject, start=4:1, end=4:7)

  ## Extract the 2nd view:
  v1[[2]]

  ## Some views can be "out of limits"
  v2 <- Views(subject, start=4:-1, end=6)
  trim(v2)
  subviews(v2, end=-2)

  ## gaps() 
  v3 <- Views(subject, start=c(8, 3), end=c(14, 4))
  gaps(v3)

  ## Views on a big XInteger subject:
  subject <- XInteger(99999, sample(99, 99999, replace=TRUE) - 50)
  v4 <- Views(subject, start=1:99*1000, end=1:99*1001)
  v4
  v4[-1]
  v4[[5]]

  ## 31 adjacent views:
  successiveViews(subject, 40:10)
\end{ExampleCode}
\end{Examples}

