Next: , Previous: , Up: Top   [Contents][Index]

3 Standards


Next: , Up: Standards   [Contents][Index]

3.1 Overview

3.1.1 Reading this manual

Common Lisp users

Embeddable Common Lisp supports all Common-Lisp data types exactly as defined in the [see ANSI]. All functions and macros are expected to behave as described in that document and in the HyperSpec [see HyperSpec] which is the online version of [see ANSI]. In other words, the Standard is the basic reference for Common Lisp and also for Embeddable Common Lisp, and this part of the manual just complements it, describing implementation-specific features such as:

In order to aid in locating these differences, this first part of the manual copies the structure of the ANSI Common-Lisp standard, having the same number of chapters, each one with a set of sections documenting the implementation-specific details.

C/C++ programmers

The second goal of this document is to provide a reference for C programmers that want to create, manipulate and operate with Common Lisp programs at a lower level, or simply embedding Embeddable Common Lisp as a library.

The C/C++ reference evolves in parallel with the Common Lisp one, in the form of one section with the name "C Reference" for each chapter of the ANSI Common-Lisp standard. Much of what is presented in those sections is redundant with the Common Lisp specification. In particular, there is a one-to-one mapping between types and functions which should be obvious given the rules explained in the next section C Reference.

We must remark that the reference in this part of the manual is not enough to know how to embed Embeddable Common Lisp in a program. In practice the user or developer will also have to learn how to build programs (System building), interface with foreign libraries (Foreign Function Interface), manage memory (Memory Management), etc. These concepts are explained in a different (Embedding ECL) part of the book.

3.1.2 C Reference

One type for everything: cl_object

ECL is designed around the basic principle that Common Lisp already provides everything that a programmer could need, orienting itself around the creation and manipulation of Common Lisp objects: conses, arrays, strings, characters, ... When embedding ECL there should be no need to use other C/C++ types, except when interfacing data to and from those other languages.

All Common Lisp objects are represented internally through the same C type, cl_object, which is either a pointer to a union type or an integer, depending on the situation. While the inner guts of this type are exposed through various headers, the user should never rely on these details but rather use the macros and functions that are listed in this manual.

There are two types of Common Lisp objects: immediate and memory allocated ones. Immediate types fit in the bits of the cl_object word, and do not require the garbage collector to be created. The list of such types may depend on the platform, but it includes at least the fixnum and character types.

Memory allocated types on the other hand require the use of the garbage collector to be created. ECL abstracts this from the user providing enough constructors, either in the form of Common Lisp functions (cl_make_array(), cl_complex(),...), or in the form of C/C++ constructors (ecl_make_symbol(), etc).

Memory allocated types must always be kept alive so that the garbage collector does not reclaim them. This involves referencing the object from one of the places that the collector scans:

For memory allocation details See Memory Management. For object implementation details See Manipulating Lisp objects.

Naming conventions

As explained in the introduction, each of the chapters in the Common Lisp standard can also be implemented using C functions and types. The mapping between both languages is done using a small set of rules described below.

In addition to the Common Lisp core functions (cl_*), there exist functions which are devoted only to C/C++ programming, with tasks such as coercion of objects to and from C types, optimized functions, inlined macroexpansions, etc. These functions and macros typically carry the prefix ecl_ or ECL_ and only return one value, if any.

Most (if not all) Common Lisp functions and constructs available from C/C++ are available in “ANSI Dictionary” sections which are part of the [Standards] entries.

Only in Common Lisp

Some parts of the language are not available as C functions, even though they can be used in Common Lisp programs. These parts are either marked in the “ANSI Dictionary” sections using the tag Only in Common Lisp, or they are simply not mentioned (macros and special constructs). This typically happens with non-translatable constructs such as

In most of those cases there exist straightforward alternatives using the constructs and functions in ECL. For example, unwind-protect can be implemented using a C macro which is provided by ECL

cl_env_ptr env = ecl_process_env();
CL_UNWIND_PROTECT_BEGIN(env) {
    /* protected code goes here */
} CL_UNWIND_PROTECT_EXIT {
    /* exit code goes here */
} CL_UNWIND_PROTECT_END;

Common Lisp generic functions can be directly accessed using funcall or apply and the function name, as shown in the code below

cl_object name = ecl_make_symbol("MY-GENERIC-FUNCTION","CL-USER");
cl_object output = cl_funcall(2, name, argument);

Identifying these alternatives requires some knowledge of Common Lisp, which is why it is recommended to approach the embeddable components in ECL only when there is some familiarity with the language.


Next: , Previous: , Up: Standards   [Contents][Index]

3.2 Evaluation and compilation

3.2.1 Compiler declaration OPTIMIZE

The OPTIMIZE declaration includes three concepts: DEBUG, SPEED, SAFETY and SPACE. Each of these declarations can take one of the integer values 0, 1, 2 and 3. According to these values, the implementation may decide how to compie or interpret a given lisp form.

ECL currently does not use all these declarations, but some of them definitely affect the speed and behavior of compiled functions. For instance, the DEBUG declaration, as shown in Table 3.1, the value of debugging is zero, the function will not appear in the debugger and, if redefined, some functions might not see the redefinition.

Behavior0123
Compiled functions in the same source file are called directlyYYNN
Compiled function appears in debugger backtraceNNYY
All functions get a global entry (SI:C-LOCAL is ignored)NNYY

Table 3.1: Behavior for different levels of DEBUG

A bit more critical is the value of SAFETY because as shown in Table 3.2, it may affect the safety checks generated by the compiler. In particular, in some circumstances the compiler may assume that the arguments to a function are properly typed. For instance, if you compile with a low value of SAFETY, and invoke RPLACA, the consequences are unspecified.

Behavior0123
The compiler generates type checks for the arguments of a lambda form, thus enforcing any type declaration written by the user.NYYY
The value of an expression or a variable declared by the user is assumed to be right.YYNN
We believe type declarations and type inference and, if the type of a form is inferred to be right for a function, slot accessor, etc, this may be inlined. Affects functions like CAR, CDR, etcYYNN
We believe types defined before compiling a file not change before the compiled code is loaded.YYNN
Arguments in a lisp form are assumed to have the appropriate types so that the form will not fail.YNNN
The slots or fields in a lisp object are accessed directly without type checks even if the type of the object could not be inferred (see line above). Affects functions like PATHNAME-TYPE, CAR, REST, etc.YNNN

Table 3.2: Behavior for different levels of SAFETY

3.2.2 C Reference

C/C++ identifier: cl_object cl_env_ptr ()

ECL stores information about each thread on a dedicated structure, which is the process environment. A pointer to this structure can be retrieved using the function or macro above. This pointer can be used for a variety of tasks, such as defining special variable bindings, controlling interrupts, retrieving function output values, etc.


Next: , Previous: , Up: Standards   [Contents][Index]

3.3 Types and classes

ECL defines the following additional built-in classes in the CL package:

3.3.1 C Reference

3.3.1.1 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
coercecl_object cl_coerce(cl_object object, cl_object result_type)
subtypepcl_object cl_subtypep(cl_narg narg, cl_object type1, cl_object type2, ...)
type-ofcl_object cl_type_of(cl_object object)
typepcl_object cl_typep(cl_narg narg, cl_object object, cl_object type_specifier, ...)
type-error-datum[Only in Common Lisp]
type-error-expected-type[Only in Common Lisp]

Next: , Previous: , Up: Standards   [Contents][Index]

3.4 Data and control flow


Next: , Up: Data and control flow   [Contents][Index]

3.4.1 Shadowed bindings

ANSI doesn’t specify what should happen if any of the LET, FLET and LABELS special operators contain many bindings sharing the same name. Because the behavior varies between the implementations and the programmer can’t rely on the spec ECL signals an error if such situation occur.

Moreover, while ANSI defines lambda list parameters in the terms of LET*, when used in function context programmer can’t provide an initialization forms for required parameters. If required parameters share the same name the error is signalled.

Described behavior is present in ECL since version 16.0.0. Previously the LET operator were using first binding. Both FLET and LABELS were signalling an error if C compiler was used and used the last binding as a visible one when the byte compiler was used.


Next: , Previous: , Up: Data and control flow   [Contents][Index]

3.4.2 Minimal compilation

Former versions of ECL, as well as many other lisps, used linked lists to represent code. Executing code thus meant traversing these lists and performing code transformations, such as macro expansion, every time that a statement was to be executed. The result was a slow and memory hungry interpreter.

Beginning with version 0.3, ECL was shipped with a bytecodes compiler and interpreter which circumvent the limitations of linked lists. When you enter code at the lisp prompt, or when you load a source file, ECL begins a process known as minimal compilation. Barely this process consists on parsing each form, macroexpanding it and translating it into an intermediate language made of bytecodes.

The bytecodes compiler is implemented in src/c/compiler.d. The main entry point is the lisp function si::make-lambda, which takes a name for the function and the body of the lambda lists, and produces a lisp object that can be invoked. For instance,

> (defvar fun (si::make-lambda 'f '((x) (1+ x))))
*FUN*
> (funcall fun 2)
3

ECL can only execute bytecodes. When a list is passed to EVAL it must be first compiled to bytecodes and, if the process succeeds, the resulting bytecodes are passed to the interpreter. Similarly, every time a function object is created, such as in DEFUN or DEFMACRO, the compiler processes the lambda form to produce a suitable bytecodes object.

The fact that ECL performs this eager compilation means that changes on a macro are not immediately seen in code which was already compiled. This has subtle implications. Take the following code:

> (defmacro f (a b) `(+ ,a ,b))
F
> (defun g (x y) (f x y))
G
> (g 1 2)
3
> (defmacro f (a b) `(- ,a ,b))
F
> (g 1 2)
3

The last statement always outputs 3 while in former implementations based on simple list traversal it would produce -1.


Next: , Previous: , Up: Data and control flow   [Contents][Index]

3.4.3 Function types

Functions in ECL can be of two types: they are either compiled to bytecodes or they have been compiled to machine code using a lisp to C translator and a C compiler. To the first category belong function loaded from lisp source files or entered at the toplevel. To the second category belong all functions in the ECL core environment and functions in files processed by compile or compile-file.

The output of (symbol-function fun) is one of the following:

ECL usually drops the source code of a function unless the global variable si:*keep-definitions* was true when the function was translated into bytecodes. Therefore, if you wish to use compile and disassemble on defined functions, you should issue (setq si:*keep-definitions* t) at the beginning of your session.

SI: *keep-definitions*

If set to T ECL will preserve the compiled function source code for disassembly and recompilation.

In Table 3.3 we list all Common Lisp values related to the limits of functions.

call-arguments-limit65536
lambda-parameters-limitcall-arguments-limit
multiple-values-limit64
lambda-list-keywords(&optional &rest &key &allow-other-keys &aux &whole &environment &body)

Table 3.3: Function related constants


Previous: , Up: Data and control flow   [Contents][Index]

3.4.4 C Calling conventions

ECL is implemented using either a C or a C++ compiler. This is not a limiting factor, but imposes some constraints on how these languages are used to implement functions, multiple values, closures, etc. In particular, while C functions can be called with a variable number of arguments, there is no facility to check how many values were actually passed. This forces us to have two types of functions in ECL

The previous conventions set some burden on the C programmer that calls ECL, for she must know the type of function that is being called and supply the right number of arguments. This burden disappears for Common Lisp programmers, though.

As an example let us assume that the user wants to invoke two functions which are part of the ANSI [see ANSI] standard and thus are exported with a C name. The first example is cl_cos, which takes just one argument and has a signature cl_object cl_cos(cl_object).

#include <math.h>
...
cl_object angle = ecl_make_double_float(M_PI);
cl_object c = cl_cos(angle);
printf("\nThe cosine of PI is %g\n", ecl_double_float(c));

The second example also involves some Mathematics, but now we are going to use the C function corresponding to +. As described in Numbers - Numbers C dictionary, the C name for the plus operator is cl_P and has a signature cl_object cl_P(cl_narg narg,...). Our example now reads as follows

cl_object one = ecl_make_fixnum(1);
cl_object two = cl_P(2, one, one);
cl_object three = cl_P(3, one, one, one);
printf("\n1 + 1 is %d\n", ecl_fixnum(two));
printf("\n1 + 1 + 1 is %d\n", ecl_fixnum(three));

Note that most Common Lisp functions will not have a C name. In this case one must use the symbol that names them to actually call the functions, using cl_funcall or cl_apply. The previous examples may thus be rewritten as follows

/* Symbol + in package CL */
cl_object plus = ecl_make_symbol("+","CL");
cl_object one = ecl_make_fixnum(1);
cl_object two = cl_funcall(3, plus, one, one);
cl_object three = cl_funcall(4, plus, one, one, one);
printf("\n1 + 1 is %d\n", ecl_fixnum(two));
printf("\n1 + 1 + 1 is %d\n", ecl_fixnum(three));

Another restriction of C and C++ is that functions can only take a limited number of arguments. In order to cope with this problem, ECL uses an internal stack to pass any argument above a hardcoded limit, ECL_C_CALL_ARGUMENTS_LIMIT, which is as of this writing 63. The use of this stack is transparently handled by the Common Lisp functions, such as apply, funcall and their C equivalents, and also by a set of macros, cl_va_arg, which can be used for coding functions that take an arbitrary name of arguments.

3.4.5 C Reference

Function: ecl_bds_bind (cl_env_ptr cl_env, cl_object var, cl_object value);
Function: ecl_bds_push (cl_env_ptr cl_env, cl_object var);

Bind a special variable

Description

Establishes a variable binding for the symbol var in the Common Lisp environment env, assigning it value.

This macro or function is the equivalent of LET* and LET.

ecl_bds_push does a similar thing, but reuses the old value of the same variable. It is thus the equivalent of (LET ((VAR VAR)) ...)

Every variable binding must undone when no longer needed. It is best practice to match each call to ecl_bds_bind by another call to ecl_bds_unwind in the same function.

