@node Manipulating Lisp objects
@section Manipulating Lisp objects

@menu
* Objects representation::
* Constructing objects::
@end menu

If you want to extend, fix or simply customize ECL for your own needs,
you should understand how the implementation works.

@cppdef cl_lispunion
@deftp @cind{} cl_lispunion { cons big ratio SF DF longfloat gencomplex csfloat cdfloat clfloat symbol pack hash array vector base_string string stream random readtable pathname bytecodes bclosure cfun cfunfixed cclosure d instance process queue lock rwlock condition_variable semaphore barrier mailbox cblock foreign frame weak sse }

Union containing all first-class ECL types.
@end deftp

@node Objects representation
@subsection Objects representation
In ECL a lisp object is represented by a type called
@code{cl_object}. 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.

@float Figure,fig:immediate_types
@caption{Immediate types}
@image{figures/immediate-types,,1in}
@end float

The topic of the immediate values and bit fiddling is nicely described
in
@url{http://www.more-magic.net/posts/internals-data-representation.html,
Peter Bex's blog} describing @url{http://www.call-cc.org/,Chicken
Scheme} internal data representation. We could borrow some ideas from it
(like improving @code{fixnum} bitness and providing more immediate
values). All changes to code related to immediate values should be
carefully @strong{benchmarked}.

The @code{fixnums} and characters are called immediate data types,
because they require no more than the @code{cl_object} datatype to store
all information. All other ECL 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.

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:

@verbatim
+---------+----------+
| CONS    |          |
+---------+----------+
|     car-pointer    |
+--------------------+
|     cdr-pointer    |
+--------------------+
@end verbatim

@cfindex --enable-small-cons [YES|no]

Note, that this is one of the possible implementation of
@code{cons}. The second one (currently default) uses the immediate value
for the @code{list} and consumes two words instead of three. Such
implementation is more memory and speed efficient (according to the
comments in the source code):

@verbatim
/*
 * CONSES
 *
 * We implement two variants. The "small cons" type carries the type
 * information in the least significant bits of the pointer. We have
 * to do some pointer arithmetics to find out the CAR / CDR of the
 * cons but the overall result is faster and memory efficient, only
 * using two words per cons.
 *
 * The other scheme stores conses as three-words objects, the first
 * word carrying the type information. This is kept for backward
 * compatibility and also because the oldest garbage collector does
 * not yet support the smaller datatype.
 *
 * To make code portable and independent of the representation, only
 * access the objects using the common macros below (that is all
 * except ECL_CONS_PTR or ECL_PTR_CONS).
 */
@end verbatim

@cppdef cl_object
@deftp @cind{} cl_object
This is the type of a lisp object. For your C/C++ program, a cl_object
can be either a fixnum, a character, or a pointer to a union of
structures (See @code{cl_lispunion} in the header object.h). The actual
interpretation of that object can be guessed with the macro
@code{ecl_t_of}.

@subsubheading Example
@exindex @code{cl_object} checking the type with @code{ecl_t_of}

For example, if x is of type cl_object, and it is of type fixnum, we may
retrieve its value:

@example
if (ecl_t_of(x) == t_fixnum)
    printf("Integer value: %d\n", ecl_fixnum(x));
@end example

@subsubheading Example
@exindex Accessing underlying @code{cl_object} structure

If @code{x} is of type @code{cl_object} and it does not contain an
immediate datatype, you may inspect the cell associated to the lisp
object using @code{x} as a pointer. For example:

@example
if (ecl_t_of(x) == t_vector)
    printf("Vector's dimension is: %d\n", x->vector.dim);
@end example

You should see the following sections and the header object.h to learn
how to use the different fields of a @code{cl_object} pointer.
@end deftp

@deftp @cind{} cl_type
Enumeration type which distinguishes the different types of lisp
objects. The most important values are:

