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