This is guile.info, produced by makeinfo version 4.3 from guile.texi.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Guile Reference: (guile).     The Guile reference manual.
END-INFO-DIR-ENTRY

   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: guile.info,  Node: Scheme to C,  Prev: C to Scheme,  Up: Converting data between C and Scheme

Scheme to C
-----------

 - Function: int gh_scm2bool (SCM OBJ)
 - Function: unsigned long gh_scm2ulong (SCM OBJ)
 - Function: long gh_scm2long (SCM OBJ)
 - Function: double gh_scm2double (SCM OBJ)
 - Function: int gh_scm2char (SCM OBJ)
     These routines convert the Scheme object to the given C type.

 - Function: char *gh_scm2newstr (SCM STR, int *LENP)
     Given a Scheme string STR, return a pointer to a new copy of its
     contents, followed by a null byte.  If LENP is non-null, set
     `*LENP' to the string's length.

     This function uses malloc to obtain storage for the copy; the
     caller is responsible for freeing it.

     Note that Scheme strings may contain arbitrary data, including null
     characters.  This means that null termination is not a reliable
     way to determine the length of the returned value.  However, the
     function always copies the complete contents of STR, and sets *LENP
     to the true length of the string (when LENP is non-null).

 - Function: void gh_get_substr (SCM str, char *return_str, int *lenp)
     Copy LEN characters at START from the Scheme string SRC to memory
     at DST.  START is an index into SRC; zero means the beginning of
     the string.  DST has already been allocated by the caller.

     If START + LEN is off the end of SRC, signal an out-of-range error.

 - Function: char *gh_symbol2newstr (SCM SYM, int *LENP)
     Takes a Scheme symbol and returns a string of the form
     `"'symbol-name"'.  If LENP is non-null, the string's length is
     returned in `*LENP'.

     This function uses malloc to obtain storage for the returned
     string; the caller is responsible for freeing it.

 - Function: char *gh_scm2chars (SCM VECTOR, chars *RESULT)
 - Function: short *gh_scm2shorts (SCM VECTOR, short *RESULT)
 - Function: long *gh_scm2longs (SCM VECTOR, long *RESULT)
 - Function: float *gh_scm2floats (SCM VECTOR, float *RESULT)
 - Function: double *gh_scm2doubles (SCM VECTOR, double *RESULT)
     Copy the numbers in VECTOR to the array pointed to by RESULT and
     return it.  If RESULT is NULL, allocate a double array large
     enough.

     VECTOR can be an ordinary vector, a weak vector, or a signed or
     unsigned uniform vector of the same type as the result array.  For
     chars, VECTOR can be a string or substring.  For floats and
     doubles, VECTOR can contain a mix of inexact and integer values.

     If VECTOR is of unsigned type and contains values too large to fit
     in the signed destination array, those values will be wrapped
     around, that is, data will be copied as if the destination array
     was unsigned.


File: guile.info,  Node: Type predicates,  Next: Equality predicates,  Prev: Converting data between C and Scheme,  Up: GH

Type predicates
===============

   These C functions mirror Scheme's type predicate procedures with one
important difference.  The C routines return C boolean values (0 and 1)
instead of `SCM_BOOL_T' and `SCM_BOOL_F'.

   The Scheme notational convention of putting a `?' at the end of
predicate procedure names is mirrored in C by placing `_p' at the end
of the procedure.  For example, `(pair? ...)' maps to `gh_pair_p(...)'.

 - Function: int gh_boolean_p (SCM VAL)
     Returns 1 if VAL is a boolean, 0 otherwise.

 - Function: int gh_symbol_p (SCM VAL)
     Returns 1 if VAL is a symbol, 0 otherwise.

 - Function: int gh_char_p (SCM VAL)
     Returns 1 if VAL is a char, 0 otherwise.

 - Function: int gh_vector_p (SCM VAL)
     Returns 1 if VAL is a vector, 0 otherwise.

 - Function: int gh_pair_p (SCM VAL)
     Returns 1 if VAL is a pair, 0 otherwise.

 - Function: int gh_procedure_p (SCM VAL)
     Returns 1 if VAL is a procedure, 0 otherwise.

 - Function: int gh_list_p (SCM VAL)
     Returns 1 if VAL is a list, 0 otherwise.

 - Function: int gh_inexact_p (SCM VAL)
     Returns 1 if VAL is an inexact number, 0 otherwise.

 - Function: int gh_exact_p (SCM VAL)
     Returns 1 if VAL is an exact number, 0 otherwise.


File: guile.info,  Node: Equality predicates,  Next: Memory allocation and garbage collection,  Prev: Type predicates,  Up: GH

Equality predicates
===================

   These C functions mirror Scheme's equality predicate procedures with
one important difference.  The C routines return C boolean values (0
and 1) instead of `SCM_BOOL_T' and `SCM_BOOL_F'.

   The Scheme notational convention of putting a `?' at the end of
predicate procedure names is mirrored in C by placing `_p' at the end
of the procedure.  For example, `(equal? ...)' maps to
`gh_equal_p(...)'.

 - Function: int gh_eq_p (SCM x, SCM y)
     Returns 1 if X and Y are equal in the sense of Scheme's `eq?'
     predicate, 0 otherwise.

 - Function: int gh_eqv_p (SCM x, SCM y)
     Returns 1 if X and Y are equal in the sense of Scheme's `eqv?'
     predicate, 0 otherwise.

 - Function: int gh_equal_p (SCM x, SCM y)
     Returns 1 if X and Y are equal in the sense of Scheme's `equal?'
     predicate, 0 otherwise.

 - Function: int gh_string_equal_p (SCM S1, SCM S2)
     Returns 1 if the strings S1 and S2 are equal, 0 otherwise.

 - Function: int gh_null_p (SCM L)
     Returns 1 if L is an empty list or pair; 0 otherwise.


File: guile.info,  Node: Memory allocation and garbage collection,  Next: Calling Scheme procedures from C,  Prev: Equality predicates,  Up: GH

Memory allocation and garbage collection
========================================


File: guile.info,  Node: Calling Scheme procedures from C,  Next: Mixing gh and scm APIs,  Prev: Memory allocation and garbage collection,  Up: GH