@cppdef t_start
@cppdef t_list
@cppdef t_character
@cppdef t_fixnum
@cppdef t_bignum
@cppdef t_ratio
@c @cppdef t_shortfloat
@cppdef t_singlefloat
@c #ifdef ECL_LONG_FLOAT
@cppdef t_longfloat
@c #endif
@cppdef t_complex
@c #ifdef ECL_COMPLEX_FLOAT
@cppdef t_csfloat
@cppdef t_cdfloat
@cppdef t_clfloat
@c #endif
@cppdef t_symbol
@cppdef t_package
@cppdef t_hashtable
@cppdef t_array
@cppdef t_vector
@c #ifdef ECL_UNICODE
@cppdef t_string
@c #endif
@cppdef t_base_string
@cppdef t_bitvector
@cppdef t_stream
@cppdef t_random
@cppdef t_readtable
@cppdef t_pathname
@cppdef t_bytecodes
@cppdef t_bclosure
@cppdef t_cfun
@cppdef t_cfunfixed
@cppdef t_cclosure
@cppdef t_instance
@cppdef t_structure = t_instance
@c #ifdef ECL_THREADS
@cppdef t_process
@cppdef t_lock
@cppdef t_rwlock
@cppdef t_condition_variable
@cppdef t_semaphore
@cppdef t_barrier
@cppdef t_mailbox
@c #endif
@cppdef t_codeblock
@cppdef t_foreign
@cppdef t_frame
@cppdef t_weak_pointer
@c #ifdef ECL_SSE2
@cppdef t_sse_pack
@c #endif
@cppdef t_end
@cppdef t_other
@cppdef t_contiguous – contiguous block

@code{t_cons} @code{t_fixnum}, @code{t_character}, @code{t_bignum},
@code{t_ratio}, @code{t_singlefloat}, @code{t_doublefloat},
@code{t_complex}, @code{t_symbol}, @code{t_package}, @code{t_hashtable},
@code{t_array}, @code{t_vector}, @code{t_string}, @code{t_bitvector},
@code{t_stream}, @code{t_random}, @code{t_readtable}, @code{t_pathname},
@code{t_bytecodes}, @code{t_cfun}, @code{t_cclosure}, @code{t_gfun},
@code{t_instance}, @code{t_foreign} and @code{t_thread}.
@end deftp

@cppdef ecl_t_of
@deftypefun cl_type ecl_t_of (cl_object x)
If @var{x} is a valid lisp object, @code{ecl_t_of(x)} returns an integer
denoting the type that lisp object. That integer is one of the values of
the enumeration type @code{cl_type}.
@end deftypefun

@cppdef ECL_CHARACTERP
@cppdef ECL_BASE_CHAR_P
@cppdef ECL_BASE_CHAR_CODE_P
@cppdef ECL_NUMBER_TYPE_P
@cppdef ECL_COMPLEXP
@cppdef ECL_REAL_TYPE_P
@cppdef ECL_FIXNUMP
@cppdef ECL_BIGNUMP
@cppdef ECL_SINGLE_FLOAT_P
@cppdef ECL_DOUBLE_FLOAT_P
@cppdef ECL_LONG_FLOAT_P
@cppdef ECL_CONSP
@cppdef ECL_LISTP
@cppdef ECL_ATOM
@cppdef ECL_SYMBOLP
@cppdef ECL_ARRAYP
@cppdef ECL_VECTORP
@cppdef ECL_BIT_VECTOR_P
@cppdef ECL_STRINGP
@cppdef ECL_HASH_TABLE_P
@cppdef ECL_RANDOM_STATE_P
@cppdef ECL_PACKAGEP
@cppdef ECL_PATHNAMEP
@cppdef ECL_READTABLEP
@cppdef ECL_FOREIGN_DATA_P
@cppdef ECL_SSE_PACK_P

