source: project/chicken/trunk/manual/Unit library @ 5945

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

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

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