source: project/chicken/branches/prerelease/manual/Unit library @ 13859

Last change on this file since 13859 was 13859, checked in by felix winkelmann, 11 years ago

merged trunk rev. 13858 (not including srandom change)

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