source: project/wiki/man/4/Unit library @ 34906

Last change on this file since 34906 was 34906, checked in by svnwiki, 3 years ago

Anonymous wiki edit for IP [74.209.19.243]: Alphabetized symbol lists and changed wording for software-type and software-version

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