source: project/wiki/Unit library @ 2905

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

manual updates

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