source: project/wiki/eggref/4/string-utils @ 35186

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

rel 1.6.0

File size: 8.9 KB
Line 
1[[tags: egg]]
2
3== string-utils
4
5[[toc:]]
6
7
8== Documentation
9
10=== Memoized String
11
12==== Usage
13
14<enscript language=scheme>
15(require-extension memoized-string)
16</enscript>
17
18==== make-string+
19
20<procedure>(make-string+ COUNT [FILL]) -> string</procedure>
21
22A ''tabling'' {{make-string}}.
23
24{{FILL}} is any valid {{char}}, including codepoints outside of the ASCII
25range. As such UTF-8 strings can be memoized.
26
27==== string+
28
29<procedure>(string+ [CHAR...]) -> string</procedure>
30
31A ''tabling'' {{string}}.
32
33{{CHAR}} is any valid {{char}}, including codepoints outside of the ASCII
34range. As such UTF-8 strings can be memoized.
35
36==== global-string
37
38<procedure>(global-string STR) -> string</procedure>
39
40Share common string space.
41
42==== make-string* (DEPRECATED)
43
44<procedure>(make-string* COUNT [FILL]) -> string</procedure>
45
46=== String Hexadecimal
47
48==== Usage
49
50<enscript language=scheme>
51(require-extension string-hexadecimal)
52</enscript>
53
54==== string->hex
55
56<procedure>(string->hex STRING [START [END]]) -> string</procedure>
57
58Returns a hexadecimal represenation of {{STRING}}. {{START}} and {{END}} are
59substring limits.
60
61{{STRING}} is treated as a string of bytes, a byte-vector.
62
63==== hex->string
64
65<procedure>(hex->string STRING [START [END]]) -> string</procedure>
66
67Returns the binary representation of a hexadecimal{{STRING}}. {{START}} and
68{{END}} are substring limits.
69
70=== Unicode Utilities
71
72The name of this extension is misleading. Only UTF-8 is currently supported.
73
74For a better treatment of UTF-8 see the [[utf-8]] extension.
75
76==== Usage
77
78<enscript language=scheme>
79(require-extension unicode-utils)
80</enscript>
81
82==== ascii-codepoint?
83
84<procedure>(ascii-codepoint? CHAR) -> boolean</procedure>
85
86==== unicode-char->string
87
88<procedure>(unicode-char->string CHAR) -> string</procedure>
89
90Returns a string formed from Unicode codepoint {{CHAR}}.
91
92''Note'' that the {{(string-length)}} (except under [[utf-8]]) may not be equal
93to {{1}}.
94
95Generates an error should the codepoint be out-of-range.
96
97==== unicode-string
98
99<procedure>(unicode-string [CHAR...]) -> string</procedure>
100
101Returns a string formed from Unicode codepoints {{CHAR...}}
102
103''Note'' that the {{(string-length)}} (except under [[utf-8]]) may not be equal
104to the length of {{CHAR...}}.
105
106Generates an error should the codepoint be out-of-range.
107
108==== *unicode-string
109
110<procedure>(*unicode-string CHARS) -> string</procedure>
111
112Returns a string formed from Unicode codepoints {{CHARS}}, a {{(list-of
113char)}}.
114
115==== unicode-make-string
116
117<procedure>(unicode-make-string COUNT [FILL]) -> string</procedure>
118
119Returns a string formed from {{COUNT}} occurrences of the Unicode codepoint
120{{FILL}}. The {{FILL}} default is {{#\space}}.
121
122''Note'' that the {{(string-length)}} (except under [[utf-8]]) may not be equal
123to {{COUNT}}.
124
125Generates an error should the codepoint be out-of-range.
126
127==== unicode-surrogate?
128
129<procedure>(unicode-surrogate? NUM) -> boolean</procedure>
130
131==== unicode-surrogates->codepoint
132
133<procedure>(unicode-surrogates->codepoint HIGH LOW) -> (or boolean fixnum)</procedure>
134
135Returns the codepoint for the valid surrogate pair {{HIGH}} and {{LOW}}.
136Otherwise returns {{#f}}.
137
138=== String Extensions
139
140Some multi-string replacements.
141
142== Usage
143
144<enscript language=scheme>
145(require-extension string-utils-extensions)
146</enscript>
147
148==== string-copy-over!
149
150<procedure>(string-copy-over! FROM TO [START [END]]) -> string</procedure>
151
152Copies a substring of {{FROM}}, determined by {{START}} & {{END}}. Returns the
153modified {{TO}}.
154
155: {{FROM}} ; {{string}} ;
156: {{TO}} ; {{string}} ;
157: {{START}} ; {{fixnum}} ; default {{0}}
158: {{END}} ; {{fixnum}} ; default {{string-length}}
159
160==== string-count*
161
162<procedure>(string-count* PRED? [STR ...]) -> fixnum</procedure>
163
164: {{STR}} ; {{string}} ;
165: {{PRED?}} ; {{(#!rest char --> boolean)}} ;
166
167==== string-any*
168
169<procedure>(string-any* PRED? [STR ...]) -> (or boolean char)</procedure>
170
171: {{STR}} ; {{string}} ;
172: {{PRED?}} ; {{(#!rest char --> boolean)}} ;
173
174==== string-every*
175
176<procedure>(string-every* PRED? [STR ...]) -> (or boolean char)</procedure>
177
178: {{STR}} ; {{string}} ;
179: {{PRED?}} ; {{(#!rest char --> boolean)}} ;
180
181=== String Utilities
182
183Reexports all of the above.
184
185== Usage
186
187<enscript language=scheme>
188(require-extension string-utils)
189</enscript>
190
191=== Bytes to Hexadecimal
192
193A common bytevector-like object to hexadecimal string facility.
194
195No error checking is performed!
196
197==== Usage
198
199<enscript language=scheme>
200(require-extension to-hex)
201</enscript>
202
203==== str_to_hex
204
205<procedure>(str_to_hex OUT IN OFF LEN)</procedure>
206
207Writes the ASCII hexadecimal representation of {{IN}} to {{OUT}}.
208
209{{IN}} is a {{nonnull-string}}.
210
211{{OFF}} is the byte offset.
212
213{{LEN}} is the length of the bytes at {{OFF}}.
214
215{{OUT}} is a {{string}} of length >= {{(+ LEN 2)}}.
216
217==== blob_to_hex
218
219<procedure>(blob_to_hex OUT IN OFF LEN)</procedure>
220
221Like {{str_to_hex}} except {{IN}} is a {{nonnull-blob}}.
222
223==== u8vec_to_hex
224
225<procedure>(u8vec_to_hex OUT IN OFF LEN)</procedure>
226
227Like {{str_to_hex}} except {{IN}} is a {{nonnull-u8vector}}.
228
229==== s8vec_to_hex
230
231<procedure>(s8vec_to_hex OUT IN OFF LEN)</procedure>
232
233Like {{str_to_hex}} except {{IN}} is a {{nonnull-s8vector}}.
234
235==== mem_to_hex
236
237<procedure>(mem_to_hex OUT IN OFF LEN)</procedure>
238
239Like {{str_to_hex}} except {{IN}} is a {{nonnull-c-pointer}}.
240
241==== hex_to_str
242
243<procedure>(hex_to_str OUT IN OFF LEN)</procedure>
244
245Reads the ASCII hexadecimal representation of {{IN}} to {{OUT}}.
246
247{{IN}} is a {{nonnull-string}}.
248
249{{OFF}} is the byte offset.
250
251{{LEN}} is the length of the bytes at {{OFF}}.
252
253{{OUT}} is a {{string}} of length >= {{(/ LEN 2)}}.
254
255==== hex_to_str
256
257<procedure>(hex_to_blob OUT IN OFF LEN)</procedure>
258
259Like {{hex_to_str}} except {{OUT}} is a {{blob}} of size >= {{(/ LEN 2)}}.
260
261=== String Interpolation
262
263==== Usage
264
265<enscript language=scheme>
266(require-extension string-interpolation)
267</enscript>
268
269<enscript language=scheme>
270(require-extension utf8-string-interpolation)
271</enscript>
272
273==== string-interpolate
274
275<procedure>(string-interpolate STR [eval-tag: EVAL-TAG] [eval-env: EVAL-ENV]) -> string</procedure>
276
277Performs substitution of embedded Scheme expressions, evaluated in the
278{{EVAL-ENV}}, prefixed with {{EVAL-TAG}} and optionally enclosed in curly
279brackets. Two consecutive {{EVAL-TAG}}s are translated to a single
280{{EVAL-TAG}}.
281
282Similar to the {{#<#}} multi-line string.
283
284{{STR}} is a {{string}}.
285
286{{EVAL-TAG}} is a {{character}}, default {{#\#}}.
287
288{{EVAL-ENV}} is an {{environment}}, default {{(interaction-environment)}}.
289
290==== Usage
291
292<enscript language=scheme>
293(require-extension string-interpolation-syntax)
294</enscript>
295
296==== set-sharp-string-interpolation-syntax
297
298<procedure>(set-sharp-string-interpolation-syntax PROC)</procedure>
299
300Extends the read-syntax with #"..." where the {{"..."}} is evaluated using
301{{(PROC "...")}}. When {{PROC}} is {{#f}} the read-syntax is cleared. When
302{{PROC}} is {{#t}} then {{PROC}} is {{identity}}.
303
304<enscript language=scheme>
305(use string-interpolation-syntax utf8-string-interpolation)
306
307(set-sharp-string-interpolation-syntax string-interpolate)
308;#"foo #(+ 1 2)bar #{(and 1 2)} baz"
309;=> "foo 3bar 2 baz"
310</enscript>
311
312
313== Requirements
314
315[[check-errors]]
316[[miscmacros]]
317[[utf8]]
318
319[[setup-helper]]
320[[test]]
321
322
323== Author
324
325[[/users/kon-lovett|Kon Lovett]]
326
327
328== Version history
329
330; 1.6.0 : Add {{string-utils-extensions}}.
331; 1.5.6 : Add types.
332; 1.5.5 :
333; 1.5.4 :
334; 1.5.3 : {{memorize-string}} -> {{global-string}}.
335; 1.5.2 : Fix {{string+}} & {{memorize-string}}.
336; 1.5.1 : Fix {{string+}} unicode support.
337; 1.5.0 : Deprecate {{make-string*}} for {{make-string+}}, add {{memorize-string}} & {{string+}}.
338; 1.4.0 : Add string-interpolation modules.
339; 1.3.1 : Fix {{hex_to_str}}, {{hex_to_blob}}.
340; 1.3.0 : Add {{hex->string}}, {{hex_to_str}}, {{hex_to_blob}}.
341; 1.2.5 : Remove [[lookup-table]].
342; 1.2.2 : Unicode string construction a little faster. Removed {{blob->hex}}.
343; 1.2.1 : Added {{blob->hex}}.
344; 1.2.0 : Added "generic" bytes to hexadecimal string.
345; 1.1.0 : Split into separate modules. Added some UTF-8 support.
346; 1.0.0 : Hello
347
348
349== License
350
351Copyright (C) 2010-2017 Kon Lovett.  All rights reserved.
352
353Permission is hereby granted, free of charge, to any person obtaining a
354copy of this software and associated documentation files (the Software),
355to deal in the Software without restriction, including without limitation
356the rights to use, copy, modify, merge, publish, distribute, sublicense,
357and/or sell copies of the Software, and to permit persons to whom the
358Software is furnished to do so, subject to the following conditions:
359
360The above copyright notice and this permission notice shall be included
361in all copies or substantial portions of the Software.
362
363THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
364IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
365FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
366THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
367OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
368ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
369OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.