source: project/chicken/trunk/manual/Unit extras @ 15896

Last change on this file since 15896 was 15896, checked in by Ivan Raikov, 10 years ago

merged manual from wiki

File size: 5.8 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit extras
5
6This unit contains a collection of useful utility definitions. The unit is
7used by default, unless the program is compiled with the {{-explicit-use}}
8option.
9
10
11
12=== Random numbers
13
14
15==== random-seed
16
17 [procedure] (random-seed [SEED])
18
19Seeds the random number generator with {{SEED}} (an {{integer}}) or
20{{(current-seconds)}} if {{SEED}} is not given.
21
22
23==== randomize
24
25 [procedure] (randomize [SEED])
26
27Set random-number seed. If {{SEED}} (an {{exact integer}}) is not supplied, the
28current time is used. On startup (when Unit {{extras}} is initialized), the
29random number generator is initialized with the current time.
30
31
32==== random
33
34 [procedure] (random N)
35
36Returns a random {{integer}} in {{[0 N-1]}}. {{N}} is an {{integer}}.
37
38On '''Windows''' {{N}} and the random value are {{exact integer}}.
39
40
41
42=== Formatted output
43
44
45==== printf
46==== fprintf
47==== sprintf
48
49 [procedure] (fprintf PORT FORMATSTRING [ARG...])
50 [procedure] (printf FORMATSTRING [ARG...])
51 [procedure] (sprintf FORMATSTRING [ARG...])
52
53Simple formatted output to a given port ({{fprintf}}), the
54value of {{(current-output-port)}} ({{printf}}), or a string
55({{sprintf}}).  The {{FORMATSTRING}} can contain any sequence
56of characters.  There must be at least as many {{ARG}} arguments given as there are format directives that require an argument in {{FORMATSTRING}}.  Extra {{ARG}} arguments are ignored.  The character `~' prefixes special formatting directives:
57
58<table>
59<tr><td>~%</td><td>
60write newline character
61</td></tr><tr><td> ~N</td><td>
62the same as {{~%}}
63</td></tr><tr><td> ~S</td><td>
64write the next argument
65</td></tr><tr><td> ~A</td><td>
66display the next argument
67</td></tr><tr><td> ~\n</td><td>
68skip all whitespace in the format-string until the next non-whitespace character
69</td></tr><tr><td> ~B</td><td>
70write the next argument as a binary number
71</td></tr><tr><td> ~O</td><td>
72write the next argument as an octal number
73</td></tr><tr><td> ~X</td><td>
74write the next argument as a hexadecimal number
75</td></tr><tr><td> ~C</td><td>
76write the next argument as a character
77</td></tr><tr><td> ~~</td><td>
78display `~'
79</td></tr><tr><td> ~!</td><td>
80flush all pending output
81</td></tr><tr><td> ~?</td><td>
82invoke formatted output routine recursively with the next two arguments as format-string and list of parameters
83</td></tr></table>
84
85
86==== format
87
88 [procedure] (format [DESTINATION] FORMATSTRING [ARG...])
89
90The parameters {{FORMATSTRING}} and {{ARG...}} are as for {{printf}}.
91
92The optional {{DESTINATION}}, when supplied, performs:
93
94; {{#f}} : {{sprintf}}
95; {{#t}} : {{printf}}
96; {{output-port}} : {{fprintf}}
97; : {{sprintf}}
98
99
100=== Pretty-printing
101
102
103==== pretty-print
104
105 [procedure] (pretty-print EXP [PORT])
106 [procedure] (pp EXP [PORT])
107
108Print expression nicely formatted. {{PORT}} defaults to the value
109of {{(current-output-port)}}.
110
111
112==== pretty-print-width
113(Parameter) Specifies the maximal line-width for pretty printing, after which line
114wrap will occur.
115
116
117=== Input/Output extensions
118
119==== read-byte
120==== write-byte
121
122 [procedure] (read-byte [PORT])
123 [procedure] (write-byte BYTE [PORT])
124
125Read/write a byte to the port given in {{PORT}}, which default to the values
126of {{(current-input-port)}} and {{(current-output-port)}}, respectively.
127
128==== read-file
129
130 [procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
131
132Returns a list containing all toplevel expressions
133read from the file or port {{FILE-OR-PORT}}. If no argument is given,
134input is read from the port that is the current value of {{(current-input-port)}}.
135After all expressions are read, and if the argument is a port, then the port will
136not be closed. The {{READER}} argument specifies the procedure used to read
137expressions from the given file or port and defaults to {{read}}. The reader
138procedure will be called with a single argument (an input port).
139If {{MAXCOUNT}} is given then only up to {{MAXCOUNT}} expressions will be read in.
140
141
142==== read-line
143==== write-line
144
145 [procedure] (read-line [PORT [LIMIT]])
146 [procedure] (write-line STRING [PORT])
147
148Line-input and -output. {{PORT}} defaults to the value of
149{{(current-input-port)}} and {{(current-output-port)}},
150respectively. If the optional argument {{LIMIT}} is given and
151not {{#f}}, then {{read-line}} reads at most {{LIMIT}}
152characters per line. {{read-line}} returns a string without the terminating newline and {{write-line}} adds a terminating newline  before outputting.
153
154
155==== read-lines
156
157 [procedure] (read-lines [PORT [MAX]])
158
159Read {{MAX}} or fewer lines from {{PORT}}. {{PORT}}
160defaults to the value of {{(current-input-port)}}. {{PORT}} may optionally be
161a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).
162
163
164==== read-string
165==== read-string!
166==== write-string
167
168 [procedure] (read-string [NUM [PORT]])
169 [procedure] (read-string! NUM STRING [PORT [START]])
170 [procedure] (write-string STRING [NUM [PORT]]
171
172Read or write {{NUM}} characters from/to {{PORT}}, which defaults to the
173value of {{(current-input-port)}} or {{(current-output-port)}}, respectively.
174If {{NUM}} is {{#f}} or not given, then all data
175up to the end-of-file is read, or, in the case of {{write-string}} the whole
176string is written. If no more input is available, {{read-string}} returns the
177empty string. {{read-string!}} reads destructively into the given {{STRING}} argument,
178but never more characters that would fit into {{STRING}}. If {{START}} is given, then
179the read characters are stored starting at that position.
180{{read-string!}} returns the actual number of characters read.
181
182
183==== read-token
184
185 [procedure] (read-token PREDICATE [PORT])
186
187Reads characters from {{PORT}} (which defaults to the value of {{(current-input-port)}})
188and calls the procedure {{PREDICATE}} with each character until {{PREDICATE}} returns
189false. Returns a string with the accumulated characters.
190
191---
192Previous: [[Unit files]]
193
194Next: [[Unit regex]]
Note: See TracBrowser for help on using the repository browser.