Debian Codegraph @

doc/modsrfi.texi

raw
1 @node Library modules - SRFIs, Library modules - Utilities, Library modules - R7RS standard libraries, Top
2 @chapter Library modules - SRFIs
3 @c NODE ライブラリモジュール - SRFI
4
5 @c EN
6 This chapter lists modules that provides SRFI functionalities.
7 Note that some of SRFI features are built in Gauche core and
8 not listed here. The SRFIs that have been adopted to R7RS-large
9 are described in @ref{Library modules - R7RS standard libraries}.
10
11 @xref{Standard conformance}, for entire list
12 of supported SRFIs.
13
14 (Even if a srfi is not listed here, you can still say
15 @code{(use srfi.N)} or @code{(import (srfi N))}, as far as
16 srfi N is supported by Gauche.)
17 @c JP
18 この章ではSRFIの機能を提供するモジュールをリストします。
19 一部のSRFIはGaucheのコアに組み込まれており、
20 この章には挙げられていないことに注意して下さい。
21 また、R7RS-largeに取り入れられたsrfiは@ref{Library modules - R7RS standard libraries}で解説しています。
22
23 サポートされている全てのSRFIのリストは@ref{Standard conformance}にあります。
24
25 (ここに挙げられていないSRFIでも、サポートされているものについては
26 @code{(use srfi.N)}や@code{(import (srfi N))}と書くことができます。)
27 @c COMMON
28
29 @c EN
30 Note that we use a hyphen to refer to a SRFI as a specification
31 (e.g. SRFI-13) but use a hierarchical name for the module
32 (e.g. @code{srfi.13} as a Gauche's module, or @code{(srfi 13)} as
33 a R7RS library).
34 @c JP
35 ここで、仕様としてのSRFIを指す場合はハイフンを使い(例: SRFI-13)、
36 モジュール名としては階層的な名前を使う(例: Gaucheモジュールとしては@code{srfi.13}、
37 R7RSライブラリとしては@code{(srfi 13)})ということに注意してください。
38 @c COMMON
39
40
41 @c ----------------------------------------------------------------------
42 @menu
43 * Testing availability of SRFIs::
44 * SRFIs that have become R7RS-large::
45 * Homogeneous vectors:: srfi.4
46 * A compatible let form with signatures and rest arguments:: srfi.5
47 * Feature-based program configuration language:: srfi.7
48 * String library:: srfi.13
49 * Time data types and procedures:: srfi.19
50 * Sources of random bits:: srfi.27
51 * Localization:: srfi.29
52 * A program argument processor:: srfi.37
53 * Eager comprehensions:: srfi.42
54 * Vector library (Legacy):: srfi.43
55 * Requiring extensions:: srfi.55
56 * Integers as bits:: srfi.60
57 * A Scheme API for test suites:: srfi.64
58 * Octet vectors:: srfi.66
59 * Basic hash tables:: srfi.69
60 * Octet-addressed binary blocks:: srfi.74
61 * Lightweight testing:: srfi.78
62 * Accessing environment variables:: srfi.98
63 * Purely functional random-access pairs and lists:: srfi.101
64 * Basic socket interface:: srfi.106
65 * Portable runtime environment inquiry:: srfi.112
66 * Comparators:: srfi.114
67 * Simple adjustable-size strings:: srfi.118
68 * Timer APIs:: srfi.120
69 * Titlecase procedures:: srfi.129
70 * Cursor-based string library:: srfi.130
71 * String library (reduced):: srfi.152
72 * First-class dynamic extents:: srfi.154
73 * Homogeneous numeric vector libraries:: srfi.160
74 * Comparator sublibrary:: srfi.162
75 * POSIX API:: srfi.170
76 * Two safer subsets of R7RS:: srfi.172
77 * Hooks (srfi):: srfi.173
78 * POSIX timespecs:: srfi.174
79 * ASCII character library:: srfi.175
80 * Bitvector library:: srfi.178
81 * JSON:: srfi.180
82 * Custom ports:: srfi.181
83 * Linear adjustable-length strings:: srfi.185
84 * Maybe and Either optional container types:: srfi.189
85 * Coroutine generators:: srfi.190
86 * Port positioning:: srfi.192
87 * Command line:: srfi.193
88 * Random data generators (SRFI):: srfi.194
89 * Range objects:: srfi.196
90 * Pipeline operators:: srfi.197
91 * String-notated bytevectors:: srfi.207
92 * Enums and enum sets:: srfi.209
93 * Procedures and syntax for multiple values:: srfi.210
94 * Central log exchange:: srfi.215
95 * SICP prerequisites:: srfi.216
96 * Integer sets:: srfi.217
97 * Define higher-order lambda:: srfi.219
98 * Generator/accumulator sub-library:: srfi.221
99 * Compound objects:: srfi.222
100 * Control features:: srfi.226
101 * Optional arguments:: srfi.227
102 * Composing comparators:: srfi.228
103 * Tagged procedures:: srfi.229
104 * Atomic operations:: srfi.230
105 * Flexible curried procedures:: srfi.232
106 * Topological sorting:: srfi.234
107 * Combinators (SRFI):: srfi.235
108 * Codesets:: srfi.238
109 * Destructuring lists:: srfi.239
110 * Syntactic monads:: srfi.247
111 * Property testing:: srfi.252
112 @end menu
113
114 @node Testing availability of SRFIs, SRFIs that have become R7RS-large, Library modules - SRFIs, Library modules - SRFIs
115 @section Testing availability of SRFIs
116 @c NODE SRFIが使えるかどうかテストする
117
118 @c EN
119 To test availability of a SRFI with @code{cond-expand}
120 (@pxref{Feature conditional}), you can use @code{(library library-name)}
121 feature requirement. You can use both Gauche-style and R7RS-style
122 library name notation.
123 @c JP
124 特定のSRFIが使えるかどうかを@code{cond-expand}で検査する場合は、機能要請式
125 @code{(library @code{library-name})}が使えます (@ref{Feature conditional}参照)。
126 @var{library-name}にはGauche方式のモジュール名もR7RS方式のライブラリ名も使えます。
127 @c COMMON
128
129 @example
130 ;; Use 'library' feature requirement with Gauche module name
131 (cond-expand
132 [(library srfi.13) (use srfi.13) ...]
133 [else ...])
134
135 ;; Use 'library' feature requirement with R7RS library name
136 (cond-expand
137 [(library (srfi 13)) (import (srfi 13)) ...]
138 [else ...])
139 @end example
140
141 @c EN
142 Alternatively you can use a SRFI name as a feature identifier.
143 @emph{This use is deprecated}. This is an old style used before R7RS.
144 With this style, if the feature is fulfilled, the necessary libraries
145 are implicitly imported, so you don't need to have @code{use} or
146 @code{import} forms (but that means you can't control the imports
147 with @code{only}, @code{rename}, @code{prefix} etc.)
148 @c JP
149 他に、SRFI名を直接機能識別子として使うこともできます。
150 @emph{ただし、この機能は非推奨です}。これはR7RS以前の方式です。
151 この指定を使った場合、機能条件が満たされたならば、必要なモジュールは自動的にインポート
152 されているので、@code{use}や@code{import}でインポートする必要はありません。
153 ただそれは、@code{only}、@code{rename}、@code{prefix}節などでインポートする
154 識別子を制御できないということでもあります。
155 @c COMMON
156
157 @example
158 ;; DEPRECATED. Use 'srfi-N' feature identifier.
159 ;; If the feature is fulfilled, you can assume the module is already 'use'd.
160 (cond-expand
161 [srfi-13 ...]
162 [else ...])
163 @end example
164
165 @c EN
166 If @code{srfi-N} is used as a feature identifier, a warning is
167 issued when an environment variable @code{GAUCHE_WARN_SRFI_FEATURE_ID} is
168 set. In future this warning will be the default. We urge the users
169 to update their code to use @code{(library srfi.N)} form.
170 @c JP
171 @code{srfi-N}が機能識別子として使われた場合、
172 環境変数@code{GAUCHE_WARN_SRFI_FEATURE_ID}がセットされていれば
173 警告が表示されます。将来はデフォルトで警告するようになります。
174 @code{srfi-N}機能識別子を使っているユーザは、なるべく早く
175 @code{(library srfi.N)}へと書き換えるようにしてください。
176 @c COMMON
177
178
179 @node SRFIs that have become R7RS-large, Homogeneous vectors, Testing availability of SRFIs, Library modules - SRFIs
180 @section SRFIs that have become R7RS-large
181 @c NODE R7RS-largeになったSRFI
182
183 @c EN
184 Here's a list of SRFIs that have become a part of R7RS-large,
185 ordered by SRFI numbers.
186 @c JP
187 以下に、R7RS-largeに取り入れられたSRFIのリストを番号順に示します。
188 @c COMMON
189
190 @table @asis
191 @item SRFI-1 List library
192 @code{scheme.list} (@pxref{R7RS lists}).
193 @item SRFI-14 Character-set library
194 @code{scheme.char-set} (@pxref{R7RS character sets}).
195 @item SRFI-41 Streams
196 @code{scheme.stream} (@pxref{R7RS stream}).
197 @item SRFI-101 Purely functional random-access pairs and lists
198 @code{scheme.rlist} (@pxref{R7RS random-access lists}).
199 @item SRFI-111 Boxes
200 @code{scheme.box} (@pxref{R7RS boxes}).
201 @item SRFI-113 Sets and bags
202 @code{scheme.set} (@pxref{R7RS sets}).
203 @item SRFI-115 Scheme Regular Expressions
204 @code{scheme.regex} (@pxref{R7RS regular expressions}).
205 @item SRFI-116 Immutable list library
206 @code{scheme.ilist} (@pxref{R7RS immutable lists}).
207 @item SRFI-117 Queues based on lists
208 @code{scheme.list-queue} (@pxref{R7RS list queues}).
209 @item SRFI-121 Generators
210 @code{scheme.generator} (@pxref{R7RS generators}).
211 @item SRFI-124 Ephemerons
212 @code{scheme.ephemeron} (@pxref{R7RS ephemerons}).
213 @item SRFI-125 Intermediate hash tables
214 @code{scheme.hash-table} (@pxref{R7RS hash tables}).
215 @item SRFI-127 Lazy sequences
216 @code{scheme.lseq} (@pxref{R7RS lazy sequences}).
217 @item SRFI-128 Comparators (reduced)
218 @code{scheme.comparator} (@pxref{R7RS comparators}).
219 @item SRFI-132 Sort library
220 @code{scheme.sort} (@pxref{R7RS sort}).
221 @item SRFI-133 Vector library
222 @code{scheme.vector} (@pxref{R7RS vectors}).
223 @item SRFI-134 Immutable deques
224 @code{scheme.ideque} (@pxref{R7RS immutable deques}).
225 @item SRFI-135 Immutable texts
226 @code{scheme.text} (@pxref{R7RS immutable texts}).
227 @item SRFI-141 Integer division
228 @code{scheme.division} (@pxref{R7RS integer division}).
229 @item SRFI-143 Fixnums
230 @code{scheme.fixnum} (@pxref{R7RS fixnum}).
231 @item SRFI-144 Flonums
232 @code{scheme.flonum} (@pxref{R7RS flonum}).
233 @item SRFI-146 Mappings
234 @code{scheme.mapping}, @code{scheme.mapping.hash} (@pxref{R7RS mappings}).
235 @item SRFI-151 Bitwise operations
236 @code{scheme.bitwise} (@pxref{R7RS bitwise operations}).
237 @item SRFI-158 Generators and accumulators
238 @code{scheme.generator} (@pxref{R7RS generators}).
239 @item SRFI-159 Combinator formatting
240 @code{scheme.show} (@pxref{R7RS combinator formatting}).
241 @item SRFI-160 Homogeneous numeric vector libraries
242 @code{scheme.vector.@@} (@pxref{R7RS uniform vectors}).
243 @end table
244
245
246 @c ----------------------------------------------------------------------
247 @node Homogeneous vectors, A compatible let form with signatures and rest arguments, SRFIs that have become R7RS-large, Library modules - SRFIs
248 @section @code{srfi.4} - Homogeneous vectors
249 @c NODE 単一型のベクタ, @code{srfi.4} - 単一型のベクタ
250
251 @deftp {Module} srfi.4
252 @mdindex srfi.4
253 @c EN
254 SRFI-4 is now implemented in @code{gauche.uvector} module
255 @xref{Uniform vectors}.
256 This module simply inherits @code{gauche.uvector} for backward-compatibility.
257 @c JP
258 SRFI-4は、@code{gauche.uvector}モジュールとして実装されています。
259 @ref{Uniform vectors}参照。
260 このモジュールは後方互換性のために単に@code{gauche.uvector}を継承しています。
261 @c COMMON
262 @end deftp
263
264 @c ----------------------------------------------------------------------
265 @node A compatible let form with signatures and rest arguments, Feature-based program configuration language, Homogeneous vectors, Library modules - SRFIs
266 @section @code{srfi.5} - A compatible let form with signatures and rest arguments
267 @c NODE シグネチャとrest引数に互換性のあるlet形式, @code{srfi.5} - シグネチャとrest引数に互換性のあるlet形式
268
269 @deftp {Module} srfi.5
270 @mdindex srfi.5
271 @c EN
272 This module provides SRFI-5's extended @code{let} syntax.
273 @c JP
274 このモジュールは SRFI-5 の拡張 @code{let} 構文を提供します。
275 @c COMMON
276 @end deftp
277
278 @defmac let ((var val) @dots{} [. (rest val @dots{})]) body @dots{}
279 @defmacx let name ((var val) @dots{} [. (rest val @dots{})]) body @dots{}
280 @defmacx let (name (var val) @dots{} [. (rest val @dots{})]) body @dots{}
281 [SRFI-5]
282 @c MOD srfi.5
283 @c EN
284 The @code{let} syntax is extended in two ways.
285 @c JP
286 @code{let} 構文は 2通りの拡張がされています。
287 @c COMMON
288
289 @c EN
290 @itemize @bullet
291 @item
292 The extended @code{let} syntax accepts the @var{name} identifier (for
293 named let syntax) within the list of bindings (as in the third
294 syntax above).
295 @item
296 The extended @code{let} syntax accepts the rest parameter binding
297 which works like the rest parameter in the @code{lambda} syntax.
298 @end itemize
299
300 See SRFI-5 document for rationale of this extension.
301 @c JP
302 @itemize @bullet
303 @item
304 拡張 @code{let} 構文は、@var{name} 束縛リスト中で(名前付き let 構文用の)
305 識別子を許します(上の3つめの構文)。
306 @item
307 拡張 @code{let} 構文は、@code{lambda} 構文の rest パラメータと同様の
308 働きをする rest パラメータ束縛を許します。
309 @end itemize
310
311 この拡張に関する理論的根拠については SRFI-5 のドキュメントを参照してください。
312 @c COMMON
313 @end defmac
314
315 @c ----------------------------------------------------------------------
316 @node Feature-based program configuration language, String library, A compatible let form with signatures and rest arguments, Library modules - SRFIs
317 @section @code{srfi.7} - Feature-based program configuration language
318 @c NODE 機能ベースプログラム設定言語, @code{srfi.7} - 機能ベースプログラム設定言語
319
320 @deftp {Module} srfi.7
321 @mdindex srfi.7
322 @c EN
323 This module provides a program configuration metalanguage
324 (@code{program} form) defined in srfi-7.
325 @c JP
326 このモジュールは、SRFI-7 で定義されている
327 プログラム設定メタ言語(@code{program} フォーム)を提供します。
328
329 @c EN
330 Gauche autoloads @code{srfi.7} module, so you don't need
331 to say @code{(use srfi.7)} explicitly.
332 @c JP
333 Gauche は @code{srfi.7} モジュールを autoload するので、@code{(use srfi.7)} と
334 明示的に書く必要はありません。
335
336 @c EN
337 Note that the @code{program} form isn't necessary to be a
338 Scheme expression. SRFI-7 allows an implementation to preprocess
339 the @code{program} form to produce a Scheme program, then
340 executes it with different means.
341 @c JP
342 @code{program} フォームは Scheme の式である必要がないことに注意してください。
343 SRFI-7 では、この @code{program}フォームを処理して Scheme プログラムを
344 生成してから、それを別の方法で実行するような実装を許しています。
345
346 @c EN
347 Gauche implements @code{program} form as a macro, so it can
348 evaluates the form directly. Nonetheless, it doesn't make sense
349 to mix @code{program} form and other forms in one file,
350 or expecting a return value of @code{program} form.
351 @c JP
352 Gauche @code{program} フォームをマクロとして実装しているので、
353 フォーム自体を直接、評価することができます。とはいえ、@code{program}
354 フォームと他のフォームを一つのファイル中で混在させたり、@code{program}
355 フォームの返り値を期待するのは、よいことではありません。
356
357 @c EN
358 A typical usage of @code{program} form is to prepare a single
359 file which just contains @code{program} form. (It can load
360 other files using @code{files} clause (see below) within the
361 @code{program} form.) To execute such a program file in Gauche,
362 you can just load it.
363 @c JP
364 @code{program}フォームの典型的な使い方は、@code{program} フォームのみを
365 含む単一のファイルを用意することです。(@code{program}フォーム中で
366 @code{files} 節(後述)を用いて他のファイルをロードすることが可能です。)
367 このようなプログラムファイルを Gauche で実行するには、単にそれを
368 ロードするだけです。
369 @c COMMON
370 @end deftp
371
372 @deffn {Configuration Language} program program-clause program-clause2 @dots{}
373 [SRFI-7]
374 @c MOD srfi.7
375 @c EN
376 This is a configuration language to structure a Scheme program,
377 based on availability of the features.
378
379 A Scheme program is constructed from the @code{program} form.
380 Gauche evaluates the constructed Scheme program on-the-fly.
381
382 Each @var{program-clause} needs to be one of the "Program Clauses" below.
383 @c JP
384 これは Scheme プログラムを構成する設定言語で、機能の利用可能性に基づいて
385 います。
386
387 Scheme のプログラムは、この @code{program}フォームから構築されます。
388 Gauche は構築された Scheme のプログラムをそのまま実行します。
389
390 各 @var{program-clause} は以下の "Program Clause" のどれか一つである
391 必要があります。
392 @c COMMON
393 @end deffn
394
395 @deffn {Program Clause} requires feature-id feature-id2 @dots{}
396 [SRFI-7]
397 @c EN
398 The @var{feature-id}'s are the same as SRFI-0's
399 (@pxref{Feature conditional}).
400 It tells that the following code requires these @var{feature-id}'s.
401
402 If a feature-id which is not supported in Gauche is given,
403 an error is signaled.
404 @c JP
405 @var{feature-id} は SRFI-0 のものと同じです
406 (@pxref{Feature conditional})。
407 あとに続くコードが @var{feature-id} を必要とすることを教えます。
408
409 Gauche ではサポートされていない feature-id が与えられた場合には、
410 エラーシグナルが発生します。
411 @c COMMON
412 @end deffn
413
414 @deffn {Program Clause} files filename @dots{}
415 [SRFI-7]
416 @c EN
417 Inserts the content of the @var{filename}s into a program.
418 In Gauche, this clause just causes @var{filename}s to be loaded
419 into the current module.
420 @c JP
421 プログラムに @var{filename}の内容を挿入します。Gauche では
422 単に、現在のモジュール中への @var{filename} のロードをひきおこします。
423 @c COMMON
424 @end deffn
425
426 @deffn {Program Clause} code scheme-expression @dots{}
427 [SRFI-7]
428 @c EN
429 The @var{scheme-expression}s are inserted into a program.
430 @c JP
431 @var{scheme-expression} がプログラムに挿入されます。
432 @c COMMON
433 @end deffn
434
435 @deffn {Program Clause} feature-cond clause clause2 @dots{}
436 [SRFI-7]
437 @c EN
438 @var{Clause} is a following form:
439 @c JP
440 @var{clause} は以下のようなフォームです。
441 @c COMMON
442 @example
443 (@var{requirement} @var{program-clause} @var{program-clause2} @dots{})
444 @end example
445
446 @c EN
447 Where @var{requirement} should be one of the following:
448 @c JP
449 ここでは、@var{requirement} は以下のもののどれかひとつでなければなりません。
450 @c COMMON
451 @itemize @bullet
452 @item
453 @var{feature-id}
454 @item
455 @code{(and @var{requirement} @dots{})}
456 @item
457 @code{(or @var{requirement} @dots{})}
458 @item
459 @code{(not @var{requirement})}
460 @end itemize
461
462 @c EN
463 The @var{requirement} of the last @var{clause} may be @code{else}.
464
465 Gauche checks each @var{requirement} one by one, and if it finds
466 a fulfilled @var{requirement}, inserts the @var{program-clause}s
467 in that @var{clause} into the program.
468 @c JP
469 最後の @var{clause} の @var{requirement} は @code{else} になるでしょう。
470
471 Gauche はそれぞれの @var{requirement} をひとつずつチェックし、
472 満された @var{requirement} が見つかると、その@var{clause}中の
473 @var{program-clause} をプログラムに挿入します。
474 @c COMMON
475 @end deffn
476
477 @c ----------------------------------------------------------------------
478 @node String library, Time data types and procedures, Feature-based program configuration language, Library modules - SRFIs
479 @section @code{srfi.13} - String library
480 @c NODE 文字列ライブラリ, @code{srfi.13} - 文字列ライブラリ
481
482 @deftp {Module} srfi.13
483 @mdindex srfi.13
484 @c EN
485 Defines a large set of string-related procedures.
486 @c JP
487 文字列に関連する手続きの大きなセットを定義しています。
488 @c COMMON
489
490 @c EN
491 It was one of the earliest popular srfis, but some of
492 the procedures were turned out not to align well with recent Scheme
493 developments. @xref{String library (reduced)},
494 and @ref{Cursor-based string library} adapts this srfis to more
495 ``modern'' form. Consider to use them for newer development.
496 @c JP
497 これは広く使われた初期のsrfiのひとつですが、いくつかの手続きは
498 その後のSchemeの発展と相性が良くないということがわかってきました。
499 @ref{String library (reduced)}や@ref{Cursor-based string library}では
500 このsrfiをより「現代的」なものにしようとしています。
501 新規に開発する場合はそれらのsrfiを見てみると良いでしょう。
502 @c COMMON
503
504 @c EN
505 Many procedures in this srfi specifies the position of a character
506 in a string with an integer index. Although it's portable, it is not
507 optimal for multibyte strings. Gauche natively supports string cursors,
508 which is more efficient than integer indexes (@pxref{String cursors}).
509 All SRFI-13 procedures
510 that accepts integer indexes can also accept string cursors.
511 @c JP
512 このsrfiの多くの手続きは、文字列中の文字の位置を整数のインデックスで表します。
513 これはポータブルですが、マルチバイト文字列では効率が悪いです。
514 Gaucheは組み込みでより効率のよい文字列カーソルをサポートしており(@ref{String cursors})、
515 SRFI-13の手続きは全て文字列インデックスを受け取るところに文字列カーソルも
516 渡せるようになっています。
517 @c COMMON
518 @end deftp
519
520 @menu
521 * SRFI-13 General conventions::
522 * SRFI-13 String predicates::
523 * SRFI-13 String constructors::
524 * SRFI-13 String selection::
525 * SRFI-13 String comparison::
526 * SRFI-13 String prefixes & suffixes::
527 * SRFI-13 String searching::
528 * SRFI-13 String case mapping::
529 * SRFI-13 String reverse & append::
530 * SRFI-13 String mapping::
531 * SRFI-13 String rotation::
532 * SRFI-13 Other string operations::
533 * SRFI-13 String filtering::
534 * SRFI-13 Low-level string procedures::
535 @end menu
536
537 @node SRFI-13 General conventions, SRFI-13 String predicates, String library, String library
538 @subsection General conventions
539 @c NODE 一般規約
540
541 @c EN
542 There are a few common factors in string library API, which I don't
543 repeat in each function description
544 @c JP
545 文字列ライブラリのAPIにはいくつか共通するものがありますが、
546 それぞれの関数の説明において繰り返しません。
547 @c COMMON
548
549 @table @emph
550 @c EN
551 @item argument convention
552 @c JP
553 @item 引数の仕様
554 @c EN
555 The following argument names imply their types.
556 @c JP
557 以下の引数名はその型を暗に表しています。
558 @c COMMON
559 @table @asis
560 @item @var{s}, @var{s1}, @var{s2}
561 @c EN
562 Those arguments must be strings.
563 @c JP
564 これらの引数は文字列でなければなりません。
565 @c COMMON
566 @item @var{char/char-set/pred}
567 @c EN
568 This argument can be a character, a character-set object,
569 or a predicate that takes a single character and returns a boolean value.
570 ``Applying @var{char/char-set/pred} to a character'' means,
571 if @var{char/char-set/pred} is a character, it is compared to the given
572 character; if @var{char/char-set/pred} is a character set, it is
573 checked if the character set contains the given character; if
574 @var{char/char-set/pred} is a procedure, it is applied
575 to the given character. ``A character satisfies @var{char/char-set/pred}''
576 means such application to the character yields true value.
577 @c JP
578 この引数は、文字、文字集合オブジェクト、あるいは1つの文字を引数に取り
579 真偽値を返す述語のいずれかです。``文字に@var{char/char-set/pred}を適用する''
580 の意味はそれぞれ、@var{char/char-set/pred}が文字ならば与えられた文字と比較される、
581 @var{char/char-set/pred}が文字集合ならばその文字集合に与えられた文字が
582 含まれるかを検査する、@var{char/char-set/pred}が述語ならばそれを与えられた
583 文字に適用する、となります。``ある文字が@var{char/char-set/pred}を満足する''
584 とは、その文字への前述のような適用が真値を返すという意味になります。
585 @c COMMON
586
587 @item @var{start}, @var{end}
588 @c EN
589 Lots of SRFI-13 functions takes these two optional arguments, which
590 limit the area of input string from @var{start}-th character
591 (inclusive) to @var{end}-th character (exclusive),
592 where the operation is performed.
593 When specified, the condition
594 0 <= @var{start} <= @var{end} <= @var{length of the string} must be
595 satisfied. Default value of @var{start} and @var{end} is
596 0 and the length of the string, respectively.
597 @c JP
598 SRFI-13の関数の多くは、その操作が実行される対象入力文字列の
599 範囲を限定する開始インデックスと終了インデックスをオプショナルな
600 引数として取ります。開始(@var{start}番目)の文字は含まれ、
601 終了(@var{end}番目)の文字は含まれません。
602 これらが指定されるとき、0 <= @var{start} <= @var{end} <= @var{length of the string}が
603 満たされなければなりません。@var{start}と@var{end}のデフォルト値は、
604 それぞれ0と文字列の長さです。
605 @c COMMON
606 @end table
607
608 @c EN
609 @item @code{shared} variant
610 @c JP
611 @item @code{shared}バージョン
612 @c EN
613 Some functions have variants with ``/shared'' attached to its name.
614 SRFI-13 defines those functions to allow to share the part of input
615 string, for better performance. Gauche doesn't have a concept of
616 shared string, and these functions are mere synonyms of their
617 non-shared variants. However, Gauche @emph{internally} shares
618 the storage of strings, so generally you don't need to worry
619 about the overhead of copying substrings.
620 @c JP
621 いくつかの関数は、その名前に``/shared''が付きます。
622 SRFI-13では、それらの関数はより良いパフォーマンスのために
623 入力文字列の一部を共有しても良いと定義しています。
624 Gaucheは、共有文字列という概念を持っていませんし、
625 それらの関数は単に共有でないバージョンの変名に過ぎません。
626 しかし、Gaucheは@emph{内部的には}文字列の保存場所を共有しているので、
627 一般的には部分文字列をコピーするオーバヘッドについて心配する
628 必要はありません。
629 @c COMMON
630
631 @c EN
632 @item @code{right} variant
633 @c JP
634 @item @code{right}バージョン
635 @c EN
636 Most functions works from left to right of the input string.
637 Some functions have variants with ``-right'' to its name,
638 that works from right to left.
639 @c JP
640 ほとんどの関数は、入力文字列を左から右へと扱います。
641 いくつかの関数は、その名前に``-right''が付き、右から左へと
642 扱うものがあります。
643 @c COMMON
644
645 @end table
646
647 @node SRFI-13 String predicates, SRFI-13 String constructors, SRFI-13 General conventions, String library
648 @subsection String predicates
649 @c NODE 文字列についての述語
650
651 @defun string-null? s
652 [SRFI-13]
653 @c MOD srfi.13
654 @c EN
655 Returns @code{#t} if @var{s} is an empty string, @code{""}.
656 @c JP
657 @var{s}が空文字列、@code{""}なら、@code{#t}を返します。
658 @c COMMON
659 @end defun
660
661 @defun string-every char/char-set/pred s :optional start end
662 [SRFI-13]
663 @c MOD srfi.13
664 @c EN
665 Sees if every character in @var{s} satisfies
666 @var{char/char-set/pred}. If so, @code{string-every} returns
667 the value that is returned at the last application of @var{char/char-set/pred}.
668 If any of the application returns @code{#f}, @code{string-every}
669 returns @code{#f} immediately.
670 @c JP
671 @var{s}に含まれる全ての文字が@var{char/char-set/pred}を
672 満足するかを検査します。満足するならば、@code{string-every}は
673 最後に適用された@var{char/char-set/pred}が返した値を戻り値とします。
674 どの適用も@code{#f}を返した場合は、@code{string-every}はすぐに
675 @code{#f}を返します。
676 @c COMMON
677 @end defun
678
679 @defun string-any char/char-set/pred s :optional start end
680 [SRFI-13]
681 @c MOD srfi.13
682 @c EN
683 Sees if any character in @var{s} satisfies
684 @var{char/char-set/pred}. If so, @code{string-any} returns
685 the value that is returned by the application. If no character
686 satisfies @var{char/char-set/pred}, @code{#f} is returned.
687 @c JP
688 @var{s}に含まれるいずれかの文字が@var{char/char-set/pred}
689 を満足するかを検査します。いずれかの文字が満足するならば、
690 @code{string-any}はその適用が返した値を戻り値とします。
691 どの文字も@var{char/char-set/pred}を満たさなければ、@code{#f}が返ります。
692 @c COMMON
693 @end defun
694
695 @node SRFI-13 String constructors, SRFI-13 String selection, SRFI-13 String predicates, String library
696 @subsection String constructors
697 @c NODE 文字列の構築子
698
699 @defun string-tabulate proc len
700 [SRFI-13]
701 @c MOD srfi.13
702 @c EN
703 @var{proc} must be a procedure that takes an integer
704 argument and returns a character. @code{string-tabulate}
705 creates a string, whose @var{i}-th character is calculated by
706 @code{(proc i)}.
707 @c JP
708 @var{proc}は整数を1つ引数として取り文字を返す手続きで
709 なければなりません。@code{string-tabulate}は、その@var{i}番目の
710 文字が@code{(proc i)}で計算されるような文字列を返します。
711 @c COMMON
712 @example
713 (string-tabulate
714 (lambda (i) (integer->char (+ i #x30))) 10)
715 @result{} "0123456789"
716 @end example
717 @end defun
718
719 @defun string-unfold p f g seed :optional base make-final
720 [SRFI-13]
721 @c MOD srfi.13
722 @c EN
723 A fundamental string builder. The @var{p}, @var{f} and @var{g} are
724 procedures, taking the current seed value. The stop predicate @var{p}
725 determines when to stop: If it returns a true value, string building
726 stops. The mapping function @var{f} returns a character
727 from the current seed value. The next seed function @var{g} returns
728 a next seed value from the current seed value. The @var{seed} argument
729 gives the initial seed value.
730 @c JP
731 基本的な文字列構築手続きです。
732 @var{p}、@var{f}、@var{g}は手続きで、現在のシード値を受けとります。
733 停止述語@var{p}はいつ繰り返しを止めるかを判断します。それが真の値を返したら、
734 文字列構築は終了し、それまでに生成された文字が集められて文字列として返されます。
735 @var{f}はシード値から文字を生成する手続きです。@var{g}はシード値から次のシード値を
736 生成します。@var{seed}引数はシード値の初期値を指定します。
737 @c COMMON
738
739 @example
740 (string-unfold (^n (= n 10))
741 (^n (integer->char (+ n 48)))
742 (^n (+ n 1))
743 0)
744 @result{} "0123456789"
745 @end example
746
747 @c EN
748 The optional argument @var{base} is, when given, prepended to the
749 result string. Another optional argument @var{make-final}
750 is a procedure that takes the last return value of @var{g} and
751 returns a string that becomes the suffix of the result string.
752 @c JP
753 省略可能引数@var{base}は、与えられれば生成される文字列のプレフィクスとなります。
754 @var{make-final}は手続きで、繰り返しが終了した後の最後のシード値を受け取り、
755 文字列のサフィックスを返します。
756 @c COMMON
757
758 @example
759 (string-unfold (^n (= n 10))
760 (^n (integer->char (+ n 48)))
761 (^n (+ n 1))
762 0 "foo" x->string)
763 @result{} "foo012345678910"
764 @end example
765 @end defun
766
767 @defun string-unfold-right p f g seed :optional base make-final
768 [SRFI-13]
769 @c MOD srfi.13
770 @c EN
771 Another fundamental string builder. The meanings of arguments
772 are the same as @code{string-unfold}. The only difference is
773 that the string is build right-to-left. The optional @var{base},
774 if given, becomes the suffix of result, and the result of
775 @var{make-final} becomes the prefix.
776 @c JP
777 もうひとつの基本的な文字列構築器です。引数の意味は@code{string-unfold}と
778 同じですが、@var{f}の返す文字が右から左へと並べられます。
779 また、章句可能な@var{base}引数はサフィックスに、
780 @var{make-final}が返す文字列はプレフィクスになります。
781 @c COMMON
782
783 @example
784 (string-unfold-right (^n (= n 10))
785 (^n (integer->char (+ n 48)))
786 (^n (+ n 1))
787 0 "foo" x->string)
788 @result{} "109876543210foo"
789 @end example
790 @end defun
791
792
793 @defun reverse-list->string char-list
794 [SRFI-13]
795 @c MOD srfi.13
796 @equiv{} @code{(list->string (reverse char-list))}.
797 @end defun
798
799 @node SRFI-13 String selection, SRFI-13 String comparison, SRFI-13 String constructors, String library
800 @subsection String selection
801 @c NODE 文字列の選択
802
803 @defun substring/shared s start :optional end
804 [SRFI-13]
805 @c MOD srfi.13
806 @c EN
807 In Gauche, this is the same as @code{substring}, except
808 that the @var{end} argument is optional.
809 @c JP
810 Gaucheでは、引数@var{end}がオプショナルであることを除いて、
811 @code{substring}と同じです。
812 @c COMMON
813 @example
814 (substring/shared "abcde" 2) @result{} "cde"
815 @end example
816 @end defun
817
818 @defun string-copy! target tstart s :optional start end
819 [SRFI-13]
820 @c MOD srfi.13
821 @c EN
822 Copies a string @var{s} into a string
823 @var{target} from the position @var{tstart}.
824 The @var{target} string must be mutable.
825 Optional @var{start} and @var{end} arguments limits the range of @var{s}.
826 If the copied string run over the end of @var{target}, an error is
827 signaled.
828 @c JP
829 文字列@var{s}を、文字列@var{target}の@var{tstart}番目以降へコピーします。
830 @var{target}文字列は変更可能でなければなりません。
831 オプションの引数@var{start}と@var{end}は、@var{s}の範囲を制限します。
832 コピーされた文字列が@var{target}の終端を越えたらエラーが通知されます。
833 @c COMMON
834 @example
835 (define s (string-copy "abcde"))
836 (string-copy! s 2 "ZZ")
837 s @result{} "abZZe"
838 @end example
839
840 @c EN
841 It is ok to pass the same string to @var{target} and @var{s}; this
842 always work even if the regions of source and destination are overlapping.
843 @c JP
844 @var{target}と@var{s}に同じ文字列を渡しても構いません。コピー元とコピー先の
845 領域が重なっていても、コピーは常に正しく行われます。
846 @c COMMON
847
848 @c EN
849 Note that Gauche encourages you to treat strings as immutable objects.
850 Internally, a string is an indirect pointer to a immutable entity, and
851 mutating a string means copying the original entity and creating a new one.
852 It doesn't ``save allocations''.
853 Always use the functional version @code{string-copy} unless you
854 absolutely need to replace a string in-place.
855 @xref{String utilities}.
856 @c JP
857 Gaucheでは、文字列を変更不可なオブジェクトとして扱うことを強く推奨しています。
858 内部的に、文字列オブジェクトは変更不可な文字列の実体へのポインタとなっています。
859 文字列を変更すると、新たな文字列実体がアロケートされそれが変更されるので、
860 破壊的手続きを使えばメモリアロケーションが節約できるということはありません。
861 どうしても文字列そのものを破壊的変更したい場合でない限りは、
862 非破壊版の@code{string-copy}を使いましょう。@ref{String utilities}参照。
863 @c COMMON
864 @end defun
865
866 @defun string-take s nchars
867 @defunx string-drop s nchars
868 @defunx string-take-right s nchars
869 @defunx string-drop-right s nchars
870 [SRFI-13]
871 @c MOD srfi.13
872 @c EN
873 Returns the first @var{nchars}-character string of @var{s}
874 (@code{string-take}) or the string without first @var{nchars}
875 (@code{string-drop}). The @code{*-right} variation counts from
876 the end of string. It is guaranteed that the returned string is
877 always a copy of @var{s}, even no character is dropped.
878 @c JP
879 @code{string-take}は、@var{s}の最初の@var{nchars}文字からなる文字列を返します。
880 @code{string-drop}は、@var{s}から最初の@var{nchars}文字からなる文字列を
881 除いた残りを返します。@code{*-right}バージョンは、文字列の最後から数えます。
882 返される文字列はいつも@var{s}のコピーであり、どの文字も削除されないことが
883 保証されています。
884 @c COMMON
885 @example
886 (string-take "abcde" 2) @result{} "ab"
887 (string-drop "abcde" 2) @result{} "cde"
888
889 (string-take-right "abcde" 2) @result{} "de"
890 (string-drop-right "abcde" 2) @result{} "abc"
891 @end example
892 @end defun
893
894 @defun string-pad s len :optional char start end
895 @defunx string-pad-right s len :optional char start end
896 [SRFI-13]
897 @c MOD srfi.13
898 @c EN
899 If a string @var{s} is shorter than @var{len},
900 returns a string of @var{len} where @var{char} is
901 padded to the left or right, respectively.
902 If @var{s} is longer than @var{len}, the rightmost
903 or leftmost @var{len} chars are taken.
904 @var{Char} defaults to @code{#\space}.
905 If @var{start} and @var{end} are provided,
906 the substring of @var{s} is used as the source.
907 @c JP
908 文字列@var{s}が@var{len}より短い場合は、@var{char}がそれぞれ左か
909 右にパディングされた長さ@var{len}の文字列を返します。
910 @var{s}が@var{len}よりも長い場合は、@var{len}文字が右端か左端から
911 取り除かれます。@var{Char}のデフォルト値は@code{#\space}です。
912 @var{start}と@var{end}が与えられると、@var{s}の部分文字列がソース
913 文字列として使われます。
914 @c COMMON
915
916 @example
917 (string-pad "abc" 10) @result{} " abc"
918 (string-pad "abcdefg" 3) @result{} "efg"
919
920 (string-pad-right "abc" 10) @result{} "abc "
921
922 (string-pad "abcdefg" 10 #\+ 2 5)
923 @result{} "+++++++cde"
924 @end example
925 @end defun
926
927 @defun string-trim s :optional char/char-set/pred start end
928 @defunx string-trim-right s :optional char/char-set/pred start end
929 @defunx string-trim-both s :optional char/char-set/pred start end
930 [SRFI-13]
931 @c MOD srfi.13
932 @c EN
933 Removes characters that match @var{char/char-set/pred}
934 from @var{s}. @code{String-trim} removes the characters from
935 left of @var{s}, @code{string-trim-right} does from right,
936 and @code{string-trim-both} does from both sides.
937 @c JP
938 @var{s}から@var{char/char-set/pred}にマッチする文字を削除します。
939 @code{String-trim}は@var{s}の左から文字を削除し、
940 @code{string-trim-right}は右から、@code{string-trim-both}は
941 両端から削除します。
942 @c COMMON
943 @c EN
944 @var{Char/char-set/pred} defaults to @code{#[\s]}, i.e. a char-set
945 of whitespaces.
946 If @var{start} and @var{end} are provided,
947 the substring of @var{s} is used as the source.
948 @c JP
949 @var{Char/char-set/pred}のデフォルト値は@code{#[\s]}、つまり空白文字の
950 文字集合です。@var{start}と@var{end}が与えられると、@var{s}の部分文字列が
951 ソース文字列として使われます。
952 @c COMMON
953
954 @example
955 (string-trim " abc ") @result{} "abc "
956 (string-trim-right " abc ") @result{} " abc"
957 (string-trim-both " abc ") @result{} "abc"
958 @end example
959 @end defun
960
961 @node SRFI-13 String comparison, SRFI-13 String prefixes & suffixes, SRFI-13 String selection, String library
962 @subsection String comparison
963 @c NODE 文字列の色々な比較
964
965 @defun string-compare s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
966 @defunx string-compare-ci s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
967 [SRFI-13]
968 @c MOD srfi.13
969 @c EN
970 Compares two strings @var{s1} and @var{s2} codepoint-wise from left.
971 When mismatch is found at the index @var{k} of @var{s1},
972 calls @var{proc<} with @var{k} if @var{s1}'s codepoint is smaller than
973 the corresponding @var{s2}'s, or calls @var{proc>} if @var{s1}'s one is
974 greater than @var{s2}'s. If two strings are the same, calls @var{proc=}
975 with the index of the last compared position in @var{s1}.
976 @c JP
977 文字列@var{s1}と@var{s2}をコードポイント毎に左から比較します。
978 不一致が@var{s1}のインデックス@var{k}で見つかった場合、対応する@var{s2}の
979 コードポイントより@var{s1}のコードポイントの方が小さければ
980 @var{proc<}を@var{k}を引数にして呼び出し、逆に大きければ
981 @var{proc>}を@var{k}を引数にして呼び出します。
982 二つの文字列が等しければ、@var{proc=}が、@var{s1}の比較された最後のインデックスを
983 引数にして呼び出されます。
984 @c COMMON
985
986 @example
987 (string-compare "abcd" "abzd"
988 (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)))
989 @result{} (< 2)
990
991 (string-compare "abcd" "abcd"
992 (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)))
993 @result{} (= 3)
994 @end example
995
996 @c EN
997 The optional arguments restricts
998 the range of the input strings; however, the index passed to one
999 of the procedures is always an index from the beginning of @var{s1}.
1000 @c JP
1001 省略可能引数は入力の文字列の比較すべき範囲を制限します。
1002 但し、@var{proc<}、@var{proc=}、@var{proc>}に渡されるインデックスは
1003 常に@var{s1}の最初から数えたものになります。
1004 @c COMMON
1005
1006 @example
1007 (string-compare "zzabcdyy" "abcz"
1008 (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)) 2 6 0 4)
1009 @result{} (< 5)
1010
1011 (string-compare "zzabcdyy" "abcz"
1012 (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)) 2 5 0 3)
1013
1014 @result{} (= 4)
1015 @end example
1016
1017 @c EN
1018 The case-insensitive variant, @code{string-compare-ci}, compares
1019 each codepoint with character-wise case-folding. It won't consider
1020 special case folding such as German eszett.
1021 @c JP
1022 @code{string-compare-ci}は大文字小文字を区別しない比較です。
1023 文字毎の大文字小文字変換を行って比較するので、文字列の長さが変わる
1024 大文字小文字変換のケース (ドイツ語のエスツェット等) は考慮されません。
1025 @c COMMON
1026 @end defun
1027
1028 @defun string= s1 s2 :optional start1 end1 start2 end2
1029 @defunx string<> s1 s2 :optional start1 end1 start2 end2
1030 @defunx string< s1 s2 :optional start1 end1 start2 end2
1031 @defunx string<= s1 s2 :optional start1 end1 start2 end2
1032 @defunx string> s1 s2 :optional start1 end1 start2 end2
1033 @defunx string>= s1 s2 :optional start1 end1 start2 end2
1034 [SRFI-13]
1035 @c MOD srfi.13
1036 @c EN
1037 Compare two strings @var{s1} and @var{s2}. Optional arguments
1038 can limit the portion of strings to be compared.
1039 Comparison is done by character-wise.
1040
1041 Note: The builtin procedures @code{string=?} etc. can also be
1042 used for character-wise string comparison, but they take
1043 arguments differently. @xref{String comparison}.
1044 @c JP
1045 二つの文字列@var{s1}と@var{s2}を比較します。省略可能引数で
1046 それぞれの文字列の一部のみを比較するように指定できます。
1047 比較は文字ごとに行われます。
1048
1049 註: 組み込み手続きの@code{string=?}等も文字毎の比較に使えますが、
1050 引数の取り方が違います。@ref{String comparison}参照。
1051 @c COMMON
1052 @end defun
1053
1054 @defun string-ci= s1 s2 :optional start1 end1 start2 end2
1055 @defunx string-ci<> s1 s2 :optional start1 end1 start2 end2
1056 @defunx string-ci< s1 s2 :optional start1 end1 start2 end2
1057 @defunx string-ci<= s1 s2 :optional start1 end1 start2 end2
1058 @defunx string-ci> s1 s2 :optional start1 end1 start2 end2
1059 @defunx string-ci>= s1 s2 :optional start1 end1 start2 end2
1060 [SRFI-13]
1061 @c MOD srfi.13
1062 @c EN
1063 Compare two strings @var{s1} and @var{s2} in case-insensitive way.
1064 Optional arguments can limit the portion of strings to be compared.
1065 Case folding and comparison is done by character-wise, so they don't
1066 consider case folding that affects multiple characters.
1067
1068 Note: We have two other sets of string comparison operations,
1069 both are named as @code{string-ci=?} etc.
1070 The builtin version (@pxref{String comparison}) does character-wise
1071 comparison. The one in @code{gauche.unicode} uses full-string
1072 case conversion (@pxref{Full string case conversion}).
1073 R7RS version is the latter.
1074 @c JP
1075 二つの文字列@var{s1}と@var{s2}を、大文字小文字を区別せずに比較します。
1076 省略可能引数でそれぞれの文字列の一部のみを比較するように指定できます。
1077 大文字小文字の畳み込みと比較は文字ごとに行われます。複数の文字に
1078 影響を与えるような大文字小文字の畳み込みは考慮しません。
1079
1080 註: Gaucheには他に2種類の大文字小文字を区別しない文字列比較手続き群があります。
1081 どちらも@code{string-ci=?}等のようにクエスチョンマーク付きの名前を持っています。
1082 Gauche組み込みのものは文字毎に大文字小文字を畳み込みます
1083 (@ref{String comparison}参照)。一方、@code{gauche.unicode}にあるものは
1084 文字列としての畳み込みを行います(@ref{Full string case conversion}参照)。
1085 R7RS版は後者です。
1086 @c COMMON
1087 @end defun
1088
1089 @defun string-hash s :optional bound start end
1090 @defunx string-hash-ci s :optional bound start end
1091 [SRFI-13]
1092 @c MOD srfi.13
1093 @c EN
1094 (Note: Gauche has builtin @code{string-hash} and @code{string-ci-hash}
1095 according to SRFI-128. @xref{Hashing}, for the details.
1096 SRFI-13's API is upper-compatible to SRFI-128's. The underlying
1097 hash algorithm is the same as the builtin ones, so @code{string-hash}
1098 returns the same value as the builtin ones for the same string
1099 if optional arguments are omitted.
1100 On the other hand, the builtin @code{string-ci-hash} uses string case
1101 folding (e.g. German eszett and @code{SS} are the same), while
1102 SRFI-13's @code{string-hash-ci} uses character-wise case folding.
1103 Unless there's a strong reason, we recommend new code should use
1104 builtin SRFI-128 version instead of SRFI-13.)
1105
1106 Calculates hash value of a string @var{s}. For @code{string-hash-ci},
1107 character-wise case folding is done before calculating the hash value.
1108
1109 If the optional @var{bound} argument is given, it must be a positive
1110 exact integer, and the return value is limited below it.
1111 The optional @var{start} and @var{end} arguments allows
1112 using that portion for calculation.
1113 @c JP
1114 (註: Gaucheは、SRFI-128に準拠した@code{string-hash}と@code{string-ci-hash}を
1115 組み込みで持っています。詳しくは@ref{Hashing}参照。
1116 SRFI-13のAPIはSRFI-128の上位互換になっています。内部で使っているハッシュ
1117 アルゴリズムは一緒なので、省略可能引数を全て省略したSRFI-13の@code{string-hash}は、
1118 組み込みの@code{string-hash}と同じ値を返します。
1119 一方、組み込みの@code{string-ci-hash}は文字列として大文字小文字の畳み込みを
1120 行います(ドイツ語のエスツェットと@code{SS}は等しく扱われます)が、SRFI-13の
1121 @code{string-hash-ci}は文字毎に大文字小文字を畳み込むように定められているので、
1122 結果が異なる可能性があります。特に強い理由がなければ、新しいコードは
1123 組み込みのSRFI-128版を使うことをおすすめします。)
1124
1125 文字列@var{s}のハッシュ値を計算して返します。@code{string-hash-ci}では
1126 ハッシュ値を計算する前に各文字について大文字小文字を畳み込みを行います。
1127
1128 省略可能引数@var{bound}は、与えられたなら正の正確な整数でなければならず、
1129 返される値は0から@code{(- bound 1)}までの値に制限されます。
1130 @var{start}と@var{end}は、与えられれば@var{s}中の対象となる部分文字列を
1131 指定します。
1132 @c COMMON
1133 @end defun
1134
1135 @node SRFI-13 String prefixes & suffixes, SRFI-13 String searching, SRFI-13 String comparison, String library
1136 @subsection String prefixes & suffixes
1137 @c NODE 文字列のプリフィックスとサフィックス
1138
1139 @defun string-prefix-length s1 s2 :optional start1 end1 start2 end2
1140 @defunx string-suffix-length s1 s2 :optional start1 end1 start2 end2
1141 @defunx string-prefix-length-ci s1 s2 :optional start1 end1 start2 end2
1142 @defunx string-suffix-length-ci s1 s2 :optional start1 end1 start2 end2
1143 [SRFI-13]
1144 @c MOD srfi.13
1145 @c EN
1146 Returns the length of the longest common prefix/suffix of two strings,
1147 @var{s1} and @var{s2}. The optional arguments restrict the range of
1148 search. The @code{*-ci} variations use case folding character comparison.
1149 @c JP
1150 二つの文字列@var{s1}と@var{s2}の、共通するプレフィクスもしくはサフィックスの
1151 長さを返します。省略可能引数はそれぞれの文字列の探索範囲を限定します。
1152 @code{*-ci}版は文字ごとに、大文字小文字を区別しない比較を行います。
1153 @c COMMON
1154
1155 @example
1156 (string-prefix-length "abacus" "abalone") @result{} 3
1157 (string-prefix-length "machine" "umbrella") @result{} 0
1158 (string-suffix-length "peeking" "poking") @result{} 4
1159
1160 (string-prefix-length "obvious" "oblivious" 2 7 4 9)
1161 @result{} 5
1162 @end example
1163 @end defun
1164
1165 @defun string-prefix? s1 s2 :optional start1 end1 start2 end2
1166 @defunx string-suffix? s1 s2 :optional start1 end1 start2 end2
1167 @defunx string-prefix-ci? s1 s2 :optional start1 end1 start2 end2
1168 @defunx string-suffix-ci? s1 s2 :optional start1 end1 start2 end2
1169 [SRFI-13]
1170 @c MOD srfi.13
1171 @c EN
1172 Returns true iff @var{s1} is a prefix or suffix of @var{s2}, respectively.
1173 The optional arguments limit the range of @var{s1} and @var{s2} to look at.
1174 The @code{*-ci} variations use case folding character comparison.
1175 @c JP
1176 それぞれ、@var{s1}が@var{s2}のプレフィクスまたはサフィックスになっていた場合に
1177 @code{#t}を、それ以外の場合に@code{#f}を返します。
1178 省略可能引数はそれぞれの文字列の探索範囲を限定します。
1179 @code{*-ci}版は文字ごとに、大文字小文字を区別しない比較を行います。
1180 @c COMMON
1181
1182 @example
1183 (string-prefix? "sch" "scheme") @result{} #t
1184 (string-prefix? "lisp" "scheme") @result{} #f
1185
1186 (string-suffix? "eme" "scheme") @result{} #t
1187 (string-suffix? "eme" "lisp") @result{} #f
1188
1189 (string-prefix? "mit-scheme" "scheme-family" 4) @result{} #t
1190 @end example
1191 @end defun
1192
1193 @node SRFI-13 String searching, SRFI-13 String case mapping, SRFI-13 String prefixes & suffixes, String library
1194 @subsection String searching
1195 @c NODE 文字列の探索
1196
1197 @defun string-index s char/char-set/pred :optional start end
1198 @defunx string-index-right s char/char-set/pred :optional start end
1199 [SRFI-13]
1200 @c MOD srfi.13
1201 @c EN
1202 Looks for the first element in a string @var{s}
1203 that matches @var{char/char-set/pred}, and returns its index.
1204 If @var{char/char-set/pred} is not found in @var{s}, returns @code{#f}.
1205 Optional @var{start} and @var{end} limit the range of @var{s} to search.
1206 @c JP
1207 文字列@var{s}の中で、@var{char/char-set/pred}にマッチする
1208 最初の要素を探し、そのインデックスを返します。
1209 @var{s}の中に@var{char/char-set/pred}が見つからない場合は、@code{#f}を
1210 返します。オプションの@var{start}と@var{end}は、@var{s}の中で検索対象と
1211 なる範囲を制限します。
1212 @c COMMON
1213 @example
1214 (string-index "Aloha oe" #\a) @result{} 4
1215 (string-index "Aloha oe" #[Aa]) @result{} 0
1216 (string-index "Aloha oe" #[\s]) @result{} 5
1217 (string-index "Aloha oe" char-lower-case?) @result{} 1
1218 (string-index "Aloha oe" #\o 3) @result{} 6
1219 @end example
1220
1221 @c EN
1222 See also the Gauche built-in procedure @code{string-scan}
1223 (@ref{String utilities}), if you need speed over portability.
1224 @c JP
1225 ポータビリティよりも速度を重視する場合は、Gaucheのビルトイン手続き
1226 @code{string-scan}(@ref{String utilities})を参照して下さい。
1227 @c COMMON
1228 @end defun
1229
1230 @defun string-skip s char/char-set/pred :optional start end
1231 @defunx string-skip-right s char/char-set/pred :optional start end
1232 [SRFI-13]
1233 @c MOD srfi.13
1234 @c EN
1235 Looks for the first element that does not match
1236 @var{char/char-set/pred} and returns its index.
1237 If such element is not found, returns @code{#f}.
1238 Optional @var{start} and @var{end} limit the range of @var{s} to search.
1239 @c JP
1240 @var{char/char-set/pred}にマッチしない最初の要素を探し、
1241 そのインデックスを返します。そのような要素が見つからない場合、@code{#f}を
1242 返します。オプションの@var{start}と@var{end}は、@var{s}の中で検索対象と
1243 なる範囲を制限します。
1244 @c COMMON
1245 @end defun
1246
1247 @defun string-count s char/char-set/pred :optional start end
1248 [SRFI-13]
1249 @c MOD srfi.13
1250 @c EN
1251 Counts the number of elements in @var{s}
1252 that matches @var{char/char-set/pred}.
1253 Optional @var{start} and @var{end} limit the range of @var{s} to search.
1254 @c JP
1255 @var{s}の中で、@var{char/char-set/pred}にマッチする要素の数を
1256 カウントします。オプションの@var{start}と@var{end}は、@var{s}の中で検索対象と
1257 なる範囲を制限します。
1258 @c COMMON
1259 @end defun
1260
1261 @defun string-contains s1 s2 :optional start1 end1 start2 end2
1262 @defunx string-contains-ci s1 s2 :optional start1 end1 start2 end2
1263 [SRFI-13]
1264 @c MOD srfi.13
1265 @c EN
1266 Looks for a string @var{s2} inside another string @var{s1}.
1267 If found, returns an index in @var{s1} from where the matching string
1268 begins. Returns @code{#f} otherwise.
1269 Optional @var{start1}, @var{end1}, @var{start2} and @var{end2}
1270 limits the range of @var{s1} and @var{s2}.
1271
1272 See also the Gauche built-in procedure @code{string-scan}
1273 (@ref{String utilities}), if you need speed over portability.
1274 @c JP
1275 @var{s1}の中で、文字列@var{s2}を探します。見つかった場合は、
1276 @var{s1}でマッチした文字列が始まるインデックスを返します。そうでなければ、
1277 @code{#f}を返します。
1278 オプションの@var{start1}、@var{end1}、@var{start2}、@var{end2}は、
1279 @var{s1}と@var{s2}の範囲を制限します。
1280
1281 ポータビリティよりも速度を重視する場合は、Gaucheのビルトイン手続き
1282 @code{string-scan}(@ref{String utilities})を参照して下さい。
1283 @c COMMON
1284 @end defun
1285
1286 @node SRFI-13 String case mapping, SRFI-13 String reverse & append, SRFI-13 String searching, String library
1287 @subsection String case mapping
1288 @c NODE 文字列のケース(大文字小文字)マッピング
1289
1290 @defun string-titlecase s :optional start end
1291 @defunx string-titlecase! s :optional start end
1292 @defunx string-upcase s :optional start end
1293 @defunx string-upcase! s :optional start end
1294 @defunx string-downcase s :optional start end
1295 @defunx string-downcase! s :optional start end
1296 [SRFI-13]
1297 @c MOD srfi.13
1298 @c EN
1299 Converts a string @var{s} to titlecase, upcase or downcase,
1300 respectively. These operations uses character-by-character
1301 mapping provided by @code{char-upcase} etc. That is, @code{string-upcase}
1302 and @code{string-downcase} can be understood as follow:
1303 @c JP
1304 文字列@var{s}をタイトルケース、大文字、小文字にそれぞれ変換します。
1305 これらの手続きは、文字ごとに@code{char-upcase}等を使った変換を行います。
1306 すなわち、@code{string-upcase}と@code{string-downcase}は以下の操作と
1307 考えることができます。
1308 @c COMMON
1309
1310 @example
1311 (string-upcase s)
1312 @equiv{} (string-map char-upcase s)
1313 (string-downcase s)
1314 @equiv{} (string-map char-downcase s)
1315 @end example
1316
1317 @c EN
1318 If you need full case mapping that handles the case when
1319 a character is mapped to more than one characters, use
1320 the procedures with the same name in @code{gauche.unicode} module
1321 (@pxref{Full string case conversion}).
1322 @c JP
1323 一文字がケース変換によって複数文字になるような場合も考慮したい場合は、
1324 @code{gauche.unicode}モジュールに定義されている同名の手続きを使ってください
1325 (@ref{Full string case conversion}参照)。
1326 @c COMMON
1327
1328 @c EN
1329 The linear-update version @code{string-titlecase!}, @code{string-upcase!}
1330 and @code{string-downcase!} destroys @var{s} to store the result.
1331 Note that in Gauche, using those procedures doesn't save anything,
1332 since string mutation is expensive by design. They are provided merely
1333 for completeness.
1334 @c JP
1335 @code{string-titlecase!}、@code{string-upcase!}、
1336 @code{string-downcase!}はその場で更新するバージョンで、@var{s}を破壊的に
1337 変更します。ただし、Gaucheでは文字列の変更は新たな文字列を作るのと効率的に
1338 何ら変わりがありません。これらの手続きは互換性のためだけに用意されています。
1339 @c COMMON
1340 @end defun
1341
1342
1343 @node SRFI-13 String reverse & append, SRFI-13 String mapping, SRFI-13 String case mapping, String library
1344 @subsection String reverse & append
1345 @c NODE 文字列の反転と追加
1346
1347 @defun string-reverse s :optional start end
1348 @defunx string-reverse! s :optional start end
1349 [SRFI-13]
1350 @c MOD srfi.13
1351 @c EN
1352 Returns a string in which the character positions are reversed
1353 from @var{s}. @code{string-reverse!} modifies @var{s}.
1354 @c JP
1355 @var{s}の文字の位置を逆順にした文字列を返します。
1356 @code{string-reverse!}は@var{s}そのものを変更します。
1357 @c COMMON
1358 @example
1359 (string-reverse "mahalo") @result{} "olaham"
1360 (string-reverse "mahalo" 3) @result{} "ola"
1361 (string-reverse "mahalo" 1 4) @result{} "aha"
1362
1363 (let ((s (string-copy "mahalo")))
1364 (string-reverse! s 1 5)
1365 s)
1366 @result{} "mlahao"
1367 @end example
1368 @end defun
1369
1370 @defun string-concatenate string-list
1371 [SRFI-13]
1372 @c MOD srfi.13
1373 @c EN
1374 Concatenates list of strings.
1375 @c JP
1376 文字列のリストを連結します。
1377 @c COMMON
1378 @example
1379 (string-concatenate '("humuhumu" "nukunuku" "apua" "`a"))
1380 @result{} "humuhumunukunukuapua`a"
1381 @end example
1382 @end defun
1383
1384 @defun string-concatenate/shared string-list
1385 @defunx string-append/shared s @dots{}
1386 [SRFI-13]
1387 @c MOD srfi.13
1388 @c EN
1389 ``Shared'' version of @code{string-concatenate} and
1390 @code{string-append}. In Gauche, these are just synonyms of them.
1391 @c JP
1392 @code{string-concatenate}と@code{string-append}の``共有''
1393 バージョンです。Gaucheでは、これらは単に別名です。
1394 @c COMMON
1395 @end defun
1396
1397 @defun string-concatenate-reverse string-list
1398 @defunx string-concatenate-reverse/shared string-list
1399 [SRFI-13]
1400 @c MOD srfi.13
1401 @c EN
1402 Reverses @var{string-list} before concatenation.
1403 ``Shared'' version works the same in Gauche.
1404 @c JP
1405 @var{string-list}を連結する前に逆順にします。
1406 Gaucheでは、``共有''バージョンは全く同じ動作をします。
1407 @c COMMON
1408 @end defun
1409
1410 @node SRFI-13 String mapping, SRFI-13 String rotation, SRFI-13 String reverse & append, String library
1411 @subsection String mapping
1412 @c NODE 文字列のマッピング
1413
1414 @defun string-map! proc s :optional start end
1415 [SRFI-13]
1416 @c MOD srfi.13
1417 @c EN
1418 @code{string-map!} applies @var{proc} on every character of @var{s},
1419 and stores the results into @var{s}. It is an error if @var{proc} returns
1420 non-character.
1421 @c JP
1422 @code{string-map!}は、@var{s}の全ての文字に対して@var{proc}を
1423 適用し、その結果を@var{s}に格納します。
1424 @var{proc}は文字を返さねばなりません。
1425 @c COMMON
1426 @example
1427 (let ((s (string-copy "wikiwiki")))
1428 (string-map! char-upcase s 4)
1429 s)
1430 @result{} "wikiWIKI"
1431 @end example
1432 @end defun
1433
1434 @defun string-fold kons knil s :optional start end
1435 @defunx string-fold-right kons knil s :optional start end
1436 [SRFI-13]
1437 @c MOD srfi.13
1438 @c EN
1439 Like @var{fold} and @var{fold-right} (@pxref{Walking over lists}),
1440 but works on a string instead of a list.
1441 @c JP
1442 文字列に対して動作する@var{fold}や@var{fold-right} (@ref{Walking over lists}参照)
1443 です。
1444 @c COMMON
1445
1446 @example
1447 (string-fold cons '() "abcde")
1448 @result{} (#\e #\d #\c #\b #\a)
1449 (string-fold-right cons '() "abcde")
1450 @result{} (#\a #\b #\c #\d #\e)
1451 @end example
1452 @end defun
1453
1454 @defun string-for-each-index proc s :optional start end
1455 [SRFI-13]
1456 @c MOD srfi.13
1457 @c EN
1458 Call @var{proc} on each index of the string @var{s}, from left to right.
1459 The result of @var{proc} is discarded.
1460 The optional @var{start} and @var{end} arguments can be an integer
1461 index or a string cursor, restricting the range
1462 of the input string to be traversed.
1463 @c JP
1464 @var{proc}を@var{s}の各文字について、左から右の順に呼びます。@var{proc}の結果は
1465 捨てられます。
1466 省略可能な@var{start}と@var{end}引数は整数の文字インデックスか
1467 文字列カーソルで、対象となる文字列の範囲を制限します。
1468 @c COMMON
1469 @end defun
1470
1471 @node SRFI-13 String rotation, SRFI-13 Other string operations, SRFI-13 String mapping, String library
1472 @subsection String rotation
1473 @c NODE 文字列のローテーション
1474
1475 @defun xsubstring s from :optional to start end
1476 [SRFI-13]
1477 @c MOD srfi.13
1478 @c EN
1479 Takes a substring of infinite repetition of string @var{s}
1480 between index @var{from} (inclusive) and index @var{to} (exclusive).
1481 If @var{to} is omitted, the length of @var{s} is assumed.
1482 @c JP
1483 @var{s}が左右に無限に繰り替えされているとみなし、その整数インデックス
1484 の@var{from}から@var{to}までを切り出して返します。
1485 @var{to}が省略された場合は@var{s}の長さが使われます。
1486 @c COMMON
1487
1488 @c EN
1489 For example, if @var{s} is @code{"abcde"}, we repeat it
1490 infinitely to both sides. So @var{5n}-th character for integer @var{n}
1491 is always @code{#\a}, which extends negative @var{n} as well.
1492 @c JP
1493 例えば、@var{s}が@code{abcde}の場合、まずそれを無限の
1494 文字列@code{...abcdeabcdeabcde...}とみなします。
1495 つまり整数@var{n}に対して@var{5n}番目の文字は常に@code{#\a}です。
1496 これは@var{n}が負の領域にも拡張されます。
1497 @c COMMON
1498
1499 @example
1500 (xsubstring "abcde" 2 10)
1501 @result{} "cdeabcde"
1502 (xsubstring "abcde" -9 -2)
1503 @result{} "bcdeabc"
1504 @end example
1505
1506 @c EN
1507 The optional @var{start} and @var{end} arguments can be an integer
1508 index or a string cursor, it works as
1509 @code{(xsubstring (substring s start end) from to)}.
1510 @c JP
1511 省略可能な@var{start}と@var{end}引数は整数の文字インデックスか
1512 文字列カーソルで、与えられた場合、
1513 @code{(xsubstring (substring s start end) from to)}と同じ動作となります。
1514 @c COMMON
1515 @end defun
1516
1517 @defun string-xcopy! target tstart s sfrom :optional sto start end
1518 [SRFI-13]
1519 @c MOD srfi.13
1520 @c EN
1521 It works as
1522 @code{(string-copy! target tstart (xsubstring s sfrom sto start end))}.
1523 @c JP
1524 @code{(string-copy! target tstart (xsubstring s sfrom sto start end))}
1525 と同じ動作をします。
1526 @c COMMON
1527 @end defun
1528
1529 @node SRFI-13 Other string operations, SRFI-13 String filtering, SRFI-13 String rotation, String library
1530 @subsection Other string operations
1531 @c NODE 他の文字列操作
1532
1533 @defun string-replace s1 s2 start1 end1 :optional start2 end2
1534 [SRFI-13]
1535 @c MOD srfi.13
1536 @c EN
1537 Returns a new string whose content is a copy of a string @var{s1}, except
1538 the part beginning from the index
1539 @var{start1} (inclusive) and ending at the index @var{end1} (exclusive)
1540 is replaced by a string @var{s2}. When optional @var{start2} and @var{end2}
1541 arguments are given, @var{s2} is trimmed first according to them.
1542 The size of the @emph{gap}, @code{(- @var{end1} @var{start1})}, doesn't
1543 need to be the same as the size of the inserted string.
1544 Effectively, this is the same as the following code.
1545 @c JP
1546 文字列@var{s1}の@var{start1}文字目(inclusive)から@var{end1}文字目(exclusive)
1547 までを文字列@var{s2}に置き換えた文字列を新たに作って返します。@var{s1}, @var{s2}は
1548 変更されません。
1549 オプショナルな引数@var{start2}、@var{end2}が与えられた場合は、
1550 @var{s2}がまずそれらによって切り取られて置換文字列として使われます。
1551 置き換える隙間の大きさ、つまり@code{(- @var{end1} @var{start1})}は
1552 @var{s2}と同じ長さである必要はありません。
1553 実質的に、この手続きは次のコードと等価です。
1554 @c COMMON
1555
1556 @example
1557 (string-append (substring s1 0 start1)
1558 (substring s2 start2 end2)
1559 (substring s1 end1 (string-length s1)))
1560 @end example
1561 @end defun
1562
1563 @defun string-tokenize s :optional token-set start end
1564 [SRFI-13]
1565 @c MOD srfi.13
1566 @c EN
1567 Splits the string @var{s} into a list of substrings,
1568 where each substring is a maximal non-empty contiguous
1569 sequence of characters from the character set @var{token-set}.
1570 The default of @var{token-set} is @code{char-set:graphic}
1571 (@pxref{Predefined character sets}).
1572
1573 See also Gauche's built-in @code{string-split} (@pxref{String utilities}),
1574 which provides similar features but different criteria.
1575 @c JP
1576 文字列 @var{s} を、@var{token-set} で指定される文字集合で
1577 構成される、空でない最大限連続した文字のシーケンスのそれぞれを
1578 要素とするリストを返します。
1579 @var{token-set} のデフォルト値は @code{char-set:graphic}
1580 (@ref{Predefined character sets}参照)。
1581
1582 同様の機能を提供する、しかし異なる基準を持つ、Gauche の組み込み手続き
1583 @code{string-split} (@ref{String utilities} 参照) も見て下さい。
1584 @c COMMON
1585 @end defun
1586
1587 @node SRFI-13 String filtering, SRFI-13 Low-level string procedures, SRFI-13 Other string operations, String library
1588 @subsection String filtering
1589 @c NODE 文字列のフィルタリング
1590
1591 @defun string-filter char/char-set/pred s :optional start end
1592 @defunx string-delete char/char-set/pred s :optional start end
1593 [SRFI-13]
1594 @c MOD srfi.13
1595 @c EN
1596 Returns a string consists of characters in a string @var{s}
1597 that passes (or don't pass) the test indicated by @var{char/char-set/pred},
1598 respectively.
1599 @c JP
1600 それぞれ、文字列@var{s}中の文字のうち@var{char/char-set/pred}で示される
1601 テストを通る、または通らない文字からなる文字列を返します。
1602 @c COMMON
1603
1604 @example
1605 (string-filter char-upper-case? "Hello, World!")
1606 @result{} "HW"
1607
1608 (string-delete char-upper-case? "Hello, World!")
1609 @result{} "ello, orld!"
1610
1611 (string-delete #\l "Hello, World!")
1612 @result{} "Heo, Word!"
1613
1614 (string-filter #[\w] "Hello, World!")
1615 @result{} "HelloWorld"
1616 @end example
1617
1618 @c EN
1619 Note: SRFI-13 was revised after finalization to switch
1620 the order of arguments @var{char/char-set/pred} and @var{s} was.
1621 At the time of finalization, the order was
1622 @code{(string-filter s pred)} and Gauche implemented it accordingly.
1623 However, most existing implementations follows the revised order,
1624 since that was what the SRFI-13 reference implementation had.
1625
1626 So, from 0.9.4, we revised the API to comply the current
1627 SRFI-13 spec, but we also accept the old order as well
1628 not to break the old code.
1629 We recommend the new code to use the new order.
1630 @c JP
1631 註: SRFI-13は制定後に改訂され、引数@var{char/char-set/pred}と@var{s}の
1632 順序が逆になりました。制定時点では引数順は
1633 @code{(string-filter s pred)}で、Gaucheもそれに従って実装していました。
1634 しかし既存の実装のほとんどは@code{(string-filter pred s)}という順序に
1635 なっています。SRFI-13の参照実装がそうだったからです。
1636
1637 0.9.4からGaucheも現在のSRFI-13の実装に合わせましたが、
1638 以前の仕様で書かれたコードとの互換性を保つため、
1639 引数順を逆にしても動作するようになっています。
1640 新しく書かれるコードは、現在のSRFI-13の引数順を使うのが良いでしょう。
1641 @c COMMON
1642 @end defun
1643
1644 @node SRFI-13 Low-level string procedures, , SRFI-13 String filtering, String library
1645 @subsection Low-level string procedures
1646 @c NODE 低レベルな文字列に関する手続き
1647
1648 @c EN
1649 Here are some helper procedures useful
1650 to write other string-processing utilities similar to SRFI-13:
1651 @c JP
1652 SRFI-13に似せた他の文字列処理ユーティリティを書くのに便利なヘルパー関数です。
1653 @c COMMON
1654
1655
1656 @defun string-parse-start+end proc s args
1657 @defunx string-parse-final-start+end proc s args
1658 [SRFI-13]
1659 @c MOD srfi.13
1660 @c EN
1661 Most SRFI-13 procedures takes optional start and end arguments.
1662 These procedures looks for them in the rest arguments @var{args},
1663 and if they're not provided, gives the default values.
1664 @c JP
1665 多くのSRFI-13の手続きは、省略可能引数としてstartとend引数を取ります。
1666 この手続きは、残余引数リスト@var{args}にstartとendが指定されているかを調べ、
1667 指定されていればそれらを、されていなければ適切なデフォルト値を返します。
1668 @c COMMON
1669
1670 @c EN
1671 The @var{proc} argument is the name (symbol) of the procedure,
1672 to be used in the error condition, and @var{s} is the string to be processed.
1673 @c JP
1674 @var{proc}はエラー通知に使われる手続きの名前 (シンボル)、
1675 @var{s}は処理すべき文字列です。
1676 @c COMMON
1677
1678 @c EN
1679 Both expects an optional @var{start} argument at the beginning of @var{args},
1680 followed by an optional @var{end} argument. If the @var{end} argument
1681 is missing, the length of @var{s} is assumed. If the @var{start} argument
1682 is also missing, @code{0} is assumed.
1683 If arguments are provided, they must be exact integers,
1684 and @code{0} <= @var{start} <= @code{end} <= @code{(string-length @var{s})} must
1685 be satisfied; otherwise, an error is signaled.
1686 @c JP
1687 どちらの手続きも、@var{args}の最初に@var{start}引数があり、その次に@var{end}引数が
1688 あることを期待します。@var{end}引数が省略されていた場合は@var{s}の長さが、
1689 @var{start}引数も省略されていた場合は@code{0}が使われます。
1690 引数が与えられた場合は、それらは正確な整数で
1691 @code{0} <= @var{start} <= @code{end} <= @code{(string-length @var{s})}
1692 を満たしていなければなりません。そうでなければエラーが投げられます。
1693 @c COMMON
1694
1695 @c EN
1696 If more than two arguments are in @var{args}, @code{string-parse-final-start+end}
1697 raises an error (in other words, it requires that the argument list
1698 end with the @var{end} argument at most), while @code{string-parse-start+end}
1699 permits it and returns the result of arguments, along with start and
1700 end indexes.
1701 @c JP
1702 @var{args}に二つ以上の引数が含まれていた場合、
1703 @code{string-parse-final-start+end}はエラーを通知します
1704 (つまり、最長でも引数リストが@var{end}引数で終わる場合に使えます)。
1705 一方、@code{string-parse-start+end}は、余分な引数を許し、それを
1706 start/endの値とともに返します。
1707 @c COMMON
1708
1709 @c EN
1710 Both function return three values: The rest of the argument list,
1711 the start index, and the end index.
1712 @c JP
1713 どちらの関数も3つの値を返します。余分な引数のリスト、startの値、endの値です。
1714 @c COMMON
1715 @end defun
1716
1717 @defmac let-string-start+end (start end [rest]) proc-exp s-exp args-exp body @dots{}
1718 [SRFI-13]
1719 @c MOD srfi.13
1720 @end defmac
1721
1722 @defun check-substring-spec proc s start end
1723 @defunx substring-spec-ok? s start end
1724 [SRFI-13]
1725 @c MOD srfi.13
1726 @end defun
1727
1728 @defun make-kmp-restart-vector s :optional c= start end
1729 [SRFI-13]
1730 @c MOD srfi.13
1731 @end defun
1732
1733 @defun kmp-step pat rv c i c= p-start
1734 [SRFI-13]
1735 @c MOD srfi.13
1736 @end defun
1737
1738 @defun string-kmp-partial-search pat rv s i :optional c= p-start s-start s-end
1739 [SRFI-13]
1740 @c MOD srfi.13
1741 @end defun
1742
1743 @c ----------------------------------------------------------------------
1744 @node Time data types and procedures, Sources of random bits, String library, Library modules - SRFIs
1745 @section @code{srfi.19} - Time data types and procedures
1746 @c NODE 時間のデータ型と手続き, @code{srfi.19} - 時間のデータ型と手続き
1747
1748 @deftp {Module} srfi.19
1749 @mdindex srfi.19
1750 @c EN
1751 This SRFI defines various representations of time and date, and
1752 conversion methods among them.
1753 @c JP
1754 このSRFIは、時間と日付に関する様々な表現と、それらの間の変換メソッドを提供します。
1755 @c COMMON
1756
1757 @c EN
1758 On Gauche, time object is supported natively by @code{<time>} class
1759 (@pxref{Time}). Date object is supported by @code{<date>} class
1760 described below.
1761 @c JP
1762 Gaucheでは、timeオブジェクトは@code{<time>}クラスとして組み込みで
1763 サポートされています(@ref{Time}参照)。dateオブジェクトは以下で説明する
1764 @code{<date>}クラスとしてサポートされます。
1765 @c COMMON
1766 @end deftp
1767
1768 @menu
1769 * SRFI-19 Time types::
1770 * SRFI-19 Time queries::
1771 * SRFI-19 Time procedures::
1772 * SRFI-19 Date::
1773 * SRFI-19 Date reader and writer::
1774 @end menu
1775
1776 @node SRFI-19 Time types, SRFI-19 Time queries, Time data types and procedures, Time data types and procedures
1777 @subsection Time types
1778 @c NODE 時間のタイプ
1779
1780 @c EN
1781 Time type is represented by a symbol. This module defines
1782 the following constant variables that is bound to its name, for
1783 convenience.
1784 @c JP
1785 時間のタイプはシンボルで表現されます。
1786 このモジュールでは以下の定数が自分の名前に束縛された形で提供されています。
1787 @c COMMON
1788
1789 @defvr {Constant} time-utc
1790 [SRFI-19]
1791 @c MOD srfi.19
1792 @c EN
1793 UTC time. Gauche's built-in @code{current-time} always returns
1794 this type (@pxref{Time}).
1795 @c JP
1796 UTC timeです。Gaucheの組み込みの@code{current-time}は常にこのタイプの時間を
1797 返します (@ref{Time}参照)。
1798 @c COMMON
1799 @end defvr
1800
1801 @defvr {Constant} time-tai
1802 [SRFI-19]
1803 @c MOD srfi.19
1804 @c EN
1805 International Atomic Time. This time is a bit larger than UTC, due to
1806 the leap seconds.
1807 @c JP
1808 International Atomic Time。この時間は閏秒による調整を受けないため、
1809 UTCより若干大きな値を取ります。
1810 @c COMMON
1811 @end defvr
1812
1813 @defvr {Constant} time-monotonic
1814 [SRFI-19]
1815 @c MOD srfi.19
1816 @c EN
1817 Implementation-dependent monotonically increasing time.
1818 In Gauche, this is the same as @code{time-tai}.
1819 @c JP
1820 実装依存の、単調増加する時間。Gaucheの実装ではこれは@code{time-tai}と同じです。
1821 @c COMMON
1822 @end defvr
1823
1824 @defvr {Constant} time-duration
1825 [SRFI-19]
1826 @c MOD srfi.19
1827 @c EN
1828 Duration between two absolute time points.
1829 @c JP
1830 二つの絶対的な時点の間の期間。
1831 @c COMMON
1832 @end defvr
1833
1834 @defvr {Constant} time-process
1835 [SRFI-19]
1836 @c MOD srfi.19
1837 @c EN
1838 CPU time in current process.
1839 Gauche calculates this from user time and system time returned by
1840 POSIX times(3).
1841 @c JP
1842 現在のプロセスのCPU時間。
1843 Gaucheは、POSIX time(3)コールが返すユーザ時間とシステム時間の合計からこの値を
1844 計算します。
1845 @c COMMON
1846 @end defvr
1847
1848 @defvr {Constant} time-thread
1849 [SRFI-19]
1850 @c MOD srfi.19
1851 @c EN
1852 CPU time in current thread.
1853 In the current implementation, this is the same as @code{time-process}.
1854 @c JP
1855 現在のスレッドのCPU時間。
1856 現在の実装ではこれは@code{time-process}と同じです。
1857 @c COMMON
1858 @end defvr
1859
1860 @node SRFI-19 Time queries, SRFI-19 Time procedures, SRFI-19 Time types, Time data types and procedures
1861 @subsection Time queries
1862 @c NODE 時間に関する問い合わせ
1863
1864 @defun current-time :optional time-type
1865 [SRFI-19]
1866 @c MOD srfi.19
1867 @c EN
1868 Extends Gauche built-in @code{current-time} (@pxref{Time}) to take
1869 optional @var{time-type} argument to specify the desired time type.
1870 @var{time-type} must be one of the types described in @ref{SRFI-19 Time types}.
1871 @c JP
1872 Gauche組み込みの@code{current-time} (@ref{Time}参照)を拡張して、
1873 必要な時間のタイプを省略可能な引数@var{time-type}で指定できるようにしています。
1874 可能な@var{time-type}の値は@ref{SRFI-19 Time types}で説明されているものです。
1875 @c COMMON
1876 @end defun
1877
1878 @defun current-date :optional tz-offset
1879 [SRFI-19]
1880 @c MOD srfi.19
1881 @c EN
1882 Returns the current date as an instance of @code{<date>} class
1883 (@pxref{SRFI-19 Date}). If @var{tz-offset} is given, it must be
1884 an offset from UTC in number of seconds. If @var{tz-offset} is
1885 not given, returns the date in local time zone.
1886 @c JP
1887 現在の日付を@code{<date>}クラスのインスタンスとして返します(@ref{SRFI-19 Date}参照)。
1888 @var{tz-offset}が与えられた場合、それがUTCからのオフセットを表す秒数として
1889 使われます。@var{tz-offset}が与えられなかった場合はローカルタイムゾーンで
1890 表現された日付が返されます。
1891 @c COMMON
1892 @end defun
1893
1894 @defun current-julian-day
1895 [SRFI-19]
1896 @c MOD srfi.19
1897 @c EN
1898 Returns the current julian day, a point in time as a real number of
1899 days since -4714-11-24T12:00:00Z (November 24, -4714 at noon, UTC).
1900 @c JP
1901 現在のユリウス日(Julian day)を返します。Julian dayは
1902 -4714-11-24T12:00:00Z (November 24, -4714 at noon, UTC) からの日数を
1903 実数で表現したものです。
1904 @c COMMON
1905 @end defun
1906
1907 @defun current-modified-julian-day
1908 [SRFI-19]
1909 @c MOD srfi.19
1910 @c EN
1911 Returns the current modified julian day, a point in time as a real
1912 number of days since 1858-11-17T00:00:00Z
1913 (November 17, 1858 at midnight, UTC).
1914 @c JP
1915 現在の修正ユリウス日(Modified julian day)を返します。Modified julian dayは
1916 1858-11-17T00:00:00Z (November 17, 1858 at midnight, UTC)
1917 からの日数を実数で表現したものです。
1918 @c COMMON
1919 @end defun
1920
1921 @defun time-resolution :optional type
1922 [SRFI-19]
1923 @c MOD srfi.19
1924 @c EN
1925 Returns clock resolution of the time type @var{type} in nanoseconds,
1926 as an exact positive integer. If @var{type} is omitted, @code{time-utc}
1927 is assumed.
1928
1929 Note: In the current implementation, the return value isn't actual
1930 resolution, but a value that's guaranteed to be equal to or greater
1931 than the actual resolution.
1932 @c JP
1933 時間タイプ@var{type}を計測する時計の粒度を、ナノセコンド単位の正整数として返します。
1934 @var{type}が省略された場合は@code{time-utc}になります。
1935
1936 註: 現在の実装では、これは正確な粒度そのものではなく、
1937 正確な粒度と等しいかより大きい値を返します。
1938 @c COMMON
1939 @end defun
1940
1941
1942 @node SRFI-19 Time procedures, SRFI-19 Date, SRFI-19 Time queries, Time data types and procedures
1943 @subsection Time procedures
1944 @c NODE 時間に関する手続き
1945
1946 @defun make-time type nanoseconds seconds
1947 [SRFI-19]
1948 @c MOD srfi.19
1949 @c EN
1950 Returns an instance of @code{<time>} class with specified initial values.
1951 Equivalent to @code{(make <time> :type type :second seconds :nanosecond nanoseconds)}.
1952 @c JP
1953 与えられた初期値を持つ@code{<time>}クラスのインスタンスを返します。
1954 @code{(make <time> :type type :second seconds :nanosecond nanoseconds)}
1955 と等価です。
1956 @c COMMON
1957 @end defun
1958
1959 @defun time-type time
1960 @defunx time-second time
1961 @defunx time-nanosecond time
1962 @defunx set-time-type! time type
1963 @defunx set-time-second! time second
1964 @defunx set-time-nanosecond! time nanosecond
1965 [SRFI-19]
1966 @c MOD srfi.19
1967 @c EN
1968 Getter and setter of @code{<time>} object slots.
1969 @c JP
1970 @code{<time>}オブジェクトのスロットのアクセサです。
1971 @c COMMON
1972 @end defun
1973
1974 @defun copy-time time
1975 [SRFI-19]
1976 @c MOD srfi.19
1977 @c EN
1978 Returns a new instance of @code{<time>} whose content is the same as
1979 given @var{time}
1980 @c JP
1981 与えられた@var{time}と同じ内容の新しい@code{<time>}オブジェクトを返します。
1982 @c COMMON
1983 @end defun
1984
1985 @defun time=? time0 time1
1986 @defunx time<? time0 time1
1987 @defunx time<=? time0 time1
1988 @defunx time>? time0 time1
1989 @defunx time>=? time0 time1
1990 [SRFI-19]
1991 @c MOD srfi.19
1992 @c EN
1993 Compares two times. Types of both times must match.
1994 @c JP
1995 二つの時間を比較します。時間のタイプは一致していなければなりません。
1996 @c COMMON
1997 @end defun
1998
1999 @defun time-difference time0 time1
2000 @defunx time-difference! time0 time1
2001 [SRFI-19]
2002 @c MOD srfi.19
2003 @c EN
2004 Returns the difference of two times, in @code{time-duration} time.
2005 Types of both times must match.
2006 @code{Time-difference!} modifies @var{time0} to store the result.
2007 @c JP
2008 二つの時間の差を@code{time-duration}タイプの時間として返します。
2009 二つの時間のタイプは一致していなければなりません。
2010 @code{Time-difference!}は結果を格納するために@var{time0}を変更します。
2011 @c COMMON
2012 @end defun
2013
2014 @defun add-duration time0 time-duration
2015 @defunx add-duration! time0 time-duration
2016 @defunx subtract-duration time0 time-duration
2017 @defunx subtract-duration! time0 time-duration
2018 [SRFI-19]
2019 @c MOD srfi.19
2020 @c EN
2021 Adds or subtracts @var{time-duration} to or from @var{time0}.
2022 Type of returned time is the same as @var{time0}. Type of
2023 @var{time-duration} must be @code{time-duration}.
2024 @code{add-duration!} and @code{subtract-duration!} reuse
2025 @var{time0} to store the result.
2026
2027 See also @code{seconds+} (@ref{Time}).
2028 @c JP
2029 @var{time-duration}を@var{time0}に加算、または@var{time0}から減算します。
2030 返される時間のタイプは@var{time0}と同じです。@var{time-duration}のタイプは
2031 @code{time-duration}でなければなりません。
2032 @code{add-duration!}と@code{subtract-duration!}は結果を格納するのに
2033 @var{time0}を再利用します。
2034
2035 @ref{Time}の@code{seconds+}も参照してください。
2036 @c COMMON
2037 @end defun
2038
2039 @node SRFI-19 Date, SRFI-19 Date reader and writer, SRFI-19 Time procedures, Time data types and procedures
2040 @subsection Date
2041 @c NODE 日付
2042
2043 @deftp {Class} <date>
2044 @clindex date
2045 @c MOD srfi.19
2046 @c EN
2047 Represents a date.
2048 @c JP
2049 日付を表現します。
2050 @c COMMON
2051
2052 @defivar <date> nanosecond
2053 @c EN
2054 Nanosecond portion of the date by an integer between 0 and 999,999,999,
2055 inclusive.
2056 @c JP
2057 日付のナノ秒部分、0 から 999,999,999 までの整数です。
2058 @c COMMON
2059 @end defivar
2060
2061 @defivar <date> second
2062 @c EN
2063 Second portion of the date by an integer between 0 and 60, inclusive.
2064 (60 for leap second).
2065 @c JP
2066 日付の秒部分、0 から 60 までの整数です。(60 は閏秒)
2067 @c COMMON
2068 @end defivar
2069
2070 @defivar <date> minute
2071 @c EN
2072 Minute portion of the date by an integer between 0 and 59, inclusive.
2073 @c JP
2074 日付の分部分、0 から 59 までの整数です。
2075 @c COMMON
2076 @end defivar
2077
2078 @defivar <date> hour
2079 @c EN
2080 Hour portion of the date by an integer between 0 and 23, inclusive.
2081 @c JP
2082 日付の時部分、0 から 23 までの整数です。
2083 @c COMMON
2084 @end defivar
2085
2086 @defivar <date> day
2087 @c EN
2088 Day portion of the date by an integer between 0 and 31, inclusive.
2089 The actual upper bound of the day is determined by the year and the month.
2090 (Note: 1 is for the first day; 0 is allowed by the specification,
2091 but I don't see why).
2092 @c JP
2093 日付の日部分、0 から 31 日までの整数です。実際の上限は年と月によって決定
2094 されます。(註: 1 は朔日(ついたち)、0 は仕様では認められていますが、
2095 なぜなのかはわかりません。)
2096 @c COMMON
2097 @end defivar
2098
2099 @defivar <date> month
2100 @c EN
2101 Month portion of the date by an integer between 1 and 12, inclusive.
2102 1 for January, 2 for February, and so on.
2103 (Note: this is different from POSIX's @code{<sys-tm>} convention).
2104 @c JP
2105 日付の月部分、1 から 12 までの整数です。1 は一月、2 は二月、以下同様です。
2106 (註: これは POSIX の @code{<sys-tm>} の命名法とは異ります。)
2107 @c COMMON
2108 @end defivar
2109
2110 @defivar <date> year
2111 @c EN
2112 Year portion of the date.
2113 @c JP
2114 日付の年部分です。
2115 @c COMMON
2116 @end defivar
2117
2118 @defivar <date> zone-offset
2119 @c EN
2120 The number of seconds east of GMT for this timezone, by an integer.
2121 @c JP
2122 このタイムゾーンが GMT より何秒東にあるかを示す整数です。
2123 @c COMMON
2124 @end defivar
2125 @end deftp
2126
2127 @defun make-date nanosecond second minute hour day month year zone-offset
2128 [SRFI-19]
2129 @c MOD srfi.19
2130 @c EN
2131 Makes a @code{<date>} object from the given values.
2132 Note: this procedure does not check if the values are in the valid range.
2133 @c JP
2134 与えられた値から @code{<date>} オブジェクトを作成します。
2135 註: この手続きは与えられた値が正しい範囲であるかどうかをチェックしません。
2136 @c COMMON
2137 @end defun
2138
2139 @defun date? obj
2140 [SRFI-19]
2141 @c MOD srfi.19
2142 @c EN
2143 Returns true iff @var{obj} is a @code{<date>} object.
2144 @c JP
2145 @var{obj} が @code{<date>} オブジェクトである場合にかぎり真を返します。
2146 @c COMMON
2147 @end defun
2148
2149 @defun date-nanosecond date
2150 @defunx date-second date
2151 @defunx date-minute date
2152 @defunx date-hour date
2153 @defunx date-day date
2154 @defunx date-month date
2155 @defunx date-year date
2156 @defunx date-zone-offset date
2157 [SRFI-19]
2158 @c MOD srfi.19
2159 @c EN
2160 Accessors.
2161 @c JP
2162 アクセサです。
2163 @c COMMON
2164 @end defun
2165
2166 @defun date-year-day date
2167 @defunx date-week-day date
2168 @defunx date-week-number date day-of-week-starting-week
2169 [SRFI-19]
2170 @c MOD srfi.19
2171 @c EN
2172 Calculates the day number in the year (1 for January 1st),
2173 the day number in the week (0 for Sunday, 1 for Monday, ...),
2174 and the ordinal week of the year which holds this date,
2175 ignoring a first partial week, respectively.
2176
2177 @var{Day-of-week-starting-week} is the integer corresponding to
2178 the day of the week which is to be considered the first day of
2179 the week (Sunday=0, Monday=1, etc.).
2180 @c JP
2181 それぞれ、一年の何日目(一月一日が 1)か、何曜日(日曜日が 0、月曜日が 1
2182 など)か、一年のうち何週目(一年の最初の週が一週間に満たない場合はその
2183 週は無視)かを計算します。
2184 @c COMMON
2185 @end defun
2186
2187 @defun date->julian-day date
2188 @defunx date->modified-julian-day date
2189 @defunx date->time-monotonic date
2190 @defunx date->time-tai date
2191 @defunx date->time-utc date
2192 [SRFI-19]
2193 @c MOD srfi.19
2194 @c EN
2195 Conversions from date to various date/time types.
2196 @c JP
2197 日付から様々な様式の日付/時間に変換します。
2198 @c COMMON
2199 @end defun
2200
2201 @defun julian-day->date jd :optional tz-offset
2202 @defunx julian-day->time-monotonic jd
2203 @defunx julian-day->time-tai jd
2204 @defunx julian-day->time-utc jd
2205 [SRFI-19]
2206 @c MOD srfi.19
2207 @c EN
2208 Conversions from julian-day to various date/time types.
2209 @c JP
2210 ユリウス日からから様々な様式の日付/時間に変換します。
2211 @c COMMON
2212 @end defun
2213
2214 @defun modified-julian-day->date jd :optional tz-offset
2215 @defunx modified-julian-day->time-monotonic jd
2216 @defunx modified-julian-day->time-tai jd
2217 @defunx modified-julian-day->time-utc jd
2218 [SRFI-19]
2219 @c MOD srfi.19
2220 @c EN
2221 Conversions from modified julian-day to various date/time types.
2222 @c JP
2223 修正ユリウス日から様々な様式の日付/時間に変換します。
2224 @c COMMON
2225 @end defun
2226
2227 @defun time-monotonic->date time :optional tz-offset
2228 @defunx time-monotonic->julian-day time
2229 @defunx time-monotonic->modified-julian-day time
2230 @defunx time-monotonic->time-tai time
2231 @defunx time-monotonic->time-tai! time
2232 @defunx time-monotonic->time-utc time
2233 @defunx time-monotonic->time-utc! time
2234 [SRFI-19]
2235 @c MOD srfi.19
2236 @c EN
2237 Conversions from time-monotonic to various date/time types.
2238 @c JP
2239 time-monotonic形式から様々な様式の日付/時間に変換します。
2240 @c COMMON
2241 @end defun
2242
2243 @defun time-tai->date time :optional tz-offset
2244 @defunx time-tai->julian-day time
2245 @defunx time-tai->modified-julian-day time
2246 @defunx time-tai->time-monotonic time
2247 @defunx time-tai->time-monotonic! time
2248 @defunx time-tai->time-utc time
2249 @defunx time-tai->time-utc! time
2250 [SRFI-19]
2251 @c MOD srfi.19
2252 @c EN
2253 Conversions from time-tai to various date/time types.
2254 @c JP
2255 time-tai形式から様々な様式の日付/時間に変換します。
2256 @c COMMON
2257 @end defun
2258
2259 @defun time-utc->date time :optional tz-offset
2260 @defunx time-utc->julian-day time
2261 @defunx time-utc->modified-julian-day time
2262 @defunx time-utc->time-monotonic time
2263 @defunx time-utc->time-monotonic! time
2264 @defunx time-utc->time-tai time
2265 @defunx time-utc->time-tai! time
2266 [SRFI-19]
2267 @c MOD srfi.19
2268 @c EN
2269 Conversions from time-utc to various date/time types.
2270 @c JP
2271 UTC 形式から様々な様式の日付/時間に変換します。
2272 @c COMMON
2273 @end defun
2274
2275 @node SRFI-19 Date reader and writer, , SRFI-19 Date, Time data types and procedures
2276 @subsection Date reader and writer
2277 @c NODE 日付の読み書き
2278
2279 @defun date->string date :optional format-string
2280 [SRFI-19+]
2281 @c MOD srfi.19
2282 @c EN
2283 Converts a @code{<date>} object to a string, according
2284 to the format specified by @var{format-string}.
2285 If @var{format-string} is omitted, @code{"~c"} is assumed.
2286 @c JP
2287 @code{<date>}オブジェクトを文字列に変換します。書式は
2288 @var{format-string}で指定します。@var{format-string}が省略された場合に
2289 は@code{"~c"}が指定されたものとします。
2290 @c COMMON
2291
2292 @c EN
2293 A format string is copied to output, except a sequence begins with
2294 @code{~} which is replaced with the following rules:
2295 @c JP
2296 書式文字列は出力にコピーされます。ただし、@code{~}で始まる並びの部分は
2297 以下の規則にしたがって書き換えられます。
2298 @c COMMON
2299
2300 @c EN
2301 @table @code
2302 @item ~~
2303 A literal @code{~}.
2304 @item ~a
2305 Locale's abbreviated weekday name (Sun...Sat).
2306 @item ~A
2307 Locale's full weekday name (Sunday...Saturday).
2308 @item ~b
2309 Locale's abbreviate month name (Jan...Dec).
2310 @item ~B
2311 Locale's full month name (January...December).
2312 @item ~c
2313 Locale's date and time (e.g., @code{"Fri Jul 14 20:28:42-0400 2000"}).
2314 @item ~d
2315 Day of month, zero padded (01...31).
2316 @item ~D
2317 Date (mm/dd/yy).
2318 @item ~e
2319 Day of month, blank padded ( 1...31).
2320 @item ~f
2321 Seconds+fractional seconds, using locale's decimal separator (e.g. 5.2).
2322 @item ~h
2323 Same as @code{~b}.
2324 @item ~H
2325 Hour, zero padded, 24-hour clock (00...23).
2326 @item ~I
2327 Hour, zero padded, 12-hour clock (01...12).
2328 @item ~j
2329 Day of year, zero padded.
2330 @item ~k
2331 Hour, blank padded, 24-hour clock ( 0...23).
2332 @item ~l
2333 Hour, blank padded, 12-hour clock ( 1...12).
2334 @item ~m
2335 Month, zero padded (01...12).
2336 @item ~M
2337 Minute, zero padded (00...59).
2338 @item ~n
2339 New line.
2340 @item ~N
2341 Nanosecond, zero padded.
2342 @item ~p
2343 Locale's AM or PM.
2344 @item ~r
2345 Time, 12 hour clock, same as @code{"~I:~M:~S ~p"}.
2346 @item ~s
2347 Number of full seconds since "the epoch" (in UTC).
2348 @item ~S
2349 Second, zero padded (00...60).
2350 @item ~t
2351 Horizontal tab.
2352 @item ~T
2353 Time, 24 hour clock, same as @code{"~H:~M:~S"}.
2354 @item ~U
2355 Week number of year with Sunday as first day of week (00...53).
2356 @item ~V
2357 ISO8601 Week number of year with Monday as first day of week.
2358 The week with the first Thursday is week 01. If there's a partial
2359 week before that, it becomes week 52 or 53 of the preceding year
2360 (01...53).
2361 @item ~w
2362 Day of week (0...6).
2363 @item ~W
2364 Week number of year with Monday as first day of week (00...52).
2365 @item ~x
2366 Locale's date representation, for example: @code{"07/31/00"}.
2367 @item ~X
2368 Locale's time representation, for example: @code{"06:51:44"}.
2369 @item ~y
2370 Last two digits of year (00...99).
2371 @item ~Y
2372 Year.
2373 @item ~z
2374 Time zone in RFC-822 style.
2375 @c @item ~Z
2376 @c Symbol time zone (not-implemented).
2377 @item ~1
2378 ISO-8601 year-month-day format, e.g. @code{"2001-02-03"}.
2379 @item ~2
2380 ISO-8601 hour-minute-second-timezone format, e.g. @code{"04:56:12-1000"}.
2381 @item ~3
2382 ISO-8601 hour-minute-second format, e.g. @code{"04:56:12"}.
2383 @item ~4
2384 ISO-8601 year-month-day-hour-minute-second-timezone format,
2385 e.g. @code{"2001-02-03T04:56:12-1000"}.
2386 @item ~5
2387 ISO-8601 year-month-day-hour-minute-second format,
2388 e.g. @code{"2001-02-03T04:56:12"}.
2389 @end table
2390 @c JP
2391 @table @code
2392 @item ~~
2393 文字@code{~}そのもの。
2394 @item ~a
2395 ロケールによる曜日省略形(Sun...Sat)
2396 @item ~A
2397 ロケールによる曜日完全形(Sunday...Saturday)
2398 @item ~b
2399 ロケールによる月省略形(Jan...Dec)
2400 @item ~B
2401 ロケールによる月完全形(January...December)
2402 @item ~c
2403 ロケールによる日付時刻(例えば @code{"Fri Jul 14 20:28:42-0400 2000"})
2404 @item ~d
2405 月日にち、0を補填(01...31)
2406 @item ~D
2407 日付(mm/dd/yy)
2408 @item ~e
2409 月日にち、空白補填( 1...31)
2410 @item ~f
2411 秒 + 小数秒、小数点はロケールによるセパレータ(たとえば、5.2)
2412 @item ~h
2413 @code{~b} に同じ
2414 @item ~H
2415 時、0を補填、24時制(00...23)
2416 @item ~I
2417 時、0を補填、12時制(01...12)
2418 @item ~j
2419 年日にち、0補填(001...366)
2420 @item ~k
2421 時、空白補填、24時制( 0...23)
2422 @item ~l
2423 時、空白補填、12時制( 1...12)
2424 @item ~m
2425 月、0補填、(01...12)
2426 @item ~M
2427 分、0補填、(00...59)
2428 @item ~n
2429 改行
2430 @item ~N
2431 ナノ秒、0補填
2432 @item ~p
2433 ロケールによるAM、PM
2434 @item ~r
2435 時刻、12時制、@code{"~I:~M:~S ~p"}と同じ
2436 @item ~s
2437 エポックからの経過秒(UTC)
2438 @item ~S
2439 秒、0補填(00...60)
2440 @item ~t
2441 水平タブ
2442 @item ~T
2443 時刻、24時制、@code{"~H:~M:~S"}と同じ
2444 @item ~U
2445 年経過週、週は日曜はじまり(00...53)
2446 @item ~V
2447 ISO8601形式の年経過週、週は月曜はじまり。年の最初の木曜日を含む週が01となり、
2448 それ以前の週にはみ出た部分は前年の52または53週となる (01...53)
2449 @item ~w
2450 曜日を表す数字、日曜が0 (0...6)
2451 @item ~W
2452 年経過週、週は月曜日はじまり(00...52)
2453 @item ~x
2454 ロケールによる日付、例えば @code{"07/31/00"}
2455 @item ~X
2456 ロケールによる時刻、24時制、例えば @code{"06:51:44"}
2457 @item ~y
2458 西暦の下2桁(00...99)
2459 @item ~Y
2460 西暦
2461 @item ~z
2462 RFC-2822スタイルのタイムゾーン
2463 @c @item ~Z
2464 @c Symbol time zone (not-implemented).
2465 @item ~1
2466 ISO-8601 の「年-月-日」形式。例えば @code{"2001-02-03"}
2467 @item ~2
2468 ISO-8601 の「時-分-秒タイムゾーン」形式。例えば @code{"04:56:12-1000"}
2469 @item ~3
2470 ISO-8601 の「時:分:秒」形式。例えば @code{"04:56:12"}
2471 @item ~4
2472 ISO-8601 の「西暦-月-日T時:分:秒タイムゾーン」形式。
2473 例えば @code{"2001-02-03T04:56:12-1000"}
2474 @item ~5
2475 ISO-8601 の「西暦-月-日T時:分:秒」形式。
2476 例えば @code{"2001-02-03T04:56:12"}
2477 @end table
2478 @c COMMON
2479
2480 @c EN
2481 Note: currently Gauche doesn't honor process's locale setting,
2482 and it always formats the date as if the locale is "C". It may
2483 be changed in future, so you shouldn't rely on, for example,
2484 @code{~a} always formatted as "Sun".."Sat".
2485 @c JP
2486 注意:現時点でGaucheはロケールの設定には従っておらず、常にロケールが
2487 "C" に設定されているものとしてフォーマットします。これについては将来変
2488 更する可能性がありますので、現在の振舞いを前提として、たとえば、
2489 @code{~a}が常に"Sun".."Sat"のようにフォーマットされることを前提にプロ
2490 グラムしてはいけません。
2491 @c COMMON
2492
2493 @c EN
2494 There's no portable way to ensure you'll get "C" locale formats
2495 since there's no standard way to set process's locale yet.
2496 However, Gauche provides a way to ensure the locale to be "C",
2497 as an extension to srfi-19.
2498 Insert @code{@@} between @code{~} and the directive
2499 character, such as @code{~@@a}.
2500 @c JP
2501 いまのところプロセスのロケールを設定する標準的な方法がないので、
2502 "C"ロケール形式を取得できるかどうかを確かめるポータブルな方法がありま
2503 せん。とはいえ、Gaucheでは SRFI-19の拡張として"C"ロケールであることを
2504 確認する方法を提供しています。@code{@@} を @code{~} とディレクティブ文
2505 字の間に挿入し、@code{~@@a} のようにします。
2506 @c COMMON
2507 @end defun
2508
2509 @defun string->date string template-string
2510 [SRFI-19]
2511 @c MOD srfi.19
2512 @c [NB] srfi-19's string->date is broken, in both spec and reference
2513 @c implementation. I'm wondering whether I should change string->date
2514 @c to make usable, or introduce another procedure, like string->date*,
2515 @c which fixes the problem.
2516 @c
2517 @c Both procedures parse a string representation of date in @var{string},
2518 @c according to the format given in @var{template-string}.
2519
2520 @c The input string must match the @var{template-string},
2521 @c except tilde-directives described below, which matches
2522 @c one or more component(s) of the date. If the input string
2523 @c is parsed successfully, a @code{<date>} object is returned
2524 @c with the matched components are filled.
2525
2526 @c If the input string does not match @var{template-string},
2527 @c an error is signaled. (The SRFI-19 spec doesn't explicitly
2528 @c state what happens if @code{string->date} doesn't accept the
2529 @c input, which actually reduces usability of @code{string->date}
2530
2531 @c but the reference implementation signals an error, and
2532 @c it would be safe to assume
2533
2534
2535 @c @table @code
2536 @c @item ~~
2537 @c Matches literal @code{~}.
2538 @c @item ~a
2539 @c Skip to an alphanumeric character, then matches abbreviated
2540 @c weekday in locale. Match result is ignored.
2541 @c @item ~A
2542 @c Skip to an alphanumeric character, then matches full
2543 @c weekday in locale. Match result is ignored.
2544 @c @item ~b
2545 @c Skip to an alphanumeric character, then matches abbreviated
2546 @c month name in locale. Sets the month component of the date.
2547 @c @item ~B
2548 @c Skip to an alphanumeric character, then matches full
2549 @c month name in locale. Sets the month component of the date.
2550 @c @item ~d
2551 @c Skip to a numeric character, then matches the day of month.
2552 @c Sets the month component of the date.
2553 @c @item ~e
2554
2555 @c ~e any day of month, blank padded date-day
2556 @c ~h char-alphabetic? same as ~b nothing
2557 @c ~H char-numeric? hour date-hour
2558 @c ~k any hour, blank padded date-hour
2559 @c ~m char-numeric? month date-month
2560 @c ~M char-numeric? minute date-minute
2561 @c ~S char-numeric? second date-second
2562 @c ~y any 2-digit year date-year within 50 years
2563 @c ~Y char-numeric? year date-year
2564 @c ~z any time zone date-zone-offset@end table
2565
2566 @end defun
2567
2568 @c ----------------------------------------------------------------------
2569 @node Sources of random bits, Localization, Time data types and procedures, Library modules - SRFIs
2570 @section @code{srfi.27} - Sources of Random Bits
2571 @c NODE ランダムビットのソース, @code{srfi.27} - ランダムビットのソース
2572
2573 @deftp {Module} srfi.27
2574 @mdindex srfi.27
2575 @c EN
2576 This module provides SRFI-27 pseudo random generator interface,
2577 using Mersenne Twister algorithm
2578 (@pxref{Mersenne-Twister random number generator}) as the backbone.
2579 @c JP
2580 このモジュールはメルセンヌツイスタアルゴリズム
2581 (@ref{Mersenne-Twister random number generator} 参照)
2582 を基礎に用いたSRFI-27疑似乱数発生器インタフェースを提供します。
2583 @c COMMON
2584
2585 @c EN
2586 The random sources provided in this module is thread safe; multiple thread
2587 can use the same random source without breaking its internal state.
2588 @c JP
2589 このモジュールが提供する乱数発生源はスレッドセーフです。
2590 複数のスレッドが同じ乱数発生源を使っても内部状態を壊してしまうことはありません。
2591 @c COMMON
2592 @end deftp
2593
2594 @defun random-integer n
2595 [SRFI-27]
2596 @c MOD srfi.27
2597 @c EN
2598 Returns a random exact integer between [0, @var{n}-1], inclusive,
2599 using the default random source.
2600 To set a random seed for this procedure, use @code{random-source-randomize!}
2601 or @code{random-source-pseudo-randomize!} on @code{default-random-source}.
2602 @c JP
2603 デフォルトの乱数発生源を用いて、0 から @var{n}-1 までの正確な整数の乱数を
2604 返します。この手続きの乱数のシードを設定するには
2605 @code{default-random-source} に対して
2606 @code{random-source-randomize!} あるいは、
2607 @code{random-source-pseudo-randomize!} を用います。
2608 @c COMMON
2609 @end defun
2610
2611 @defun random-real
2612 [SRFI-27]
2613 @c MOD srfi.27
2614 @c EN
2615 Returns a random real number between (0, 1), exclusive,
2616 using the default random source.
2617 To set a random seed for this procedure, use @code{random-source-randomize!}
2618 or @code{random-source-pseudo-randomize!} on @code{default-random-source}.
2619 @c JP
2620 デフォルトの乱数発生源を用いて、0 より大きく、1 未満の実数乱数を返します。
2621 この手続きの乱数のシードを設定するには @code{default-random-source} に対して
2622 @code{random-source-randomize!} あるいは、
2623 @code{random-source-pseudo-randomize!} を用います。
2624 @c COMMON
2625 @end defun
2626
2627 @defvar default-random-source
2628 [SRFI-27]
2629 @c MOD srfi.27
2630 @c EN
2631 Keeps the default random source that is used by @code{random-integer}
2632 and @code{random-real}.
2633 @c JP
2634 @code{random-integer} および @code{random-real} が利用するデフォルトの
2635 乱数発生源を保持しています。
2636 @c COMMON
2637 @end defvar
2638
2639 @defun make-random-source
2640 [SRFI-27]
2641 @c MOD srfi.27
2642 @c EN
2643 Creates and returns a new random source.
2644 In the current Gauche implementation, it is just a @code{<mersenne-twister>}
2645 object. It may be changed in the future implementation.
2646 @c JP
2647 乱数の発生源を生成し返します。
2648 現在の Gauche の実装では、これは @code{<mersenne-twister>} のオブジェクトです。
2649 将来の実装では変更される可能性があります。
2650 @c COMMON
2651 @end defun
2652
2653 @defun random-source? obj
2654 [SRFI-27]
2655 @c MOD srfi.27
2656 @c EN
2657 Returns @code{#t} if @var{obj} is a random source object.
2658 @c JP
2659 @var{obj} が乱数発生源オブジェクトであれば、@code{#t} を返します。
2660 @c COMMON
2661 @end defun
2662
2663 @defun random-source-state-ref s
2664 @defunx random-source-state-set! s state
2665 [SRFI-27]
2666 @c MOD srfi.27
2667 @c EN
2668 Gets and sets the "snapshot" of the state of the random source @var{s}.
2669 @var{State} is an opaque object whose content depends on the backbone
2670 generator.
2671 @c JP
2672 乱数発生源 @var{s} の状態の「スナップショット」を獲得あるいは設定します。
2673 @var{state} は背後にある発生器に依存する内容をもつ不透明なオブジェクトです。
2674 @c COMMON
2675 @end defun
2676
2677 @defun random-source-randomize! s
2678 [SRFI-27]
2679 @c MOD srfi.27
2680 @c EN
2681 Makes an effort to set the state of the random source @var{s} to
2682 a truly random state. The current implementation uses the current
2683 time and the process ID to set the random seed.
2684 @c JP
2685 乱数発生源 @var{s} の状態を完全にランダムな状態にしようとします。
2686 現在の実装では乱数のシードを設定するのに、現在の時刻とプロセス ID を
2687 使います。
2688 @c COMMON
2689 @end defun
2690
2691 @defun random-source-pseudo-randomize! s i j
2692 [SRFI-27]
2693 @c MOD srfi.27
2694 @c EN
2695 Changes the state of the random source @var{s} into the initial state
2696 of the (@var{i}, @var{j})-th independent random source,
2697 where @var{i} and @var{j} are non-negative integers.
2698 This procedure can be used to reuse a random source @var{s} as large
2699 number of independent random source, indexed by two non-negative integers.
2700 Note that this procedure is entirely deterministic.
2701 @c JP
2702 乱数発生源 @var{s} の状態を発生源とは独立した (@var{i}, @var{j}) 番の
2703 初期状態に設定します。@var{i} および @var{j} は非負の整数です。
2704 この手続きは乱数発生源 @var{s} を二つの非負整数でインデックス付した、
2705 大規模の独立の乱数発生源として再利用するときに利用できます。
2706 この手続きは、完全な決定性があることに注意してください。
2707 @c COMMON
2708 @end defun
2709
2710 @defun random-source-make-integers s
2711 [SRFI-27]
2712 @c MOD srfi.27
2713 @c EN
2714 Returns a procedure, that takes one integer argument @var{n} and
2715 returns a random integer between 0 and @var{n}-1 inclusive for every
2716 invocation, from the random source @var{s}.
2717 @c JP
2718 呼出しのたびに乱数発生源 @var{s} より、 0 から @var{n}-1 までの整数の
2719 乱数を返す、一つの整数 @var{n} を引数としてとる手続きを、返します。
2720 @c COMMON
2721 @end defun
2722
2723 @defun random-source-make-reals s :optional unit
2724 [SRFI-27]
2725 @c MOD srfi.27
2726 @c EN
2727 Returns a procedure, that takes no argument and
2728 returns a random real between 0 and 1 exclusive for
2729 every invocation, from the random source @var{s}.
2730 If @var{unit} is given, the random real the returned procedure
2731 generates will be quantized by the given @var{unit}, where
2732 0 < @var{unit} < 1.
2733 @c JP
2734 呼出しのたびに乱数発生源 @var{s} から 0 より大きく 1 未満の実数乱数を
2735 返す、無引数の手続きを返します。
2736 @var{unit} が与えられた場合、返された手続きが生成する実数乱数は
2737 @var{unit} 単位に量子化されます。@var{unit} は、 0 より大きく 1 未満で
2738 なければなりません。
2739 @c COMMON
2740 @end defun
2741
2742 @c ----------------------------------------------------------------------
2743 @node Localization, A program argument processor, Sources of random bits, Library modules - SRFIs
2744 @section @code{srfi.29} - Localization
2745 @c NODE 地域化, @code{srfi.29} - 地域化
2746
2747 @deftp {Module} srfi.29
2748 @mdindex srfi.29
2749 @mdindex srfi.29.bundle
2750 @mdindex srfi.29.format
2751 @c EN
2752 This module implements the message localization mechanism
2753 defined in SRFI-29.
2754
2755 In fact, this module consists of two submodules,
2756 @code{srfi.29.bundle} and @code{srfi.29.format}.
2757 The module @code{srfi.29} extends both submodules.
2758 It is because srfi-29's definition of the @code{format}
2759 procedure is incompatible to Gauche's native @code{format}
2760 (thus Common Lisp's @code{format}) in the handling of
2761 @code{~@@*} directive.
2762
2763 So I splitted the module into two, @code{srfi.29.format}
2764 which contains srfi-29's @code{format}, and @code{srfi.29.bundle}
2765 which contains the rest ("bundle" API).
2766 If a program wishes a complete compatibility of
2767 srfi-29, use @code{srfi.29} module, which overrides
2768 Gauche's native @code{format}. If a program just wants
2769 srfi-29's "bundle" API, but wants to keep Gauche's @code{format},
2770 use @code{srfi.29.bundle}.
2771
2772 A localization feature is also provided by @code{text.gettext} module
2773 (@pxref{Localized messages}),
2774 which is a preferable way of message localization in Gauche.
2775 This module is provided mainly for porting code that uses
2776 srfi-29 features.
2777 @c JP
2778 このモジュールは SRFI-29 で定義されたメッセージの地域化機構を実装したものです。
2779
2780 実際には、このモジュールは2つのサブモジュール、@code{srfi.29.bundle}
2781 および @code{srfi.29.format} で構成されています。@code{srfi.29}モジュールは
2782 このふたつのモジュールをextendしています。このようにしているのは、
2783 SRFI-29 での @code{format} 手続きの定義が Gauche ネイティヴの(すなわち
2784 Common Lisp の) @code{format} とでは @code{~@@*} 指令の扱い
2785 において互換性がないからです。
2786
2787 そんなわけで、SRFI-29 の @code{format} を含む @code{srfi.29.format} と
2788 それ以外(「バンドル」API)を含む @code{srfi.29.bundle} に分離しました。
2789 プログラムを SRFI-29 と完全に互換性のあるものにしたければ、@code{srfi.29}
2790 モジュールを使って下さい。こうすると Gauche ネイティヴの
2791 @code{format} が上書きされます。SRFI-29 の「バンドル」API を使いたいだけで、
2792 Gauche の @code{format} をそのままにしておきたいなら、@code{srfi.29.bundle}
2793 を使って下さい。
2794
2795 地域化機能は @code{text.gettext} モジュールによっても提供され
2796 (@pxref{Localized messages})、Gauche でメッセージの地域化をするのなら
2797 @code{text.gettext} を使うのが好ましい方法です。@code{srfi.29} モジュールは
2798 主として SRFI-29 の機能を使っているコードをポーティングするためにあります。
2799 @c COMMON
2800 @end deftp
2801
2802 @c EN
2803 @subheading Bundle specifier
2804 @c JP
2805 @subheading バンドル指定子
2806 @c COMMON
2807
2808 @c EN
2809 A @emph{bundle specifier} is an arbitrary list of symbols,
2810 but typically it takes the form like:
2811 @c JP
2812 @emph{バンドル指定子}はシンボルを要素とする任意のリストです。しかし
2813 典型的には以下のようなフォームになります。
2814 @c COMMON
2815 @example
2816 @code{(@var{package} @var{language} @var{country} @var{details} @dots{})}
2817 @end example
2818 @c EN
2819 Where @var{package} specifies the software package,
2820 @var{language} and @var{country} specifies language and country code,
2821 and @var{details} gives other informations like encoding.
2822
2823 The values for the default bundle specifier can be obtained
2824 by the following parameters.
2825 @c JP
2826 ここで、@var{package} はソフトウェアパッケージを指定し、
2827 @var{language} および @var{country} は言語と国コードを指定、そして、
2828 @var{details} はエンコーディングのようなそのほかの情報を指定します。
2829
2830 デフォルトのバンドル指定子の値は以下のようなパラメータで取得可能です。
2831 @c COMMON
2832
2833 @deffn {Parameter} current-language
2834 @deffnx {Parameter} current-country
2835 @deffnx {Parameter} current-locale-details
2836 [SRFI-29]
2837 @c MOD srfi.29
2838 @c EN
2839 The @code{current-language} and @code{current-country} parameters
2840 keep the ISO 639-1 language code and ISO 3166-1 country code
2841 respectively, both as symbols.
2842 The @code{current-locale-details} keeps a list of auxiliary
2843 local informations, such as encodings.
2844
2845 These parameters are initialized if @code{LANG} environment
2846 variable is set in the form of @code{lang_country.encoding} format.
2847 For example, if the @code{LANG} setting is @code{ja_JP.eucJP},
2848 those parameters are @code{ja}, @code{jp}, and @code{(eucjp)},
2849 respectively. If @code{LANG} is @code{C} or undefined,
2850 the default values are @code{en}, @code{us}, and @code{()}, respectively.
2851 @c JP
2852 @code{current-language} および @code{current-country} パラメータは
2853 ISO 639-1 の言語コードと ISO 3166-1 の国コードをそれぞれシンボルで
2854 保持しています。@code{current-locale-details} はエンコーディングのような
2855 補助的な地域情報のリストを保持しています。
2856
2857 これらのパラメータは、環境変数 @code{LANG} が @code{lang_country.encoding}
2858 フォーマットの形式で設定されていれば、初期化されます。たとえば、
2859 @code{LANG} が @code{ja_JP.eucJP} に設定されていれば、それらの
2860 パラメータはそれぞれ @code{ja}、@code{jp}、@code{(eucjp)} に設定されます。
2861 @code{LANG} が @code{C} であるかあるいは定義されていなければ、
2862 デフォルト値は、それぞれ @code{en}、@code{us}、@code{()} です。
2863 @c COMMON
2864 @end deffn
2865
2866 @c EN
2867 @subheading Bundle preparation
2868 @c JP
2869 @subheading バンドル準備
2870 @c COMMON
2871
2872 @defun declare-bundle! bundle-specifier association-list
2873 [SRFI-29]
2874 @c MOD srfi.29
2875 @c EN
2876 Put the association list of template key (symbol) and the locale-specific
2877 message (string) into the bundle database, with @var{bundle-specifier}
2878 as the key.
2879 @c JP
2880 テンプレートキー(シンボル)と特定ロケールのメッセージ(文字列)の連想リストを
2881 @var{bundle-specifier} をキーとして、バンドルデータベースに入れます。
2882 @c COMMON
2883 @end defun
2884
2885 @c EN
2886 Gauche currently supports only in-memory bundle database.
2887 That is, you have to call @code{declare-bundle!} within the application
2888 in order to lookup the localized messages.
2889 @c JP
2890 Gauche は現在のところメモリ上のバンドルデータベースのみサポートしています。
2891 つまり、地域化されてメッセージを探しあてるには、そのアプリケーション内で
2892 @code{declare-bundle!} を呼ぶ必要があるということです。
2893 @c COMMON
2894
2895 @defun save-bundle! bundle-specifier
2896 @defunx load-bundle! bundle-specifier
2897 [SRFI-29]
2898 @c MOD srfi.29
2899 @c EN
2900 Since Gauche doesn't support persistent bundle database yet,
2901 these procedures does nothing and returns @code{#f}.
2902 (It is still conforming behavior of srfi-29).
2903 @c JP
2904 Gauche は今のところ永続バンドルデータベースをサポートしていないので、
2905 これらの手続きはなにもせず @code{#f} を返します
2906 (これはいまのところ srfi-29 の振舞いと適合しています)。
2907 @c COMMON
2908 @end defun
2909
2910 @c EN
2911 @subheading Retrieving localized message
2912 @c JP
2913 @subheading 地域化されたメッセージの検索
2914 @c COMMON
2915
2916 @defun localized-template package-name message-template-name
2917 [SRFI-29]
2918 @c MOD srfi.29
2919 @c EN
2920 Retrieves localized message, associated with a symbol
2921 @var{message-template-name} in the package @var{package-name}.
2922 @c JP
2923 地域化されたメッセージを検索します。当該メッセージは
2924 @var{package-name} パッケージの中で、@var{message-template-name}
2925 シンボルと関連つけられています。
2926 @c COMMON
2927 @end defun
2928
2929 @c EN
2930 @subheading Extended format procedure
2931 @c JP
2932 @subheading 拡張された format 手続き
2933 @c COMMON
2934
2935 @defun format format-string args
2936 [SRFI-29]
2937 @c MOD srfi.29
2938 @c EN
2939 SRFI-29 extends SRFI-28's @code{format} procedure spec
2940 (which supports @code{~a}, @code{~s}, @code{~%} and @code{~~} directives),
2941 in order to support argument repositioning.
2942
2943 A directive @code{~N@@*}, where N is an integer or can be omitted,
2944 causes the next directive to retrieve a value from @var{N}-th
2945 optional argument. The referenced value isn't consumed,
2946 and won't affect the processing of subsequent directives.
2947
2948 Although SRFI-28 spec is compatible to
2949 Gauche's native @code{format} (@pxref{Output}),
2950 this SRFI-29 extension isn't.
2951 Specifically, the @code{~N@@*} directive of Gauche's @code{format}
2952 changes the argument pointer to points @var{N}-th optional argument,
2953 thus it affects all the subsequent arguments.
2954
2955 Because of this incompatibility, this function is defined in
2956 a separate module, @code{srfi.29.format}. If you use @code{srfi.29},
2957 which extends @code{srfi.29.bundle} and @code{srfi.29.format},
2958 the @code{format} procedure will be overridden by srfi-29's @code{format}
2959 in your module. If you want to keep Gauche's native @code{format},
2960 use @code{srfi.29.bundle} only.
2961 @c JP
2962 SRFI-29 は SRFI-28 の @code{format} 手続きの仕様(これは @code{~a}、
2963 @code{~s}、@code{~%} および @code{~~} 指令をサポートしている)を
2964 引数再配置をサポートするために拡張しています。
2965
2966 @code{~N@@*} 指令は @var{N}-番目のオプション引数から値を引き出す次の
2967 指令の契機となります。参照された値が消費されることはありません。また、
2968 参照された値がその後につづく指令の処理に影響を与えることはありません。
2969
2970 SRFI-28 の仕様は Gauche ネイティヴの @code{format} (@pxref{Output}) と
2971 互換性がありますが、この SRFI-29 の拡張には互換性がありません。
2972 具体的には、Gauche ネイティヴの @code{format} の @code{~N@@*} 指定は
2973 引数ポインタを @var{N}-番目のオプション引数を指すように変更します。
2974 それゆえ、そのあとに続くすべての引数に影響をあたえます。
2975
2976 この非互換性があるために、この関数は、分離したモジュール
2977 @code{srfi.29.format} で定義されています。@code{srfi.29.bundle} と
2978 @code{srfi.29.format} を拡張する @code{srfi.29} を使うと、@code{format}
2979 手続きは SRFI-29 の @code{format} でそのモジュール内で上書きされます。
2980 Gauche ネイティヴの @code{format} を使いたければ、@code{srfi.29.bundle}
2981 だけを使うようにしてください。
2982 @c COMMON
2983 @end defun
2984
2985 @c ----------------------------------------------------------------------
2986 @node A program argument processor, Eager comprehensions, Localization, Library modules - SRFIs
2987 @section @code{srfi.37} - args-fold: a program argument processor
2988 @c NODE args-fold プログラム引数処理, @code{srfi.37} - args-fold プログラム引数処理
2989
2990 @deftp {Module} srfi.37
2991 @mdindex srfi.37
2992 @c EN
2993 This module implements @code{args-fold},
2994 yet another procedure to process command-line
2995 arguments, defined in SRFI-37.
2996
2997 Unlike @code{gauche.parseopt}
2998 (@pxref{Parsing command-line options}),
2999 @code{args-fold} provides functional interface, i.e.
3000 the user's states are explicitly passed via parser's argument and
3001 return values, and also follows POSIX and GNU getopt guidelines,
3002 including long options.
3003 @c JP
3004 このモジュールは、@code{args-fold} を実装しています。
3005 これは、SRFI-37で定義されている
3006 コマンドライン引数の処理をするもうひとつの手続きです。
3007
3008 @code{gauche.parseopt} (@ref{Parsing command-line options}
3009 参照) とは違って、@code{args-fold} は関数的なインタフェースです。すなわち、
3010 利用者側の状態は、パーザの引数を通じて明示的に渡され、値が返ります。
3011 また、ロングオプションを含む、POSIX および GNU の getopt のガイドラインに
3012 準拠しています。
3013 @c COMMON
3014 @end deftp
3015
3016 @defun args-fold args options unrecognized-proc operand-proc :rest seeds
3017 [SRFI-37]
3018 @c MOD srfi.37
3019 @c EN
3020 Processes program options @var{args} from left to right,
3021 according to given option specification @var{options},
3022 and two procedures @var{unrecognized-proc} and @var{operand-proc}.
3023
3024 @var{Options} is a list of option objects, explained below.
3025 Each option object keeps the name(s) of the option,
3026 a flag to specify whether the option takes
3027 an argument or not, and a procedure to process that option
3028 (we'll call it @emph{option procedure}).
3029
3030 @code{Args-fold} recognizes both single-character options (short options)
3031 and long options. A short option must begin with single hyphen
3032 (e.g. @code{-a}), while long option must begin with double hyphens
3033 (e.g. @code{--help}). Short options can be
3034 concatenated, e.g. @code{-abc} or @code{-a -b -c}.
3035 Both a short option and a long option can take
3036 required or optional arguments. Required short-option argument
3037 can appear with or without space after the option, e.g.
3038 @code{-afoo} or @code{-a foo}.
3039 Long-option argument can appear after character '@code{=}' or
3040 space, e.g. @code{--long=foo} or @code{--long foo}.
3041
3042 When @code{args-fold} encounters a command-line argument that cannot
3043 be an option argument, and doesn't begin with hyphen, the argument is
3044 treated as an @emph{operand}. @code{Args-fold} allows operands and
3045 options to be interleaved. However, if @code{args-fold} encounters
3046 '@code{--}', the rest of arguments are treated as operands,
3047 regardless of beginning with hyphen or not.
3048
3049 When the given option matches one of option object in @var{options},
3050 the option procedure is called as follows:
3051 @c JP
3052 与えられたオプション仕様 @var{options} および、ふたつの手続き
3053 @var{unrecognized-proc} と @var{operand-proc} とにしたがって、プログラム
3054 引数 @var{args} を左から右へ処理します。
3055
3056 @var{options} はオプションオブジェクトのリストで以下のようなものです。
3057 各オプションオブジェクトはオプションの名前、そのオプションが引数を
3058 とるかどうかを指定するフラグ、そのオプションを処理する手続き
3059 (今後これを @emph{オプション手続き}とよびます)を保持しています。
3060
3061 @code{args-fold} は単一文字のオプション(ショートオプション)と
3062 ロングオプションの両方を認識します。ショートオプションは単一の
3063 ハイフンで始まって(たとえば、@code{-a})いなければなりません。一方、
3064 ロングオプションは二つのハイフンで始まって(たとえば、@code{--help})
3065 いなければなりません。ショートオプションは連結することが可能で、
3066 たとえば、@code{-abc} あるいは @code{-a -b -c} と書くことができます。
3067 ショートオプション、ロングオプションはともに、必須引数あるいはオプショナル
3068 引数を取ることができます。ショートオプションの必須引数は当該オプション
3069 あとに空白なしあるいは空白をいれて指定することができます。たとえば、
3070 @code{-afoo} あるいは @code{-a foo} が可能です。ロングオプションの
3071 引数は'@code{=}'文字あるいは空白をはさみます。たとえば、
3072 @code{--long=foo} または @code{--long foo} です。
3073
3074 @code{args-fold} はオプションの引数ではなく、ハイフンで始まっていない
3075 コマンドライン引数を@emph{オペランド}としてとりあつかいます。
3076 @code{args-fold} はオペランドとオプションが交互に出現するのを許します。
3077 しかし、'@code{--}' に出逢うと、のこりは、ハイフンで始まっていようと
3078 なかろうと、オペランドとして扱われます。
3079
3080 与えられたオプションが @var{options} 内のオプションオブジェクトのひとつ
3081 にマッチすれば、オプション手続きが以下のように呼出されます。
3082 @c COMMON
3083
3084 @example
3085 (@var{option-proc} @var{option} @var{name} @var{arg} @var{seed} @dots{})
3086 @end example
3087
3088 @c EN
3089 where @var{option} is the matched option object, @var{name} is
3090 the string actually used to specify the option, @var{arg} is
3091 the option argument (or @code{#f} if there's none), and
3092 @var{seed} @dots{} is the user's state information.
3093 @var{Option-proc} must return as many arguments as @var{seed}s.
3094
3095 When @code{args-fold} encounters an option that doesn't match
3096 any of the option objects, it creates a new option object
3097 for the option and calls @var{unrecognized-proc}
3098 with the same arguments as @var{option-proc}.
3099
3100 When @code{args-fold} finds an operand, @var{operand-proc}
3101 is called as follows:
3102 @c JP
3103 ここで、@var{option} はマッチしたオプションオブジェクトで、@var{name}
3104 は実際にオプションを指定するのに使われた文字列、@var{arg} はそのオプション
3105 の引数(あるいは存在しなければ、@code{#f})、そして @var{seed} @dots{} は
3106 利用者側の状態情報です。@var{option-proc} は @var{seed} と同じ数だけ
3107 値を返さなければなりません。
3108
3109 @code{args-fold} がオペランドを見つけたら、@var{operand-proc} が
3110 以下のように呼出されます。
3111 @c COMMON
3112
3113 @example
3114 (@var{operand-proc} @var{operand} @var{seed} @dots{})
3115 @end example
3116
3117 @c EN
3118 @var{Operand-proc} must return as many arguments as @var{seed}s.
3119
3120 The caller's state should be explicitly passed around seed arguments
3121 and return values. The initial seed values are @var{seed}s given
3122 to @code{args-fold}. The values returned from option procedure,
3123 @var{unrecognized-proc} and @var{operand-proc} are used as the seed
3124 arguments of next invocation of those procedures. The values
3125 returned from the last call to the procedures are returned
3126 from @code{args-fold}.
3127 @c JP
3128 @var{operand-proc} は @var{seed} と同じ数だけ
3129 値を返さなければなりません。
3130
3131 呼出し側の状態は明示的にシード引数で渡され、戻されます。初期のシード値は
3132 @code{args-fold} に与えた @var{seed} です。この値は、オプション手続き
3133 @var{unrecognized-proc} と @var{operand-proc} によって戻され、
3134 次にこれらのオプション手続きの呼出し時にシード引数として使われます。
3135 これらの手続きの最後の呼出しから返されたこの値は @code{args-fold} によって
3136 返されます。
3137 @c COMMON
3138 @end defun
3139
3140 @defun option names require-arg? optional-arg? processor
3141 [SRFI-37]
3142 @c MOD srfi.37
3143 @c EN
3144 Creates an option object with the passed properties.
3145
3146 @var{Names} is a list of characters and/or strings.
3147 A character is used for a short option, and a string is used
3148 for a long option.
3149
3150 Two flags, @var{require-arg?} and @var{optional-arg?}
3151 indicates whether the option should take an option argument,
3152 or may take an option argument.
3153
3154 @var{Processor} is the option processor procedure.
3155
3156 Note that, if an option argument is passed using '@code{=}'
3157 character, it is passed to the option procedure even if
3158 the option has @code{#f} in both @var{require-arg?}
3159 and @var{optional-arg?}. It is up to the option procedure
3160 to deal with the argument.
3161
3162 It should also be noted that the optional option argument
3163 for a short option is only recognized if it is given
3164 without whitespace after the short option. That is, if
3165 a short option '@code{d}' is marked to take optional option argument,
3166 then '@code{-dfoo}' is interpreted as '@code{-d}' with argument '@code{foo}',
3167 but '@code{-d foo}' is interpreted as '@code{-d}' without argument
3168 and an operand @code{foo}. If '@code{d}' is marked to
3169 take required option argument, however, both are interpreted
3170 as '@code{-d}' with argument '@code{foo}'.
3171 @c JP
3172 渡されたプロパティでオプションオブジェクトを作成します。
3173
3174 @var{names} は文字と(あるいは)文字列のリストです。文字はショートオプションに
3175 使い、文字列はロングオプションに使います。
3176
3177 ふたつのフラグ @var{require-arg?} と @var{optional-arg?} はオプションが
3178 必須引数をとるか、あるいは、オプショナル引数をとるかを示します。
3179
3180 @var{processor} はそのオプションの処理をする手続きです。
3181
3182 オプションの引数が '@code{=}' つきで渡された場合には、
3183 たとえ @var{require-arg?}、@var{optional-arg?} がともに @code{#f}
3184 であっても、そのオプションの引数はオプション処理手続きに渡されることに
3185 注意してください。オプション手続きにその引数を処理させようとします。
3186
3187 ショートオプションに対するオプショナルなオプションの引数は、オプションに
3188 つづいてスペースなしで指定されたときにだけ認識されることにも
3189 注意してください。たとえば、ショートオプション @code{d} がオプショナル
3190 引数をもつことになっているとき、'@code{-dfoo}' は '@code{-d}' が引数
3191 '@code{foo}' をもつと解釈されますが、'@code{-d foo}' は引数なしの
3192 '@code{-d}' とオペランド '@code{foo}' と解釈されてしまいます。もし、
3193 '@code{-d}' が必須引数をもつと設定されているなら、両方ともに
3194 '@code{-dfoo}' は '@code{-d}' が引数 '@code{foo}' をもつと解釈されます。
3195 @c COMMON
3196 @end defun
3197
3198 @defun option? obj
3199 [SRFI-37]
3200 @c MOD srfi.37
3201 @c EN
3202 Returns @code{#t} if @var{obj} is an option object,
3203 @code{#f} otherwise.
3204 @c JP
3205 @var{obj} がオプションオブジェクトなら @code{#t} を返し、
3206 そうでなければ、@code{#f} を返します。
3207 @c COMMON
3208 @end defun
3209
3210 @defun option-names option
3211 @defunx option-required-arg? option
3212 @defunx option-optional-arg? option
3213 @defunx option-processor
3214 [SRFI-37]
3215 @c MOD srfi.37
3216 @c EN
3217 Returns the properties of an option object @var{option}.
3218 @c JP
3219 オプションオブジェクト @var{option} のプロパティを返します。
3220 @c COMMON
3221 @end defun
3222
3223 @c EN
3224 A simple example:
3225 @c JP
3226 簡単な例:
3227 @c COMMON
3228
3229 @example
3230 (use srfi.37)
3231
3232 (define options
3233 (list (option '(#\d "debug") #f #t
3234 (lambda (option name arg debug batch paths files)
3235 (values (or arg "2") batch paths files)))
3236 (option '(#\b "batch") #f #f
3237 (lambda (option name arg debug batch paths files)
3238 (values debug #t paths files)))
3239 (option '(#\I "include") #t #f
3240 (lambda (option name arg debug batch paths files)
3241 (values debug batch (cons arg paths) files)))))
3242
3243 (define (main args)
3244 (receive (debug-level batch-mode include-paths files)
3245 (args-fold (cdr args)
3246 options
3247 (lambda (option name arg . seeds) ; unrecognized
3248 (error "Unrecognized option:" name))
3249 (lambda (operand debug batch paths files) ; operand
3250 (values debug batch paths (cons operand files)))
3251 0 ; default value of debug level
3252 #f ; default value of batch mode
3253 '() ; initial value of include paths
3254 '() ; initial value of files
3255 )
3256 (print "debug level = " debug-level)
3257 (print "batch mode = " batch-mode)
3258 (print "include paths = " (reverse include-paths))
3259 (print "files = " (reverse files))
3260 0))
3261 @end example
3262
3263 @c ----------------------------------------------------------------------
3264 @node Eager comprehensions, Vector library (Legacy), A program argument processor, Library modules - SRFIs
3265 @section @code{srfi.42} - Eager comprehensions
3266 @c NODE 先行評価的内包表記, @code{srfi.42} - 先行評価的内包表記
3267
3268 @deftp {Module} srfi.42
3269 @mdindex srfi.42
3270 @c EN
3271 This module provides a generic comprehension mechanism, which some other
3272 languages (e.g. Haskell and Python) offer as a built-in mechanism.
3273 It provides a rich set of operators so it can be used not only as a list
3274 generator but as a generic loop construct (actually, some may say
3275 it is as powerful/evil as Common Lisp's @emph{loop} macro).
3276 @c JP
3277 このモジュールはジェネリックな内包表記(comprehension)機構を提供します。
3278 この機構は他の言語(Haskell、Pythonなど)では組み込みの機構になっていま
3279 す。この機構は豊富な操作手続を提供しているので、リストジェネレータとい
3280 うだけではなく、ジェネリックなループ構文(Common Lisp の @emph{loop} マ
3281 クロ並みに強力/邪悪だという人もいます)を提供しています。
3282 @c COMMON
3283
3284 @c EN
3285 It runs eagerly as the name suggests, that is, if it generates a list, it
3286 creates the entire list when evaluated, instead of generate the
3287 elements @emph{on demand}. Thus it can't represent an infinite
3288 sequence, which Haskell's comprehension naturally does. Gauche offers
3289 a few alternatives to deal with lazy, possibly infinite, sequences:
3290 See @ref{Lazy sequences}, @ref{Generators} and @ref{Stream library}.
3291 @c JP
3292 この機構は名前の通り、先行評価的に走ります。すなわち、リストを生成する場合、評価時
3293 にすべてのリストを生成します。要素を@emph{要求駆動的}に生成するわけで
3294 はありません。それゆえ、無限列を表現することはできません。それが自然に
3295 できる Haskell とは違います。Gaucheは、遅延生成される有限/無限列を
3296 扱う方法を他にいくつか提供しています。
3297 @ref{Lazy sequences}、@ref{Generators}、@ref{Stream library}を
3298 参照してください。
3299 @c COMMON
3300 @end deftp
3301
3302 @c EN
3303 @subheading Eager comprehension examples
3304 @c JP
3305 @subheading 先行評価的内包表記の例
3306 @c COMMON
3307
3308 @c EN
3309 Let's begin with some examples.
3310 @c JP
3311 いくつかの例からはじめましょう。
3312 @c COMMON
3313
3314 @c EN
3315 Generate a list of squares for the first five integers:
3316 @c JP
3317 5番目までの整数の自乗のリストを生成しましょう。
3318 @c COMMON
3319 @example
3320 (list-ec (: i 5) (* i i)) @result{} (0 1 4 9 16)
3321 @end example
3322
3323 @c EN
3324 @code{list-ec} is a comprehension macro that generates a list.
3325 The first form @code{(: i 5)} is called a @var{qualifier}, which
3326 specifies a set of values to repeat over (here it is each integer
3327 from 0 below 5).
3328 The last form
3329 @code{(* i i)} is called a @var{body}, which is an ordinary Scheme expression
3330 evaluated for each values generated by the @var{qualifier}.
3331 @c JP
3332 @code{list-ec}はリストを生成する内包表記マクロです。
3333 最初のフォーム@code{(: i 5)}は@var{qualifier}と呼ばれ、
3334 繰り返しを行う値の集合を指定します (この例では0以上5未満の整数)。
3335 最後のフォーム@code{(* i i)}は@var{body}と呼ばれ、
3336 @var{qualifier}によって生成される値それぞれにつき評価される通常のScheme式です。
3337 @c COMMON
3338
3339 @c EN
3340 A comprehension can have more than one qualifiers.
3341 Next example generate set of pair of numbers @code{(x y)}, where @code{x}
3342 is between 2 (inclusive) and 5 (exclusive),
3343 and @code{y} is between 1 (inclusive) and x (exclusive).
3344 @c JP
3345 内包表記は複数のqualifierを持つことができます。
3346 次の例は数の対@code{(x y)}の集合を生成します。ここで@code{x}は
3347 2以上 5未満、@code{y}は1以上 x 未満です。
3348 @c COMMON
3349
3350 @example
3351 (list-ec (: x 2 5) (: y 1 x) (list x y))
3352 @result{} ((2 1) (3 1) (3 2) (4 1) (4 2) (4 3))
3353 @end example
3354
3355 @c EN
3356 The qualifiers works as @emph{nested}; that is, @code{(: x 2 5)}
3357 specifies to repeat the rest of the clauses---@code{(: y 1 x)} and
3358 @code{(list x y)}.
3359 @c JP
3360 複数のqualifierはネストするように動作します。つまり、@code{(: x 2 5)}は
3361 残りの節---@code{(: y 1 x)} および @code{(list x y)} を繰り返すように
3362 指定しているということです。
3363 @c COMMON
3364
3365 @c EN
3366 The above two examples can be written in Haskell as the followings:
3367 @c JP
3368 上の2つの例はHaskellで書くと以下のようになります。
3369 @c COMMON
3370
3371 @example
3372 [ i*i | i <- [0..4] ]
3373 [ (x,y) | x <- [2..4], y <- [1..x-1] ]
3374 @end example
3375
3376 @c EN
3377 Note the differences: (1) In Haskell, the body expression to yield the
3378 elements comes first, followed by qualifiers (selectors). In SRFI-42, the body
3379 expression comes last. (2) In SRFI-42, range operator's lower bound
3380 is inclusive but its upper bound is exclusive.
3381 @c JP
3382 違いに注意:(1) Haskellでは要素になる本体部が先にきて、そのあとに修飾
3383 部(セレクタ)がきます。SRFI-42では本体部は最後になります。(2) SRFI-42で
3384 は範囲指定の下限はそれを含み、上限はそれを含みません。
3385 @c COMMON
3386
3387 @c EN
3388 List a set of numbers @code{(a b c d)}, where @code{a^3+b^3 = c^3+d^3}:
3389 @c JP
3390 @code{a^3+b^3 = c^3+d^3}を満すような数字の集合@code{(a b c d)}を列挙し
3391 ましょう。
3392 @c COMMON
3393 @example
3394 (define (taxi-number n)
3395 (list-ec (: a 1 n)
3396 (: b (+ a 1) n)
3397 (: c (+ a 1) b)
3398 (: d (+ c 1) b)
3399 (if (= (+ (expt a 3) (expt b 3))
3400 (+ (expt c 3) (expt d 3))))
3401 (list a b c d)))
3402 @end example
3403
3404 @c EN
3405 If you want to change values of more than one variable
3406 simultaneously, instead of nesting, you can bundle the qualifiers
3407 like this:
3408 @c JP
3409 複数の変数を(ネストするのではなく)同時に変化させたい場合は、
3410 複数のqualifierを次のようにまとめることができます。
3411 @c COMMON
3412
3413 @example
3414 (list-ec (:parallel (: x '(a b c d)) (: y '(1 2 3 4)))
3415 (list x y))
3416 @result{} ((a 1) (b 2) (c 3) (d 4))
3417 @end example
3418
3419 @c EN
3420 You can generate not only a list, but other sequences:
3421 @c JP
3422 リストだけではなく、他のシーケンスも生成できます。
3423 @c COMMON
3424 @example
3425 (vector-ec (: i 5) i) @result{} #(0 1 2 3 4)
3426 (string-ec (: i 5) (integer->char (+ i 65))) @result{} "ABCDE"
3427 @end example
3428
3429 @c EN
3430 Or apply folding operations:
3431 @example
3432 (sum-ec (: i 1 100) i)
3433 @result{} 4950 ;; sum of integers from 1 below 100.
3434 (product-ec (: i 1 10) i)
3435 @result{} 362880 ;; ... and product of them.
3436 @end example
3437 @c JP
3438 畳み込み演算も適用できます。
3439 @example
3440 (sum-ec (: i 1 100) i)
3441 @result{} 4950 ;; 1以上100未満の整数の和
3442 (product-ec (: i 1 10) i)
3443 @result{} 362880 ;; 1以上10未満の整数の積
3444 @end example
3445 @c COMMON
3446
3447 @c EN
3448 @subheading Comprehension macros
3449 @c JP
3450 @subheading 内包表記マクロ
3451 @c COMMON
3452
3453 @c EN
3454 Each comprehension takes the following form.
3455 @c JP
3456 それぞれの内包表記は以下のような形式になります。
3457 @c COMMON
3458 @example
3459 (@var{comprehension-macro} @var{qualifier} @dots{} @var{body})
3460 @end example
3461
3462 @c EN
3463 It evaluates @var{body} repeatedly as specified by @var{qualifier} @dots{}.
3464 Depending on the type of comprehension,
3465 the results of @var{body} may be either collected to create an
3466 aggregate (list, vector, string, ...), folded by some operator
3467 (sum, product, min, max, ...), or simply discarded.
3468 @c JP
3469 @var{qualifier} @dots{}の指定に従って@var{body}をくりかえし評価します。内包表記の種類
3470 によって、@var{body}の結果は(リスト、ベクタ、文字列などに)集約されるか、
3471 (sum、product、min、maxなどによって)畳み込まれるか、あるいは、単に捨て
3472 られます。
3473 @c COMMON
3474
3475 @c EN
3476 Each @var{qualifier} specifies how to repeat the following
3477 @var{qualifiers} and @var{body}. A @var{qualifier} can be a
3478 generational qualifier that yields a set of values to loop
3479 over, or a control qualifier that specify a condition
3480 to exclude some values. See the Qualifiers heading below.
3481 @c JP
3482 それぞれの@var{qualifier}は、それ以降の@var{qualifier}と@var{body}
3483 をどのように繰り返すかを指定します。@var{qualifier}には、繰り返しに
3484 使う値を生成する生成的@var{qualifier}と、条件によって値を繰り返しから
3485 省く制御的@var{qualifier}があります。以下のQualifiersの節を参照してください。
3486 @c COMMON
3487
3488 @c EN
3489 A few comprehensions takes extra values before @var{qualifiers} or
3490 after @var{body}.
3491 @c JP
3492 いくつかの内包表記では、追加の値が@var{qualifiers}の前か、@var{body}
3493 の後に置かれます。
3494 @c COMMON
3495
3496 @defmac do-ec qualifier @dots{} body
3497 [SRFI-42]
3498 @c MOD srfi.42
3499 @c EN
3500 Repeats @var{body}. The results of @var{body} is discarded.
3501 This is for side-effecting operations.
3502 @c JP
3503 @var{body}を繰り返します。@var{body}の返り値は捨てられます。
3504 この形式は副作用目的で使います。
3505 @c COMMON
3506 @end defmac
3507
3508 @defmac list-ec qualifier @dots{} body
3509 [SRFI-42]
3510 @c MOD srfi.42
3511 @c EN
3512 Repeats @var{body} and collects the results into a list.
3513 @c JP
3514 @var{body}を繰り返し、結果をリストに集めて返します。
3515 @c COMMON
3516 @end defmac
3517
3518 @defmac append-ec qualifier @dots{} body
3519 [SRFI-42]
3520 @c MOD srfi.42
3521 @c EN
3522 Repeats @var{body}, which must yield a list.
3523 Returns a list which is the concatenation of all lists returned by @var{body}.
3524 @c JP
3525 @var{body}を繰り返し、その結果のリストを結合して返します。
3526 @var{body}は必ずリストを返さなければなりません。
3527 @c COMMON
3528 @end defmac
3529
3530 @defmac string-ec qualifier @dots{} body
3531 @defmacx string-append-ec qualifier @dots{} body
3532 [SRFI-42]
3533 @c MOD srfi.42
3534 @c EN
3535 Repeats @var{body}, which must yield a character (in @code{string-ec})
3536 or a string (in @code{string-append-ec}). Returns a string that
3537 consists of the results of @var{body}.
3538 @c JP
3539 @var{body}を繰り返します。@var{body}は@code{string-ec}では文字へ、
3540 @code{string-append-ec}では文字列へと評価されなければなりません。
3541 結果を集め、または結合した文字列が買えされます。
3542 @c COMMON
3543 @end defmac
3544
3545 @defmac vector-ec qualifier @dots{} body
3546 [SRFI-42]
3547 @c MOD srfi.42
3548 @c EN
3549 Repeats @var{body} and collects the results into a vector.
3550 @c JP
3551 @var{body}を繰り返し、結果をベクタに集めて返します。
3552 @c COMMON
3553 @end defmac
3554
3555 @defmac vector-of-length-ec k qualifier @dots{} body
3556 [SRFI-42]
3557 @c MOD srfi.42
3558 @c EN
3559 This is like @code{vector-ec}, except that the length of the
3560 result vector is known to be @var{k}. It can be more efficient
3561 than @code{vector-ec}. Unless the comprehension repeats exactly
3562 @var{k} times, an error is signaled.
3563 @c JP
3564 @code{vector-ec}と似ていますが、最終的なベクタの長さが@var{k}と分かっている時に
3565 使えます。あらかじめベクタをアロケートしておけるので@code{vector-ec}より効率が良いです。
3566 繰り返しが正確に@var{k}回にならなかった場合はエラーが投げられます。
3567 @c COMMON
3568 @end defmac
3569
3570 @defmac sum-ec qualifier @dots{} body
3571 @defmacx product-ec qualifier @dots{} body
3572 [SRFI-42]
3573 @c MOD srfi.42
3574 @c EN
3575 @var{body} must yield a numeric value. Returns sum of and product of
3576 the results, respectively.
3577 @c JP
3578 @var{body}は数値を生成しなければなりません。繰り返しによって生成される数値の和と積を
3579 それぞれ返します。
3580 @c COMMON
3581 @end defmac
3582
3583 @defmac min-ec qualifier @dots{} body
3584 @defmacx max-ec qualifier @dots{} body
3585 [SRFI-42]
3586 @c MOD srfi.42
3587 @c EN
3588 @var{body} must yield a real number. Returns maximum and minimum value
3589 of the results, respectively. @var{body} must be evaluated at least once,
3590 or an error is signaled.
3591 @c JP
3592 @var{body}は実数値を生成しなければなりません。
3593 最初および最大の結果をそれぞれ返します。@var{body}は最低1回は実行されねばならず、
3594 そうでなければエラーが投げられます。
3595 @c COMMON
3596 @end defmac
3597
3598 @defmac any?-ec qualifier @dots{} test
3599 @defmacx every?-ec qualifier @dots{} test
3600 [SRFI-42]
3601 @c MOD srfi.42
3602 @c EN
3603 Evaluates @var{test} for each iteration, and returns
3604 @code{#t} as soon as it yields non-@code{#f} (for @code{any?-ec}),
3605 or returns @code{#f} as soon as it yields @code{#f} (for @code{every?-ec}).
3606 Unlink the comprehensions introduced above, these stop evaluating
3607 @var{test} as soon as the condition meets.
3608 If the qualifiers makes no iteration, @code{#f} and @code{#t} are
3609 returned, respectively.
3610 @c JP
3611 繰り返しのたびに@var{test}を評価し、@code{any?-ec}では@var{test}が偽でない
3612 値を返したら直ちにその値を、@code{every?-ec}では@var{test}が偽を返したら
3613 直ちに@code{#f}を、それぞれ返します。これまで上で説明してきた
3614 内包表記とは異なり、これらは@var{test}が条件を満たしたら繰り返しを打ち切ります。
3615 もし繰り返しが一度もなされなかった場合、それぞれ@code{#f}と@code{#t}が戻り値となります。
3616 @c COMMON
3617 @end defmac
3618
3619 @defmac first-ec default qualifier @dots{} body
3620 @defmacx last-ec default qualifier @dots{} body
3621 [SRFI-42]
3622 @c MOD srfi.42
3623 @c EN
3624 First initializes the result by the value of the expression @var{default},
3625 then start iteration, and returns the value of the first and last
3626 evaluation of @var{body}, respectively. In fact, @code{first-ec}
3627 only evaluates @var{body} at most once.
3628 @c JP
3629 まず結果を@var{default}式の値で初期化し、繰り返しを開始します。
3630 そして、最初または最後の@var{body}の値をそれぞれ返します。
3631 実際のところ、@code{first-ec}は@var{body}をたかだか一回しか評価しません。
3632 @c COMMON
3633
3634 @c EN
3635 These forms are most useful when used with control qualifiers.
3636 For example, the following @code{first-ec} returns the @emph{first}
3637 set of distinct integers (@var{x}, @var{y}, @var{z}),
3638 where @var{x}*@var{x}+@var{y}*@var{y}+@var{z}*@var{z} becomes a square
3639 of another integer @var{w}.
3640 @c JP
3641 これらのフォームは、フロー制御のqualifierと一緒に使うことで効果を発揮します。
3642 例えば、下の@code{first-ec}は、それぞれ異なる3つの正整数(@var{x}, @var{y}, @var{z})で、
3643 @var{x}*@var{x}+@var{y}*@var{y}+@var{z}*@var{z}が@var{w}の平方と等しくなるような
3644 組み合わせのうち最初のものを返します。
3645 @c COMMON
3646
3647 @example
3648 (first-ec #f (:integers w) (: z 1 w) (: y 1 z) (: x 1 y)
3649 (if (= (* w w) (+ (* x x) (* y y) (* z z))))
3650 (list x y z w))
3651 @end example
3652
3653 @c EN
3654 Note that the first qualifier, @code{(:integers w)}, generates
3655 infinite number of integers; if you use @code{list-ec} instead of
3656 @code{first-ec} it won't stop.
3657 @c JP
3658 @code{(:integers w)}は無限に整数列を生成することに注意してください。
3659 @code{first-ec}のかわりに@code{list-ec}を使うと、評価は終了しません。
3660 @c COMMON
3661 @end defmac
3662
3663 @defmac fold-ec seed qualifier @dots{} expr proc
3664 @defmacx fold3-ec seed qualifier @dots{} expr init proc
3665 [SRFI-42]
3666 @c MOD srfi.42
3667 @c EN
3668 Reduces the values produced by @var{expr}.
3669 @c JP
3670 @var{expr}が生成する値をまとめます。
3671 @c COMMON
3672
3673 @c EN
3674 Suppose @var{expr} produces a sequence of values
3675 @var{x0}, @var{x1}, @dots{}, @var{xN}. @code{Fold-ec}
3676 calculates the following value:
3677 @c JP
3678 @var{expr}が生成する値を@var{x0}, @var{x1}, @dots{}, @var{xN}とした場合、
3679 @code{fold-ec}は次の値を計算します:
3680 @c COMMON
3681
3682 @example
3683 (@var{proc} @var{xN} (@dots{}(@var{proc} @var{x1} (@var{proc} @var{x0} @var{seed}))@dots{}))
3684 @end example
3685
3686 @c EN
3687 It's similar to @code{fold}, except that @var{proc} is evaluated
3688 within the scope of @var{qualifier} @dots{} so you can refer to the
3689 variables introduced by them. On the other hand,
3690 @var{seed} is outside of the scope of @var{qualifier}s.
3691 @c JP
3692 @code{fold}と似ていますが、@var{proc}は@var{qualifier} @dots{}のスコープ内で
3693 評価されるので、それらが導入する変数を参照することができます。
3694 ただし@var{seed}は@var{qualifier}のスコープの外で評価されます。
3695 @c COMMON
3696
3697 @c EN
3698 @code{Fold-ec3} is almost the same but the initial value calculation.
3699 In @code{fold-ec3}, @var{seed} is only used when @var{qualifier}s
3700 makes no iteration. Otherwise it calculates the following value:
3701 @c JP
3702 @code{fold-ec3}は初期値の計算以外は同じです。
3703 @code{fold-ec3}では、@var{seed}は@var{qualifier}が一度も繰り返しを行わなかった
3704 場合にのみ使われます。そうでなければ以下の値が計算されます:
3705 @c COMMON
3706
3707 @example
3708 (@var{proc} @var{xN} (@dots{}(@var{proc} @var{x1} (@var{init} @var{x0}))@dots{}))
3709 @end example
3710
3711 @end defmac
3712
3713 @subheading Qualifiers
3714
3715 @c EN
3716 @subsubheading Generational qualifiers
3717 @c JP
3718 @subsubheading 生成的qualifier
3719 @c COMMON
3720
3721 @c EN
3722 This type of qualifiers generates (possibly infinite) values
3723 over which the rest of clauses iterate.
3724 @c JP
3725 このタイプのqualifierは、いくつかの値(無限個のこともあります)を次々に
3726 生成し、各値について残りの節を繰り返します。
3727 @c COMMON
3728
3729 @c EN
3730 In the following descriptions, @var{vars} refers to either
3731 a single identifier, or a series of identifier and a form
3732 @code{(index @var{identifier2})}. The single identifier
3733 in the former case and the first identifier in the latter case
3734 name the variable to which each generated value is bound.
3735 The @var{identifier2} in the latter case names a variable
3736 to which a series of integers, increasing with each generated
3737 element, is bound. See the following example:
3738 @c JP
3739 以下の説明において、@var{vars}というのはひとつの識別子か、
3740 識別子とフォーム@code{(index @var{identifier2})}の並びです。
3741 最初の形式での識別子、あるいは二番目の形式での最初の識別子は、
3742 生成された値が束縛される変数です。二番目の形式の@var{identifier2}は、
3743 0から始まり値が生成されるたびにインクリメントされる整数値が束縛されます。
3744 次の例を見てください。
3745 @c COMMON
3746
3747 @example
3748 (list-ec (: x '(a b c)) x)
3749 @result{} (a b c)
3750 (list-ec (: x (index y) '(a b c)) (cons x y))
3751 @result{} ((a . 0) (b . 1) (c . 2))
3752 @end example
3753
3754 @deffn {EC Qualifier} : vars arg1 args @dots{}
3755 @c EN
3756 A generic dispatcher of generational qualifiers.
3757 An appropriate generational qualifier is selected based on the
3758 types of @var{arg1} @var{args} @dots{}.
3759 @c JP
3760 @var{arg1} @var{args} @dots{} の型に基づいて、以下の生成的qualifierの
3761 いずれかにディスパッチされる、汎用的なqualifierです。
3762 @c COMMON
3763 @end deffn
3764
3765 @deffn {EC Qualifier} :list vars arg1 args @dots{}
3766 @deffnx {EC Qualifier} :vector vars arg1 args @dots{}
3767 @deffnx {EC Qualifier} :uvector vars arg1 args @dots{}
3768 @deffnx {EC Qualifier} :string vars arg1 args @dots{}
3769 @c EN
3770 @var{Arg1} @var{args} @dots{} should be all lists, vectors, uniform vectors
3771 or strings,
3772 respectively. Repeats the subsequent clauses while binding
3773 each element from those args bound to @var{vars}.
3774 (The @code{:uvector} qualifier is Gauche's extension.)
3775 @c JP
3776 それぞれのフォームにおいて、
3777 @var{arg1} @var{args} @dots{}は全てリスト、ベクタ、ユニフォームベクタ、
3778 あるいは文字列でなければなりません。
3779 各要素を@var{vars}に束縛して続く節を繰り返します。
3780 (@code{:uvector}はGaucheの独自拡張です。)
3781 @c COMMON
3782
3783 @example
3784 (list-ec (:string c "ab" "cd") c) @result{} (#\a #\b #\c #\d)
3785 @end example
3786
3787 @c EN
3788 If the arguments given to the generic qualifier @code{:} are
3789 all lists, vectors, uniform vectors or strings, then these qualifiers are used.
3790 @c JP
3791 汎用qualifier@code{:}に渡された引数が全てリスト、ベクタ、ユニフォームベクタあるいは文字列
3792 であった場合は、これらのqualifierが使われます。
3793 @c COMMON
3794 @end deffn
3795
3796 @deffn {EC Qualifier} :integers vars
3797 @c EN
3798 Generates infinite series of increasing integers, starting from 0.
3799 @c JP
3800 0から始まり1づつ増加しつづける無限正確整数列を生成します。
3801 @c COMMON
3802 @end deffn
3803
3804 @deffn {EC Qualifier} :range vars stop
3805 @deffnx {EC Qualifier} :range vars start stop
3806 @deffnx {EC Qualifier} :range vars start stop step
3807 @deffnx {EC Qualifiter} :range vars range
3808 @c EN
3809 The first three forms
3810 generates a series of exact integers, starting from
3811 @var{start} (defaults to 0) and stops below @var{stop},
3812 stepping by @var{step} (defaults to 1). Giving a negative
3813 integer to @var{step} makes a decreasing series.
3814 @c JP
3815 最初の3つの形式は、
3816 @var{start}から始まり、@var{step}づつ増加し、@var{stop}を越えないような
3817 正確な整数列を生成します。@var{start}が省略された場合は0、
3818 @var{step}が省略された場合は1が使われます。
3819 @var{step}に負数を与えれば減少列も作れます。
3820 @c COMMON
3821
3822 @example
3823 (list-ec (:range v 5) v) @result{} (0 1 2 3 4)
3824 (list-ec (:range v 3 8) v) @result{} (3 4 5 6 7)
3825 (list-ec (:range v 1 8 2) v) @result{} (1 3 5 7)
3826 (list-ec (:range v 8 1 -2) v) @result{} (8 6 4 2)
3827 @end example
3828
3829 @c EN
3830 If one, two or three exact integer(s) is/are given to the generic
3831 qualifier @code{:}, this qualifier is used.
3832 @c JP
3833 汎用qualifier@code{:}に1個から3個の正確な整数が与えられた場合は、
3834 このqualifierが使われます。
3835 @c COMMON
3836
3837 @c EN
3838 If a range object (@pxref{Range}) is given to this qualifier,
3839 as in the fourth form,
3840 this generates each element in the range sequentially.
3841 @c JP
3842 最後の形式のように、レンジオブジェクト (@ref{Range}参照) が与えられた場合は、
3843 そのレンジの要素を順に生成します。
3844 @c COMMON
3845 @end deffn
3846
3847 @deffn {EC Qualifier} :real-range vars stop
3848 @deffnx {EC Qualifier} :real-range vars start stop
3849 @deffnx {EC Qualifier} :real-range vars start stop step
3850 @c EN
3851 Generates a series of real numbers, starting from
3852 @var{start} (defaults to 0) and stops below @var{stop},
3853 stepping by @var{step} (defaults to 1). If all the arguments
3854 are exact numbers, the result consists of exact numbers; if any
3855 of the arguments are inexact, the result consists of inexact numbers.
3856 @c JP
3857 @var{start}から始まり、@var{step}づつ増加し、@var{stop}を越えないような
3858 実数列を生成します。@var{start}が省略された場合は0、
3859 @var{step}が省略された場合は1が使われます。
3860 全ての引数が正確数であれば正確な数列が、ひとつでも非正確数が混じって入れば
3861 非正確な数列が生成されます。
3862 @c COMMON
3863
3864 @example
3865 (list-ec (:real-range v 5.0) v)
3866 @result{} (0.0 1.0 2.0 3.0 4.0)
3867 (list-ec (:real-range v 1 4 1/3) v)
3868 @result{} (1 4/3 5/3 2 7/3 8/3 3 10/3 11/3)
3869 (list-ec (:real-range v 1 5.0 1/2) v)
3870 @result{} (1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5)
3871 @end example
3872
3873 @c EN
3874 If one, two or three real numbers is/are given to the generic
3875 qualifier @code{:}, and any one of them isn't an exact integer,
3876 then this qualifier is used.
3877 @c JP
3878 汎用qualifier@code{:}に1個から3個の実数が与えられ、そのうちどれかひとつでも
3879 正確な整数でないものがあれば、このqualifierが使われます。
3880 @c COMMON
3881 @end deffn
3882
3883 @deffn {EC Qualifier} :char-range vars min max
3884 @c EN
3885 Generates a series of characters, starting from @var{min} and
3886 ending at @var{max} (inclusive). The characters are enumerated
3887 in the order defined by @code{char<=?} (@pxref{Characters}).
3888 @c JP
3889 文字@var{min}から@var{max}まで(両端含む)の文字を順に生成します。
3890 文字順は@code{char<=?}で比べられるのと同じ順になります (@ref{Characters}参照)。
3891 @c COMMON
3892
3893 @example
3894 (list-ec (:char-range v #\a #\e) v)
3895 @result{} (#\a #\b #\c #\d #\e)
3896 @end example
3897
3898 @c EN
3899 If two characters are given to the generic
3900 qualifier @code{:}, this qualifier is used.
3901 @c JP
3902 汎用qualifier@code{:}に2つの文字が与えられた場合は、
3903 このqualifierが使われます。
3904 @c COMMON
3905 @end deffn
3906
3907 @deffn {EC Qualifier} :port vars port
3908 @deffnx {EC Qualifier} :port vars port read-proc
3909 @c EN
3910 Generates a series of values read from an input port @var{port},
3911 by the procedure @var{read-proc} (defaults to @code{read}). The
3912 series terminates when EOF is read.
3913 @c JP
3914 入力ポート@var{port}から、@var{read-proc}を使って読まれる値を、
3915 EOFに出会うまで次々に生成します。@var{read-proc}が省略された場合は@code{read}
3916 が使われます。
3917 @c COMMON
3918
3919 @example
3920 (call-with-input-string "a \"b\" :c"
3921 (^p (list-ec (:port v p) v)))
3922 @result{} (a "b" :c)
3923 @end example
3924
3925 @c EN
3926 If one or two arguments are given to the generic
3927 qualifier @code{:} and the first one is an input port,
3928 then this qualifier is used.
3929 @c JP
3930 汎用qualifier@code{:}に2つの引数が与えられ、最初の引数が入力ポートであれば、
3931 このqualifierが使われます。
3932 @c COMMON
3933 @end deffn
3934
3935 @deffn {EC Qualifier} :generator vars gen
3936 @c EN
3937 This is Gauche's extension and not defined in SRFI-42.
3938 @var{gen} must be a procedure with zero arguments.
3939 This qualifier repeats until @var{gen} returns EOF.
3940
3941 Gauche has a set of utilities to create and operate on
3942 such procedures; see @ref{Generators}.
3943 @c JP
3944 これはSRFI-42には定義さていない、Gauche独自の拡張です。
3945 @var{gen}は引数と取らない手続きです。このqualifierは
3946 @var{gen}がEOFを返すまで繰り返します。
3947
3948 Gaucheは、そのような手続きを作ったり操作したりする便利な関数群を
3949 提供しています。@ref{Generators}を参照してください。
3950 @c COMMON
3951
3952 @example
3953 (use gauche.generator)
3954 (list-ec (:generator v (grange 1 8)) v)
3955 @result{} (1 2 3 4 5 6 7)
3956 @end example
3957
3958 @c EN
3959 If one argument is given to the generic
3960 qualifier @code{:} and it is applicable without arguments,
3961 then this qualifier is used.
3962 @c JP
3963 汎用qualifier@code{:}に1つの引数が与えられ、それが引数無しで呼び出し可能なものであれば、
3964 このqualifierが使われます。
3965 @c COMMON
3966 @end deffn
3967
3968 @deffn {EC Qualifier} :collection vars coll
3969 @c EN
3970 This is Gauche's extension and not defined in SRFI-42.
3971 @var{coll} must be an instance of @code{<collection>} or its subclass.
3972 (@pxref{Collection framework}).
3973 This qualifier repeats over the elements in the collection.
3974
3975 If srfi-42 has a specialized qualifier, it is faster to use it
3976 (e.g. a vector is also a collection, but using @code{:vector} is
3977 faster than @code{:collection}).
3978 @c JP
3979 これはSRFI-42には定義さていない、Gauche独自の拡張です。
3980 @var{coll}は@code{<collection>}クラスかそのサブクラスのインスタンスでなければなりません
3981 (@ref{Collection framework}参照)。
3982 このqualifierはコレクションの各要素に対して繰り返します。
3983
3984 特定の型に特化したqualifierがある場合はそちらを使う方が速いです
3985 (例えば、ベクタはコレクションでもありますが、@code{:collection}を使うより
3986 @code{:vector}を使う方が速いです。)
3987 @c COMMON
3988
3989 @c EN
3990 If one argument is given to the generic
3991 qualifier @code{:} and it is a collection other than the specific
3992 types supported directly in SRFI-42, this qualifer is used.
3993 @c JP
3994 汎用qualifier@code{:}に1つの引数が与えられ、
3995 それがSRFI-42で用意されている型以外のコレクションであれば、
3996 このqualifierが使われます。
3997 @c COMMON
3998 @end deffn
3999
4000 @deffn {EC Qualifier} :parallel generator @dots{}
4001 @c EN
4002 This is used to run through multiple generators in parallel.
4003 It terminates when any one of @var{generator} is exhausted.
4004 @c JP
4005 複数のジェネレータ節を並列に走査するのに使います。
4006 @var{generator}のどれかが値を使い切った時点で止まります。
4007 @c COMMON
4008
4009 @example
4010 (list-ec (:parallel (: x '(a b c))
4011 (: y "defg"))
4012 (cons x y))
4013 @result{} ((a . #\d) (b . #\e) (c . #\f))
4014
4015 ;; Compare with this:
4016 (list-ec (: x '(a b c))
4017 (: y "defg")
4018 (cons x y))
4019 @result{} ((a . #\d) (a . #\e) (a . #\f) (a . #\g)
4020 (b . #\d) (b . #\e) (b . #\f) (b . #\g)
4021 (c . #\d) (c . #\e) (c . #\f) (c . #\g))
4022 @end example
4023 @end deffn
4024
4025 @deffn {EC Qualifier} :let vars expr
4026 @c EN
4027 Evaluate @var{expr}, and bind the result to @var{vars} and execure
4028 the following clauses once.
4029 If @var{vars} has an index var, it is bound to 0.
4030 It is effectively the same as @code{(:list vars (list expr))}.
4031 @c JP
4032 @var{expr}を評価し、その値を@var{vars}に束縛して1回だけ以降の節を実行します。
4033 @var{vars}にインデックス変数があればそれは0に束縛されます。
4034 実効的には@code{(:list vars (list expr))}と同じです。
4035 @c COMMON
4036 @end deffn
4037
4038 @deffn {EC Qualifier} :while g-qualifier expr
4039 @deffnx {EC Qualifier} :until generator expr
4040 @c EN
4041 Generates values from @var{g-qualifier} while/until @var{expr} evaluates true.
4042 Here, @var{g-qualifier} is one of generative EC qualifiers. The variable
4043 bound in @var{g-qualifier} is visible from @var{expr}.
4044 @c JP
4045 @var{g-qualifier}は生成的qualifierです。@var{g-qualifier}が生成する値によって
4046 @var{expr}が真の値である間/真の値になるまで、値を生成しつづけます。@var{expr}内では
4047 @var{g-qualifier}が束縛する変数が使えます。
4048 @c COMMON
4049
4050 @example
4051 (use math.prime)
4052 (sum-ec (:while (: p (index k) *primes*) (<= k 100)) p)
4053 @end example
4054 @end deffn
4055
4056
4057 @deffn {EC Qualifier} :dispatched vars dispatch arg1 args @dots{}
4058 @end deffn
4059
4060 @deffn {EC Qualifier} :do (lb @dots{}) ne1? (ls @dots{})
4061 @deffnx {EC Qualifier} :do (let (ob @dots{}) oc @dots{}) (lb @dots{}) ne1? (let (ib @dots{}) ic @dots{}) ne2? (ls @dots{})
4062 @end deffn
4063
4064 @c EN
4065 @subsubheading Control qualifiers
4066 @c JP
4067 @subsubheading フロー制御qualifier
4068 @c COMMON
4069
4070 @deffn {EC Qualifier} if test
4071 @c EN
4072 Evaluates @var{test}, and if it yields false, stops that iteration
4073 and start the next iteration.
4074 @c JP
4075 @var{test}を評価し、それが偽だった場合はその回の繰り返しを中止し、次の繰り返しに移ります。
4076 @c COMMON
4077
4078 @c EN
4079 The following examples returns a list of pythagorian triplets @code{(a b c)},
4080 which satisfies @code{a^2 + b^2 = c^2}, less than 100.
4081 @c JP
4082 次の例は、@code{a^2 + b^2 = c^2}を満たすピタゴラス数@code{(a b c)}の組を、
4083 c < 100 の範囲で列挙します。
4084 @c COMMON
4085
4086 @example
4087 (list-ec (: c 1 100) (: a 1 c) (: b a c)
4088 (if (= (square c) (+ (square a) (square b))))
4089 (list a b c))
4090 @result{} ((3 4 5) (6 8 10) (5 12 13) (9 12 15) (8 15 17) @dots{})
4091 @end example
4092 @end deffn
4093
4094 @deffn {EC Qualifier} not test
4095 @deffnx {EC Qualifier} and test @dots{}
4096 @deffnx {EC Qualifier} or test @dots{}
4097 @c EN
4098 A shorthand of @code{(if (not test))}, @code{(if (and test @dots{}))}, and
4099 @code{(if (or test @dots{}))}.
4100 @c JP
4101 それぞれ@code{(if (not test))}、@code{(if (and test @dots{}))}、
4102 @code{(if (or test @dots{}))}の略記です。
4103 @c COMMON
4104 @end deffn
4105
4106 @deffn {EC Qualifier} begin command @dots{} expr
4107 @c EN
4108 During iteration, evaluates @var{command} @dots{} for side effects
4109 before evalutes @var{expr}. The result of @var{command}s are discarded.
4110 @c JP
4111 繰り返しの途中に、@var{expr}を評価する前に@var{command} @dots{}を副作用のために評価します。
4112 @var{command}の結果は捨てられます。
4113 @c COMMON
4114 @end deffn
4115
4116 @deffn {EC Qualifier} nested qualifier @dots{}
4117 @c EN
4118 Splices @var{qualifier} @dots{}. For example,
4119 @code{(list-ec (: a 2) (nested (: b 2) (: c 2)) (: d 2) (list a b c d))}
4120 is equivalent to
4121 @code{(list-ec (: a 2) (: b 2) (: c 2) (: d 2) (list a b c d))}.
4122 @c JP
4123 @var{qualifier} @dots{}をこの箇所にスプライシングします。たとえば
4124 @code{(list-ec (: a 2) (nested (: b 2) (: c 2)) (: d 2) (list a b c d))} は
4125 @code{(list-ec (: a 2) (: b 2) (: c 2) (: d 2) (list a b c d))} と同じです。
4126 @c COMMON
4127 @end deffn
4128
4129
4130 @c ----------------------------------------------------------------------
4131 @node Vector library (Legacy), Requiring extensions, Eager comprehensions, Library modules - SRFIs
4132 @section @code{srfi.43} - Vector library (legacy)
4133 @c NODE ベクタライブラリ(旧式), @code{srfi.43} - ベクタライブラリ(旧式)
4134
4135 @deftp {Module} srfi.43
4136 @mdindex srfi.43
4137 @c EN
4138 This module is effectively superseded by R7RS and SRFI-133.
4139 There are a few procedures that are not compatible with R7RS and
4140 SRFI-133, and this module remains to support
4141 legacy code that depends on them.
4142
4143 @xref{Vectors}, and @pxref{R7RS vectors}, for the ``modern'' versions
4144 of vector library. New code should use them.
4145
4146 The following procedures in SRFI-43 are built-in.
4147 @xref{Vectors}, for the description.
4148 @c JP
4149 このモジュールは実効的に、R7RSとSRFI-133に取って代わられています。
4150 いくつかの手続きはR7RSやSRFI-133の同名の手続きとは非互換で、
4151 このモジュールはSRFI-43に依存している既存のコードのためだけに
4152 残されています。
4153
4154 「現代的な」ベクタライブラリは、@ref{Vectors}と@ref{R7RS vectors}
4155 で説明されています。新たなコードはそちらを使うべきです。
4156
4157 以下のSRFI-43の手続きは組み込みになっています。
4158 説明は@ref{Vectors}を参照してください。
4159 @c COMMON
4160
4161 @example
4162 make-vector vector vector? vector-ref
4163 vector-set! vector-length vector-fill! vector-copy
4164 vector-copy! vector-append vector->list list->vector
4165 reverse-list->vector
4166 @end example
4167
4168 @c EN
4169 The following procedures in SRFI-43 are supported by SRFI-133.
4170 @xref{R7RS vectors}, for the description.
4171 @c JP
4172 以下のSRFI-43の手続きはSRFI-133でも同様にサポートされています。
4173 説明は@ref{R7RS vectors}を参照してください。
4174 @c COMMON
4175
4176 @example
4177 vector-unfold vector-unfold-right vector-reverse-copy
4178 vector-reverse-copy! vector-concatenate vector-empty?
4179 vector= vector-index vector-index-right
4180 vector-skip vector-skip-right vector-binary-search
4181 vector-any vector-every vector-swap!
4182 reverse-vector->list
4183 @end example
4184
4185 @c EN
4186 We explain the procedures that are not listed above.
4187 @c JP
4188 ここでは上に挙げられていない手続きを説明します。
4189 @c COMMON
4190 @end deftp
4191
4192 @defun vector-fold kons knil vec1 vec2 @dots{}
4193 @defunx vector-fold-right kons knil vec1 vec2 @dots{}
4194 [SRFI-43]
4195 @c MOD srfi.43
4196 @c EN
4197 Like @code{vector-fold} and @code{vector-fold-right}
4198 in SRFI-133, but @var{kons}
4199 takes an extra argument, the current index, as its first argument.
4200 So @var{kons} must accept @var{n}+2 arguments, where
4201 @var{n} is the number of given vectors.
4202 It is called as @code{(kons <index> <cumulated-value> <elt1> <elt2> ...)}.
4203 @c JP
4204 SRFI-133の@code{vector-fold}と@code{vector-fold-right}と似ていますが、
4205 @var{kons}手続きは追加で、現在のインデックスを第一引数として取ります。
4206 従って、@var{n}を引数で与えられたベクタの数とすると、
4207 @var{kons}は@var{n+2}個の引数を取らなければなりません。
4208 @var{kons}は@code{(kons <index> <cumulated-value> <elt1> <elt2> ...)}
4209 のように呼ばれます。
4210 @c COMMON
4211
4212 @c EN
4213 Gauche has @code{fold-with-index} (@pxref{Mapping over sequences})
4214 that can be used to fold vectors with index, but the argument order
4215 of @var{kons} is slightly different: It passes the index, each
4216 element from argument vectors, then cumulated values.
4217 @c JP
4218 Gaucheには@code{fold-with-index}があって、ベクタをインデックスつきで
4219 foldするのに使えます(@ref{Mapping over sequences})が、
4220 @var{kons}が受け取る引数の順序が違います: インデックスの次に
4221 各ベクタの要素、そして最後に累積された値が来ます。
4222 @c COMMON
4223
4224 @example
4225 (use srfi.43)
4226 (vector-fold list '() '#(a b c) '#(d e f))
4227 @result{} (2 (1 (0 () a d) b e) c f)
4228
4229 (use gauche.sequence)
4230 (fold-with-index list '() '#(a b c) '#(d e f))
4231 @result{} (2 c f (1 b e (0 a d ())))
4232 @end example
4233 @end defun
4234
4235 @defun vector-map f vec1 vec2 @dots{}
4236 @defunx vector-map! f vec1 vec2 @dots{}
4237 @defunx vector-for-each f vec1 vec2 @dots{}
4238 @defunx vector-count f vec1 vec2 @dots{}
4239 [SRFI-43]
4240 @c MOD srfi.43
4241 @c EN
4242 Like @code{vector-map} and @code{vector-for-each} of R7RS,
4243 and @code{vector-map!} and @code{vector-count} in @code{srfi-133},
4244 except @var{f} takes
4245 an extra argument, the current index, as its first argument.
4246 @c JP
4247 R7RSの@code{vector-map}および@code{vector-for-each}、
4248 そして@code{srfi-133}の@code{vector-map!}および@code{vector-cout}と
4249 ほぼ同じですが、@var{f}が現在のインデックスを最初の引数として(他の引数より前に)
4250 取ります。
4251 @c COMMON
4252
4253 @c EN
4254 Gauche provides @code{vector-map-with-index},
4255 @code{vector-map-with-index!} and @code{vector-for-each-with-index}
4256 which are the same as SRFI-43's @code{vector-map}, @code{vector-map!}
4257 and @code{vector-for-each}, respectively. @xref{Vectors}.
4258 @c JP
4259 GaucheはSRFI-43の@code{vector-map}、@code{vector-map!}、
4260 @code{vector-for-each}互換な手続きをそれぞれ
4261 @code{vector-map-with-index}、
4262 @code{vector-map-with-index!}、@code{vector-for-each-with-index}という
4263 名前で提供しています。@ref{Vectors}参照。
4264 @c COMMON
4265
4266 @example
4267 (vector-map list '#(a b c))
4268 @result{} #((0 a) (1 b) (2 c))
4269 (vector-map list '#(a b c) '#(d e f g))
4270 @result{} #((0 a d) (1 b e) (2 c f))
4271 (vector-count = '#(0 2 2 4 4))
4272 @result{} 3
4273 @end example
4274
4275 @c EN
4276 (Note: The @code{vector-count} example calls @code{=} with
4277 two arguments, the current index and the element, for each element
4278 of the input vector. So it counts the number of
4279 occasions when the element is equal to the index.)
4280 @c JP
4281 (註: @code{vector-count}は@code{=}を二つの引数、現在のインデックスと
4282 ベクタの要素で呼び出します。従ってこの例は、ベクタの要素がインデックスと一致する
4283 場合を数えています。)
4284 @c COMMON
4285
4286 @c EN
4287 The generic @code{map} and @code{for-each}
4288 in @code{gauche.collection} can be used
4289 on vectors, but the mapped procedure is called without index, and the result
4290 is returned as a list.
4291 @code{(vector-map f vec1 vec2 @dots{})} is operationally equivalent to
4292 @code{(map-to-with-index <vector> f vec1 vec2 @dots{})}.
4293 See @ref{Collection framework} and @ref{Sequence framework}.
4294 @c JP
4295 @code{gauche.collection}のジェネリックな@code{map}や@code{for-each}は
4296 ベクタに対しても使えますが、マップされる手続きはインデックスを取らず、
4297 また結果はリストになります。
4298 @code{(vector-map f vec1 vec2 @dots{})}は機能的には
4299 @code{(map-to-with-index <vector> f vec1 vec2 @dots{})}と同じになります。
4300 詳しくは@ref{Collection framework}と@ref{Sequence framework}を参照してください。
4301 @c COMMON
4302 @end defun
4303
4304 @c ----------------------------------------------------------------------
4305 @node Requiring extensions, Integers as bits, Vector library (Legacy), Library modules - SRFIs
4306 @section @code{srfi.55} - Requiring extensions
4307 @c NODE require の拡張, @code{srfi.55} - require の拡張
4308
4309 @deftp {Module} srfi.55
4310 @mdindex srfi.55
4311 @c EN
4312 This module defines @code{require-extension} macro, a yet another way
4313 to write portable scripts. See @ref{Feature conditional} and
4314 @ref{Feature-based program configuration language} for other means of
4315 ensuring specific features.
4316 @c JP
4317 このモジュールでは @code{require-extension} マクロが定義されています。
4318 これは、ポータブルなスクリプトを書くためのもうひとつ別の方法です。
4319 指定した特性を確認する他の方法については、@ref{Feature conditional}
4320 および@ref{Feature-based program configuration language}を見てください。
4321 @c COMMON
4322
4323 @c EN
4324 This module is autoloaded when you use @code{require-extension}, so
4325 you don't need explicitly say @code{(use srfi.55)}; for portable scripts,
4326 you shouldn't.
4327 @c JP
4328 このモジュールは、@code{require-extension}を使った際に自動的にロードさ
4329 れます。それゆえ明示的に@code{(use srfi.55)}する必要はありませんし、ポー
4330 タビリティのためにはするべきではありません。
4331 @c COMMON
4332 @end deftp
4333
4334 @defmac require-extension clause @dots{}
4335 [SRFI-55]
4336 @c MOD srfi.55
4337 @c EN
4338 Make extension(s) specified by @var{clause}s available in the rest
4339 of the program.
4340 @c JP
4341 @var{clause}で指定した拡張を以降のプログラムで利用可能にします。
4342 @c COMMON
4343
4344 @c EN
4345 A @var{clause} takes the following form:
4346 @c JP
4347 @var{clause}は以下の形式になります。
4348 @c COMMON
4349 @example
4350 (@var{extension-id} @var{extension-arg} @dots{})
4351 @end example
4352
4353 @c EN
4354 Currently, only @code{srfi} is supported as @var{extension-id}, and
4355 its arguments are SRFI numbers.
4356 @c JP
4357 現時点では、@code{srfi}のみ@var{extension-id}として使えます。その引数
4358 はSRFIの番号です。
4359 @c COMMON
4360
4361 @c EN
4362 For example, the following form:
4363 @c JP
4364 たとえば、以下の
4365 @c COMMON
4366 @example
4367 (require-extension (srfi 1 13 14))
4368 @end example
4369
4370 @c EN
4371 Roughly corresponds to Gauche's @code{use} forms:
4372 @c JP
4373 は以下の Gauche の @code{use} 形式にほぼ対応します。
4374 @c COMMON
4375 @example
4376 (use srfi.1)
4377 (use srfi.13)
4378 (use srfi.14)
4379 @end example
4380 @end defmac
4381
4382 @c ----------------------------------------------------------------------
4383 @node Integers as bits, A Scheme API for test suites, Requiring extensions, Library modules - SRFIs
4384 @section @code{srfi.60} - Integers as bits
4385 @c NODE 整数に対するビット操作, @code{srfi.60} - 整数に対するビット操作
4386
4387 @deftp {Module} srfi.60
4388 @mdindex srfi.60
4389 @c EN
4390 This srfi provides bit operations on integers, regarding them
4391 as 2's complement representation. It is compatible to SLIB's @code{logical}
4392 module.
4393 @c JP
4394 このsrfiは、2の補数表現とみなした正確な整数に対するビット演算を提供します。
4395 SLIBの@code{logical}モジュールと互換です。
4396 @c COMMON
4397
4398 @c EN
4399 The newer SRFI-151 (@pxref{R7RS bitwise operations}) provides the same
4400 functionality and more, with more consistent naming. We recommend
4401 new code to use SRFI-151, while we keep SRFI-60 for the backward
4402 compatibility.
4403 @c JP
4404 より新しいSRFI-151 (@ref{R7RS bitwise operations})はこのsrfiの機能を
4405 カバーし、新しい機能を加え、さらに一貫性のある名前を採用しています。
4406 新に書くコードにはSRFI-151を使ってください。
4407 SRFI-60は後方互換性のために残されています。
4408 @c COMMON
4409
4410 @c EN
4411 The following procedures are Gauche built-in.
4412 @xref{Basic bitwise operations}, for the description.
4413 @c JP
4414 以下の手続きはGauche組み込みです。
4415 @ref{Basic bitwise operations}を参照してください。
4416 @c COMMON
4417
4418 @example
4419 lognot logand logior logxor
4420 logtest logcount integer-length logbit?
4421 copy-bit bit-field copy-bit-field ash
4422 @end example
4423
4424 @c EN
4425 The following procedures are defined in SRFI-151.
4426 @xref{R7RS bitwise operations}, for the description.
4427 @c JP
4428 以下の手続きはSRFI-151で定義されています。
4429 @ref{R7RS bitwise operations}を参照してください。
4430 @c COMMON
4431
4432 @example
4433 bitwise-not bitwise-and bitwise-ior bitwise-xor
4434 arithmetic-shift bit-count bitwise-if bit-set?
4435 copy-bit first-set-bit
4436 @end example
4437 @end deftp
4438
4439 @c EN
4440 We describe procedures that are unique in SRFI-60 below.
4441 @c JP
4442 SRFI-60特有の手続きを以下に説明します。
4443 @c COMMON
4444
4445 @defun bitwise-merge mask n0 n1
4446 [SRFI-60]
4447 @c MOD srfi.60
4448 @c EN
4449 Same as @code{bitwise-if} (@pxref{R7RS bitwise operations}).
4450 @c JP
4451 @code{bitwise-if}と同じです(@ref{R7RS bitwise operations}参照)。
4452 @c COMMON
4453 @end defun
4454
4455 @defun any-bits-set? mask n
4456 [SRFI-60]
4457 @c MOD srfi.60
4458 @c EN
4459 Same as builtin @code{logtest} (@pxref{Basic bitwise operations}).
4460 It is also called @code{any-bit-set?} in SRFI-151 (@pxref{R7RS bitwise operations}).
4461 @c JP
4462 組み込みの@code{logtest}と同じです (@ref{Basic bitwise operations}参照)。
4463 SRFI-151では@code{any-bit-set?}と呼ばれています
4464 (@ref{R7RS bitwise operations}参照)。
4465 @c COMMON
4466 @end defun
4467
4468 @defun log2-binary-factors n
4469 [SRFI-60]
4470 @c MOD srfi.60
4471 @c EN
4472 It is also called as @code{first-set-bit} in this srfi, which is also
4473 in SRFI-151 (@pxref{R7RS bitwise operations}).
4474 This is equivalent to Gauche's built-in @code{twos-exponent-factor}
4475 (@pxref{Basic bitwise operations}).
4476 @c JP
4477 これはこのsrfiの@code{first-set-bit}の別名で、@code{first-set-bit}の方は
4478 SRFI-151で提供されています(@ref{R7RS bitwise operations}参照)。
4479 また、Gaucheの組み込みである@code{twos-exponent-factor}とも同じです
4480 (@ref{Basic bitwise operations}参照)。
4481 @c COMMON
4482 @end defun
4483
4484 @defun rotate-bit-field n count start end
4485 [SRFI-60]
4486 @c MOD srfi.60
4487 @c EN
4488 This is equivalent to @code{bit-field-rotate} in SRFI-151
4489 (@pxref{R7RS bitwise operations}).
4490 @c JP
4491 SRFI-151の@code{bit-field-rotate}と同じです(@ref{R7RS bitwise operations}参照)。
4492 @c COMMON
4493 @end defun
4494
4495 @defun reverse-bit-field n start end
4496 [SRFI-60]
4497 @c MOD srfi.60
4498 @c EN
4499 This is equivalent to @code{bit-field-reverse} in SRFI-151
4500 (@pxref{R7RS bitwise operations}).
4501 @c JP
4502 SRFI-151の@code{bit-field-reverse}と同じです(@ref{R7RS bitwise operations}参照)。
4503 @c COMMON
4504 @end defun
4505
4506 @defun integer->list n :optional len
4507 [SRFI-60]
4508 @c MOD srfi.60
4509 @c EN
4510 Breaks @var{n} to each bits, representing @code{1} as @code{#t} and
4511 @code{0} as @code{#f}, LSB last, and returns a list of them.
4512 If a nonnegative integer @var{len} is given, it specifies the length
4513 of the result. If it is omitted, @code{(integer-length n)} is used.
4514 @c JP
4515 整数nをビットに分割し、論理値のリストとして返します。
4516 @code{1}であるビットが@code{#t}に、
4517 @code{0}であるビットが@code{#f}にマップされます。MSBが最初、LSBが最後になります。
4518 非負整数@var{len}が与えられた場合は、それが結果の長さを指定します。
4519 そうでなければ @code{(integer-length n)}が結果の長さになります。
4520 @c COMMON
4521
4522 @example
4523 (integer->list 10) @result{} (#t #f #t #f)
4524 (integer->list 10 6) @result{} (#f #f #t #f #t #f)
4525 @end example
4526
4527 @c EN
4528 SRFI-151 has similar procedure @code{bits->list}, with a reversed bit
4529 order (LSB first) (@pxref{R7RS bitwise operations}).
4530 @c JP
4531 SRFI-151の@code{bits->list}は、ビット順が逆 (LSBが最初) であることを除けば
4532 これと同じです(@ref{R7RS bitwise operations}参照)。
4533 @c COMMON
4534 @end defun
4535
4536 @defun list->integer lis
4537 [SRFI-60]
4538 @c MOD srfi.60
4539 @c EN
4540 Takes a list of boolean values, replaces the true value for @code{1}
4541 and the false value for @code{0}, and compose an integer regarding
4542 each value as a binary digit. If @var{n} is nonnegative integer,
4543 @code{(eqv? (list->integer (integer->list n)) n)} is true.
4544 @c JP
4545 論理値のリストを取り、@code{#t}を@code{1}、@code{#f}を@code{0}と解釈して、
4546 各ビットからなる整数を返します。@var{n}を非負整数とすると、
4547 @code{(eqv? (list->integer (integer->list n)) n)}が成り立ちます。
4548 @c COMMON
4549
4550 @example
4551 (list->integer '(#f #t #f #t #f)) @result{} 10
4552 @end example
4553
4554 @c EN
4555 SRFI-151 has similar procedure @code{list->bits}, with a reversed bit
4556 order (LSB first) (@pxref{R7RS bitwise operations}).
4557 @c JP
4558 SRFI-151の@code{list->bits}は、ビット順が逆 (LSBが最初) であることを除けば
4559 これと同じです(@ref{R7RS bitwise operations}参照)。
4560 @c COMMON
4561 @end defun
4562
4563 @defun booleans->integer bool @dots{}
4564 [SRFI-60]
4565 @c MOD srfi.60
4566 @equiv{} @code{(list->integer (list @var{bool} @dots{}))}
4567
4568 @c EN
4569 SRFI-151 has similar procedure @code{bits}, with a reversed bit
4570 order (LSB first) (@pxref{R7RS bitwise operations}).
4571 @c JP
4572 SRFI-151の@code{bits}は、ビット順が逆 (LSBが最初) であることを除けば
4573 これと同じです(@ref{R7RS bitwise operations}参照)。
4574 @c COMMON
4575 @end defun
4576
4577 @c ----------------------------------------------------------------------
4578 @node A Scheme API for test suites, Octet vectors, Integers as bits, Library modules - SRFIs
4579 @section @code{srfi.64} - A Scheme API for test suites
4580 @c NODE SchemeテストスイートAPI, @code{srfi.64} - SchemeテストスイートAPI
4581
4582 @deftp {Module} srfi.64
4583 @mdindex srfi.64
4584 @c EN
4585 This module defines API to write a portable test suite. In Gauche,
4586 it is adapted to work with @code{gauche.test} native test framework
4587 (@pxref{Unit testing}).
4588 @c JP
4589 このモジュールはポータブルなテストスイートを書くAPIを提供します。
4590 Gaucheでは、このsrfiは@code{gauche.test}と協調して動くようになっています
4591 (@ref{Unit testing}参照)。
4592 @c COMMON
4593
4594 @c EN
4595 If SRFI-64 tests are run during @code{gauche.test}
4596 the tests becomes a part of the whole @code{gauche.test} suite.
4597 @c JP
4598 @code{gauche.test}が有効な状態で、SRFI-64テストを走らせた場合、
4599 それらのテストは@code{gauche.test}の一部として実行されます。
4600 @c COMMON
4601
4602 @c EN
4603 The recommended way is to write a test suite in pure srfi-64, then include
4604 it from the gauche test script:
4605 @c JP
4606 推奨されるテストの書き方は、ポータブルなテストをsrfi-64のみで書き、
4607 Gaucheテストスクリプトから次のとおりincludeすることです。
4608 @c COMMON
4609
4610 @example
4611 (use gauche.test)
4612 (test-start "the tests")
4613 ;; portable test
4614 (include "test-suite-in-srfi-64")
4615
4616 ;; gauche-specific test, if needed
4617 ...
4618
4619 (test-end)
4620 @end example
4621
4622 @c EN
4623 If @file{test-suite-in-srfi-64.scm} is run by itself, it uses SRFI-64's
4624 default reporting system. If it is run within @code{gauche.test} script,
4625 the results are reported via @code{gauche.test}, consolidated with other
4626 Gauche test results.
4627 @c JP
4628 @file{test-suite-in-srfi-64.scm}をそれ単独で走らせた場合は、
4629 SRFI-64のデフォルトのテスト報告形式で結果が報告されます。
4630 @code{gauche.test}スクリプトからincludeして走らせた場合は、
4631 結果が@code{gauche.test}の報告形式を使って、他のGaucheテストと合わせて報告されます。
4632 @c COMMON
4633 @end deftp
4634
4635 @menu
4636 * SRFI-64 test runner::
4637 * SRFI-64 test API::
4638 @end menu
4639
4640 @node SRFI-64 test runner, SRFI-64 test API, A Scheme API for test suites, A Scheme API for test suites
4641 @subsection Test runner
4642
4643 In SRFI-64, tests are run with an active @emph{test runner} which collects
4644 test results and emits reports. It allows users to provide custom runners
4645 to handle tailored reports suitable to the specific tests.
4646
4647 @subsubheading Test runner object
4648
4649 @deftp {Record} test-runner
4650 [SRFI-64]
4651 @c MOD srfi.64
4652
4653 @end deftp
4654
4655 @defun test-runner? obj
4656 [SRFI-64]
4657 @c MOD srfi.64
4658 @end defun
4659
4660 @deftp {Parameter} test-runner-current
4661 [SRFI-64]
4662 @c MOD srfi.64
4663 @end deftp
4664
4665 @defun test-runner-get
4666 [SRFI-64]
4667 @c MOD srfi.64
4668 @end defun
4669
4670 @defun test-runner-simple
4671 [SRFI-64]
4672 @c MOD srfi.64
4673 @end defun
4674
4675 @defun test-runner-null
4676 [SRFI-64]
4677 @c MOD srfi.64
4678 @end defun
4679
4680 @defun test-runner-factory :optional factory
4681 [SRFI-64]
4682 @c MOD srfi.64
4683 @end defun
4684
4685
4686 @subsubheading Running tests with a specified runner
4687
4688 @defun test-apply [runner] specifier @dots{} procedure
4689 [SRFI-64]
4690 @c MOD srfi.64
4691 @end defun
4692
4693 @defmac test-with-runner runner decl-or-expr @dots{}
4694 [SRFI-64]
4695 @c MOD srfi.64
4696 @end defmac
4697
4698
4699 @subsubheading Latest result properties
4700
4701 A runner holds a single alist to keep the latest result properties.
4702 Except the @code{result-kind} property, which is set by every basic
4703 test procedures, the usage of properties are up to the test runner
4704 and/or test writer.
4705
4706 @defun test-result-clear runner
4707 [SRFI-64]
4708 @c MOD srfi.64
4709 @end defun
4710
4711 @defun test-result-ref runner pname :optional default
4712 [SRFI-64]
4713 @c MOD srfi.64
4714 @end defun
4715
4716 @defun test-result-set! runnre pname value
4717 [SRFI-64]
4718 @c MOD srfi.64
4719 @end defun
4720
4721 @defun test-result-remove runner pname
4722 [SRFI-64]
4723 @c MOD srfi.64
4724 @end defun
4725
4726 @defun test-result-alist runner
4727 [SRFI-64]
4728 @c MOD srfi.64
4729 @end defun
4730
4731 @defun test-result-kind :optional runner
4732 [SRFI-64]
4733 @c MOD srfi.64
4734 @end defun
4735
4736 @defun test-passed? :optional runner
4737 [SRFI-64]
4738 @c MOD srfi.64
4739 @end defun
4740
4741 @subsubheading Keeping track of test status
4742
4743 @defun test-runner-pass-count runner
4744 @defunx test-runner-fail-count runner
4745 @defunx test-runner-xpass-count runner
4746 @defunx test-runner-xfail-count runner
4747 @defunx test-runner-skip-count runner
4748 [SRFI-64]
4749 @c MOD srfi.64
4750 @end defun
4751
4752 @defun test-runner-test-name runner
4753 [SRFI-64]
4754 @c MOD srfi.64
4755 @end defun
4756
4757 @defun test-runner-group-path runner
4758 [SRFI-64]
4759 @c MOD srfi.64
4760 @end defun
4761
4762 @defun test-runner-group-stack runner
4763 [SRFI-64]
4764 @c MOD srfi.64
4765 @end defun
4766
4767 @defun test-runner-aux-value runner
4768 @defunx test-runner-aux-value! runner value
4769 [SRFI-64]
4770 @c MOD srfi.64
4771 @end defun
4772
4773 @defun test-runner-reset runner
4774 [SRFI-64]
4775 @c MOD srfi.64
4776 @end defun
4777
4778 @subsubheading Callbacks
4779
4780 @defun test-runner-on-test-begin runner
4781 @defunx test-runner-on-test-begin! runner proc
4782 [SRFI-64]
4783 @c MOD srfi.64
4784 @end defun
4785
4786 @defun test-runner-on-test-end runner
4787 @defunx test-runner-on-test-end! runner proc
4788 [SRFI-64]
4789 @c MOD srfi.64
4790 @end defun
4791
4792 @defun test-runner-on-group-begin runner
4793 @defunx test-runner-on-group-begin! runner proc
4794 [SRFI-64]
4795 @c MOD srfi.64
4796 @end defun
4797
4798 @defun test-runner-on-group-end runner
4799 @defunx test-runner-on-group-end! runner proc
4800 [SRFI-64]
4801 @c MOD srfi.64
4802 @end defun
4803
4804 @defun test-runner-on-bad-count runner
4805 @defunx test-runner-on-bad-count! runner proc
4806 [SRFI-64]
4807 @c MOD srfi.64
4808 @end defun
4809
4810 @defun test-runner-on-bad-end-name runner
4811 @defunx test-runner-on-bad-end-name! runner proc
4812 [SRFI-64]
4813 @c MOD srfi.64
4814 @end defun
4815
4816 @defun test-runner-on-final runner
4817 @defunx test-runner-on-final! runner proc
4818 [SRFI-64]
4819 @c MOD srfi.64
4820 @end defun
4821
4822
4823 @defun test-on-test-begin-simple runner
4824 @defunx test-on-test-end-simple runner
4825 @defunx test-on-group-begin-simple runner
4826 @defunx test-on-group-end-simple runner
4827 @defunx test-on-bad-count-simple runner actual-count expected-count
4828 @defunx test-on-bad-end-name-simple runner begin-name end-name
4829 [SRFI-64]
4830 @c MOD srfi.64
4831 @end defun
4832
4833 @node SRFI-64 test API, , SRFI-64 test runner, A Scheme API for test suites
4834 @subsection Test API
4835
4836 @subsubheading Test grouping
4837
4838 SRFI-64 tests can be grouped, and groups can be nested.
4839
4840 @defun test-begin suite-name :optional count
4841 [SRFI-64]
4842 @c MOD srfi.64
4843 @end defun
4844
4845 @defun test-end :optional suite-name
4846 [SRFI-64]
4847 @c MOD srfi.64
4848 @end defun
4849
4850 @defun test-group suite-name body @dots{}
4851 [SRFI-64]
4852 @c MOD srfi.64
4853 @end defun
4854
4855 @defun test-group-with-cleanup suite-name body @dots{} cleanup
4856 [SRFI-64]
4857 @c MOD srfi.64
4858 @end defun
4859
4860 @subsubheading Individual tests
4861
4862 @defmac test-assert [test-name] expr
4863 [SRFI-64]
4864 @c MOD srfi.64
4865 @end defmac
4866
4867 @defmac test-eqv [test-name] expected test-expr
4868 @defmacx test-eq [test-name] expected test-expr
4869 @defmacx test-equal [test-name] expected test-expr
4870 [SRFI-64]
4871 @c MOD srfi.64
4872 @end defmac
4873
4874 @defmac test-approximate [test-name] extected test-expr margin
4875 [SRFI-64]
4876 @c MOD srfi.64
4877 @end defmac
4878
4879 @defmac test-error [[test-name] error-type] test-expr
4880 [SRFI-64]
4881 @c MOD srfi.64
4882 @end defmac
4883
4884 @defun test-read-eval-string string
4885 [SRFI-64]
4886 @c MOD srfi.64
4887 @end defun
4888
4889 @defmac test-expect-fail specifier
4890 [SRFI-64]
4891 @c MOD srfi.64
4892 @end defmac
4893
4894
4895 @subsubheading Conditional tests
4896
4897 @defun test-match-name name
4898 @defunx test-match-nth n :optional count
4899 @defunx test-match-any specifier @dots{}
4900 @defunx test-match-all specifier @dots{}
4901 [SRFI-64]
4902 @c MOD srfi.64
4903 @end defun
4904
4905 @defun test-skip specifier
4906 [SRFI-64]
4907 @c MOD srfi.64
4908 @end defun
4909
4910
4911 @c ----------------------------------------------------------------------
4912 @node Octet vectors, Basic hash tables, A Scheme API for test suites, Library modules - SRFIs
4913 @section @code{srfi.66} - Octet vectors
4914 @c NODE オクテットベクタ, @code{srfi.66} - オクテットベクタ
4915
4916 @deftp {Module} srfi.66
4917 @mdindex srfi.66
4918 @c EN
4919 This module defines procedures to deal with @code{u8vector}s; they are
4920 almost a subset of @code{srfi.160} and @code{gauche.uvector}
4921 (@pxref{Uniform vectors}, except one procedure, @code{u8vector-copy!},
4922 which has different argument orders (unfortunate historical artifacts).
4923 @c JP
4924 このモジュールは@code{u8vector}に特化した手続きを定義します。
4925 ほぼ@code{srfi.160}および@code{gauche.uvector}のサブセットです。
4926 (@pxref{Uniform vectors})。例外は@code{u8vector-copy!}で、
4927 これは不幸な歴史的事情から、@code{gauche.uvector}と引数順が異なります。
4928 @c COMMON
4929
4930 @c EN
4931 There's no reason to use this srfi except porting code that relies
4932 on @code{srfi.66}.
4933 @c JP
4934 @var{srfi.66}に依存するコードを移植するのでなければ、
4935 このモジュールを使う場面は無いでしょう。
4936 @c COMMON
4937
4938 @c EN
4939 The following procedures are the same as @code{gauche.uvector}:
4940 @c JP
4941 以下の手続きは@code{gauche.uvector}と同じです。
4942 @c COMMON
4943
4944 @example
4945 u8vector? make-u8vector u8vector
4946 u8vector->list list->u8vector
4947 u8vector-length u8vector-ref u8vector-set!
4948 u8vector=? u8vector-compare u8vector-copy
4949 @end example
4950 @end deftp
4951
4952 @defun u8vector-copy! src sstart target tstart n
4953 [SRFI-66]
4954 @c MOD srfi.66
4955 @c EN
4956 Copy the content of an u8vector @var{src}, starting from @var{sstart}
4957 for @var{n} octets, into an u8vector @var{target} beginning from
4958 @var{tstart}. The @var{target} u8vector must be mutable.
4959 @c JP
4960 u8vectorである@var{src}の、インデックス@var{sstart}から@var{n}オクテットを、
4961 u8vector @var{target}のインデックス@var{tstart}からにコピーします。
4962 @var{target}は変更可能なu8vectorでなければなりません。
4963 @c COMMON
4964
4965 @c EN
4966 Note that @code{gauche.uvector} has also @code{u8vector-copy!},
4967 but its argument order is as follows, where @var{send}
4968 is @code{(+ @var{sstart} @var{n})}:
4969 @c JP
4970 @code{gauche.uvector}も@code{u8vector-copy!}を提供しますが、
4971 引数が異なります。@var{send}を@code{(+ @var{sstart} @var{n})}として、
4972 次のとおりです:
4973 @c COMMON
4974
4975 @example
4976 (u8vector-copy! target tstart src sstart send)
4977 @end example
4978
4979 @c EN
4980 Gauche's argument order is consistent with @code{vector-copy!} of
4981 R7RS, SRFI-43 and SRFI-133.
4982
4983 We recommend to use @code{srfi.66} only for porting third-party
4984 libraries to avoid confusion.
4985 @c JP
4986 Gaucheの引数順は、R7RS、SRFI-43およびSRFI-133の@var{vector-copy!}と
4987 一貫性があります。
4988
4989 混乱を避けるため、
4990 @code{srfi.66}モジュールはサードパーティライブラリを移植する際に必要な場合に限り
4991 使うと良いでしょう。
4992 @c COMMON
4993 @end defun
4994
4995 @c ----------------------------------------------------------------------
4996 @node Basic hash tables, Octet-addressed binary blocks, Octet vectors, Library modules - SRFIs
4997 @section @code{srfi.69} - Basic hash tables
4998 @c NODE 基本的なハッシュテーブル, @code{srfi.69} - 基本的なハッシュテーブル
4999
5000 @deftp {Module} srfi.69
5001 @mdindex srfi.69
5002 @c EN
5003 This module has been superseded by R7RS @code{scheme.hash-table}
5004 (@pxref{R7RS hash tables}). New code should use it instead.
5005 @c JP
5006 このモジュールはR7RSの@code{scheme.hash-table}により更改されています。
5007 (@ref{R7RS hash tables}参照)。新たなコードはそちらを使うようにしてください。
5008 @c COMMON
5009
5010 @c EN
5011 This is a thin adaptor on Gauche's built-in hashtables
5012 (@pxref{Hashtables}). This is provided for the compatibility
5013 to the portable libraries; the hashtable object created by
5014 this module's @code{make-hash-table} is the same as the one
5015 created by Gauche's built-in, and you can pass the table to
5016 both APIs.
5017 @c JP
5018 このモジュールは、Gauche組み込みのハッシュテーブルのごく薄いラッパーです
5019 (@ref{Hashtables}参照)。このsrfiを要求するライブラリへの互換性のためだけに
5020 提供されています。このモジュールの@code{make-hash-table}で作られるハッシュテーブルは
5021 Gauche組み込みのハッシュテーブルそのものなので、どちらのAPIにも渡せます。
5022 @c COMMON
5023 @end deftp
5024
5025 @c EN
5026 Here's a summary of difference between SRFI-69 and Gauche's built-in
5027 hash table API:
5028 @c JP
5029 SRFI-69とGaucheのAPIの違いを挙げておきます:
5030 @c COMMON
5031
5032 @itemize
5033 @item
5034 @c EN
5035 The constructor @code{make-hash-table}, as well as @code{alist->hash-table},
5036 takes equality predicate and hash function, instead of a single
5037 comparator argument as Gauche does.
5038 @c JP
5039 コンストラクタ@code{make-hash-table}および@code{alist->hash-table}は、
5040 Gaucheでは比較器を取りますが、SRFI-69では等価述語とハッシュ関数を取ります。
5041 @c COMMON
5042 @item
5043 @c EN
5044 The hash function passed to SRFI-69's @code{make-hash-table}
5045 takes two arguments, an object to calculate a hash value,
5046 and a positive integer that limits the range of the hash value.
5047 @c JP
5048 SRFI-69の@code{make-hash-table}に渡されるハッシュ関数は、
5049 ハッシュ値を計算するオブジェクトに加え、ハッシュ値の範囲を指定する整数を取ります。
5050 @c COMMON
5051 @item
5052 @c EN
5053 SRFI-69's primary hash table accessor is @code{hash-table-ref},
5054 which takes a thunk to be called when the table doesn't have an
5055 entry for the given key, while Gauche's @code{hash-table-get} takes
5056 a fallback value for that.
5057 SRFI-69 also has @code{hash-table-ref/default},
5058 which takes a fallback value like Gauche's @code{hash-table-get},
5059 but the default value can't be omitted.
5060 @c JP
5061 SRFI-69の基本アクセサである@code{hash-table-ref}は、
5062 キーが登録されていなかった場合のデフォルト値を得るために、サンクを取ります。
5063 Gaucheの@code{hash-table-ref}はデフォルト値そのものを取ります。
5064 SRFI-69の@code{hash-table-ref/default}が、Gaucheの@code{hash-table-ref}に
5065 相当します。(但し@code{hash-table-ref/default}はデフォルト値を省略できません)。
5066 @c COMMON
5067 @item
5068 @c EN
5069 SRFI-69's @code{hash-table-update!} and @code{hash-table-update!/default}
5070 to Gauche's @code{hash-table-update!} is the same as
5071 @code{hash-table-ref}, @code{hash-table-ref/default} and
5072 @code{hash-table-get}.
5073 @c JP
5074 SRFI-69の@code{hash-table-update!}と@code{hash-table-update!/default}に対する
5075 Gaucheの@code{hash-table-update!}は、
5076 @code{hash-table-ref}と@code{hash-table-ref/default}に対する
5077 @code{hash-table-get}の関係と同じです。
5078 @c COMMON
5079 @item
5080 @c EN
5081 The basic iterator of SRFI-69 is called @code{hash-table-walk},
5082 which is Gauche's @code{hash-table-for-each}. The srfi name is chosen
5083 to avoid conflict with existing Scheme implementations.
5084 @c JP
5085 Gaucheの@code{hash-table-for-each}に相当するイテレータはSRFI-69では
5086 @code{hash-table-walk}です。
5087 srfiは既存の実装と名前がぶつからないようにこの名前を採用しました。
5088 @c COMMON
5089 @end itemize
5090
5091 @c EN
5092 The following procedures are the same as Gauche's built-in ones.
5093 @xref{Hashtables}, for the details.
5094 @c JP
5095 以下の手続きはGauche組み込みのものと同じです。
5096 @ref{Hashtables}を参照してください。
5097 @c COMMON
5098
5099 @example
5100 hash-table? hash-table-delete! hash-table-exists?
5101 hash-table-keys hash-table-values hash-table-fold
5102 hash-table->alist hash-table-copy
5103 @end example
5104
5105
5106 @defun make-hash-table :optional eq-pred hash-proc :rest args
5107 [SRFI-69]
5108 @c MOD srfi.69
5109 @c EN
5110 Creates a new hashtable and returns it. This is the same name
5111 as Gauche's built-in procedure, but the arguments are different.
5112 @c JP
5113 新たなハッシュテーブルを作って返します。Gauche組み込みのものと同じ名前ですが、
5114 引数が異なります。
5115 @c COMMON
5116
5117 @c EN
5118 The @var{eq-pred} argument is an equality predicate; it takes
5119 two arguments and returns @code{#t} if two are the same,
5120 and @code{#f} if not. When omitted, @code{equal?} is used.
5121 @c JP
5122 @var{eq-pred}は等価判定述語です。
5123 二つの引数を取り、それらが等価であるとみなされる場合に@code{#t}を返します。
5124 省略された場合は@code{equal?}が使われます。
5125 @c COMMON
5126
5127 @c EN
5128 The @var{hash-proc} argument is a hash function.
5129 It takes two arguments: an object to hash, and a positive
5130 integer to limit the range of the hash value. (Note that
5131 Gauche's native hash functions takes only one argument.)
5132 When omitted, Gauche tries to choose appropriate hash function
5133 if @code{eq-pred} is known one (@code{eq?}, @code{eqv?},
5134 @code{equal?}, @code{string=?} or @code{string-ci=?}).
5135 Otherwise we use @code{scheme.hash-table}'s @code{hash} procedure
5136 (@pxref{R7RS hash tables}).
5137 But there's no guarantee that the generic @code{hash}
5138 works appropriately; you should give
5139 suitable @var{hash-proc} if you pass custom @var{eq-pred}.
5140 @c JP
5141 @var{hash-proc}はハッシュ関数です。ハッシュ値を計算したいオブジェクトと、
5142 ハッシュ値の範囲を指定する正の整数の、二つの引数を取ります。
5143 (Gaucheの組み込みのハッシュ関数は一つの引数しか取らないことに注意してください)。
5144 省略された場合、Gaucheは@code{eq-pred}が既知の関数
5145 (@code{eq?}、@code{eqv?}、@code{equal?}、@code{string=?}、
5146 @code{string-ci=?})であればそれにふさわしいハッシュ関数を提供し、
5147 そうでなければ@code{scheme.hash-table}の@code{hash}を使います
5148 (@ref{R7RS hash tables}参照)。
5149 ただ、ジェネリックな@code{hash}が常にふさわしいとは限りません。
5150 @var{eq-pred}を渡したなら、適切な@var{hash-proc}も渡すべきです。
5151 @c COMMON
5152
5153 @c EN
5154 The returned hash table is an instance of Gauche's native
5155 hash table. You can pass it to Gauche's builtin procedures.
5156 @c JP
5157 返されるハッシュテーブルはGaucheのネイティブハッシュテーブルです。
5158 従ってそれをGaucheの組み込み関数に渡すこともできます。
5159 @c COMMON
5160
5161 @c EN
5162 SRFI-69 allows implementation-specific arguments @var{args} to be
5163 passed to @code{make-hash-table}. At this moment, Gauche
5164 ignores them.
5165 @c JP
5166 SRFI-69は@code{make-hash-table}に実装依存の余分な引数@var{args}
5167 を渡すことを許しています。今のところ、Gaucheは余分な引数は単に無視します。
5168 @c COMMON
5169 @end defun
5170
5171 @defun alist->hash-table alist :optional eq-pred hash-fn :rest args
5172 [SRFI-69]
5173 @c MOD srfi.69
5174 @c EN
5175 Like Gauche's builtin @code{alist->hash-table}, but takes
5176 @var{eq-pred} and @var{hash-fn} separately,
5177 instead of a single comparator.
5178 @c JP
5179 組み込みの@code{alist->hash-table}と似てますが、
5180 単一の比較器ではなく
5181 @var{eq-pred}と@var{hash-fn}を別々に取ります。
5182 @c COMMON
5183
5184 @c EN
5185 The @var{alist} argument is a list of pairs. The car of each
5186 pair is used for a key, and the cdr for its value.
5187 @c JP
5188 @var{alist}引数はペアのリストです。それぞれのペアの
5189 carがキー、cdrが対応する値になります。
5190 @c COMMON
5191
5192 @c EN
5193 See @code{make-hash-table} above for the description of
5194 @var{eq-pred}, @var{hash-fn} and @var{args}.
5195 @c JP
5196 @var{eq-pred}、@var{hash-fn}、および@var{args}についての詳細は
5197 上の@code{make-hash-table}を参照してください。
5198 @c COMMON
5199 @end defun
5200
5201 @defun hash-table-equivalence-function ht
5202 @defunx hash-table-hash-function ht
5203 [SRFI-69]
5204 @c MOD srfi.69
5205 @c EN
5206 Returns equivalence function and hash function of the
5207 hashtable @var{ht}.
5208 @c JP
5209 ハッシュテーブル@var{ht}の等価判定述語とハッシュ関数をそれぞれ返します。
5210 @c COMMON
5211
5212 @c EN
5213 Note that SRFI-69's hash function takes an optional
5214 @var{bound} argument. Since our underlying hash tables
5215 don't use bound argument, we actually wrap the internal hash function
5216 to allow the optional bound argument.
5217 @c JP
5218 SRFI-69のハッシュ関数は省略可能な@var{bound}引数を取ることになっています。
5219 Gaucheのハッシュテーブルのハッシュ関数は@var{bound}引数を取らないので、
5220 @code{hash-table-hash-function}が返す関数はラッパーをかませて
5221 省略可能な@var{bound}引数を取るようにしています。
5222 @c COMMON
5223 @end defun
5224
5225 @defun hash-table-ref ht key :optional thunk
5226 [SRFI-69]
5227 @c MOD srfi.69
5228 @c EN
5229 Looks up the value corresponding to @var{key} in a hash table @var{ht}.
5230 If there's no entry for @var{key}, @var{thunk} is called
5231 without arguments, and its result is returned.
5232 The default of @var{thunk} is to signal an error.
5233 @c JP
5234 ハッシュテーブル@var{ht}からキー@var{key}を探し、対応する値を返します。
5235 @var{key}がテーブル中に無かった場合、@var{thunk}が引数なしで呼ばれ、
5236 その結果が戻り値となります。
5237 @var{thunk}の省略時の値はエラーを投げる手続きです。
5238 @c COMMON
5239
5240 @c EN
5241 This convention differs from Gauche's built-in @code{hash-table-get},
5242 which takes optonal @var{default} argument to be returned when the key
5243 doesn't exist (@pxref{Hashtables}). The following equivalence holds:
5244 @c JP
5245 このインタフェースGauche組み込みの@code{hash-table-get}と異なることに
5246 注意してください。@code{hash-table-get}は省略可能な@var{default}引数を取り、
5247 キーが見つからなかった場合はそれを返します(@ref{Hashtables}参照)。
5248 次の関係が成り立ちます。
5249 @c COMMON
5250
5251 @example
5252 (hash-table-get ht key default) @equiv{} (hash-table-ref ht key (^[] default))
5253 @end example
5254 @end defun
5255
5256 @defun hash-table-ref/default ht key default
5257 [SRFI-69]
5258 @c MOD srfi.69
5259 @c EN
5260 Looks up the value corresponding to @var{key} in a hash table @var{ht}.
5261 If the key doesn't exist, @var{default} is returned.
5262 This is like Gauche's @code{hash-table-get}, but @var{default} can't be
5263 omitted (@pxref{Hashtables}).
5264 @c JP
5265 ハッシュテーブル@var{ht}からキー@var{key}に対応する値を探して返します。
5266 キーが見つからなければ@var{default}が返されます。
5267 組み込みの@code{hash-table-get}と似ていますが、@var{default}
5268 は省略できません(@ref{Hashtables}参照)。
5269 @c COMMON
5270 @end defun
5271
5272 @defun hash-table-set! ht key val
5273 [SRFI-69]
5274 @c MOD srfi.69
5275 @c EN
5276 This is the same as Gauche's @code{hash-table-put!} (@pxref{Hashtables}).
5277 @c JP
5278 Gaucheの@code{hash-table-put!}と同じです(@ref{Hashtables}参照)。
5279 @c COMMON
5280 @end defun
5281
5282 @defun hash-table-update! ht key proc :optional thunk
5283 @defunx hash-table-update!/default ht key proc default
5284 [SRFI-69]
5285 @c MOD srfi.69
5286 @c EN
5287 Calls @var{proc} with the value associated to @var{key} in @var{ht},
5288 and replace the value in @var{ht} with the result of @var{proc}.
5289 The following functional equivalences hold, though these procedures
5290 may be more efficient.
5291 @c JP
5292 @var{ht}中の@var{key}に対応する値を引数として@var{proc}を呼び出し、
5293 @var{ht}中の値を@var{proc}の戻り値で置き換えます。
5294 以下の機能的な等価性が成り立ちますが、これらの手続きの方が効率的かもしれません。
5295 @c COMMON
5296
5297 @example
5298 (hash-table-update! ht key proc thunk)
5299 @equiv{} (hash-table-set! ht key (proc (hash-table-ref ht key thunk)))
5300
5301 (hash-table-update!/default ht key proc default)
5302 @equiv{} (hash-table-set! ht key (proc (hash-table-ref/default ht key default)))
5303 @end example
5304
5305 @c EN
5306 Note that Gauche's built-in @code{hash-table-update!} is different, for
5307 it takes optional @var{default} argument instead of @var{thunk}
5308 (@pxref{Hashtables}).
5309 @c JP
5310 Gauche組み込みの@code{hash-table-update!}は@var{thunk}ではなく@var{default}
5311 を取る点で異なっていることに注意してください(@ref{Hashtables}参照)
5312 @c COMMON
5313 @end defun
5314
5315 @defun hash-table-size ht
5316 [SRFI-69]
5317 @c MOD srfi.69
5318 @c EN
5319 Returns the number of entries in a hash table @var{ht}. The same as Gauche's
5320 @code{hash-table-num-entries}.
5321 @c JP
5322 ハッシュテーブル@var{ht}中のエントリの数を返します。
5323 Gaucheの@code{hash-table-num-entries}と同じです。
5324 @c COMMON
5325 @end defun
5326
5327 @defun hash-table-walk ht proc
5328 [SRFI-69]
5329 @c MOD srfi.69
5330 @c EN
5331 For each entry in a hash table @var{ht},
5332 calls @var{proc} with two arguments, a key and its value.
5333 It's the same as Gauche's @code{hash-table-for-each}.
5334 @c JP
5335 ハッシュテーブル@var{ht}の各エントリにつき、
5336 キーと値を引数として@var{proc}を呼びます。
5337 Gaucheの@code{hash-table-for-each}と同じです。
5338 @c COMMON
5339 @end defun
5340
5341 @defun hash-table-merge! ht1 ht2
5342 [SRFI-69]
5343 @c MOD srfi.69
5344 @c EN
5345 Add all entries in a hash table @var{ht2} into a hash table @var{ht1},
5346 and returns @var{ht1}. Note that @var{ht1} is destructively modified.
5347 If an entry with the same key exists in both @var{ht1} and @var{ht2},
5348 its value in @var{ht1} is replaced with @var{ht2}'s.
5349 @c JP
5350 @var{ht2}の全てのエントリを@var{ht1}に追加し、@var{ht1}を返します。
5351 @var{ht1}は破壊的に変更されることに注意してください。
5352 同じキーを持つエントリが@var{ht1}と@var{ht2}の両方にあった場合は、
5353 @var{ht2}の値で@var{ht1}のエントリが上書きされます。
5354 @c COMMON
5355 @end defun
5356
5357 @defun hash obj :optional bound
5358 [SRFI-69]
5359 @c MOD srfi.69
5360 @c EN
5361 Like Gauche's @code{hash}, except this one can take @var{bound} argument;
5362 if provided, it must be a positive integer, and the return value
5363 is limited between 0 and @code{(- bound 1)}, inclusive.
5364 @c JP
5365 Gaucheの@code{hash}と似ていますが、省略可能な@var{bound}引数を取ります。
5366 @var{bound}引数は与えられるなら正の整数でなければならず、
5367 返される値が0から@code{(- bound 1)} (両端含む) までに制限されます。
5368 @c COMMON
5369 @end defun
5370
5371 @defun string-hash obj :optional bound
5372 @defunx string-ci-hash obj :optional bound
5373 [SRFI-69]
5374 @c MOD srfi.69
5375 @c EN
5376 These are like SRFI-13's (@pxref{String library}), except
5377 these don't take @var{start} and @var{end} argument.
5378 @c JP
5379 SRFI-13の同名の手続きと似ていますが、@var{start}/@var{end}引数は取りません
5380 (@ref{String library}参照)。
5381 @c COMMON
5382 @end defun
5383
5384 @defun hash-by-identity obj :optional bound
5385 [SRFI-69]
5386 @c MOD srfi.69
5387 @c EN
5388 This is Gauche's @code{eq-hash}, except this one can take bound argument.
5389 @c JP
5390 @var{bound}引数を取ること以外はGaucheの@code{eq-hash}と同じです。
5391 @c COMMON
5392 @end defun
5393
5394 @c ----------------------------------------------------------------------
5395 @node Octet-addressed binary blocks, Lightweight testing, Basic hash tables, Library modules - SRFIs
5396 @section @code{srfi.74} - Octet-addressed binary blocks
5397 @c NODE オクテットを単位とするバイナリブロック, @code{srfi.74} - オクテットを単位とするバイナリブロック
5398
5399 @deftp {Module} srfi.74
5400 @mdindex srfi.74
5401 @c EN
5402 This module provides procedures to deal with @emph{blob},
5403 or a sequence of octets. In Gauche, a blob is simply an u8vector.
5404 @c JP
5405 このモジュールは、オクテットの列である@var{blob}を扱う手続きを提供します。
5406 Gaucheではblobは単なるu8vectorです。
5407 @c COMMON
5408
5409 @c EN
5410 Most functionalities of this module is available
5411 in @code{binary.io} module (@pxref{Binary I/O}), and in fact
5412 this module is a thin wrapper to it.
5413 We provide this module for the compatibility.
5414 If you're writing Gauche-specific code, we recommend to use
5415 @code{binary.io} directly.
5416 @c JP
5417 このモジュールの機能はほとんど@code{binary.io}モジュールにあり、
5418 実際、@code{binary.io}の薄いラッパーとして実装されています
5419 (@ref{Binary I/O})。
5420 このモジュールは互換性のために提供されています。Gauche専用のコードを書くなら
5421 @code{binary.io}を直接使うのが良いでしょう。
5422 @c COMMON
5423 @end deftp
5424
5425 @defmac endianness e
5426 [SRFI-74]
5427 @c MOD srfi.74
5428 @c EN
5429 The argument @var{e} must be one of the symbols @code{big}, @code{little},
5430 or @code{native}. It expands to the implementation-specific
5431 endianness designator. In Gauche, the result is one of the
5432 symbols; @pxref{Endianness}, for the details.
5433 @c JP
5434 @var{e}はシンボル@code{big}、@code{little}、@code{native}のいずれかでなければ
5435 なりません。これは、エンディアンネスを示す実装依存のオブジェクトへと展開されます。
5436 Gaucheではそれは単なるシンボルです。詳しくは@ref{Endianness}を参照してください。
5437 @c COMMON
5438 @end defmac
5439
5440 @defun make-blob size
5441 [SRFI-74]
5442 @c MOD srfi.74
5443 @c EN
5444 Returns a freshly created blob that can hold @var{size} octets.
5445 In Gauche, this is the same as @code{(make-u8vector size)}.
5446 @c JP
5447 @var{size}オクテットの大きさを持つblobを新に作って返します。
5448 Gaucheではこれは@code{(make-u8vector size)}と同じです。
5449 @c COMMON
5450 @end defun
5451
5452 @defun blob? obj
5453 [SRFI-74]
5454 @c MOD srfi.74
5455 @c EN
5456 Returns @code{#t} if @var{obj} is a blob, @code{#f} otherwise.
5457 In Gauche, this is the same as @code{(u8vector? obj)}.
5458 @c JP
5459 @var{obj}がblogなら@code{#t}を、そうでなければ@code{#f}を返します。
5460 Gaucheではこれは@code{(u8vector? obj)}と同じです。
5461 @c COMMON
5462 @end defun
5463
5464 @defun blob-length blob
5465 [SRFI-74]
5466 @c MOD srfi.74
5467 @c EN
5468 Returns the size of the blob, in octets. In Gauche,
5469 this is the same as @code{(u8vector-length blob)}.
5470 @c JP
5471 blogのオクテットで測ったサイズを返します。
5472 Gaucheeではこれは@code{(u8vector-length blob)}と同じです。
5473 @c COMMON
5474 @end defun
5475
5476 @defun blob-uint-ref size endian blob pos
5477 @defunx blob-sint-ref size endian blob pos
5478 [SRFI-74]
5479 @c MOD srfi.74
5480 @c EN
5481 Read an unsigned or signed integer of @var{size} octets beginning
5482 at the position of @var{pos} from @var{blob}, respectively.
5483
5484 These are wrappers of @code{(get-uint size blob pos endian)}
5485 and @code{(get-sint size blob pos endian)} in @code{binary.io}
5486 module (@pxref{Binary I/O}), except that
5487 @code{blob-uint-ref}/@code{blob-sint-ref} only accept u8vector
5488 as @var{blob}.
5489 @c JP
5490 @var{size}オクテットからなる符号なし/符号つき整数を、@var{blob}の@var{pos}
5491 オクテット目から取り出します。
5492
5493 これはそれぞれ、@code{binary.io}モジュールを使った
5494 @code{(get-uint size blob pos endian)}および
5495 @code{(get-sint size blob pos endian)}のラッパーです
5496 (@ref{Binary I/O})。
5497 ただし、@code{blob-uint-ref}/@code{blob-sint-ref}は
5498 @var{blob}としてu8vectorしか受け付けません。
5499 @c COMMON
5500 @end defun
5501
5502 @defun blob-uint-set! size endian blob pos val
5503 @defunx blob-sint-set! size endian blob pos val
5504 [SRFI-74]
5505 @c MOD srfi.74
5506 @c EN
5507 Store an unsigned or signed integer @var{val} of @var{size} octets
5508 into @var{blob} starting at the position of @var{pos}, respectively.
5509
5510 These are wrappers of @code{(put-uint! size blob pos val endian)}
5511 and @code{(put-sint! size blob pos val endian)} in @code{binary.io}
5512 module (@pxref{Binary I/O}), except that
5513 @code{blob-uint-set!}/@code{blob-sint-set!} only accept u8vector
5514 as @var{blob}.
5515 @c JP
5516 @var{size}オクテットからなる符号なし/符号つき整数@var{val}を、
5517 @var{blob}の@var{pos}オクテット目から格納します。
5518
5519 これはそれぞれ、@code{binary.io}モジュールを使った
5520 @code{(put-uint! size blob pos val endian)}および
5521 @code{(put-sint! size blob pos val endian)}のラッパーです
5522 (@ref{Binary I/O})。
5523 ただし、@code{blob-uint-set!}/@code{blob-sint-set!}は
5524 @var{blob}としてu8vectorしか受け付けません。
5525 @c COMMON
5526 @end defun
5527
5528 @defun blob-u8-ref blob pos
5529 @defunx blob-u8-set! blob pos val
5530 @defunx blob-s8-ref blob pos
5531 @defunx blob-s8-set! blob pos val
5532 [SRFI-74]
5533 @c MOD srfi.74
5534 @c EN
5535 Get/set an unsigned or signed integer as a octet at @var{pos}
5536 from/to @var{blob}.
5537
5538 These are wrappers of @code{get-u8}, @code{put-u8!},
5539 @code{get-s8} and @code{put-s8!} in @code{binary.io}, respectively.
5540 @c JP
5541 1オクテットの符号つき/符号なし整数を@var{blob}の@var{pos}位置から読み出し/に書き込みます。
5542
5543 これらはそれぞれ、@code{binary.io}モジュールの
5544 @code{get-u8}、@code{put-u8!}、@code{get-s8}および@code{put-s8!}と同じです。
5545 @c COMMON
5546 @end defun
5547
5548 @defun blob-u16-ref endian blob pos
5549 @defunx blob-u16-set! endian blob pos val
5550 @defunx blob-s16-ref endian blob pos
5551 @defunx blob-s16-set! endian blob pos val
5552 @defunx blob-u32-ref endian blob pos
5553 @defunx blob-u32-set! endian blob pos val
5554 @defunx blob-s32-ref endian blob pos
5555 @defunx blob-s32-set! endian blob pos val
5556 @defunx blob-u64-ref endian blob pos
5557 @defunx blob-u64-set! endian blob pos val
5558 @defunx blob-s64-ref endian blob pos
5559 @defunx blob-s64-set! endian blob pos val
5560 [SRFI-74]
5561 @c MOD srfi.74
5562 @c EN
5563 Get/set an unsigned or signed integer of the indicated length
5564 at @var{pos} from/to @var{blob}, using the specified @var{endian}.
5565
5566 These are wrappers of corresponding @code{get-XX} and @code{put-XX!}
5567 in @code{binary.io}; note that the argument orders differ, though.
5568 @c JP
5569 それぞれのサイズの符号つき/符号なし整数を
5570 @var{blob}の@var{pos}位置から@var{endian}のバイトオーダで読み出し/に書き込みます。
5571
5572 これらはそれぞれ、@code{binary.io}モジュールの
5573 @code{get-XX}および@code{put-XX!}手続きのラッパーです。
5574 引数順序が異なることに注意してください。
5575 @c COMMON
5576 @end defun
5577
5578 @defun blob-u16-native-ref blob pos
5579 @defunx blob-u16-native-set! blob pos val
5580 @defunx blob-s16-native-ref blob pos
5581 @defunx blob-s16-native-set! blob pos val
5582 @defunx blob-u32-native-ref blob pos
5583 @defunx blob-u32-native-set! blob pos val
5584 @defunx blob-s32-native-ref blob pos
5585 @defunx blob-s32-native-set! blob pos val
5586 @defunx blob-u64-native-ref blob pos
5587 @defunx blob-u64-native-set! blob pos val
5588 @defunx blob-s64-native-ref blob pos
5589 @defunx blob-s64-native-set! blob pos val
5590 [SRFI-74]
5591 @c MOD srfi.74
5592 @c EN
5593 Get/set an unsigned or signed integer of the indicated length
5594 at @var{pos} from/to @var{blob}, using the native endianness.
5595
5596 These are wrappers of corresponding @code{get-XX} and @code{put-XX!}
5597 in @code{binary.io}; note that the argument orders differ, though.
5598
5599 Note: SRFI-74 only requires these procedures to work with alined @var{pos},
5600 which is the multiple of the size of the integer in octets.
5601 Gauche doesn't have such restriction, but keep this in mind when
5602 you're writing a portable code.
5603 @c JP
5604 それぞれのサイズの符号つき/符号なし整数を
5605 @var{blob}の@var{pos}位置からネイティブバイトオーダで読み出し/に書き込みます。
5606
5607 これらはそれぞれ、@code{binary.io}モジュールの
5608 @code{get-XX}および@code{put-XX!}手続きのラッパーです。
5609 引数順序が異なることに注意してください。
5610
5611 註: SRFI-74は、これらの手続きは@var{pos}がアラインされている場合、
5612 すなわち扱う整数のオクテットでの大きさの整数倍のときだけ動作すれば良いとしています。
5613 Gaucheではそういう制約はありませんが、ポータブルなコードを書く場合は気をつけて下さい。
5614 @c COMMON
5615 @end defun
5616
5617 @defun blob=? blob1 blob2
5618 [SRFI-74]
5619 @c MOD srfi.74
5620 @c EN
5621 This is the same as @code{u8vector=?} in @code{gauche.uvector}.
5622 @c JP
5623 これは@code{gauche.uvector}の@code{u8vector=?}と同じです。
5624 @c COMMON
5625 @end defun
5626
5627 @defun blob-copy! src sstart target tstart n
5628 [SRFI-74]
5629 @c MOD srfi.74
5630 @c EN
5631 Copy @var{n} octets from the source blob @var{src} starting from @var{sstart}
5632 into the target blob @var{target} starting from @var{tstart}.
5633
5634 Note that the order of arguments differs from other @code{*-copy!}
5635 procedures (e.g. R7RS's @code{string-copy!} and @code{vector-copy!},
5636 and @code{gauche.uvector}'s @code{u8vector-copy!})), which have the
5637 following signature: @code{(*-copy! target tstart src sstart send)}
5638 @c JP
5639 blobである@var{src}の@var{ssatrt}から@var{n}オクテットを、
5640 @var{target} blobの@var{tstart}からの位置にコピーします。
5641
5642 引数の順序が他の@code{*-copy!}手続きと異なっているのに注意してください
5643 (R7RSの@code{string-copy!}、@code{vector-copy!}、および@code{gauche.uvector}の
5644 @code{u8vector-copy!}等は、@code{(*-copy! target tstart src sstart send)}
5645 という順序で引数を取ります。)
5646 @c COMMON
5647 @end defun
5648
5649 @defun blob-copy blob
5650 [SRFI-74]
5651 @c MOD srfi.74
5652 @c EN
5653 Returns a fresh copy of @var{blob}. The same as @code{u8vector-copy}
5654 in @code{gauche.uvector}.
5655 @c JP
5656 @var{blob}の新たなコピーを返します。
5657 @code{gauche.uvecto}の@code{u8vector-copy}と同じです。
5658 @c COMMON
5659 @end defun
5660
5661 @defun blob->u8-list blob
5662 @defunx u8-list->blob list
5663 [SRFI-74]
5664 @c MOD srfi.74
5665 @c EN
5666 Wrappers of @code{u8vector->list} and @code{list->u8vector}, except
5667 those don't take optional start/end arguments.
5668 @c JP
5669 @code{u8vector->list}および@code{list->u8vector}のラッパーです。
5670 ただし、省略可能なstart/end引数は取りません。
5671 @c COMMON
5672 @end defun
5673
5674 @defun blob->uint-list size endian blob
5675 @defunx blob->sint-list size endian blob
5676 [SRFI-74]
5677 @c MOD srfi.74
5678 @c EN
5679 Read a sequence of unsigned or signed integers of @var{size} octets from
5680 @var{blob} with @var{endian}, and returns them as a list.
5681 @c JP
5682 それぞれ@var{size}オクテットからなる、バイトオーダー@var{endian}の符号つき/符号なし
5683 整数を連続して@var{blob}から読み出し、リストにして返します。
5684 @c COMMON
5685
5686 @example
5687 (blob->uint-list 3 (endianness big) '#u8(0 0 1 0 0 2 0 0 3))
5688 @result{} (1 2 3)
5689 @end example
5690 @end defun
5691
5692 @defun uint-list->blob size endian list
5693 @defunx sint-list->blob size endian list
5694 [SRFI-74]
5695 @c MOD srfi.74
5696 @c EN
5697 Convert a @var{list} of unsigned or signed integers to a blob.
5698 The resulting blob has @code{(* size (length list))} octets.
5699 Each integer occupies @var{size} octets.
5700 @c JP
5701 符号なし/符号つき整数のリスト@var{list}をblobにして返します。
5702 作られるblobの大きさは@code{(* size (length list))}オクテットで、
5703 sそれぞれの整数が@var{size}オクテットを占めます。
5704 @c COMMON
5705
5706 @example
5707 (uint-list->blob 3 (endianness little) '(1 2 3))
5708 @result{} #u8(1 0 0 2 0 0 3 0 0)
5709 @end example
5710 @end defun
5711
5712 @c ----------------------------------------------------------------------
5713 @node Lightweight testing, Accessing environment variables, Octet-addressed binary blocks, Library modules - SRFIs
5714 @section @code{srfi.78} - Lightweight testing
5715 @c NODE 軽量なテスト, @code{srfi.78} - 軽量なテスト
5716
5717 @deftp {Module} srfi.78
5718 @mdindex srfi.78
5719 @c EN
5720 This srfi defines @code{check} and @code{check-ec} macro, along
5721 with a few helper procedures, to write tests. Especially,
5722 @code{check-ec} uses the same comprehension style as SRFI-42
5723 to run test expressions with various combinations of input easily.
5724 @c JP
5725 このsrfiは、テストを書くためのマクロ@code{check}と@code{check-ec}、
5726 およびいくつかの補助手続きを定義します。
5727 特に、@code{check-ec}はSRFI-42スタイルの内包表記で
5728 パラメータを様々に変えてテストしたい式を評価することができます。
5729 @c COMMON
5730
5731 @c EN
5732 We implemented this module to work with @code{gauche.test}
5733 (@pxref{Unit testing}).
5734 Specifically,
5735 if the check macros are invoked while @code{gauche.test} is active
5736 (that is, between @code{test-start} and @code{test-end}), the check
5737 macros are simply a wrapper of Gauche's @code{test} macro; the results
5738 are tracked and reported by @code{gauche.test}.
5739 @c JP
5740 Gaucheでは、このモジュールは@code{gauche.test}とうまく協働するようになっています
5741 (@ref{Unit testing}参照)。
5742 @code{gauche.test}がアクティブ (つまり@code{test-start}と@code{test-end}の間)に
5743 checkマクロが呼ばれた場合、それは@code{gauche.test}の@code{test}マクロの
5744 ラッパーとなり、テストの結果は@code{gauche.test}側でまとめられて報告されます。
5745 @c COMMON
5746
5747 @c EN
5748 If this module is used without @code{gauche.test}, however, it works as
5749 specified by the srfi, including reporting. So, a tests using this srfi
5750 can be run in both ways---if it is loaded by itself, it runs as vanilla SRFI-78,
5751 and if it is included in a test file that uses @code{gacuhe.test}, it runs
5752 as a part of @code{gauche.test}.
5753 @c JP
5754 このモジュールが@code{gauche.test}と一緒ではなく、単独で使われた場合は、
5755 結果報告も含めsrfiで述べられている通りに動きます。つまり、このsrfiで書かれた
5756 テストは2通りの方法で実行できるということです。それ単独でロードされた場合は
5757 素のSRFI-78として、そして@code{gauche.test}を使うテストファイルからincludeされた
5758 場合は@code{gauche.test}の一部として。
5759 @c COMMON
5760 @end deftp
5761
5762 @defmac check expr => expected
5763 @defmacx check expr (=> equal) expected
5764 [SRFI-78]
5765 @c MOD srfi.78
5766 @c EN
5767 Evaluate @var{expected} and @var{equal}, then evaluate @var{expr} and
5768 compare the results of @var{expected} and @var{expr} using @var{equal}.
5769 In the first form, @code{equal?} is used as @var{equal}.
5770 @c JP
5771 @var{expected}と@var{equal}を評価し、次に@var{expr}を評価してその結果を
5772 @var{expected}の結果と@var{equal}を使って比べます。
5773 最初の形式では、@var{equal}として@code{equal?}が使われます。
5774 @c COMMON
5775 @end defmac
5776
5777 @defmac check-ec qualifier @dots{} expr => expected (argument @dots{})
5778 @defmacx check-ec qualifier @dots{} expr (=> equal) expected (argument @dots{})
5779 @defmacx check-ec qualifier @dots{} expr => expected
5780 @defmacx check-ec qualifier @dots{} expr (=> equal) expected
5781 [SRFI-78]
5782 @c MOD srfi.78
5783 @c EN
5784 Evaluates @var{expr}, @var{equal} and @var{expected} repeatedly
5785 in the environment where the @var{qualifier}s bind variables,
5786 and each time the results of @var{expr} and @var{equal} are
5787 compared with @var{equal}. If the results don't agree,
5788 the failure is recorded with the given @var{argument} @dots{}, which can
5789 be useful to diagnose which combination of bindings the test failed on.
5790 Single failure stops the iteration. If the results of @var{expr} and
5791 @var{expected} agrees on all the iterations, the entire @code{check-ec}
5792 is regarded as success.
5793 @c JP
5794 @var{qualifier}で指定される変数束縛の全ての組み合わせの下で、
5795 @var{expr}、@var{equal}、@var{expected}を繰り返し評価し、
5796 その度に@var{expr}と@var{expected}を@var{equal}で比較します。
5797 もし異なっていれば、それが失敗として記録され、@code{check-ec}全体が失敗として
5798 終了します。全ての組み合わせにおいて@var{expr}と@var{expected}の結果が一致すれば、
5799 @code{check-ec}全体が成功とみなされます。
5800 @c COMMON
5801
5802 @c EN
5803 The way @var{qualifier}s work is the same as SRFI-42.
5804 @xref{Eager comprehensions}, for the details.
5805 @c JP
5806 @var{qualifier}の指定方法はSRFI-42に準じます。
5807 詳しくは@ref{Eager comprehensions}を参照してください。
5808 @c COMMON
5809
5810 @c EN
5811 The following example tests Fermat numbers (2^2^n + 1) are primes.
5812 It fails since F_5 is a composite.
5813 @c JP
5814 次のテストは、フェルマー数 (2^2^n + 1) が素数かどうかを順に調べています。
5815 F_5は合成数なのでテストは失敗します。
5816 @c COMMON
5817
5818 @example
5819 (use math.prime)
5820 (check-ec (: n 6)
5821 (:let fn (+ (expt 2 (expt 2 n)) 1))
5822 (bpsw-prime? fn)
5823 => #t (n))
5824 @result{}
5825 @r{prints} Checking (bpsw-prime? fn), expecting #t => ERROR: got #f, with n: 5
5826 @end example
5827
5828 @c EN
5829 The entire @code{check-ec} form is treated as one check for the sake of
5830 reporting.
5831 @c JP
5832 レポートの観点からは、@code{check-ec}全体がひとつのチェックとして扱われます。
5833 @c COMMON
5834 @end defmac
5835
5836 @defun check-report
5837 [SRFI-78]
5838 @c MOD srfi.78
5839 @c EN
5840 If this module is used stand-alone, prints the summary of test results
5841 to the current output port.
5842
5843 If this module is running inside @code{gauche.test}, this does nothing.
5844 Reporting is done by @code{gauche.test}.
5845 @c JP
5846 このモジュールが単独で使われた場合、現在の出力ポートにこれまでのテスト結果のまとめを
5847 出力します。
5848
5849 このモジュールが@code{gauche.test}と一緒に使われた場合は何もしません。
5850 テスト結果報告は@code{gauche.test}によって行われます。
5851 @c COMMON
5852 @end defun
5853
5854 @defun check-set-mode! mode
5855 [SRFI-78]
5856 @c MOD srfi.78
5857 @c EN
5858 Sets how the test progress and result will be reported. This only has
5859 an effect when check is run without @code{gauche.test}.
5860 @c JP
5861 テストの進行と結果をどう報告するかを指定します。これは@code{gauche.test}と一緒に
5862 使われた時には意味を持ちません。
5863 @c COMMON
5864
5865 @c EN
5866 Valid @var{mode} is one of the following symbols:
5867 @c JP
5868 @var{mode}には次のシンボルのいずれかを指定します。
5869 @c COMMON
5870 @table @code
5871 @item off
5872 @c EN
5873 Do not report the result at all, even from @code{(check-report)}.
5874 @c JP
5875 @code{(check-report)}も含め、結果は一切報告しません。
5876 @c COMMON
5877 @item summary
5878 @c EN
5879 Report the summary of the results when @code{(chec-report)} is called.
5880 @c JP
5881 @code{(chec-report)}が呼ばれた時にまとめを報告するだけです。
5882 @c COMMON
5883 @item report-failed
5884 @c EN
5885 In addition to @code{summary}, report any failed checks as they occur.
5886 @c JP
5887 @code{summary}の動作に加え、チェックが失敗した場合にその都度報告します。
5888 @c COMMON
5889 @item report
5890 @c EN
5891 In addition to @code{summary}, report each result of check as they occur.
5892 @c JP
5893 @code{summary}の動作に加え、チェック毎にその成功失敗を報告します。
5894 @c COMMON
5895 @end table
5896
5897 @c EN
5898 The default is @code{report}.
5899 @c JP
5900 デフォルトは@code{report}です。
5901 @c COMMON
5902 @end defun
5903
5904 @defun check-reset!
5905 [SRFI-78]
5906 @c MOD srfi.78
5907 @c EN
5908 Clears the internal state to keep track of number of performed checks and
5909 failed checks, etc. This doesn't affect @code{gauche.test} bookkeeping.
5910 @c JP
5911 内部のテスト結果記録をクリアします。@code{gauche.test}の結果記録には影響を及ぼしません。
5912 @c COMMON
5913 @end defun
5914
5915 @defun check-passed? expected-total-count
5916 [SRFI-78]
5917 @c MOD srfi.78
5918 @c EN
5919 This can be used to programatically query whether the expected number
5920 of tests are passed since the last @code{check-reset!} or the beginning.
5921 The @var{expected-total-count} must be a number, and it returns @code{#t}
5922 iff the internal count of passed test matches it and there is no failed checks.
5923
5924 This works even if checks are run with @code{gauche.test}.
5925 However, only the tests using @code{check} and @code{check-ec} are counted.
5926 @c JP
5927 これはプログラム内から、最後の@code{check-reset!}もしくはプログラム開始以降に
5928 期待した数のテストが成功したかどうかを調べるのに使えます。
5929 @var{expected-total-count}には期待される成功したテストの数を渡します。
5930 テスト失敗がなく、成功したテストの数が@var{expected-total-count}に一致すれば
5931 @code{#t}が、そうでなければ@code{#f}が返されます。
5932
5933 これは@code{gauche.test}と一緒に使った場合でも有効です。ただし、
5934 カウントされるのは@code{check}と@code{check-ec}の結果のみです。
5935 @c COMMON
5936 @end defun
5937
5938 @c ----------------------------------------------------------------------
5939 @node Accessing environment variables, Purely functional random-access pairs and lists, Lightweight testing, Library modules - SRFIs
5940 @section @code{srfi.98} - Accessing environment variables
5941 @c NODE 環境変数へのアクセス, @code{srfi.98} - 環境変数へのアクセス
5942
5943 @deftp {Module} srfi.98
5944 @mdindex srfi.98
5945 @c EN
5946 This srfi defines a portable way to access the underlying system's
5947 environment variables. Gauche supports such procedures built-in
5948 (@pxref{Environment inquiry}),
5949 but portable programs may want to use srfi API instead.
5950 @c JP
5951 このsrfiはシステムの環境変数にアクセスするポータブルな方法を定義しています。
5952 Gaucheは組み込みで環境変数にアクセスする手続きを持っていますが
5953 (@ref{Environment inquiry}参照)、
5954 ポータブルなコードを書くにはこちらのAPIを使うのが良いでしょう。
5955 @c COMMON
5956 @end deftp
5957
5958 @defun get-environment-variable name
5959 [SRFI-98]
5960 @c MOD srfi.98
5961 @c EN
5962 Returns a string value of an environment variable named by a string @var{name}.
5963 If the named environment variable doesn't exist, @code{#f} is returned.
5964
5965 This is equivalent to @code{sys-getenv}.
5966 @c JP
5967 文字列@var{name}で指定される名前を持つ環境変数の値を文字列で返します。
5968 そのような環境変数が存在しなければ、@code{#f}が返されます。
5969
5970 この手続きは@code{sys-getenv}と等価です。
5971 @c COMMON
5972 @example
5973 (get-environment-variable "PATH")
5974 @result{} "/bin:/usr/sbin:/usr/bin"
5975 @end example
5976 @end defun
5977
5978 @defun get-environment-variables
5979 [SRFI-98]
5980 @c MOD srfi.98
5981 @c EN
5982 Returns an assoc list of the name and the value of each environment
5983 variable.
5984
5985 This is equivalent to @code{sys-environ->alist} without
5986 the optional argument.
5987 @c JP
5988 全ての環境変数の名前と値の連想リストを返します。
5989
5990 この手続きは、省略引数を取らない時の@code{sys-environ->alist}と等価です。
5991 @c COMMON
5992 @example
5993 (get-environment-variables)
5994 @result{} (("PATH" . "/bin:/usr/sbin:/usr/bin")
5995 @dots{})
5996 @end example
5997 @end defun
5998
5999 @c ----------------------------------------------------------------------
6000 @node Purely functional random-access pairs and lists, Basic socket interface, Accessing environment variables, Library modules - SRFIs
6001 @section @code{srfi.101} - Purely functional random-access pairs and lists
6002 @c NODE 純粋に関数的でランダムアクセス可能なペアとリスト, @code{srfi.101} - 純粋に関数的でランダムアクセス可能なペアとリスト
6003
6004 @deftp {Module} srfi.101
6005 @mdindex srfi.101
6006 @c EN
6007 SRFI-101 has become a part of R7RS large.
6008 @xref{R7RS random-access lists}.
6009 @c JP
6010 SRFI-101はR7RS largeに採り入れられました。
6011 @ref{R7RS random-access lists}を参照してください。
6012 @c COMMON
6013
6014 @c EN
6015 Special treatment of @code{cond-expand}: The feature conditional
6016 @code{cond-expand} implicitly makes the checked library loaded
6017 if available. That is, you can usually say
6018 @code{(cond-expand (srfi-N <code>))} where @code{<code>} can assume
6019 SRFI-N is already available, without saying @code{(use srfi.N)}.
6020
6021 However, @code{srfi.101} exports the names that conflicts with
6022 standard primitive pair and list operators, and importing
6023 it without prefix or renaming would surprise you.
6024 To avoid confusion, we don't automatically use @code{srfi.101}
6025 even if it is used as feature conditional.
6026
6027 The recommended way is to use @code{library} feature requirements,
6028 and use @code{srfi.101} with your desired prefix, e.g.
6029 @code{(cond-expand ((library srfi.101) (use srfi.101 :prefix ra:)))}.
6030 @c JP
6031 @code{cond-expand}の特別な扱いについて: @code{cond-expand}は
6032 チェックした機能が使える場合には、必要なライブラリを暗黙にロードします。
6033 つまり、@code{(cond-expand (srfi-N <code>))} とした場合、@code{srfi-N}が
6034 サポートされていれば@code{<code>}の中で@code{(use srfi.N)}とする必要はありません。
6035
6036 しかし、@code{srfi-101}は組み込みの重要なリストやペア操作手続きと同じ名前の
6037 手続きをたくさんエクスポートしているので、プレフィクスやリネーム無しで
6038 インポートすると、びっくりするようなことになるでしょう。
6039 混乱を避けるため、SRFI1-101に限っては、それが機能識別子として使われても
6040 @code{srfi.101}は自動的にはインポートされません。
6041
6042 推奨の方法は、@code{library}指定を使い、明示的なプレフィクスつきで@code{srfi.101}を
6043 useすることです。例えば:
6044 @code{(cond-expand ((library srfi.101) (use srfi.101 :prefix ra:)))}。
6045 @c COMMON
6046 @end deftp
6047
6048 @c ----------------------------------------------------------------------
6049 @node Basic socket interface, Portable runtime environment inquiry, Purely functional random-access pairs and lists, Library modules - SRFIs
6050 @section @code{srfi.106} - Basic socket interface
6051 @c NODE 基本的なソケットインタフェース, @code{srfi.106} - 基本的なソケットインタフェース
6052
6053 @deftp {Module} srfi.106
6054 @mdindex srfi.106
6055 @c EN
6056 A portable basic socket interface.
6057
6058 Although comprehensive network API is provided by @code{gauche.net}
6059 (@pxref{Networking}), it is Gauche-specific. This srfi provides
6060 a small subset of socket operations, but it offers a portable way
6061 to create applications that needs simple networking.
6062
6063 Note that some procedures have the same name as the ones in @code{gauche.net},
6064 but the interface may differ.
6065
6066 A socket object created by this srfi's API is an instance
6067 of Gauche's @code{<socket>}, so it can be passed to the API
6068 in @code{gauche.net} and vice versa.
6069
6070 The following procedures are exactly the same as defined in @code{gauche.net}.
6071 @xref{Networking}, for the details.
6072 @c JP
6073 ポータブルなソケットインタフェースです。
6074
6075 Gaucheは@code{gauche.net}モジュールで包括的なネットワークAPIを提供しています
6076 (@ref{Networking}参照)。しかしそれはGauche特有のものです。
6077 このsrfiはソケット操作の小さなサブセットを提供し、
6078 簡単なネットワーキングを必要とするアプリケーションをポータブルに書けるようにします。
6079
6080 @code{gauche.net}と同じ名前を持ち、インタフェースが異なる手続きがあることに注意してください。
6081
6082 このsrfiのAPIで作られるソケットオブジェクトはGaucheの@code{<socket>}オブジェクト
6083 そのものなので、@code{gauche.net}のAPIに渡したり、またその逆も可能です。
6084
6085 以下にあげる手続きは@code{gauche.net}のものと全く同一です。
6086 説明は@ref{Networking}を参照してください。
6087 @c COMMON
6088
6089 @example
6090 socket-accept socket-shutdown socket-close
6091 socket-input-port socket-output-port
6092 @end example
6093 @end deftp
6094
6095 @c EN
6096 @subheading Socket object
6097 @c JP
6098 @subheading ソケットオブジェクト
6099 @c COMMON
6100
6101 @defun make-client-socket node service :optional ai-family ai-socktype ai-flags ai-protocol
6102 [SRFI-106]
6103 @c MOD srfi.106
6104 @c EN
6105 Creates and returns a socket to
6106 communicate with the node @var{node} and @var{service}.
6107 If the socket type is connection-oriented (that is, @var{ai-socktype} is
6108 @code{*sock-stream*}, which is the default),
6109 the returned socket is already connected.
6110 @c JP
6111 ノード@var{node}のサービス@var{service}と通信するためのソケットを作って返します。
6112 ソケットの型がコネクション指向なら(つまり、@var{ai-socktype}が
6113 @code{*sock-stream*}なら、これはデフォルトですが)、
6114 返されるソケットは既にコネクトされた状態になっています。
6115 @c COMMON
6116
6117 @c EN
6118 Both @var{node} and @var{service} must be strings.
6119 The @var{node} argument is passed to @code{getaddrinfo(3)} to resolve
6120 to the server IP address(es).
6121 A service name solely consists of decimal digits is interpreted as
6122 a port number.
6123 @c JP
6124 @var{node}と@var{service}は文字列でなければなりません。
6125 @var{node}は@code{getaddrinfo(3)}に渡されてサーバのIPアドレスに解決されます。
6126 @var{service}が数字のみで構成されていた場合はポート番号とみなされます。
6127 @c COMMON
6128
6129 @c EN
6130 The default value of optional arguments are as follows:
6131 @code{*af-inet*} for @var{ai-family},
6132 @code{*sock-stream*} for @var{ai-socktype},
6133 @code{(socket-merge-flags *ai-v4mapped* *ai-addrconfig*)} for
6134 @var{ai-flags}, and @code{*ipproto-ip*} for @var{ai-protocol}.
6135 See below for valid flag values.
6136 @c JP
6137 省略可能引数のデフォルト値は次の通りです:
6138 @var{ai-family}は@code{*af-inet*}、
6139 @var{ai-socktype}は@code{*sock-stream*}、
6140 @var{ai-flags}は@code{(socket-merge-flags *ai-v4mapped* *ai-addrconfig*)}、
6141 そして@var{ai-protocol}は@code{*ipproto-ip*}。
6142 有効なフラグの種類については下を参照してください。
6143 @c COMMON
6144
6145 @c EN
6146 This API differs from @code{make-client-socket} in @code{gauche.net}.
6147 @c JP
6148 @code{gauche.net}の@code{make-client-socket}とはAPIが異なることに注意してください。
6149 @c COMMON
6150
6151 @example
6152 (make-client-socket "127.0.0.1" "80")
6153 @result{} a <socket> connected to port 80 of localhost
6154 @end example
6155 @end defun
6156
6157 @defun make-server-socket service :optional ai-family ai-socktype ai-protocol
6158 [SRFI-106]
6159 @c MOD srfi.106
6160 @c EN
6161 Creates and returns a server socket that binds and listens at
6162 the port specified by
6163 @var{service}, which must be a string. A service name solely consists
6164 of decimal digits is interpreted as a port number.
6165 @c JP
6166 @var{service}で指定されるポートで待ち受けるサーバソケットを作って返します。
6167 @var{service}は文字列でなければなりません。@var{service}が全て数字で構成されていた
6168 場合はポート番号と解釈されます。
6169 @c COMMON
6170
6171 @c EN
6172 The default value of optional arguments are as follows:
6173 @code{*af-inet*} for @var{ai-family},
6174 @code{*sock-stream*} for @var{ai-socktype},
6175 and @code{*ipproto-ip*} for @var{ai-protocol}.
6176 See below for valid flag values.
6177 @c JP
6178 省略可能引数のデフォルト値は次の通りです:
6179 @var{ai-family}は@code{*af-inet*}、
6180 @var{ai-socktype}は@code{*sock-stream*}、
6181 @var{ai-protocol}は@code{*ipproto-ip*}。
6182 有効なフラグの種類については下を参照してください。
6183 @c COMMON
6184
6185 @c EN
6186 This API differs from @code{make-server-socket} in @code{gauche.net}.
6187 @c JP
6188 @code{gauche.net}の@code{make-server-socket}とはAPIが異なることに注意してください。
6189 @c COMMON
6190 @end defun
6191
6192 @defun socket? obj
6193 [SRFI-106]
6194 @c MOD srfi.106
6195 @c EN
6196 Equivalent to @code{(is-a? obj <socket>)}.
6197 @c JP
6198 @code{(is-a? obj <socket>)}と同じです。
6199 @c COMMON
6200 @end defun
6201
6202 @c EN
6203 @subheading Communication
6204 @c JP
6205 @subheading 通信
6206 @c COMMON
6207
6208 @defun socket-send socket u8vector :optional flags
6209 [SRFI-106]
6210 @c MOD srfi.106
6211 @c EN
6212 Almost same as @code{socket-send} in @code{gauche.net}, except that
6213 this procedure only accepts a u8vector as the message.
6214 (The one in @code{gauche.net} can take a string as well.)
6215
6216 Returns the number of octets that are actually sent.
6217 @c JP
6218 @code{gauche.net}の@code{socket-send}とほぼ同じですが、
6219 @code{gauche.net}のものが文字列も引数に取ることができるのに対し、
6220 こちらはu8vectorのみを受け付けます。
6221
6222 実際に送られたオクテット数を返します。
6223 @c COMMON
6224 @end defun
6225
6226 @defun socket-recv socket size :optional flags
6227 [SRFI-106]
6228 @c MOD srfi.106
6229 @c EN
6230 This is like @code{socket-recv} in @code{gauche.net}, except that
6231 this procedure returns the received data in u8vector,
6232 instead of a string. If the peer has shut down the connection,
6233 this procedure returns an empty u8vector, @code{#u8()}.
6234
6235 The @var{size} argument specifies the maximum size of the receiving
6236 data. The returned vector may be shorter if that much data is received.
6237 @c JP
6238 @code{gauche.net}の@code{socket-recv}に似ていますが、こちらは
6239 文字列ではなくu8vectorを返します。もし通信の相手がコネクションを閉じていた場合は、
6240 空のu8vector @code{#u8()}が返されます。
6241
6242 @var{size}引数は受信データの最大のサイズを指定します。
6243 受信データがそれより小さい場合は返されるベクタもそれに合わせて短くなります。
6244 @c COMMON
6245 @end defun
6246
6247 @c EN
6248 @subheading Flags
6249 @c JP
6250 @subheading フラグ
6251 @c COMMON
6252
6253 @c EN
6254 The srfi provides common names for constants of typical socket flags,
6255 as well as macros that map symbolic name(s) to the flags.
6256 @c JP
6257 このsrfiでは、典型的なソケットフラグを表す定数と、
6258 名前からフラグ値を求めるマクロも提供しています。
6259 @c COMMON
6260
6261 @defun socket-merge-flags flag @dots{}
6262 [SRFI-106]
6263 @c MOD srfi.106
6264 @c EN
6265 Merge bitwise flags. This is simply @code{logior} in Gauche.
6266 @c JP
6267 与えられた@var{flag} @dots{}をビット演算でマージします。
6268 Gauche組み込みの@code{logior}と実質的に同じです。
6269 @c COMMON
6270 @end defun
6271
6272 @defun socket-purge-flags base-flag flag @dots{}
6273 [SRFI-106]
6274 @c MOD srfi.106
6275 @c EN
6276 Drop the bitwise flags in @var{base-flag} that are set
6277 in @var{flag} @dots{}.
6278 @c JP
6279 @var{base-flag}のビットのうち、@var{flag} @dots{}で示されるビットを0にします。
6280 @c COMMON
6281 @end defun
6282
6283 @subsubheading Address family
6284
6285 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
6286 @vindex *af-inet*
6287 @vindex *af-inet6*
6288 @vindex *af-unspec*
6289 @item @code{*af-inet*} @tab @code{AF_INET}
6290 @item @code{*af-inet6*} @tab @code{AF_INET6}
6291 @item @code{*af-unspec*} @tab @code{AF_UNSPEC}
6292 @end multitable
6293
6294 @defmac address-family name
6295 [SRFI-106]
6296 @c MOD srfi.106
6297 @c EN
6298 @var{Name} can be either one of symbols
6299 @code{inet}, @code{inet6}, or @code{unspec}, and
6300 the macro expands into the value of @code{*af-inet*},
6301 @code{*af-inet6*} or @code{*af-unspec*}, respectively.
6302
6303 If @var{name} is other object, an error is signaled.
6304 @c JP
6305 @var{name}がシンボル@code{inet}、@code{inet6}、@code{unspec}のいずれかであれば、
6306 それぞれ@code{*af-inet*}、@code{*af-inet6*}、@code{*af-unspec*}の値へと展開されます。
6307
6308 @var{name}がそれ以外のオブジェクトならエラーが報告されます。
6309 @c COMMON
6310 @end defmac
6311
6312
6313 @subsubheading Socket domain
6314
6315 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
6316 @vindex *sock-stream*
6317 @vindex *sock-dgram*
6318 @item @code{*sock-stream*} @tab @code{SOCK_STREAM}
6319 @item @code{*sock-dgram*} @tab @code{SOCK_DGRAM}
6320 @end multitable
6321
6322 @defmac socket-domain name
6323 [SRFI-106]
6324 @c MOD srfi.106
6325 @c EN
6326 @var{Name} can be either one of symbols
6327 @code{stream} or @code{datagram}, and the macro
6328 expands into the value of @code{*sock-stream*} and
6329 @code{*sock-dgram*}, respectively.
6330
6331 If @var{name} is other object, an error is signaled.
6332 @c JP
6333 @var{name}がシンボル@code{stream}、@code{datagram}のいずれかであれば、
6334 それぞれ@code{*sock-stream*}、@code{*sock-dgram*}の値へと展開されます。
6335
6336 @var{name}がそれ以外のオブジェクトならエラーが報告されます。
6337 @c COMMON
6338 @end defmac
6339
6340
6341 @subsubheading Address info
6342
6343 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
6344 @vindex *ai-canonname*
6345 @vindex *ai-numerichost*
6346 @vindex *ai-v4mapped*
6347 @vindex *ai-all*
6348 @vindex *ai-addrconfig*
6349 @item @code{*ai-canonname*} @tab @code{AI_CANONNAME}
6350 @item @code{*ai-numerichost*} @tab @code{AI_NUMERICHOST}
6351 @item @code{*ai-v4mapped*} @tab @code{AI_V4MAPPED}
6352 @item @code{*ai-all*} @tab @code{AI_ALL}
6353 @item @code{*ai-addrconfig*} @tab @code{AI_ADDRCONFIG}
6354 @end multitable
6355
6356 @defmac address-info name @dots{}
6357 [SRFI-106]
6358 @c MOD srfi.106
6359 @c EN
6360 Maps combination of names @code{canoname}, @code{numerichost},
6361 @code{v4mapped}, @code{all} and @code{addrconfig}
6362 to the combination of corresponding flags.
6363
6364 An error is signaled if other symbols are passed.
6365 (Note: @code{canoname} for @code{*ai-canonname*}).
6366 @c JP
6367 シンボル@code{canoname}、@code{numerichost}、
6368 @code{v4mapped}、@code{all}、@code{addrconfig}の組み合わせを、
6369 対応するビットフラグの組み合わせへと展開します。
6370
6371 他のシンボルが渡された場合はエラーが報告されます。
6372 (註: @code{*ai-canonname*}に対応するのは@code{canoname}です)。
6373 @c COMMON
6374 @end defmac
6375
6376 @c EN
6377 @subsubheading Protocol
6378 @c JP
6379 @subsubheading プロトコル
6380 @c COMMON
6381
6382 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
6383 @vindex *ipproto-ip*
6384 @vindex *ipproto-tcp*
6385 @vindex *ipproto-udp*
6386 @item @code{*ipproto-ip*} @tab @code{IPPROTO_IP}
6387 @item @code{*ipproto-tcp*} @tab @code{IPPROTO_TCP}
6388 @item @code{*ipproto-udp*} @tab @code{IPPROTO_UDP}
6389 @end multitable
6390
6391 @defmac ip-protocol name
6392 [SRFI-106]
6393 @c MOD srfi.106
6394 @c EN
6395 Maps one of names @code{ip}, @code{tcp}, and @code{udp}
6396 to the corresponding flag value. An error is signaled
6397 if other symbol is passed.
6398 @c JP
6399 シンボル@code{ip}、@code{tcp}、and @code{udp}を
6400 それぞれ対応するフラグの値へと展開します。
6401 他のシンボルが渡されたらエラーを報告します。
6402 @c COMMON
6403 @end defmac
6404
6405 @c EN
6406 @subsubheading Message type
6407 @c JP
6408 @subsubheading メッセージタイプ
6409 @c COMMON
6410
6411 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
6412 @vindex *msg-none*
6413 @vindex *msg-peek*
6414 @vindex *msg-oob*
6415 @vindex *msg-waitall*
6416 @item @code{*msg-none*} @tab 0
6417 @item @code{*msg-peek*} @tab @code{MSG_PEEK}
6418 @item @code{*msg-oob*} @tab @code{MSG_OOB}
6419 @item @code{*msg-waitall*} @tab @code{MSG_WAITALL}
6420 @end multitable
6421
6422 @defmac message-type name @dots{}
6423 [SRFI-106]
6424 @c MOD srfi.106
6425 @c EN
6426 Maps combination of names @code{none}, @code{peek},
6427 @code{oob} and @code{wait-all}
6428 to the combination of corresponding flags.
6429
6430 An error is signaled if other symbols are passed.
6431 (Note: @code{wait-all} for @code{*msg-waitall*}).
6432 @c JP
6433 シンボル@code{none}、@code{peek}、
6434 @code{oob}、@code{wait-all}の組み合わせを、
6435 対応するビットフラグの組み合わせへと展開します。
6436
6437 他のシンボルが渡された場合はエラーが報告されます。
6438 (註: @code{*msg-waitall*}に対応するのは@code{wait-all}です)。
6439 @c COMMON
6440 @end defmac
6441
6442 @c EN
6443 @subsubheading Shutdown method
6444 @c JP
6445 @subsubheading シャットダウン
6446 @c COMMON
6447
6448 @multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
6449 @vindex *shut-rd*
6450 @vindex *shut-wr*
6451 @vindex *shut-rdwr*
6452 @item @code{*shut-rd*} @tab @code{SHUT_RD}
6453 @item @code{*shut-wr*} @tab @code{SHUT_WR}
6454 @item @code{*shut-rdwr*} @tab @code{SHUT_RDWR}
6455 @end multitable
6456
6457 @defmac shutdown-method name @dots{}
6458 [SRFI-106]
6459 @c MOD srfi.106
6460 @c EN
6461 Maps combination of names @code{read} and @code{write}
6462 to the combination of corresponding flags.
6463
6464 An error is signaled if other symbols are passed.
6465 @c JP
6466 シンボル@code{code}と@code{write}の組み合わせを対応するビットマスクの値へと展開します。
6467
6468 他のシンボルが渡された場合はエラーが報告されます。
6469 @c COMMON
6470 @end defmac
6471
6472 @c ----------------------------------------------------------------------
6473 @node Portable runtime environment inquiry, Comparators, Basic socket interface, Library modules - SRFIs
6474 @section @code{srfi.112} - Environment inquiry
6475 @c NODE ポータブルな実行環境の問い合わせ, @code{srfi.112} - 実行環境の問い合わせ
6476
6477 @deftp {Module} srfi.112
6478 @mdindex srfi.112
6479 @c EN
6480 This srfi provides a portable way to obtain runtime information.
6481 @c JP
6482 このsrfiは実行時の情報を問い合わせるポータブルな方法を提供します。
6483 @c COMMON
6484 @end deftp
6485
6486 @defun implementation-name
6487 [SRFI-112]
6488 @c MOD srfi.112
6489 @c EN
6490 The name of the implementation.
6491 Returns a string @code{"Gauche"}.
6492 @c JP
6493 実装の名前。文字列@code{"Gauche"}が返ります。
6494 @c COMMON
6495 @end defun
6496
6497 @defun implementation-version
6498 [SRFI-112]
6499 @c MOD srfi.112
6500 @c EN
6501 Returns a string of Gauche's version. The same as @code{gauche-version}
6502 (@pxref{Environment inquiry}).
6503 @c JP
6504 Gaucheのバージョンを示す文字列が返ります。
6505 @code{gauche-version}と同じです (@ref{Environment inquiry}参照)。
6506 @c COMMON
6507 @end defun
6508
6509 @defun cpu-architecture
6510 [SRFI-112]
6511 @c MOD srfi.112
6512 @c EN
6513 Returns a string of CPU architecture info, such as @code{"x86_64"}.
6514 Same as the @code{machine} field of the return value of @code{sys-uname}
6515 (@pxref{System inquiry}).
6516 @c JP
6517 CPUアーキテクチャの情報(@code{"x86_64"}など)を文字列で返します。
6518 @code{sys-uname}の@code{machine}フィールドと同じです(@ref{System inquiry}参照)。
6519 @c COMMON
6520 @end defun
6521
6522 @defun machine-name
6523 [SRFI-112]
6524 @c MOD srfi.112
6525 @c EN
6526 Returns the host name. Same as the @code{nodename} field of
6527 the return value of @code{sys-uname}.
6528 (@pxref{System inquiry}).
6529 @c JP
6530 ホスト名を返します。@code{sys-uname}の@code{nodename}フィールドと同じです
6531 (@ref{System inquiry}参照)。
6532 @c COMMON
6533 @end defun
6534
6535 @defun os-name
6536 [SRFI-112]
6537 @c MOD srfi.112
6538 @c EN
6539 Returns the OS name. Same as the @code{sysname} field
6540 of the return value of @code{sys-uname}.
6541 @c JP
6542 OSの名前を返します。@code{sys-uname}の@code{sysname}フィールドと同じです
6543 (@ref{System inquiry}参照)。
6544 @c COMMON
6545 @end defun
6546
6547 @defun os-version
6548 [SRFI-112]
6549 @c MOD srfi.112
6550 @c EN
6551 Returns the OS version. Same as the @code{release} field
6552 of the return value of @code{sys-uname}.
6553 @c JP
6554 OSのバージョンを返します。@code{sys-uname}の@code{release}フィールドと同じです
6555 (@ref{System inquiry}参照)。
6556 @c COMMON
6557 @end defun
6558
6559 @c EN
6560 Here's an example of output. It is likely to differ on your environment.
6561 @c JP
6562 出力の例を示します。あなたの実行環境では多分違った値になるでしょう。
6563 @c COMMON
6564
6565 @example
6566 gosh> (implementation-name)
6567 "Gauche"
6568 gosh> (implementation-version)
6569 "0.9.5"
6570 gosh> (cpu-architecture)
6571 "x86_64"
6572 gosh> (machine-name)
6573 "scherzo"
6574 gosh> (os-name)
6575 "Linux"
6576 gosh> (os-version)
6577 "3.2.0-89-generic"
6578 @end example
6579
6580
6581 @c ----------------------------------------------------------------------
6582 @node Comparators, Simple adjustable-size strings, Portable runtime environment inquiry, Library modules - SRFIs
6583 @section @code{srfi.114} - Comparators
6584 @c NODE 比較器, @code{srfi.114} - 比較器
6585
6586 @deftp {Module} srfi.114
6587 @mdindex srfi.114
6588 @c EN
6589 This module is provided for the compatibility of code using SRFI-114.
6590 The new code should use SRFI-128, which is fully built-in.
6591 @c JP
6592 このモジュールはSRFI-114を使っているコードとの互換性のために提供されています。
6593 新規コードはSRFI-128を使ってください。そちらは組み込みになっています。
6594 @c COMMON
6595
6596 @c EN
6597 Note that SRFI-114's @code{make-comparator} has different interface from
6598 built-in (SRFI-128) @code{make-comparator}.
6599 If you simply say @code{(use srfi.114)} or @code{(import (srfi 114))},
6600 it shadows the built-in one. If you need to use some of SRFI-114
6601 procedures, it's better to import them selectively.
6602 @c JP
6603 SRFI-114の@code{make-comparator}は組み込み(SRFI-128)の@code{make-comparator}
6604 と異なるインタフェースを持つことに注意してください。
6605 単に@code{(use srfi.114)}や@code{(import (srfi 114))}とすると、
6606 組み込みの@code{make-comparator}がシャドウされます。
6607 SRFI-114のいくつかの手続きだけを使いたいなら、それらを選択的にインポートするのが良いでしょう。
6608 @c COMMON
6609
6610 @c EN
6611 Note that comparators created with SRFI-114 procedures are the same
6612 type as the ones created with SRFI-128 procedures and can be used
6613 interchangebly.
6614 @c JP
6615 SRFI-114手続きで作られる比較器は、SRFI-128で作られる比較器と同じ型で、
6616 互いにどちらの手続きにも渡すことができます。
6617 @c COMMON
6618
6619 @c EN
6620 The following procedures are built-in. @xref{Basic comparators}, for
6621 the detailed documentation. Those are also exported from @code{srfi.114}
6622 for the compatibility.
6623 @c JP
6624 以下の手続きは組み込みで提供されます。
6625 説明は@ref{Basic comparators}を参照してください。
6626 互換性のために、これらは@code{srfi.114}モジュールからもエクスポートされます。
6627 @c COMMON
6628
6629 @table @asis
6630 @item Predicates
6631 @code{comparator?},
6632
6633 @item Standard comparators
6634 @code{boolean-comparator},
6635 @code{char-comparator},
6636 @code{char-ci-comparator},
6637 @code{string-comparator},
6638 @code{string-ci-comparator},
6639 @code{symbol-comparator},
6640 @code{exact-integer-comparator},
6641 @code{integer-comparator},
6642 @code{rational-comparator},
6643 @code{real-comparator},
6644 @code{complex-comparator},
6645 @code{number-comparator},
6646 @code{pair-comparator},
6647 @code{list-comparator},
6648 @code{vector-comparator},
6649 @code{bytevector-comparator},
6650 @code{uvector-comparator}
6651
6652 @item The default comparator
6653 @code{default-comparator}
6654
6655 @item Wrapped equality predicates
6656 @code{eq-comparator},
6657 @code{eqv-comparator},
6658 @code{equal-comparator}
6659
6660 @item Accessors
6661 @code{comparator-equality-predicate},
6662 @code{comparator-comparison-procedure},
6663 @code{comparator-hash-function}
6664
6665 @item Primitive applicators
6666 @code{comparator-test-type},
6667 @code{comparator-check-type},
6668 @code{comparator-compare},
6669 @code{comparator-hash}
6670
6671 @item Comparison predicates
6672 @code{=?},
6673 @code{<?},
6674 @code{<=?},
6675 @code{>?},
6676 @code{>=?}
6677 @end table
6678
6679 @end deftp
6680
6681 @subsubheading Basic comparator interface
6682
6683 @defun make-comparator type-test equal compare hash :optional name
6684 [SRFI-114+]
6685 @c MOD srfi.114
6686 @c EN
6687 This is SRFI-114 style comparator constructor. The optional @var{name}
6688 argument is Gauche's extension.
6689 @c JP
6690 SRFI-114形式の比較器コンストラクタです。省略可能引数@var{name}はGaucheの拡張です。
6691 @c COMMON
6692
6693 @c EN
6694 This is the same as built-in @code{make-comparator/compare}.
6695 @xref{Basic comparators}, for the details.
6696 @c JP
6697 この手続きは組み込みの@code{make-comparator/compare}と同じです。
6698 詳しくは@ref{Basic comparators}を参照してください。
6699 @c COMMON
6700
6701 @c EN
6702 Do not confuse this with built-in (SRFI-128) @code{make-comparator};
6703 if you @code{(use srfi.114)}, this one shadows the built-in one.
6704 @c JP
6705 組み込み (SRFI-128) の@code{make-comparator}と混同しないようにしてください。
6706 単に@code{(use srfi.114)}とすると、組み込みのそれがSRFI-114でシャドウされます。
6707 @c COMMON
6708
6709 @c EN
6710 Note that a comparator works for both SRFI-114 and SRFI-128 procedures,
6711 regardless of how it is constructed.
6712 @c JP
6713 比較器はどちらで作られたかにかかわらず、SRFI-114の手続きにもSRFI-128の手続きにも
6714 渡すことができます。
6715 @c COMMON
6716 @end defun
6717
6718 @defun comparator-comparison-procedure? c
6719 @defunx comparator-hash-function? c
6720 [SRFI-114]
6721 @c MOD srfi.114
6722 Returns true iff a comparator @var{c} can be used to order objects
6723 or to hash them, respectively. These are aliases of
6724 built-in @code{comparator-ordered?} and @code{comparator-hashable?}.
6725 @end defun
6726
6727 @defun comparator-type-test-procedure c
6728 [SRFI-114]
6729 @c MOD srfi.114
6730 Returns type test predicate of a comparator @var{c}.
6731 This is an alias of built-in @code{comparator-type-test-predicate}.
6732 @end defun
6733
6734 @defun comparator-equal? c a b
6735 [SRFI-114]
6736 @c MOD srfi.114
6737 Checks equality of @var{a} and @var{b} using the equality predicate
6738 of a comparator @var{c}. This can be also written in @code{=?}, which
6739 is built-in (@pxref{Comparator predicates and accessors}).
6740 @example
6741 (=? c a b)
6742 @end example
6743 @end defun
6744
6745
6746 @subsubheading Auxiliary comparator constructors
6747
6748 @defun make-inexact-real-comparator epsilon rounding nan-handling
6749 [SRFI-114]
6750 @c MOD srfi.114
6751 Returns a comparator for inexact real numbers, taking into
6752 account of errors and NaNs.
6753
6754 The basic idea is that we compare two finite real numbers
6755 after rounding them to @var{epsilon} interval, which must be
6756 a nonnegative real number.
6757 (Note that it's not to compare two numbers ``close enough'', as often
6758 being done to compare inexact numbers. ``Close enough'' scheme
6759 won't be transitive.)
6760
6761 The rounding mode is specified by the @var{rounding} argument.
6762 It can be either one of the symbols @code{round}, @code{ceiling},
6763 @code{floor} or @code{truncate}, or a procedure that takes
6764 two arguments, a real number and an epsilon, and returns
6765 the rounded result of the first argument according to the
6766 given epsilon.
6767
6768 The @var{nan-handling} argument determines how to handle the
6769 case to compare NaN and non-NaN numbers. (If both are NaNs,
6770 this comparator regards them as equal). It can be either
6771 one of the followings:
6772 @table @asis
6773 @item @code{min}
6774 If it's a symbol @code{min}, NaN is compared as smaller than
6775 all other real numbers, even than @code{-inf.0}.
6776 @item @code{max}
6777 If it's a symbol @code{min}, NaN is compared as greater than
6778 all other real numbers, even than @code{+inf.0}.
6779 @item @code{error}
6780 If it's a symbol @code{error}, an error is signaled.
6781 @item a procedure taking one argument
6782 The procedure is invoked with the real number which is not NaN.
6783 If it ever returns, it must return either 1, 0 or -1, for
6784 it's used as the result of the comparison procedure of
6785 the comparator. However, since the procedure doesn't know
6786 @emph{which} argument is non-NaN, it's hard to have consistent
6787 semantics; the best bet is to throw a custom error.
6788 @end table
6789
6790 @example
6791 (define c (make-inexact-real-comparator 0.1 'round 'error))
6792
6793 (comparator-compare c 0.112 0.098) @result{} 0
6794 (comparator-compare c 0.131 0.172) @result{} -1
6795 @end example
6796
6797 Note: Rounding to the nearest epsilon interval would involve
6798 scaling inexact numbers, and that may reveal small difference
6799 between the actual number and its notation. For example,
6800 an inexact real number denoted as @code{0.15} is actually
6801 slightly smaller than @code{15/100}, and rounding with epsilon
6802 @code{0.1} would result @code{0.1}, not @code{0.2}.
6803 @end defun
6804
6805 @defun make-car-comparator cmpr
6806 @defunx make-cdr-comparator cmpr
6807 [SRFI-114]
6808 @c MOD srfi.114
6809 @c EN
6810 Returns comparators that accept pairs, and compare them with
6811 their car or cdr by @var{cmpr}, respectively.
6812
6813 Using @code{make-key-comparator}, these cam be written as follows
6814 (@pxref{Combining comparators}, for @code{make-key-comparator}).
6815 @c JP
6816 ペアを受け取り、その@code{car}のみまたは@code{cdr}のみを@var{cmpr}で
6817 比較するような比較器を返します。
6818
6819 @code{make-key-comparator}を使えばこれらは以下の通りに書けます。
6820 (@code{make-key-comparator}については@ref{Combining comparators}を参照)。
6821 @c COMMON
6822 @example
6823 (define (make-car-comparator cmpr)
6824 (make-key-comparator cmpr pair? car))
6825
6826 (define (make-cdr-comparator cmpr)
6827 (make-key-comparator cmpr pair? cdr))
6828 @end example
6829 @end defun
6830
6831 @defun make-list-comparator element-comparator
6832 @defunx make-vector-comparator element-comparator
6833 @defunx make-bytevector-comparator element-comparator
6834 [SRFI-114]
6835 @c MOD srfi.114
6836 Returns a new comparator that compares lists, vectors and
6837 bytevectors element-wise using @var{element-comparator},
6838 respectively. These are more general versions of
6839 @code{list-comparator}, @code{vector-comparator} and
6840 @code{bytevector-comparator}, which use @code{default-comparator}
6841 as @var{element-comparator}.
6842
6843 For a list comparator, it is an error to pass improper lists.
6844
6845 Note that comparing sequences of different lengths is slightly
6846 different between lists and vector/bytevectors. List comparator
6847 uses ``dictionary'' order, so @code{(1 3)} comes after @code{(1 2 3)},
6848 assuming elements are compared numerically.
6849 For vectors and bytevectors, shorter one always precedes the other,
6850 so @code{#(1 3)} comes before @code{#(1 2 3)}.
6851 @end defun
6852
6853 @defun make-listwise-comparator type-test element-comparator empty? head tail
6854 [SRFI-114]
6855 @c MOD srfi.114
6856 More general version of @code{make-list-comparator}.
6857 Returns a comparator that compares structures which can be
6858 traversed using three procedures, @var{empty?}, @var{head} and @var{tail}.
6859 Each of those procedure receives a structure to be compared, and @var{empty?}
6860 must return @code{#t} iff the structure is empty, @var{head}
6861 must return the first element in the structure, and @var{tail}
6862 must return the same type of structure containing all the elements
6863 but the head. The @var{type-test} predicate checks if the arguments
6864 passed to the comparator to be a suitable structure.
6865
6866 That is, @code{make-list-comparator} can be written in
6867 @code{make-listwise-comparator} as follows.
6868 @example
6869 (make-list-compartator element-comparator)
6870 @equiv{}
6871 (make-listwise-comparator list? element-comparator null? car cdr)
6872 @end example
6873
6874 This can be used to compare list-like structures. For example,
6875 the following call returns a comparator that compares elements
6876 of two lazy streams (@pxref{Stream library}).
6877
6878 @example
6879 (make-listwise-comparator stream?
6880 element-comparator
6881 stream-null?
6882 stream-car
6883 stream-cdr)
6884 @end example
6885 @end defun
6886
6887 @defun make-vectorwise-comparator type-test element-comparator length ref
6888 [SRFI-114]
6889 @c MOD srfi.114
6890 More general version of @code{make-vector-comparator}.
6891 Returns a comparator that compares structures which can be
6892 traversed using two procedures, @var{length} and @var{ref}.
6893 The @var{length} procedure must return the number of elements in the
6894 structure. The @var{ref} procedure receives a structure and a nonnegative
6895 exact integer index @var{k}, and must return @var{k}-th element
6896 of the structure.
6897
6898 That is, the following equivalence holds:
6899 @example
6900 (make-vector-comparator element-comparator)
6901 @equiv{}
6902 (make-vectorwise-comparator vector? element-comparator
6903 vector-length vector-ref)
6904
6905 (make-bytevector-comparator element-comparator)
6906 @equiv{}
6907 (make-vectorwise-comparator u8vector? element-comparator
6908 u8vector-length u8vector-ref)
6909 @end example
6910 @end defun
6911
6912 @defun make-pair-comparator car-comparator cdr-comparator
6913 [SRFI-114]
6914 @c MOD srfi.114
6915 Creates a comparator that compares pairs, with their cars
6916 by @var{car-comparator} and their cdrs by @var{cdr-comparator}.
6917 @end defun
6918
6919 @defun make-improper-list-comparator element-comparator
6920 [SRFI-114]
6921 @c MOD srfi.114
6922 This may be understood as recursive pair comparator; if objects
6923 to be compared are pairs, we recurse their cars then their cdrs.
6924 If objects to be compared are not pairs, we use @var{element-comparator}
6925 to compare them.
6926 @end defun
6927
6928 @defun make-selecting-comparator comparator1 comparator2 @dots{}
6929 [SRFI-114]
6930 @c MOD srfi.114
6931 This creates a comparator that works any one of the given comparators;
6932 the objects to be compared are type-tested with each of the comparators
6933 in order, and the first comparator that accepts all objects will be used.
6934 @end defun
6935
6936 @defun make-refining-comparator comparator1 comparator2 @dots{}
6937 [SRFI-114]
6938 @c MOD srfi.114
6939 This is similar to @code{make-selecting-comparator}, except that
6940 if the first comparator that accepts given objects to compare finds
6941 they are equal (or 0 by the comparison procedure), it tries other
6942 comparators down the list, if any.
6943 @end defun
6944
6945 @defun make-reverse-comparator comparator
6946 [SRFI-114]
6947 @c MOD srfi.114
6948 Returns a comparator that just reverses the comparison order of
6949 @var{comparator}.
6950 @end defun
6951
6952 @defun make-debug-comparator comparator
6953 [SRFI-114]
6954 @c MOD srfi.114
6955 @end defun
6956
6957 @subsubheading Comparison procedure constructors
6958
6959 @defun make-comparison< lt-pred
6960 @defunx make-comparison> gt-pred
6961 @defunx make-comparison<= le-pred
6962 @defunx make-comparison>= ge-pred
6963 @defunx make-comparison=/< eq-pred lt-pred
6964 @defunx make-comparison=/> eq-pred gt-pred
6965 [SRFI-114]
6966 @c MOD srfi.114
6967 Utility procedures to create a comparison procedure (the one returns
6968 -1, 0, or 1) from the given predicate. For example,
6969 @code{make-comparison<} can be defined as follows:
6970
6971 @example
6972 (define (make-comparison< pred)
6973 (^[a b] (cond [(pred a b) -1]
6974 [(pred b a) 1]
6975 [else 0])))
6976 @end example
6977 @end defun
6978
6979 @subsubheading Comparison syntax
6980
6981 @defmac if3 expr less equal greater
6982 [SRFI-114]
6983 @c MOD srfi.114
6984 Three-way @code{if}: Evaluates @var{expr}, and then evaluates
6985 either one of @var{less}, @var{equal}, or @var{greater},
6986 depending on the value of @var{expr} is either less than zero,
6987 equal to zero, or greater than zero, respectively.
6988 @end defmac
6989
6990 @defmac if=? expr consequent :optional alternate
6991 @defmacx if<? expr consequent :optional alternate
6992 @defmacx if>? expr consequent :optional alternate
6993 @defmacx if<=? expr consequent :optional alternate
6994 @defmacx if>=? expr consequent :optional alternate
6995 @defmacx if-not=? expr consequent :optional alternate
6996 [SRFI-114]
6997 @c MOD srfi.114
6998 Conditional evaluation according to comparison expression @var{expr};
6999 that is, @code{if@var{OP}?} evaluates @var{consequent} if
7000 @code{(@var{OP} expr 0)} is true, otherwise it evaluates @var{alternate}
7001 when provided.
7002
7003 @example
7004 (if<? (compare 10 20) 'yes) @result{} yes
7005 (if>=? (compare 10 20) 'yes 'no) @result{} no
7006 @end example
7007 @end defmac
7008
7009 @subsubheading Comparison predicate constructors
7010
7011 @defun make=? comparator
7012 @defunx make<? comparator
7013 @defunx make>? comparator
7014 @defunx make<=? comparator
7015 @defunx make>=? comparator
7016 [SRFI-114]
7017 @c MOD srfi.114
7018 @example
7019 ((make=? comparator) obj1 obj2 obj3 @dots{})
7020 @equiv{} (=? comparator obj1 obj2 obj3 @dots{})
7021 @end example
7022 @end defun
7023
7024 @subsubheading Interval comparison predicates
7025
7026
7027 @defun in-open-interval? [comparator] obj1 obj2 obj3
7028 @defunx in-closed-interval? [comparator] obj1 obj2 obj3
7029 @defunx in-open-closed-interval? [comparator] obj1 obj2 obj3
7030 @defunx in-closed-open-interval? [comparator] obj1 obj2 obj3
7031 [SRFI-114]
7032 @c MOD srfi.114
7033 Check if @var{obj1}, @var{obj2} and @var{obj3} has the following
7034 relationships:
7035
7036 @example
7037 (and (op1 obj1 obj2) (op2 obj2 obj3))
7038 @end example
7039
7040 Where each of @var{op1} and @var{op2} can be
7041 @code{(make<? comparator)} (if that end is @emph{open}),
7042 or @code{(make<=? comparator)} (if that end is @emph{closed}).
7043
7044 When @var{comparator} is omitted, the default comparator is used.
7045
7046 @example
7047 (use srfi.42)
7048 (list-ec (: x 0 5) (list x (in-closed-open-interval? 1 x 3)))
7049 @result{} ((0 #f) (1 #t) (2 #t) (3 #f) (4 #f))
7050 @end example
7051 @end defun
7052
7053 @subsubheading Min/max comparison procedures
7054
7055 @code{comparator-min} and @code{comparator-max} are the
7056 same as @code{srfi.162}. @xref{Comparator sublibrary}.
7057
7058
7059 @c ----------------------------------------------------------------------
7060 @node Simple adjustable-size strings, Timer APIs, Comparators, Library modules - SRFIs
7061 @section @code{srfi.118} - Simple adjustable-size strings
7062 @c NODE 簡単な可変長文字列, @code{srfi.118} - 簡単な可変長文字列
7063
7064 @deftp {Module} srfi.118
7065 @mdindex srfi.118
7066 @c EN
7067 This SRFI defines two string mutating operations that can change
7068 the length of the string: @code{string-append!} and @code{string-replace!}.
7069
7070 Note that, in Gauche, the body of strings is immutable; when you mutate
7071 a string, Gauche creates a fresh new string body and just switch a pointer
7072 in the original string to point the new string body. So it is not a
7073 problem to implement this SRFI in Gauche, but it also means you won't
7074 get any performance benefit by using these operations. Using immutable
7075 counterparts (@code{string-append} and @code{string-replace}) gives
7076 you the same performance. (Be aware that the interface is slightly
7077 different from the immutable versions.)
7078
7079 We provide this module only for the compatibility. Gauche-specific
7080 programs should stay away from this module. Particularly, avoid
7081 code like the example in SRFI-118 document (build a string by
7082 @code{append!}-ing small chunks at a time)---they're quadratic on Gauche.
7083 @c JP
7084 このSRFIは、文字列の長さを変えるような破壊的変更を行う文字列操作ルーチンを
7085 提供します。
7086
7087 Gaucheでは、文字列の本体は変更不可になっています。
7088 文字列の破壊的変更は、
7089 実際には新たな文字列本体を作成して、元の文字列が指している本体とポインタを
7090 置き換えることで実現されます。
7091 ですのでこのsrfiをGaucheに実装すること自体は全く問題ないのですが、
7092 これらのAPIを使ったからといって性能上の恩恵にあずかれるわけではありません。
7093 変更不可な文字列を@code{string-append} and @code{string-replace}で
7094 切り貼りするのと、性能的には何ら変わりません。
7095 (このモジュールのAPIは、変更不可文字列を扱うAPIと若干異なることに注意してください。)
7096
7097 このモジュールは、互換性のためだけ提供されます。
7098 Gaucheに依存したプログラムはこのモジュールを使う必要はないでしょう。
7099 特に、SRFI-118のドキュメントにある例は避けるのが懸命です
7100 (文字列を、小さな塊ごとに破壊的にappendしてゆくという実装ですが、
7101 Gaucheではそれは文字列の長さの2乗に比例した時間がかかってしまいます)。
7102 @c COMMON
7103 @end deftp
7104
7105 @defun string-append! string values @dots{}
7106 [SRFI-118]
7107 @c MOD srfi.118
7108 @c EN
7109 The @var{string} argument must be a mutable string.
7110 Modify @var{string} by appending @var{values}, each of which is
7111 either a character or a string.
7112 @c JP
7113 @var{string}引数は変更可能な文字列でなければなりません。
7114 残りの引数@var{values}はそれぞれ文字または文字列です。それらを@var{string}に
7115 破壊的に追加します。
7116 @c COMMON
7117
7118 @example
7119 (rlet1 a (string-copy "abc")
7120 (string-append! a #\X "YZ"))
7121 @result{} "abcXYZ"
7122 @end example
7123 @end defun
7124
7125 @defun string-replace! dst dst-start dst-end src :optional src-start src-end
7126 [SRFI-118]
7127 @c MOD srfi.118
7128 @c EN
7129 The @var{dst} argument must be a mutable string.
7130 Replace @var{dst} between @var{dst-start} (inclusive) and
7131 @var{dst-end} (exclusive) with a string @var{src}. The optional
7132 arguments @var{src-start} and @var{src-end} limits the region of
7133 @var{src} to be used.
7134 @c JP
7135 @var{dst}引数は変更可能な文字列でなければなりません。
7136 @var{dst}中の、@var{dst-start}(inclusive)から@var{dst-end}(exclusive)までの
7137 内容が文字列@var{src}で置き換えられます。省略可能引数
7138 @var{src-start}と@var{src-end}で、@var{src}の使う部分を制限することができます。
7139 @c COMMON
7140
7141 @c EN
7142 Be aware that the order of arguments differ from
7143 SRFI-13's @code{string-replace} (@pxref{SRFI-13 Other string operations});
7144 @code{string-replace!} resembles to @code{string-copy!} (also in SRFI-13),
7145 rather than @code{string-replace}.
7146 @c JP
7147 引数の順序がSRFI-13の@code{string-replace}とは異なることに
7148 注意して下さい (@ref{SRFI-13 Other string operations}参照)。
7149 @code{string-replace!}の引数順は同じくSRFI-13にある@code{string-copy!}に
7150 似せてあります。
7151 @c COMMON
7152
7153 @example
7154 (rlet1 a (string-copy "abc")
7155 (string-replace! a 1 2 "XYZ"))
7156 @result{} "aXYZc"
7157 @end example
7158 @end defun
7159
7160
7161 @c ----------------------------------------------------------------------
7162 @node Timer APIs, Titlecase procedures, Simple adjustable-size strings, Library modules - SRFIs
7163 @section @code{srfi.120} - Timer APIs
7164 @c NODE タイマーAPI, @code{srfi.120} - タイマーAPI
7165
7166 @deftp {Module} srfi.120
7167 @mdindex srfi.120
7168 @c EN
7169 This srfi provides a device to run tasks in a specified time.
7170
7171 In Gauche, this is a thin wrapper of @code{control.scheduler} module
7172 (@pxref{Scheduler}, for the details). Use this module if you need portability.
7173 @c JP
7174 このsrfiは、タスクを指定した時間に実行するデバイスを提供します。
7175
7176 Gaucheではこれは@code{control.scheduler}の薄いラッパーです。
7177 (詳しくは@ref{Scheduler}参照)。このモジュールは移植性が必要な場合に利用すると良いでしょう。
7178 @c COMMON
7179 @end deftp
7180
7181 @defun make-timer :optional error-handler
7182 [SRFI-120]
7183 @c MOD srfi.120
7184 @c EN
7185 Create a new timer, with @var{error-handler} as an error hander.
7186 The @var{error-handler} argument must be @code{#f} or
7187 a procedure that takes one argument.
7188 If it is a procedure, it is called when the task thunk raises an error,
7189 with the raised condition as an argument. Its return value is ignored.
7190 If omitted, @code{#f} is assumed.
7191
7192 In Gauche, returned timer object is just an instance of @code{<scheduler>},
7193 and @var{error-handler} is set in its @code{error-handler} slot.
7194 @xref{Scheduler}, for the details.
7195 @c JP
7196 新たなタイマーを作って返します。@var{error-handler}引数は@code{#f}もしくは
7197 引数をひとつ取る手続きです。手続きであれば、タスクのサンクがエラーを上げた時に、
7198 投げられたコンディションを引数にして呼び出されます。その返り値は無視されます。
7199 省略された場合は@code{#f}とされます。
7200
7201 Gaucheでは、返されるタイマーオブジェクトは@code{<scheduler>}のインスタンスで、
7202 @var{error-handler}引数は@code{error-handler}スロットに渡されます。
7203 詳しくは@ref{Scheduler}を見てください。
7204 @c COMMON
7205 @end defun
7206
7207 @defun timer? obj
7208 [SRFI-120]
7209 @c MOD srfi.120
7210 @c EN
7211 Returns @code{#t} iff @var{obj} is a timer
7212 (an instance of @code{<scheduler>}).
7213
7214 Same as @code{scheduler?} in @code{control.scheduler} (@pxref{Scheduler}).
7215 @c JP
7216 @var{obj}がタイマー (@code{<scheduler>}のインスタンス)であれば@code{#t}を、
7217 そうでなければ@code{#f}を返します。
7218
7219 @code{control.scheduler}の@code{scheduler?}と同じです (@ref{Scheduler}参照)。
7220 @c COMMON
7221 @end defun
7222
7223 @defun timer-cancel! timer
7224 [SRFI-120]
7225 @c MOD srfi.120
7226 @c EN
7227 Stops the timer. No tasks in the queue will be executed, and
7228 no new tasks is accepted. Once timer is canceled, it can't be restarted.
7229
7230 If the timer's tasks ever raised an error, and either the timer doesn't
7231 have an error handler, or an error handler itself raises an error, then
7232 the condition object is kept in the timer and reraised from this procedure.
7233
7234 See also @code{scheduler-terminate!} in @code{control.scheduler}
7235 (@pxref{Scheduler}).
7236 @c JP
7237 タイマーを止めます。まだ残っているタスクはもう実行されず、
7238 また新しいタスクを登録することもできません。
7239 一旦止められたタイマーをリスタートすることはできません。
7240
7241 タイマーのタスクがエラーを投げて、タイマーがerror-handlerを持っていないか、
7242 あるいはエラーを処理したerror-handlerがその中でさらにエラーを投げた場合、
7243 投げられたコンディションはタイマー中に保存され、この手続きからreraiseされます。
7244
7245 @code{control.scheduler}の@code{scheduler-terminate!}も参照してください
7246 (@ref{Scheduler})。
7247 @c COMMON
7248 @end defun
7249
7250 @defun timer-schedule! timer thunk when :optional period
7251 [SRFI-120]
7252 @c MOD srfi.120
7253 @c EN
7254 Creates a new task to run @var{thunk} in the @var{timer}, at @var{when}.
7255 The @var{when} argument specifies the relative time from the moment
7256 this procedure is called. It must be either an integer as the number
7257 of @emph{milliseconds}, or a time delta object created by
7258 @code{make-timer-delta}.
7259
7260 If the @var{period} argument is given and non zero, the task will be
7261 repeated in every period.
7262 It must be a nonnegative integer in milliseconds
7263 or a time delta object. If it is zero, task is non-repeating.
7264
7265 Retuns a task-id, which can be used to reschedule or remove the task
7266 later. The srfi specifies a task id to be any printable Scheme object;
7267 Gauche uses an integer.
7268
7269 Note: In Gauche, a time delta object is a SRFI-19 @code{time-duration}
7270 time (@pxref{SRFI-19 Time types}).
7271
7272 This is implemented on top of @code{scheduler-schedule!} in
7273 @code{control.scheduler} (@pxref{Scheduler}), but note that
7274 the unit of @var{when} and @var{period} is different from it.
7275 @c JP
7276 @var{thunk}を@var{when}で指定される時点に実行するタスクを作成します。
7277 @var{when}は正確な非負整数か、@code{make-timer-delta}が返す時間差オブジェクト
7278 でなければならず、この手続きを呼び出した時点からの相対時間を指定します。
7279 整数の場合はミリ秒単位です。
7280
7281 @var{period}引数が与えられてゼロでない場合、タスクは指定間隔で繰り返されます。
7282 @var{period}引数も@var{when}と同様、非負整数のミリ秒か時間差オブジェクトです。
7283 @var{period}がゼロの場合はタスクは繰り返しません。
7284
7285 戻り値はタスクIDで、それを使ってタスクをリスケジュールしたり削除したりできます。
7286 SRFIではタスクIDは「print可能であること」としか規定されていません。
7287 Gaucheは整数を使っています。
7288
7289 註: Gaucheでは、時間差オブジェクトはSRFI-19の@code{time-duration}タイプの
7290 @code{<time>}オブジェクトです。@ref{SRFI-19 Time types}参照。
7291
7292 この手続きは@code{control.scheduler}の@code{scheduler-schedule!}を
7293 使って実装されています(@ref{Scheduler}参照)が、
7294 @var{when}と@var{period}の単位が異なっていることに注意してください。
7295 @c COMMON
7296 @end defun
7297
7298 @defun timer-reschedule! timer task-id when :optional period
7299 [SRFI-120]
7300 @c MOD srfi.120
7301 @c EN
7302 Change the timing when task identified by @var{task-id} in @var{timer}
7303 is executed. The @var{task-id} should be the object returned
7304 from previous @code{timer-schedule!} on the same @var{timer}.
7305 @c JP
7306 @var{timer}中で@var{task-id}で指定されるタスクの実行時間を変更します。
7307 @var{task-id}はこれ以前に@code{timer-schedule!}を@var{timer}に適用して
7308 返されたオブジェクトでなければなりません。
7309 @c COMMON
7310
7311 @c EN
7312 The semantics of @var{when} and @var{period} are the same as
7313 @code{timer-schedule!}.
7314 @c JP
7315 @var{when}と@var{period}の意味は@code{timer-schedule!}と同じです。
7316 @c COMMON
7317
7318 @c EN
7319 If there's no task with @var{task-id} in @var{timer} (including the
7320 case that the task was one-shot and already run), an error is thrown.
7321 (The behavior is undefined in the srfi).
7322 @c JP
7323 @var{task-id}に該当するタスクが無い場合 (一回きりのタスクとして既に実行されてしまって
7324 いる場合も含みます) にはエラーが投げられます。(srfiではこの場合の動作は規定されていません)
7325 @c COMMON
7326
7327 @c EN
7328 This procedure returns @var{task-id}.
7329 @c JP
7330 返り値は@var{task-id}です。
7331 @c COMMON
7332
7333 @c EN
7334 This is implemented on top of @code{scheduler-reschedule!} in
7335 @code{control.scheduler} (@pxref{Scheduler}), but note that
7336 the unit of @var{when} and @var{period} is different from it.
7337 @c JP
7338 この手続きは@code{control.scheduler}の@code{scheduler-reschedule!}を
7339 使って実装されています(@ref{Scheduler}参照)が、
7340 @var{when}と@var{period}の単位が異なっていることに注意してください。
7341 @c COMMON
7342
7343 @end defun
7344
7345 @defun timer-task-remove! timer task-id
7346 [SRFI-120]
7347 @c MOD srfi.120
7348 @c EN
7349 Removes the task specified by @var{task-id} from the @var{timer}.
7350 Returns @code{#t} if the task is actually removed, @code{#f} if
7351 the timer doesn't have the specified task.
7352 @c JP
7353 @var{timer}中の、@var{task-id}で指定されるタスクを取り除きます。
7354 タスクが実際に取り除かれたら@code{#t}を、指定のタスクが存在しなければ@code{#f}を返します。
7355 @c COMMON
7356 @end defun
7357
7358 @defun timer-task-exists? timer task-id
7359 [SRFI-120]
7360 @c MOD srfi.120
7361 @c EN
7362 Returns @code{#t} iff the timer has a task specified by @var{task-id}.
7363 A non-repeated task is automatically removed from @var{timer} once executed.
7364 @c JP
7365 @var{timer}が@var{task-id}で指定されるタスクを持っていれば@code{#t}を、
7366 そうでなければ@code{#f}を返します。
7367 繰り返さないタスクは実行されたら@var{timer}から自動的に除かれます。
7368 @c COMMON
7369 @end defun
7370
7371 @defun make-timer-delta n unit
7372 [SRFI-120]
7373 @c MOD srfi.120
7374 @c EN
7375 A constructor for time-delta object. It can be passed to @var{when}
7376 and @var{period} arguments of @code{timer-schedule!} and
7377 @code{timer-reschedule!}.
7378 @c JP
7379 時間差オブジェクトのコンストラクタです。時間差オブジェクトは@code{timer-schedule!}と
7380 @code{timer-reschedule!}の@var{when}と@var{period}引数に渡すことができます。
7381 @c COMMON
7382
7383 @c EN
7384 In Gauche, a time-delta object is an instance of @code{<time>} with
7385 @code{time-duration} type (@pxref{SRFI-19 Time types}).
7386 The srfi doesn't specify the concrete
7387 implementation, though, so portable code should use this procedure.
7388 @c JP
7389 Gaucheでは時間差オブジェクトは@code{time-duration}型の@code{<time>}オブジェクト
7390 のインスタンスです(@ref{SRFI-19 Time types}参照)。
7391 このSRFIでは時間差オブジェクトの具体的な実装は指定されていないので、
7392 ポータブルなコードではこの手続きを使って時間差オブジェクトを得るのが良いでしょう。
7393 @c COMMON
7394
7395 @c EN
7396 @var{n} is an integer, and @code{unit} must be one of the following symbols:
7397 @code{h} (hour), @code{m} (minute), @code{s} (second),
7398 @code{ms} (millisecond), @code{us} (microsecond) or @code{ns} (nanosecond).
7399 @c JP
7400 @var{n}は整数、@code{unit}は以下のシンボルのいずれかです:
7401 @code{h} (時間)、@code{m} (分)、@code{s} (秒)、
7402 @code{ms} (ミリ秒)、@code{us} (マイクロ秒)、@code{ns} (ナノ秒)。
7403 @c COMMON
7404 @end defun
7405
7406 @defun timer-delta? obj
7407 [SRFI-120]
7408 @c MOD srfi.120
7409 @c EN
7410 Returns @code{#t} iff @var{obj} is a time-delta object,
7411 which is, in Gauche, an instance of @code{<time>} object with
7412 @code{time-duration} type.
7413 @c JP
7414 @var{obj}が時間差オブジェクトなら@code{#t}を、そうでなければ@code{#f}を返します。
7415 Gaucheでは時間差オブジェクトは@code{time-duration}型の@code{<time>}オブジェクトの
7416 インスタンスです。
7417 @c COMMON
7418 @end defun
7419
7420
7421 @c ----------------------------------------------------------------------
7422 @node Titlecase procedures, Cursor-based string library, Timer APIs, Library modules - SRFIs
7423 @section @code{srfi.129} - Titlecase procedures
7424 @c NODE Titlecase手続き, @code{srfi.129} - Titlecase手続き
7425
7426 @deftp {Module} srfi.129
7427 @mdindex srfi.129
7428 @c EN
7429 This srfi defines 3 procedures handling titlecase of characters.
7430 All of the procedures are supported by Gauche, and this module
7431 serves as a compatiblity interface.
7432 @c JP
7433 このsrfiは、文字のtitlecaseを扱う3つの手続きを定義しています。
7434 全ての手続きはGaucheでサポートされているので、このモジュールは互換性のための
7435 インタフェースを提供するだけです。
7436 @c COMMON
7437
7438 @c EN
7439 These two procedures are built-in (@pxref{Characters}):
7440 @c JP
7441 次の2つの手続きは組み込みです (@ref{Characters}参照):
7442 @c COMMON
7443 @example
7444 char-title-case?
7445 char-titlecase
7446 @end example
7447
7448 @c EN
7449 The following procedure is provided in @code{gauche.unicode}
7450 (@pxref{Full string case conversion}).
7451 @c JP
7452 次の手続きは@code{gauche.unicode}で提供されています
7453 (@ref{Full string case conversion}参照):
7454 @c COMMON
7455 @example
7456 string-titlecase
7457 @end example
7458
7459 @end deftp
7460
7461 @c ----------------------------------------------------------------------
7462 @node Cursor-based string library, String library (reduced), Titlecase procedures, Library modules - SRFIs
7463 @section @code{srfi.130} - Cursor-based string library
7464 @c NODE カーソルを使う文字列ライブラリ, @code{srfi.130} - カーソルを使う文字列ライブラリ
7465
7466 @deftp {Module} srfi.130
7467 @mdindex srfi.130
7468 @c EN
7469 This is an reduced version of @code{srfi.13} that supports cursors in
7470 addition to indexes. The consistency with R7RS and recent srfis are
7471 also considered.
7472 @c JP
7473 これは@code{srfi.13}の縮小バージョンで、インデックスの箇所に文字列カーソルも
7474 使えるようにしたものです。APIにはR7RSと最近のsrfiとの一貫性も考慮してあります。
7475 @c COMMON
7476
7477 @c EN
7478 Gauche supports string cursors natively (@pxref{String cursors}), so
7479 all built-in and SRFI-13 string procedures that takes string indexes
7480 can als otake string cursors as well. You want to use this module
7481 explicitly, though, if you're writing a portable code.
7482 @c JP
7483 Gaucheは文字列カーソルを組み込みでサポートしており(@ref{String cursors}参照)、
7484 文字列インデックスを引数に取る組み込み手続きやSRFI-13手続きはインデックスの箇所に
7485 文字列カーソルを渡すことができます。ただ、ポータブルなコードを書いている場合は、
7486 このモジュールを明示的に使うのが良いでしょう。
7487 @c COMMON
7488
7489 @c EN
7490 The following are built-in. @xref{String cursors}, for the details.
7491 @c JP
7492 以下の手続きは組み込みです。@ref{String cursors}を参照してください。
7493 @c COMMON
7494
7495 @example
7496 string-cursor? string-cursor-start string-cursor-end
7497 string-cursor-next strig-cursor-prev string-cursor-forward
7498 string-cursor-back string-cursor=? string-cursor<?
7499 string-cursor<=? string-cursor>? string-cursor>=?
7500 string-cursor-diff string-cursor->index string-index->cursor
7501 @end example
7502
7503 @c EN
7504 The following procedures are simply aliases of the builtin version
7505 without the @code{/cursor} or @code{/cursors} suffix.
7506 @c JP
7507 以下の手続きは@code{/cursor}や@code{/cursors}サフィックスを除いた
7508 組み込み手続きの単なる別名になっています。
7509 @c COMMON
7510
7511 @example
7512 string->list/cursors string->vector/cursors string-copy/cursors
7513 string-ref/cursor substring/cursors
7514 @end example
7515
7516 @c EN
7517 The following procedures are defined in SRFI-13. @xref{String library},
7518 for the details. Note: Some of those procedures in SRFI-13 accept
7519 only indexes. In SRFI-130, both indexes
7520 and cursors are accepted. Our SRFI-13 implementation shares the same
7521 procedure with SRFI-130, so they accept both indexes and cursors but
7522 such code won't be portable as SRFI-13.
7523 @c JP
7524 以下の手続きはSRFI-13で定義されています (@ref{String library}参照)。
7525 SRFI-13でインデックスのみを受け取る手続きは、SRFI-130で
7526 インデックスと文字列カーソル両方を受け取るように拡張されています。
7527 GaucheではSRFI-13とSRFI-130の手続きは同じコードを利用していて、
7528 従って常にインデックスも文字列カーソルも使えますが、
7529 SRFI-13としてインポートした手続きに文字列カーソルを渡すのはポータブルではありません。
7530 @c COMMON
7531
7532 @example
7533 string-null? string-any string-every string-tabulate
7534 string-unfold string-unfold-right reverse-list->string
7535 string-take string-drop string-take-right string-drop-right
7536 string-pad string-pad-right string-trim string-trim-right
7537 string-trim-both string-replace string-prefix-length
7538 string-suffix-length string-prefix? string-suffix
7539 string-concatenate string-concatenate-reverse string-count
7540 string-filter string-reverse
7541 @end example
7542
7543 @c EN
7544 The following procedures are the same as SRFI-152, except that
7545 the arguments that takes integer indexes can also accept string cursors
7546 (@pxref{String library (reduced)}):
7547 @c JP
7548 以下の手続きは、整数インデックスを取る引数が文字列カーソルも取れるという点を除いて、
7549 SRFI-152にあるものと同じです (@ref{String library (reduced)}参照):
7550 @c COMMON
7551
7552 @example
7553 string-replicate string-remove string-split
7554 @end example
7555
7556 @c EN
7557 The following procedures are also defined in SRFI-13, but SRFI-130 redefines
7558 them to return a string cursor instead of an integer index. They are
7559 described below.
7560 @c JP
7561 以下の手続きはSRFI-13の同名の手続きと異なり、インデックスではなく文字列カーソルを返します。
7562 以下で詳しく説明します。
7563 @c COMMON
7564
7565 @example
7566 string-index string-index-right
7567 string-skip string-skip-right
7568 string-contains string-contains-right
7569 @end example
7570 @end deftp
7571
7572 @defun string-index string pred :optional start end
7573 @defunx string-index-right string pred :optional start end
7574 @defunx string-skip string pred :optional start end
7575 @defunx string-skip-right string pred :optional start end
7576 [SRFI-130]
7577 @c MOD srfi.130
7578 @c EN
7579 Find the position of a character that satisfies @var{pred}
7580 (@code{string-index}/@code{string-index-right}), or
7581 does not satisfy @var{pred}
7582 (@code{string-skip}/@code{string-skip-right}), in a @var{string}.
7583 The chacter is searched from left to right in
7584 @code{string-index}/@code{string-skip}, and
7585 right to left in @code{string-index-right}/@code{string-skip-right}.
7586 @c JP
7587 @var{pred}を満たす(@code{string-index}/@code{string-index-right})
7588 もしくは満たさない(@code{string-skip}/@code{string-skip-right})最初の文字
7589 の位置を返します。
7590 @code{string-index}/@code{string-skip}は左から、
7591 @code{string-index-right}/@code{string-skip-right}は右から該当する文字を探します。
7592 @c COMMON
7593
7594 @c EN
7595 While SRFI-13's procedures of the same names returns integer index,
7596 these returns a string cursor instead.
7597 @c JP
7598 SRFI-13の同名の手続きが整数の文字インデックスを返すのに対し、
7599 これらは文字列カーソルを返します。
7600 @c COMMON
7601
7602 @c EN
7603 The returned cursor from @code{string-index}/@code{string-skip}
7604 points the leftmost character that satisfies/does not satsify @var{pred},
7605 while the returned cursor from
7606 @code{string-index-right} points the next (right) character of the rightmost
7607 one that satisfies/does not satisfy @var{pred}.
7608 If there're no characters that satisfy @var{pred},
7609 @code{string-index} returns a cursor at the end
7610 of the string, while @code{string-index-right}
7611 returns a cursor at the beginning of the string.
7612 (The @code{*-skip} variation reverses the condition).
7613 @c JP
7614 @code{string-index}が返すカーソルは、
7615 @var{pred}を満たす最も左の文字を指しています。
7616 一方、@code{string-index-right}が返すカーソルは、
7617 @var{pred}を満たす最も右の文字の次(一つ右)を指しています。
7618 また、ひとつも@var{pred}を満たす文字が無かった場合、
7619 @code{string-index}は文字列の最後(最後の文字の次)を指すカーソルを、
7620 @code{string-index-right}は文字列の先頭を指すカーソルを返します。
7621 (@code{*-skip}は条件が逆になるだけです)。
7622 @c COMMON
7623
7624 @c EN
7625 (This is easier to understand if you think the cursor is between characters;
7626 if we scan a string from left to right, the cursor looks at the
7627 character on its right; if we scan from right to left, the cursor looks at
7628 the character on its left.)
7629 @c JP
7630 (この仕様は、カーソルが文字の「間」にあると考える方がわかりやすいかもしれません。
7631 左から右に文字列を見て行く時は、カーソルは自分の右側の文字を見ます。
7632 右から左に見て行く時は、自分の左側の文字を見ます。)
7633 @c COMMON
7634
7635 @c EN
7636 Be aware that they still return a cursor even no characters satisfy the
7637 condition, while SRFI-13 versions return @code{#f} in such cases.
7638 @c JP
7639 条件を満たす文字が無かった時にもカーソルが返されることに注意してください。
7640 SRFI-13のバージョンではその場合は@code{#f}が返されていました。
7641 @c COMMON
7642
7643 @c EN
7644 The optional @var{start}/@var{end} can be string cursors or integer
7645 indexes to limit the region of @var{string} to search.
7646 @c JP
7647 省略可能な@var{start}/@var{end}引数は文字列カーソルか整数の文字インデックスで、
7648 探索領域を限定します。
7649 @c COMMON
7650
7651 @example
7652 (define *s* "abc def ghi")
7653
7654 (string-cursor->index *s* (string-index *s* char-whitespace?))
7655 @result{} 3
7656
7657 (string-cursor->index *s* (string-index *s* char-whitespace? 4))
7658 @result{} 7
7659
7660 (string-cursor->index *s* (string-index-right *s* char-whitespace?))
7661 @result{} 8
7662
7663 (string-cursor->index *s* (string-index-right *s* char-whitespace? 0 7))
7664 @result{} 4
7665 @end example
7666 @end defun
7667
7668 @defun string-contains haystack needle :optional start1 end1 start2 end2
7669 @defunx string-contains-right haystack needle :optional start1 end1 start2 end2
7670 [SRFI-130]
7671 @c MOD srfi.130
7672 @c EN
7673 Search for a substring @var{needle} in a string @var{haystack}.
7674 The substring is searched from left to right (@code{string-contains})
7675 or right to left (@code{string-contains-right}).
7676 @c JP
7677 文字列@var{haystack}の中から部分文字列@var{needle}を探します。探索方向は、
7678 @code{string-contains}では左から右へ@code{string-contains-right}では
7679 右から左です。
7680 @c COMMON
7681
7682 @c EN
7683 While SRFI-13's procedures of the same names returns an integer index
7684 of the beginning of the substring if found,
7685 these procedures returns a string cursor
7686 of the beginning of @var{haystack}.
7687 @c JP
7688 SRFI-13の同名の手続きは、見つかった部分文字列の開始位置を整数インデックスで
7689 返しますが、これらの手続きは文字列カーソルで返します。
7690 @c COMMON
7691
7692 @c EN
7693 If @var{haystack} doesn't countain @var{needle}, they return @code{#f}.
7694 @c JP
7695 @var{haystack}が@var{needle}中に無ければ@code{#f}が返されます。
7696 @c COMMON
7697 @end defun
7698
7699 @defun string-for-each-cursor proc string :optional start end
7700 [SRFI-130]
7701 @c MOD srfi.130
7702 @c EN
7703 Calls @var{proc} with each cursor of @var{string}, from left to right,
7704 excluding the post-end cursor. This is the cursor version of
7705 @code{string-for-each-index} in SRFI-13 (@pxref{SRFI-13 String mapping}).
7706 @c JP
7707 @var{proc}を@var{string}中の各文字列カーソル位置(左から右へ)を引数にして
7708 順に呼び出します。ただし最後のカーソル(末尾文字の次の位置)については@var{proc}
7709 を呼びません。
7710 SRFI-13の@code{string-for-each-index}の文字列カーソル版です。
7711 @c COMMON
7712
7713 @example
7714 (define s "abc")
7715 (string-for-each-cursor (^c (display (string-ref/cursor s c))) s)
7716 @result{} @r{displays} abc
7717 @end example
7718 @end defun
7719
7720
7721 @c ----------------------------------------------------------------------
7722 @node String library (reduced), First-class dynamic extents, Cursor-based string library, Library modules - SRFIs
7723 @section @code{srfi.152} - String library (reduced)
7724 @c NODE 文字列ライブラリ(簡略版), @code{srfi.152} - 文字列ライブラリ(簡略版)
7725
7726 @deftp {Module} srfi.152
7727 @mdindex srfi.152
7728 @c EN
7729 This is an improved version of @code{srfi.13}. The spec is actually smaller
7730 than SRFI-13 (hence 'reduced' in the title) by removing bells and whistles.
7731 The consistency with R7RS and recent srfis are also considered.
7732
7733 The following are built-in. @xref{Strings}, for the details.
7734 @c JP
7735 これは@code{srfi.13}の改良版です。
7736 @code{srfi.13}から余分なものを取り除き、R7RSや最近のsrfiとの一貫性を
7737 改善したもので、実際は@code{srfi.13}より小さくなっています。
7738
7739 以下に示す手続きは組み込みです。詳しくは@ref{Strings}を参照してください。
7740 @c COMMON
7741
7742 @example
7743 string? make-string string string-length
7744 string->vector string->list vector->string list->string
7745 string-ref string-set! substring string-copy
7746 string=? string<? string<=? string>?
7747 string>=? string-append string-join string-split
7748 string-map string-for-each read-string write-string
7749 string-fill!
7750 @end example
7751
7752 @c EN
7753 The following procedures are defined to use Unicode string case folding,
7754 and @code{gauche.unicode} module provides them.
7755 @xref{Full string case conversion}, for the details.
7756 Note that Gauche's
7757 built-in versions uses character-wise case folding, which differs
7758 from string case folding on some characters (German eszett, for example).
7759 @c JP
7760 以下に示す手続きはUnicodeの文字列の大文字小文字変換を使うように定義されていて、
7761 元は@code{gauche.unicode}で提供されています。
7762 説明は@ref{Full string case conversion}を参照してください。
7763 Gaucheの組み込みにも同名の手続きがありますが、それらは文字ごとに
7764 大文字小文字変換を行うので、文字列としての大文字小文字変換とは異なります
7765 (ドイツ語のエスツェット等)。
7766 @c COMMON
7767
7768 @example
7769 string-ci=? string-ci<? string-ci<=? string-ci>? string-ci>=?
7770 @end example
7771
7772 @c EN
7773 The following procedures are defined in SRFI-13. @xref{String library},
7774 for the details. Note: Some of those procedures in SRFI-13 that require
7775 predicate allows a char-set or a character to be passed instead
7776 (e.g. @code{string-filter}). In SRFI-152, only predicate is allowed.
7777 Our SRFI-152 implementation shares the same procedure with SRFI-13, so
7778 they accept the same arguments as SRFI-13's, but such code won't be
7779 portable as SRFI-152.
7780 @c JP
7781 以下に示す手続きはSRFI-13で定義されています。
7782 説明は@ref{String library}を参照してください。
7783 SRFI-13ではこれらの手続きのいくつかは、述語引数として手続きだけでなく文字集合や
7784 文字を取ることができます(例: @code{string-filter})。
7785 SRFI-152では手続きしか許していません。Gaucheの実装ではこれらの手続きは
7786 SRFI-13のものと同じなのでSRFI-13のような使い方ができますが、
7787 SRFI-152として移植性のあるコードを書く際には手続きだけを渡すように気をつけてください。
7788 @c COMMON
7789
7790 @example
7791 string-null? string-any string-every string-tabulate
7792 string-unfold string-unfold-right reverse-list->string
7793 string-take string-drop string-take-right string-drop-right
7794 string-pad string-pad-right string-trim string-trim-right
7795 string-trim-both string-replace string-prefix-length string-suffix-length
7796 string-prefix? string-suffix? string-index string-index-right
7797 string-skip string-skip-right string-contains string-concatenate
7798 string-concatenate-reverse string-fold string-fold-right
7799 string-count string-filter string-copy!
7800 @end example
7801 @end deftp
7802
7803 @c EN
7804 We describe procedures unique to this module below.
7805 @c JP
7806 以降では、SRFI-152特有の手続きについて説明します。
7807 @c COMMON
7808
7809 @defun string-remove pred string :optional start end
7810 [SRFI.152]
7811 @c MOD srfi.152
7812 @c EN
7813 Returns a substring of @var{string} between @var{start} and @var{end},
7814 except characters that satisfy @var{pred}. In other words,
7815 it is @code{(string-filter (complement pred) string start end)}.
7816
7817 This is called @var{string-delete} in @code{srfi.13}. Being changed
7818 to take only a predicate (but not a character), it is renamed for
7819 the consistency of other srfi (e.g. @code{filter}, @code{remove} and
7820 @code{delete} in SRFI-1.)
7821 @c JP
7822 @var{string}の@var{start}と@var{end}インデックス間から、
7823 述語@var{pred}を満たす文字を除いた部分文字列を返します。
7824 @code{(string-filter (complement pred) string start end)}と同じです。
7825
7826 これは@code{srfi.13}で@var{string-delete}と呼ばれていた手続きに相当します。
7827 第一引数に述語手続きだけを取るようにし、また他のsrfiとの一貫性を重視して
7828 名前が変えられました(例えばSRFI-1の@code{filter}、@code{remove}、@code{delete}の
7829 関係を考えてください)。
7830 @c COMMON
7831
7832 @example
7833 (string-remove char-whitespace?
7834 "Quick fox jumps over the lazy dog"
7835 3 22)
7836 @result{} "ckfoxjumpsovert"
7837 @end example
7838 @end defun
7839
7840 @defun string-replicate string from to :optional start end
7841 [SRFI-152]
7842 @c MOD srfi.152
7843 @c EN
7844 Extended substring. It is called @code{xsubstring} in SRFI-13, but
7845 renamed for the consistency.
7846
7847 Extract a substring of @var{string} between @var{start} and @var{end},
7848 and conceptually create a bidirectional infinite string by repeating
7849 the substring to both direction. For example, suppose @var{string}
7850 is @code{"abcde"}, @var{start} is 1, and @var{end} is 4. So we repeat
7851 the substring @code{"bcd"}, with one @code{b} falling on the index zero:
7852 @c JP
7853 拡張版substringです。SRFI-13では@code{xsubstring}と呼ばれていましたが、
7854 一貫性のため名前が変えられました。
7855
7856 @var{string}のインデックス@var{start}から@var{end}までの部分文字列をとり、
7857 それを両側に無限に繰り返した文字悦を考えます。
7858 例えば@var{string}が@code{"abcde"}であり、@var{start}が1、@var{end}が4なら、
7859 @code{"bcd"}が無限に繰り替えされた文字列を考えます。この文字列がソース文字列となります。
7860 @code{b}がインデックスの起点です。
7861 @c COMMON
7862
7863 @example
7864 ... b c d b c d b c d b c d b ...
7865 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6
7866 @end example
7867
7868 @c EN
7869 Then we extract a substring between @var{from} and @var{to}
7870 out of this infinite string.
7871 @c JP
7872 このソース文字列から、インデックス@var{from}と@var{to}の間の部分文字列を取り出し返します。
7873 @c COMMON
7874
7875 @example
7876 (string-replicate "abcde" 2 10 1 4)
7877 @result{} "dbcdbcdb"
7878 (string-replicate "abcde" -5 -3 1 4)
7879 @result{} "cdbcdbcd"
7880 @end example
7881 @end defun
7882
7883 @defun string-segment string k
7884 [SRFI-152]
7885 @c MOD srfi.152
7886 @c EN
7887 Splits @var{string} by every @var{k} characters and returns
7888 a list of those strings. The last string may be shorter than @var{k}.
7889 @c JP
7890 @var{string}を@var{k}文字ごとに分割して、そのリストを返します。
7891 最後の文字列は@var{k}文字より短いかもしれません。
7892 @c COMMON
7893
7894 @example
7895 (string-segment "abcdefghijklmn" 3)
7896 @result{} ("abc" "def" "ghi" "jkl" "mn")
7897 @end example
7898
7899 @c EN
7900 We have a similar procedure on lists, @code{slices}
7901 (@pxref{List accessors and modifiers}).
7902 @c JP
7903 類似の手続きとして、@code{slices}があります。
7904 (@ref{List accessors and modifiers}参照)。
7905 @c COMMON
7906 @end defun
7907
7908 @defun string-contains-right string1 string2 :optional start1 end1 start2 end2
7909 [SRFI-152]
7910 @c MOD srfi.152
7911 @c EN
7912 Like @code{string-contains}, looks for a needle @var{string2} from
7913 a haystack @var{string1}, but if it is found, returns the start index
7914 of the @emph{last} match, instead of the first match. The returned index
7915 is in @var{string1}. The optional arguments limit the range of a needle
7916 and a haystack. If a needle isn't found, @code{#f} is returned.
7917
7918 An edge case: If a needle is empty (e.g. @var{string2} is empty,
7919 or @var{start2} = @var{end2}), it always matches right after the haystack,
7920 so @var{end1} is returned.
7921 @c JP
7922 @code{string-contains}と同様、
7923 ソース文字列@var{string1}から探索文字列@var{string2}を探しますが、
7924 見つかった場合は最初ではなく最後のマッチの開始インデックスを返します。
7925 開始インデックスは@var{string1}に対するものです。
7926 省略可能引数は@var{string1}、@var{string2}それぞれの対象とする文字列を制限します。
7927 探索文字列@var{string2}が見つからなかった場合は@code{#f}が返されます。
7928
7929 エッジケースとして、探索文字列が空文字列の場合 (@var{string2}が空であるとか、
7930 @var{start2} = @var{end2}である場合)は、
7931 それは常にソース文字列の一番右端とマッチします。つまり@var{end1}が戻り値になります。
7932 @c COMMON
7933
7934 @example
7935 (string-contains-right "Little Lisper" "Li")
7936 @result{} 7
7937 @end example
7938 @end defun
7939
7940 @defun string-take-while string pred :optional start end
7941 @defunx string-take-while-right string pred :optional start end
7942 [SRFI-152]
7943 @c MOD srfi.152
7944 @c EN
7945 Returns the longest prefix or suffix of @var{string} in which all characters
7946 satisfy @var{pred}.
7947
7948 Note: The order of @var{pred} and the source object is different from
7949 other @code{take-while}-style procedures, such as @code{take-while}
7950 (@ref{R7RS lists}), @code{ideque-take-while} (@ref{R7RS immutable deques}),
7951 and @code{lseq-take-while} (@ref{R7RS lazy sequences}).
7952 @c JP
7953 @var{string}から、全ての文字が述語@var{pred}を満たすような最長のプレフィクスまたは
7954 サフィックスを返します。
7955
7956 註: @var{pred}引数と対象とするオブジェクトの順序が、
7957 他の@code{take-while}系手続き、
7958 @code{take-while}(@ref{R7RS lists})、
7959 @code{ideque-take-while} (@ref{R7RS immutable deques})、
7960 @code{lseq-take-while} (@ref{R7RS lazy sequences})等とは逆であることに
7961 注意してください。
7962 @c COMMON
7963 @end defun
7964
7965 @defun string-drop-while string pred :optional start end
7966 @defunx string-drop-while-right string pred :optional start end
7967 [SRFI-152]
7968 @c MOD srfi.152
7969 @c EN
7970 Returns the longest prefix or suffix of @var{string} in which all characters
7971 does not satisfy @var{pred}.
7972
7973 Note: The order of @var{pred} and the source object is different from
7974 other @code{drop-while}-style procedures, such as @code{drop-while}
7975 (@ref{R7RS lists}), @code{ideque-drop-while} (@ref{R7RS immutable deques}),
7976 and @code{lseq-drop-while} (@ref{R7RS lazy sequences}).
7977 @c JP
7978 @var{string}から、全ての文字が述語@var{pred}を満たさないような最長のプレフィクスまたは
7979 サフィックスを返します。
7980
7981 註: @var{pred}引数と対象とするオブジェクトの順序が、
7982 他の@code{drop-while}系手続き、
7983 @code{drop-while}(@ref{R7RS lists})、
7984 @code{ideque-drop-while} (@ref{R7RS immutable deques})、
7985 @code{lseq-drop-while} (@ref{R7RS lazy sequences})等とは逆であることに
7986 注意してください。
7987 @c COMMON
7988 @end defun
7989
7990 @defun string-span string pred :optional start end
7991 @defunx string-break string pred :optional start end
7992 [SRFI-152]
7993 @c MOD srfi.152
7994 @c EN
7995 Find the longest prefix of @var{string} between @var{start} and @var{end}
7996 in which all characters satisy / do not satisfy @var{pred}, and returns
7997 the prefix and the rest of substring as two values.
7998 @c JP
7999 @var{string}の@var{start}から@var{end}までの範囲のうち、
8000 全ての文字が述語@var{pred}を満たす、あるいは満たさないような最長のプレフィクスをみつけ、
8001 そのプレフィクスと、残りの部分文字列を二つの値として返します。
8002 @c COMMON
8003
8004 @example
8005 (string-break "foo@@example.com" (cut eqv? <> #\@@))
8006 @result{} "foo" @r{and} "@@example.com"
8007
8008 (string-break "foo@@example.com" (cut eqv? <> #\@@) 1 10)
8009 @result{} "oo" "@@exampl"
8010
8011 @c EN
8012 ;; This is Gauche specific - a char-set can work as a predicate:
8013 @c JP
8014 ;; Gaucheでは文字集合を述語手続きとしても使える
8015 @c COMMON
8016 (string-span "VAR_1 = $VAR_2" #[\w])
8017 @result{} "VAR_1" @r{and} " = $VAR_2"
8018 @end example
8019
8020 @c EN
8021 Note: The order of @var{pred} and the source object is different from
8022 @code{span} and @code{break} in @code{scheme.list}
8023 (@pxref{R7RS lists}).
8024 @c JP
8025 @var{pred}引数とソースオブジェクトの順が、
8026 @code{scheme.list}の@code{span}、@code{break}と逆であることに注意
8027 (@ref{R7RS lists}参照)。
8028 @c COMMON
8029 @end defun
8030
8031 @c ----------------------------------------------------------------------
8032 @node First-class dynamic extents, Homogeneous numeric vector libraries, String library (reduced), Library modules - SRFIs
8033 @section @code{srfi.154} - First-class dynamic extents
8034 @c NODE 第一級の動的エクステント, @code{srfi.154} - 第一級の動的エクステント
8035
8036 @deftp {Module} srfi.154
8037 @mdindex srfi.154
8038 @c EN
8039 This module provides a convenient way to reify the dynamic environment.
8040 A continuation captured by @code{call/cc} includes the dynamic environment,
8041 as well as the control flow. Sometimes you only want the dynamic environment
8042 part. A dynamic extent is a reified dynamic environment.
8043 @c JP
8044 このモジュールは、動的環境を簡単に取り出す手段を提供します。
8045 @code{call/cc}によって捕捉される継続は、制御フローと同時に動的環境を保持しますが、
8046 時には動的環境だけが欲しい場合があります。
8047 動的エクステントは、具象化された動的環境です。
8048 @c COMMON
8049
8050 @c EN
8051 Let's see an example. You want a procedure that prints out
8052 a message to the error port, so you wrote this @code{print-error}:
8053 @c JP
8054 例で見てみましょう。メッセージをエラー出力に出したいので、
8055 こんな@code{print-error}を書いたとします:
8056 @c COMMON
8057
8058 @example
8059 (define print-error
8060 (lambda (msg) (display msg (current-error-port))))
8061 @end example
8062
8063 @c EN
8064 However, if @code{print-error} is called while the current error port
8065 is altered, it is affected. It is supposed to be so, that's
8066 the point of @code{current-error-port}.
8067 @c JP
8068 ところで、@code{print-error}が呼ばれた時点で現在のエラー出力ポートが置き換えられていたら、
8069 出力先は変わります。もちろん、そのための@code{current-error-port}なのですから、
8070 これは想定された動作です。
8071 @c COMMON
8072
8073 @example
8074 (call-with-output-string
8075 (^p (with-error-to-port p (^[] (print-error "abc\n")))))
8076 @result{} "abc\n"
8077 @end example
8078
8079 @c EN
8080 If you do want @code{print-error} to use the error port
8081 at the time it is defined, you have to extract the dynamic value
8082 at the moment.
8083 @c JP
8084 けれども、@code{print-error}が定義された時点でのエラー出力ポートを常に使いたい
8085 場合はどうすれば良いでしょうか。ひとつの方法は、定義時のエラー出力ポートの
8086 動的な値を保存しておくことです:
8087 @c COMMON
8088
8089 @example
8090 (define print-error
8091 (let1 eport (current-error-port)
8092 (lambda (msg) (display msg eport))))
8093 @end example
8094
8095 @c EN
8096 This would be quickly cumbersome when you need to capture multiple
8097 dynamic values, or the original @code{print-error} is called indirectly
8098 and you can't modify it the way shown above.
8099 @c JP
8100 しかし、これは捕捉したい動的な値が増えればややこしくなりますし、
8101 @code{print-error}が自分の触れない箇所で定義されていて書き換えられない場合も
8102 面倒です。
8103 @c COMMON
8104
8105 @c EN
8106 Using @code{dynamic-lambda} addresses this issue. It not only captures
8107 the lexical environment, but also the dynamic environment when it
8108 is evaluated. So the @code{current-error-port} in its body
8109 returns the current error port at the time of @code{print-error}
8110 being defined, not when it is called:
8111 @c JP
8112 @code{dynamic-lambda}は、レキシカルな環境だけでなくそれが評価された時点の
8113 動的環境をも捕捉することでこの問題を解決します。
8114 次の例では、@code{current-error-port}は@code{print-error}が定義された時点の
8115 値を返します:
8116 @c COMMON
8117
8118 @example
8119 (define print-error
8120 (dynamic-lambda (msg) (display msg (current-error-port))))
8121 @end example
8122 @end deftp
8123
8124 @defun current-dynamic-extent
8125 [SRFI-154]
8126 @c MOD srfi.154
8127 @c EN
8128 Returns a dynamic-extent object that reifies the current dynamic
8129 environment.
8130 @c JP
8131 現在の動的環境を具象化した動的エクステントオブジェクトを返します。
8132 @c COMMON
8133 @end defun
8134
8135 @defun dynamic-extent? obj
8136 [SRFI-154]
8137 @c MOD srfi.154
8138 @c EN
8139 Returns @code{#t} iff @var{obj} is a dynamic-extent object.
8140 @c JP
8141 @var{obj}が動的エクステントオブジェクトの時のみ@code{#t}を返します。
8142 @c COMMON
8143 @end defun
8144
8145 @defun with-dynamic-extent dynext thunk
8146 [SRFI-154]
8147 @c MOD srfi.154
8148 @c EN
8149 Calls the @var{thunk} in the dynamic extent @var{dynext}, and
8150 returns the values yielded by @var{thunk}.
8151 @c JP
8152 動的環境を動的エクステント@var{dynext}で置き換えた状態で
8153 @var{thunk}を呼びます。@var{thunk}が返した値が戻り値となります。
8154 @c COMMON
8155 @end defun
8156
8157 @defmac dynamic-lambda formals body @dots{}
8158 [SRFI-154]
8159 @c MOD srfi.154
8160 @c EN
8161 Like @code{lambda}, but this not only captures the lexical environment,
8162 but also the dynamic environment. Yields a procedure.
8163
8164 Note: Since @code{dynamic-lambda} needs to swap the dynamic environment
8165 after executing @var{body}, the last expression of @var{body} isn't
8166 called in the tail context even if the procedure created by
8167 @code{dynamic-lambda} is called in tail context.
8168 @c JP
8169 @code{lambda}のように振る舞いますが、レキシカルな環境だけでなく、
8170 評価時の動的環境も捕捉します。手続きを返します。
8171
8172 註: @code{dynamic-lambda}は最後の@var{body}の実行が終わった後で動的環境を
8173 戻さなければならないので、@code{dynamic-lambda}で作られた手続きが末尾呼び出し
8174 されたとしても、@var{body}の末尾式は末尾呼び出しにはなりません。
8175 @c COMMON
8176 @end defmac
8177
8178
8179
8180 @c ----------------------------------------------------------------------
8181 @node Homogeneous numeric vector libraries, Comparator sublibrary, First-class dynamic extents, Library modules - SRFIs
8182 @section @code{srfi.160} - Homogeneous numeric vector libraries
8183 @c NODE 均質な数値ベクタライブラリ, @code{srfi.160} - 均質な数値ベクタライブラリ
8184
8185 @deftp {Module} srfi.160
8186 @mdindex srfi.160
8187 @c EN
8188 This is an enhancement of SRFI-4, Homogeneous vectors
8189 (@pxref{Homogeneous vectors}), and then become a part
8190 of R7RS-large (@pxref{R7RS uniform vectors}).
8191
8192 In Gauche, all the procedures in this module are provided
8193 as a part of @code{gauche.uvector} module
8194 (@pxref{Uniform vectors}), and described there.
8195
8196 This module only exports the procedures defined in @code{srfi.160}.
8197 @c JP
8198 これはSRFI-4の拡張で (@ref{Homogeneous vectors}参照)、
8199 R7RS-largeの一部になりました (@ref{R7RS uniform vectors}参照)。
8200
8201 Gaucheでは、このモジュールの全ての手続きは @code{gauche.uvector}
8202 モジュールで提供されているので、そちらで説明されています
8203 (@ref{Uniform vectors}参照)。
8204
8205 このモジュールは、@code{srfi.160}で定義されている手続きのみをエクスポートします。
8206 @c COMMON
8207 @end deftp
8208
8209 @c ----------------------------------------------------------------------
8210 @node Comparator sublibrary, POSIX API, Homogeneous numeric vector libraries, Library modules - SRFIs
8211 @section @code{srfi.162} - Comparator sublibrary
8212 @c NODE 比較器のサブライブラリ, @code{srfi.162} - 比較器のサブライブラリ
8213
8214 @deftp {Module} srfi.162
8215 @mdindex srfi.162
8216 @c EN
8217 This is a supplement of SRFI-128, comparators. It provides
8218 a few comparator procedures, as well as several useful
8219 pre-defined comparators, listed below.
8220 Theese pre-defined comparators are already built in Gauche,
8221 so see @ref{Predefined comparators} for the details.
8222 @c JP
8223 これはSRFI-128(比較器)への追加です。いくつかの比較器手続きと、
8224 以下に示す便利な定義済み比較器を提供します。
8225 Gaucheではこれらの定義済み比較器は組み込みになっているので、
8226 詳細は@ref{Predefined comparators}を参照してください。
8227 @c COMMON
8228
8229 @example
8230 default-comparator boolean-comparator real-comparator
8231 char-comparator char-ci-comparator string-comparator
8232 string-ci-comparator pair-comparator list-comparator
8233 vector-comparator eq-comparator eqv-comparator
8234 equal-comparator
8235 @end example
8236 @end deftp
8237
8238 @defun comparator-min comparator obj obj2 @dots{}
8239 @defunx comparator-max comparator obj obj2 @dots{}
8240 [SRFI-162]
8241 @c MOD srfi.162
8242 @c EN
8243 Find the object in @var{obj1} @var{obj2} @dots{} that is
8244 minimum or maximum compared by @var{comparator}.
8245 Note: SRFI-114 provides the same procedures.
8246 @c JP
8247 @var{obj1} @var{obj2} @dots{}のうちから、
8248 @var{comparator}に基づいた最小あるいは最大の値を返します。
8249 SRFI-114にも同じ手続きがあります。
8250 @c COMMON
8251
8252 @example
8253 (comparator-min list-comparator '(a c b) '(a d) '(a c))
8254 @result{} (a c)
8255 @end example
8256 @end defun
8257
8258 @defun comparator-min-in-list comparator list
8259 @defunx comparator-min-in-list comparator list
8260 [SRFI-162]
8261 @c MOD srfi.162
8262 @c EN
8263 Find the object in @var{list} that is minimum or maximum compared
8264 by @var{comparator}. It is an error if @var{list} is empty.
8265 @c JP
8266 @var{list}中のオブジェクトのうちから、
8267 @var{comparator}に基づいた最小あるいは最大の値を返します。
8268 @var{list}が空の場合はエラーが投げられます。
8269 @c COMMON
8270 @end defun
8271
8272 @c ----------------------------------------------------------------------
8273 @node POSIX API, Two safer subsets of R7RS, Comparator sublibrary, Library modules - SRFIs
8274 @section @code{srfi.170} - POSIX API
8275
8276 @deftp {Module} srfi.170
8277 @mdindex srfi.170
8278 @c EN
8279 This module provides a portable interface to a part of POSIX API,
8280 mainly filesystem interface.
8281 @c JP
8282 このモジュールは、ファイルシステムインタフェースを中心としたPOSIX APIの一部を
8283 ポータブルなインタフェースとして提供します。
8284 @c COMMON
8285
8286 @c EN
8287 In Gauche, it is a thin wrapper of Gauche's native system interface
8288 (@pxref{System interface}). You may want to use this module for
8289 a portable code.
8290 @c JP
8291 GaucheではこのモジュールはGaucheのネイティブシステムインタフェース
8292 (@ref{System interface})の薄いラッパーになっています。
8293 ポータブルなコードを書く場合にこのモジュールは便利でしょう。
8294 @c COMMON
8295 @end deftp
8296
8297 @c EN
8298 @subheading POSIX Error
8299 @c JP
8300 @subheading POSIXエラー
8301 @c COMMON
8302
8303 @defun posix-error? obj
8304 [SRFI-170]
8305 @c MOD srfi.170
8306 @c EN
8307 Returns @code{#t} iff @var{obj} is a condition thrown due to
8308 underlying POSIX-layer error. On Gauche, POSIX-layer condition
8309 is the same as @code{<system-error>} (@pxref{Conditions}).
8310 @c JP
8311 @var{obj}がPOSIXレイヤから投げられたコンディションである場合に@code{#t}を返します。
8312 Gaucheeでは、POSIXレイヤのコンディションは@code{<system-error>}の
8313 インスタンスです (@ref{Conditions}参照)。
8314 @c COMMON
8315 @end defun
8316
8317 @defun posix-error-name err
8318 [SRFI-170]
8319 @c MOD srfi.170
8320 @c EN
8321 The argument must be a POSIX-layer condition, that is,
8322 an object that satisfies @code{posix-error?}. In Gauche,
8323 it is a @code{<system-error>} object.
8324
8325 Returns the POSIX error name (symbol)
8326 of the given condition, such as @code{ENOENT}.
8327
8328 See also @code{sys-errno->symbol} (@pxref{System inquiry}).
8329 @c JP
8330 引数はPOSIX層のコンディション、つまり@code{posix-error?}を満たすオブジェクトで
8331 なければなりません。Gaucheではそれは@code{<system-error>}オブジェクトです。
8332
8333 与えられたコンディションのPOSIXエラー名をシンボルで返します
8334 (例: @code{ENOENT})。
8335
8336 @code{sys-errno->symbol}も参照してください
8337 (@ref{System inquiry})。
8338 @c COMMON
8339 @end defun
8340
8341 @defun posix-error-message err
8342 [SRFI-170]
8343 @c MOD srfi.170
8344 @c EN
8345 The argument must be a POSIX-layer condition, that is,
8346 an object that satisfies @code{posix-error?}. In Gauche,
8347 it is a @code{<system-error>} object.
8348
8349 Returns the error message (string) describing the error,
8350 e.g. @code{"No such file or directory"}.
8351
8352 See also @code{sys-strerror} (@pxref{System inquiry}).
8353 @c JP
8354 引数はPOSIX層のコンディション、つまり@code{posix-error?}を満たすオブジェクトで
8355 なければなりません。Gaucheではそれは@code{<system-error>}オブジェクトです。
8356
8357 与えられたコンディションのPOSIXエラーメッセージを文字列で返します
8358 (例: @code{"No such file or directory"})。
8359
8360 @code{sys-strerror}も参照してください
8361 (@ref{System inquiry})。
8362 @c COMMON
8363 @end defun
8364
8365 @subheading I/O
8366
8367 @defun open-file fname port-type flags :optional permission buffer-mode
8368 [SRFI-170]
8369 @c MOD srfi.170
8370 Opens a file named by @var{fname} and returns a port to read or write
8371 the file. You have finer control than
8372 @code{open-input-file}/@code{open-output-file}.
8373
8374 The @code{port-type} argument must be either one of the value
8375 of the constant @code{binary-input}, @code{textual-input},
8376 @code{binary-output}, @code{textual-output} and
8377 @code{binary-input/output}. The direction of the returned port
8378 is determined by this argument.
8379
8380 Gauche doesn't distinguish textual ports and binary ports.
8381
8382 The @var{flags} argument is a bitwise ior of
8383 zero or more of the following bitmasks:
8384 @code{open/append}, @code{open/create}, @code{open/exclusive},
8385 @code{open/nofollow} and @code{open/truncate}. These corresponds
8386 to the POSIX flags @code{O_APPEND}, @code{O_CREAT}, @code{O_EXCL},
8387 @code{O_NOFOLLOW} and @code{O_TRUNC}. Gauche exposes the POSIX flags
8388 in @code{gauche.fcntl} (@pxref{Low-level file operations}).
8389
8390 Note: POSIX @code{open(2)} also requires one of the bitmasks
8391 @code{O_RDONLY}, @code{O_WRONLY} and @code{O_RDWR}. These flags
8392 are deduced from the @var{port-type} argument.
8393
8394 The optional @var{permission} is an integer permission bits
8395 to be used when a new file is created. The actual permission bits
8396 are also affected by the current @code{umask}.
8397
8398 The optional @var{buffer-mode} is a value of either one of the followings:
8399 @code{buffer-none}, @code{buffer-block}, and @code{buffer-line}.
8400 @end defun
8401
8402 @defun fd->port fd port-type :optional buffer-mode
8403 [SRFI-170]
8404 @c MOD srfi.170
8405 Creates a Scheme port wrapping an integer file descriptor @var{fd}.
8406 The descriptor shouldn't be used by other Scheme ports. After calling
8407 this procedure, no I/O should be done via @var{fd} directly; the descriptor
8408 is ``owned'' by the port, and will be closed once the port is closed.
8409
8410 The @code{port-type} argument must be either one of the value
8411 of the constant @code{binary-input}, @code{textual-input},
8412 @code{binary-output}, @code{textual-output} and
8413 @code{binary-input/output}. The direction must match how @var{fd} was
8414 opened.
8415
8416 The optional @var{buffer-mode} is a value of either one of the followings:
8417 @code{buffer-none}, @code{buffer-block}, and @code{buffer-line}.
8418 @end defun
8419
8420 @defvr {Constant} binary-input
8421 @defvrx {Constant} textual-input
8422 @defvrx {Constant} binary-output
8423 @defvrx {Constant} textual-output
8424 @defvrx {Constant} binary-input/output
8425 [SRFI-170]
8426 @c MOD srfi.170
8427 Constants to be used as @var{port-type} argument of
8428 @code{open-file} and @code{fd->port}.
8429 @end defvr
8430
8431 @defvr {Constant} buffer-none
8432 @defvrx {Constant} buffer-block
8433 @defvrx {Constant} buffer-line
8434 [SRFI-170]
8435 @c MOD srfi.170
8436 Constants to be used as @var{buffer-mode} argument of
8437 @code{open-file} and @code{fd->port}.
8438 @end defvr
8439
8440 @defvr {Constant} open/append
8441 @defvrx {Constant} open/create
8442 @defvrx {Constant} open/exclusive
8443 @defvrx {Constant} open/nofollow
8444 @defvrx {Constant} open/truncate
8445 [SRFI-170]
8446 @c MOD srfi.170
8447 Bitmask constants to be used as @var{flags} argument of
8448 @code{open-file}.
8449 @end defvr
8450
8451 @subheading File System
8452
8453 @defun create-directory fname :optional permission
8454 @defunx create-fifo fname :optional permission
8455 @defunx create-hard-link old-fname new-fname
8456 @defunx create-symlink old-fname new-fname
8457 [SRFI-170]
8458 @c MOD srfi.170
8459 Corresponds to Gauche's built-in @code{sys-mkdir}, @code{sys-mkfifo},
8460 @code{sys-link} and @code{sys-symlink}.
8461
8462 The default value of @var{permission} is @code{#o775} for
8463 @code{create-directory}, and @code{#o664} for @code{create-fifo}
8464 (It's not optoinal for Gauche's built-in).
8465
8466 On Windows, @code{create-fifo} and @code{create-symlink} are
8467 not supported. Procedures exist, but raise an error when called.
8468 @end defun
8469
8470 @defun read-symlink name
8471 [SRFI-170]
8472 @c MOD srfi.170
8473 Gauche's @code{sys-readlink}.
8474 @end defun
8475
8476 @defun rename-file old new
8477 [SRFI-170]
8478 @c MOD srfi.170
8479 Gauche's @code{sys-rename}.
8480 @end defun
8481
8482 @defun delete-directory name
8483 [SRFI-170]
8484 @c MOD srfi.170
8485 Gauche's @code{sys-rmdir}. The directory must be empty.
8486
8487 To remove directory that may not be empty,
8488 you can use @code{delete-directory*}
8489 in @code{file.util} (@pxref{Directory utilities}).
8490 @end defun
8491
8492 @defun set-file-owner fname uid gid
8493 [SRFI-170]
8494 @c MOD srfi.170
8495 Gauche's @code{sys-chown}. The @var{uid} and @var{gid} arguments
8496 should be an integer uid/gid, or the value of the constant
8497 @code{owner/unchanged} and @code{group/unchanged}, respectively,
8498 to indicate to keep the original value.
8499 @end defun
8500
8501 @defvr {Constant} owner/unchanged
8502 @defvrx {Constant} group/unchanged
8503 [SRFI-170]
8504 @c MOD srfi.170
8505 Constants to be passed as @var{uid} and @var{gid} arguments
8506 of @code{set-file-owner}, respectively.
8507 @end defvr
8508
8509
8510 @defun set-file-times funame :optional atime mtime
8511 [SRFI-170]
8512 @c MOD srfi.170
8513 Gauche's @code{sys-utime}. The @var{atime} and @var{mtime}
8514 arguments must be a @code{<time>} object (@pxref{Time}), or
8515 either one of the values of constants @code{time/now} or
8516 @code{time/unchanged}. The constant @code{time/now}
8517 indicates the time when the procedure is called,
8518 and the constant @code{time/unchanged} indicates the
8519 corresponding timestamp remains the same.
8520 @end defun
8521
8522 @defvr {Constant} time/now
8523 @defvrx {Constant} time/unchanged
8524 [SRFI-170]
8525 @c MOD srfi.170
8526 Constants that can be passed to @var{atime} and @var{mtime}
8527 arguments of @code{set-file-times}.
8528 @end defvr
8529
8530 @defun truncate-file fname-or-port len
8531 [SRFI-170]
8532 @c MOD srfi.170
8533 The first argument can be a string filename or a open port associated
8534 to a file. If it is a filename, @code{sys-truncate} is called,
8535 and if it is a port, @code{sys-ftruncate} is called.
8536 @end defun
8537
8538 @defun file-info fname-or-port follow?
8539 [SRFI-170]
8540 @c MOD srfi.170
8541 Gauche's @code{sys-stat}, @code{sys-lstat} or @code{sys-fstat}.
8542
8543 The first argument can be a string filename or a open port associated
8544 to a file. If it is a filename, @code{sys-stat} or @code{sys-lstat}
8545 is called depending on whether @var{follow?} is @code{#t} or @code{#f}.
8546 If it is a port, @code{sys-fstat} is called.
8547
8548 Returns a file-info object, which is a @code{<sys-stat>} instance
8549 in Gauche (@pxref{File stats}).
8550 @end defun
8551
8552 @defun file-info? obj
8553 [SRFI-170]
8554 @c MOD srfi.170
8555 Returns @code{#t} iff @var{obj} is a file-info object, which is
8556 a @code{<sys-stat>} instance in Gauche (@pxref{File stats}).
8557 @end defun
8558
8559 @defun file-info:device file-info
8560 @defunx file-info:inode file-info
8561 @defunx file-info:mode file-info
8562 @defunx file-info:nlinks file-info
8563 @defunx file-info:uid file-info
8564 @defunx file-info:gid file-info
8565 @defunx file-info:rdev file-info
8566 @defunx file-info:size file-info
8567 @defunx file-info:blksize file-info
8568 @defunx file-info:blocks file-info
8569 @defunx file-info:atime file-info
8570 @defunx file-info:mtime file-info
8571 @defunx file-info:ctime file-info
8572 [SRFI-170]
8573 @c MOD srfi.170
8574 Accessorso of file-info object (@code{<sys-stat>}) (@pxref{File stats}).
8575 Access its @code{dev}, @code{ino}, @code{mode}, @code{nlink},
8576 @code{uid}, @code{gid}, @code{rdev}, @code{size},
8577 @code{blksize}, @code{blocks}, @code{atim}, @code{mtim}, @code{ctim}
8578 slots, respectively.
8579
8580 Note: @code{<sys-stat>}'s @code{atime}, @code{mtime} and @code{ctime}
8581 contains integer for the backward compatibility, while
8582 @code{file-info:atime}, @code{file-info:mtime} and @code{file-info:ctime}
8583 returns @code{<time>} object.
8584 @end defun
8585
8586 @defun file-info-directory? file-info
8587 @defunx file-info-fifo? file-info
8588 @defunx file-info-symlink? file-info
8589 @defunx file-info-regular? file-info
8590 @defunx file-info-socket? file-info
8591 @defunx file-info-device? file-info
8592 [SRFI-170]
8593 @c MOD srfi.170
8594 Returns true iff the file-info object (@code{<sys-stat>} is of the
8595 respective type. (@code{file-info-device?} returns true if
8596 the file is either block or character device).
8597 It corresponds to the @code{type} slot of @code{<sys-stat>}.
8598 @end defun
8599
8600 @defun set-file-mode fname mode-bits
8601 [SRFI-170]
8602 @c MOD srfi.170
8603 Gauche's @code{sys-chmod}.
8604 @end defun
8605
8606 @defun directory-files dir :optional dotfiles?
8607 [SRFI-170]
8608 @c MOD srfi.170
8609 Returns a list of filenames in the directory named @var{dir}.
8610 Similar to @code{directory-list} in @code{file.util}
8611 (@pxref{Directory utilities}), but (1) it never includes
8612 @code{.} and @code{..} (as true value is given to @code{:children?}
8613 argument of @code{directory-list}), and (2) it doesn't include
8614 files beginning with @code{.} by default, unless @code{dotfiles?} is true.
8615 @end defun
8616
8617 @defun make-directory-files-generator dir :optional dotfiles?
8618 [SRFI-170]
8619 @c MOD srfi.170
8620 Returns a generator (@pxref{Generators}) that generates file names
8621 in the directory named @var{dir}. The names never include
8622 @code{.} and @code{..}, and the filenames beginning with @code{.} is
8623 omitted unless @var{dotfiles?} is true.
8624 @end defun
8625
8626 @defun open-directory dir :optional dotfiles?
8627 @defunx read-directory dir-object
8628 @defunx close-directory dir-object
8629 [SRFI-170]
8630 @c MOD srfi.170
8631 This is a directory scanner API more close to POSIX @code{opendir},
8632 @code{readdir} and @code{closedir}. A directory object is opened
8633 with @code{open-directory}, and its entries (filenames) can be read
8634 one by one using @code{read-directory}. If the file names are exausted,
8635 @code{read-directory} returns an EOF object. A directory object
8636 must be closed with @code{close-directory}.
8637
8638 The filenames to be retrieved are the same as @code{directory-files}; that is,
8639 @code{.} and @code{..} are never included, and names beginning with @code{.}
8640 is exluded unless @var{dotfiles?} is true.
8641 @end defun
8642
8643 @defun real-path path
8644 [SRFI-170]
8645 @c MOD srfi.170
8646 Gauche's @code{sys-realpath}.
8647 @end defun
8648
8649 @defun file-space path-or-port
8650 [SRFI-170]
8651 @c MOD srfi.170
8652 Returns the free space of a file system where a file specified by
8653 @var{path-or-port} resides, in number of bytes.
8654 @end defun
8655
8656 @deffn {Parameter} temp-file-prefix
8657 [SRFI-170]
8658 @c MOD srfi.170
8659 A parameter holding a path prefix to be used by @code{create-temp-file}
8660 and @code{call-with-temporary-filename}. In Gauche,
8661 the default value is set to
8662 @code{(build-path (temporary-directory) (x->string (sys-getpid)))}.
8663 @xref{Temporary files and directories}, for the description of
8664 @code{temporary-directory}.
8665 @end deffn
8666
8667 @defun create-temp-file :optional prefix
8668 [SRFI-170]
8669 @c MOD srfi.170
8670 @end defun
8671
8672 @defun call-with-temporary-filename maker :optional prefix
8673 [SRFI-170]
8674 @c MOD srfi.170
8675 @end defun
8676
8677 @subheading Process state
8678
8679 Note: For SRFI-170's @code{current-directory}, we reuse
8680 @code{file.util}'s one. @xref{Directory utilities}, for the description.
8681
8682 @defun umask
8683 [SRFI-170]
8684 @c MOD srfi.170
8685 Returns the current umask value.
8686 Gauche's @code{sys-umask} without argument.
8687 @end defun
8688
8689 @defun set-umask! mask
8690 [SRFI-170]
8691 @c MOD srfi.170
8692 Sets @var{mask}, which must be a nonnegative exact integer,
8693 as the current umask.
8694 Gauche's @code{sys-umask}, except that it returns unspecified value.
8695 @end defun
8696
8697 @defun set-current-directory! dir
8698 [SRFI-170]
8699 @c MOD srfi.170
8700 Sets the process's current working directory to @var{dir}.
8701 Gauche's @code{sys-chdir}.
8702 It can also be done with @code{current-working-directory} in @code{file.util}
8703 (@pxref{Directory utilities}).
8704 @end defun
8705
8706 @defun pid
8707 [SRFI-170]
8708 @c MOD srfi.170
8709 Returns the current process id. Gauche's @code{sys-getpid}.
8710 @end defun
8711
8712 @defun nice :optional delta
8713 [SRFI-170]
8714 @c MOD srfi.170
8715 Increments the current process's nice value by @var{delta}, which must
8716 be an exact integer. The lower the nice value is, the more chance
8717 the process gets run. If omitted, @var{delta} is assumed to be 1.
8718 Gauche's @code{sys-nice}.
8719 @end defun
8720
8721 @defun user-uid
8722 @defunx user-gid
8723 @defunx user-effective-uid
8724 @defunx user-effecitve-gid
8725 @defunx user-supplementary-gids
8726 [SRFI-170]
8727 @c MOD srfi.170
8728 Gauche's @code{sys-getuid}, @code{sys-getgid}, @code{sys-geteuid},
8729 @code{sys-getegid}, and @code{sys-getgroups}, respectievly.
8730 @end defun
8731
8732 @subheading User and group database access
8733
8734 @defun user-info uid-or-name
8735 [SRFI-170]
8736 @c MOD srfi.170
8737 Returns a user-info object, which is a @code{<sys-passwd>} instance
8738 in Gauche, of a user specified by @var{uid-or-name}, which must be
8739 an exact integer uid or a string username.
8740 If it is an uid, @var{sys-getpwuid} is called, and if it is a username
8741 @code{sys-getpwnam} is called.
8742 @end defun
8743
8744 @defun user-info? obj
8745 [SRFI-170]
8746 @c MOD srfi.170
8747 Returns @code{#t} iff @var{obj} is a user-info object (@code{<sys-passwd>}).
8748 @end defun
8749
8750 @defun user-info:name uinfo
8751 @defunx user-info:uid uinfo
8752 @defunx user-info:gid uinfo
8753 @defunx user-info:home-dir uinfo
8754 @defunx user-info:shell uinfo
8755 @defunx user-info:full-name uinfo
8756 [SRFI-170]
8757 @c MOD srfi.170
8758 Returns the value of @var{name}, @code{uid}, @code{gid}, @code{dir},
8759 @code{shell} and @var{gecos} slots of a user-info object (@code{<sys-passwd})
8760 @var{uinfo}.
8761 @end defun
8762
8763 @defun user-info:parsed-full-name uinfo
8764 [SRFI-170]
8765 @c MOD srfi.170
8766 @end defun
8767
8768 @defun group-info gid-or-name
8769 [SRFI-170]
8770 @c MOD srfi.170
8771 Returns a group-info object, which is a @code{<sys-group>} instance
8772 in Gauche, of a group specified by @var{gid-or-name}, which must be
8773 an exact integer gid or a string groupname.
8774 If it is an gid, @var{sys-getgrgid} is called, and if it is a groupname
8775 @code{sys-getgrnam} is called.
8776 @end defun
8777
8778 @defun group-info? obj
8779 [SRFI-170]
8780 @c MOD srfi.170
8781 Returns @code{#t} iff @var{obj} is a group-info object (@code{<sys-group}).
8782 @end defun
8783
8784 @defun group-info:name ginfo
8785 @defunx group-info:gid ginfo
8786 [SRFI-170]
8787 @c MOD srfi.170
8788 Returns the value of @code{name} and @code{gid} slot of a group info
8789 (@code{<sys-group>}).
8790 @end defun
8791
8792 @subheading Time
8793
8794 @defun posix-time
8795 [SRFI-170]
8796 @c MOD srfi.170
8797 Same as @code{current-time} (@pxref{Time}). Return value is a @code{<time>}
8798 instance of @code{time-utc}.
8799 @end defun
8800
8801 @defun monotonic-time
8802 [SRFI-170]
8803 @c MOD srfi.170
8804 Returns a @code{<time>} instance of @code{time-monotonic}, representing
8805 a elapsed time since an unspecified epoch. It is guaranteed to monotonically
8806 increasing during the lifetime of the process, even if the system clock
8807 is modified.
8808 @end defun
8809
8810 @subheading Environment variables
8811
8812 @xref{Accessing environment variables}, for getting environment variables.
8813 This srfi defines the means to modify them.
8814
8815 @defun set-enviroment-variable! name value
8816 [SRFI-170]
8817 @c MOD srfi.170
8818 Gauche's @code{sys-setenv} with the third argument being @code{#t}
8819 (overwrite the existing value).
8820 @end defun
8821
8822 @defun delete-environment-variable! name
8823 [SRFI-170]
8824 @c MOD srfi.170
8825 Gauche's @code{sys-unsetenv}.
8826 @end defun
8827
8828 @subheading Terminal device control
8829
8830 @defun terminal? port
8831 [SRFI-170]
8832 @c MOD srfi.170
8833 Gauche's @code{sys-isatty}.
8834 @end defun
8835
8836 @c ----------------------------------------------------------------------
8837 @node Two safer subsets of R7RS, Hooks (srfi), POSIX API, Library modules - SRFIs
8838 @section @code{srfi.172} - Two safer subsets of R7RS
8839 @c NODE 二つの安全なR7RSサブセット, @code{srfi.172} - 二つの安全なR7RSサブセット
8840
8841 @deftp {Module} srfi.172
8842 @deftpx {Module} srfi.172.functional
8843 @mdindex srfi.172
8844 @mdindex srfi.172.functional
8845 @c EN
8846 This module exports a subset of R7RS-small bindings that can be used
8847 relatively safely in the quasi-sandbox environment. To realize
8848 a true sandbox, the runtime needs more measures such as preventing
8849 resource hogging and the data structure that allows
8850 loopholes from being passed to those procedures.
8851 However, this module can be a good starting point.
8852 @c JP
8853 このモジュールは、R7RS-smallのうちほぼサンドボックスとして使えるような、
8854 制限された比較的安全な束縛をエクスポートします。
8855 「ほぼ」というのは、完全に安全なサンドボックスにするには束縛の制限以外の対策も
8856 必要だからです。例えばリソースを無制限に消費するコードを走るのを防いだり、
8857 渡すことでループホールが作られてしまうようなデータが渡らないようにする、等です。
8858 このモジュールはそういった環境を作る起点として使えるでしょう。
8859 @c COMMON
8860
8861 @c EN
8862 The submodule @code{srfi.172.functional} further resricts exported
8863 bindings to side-effect free ones.
8864 @c JP
8865 サブモジュール@code{srfi.172.functional}は、そこからさらに副作用の無い関数のみに
8866 限定した束縛をエクスポートします。
8867 @c COMMON
8868
8869 @c EN
8870 The bindings exported by @code{srfi.172} are as follows:
8871 @c JP
8872 @code{srfi.172}がエクスポートする束縛は次のとおりです:
8873 @c COMMON
8874
8875 @example
8876 - * / + < <= = => > >= abs acos and angle append apply asin assoc assq
8877 assv atan begin boolean? boolean=? bytevector bytevector?
8878 bytevector-append bytevector-copy bytevector-copy!
8879 bytevector-length bytevector-u8-ref bytevector-u8-set! caaaar
8880 caaadr caaar caadar caaddr caadr caar cadaar cadadr cadar caddar
8881 cadddr caddr cadr call/cc call-with-current-continuation
8882 call-with-port call-with-values car case case-lambda cdaaar cdaadr
8883 cdaar cdadar cdaddr cdadr cdar cddaar cddadr cddar cdddar cddddr
8884 cdddr cddr cdr ceiling char? char<? char<=? char=? char>? char>=?
8885 char->integer char-alphabetic? char-ci<? char-ci<=? char-ci=?
8886 char-ci>? char-ci>=? char-downcase char-foldcase char-lower-case?
8887 char-numeric? char-upcase char-upper-case? char-whitespace?
8888 close-input-port close-output-port close-port complex? cond
8889 cond-expand cons cos delay delay-force denominator digit-value do
8890 dynamic-wind else eof-object eof-object? eq? equal? eqv? error
8891 error-object? error-object-irritants error-object-message even?
8892 exact exact? exact-integer? exact-integer-sqrt exp expt finite?
8893 floor floor/ floor-quotient floor-remainder force for-each gcd
8894 get-output-bytevector get-output-string guard if imag-part inexact
8895 inexact? infinite? input-port? integer? integer->char lambda lcm
8896 length let let* let*-values letrec letrec* let-values list list?
8897 list->string list->vector list-copy list-ref list-set! list-tail
8898 log magnitude make-bytevector make-list make-parameter make-polar
8899 make-promise make-rectangular make-string make-vector map max
8900 member memq memv min modulo nan? negative? newline not null?
8901 number? number->string numerator odd? open-input-bytevector
8902 open-input-string open-output-bytevector open-output-string or
8903 output-port? pair? peek-char peek-u8 parameterize port? positive?
8904 procedure? promise? quasiquote quote quotient raise
8905 raise-continuable rational? rationalize read-bytevector
8906 read-bytevector! read-char read-error? read-line read-string
8907 read-u8 real? real-part remainder reverse round set! set-car!
8908 set-cdr! sin sqrt square string string? string<? string<=?
8909 string=? string>? string>=? string->list string->number
8910 string->utf8 string->vector string-append string-ci<? string-ci<=?
8911 string-ci=? string-ci>? string-ci>=? string-copy string-copy!
8912 string-downcase string-fill! string-foldcase string-for-each
8913 string-length string-map string-ref string-set! string-upcase
8914 substring symbol? symbol=? symbol->string tan textual-port?
8915 truncate truncate/ truncate-quotient truncate-remainder unless
8916 unquote unquote-splicing utf8->string values vector vector?
8917 vector->list vector->string vector-append vector-copy vector-copy!
8918 vector-fill! vector-for-each vector-length vector-map vector-ref
8919 vector-set! when with-exception-handler write-bytevector
8920 write-char write-string write-u8 zero?
8921 @end example
8922
8923 @c EN
8924 The module @code{srfi.172.functional} exports the above bindings
8925 except for:
8926 @c JP
8927 @code{srfi.172.functional}がエクスポートするのは、上のリストから
8928 以下のものを除いた束縛です。
8929 @c COMMON
8930
8931 @itemize @bullet
8932 @item
8933 @code{set!}
8934 @item
8935 @c EN
8936 Procedures whose names end with @code{!}:
8937 @c JP
8938 @code{!}で終わる手続き:
8939 @c COMMON
8940 @code{bytevector-copy!}, @code{bytevector-u8-set!}, @code{list-set!},
8941 @code{read-bytevector!}, @code{set-car!}, @code{set-cdr!},
8942 @code{string-copy!}, @code{string-fill!}, @code{string-set!},
8943 @code{vector-copy!}, @code{vector-fill!}, @code{vector-set!}
8944 @item
8945 @c EN
8946 Procedures whose names contain @code{port}:
8947 @c JP
8948 @code{port}が含まれる手続き:
8949 @c COMMON
8950 @code{call-with-port}, @code{close-input-port},
8951 @code{close-output-port}, @code{close-port}, @code{input-port?},
8952 @code{output-port?}, @code{port?}, @code{textual-port?}
8953 @item
8954 @c EN
8955 Procedures whose names begin with @code{read}:
8956 @c JP
8957 @code{read}で始まる手続き:
8958 @c COMMON
8959 @code{read-bytevector}, @code{read-bytevector!}, @code{read-char},
8960 @code{read-error?}, @code{read-line}, @code{read-string},
8961 @code{read-u8}
8962 @item
8963 @c EN
8964 Procedures whose names begin with @code{peek}:
8965 @c JP
8966 @code{peek}で始まる手続き:
8967 @c COMMON
8968 @code{peek-char}, @code{peek-u8}
8969 @item
8970 @c EN
8971 Procedures whose names begin with @code{write}:
8972 @c JP
8973 @code{write}で始まる手続き:
8974 @c COMMON
8975 @code{write-bytevector}, @code{write-char},
8976 @code{write-string}, @code{write-u8}
8977 @end itemize
8978 @end deftp
8979
8980 @c ----------------------------------------------------------------------
8981 @node Hooks (srfi), POSIX timespecs, Two safer subsets of R7RS, Library modules - SRFIs
8982 @section @code{srfi.173} - Hooks (srfi)
8983 @c NODE フック(srfi), @code{srfi.173} - フック(srfi)
8984
8985 @deftp {Module} srfi.173
8986 @mdindex srfi.173
8987 @c EN
8988 This module provides hooks, which manages a list of
8989 closures to be called.
8990
8991 It is based on Guile's hooks, which Gauche supports in
8992 @code{gauche.hook} module (@pxref{Hooks}). This srfi
8993 is a thin layer on top of @code{gauche.hook}.
8994
8995 The following procedures are the same as @code{gauche.hook}:
8996 @c JP
8997 このモジュールは、呼ばれるべきクロージャのリストを管理する「フック」を提供します。
8998
8999 GaucheではもともとGuileにあったhookの仕様を
9000 @code{gauche.hook}モジュールとして採り入れています
9001 (@ref{Hooks}参照)。
9002 このsrfiは@code{gauche.hook}に薄いレイヤをかぶせたものです。
9003
9004 以下の手続きは@code{gauche.hook}のものと同じです。
9005 @c COMMON
9006
9007 @example
9008 make-hook hook? hook->list
9009 @end example
9010 @end deftp
9011
9012 @defun hook-add! hook proc
9013 [SRFI-173]
9014 @c MOD srfi.173
9015 @c EN
9016 Add a procedure @var{proc} to a hook @var{hook}. The procedure
9017 must accept the number of arguments that matches the arity of the hook.
9018 It is the same as @code{(add-hook! hook proc)} of @code{gauche.hook}.
9019 @c JP
9020 手続き@var{proc}をフック@var{hook}に追加します。手続きは、フックのアリティと
9021 同じ数の引数を受け付けなければなりません。
9022 これは@code{gauche.hook}の@code{(add-hook! hook proc)}と同じです。
9023 @c COMMON
9024 @end defun
9025
9026 @defun hook-delete! hook proc
9027 [SRFI-173]
9028 @c MOD srfi.173
9029 @c EN
9030 Delete @var{proc} from @var{hook}. If @var{proc} isn't in @var{hook},
9031 do nothing. It is the same as @code{(delete-hook! hook proc)}
9032 of @code{gauche.hook}.
9033 @c JP
9034 @var{proc}を@var{hook}から削除します。@var{proc}が@var{hook}に登録されていない
9035 場合は何もしません。
9036 @code{gauche.hook}の@code{(delete-hook! hook proc)}と同じです。
9037 @c COMMON
9038 @end defun
9039
9040 @defun hook-reset! hook
9041 [SRFI-173]
9042 @c MOD srfi.173
9043 @c EN
9044 Remove all the procedures registered in @var{hook}.
9045 It is the same as @code{(reset-hook! hook)} of @code{gauche.hook}.
9046 @c JP
9047 @var{hook}に登録された全ての手続きを削除します。
9048 @code{gauche.hook}の@code{(reset-hook! hook)}と同じです。
9049 @c COMMON
9050 @end defun
9051
9052 @defun hook-run hook args @dots{}
9053 [SRFI-173]
9054 @c MOD srfi.173
9055 @c EN
9056 Apply all the procedures from @var{hook} to the @var{args}.
9057 The order of the procedure isn't specified in the srfi, though
9058 Gauche preserves the order (see @code{run-hook}
9059 (@pxref{Hooks}).
9060 @c JP
9061 @var{hook}に登録された手続き全てを順次、@var{args}を引数として呼び出します。
9062 srfiでは手続きを呼び出す順番は指定されていません。
9063 Gaucheは登録された順序で呼び出します
9064 (@ref{Hooks}の@code{run-hook}参照)。
9065 @c COMMON
9066 @end defun
9067
9068 @defun list->hook arity list
9069 [SRFI-173]
9070 @c MOD srfi.173
9071 @c EN
9072 Creates a new hook with specified @var{arity} (which is a non-negative
9073 exact integer), which has the procedures in @var{list}.
9074 All the procedures must accept @var{arity} number of arguments.
9075 @c JP
9076 アリティ@var{arity} (非負の正確な整数) を持つフックを作り、
9077 手続きのリスト@var{list}中の手続きをフックに登録して、そのフックを返します。
9078 全ての手続きは@var{arity}個の引数を受け付けなくてはなりません。
9079 @c COMMON
9080 @end defun
9081
9082 @defun list->hook! hook list
9083 [SRFI-173]
9084 @c MOD srfi.173
9085 @c EN
9086 Replace the list of procedures in @var{hook} with procedures
9087 in @var{list}.
9088 All the procedures must accept the number of arguments
9089 the same as @var{hook}'s arity.
9090 @c JP
9091 フック@var{hook}に登録された手続きのリストを、@var{list}にある手続きと
9092 置き換えます。
9093 全ての手続きは@var{arity}個の引数を受け付けなくてはなりません。
9094 @c COMMON
9095 @end defun
9096
9097 @c ----------------------------------------------------------------------
9098 @node POSIX timespecs, ASCII character library, Hooks (srfi), Library modules - SRFIs
9099 @section @code{srfi.174} - POSIX timespecs
9100
9101 @deftp {Module} srfi.174
9102 @mdindex srfi.174
9103 @c EN
9104 Note: This srfi is originally intended to be used with SRFI-170
9105 (@pxref{POSIX API}), but it turned out this was not enough to support
9106 the latter--notably, we need SRFI-19 type argument in the constructor.
9107 @c JP
9108 註: このsrfiはSRFI-170 (@ref{POSIX API}参照)で使うための補助ライブラリとして
9109 作られたのですが、その後の議論で不十分であることがわかりました。
9110 特に、SRFI-19の時間の型をコンストラクタで指定することが不可欠だとわかったのです。
9111 @c COMMON
9112
9113 @c EN
9114 Consequently, it is likely that this srfi will be superseded later.
9115 We deprecate using this srfi; if you need a portable time representation,
9116 SRFI-19 is the best choice at this moment. @xref{Time data types and procedures},
9117 for the details.
9118 @c JP
9119 従って、このsrfiは将来のsrfiで置き換えられる可能性が高く、使用は非推奨です。
9120 ポータブルな時間の表現が必要であれば、SRFI-19を使ってください
9121 (@ref{Time data types and procedures}参照)。
9122 @c COMMON
9123 @end deftp
9124
9125 @defun timespec secs nsecs
9126 [SRFI-174]
9127 @c MOD srfi.174
9128 Creates and returns a timespec, whose second part is @var{secs} and
9129 nanosecond part is @var{nsecs}. The second part must be an exact
9130 integer; if it is positive, it's the number of seconds since
9131 Epoch (Jan 1, 1970 UTC), and if it's negative, it's before the Epoch.
9132 The nanosecond part is a nonnegative integer less than 1e9, and represents
9133 the fraction of seconds in nanosecond resolution. Note that if the second
9134 part is negative, the nanosecond part counts toward past.
9135
9136 This is the same as @code{(make-time time-utc nsecs secs)} of
9137 SRFI-19. Note the order of arguments.
9138 @end defun
9139
9140 @defun timespec? obj
9141 [SRFI-174]
9142 @c MOD srfi.174
9143 Returns @code{#t} iff @var{obj} is a @code{<time>} object. It doesn't
9144 check the type of time.
9145 @end defun
9146
9147 @defun timespec-seconds ts
9148 @defunx timespec-nanosecods ts
9149 [SRFI-174]
9150 @c MOD srfi.174
9151 Returns second and nanosecond part of the @code{<time>} object.
9152 Same as @code{time-second} and @code{time-nanosecond} of SRFI-19
9153 (note that we use plurals in this srfi).
9154 @end defun
9155
9156 @defun inexact->timespec v
9157 [SRFI-174]
9158 @c MOD srfi.174
9159 Convert an inexact real number @var{v} to a timespec. The integral part
9160 of @var{v} is the seconds after (when @var{v} is positive)
9161 or before (when @var{v} is negative) the Epoch, and the fractional part
9162 is rounded into nanosecond resolution.
9163 @end defun
9164
9165 @defun timespec->inexact ts
9166 [SRFI-174]
9167 Convert a timespec into an inexact real number in seconds.
9168 @c MOD srfi.174
9169 @end defun
9170
9171 @defun timespec=? ts1 ts2
9172 [SRFI-174]
9173 @c MOD srfi.174
9174 Returns @code{#t} iff two timespecs are the same.
9175 It is the same as @code{time=?} in SRFI-19.
9176 @end defun
9177
9178 @defun timespec<? ts1 ts2
9179 [SRFI-174]
9180 @c MOD srfi.174
9181 Returns @code{#t} iff a timespec @var{ts1} is strictly before
9182 the timespec @var{ts2}. It is the same as @code{time<?} in SRFI-19.
9183 @end defun
9184
9185 @defun timespec-hash ts
9186 [SRFI-174]
9187 @c MOD srfi.174
9188 Compute a hash value of a timespec @var{ts}. It is same as
9189 passing a @code{<time>} object to @code{default-hash}, and
9190 affected by the current hash salt value (@pxref{Hashing}).
9191 @end defun
9192
9193 @c ----------------------------------------------------------------------
9194 @node ASCII character library, Bitvector library, POSIX timespecs, Library modules - SRFIs
9195 @section @code{srfi.175} - ASCII character library
9196 @c NODE ASCII文字ライブラリ, @code{srfi.175} - ASCII文字ライブラリ
9197
9198 @deftp {Module} srfi.175
9199 @mdindex srfi.175
9200 @c EN
9201 This module provides a set of character/string utilities that deal with
9202 ASCII characters and codepoints. It is particulary useful for small
9203 Scheme implementations that only handles, and a portable
9204 code that only concerns, ASCII characters.
9205 @c JP
9206 ASCII文字とASCIIコードポイントを扱うユーティリティを提供するモジュールです。
9207 ASCIIだけを対象とする小さなScheme実装や、ASCIIだけを対象とするポータブルな
9208 コードを書きたい場合に便利です。
9209 @c COMMON
9210
9211 @c EN
9212 Since Gauche supports full Unicode, you may not need to use this module
9213 to write Gauche-specific code. This is mainly for the compatibility.
9214 @c JP
9215 GaucheはUnicodeの全ての文字を扱えるので、Gauche用のコードを書いている時には
9216 敢えてこのモジュールを使う必要は無いでしょう。互換性のために用意しています。
9217 @c COMMON
9218
9219 @c EN
9220 One of the characteristics of this module is that many procedures can
9221 take an integer in place of a character; an integer between 0 and 127
9222 is interpreted as an ASCII codepoint. An integer outside the range
9223 is interpreted as an non-ASCII codepoint. Such argument is noted
9224 as @var{char-or-code} in the description. It is handy while you're
9225 dealing with a binary file which may contain some ASCII text in it.
9226 @c JP
9227 このモジュールに特徴的なのは、多くの手続きで、文字のかわりに整数を取れることです。
9228 0と127の間の正確な整数はASCIIコードポイントと解釈されます。
9229 それ以外の整数は非ASCIIコードポイントと解釈されます。
9230 文字と整数の両方を取れる引数は、@var{char-or-code}と表記しています。
9231 例えばバイナリファイルの一部にASCIIテキストが含まれるものを扱う際に便利でしょう。
9232 @c COMMON
9233 @end deftp
9234
9235 @defun ascii-codepoint? obj
9236 [SRFI-175]
9237 @c MOD srfi.175
9238 @c EN
9239 Returns @code{#t} iff @var{obj} is an exact integer between 0 and 127,
9240 inclusive.
9241 @c JP
9242 @var{obj}が0..127の範囲の正確な整数であれば@code{#t}を、そうでなければ@code{#f}を
9243 返します。
9244 @c COMMON
9245 @end defun
9246
9247 @defun ascii-bytevecotr? obj
9248 [SRFI-175]
9249 @c MOD srfi.175
9250 @c EN
9251 Returns @code{#t} iff @var{obj} is a bytevector (@code{u8vector}) and
9252 all of its elements are between 0 and 127, inclusive.
9253 @c JP
9254 @var{obj}がバイトベクタ(@code{u8vector})で、全ての要素が0..127の範囲に収まっていれば
9255 @code{#t}を、そうでなければ@code{#f}を返します。
9256 @c COMMON
9257 @end defun
9258
9259 @defun ascii-char? obj
9260 [SRFI-175]
9261 @c MOD srfi.175
9262 @c EN
9263 Returns @code{#t} iff @var{obj} is an ASCII character.
9264 @c JP
9265 @var{obj}がASCII文字であれば@code{#t}を、そうでなければ@code{#f}を返します。
9266 @c COMMON
9267 @end defun
9268
9269 @defun ascii-string? obj
9270 [SRFI-175]
9271 @c MOD srfi.175
9272 @c EN
9273 Returns @code{#t} iff @var{obj} is a string and all of its elements
9274 are ASCII characters.
9275 @c JP
9276 @var{obj}が文字列で、その中の全ての文字がASCII文字なら@code{#t}を、そうでなければ
9277 @code{#f}を返します。
9278 @c COMMON
9279 @end defun
9280
9281 @defun ascii-control? char-or-code
9282 [SRFI-175]
9283 @c MOD srfi.175
9284 @c EN
9285 Returns @code{#t} iff @var{char-or-code} is in the range of
9286 ASCII control characters
9287 @c JP
9288 @var{char-or-code}がASCII制御文字の範囲なら@code{#t}を、そうでなければ@code{#f}を
9289 返します。
9290 @c COMMON
9291
9292 @example
9293 (ascii-control? #\tab) @result{} #t
9294 (ascii-control? #\A) @result{} #f
9295
9296 (ascii-control? 127) @result{} #t
9297 (ascii-control? 255) @result{} #f
9298 @end example
9299
9300 @c EN
9301 Note: The accepted character range corresponds to
9302 @code{char-set:ascii-control} (@pxref{Predefined character sets}).
9303 @c JP
9304 @code{#t}が返される文字の集合は@code{char-set:ascii-control}と
9305 一致します (@ref{Predefined character sets}参照)。
9306 @c COMMON
9307 @end defun
9308
9309 @defun ascii-non-control? char-or-code
9310 [SRFI-175]
9311 @c MOD srfi.175
9312 @c EN
9313 Returns @code{#t} iff @var{char-or-code} is in the range of ASCII but
9314 not a control character.
9315 @c JP
9316 @var{char-or-code}がASCIIの範囲でかつ制御文字でなければ@code{#t}を、
9317 そうでなければ@code{#f}を
9318 返します。
9319 @c COMMON
9320 @end defun
9321
9322 @defun ascii-space-or-tab? char-or-code
9323 [SRFI-175]
9324 @c MOD srfi.175
9325 @c EN
9326 Returns @code{#t} iff @var{char-or-code} is a tab or a whitespace.
9327 @c JP
9328 @var{char-or-code}がタブ文字かASCII空白文字であれば@code{#t}を、
9329 そうでなければ@code{#f}を返します。
9330 @c COMMON
9331 @end defun
9332
9333 @defun ascii-other-graphic? char-or-code
9334 [SRFI-175]
9335 @c MOD srfi.175
9336 @c EN
9337 Returns @code{#t} iff @var{char-or-code} is in the range of ASCII
9338 graphic characters but not a letter nor a digit.
9339 @c JP
9340 @var{char-or-code}がASCIIの範囲で、アルファベットと数字以外の
9341 グラフィック文字であれば@code{#t}を返します。
9342 @c COMMON
9343
9344 @c EN
9345 Note: The accepted character range corresponds to
9346 @code{(char-set-difference char-set:ascii-graphic char-set:ascii-letter+digit)}
9347 (@pxref{Predefined character sets}).
9348 @c JP
9349 @code{#t}が返される文字の集合は
9350 @code{(char-set-difference char-set:ascii-graphic char-set:ascii-letter+digit)}と
9351 一致します (@ref{Predefined character sets}参照)。
9352 @c COMMON
9353 @end defun
9354
9355 @defun ascii-alphanumeric? char-or-code
9356 [SRFI-175]
9357 @c MOD srfi.175
9358 @c EN
9359 Returns @code{#t} iff @var{char-or-code} is in the ASCII alphabet or digit
9360 range.
9361 @c JP
9362 @var{char-or-code}がASCIIアルファベットか数字であれば@code{#t}を、
9363 そうでなければ@code{#f}を返します。
9364 @c COMMON
9365
9366 @c EN
9367 Note: The accepted character range corresponds to
9368 @code{char-set:ascii-letter+digit}
9369 (@pxref{Predefined character sets}).
9370 @c JP
9371 @code{#t}が返される文字の集合は
9372 @code{char-set:ascii-letter+digit}と
9373 一致します (@ref{Predefined character sets}参照)。
9374 @c COMMON
9375 @end defun
9376
9377 @defun ascii-alphabetic? char-or-code
9378 [SRFI-175]
9379 @c MOD srfi.175
9380 @c EN
9381 Returns @code{#t} iff @var{char-or-code} is in the ASCII alphabet range.
9382 @c JP
9383 @var{char-or-code}が
9384 @c COMMON
9385
9386 @c EN
9387 Note: The accepted character range corresponds to
9388 @code{char-set:ascii-letter}
9389 (@pxref{Predefined character sets}).
9390 @c JP
9391 @code{#t}が返される文字の集合は
9392 @code{char-set:ascii-letter}と
9393 一致します (@ref{Predefined character sets}参照)。
9394 @c COMMON
9395 @end defun
9396
9397 @defun ascii-numeric? char-or-code
9398 [SRFI-175]
9399 @c MOD srfi.175
9400 Returns @code{#t} iff @var{char-or-code} is in the ASCII digit range.
9401
9402 @c EN
9403 Note: The accepted character range corresponds to
9404 @code{char-set:ascii-digit}
9405 (@pxref{Predefined character sets}).
9406 @c JP
9407 @code{#t}が返される文字の集合は
9408 @code{char-set:ascii-digit}と
9409 一致します (@ref{Predefined character sets}参照)。
9410 @c COMMON
9411 @end defun
9412
9413 @defun ascii-whitespace? char-or-code
9414 [SRFI-175]
9415 @c MOD srfi.175
9416 Returns @code{#t} iff @var{char-or-code} is one of the ASCII whitespaces.
9417
9418 @c EN
9419 Note: The accepted character range corresponds to
9420 @code{char-set:ascii-whitespace}
9421 (@pxref{Predefined character sets}).
9422 @c JP
9423 @code{#t}が返される文字の集合は
9424 @code{char-set:ascii-whitespace}と
9425 一致します (@ref{Predefined character sets}参照)。
9426 @c COMMON
9427 @end defun
9428
9429 @defun ascii-upper-case? char-or-code
9430 @defunx ascii-lower-case? char-or-code
9431 [SRFI-175]
9432 @c MOD srfi.175
9433 Returns @code{#t} iff @var{char-or-code} is one of upper/lower case
9434 ASCII alphabets.
9435
9436 @c EN
9437 Note: The accepted character range corresponds to
9438 @code{char-set:ascii-upper-case}/@code{char-set:ascii-lower-case}
9439 (@pxref{Predefined character sets}).
9440 @c JP
9441 @code{#t}が返される文字の集合は
9442 @code{char-set:ascii-upper-case}/@code{char-set:ascii-lower-case}と
9443 一致します (@ref{Predefined character sets}参照)。
9444 @c COMMON
9445 @end defun
9446
9447 @defun ascii-ci=? char-or-code1 char-or-code2
9448 @defunx ascii-ci<? char-or-code1 char-or-code2
9449 @defunx ascii-ci<=? char-or-code1 char-or-code2
9450 @defunx ascii-ci>? char-or-code1 char-or-code2
9451 @defunx ascii-ci>=? char-or-code1 char-or-code2
9452 [SRFI-175]
9453 @c MOD srfi.175
9454 @c EN
9455 Each argument may be a character or a codepoint. If the argument
9456 falls into ASCII upper case letters, it is converted to the corresponding
9457 lower case letter codepoint, and then two are compared as codepoints.
9458 Two arguments don't need to be of the same type.
9459 @c JP
9460 各引数は文字かコードポイントです。引数がASCIIの大文字に相当する場合、それは対応する小文字の
9461 コードポイントに変換され、その後コードポイント同士の比較結果が返されます。
9462 二つの引数の型が一致している必要はありません。
9463 @c COMMON
9464
9465 @c EN
9466 It is allowed to pass non-ascii range; if it is a non-ASCII character,
9467 its codepoint of the native encoding is taken (no case-folding is considered),
9468 and compared as codepoints. Of course the result are not portable, except
9469 that any non-ASCII character has a codepoint greater than any ASCII characters.
9470 @c JP
9471 ASCII範囲外の引数を渡すことは許されます。非ASCII文字は内部エンコーディングによるコードポイント
9472 に変換されます(大文字小文字は考慮されません)。非ASCII文字はASCII文字より大きい、
9473 ということ以外、結果は処理系依存になります。
9474 @c COMMON
9475 @end defun
9476
9477 @defun ascii-string-ci=? string1 string2
9478 @defunx ascii-string-ci<? string1 string2
9479 @defunx ascii-string-ci<=? string1 string2
9480 @defunx ascii-string-ci>? string1 string2
9481 @defunx ascii-string-ci>=? string1 string2
9482 [SRFI-175]
9483 @c MOD srfi.175
9484 @c EN
9485 Compares two strings with ASCII case folding. Argument strings may
9486 contain non-ASCII characters; such characters are compared without
9487 case folding.
9488 @c JP
9489 ASCII文字の範囲で大文字小文字を考慮せずに、二つの文字列を比較します。
9490 文字列は非ASCII文字を含んでいても構いません。それらについては大文字小文字の考慮はせず、
9491 内部エンコーディングのコードポイントを使って比較します。
9492 @c COMMON
9493 @end defun
9494
9495 @defun ascii-upcase char-or-code
9496 @defunx ascii-downcase char-or-code
9497 [SRFI-175]
9498 @c MOD srfi.175
9499 @c EN
9500 If the argument represents a ASCII upper/lower case letter,
9501 returns the corresponding lower/upper case character or codepoint.
9502 The type of the return value is the same as the argument.
9503 If the argument is a character or a codepoint other than that,
9504 it is returned as is.
9505 @c JP
9506 引数がASCIIの大文字/小文字に相当する場合、対応する小文字/大文字の文字またはコードポイントを
9507 返します。戻り値は引数と同じ型になります。
9508 引数がそれ以外の文字に相当する場合は、そのまま返されます。
9509 @c COMMON
9510 @end defun
9511
9512 @defun ascii-control->graphic char-or-code
9513 @defunx ascii-graphic->control char-or-code
9514 [SRFI-175]
9515 @c MOD srfi.175
9516 @c EN
9517 ASCII control characters (@code{#\x00}, @code{#\x01} .. @code{#\x1f},
9518 and @code{#\x7f})
9519 are sometimes noted as @code{^@@}, @code{^A} .. @code{^_}, and @code{^?}.
9520 These procedures converts the control character and corresponding
9521 graphical character (the one comes after @code{^}), and vice versa.
9522 The type of the return value is the same as the argument.
9523 @c JP
9524 ASCII制御文字(@code{#\x00}, @code{#\x01} .. @code{#\x1f},
9525 and @code{#\x7f})はしばしば、
9526 @code{^@@}, @code{^A} .. @code{^_} および @code{^?} のように
9527 表記されます。これらの手続きは、制御文字とその表記 (@code{^}の後に来る文字)とを
9528 相互に変換するものです。
9529 戻り値の型は引数と同じになります。
9530 @c COMMON
9531
9532 @c EN
9533 If the argument isn't an ASCII control character / a graphical character
9534 that corresponds to an ASCII control character, @code{#f} is returned.
9535 @c JP
9536 引数がASCII制御文字/制御文字に対応するASCII表示文字でなければ、@code{#f}が返ります。
9537 @c COMMON
9538 @end defun
9539
9540 @defun ascii-mirror-bracket char-or-code
9541 [SRFI-175]
9542 @c MOD srfi.175
9543 @c EN
9544 There are four pairs of brackets in ASCII: @code{(} and @code{)},
9545 @code{@{} and @code{@}}, @code{[} and @code{]}, and @code{<} and @code{>}.
9546 If @var{char-or-code} is either one of these eight chars or codepoints,
9547 returns the corresponding bracket.
9548 The type of the return value is the same as the argument.
9549 @c JP
9550 ASCIIには4ペアの括弧があります。@code{(}と@code{)}、
9551 @code{@{}と@code{@}}、@code{[}と@code{]}、そして@code{<}と@code{>}です。
9552 引数@var{char-or-code}がこれら8文字のいずれかに相当する場合に、
9553 それと対になる文字またはコードポイントを返します。
9554 戻り値の型は引数と同じになります。
9555 @c COMMON
9556
9557 @c EN
9558 If the argument is a char or a codepoint other than those brackets,
9559 @code{#f} is returned.
9560 @c JP
9561 引数が括弧の文字またはコードポイントでなければ、@code{#f}が返されます。
9562 @c COMMON
9563 @end defun
9564
9565 @defun ascii-nth-digit n
9566 [SRFI-175]
9567 @c MOD srfi.175
9568 @c EN
9569 Returns a digit character representing the number @var{n}.
9570 If @var{n} is not an exact integer between 0 and 9, inclusive,
9571 @code{#f} is returned.
9572 @c JP
9573 数値@var{n}を表すASCII数字文字を返します。@var{n}が0から9までの正確な整数でない
9574 場合は@code{#f}を返します。
9575 @c COMMON
9576
9577 @example
9578 (ascii-nth-digit 3) @result{} #\3
9579 @end example
9580
9581 @c EN
9582 See also @code{integer->digit} (@pxref{Characters}).
9583 @c JP
9584 @code{integer->digit} (@ref{Characters})も参照。
9585 @c COMMON
9586 @end defun
9587
9588 @defun ascii-nth-upper-case n
9589 @defunx ascii-nth-lower-case n
9590 [SRFI-175]
9591 @c MOD srfi.175
9592 @c EN
9593 Returns @code{(modulo @var{n} 26)}-th character of upper/lower case
9594 ASCII alphabet.
9595 @c JP
9596 @code{(modulo @var{n} 26)}番目のASCII大文字/小文字アルファベットを返します。
9597 @c COMMON
9598
9599 @example
9600 (ascii-nth-upper-case 0) @result{} #\A
9601 (ascii-nth-lower-case 1) @result{} #\b
9602
9603 (ascii-nth-upper-case 25) @result{} #\Z
9604 (ascii-nth-lower-case 26) @result{} #\a
9605 @end example
9606
9607 @c EN
9608 See also @code{integer->digit} (@pxref{Characters}).
9609 @c JP
9610 @code{integer->digit} (@ref{Characters})も参照。
9611 @c COMMON
9612 @end defun
9613
9614 @defun ascii-digit-value char-or-code limit
9615 [SRFI-175]
9616 @c MOD srfi.175
9617 @c EN
9618 If @var{char-or-code} represents an ASCII decimal digits and
9619 the corresponding number is less than @var{limit},
9620 returns the number. Otherwise, returns @code{#f}.
9621 @c JP
9622 @var{char-or-code}がASCII数字文字またはそのコードポイントであり、
9623 それが表す数値が@var{limit}未満であればその数値を、
9624 そうでなければ@code{#f}を返します。
9625 @c COMMON
9626
9627 @example
9628 (ascii-digit-value #\5 10) @result{} 5
9629 (ascii-digit-value #\9 8) @result{} #f
9630
9631 (ascii-digit-value 48 10) @result{} 0
9632 @end example
9633
9634 @c EN
9635 See also @code{digit->integer} (@pxref{Characters}).
9636 @c JP
9637 @code{digit->integer} (@ref{Characters})も参照。
9638 @c COMMON
9639 @end defun
9640
9641 @defun ascii-upper-case-value char-or-code offset limit
9642 @defunx ascii-lower-case-value char-or-code offset limit
9643 [SRFI-175]
9644 @c MOD srfi.175
9645 @c EN
9646 If @var{char-or-code} is n-th ASCII upper/lower case alphabet,
9647 and @var{n} is less than @var{limit}, returns @code{(+ @var{n} @var{offset})}.
9648 Otherwise returns @code{#f}.
9649 @c JP
9650 @var{char-or-code}がn番目のASCII大文字/小文字またはそのコードポイントで、
9651 nが@var{limit}未満であれば、@code{(+ @var{n} @var{offset})}を返します。
9652 そうでなければ@code{#f}を返します。
9653 @c COMMON
9654
9655 @example
9656 (ascii-upper-case-value #\E 10 6) @result{} 14
9657 (ascii-lower-case-value #\z 0 26) @result{} 25
9658 @end example
9659
9660 @c EN
9661 See also @code{digit->integer} (@pxref{Characters}).
9662 @c JP
9663 @code{digit->integer} (@ref{Characters})も参照。
9664 @c COMMON
9665 @end defun
9666
9667 @c ----------------------------------------------------------------------
9668 @node Bitvector library, JSON, ASCII character library, Library modules - SRFIs
9669 @section @code{srfi.178} - Bitvector library
9670 @c NODE ビットベクタライブラリ, @code{srfi.178} - ビットベクタライブラリ
9671
9672 @deftp {Module} srfi.178
9673 @mdindex srfi.178
9674 @c EN
9675 Gauche supports all SRFI-178 operations by built-in procedures
9676 and the module @code{gauche.bitvector}.
9677 @c JP
9678 GaucheはSRFI-178の全ての手続きを、組み込みか@code{gauche.bitvector}モジュールでサポートしています。
9679 @c COMMON
9680
9681 @c EN
9682 The following procedures are built-in. @xref{Bitvectors}, for the description.
9683 @c JP
9684 以下の手続きは組み込みです。@ref{Bitvectors}を参照してください。
9685 @c COMMON
9686
9687 @example
9688 bit->integer bit->boolean
9689 bitvector make-bitvector list->bitvector
9690 bitvector? bitvector-length
9691 string->bitvector bitvector->string
9692 bitvector-ref/int bitvector-ref/bool
9693 bitvector-set! bitvector-copy bitvector-copy!
9694 @end example
9695
9696 @c EN
9697 The following procedures are provided in @ref{Bitvector utilities}.
9698 @c JP
9699 以下の手続きは@ref{Bitvector utilities}で説明されます。
9700 @c COMMON
9701
9702 @example
9703 bitvector-unfold bitvector-unfold-right bitvector-reverse-copy
9704 bitvector-append bitvector-concatenate bitvector-append-subbitvectors
9705 bitvector-emtpy? bitvector=?
9706 bitvector-take bitvector-take-right
9707 bitvector-drop bitvector-drop-right
9708 bitvector-segment
9709 bitvector-fold/int bitvector-fold/bool
9710 bitvector-fold-right/int bitvector-fold-right/bool
9711 bitvector-map/int bitvetor-map/bool
9712 bitvector-map!/int bitvetor-map!/bool
9713 bitvector-map->list/int bitvector-map->list/bool
9714 bitvector-for-each/int bitvector-for-each/bool
9715 bitvector-prefix-length bitvector-suffix-length
9716 bitvector-prefix? bitvector-suffix?
9717 bitvector-pad bitvector-pad-right
9718 bitvector-trim bitvector-trim-right bitvector-trim-both
9719 bitvector-swap! bitvector-reverse! bitvector-reverse-copy!
9720 bitvector->list/int bitvector->list/bool
9721 reverse-bitvector->list/int reverse-bitvector->list/bool
9722 reverse-list->bitvector
9723 bitvector->vector/int bitvector->vector/bool
9724 reverse-bitvector->vector/int reverse-bitvector->vector/bool
9725 vector->bitvector reverse-vector->bitvector
9726 bitvector->integer
9727 integre->bitvector
9728 make-bitvector/int-generator make-bitvector/bool-generator
9729 make-bitvector-accumulator
9730 bitvector-not bitvector-not!
9731 bitvector-and bitvector-and!
9732 bitvector-ior bitvector-ior!
9733 bitvector-xor bitvector-xor!
9734 bitvector-eqv bitvector-eqv!
9735 bitvector-nand bitvector-nand!
9736 bitvector-nor bitvector-nor!
9737 bitvector-andc1 bitvector-andc1!
9738 bitvector-andc2 bitvector-andc2!
9739 bitvector-orc1 bitvector-orc1!
9740 bitvector-orc2 bitvector-orc2!
9741 bitvector-logical-shift
9742 bitvector-count bitvector-count-run
9743 bitvector-if
9744 bitvector-first-bit
9745 bitvector-field-any? bitvector-field-every?
9746 bitvector-field-clear bitvector-field-clear!
9747 bitvector-field-set bitvector-field-set!
9748 bitvector-field-replace bitvector-field-replace!
9749 bitvector-field-replace-same bitvector-field-replace-same!
9750 bitvector-field-rotate
9751 bitvector-field-flip bitvector-field-flip!
9752 @end example
9753 @end deftp
9754
9755 @c ----------------------------------------------------------------------
9756 @node JSON, Custom ports, Bitvector library, Library modules - SRFIs
9757 @section @code{srfi.180} - JSON
9758
9759 @deftp {Module} srfi.180
9760 @mdindex srfi.180
9761 @c EN
9762 This srfi defines the means of parsing and constructin JSON.
9763
9764 In Gauche, this module is implemented on top of @code{rfc.json} module
9765 (@pxref{JSON parsing and construction}).
9766 Notably, the parameter @code{json-nesting-depth-limit} is the same
9767 as the one in @code{rfc.json}.
9768 @c JP
9769 このsrfiはJSONフォーマットをパーズ、および構築する手段を定義します。
9770
9771 Gaucheでは、このモジュールは@code{rfc.json}の上に実装されています
9772 (@ref{JSON parsing and construction}参照)。
9773 特に、@code{json-nesting-depth-limit}パラメータは@code{rfc.json}のものと同じです。
9774 @c COMMON
9775
9776 @c EN
9777 Gauche's @code{rfc.json} is more flexible in terms of mapping
9778 JSON objects to Scheme objects. On the other hand, @code{srfi.180}
9779 provides a streaming parser/generator, which allows the caller
9780 to process input as it is read, instead of waiting the entire
9781 input to be parsed.
9782 @c JP
9783 Gaucheの@code{rfc.json}は、JSONオブジェクトとSchemeオブジェクト間のマッピングを
9784 カスタマイズできるという点でより柔軟です。一方、
9785 @code{srfi.180}はストリーミングパーザとジェネレータを提供しており、
9786 入力を全て読んでからパーズ結果を得るのではなく、入力を読みながら処理することができます。
9787 @c COMMON
9788 @end deftp
9789
9790 @c EN
9791 @subheading Predicates and parameters
9792 @c JP
9793 @subheading 述語とパラメータ
9794 @c COMMON
9795
9796 @defun json-error? obj
9797 [SRFI-180]
9798 @c MOD srfi.180
9799 @c EN
9800 JSON reader and writer raise a condition that satisfies
9801 this predicate when it encounters invalid JSON syntax and/or object,
9802 or the input exceeds the limits specified by
9803 @code{json-nesting-depth-limit} or
9804 @code{json-number-of-character-limit} parameters.
9805 @c JP
9806 JSONのリーダとライターは、不正なJSON構文や、JSONで表現できないオブジェクトに
9807 行き当たった場合、あるいは入力がパラメータ@code{json-nesting-depth-limit}や
9808 や@code{json-number-of-character-limit}で示される限度を越えた場合に、
9809 この述語を満たすコンディションオブジェクトを投げます。
9810 @c COMMON
9811
9812 @c EN
9813 Since @code{srfi.180} is implemented on top of @code{rfc.json},
9814 which raises a condition @code{<json-parse-error>} for input and
9815 @code{<json-construct-error>} for the output, this predicate simply
9816 returns @code{#t} iff @var{obj} is an instance of either class.
9817 @xref{JSON parsing and construction}, for the detail of these conditions.
9818 @c JP
9819 Gaucheでは@code{srfi.180}は@code{rfc.json}上に実装されていて、
9820 @code{rfc.json}はパーズ時のエラーには@code{<json-parse-error>}を、
9821 構築時のエラーには@code{<json-construct-error>}を投げるので、
9822 この述語は@var{obj}がそれらのクラスのどちらかのインスタンスであれば
9823 @code{#t}を返します。
9824 これらのコンディションについては@ref{JSON parsing and construction}を参照してください。
9825 @c COMMON
9826 @end defun
9827
9828 @defun json-error-reason err
9829 [SRFI-180]
9830 @c MOD srfi.180
9831 @c EN
9832 Returns a string explaining the reason for the error @var{err},
9833 if @var{err} is a JSON error object (an object that satisfies
9834 @code{json-error?}).
9835 @c JP
9836 @var{err}がJSONエラーオブジェクト (@code{json-error?}を満たすオブジェクト)
9837 であった場合、エラーの理由を説明する文字列を返します。
9838 @c COMMON
9839
9840 @c EN
9841 In Gauche, a JSON error object is an instance of either
9842 @code{<json-parse-error>} or @code{<json-construct-error>})
9843 conditions, and @code{json-error-reason} simply returns the content of
9844 its @code{message} slot.
9845 @c JP
9846 GaucheではJSONエラーオブジェクトは@code{<json-parse-error>}か
9847 @code{<json-construct-error>}コンディションタイプのインスタンスであり、
9848 @code{json-error-reason}は単にコンディションオブジェクトの@code{message}スロットの
9849 値を返します。
9850 @c COMMON
9851 @end defun
9852
9853 @defun json-null? obj
9854 [SRFI-180]
9855 @c MOD srfi.180
9856 @c EN
9857 Returns @code{#t} iff @var{obj} is the symbol @code{null}.
9858 @c JP
9859 @var{obj}がシンボル@code{null}であれば@code{#t}を、そうでなければ@code{#f}を返します。
9860 @c COMMON
9861 @end defun
9862
9863 @deffn {Parameter} json-number-of-character-limit
9864 [SRFI-180]
9865 @c MOD srfi.180
9866 @c EN
9867 A parameter that holds a real value. If the number of characters
9868 of input JSON text exceeds the value while @code{json-generator},
9869 @code{json-fold} or @code{json-read} is processing the input,
9870 a JSON error is thrown.
9871 @c JP
9872 実数を値に持つパラメータです。@code{json-generator}、@code{json-fold}、
9873 および@code{json-read}で入力のJSONテキストの文字数がこの値を越えた場合、
9874 JSONエラーが投げられます。
9875 @c COMMON
9876 @end deffn
9877
9878 @c EN
9879 @subheading JSON reader
9880 @c JP
9881 @subheading JSONリーダ
9882 @c COMMON
9883
9884 @defun json-generator :optional port-or-generator
9885 [SRFI-180]
9886 @c MOD srfi.180
9887 @c EN
9888 Streaming parser. The input @var{port-or-generator} must be
9889 an input port, or a char generator.
9890 @c JP
9891 ストリーミングパーザ。
9892 @var{port-or-generator}は入力ポートか、文字のジェネレータでなければなりません。
9893 @c COMMON
9894
9895 @c EN
9896 Each time it is called, it returns one of the following values, parsed
9897 from the input.
9898 @c JP
9899 この手続きは、呼ばれる度に、必要なだけ入力を読んで次のいずれかの値を返します。
9900 @c COMMON
9901
9902 @c EN
9903 @table @asis
9904 @item string
9905 JSON string.
9906 @item real number
9907 JSON number.
9908 @item @code{#t}, @code{#f}
9909 JSON @code{true} and @code{false}
9910 @item @code{null}
9911 JSON @code{null}
9912 @item @code{array-start}
9913 The beginning of an array. What follows is the array's element,
9914 up to the matching @code{array-end}.
9915 @item @code{array-end}
9916 The ending of an array.
9917 @item @code{object-start}
9918 The beginning of an object. What follows is alternating
9919 string keys and JSON values, up to the matching @code{object-end}.
9920 @item @code{object-end}
9921 The ending of an object.
9922 @item EOF
9923 After one top-level JSON value is read, the generator returns EOF.
9924 @end table
9925 @c JP
9926 @table @asis
9927 @item 文字列
9928 JSON文字列
9929 @item 実数
9930 JSON数値
9931 @item @code{#t}, @code{#f}
9932 JSONの@code{true}と@code{false}
9933 @item @code{null}
9934 JSONの@code{null}
9935 @item @code{array-start}
9936 配列の開始。次に対応する@code{array-end}が出てくるまで、
9937 配列の要素をストリーミングで返す。
9938 @item @code{array-end}
9939 配列の終了。
9940 @item @code{object-start}
9941 オブジェクトの開始。この後、文字列のキーとJSONの値が交互に返される。
9942 終了は@code{object-end}で示される。
9943 @item @code{object-end}
9944 オブジェクトの終了。
9945 @item EOF
9946 ひとつのトップレベルのJSON値が全て読まれたら、ジェネレータはEOFを返す。
9947 @end table
9948 @c COMMON
9949
9950
9951 The generator internally tracks the state, and raises
9952 @code{<json-parse-error>} when the input contains invalid JSON text.
9953 See also @code{json-error?} above.
9954
9955 If the input contains more than one toplevel JSON value, you have to
9956 call @code{json-generator} after the previous generator is exhausted.
9957
9958 Note that if a toplevel JSON value is a number, @code{true}, @code{false}
9959 or @code{null}, the parser need to read one character ahead to recognize
9960 the value. So the subsequent call of @code{json-generator} won't read
9961 a character immediately following those values.
9962
9963 Generally, multiple toplevel values uses delimiters for each values
9964 so it won't be an issue. See @code{json-lines-read} and
9965 @code{json-sequence-read} below.
9966 @end defun
9967
9968 @defun json-fold proc array-start array-end object-start object-end seed :optional port-or-generator
9969 [SRFI-180]
9970 @c MOD srfi.180
9971 A procedure to translate JSON pasring result to Scheme object on the fly.
9972
9973 The @var{port-or-generator} argument is either an input port,
9974 or a char generator, defaulted to the current input port.
9975 It is first passed to @code{json-generator} to
9976 get a generator of parser events. Then, @code{json-fold} retrieves
9977 value from the generator and take one of the following actions:
9978
9979 @itemize
9980 @item
9981 If it generates a string, a number, a boolean or @code{null},
9982 calls @code{(proc obj seed)} where @var{obj} is the generated value
9983 and @var{seed} is the current seed value, and make the result a new seed value.
9984 @item
9985 If it generates @code{array-start}, save the current seed, calls
9986 @code{(array-start seed)} and make the result a new seed value.
9987 @item
9988 If it generates @code{array-end}, calls @code{(array-end seed)}, let
9989 the result be @var{arr}, recover the seed value saved
9990 at the corresponding @code{array-start}, and calls
9991 @code{(proc arr recovered-seed)}. Let the result a new seed value.
9992 @item
9993 If it generates @code{object-start}, save the current seed, calls
9994 @code{(object-start seed)} and make the result a new seed value.
9995 @item
9996 If it generates @code{object-end}, calls @code{(object-end seed)}, let
9997 the result be @var{obj}, recover the seed value saved
9998 at the corresponding @code{object-start}, and calls
9999 @code{(proc obj recovered-seed)}. Let the result a new seed value.
10000 @item
10001 If it generates EOF, returns the seed value as the result of
10002 @code{json-fold}.
10003 @end itemize
10004 @end defun
10005
10006 @defun json-read :optional port-or-generator
10007 [SRFI-180]
10008 @c MOD srfi.180
10009 Read one JSON value or object from @var{port-or-generator}, which
10010 should be an input port or a char generator. If it is omitted,
10011 the current input port is used.
10012
10013 JSON strings and numbers are mapped to Scheme strings and numbers.
10014 JSON @code{true} and @code{false} become @code{#t} and @code{#f}.
10015 JSON @code{null} becomes a symbol @code{null}.
10016 JSON arrays become Scheme vectors, and JSON objects
10017 become Scheme alist, in which keys are converted to symbols.
10018
10019 If the input contains invalid JSON text, a @code{<json-parse-error>}
10020 is thrown.
10021
10022 See also @code{parse-json} in @code{rfc.json}
10023 (@pxref{JSON parsing and construction}).
10024
10025 @example
10026 (call-with-input-string
10027 "[@{\"a\":1@}, @{\"b\":true, \"c\":\"foo\"@}, null]"
10028 json-read)
10029 @result{} #(((a . 1))
10030 ((b . #t) (c . "foo"))
10031 null)
10032 @end example
10033 @end defun
10034
10035 @defun json-lines-read :optional port-or-generator
10036 [SRFI-180]
10037 @c MOD srfi.180
10038 Returns a generator that yields a JSON values at a time,
10039 read from the source in JSON Lines format
10040 (@url{http://jsonlines.org/}), which contains multiple
10041 toplevel JSON values separated with @code{#\newline}.
10042 The input @var{port-or-generator} should be an input port
10043 or a char generator, defaulted to the current input port.
10044
10045 See @code{json-read} above about the mapping from JSON values to Scheme
10046 values.
10047 @end defun
10048
10049 @defun json-sequence-read :optional port-or-generator
10050 [SRFI-180]
10051 @c MOD srfi.180
10052 Returns a generator that yields a JSON values at a time,
10053 read from the source in JSON Text Sequence format
10054 (RFC7464, @url{https://tools.ietf.org/html/rfc7464}).
10055 The input @var{port-or-generator} should be an input port
10056 or a char generator, defaulted to the current input port.
10057
10058 JSON Text Sequence can contain multiple JSON values,
10059 each one leaded by one or more consecutive U+001E.
10060 If it encounters text unparsable as JSON, that segment (until next U+001E)
10061 is silently ignored. Returns a list of read JSON values.
10062
10063 See @code{json-read} above about the mapping from JSON values to Scheme
10064 values.
10065
10066 See also @code{construct-json} in @code{rfc.json}
10067 (@pxref{JSON parsing and construction}).
10068 @end defun
10069
10070 @subheading JSON writer
10071
10072 @defun json-accumulator port-or-accumlator
10073 [SRFI-180]
10074 @c MOD srfi.180
10075 This is dual to @code{json-generator}. The @code{port-or-accumulator}
10076 should be an output port or an accumulator that accepts a character or
10077 a string. This procedure
10078 returns an accumulator that accepts the events such as
10079 @code{json-generator} generates.
10080 @end defun
10081
10082 @defun json-write obj :optional port-or-accumulator
10083 [SRFI-180]
10084 @c MOD srfi.180
10085 Write @var{obj} as a JSON to @var{port-or-accumulator}, which
10086 must be an output port or an accumulator that accepts a character or
10087 a string.
10088 @end defun
10089
10090 @c ----------------------------------------------------------------------
10091 @node Custom ports, Linear adjustable-length strings, JSON, Library modules - SRFIs
10092 @section @code{srfi.181} - Custom ports
10093 @c NODE カスタムポート, @code{srfi.181} - カスタムポート
10094
10095 @deftp {Module} srfi.181
10096 @mdindex srfi.181
10097 @c EN
10098 This srfi defines a way to implement a port in Scheme.
10099 Gauche has native support of such ports (@pxref{Virtual ports}),
10100 but this srfi is useful for portable code.
10101 @c JP
10102 このsrfiは、ポートをSchemeで実装する方法を定義します。
10103 Gaucheは仮想ポートとしてそういう機能を提供しています(@ref{Virtual ports})が、
10104 ポータブルなコードを書く場合はこのsrfiが便利でしょう。
10105 @c COMMON
10106
10107 @c EN
10108 The interface is upper compatible to R6RS.
10109 @c JP
10110 インタフェースはR6RSの上位互換になっています。
10111 @c COMMON
10112
10113 @c EN
10114 Note that R7RS Scheme distinguishes binary and textual ports,
10115 while Gauche ports can handle both.
10116 @c JP
10117 R7RSではバイナリポートとテキストポートは区別されますが、
10118 Gaucheのポートはバイナリもテキストもどちらも読み書きできます。
10119 @c COMMON
10120 @end deftp
10121
10122 @menu
10123 * Creating custom ports::
10124 * Transcoded ports::
10125 @end menu
10126
10127 @node Creating custom ports, Transcoded ports, Custom ports, Custom ports
10128 @subsection Creating custom ports
10129 @c NODE カスタムポートの作成
10130
10131 @defun make-custom-binary-input-port id read! get-pos set-pos! close
10132 @defunx make-custom-textual-input-port id read! get-pos set-pos! close
10133 [SRFI-181]
10134 @c MOD srfi.181
10135 @c EN
10136 Creates a new binary and textual input port and returns it, respectively.
10137 @c JP
10138 それぞれ、新たなバイナリポートとテキストポートを作って返します。
10139 @c COMMON
10140
10141 @c EN
10142 The @var{id} argument is an arbitrary Scheme procedure. SRFI doesn't
10143 specify how it is used. In Gauche, @var{id} will be returned
10144 with @code{port-name} procedure (@pxref{Common port operations}).
10145 @c JP
10146 @var{id}引数は任意のSchemeオブジェクトです。このsrfiではそれがどう使われるかは
10147 規定されません。Gaucheでは、@var{id}に渡した値は
10148 @code{port-name}手続きで得ることができます(@ref{Common port operations}参照)。
10149 @c COMMON
10150
10151 @c EN
10152 The @var{read!} argument is a procedure to be called
10153 as @code{(read! @var{buffer} @var{start} @var{count})}.
10154 For @code{make-custom-binary-input-port}, @var{buffer} is a
10155 bytevector (u8vector).
10156 For @code{make-custom-textual-input-port}, @var{buffer} is either
10157 a string or a vector of characters (Gauche's implementation always
10158 use a vector, but portable code should handle both).
10159 @c JP
10160 @var{read!}引数は手続きで、
10161 @code{(read! @var{buffer} @var{start} @var{count})}のように呼び出されます。
10162 @code{make-custom-binary-input-port}では、@var{buffer}は
10163 バイトベクタ(u8vector)です。
10164 @code{make-custom-textual-input-port}では、@var{buffer}は文字列か
10165 文字のベクタです(Gaucheでは常に文字のベクタが渡されますが、
10166 ポータブルなコードはどちらにも対応できるように書かれなければなりません)。
10167 @c COMMON
10168
10169 @c EN
10170 It should generate up to @var{count} bytes/characters of data and fill
10171 @var{buffer} beginning from @var{start}, then return the number of
10172 bytes/characters generated.
10173 It should generate at least 1 byte/character if there's still data.
10174 To indicate the end of the data, it writes no data and returns 0.
10175 @c JP
10176 @var{read!}手続きは、最大で@var{count}個のバイトもしくは文字を生成し、
10177 それを@var{buffer}の@var{start}番目から書き込んで、
10178 生成されたバイト/文字数を返します。
10179 @var{read!}手続きは入力データがあるなら、
10180 少なくとも1バイト/文字をバッファに書き込まなければなりません。
10181 入力データがもう無いことを示すには、バッファを変更せず、0を返します。
10182 @c COMMON
10183
10184 @c EN
10185 The @var{get-pos} argument is a procedure to be called without arguments,
10186 and returns an implementation-dependent object that indicates
10187 the current position of the input stream. The `current position' is
10188 where next @var{read!} will generate the data. This can be @code{#f}
10189 if the port doesn't provide positions.
10190 @c JP
10191 @var{get-pos}引数は、引数を取らない手続きで、呼ばれたら入力ストリーム中の現在の位置を
10192 示す処理系依存のオブジェクトを返します。「現在の位置」とは、次に@var{read!}が呼ばれた
10193 時に読み出される位置です。カスタムポートが位置情報を扱う必要がなければ、
10194 この引数は@code{#f}で構いません。
10195 @c COMMON
10196
10197 @c EN
10198 For @code{make-custom-binary-input-port}, there's a special rule that
10199 if @var{get-pos} returns an exact integer, it should be a byte position
10200 in the stream.
10201 @c JP
10202 ただし、@code{make-custom-binary-input-port}については、
10203 @var{get-pos}が正確な整数を返す場合、
10204 それは入力ストリーム中のバイト位置でなければなりません。
10205 @c COMMON
10206
10207 @c EN
10208 The @var{set-pos!} argument is a procedure to be called with one argument,
10209 a new position.
10210 It should set the source's position so that next @var{read!} starts
10211 generating data from there. The passed position is something that has
10212 been returned by @var{get-pos}, or, for @code{make-custom-binary-input-port},
10213 an exact integer that indicates the byte offset from the beginning of
10214 the input. This argument can be @code{#f} if the port doesn't
10215 support setting positions. The returned value of @var{set-pos!} is
10216 ignored.
10217 @c JP
10218 @var{set-pos!}引数はひとつの引数を取る手続きです。
10219 渡された引数は以前の@var{get-pos}が返した値か、
10220 @code{make-custom-binary-input-port}の場合は、
10221 入力先頭からのバイトオフセットです。
10222 この手続きは、次の@var{read!}が指定位置からデータを読み出すように内部状態を更新します。
10223 カスタムポートが位置情報のセットをサポートしなくて良いなら、この引数は@code{#f}で
10224 構いません。
10225 @c COMMON
10226
10227 @c EN
10228 If the position passed to @var{set-pos!} is invalid,
10229 an error that satisfy @code{i/o-invalid-position-error?} should be
10230 thrown. Portably, it can be done by throwing a condition created
10231 by @code{make-i/o-invalid-position-error} (@pxref{Port positioning}).
10232 For Gauche-specific code, you can throw a condition
10233 @code{<io-invalid-position-error>}.
10234 @c JP
10235 @var{set-pos!}に渡された位置情報が不正なものであった場合、それは
10236 @code{i/o-invalid-position-error?}を満たすエラーを投げなければなりません。
10237 ポータブルに書くには、@code{make-i/o-invalid-position-error}で作った
10238 エラーオブジェクトを投げます(@ref{Port positioning}参照)。
10239 Gauche特有のコードで良ければ、
10240 @code{<io-invalid-position-error>}コンディションを投げても良いです。
10241 @c COMMON
10242
10243 @c EN
10244 The @var{close} argument is a procedure to be called without
10245 argument, when the custom port is closed. It can be @code{#f} if you
10246 don't need a special cleanup.
10247 @c JP
10248 @var{close}引数は、カスタムポートがクローズされた時に呼び出される、
10249 引数を取らない手続きです。特にクローズ時のクリーンアップが不要であれば
10250 @code{#f}を渡すこともできます。
10251 @c COMMON
10252 @end defun
10253
10254 @defun make-custom-binary-output-port id write! get-pos set-pos! close :optional flush
10255 @defunx make-custom-textual-output-port id write! get-pos set-pos! close :optional flush
10256 [SRFI-181]
10257 @c MOD srfi.181
10258 @c EN
10259 Creates a new binary and textual out port and returns it, respectively.
10260 @c JP
10261 それぞれ、バイナリ出力ポートおよびテキスト出力ポートを作成して返します。
10262 @c COMMON
10263
10264 @c EN
10265 The @var{id} argument is an arbitrary Scheme object. This SRFI doesn't
10266 specify how it is used. In Gauche, @var{id} will be returned
10267 with @code{port-name} procedure (@pxref{Common port operations}).
10268 @c JP
10269 @var{id}は任意のSchemeオブジェクトです。このSRFIはその用途について特に規定しません。
10270 Gaucheでは、@code{port-name}手続きによって@var{id}を得ることができます
10271 (@ref{Common port operations}参照)。
10272 @c COMMON
10273
10274 @c EN
10275 The @var{write!} argument is a procedure to be called as
10276 @code{(write! @var{buffer} @var{start} @var{count})}.
10277 For @code{make-custom-binary-output-port}, @var{buffer} is a bytevector.
10278 For @code{make-custom-textual-output-port}, @var{buffer} is either
10279 a string or a vector of characters (Gauche's implementation always
10280 use a vector, but portable code should handle both).
10281 @c JP
10282 @var{write!}引数は、@code{(write! @var{buffer} @var{start} @var{count})}のように
10283 呼び出される手続きです。@code{make-custom-binary-output-port}では
10284 @var{buffer}はバイトベクタで、@code{make-custom-textual-output-port}では
10285 @var{buffer}は文字列もしくは文字のベクタです(Gaucheでは常にベクタが渡されますが、
10286 ポータブルなコードではどちらが来ても良いように書いておく必要があります)。
10287 @c COMMON
10288
10289 @c EN
10290 The @var{write!} procedure writes data in @var{buffer}
10291 starting from @var{start}, upto @var{count} items at maximum,
10292 to the external sink. It must return the number
10293 of actual items written.
10294 @c JP
10295 @var{write!}手続きは、@var{buffer}のインデックス@var{start}から最大@var{count}要素
10296 を外部のシンクへと書き出し、実際に書き出された要素数を返します。
10297 @c COMMON
10298
10299 @c EN
10300 The @var{get-pos} argument should be a procedure without taking argument,
10301 or @code{#f}. If it is a procedure, it should return the position
10302 of the sink where the next @var{write!} writes to. The position
10303 can be an arbitrary Scheme object, but for
10304 @code{make-custom-binary-output-port}, a position represented as
10305 an exact integer should correspond to the byte offset in the port.
10306 @c JP
10307 @var{get-pos}引数は、引数を取らない手続きか@code{#f}でなければなりません。
10308 手続きの場合、呼ばれたら、次の@var{write!}が書き込むであろうシンクの位置を返します。
10309 位置は任意のSchemeオブジェクトが許されますが、
10310 @code{make-custom-binary-output-port}の場合、@var{get-pos}が
10311 正確な整数を返すならそれはポートのバイトオフセットでなければなりません。
10312 @c COMMON
10313
10314 @c EN
10315 The @var{set-pos!} argument is a procedure to be called with one argument,
10316 a new position, or @code{#f}.
10317 It should set the sink's position so that next @var{write!} starts
10318 to write data from there. The passed position is something that has
10319 been returned by @var{get-pos}, or, for @code{make-custom-binary-output-port},
10320 an exact integer that indicates the byte offset from the beginning of
10321 the output. This argument can be @code{#f} if the port doesn't
10322 support setting positions. The returned value of @var{set-pos!} is
10323 ignored.
10324 @c JP
10325 @var{set-pos!}引数は引数をひとつ取る手続きか@code{#f}でなければなりません。
10326 手続きの場合、引数はシンクの位置を示すオブジェクトで、次の@var{write!}が
10327 その位置から書き込まれるようにポートと状態をセットします。
10328 位置を示すオブジェクトは、同じポートに対して@var{get-pos}が以前返した位置か、
10329 もしくは@code{make-custom-binary-output-port}の場合、ポートの先頭からの
10330 バイトオフセットを示す正確な整数です。@var{set-pos!}が@code{#f}の場合は、
10331 ポートは位置を変える手段を持ちません。@var{set-pos!}の戻り値は無視されます。
10332 @c COMMON
10333
10334 @c EN
10335 If the position passed to @var{set-pos!} is invalid,
10336 an error that satisfy @code{i/o-invalid-position-error?} should be
10337 thrown. Portably, it can be done by throwing a condition created
10338 by @code{make-i/o-invalid-position-error} (@pxref{Port positioning}).
10339 For Gauche-specific code, you can throw a condition
10340 @code{<io-invalid-position-error>}.
10341 @c JP
10342 @var{set-pos!}に渡された引数が位置を示すオブジェクトとして不適切だった場合は、
10343 述語@code{i/o-invalid-position-error?}を満たすエラーを投げなければなりません。
10344 ポータブルなコードでは、@code{make-i/o-invalid-position-error}を使って
10345 そのようなエラーを作ることができます (@ref{Port positioning}参照)。
10346 Gauche特有のコードなら、@code{<io-invalid-position-error>}コンディションを
10347 投げることもできます。
10348 @c COMMON
10349
10350 @c EN
10351 The @var{close} argument is a procedure to be called without
10352 argument, when the port is closed. It can be @code{#f} if you
10353 don't need a special cleanup.
10354 @c JP
10355 @var{close}引数は引数を取らない手続きで、ポートが閉じられた時に呼ばれます。
10356 ポートが閉じられた時に特にすることが無ければ@code{#f}を渡しても構いません。
10357 @c COMMON
10358
10359 @c EN
10360 The @var{flush} argument, if provided and not @code{#f},
10361 should be a procedure taking no arguments. It is called when
10362 the port is requested to flush the data buffered in the sink, if any.
10363 @c JP
10364 @var{flush}引数は、引数を取らない手続きか@code{#f}です。
10365 ポートが、バッファされたデータが確実にシンクに書き出されたことを保証したい時に
10366 呼ばれます。
10367 @c COMMON
10368 @end defun
10369
10370 @defun make-custom-binary-input/output-port id read! write! get-pos set-pos! close :optional flush
10371 [SRFI-181]
10372 @c MOD srfi.181
10373 @c EN
10374 Creates a bidirectional binary i/o port. Since Gauche doesn't distinguish
10375 binary and textual ports, you can use the returned port for textual i/o as well,
10376 but portable code must avoid it.
10377 @c JP
10378 バイナリ入出力ポートを作って返します。Gaucheはバイナリポートと
10379 テキストポートを区別しないので、作られたポートをテキスト入出力に使うこともできますが、
10380 ポータブルなコードではそれは避けるべきでしょう。
10381 @c COMMON
10382
10383 @c EN
10384 (The reason textual input/output port is not defined in the SRFI is that
10385 it is difficult to define a consistent semantics agnostic to the internal
10386 representation of character stream. In Gauche, we immediately convert
10387 characters to the octet stream of internal character encoding.)
10388 @c JP
10389 (このSRFIではテキスト入出力ポートは定義されません。
10390 というのも、文字ストリームの内部表現とは独立した一貫性のあるセマンティクスを
10391 定義するのが難しいからです。Gaucheでは文字の入出力は
10392 内部エンコーディングに従ったオクテット列の入出力とみなします。)
10393 @c COMMON
10394
10395 @c EN
10396 The arguments, @var{id}, @var{read!}, @var{write!},
10397 @var{get-pos}, @var{set-pos!}, @var{close} and @var{flush} are
10398 the same as @code{make-custom-binary-input-port} and
10399 @code{make-custom-binary-output-port}.
10400 @c JP
10401 引数@var{id}、@var{read!}、@var{write!}、@var{get-pos}、@var{set-pos!}、
10402 @var{close}、@var{flush}の意味は、
10403 @code{make-custom-binary-input-port}および@code{make-custom-binary-output-port}
10404 のそれらと同じです。
10405 @c COMMON
10406 @end defun
10407
10408 @node Transcoded ports, , Creating custom ports, Custom ports
10409 @subsection Transcoded ports
10410 @c NODE 符号変換ポート
10411
10412 @c EN
10413 A transcoded port is a portable way to read/write characters in
10414 an encodings other than the system's default one. This API is
10415 defined first in R6RS, and adopted in SRFI-181.
10416 @c JP
10417 符号変換ポートとは、システムの文字エンコーディング以外の符号化方式でエンコードされた
10418 文字の読み書きをポータブルにする方法です。
10419 このAPIは当初R6RSで定義され、SRFI-181に採用されました。
10420 @c COMMON
10421
10422 @c EN
10423 In SRFI-181 (and R6RS) world, strings and characters are all
10424 an abstract entity without the concept of encodings (internally,
10425 you can think them being encoded in the system's native encoding),
10426 and the explicit encodings only matter when you refer to the outside
10427 resource, e.g. files or a binary data represented in a bytevector.
10428 Therefore, conversions are only defined between binary ports (external world)
10429 and textual ports (internal), or a bytevector (external world) and
10430 a string (internal).
10431 @c JP
10432 SRFI-181(およびR6RS)の世界では、文字列と文字はエンコーディングという概念を持たない
10433 抽象化されたオブジェクトです (内部的には、システムのネイティブエンコーディングで
10434 保持されていると考えて良いでしょう)。
10435 従って、エンコーディングを考える必要があるのは、
10436 外部から与えられる、ファイルやバイトベクタに格納されたバイナリデータを扱いたい時だけです。
10437 従って符号変換は、バイナリポート(外部世界)とテキストポート(内部世界)の間か、
10438 バイトベクタ(外部世界)と文字列(内部世界)の間でのみ定義されます。
10439 @c COMMON
10440
10441 @c EN
10442 Here's some terms:
10443 @c JP
10444 用語の定義:
10445 @c COMMON
10446
10447 @c EN
10448 @table @emph
10449 @item Codec
10450 A codec specifies a character encoding scheme.
10451 @item EOL-style
10452 Specifies (non)converson of EOL character(s).
10453 @item Transcoder
10454 A transcoder bundles a codec, an eol-style, and error handling mode.
10455 @end table
10456 @c JP
10457 @table @emph
10458 @item コーデック
10459 文字エンコーディング方式(CES)を特定するオブジェクトです
10460 @item 行末スタイル
10461 行末文字の扱いを指定する名前
10462 @item トランスコーダ
10463 コーデック、行末スタイル、エラー処理をまとめるオブジェクト
10464 @end table
10465 @c COMMON
10466
10467 @c EN
10468 NB: For Gauche-specific code, you can use @code{gauche.charconv} module
10469 (@pxref{Character code conversion}) that provides more options.
10470 @c JP
10471 註: Gauche特有のコードなら、@code{gauche.charconv}モジュールがさらに柔軟な
10472 機能を提供しています(@ref{Character code conversion}参照)。
10473 @c COMMON
10474
10475 @c EN
10476 @subsubheading Transcoders
10477 @c JP
10478 @subsubheading トランスコーダ
10479 @c COMMON
10480
10481 @defun make-transcoder codec eol-style error-handling
10482 [SRFI-181]
10483 @c MOD srfi.181
10484 @c EN
10485 Creates and returns a transcoder with the given parameters.
10486 A transcoder is an immutable object.
10487 @c JP
10488 与えられたパラメータをまとめたトランスコーダを作って返します。
10489 トランスコーダは変更不可なオブジェクトです。
10490 @c COMMON
10491
10492 @c EN
10493 The @var{codec} argument must be a codec object, either created by
10494 @code{make-codec} or one of the predefined codecs; see below.
10495 @c JP
10496 @var{codec}引数は@code{make-codec}で作られるか、あらかじめ作られている
10497 コーデックオブジェクトです。下で説明します。
10498 @c COMMON
10499
10500 @c EN
10501 The @var{eol-style} argument is one of the following symbols to specify
10502 End-of-likne style:
10503 @c JP
10504 @var{eol-style}引数は行末文字の処理を指定する、次のシンボルのいずれかです。
10505 @c COMMON
10506
10507 @table @code
10508 @item none
10509 @c EN
10510 End-of-line character is passed as-is.
10511 @c JP
10512 行末文字の変換を行いません。
10513 @c COMMON
10514 @item lf
10515 @c EN
10516 Output port converts @code{#\newline} to @code{LF} octet.
10517 Input port converts any line ending to @code{#\newline}.
10518 @c JP
10519 出力ポートは@code{#\nelwine}文字を@code{LF}オクテットに変換します。
10520 入力ポートはどんな行末文字でも@code{#\newline}に変換します。
10521 @c COMMON
10522 @item crlf
10523 @c EN
10524 Output port converts @code{#\newline} to @code{CR-LF} octet sequence.
10525 Input port converts any line ending to @code{#\newline}.
10526 @c JP
10527 出力ポートは@code{#\nelwine}文字を@code{CR-LF}オクテット列に変換します。
10528 入力ポートはどんな行末文字でも@code{#\newline}に変換します。
10529 @c COMMON
10530 @end table
10531
10532 @c EN
10533 The @var{error-handling} argument is a symbol to specify the behavior
10534 when an encoding or decoding error occurs.
10535 It can be one of the following symbols.
10536 @c JP
10537 @var{error-handling}引数は、エンコードもしくはデコードできない文字があったときの
10538 振る舞いを指定する、以下のシンボルのいずれかです。
10539 @c COMMON
10540
10541 @table @code
10542 @item replace
10543 @c EN
10544 Octets that do not consist a valid character encoding are replaced
10545 with @code{#\xFFFD} (or @code{#\?} if the target encoding of an output
10546 transcoding port does not contain @code{#\xFFFD}.)
10547 @c JP
10548 有効な文字エンコーディングにならないオクテットは文字@code{#\xFFFD}に置き換えられます
10549 (出力変換ポートで変換先の文字セットが@code{#\xFFFD}を持っていない場合は@code{#\?}が
10550 使われます)。
10551 @c COMMON
10552 @item raise
10553 @c EN
10554 Raise an error with a condition satisfying @code{i/o-encoding-error?}.
10555 The erroneous octet are consumed and next I/O on the port continues
10556 with the next character.
10557 @c JP
10558 @code{i/o-encoding-error?}を満たすコンディションを伴ってエラーを投げます。
10559 原因になったオクテットは消費され、次のI/Oは次の文字から続行されます。
10560 @c COMMON
10561 @end table
10562 @end defun
10563
10564 @defun native-transcoder
10565 [SRFI-181]
10566 @c MOD srfi.181
10567 @c EN
10568 Returns a singleton of the transcoder representing systems native
10569 (internal) codec and eol-style. In Gauche, the native codec
10570 is the codec uses Gauche's native encoding
10571 (returned by @code{gauche-character-encoding}, @pxref{Characters}),
10572 and eol-style is @code{none}.
10573 @c JP
10574 システム内部で使われているコーデックおよび行末スタイルを表すトランスコーダを返します。
10575 Gaucheでは、内部コーデックは内部文字エンコーディング
10576 (@code{gauche-character-encoding}が返すもの。@ref{Characters}参照)
10577 を使うコーデックで、行末スタイルは@code{none}です。
10578 @c COMMON
10579 @end defun
10580
10581 @defun transcoded-port binary-port transcoder
10582 [SRFI-181]
10583 @c MOD srfi.181
10584 @c EN
10585 Creates a transcoded port wrapping @var{binary-port}, performing the
10586 conversion specified by @var{transcoder}.
10587
10588 If @var{binary-port} is an input port, it returns an input port,
10589 converting the CES specified in @var{transcoder} to the system's
10590 native encoding.
10591
10592 If @var{binary-port} is an output port, it returns an output port,
10593 converting the system's native encoding to the CES specified in
10594 @var{transcoder}.
10595
10596 In Gauche, conversion is done by conversion ports.
10597 @xref{Conversion ports}, for the details.
10598 @c JP
10599 @var{binary-port}をラップし、@var{transcoder}により符号変換を行うポートを返します。
10600
10601 @var{binary-port}が入力ポートなら、返されるのはテキスト入力ポートで、
10602 @var{transcoder}が指定する方式で符号化された外部データを読み込む際に
10603 内部エンコーディングへと変換します。
10604
10605 @var{binary-port}が出力ポートなら、返されるのはテキスト出力ポートで、
10606 内部エンコーディングによる文字や文字列を出力する際に、
10607 @var{transcoder}が指定する方式へと変換します。
10608
10609 Gaucheでは符号変換は変換ポートで行われます。
10610 詳しくは@ref{Conversion ports}を参照してください。
10611 @c COMMON
10612 @end defun
10613
10614 @defun bytevector->string bytevector transcoder
10615 [SRFI-181]
10616 @c MOD srfi.181
10617 @c EN
10618 Decode the binary data in @var{bytevector} as the CES specified
10619 by @var{transcoder}, and returns a string in the native encoding.
10620
10621 It is a wrapper of Gauche's @code{ces-convert}; @pxref{Conversion ports}.
10622 @c JP
10623 @var{bytevector}に格納されたバイナリデータを、
10624 @var{transcoder}で指定される符号化方式によるものとみなして、
10625 それを内部エンコーディングによる文字列に変換したものを返します。
10626
10627 Gaucheの@code{ces-convert}のラッパーです (@ref{Conversion ports}参照)。
10628 @c COMMON
10629 @end defun
10630
10631 @defun string->bytevector string transcoder
10632 [SRFI-181]
10633 @c MOD srfi.181
10634 @c EN
10635 Encode the string in the CES specified by @var{transcoder},
10636 and returns a bytevector.
10637
10638 It is a wrapper of Gauche's @code{ces-convert-to}; @pxref{Conversion ports}.
10639 @c JP
10640 文字列を、@var{transcoder}が指定する符号化方式に変換したものをバイトベクタとして返します。
10641
10642 Gaucheの@code{ces-convert-to}のラッパーです (@ref{Conversion ports}参照)。
10643 @c COMMON
10644 @end defun
10645
10646 @c EN
10647 @subsubheading Codecs
10648 @c JP
10649 @subsubheading コーデック
10650 @c COMMON
10651
10652 @defun make-codec name
10653 [SRFI-181]
10654 @c MOD srfi.181
10655 @c EN
10656 Returns a codec representing a character encoding scheme named by
10657 @var{name}. A portable code should only use string for @var{name},
10658 while Gauche accepts a symbol as well.
10659
10660 If @var{name} isn't recognized as a supported codec name,
10661 a condition that satisfies @code{unknown-encoding-error?} is thrown.
10662 @c JP
10663 @var{name}で指定される文字符号化方式を表すコーデックを返します。
10664 ポータブルなコードでは@var{name}に文字列を渡してください。Gaucheではシンボルも
10665 受け付けます。
10666
10667 @var{name}がサポートされているコーデックの名前でなければ、
10668 述語@code{unknown-encoding-error?}を満たすコンディションを伴ってエラーが投げられます。
10669 @c COMMON
10670 @end defun
10671
10672 @defun unknown-encoding-error? obj
10673 [SRFI-181]
10674 @c MOD srfi.181
10675 @c EN
10676 If the system sees unknown or unsupported codec, a condition
10677 that satisfies this predicate is thrown.
10678 @c JP
10679 システムが認識しないあるいはサポートしないコーデックを使うように指示された場合、
10680 この述語を満たすコンディションが投げられます。
10681 @c COMMON
10682 @end defun
10683
10684 @defun unknown-encoding-error-name obj
10685 [SRFI-181]
10686 @c MOD srfi.181
10687 @c EN
10688 The argument must be an unknown encoding error condition
10689 that satisfies @code{unknown-encoding-error?}. It returns
10690 the name that caused the condition to be thrown.
10691 @c JP
10692 引数は述語@code{unknown-encoding-error?}を満たすコンディションでなければなりません。
10693 このコンディションの原因となったコーデック名を返します。
10694 @c COMMON
10695 @end defun
10696
10697 @defun latin-1-codec
10698 @defunx utf-8-codec
10699 @defunx utf-16-codec
10700 [SRFI-181]
10701 @c MOD srfi.181
10702 @c EN
10703 A pre-defined codecs for @code{latin-1} (ISO8859-1),
10704 @code{utf-8}, and @code{utf-16}.
10705 @c JP
10706 あらかじめ作られている、
10707 @code{latin-1} (ISO8859-1)、@code{utf-8}、および@code{utf-16}コーデックを返します。
10708 @c COMMON
10709
10710 @c EN
10711 The @code{utf-16} codec recognizes
10712 BOM when used for input; if no BOM is found, UTF-16BE is assumed.
10713 When used for output, @code{utf-16} always attaches BOM.
10714 @c JP
10715 @code{utf-16}コーデックは入力にBOMがあればそのバイトオーダーを使い、
10716 無ければUTF-16BEを使います。
10717 出力に使われた場合は常にBOMを出力します。
10718 @c COMMON
10719 @end defun
10720
10721 @c EN
10722 @subsubheading EOL style
10723 @c JP
10724 @subsubheading 行末スタイル
10725 @c COMMON
10726
10727 @defun native-eol-style
10728 [SRFI-181]
10729 @c MOD srfi.181
10730 @c EN
10731 Returns the default eol style. In Gauche, it is @code{none}.
10732 @c JP
10733 デフォルトの行末スタイルを返します。Gaucheでは@code{none}です。
10734 @c COMMON
10735 @end defun
10736
10737 @c EN
10738 @subsubheading Transcoding errors
10739 @c JP
10740 @subsubheading 変換エラー
10741 @c COMMON
10742
10743 @defun i/o-decoding-error? obj
10744 [SRFI-181]
10745 @c MOD srfi.181
10746 @c EN
10747 When an input transcoded port encounters a sequence that's not valid
10748 for the input codec, a condition that satisfies this predicate
10749 is thrown.
10750
10751 In Gauche, such condition is @code{<io-decoding-error>}.
10752 @c JP
10753 入力変換ポートがコーデックとして不正なバイトシーケンスに出会った場合、
10754 この述語を満たすコンディションが投げられます。
10755
10756 Gaucheではそのコンディションは@code{<io-decoding-error>}のインスタンスです。
10757 @c COMMON
10758 @end defun
10759
10760 @defun i/o-encoding-error? obj
10761 [SRFI-181]
10762 @c MOD srfi.181
10763 @c EN
10764 When an output transcoded port encounters a character that can't be
10765 encoded in the output codec, and the handling mode is @code{raise},
10766 a condition that satisfies this predicate is thrown.
10767
10768 In Gauche, such condition is @code{<io-encoding-error>}.
10769 @c JP
10770 出力変換ポートが出力しようとした文字がコーデックで表わせず、
10771 エラーハンドリングモードが@code{raise}である場合、
10772 この述語を満たすコンディションが投げられます。
10773
10774 Gaucheではそのコンディションは@code{<io-encoding-error>}のインスタンスです。
10775 @c COMMON
10776 @end defun
10777
10778 @defun i/o-encoding-error-char i/o-encoding-condition
10779 [SRFI-181]
10780 @c MOD srfi.181
10781 @c EN
10782 Retries the character that caused the @code{<io-encoding-error>} is thrown.
10783 @c JP
10784 @code{<io-encoding-error>}コンディションの原因となった文字を返します。
10785 @c COMMON
10786 @end defun
10787
10788
10789 @c ----------------------------------------------------------------------
10790 @node Linear adjustable-length strings, Maybe and Either optional container types, Custom ports, Library modules - SRFIs
10791 @section @code{srfi.185} - Linear adjustable-length strings
10792 @c NODE 線形更新な可変長文字列, @code{srfi.185} - 線形更新な可変長文字列
10793
10794 @deftp {Module} srfi.185
10795 @mdindex srfi.185
10796 @c EN
10797 This module provides a linear-update version of @code{string-append}
10798 and @code{string-replace}. ``Linear update'' means the caller
10799 won't access the first string argument, hence the implementation
10800 @emph{can} reuse it to store the result, for the efficiency.
10801 @c JP
10802 このモジュールは@code{string-append}と@code{string-replace}の線形更新版を提供します。
10803 「線形更新」とは、この関数を呼び出した後は引数が使われないことが前提になっているという
10804 意味で、従って処理系は結果を格納するために引数を破壊的に再利用することが許されています。
10805 @c COMMON
10806
10807 @c EN
10808 Note that, in Gauche, a string is just a pointer to an immutable
10809 string body. Mutation of a string is actually constructing a new
10810 string body and swapping the pointer, so it has no performance
10811 advantage to immutable versions. And in fact, we implement
10812 these without mutating their arguments.
10813 @c JP
10814 しかしGaucheでは、文字列は変更不可な文字列本体へのポインタであって、
10815 文字列の変更は新たな文字列本体を作ってポインタを差し替える操作にすぎず、
10816 文字列を破壊的に再利用するメリットは全くありません。
10817 従ってこのsrfiのAPIは単に非破壊版を呼び出すだけになっています。
10818 @c COMMON
10819
10820 @c EN
10821 This module also provides macros with the same name as @code{srfi.118}
10822 procedures (@pxref{Simple adjustable-size strings}), which @code{set!}
10823 the result to its first argument, so they can work as a drop-in
10824 replacement to @code{srfi.118}.
10825 @c JP
10826 このモジュールはまた、@code{srfi.118}の手続き(@ref{Simple adjustable-size strings}参照)
10827 と同名のマクロを提供しています。マクロは結果を引数に渡された式に
10828 @code{set!}する式に展開されるので、一見@code{srfi.118}と同じように使うことができます。
10829 @c COMMON
10830 @end deftp
10831
10832 @defun string-append-linear! dst str-or-char @dots{}
10833 [SRFI-185]
10834 @c MOD srfi.185
10835 @c EN
10836 Returns a string which is a concatenation of a string @var{dst}
10837 and the arguments. The second argument an after can be
10838 a string or a character. The caller shouldn't access @var{dst}
10839 after calling this procedure, for the implementation may destructively
10840 reuse the string passed to @var{dst}. Although Gauche won't
10841 mutate @var{dst}, other implementations may, so portable code
10842 should adhere this restriction.
10843 @c JP
10844 文字列@var{dst}と他の引数を全部つなげた文字列を返します。
10845 2番目以降の引数は文字でも文字列でも構いません。呼び出し元は、この関数を読んだ後は
10846 @var{dst}が指す文字列にアクセスしてはいけません。実装は@var{dst}が指す文字列を
10847 破壊的に再利用して結果を格納することが許されています。Gaucheは@var{dst}を
10848 破壊しませんが、ポータブルなコードでは@var{dst}を使わないようにしてください。
10849 @c COMMON
10850
10851 @c EN
10852 You can't count on @var{dst} being mutated; you always have to use the returned
10853 string.
10854 @c JP
10855 @var{dst}が破壊することをあてにしてはいけません。
10856 常に戻り値の文字列を使うようにしてください。
10857 @c COMMON
10858
10859 @example
10860 (string-append-linear! "abc" "def" #\g "hij")
10861 @result{} "abcdefghij"
10862 @end example
10863 @end defun
10864
10865 @defun stirng-replace-linear! dst dst-start dst-end src :optional src-start src-end
10866 [SRFI-185]
10867 @c MOD srfi.185
10868 @c EN
10869 Returns copy of a string @var{dst} except
10870 the portion of from @var{dst-start} (inclusive)
10871 to @var{dst-end} (exclusive), by a string @var{src} (from @var{src-start}
10872 to @var{src-end}).
10873 The caller shouldn't access @var{dst}
10874 after calling this procedure, for the implementation may destructively
10875 reuse the string passed to @var{dst}. Although Gauche won't
10876 mutate @var{dst}, other implementations may, so portable code
10877 should adhere this restriction.
10878 @c JP
10879 文字列@var{dst}のうち、@var{dst-start}(含まれる)から@var{dst-end}(含まれない)
10880 までの範囲を、文字列@var{src}(の@var{src-start}と@var{src-end}の範囲)で置き換えた
10881 文字列を返します。
10882 呼び出し元は、この関数を読んだ後は
10883 @var{dst}が指す文字列にアクセスしてはいけません。実装は@var{dst}が指す文字列を
10884 破壊的に再利用して結果を格納することが許されています。Gaucheは@var{dst}を
10885 破壊しませんが、ポータブルなコードでは@var{dst}を使わないようにしてください。
10886 @c COMMON
10887
10888 @c EN
10889 Gauche allows string cursors, as well as integer character index,
10890 in @var{dst-start}, @var{dst-end}, @code{src-start} and @var{src-end} arguments.
10891 (@xref{String cursors}).
10892 @c JP
10893 Gaucheでは、@var{dst-start}、@var{dst-end}、@code{src-start}、@var{src-end}
10894 引数に、整数の文字インデックスだけでなく文字列カーソルも使えます。
10895 (@ref{String cursors}参照)。
10896 @c COMMON
10897 @end defun
10898
10899 @defmac string-append! dst string-or-char @dots{}
10900 @defmacx string-replace! dst dst-start dst-end src :optional src-start src-end
10901 [SRFI-185]
10902 @c MOD srfi.185
10903 @c EN
10904 These macros expand into the following forms:
10905 @c JP
10906 これらのマクロは次の形に展開されます。
10907 @c COMMON
10908
10909 @example
10910 (set! dst (string-append-linear! dst string-or-char @dots{}))
10911
10912 (set! dst (string-replace-linear! dst dst-start dst-end src src-start src-end))
10913 @end example
10914
10915 @c EN
10916 Hence they can be used for the code that expects @var{dst} to contain
10917 the result after calling these macros.
10918 Gauche supports generalized @code{set!}, so @var{dst} can be
10919 a procedure call with a setter defined.
10920 @c JP
10921 つまり、呼び出した後に@var{dst}に変更された文字列が格納されることを想定している
10922 箇所に使えます。Gaucheは一般化された@code{set!}を持っているので、
10923 @var{dst}にはセッターが定義されている手続き呼び出しも使えます。
10924 @c COMMON
10925
10926 @example
10927 (define x (list (string-copy "abc")))
10928
10929 (string-append! (car x) #\d #\e #\f)
10930
10931 x @result{} ("abcdef")
10932 @end example
10933
10934 @c EN
10935 The code that uses SRFI-118 (@pxref{Simple adjustable-size strings}) is
10936 likely to be replaced using these macros.
10937 @c JP
10938 SRFI-118 (@ref{Simple adjustable-size strings}参照)を使っているコードは、
10939 このマクロで置き換えられることも多いでしょう。
10940 @c COMMON
10941 @end defmac
10942
10943 @c ----------------------------------------------------------------------
10944 @node Maybe and Either optional container types, Coroutine generators, Linear adjustable-length strings, Library modules - SRFIs
10945 @section @code{srfi.189} - Maybe and Either: optional container types
10946 @c NODE MaybeとEither、オプショナルなコンテナ型, @code{srfi.189} - MaybeとEither、オプショナルなコンテナ型
10947
10948 @deftp {Module} srfi.189
10949 @mdindex srfi.189
10950 Maybe and Either types are immutable container types
10951 that can ``wrap'' zero or more values. Maybe can be used
10952 in the context where the value(s) may be missing (as opposed to
10953 ``zero values''). Either can be used in the context where
10954 the value(s) can be correct ones or erroneous ones.
10955
10956 If you're familiar with functional languages like Haskell, you may
10957 already know them. They are useful when used in the monadic pattern; that is,
10958 you can code as if the chain of calculations never fails,
10959 yet whenever the calculation fail at one place,
10960 the rest of chain is canceled and just the failure is returned.
10961
10962 Maybe is a union of two types, Just and Nothing. Just wraps
10963 valid value(s), while Nothing indicates there's no meaningful values.
10964 Either is a union of two types, Right and Left. Right wraps
10965 valid value(s), while Left indicates an error, carrying some information
10966 as its payload.
10967 @end deftp
10968
10969 @menu
10970 * Maybe and Either types and predicates::
10971 * Maybe and Either constructors::
10972 * Maybe and Either accessors::
10973 * Maybe and Either sequence operations::
10974 * Maybe and Either protocol converters::
10975 * Maybe and Either syntactic utilities::
10976 * Trivalent logic::
10977 @end menu
10978
10979 @node Maybe and Either types and predicates, Maybe and Either constructors, Maybe and Either optional container types, Maybe and Either optional container types
10980 @subsection Types and predicates
10981
10982 @deftp {Class} <maybe>
10983 @deftpx {Class} <just>
10984 @deftpx {Class} <nothing>
10985 @c MOD srfi.189
10986 Maybe classes. @code{<just>} and @code{<nothing>} are subclasses of
10987 @code{<maybe>}. An instance of @code{<just>} carries zero or more
10988 values (payload), while an instance of @code{<nothing>} doesn't carry
10989 information.
10990
10991 The @code{<maybe>} class is an abstract class and can't
10992 create an instance of its own.
10993 Instances of @code{<just>} and @code{<nothing>} should be created with
10994 constructor procedures @code{just} and @code{nothing}.
10995 @end deftp
10996
10997 @deftp {Class} <either>
10998 @deftpx {Class} <right>
10999 @deftpx {Class} <left>
11000 @c MOD srfi.189
11001 Either classes. @code{<right>} and @code{<left>} are subclasses of
11002 @code{<either>}. An instance of either class carry zero or more
11003 values (payload); it is customary to use @code{<right>} to propagate
11004 the legitimate results of compuation, while use @code{<left>} to
11005 propagate erroneous conditions whose payload describes what's wrong.
11006
11007 The @code{<either>} class is an abstract class and can't
11008 create an instance of its own.
11009 Instances of @code{<right>} and @code{<left>} should be created with
11010 constructor procedures @code{right} and @code{left}.
11011 @end deftp
11012
11013 @defun maybe? obj
11014 @defunx just? obj
11015 @defunx nothing? obj
11016 [SRFI-189]
11017 @c MOD srfi.189
11018 Type predicates.
11019 Returns @code{#t} iff @var{obj} is a Maybe, a Just, or a Nothing,
11020 respectively.
11021 @end defun
11022
11023 @defun either? obj
11024 @defunx right? obj
11025 @defunx left? obj
11026 [SRFI-189]
11027 @c MOD srfi.189
11028 Type predicates.
11029 Returns @code{#t} iff @var{obj} is a Either, a Right, or a Left,
11030 respectively.
11031 @end defun
11032
11033 @defun maybe= elt= maybe1 maybe @dots{}
11034 [SRFI-189]
11035 @c MOD srfi.189
11036 Equality predicate of Maybes. It returns @code{#t} iff
11037 all of @var{maybe1} @var{maybe} @dots{} are Nothings,
11038 or Justs with their respective payload objects are the same
11039 using @var{elt=}.
11040 @end defun
11041
11042 @defun either= elt= either1 either @dots{}
11043 [SRFI-189]
11044 @c MOD srfi.189
11045 Equality predicate of Eithers. It returns @code{#t} iff
11046 all of @var{either11} @var{either} @dots{} are the same
11047 types (all Rights, or all Lefts), with
11048 respective payload objects are the same
11049 using @var{elt=}.
11050 @end defun
11051
11052 @node Maybe and Either constructors, Maybe and Either accessors, Maybe and Either types and predicates, Maybe and Either optional container types
11053 @subsection Constructors
11054
11055 @defun just obj @dots{}
11056 [SRFI-189]
11057 @c MOD srfi.189
11058 Returns a Just with @var{obj} @dots{} as its payload.
11059 @end defun
11060
11061 @defun nothing
11062 [SRFI-189]
11063 @c MOD srfi.189
11064 Returns a Nothing.
11065 @end defun
11066
11067 @defun right obj @dots{}
11068 @defunx left obj @dots{}
11069 [SRFI-189]
11070 @c MOD srfi.189
11071 Returns a Right or a Left respectively, with @var{obj} @dots{}
11072 as its payload.
11073 @end defun
11074
11075 @defun list->just objs
11076 @defunx list->right objs
11077 @defunx list->left objs
11078 [SRFI-189]
11079 @c MOD srfi.189
11080 Returns a Just, Right or Left respectively, with
11081 @var{objs} as its payload.
11082 @end defun
11083
11084 @defun maybe->either maybe obj @dots{}
11085 [SRFI-189]
11086 @c MOD srfi.189
11087 The @var{maybe} argument must be a Maybe.
11088 If it is a Just, then a Right with the same payload is returned.
11089 If it is a Nothing, a Left with @var{obj} @dots{} as its payload.
11090 @end defun
11091
11092 @defun either->maybe either
11093 [SRFI-189]
11094 @c MOD srfi.189
11095 The @var{either} argument must be an Either.
11096 If it is a Right, then a Just with the same payload is returned.
11097 If it is a Left, a Nothing is returned.
11098 @end defun
11099
11100 @defun either-swap either
11101 [SRFI-189]
11102 @c MOD srfi.189
11103 The @var{either} argument must be an Either.
11104 If it is a Right, a Left with the same payload argument is returned.
11105 If it is a Left, a Right with the same payload argument is returned.
11106 @end defun
11107
11108 @node Maybe and Either accessors, Maybe and Either sequence operations, Maybe and Either constructors, Maybe and Either optional container types
11109 @subsection Accessors
11110
11111 @defun maybe-ref maybe failure :optional success
11112 [SRFI-189]
11113 @c MOD srfi.189
11114 The @var{maybe} arugment must be a Maybe. If it's a Nothing,
11115 a procedure @var{failure} is tail-called with no arguments.
11116 If it's Just, a procedure @var{success} is tail-called with its
11117 payload object(s). If @var{success} is omitted, @code{values} is used.
11118
11119 @example
11120 (maybe-ref (just 1 2) (^[] (error 'huh?)) +)
11121 @result{} 3
11122 @end example
11123 @end defun
11124
11125 @defun either-ref either failure :optional success
11126 [SRFI-189]
11127 @c MOD srfi.189
11128 The @var{either} argument must be an Either.
11129 If it's a Left, a procedure @var{failure} is called with
11130 its payload object(s). If it's a Right, a procedure
11131 @var{success} is called with its payload object(s).
11132 If @var{success} is omitted, @code{values} is used.
11133 @end defun
11134
11135 @defun maybe-ref/default maybe default @dots{}
11136 [SRFI-189]
11137 @c MOD srfi.189
11138 The @var{maybe} argument must be a Maybe. If it's a Nothing,
11139 @var{default} @dots{} are returned as multiple values.
11140 If it's a Just, its payload object(s) is/are returned as multiple values.
11141 @end defun
11142
11143 @defun either-ref/default maybe default @dots{}
11144 [SRFI-189]
11145 @c MOD srfi.189
11146 The @var{either} argument must be an Either. If it's a Left,
11147 @var{default} @dots{} are returned as multiple values (the Left's payload
11148 is discarded).
11149 If it's a Right, its payload object(s) is/are returned as multiple values.
11150 @end defun
11151
11152 @defun maybe-join maybe
11153 [SRFI-189]
11154 @c MOD srfi.189
11155 If @var{maybe} is a Nothing,
11156 it is returned. If it's a Maybe and its only payload is a Maybe,
11157 the inner Maybe is returned. Other cases raise an error.
11158 @end defun
11159
11160 @defun either-join either
11161 [SRFI-189]
11162 @c MOD srfi.189
11163 If @var{either} is a Left, it is returned.
11164 If it is a Right and its only payload is an Either,
11165 the inner Either is returned. Other cases raise an error.
11166 @end defun
11167
11168 @defun maybe-bind maybe mproc mproc2 @dots{}
11169 [SRFI-189]
11170 @c MOD srfi.189
11171 Monadic @var{bind} operation. The @var{maybe} argument must be a Maybe.
11172 If it is a Nothing, it is returned.
11173 If it is a Just, its payload object(s) is/are applied to a procedure
11174 @var{mproc}, which must return a Maybe. If @var{mproc2} @dots{} are
11175 given, the same operation is repeated on them.
11176
11177 @example
11178 (maybe-bind m p p2)
11179 @equiv{} (maybe-bind (maybe-bind m p) p2)
11180 @end example
11181 @end defun
11182
11183 @defun either-bind either mproc mproc2 @dots{}
11184 [SRFI-189]
11185 @c MOD srfi.189
11186 Monadic @var{bind} operation. The @var{either} argument must be an Either.
11187 If it is a Left, it is returned as is.
11188 If it is a Right, its payload object(s) is/are applied to a procedure
11189 @var{mproc}, which must return an Either. If @var{mproc2} @dots{} are
11190 given, the same operation is repeated on them.
11191
11192 @example
11193 (either-bind e p p2)
11194 @equiv{} (either-bind (either-bind e p) p2)
11195 @end example
11196 @end defun
11197
11198 @defun maybe-compose mproc mproc2 @dots{}
11199 @defunx either-compose mproc mproc2 @dots{}
11200 [SRFI-189]
11201 @c MOD srfi.189
11202 Each argument must be a procedure taking zero or more arguments
11203 and return a Maybe/an Either. Returns a procedure that accepts zero or more
11204 arguments and returns a Maybe/an Either.
11205
11206 When the returned procedure is called, it first calls @var{mproc};
11207 if it returns a Nothing/Left, or there's no more mprocs, the result is
11208 returned. If the result is a Just, its payload is applied
11209 to the next mproc, and so on.
11210
11211 @example
11212 (maybe-bind m p p2 ...)
11213 @result{} (maybe-ref m (^[] (nothing))
11214 (maybe-compose p p2 ...))
11215 @end example
11216 @end defun
11217
11218
11219 @node Maybe and Either sequence operations, Maybe and Either protocol converters, Maybe and Either accessors, Maybe and Either optional container types
11220 @subsection Sequence operations
11221
11222 A Maybe and an Either can be a container of zero or one element, and
11223 we have several procedures that employ this view.
11224 (Note: For this purpose, we treat multiple payload values as a whole,
11225 since they are processed in one step---as if we don't regard
11226 multiple procedure arguments and multiple return values as a sequence
11227 of individual values.)
11228
11229 @defun maybe-length maybe
11230 @defunx either-length either
11231 [SRFI-189]
11232 @c MOD srfi.189
11233 Returns 0 if @var{maybe}/@var{either} is a Nothing/Left, and
11234 1 if it is a Just/Right. An error is thrown if the argument
11235 isn't a Maybe/an Either.
11236 @end defun
11237
11238 @defun maybe-filter pred maybe
11239 @defunx either-filter pred either obj @dots{}
11240 [SRFI-189]
11241 @c MOD srfi.189
11242 If @var{maybe}/@var{either} is a Nothing/Left,
11243 returns a Nothing/a Left of @var{obj} @dots{}.
11244 If @var{maybe}/@var{either} is a Just/a Right, apply @var{pred} on
11245 its payload value(s). If @var{pred} returns a true value,
11246 @var{maybe}/@var{either} is returned; otherwise,
11247 a Nothing/a Left of @var{obj} @dots{} is returned.
11248
11249 An error is thrown if @var{maybe}/@var{either} isn't a Maybe/an Either.
11250 @end defun
11251
11252 @defun maybe-remove pred maybe
11253 @defunx either-remove pred either obj @dots{}
11254 [SRFI-189]
11255 @c MOD srfi.189
11256 Like @code{maybe-filter}/@code{either-filter}, but the meaning of
11257 @var{pred} is reversed.
11258 @end defun
11259
11260 @defun maybe-sequence mappable cmap :optional aggregator
11261 @defunx either-sequence mappable cmap :optional aggregator
11262 [SRFI-189]
11263 @c MOD srfi.189
11264 This converts a collection of Maybes/Eithers to a Mayber/an Either of
11265 a collection. The input collection and the collection in the output can
11266 be of different type.
11267
11268 It's easier to explain using Haskell-ish type signatures, although
11269 it's not precisely specified. Suppose @code{Container x} is
11270 some kind of a collection of
11271 type @var{x}, and @code{a*} is multiple values of arbitrary types.
11272
11273 @example
11274 Mappable = Container Maybe a*
11275 CMap = ((Maybe a* -> b) -> Container Maybe a* -> Container' b
11276 Aggregator = a* -> b
11277
11278 maybe-sequence :: Mappable -> CMap -> Aggregator -> Container' b
11279 @end example
11280
11281 The @var{cmap} maps @var{proc} over the input container (@var{mappable}),
11282 and gathers the result into another container. It can be any containers,
11283 as long as it matches the @var{mappable} argument. For example, @var{mappable}
11284 may be a vector of Maybes, and @var{cmap} can be @code{vector-map}--in that case,
11285 both @code{Container} and @code{Container'} are @code{Vector}.
11286 Or, @var{mappable} may be a list of Maybes, and @var{cmap} can be
11287 @code{(cut map-to <string> <> <>)}, then @code{Container} is a list and
11288 @code{Container'} is a string.
11289
11290 The types @code{a*} and @code{b} is determined by the @var{aggregator}
11291 procedure, whose default value is @code{list}.
11292 @end defun
11293
11294 @defun maybe-map proc maybe
11295 @defunx either-map proc either
11296 [SRFI-189]
11297 @c MOD srfi.189
11298 If @var{maybe}/@var{either} is a Nothing/Left, it is returned as is.
11299 If it is a Just/Right, its payload value(s) is/are passed to @var{proc},
11300 and the result is returned.
11301 @end defun
11302
11303 @defun maybe-for-each proc maybe
11304 @defunx either-for-each proc either
11305 [SRFI-189]
11306 @c MOD srfi.189
11307 If @var{maybe}/@var{either} is a Nothing/Left, these procedures do nothing.
11308 Otherwise, @var{proc} is applied to the argument's payload values.
11309 The result of @var{proc} is discarded. Returns an unspecified vlaue.
11310 @end defun
11311
11312 @defun maybe-fold kons knil maybe
11313 @defunx either-fold kons knil either
11314 [SRFI-189]
11315 @c MOD srfi.189
11316 If @var{maybe}/@var{either} is a Nothing/Left, @var{knil} is returned.
11317 Otherwise, @var{kons} is called with the argument's payload values, plus
11318 @var{knil}. What @var{kons} returns becomes the result.
11319 @end defun
11320
11321 @defun maybe-unfold p f g seed @dots{}
11322 @defunx either-unfold p f g seed @dots{}
11323 [SRFI-189]
11324 @c MOD srfi.189
11325 First, the stop predicate @var{p} is applied to @var{seed} @dots{}.
11326 If it returns a true value, a Nothing / a Left of @var{seed} @dots{} is
11327 returned. Otherwise, @var{g} is applied to @var{seed} @dots{},
11328 which should return the same number of values as seeds, and passed
11329 to @var{p}. If @var{p} returns false, it is an error.
11330 If @var{p} returns true, @var{mapper} is applied to @var{seed} @dots{},
11331 then the results are wrapped in a Just/Right to be returned.
11332 @end defun
11333
11334
11335 @node Maybe and Either protocol converters, Maybe and Either syntactic utilities, Maybe and Either sequence operations, Maybe and Either optional container types
11336 @subsection Protocol converters
11337
11338 @defun maybe->list maybe
11339 [SRFI-189]
11340 @c MOD srfi.189
11341 If @var{maybe} is a Just, returns a list of its payload values.
11342 If it is a Nothing, an empty list is retured.
11343 @end defun
11344
11345 @defun list->maybe lis
11346 [SRFI-189]
11347 @c MOD srfi.189
11348 If @var{lis} is an empty list, a Nothing is returned.
11349 Otherwise, a Just that has elements in @var{lis} as payload values
11350 is returned.
11351
11352 Note that @code{(list->maybe (maybe->list x))} isn't an identity
11353 mapping---if @var{x} is a Just with zero payload values, you'll get
11354 a Nothing.
11355 @end defun
11356
11357 @defun either->list either
11358 [SRFI-189]
11359 @c MOD srfi.189
11360 If @var{either} is a Right, returns a list of its payload values.
11361 If it is a Left, returns an empty string.
11362 @end defun
11363
11364 @defun list->either lis obj @dots{}
11365 [SRFI-189]
11366 @c MOD srfi.189
11367 If @var{lis} is an empty list, a Left of @var{obj} @dots{} is returned.
11368 Otherwise, a Right that has elements in @var{lis} as payload values
11369 is returned.
11370 @end defun
11371
11372 @defun maybe->truth maybe
11373 [SRFI-189]
11374 @c MOD srfi.189
11375 If @var{maybe} is a Nothing, @code{#f} is returned.
11376 Otherwise, it must be a Just with one value, and its value is returned.
11377
11378 If @var{maybe} is a Just and it doesn't have exactly one value, an error
11379 is thrown. If you want to deal with arbitrary number of payload values,
11380 use @code{maybe->list-truth}.
11381 @end defun
11382
11383 @defun truth->maybe obj
11384 [SRFI-189]
11385 @c MOD srfi.189
11386 If @var{obj} is @code{#f}, returns a Nothing.
11387 Otherwise, returns a Just with @var{obj} as its payload.
11388
11389 Note that @code{(truth->maybe (maybe->truth x))} isn't an identity mapping---
11390 if @var{x} is a Just wrapping @code{#f}, you'll get a Nothing.
11391 @end defun
11392
11393 @defun either->truth either
11394 [SRFI-189]
11395 @c MOD srfi.189
11396 If @var{either} is a Left, @code{#f} is returned.
11397 Otherwise, it must be a Right with one value, and its value is returned.
11398
11399 If @var{either} is a Right and it doesn't have exactly one value, an error
11400 is thrown. If you want to deal with arbitrary number of payload values,
11401 use @code{either->list-truth}.
11402 @end defun
11403
11404 @defun truth->either obj fail-obj @dots{}
11405 [SRFI-189]
11406 @c MOD srfi.189
11407 If @var{obj} is @code{#f}, returns a Left with @var{fail-obj} @dots{} is
11408 returned.
11409 Otherwise, returns a Right with @var{obj} as its payload.
11410 @end defun
11411
11412 @defun maybe->list-truth maybe
11413 [SRFI-189]
11414 @c MOD srfi.189
11415 Like @code{maybe->list}, it returns @code{#f} if @var{maybe} is a Nothing.
11416 If @var{maybe} is a Just, however, it returns a list of its payload values.
11417 @end defun
11418
11419 @defun list-truth->maybe lis-or-false
11420 [SRFI-189]
11421 @c MOD srfi.189
11422 The argument must be @code{#f} of a list. If it is @code{#f}, a Nothing
11423 is returned. If it is a list, a Just with elements of the list is
11424 returned.
11425
11426 @code{(list-truth->maybe (maybe->list-truth x))} is an identity mapping.
11427 @end defun
11428
11429 @defun either->list-truth either
11430 [SRFI-189]
11431 @c MOD srfi.189
11432 Like @code{either->list}, it returns @code{#f} if @var{either} is a Left.
11433 If @var{either} is a Right, however, it returns a list of its payload values.
11434 @end defun
11435
11436 @defun list-truth->either lis-or-false fail-objs @dots{}
11437 [SRFI-189]
11438 @c MOD srfi.189
11439 The @var{list-or-false} argument must be @code{#f} of a list.
11440 If it is @code{#f}, a Left with @var{fail-objs} @dots{}
11441 is returned. If it is a list, a Right with elements of the list is
11442 returned.
11443 @end defun
11444
11445 @defun maybe->generation maybe
11446 [SRFI-189]
11447 @c MOD srfi.189
11448 If @var{maybe} is a Nothing, an EOF object is returned.
11449 Otherwise, it must be a Just with one value, and its value is returned.
11450 If @var{maybe} is a Just and it doesn't have exactly one value, an error
11451 is thrown.
11452 @end defun
11453
11454 @defun generation->maybe obj
11455 [SRFI-189]
11456 @c MOD srfi.189
11457 If @var{obj} is an EOF value, a Nothing is returned.
11458 Otherwise, a Just wrapping @var{obj} is returned.
11459 @end defun
11460
11461 @defun either->generation either
11462 [SRFI-189]
11463 @c MOD srfi.189
11464 If @var{either} is a Left, an EOF object is returned.
11465 Otherwise, it must be a Right with one value, and its value is returned.
11466 If @var{either} is a Right and it doesn't have exactly one value, an error
11467 is thrown.
11468 @end defun
11469
11470 @defun generation->either obj fail-objs @dots{}
11471 [SRFI-189]
11472 @c MOD srfi.189
11473 If @var{obj} is an EOF value, a Left with @var{fail-objs} @dots{} is returned.
11474 Otherwise, a Right wrapping @var{obj} is returned.
11475 @end defun
11476
11477 @defun maybe->values maybe
11478 [SRFI-189]
11479 @c MOD srfi.189
11480 If @var{maybe} is a Just, returns its payload as multiple values.
11481 If it is a Nothing, returns no values.
11482 (Note that a Just with zero values also returns no values.)
11483 @end defun
11484
11485 @defun values->maybe producer
11486 [SRFI-189]
11487 @c MOD srfi.189
11488 It first invokes a procedure @var{producer} with no values.
11489 If it returns zero values, a Nothing is returned; otherwise,
11490 a Just with those values are returned.
11491 @end defun
11492
11493 @defun either->values either
11494 [SRFI-189]
11495 @c MOD srfi.189
11496 If @var{either} is a Right, returns its payload as multiple values.
11497 If it is a Left, returns no values.
11498 (Note that a Right with zero values also returns no values.)
11499 @end defun
11500
11501 @defun values->either producer fail-obj @dots{}
11502 [SRFI-189]
11503 @c MOD srfi.189
11504 It first invokes a procedure @var{producer} with no values.
11505 If it returns zero values, a Left with @var{fail-obj} @dots{} as
11506 its payload is returned.
11507 If it returns one or more values,
11508 a Right with those values are returned.
11509 @end defun
11510
11511 @defun maybe->two-values maybe
11512 [SRFI-189]
11513 @c MOD srfi.189
11514 If @var{maybe} is a Just with exactly one value, the value and @code{#t}
11515 is returned. If @var{maybe} is a Nothing, two @code{#f} is returned.
11516 An error is thrown if @var{maybe} has a Just with zero or more than two
11517 values.
11518 @end defun
11519
11520 @defun two-values->maybe producer
11521 [SRFI-189]
11522 @c MOD srfi.189
11523 The inverse of @code{maybe->two-values}. A procedure @var{producer}
11524 is called with no arguments. It must return two values, a possible
11525 payload value, and a boolean. If the second value is true,
11526 a Just with the first value is returned. If the second value is @code{#f},
11527 a Nothing is returned (the first return value is ignored).
11528 @end defun
11529
11530 @defun exception->either pred thunk
11531 [SRFI-189]
11532 @c MOD srfi.189
11533 A procedure @var{thunk} is called without argument, wrapped by an
11534 exception handler. If @var{thunk} raises a condition, it is
11535 examined by @var{pred}. If @var{pred} returns true on the condition,
11536 the exception is wrapped by a Left and returned.
11537 If @var{pred} returns @code{#f}, the exception is reraised.
11538 If no exception is raised, the result(s) of @var{thunk} is wrapped
11539 by a Right and returned.
11540 @end defun
11541
11542 @node Maybe and Either syntactic utilities, Trivalent logic, Maybe and Either protocol converters, Maybe and Either optional container types
11543 @subsection Syntactic utilities
11544
11545 @defmac maybe-if mtest then else
11546 [SRFI-189]
11547 @c MOD srfi.189
11548 If the @var{mtest} expression yields a Just, evaluates @var{then}.
11549 If the @var{mtest} expression yeilds a Nothing, evaluates @var{else}.
11550 If the @var{mtest} expression doesn't produce a Maybe, an error
11551 is thrown.
11552 @end defmac
11553
11554 @defmac maybe-and maybe @dots{}
11555 @defmacx either-and either @dots{}
11556 [SRFI-189]
11557 @c MOD srfi.189
11558 Evaluates @var{maybe}/@var{either} from left to right, as far as
11559 each yields a Just/Right. If every expression yields a Just/Right,
11560 the last one is returned. If it encounters an expression that
11561 yields a Nothing/Left, it stops evaluating the rest of expressions and
11562 returns the Nothing/Left.
11563
11564 If expressions yield something other than Maybe/Either, an error is thrown.
11565 @end defmac
11566
11567 @defmac maybe-or maybe @dots{}
11568 @defmacx either-or either @dots{}
11569 [SRFI-189]
11570 @c MOD srfi.189
11571 Evaluates @var{maybe}/@var{either} from left to right, as far as
11572 each yields a Nothing/Left. If it encounters an expression that
11573 yields a Just/Right, it stops evaluating the rest of expressions and
11574 returns it.
11575
11576 If expressions yield something other than Maybe/Either, an error is thrown.
11577 @end defmac
11578
11579 @defmac maybe-let* ( claw @dots{} ) body @dots{}
11580 @defmacx either-let* ( claw @dots{} ) body @dots{}
11581 [SRFI-189]
11582 @c MOD srfi.189
11583 This is a Maybe/Either version of @code{and-let*}.
11584
11585 Each @var{claw} can be either one of the following forms:
11586 @table @code
11587 @item @var{identifier}
11588 The @var{identifier}'s value is taken. It must be a Maybe/an Either,
11589 or an error is signaled.
11590 If it is a Just/Right, evaluation proceeds to the next claw.
11591 If it is a Nothing/Left, evaluation stops and the value is returned
11592 immediately.
11593 @item (@var{identifier} @var{expression})
11594 The @var{expression} is evaluated. It must yield a Maybe/an Either,
11595 or an error is signaled.
11596 If it is a Just/Right, @var{identifier} is bound to its payload,
11597 and the rest of @var{claw}s and @var{body} are processed with the scope
11598 of @var{identifier}. If it is a Nothing/Left, evaluation stops and
11599 the value is returned immediately.
11600 An error is signaled if a Just/Right doesn't carry exactly one value.
11601 @item ( @var{expression} )
11602 The @var{expression} is evaluated. It must yield a Maybe/an Either,
11603 or an error is signaled.
11604 If it is a Just/Right, evaluation proceeds to the next claw.
11605 If it is a Nothing/Left, evaluation stops and the value is returned
11606 immediately.
11607 @end table
11608
11609 After all @var{claws} are processed and none yields a Nothing/Left,
11610 @var{body} @dots{} are evaluated.
11611 @end defmac
11612
11613 @defmac maybe-let*-values ( mv-claw @dots{} ) body @dots{}
11614 @defmacx either-let*-values ( mv-claw @dots{} ) body @dots{}
11615 [SRFI-189]
11616 @c MOD srfi.189
11617 Multi-value payload version of @code{maybe-let*}/@code{either-let*}.
11618
11619 Each @var{claw} can be either one of the following forms:
11620 @table @code
11621 @item @var{identifier}
11622 The @var{identifier}'s value is taken. It must be a Maybe/an Either,
11623 or an error is signaled.
11624 If it is a Just/Right, evaluation proceeds to the next claw.
11625 If it is a Nothing/Left, evaluation stops and the value is returned
11626 immediately.
11627 @item (@var{formals} @var{expression})
11628 The @var{formals} is the same as the formals of the lambda form, that
11629 is, a proper or dotted list of identifiers.
11630
11631 The @var{expression} is evaluated. It must yield a Maybe/an Either,
11632 or an error is signaled.
11633 If it is a Just/Right, identifiers in the @var{formals} are bound
11634 with the payload of the Just/Right,
11635 and the rest of @var{claw}s and @var{body} are processed with the scope
11636 of those identifiers. If it is a Nothing/Left, evaluation stops and
11637 the value is returned immediately.
11638 An error is signaled if the formals doesn't match the payload
11639 of the Just/Right.
11640 @item ( @var{expression} )
11641 The @var{expression} is evaluated. It must yield a Maybe/an Either,
11642 or an error is signaled.
11643 If it is a Just/Right, evaluation proceeds to the next claw.
11644 If it is a Nothing/Left, evaluation stops and the value is returned
11645 immediately.
11646 @end table
11647
11648 After all @var{claws} are processed and none yields a Nothing/Left,
11649 @var{body} @dots{} are evaluated.
11650 @end defmac
11651
11652 @defmac either-guard pred body @dots{}
11653 [SRFI-189]
11654 @c MOD srfi.189
11655 The @var{body} @dots{} is evaluated, and the value(s) it produces
11656 are wrapped in a Right and returned. If an exception occurs in
11657 @var{body} @dots{}, the thrown condition is passed to a predicate @var{pred}.
11658 If the condition satisfies the predicate, it is wrapped in a Left
11659 and returned. Otherwise, the condition is reraised with
11660 @code{raise-continuable.}
11661 @end defmac
11662
11663 @node Trivalent logic, , Maybe and Either syntactic utilities, Maybe and Either optional container types
11664 @subsection Trivalent logic
11665
11666 This section describes procedures that deal with trivalent logic---a value can
11667 be a false value (@code{Just #f}), a true value
11668 (@code{Just} with anything other than @code{#f}), and @code{Nothing}.
11669
11670 If any of the arguments is @code{Nothing}, the result becomes @code{Nothing}
11671 (except @code{tri=?}).
11672
11673 All the argument must be Maybe type, or an error is signalled.
11674
11675 @defun tri-not maybe
11676 [SRFI-189]
11677 @c MOD srfi.189
11678 Returns @code{Just #t} if @var{maybe} is trivalent-false,
11679 @code{Just #f} if @var{maybe} is triavlent-true, and
11680 @code{Nothing} if @var{maybe} is @code{Nothing}.
11681 @end defun
11682
11683 @defun try=? maybe @dots{}
11684 [SRFI-189]
11685 @c MOD srfi.189
11686 Returns @code{Just #t} if arguments are either all trivalent-true
11687 or all trivalent-false. Otherwise return @code{Just #f}.
11688 Note that if any of the argument is @code{Nothing}, the result is
11689 @code{Just #f} (even all arguments are @code{Nothing}).
11690 @end defun
11691
11692 @defun try-and maybe @dots{}
11693 [SRFI-189]
11694 @c MOD srfi.189
11695 Returns @code{Just #t} if all arguments are trivalent-true,
11696 @code{Just #f} if all arguments are @code{Just} but at least one
11697 of them is @code{Just #f}, and @code{Nothing} if any of the arguments
11698 is @code{Nothing}. If there's no arguments, @code{Just #t} is returned.
11699
11700 This is not a shortcut operation like @code{and}.
11701 @end defun
11702
11703 @defun try-or maybe @dots{}
11704 [SRFI-189]
11705 @c MOD srfi.189
11706 Returns @code{Just #f} if all arguments are trivalent-false,
11707 @code{Just #t} if all arguments are @code{Just} but at least one
11708 of them is trivalent-true, and @code{Nothing} if any of the arguments
11709 is @code{Nothing}. If there's no arguments, @code{Just #f} is returned.
11710
11711 This is not a shortcut operation like @code{or}.
11712 @end defun
11713
11714 @defun try-merge maybe @dots{}
11715 [SRFI-189]
11716 @c MOD srfi.189
11717 If all arguments are @code{Nothing}, @code{Nothing} is returned.
11718 Otherwise, first @code{Just} is returned.
11719 @end defun
11720
11721 @c ----------------------------------------------------------------------
11722 @node Coroutine generators, Port positioning, Maybe and Either optional container types, Library modules - SRFIs
11723 @section @code{srfi.190} - Coroutine generators
11724 @c NODE コルーチンジェネレータ, @code{srfi.190} - コルーチンジェネレータ
11725
11726 @deftp {Module} srfi.190
11727 @mdindex srfi.190
11728 This module provides a macro, @code{coroutine-generator},
11729 that simplifies defining a generator-based coroutine.
11730 @end deftp
11731
11732 @defmac coroutine-generator body
11733 [SRFI-190]
11734 @c MOD srfi.190
11735 @end defmac
11736
11737 @defmac yield
11738 [SRFI-190]
11739 @c MOD srfi.190
11740 @end defmac
11741
11742 @defmac define-coroutine-generator name expr
11743 @defmacx define-coroutine-generator (name . formals) body @dots{}
11744 [SRFI-190]
11745 @c MOD srfi.190
11746 @end defmac
11747
11748 @c ----------------------------------------------------------------------
11749 @node Port positioning, Command line, Coroutine generators, Library modules - SRFIs
11750 @section @code{srfi.192} - Port positioning
11751 @c NODE ポート位置, @code{srfi.192} - ポート位置
11752
11753 @deftp {Module} srfi.192
11754 @mdindex srfi.192
11755 @c EN
11756 This srfi defines procedures to get and set the current position of
11757 the port.
11758
11759 This feature is already supported in the Gauche core, so the following
11760 procedure is described in @ref{Common port operations}.
11761 @c JP
11762 このsrfiはポートの現在の位置を取得したり設定したりする手続きを提供します。
11763
11764 この機能はGaucheのコアでサポートされており、以下の手続きは
11765 @ref{Common port operations}で説明されています:
11766 @c COMMON
11767 @example
11768 port-position
11769 port-has-port-position?
11770 set-port-position!
11771 port-has-set-port-position?
11772 @end example
11773 @end deftp
11774
11775 @defun make-i/o-invalid-position-error pos
11776 [SRFI-192]
11777 @c MOD srfi.192
11778 @c EN
11779 This portably creates a condition suitable to be raised from
11780 @code{set-port-position!} when the given position object can't
11781 be accepted. The @var{pos} argument is the offending position object.
11782 @c JP
11783 これは、@code{set-port-position!}が不正な位置情報を受け取った時に
11784 投げるべきコンディションを作成するポータブルな手続きです。
11785 @var{pos}引数は問題となった位置情報でう。
11786 @c COMMON
11787
11788 @c EN
11789 In Gauche, such condition is represented by
11790 @code{<io-invalid-position-error>} class, which is a subclass
11791 of @code{<port-error>}.
11792 @c JP
11793 Gaucheでは、その場合のコンディションは@code{<port-error>}のサブクラスである
11794 @code{<io-invalid-position-error>}のインスタンスで表されています。
11795 @c COMMON
11796
11797 @c EN
11798 If you raise a condition created with this procedure from
11799 the @code{set-position!} callback of the custom ports
11800 (@pxref{Custom ports}), Gauche intercepts it and adds
11801 the port information to the condition.
11802 @c JP
11803 カスタムポート(@ref{Custom ports}参照)の@code{set-position!}コールバック手続き
11804 の中で、この手続きで作ったコンディションを投げた場合、
11805 Gaucheはその例外をインターセプトして、ポートの情報をコンディションに付け加えます。
11806 @c COMMON
11807 @end defun
11808
11809 @defun i/o-invalid-position-error? obj
11810 [SRFI-192]
11811 @c MOD srfi.192
11812 @c EN
11813 Returns @code{#t} iff @var{obj} is an i/o-invalid-position-error
11814 condition (or a compound condition that includes it).
11815
11816 In Gauche, it is the same as
11817 @code{(condition-has-type? @var{obj} <io-invalid-position-error>)}.
11818 @c JP
11819 @var{obj}がi/o-invalid-position-errorか、
11820 それを含む複合コンディションであれば@code{#t}を、そうでなければ@code{#f}を返します。
11821
11822 Gaucheでは、これは
11823 @code{(condition-has-type? @var{obj} <io-invalid-position-error>)}
11824 と同じことです。
11825 @c COMMON
11826 @end defun
11827
11828 @c ----------------------------------------------------------------------
11829 @node Command line, Random data generators (SRFI), Port positioning, Library modules - SRFIs
11830 @section @code{srfi.193} - Command line
11831 @c NODE コマンドライン, @code{srfi.193} - コマンドライン
11832
11833 @deftp {Module} srfi.193
11834 @mdindex srfi.193
11835 @c EN
11836 This srfi clarifying how the command line arguments can be accessed
11837 via R7RS @code{command-line}, plus a few supporting APIs.
11838 @c JP
11839 このsrfiは、R7RSの@code{command-line}が返す値についての仕様を
11840 明確化し、またいくつかのサポートAPIを定義しています。
11841 @c COMMON
11842
11843 @c EN
11844 The following procedures are built-in. @xref{Command-line arguments},
11845 for the details.
11846 @c JP
11847 次の手続きは組み込みになっています。
11848 @ref{Command-line arguments}を参照してください。
11849 @c COMMON
11850
11851 @example
11852 command-line script-file
11853 @end example
11854 @end deftp
11855
11856 @defun command-name
11857 [SRFI-193]
11858 @c MOD srfi.193
11859 @c EN
11860 If the first element of @code{command-line} is an empty string,
11861 returns @code{#f}. Otherwise, returns the first element without directory
11862 name and obvious extension (@code{.scm}, @code{.exe}) stripped.
11863 @c JP
11864 @code{command-line}の最初の要素が空文字列であれば@code{#f}を、
11865 そうでなければ@code{command-line}の最初の要素からディレクトリパスと
11866 典型的な拡張子(@code{.scm}、@code{.exe})を除いた名前を返します。
11867 @c COMMON
11868
11869 @c EN
11870 For example, if you run a Scheme script @code{foo.scm}
11871 as a program, this procedure returns @code{foo}. If you compile
11872 your script to an executable on Windows as the name
11873 @code{/usr/local/bin/foo.exe}, this procedure still returns @code{foo}.
11874 In general, if you are running a Scheme program as some sort of 'command',
11875 this procedure returns its name. The exception is when you're running
11876 a REPL, in which case this procedure returns @code{#f}.
11877 @c JP
11878 例えば、Schemeスクリプトを@code{/usr/local/bin/foo.scm}を
11879 プログラムとして走らせたら、この手続きは@code{foo}を返します。
11880 このスクリプトをWindows実行可能形式にコンパイルして
11881 @code{/usr/local/bin/foo.exe}に置いたとしても、やはりこの手続きは@code{foo}を返します。
11882 一般に、Schemeプログラムを何らかの形で「コマンド」として走らせた場合、
11883 その「コマンド名」にふさわしいものが返されます。例外はREPLを走らせている場合で、
11884 @code{#f}が返されます。
11885 @c COMMON
11886
11887 @c EN
11888 This is useful for diagnostic messages, for example.
11889 @c JP
11890 これは診断メッセージ等に便利です。
11891 @c COMMON
11892 @end defun
11893
11894 @defun command-args
11895 [SRFI-193]
11896 @c MOD srfi.193
11897 @c EN
11898 Returns the cdr of @code{(command-line)}.
11899 @c JP
11900 @code{(commnand-line)}のcdrを返します。
11901 @c COMMON
11902 @end defun
11903
11904 @defun script-directory
11905 [SRFI-193]
11906 @c MOD srfi.193
11907 @c EN
11908 Returns the directory part of @code{(script-file)}, if it has a string path.
11909 It always ends with the directory separator.
11910 If @code{(script-file)} is @code{#f}, @code{#f} is returned.
11911 @c JP
11912 @code{(script-file)}の値が文字列なら、そのディレクトリ部分を返します。
11913 この場合、返される文字列の末尾は必ずディレクトリ区切り文字になっています。
11914 @code{(script-file)}が@code{#f}なら@code{#f}が返されます。
11915 @c COMMON
11916
11917 @c EN
11918 This is useful, for example, to find an auxiliary files relative to the
11919 script location.
11920 @c JP
11921 これは例えば、補助ファイルをスクリプトからの相対位置で探すのに便利です。
11922 @c COMMON
11923 @end defun
11924
11925 @c ----------------------------------------------------------------------
11926 @node Random data generators (SRFI), Range objects, Command line, Library modules - SRFIs
11927 @section @code{srfi.194} - Random data generators (SRFI)
11928 @c NODE SRFIランダムデータジェネレータ, @code{srfi.194} - ランダムデータジェネレータ (SRFI)
11929
11930 @deftp {Module} srfi.194
11931 @mdindex srfi.194
11932 This module provides a set of generators (@pxref{Generators}) that yield
11933 random data of specific distributions.
11934
11935 Gauche has its own random data generator module @code{data.random}
11936 (@pxref{Random data generators}), which was a basis of this SRFI,
11937 although procedure names are adjusted to match other SRFIs.
11938 This SRFI also adds several advanced random data generators.
11939 @end deftp
11940
11941 @subheading Random sources
11942
11943 @deffn {Parameter} current-random-source
11944 [SRFI-194]
11945 @c MOD srfi.194
11946 The value of this parameter must be a SRFI-27 random source.
11947 Generators created in this module use the value of this parameter
11948 at the time of creation as a random source. Changing this after
11949 a generator is created won't affect its behavior.
11950
11951 In Gauche, this is just an alias of @code{random-data-random-source}
11952 of @code{data.random}. Rebinding either one affects both @code{srfi.194}
11953 and @code{data.random} procedures (@pxref{Random data generators}).
11954 @end deffn
11955
11956 @defun with-random-source random-source thunk
11957 [SRFI-194]
11958 @c MOD srfi.194
11959 Calls @var{thunk} while binding the parameter @code{current-random-source}
11960 to @var{random-source}, which must be a random source
11961 object of srfi-27.
11962 @end defun
11963
11964 @defun make-random-source-generator i
11965 [SRFI-194]
11966 @c MOD srfi.194
11967 Returns a fresh generator that creates
11968 a new random source by @code{make-random-source}, and
11969 process it with @code{random-source-pseudo-randomize!} with @var{i},
11970 and internal counter @var{j}, starting from 0 and incremented
11971 every time the generator is called.
11972 @xref{Sources of random bits}, for the details of
11973 @code{make-random-source} and
11974 @code{random-source-pseudo-randomize!}.
11975 @end defun
11976
11977 @subheading Uniform distributions
11978
11979 @defun make-random-integer-generator lower-bound upper-bound
11980 [SRFI-194]
11981 @c MOD srfi.194
11982 Creates and returns a generator that generates exact integers
11983 between @var{lower-bound} (inclusive) and @var{upper-bound}
11984 (exclusive).
11985 Same as calling @code{(integers$ (- upper-bound lower-boud) lower-bound)}
11986 of @code{data.random} (@pxref{Random data generators}).
11987
11988 Note that this is different from @code{integers-between$}, which
11989 includes the upper bound.
11990 @end defun
11991
11992 @defun make-random-u1-generator
11993 @defunx make-random-u8-generator
11994 @defunx make-random-s8-generator
11995 @defunx make-random-u16-generator
11996 @defunx make-random-s16-generator
11997 @defunx make-random-u32-generator
11998 @defunx make-random-s32-generator
11999 @defunx make-random-u64-generator
12000 @defunx make-random-s64-generator
12001 [SRFI-194]
12002 @c MOD srfi.194
12003 Creates and returns a generator of fixed-range exact integers.
12004 Calling @code{make-random-u1-generator} is the same as
12005 @code{(integers$ 2)}, and other generators are
12006 the same as @code{uint8s$}, @code{sint8s$}, etc., of
12007 @code{data.random} (@pxref{Random data generators}).
12008 @end defun
12009
12010 @defun clamp-real-number lower-bound upper-bound value
12011 [SRFI-194]
12012 @c MOD srfi.194
12013 All arguments must be real numbers, and @var{lower-bound} must be
12014 less than or equal to @var{upper-bound}. If @var{value} is between
12015 two bounds, it is returned as is. If it is smaller than @var{lower-bound},
12016 @var{lower-bound} is returned.
12017 If it is greater than @var{upper-bound}, @var{upper-bound} is returned.
12018
12019 Similar to Gauche's build-in @code{clamp}, with different argument
12020 order (@pxref{Arithmetics}).
12021 @end defun
12022
12023 @defun make-random-real-generator lower-bound upper-bound
12024 [SRFI-194]
12025 @c MOD srfi.194
12026 Returns a fresh generator that produces a real number between
12027 @var{lower-bound} and @var{upper-bound}, both inclusive.
12028
12029 It is the same as @code{reals-between$} of @code{data.random}
12030 (@pxref{Random data generators}).
12031 @end defun
12032
12033 @defun make-random-rectangular-generator re-lower-bound re-upper-bound im-lower-bound im-upper-bound
12034 @defunx make-random-polar-generator [origin] mag-lower-bound mag-upper-bound :optional angle-lower-bound angle-upper-bound
12035 [SRFI-194]
12036 @c MOD srfi.194
12037 Returns a fresh generator that produces a complex number
12038 uniformly within the area specified by the arguments.
12039 They are the same as @code{complexes-rectangular$} and
12040 @code{complexes-polar$} of @code{data.random}
12041 (@pxref{Random data generators}), respectively.
12042 See their entries for the details.
12043 @end defun
12044
12045 @defun make-random-boolean-generator
12046 [SRFI-194]
12047 @c MOD srfi.194
12048 Returns a fresh generator that produces random boolean values.
12049 It is the same as @code{booleans$} of @code{data.random}
12050 (@pxref{Random data generators}).
12051 @end defun
12052
12053 @defun make-random-char-generator string
12054 [SRFI-194]
12055 @c MOD srfi.194
12056 Returns a fresh generator that produces characters uniformly
12057 sampled from @var{string}. The order of characters within @var{string}
12058 is irrelevant. You can repeat characters in @var{stirng} to increase
12059 the chance of that characters to be produced.
12060
12061 It is an error if @var{string} is empty.
12062
12063 This is not the same as @code{chars$}, but rather a type-restricted
12064 case of @code{samples$} of @code{data.random}
12065 (@pxref{Random data generators}).
12066 @end defun
12067
12068 @defun make-random-string-generator k string
12069 [SRFI-194]
12070 @c MOD srfi.194
12071 Returns a fresh generator that produces a random string
12072 of length @var{k} and consisting characters uniformly
12073 sampled from @var{string}.
12074
12075 It is an error if @var{string} is empty.
12076
12077 This is not the same as @code{strings-of} of @code{data.random}.
12078 Rather, this can be written as
12079 @code{(strings-of (integers$ k) (samples$ str))}
12080 (@pxref{Random data generators}).
12081 @end defun
12082
12083 @subheading Nonuniform distributions
12084
12085 @defun make-bernoulli-generator p
12086 [SRFI-194]
12087 @c MOD srfi.194
12088 @end defun
12089
12090 @defun make-binomial-generator n p
12091 [SRFI-194]
12092 @c MOD srfi.194
12093 @end defun
12094
12095 @defun make-categorical-generator weight-vec
12096 [SRFI-194]
12097 @c MOD srfi.194
12098 @end defun
12099
12100 @defun make-normal-generator :optional mean deviation
12101 [SRFI-194]
12102 @c MOD srfi.194
12103 @end defun
12104
12105 @defun make-exponential-generator mean
12106 [SRFI-194]
12107 @c MOD srfi.194
12108 @end defun
12109
12110 @defun make-geometric-generator p
12111 [SRFI-194]
12112 @c MOD srfi.194
12113 @end defun
12114
12115 @defun make-poisson-geneartor L
12116 [SRFI-194]
12117 @c MOD srfi.194
12118 @end defun
12119
12120 @defun make-zipf-generator N :optional s q
12121 [SRFI-194]
12122 @c MOD srfi.194
12123 @end defun
12124
12125 @defun make-sphere-generator n
12126 [SRFI-194]
12127 @c MOD srfi.194
12128 @end defun
12129
12130 @defun make-ellipsoid-generator axes
12131 [SRFI-194]
12132 @c MOD srfi.194
12133 @end defun
12134
12135 @defun make-ball-generator dimensions
12136 [SRFI-194]
12137 @c MOD srfi.194
12138 @end defun
12139
12140 @subheading Generator operations
12141
12142 @defun gsampling generator @dots{}
12143 [SRFI-194]
12144 @c MOD srfi.194
12145 @end defun
12146
12147
12148 @c ----------------------------------------------------------------------
12149 @node Range objects, Pipeline operators, Random data generators (SRFI), Library modules - SRFIs
12150 @section @code{srfi.196} - Range objects
12151 @c NODE レンジオブジェクト, @code{srfi.196} - レンジオブジェクト
12152
12153 @deftp {Module} srfi.196
12154 @mdindex srfi.196
12155 @c EN
12156 This srfi defines @emph{range} object, an abstract immutable sequence.
12157
12158 Gauche's @code{data.range} module provides superset of @code{srfi.196}.
12159 This module re-exports the following procedures from it for the portable
12160 code.
12161 @xref{Range}, for the description of the procedures.
12162 @c JP
12163 このsrfiはレンジオブジェクトを定義します。
12164 レンジオブジェクトは、変更不可なシーケンスを抽象化したものです。
12165
12166 Gaucheは@code{data.range}モジュールで@code{srfi.196}のスーパーセットを
12167 提供しています。このモジュールは、ポータブルなコードのために以下の手続きを
12168 再エクスポートするだけのものです。
12169 レンジオブジェクトについて詳しくは@ref{Range}を参照してください。
12170 @c COMMON
12171
12172 @example
12173 range numeric-range iota-range
12174 vector-range string-range range-append
12175 range? range=? range-length
12176 range-ref range-first range-last
12177 range-split-at subrange range-segment
12178 range-take range-take-right
12179 range-drop range-drop-right
12180 range-count range-any range-every
12181 range-map range-map->list range-map->vector
12182 range-for-each range-filter-map range-filter-map->list
12183 range-filter range-filter->list
12184 range-remove range-remove->list
12185 range-fold range-fold-right range-reverse
12186 range-index range-index-right
12187 range-take-while range-take-while-right
12188 range-drop-while range-drop-while-right
12189 range->list range->vector range->string
12190 vector->range range->generator
12191 @end example
12192 @end deftp
12193
12194 @c ----------------------------------------------------------------------
12195 @node Pipeline operators, String-notated bytevectors, Range objects, Library modules - SRFIs
12196 @section @code{srfi.197} - Pipeline operators
12197 @c NODE パイプラインオペレータ, @code{srfi.197} - パイプラインオペレータ
12198
12199 @deftp {Module} srfi.197
12200 @mdindex srfi.197
12201 @c EN
12202 This module provides a set of macros to compose multiple operations.
12203 It is similar to Clojure's ``threading macro''.
12204 @c JP
12205 このモジュールは、複数の操作を組み合わせるマクロを提供します。
12206 Clojureの「スレッドマクロ」に似たものです。
12207 @c COMMON
12208
12209 @c EN
12210 When you're passing a result of some procedure to another procedure and
12211 so on, sometimes you get a deeply nested expression:
12212 @c JP
12213 ひとつの関数適用の結果を別の関数に渡して…というのをつなげてゆくと、
12214 しばしば式のネストが深くなってしまいます:
12215 @c COMMON
12216
12217 @example
12218 (g (f (e (d (c (b (a arg)))))))
12219 @end example
12220
12221 @c EN
12222 In Gauche, you can also write the above expression with @code{$} macro
12223 (@pxref{Making procedures}):
12224 @c JP
12225 Gaucheでは@code{$}マクロを使えば上の式はこうも書けます
12226 (@ref{Making procedures}参照):
12227 @c COMMON
12228
12229 @example
12230 ($ g $ f $ e $ d $ c $ b $ a arg)
12231 @end example
12232
12233 @c EN
12234 Deep nesting is avoided, but it's still right-to-left, and the placement
12235 of argument to receive the previous result is limited to the last position.
12236 @c JP
12237 ネストは浅くなりましたが、適用順は依然として右から左で、
12238 また前の結果を引数として渡す位置が最後の引数に限られます。
12239 @c COMMON
12240
12241 @c EN
12242 With @code{chain} macro in this module, you can write it
12243 from left to right:
12244 @c JP
12245 このモジュールの@code{chain}マクロを使うと、
12246 上の式は左から右にデータを流すように書けます:
12247 @c COMMON
12248
12249 @example
12250 (chain (a arg) (b _) (c _) (d _) (e _) (f _) (g _))
12251 @end example
12252
12253 @c EN
12254 The @code{_} in the second expressions and after indicates the place
12255 where previous result is passed.
12256 It is conceptually expanded to the following:
12257 @c JP
12258 2番目以降の式中の@code{_}は、前の結果をその位置の引数で受け取ることを示します。
12259 上の式は概念的には次の式と等価です。
12260 @c COMMON
12261
12262 @example
12263 (let* ((tmp (a arg))
12264 (tmp (b tmp))
12265 (tmp (c tmp))
12266 (tmp (d tmp))
12267 (tmp (e tmp)))
12268 (g tmp))
12269 @end example
12270
12271 @c EN
12272 Because the placeholder is explicit, you can pass additional arguments:
12273 @c JP
12274 引数をはめ込む場所を明示できるので、他の引数も自由に渡せます:
12275 @c COMMON
12276
12277 @example
12278 (chain x (y a _) (z _ b))
12279 @equiv{}
12280 (let* ((tmp x)
12281 (tmp (y a tmp)))
12282 (z tmp b))
12283 @end example
12284
12285 @c EN
12286 Or even use multiple values:
12287 @c JP
12288 多値を受け取って複数の引数として渡すこともできます:
12289 @c COMMON
12290
12291 @example
12292 (chain mv-expr (f _ _) (g _ _))
12293 @equiv{}
12294 (let*-values (((tmp1 tmp2) mv-expr)
12295 ((tmp1 tmp2) (f tmp1 tmp2)))
12296 (g tmp1 tmp2))
12297 @end example
12298 @end deftp
12299
12300 @defmac chain initial-value [placeholder [ellipsis]] step @dots{}
12301 [SRFI-197]
12302 @c MOD srfi.197
12303 @c EN
12304 The optional @var{placeholder} and @var{ellipsis} are, if given,
12305 literal symbols. It replaces the default placeholder and ellipsis
12306 symbols, @code{_} and @code{...}, respectively.
12307 @c JP
12308 省略可能な@var{placeholder}と@var{ellipsis}引数は、
12309 リテラルシンボルでなければなりません。与えられた場合は、
12310 デフォルトのプレースホルダ@code{_}とエリプシス@code{...}を置き換えます。
12311 @c COMMON
12312
12313 @c EN
12314 Each @var{step} is @code{(@var{datum} @dots{})}, where each @var{datum}
12315 must be either an expression, placeholder symbol, or the ellipsis symbol.
12316 The ellipsis symbol must appear in the last position, if any,
12317 and must immediately follow the placeholder symbol.
12318 @c JP
12319 各@var{step}は@code{(@var{datum} @dots{})}の形で、
12320 @var{datum}は式、プレースホルダ、あるいはエリプシスです。
12321 但し、エリプシスは最後の要素としてのみ許され、現れた場合は直前がプレースホルダ
12322 でなければなりません。
12323 @c COMMON
12324
12325 @c EN
12326 Conceptually, each @var{step} becomes a procedure that takes as
12327 many arguments as the placeholders. If the @var{step} ends with
12328 ellipsis symbol, the last placeholder works as the ``rest'' arguments.
12329 @c JP
12330 概念的には、各@var{step}はプレースホルダの数だけ引数を取る手続きへと展開されます。
12331 手続きに渡された引数は順にプレースホルダの箇所に充てられます。
12332 @var{step}の最後がエリプシスだった場合は、直前のプレースホルダが ``rest'' 引数として
12333 動作します。
12334 @c COMMON
12335
12336 @c EN
12337 If a @var{step} expects more than one value, the previous @var{step}
12338 or @var{initial-value} is expected to yield that many values.
12339 @c JP
12340 @var{step}が一つ以上の値を期待する場合、直前の@var{step}もしくは
12341 @var{initial-value}は同じ数だけの値を生成せねばなりません。
12342 @c COMMON
12343
12344 @example
12345 (chain expr (f _ a _ ...))
12346 @equiv{}
12347 (let*-values (((tmp1 . tmp2) expr))
12348 (apply f tmp1 a tmp2))
12349 @end example
12350 @end defmac
12351
12352 @defmac chain-and initial-value [placeholder] step @dots{}
12353 [SRFI-197]
12354 @c MOD srfi.197
12355 @c EN
12356 A variant of @code{chain} that stops and returns @code{#f}
12357 immedialy when the intermediate result becomes @code{#f}.
12358 @c JP
12359 @code{chain}の変種で、中間の結果が@code{#f}になった場合にその後の@var{step}の
12360 評価を行わず直ちに@code{#f}を返します。
12361 @c COMMON
12362
12363 @c EN
12364 The @var{initial-value} is an expression that yields one value.
12365 The @var{placeholder} is a literal symbol to be used as the placeholder
12366 in @var{step}; if omitted, @code{_} is used.
12367 @c JP
12368 @var{initial-value}はひとつの値を返す式です。
12369 @var{placeholder}は@var{step}中でプレースホルダーとして使われるリテラルシンボルです。
12370 省略時には@code{_}が使われます。
12371 @c COMMON
12372
12373 @c EN
12374 Unlike @code{chain}, a @var{step} can only contain zero or one placeholder
12375 symbol. If @var{step} doesn't contain placeholder symbol, the previous
12376 @var{step}'s result isn't passed, but it is still checked if it's @code{#f}.
12377 @c JP
12378 @code{chain}と違い、各@var{step}はたかだか1個のプレースホルダーしか
12379 含むことができません。@var{step}がプレースホルダーを含んでいない場合、
12380 直前の@var{step}の結果は操作を打ちきるかどうかの判定のみに使われ、その後捨てられます。
12381 @c COMMON
12382 @end defmac
12383
12384 @defmac chain-when initial-value [placeholder] ([guard] step) @dots{}
12385 [SRFI-197]
12386 @c MOD srfi.197
12387 @c EN
12388 A variant of @code{chain} where you can select whether each @var{step}
12389 is applied or skipped.
12390 @c JP
12391 @code{chain}の変種で、@var{step}を適用するかどうかを選べるものです。
12392 @c COMMON
12393
12394 @c EN
12395 Each @var{step} can have at most one placeholder symbol, just as
12396 @code{chain-and}.
12397 @c JP
12398 @code{chain-and}と同じく、各@var{step}はプレースホルダーをたかだか1個までしか
12399 含むことができません。
12400 @c COMMON
12401
12402 @c EN
12403 Each @var{guard} is an expression. For each step, @var{guard} is
12404 evaluated, and if it yields a true value, the previous result is
12405 passed to the placeholder in the corresponding @var{step}. If
12406 @var{guard} yields @code{#f}, however, @var{step} is skipped and
12407 the previous value is passed through to the next step.
12408 @c JP
12409 各@var{guard}は式です。各ステップで、まず@var{guard}が評価され、
12410 それが真ならば直前に実行された結果がプレースホルダーに束縛されて
12411 対応する@var{step}が実行されます。@var{guard}が偽ならば、
12412 @var{step}は実行されず、直前の結果が次のステップへと持ち越されます。
12413 @c COMMON
12414
12415 @example
12416 (chain-when expr ((p? x) (f _)) ((q? x) (g _)))
12417 @equiv{}
12418 (let* ([tmp expr]
12419 [tmp (if (p? x) (f tmp) tmp)])
12420 (if (q? x) (g tmp) tmp))
12421 @end example
12422 @end defmac
12423
12424 @defmac chain-lambda [placeholder [ellipsis]] step @dots{}
12425 [SRFI-197]
12426 @c MOD srfi.197
12427 @example
12428 (chain-lambda step @dots{})
12429 @equiv{} (lambda args (chain (apply values args) step @dots{}))
12430 @end example
12431 @end defmac
12432
12433 @defmac nest [placeholder] step @dots{} initial-value
12434 [SRFI-197]
12435 @c MOD srfi.197
12436 @c EN
12437 Similar to @code{chain}, except the order of steps is right-to-left.
12438
12439 Each @var{step} must have exactly one placeholder symbol, for
12440 this macro simply nests the steps:
12441 @c JP
12442 @code{chain}と似ていますが、評価順が右から左になります。
12443
12444 各@var{step}はひとつだけプレースホルダーシンボルを持たなければなりません。
12445 このマクロは単にステップをネストした式に変換するだけです。
12446 @c COMMON
12447
12448 @example
12449 (nest (f a _) (g _ b) (h _) expr)
12450 @equiv{} (f a (g (h expr) b))
12451 @end example
12452 @end defmac
12453
12454 @defmac nest-reverse initial-value [placeholder] step @dots{}
12455 [SRFI-197]
12456 @c MOD srfi.197
12457 @c EN
12458 Similar to @code{nest} except the nesting is in reverse order.
12459
12460 Each @var{step} must have exactly one placeholder symbol, for
12461 this macro simply nests the steps:
12462 @c JP
12463 @code{nest}の評価順が逆になったものです。
12464
12465 各@var{step}はひとつだけプレースホルダーシンボルを持たなければなりません。
12466 このマクロは単にステップをネストした式に変換するだけです。
12467 @c COMMON
12468
12469 @example
12470 (nest expr (h _) (g _ b) (f a _))
12471 @equiv{} (f a (g (h expr) b))
12472 @end example
12473 @end defmac
12474
12475 @c ----------------------------------------------------------------------
12476 @node String-notated bytevectors, Enums and enum sets, Pipeline operators, Library modules - SRFIs
12477 @section @code{srfi.207} - String-notated bytevectors
12478 @c NODE 文字列表示のバイトベクタ, @code{srfi.207} - 文字列表示のバイトベクタ
12479
12480 @deftp {Module} srfi.207
12481 @mdindex srfi.207
12482 This SRFI defines an alternative representation of bytevectors, and
12483 provides a bunch of procedures that can treat a bytevector as a bytestring.
12484 @end deftp
12485
12486 @defun bytestring arg @dots{}
12487 [SRFI-207]
12488 @c MOD srfi.207
12489 Each argument must be either one of the followings, and the procedure
12490 returns a new bytevector which is concatenation of the given arguments.
12491
12492 @itemize @bullet
12493 @item
12494 An exact integer, between 0 and 255 inclusive.
12495 @item
12496 An ASCII character.
12497 @item
12498 A bytevector
12499 @item
12500 A string of ASCII characters
12501 @end itemize
12502
12503 An error is signaled if anything other than above is given.
12504
12505 @example
12506 (bytestring "lor" #\r #\x65 #u8(#x6d))
12507 @result{} #u8(108 111 114 114 101 109) ; #u8"lorem"
12508 @end example
12509 @end defun
12510
12511 @defun make-bytestring lis
12512 [SRFI-207]
12513 @c MOD srfi.207
12514 Returns a new bytevector whose content is a concatenation of
12515 elements in @var{lis}. Each element must be either an exact integer
12516 between 0 and 255 inclusive, an ASCII character, a bytevector
12517 or an ASCII string. It is effectively the same as
12518 @code{(apply bytestring lis)}.
12519 @end defun
12520
12521 @defun make-bytestring! bv at lis
12522 [SRFI-207]
12523 @c MOD srfi.207
12524 Fill a bytevector @var{bv} starting from index @var{at} with the
12525 elements in @var{lis}. Each element must be either an exact integer
12526 between 0 and 255 inclusive, an ASCII character, a bytevector
12527 or an ASCII string.
12528
12529 Returns an undefined value.
12530
12531 @example
12532 (rlet1 bv (make-u8vector 10)
12533 (make-bytestring! bv 1 '("ab" #\c #u8"de")))
12534 @result{} #u8(0 97 98 99 100 101 0 0 0 0)
12535 @end example
12536 @end defun
12537
12538 @defun bytevector->hex-string bv
12539 @defunx hex-string->bytevector string
12540 [SRFI-207]
12541 @c MOD srfi.207
12542 Convert a bytevector to hexadecimal digit string, and vice versa.
12543
12544 A condition that satisfies @code{bytestring-error?} is thrown
12545 by @code{hex-string->bytevector} if @var{string} contains a letter
12546 not valid as a hexadecimal digits.
12547
12548 @example
12549 (bytevector->hex-string #u8"aloha")
12550 @result{} "616c6f6861"
12551 (hex-string->bytevector "616C6F6861")
12552 @result{} #u8(97 108 111 104 97) ; #u8"aloha"
12553 @end example
12554 @end defun
12555
12556 @defun bytevector->base64 bv :optional digits
12557 @defunx base64->bytevector string :optional digits
12558 [SRFI-207]
12559 @c MOD srfi.207
12560 Encode a bytevector @var{bv} to Base64 encoded string, and vice versa.
12561
12562 A condition that satisfies @code{bytestring-error?} is thrown
12563 by @code{base64->bytevector} if @var{string} contains a letter
12564 not valid as a hexadecimal digits. Whitespace characters in @var{string}
12565 are silently ignored, though.
12566
12567 By default, they use standard Base64 mappings. You can specify
12568 a string of two ASCII characters in @var{digits} to alter
12569 mapping of 62nd and 63rd digits; the 'URL-safe' variant
12570 of Base64 can be achieved by passing @code{"-_"} as @var{digits}.
12571
12572 @xref{Base64 encoding/decoding}, for Gauche-specific Base64 library
12573 that provides more APIs.
12574 @end defun
12575
12576 @defun bytestring->list bv :optional start end
12577 [SRFI-207]
12578 @c MOD srfi.207
12579 Converts each element of a bytevector @var{bv} to
12580 either a character (if the element is an integer between 32 and 127,
12581 inclusive) or an integer, and returns a list of converted elements.
12582 If you pass the resulting list to @code{make-bytestring}, you can obtain
12583 the same bytevector as @var{bv}.
12584
12585 If you pass the optional @var{start} and @var{end} indexes,
12586 only the specified range of @var{bv} is considered.
12587 @end defun
12588
12589 @defun make-bytestring-generator arg @dots{}
12590 [SRFI-207]
12591 @c MOD srfi.207
12592 Returns a generator that works as the same as
12593 @code{(uvector->generator (bytestring @var{arg} @dots{}))},
12594 but this can skip creating intermediate bytestrings.
12595 @end defun
12596
12597 @defun bytestring-pad bv len char-or-u8
12598 @defunx bytestring-pad-right bv len char-or-u8
12599 [SRFI-207]
12600 @c MOD srfi.207
12601 Returns a newly allocated bytevector of at least @var{len} long.
12602 If @var{bv} is shorter than @var{len}, the rest is padded with
12603 @var{char-or-u8} (which can be either an ASCII character or
12604 an exact integer between 0 and 255). The pad is added to the left
12605 with @code{bytestring-pad}, and to the right with @code{bytestring-pad-right}.
12606
12607 This is a bytestring version of @code{string-pad} and @code{string-pad-right}
12608 (@pxref{SRFI-13 String selection}).
12609 @end defun
12610
12611 @defun bytestring-trim bv pred
12612 @defunx bytestring-trim-right bv pred
12613 @defunx bytestring-trim-both bv pred
12614 [SRFI-207]
12615 @c MOD srfi.207
12616 Remove octets that satisfies @var{pred}
12617 at the beginning / at the end / at both ends of a bitvector @var{bv}.
12618 The procedure @var{pred} receives an exact integer between 0 and 255.
12619
12620 They always return a fresh bytevector, even when no octets are trimmed.
12621
12622 This is a bytestring version of @code{string-trim},
12623 @code{string-trim-right}, and @code{string-trim-both}
12624 (@pxref{SRFI-13 String selection}).
12625 @end defun
12626
12627 @defun bytrestring-replace bv1 bv2 start1 end1 :optional start2 end2
12628 [SRFI-207]
12629 @c MOD srfi.207
12630 Returns a new bytevector whose content is a copy of a bytevector
12631 @var{bv1}, except the part beginning from the index
12632 @var{start1} (inclusive) and ending at the index @var{end1} (exclusive)
12633 is replaced by a byvetvector @var{bv2}.
12634 When optional @var{start2} and @var{end2}
12635 arguments are given, @var{bv2} is trimmed first accordingly.
12636 The size of the @emph{gap}, @code{(- @var{end1} @var{start1})}, doesn't
12637 need to be the same as the size of the inserted bytevector.
12638 Effectively, this is the same as the following code.
12639
12640 @example
12641 (bytevector-append (subseq bv1 0 start1)
12642 (subseq bv2 start2 end2)
12643 (subseq bv1 end1 (bytevector-length bv1)))
12644 @end example
12645
12646 This is a bytestring version of @code{string-replace}
12647 (@pxref{SRFI-13 Other string operations}).
12648 @end defun
12649
12650 @defun bytestring<? bv1 bv2
12651 @defunx bytestring<=? bv1 bv2
12652 @defunx bytestring>? bv1 bv2
12653 @defunx bytestring>=? bv1 bv2
12654 [SRFI-207]
12655 @c MOD srfi.207
12656 Compare two bytevectors lexicographically. These are bytestring
12657 version of @code{string<?} (@pxref{String comparison}).
12658
12659 There's no @code{bytestring=?}, for you can check equality of bytevectors
12660 by @code{bytevector=?} in @code{scheme.bytevector} and
12661 @code{gauche.uvector} (@pxref{Bytevector compatibility}).
12662
12663 Note that @code{bytevector-comparator} compares bytevectors
12664 differently. The comparator first compares the lengths, and only
12665 uses elements when both vectors are of the same length
12666 (@pxref{Predefined comparators}).
12667
12668 @example
12669 (bytestring<? #u8"abc" #u8"ac") @result{} #t
12670 (<? bytevector-comparator #u8"abc" #u8"ac") @result{} #f
12671 @end example
12672
12673 This contrasts SRFI-207's view of bytevectors as a string of bytes,
12674 with the view of them as an array of bytes.
12675 @end defun
12676
12677 @defun bytestring-index bv pred :optional start end
12678 @defunx bytestring-index-right bv pred :optional start end
12679 [SRFI-207]
12680 @c MOD srfi.207
12681 Returns the first or last index of the octet that satisfies @var{pred}
12682 in a bytevector @var{bv}. The optional @var{start} and @var{end}
12683 arguments limit the range to search.
12684
12685 These are bytestring version of @code{string-index} and
12686 @code{string-index-right} (@pxref{SRFI-13 String searching}).
12687 @end defun
12688
12689 @defun bytestring-break bv pred
12690 @defunx bytestring-span bv pred
12691 [SRFI-207]
12692 @c MOD srfi.207
12693 Returns two bytevectors, the first one is a maximum prefix of @var{bv}
12694 whose element does not / does satisfy @var{pred}, and the second one
12695 is the rest of @var{bv}.
12696
12697 @example
12698 (bytestring-break #u8"abracadabra" (cut = <> 100))
12699 @result{} #u8(97 98 114 97 99 97) @r{and} #u8(100 97 98 114 97)
12700 (bytestring-span #u8(1 2 3 4 5 4 3 2 1) (cut < <> 5))
12701 @result{} #u8(1 2 3 4) @r{and} #u8(5 4 3 2 1)
12702 @end example
12703 @end defun
12704
12705 @defun bytestring-join bv-list delim :optional grammar
12706 [SRFI-207]
12707 @c MOD srfi.207
12708 Given list of bytevectors @var{bv-list}, concatenates the bytevectors
12709 with a delimiter @var{delim}, which can be an exact integer
12710 between 0 and 255 inclusive, an ASCII character, a bytevector
12711 or a string of ASCII characters.
12712
12713 The @var{grammar} argument must be one of the symbols @code{infix},
12714 @code{strict-infix}, @code{suffix}, and @code{prefix}, as in
12715 @code{string-join} (@pxref{String utilities}). The difference
12716 between @code{infix} and @code{strict-infix} is that the former
12717 allows to join zero byvectors (returns @code{#u8()}), while the
12718 latter raises an error when @var{bv-list} is empty. When omitted,
12719 @code{infix} is assumed.
12720
12721 @example
12722 (bytestring-join '(#u8"a" #u8"b" #u8"c") 0) @result{} #u8(97 0 98 0 99)
12723 (bytestring-join '(#u8"a" #u8"b" #u8"c") 0 'prefix) @result{} #u8(0 97 0 98 0 99)
12724 (bytestring-join '(#u8"a" #u8"b" #u8"c") 0 'suffix) @result{} #u8(97 0 98 0 99 0)
12725 @end example
12726 @end defun
12727
12728 @defun bytestring-split bv delim :optional grammar
12729 [SRFI-207]
12730 @c MOD srfi.207
12731 Split a bytevector @var{bv} with @var{delim}, which must be
12732 either an exact integer between 0 and 255 inclusive or an ASCII character,
12733 and returns a list of bytevectors. Delimiters themselves are not included
12734 in the result.
12735
12736 The @var{grammar} argument is, if given, either one of the symbols
12737 @code{infix}, @code{strict-infix}, @code{prefix}, or @code{suffix},
12738 similar to @code{bytestring-join}. If it is @code{prefix}/@code{suffix},
12739 the preceding/succeeding @var{delim} is ignored, if any. There are no
12740 difference between @code{infix} and @code{strict-infix}. The default
12741 is @code{infix}.
12742
12743 @example
12744 (bytestring-split #u8"abracadabra" #\a)
12745 @result{} (#u8() #u8(98 114) #u8(99) #u8(100) #u8(98 114) #u8())
12746 (bytestring-split #u8"abracadabra" #\a 'prefix)
12747 @result{} (#u8(98 114) #u8(99) #u8(100) #u8(98 114) #u8())
12748 (bytestring-split #u8"abracadabra" #\a 'suffix)
12749 @result{} (#u8() #u8(98 114) #u8(99) #u8(100) #u8(98 114))
12750 @end example
12751 @end defun
12752
12753 @defun read-textual-bytestring prefix :optional port
12754 [SRFI-207]
12755 @c MOD srfi.207
12756 This parses a textual representation of a bytestring read from
12757 @var{port} (defaults to the current input port) and returns a bytevector.
12758 If @var{prefix} is false, it assumes the preceding @code{"#u8"} has
12759 already been read. If the input can't be parsed as a valid
12760 textual representation of a bytestring, an error satisfying
12761 @code{bytestring-error?} is raised.
12762
12763 @example
12764 (with-input-from-string "#u8\"abc\\x80;\"" (cut read-textual-bytestring #t))
12765 @result{} #u8(97 98 99 128)
12766 @end example
12767 @end defun
12768
12769 @defun write-textual-bytestring bv :optional port
12770 [SRFI-207]
12771 @c MOD srfi.207
12772 Writes a bytevector @var{bv} in the textual representation to
12773 @var{port} (defaults to the current output port).
12774
12775 @example
12776 (write-textual-bytestring #u8(65 66 128 255 0))
12777 @result{} @r{prints} #u8"AB\x80;\xff;\x00;"
12778 @end example
12779 @end defun
12780
12781 @defun write-binary-bitestring port arg @dots{}
12782 [SRFI-207]
12783 @c MOD srfi.207
12784 @example
12785 Works like @code{(write-textual-bytestring (bytestring arg @dots{}) port)},
12786 but without creating the intermediate bytevector.
12787 If any arguments are invalid to construct a bytevector, an error
12788 satisfying @code{bytestring-error?} signaled.
12789 @end example
12790 @end defun
12791
12792 @defun bytestring-error? obj
12793 [SRFI-207]
12794 @c MOD srfi.207
12795 Returns @code{#t} if @var{obj} is a condition thrown from
12796 bytestring operations.
12797 @end defun
12798
12799
12800 @c ----------------------------------------------------------------------
12801 @node Enums and enum sets, Procedures and syntax for multiple values, String-notated bytevectors, Library modules - SRFIs
12802 @section @code{srfi.209} - Enums and enum sets
12803 @c NODE enumとenum集合, @code{srfi.209} - enumとenum集合
12804
12805 @deftp {Module} srfi.209
12806 @mdindex srfi.209
12807 Enums are objects to represent a finite set of options. Traditionally
12808 Lisp-family languages have used symbols or keywords for the purpose,
12809 but it is error prone that you can pass arbitrary symbols which can only
12810 be checked at runtime.
12811
12812 The enums in this srfi allows the user to define and use enums statically,
12813 that is, checked at macro-expansion time.
12814
12815 There are three kind of objects involved in the enum system:
12816
12817 @table @strong
12818 @item Enum type
12819 An enum type defines all possible enums that can belong to the type.
12820 It can be created at macro-expansion time with @code{define-enum},
12821 or at run-time with @code{make-enum-type}. It is an immutable object.
12822 @item Enum
12823 An enum is an object that belong to a certain enum type. Each enum
12824 has a name (a symbol unique within the enum type),
12825 an ordinal (nonnegative contiguous exact integer), and
12826 a value (arbitrary Scheme value, defaults to the name).
12827 Enums are instantiated at the same time as an enum type is instantiated.
12828 It is also an immutable object.
12829 @item Enum set
12830 An enum set is a subset of enums from the enums in a certain enum type.
12831 An efficient set operation over an enum set is provided.
12832 @end table
12833 @end deftp
12834
12835 @subheading Enum types
12836
12837 @defmac define-enum type-name (name-value @dots{}) make-set
12838 [SRFI-209]
12839 @c MOD srfi.209
12840 The high-level declarative interface. This defines a new
12841 enum type and interface macros.
12842
12843 The enums the enum type contains are specified with @var{name-value} @dots{},
12844 each of which must be either a symbol, or a form @code{(symbol value)}.
12845 If it is a symbol, it is used both as the enum name and its value.
12846 If it is @code{(symbol value)}, the symbol is used as the enum name
12847 and the value is used as its value.
12848
12849 The @var{type-name} argument must be an identifier and
12850 is bound to a macro, which takes a single
12851 symbol as an argument. When invoked, it expands into an enum object.
12852
12853 The @var{make-set} argument must also be an identifier and
12854 is bound to a macro, which takes zero or more symbols and
12855 expands into an enum set object.
12856
12857 Since @var{type-name} and @var{make-set} are macros, the given enum name(s)
12858 can be statically checked at expansion time.
12859
12860 @example
12861 (define-enum fruits (apple orange banana mango papaya) fruit-set)
12862
12863 (fruits apple) @result{} #<enum apple>
12864 (fruits mango) @result{} #<enum mango>
12865
12866 (fruit-set oragne mango papaya)
12867 @result{} #<enum-set fruits (orange mango papaya)>
12868 @end example
12869 @end defmac
12870
12871 @defun make-enum-type list :optional name
12872 [SRFI-209]
12873 @c MOD srfi.209
12874 A procedural interface to create enum type and associated enums.
12875
12876 This procdure first creates enums according to @var{list}.
12877 Each element
12878 must be either a symbol, or a form @code{(symbol value)}.
12879 If it's the former, the symbol is used both as the enum name and
12880 its value. If it's the latter, the symbol is used as the enum name
12881 and the value is used as its value.
12882 Note that enum objects can only be created with this procedure
12883 (or the high-level macro) along with an enum type.
12884
12885 Each enum also gets a nonnegative integer @var{ordinal}, in the
12886 order of @var{list}, starting from zero.
12887
12888 The optional @var{name} argument is a Gauche's extension. It attaches
12889 @var{name} to the created enum-type. It is only for debugging aid,
12890 and printed when you write the enum type.
12891
12892 Enum type is immutable. Once created, its enum members cannot be changed.
12893
12894 @example
12895 (make-enum-type '(one two three))
12896 @result{} #<enum-type (one ...)>
12897 (make-enum-type '(one two three) 'counts)
12898 @result{} #<enum-type counts>
12899 @end example
12900 @end defun
12901
12902 @defun enum-type? obj
12903 [SRFI-209]
12904 @c MOD srfi.209
12905 Returns @code{#t} if @var{obj} is an enum-type, @code{#f} otherwise.
12906 @end defun
12907
12908 @defun enum-type-size etype
12909 [SRFI-209]
12910 @c MOD srfi.209
12911 Returns the number of enums the enum type @var{etype} has.
12912 @end defun
12913
12914 @defun enum-min etype
12915 @defunx enum-max etype
12916 [SRFI-209]
12917 @c MOD srfi.209
12918 Returns the minimun and maximum enum the enum type @var{etype} has.
12919
12920 @example
12921 (define fruits (make-enum-type '(apple orange banana mango papaya)))
12922
12923 (enum-min fruits) @result{} #<enum apple>
12924 (enum-max fruits) @result{} #<enum papaya>
12925 @end example
12926
12927 They throw an error if @var{etype} has no enums.
12928 @end defun
12929
12930 @defun enum-type-enums etype
12931 [SRFI-209]
12932 @c MOD srfi.209
12933 Returns a list of enums the enum type @var{etype} has, in the order
12934 of their ordinals.
12935
12936 @example
12937 (define fruits (make-enum-type '(apple orange banana mango papaya)))
12938
12939 (enum-type-enums fruits)
12940 @result{} (#<enum apple> #<enum orange> #<enum banana>
12941 #<enum mango> #<enum papaya>)
12942 @end example
12943 @end defun
12944
12945 @defun enum-type-names etype
12946 [SRFI-209]
12947 @c MOD srfi.209
12948 Returns a list of names of enums the enum type @var{etype} has, in the order
12949 of their ordinals.
12950
12951 @example
12952 (define fruits (make-enum-type '(apple orange banana mango papaya)))
12953
12954 (enum-type-names fruits)
12955 @result{} (apple orange banana mango papaya)
12956 @end example
12957 @end defun
12958
12959 @defun enum-type-values etype
12960 [SRFI-209]
12961 @c MOD srfi.209
12962 Returns a list of the values of the enums the enum type @var{etype} has,
12963 in the order of their ordinals.
12964 @end defun
12965
12966 @defun enum-type-contains? etype enum
12967 [SRFI-209]
12968 @c MOD srfi.209
12969 Returns @code{#t} iff enum type @var{etype} contains @var{enum},
12970 @code{#f} otherwise.
12971 @end defun
12972
12973 @defun enum-name->enum etype symbol
12974 [SRFI-209]
12975 @c MOD srfi.209
12976 Returns an enum object in @var{etype} whose name is @var{symbol}.
12977 If @var{etype} doesn't have an enum of such name, @code{#f} is returned.
12978 @end defun
12979
12980 @defun enum-ordinal->enum etype n
12981 [SRFI-209]
12982 @c MOD srfi.209
12983 Returns @var{n}-th enum of @var{etype}.
12984 If @var{n} is over the range of enums in @var{etype}, @code{#f} is returned.
12985 @end defun
12986
12987 @defun enum-name->ordinal etype symbol
12988 [SRFI-209]
12989 @c MOD srfi.209
12990 Returns the ordinal of the enum in @var{etype} whose name is @var{symbol}.
12991 An error is thrown if @var{etype} doesn't have such symbol.
12992 @end defun
12993
12994 @defun enum-name->value etype symbol
12995 [SRFI-209]
12996 @c MOD srfi.209
12997 Returns the value of the enum in @var{etype} whose name is @var{symbol}.
12998 An error is thrown if @var{etype} doesn't have such symbol.
12999 @end defun
13000
13001 @defun enum-ordinal->name etype n
13002 [SRFI-209]
13003 @c MOD srfi.209
13004 Returns the name of the @var{n}-th enum of @var{etype}.
13005 An error is thrown if @var{n} is out of the range.
13006 @end defun
13007
13008 @defun enum-ordinal->value etype n
13009 [SRFI-209]
13010 @c MOD srfi.209
13011 Returns the value of the @var{n}-th enum of @var{etype}.
13012 An error is thrown if @var{n} is out of the range.
13013 @end defun
13014
13015 @defun make-enum-comparator etype
13016 [SRFI-209]
13017 @c MOD srfi.209
13018 Returns a comparator that can compare two enums that belong to @var{etype}.
13019 @xref{Comparators}, for the details of comparators.
13020 @end defun
13021
13022 @subheading Enums
13023
13024 @defun enum-type enum
13025 @defunx enum-name enum
13026 @defunx enum-ordinal enum
13027 @defunx enum-value enum
13028 [SRFI-209]
13029 @c MOD srfi.209
13030 Returns enum's type (@code{<enum-type>} instance), enum's name (symbol),
13031 enum's ordinal (nonnegative exact integer), and enum's value (any object),
13032 respectively.
13033
13034 Note that enum objects can only be constructed with the enum type
13035 it belongs (by @code{define-enum} or @code{make-enum-type}), and
13036 they are immutable.
13037 @end defun
13038
13039 @defun enum? obj
13040 [SRFI-209]
13041 @c MOD srfi.209
13042 Returns @code{#t} if @var{obj} is an enum, @code{#f} otherwise.
13043 @end defun
13044
13045 @defun enum=? enum0 enum1 enums ...
13046 @defunx enum<? enum0 enum1 enums ...
13047 @defunx enum<=? enum0 enum1 enums ...
13048 @defunx enum>? enum0 enum1 enums ...
13049 @defunx enum>=? enum0 enum1 enums ...
13050 [SRFI-209]
13051 @c MOD srfi.209
13052 These comapres enums by its ordinals. All the enums must belong
13053 to the same enum type, or an error is thrown.
13054 @end defun
13055
13056 @defun enum-next enum
13057 [SRFI-209]
13058 @c MOD srfi.209
13059 Returns the next enum of @var{enum}, that is,
13060 an enum that belongs to the same enum type as @var{enum} and
13061 has an incremented ordinal. If @var{enum} is the last enum of
13062 its type, @code{#f} is returned.
13063 @end defun
13064
13065 @defun enum-prev enum
13066 [SRFI-209]
13067 @c MOD srfi.209
13068 Returns the previous enum of @var{enum}, that is,
13069 an enum that belongs to the same enum type as @var{enum} and
13070 has a decremented ordinal. If @var{enum} is the first enum of
13071 its type, @code{#f} is returned.
13072 @end defun
13073
13074 @subheading Enum sets
13075
13076 @defun enum-type->enum-set etype
13077 [SRFI-209]
13078 @c MOD srfi.209
13079 Returns an enum set that contains all enums in the enum type @var{etype}.
13080 @end defun
13081
13082 @defun enum-set etype enum @dots{}
13083 [SRFI-209]
13084 @c MOD srfi.209
13085 Returns an enum set that contains @var{enum} @dots{} of an enum type
13086 @var{etype}. An error is thrown unless all @var{enum} @dots{} belong
13087 to @var{etype}.
13088 @end defun
13089
13090 @defun enum-empty-set etype
13091 [SRFI-209]
13092 @c MOD srfi.209
13093 Returns an empty enum set for the enum type @var{etype}.
13094 @end defun
13095
13096 @defun list->enum-set etype enum-list
13097 [SRFI-209]
13098 @c MOD srfi.209
13099 Returns an enum set of an enum type @var{etype}, contaning enums
13100 listed in @var{enum-list}. If @var{enum-list} contains anything
13101 other than enums from @var{etype}, an error is thrown.
13102 @end defun
13103
13104 @defun enum-set-projection etype-or-eset eset
13105 [SRFI-209]
13106 @c MOD srfi.209
13107 The @var{etype-or-eset} argument must be an enum type or an enum set.
13108 Returns a new enum set on an enum type @var{etype-or-eset} (if it is
13109 an enum set, its enum type is used), which contains enums
13110 having the same names as the names of enums contained in @var{eset}.
13111 The @var{eset}'s enum type doesn't need to be the same as the
13112 result enum set.
13113 @end defun
13114
13115 @defun enum-set-copy eset
13116 [SRFI-209]
13117 @c MOD srfi.209
13118 Returns a copy of an enum set @var{eset}.
13119 @end defun
13120
13121 @defun enum-set? obj
13122 [SRFI-209]
13123 @c MOD srfi.209
13124 Returns @code{#t} if @var{obj} is an enum set, @code{#f} otherwise.
13125 @end defun
13126
13127 @defun enum-set-contains? eset enum
13128 [SRFI-209]
13129 @c MOD srfi.209
13130 Returns @code{#t} if @var{enum} is a member of @var{eset}, @code{#f} otherwise.
13131 @end defun
13132
13133 @defun enum-set-empty? eset
13134 [SRFI-209]
13135 @c MOD srfi.209
13136 Returns a@code{#t} if @var{eset} is empty.
13137 @end defun
13138
13139 @defun enum-set-disjoint? eset1 eset2
13140 [SRFI-209]
13141 @c MOD srfi.209
13142 Returns @var{#t} if two enum sets on the same enum type share
13143 no common enums. An error is thrown unless @var{eset1} and @var{eset2}
13144 are for the same enum type..
13145 @end defun
13146
13147 @defun enum-set=? eset1 eset2
13148 @defunx enum-set<? eset1 eset2
13149 @defunx enum-set<=? eset1 eset2
13150 @defunx enum-set>? eset1 eset2
13151 @defunx enum-set>=? eset1 eset2
13152 [SRFI-209]
13153 @c MOD srfi.209
13154 This determines subset relationship of two enum sets. Both enum sets
13155 must be for the same enum type, or an error is thrown.
13156 @end defun
13157
13158 @defun enum-set-subset? eset1 eset2
13159 [SRFI-209]
13160 @c MOD srfi.209
13161 Returns @code{#t} if the @emph{names} of the member of enum set @var{eset1}
13162 is a subset of the names of the member of @var{eset2}. Otherwise
13163 returns @code{#f}. Unlike @code{enum-set<?}, two enum set can be
13164 of different enum types. Comparison is done with the names only.
13165 @end defun
13166
13167 @defun enum-set-any? pred eset
13168 @defunx enum-set-every? pred eset
13169 [SRFI-209]
13170 @c MOD srfi.209
13171 Returns @code{#t} if any or every application of @var{proc} to the
13172 elemens of enum set @var{eset} yields true. Otherwise returns @code{#f}.
13173 @end defun
13174
13175 @defun enum-set-type eset
13176 [SRFI-209]
13177 @c MOD srfi.209
13178 Returns the enum type of the enum set @var{eset}.
13179 @end defun
13180
13181 @defun enum-set-size eset
13182 [SRFI-209]
13183 @c MOD srfi.209
13184 Returns the number of elements in the enum set @var{eset}.
13185 @end defun
13186
13187 @defun enum-set->enum-list eset
13188 [SRFI-209]
13189 @c MOD srfi.209
13190 Returns a list of enums contained in the enum set @var{eset},
13191 in the increasing order of enumcs.
13192 @end defun
13193
13194 @defun enum-set-adjoin eset enum @dots{}
13195 @defunx enum-set-adjoin! eset enum @dots{}
13196 [SRFI-209]
13197 @c MOD srfi.209
13198 Returns an enum set that contains all the members in the enum set @var{eset}
13199 plus @var{enum} @dots{}. All @var{enum}s must belong to the same enum type
13200 of @var{eset}.
13201
13202 The linear update version @code{enum-set-adjoin!} may modify @var{eset}
13203 to produce the result.
13204 @end defun
13205
13206 @defun enum-set-delete eset enum @dots{}
13207 @defunx enum-set-delete! eset enum @dots{}
13208 [SRFI-209]
13209 @c MOD srfi.209
13210 Returns an enum set that contains all the members in the enum set @var{eset}
13211 except @var{enum} @dots{}. All @var{enum}s must belong to the same enum type
13212 of @var{eset}.
13213
13214 The linear update version @code{enum-set-delete!} may modify @var{eset}
13215 to produce the result.
13216 @end defun
13217
13218 @defun enum-set-delete-all eset list @dots{}
13219 @defunx enum-set-delete-all! eset list @dots{}
13220 [SRFI-209]
13221 @c MOD srfi.209
13222 Returns an enum set that contains all the members in the enum set @var{eset}
13223 the enums in @var{list}. An error is thrown if
13224 @var{list} contains non-enums, or enums that do not belong to the same
13225 enum type of @var{eset}.
13226
13227 The linear update version @code{enum-set-delete-all!} may modify @var{eset}
13228 to produce the result.
13229 @end defun
13230
13231 @defun enum-set-count pred eset
13232 [SRFI-209]
13233 @c MOD srfi.209
13234 Applies @var{pred} on each enum in @var{eset}, and returns the number
13235 of times when @var{pred} yields a true value.
13236 @end defun
13237
13238 @defun enum-set-filter pred eset
13239 @defunx enum-set-remove pred eset
13240 [SRFI-209]
13241 @c MOD srfi.209
13242 Returns a new enum set that contains the enums that satisfy or
13243 do not satisfy @var{pred}.
13244 @end defun
13245
13246 @defun enum-set-map->list proc eset
13247 [SRFI-209]
13248 @c MOD srfi.209
13249 Applies @var{proc} on each enum in @var{eset},
13250 and returns a list of the results, in the increasing order of enums.
13251 @end defun
13252
13253 @defun enum-set-for-each proc eset
13254 [SRFI-209]
13255 @c MOD srfi.209
13256 Applies @var{proc} on each enum in @var{eset} in the increasing order.
13257 The results of @var{proc} are discarded.
13258 @end defun
13259
13260 @defun enum-set-fold kons knil eset
13261 [SRFI-209]
13262 @c MOD srfi.209
13263 For each enum in @var{eset},
13264 apply @var{kons} on it and the current
13265 state value, whose initial value is @var{knil}. The result
13266 of @var{kons} is used as the state value of the next iteration.
13267 The last result of @var{kons} is returned.
13268 The @var{eset} is traversed in increasing order.
13269 @end defun
13270
13271 @defun enum-set-complement eset
13272 @defunx enum-set-complement! eset
13273 [SRFI-209]
13274 @c MOD srfi.209
13275 Returns an enum set of the same enum type as @var{eset}, but
13276 contains enums that are not contained in @var{eset}.
13277 The linear updating version @code{enum-set-complement!} may reuse
13278 the storage of @var{eset}.
13279 @end defun
13280
13281 @defun enum-set-union eset1 eset2
13282 @defunx enum-set-union! eset1 eset2
13283 [SRFI-209]
13284 @c MOD srfi.209
13285 Two enum sets must be of the same enum type.
13286 Returns an enum set of the same type
13287 that contains enums each of which is in at least
13288 either of @var{eset1} or @var{eset2}.
13289 The linear updating version @code{enum-set-union!} may reuse
13290 the storage of @var{eset1}.
13291 @end defun
13292
13293 @defun enum-set-intersection eset1 eset2
13294 @defunx enum-set-intersection! eset1 eset2
13295 [SRFI-209]
13296 @c MOD srfi.209
13297 Two enum sets must be of the same enum type.
13298 Returns an enum set of the same type
13299 that contains enums each of which is in both
13300 @var{eset1} and @var{eset2}.
13301 The linear updating version @code{enum-set-intersection!} may reuse
13302 the storage of @var{eset1}.
13303 @end defun
13304
13305 @defun enum-set-difference eset1 eset2
13306 @defunx enum-set-difference! eset1 eset2
13307 [SRFI-209]
13308 @c MOD srfi.209
13309 Two enum sets must be of the same enum type.
13310 Returns an enum set of the same type
13311 that contains enums each of which is in @var{eset1}
13312 but not in @var{eset2}.
13313 The linear updating version @code{enum-set-difference!} may reuse
13314 the storage of @var{eset1}.
13315 @end defun
13316
13317 @defun enum-set-xor eset1 eset2
13318 @defunx enum-set-xor! eset1 eset2
13319 [SRFI-209]
13320 @c MOD srfi.209
13321 Two enum sets must be of the same enum type.
13322 Returns an enum set of the same type
13323 that contains enums each of which is in either @var{eset1}
13324 or @var{eset2}, but not both.
13325 The linear updating version @code{enum-set-xor!} may reuse
13326 the storage of @var{eset1}.
13327 @end defun
13328
13329 @subheading R6RS enumeration compatibility
13330
13331 R6RS also has enumerations, but it does not have separate @emph{enum} object,
13332 nor explicitly deal with enum types.
13333 Symbols are used to represent each enum, and enum types are
13334 implicitly dealt with enum sets.
13335
13336 @defmac define-enumeration type-name (name-value @dots{}) make-set
13337 [SRFI-209]
13338 @c MOD srfi.209
13339 Creates a new enum type and defines a macro named @var{type-name}
13340 and @var{make-set}. VEry similar to @code{define-enum}, except that
13341 the macro invocation @code{(@var{type-name} @var{symbol})} returns
13342 the symbol itself instead of an enum object.
13343 @end defmac
13344
13345 @defun make-enumeration symbol-list
13346 [SRFI-209]
13347 @c MOD srfi.209
13348 Creates a new enum type with the enums each of which has the name
13349 given in @var{symbol-list}. Returns a fresh enum set containing
13350 all the enums. The created enum type ca be obtained with
13351 @code{enum-set-type}.
13352 @end defun
13353
13354 @defun enum-set-universe eset
13355 [SRFI-209]
13356 @c MOD srfi.209
13357 Returns a fresh enum set that contains all the enums of the enum type
13358 of the given enum set @var{eset}.
13359 It is basically @code{(enum-type->enum-set (enum-set-type eset))}.
13360 @end defun
13361
13362 @defun enum-set-costructor eset
13363 [SRFI-209]
13364 @c MOD srfi.209
13365 Returns a procedure that accepts a list of symbols as an argument,
13366 and returns a fresh enum set that contains the enums whose names
13367 are given in the list.
13368 @end defun
13369
13370 @defun enum-set-member? symbol eset
13371 [SRFI-209]
13372 @c MOD srfi.209
13373 Returns @code{#t} if @var{symbol} is the name of a member of @var{eset},
13374 or @code{#f} @var{symbol} is a valid name of the enum type of
13375 @var{eset} but not in @var{eset}. An error is signaled
13376 if @var{symbol} is not a valid name of enums in the enum type.
13377 @end defun
13378
13379 @defun enum-set-indexer eset
13380 [SRFI-209]
13381 @c MOD srfi.209
13382 Returns a procedure that takes one argument, a symbol, and
13383 returns the ordinal of the enum that has the given symbol as a name.
13384 If the given symbol is not a name of any enums in the enum type
13385 of @var{eset}, @code{#f} is returned. Note that the enum with the
13386 given symbol does not need to be in @var{eset}; basically, @var{eset}
13387 is used only to obtain the enum type.
13388 @end defun
13389
13390 @defun enum-set->list eset
13391 [SRFI-209]
13392 @c MOD srfi.209
13393 Returns a list of the names of the members of @var{eset}.
13394 Same as @code{(map enum-name (enum-set->enum-list eset))}.
13395 @end defun
13396
13397 @c ----------------------------------------------------------------------
13398 @node Procedures and syntax for multiple values, Central log exchange, Enums and enum sets, Library modules - SRFIs
13399 @section @code{srfi.210} - Procedures and syntax for multiple values
13400 @c NODE 多値のための手続きと構文, @code{srfi.210} - 多値のための手続きと構文
13401
13402 @deftp {Module} srfi.210
13403 @mdindex srfi.210
13404 @c EN
13405 This module provides macros and procedures to blend multiple-value
13406 expressions naturally into the orinary single-value expressions.
13407 @c JP
13408 このモジュールは、複数の値を返す式を通常の単一の値を扱う式にうまく混ぜて使えるようにする
13409 マクロや手続きを提供します。
13410 @c COMMON
13411 @end deftp
13412
13413 @defmac with-values producer consumer
13414 [SRFI-210]
13415 @c MOD srfi.210
13416 @c EN
13417 A shorthand notation of @code{(call-with-values (^[] producer) consumer)}.
13418 @c JP
13419 @code{(call-with-values (^[] producer) consumer)}の略記です。
13420 @c COMMON
13421 @end defmac
13422
13423 @defmac case-receive producer clause @dots{}
13424 [SRFI-210]
13425 @c MOD srfi.210
13426 @c EN
13427 A shorthand notation of
13428 @code{(with-values producer (case-lambda clause @dots{}))}.
13429 @c JP
13430 @code{(with-values producer (case-lambda clause @dots{}))}の略記です。
13431 @c COMMON
13432 @end defmac
13433
13434 @defmac apply/mv operator operand @dots{} producer
13435 [SRFI-210]
13436 @c MOD srfi.210
13437 @c EN
13438 Similar to @code{apply}, but the multiple values yielded
13439 from the last argument (@var{producer}) is turned into the tail of
13440 the argument list; that is,
13441 @code{(apply operator operand @dots{} (values->list producer))}.
13442 @c JP
13443 @code{apply}と似ていますが、最後の引数@var{producer}は複数の値を返すことができ、
13444 それが@var{operator}への引数リストの末尾に付け加えられます。
13445 つまり@code{(apply operator operand @dots{} (values->list producer))}と同じです。
13446 @c COMMON
13447 @end defmac
13448
13449 @defmac call/mv proc producer @dots{}
13450 [SRFI-210]
13451 @c MOD srfi.210
13452 @c EN
13453 Calls @var{proc} with the argument produced by the expression
13454 @var{producer} @dots{} and 'splicing' their result(s) into a single
13455 argument list.
13456 @c JP
13457 @var{producer} @dots{}の各式が返す多値をリストにしてつなぎあわせたものを
13458 引数リストにして@var{proc}を呼び出します。
13459 @c COMMON
13460
13461 @example
13462 (call/mv list (values 1 2 3) (values 4 5 6))
13463 @result{} (1 2 3 4 5 6)
13464 @end example
13465 @end defmac
13466
13467 @defmac list/mv element @dots{} producer
13468 @defmacx vector/mv element @dots{} producer
13469 @defmacx box/mv element @dots{} producer
13470 [SRFI-210]
13471 @c MOD srfi.210
13472 @c EN
13473 Returns a list, a vector, or a box, consisting of @var{element} @dots{}
13474 and the value(s) produced by @var{producer}.
13475 @c JP
13476 @var{element} @dots{}および、@var{producer}が返す多値のそれぞれを要素とする
13477 リスト、ベクタ、ボックスを作って返します。
13478 @c COMMON
13479
13480 @c EN
13481 Single-argument @code{list/mv} is the same as Gauche's @code{values->list}
13482 (@pxref{Multiple values}).
13483 @c JP
13484 @code{list/mv}に引数をひとつだけ渡した場合は、Gauche組み込みの@code{values->list}
13485 と同じです(@ref{Multiple values}参照)。
13486 @c COMMON
13487
13488 @example
13489 (list/mv 1 2 (values 3 4 5)) @result{} (1 2 3 4 5)
13490 (vector/mv 1 2 (values 3 4 5)) @result{} #(1 2 3 4 5)
13491 (box/mv 1 2 (values 3 4 5)) @result{} #<mv-box[5] 1 2 3 4 5>
13492 @end example
13493 @end defmac
13494
13495 @defmac value/mv index element @dots{} producer
13496 [SRFI-210]
13497 @c MOD srfi.210
13498 @c EN
13499 Returns the same value as
13500 @code{(list-ref (list/mv element @dots{} producer) index)}.
13501 @c JP
13502 @code{(list-ref (list/mv element @dots{} producer) index)}と同じ値を返します。
13503 @c COMMON
13504
13505 @c EN
13506 With no @var{element} @dots{}, it is the same as Gauche's @code{values-ref}
13507 (@pxref{Multiple values}) except the argument order.
13508 @c JP
13509 @var{element} @dots{}が無い場合は、Gauche組み込みの@code{values-ref}の
13510 引数順をひっくり返したものになります(@ref{Multiple values}参照)。
13511 @c COMMON
13512 @end defmac
13513
13514 @defmac coarity producer
13515 [SRFI-210]
13516 @c MOD srfi.210
13517 @c EN
13518 Evaluate @var{producer}, and returns the number of values it yielded.
13519 @c JP
13520 @var{producer}を評価し、結果の値の数を返します。
13521 @c COMMON
13522 @end defmac
13523
13524 @defmac bind/mv producer transducer @dots{}
13525 [SRFI-210]
13526 @c MOD srfi.210
13527 @c EN
13528 Evaluate @var{producer}, and passes its results to the first @var{transducer}
13529 as arguments. The values returned by the first @var{transducer}
13530 are passed to the next @var{transducer} as arguments, and so on.
13531 Returns the results of the last @var{transducer}.
13532 The call to the last @var{transducer} is tail-call.
13533 @c JP
13534 @var{producer}を評価し、その結果の値(複数かもしれない)を引数として
13535 最初の@var{transducer}を呼びます。それが値(複数かもしれない)を返したらそれらを
13536 引数として二番目の@var{transducer}を呼び、以下同様にして最後の@var{transducer}が
13537 返す値(複数かもしれない)を返します。最後の@var{transducer}は末尾呼び出しされます。
13538 @c COMMON
13539
13540 @c EN
13541 If no @var{transducer}s are given, it returns the results of
13542 @var{producer}.
13543 @c JP
13544 @var{transducer}が与えられなければ、@var{producer}の結果の値(複数かもしれない)が
13545 そのまま返されます。
13546 @c COMMON
13547 @end defmac
13548
13549 @defun list-values lis
13550 @defunx vector-values vec
13551 @defunx box-values box
13552 [SRFI-210]
13553 @c MOD srfi.210
13554 @c EN
13555 Turn the content of @var{lis}, @var{vec} or @var{box} into multiple values.
13556 @c JP
13557 リスト@var{lis}、ベクタ@var{vec}、ボックス@var{box}の中身を複数の値として返します。
13558 @c COMMON
13559
13560 @c EN
13561 Note that @code{box-values} is the same as @code{unbox}, but provided here
13562 for the naming consistency (@pxref{Boxes}).
13563 @c JP
13564 @code{box-values}は@code{unbox}と同じですが、
13565 名前付けの一貫性のために用意されています (@ref{Boxes}参照)。
13566 @c COMMON
13567 @end defun
13568
13569 @defun value index obj @dots{}
13570 [SRFI-210]
13571 @c MOD srfi.210
13572 @c EN
13573 Returns the @var{index}-th value of @var{obj} @dots{}.
13574 @c JP
13575 @var{obj} @dots{}の@var{index}番目の値を返します。
13576 @c COMMON
13577 @end defun
13578
13579 @defun identity obj @dots{}
13580 [SRFI-210]
13581 @c MOD srfi.210
13582 @c EN
13583 Synonym of @code{values}. Note that this is different from
13584 Gauche's built-in @code{identity}, which takes exactly one argument
13585 (@pxref{Combinators}).
13586 @c JP
13587 @code{values}と同じです。
13588 Gaucheの組み込みの@code{identity}はこれと違い正確に一つの値だけを取ることに
13589 注意してください (@ref{Combinators}参照)。
13590 @c COMMON
13591 @end defun
13592
13593 @defun compose-left transducer @dots{}
13594 [SRFI-210]
13595 @c MOD srfi.210
13596 @c EN
13597 Each @var{transducer} must be a procedure.
13598 Returns a procedure that applies the first @var{transducer} to its
13599 arguments, then applies the next @var{transducer} to the result(s)
13600 of the first one, and so on. Returns the result(s) returned from
13601 the last @var{transducer}. If no @var{tranducer}s are given,
13602 returned procedure is the same as @code{values}.
13603 @c JP
13604 各@var{transducer}は手続きでなければなりません。
13605 合成された手続きを返します。その手続きは、渡された引数をまず最初の@var{transducer}
13606 に渡し、その結果(複数かもしれない)を次の@var{transducer}に渡し、ということを続けて
13607 最後の@var{transducer}の結果(複数かもしれない)を返します。
13608 @var{tranducer}がひとつも渡されない場合は@code{values}と同じです。
13609 @c COMMON
13610
13611 @c EN
13612 This can be written using Gauche's built-in @code{compose} as follows
13613 (@pxref{Combinators}):
13614 @c JP
13615 これはGauche組み込みの@code{compose}を使って次のように書けます(@ref{Combinators}参照)。
13616 @c COMMON
13617
13618 @example
13619 (define (compose-left . procs) (apply compose (reverse procs)))
13620 @end example
13621 @end defun
13622
13623 @defun compose-right transducer @dots{}
13624 [SRFI-210]
13625 @c MOD srfi.210
13626 @c EN
13627 Each @var{transducer} must be a procedure.
13628 Returns a procedure that applies the last @var{transducer} to its
13629 arguments, then applies the previous @var{transducer} to the result(s)
13630 of the last one, and so on. Returns the result(s) returned from
13631 the first @var{transducer}. If no @var{tranducer}s are given,
13632 returned procedure is the same as @code{values}.
13633 @c JP
13634 各@var{transducer}は手続きでなければなりません。
13635 合成された手続きを返します。その手続きは、渡された引数をまず最後の@var{transducer}
13636 に渡し、その結果(複数かもしれない)をひとつ前の@var{transducer}に渡し、ということを続けて
13637 最初の@var{transducer}の結果(複数かもしれない)を返します。
13638 @var{tranducer}がひとつも渡されない場合は@code{values}と同じです。
13639 @c COMMON
13640
13641 @c EN
13642 This is the same as Gauche's built-in @code{compose}
13643 (@pxref{Combinators}).
13644 @c JP
13645 これはGauche組み込みの@code{compose}と同じです(@ref{Combinators}参照)。
13646 @c COMMON
13647 @end defun
13648
13649 @defun map-values proc
13650 [SRFI-210]
13651 @c MOD srfi.210
13652 @c EN
13653 Returns a procedure that takes any number of arguments, applys @var{proc}
13654 on each argument, and returns the results as multiple values.
13655 The behavior is undefined if @var{proc} doesn't return a single value.
13656 @c JP
13657 手続きを作って返します。その手続きは、任意個の引数を取り、それぞれに@var{proc}を適用して、
13658 その結果を多値として返すものです。
13659 @var{proc}が一つ以外の値を返した場合の動作は未定義です。
13660 @c COMMON
13661
13662 @example
13663 ((map-values (cut + <> 1)) 1 2 3)
13664 @result{} 2, 3, 4
13665 @end example
13666 @end defun
13667
13668 @defun bind/list lis transducer @dots{}
13669 @defunx bind/box box transducer @dots{}
13670 @defunx bind obj transducer @dots{}
13671 [SRFI-210]
13672 @c MOD srfi.210
13673 @c EN
13674 These are @emph{bind} operation in Monads. The first argument
13675 is the source of data; they're first expanded into values (for
13676 @code{bind/list}, each element of @var{lis} is taken; for @code{bind/box},
13677 it is unboxed, and for @code{bind}, @var{obj} is the singleton value).
13678 Those values are passed as arguments to the first @var{transducer},
13679 and its result(s) are passed as argumenst to the second @var{transducer}
13680 and so on. The value(s) returned by the last @var{transducer} becomes
13681 the result(s) of those procedures. These can be written using
13682 @code{compose-left} and procedure application:
13683 @c JP
13684 これらはモナドのbindです。最初の引数はデータのソースで、それぞれが多値へと展開されます
13685 (@code{bind/list}ではリスト@var{lis}の各要素が多値に、
13686 @code{bind/box}ではボックス@var{box}の各要素が多値に、
13687 @code{bind}では@var{obj}が唯一の値になります)。
13688 それが引数として最初の@var{transducer}に渡されます。
13689 その結果(複数かもしれない)が次の@var{transducer}に渡されます。
13690 そうしていって最後の@var{transducer}の返す値(複数かもしれない)が全体の結果となります。
13691 これらは@code{compose-left}を使って次のとおり書けます。
13692 @c COMMON
13693
13694 @example
13695 (bind/list lis proc @dots{})
13696 @equiv{} (apply (compose-left proc @dots{}) lis)
13697 (bind/box box proc @dots{})
13698 @equiv{} (apply/mv (compose-left proc @dots{}) (unbox box))
13699 (bind obj proc @dots{})
13700 @equiv{} ((compose-left proc @dots{}) obj)
13701 @end example
13702 @end defun
13703
13704 @c ----------------------------------------------------------------------
13705 @node Central log exchange, SICP prerequisites, Procedures and syntax for multiple values, Library modules - SRFIs
13706 @section @code{srfi.215} - Central log exchange
13707 @c NODE 中央ログ交換局, @code{srfi.215} - 中央ログ交換局
13708
13709 @deftp {Module} srfi.215
13710 @mdindex srfi.215
13711 @c EN
13712 This module abstracts a logging mechanism so that the code
13713 can produce log messages in the same way regardless of
13714 the underlying log system.
13715
13716 In Gauche, the default logging system is set to use @code{gauche.logger}
13717 (@pxref{User-level logging}). For Gauche-specific code,
13718 you can directly use @code{gauche.logger}. This module is convenient
13719 when you're writing portable code.
13720 @c JP
13721 このモジュールはログ機構を抽象化して、具体的にどういうログシステムが使われているかに
13722 かかわらず統一的な方法でログメッセージを送り出す方法を提供します。
13723
13724 Gaucheでは、デフォルトのログシステムは@code{gauche.logger}を使うように設定してあります
13725 (@pxref{User-level logging})。
13726 Gauche特定のコードを書いているなら@code{gauche.logger}を直接使っても良いでしょう。
13727 このモジュールはポータブルなコードを書く場合に便利です。
13728 @c COMMON
13729 @end deftp
13730
13731 @deffn {Parameter} current-log-callback
13732 [SRFI-215]
13733 @c MOD srfi.215
13734 @c EN
13735 The value of this parameter must be a procedure that takes a single
13736 argument, a log message packet.
13737
13738 A log message packet is an alist, with symbols as keys. Their values can
13739 be a string, an exact integer, a bytevector (u8vector),
13740 or an instance of @code{<error>}. SRFI doesn't specify what
13741 will happen if other types of values are given. Gauche converts
13742 them to strings before this callback is called, but a portable program
13743 should avoid passing values other than listed above.
13744
13745 Two keys, @code{SEVERITY} and @code{MESSAGE}, are always present,
13746 with an exact integer value and a string as their values, respectively.
13747 The severity value is between 0 and 7, inclusive, and corresponding
13748 constans are defined; see below.
13749 Users can use other keys freely, though SRFI-215 suggests some
13750 common key names so check them up.
13751
13752 SRFI-215 also suggests that the default log callback procedure buffers
13753 log messages, and pass them to a user-provided callback when this
13754 parameter is set/rebound. In our implementation, the default
13755 callback directly sends logs to @code{log-format}
13756 (@pxref{User-level logging}), for your convenience.
13757 @c JP
13758 このパラメータの値は引数を一つ取る手続きでなければなりません。
13759 引数はログメッセージオブジェクトです。
13760
13761 ログメッセージオブジェクトは連想リストで、キーは常にシンボルです。
13762 値は、文字列、正確な整数、バイトベクタ(u8vector)、@code{<error>}のインスタンス、
13763 のいずれかです。SRFIではそれ以外の値が渡された場合の動作は規定されていません。
13764 Gaucheではそれ以外の値はコールバックに渡す前に文字列に変換しますが、
13765 ポータブルなプログラムでは上に列挙された値に留めておくべきです。
13766
13767 キー@code{SEVERITY}と@code{MESSAGE}は常に存在し、
13768 それぞれ正確な整数と文字列を値に持ちます。
13769 @code{SEVERITY}の値は0から7まで(両端含む)です。
13770 その意味を示す定数が定義されているので下のエントリを参照してください。
13771 ユーザはその他のキーを自由に使えます。
13772 ただ、SRFI-215はいくつかの共通するキーを提示しているので見ておくと良いでしょう。
13773
13774 SRFI-25はまた、デフォルトのコールバックはログメッセージをバッファし、
13775 このコールバックの値が変えられた時に貯められたメッセージを新たなコールバックに渡すことを
13776 提案mしています。
13777 しかし我々の実装では、デフォルトのコールバックは直接@code{log-format}に
13778 ログを流します (@ref{User-level logging}参照)。
13779 @c COMMON
13780
13781 @end deffn
13782
13783 @deffn {Parameter} current-log-fields
13784 [SRFI-215]
13785 @c MOD srfi.215
13786 @c EN
13787 This parameter holds a key-value list, @code{(key1 value1 key2 value2 @dots{})},
13788 that are automatically appended to the fields passed to @code{send-log}.
13789 The effect is as if that procedure was always invoked as
13790 @code{(apply send-log severity message key value ... (current-log-fields))}.
13791
13792 When you set/rebind this parameter, the passed value is validated
13793 to be a valid key-value arguments for @code{send-log}.
13794 @c JP
13795 このパラメータは@code{(key1 value1 key2 value2 @dots{})}の形のキー-値リストで、
13796 その内容が@code{send-log}が呼ばれた時にそのフィールドリストに自動的に付け加えられます。
13797 つまり、@code{send-log}は
13798 @code{(apply send-log severity message [key value] ... (current-log-fields))}
13799 と呼ばれたかのように振る舞うということです。
13800
13801 このパラメータをセット/再束縛した時点で、渡された値が@code{send-log}の引数として
13802 ふさわしいかどうかが検査されます。
13803 @c COMMON
13804 @end deffn
13805
13806 @defun send-log severity message @dots{}
13807 [SRFI-215]
13808 @c MOD srfi.215
13809 @c EN
13810 A single-stop API to construct a log message packet and dispatch to
13811 the current log callback.
13812
13813 The @var{severity} argument must be an exact integer between 0 and
13814 7, inclusive. It will be the value of @code{SEVERITY} key in the
13815 log message packet. There are constants defined for each severity
13816 value: @code{EMERGENCY}, @code{ALERT}, @code{CRITICAL}, @code{ERROR},
13817 @code{WARNING}, @code{NOTICE}, @code{INFO}, and @code{DEBUG}.
13818 The @var{message} argument is a string and
13819 will be the value of @code{MESSAGE} key in the log message packet.
13820
13821 The rest of the argument must be a key-value list.
13822 The @code{SEVERITY} and @code{MESSAGE} keys are prepended,
13823 and value of @code{current-log-fields} are appended,
13824 and the entire key-value list is converted to an alist
13825 to construct a log message packet.
13826 See @code{current-log-callback} above for the
13827 valid keys and values.
13828
13829 This procedure does not return a meaningful value.
13830 @c JP
13831 ログメッセージパケットを作って現在のログコールバックに送信します。
13832
13833 @var{severity}引数は0から7までの正確な整数でなければなりません。
13834 これはログメッセージパケットの@code{SEVERITY}キーに対する値となります。
13835 各値を意味する次の定数が定義されています:
13836 @code{EMERGENCY}、@code{ALERT}、@code{CRITICAL}、@code{ERROR}、
13837 @code{WARNING}、@code{NOTICE}、@code{INFO}、@code{DEBUG}。
13838 @var{message}引数は文字列で、ログメッセージパケットの
13839 @code{MESSAGE}キーに対する値となります。
13840
13841 残りの引数はキー-値リストです。これに@code{SEVERITY}と@code{MESSAGE}が
13842 前置され、@code{current-log-fields}の値が後置され、全体がalistに変換されて
13843 ログメッセージパケットとなります。有効なキーと値については
13844 上の@code{current-log-callback}を参照してください。
13845
13846 この手続きは意味のある値は返しません。
13847 @c COMMON
13848
13849 @example
13850 (send-log INFO (string-append "User " username " logged in")
13851 'USERNAME username 'REMOTE_IP remote-ip)
13852 @end example
13853 @end defun
13854
13855 @defvr {Constant} EMERGENCY
13856 @defvrx {Constant} ALERT
13857 @defvrx {Constant} CRITICAL
13858 @defvrx {Constant} ERROR
13859 @defvrx {Constant} WARNING
13860 @defvrx {Constant} NOTICE
13861 @defvrx {Constant} INFO
13862 @defvrx {Constant} DEBUG
13863 [SRFI-215]
13864 @c MOD srfi.215
13865 @c EN
13866 Bound to exact integers from 0 to 7, respectively, to indicate the severity
13867 of the incident to be logged.
13868 @c JP
13869 それぞれ正確な整数0から7に束縛され、ログされる事象の深刻度を示します。
13870 @c COMMON
13871 @end defvr
13872
13873
13874 @c ----------------------------------------------------------------------
13875 @node SICP prerequisites, Integer sets, Central log exchange, Library modules - SRFIs
13876 @section @code{srfi.216} - SICP prerequisites
13877 @c NODE SICP用ライブラリ, @code{srfi.216} - SICP用ライブラリ
13878
13879 @deftp {Module} srfi.216
13880 @mdindex srfi.216
13881 @c EN
13882 This module provides several utility procedures to write code and
13883 implement exercises of ``Structure and Interpretation of Computer Programs''.
13884 @c JP
13885 このモジュールは、『計算機プログラムの構造と解釈』(SICP)の練習課題を実装するための
13886 いくつかのユーティリティを提供します。
13887 @c COMMON
13888
13889 @c EN
13890 We provide this module for the portability, i.e. to run existing
13891 code that depends on this module. If you're studying SICP and
13892 writing code by yourself using Gauche, we recommend you to
13893 install Gauche-compat-sicp extension
13894 (@url{https://github.com/shirok/Gauche-compat-sicp}), for it takes care
13895 of Gauche-specific matters.
13896 @c JP
13897 このモジュールを提供する主な目的は、このモジュールに依存している既存のコードの移植性のためです。
13898 SICPの課題をGaucheで解きながら学んでいる場合は、
13899 Gauche-compat-sicp拡張
13900 (@url{https://github.com/shirok/Gauche-compat-sicp})を使うことをおすすめします。
13901 Gauche特有の問題への対応が入っています。
13902 @c COMMON
13903 @end deftp
13904
13905 @defvr {Constant} true
13906 @defvrx {Constant} false
13907 @defvrx {Constant} nil
13908 [SRFI-216]
13909 @c MOD srfi.216
13910 @c EN
13911 Constants bound to @code{#t}, @code{#f}, and @code{()}, respectively.
13912 @c JP
13913 それぞれ@code{#t}、@code{#f}、@code{()}に束縛された定数です。
13914 @c COMMON
13915 @end defvr
13916
13917 @defun runtime
13918 [SRFI-216]
13919 @c MOD srfi.216
13920 @c EN
13921 Returns an exact integer monotonically increasing from certain point
13922 of time in the past. The absolute value doesn't matter, but you can
13923 use differences of calls to @code{runtime} to compare relative elapsed time.
13924 @c JP
13925 過去のある時点から、時間経過によって単調増加する正確な整数を返します。
13926 具体的な値に意味はありませんが、二つの@code{runtime}呼び出しの差を取ることで
13927 相対的な時間経過を比較することができます。
13928 @c COMMON
13929 @end defun
13930
13931 @defun random n
13932 [SRFI-216]
13933 @c MOD srfi.216
13934 @c EN
13935 The argument @var{n} must be a positive real number. Returns a random
13936 nonnegative integer less than @var{n}.
13937 @c JP
13938 @var{n}は正の実数でなければなりません。@var{n}未満のランダムな非負整数を返します。
13939 @c COMMON
13940
13941 @c EN
13942 If @var{n} is exact, an exact integer is returned. Otherwise, an inexact
13943 integeer is returned.
13944 @c JP
13945 @var{n}が正確数なら、正確な整数が返ります。
13946 そうでなければ不正確な整数が返ります。
13947 @c COMMON
13948 @end defun
13949
13950 @defun parallel-execute thunk thunk2 @dots{}
13951 [SRFI-216]
13952 @c MOD srfi.216
13953 @c EN
13954 Run given thunks in parallel using threads. Returns an undefined
13955 value after all thunks are completed.
13956 @c JP
13957 与えられた@var{thunk}を、スレッドを使って並列に実行します。
13958 全ての@var{thunk}の実行が終了したら、未定義の値を返します。
13959 @c COMMON
13960 @end defun
13961
13962 @defun test-and-set! pair
13963 [SRFI-216]
13964 @c MOD srfi.216
13965 @c EN
13966 The argument must be a mutable pair.
13967 If its @code{car} is @code{#f}, set it to @code{#t} and returns @code{#f}.
13968 Otherwise returns @code{#t} without modifying the argument.
13969 The operation is performed atomically.
13970 @c JP
13971 引数は変更可能なペアでなければなりません。
13972 その@code{car}が@code{#f}なら、それを@code{#t}に変えて@code{#f}を返します。
13973 そうでなければ引数は変更せずに@code{#f}を返します。
13974 この操作はアトミックに行われます。
13975 @c COMMON
13976 @end defun
13977
13978 @defmac cons-stream a b
13979 [SRFI-216]
13980 @c MOD srfi.216
13981 @c EN
13982 Expands into @code{(cons a (delay b))}. Note that the @code{car} side
13983 of stream (@var{a}) is eagerly evaluated.
13984 @c JP
13985 @code{(cons a (delay b))}へと展開されます。@code{car}部分にあたる
13986 @var{a}は積極的に評価されることに注意してください。
13987 @c COMMON
13988
13989 @c EN
13990 This is not compatible with @code{util.stream}'s @code{stream-cons}
13991 (@pxref{Stream primitives}). The reason SICP need this as primitive
13992 is that SICP does not use macros, so it can't define its own
13993 syntactic abstraction.
13994 @c JP
13995 これは@code{util.stream}の@code{stream-cons}と異なります
13996 (@ref{Stream primitives}参照)。SICPはマクロを陽に使わないので、
13997 このオペレータがプリミティブとして用意されている前提で書かれています。
13998 @c COMMON
13999 @end defmac
14000
14001 @defvr {Constant} the-empty-stream
14002 [SRFI-216]
14003 @c MOD srfi.216
14004 @c EN
14005 A singleton instance of the empty stream. This should be used with
14006 the following @code{stream-null?}. Note that this is not compatible with
14007 @code{stream-null} of @code{util.stream} (@pxref{Stream primitives}).
14008 @c JP
14009 空のストリームを表すシングルトンインスタンスです。
14010 これは、次の@code{stream-null?}と一緒に使われなければなりません。
14011 @code{util.stream}の@code{stream-null}と互換性はありません
14012 (@ref{Stream primitives}参照)。
14013 @c COMMON
14014 @end defvr
14015
14016 @defun stream-null? obj
14017 [SRFI-216]
14018 @c MOD srfi.216
14019 @c EN
14020 Returns @code{#t} if @var{obj} is equivalent to @code{the-empty-stream},
14021 @code{#f} otherwise.
14022 Note that this is not the same as @code{stream-null?} of @code{util.stream}
14023 (@pxref{Stream primitives}).
14024 @c JP
14025 @var{obj}が@code{the-empty-stream}であれば@code{#t}を、
14026 そうでなければ@code{#f}を返します。
14027 これは@code{util.stream}の@code{stream-null?}とは異なります
14028 (@ref{Stream primitives}参照)。
14029 @c COMMON
14030 @end defun
14031
14032
14033 @c ----------------------------------------------------------------------
14034 @node Integer sets, Define higher-order lambda, SICP prerequisites, Library modules - SRFIs
14035 @section @code{srfi.217} - Integer sets
14036 @c NODE 整数集合, @code{srfi.217} - 整数集合
14037
14038 @deftp {Module} srfi.217
14039 @mdindex srfi.217
14040 @c EN
14041 This srfi defines a set whose element is limited to fixnums.
14042
14043 Although general sets are provided by @code{scheme.set}
14044 (@pxref{R7RS sets}), this module may take advantage of limited-type
14045 elements to optimize storage and operations.
14046
14047 It also provides range-based operations, which aren't available in
14048 the general sets.
14049 @c JP
14050 このsrfiは要素がfixnumに限定されたセットを定義します。
14051
14052 汎用のセットは@code{scheme.set}で提供されています(@ref{R7RS sets}参照)が、
14053 このモジュールは要素が限定されていることを利用してコンパクトにセットを保持します。
14054
14055 また、汎用のセットにはない、キーの範囲を使った操作も提供しています。
14056 @c COMMON
14057 @end deftp
14058
14059 @subheading Constructors
14060
14061 @defun iset element @dots{}
14062 [SRFI-217]
14063 @c MOD srfi.217
14064 @c EN
14065 Returns a fresh iset contains @var{element} @dots{}.
14066 Each @var{element} must be a fixnum.
14067 @c JP
14068 @var{element} @dots{} を要素とする新たなisetを作って返します。
14069 各@var{element}はfixnumでなければなりません。
14070 @c COMMON
14071 @end defun
14072
14073 @defun iset-unfold p f g seed
14074 [SRFI-217]
14075 @c MOD srfi.217
14076 @c EN
14077 Constructs an iset whose element is computed procedurally.
14078
14079 The @var{p} argument is called with a current seed value. If it returns
14080 @code{#t}, the iteration ends.
14081
14082 The @var{f} argument is called with a current seed value, and returns
14083 a fixnum to be included into the set.
14084
14085 The @var{g} argument is called with a current seed value, and returns
14086 the next seed value.
14087
14088 The @var{seed} argument gives the initial seed.
14089 @c JP
14090 手続的に要素を計算して整数集合を作ります。
14091
14092 @var{p}は現在の状態値を引数に取り、それが@code{#t}を返せば繰り返しを終了します。
14093
14094 @var{f}は現在の状態値を引数に取り、集合に含めるべきfixnumを返します。
14095
14096 @var{g}は現在の状態値を引数に取り、次の状態値を返します。
14097
14098 @var{seed}は状態値の初期値を指定します。
14099 @c COMMON
14100
14101 @example
14102 (iset->list
14103 (iset-unfold (cut > <> 10) (cut * <> 2) (cut + <> 1) 0))
14104 @result{} (0 2 4 6 8 10 12 14 16 18 20)
14105 @end example
14106 @end defun
14107
14108 @defun make-range-iset start end :optional step
14109 [SRFI-217]
14110 @c MOD srfi.217
14111 @c EN
14112 Creates an iset that contains each fixnum in
14113 @code{(numeric-range @var{start} @var{end} @var{step})}.
14114 @xref{Range}, for the details of ranges.
14115 @c JP
14116 @code{(numeric-range @var{start} @var{end} @var{step})}で生成されるレンジ
14117 に含まれるfixnumを要素とする整数集合を作って返します。
14118 レンジについては@ref{Range}を参照してください。
14119 @c COMMON
14120
14121 @example
14122 (iset->list (make-range-iset 0 5))
14123 @result{} (0 1 2 3 4)
14124 @end example
14125 @end defun
14126
14127 @c EN
14128 @subheading Predicates
14129 @c JP
14130 @subheading 述語
14131 @c COMMON
14132
14133 @defun iset? obj
14134 [SRFI-217]
14135 @c MOD srfi.217
14136 @c EN
14137 Returns @code{#t} iff @var{obj} is an iset.
14138 @c JP
14139 @var{obj}が整数集合なら@code{#t}を、そうでなければ@code{#f}を返します。
14140 @c COMMON
14141 @end defun
14142
14143 @defun iset-contains? iset element
14144 [SRFI-217]
14145 @c MOD srfi.217
14146 @c EN
14147 Returns @code{#t} iff @var{iset} contains @var{element}.
14148 @c JP
14149 @var{iset}が@var{element}を要素に持っていれば@code{#t}を、
14150 そうでなければ@code{#f}を返します。
14151 @c COMMON
14152 @end defun
14153
14154 @defun iset-empty? iset
14155 [SRFI-217]
14156 @c MOD srfi.217
14157 @c EN
14158 Returns @code{#t} iff @var{iset} is empty.
14159 @c JP
14160 @var{iset}が空なら@code{#t}を、そうでなければ@code{#f}を返します。
14161 @c COMMON
14162 @end defun
14163
14164 @defun iset-disjoint? iset1 iset2
14165 [SRFI-217]
14166 @c MOD srfi.217
14167 @c EN
14168 Both arguments must be an iset. Returns @code{#t} iff no element belongs
14169 to both isets.
14170 @c JP
14171 引数はともに整数集合でなければなりません。
14172 両方に共通する要素が無ければ@code{#t}を、あれば@code{#f}を返します。
14173 @c COMMON
14174 @end defun
14175
14176 @c EN
14177 @subheading Accessors
14178 @c JP
14179 @subheading アクセサ
14180 @c COMMON
14181
14182 @defun iset-member iset element default
14183 [SRFI-217]
14184 @c MOD srfi.217
14185 @c EN
14186 Returns @var{element} if it is contained in @var{iset}, otherwise @var{default}.
14187 @c JP
14188 @var{element}が@var{iset}の要素であればそれを、
14189 でなければ@var{default}を返します。
14190 @c COMMON
14191 @end defun
14192
14193 @defun iset-min iset
14194 @defunx iset-max iset
14195 [SRFI-217]
14196 @c MOD srfi.217
14197 @c EN
14198 Returns the minimum and the maximum element in @var{iset}. If
14199 @var{iset} is empty, returns @code{#f}.
14200 @c JP
14201 @var{iset}の最小または最大の要素を返します。
14202 @var{iset}が空の場合は@code{#f}を返します。
14203 @c COMMON
14204 @end defun
14205
14206 @c EN
14207 @subheading Updaters
14208 @c JP
14209 @subheading 更新
14210 @c COMMON
14211
14212 @defun iset-adjoin iset elt1 elt2 @dots{}
14213 @defunx iset-adjoin! iset elt1 elt2 @dots{}
14214 [SRFI-217]
14215 @c MOD srfi.217
14216 @c EN
14217 Returns an iset that includes all the elements in @var{iset},
14218 plus @var{elt1} @var{elt2} @dots{}.
14219 An error is thrown if @var{elt1} @var{elt2} @dots{} include other than
14220 fixnums.
14221 @c JP
14222 @var{iset}の要素に、@var{elt1} @var{elt2} @dots{}を加えたものを要素として持つ
14223 整数集合を返します。@var{elt1} @var{elt2} @dots{} にfixnum以外のものが
14224 含まれていたらエラーが投げられます。
14225 @c COMMON
14226
14227 @c EN
14228 The linear update version @code{iset-adjoin!} may reuse @var{iset}
14229 to store the result, but the caller must always use its return value.
14230 @c JP
14231 線形更新版@code{iset-adjoin!}は結果を作るのに@var{iset}を再利用するかもしれません。
14232 ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
14233 @c COMMON
14234 @end defun
14235
14236 @defun iset-delete iset elt1 elt2 @dots{}
14237 @defunx iset-delete! iset elt1 elt2 @dots{}
14238 [SRFI-217]
14239 @c MOD srfi.217
14240 @c EN
14241 Returns an iset that includes the elements in @var{iset}
14242 except the ones matching one of @var{elt1} @var{elt2} @dots{}.
14243 @c JP
14244 @var{iset}の要素から、@var{elt1} @var{elt2} @dots{}を除いたものを含む
14245 整数集合を返します。
14246 @c COMMON
14247
14248 @c EN
14249 The linear update version @code{iset-delete!} may reuse @var{iset}
14250 to store the result, but the caller must always use its return value.
14251 @c JP
14252 線形更新版@code{iset-delete!}は結果を作るのに@var{iset}を再利用するかもしれません。
14253 ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
14254 @c COMMON
14255 @end defun
14256
14257 @defun iset-delete-all iset elt-list
14258 @defunx iset-delete-all! iset elt-list
14259 [SRFI-217]
14260 @c MOD srfi.217
14261 @c EN
14262 The @var{elt-list} argument must be a list of fixnums.
14263 Returns an iset that includes the elements in @var{iset}
14264 except the ones in @var{elt-list}.
14265 @c JP
14266 @var{elt-list}引数はfixnumのリストでなければなりません。
14267 @var{iset}の要素から、@var{elt-list}に含まれるfixnumを取り除いたものを要素とする
14268 整数集合を返します。
14269 @c COMMON
14270
14271 @c EN
14272 The linear update version @code{iset-delete-all!} may reuse @var{iset}
14273 to store the result, but the caller must always use its return value.
14274 @c JP
14275 線形更新版@code{iset-delete-all!}は結果を作るのに@var{iset}を再利用するかもしれません。
14276 ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
14277 @c COMMON
14278 @end defun
14279
14280 @defun iset-delete-min iset
14281 @defunx iset-delete-min! iset
14282 @defunx iset-delete-max iset
14283 @defunx iset-delete-max! iset
14284 [SRFI-217]
14285 @c MOD srfi.217
14286 @c EN
14287 Returns two values: The minimum or the maximum element in @var{iset},
14288 and a new iset that contains elements in @var{iset} except the
14289 minimum/maximum element. An error is thrown if @var{iset} is empty.
14290 @c JP
14291 二つの値を返します。@var{iset}の最小もしくは最大の要素と、
14292 その要素を取り除いた整数集合です。@var{iset}が空の場合はエラーが投げられます。
14293 @c COMMON
14294
14295 @c EN
14296 The linear update version @code{iset-delete-min!}/@code{iset-delete-max!}
14297 may reuse @var{iset} to store the result,
14298 but the caller must always use its return value.
14299 @c JP
14300 線形更新版@code{iset-delete-min!}/@code{iset-delete-mac!}は結果を作るのに
14301 @var{iset}を再利用するかもしれません。
14302 ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
14303 @c COMMON
14304 @end defun
14305
14306 @defun iset-search iset element failure success
14307 @defunx iset-search! iset element failure success
14308 [SRFI-217]
14309 @c MOD srfi.217
14310 @c EN
14311 Search @var{iset} for matching @var{element} from lowest to highest value.
14312 They return two values, a (possibly updated) iset, and auxiliary
14313 value as explained below. The @var{failure} and @var{success}
14314 arguments are both procedures.
14315 @c JP
14316 @var{iset}の要素のうち@var{element}と一致するものを下から順に探します。
14317 戻り値は二つで、一つ目は整数集合、二つ目は以下に説明する補助値です。
14318 @var{failure}と@var{success}はともに手続きです。
14319 @c COMMON
14320
14321 @c EN
14322 If @var{element} is found, the @var{success} procedure is called
14323 with three arguments: the matching element of @var{iset}, a procedure
14324 @var{update}, and a procedure @var{remove}. The @var{success} procedure
14325 can either return or tail call one of either @var{update} or @var{remove}.
14326 @c JP
14327 @var{element}が見つかった場合、@var{success}が3つの引数で呼び出されます:
14328 マッチした要素、手続き@var{update}、そいて手続き@var{remove}です。
14329 @var{success}手続きはそのまま戻るか、@var{update}か@var{remove}のどちらかを
14330 末尾呼び出しすることができます。
14331 @c COMMON
14332
14333 @c EN
14334 The @var{update} procedure
14335 can be invoked with two arguments, @var{new-element} and @var{obj}; if
14336 called, @var{new-element} replaces @var{element} in @var{iset}, and
14337 @code{iset-search} returns the new iset and @var{obj}.
14338 The @var{remove} procedure can be invoked with one argument, @var{obj}.
14339 It removes the matching element from @var{iset} and @code{iset-search}
14340 returns the new iset and @var{obj}.
14341 When those procedures are tail-called from @var{success}, those values
14342 become the return values of @code{iset-search}.
14343 @c JP
14344 @var{update}手続きは二つの引数@var{new-element}と@var{obj}を取ります。
14345 呼ばれると、この手続きは@var{iset}の要素@var{element}を@var{new-element}
14346 で置き換えた整数集合および@var{obj}を戻り値として返します。
14347 @var{remove}手続きは一つの引数@var{obj}を取り、@var{iset}から@var{element}
14348 を除いた整数集合および@var{obj}を戻り値として返します。
14349 @var{success}手続きからこれらの手続きが末尾呼び出しされていれば、
14350 この整数集合と@var{obj}がそのまま@code{iset-search}の戻り値となります。
14351 @c COMMON
14352
14353 @c EN
14354 If @var{element} is not found, the @var{failure} procedure is called
14355 with two arguments, @var{insert} and @var{ignore}, both procedures
14356 and @var{failure} is expected to tail-call one of them.
14357 @c JP
14358 @var{element}が見つからなかった場合、@var{failure}手続きが二つの引数、
14359 @var{insert}と@var{ignore}を伴って呼ばれます。これらはそれぞれが手続きで、
14360 @var{failure}はどちらかを末尾呼び出ししなければなりません。
14361 @c COMMON
14362
14363 @c EN
14364 The @var{insert} procedure can be called with one argument, @var{obj}.
14365 It causes @code{iset-search} to return a new iset that contains all
14366 the elements from @var{iset} plus @var{element}, and @var{obj}.
14367 The @var{ignore} procedure can be called with one argument, @var{obj}.
14368 It causes @code{iset-search} to return the original @var{iset} and
14369 @var{obj}.
14370 @c JP
14371 @var{insert}手続きはひとつの引数@var{obj}を取り、
14372 @var{element}を@var{iset}に追加した整数集合と@var{obj}を戻り値とします。
14373 @var{ignore}手続きはひとつの引数@var{obj}を取り、
14374 @var{iset}そのものと@var{obj}を戻り値とします。
14375 @c COMMON
14376
14377 @c EN
14378 The linear update version, @code{iset-search!}, may reuse @var{iset}
14379 for the updated iset.
14380 @c JP
14381 線形更新版の@code{iset-search!}では、結果の整数集合を作るために
14382 @var{iset}が破壊的に変更されるかもしれません。
14383 @c COMMON
14384 @end defun
14385
14386 @c EN
14387 @subheading The whole iset
14388 @c JP
14389 @subheading 集合全体への操作
14390 @c COMMON
14391
14392 @defun iset-size iset
14393 [SRFI-217]
14394 @c MOD srfi.217
14395 @c EN
14396 Returns the number of elements in @var{iset}.
14397 @c JP
14398 @var{iset}の要素数を返します。
14399 @c COMMON
14400 @end defun
14401
14402 @defun iset-find pred iset failure
14403 [SRFI-217]
14404 @c MOD srfi.217
14405 @c EN
14406 Returns the smallest element of @var{iset} that satisfies @var{pred}.
14407 If no element satisfies @var{pred}, @var{failure} is called with no
14408 arguments, and its result is returned from @code{iset-find}.
14409 @c JP
14410 @var{iset}の要素のうち、述語@var{pred}を満たす最小の要素を返します。
14411 もし@var{pred}を満たす要素が見つからなかったら、手続き@var{failure}を引数無しで
14412 呼び出しその結果を返します。
14413 @c COMMON
14414 @end defun
14415
14416 @defun iset-count pred iset
14417 [SRFI-217]
14418 @c MOD srfi.217
14419 @c EN
14420 Returns the number of elements in @var{iset} that satisfy @var{pred}.
14421 @c JP
14422 @var{iset}の要素のうち、述語@var{pred}を満たすものの個数を返します。
14423 @c COMMON
14424 @end defun
14425
14426 @defun iset-any? pred iset
14427 [SRFI-217]
14428 @c MOD srfi.217
14429 @c EN
14430 Returns @code{#t} if any element in @var{iset} satisfies @var{pred},
14431 @code{#f} otherwise.
14432 @c JP
14433 @var{iset}の要素のうち@var{pred}を満たすものがひとつでもあれば@code{#t}を、
14434 そうでなければ@code{#f}を返します。
14435 @c COMMON
14436 @c COMMON
14437 @end defun
14438
14439 @defun iset-every? pred iset
14440 [SRFI-217]
14441 @c MOD srfi.217
14442 @c EN
14443 Returns @code{#t} if every element in @var{iset} satisfies @var{pred},
14444 @code{#f} otherwise.
14445 @c JP
14446 @var{iset}の要素が全て@var{pred}を満たしたら@code{#t}を、そうでなければ@code{#f}を
14447 返します。
14448 @c COMMON
14449 @end defun
14450
14451 @c EN
14452 @subheading Mapping and folding
14453 @c JP
14454 @subheading マップとfold
14455 @c COMMON
14456
14457 @defun iset-map proc iset
14458 [SRFI-217]
14459 @c MOD srfi.217
14460 @c EN
14461 Creates and returns a new iset whose elements consist of
14462 the result of @var{proc} applied to each element of the given @var{iset}.
14463 An error is signaled if @var{proc} doesn't return a fixnum.
14464 @c JP
14465 @var{iset}の各要素に@var{proc}を適用し、その結果を集めた@var{iset}を作って返します。
14466 @var{proc}の戻り値がfixnumでなければエラーが投げられます。
14467 @c COMMON
14468
14469 @c EN
14470 Note that the size of the result set may be smaller than the input,
14471 if @var{proc} isn't injective.
14472 @c JP
14473 @var{proc}が単射でなければ、返される整数集合は元の@var{iset}より小さくなります。
14474 @c COMMON
14475
14476 @c EN
14477 The order of @var{proc}'s application is unspecified.
14478 @c JP
14479 @var{proc}が適用される順序は不定です。
14480 @c COMMON
14481 @end defun
14482
14483 @defun iset-for-each proc iset
14484 [SRFI-217]
14485 @c MOD srfi.217
14486 @c EN
14487 Applies @var{proc} to each element in @var{iset} in increasing order.
14488 The result of @var{proc} is discarded. Returns unspecified result.
14489 @c JP
14490 @var{proc}を@var{iset}の各要素に、要素の昇順に適用します。
14491 @var{proc}の結果は捨てられます。戻り値は指定されません。
14492 @c COMMON
14493 @end defun
14494
14495 @defun iset-fold kons knil iset
14496 @defunx iset-fold-right kons knil iset
14497 [SRFI-217]
14498 @c MOD srfi.217
14499 @c EN
14500 Like @code{fold}/@code{fold-right}, apply @var{kons} on each element
14501 in @var{iset}, increasing or decreasing order,
14502 passing the result to the previous @var{kons}, or @var{knil}
14503 for the first iteration. Returns the last result of @var{kons}.
14504 If @var{iset} is empty, @var{kons} is never called and @var{knil} is
14505 returned as is.
14506 @c JP
14507 @code{fold}/@code{fold-right}と同じように、@var{kons}を@var{iset}の各要素と
14508 直前の@var{kons}の結果を引数にして呼び出してゆきます。最初の@var{kons}の呼び出しには
14509 @var{knil}が使われます。要素はそれぞれ昇順/降順に呼び出されます。
14510 最後の@var{kons}の結果が戻り値になります。
14511 @var{iset}が空なら、@var{kons}は呼ばれず@var{knil}がそのまま返されます。
14512 @c COMMON
14513
14514 @example
14515 (iset-fold cons '() (iset 2 3 5 7 11))
14516 @result{} (11 7 5 3 2)
14517 (iset-fold-right cons '() (iset 2 3 5 7 11))
14518 @result{} (2 3 5 7 11)
14519 @end example
14520 @end defun
14521
14522 @defun iset-filter pred iset
14523 @defunx iset-filter! pred iset
14524 [SRFI-217]
14525 @c MOD srfi.217
14526 @c EN
14527 Returns an iset that contains the elements in @var{iset} that satisfy @var{pred}.
14528 The linear-update version @code{iset-filter!} may reuse given @var{iset}
14529 to store the result.
14530 @c JP
14531 @var{iset}の要素のうち、述語@var{pred}を満たすものだけを集めた整数集合を作って返します。
14532 線形更新版@code{iset-filter!}は結果を作るために@var{iset}を再利用するかもしれません。
14533 @c COMMON
14534 @end defun
14535
14536 @defun iset-remove pred iset
14537 @defunx iset-remove! pred iset
14538 [SRFI-217]
14539 @c MOD srfi.217
14540 @c EN
14541 Returns an iset that contains the elements in @var{iset} that do not satisfy
14542 @var{pred}.
14543 The linear-update version @code{iset-remove!} may reuse given @var{iset}
14544 to store the result.
14545 @c JP
14546 @var{iset}の要素のうち、述語@var{pred}を満たさないものだけを集めた整数集合を作って返します。
14547 線形更新版@code{iset-remove!}は結果を作るために@var{iset}を再利用するかもしれません。
14548 @c COMMON
14549 @end defun
14550
14551 @defun iset-partition pred iset
14552 @defunx iset-partition! pred iset
14553 [SRFI-217]
14554 @c MOD srfi.217
14555 @c EN
14556 Returns two isets, first one consisting of the elements in @var{iset} that
14557 satisfy @var{pred}, and the second one consisting of the elements that
14558 don't.
14559 The linear-update version @code{iset-partition!} may reuse given @var{iset}
14560 to store one of the results.
14561 @c JP
14562 ふたつの整数集合を返します。一つ目は、@var{iset}の要素のうち述語@var{pred}を満たすもの、
14563 二つ目は満たさないものを集めた集合です。
14564 線形更新版@code{iset-partition!}は結果を作るために@var{iset}を再利用するかもしれません。
14565 @c COMMON
14566 @end defun
14567
14568 @c EN
14569 @subheading Copying and conversion
14570 @c JP
14571 @subheading コピーと変換
14572 @c COMMON
14573
14574 @defun iset-copy iset
14575 [SRFI-217]
14576 @c MOD srfi.217
14577 @c EN
14578 Returns a copy of @var{iset}.
14579 @c JP
14580 @var{iset}のコピーを返します。
14581 @c COMMON
14582 @end defun
14583
14584 @defun iset->list iset
14585 [SRFI-217]
14586 @c MOD srfi.217
14587 @c EN
14588 Returns a list of elements in @var{iset}, in increasing order.
14589 @c JP
14590 @var{iset}の要素を昇順に並べたリストを返します。
14591 @c COMMON
14592 @end defun
14593
14594 @defun list->iset list
14595 [SRFI-217]
14596 @c MOD srfi.217
14597 @c EN
14598 Returns an iset that contains elements in @var{list}. The elements
14599 in @var{list} must be fixnums. Duplicate elements are consolidated.
14600 @c JP
14601 @var{list}はfixnumのリストでなければなりません。
14602 それらを要素として持つ整数集合を作って返します。重複する要素はひとつにまとめられます。
14603 @c COMMON
14604 @end defun
14605
14606 @defun list->iset! iset list
14607 [SRFI-217]
14608 @c MOD srfi.217
14609 @c EN
14610 Returns an iset consists of the elements from @var{iset} and @var{list}.
14611 All the elements must be fixnums.
14612 It may reuse the given @var{iset} to store the result.
14613 @c JP
14614 @var{iset}に、fixnumのリスト@var{list}を要素として足した整数集合を返します。
14615 引数@var{iset}は結果を作るために破壊的に再利用されるかもしれません。
14616 @c COMMON
14617 @end defun
14618
14619 @c EN
14620 @subheading Subsets
14621 @c JP
14622 @subheading 部分集合
14623 @c COMMON
14624
14625 @defun iset=? iset1 iset2 iset3 @dots{}
14626 [SRFI-217]
14627 @c MOD srfi.217
14628 @c EN
14629 Returns @code{#t} iff all given isets contains the same elements.
14630 @c JP
14631 与えられた整数集合すべてが同じ要素を含んでいれば@code{#t}を、
14632 そうでなければ@code{#f}を返します。
14633 @c COMMON
14634 @end defun
14635
14636 @defun iset<? iset1 iset2 iset3 @dots{}
14637 @defunx iset<=? iset1 iset2 iset3 @dots{}
14638 @defunx iset>? iset1 iset2 iset3 @dots{}
14639 @defunx iset>=? iset1 iset2 iset3 @dots{}
14640 [SRFI-217]
14641 @c MOD srfi.217
14642 @c EN
14643 These compares subset relationships between isets.
14644 @code{(iset<=? iset1 iset2)} is @code{#t} iff every element of @var{iset1}
14645 is contained in @var{iset2}, and so on.
14646 @c JP
14647 整数集合間の包含関係を比較します。
14648 例えば@code{(iset<=? iset1 iset2)}は、@var{iset1}の全ての要素が@var{iset2}に
14649 含まれている場合(@var{iset1}が@var{iset2}の部分集合である場合)に@code{#t}、
14650 そうでなければ@code{#f}となります。
14651 @c COMMON
14652 @end defun
14653
14654 @c EN
14655 @subheading Set theory operations
14656 @c JP
14657 @subheading 集合演算
14658 @c COMMON
14659
14660 @defun iset-union iset1 iset2 iset3 @dots{}
14661 @defunx iset-union! iset1 iset2 iset3 @dots{}
14662 [SRFI-217]
14663 @c MOD srfi.217
14664 @c EN
14665 Returns an iset that is a union of given isets. Functional version
14666 @code{iset-union} always returns a fresh iset. Linear update version
14667 @code{iset-union!} may reuse @var{iset1} to produce the result.
14668 @c JP
14669 与えられた整数集合の和集合を返します。
14670 @code{iset-union}は関数的で、常に新たな整数集合を作って返します。
14671 線形更新版の@code{iset-union!}は、結果を作るために@var{iset1}を破壊的に再利用する
14672 かもしれません。
14673 @c COMMON
14674 @end defun
14675
14676 @defun iset-intersection iset1 iset2 iset3 @dots{}
14677 @defunx iset-intersection! iset1 iset2 iset3 @dots{}
14678 [SRFI-217]
14679 @c MOD srfi.217
14680 @c EN
14681 Returns an iset that is an intersction of the given iset. Functional version
14682 @code{iset-intersection} always returns a fresh iset. Linear update version
14683 @code{iset-intersection!} may reuse @var{iset1} to produce the result.
14684 @c JP
14685 与えられた整数集合全てに共通する要素を含む整数集合を返します。
14686 @code{iset-intersection}は関数的で、常に新たな整数集合を作って返します。
14687 線形更新版の@code{iset-intersection!}は、結果を作るために@var{iset1}を破壊的に再利用する
14688 かもしれません。
14689 @c COMMON
14690 @end defun
14691
14692 @defun iset-difference iset1 iset2 iset3 @dots{}
14693 @defunx iset-difference! iset1 iset2 iset3 @dots{}
14694 [SRFI-217]
14695 @c MOD srfi.217
14696 @c EN
14697 Returns an iset that has elements in @var{iset1} but not
14698 in @var{iset2} @var{iset3} @dots{}.
14699 Functional version
14700 @code{iset-difference} always returns a fresh iset. Linear update version
14701 @code{iset-difference!} may reuse @var{iset1} to produce the result.
14702 @c JP
14703 @var{iset1}の要素のうち、@var{iset2}, @code{iset3} @dots{}に含まれないものを
14704 集めた整数集合を返します。
14705 @code{iset-difference}は関数的で、常に新たな整数集合を作って返します。
14706 線形更新版の@code{iset-difference!}は、結果を作るために@var{iset1}を破壊的に再利用する
14707 かもしれません。
14708 @c COMMON
14709 @end defun
14710
14711 @defun iset-xor iset1 iset2
14712 @defunx iset-xor! iset1 iset2
14713 [SRFI-217]
14714 @c MOD srfi.217
14715 @c EN
14716 Returns an iset that has elements, each of which is either in @var{iset1}
14717 or @var{iset2} but not in both.
14718 Functional version
14719 @code{iset-xor} always returns a fresh iset. Linear update version
14720 @code{iset-xor!} may reuse @var{iset1} to produce the result.
14721 @c JP
14722 @var{iset1}と@var{iset2}のどちらか一方のみに含まれている要素を集めた整数集合を
14723 返します。
14724 @code{iset-xor}は関数的で、常に新たな整数集合を作って返します。
14725 線形更新版の@code{iset-xor!}は、結果を作るために@var{iset1}を破壊的に再利用する
14726 かもしれません。
14727 @c COMMON
14728 @end defun
14729
14730 @c EN
14731 @subheading Intervals and ranges
14732 @c JP
14733 @subheading 区間
14734 @c COMMON
14735
14736 @defun iset-open-interval iset low high
14737 @defunx iset-closed-interval iset low high
14738 @defunx iset-open-closed-interval iset low high
14739 @defunx iset-closed-open-interval iset low high
14740 [SRFI-217]
14741 @c MOD srfi.217
14742 @c EN
14743 Extract elements in @var{iset} that are in the range
14744 specified by @var{low} and @var{high}, which must be real numbers.
14745 The `open' and `close' in the name indicates whether
14746 the boundary is included; @code{iset-open-interval} doesn't include
14747 both boundary, @code{iset-close-interval} includes both
14748 boundary, @code{iset-open-closed-interval} includes @var{high} but
14749 not @var{low} @code{set-closed-open-interval} inclues @var{low}
14750 but not @var{high}.
14751 @c JP
14752 @var{iset}の要素のうち、実数@var{low}と@var{high}で指定される区間内の
14753 要素のみを含む@var{iset}を返します。下限@var{low}、上限@var{high}それぞれを
14754 区間に含むか含まないかで4種類のバリエーションがあります。
14755 @code{iset-open-interval}は共に含まず、
14756 @code{iset-close-interval}は共に含み、
14757 @code{iset-open-closed-interval}は@var{low}を含まず@var{high}は含み、
14758 @code{iset-closed-open-interval}は@var{low}を含み@var{high}は含みません。
14759 @c COMMON
14760
14761 @example
14762 (iset->list (iset-open-interval (iset 2 3 5 7 11) 2 7))
14763 @result{} (3 5)
14764 (iset->list (iset-closed-interval (iset 2 3 5 7 11) 2 7))
14765 @result{} (2 3 5 7)
14766 (iset->list (iset-open-closed-interval (iset 2 3 5 7 11) 2 7))
14767 @result{} (3 5 7)
14768 (iset->list (iset-closed-open-interval (iset 2 3 5 7 11) 2 7))
14769 @result{} (2 3 5)
14770 @end example
14771 @end defun
14772
14773 @defun isubset= iset k
14774 @defunx isubset< iset k
14775 @defunx isubset<= iset k
14776 @defunx isubset> iset k
14777 @defunx isubset>= iset k
14778 [SRFI-217]
14779 @c MOD srfi.217
14780 @c EN
14781 Returns a subset of @var{iset} whose elements are equal to,
14782 less than, less than or equal to, greater than, and greater than or
14783 equal to, @var{k}, which must be a real number.
14784 @c JP
14785 @var{iset}の要素のうち、それぞれ、
14786 実数@var{k}と等しい要素のみを含む部分集合、
14787 @var{k}未満の要素のみを含む部分集合、
14788 @var{k}以下の要素のみを含む部分集合、
14789 @var{k}超過の要素のみを含む部分集合、
14790 @var{k}以上の要素のみを含む部分集合を返します。
14791 @c COMMON
14792 @end defun
14793
14794 @c ----------------------------------------------------------------------
14795 @node Define higher-order lambda, Generator/accumulator sub-library, Integer sets, Library modules - SRFIs
14796 @section @code{srfi.219} - Define higher-order lambda
14797 @c NODE 高階lambdaの定義, @code{srfi.219} - 高階lambdaの定義
14798
14799 @deftp {Module} srfi.219
14800 @mdindex srfi.219
14801 @c EN
14802 This srfi enhances @code{define} form to allow defining
14803 function-returning-function compactly. It works as follows:
14804 @c JP
14805 このsrfiは、関数を返す関数を簡単に定義できるように@code{define}を拡張します。
14806 次のように動作します。
14807 @c COMMON
14808
14809 @example
14810 (define ((f a b) c d) ...)
14811 @equiv{} (define (f a b) (lambda (c d) ...))
14812 @equiv{} (define f (lambda (a b) (lambda (c d) ...)))
14813
14814 (define (((f a) b) c) ...)
14815 @equiv{} (define ((f a) b) (lambda (c) ...))
14816 @equiv{} (define (f a) (lambda (b) (lambda (c) ...)))
14817 @equiv{} (define f (lambda (a) (lambda (b) (lambda (c) ...))))
14818 @end example
14819
14820 @c EN
14821 This feature has been traditionally supported in many
14822 implementations, including Gauche. So you can use this feature
14823 without using @code{srfi.193}. This module is provided for
14824 the portable code.
14825 @c JP
14826 この機能は伝統的に多くの実装でサポートされており、Gaucheも例外ではありません。
14827 従って@code{srfi.193}を使わないでもこの機能を使うことはできます。
14828 ポータブルなコードを書く必要がある場合にこのモジュールを使うと良いでしょう。
14829 @c COMMON
14830
14831 @c EN
14832 Note: Gauche has two @code{define}s: A ``vanilla'' @code{define} that
14833 works as defined in R7RS, and an ``extended'' @code{define} that
14834 supports extended lambda arguments. If you import @code{srfi.193},
14835 it imports the former, hence extended lambda arguments are not available.
14836 It's what you need for the portable code.
14837 @c JP
14838 Gaucheはふたつの@code{define}を持っています。
14839 R7RSで定義されているとおりの「素の」@code{define}と、
14840 拡張ラムダ引数をサポートしている「拡張」@code{define}です。
14841 @code{srfi.193}をインポートすると前者の@code{define}がインポートされます。
14842 ポータブルなコードに必要なのは前者だからです。
14843 @c COMMON
14844 @end deftp
14845
14846 @c ----------------------------------------------------------------------
14847 @node Generator/accumulator sub-library, Compound objects, Define higher-order lambda, Library modules - SRFIs
14848 @section @code{srfi.221} - Generator/accumulator sub-library
14849 @c NODE ジェネレータ/アキュムレータ サブライブラリ, @code{srfi.221} - ジェネレータ/アキュムレータ サブライブラリ
14850
14851 @deftp {Module} srfi.221
14852 @mdindex srfi.221
14853 @c EN
14854 This srfi adds several utility procedures to the generator library
14855 (@pxref{Generators}, for Gauche's native support of generators;
14856 @pxref{R7RS generators}, for R7RS-large spec).
14857 @c JP
14858 このsrfiは、ジェネレータライブラリにいくつか有用な手続きを追加するものです。
14859 (Gaucheのネイティブなジェネレータについては@ref{Generators}を、
14860 R7RS-largeのジェネレータについては@ref{R7RS generators}を参照。)
14861 @c COMMON
14862 @end deftp
14863
14864 @defun gcompose-left constructor operation @dots{}
14865 @defunx gcompose-right constructor operation @dots{}
14866 [SRFI-221]
14867 @c MOD srfi.221
14868 @c EN
14869 The @var{constructor} argument is a thunk that returns a generator.
14870 Each @var{operation} is a procedure that takes a generator and returns
14871 a generator.
14872 @c JP
14873 @var{constructor}は引数を取らずジェネレータを返す手続き、
14874 各@var{operation}はジェネレータを取りジェネレータを返す手続きです。
14875 @c COMMON
14876
14877 @c EN
14878 These procedures creates and returns a generator that is a composition
14879 of given operations on top of the one constructed by @var{constructor}.
14880 @code{gcompose-left} applies @var{operation}s left to right (left-associative),
14881 while @code{gcompose-right} does right to left (right-associative).
14882 @c JP
14883 これらの手続きは、@var{constructor}で作られるジェネレータに@var{operations}を
14884 合成したジェネレータを作って返します。
14885 @code{gcompose-left}は@var{operator}を左から右に(左結合)、
14886 @code{gcompose-right}は右から左に(右結合)適用します。
14887 @c COMMON
14888
14889 @example
14890 (use gauche.generator)
14891 (use srfi.221)
14892
14893 (generator->list
14894 (gcompose-left
14895 (cut make-iota-generator 100)
14896 (cut gfilter even? <>)
14897 (cut ggroup <> 5)))
14898 @result{} ((0 2 4 6 8) (10 12 14 16 18) (20 22 24 26 28)
14899 (30 32 34 36 38) (40 42 44 46 48) (50 52 54 56 58)
14900 (60 62 64 66 68) (70 72 74 76 78) (80 82 84 86 88)
14901 (90 92 94 96 98))
14902
14903 ;; The same result can be obtained with:
14904 (generator->list
14905 (gcompose-right
14906 (cut ggroup <> 5)
14907 (cut gfilter even? <>)
14908 (cut make-iota-generator 100)))
14909 @end example
14910 @end defun
14911
14912 @defun accumulate-generated-values accumulator generator
14913 [SRFI-221]
14914 @c MOD srfi.221
14915 @c EN
14916 Calls @var{generator} repeatedly, accumulating the values into
14917 @var{accumulator}, until @var{generator} is exhausted. Then it
14918 retrieves and returns the accumulated value.
14919 @xref{R7RS generators}, for the details of accumulators.
14920 @c JP
14921 @var{generator}を繰り返し呼び、得られる値を@var{accumulator}に蓄積してゆきます。
14922 @var{generator}が尽きたら、蓄積された値を返します。
14923 アキュムレータについては@ref{R7RS generators}を参照してください。
14924 @c COMMON
14925
14926 @c EN
14927 It is a generalization of @code{generator->list} type of converter;
14928 you can pass an accumulator that returns the desired type of result.
14929 @c JP
14930 これは、@code{generator->list}のような変換器の一般化です。
14931 渡すアキュムレータによって、どういうオブジェクトに変換するかが決まります。
14932 @c COMMON
14933 @end defun
14934
14935 @defun genumerate gen
14936 [SRFI-221]
14937 @c MOD srfi.221
14938 @c EN
14939 Returns a generator that yields pairs, each of which consists of
14940 an exact integer count and the value yielded by @var{gen}.
14941 The count starts from 0 and incremented.
14942 @c JP
14943 0から始まる整数と、@var{gen}が生成する値とのペアを次々に生成するジェネレータを返します。
14944 @c COMMON
14945
14946 @example
14947 (generator->list (genumerate (list->generator '(a b c d e))))
14948 @result{} ((0 . a) (1 . b) (2 . c) (3 . d) (4 . e))
14949 @end example
14950 @end defun
14951
14952 @defun gchoice choice-gen source-gen @dots{}
14953 [SRFI-221]
14954 @c MOD srfi.221
14955 @c EN
14956 All arguments are generators.
14957 Returns a generator that yields a value from one of @var{source-gen}s,
14958 according to @var{choice-gen}.
14959 @c JP
14960 引き数は全てジェネレータです。
14961 @var{choice-gen}ジェネレータの値に従って@var{source-gen}を選び、そのジェネレータが
14962 生成する値を返すようなジェネレータを作って返します。
14963 @c COMMON
14964
14965 @c EN
14966 The @var{choice-gen} must be a generator that yields exact integers
14967 between 0 and one minus the number of @var{source-gen}s.
14968 @c JP
14969 @var{choice-gen}は0から@var{source-gen}の数マイナス1までの正確な整数を
14970 返すジェネレータです。
14971 @c COMMON
14972
14973 @c EN
14974 Each time the resulting generator is invoked, @var{choice-gen} is called.
14975 If it is exhausted, the resulting generator is also exhausted.
14976 @c JP
14977 結果のジェネレータが呼ばれると、まず@var{choice-gen}が呼ばれます。
14978 それが既に尽きていたら、結果のジェネレータも尽きます。
14979 @c COMMON
14980
14981 @c EN
14982 Otherwise, the @var{source-gen} indexed by the result of @var{choice-gen}
14983 is called, and if it isn't exhausted, the value is returned.
14984 @c JP
14985 そうでなければ、@var{choice-gen}の値番目の@var{source-gen}が選ばれて呼ばれ、
14986 それが尽きてなければその結果が返されます。
14987 @c COMMON
14988
14989 @c EN
14990 If the selected @var{source-gen} is exhausted, @var{choice-gen} is retried
14991 until non-exhausted @var{source-gen} yields a value. If all @var{source-gen}
14992 is exhausted, the resulting generator is also exhausted.
14993 @c JP
14994 選ばれた@var{source-gen}が既に尽きていた場合、尽きていない@var{source-gen}が選ばれるまで
14995 @var{choice-gen}が繰り返し呼ばれます。全ての@var{source-gen}が尽きた場合は
14996 結果のジェネレータも尽きます。
14997 @c COMMON
14998 @end defun
14999
15000 @defun stream->generator stream
15001 [SRFI-221]
15002 @c MOD srfi.221
15003 @c EN
15004 Returns a generator that yields each element of a lazy stream @var{stream}.
15005 Lazy streams are defined in R7RS-large @code{scheme.stream}
15006 (@pxref{R7RS stream}), which is a subset of Gauche's @code{util.stream}
15007 (@pxref{Stream library}).
15008 @c JP
15009 遅延ストリーム@var{stream}の要素を次々に生成するジェネレータを返します。
15010 遅延ストリームは、R7RS-largeの@code{scheme.stream}で定義されています
15011 (@ref{R7RS stream}参照)。それはGaucheの@code{util.stream}のサブセットです
15012 (@ref{Stream library}参照)。
15013 @c COMMON
15014 @end defun
15015
15016 @defun generator->stream generator
15017 [SRFI-221]
15018 @c MOD srfi.221
15019 @c EN
15020 Returns a lazy stream whose elements consist of the values
15021 generated by @var{generator}
15022 Lazy streams are defined in R7RS-large @code{scheme.stream}
15023 (@pxref{R7RS stream}), which is a subset of Gauche's @code{util.stream}
15024 (@pxref{Stream library}).
15025 @c JP
15026 @var{generator}が生成する値を要素とする遅延ストリームを返します。
15027 遅延ストリームは、R7RS-largeの@code{scheme.stream}で定義されています
15028 (@ref{R7RS stream}参照)。それはGaucheの@code{util.stream}のサブセットです
15029 (@ref{Stream library}参照)。
15030 @c COMMON
15031
15032 @c EN
15033 See also @code{generator->lseq} (@pxref{Lazy sequences}),
15034 which returns a lazy sequence defined in R7RS-large @code{scheme.lseq}.
15035 In Gauche, lazy sequences are integrated to ordinary lists and more
15036 lightweight than lazy streams.
15037 @c JP
15038 なお、R7RS-largenの@code{scheme.lseq}で定義される遅延シーケンスを返す
15039 @code{genreator->lseq}もあります (@ref{Lazy sequences}参照)。
15040 Gaucheでは、遅延シーケンスは通常のリストと統合されていて、遅延ストリームより軽いです。
15041 @c COMMON
15042 @end defun
15043
15044 @c ----------------------------------------------------------------------
15045 @node Compound objects, Control features, Generator/accumulator sub-library, Library modules - SRFIs
15046 @section @code{srfi.222} - Compound objects
15047 @c NODE 複合オブジェクト, @code{srfi.222} - 複合オブジェクト
15048
15049 @deftp {Module} srfi.222
15050 @mdindex srfi.222
15051 @c EN
15052 Compound objects are encapsulation of an immutable sequence of objects.
15053 Any objects other than a compound object can be included in a compound object;
15054 if you try to create a compound object including compound objects,
15055 it is 'flattened'---that is, the source's subobjects are retrieved
15056 and each one is put into the new compound object.
15057 @c JP
15058 複合オブジェクトは、オブジェクトの並びをまとめたもので、それ自体は変更不可なオブジェクトです。
15059 複合オブジェクト以外の任意オブジェクトを要素とすることができます。
15060 複合オブジェクトを含めようとした場合は、
15061 その要素が取り出されてそれぞれ結果の複合オブジェクトに埋め込まれます。
15062 つまり複合オブジェクトがネストすることはありません。
15063 @c COMMON
15064
15065 @c EN
15066 This is an abstraction of the compound condition (@pxref{Conditions}),
15067 although Gauche's compound conditions are not built on this.
15068 @c JP
15069 これは複合コンディション (@pxref{Conditions}) の機能を抽象化したものです。
15070 ただし、Gaucheでは複合コンディション自体は複合オブジェクトとしては実装されていません。
15071 @c COMMON
15072
15073 @c EN
15074 This module is mainly provided for the compatibility; used with
15075 R7RS records (@pxref{Record types}), you can have a portable
15076 multiple inheritance of records.
15077 @c JP
15078 このモジュールは主に互換性のために提供されています。
15079 R7RSレコード(@pxref{Record types})と併用すれば、
15080 移植可能な形でレコードの多重継承を扱うことができます。
15081 @c COMMON
15082 @end deftp
15083
15084 @defun make-compound obj @dots{}
15085 [SRFI-222]
15086 @c MOD srfi.222
15087 @c EN
15088 Returns a compound objects having @var{obj} @dots{} as its subobjects.
15089 Each @var{obj} can any Scheme object, but
15090 if @var{obj} is a compound object itself, it is expanded into its
15091 subobjects:
15092 @c JP
15093 @var{obj} @dots{}をサブオブジェクトとして持つ複合オブジェクトを作って返します。
15094 @var{obj}は任意のSchemeオブジェクトですが、それが複合オブジェクトだった場合は、
15095 そのサブオブジェクトがそこに展開されて使われます。
15096 @c COMMON
15097
15098 @example
15099 (make-compound 1 2 3)
15100 @result{} #<compound-object (1 2 3)>
15101 (make-compund 0 (make-compound 1 2 3) 4 5)
15102 @result{} #<compound-object (0 1 2 3 4 5)>
15103 @end example
15104 @end defun
15105
15106 @defun compound? obj
15107 [SRFI-222]
15108 @c MOD srfi.222
15109 @c EN
15110 Returns @code{#t} iff @var{obj} is a compound object.
15111 @c JP
15112 @var{obj}が複合オブジェクトなら@code{#t}を、そうでなければ@code{#f}を返します。
15113 @c COMMON
15114 @end defun
15115
15116 @defun compound-subobjects obj
15117 [SRFI-222]
15118 @c MOD srfi.222
15119 @c EN
15120 If @var{obj} is a compound, returns a list of its subobjects.
15121 Otherwise, returns a 1-element list of @var{obj}.
15122
15123 That is, it always returns a list of non-compound objects.
15124 @c JP
15125 @var{obj}が複合オブジェクトなら、そのサブオブジェクトのリストを、
15126 そうでなければ@var{obj}ひとつを要素とするリストを返します。
15127
15128 すなわち、返されるのは常に、複合オブジェクトを含まないオブジェクトのリストです。
15129 @c COMMON
15130 @end defun
15131
15132 @defun compound-length obj
15133 [SRFI-222]
15134 @c MOD srfi.222
15135 @c EN
15136 If @var{obj} is a compound, returns the number of its subobjects.
15137 Otherwise, returns 1.
15138 @c JP
15139 @var{obj}が複合オブジェクトなら持っているサブオブジェクトの数を、
15140 そうでなければ1を返します。
15141 @c COMMON
15142 @end defun
15143
15144 @defun compound-ref obj k
15145 [SRFI-222]
15146 @c MOD srfi.222
15147 @c EN
15148 Returns @var{k}-th subobject of @var{obj} if it is a compound.
15149 Othrewise, @var{k} must be zero and @var{obj} itself is returned.
15150 @c JP
15151 @var{obj}が複合オブジェクトなら@var{k}番目のサブオブジェクトを返します。
15152 そうでなければ、@var{k}は0でなければならず、その場合@var{obj}自身が返されます。
15153 @c COMMON
15154
15155 @c EN
15156 An error is thrown if @var{k} is not a nonnegative exact integer
15157 or out of range.
15158 @c JP
15159 @var{k}が非負の正確な整数でなかったり、指定可能範囲外であればエラーが投げられます。
15160 @c COMMON
15161 @end defun
15162
15163 @defun compound-map mapper obj
15164 [SRFI-222]
15165 @c MOD srfi.222
15166 @c EN
15167 Returns a compound object whose subobjects are result of applying
15168 @var{mapper} on each subobject of @var{obj}. If @var{obj} is not
15169 a compound, it is treated as if a compound with @var{obj} as a sole
15170 subobject. Note that if @var{mapper} returns a compound, its subobjects
15171 are spliced in place. Thus the number of subobjects of the result may differ
15172 from the number of subobjects of @var{obj}.
15173 @c JP
15174 @var{obj}の持つサブオブジェクトそれぞれに@var{mapper}を適用し、その結果を集めた
15175 複合オブジェクトを作って返します。@var{obj}が複合オブジェクトでなければ、
15176 あたかも@var{obj}自身を唯一のサブオブジェクトとする複合オブジェクトであるかのように
15177 扱われます。@var{mapper}が複合オブジェクトを返した場合、そのサブオブジェクトが
15178 取り出されて結果に使われることに注意してください。つまり、
15179 結果の持つサブオブジェクトの数は、@var{obj}の持つサブオブジェクトと異なる場合があります。
15180 @c COMMON
15181
15182 @example
15183 (compound-map (cut + 1 <>) (make-compound 1 2 3))
15184 @result{} #<compound (2 3 4)>
15185 (compound-map (cut make-compound <> 'x) (make-compound 1 2 3))
15186 @result{} #<compound (1 x 2 x 3 x)>
15187 (compound-map (cut + 1 <>) 3)
15188 @result{} #<compound (4)>
15189 @end example
15190 @end defun
15191
15192 @defun compound-map->list mapper obj
15193 [SRFI-222]
15194 @c MOD srfi.222
15195 @c EN
15196 Returns a list of results of applying @var{mapper} on each subobjects
15197 of @var{obj}. If @var{obj} is not a compound, @var{mapper} is directly
15198 applied on @var{obj}.
15199 @c JP
15200 @var{mapper}を@var{obj}の各サブオブジェクトに適用し、結果のリストを返します。
15201 @var{obj}が複合オブジェクトでなければ、@var{mapper}を直接@var{obj}に適用し、
15202 結果をリストにくるんで返します。
15203 @c COMMON
15204
15205 @c EN
15206 Unlike @code{compound-map}, the result of @var{mapper} appears as is
15207 in the result list, even when it is a compound object. Hence the
15208 length of the result list always matches @code{(compound-length obj)}.
15209 @c JP
15210 @code{compound-map}と異なり、@var{mapper}の結果が複合オブジェクトであった場合でも
15211 それがそのまま結果のリストに現れます。つまり、結果のリストの長さは常に
15212 @code{(compound-length obj)}と同じです。
15213 @c COMMON
15214
15215 @example
15216 (compound-map->list (cut + 1 <>) (make-compound 1 2 3))
15217 @result{} (2 3 4)
15218 (compound-map->list (cut make-compound <> 'x) (make-compound 1 2 3))
15219 @result{} (#<compound (1 x)> #<compound (2 x)> #<compound (3 x)>)
15220 (compound-map->list (cut + 1 <>) 3)
15221 @result{} (4)
15222 @end example
15223 @end defun
15224
15225 @defun compound-filter pred obj
15226 [SRFI-222]
15227 @c MOD srfi.222
15228 @c EN
15229 Collect subobjects of @var{obj} that satisfies @var{pred}, and
15230 returns a compound that consists of them. If @var{obj} is not a compound,
15231 it is treated as if it is a compound with @var{obj} as a sole subobject.
15232 @c JP
15233 @var{obj}のサブオブジェクトにそれぞれ@var{pred}を適用し、それが真の値を返した
15234 サブオブジェクトのみを集めて新たな複合オブジェクトを作って返します。
15235 @var{obj}が複合オブジェクトでなければ、あたかもそれ自身を唯一のサブオブジェクトに持つ
15236 複合オブジェクトのように扱われます。
15237 @c COMMON
15238
15239 @example
15240 (compound-filter odd? (make-compound 1 2 3))
15241 @result{} #<compound (1 3)>
15242 (compound-filter odd? 1)
15243 @result{} #<compound (1)>
15244 (compound-filter odd? 2)
15245 @result{} #<compound ()>
15246 @end example
15247 @end defun
15248
15249 @defun compound-predicate pred obj
15250 [SRFI-222]
15251 @c MOD srfi.222
15252 @c EN
15253 Returns @code{#t} if @var{obj} satisfies @var{pred},
15254 or any of @var{obj}'s subobjects satisfies @var{pred}
15255 when @var{obj} is a compound. Returns @code{#f} otherwise.
15256 @c JP
15257 @var{obj}が述語@var{pred}を満たすか、@var{obj}が複合オブジェクトであり
15258 いずれかのサブオブジェクトが@var{pred}を満たせば@code{#t}を、
15259 そうでなければ@code{#f}を返します。
15260 @c COMMON
15261 @end defun
15262
15263 @defun compound-access pred acc default obj
15264 [SRFI-222]
15265 @c MOD srfi.222
15266 @c EN
15267 If @var{obj} satisfies @var{pred}, @var{acc} is applied ot @var{obj}
15268 and the result is returned. Otherwise, if @var{obj} is a compound,
15269 @var{pred} is applied on each subobject, and @var{acc} is applied
15270 on the first subobject that satisfies @var{pred}, and the result
15271 is returned. If none of the case is satisfied, @var{default} is returned.
15272 @c JP
15273 @var{obj}が述語@var{pred}を満たした場合、@var{obj}に@var{acc}が適用され、
15274 その結果が返されます。そうでなく、@var{obj}が複合オブジェクトの場合は、
15275 そのサブオブジェクトが順に@var{pred}を満たすかどうか検査され、最初に満たした
15276 サブオブジェクトに対して@var{acc}が適用され、その結果が返されます。
15277 全てに当てはまらない場合は@var{default}が返されます。
15278 @c COMMON
15279
15280 @example
15281 (define-record-type <foo> make-foo foo?
15282 (f foo-f))
15283
15284 (define-record-type <bar> make-bar bar?
15285 (b bar-b))
15286
15287 (define c (make-compound (make-foo "foo!") (make-bar "bar!") '(ca . cd)))
15288
15289 (compound-access foo? foo-f 'none c) @result{} "foo!"
15290 (compound-access bar? bar-b 'none c) @result{} "bar!"
15291 (compound-access pair? car 'none c) @result{} ca
15292 (compound-access char? char->integer 'none c) @result{} none
15293 @end example
15294 @end defun
15295
15296 @c ----------------------------------------------------------------------
15297 @node Control features, Optional arguments, Compound objects, Library modules - SRFIs
15298 @section @code{srfi.226} - Control features
15299 @c NODE 制御機構, @code{srfi.226} - 制御機構
15300
15301 @deftp {Module} srfi.226
15302 @mdindex srfi.226
15303 @c EN
15304 This srfi enhances the semantics of Scheme's fundamental concepts
15305 such as continuations and dynamic environments, to support multi-threaded
15306 programs and delimited continuations. Some R7RS primitives such as
15307 @code{call/cc} and @code{dynamic-wind} are extended
15308 to be consistent with the enhanced execution model.
15309 @c JP
15310 このSRFIは、Schemeの根本的な概念である継続や動的環境のセマンティクスを、
15311 マルチスレッドプログラムや限定継続をサポートできるように拡大するものです。
15312 @code{call/cc}や@code{dynamic-wind}といったいくつかのR7RSプリミティブは、
15313 拡大されたセマンティクスに一致するように拡張されます。
15314 @c COMMON
15315
15316 @c EN
15317 The thread API is mostly compatible with SRFI-18, and so as with
15318 Gauche's thread API (@pxref{Threads}).
15319 @c JP
15320 スレッドAPIはSRFI-18およびGaucheのスレッドAPIとほぼ互換です (@ref{Threads}参照)。
15321 @c COMMON
15322
15323 @c EN
15324 Since the enhanced features are tightly coupled with runtime, most
15325 APIs in this srfi is implemented as built-ins in Gauche.
15326 This section gives you the overview of SRFI-226 APIs and pointers
15327 to the documents.
15328 @c JP
15329 拡大された機能はランタイムと固く結びついているので、
15330 このSRFIのAPIは主にGaucheの組み込みとして実装されています。
15331 この節では、SRFI-226のAPIの一覧とドキュメントへのポインタを示します。
15332 @c COMMON
15333
15334 @c EN
15335 In 0.9.13, Gauche only implements part of SRFI-226. We'll cover its entirety
15336 in future releases.
15337 @c JP
15338 0.9.13の時点では、GaucheはSRFI-226の一部のみを実装しています。
15339 将来のリリースで全てをカバーする予定です。
15340 @c COMMON
15341
15342 @c EN
15343 SRFI-226 is an upward compatible extension of R7RS. However, Gauche has also
15344 extended R7RS control features in regards of multi-threaded
15345 programs, and there are subtle incompatibilites. We'll move to
15346 full SRFI-226 compatibility, but we also provide backward-compatible
15347 interface. If you use @code{srfi.226}, you'll get SRFI-226
15348 behavior.
15349 @c JP
15350 SRFI-226はR7RSの上位互換になっています。
15351 ただ、GaucheはGaucheでR7RSの制御機構をマルチスレッド向けに拡張していて、
15352 SRFI-226と非互換であった部分があります。
15353 徐々にSRFI-226互換に移行してゆきますが、後方互換なインタフェースも提供します。
15354 @code{srfi.226}をuseした場合はSRFI-226の振る舞いになります。
15355 @c COMMON
15356 @end deftp
15357
15358 @c EN
15359 Here's a list of SRFI-226 APIs and how Gauche supports them.
15360 @c JP
15361 以下が、SRFI-226のAPIのリストとGaucheのサポート状況です。
15362 @c COMMON
15363
15364 @table @b
15365 @item Continuation prompts
15366 @table @code
15367 @item &continuation
15368 @itemx make-continuation-violation
15369 @itemx continuation-violation?
15370 @itemx continuation-violation-prompt-tag
15371 @xref{Conditions}
15372 @item make-continuation-prompt-tag
15373 @itemx default-continuation-prompt-tag
15374 @itemx continuation-prompt-tag?
15375 @itemx call-with-continuation-prompt
15376 @itemx abort-current-continuation
15377 @xref{Continuation prompts}.
15378 @end table
15379
15380 @item Continuations
15381 @table @code
15382 @item call-with-non-comosable-continuation
15383 @itemx call-with-composable-continuation
15384 Not implemented yet.
15385 @item call-with-current-continuation
15386 @itemx call/cc
15387 @xref{Continuations}.
15388 @item call-in-continuation
15389 @itemx call-in
15390 Not implemented yet.
15391 @item call-with-continuation-barrier
15392 Not implemented yet.
15393 @item continuation-prompt-available?
15394 Not implemented yet.
15395 @item dynamic-wind
15396 @xref{Continuations}.
15397 @item unwind-protect
15398 @xref{High-level exception handling mechanism}.
15399 @end table
15400
15401 @item Shift and reset
15402 @table @code
15403 @item shift-at
15404 @itemx reset-at
15405 Not implemented yet.
15406 @item shift
15407 @itemx reset
15408 @xref{Partial continuations}. However, current implementation
15409 of @code{shift}/@code{reset} hasn't integrated to SRFI-226 model
15410 yet.
15411 @end table
15412
15413 @item Inspection
15414 @table @code
15415 @item continuation?
15416 @itemx non-composable-continuation?
15417 Not implemented yet.
15418 @end table
15419
15420 @item Continuation marks
15421 @table @code
15422 @item with-continuation-mark
15423 @itemx with-continuation-marks
15424 @itemx call-with-immediate-continuation-mark
15425 @itemx continuation-marks
15426 @itemx current-continuation-marks
15427 @itemx continuation-mark-set?
15428 @itemx continuation-mark-set->list
15429 @itemx continuation-mark-set-first
15430 @xref{Continuation marks}.
15431 @item continuation-mark-set->list*
15432 @itemx continuation-mark-set->iterator
15433 Not implemented yet.
15434 @item make-continuation-mark-key
15435 @itemx continuation-mark-key?
15436 @xref{Continuation marks}.
15437 @end table
15438
15439 @item Parameter objects
15440 @table @code
15441 @item make-parameter
15442 @itemx make-thread-parameter
15443 @xref{Parameters}. Gauche's built-in @code{make-parameter} works
15444 in a compatibility mode for now. If you use @code{srfi.226},
15445 @code{make-parameter} works as specified in SRFI-226.
15446 @item parameter?
15447 @xref{Parameters}.
15448 @item parameterize
15449 @xref{Parameters}. Gauche's built-in @code{parameterize} works
15450 in a compatibility mode for now. If you use @code{srfi.226},
15451 @code{make-parameter} works as specified in SRFI-226.
15452 @item current-parameterization
15453 @itemx parameterization?
15454 @itemx call-with-parameterization
15455 @xref{Parameters}.
15456 @item temporarily
15457 @xref{Dynamic states}.
15458 @end table
15459
15460 @item Fluids
15461 @table @code
15462 @item define-fluid
15463 @itemx define-thread-fluid
15464 @itemx define-fluidified
15465 @itemx fluid-let
15466 @itemx fluid-let*
15467 @itemx fluid-parameter
15468 Not implemented yet.
15469 @end table
15470
15471 @item Initial continuations
15472 @table @code
15473 @item call-with-initial-continuation
15474 Not implemented yet.
15475 @end table
15476
15477 @item Promises
15478 @table @code
15479 @item delay
15480 @itemx promise?
15481 @itemx force
15482 @itemx make-promise
15483 @xref{Delay force and lazy}.
15484 Gauche's built-ins are SRFI-226 compatible.
15485 @end table
15486
15487 @item Exceptions
15488 @table @code
15489 @item with-exception-handler
15490 @itemx current-exception-handler
15491 @itemx exception-handler-stack
15492 @xref{Low-level exception handling mechanism}.
15493 Gauche's built-ins are SRFI-226 compatible.
15494 @item raise
15495 @itemx raise-continuable
15496 @xref{Signaling exceptions}.
15497 @item guard
15498 @xref{High-level exception handling mechanism}.
15499 @end table
15500
15501 @item Conditions
15502 @table @code
15503 @item &parameterization
15504 @itemx make-parameterization-condition
15505 @itemx parameterization-condition?
15506 @itemx condition-parameterization
15507 Not implemented yet.
15508 @item &continuation-marks
15509 @itemx make-continuation-marks-condition
15510 @itemx continuation-marks-condition?
15511 @itemx condition-continuation-marks
15512 Not implemented yet.
15513 @item &exception-handler-stack
15514 @itemx make-exception-handler-stack-condition
15515 @itemx exception-handler-stack-condition?
15516 @itemx condition-exception-handler-stack
15517 Not implemented yet.
15518 @end table
15519
15520 @item Time objects
15521 @table @code
15522 @item time?
15523 @itemx current-time
15524 @itemx seconds+ time
15525 @xref{Time}.
15526 @end table
15527
15528 @item Threads
15529 @table @code
15530 @item &thread
15531 @itemx make-thread-condition
15532 @itemx thread-condition?
15533 @itemx &uncaught-exception
15534 @itemx make-uncaught-exception
15535 @itemx uncaught-exception-condition?
15536 @itemx uncaught-exception-condition-reason
15537 @itemx &thread-already-terminated
15538 @itemx make-thread-already-terminated-condition
15539 @itemx thread-already-terminated-condition?
15540 @itemx &thread-timeout
15541 @itemx make-thread-timeout-condition
15542 @itemx thread-timeout-condition?
15543 @itemx &thread-abandoned-mutex
15544 @itemx make-thread-abandoned-mutex-condition
15545 @itemx thread-abandoned-mutex-condition?
15546 @itemx &concurrent-modification
15547 @itemx make-concurrent-modification-violation
15548 @itemx concurrent-modification-violation?
15549 @xref{Thread exceptions}.
15550 @item make-thread
15551 @itemx thread?
15552 @itemx current-thread
15553 @itemx thread-start!
15554 @itemx thread-yield!
15555 @itemx thread-sleep!
15556 @itemx thread-terminate!
15557 @itemx thread-schedule-terminate!
15558 @itemx thread-join!
15559 @xref{Threads}.
15560
15561 @item make-mutex
15562 @itemx mutex?
15563 @itemx mutex-state
15564 @itemx mutex-lock!
15565 @itemx mutex-unlock!
15566 @xref{Mutex}.
15567
15568 @item make-condition-variable
15569 @itemx condition-variable?
15570 @itemx condition-variable-signal!
15571 @itemx condition-variable-broadcast!
15572 @xref{Condition variable}.
15573
15574 @item make-thread-local
15575 @itemx thread-local?
15576 @itemx tlref
15577 @itemx tlset!
15578 @xref{Thread local storage}.
15579
15580 @item current-interrupt-level
15581 @itemx disable-interrupts!
15582 @itemx enable-interrupts!
15583 @itemx with-interrupts-disabled
15584 @itemx with-interrupts-enabled
15585 @itemx thread-interrupt!
15586 Not implemented yet.
15587 @end table
15588 @end table
15589
15590
15591
15592 @c ----------------------------------------------------------------------
15593 @node Optional arguments, Composing comparators, Control features, Library modules - SRFIs
15594 @section @code{srfi.227} - Optional arguments
15595 @c NODE 省略可能引数, @code{srfi.227} - 省略可能引数
15596
15597 @deftp {Module} srfi.227
15598 @deftpx {Module} srfi.227.definitions
15599 @mdindex srfi.227
15600 @mdindex srfi.227.definitions
15601 @c EN
15602 This srfi provies macros to specify optional arguments portably.
15603 Gauche supports optional arguments in extended formals
15604 (@pxref{Making procedures}), but it is not portable.
15605 @c JP
15606 このsrfiは、ポータブルに省略可能引数を書く方法を提供します。
15607 Gaucheは拡張引数構文で省略可能引数を指定できますが、ポータブルではありません
15608 (@ref{Making procedures}参照)。
15609 @c COMMON
15610
15611 @c EN
15612 The main module, @code{srfi.227}, exports macros
15613 @code{opt-lambda}, @code{opt*-lambda}, @code{let-optionals}, and
15614 @code{let-optionals*}. Note that this @code{let-optionals*} has different
15615 semantics from Gauche's built-in @code{let-optionals*}.
15616 @c JP
15617 モジュール@var{srfi.227}はマクロ
15618 @code{opt-lambda}、@code{opt*-lambda}、@code{let-optionals}、
15619 @code{let-optionals*}をexportします。この@code{let-optionals*}は
15620 Gauche組み込みの@code{let-optionals*}と異なることに注意してください。
15621 @c COMMON
15622
15623 @c EN
15624 The submodule @code{srfi.227.definitions} exports two more
15625 macros, @code{define-optionals} and @code{define-optionals*}.
15626 @c JP
15627 サブモジュール@code{srfi.227.definitions}はさらに2つのマクロ、
15628 @code{define-optionals}と@code{define-optionals*}をexportします。
15629 @c COMMON
15630 @end deftp
15631
15632 @defmac opt-labmda opt-formals body @dots{}
15633 @defmacx opt*-lambda opt-formals body @dots{}
15634 [SRFI-227]
15635 @c MOD srfi.227
15636 @c EN
15637 Evaliates to a procedure, similar to @code{lambda}.
15638 @c JP
15639 @code{lambda}と同じように、手続きへと評価されます。
15640 @c COMMON
15641
15642 @c EN
15643 The @var{opt-formals} is either one of the following form:
15644 @c JP
15645 @var{opt-formals}は以下のいずれかの形式です。
15646 @c COMMON
15647 @example
15648 (@var{var} @dots{} (@var{optvar} @var{init}) @dots{})
15649 (@var{var} @dots{} (@var{optvar} @var{init}) @dots{} . @var{restvar})
15650 @end example
15651
15652 @c EN
15653 @var{Var}, @var{optvar}, and @var{restvar} are identifiers.
15654 Each @var{init} is an expression.
15655 @c JP
15656 @var{var}、@code{optvar}、@code{restvar}は識別子で、
15657 @var{init}は式です。
15658 @c COMMON
15659
15660 @c EN
15661 @var{Var} @dots{} are required arguments. @var{Optvar} @dots{} are
15662 optional arguments, and when no corresponding parameter is provided,
15663 @var{init} is evaluated and used as the value of the argument.
15664 @c JP
15665 @var{var} @dots{}は必須引数を指定します。
15666 @var{optvar} @dots{}は省略可能引数で、与えられた実引数が足りない場合は
15667 対応する@var{init}が評価されその値に束縛されます。
15668 @c COMMON
15669
15670 @c EN
15671 In the first form, giving exessive arguments throws an error; in the
15672 second form, excessive arguments are bound to @var{restvar} as a list.
15673 @c JP
15674 最初の形式では、余分な引数が与えられるとエラーが投げられます。
15675 二番目の形式では、余分な引数はリストとして@var{restvar}に束縛されます。
15676 @c COMMON
15677
15678 @c EN
15679 The scope of @var{init} differs between @code{opt-lambda} and
15680 @var{opt-lambda*}. With @code{opt-lambda}, @var{init}s are evaluated
15681 in the scope where @code{opt-lambda} is placed. With @var{opt*-lambda},
15682 the scope of @var{init}s also includes preceding @var{var}s and @var{optvar}s.
15683 @c JP
15684 @var{init}のスコープは@code{opt-lambda}と@code{opt*-lambda}で異なります。
15685 @code{opt-lambda}では、@var{init}は@code{opt-lambda}が置かれた環境で評価されます。
15686 @code{opt*-lambda}ではそれに加え、先行する@var{var}と@var{optvar}も
15687 スコープに含まれます。
15688 @c COMMON
15689
15690 @example
15691 (let ((x 1))
15692 ((opt-lambda (x (y (+ x 1))) (list x y)) 10))
15693 @result{} (10 2)
15694
15695 (let ((x 1))
15696 ((opt*-lambda (x (y (+ x 1))) (list x y)) 10))
15697 @result{} (10 11)
15698 @end example
15699
15700 @c EN
15701 Note: @code{(opt*-lambda (v @dots{} (w init) @dots{}) body @dots{}} is the same
15702 as Gauche's
15703 @code{(lambda (v @dots{} :optional (w init) @dots{}) body @dots{})}.
15704 @c JP
15705 @code{(opt*-lambda (v @dots{} (w init) @dots{}) body @dots{}}は
15706 Gaucheの拡張引数を使った
15707 @code{(lambda (v @dots{} :optional (w init) @dots{}) body @dots{})}
15708 と同じです。
15709 @c COMMON
15710 @end defmac
15711
15712 @defmac let-optionals expr opt-formals body @dots{}
15713 @defmacx let-optionals* expr opt-formals body @dots{}
15714 [SRFI-227]
15715 @c MOD srfi.227
15716 @c EN
15717 Syntax sugar to decompose the result of @var{expr} using @var{opt-formals}:
15718 @c JP
15719 @var{opt-formal}を使って@var{expr}の結果を分解する糖衣構文です。
15720 @c COMMON
15721
15722 @example
15723 (let-optionals expr opt-formals body @dots{})
15724 @equiv{} ((opt-lambda opt-formals body @dots{}) expr)
15725
15726 (let-optionals* expr opt-formals body @dots{})
15727 @equiv{} ((opt*-lambda opt-formals body @dots{}) expr)
15728 @end example
15729
15730 @c EN
15731 Note: Gauche has built-in @code{let-optionals*}, which is different
15732 from this srfi. Gauche's doesn't allow requried parameters.
15733 @xref{Making procedures}, for the details.
15734 @c JP
15735 註: Gaucheの組み込みの@code{let-optionals*}は、
15736 必須パラメータを取らないという点でこのsrfiと異なります。
15737 @ref{Making procedures}参照。
15738 @c COMMON
15739 @end defmac
15740
15741 @defmac define-optionals (name . opt-formals) body @dots{}
15742 @defmacx define-optionals* (name . opt-formals) body @dots{}
15743 [SRFI-227]
15744 @c MOD srfi.227.definitions
15745 @c EN
15746 These two forms are provided in a submodule @code{srfi.227.definitions}.
15747 @c JP
15748 これら2つのフォームはサブモジュール@code{srfi.227.definitions}で提供されます。
15749 @c COMMON
15750
15751 @example
15752 (define-optionals (name . opt-formals) body @dots{})
15753 @equiv{} (define name (opt-lambda opt-formals body @dots{}))
15754
15755 (define-optionals* (name . opt-formals) body @dots{})
15756 @equiv{} (define name (opt*-lambda opt-formals body @dots{}))
15757 @end example
15758 @end defmac
15759
15760
15761 @c ----------------------------------------------------------------------
15762 @node Composing comparators, Tagged procedures, Optional arguments, Library modules - SRFIs
15763 @section @code{srfi.228} - Composing comparators
15764 @c NODE 比較器の合成, @code{srfi.228} - 比較器の合成
15765
15766 @deftp {Module} srfi.228
15767 @mdindex srfi.228
15768 @c EN
15769 This module provides a few utility procedures to compose
15770 comparators for typical aggregates. For the details
15771 of comparators, @pxref{Basic comparators}, and @pxref{Comparators}.
15772 @c JP
15773 このモジュールは、典型的な集合型のために比較器を合成するいくつかのユーティリティを
15774 提供します。比較器については
15775 @ref{Basic comparators}と@ref{Comparators}を参照してください。
15776 @c COMMON
15777 @end deftp
15778
15779 @defun make-wrapper-comparator type-test unwrap contents-comparator
15780 [SRFI-228]
15781 @c MOD srfi.228
15782 @c EN
15783 Creates a comparator for objects that wraps other entities.
15784 @c JP
15785 何らかの要素をくるむオブジェクトのための比較器を作ります。
15786 @c COMMON
15787
15788 @c EN
15789 First it tests the given object with @var{type-test}; then, it calls
15790 @var{unwrap} on it to extract contents, and use @code{contents-comparator}
15791 on the exracted contents.
15792 @c JP
15793 作られた比較器は、@var{type-test}で適合性を調べ、適合するなら
15794 @var{unwrap}をオブジェクトに適用して、得られた結果について
15795 @code{contents-comparator}を使って比較します。
15796 @c COMMON
15797
15798 @c EN
15799 For example, suppose you want to deal with a string inside a box.
15800 You can create a comparator for such structs (@code{strbox-comparator})
15801 as follows:
15802 @c JP
15803 例えば、文字列をboxに入れたものを扱うとしましょう。
15804 そういうオブジェクトのための比較器@code{strbox-comparator}は、次のとおり定義できます。
15805 @c COMMON
15806
15807 @example
15808 (define (strbox? obj)
15809 (and (box? obj) (string? (unbox obj))))
15810
15811 (define strbox-comparator
15812 (make-wrapper-comparator strbox? unbox string-comparator))
15813 @end example
15814
15815 @c EN
15816 Then you can compare to strboxes with @code{<?} etc., or make
15817 a hashtable or treemap by passing @code{strbox-comparator} as a comparator.
15818 @c JP
15819 こう定義しておけば、boxに入った文字列を@code{<?}等で比較したり、
15820 ハッシュテーブルやツリーマップに格納したりすることができます。
15821 @c COMMON
15822 @end defun
15823
15824 @defun make-product-comparator comparator @dots{}
15825 [SRFI-228]
15826 @c MOD srfi.228
15827 @c EN
15828 Creates a comparator for objects of a @emph{common} type of the types
15829 dealt with given comparators. Combined with @code{make-wrapper-comparator},
15830 this can also be used to create a comparator for the product types.
15831 @c JP
15832 与えられた比較器が扱う型に共通する型のための比較器を作ります。
15833 @code{make-wrapper-comparator}と合わせると、直積型の比較器を簡単に作れます。
15834 @c COMMON
15835
15836 @c EN
15837 The type predicate of the resulting comparator is satisfied iff
15838 the object satisfies every type predicates of @var{comparator}s.
15839 @c JP
15840 作られる比較器の型検査述語は、与えられた@var{comparator}の型検査述語全てを満たす時に
15841 満たされるものです。
15842 @c COMMON
15843
15844 @c EN
15845 The equality predicate is satisfied iff two objects are equal
15846 to each other according to all @var{comparator}s.
15847 @c JP
15848 作られる比較器の等価判定述語は、全ての@var{comparator}の等価判定を満たす時に
15849 満たされます。
15850 @c COMMON
15851
15852 @c EN
15853 The ordering predicate is defined only if all the @var{comparator}s
15854 have ordering predicate. Two objects can be ordered by applying
15855 ordering predicate of @var{comparator}s left to right. If an ordering
15856 predicate returns true, the ordering predicate of the product comparator
15857 immediately returns true. Otherwise, two objects are checked with
15858 the equality predicate of the current comparator. If two objects are
15859 not equal, or no more comparators are left, then the ordering predicate
15860 of the product comparator returns @code{#f}. Otherwise, the next
15861 comparator is tried.
15862 @c JP
15863 順序判定述語は、@var{comparator}全てが順序判定述語を持つ場合に限り定義され、
15864 次のとおり動作します。二つのオブジェクトは、@var{comparator}の左から順に、
15865 その順序判定述語に渡されます。最初の@var{comparator}の順序判定述語が真を返したら
15866 全体の順序判定述語は直ちに真を返します。そうでなければ、最初の@var{comparator}の
15867 等価判定述語が呼ばれ、それが偽を返したら全体の順序判定述語は直ちに偽を返します。
15868 最初の@var{comparator}の等価判定述語が真であれば、次の@var{comparator}に進み、
15869 同様に繰り返します。次の@var{comparator}が無くなれば偽が返されます。
15870 @c COMMON
15871
15872 @c EN
15873 The hash function is defined only if all the @var{comparator}s
15874 have hash functions. Each hash function is called, and the
15875 results are combined to produce the final hash value.
15876 @c JP
15877 ハッシュ関数は@var{comparator}全てがハッシュ関数を持つ場合に限り定義されます。
15878 それぞれの@var{comparator}のハッシュ関数がオブジェクトに対して呼ばれ、
15879 そのハッシュ値を組み合わせたものが全体のハッシュ値となります。
15880 @c COMMON
15881
15882 @c EN
15883 The following example defines a comparator of a record type
15884 based on the comparators of the fields.
15885 @c JP
15886 次の例は、レコード型の比較器を、フィールドの比較器から合成します。
15887 @c COMMON
15888
15889 @example
15890 (define-record-type <member> make-member member?
15891 (name member-name) ; string
15892 (age member-age)) ; integer
15893
15894 (define member-comparator
15895 (make-product-comparator
15896 (make-wrapper-comparator member? member-name string-comparator)
15897 (make-wrapper-comparator member? member-age integer-comparator)))
15898 @end example
15899 @end defun
15900
15901 @defun make-sum-comparator comparator @dots{}
15902 [SRFI-228]
15903 @c MOD srfi.228
15904 @c EN
15905 Creates a comparator for objects of a @emph{union} type of the types
15906 dealt with the given comparators.
15907 @c JP
15908 与えられた比較器が扱う型の直和型を扱える比較器を作ります。
15909 @c COMMON
15910
15911 @c EN
15912 The type predicate of the created comparator
15913 is satisfied if the given object satisfies a type
15914 predicate of any one of the given comparators. The leftmost comparator
15915 that the object satisfies is called the @emph{relevant comparator}.
15916 @c JP
15917 返される型検査述語は、与えられたオブジェクトが@var{comparator} @dots{}の
15918 型検査述語のいすれかを満たせば真を返します。
15919 最初に型検査述語が満たされた比較器を「妥当な比較器」と呼びます。
15920 @c COMMON
15921
15922 @c EN
15923 The equality predicate is satisfied if the two objects share the
15924 relevant comparator and are equal to each other with regard to the
15925 comparator.
15926 @c JP
15927 等価判定述語は、二つの引数の妥当な比較器が等しく、
15928 その比較器の等価判定述語が真を返した場合にのみ真となります。
15929 @c COMMON
15930
15931 @c EN
15932 The ordering predicate works as follows: First, relevant comparators
15933 of two given objects are picked. If the relevant comparator of
15934 the first object is to the left of the relevant comparator of
15935 the second, the ordering predicate of the sum comparator is satisfied.
15936 If the first one is to the right of the second one, the ordering predicate
15937 is unsatisfied. If two objects share the relevant comparator,
15938 they are oreder by the ordering predicate of the relevant comparator.
15939 @c JP
15940 順序判定述語は次のとおり動作します。
15941 まず、各引数の妥当な比較器が選ばれます。最初の引数の妥当な比較器が
15942 二番目の引数の妥当な比較器より左にあれば、順序判定述語は満たされます
15943 (つまり最初の引数の方が「小さい」とみなされます)。
15944 最初の引数の妥当な比較器が二番目のそれより右にあれば、順序判定述語は満たされません。
15945 二つの引数の妥当な比較器が等しければ、その順序判定述語の結果がそのまま返されます。
15946 @c COMMON
15947
15948 @c EN
15949 The hash function returns the hash value computed by the relevant
15950 comparator of the given object.
15951 @c JP
15952 ハッシュ関数は、引数の妥当な比較器のハッシュ関数をそのまま使います。
15953 @c COMMON
15954 @end defun
15955
15956 @defvar comparator-one
15957 [SRFI-228]
15958 @c MOD srfi.228
15959 @c EN
15960 This is a comparator that works as a unit element for the product
15961 comparator. It accepts any object and all values are equal; that is,
15962 its type predcate and its equality predicate always return @code{#t},
15963 its ordering predicate always returns @code{#f}, and its hash
15964 function always returns 0.
15965 @c JP
15966 これは直積型の比較器の単位元として動作する比較器です。
15967 いかなるオブジェクトも許容し、全てのオブジェクトを等価とみなします。
15968 つまり、その型検査述語と等価判定述語は常に@code{#t}を返します。
15969 順序判定述語は常に@code{#f}を返し、ハッシュ関数は常に0を返します。
15970 @c COMMON
15971 @end defvar
15972
15973 @defvar comparator-zero
15974 [SRFI-228]
15975 @c MOD srfi.228
15976 @c EN
15977 This is a comparator that works as a unit element for the sum
15978 comparator. Its domain is empty; that is, its type predicate always
15979 returns @code{#f}, and it is an error to invoke its equality predicate,
15980 ordering predicate and hash function.
15981 @c JP
15982 これは直和型の比較器の単位元として動作する比較器です。
15983 この比較器が対象とする定義域は空集合です。すなわち、型検査述語は常に@code{#f}を返します。
15984 等価判定述語、順序判定述語、およびハッシュ関数はエラーを投げます。
15985 @c COMMON
15986 @end defvar
15987
15988 @c ----------------------------------------------------------------------
15989 @node Tagged procedures, Atomic operations, Composing comparators, Library modules - SRFIs
15990 @section @code{srfi.229} - Tagged procedures
15991 @c NODE 手続きタグ, @code{srfi.229} - 手続きタグ
15992
15993 @deftp {Module} srfi.229
15994 @mdindex srfi.229
15995 @c EN
15996 This srfi allows to attach auxiliary information (tag) to a procedure.
15997 A tag can be attached when a procedure is created, and later retrieved.
15998 A procedure itself should be considered as an immutable entity,
15999 so you can't attach or remove a tag to an existing procedure
16000 (although you can attach a mutable structure as a tag and mutate
16001 it later; much like the closed environment can be mutated).
16002 @c JP
16003 このsrfiは、手続きに補助的な情報(タグ)を付加できるようにするものです。
16004 タグは手続きを作るときに与えることができて、後で取り出すことができます。
16005 手続きは変更不可なオブジェクトであり、従って既にある手続きにタグを追加したり
16006 取り除いたりすることはできません。(ただ、変更可能な構造をタグとして付加して、
16007 その構造を後で変更することはできます。クロージャに閉じ込まれた環境を
16008 変更できるのと同じです)。
16009 @c COMMON
16010 @end deftp
16011
16012 @defmac lambda/tag expr formals body @dots{}
16013 [SRFI-229]
16014 @c MOD srfi.229
16015 @c EN
16016 Evaluates @var{expr}, and returns a procedure that is
16017 the same as @code{(lambda formals body @dots{})} except that
16018 the value of @var{expr} is attached as a tag to the resulting
16019 procedure. The tag can be retrieved with @code{procedure-tag}.
16020 @c JP
16021 @var{expr}を評価し、その値をタグとして持つ手続き@code{(lambda formals body @dots{})}を
16022 返します。タグは@code{procedure-tag}で取り出すことができます。
16023 @c COMMON
16024 @end defmac
16025
16026 @defmac case-lambda/tag expr clause @dots{}
16027 [SRFI-229]
16028 @c MOD srfi.229
16029 @c EN
16030 Each @var{clause} is @code{(formals body @dots{})}, much like
16031 the ordinary @code{case-lambda}.
16032
16033 First evaluates @var{expr}, and returns a procedure that is
16034 the same as @code{(case-lambda clause @dots{})}, excpet that
16035 the value of @var{expr} is attached as a tag to the resulting
16036 procedure. The tag can be retrieved with @code{procedure-tag}.
16037 @c JP
16038 各@var{clause}は、通常の@code{case-lambda}と同様に
16039 @code{(formals body @dots{})}という形式です。
16040
16041 まず@var{expr}を評価し、その値をタグとして持つ、
16042 @code{(case-lambda clause @dots{})}で作られる手続きを返します。
16043 タグは@code{procedure-tag}で取り出すことができます。
16044 @c COMMON
16045 @end defmac
16046
16047 @defun procedure/tag? obj
16048 [SRFI-229]
16049 @c MOD srfi.229
16050 @c EN
16051 Returns @code{#t} iff @var{obj} is a procedure and has a tag.
16052 @c JP
16053 @var{obj}が手続きであり、タグを持っていたら@code{#t}を返します。
16054 @c COMMON
16055 @end defun
16056
16057 @defun procedure-tag proc
16058 [SRFI-229]
16059 @c MOD srfi.229
16060 @c EN
16061 Returns a tag of @var{proc}, which must be a tagged procedure.
16062 If @var{proc} is not a procedure or not tagged, an error
16063 is signaled.
16064 @c JP
16065 @var{proc}がタグ付き手続きであればそのタグを返します。
16066 @var{proc}がタグ付き手続きでなければエラーが投げられます。
16067 @c COMMON
16068 @end defun
16069
16070
16071 @c ----------------------------------------------------------------------
16072 @node Atomic operations, Flexible curried procedures, Tagged procedures, Library modules - SRFIs
16073 @section @code{srfi.230} - Atomic operations
16074 @c NODE アトミックな操作, @code{srfi.230} - アトミックな操作
16075
16076 @deftp {Module} srfi.230
16077 @mdindex srfi.230
16078 This srfi defines a set of data types and operations that perform
16079 certain dereference and modification operations atomically.
16080 The interface is similar to C++'s atomic operation library.
16081
16082 The srfi also defines sevaral relaxed memory order constraints.
16083 In the current Gauche operations, those operation involves VM-level
16084 procedure calls and all operations are done with sequentially consistent
16085 order, no matter what @var{memory-order} argument is.
16086 Other Scheme implementations that inline-compiles these
16087 operations may emit more efficient code with relaxed memory orders.
16088
16089 Gauche's implementation does utilize lock-free atomic operations,
16090 so they may still faster than using mutexes (@pxref{Mutex}).
16091 @end deftp
16092
16093 @subheading Memory order
16094
16095 @defmac memory-order symbol
16096 [SRFI-230]
16097 @c MOD srfi.230
16098 If @var{symbol} must be one of the following symbols specifying
16099 memory order: @code{relaxed}, @code{aquire}, @code{release},
16100 @code{aquire-release}, or @code{sequentially-consistent},
16101 it is returned as is. Otherwise, a syntax error is thrown.
16102 This can be used instaed of @code{quote} to statically check
16103 the validity of the symbol.
16104
16105 In Gauche's current implementation, all atomic operations are
16106 done in @code{sequentially-consistent}, no matter what memory order
16107 you specify. Portable code may use more relaxed order and expect
16108 it runs more efficiently on other implementations.
16109 @end defmac
16110
16111 @defun memory-order? obj
16112 [SRFI-230]
16113 @c MOD srfi.230
16114 Returns @code{#t} if @var{obj} is one of the valid symbols as
16115 memory order, @code{#f} otherwise.
16116 @end defun
16117
16118 @subheading Atomic flag
16119
16120 An atomic flag is a storage that holds a boolean value.
16121 The initial value is @code{#f}.
16122 Referencing the flag can only be done with
16123 @code{atomic-flag-test-and-set!}, which turns the value to @code{#t}.
16124
16125 @defun make-atomic-flag
16126 [SRFI-230]
16127 @c MOD srfi.230
16128 Returns a newly created atomic flag. Its value is @code{#f}.
16129 @end defun
16130
16131 @defun atomic-flag? obj
16132 [SRFI-230]
16133 @c MOD srfi.230
16134 Returns @code{#t} if @code{obj} is an atomic flag,
16135 @code{#f} otherwise.
16136 @end defun
16137
16138 @defun atomic-flag-test-and-set! flag :optional memory-order
16139 [SRFI-230]
16140 @c MOD srfi.230
16141 Set @var{flag}'s value to @code{#t} and returns its previous value,
16142 atomically.
16143
16144 Gauche uses sequentially consistent order regardless of
16145 the @var{memory-order} argument.
16146 @end defun
16147
16148 @defun atomic-flag-clear! flag :optional memory-order
16149 [SRFI-230]
16150 @c MOD srfi.230
16151 Reset @var{flag}'s value to @code{#f}.
16152
16153 Gauche uses sequentially consistent order regardless of
16154 the @var{memory-order} argument.
16155 @end defun
16156
16157 @subheading Atomic box
16158
16159 An atomic box is a storage that holds a Scheme value.
16160
16161 @defun make-atomic-box val
16162 [SRFI-230]
16163 @c MOD srfi.230
16164 Creates a new atomic box whose value is @var{val}.
16165 @end defun
16166
16167 @defun atomic-box? obj
16168 [SRFI-230]
16169 @c MOD srfi.230
16170 Returns @code{#t} if @code{obj} is an atomic box,
16171 @code{#f} otherwise.
16172 @end defun
16173
16174 @defun atomic-box-ref abox :optional memory-order
16175 [SRFI-230]
16176 @c MOD srfi.230
16177 Returns the content of atomic box @var{abox}.
16178
16179 Gauche uses sequentially consistent order regardless of
16180 the @var{memory-order} argument.
16181 @end defun
16182
16183 @defun atomic-box-set! abox val :optional memory-order
16184 [SRFI-230]
16185 @c MOD srfi.230
16186 Sets @var{val} as the content of atomic box @var{abox},
16187 and returns an undefined value.
16188
16189 Gauche uses sequentially consistent order regardless of
16190 the @var{memory-order} argument.
16191 @end defun
16192
16193 @defun atomic-box-swap! abox val :optional memory-order
16194 [SRFI-230]
16195 @c MOD srfi.230
16196 Sets @var{val} as the content of atomic box @var{abox},
16197 and returns the previous content, atomically.
16198
16199 Gauche uses sequentially consistent order regardless of
16200 the @var{memory-order} argument.
16201
16202 @example
16203 (define b (make-atomic-box 'foo))
16204
16205 (atomic-box-swap! box 'bar) @result{} foo
16206 (atomic-box-ref box) @result{} bar
16207 @end example
16208
16209 @end defun
16210
16211 @defun atomic-box-compare-and-swap! abox expected desired :optional memory-order
16212 [SRFI-230]
16213 @c MOD srfi.230
16214 Compares the content of atomic box @var{abox} and @var{expected}.
16215 If both are the same (in @code{eq?} sense), sets @var{desired} as the
16216 new value of @var{abox}. Returns the previous content. All operations
16217 are done atomically.
16218
16219 You can know the content is altered if @code{(eq? return-value expected)}
16220 is true.
16221
16222 Gauche uses sequentially consistent order regardless of
16223 the @var{memory-order} argument.
16224 @end defun
16225
16226 @subheading Atomic fxbox
16227
16228 An atomic fxbox is a storage that can hold a fixnum.
16229 It provides atomic fetcy-compute-store opertaions as well.
16230
16231 @defun make-atomic-fxbox fxval
16232 [SRFI-230]
16233 @c MOD srfi.230
16234 Creates a new atomic box whose value is @var{fxval}.
16235 @end defun
16236
16237 @defun atomic-fxbox? obj
16238 [SRFI-230]
16239 @c MOD srfi.230
16240 Returns @code{#t} if @code{obj} is an atomic fxbox,
16241 @code{#f} otherwise.
16242 @end defun
16243
16244 @defun atomic-fxbox-ref fxbox :optional memory-order
16245 [SRFI-230]
16246 @c MOD srfi.230
16247 Returns the content of atomic fxbox @var{fxbox}.
16248
16249 Gauche uses sequentially consistent order regardless of
16250 the @var{memory-order} argument.
16251 @end defun
16252
16253 @defun atomic-fxbox-set! fxbox fxval :optional memory-order
16254 [SRFI-230]
16255 @c MOD srfi.230
16256 Sets @var{fxval} as the content of atomic fxbox @var{fxbox},
16257 and returns an undefined value.
16258
16259 Gauche uses sequentially consistent order regardless of
16260 the @var{memory-order} argument.
16261 @end defun
16262
16263 @defun atomic-fxbox-swap! fxbox fxval :optional memory-order
16264 [SRFI-230]
16265 @c MOD srfi.230
16266 Sets @var{fxval} as the content of atomic fxbox @var{fxbox},
16267 and returns the previous content, atomically.
16268
16269 Gauche uses sequentially consistent order regardless of
16270 the @var{memory-order} argument.
16271 @end defun
16272
16273 @defun atomic-fxbox-compare-and-swap! fxbox expected desired :optional memory-order
16274 [SRFI-230]
16275 @c MOD srfi.230
16276 Compares the content of atomic fxbox @var{fxbox} and @var{expected}.
16277 If both are the same (in @code{eq?} sense), sets @var{desired} as the
16278 new value of @var{fxbox}. Returns the previous content. All operations
16279 are done atomically.
16280
16281 You can know the content is altered if @code{(eq? return-value expected)}
16282 is true.
16283
16284 Gauche uses sequentially consistent order regardless of
16285 the @var{memory-order} argument.
16286 @end defun
16287
16288 @defun atomic-fxbox+/fetch! fxbox fxval :optional memory-order
16289 @defunx atomic-fxbox-/fetch! fxbox fxval :optional memory-order
16290 @defunx atomic-fxbo-and/fetch! fxbox fxval :optional memory-order
16291 @defunx atomic-fxbo-ior/fetch! fxbox fxval :optional memory-order
16292 @defunx atomic-fxbo-xor/fetch! fxbox fxval :optional memory-order
16293 [SRFI-230]
16294 @c MOD srfi.230
16295 Retrieves the value of atomic fxbox @var{fxbox}, calculates
16296 @code{(+ prev-val fxval)}, @code{(- prev-val fxval)},
16297 @code{(logand prev-val fxval)}, @code{(logior prev-val fxval}),
16298 or @code{(logxor prev-val fxval)}, respectively,
16299 then store the result to @var{fxbox}, and returns the previsou value.
16300 The entire sequence of operations are done atomically.
16301
16302 This does not check the numerical overflow.
16303
16304 Gauche uses sequentially consistent order regardless of
16305 the @var{memory-order} argument.
16306 @end defun
16307
16308 @subheading Atomic pair
16309
16310 An atomic pair is a storage that can hold two Scheme values,
16311 and both can be updated at once atomically.
16312
16313 @defun make-atomic-pair val1 val2
16314 [SRFI-230]
16315 @c MOD srfi.230
16316 Creates a new atomic pair that has two values, @var{val1} and @var{val2}.
16317 @c MOD srfi.230
16318
16319 @end defun
16320
16321 @defun atomic-pair? obj
16322 [SRFI-230]
16323 @c MOD srfi.230
16324 Returns @code{#t} if @code{obj} is an atomic pair,
16325 @code{#f} otherwise.
16326 @end defun
16327
16328 @defun atomic-pair-ref apair :optional memory-order
16329 [SRFI-230]
16330 @c MOD srfi.230
16331 Atomically dereference the two values @var{apair} holds,
16332 and returns them as the two return values.
16333
16334 Gauche uses sequentially consistent order regardless of
16335 the @var{memory-order} argument.
16336 @end defun
16337
16338 @defun atomic-pair-set! apair val1 val2 :optional memory-order
16339 [SRFI-230]
16340 @c MOD srfi.230
16341 Atomically stores @var{val1} and @var{val2} to an atomic pair @var{apair}.
16342 Returns an undefined value.
16343
16344 Gauche uses sequentially consistent order regardless of
16345 the @var{memory-order} argument.
16346 @end defun
16347
16348 @defun atomic-pair-swap! apair val1 val2 :optional memory-order
16349 [SRFI-230]
16350 @c MOD srfi.230
16351 Atomically stores @var{val1} and @var{val2} to an atomic pair @var{apair}
16352 and returns the previous values.
16353
16354 Gauche uses sequentially consistent order regardless of
16355 the @var{memory-order} argument.
16356 @end defun
16357
16358 @defun atomic-pair-compare-and-swap! abox expected1 expected2 desired1 desired2 :optional memory-order
16359 [SRFI-230]
16360 @c MOD srfi.230
16361 Compare two values in atomic box @var{abox} with @var{expected1} and
16362 @var{expected2}, respectively. If each corresponding values are
16363 the same (in @code{eq?} sense), store @var{desired1} and @code{desired2}
16364 to @var{abox}. Always returns teh original values.
16365 The whole operations are done atomically.
16366
16367 You can know the values are altered by comparing returned values
16368 and expected values.
16369
16370 Gauche uses sequentially consistent order regardless of
16371 the @var{memory-order} argument.
16372 @end defun
16373
16374 @subheading Memory synchronization
16375
16376 @defun atomic-fence memory-order
16377 [SRFI-230]
16378 @c MOD srfi.230
16379 Synchronize memory according to at least @var{memory-order}
16380 constraints. In the current version of Gauche,
16381 regardless of @var{memory-order},
16382 the memory is synchronized with sequentially consistent manner.
16383 @end defun
16384
16385 @c ----------------------------------------------------------------------
16386 @node Flexible curried procedures, Topological sorting, Atomic operations, Library modules - SRFIs
16387 @section @code{srfi.232} - Flexible curried procedures
16388 @c NODE 柔軟なカリー化された手続き, @code{srfi.232} - 柔軟なカリー化された手続き
16389
16390 @deftp {Module} srfi.232
16391 @mdindex srfi.232
16392 @c EN
16393 This srfi provides macros to define a procedure that can accept
16394 less than or more than the given formal parameters. If the number of given
16395 parameters is less than the required parameters, it becomes partial
16396 application; a procedure that will take the remaining parameters is returned.
16397 If the number of given parameters is more than the maximum number of
16398 parameters, then the excessive parameters are passed to the result
16399 of the original procedure, assuming the original procedure returns
16400 a procedure.
16401 @c JP
16402 このモジュールは、定義時に指定された仮引数よりも少なかったり多かったりする実引数を取れる
16403 手続きを定義するマクロを提供します。
16404 このマクロで定義された手続きが、仮引数よりも少ない実引数を渡された場合は、
16405 部分適用となり、残りの引数を受け取る手続きが返されます。
16406 もし仮引数よりも多い実引数が渡された場合、仮引数分の実引数が手続きにまず渡され、
16407 その戻り値(手続きであることが期待されます)に残りの実引数が渡されます。
16408 @c COMMON
16409
16410 @c EN
16411 Currying in the strict sense converts n-ary procedures to nested 1-ary
16412 procedures:
16413 @c JP
16414 厳密な意味でのカリー化は、n引数の手続きをネストした1引数の手続きに変換することです。
16415 @c COMMON
16416
16417 @example
16418 (lambda (a b c) body)
16419 @result{} (lambda (a) (lambda (b) (lambda (c) body)))
16420 @end example
16421
16422 @c EN
16423 However, with Scheme, you need nested parentheses to give all
16424 the parameters to it:
16425 @c JP
16426 Schemeでは、この方法でカリー化された手続きにすべての引数を渡そうとすると、
16427 括弧をネストしなければなりません。
16428 @c COMMON
16429
16430 @example
16431 (((f 1) 2) 3)
16432 @end example
16433
16434 @c EN
16435 The procedure created with this srfi allows more than one parameters
16436 to be passed at once. The following calls to @code{f} all yield the
16437 same result:
16438 @c JP
16439 これに対し、このsrfiで作られる手続きには、複数の引数をまとめて渡すことができます。
16440 以下の例で、@code{f}の呼び出しはすべて同じ動作となります。
16441 @c COMMON
16442
16443 @example
16444 (define-curried (f a b c) body)
16445
16446 (f 1 2 3)
16447 (((f 1) 2) 3)
16448 ((f 1 2) 3)
16449 ((f 1) 2 3)
16450 @end example
16451
16452 @c EN
16453 Moreover, the procedure can take more parameters than the formals,
16454 assuming that the procedure with full parameters return a procedure
16455 that takes extra parameters. In other words, the following
16456 equivalance holds:
16457 @c JP
16458 さらに、仮引数よりも多くの実引数を@code{f}に渡すことができます。ここで、
16459 @code{f}は(追加の引数を取る)手続きを返すことが期待されています。
16460 つまり、次のような等価性が成り立ちます。
16461 @c COMMON
16462
16463 @example
16464 (f 1 2 3 4 5 6) @equiv{} ((f 1 2 3) 4 5 6)
16465 @end example
16466 @end deftp
16467
16468 @defmac curried formals body @dots{}
16469 [SRFI-232]
16470 @c MOD srfi.232
16471 @c EN
16472 Returns a procedure just like @var{(lambda formals body @dots{})},
16473 except that the returned procedure may take less or more parameters
16474 than the specified in @var{formals}.
16475 @c JP
16476 @var{(lambda formals body @dots{})}と同じように手続きを作って返しますが、
16477 作られた手続きは@var{formals}で指定されるより少なかったり多かったりする引数を
16478 取ることができます。
16479 @c COMMON
16480
16481 @c EN
16482 If it is given with less parameters than the required ones, it works
16483 as partial application; the result is a procedure that will accept
16484 the remaining parameters.
16485 @c JP
16486 呼び出し時に渡される引数が過少な場合は、部分適用として動作し、
16487 残りの引数を受け取る手続きが返されます。
16488 @c COMMON
16489
16490 @example
16491 (define f (curried (a b c d) (+ a b c d)))
16492
16493 @c EN
16494 (f 1 2 3 4) @result{} 10 ; ordinary application
16495 (f 1 2) @result{} #<procedure> ; partial application, like (pa$ f 1 2)
16496 ((f 1 2) 3 4) @result{} 10 ; fulfilling the remaining argument
16497 (((f 1 2) 3) 4) @result{} 10 ; partial application can be nested
16498 (((f 1) 2 3) 4) @result{} 10 ; ... and can be grouped in any way
16499 @c JP
16500 (f 1 2 3 4) @result{} 10 ; 通常の呼び出し
16501 (f 1 2) @result{} #<procedure> ; 部分適用。(pa$ f 1 2)と同じ
16502 ((f 1 2) 3 4) @result{} 10 ; 残りの引数を提供
16503 (((f 1 2) 3) 4) @result{} 10 ; 部分適用はネストでき、
16504 (((f 1) 2 3) 4) @result{} 10 ; ... また一回の呼び出しでいくつも引数を渡せる
16505 @c COMMON
16506 @end example
16507
16508 @c EN
16509 The procedure can accept more parameters than the ones given to
16510 @var{formals}, even @var{formals} does not specify the ``rest'' parameter.
16511 If @var{formals} takes the rest parameter, the excess arguments are passed
16512 to it. If not, the result of the procedure with required parameters
16513 are applied over the excess arguments.
16514 @c JP
16515 また、@var{formals}が「残余引数」を指定していなくても、返される手続きは@var{formals}より
16516 多くの引数を取ることができます。@var{formals}が残余引数を取る場合は、
16517 余分な実引数は残余引数として渡されます。そうでなければ、必要な引数だけが手続きにまず
16518 渡され、その戻り値がもう一度、残りの引数とともに呼び出されます。
16519 @c COMMON
16520
16521 @example
16522 (define f (curried (a b c) (^[x] (* x (+ a b c)))))
16523
16524 (f 1 2 3 4) @result{} 24 ; @equiv{} ((f 1 2 3) 4)
16525 @end example
16526
16527 @c EN
16528 If no arguments are given to the procedure,
16529 it returls the procedure itself:
16530 @c JP
16531 引数が渡されなかった場合は、手続き自身が返ります。
16532 @c COMMON
16533
16534 @example
16535 (((f)) 1 2 3) @equiv{} (f 1 2 3)
16536 @end example
16537
16538 @c EN
16539 As a special case, @code{(curried () body)} and @code{(curried identifier body)}
16540 are the same as @code{(lambda () body)} and @code{(lambda identifier body)},
16541 respectively.
16542 @c JP
16543 特別な場合として、
16544 @code{(curried () body)}および@code{(curried identifier body)}は、それぞれ
16545 @code{(lambda () body)}および@code{(lambda identifier body)}と同じです。
16546 @c COMMON
16547 @end defmac
16548
16549 @defmac define-curried (name . formals) body @dots{}
16550 [SRFI-232]
16551 @c MOD srfi.232
16552 @c EN
16553 A shorthand of @code{(define name (curried formals body @dots{}))}.
16554 @c JP
16555 @code{(define name (curried formals body @dots{}))}の略記です。
16556 @c COMMON
16557 @end defmac
16558
16559 @c ----------------------------------------------------------------------
16560 @node Topological sorting, Combinators (SRFI), Flexible curried procedures, Library modules - SRFIs
16561 @section @code{srfi.234} - Topological sorting
16562 @c NODE トポロジカルソート, @code{srfi.234} - トポロジカルソート
16563
16564 @deftp {Module} srfi.234
16565 @mdindex srfi.234
16566 This module implements topological sort algorithm.
16567
16568 The SRFI is an enhancement of Gauche's @code{util.toposort} module
16569 (@pxref{Topological sort (legacy)}).
16570 As this SRFI is finalized, we encourage new code to use this for
16571 richer features and portability. Original @code{util.toposort} has
16572 become a thin wrapper of this module.
16573 @end deftp
16574
16575 @defun topological-sort graph :optional eq node-array
16576 [SRFI-234]
16577 @c MOD srfi.234
16578 Returns a list of node, ordered to satisfy the dependency graph
16579 represented by @var{graph}.
16580
16581 @var{Graph} represents a directed acyclic graph (DAG) by a list
16582 of connections, where each connection is the form
16583 @example
16584 (<node> <downstream> <downstream2> ...)
16585 @end example
16586 that means a node @code{<node>} is connected to other nodes
16587 @code{<downstream>} etc. @code{<node>} can be arbitrary
16588 object. Their equality is compared by a procedure @var{eq},
16589 which is @code{equal?} by default.
16590
16591 If the graph contains cycles, @code{#f} is returned.
16592
16593 @example
16594 (topological-sort '((shirt tie belt)
16595 (tie jacket)
16596 (belt jacket)
16597 (watch)
16598 (pants shoes belt)
16599 (undershorts pants shoes)
16600 (socks shoes)))
16601 @result{} (socks undershorts watch shirt tie pants belt jacket shoes)
16602 @end example
16603
16604 If the optional @var{node-array} is given and not @code{#f}, it must
16605 be a vector of nodes, and @var{graph} uses integer indices
16606 of the nodes in place of nodes themselves. The comparison
16607 predicate @var{eq} is applied on the indices. Once the nodes are
16608 sorted, they are looked up from @var{node-array}, and a list of
16609 nodes is returned.
16610 @end defun
16611
16612 @defun topological-sort/details graph :optional eq node-array
16613 [SRFI-234]
16614 @c MOD srfi.234
16615 Like @code{topological-sort}, but returns three values for
16616 further information. The meanings of arguments are the same
16617 as @code{topological-sort}.
16618
16619 If nodes can be topologically sorted, the first return value
16620 is a sorted list of nodes, and the second and the third values are
16621 @code{#f}.
16622
16623 If nodes cannot be topologically sorted, the first return value
16624 is @code{#f}, the second return value is an error message,
16625 and the third value is a list of nodes that provides information
16626 of at least one cycle.
16627 @end defun
16628
16629 @defun edgelist->graph edgelist :optional retriever
16630 [SRFI-234]
16631 @c MOD srfi.234
16632 Converts a list of edges @var{edgelist} to a graph acceptable by
16633 @code{topolocial-sort}. Each edge is a list of two nodes, representing
16634 a directed edge @code{(@var{from-node} @var{to-node})}.
16635 The returned graph is a list of
16636 @code{(@var{from-node} @var{downstream-node} @var{downstream-node2} @dots{})}.
16637
16638 The optional argument @var{retriever} is called
16639 as @code{(@var{retriever} @var{from-node} @var{graph})} to get a
16640 graph entry starting with @var{from-node}. When omitted, @code{assoc}
16641 is used. If you need to compare nodes in a special way different from
16642 @code{equal?}, you can give a customized procedure.
16643
16644 @example
16645 (edgelist->graph '((a b) (a c) (b e) (c b)))
16646 @result{} ((a b c) (b e) (c b))
16647 @end example
16648 @end defun
16649
16650 @defun edgelist/inverted->graph edgelist :optional retriever
16651 [SRFI-234]
16652 @c MOD srfi.234
16653 Like @code{edgelist->graph}, but take each edge entry
16654 as @code{(@var{to-node} @var{from-node})}.
16655
16656 @example
16657 (edgelist/inverted->graph '((a b) (a c) (b e) (a e)))
16658 @result{} ((b a) (c a) (e b a))
16659 @end example
16660 @end defun
16661
16662 @defun graph->edgelist graph
16663 [SRFI-234]
16664 @c MOD srfi.234
16665 Given @var{graph}, which is a list of
16666 @code{(@var{from-node} @var{downstream-node} @var{downstream-node1} @dots{})},
16667 returns a list of edges, each of which being
16668 @code{(@var{from-node} @var{to-node})}.
16669 This is an inverse operation of @code{edgelist->graph}.
16670 @end defun
16671
16672 @defun graph->edgelist/inverted graph
16673 [SRFI-234]
16674 @c MOD srfi.234
16675 Given @var{graph}, which is a list of
16676 @code{(@var{from-node} @var{downstream-node} @var{downstream-node1} @dots{})},
16677 returns a list of edges, each of which being
16678 @code{(@var{to-node} @var{from-node})}.
16679 This is an inverse operation of @code{edgelist/inverted->graph}.
16680 @end defun
16681
16682 @defun connected-components graph
16683 [SRFI-234]
16684 @c MOD srfi.234
16685 Returns a list of node lists, where each list of nodes consists of
16686 a connected component of a directed graph @var{graph}.
16687 The format of @var{graph} argument is the same as @code{topological-sort},
16688 i.e. @code{((node downstream @dots{}) @dots{})}.
16689
16690 A connected component is a group of nodes such that from any node in the group
16691 can reach any other nodes in the same group.
16692
16693 @example
16694 (connected-components '((1 2 3) (2 1) (3 4) (4 3)))
16695 @result{} ((4 3) (1 2))
16696 @end example
16697
16698 Note: The order of result list, and the order of each node group in the
16699 list, don't matter. Mathematically, they should be sets instead of
16700 lists.
16701 @end defun
16702
16703 @c ----------------------------------------------------------------------
16704 @node Combinators (SRFI), Codesets, Topological sorting, Library modules - SRFIs
16705 @section @code{srfi.235} - Combinators (SRFI)
16706 @c NODE コンビネータ (SRFI), @code{srfi.235} - コンビネータ (SRFI)
16707
16708 @deftp {Module} srfi.235
16709 @mdindex srfi.235
16710 @c EN
16711 This srfi provides combinator utilities. Gauche provides some frequently-used
16712 combinators built-in. This module augments it.
16713 @c JP
16714 このSRFIはコンビネータのユーティリティを提供します。
16715 Gaucheは組み込みでよく使われるコンビネータを持っていますが、このSRFIはそれを補強します。
16716 @c COMMON
16717
16718 @c EN
16719 The following procedures are built-in; @pxref{Combinators}, for the details.
16720 @c JP
16721 以下の手続きは組み込みです。詳しくは@ref{Combinators}を参照してください。
16722 @c COMMON
16723
16724 @example
16725 constantly complement flip swap boolean
16726 @end example
16727 @end deftp
16728
16729 @c EN
16730 @subheading Combinator utilities
16731 @c JP
16732 @subheading コンビネータユーティリティ
16733 @c COMMON
16734
16735 @c EN
16736 Procedures that takes procedure(s) and returns a procedure.
16737 @c JP
16738 手続きを取って手続きを返す手続きです。
16739 @c COMMON
16740
16741 @defun on-left proc
16742 [SRFI-235]
16743 @c MOD srfi.235
16744 @c EN
16745 Returns a two argument procedure, which ignores its right argument
16746 and calls @var{proc} with the left argument.
16747 @c JP
16748 2つの引数を取る手続きを返します。その手続きが呼ばれると、右側の引数を無視して
16749 左側の引数を@var{proc}に渡します。
16750 @c COMMON
16751
16752 @example
16753 ((on-left car) '(a b) '(c d)) @result{} a
16754 @end example
16755 @end defun
16756
16757 @defun on-right proc
16758 [SRFI-235]
16759 @c MOD srfi.235
16760 @c EN
16761 Returns a two argument procedure, which ignores its left argument
16762 and calls @var{proc} with the right argument.
16763 @c JP
16764 2つの引数を取る手続きを返します。その手続きが呼ばれると、左側の引数を無視して
16765 右側の引数を@var{proc}に渡します。
16766 @c COMMON
16767
16768 @example
16769 ((on-right car) '(a b) '(c d)) @result{} c
16770 @end example
16771 @end defun
16772
16773 @defun conjoin pred @dots{}
16774 [SRFI-235]
16775 @c MOD srfi.235
16776 @c EN
16777 Returns a procedure taking any number of arguments and that behaves
16778 as follows: For each argument, calls @var{pred} @dots{} left to right;
16779 if any of @var{pred} returns @code{#f}, stop and immediately returns
16780 @code{#f}. If all predicates returns a true value for all arguments,
16781 returns the last result. If no @var{pred}s are given, or no arguments are given,
16782 returns @code{#t}.
16783 @c JP
16784 任意個の引数を取る、次の動作をする関数を返します。
16785 各引数に対し、@var{pred} @dots{}を左から順に適用します。@var{pred}が@code{#f}を
16786 返したらただちに@code{#f}を返します。全ての引数に対し、全ての@var{pred}が真の値を
16787 返したら、最後の評価値を返します。@var{pred}がゼロ個の場合、もしくは返された関数が
16788 引数無しで呼び出された場合は@code{#t}を返します。
16789 @c COMMON
16790
16791 @example
16792 ((conjoin char? digit->integer) #\1 #\2 #\3) @result{} 3
16793 ((conjoin char? digit->integer) #\1 #\a #\3) @result{} #f
16794 @end example
16795
16796 @end defun
16797
16798 @defun disjoin pred @dots{}
16799 [SRFI-235]
16800 @c MOD srfi.235
16801 @c EN
16802 Returns a procedure taking any number of arguments and that behaves
16803 as follows: For each argument, calls @var{pred} @dots{} left to right;
16804 if any of @var{pred} returns a true value, stop and immediately returns
16805 that value. If all predicates returns @code{#f} for all arguments,
16806 returns @code{#f}. If no @var{pred}s are given, or no arguments are given,
16807 returns @code{#f}.
16808 @c JP
16809 任意個の引数を取る、次の動作をする関数を返します。
16810 各引数に対し、@var{pred} @dots{}を左から順に適用します。@var{pred}が真の値を
16811 返したらただちにその値を返します。全ての引数に対し、全ての@var{pred}が@code{#f}を
16812 返したら、@code{#f}を返します。@var{pred}がゼロ個の場合、もしくは返された関数が
16813 引数無しで呼び出された場合は@code{#f}を返します。
16814 @c COMMON
16815
16816 @example
16817 ((disjoin integer? char?) 'a 'b 'c) @result{} #f
16818 ((disjoin integer? char?) #\a 'b 'c) @result{} #t
16819 @end example
16820
16821 @end defun
16822
16823 @defun each-of proc @dots{}
16824 [SRFI-235]
16825 @c MOD srfi.235
16826 @c EN
16827 Returns a procedure that works, when applied to arguments, applies
16828 each @var{proc} on the arguments in turn. The result of
16829 @var{proc}s are discarded.
16830 @c JP
16831 手続きを返します。返された手続きは、適用された際に、
16832 各@var{proc}を順に呼び出します。@var{proc}の結果は捨てられます。
16833 @c COMMON
16834
16835 @example
16836 (define (f x y) (print (+ x y)))
16837 (define (g x y) (print (* x y)))
16838
16839 ((each-of f g) 2 7)
16840 @result{} #<undef>; @r{prints} 9 @r{and} 14
16841 @end example
16842 @end defun
16843
16844 @defun all-of pred
16845 [SRFI-235]
16846 @c MOD srfi.235
16847 @c EN
16848 Returns a procedure that takes one argument, a list.
16849 The returned procedure tries to apply @var{pred} to each element
16850 of @var{list} in turn.
16851 If @var{pred} returns @var{#f}, immediately returns @var{#f}. Otherwise,
16852 returns the last result of @var{pred}. If the returned procedure
16853 is applied to an empty list, @code{#t} is returned.
16854
16855 The following equivalence holds:
16856 @c JP
16857 リストをひとつ取る手続きを返します。
16858 返された手続きは、リストの要素に順に@var{pred}を適用してゆきます。
16859 それが@code{#f}を返したらそこで適用を打ち切り@code{#f}を返します。
16860 そうでなければ最後の@var{pred}の適用結果を返します。
16861 空リストに適用された場合は@code{#t}を返します。
16862
16863 次の等価性が成り立ちます:
16864 @c COMMON
16865 @example
16866 ((all-of pred) list) @equiv{} (every pred list)
16867 @end example
16868 @end defun
16869
16870 @defun any-of pred
16871 [SRFI-235]
16872 @c MOD srfi.235
16873 @c EN
16874 Returns a procedure that takes one argument, a list.
16875 The returned procedure applies @var{pred} to each element
16876 of @var{list} in turn.
16877 If @var{pred} returns a true value, immediately returns it. Otherwise,
16878 returns @code{#f}. If the returned procedure
16879 is applied to an empty list, @code{#f} is returned.
16880
16881 The following equivalence holds:
16882 @c JP
16883 リストをひとつ取る手続きを返します。
16884 返された手続きは、リストの要素に順に@var{pred}を適用してゆきます。
16885 それが真の値を返したらそこで適用を打ち切りその値を返します。
16886 そうでなければ@code{#f}を返します
16887 空リストに適用された場合は@code{#f}を返します。
16888
16889 次の等価性が成り立ちます:
16890 @c COMMON
16891 @example
16892 ((any-of pred) list) @equiv{} (any pred list)
16893 @end example
16894 @end defun
16895
16896 @defun on reducer mapper
16897 [SRFI-235]
16898 @c MOD srfi.235
16899 @c EN
16900 Returns a procedure such that @code{(apply (on reducer mapper) args)}
16901 works as if @code{(apply reducer (map mapper args))}.
16902 @c JP
16903 @code{(apply (on reducer mapper) args)}が
16904 @code{(apply reducer (map mapper args))}と同じ動作になるような手続きを返します。
16905 @c COMMON
16906
16907 @example
16908 (define square-sum (on + square))
16909
16910 (square-sum 1 2 3 4 5) @result{} 55
16911 @end example
16912 @end defun
16913
16914 @defun left-section proc arg @dots{}
16915 [SRFI-235]
16916 @c MOD srfi.235
16917 Returns a procedure such that, when applied to more args, calls @var{proc}
16918 with @var{arg} @dots{} and the given args. In other words,
16919 returns a specialized procedure with the left argumen(s) are given
16920 as @var{arg} @dots{}.
16921
16922 In Gauche, this is the same as @code{(pa$ arg @dots{})} (@pxref{Combinators}).
16923
16924 @example
16925 ((left-section list 'a 'b 'c) 'd 'e 'f)
16926 @result{} (a b c d e f)
16927 @end example
16928 @end defun
16929
16930 @defun right-section proc arg @dots{}
16931 [SRFI-235]
16932 @c MOD srfi.235
16933 Returns a procedure such that, when applied to more args, calls @var{proc}
16934 with the newly given args concatenated with @code{(reverse @var{arg} @dots{})}.
16935
16936 @example
16937 ((right-section list 'a 'b 'c) 'd 'e 'f)
16938 @result{} (d e f c b a)
16939 @end example
16940
16941 The reason that @var{arg} @dots{} is reversed is because of
16942 this invariance:
16943
16944 @example
16945 (right-section proc arg arg1 @dots{})
16946 @equiv{} (right-section (right-section proc arg) arg1 @dots{})
16947 @end example
16948 @end defun
16949
16950 @defun apply-chain proc proc2 @dots{}
16951 [SRFI-235]
16952 @c MOD srfi.235
16953 Returns a procedure such that it applies the last procedure to the
16954 given arguments, then applies the previous procedure on the
16955 returned value(s), and so on. Returns the result(s) of @var{proc}.
16956
16957 @example
16958 ((apply-chain car cdr) '(a b c d)) @result{} b
16959 ((apply-chain list div-and-mod) 10 3) @result{} (3 1)
16960 @end example
16961 @end defun
16962
16963 @defun arguments-drop proc n
16964 @defunx arguments-drop-right proc n
16965 @defunx arguments-take proc n
16966 @defunx arguments-take-right proc n
16967 [SRFI-235]
16968 @c MOD srfi.235
16969 Returns a procedure such that @var{proc} is applied on the argument
16970 list after taking/dropping @var{n} arguments. That is,
16971 @code{(arguments-drop proc n)} is
16972 @code{(^ args (apply proc (drop args n)))}, and so on.
16973
16974 @example
16975 ((arguments-drop list 2) 'a 'b 'c 'd 'e) @result{} (c d e)
16976 ((arguments-drop-right list 2) 'a 'b 'c 'd 'e) @result{} (a b c)
16977 ((arguments-take list 2) 'a 'b 'c 'd 'e) @result{} (a b)
16978 ((arguments-take-right list 2) 'a 'b 'c 'd 'e) @result{} (d e)
16979 @end example
16980 @end defun
16981
16982 @defun group-by key-proc :optional equal
16983 [SRFI-235]
16984 @c MOD srfi.235
16985 Returns a procedure that takes one list argument. It applies
16986 @var{key-proc} to each element of the list to get keys, and then
16987 elements with the same key are grouped into a fresh list, and
16988 returns list of such groups.
16989 The keys are compared with @var{equal}, which defaults to @code{equal?}.
16990 Within each group, elements that appears left in the original list
16991 also appears on the left.
16992
16993 @code{((group-by key-proc eq-proc) lis)} works like
16994 @code{(group-collection lis :key key-proc :test eq-proc)}, except
16995 that @code{group-collection} can take any collection
16996 (@pxref{Selection and searching in collection}).
16997
16998 @example
16999 ((group-by (cut string-ref <> 0) char-ci=?)
17000 '("apricot" "Banana" "Apple" "blueberry"))
17001 @result{} (("apricot" "Apple") ("Banana" "blueberry"))
17002 @end example
17003 @end defun
17004
17005 @c EN
17006 @subheading Syntax-like procedures
17007 @c JP
17008 @subheading 構文に対応する手続き
17009 @c COMMON
17010
17011 @defun begin-procedure thunk @dots{}
17012 [SRFI-235]
17013 @c MOD srfi.235
17014 @c EN
17015 Calls @var{thunk} @dots{} from left to right. Discats their results
17016 except the last one(s), which will be the result(s) of this procedure.
17017 @c JP
17018 @var{thunk} @dots{}を左から順に呼び出します。最後の@var{thunk}の呼び出し
17019 以外の結果は捨てられます。最後の@var{thunk}の呼び出し結果が返されます。
17020 @c COMMON
17021
17022 @c EN
17023 If no @var{thunk}s are given, returns @code{#<undef>}.
17024 @c JP
17025 @var{thunk}がひとつも与えられなかった場合は@code{#<undef>}が返されます。
17026 @c COMMON
17027 @end defun
17028
17029 @defun if-procedure value then-thunk else-thunk
17030 [SRFI-235]
17031 @c MOD srfi.235
17032 @c EN
17033 If @var{value} is true, calls @var{then-thunk} and returns its
17034 result(s). Otherwise, calls @var{else-thunk} and returns its result(s).
17035 @c JP
17036 @var{value}が真なら@var{then-thunk}を呼び、その結果を返します。
17037 そうでなければ@var{else-thunk}を呼び、その結果を返します。
17038 @c COMMON
17039 @end defun
17040
17041 @defun when-procedure value thunk @dots{}
17042 @defunx unless-procedure value thunk @dots{}
17043 [SRFI-235]
17044 @c MOD srfi.235
17045 @c EN
17046 If @var{value} evaluates to true/false, calls each @var{thunk} in turn
17047 and returns an undefined value, respectively.
17048 Otherwise, returns imediately.
17049 @c JP
17050 @var{value}が真または偽の値に評価されたら、
17051 各@var{thunk}を順に呼び出して、未定義値を返します。
17052 そうでなければ直ちに返ります。
17053 @c COMMON
17054 @end defun
17055
17056 @defun value-procedure value then-proc else-thunk
17057 [SRFI-235]
17058 @c MOD srfi.235
17059 @c EN
17060 If @var{value} evaluates to true, apply @var{then-proc} on it and returns
17061 its result(s). Otherwise, call @var{else-thunk} and returns
17062 its result(s).
17063 @c JP
17064 @var{value}が真の値に評価されたら、
17065 その値を引数に@var{then-proc}を呼び出しその戻り値を返します。
17066 そうでなければ、@var{else-thunk}を引数なしで呼び出しその戻り値を返します。
17067 @c COMMON
17068 @end defun
17069
17070 @defun case-procedure value thunk-alist :optional else-thunk
17071 [SRFI-235]
17072 @c MOD srfi.235
17073 @c EN
17074 The @var{thunk-alist} argument is a list of pairs of a value and
17075 a thunk. First, @var{value} is evaluated, then the result
17076 is searched from the cars of @var{thunk-alist}, using @code{eqv?}.
17077 If there's a matching entry, its thunk is called and its result(s) is/are
17078 returned. If there's no matching entry, @var{else-thunk} is invoked
17079 if present and its result(s) is/are returned.
17080 If there's neither @var{else-thunk}, an undefined value is returned.
17081 @c @JP
17082 @var{thunk-alist}引数は、値とサンクのペアのリストです。
17083 まず@var{value}が評価され、その値が@var{thunk-alist}中のペアのcarの値と順に@var{eqv?}
17084 で比較されます。一致するエントリが見つかったら、そのペアのcdrにあるサンクが呼ばれ、
17085 その結果が戻り値となります。一致するエントリが無い場合、
17086 @var{else-thunk}が与えられていればそれが呼ばれてその結果が戻り値となり、
17087 与えられていなければ未定義値が返されます。
17088 @c COMMON
17089 @end defun
17090
17091 @defun and-procedure thunk @dots{}
17092 [SRFI-235]
17093 @c MOD srfi.235
17094 @c EN
17095 Calls @var{thunk} @dots{} left to right, until it yields
17096 @code{#f}, and returns @code{#f}. If all @var{thunk}s yields
17097 true value, returns the result of the last @code{thunk}.
17098 If no @var{thunk}s are given, returns @code{#t}.
17099 @c JP
17100 @var{thunk} @dots{}を左から順に呼んでいきます。@code{#f}を返すサンクがあれば
17101 そこで評価を打ち切り@code{#f}を返します。最後のサンクまでどれも@code{#f}を返さなければ、
17102 最後のサンクの結果を戻り値とします。@var{thunk}がひとつも与えられなかった場合は
17103 @code{#t}を返します。
17104 @c COMMON
17105 @end defun
17106
17107 @defun eager-and-procedure thunk @dots{}
17108 [SRFI-235]
17109 @c MOD srfi.235
17110 @c EN
17111 Calls all @var{thunk}s, then checks their results. If any
17112 of the result is @code{#f}, returns @code{#f}.
17113 Otherwise, returns the last result of @var{thunk}.
17114 If no @var{thunk}s are given, returns @code{#t}.
17115 @c JP
17116 @var{thunk} @dots{}をまず全て呼び出し、それから結果を調べます。
17117 どれかひとつでも@code{#f}があったら@code{#f}を返します。
17118 そうでなければ、最後の@var{thunk}の結果を返します。
17119 @var{thunk}がひとつも与えられなかった場合は@code{#t}を返します。
17120 @c COMMON
17121 @end defun
17122
17123 @defun or-procedure thunk @dots{}
17124 [SRFI-235]
17125 @c MOD srfi.235
17126 @c EN
17127 Calls @var{thunk} @dots{} left to right, until it yields
17128 a true value, and returns that value. If all @var{thunk}s yields
17129 @code{#f}, returns @code{#f}. If no @var{thunk}s are given,
17130 returns @code{#t}.
17131 @c JP
17132 @var{thunk} @dots{}を左から順に呼んでいきます。真の値を返すサンクがあれば
17133 そこで評価を打ち切りその値を返します。最後のサンクまでどれも真の値を返さなければ
17134 @code{#f}を返します。@var{thunk}がひとつも与えられなかった場合は
17135 @code{#t}を返します。
17136 @c COMMON
17137 @end defun
17138
17139 @defun eager-or-procedure thunk @dots{}
17140 [SRFI-235]
17141 @c MOD srfi.235
17142 @c EN
17143 Calls all @var{thunk}s, then checks their results from left to right,
17144 and returns the first true value. If all the results are @code{#f},
17145 or no @var{thunk}s are given, returns @code{#f}.
17146 @c JP
17147 @var{thunk} @dots{}をまず全て呼び出し、それから結果を左から右へ調べ、
17148 最初に出会った真の値を返します。全てが@code{#f}であったり、
17149 @var{thunk}がひとつも与えられなかった場合は@code{#f}を返します。
17150 @c COMMON
17151 @end defun
17152
17153 @defun funcall-procedure thunk
17154 [SRFI-235]
17155 @c MOD srfi.235
17156 @c EN
17157 Just call @var{thunk} and returns its result(s).
17158 This is useful to pass to other procedures, e.g.
17159 @code{(map funcall-procedure list-of-procedures)}.
17160 @c JP
17161 @var{thunk}を呼び出しその結果を返します。
17162 これは他の手続きに渡すのに便利です。例えば:
17163 @code{(map funcall-procedure list-of-procedures)}。
17164 @c COMMON
17165 @end defun
17166
17167 @defun loop-procedure thunk
17168 [SRFI-235]
17169 @c MOD srfi.235
17170 @c EN
17171 Calls @var{thunk} repeatedly forever. Nonlocal escape is the only
17172 way to break out.
17173 @c JP
17174 繰り返し@var{thunk}を呼びます。@var{thunk}からの大域脱出のみが
17175 ループを抜ける方法です。
17176 @c COMMON
17177 @end defun
17178
17179 @defun while-procedure thunk
17180 @defunx until-procedure thunk
17181 [SRFI-235]
17182 @c MOD srfi.235
17183 @c EN
17184 Calls @var{thunk} repeatedly while/until it returns a true value,
17185 respectively.
17186 @c JP
17187 それぞれ、@var{thunk}が真の値を返す限り(while)、あるいは真の値を返すまで(until)、
17188 繰り返し@var{thunk}を呼びつづけます。
17189 @c COMMON
17190 @end defun
17191
17192 @c EN
17193 @subheading Auxiliary utilities
17194 @c JP
17195 @subheading 補助ユーティリティ
17196 @c COMMON
17197
17198 @defun always obj @dots{}
17199 [SRFI-235]
17200 @c MOD srfi.235
17201 @c EN
17202 Ignores arguments and always returns @code{#t}.
17203 Same as @code{(constantly #t)}.
17204 @c JP
17205 引数を無視して常に@code{#t}を返す手続きです。
17206 @code{(constantly #t)}と同じです。
17207 @c COMMON
17208 @end defun
17209
17210 @defun never obj @dots{}
17211 [SRFI-235]
17212 @c MOD srfi.235
17213 @c EN
17214 Ignores arguments and always returns @code{#f}.
17215 Same as @code{(constantly #f)}.
17216 @c JP
17217 引数を無視して常に@code{#f}を返す手続きです。
17218 @code{(constantly #f)}と同じです。
17219 @c COMMON
17220 @end defun
17221
17222 @c EN
17223 Note: @code{boolean} is provided in the core (@pxref{Booleans}).
17224 @c JP
17225 註: @code{boolean}は組み込みです (@ref{Booleans}参照)。
17226 @c COMMON
17227
17228 @c ----------------------------------------------------------------------
17229 @node Codesets, Destructuring lists, Combinators (SRFI), Library modules - SRFIs
17230 @section @code{srfi.238} - Codesets
17231 @c NODE コードセット, @code{srfi.238} - コードセット
17232
17233 @deftp {Module} srfi.238
17234 @mdindex srfi.238
17235 @c EN
17236 This module provides a unified interface for system-defined set of
17237 code values, such as errno or signal numbers.
17238 @c JP
17239 このモジュールは、エラー番号やシグナル番号のような、システムが提供するコード値の集合を
17240 扱うための統一的なインタフェースを提供します。
17241 @c COMMON
17242
17243 @c EN
17244 In Gauche, we have predefined integer constants for errnos (e.g. @code{EINTR})
17245 and signals (e.g. @code{SIGINT}) in @code{gauche} module, and
17246 we have built-in procedures to convert integer code to
17247 symbols (@code{sys-errno->symbol}, @code{sys-signal-name})
17248 and to string messages (@code{sys-strerror}, @code{sys-strsignal}).
17249 You may want to use this srfi for portable code, though.
17250 @c JP
17251 Gaucheはエラー番号(errno)を表す整数定数(例:@code{EINTR})とシグナル番号を
17252 表す整数定数(例@code{SIGINT})を@code{gauche}モジュールで提供していて、
17253 また整数を対応するシンボルに変換する手続き
17254 (@code{sys-errno->symbol}, @code{sys-signal-name})
17255 および整数から記述的なメッセージを得る手続き
17256 (@code{sys-strerror}, @code{sys-strsignal})
17257 を組み込みにしてます。
17258 ただ、ポータブルなコードを書きたい場合はこのSRFIは有用でしょう。
17259 @c COMMON
17260 @end deftp
17261
17262 @defun codeset? obj
17263 [SRFI-238]
17264 @c MOD srfi.238
17265 @c EN
17266 Returns @code{#t} if @var{obj} is an object that can be used as a @var{codeset}
17267 argument for this srfi's API, @code{#f} otherwise.
17268 In Gauche, @var{obj} must be either a symbol @code{errno} or @code{signal}.
17269 @c JP
17270 @var{obj}がこのsrfiのAPIの@var{codeset}引数に渡せるものなら@code{#t}を、
17271 そうでなければ@code{#f}を返します。
17272 Gaucheでは@var{obj}はシンボル@code{errno}か@code{signal}でなければなりません。
17273 @c COMMON
17274 @end defun
17275
17276 @defun codeset-symbols codeset
17277 [SRFI-238]
17278 @c MOD srfi.238
17279 @c EN
17280 Returns a list of symbols defined in a codeset designated by @var{codeset}.
17281 In Gauche, @var{codeset} must be a symbol. If it does not name a supported
17282 codeset, an empty list is returned.
17283 @c JP
17284 @var{codeset}引数で表されるコードセットが定義しているシンボルのリストを返します。
17285 Gaucheでは@var{codeset}はシンボルでなければなりません。
17286 それが定義済みコードセットに対応しないシンボルだった場合は空リストが返されます。
17287 @c COMMON
17288
17289 @example
17290 (codeset-symbols 'errno)
17291 @result{} (EPERM ENOENT ESRCH EINTR EIO ...)
17292 @end example
17293 @end defun
17294
17295 @defun codeset-symbol codeset code
17296 @defunx codeset-number codeset code
17297 @defunx codeset-message codeset code
17298 [SRFI-238]
17299 @c MOD srfi.238
17300 @c EN
17301 Returns a symbol, an exact integer, or a message string associated to
17302 the @var{code} in the codeset designated by @var{codeset}, respectively
17303 @c JP
17304 それぞれ、@var{codeset}で指定されるコードセット中の@var{code}に対応する
17305 シンボル、正確な整数、あるいはメッセージ文字列を返します。
17306 @c COMMON
17307
17308 @c EN
17309 The @var{code} argument can be either a symbol or an exact integer.
17310 The @var{codeset} argument must be a symbol.
17311 @c JP
17312 @var{code}引数はシンボルまたは正確な整数です。
17313 @var{codeset}引数はシンボルでなければなりません。
17314 @c COMMON
17315
17316 @c EN
17317 If @var{codeset} is not a name of supported codesets (in Gauche,
17318 we have @code{errno} and @code{signale}), or @var{code} is not in
17319 the specified codeset, @code{#f} is returned.
17320 @c JP
17321 @var{codeset}がGaucheでサポートするコードセットを指定しないシンボルだったり、
17322 @var{code}が指定されたコードセット中のコードを指定しない場合は@code{#f}が返ります。
17323 @c COMMON
17324
17325 @example
17326 (codeset-symbol 'errno 'EINTR) @result{} EINTR
17327 (codeset-symbol 'errno EINTR) @result{} EINTR ; Gauche has predefined constant
17328
17329 (codeset-number 'errno 'EINTR) @result{} 4 ; Actual number is platform dependent
17330 (codeset-number 'errno 4) @result{} 4
17331
17332 (codeset-message 'errno EINTR) @result{} "Interrupted system call"
17333
17334 (codeset-message 'errno 'NoSuchErrno) @result{} #f
17335 @end example
17336 @end defun
17337
17338 @c ----------------------------------------------------------------------
17339 @node Destructuring lists, Syntactic monads, Codesets, Library modules - SRFIs
17340 @section @code{srfi.239} - Destructuring lists
17341 @c NODE リストの分解, @code{srfi.239} - リストの分解
17342
17343 @deftp {Module} srfi.239
17344 @mdindex srfi.239
17345 @c EN
17346 This module provides a pattarn-matching macro specialized for
17347 the common pattern appearing frequently in list processing code.
17348 It can be seen as a subset of @code{match} (@pxref{Pattern matching});
17349 if you're writing Gauche-specific code, you don't need this module.
17350 However, this is useful for portable code.
17351 @c JP
17352 このモジュールは、リスト処理のコードで頻繁に現れるパターンに特化した
17353 パターンマッチングの機能を提供します。
17354 Gauche用のコードを書いているなら、機能としてはGaucheの@code{match}のサブセットになるので
17355 このモジュールを使う必要はありません(@ref{Pattern matching}参照)が、
17356 ポータブルなコードを書いている時は有用でしょう。
17357 @c COMMON
17358 @end deftp
17359
17360 @defmac list-case expr clause @dots{}
17361 [SRFI-239]
17362 @c MOD srfi.239
17363 @c EN
17364 Each @var{clause} must be one of the following forms:
17365 @c JP
17366 各@var{clause}は以下のいずれかの形をとります。
17367 @c COMMON
17368
17369 @itemize @bullet
17370 @item
17371 @code{((@var{var1} . @var{var2}) @var{body} @dots{})}
17372 @item
17373 @code{(() @var{body} @dots{})}
17374 @item
17375 @code{(@var{var} @var{body} @dots{})}
17376 @end itemize
17377
17378 @c EN
17379 Here, @var{var}, @var{var1}, @var{var2} are identifiers.
17380 The order of clauses does not matter, and not all three forms need
17381 to be present.
17382 @c JP
17383 ここで、@var{var}、@var{var1}、@var{var2}は識別子です。
17384 @var{clause}は順不同で、3つ全てが揃っていなくても構いません。
17385 @c COMMON
17386
17387 @c EN
17388 First @var{expr} is evaluated. If it is a pair, the first type of
17389 clause is selected, and @var{body} @dots{} are evaluated with
17390 the environment where the pair's car is bound to @var{var1} and the pair's
17391 cdr is bound to @var{var2}.
17392 If it is an empty list, the second type of clause is selected,
17393 and its @var{body} @dots{} are evaluated.
17394 Otherwise, the third type of clause is selected,
17395 its @var{body} @dots{} are evaluated where
17396 the value of @var{expr} is bound to @var{var}.
17397 @c JP
17398 まず@var{expr}が評価されます。それがペアなら、最初の形式の節が選択され、
17399 @var{var1}がペアのcarに、@var{var2}がcdrに束縛された環境で@var{body} @dots{}が
17400 評価されます。
17401 @var{expr}の値が空リストなら2番めの形式の節が選択され、
17402 @var{body} @dots{}が評価されます。
17403 それ以外の場合は3番めの形式の節が選択され、
17404 @var{expr}の値が@var{var}に束縛された環境で
17405 @var{body} @dots{}が評価されます。
17406 @c COMMON
17407
17408 @c EN
17409 The identifier @code{_} has special meaning in @var{var}, @var{var1},
17410 and @var{var2}; it is not bound and the corresponding value is simply discarded.
17411 @c JP
17412 @var{var}、@var{var1}、@var{var2}に@code{_}が使われた場合、
17413 該当する値は束縛されず捨てられます。
17414 @c COMMON
17415
17416 @c EN
17417 If not all three forms are present and the result of @var{expr} does not
17418 match the provided clauses, an error is thrown.
17419 Note that, unlike @code{match},
17420 if the first type of clause isn't provided, a pair does not
17421 match the third type of clause
17422 @c JP
17423 3つ全ての節が揃っていなくて、@var{expr}の結果にマッチする節がなければ、
17424 エラーが報告されます。
17425 @code{match}と違い、最初の形式の節が指定されていない場合に、
17426 ペアは3番めの形式の節とはマッチしません。
17427 @c COMMON
17428 @end defmac
17429
17430 @c ----------------------------------------------------------------------
17431 @node Syntactic monads, Property testing, Destructuring lists, Library modules - SRFIs
17432 @section @code{srfi.247} - Syntactic monads
17433 @c NODE 構文的モナド, @code{srfi.247} - 構文的モナド
17434
17435 @deftp {Module} srfi.247
17436 @mdindex srfi.247
17437 This module provide a macro-defining macro, @code{define-syntactic-monad},
17438 that captures a typical pattern of adding implicit or hidden
17439 arguments.
17440 @end deftp
17441
17442 @defmac define-syntactic-monad name formal @dots{}
17443 [SRFI-247]
17444 @c MOD srfi.247
17445 @end defmac
17446
17447
17448 @c ----------------------------------------------------------------------
17449 @node Property testing, , Syntactic monads, Library modules - SRFIs
17450 @section @code{srfi.252} - Property testing
17451 @c NODE プロパティテスト, @code{srfi.252} - プロパティテスト
17452
17453 @deftp {Module} srfi.252
17454 @mdindex srfi.252
17455 @c EN
17456 Property testing is to feed random input to a component to be tested
17457 and see if it satisfies certain properties hold. The method was made
17458 popular with Haskell's QuickCheck.
17459 @c JP
17460 プロパティテストは、テストしたいコンポーネントにランダムな入力を供給して
17461 満たすべき属性(プロパティ)が満たされるかをテストする方法です。
17462 HaskellのQuickCheckによってポピュラーになりました。
17463 @c COMMON
17464
17465 @c EN
17466 This module provides two groups of APIs; one for running property tests,
17467 and another for generating random input.
17468 @c JP
17469 このモジュールでは、プロパティテストを実行するためのAPI群と、
17470 ランダムな入力を生成するためのAPI群のふたつを提供します。
17471 @c COMMON
17472
17473 @c EN
17474 The test procedures are integrated with @code{gauche.test}
17475 (@pxref{Unit testing}). The SRFI is designed to be used with
17476 SRFI-64 (@pxref{A Scheme API for test suites}); in Gauche, you can
17477 run them with either of modules.
17478 @c JP
17479 テスト手続きは@code{gauche.test}と統合されています
17480 (@ref{Unit testing}参照)。また、このSRFIはSRFI-64と併せて使えるように
17481 設計されており、GaucheでもSRFI-64と併用することができます
17482 (@ref{A Scheme API for test suites}参照)。
17483 @c COMMON
17484
17485 @c EN
17486 The random input generators are built on top of @code{data.random}
17487 (@pxref{Random data generators}). They are provided for
17488 the convenience; you can use any generator to create input feed.
17489 @c JP
17490 ランダムな入力を生成するジェネレータは@code{data.random}の上に
17491 構築されています (@ref{Random data generators}参照)。
17492 これは簡便のために提供されています。必要なら、独自にジェネレータを作っても構いません。
17493 @c COMMON
17494 @end deftp
17495
17496 @c EN
17497 @subheading Testing forms
17498 @c JP
17499 @subheading テストフォーム
17500 @c COMMON
17501
17502 @defmac test-property property-check generator-list :optional runs
17503 @defmacx test-property-expect-fail property-check generator-list :optional runs
17504 @defmacx test-property-skip property-check generator-list :optional runs
17505 @defmacx test-property-error property-check generator-list :optional runs
17506 @defmacx test-property-error-type error-type property-check generator-list :optional runs
17507 [SRFI-252]
17508 @c MOD srfi.252
17509 @c EN
17510 Calls @var{property-check} over the arguments generated by
17511 the generators in @var{generator-list} as many times as @var{runs}.
17512 @c JP
17513 @var{generator-list}にあるジェネレータが生成した値を引数として、
17514 @var{property-check}を呼びます。それを@var{runs}回繰り返します。
17515 @c COMMON
17516
17517 @c EN
17518 @var{property-check} is an expression that evaluates to
17519 a procedure accepts input, and returns
17520 @code{#t} if the property is satisfied, @code{#f} if not.
17521 The input is fed from generators listed in @var{generator-list};
17522 it must have as many generators as the number of arguments
17523 @var{property-check} accepts.
17524 @c JP
17525 @var{property-check}は手続きに評価される式で、プロパティが満たされたら@code{#t}を、
17526 そうでなければ@code{#f}を返します。
17527 引数は@var{generator-list}にリストされた各ジェネレータが生成します。
17528 @var{generator-list}は@var{property-check}が受け取る引数と
17529 同数のジェネレータから構成されていなければなりません。
17530 @c COMMON
17531
17532 @c EN
17533 The optional argument @var{runs} must be a nonnegative exact integer
17534 to specify how many times @var{property-check} should be run.
17535 If omitted, the system default is used, which is 30 in Gauche.
17536 The default runs may be changed in future.
17537 @c JP
17538 省略可能な@var{runs}引数は非負の整数で、@var{property-check}を何回呼び出すかを
17539 指定します。省略された場合はシステムのデフォルトが使われます
17540 (Gaucheでは今のところ30。但し将来変わる可能性はあります)。
17541 @c COMMON
17542
17543 @c EN
17544 @code{Test-property} is the basic one; the test passes when every
17545 @var{property-check} invocation returns true.
17546 @code{Test-property-expect-fail}, on the other hand, passes
17547 when every @var{property-check} returns false (thus, expected failure).
17548 @code{Test-property-skip} does not run @var{property-check}, just
17549 counts @var{runs} attempts as skipped tests.
17550 @code{Test-property-error} expects all invocations of @var{property-check}
17551 raises an error.
17552 Finally, @code{test-property-error} and
17553 @code{test-property-error-type} expect all @var{property-check} invocations
17554 raise an error. Additionally, @code{test-property-error-type}
17555 expects the raised error is of type @var{error-type},
17556 which should be a condition type.
17557 @c JP
17558 @code{test-property}が最も基本的なもので、全ての@var{property-check}の呼び出しが
17559 成功であれば成功します。
17560 @code{test-property-expect-fail}は逆に、全ての@var{properyt-check}
17561 の呼び出しが失敗した場合に成功します (つまり、失敗することを期待したチェックです)。
17562 @code{test-property-skip}は@var{property-check}は呼び出さず、
17563 @var{runs}回のテストをスキップしたということだけを記録します。
17564 最後に、@code{test-property-error}と@code{test-property-error-type}は
17565 @var{property-check}が常にエラーを投げることを期待します。
17566 @code{test-property-error-type}はそれに加え、投げられるエラーが
17567 @var{error-type}コンディションタイプであることを期待します。
17568 @c COMMON
17569
17570 @c EN
17571 This SRFI is designed to be used with SRFI-64, but you can use these
17572 directly with @code{gauche.test} without loading @code{srfi.64}.
17573 @c JP
17574 SRFIではこれらのテストはSRFI-64のフレームワーク上で実行されることを
17575 想定していますが、@code{srfi.64}をロードせずに@code{gauche.test}のテストの
17576 一環として実行することも可能です。
17577 @c COMMON
17578 @end defmac
17579
17580 @defun property-test-runner
17581 [SRFI-252]
17582 @c MOD srfi.252
17583 Returns a SRFI-64 test runner object specialized for property testing.
17584 In Gauche, this simply returns SRFI-64 simple runner, but other
17585 implementations may have some additional features. It is recommended
17586 that portable code sets the runner created with this procedure
17587 before calling property test procedures.
17588 @end defun
17589
17590 @subheading Generators
17591
17592 These are procedures that create generators of specific types.
17593 You can find similar generator procedurs in @code{data.random}
17594 (@pxref{Random data generators})
17595 and @code{srfi.194} (@pxref{Random data generators (SRFI)}),
17596 but the procedures here creates generators with one specific
17597 property suitable for testing: They start generating certain
17598 pre-defined values--typical, or boundary values--before generating
17599 random values.
17600
17601 All created generators captures the value of parameter
17602 @code{random-data-random-source} (@pxref{Random data generators}) when created.
17603 If you want to have reproducible results, you can provide your own
17604 random source.
17605
17606 @defun boolean-generator
17607 [SRFI-252]
17608 @c MOD srfi.252
17609 Returns a generator that yields @code{#t} and @code{#f}, then
17610 a random boolean values in equal probability.
17611
17612 See also @code{booleans$} in @code{data.random}
17613 (@pxref{Random data generators}).
17614 @end defun
17615
17616 @defun bytevector-generator
17617 [SRFI-252]
17618 @c MOD srfi.252
17619 Returns a generator that yields an empty bytevector @code{#u8()} first,
17620 then bytevectors of random length and random content subsequently.
17621
17622 In Gauche, it is realized as follows (@pxref{Random data generators},
17623 for @code{sequences-of} and @code{integers$}).
17624 The constant @code{sequence-max-size} is currently 33 but may be
17625 changed.
17626 @example
17627 (gcons* '#u8()
17628 (sequences-of <u8vector>
17629 (integers$ sequence-max-size)
17630 (integers$ 256))))
17631 @end example
17632 @end defun
17633
17634 @defun char-generator
17635 [SRFI-252]
17636 @c MOD srfi.252
17637 Returns a character generator that yields @code{#\null}, then
17638 random characters subsequently. Currently we sample
17639 charactres uniformly from the entire Unicode range, but that
17640 causes most of the characters to be very infrequently used ones.
17641 We might change it in future.
17642
17643 See also @code{chars$} in @code{data.random}
17644 (@pxref{Random data generators}).
17645 @end defun
17646
17647 @defun string-generator
17648 [SRFI-252]
17649 @c MOD srfi.252
17650 Returns a string generator that yields an empty string @code{""},
17651 then strings of random length and random content subsequently.
17652
17653 In Gauche, it is realized as follows (@pxref{Random data generators},
17654 for @code{strings-of} and @code{integers$}).
17655 The constant @code{sequence-max-size} is currently 33 but may be
17656 changed.
17657 @example
17658 (gcons* ""
17659 (strings-of (integers$ sequence-max-size) (chars$ char-set:full)))
17660 @end example
17661
17662 Note that the chracters are sampled uniformly from the entire Unicode
17663 range, which causes almost all strings to consist of very infrequently
17664 used characters. We might address this in future.
17665 @end defun
17666
17667 @defun symbol-generator
17668 [SRFI-252]
17669 @c MOD srfi.252
17670 Returns a symbol generator that yields a symbol whose name
17671 is empty (@code{||}), then symbols of random length and
17672 random content subsequently. It is basically
17673 @code{(gmap string->symbol (string-generator))}.
17674
17675 Note that the chracters are sampled uniformly from the entire Unicode
17676 range, which causes almost all symbols to consist of very infrequently
17677 used characters. We might address this in future.
17678 @end defun
17679
17680 @defun complex-generator
17681 @defunx inexact-complex-generator
17682 [SRFI-252]
17683 @c MOD srfi.252
17684 Returns a generator that yields the following inexact complex
17685 numbers, followed by random complex numbers.
17686
17687 @example
17688 0.0 -0.0 0.5 -0.5 1.0 -1.0
17689 0.0+1.0i 0.0-1.0i -0.0+1.0i -0.0-1.0i
17690 0.5+0.5i 0.5-0.5i -0.5+0.5i -0.5-0.5i
17691 1.0+1.0i 1.0-1.0i -1.0+1.0i -1.0-1.0i
17692 +inf.0+inf.0i +inf.0-inf.0i -inf.0+inf.0i -inf.0-inf.0i
17693 +nan.0+nan.0i
17694 +inf.0 -inf.0 +nan.0
17695 @end example
17696
17697 Note: SRFI specifies @code{complex-generator} to return
17698 both exact and inexact complex numbers if the implementation supports
17699 them. Gauche doesn't have exact complex numbers, so it is the
17700 same as @code{inexact-complex-generator}.
17701
17702 In Gauche, a random complex number is created by
17703 uniformly sampled finite flonums for real and imaginary parts.
17704 Note that ``uniformly sampled finite flonums'' are not the same
17705 as ``uniformly sampled real numbers''; See @code{finite-flonums$}
17706 for the details (@pxref{Random data generators}).
17707 @end defun
17708
17709 @defun exact-complex-generator
17710 @defunx exact-integer-complex-generator
17711 [SRFI-252]
17712 @c MOD srfi.252
17713 Gauche does not support exact complex numbers, and these procedures
17714 raise an error when called.
17715 @end defun
17716
17717 @defun integer-generator
17718 @defunx exact-integer-generator
17719 @defunx inexact-integer-generator
17720 [SRFI-252]
17721 @c MOD srfi.252
17722 Return generators that yields integers, exact integers,
17723 and inexact integers, respectively.
17724
17725 The exact integer generator always yield @code{0}, @code{1}, and @code{-1}
17726 at the beginning, then random integers follow.
17727
17728 The inexact integer generator always yield @code{0.0}, @code{-0.0},
17729 @code{1.0}, and @code{-1.0}
17730 at the beginning, then random integers follow.
17731
17732 The general integer generator created by @code{integer-generator}
17733 samples evenly from an exact integer genratgor and an inexact
17734 integer generator.
17735
17736 Since the range of exact integers is only bounded by the memory,
17737 uniform sampling from the entire possible range is infeasible;
17738 almost all samples would become a huge integer. Instead, we split
17739 integer range into 3: relatively small integers,
17740 fixnums, and bignums, and sample evenly from these three generators.
17741 Small integers and fixnums are sampled uniformly within its range,
17742 and bignums are sampled according to the power law; so, we see
17743 a lot more bignums closer to fixnum range, with occasional really big
17744 numbers sprinkled in.
17745 @end defun
17746
17747 @defun rational-generator
17748 @defunx exact-rational-generator
17749 @defunx inexact-rational-generator
17750 [SRFI-252]
17751 @c MOD srfi.252
17752 Return generators that yields rational numbers, exact rational numbers,
17753 and inexact rational numbers, respectively.
17754
17755 The exact rational number generator yields
17756 @code{0}, @code{1}, @code{-1}, @code{1/2}, and @code{-1/2} at
17757 the beginning, then generate @code{(/ a b)} where @code{a}, @code{b}
17758 are generated in the same way as @code{exact-integer-generator}'s
17759 distribution, except 0 is excluded from @code{b}.
17760
17761 The inexact rational number generator yields
17762 @code{0.0}, @code{-0.0}, @code{0.5}, @code{=0.5}, @code{1.0}, and @code{-1.0}
17763 at the beginning, then proceed to generate random inexact rational numbers.
17764 In Gauche, inexact rational numbers are finite flonums, and we uniformly
17765 samples from all possible finite flonums (which is @emph{not} the same
17766 as uniform sample from a range of real numbers).
17767 See @code{finite-flonums$} in @ref{Random data generators}.
17768
17769 The general rational number generator created by @code{rational-generator}
17770 evenly samples from an exact rational number generator and
17771 an inexact rational number generator.
17772 @end defun
17773
17774 @defun real-generator
17775 @defunx exact-real-generator
17776 @defunx inexact-real-generator
17777 [SRFI-252]
17778 @c MOD srfi.252
17779 Return generators that yields real numbers, exact real numbers,
17780 and inexact real numbers, respectively.
17781
17782 In Gauche, the set of exact real numbers are exactly the same as
17783 the set of exact rational numbers (infinites and NaNs are inexact),
17784 so @code{exact-real-generator} is the same as
17785 @code{exact-rational-generator}.
17786
17787 The inexact real number generator yields
17788 @code{0.0}, @code{-0.0}, @code{0.5}, @code{-0.5},
17789 @code{1.0}, @code{-1.0}, @code{+inf.0}, @code{-inf.0}, and @code{+nan.0}
17790 at the beginning, followed by inexact real numbers uniformly sampled
17791 from all possible finite flonums (which is @emph{not} the same
17792 as uniform sample from a range of real numbers).
17793 See @code{finite-flonums$} in @ref{Random data generators}.
17794
17795 The general real number generator created by @code{real-generator}
17796 evenly samples from an exact real number generator and
17797 an inexact real number generator.
17798 @end defun
17799
17800 @defun number-generator
17801 @defunx exact-number-generator
17802 @defunx inexact-number-generator
17803 [SRFI-252]
17804 @c MOD srfi.252
17805 In Gauche, the set of exact numbers is the same as
17806 the set of exact rational numbers (we don't have exact complex),
17807 and the set of inexact numbers
17808 is the same as the set of inexact complex numbers.
17809 Thus @code{exact-number-generator} is the same as
17810 @code{exact-rational-generator}, and
17811 @code{inexact-number-generator} is the same as
17812 @code{inexact-complex-generator}.
17813
17814 The general number generator created by @code{number-generator}
17815 evenly samples from an exact number generator and
17816 an inexact number generator.
17817 @end defun
17818
17819 @defun list-generator-of elt-generator :optional max-length
17820 @defunx vector-generator-of elt-generator :optional mex-length
17821 [SRFI-252]
17822 @c MOD srfi.252
17823 Return generators that yield a list/vector of random length
17824 up to @var{max-length},
17825 and elements generated by @var{elt-generator}, respectively.
17826 Similar to @code{lists-of}/@code{vectors-of} in @code{data.random}.
17827
17828 When @var{max-length} is omitted, we leave the length to the default
17829 of @code{lists-of}/@code{vectors-of},
17830 which is determined by the parameter
17831 @code{default-sizer} in @code{data.random}.
17832 @xref{Random data generators}, for the details.
17833 @end defun
17834
17835 @defun pair-generator-of car-generator :optional cdr-generator
17836 [SRFI-252]
17837 @c MOD srfi.252
17838 Returns a generator that yields pairs, whose car is generated
17839 with @code{car-generator} and whose cdr is generated
17840 with @code{cdr-generator}. If @var{cdr-generator} is omitted,
17841 @code{car-generator} is used.
17842 @end defun
17843
17844 @defun procedure-generator-of value-generator
17845 [SRFI-252]
17846 @c MOD srfi.252
17847 Returns a generator that yields procedures, which accepts
17848 any number of arguments and returns a value generated with
17849 @var{value-generator}.
17850 @end defun
17851
17852
17853 @c Local variables:
17854 @c mode: texinfo
17855 @c coding: utf-8
17856 @c end: