@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 2017 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Records
@chapter Records
@cindex record

  The purpose of records is to allow programmers to create objects
with new types that are not built into Emacs.  They are used as the
underlying representation of @code{cl-defstruct} and @code{defclass}
instances.

  Internally, a record object is much like a vector; its slots can be
accessed using @code{aref} and it can be copied using
@code{copy-sequence}.  However, the first slot is used to hold its
type as returned by @code{type-of}.  Also, in the current
implementation records can have at most 4096 slots, whereas vectors
can be much larger.  Like arrays, records use zero-origin indexing:
the first slot has index 0.

  The type slot should be a symbol or a type descriptor.  If it's a
type descriptor, the symbol naming its type will be returned;
@ref{Type Descriptors}.  Any other kind of object is returned as-is.

  The printed representation of records is @samp{#s} followed by a
list specifying the contents.  The first list element must be the
record type.  The following elements are the record slots.

  A record is considered a constant for evaluation: the result of
evaluating it is the same record.  This does not evaluate or even
examine the slots.  @xref{Self-Evaluating Forms}.

@menu
* Record Functions::        Functions for records.
* Backward Compatibility::  Compatibility for cl-defstruct.
@end menu

@node Record Functions
@section Record Functions

@defun recordp object
This function returns @code{t} if @var{object} is a record.

@example
@group
(recordp #s(a))
     @result{} t
@end group
@end example
@end defun

@defun record type &rest objects
This function creates and returns a record whose type is @var{type}
and remaining slots are the rest of the arguments, @var{objects}.

@example
@group
(record 'foo 23 [bar baz] "rats")
     @result{} #s(foo 23 [bar baz] "rats")
@end group
@end example
@end defun

@defun make-record type length object
This function returns a new record with type @var{type} and
@var{length} more slots, each initialized to @var{object}.

@example
@group
(setq sleepy (make-record 'foo 9 'Z))
     @result{} #s(foo Z Z Z Z Z Z Z Z Z)
@end group
@end example
@end defun

@node Backward Compatibility
@section Backward Compatibility

  Code compiled with older versions of @code{cl-defstruct} that
doesn't use records may run into problems when used in a new Emacs.
To alleviate this, Emacs detects when an old @code{cl-defstruct} is
used, and enables a mode in which @code{type-of} handles old struct
objects as if they were records.

@defun cl-old-struct-compat-mode arg
If @var{arg} is positive, enable backward compatibility with old-style
structs.
@end defun