@deftypefun bool ECL_CHARACTERP (cl_object o)
@deftypefunx bool ECL_BASE_CHAR_P (cl_object o)
@deftypefunx bool ECL_BASE_CHAR_CODE_P (ecl_character o)
@deftypefunx bool ECL_NUMBER_TYPE_P (cl_object o)
@deftypefunx bool ECL_COMPLEXP (cl_object o)
@deftypefunx bool ECL_REAL_TYPE_P (cl_object o)
@deftypefunx bool ECL_FIXNUMP (cl_object o)
@deftypefunx bool ECL_BIGNUMP (cl_object o)
@deftypefunx bool ECL_SINGLE_FLOAT_P (cl_object o)
@deftypefunx bool ECL_DOUBLE_FLOAT_P (cl_object o)
@deftypefunx bool ECL_LONG_FLOAT_P (cl_object o)
@deftypefunx bool ECL_CONSP (cl_object o)
@deftypefunx bool ECL_LISTP (cl_object o)
@deftypefunx bool ECL_ATOM (cl_object o)
@deftypefunx bool ECL_SYMBOLP (cl_object o)
@deftypefunx bool ECL_ARRAYP (cl_object o)
@deftypefunx bool ECL_VECTORP (cl_object o)
@deftypefunx bool ECL_BIT_VECTOR_P (cl_object o)
@deftypefunx bool ECL_STRINGP (cl_object o)
@deftypefunx bool ECL_HASH_TABLE_P (cl_object o)
@deftypefunx bool ECL_RANDOM_STATE_P (cl_object o)
@deftypefunx bool ECL_PACKAGEP (cl_object o)
@deftypefunx bool ECL_PATHNAMEP (cl_object o)
@deftypefunx bool ECL_READTABLEP (cl_object o)
@deftypefunx bool ECL_FOREIGN_DATA_P (cl_object o)
@deftypefunx bool ECL_SSE_PACK_P (cl_object o)

Different macros that check whether @var{o} belongs to the specified
type. These checks have been optimized, and are preferred over several
calls to @code{ecl_t_of}.
@end deftypefun

@cppdef ECL_IMMEDIATE
@deftypefun bool ECL_IMMEDIATE (cl_object o)
Tells whether @var{x} is an immediate datatype.
@end deftypefun

@node Constructing objects
@subsection Constructing objects

On each of the following sections we will document the standard
interface for building objects of different types. For some objects,
though, it is too difficult to make a C interface that resembles all of
the functionality in the lisp environment. In those cases you need to

@enumerate
@item build the objects from their textual representation, or
@item use the evaluator to build these objects.
@end enumerate

The first way makes use of a C or Lisp string to construct an
object. The two functions you need to know are the following ones.

@cppdef c_string_to_object
@cppdef ecl_read_from_cstring
@cppdef si_string_to_object
@defun si::string-to-object string &optional (err-value nil)
@end defun
@deftypefun cl_object si_string_to_object (cl_narg narg, cl_object str, ...)
@deftypefunx cl_object ecl_read_from_cstring (const char *s)
@coderef{ecl_read_from_cstring} builds a lisp object from a C string
which contains a suitable representation of a lisp
object. @coderef{si_string_to_object} performs the same task, but uses a
lisp string, and therefore it is less useful.

@itemize @bullet
@item @strong{DEPRECATED} @coderef{c_string_to_object} – equivalent to @coderef{ecl_read_from_cstring}
@end itemize

@subsubheading Example
@exindex @coderef{ecl_read_from_cstring} constructing Lisp objects in C

Using a C string
@example
cl_object array1 = ecl_read_from_cstring("#(1 2 3 4)");
@end example

Using a Lisp string
@example
cl_object string = make_simple_base_string("#(1 2 3 4)");
cl_object array2 = si_string_to_object(string);
@end example
@end deftypefun

@subheading Integers
Common-Lisp distinguishes two types of integer types: @code{bignum}s and
@code{fixnum}s. A fixnum is a small integer, which ideally occupies only
a word of memory and which is between the values
@coderef{MOST-NEGATIVE-FIXNUM} and @coderef{MOST-POSITIVE-FIXNUM}. A
@code{bignum} is any integer which is not a @code{fixnum} and it is only
constrained by the amount of memory available to represent it.

In ECL a @code{fixnum} is an integer that, together with the tag bits,
fits in a word of memory. The size of a word, and thus the size of a
@code{fixnum}, varies from one architecture to another, and you should
refer to the types and constants in the ecl.h header to make sure that
your C extensions are portable. All other integers are stored as
@code{bignum}s, they are not immediate objects, they take up a variable
amount of memory and the GNU Multiprecision Library is required to
create, manipulate and calculate with them.

@cppdef cl_fixnum
@deftp @cind{} cl_fixnum
This is a C signed integer type capable of holding a whole @code{fixnum}
without any loss of precision. The opposite is not true, and you may
create a @code{cl_fixnum} which exceeds the limits of a fixnum and
should be stored as a @code{bignum}.
@end deftp