Function: ecl_bds_unwind1 (cl_env_ptr cl_env);
Function: ecl_bds_unwind_n (cl_env_ptr cl_env, int n);

Undo one variable binding

Description

ecl_bds_unwind1 undoes the outermost variable binding, restoring the original value of the symbol in the process.

ecl_bds_unwind_n does the same, but for the n last variables.

Every variable binding must undone when no longer needed. It is best practice to match each call to ecl_bds_bind by another call to ecl_bds_unwind in the same function.

Macro: ecl_setq (cl_env_ptr cl_env, cl_object var, cl_object value);

C equivalent of setq

Description

Assigns value to the special variable denoted by the symbol var, in the Common Lisp environment cl_env.

This function implements a variable assignment, not a variable binding. It is thus the equivalent of setq.

Function: ecl_symbol_value (cl_env_ptr cl_env, cl_object var);

Description

Retrieves the value of the special variable or constant denoted by the symbol var, in the Common Lisp environment cl_env.

This function implements the equivalent of symbol-value and works both on special variables and constants.

If the symbol is not bound, an error is signaled.

Macro: typedef struct { ... } ecl_va_list[1];
Macro: ecl_va_start (ecl_va_list arglist, last_argument, narg, n_ordinary);
Macro: cl_object ecl_va_arg (ecl_va_list arglist);
Macro: cl_object ecl_va_end (ecl_va_list arglist);

Accepting a variable number of arguments

Description

The macros above are used to code a function that accepts an arbitrary number of arguments. We will describe them in a practical example

cl_object my_plus(cl_narg narg, cl_object required1, ...)
{
    cl_env_ptr env = ecl_process_env();
    cl_object other_value;
    ecl_va_list varargs;
    ecl_va_start(varargs, required1, narg, 1);
    while (narg > 1) {
        cl_object other_value = ecl_va_arg(varargs);
	required1 = ecl_plus(required1, other_value);
    }
    ecl_va_end(varargs);
    ecl_return1(env, required1);
}

The first thing to do is to declare the variable that will hold the arguments. This is varargs in our example and it has the type ecl_va_list.

This arguments list is initialized with the ecl_va_start macro, based on the supplied number of arguments, narg, the number of required arguments which are passed as ordinary C arguments (1 in this case), the last such ordinary arguments, required, and the buffer for the argument list, varargs.

Once varargs has been initialized, we can retrieve these values one by one using ecl_va_arg. Note that the returned value always has the type cl_object, for it is always a Common Lisp object.

The last statement before returning the output of the function is ecl_va_end. This macro performs any required cleanup and should never be omitted.

Function: cl_object ecl_nvalues (cl_env_ptr env);
Function: cl_object ecl_nth_value (cl_env_ptr env, int n);

Accessing output values

Description

Common Lisp functions may return zero, one or more values. In ECL, the first two cases do not require any special manipulation, as the C function returns either NIL or the first (zeroth) value directly. However, if one wishes to access additional values from a function, one needs to use these two macros or functions

Note that in both cases these macros and functions have to be used right after the Lisp function was called. This is so because other Lisp functions might destroy the content of the return stack.

Example

A C/C++ excerpt:

cl_env_ptr env = ecl_process_env();
cl_object a = ecl_make_fixnum(13);
cl_object b = ecl_make_fixnum(6);
cl_object modulus = cl_floor(2, a, b);
cl_object remainder = ecl_nth_value(env, 1);

The somewhat equivalent Common Lisp code:

(multiple-value-bind (modulus equivalent)
    (floor 13 6))
Function: ecl_return0 (cl_env_ptr cl_env);
Function: ecl_return1 (cl_env_ptr cl_env, cl_object value1);
Function: ecl_return2 (cl_env_ptr cl_env, cl_object value1, cl_object value2);
Function: ecl_return3 (cl_env_ptr cl_env, cl_object value1, cl_object value2, cl_object value3);

Returning multiple values

Description

Returns N values from a C/C++ function in a way that a Common Lisp function can recognize and use them. The 0-th value is returned directly, while values 1 to N are stored in the Common Lisp environment cl_env. This macro has to be used from a function which returns an object of type cl_object.

Macro: ECL_BLOCK_BEGIN
ECL_BLOCK_BEGIN(env,code) {

} ECL_BLOCK_END;

Description

ECL_BLOCK_BEGIN establishes a block named code that becomes visible for the Common Lisp code. This block can be used then as a target for cl_return.

env must be the value of the current Common Lisp environment, obtained with ecl_process_env.

The C/C++ program has to ensure that the code in ECL_BLOCK_END gets executed, avoiding a direct exit of the block via goto or a C/C++ return.

Macro: ECL_CATCH_BEGIN
ECL_CATCH_BEGIN(env,tag) {

} ECL_CATCH_END;

Description

ECL_CATCH_BEGIN establishes a destination for throw with the code given by tag.

env must be the value of the current Common Lisp environment, obtained with ecl_process_env.

The C/C++ program has to ensure that the code in ECL_CATCH_END gets executed, avoiding a direct exit of the catch block via goto or a C/C++ return.

Macro: ECL_UNWIND_PROTECT_BEGIN

C macro for unwind-protect

Synopsis

ECL_UNWIND_PROTECT_BEGIN(env) {

} ECL_UNWIND_PROTECT_EXIT {

} ECL_UNWIND_PROTECT_END;

Description

ECL_UNWIND_PROTECT_BEGIN establishes two blocks of C code that work like the equivalent ones in Common Lisp: a protected block, contained between the "BEGIN" and the "EXIT" statement, and the exit block, appearing immediately afterwards. The form guarantees that the exit block is always executed, even if the protected block attempts to exit via som nonlocal jump construct (throw, return, etc).

env must be the value of the current Common Lisp environment, obtained with ecl_process_env.

The utility of this construct is limited, for it only protects against nonlocal exits caused by Common Lisp constructs: it does not interfere with C goto, return or with C++ exceptions.

3.4.5.1 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function or constant
applycl_object cl_apply(cl_narg narg, cl_object function, ...)
call-arguments-limitECL_CALL_ARGUMENTS_LIMIT
compiled-function-pcl_object cl_compiled_function_p(cl_object object)
complementcl_object cl_complement(cl_object function)
constantlycl_object cl_constantly(cl_object value)
everycl_object cl_every(cl_narg narg, cl_object predicate, ...)
eqcl_object cl_eq(cl_object x, cl_object y)
eqlcl_object cl_eql(cl_object x, cl_object y)
equalcl_object cl_equal(cl_object x, cl_object y)
equalpcl_object cl_equalp(cl_object x, cl_object y)
fboundpcl_object cl_fboundp(cl_object function_name)
fdefinitioncl_object cl_fdefinition(cl_object function_name)
fmakunboundcl_object cl_fmakunbound(cl_object function_name)
funcallcl_object cl_funcall(cl_narg narg, cl_object function, ...)
function-lambda-expressioncl_object cl_function_lambda_expression(cl_object function)
functionpcl_object cl_functionp(cl_object object)
get-setf-expansioncl_object cl_get_setf_expansion(cl_narg narg, cl_object place, ...)
identitycl_object cl_identity(cl_object x)
LET, LET*cl_object ecl_bds_bind(cl_env_ptr env, cl_object symbol, cl_object value)
lambda-parameters-limitECL_LAMBDA_PARAMETERS_LIMIT
multiple-values-limitECL_MULTIPLE_VALUES_LIMIT
notcl_object cl_not(cl_object object)
noteverycl_object cl_notevery(cl_narg narg, cl_object predicate, ...)
notanycl_object cl_notany(cl_narg narg, cl_object predicate, ...)
setcl_object cl_set(cl_object symbol, cl_object value)
setqcl_object ecl_setq(cl_env_ptr env, cl_object symbol, cl_object value)
symbol-valuecl_object ecl_symbol_value(cl_env_ptr env, cl_object symbol)
somecl_object cl_some(cl_narg narg, cl_object predicate, ...)
values-listcl_object cl_values_list(cl_object list)

Next: , Previous: , Up: Standards   [Contents][Index]

3.5 Objects


Up: Objects   [Contents][Index]

3.5.1 C Reference

3.5.1.1 ANSI Dictionary

Common Lisp and C equivalence

Lisp symbolC function
function-keywords[Only in Common Lisp]
ensure-generic-functioncl_object cl_ensure_generic_function(cl_narg narg, cl_object function_name, ...)
allocate-instance[Only in Common Lisp]
reinitialize-instance[Only in Common Lisp]
shared-initialize[Only in Common Lisp]
update-instance-for-different-class[Only in Common Lisp]
update-instance-for-redefined-class[Only in Common Lisp]
change-class[Only in Common Lisp]
slot-boundpcl_object cl_slot_boundp(cl_object instance, cl_object slot_name)
slot-exists-pcl_object cl_slot_exists_p(cl_object instance, cl_object slot_name)
slot-makunboundcl_object cl_slot_makunbound(cl_object instance, cl_object slot_name)
slot-missing[Only in Common Lisp]
slot-unbound[Only in Common Lisp]
slot-valuecl_object cl_slot_value(cl_object instance, cl_object slot_name)
method-qualifiers[Only in Common Lisp]
no-applicable-method[Only in Common Lisp]
no-next-method[Only in Common Lisp]
remove-method[Only in Common Lisp]
make-instance[Only in Common Lisp]
make-instances-obsolete[Only in Common Lisp]
make-load-form[Only in Common Lisp]
make-load-form-saving-slotscl_object cl_make_load_form_saving_slots(cl_narg narg, cl_object object, ...)
find-classcl_object cl_find_class(cl_narg narg, cl_object symbol, ...)
compute-applicable-methods[Only in Common Lisp]
find-method[Only in Common Lisp]
add-method[Only in Common Lisp]
initialize-instance[Only in Common Lisp]
class-name[Only in Common Lisp]
(setf class-name)[Only in Common Lisp]
class-ofcl_object cl_class_of(cl_object object)
unbound-slot-instance[Only in Common Lisp]

Next: , Previous: , Up: Standards   [Contents][Index]

3.6 Structures


Up: Structures   [Contents][Index]

3.6.1 C Reference

3.6.1.1 ANSI Dictionary

Common Lisp and C equivalence

Lisp symbolC function
copy-structurecl_object cl_copy_structure(cl_object structure)

Next: , Previous: , Up: Standards   [Contents][Index]

3.7 Conditions


Up: Conditions   [Contents][Index]

3.7.1 C Reference

Macro: ECL_HANDLER_CASE

C macro for handler-case

Synopsis