Calling Scheme procedures from C
================================

   Many of the Scheme primitives are available in the `gh_' interface;
they take and return objects of type SCM, and one could basically use
them to write C code that mimics Scheme code.

   I will list these routines here without much explanation, since what
they do is the same as documented in *Note R5RS: (r5rs)Standard
procedures.  But I will point out that when a procedure takes a
variable number of arguments (such as `gh_list'), you should pass the
constant SCM_UNDEFINED from C to signify the end of the list.

 - Function: SCM gh_define (char *NAME, SCM VAL)
     Corresponds to the Scheme `(define name val)': it binds a value to
     the given name (which is a C string).  Returns the new object.

Pairs and lists
===============

 - Function: SCM gh_cons (SCM A, SCM B)
 - Function: SCM gh_list (SCM l0, SCM l1, ... , SCM_UNDEFINED)
     These correspond to the Scheme `(cons a b)' and `(list l0 l1 ...)'
     procedures.  Note that `gh_list()' is a C macro that invokes
     `scm_listify()'.

 - Function: SCM gh_car (SCM OBJ)
 - Function: SCM gh_cdr (SCM OBJ)
     ...

 - Function: SCM gh_c[ad][ad][ad][ad]r (SCM OBJ)
     These correspond to the Scheme `(caadar ls)' procedures etc ...

 - Function: SCM gh_set_car_x(SCM PAIR, SCM VALUE)
     Modifies the CAR of PAIR to be VALUE.  This is equivalent to the
     Scheme procedure `(set-car! ...)'.

 - Function: SCM gh_set_cdr_x(SCM PAIR, SCM VALUE)
     Modifies the CDR of PAIR to be VALUE.  This is equivalent to the
     Scheme procedure `(set-cdr! ...)'.

 - Function: unsigned long gh_length (SCM LS)
     Returns the length of the list.

 - Function: SCM gh_append (SCM ARGS)
 - Function: SCM gh_append2 (SCM L1, SCM L2)
 - Function: SCM gh_append3 (SCM L1, SCM L2, L3)
 - Function: SCM gh_append4 (SCM L1, SCM L2, L3, L4)
     `gh_append()' takes ARGS, which is a list of lists `(list1 list2
     ...)', and returns a list containing all the elements of the
     individual lists.

     A typical invocation of `gh_append()' to append 5 lists together
     would be
            gh_append(gh_list(l1, l2, l3, l4, l5, SCM_UNDEFINED));

     The functions `gh_append2()', `gh_append2()', `gh_append3()' and
     `gh_append4()' are convenience routines to make it easier for C
     programs to form the list of lists that goes as an argument to
     `gh_append()'.

 - Function: SCM gh_reverse (SCM LS)
     Returns a new list that has the same elements as LS but in the
     reverse order.  Note that this is implemented as a macro which
     calls `scm_reverse()'.

 - Function: SCM gh_list_tail (SCM LS, SCM K)
     Returns the sublist of LS with the last K elements.

 - Function: SCM gh_list_ref (SCM LS, SCM K)
     Returns the Kth element of the list LS.

 - Function: SCM gh_memq (SCM X, SCM LS)
 - Function: SCM gh_memv (SCM X, SCM LS)
 - Function: SCM gh_member (SCM X, SCM LS)
     These functions return the first sublist of LS whose CAR is X.
     They correspond to `(memq x ls)', `(memv x ls)' and `(member x
     ls)', and hence use (respectively) `eq?', `eqv?' and `equal?' to
     do comparisons.

     If X does not appear in LS, the value `SCM_BOOL_F' (not the empty
     list) is returned.

     Note that these functions are implemented as macros which call
     `scm_memq()', `scm_memv()' and `scm_member()' respectively.

 - Function: SCM gh_assq (SCM X, SCM ALIST)
 - Function: SCM gh_assv (SCM X, SCM ALIST)
 - Function: SCM gh_assoc (SCM X, SCM ALIST)
     These functions search an "association list" (list of pairs) ALIST
     for the first pair whose CAR is X, and they return that pair.

     If no pair in ALIST has X as its CAR, the value `SCM_BOOL_F' (not
     the empty list) is returned.

     Note that these functions are implemented as macros which call
     `scm_assq()', `scm_assv()' and `scm_assoc()' respectively.

Symbols
=======

