<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 2. Manipulating Lisp objects</title><link rel="stylesheet" href="ecl.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="The ECL manual"><link rel="up" href="pt03.html" title="Part III. Internals"><link rel="prev" href="ch24s06.html" title="1.6. Compiler examples"><link rel="next" href="ch25s02.html" title="2.2. Constructing objects"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Manipulating Lisp objects</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch24s06.html">Prev</a> </td><th width="60%" align="center">Part III. Internals</th><td width="20%" align="right"> <a accesskey="n" href="ch25s02.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 2. Manipulating Lisp objects"><div class="titlepage"><div><div><h2 class="title"><a name="Lisp-objects"></a>Chapter 2. Manipulating Lisp objects</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ch25.html#Internals-Objects-representation">2.1. Objects representation</a></span></dt><dt><span class="section"><a href="ch25s02.html">2.2. Constructing objects</a></span></dt><dt><span class="section"><a href="ch25s03.html">2.3. Integers</a></span></dt><dt><span class="section"><a href="ch25s04.html">2.4. Characters</a></span></dt><dt><span class="section"><a href="ch25s05.html">2.5. Arrays</a></span></dt><dt><span class="section"><a href="ch25s06.html">2.6. Strings</a></span></dt><dt><span class="section"><a href="ch25s07.html">2.7. Bitvectors</a></span></dt><dt><span class="section"><a href="ch25s08.html">2.8. Streams</a></span></dt><dt><span class="section"><a href="ch25s09.html">2.9. Structures</a></span></dt><dt><span class="section"><a href="ch25s10.html">2.10. Instances</a></span></dt><dt><span class="section"><a href="ch25s11.html">2.11. Bytecodes</a></span></dt></dl></div><p>If you want to extend, fix or simply customize <span class="application">ECL</span> for your own needs,
you should understand how the implementation works.</p><div class="section" title="2.1. Objects representation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Internals-Objects-representation"></a>2.1. Objects representation</h2></div></div></div><p>In <span class="application">ECL</span> a lisp object is represented by a type called <code class="literal">cl_object</code>. This
type is a word which is long enough to host both an integer and a pointer. The
least significant bits of this word, also called the tag bits, determine
whether it is a pointer to a C structure representing a complex object, or
whether it is an immediate data, such as a fixnum or a character.</p><pre class="screen">
|-------------------|--|
| Fixnum value |01|
|-------------------|--|
|------------|------|--|
| Unused bits| char |10|
|------------|------|--|
|----------------------| |--------|--------|-----|--------|
| Pointer to cell |---->| word-1 | word-2 | ... | word-n |
|----------------------| |--------|--------|-----|--------|
| ...................00| | actual data of the object |
|----------------------| |--------------------------------|
</pre><p>The fixnums and characters are called immediate datatypes, because they require
no more than the <code class="literal">cl_object</code> datatype to store all information. All other
<span class="application">ECL</span> objects are non-immediate and they are represented by a pointer to a
cell that is allocated on the heap. Each cell consists of several words of
memory and contains all the information related to that object. By storing data
in multiples of a word size, we make sure that the least significant bits of a
pointer are zero, which distinguishes pointers from immediate data.</p><p>In an immediate datatype, the tag bits determine the type of the object. In
non-immediate datatypes, the first byte in the cell contains the secondary type
indicator, and distinguishes between different types of non immediate data. The
use of the remaining bytes differs for each type of object. For instance, a
cons cell consists of three words:</p><pre class="screen">
|---------|----------|
|CONS| | |
|---------|----------|
| car-pointer |
|--------------------|
| cdr-pointer |
|--------------------|
</pre><p>There is one important function which tells the type of an object, plus several
macros which group several tests.</p><div class="blockquote"><blockquote class="blockquote"><pre class="screen"><a class="indexterm" name="id676406"></a>— C type: <span class="structname">cl_object</span></pre><p>This is the type of a lisp object. For your C/C++ program, a <code class="literal">cl_object</code>
can be either a fixnum, a character, or a pointer to a union of structures (See
the header <code class="filename">object.h</code>). The actual interpretation of that object can be
guessed with the macro <code class="literal">type_of</code>.</p><p>For example, if <em class="replaceable"><code>x</code></em> is of type <code class="literal">cl_object</code>, and it is of type fixnum,
we may retrieve its value</p><pre class="screen">
if (type_of(x) == t_fixnum)
printf("Integer value: %d\n", fix(x));
</pre><p class="continues">If <em class="replaceable"><code>x</code></em> is of type <code class="literal">cl_object</code> and it does not contain an immediate
datatype, you may inspect the cell associated to the lisp object using <em class="replaceable"><code>x</code></em>
as a pointer. For example,</p><pre class="screen">
if (type_of(x) == t_cons)
printf("CAR = %x, CDR = %x\n", x->cons.car, x->cons.cdr);
else if (type_of(x) == t_string)
printf("String: %s\n", x->string.self);
</pre><p class="continues">You should see the following sections and the header <code class="filename">object.h</code> to learn
how to use the different fields of a <code class="literal">cl_object</code> pointer.</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><pre class="screen"><a class="indexterm" name="id676515"></a>— C type: <span class="structname">cl_type</span></pre><p>Enumeration type which distinguishes the different types of lisp objects. The
most important values are t_cons, t_fixnum, t_character, t_bignum, t_ratio,
t_singlefloat, t_doublefloat, t_complex, t_symbol, t_package, t_hashtable,
t_array, t_vector, t_string, t_bitvector, t_stream, t_random, t_readtable,
t_pathname, t_bytecodes, t_cfun, t_cclosure, t_gfun, t_instance, t_foreign and
t_thread.</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><pre class="screen"><a class="indexterm" name="id676541"></a>— Function: <span class="returnvalue">cl_type</span> <code class="function">type_of</code> (<span class="type">cl_object</span> <code class="varname">O</code>)</pre><p>If <em class="replaceable"><code>O</code></em> is a valid lisp object, <code class="literal">type_of(<em class="replaceable"><code>O</code></em>)</code> returns an integer
denoting the type that lisp object. That integer is one of the values of the
enumeration type <code class="literal">cl_type</code>.</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><pre class="screen"><a class="indexterm" name="id676596"></a>— Function: <span class="returnvalue">bool</span> <code class="function">FIXNUMP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676626"></a>— Function: <span class="returnvalue">bool</span> <code class="function">CHARACTERP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676655"></a>— Function: <span class="returnvalue">bool</span> <code class="function">CONSP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676685"></a>— Function: <span class="returnvalue">bool</span> <code class="function">LISTP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676714"></a>— Function: <span class="returnvalue">bool</span> <code class="function">ATOM</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676743"></a>— Function: <span class="returnvalue">bool</span> <code class="function">ARRAYP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676773"></a>— Function: <span class="returnvalue">bool</span> <code class="function">VECTORP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><pre class="screen"><a class="indexterm" name="id676802"></a>— Function: <span class="returnvalue">bool</span> <code class="function">STRINGP</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><p>Different macros that check whether <em class="replaceable"><code>o</code></em> belongs to the specified type.
These checks have been optimized, and are preferred over several calls to
<code class="literal">type_of</code>.</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><pre class="screen"><a class="indexterm" name="id676848"></a>— Function: <span class="returnvalue">bool</span> <code class="function">IMMEDIATE</code> (<span class="type">cl_object</span> <code class="varname">o</code>)</pre><p>Tells whether <em class="replaceable"><code>o</code></em> is an immediate datatype.</p></blockquote></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch24s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch25s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.6. Compiler examples </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.2. Constructing objects</td></tr></table></div></body></html>