@cppdef cl_index
@deftp @cind{} cl_index
This is a C unsigned integer type capable of holding a non-negative
@code{fixnum} without loss of precision. Typically, a @code{cl_index} is
used as an index into an array, or into a proper list, etc.
@end deftp

@cppdef MOST_NEGATIVE_FIXNUM
@cppdef MOST_POSITIVE_FIXNUM
@lspdef MOST-NEGATIVE-FIXNUM
@lspdef MOST-POSITIVE-FIXNUM
@defvr {Constant} MOST_NEGATIVE_FIXNUM
@defvrx {Constant} MOST_POSITIVE_FIXNUM
These constants mark the limits of a @code{fixnum}.
@end defvr

@cppdef ecl_fixnum_lower
@cppdef ecl_fixnum_greater
@cppdef ecl_fixnum_leq
@cppdef ecl_fixnum_geq
@cppdef ecl_fixnum_plusp
@cppdef ecl_fixnum_minusp
@deftypefun bool ecl_fixnum_lower (cl_fixnum a, cl_fixnum b)
@deftypefunx bool ecl_fixnum_greater (cl_fixnum a, cl_fixnum b)
@deftypefunx bool ecl_fixnum_leq (cl_fixnum a, cl_fixnum b)
@deftypefunx bool ecl_fixnum_geq (cl_fixnum a, cl_fixnum b)
@deftypefunx bool ecl_fixnum_plusp (cl_fixnum a)
@deftypefunx bool ecl_fixnum_minusp (cl_fixnum a)
Operations on @code{fixnums} (comparison and predicates).
@end deftypefun

@cppindex ecl_make_fixnum
@cppindex ecl_fixnum
@cppindex MAKE_FIXNUM
@cppindex fix
@deftypefun cl_object ecl_make_fixnum (cl_fixnum n)
@deftypefunx cl_fixnum ecl_fixnum (cl_object o)
@code{ecl_make_fixnum} converts from an integer to a lisp object, while
the @code{ecl_fixnum} does the opposite (converts lisp object fixnum to
integer). These functions do @strong{not} check their arguments.
@itemize @bullet
@item @strong{DEPRECATED} @code{MAKE_FIXNUM} – equivalent to @code{ecl_make_fixnum}
@item @strong{DEPRECATED} @code{fix} – equivalent to @code{ecl_fixnum}
@end itemize
@end deftypefun

@cppindex cl_fixnum
@cppindex cl_index
@cppdef fixint
@cppdef fixnint
@deftypefun cl_fixnum fixint (cl_object o)
@deftypefunx cl_index fixnint (cl_object o)
Safe conversion of a lisp @code{fixnum} to a C integer of the
appropriate size. Signals an error if @var{o} is not of fixnum type.

@coderef{fixnint} additionally ensure that @var{o} is not negative.
@end deftypefun

@subheading Characters

@cfindex --enable-unicode [32|16|no]

ECL has two types of characters – one fits in the C type char, while
the other is used when ECL is built with a configure option
@code{--enable-unicode} which defaults to 32 (characters are stored in
32bit variable and codepoints have 21-bits).

@cppindex ecl_character
@cppindex ecl_base_char
@deftp @cind{} ecl_character
Immediate type @code{t_character}. If ECL built with Unicode support,
then may be either base or extended character, which may be
distinguished with the predicate @coderef{ECL_BASE_CHAR_P}.

Additionally we have @coderef{ecl_base_char} for base strings, which is an
equivalent to the ordinary char.

@subsubheading Example
@exindex distinguishing between base and Unicode character
@example
if (ECL_CHARACTERP(o) && ECL_BASE_CHAR_P(o))
    printf("Base character: %c\n", ECL_CHAR_CODE(o));
@end example
@end deftp

@cppindex ECL_CHAR_CODE_LIMIT
@cppindex CHAR_CODE_LIMIT
@defvr {Constant} ECL_CHAR_CODE_LIMIT
Each character is assigned an integer code which ranges from 0 to
(ECL_CHAR_CODE_LIMIT-1).
@itemize @bullet
@item @strong{DEPRECATED} @code{CHAR_CODE_LIMIT} – equivalent to @code{ECL_CHAR_CODE_LIMIT}
@end itemize
@end defvr