Vectors
=======

 - Function: SCM gh_make_vector (SCM N, SCM FILL)
 - Function: SCM gh_vector (SCM LS)
 - Function: SCM gh_vector_ref (SCM V, SCM I)
 - Function: SCM gh_vector_set (SCM V, SCM I, SCM VAL)
 - Function: unsigned long gh_vector_length (SCM V)
 - Function: SCM gh_list_to_vector (SCM LS)
     These correspond to the Scheme `(make-vector n fill)', `(vector a
     b c ...)' `(vector-ref v i)' `(vector-set v i value)'
     `(vector-length v)' `(list->vector ls)' procedures.

     The correspondence is not perfect for `gh_vector': this routine
     takes a list LS instead of the individual list elements, thus
     making it identical to `gh_list_to_vector'.

     There is also a difference in gh_vector_length: the value returned
     is a C `unsigned long' instead of an SCM object.

Procedures
==========

 - Function: SCM gh_apply (SCM proc, SCM args)
     Call the Scheme procedure PROC, with the elements of ARGS as
     arguments.  ARGS must be a proper list.

 - Function: SCM gh_call0 (SCM proc)
 - Function: SCM gh_call1 (SCM proc, SCM arg)
 - Function: SCM gh_call2 (SCM proc, SCM arg1, SCM arg2)
 - Function: SCM gh_call3 (SCM proc, SCM arg1, SCM arg2, SCM arg3)
     Call the Scheme procedure PROC with no arguments (`gh_call0'), one
     argument (`gh_call1'), and so on.  You can get the same effect by
     wrapping the arguments up into a list, and calling `gh_apply';
     Guile provides these functions for convenience.

 - Function: SCM gh_catch (SCM key, SCM thunk, SCM handler)
 - Function: SCM gh_throw (SCM key, SCM args)
     Corresponds to the Scheme `catch' and `throw' procedures, which in
     Guile are provided as primitives.

 - Function: SCM gh_is_eq (SCM a, SCM b)
 - Function: SCM gh_is_eqv (SCM a, SCM b)
 - Function: SCM gh_is_equal (SCM a, SCM b)
     These correspond to the Scheme `eq?', `eqv?' and `equal?'
     predicates.

 - Function: int gh_obj_length (SCM OBJ)
     Returns the raw object length.

Data lookup
===========

   For now I just include Tim Pierce's comments from the `gh_data.c'
file; it should be organized into a documentation of the two functions
here.

     /* Data lookups between C and Scheme
     
        Look up a symbol with a given name, and return the object to which
        it is bound.  gh_lookup examines the Guile top level, and
        gh_module_lookup checks the module name space specified by the
        `vec' argument.
     
        The return value is the Scheme object to which SNAME is bound, or
        SCM_UNDEFINED if SNAME is not bound in the given context. [FIXME:
        should this be SCM_UNSPECIFIED?  Can a symbol ever legitimately be
        bound to SCM_UNDEFINED or SCM_UNSPECIFIED?  What is the difference?
        -twp] */


File: guile.info,  Node: Mixing gh and scm APIs,  Next: scm transition summary,  Prev: Calling Scheme procedures from C,  Up: GH

Mixing gh and scm APIs
======================


File: guile.info,  Node: scm transition summary,  Prev: Mixing gh and scm APIs,  Up: GH

Transitioning to the scm Interface
==================================

   The following table summarizes the available information on how to
transition from the GH to the scm interface.  Where transitioning is not
completely straightforward, the table includes a reference to more
detailed documentation in the preceding sections.

Header file
     Use `#include <libguile.h>' instead of `#include <guile/gh.h>'.

Compiling and Linking
     Use `guile-config' to pick up the flags required to compile C or
     C++ code that uses `libguile', like so

          $(CC) -o prog.o -c prog.c `guile-config compile`

     If you are using libtool to link your executables, just use
     `-lguile' in your link command.  Libtool will expand this into the
     needed linker options automatically.  If you are not using
     libtool, use the `guile-config' program to query the needed
     options explicitly.  A linker command like

          $(CC) -o prog prog.o `guile-config link`

     should be all that is needed.  To link shared libraries that will
     be used as Guile Extensions, use libtool to control both the
     compilation and the link stage.

The `SCM' type
     No change: the scm interface also uses this type to represent an
     arbitrary Scheme value.

`SCM_BOOL_F' and `SCM_BOOL_T'
     No change.

`SCM_UNSPECIFIED' and `SCM_UNDEFINED'
     No change.

`gh_enter'
     Use `scm_boot_guile' instead, but note that `scm_boot_guile' has a
     slightly different calling convention from `gh_enter':
     `scm_boot_guile', and the main program function that you specify
     for `scm_boot_guile' to call, both take an additional CLOSURE
     parameter.  *Note Guile Initialization Functions:: for more
     details.

`gh_repl'
     Use `scm_shell' instead.

`gh_init'
     Use `scm_init_guile' instead.

`gh_eval_str'
     Use `scm_c_eval_string' instead.

`gh_eval_file' or `gh_load'
     Use `scm_c_primitive_load' instead.

`gh_new_procedure'
     Use `scm_c_define_gsubr' instead, but note that the arguments are
     in a different order: for `scm_c_define_gsubr' the C function
     pointer is the last argument.  *Note A Sample Guile Extension::
     for an example.

`gh_defer_ints' and `gh_allow_ints'
     Use `SCM_DEFER_INTS' and `SCM_ALLOW_INTS' instead.  Note that
     these macros are used without parentheses, as in `SCM_DEFER_INTS;'.

`gh_bool2scm'
     Use `SCM_BOOL' instead.

`gh_ulong2scm'
     Use `scm_ulong2num' instead.

`gh_long2scm'
     Use `scm_long2num' instead.

`gh_double2scm'
     Use `scm_make_real' instead.

`gh_char2scm'
     Use `SCM_MAKE_CHAR' instead.

`gh_str2scm'
     Use `scm_mem2string' instead.

`gh_str02scm'
     Use `scm_makfrom0str' instead.

`gh_set_substr'
     No direct scm equivalent.  [FIXME]

`gh_symbol2scm'
     Use `scm_str2symbol' instead.  [FIXME: inconsistent naming, should
     be `scm_str02symbol'.]

`gh_ints2scm' and `gh_doubles2scm'
     No direct scm equivalent.  [FIXME]

`gh_chars2byvect' and `gh_shorts2svect'
     No direct scm equivalent.  [FIXME]

`gh_longs2ivect' and `gh_ulongs2uvect'
     No direct scm equivalent.  [FIXME]

`gh_floats2fvect' and `gh_doubles2dvect'
     No direct scm equivalent.  [FIXME]

`gh_scm2bool'
     Use `SCM_NFALSEP' instead.

`gh_scm2int'
     Replace `gh_scm2int (OBJ)' by
          scm_num2int (OBJ, SCM_ARG1, STR)
     where STR is a C string that describes the context of the call.

`gh_scm2ulong'
     Replace `gh_scm2ulong (OBJ)' by
          scm_num2ulong (OBJ, SCM_ARG1, STR)
     where STR is a C string that describes the context of the call.

`gh_scm2long'
     Replace `gh_scm2long (OBJ)' by
          scm_num2long (OBJ, SCM_ARG1, STR)
     where STR is a C string that describes the context of the call.

`gh_scm2double'
     Replace `gh_scm2double (OBJ)' by
          scm_num2dbl (OBJ, STR)
     where STR is a C string that describes the context of the call.

`gh_scm2char'
     Use the `SCM_CHAR' macro instead, but note that `SCM_CHAR' does
     not check that its argument is actually a character.  To check that
     a `SCM' value is a character before using `SCM_CHAR' to extract
     the character value, use the `SCM_VALIDATE_CHAR' macro.

`gh_scm2newstr'
     No direct scm equivalent.  [FIXME]

`gh_get_substr'
     No direct scm equivalent.  [FIXME]

`gh_symbol2newstr'
     No direct scm equivalent.  [FIXME]

`gh_scm2chars'
     No direct scm equivalent.  [FIXME]

`gh_scm2shorts' and `gh_scm2longs'
     No direct scm equivalent.  [FIXME]

`gh_scm2floats' and `gh_scm2doubles'
     No direct scm equivalent.  [FIXME]

`gh_boolean_p'
     Use the `SCM_BOOLP' macro instead, or replace `gh_boolean_p (OBJ)'
     by
          SCM_NFALSEP (scm_boolean_p (OBJ))

`gh_symbol_p'
     Use the `SCM_SYMBOLP' macro instead, or replace `gh_symbol_p
     (OBJ)' by
          SCM_NFALSEP (scm_symbol_p (OBJ))

`gh_char_p'
     Use the `SCM_CHARP' macro instead, or replace `gh_char_p (OBJ)' by
          SCM_NFALSEP (scm_char_p (OBJ))

`gh_vector_p'
     Use the `SCM_VECTORP' macro instead, or replace `gh_vector_p
     (OBJ)' by
          SCM_NFALSEP (scm_vector_p (OBJ))

`gh_pair_p'
     Use the `SCM_CONSP' macro instead, or replace `gh_pair_p (OBJ)' by
          SCM_NFALSEP (scm_pair_p (OBJ))

`gh_number_p'
     Use the `SCM_NUMBERP' macro instead, or replace `gh_number_p
     (OBJ)' by
          SCM_NFALSEP (scm_number_p (OBJ))

`gh_string_p'
     Use the `SCM_STRINGP' macro instead, or replace `gh_string_p
     (OBJ)' by
          SCM_NFALSEP (scm_string_p (OBJ))

`gh_procedure_p'
     Replace `gh_procedure_p (OBJ)' by
          SCM_NFALSEP (scm_procedure_p (OBJ))

`gh_list_p'
     Replace `gh_list_p (OBJ)' by
          SCM_NFALSEP (scm_list_p (OBJ))

`gh_inexact_p'
     Use the `SCM_INEXACTP' macro instead, or replace `gh_inexact_p
     (OBJ)' by
          SCM_NFALSEP (scm_inexact_p (OBJ))

`gh_exact_p'
     Replace `gh_exact_p (OBJ)' by
          SCM_NFALSEP (scm_exact_p (OBJ))

`gh_eq_p'
     Use the `SCM_EQ_P' macro instead, or replace `gh_eq_p (X, Y)' by
          SCM_NFALSEP (scm_eq_p (X, Y))

`gh_eqv_p'
     Replace `gh_eqv_p (X, Y)' by
          SCM_NFALSEP (scm_eqv_p (X, Y))

`gh_equal_p'
     Replace `gh_equal_p (X, Y)' by
          SCM_NFALSEP (scm_equal_p (X, Y))

`gh_string_equal_p'
     Replace `gh_string_equal_p (X, Y)' by
          SCM_NFALSEP (scm_string_equal_p (X, Y))

`gh_null_p'
     Use the `SCM_NULLP' macro instead, or replace `gh_null_p (OBJ)' by
          SCM_NFALSEP (scm_null_p (OBJ))

`gh_cons'
     Use `scm_cons' instead.

`gh_car' and `gh_cdr'
     Use the `SCM_CAR' and `SCM_CDR' macros instead.

`gh_cxxr' and `gh_cxxxr'
     (Where each x is either `a' or `d'.)  Use the corresponding
     `SCM_CXXR' or `SCM_CXXXR' macro instead.

`gh_set_car_x' and `gh_set_cdr_x'
     Use `scm_set_car_x' and `scm_set_cdr_x' instead.

`gh_list'
     Use `scm_listify' instead.

`gh_length'
     Replace `gh_length (LST)' by
          scm_num2ulong (scm_length (LST), SCM_ARG1, STR)
     where STR is a C string that describes the context of the call.

`gh_append'
     Use `scm_append' instead.

`gh_append2', `gh_append3', `gh_append4'
     Replace `gh_appendN (L1, ..., LN)' by
          scm_append (scm_listify (L1, ..., LN, SCM_UNDEFINED))

`gh_reverse'
     Use `scm_reverse' instead.

`gh_list_tail' and `gh_list_ref'
     Use `scm_list_tail' and `scm_list_ref' instead.

`gh_memq', `gh_memv' and `gh_member'
     Use `scm_memq', `scm_memv' and `scm_member' instead.

`gh_assq', `gh_assv' and `gh_assoc'
     Use `scm_assq', `scm_assv' and `scm_assoc' instead.

`gh_make_vector'
     Use `scm_make_vector' instead.

`gh_vector' or `gh_list_to_vector'
     Use `scm_vector' instead.

`gh_vector_ref' and `gh_vector_set_x'
     Use `scm_vector_ref' and `scm_vector_set_x' instead.

`gh_vector_length'
     Use the `SCM_VECTOR_LENGTH' macro instead.

`gh_apply'
     Use `scm_apply' instead, but note that `scm_apply' takes an
     additional third argument that you should set to `SCM_EOL'.


File: guile.info,  Node: Reference Intro,  Next: API Overview,  Prev: GH,  Up: Top

Part IV: Guile API Reference
****************************

   Guile provides an application programming interface ("API") to
developers in two core languages: Scheme and C.  This part of the manual
contains reference documentation for all of the functionality that is
available through both Scheme and C interfaces.


File: guile.info,  Node: API Overview,  Next: Simple Data Types,  Prev: Reference Intro,  Up: Top

Overview of the Guile API
*************************

   Guile's application programming interface ("API") makes
functionality available that an application developer can use in either
C or Scheme programming.  The interface consists of "elements" that may
be macros, functions or variables in C, and procedures, variables,
syntax or other types of object in Scheme.  Broadly speaking, the
interface as a whole can be divided into three groups.

  1. Elements that are available equivalently as C functions or Scheme
     procedures.

  2. Elements that are only available as macros, functions or variables
     for C programming.

  3. Elements that are only available as procedures or other objects in
     Scheme.

   Functions/procedures in the first group are often known as
"primitives", "subrs" or "builtins".  An example is the `assq' Scheme
procedure, which is also available as `scm_assq' in C.

   Elements in the second and third groups exist because they provide
additional language-specific benefits in either Scheme or C.  Examples
are the C macro `SCM_CONSP', which is faster and more convenient in C
programming than the primitive `scm_pair_p', and the
procedure-with-setter `make-object-property', which provides a more
convenient property handling interface in Scheme than the primitives on
which it is based.

* Menu:

* Primitives::                  Identical function for Scheme and C.
* C Only::                      Elements only available in C.
* Scheme Only::                 Elements only available in Scheme.
* Reference Layout::            The layout of this part of the manual.


File: guile.info,  Node: Primitives,  Next: C Only,  Up: API Overview

Identical Function in both Scheme and C
=======================================

   They form the majority of the API, and allow both C and Scheme
programmers to perform identical operations.

   Scheme procedures marked "primitive functions" have a regular
interface when calling from C, reflected in two areas: the name of a C
function, and the convention for passing non-required arguments to this
function.

* Menu:

* Transforming Scheme name to C name::
* Structuring argument lists for C functions::


File: guile.info,  Node: Transforming Scheme name to C name,  Next: Structuring argument lists for C functions,  Up: Primitives

Transforming Scheme name to C name
----------------------------------

   Normally, the name of a C function can be derived given its Scheme
name, using some simple textual transformations:

   * Replace `-' (hyphen) with `_' (underscore).

   * Replace `?' (question mark) with "_p".

   * Replace `!' (exclamation point) with "_x".

   * Replace internal `->' with "_to_".

   * Replace `<=' (less than or equal) with "_leq".

   * Replace `>=' (greater than or equal) with "_geq".

   * Replace `<' (less than) with "_less".

   * Replace `>' (greater than) with "_gr".

   * Replace `@' with "at". [Omit?]

   * Prefix with "gh_" (or "scm_" if you are ignoring the gh interface).

   * [Anything else?  -ttn, 2000/01/16 15:17:28]


   Here is an Emacs Lisp command that prompts for a Scheme function
name and inserts the corresponding C function name into the buffer.

     (defun insert-scheme-to-C (name &optional use-gh)
       "Transforms Scheme NAME, a string, to its C counterpart, and inserts it.
     Prefix arg non-nil means use \"gh_\" prefix, otherwise use \"scm_\" prefix."
       (interactive "sScheme name: \nP")
       (let ((transforms '(("-"  . "_")
                           ("?"  . "_p")
                           ("!"  . "_x")
                           ("->" . "_to_")
                           ("<=" . "_leq")
                           (">=" . "_geq")
                           ("<"  . "_less")
                           (">"  . "_gr")
                           ("@"  . "at"))))
         (while transforms
           (let ((trigger (concat "\\(.*\\)"
                                  (regexp-quote (caar transforms))
                                  "\\(.*\\)"))
                 (sub (cdar transforms))
                 (m nil))
             (while (setq m (string-match trigger name))
               (setq name (concat (match-string 1 name)
                                  sub
                                  (match-string 2 name)))))
           (setq transforms (cdr transforms))))
       (insert (if use-gh "gh_" "scm_") name))


File: guile.info,  Node: Structuring argument lists for C functions,  Prev: Transforming Scheme name to C name,  Up: Primitives

Structuring argument lists for C functions
------------------------------------------

   The C function's arguments will be all of the Scheme procedure's
arguments, both required and optional; if the Scheme procedure takes a
"rest" argument, that will be a final argument to the C function.  The
C function's arguments, as well as its return type, will be `SCM'.


File: guile.info,  Node: C Only,  Next: Scheme Only,  Prev: Primitives,  Up: API Overview

Elements Available Only in C
============================

   For C this is usually a matter of better performance (e.g. the
`SCM_CONSP' macro) or of accepting C language types rather than the
generic `SCM'.


File: guile.info,  Node: Scheme Only,  Next: Reference Layout,  Prev: C Only,  Up: API Overview

Elements Available Only in Scheme
=================================


File: guile.info,  Node: Reference Layout,  Prev: Scheme Only,  Up: API Overview

Reference Material Layout
=========================

   This part of the reference manual documents all of Guile's core
Scheme-level language and features in functionally-related groups.
Where a particular section of the manual includes both R5RS-compliant
parts and Guile-specific extensions, the text indicates which parts of
the documentation describe R5RS behaviour and which parts describe Guile
extensions.

   For a quick way of identifying the parts of Guile that implement
R5RS-compliant features, see the R5RS index: *Note R5RS Index::.


File: guile.info,  Node: Simple Data Types,  Next: Compound Data Types,  Prev: API Overview,  Up: Top

Simple Generic Data Types
*************************

   This chapter describes those of Guile's simple data types which are
primarily used for their role as items of generic data.  By "simple" we
mean data types that are not primarily used as containers to hold other
data -- i.e. pairs, lists, vectors and so on.  For the documentation of
such "compound" data types, see *Note Compound Data Types::.

   One of the great strengths of Scheme is that there is no
straightforward distinction between "data" and "functionality".  For
example, Guile's support for dynamic linking could be described

   * either in a "data-centric" way, as the behaviour and properties of
     the "dynamically linked object" data type, and the operations that
     may be applied to instances of this type

   * or in a "functionality-centric" way, as the set of procedures that
     constitute Guile's support for dynamic linking, in the context of
     the module system.

   The contents of this chapter are, therefore, a matter of judgment.
By "generic", we mean to select those data types whose typical use as
_data_ in a wide variety of programming contexts is more important than
their use in the implementation of a particular piece of
_functionality_.  The last section of this chapter provides references
for all the data types that are documented not here but in a
"functionality-centric" way elsewhere in the manual.

* Menu:

* Booleans::                    True/false values.
* Numbers::                     Numerical data types.
* Characters::                  New character names.
* Strings::                     Special things about strings.
* Regular Expressions::         Pattern matching and substitution.
* Symbols::                     Symbols.
* Keywords::                    Self-quoting, customizable display keywords.
* Other Types::                 "Functionality-centric" data types.


File: guile.info,  Node: Booleans,  Next: Numbers,  Up: Simple Data Types

Booleans
========

   The two boolean values are `#t' for true and `#f' for false.

   Boolean values are returned by predicate procedures, such as the
general equality predicates `eq?', `eqv?' and `equal?' (*note
Equality::) and numerical and string comparison operators like
`string=?' (*note String Comparison::) and `<=' (*note Comparison::).

     (<= 3 8)
     =>
     #t
     
     (<= 3 -3)
     =>
     #f
     
     (equal? "house" "houses")
     =>
     #f
     
     (eq? #f #f)
     =>
     #t

   In test condition contexts like `if' and `cond' (*note if cond
case::), where a group of subexpressions will be evaluated only if a
CONDITION expression evaluates to "true", "true" means any value at all
except `#f'.

     (if #t "yes" "no")
     =>
     "yes"
     
     (if 0 "yes" "no")
     =>
     "yes"
     
     (if #f "yes" "no")
     =>
     "no"

   A result of this asymmetry is that typical Scheme source code more
often uses `#f' explicitly than `#t': `#f' is necessary to represent an
`if' or `cond' false value, whereas `#t' is not necessary to represent
an `if' or `cond' true value.

   It is important to note that `#f' is *not* equivalent to any other
Scheme value.  In particular, `#f' is not the same as the number 0
(like in C and C++), and not the same as the "empty list" (like in some
Lisp dialects).

   The `not' procedure returns the boolean inverse of its argument:

 - Scheme Procedure: not x
 - C Function: scm_not (x)
     Return `#t' iff X is `#f', else return `#f'.

   The `boolean?' procedure is a predicate that returns `#t' if its
argument is one of the boolean values, otherwise `#f'.

 - Scheme Procedure: boolean? obj
 - C Function: scm_boolean_p (obj)
     Return `#t' iff OBJ is either `#t' or `#f'.


File: guile.info,  Node: Numbers,  Next: Characters,  Prev: Booleans,  Up: Simple Data Types

Numerical data types
====================

   Guile supports a rich "tower" of numerical types -- integer,
rational, real and complex -- and provides an extensive set of
mathematical and scientific functions for operating on numerical data.
This section of the manual documents those types and functions.

   You may also find it illuminating to read R5RS's presentation of
numbers in Scheme, which is particularly clear and accessible: see
*Note Numbers: (r5rs)Numbers.

* Menu:

* Numerical Tower::             Scheme's numerical "tower".
* Integers::                    Whole numbers.
* Reals and Rationals::         Real and rational numbers.
* Complex Numbers::             Complex numbers.
* Exactness::                   Exactness and inexactness.
* Number Syntax::               Read syntax for numerical data.
* Integer Operations::          Operations on integer values.
* Comparison::                  Comparison predicates.
* Conversion::                  Converting numbers to and from strings.
* Complex::                     Complex number operations.
* Arithmetic::                  Arithmetic functions.
* Scientific::                  Scientific functions.
* Primitive Numerics::          Primitive numeric functions.
* Bitwise Operations::          Logical AND, OR, NOT, and so on.
* Random::                      Random number generation.


File: guile.info,  Node: Numerical Tower,  Next: Integers,  Up: Numbers

Scheme's Numerical "Tower"
--------------------------

   Scheme's numerical "tower" consists of the following categories of
numbers:

   * integers (whole numbers)

   * rationals (the set of numbers that can be expressed as P/Q where P
     and Q are integers)

   * real numbers (the set of numbers that describes all possible
     positions along a one dimensional line)

   * complex numbers (the set of numbers that describes all possible
     positions in a two dimensional space)

   It is called a tower because each category "sits on" the one that
follows it, in the sense that every integer is also a rational, every
rational is also real, and every real number is also a complex number
(but with zero imaginary part).

   Of these, Guile implements integers, reals and complex numbers as
distinct types.  Rationals are implemented as regards the read syntax
for rational numbers that is specified by R5RS, but are immediately
converted by Guile to the corresponding real number.

   The `number?' predicate may be applied to any Scheme value to
discover whether the value is any of the supported numerical types.

 - Scheme Procedure: number? obj
 - C Function: scm_number_p (obj)
     Return `#t' if OBJ is any kind of number, else `#f'.

   For example:

     (number? 3)
     =>
     #t
     
     (number? "hello there!")
     =>
     #f
     
     (define pi 3.141592654)
     (number? pi)
     =>
     #t

   The next few subsections document each of Guile's numerical data
types in detail.


File: guile.info,  Node: Integers,  Next: Reals and Rationals,  Prev: Numerical Tower,  Up: Numbers

Integers
--------

   Integers are whole numbers, that is numbers with no fractional part,
such as 2, 83 and -3789.

   Integers in Guile can be arbitrarily big, as shown by the following
example.

     (define (factorial n)
       (let loop ((n n) (product 1))
         (if (= n 0)
             product
             (loop (- n 1) (* product n)))))
     
     (factorial 3)
     =>
     6
     
     (factorial 20)
     =>
     2432902008176640000
     
     (- (factorial 45))
     =>
     -119622220865480194561963161495657715064383733760000000000

   Readers whose background is in programming languages where integers
are limited by the need to fit into just 4 or 8 bytes of memory may find
this surprising, or suspect that Guile's representation of integers is
inefficient.  In fact, Guile achieves a near optimal balance of
convenience and efficiency by using the host computer's native
representation of integers where possible, and a more general
representation where the required number does not fit in the native
form.  Conversion between these two representations is automatic and
completely invisible to the Scheme level programmer.

 - Scheme Procedure: integer? x
 - C Function: scm_integer_p (x)
     Return `#t' if X is an integer number, else `#f'.

          (integer? 487)
          =>
          #t
          
          (integer? -3.4)
          =>
          #f


File: guile.info,  Node: Reals and Rationals,  Next: Complex Numbers,  Prev: Integers,  Up: Numbers

Real and Rational Numbers
-------------------------

   Mathematically, the real numbers are the set of numbers that describe
all possible points along a continuous, infinite, one-dimensional line.
The rational numbers are the set of all numbers that can be written as
fractions P/Q, where P and Q are integers.  All rational numbers are
also real, but there are real numbers that are not rational, for example
the square root of 2, and pi.

   Guile represents both real and rational numbers approximately using a
floating point encoding with limited precision.  Even though the actual
encoding is in binary, it may be helpful to think of it as a decimal
number with a limited number of significant figures and a decimal point
somewhere, since this corresponds to the standard notation for non-whole
numbers.  For example:

     0.34
     -0.00000142857931198
     -5648394822220000000000.0
     4.0

   The limited precision of Guile's encoding means that any "real"
number in Guile can be written in a rational form, by multiplying and
then dividing by sufficient powers of 10 (or in fact, 2).  For example,
`-0.00000142857931198' is the same as `142857931198' divided by
`100000000000000000'.  In Guile's current incarnation, therefore, the
`rational?' and `real?' predicates are equivalent.

   Another aspect of this equivalence is that Guile currently does not
preserve the exactness that is possible with rational arithmetic.  If
such exactness is needed, it is of course possible to implement exact
rational arithmetic at the Scheme level using Guile's arbitrary size
integers.

   A planned future revision of Guile's numerical tower will make it
possible to implement exact representations and arithmetic for both
rational numbers and real irrational numbers such as square roots, and
in such a way that the new kinds of number integrate seamlessly with
those that are already implemented.

 - Scheme Procedure: real? obj
 - C Function: scm_real_p (obj)
     Return `#t' if OBJ is a real number, else `#f'.  Note that the
     sets of integer and rational values form subsets of the set of
     real numbers, so the predicate will also be fulfilled if OBJ is an
     integer number or a rational number.

 - Scheme Procedure: rational? x
 - C Function: scm_real_p (x)
     Return `#t' if X is a rational number, `#f' otherwise.  Note that
     the set of integer values forms a subset of the set of rational
     numbers, i. e. the predicate will also be fulfilled if X is an
     integer number.  Real numbers will also satisfy this predicate,
     because of their limited precision.


File: guile.info,  Node: Complex Numbers,  Next: Exactness,  Prev: Reals and Rationals,  Up: Numbers

Complex Numbers
---------------

   Complex numbers are the set of numbers that describe all possible
points in a two-dimensional space.  The two coordinates of a particular
point in this space are known as the "real" and "imaginary" parts of
the complex number that describes that point.

   In Guile, complex numbers are written in rectangular form as the sum
of their real and imaginary parts, using the symbol `i' to indicate the
imaginary part.

     3+4i
     =>
     3.0+4.0i
     
     (* 3-8i 2.3+0.3i)
     =>
     9.3-17.5i

   Guile represents a complex number as a pair of numbers both of which
are real, so the real and imaginary parts of a complex number have the
same properties of inexactness and limited precision as single real
numbers.

 - Scheme Procedure: complex? x
 - C Function: scm_number_p (x)
     Return `#t' if X is a complex number, `#f' otherwise.  Note that
     the sets of real, rational and integer values form subsets of the
     set of complex numbers, i. e. the predicate will also be fulfilled
     if X is a real, rational or integer number.


File: guile.info,  Node: Exactness,  Next: Number Syntax,  Prev: Complex Numbers,  Up: Numbers

Exact and Inexact Numbers
-------------------------

   R5RS requires that a calculation involving inexact numbers always
produces an inexact result.  To meet this requirement, Guile
distinguishes between an exact integer value such as `5' and the
corresponding inexact real value which, to the limited precision
available, has no fractional part, and is printed as `5.0'.  Guile will
only convert the latter value to the former when forced to do so by an
invocation of the `inexact->exact' procedure.

 - Scheme Procedure: exact? x
 - C Function: scm_exact_p (x)
     Return `#t' if X is an exact number, `#f' otherwise.

 - Scheme Procedure: inexact? x
 - C Function: scm_inexact_p (x)
     Return `#t' if X is an inexact number, `#f' else.

 - Scheme Procedure: inexact->exact z
 - C Function: scm_inexact_to_exact (z)
     Return an exact number that is numerically closest to Z.

 - Scheme Procedure: exact->inexact z
     Convert the number Z to its inexact representation.


File: guile.info,  Node: Number Syntax,  Next: Integer Operations,  Prev: Exactness,  Up: Numbers

Read Syntax for Numerical Data
------------------------------

   The read syntax for integers is a string of digits, optionally
preceded by a minus or plus character, a code indicating the base in
which the integer is encoded, and a code indicating whether the number
is exact or inexact.  The supported base codes are:

   * `#b', `#B' -- the integer is written in binary (base 2)

   * `#o', `#O' -- the integer is written in octal (base 8)

   * `#d', `#D' -- the integer is written in decimal (base 10)

   * `#x', `#X' -- the integer is written in hexadecimal (base 16).

   If the base code is omitted, the integer is assumed to be decimal.
The following examples show how these base codes are used.

     -13
     =>
     -13
     
     #d-13
     =>
     -13
     
     #x-13
     =>
     -19
     
     #b+1101
     =>
     13
     
     #o377
     =>
     255

   The codes for indicating exactness (which can, incidentally, be
applied to all numerical values) are:

   * `#e', `#E' -- the number is exact

   * `#i', `#I' -- the number is inexact.

   If the exactness indicator is omitted, the integer is assumed to be
exact, since Guile's internal representation for integers is always
exact.  Real numbers have limited precision similar to the precision of
the `double' type in C.  A consequence of the limited precision is that
all real numbers in Guile are also rational, since any number R with a
limited number of decimal places, say N, can be made into an integer by
multiplying by 10^N.


File: guile.info,  Node: Integer Operations,  Next: Comparison,  Prev: Number Syntax,  Up: Numbers

Operations on Integer Values
----------------------------

 - Scheme Procedure: odd? n
 - C Function: scm_odd_p (n)
     Return `#t' if N is an odd number, `#f' otherwise.

 - Scheme Procedure: even? n
 - C Function: scm_even_p (n)
     Return `#t' if N is an even number, `#f' otherwise.

 - Scheme Procedure: quotient
     Return the quotient of the numbers X and Y.

 - Scheme Procedure: remainder
     Return the remainder of the numbers X and Y.
          (remainder 13 4) => 1
          (remainder -13 4) => -1

 - Scheme Procedure: modulo
     Return the modulo of the numbers X and Y.
          (modulo 13 4) => 1
          (modulo -13 4) => 3

 - Scheme Procedure: gcd
     Return the greatest common divisor of all arguments.  If called
     without arguments, 0 is returned.

 - Scheme Procedure: lcm
     Return the least common multiple of the arguments.  If called
     without arguments, 1 is returned.


File: guile.info,  Node: Comparison,  Next: Conversion,  Prev: Integer Operations,  Up: Numbers

Comparison Predicates
---------------------

 - Scheme Procedure: =
     Return `#t' if all parameters are numerically equal.

 - Scheme Procedure: <
     Return `#t' if the list of parameters is monotonically increasing.

 - Scheme Procedure: >
     Return `#t' if the list of parameters is monotonically decreasing.

 - Scheme Procedure: <=
     Return `#t' if the list of parameters is monotonically
     non-decreasing.

 - Scheme Procedure: >=
     Return `#t' if the list of parameters is monotonically
     non-increasing.

 - Scheme Procedure: zero?
     Return `#t' if Z is an exact or inexact number equal to zero.

 - Scheme Procedure: positive?
     Return `#t' if X is an exact or inexact number greater than zero.

 - Scheme Procedure: negative?
     Return `#t' if X is an exact or inexact number less than zero.


File: guile.info,  Node: Conversion,  Next: Complex,  Prev: Comparison,  Up: Numbers

Converting Numbers To and From Strings
--------------------------------------

 - Scheme Procedure: number->string n [radix]
 - C Function: scm_number_to_string (n, radix)
     Return a string holding the external representation of the number
     N in the given RADIX.  If N is inexact, a radix of 10 will be used.

 - Scheme Procedure: string->number string [radix]
 - C Function: scm_string_to_number (string, radix)
     Return a number of the maximally precise representation expressed
     by the given STRING. RADIX must be an exact integer, either 2, 8,
     10, or 16. If supplied, RADIX is a default radix that may be
     overridden by an explicit radix prefix in STRING (e.g. "#o177").
     If RADIX is not supplied, then the default radix is 10. If string
     is not a syntactically valid notation for a number, then
     `string->number' returns `#f'.


File: guile.info,  Node: Complex,  Next: Arithmetic,  Prev: Conversion,  Up: Numbers

Complex Number Operations
-------------------------

 - Scheme Procedure: make-rectangular real imaginary
 - C Function: scm_make_rectangular (real, imaginary)
     Return a complex number constructed of the given REAL and
     IMAGINARY parts.

 - Scheme Procedure: make-polar x y
 - C Function: scm_make_polar (x, y)
     Return the complex number X * e^(i * Y).

 - Scheme Procedure: real-part
     Return the real part of the number Z.

 - Scheme Procedure: imag-part
     Return the imaginary part of the number Z.

 - Scheme Procedure: magnitude
     Return the magnitude of the number Z. This is the same as `abs'
     for real arguments, but also allows complex numbers.

 - Scheme Procedure: angle
     Return the angle of the complex number Z.


File: guile.info,  Node: Arithmetic,  Next: Scientific,  Prev: Complex,  Up: Numbers

Arithmetic Functions
--------------------

 - Scheme Procedure: + z1 ...
     Return the sum of all parameter values.  Return 0 if called
     without any parameters.

 - Scheme Procedure: - z1 z2 ...
     If called with one argument Z1, -Z1 is returned. Otherwise the sum
     of all but the first argument are subtracted from the first
     argument.

 - Scheme Procedure: * z1 ...
     Return the product of all arguments.  If called without arguments,
     1 is returned.

 - Scheme Procedure: / z1 z2 ...
     Divide the first argument by the product of the remaining
     arguments.  If called with one argument Z1, 1/Z1 is returned.

 - Scheme Procedure: abs x
 - C Function: scm_abs (x)
     Return the absolute value of X.

     X must be a number with zero imaginary part.  To calculate the
     magnitude of a complex number, use `magnitude' instead.

 - Scheme Procedure: max x1 x2 ...
     Return the maximum of all parameter values.

 - Scheme Procedure: min x1 x2 ...
     Return the minimum of all parameter values.

 - Scheme Procedure: truncate
     Round the inexact number X towards zero.

 - Scheme Procedure: round x
     Round the inexact number X towards zero.

 - Scheme Procedure: floor x
     Round the number X towards minus infinity.

 - Scheme Procedure: ceiling x
     Round the number X towards infinity.

   For the `truncate' and `round' procedures, the Guile library exports
equivalent C functions, but taking and returning arguments of type
`double' rather than the usual `SCM'.

 - C Function: double scm_truncate (double x)
 - C Function: double scm_round (double x)

   For `floor' and `ceiling', the equivalent C functions are `floor'
and `ceil' from the standard mathematics library (which also take and
return `double' arguments).


File: guile.info,  Node: Scientific,  Next: Primitive Numerics,  Prev: Arithmetic,  Up: Numbers

Scientific Functions
--------------------

   The following procedures accept any kind of number as arguments,
including complex numbers.

 - Scheme Procedure: sqrt z
     Return the square root of Z.

 - Scheme Procedure: expt z1 z2
     Return Z1 raised to the power of Z2.

 - Scheme Procedure: sin z
     Return the sine of Z.

 - Scheme Procedure: cos z
     Return the cosine of Z.

 - Scheme Procedure: tan z
     Return the tangent of Z.

 - Scheme Procedure: asin z
     Return the arcsine of Z.

 - Scheme Procedure: acos z
     Return the arccosine of Z.

 - Scheme Procedure: atan z
     Return the arctangent of Z.

 - Scheme Procedure: exp z
     Return e to the power of Z, where e is the base of natural
     logarithms (2.71828...).

 - Scheme Procedure: log z
     Return the natural logarithm of Z.

 - Scheme Procedure: log10 z
     Return the base 10 logarithm of Z.

 - Scheme Procedure: sinh z
     Return the hyperbolic sine of Z.

 - Scheme Procedure: cosh z
     Return the hyperbolic cosine of Z.

 - Scheme Procedure: tanh z
     Return the hyperbolic tangent of Z.

 - Scheme Procedure: asinh z
     Return the hyperbolic arcsine of Z.

 - Scheme Procedure: acosh z
     Return the hyperbolic arccosine of Z.

 - Scheme Procedure: atanh z
     Return the hyperbolic arctangent of Z.

