source: project/wiki/eggref/5/string-utils @ 39546

Last change on this file since 39546 was 39546, checked in by Kon Lovett, 6 months ago

rel 2.4.0

File size: 9.7 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(import memoized-string)
16</enscript>
17
18==== make-string+
19
20<procedure>(make-string+ COUNT [FILL]) -> string</procedure>
21
22An ''interning'' {{make-string}}.
23
24{{FILL}} is any valid {{char}}, including codepoints outside of the ASCII
25range, which produce UTF-8 strings.
26
27==== string+
28
29<procedure>(string+ [CHAR...]) -> string</procedure>
30
31An ''interning'' {{string}}.
32
33{{CHAR}} is any valid {{char}}, including codepoints outside of the ASCII
34range, which produce UTF-8 strings.
35
36==== global-string
37
38<procedure>(global-string STR) -> string</procedure>
39
40Share common string space.
41
42=== String Hexadecimal
43
44==== Usage
45
46<enscript language=scheme>
47(import string-hexadecimal)
48</enscript>
49
50==== string->hex
51
52<procedure>(string->hex STRING [START [END]]) -> string</procedure>
53
54Returns a hexadecimal represenation of {{STRING}}. {{START}} and {{END}} are
55substring limits.
56
57{{STRING}} is treated as a string of bytes, a byte-vector.
58
59==== hex->string
60
61<procedure>(hex->string STRING [START [END]]) -> string</procedure>
62
63Returns the binary representation of a hexadecimal{{STRING}}. {{START}} and
64{{END}} are substring limits.
65
66=== Hexadecimal Procedures
67
68==== Usage
69
70<enscript language=scheme>
71(import to-hex)
72</enscript>
73
74==== str_to_hex
75
76<procedure>(str_to_hex OUT IN OFF LEN)</procedure>
77
78Writes the ASCII hexadecimal representation of {{IN}} to {{OUT}}.
79
80{{IN}} is a {{nonnull-string}}.
81
82{{OFF}} is the byte offset.
83
84{{LEN}} is the length of the bytes at {{OFF}}.
85
86{{OUT}} is a {{string}} of length >= {{(+ LEN 2)}}.
87
88==== blob_to_hex
89
90<procedure>(blob_to_hex OUT IN OFF LEN)</procedure>
91
92Like {{str_to_hex}} except {{IN}} is a {{nonnull-blob}}.
93
94==== u8vec_to_hex
95
96<procedure>(u8vec_to_hex OUT IN OFF LEN)</procedure>
97
98Like {{str_to_hex}} except {{IN}} is a {{nonnull-u8vector}}.
99
100==== s8vec_to_hex
101
102<procedure>(s8vec_to_hex OUT IN OFF LEN)</procedure>
103
104Like {{str_to_hex}} except {{IN}} is a {{nonnull-s8vector}}.
105
106==== mem_to_hex
107
108<procedure>(mem_to_hex OUT IN OFF LEN)</procedure>
109
110Like {{str_to_hex}} except {{IN}} is a {{nonnull-c-pointer}}.
111
112==== hex_to_str
113
114<procedure>(hex_to_str OUT IN OFF LEN)</procedure>
115
116Reads the ASCII hexadecimal representation of {{IN}} to {{OUT}}.
117
118{{IN}} is a {{nonnull-string}}.
119
120{{OFF}} is the byte offset.
121
122{{LEN}} is the length of the bytes at {{OFF}}.
123
124{{OUT}} is a {{string}} of length >= {{(/ LEN 2)}}.
125
126==== hex_to_str
127
128<procedure>(hex_to_blob OUT IN OFF LEN)</procedure>
129
130Like {{hex_to_str}} except {{OUT}} is a {{blob}} of size >= {{(/ LEN 2)}}.
131
132=== Unicode Utilities
133
134The name of this extension is misleading. Only UTF-8 is currently supported.
135
136For a better treatment of UTF-8 see the [[utf-8]] extension.
137
138==== Usage
139
140<enscript language=scheme>
141(import unicode-utils)
142</enscript>
143
144==== ascii-codepoint?
145
146<procedure>(ascii-codepoint? CHAR) -> boolean</procedure>
147
148==== char->unicode-string
149
150<procedure>(char->unicode-string CHAR) -> string</procedure>
151
152Returns a string formed from Unicode codepoint {{CHAR}}.
153
154''Note'' that the {{(string-length)}} (except under [[utf-8]]) may not be equal
155to {{1}}.
156
157Generates an error should the codepoint be out-of-range.
158
159==== unicode-string
160
161<procedure>(unicode-string [CHAR...]) -> string</procedure>
162
163Returns a string formed from Unicode codepoints {{CHAR...}}
164
165''Note'' that the {{(string-length)}} (except under [[utf-8]]) may not be equal
166to the length of {{CHAR...}}.
167
168Generates an error should the codepoint be out-of-range.
169
170==== *unicode-string
171
172<procedure>(*unicode-string CHARS) -> string</procedure>
173
174Returns a string formed from Unicode codepoints {{CHARS}}, a {{(list-of
175char)}}.
176
177==== unicode-make-string
178
179<procedure>(unicode-make-string COUNT [FILL]) -> string</procedure>
180
181Returns a string formed from {{COUNT}} occurrences of the Unicode codepoint
182{{FILL}}. The {{FILL}} default is {{#\space}}.
183
184''Note'' that the {{(string-length)}} (except under [[utf-8]]) may not be equal
185to {{COUNT}}.
186
187Generates an error should the codepoint be out-of-range.
188
189==== unicode-surrogate?
190
191<procedure>(unicode-surrogate? NUM) -> boolean</procedure>
192
193==== unicode-surrogates->codepoint
194
195<procedure>(unicode-surrogates->codepoint HIGH LOW) -> (or boolean fixnum)</procedure>
196
197Returns the codepoint for the valid surrogate pair {{HIGH}} and {{LOW}}.
198Otherwise returns {{#f}}.
199
200=== String Utilities
201
202==== Usage
203
204<enscript language=scheme>
205(import string-utils)
206</enscript>
207
208==== string-trim-whitespace-both
209
210<procedure>(string-trim-whitespace-both S) -> string</procedure>
211
212Returns the {{string}} {{S}} with whitespace trimmed.
213
214==== list-as-string
215
216<procedure>(list-as-string LS) -> string</procedure>
217
218Returns the {{list}} {{LS}} written to a {{string}}.
219
220==== number->padded-string
221
222<procedure>(number->padded-string N WIDTH [PADCHAR [BASE]]) -> string</procedure>
223
224; N : {{number}} ; source
225; WIDTH : {{fixnum}} ; field width
226; PADCHAR : {{char}} ; padding character
227; BASE : {{fixnum}} ; number conversion base
228
229==== string-fixed-length
230
231<procedure>(string-fixed-length S N [pad-char: #\space] [trailing: "..."]) -> string</procedure>
232
233Returns the {{string}} {{S}} with the {{string-length}} fixed to {{N}}.
234
235A shorter string is padded. A longer string is truncated, & suffixed with the
236{{trailing}}.
237
238==== string-longest-common-prefix
239
240<procedure>(string-longest-common-prefix STRINGS) -> string</procedure>
241
242Returns the longest comment prefix of {{STRINGS}}.
243
244; STRINGS : {{(list-of string)}}
245
246==== string-longest-common-suffix
247
248<procedure>(string-longest-common-suffix STRINGS) -> string</procedure>
249
250Returns the longest comment suffix of {{STRINGS}}.
251
252; STRINGS : {{(list-of string)}}
253
254==== string-longest-prefix
255
256<procedure>(string-longest-prefix CANDIDATE OTHERS) -> (or boolean string)</procedure>
257
258Returns the member with the longest comment prefix of {{CANDIDATE}} from
259{{OTHERS}}, or {{#f}}.
260
261; CANDIDATE : {{string}}
262; OTHERS : {{(list-of string)}}
263
264==== string-longest-suffix
265
266<procedure>(string-longest-suffix CANDIDATE OTHERS) -> (or boolean string)</procedure>
267
268Returns the member with the longest comment suffix of {{CANDIDATE}} from
269{{OTHERS}}, or {{#f}}.
270
271; CANDIDATE : {{string}}
272; OTHERS : {{(list-of string)}}
273
274=== String Interpolation
275
276Extends the read-syntax with #"..." where tagged scheme expressions in the
277string are evaluated at runtime.
278
279Similar to the {{#<#}} multi-line string.
280
281See [[http://wiki.call-cc.org/man/5/Extensions%20to%20the%20standard#multiline-string-constant-with-embedded-expressions|Multiline String Constant with Embedded Expressions]].
282
283<enscript language=scheme>
284(import utf8-string-interpolation)
285
286#"@ #(+ 1 2)## (#'and #1 #2) = #(and 1 2) trailing #"
287;=> "@ 3# (and 1 2) = 2 trailing #"
288</enscript>
289
290'''Note''' Support for the #{<sexpr>} subform is deprecated; use the #<sexpr> form.
291
292==== Usage
293
294<enscript language=scheme>
295(import string-interpolation)
296</enscript>
297
298<enscript>
299csc -extend string-interpolation ...
300</enscript>
301
302<enscript>
303csi -require-extension string-interpolation ...
304</enscript>
305
306Activates string-interpolation {{#"..."}} syntax.
307
308Substitute {{utf8-string-interpolation}} when UTF8.
309
310==== Usage
311
312<enscript language=scheme>
313(import string-interpolation-syntax)
314</enscript>
315
316==== set-sharp-string-interpolation-syntax
317
318<procedure>(set-sharp-string-interpolation-syntax PROC)</procedure>
319
320Extends the read-syntax with #"..." where the {{"..."}} is evaluated using
321{{(PROC "...")}}.
322
323; {{PROC}} : {{#f}} ; read-syntax is cleared.
324; {{PROC}} : {{#t}} ; {{PROC}} is {{identity}}.
325; {{PROC}} : {{procedure}} ; interpolation function.
326
327==== Usage
328
329<enscript language=scheme>
330(import string-interpolator) ;or (import utf8-string-interpolator)
331</enscript>
332
333==== string-interpolate
334
335<procedure>(string-interpolate STR [eval-tag: EVAL-TAG]) -> list</procedure>
336
337Performs substitution of embedded Scheme expressions, prefixed with
338{{EVAL-TAG}}. Two consecutive {{EVAL-TAG}}s are translated to a single
339{{EVAL-TAG}}. A trailing {{EVAL-TAG}} is taken literally.
340
341; {{STR}} : {{string}}.
342; {{EVAL-TAG}} : {{character}}, default {{#\#}}.
343
344
345== Requirements
346
347[[check-errors]]
348[[miscmacros]]
349[[srfi-1]]
350[[srfi-13]]
351[[srfi-69]]
352[[utf8]]
353
354[[test]]
355
356
357== Author
358
359[[/users/kon-lovett|Kon Lovett]]
360
361
362== Version history
363
364; 2.4.0 : Add {{string-longest-common-prefix/suffix}}, {{string-longest-prefix/suffix}}, {{number->padded-string}}, {{list-as-string}}, {{string-trim-whitespace-both}}.
365; 2.3.2 : Deprecate {{unicode-char->string}}, fixes for {{memoized-string}} & {{string-utils}} modules, {{ascii-codepoint?}} & {{unicode-surrogate?}} are not predicates.
366; 2.3.1 : Minor optimization.
367; 2.3.0 : Deprecate #{...} support. Add {{string-interpolator}} modules.
368; 2.2.0 : Fix {{string-interpolation}}.
369; 2.1.0 : Add {{utf8-string-interpolation}}.
370; 2.0.0 : C5 release.
371
372
373== License
374
375Copyright (C) 2010-2021 Kon Lovett.  All rights reserved.
376
377Permission is hereby granted, free of charge, to any person obtaining a
378copy of this software and associated documentation files (the Software),
379to deal in the Software without restriction, including without limitation
380the rights to use, copy, modify, merge, publish, distribute, sublicense,
381and/or sell copies of the Software, and to permit persons to whom the
382Software is furnished to do so, subject to the following conditions:
383
384The above copyright notice and this permission notice shall be included
385in all copies or substantial portions of the Software.
386
387THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
388IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
389FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
390THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
391OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
392ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
393OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.