\HeaderA{attributes}{Object Attribute Lists}{attributes}
\aliasA{attributes<\Rdash}{attributes}{attributes<.Rdash.}
\aliasA{mostattributes<\Rdash}{attributes}{mostattributes<.Rdash.}
\keyword{attribute}{attributes}
\begin{Description}\relax
These functions access an object's attributes.
The first form below returns the object's attribute list.
The replacement forms uses the list on the right-hand
side of the assignment as the object's attributes (if appropriate).
\end{Description}
\begin{Usage}
\begin{verbatim}
attributes(obj)
attributes(obj) <- value
mostattributes(obj) <- value
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{obj}] an object
\item[\code{value}] an appropriate named list of attributes, or \code{NULL}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Unlike \code{\LinkA{attr}{attr}} it is possible to set attributes on a
\code{NULL} object: it will first be coerced to an empty list.

Note that some attributes (namely \code{\LinkA{class}{class}},
\code{\LinkA{comment}{comment}}, \code{\LinkA{dim}{dim}}, \code{\LinkA{dimnames}{dimnames}},
\code{\LinkA{names}{names}}, \code{\LinkA{row.names}{row.names}} and
\code{\LinkA{tsp}{tsp}}) are treated specially and have restrictions on
the values which can be set.  (Note that this is not true of
\code{\LinkA{levels}{levels}} which should be set for factors via the
\code{levels} replacement function.)

Attributes are not stored internally as a list and should be thought
of as a set and not a vector.  They must have unique
names (and \code{NA} is taken as \code{"NA"}, not a missing value).

Assigning attributes first removes all attributes, then sets any
\code{dim} attribute and then the remaining attributes in the order
given: this ensures that setting a \code{dim} attribute always precedes
the \code{dimnames} attribute.

The \code{mostattributes} assignment takes special care for the
\code{\LinkA{dim}{dim}}, \code{\LinkA{names}{names}} and \code{\LinkA{dimnames}{dimnames}}
attributes, and assigns them only when valid whereas an
\code{attributes} assignment would give an error if any are not.

The names of a pairlist are not stored as attributes, but are reported
as if they were (and can be set by the replacement method for attributes).
\end{Details}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{attr}{attr}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- cbind(a=1:3, pi=pi) # simple matrix w/ dimnames
attributes(x)

## strip an object's attributes:
attributes(x) <- NULL
x # now just a vector of length 6

mostattributes(x) <- list(mycomment = "really special", dim = 3:2,
   dimnames = list(LETTERS[1:3], letters[1:5]), names = paste(1:6))
x # dim(), but not {dim}names
\end{ExampleCode}
\end{Examples}

