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

Last change on this file was 35152, checked in by Kon Lovett, 19 months ago

remove invalid 4th format DESTINATION

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