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