218 lines
13 KiB
HTML
218 lines
13 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<!-- This manual documents Guile version 3.0.10.
|
||
|
|
|
||
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
||
|
|
Inc.
|
||
|
|
|
||
|
|
Copyright (C) 2021 Maxime Devos
|
||
|
|
|
||
|
|
Copyright (C) 2024 Tomas Volf
|
||
|
|
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with no
|
||
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
|
|
copy of the license is included in the section entitled "GNU Free
|
||
|
|
Documentation License." -->
|
||
|
|
<title>Records (Guile Reference Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Records (Guile Reference Manual)">
|
||
|
|
<meta name="keywords" content="Records (Guile Reference Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content=".texi2any-real">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Data-Types.html" rel="up" title="Data Types">
|
||
|
|
<link href="Structures.html" rel="next" title="Structures">
|
||
|
|
<link href="SRFI_002d9-Records.html" rel="prev" title="SRFI-9 Records">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
span:hover a.copiable-link {visibility: visible}
|
||
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="subsection-level-extent" id="Records">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Structures.html" accesskey="n" rel="next">Structures</a>, Previous: <a href="SRFI_002d9-Records.html" accesskey="p" rel="prev">SRFI-9 Records</a>, Up: <a href="Data-Types.html" accesskey="u" rel="up">Data Types</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<h4 class="subsection" id="Records-1"><span>6.6.17 Records<a class="copiable-link" href="#Records-1"> ¶</a></span></h4>
|
||
|
|
|
||
|
|
<p>A <em class="dfn">record type</em> is a first class object representing a user-defined
|
||
|
|
data type. A <em class="dfn">record</em> is an instance of a record type.
|
||
|
|
</p>
|
||
|
|
<p>Note that in many ways, this interface is too low-level for every-day
|
||
|
|
use. Most uses of records are better served by SRFI-9 records.
|
||
|
|
See <a class="xref" href="SRFI_002d9-Records.html">SRFI-9 Records</a>.
|
||
|
|
</p>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_003f"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record?</strong> <var class="def-var-arguments">obj</var><a class="copiable-link" href="#index-record_003f"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return <code class="code">#t</code> if <var class="var">obj</var> is a record of any type and <code class="code">#f</code>
|
||
|
|
otherwise.
|
||
|
|
</p>
|
||
|
|
<p>Note that <code class="code">record?</code> may be true of any Scheme value; there is no
|
||
|
|
promise that records are disjoint with other Scheme types.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-make_002drecord_002dtype"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">make-record-type</strong> <var class="def-var-arguments">type-name field-names [print] [#:parent=<code class="code">#f</code>] [#:uid=<code class="code">#f</code>] [#:extensible?=<code class="code">#f</code>] [#:opaque?=<code class="code">#f</code>] [#:allow-duplicate-field-names?=<code class="code">#t</code>]</var><a class="copiable-link" href="#index-make_002drecord_002dtype"> ¶</a></span></dt>
|
||
|
|
<dd><p>Create and return a new <em class="dfn">record-type descriptor</em>.
|
||
|
|
</p>
|
||
|
|
<p><var class="var">type-name</var> is a string naming the type. Currently it’s only used
|
||
|
|
in the printed representation of records, and in diagnostics.
|
||
|
|
<var class="var">field-names</var> is a list of elements of the form <code class="code">(immutable
|
||
|
|
<var class="var">name</var>)</code>, <code class="code">(mutable <var class="var">name</var>)</code>, or <var class="var">name</var>, where
|
||
|
|
<var class="var">name</var> are symbols naming the fields of a record of the type.
|
||
|
|
Duplicates are not allowed among these symbols, unless
|
||
|
|
<var class="var">allow-duplicate-field-names?</var> is true.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example-preformatted">(make-record-type "employee" '(name age salary))
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The optional <var class="var">print</var> argument is a function used by
|
||
|
|
<code class="code">display</code>, <code class="code">write</code>, etc, for printing a record of the new
|
||
|
|
type. It’s called as <code class="code">(<var class="var">print</var> record port)</code> and should look
|
||
|
|
at <var class="var">record</var> and write to <var class="var">port</var>.
|
||
|
|
</p>
|
||
|
|
<p>Pass the <code class="code">#:parent</code> keyword to derive a record type from a
|
||
|
|
supertype. A derived record type has the fields from its parent type,
|
||
|
|
followed by fields declared in the <code class="code">make-record-type</code> call. Record
|
||
|
|
predicates and field accessors for instance of a parent type will also
|
||
|
|
work on any instance of a subtype.
|
||
|
|
</p>
|
||
|
|
<a class="index-entry-id" id="index-extensible-record-types"></a>
|
||
|
|
<a class="index-entry-id" id="index-record-types_002c-extensible"></a>
|
||
|
|
<p>Allowing record subtyping has a small amount of overhead. To avoid this
|
||
|
|
overhead, prevent extensibility by passing <code class="code">#:extensible? #f</code>.
|
||
|
|
By default, record types in Guile are not extensible.
|
||
|
|
</p>
|
||
|
|
<a class="index-entry-id" id="index-prefab-record-types"></a>
|
||
|
|
<a class="index-entry-id" id="index-record-types_002c-prefab"></a>
|
||
|
|
<a class="index-entry-id" id="index-record-types_002c-nongenerative"></a>
|
||
|
|
<p>Generally speaking, calling <code class="code">make-record-type</code> returns a fresh
|
||
|
|
record type; it <em class="emph">generates</em> new record types. However sometimes
|
||
|
|
you only want to define a record type if one hasn’t been defined
|
||
|
|
already. For a <em class="emph">nongenerative</em> record type definition, pass a
|
||
|
|
symbol as the <code class="code">#:uid</code> keyword parameter. If a record with the
|
||
|
|
given <var class="var">uid</var> was already defined, it will be returned instead. The
|
||
|
|
type name, fields, parent (if any), and so on for the previously-defined
|
||
|
|
type must be compatible.
|
||
|
|
</p>
|
||
|
|
<a class="index-entry-id" id="index-record-types_002c-opaque"></a>
|
||
|
|
<p>R6RS defines a notion of “opaque” record types. Given an instance of
|
||
|
|
an opaque record type, one cannot obtain a run-time representation of
|
||
|
|
the record type. See <a class="xref" href="rnrs-records-procedural.html">rnrs records procedural</a>, for full details. The
|
||
|
|
<code class="code">#:opaque?</code> flag is used by Guile’s R6RS layer to record this
|
||
|
|
information. The default is determined by whether the parent type, if
|
||
|
|
any, was opaque.
|
||
|
|
</p>
|
||
|
|
<p>Fields are mutable by default, meaning that <code class="code">record-modifier</code> will
|
||
|
|
return a procedure that can update a record in place. Specifying a
|
||
|
|
field using the form <code class="code">(immutable <var class="var">name</var>)</code> instead marks a field
|
||
|
|
as immutable.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002dconstructor"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-constructor</strong> <var class="def-var-arguments">rtd</var><a class="copiable-link" href="#index-record_002dconstructor"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a procedure for constructing new members of the type represented
|
||
|
|
by <var class="var">rtd</var>. The result will be a procedure accepting exactly as many
|
||
|
|
arguments as there are fields in the record type.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002dpredicate"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-predicate</strong> <var class="def-var-arguments">rtd</var><a class="copiable-link" href="#index-record_002dpredicate"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a procedure for testing membership in the type represented by
|
||
|
|
<var class="var">rtd</var>. The returned procedure accepts exactly one argument and
|
||
|
|
returns a true value if the argument is a member of the indicated record
|
||
|
|
type; it returns a false value otherwise.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002daccessor"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-accessor</strong> <var class="def-var-arguments">rtd field-name</var><a class="copiable-link" href="#index-record_002daccessor"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a procedure for reading the value of a particular field of a
|
||
|
|
member of the type represented by <var class="var">rtd</var>. The returned procedure
|
||
|
|
accepts exactly one argument which must be a record of the appropriate
|
||
|
|
type; it returns the current value of the field named by the symbol
|
||
|
|
<var class="var">field-name</var> in that record.
|
||
|
|
</p>
|
||
|
|
<p>If <var class="var">field-name</var> is a symbol, it must be a member of the list of
|
||
|
|
field-names in the call to <code class="code">make-record-type</code> that created the type
|
||
|
|
represented by <var class="var">rtd</var>. If multiple fields in <var class="var">rtd</var> have the same
|
||
|
|
name, <code class="code">record-accessor</code> returns the first one.
|
||
|
|
</p>
|
||
|
|
<p>If <var class="var">field-name</var> is an integer, it should be an index into
|
||
|
|
<code class="code">(record-type-fields <var class="var">rtd</var>)</code>. This allows accessing fields
|
||
|
|
with duplicate names.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002dmodifier"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-modifier</strong> <var class="def-var-arguments">rtd field-name</var><a class="copiable-link" href="#index-record_002dmodifier"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a procedure for writing the value of a particular field of a
|
||
|
|
member of the type represented by <var class="var">rtd</var>. The returned procedure
|
||
|
|
accepts exactly two arguments: first, a record of the appropriate type,
|
||
|
|
and second, an arbitrary Scheme value; it modifies the field named by
|
||
|
|
the symbol <var class="var">field-name</var> in that record to contain the given value.
|
||
|
|
The returned value of the modifier procedure is unspecified. The symbol
|
||
|
|
<var class="var">field-name</var> is a field name or a field index, as in
|
||
|
|
<code class="code">record-modifier</code>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002dtype_002ddescriptor"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-type-descriptor</strong> <var class="def-var-arguments">record</var><a class="copiable-link" href="#index-record_002dtype_002ddescriptor"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a record-type descriptor representing the type of the given
|
||
|
|
record. That is, for example, if the returned descriptor were passed to
|
||
|
|
<code class="code">record-predicate</code>, the resulting predicate would return a true
|
||
|
|
value when passed the given record. Note that it is not necessarily the
|
||
|
|
case that the returned descriptor is the one that was passed to
|
||
|
|
<code class="code">record-constructor</code> in the call that created the constructor
|
||
|
|
procedure that created the given record.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002dtype_002dname"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-type-name</strong> <var class="def-var-arguments">rtd</var><a class="copiable-link" href="#index-record_002dtype_002dname"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return the type-name associated with the type represented by rtd. The
|
||
|
|
returned value is <code class="code">eqv?</code> to the <var class="var">type-name</var> argument given in
|
||
|
|
the call to <code class="code">make-record-type</code> that created the type represented by
|
||
|
|
<var class="var">rtd</var>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-record_002dtype_002dfields"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">record-type-fields</strong> <var class="def-var-arguments">rtd</var><a class="copiable-link" href="#index-record_002dtype_002dfields"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return a list of the symbols naming the fields in members of the type
|
||
|
|
represented by <var class="var">rtd</var>. The returned value is <code class="code">equal?</code> to the
|
||
|
|
field-names argument given in the call to <code class="code">make-record-type</code> that
|
||
|
|
created the type represented by <var class="var">rtd</var>.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Structures.html">Structures</a>, Previous: <a href="SRFI_002d9-Records.html">SRFI-9 Records</a>, Up: <a href="Data-Types.html">Data Types</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|