emacs/doc/lispref/records.texi

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

  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.

  To avoid conflicts with other type names, Lisp programs that define
new types of records should normally use the naming conventions of the
package where these record types are introduced for the names of the
types.  Note that the names of the types which could possibly conflict
might not be known at the time the package defining a record type is
loaded; they could be loaded at some future point in time.

  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

To copy trees consisting of records, vectors and conses (lists), use
@code{copy-tree} with its optional second argument non-@code{nil}.
@xref{Building Lists, copy-tree}.

@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