source: project/wiki/Unit library @ 7932

Last change on this file since 7932 was 7932, checked in by felix winkelmann, 12 years ago

merged manual from release branch rev. 7332

File size: 28.9 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit library
5
6This unit contains basic Scheme definitions. This unit is used by default,
7unless the program is compiled with the {{-explicit-use}} option.
8
9=== Arithmetic
10
11
12==== add1/sub1
13
14; [procedure] (add1 N)
15; [procedure] (sub1 N)
16
17Adds/subtracts 1 from {{N}}.
18
19==== Binary integer operations
20
21Binary integer operations. {{arithmetic-shift}} shifts the argument {{N1}} by
22{{N2}} bits to the left. If {{N2}} is negative, than {{N1}} is shifted to the
23right. These operations only accept exact integers or inexact integers in word
24range (32 bit signed on 32-bit platforms, or 64 bit signed on 64-bit
25platforms).
26
27; [procedure] (bitwise-and N1 ...)
28; [procedure] (bitwise-ior N1 ...)
29; [procedure] (bitwise-xor N1 ...)
30; [procedure] (bitwise-not N)
31; [procedure] (arithmetic-shift N1 N2)
32
33==== bit-set?
34
35 [procedure] (bit-set? N INDEX)
36
37Returns {{#t}} if the bit at the position {{INDEX}} in the integer {{N}} is
38set, or {{#f}} otherwise. The rightmost/least-significant bit is bit 0.
39
40
41==== fixnum?
42
43 [procedure] (fixnum? X)
44
45Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.
46
47==== Arithmetic fixnum operations
48
49These procedures do not check their arguments, so non-fixnum parameters will
50result in incorrect results. {{fxneg}} negates its argument.
51
52On division by zero, {{fx/}} and {{fxmod}} signal a condition of kind
53{{(exn arithmetic)}}.
54
55{{fxshl}} and {{fxshr}} perform arithmetic shift left and right,
56respectively.
57
58; [procedure] (fx+ N1 N2)
59; [procedure] (fx- N1 N2)
60; [procedure] (fx* N1 N2)
61; [procedure] (fx/ N1 N2)
62; [procedure] (fxmod N1 N2)
63; [procedure] (fxneg N)
64; [procedure] (fxmin N1 N2)
65; [procedure] (fxmax N1 N2)
66; [procedure] (fx= N1 N2)
67; [procedure] (fx> N1 N2)
68; [procedure] (fx< N1 N2)
69; [procedure] (fx>= N1 N2)
70; [procedure] (fx<= N1 N2)
71; [procedure] (fxand N1 N2)
72; [procedure] (fxior N1 N2)
73; [procedure] (fxxor N1 N2)
74; [procedure] (fxnot N)
75; [procedure] (fxshl N1 N2)
76; [procedure] (fxshr N1 N2)
77
78
79==== Arithmetic floating-point operations
80
81In safe mode, these procedures throw a type error with non-float
82arguments (except {{flonum?}}, which returns {{#f}}). In unsafe mode,
83these procedures do not check their arguments. A non-flonum argument
84in unsafe mode can crash the system.
85
86; [procedure] (flonum? X)
87; [procedure] (fp+ X Y)
88; [procedure] (fp- X Y)
89; [procedure] (fp* X Y)
90; [procedure] (fp/ X Y)
91; [procedure] (fpneg X)
92; [procedure] (fpmin X Y)
93; [procedure] (fpmax X Y)
94; [procedure] (fp= X Y)
95; [procedure] (fp> X Y)
96; [procedure] (fp< X Y)
97; [procedure] (fp>= X Y)
98; [procedure] (fp<= X Y)
99
100
101==== signum
102
103 [procedure] (signum N)
104
105Returns {{1}} if {{N}} is positive, {{-1}} if {{N}}
106is negative or {{0}} if {{N}} is zero. {{signum}} is exactness preserving.
107
108
109==== finite?
110
111 [procedure] (finite? N)
112
113Returns {{#f}} if {{N}} is negative or positive infinity, and {{#t}} otherwise.
114
115
116
117=== File Input/Output
118
119==== current-output-port
120
121 [procedure] (current-output-port [PORT])
122
123Returns default output port. If {{PORT}} is given, then that port is selected
124as the new current output port.
125
126Note that the default output port is not buffered. Use [[Unit posix#Setting the
127file buffering mode|{{set-buffering-mode!}}]] if you need a different behavior.
128
129==== current-error-port
130
131 [procedure] (current-error-port [PORT])
132
133Returns default error output port. If {{PORT}} is given, then that port is
134selected as the new current error output port.
135
136Note that the default error output port is not buffered. Use [[Unit
137posix#Setting the file buffering mode|{{set-buffering-mode!}}]] if you need a
138different behavior.
139
140==== flush-output
141
142 [procedure] (flush-output [PORT])
143
144Write buffered output to the given output-port. {{PORT}} defaults
145to the value of {{(current-output-port)}}.
146
147
148==== port-name
149
150 [procedure] (port-name [PORT])
151
152Fetch filename from {{PORT}}. This returns the filename that was used to open
153this file. Returns a special tag string, enclosed into parentheses for
154non-file ports. {{PORT}} defaults to the value of {{(current-input-port)}}.
155
156
157==== port-position
158
159 [procedure] (port-position [PORT])
160
161Returns the current position of {{PORT}} as two values: row and column number.
162If the port does not support such an operation an error is signaled. This
163procedure is currently only available for input ports. {{PORT}} defaults to the
164value of {{(current-input-port)}}.
165
166
167==== set-port-name!
168
169 [procedure] (set-port-name! PORT STRING)
170
171Sets the name of {{PORT}} to {{STRING}}.
172
173
174
175=== Files
176
177==== delete-file
178
179 [procedure] (delete-file STRING)
180
181Deletes the file with the pathname {{STRING}}. If the file does
182not exist, an error is signaled.
183
184
185==== file-exists?
186
187 [procedure] (file-exists? STRING)
188
189Returns {{STRING}} if a file with the given pathname exists, or
190{{#f}} otherwise.
191
192
193==== rename-file
194
195 [procedure] (rename-file OLD NEW)
196
197Renames the file or directory with the pathname {{OLD}} to
198{{NEW}}. If the operation does not succeed, an error is signaled.
199
200
201=== String ports
202
203==== get-output-string
204
205 [procedure] (get-output-string PORT)
206
207Returns accumulated output of a port created with
208{{(open-output-string)}}.
209
210
211==== open-input-string
212
213 [procedure] (open-input-string STRING)
214
215Returns a port for reading from {{STRING}}.
216
217
218==== open-output-string
219
220 [procedure] (open-output-string)
221
222Returns a port for accumulating output in a string.
223
224
225
226
227
228=== Feature identifiers
229
230
231CHICKEN maintains a global list of ''features'' naming functionality available
232in the current system. Additionally the {{cond-expand}} form accesses this
233feature list to infer what features are provided. Predefined features are
234{{chicken}}, and the SRFIs (Scheme Request For Implementation) provided by the
235base system: {{srfi-23, srfi-30, srfi-39}}. If the {{eval}} unit
236is used (the default), the features {{srfi-0, srfi-2, srfi-6, srfi-8, srfi-9}}
237and {{srfi-10}} are defined. When compiling code (during compile-time) the
238feature {{compiling}} is registered. When evaluating code in the interpreter
239(csi), the feature {{csi}} is registered.
240
241
242==== features
243
244 [procedure] (features)
245
246Returns a list of all registered features that will be accepted as valid
247feature-identifiers by {{cond-expand}}.
248
249
250==== feature?
251
252 [procedure] (feature? ID ...)
253
254Returns {{#t}} if all features with the given feature-identifiers {{ID ...}}
255are registered.
256
257
258==== register-feature!
259
260 [procedure] (register-feature! FEATURE ...)
261
262Register one or more features that will be accepted as valid
263feature-identifiers by {{cond-expand}}. {{FEATURE ...}} may
264be a keyword, string or symbol.
265
266
267==== unregister-feature!
268
269 [procedure] (unregister-feature! FEATURE ...)
270
271Unregisters the specified feature-identifiers. {{FEATURE ...}}
272may be a keyword, string or symbol.
273
274
275
276
277
278=== Keywords
279
280Keywords are special symbols prefixed with {{#:}} that evaluate
281to themselves. Procedures can use keywords to accept optional named
282parameters in addition to normal required parameters. Assignment to
283and bindings of keyword symbols is not allowed.
284The parameter {{keyword-style}} and the compiler/interpreter option
285{{-keyword-style}} can be used to allow an additional keyword
286syntax, either compatible to Common LISP, or to DSSSL.
287
288
289
290==== get-keyword
291
292 [procedure] (get-keyword KEYWORD ARGLIST [THUNK])
293
294Returns the argument from {{ARGLIST}} specified under the keyword
295{{KEYWORD}}. If the keyword is not found, then the zero-argument
296procedure {{THUNK}} is invoked and the result value is returned. If
297{{THUNK}} is not given, {{#f}} is returned.
298
299<enscript highlight=scheme>
300(define (increase x . args)
301  (+ x (get-keyword #:amount args (lambda () 1))) )
302(increase 123)                                      ==> 124
303(increase 123 #:amount 10)                          ==> 133
304</enscript>
305
306Note: the {{KEYWORD}} may actually be any kind of object.
307
308
309==== keyword?
310
311 [procedure] (keyword? X)
312
313Returns {{#t}} if {{X}} is a keyword symbol, or {{#f}}
314otherwise.
315
316
317==== keyword->string
318
319 [procedure] (keyword->string KEYWORD)
320
321Transforms {{KEYWORD}} into a string.
322
323
324==== string->keyword
325
326 [procedure] (string->keyword STRING)
327
328Returns a keyword with the name {{STRING}}.
329
330
331
332
333
334=== Exceptions
335
336
337CHICKEN implements the (currently withdrawn)
338[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] exception system. For
339more information, see the
340[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] document.
341
342
343
344==== condition-case
345
346 [syntax] (condition-case EXPRESSION CLAUSE ...)
347
348Evaluates {{EXPRESSION}} and handles any exceptions that are covered by
349{{CLAUSE ...}}, where {{CLAUSE}} should be of the following form:
350
351<enscript highlight=scheme>
352CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
353</enscript>
354
355If provided, {{VARIABLE}} will be bound to the signaled exception
356object. {{BODY ...}} is executed when the exception is a property-
357or composite condition with the kinds given {{KIND ...}} (unevaluated).
358If no clause applies, the exception is re-signaled in the same dynamic
359context as the {{condition-case}} form.
360
361<enscript highlight=scheme>
362(define (check thunk)
363  (condition-case (thunk)
364    [(exn file) (print "file error")]
365    [(exn) (print "other error")]
366    [var () (print "something else")] ) )
367
368(check (lambda () (open-input-file "")))   ; -> "file error"
369(check (lambda () some-unbound-variable))  ; -> "othererror"
370(check (lambda () (signal 99)))            ; -> "something else"
371
372(condition-case some-unbound-variable
373  [(exn file) (print "ignored")] )      ; -> signals error
374
375</enscript>
376
377
378==== breakpoint
379
380 [procedure] (breakpoint [NAME])
381
382Programmatically triggers a breakpoint (similar to the {{,br}} top-level csi
383command).
384
385All error-conditions signaled by the system are of kind {{exn}}.
386The following composite conditions are additionally defined:
387
388<table>
389
390<tr><td> (exn arity)
391
392Signaled when a procedure is called with the wrong number of arguments.
393
394</td></tr><tr><td> (exn type)
395
396Signaled on type-mismatch errors, for example when an argument of the wrong
397type is passed to a built-in procedure.
398
399</td></tr><tr><td> (exn arithmetic)
400
401Signaled on arithmetic errors, like division by zero.
402
403</td></tr><tr><td> (exn i/o)
404
405Signaled on input/output errors.
406
407</td></tr><tr><td> (exn i/o file)
408
409Signaled on file-related errors.
410
411</td></tr><tr><td> (exn i/o net)
412
413Signaled on network errors.
414
415</td></tr><tr><td> (exn bounds)
416
417Signaled on errors caused by accessing non-existent elements of a collection.
418
419</td></tr><tr><td> (exn runtime)
420
421Signaled on low-level runtime-system error-situations.
422
423</td></tr><tr><td> (exn runtime limit)
424
425Signaled when an internal limit is exceeded (like running out of memory).
426
427</td></tr><tr><td> (exn match)
428
429Signaled on errors raised by failed matches (see the section on {{match}}).
430
431</td></tr><tr><td> (exn syntax)
432
433Signaled on syntax errors.
434
435</td></tr><tr><td> (exn breakpoint)
436
437Signaled when a breakpoint is reached.
438
439</td></tr>
440
441</table>
442
443Notes:
444
445* All error-exceptions (of the kind {{exn}}) are non-continuable.
446
447* Error-exceptions of the {{exn}} kind have additional {{arguments}} and
448{{location}} properties that contain the arguments passed to the
449exception-handler and the name of the procedure where the error occurred (if
450available).
451
452* When the {{posix}} unit is available and used, then a user-interrupt
453({{signal/int}}) signals an exception of the kind {{user-interrupt}}.
454
455* the procedure {{condition-property-accessor}} accepts an optional third
456argument. If the condition does not have a value for the desired property and
457if the optional argument is given, no error is signaled and the accessor
458returns the third argument.
459
460* In composite conditions all properties are currently collected in a single
461property-list, so in the case that to conditions have the same named property,
462only one will be visible.
463
464
465
466=== Environment information and system interface
467
468
469
470==== argv
471
472 [procedure] (argv)
473
474Return a list of all supplied command-line arguments. The first item in
475the list is a string containing the name of the executing program. The
476other items are the arguments passed to the application. This list is
477freshly created on every invocation of {{(argv)}}. It depends on
478the host-shell whether arguments are expanded ('globbed') or not.
479
480
481==== exit
482
483 [procedure] (exit [CODE])
484
485Exit the running process and return exit-code, which defaults to 0
486(Invokes {{exit-handler}}).
487
488Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
489==== build-platform
490
491 [procedure] (build-platform)
492
493Returns a symbol specifying the toolset which has been used for
494building the executing system, which is one of the following:
495
496 cygwin
497 mingw32
498 gnu
499 intel
500 unknown
501
502
503==== chicken-version
504
505 [procedure] (chicken-version [FULL])
506
507Returns a string containing the version number of the CHICKEN runtime
508system. If the optional argument {{FULL}} is given and true, then
509a full version string is returned.
510
511
512==== errno
513
514 [procedure] (errno)
515
516Returns the error code of the last system call.
517
518
519==== getenv
520
521 [procedure] (getenv STRING)
522
523Returns the value of the environment variable {{STRING}} or
524{{#f}} if that variable is not defined.
525
526
527
528==== machine-byte-order
529
530 [procedure] (machine-byte-order)
531
532Returns the symbol {{little-endian}} or {{big-endian}}, depending on the
533machine's byte-order.
534
535
536==== machine-type
537
538 [procedure] (machine-type)
539
540Returns a symbol specifying the processor on which this process is
541currently running, which is one of the following:
542
543 alpha
544 mips
545 hppa
546 ultrasparc
547 sparc
548 ppc
549 ppc64
550 ia64
551 x86
552 x86-64
553 unknown
554
555
556==== on-exit
557
558 [procedure] (on-exit THUNK)
559
560Schedules the zero-argument procedures {{THUNK}} to be executed before
561the process exits, either explicitly via {{exit}} or implicitly after execution
562of the last top-level form. Note that finalizers for unreferenced finalized
563data are run before exit procedures.
564
565
566==== software-type
567
568 [procedure] (software-type)
569
570Returns a symbol specifying the operating system on which this process
571is currently running, which is one of the following:
572
573 windows
574 unix
575 macos
576 ecos
577 unknown
578
579
580==== software-version
581
582 [procedure] (software-version)
583
584Returns a symbol specifying the operating system version on which this
585process is currently running, which is one of the following:
586
587 linux
588 freebsd
589 netbsd
590 openbsd
591 macosx
592 hpux
593 solaris
594 sunos
595 unknown
596
597
598
599==== c-runtime
600
601 [procedure] (c-runtime)
602
603Returns a symbol that designates what kind of C runtime library has been linked
604with this version of the Chicken libraries. Possible return values are
605{{static}}, {{dynamic}} or {{unknown}}. On systems not compiled with the
606Microsoft C compiler, {{c-runtime}} always returns {{unknown}}.
607
608
609==== system
610
611 [procedure] (system STRING)
612
613Execute shell command. The functionality offered by this procedure
614depends on the capabilities of the host shell. If the forking of a subprocess
615failed, an exception is raised. Otherwise the return status of the
616subprocess is returned unaltered.
617
618
619
620
621=== Execution time
622
623
624
625==== cpu-time
626
627 [procedure] (cpu-time)
628
629Returns the used CPU time of the current process in milliseconds as
630two values: the time spent in user code, and the time spent in system
631code. On platforms where user and system time can not be differentiated,
632system time will be always be 0.
633
634
635==== current-milliseconds
636
637 [procedure] (current-milliseconds)
638
639Returns the number of milliseconds since process- or machine startup.
640
641
642==== current-seconds
643
644 [procedure] (current-seconds)
645
646Returns the number of seconds since midnight, Jan. 1, 1970.
647
648
649==== current-gc-milliseconds
650
651 [procedure] (current-gc-milliseconds)
652
653Returns the number of milliseconds spent in major garbage collections since
654the last call of {{current-gc-milliseconds}} and returns an exact
655integer.
656
657
658
659=== Interrupts and error-handling
660
661
662
663==== enable-warnings
664
665 [procedure] (enable-warnings [BOOL])
666
667Enables or disables warnings, depending on wether {{BOOL}} is true or false.
668If called with no arguments, this procedure returns {{#t}} if warnings are
669currently enabled, or {{#f}} otherwise. Note that this is not a parameter.
670The current state (whether warnings are enabled or disabled) is global and not
671thread-local.
672
673
674==== error
675
676 [procedure] (error [LOCATION] [STRING] EXP ...)
677
678Prints error message, writes all extra arguments to the
679value of {{(current-error-port)}} and invokes the
680current exception-handler. This conforms to
681[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]].
682If {{LOCATION}} is given and a symbol, it specifies the ''location'' (the name
683of the procedure) where the error occurred.
684
685
686
687==== get-call-chain
688
689 [procedure] (get-call-chain [START [THREAD]])
690
691Returns a list with the call history. Backtrace information
692is only generated in code compiled without {{-no-trace}} and evaluated code.
693If the optional argument {{START}} is given, the backtrace starts
694at this offset, i.e. when {{START}} is 1, the next to last trace-entry
695is printed, and so on. If the optional argument {{THREAD}} is given, then
696the call-chain will only be constructed for calls performed by this thread.
697
698
699
700==== print-call-chain
701
702 [procedure] (print-call-chain [PORT [START [THREAD]]])
703
704Prints a backtrace of the procedure call history to {{PORT}},
705which defaults to {{(current-output-port)}}.
706
707
708==== print-error-message
709
710 [procedure] (print-error-message EXN [PORT [STRING]])
711
712Prints an appropriate error message to {{PORT}} (which defaults to the
713value of {{(current-output-port)}} for the object {{EXN}}.
714{{EXN}} may be a condition, a string or any other object.
715If the optional argument {{STRING}} is given, it is printed before the
716error-message. {{STRING}} defaults to {{"Error:"}}.
717
718
719
720==== procedure-information
721
722 [procedure] (procedure-information PROC)
723
724Returns an s-expression with debug information for the procedure {{PROC}}, or
725{{#f}}, if {{PROC}} has no associated debug information.
726
727
728==== reset
729
730 [procedure] (reset)
731
732Reset program (Invokes {{reset-handler}}).
733
734
735==== warning
736
737 [procedure] (warning STRING EXP ...)
738
739Displays a warning message (if warnings are enabled with {{enable-warnings}}) and
740continues execution.
741
742
743==== singlestep
744
745 [procedure] (singlestep THUNK)
746
747Executes the code in the zero-procedure {{THUNK}} in single-stepping mode.
748
749
750
751=== Garbage collection
752
753
754
755==== gc
756
757 [procedure] (gc [FLAG])
758
759Invokes a garbage-collection and returns the number of free bytes in the heap.
760The flag specifies whether a minor ({{#f}}) or major ({{#t}}) GC is to be
761triggered. If no argument is given, {{#t}} is assumed. An explicit {{#t}}
762argument will cause all pending finalizers to be executed.
763
764==== memory-statistics
765
766 [procedure] (memory-statistics)
767
768Performs a major garbage collection and returns a three element vector
769containing the total heap size in bytes, the number of bytes currently
770used and the size of the nursery (the first heap generation). Note
771that the actual heap is actually twice the size given in the heap size,
772because CHICKEN uses a copying semi-space collector.
773
774
775==== set-finalizer!
776
777 [procedure] (set-finalizer! X PROC)
778
779Registers a procedure of one argument {{PROC}}, that will be
780called as soon as the non-immediate data object {{X}} is about to
781be garbage-collected (with that object as its argument). Note that
782the finalizer will '''not''' be called while interrupts are disabled.
783This procedure returns {{X}}.
784
785
786==== set-gc-report!
787
788 [procedure] (set-gc-report! FLAG)
789
790Print statistics after every GC, depending on {{FLAG}}. A value of
791{{#t}} shows statistics after every major GC. A true value different
792from {{#t}} shows statistics after every minor GC. {{#f}}
793switches statistics off.
794
795
796
797
798
799=== Other control structures
800
801
802
803==== promise?
804
805 [procedure] (promise? X)
806
807Returns {{#t}} if {{X}} is a promise returned by {{delay}}, or
808{{#f}} otherwise.
809
810
811
812=== String utilities
813
814
815==== reverse-list->string
816
817 [procedure] (reverse-list->string LIST)
818
819Returns a string with the characters in {{LIST}} in reverse order. This is
820equivalent to {{(list->string (reverse LIST))}}, but much more efficient.
821
822
823
824=== Generating uninterned symbols
825
826==== gensym
827
828 [procedure] (gensym [STRING-OR-SYMBOL])
829
830Returns a newly created uninterned symbol. If an argument is provided,
831the new symbol is prefixed with that argument.
832
833
834==== string->uninterned-symbol
835
836 [procedure] (string->uninterned-symbol STRING)
837
838Returns a newly created, unique symbol with the name {{STRING}}.
839
840
841
842=== Standard Input/Output
843
844==== port?
845
846 [procedure] (port? X)
847
848Returns {{#t}} if {{X}} is a port object or {{#f}}
849otherwise.
850
851
852==== print
853
854 [procedure] (print [EXP1 ...])
855
856Outputs the optional arguments {{EXP1 ...}} using {{display}} and
857writes a newline character to the port that is the value of
858{{(current-output-port)}}. Returns {{(void)}}.
859
860
861==== print*
862
863 [procedure] (print* [EXP1 ...])
864
865Similar to {{print}}, but does not output a terminating newline
866character and performs a {{flush-output}} after writing its arguments.
867
868
869
870
871=== User-defined named characters
872
873==== char-name
874
875 [procedure] (char-name SYMBOL-OR-CHAR [CHAR])
876
877This procedure can be used to inquire about character names or to
878define new ones. With a single argument the behavior is as follows:
879If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
880the character with this name, or {{#f}} if no character is defined
881under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
882name of the character is returned as a symbol, or {{#f}} if the
883character has no associated name.
884
885If the optional argument {{CHAR}} is provided, then
886{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
887the given character. If multiple names designate the same character,
888then the {{write}} will use the character name that was defined last.
889
890<enscript highlight=scheme>
891(char-name 'space)                  ==> #\space
892(char-name #\space)                 ==> space
893(char-name 'bell)                   ==> #f
894(char-name (integer->char 7))       ==> #f
895(char-name 'bell (integer->char 7))
896(char-name 'bell)                   ==> #\bell
897(char->integer (char-name 'bell))   ==> 7
898</enscript>
899
900
901
902=== Blobs
903
904"blobs" are collections of unstructured bytes. You can't do much
905with them, but allow conversion to and from SRFI-4 number vectors.
906
907==== make-blob
908
909 [procedure] (make-blob SIZE)
910
911Returns a blob object of {{SIZE}} bytes, aligned on an 8-byte boundary,
912uninitialized.
913
914==== blob?
915
916 [procedure] (blob? X)
917
918Returns {{#t}} if {{X}} is a blob object, or
919{{#f}} otherwise.
920
921==== blob-size
922
923 [procedure] (blob-size BLOB)
924
925Returns the number of bytes in {{BLOB}}.
926
927==== blob->string
928
929 [procedure] (blob->string BLOB)
930
931Returns a string with the contents of {{BLOB}}.
932
933==== string->blob
934
935 [procedure] (string->blob STRING)
936
937Returns a blob with the contents of {{STRING}}.
938
939==== blob=?
940
941 [procedure] (blob=? BLOB1 BLOB2)
942
943Returns {{#t}} if the two argument blobs are of the same
944size and have the same content.
945
946
947
948=== Vectors
949
950==== vector-copy!
951
952 [procedure] (vector-copy! VECTOR1 VECTOR2 [COUNT])
953
954Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
955argument {{COUNT}} is given, it specifies the maximal number of
956elements to be copied. If not given, the minimum of the lengths of the
957argument vectors is copied.
958
959Exceptions: {{(exn bounds)}}
960
961
962==== vector-resize
963
964 [procedure] (vector-resize VECTOR N [INIT])
965
966Creates and returns a new vector with the contents of {{VECTOR}} and length
967{{N}}. If {{N}} is greater than the original length of {{VECTOR}}, then all
968additional items are initialized to {{INIT}}. If {{INIT}} is not specified, the
969contents are initialized to some unspecified value.
970
971
972
973=== The unspecified value
974
975==== void
976
977 [procedure] (void)
978
979Returns an unspecified value.
980
981
982
983=== Continuations
984
985==== call/cc
986
987 [procedure] (call/cc PROCEDURE)
988
989An alias for {{call-with-current-continuation}}.
990
991
992==== continuation-capture
993
994 [procedure] (continuation-capture PROCEDURE)
995
996Creates a continuation object representing the current continuation and
997tail-calls {{PROCEDURE}} with this continuation as the single argument.
998
999More information about this continuation API can be found in the paper
1000[[http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf]] ''A Better
1001API for first class Continuations'' by Marc Feeley.
1002
1003
1004==== continuation?
1005
1006 [procedure] (continuation? X)
1007
1008Returns {{#t}} if {{X}} is a continuation object, or {{#f}} otherwise. Please
1009note that this applies only to continuations created by the Continuation API,
1010but not by call/cc, i.e.: {{(call-with-current-continuation continuation?)}}
1011returns {{#f}}, whereas {{(continuation-capture continuation?)}} returns
1012{{#t}}.
1013
1014
1015==== continuation-graft
1016
1017 [procedure] (continuation-graft CONT THUNK)
1018
1019Calls the procedure {{THUNK}} with no arguments and the implicit continuation
1020{{CONT}}.
1021
1022
1023==== continuation-return
1024
1025 [procedure] (continuation-return CONT VALUE ...)
1026
1027Returns the value(s) to the continuation {{CONT}}. {{continuation-return}} could
1028be implemented like this:
1029
1030<enscript highlight=scheme>
1031(define (continuation-return k . vals)
1032  (continuation-graft
1033    k
1034    (lambda () (apply values vals)) ) )
1035</enscript>
1036
1037
1038
1039=== Setters
1040
1041SRFI-17 is fully implemented. For more information see:
1042[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
1043
1044==== setter
1045
1046 [procedure] (setter PROCEDURE)
1047
1048Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
1049{{PROCEDURE}} has no associated setter-procedure.
1050
1051Note that {{(set! (setter PROC) ...)}} for a procedure that has no associated
1052setter procedure yet is a very slow operation (the old procedure is replaced by
1053a modified copy, which involves a garbage collection).
1054
1055
1056==== getter-with-setter
1057
1058 [procedure] (getter-with-setter GETTER SETTER)
1059
1060Returns a copy of the procedure {{GETTER}} with the associated setter procedure
1061{{SETTER}}. Contrary to the SRFI specification, the setter of the returned
1062procedure may be changed.
1063
1064
1065
1066=== Reader extensions
1067
1068==== define-reader-ctor
1069
1070 [procedure] (define-reader-ctor SYMBOL PROC)
1071
1072Define new read-time constructor for {{#,}} read syntax. For further information, see
1073the documentation for [[http://srfi.schemers.org/srfi-10/srfi-10.html|SRFI-10]].
1074
1075
1076==== set-read-syntax!
1077
1078 [procedure] (set-read-syntax! CHAR-OR-SYMBOL PROC)
1079
1080When the reader encounters the non-whitespace character {{CHAR}} while reading
1081an expression from a given port, then the procedure {{PROC}} will be called with
1082that port as its argument. The procedure should return a value that will be returned
1083to the reader:
1084
1085<enscript highlight=scheme>
1086 ; A simple RGB color syntax:
1087
1088 (set-read-syntax! #\%
1089   (lambda (port)
1090     (apply vector
1091       (map (cut string->number <> 16)
1092            (string-chop (read-string 6 port) 2) ) ) ) )
1093
1094 (with-input-from-string "(1 2 %f0f0f0 3)" read)
1095 ; ==> (1 2 #(240 240 240) 3)
1096</enscript>
1097
1098If {{CHAR-OR-SYMBOL}} is a symbol, then a so-called ''read-mark'' handler is defined.
1099In that case the handler procedure will be called when a character-sequence of the
1100form
1101
1102 #!SYMBOL
1103
1104is encountered.
1105
1106You can undo special handling of read-syntax by passing {{#f}} as the second argument
1107(if the syntax was previously defined via {{set-read-syntax!}}).
1108
1109Note that all of CHICKEN's special non-standard read-syntax is handled directly by the reader.
1110To disable built-in read-syntax, define a handler that triggers an error (for example).
1111
1112
1113==== set-sharp-read-syntax!
1114
1115 [procedure] (set-sharp-read-syntax! CHAR-OR-SYMBOL PROC)
1116
1117Similar to {{set-read-syntax!}}, but allows defining new {{#<CHAR> ...}} reader syntax.
1118If the first argument is a symbol, then this procedure is equivalent to {{set-read-syntax!}}.
1119
1120
1121==== set-parameterized-read-syntax!
1122
1123 [procedure] (set-parameterized-read-syntax! CHAR-OR-SYMBOL PROC)
1124
1125Similar to {{set-sharp-read-syntax!}}, but intended for defining reader syntax of the
1126form {{#<NUMBER><CHAR> ...}}. The handler procedure {{PROC}} will be called with two
1127arguments: the input port and the number preceding
1128the dispatching character.
1129If the first argument is a symbol, then this procedure is equivalent to {{set-read-syntax!}}.
1130
1131
1132==== copy-read-table
1133
1134 [procedure] (copy-read-table READ-TABLE)
1135
1136Returns a copy of the given read-table. You can access the currently active read-table
1137with {{(current-read-table)}}.
1138
1139
1140=== Property lists
1141
1142As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
1143Properties are accessible via a key that can be any kind of value but which will
1144be compared using {{eq?}}.
1145
1146==== get
1147
1148  [procedure] (get SYMBOL PROPERTY [DEFAULT])
1149
1150Returns the value stored under the key {{PROPERTY}} in the property
1151list of {{SYMBOL}}. If no such property is stored, returns
1152{{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
1153
1154==== put!
1155
1156  [procedure] (put! SYMBOL PROPERTY VALUE)
1157  [setter] (set! (get SYMBOL PROPERTY) VALUE)
1158
1159Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
1160{{SYMBOL}} replacing any previously stored value.
1161
1162==== remprop!
1163
1164  [procedure] (remprop! SYMBOL PROPERTY)
1165
1166Deletes the first property matching the key {{PROPERTY}} in the property list
1167of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
1168
1169==== symbol-plist
1170
1171  [procedure] (symbol-plist SYMBOL)
1172  [setter] (set! (symbol-plist SYMBOL) LST)
1173
1174Returns the property list of {{SYMBOL}} or sets it.
1175
1176==== get-properties
1177
1178  [procedure] (get-properties SYMBOL PROPERTIES)
1179
1180Searches the property list of {{SYMBOL}} for the first property with a key in
1181the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
1182and the tail of property list after the matching property. When no match found
1183all values are {{#f}}.
1184
1185{{PROPERTIES}} may also be an atom, in which case it is treated as a list of
1186one element.
1187
1188
1189Previous: [[Parameters]]
1190
1191Next: [[Unit eval]]
Note: See TracBrowser for help on using the repository browser.