ECL_HANDLER_CASE_BEGIN(env,names) {

} ECL_HANDLER_CASE(n,condition) { {

} ECL_HANDLER_CASE_END;

Description

ECL_HANDLER_CASE_BEGIN runs a block of C code with a set of error handlers bound to the names given by the list names. The subsequent ECL_HANDLER_CASE statements specify what to do when the n-th type of conditions is found, where n is an integer denoting the position of the name in the list names.

When a condition is signaled, ECL scans the list of signal handlers, looking for matches based on typep. If the match with the highest precedence belongs to the list names, ECL will perform a non-local transfer of control to the appropriate ECL_HANDLER_CASE, passing it a condition object as unique argument.

The following example shows how to establish a handler for ERROR conditions. Note how the first value to ECL_HANDLER_CASE matches the position of the restart name in the list:

cl_object error = ecl_make_symbol("ERROR","CL");
ECL_HANDLER_CASE_BEGIN(the_env, ecl_list1(error)) {
   /* This form is evaluated with bound handlers */
   output = cl_eval(1, form);
} ECL_HANDLER_CASE(1, condition) {
   /* This code is executed when an error happens */
   /* We just return the error that took place */
   output = condition;
} ECL_HANDLER_CASE_END;
Macro: ECL_RESTART_CASE

C macro for restart-case

Synopsis

ECL_RESTART_CASE_BEGIN(env,names) {

} ECL_RESTART_CASE(n,args) { {

} ECL_RESTART_CASE_END;

Description

ECL_RESTART_CASE_BEGIN runs a block of C code with a set of restarts bound to the names given by the list names. The subsequent ECL_RESTART_CASE statements specify what to do when the n-th restart is invoked, where n is an integer denoting the position of the name in the list names.

When the restart is invoked, it can receive any number of arguments, which are grouped in a list and stored in a new variable created with the name args.

The following example shows how to establish an ABORT and a USE-VALUE restart. Note how the first value to ECL_RESTART_CASE matches the position of the restart name in the list:

cl_object abort = ecl_make_symbol("ABORT","CL");
cl_object use_value = ecl_make_symbol("USE-VALUE","CL");
ECL_RESTART_CASE_BEGIN(the_env, cl_list(2, abort, use_value)) {
   /* This form is evaluated with bound restarts */
   output = cl_eval(1, form);
} ECL_RESTART_CASE(1, args) {
   /* This code is executed when the 1st restart (ABORT) is invoked */
   output = Cnil;
} ECL_RESTART_CASE(2, args) {
   /* This code is executed when the 2nd restart (ABORT) is invoked */
   output = ECL_CAR(args);
} ECL_RESTART_CASE_END;

3.7.1.1 Conditions C dictionary

Common Lisp and C equivalence

Lisp symbolC function
abortcl_object cl_abort(cl_narg narg, ...)
breakcl_object cl_break()
cell-error-name[Only in Common Lisp]
cerrorcl_object cl_cerror(cl_narg narg, cl_object continue_format_control, cl_object datum, ...)
compute-restartscl_object cl_compute_restarts(cl_narg narg, ...)
continuecl_object cl_continue(cl_narg narg, ...)
errorcl_object cl_error(cl_narg narg, cl_object datum, ...)
find-restartcl_object cl_find_restart(cl_narg narg, cl_object identifier, ...)
handler-caseECL_HANDLER_CASE macro
invalid-method-error[Only in Common Lisp]
invoke-debuggercl_object cl_invoke_debugger(cl_object condition)
invoke-restartcl_object cl_invoke_restart(cl_narg narg, cl_object restart, ...)
invoke-restart-interactivelycl_object cl_invoke_restart_interactively(cl_object restart)
make-conditioncl_object cl_make_condition(cl_narg narg, cl_object type)
method-combination-error[Only in Common Lisp]
muffle-warningcl_object cl_muffle_warning(cl_narg narg, ...)
restart-name[Only in Common Lisp]
restart-caseECL_RESTART_CASE macro
signalcl_object cl_signal(cl_narg narg, cl_object datum, ...)
simple-condition-format-control[Only in Common Lisp]
simple-condition-format-arguments[Only in Common Lisp]
store-valuecl_object cl_store_value(cl_narg narg, ...)
use-valuecl_object cl_use_value(cl_narg narg, ...)
warncl_object cl_warn(cl_narg narg, cl_object datum, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.8 Symbols

There are no implementation-specific limits on the size or content of symbol names. It is however not allowed to write on the strings which have been passed to #'make-symbol or returned from #'symbol-name.

3.8.1 C Reference

Function: cl_object ecl_make_keyword (char * name);

Find a lisp keyword

Description

Many Lisp functions take keyword arguments. When invoking a function with keyword arguments we need keywords, which are a kind of symbols that live in the KEYWORD package. This function does the task of finding or creating those keywords from C strings.

Example

The following example converts a section of a string to uppercase characters:

cl_object start = ecl_make_keyword("START");
cl_object end = ecl_make_keyword("END");
...
sup = cl_string_upcase(4, s, start, ecl_make_fixnum(2),
                       end, ecl_make_fixnum(6));
Function: cl_object ecl_make_symbol (const char * name, const char * package_name);

Find a lisp symbol

Description

This function finds or create a symbol in the given package. First of all, it tries to find the package named by package_name. If it does not exist, an error is signaled. Then, a symbol with the suppled name is searched in the given package. If the symbol exists, it is returned. If it does not exist, using INTERN.

3.8.1.1 ANSI Dictionary

Common Lisp and C equivalence

Lisp symbolC function
boundpcl_object cl_boundp(cl_object symbolp)
copy-symbolcl_object cl_copy_symbol(cl_narg narg, cl_object symbol, ...)
getcl_object cl_get(cl_object symbol, cl_object indicator)
gensymcl_object cl_gensym(cl_narg narg, ...)
gentempcl_object cl_gentemp(cl_narg narg, ...)
keywordpcl_object cl_keywordp(cl_object object)
make-symbolcl_object cl_make_symbol(cl_object name)
makunboundcl_object cl_makunbound(cl_object makunbound)
rempropcl_object cl_remprop(cl_object symbol, cl_object indicator)
setcl_object cl_set(cl_object symbol, cl_object value)
symbolpcl_object cl_symbolp(cl_object object)
symbol-functioncl_object cl_symbol_function(cl_object symbol)
symbol-namecl_object cl_symbol_name(cl_object symbol)
symbol-packagecl_object cl_symbol_package(cl_object symbol)
symbol-plistcl_object cl_symbol_plist(cl_object symbol)
symbol-valuecl_object cl_symbol_value(cl_object symbol)

Next: , Previous: , Up: Standards   [Contents][Index]

3.9 Packages

In Table 3.4 we list all packages available in ECL. The nicknames are aliases for a package. Thus, system:symbol may be written as sys:symbol or si:symbol. The module field explains which library provides what package. For instance, the ASDF is obtained when loading the ASDF library with (require 'asdf).

NameNicknameIn moduleDescription
COMMON-LISPCL, LISPECL coreMain Common Lisp package.
CLOSMOPECL coreSymbols from the AMOP.
EXT ECL coreECL extensions to the language & library.
SYSTEMSI, SYSECL coreFunctions and variables internal to the implementation. Never to be used.
FFIECL coreForeign function interface
CMPCCMPThe compiler
SB-BSD-SOCKETS SOCKETSSockets library compatible with SBCL’s
SB-RTRT, REGRESSION-TESTRTTest units (customized for ECL)
ASDF ASDFSystem definition file with ECL customizations.

Table 3.4: ECL packages


Next: , Previous: , Up: Standards   [Contents][Index]

3.10 Numbers


Next: , Up: Numbers   [Contents][Index]

3.10.1 Numeric types

ECL supports all of the Common Lisp numeric tower, which is shown in Table 3.5. The details, however, depend both on the platform on which ECL runs and on the configuration which was chosen when building ECL.

TypeDescription
fixnumSigned integer with a number of bits given by ext:fixnum-bits, fit in a machine word.
bignumArbitrary size integers, only limited by amount of memory.
ratioArbitrary size rational number, made up of two integers.
short-floatEquivalent to single-float.
single-float32-bits IEEE floating point number.
double-float64-bits IEEE floating point number.
long-floatEither equivalent to double-float, or a 96/128 bits IEEE floating point number (long double in C/C++).
rationalAn alias for (or integer ratio)
floatAn alias for (or single-float double-float short-float long-float)
realAn alias for (or real integer float)
complexComplex number made of two real numbers of the above mentioned types.

Table 3.5: Numeric types in ECL

In general, the size of a FIXNUM is determined by the word size of a machine, which ranges from 32 to 64 bits. Integers larger than this are implemented using the GNU Multiprecision library. Rationals are implemented using two integers, without caring whether they are fixnum or not. Floating point numbers include at least the two IEEE types of 32 and 64 bits respectively. In machines where it is supported, it is possible to associate the lisp LONG-FLOAT with the machine type long double whose size ranges from 96 to 128 bits, and which are a bit slower.


Next: , Previous: , Up: Numbers   [Contents][Index]

3.10.2 Random-States

ECL relies internally on a 32-bit Mersenne-Twister random number generator, using a relatively large buffer to precompute about 5000 pseud-random bytes. This implies also that random states can be printed readably and also read, using the #$ macro. There is no provision to create random states from user arrays, though. Random state is printed unreadably by default.

The #$ macro can be used to initialize the generator with a random seed (an integer), an array of random bytes (mainly used for reading back printed random-state) and another random-state (syntactic sugar for copying the random-state).


Previous: , Up: Numbers   [Contents][Index]

3.10.3 C Reference


Next: , Up: Numbers - C Reference   [Contents][Index]

3.10.3.1 Number C types

Numeric C types understood by ECL

Type names

cl_fixnumfixnum
cl_index(integer 0 most-positive-fixnum)
floatshort-float, single-float
doubledouble-float
long double (*)long-floatECL_LONG_FLOAT:long-float
uint8_t(unsigned-byte 8)
int8_t(signed-byte 8)
uint16_t(unsigned-byte 16)ecl_uint16_t:uint16-t
int16_t(signed-byte 16)ecl_int16_t:int16-t
uint32_t(unsigned-byte 32)ecl_uint32_t:uint32-t
int32_t(signed-byte 32)ecl_int32_t:int32-t
uint64_t(unsigned-byte 64)ecl_uint64_t:uint64-t
int64_t(signed-byte 64)ecl_int64_t:int64-t
short(integer ffi:c-short-min ffi:c-short-max)
unsigned short(integer 0 ffi:c-ushort-max)
int(integer ffi:c-int-min ffi:c-int-max)
unsigned int(integer 0 ffi:c-uint-max)
long(integer ffi:c-long-min ffi:c-long-max)
unsigned long(integer 0 ffi:c-long-max)
long long(integer ffi:c-long-long-min ffi:c-long-long-max)ecl_long_long_t:long-long
unsigned long long(integer 0 ffi:c-ulong-long-max)ecl_ulong_long_t:ulong-long

Description

The table above shows the relation between C types and the equivalent Common Lisp types. All types are standard C99 types, except for two. First, cl_fixnum is the smallest signed integer that can fit a fixnum. Second, cl_index is the smallest unsigned integer that fits a fixnum and is typically the unsigned counterpart of cl_fixnum.

(*) The long double does not exist on all platforms. When it exists, the macro ECL_LONG_DOUBLE will be defined, and long-double will be equivalent to it.

Many other types might also not exist on all platforms. This includes not only long long and unsigned long long, but also some of the C99 integer types. There are two ways to detect which integer types are available in your system:


Next: , Previous: , Up: Numbers - C Reference   [Contents][Index]

3.10.3.2 Number constructors

Creating Lisp types from C numbers

Functions

Function: cl_object ecl_make_fixnum (cl_fixnum n)
Function: cl_object ecl_make_integer (cl_fixnum n)
Function: cl_object ecl_make_unsigned_integer (cl_index n)
Function: cl_object ecl_make_single_float (float n)
Function: cl_object ecl_make_double_float (double n)
Function: cl_object ecl_make_long_float (long double n)
Function: cl_object ecl_make_uint8_t (uint8_t n)
Function: cl_object ecl_make_int8_t (int8_t n)
Function: cl_object ecl_make_uint16_t (uint16_t n)
Function: cl_object ecl_make_int16_t (int16_t n)
Function: cl_object ecl_make_uint32_t (uint32_t n)
Function: cl_object ecl_make_int32_t (int32_t n)
Function: cl_object ecl_make_uint64_t (uint64_t n)
Function: cl_object ecl_make_int64_t (int64_t n)
Function: cl_object ecl_make_short_t (short n)
Function: cl_object ecl_make_ushort_t (unsigned short n)
Function: cl_object ecl_make_int (int n)
Function: cl_object ecl_make_uint (unsigned int n)
Function: cl_object ecl_make_long (long n)
Function: cl_object ecl_make_ulong (unsigned long n)
Function: cl_object ecl_make_long_long (long long n)
Function: cl_object ecl_make_ulong_long (unsigned long long n)
Function: cl_object ecl_make_ratio (cl_object numerator, cl_object denominator)
Function: cl_object ecl_make_complex (cl_object real, cl_object imag)

Description

These functions create a Lisp object from the corresponding C number. If the number is an integer type, the result will always be an integer, which may be a bignum. If on the other hand the C number is a float, double or long double, the result will be a float.

There is some redundancy in the list of functions that convert from cl_fixnum and cl_index to lisp. On the one hand, ecl_make_fixnum() always creates a fixnum, dropping bits if necessary. On the other hand, ecl_make_integer and ecl_make_unsigned_integer faithfully converts to a Lisp integer, which may a bignum.

Note also that some of the constructors do not use C numbers. This is the case of ecl_make_ratio and ecl_make_complex, because they are composite Lisp types.

These functions or macros signal no errors.


Next: , Previous: , Up: Numbers - C Reference   [Contents][Index]

3.10.3.3 Number accessors

Unchecked conversion from Lisp types to C numbers

Functions

Function: cl_fixnum ecl_fixnum (cl_object n)
Function: float ecl_fixnum (cl_object n)
Function: double ecl_fixnum (cl_object n)
Function: long double ecl_fixnum (cl_object n)

Description

These functions and macros extract a C number from a Lisp object. They do not check the type of the Lisp object as they typically just access directly the value from a C structure.


Next: , Previous: , Up: Numbers - C Reference   [Contents][Index]

3.10.3.4 Number coercion

Checked conversion from Lisp types to C numbers

Functions

Function: cl_fixnum ecl_to_fixnum (cl_object n);
Function: cl_index ecl_to_unsigned_integer (cl_object n);
Function: flaot ecl_to_float (cl_object n);
Function: double ecl_to_double (cl_object n);
Function: long double ecl_to_long_double (cl_object n);
Function: float ecl_to_float (cl_object n);
Function: int8_t ecl_to_uint8_t (cl_object n);
Function: int8_t ecl_to_int8_t (cl_object n);
Function: uint16_t ecl_to_uint16_t (cl_object n);
Function: int16_t ecl_to_int16_t (cl_object n);
Function: uint32_t ecl_to_uint32_t (cl_object n);
Function: int32_t ecl_to_int32_t (cl_object n);
Function: uint64_t ecl_to_uint64_t (cl_object n);
Function: int64_t ecl_to_int64_t (cl_object n);
Function: short ecl_to_short (cl_object n);
Function: unsigned short ecl_to_ushort (cl_object n);
Function: int ecl_to_int (cl_object n);
Function: unsigned int ecl_to_uint (cl_object n);
Function: long ecl_to_long (cl_object n);
Function: unsigned long ecl_to_ulong (cl_object n);
Function: long long ecl_to_long_long (cl_object n);
Function: unsigned long long ecl_to_ulong_long (cl_object n);

Description

These functions and macros convert a Lisp object to the corresponding C number type. The conversion is done through a coercion process which may signal an error if the argument does not fit the expected type.


Previous: , Up: Numbers - C Reference   [Contents][Index]

3.10.3.5 Numbers C dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
=cl_object cl_E()
/=cl_object cl_NE()
<cl_object cl_L()
>cl_object cl_G()
<=cl_object cl_LE()
>=cl_object cl_GE()
maxcl_object cl_max(cl_narg narg, ...)
mincl_object cl_min(cl_narg narg, ...)
minuspcl_object cl_minusp(cl_object real)
pluspcl_object cl_plusp(cl_object real)
zeropcl_object cl_zerop(cl_object number)
floorcl_object cl_floor(cl_narg narg, cl_object number, ...)
ffloorcl_object cl_ffloor(cl_narg narg, cl_object number, ...)
ceilingcl_object cl_ceiling(cl_narg narg, cl_object number, ...)
fceilingcl_object cl_fceiling(cl_narg narg, cl_object number, ...)
truncatecl_object cl_truncate(cl_narg narg, cl_object number, ...)
ftruncatecl_object cl_ftruncate(cl_narg narg, cl_object number, ...)
roundcl_object cl_round(cl_narg narg, cl_object number, ...)
froundcl_object cl_fround(cl_narg narg, cl_object number, ...)
sincl_object cl_sin(cl_object radians)
coscl_object cl_cos(cl_object radians)
tancl_object cl_tan(cl_object radians)
asincl_object cl_asin(cl_object number)
acoscl_object cl_acos(cl_object number)
atancl_object cl_atan(cl_object number)
sinhcl_object cl_sinh(cl_object number)
coshcl_object cl_cosh(cl_object number)
tanhcl_object cl_tanh(cl_object number)
asinhcl_object cl_asinh(cl_object number)
acoshcl_object cl_acosh(cl_object number)
atanhcl_object cl_atanh(cl_object number)
*cl_object cl_X(cl_narg narg, ...)
+cl_object cl_P(cl_narg narg, ...)
-cl_object cl_M(cl_narg narg, cl_object number, ...)
/cl_object cl_N(cl_narg narg, cl_object number, ...)
1+cl_object cl_1P()
1-cl_object cl_1M()
abscl_object cl_abs(cl_object number)
evenpcl_object cl_evenp(cl_object integer)
oddpcl_object cl_oddp(cl_object integer)
expcl_object cl_exp(cl_object number)
exptcl_object cl_expt(cl_object base, cl_object power)
gcdcl_object cl_gcd(cl_narg narg, ...)
lcmcl_object cl_lcm(cl_narg narg, ...)
logcl_object cl_log(cl_narg narg, cl_object number, ...)
modcl_object cl_mod(cl_object number, cl_object divisor)
remcl_object cl_rem(cl_object number, cl_object divisor)
signumcl_object cl_signum(cl_object number)
sqrtcl_object cl_sqrt(cl_object number)
isqrtcl_object cl_isqrt(cl_object natural)
make-random-statecl_object cl_make_random_state(cl_narg narg, ...)
randomcl_object cl_random(cl_narg narg, cl_object limit, ...)
random-state-pcl_object cl_random_state_p(cl_object object)
numberpcl_object cl_numberp(cl_object object)
ciscl_object cl_cis(cl_object radians)
complexcl_object cl_complex(cl_narg narg, cl_object realpart, ...)
complexpcl_object cl_complexp(cl_object object)
conjugatecl_object cl_conjugate(cl_object number)
phasecl_object cl_phase(cl_object number)
realpartcl_object cl_realpart(cl_object number)
imagpartcl_object cl_imagpart(cl_object number)
upgraded-complex-part-typecl_object cl_upgraded_complex_part_type(cl_narg narg, cl_object typespec, ...)
realpcl_object cl_realp(cl_object object)
numeratorcl_object cl_numerator(cl_object rational)
denominatorcl_object cl_denominator(cl_object rational)
rationalcl_object cl_rational(cl_object number)
rationalizecl_object cl_rationalize(cl_object number)
rationalpcl_object cl_rationalp(cl_object object)
ashcl_object cl_ash(cl_object integer, cl_object count)
integer-lengthcl_object cl_integer_length(cl_object integer)
integerpcl_object cl_integerp(cl_object object)
parse-integercl_object cl_parse_integer(cl_narg narg, cl_object string, ...)
boolecl_object cl_boole(cl_object op, cl_object integer1, cl_object integer2)
logandcl_object cl_logand(cl_narg narg, ...)
logandc1cl_object cl_logandc1(cl_object integer1, cl_object integer2)
logandc2cl_object cl_logandc2(cl_object integer1, cl_object integer2)
logeqvcl_object cl_logeqv(cl_narg narg, ...)
logiorcl_object cl_logior(cl_narg narg, ...)
lognandcl_object cl_lognand(cl_object integer1, cl_object integer2)
lognorcl_object cl_lognor(cl_object integer1, cl_object integer2)
lognotcl_object cl_lognot(cl_object integer)
logorc1cl_object cl_logorc1(cl_object integer1, cl_object integer2)
logorc2cl_object cl_logorc2(cl_object integer1, cl_object integer2)
logxorcl_object cl_logxor(cl_narg narg, ...)
logbitpcl_object cl_logbitp(cl_object index, cl_object integer)
logcountcl_object cl_logcount(cl_object integer)
logtestcl_object cl_logtest(cl_object integer1, cl_object integer2)
bytecl_object cl_byte(cl_object size, cl_object position)
bytes-sizecl_object cl_byte_size(cl_object bytespec)
byte-positioncl_object cl_byte_position(cl_object bytespec)
deposit-fieldcl_object cl_deposit_field(cl_object newbyte, cl_object bytespec, cl_object integer)
dpbcl_object cl_dpb(cl_object newbyte, cl_object bytespec, cl_object integer)
ldbcl_object cl_ldb(cl_object bytespec, cl_object integer)
ldb-testcl_object cl_ldb_test(cl_object bytespec, cl_object integer)
mask-fieldcl_object cl_mask_field(cl_object bytespec, cl_object integer)
decode-floatcl_object cl_decode_float(cl_object float)
scale-floatcl_object cl_scale_float(cl_object float, cl_object integer)
float-radixcl_object cl_float_radix(cl_object float)
float-signcl_object cl_float_sign(cl_narg narg, cl_object float1, ...)
float-digitscl_object cl_float_digits(cl_object float)
float-precisioncl_object cl_float_precision(cl_object float)
integer-decode-floatcl_object cl_integer_decode_float(cl_object float)
floatcl_object cl_float(cl_narg narg, cl_object number)
floatpcl_object cl_floatp(cl_object object)
arithmetic-error-operands[Only in Common Lisp]
arithmetic-error-operation[Only in Common Lisp]

Next: , Previous: , Up: Standards   [Contents][Index]

3.11 Characters

ECL is fully ANSI Common-Lisp compliant in all aspects of the character data type, with the following peculiarities.


Next: , Up: Characters   [Contents][Index]

3.11.1 Unicode vs. POSIX locale

There are two ways of building ECL: with C or with Unicode character codes. These build modes are accessed using the --disable-unicode and --enable-unicode configuration options, the last one being the default.

When using C characters we are actually relying on the char type of the C language, using the C library functions for tasks such as character conversions, comparison, etc. In this case characters are typically 8 bit wide and the character order and collation are determines by the current POSIX or C locale. This is not very accurate, leaves out many languages and character encodings but it is sufficient for small applications that do not need multilingual support.

When no option is specified ECL builds with support for a larger character set, the Unicode 6.0 standard. This uses 24 bit large character codes, also known as codepoints, with a large database of character properties which include their nature (alphanumeric, numeric, etc), their case, their collation properties, whether they are standalone or composing characters, etc.

3.11.1.1 Character types

If ECL is compiled without Unicode support, all characters are implemented using 8-bit codes and the type extended-char is empty. If compiled with Unicode support, characters are implemented using 24 bits and the extended-char type covers characters above code 255.

TypeWith UnicodeWithout Unicode
standard-char#\Newline,32-126#\Newline,32-126
base-char0-2550-255
extended-char-256-16777215

3.11.1.2 Character names

All characters have a name. For non-printing characters between 0 and 32, and for 127 we use the ordinary ASCII names. Characters above 127 are printed and read using hexadecimal Unicode notation, with a U followed by 24 bit hexadecimal number, as in U0126.

CharacterCode
#\Null0
#\Ack1
#\Bell7
#\Backspace8
#\Tab9
#\Newline10
#\Linefeed10
#\Page12
#\Esc27
#\Escape27
#\Space32
#\Rubout127
#\U0080128

Table 3.6

Note that #\Linefeed is synonymous with #\Newline and thus is a member of standard-char.


Next: , Previous: , Up: Characters   [Contents][Index]

3.11.2 #\Newline characters

Internally, ECL represents the #\Newline character by a single code. However, when using external formats, ECL may parse character pairs as a single #\Newline, and viceversa, use multiple characters to represent a single #\Newline.


Previous: , Up: Characters   [Contents][Index]

3.11.3 C Reference

3.11.3.1 C types

C character types

Type names

ecl_charactercharacter
ecl_base_charbase-char

Description

ECL defines two C types to hold its characters: ecl_base_char and ecl_character.

For your code to be portable and future proof, use both types to really express what you intend to do.

3.11.3.2 Constructors

Creating and extracting characters from Lisp objects

Functions

Function: cl_object ECL_CODE_CHAR (ecl_character code);
Function: ecl_character ECL_CHAR_CODE (cl_object o);
Function: cl_object ecl_char_code (ecl_character code);
Function: ecl_base_char ecl_base_char_code (cl_object o);

Description

These functions and macros convert back and forth from C character types to Lisp. The macros ECL_CHAR_CODE and ECL_CODE_CHAR perform this coercion without checking the arguments. The functions ecl_char_code and ecl_base_char_code, on the other hand, verify that the argument has the right type and signal an error otherwise.

3.11.3.3 Predicates

C predicates for Lisp characters

Functions

Function: bool ecl_base_char_p (ecl_character c);
Function: bool ecl_alpha_char_p (ecl_character c);
Function: bool ecl_alphanumeric_p (ecl_character c);
Function: bool ecl_graphic_char_p (ecl_character c);
Function: bool ecl_digit_p (ecl_character c);
Function: bool ecl_standard_char_p (ecl_character c);

Description

These functions are equivalent to their Lisp equivalents but return C booleans.

3.11.3.4 Character case

C functions related to the character case

Functions

Function: bool ecl_upper_case_p (ecl_character c);
Function: bool ecl_lower_case_p (ecl_character c);
Function: bool ecl_both_case_p (ecl_character c);
Function: ecl_character ecl_char_downcase (ecl_character c);
Function: ecl_character ecl_char_upcase (ecl_character c);

Description

These functions check or change the case of a character. Note that in a Unicode context, the output of these functions might not be accurate (for instance when the uppercase character has two or more codepoints).

3.11.3.5 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
char=cl_object cl_charE(cl_narg narg, ...)
char/=cl_object cl_charNE(cl_narg narg, ...)
char<cl_object cl_charL(cl_narg narg, ...)
char>cl_object cl_charG(cl_narg narg, ...)
char<=cl_object cl_charLE(cl_narg narg, ...)
char>=cl_object cl_charGE(cl_narg narg, ...)
char-equalcl_object cl_char_equal(cl_narg narg, ...)
char-not-equalcl_object cl_char_not_equal(cl_narg narg, ...)
char-lesspcl_object cl_char_lessp(cl_narg narg, ...)
char-greaterpcl_object cl_char_greaterp(cl_narg narg, ...)
char-not-greaterpcl_object cl_char_not_greaterp(cl_narg narg, ...)
char-not-lesspcl_object cl_char_not_lessp(cl_narg narg, ...)
charactercl_object cl_character(cl_object char_designator)
characterpcl_object cl_characterp(cl_object object)
alpha-char-pcl_object cl_alpha_char_p(cl_object character)
alphanumericpcl_object cl_alphanumericp(cl_object character)
digit-charcl_object cl_digit_char(cl_narg narg, cl_object character, ...)
digit-char-pcl_object cl_digit_char_p(cl_narg narg, cl_object character, ...)
graphic-char-pcl_object cl_graphic_char_p(cl_object character)
standard-char-pcl_object cl_standard_char_p(cl_object character)
char_upcasecl_object cl_char_upcase(cl_object character)
char-downcasecl_object cl_char_downcase(cl_object character)
upper-case-pcl_object cl_upper_case_p(cl_object character)
lower-case-pcl_object cl_lower_case_p(cl_object character)
both-case-pcl_object cl_both_case_p(cl_object character)
char-codecl_object cl_char_code(cl_object character)
char-intcl_object cl_char_int(cl_object character)
code-charcl_object cl_code_char(cl_object code)
char-namecl_object cl_char_name(cl_object character)
name-charcl_object cl_name_char(cl_object name)

Next: , Previous: , Up: Standards   [Contents][Index]

3.12 Conses


Up: Conses   [Contents][Index]

3.12.1 C Reference

3.12.1.1 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
conscl_object cl_cons(cl_object car, cl_object cdr)
conspcl_object cl_consp(cl_object object)
atomcl_object cl_atom(cl_object object)
rplacacl_object cl_rplaca(cl_object cons, cl_object car)
rplacdcl_object cl_rplacd(cl_object cons, cl_object cdr)
carcl_object cl_car(cl_object cons)
cdrcl_object cl_cdr(cl_object cons)
caarcl_object cl_caar(cl_object cons)
cdarcl_object cl_cdar(cl_object cons)
cadrcl_object cl_cadr(cl_object cons)
cddrcl_object cl_cddr(cl_object cons)
caaarcl_object cl_caaar(cl_object cons)
cdaarcl_object cl_cdaar(cl_object cons)
cadarcl_object cl_cadar(cl_object cons)
cddarcl_object cl_cddar(cl_object cons)
caadrcl_object cl_caadr(cl_object cons)
cdadrcl_object cl_cdadr(cl_object cons)
caddrcl_object cl_caddr(cl_object cons)
cdddrcl_object cl_cdddr(cl_object cons)
caaaarcl_object cl_caaaar(cl_object cons)
cdaaarcl_object cl_cdaaar(cl_object cons)
cadaarcl_object cl_cadaar(cl_object cons)
cddaarcl_object cl_cddaar(cl_object cons)
caadarcl_object cl_caadar(cl_object cons)
cdadarcl_object cl_cdadar(cl_object cons)
caddarcl_object cl_caddar(cl_object cons)
cdddarcl_object cl_cdddar(cl_object cons)
caaadrcl_object cl_caaadr(cl_object cons)
cdaadrcl_object cl_cdaadr(cl_object cons)
cadadrcl_object cl_cadadr(cl_object cons)
cddadrcl_object cl_cddadr(cl_object cons)
caaddrcl_object cl_caaddr(cl_object cons)
cdaddrcl_object cl_cdaddr(cl_object cons)
cadddrcl_object cl_cadddr(cl_object cons)
cddddrcl_object cl_cddddr(cl_object cons)
copy-treecl_object cl_copy_tree(cl_object tree)
subliscl_object cl_sublis(cl_narg narg, cl_object alist, cl_object tree, ...)
nsubliscl_object cl_sublis(cl_narg narg, cl_object alist, cl_object tree, ...)
substcl_object cl_subst(cl_narg narg, cl_object new, cl_object old, cl_object tree, ...)
subst-ifcl_object cl_subst_if(cl_narg narg, cl_object new, cl_object predicate, cl_object tree, ...)
subst-if-notcl_object cl_subst_if_not(cl_narg narg, cl_object new, cl_object predicate, cl_object tree, ...)
nsubstcl_object cl_nsubst(cl_narg narg, cl_object new, cl_object old, cl_object tree, ...)
nsubst-ifcl_object cl_nsubst_if(cl_narg narg, cl_object new, cl_object predicate, cl_object tree, ...)
nsubst-if-notcl_object cl_nsubst_if_not(cl_narg narg, cl_object new, cl_object predicate, cl_object tree, ...)
tree-equalcl_object cl_tree_equal(cl_narg narg, cl_object tree1, cl_object tree2, ...)
copy-listcl_object cl_copy_list(cl_object list)
listcl_object cl_list(cl_narg narg, ...)
list*cl_object cl_listA(cl_narg narg, ...)
list-lengthcl_object cl_list_length(cl_object list)
listpcl_object cl_listp(cl_object object)
make-listcl_object cl_make_list(cl_narg narg, cl_object size, ...)
firstcl_object cl_first(cl_object list)
secondcl_object cl_second(cl_object list)
thirdcl_object cl_third(cl_object list)
fourthcl_object cl_fourth(cl_object list)
fifthcl_object cl_fifth(cl_object list)
sixthcl_object cl_sixth(cl_object list)
seventhcl_object cl_seventh(cl_object list)
eighthcl_object cl_eighth(cl_object list)
ninthcl_object cl_ninth(cl_object list)
tenthcl_object cl_tenth(cl_object list)
nthcl_object cl_nth(cl_object n, cl_object list)
endpcl_object cl_endp(cl_object list)
nullcl_object cl_null(cl_object object)
nconccl_object cl_nconc(cl_narg narg, ...)
appendcl_object cl_append(cl_narg narg, ...)
revappendcl_object cl_revappend(cl_object list, cl_object tail)
nreconccl_object cl_nreconc(cl_object list, cl_object tail)
butlastcl_object cl_butlast(cl_narg narg, cl_object list, ...)
nbutlastcl_object cl_nbutlast(cl_narg narg, cl_object list, ...)
lastcl_object cl_last(cl_narg narg, cl_object list, ...)
ldiffcl_object cl_ldiff(cl_object list, cl_object object)
tailpcl_object cl_tailp(cl_object object, cl_object list)
nthcdrcl_object cl_nthcdr(cl_object n, cl_object list)
restcl_object cl_rest(cl_object list)
membercl_object cl_member(cl_narg narg, cl_object member, cl_object list, ....)
member-ifcl_object cl_member_if(cl_narg narg, cl_object predicate, cl_object list, ....)
member-if-notcl_object cl_member_if_not(cl_narg narg, cl_object predicate, cl_object list, ....)
mapccl_object cl_mapc(cl_narg narg, cl_object function, ...)
mapcarcl_object cl_mapcar(cl_narg narg, cl_object function, ...)
mapcancl_object cl_mapcan(cl_narg narg, cl_object function, ...)
maplcl_object cl_mapl(cl_narg narg, cl_object function, ...)
maplistcl_object cl_maplist(cl_narg narg, cl_object function, ...)
mapconcl_object cl_mapcon(cl_narg narg, cl_object function, ...)
aconscl_object cl_acons(cl_object key, cl_object datum, cl_object alist)
assoccl_object cl_assoc(cl_narg narg, cl_object item, cl_object alist, ...)
assoc-ifcl_object cl_assoc_if(cl_narg narg, cl_object predicate, cl_object alist, ...)
assoc-if-notcl_object cl_assoc_if_not(cl_narg narg, cl_object predicate, cl_object alist, ...)
copy-alistcl_object cl_copy_alist(cl_object alist)
pairliscl_object cl_pairlis(cl_narg narg, cl_object keys, cl_object data, ...)
rassoccl_object cl_rassoc(cl_narg narg, cl_object item, cl_object alist, ...)
rassoc-ifcl_object cl_rassoc_if(cl_narg narg, cl_object predicate, cl_object alist, ...)
rassoc-if-notcl_object cl_rassoc_if_not(cl_narg narg, cl_object predicate, cl_object alist, ...)
get-propertiescl_object cl_get_properties(cl_object plist, cl_object indicator_list)
getfcl_object cl_getf(cl_narg narg, cl_object plist, cl_object indicator, ...)
intersectioncl_object cl_intersection(cl_narg narg, cl_object list1, cl_object list2, ...)
nintersectioncl_object cl_nintersection(cl_narg narg, cl_object list1, cl_object list2, ...)
adjoincl_object cl_adjoin(cl_narg narg, cl_object item, cl_object list, ...)
set-differencecl_object cl_set_difference(cl_narg narg, cl_object list1, cl_object list2, ...)
nset-differencecl_object cl_nset_difference(cl_narg narg, cl_object list1, cl_object list2, ...)
set-exclusive-orcl_object cl_set_exclusive_or(cl_narg narg, cl_object list1, cl_object list2, ...)
nset-exclusive-orcl_object cl_nset_exclusive_or(cl_narg narg, cl_object list1, cl_object list2, ...)
subsetpcl_object cl_subsetp(cl_narg narg, cl_object list1, cl_object list2, ...)
unioncl_object cl_union(cl_narg narg, cl_object list1, cl_object list2)
nunioncl_object cl_nunion(cl_narg narg, cl_object list1, cl_object list2)

Next: , Previous: , Up: Standards   [Contents][Index]

3.13 Arrays


Next: , Up: Arrays   [Contents][Index]

3.13.1 Array limits

ECL arrays can have up to 64 dimensions. Common-Lisp constants related to arrays have the following values in ECL.

ConstantValue
array-rank-limit64
array-dimension-limitmost-positive-fixnum
array-total-size-limitarray-dimension-limit

Next: , Previous: , Up: Arrays   [Contents][Index]

3.13.2 Specializations

When the elements of an array are declared to have some precise type, such as a small or large integer, a character or a floating point number, ECL has means to store those elements in a more compact form, known as a specialized array. The list of types for which ECL specializes arrays is platform dependent, but is summarized in the following table, together with the C type which is used internally and the expected size.

Specialized typeElement C typeSize
bit-1 bit
characterunsigned char or uint32_tDepends on character range
base-charunsigned char
fixnumcl_fixnumMachine word (32 or 64 bits)
(signed-byte 8)int8_t8 bits
(unsigned-byte 8)uint8_t8 bits
(signed-byte 16)int16_t16 bits
(unsigned-byte 16)uint16_t16 bits
(signed-byte 32)int32_t32 bits
(unsigned-byte 32)uint32_t32 bits
(signed-byte 64)int64_t64 bits
(unsigned-byte 64)uint64_t64 bits
single-float or short-floatfloat32-bits IEEE float
double-floatdouble64-bits IEEE float
long-floatlong doubleBetween 96 and 128 bits.
tcl_objectSize of a pointer.

Let us remark that some of these specialized types might not exist in your platform. This is detected using conditional reading and features (See Numbers).


Previous: , Up: Arrays   [Contents][Index]

3.13.3 C Reference

3.13.3.1 Types and constants

C types, limits and enumerations

Constants and types

Constant: ECL_ARRAY_RANK_LIMIT
Constant: ECL_ARRAY_DIMENSION_LIMIT
Constant: ECL_ARRAY_TOTAL_LIMIT
enum: cl_elttype {ecl_aet_object, ...}
Lisp or C typeEnumeration valueLisp or C typeEnumeration value
tecl_aet_object(unsigned-byte 1)ecl_aet_bit
cl_fixnumecl_aet_fixcl_indexecl_aet_index
(unsigned-byte 8)ecl_aet_b8(signed-byte 8)ecl_aet_i8
(unsigned-byte 16)ecl_aet_b16(signed-byte 16)ecl_aet_i16
(unsigned-byte 32)ecl_aet_b32(signed-byte 32)ecl_aet_i32
(unsigned-byte 64)ecl_aet_b64(signed-byte 64)ecl_aet_i64
ecl_characterecl_aet_checl_base_charecl_aet_bc
single-floatecl_aet_sfdouble-floatecl_aet_df

Description

This list contains the constants that limit the rank of an array (ECL_ARRAY_RANK_LIMIT), the maximum size of each dimension (ECL_ARRAY_DIMENSION_LIMIT) and the maximum number of elements in an array (ECL_ARRAY_TOTAL_LIMIT).

ECL uses also internally a set of constants to describe the different specialized arrays. The constants form up the enumeration type cl_elttype. They are listed in the table above, which associates enumeration values with the corresponding Common Lisp element type.

3.13.3.2 ecl_aet_to_symbol, ecl_symbol_to_aet

To and from element types

Functions

Function: cl_object ecl_aet_to_symbol (cl_elttype param)
Function: cl_elttype ecl_symbol_to_aet (cl_object type)

Description

ecl_aet_to_symbol returns the Lisp type associated to the elements of that specialized array class. ecl_symbol_to_aet does the converse, computing the C constant that is associated to a Lisp elment type.

The functions may signal an error if any of the arguments is an invalid C or Lisp type.

3.13.3.3 Constructors

Creating array and vectors

Functions

Function: cl_object ecl_alloc_simple_vector( cl_elttype element_type, cl_index length);
Function: cl_object si_make_vector( cl_object element_type, cl_object length, cl_object adjustablep, cl_object fill_pointerp, cl_object displaced_to, cl_object displacement);
Function: cl_object si_make_array( cl_object element_type, cl_object dimensions, cl_object adjustablep, cl_object fill_pointerp, cl_object displaced_to, cl_object displacement);

Description

The function ecl_alloc_simple_vector is the simplest constructor, creating a simple vector (i.e. non-adjustable and without a fill pointer), of the given size, preallocating the memory for the array data. The first argument, element_type, is a C constant that represents a valid array element type (See cl_elttype).

The function si_make_vector does the same job but allows creating an array with fill pointer, which is adjustable or displaced to another array.

Finally, the function si_make_array does a similar job to si_make_function but its second argument, dimension, can be a list of dimensions, to create a multidimensional array.

Examples

Create one-dimensional base-string with room for 11 characters:

cl_object s = ecl_alloc_simple_vector(ecl_aet_bc, 11);

Create a one-dimensional array with a fill pointer

cl_object type = ecl_make_symbol("BYTE8","EXT");
cl_object a = si_make_vector(ecl_make_fixnum(16), type, Cnil, /* adjustable */
                             ecl_make_fixnum(0) /* fill-pointer */,
                             Cnil /* displaced_to */,
                             Cnil /* displacement */);

An alternative formulation

cl_object type = ecl_make_symbol("BYTE8","EXT");
cl_object a = si_make_array(ecl_make_fixnum(16), type, Cnil, /* adjustable */
                            ecl_make_fixnum(0) /* fill-pointer */,
                            Cnil /* displaced_to */,
                            Cnil /* displacement */);

Create a 2-by-3 two-dimensional array, specialized for an integer type:

cl_object dims = cl_list(2, ecl_make_fixnum(2), ecl_make_fixnum(3));
cl_object type = ecl_make_symbol("BYTE8","EXT");
cl_object a = si_make_array(dims, type, Cnil, /* adjustable */
                            Cnil /* fill-pointer */,
                            Cnil /* displaced_to */,
                            Cnil /* displacement */);

3.13.3.4 Accessors

Reading and writing array elements

Functions

Function: cl_object ecl_aref (cl_object array, cl_index row_major_index);
Function: cl_object ecl_aset (cl_object array, cl_index row_major_index, cl_object new_value);
Function: cl_object ecl_aref1 (cl_object vector, cl_index row_major_index);
Function: cl_object ecl_aset1 (cl_object vector, cl_index row_major_index, cl_object new_value);

Description

ecl_aref accesses an array using the supplied row_major_index, checking the array bounds and returning a Lisp object for the value at that position. ecl_aset does the converse, storing a Lisp value at the given row_major_index.

The first argument to ecl_aref or ecl_aset is an array of any number of dimensions. For an array of rank N and dimensions d1, d2 ... up to dN, the row major index associated to the indices (i1,i2,...iN) is computed using the formula i1+d1*(i2+d3*(i3+...)).

ecl_aref1 and ecl_aset1 are specialized versions that only work with one-dimensional arrays or vectors. They verify that the first argument is indeed a vector.

All functions above check that the index does not exceed the array bounds, that the values match the array element type and that the argument is an array (or a vector). If these conditions are not met, a type error is signaled.

3.13.3.5 Array properties

Array size, fill pointer, etc.

Synopsis

Function: cl_elttype ecl_array_elttype (cl_object array);
Function: cl_index ecl_array_rank (cl_object array);
Function: cl_index ecl_array_dimension (cl_object array, cl_index index);

Description

These functions query various properties of the arrays. Some of them belong to the list of functions in the Common Lisp package, without any need for specialized versions. More precisely

3.13.3.6 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
make-arraycl_object cl_make_array(cl_narg narg, cl_object dimension...)
adjust-arraycl_object cl_adjust_array(cl_narg narg, cl_object array, cl_object dimensions, ...)
adjustable-array-pcl_object cl_adjustable_array_p(cl_object array)
arefcl_object cl_aref(cl_narg narg, cl_object array, ...)
array-dimensioncl_object cl_array_dimension(cl_object array, cl_object index)
array-dimensionscl_object cl_array_dimension(cl_object array)
array-element-typecl_object cl_array_element_type(cl_object array)
array-has-fill-pointer-pcl_object cl_array_has_fill_pointer_p(cl_object array)
array-displacementcl_object cl_array_displacement(cl_object array)
array-in-bounds-pcl_object cl_array_in_bounds_p(cl_narg narg, cl_object array, ...)
array-rankcl_object cl_array_rank(cl_object array)
array-row-major-indexcl_object cl_array_row_major_index(cl_narg narg, cl_object array, ...)
array-total-sizecl_object cl_array_total_size(cl_object array)
arraypcl_object cl_arrayp(cl_object array)
fill-pointercl_object cl_fill_pointer(cl_object array)
row-major-arefcl_object cl_row_major_aref(cl_object array, cl_object index)
upgraded-array-element-typecl_object cl_upgraded_array_element_type(cl_narg narg, cl_object typespec, ...)
simple-vector-pcl_object cl_simple_vector_p(cl_object object)
svrefcl_object cl_svref(cl_object simple_vector, cl_object index)
vectorcl_object cl_vector(cl_narg narg, ...)
vector-popcl_object cl_vector_pop(cl_object vector)
vector-pushcl_object cl_vector_push(cl_object new_element, cl_object vector)
vector-push-extendcl_object cl_vector_push_extend(cl_narg narg, cl_object new_element, cl_object vector, ...)
vectorpcl_object cl_vectorp(cl_object object)
bitcl_object cl_bit(cl_narg narg, cl_object bit_array, ...)
sbitcl_object cl_sbit(cl_narg narg, cl_object bit_array, ...)
bit-andcl_object cl_bit_and(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-andc1cl_object cl_bit_andc1(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-andc2cl_object cl_bit_andc2(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-eqvcl_object cl_bit_eqv(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-iorcl_object cl_bit_ior(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-nandcl_object cl_bit_nand(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-norcl_object cl_bit_nor(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-orc1cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-orc2cl_object cl_bit_orc1(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-xorcl_object cl_bit_xor(cl_narg narg, cl_object array1, cl_object array2, ...)
bit-notcl_object cl_bit_not(cl_narg narg, cl_object array, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.14 Strings


Next: , Up: Strings   [Contents][Index]

3.14.1 String types & Unicode

The ECL implementation of strings is ANSI Common-Lisp compliant. There are basically four string types as shown in Table 3.7. As explained in Characters, when Unicode support is disabled, character and base-character are the same type and the last two string types are equivalent to the first two.

AbbreviationExpanded typeRemarks
string(array character (*))8 or 32 bits per character, adjustable.
simple-string(simple-array character (*))8 or 32 bits per character, not adjustable nor displaced.
base-string(array base-char (*))8 bits per character, adjustable.
simple-base-string(simple-array base-char (*))8 bits per character, not adjustable nor displaced.

Table 3.7: Common Lisp string types

It is important to remember that strings with unicode characters can only be printed readably when the external format supports those characters. If this is not the case, ECL will signal a serious-condition. This condition will abort your program if not properly handled.


Previous: , Up: Strings   [Contents][Index]

3.14.2 C reference

3.14.2.1 Base string constructors

Building strings of C data

Functions

Function: cl_object ecl_alloc_adjustable_base_string (cl_index length);
Function: cl_object ecl_alloc_adjustable_simple_string (cl_index length);
Function: cl_object ecl_make_simple_base_string (ecl_base_char* data, cl_index length);
Function: cl_object ecl_make_constant_base_string (ecl_base_char* data, cl_index length);

Description

These are different ways to create a base string, which is a string that holds a small subset of characters, the base-char, with codes ranging from 0 to 255.

ecl_alloc_simple_base_string creates an empty string with that much space for characters and a fixed lenght. The string does not have a fill pointer and cannot be resized, and the initial data is unspecified

ecl_alloc_adjustable_base_string is similar to the previous function, but creates an adjustable string with a fill pointer. This means that the lenght of the string can be changed and the string itself can be resized to accomodate more data.

The other constructors create strings but use some preexisting data. ecl_make_simple_base_string creates a string copying the data that the user supplies, and using freshly allocated memory. ecl_make_constant_base_string on the other hand, does not allocate memory, but simply uses the supplied pointer as buffer for the string. This last function should be used with care, ensuring that the supplied buffer is not deallocated.

3.14.2.2 String accessors

Reading and writing characters into a string

Functions

Function: ecl_character ecl_char (cl_object string, cl_index ndx);
Function: ecl_character ecl_char_set (cl_object string, cl_index ndx, ecl_character c);

Description

Access to string information should be done using these two functions. The first one implements the equivalent of the CHAR function from Common Lisp, returning the character that is at position ndx in the string s.

The counterpart of the previous function is ecl_char_set, which implements (SETF CHAR) and stores character c at the position ndx in the given string.

Both functions check the type of their arguments and verify that the indices do not exceed the string boundaries. Otherwise they signal a serious-condition.

3.14.2.3 Strings C dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
simple-string-pcl_object cl_simple_string_p(cl_object string)
charcl_object cl_char(cl_object string, cl_object index)
scharcl_object cl_schar(cl_object string, cl_object index)
stringcl_object cl_string(cl_object x)
string-upcasecl_object cl_string_upcase(cl_narg narg, cl_obejct string, ...)
string-downcasecl_object cl_string_downcase(cl_narg narg, cl_obejct string, ...)
string-capitalizecl_object cl_string_capitalize(cl_narg narg, cl_obejct string, ...)
nstring-upcasecl_object cl_nstring_upcase(cl_narg narg, cl_obejct string, ...)
nstring-downcasecl_object cl_nstring_downcase(cl_narg narg, cl_obejct string, ...)
nstring-capitalizecl_object cl_nstring_capitalize(cl_narg narg, cl_obejct string, ...)
string-trimcl_object cl_string_trim(cl_object character_bag, cl_object string)
string-left-trimcl_object cl_string_left_trim(cl_object character_bag, cl_object string)
string-right-trimcl_object cl_string_right_trim(cl_object character_bag, cl_object string)
stringcl_object cl_string(cl_narg narg, cl_object string1, cl_object string2, ...)
string=cl_object cl_stringE(cl_narg narg, cl_object string1, cl_object string2, ...)
string/=cl_object cl_stringNE(cl_narg narg, cl_object string1, cl_object string2, ...)
string<cl_object cl_stringL(cl_narg narg, cl_object string1, cl_object string2, ...)
string>cl_object cl_stringG(cl_narg narg, cl_object string1, cl_object string2, ...)
string<=cl_object cl_stringLE(cl_narg narg, cl_object string1, cl_object string2, ...)
string>=cl_object cl_stringGE(cl_narg narg, cl_object string1, cl_object string2, ...)
string-equalcl_object cl_string_equal(cl_narg narg, cl_object string1, cl_object string2, ...)
string-not-equalcl_object cl_string_not_equal(cl_narg narg, cl_object string1, cl_object string2, ...)
string-lesspcl_object cl_string_lessp(cl_narg narg, cl_object string1, cl_object string2, ...)
string-greaterpcl_object cl_string_greaterp(cl_narg narg, cl_object string1, cl_object string2, ...)
string-not-greaterpcl_object cl_string_not_greaterp(cl_narg narg, cl_object string1, cl_object string2, ...)
string-not-lesspcl_object cl_string_not_lessp(cl_narg narg, cl_object string1, cl_object string2, ...)
stringpcl_object cl_stringp(cl_object x)
make-stringcl_object cl_make_string(cl_narg narg, cl_object size, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.15 Sequences


Up: Sequences   [Contents][Index]

3.15.1 C Reference

3.15.1.1 Sequences C dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
concatenatecl_object cl_concatenate(cl_narg narg, cl_object result_type, ...)
copy-seqcl_object cl_copy_seq(cl_object sequence)
countcl_object cl_count(cl_narg narg, cl_object item, cl_object sequence, ...)
count-ifcl_object cl_count_if(cl_narg narg, cl_object predicate, cl_object sequence, ...)
count-if-notcl_object cl_count_if_not(cl_narg narg, cl_object predicate, cl_object sequence, ...)
deletecl_object cl_delete(cl_narg narg, cl_object newitem, cl_object sequence, ...)
delete-ifcl_object cl_delete_if(cl_narg narg, cl_object newitem, cl_object test, cl_object sequence, ...)
delete-if-notcl_object cl_delete_if_not(cl_narg narg, cl_object newitem, cl_object test, cl_object sequence, ...)
delete-duplicatescl_object cl_delete_duplicates(cl_narg narg, cl_object sequence)
eltcl_object cl_elt(cl_object sequence, cl_object index)
fillcl_object cl_fill(cl_narg narg, cl_object sequence, cl_object item, ...)
findcl_object cl_find(cl_narg narg, cl_object item, cl_object sequence, ...)
find-ifcl_object cl_find_if(cl_narg narg, cl_object predicate, cl_object sequence, ...)
find-if-notcl_object cl_find_if_not(cl_narg narg, cl_object predicate, cl_object sequence, ...)
make-sequencecl_object cl_make_sequence(cl_narg narg, cl_object result_type, cl_object size, ...)
mapcl_object cl_map(cl_narg narg, cl_object result_type, cl_object function)
map-intocl_object cl_map_into(cl_narg narg, cl_object result_sequence, cl_object function, ...)
mergecl_object cl_merge(cl_narg narg, cl_object result_type, cl_object sequence1, cl_object sequence2, ...)
mismatchcl_object cl_mismatch(cl_narg narg, cl_object sequence1, cl_object sequence2)
nreversecl_object cl_nreverse(cl_object sequence)
nsubstitutecl_object cl_nsubstitute(cl_narg narg, cl_object newitem, cl_object olditem, cl_object sequence, ...)
nsubstitute-ifcl_object cl_nsubstitute_if(cl_narg narg, cl_object newitem, cl_object predicate, cl_object sequence, ...)
nsubstitute-if-notcl_object cl_nsubstitute_if_not(cl_narg narg, cl_object newitem, cl_object predicate, cl_object sequence, ...)
positioncl_object cl_position(cl_narg narg, cl_object item, cl_object sequence, ...)
position-ifcl_object cl_pos_pif(cl_narg narg, cl_object predicate, cl_object sequence, ...)
position-if-notcl_object cl_pos_pif_not(cl_narg narg, cl_object predicate, cl_object sequence, ...)
reducecl_object cl_reduce(cl_narg narg, cl_object function, cl_object sequence, ...)
removecl_object cl_remove(cl_narg narg, cl_object newitem, cl_object sequence, ...)
remove-ifcl_object cl_remove_if(cl_narg narg, cl_object newitem, cl_object test, cl_object sequence, ...)
remove-if-notcl_object cl_remove_if_not(cl_narg narg, cl_object newitem, cl_object test, cl_object sequence, ...)
remove-duplicatescl_object cl_remove_duplicates(cl_narg narg, cl_object sequence)
replacecl_object cl_replace(cl_narg narg, cl_object sequence1, cl_object sequence2)
reversecl_object cl_reverse(cl_object sequence)
searchcl_object cl_search(cl_narg narg, cl_object sequence1, cl_object sequence2)
sortcl_object cl_sort(cl_narg narg, cl_object sequence, cl_object predicate, ...)
stable-sortcl_object cl_stable_sort(cl_narg narg, cl_object sequence, cl_object predicate, ...)
subseqcl_object cl_subseq(cl_narg narg, cl_object sequence, cl_object start)
substitutecl_object cl_substitute(cl_narg narg, cl_object newitem, cl_object olditem, cl_object sequence, ...)
substitute-ifcl_object cl_substitute_if(cl_narg narg, cl_object newitem, cl_object predicate, cl_object sequence, ...)
substitute-if-notcl_object cl_substitute_if_not(cl_narg narg, cl_object newitem, cl_object predicate, cl_object sequence, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.16 Hash tables

Weakness in hash tables

Weak hash tables allow the garbage collector to reclaim some of the entries if they are not strongly referenced elsewhere. ECL supports four kinds of weakness in hash tables: :key, :value, key-and-value and key-or-value.

To make hash table weak, programmer has to provide :weakness keyword argument to cl:make-hash-table with the desired kind of weakness value (NIL means that the hash table has only strong references).

For more information see Weak References - Data Types and Implementation by Bruno Haible.

ext: hash-table-weakness ht

Returns type of the hash table weakness. Possible return values are: :key, :value, :key-and-value, :key-or-value or NIL.

Thread-safe hash tables

By default ECL doesn’t protect hash tables from simultaneous access for performance reasons. Read and write access may is synchronized when synchronized keyword argument to make-hash-table is T - (make-hash-table :synchronized t).

ext: hash-table-synchronized-p ht

Predicate answering whenever hash table is synchronized or not.

Hash tables serialization

ext: hash-table-content ht

Returns freshly consed list of pairs (key . val) being contents of the hash table.

ext: hash-table-fill ht values

Fills ht with values being list of (key . val). Hash table may have some content already, but conflicting keys will be overwritten.

Example

CL-USER> (defparameter *ht*
           (make-hash-table :synchronized t
                            :weakness :key-or-value))
*HT*

CL-USER> (ext:hash-table-weakness *ht*)
:KEY-OR-VALUE

CL-USER> (ext:hash-table-synchronized-p *ht*)
T

CL-USER> (ext:hash-table-fill *ht* '((:foo 3) (:bar 4) (:quux 5)))
#<hash-table 000055b1229e0b40>

CL-USER> (ext:hash-table-content *ht*)
((#<weak-pointer 000055b121866350> . #<weak-pointer 000055b121866320>)
 (#<weak-pointer 000055b121866370> . #<weak-pointer 000055b121866360>)
 (#<weak-pointer 000055b121866390> . #<weak-pointer 000055b121866380>))

Up: Hash tables   [Contents][Index]

3.16.1 C Reference

3.16.1.1 Hash tables C dictionary

Common Lisp and C equivalence

Lisp symbolC function
clrhashcl_object cl_clrhash(cl_object hash_table)
gethashcl_object cl_gethash(cl_narg narg, cl_object key, cl_object hash_table, ...)
hash-table-countcl_object cl_hash_table_count(cl_object hash_table)
hash-table-pcl_object cl_hash_table_p(cl_object hash_table)
hash-table-rehash-sizecl_object cl_hash_table_rehash_size(cl_object hash_table)
hash-table-rehash-thresholdcl_object cl_hash_table_rehash_thresholdy(cl_object hash_table)
hash-table-sizecl_object cl_hash_table_size(cl_object hash_table)
hash-table-testcl_object cl_hash_table_test(cl_object hash_table)
make-hash-tablecl_object cl_make_hash_table(cl_narg narg, ...)
maphashcl_object cl_maphash(cl_object function, cl_object hash_table)
remhashcl_object cl_remhash(cl_object key, cl_object hash_table)
sxhashcl_object cl_sxhash(cl_object object)

Next: , Previous: , Up: Standards   [Contents][Index]

3.17 Filenames


Next: , Up: Filenames   [Contents][Index]

3.17.1 Syntax

A pathname in the file system of Common-Lisp consists of six elements: host, device, directory, name, type and version. Pathnames are read and printed using the #P reader macro followed by the namestring. A namestring is a string which represents a pathname. The syntax of namestrings for logical pathnames is well explained in the ANSI [see ANSI] and it can be roughly summarized as follows:

[hostname:][;][directory-item;]0 or more[name][.type[.version]]
  hostname = word
  directory-item = wildcard-word
  type, name = wildcard-word without dots

Here, wildcard-word is a sequence of any character excluding #\Null and dots. word is like a wildcard-word but asterisks are excluded.

The way ECL parses a namestring is by first looking for the hostname component in the previous template. If it is found and it corresponds to a previously defined logical hostname, it assumes that the namestring corresponds to a logical pathname. If hostname is not found or it is not a logical hostname, then ECL tries the physical pathname syntax

[device:][[//hostname]/][directory-item/]0 or more[name][.type]
  device, hostname = word
  directory-item = wildcard-word
  type = wildcard-word without dots
  name = [.]wildcard-word

If this syntax also fails, then the namestring is not a valid pathname string and a parse-error will be signalled.

It is important to remark that in ECL, all physical namestrings result into pathnames with a version equal to :NEWEST. Pathnames which are not logical and have any other version (i. e. NIL or a number), cannot be printed readably, but can produce a valid namestring which results of ignoring the version.

Finally, an important rule applies to physical namestrings: if a namestring contains one or more periods ‘.’, the last period separates the namestring into the file name and the filetype. However, a namestring with a single leading period results in a name with a period in it. This is for compatibility with Unix filenames such as .bashrc, where the leading period indicates that the file is hidden.

The previous rule has in important consequence, because it means that if you want to create a pathname without a name, you have to do it explicitely. In other words, ".*" is equivalent to (MAKE-PATHNAME :NAME ".*" :TYPE NIL), while (MAKE-PATHNAME :NAME NIL :TYPE :WILD) creates a pathname whose type is a wildcard.

The following table illustrates how the physical pathnames work with practical examples.

NamestringNameTypeDirectoryDevice
"foo.lsp""foo""lsp"NILNIL
".bashrc"".bashrc"NILNILNIL
".ecl.lsp"".ecl""lsp"NILNIL
"foo.*""foo":WILDNILNIL
"*.*":WILD:WILDNILNIL
"ecl/build/bare.lsp""bare""lsp"(:relative "ecl" "build")NIL
"ecl/build/"NILNIL(:relative "ecl" "build")NIL
"../../ecl/build/"NILNIL(:relative :up :up "ecl" "build")NIL
"/etc/"NILNIL(:absolute "etc")NIL
"C:/etc/"NILNIL(:absolute "etc")"C"
".*"".*"NILNILNIL
#.(MAKE-PATHNAME :TYPE "*")NIL:WILDNILNIL

Table 3.8: Examples of physical namestrings


Next: , Previous: , Up: Filenames   [Contents][Index]

3.17.2 Wild pathnames and matching

ECL accepts four kind of wildcards in pathnames.

The matching rules in Common Lisp and ECL are simple but have some unintuitive consequences when compared to Unix/DOS rules. The most important one is that directories must always end with a trailing slash /, as in #p"/my/home/directory/". Second to that, NIL values can only be matched by NIL and :WILD. Hence, "*" can only match files without file type. For some examples see Files - Dictionary.


Previous: , Up: Filenames   [Contents][Index]

3.17.3 C Reference

3.17.3.1 Filenames C dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
directory-namestringcl_object cl_directory_namestring(cl_object pathname)
enough-namestringcl_object cl_enough_namestring(cl_narg narg, cl_object pathname, ...)
file-namestringcl_object cl_file_namestring(cl_object pathname)
host-namestringcl_object cl_host_namestring(cl_object pathname)
load-logical-pathname-translationscl_object cl_load_logical_pathname_translations(cl_object host)
logical-pathname-translationscl_object cl_logical_pathname_translations(cl_object host)
logical-pathnamecl_object cl_logical_pathname(cl_object pathspec)
make-pathnamecl_object cl_make_pathname(cl_narg narg, ...)
merge-pathnamescl_object cl_merge_pathnames(cl_narg narg, cl_object pathname,...)
namestringcl_object cl_namestring(cl_object pathname)
parse-namestringcl_object cl_parse_namestring(cl_narg narg, cl_object thing, ...)
pathnamecl_object cl_pathname(cl_object pathspec)
pathname-devicecl_object cl_pathname_device(cl_narg narg, cl_object pathname, ...)
pathname-directorycl_object cl_pathname_directory(cl_narg narg, cl_object pathname, ...)
pathname-hostcl_object cl_pathname_host(cl_narg narg, cl_object pathname, ...)
pathname-match-pcl_object cl_pathname_match_p(cl_object pathname, cl_object wildcard)
pathname-namecl_object cl_pathname_name(cl_narg narg, cl_object pathname, ...)
pathname-typecl_object cl_pathname_type(cl_narg narg, cl_object pathname, ...)
pathname-versioncl_object cl_pathname_version(cl_object pathname)
pathnamepcl_object cl_pathnamep(cl_object object)
translate-logical-pathnamecl_object cl_translate_logical_pathname(cl_narg narg, cl_object pathname, ...)
translate-pathnamecl_object cl_translate_pathname(cl_narg narg, cl_object source, cl_object from_wildcard, cl_object to_wildcard, ...)
wild-pathname-pcl_object cl_wild_pathname_p(cl_narg narg, cl_object pathname, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.18 Files


Next: , Up: Files   [Contents][Index]

3.18.1 Dictionary

3.18.1.1 DIRECTORY

This function does not have any additional arguments other than the ones described in ANSI [see ANSI]. To list files and directories, it follows the rules for matching pathnames described in Filenames - Wild pathnames and matching. In short, you have the following practical examples:

ArgumentMeaning
"/home/jlr/*.*"List all files in directory /home/jlr/ Note that it lists only files, not directories!
"/home/jlr/*"Same as before, but only files without type.
"/home/jlr/*/"List all directories contained in /home/jlr/. Nested directories are not navigated.
"/home/jlr/**/*.*"List all files in all directories contained in /home/jlr/, recursively. Nested directories are navigated.

Table 3.9: Examples of using DIRECTORY


Previous: , Up: Files   [Contents][Index]

3.18.2 C Reference

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
delete-filecl_object cl_delete_file(cl_object filespec)
directorycl_object cl_directory(cl_narg narg, cl_object pathspec, ...)
ensure-directories-existcl_object cl_ensure_directories_exist(cl_narg narg, cl_object pathspec, ...)
file-authorcl_object cl_file_author(cl_object pathspec)
file-error-pathname[Only in Common Lisp]
file-write-datecl_object cl_file_write_date(cl_object pathspec)
probe-filecl_object cl_probe_file(cl_object pathspec)
rename-filecl_object cl_rename_file(cl_object filespec, cl_object new_name)
truenamecl_object cl_truename(cl_object filespec)

Next: , Previous: , Up: Standards   [Contents][Index]

3.19 Streams


Next: , Up: Streams   [Contents][Index]

3.19.1 ANSI Streams


Next: , Up: Streams - ANSI Streams   [Contents][Index]

3.19.1.1 Supported types

ECL implements all stream types described in ANSI [see ANSI]. Additionally, when configured with option --enable-clos-streams, ECL includes a version of Gray streams where any object that implements the appropiate methods (stream-input-p, stream-read-char, etc) is a valid argument for the functions that expect streams, such as read, print, etc.


Next: , Previous: , Up: Streams - ANSI Streams   [Contents][Index]

3.19.1.2 Element types

ECL distinguishes between two kinds of streams: character streams and byte streams. Character streams only accept and produce characters, written or read one by one, with write-char or read-char, or in chunks, with write-sequence or any of the Lisp printer functions. Character operations are conditioned by the external format, as described in Streams - External formats.

ANSI Common Lisp also supports binary streams. Here input and output is performed in chunks of bits. Binary streams are created with the function open passing as argument a subtype of integer and the implementation is free to round up that integer type to the closest size it supports. In particular ECL rounds up the size to a multiple of a byte. For example, the form (open "foo.bin" :direction :output :element-type '(unsigned-byte 13)), will open the file foo.bin for writing, using 16-bit words as the element type.


Previous: , Up: Streams - ANSI Streams   [Contents][Index]

3.19.1.3 External formats

An external format is an encoding for characters that maps character codes to a sequence of bytes, in a one-to-one or one-to-many fashion. External formats are also known as "character encodings" in the programming world and are an essential ingredient to be able to read and write text in different languages and alphabets.

ECL has one of the most complete supports for external formats, covering all of the usual codepages from the Windows and Unix world, up to the more recent UTF-8, UCS-2 and UCS-4 formats, all of them with big and small endian variants, and considering different encodings for the newline character.

However, the set of supported external formats depends on the size of the space of character codes. When ECL is built with Unicode support (the default option), it can represent all known characters from all known codepages, and thus all external formats are supported. However, when ECL is built with the restricted character set, it can only use one codepage (the one provided by the C library), with a few variants for the representation of end-of-line characters.

In ECL, an external format designator is defined recursively as either a symbol or a list of symbols. The grammar is as follows

external-format-designator := 
   symbol |
   ( {symbol}+ )

and the table of known symbols is shown below. Note how some symbols (:cr, :little-endian, etc.) just modify other external formats.

SymbolsCodepage or encodingUnicode required
:cr#\Newline is Carriage ReturnNo
:crlf#\Newline is Carriage Return followed by LinefeedNo
:lf#\Newline is LinefeedNo
:little-endianModify UCS to use little endian encoding.No
:big-endianModify UCS to use big endian encoding.No
:utf-8 :utf8Unicode UTF-8Yes
:ucs-2 :ucs2 :utf-16 :utf16 :unicodeUCS-2 encoding with BOM.Yes
:ucs-2le :ucs2le :utf-16leUCS-2 with big-endian encodingYes
:ucs-2be :ucs2be :utf-16beUCS-2 with big-endian encodingYes
:ucs-4 :ucs4 :utf-32 :utf32UCS-4 encoding with BOM.Yes
:ucs-4le :ucs4le :utf-32leUCS-4 with big-endian encodingYes
:ucs-4be :ucs4be :utf-32beUCS-4 with big-endian encodingYes
:iso-8859-1 :iso8859-1 :latin-1 :cp819 :ibm819Latin-1 encodingYes
:iso-8859-2 :iso8859-2 :latin-2 :latin2Latin-2 encodingYes
:iso-8859-3 :iso8859-3 :latin-3 :latin3Latin-3 encodingYes
:iso-8859-4 :iso8859-4 :latin-4 :latin4Latin-4 encodingYes
:iso-8859-5 :cyrillicLatin-5 encodingYes
:iso-8859-6 :arabic :asmo-708 :ecma-114Latin-6 encodingYes
:iso-8859-7 :greek8 :greek :ecma-118Greek encodingYes
:iso-8859-8 :hebrewHebrew encodingYes
:iso-8859-9 :latin-5 :latin5Latin-5 encodingYes
:iso-8859-10 :iso8859-10 :latin-6 :latin6Latin-6 encodingYes
:iso-8859-13 :iso8859-13 :latin-7 :latin7Latin-7 encodingYes
:iso-8859-14 :iso8859-14 :latin-8 :latin8Latin-8 encodingYes
:iso-8859-15 :iso8859-15 :latin-9 :latin9Latin-7 encodingYes
:dos-cp437 :ibm-437IBM CP 437Yes
:dos-cp850 :ibm-850 :cp850Windows CP 850Yes
:dos-cp852 :ibm-852IBM CP 852Yes
:dos-cp855 :ibm-855IBM CP 855Yes
:dos-cp860 :ibm-860IBM CP 860Yes
:dos-cp861 :ibm-861IBM CP 861Yes
:dos-cp862 :ibm-862 :cp862Windows CP 862Yes
:dos-cp863 :ibm-863IBM CP 863Yes
:dos-cp864 :ibm-864IBM CP 864Yes
:dos-cp865 :ibm-865IBM CP 865Yes
:dos-cp866 :ibm-866 :cp866Windows CP 866Yes
:dos-cp869 :ibm-869IBM CP 869Yes
:windows-cp932 :windows-932 :cp932Windows CP 932Yes
:windows-cp936 :windows-936 :cp936Windows CP 936Yes
:windows-cp949 :windows-949 :cp949Windows CP 949Yes
:windows-cp950 :windows-950 :cp950Windows CP 950Yes
:windows-cp1250 :windows-1250 :ms-eeWindows CP 1250Yes
:windows-cp1251 :windows-1251 :ms-cyrlWindows CP 1251Yes
:windows-cp1252 :windows-1252 :ms-ansiWindows CP 1252Yes
:windows-cp1253 :windows-1253 :ms-greekWindows CP 1253Yes
:windows-cp1254 :windows-1254 :ms-turkWindows CP 1254Yes
:windows-cp1255 :windows-1255 :ms-hebrWindows CP 1255Yes
:windows-cp1256 :windows-1256 :ms-arabWindows CP 1256Yes
:windows-cp1257 :windows-1257 :winbaltrimWindows CP 1257Yes
:windows-cp1258 :windows-1258Windows CP 1258Yes

Previous: , Up: Streams   [Contents][Index]

3.19.2 C Reference

3.19.2.1 Streams C dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
broadcast-stream-streamscl_object cl_broadcast_stream_streams(cl_object broadcast_stream)
clear-inputcl_object cl_clear_input(cl_narg narg, ...)
clear-outputcl_object cl_clear_outputt(cl_narg narg, ...)
closecl_object cl_close(cl_narg narg, cl_object stream, ...)
concatenated-stream-streamscl_object cl_concatenated_stream_streams(cl_object concatenated_stream)
echo-stream-input-streamcl_object cl_echo_stream_input_stream(cl_object echo_stream)
echo-stream-output-streamcl_object cl_echo_stream_output_stream(cl_object echo_stream)
file-lengthcl_object cl_file_length(cl_object stream)
file-positioncl_object cl_file_position(cl_object stream)
file-string-lengthcl_object cl_file_string_length(cl_object stream, cl_object object)
finish-outputcl_object cl_finish_outputt(cl_narg narg, ...)
force-outputcl_object cl_force_outputt(cl_narg narg, ...)
fresh-linecl_object cl_fresh_line(cl_narg narg, ...)
get-output-stream-stringcl_object cl_get_output_stream_string(cl_object string_output_stream)
input-stream-pcl_object cl_input_stream_p(cl_object stream)
interactive-stream-pcl_object cl_interactive_stream_p(cl_object stream)
listencl_object cl_listen(cl_narg narg, cl_object stream, ...)
make-broadcast-streamcl_object cl_make_broadcast_stream(cl_narg narg, ...)
make-concatenated-streamcl_object cl_make_concatenated_stream(cl_narg narg, ....)
make-echo-streamcl_object cl_make_echo_stream(cl_object input, cl_object output)
make-string-input-streamcl_object cl_make_string_input_stream(cl_narg narg, cl_object string, ...)
make-string-output-streamcl_object cl_make_string_output_stream(cl_narg narg, ...)
make-two-way-streamcl_object cl_make_two_way_stream(cl_object input, cl_object output)
make-synonym-streamcl_object cl_make_synonym_stream(cl_object symbol)
opencl_object cl_open(cl_narg narg, cl_object filespec, ...)
open-stream-pcl_object cl_open_stream_p(cl_object stream)
output-stream-pcl_object cl_output_stream_p(cl_object stream)
peek-charcl_object cl_peek_char(cl_narg narg, ...)
read-bytecl_object cl_read_byte(cl_narg narg, cl_object stream, ...)
read-charcl_object cl_read_char(cl_narg narg, ...)
read-char-no-hangcl_object cl_read_char_no_hang(cl_narg narg, ...)
read-linecl_object cl_read_line(cl_narg narg, ...)
read-sequencecl_object cl_read_sequence(cl_narg narg, cl_object sequence, cl_object stream)
stream-element-typecl_object cl_stream_element_type(cl_object stream)
stream-error-stream[Only in Common Lisp]
stream-external-formatcl_object cl_stream_external_format(cl_object stream)
streampcl_object cl_streamp(cl_object object)
synonym-stream-symbolcl_object cl_synonym_stream_symbol(cl_object synonym_stream)
terpricl_object cl_terpri(cl_narg narg, ...)
two-way-stream-input-streamcl_object cl_two_way_stream_input_stream(cl_object two_way_stream)
two-way-stream-output-streamcl_object cl_two_way_stream_output_stream(cl_object two_way_stream)
unread-charcl_object cl_unread_char(cl_narg narg, cl_object character, ...)
write-bytecl_object cl_write_byte(cl_object byte, cl_object stream)
write-charcl_object cl_write_char(cl_narg narg, cl_object character, ...)
write-linecl_object cl_write_line(cl_narg narg, cl_object string)
write-stringcl_object cl_write_string(cl_narg narg, cl_object string)
write-sequencecl_object cl_write_sequence(cl_narg narg, cl_object sequence, cl_object stream)
y-or-n-pcl_object cl_y_or_n_p(cl_narg narg, ...)
yes-or-no-pcl_object cl_yes_or_no_p(cl_narg narg, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.20 Printer

In all situations where the rules are well specified, ECL prints objects according to ANSI [see ANSI]. The specification leaves however a number of cases as implementation dependent behavior. The output of ECL in those cases is summarized in Table 3.10. Except for the types character and random-state, most of those examples regard non-standard written forms #<...> cannot be read back using read. These printed representations are just informative and should not be used to reconstruct or compare objects.

Lisp typeFormatRemarks
package#<package name>
random-state#<character array>
bitvector#<bit-vector unique-id>Only when *print-array* is false.
vector#<vector unique-id>Only when *print-array* is false.
array#<array unique-id>Only when *print-array* is false.
hash-table#<hash-table unique-id>
readtable#<readtable unique-id>
interpreted function#<bytecompiled-function name-or-id>Name is a symbol.
machine compiled function#<compiled-function name>Name is a symbol.
input-stream#<input stream "filename">An stream that reads from filename.
output-stream#<output stream "filename">An stream that writes to filename.
probe-stream#<probe stream "filename">
string-input-stream#<string-input stream from "string-piece">The string is the text left to be read.
string-output-stream#<string-output stream unique-id>
two-way-stream#<two-way stream unique-id>
echo-stream#<echo stream unique-id>
synonym-stream#<synonym stream to symbol>
broadcast-stream#<broadcast stream unique-id>
concatenated-stream#<concatenated stream unique-id>
closed-stream#<closed ...>The dots denote any of the above stream forms.

Table 3.10: Implementation-specific printed representation

3.20.1 C Reference

3.20.1.1 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
copy-pprint-dispatchcl_object cl_copy_pprint_dispatch(cl_narg narg, ...)
pprint-dispatchcl_object cl_pprint_dispatch(cl_narg narg, cl_object object, ...)
pprint-fillcl_object cl_pprint_fill(cl_narg narg, cl_object stream, cl_object object, ...)
pprint-linearcl_object cl_pprint_linear(cl_narg narg, cl_object stream, cl_object object, ...)
pprint-tabularcl_object cl_pprint_tabular(cl_narg narg, cl_object stream, cl_object object, ...)
pprint-indentcl_object cl_pprint_indent(cl_narg narg, cl_object relative_to, cl_object n, ...)
pprint-newlinecl_object cl_pprint_newline(cl_narg narg, cl_object kind, ...)
pprint-tabcl_object cl_pprint_tab(cl_narg narg, cl_object kind, cl_object colnum, cl_object colinc, ...)
print-object[Only in Common Lisp]
set-pprint-dispatchcl_object cl_set_pprint_dispatch(cl_narg narg, cl_object ype_spec, cl_object function, ...)
writecl_object cl_write(cl_narg narg, cl_object object, ...)
prin1cl_object cl_prin1(cl_narg narg, cl_object object, ...)
princcl_object cl_princ(cl_narg narg, cl_object object, ...)
printcl_object cl_print(cl_narg narg, cl_object object, ...)
pprintcl_object cl_pprint(cl_narg narg, cl_object object, ...)
write-to-stringcl_object cl_write_to_string(cl_narg narg, cl_object object, ...)
prin1-to-stringcl_object cl_prin1_to_string(cl_object object)
princ-to-stringcl_object cl_princ_to_string(cl_object object)
print-not-readable-object[Only in Common Lisp]
formatcl_object cl_format(cl_narg narg, cl_object string, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.21 Reader

3.21.1 C Reference

3.21.1.1 ANSI Dictionary

Common Lisp and C equivalence

Synopsis

Lisp symbolC function
copy-readtablecl_object cl_copy_readtable(cl_narg narg, ...)
make-dispatch-macro-charactercl_object cl_make_dispatch_macro_character(cl_narg narg, cl_object char, ...)
readcl_object cl_read(cl_narg narg, ...)
read-preerving-whitespacecl_object cl_read_preserving_whitespace(cl_narg narg, ...)
read-delimited-listcl_object cl_read_delimited_list(cl_narg narg, cl_object char, ...)
read-from-stringcl_object cl_read_from_string(cl_narg narg, cl_object string, ...)
readtable-casecl_object cl_readtable_case(cl_object readtable)
readtablepcl_object cl_readtablep(cl_object object)
get-dispatch-macro-charactercl_object cl_get_dispatch_macro_character(cl_narg narg, cl_object disp_char, cl_object sub_char, ...)
set-dispatch-macro-charactercl_object cl_set_dispatch_macro_character(cl_narg narg, cl_object disp_char, cl_object sub_char, cl_object function, ...)
get-macro-charactercl_object cl_get_macro_character(cl_narg narg, cl_object char, ...)
set-macro-charactercl_object cl_set_macro_character(cl_narg narg, cl_object char, cl_object function, ...)
set-syntax-from-charcl_object cl_set_syntax_from_char(cl_narg narg, cl_object to_char, cl_object from_char, ...)

Next: , Previous: , Up: Standards   [Contents][Index]

3.22 System construction

3.22.1 C Reference

3.22.1.1 ANSI Dictionary

Synopsis

Lisp symbolC function
compile-file[Only in Common Lisp]
compile-file-pathname[Only in Common Lisp]
loadcl_object cl_load()
providecl_object cl_provide(cl_object module_name)
requirecl_object cl_require(cl_narg narg, cl_object module_name, ...)

Previous: , Up: Standards   [Contents][Index]

3.23 Environment


Next: , Up: Environment   [Contents][Index]

3.23.1 Dictionary

Function: disassemble function-designator*

Display the assembly code of a function

Synopsis

function-designator

A symbol which is bound to a function in the global environment, or a lambda form

Description

As specified in ANSI [see ANSI] this function outputs the internal represention of a compiled function, or of a lambda form, as it would look after being compiled.

ECL only has a particular difference: it has two different compilers, one based on bytecodes and one based on the C language. The output will thus depend on the arguments and on which compiler is active at the moment in which this function is run.

Macro: trace function-name*

Follow the execution of functions

Synopsis

(trace function-name*)

function-name

{symbol|symbol[option form]*)}

symbol

A symbol which is bound to a function in the global environment. Not evaluated.

option

One of :BREAK, :BREAK-AFTER, :COND-BEFORE, :COND-AFTER, :COND, :PRINT, :PRINT-AFTER, :STEP

form

A lisp form evaluated in an special environment.

returns

List of symbols with traced functions.

Description

Causes one or more functions to be traced. Each function-name can be a symbol which is bound to a function, or a list containing that symbol plus additional options. If the function bound to that symbol is called, information about the argumetns and output of this function will be printed. Trace options will modify the amount of information and when it is printed.

Not that if the function is called from another function compiled in the same file, tracing might not be enabled. If this is the case, to enable tracing, recompile the caller with a notinline declaration for the called function.

trace returns a name list of those functions that were traced by the call to trace. If no function-name is given, trace simply returns a name list of all the currently traced functions.

Trace options cause the normal printout to be suppressed, or cause extra information to be printed. Each option is a pair of an option keyword and a value form. If an already traced function is traced again, any new options replace the old options and a warning might be printed. The lisp form accompanying the option is evaluated in an environment where sys::arglist is contains the list of arguments to the function.

The following options are defined:

:cond, :cond-before, :cond-after

If :cond-before is specified, then trace does nothing unless form evaluates to true at the time of the call. :cond-after is similar, but suppresses the initial printout, and is tested when the function returns. :cond tries both before and after.

:step

If form evaluates to true, the stepper is entered.

:break, :break-after

If specified, and form evaluates to true, then the debugger is invoked at the start of the function or at the end of the function according to the respective option.

:print, :print-after

In addition to the usual printout, the result of evaluating form is printed at the start of the function or at the end of the function, depending on the option. Multiple print options cause multiple values to be output, in the order in which they were introduced.


Previous: , Up: Environment   [Contents][Index]

3.23.2 C Reference

3.23.2.1 ANSI Dictionary

Common Lisp and C equivalence

Lisp symbolC function
decode-universal-timecl_object cl_decode_universal_time(cl_narg narg, cl_object universal_time, ...)
encode-universal-timecl_object cl_encode_universal_time(cl_narg narg, cl_object second, cl_object minute, cl_object hour, cl_object date, cl_object month, cl_object year, ...)
get-universal-timecl_object cl_get_universal_time(void)
get-decoded-timecl_object cl_get_decoded_time(void)
sleepcl_object cl_sleep(cl_object seconds)
aproposcl_object cl_apropos(cl_narg narg, cl_object string, ...)
apropos-listcl_object cl_apropos_list(cl_narg narg, cl_object string, ...)
describecl_object cl_describe(cl_narg narg, cl_object object, ...)
describe-object[Only in Common Lisp]
get-internal-real-timecl_object cl_get_internal_real_time()
get-internal-run-timecl_object cl_get_internal_run_time()
disassemble[Only in Common Lisp]
documentation[Only in Common Lisp]
roomcl_object cl_room(cl_narg narg, ...)
edcl_object cl_ed(cl_narg narg, ...)
inspectcl_object cl_inspect(cl_object object)
dribblecl_object cl_dribble(cl_narg narg, ...)
lisp-implementation-typecl_object cl_lisp_implementation_type(void)
lisp-implementation-versioncl_object cl_lisp_implementation_version(void)
short-site-namecl_object cl_short_site_name()
long-site-namecl_object cl_long_site_name()
machine-instancecl_object cl_machine_instance()
machine-typecl_object cl_machine_type()
machine-versioncl_object cl_machine_version()
software-typecl_object cl_software_type()
software-versioncl_object cl_software_version()
user-homedir-pathnamecl_object cl_user_homedir_pathname()

Previous: , Up: Environment   [Contents][Index]