source: project/wiki/man/4/Unit extras @ 14097

Last change on this file since 14097 was 14097, checked in by felix winkelmann, 10 years ago

created manual subdirs and imported chicken-4 manual, changed link

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=== Input/Output extensions
101
102==== pretty-print
103
104 [procedure] (pretty-print EXP [PORT])
105 [procedure] (pp EXP [PORT])
106
107Print expression nicely formatted. {{PORT}} defaults to the value
108of {{(current-output-port)}}.
109
110
111==== pretty-print-width
112(Parameter) Specifies the maximal line-width for pretty printing, after which line
113wrap will occur.
114
115==== read-byte
116==== write-byte
117
118 [procedure] (read-byte [PORT])
119 [procedure] (write-byte BYTE [PORT])
120
121Read/write a byte to the port given in {{PORT}}, which default to the values
122of {{(current-input-port)}} and {{(current-output-port)}}, respectively.
123
124==== read-file
125
126 [procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
127
128Returns a list containing all toplevel expressions
129read from the file or port {{FILE-OR-PORT}}. If no argument is given,
130input is read from the port that is the current value of {{(current-input-port)}}.
131After all expressions are read, and if the argument is a port, then the port will
132not be closed. The {{READER}} argument specifies the procedure used to read
133expressions from the given file or port and defaults to {{read}}. The reader
134procedure will be called with a single argument (an input port).
135If {{MAXCOUNT}} is given then only up to {{MAXCOUNT}} expressions will be read in.
136
137
138==== read-line
139==== write-line
140
141 [procedure] (read-line [PORT [LIMIT]])
142 [procedure] (write-line STRING [PORT])
143
144Line-input and -output. {{PORT}} defaults to the value of
145{{(current-input-port)}} and {{(current-output-port)}},
146respectively. If the optional argument {{LIMIT}} is given and
147not {{#f}}, then {{read-line}} reads at most {{LIMIT}}
148characters per line. {{read-line}} returns a string without the terminating newline and {{write-line}} adds a terminating newline  before outputting.
149
150
151==== read-lines
152
153 [procedure] (read-lines [PORT [MAX]])
154
155Read {{MAX}} or fewer lines from {{PORT}}. {{PORT}}
156defaults to the value of {{(current-input-port)}}. {{PORT}} may optionally be
157a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).
158
159
160==== read-string
161==== read-string!
162==== write-string
163
164 [procedure] (read-string [NUM [PORT]])
165 [procedure] (read-string! NUM STRING [PORT [START]])
166 [procedure] (write-string STRING [NUM [PORT]]
167
168Read or write {{NUM}} characters from/to {{PORT}}, which defaults to the
169value of {{(current-input-port)}} or {{(current-output-port)}}, respectively.
170If {{NUM}} is {{#f}} or not given, then all data
171up to the end-of-file is read, or, in the case of {{write-string}} the whole
172string is written. If no more input is available, {{read-string}} returns the
173empty string. {{read-string!}} reads destructively into the given {{STRING}} argument,
174but never more characters that would fit into {{STRING}}. If {{START}} is given, then
175the read characters are stored starting at that position.
176{{read-string!}} returns the actual number of characters read.
177
178
179==== read-token
180
181 [procedure] (read-token PREDICATE [PORT])
182
183Reads characters from {{PORT}} (which defaults to the value of {{(current-input-port)}})
184and calls the procedure {{PREDICATE}} with each character until {{PREDICATE}} returns
185false. Returns a string with the accumulated characters.
186
187---
188Previous: [[Unit files]]
189
190Next: [[Unit regex]]
Note: See TracBrowser for help on using the repository browser.