@c EN \input texinfo @c -*- mode: texinfo; coding: utf-8; -*- @c JP \input texinfo-ja @c -*- mode: texinfo; coding: utf-8; -*- @c COMMON @comment %**start of header @documentencoding UTF-8 @c EN @documentlanguage en @setfilename gauche-deve.info @settitle Gauche Developers' Reference @dircategory The Algorithmic Language Scheme @direntry * Gauche Developers' Reference: (gauche-deve.info). Internals of Gauche @end direntry @c JP @documentlanguage ja @setfilename gauche-devj.info @settitle Gauche Developers' Reference @dircategory The Algorithmic Language Scheme @direntry * Gauche Developers' Reference (ja): (gauche-devj.info). Internals of Gauche @end direntry @c COMMON @comment %**end of header @titlepage @c EN @title Gauche Developers' Reference @c JP @title Gauche Developers' Reference @c COMMON @subtitle version @VERSION@ @author Shiro Kawai (shiro@@acm.org) @page @vskip 0pt plus 1filll Copyright @copyright{} 2009-2024 Shiro Kawai @end titlepage @node Top, Introduction, (dir), (dir) @ifnottex This document explains the internal guts of Gauche for developers who want to extend Gauche functionality in C, or to embed Gauche to other applications. This manual is for version @VERSION@. @end ifnottex @menu * Introduction:: * Getting started:: * Fundamental concepts:: * Real-life examples:: * C API reference:: * Creating new Scheme datatypes:: * Helper program reference:: * Indices:: @end menu @c ====================================================================== @node Introduction, Getting started, Top, Top @chapter Introduction The core part of the Gauche runtime is written in C and provided as a library, @file{libgauche}. This document explains how to use it from C. Using C API, you can extend Gauche's functionality (e.g. providing bindinds to the existing C library), and also link @file{libgauche} to your application, making Gauche as an embedded scripting language. Gauche's C API is designed for efficiency, consistency, simplicity and safety, roughly in this order of precedence. That is, sometimes we omit a safety net for efficiency, or we provide several different APIs, each of which is efficient for a particular purpose, rather than simple generic interface with overhead. By saying efficiency over safety doesn't mean Gauche has security holes, but we do assume you know what you're doing. If you need safety nets, you can write in Scheme and call it from C. That said, it won't be too difficult to use Gauche's C API as far as you know some fundamental design concepts. We intend this document to serve both a programmer's guide that explains such design concepts, and a programmer's reference that describes every C API in detail. The guide part begins with @ref{Getting started}, that shows how to write a simple Gauche extension in C, as well as a simple application that embeds Gauche. It gives an overview of the whole process. The following chapter, @ref{Fundamental concepts}, describes the design behind the API. We strongly recommend you to understand this chapter before trying to use Gauche C API seriously. As we mentioned above, it is very easy to break something without knowing those concepts. The guide part concludes with @ref{Real-life examples}, that explains pitfalls in the practical situations using excerpt of the actual Gauche extension code. The reference part consists of two chapters: @ref{C API reference} lists all the public C API. @ref{Helper program reference} explains several programs installed as a part of Gauche Scheme system to help program development. @c ====================================================================== @node Getting started, Fundamental concepts, Introduction, Top @chapter Getting started This chapter explains the basics of how to use Gauche C API by several simple examples. Although each example is too small to be practical value, we try to present working code for each example, so that you can actually play with it. We recommend you to read through all examples, for we introduce new concepts in each step. We deal with the advanced topics that arise in the practical situation in @ref{Real-life examples}. The prerequisites for building Gauche extension, besides the basic compiler chain, are the followings. We assume these are installed in your system. @itemize @bullet @item Gauche 0.9.10 or later @item A compiler suite compatible to the one used to build @file{libgauche}. @end itemize @menu * A trivial extension:: * Simple readline binding:: @end menu @node A trivial extension, Simple readline binding, Getting started, Getting started @section A trivial extension @menu * Generating skeletons:: * Building the trivial module:: * The templates explained:: * Introduction of the stub file:: @end menu @node Generating skeletons, Building the trivial module, A trivial extension, A trivial extension @subsection Generating skeletons Let's create a Gauche extension that does nothing. Gauche can generate a skeleton of the extension code by @code{gauche-package generate} command. You give the package name to the command-line argument (here we pick @code{trivial}). @smallexample % @b{ls trivial} ls: trivial: No such file or directory % @b{gauche-package generate trivial} % @b{ls trivial} configure package.scm trivial.c triviallib.stub Makefile.in test.scm trivial.h trivial.scm @end smallexample The @code{gauche-package} command creates a directory @file{trivial}, and populates it with template files. The role of each file is shown below. @table @emph @item Package description (@file{package.scm}) This file contains metainformation about the extension, such as version, dependency, license or repository URL. @item Glue code (@file{trivial.c} and @file{trivial.h}) If what you want to do is just to write C functions and make it available from Scheme, the function definitions and declarations would go to these files. Even if what you want to do is just to write bindings to an existing library, it is typical that you need small amount of auxiliary management code, such as initializing the library and allocating/freeing library-side data structures. @item Stub file (@file{triviallib.stub}) This file is the bridge between C world and Scheme world. You have to list C functions you want to make it visible from Scheme world. Because of its nature, this file looks like a mixture of Scheme code and C code fragments. When the package is compiled, Gauche's helper scripts generate a C file from a stub file, and compile it with other glue code to generate a dynamically loadable object code, called DLL (dynamically loadable library) or SO (shared object), depending on the platform. (Note: We're in middle of the process of retiring @file{*.stub} file; instead, you'll be able to mix Scheme and C code in @file{*.scm} file that will be compiled into DSO. The extensions bundled with the Gauche distribution, and several Gauche extensions, have already been switched; you can take a peek and maybe start trying it. The detailed specification of this @emph{precompilation}, or ahead-of-time compilation, is still fluid and may be changed in incompatible way, though.) @item Module file (@file{trivial.scm}) This file typically defines Gauche modules and sets exported symbols, and dynamically loads the compiled object code. You may put auxiliary Scheme code in it. @item Makefile template (@file{Makefile.in}) Gauche relies on the traditional build workflow---you run @file{configure} script to generate @file{Makefile} that is tailored for your system. Sticking to good old @code{make} makes it easy to incorporate third party libraries. @item Configure script (@file{configure}) This is a script that generates @file{Makefile} from @file{Makefile.in}. Edit this if you need other files to be tailored, or need to test other features on the platform. We used to use GNU @code{autoconf} to generate @file{configure}, but we're moving away from it. GNU @code{autoconf} is a fine tool with lots of practical knowledge had put into development, but its premise is that you have limited set of tools on the platform where you compile the software, and that limitation makes the pipeline complicated. When you build Gauche extension, we already know you have Gauche installed, so we can use Gauche's features to do configuration work instead of relying on shell and other limited set of command-line tools. It is especially handy since we no longer need an extra pass to generate @file{configure} from @file{configure.ac}. With the power of Gauche you can write @file{configure} file directly, and you can check it in to VCS. The users won't need @code{autoconf} to build from the (unpreprocessed) source tree. We try to match the interface of @file{configure} script to @code{autoconf}-generated ones; it accepts most of the standard options such as @code{--prefix}. @item Unit test (@file{test.scm}) It is strongly encouraged to include unit test in your package, and this file contains the skeleton of it. The package user can run the test by @code{make check}. @end table @node Building the trivial module, The templates explained, Generating skeletons, A trivial extension @subsection Building, testing and installing the trivial module These auto-generated files are already buildable. First, you need to run the @file{configure} script to generate @file{Makefile}, then run @code{make}. @smallexample % @b{cd trivial} % @b{./configure} checking for gosh... /usr/bin/gosh checking for gauche-config... /usr/bin/gauche-config checking for gauche-package... /usr/bin/gauche-package checking for gauche-install... /usr/bin/gauche-install checking for gauche-cesconv... /usr/bin/gauche-cesconv configure: creating trivial.gpd configure: creating Makefile % @b{make} /usr/bin/gauche-package compile --verbose trivial trivial.c triviallib.stub @i{(... message truncated ...)} % @b{ls} Makefile config.log trivial.c trivial.o triviallib.o Makefile.in configure trivial.gpd trivial.scm triviallib.stub VERSION test.scm trivial.h trivial.so @end smallexample The build process creates @file{trivial.so}, the dynamically loadable object file (the actual suffix may differ on some OSes). Now it's ready to load the extension into Gauche. The skeleton code defines a Scheme function @code{test-trivial}, which just returns a string. Run the Gauche interpreter, load the @code{trivial} module, and call @code{test-trivial} function. Note that you need to give @code{-I.} option to @code{gosh}, so that Gauche can find the @file{trivial} module files. @smallexample % @b{gosh -I.} gosh> @b{(use trivial)} gosh> @b{(test-trivial)} "trivial is working" gosh> @end smallexample You may have noticed a file @file{trivial.gpd}. The unfamiliar suffix @code{gpd} stands for ``Gauche package description''. It is created by @file{configure}, and records the name and version of the package, and the configure options. It is installed as a part of the package and will be used by @code{gauche-package} script (e.g. @code{gauche-package list} lists the installed packages). You can also run a unit test by @code{make check}. @smallexample % make check /usr/bin/gosh -I. test.scm > test.log Testing trivial ... passed. @end smallexample For now, it just checks if the compiled extension can be loaded, and the integrity of the module. As you add APIs in the extension, you're expected to add tests as well. Finally, you can install the extension by @code{make install}. @smallexample % make install /usr/bin/gauche-install -m 444 -T /usr/lib/gauche/site/include /usr/bin/gauche-install -m 444 -T /usr/share/gauche/site/lib trivial.scm /usr/bin/gauche-install -m 555 -T /usr/lib/gauche/site/0.8.8/i686-pc-linux-gnu trivial.so /usr/bin/gauche-install -m 444 -T /usr/share/gauche/site/lib/.packages trivial.gpd @end smallexample By default, the files are installed in the site-specific area reserved within the installed Gauche. If you want to change the install location, you can do the same as typical autoconfigured softwares; e.g. giving @code{--prefix} option to the @code{configure} script. @node The templates explained, Introduction of the stub file, Building the trivial module, A trivial extension @subsection The templates explained @node Introduction of the stub file, , The templates explained, A trivial extension @subsection Introduction of the stub file @node Simple readline binding, , A trivial extension, Getting started @section Simple readline binding @c ====================================================================== @node Fundamental concepts, Real-life examples, Getting started, Top @chapter Fundamental concepts @menu * Naming convention:: * Scheme types and C types:: * Memories:: * The VM:: * CPS API:: @end menu @node Naming convention, Scheme types and C types, Fundamental concepts, Fundamental concepts @section Naming convention @c Memo: @c Scm_XXXXSet(XXXX xxxx, ...) - operation to modify xxxx. @c Scm_SetXXXX(...) - operation to modify some global (or per-vm) value. @node Scheme types and C types, Memories, Naming convention, Fundamental concepts @section Scheme types and C types @node Memories, The VM, Scheme types and C types, Fundamental concepts @section Memories @node The VM, CPS API, Memories, Fundamental concepts @section The VM @node CPS API, , The VM, Fundamental concepts @section CPS API @c ====================================================================== @node Real-life examples, C API reference, Fundamental concepts, Top @chapter Real-life examples To be written. Meanwhile have a look at @file{examples/mqueue-cpp/README.adoc} in the Gauche source tree. @c ====================================================================== @node C API reference, Creating new Scheme datatypes, Real-life examples, Top @chapter C API reference In this chapter we describe most of public C APIs provided by libgauche. We say `most' because the features to let you create a new Scheme datatype requires dedicated chapter, @ref{Creating new Scheme datatypes}. @menu * Representation of Scheme objects:: * Initialization and cleanup:: * Memory allocation and GC:: * Booleans:: * Numbers:: * Pairs and lists:: * Symbols:: * Glocs:: * Modules:: * Characters:: * Character sets:: * Strings:: * Regular expressions:: * Vectors:: * Dictionaries:: * Weak pointers:: * Exceptions:: * Calling back to Scheme:: * Input and output:: * Loading programs:: * System interface:: @end menu @node Representation of Scheme objects, Initialization and cleanup, C API reference, C API reference @section Representation of Scheme objects @deftp {Type} ScmObj Scheme objects are uniformly treated as of type @code{ScmObj}, which may be either a tagged pointer to a heap allocated object or a tagged immediate value. Most Scheme objects are heap allocated, and except Scheme pairs, heap allocated Scheme object has a fixed header. We don't go into more details here, but we'll revisit this topic in @ref{Creating new Scheme datatypes}. Certain frequently used Scheme objects, such as boolean values, small exact integers and characters, are encoded in a word without allocating objects in heap, and we call them @emph{immediate values}. Querying the type of a Scheme object and accessing its fields should be done via provided macros or APIs. The user code must treat @code{ScmObj} as an opaque word, since the internal representation may change. The standard way to treat @code{ScmObj} value is (1) check to see if its type matches what you expect, and (2) cast @code{ScmObj} to the actual type and use it, as the following example shows. @example void your_C_function(ScmObj arg) @{ if (SCM_STRINGP(arg)) @{ /* check */ ScmString *s = SCM_STRING(arg); /* cast */ do_whatever_you_like_with_scheme_string(s); @} else @{ SCM_TYPE_ERROR(arg, "a string"); @} @} @end example The @code{SCM_TYPE_ERROR} macro raises an error reporting "a string is required for arg, but got ...". That's a convenient way to report the wrong type argument. See @ref{Exceptions} for more details of reporting errors. Although it is not always checked explicitly, the programmer should keep in mind that C's @code{NULL} is never a valid value for @code{ScmObj}. If a C API requires @code{ScmObj} as an argument, you shouldn't pass @code{NULL} to it. Also if your function returns @code{ScmObj}, you should make sure it will never return @code{NULL}. @end deftp @deftypefn {Macro} ScmObj SCM_OBJ (void *@var{obj}) Typecast @var{obj} to @code{ScmObj}. @var{Obj} must be a pointer to an actual Scheme object. @end deftypefn We describe a few special constant Scheme objects here: @deftypevr {Macro} ScmObj SCM_EOF The Scheme's @code{#} object. @end deftypevr @deftypevr {Macro} ScmObj SCM_UNDEFINED The Gauche's @code{#} object. In Gauche, it is used as a placeholder where the value itself doesn't matter. At the time of writing this document, there's a discussion in the next Scheme standard to define @emph{the `unspecified' value} for this purpose, and it is likely that this value will become such a value. @end deftypevr @deftypevr {Macro} ScmObj SCM_UNBOUND This is a special value only seen in C world, and used to indicate that a variable hasn't got a Scheme value assigned. For example, if a Scheme procedure with an optional argument is defined in C, and no value is passed to the optional argument, @code{SCM_UNBOUND} is given in C world. This value should never be leaked out to Scheme world. @end deftypevr @deftypefn {Macro} int SCM_EOFP (ScmObj @var{obj}) @deftypefnx {Macro} int SCM_UNDEFINEDP (ScmObj @var{obj}) @deftypefnx {Macro} int SCM_UNBOUNDP (ScmObj @var{obj}) Predicates to check whether the given @var{obj} is @code{SCM_EOF}, @code{SCM_UNDEFINED}, or @code{SCM_UNBOUND}, respectively. @end deftypefn @node Initialization and cleanup, Memory allocation and GC, Representation of Scheme objects, C API reference @section Initialization and cleanup This section explains how to initialize Gauche scheme runtime, and how to clean it up. These functions are for the applications that uses Gauche as an embedded Scheme engine; when you're writing Gauche extensions, you don't (and shouldn't) use these functions. @subsubheading Initialization @deftypefun void Scm_Init (const char *@var{signature}) Initializes the runtime. Must be called before any other Gauche API call. To @var{signature}, you should always pass a macro @code{GAUCHE_SIGNATURE}. It is used to check a proper version of Gauche shared library is linked. If you have several version of Gauche libraries (e.g. different encoding or thread configuration), accidentally linking unintended version would cause mysterious runtime crash. If the signature doesn't match the library's, this function exits the process with a message explaining it. @end deftypefun @subsubheading Cleanup and termination @deftypefun void Scm_Exit (int @var{code}) Exits the process with @var{code} as the exit code. Calling @code{Scm_Exit} is the easiest way to terminate Gauche application safely. It runs pending dynamic handlers, registered cleanup handlers (see below), flushes output ports, then calls @code{exit(2)} to exit. Directly calling @code{exit(2)} would skip all those cleanup process. @end deftypefun @deftypefun void Scm_Cleanup (void) Cleans up the Scheme runtime just like @code{Scm_Exit()}, but does not call @code{exit(2)} at the end. This is useful for applications that want to shut down Gauche runtime but need to continue running. Once you call @code{Scm_Cleanup()}, you shouldn't use any other Gauche functions. It is harmless to call @code{Scm_Cleanup()} more than once; it becomes no-op from the second time and after. @end deftypefun @deftypefun void Scm_Panic (const char *@var{msg}, @dots{}) The @var{msg} and other arguments are treated like @code{printf(3)}. Formats and displays the formatted message, then exits the process by calling @code{_exit(2)} with exit code 1. No cleanup is done. This is called when a serious defect is detected in the Gauche runtime and cannot continue normal operation in any way. @end deftypefun @deftypefun void Scm_Abort (const char *@var{msg}) Writes @var{msg} to file descriptor 2, and exits the process by calling @code{_exit(2)} with exit code 1. No cleanup is done. This is the last resort of emergency exit, where you cannot even call @code{malloc} reliably. @end deftypefun @subsubheading Cleanup handlers You can register functions to be called when Gauche runtime is shut down. The registered functions are called by @code{Scm_Exit()} or @code{Scm_Cleanup()} in the reverse order of their registration. @deftypefun {void *} Scm_AddCleanupHandler (void (*@var{h})(void *), void *@var{d}) Adds a function @var{h} to the cleanup handler chain, with an opaque data pointer @var{d}. At the cleanup time, @var{h} is called with @var{d} as the single argument. Returns an opaque handle, which can be passed to DeleteCleanupHandler. @end deftypefun @deftypefun void Scm_DeleteCleanupHandler (void *@var{handle}) Delete cleanup handler. The @var{handle} argument should be an opaque pointer returned from @code{Scm_AddCleanupHandler}. (But it won't complain if other pointer is given; it just does nothing.) @end deftypefun @node Memory allocation and GC, Booleans, Initialization and cleanup, C API reference @section Memory allocation and GC Memories allocated by using the following macros are owned by Gauche runtime and managed by the garbage collector. @subsubheading Allocator macros There's two kind of allocators; ordinary ones and @emph{atomic} ones. Here the term @emph{atomic} means the allocated memory would never contain pointers the collector needs to trace. For example, when you allocate memory for a character string, you can use atomic allocator since the memory won't contain any pointers. It is important to use atomic versions whenever possible. Gauche's GC is conservative, which means if there's a word that looks like a pointer in a live object, the collector assumes it is a pointer and retains the memory chunk pointed by it. If it is not really a pointer, the collector may retain unnecessary memory chunks. It is called false pointers. Telling the collector that a chunk of memory never contains traceable pointer you can reduce the chance of false pointers. It is OK for the atomic memory chunk to contain a pointer, as far as the pointed chunk is reachable by other means, or you can allow the pointed chunk to be collected (like weak pointers). Note: The term @emph{atomic} here probably came from the fact that such a memory chunk is a terminal node, or an atom, in the graph the collector traverses. It has nothing to do with the atomic operations. @deftypefn {Macro} {@var{TYPE} *} SCM_NEW (@var{TYPE}) @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC (@var{TYPE}) Allocates memory for datatype @var{TYPE} and returns its pointer. @code{ATOMIC} version allocates the memory as an atomic chunk. @end deftypefn @deftypefn {Macro} {@var{TYPE} *} SCM_NEW_ARRAY (@var{TYPE}, size_t @var{nelts}) @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC_ARRAY (@var{TYPE}, size_t @var{nelts}) Allocates memory for an array of size @var{nelts} of datatype @var{TYPE}, and returns its pointer. @end deftypefn @deftypefn {Macro} {@var{TYPE} *} SCM_NEW2 (@var{TYPE}, size_t @var{size}) @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC2 (@var{TYPE}, size_t @var{size}) Allocates memory of @var{size} bytes, and returns it as a pointer to the datatype @var{TYPE}. @end deftypefn Note: to allocate a Scheme object for the class that is inheritable from Scheme, you should use @code{SCM_ALLOCATE} macro to do some extra initialization. It is described in @ref{Creating new Scheme datatypes}. You don't need to worry about it as far as you uses provided set of Scheme datatypes, for each of them have a special "make" function such as @code{Scm_MakeString}, @code{Scm_MakeVector}, etc. @subsubheading Garbage collection The garbage collector runs implicitly whenever it is necessary. However, you can run it explicitly by this function: @deftypefun void Scm_GC (void) Triggers full GC. @end deftypefun @subsubheading Finalizers @deftypefun void Scm_RegisterFinalizer (ScmObj @var{obj}, ScmFinalizerProc @var{finalizer}, void *@var{data}) Register the function @var{finalizer} to be called by the garbage collector after the object @var{obj} is determined as dead. The function will be given two arguments, the object and @var{data}. GC works as this: After sweeping phase it has a set of unreachable objects. If an unreachable object has a finalizer, it queues the object in ``to-be-finalized'' list. Gauche's VM checks the queue occasionally and processes them if it's not empty. You should consider a finalizer as an asynchronous callback, much like Scheme-level signal handlers. It is guaranteed to be called when VM state is consistent (thus you can call back Gauche API safely from the finalizer) and outside of GC (thus you can allocate inside the finalizer), but you can't assume much more. If @var{obj} points to another objects that's also being garbage collected, that objects might already be finalized when @var{obj}'s finalizer is called. So you have to make finalizers set the objects to harmless state, and you also have to check the case objects referred from @var{obj} are in such state. You can't choose which thread will call the finalizer. Any thread that allocates may call the finalizer. You can resurrect @var{obj} by storing a pointer to it in some root set. GC doesn't immediately put back @var{obj} to a free memor pool after the finalizer is run; basically it leaves @var{obj}'s fate to the finalizer. If the finalizer doesn't keep references to @var{obj}, then @var{obj} will be reclaimed in @emph{next} GC cycle, for it isn't pointed from live objects. Note that GC unregisters finalizer of @var{obj} when it chains @var{obj} to ``to-be-finalized'' list. So when the finalizer is called, @var{obj} no longer has a finalizer. Last but not least, there's no guarantee that the finalizer is called promptly after @var{obj} lost all live references, or whether it is called at all. There might be an indefinite delay between the point when @var{obj} becomes a garbage and the finalizer is run. You should think finalizers as a safety-net, rather than a guaranteed clean-up mechanism. If your object requires explicit clean-up, ask users to do it explicitly (possibly wrapping it with @code{call-with-*} style procedure). Finalizers are for back up when the user fails to do so. @end deftypefun @deftypefun void Scm_UnregisterFinalizer (ScmObj @var{obj}) @end deftypefun @node Booleans, Numbers, Memory allocation and GC, C API reference @section Booleans @deftypevr {Macro} ScmObj SCM_TRUE @deftypevrx {Macro} ScmObj SCM_FALSE Scheme's @code{#t} and @code{#f}. @end deftypevr @deftypefn {Macro} int SCM_TRUEP (ScmObj @var{obj}) @deftypefnx {Macro} int SCM_FALSEP (ScmObj @var{obj}) Predicates to check whether the given @var{obj} is @code{SCM_TRUE} or @code{SCM_FALSE}, respectively. Note that @code{!SCM_FALSEP(obj)} is different from @code{SCM_TRUEP(obj)}. Since Scheme treats anything other than @code{#f} as a true value, usually what you need is @code{SCM_FALSEP}. You use @code{SCM_TRUEP} only iff you want to make sure the object is @code{#t}. @end deftypefn @deftypefn {Macro} int SCM_BOOLP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is either @code{SCM_FALSE} or @code{SCM_TRUE}. @end deftypefn @deftypefn {Macro} int SCM_BOOL_VALUE (ScmObj @var{obj}) Converts Scheme value to C boolean value. Returns @code{FALSE} iff @var{obj} is @code{#f}. @end deftypefn @deftypefn {Macro} ScmObj SCM_MAKE_BOOL (@var{obj}) Converts C boolean value to a Scheme boolean value. Returns @code{SCM_FALSE} if @var{obj} is @code{FALSE}, and @code{SCM_TRUE} for any other values. @end deftypefn @deftypefn {Macro} int SCM_EQ (ScmObj @var{x}, ScmObj @var{y}) Compares two Scheme objects are the same, in the sense of Scheme's @code{eq?}. You should always use this macro instead of comparing two Scheme objects by @code{==}. @end deftypefn @deftypefun int Scm_EqP (ScmObj @var{x}, ScmObj @var{y}) A function version of @code{SCM_EQ}. @end deftypefun @deftypefun int Scm_EqvP (ScmObj @var{x}, ScmObj @var{y}) Scheme's @code{eqv?}. @end deftypefun @deftypefun int Scm_EqualP (ScmObj @var{x}, ScmObj @var{y}) Scheme's @code{equal?}. Note: this function may call back VM recursively. @end deftypefun @deftypefun int Scm_EqualM (ScmObj @var{x}, ScmObj @var{y}, int @var{mode}) A convenient function to write functions with parameterized equivalence procedure. @var{Mode} may be one of the following constants: @table @code @item SCM_CMP_EQ Compare using @code{eq?} @item SCM_CMP_EQV Compare using @code{eqv?} @item SCM_CMP_EQUAL Compare using @code{equal?} @end table @end deftypefun @node Numbers, Pairs and lists, Booleans, C API reference @section Numbers @menu * Scheme number objects:: * Number predicates:: * Converting C and Scheme numbers:: * Generic arithmetics:: * Subtype-specific number operations:: * Reading and writing numbers:: @end menu @node Scheme number objects, Number predicates, Numbers, Numbers @subsection Scheme number objects @subsubheading C representation of numbers Gauche uses several different structures to represent Scheme numbers. Because of this polymorphic nature, the Scheme numbers are almost always passed as @code{ScmObj}, except special occasions. In Scheme level you usually don't need to think much about different types of numbers, for Gauche automatically converts them as needed. There are C routines that accept generic Scheme numbers like Scheme, but from time to time you need to check the actual type of the number and cast it from @code{ScmObj} to the actual structure. Currently Gauche has the following C-level representations. @table @emph @item Fixnum For small Scheme exact integers (30 or 62 bit signed integer in 32 or 64 bit architectures, respectively), we encode its immediate value into a machine word. @item Bignum If a Scheme exact integer doesn't fit in fixnum, it is represented as a bignum, by a @code{ScmBignum} structure. @item Ratnum A Scheme exact non-integral number is represented as a ratnum, by a @code{ScmRatnum} structure. @item Flonum Scheme real numbers are represented as flonum, by @code{ScmFlonum} structure. @item Compnum Scheme complex numbers are represented as compnum, by a @code{ScmCompnum} structure. @end table It is important to not confuse these @emph{representations} and Scheme numeric hierarchy: A Scheme real number can be represented in either flonum, ratnum, bignum or fixnum, for example. For each possible Scheme numeric type and exactness, the possible C representation is shown in the table below: @example | exact | inexact | --------+----------------------+---------------+ integer |fixnum, bignum |flonum | | | | rational|fixnum, bignum, ratnum|flonum | | | | real |fixnum, bignum, ratnum|flonum | | | | complex |fixnum, bignum, ratnum|flonum, compnum| ________|______________________|_______________| @end example (Note: Exact real and exact complex are supported in a sense that exact rational number is always a real and complex number as well.) @subsubheading Normalized form One Scheme number may be represented by more than one C types; for example, an exact integer can also be represented in ratnum with its denominator as 1. To make things simple and clean, there's one important rule C-routine writers should know: If your routine returns a Scheme number, it must be in a @emph{normalized} form, i.e.: @itemize @bullet @item If the number is an exact integer, it should be either fixnum or bignum; if the value fits in fixnum, it should be fixnum. @item Denominator of ratnum is always greater than 1. That is, the sign of ratnum is the sign of its numerator. @item If the imaginary part of the number is 0.0, it must be in flonum, rather than compnum. @end itemize (Note: here we use the term @emph{normalized} and @emph{denormalized} in the sense that Scheme numbers should be represented in a simplest possible C structure. It is unrelated to the term in IEEE floating point number.) Most C APIs expect normalized numbers, and return normalized one. As far as you're using those APIs, you don't need to care about normalization, or even how the number is represented in Scheme. If you ever need to peek into the representation, or deal with denormalized numbers, see @ref{Subtype-specific number operations}. Carrying around a denormalized Scheme number should be limited for intermediate results, and only when you find the overhead of conversion is a problem. Generally such overhead is negligible compared to other overheads. If you use denormalized numbers, make sure normalize them before passing it back to the rest of the world, or bad things will happen. @subsubheading Conversions and clamping Converting a Scheme number to a C number is a tricky business. It's always possible that the Scheme number you got may not fit into the desired C variable. There are several options you can choose. @itemize @bullet @item Error: Throws an error. @item Clamp: If the Scheme value falls out of the supported range of C variable, use the closest representable value. @item Convert only when possible. If conversion is not possible, use the Scheme value as-is. It is useful to provide a shortcut path to improve performance. @end itemize Some C APIs take @var{clamp} argument to specify the behavior. The value can be one of the following enums. @deftp {Enum} ScmClampMode @table @code @item SCM_CLAMP_ERROR An error is thrown if the given Scheme number doesn't fit to the resulting C number. @item SCM_CLAMP_HI If the given Scheme number is too large to fit in the resulting C number, the largest possible C number in the result type is returned instead. If the given Scheme number is too small, an error is signalled. @item SCM_CLAMP_LO If the given Scheme number is too small to fit in the resulting C number, the smallest possible C number in the result type is returned instead. If the given Scheme number is too large, an error is signalled. @item SCM_CLAMP_BOTH Clamp both sides; with this argument, the API won't throw an out-of-range error. @item SCM_CLAMP_NONE If the given Scheme number is out of the range, no conversion is performed (an extra output argument tells you whether it has happened or not). @end table @end deftp See @var{Scm_GetIntegerClamp} below for a concrete example. @node Number predicates, Converting C and Scheme numbers, Scheme number objects, Numbers @subsection Number predicates @deftypefn {Macro} int SCM_INTEGERP (ScmObj @var{obj}) Returns @code{TRUE} if @var{obj} is a Scheme exact integer; that is, @var{obj} is either a fixnum or a bignum. (The name is somewhat misleading. This is @emph{not} Scheme's @code{integer?}. To check whether @var{obj} is an integer, regardless of exact or inexact, use @code{Scm_IntegerP} below). @end deftypefn @deftypefn {Macro} int SCM_RATIONALP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a Scheme exact rational number; that is, @var{obj} is either one of fixnum, bignum or ratnum. @end deftypefn @deftypefn {Macro} int SCM_REALP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a Scheme real number; that is, @var{obj} is either one of fixnum, bignum, ratnum or flonum. @end deftypefn @deftypefn {Macro} int SCM_NUMBERP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a Scheme number, that is, either a fixnum, bignum, ratnum, flonum, or compnum. @end deftypefn @deftypefun int Scm_IntegerP (ScmObj @var{num}) Returns @code{TRUE} iff @var{num} is (exact or inexact) integer. Note: If @var{num} is a flonum with exponent larger than certain value, @code{Scm_IntegerP} always returns @code{TRUE}, because of its limited precision of mantissa. @end deftypefun @deftypefun int Scm_OddP (ScmObj @var{num}) Returns @code{TRUE} iff a Scheme (exact or inexact) integer is an odd number. This throws an error if @var{num} is not an integer. @end deftypefun @deftypefun int Scm_FiniteP (ScmObj @var{obj}) @deftypefunx int Scm_IniniteP (ScmObj @var{obj}) @deftypefunx int Scm_NanP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a finite number, an infinite number, or a NaN, respectively. It is an error if @var{obj} is not a Scheme number object. @end deftypefun @node Converting C and Scheme numbers, Generic arithmetics, Number predicates, Numbers @subsection Converting C and Scheme numbers @subsubheading Integers @deftypefun ScmObj Scm_MakeInteger (long @var{i}) @deftypefunx ScmObj Scm_MakeIntegerU (u_long @var{i}) @deftypefunx ScmObj Scm_MakeInteger64 (int64_t @var{i}) @deftypefunx ScmObj Scm_MakeIntegerU64 (uint64_t @var{i}) Convert a C integer to a Scheme integer. Always returns a normalized number. @end deftypefun @deftypefun long Scm_GetIntegerClamp (ScmObj obj, int clamp, int *oor) @deftypefunx u_long Scm_GetIntegerUClamp (ScmObj obj, int clamp, int *oor) @deftypefunx int Scm_GetInteger8Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx u_int Scm_GetIntegerU8Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx int Scm_GetInteger16Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx u_int Scm_GetIntegerU16Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx int32_t Scm_GetInteger32Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx uint32_t Scm_GetIntegerU32Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx int64_t Scm_GetInteger64Clamp (ScmObj obj, int clamp, int *oor) @deftypefunx uint64_t Scm_GetIntegerU64Clamp (ScmObj obj, int clamp, int *oor) Convert a Scheme number @var{obj} to a C integer. If @var{obj} is a FLONUM or a RATNUM, they are rounded to the nearest integer. If the number @var{obj} can't be represented by the desired C integer type, the behavior depends on @var{clamp}, which must be one of @code{ScmClampMode}. See above for how out-of-range value can be clamped. If the out-of-range value isn't clamped by @var{clamp} argument, @var{clamp} is not @code{SCM_CLAMP_ERROR}, and @var{oor} is not @code{NULL} then @code{*oor} is set to @code{TRUE} and 0 is returned. Otherwise, an error is thrown. If @var{obj} is not a real number, an error is thrown. @end deftypefun @deftypefun long Scm_GetInteger (ScmObj obj) @deftypefunx u_long Scm_GetIntegerU (ScmObj obj) @deftypefunx int Scm_GetInteger8 (ScmObj obj) @deftypefunx u_int Scm_GetIntegerU8 (ScmObj obj) @deftypefunx int Scm_GetInteger16 (ScmObj obj) @deftypefunx u_int Scm_GetIntegerU16 (ScmObj obj) @deftypefunx int32_t Scm_GetInteger32 (ScmObj obj) @deftypefunx uint32_t Scm_GetIntegerU32 (ScmObj obj) @deftypefunx int64_t Scm_GetInteger64 (ScmObj obj) @deftypefunx uint64_t Scm_GetIntegerU64 (ScmObj obj) These are actually macros, expand into @code{Scm_GetIntegerClamp(obj, SCM_CLAMP_ERROR, NULL)} etc. @end deftypefun @subsubheading Rational numbers @deftypefun ScmObj Scm_MakeRational (ScmObj numer, ScmObj denom) Numerator @var{numer} and denominator @var{denom} must both be exact integers, and @var{denum} must not be zero. This returns a simplest Scheme numebr of @code{numer/denom}, that is, it simplifies the rational number as much as possible; it can even be an integer if @var{numer} is a multiple of @var{denom}. @end deftypefun @deftypefun ScmObj Scm_MakeRatnum (ScmObj numer, ScmObj denom) Numerator @var{numer} and denominator @var{denom} must both be exact integers, and @var{denum} must not be zero. Returns a RATNUM of @code{numer/denom}. This doesn't do any simplification. You should only use this to create an intermediate result, where you'll eventually simplify the result along the way. Whenever you create a number to return to the Scheme world, you should always use @code{Scm_MakeRational} above. @end deftypefun @deftypefun ScmObj Scm_ReduceRational (ScmObj rational) The argument must be a Scheme rational number (exact integer or ratnum). Returns a simplified rational number, either in ratnum or integer. @end deftypefun @deftypefun ScmObj Scm_Numerator (ScmObj n) @deftypefunx ScmObj Scm_Denominator (ScmObj n) The argument must be a Scheme real number (integer, ratnum or flonum). Returns its numerator and denominator, respectively. If the argument is a flonum, it is first converted to an exact number by @code{Scm_Exact}. @end deftypefun @subsubheading Real numbers @deftypefun ScmObj Scm_MakeFlonum (double @var{d}) Returns a flonum from C @code{double} value. @end deftypefun @deftypefun ScmObj Scm_MakeFlonumToNumber (double @var{d}, int exactp) Returns a scheme number corresponds to C @code{double} value @var{d}. Unlike @code{Scm_MakeFlonum}, this routine returns a Scheme exact integer if @code{exactp} is not @code{FALSE}, and @var{d} is an integer. @end deftypefun @deftypefun double Scm_GetDouble (ScmObj @var{obj}) Returns a C @code{double} value of Scheme real number @var{obj} (that means @var{obj} can be a Scheme integer or ratnum as well). If @var{obj} is not a Scheme real number, 0.0 is returned. If @var{obj} is a ratnum, the closest IEEE double floating point number is returned. If @var{obj} is a bignum or ratnum that can't be represented by @code{double}, an infinity (positive or negative, depends on @var{obj}'s sign) is returned. @end deftypefun @deftypefun ScmObj Scm_DecodeFlonum (double d, int *exp, int *sign) Decompose a C double value @var{d} into its mantissa, exponent and sign. Returns the mantissa as a Scheme exact integer, and stores the exponent and the sign (either -1 or 1) in the location pointed by @var{exp} and @var{sign}. It returns Scheme integer since mantissa may not fit in @code{long} on 32bit platforms, and this was created before @code{int64_t} became available universally. On 64bit platforms, returned number is always a fixnum so no allocation occurs. @end deftypefun @deftypefun double Scm_EncodeFlonum (ScmObj mant, int exp, int sign) Inverse of @code{Scm_DecodeFlonum}. Given mantissa (a Scheme exact integer), exponent and sign, returns a C double. @var{sign} must be either -1 or 1, and @var{exp} must be greater than or equal to -1074 and less than or equal to 971. @var{mant} must be between 2^52 (inclusive) and 2^53 (exclusive) if @var{exp} is greater than -1074, or between 0 (inclusive) and 2^52 (exclusive) if @var{exp} is -1074 (denormalized number). The returned value is @code{(@var{sign} * @var{mant} * 2^@var{exp})}. Note that the exponent value is offset by the mantissa scale, so it is not the literal value stored in the exponent field of the IEEE double. @end deftypefun @deftypefun int Scm_FlonumSign (double d) Returns -1 or 1, depending on the sign bit of @var{d}. This differs from @code{Scm_Sign} which returns 0 for both +0.0 and -0.0. @end deftypefun @deftp {Type} ScmHalfFloat 16-bit floating point number (1 bit sign, 5 bit exponent and 10-bit mantissa). This format is sometimes used in the image data. @end deftp @deftypefun double Scm_HalfToDouble (ScmHalfFloat v) @deftypefunx ScmHalfFloat Scm_DoubleToHalf (double d) Convert between half float and C double. If the given double can't be represented in half float, it is mapped to infinities. @end deftypefun @subsubheading Complex numbers @deftypefun ScmObj Scm_MakeComplex (double @var{real}, double @var{imag}) Returns a Scheme number @code{@var{real}+@var{imag}i}. The return value is normalized, so it may be just a flonum if @var{imag} is zero. @end deftypefun @deftypefun ScmObj Scm_MakeComplexPolar (double @var{mag}, double @var{angle}) Returns a Scheme number @code{@var{real}@@@var{imag}i}. The return value is normalized, so it may be just a flonum if the imaginary part of the number is zero. @end deftypefun @deftypefun double Scm_RealPart (ScmObj @var{obj}) @deftypefunx double Scm_ImagPart (ScmObj @var{obj}) @deftypefunx double Scm_Magnitude (ScmObj @var{obj}) @deftypefunx double Scm_Angle (ScmObj @var{obj}) Returns real part, imaginary part, magnitude and angle of a Scheme number @var{obj}, which can be any number. @end deftypefun @deftp {Type} ScmDoubleComplex @deftpx {Type} ScmFloatComplex @deftpx {Type} ScmHalfComplex C-world representation of compelx numbers, using @code{double}, @code{float} and @code{ScmHalfFloat} for each complenent, respectively. @end deftp @deftypefun ScmDoubleComplex Scm_GetDoubleComplex (ScmObj z) @deftypefunx ScmFloatComplex Scm_GetFloatComplex (ScmObj z) @deftypefunx ScmHalfComplex Scm_GetHalfeComplex (ScmObj z) Converts a Scheme number object @var{z} (can be any Scheme number) to C-world complex representation. @end deftypefun @deftypefun ScmObj Scm_DoubleComplexToComplex (ScmDoubleCompex z) @deftypefunx ScmObj Scm_FloatComplexToComplex (ScmFloatCompex z) @deftypefunx ScmObj Scm_HalfComplexToComplex (ScmHalfCompex z) Converts C-world complex representation to a Scheme number object. @end deftypefun @subsubheading Exactness @deftypefun ScmObj Scm_Exact (ScmObj obj) Scheme's @code{exact}. An error is thrown if @var{obj} is not a Scheme number object, an infinity, or a NaN. @end deftypefun @deftypefun ScmObj Scm_Inexact (ScmObj obj) Scheme's @code{inexact}. An error is thrown if @var{obj} is not a Scheme number object. If @var{obj} is out of range where IEEE double can represent, an infinity object is returned. @end deftypefun @node Generic arithmetics, Subtype-specific number operations, Converting C and Scheme numbers, Numbers @subsection Generic arithmetics @subsubheading Exact integer operations The following routines operates on Scheme exact integers. If the given @code{ScmObj} argument is not a Scheme exact integer, an error is signalled. For bitwise routines, an integer is regarded in 2's complement form in case if it is negative. @deftypefun ScmObj Scm_LogAnd (ScmObj @var{x}, ScmObj @var{y}) @deftypefunx ScmObj Scm_LogIor (ScmObj @var{x}, ScmObj @var{y}) @deftypefunx ScmObj Scm_LogXor (ScmObj @var{x}, ScmObj @var{y}) @deftypefunx ScmObj Scm_LogNot (ScmObj @var{x}) Bitwise operations. Arguments must be Scheme exact integers. Returns a Scheme exact integer, each bit of which is logical @emph{and}, @emph{inclusive or}, @emph{exclusive or}, and @emph{not} of the corresponding bit(s) of the argument(s). Correspond to Scheme @code{logand}, @code{logior}, @code{logxor} and @code{lognot}, respectively. @end deftypefun @deftypefun ScmObj Scm_Ash (ScmObj @var{x}, int @var{cnt}) Arithmetic left shift of a Scheme exact integer @var{x} by @var{cnt} bits. If @var{cnt} is negative, it it shifts to right by @var{-cnt} bits. Corresponds to Scheme @code{ash}. @end deftypefun @deftypefun int Scm_LogTest (ScmObj @var{x}, ScmObj @var{y}) Returns @code{FALSE} if bitwise @emph{and} of two Scheme exact integers @var{x} and @var{y} yields zero, or @var{TRUE} otherwise. Corresponds to Scheme @code{logtest}. @end deftypefun @deftypefun int Scm_LogBit (ScmObj @var{x}, int @var{b}) Returns @code{TRUE} or @code{FALSE} if @var{b}-th bit of a Scheme exact integer @var{x} is set or not set, respectively. 0-th bit is the least significant bit. Corresponds to Scheme @code{logbit}. @end deftypefun @subsubheading General operations @deftypefun ScmObj Scm_Abs (ScmObj @var{num}) Returns the distance between 0 and @var{num}, which can be any number (including complex numbers). Exactness of @var{num} is preserved. An error is signalled if @var{num} is not a Scheme number. @end deftypefun @deftypefun int Scm_Sign (ScmObj @var{num}) @var{Num} must be a real number. Returns -1, 0, or 1 when @var{num} is less than, equal to, or greater than zero, respectively. If @var{num} is not a Scheme real number, an error is signalled. Note that this returns 0 for negative zero @code{-0.0}. To check the sign of zero, use @code{Scm_FlonumSign}. @end deftypefun @deftypefun ScmObj Scm_Negate (ScmObj @var{num}) @end deftypefun @deftypefun ScmObj Scm_Reciprocal (ScmObj @var{num}) @end deftypefun @deftypefun ScmObj Scm_Add (ScmObj @var{arg1}, ScmObj @var{arg2}) @deftypefunx ScmObj Scm_Sub (ScmObj @var{arg1}, ScmObj @var{arg2}) @deftypefunx ScmObj Scm_Mul (ScmObj @var{arg1}, ScmObj @var{arg2}) @deftypefunx ScmObj Scm_Div (ScmObj @var{arg1}, ScmObj @var{arg2}) @end deftypefun @deftypefun ScmObj Scm_Quotient (ScmObj @var{arg1}, ScmObj @var{arg2}, ScmObj *@var{rem}) Returns @code{(quotient @var{arg1} @var{arg2})}. If @var{rem} is not NULL, the remainder is stored in @code{*rem}. @end deftypefun @deftypefun ScmObj Scm_Modulo (ScmObj @var{arg1}, ScmObj @var{arg2}, int remainderp) @end deftypefun @deftypefun ScmObj Scm_Expt (ScmObj @var{x}, ScmObj @var{y}) @end deftypefun @deftypefun int Scm_NumEq (ScmObj @var{x}, ScmObj @var{y}) Returns @code{TRUE} iff two Scheme numbers are equal (same as Scheme's @code{=}). @end deftypefun @deftypefun int Scm_NumCmp (ScmObj @var{x}, ScmObj @var{y}) Returns @code{-1}, @code{0}, or @code{1}, where @code{x < y}, @code{x = y} or @code{x > y}, respectively. Arguments must be Scheme real numbers. @end deftypefun @deftypefun void Scm_MinMax (ScmObj @var{arg0}, ScmObj @var{args}, ScmObj *@var{min}, ScmObj *@var{max}) @end deftypefun @deftp {Enum} ScmRoundMode @example enum ScmRoundMode @{ SCM_ROUND_FLOOR, SCM_ROUND_CEIL, SCM_ROUND_TRUNC, SCM_ROUND_ROUND @}; @end example @end deftp @deftypefun ScmObj Scm_Round (ScmObj @var{num}, int @var{mode}) Round a real number @var{num} to an integer. @end deftypefun @node Subtype-specific number operations, Reading and writing numbers, Generic arithmetics, Numbers @subsection Subtype-specific number operations @menu * Fixnum operations:: * Bignum operations:: * Flonum operations:: * Compnum operations:: @end menu @node Fixnum operations, Bignum operations, Subtype-specific number operations, Subtype-specific number operations @subsubsection Fixnum operations The following macros treat fixnums specifically. In most cases you should use generic versions above, so that you don't need to care about difference between fixnums and bignums, and normalization. However, if you know your Scheme number is mostly small and you need speed, these macros will be handy. @deftypefn {Macro} int SCM_INTP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a fixnum. See @code{SCM_INTEGERP} (@pxref{Number predicates}), to see if @var{obj} is an exact integer (either a fixnum or a bignum). @end deftypefn @deftypevr {Macro} int SCM_SMALL_INT_SIZE Number of bits (excluding sign bit) of an integer representable in fixnum. Currently it is 29 and 61 for 32 and 64-bit architectures, respectively. @end deftypevr @deftypevr {Macro} long SCM_SMALL_INT_MAX @deftypevrx {Macro} long SCM_SMALL_INT_MIN Maximum and minimum integer values representable in fixnum. @end deftypevr @deftypefn {Macro} int SCM_SMALL_INT_FITS (long @var{k}) Returns @code{TRUE} iff @var{k} fits in fixnum. @end deftypefn @deftypefn {Macro} long SCM_INT_VALUE (ScmObj @var{fixnum}) Extracts (unboxes) an integer value from @var{fixnum}. You have to check whether @var{fixnum} is a fixnum or not before applying this. @end deftypefn @deftypefn {Macro} ScmObj SCM_MAKE_INT (long @var{i}) Boxes an integer value @var{i} to a fixnum. You have to make sure @var{i} is in the range representable by fixnum. @end deftypefn @deftypefn {Macro} int SCM_UINTP (ScmObj @var{obj}) A convenience macro to check if @var{obj} is a fixnum @emph{and} non-negative. @end deftypefn @node Bignum operations, Flonum operations, Fixnum operations, Subtype-specific number operations @subsubsection Bignum operations Again, it should generally be avoided to use bignums explicitly; generic integer routines should take care of most cases. A bignum keeps the absolute value in array of @code{u_long}s, least significant word first. The sign is kept separately. It also keeps the number of words used. There's one more constraint about normalization. Normalized bignum uses only as many words as necessary to represent the given number. That is, the most significant word should never be zero for normalized bignums. You may see denormalized bignums only in limited occasions, such as the intermediate results. Denormalized bignums should never be leaked out to other APIs or to the Scheme world. @deftypefn {Macro} int SCM_BIGNUMP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a bignum. @end deftypefn @deftypefn {Macro} ScmBignum* SCM_BIGNUM (ScmObj @var{bignum}) Cast @var{bignum} to @code{ScmBignum*}. @end deftypefn @deftypefn {Macro} int SCM_BIGNUM_SIZE (ScmObj @var{bignum}) Returns the number of words used in the bignum. @end deftypefn @deftypefn {Macro} int SCM_BIGNUM_SIGN (ScmObj @var{bignum}) Returns the sign (-1 or 1) of the bignum. If @var{bignum} is denormalized and contains zero, this macro returns 0. @end deftypefn The following APIs are for internal use, and only available when you include @file{gauche/bignum.h}. You should need these only if you're implementing some basic bignum arithmetics. @deftypefun ScmObj Scm_MakeBignumFromSI (long @var{val}) @deftypefunx ScmObj Scm_MakeBignumFromUI (u_long @var{val}) Converts C @code{long} or @code{u_long} value to a bignum. The result is always a bignum, even when @var{val} can fit in fixnum (i.e. the result can be denormalized). @end deftypefun @deftypefun ScmObj Scm_MakeBignumFromUIArray (int @var{sign}, u_long *@var{values}, int @var{size}) Creates a (possibly denormalized) bignum from the given @code{u_long} array of length @var{size}. @var{Size} must be greater than 0. The first word @var{Values} is for the least significant word. If @var{sign} is not zero, its sign determines the sign of the bignum, and @code{values} are taken as absolute values. If @var{sign} is zero, this routine assumes @code{values} contains 2's complement form of the integer. @end deftypefun @deftypefun ScmObj Scm_MakeBignumFromDouble (double @var{val}) Returns a (possible denormalized) bignum that represents the integral part of @var{val}. @end deftypefun @deftypefun {ScmBignum *} Scm_MakeBignumWithSize (int @var{size}, u_long @var{init}) @end deftypefun @deftypefun ScmObj Scm_BignumCopy (ScmBignum *@var{bignum}) Copy the given @var{bignum}. The return value can be denormalized if @var{bignum} is denormalized. @end deftypefun @deftypefun ScmObj Scm_NormalizeBignum (ScmBignum *@var{bignum}) Returns a normalized Scheme integer from the given bignum. That is, the returned value can be fixnum if @var{bignum} is small enough. This also adjust the size of bignum if it contains leading zero words. The routine that returns the number to the outside world should always use this routine to ensure a denormalized bignum would never be leaked out. @end deftypefun @deftypefun long Scm_BignumToSI (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor}) @deftypefunx u_long Scm_BignumToUI (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor}) Converts a bignum to C @code{long} and @code{u_long}, respectively. The behavior when @var{bignum} is out of range is determined by @var{clamp} argument. The @code{bignum} argument must be a normalized bignum. @end deftypefun @deftypefun ScmInt64 Scm_BignumToSI64 (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor}) @deftypefunx ScmUInt64 Scm_BignumToUI64 (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor}) 64-bit integer version of @code{Scm_BignumToSI} and @code{Scm_BignumToUI}. The @code{bignum} argument must be a normalized bignum. @end deftypefun @deftypefun double Scm_BignumToDouble (ScmBignum *@var{bignum}) Converts a bignum to C @code{double} value. The @code{bignum} argument must be a normalized bignum. @end deftypefun @deftypefun ScmObj Scm_BignumNegate (ScmBignum *@var{bignum}) Returns @code{-@var{bignum}}. The argument may be denormalized. The returned value is a normalized Scheme integer. @end deftypefun @deftypefun int Scm_BignumCmp (ScmBignum *@var{bx}, ScmBignum *@var{by}) Compares two normalized bignums. Returns -1 if @code{@var{bx} < @var{by}}, 0 if @code{@var{bx} = @var{by}}, and 1 if @code{@var{bx} > @var{by}}. @end deftypefun @deftypefun int Scm_BignumAbsCmp (ScmBignum *@var{bx}, ScmBignum *@var{by}) Compares absolute values of two normalized bignums. Returns -1 if @code{abs(@var{bx}) < abs(@var{by})}, 0 if @code{abs(@var{bx}) = abs(@var{by})}, and 1 if @code{abs(@var{bx}) > abs(@var{by})}. @end deftypefun @deftypefun ScmObj Scm_BignumAdd (ScmBignum *@var{bx}, ScmBignum *@var{by}) @deftypefunx ScmObj Scm_BignumSub (ScmBignum *@var{bx}, ScmBignum *@var{by}) @deftypefunx ScmObj Scm_BignumMul (ScmBignum *@var{bx}, ScmBignum *@var{by}) Returns @code{(+ @var{bx} @var{by})}, @code{(- @var{bx} @var{by})}, and @code{(* @var{bx} @var{by})}, respectively. Both argument should be normalized. The return value is a normalized Scheme integer. @end deftypefun @deftypefun ScmObj Scm_BignumAddSI (ScmBignum *@var{bx}, long @var{y}) @deftypefunx ScmObj Scm_BignumSubSI (ScmBignum *@var{bx}, long @var{y}) @deftypefunx ScmObj Scm_BignumMulSI (ScmBignum *@var{bx}, long @var{y}) Returns @code{(+ @var{bx} @var{y})}, @code{(- @var{bx} @var{y})}, and @code{(* @var{bx} @var{y})}, respectively. @var{Bx} should be normalized. The return value is a normalized Scheme integer. @end deftypefun @deftypefun ScmObj Scm_BignumDivRem (ScmBignum *@var{dividend}, ScmBignum *@var{divisor}) Returns a cons of quotient and remainder of two bignums. Both bignums should be normalized. Returns normalized numbers. @end deftypefun @deftypefun ScmObj Scm_BignumDivSI (ScmBignum *@var{dividend}, long @var{divisor}, long *@var{remainder}) Returns a quotient of @var{dividend} divided by @var{divisor}. The remainder is stored in *@var{remainder}. @var{Dividend} should be normalized. Returns normalized number. @end deftypefun @node Flonum operations, Compnum operations, Bignum operations, Subtype-specific number operations @subsubsection Flonum operations @deftypefn {Macro} int SCM_FLONUMP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a flonum. Note: in most cases, you may want to use @code{SCM_REALP} instead of this; @code{Scm_GetDouble} can treat integers transparently. @end deftypefn @deftypefun ScmObj Scm_DecodeFlonum (double @var{d}, int *@var{pexp}, int *@var{psign}) Decompose C double value @var{d} into its mantissa, exponent and sign values. The mantissa is returned as a Scheme integer (since it is 53bits in IEEE double-precision floating format, we cannot return it as C integer portably). Values of exponent and sign (-1 or 1) are stored in @code{*pexp} and @code{psign}. Two special cases: If @var{d} is infinity, @code{SCM_TRUE} is returned, and @code{*psign} contains its sign (-1 or 1). If @var{d} is @code{NaN}, @code{SCM_FALSE} is returned. @end deftypefun @node Compnum operations, , Flonum operations, Subtype-specific number operations @subsubsection Compnum operations @deftypefn {Macro} int SCM_COMPLEXP (ScmObj @var{obj}) Returns @code{TRUE} iff @var{obj} is a compnum. @end deftypefn @deftypefn {Macro} double SCM_COMPLEX_REAL (ScmObj @var{compnum}) @deftypefnx {Macro} double SCM_COMPLEX_IMAG (ScmObj @var{compnum}) Access to real and imaginary part of the complex number @var{compnum}, which must be a compnum. @end deftypefn @deftypefun ScmObj Scm_MakeCompnum (double @var{real}, double @var{imag}) Returns a (possibly denormalized) compnum, whose real part is @var{real} and imaginary part is @var{imag}. @end deftypefun @node Reading and writing numbers, , Subtype-specific number operations, Numbers @subsection Reading and writing numbers @deftypefun ScmObj Scm_StringToNumber (ScmString *str, int radix, u_long flags) Scheme's @code{string->number}. Parse external representation of a Scheme number in @var{str}. If the argument can't be parsed as a number, @code{SCM_FALSE} is returned. The @var{radix} argument specifies the default radix. If it isn't between between 2 to 36, inclusive, @code{SCM_FALSE} is returned. This setting may be overridden if the input contains explicit radix prefix (@code{#x} etc.) The @var{flags} argument can be a logical or of the following bitmasks: @table @code @item SCM_NUMBER_FORMAT_EXACT @itemx SCM_NUMBER_FORMAT_INEXACT If no explicit exactness prefix is in input, force the input to be parsed as an exact/inexact number. If neither of these flags is given, and no explicit exactness prefix is in input, the exactness is automatically deduced as the same rule as Gauche's reader---that is, if the input contains a decimal point and/or exponential notation, or the input is non-real complex number, it becomes inexact; otherwise, it becomes exact. @item SCM_NUMBER_FORMAT_STRICT_R7RS Reject input that's not strictly follow R7RS syntax. @item SCM_NUMBER_FORMAT_ALT_RADIX Do not allow @code{#@var{n}R} style radix prefix. @end table @end deftypefun @deftypefun ScmObj Scm_NumberToString (ScmObj obj, int radix, u_long flags) Scheme's @code{number->string}. An error is thrown if @var{obj} isn't a number, or @var{radix} isn't between 2 and 10. The @var{flags} argument can be a logical or of the following bitmasks: @table @code @item SCM_NUMBER_FORMAT_USE_UPPER Use uppercase letters for digits greater than 10. The default is to use lower case. @item SCM_NUMBER_SHOW_PLUS Prepend @code{+} sign in positive number. @item SCM_NUMBER_FORMAT_ALT_RADIX Add a radix prefix. @item SCM_NUMBER_FORMAT_ROUND_NOTATIONAL Use notational decimal rounding. See the @code{format} entry of Gauche's reference manual about notational rounding. @end table @end deftypefun @node Pairs and lists, Symbols, Numbers, C API reference @section Pairs and lists @menu * Pair type and null:: * List constructors:: * List predicates:: * List accessors and modifiers:: * List utilities:: @end menu @node Pair type and null, List constructors, Pairs and lists, Pairs and lists @subsection Pair type and null @deftp {Scheme Object} ScmPair Represents a Scheme pair. It exposes @code{car} and @code{cdr} fields, but they should always be accessed via accessor functions or macros. Some pairs are special and may have hidden fields. Also, Gauche may impose a special alignment requirements for pairs, so you should never define a variable of type ScmPair in your C code. Instead, use the constructor API such as @code{Scm_Cons()} to get an instance of ScmPair. @example @{ /* Don't do this, or a devil comes out of your nose. */ ScmPair foo = @{ ... @}; /* Instead, you can do this: */ ScmObj foo = Scm_Cons(...); @} @end example @end deftp @deftypevr {Scheme Constant} ScmObj SCM_NIL A Scheme empty list, @code{()}. @end deftypevr @node List constructors, List predicates, Pair type and null, Pairs and lists @subsection List constructors @deftypefun ScmObj Scm_Cons (ScmObj car, ScmObj cdr) Allocates and returns a fresh pair of @var{car} and @var{cdr}. @end deftypefun @deftypefun ScmObj Scm_Acons (ScmObj caar, ScmObj cadr, ScmObj cdr) Scheme's @code{acons}. Returns @code{(cons (cons caar cadr) cdr)}. @end deftypefun @deftypefun ScmObj Scm_List (ScmObj elt, @dots{}, NULL) Returns a Scheme list of @var{elt}, @dots{}. The C argument must be terminated by NULL (note that NULL can never be a valid Scheme value). @end deftypefun @deftypefun ScmObj Scm_Conses (ScmObj elt, @dots{}, NULL) Scheme's @code{cons*}. @end deftypefun @deftypefun ScmObj Scm_VaList (va_list elts) @deftypefunx ScmObj Scm_VaCons (va_list elts) Vararg version of @code{Scm_List} and @code{Scm_Conses}. @end deftypefun @deftypefun ScmObj Scm_ArrayToList (ScmObj *elts, ScmSize nelts) Takes a C array of @code{ScmObj}s of size @var{nelts}, and returns a Scheme list that has @var{elts} as its elements. @end deftypefun @deftypefun ScmObj Scm_ArrayToListWithTail (ScmObj *elts, ScmSize nelts, ScmObj tail) Takes a C array of @code{ScmObj}s of size @var{nelts}, and creates a Scheme list that has @var{elts} as its elements, and has @var{tail} in its tail. @end deftypefun @deftypefun ScmObj *Scm_ListToArray (ScmObj list, ScmSize *nelts, ScmObj *store, int alloc) Converts a Scheme list to a C array of @code{ScmObj*}. An error is thrown if @var{list} is not a proper list. You can pass in a storage to store the result, or let the function allocate. If @var{store} is NULL, the function always allocate an @code{ScmObj*} array. The size of the array is stored in @code{*nelts}. If @var{store} is not NULL, it must point to a writable memory of at least @code{sizeof(ScmObj) * (*nelts)}. If the length of @var{list} is smaller than or equal to @code{*nelts}, the result is stored in @code{*store}, and @code{store} is returned. The value of @code{*nelts} is adjusted to contain the actual number of elements. If the length of @var{list} is greater than @var{*nelts}, the behavior depends on the @code{alloc} flag. If it is @code{FALSE}, an error is thrown. Otherwise, a new storage is allocated, filled, and returned. The value of @code{*nelts} is ajusted to contain the actual number of elements. @end deftypefun @deftypefn {Macro} ScmObj SCM_LIST1 (ScmObj a) @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b) @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b, c) @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b, c, d) @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b, c, d, e) Convenience macros to create a Scheme list of length 1 to 5. @end deftypefn @deftypefun ScmObj Scm_MakeImmutablePair (ScmObj car, ScmObj cdr) Creates and returns an immutable pair. Immutable pair is almost indistinguishable from ordinary (mutable) pairs, except that it returns false for @code{Scm_ImmutablePairP()}, and it raises an error when its car or cdr is tried to be modified. Immutable pairs take up more storage than ordinary pairs. Unless you have a specific reason to use immutable pairs, you don't need to worry about them. @end deftypefun @deftypefn {Macro} void SCM_APPEND1 (ScmObj head, ScmObj tail, ScmObj obj) This macro captures an idiom of constructing a list from left to right. The @var{head} and @var{tail} arguments must be a variable, initialized by @code{SCM_NIL}. This macro works like this: @itemize @bullet @item If @var{head} is @code{SCM_NIL}, create a new pair whose car is @var{obj}, and make @var{head} and @var{tail} both point to the pair. @item Otherwise, create a new pair whose car is @var{obj}, set the cdr of @var{tail} to the new pair, then set @var{tail} to point the new pair. @end itemize That is, @var{head} points to the first pair of the constructed list, and @var{tail} points to the last pair of the constructed list. @end deftypefn @deftypefn {Macro} void SCM_APPEND (ScmObj head, ScmObj tail, ScmObj lis) This macro captures an idiom of constructing a list from left to right. Similar to @code{SCM_APPEND1}, but @var{lis} must be a proper Scheme list. It appends a list @var{lis} to the cdr of @var{tail} and make @var{tail} point to the last pair of @var{lis}. In other words, it splices @var{lis}. @end deftypefn @node List predicates, List accessors and modifiers, List constructors, Pairs and lists @subsection List predicates @deftypefn {Macro} int SCM_NULLP (ScmObj obj) Return a true value iff @var{obj} is @code{SCM_NIL}. @end deftypefn @deftypefn {Macro} int SCM_PAIRP (ScmObj obj) Return a true value iff @var{obj} is a Scheme pair. Note: If @var{obj} is a lazy pair, it is forced by this macro. So once this macro returns true, you can assume @var{obj} is @code{ScmPair}. @end deftypefn @deftypefn {Macro} int SCM_LISTP (ScmObj obj) Returns a true value iff @var{obj} is a Scheme pair or a Scheme emptylist. If @var{obj} is a lazy pair, it is forced. Note that this doesn't check if @var{obj} is a proper list. @end deftypefn @deftypefn {Macro} int SCM_PROPER_LIST_P (ScmObj obj) @deftypefnx {Macro} int SCM_DOTTED_LIST_P (ScmObj obj) @deftypefnx {Macro} int SCM_CIRCULAR_LIST_P (ScmObj obj) Returns a true value iff @var{obj} is a Scheme proper list, a Scheme dotted list, or a Scheme circular list, respectively. These macros traverses the spine of @var{obj}, so all the lazy pairs are forced. Notably, if @var{obj} is an infinite lazy sequence these macros never returns. @end deftypefn @deftypefun int Scm_ImmutablePairP (ScmObj obj) Returns a true value if @var{obj} is a pair and immutable. @end deftypefun @node List accessors and modifiers, List utilities, List predicates, Pairs and lists @subsection List accessors and modifiers @deftypefun ScmObj Scm_Car (ScmObj obj) @deftypefunx ScmObj Scm_Cdr (ScmObj obj) @deftypefunx ScmObj Scm_Caar (ScmObj obj) @deftypefunx ScmObj Scm_Cadr (ScmObj obj) @deftypefunx ScmObj Scm_Cdar (ScmObj obj) @deftypefunx ScmObj Scm_Cddr (ScmObj obj) Scheme's @code{car} etc. If @var{obj} isn't a pair, an error is thrown. @end deftypefun @deftypefun ScmObj Scm_SetCar (ScmObj obj) @deftypefunx ScmObj Scm_SetCdr (ScmObj obj) Scheme's @code{set-car!} and @code{set-cdr!}. If @var{obj} isn't a mutable pair, an error is thrown. @end deftypefun @deftypefun ScmObj Scm_ListRef (ScmObj list, ScmSmallInt i, ScmObj fallback) @end deftypefun @deftypefun ScmObj Scm_ListTail (ScmObj list, ScmSmallInt i, ScmObj fallback) @end deftypefun @deftypefun ScmObj Scm_LastPair (ScmObj list) @end deftypefun @deftypefn {Macro} void SCM_FOR_EACH (ScmObj var, ScmObj list) body This is a convenience macro to traverse a Scheme list. It is expanded into something like this: @example for (var = list; SCM_PAIRP(var); var = Scm_Cdr(var)) body @end example That is, @var{body} is executed while @var{var} holds each pair in the list. @end deftypefn @node List utilities, , List accessors and modifiers, Pairs and lists @subsection List utilities @deftypefun ScmSize Scm_Length (ScmObj obj) If @var{obj} is a Scheme proper list, returns its length. If @var{obj} is an emptylist, the length is 0. If @var{obj} is a Scheme dotted list (which includes a non-pair, non-emptylist object), returns SCM_LIST_DOTTED, which is a negative integer constant. If @var{obj} is a Scheme circular list, returns @code{SCM_LIST_CIRCULAR}, which is a nevative integer constant. @end deftypefun @deftypefun ScmObj Scm_CopyList (ScmObj list) Scheme's @code{copy-list}. Return a fresh copy of a Scheme proper or dotted list @var{list}. If @var{list} is circular, an error is thrown. @end deftypefun @deftypefun ScmObj Scm_MakeList (ScmSmallInt len, ScmObj fill) Scheme's @code{make-list}. Creates a fresh @var{len}-element list, whose elements are all @var{fill}. @end deftypefun @deftypefun ScmObj Scm_Append2 (ScmObj list, ScmObj obj) @deftypefunx ScmObj Scm_Append2X (ScmObj list, ScmObj obj) Concatenate @var{obj} after a Scheme proper list @var{list}. @code{Scm_Append2X} may destructively modify @var{list}. @end deftypefun @deftypefun ScmObj Scm_Append (ScmObj args) This is rather Scheme's @code{concatenate}. Elements of @var{args} must be proper lists except the last one. @end deftypefun @deftypefun ScmObj Scm_Reverse (ScmObj list) @deftypefunx ScmObj Scm_ReverseX (ScmObj list) @end deftypefun @deftypefun ScmObj Scm_Reverse2 (ScmObj list, ScmObj tail) @deftypefunx ScmObj Scm_Reverse2X (ScmObj list, ScmObj tail) @end deftypefun @deftypefun ScmObj Scm_Memq (ScmObj obj, ScmObj list) @deftypefunx ScmObj Scm_Memv (ScmObj obj, ScmObj list) Scheme's @code{memq} and @code{memv}. These won't throw an error, as long as @var{list} doesn't contain a lazy pair. @end deftypefun @deftypefun ScmObj Scm_Member (ScmObj obj, ScmObj list, int cmpmode) Generalized member. The @var{cmpmode} argument must be either one of @code{SCM_CMP_EQ}, @code{SCM_CMP_EQV}, or @code{SCM_CMP_EQUAL}, specifying the comparison should be done by @code{eq?}, @code{eqv?}, or @code{equal}. @end deftypefun @deftypefun ScmObj Scm_Assq (ScmObj obj, ScmObj list) @deftypefunx ScmObj Scm_Assv (ScmObj obj, ScmObj list) Scheme's @code{assq} and @code{assv}. These won't throw an error, as long as @var{list} doesn't contain a lazy pair. Non-pair elements in @var{list} are ignored. @end deftypefun @deftypefun ScmObj Scm_Assoc (ScmObj obj, ScmObj list, int cmpmode) Generalized assoc. The @var{cmpmode} argument must be either one of @code{SCM_CMP_EQ}, @code{SCM_CMP_EQV}, or @code{SCM_CMP_EQUAL}, specifying the comparison should be done by @code{eq?}, @code{eqv?}, or @code{equal}. @end deftypefun @deftypefun ScmObj Scm_Delete (ScmObj obj, ScmObj list, int cmpmode) @deftypefunx ScmObj Scm_DeleteX (ScmObj obj, ScmObj list, int cmpmode) @end deftypefun @deftypefun ScmObj Scm_AssocDelete (ScmObj obj, ScmObj list, int cmpmode) @deftypefunx ScmObj Scm_AssocDeleteX (ScmObj obj, ScmObj list, int cmpmode) @end deftypefun @deftypefun ScmObj Scm_DeleteDuplicates (ScmObj list, int cmpmode) @deftypefunx ScmObj Scm_DeleteDuplicatesX (ScmObj list, int cmpmode) @end deftypefun @deftypefun ScmObj Scm_MonotonicMerge (ScmObj sequences) @end deftypefun @node Symbols, Glocs, Pairs and lists, C API reference @section Symbols @deftp {Scheme Object} ScmSymbol Represents a Scheme symbol. Unlike Common Lisp, Gauche's symbol is merely an interned string. It keeps no other information than its name. Global binding is realized by modules that associate a symbol to a @emph{gloc}, which keeps the global value, defined modules, etc. @end deftp @deftypevr {Scheme Class Constant} {ScmClass *} SCM_CLASS_SYMBOL A constant pointer pointing Gauche's @code{} class. @end deftypevr @deftypefn {Macro} {ScmSymbol *} SCM_SYMBOL (ScmObj @var{obj}) Converts @code{ScmObj} to the pointer to a symbol. @end deftypefn @deftypefn {Macro} int SCM_SYMBOLP (ScmObj @var{obj}) @code{TRUE} iff @var{obj} is a symbol. Note: In recent Gauche, keywords are a subclass of symbols, and satisfies @code{SCM_SYMBOLP} too. @end deftypefn @deftypefn {Macro} {ScmString *} SCM_SYMBOL_NAME (ScmObj @var{symbol}) Returns the name of the symbol. @end deftypefn @deftypefun ScmObj Scm_Intern (ScmString *@var{name}) Creates and returns a symbol whose name is @var{name} and registers it in the internal hash table. If there's already a symbol with @var{name}, new symbol isn't created, and the existing symbol is returned. @end deftypefun @deftypefun ScmObj Scm_Gensym (ScmString *@var{prefix}) Creates and returns an uninterned symbol, whose name is generated from @var{prefix} followed by some numbers. @var{Prefix} can be @code{NULL}, in which case the default prefix is used. @end deftypefun @deftypefn {Macro} ScmObj SCM_INTERN (const char *@var{name}) A convenience macro to create a symbol with the name @var{name}. Implemented as follows: @example Scm_Intern(SCM_STRING(SCM_MAKE_STR_IMMUTABLE(cstr))) @end example @end deftypefn @node Keywords, , Symbols, Symbols @section Keywords Keywords are almost the same as symbols; in fact, @code{ScmKeyword} is just a type alias of @code{ScmSymbol}. They do have different runtime types (@code{SCM_CLASS_KEYWORD} vs @code{SCM_CLASS_SYMBOL}), but in recent Gauche the keyword class is a subclass of the symbol class by default. @deftp {Scheme Object} ScmKeyword Represents the Scheme keyword objects. @end deftp @deftypevr {Scheme Class Constant} {ScmClass *} SCM_CLASS_KEYWORD A constant pointer pointing Gauche's @code{} class. @end deftypevr @deftypefn {Macro} {ScmKeyword *} SCM_KEYWORD (ScmObj @var{obj}) Converts @code{ScmObj} to the pointer to a keyword. @end deftypefn @deftypefn {Macro} int SCM_KEYWORDP (ScmObj @var{obj}) @code{TRUE} iff @var{obj} is a keyword. @end deftypefn @deftypefn {Macro} {ScmString *} SCM_KEYWORD_NAME (ScmObj @var{keyword}) Returns the name of the keyword. @end deftypefn @deftypefun ScmObj Scm_MakeKeyword (ScmString *@var{name}) Scheme's @code{make-keyword}. Returns a keyword whose name is @var{name}. Note that preceding @code{:} is not a part of the keyword name. @end deftypefun @deftypefun ScmObj Scm_GetKeyword (ScmObj @var{key}, ScmObj @var{list}, ScmObj @var{fallback}) Scheme's @code{get-keyword}. This is actually a misnomer; @var{key} doesn't need to be a keyword, but can be any object. @end deftypefun @deftypefun ScmObj Scm_DeleteKeyword (ScmObj @var{key}, ScmObj @var{list}) Scheme's @code{delete-keyword}. This is actually a misnomer; @var{key} doesn't need to be a keyword, but can be any object. @end deftypefun @deftypefun ScmObj Scm_DeleteKeywordX (ScmObj @var{key}, ScmObj @var{list}) Scheme's @code{delete-keyword!}. @var{list} may be modified desctructively. This is actually a misnomer; @var{key} doesn't need to be a keyword, but can be any object. @end deftypefun @deftypefn {Macro} ScmObj SCM_MAKE_KEYWORD (const char *@var{name}) A convenience macro to create a keyword from C string @var{name}. Implemented as follows: @example Scm_MakeKeyword(SCM_STRING(SCM_MAKE_STR_IMMUTABLE(name))) @end example @end deftypefn @deftypefn {Macro} ScmObj SCM_GET_KEYWORD (const char *@var{name}, ScmObj @var{list}, ScmObj @var{fallback}) A convenience macro to search a value marked by a keyword whose name is specified by C string @var{name}. Implemented as follows: @example Scm_GetKeyword(SCM_MAKE_KEYWORD(name), list, fallback) @end example @end deftypefn @node Glocs, Modules, Symbols, C API reference @section Glocs A gloc, or global location, is a structure to keep the global value. A module maps a symbol to a gloc. Glocs are not directly used in the Scheme world (except in some introspection features), and even in the C world you don't usually need to deal with them. To get/set the value of a global variable, you can use @code{Scm_GlobalVariableRef} and @code{Scm_Define}, respectively (@pxref{Modules}). @deftp {Scheme Object} ScmGloc Represents a gloc object. @end deftp @deftypevr {Scheme Class Constant} {ScmClass *} SCM_CLASS_GLOC A constant pointer pointing Gauche's @code{} class. @end deftypevr @deftypefn {Macro} {ScmGloc *} SCM_GLOC (ScmObj @var{obj}) Converts @code{ScmObj} to the pointer to a gloc. @end deftypefn @deftypefn {Macro} int SCM_GLOCP (ScmObj @var{obj}) @code{TRUE} iff @var{obj} is a gloc. @end deftypefn @deftypefn {Macro} ScmObj SCM_GLOC_GET (ScmGloc *@var{gloc}) Returns the global value of @var{gloc}. This may return @code{SCM_UNBOUND}; in such a case, the C routine must make sure it won't leak out to the Scheme world (usually the expected behavior is to raise an "undefined variable" error. @end deftypefn @deftypefn {Macro} void SCM_GLOC_SET (ScmGloc *@var{gloc}, ScmObj @var{val}) Sets the global value of @var{gloc} to @var{val}. This may raise an error if @var{gloc} is marked as a constant. @end deftypefn @deftypefn {Macro} void SCM_GLOC_CONST_P (ScmGloc *@var{gloc}) @code{TRUE} iff @var{gloc} is marked as a constant. @end deftypefn @node Modules, Characters, Glocs, C API reference @section Modules @deftp {Scheme Object} ScmModule Represents the Scheme module objects. @end deftp @deftypefun ScmModule *Scm_FindModule (ScmSymbol *name, int flags) @end deftypefun @deftypefun ScmObj Scm_MakeModule (ScmSymbol *name, int error_if_exists) @end deftypefun @deftypefun ScmObj Scm_GlobalVariableRef (ScmModule *module, ScmSymbol *symbol, int flags) @end deftypefun @deftypefun ScmObj Scm_Define (ScmModule *module, ScmSymbol *symbol, ScmObj value) @deftypefunx ScmObj Scm_DefineConst (ScmModule *module, ScmSymbol *symbol, ScmObj value) @end deftypefun @node Characters, Character sets, Modules, C API reference @section Characters @deftp {Type} ScmChar A word large enough to hold all characters Gauche can handle. It is like @code{wchar_t}, but we chose to use our own type since the actual implementation of @code{wchar_t} varies among platforms which complicates implementation. You can assume that within the range of ASCII characters, C's @code{char} and @code{ScmChar} have the same value; that is, you can safely cast C's ASCII character to @code{ScmChar}. If Gauche is compiled with utf-8 as internal character encoding, the value of @code{ScmChar} always matches unicode codepoint value. Note that @code{ScmChar} is @emph{not} the representation of Scheme character; you stil need to box @code{ScmChar} value to pass a character to the Scheme world by the following macros. @end deftp @deftypefn {Macro} ScmChar SCM_CHAR (@var{val}) Typecast C value @var{val} to @code{ScmChar}. @end deftypefn @deftypefn {Macro} int SCM_CHARP (ScmObj @var{obj}) Predicate to check whether @var{obj} is a Scheme character or not. @end deftypefn @deftypefn {Macro} ScmChar SCM_CHAR_VALUE (ScmObj @var{obj}) Unbox @code{ScmChar} value from a Scheme character @var{obj}. @end deftypefn @deftypefn {Macro} ScmObj SCM_MAKE_CHAR (ScmChar @var{val}) Box @var{ScmChar} value to a Scheme character. @end deftypefn @deftypevr {Macro} ScmChar SCM_CHAR_INVALID A value that can't be a valid character. Used in various situations to indicate there's no appropriate character. @end deftypevr @deftypevr {Macro} ScmChar SCM_CHAR_MAX Maximum possible value of @code{ScmChar}. @end deftypevr @deftp {Enum} Scm_IllegalCharHandling In some functions that have to deal with characters coming from outside world, you need to specify how they should behave when they meet a data chunk that does not consist a valid character in Gauche's native encoding. This enum specifies the behavior. @table @code @item SCM_ILLEGAL_CHAR_REJECT Refuse to handle illegal chars. For ports this means raising an error. For string conversion procedure, this makes it to return some non-string value, such as @code{SCM_FALSE}. @item SCM_ILLEGAL_CHAR_OMIT Silently discard the illegal chars. @item SCM_ILLEGAL_CHAR_REPLACE Replace an illegal char to a substitute char, specified elsewhere. @end table @end deftp @deftypefn {Macro} int SCM_CHAR_ASCII_P (ScmChar @var{val}) @deftypefnx {Macro} int SCM_CHAR_UPPER_P (ScmChar @var{val}) @deftypefnx {Macro} int SCM_CHAR_LOWER_P (ScmChar @var{val}) Like @code{isascii()}, @code{isupper()}, and @code{islower()}. We can't use standard functions on @code{ScmChar}, since @code{ScmChar} representation may be different from what the platform supports. Note that @var{val} may be used more than once in the expanded form. @end deftypefn @deftypefn {Macro} ScmChar SCM_CHAR_UPCASE (ScmChar @var{val}) @deftypefnx {Macro} ScmChar SCM_CHAR_DOWNCASE (ScmChar @var{val}) Converts @code{ScmChar} to upper case or lower case character, respectively. Note that @var{val} may be used more than once in the expanded form. @end deftypefn As of 0.8.8, @code{SCM_CHAR_UPPER_P}, @code{SCM_CHAR_LOWER_P}, @code{SCM_CHAR_UPCASE} and @code{SCM_CHAR_DOWNCASE} only work properly on ASCII characters. For any other characters, the predicates return @code{FALSE}, and the converters return the passed value as is. It'll be extended to support larger character ranges according to Unicode character attributes. @deftypefun int Scm_DigitToInt (ScmChar @var{ch}, int @var{radix}) If a character @var{ch} represents a digit of a number in @var{radix}, returns the value it represents. Otherwise, returns @code{-1}. The valid range of @var{radix} is between 2 and 36, inclusive. @example Scm_DigitToInt(SCM_CHAR('0'), 10) @result{} 0 Scm_DigitToInt(SCM_CHAR('5'), 10) @result{} 5 Scm_DigitToInt(SCM_CHAR('c'), 10) @result{} -1 Scm_DigitToInt(SCM_CHAR('c'), 16) @result{} 12 Scm_DigitToInt(SCM_CHAR('C'), 16) @result{} 12 Scm_DigitToInt(SCM_CHAR('z'), 36) @result{} 35 @end example @end deftypefun @deftypefun ScmChar Scm_IntToDigit (int @var{n}, int @var{radix}) Converts an integer to a character that represents that integer. in radix @var{radix} number. @var{Radix} must be between 2 and 36 inclusive. If @var{n} is outside of valid range, @code{SCM_CHAR_INVALID} is returned. @example Scm_IntToDigit(0, 10) @result{} SCM_CHAR('0') Scm_IntToDigit(5, 10) @result{} SCM_CHAR('5') Scm_IntToDigit(10, 10) @result{} SCM_CHAR_INVALID Scm_IntToDigit(10, 16) @result{} SCM_CHAR('a') Scm_IntToDigit(35, 36) @result{} SCM_CHAR('z') @end example @end deftypefun @deftypefun ScmChar Scm_UcsToChar (int @var{n}) Converts unicode codepoint @var{n} to an @code{ScmChar} value. Since Gauche uses only utf-8 as internal encoding now, this is an identify function. This function may return @code{SCM_CHAR_INVALID} if @var{n} can't be converted to a valid character in the native encoding. (Note that, however, this function does not perform exhaustive checking; if Gauche's internal encoding is utf-8, you can pass any value to @var{n} even if it is not a valid Unicode codepoint, and this function still returns @var{n} as is.) @end deftypefun @deftypefun int Scm_CharToUcs (ScmChar @var{ch}) Converts @code{ScmChar} value to Unicode codepoint. This function may return @code{-1} if @var{ch} can't be converted to Unicode codepoint. @end deftypefun @deftypefun ScmObj Scm_CharEncodingname (void) Returns a Scheme symbol that represents Gauche's internal character encoding. As of 0.8.8, it may be either one of @code{utf-8}, @code{euc-jp}, @code{sjis} or @code{none}. @end deftypefun @deftypefun {const char **} Scm_SupportedCharacterEncodings (void) Returns a NULL-terminated array of C strings of character encoding names that are supported natively. Since an encoding can be upper-compatible to another encoding, there can be multiple supported encodings; for example, if Gauche is compiled with @code{utf-8} as native encoding, @code{ascii} and @code{iso-8859-1} are also supported since they are subset of Unicode. An encoding can have several aliases (e.g. @code{iso-8859-1} is often referred as @code{latin-1}). To avoid complication, you should use @code{Scm_SupportedCharacterEncodingP} below to test whether the running Gauche supports a certain encoding or not. @end deftypefun @deftypefun int Scm_SupportedCharacterEncodingP (const char *@var{encoding}) Returns @code{TRUE} if a character encoding named by @var{encoding} is natively supported on the running Gauche. Returns @code{FALSE} otherwise. @var{Encoding} is compared in case insensitive way, and certain variations (e.g. with or without hyphen) are allowed. @end deftypefun @node Character sets, Strings, Characters, C API reference @section Character sets @node Strings, Regular expressions, Character sets, C API reference @section Strings @subheading Multibyte strings and thread safety Gauche supports multibyte strings natively, so its C API just hides most complexities that come with multibyte encodings. You should treat Scheme strings as opaque objects and use provided APIs and macros to access their contents. Because of multibyte nature, the size of the string measured in bytes can be different from the number of characters the string contains. In Gauche, we refer the size of a string in bytes as @emph{size}, while the number of characters in a string as @emph{length}. One important fact: Internally, Gauche treats string as immutable objects, @code{ScmStringBody}. Scheme standard requires string to be mutable, so we have a Scheme string (@code{ScmString}) keep a pointer to a string body, and when the Scheme string is modified, we allocate a new string body and switch the pointer in the Scheme string to the new body. You can now see it is disastrously inefficient to call @code{string-set!} repeatedly on a string in Gauche. Note that, with preemptive multithreads, a Scheme string (@code{ScmString}) can be mutated while another thread is accessing it. It is a problem for us, since string mutation can change the size (in bytes) of the string because of multibyte characters. If you obtain the size, then accesses the string content using the size, you don't want the size of the content to be changed in between. (This is not so much a problem for the implementations that use an array of fixed-size characters, since mutation is localized to a single character at a time.) It is too expensive to use mutex for every string access. Immutability helps here; retrieving @code{ScmStringBody} from @code{ScmString} is an atomic operation, and once you get hold onto @code{ScmStringBody}, you don't need to worry about other threads because it will never be changed. All the properties of strings, such as its size, belong to @code{ScmStringBody} and not @code{ScmString}. @example /* WRONG: Thread-unsafe code */ void f(ScmString *s) @{ int size = SCM_STRING_BODY_SIZE(SCM_STRING_BODY(s)); /* in bytes */ const char *cstr = Scm_GetStringConst(s); /* do something with size and cstr */ @} /* CORRECT: Thread-safe code */ void f(ScmString *s) @{ int size; const char *cstr = Scm_GetStringContent(s, &size, NULL, NULL); /* do something with size and cstr */ @} /* CORRECT: This one is also thread-safe, though you need to scan the string twice. */ void f(ScmString *s) @{ const char *cstr = Scm_GetStringConst(s); int size = strlen(cstr); /* do something with size and cstr */ @} @end example @subheading Datatype @deftp {Scheme Object} ScmString Scheme string. It is merely a header that contains a pointer to @code{ScmStringBody}. @end deftp @deftp {Type} ScmStringBody The body of the string. It is immutable---that is, once it is constructed, it should never be changed. @end deftp @deftypevr {Constant} int SCM_STRING_IMMUTABLE @deftypevrx {Constant} int SCM_STRING_INCOMPLETE @deftypevrx {Constant} int SCM_STRING_COPYING Flags to specify the nature of the string and/or the behavior of the string constructor. @table @code @item SCM_STRING_IMMUTABLE When passed to the constructor, it creates an immutable Scheme string. This flag is stored in the Scheme string and causes an error if you try to attempt to modify it. @item SCM_STRING_INCOMPLETE When passed to the constructor, it creates an incomplete Scheme string (even the string doesn't contain illegal byte sequences). The Scheme string is also marked incomplete when the constructor found illegal byte sequences. @item SCM_STRING_COPYING This is only used by the string constructor and not stored in the string object. This flag indicates the constructor to copy the content of the passed byte array. See @code{Scm_MakeString} below for the detailed explanation. @end table @end deftypevr @deftypefn {Macro} int SCM_STRINGP (ScmObj @var{obj}) Type predicate. @end deftypefn @deftypefn {Macro} {ScmString *} SCM_STRING (ScmObj @var{obj}) Typecast. @end deftypefn @deftypefn {Macro} {const ScmStringBody *} SCM_STRING_BODY (ScmObj @var{str}) Returns a pointer to the body of the Scheme string @var{str}. Note that the returned body is immutable. @end deftypefn @deftypefn {Macro} int SCM_STRING_BODY_LENGTH (ScmStringBody *@var{body}) @deftypefnx {Macro} int SCM_STRING_BODY_SIZE (ScmStringBody *@var{body}) @deftypefnx {Macro} int SCM_STRING_BODY_FLAGS (ScmStringBody *@var{body}) Query the parameters of the string body. @end deftypefn @deftypefn {Macro} int SCM_STRING_BODY_HAS_FLAG (ScmStringBody *@var{body}, int @var{flag}) Query if the string body has a flag, which is a bitwise OR of zero or more of the @code{SCM_STRING_*} flags. @end deftypefn @deftypefn {Macro} int SCM_STRING_BODY_IMMUTABLE_P (ScmStringBody *@var{body}) @deftypefnx {Macro} int SCM_STRING_BODY_INCOMPLETE_P (ScmStringBody *@var{body}) Returns true iff the string body is immutable or incomplete, respectively. @end deftypefn @deftypefn {Macro} int SCM_STRING_BODY_SYNGLE_BYTE_P (ScmStringBody *@var{body}) Returns true iff the string consists of only single byte characters. @end deftypefn @subheading Constructors @deftypefun ScmObj Scm_MakeString (const char *@var{str}, int @var{size}, int @var{len}, int @var{flags}) Creates a new Scheme string, whose content, size (in bytes), and length (in characters) are given by @var{str}, @var{size} and @var{len}, respectively. You can pass @code{-1} to @var{size}. In such case, @code{Scm_MakeString} assumes @var{str} is @code{NUL}-terminated string and calculates the size. If you pass an explicit size, @var{str} does not need to be @code{NUL}-terminated. You can pass @code{-1} to @var{len}. In such case, @code{Scm_MakeString} counts characters in @var{str}. If you pass an explicit length, @code{Scm_MakeString} trust it---passing wrong number will cause lots of troubles. C-string @var{str} is interpreted in the Gauche's native multibyte encoding. If you pass @code{-1} to @var{len}, and @var{str} contains an illegal byte sequence as the native multibyte encoding, the created string becomes incomplete. You can also create an incomplete string explicitly by passing @code{SCM_STRING_INCOMPLETE} flag to @var{flags}. @var{Flags} is a bitwise OR of the following bitmasks. @table @code @item SCM_STRING_INCOMPLETE Creates an incomplete string, even if @var{str} contains only valid characters. @item SCM_STRING_IMMUTABLE Creates an immutable string. Immutable string would raise an error if used by mutating procedures. @item SCM_STRING_COPYING The content pointed by @var{str} is copied, so that the caller can free @var{str} after this call. Without this flag, the created string directly points the region passed by @var{str}, and it is managed by Gauche's garbage collector. That is, if @var{str} points a static data or the region you get by Gauche's allocators, you don't need this flag; while if @var{str} points the region you get by @code{malloc} or other means, you have to specify this flag. @end table @end deftypefun @deftypefn {Macro} ScmObj SCM_MAKE_STR (const char *@var{cstr}) A convenience macro, expanded as follows: @example Scm_MakeString(@var{cstr}, -1, -1, 0) @end example That is, the size and length are counted automatically, and @var{cstr} is not copied. @end deftypefn @deftypefn {Macro} ScmObj SCM_MAKE_STR_COPYING (const char *@var{cstr}) A convenience macro, expanded as follows: @example Scm_MakeString(@var{cstr}, -1, -1, SCM_STRING_COPYING) @end example That is, the size and length are counted automatically, and @var{cstr} is copied. @end deftypefn @deftypefn {Macro} ScmObj SCM_MAKE_STR_IMMUTABLE (const char *@var{cstr}) A convenience macro, expanded as follows: @example Scm_MakeString(@var{cstr}, -1, -1, SCM_STRING_IMMUTABLE) @end example @end deftypefn @deftypefun ScmObj Scm_MakeFillString (int @var{len}, ScmChar @var{fill}) Creates a Scheme string consists of the character @var{fill} repeated for @var{len} times. Returned string is always mutable and complete. @end deftypefun @deftypefun ScmObj Scm_CopyStringWithFlags (ScmString *@var{str}, int @var{flags}, int @var{mask}) Copy the content of the string @var{str}, with modifying the flags as specified by the following expression: @example newflag = (@var{flags} & @var{mask}) | (oldflag & ~@var{mask}) @end example Typically you want to drop immutable flag. Gauche internal uses bits in the flags other than listed here, so you shouldn't change those bits. Note: to copy a part of a string, you can use @code{Scm_Substring()}. @end deftypefun @deftypefun ScmObj Scm_CopyString (ScmString *@var{str}) An convenience function, equivalent to the following: @example Scm_CopyStringWithFlags(str, 0, SCM_STRING_IMMUTABLE) @end example @end deftypefun @deftypefn {Macro} {} SCM_STRING_CONST_INITIALIZER (const char *@var{str}, int @var{len}, int @var{siz}) This is expanded to a static initializer of @code{ScmStringRec} structure. @var{Len} and @var{siz} must be the correct values (you can't pass @code{-1}). This is mainly for programs that generates C source. This can be used to embed static Scheme strings in the C source. @end deftypefn @deftypefn {Macro} {} SCM_DEFINE_STRING_CONST (@var{name}, const char *@var{str}, int @var{len}, int @var{siz}) Expands to: @example ScmString @var{name} = SCM_STRING_CONST_INITIALIZER(@var{str}, @var{len}, @var{siz}) @end example @end deftypefn @subheading C-string extraction @deftypefun {const char *} Scm_GetStringConst (ScmString *@var{str}) Retrieves string content as a C string (@code{NUL}-terminated). This is the efficient way to convert a Scheme string to a C string. @end deftypefun @deftypefun {char *} Scm_GetString (ScmString *@var{str}) Use this when you need a mutable C string. This function copies the content every time and returns a freshly allocated string. @end deftypefun @deftypefun {const char *} Scm_GetStringContent (ScmString *@var{str}, unsigned int *@var{psize}, unsigned int *@var{plen}, unsigned int *@var{pflags}) Use this function if you want to retrieve other attributes of the strings at once. The return value points to the beginning of the string content, but it may not be @code{NUL}-terminated. @var{Psize}, @var{plen}, and @var{pflags} are pointers to the location where the size, the length, and the flags of the string is returned. Any of them can be @code{NULL} if the caller doesn't need the information. The retrieval of those information and string content is atomic, so this is a thread safe way to get informations out of @code{ScmString}. @end deftypefun @subheading Conversions @deftypefun ScmObj Scm_CStringArrayToList (const char **@var{array}, int @var{size}, int @var{flags}) Converts an array of C string to a list of Scheme strings. If @var{size} is nonnegative, it specifies the size of @var{array}. If @var{size} is negative, @var{array} is assumed to be @code{NULL}-terminated. The @var{flags} argument is passed to @code{Scm_MakeString} as is. @end deftypefun @deftypefun {const char **} Scm_ListToConstCStringArray (ScmObj @var{list}, int @var{errp}) Converts a list of Scheme strings @var{list} into C const string array, @code{NULL} terminated. If @var{errp} is true, an error is signaled if @var{list} contains other than Scheme strings. If @var{errp} is false, @code{NULL} is returned in such cases. @end deftypefun @deftypefun {char **} Scm_ListToCStringArray (ScmObj @var{list}, int @var{errp}, void *@var{alloc}(size_t)) Converts a list of Scheme strings @var{list} into C string array, @code{NULL} terminated. Unlike @code{Scm_ListToConstCStringArray}, each C string is freshly allocated and mutable. Furthermore, if @code{alloc} is provided, it is used to allocate C strings and the pointer array. @end deftypefun @deftypefun ScmObj Scm_StringToList (ScmString *@var{str}) Scheme's @code{string->list}. Returns a list of characters. Signals an error if @var{str} is an incomplete string. @end deftypefun @deftypefun ScmObj Scm_ListToString (ScmObj @var{chars}) Scheme's @code{list->string}. Converts a list of characters to a Scheme string. Signals an error if @var{chars} is not a list, or it contains other than Scheme character. @end deftypefun @deftypefun ScmObj Scm_StringCompleteToIncomplete (ScmString *@var{str}) Returns a newly created incomplete Scheme string whose content is the same as given Scheme string @var{str}. @end deftypefun @deftypefun ScmObj Scm_StringIncompleteToComplete (ScmString *@var{str}, int @var{handling}, ScmChar @var{substitute}) Returns a newly created complete Scheme string whose content is the same as given (possible incomplete) string @var{str}. The @var{handling} argument must be one of the values of enum @code{Scm_IllegalCharacterHandling}, and determines the behavior when @var{str} contains an illegal byte sequences. If it is @code{SCM_ILLEGAL_CHAR_REJECT}, @code{SCM_FALSE} is returned. If it is @code{SCM_ILLEGAL_CHAR_OMIT}, illegal bytes are omitted from the result string. If it is @code{SCM_ILLEGAL_CHAR_REPLACE}, each illegal byte is replaced for @var{substitute}. The @var{substitute} argument isn't used in other cases. @end deftypefun @subheading Comparisons @deftypefun int Scm_StringEqual (ScmString *@var{x}, ScmString *@var{y}) Returns @code{TRUE} if two strings are equal (as by @code{string=?}), @code{FALSE} otherwise. A string is equal to another if both their completeness and contents match. @end deftypefun @deftypefun int Scm_StringCmp (ScmString *@var{x}, ScmString *@var{y}) Returns a positive integer if string @var{x} is greater than string @var{y}, a negative integer if string @var{x} is less than string @var{y}, and zero if string @var{x} and string @var{y} are the same. Comparison is done in the codepoint order. Unlike @code{Scm_StringEqual}, this function signals an error if completeness of both string differ. @end deftypefun @deftypefun int Scm_StringCiCmp (ScmString *@var{x}, ScmString *@var{y}) Like @code{Scm_StringCmp}, but compares in case-insensitive way. Currently Gauche only folds cases within ASCII range. Soon it'll follow Unicode case folding rules. @end deftypefun @subheading Accessors @deftypefun ScmChar Scm_StringRef (ScmString *@var{str}, int @var{k}, int @var{range_error}) Scheme's @code{string-ref}. Returns a character at the @var{k}-th position of the string @var{str}. When @var{k} is out of range, returns @code{SCM_CHAR_INVALID} if @code{range_error} is @code{FALSE}, or raises an error if @code{range_error} is true. For the time being, an error is raised if @var{str} is an incomplete string. @end deftypefun @deftypefun int Scm_StringByteRef (ScmString *@var{str}, int @var{k}, int @var{range_error}) Returns @var{k}-th byte in the Scheme string @var{str} as a nonnegative integer. If @var{range_error} is true, an error is signalled if @var{k} is out of range. If @var{range_error} is false, -1 is returned if @var{k} is out of range. @var{Str} can be an incomplete string. @end deftypefun @deftypefun ScmObj Scm_Substring (ScmString *@var{str}, int @var{start}, int @var{end}, int @var{byterange}) Returns a substring of @var{str}, starting from @var{start} (inclusive) and ending at @var{end} (exclusive). If @var{byterange} is @code{FALSE} and @var{str} is complete, @var{start} and @var{end} are character count and returned string will be complete. Otherwise, they are byte count and returned string will be incomplete. A negative value in the @var{end} argument is regarded as the length/size of the input string. After this treatment, both @var{start} and @var{end} arguments must be in the valid range, and @var{start} must be less than or equal to @var{end}, or an error is signalled. It is guaranteed that the returned string is newly created and mutable, even if the @var{start} and @var{end} specifies the entire string. @end deftypefun @subheading Mutator @deftypefun ScmObj Scm_StringReplaceBody (ScmString *@var{target}, ScmStringBody *@var{newbody}) Replaces @var{target}'s body by @var{newbody}. An error is signalled if @var{target} is immutable. This is the only C API that allows mutation of Scheme strings. Scheme-level string mutators, such as @code{string-set!} and @code{string-fill!}, are implemented in Scheme on top of this API. Since string body is immutable, such mutators needs to allocate and fill a new string body anyway, there's little merit in providing those mutators in C. @end deftypefun @subsubheading Concatenation @deftypefun ScmObj Scm_StringAppend2 (ScmString *@var{x}, ScmString *@var{y}) Returns a new Scheme string whose content is concatenation of strings @var{x} and @var{y}. @end deftypefun @deftypefun ScmObj Scm_StringAppendC (ScmString *@var{x}, const char *@var{s}, int @var{size}, int @var{len}) Returns a new Scheme string whose content is concatenation of a Scheme string @var{x} and C-level string @var{s}. Like @code{Scm_MakeString}, you can give -1 to @var{size} and/or @var{len} to make the function calculates those values. If you give -1 to @var{size}, @var{s} must be @code{NUL}-terminated; otherwise @var{s} doesn't need to be. @end deftypefun @deftypefun ScmObj Scm_StringAppend (ScmObj @var{strs}) The @var{strs} argument must be a list of Scheme strings. Returns a new Scheme string whose content is concatenation of all the strings. An error is signalled if not all elements in @var{strs} are strings. If any element in @var{strs} is incomplete, the result string becomes incomplete. @end deftypefun @deftypefun ScmObj Scm_StringJoin (ScmObj @var{strs}, ScmString *@var{delim}, int @var{grammar}) Scheme's @var{string-join}. Concatenates a list of strings @var{strs} with inserting a delimiter @var{delim} between them. The @var{grammar} argument must be one of the following enums: @example enum @{ SCM_STRING_JOIN_INFIX, SCM_STRING_JOIN_STRICT_INFIX, SCM_STRING_JOIN_SUFFIX, SCM_STRING_JOIN_PREFIX @}; @end example They correspond to @code{infix}, @code{strict-infix}, @code{suffix}, and @code{prefix} as defined in @code{srfi-13}'s @code{string-join}. @end deftypefun @subheading Searching @deftypefun ScmObj Scm_StringScan (ScmString *@var{s1}, ScmString *@var{s2}, int @var{retmode}) @deftypefunx ScmObj Scm_StringScanChar (ScmString *@var{s1}, ScmChar @var{ch}, int @var{retmode}) Scheme's @code{string-scan}. Search a string @var{s2} or a character @var{ch} within a string @var{s1}, respectively. Return value depends on the @var{retmode} argument, as follows: @table @code @item SCM_STRING_SCAN_INDEX Returns an index of the first found instance of @var{s1}/@var{ch}, or @code{SCM_FALSE} if no instance is found. @item SCM_STRING_SCAN_BEFORE Returns a substring of @var{s1} between its beginning and just before the first found instance of @var{s1}/@var{ch}, or @code{SCM_FALSE} if no instance is found. @item SCM_STRING_SCAN_AFTER Returns a substring of @var{s1} between just after the first found instance of @var{s1}/@var{ch} and the end of @var{s1}, or @code{SCM_FALSE} if no instance is found. @item SCM_STRING_SCAN_BEFORE2 Returns two values via @code{Scm_Values()}, the substring of @var{s1} before the found instance and the rest, or two @code{SCM_FALSE}s if no instance found. @item SCM_STRING_SCAN_AFTER2 Returns two values via @code{Scm_Values()}, the substring of @var{s1} before the end of the found instance and the rest, or two @code{SCM_FALSE}s if no instance found. @item SCM_STRING_SCAN_BOTH Returns two values via @code{Scm_Values()}, the substring of @var{s1} before the found instance and after the found instance, or two @code{SCM_FALSE}s if no instance found. @end table The last three return multiple values on the running Gauche VM. See @ref{Calling back to Scheme}, for how to retrieve those values. @end deftypefun @deftypefun ScmObj Scm_StringSplitByChar (ScmString *@var{str}, ScmChar @var{ch}) @end deftypefun @subheading Miscellaneous utilities @deftypefun int Scm_MBLen (const char *@var{str}, const char *@var{stop}) A utility function to count the number of characters in a multibyte string @var{str}, assuming it's in Gauche's native encoding. If @var{stop} is given, it specifies the end point in the string; bytes just before @var{stop} are counted. The string may have @code{NUL} character in this case. If @var{stop} is @code{NULL}, @var{str} is assumed to be @code{NUL} terminated. If the string is complete, the number of characters is returned. If the string is incomplete, -1 is returned. @end deftypefun @subheading Dynamic strings Dynamic strings provide a convenient way to construct a string of an unknown length. It is a base of output string port, but from C programs using dynamic strings is lightweight than output string port (see @ref{Built-in ports}, for string ports). It is OK to call dynamic string operations while locking a mutex. @deftp {Datatype} ScmDString A structure to keep a string under construction. It is not a Scheme datatype (means: you can't cast it to @code{ScmObj}). You can allocate it on the C stack for efficient operation. @end deftp The typical usage of dynamic strings looks like this: @example ScmDString ds; ScmObj str; Scm_DStringInit(&ds); /* Initialization */ Scm_DstringPutc(&ds, 'a'); /* Adding content */ Scm_DstringPutz(&ds, "abc", -1); /* Adding content */ ... str = Scm_DStringGet(&ds, 0); /* Obtains the result string */ @end example @deftypefun void Scm_DStringInit (ScmDString *@var{dstr}) Initializes a dynamic string object. A dynamic string object must be initialized before used. @end deftypefun @deftypefun int Scm_DStringSize (ScmDString *@var{dstr}) Returns the size (number of bytes) accumulated in the dynamic string. @end deftypefun @deftypefun ScmObj Scm_DStringGet (ScmDString *@var{dstr}, int @var{flags}) Extracts the accumulated string as a Scheme string. The accumulated data remains in @var{dstr}. By default, returned string is mutable, and its completeness is determined by its content. You may pass @code{SCM_STRING_IMUUTABLE} and/or @code{SCM_STRING_INCOMPLETE} to the @var{flags} argument to force the attributes of the result string. @end deftypefun @deftypefun {const char *} Scm_DStringGetz (ScmDString *@var{dstr}) Extracts the accumulated string as a @code{NUL}-terminated C string. The accumulated data remains in @var{dstr}. @end deftypefun @deftypefun void Scm_DStringPutz (ScmDString *@var{dstr}, const char *@var{str}, int @var{siz}) Adds C string @var{str} to the dynamic string. If @var{siz} is negative, @var{str} is assumed to be @code{NUL}-terminated. If @var{siz} is nonnegative, it specifies the size of the string (in which case @var{str} may contain @code{NUL} character in it.) @end deftypefun @deftypefun void Scm_DStringAdd (ScmDString *@var{dstr}, ScmString *@var{str}) Adds Scheme string @var{str} to the dynamic string. @end deftypefun @deftypefun void Scm_DStringPutb (ScmDString *@var{dstr}, char @var{byte}) Adds a single byte @var{byte} to the dynamic string. @end deftypefun @deftypefun void Scm_DStringPutc (ScmDString *@var{dstr}, ScmChar @var{ch}) Adds a single character @var{ch} to the dynamic string. @end deftypefun @node Regular expressions, Vectors, Strings, C API reference @section Regular expressions @node Vectors, Dictionaries, Regular expressions, C API reference @section Vectors @deftypefn {Macro} int SCM_VECTORP (ScmObj @var{obj}) Type predicate. @end deftypefn @deftypefn {Macro} {ScmVector *} SCM_VECTOR (ScmObj @var{obj}) Typecast. @end deftypefn @deftypefn {Macro} int SCM_VECTOR_SIZE (ScmObj @var{vec}) Returns the number of elements of the vector @var{vec}. @end deftypefn @deftypefn {Macro} {ScmObj *} SCM_VECTOR_ELEMENTS (ScmObj @var{vec}) Returns the pointer to the array of the vector contents. @end deftypefn @deftypefn {Macro} ScmObj SCM_VECTOR_ELEMENT (ScmObj @var{vec}, int @var{k}) Returns the @var{k}-th element of the vector. No boundary check is done. Use @code{Scm_VectorRef} for safer access. @end deftypefn @deftypefun ScmObj Scm_MakeVector (int @var{size}, ScmObj @var{fill}) Returns a vector of @var{size} elements. Each element is initialized by @var{fill}. @end deftypefun @deftypefun ScmObj Scm_ListToVector (ScmObj @var{list}, int @var{start}, int @var{end}) Creates a vector from @var{start}-th element (inclusive) to @var{end}-th element (exclusive) of a list @var{list}. @var{end} can be @code{-1} to indicate the end of the list. @end deftypefun @deftypefun ScmObj Scm_VectorToList (ScmVector *@var{vec}, int @var{start}, int @var{end}) Creates a list from @var{start}-th element (inclusive) to @var{end}-th element (exclusive) of a vector @var{vec}. @var{end} can be @code{-1} to indicate the end of the vector. @end deftypefun @deftypefun ScmObj Scm_VectorRef (ScmVector *@var{vec}, int @var{k}, ScmObj @var{fallback}) Returns @var{k}-th element of the vector. If @var{k} is out of range, the value passed to @var{fallback} is returned. Note that this routine will never raise an error; argument check of Scheme's @code{vector-ref} is done in the bridge stub. @end deftypefun @deftypefun ScmObj Scm_VectorSet (ScmVector *@var{vec}, int @var{k}, ScmObj @var{obj}) Sets @var{k}-th element of a vector @var{vec} by @var{obj}. Always return @var{obj}. If @var{k} is out of range, no operation is performed (no error is signalled). The boundary check for Scheme's @code{vector-set!} is done in the bridge stub. @end deftypefun @deftypefun ScmObj Scm_VectorFill (ScmVector *@var{vec}, ScmObj @var{fill}, int @var{start}, int @var{end}) Sets @var{start}-th element (inclusive) to @var{end}-th element (exclusive) of a vector @var{vec} by @var{fill}. @var{end} can be @code{-1} to indicate the end of the vector. @end deftypefun @deftypefun ScmObj Scm_VectorCopy (ScmVector *@var{vec}, int @var{start}, int @var{end}, ScmObj @var{fill}) Creates a new vector, whose content is the same as the content of @var{vec} beginning with @var{start}-th element and ending with (@var{end}-1)-th element. If @var{end} is -1, it is taken as the length of @var{vec}. Unlike other vector APIs, @var{start} can be negative and @var{end} can be greater than then length of @var{vec}; in such case, @var{vec} is regarded as if it has implicit elements in both directions, whose value is given by @var{fill}. @end deftypefun @deftypefn {Macro} int SCM_UVECTORP (ScmObj @var{obj}) Type predicate. @end deftypefn @deftypefn {Macro} {ScmUVector *} SCM_UVECTOR (ScmObj @var{obj}) Typecast. @end deftypefn @deftypefn {Macro} {void *} SCM_UVECTOR_OWNER (ScmObj @var{vec}) Returns the owner pointer of the uniform vector @var{vec}. @end deftypefn @deftypefn {Macro} {void *} SCM_UVECTOR_ELEMENTS (ScmObj @var{vec}) Returns the pointer to the array of the uniform vector contents. @end deftypefn @deftypefn {Macro} int SCM_UVECTOR_SIZE (ScmObj @var{vec}) Returns the number of elements of the uniform vector @var{vec}. @end deftypefn @deftypefn {Macro} int SCM_UVECTOR_IMMUTABLE_P (ScmObj @var{vec}) Returns non-zero if the uniform vector is immutable. @end deftypefn @deftypefn {Macro} void SCM_UVECTOR_IMMUTABLE_SET (ScmObj @var{vec}, @var{flags}) Sets immutable state of the uniform vector @var{vec}. @end deftypefn @deftypefn {Macro} void SCM_UVECTOR_CHECK_MUTABLE (ScmObj @var{vec}) Raise an error if the uniform vector @var{vec} is immutable. @end deftypefn @deftypefn {Macro} int SCM_UVECTOR_SUBTYPE_P (ScmObj @var{vec}, ScmUVectorType @var{type}) Returns true if the uniform vector @var{vec} is of type @var{type}. @end deftypefn @deftypefun ScmUVectorType Scm_UVectorType (ScmClass @var{klass}) Returns the vector type of the uniform vector class @var{klass}. @end deftypefun @deftypefun {const char *} Scm_UVectorTypeName (int @var{type}) Converts @var{type} (of type @code{ScmUVectorType} actually) to a string. @end deftypefun @deftypefun int Scm_UVectorElementSize (ScmClass @var{klass}) Returns the element type in bytes of the uniform vector class @var{klass}. @end deftypefun @deftypefun int Scm_UVectorSizeInBytes (ScmUVector *@var{vec}) Returns the size in bytes of the uniform vector @var{vec}. @end deftypefun @deftypefun ScmObj Scm_MakeUVector (ScmClass *@var{klass}, ScmSmallInt @var{size}, void *@var{init}) Returns a mutable uniform vector of type @var{klass}, @var{size} elements and no owner. The vector data is contained in @var{init}, which must be properly prepared by the caller. This normally is allocated in heap. But it could also be from other sources, e.g. mmap. @end deftypefun @deftypefun ScmObj Scm_MakeUVectorFull (ScmClass *@var{klass}, ScmSmallInt @var{size}, void *@var{init}, int @var{immutablep}, void *@var{owner}) Creates a new uniform vector. This is the extended version of @code{Scm_MakeUVector} that lets you control both owner and immutable state. @end deftypefun @deftypefun ScmObj Scm_ListToUVector (ScmClass *@var{klass}, ScmObj @var{list}, ScmSmallInt @var{start}, ScmSmallInt @var{end}) Creates a uniform vector of class @var{klass} from @var{start}-th element (inclusive) to @var{end}-th element (exclusive) of a list @var{list}. @var{end} can be @code{-1} to indicate the end of the list. @end deftypefun @deftypefun ScmObj Scm_UVectorSet (ScmUVector *@var{vec}, int @var{t}, int @var{k}, ScmObj @var{val}, int @var{clamp}) Sets @var{k}-th element of a vector @var{vec} (of type @var{type}) by @var{val}. See @ref{Scheme number objects} for @var{clamp}. Always return @var{obj}. If @var{k} is out of range, no operation is performed and an error is signalled. @end deftypefun @deftypefun ScmObj Scm_Make@var{tag}Vector (ScmSmallInt @var{size}, type @var{fill}) @deftypefunx ScmObj Scm_Make@var{tag}VectorFromArray (ScmSmallInt @var{size}, const type @var{array}[]) @deftypefunx ScmObj Scm_Make@var{tag}VectorFromArrayShared (ScmSmallInt @var{size}, type @var{array}[]) For all supported uniform vector types, there are three functions each type to create a vector of the type in question. @itemize @item The first variant creates a mutable vector automatically allocated on heap. @item The second variant initializes heap allocated vector data with @var{array}. @item The third variant directly uses @var{array} as the vector data. @end itemize @end deftypefun @node Dictionaries, Weak pointers, Vectors, C API reference @section Dictionaries Dictionaries are data structures that maps a key object to a value object. Gauche provides two kinds of basic dictionaries: hash tables and tree maps. Each kind of dictionary has two layers of API: The 'core' API (@code{ScmHashCore}, @code{ScmTreeCore}) works on a C structure, and deals with raw C pointers. On top of core API, Scheme-level objects (@code{ScmHashTable}, @code{ScmTreeMap}) are defined. There are other built-in structures that are built on opt of core API; for example, @code{ScmCharSet} uses @code{ScmTreeCore} internally, and there's a plan to provide @code{ScmWeakHashTable} which will be built on top of @code{ScmHashCore}. @menu * Common dictionary interface:: * Hash tables:: * Tree maps:: @end menu @node Common dictionary interface, Hash tables, Dictionaries, Dictionaries @subsection Common dictionary interface Since there are lots of similarities between hash tables and tree maps, they share some common data structures and enums. @deftp {Enum} ScmDictSetFlags These are bitflags @code{Scm_HashTableSet} and @code{Scm_TreeMapSet} take. @table @code @item SCM_DICT_NO_OVERWRITE If this flag is given, the function does not overwrite an existing entry; it only adds a new entry if no existing entry has the given key. @item SCM_DICT_NO_CREATE If this flag is given, the function does not add a new entry; it only changes the value of the existing entry. @end table @end deftp If both @code{SCM_DICT_NO_OVERWRITE} and @code{SCM_DICT_NO_CREATE} are given, the behavior is undefined. In future it is possible that we have more flags. Each key-value pair in a dictionary is kept in a @code{ScmDictEntry} structure. The low-level access functions (@code{Scm_HashCoreSearch} and @code{Scm_TreeCoreSearch}), and iterators (@code{Scm_HashIterNext} and @code{Scm_TreeCoreNext} etc.) returns a pointer to this structure. @deftp {Struct} ScmDictEntry @example typedef struct ScmDictEntryRec @{ const intptr_t key; intptr_t value; @} ScmDictEntry; @end example @end deftp Note that they can be used to keep non-@code{ScmObj}s, so the type of key and value is @code{intptr_t}. If you're accessing high-level dictionaries @code{Scm_HashTable} and @code{Scm_TreeMap}, both of which are designed to store @code{ScmObjs}, you should use the following accessor macros to retrieve @code{ScmObj}s. @deftypefn {Macro} ScmObj SCM_DICT_KEY (ScmDictEntry* @var{entry}) @deftypefnx {Macro} ScmObj SCM_DICT_VALUE (ScmDictEntry* @var{entry}) Accesses the key and the value fields of @code{ScmDictEntry} as @code{ScmObj}s, respectively. @end deftypefn @deftypefn {Macro} ScmObj SCM_DICT_SET_VALUE (ScmdictEntry* @var{entry}, ScmObj @var{value}) Sets @var{value} to the value field of @var{entry} and returns @var{value} itself. The caller have to make sure @var{value} is a valid @code{ScmObj}. Particularly, it is prohibited to pass @code{SCM_UNBOUND} as @var{value}. @end deftypefn Each core dictionary API provides a search function that takes operation (@code{op}) argument, which must be one of the following values: @deftp {Enum} ScmDictOp @table @code @item SCM_DICT_GET The search function returns @code{ScmDictEntry*} if found, @code{NULL} otherwise. @item SCM_DICT_CREATE The search function creates a new entry if the given entry is not found. Always returns @code{ScmDictEntry*}. @item SCM_DICT_DELETE The search function deletes a found entry from the dictionary. Returns @code{NULL} if no entry is found. Otherwise returns @code{ScmDictEntry*} which is just deleted from the dictionary. @end table @end deftp @node Hash tables, Tree maps, Common dictionary interface, Dictionaries @subsection Hash tables @subsubheading Low-level API @deftp {Enum} ScmHashType Specifies the pre-defined hash table types. Except @code{SCM_HASH_GENERAL}, each type implies specific hash and compare functions. @table @code @item SCM_HASH_EQ @code{eq?}-type hashtables. Compare function is @code{SCM_EQ}, and hash function is @code{Scm_EqHash}. @item SCM_HASH_EQV @code{eqv?}-type hashtables. Compare function is @code{Scm_Eqv}, and hash function is @code{Scm_EqvHash}. @item SCM_HASH_EQUAL @code{equal?}-type hashtables. Compare function is @code{Scm_Equal}, and hash function is @code{Scm_Hash}. @item SCM_HASH_STRING @code{string=?}-type hashtables. Compare function is @code{Scm_StringEqual}, and hash function is @code{Scm_HashString}. @item SCM_HASH_WORD Non-@code{ScmObj} one-word hashtables. Comparison is @code{==}, and hash is @code{Scm_EqHash}. The table may keep arbitrary machine words, not only @code{ScmObj}s. @item SCM_HASH_GENERAL A generic hashtable that uses user-provided comparison and hash functions. Currently this type of hashtables is not well supported; more support is planned in future. @end table @end deftp @deftp {Struct} ScmHashCore A C struct to hold a hash table. This structure is not an @code{ScmObj}, and supposed to be used embedded in other structures. @end deftp @deftypefun void Scm_HashCoreInitSimple (ScmHashCore *@var{core}, ScmHashType @var{type}, unsigned int @var{initSize}, void *@var{data}) Initialize a hash core structure pointed by @var{core}, with predefined hash and compare functions determined by the @var{type} argument. You can pass one of the @code{ScmHashType} enums except @code{SCM_HASH_GENERAL} to @var{type}. If you know rough number of hashtable entries, you can tell it by @var{initSize} argument so that the hashtable may be optimized for that size. Passing 0 makes the function to choose a reasonable value. The @var{data} argument is an opaque pointer for the application. @end deftypefun @deftypefun void Scm_HashCoreCopy (ScmHashCore *@var{dst}, const ScmHashCore *@var{src}) Copies the content of @var{src} to @var{dst}, including the hash type, hash function and compare function. The original content of @var{dst} is destroyed. It is OK to pass uninitialized @code{ScmHashCore} as @var{dst}. @end deftypefun @deftypefun {ScmDictEntry *} Scm_HashCoreSearch (ScmHashCore *@var{core}, intptr_t @var{key}, ScmDictOp @var{op}) Searches an entry with the given @var{key}, and and perform the operation specified by @var{op}, which must be either @code{SCM_DICT_GET}, @code{SCM_DICT_CREATE}, or @code{SCM_DICT_DELETE}. Returns a pointer to the found, created or deleted entry. For get and delete operations it may return @code{NULL} if there's no entry found for @var{key}. @end deftypefun @deftypefun int Scm_HashCoreNumEntries (ScmHashCore *@var{core}) Returns the current number of entries in the hash core. @end deftypefun @subsubheading Iterators @deftp {Struct} ScmHashIter An opaque structure to iterate over a hash table. This is not an @code{ScmObj}. You can modify the value of the entries while iterating over a hash table; however, once an entry is added or deleted, the behavior of existing iterators become undefined. @end deftp @deftypefun void Scm_HashIterInit (ScmHashIter *@var{iter}, ScmHashCore *@var{core}) Initializes an iterator @var{iter} to iterate through a hash core @var{core}. At the beginning, the iterator points to an imaginary entry just before the first entry, so that the first call of @code{Scm_HashIterNext} returns the first entry. @end deftypefun @deftypefun {ScmDictEntry *} Scm_HashIterNext (ScmHashIter *@var{iter}) Updates the iterator @var{iter} to point to the next entry, then returns it. If the iterator has visited all entries, @code{NULL} is returned. @end deftypefun @subsubheading Hash functions Other than @code{Scm_EqHash} and @code{Scm_EqvHash}, which returns a value that depends on the run-time address of the objects, hash values depend on the @emph{salt} value, which is initialized randomly at the process initialization time. @deftypefun {u_long} Scm_EqHash (ScmObj @var{obj}) Calculates hash value of the object suitable for @code{eq?}-type hash table. @end deftypefun @deftypefun {u_long} Scm_EqvHash (ScmObj @var{obj}) Calculates hash value of the object suitable for @code{eqv?}-type hash table. @end deftypefun @deftypefun {u_long} Scm_HashString (ScmString *@var{str}, unsigned long @var{bound}) @end deftypefun @deftypefun {u_long} Scm_PortableHash (ScmObj @var{obj}, u_long salt) @end deftypefun @deftypefun {ScmSmallInt} Scm_DefaultHash (ScmObj @var{obj}) @end deftypefun @deftypefun {ScmSmallInt} Scm_RecursiveHash (ScmObj @var{obj}, ScmSmallInt salt, u_long flags) @end deftypefun @deftypefun {ScmSmallInt} Scm_SmallIntHash (ScmSmallInt val, ScmSmallInt salt, u_long flags) @end deftypefun @deftypefun {ScmSmallInt} Scm_Int64Hash (int64_t val, ScmSmallInt salt, u_long flags) @end deftypefun @deftypefun u_long Scm_CombineHashValue (u_long a, u_long b) @end deftypefun @deftypefun ScmSmallInt Scm_HashSaltRef (void) @deftypefunx ScmSmallInt Scm_HashSaltSet (ScmSmallInt salt) @end deftypefun @deftypefun ScmSmallInt Scm_PortableHashSalt (ScmObj newval) @end deftypefun @subsubheading Scheme HashTable object @deftp {ScmObj} ScmHashTable @end deftp @deftypefn {Macro} int SCM_HASH_TABLE_P (ScmObj @var{obj}) Type predicate. @end deftypefn @deftypefn {Macro} {ScmHashTable *} SCM_HASH_TABLE (ScmObj @var{obj}) Typecast macro. @end deftypefn @deftypefn {Macro} {ScmHashCore *} SCM_HASH_TABLE_CORE (ScmHashTable *@var{ht}) Returns a pointer to the @code{ScmHashCore} in the hash table @var{ht}. @end deftypefn @deftypefn {Macro} {ScmHashCore *} SCM_HASH_TABLE_CORE (ScmHashTable *@var{ht}) Returns a pointer to the @code{ScmHashCore} in the hash table @var{ht}. @end deftypefn @deftypefun ScmObj Scm_MakeHashTableSimple (ScmHashType @var{type}, int @var{initSize}) @end deftypefun @node Tree maps, , Hash tables, Dictionaries @subsection Tree maps A tree map uses balanced binary tree to store the key-value pair. Entry retrieval and modification is O(log(n)). @subsubheading Low-level API @deftp {Struct} ScmTreeCore A C struct to hold a tree map. This structure is not an @code{ScmObj}, and supposed to be used embedded in other structures. @end deftp @deftp {Function Prototype} ScmTreeCompareProc @example typedef int ScmTreeCoreCompareProc(ScmTreeCore* tc, intptr_t k1, intptr_t k2); @end example Called when the tree map routine need to compare keys, @var{k1} and @var{k2}. The function must return @code{-1} if @var{k1} is before @var{k2}, @code{0} if @var{k1} and @var{k2} is the same, and @var{1} if @var{k1} is after @var{k2}. @end deftp @deftypefun void Scm_TreeCoreInit (ScmTreeCore *@var{tc}, ScmTreeCoreCompareProc *@var{cmp}, void *@var{data}) Initializes @code{ScmTreeCore} structure @var{tc}, using @var{cmp} as the compare procedure. Whatever information @var{tc} has been carrying will be lost. @end deftypefun @deftypefun void Scm_TreeCoreCopy (ScmTreeCore *@var{dst}, const ScmTreeCore *@var{src}) Copies the content of @var{src} into @var{dst}. Whatever information in @var{dst} will be lost. @end deftypefun @deftypefun {ScmDictEntry *} Scm_TreeCoreSearch (ScmTreeCore *@var{tc}, intptr_t @var{key}, ScmDictOp @var{op}) Searches an entry with the given @var{key}, and perform the operation specified by @var{op}, which must be either @code{SCM_DICT_GET}, @code{SCM_DICT_CREATE}, or @code{SCM_DICT_DELETE}. Returns a pointer to the found, created or deleted entry. For get and delete operations it may return @code{NULL} if there's no entry found for @var{key}. @end deftypefun @deftypefun {ScmDictEntry *} Scm_TreeCoreClosestEntries (ScmTreeCore *@var{tc}, intptr_t @var{key}, ScmDictEntry **@var{lo}, ScmDictEntry **@var{hi}) Searches an entry with the given @var{key} and returns an exact match, or @code{NULL} if there's no exact match. Besides that, it stores the pointers of entries closest to the given key, from below the key and above the key, in the location pointed by @var{lo} and @var{hi}, respectively. If the tree core has exact match, @var{*lo} and @var{*hi} will have pointers to the immediately previous and next entries. If the tree core doesn't have exact match, the given key is between the keys of two entries pointed by @var{*lo} and @var{*hi}. As a boundary case, if the given key is smaller than the smallest key in @var{tc}, @var{*lo} is @code{NULL}; if the given key is greater than the greatest, @var{*hi} is @code{NULL}; and if @var{tc} is empty, both @var{*lo} and @var{*hi} is @code{NULL}. @end deftypefun @deftp {Enum} ScmTreeCoreBoundOp Specify which side you're operating of the call to @code{ScmTreeCoreGetBound} and @code{ScmTreeCorePopBound}. @table @code @item SCM_TREE_CORE_MIN Operate on the entry of the minimum (smallest) key. @item SCM_TREE_CORE_MAX Operate on the entry of the maximum (greatest) key. @end table @end deftp @deftypefun {ScmDictEntry *} Scm_TreeCoreGetBound (ScmTreeCore *@var{tc}, ScmTreeCoreBoundOp @var{op}) Returns the entry in @var{tc} with the minimum or maximum key, as specified by @var{op} argument. May return @code{NULL} if @var{tc} is empty. @end deftypefun @deftypefun {ScmDictEntry *} Scm_TreeCorePopBound (ScmTreeCore *@var{tc}, ScmTreeCoreBoundOp @var{op}) Finds the entry in @var{tc} with the minimum or maximum key, as specified by @var{op} argument, and removes the entry from @var{tc}, then returns the entry. If @var{tc} is empty, no operation is performed and @code{NULL} is returned. @end deftypefun @deftypefun int Scm_TreeCoreNumEntries (ScmTreeCore *@var{tc}) Returns the number of entries in @var{tc}. @end deftypefun @subsubheading Iterators @deftp {Struct} ScmTreeIter An iterator over a tree map. This is not an @code{ScmObj}. Must be treated as opaque structure. An iterator can point to one of the entries in a tree core, or @code{NULL}. The @code{NULL} indicates the iterator is outside of the tree---it's both below the minimum key and above the maximum key simultaneously. That is, when an iterator points to @code{NULL}, when you call @code{Scm_TreeIterNext} you'll get the minimum key entry, while you call @code{Scm_TreeIterPrev} and you'll get the maximum key entry. You can modify the value of the entries while iterating over a tree map; however, once an entry is added or deleted, the behavior of existing iterators become undefined. @end deftp @deftypefun void Scm_TreeIterInit (ScmTreeIter *@var{iter}, ScmTreeCore *@var{tc}, ScmDictEntry *@var{start}) Initializes an iterator @var{iter} over a tree core @var{tc}. If @var{start} is NULL, the iterator is set just before the smallest entry in @var{tc} (i.e. the next call to @var{Scm_TreeCoreNext} will return the smallest entry); otherwise, the iterator points the given entry (i.e. the next call to @var{Scm_TreeCoreNext} will return the next entry of @var{start}). In the latter case, @var{start} must points to an entry in @var{tc}, otherwise an error is signalled. @end deftypefun @deftypefun {ScmDictEntry *} Scm_TreeIterCurrent (ScmTreeIter *@var{iter}) Returns the entry the iterator currently pointing. Can be @code{NULL}. @end deftypefun @deftypefun int Scm_TreeIterAtEnd (ScmTreeIter *@var{iter}) Returns @code{TRUE} iff the iterator has been pointing inside the tree and now pointing @code{NULL} after calling either @code{ScmTreeIterNext} or @code{ScmTreeIterPrev}. If you call @code{ScmTreeIterNext} on an iterator that is "at end", it starts from the minimum key entry; likewise, @code{ScmTreeIterPrev} makes it starts from the maximum key entry. In either case, "at end" flag is cleared. @end deftypefun @deftypefun {ScmDictEntry *} Scm_TreeIterNext (ScmTreeIter *@var{iter}) @deftypefunx {ScmDictEntry *} Scm_TreeIterPrev (ScmTreeIter *@var{iter}) Moves the iterator to the next or previous entry and returns it, respectively. If the iterator was pointing the maximum (minimum) key entry before calling @code{Scm_TreeIterNext} (@code{Scm_TreeIterPrev}), @code{NULL} is returned and the iterator becomes "at end" state (i.e. @code{Scm_TreeIterAtEnd} returns @code{TRUE}). @end deftypefun @subsubheading Scheme TreeMap object @deftp {ScmObj} ScmTreeMap This is the Scheme's @code{} object. It contains @code{ScmTreeCore}, whose pointer can be obtained by the macro @code{SCM_TREE_MAP_CORE}. @end deftp @deftypefn {Macro} {ScmTreeMap *} SCM_TREE_MAP (ScmObj @var{obj}) Cast macro. @end deftypefn @deftypefn {Macro} int SCM_TREE_MAP_P (ScmObj @var{obj}) Type predicate. @end deftypefn @deftypefn {Macro} {ScmTreeCore *} SCM_TREE_MAP_CORE (ScmTreeMap *@var{obj}) Returns the pointer to the @code{ScmTreeCore} part in a tree map. @end deftypefn @deftypefn {Macro} {void *} SCM_TREE_MAP_DATA (ScmTreeMap *@var{obj}) Returns the opaque data in a tree map. @end deftypefn @deftypefun ScmObj Scm_MakeTreeMap (ScmTreeCoreCompareProc *@var{cmp}, void *@var{data}) Creates an instance of @code{} object, using the given comparison function and the opaque data. Although it is built on top of @code{ScmTreeCore}, it is supposed that @code{ScmTreeMap}'s entry always have @code{ScmObj} in both key and value. If C code violates that, the outcome will be undefined. (If you need to have a tree map with raw C pointers exposed to Scheme world, create your own type using @code{ScmTreeCore}.) @end deftypefun @deftypefun ScmObj Scm_TreeMapCopy (const ScmTreeMap *@var{src}) Returns a newly created tree map, whose content is a copy of the given tree map. @end deftypefun @deftypefun ScmObj Scm_TreeMapRef (ScmTreeMap *@var{tm}, ScmObj @var{key}, ScmObj @var{fallback}) Searches an entry with the given @var{key}, and returns its value. If there's no entry that has @var{key}, a value passed to @var{fallback} is returned (unlike Scheme-level @code{tree-map-get}, it doesn't signals an error). A standard way to take a specific action when no entry is found is to pass @code{SCM_UNBOUND} as @var{fallback}, since @code{SCM_UNBOUND} should never appear as the valid value. @example ScmObj v = Scm_TreeMapRef(tm, key, SCM_UNBOUND); if (SCM_UNBOUNDP(v)) /* no entry for the key */ @end example @end deftypefun @deftypefun ScmObj Scm_TreeMapSet (ScmTreeMap *@var{tm}, ScmObj @var{key}, ScmObj @var{val}, ScmObj @var{flags}) Sets @var{val} as the value of the entry that has @var{key}. @code{Flags} is a bitwise-OR of @code{ScmDictSetFlags}. Passing 0 to @var{flags} achieves the common action to modify the entry if it exists, and to create a new one otherwise. If @var{flags} has @code{SCM_DICT_NO_OVERWRITE} bit set, it won't modify the existing entry, and only adds a new one if the entry hasn't existed. If @var{flags} has @code{SCM_DICT_NO_CREATE}, it modifies if the entry exists, but do not add a new one otherwise. (The effect of specifying both bits is undefined). Returns the value of the entry of @var{key} after the operation, or @code{SCM_UNBOUND} iff @code{SCM_DICT_NO_CREATE} is given to the @var{flags} and no new entry is created. @end deftypefun @deftypefun ScmObj Scm_TreeMapDelete (ScmTreeMap *@var{tm}, ScmObj @var{key}) Deletes the entry that has @var{key}. If the entry has existed, returns its value. Otherwise, returns @code{SCM_UNBOUND}. @end deftypefun @deftypefun void Scm_TreeMapDump (ScmTreeMap *@var{tm}, ScmPort *@var{out}) This is for debugging. Dumps the content of tree map with its internal structure to the given port @var{out}. @end deftypefun @node Weak pointers, Exceptions, Dictionaries, C API reference @section Weak pointers @node Exceptions, Calling back to Scheme, Weak pointers, C API reference @section Exceptions @node Calling back to Scheme, Input and output, Exceptions, C API reference @section Calling back to Scheme @node Input and output, Loading programs, Calling back to Scheme, C API reference @section Input and output @menu * Built-in ports:: * Custom ports:: * Input:: * Output:: @end menu @node Built-in ports, Custom ports, Input and output, Input and output @subsection Built-in ports @subsubheading Opening and closing ports @deftypefun ScmObj Scm_OpenFilePort (const char *path, int flags, int buffering, int perm) Open a file named by @var{path}, and returns a newly created Scheme port associated with the file. The @code{name} slot of the created port is set as @var{path}. The @var{flags} and @var{perm} arguments are passed to @code{open(2)} as the second and third argument, respectively. The @var{buffering} argument may be either one of @code{SCM_PORT_BUFFER_FULL}, @code{SCM_PORT_BUFFER_LINE} or @code{SCM_PORT_BUFFER_NONE}, specifying the buffering mode. If a file couldn't be opened, @code{SCM_FALSE} is returned. The reason can be obtained from @code{errno}. @end deftypefun @deftypefun ScmObj Scm_MakePortWithFd (ScmObj name, int direction, int fd, int bufmode, int ownerp) Creates a Scheme port that read from or write to the specified file descriptor @var{fd}. The @var{name} argument is used for the port's @var{name} slot. You need to specify either @code{SCM_PORT_INPUT} or @code{SCM_PORT_OUTPUT} as the direction. The @var{buffering} argument may be either one of @code{SCM_PORT_BUFFER_FULL}, @code{SCM_PORT_BUFFER_LINE} or @code{SCM_PORT_BUFFER_NONE}, specifying the buffering mode. If @var{ownerp} is @code{TRUE}, the created Scheme port becomes the owner of the file descriptor; that is, when the Scheme port is closed, it closes the file descriptor, too. @end deftypefun @deftypefun ScmObj Scm_MakeInputStringPort (ScmString *@var{str}, int @var{privatep}) Returns a Scheme string port that reads from the given Scheme string. Corresponds to Scheme's @code{open-input-string}. If @var{privatep} is @code{TRUE}, the port is pre-locked by the current thread; i.e. no other threads can access this port, and the current thread avoids locking overhead. @end deftypefun @deftypefun ScmObj Scm_MakeOutputStringPort (int @var{privatep}) Returns a Scheme output string port that collects the stuff written to it. You can retrieve the result string by @code{Scm_GetOutputString()} below. Corresponds to Scheme's @code{open-output-string}. The @var{privatep} flag is the same as @code{Scm_MakeInputStringPort}. @end deftypefun @deftypefun ScmObj Scm_GetRemainingInputString (ScmPort *@var{port}, int @var{flags}) @var{port} must be an input string port created by @code{Scm_MakeInputStringPort}. Returns a newly-created Scheme string which contains the stuff in the original string which hasn't been read. By default, the result string is mutable, and complete as long as it doesn't contain illegal byte sequences. You may explicitly make it immutable and/or incomplete by giving string constructor flags (@code{SCM_STRING_IMMUTABLE} and/or @code{SCM_STRING_INCOMPLETE}) to the @var{flags} argument (@pxref{Strings}). @end deftypefun @deftypefun ScmObj Scm_GetOutputstring (ScmPort *@var{port}, int @var{flags}) Returns a newly-created Scheme string from the output string port @var{port}, created by @code{Scm_MakeOutputStringPort}. By default, the result string is mutable, and complete as long as it doesn't contain illegal byte sequences. You may explicitly make it immutable and/or incomplete by giving string constructor flags (@code{SCM_STRING_IMMUTABLE} and/or @code{SCM_STRING_INCOMPLETE}) to the @var{flags} argument (@pxref{Strings}). @end deftypefun @deftypefun void Scm_ClosePort (ScmPort *@var{port}) Close the port. If it is already closed, nothing is done. Closing port invokes a cleanup handler associated to the port. For example, buffered output port may flush its buffer in the handler. The cleanup handler may run a Scheme code, if the port is a procedural port. An error caused in a cleanup handler will raises Scheme exception (i.e. Scm_ClosePort may not return if an error is raised); such errors should be handled by Scheme error handling framework. @end deftypefun @subsubheading General port information @deftypefun ScmObj Scm_PortName (ScmPort *@var{port}) Returns the value of @code{name} slot of the port. If the port is a file port, its name contains the original pathname of the file. For other ports, the name field contains some description of ports only useful for debug messages. @end deftypefun @deftypefun int Scm_PortLine (ScmPort *@var{port}) Returns the value of @var{line} slot of the port. Most built-in port types keeps track of the line count, as far as (1) only character I/O is performed, and (2) no random-access operation is performed, on the port. If either of such operation is done on the port, the number returned from this function doesn't have meaning. Port line count begins with 1. @end deftypefun @deftypefun int Scm_PortFileNo (ScmPort *@var{port}) Returns the port's associated file descriptor number, if any. Returns -1 otherwise. @end deftypefun @subsubheading Locking ports @subsubheading Pre-created ports @deftypefn {Macro} ScmPort* SCM_CURIN @deftypefnx {Macro} ScmPort* SCM_CUROUT @deftypefnx {Macro} ScmPort* SCM_CURERR These macro returns the current input, output, and error port of the current VM, respectively. Corresponds to Scheme's @code{(current-input-port)}, @code{(current-output-port)}, and @code{(current-error-port)}. @end deftypefn @deftypefun ScmObj Scm_Stdin (void) @deftypefunx ScmObj Scm_Stdout (void) @deftypefunx ScmObj Scm_Stderr (void) These functions returns ports associated to file descriptor 0, 1, or 2, respectively. Generally you should use @code{SCM_CURIN} macro etc., described above, since they're in sync with Scheme-world's current ports. However, if you have a reason to access to stdio specifically, you may use these functions. @end deftypefun @node Custom ports, Input, Built-in ports, Input and output @subsection Custom ports There are two ways to extend port functionalities and creates your own port types. A @emph{fully virtual port} basically has all basic port I/O operations as virtual functions, so you can override those functionalities as you like. A @emph{virtual buffered port}, on the other hand, implements buffering by itself, and calls back your routines when it needs more data to read or it needs to flush the buffer. (See the @code{gauche.vport} entry of the Gauche Users' Reference for the Scheme counterparts of these custom ports) @subsubheading Fully virtual ports @deftypefun ScmObj Scm_MakeVirtualport (ScmClass *@var{klass}, int @var{direction}, const ScmPortVTable *@var{vtable}) Returns a newly created fully virtual port of class @var{klass}, which must be a subclass of @code{SCM_CLASS_PORT}. You need prepare the structure @var{vtable} to specify the behavior of the port. You can leave some of the fields NULL, if the functionality is not needed in the port's operation. The content of the @var{vtable} will be copied, so you don't need to keep it after the call of @code{Scm_MakeVirtualPort}. @example typedef struct ScmPortVTableRec @{ int (*Getb)(ScmPort *p); int (*Getc)(ScmPort *p); int (*Getz)(char *buf, int buflen, ScmPort *p); int (*Ready)(ScmPort *p, int charp); void (*Putb)(ScmByte b, ScmPort *p); void (*Putc)(ScmChar c, ScmPort *p); void (*Putz)(const char *buf, int size, ScmPort *p); void (*Puts)(ScmString *s, ScmPort *p); void (*Flush)(ScmPort *p); void (*Close)(ScmPort *p); off_t (*Seek)(ScmPort *p, off_t off, int whence); void *data; @} ScmPortVTable; @end example For a character input port, you must provide at least @code{Getc} procedure. For a binary input port, you must provide at least @code{Getb} and @code{Getz} procedures. For a general input port, on which binary or character input can be done, you must provide at least those three procedures. @code{Getb} should return an 8bit unsigned integer value read from the port, or @code{EOF} if the port has already reached EOF. @code{Getc} should return an @code{ScmChar} read from the port, or @code{SCM_CHAR_INVALID} if the port has already reached EOF. @code{Getz} should read at most @var{buflen} bytes from the port and store it in @var{buf}, then returns the number of bytes actually read. Returning @code{0} indicates the port has already reached EOF. For a character output port you must provide at least @code{Putc} and @code{Puts} procedures. For a binary output port you must provide at least @code{Putb} and @code{Putz} procedures. For a general output port you must provide at least those four procedures. @code{Putb} and @code{Putc} write a byte or a character to the port, respectively. @code{Putz} writes @var{size} bytes in @var{buf} to the port. @code{Puts} writes the content of the given Scheme string to the port. The @code{Ready} procedure is optional for an input port. If provided, it is called when @code{char-ready?} or @code{byte-ready?} Scheme procedure is called on the port (the @var{charp} is @code{TRUE} for @code{char-ready?}, and @code{FALSE} for @code{byte-ready?}). It must return @code{TRUE} if a character or a byte is ready to be read from the port, @code{FALSE} otherwise. If @code{Ready} procedure is not provided, the port is assumed to be always ready. The @code{Close} procedure is optional for a both input and output port. It is called when the port is closed (either explicitly by @code{Scm_ClosePort}, or implicitly by the port being garbage-collected). For output port, @code{Flush} procedure is called just before @code{Close}, so you don't need to care about flushing in this procedure. The @code{Flush} procedure is optional for an output port. It is called when an explicit flushing is requested to the port (such as @code{flush} Scheme procedure), or just before the @code{Close} procedure when the port is closed. It is important to note that @code{Close} and @code{Flush} procedures can be called in finalization stage of the port. That means (1) you cannot predict in which thread these procedures are called, and (2) at the time these procedures are called, the objects visible from these procedures may already be finalized. Extra care needs to be taken to deal with those irregular situations. The @code{Seek} procedure is called for seek operation (such as @code{port-seek} Scheme procedure). If you don't provide this, the port becomes unseekable. For all those procedures, error conditions should be reported by Scheme exception mechanism. Care should be taken not to leave the port in inconsistent state in case an exception is thrown. The @code{data} field may contain opaque data to be used in your custom port operations. Once the procedure port is created, the value of this data pointer can be accessed by the macro @code{SCM_PORT_VIRTUAL_DATA}. @end deftypefun @subsubheading Virtual buffered ports @node Input, Output, Custom ports, Input and output @subsection Input @node Output, , Input, Input and output @subsection Output @node Loading programs, System interface, Input and output, C API reference @section Loading programs @deftypefun ScmObj Scm_VMLoadFromPort (ScmPort *@var{port}, ScmObj @var{next_paths}, ScmObj @var{env}, int flags) This is a CPS API. The most basic function in the @code{load}-family. Read an expression from the given port and evaluates it repeatedly, until it reaches EOF. Then the port is closed. The port is locked by the calling thread until the operation terminates. The result of the last evaluation remains on VM. No matter how the load terminates, either normal or abnormal, the port is closed, and the current module is restored to the one when load is called. @var{Flags} argument is ignored for now, but reserved for future extension. @code{SCM_LOAD_QUIET_NOFILE} and @code{SCM_LOAD_IGNORE_CODING} won't have any effect for @code{Scm_LoadFromPort}; see @code{Scm_Load} below. @end deftypefun @deftypefun ScmObj Scm_FindFile (ScmString *@var{filename}, ScmObj *@var{paths}, ScmObj @var{suffixes}, int @var{flags}) Core function to search specified file from the search paths *@var{path}. Search rules are: @enumerate @item If given filename begins with @file{/}, @file{./} or @file{../}, the file is searched. @item If given filename begins with @file{~}, unix-style username expansion is done, then the resulting file is searched. @item Otherwise, the file is searched for each directory in *@var{paths}. @end enumerate If a file is found, it's pathname is returned. *@var{Path} is modified to contain the remains of load paths, which can be used again to find next matching filename. If @var{suffixes} is given, filename is assumed not to have suffix, and suffixes listed in @var{suffixes} are tried one by one. The elements in @var{suffixes} is directly appended to the @var{filename}; so usually it begins with dot. The following flag is effective in @var{flags}. Other flags are ignored. @table @code @item SCM_LOAD_QUIET_NOFILE If this flag is set, @code{Scm_FindFile} returns @code{SCM_FALSE} when it cannot find the file. If this flag is not set (default), @code{Scm_FindFile} raises an error. @end table @end deftypefun @node System interface, , Loading programs, C API reference @section System interface Gauche provides a few wrapper APIs for operating system interface to allow applications written without concerning @c ====================================================================== @node Creating new Scheme datatypes, Helper program reference, C API reference, Top @chapter Creating new Scheme datatypes @c ====================================================================== @node Helper program reference, Indices, Creating new Scheme datatypes, Top @chapter Helper program reference Several executable scripts are installed along Gauche. They are to help build and installation process. @menu * Managing packages:: * Simplifying build process:: * Gauche-config - configuration parameters:: * Gauche-install - alternative install script:: * Gauche-package - package manager:: @end menu @node Managing packages, Simplifying build process, Helper program reference, Helper program reference @section Managing packages @deffn {Command} gauche-package @var{operation} [@var{option} @dots{}] [@var{arg} ...] The @code{gauche-package} command is the front-end of managing Gauche extension packages. It can perform the various operations according to @var{operation} argument. @table @asis @item Download, compile and install packages @code{install}, @code{build}, @code{compile} @item Retrieve info about installed packages @code{list}, @code{reconfigure}, @code{make-gpd} @item Help package development @code{generate} @item Instruct @code{gauche-package} usage @code{help} @end table Among those operations, usually @code{install}, @code{build}, @code{list}, @code{generate} and @code{help} are used directly from the shell. Other operations are mainly invoked by @code{make} command. @end deffn @menu * gauche-package operations:: * Customizing gauche-package :: @end menu @node gauche-package operations, Customizing gauche-package , Managing packages, Managing packages @subsection gauche-package operations @deffn {Package Operation} gauche-package install [@var{options}] @var{tarball-path/url} This operation obtains the package source specified by @var{tarball-path/url}, then extracts the source, configures and builds, runs the tests, and installs the built package. Most of the time this is the only command required to install a Gauche extension package. The argument @var{tarball-path/url} may be a URL (http, https, and ftp are supported), or a path to the local file of gzip-compressed tarball of the package source. If it is a URL, @code{gauche-package} downloads it first. By default @code{gauche-package} uses the current working directory, but you can make it use specific directory by customizing @file{~/.gauche-package} (@pxref{Customizing gauche-package}). The following options are recognized by this operation. @deffn {Option} -n, --dry-run Shows shell commands to be executed, without running them. @end deffn @deffn {Option} -C, --configure-options=@var{options} Pass @var{options} to the @code{./configure} script. Overrides @code{-r}. The following command configures the package with the option @code{--prefix=/opt}. @example gauche-package install -C='--prefix=/opt' package.tgz @end example Those configure options are recorded in the package description file @end deffn @end deffn @node Customizing gauche-package , , gauche-package operations, Managing packages @subsection Customizing gauche-package @node Simplifying build process, Gauche-config - configuration parameters, Managing packages, Helper program reference @section Simplifying build process @deffn {Command} gauche-cesconv [options] [inputfile] @end deffn @node Gauche-config - configuration parameters, Gauche-install - alternative install script, Simplifying build process, Helper program reference @section @code{gauche-config} - configuration parameters @node Gauche-install - alternative install script, Gauche-package - package manager, Gauche-config - configuration parameters, Helper program reference @section @code{gauche-install} - alternative install script @node Gauche-package - package manager, , Gauche-install - alternative install script, Helper program reference @section @code{gauche-package} - package manager @c ====================================================================== @node Indices, , Helper program reference, Top @appendix Indices @c NODE 索引 @menu * Function and Macro Index:: * Type Index:: * Variable Index:: @end menu @node Function and Macro Index, Type Index, Indices, Indices @appendixsec Function and Macro Index @printindex fn @node Type Index, Variable Index, Function and Macro Index, Indices @appendixsec Type Index @printindex tp @node Variable Index, , Type Index, Indices @appendixsec Variable Index @printindex vr @contents @bye ;; Local variables: ;; outline-regexp: "@chap\\|@\\(sub\\)*section" ;; end: