1@c -*-texinfo-*-
2@c This is part of the GNU Emacs Lisp Reference Manual.
3@c Copyright (C) 2017--2021 Free Software Foundation, Inc.
4@c See the file elisp.texi for copying conditions.
5@node Records
6@chapter Records
7@cindex records
8
9  The purpose of records is to allow programmers to create objects
10with new types that are not built into Emacs.  They are used as the
11underlying representation of @code{cl-defstruct} and @code{defclass}
12instances.
13
14  Internally, a record object is much like a vector; its slots can be
15accessed using @code{aref} and it can be copied using
16@code{copy-sequence}.  However, the first slot is used to hold its
17type as returned by @code{type-of}.  Also, in the current
18implementation records can have at most 4096 slots, whereas vectors
19can be much larger.  Like arrays, records use zero-origin indexing:
20the first slot has index 0.
21
22  The type slot should be a symbol or a type descriptor.  If it's a
23type descriptor, the symbol naming its type will be returned;
24@ref{Type Descriptors}.  Any other kind of object is returned as-is.
25
26  The printed representation of records is @samp{#s} followed by a
27list specifying the contents.  The first list element must be the
28record type.  The following elements are the record slots.
29
30  To avoid conflicts with other type names, Lisp programs that define
31new types of records should normally use the naming conventions of the
32package where these record types are introduced for the names of the
33types.  Note that the names of the types which could possibly conflict
34might not be known at the time the package defining a record type is
35loaded; they could be loaded at some future point in time.
36
37  A record is considered a constant for evaluation: the result of
38evaluating it is the same record.  This does not evaluate or even
39examine the slots.  @xref{Self-Evaluating Forms}.
40
41@menu
42* Record Functions::        Functions for records.
43* Backward Compatibility::  Compatibility for cl-defstruct.
44@end menu
45
46@node Record Functions
47@section Record Functions
48
49@defun recordp object
50This function returns @code{t} if @var{object} is a record.
51
52@example
53@group
54(recordp #s(a))
55     @result{} t
56@end group
57@end example
58@end defun
59
60@defun record type &rest objects
61This function creates and returns a record whose type is @var{type}
62and remaining slots are the rest of the arguments, @var{objects}.
63
64@example
65@group
66(record 'foo 23 [bar baz] "rats")
67     @result{} #s(foo 23 [bar baz] "rats")
68@end group
69@end example
70@end defun
71
72@defun make-record type length object
73This function returns a new record with type @var{type} and
74@var{length} more slots, each initialized to @var{object}.
75
76@example
77@group
78(setq sleepy (make-record 'foo 9 'Z))
79     @result{} #s(foo Z Z Z Z Z Z Z Z Z)
80@end group
81@end example
82@end defun
83
84@node Backward Compatibility
85@section Backward Compatibility
86
87  Code compiled with older versions of @code{cl-defstruct} that
88doesn't use records may run into problems when used in a new Emacs.
89To alleviate this, Emacs detects when an old @code{cl-defstruct} is
90used, and enables a mode in which @code{type-of} handles old struct
91objects as if they were records.
92
93@defun cl-old-struct-compat-mode arg
94If @var{arg} is positive, enable backward compatibility with old-style
95structs.
96@end defun
97