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

Last change on this file since 25875 was 25875, checked in by felix winkelmann, 9 years ago

merged some manual changes from master into wiki

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