@cppindex ecl_char_code
@cppindex ecl_base_char_code
@cppindex ECL_CHAR_CODE
@cppindex ECL_CODE_CHAR
@cppindex CODE_CHAR
@cppindex CHAR_CODE
@deftypefun cl_object ECL_CODE_CHAR (ecl_character o)
@deftypefunx ecl_character ECL_CHAR_CODE (cl_object o)
@deftypefunx ecl_character ecl_char_code (cl_object o)
@deftypefunx ecl_base_char ecl_base_char_code (cl_object o)
@code{ECL_CHAR_CODE}, @code{ecl_char_code} and
@code{ecl_base_char_code} return the integer code associated to a
lisp character. @code{ecl_char_code} and @code{ecl_base_char_code}
perform a safe conversion, while @code{ECL_CHAR_CODE} doesn't check
its argument.

@code{ECL_CODE_CHAR} returns the lisp character associated to an integer
code. It does not check its arguments.

@itemize @bullet
@item @strong{DEPRECATED} @code{CHAR_CODE} – equivalent to @code{ECL_CHAR_CODE}
@item @strong{DEPRECATED} @code{CODE_CHAR} – equivalent to @code{ECL_CODE_CHAR}
@end itemize
@end deftypefun

@cppdef ecl_char_eq
@cppdef ecl_char_equal
@deftypefun bool ecl_char_eq (cl_object x, cl_object y)
@deftypefunx bool ecl_char_equal (cl_object x, cl_object y)
Compare two characters for equality. char_eq take case into account and
char_equal ignores it.
@end deftypefun

@cppdef ecl_char_cmp
@cppdef ecl_char_compare
@deftypefun int ecl_char_cmp (cl_object x, cl_object y)
@deftypefunx int ecl_char_compare (cl_object x, cl_object y)
Compare the relative order of two characters. @coderef{ecl_char_cmp}
takes care of case and @coderef{ecl_char_compare} converts all
characters to uppercase before comparing them.
@end deftypefun

@subheading Arrays

An array is an aggregate of data of a common type, which can be accessed
with one or more non-negative indices. ECL stores arrays as a C structure
with a pointer to the region of memory which contains the actual
data. The cell of an array datatype varies depending on whether it is a
vector, a bit-vector, a multidimensional array or a string.

@cppdef ECL_ADJUSTABLE_ARRAY_P
@cppdef ECL_ARRAY_HAS_FILL_POINTER_P
@deftypefun bool ECL_ADJUSTABLE_ARRAY_P (cl_object x)
@deftypefunx bool ECL_ARRAY_HAS_FILL_POINTER_P (cl_object x)
All arrays (arrays, strings and bit-vectors) may be tested for being
adjustable and whenever they have a fill pointer with this two
macros. They don't check the type of their arguments.
@end deftypefun

@cppdef ecl_vector
@deftp @cind{} ecl_vector
If @code{x} contains a vector, you can access the following fields:

@table @code
@item x->vector.elttype
The type of the elements of the vector.
@item x->vector.displaced
List storing the vectors that @code{x} is displaced from and that x
displaces to.
@item x->vector.dim
The maximum number of elements.
@item x->vector.fillp
Actual number of elements in the vector or @code{fill pointer}.
@item x->vector.self
Union of pointers of different types. You should choose the right
pointer depending on @var{x->vector.elttype}.
@end table
@end deftp

@cppdef ecl_array
@deftp @cind{} ecl_array
If @code{x} contains a multidimensional array, you can access the
following fields:

@table @code
@item x->array.elttype
The type of the elements of the array.
@item x->array.rank
The number of array dimensions.
@item x->array.displaced
List storing the arrays that @code{x} is displaced from and that x
displaces to.
@item x->array.dim
The maximum number of elements.
@item x->array.dims[]
Array with the dimensions of the array. The elements range from
@code{x->array.dim[0]} to @code{x->array.dim[x->array.rank-1]}.
@item x->array.fillp
Actual number of elements in the array or @code{fill pointer}.
@item x->array.self
Union of pointers of different types. You should choose the right
pointer depending on @var{x->array.elttype}.
@end table
@end deftp

