Debian Codegraph @

doc/gauche-dev.texi

raw
1 @c EN
2 \input texinfo @c -*- mode: texinfo; coding: utf-8; -*-
3 @c JP
4 \input texinfo-ja @c -*- mode: texinfo; coding: utf-8; -*-
5 @c COMMON
6 @comment %**start of header
7 @documentencoding UTF-8
8 @c EN
9 @documentlanguage en
10 @setfilename gauche-deve.info
11 @settitle Gauche Developers' Reference
12 @dircategory The Algorithmic Language Scheme
13 @direntry
14 * Gauche Developers' Reference: (gauche-deve.info). Internals of Gauche
15 @end direntry
16 @c JP
17 @documentlanguage ja
18 @setfilename gauche-devj.info
19 @settitle Gauche Developers' Reference
20 @dircategory The Algorithmic Language Scheme
21 @direntry
22 * Gauche Developers' Reference (ja): (gauche-devj.info). Internals of Gauche
23 @end direntry
24 @c COMMON
25 @comment %**end of header
26
27 @titlepage
28 @c EN
29 @title Gauche Developers' Reference
30 @c JP
31 @title Gauche Developers' Reference
32 @c COMMON
33 @subtitle version @VERSION@
34 @author Shiro Kawai (shiro@@acm.org)
35
36 @page
37 @vskip 0pt plus 1filll
38 Copyright @copyright{} 2009-2024 Shiro Kawai <shiro@@acm.org>
39
40 @end titlepage
41
42 @node Top, Introduction, (dir), (dir)
43
44 @ifnottex
45 This document explains the internal guts of Gauche
46 for developers who want to extend Gauche functionality in C,
47 or to embed Gauche to other applications.
48 This manual is for version @VERSION@.
49 @end ifnottex
50
51 @menu
52 * Introduction::
53 * Getting started::
54 * Fundamental concepts::
55 * Real-life examples::
56 * C API reference::
57 * Creating new Scheme datatypes::
58 * Helper program reference::
59 * Indices::
60 @end menu
61
62 @c ======================================================================
63 @node Introduction, Getting started, Top, Top
64 @chapter Introduction
65
66 The core part of the Gauche runtime is written in C and provided
67 as a library, @file{libgauche}. This document explains how to
68 use it from C. Using C API, you can extend Gauche's
69 functionality (e.g. providing bindinds to the existing C library),
70 and also link @file{libgauche} to your application, making
71 Gauche as an embedded scripting language.
72
73 Gauche's C API is designed for efficiency, consistency,
74 simplicity and safety, roughly in this order of precedence.
75 That is, sometimes we omit a safety net for efficiency, or we provide
76 several different APIs, each of which is efficient for a particular
77 purpose, rather than simple generic interface with overhead.
78 By saying efficiency over safety doesn't mean Gauche has security
79 holes, but we do assume you know what you're doing. If you need
80 safety nets, you can write in Scheme and call it from C.
81
82 That said, it won't be too difficult to use Gauche's C API
83 as far as you know some fundamental design concepts.
84
85 We intend this document to serve both a programmer's guide
86 that explains such design concepts, and a programmer's reference
87 that describes every C API in detail.
88
89 The guide part begins with @ref{Getting started}, that shows
90 how to write a simple Gauche extension in C, as well as
91 a simple application that embeds Gauche. It gives an overview
92 of the whole process.
93
94 The following chapter, @ref{Fundamental concepts}, describes
95 the design behind the API. We strongly recommend you to
96 understand this chapter before trying to use Gauche C API
97 seriously. As we mentioned above, it is very easy to break
98 something without knowing those concepts.
99
100 The guide part concludes with @ref{Real-life examples}, that
101 explains pitfalls in the practical situations using excerpt
102 of the actual Gauche extension code.
103
104 The reference part consists of two chapters: @ref{C API reference}
105 lists all the public C API. @ref{Helper program reference}
106 explains several programs installed as a part of Gauche Scheme
107 system to help program development.
108
109 @c ======================================================================
110 @node Getting started, Fundamental concepts, Introduction, Top
111 @chapter Getting started
112
113 This chapter explains the basics of how to use Gauche C API
114 by several simple examples.
115
116 Although each example is too small to be practical value,
117 we try to present working code for each example, so that you
118 can actually play with it. We recommend you to read through
119 all examples, for we introduce new concepts in each step.
120
121 We deal with the advanced topics that arise in the practical
122 situation in @ref{Real-life examples}.
123
124 The prerequisites for building Gauche extension, besides
125 the basic compiler chain, are the followings. We assume
126 these are installed in your system.
127 @itemize @bullet
128 @item
129 Gauche 0.9.10 or later
130 @item
131 A compiler suite compatible to the one used to build @file{libgauche}.
132 @end itemize
133
134 @menu
135 * A trivial extension::
136 * Simple readline binding::
137 @end menu
138
139 @node A trivial extension, Simple readline binding, Getting started, Getting started
140 @section A trivial extension
141
142 @menu
143 * Generating skeletons::
144 * Building the trivial module::
145 * The templates explained::
146 * Introduction of the stub file::
147 @end menu
148
149 @node Generating skeletons, Building the trivial module, A trivial extension, A trivial extension
150 @subsection Generating skeletons
151
152 Let's create a Gauche extension that does nothing.
153
154 Gauche can generate a skeleton of the extension code
155 by @code{gauche-package generate} command. You give the
156 package name to the command-line argument (here we pick @code{trivial}).
157
158 @smallexample
159 % @b{ls trivial}
160 ls: trivial: No such file or directory
161 % @b{gauche-package generate trivial}
162 % @b{ls trivial}
163 configure package.scm trivial.c triviallib.stub
164 Makefile.in test.scm trivial.h trivial.scm
165 @end smallexample
166
167 The @code{gauche-package} command creates a directory @file{trivial},
168 and populates it with template files. The role of each file is shown
169 below.
170
171 @table @emph
172 @item Package description (@file{package.scm})
173 This file contains metainformation about the extension,
174 such as version, dependency, license or repository URL.
175
176 @item Glue code (@file{trivial.c} and @file{trivial.h})
177 If what you want to do is just to write C functions and make it
178 available from Scheme, the function definitions and declarations
179 would go to these files.
180
181 Even if what you want to do is just to write bindings to
182 an existing library, it is typical that you need small amount
183 of auxiliary management code, such as initializing the library
184 and allocating/freeing library-side data structures.
185
186 @item Stub file (@file{triviallib.stub})
187 This file is the bridge between C world and Scheme world.
188 You have to list C functions you want to make it visible from
189 Scheme world. Because of its nature, this file looks like
190 a mixture of Scheme code and C code fragments.
191
192 When the package is compiled, Gauche's helper scripts generate
193 a C file from a stub file, and compile it with other glue code
194 to generate a dynamically loadable object code, called DLL
195 (dynamically loadable library) or SO (shared object), depending
196 on the platform.
197
198 (Note: We're in middle of the process of retiring @file{*.stub} file;
199 instead, you'll be able to mix Scheme and C code in @file{*.scm} file
200 that will be compiled into DSO. The extensions bundled with the Gauche
201 distribution, and several Gauche extensions, have already been switched;
202 you can take a peek and maybe start trying it. The detailed specification
203 of this @emph{precompilation}, or ahead-of-time compilation, is still
204 fluid and may be changed in incompatible way, though.)
205
206 @item Module file (@file{trivial.scm})
207 This file typically defines Gauche modules and sets exported
208 symbols, and dynamically loads the compiled object code.
209 You may put auxiliary Scheme code in it.
210
211 @item Makefile template (@file{Makefile.in})
212 Gauche relies on the traditional build workflow---you run @file{configure}
213 script to generate @file{Makefile} that is tailored for your system.
214 Sticking to good old @code{make} makes it easy to incorporate
215 third party libraries.
216
217 @item Configure script (@file{configure})
218 This is a script that generates @file{Makefile} from @file{Makefile.in}.
219 Edit this if you need other files to be tailored, or need to test
220 other features on the platform.
221
222 We used to use GNU @code{autoconf} to generate @file{configure},
223 but we're moving away from it. GNU @code{autoconf} is a fine tool
224 with lots of practical knowledge had put into development, but its
225 premise is that you have limited set of tools on the platform where
226 you compile the software, and that limitation makes the pipeline
227 complicated.
228
229 When you build Gauche extension, we already know you have Gauche
230 installed, so we can use Gauche's features to do configuration
231 work instead of relying on shell and other limited set of command-line
232 tools. It is especially handy since we no longer need an extra
233 pass to generate @file{configure} from @file{configure.ac}. With
234 the power of Gauche you can write @file{configure} file directly,
235 and you can check it in to VCS. The users won't need @code{autoconf}
236 to build from the (unpreprocessed) source tree.
237
238 We try to match the interface of @file{configure} script to
239 @code{autoconf}-generated ones; it accepts most of the standard
240 options such as @code{--prefix}.
241
242 @item Unit test (@file{test.scm})
243 It is strongly encouraged to include unit test in your package,
244 and this file contains the skeleton of it. The package user
245 can run the test by @code{make check}.
246 @end table
247
248 @node Building the trivial module, The templates explained, Generating skeletons, A trivial extension
249 @subsection Building, testing and installing the trivial module
250
251 These auto-generated files are already buildable.
252 First, you need to
253 run the @file{configure} script to
254 generate @file{Makefile}, then run @code{make}.
255
256 @smallexample
257 % @b{cd trivial}
258 % @b{./configure}
259 checking for gosh... /usr/bin/gosh
260 checking for gauche-config... /usr/bin/gauche-config
261 checking for gauche-package... /usr/bin/gauche-package
262 checking for gauche-install... /usr/bin/gauche-install
263 checking for gauche-cesconv... /usr/bin/gauche-cesconv
264 configure: creating trivial.gpd
265 configure: creating Makefile
266 % @b{make}
267 /usr/bin/gauche-package compile --verbose trivial trivial.c triviallib.stub
268 @i{(... message truncated ...)}
269 % @b{ls}
270 Makefile config.log trivial.c trivial.o triviallib.o
271 Makefile.in configure trivial.gpd trivial.scm triviallib.stub
272 VERSION test.scm trivial.h trivial.so
273 @end smallexample
274
275 The build process creates @file{trivial.so}, the dynamically loadable
276 object file (the actual suffix may differ on some OSes).
277
278 Now it's ready to load the extension into Gauche. The skeleton code
279 defines a Scheme function @code{test-trivial}, which just returns
280 a string. Run the Gauche interpreter, load the @code{trivial} module,
281 and call @code{test-trivial} function. Note that you need to give
282 @code{-I.} option to @code{gosh}, so that Gauche can find the @file{trivial}
283 module files.
284
285 @smallexample
286 % @b{gosh -I.}
287 gosh> @b{(use trivial)}
288 gosh> @b{(test-trivial)}
289 "trivial is working"
290 gosh>
291 @end smallexample
292
293 You may have noticed a file @file{trivial.gpd}. The unfamiliar
294 suffix @code{gpd} stands for ``Gauche package description''.
295 It is created by @file{configure}, and records the name and version
296 of the package, and the configure options. It is installed as a part
297 of the package and will be used by @code{gauche-package} script
298 (e.g. @code{gauche-package list} lists the installed packages).
299
300 You can also run a unit test by @code{make check}.
301
302 @smallexample
303 % make check
304 /usr/bin/gosh -I. test.scm > test.log
305 Testing trivial ... passed.
306 @end smallexample
307
308 For now, it just checks if the compiled extension can be loaded,
309 and the integrity of the module. As you add APIs in the extension,
310 you're expected to add tests as well.
311
312 Finally, you can install the extension by @code{make install}.
313
314 @smallexample
315 % make install
316 /usr/bin/gauche-install -m 444 -T /usr/lib/gauche/site/include
317 /usr/bin/gauche-install -m 444 -T /usr/share/gauche/site/lib trivial.scm
318 /usr/bin/gauche-install -m 555 -T /usr/lib/gauche/site/0.8.8/i686-pc-linux-gnu trivial.so
319 /usr/bin/gauche-install -m 444 -T /usr/share/gauche/site/lib/.packages trivial.gpd
320 @end smallexample
321
322 By default, the files are installed in the site-specific area
323 reserved within the installed Gauche.
324 If you want to change the install location, you can do the
325 same as typical autoconfigured softwares; e.g. giving
326 @code{--prefix} option to the @code{configure} script.
327
328 @node The templates explained, Introduction of the stub file, Building the trivial module, A trivial extension
329 @subsection The templates explained
330
331
332
333
334
335 @node Introduction of the stub file, , The templates explained, A trivial extension
336 @subsection Introduction of the stub file
337
338
339
340 @node Simple readline binding, , A trivial extension, Getting started
341 @section Simple readline binding
342
343
344
345
346
347
348
349
350
351 @c ======================================================================
352 @node Fundamental concepts, Real-life examples, Getting started, Top
353 @chapter Fundamental concepts
354
355 @menu
356 * Naming convention::
357 * Scheme types and C types::
358 * Memories::
359 * The VM::
360 * CPS API::
361 @end menu
362
363 @node Naming convention, Scheme types and C types, Fundamental concepts, Fundamental concepts
364 @section Naming convention
365
366 @c Memo:
367 @c Scm_XXXXSet(XXXX xxxx, ...) - operation to modify xxxx.
368 @c Scm_SetXXXX(...) - operation to modify some global (or per-vm) value.
369
370 @node Scheme types and C types, Memories, Naming convention, Fundamental concepts
371 @section Scheme types and C types
372
373 @node Memories, The VM, Scheme types and C types, Fundamental concepts
374 @section Memories
375
376 @node The VM, CPS API, Memories, Fundamental concepts
377 @section The VM
378
379
380
381
382 @node CPS API, , The VM, Fundamental concepts
383 @section CPS API
384
385
386
387
388 @c ======================================================================
389 @node Real-life examples, C API reference, Fundamental concepts, Top
390 @chapter Real-life examples
391
392 To be written. Meanwhile have a look at @file{examples/mqueue-cpp/README.adoc}
393 in the Gauche source tree.
394
395 @c ======================================================================
396 @node C API reference, Creating new Scheme datatypes, Real-life examples, Top
397 @chapter C API reference
398
399 In this chapter we describe most of public C APIs provided by
400 libgauche. We say `most' because the features to let you create
401 a new Scheme datatype requires dedicated chapter,
402 @ref{Creating new Scheme datatypes}.
403
404 @menu
405 * Representation of Scheme objects::
406 * Initialization and cleanup::
407 * Memory allocation and GC::
408 * Booleans::
409 * Numbers::
410 * Pairs and lists::
411 * Symbols::
412 * Glocs::
413 * Modules::
414 * Characters::
415 * Character sets::
416 * Strings::
417 * Regular expressions::
418 * Vectors::
419 * Dictionaries::
420 * Weak pointers::
421 * Exceptions::
422 * Calling back to Scheme::
423 * Input and output::
424 * Loading programs::
425 * System interface::
426 @end menu
427
428 @node Representation of Scheme objects, Initialization and cleanup, C API reference, C API reference
429 @section Representation of Scheme objects
430
431 @deftp {Type} ScmObj
432 Scheme objects are uniformly treated as of type @code{ScmObj},
433 which may be either a tagged pointer to a heap allocated object
434 or a tagged immediate value.
435
436 Most Scheme objects are heap allocated, and except Scheme pairs,
437 heap allocated Scheme object has a fixed header. We don't go
438 into more details here, but we'll revisit this topic in
439 @ref{Creating new Scheme datatypes}. Certain frequently used
440 Scheme objects, such as boolean values, small exact integers
441 and characters, are encoded in a word without allocating
442 objects in heap, and we call them @emph{immediate values}.
443
444 Querying the type of a Scheme object and accessing its fields
445 should be done via provided macros or APIs. The user code must
446 treat @code{ScmObj} as an opaque word, since the internal
447 representation may change.
448
449 The standard way to treat @code{ScmObj} value is (1) check to see
450 if its type matches what you expect, and (2) cast @code{ScmObj} to
451 the actual type and use it, as the following example shows.
452
453 @example
454 void your_C_function(ScmObj arg)
455 @{
456 if (SCM_STRINGP(arg)) @{ /* check */
457 ScmString *s = SCM_STRING(arg); /* cast */
458 do_whatever_you_like_with_scheme_string(s);
459 @} else @{
460 SCM_TYPE_ERROR(arg, "a string");
461 @}
462 @}
463 @end example
464
465 The @code{SCM_TYPE_ERROR} macro raises an error reporting
466 "a string is required for arg, but got ...". That's a convenient
467 way to report the wrong type argument. See @ref{Exceptions}
468 for more details of reporting errors.
469
470 Although it is not always checked explicitly, the programmer should
471 keep in mind that C's @code{NULL} is never a valid value for @code{ScmObj}.
472 If a C API requires @code{ScmObj} as an argument, you shouldn't pass
473 @code{NULL} to it. Also if your function returns @code{ScmObj},
474 you should make sure it will never return @code{NULL}.
475 @end deftp
476
477 @deftypefn {Macro} ScmObj SCM_OBJ (void *@var{obj})
478 Typecast @var{obj} to @code{ScmObj}. @var{Obj} must be
479 a pointer to an actual Scheme object.
480 @end deftypefn
481
482 We describe a few special constant Scheme objects here:
483
484 @deftypevr {Macro} ScmObj SCM_EOF
485 The Scheme's @code{#<eof>} object.
486 @end deftypevr
487
488 @deftypevr {Macro} ScmObj SCM_UNDEFINED
489 The Gauche's @code{#<undef>} object. In Gauche, it is used as a
490 placeholder where the value itself doesn't matter. At the time of
491 writing this document, there's a discussion in the next Scheme standard
492 to define @emph{the `unspecified' value} for this purpose, and it is
493 likely that this value will become such a value.
494 @end deftypevr
495
496 @deftypevr {Macro} ScmObj SCM_UNBOUND
497 This is a special value only seen in C world, and used to indicate
498 that a variable hasn't got a Scheme value assigned. For example,
499 if a Scheme procedure with an optional argument is defined in C,
500 and no value is passed to the optional argument, @code{SCM_UNBOUND}
501 is given in C world. This value should never be leaked out to
502 Scheme world.
503 @end deftypevr
504
505 @deftypefn {Macro} int SCM_EOFP (ScmObj @var{obj})
506 @deftypefnx {Macro} int SCM_UNDEFINEDP (ScmObj @var{obj})
507 @deftypefnx {Macro} int SCM_UNBOUNDP (ScmObj @var{obj})
508 Predicates to check whether the given @var{obj} is @code{SCM_EOF},
509 @code{SCM_UNDEFINED}, or @code{SCM_UNBOUND}, respectively.
510 @end deftypefn
511
512 @node Initialization and cleanup, Memory allocation and GC, Representation of Scheme objects, C API reference
513 @section Initialization and cleanup
514
515 This section explains how to initialize Gauche scheme runtime,
516 and how to clean it up.
517
518 These functions are for the applications that uses Gauche as
519 an embedded Scheme engine; when you're writing Gauche extensions,
520 you don't (and shouldn't) use these functions.
521
522 @subsubheading Initialization
523
524 @deftypefun void Scm_Init (const char *@var{signature})
525 Initializes the runtime. Must be called before any other
526 Gauche API call.
527
528 To @var{signature}, you should always
529 pass a macro @code{GAUCHE_SIGNATURE}. It is used to check a
530 proper version of Gauche shared library is linked. If you
531 have several version of Gauche libraries (e.g. different
532 encoding or thread configuration), accidentally linking
533 unintended version would cause mysterious runtime crash.
534 If the signature doesn't match the library's, this function
535 exits the process with a message explaining it.
536 @end deftypefun
537
538 @subsubheading Cleanup and termination
539
540 @deftypefun void Scm_Exit (int @var{code})
541 Exits the process with @var{code} as the exit code.
542 Calling @code{Scm_Exit} is the easiest way to terminate Gauche
543 application safely. It runs pending dynamic handlers,
544 registered cleanup handlers (see below), flushes output ports,
545 then calls @code{exit(2)} to exit.
546
547 Directly calling @code{exit(2)} would skip all those cleanup
548 process.
549 @end deftypefun
550
551 @deftypefun void Scm_Cleanup (void)
552 Cleans up the Scheme runtime just like @code{Scm_Exit()},
553 but does not call @code{exit(2)} at the end. This is useful
554 for applications that want to shut down Gauche runtime but
555 need to continue running.
556
557 Once you call @code{Scm_Cleanup()}, you shouldn't use any
558 other Gauche functions.
559
560 It is harmless to call @code{Scm_Cleanup()} more than once;
561 it becomes no-op from the second time and after.
562 @end deftypefun
563
564 @deftypefun void Scm_Panic (const char *@var{msg}, @dots{})
565 The @var{msg} and other arguments are treated like @code{printf(3)}.
566 Formats and displays the formatted message, then exits the process
567 by calling @code{_exit(2)} with exit code 1. No cleanup is done.
568
569 This is called when a serious defect is detected in the Gauche
570 runtime and cannot continue normal operation in any way.
571 @end deftypefun
572
573 @deftypefun void Scm_Abort (const char *@var{msg})
574 Writes @var{msg} to file descriptor 2, and exits the process
575 by calling @code{_exit(2)} with exit code 1. No cleanup is done.
576
577 This is the last resort of emergency exit, where you cannot
578 even call @code{malloc} reliably.
579 @end deftypefun
580
581 @subsubheading Cleanup handlers
582
583 You can register functions to be called when Gauche runtime
584 is shut down. The registered functions are called by
585 @code{Scm_Exit()} or @code{Scm_Cleanup()} in the reverse
586 order of their registration.
587
588 @deftypefun {void *} Scm_AddCleanupHandler (void (*@var{h})(void *), void *@var{d})
589 Adds a function @var{h} to the cleanup handler chain, with an opaque
590 data pointer @var{d}. At the cleanup time, @var{h} is called
591 with @var{d} as the single argument.
592
593 Returns an opaque handle, which can be passed to DeleteCleanupHandler.
594 @end deftypefun
595
596 @deftypefun void Scm_DeleteCleanupHandler (void *@var{handle})
597 Delete cleanup handler. The @var{handle} argument should be an opaque pointer
598 returned from @code{Scm_AddCleanupHandler}. (But it won't complain if
599 other pointer is given; it just does nothing.)
600 @end deftypefun
601
602 @node Memory allocation and GC, Booleans, Initialization and cleanup, C API reference
603 @section Memory allocation and GC
604
605 Memories allocated by using the following macros are owned
606 by Gauche runtime and managed by the garbage collector.
607
608 @subsubheading Allocator macros
609
610 There's two kind of allocators; ordinary ones and
611 @emph{atomic} ones. Here the term @emph{atomic} means
612 the allocated memory would never contain pointers
613 the collector needs to trace. For example, when you
614 allocate memory for a character string, you can use
615 atomic allocator since the memory won't contain any
616 pointers.
617
618 It is important to use atomic versions whenever possible.
619 Gauche's GC is conservative, which means if there's a
620 word that looks like a pointer in a live object, the collector assumes
621 it is a pointer and retains the memory chunk pointed by it.
622 If it is not really a pointer, the collector may retain
623 unnecessary memory chunks. It is called false pointers.
624 Telling the collector that a chunk of memory never contains
625 traceable pointer you can reduce the chance of false pointers.
626
627 It is OK for the atomic memory chunk to contain a pointer,
628 as far as the pointed chunk is reachable by other means,
629 or you can allow the pointed chunk to be collected (like
630 weak pointers).
631
632 Note: The term @emph{atomic} here probably came from the
633 fact that such a memory chunk is a terminal node, or an atom,
634 in the graph the collector traverses. It has nothing to
635 do with the atomic operations.
636
637 @deftypefn {Macro} {@var{TYPE} *} SCM_NEW (@var{TYPE})
638 @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC (@var{TYPE})
639 Allocates memory for datatype @var{TYPE} and returns its pointer.
640 @code{ATOMIC} version allocates the memory as an atomic chunk.
641 @end deftypefn
642
643 @deftypefn {Macro} {@var{TYPE} *} SCM_NEW_ARRAY (@var{TYPE}, size_t @var{nelts})
644 @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC_ARRAY (@var{TYPE}, size_t @var{nelts})
645 Allocates memory for an array of size @var{nelts} of datatype @var{TYPE},
646 and returns its pointer.
647 @end deftypefn
648
649 @deftypefn {Macro} {@var{TYPE} *} SCM_NEW2 (@var{TYPE}, size_t @var{size})
650 @deftypefnx {Macro} {@var{TYPE} *} SCM_NEW_ATOMIC2 (@var{TYPE}, size_t @var{size})
651 Allocates memory of @var{size} bytes, and returns it as a pointer to
652 the datatype @var{TYPE}.
653 @end deftypefn
654
655 Note: to allocate a Scheme object for the class that is inheritable
656 from Scheme, you should use @code{SCM_ALLOCATE} macro to do some
657 extra initialization. It is described in @ref{Creating new Scheme datatypes}.
658 You don't need to worry about it as far as you uses provided set
659 of Scheme datatypes, for each of them have a special "make" function
660 such as @code{Scm_MakeString}, @code{Scm_MakeVector}, etc.
661
662 @subsubheading Garbage collection
663
664 The garbage collector runs implicitly whenever it is necessary.
665 However, you can run it explicitly by this function:
666
667 @deftypefun void Scm_GC (void)
668 Triggers full GC.
669 @end deftypefun
670
671
672
673 @subsubheading Finalizers
674
675 @deftypefun void Scm_RegisterFinalizer (ScmObj @var{obj}, ScmFinalizerProc @var{finalizer}, void *@var{data})
676 Register the function @var{finalizer} to be called by the garbage
677 collector after the object @var{obj} is determined as dead. The function will
678 be given two arguments, the object and @var{data}.
679
680 GC works as this: After sweeping phase it has a set of unreachable objects.
681 If an unreachable object has a finalizer, it queues the object
682 in ``to-be-finalized'' list. Gauche's VM checks the queue occasionally
683 and processes them if it's not empty.
684
685 You should consider a finalizer as an asynchronous callback, much like
686 Scheme-level signal handlers. It is guaranteed to be called when VM
687 state is consistent (thus you can call back Gauche API safely from
688 the finalizer) and outside of GC (thus you can allocate inside
689 the finalizer), but you can't assume much more.
690
691 If @var{obj} points to another objects that's also being garbage collected,
692 that objects might already be finalized when @var{obj}'s finalizer
693 is called. So you have to make finalizers set the objects to harmless
694 state, and you also have to check the case
695 objects referred from @var{obj} are in such state.
696
697 You can't choose which thread will call the finalizer. Any thread that
698 allocates may call the finalizer.
699
700 You can resurrect @var{obj} by storing a pointer to it in some root set.
701 GC doesn't immediately put back @var{obj} to a free memor pool
702 after the finalizer is run; basically
703 it leaves @var{obj}'s fate to the finalizer. If the finalizer doesn't keep
704 references to @var{obj}, then @var{obj} will be reclaimed in @emph{next}
705 GC cycle, for it isn't pointed from live objects.
706 Note that GC unregisters finalizer of @var{obj} when it
707 chains @var{obj} to ``to-be-finalized'' list. So when the finalizer
708 is called, @var{obj} no longer has a finalizer.
709
710 Last but not least, there's no guarantee that the finalizer is called
711 promptly after @var{obj} lost all live references,
712 or whether it is called at all. There might be an indefinite delay
713 between the point when @var{obj} becomes a garbage and the finalizer is run.
714 You should think finalizers as a safety-net, rather than a guaranteed clean-up
715 mechanism. If your object requires explicit clean-up, ask users to do it
716 explicitly (possibly wrapping it with @code{call-with-*} style procedure).
717 Finalizers are for back up when the user fails to do so.
718 @end deftypefun
719
720 @deftypefun void Scm_UnregisterFinalizer (ScmObj @var{obj})
721 @end deftypefun
722
723 @node Booleans, Numbers, Memory allocation and GC, C API reference
724 @section Booleans
725
726 @deftypevr {Macro} ScmObj SCM_TRUE
727 @deftypevrx {Macro} ScmObj SCM_FALSE
728 Scheme's @code{#t} and @code{#f}.
729 @end deftypevr
730
731 @deftypefn {Macro} int SCM_TRUEP (ScmObj @var{obj})
732 @deftypefnx {Macro} int SCM_FALSEP (ScmObj @var{obj})
733 Predicates to check whether the given @var{obj} is @code{SCM_TRUE} or
734 @code{SCM_FALSE}, respectively. Note that @code{!SCM_FALSEP(obj)}
735 is different from @code{SCM_TRUEP(obj)}. Since Scheme treats anything
736 other than @code{#f} as a true value, usually what you need is
737 @code{SCM_FALSEP}. You use @code{SCM_TRUEP} only iff you want
738 to make sure the object is @code{#t}.
739 @end deftypefn
740
741 @deftypefn {Macro} int SCM_BOOLP (ScmObj @var{obj})
742 Returns @code{TRUE} iff @var{obj} is either @code{SCM_FALSE} or
743 @code{SCM_TRUE}.
744 @end deftypefn
745
746 @deftypefn {Macro} int SCM_BOOL_VALUE (ScmObj @var{obj})
747 Converts Scheme value to C boolean value. Returns @code{FALSE}
748 iff @var{obj} is @code{#f}.
749 @end deftypefn
750
751 @deftypefn {Macro} ScmObj SCM_MAKE_BOOL (@var{obj})
752 Converts C boolean value to a Scheme boolean value.
753 Returns @code{SCM_FALSE} if @var{obj} is @code{FALSE},
754 and @code{SCM_TRUE} for any other values.
755 @end deftypefn
756
757 @deftypefn {Macro} int SCM_EQ (ScmObj @var{x}, ScmObj @var{y})
758 Compares two Scheme objects are the same, in the sense of
759 Scheme's @code{eq?}. You should always use this macro
760 instead of comparing two Scheme objects by @code{==}.
761 @end deftypefn
762
763 @deftypefun int Scm_EqP (ScmObj @var{x}, ScmObj @var{y})
764 A function version of @code{SCM_EQ}.
765 @end deftypefun
766
767 @deftypefun int Scm_EqvP (ScmObj @var{x}, ScmObj @var{y})
768 Scheme's @code{eqv?}.
769 @end deftypefun
770
771 @deftypefun int Scm_EqualP (ScmObj @var{x}, ScmObj @var{y})
772 Scheme's @code{equal?}. Note: this function may call back VM recursively.
773 @end deftypefun
774
775 @deftypefun int Scm_EqualM (ScmObj @var{x}, ScmObj @var{y}, int @var{mode})
776 A convenient function to write functions with parameterized
777 equivalence procedure. @var{Mode} may be one of the following
778 constants:
779 @table @code
780 @item SCM_CMP_EQ
781 Compare using @code{eq?}
782 @item SCM_CMP_EQV
783 Compare using @code{eqv?}
784 @item SCM_CMP_EQUAL
785 Compare using @code{equal?}
786 @end table
787 @end deftypefun
788
789
790
791 @node Numbers, Pairs and lists, Booleans, C API reference
792 @section Numbers
793
794 @menu
795 * Scheme number objects::
796 * Number predicates::
797 * Converting C and Scheme numbers::
798 * Generic arithmetics::
799 * Subtype-specific number operations::
800 * Reading and writing numbers::
801 @end menu
802
803 @node Scheme number objects, Number predicates, Numbers, Numbers
804 @subsection Scheme number objects
805
806 @subsubheading C representation of numbers
807
808 Gauche uses several different structures to represent Scheme
809 numbers. Because of this polymorphic nature, the Scheme numbers
810 are almost always passed as @code{ScmObj}, except special occasions.
811 In Scheme level you usually don't need to think much
812 about different types of numbers, for Gauche automatically
813 converts them as needed. There are C routines that accept
814 generic Scheme numbers like Scheme, but from time to time
815 you need to check the actual type of the number and cast it
816 from @code{ScmObj} to the actual structure.
817
818 Currently Gauche has the following C-level representations.
819
820 @table @emph
821 @item Fixnum
822 For small Scheme exact integers (30 or 62 bit signed integer
823 in 32 or 64 bit
824 architectures, respectively), we encode its immediate value into
825 a machine word.
826 @item Bignum
827 If a Scheme exact integer doesn't fit in fixnum, it is represented
828 as a bignum, by a @code{ScmBignum} structure.
829 @item Ratnum
830 A Scheme exact non-integral number is represented as a ratnum,
831 by a @code{ScmRatnum} structure.
832 @item Flonum
833 Scheme real numbers are represented as flonum, by @code{ScmFlonum}
834 structure.
835 @item Compnum
836 Scheme complex numbers are represented as compnum, by
837 a @code{ScmCompnum} structure.
838 @end table
839
840 It is important to not confuse these @emph{representations} and
841 Scheme numeric hierarchy: A Scheme real number can be represented
842 in either flonum, ratnum, bignum or fixnum, for example.
843 For each possible Scheme numeric type and exactness, the possible
844 C representation is shown in the table below:
845
846 @example
847 | exact | inexact |
848 --------+----------------------+---------------+
849 integer |fixnum, bignum |flonum |
850 | | |
851 rational|fixnum, bignum, ratnum|flonum |
852 | | |
853 real |fixnum, bignum, ratnum|flonum |
854 | | |
855 complex |fixnum, bignum, ratnum|flonum, compnum|
856 ________|______________________|_______________|
857 @end example
858
859 (Note: Exact real and exact complex are supported in a sense
860 that exact rational number is always a real and complex number
861 as well.)
862
863 @subsubheading Normalized form
864
865 One Scheme number may be represented by more than
866 one C types; for example, an exact integer can also
867 be represented in ratnum with its denominator as 1.
868
869 To make things simple and clean, there's one important
870 rule C-routine writers should know:
871 If your routine returns a Scheme number, it must be in
872 a @emph{normalized} form, i.e.:
873
874 @itemize @bullet
875 @item
876 If the number is an exact integer, it should be either
877 fixnum or bignum; if the value fits in fixnum, it should be
878 fixnum.
879 @item
880 Denominator of ratnum is always greater than 1. That is,
881 the sign of ratnum is the sign of its numerator.
882 @item
883 If the imaginary part of the number is 0.0, it must be
884 in flonum, rather than compnum.
885 @end itemize
886
887 (Note: here we use the term @emph{normalized} and @emph{denormalized}
888 in the sense that Scheme numbers should be represented in a simplest
889 possible C structure. It is unrelated to the term in
890 IEEE floating point number.)
891
892 Most C APIs expect normalized numbers, and return normalized one.
893 As far as you're using those APIs, you don't need to care about
894 normalization, or even how the number is represented in Scheme.
895
896 If you ever need to peek into the representation, or deal with
897 denormalized numbers, see @ref{Subtype-specific number operations}.
898 Carrying around a denormalized Scheme number should be limited
899 for intermediate results, and only when you find the overhead of
900 conversion is a problem. Generally such overhead is negligible
901 compared to other overheads. If you use denormalized numbers,
902 make sure normalize them before passing it back to the rest
903 of the world, or bad things will happen.
904
905 @subsubheading Conversions and clamping
906
907 Converting a Scheme number to a C number is a
908 tricky business. It's always possible that the Scheme number
909 you got may not fit into the desired C variable. There are several
910 options you can choose.
911
912 @itemize @bullet
913 @item
914 Error: Throws an error.
915 @item
916 Clamp: If the Scheme value falls out of the supported range
917 of C variable, use the closest representable value.
918 @item
919 Convert only when possible. If conversion is not possible, use
920 the Scheme value as-is. It is useful to provide a shortcut path
921 to improve performance.
922 @end itemize
923
924 Some C APIs take @var{clamp} argument to specify the behavior. The value
925 can be one of the following enums.
926
927 @deftp {Enum} ScmClampMode
928 @table @code
929 @item SCM_CLAMP_ERROR
930 An error is thrown if the given Scheme number doesn't fit
931 to the resulting C number.
932 @item SCM_CLAMP_HI
933 If the given Scheme number is too large to fit in the
934 resulting C number, the largest possible C number in the
935 result type is returned instead. If the given Scheme number
936 is too small, an error is signalled.
937 @item SCM_CLAMP_LO
938 If the given Scheme number is too small to fit in the
939 resulting C number, the smallest possible C number in the
940 result type is returned instead. If the given Scheme number
941 is too large, an error is signalled.
942 @item SCM_CLAMP_BOTH
943 Clamp both sides; with this argument, the API won't throw
944 an out-of-range error.
945 @item SCM_CLAMP_NONE
946 If the given Scheme number is out of the range, no conversion
947 is performed (an extra output argument tells you whether
948 it has happened or not).
949 @end table
950 @end deftp
951
952 See @var{Scm_GetIntegerClamp} below for a concrete example.
953
954 @node Number predicates, Converting C and Scheme numbers, Scheme number objects, Numbers
955 @subsection Number predicates
956
957 @deftypefn {Macro} int SCM_INTEGERP (ScmObj @var{obj})
958 Returns @code{TRUE} if @var{obj} is a Scheme exact integer; that is,
959 @var{obj} is either a fixnum or a bignum.
960 (The name is somewhat misleading. This is @emph{not} Scheme's @code{integer?}.
961 To check whether @var{obj} is an integer, regardless of exact or
962 inexact, use @code{Scm_IntegerP} below).
963 @end deftypefn
964
965 @deftypefn {Macro} int SCM_RATIONALP (ScmObj @var{obj})
966 Returns @code{TRUE} iff @var{obj} is a Scheme exact rational number; that is,
967 @var{obj} is either one of fixnum, bignum or ratnum.
968 @end deftypefn
969
970 @deftypefn {Macro} int SCM_REALP (ScmObj @var{obj})
971 Returns @code{TRUE} iff @var{obj} is a Scheme real number; that is,
972 @var{obj} is either one of fixnum, bignum, ratnum or flonum.
973 @end deftypefn
974
975 @deftypefn {Macro} int SCM_NUMBERP (ScmObj @var{obj})
976 Returns @code{TRUE} iff @var{obj} is a Scheme number,
977 that is, either a fixnum, bignum, ratnum, flonum, or compnum.
978 @end deftypefn
979
980 @deftypefun int Scm_IntegerP (ScmObj @var{num})
981 Returns @code{TRUE} iff @var{num} is (exact or inexact) integer.
982
983 Note: If @var{num} is a flonum with exponent larger than certain value,
984 @code{Scm_IntegerP} always returns @code{TRUE}, because of its limited
985 precision of mantissa.
986 @end deftypefun
987
988 @deftypefun int Scm_OddP (ScmObj @var{num})
989 Returns @code{TRUE} iff a Scheme (exact or inexact) integer is
990 an odd number. This throws an error if @var{num} is not an integer.
991 @end deftypefun
992
993 @deftypefun int Scm_FiniteP (ScmObj @var{obj})
994 @deftypefunx int Scm_IniniteP (ScmObj @var{obj})
995 @deftypefunx int Scm_NanP (ScmObj @var{obj})
996 Returns @code{TRUE} iff @var{obj} is a finite number,
997 an infinite number, or a NaN, respectively. It is an error if
998 @var{obj} is not a Scheme number object.
999 @end deftypefun
1000
1001 @node Converting C and Scheme numbers, Generic arithmetics, Number predicates, Numbers
1002 @subsection Converting C and Scheme numbers
1003
1004 @subsubheading Integers
1005
1006 @deftypefun ScmObj Scm_MakeInteger (long @var{i})
1007 @deftypefunx ScmObj Scm_MakeIntegerU (u_long @var{i})
1008 @deftypefunx ScmObj Scm_MakeInteger64 (int64_t @var{i})
1009 @deftypefunx ScmObj Scm_MakeIntegerU64 (uint64_t @var{i})
1010 Convert a C integer to a Scheme integer.
1011 Always returns a normalized number.
1012 @end deftypefun
1013
1014 @deftypefun long Scm_GetIntegerClamp (ScmObj obj, int clamp, int *oor)
1015 @deftypefunx u_long Scm_GetIntegerUClamp (ScmObj obj, int clamp, int *oor)
1016 @deftypefunx int Scm_GetInteger8Clamp (ScmObj obj, int clamp, int *oor)
1017 @deftypefunx u_int Scm_GetIntegerU8Clamp (ScmObj obj, int clamp, int *oor)
1018 @deftypefunx int Scm_GetInteger16Clamp (ScmObj obj, int clamp, int *oor)
1019 @deftypefunx u_int Scm_GetIntegerU16Clamp (ScmObj obj, int clamp, int *oor)
1020 @deftypefunx int32_t Scm_GetInteger32Clamp (ScmObj obj, int clamp, int *oor)
1021 @deftypefunx uint32_t Scm_GetIntegerU32Clamp (ScmObj obj, int clamp, int *oor)
1022 @deftypefunx int64_t Scm_GetInteger64Clamp (ScmObj obj, int clamp, int *oor)
1023 @deftypefunx uint64_t Scm_GetIntegerU64Clamp (ScmObj obj, int clamp, int *oor)
1024 Convert a Scheme number @var{obj} to a C integer.
1025 If @var{obj} is a FLONUM or a RATNUM, they are rounded to the nearest
1026 integer.
1027
1028 If the number @var{obj} can't be represented by the desired C integer type,
1029 the behavior depends on @var{clamp},
1030 which must be one of @code{ScmClampMode}. See above for how out-of-range
1031 value can be clamped. If the out-of-range value isn't clamped by @var{clamp}
1032 argument, @var{clamp} is not @code{SCM_CLAMP_ERROR}, and @var{oor} is not
1033 @code{NULL} then @code{*oor} is set to @code{TRUE} and 0 is returned.
1034 Otherwise, an error is thrown.
1035
1036 If @var{obj} is not a real number, an error is thrown.
1037 @end deftypefun
1038
1039 @deftypefun long Scm_GetInteger (ScmObj obj)
1040 @deftypefunx u_long Scm_GetIntegerU (ScmObj obj)
1041 @deftypefunx int Scm_GetInteger8 (ScmObj obj)
1042 @deftypefunx u_int Scm_GetIntegerU8 (ScmObj obj)
1043 @deftypefunx int Scm_GetInteger16 (ScmObj obj)
1044 @deftypefunx u_int Scm_GetIntegerU16 (ScmObj obj)
1045 @deftypefunx int32_t Scm_GetInteger32 (ScmObj obj)
1046 @deftypefunx uint32_t Scm_GetIntegerU32 (ScmObj obj)
1047 @deftypefunx int64_t Scm_GetInteger64 (ScmObj obj)
1048 @deftypefunx uint64_t Scm_GetIntegerU64 (ScmObj obj)
1049 These are actually macros, expand into
1050 @code{Scm_GetIntegerClamp(obj, SCM_CLAMP_ERROR, NULL)} etc.
1051 @end deftypefun
1052
1053 @subsubheading Rational numbers
1054
1055 @deftypefun ScmObj Scm_MakeRational (ScmObj numer, ScmObj denom)
1056 Numerator @var{numer} and denominator @var{denom} must both be
1057 exact integers, and @var{denum} must not be zero.
1058 This returns a simplest Scheme numebr of @code{numer/denom},
1059 that is, it simplifies the rational number as much as possible;
1060 it can even be an integer if @var{numer} is a multiple of @var{denom}.
1061 @end deftypefun
1062
1063 @deftypefun ScmObj Scm_MakeRatnum (ScmObj numer, ScmObj denom)
1064 Numerator @var{numer} and denominator @var{denom} must both be
1065 exact integers, and @var{denum} must not be zero.
1066 Returns a RATNUM of @code{numer/denom}. This doesn't do any
1067 simplification.
1068
1069 You should only use this to create an intermediate result, where
1070 you'll eventually simplify the result along the way.
1071 Whenever you create a number to return to the Scheme world,
1072 you should always use @code{Scm_MakeRational} above.
1073 @end deftypefun
1074
1075 @deftypefun ScmObj Scm_ReduceRational (ScmObj rational)
1076 The argument must be a Scheme rational number (exact integer or ratnum).
1077 Returns a simplified rational number, either in ratnum or integer.
1078 @end deftypefun
1079
1080 @deftypefun ScmObj Scm_Numerator (ScmObj n)
1081 @deftypefunx ScmObj Scm_Denominator (ScmObj n)
1082 The argument must be a Scheme real number (integer, ratnum or flonum).
1083 Returns its numerator and denominator, respectively.
1084 If the argument is a flonum, it is first converted to an exact
1085 number by @code{Scm_Exact}.
1086 @end deftypefun
1087
1088
1089 @subsubheading Real numbers
1090
1091 @deftypefun ScmObj Scm_MakeFlonum (double @var{d})
1092 Returns a flonum from C @code{double} value.
1093 @end deftypefun
1094
1095 @deftypefun ScmObj Scm_MakeFlonumToNumber (double @var{d}, int exactp)
1096 Returns a scheme number corresponds to C @code{double} value @var{d}.
1097 Unlike @code{Scm_MakeFlonum}, this routine returns a Scheme exact
1098 integer if @code{exactp} is not @code{FALSE},
1099 and @var{d} is an integer.
1100 @end deftypefun
1101
1102 @deftypefun double Scm_GetDouble (ScmObj @var{obj})
1103 Returns a C @code{double} value of Scheme real number @var{obj}
1104 (that means @var{obj} can be a Scheme integer or ratnum as well).
1105 If @var{obj} is not a Scheme real number, 0.0 is returned.
1106 If @var{obj} is a ratnum, the closest IEEE double floating point number
1107 is returned.
1108 If @var{obj} is a bignum or ratnum that can't be represented by @code{double},
1109 an infinity (positive or negative, depends on @var{obj}'s sign)
1110 is returned.
1111 @end deftypefun
1112
1113 @deftypefun ScmObj Scm_DecodeFlonum (double d, int *exp, int *sign)
1114 Decompose a C double value @var{d} into its mantissa, exponent and sign.
1115 Returns the mantissa as a Scheme exact integer, and stores the exponent
1116 and the sign (either -1 or 1) in the location pointed by
1117 @var{exp} and @var{sign}.
1118
1119 It returns Scheme integer since mantissa may not fit in @code{long}
1120 on 32bit platforms, and this was created before @code{int64_t} became
1121 available universally. On 64bit platforms, returned number is always
1122 a fixnum so no allocation occurs.
1123 @end deftypefun
1124
1125 @deftypefun double Scm_EncodeFlonum (ScmObj mant, int exp, int sign)
1126 Inverse of @code{Scm_DecodeFlonum}. Given mantissa (a Scheme exact integer),
1127 exponent and sign, returns a C double.
1128
1129 @var{sign} must be either -1 or 1, and @var{exp} must be greater than or
1130 equal to -1074 and less than or equal to 971. @var{mant} must be between
1131 2^52 (inclusive) and 2^53 (exclusive) if @var{exp} is greater than -1074,
1132 or between 0 (inclusive) and 2^52 (exclusive) if @var{exp} is -1074
1133 (denormalized number).
1134
1135 The returned value is @code{(@var{sign} * @var{mant} * 2^@var{exp})}.
1136
1137 Note that the exponent value is offset by the mantissa scale, so it is not
1138 the literal value stored in the exponent field of the IEEE double.
1139 @end deftypefun
1140
1141 @deftypefun int Scm_FlonumSign (double d)
1142 Returns -1 or 1, depending on the sign bit of @var{d}. This differs
1143 from @code{Scm_Sign} which returns 0 for both +0.0 and -0.0.
1144 @end deftypefun
1145
1146 @deftp {Type} ScmHalfFloat
1147 16-bit floating point number (1 bit sign, 5 bit exponent and 10-bit mantissa).
1148 This format is sometimes used in the image data.
1149 @end deftp
1150
1151 @deftypefun double Scm_HalfToDouble (ScmHalfFloat v)
1152 @deftypefunx ScmHalfFloat Scm_DoubleToHalf (double d)
1153 Convert between half float and C double.
1154 If the given double can't be represented in half float, it is mapped
1155 to infinities.
1156 @end deftypefun
1157
1158 @subsubheading Complex numbers
1159
1160 @deftypefun ScmObj Scm_MakeComplex (double @var{real}, double @var{imag})
1161 Returns a Scheme number @code{@var{real}+@var{imag}i}.
1162 The return value is normalized, so it may be just a flonum
1163 if @var{imag} is zero.
1164 @end deftypefun
1165
1166 @deftypefun ScmObj Scm_MakeComplexPolar (double @var{mag}, double @var{angle})
1167 Returns a Scheme number @code{@var{real}@@@var{imag}i}.
1168 The return value is normalized, so it may be just a flonum
1169 if the imaginary part of the number is zero.
1170 @end deftypefun
1171
1172 @deftypefun double Scm_RealPart (ScmObj @var{obj})
1173 @deftypefunx double Scm_ImagPart (ScmObj @var{obj})
1174 @deftypefunx double Scm_Magnitude (ScmObj @var{obj})
1175 @deftypefunx double Scm_Angle (ScmObj @var{obj})
1176 Returns real part, imaginary part, magnitude and angle of a Scheme number
1177 @var{obj}, which can be any number.
1178 @end deftypefun
1179
1180 @deftp {Type} ScmDoubleComplex
1181 @deftpx {Type} ScmFloatComplex
1182 @deftpx {Type} ScmHalfComplex
1183 C-world representation of compelx numbers, using @code{double}, @code{float}
1184 and @code{ScmHalfFloat} for each complenent, respectively.
1185 @end deftp
1186
1187 @deftypefun ScmDoubleComplex Scm_GetDoubleComplex (ScmObj z)
1188 @deftypefunx ScmFloatComplex Scm_GetFloatComplex (ScmObj z)
1189 @deftypefunx ScmHalfComplex Scm_GetHalfeComplex (ScmObj z)
1190 Converts a Scheme number object @var{z} (can be any Scheme number)
1191 to C-world complex representation.
1192 @end deftypefun
1193
1194 @deftypefun ScmObj Scm_DoubleComplexToComplex (ScmDoubleCompex z)
1195 @deftypefunx ScmObj Scm_FloatComplexToComplex (ScmFloatCompex z)
1196 @deftypefunx ScmObj Scm_HalfComplexToComplex (ScmHalfCompex z)
1197 Converts C-world complex representation to a Scheme number object.
1198 @end deftypefun
1199
1200 @subsubheading Exactness
1201
1202 @deftypefun ScmObj Scm_Exact (ScmObj obj)
1203 Scheme's @code{exact}. An error is thrown if @var{obj} is not a
1204 Scheme number object, an infinity, or a NaN.
1205 @end deftypefun
1206
1207 @deftypefun ScmObj Scm_Inexact (ScmObj obj)
1208 Scheme's @code{inexact}. An error is thrown if @var{obj} is not a
1209 Scheme number object. If @var{obj} is out of range where IEEE double
1210 can represent, an infinity object is returned.
1211 @end deftypefun
1212
1213
1214 @node Generic arithmetics, Subtype-specific number operations, Converting C and Scheme numbers, Numbers
1215 @subsection Generic arithmetics
1216
1217
1218 @subsubheading Exact integer operations
1219
1220 The following routines operates on Scheme exact integers. If
1221 the given @code{ScmObj} argument is not a Scheme exact integer,
1222 an error is signalled. For bitwise routines, an integer is
1223 regarded in 2's complement form in case if it is negative.
1224
1225 @deftypefun ScmObj Scm_LogAnd (ScmObj @var{x}, ScmObj @var{y})
1226 @deftypefunx ScmObj Scm_LogIor (ScmObj @var{x}, ScmObj @var{y})
1227 @deftypefunx ScmObj Scm_LogXor (ScmObj @var{x}, ScmObj @var{y})
1228 @deftypefunx ScmObj Scm_LogNot (ScmObj @var{x})
1229 Bitwise operations. Arguments must be Scheme exact integers.
1230 Returns a Scheme exact integer, each bit of which is logical
1231 @emph{and}, @emph{inclusive or}, @emph{exclusive or},
1232 and @emph{not} of the corresponding bit(s) of the argument(s).
1233 Correspond to Scheme @code{logand}, @code{logior},
1234 @code{logxor} and @code{lognot}, respectively.
1235 @end deftypefun
1236
1237 @deftypefun ScmObj Scm_Ash (ScmObj @var{x}, int @var{cnt})
1238 Arithmetic left shift of a Scheme exact integer @var{x} by @var{cnt} bits.
1239 If @var{cnt} is negative, it it shifts to right by @var{-cnt} bits.
1240 Corresponds to Scheme @code{ash}.
1241 @end deftypefun
1242
1243 @deftypefun int Scm_LogTest (ScmObj @var{x}, ScmObj @var{y})
1244 Returns @code{FALSE} if bitwise @emph{and} of two Scheme exact
1245 integers @var{x} and @var{y} yields zero, or @var{TRUE} otherwise.
1246 Corresponds to Scheme @code{logtest}.
1247 @end deftypefun
1248
1249 @deftypefun int Scm_LogBit (ScmObj @var{x}, int @var{b})
1250 Returns @code{TRUE} or @code{FALSE} if @var{b}-th bit of
1251 a Scheme exact integer @var{x} is set or not set, respectively.
1252 0-th bit is the least significant bit.
1253 Corresponds to Scheme @code{logbit}.
1254 @end deftypefun
1255
1256 @subsubheading General operations
1257
1258 @deftypefun ScmObj Scm_Abs (ScmObj @var{num})
1259 Returns the distance between 0 and @var{num}, which can
1260 be any number (including complex numbers). Exactness
1261 of @var{num} is preserved. An error is signalled if
1262 @var{num} is not a Scheme number.
1263 @end deftypefun
1264
1265 @deftypefun int Scm_Sign (ScmObj @var{num})
1266 @var{Num} must be a real number. Returns -1, 0, or 1
1267 when @var{num} is less than, equal to, or greater than zero,
1268 respectively. If @var{num} is not a Scheme real number,
1269 an error is signalled.
1270
1271 Note that this returns 0 for negative zero @code{-0.0}. To check
1272 the sign of zero, use @code{Scm_FlonumSign}.
1273 @end deftypefun
1274
1275 @deftypefun ScmObj Scm_Negate (ScmObj @var{num})
1276 @end deftypefun
1277
1278 @deftypefun ScmObj Scm_Reciprocal (ScmObj @var{num})
1279 @end deftypefun
1280
1281 @deftypefun ScmObj Scm_Add (ScmObj @var{arg1}, ScmObj @var{arg2})
1282 @deftypefunx ScmObj Scm_Sub (ScmObj @var{arg1}, ScmObj @var{arg2})
1283 @deftypefunx ScmObj Scm_Mul (ScmObj @var{arg1}, ScmObj @var{arg2})
1284 @deftypefunx ScmObj Scm_Div (ScmObj @var{arg1}, ScmObj @var{arg2})
1285 @end deftypefun
1286
1287 @deftypefun ScmObj Scm_Quotient (ScmObj @var{arg1}, ScmObj @var{arg2}, ScmObj *@var{rem})
1288 Returns @code{(quotient @var{arg1} @var{arg2})}.
1289 If @var{rem} is not NULL, the remainder is stored in @code{*rem}.
1290 @end deftypefun
1291
1292 @deftypefun ScmObj Scm_Modulo (ScmObj @var{arg1}, ScmObj @var{arg2}, int remainderp)
1293 @end deftypefun
1294
1295 @deftypefun ScmObj Scm_Expt (ScmObj @var{x}, ScmObj @var{y})
1296 @end deftypefun
1297
1298 @deftypefun int Scm_NumEq (ScmObj @var{x}, ScmObj @var{y})
1299 Returns @code{TRUE} iff two Scheme numbers are equal
1300 (same as Scheme's @code{=}).
1301 @end deftypefun
1302
1303 @deftypefun int Scm_NumCmp (ScmObj @var{x}, ScmObj @var{y})
1304 Returns @code{-1}, @code{0}, or @code{1}, where @code{x < y}, @code{x = y}
1305 or @code{x > y}, respectively. Arguments must be Scheme real numbers.
1306 @end deftypefun
1307
1308 @deftypefun void Scm_MinMax (ScmObj @var{arg0}, ScmObj @var{args}, ScmObj *@var{min}, ScmObj *@var{max})
1309 @end deftypefun
1310
1311 @deftp {Enum} ScmRoundMode
1312 @example
1313 enum ScmRoundMode @{
1314 SCM_ROUND_FLOOR,
1315 SCM_ROUND_CEIL,
1316 SCM_ROUND_TRUNC,
1317 SCM_ROUND_ROUND
1318 @};
1319 @end example
1320 @end deftp
1321
1322 @deftypefun ScmObj Scm_Round (ScmObj @var{num}, int @var{mode})
1323 Round a real number @var{num} to an integer.
1324 @end deftypefun
1325
1326
1327
1328 @node Subtype-specific number operations, Reading and writing numbers, Generic arithmetics, Numbers
1329 @subsection Subtype-specific number operations
1330
1331 @menu
1332 * Fixnum operations::
1333 * Bignum operations::
1334 * Flonum operations::
1335 * Compnum operations::
1336 @end menu
1337
1338 @node Fixnum operations, Bignum operations, Subtype-specific number operations, Subtype-specific number operations
1339 @subsubsection Fixnum operations
1340
1341 The following macros treat fixnums specifically.
1342 In most cases you should use generic versions above, so that
1343 you don't need to care about difference between fixnums and bignums,
1344 and normalization. However, if you know your Scheme number is
1345 mostly small and you need speed, these macros will be handy.
1346
1347 @deftypefn {Macro} int SCM_INTP (ScmObj @var{obj})
1348 Returns @code{TRUE} iff @var{obj} is a fixnum.
1349
1350 See @code{SCM_INTEGERP} (@pxref{Number predicates}),
1351 to see if @var{obj} is an exact integer (either a fixnum or a bignum).
1352 @end deftypefn
1353
1354 @deftypevr {Macro} int SCM_SMALL_INT_SIZE
1355 Number of bits (excluding sign bit) of an integer representable
1356 in fixnum. Currently it is 29 and 61 for 32 and 64-bit architectures,
1357 respectively.
1358 @end deftypevr
1359
1360 @deftypevr {Macro} long SCM_SMALL_INT_MAX
1361 @deftypevrx {Macro} long SCM_SMALL_INT_MIN
1362 Maximum and minimum integer values representable in fixnum.
1363 @end deftypevr
1364
1365 @deftypefn {Macro} int SCM_SMALL_INT_FITS (long @var{k})
1366 Returns @code{TRUE} iff @var{k} fits in fixnum.
1367 @end deftypefn
1368
1369 @deftypefn {Macro} long SCM_INT_VALUE (ScmObj @var{fixnum})
1370 Extracts (unboxes) an integer value from @var{fixnum}. You have to check
1371 whether @var{fixnum} is a fixnum or not before applying this.
1372 @end deftypefn
1373
1374 @deftypefn {Macro} ScmObj SCM_MAKE_INT (long @var{i})
1375 Boxes an integer value @var{i} to a fixnum. You have to make
1376 sure @var{i} is in the range representable by fixnum.
1377 @end deftypefn
1378
1379 @deftypefn {Macro} int SCM_UINTP (ScmObj @var{obj})
1380 A convenience macro to check if @var{obj} is a fixnum
1381 @emph{and} non-negative.
1382 @end deftypefn
1383
1384 @node Bignum operations, Flonum operations, Fixnum operations, Subtype-specific number operations
1385 @subsubsection Bignum operations
1386
1387 Again, it should generally be avoided to use bignums explicitly;
1388 generic integer routines should take care of most cases.
1389
1390 A bignum keeps the absolute value in array of @code{u_long}s,
1391 least significant word first.
1392 The sign is kept separately. It also keeps the number of
1393 words used.
1394
1395 There's one more constraint about normalization. Normalized
1396 bignum uses only as many words as necessary to represent the
1397 given number. That is, the most significant word should never
1398 be zero for normalized bignums. You may see denormalized
1399 bignums only in limited occasions, such as the intermediate
1400 results. Denormalized bignums should never be leaked out
1401 to other APIs or to the Scheme world.
1402
1403 @deftypefn {Macro} int SCM_BIGNUMP (ScmObj @var{obj})
1404 Returns @code{TRUE} iff @var{obj} is a bignum.
1405 @end deftypefn
1406
1407 @deftypefn {Macro} ScmBignum* SCM_BIGNUM (ScmObj @var{bignum})
1408 Cast @var{bignum} to @code{ScmBignum*}.
1409 @end deftypefn
1410
1411 @deftypefn {Macro} int SCM_BIGNUM_SIZE (ScmObj @var{bignum})
1412 Returns the number of words used in the bignum.
1413 @end deftypefn
1414
1415 @deftypefn {Macro} int SCM_BIGNUM_SIGN (ScmObj @var{bignum})
1416 Returns the sign (-1 or 1) of the bignum. If @var{bignum}
1417 is denormalized and contains zero, this macro returns 0.
1418 @end deftypefn
1419
1420 The following APIs are for internal use, and only available
1421 when you include @file{gauche/bignum.h}. You should need
1422 these only if you're implementing some basic bignum arithmetics.
1423
1424 @deftypefun ScmObj Scm_MakeBignumFromSI (long @var{val})
1425 @deftypefunx ScmObj Scm_MakeBignumFromUI (u_long @var{val})
1426 Converts C @code{long} or @code{u_long} value to a bignum.
1427 The result is always a bignum, even when @var{val} can fit
1428 in fixnum (i.e. the result can be denormalized).
1429 @end deftypefun
1430
1431 @deftypefun ScmObj Scm_MakeBignumFromUIArray (int @var{sign}, u_long *@var{values}, int @var{size})
1432 Creates a (possibly denormalized) bignum from the given @code{u_long}
1433 array of length @var{size}. @var{Size} must be greater than 0.
1434 The first word @var{Values} is for the least significant word.
1435
1436 If @var{sign} is not zero, its sign determines the sign of the bignum,
1437 and @code{values} are taken as absolute values. If @var{sign} is zero,
1438 this routine assumes @code{values} contains 2's complement form of
1439 the integer.
1440 @end deftypefun
1441
1442 @deftypefun ScmObj Scm_MakeBignumFromDouble (double @var{val})
1443 Returns a (possible denormalized) bignum that represents
1444 the integral part of @var{val}.
1445 @end deftypefun
1446
1447 @deftypefun {ScmBignum *} Scm_MakeBignumWithSize (int @var{size}, u_long @var{init})
1448 @end deftypefun
1449
1450 @deftypefun ScmObj Scm_BignumCopy (ScmBignum *@var{bignum})
1451 Copy the given @var{bignum}. The return value can be
1452 denormalized if @var{bignum} is denormalized.
1453 @end deftypefun
1454
1455 @deftypefun ScmObj Scm_NormalizeBignum (ScmBignum *@var{bignum})
1456 Returns a normalized Scheme integer from the given bignum.
1457 That is, the returned value can be fixnum if @var{bignum}
1458 is small enough. This also adjust the size of bignum if
1459 it contains leading zero words.
1460
1461 The routine that returns the number to the outside world should
1462 always use this routine to ensure a denormalized bignum would
1463 never be leaked out.
1464 @end deftypefun
1465
1466 @deftypefun long Scm_BignumToSI (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor})
1467 @deftypefunx u_long Scm_BignumToUI (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor})
1468 Converts a bignum to C @code{long} and @code{u_long}, respectively.
1469 The behavior when @var{bignum}
1470 is out of range is determined by @var{clamp} argument.
1471 The @code{bignum} argument must be a normalized bignum.
1472 @end deftypefun
1473
1474 @deftypefun ScmInt64 Scm_BignumToSI64 (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor})
1475 @deftypefunx ScmUInt64 Scm_BignumToUI64 (ScmBignum *@var{bignum}, ScmClampMode @var{clamp}, int *@var{oor})
1476 64-bit integer version of @code{Scm_BignumToSI} and
1477 @code{Scm_BignumToUI}.
1478 The @code{bignum} argument must be a normalized bignum.
1479 @end deftypefun
1480
1481 @deftypefun double Scm_BignumToDouble (ScmBignum *@var{bignum})
1482 Converts a bignum to C @code{double} value.
1483 The @code{bignum} argument must be a normalized bignum.
1484 @end deftypefun
1485
1486 @deftypefun ScmObj Scm_BignumNegate (ScmBignum *@var{bignum})
1487 Returns @code{-@var{bignum}}. The argument may be denormalized.
1488 The returned value is a normalized Scheme integer.
1489 @end deftypefun
1490
1491 @deftypefun int Scm_BignumCmp (ScmBignum *@var{bx}, ScmBignum *@var{by})
1492 Compares two normalized bignums. Returns -1 if @code{@var{bx} < @var{by}},
1493 0 if @code{@var{bx} = @var{by}}, and 1 if @code{@var{bx} > @var{by}}.
1494 @end deftypefun
1495
1496 @deftypefun int Scm_BignumAbsCmp (ScmBignum *@var{bx}, ScmBignum *@var{by})
1497 Compares absolute values of two normalized bignums.
1498 Returns -1 if @code{abs(@var{bx}) < abs(@var{by})},
1499 0 if @code{abs(@var{bx}) = abs(@var{by})},
1500 and 1 if @code{abs(@var{bx}) > abs(@var{by})}.
1501 @end deftypefun
1502
1503 @deftypefun ScmObj Scm_BignumAdd (ScmBignum *@var{bx}, ScmBignum *@var{by})
1504 @deftypefunx ScmObj Scm_BignumSub (ScmBignum *@var{bx}, ScmBignum *@var{by})
1505 @deftypefunx ScmObj Scm_BignumMul (ScmBignum *@var{bx}, ScmBignum *@var{by})
1506 Returns
1507 @code{(+ @var{bx} @var{by})},
1508 @code{(- @var{bx} @var{by})},
1509 and @code{(* @var{bx} @var{by})}, respectively.
1510 Both argument should be normalized.
1511 The return value is a normalized Scheme integer.
1512 @end deftypefun
1513
1514 @deftypefun ScmObj Scm_BignumAddSI (ScmBignum *@var{bx}, long @var{y})
1515 @deftypefunx ScmObj Scm_BignumSubSI (ScmBignum *@var{bx}, long @var{y})
1516 @deftypefunx ScmObj Scm_BignumMulSI (ScmBignum *@var{bx}, long @var{y})
1517 Returns
1518 @code{(+ @var{bx} @var{y})},
1519 @code{(- @var{bx} @var{y})},
1520 and @code{(* @var{bx} @var{y})}, respectively.
1521 @var{Bx} should be normalized.
1522 The return value is a normalized Scheme integer.
1523 @end deftypefun
1524
1525 @deftypefun ScmObj Scm_BignumDivRem (ScmBignum *@var{dividend}, ScmBignum *@var{divisor})
1526 Returns a cons of quotient and remainder of two bignums.
1527 Both bignums should be normalized. Returns normalized numbers.
1528 @end deftypefun
1529
1530 @deftypefun ScmObj Scm_BignumDivSI (ScmBignum *@var{dividend}, long @var{divisor}, long *@var{remainder})
1531 Returns a quotient of @var{dividend} divided by @var{divisor}.
1532 The remainder is stored in *@var{remainder}.
1533 @var{Dividend} should be normalized. Returns normalized number.
1534 @end deftypefun
1535
1536 @node Flonum operations, Compnum operations, Bignum operations, Subtype-specific number operations
1537 @subsubsection Flonum operations
1538
1539 @deftypefn {Macro} int SCM_FLONUMP (ScmObj @var{obj})
1540 Returns @code{TRUE} iff @var{obj} is a flonum.
1541
1542 Note: in most cases, you may want to use @code{SCM_REALP} instead
1543 of this; @code{Scm_GetDouble} can treat integers transparently.
1544 @end deftypefn
1545
1546 @deftypefun ScmObj Scm_DecodeFlonum (double @var{d}, int *@var{pexp}, int *@var{psign})
1547 Decompose C double value @var{d} into its mantissa, exponent and sign values.
1548
1549 The mantissa is returned as a Scheme integer (since it is 53bits in IEEE
1550 double-precision floating format, we cannot return it as C integer
1551 portably). Values of exponent and sign (-1 or 1) are stored in
1552 @code{*pexp} and @code{psign}.
1553
1554 Two special cases: If @var{d} is infinity, @code{SCM_TRUE} is returned,
1555 and @code{*psign} contains its sign (-1 or 1). If @var{d} is @code{NaN},
1556 @code{SCM_FALSE} is returned.
1557 @end deftypefun
1558
1559
1560 @node Compnum operations, , Flonum operations, Subtype-specific number operations
1561 @subsubsection Compnum operations
1562
1563 @deftypefn {Macro} int SCM_COMPLEXP (ScmObj @var{obj})
1564 Returns @code{TRUE} iff @var{obj} is a compnum.
1565 @end deftypefn
1566
1567 @deftypefn {Macro} double SCM_COMPLEX_REAL (ScmObj @var{compnum})
1568 @deftypefnx {Macro} double SCM_COMPLEX_IMAG (ScmObj @var{compnum})
1569 Access to real and imaginary part of the complex number
1570 @var{compnum}, which must be a compnum.
1571 @end deftypefn
1572
1573 @deftypefun ScmObj Scm_MakeCompnum (double @var{real}, double @var{imag})
1574 Returns a (possibly denormalized) compnum, whose real part is
1575 @var{real} and imaginary part is @var{imag}.
1576 @end deftypefun
1577
1578
1579
1580 @node Reading and writing numbers, , Subtype-specific number operations, Numbers
1581 @subsection Reading and writing numbers
1582
1583 @deftypefun ScmObj Scm_StringToNumber (ScmString *str, int radix, u_long flags)
1584 Scheme's @code{string->number}. Parse external representation of a Scheme
1585 number in @var{str}. If the argument can't be parsed as a number,
1586 @code{SCM_FALSE} is returned.
1587
1588 The @var{radix} argument specifies the default radix. If it isn't between
1589 between 2 to 36, inclusive, @code{SCM_FALSE} is returned.
1590 This setting may be overridden if the input contains explicit radix
1591 prefix (@code{#x} etc.)
1592
1593 The @var{flags} argument can be a logical or of the following bitmasks:
1594
1595 @table @code
1596 @item SCM_NUMBER_FORMAT_EXACT
1597 @itemx SCM_NUMBER_FORMAT_INEXACT
1598 If no explicit exactness prefix is in input, force the input to
1599 be parsed as an exact/inexact number. If neither of these flags
1600 is given, and no explicit exactness prefix is in input,
1601 the exactness is automatically deduced as the same rule as Gauche's
1602 reader---that is, if the input contains a decimal point and/or exponential
1603 notation, or the input is non-real complex number, it becomes inexact;
1604 otherwise, it becomes exact.
1605
1606 @item SCM_NUMBER_FORMAT_STRICT_R7RS
1607 Reject input that's not strictly follow R7RS syntax.
1608
1609 @item SCM_NUMBER_FORMAT_ALT_RADIX
1610 Do not allow @code{#@var{n}R} style radix prefix.
1611 @end table
1612 @end deftypefun
1613
1614 @deftypefun ScmObj Scm_NumberToString (ScmObj obj, int radix, u_long flags)
1615 Scheme's @code{number->string}. An error is thrown if @var{obj} isn't a
1616 number, or @var{radix} isn't between 2 and 10.
1617
1618 The @var{flags} argument can be a logical or of the following bitmasks:
1619
1620 @table @code
1621 @item SCM_NUMBER_FORMAT_USE_UPPER
1622 Use uppercase letters for digits greater than 10. The default is to use
1623 lower case.
1624
1625 @item SCM_NUMBER_SHOW_PLUS
1626 Prepend @code{+} sign in positive number.
1627
1628 @item SCM_NUMBER_FORMAT_ALT_RADIX
1629 Add a radix prefix.
1630
1631 @item SCM_NUMBER_FORMAT_ROUND_NOTATIONAL
1632 Use notational decimal rounding. See the @code{format} entry
1633 of Gauche's reference manual about notational rounding.
1634 @end table
1635 @end deftypefun
1636
1637
1638 @node Pairs and lists, Symbols, Numbers, C API reference
1639 @section Pairs and lists
1640
1641 @menu
1642 * Pair type and null::
1643 * List constructors::
1644 * List predicates::
1645 * List accessors and modifiers::
1646 * List utilities::
1647 @end menu
1648
1649 @node Pair type and null, List constructors, Pairs and lists, Pairs and lists
1650 @subsection Pair type and null
1651
1652 @deftp {Scheme Object} ScmPair
1653 Represents a Scheme pair.
1654
1655 It exposes @code{car} and @code{cdr} fields, but they should always be
1656 accessed via accessor functions or macros.
1657
1658 Some pairs are special and may have hidden fields.
1659 Also, Gauche may impose a special alignment requirements for pairs,
1660 so you should never define a variable of type ScmPair in your C code.
1661 Instead, use the constructor API such as @code{Scm_Cons()} to get
1662 an instance of ScmPair.
1663
1664 @example
1665 @{
1666 /* Don't do this, or a devil comes out of your nose. */
1667 ScmPair foo = @{ ... @};
1668
1669 /* Instead, you can do this: */
1670 ScmObj foo = Scm_Cons(...);
1671 @}
1672 @end example
1673 @end deftp
1674
1675 @deftypevr {Scheme Constant} ScmObj SCM_NIL
1676 A Scheme empty list, @code{()}.
1677 @end deftypevr
1678
1679 @node List constructors, List predicates, Pair type and null, Pairs and lists
1680 @subsection List constructors
1681
1682 @deftypefun ScmObj Scm_Cons (ScmObj car, ScmObj cdr)
1683 Allocates and returns a fresh pair of @var{car} and @var{cdr}.
1684 @end deftypefun
1685
1686 @deftypefun ScmObj Scm_Acons (ScmObj caar, ScmObj cadr, ScmObj cdr)
1687 Scheme's @code{acons}. Returns @code{(cons (cons caar cadr) cdr)}.
1688 @end deftypefun
1689
1690 @deftypefun ScmObj Scm_List (ScmObj elt, @dots{}, NULL)
1691 Returns a Scheme list of @var{elt}, @dots{}. The C argument must
1692 be terminated by NULL (note that NULL can never be a valid Scheme
1693 value).
1694 @end deftypefun
1695
1696 @deftypefun ScmObj Scm_Conses (ScmObj elt, @dots{}, NULL)
1697 Scheme's @code{cons*}.
1698 @end deftypefun
1699
1700 @deftypefun ScmObj Scm_VaList (va_list elts)
1701 @deftypefunx ScmObj Scm_VaCons (va_list elts)
1702 Vararg version of @code{Scm_List} and @code{Scm_Conses}.
1703 @end deftypefun
1704
1705 @deftypefun ScmObj Scm_ArrayToList (ScmObj *elts, ScmSize nelts)
1706 Takes a C array of @code{ScmObj}s of size @var{nelts},
1707 and returns a Scheme list that has @var{elts} as its elements.
1708 @end deftypefun
1709
1710 @deftypefun ScmObj Scm_ArrayToListWithTail (ScmObj *elts, ScmSize nelts, ScmObj tail)
1711 Takes a C array of @code{ScmObj}s of size @var{nelts}, and
1712 creates a Scheme list that has @var{elts} as its elements,
1713 and has @var{tail} in its tail.
1714 @end deftypefun
1715
1716 @deftypefun ScmObj *Scm_ListToArray (ScmObj list, ScmSize *nelts, ScmObj *store, int alloc)
1717 Converts a Scheme list to a C array of @code{ScmObj*}. An error is thrown
1718 if @var{list} is not a proper list.
1719
1720 You can pass in a storage to store the result, or let the function allocate.
1721
1722 If @var{store} is NULL, the function always allocate an @code{ScmObj*} array.
1723 The size of the array is stored in @code{*nelts}.
1724
1725 If @var{store} is not NULL, it must point to a writable memory of at least
1726 @code{sizeof(ScmObj) * (*nelts)}. If the length of @var{list} is
1727 smaller than or equal to @code{*nelts}, the result is stored in @code{*store},
1728 and @code{store} is returned. The value of @code{*nelts} is adjusted
1729 to contain the actual number of elements.
1730
1731 If the length of @var{list} is greater than @var{*nelts},
1732 the behavior depends on the @code{alloc} flag. If it is @code{FALSE},
1733 an error is thrown. Otherwise, a new storage is allocated, filled, and
1734 returned. The value of @code{*nelts} is ajusted to contain the actual
1735 number of elements.
1736 @end deftypefun
1737
1738 @deftypefn {Macro} ScmObj SCM_LIST1 (ScmObj a)
1739 @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b)
1740 @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b, c)
1741 @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b, c, d)
1742 @deftypefnx {Macro} ScmObj SCM_LIST1 (ScmObj a, b, c, d, e)
1743 Convenience macros to create a Scheme list of length 1 to 5.
1744 @end deftypefn
1745
1746 @deftypefun ScmObj Scm_MakeImmutablePair (ScmObj car, ScmObj cdr)
1747 Creates and returns an immutable pair. Immutable pair is almost
1748 indistinguishable from ordinary (mutable) pairs, except that it
1749 returns false for @code{Scm_ImmutablePairP()}, and it raises an error
1750 when its car or cdr is tried to be modified.
1751
1752 Immutable pairs take up more storage than ordinary pairs. Unless you
1753 have a specific reason to use immutable pairs, you don't need to
1754 worry about them.
1755 @end deftypefun
1756
1757 @deftypefn {Macro} void SCM_APPEND1 (ScmObj head, ScmObj tail, ScmObj obj)
1758 This macro captures an idiom of constructing a list from left to right.
1759
1760 The @var{head} and @var{tail} arguments must be a variable, initialized
1761 by @code{SCM_NIL}. This macro works like this:
1762
1763 @itemize @bullet
1764 @item
1765 If @var{head} is @code{SCM_NIL}, create a new pair whose car is @var{obj},
1766 and make @var{head} and @var{tail} both point to the pair.
1767 @item
1768 Otherwise, create a new pair whose car is @var{obj},
1769 set the cdr of @var{tail} to the new pair, then set @var{tail} to point
1770 the new pair.
1771 @end itemize
1772
1773 That is, @var{head} points to the first pair of the constructed list,
1774 and @var{tail} points to the last pair of the constructed list.
1775 @end deftypefn
1776
1777 @deftypefn {Macro} void SCM_APPEND (ScmObj head, ScmObj tail, ScmObj lis)
1778 This macro captures an idiom of constructing a list from left to right.
1779 Similar to @code{SCM_APPEND1}, but @var{lis} must be a proper Scheme list.
1780 It appends a list @var{lis} to the
1781 cdr of @var{tail} and make @var{tail} point to the last pair of @var{lis}.
1782 In other words, it splices @var{lis}.
1783 @end deftypefn
1784
1785
1786 @node List predicates, List accessors and modifiers, List constructors, Pairs and lists
1787 @subsection List predicates
1788
1789 @deftypefn {Macro} int SCM_NULLP (ScmObj obj)
1790 Return a true value iff @var{obj} is @code{SCM_NIL}.
1791 @end deftypefn
1792
1793 @deftypefn {Macro} int SCM_PAIRP (ScmObj obj)
1794 Return a true value iff @var{obj} is a Scheme pair.
1795
1796 Note: If @var{obj} is a lazy pair, it is forced by this macro.
1797 So once this macro returns true, you can assume @var{obj} is @code{ScmPair}.
1798 @end deftypefn
1799
1800 @deftypefn {Macro} int SCM_LISTP (ScmObj obj)
1801 Returns a true value iff @var{obj} is a Scheme pair or a Scheme emptylist.
1802 If @var{obj} is a lazy pair, it is forced.
1803
1804 Note that this doesn't check if @var{obj} is a proper list.
1805 @end deftypefn
1806
1807 @deftypefn {Macro} int SCM_PROPER_LIST_P (ScmObj obj)
1808 @deftypefnx {Macro} int SCM_DOTTED_LIST_P (ScmObj obj)
1809 @deftypefnx {Macro} int SCM_CIRCULAR_LIST_P (ScmObj obj)
1810 Returns a true value iff @var{obj} is a Scheme proper list,
1811 a Scheme dotted list, or a Scheme circular list, respectively.
1812
1813 These macros traverses the spine of @var{obj}, so all the lazy pairs
1814 are forced. Notably, if @var{obj} is an infinite lazy sequence
1815 these macros never returns.
1816 @end deftypefn
1817
1818 @deftypefun int Scm_ImmutablePairP (ScmObj obj)
1819 Returns a true value if @var{obj} is a pair and immutable.
1820 @end deftypefun
1821
1822
1823 @node List accessors and modifiers, List utilities, List predicates, Pairs and lists
1824 @subsection List accessors and modifiers
1825
1826 @deftypefun ScmObj Scm_Car (ScmObj obj)
1827 @deftypefunx ScmObj Scm_Cdr (ScmObj obj)
1828 @deftypefunx ScmObj Scm_Caar (ScmObj obj)
1829 @deftypefunx ScmObj Scm_Cadr (ScmObj obj)
1830 @deftypefunx ScmObj Scm_Cdar (ScmObj obj)
1831 @deftypefunx ScmObj Scm_Cddr (ScmObj obj)
1832 Scheme's @code{car} etc. If @var{obj} isn't a pair, an error is thrown.
1833 @end deftypefun
1834
1835 @deftypefun ScmObj Scm_SetCar (ScmObj obj)
1836 @deftypefunx ScmObj Scm_SetCdr (ScmObj obj)
1837 Scheme's @code{set-car!} and @code{set-cdr!}. If @var{obj} isn't a
1838 mutable pair, an error is thrown.
1839 @end deftypefun
1840
1841 @deftypefun ScmObj Scm_ListRef (ScmObj list, ScmSmallInt i, ScmObj fallback)
1842 @end deftypefun
1843
1844 @deftypefun ScmObj Scm_ListTail (ScmObj list, ScmSmallInt i, ScmObj fallback)
1845 @end deftypefun
1846
1847 @deftypefun ScmObj Scm_LastPair (ScmObj list)
1848 @end deftypefun
1849
1850 @deftypefn {Macro} void SCM_FOR_EACH (ScmObj var, ScmObj list) body
1851 This is a convenience macro to traverse a Scheme list. It is expanded
1852 into something like this:
1853
1854 @example
1855 for (var = list; SCM_PAIRP(var); var = Scm_Cdr(var)) body
1856 @end example
1857
1858 That is, @var{body} is executed while @var{var} holds each pair
1859 in the list.
1860 @end deftypefn
1861
1862 @node List utilities, , List accessors and modifiers, Pairs and lists
1863 @subsection List utilities
1864
1865 @deftypefun ScmSize Scm_Length (ScmObj obj)
1866 If @var{obj} is a Scheme proper list, returns its length. If
1867 @var{obj} is an emptylist, the length is 0.
1868
1869 If @var{obj} is a Scheme dotted list (which includes
1870 a non-pair, non-emptylist object), returns SCM_LIST_DOTTED, which
1871 is a negative integer constant.
1872
1873 If @var{obj} is a Scheme circular list, returns @code{SCM_LIST_CIRCULAR},
1874 which is a nevative integer constant.
1875 @end deftypefun
1876
1877 @deftypefun ScmObj Scm_CopyList (ScmObj list)
1878 Scheme's @code{copy-list}.
1879 Return a fresh copy of a Scheme proper or dotted list @var{list}.
1880 If @var{list} is circular, an error is thrown.
1881 @end deftypefun
1882
1883 @deftypefun ScmObj Scm_MakeList (ScmSmallInt len, ScmObj fill)
1884 Scheme's @code{make-list}.
1885 Creates a fresh @var{len}-element list, whose elements are all @var{fill}.
1886 @end deftypefun
1887
1888 @deftypefun ScmObj Scm_Append2 (ScmObj list, ScmObj obj)
1889 @deftypefunx ScmObj Scm_Append2X (ScmObj list, ScmObj obj)
1890 Concatenate @var{obj} after a Scheme proper list @var{list}.
1891 @code{Scm_Append2X} may destructively modify @var{list}.
1892 @end deftypefun
1893
1894 @deftypefun ScmObj Scm_Append (ScmObj args)
1895 This is rather Scheme's @code{concatenate}. Elements of @var{args}
1896 must be proper lists except the last one.
1897 @end deftypefun
1898
1899 @deftypefun ScmObj Scm_Reverse (ScmObj list)
1900 @deftypefunx ScmObj Scm_ReverseX (ScmObj list)
1901 @end deftypefun
1902
1903 @deftypefun ScmObj Scm_Reverse2 (ScmObj list, ScmObj tail)
1904 @deftypefunx ScmObj Scm_Reverse2X (ScmObj list, ScmObj tail)
1905 @end deftypefun
1906
1907 @deftypefun ScmObj Scm_Memq (ScmObj obj, ScmObj list)
1908 @deftypefunx ScmObj Scm_Memv (ScmObj obj, ScmObj list)
1909 Scheme's @code{memq} and @code{memv}. These won't throw an error,
1910 as long as @var{list} doesn't contain a lazy pair.
1911 @end deftypefun
1912
1913 @deftypefun ScmObj Scm_Member (ScmObj obj, ScmObj list, int cmpmode)
1914 Generalized member. The @var{cmpmode} argument must be either one
1915 of @code{SCM_CMP_EQ}, @code{SCM_CMP_EQV}, or @code{SCM_CMP_EQUAL},
1916 specifying the comparison should be done by @code{eq?}, @code{eqv?},
1917 or @code{equal}.
1918 @end deftypefun
1919
1920 @deftypefun ScmObj Scm_Assq (ScmObj obj, ScmObj list)
1921 @deftypefunx ScmObj Scm_Assv (ScmObj obj, ScmObj list)
1922 Scheme's @code{assq} and @code{assv}. These won't throw an error,
1923 as long as @var{list} doesn't contain a lazy pair.
1924 Non-pair elements in @var{list} are ignored.
1925 @end deftypefun
1926
1927 @deftypefun ScmObj Scm_Assoc (ScmObj obj, ScmObj list, int cmpmode)
1928 Generalized assoc. The @var{cmpmode} argument must be either one
1929 of @code{SCM_CMP_EQ}, @code{SCM_CMP_EQV}, or @code{SCM_CMP_EQUAL},
1930 specifying the comparison should be done by @code{eq?}, @code{eqv?},
1931 or @code{equal}.
1932 @end deftypefun
1933
1934 @deftypefun ScmObj Scm_Delete (ScmObj obj, ScmObj list, int cmpmode)
1935 @deftypefunx ScmObj Scm_DeleteX (ScmObj obj, ScmObj list, int cmpmode)
1936 @end deftypefun
1937
1938 @deftypefun ScmObj Scm_AssocDelete (ScmObj obj, ScmObj list, int cmpmode)
1939 @deftypefunx ScmObj Scm_AssocDeleteX (ScmObj obj, ScmObj list, int cmpmode)
1940 @end deftypefun
1941
1942 @deftypefun ScmObj Scm_DeleteDuplicates (ScmObj list, int cmpmode)
1943 @deftypefunx ScmObj Scm_DeleteDuplicatesX (ScmObj list, int cmpmode)
1944 @end deftypefun
1945
1946 @deftypefun ScmObj Scm_MonotonicMerge (ScmObj sequences)
1947 @end deftypefun
1948
1949
1950 @node Symbols, Glocs, Pairs and lists, C API reference
1951 @section Symbols
1952
1953 @deftp {Scheme Object} ScmSymbol
1954 Represents a Scheme symbol. Unlike Common Lisp,
1955 Gauche's symbol is merely an interned string. It keeps
1956 no other information than its name. Global binding
1957 is realized by modules that associate a symbol to
1958 a @emph{gloc}, which keeps the global value, defined
1959 modules, etc.
1960 @end deftp
1961
1962 @deftypevr {Scheme Class Constant} {ScmClass *} SCM_CLASS_SYMBOL
1963 A constant pointer pointing Gauche's @code{<symbol>} class.
1964 @end deftypevr
1965
1966 @deftypefn {Macro} {ScmSymbol *} SCM_SYMBOL (ScmObj @var{obj})
1967 Converts @code{ScmObj} to the pointer to a symbol.
1968 @end deftypefn
1969
1970 @deftypefn {Macro} int SCM_SYMBOLP (ScmObj @var{obj})
1971 @code{TRUE} iff @var{obj} is a symbol.
1972 Note: In recent Gauche, keywords are a subclass of symbols, and
1973 satisfies @code{SCM_SYMBOLP} too.
1974 @end deftypefn
1975
1976 @deftypefn {Macro} {ScmString *} SCM_SYMBOL_NAME (ScmObj @var{symbol})
1977 Returns the name of the symbol.
1978 @end deftypefn
1979
1980 @deftypefun ScmObj Scm_Intern (ScmString *@var{name})
1981 Creates and returns a symbol whose name is @var{name} and registers it in the
1982 internal hash table. If there's already a symbol with @var{name},
1983 new symbol isn't created, and the existing symbol is returned.
1984 @end deftypefun
1985
1986 @deftypefun ScmObj Scm_Gensym (ScmString *@var{prefix})
1987 Creates and returns an uninterned symbol, whose name is generated
1988 from @var{prefix} followed by some numbers. @var{Prefix} can be
1989 @code{NULL}, in which case the default prefix is used.
1990 @end deftypefun
1991
1992 @deftypefn {Macro} ScmObj SCM_INTERN (const char *@var{name})
1993 A convenience macro to create a symbol with the name @var{name}.
1994 Implemented as follows:
1995 @example
1996 Scm_Intern(SCM_STRING(SCM_MAKE_STR_IMMUTABLE(cstr)))
1997 @end example
1998 @end deftypefn
1999
2000 @node Keywords, , Symbols, Symbols
2001 @section Keywords
2002
2003 Keywords are almost the same as symbols; in fact,
2004 @code{ScmKeyword} is just a type alias of @code{ScmSymbol}.
2005 They do have different runtime types (@code{SCM_CLASS_KEYWORD} vs
2006 @code{SCM_CLASS_SYMBOL}), but in recent Gauche the keyword class
2007 is a subclass of the symbol class by default.
2008
2009 @deftp {Scheme Object} ScmKeyword
2010 Represents the Scheme keyword objects.
2011 @end deftp
2012
2013 @deftypevr {Scheme Class Constant} {ScmClass *} SCM_CLASS_KEYWORD
2014 A constant pointer pointing Gauche's @code{<keyword>} class.
2015 @end deftypevr
2016
2017 @deftypefn {Macro} {ScmKeyword *} SCM_KEYWORD (ScmObj @var{obj})
2018 Converts @code{ScmObj} to the pointer to a keyword.
2019 @end deftypefn
2020
2021 @deftypefn {Macro} int SCM_KEYWORDP (ScmObj @var{obj})
2022 @code{TRUE} iff @var{obj} is a keyword.
2023 @end deftypefn
2024
2025 @deftypefn {Macro} {ScmString *} SCM_KEYWORD_NAME (ScmObj @var{keyword})
2026 Returns the name of the keyword.
2027 @end deftypefn
2028
2029 @deftypefun ScmObj Scm_MakeKeyword (ScmString *@var{name})
2030 Scheme's @code{make-keyword}.
2031 Returns a keyword whose name is @var{name}. Note that preceding
2032 @code{:} is not a part of the keyword name.
2033 @end deftypefun
2034
2035 @deftypefun ScmObj Scm_GetKeyword (ScmObj @var{key}, ScmObj @var{list}, ScmObj @var{fallback})
2036 Scheme's @code{get-keyword}.
2037 This is actually a misnomer; @var{key} doesn't need to be a keyword, but
2038 can be any object.
2039 @end deftypefun
2040
2041 @deftypefun ScmObj Scm_DeleteKeyword (ScmObj @var{key}, ScmObj @var{list})
2042 Scheme's @code{delete-keyword}.
2043 This is actually a misnomer; @var{key} doesn't need to be a keyword, but
2044 can be any object.
2045 @end deftypefun
2046
2047 @deftypefun ScmObj Scm_DeleteKeywordX (ScmObj @var{key}, ScmObj @var{list})
2048 Scheme's @code{delete-keyword!}. @var{list} may be modified desctructively.
2049 This is actually a misnomer; @var{key} doesn't need to be a keyword, but
2050 can be any object.
2051 @end deftypefun
2052
2053 @deftypefn {Macro} ScmObj SCM_MAKE_KEYWORD (const char *@var{name})
2054 A convenience macro to create a keyword from C string @var{name}.
2055 Implemented as follows:
2056 @example
2057 Scm_MakeKeyword(SCM_STRING(SCM_MAKE_STR_IMMUTABLE(name)))
2058 @end example
2059 @end deftypefn
2060
2061 @deftypefn {Macro} ScmObj SCM_GET_KEYWORD (const char *@var{name}, ScmObj @var{list}, ScmObj @var{fallback})
2062 A convenience macro to search a value marked by a keyword whose name
2063 is specified by C string @var{name}.
2064 Implemented as follows:
2065 @example
2066 Scm_GetKeyword(SCM_MAKE_KEYWORD(name), list, fallback)
2067 @end example
2068 @end deftypefn
2069
2070
2071
2072 @node Glocs, Modules, Symbols, C API reference
2073 @section Glocs
2074
2075 A gloc, or global location, is a structure to keep the global
2076 value. A module maps a symbol to a gloc. Glocs are not directly
2077 used in the Scheme world (except in some introspection features),
2078 and even in the C world you don't usually need to deal with them.
2079 To get/set the value of a global variable, you can use
2080 @code{Scm_GlobalVariableRef} and @code{Scm_Define}, respectively
2081 (@pxref{Modules}).
2082
2083 @deftp {Scheme Object} ScmGloc
2084 Represents a gloc object.
2085 @end deftp
2086
2087 @deftypevr {Scheme Class Constant} {ScmClass *} SCM_CLASS_GLOC
2088 A constant pointer pointing Gauche's @code{<gloc>} class.
2089 @end deftypevr
2090
2091 @deftypefn {Macro} {ScmGloc *} SCM_GLOC (ScmObj @var{obj})
2092 Converts @code{ScmObj} to the pointer to a gloc.
2093 @end deftypefn
2094
2095 @deftypefn {Macro} int SCM_GLOCP (ScmObj @var{obj})
2096 @code{TRUE} iff @var{obj} is a gloc.
2097 @end deftypefn
2098
2099 @deftypefn {Macro} ScmObj SCM_GLOC_GET (ScmGloc *@var{gloc})
2100 Returns the global value of @var{gloc}. This may return
2101 @code{SCM_UNBOUND}; in such a case, the C routine must
2102 make sure it won't leak out to the Scheme world (usually
2103 the expected behavior is to raise an "undefined variable"
2104 error.
2105 @end deftypefn
2106
2107 @deftypefn {Macro} void SCM_GLOC_SET (ScmGloc *@var{gloc}, ScmObj @var{val})
2108 Sets the global value of @var{gloc} to @var{val}.
2109 This may raise an error if @var{gloc} is marked as a constant.
2110 @end deftypefn
2111
2112 @deftypefn {Macro} void SCM_GLOC_CONST_P (ScmGloc *@var{gloc})
2113 @code{TRUE} iff @var{gloc} is marked as a constant.
2114 @end deftypefn
2115
2116
2117 @node Modules, Characters, Glocs, C API reference
2118 @section Modules
2119
2120 @deftp {Scheme Object} ScmModule
2121 Represents the Scheme module objects.
2122 @end deftp
2123
2124 @deftypefun ScmModule *Scm_FindModule (ScmSymbol *name, int flags)
2125 @end deftypefun
2126
2127 @deftypefun ScmObj Scm_MakeModule (ScmSymbol *name, int error_if_exists)
2128 @end deftypefun
2129
2130 @deftypefun ScmObj Scm_GlobalVariableRef (ScmModule *module, ScmSymbol *symbol, int flags)
2131 @end deftypefun
2132
2133 @deftypefun ScmObj Scm_Define (ScmModule *module, ScmSymbol *symbol, ScmObj value)
2134 @deftypefunx ScmObj Scm_DefineConst (ScmModule *module, ScmSymbol *symbol, ScmObj value)
2135 @end deftypefun
2136
2137
2138
2139 @node Characters, Character sets, Modules, C API reference
2140 @section Characters
2141
2142 @deftp {Type} ScmChar
2143 A word large enough to hold all characters Gauche can handle.
2144 It is like @code{wchar_t}, but we chose to use our own type since
2145 the actual implementation of @code{wchar_t} varies among platforms
2146 which complicates implementation.
2147
2148 You can assume that within the range of ASCII characters, C's @code{char}
2149 and @code{ScmChar} have the same value; that is, you can safely cast
2150 C's ASCII character to @code{ScmChar}.
2151 If Gauche is compiled with utf-8 as internal character encoding,
2152 the value of @code{ScmChar} always matches unicode codepoint value.
2153
2154 Note that @code{ScmChar} is @emph{not} the representation of Scheme
2155 character; you stil need to box @code{ScmChar} value to pass a
2156 character to the Scheme world by the following macros.
2157 @end deftp
2158
2159 @deftypefn {Macro} ScmChar SCM_CHAR (@var{val})
2160 Typecast C value @var{val} to @code{ScmChar}.
2161 @end deftypefn
2162
2163 @deftypefn {Macro} int SCM_CHARP (ScmObj @var{obj})
2164 Predicate to check whether @var{obj} is a Scheme character or not.
2165 @end deftypefn
2166
2167 @deftypefn {Macro} ScmChar SCM_CHAR_VALUE (ScmObj @var{obj})
2168 Unbox @code{ScmChar} value from a Scheme character @var{obj}.
2169 @end deftypefn
2170
2171 @deftypefn {Macro} ScmObj SCM_MAKE_CHAR (ScmChar @var{val})
2172 Box @var{ScmChar} value to a Scheme character.
2173 @end deftypefn
2174
2175 @deftypevr {Macro} ScmChar SCM_CHAR_INVALID
2176 A value that can't be a valid character. Used in various
2177 situations to indicate there's no appropriate character.
2178 @end deftypevr
2179
2180 @deftypevr {Macro} ScmChar SCM_CHAR_MAX
2181 Maximum possible value of @code{ScmChar}.
2182 @end deftypevr
2183
2184 @deftp {Enum} Scm_IllegalCharHandling
2185 In some functions that have to deal with characters coming
2186 from outside world, you need to specify how they should behave
2187 when they meet a data chunk that does not consist a valid
2188 character in Gauche's native encoding. This enum specifies
2189 the behavior.
2190
2191 @table @code
2192 @item SCM_ILLEGAL_CHAR_REJECT
2193 Refuse to handle illegal chars.
2194 For ports this means raising an error.
2195 For string conversion procedure, this makes it to return
2196 some non-string value, such as @code{SCM_FALSE}.
2197 @item SCM_ILLEGAL_CHAR_OMIT
2198 Silently discard the illegal chars.
2199 @item SCM_ILLEGAL_CHAR_REPLACE
2200 Replace an illegal char to a substitute
2201 char, specified elsewhere.
2202 @end table
2203 @end deftp
2204
2205
2206 @deftypefn {Macro} int SCM_CHAR_ASCII_P (ScmChar @var{val})
2207 @deftypefnx {Macro} int SCM_CHAR_UPPER_P (ScmChar @var{val})
2208 @deftypefnx {Macro} int SCM_CHAR_LOWER_P (ScmChar @var{val})
2209 Like @code{isascii()}, @code{isupper()}, and @code{islower()}.
2210 We can't use standard functions on @code{ScmChar}, since
2211 @code{ScmChar} representation may be different from what
2212 the platform supports. Note that @var{val} may be used
2213 more than once in the expanded form.
2214 @end deftypefn
2215
2216 @deftypefn {Macro} ScmChar SCM_CHAR_UPCASE (ScmChar @var{val})
2217 @deftypefnx {Macro} ScmChar SCM_CHAR_DOWNCASE (ScmChar @var{val})
2218 Converts @code{ScmChar} to upper case or lower case character,
2219 respectively. Note that @var{val} may be used
2220 more than once in the expanded form.
2221 @end deftypefn
2222
2223 As of 0.8.8, @code{SCM_CHAR_UPPER_P}, @code{SCM_CHAR_LOWER_P},
2224 @code{SCM_CHAR_UPCASE} and @code{SCM_CHAR_DOWNCASE}
2225 only work properly on ASCII characters. For any other characters,
2226 the predicates return @code{FALSE}, and the converters
2227 return the passed value as is.
2228 It'll be extended to support larger character
2229 ranges according to Unicode character attributes.
2230
2231 @deftypefun int Scm_DigitToInt (ScmChar @var{ch}, int @var{radix})
2232 If a character @var{ch} represents a digit of a number in @var{radix},
2233 returns the value it represents. Otherwise, returns @code{-1}.
2234
2235 The valid range of @var{radix} is between 2 and 36, inclusive.
2236
2237 @example
2238 Scm_DigitToInt(SCM_CHAR('0'), 10) @result{} 0
2239 Scm_DigitToInt(SCM_CHAR('5'), 10) @result{} 5
2240 Scm_DigitToInt(SCM_CHAR('c'), 10) @result{} -1
2241 Scm_DigitToInt(SCM_CHAR('c'), 16) @result{} 12
2242 Scm_DigitToInt(SCM_CHAR('C'), 16) @result{} 12
2243 Scm_DigitToInt(SCM_CHAR('z'), 36) @result{} 35
2244 @end example
2245 @end deftypefun
2246
2247 @deftypefun ScmChar Scm_IntToDigit (int @var{n}, int @var{radix})
2248 Converts an integer to a character that represents that integer.
2249 in radix @var{radix} number. @var{Radix} must be between
2250 2 and 36 inclusive.
2251
2252 If @var{n} is outside of valid range, @code{SCM_CHAR_INVALID}
2253 is returned.
2254
2255 @example
2256 Scm_IntToDigit(0, 10) @result{} SCM_CHAR('0')
2257 Scm_IntToDigit(5, 10) @result{} SCM_CHAR('5')
2258 Scm_IntToDigit(10, 10) @result{} SCM_CHAR_INVALID
2259 Scm_IntToDigit(10, 16) @result{} SCM_CHAR('a')
2260 Scm_IntToDigit(35, 36) @result{} SCM_CHAR('z')
2261 @end example
2262 @end deftypefun
2263
2264 @deftypefun ScmChar Scm_UcsToChar (int @var{n})
2265 Converts unicode codepoint @var{n} to an @code{ScmChar} value.
2266 Since Gauche uses only utf-8 as internal encoding now, this is an identify
2267 function.
2268
2269 This function may return @code{SCM_CHAR_INVALID} if @var{n}
2270 can't be converted to a valid character in the native encoding.
2271 (Note that, however, this function does not perform exhaustive
2272 checking; if Gauche's internal encoding is utf-8, you can
2273 pass any value to @var{n} even if it is not a valid Unicode codepoint,
2274 and this function still returns @var{n} as is.)
2275 @end deftypefun
2276
2277 @deftypefun int Scm_CharToUcs (ScmChar @var{ch})
2278 Converts @code{ScmChar} value to Unicode codepoint. This function
2279 may return @code{-1}
2280 if @var{ch} can't be converted to Unicode codepoint.
2281 @end deftypefun
2282
2283 @deftypefun ScmObj Scm_CharEncodingname (void)
2284 Returns a Scheme symbol that represents Gauche's internal character encoding.
2285 As of 0.8.8, it may be either one of @code{utf-8},
2286 @code{euc-jp}, @code{sjis} or @code{none}.
2287 @end deftypefun
2288
2289 @deftypefun {const char **} Scm_SupportedCharacterEncodings (void)
2290 Returns a NULL-terminated array of C strings of character encoding names
2291 that are supported natively. Since an encoding can be upper-compatible
2292 to another encoding, there can be multiple supported encodings; for example,
2293 if Gauche is compiled with @code{utf-8} as native encoding, @code{ascii}
2294 and @code{iso-8859-1} are also supported since they are subset of
2295 Unicode.
2296
2297 An encoding can have several aliases (e.g. @code{iso-8859-1} is often
2298 referred as @code{latin-1}). To avoid complication, you should use
2299 @code{Scm_SupportedCharacterEncodingP} below to test whether the
2300 running Gauche supports a certain encoding or not.
2301 @end deftypefun
2302
2303 @deftypefun int Scm_SupportedCharacterEncodingP (const char *@var{encoding})
2304 Returns @code{TRUE} if a character encoding named by @var{encoding}
2305 is natively supported on the running Gauche. Returns @code{FALSE} otherwise.
2306
2307 @var{Encoding} is compared in case insensitive way, and certain
2308 variations (e.g. with or without hyphen) are allowed.
2309 @end deftypefun
2310
2311 @node Character sets, Strings, Characters, C API reference
2312 @section Character sets
2313
2314 @node Strings, Regular expressions, Character sets, C API reference
2315 @section Strings
2316
2317 @subheading Multibyte strings and thread safety
2318
2319 Gauche supports multibyte strings natively, so its C API just
2320 hides most complexities that come with multibyte encodings. You should
2321 treat Scheme strings as opaque objects and use provided APIs and macros
2322 to access their contents.
2323
2324 Because of multibyte nature, the size of the string measured in bytes
2325 can be different from the number of characters the string contains.
2326 In Gauche, we refer the size of a string in bytes as @emph{size},
2327 while the number of characters in a string as @emph{length}.
2328
2329 One important fact: Internally, Gauche treats string as immutable objects,
2330 @code{ScmStringBody}. Scheme standard requires string to be mutable,
2331 so we have a Scheme string (@code{ScmString}) keep a pointer to a
2332 string body, and when the Scheme string is modified, we allocate
2333 a new string body and switch the pointer in the Scheme string
2334 to the new body. You can now see it is disastrously inefficient to
2335 call @code{string-set!} repeatedly on a string in Gauche.
2336
2337 Note that, with preemptive multithreads, a Scheme string (@code{ScmString})
2338 can be mutated while another thread is accessing it. It is a problem for
2339 us, since string mutation can change the size (in bytes) of the string
2340 because of multibyte characters. If you obtain the size, then accesses
2341 the string content using the size, you don't want the size of the
2342 content to be changed in between.
2343 (This is not so much a problem for the implementations that use an
2344 array of fixed-size characters, since mutation is localized to a
2345 single character at a time.)
2346
2347 It is too expensive to use mutex for every string access.
2348 Immutability helps here;
2349 retrieving @code{ScmStringBody} from @code{ScmString} is an atomic
2350 operation, and once you get hold onto @code{ScmStringBody}, you don't
2351 need to worry about other threads because it will never be changed.
2352 All the properties of strings, such as its size, belong to
2353 @code{ScmStringBody} and not @code{ScmString}.
2354
2355 @example
2356 /* WRONG: Thread-unsafe code */
2357 void f(ScmString *s)
2358 @{
2359 int size = SCM_STRING_BODY_SIZE(SCM_STRING_BODY(s)); /* in bytes */
2360 const char *cstr = Scm_GetStringConst(s);
2361
2362 /* do something with size and cstr */
2363 @}
2364
2365 /* CORRECT: Thread-safe code */
2366 void f(ScmString *s)
2367 @{
2368 int size;
2369 const char *cstr = Scm_GetStringContent(s, &size, NULL, NULL);
2370
2371 /* do something with size and cstr */
2372 @}
2373
2374 /* CORRECT: This one is also thread-safe, though you need to
2375 scan the string twice. */
2376 void f(ScmString *s)
2377 @{
2378 const char *cstr = Scm_GetStringConst(s);
2379 int size = strlen(cstr);
2380
2381 /* do something with size and cstr */
2382 @}
2383 @end example
2384
2385 @subheading Datatype
2386
2387 @deftp {Scheme Object} ScmString
2388 Scheme string. It is merely a header that contains a pointer
2389 to @code{ScmStringBody}.
2390 @end deftp
2391
2392 @deftp {Type} ScmStringBody
2393 The body of the string. It is immutable---that is, once it
2394 is constructed, it should never be changed.
2395 @end deftp
2396
2397 @deftypevr {Constant} int SCM_STRING_IMMUTABLE
2398 @deftypevrx {Constant} int SCM_STRING_INCOMPLETE
2399 @deftypevrx {Constant} int SCM_STRING_COPYING
2400 Flags to specify the nature of the string and/or the behavior of
2401 the string constructor.
2402
2403 @table @code
2404 @item SCM_STRING_IMMUTABLE
2405 When passed to the constructor, it creates an immutable Scheme string.
2406 This flag is stored in the Scheme string and causes an error
2407 if you try to attempt to modify it.
2408
2409 @item SCM_STRING_INCOMPLETE
2410 When passed to the constructor, it creates an incomplete Scheme
2411 string (even the string doesn't contain illegal byte sequences).
2412 The Scheme string is also marked incomplete when the constructor
2413 found illegal byte sequences.
2414
2415 @item SCM_STRING_COPYING
2416 This is only used by the string constructor and not stored in
2417 the string object. This flag indicates the constructor to copy
2418 the content of the passed byte array. See @code{Scm_MakeString}
2419 below for the detailed explanation.
2420 @end table
2421 @end deftypevr
2422
2423 @deftypefn {Macro} int SCM_STRINGP (ScmObj @var{obj})
2424 Type predicate.
2425 @end deftypefn
2426
2427 @deftypefn {Macro} {ScmString *} SCM_STRING (ScmObj @var{obj})
2428 Typecast.
2429 @end deftypefn
2430
2431 @deftypefn {Macro} {const ScmStringBody *} SCM_STRING_BODY (ScmObj @var{str})
2432 Returns a pointer to the body of the Scheme string @var{str}.
2433 Note that the returned body is immutable.
2434 @end deftypefn
2435
2436 @deftypefn {Macro} int SCM_STRING_BODY_LENGTH (ScmStringBody *@var{body})
2437 @deftypefnx {Macro} int SCM_STRING_BODY_SIZE (ScmStringBody *@var{body})
2438 @deftypefnx {Macro} int SCM_STRING_BODY_FLAGS (ScmStringBody *@var{body})
2439 Query the parameters of the string body.
2440 @end deftypefn
2441
2442 @deftypefn {Macro} int SCM_STRING_BODY_HAS_FLAG (ScmStringBody *@var{body}, int @var{flag})
2443 Query if the string body has a flag, which is a bitwise OR
2444 of zero or more of the @code{SCM_STRING_*} flags.
2445 @end deftypefn
2446
2447 @deftypefn {Macro} int SCM_STRING_BODY_IMMUTABLE_P (ScmStringBody *@var{body})
2448 @deftypefnx {Macro} int SCM_STRING_BODY_INCOMPLETE_P (ScmStringBody *@var{body})
2449 Returns true iff the string body is immutable or incomplete, respectively.
2450 @end deftypefn
2451
2452 @deftypefn {Macro} int SCM_STRING_BODY_SYNGLE_BYTE_P (ScmStringBody *@var{body})
2453 Returns true iff the string consists of only single byte characters.
2454 @end deftypefn
2455
2456
2457 @subheading Constructors
2458
2459 @deftypefun ScmObj Scm_MakeString (const char *@var{str}, int @var{size}, int @var{len}, int @var{flags})
2460 Creates a new Scheme string, whose content, size (in bytes),
2461 and length (in characters) are given by @var{str}, @var{size} and
2462 @var{len}, respectively.
2463
2464 You can pass @code{-1} to @var{size}. In such case, @code{Scm_MakeString}
2465 assumes @var{str} is @code{NUL}-terminated string and calculates
2466 the size. If you pass an explicit size, @var{str} does not need
2467 to be @code{NUL}-terminated.
2468
2469 You can pass @code{-1} to @var{len}. In such case, @code{Scm_MakeString}
2470 counts characters in @var{str}. If you pass an explicit length,
2471 @code{Scm_MakeString} trust it---passing wrong number will cause
2472 lots of troubles.
2473
2474 C-string @var{str} is interpreted in the Gauche's native
2475 multibyte encoding. If you pass @code{-1} to @var{len},
2476 and @var{str} contains an illegal byte sequence as the
2477 native multibyte encoding, the created string becomes
2478 incomplete. You can also create an incomplete string
2479 explicitly by passing @code{SCM_STRING_INCOMPLETE} flag
2480 to @var{flags}.
2481
2482 @var{Flags} is a bitwise OR of the following bitmasks.
2483
2484 @table @code
2485 @item SCM_STRING_INCOMPLETE
2486 Creates an incomplete string, even if @var{str} contains
2487 only valid characters.
2488 @item SCM_STRING_IMMUTABLE
2489 Creates an immutable string. Immutable string would
2490 raise an error if used by mutating procedures.
2491 @item SCM_STRING_COPYING
2492 The content pointed by @var{str} is copied, so that the caller
2493 can free @var{str} after this call.
2494 Without this flag, the created string directly points the
2495 region passed by @var{str}, and it is managed by Gauche's garbage
2496 collector. That is, if @var{str} points a static data or the region
2497 you get by Gauche's allocators, you don't need this flag; while
2498 if @var{str} points the region you get by @code{malloc} or other
2499 means, you have to specify this flag.
2500 @end table
2501 @end deftypefun
2502
2503 @deftypefn {Macro} ScmObj SCM_MAKE_STR (const char *@var{cstr})
2504 A convenience macro, expanded as follows:
2505 @example
2506 Scm_MakeString(@var{cstr}, -1, -1, 0)
2507 @end example
2508 That is, the size and length are counted automatically, and
2509 @var{cstr} is not copied.
2510 @end deftypefn
2511
2512 @deftypefn {Macro} ScmObj SCM_MAKE_STR_COPYING (const char *@var{cstr})
2513 A convenience macro, expanded as follows:
2514 @example
2515 Scm_MakeString(@var{cstr}, -1, -1, SCM_STRING_COPYING)
2516 @end example
2517 That is, the size and length are counted automatically, and
2518 @var{cstr} is copied.
2519 @end deftypefn
2520
2521 @deftypefn {Macro} ScmObj SCM_MAKE_STR_IMMUTABLE (const char *@var{cstr})
2522 A convenience macro, expanded as follows:
2523 @example
2524 Scm_MakeString(@var{cstr}, -1, -1, SCM_STRING_IMMUTABLE)
2525 @end example
2526 @end deftypefn
2527
2528 @deftypefun ScmObj Scm_MakeFillString (int @var{len}, ScmChar @var{fill})
2529 Creates a Scheme string consists of the character @var{fill}
2530 repeated for @var{len} times. Returned string is always
2531 mutable and complete.
2532 @end deftypefun
2533
2534 @deftypefun ScmObj Scm_CopyStringWithFlags (ScmString *@var{str}, int @var{flags}, int @var{mask})
2535 Copy the content of the string @var{str}, with modifying the flags
2536 as specified by the following expression:
2537 @example
2538 newflag = (@var{flags} & @var{mask}) | (oldflag & ~@var{mask})
2539 @end example
2540
2541 Typically you want to drop immutable flag.
2542 Gauche internal uses bits in the flags other than listed here,
2543 so you shouldn't change those bits.
2544
2545 Note: to copy a part of a string, you can use @code{Scm_Substring()}.
2546 @end deftypefun
2547
2548 @deftypefun ScmObj Scm_CopyString (ScmString *@var{str})
2549 An convenience function, equivalent to the following:
2550 @example
2551 Scm_CopyStringWithFlags(str, 0, SCM_STRING_IMMUTABLE)
2552 @end example
2553 @end deftypefun
2554
2555 @deftypefn {Macro} {} SCM_STRING_CONST_INITIALIZER (const char *@var{str}, int @var{len}, int @var{siz})
2556 This is expanded to a static initializer of @code{ScmStringRec} structure.
2557 @var{Len} and @var{siz} must be the correct values (you can't pass @code{-1}).
2558
2559 This is mainly for programs that generates C source. This can
2560 be used to embed static Scheme strings in the C source.
2561 @end deftypefn
2562
2563 @deftypefn {Macro} {} SCM_DEFINE_STRING_CONST (@var{name}, const char *@var{str}, int @var{len}, int @var{siz})
2564 Expands to:
2565 @example
2566 ScmString @var{name} =
2567 SCM_STRING_CONST_INITIALIZER(@var{str}, @var{len}, @var{siz})
2568 @end example
2569 @end deftypefn
2570
2571 @subheading C-string extraction
2572
2573 @deftypefun {const char *} Scm_GetStringConst (ScmString *@var{str})
2574 Retrieves string content as a C string (@code{NUL}-terminated).
2575 This is the efficient way to convert a Scheme string to a C string.
2576 @end deftypefun
2577
2578 @deftypefun {char *} Scm_GetString (ScmString *@var{str})
2579 Use this when you need a mutable C string. This function
2580 copies the content every time and returns a freshly allocated
2581 string.
2582 @end deftypefun
2583
2584 @deftypefun {const char *} Scm_GetStringContent (ScmString *@var{str}, unsigned int *@var{psize}, unsigned int *@var{plen}, unsigned int *@var{pflags})
2585 Use this function if you want to retrieve other attributes of
2586 the strings at once. The return value points to the beginning
2587 of the string content, but it may not be @code{NUL}-terminated.
2588
2589 @var{Psize}, @var{plen}, and @var{pflags} are pointers to the
2590 location where the size, the length, and the flags of the
2591 string is returned. Any of them
2592 can be @code{NULL} if the caller doesn't need the information.
2593 The retrieval of those information and string content is atomic,
2594 so this is a thread safe way to get informations out of @code{ScmString}.
2595 @end deftypefun
2596
2597 @subheading Conversions
2598
2599 @deftypefun ScmObj Scm_CStringArrayToList (const char **@var{array}, int @var{size}, int @var{flags})
2600 Converts an array of C string to a list of Scheme strings.
2601 If @var{size} is nonnegative, it specifies the size of @var{array}.
2602 If @var{size} is negative, @var{array} is assumed to be @code{NULL}-terminated.
2603 The @var{flags} argument is passed to @code{Scm_MakeString} as is.
2604 @end deftypefun
2605
2606 @deftypefun {const char **} Scm_ListToConstCStringArray (ScmObj @var{list}, int @var{errp})
2607 Converts a list of Scheme strings @var{list} into C const string array,
2608 @code{NULL} terminated. If @var{errp} is true, an error is
2609 signaled if @var{list} contains other than Scheme strings.
2610 If @var{errp} is false, @code{NULL} is returned in such cases.
2611 @end deftypefun
2612
2613 @deftypefun {char **} Scm_ListToCStringArray (ScmObj @var{list}, int @var{errp}, void *@var{alloc}(size_t))
2614 Converts a list of Scheme strings @var{list} into C string array,
2615 @code{NULL} terminated. Unlike @code{Scm_ListToConstCStringArray},
2616 each C string is freshly allocated and mutable. Furthermore,
2617 if @code{alloc} is provided, it is used to allocate C strings
2618 and the pointer array.
2619 @end deftypefun
2620
2621 @deftypefun ScmObj Scm_StringToList (ScmString *@var{str})
2622 Scheme's @code{string->list}. Returns a list of characters.
2623 Signals an error if @var{str} is an incomplete string.
2624 @end deftypefun
2625
2626 @deftypefun ScmObj Scm_ListToString (ScmObj @var{chars})
2627 Scheme's @code{list->string}. Converts a list of characters
2628 to a Scheme string. Signals an error if @var{chars} is
2629 not a list, or it contains other than Scheme character.
2630 @end deftypefun
2631
2632 @deftypefun ScmObj Scm_StringCompleteToIncomplete (ScmString *@var{str})
2633 Returns a newly created incomplete Scheme string whose content is
2634 the same as given Scheme string @var{str}.
2635 @end deftypefun
2636
2637 @deftypefun ScmObj Scm_StringIncompleteToComplete (ScmString *@var{str}, int @var{handling}, ScmChar @var{substitute})
2638 Returns a newly created complete Scheme string whose content is
2639 the same as given (possible incomplete) string @var{str}.
2640
2641 The @var{handling} argument must be one of the values of enum
2642 @code{Scm_IllegalCharacterHandling}, and determines the behavior
2643 when @var{str} contains an illegal byte sequences.
2644 If it is @code{SCM_ILLEGAL_CHAR_REJECT}, @code{SCM_FALSE} is returned.
2645 If it is @code{SCM_ILLEGAL_CHAR_OMIT}, illegal bytes are omitted
2646 from the result string.
2647 If it is @code{SCM_ILLEGAL_CHAR_REPLACE}, each illegal byte is
2648 replaced for @var{substitute}. The @var{substitute} argument
2649 isn't used in other cases.
2650 @end deftypefun
2651
2652 @subheading Comparisons
2653
2654 @deftypefun int Scm_StringEqual (ScmString *@var{x}, ScmString *@var{y})
2655 Returns @code{TRUE} if two strings are equal (as by @code{string=?}),
2656 @code{FALSE} otherwise.
2657 A string is equal to another if both their completeness and contents
2658 match.
2659 @end deftypefun
2660
2661 @deftypefun int Scm_StringCmp (ScmString *@var{x}, ScmString *@var{y})
2662 Returns a positive integer if string @var{x} is greater than
2663 string @var{y}, a negative integer if string @var{x} is less than
2664 string @var{y}, and zero if string @var{x} and string @var{y} are
2665 the same. Comparison is done in the codepoint order.
2666 Unlike @code{Scm_StringEqual}, this function signals an error
2667 if completeness of both string differ.
2668 @end deftypefun
2669
2670 @deftypefun int Scm_StringCiCmp (ScmString *@var{x}, ScmString *@var{y})
2671 Like @code{Scm_StringCmp}, but compares in case-insensitive way.
2672
2673 Currently Gauche only folds cases within ASCII range. Soon it'll
2674 follow Unicode case folding rules.
2675 @end deftypefun
2676
2677 @subheading Accessors
2678
2679 @deftypefun ScmChar Scm_StringRef (ScmString *@var{str}, int @var{k}, int @var{range_error})
2680 Scheme's @code{string-ref}. Returns a character at the @var{k}-th position
2681 of the string @var{str}. When @var{k} is out of range,
2682 returns @code{SCM_CHAR_INVALID} if @code{range_error} is @code{FALSE},
2683 or raises an error if @code{range_error} is true.
2684
2685 For the time being, an error is raised if @var{str} is an incomplete
2686 string.
2687 @end deftypefun
2688
2689 @deftypefun int Scm_StringByteRef (ScmString *@var{str}, int @var{k}, int @var{range_error})
2690 Returns @var{k}-th byte in the Scheme string @var{str} as a nonnegative
2691 integer. If @var{range_error} is true, an error is signalled
2692 if @var{k} is out of range. If @var{range_error} is false,
2693 -1 is returned if @var{k} is out of range.
2694 @var{Str} can be an incomplete string.
2695 @end deftypefun
2696
2697 @deftypefun ScmObj Scm_Substring (ScmString *@var{str}, int @var{start}, int @var{end}, int @var{byterange})
2698 Returns a substring of @var{str}, starting from @var{start}
2699 (inclusive) and ending at @var{end} (exclusive).
2700 If @var{byterange} is @code{FALSE} and @var{str} is complete,
2701 @var{start} and @var{end} are character count and returned
2702 string will be complete. Otherwise, they are byte count and returned
2703 string will be incomplete.
2704
2705 A negative value in the @var{end} argument is regarded as
2706 the length/size of the input string. After this treatment,
2707 both @var{start} and @var{end} arguments must be in the valid range,
2708 and @var{start} must be less than or equal to @var{end}, or an error
2709 is signalled.
2710
2711 It is guaranteed that the returned string is newly created and
2712 mutable, even if the @var{start} and @var{end} specifies the entire
2713 string.
2714 @end deftypefun
2715
2716 @subheading Mutator
2717
2718 @deftypefun ScmObj Scm_StringReplaceBody (ScmString *@var{target}, ScmStringBody *@var{newbody})
2719 Replaces @var{target}'s body by @var{newbody}. An error is signalled
2720 if @var{target} is immutable.
2721
2722 This is the only C API that allows mutation of Scheme strings.
2723 Scheme-level string mutators, such as @code{string-set!} and
2724 @code{string-fill!}, are implemented in Scheme on top of
2725 this API. Since string body is immutable, such mutators
2726 needs to allocate and fill a new string body anyway, there's
2727 little merit in providing those mutators in C.
2728 @end deftypefun
2729
2730
2731 @subsubheading Concatenation
2732
2733 @deftypefun ScmObj Scm_StringAppend2 (ScmString *@var{x}, ScmString *@var{y})
2734 Returns a new Scheme string whose content is concatenation of
2735 strings @var{x} and @var{y}.
2736 @end deftypefun
2737
2738 @deftypefun ScmObj Scm_StringAppendC (ScmString *@var{x}, const char *@var{s}, int @var{size}, int @var{len})
2739 Returns a new Scheme string whose content is concatenation of
2740 a Scheme string @var{x} and C-level string @var{s}.
2741 Like @code{Scm_MakeString}, you can give -1 to @var{size} and/or @var{len}
2742 to make the function calculates those values. If you give -1 to @var{size},
2743 @var{s} must be @code{NUL}-terminated; otherwise @var{s} doesn't need to be.
2744 @end deftypefun
2745
2746 @deftypefun ScmObj Scm_StringAppend (ScmObj @var{strs})
2747 The @var{strs} argument must be a list of Scheme strings.
2748 Returns a new Scheme string whose content is concatenation
2749 of all the strings. An error is signalled if not all elements
2750 in @var{strs} are strings.
2751
2752 If any element in @var{strs} is incomplete, the result string
2753 becomes incomplete.
2754 @end deftypefun
2755
2756 @deftypefun ScmObj Scm_StringJoin (ScmObj @var{strs}, ScmString *@var{delim}, int @var{grammar})
2757 Scheme's @var{string-join}. Concatenates a list of strings @var{strs}
2758 with inserting a delimiter @var{delim} between them. The @var{grammar}
2759 argument must be one of the following enums:
2760
2761 @example
2762 enum @{
2763 SCM_STRING_JOIN_INFIX,
2764 SCM_STRING_JOIN_STRICT_INFIX,
2765 SCM_STRING_JOIN_SUFFIX,
2766 SCM_STRING_JOIN_PREFIX
2767 @};
2768 @end example
2769
2770 They correspond to @code{infix}, @code{strict-infix}, @code{suffix},
2771 and @code{prefix} as defined in @code{srfi-13}'s @code{string-join}.
2772 @end deftypefun
2773
2774 @subheading Searching
2775
2776 @deftypefun ScmObj Scm_StringScan (ScmString *@var{s1}, ScmString *@var{s2}, int @var{retmode})
2777 @deftypefunx ScmObj Scm_StringScanChar (ScmString *@var{s1}, ScmChar @var{ch}, int @var{retmode})
2778 Scheme's @code{string-scan}.
2779 Search a string @var{s2} or a character @var{ch} within a string @var{s1},
2780 respectively. Return value depends on the @var{retmode} argument, as follows:
2781 @table @code
2782 @item SCM_STRING_SCAN_INDEX
2783 Returns an index of the first found instance of @var{s1}/@var{ch},
2784 or @code{SCM_FALSE} if no instance is found.
2785 @item SCM_STRING_SCAN_BEFORE
2786 Returns a substring of @var{s1} between its beginning and just
2787 before the first found instance of @var{s1}/@var{ch},
2788 or @code{SCM_FALSE} if no instance is found.
2789 @item SCM_STRING_SCAN_AFTER
2790 Returns a substring of @var{s1} between just after the first found instance
2791 of @var{s1}/@var{ch} and the end of @var{s1},
2792 or @code{SCM_FALSE} if no instance is found.
2793 @item SCM_STRING_SCAN_BEFORE2
2794 Returns two values via @code{Scm_Values()},
2795 the substring of @var{s1} before the found instance
2796 and the rest, or two @code{SCM_FALSE}s if no instance found.
2797 @item SCM_STRING_SCAN_AFTER2
2798 Returns two values via @code{Scm_Values()},
2799 the substring of @var{s1} before the end of the
2800 found instance and the rest, or two @code{SCM_FALSE}s if no instance found.
2801 @item SCM_STRING_SCAN_BOTH
2802 Returns two values via @code{Scm_Values()},
2803 the substring of @var{s1} before the found instance and
2804 after the found instance, or two @code{SCM_FALSE}s if no instance found.
2805 @end table
2806
2807 The last three return multiple values on the running Gauche VM.
2808 See @ref{Calling back to Scheme}, for how to retrieve those values.
2809 @end deftypefun
2810
2811 @deftypefun ScmObj Scm_StringSplitByChar (ScmString *@var{str}, ScmChar @var{ch})
2812
2813 @end deftypefun
2814
2815
2816 @subheading Miscellaneous utilities
2817
2818 @deftypefun int Scm_MBLen (const char *@var{str}, const char *@var{stop})
2819 A utility function to count the number of characters in a multibyte
2820 string @var{str}, assuming it's in Gauche's native encoding.
2821
2822 If @var{stop} is given, it specifies the end point in the string;
2823 bytes just before @var{stop} are counted. The string may have
2824 @code{NUL} character in this case.
2825
2826 If @var{stop} is @code{NULL}, @var{str} is assumed to be @code{NUL}
2827 terminated.
2828
2829 If the string is complete, the number of characters is returned.
2830 If the string is incomplete, -1 is returned.
2831 @end deftypefun
2832
2833
2834 @subheading Dynamic strings
2835
2836 Dynamic strings provide a convenient way to construct a string
2837 of an unknown length. It is a base of output string port, but
2838 from C programs using dynamic strings is lightweight than output
2839 string port (see @ref{Built-in ports}, for string ports).
2840 It is OK to call dynamic string operations while locking a
2841 mutex.
2842
2843 @deftp {Datatype} ScmDString
2844 A structure to keep a string under construction. It is not a
2845 Scheme datatype (means: you can't cast it to @code{ScmObj}).
2846 You can allocate it on the C stack for efficient operation.
2847 @end deftp
2848
2849 The typical usage of dynamic strings looks like this:
2850
2851 @example
2852 ScmDString ds;
2853 ScmObj str;
2854
2855 Scm_DStringInit(&ds); /* Initialization */
2856 Scm_DstringPutc(&ds, 'a'); /* Adding content */
2857 Scm_DstringPutz(&ds, "abc", -1); /* Adding content */
2858 ...
2859
2860 str = Scm_DStringGet(&ds, 0); /* Obtains the result string */
2861 @end example
2862
2863 @deftypefun void Scm_DStringInit (ScmDString *@var{dstr})
2864 Initializes a dynamic string object. A dynamic string object
2865 must be initialized before used.
2866 @end deftypefun
2867
2868 @deftypefun int Scm_DStringSize (ScmDString *@var{dstr})
2869 Returns the size (number of bytes) accumulated in the dynamic string.
2870 @end deftypefun
2871
2872 @deftypefun ScmObj Scm_DStringGet (ScmDString *@var{dstr}, int @var{flags})
2873 Extracts the accumulated string as a Scheme string. The accumulated
2874 data remains in @var{dstr}. By default, returned string is mutable,
2875 and its completeness is determined by its content. You may pass
2876 @code{SCM_STRING_IMUUTABLE} and/or @code{SCM_STRING_INCOMPLETE} to
2877 the @var{flags} argument to force the attributes of the result string.
2878 @end deftypefun
2879
2880 @deftypefun {const char *} Scm_DStringGetz (ScmDString *@var{dstr})
2881 Extracts the accumulated string as a @code{NUL}-terminated C string.
2882 The accumulated data remains in @var{dstr}.
2883 @end deftypefun
2884
2885 @deftypefun void Scm_DStringPutz (ScmDString *@var{dstr}, const char *@var{str}, int @var{siz})
2886 Adds C string @var{str} to the dynamic string. If @var{siz} is negative,
2887 @var{str} is assumed to be @code{NUL}-terminated. If @var{siz} is nonnegative,
2888 it specifies the size of the string (in which case @var{str} may contain
2889 @code{NUL} character in it.)
2890 @end deftypefun
2891
2892 @deftypefun void Scm_DStringAdd (ScmDString *@var{dstr}, ScmString *@var{str})
2893 Adds Scheme string @var{str} to the dynamic string.
2894 @end deftypefun
2895
2896 @deftypefun void Scm_DStringPutb (ScmDString *@var{dstr}, char @var{byte})
2897 Adds a single byte @var{byte} to the dynamic string.
2898 @end deftypefun
2899
2900 @deftypefun void Scm_DStringPutc (ScmDString *@var{dstr}, ScmChar @var{ch})
2901 Adds a single character @var{ch} to the dynamic string.
2902 @end deftypefun
2903
2904
2905 @node Regular expressions, Vectors, Strings, C API reference
2906 @section Regular expressions
2907
2908 @node Vectors, Dictionaries, Regular expressions, C API reference
2909 @section Vectors
2910
2911 @deftypefn {Macro} int SCM_VECTORP (ScmObj @var{obj})
2912 Type predicate.
2913 @end deftypefn
2914
2915 @deftypefn {Macro} {ScmVector *} SCM_VECTOR (ScmObj @var{obj})
2916 Typecast.
2917 @end deftypefn
2918
2919 @deftypefn {Macro} int SCM_VECTOR_SIZE (ScmObj @var{vec})
2920 Returns the number of elements of the vector @var{vec}.
2921 @end deftypefn
2922
2923 @deftypefn {Macro} {ScmObj *} SCM_VECTOR_ELEMENTS (ScmObj @var{vec})
2924 Returns the pointer to the array of the vector contents.
2925 @end deftypefn
2926
2927 @deftypefn {Macro} ScmObj SCM_VECTOR_ELEMENT (ScmObj @var{vec}, int @var{k})
2928 Returns the @var{k}-th element of the vector.
2929 No boundary check is done. Use @code{Scm_VectorRef} for safer access.
2930 @end deftypefn
2931
2932 @deftypefun ScmObj Scm_MakeVector (int @var{size}, ScmObj @var{fill})
2933 Returns a vector of @var{size} elements. Each element is
2934 initialized by @var{fill}.
2935 @end deftypefun
2936
2937 @deftypefun ScmObj Scm_ListToVector (ScmObj @var{list}, int @var{start}, int @var{end})
2938 Creates a vector from @var{start}-th element (inclusive) to
2939 @var{end}-th element (exclusive) of a list @var{list}.
2940 @var{end} can be @code{-1} to indicate the end of the list.
2941 @end deftypefun
2942
2943 @deftypefun ScmObj Scm_VectorToList (ScmVector *@var{vec}, int @var{start}, int @var{end})
2944 Creates a list from @var{start}-th element (inclusive) to
2945 @var{end}-th element (exclusive) of a vector @var{vec}.
2946 @var{end} can be @code{-1} to indicate the end of the vector.
2947 @end deftypefun
2948
2949 @deftypefun ScmObj Scm_VectorRef (ScmVector *@var{vec}, int @var{k}, ScmObj @var{fallback})
2950 Returns @var{k}-th element of the vector. If @var{k} is
2951 out of range, the value passed to @var{fallback} is returned.
2952 Note that this routine will never raise an error; argument check
2953 of Scheme's @code{vector-ref} is done in the bridge stub.
2954 @end deftypefun
2955
2956 @deftypefun ScmObj Scm_VectorSet (ScmVector *@var{vec}, int @var{k}, ScmObj @var{obj})
2957 Sets @var{k}-th element of a vector @var{vec} by @var{obj}.
2958 Always return @var{obj}.
2959 If @var{k} is out of range, no operation is performed (no error
2960 is signalled). The boundary check for Scheme's @code{vector-set!}
2961 is done in the bridge stub.
2962 @end deftypefun
2963
2964
2965 @deftypefun ScmObj Scm_VectorFill (ScmVector *@var{vec}, ScmObj @var{fill}, int @var{start}, int @var{end})
2966 Sets @var{start}-th element (inclusive) to @var{end}-th element
2967 (exclusive) of a vector @var{vec} by @var{fill}.
2968 @var{end} can be @code{-1} to indicate the end of the vector.
2969 @end deftypefun
2970
2971 @deftypefun ScmObj Scm_VectorCopy (ScmVector *@var{vec}, int @var{start}, int @var{end}, ScmObj @var{fill})
2972 Creates a new vector, whose content is the same
2973 as the content of @var{vec} beginning with @var{start}-th element
2974 and ending with (@var{end}-1)-th element. If @var{end} is -1,
2975 it is taken as the length of @var{vec}. Unlike other vector APIs,
2976 @var{start} can be negative and @var{end} can be greater than
2977 then length of @var{vec}; in such case, @var{vec} is regarded
2978 as if it has implicit elements in both directions, whose value
2979 is given by @var{fill}.
2980 @end deftypefun
2981
2982 @deftypefn {Macro} int SCM_UVECTORP (ScmObj @var{obj})
2983 Type predicate.
2984 @end deftypefn
2985
2986 @deftypefn {Macro} {ScmUVector *} SCM_UVECTOR (ScmObj @var{obj})
2987 Typecast.
2988 @end deftypefn
2989
2990 @deftypefn {Macro} {void *} SCM_UVECTOR_OWNER (ScmObj @var{vec})
2991 Returns the owner pointer of the uniform vector @var{vec}.
2992 @end deftypefn
2993
2994 @deftypefn {Macro} {void *} SCM_UVECTOR_ELEMENTS (ScmObj @var{vec})
2995 Returns the pointer to the array of the uniform vector contents.
2996 @end deftypefn
2997
2998 @deftypefn {Macro} int SCM_UVECTOR_SIZE (ScmObj @var{vec})
2999 Returns the number of elements of the uniform vector @var{vec}.
3000 @end deftypefn
3001
3002 @deftypefn {Macro} int SCM_UVECTOR_IMMUTABLE_P (ScmObj @var{vec})
3003 Returns non-zero if the uniform vector is immutable.
3004 @end deftypefn
3005
3006 @deftypefn {Macro} void SCM_UVECTOR_IMMUTABLE_SET (ScmObj @var{vec}, @var{flags})
3007 Sets immutable state of the uniform vector @var{vec}.
3008 @end deftypefn
3009
3010 @deftypefn {Macro} void SCM_UVECTOR_CHECK_MUTABLE (ScmObj @var{vec})
3011 Raise an error if the uniform vector @var{vec} is immutable.
3012 @end deftypefn
3013
3014 @deftypefn {Macro} int SCM_UVECTOR_SUBTYPE_P (ScmObj @var{vec}, ScmUVectorType @var{type})
3015 Returns true if the uniform vector @var{vec} is of type @var{type}.
3016 @end deftypefn
3017
3018 @deftypefun ScmUVectorType Scm_UVectorType (ScmClass @var{klass})
3019 Returns the vector type of the uniform vector class @var{klass}.
3020 @end deftypefun
3021
3022 @deftypefun {const char *} Scm_UVectorTypeName (int @var{type})
3023 Converts @var{type} (of type @code{ScmUVectorType} actually) to a
3024 string.
3025 @end deftypefun
3026
3027 @deftypefun int Scm_UVectorElementSize (ScmClass @var{klass})
3028 Returns the element type in bytes of the uniform vector class
3029 @var{klass}.
3030 @end deftypefun
3031
3032 @deftypefun int Scm_UVectorSizeInBytes (ScmUVector *@var{vec})
3033 Returns the size in bytes of the uniform vector @var{vec}.
3034 @end deftypefun
3035
3036 @deftypefun ScmObj Scm_MakeUVector (ScmClass *@var{klass}, ScmSmallInt @var{size}, void *@var{init})
3037 Returns a mutable uniform vector of type @var{klass}, @var{size}
3038 elements and no owner. The vector data is contained in @var{init},
3039 which must be properly prepared by the caller. This normally is
3040 allocated in heap. But it could also be from other sources, e.g. mmap.
3041 @end deftypefun
3042
3043 @deftypefun ScmObj Scm_MakeUVectorFull (ScmClass *@var{klass}, ScmSmallInt @var{size}, void *@var{init}, int @var{immutablep}, void *@var{owner})
3044 Creates a new uniform vector. This is the extended version of
3045 @code{Scm_MakeUVector} that lets you control both owner and immutable
3046 state.
3047 @end deftypefun
3048
3049 @deftypefun ScmObj Scm_ListToUVector (ScmClass *@var{klass}, ScmObj @var{list}, ScmSmallInt @var{start}, ScmSmallInt @var{end})
3050 Creates a uniform vector of class @var{klass} from @var{start}-th
3051 element (inclusive) to @var{end}-th element (exclusive) of a list
3052 @var{list}. @var{end} can be @code{-1} to indicate the end of the
3053 list.
3054 @end deftypefun
3055
3056 @deftypefun ScmObj Scm_UVectorSet (ScmUVector *@var{vec}, int @var{t}, int @var{k}, ScmObj @var{val}, int @var{clamp})
3057 Sets @var{k}-th element of a vector @var{vec} (of type @var{type}) by
3058 @var{val}. See @ref{Scheme number objects} for @var{clamp}.
3059 Always return @var{obj}.
3060 If @var{k} is out of range, no operation is performed and an error is
3061 signalled.
3062 @end deftypefun
3063
3064 @deftypefun ScmObj Scm_Make@var{tag}Vector (ScmSmallInt @var{size}, type @var{fill})
3065 @deftypefunx ScmObj Scm_Make@var{tag}VectorFromArray (ScmSmallInt @var{size}, const type @var{array}[])
3066 @deftypefunx ScmObj Scm_Make@var{tag}VectorFromArrayShared (ScmSmallInt @var{size}, type @var{array}[])
3067 For all supported uniform vector types, there are three functions each
3068 type to create a vector of the type in question.
3069 @itemize
3070 @item
3071 The first variant creates a mutable vector automatically allocated on
3072 heap.
3073 @item
3074 The second variant initializes heap allocated vector data with
3075 @var{array}.
3076 @item
3077 The third variant directly uses @var{array} as the vector data.
3078 @end itemize
3079 @end deftypefun
3080
3081
3082 @node Dictionaries, Weak pointers, Vectors, C API reference
3083 @section Dictionaries
3084
3085 Dictionaries are data structures that maps a key object to
3086 a value object. Gauche provides two kinds of basic dictionaries:
3087 hash tables and tree maps.
3088
3089 Each kind of dictionary has two layers of API: The 'core'
3090 API (@code{ScmHashCore}, @code{ScmTreeCore}) works on a
3091 C structure, and deals with raw C pointers. On top of core
3092 API, Scheme-level objects (@code{ScmHashTable}, @code{ScmTreeMap})
3093 are defined. There are other built-in structures that are built
3094 on opt of core API; for example, @code{ScmCharSet} uses
3095 @code{ScmTreeCore} internally, and there's a plan to provide
3096 @code{ScmWeakHashTable} which will be built on top of @code{ScmHashCore}.
3097
3098 @menu
3099 * Common dictionary interface::
3100 * Hash tables::
3101 * Tree maps::
3102 @end menu
3103
3104 @node Common dictionary interface, Hash tables, Dictionaries, Dictionaries
3105 @subsection Common dictionary interface
3106
3107 Since there are lots of similarities between hash tables and tree maps,
3108 they share some common data structures and enums.
3109
3110 @deftp {Enum} ScmDictSetFlags
3111 These are bitflags @code{Scm_HashTableSet} and @code{Scm_TreeMapSet} take.
3112
3113 @table @code
3114 @item SCM_DICT_NO_OVERWRITE
3115 If this flag is given, the function does not overwrite an existing entry;
3116 it only adds a new entry if no existing entry has the given key.
3117 @item SCM_DICT_NO_CREATE
3118 If this flag is given, the function does not add a new entry;
3119 it only changes the value of the existing entry.
3120 @end table
3121 @end deftp
3122
3123 If both @code{SCM_DICT_NO_OVERWRITE} and @code{SCM_DICT_NO_CREATE} are
3124 given, the behavior is undefined. In future it is possible that we have
3125 more flags.
3126
3127 Each key-value pair in a dictionary is kept in
3128 a @code{ScmDictEntry} structure. The low-level access
3129 functions (@code{Scm_HashCoreSearch} and @code{Scm_TreeCoreSearch}),
3130 and iterators (@code{Scm_HashIterNext} and @code{Scm_TreeCoreNext} etc.)
3131 returns a pointer to this structure.
3132
3133 @deftp {Struct} ScmDictEntry
3134 @example
3135 typedef struct ScmDictEntryRec @{
3136 const intptr_t key;
3137 intptr_t value;
3138 @} ScmDictEntry;
3139 @end example
3140 @end deftp
3141
3142 Note that they can be used to keep non-@code{ScmObj}s, so the type of
3143 key and value is @code{intptr_t}. If you're accessing high-level
3144 dictionaries @code{Scm_HashTable} and @code{Scm_TreeMap}, both
3145 of which are designed to store @code{ScmObjs}, you should use the following
3146 accessor macros to retrieve @code{ScmObj}s.
3147
3148 @deftypefn {Macro} ScmObj SCM_DICT_KEY (ScmDictEntry* @var{entry})
3149 @deftypefnx {Macro} ScmObj SCM_DICT_VALUE (ScmDictEntry* @var{entry})
3150 Accesses the key and the value fields of @code{ScmDictEntry} as
3151 @code{ScmObj}s, respectively.
3152 @end deftypefn
3153
3154 @deftypefn {Macro} ScmObj SCM_DICT_SET_VALUE (ScmdictEntry* @var{entry}, ScmObj @var{value})
3155 Sets @var{value} to the value field of @var{entry} and returns
3156 @var{value} itself.
3157
3158 The caller have to make sure @var{value} is a valid @code{ScmObj}.
3159 Particularly, it is prohibited to pass @code{SCM_UNBOUND} as @var{value}.
3160 @end deftypefn
3161
3162 Each core dictionary API provides a search function that takes
3163 operation (@code{op}) argument, which must be one of the following
3164 values:
3165
3166 @deftp {Enum} ScmDictOp
3167 @table @code
3168 @item SCM_DICT_GET
3169 The search function returns @code{ScmDictEntry*} if found,
3170 @code{NULL} otherwise.
3171 @item SCM_DICT_CREATE
3172 The search function creates a new entry if the given entry
3173 is not found. Always returns @code{ScmDictEntry*}.
3174 @item SCM_DICT_DELETE
3175 The search function deletes a found entry from the dictionary.
3176 Returns @code{NULL} if no entry is found.
3177 Otherwise returns @code{ScmDictEntry*}
3178 which is just deleted from the dictionary.
3179 @end table
3180 @end deftp
3181
3182 @node Hash tables, Tree maps, Common dictionary interface, Dictionaries
3183 @subsection Hash tables
3184
3185 @subsubheading Low-level API
3186
3187 @deftp {Enum} ScmHashType
3188 Specifies the pre-defined hash table types. Except @code{SCM_HASH_GENERAL},
3189 each type implies specific hash and compare functions.
3190 @table @code
3191 @item SCM_HASH_EQ
3192 @code{eq?}-type hashtables. Compare function is @code{SCM_EQ},
3193 and hash function is @code{Scm_EqHash}.
3194 @item SCM_HASH_EQV
3195 @code{eqv?}-type hashtables. Compare function is @code{Scm_Eqv},
3196 and hash function is @code{Scm_EqvHash}.
3197 @item SCM_HASH_EQUAL
3198 @code{equal?}-type hashtables. Compare function is @code{Scm_Equal},
3199 and hash function is @code{Scm_Hash}.
3200 @item SCM_HASH_STRING
3201 @code{string=?}-type hashtables. Compare function is @code{Scm_StringEqual},
3202 and hash function is @code{Scm_HashString}.
3203 @item SCM_HASH_WORD
3204 Non-@code{ScmObj} one-word hashtables. Comparison is @code{==},
3205 and hash is @code{Scm_EqHash}. The table may keep arbitrary machine words,
3206 not only @code{ScmObj}s.
3207 @item SCM_HASH_GENERAL
3208 A generic hashtable that uses user-provided comparison and hash functions.
3209 Currently this type of hashtables is not well supported; more support is
3210 planned in future.
3211 @end table
3212 @end deftp
3213
3214 @deftp {Struct} ScmHashCore
3215 A C struct to hold a hash table. This structure is not an @code{ScmObj},
3216 and supposed to be used embedded in other structures.
3217 @end deftp
3218
3219 @deftypefun void Scm_HashCoreInitSimple (ScmHashCore *@var{core}, ScmHashType @var{type}, unsigned int @var{initSize}, void *@var{data})
3220 Initialize a hash core structure pointed by @var{core}, with predefined
3221 hash and compare functions determined by the @var{type} argument.
3222 You can pass one of the @code{ScmHashType} enums except
3223 @code{SCM_HASH_GENERAL} to @var{type}.
3224
3225 If you know rough number of hashtable entries, you can tell it by
3226 @var{initSize} argument so that the hashtable may be optimized for
3227 that size. Passing 0 makes the function to choose a reasonable value.
3228
3229 The @var{data} argument is an opaque pointer for the application.
3230 @end deftypefun
3231
3232 @deftypefun void Scm_HashCoreCopy (ScmHashCore *@var{dst}, const ScmHashCore *@var{src})
3233 Copies the content of @var{src} to @var{dst}, including the hash type,
3234 hash function and compare function. The original content of @var{dst}
3235 is destroyed. It is OK to pass uninitialized @code{ScmHashCore} as @var{dst}.
3236 @end deftypefun
3237
3238 @deftypefun {ScmDictEntry *} Scm_HashCoreSearch (ScmHashCore *@var{core}, intptr_t @var{key}, ScmDictOp @var{op})
3239 Searches an entry with the given @var{key}, and and perform the operation
3240 specified by @var{op}, which must be either @code{SCM_DICT_GET},
3241 @code{SCM_DICT_CREATE}, or @code{SCM_DICT_DELETE}.
3242
3243 Returns a pointer to the found, created or deleted entry. For
3244 get and delete operations it may return @code{NULL} if there's no
3245 entry found for @var{key}.
3246 @end deftypefun
3247
3248 @deftypefun int Scm_HashCoreNumEntries (ScmHashCore *@var{core})
3249 Returns the current number of entries in the hash core.
3250 @end deftypefun
3251
3252 @subsubheading Iterators
3253
3254 @deftp {Struct} ScmHashIter
3255 An opaque structure to iterate over a hash table.
3256 This is not an @code{ScmObj}.
3257
3258 You can modify the value of the entries while iterating over
3259 a hash table; however, once an entry is added or deleted,
3260 the behavior of existing iterators become undefined.
3261 @end deftp
3262
3263 @deftypefun void Scm_HashIterInit (ScmHashIter *@var{iter}, ScmHashCore *@var{core})
3264 Initializes an iterator @var{iter} to iterate through a hash core @var{core}.
3265 At the beginning, the iterator points to an imaginary entry just before
3266 the first entry, so that the first call of @code{Scm_HashIterNext} returns
3267 the first entry.
3268 @end deftypefun
3269
3270 @deftypefun {ScmDictEntry *} Scm_HashIterNext (ScmHashIter *@var{iter})
3271 Updates the iterator @var{iter} to point to the next entry, then
3272 returns it. If the iterator has visited all entries, @code{NULL}
3273 is returned.
3274 @end deftypefun
3275
3276 @subsubheading Hash functions
3277
3278 Other than @code{Scm_EqHash} and @code{Scm_EqvHash}, which returns
3279 a value that depends on the run-time address of the objects,
3280 hash values depend on the @emph{salt} value, which is initialized
3281 randomly at the process initialization time.
3282
3283 @deftypefun {u_long} Scm_EqHash (ScmObj @var{obj})
3284 Calculates hash value of the object suitable for @code{eq?}-type
3285 hash table.
3286 @end deftypefun
3287
3288 @deftypefun {u_long} Scm_EqvHash (ScmObj @var{obj})
3289 Calculates hash value of the object suitable for @code{eqv?}-type
3290 hash table.
3291 @end deftypefun
3292
3293 @deftypefun {u_long} Scm_HashString (ScmString *@var{str}, unsigned long @var{bound})
3294 @end deftypefun
3295
3296 @deftypefun {u_long} Scm_PortableHash (ScmObj @var{obj}, u_long salt)
3297 @end deftypefun
3298
3299 @deftypefun {ScmSmallInt} Scm_DefaultHash (ScmObj @var{obj})
3300 @end deftypefun
3301
3302 @deftypefun {ScmSmallInt} Scm_RecursiveHash (ScmObj @var{obj}, ScmSmallInt salt, u_long flags)
3303 @end deftypefun
3304
3305 @deftypefun {ScmSmallInt} Scm_SmallIntHash (ScmSmallInt val, ScmSmallInt salt, u_long flags)
3306 @end deftypefun
3307
3308 @deftypefun {ScmSmallInt} Scm_Int64Hash (int64_t val, ScmSmallInt salt, u_long flags)
3309 @end deftypefun
3310
3311 @deftypefun u_long Scm_CombineHashValue (u_long a, u_long b)
3312 @end deftypefun
3313
3314 @deftypefun ScmSmallInt Scm_HashSaltRef (void)
3315 @deftypefunx ScmSmallInt Scm_HashSaltSet (ScmSmallInt salt)
3316 @end deftypefun
3317
3318 @deftypefun ScmSmallInt Scm_PortableHashSalt (ScmObj newval)
3319 @end deftypefun
3320
3321
3322 @subsubheading Scheme HashTable object
3323
3324 @deftp {ScmObj} ScmHashTable
3325 @end deftp
3326
3327 @deftypefn {Macro} int SCM_HASH_TABLE_P (ScmObj @var{obj})
3328 Type predicate.
3329 @end deftypefn
3330
3331 @deftypefn {Macro} {ScmHashTable *} SCM_HASH_TABLE (ScmObj @var{obj})
3332 Typecast macro.
3333 @end deftypefn
3334
3335 @deftypefn {Macro} {ScmHashCore *} SCM_HASH_TABLE_CORE (ScmHashTable *@var{ht})
3336 Returns a pointer to the @code{ScmHashCore} in the hash table @var{ht}.
3337 @end deftypefn
3338
3339 @deftypefn {Macro} {ScmHashCore *} SCM_HASH_TABLE_CORE (ScmHashTable *@var{ht})
3340 Returns a pointer to the @code{ScmHashCore} in the hash table @var{ht}.
3341 @end deftypefn
3342
3343 @deftypefun ScmObj Scm_MakeHashTableSimple (ScmHashType @var{type}, int @var{initSize})
3344 @end deftypefun
3345
3346
3347
3348 @node Tree maps, , Hash tables, Dictionaries
3349 @subsection Tree maps
3350
3351 A tree map uses balanced binary tree to store the key-value pair.
3352 Entry retrieval and modification is O(log(n)).
3353
3354 @subsubheading Low-level API
3355
3356 @deftp {Struct} ScmTreeCore
3357 A C struct to hold a tree map. This structure is not an @code{ScmObj},
3358 and supposed to be used embedded in other structures.
3359 @end deftp
3360
3361 @deftp {Function Prototype} ScmTreeCompareProc
3362 @example
3363 typedef int ScmTreeCoreCompareProc(ScmTreeCore* tc,
3364 intptr_t k1,
3365 intptr_t k2);
3366 @end example
3367 Called when the tree map routine need to compare keys, @var{k1}
3368 and @var{k2}. The function must return @code{-1} if @var{k1}
3369 is before @var{k2}, @code{0} if @var{k1} and @var{k2} is the same,
3370 and @var{1} if @var{k1} is after @var{k2}.
3371 @end deftp
3372
3373 @deftypefun void Scm_TreeCoreInit (ScmTreeCore *@var{tc}, ScmTreeCoreCompareProc *@var{cmp}, void *@var{data})
3374 Initializes @code{ScmTreeCore} structure @var{tc}, using @var{cmp}
3375 as the compare procedure. Whatever information @var{tc} has been
3376 carrying will be lost.
3377 @end deftypefun
3378
3379 @deftypefun void Scm_TreeCoreCopy (ScmTreeCore *@var{dst}, const ScmTreeCore *@var{src})
3380 Copies the content of @var{src} into @var{dst}. Whatever information
3381 in @var{dst} will be lost.
3382 @end deftypefun
3383
3384 @deftypefun {ScmDictEntry *} Scm_TreeCoreSearch (ScmTreeCore *@var{tc}, intptr_t @var{key}, ScmDictOp @var{op})
3385 Searches an entry with the given @var{key}, and perform the operation
3386 specified by @var{op}, which must be either @code{SCM_DICT_GET},
3387 @code{SCM_DICT_CREATE}, or @code{SCM_DICT_DELETE}.
3388
3389 Returns a pointer to the found, created or deleted entry. For
3390 get and delete operations it may return @code{NULL} if there's no
3391 entry found for @var{key}.
3392 @end deftypefun
3393
3394 @deftypefun {ScmDictEntry *} Scm_TreeCoreClosestEntries (ScmTreeCore *@var{tc}, intptr_t @var{key}, ScmDictEntry **@var{lo}, ScmDictEntry **@var{hi})
3395 Searches an entry with the given @var{key} and returns an exact match,
3396 or @code{NULL} if there's no exact match. Besides that, it stores
3397 the pointers of entries closest to the given key, from below the key
3398 and above the key, in the location pointed by @var{lo} and @var{hi},
3399 respectively. If the tree core has exact match, @var{*lo} and @var{*hi}
3400 will have pointers to the immediately previous and next entries.
3401 If the tree core doesn't have exact match, the given key is
3402 between the keys of two entries pointed by @var{*lo} and @var{*hi}.
3403
3404 As a boundary case, if the given key is smaller than the smallest
3405 key in @var{tc}, @var{*lo} is @code{NULL}; if the given key is greater
3406 than the greatest, @var{*hi} is @code{NULL}; and if @var{tc} is empty,
3407 both @var{*lo} and @var{*hi} is @code{NULL}.
3408 @end deftypefun
3409
3410 @deftp {Enum} ScmTreeCoreBoundOp
3411 Specify which side you're operating of the call to
3412 @code{ScmTreeCoreGetBound} and @code{ScmTreeCorePopBound}.
3413
3414 @table @code
3415 @item SCM_TREE_CORE_MIN
3416 Operate on the entry of the minimum (smallest) key.
3417 @item SCM_TREE_CORE_MAX
3418 Operate on the entry of the maximum (greatest) key.
3419 @end table
3420 @end deftp
3421
3422 @deftypefun {ScmDictEntry *} Scm_TreeCoreGetBound (ScmTreeCore *@var{tc}, ScmTreeCoreBoundOp @var{op})
3423 Returns the entry in @var{tc} with the minimum or maximum key, as
3424 specified by @var{op} argument. May return @code{NULL} if @var{tc}
3425 is empty.
3426 @end deftypefun
3427
3428 @deftypefun {ScmDictEntry *} Scm_TreeCorePopBound (ScmTreeCore *@var{tc}, ScmTreeCoreBoundOp @var{op})
3429 Finds the entry in @var{tc} with the minimum or maximum key, as
3430 specified by @var{op} argument, and removes the entry from @var{tc},
3431 then returns the entry. If @var{tc} is empty, no operation is
3432 performed and @code{NULL} is returned.
3433 @end deftypefun
3434
3435 @deftypefun int Scm_TreeCoreNumEntries (ScmTreeCore *@var{tc})
3436 Returns the number of entries in @var{tc}.
3437 @end deftypefun
3438
3439 @subsubheading Iterators
3440
3441 @deftp {Struct} ScmTreeIter
3442 An iterator over a tree map. This is not an @code{ScmObj}.
3443 Must be treated as opaque structure.
3444
3445 An iterator can point to one of the entries in a tree core,
3446 or @code{NULL}. The @code{NULL} indicates the iterator is
3447 outside of the tree---it's both below the minimum key and above
3448 the maximum key simultaneously. That is, when an iterator points
3449 to @code{NULL}, when you call @code{Scm_TreeIterNext} you'll get
3450 the minimum key entry, while you call @code{Scm_TreeIterPrev} and
3451 you'll get the maximum key entry.
3452
3453 You can modify the value of the entries while iterating over
3454 a tree map; however, once an entry is added or deleted,
3455 the behavior of existing iterators become undefined.
3456 @end deftp
3457
3458 @deftypefun void Scm_TreeIterInit (ScmTreeIter *@var{iter}, ScmTreeCore *@var{tc}, ScmDictEntry *@var{start})
3459 Initializes an iterator @var{iter} over a tree core @var{tc}.
3460 If @var{start} is NULL, the iterator is set just before the smallest
3461 entry in @var{tc} (i.e. the next call to @var{Scm_TreeCoreNext} will
3462 return the smallest entry); otherwise, the iterator points the given entry
3463 (i.e. the next call to @var{Scm_TreeCoreNext} will return the next
3464 entry of @var{start}).
3465 In the latter case, @var{start} must points to an entry in @var{tc},
3466 otherwise an error is signalled.
3467 @end deftypefun
3468
3469 @deftypefun {ScmDictEntry *} Scm_TreeIterCurrent (ScmTreeIter *@var{iter})
3470 Returns the entry the iterator currently pointing. Can be @code{NULL}.
3471 @end deftypefun
3472
3473 @deftypefun int Scm_TreeIterAtEnd (ScmTreeIter *@var{iter})
3474 Returns @code{TRUE} iff the iterator has been pointing inside the tree
3475 and now pointing @code{NULL} after calling either @code{ScmTreeIterNext}
3476 or @code{ScmTreeIterPrev}.
3477
3478 If you call @code{ScmTreeIterNext} on an iterator that is "at end",
3479 it starts from the minimum key entry; likewise, @code{ScmTreeIterPrev}
3480 makes it starts from the maximum key entry. In either case, "at end"
3481 flag is cleared.
3482 @end deftypefun
3483
3484 @deftypefun {ScmDictEntry *} Scm_TreeIterNext (ScmTreeIter *@var{iter})
3485 @deftypefunx {ScmDictEntry *} Scm_TreeIterPrev (ScmTreeIter *@var{iter})
3486 Moves the iterator to the next or previous entry and returns it,
3487 respectively.
3488 If the iterator was pointing the maximum (minimum) key entry
3489 before calling @code{Scm_TreeIterNext} (@code{Scm_TreeIterPrev}),
3490 @code{NULL} is returned and the iterator becomes "at end" state
3491 (i.e. @code{Scm_TreeIterAtEnd} returns @code{TRUE}).
3492 @end deftypefun
3493
3494 @subsubheading Scheme TreeMap object
3495
3496 @deftp {ScmObj} ScmTreeMap
3497 This is the Scheme's @code{<tree-map>} object. It contains
3498 @code{ScmTreeCore}, whose pointer can be obtained
3499 by the macro @code{SCM_TREE_MAP_CORE}.
3500 @end deftp
3501
3502 @deftypefn {Macro} {ScmTreeMap *} SCM_TREE_MAP (ScmObj @var{obj})
3503 Cast macro.
3504 @end deftypefn
3505
3506 @deftypefn {Macro} int SCM_TREE_MAP_P (ScmObj @var{obj})
3507 Type predicate.
3508 @end deftypefn
3509
3510 @deftypefn {Macro} {ScmTreeCore *} SCM_TREE_MAP_CORE (ScmTreeMap *@var{obj})
3511 Returns the pointer to the @code{ScmTreeCore} part in a tree map.
3512 @end deftypefn
3513
3514 @deftypefn {Macro} {void *} SCM_TREE_MAP_DATA (ScmTreeMap *@var{obj})
3515 Returns the opaque data in a tree map.
3516 @end deftypefn
3517
3518 @deftypefun ScmObj Scm_MakeTreeMap (ScmTreeCoreCompareProc *@var{cmp}, void *@var{data})
3519 Creates an instance of @code{<tree-map>} object, using the given
3520 comparison function and the opaque data. Although it is built on
3521 top of @code{ScmTreeCore}, it is supposed that @code{ScmTreeMap}'s
3522 entry always have @code{ScmObj} in both key and value. If C code
3523 violates that, the outcome will be undefined.
3524
3525 (If you need to have a tree map with raw C pointers exposed to Scheme
3526 world, create your own type using @code{ScmTreeCore}.)
3527 @end deftypefun
3528
3529 @deftypefun ScmObj Scm_TreeMapCopy (const ScmTreeMap *@var{src})
3530 Returns a newly created tree map, whose content is a copy
3531 of the given tree map.
3532 @end deftypefun
3533
3534 @deftypefun ScmObj Scm_TreeMapRef (ScmTreeMap *@var{tm}, ScmObj @var{key}, ScmObj @var{fallback})
3535 Searches an entry with the given @var{key}, and returns its value.
3536 If there's no entry that has @var{key}, a value passed to @var{fallback}
3537 is returned (unlike Scheme-level @code{tree-map-get}, it doesn't
3538 signals an error).
3539
3540 A standard way to take a specific action when no entry is found is
3541 to pass @code{SCM_UNBOUND} as @var{fallback}, since @code{SCM_UNBOUND}
3542 should never appear as the valid value.
3543
3544 @example
3545 ScmObj v = Scm_TreeMapRef(tm, key, SCM_UNBOUND);
3546 if (SCM_UNBOUNDP(v)) /* no entry for the key */
3547 @end example
3548 @end deftypefun
3549
3550 @deftypefun ScmObj Scm_TreeMapSet (ScmTreeMap *@var{tm}, ScmObj @var{key}, ScmObj @var{val}, ScmObj @var{flags})
3551 Sets @var{val} as the value of the entry that has @var{key}.
3552 @code{Flags} is a bitwise-OR of @code{ScmDictSetFlags}.
3553 Passing 0 to @var{flags} achieves the common action
3554 to modify the entry if it exists, and to create a new one otherwise.
3555 If @var{flags} has @code{SCM_DICT_NO_OVERWRITE} bit set, it won't
3556 modify the existing entry, and only adds a new one if the entry
3557 hasn't existed. If @var{flags} has @code{SCM_DICT_NO_CREATE},
3558 it modifies if the entry exists, but do not add a new one otherwise.
3559 (The effect of specifying both bits is undefined).
3560
3561 Returns the value of the entry of @var{key} after the operation,
3562 or @code{SCM_UNBOUND} iff @code{SCM_DICT_NO_CREATE} is given to the
3563 @var{flags} and no new entry is created.
3564 @end deftypefun
3565
3566 @deftypefun ScmObj Scm_TreeMapDelete (ScmTreeMap *@var{tm}, ScmObj @var{key})
3567 Deletes the entry that has @var{key}. If the entry has existed,
3568 returns its value. Otherwise, returns @code{SCM_UNBOUND}.
3569 @end deftypefun
3570
3571 @deftypefun void Scm_TreeMapDump (ScmTreeMap *@var{tm}, ScmPort *@var{out})
3572 This is for debugging. Dumps the content of tree map with
3573 its internal structure to the given port @var{out}.
3574 @end deftypefun
3575
3576
3577
3578
3579 @node Weak pointers, Exceptions, Dictionaries, C API reference
3580 @section Weak pointers
3581
3582 @node Exceptions, Calling back to Scheme, Weak pointers, C API reference
3583 @section Exceptions
3584
3585 @node Calling back to Scheme, Input and output, Exceptions, C API reference
3586 @section Calling back to Scheme
3587
3588 @node Input and output, Loading programs, Calling back to Scheme, C API reference
3589 @section Input and output
3590
3591 @menu
3592 * Built-in ports::
3593 * Custom ports::
3594 * Input::
3595 * Output::
3596 @end menu
3597
3598 @node Built-in ports, Custom ports, Input and output, Input and output
3599 @subsection Built-in ports
3600
3601 @subsubheading Opening and closing ports
3602
3603 @deftypefun ScmObj Scm_OpenFilePort (const char *path, int flags, int buffering, int perm)
3604 Open a file named by @var{path}, and returns a newly created Scheme port
3605 associated with the file. The @code{name} slot of the created port
3606 is set as @var{path}.
3607
3608 The @var{flags} and @var{perm} arguments are passed to @code{open(2)}
3609 as the second and third argument, respectively. The @var{buffering}
3610 argument may be either one of @code{SCM_PORT_BUFFER_FULL},
3611 @code{SCM_PORT_BUFFER_LINE} or @code{SCM_PORT_BUFFER_NONE},
3612 specifying the buffering mode.
3613
3614 If a file couldn't be opened, @code{SCM_FALSE} is returned. The
3615 reason can be obtained from @code{errno}.
3616 @end deftypefun
3617
3618 @deftypefun ScmObj Scm_MakePortWithFd (ScmObj name, int direction, int fd, int bufmode, int ownerp)
3619 Creates a Scheme port that read from or write to the specified file
3620 descriptor @var{fd}. The @var{name} argument is used for the
3621 port's @var{name} slot. You need to specify either
3622 @code{SCM_PORT_INPUT} or @code{SCM_PORT_OUTPUT} as the direction.
3623 The @var{buffering}
3624 argument may be either one of @code{SCM_PORT_BUFFER_FULL},
3625 @code{SCM_PORT_BUFFER_LINE} or @code{SCM_PORT_BUFFER_NONE},
3626 specifying the buffering mode.
3627
3628 If @var{ownerp} is @code{TRUE}, the created Scheme port becomes the owner
3629 of the file descriptor; that is, when the Scheme port is closed,
3630 it closes the file descriptor, too.
3631 @end deftypefun
3632
3633 @deftypefun ScmObj Scm_MakeInputStringPort (ScmString *@var{str}, int @var{privatep})
3634 Returns a Scheme string port that reads from the given Scheme string.
3635 Corresponds to Scheme's @code{open-input-string}.
3636
3637 If @var{privatep} is @code{TRUE}, the port is pre-locked by the
3638 current thread; i.e. no other threads can access this port, and
3639 the current thread avoids locking overhead.
3640 @end deftypefun
3641
3642 @deftypefun ScmObj Scm_MakeOutputStringPort (int @var{privatep})
3643 Returns a Scheme output string port that collects the stuff written to it.
3644 You can retrieve the result string by @code{Scm_GetOutputString()} below.
3645 Corresponds to Scheme's @code{open-output-string}.
3646
3647 The @var{privatep} flag is the same as @code{Scm_MakeInputStringPort}.
3648 @end deftypefun
3649
3650 @deftypefun ScmObj Scm_GetRemainingInputString (ScmPort *@var{port}, int @var{flags})
3651 @var{port} must be an input string port created by
3652 @code{Scm_MakeInputStringPort}.
3653 Returns a newly-created Scheme string which contains the stuff
3654 in the original string which hasn't been read.
3655
3656 By default, the result string is mutable, and complete as long as
3657 it doesn't contain illegal byte sequences. You may explicitly
3658 make it immutable and/or incomplete by giving
3659 string constructor flags (@code{SCM_STRING_IMMUTABLE}
3660 and/or @code{SCM_STRING_INCOMPLETE}) to the @var{flags} argument
3661 (@pxref{Strings}).
3662 @end deftypefun
3663
3664 @deftypefun ScmObj Scm_GetOutputstring (ScmPort *@var{port}, int @var{flags})
3665 Returns a newly-created Scheme string from the output string port @var{port},
3666 created by @code{Scm_MakeOutputStringPort}.
3667
3668 By default, the result string is mutable, and complete as long as
3669 it doesn't contain illegal byte sequences. You may explicitly
3670 make it immutable and/or incomplete by giving
3671 string constructor flags (@code{SCM_STRING_IMMUTABLE}
3672 and/or @code{SCM_STRING_INCOMPLETE}) to the @var{flags} argument
3673 (@pxref{Strings}).
3674 @end deftypefun
3675
3676 @deftypefun void Scm_ClosePort (ScmPort *@var{port})
3677 Close the port. If it is already closed, nothing is done.
3678 Closing port invokes a cleanup handler associated to the port.
3679 For example, buffered output port may flush its buffer in the
3680 handler. The cleanup handler may run a Scheme code, if the port
3681 is a procedural port. An error caused in a cleanup handler will
3682 raises Scheme exception (i.e. Scm_ClosePort may not return if an error
3683 is raised); such errors should be handled by Scheme error handling
3684 framework.
3685 @end deftypefun
3686
3687 @subsubheading General port information
3688
3689 @deftypefun ScmObj Scm_PortName (ScmPort *@var{port})
3690 Returns the value of @code{name} slot of the port.
3691 If the port is a file port, its name contains the original pathname
3692 of the file. For other ports, the name field contains some
3693 description of ports only useful for debug messages.
3694 @end deftypefun
3695
3696 @deftypefun int Scm_PortLine (ScmPort *@var{port})
3697 Returns the value of @var{line} slot of the port.
3698 Most built-in port types keeps track of the line count,
3699 as far as (1) only character I/O is performed, and
3700 (2) no random-access operation is performed, on the port.
3701 If either of such operation is done on the port, the number
3702 returned from this function doesn't have meaning.
3703
3704 Port line count begins with 1.
3705 @end deftypefun
3706
3707 @deftypefun int Scm_PortFileNo (ScmPort *@var{port})
3708 Returns the port's associated file descriptor number, if any.
3709 Returns -1 otherwise.
3710 @end deftypefun
3711
3712 @subsubheading Locking ports
3713
3714 @subsubheading Pre-created ports
3715
3716 @deftypefn {Macro} ScmPort* SCM_CURIN
3717 @deftypefnx {Macro} ScmPort* SCM_CUROUT
3718 @deftypefnx {Macro} ScmPort* SCM_CURERR
3719 These macro returns the current input, output, and error port
3720 of the current VM, respectively. Corresponds to Scheme's
3721 @code{(current-input-port)}, @code{(current-output-port)},
3722 and @code{(current-error-port)}.
3723 @end deftypefn
3724
3725
3726 @deftypefun ScmObj Scm_Stdin (void)
3727 @deftypefunx ScmObj Scm_Stdout (void)
3728 @deftypefunx ScmObj Scm_Stderr (void)
3729 These functions returns ports associated to file descriptor
3730 0, 1, or 2, respectively. Generally you should use
3731 @code{SCM_CURIN} macro etc., described above, since they're
3732 in sync with Scheme-world's current ports. However, if you
3733 have a reason to access to stdio specifically, you may use
3734 these functions.
3735 @end deftypefun
3736
3737
3738 @node Custom ports, Input, Built-in ports, Input and output
3739 @subsection Custom ports
3740
3741 There are two ways to extend port functionalities and creates
3742 your own port types. A @emph{fully virtual port} basically has
3743 all basic port I/O operations as virtual functions, so you
3744 can override those functionalities as you like.
3745 A @emph{virtual buffered port}, on the other hand, implements
3746 buffering by itself, and calls back your routines when it needs
3747 more data to read or it needs to flush the buffer.
3748
3749 (See the @code{gauche.vport} entry of the Gauche Users' Reference
3750 for the Scheme counterparts of these custom ports)
3751
3752 @subsubheading Fully virtual ports
3753
3754 @deftypefun ScmObj Scm_MakeVirtualport (ScmClass *@var{klass}, int @var{direction}, const ScmPortVTable *@var{vtable})
3755 Returns a newly created fully virtual port of class @var{klass},
3756 which must be a subclass of @code{SCM_CLASS_PORT}.
3757
3758 You need prepare the structure @var{vtable} to specify the behavior
3759 of the port. You can leave some of the fields NULL, if the
3760 functionality is not needed in the port's operation.
3761 The content of the @var{vtable} will be copied,
3762 so you don't need to keep it after the call of @code{Scm_MakeVirtualPort}.
3763
3764 @example
3765 typedef struct ScmPortVTableRec @{
3766 int (*Getb)(ScmPort *p);
3767 int (*Getc)(ScmPort *p);
3768 int (*Getz)(char *buf, int buflen, ScmPort *p);
3769 int (*Ready)(ScmPort *p, int charp);
3770 void (*Putb)(ScmByte b, ScmPort *p);
3771 void (*Putc)(ScmChar c, ScmPort *p);
3772 void (*Putz)(const char *buf, int size, ScmPort *p);
3773 void (*Puts)(ScmString *s, ScmPort *p);
3774 void (*Flush)(ScmPort *p);
3775 void (*Close)(ScmPort *p);
3776 off_t (*Seek)(ScmPort *p, off_t off, int whence);
3777 void *data;
3778 @} ScmPortVTable;
3779 @end example
3780
3781 For a character input port, you must provide at least @code{Getc}
3782 procedure. For a binary input port, you must provide at least
3783 @code{Getb} and @code{Getz} procedures. For a general input port,
3784 on which binary or character input can be done, you must provide
3785 at least those three procedures.
3786
3787 @code{Getb} should return an 8bit unsigned integer value read from
3788 the port, or @code{EOF} if the port has already reached EOF.
3789 @code{Getc} should return an @code{ScmChar} read from the port,
3790 or @code{SCM_CHAR_INVALID} if the port has already reached EOF.
3791 @code{Getz} should read at most @var{buflen} bytes from the port
3792 and store it in @var{buf}, then returns the number of bytes
3793 actually read. Returning @code{0} indicates the port has
3794 already reached EOF.
3795
3796 For a character output port you must provide at least @code{Putc}
3797 and @code{Puts} procedures. For a binary output port you must
3798 provide at least @code{Putb} and @code{Putz} procedures.
3799 For a general output port you must provide at least those four
3800 procedures.
3801
3802 @code{Putb} and @code{Putc} write a byte or a character
3803 to the port, respectively. @code{Putz} writes @var{size} bytes
3804 in @var{buf} to the port. @code{Puts} writes the content of
3805 the given Scheme string to the port.
3806
3807 The @code{Ready} procedure is optional for an input port.
3808 If provided, it is called when @code{char-ready?} or @code{byte-ready?}
3809 Scheme procedure is called on the port (the @var{charp} is @code{TRUE}
3810 for @code{char-ready?}, and @code{FALSE} for @code{byte-ready?}).
3811 It must return @code{TRUE} if a character or a byte is ready to
3812 be read from the port, @code{FALSE} otherwise.
3813 If @code{Ready} procedure is not provided, the port is assumed to
3814 be always ready.
3815
3816 The @code{Close} procedure is optional for a both input and output port.
3817 It is called when the port is closed (either explicitly by
3818 @code{Scm_ClosePort}, or implicitly by the port being garbage-collected).
3819 For output port, @code{Flush} procedure is called just before @code{Close},
3820 so you don't need to care about flushing in this procedure.
3821
3822 The @code{Flush} procedure is optional for an output port.
3823 It is called when an explicit flushing is requested to the port
3824 (such as @code{flush} Scheme procedure), or just before the
3825 @code{Close} procedure when the port is closed.
3826
3827 It is important to note that @code{Close} and @code{Flush} procedures can
3828 be called in finalization stage of the port. That means (1) you
3829 cannot predict in which thread these procedures are called, and
3830 (2) at the time these procedures are called, the objects visible
3831 from these procedures may already be finalized. Extra care needs
3832 to be taken to deal with those irregular situations.
3833
3834 The @code{Seek} procedure is called for seek operation (such as
3835 @code{port-seek} Scheme procedure). If you don't provide
3836 this, the port becomes unseekable.
3837
3838 For all those procedures, error conditions should be reported
3839 by Scheme exception mechanism. Care should be taken not to leave
3840 the port in inconsistent state in case an exception is thrown.
3841
3842 The @code{data} field may contain opaque data to be used in your
3843 custom port operations. Once the procedure port is created,
3844 the value of this data pointer can be accessed by the macro
3845 @code{SCM_PORT_VIRTUAL_DATA}.
3846 @end deftypefun
3847
3848 @subsubheading Virtual buffered ports
3849
3850
3851
3852
3853 @node Input, Output, Custom ports, Input and output
3854 @subsection Input
3855
3856
3857 @node Output, , Input, Input and output
3858 @subsection Output
3859
3860
3861 @node Loading programs, System interface, Input and output, C API reference
3862 @section Loading programs
3863
3864 @deftypefun ScmObj Scm_VMLoadFromPort (ScmPort *@var{port}, ScmObj @var{next_paths}, ScmObj @var{env}, int flags)
3865 This is a CPS API.
3866
3867 The most basic function in the @code{load}-family. Read an expression
3868 from the given port and evaluates it repeatedly, until it reaches
3869 EOF. Then the port is closed. The port is locked by the calling
3870 thread until the operation terminates.
3871
3872 The result of the last evaluation remains on VM.
3873
3874 No matter how the load terminates, either normal or abnormal,
3875 the port is closed, and the current module is restored to the
3876 one when load is called.
3877
3878 @var{Flags} argument is ignored for now, but reserved for future
3879 extension. @code{SCM_LOAD_QUIET_NOFILE} and
3880 @code{SCM_LOAD_IGNORE_CODING}
3881 won't have any effect for @code{Scm_LoadFromPort};
3882 see @code{Scm_Load} below.
3883 @end deftypefun
3884
3885 @deftypefun ScmObj Scm_FindFile (ScmString *@var{filename}, ScmObj *@var{paths}, ScmObj @var{suffixes}, int @var{flags})
3886 Core function to search specified file from the search paths *@var{path}.
3887 Search rules are:
3888
3889 @enumerate
3890 @item
3891 If given filename begins with @file{/}, @file{./} or @file{../},
3892 the file is searched.
3893 @item
3894 If given filename begins with @file{~}, unix-style username
3895 expansion is done, then the resulting file is searched.
3896 @item
3897 Otherwise, the file is searched for each directory in
3898 *@var{paths}.
3899 @end enumerate
3900
3901 If a file is found, it's pathname is returned. *@var{Path} is modified
3902 to contain the remains of load paths, which can be used again to
3903 find next matching filename.
3904
3905 If @var{suffixes} is given, filename is assumed not to have suffix,
3906 and suffixes listed in @var{suffixes} are tried one by one.
3907 The elements in @var{suffixes} is directly appended to the @var{filename};
3908 so usually it begins with dot.
3909
3910 The following flag is effective in @var{flags}. Other flags are ignored.
3911 @table @code
3912 @item SCM_LOAD_QUIET_NOFILE
3913 If this flag is set, @code{Scm_FindFile} returns @code{SCM_FALSE}
3914 when it cannot find the file. If this flag is not set (default),
3915 @code{Scm_FindFile} raises an error.
3916 @end table
3917 @end deftypefun
3918
3919
3920 @node System interface, , Loading programs, C API reference
3921 @section System interface
3922
3923 Gauche provides a few wrapper APIs for operating system interface
3924 to allow applications written without concerning
3925
3926 @c ======================================================================
3927 @node Creating new Scheme datatypes, Helper program reference, C API reference, Top
3928 @chapter Creating new Scheme datatypes
3929
3930
3931
3932
3933
3934 @c ======================================================================
3935 @node Helper program reference, Indices, Creating new Scheme datatypes, Top
3936 @chapter Helper program reference
3937
3938 Several executable scripts are installed along Gauche.
3939 They are to help build and installation process.
3940
3941 @menu
3942 * Managing packages::
3943 * Simplifying build process::
3944 * Gauche-config - configuration parameters::
3945 * Gauche-install - alternative install script::
3946 * Gauche-package - package manager::
3947 @end menu
3948
3949 @node Managing packages, Simplifying build process, Helper program reference, Helper program reference
3950 @section Managing packages
3951
3952 @deffn {Command} gauche-package @var{operation} [@var{option} @dots{}] [@var{arg} ...]
3953
3954 The @code{gauche-package} command is the front-end of managing
3955 Gauche extension packages. It can perform the various operations
3956 according to @var{operation} argument.
3957
3958 @table @asis
3959 @item Download, compile and install packages
3960 @code{install}, @code{build}, @code{compile}
3961 @item Retrieve info about installed packages
3962 @code{list}, @code{reconfigure}, @code{make-gpd}
3963 @item Help package development
3964 @code{generate}
3965 @item Instruct @code{gauche-package} usage
3966 @code{help}
3967 @end table
3968
3969 Among those operations, usually @code{install}, @code{build},
3970 @code{list}, @code{generate} and @code{help} are used directly from
3971 the shell.
3972 Other operations are mainly invoked by @code{make} command.
3973 @end deffn
3974
3975 @menu
3976 * gauche-package operations::
3977 * Customizing gauche-package ::
3978 @end menu
3979
3980 @node gauche-package operations, Customizing gauche-package , Managing packages, Managing packages
3981 @subsection gauche-package operations
3982
3983 @deffn {Package Operation} gauche-package install [@var{options}] @var{tarball-path/url}
3984
3985 This operation obtains the package source specified by @var{tarball-path/url},
3986 then extracts the source, configures and builds,
3987 runs the tests, and installs the built package.
3988 Most of the time this is the only command required to install a Gauche
3989 extension package.
3990
3991 The argument @var{tarball-path/url} may be a URL (http, https, and ftp
3992 are supported), or a path to the local file of gzip-compressed tarball
3993 of the package source. If it is a URL, @code{gauche-package} downloads
3994 it first. By default @code{gauche-package} uses the current working
3995 directory, but you can make it use specific directory by customizing
3996 @file{~/.gauche-package} (@pxref{Customizing gauche-package}).
3997
3998 The following options are recognized by this operation.
3999
4000 @deffn {Option} -n, --dry-run
4001 Shows shell commands to be executed, without running them.
4002 @end deffn
4003
4004 @deffn {Option} -C, --configure-options=@var{options}
4005 Pass @var{options} to the @code{./configure} script. Overrides @code{-r}.
4006 The following command configures the package with the option
4007 @code{--prefix=/opt}.
4008 @example
4009 gauche-package install -C='--prefix=/opt' package.tgz
4010 @end example
4011
4012 Those configure options are recorded in the package description
4013 file
4014 @end deffn
4015
4016
4017 @end deffn
4018
4019
4020 @node Customizing gauche-package , , gauche-package operations, Managing packages
4021 @subsection Customizing gauche-package
4022
4023
4024
4025 @node Simplifying build process, Gauche-config - configuration parameters, Managing packages, Helper program reference
4026 @section Simplifying build process
4027
4028
4029
4030 @deffn {Command} gauche-cesconv [options] [inputfile]
4031 @end deffn
4032
4033 @node Gauche-config - configuration parameters, Gauche-install - alternative install script, Simplifying build process, Helper program reference
4034 @section @code{gauche-config} - configuration parameters
4035
4036 @node Gauche-install - alternative install script, Gauche-package - package manager, Gauche-config - configuration parameters, Helper program reference
4037 @section @code{gauche-install} - alternative install script
4038
4039
4040
4041
4042 @node Gauche-package - package manager, , Gauche-install - alternative install script, Helper program reference
4043 @section @code{gauche-package} - package manager
4044
4045
4046
4047
4048 @c ======================================================================
4049 @node Indices, , Helper program reference, Top
4050 @appendix Indices
4051 @c NODE 索引
4052
4053 @menu
4054 * Function and Macro Index::
4055 * Type Index::
4056 * Variable Index::
4057 @end menu
4058
4059 @node Function and Macro Index, Type Index, Indices, Indices
4060 @appendixsec Function and Macro Index
4061 @printindex fn
4062
4063
4064 @node Type Index, Variable Index, Function and Macro Index, Indices
4065 @appendixsec Type Index
4066 @printindex tp
4067
4068 @node Variable Index, , Type Index, Indices
4069 @appendixsec Variable Index
4070 @printindex vr
4071
4072 @contents
4073 @bye
4074
4075 ;; Local variables:
4076 ;; outline-regexp: "@chap\\|@\\(sub\\)*section"
4077 ;; end: