source: project/wiki/man/5/TODO/Unit library @ 34261

Last change on this file since 34261 was 34261, checked in by sjamaan, 15 months ago

man/5: Add Module (chicken plist)

File size: 15.3 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==== exact-integer-sqrt
21
22<procedure>(exact-integer-sqrt K)</procedure>
23
24Returns two values {{s}} and {{r}}, where {{s^2 + r = K}} and {{K < (s+1)^2}}.
25In other words, {{s}} is the closest square root we can find that's equal to or
26smaller than {{K}}, and {{r}} is the rest if {{K}} isn't a neat square of two numbers.
27
28This procedure is compatible with the R7RS specification.
29
30==== exact-integer-nth-root
31
32<procedure>(exact-integer-nth-root K N)</procedure>
33
34Like {{exact-integer-sqrt}}, but with any base value.  Calculates
35{{\sqrt[N]{K}}}, the {{N}}th root of {{K}} and returns two values
36{{s}} and {{r}} where {{s^N + r = K}} and {{K < (s+1)^N}}.
37
38
39==== fixnum?
40
41<procedure>(fixnum? X)</procedure>
42
43Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.
44
45==== flonum?
46
47<procedure>(flonum? X)</procedure>
48
49Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.
50
51==== bignum?
52
53<procedure>(bignum? X)</procedure>
54
55Returns {{#t}} if {{X}} is a bignum (integer larger than fits in a
56fixnum), or {{#f}} otherwise.
57
58==== exact-integer?
59
60<procedure>(exact-integer? X)</procedure>
61
62Returns {{#t}} if {{X}} is an exact integer (i.e., a fixnum or a
63bignum), or {{#f}} otherwise.
64
65==== cplxnum?
66
67<procedure>(cplxnum? X)</procedure>
68
69Returns {{#t}} if {{X}} is a true complex number (it has an imaginary
70component), or {{#f}} otherwise.
71
72Please note that {{complex?}} will always return {{#t}} for any number
73type supported by CHICKEN, so you can use this predicate if you want
74to know the representational type of a number.
75
76==== ratnum?
77
78<procedure>(ratnum? X)</procedure>
79
80Returns {{#t}} if {{X}} is a true rational number (it is a fraction
81with a denominator that's not 1), or {{#f}} otherwise.
82
83Please note that {{rational?}} will always return {{#t}} for any
84number type supported by CHICKEN except complex numbers and non-finite
85flonums, so you can use this predicate if you want to know the
86representational type of a number.
87
88==== Division with quotient and remainder
89
90<procedure>(quotient&remainder X Y)</procedure>
91<procedure>(quotient&modulo X Y)</procedure>
92
93Returns two values: the quotient and the remainder (or modulo) of
94{{X}} divided by {{Y}}.  Could be defined as {{(values (quotient X Y)
95(remainder X Y))}}, but is much more efficient when dividing very
96large numbers.
97
98
99==== nan?
100
101<procedure>(nan? N)</procedure>
102
103Returns {{#t}} if {{N}} is not a number (a IEEE flonum NaN-value).  If
104{{N}} is a complex number, it's considered nan if it has a real or
105imaginary component that's nan.
106
107==== finite?
108
109<procedure>(infinite? N)</procedure>
110
111Returns {{#t}} if {{N}} is negative or positive infinity, and {{#f}}
112otherwise.  If {{N}} is a complex number, it's considered infinite if
113it has a real or imaginary component that's infinite.
114
115==== finite?
116
117<procedure>(finite? N)</procedure>
118
119Returns {{#t}} if {{N}} represents a finite number and {{#f}}
120otherwise.  Positive and negative infinity as well as NaNs are not
121considered finite.  If {{N}} is a complex number, it's considered
122finite if both the real and imaginary components are finite.
123
124==== signum
125
126<procedure>(signum N)</procedure>
127
128For real numbers, returns {{1}} if {{N}} is positive, {{-1}} if {{N}}
129is negative or {{0}} if {{N}} is zero. {{signum}} is exactness
130preserving.
131
132For complex numbers, returns a complex number of the same angle but
133with magnitude 1.
134
135=== File Input/Output
136
137==== current-output-port
138
139<procedure>(current-output-port [PORT])</procedure>
140
141Returns default output port. If {{PORT}} is given, then that port is selected
142as the new current output port.
143
144Note that the default output port is not buffered. Use [[Unit posix#Setting the
145file buffering mode|{{set-buffering-mode!}}]] if you need a different behavior.
146
147==== current-error-port
148
149<procedure>(current-error-port [PORT])</procedure>
150
151Returns default error output port. If {{PORT}} is given, then that port is
152selected as the new current error output port.
153
154Note that the default error output port is not buffered. Use [[Unit
155posix#Setting the file buffering mode|{{set-buffering-mode!}}]] if you need a
156different behavior.
157
158==== flush-output
159
160<procedure>(flush-output [PORT])</procedure>
161
162Write buffered output to the given output-port. {{PORT}} defaults
163to the value of {{(current-output-port)}}.
164
165==== input-port-open?
166
167<procedure>(input-port-open? PORT)</procedure>
168
169Is the given {{PORT}} open for input?
170
171<procedure>(output-port-open? PORT)</procedure>
172
173Is the given {{PORT}} open for output?
174
175==== port-closed?
176
177<procedure>(port-closed? PORT)</procedure>
178
179Is the given {{PORT}} closed (in all directions)?
180
181==== port-name
182
183<procedure>(port-name [PORT])</procedure>
184
185Fetch filename from {{PORT}}. This returns the filename that was used to open
186this file. Returns a special tag string, enclosed into parentheses for
187non-file ports. {{PORT}} defaults to the value of {{(current-input-port)}}.
188
189
190==== port-position
191
192<procedure>(port-position [PORT])</procedure>
193
194Returns the current position of {{PORT}} as two values: row and column number.
195If the port does not support such an operation an error is signaled. This
196procedure is currently only available for input ports. {{PORT}} defaults to the
197value of {{(current-input-port)}}.
198
199
200==== set-port-name!
201
202<procedure>(set-port-name! PORT STRING)</procedure>
203
204Sets the name of {{PORT}} to {{STRING}}.
205
206
207=== String ports
208
209==== get-output-string
210
211<procedure>(get-output-string PORT)</procedure>
212
213Returns accumulated output of a port created with
214{{(open-output-string)}}.
215
216
217==== open-input-string
218
219<procedure>(open-input-string STRING)</procedure>
220
221Returns a port for reading from {{STRING}}.
222
223
224==== open-output-string
225
226<procedure>(open-output-string)</procedure>
227
228Returns a port for accumulating output in a string.
229
230
231
232=== System interface
233
234==== sleep
235
236<procedure>(sleep SECONDS)</procedure>
237
238Puts the program to sleep for {{SECONDS}}. If the scheduler is loaded
239(for example when srfi-18 is in use) then only the calling thread is put
240to sleep and other threads may continue executing. Otherwise, the whole
241process is put to sleep.
242
243
244=== Interrupts and error-handling
245
246==== enable-warnings
247
248<procedure>(enable-warnings [BOOL])</procedure>
249
250Enables or disables warnings, depending on wether {{BOOL}} is true or false.
251If called with no arguments, this procedure returns {{#t}} if warnings are
252currently enabled, or {{#f}} otherwise. Note that this is not a parameter.
253The current state (whether warnings are enabled or disabled) is global and not
254thread-local.
255
256
257==== error
258
259<procedure>(error [LOCATION] [STRING] EXP ...)</procedure>
260
261Prints error message, writes all extra arguments to the
262value of {{(current-error-port)}} and invokes the
263current exception-handler. This conforms to
264[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]].
265If {{LOCATION}} is given and a symbol, it specifies the ''location'' (the name
266of the procedure) where the error occurred.
267
268
269
270==== get-call-chain
271
272<procedure>(get-call-chain [START [THREAD]])</procedure>
273
274Returns a list with the call history. Backtrace information
275is only generated in code compiled without {{-no-trace}} and evaluated code.
276If the optional argument {{START}} is given, the backtrace starts
277at this offset, i.e. when {{START}} is 1, the next to last trace-entry
278is printed, and so on. If the optional argument {{THREAD}} is given, then
279the call-chain will only be constructed for calls performed by this thread.
280
281
282
283==== print-call-chain
284
285<procedure>(print-call-chain [PORT [START [THREAD [HEADER]]]])</procedure>
286
287Prints a backtrace of the procedure call history to {{PORT}},
288which defaults to {{(current-output-port)}}. The output is prefixed by the
289{{HEADER}}, which defaults to {{"\n\tCall history:\n"}}.
290
291
292==== print-error-message
293
294<procedure>(print-error-message EXN [PORT [HEADER]])</procedure>
295
296Prints an appropriate error message to {{PORT}} (which defaults to the value of
297{{(current-output-port)}} for the object {{EXN}}. {{EXN}} may be a condition, a
298string or any other object. The output is prefixed by the {{HEADER}}, which
299defaults to {{"Error:"}}.
300
301
302==== procedure-information
303
304<procedure>(procedure-information PROC)</procedure>
305
306Returns an s-expression with debug information for the procedure {{PROC}}, or
307{{#f}}, if {{PROC}} has no associated debug information.
308
309
310==== reset
311
312<procedure>(reset)</procedure>
313
314Reset program (Invokes {{reset-handler}}).
315
316
317==== warning
318
319<procedure>(warning STRING EXP ...)</procedure>
320
321Displays a warning message (if warnings are enabled with {{enable-warnings}}) and
322continues execution.
323
324
325
326
327=== Other predicates and comparison operations
328
329
330
331==== promise?
332
333<procedure>(promise? X)</procedure>
334
335Returns {{#t}} if {{X}} is a promise returned by {{delay}}, or
336{{#f}} otherwise.
337
338
339==== equal=?
340
341<procedure>(equal=? X y)</procedure>
342
343Similar to the standard procedure {{equal?}}, but compares numbers
344using the {{=}} operator, so {{equal=?}} allows structural comparison
345in combination with comparison of numerical data by value.
346
347
348
349=== String utilities
350
351
352==== reverse-list->string
353
354<procedure>(reverse-list->string LIST)</procedure>
355
356Returns a string with the characters in {{LIST}} in reverse order. This is
357equivalent to {{(list->string (reverse LIST))}}, but much more efficient.
358
359
360
361=== Symbols
362
363==== Symbol utilities
364
365===== symbol-append
366
367<procedure>(symbol-append SYMBOL1 ...)</procedure>
368
369Creates a new symbol from the concatenated names of the argument symbols
370{{(SYMBOL1 ...)}}.
371
372==== Uninterned symbols ("gensyms")
373
374Symbols may be "interned" or "uninterned". Interned symbols are
375registered in a global table, and when read back from a port are
376identical to a symbol written before:
377
378<enscript highlight=scheme>
379(define sym 'foo)
380
381(eq? sym (with-input-from-string
382            (with-output-to-string
383              (lambda () (write sym)))
384            read))
385
386  => #t
387</enscript>
388
389Uninterned symbols on the other hand are not globally registered and so
390multiple symbols with the same name may coexist:
391
392<enscript highlight=scheme>
393(define sym (gensym 'foo))   ; sym is a uninterned symbol like "foo42"
394
395(eq? sym (with-input-from-string    ; the symbol read will be an interned symbol
396            (with-output-to-string
397              (lambda () (write sym)))
398            read))
399
400  => #f
401
402(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))
403
404  => #f
405</enscript>
406
407Use uninterned symbols if you need to generate unique values that
408can be compared quickly, for example as keys into a hash-table
409or association list. Note that uninterned symbols lose their
410uniqueness property when written to a file and read back in, as
411in the example above.
412
413
414===== gensym
415
416<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
417
418Returns a newly created uninterned symbol. If an argument is provided,
419the new symbol is prefixed with that argument.
420
421
422===== string->uninterned-symbol
423
424<procedure>(string->uninterned-symbol STRING)</procedure>
425
426Returns a newly created, unique symbol with the name {{STRING}}.
427
428
429=== Standard Input/Output
430
431==== port?
432
433<procedure>(port? X)</procedure>
434
435Returns {{#t}} if {{X}} is a port object or {{#f}}
436otherwise.
437
438
439==== print
440
441<procedure>(print [EXP1 ...])</procedure>
442
443Outputs the optional arguments {{EXP1 ...}} using {{display}} and
444writes a newline character to the port that is the value of
445{{(current-output-port)}}. Returns {{(void)}}.
446
447
448==== print*
449
450<procedure>(print* [EXP1 ...])</procedure>
451
452Similar to {{print}}, but does not output a terminating newline
453character and performs a {{flush-output}} after writing its arguments.
454
455
456
457
458=== User-defined named characters
459
460==== char-name
461
462<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>
463
464This procedure can be used to inquire about character names or to
465define new ones. With a single argument the behavior is as follows:
466If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
467the character with this name, or {{#f}} if no character is defined
468under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
469name of the character is returned as a symbol, or {{#f}} if the
470character has no associated name.
471
472If the optional argument {{CHAR}} is provided, then
473{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
474the given character. If multiple names designate the same character,
475then the {{write}} will use the character name that was defined last.
476
477<enscript highlight=scheme>
478(char-name 'space)                  ==> #\space
479(char-name #\space)                 ==> space
480(char-name 'bell)                   ==> #f
481(char-name (integer->char 7))       ==> #f
482(char-name 'bell (integer->char 7))
483(char-name 'bell)                   ==> #\bell
484(char->integer (char-name 'bell))   ==> 7
485</enscript>
486
487
488=== Lists
489
490==== foldl
491
492<procedure>(foldl PROCEDURE INIT LIST)</procedure>
493
494Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from the left:
495
496<enscript hightlight=scheme>
497(foldl + 0 '(1 2 3))    ==>    (+ (+ (+ 0 1) 2) 3)
498</enscript>
499
500Note that the order of arguments taken by {{PROCEDURE}} is different
501from the {{SRFI-1}} {{fold}} procedure, but matches the more natural
502order used in Haskell and Objective Caml.
503
504
505==== foldr
506
507<procedure>(foldr PROCEDURE INIT LIST)</procedure>
508
509Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from the right:
510
511<enscript hightlight=scheme>
512(foldr + 0 '(1 2 3))    ==>    (+ 1 (+ 2 (+ 3 0)))
513</enscript>
514
515
516=== Vectors
517
518==== vector-copy!
519
520<procedure>(vector-copy! VECTOR1 VECTOR2 [COUNT])</procedure>
521
522Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
523argument {{COUNT}} is given, it specifies the maximal number of
524elements to be copied. If not given, the minimum of the lengths of the
525argument vectors is copied.
526
527Exceptions: {{(exn bounds)}}
528
529
530==== vector-resize
531
532<procedure>(vector-resize VECTOR N [INIT])</procedure>
533
534Creates and returns a new vector with the contents of {{VECTOR}} and length
535{{N}}. If {{N}} is greater than the original length of {{VECTOR}}, then all
536additional items are initialized to {{INIT}}. If {{INIT}} is not specified, the
537contents are initialized to some unspecified value.
538
539
540==== subvector
541
542<procedure>(subvector VECTOR FROM [TO])</procedure>
543
544Returns a new vector with elements taken from {{VECTOR}} in the
545given range. {{TO}} defaults to {{(vector-length VECTOR)}}.
546
547{{subvector}} was introduced in CHICKEN 4.7.3.
548
549
550=== The unspecified value
551
552==== void
553
554<procedure>(void ARGUMENT ...)</procedure>
555
556Ignores {{ARGUMENT ...}} and returns an unspecified value.
557
558
559
560=== Continuations
561
562==== call/cc
563
564<procedure>(call/cc PROCEDURE)</procedure>
565
566An alias for {{call-with-current-continuation}}.
567
568
569=== Setters
570
571SRFI-17 is fully implemented. For more information see:
572[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
573
574==== setter
575
576<procedure>(setter PROCEDURE)</procedure>
577
578Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
579{{PROCEDURE}} has no associated setter-procedure.
580
581Note that {{(set! (setter PROC) ...)}} for a procedure that has no associated
582setter procedure yet is a very slow operation (the old procedure is replaced by
583a modified copy, which involves a garbage collection).
584
585
586==== getter-with-setter
587
588<procedure>(getter-with-setter GETTER SETTER)</procedure>
589
590Returns a copy of the procedure {{GETTER}} with the associated setter procedure
591{{SETTER}}. Contrary to the SRFI specification, the setter of the returned
592procedure may be changed.
593
594
595
596----
597Previous: [[Exceptions]] Next: [[Unit eval]]
Note: See TracBrowser for help on using the repository browser.