@cppindex cl_elttype
@deftp @cind{} cl_elttype ecl_aet_object ecl_aet_sf ecl_aet_df ecl_aet_lf ecl_aet_csf ecl_aet_cdf ecl_aet_clf ecl_aet_bit ecl_aet_fix ecl_aet_index ecl_aet_b8 ecl_aet_i8 ecl_aet_b16 ecl_aet_i16 ecl_aet_b32 ecl_aet_i32 ecl_aet_b64 ecl_aet_i64 ecl_aet_ch ecl_aet_bc

Each array is of an specialized type which is the type of the elements
of the array. ECL has arrays only a few following specialized types, and
for each of these types there is a C integer which is the corresponding
value of @code{x->array.elttype} or @code{x->vector.elttype}. We list
some of those types together with the C constant that denotes that type:

@table @var
@item t
@code{ecl_aet_object}
@item single-float
@code{ecl_aet_sf}
@item double-float
@code{ecl_aet_df}
@item long-float
@code{ecl_aet_lf}
@item (COMPLEX SINGLE-FLOAT)
@code{ecl_aet_csf}
@item (COMPLEX DOUBLE-FLOAT)
@code{ecl_aet_cdf}
@item (COMPLEX LONG-FLOAT)
@code{ecl_aet_clf}
@item BIT
@code{ecl_aet_bit}
@item FIXNUM
@code{ecl_aet_fix}
@item INDEX
@code{ecl_aet_index}
@item CHARACTER
@code{ecl_aet_ch}
@item BASE-CHAR
@code{ecl_aet_bc}
@end table
@end deftp

@cppindex ecl_array_elttype
@deftypefun cl_elttype ecl_array_elttype (cl_object array)
Returns the element type of the array @code{o}, which can be a string, a
bit-vector, vector, or a multidimensional array.

@subsubheading Example
@exindex @code{ecl_array_elttype} different types of objects
For example, the code

@example
ecl_array_elttype(ecl_read_from_cstring("\"AAA\""));  /* returns ecl_aet_ch */
ecl_array_elttype(ecl_read_from_cstring("#(A B C)")); /* returns ecl_aet_object */
@end example
@end deftypefun

@cppindex ecl_aref
@cppindex ecl_aset
@deftypefun cl_object ecl_aref (cl_object x, cl_index index)
@deftypefunx cl_object ecl_aset (cl_object x, cl_index index, cl_object value)
These functions are used to retrieve and set the elements of an
array. The elements are accessed with one index, index, as in the lisp
function ROW-MAJOR-AREF.

@subsubheading Example
@exindex @code{ecl_aref} and @code{ecl_aset} accessing arrays
@example
cl_object array = ecl_read_from_cstring("#2A((1 2) (3 4))");
cl_object x = ecl_aref(array, 3);
cl_print(1, x);	/* Outputs 4 */
ecl_aset(array, 3, ecl_make_fixnum(5));
cl_print(1, array); /* Outputs #2A((1 2) (3 5)) */
@end example
@end deftypefun

@cppindex ecl_aref1
@cppindex ecl_aset1
@deftypefun cl_object ecl_aref1 (cl_object x, cl_index index)
@deftypefunx cl_object ecl_aset1 (cl_object x, cl_index index, cl_object value)
These functions are similar to @code{aref} and @code{aset}, but they operate on vectors.

@subsubheading Example
@exindex @code{ecl_aref1} and @code{ecl_aset1} accessing vectors
@example
cl_object array = ecl_read_from_cstring("#(1 2 3 4)");
cl_object x = ecl_aref1(array, 3);
cl_print(1, x);	    /* Outputs 4 */
ecl_aset1(array, 3, ecl_make_fixnum(5));
cl_print(1, array); /* Outputs #(1 2 3 5) */
@end example
@end deftypefun

@subheading Strings

A string, both in Common-Lisp and in ECL is nothing but a vector of
characters. Therefore, almost everything mentioned in the section of
arrays remains valid here.

The only important difference is that ECL stores the base-strings
(non-Unicode version of a string) as a lisp object with a pointer to a
zero terminated C string. Thus, if a string has n characters, ECL will
reserve n+1 bytes for the base-string. This allows us to pass the
base-string self pointer to any C routine.

