% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/keylist.r
\name{keylist}
\alias{keylist}
\alias{is.keylist}
\alias{as.keylist}
\alias{as.keylist.default}
\alias{keylist.append}
\title{Create a List With Unique Keys}
\usage{
keylist(..., .named = FALSE)

is.keylist(x)

as.keylist(x, ...)

\method{as.keylist}{default}(x, ..., .named = FALSE, .recursive = FALSE)

keylist.append(klst, values, after = length(klst))
}
\arguments{
\item{...}{for \code{keylist}: objects, possibly named, for \code{as.keylist}: passed to other
methods.}

\item{.named}{boolean indicating whether the list should be fully named or not.
If \code{TRUE} then all elements must be named and unique, if \code{FALSE} then
names are not required but if they are present they must be unique.}

\item{x}{object to be coerced or tested.}

\item{.recursive}{boolean indicating whether to recursively validate nested lists.
If \code{TRUE} then all nested lists will be validated and converted to
keylists, if \code{FALSE} then only the top level list will be validated
and converted to a keylist.}

\item{klst}{passed to \link{append}: the keylist to which the values are to be appended.}

\item{values}{passed to \link{append}: the values to be included in the modified keylist.}

\item{after}{passed to \link{append}: a subscript, after which the values are to be appended.}
}
\value{
A list object of class \code{klist} or \code{knlist}. For \code{is.keylist()} a boolean.
}
\description{
Create a list with unique keys (either fully named, \link{knlist}, or a
mix of named and unnamed, \link{klist}), erroring if duplicate keys are found.
}
\details{
\code{keylist()} creates one of the two keylist objects: \code{\link{klist}} or \code{\link{knlist}},
depending on the value of the \code{.named} argument. Those methods are
generally preferred as they are more explicit.

\code{is.keylist()} checks if an object inherits from either \code{klist} or \code{knlist}.

\code{keylist.append()} applies \link{append} to a keylist and validates the result
depending on whether the input was a \code{klist} or \code{knlist}.

keylist objects accept any R object as elements, but the keys must be
unique. The key validation is done at the top level, so nested lists
are not validated unless they are also keylists. To recursively turn
a nested list structure into keylists, use
\code{as.keylist(x, .recursive = TRUE)} or one of the lower level variants.
}
\note{
keylists compare names using C's \code{strcmp} function.

\link{as.list} and \link{as.vector} methods for keylist objects remove the class
and return a base R list or vector.
}
\examples{
keylist(a = 1, 2, b = 3) # default is a klist
try(keylist(1, a = 2, a = 1)) # duplicate keys not allowed

x <- keylist(a = 1, b = 2, .named = TRUE) # create a knlist
try(keylist(1, b = 2, .named = TRUE)) # unnamed keys not allowed
try(x[[1]] <- 1) # knlist only accepts character indexing for assignment

# objects within a keylist are not subject to validation
keylist(1, list(a = 1, a = 2))
try(keylist(1, keylist(a = 1, a = 2))) # but nested keylists are

# recursively validate and convert to keylist
x <- list(1, list(1, 2))
x <- as.keylist(x, .recursive = TRUE)
class(x[[2]]) # nested list is now a keylist

is.keylist(klist(1)) && is.keylist(knlist(a = 1)) # TRUE

keylist.append(klist(a = 1), list(2, b = 3)) # append to a klist
# c() method for keylist objects also validates
try(c(keylist(a = 1), list(a = 3)))
}
\seealso{
\link{klist} and \link{knlist}.
}
