source: project/wiki/Unit library @ 2794

Last change on this file since 2794 was 2794, checked in by felix winkelmann, 14 years ago

chicken update, codewalk fix, bb experiment

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