@cppdef ecl_string
@cppdef ecl_base_string
@deftp @cind{} ecl_string
@deftpx @cind{} ecl_base_string
If @code{x} is a lisp object of type string or a base-string, we can
access the following fields:
@table @code
@item x->string.dim  x->base_string.dim
Actual number of characters in the string.
@item x->string.fillp  x->base_string.fillp
Actual number of characters in the string.
@item x->string.self  x->base_string.self
Pointer to the characters (appropriately @code{ecl_character}'s and @code{ecl_base_char}'s).
@end table
@end deftp

@cppdef ECL_EXTENDED_STRING_P
@cppdef ECL_BASE_STRING_P
@deftypefun bool ECL_EXTENDED_STRING_P (cl_object object)
@deftypefunx bool ECL_BASE_STRING_P (cl_object object)

Verifies if an objects is an extended or base string. If Unicode isn't
supported, then @code{ECL_EXTENDED_STRING_P} always returns 0.
@end deftypefun

@subheading Bit-vectors

Bit-vector operations are implemented in file
@code{src/c/array.d}. Bit-vector shares the structure with a vector,
therefore, almost everything mentioned in the section of arrays remains
valid here.

@subheading Streams

Streams implementation is a broad topic. Most of the implementation is
done in the file @code{src/c/file.d}. Stream handling may have different
implementations referred by a member pointer @code{ops}.

Additionally on top of that we have implemented @emph{Gray Streams} (in
portable Common Lisp) in file @code{src/clos/streams.lsp}, which may be
somewhat slower (we need to benchmark it!). This implementation is in a
separate package @var{GRAY}. We may redefine functions in the
@var{COMMON-LISP} package with a function @code{redefine-cl-functions}
at run-time.

@cppdef ecl_file_pos
@deftp @cind{} ecl_file_ops write_* read_* unread_* peek_* listen clear_input clear_output finish_output force_output input_p output_p interactive_p element_type length get_position set_position column close
@end deftp

@cppdef ecl_stream
@deftp @cind{} ecl_stream
@table @code
@item ecl_smmode mode
Stream mode (in example @code{ecl_smm_string_input}).
@item int closed
Whenever stream is closed or not.
@item ecl_file_ops *ops
Pointer to the structure containing operation implementations (dispatch
table).
@item union file
Union of ANSI C streams (FILE *stream) and POSIX files interface
(cl_fixnum descriptor).
@item cl_object object0, object1
Some objects (may be used for a specific implementation purposes).
@item cl_object byte_stack
Buffer for unread bytes.
@item cl_index column
File column.
@item cl_fixnum last_char
Last character read.
@item cl_fixnum last_code[2]
Actual composition of the last character.
@item cl_fixnum int0 int1
Some integers (may be used for a specific implementation purposes).
@item cl_index byte_size
Size of byte in binary streams.
@item cl_fixnum last_op
0: unknown, 1: reading, -1: writing
@item char *buffer
Buffer for FILE
@item cl_object format
external format
@item cl_eformat_encoder encoder
@item cl_eformat_encoder decoder
@item cl_object format_table
@item in flags
Character table, flags, etc
@item ecl_character eof_character
@end table
@end deftp

@cppdef ECL_ANSI_STREAM_P
@deftypefun bool ECL_ANSI_STREAM_P (cl_object o)
Predicate determining if @code{o} is a first-class stream object.
@end deftypefun

@cppdef ECL_ANSI_STREAM_TYPE_P
@deftypefun bool ECL_ANSI_STREAM_TYPE_P (cl_object o, ecl_smmode m)
Predicate determining if @code{o} is a first-class stream object of
type @code{m}.
@end deftypefun

@subheading Structures

Structures and instances share the same datatype @code{t_instance} (
with a few exceptions. Structure implementation details are the file
@code{src/c/structure.d}.

@cppdef ECL_STRUCT_TYPE
@cppdef ECL_STRUCT_SLOTS
@cppdef ECL_STRUCT_LENGTH
@cppdef ECL_STRUCT_SLOT
@cppdef ECL_STRUCT_NAME
@deftypefun cl_object ECL_STRUCT_TYPE (cl_object x)
@deftypefunx cl_object ECL_STRUCT_SLOTS (cl_object x)
@deftypefunx cl_object ECL_STRUCT_LENGTH (cl_object x)
@deftypefunx cl_object ECL_STRUCT_SLOT (cl_object x, cl_index i)
@deftypefunx cl_object ECL_STRUCT_NAME (cl_object x)
Convenience functions for the structures.
@end deftypefun

@subheading Instances

@cppdef ECL_CLASS_OF
@cppdef ECL_SPEC_FLAG
@cppdef ECL_SPEC_OBJECT
@cppdef ECL_CLASS_NAME
@cppdef ECL_CLASS_SUPERIORS
@cppdef ECL_CLASS_INFERIORS
@cppdef ECL_CLASS_SLOTS
@cppdef ECL_CLASS_CPL
@cppdef ECL_INSTANCEP

@deftypefun cl_object ECL_CLASS_OF (cl_object x)
@deftypefunx cl_object ECL_SPEC_FLAG (cl_object x)
@deftypefunx cl_object ECL_SPEC_OBJECT (cl_object x)
@deftypefunx cl_object ECL_CLASS_NAME (cl_object x)
@deftypefunx cl_object ECL_CLASS_SUPERIORS (cl_object x)
@deftypefunx cl_object ECL_CLASS_INFERIORS (cl_object x)
@deftypefunx cl_object ECL_CLASS_SLOTS (cl_object x)
@deftypefunx cl_object ECL_CLASS_CPL (cl_object x)
@deftypefunx bool ECL_INSTANCEP (cl_object x)
Convenience functions for the structures.
@end deftypefun

@subheading Bytecodes

A bytecodes object is a lisp object with a piece of code that can be
interpreted. The objects of type @code{t_bytecodes} are implicitly
constructed by a call to eval, but can also be explicitly constructed
with the @code{si_make_lambda} function.

@cppdef si_safe_eval
@cppdef cl_safe_eval
@cppdef cl_eval
@defun si:safe-eval form env &optional err-value
@end defun
@deftypefun cl_object si_safe_eval (cl_narg narg, cl_object form, cl_object env, ...)

@code{si_safe_eval} evaluates @code{form} in the lexical
environment@footnote{Note that @code{env} must be a lexical
environment as used in the interpreter, @xref{The lexical
environment}} @code{env}, which can be @code{ECL_NIL}. Before
evaluating it, the expression form is bytecompiled. If the form
signals an error, or tries to jump to an outer point, the function has
two choices: by default, it will invoke a debugger, but if a third
value is supplied, then @code{si_safe_eval} will not use a debugger
but rather return that value.

@itemize @bullet
@item @strong{DEPRECATED} @code{cl_object cl_eval (cl_object form)} -
@code{cl_eval} is the equivalent of @code{si_safe_eval} but without
environment and with no @code{err-value} supplied. It exists only for
compatibility with previous versions.
@item @strong{DEPRECATED} @code{cl_object cl_safe_eval (cl_object form, cl_object env, cl_object err_value)} -
Equivalent of @code{si_safe_eval}.
@end itemize

@subheading Example
@exindex @code{si_safe_eval}
@example
cl_object form = ecl_read_from_cstring("(print 1)");
si_safe_eval(2, form, ECL_NIL);
si_safe_eval(3, form, ECL_NIL, ecl_make_fixnum(3)); /* on error function will return 3 */
@end example
@end deftypefun

@cppdef si_make_lambda
@deftypefun cl_object si_make_lambda (cl_object name, cl_object def)
Builds an interpreted lisp function with name given by the symbol name
and body given by @code{def}.

@subheading Example
@exindex @code{si_make_lambda} building functions

For instance, we would achieve the equivalent of

@lisp
(funcall #'(lambda (x y)
             (block foo (+ x y)))
         1 2)
@end lisp

with the following code

@example
cl_object def = ecl_read_from_cstring("((x y) (+ x y))");
cl_object name = ecl_make_symbol("FOO", "COMMON-LISP-USER");
cl_object fun = si_make_lambda(name, def);
return cl_funcall(3, fun, ecl_make_fixnum(1), ecl_make_fixnum(2));
@end example

Notice that @code{si_make_lambda} performs a bytecodes compilation of
the definition and thus it may signal some errors. Such errors are not
handled by the routine itself so you might consider using
@code{si_safe_eval} instead.
@end deftypefun
