Debian Codegraph @

doc/modr7rs.texi

raw
1 @node Library modules - R7RS standard libraries, Library modules - SRFIs, Library modules - Gauche extensions, Top
2 @chapter Library modules - R7RS standard libraries
3
4 @c NODE ライブラリモジュール - R7RS標準ライブラリ
5
6 @c EN
7 Gauche predates R7RS, and for the convenience, Gauche makes quite a few
8 procedures as built-in (@pxref{Core library}). Although the set of
9 Gauche's core features are mostly superset of R7RS, some functions
10 and syntaxes have different names and/or interface from R7RS.
11
12 R7RS fully-compatible syntaxes and functions are available
13 in the set of modules described in this chapter. Since R7RS
14 programs and libraries needs to follow a specific format
15 (@code{import} declaration or @code{define-library} form),
16 generally there's no ambiguity in whether you're looking at R7RS code
17 or Gauche-specific code. Also, it is totally transparent to load
18 R7RS library into Gauche-specific code or vice versa.
19 However, you need to be aware of which ``world'' you're in when
20 you code.
21 @c JP
22 GaucheはR7RS以前からあり、使い勝手のために非常に多くの組み込み手続きを
23 持っています(@ref{Core library}参照)。そのほとんどはR7RSのスーパーセットと
24 なっていますが、いくつかの手続きや構文は違う名前であったり、
25 違うインタフェースを取っていたりします。
26
27 R7RSと完全に互換な構文と関数は、本章で説明されるモジュール群によって提供されます。
28 R7RSプログラムとライブラリは特定の形式で書かれるので
29 (@code{import}宣言で始まるか、もしくは@code{define-library}フォーム)、
30 通常はR7RSのコードを見ているのかGauche特有のコードを見ているのかははっきり区別できます。
31 また、Gauche特有のコードからR7RSライブラリをロードすることも、その逆も、
32 全く透過的にできます。
33 但し、コードを書く時には、どちらの「世界」にいるのかを意識する必要があります。
34 @c COMMON
35
36 @c EN
37 If you're familiar with Gauche, take a look at
38 the section @ref{R7RS integration}, which describes how you can
39 go back and forth between Gauche and R7RS.
40 @c JP
41 Gaucheに慣れているプログラマは、まず@ref{R7RS integration}に目を通してください。
42 どうやってGaucheとR7RSの世界を行き来するか説明してあります。
43 @c COMMON
44
45 @menu
46 * R7RS integration::
47 * R7RS small language::
48 * R7RS large::
49 @end menu
50
51
52 @node R7RS integration, R7RS small language, Library modules - R7RS standard libraries, Library modules - R7RS standard libraries
53 @section R7RS integration
54 @c NODE R7RS統合
55
56 @menu
57 * Traveling between two worlds back and forth::
58 * Three forms of import::
59 @end menu
60
61 @node Traveling between two worlds back and forth, Three forms of import, R7RS integration, R7RS integration
62 @subsection Traveling between two worlds back and forth
63 @c NODE 二つの世界を往き来する
64
65 @c EN
66 When you start Gauche, either in REPL or as a script, you're in
67 @code{user} module, which @emph{inherits} @code{gauche} module.
68 Likewise, when you read a library, the initial module inherits
69 @code{gauche} module (until you call @code{select-module}).
70 That's why you can access all the built-in procedures of Gauche
71 without saying @code{(use something)}. (@xref{Module inheritance}, for
72 the details about inheriting modules).
73 @c JP
74 Gaucheを起動した直後は、それがREPLであってもスクリプトファイルの実行であっても、
75 トップレベルは@code{user}モジュールになっています。@code{user}モジュールは
76 @code{gauche}モジュールを@emph{継承}しています。
77 また、ライブラリを読み込む際にも、(@code{select-module}が呼ばれるまでは)
78 トップレベルは@code{gauche}を継承したモジュールになっています。
79 これが、@code{(use something)}等といちいち書かないでも
80 Gaucheの組み込み手続きを使える理由です。
81 (モジュールの継承については@ref{Module inheritance}を参照してください)。
82 @c COMMON
83
84 @c EN
85 On the other hand, R7RS requires to be explicit about which namespaces
86 you'll be using, by @code{import} form, e.g. @code{(import (scheme base))}.
87 Besides, R7RS library must be explicitly enclosed by @code{define-library} form.
88 Before the first @code{import} form of a program, or outside of
89 @code{define-library}, is beyond R7RS world---the standard defines
90 nothings about it.
91 @c JP
92 一方、R7RSでは@code{import}フォームによってどの名前空間を利用するか明示することが
93 求められています(例: @code{(import (scheme base))})。
94 また、R7RSライブラリはそれぞれ@code{define-library}フォームで囲う必要があります。
95 プログラムの最初の@code{import}より前、あるいはライブラリの@code{define-library}の
96 外側は、R7RSの世界の外であり、標準では何も規定していません。
97 @c COMMON
98
99 @c EN
100 These facts let Gauche to set up appropriate ``world'',
101 and you can use R7RS code and traditional Gauche code transparently.
102 @c JP
103 Gaucheはこれを利用して、適切な「世界」を設定し、R7RSコードと既存のGaucheコードを
104 透過的に混ぜられるようにしています。
105 @c COMMON
106
107 @c EN
108 NB: As explained in @ref{Three forms of import},
109 R7RS @code{import} is rather different from Gauche
110 @code{import}, so we note the former @code{r7rs#import} and the latter
111 @code{gauche#import} in this section for clarity. When you write code
112 don't use prefixes @code{r7rs#} and @code{gauche#}; just write @code{import}.
113 @c JP
114 註:@ref{Three forms of import}で説明しますが、
115 R7RSの@code{import}はGaucheの@code{import}と異なります。この節では
116 区別が必要な時は前者を@code{r7rs#import}、後者を@code{gauche#import}と
117 表記しますが、実際のコードでは@code{r7rs#}や@code{gauche#}といったプレフィクスを
118 つけずに、単に@code{import}と書いてください。
119 @c COMMON
120
121 @c EN
122 @subheading Loading R7RS libraries
123 @c JP
124 @subheading R7RSライブラリをロードする
125 @c COMMON
126
127 @c EN
128 The @code{define-library} form is defined as a macro in @code{gauche} module;
129 it sets up R7RS environment before evaluating its contents.
130 So, when you load an R7RS library (either from Gauche code via @code{use}
131 form, or from R7RS code via @code{r7rs#import} form),
132 Gauche starts loading the file in @code{gauche} module, but immediately
133 see @code{define-library} form, and the rest is handled in R7RS
134 environment.
135 @c JP
136 @code{define-library}フォーム自身は、@code{gauche}モジュール内のマクロとして
137 定義されていて、R7RS環境を設定してその中身を評価するコードに展開されます。
138 (Gaucheコードから@code{use}を使うか、
139 R7RSコードから@code{r7rs#import}フォームを使うかして)R7RSライブラリをロードすると、
140 Gaucheはファイルの評価を@code{gauche}モジュール内で始めますが、すぐに
141 @code{define-library}フォームに当たるので、その中身はR7RS環境で処理されることになります。
142 @c COMMON
143
144 @c EN
145 Suppose you have an R7RS library @code{(mylib foo)} with the following code:
146 @c JP
147 以下のコードを持つ、R7RSライブラリ@code{(mylib foo)}があるとしましょう。
148 @c COMMON
149
150 @example
151 (define-library (mylib foo)
152 (import (scheme base))
153 (export snoc)
154 (begin
155 (define (snoc x y) (cons y x))))
156 @end example
157
158 @c EN
159 It should be saved as @file{mylib/foo.scm} in one of the directories in
160 @code{*load-path*}.
161 @c JP
162 このファイルは@code{*load-path*}にあるディレクトリのどれかの下に、
163 @file{mylib/foo.scm}という名前で保存されなければなりません。
164 @c COMMON
165
166 @c EN
167 From R7RS code, this library can be loaded by @code{r7rs#import}:
168 @c JP
169 R7RSコードからは、このライブラリは@code{r7rs#import}フォームでロードできます。
170 @c COMMON
171
172 @example
173 (import (mylib foo))
174
175 (snoc 1 2) @result{} (2 . 1)
176 @end example
177
178 @c EN
179 To use this library from Gauche code, concatenate elements of library
180 names by @code{.} to get a module name, and @code{use} it:
181 @c JP
182 Gaucheコードからこのライブラリを使うには、ライブラリ名の各要素を@code{.}で
183 つなげたものをモジュール名として、@code{use}します。
184 @c COMMON
185
186 @example
187 (use mylib.foo)
188
189 (snoc 1 2) @result{} (2 . 1)
190 @end example
191
192 @c EN
193 @subheading Loading Gauche libraries
194 @c JP
195 @subheading Gaucheライブラリのロード
196 @c COMMON
197
198 @c EN
199 To use Gauche library @code{foo.bar} from R7RS code,
200 split the module name by @code{.} to make a list for the name
201 of the library. For example, @code{gauche.lazy} module can be
202 used from R7RS as follows:
203 @c JP
204 Gaucheライブラリの@code{foo.bar}をR7RSコードから使うには、
205 モジュール名を@code{.}で区切った名前のリストをライブラリ名として使います。
206 例えば@code{gauche.lazy}モジュールは次のとおりR7RSから使えます。
207 @c COMMON
208
209 @example
210 (import (gauche lazy))
211 @end example
212
213 @c EN
214 For SRFI modules, R7RS implementations have a convention to
215 name it as @code{(srfi n)}, and Gauche follows it.
216 The following code loads SRFI-1 and SRFI-13 from R7RS code:
217 @c JP
218 SRFIモジュールについては、R7RSでは慣習的に@code{(srfi n)}という
219 名前を使うので、Gaucheもそれに合わせています。R7RSコードから
220 SRFI-1とSRFI-13を使うには、次のようにします。
221 @c COMMON
222
223 @example
224 (import (srfi 1) (srfi 13))
225 @end example
226
227 @c EN
228 (It's not that Gauche treat @code{srfi} name specially; installation
229 of Gauche includes adapter libraries such as @file{srfi/1.scm}.)
230 @c JP
231 (これが動くのは、Gaucheが@code{srfi}という名前を特別扱いしているのではなく、
232 Gaucheをインストールした時に@code{srfi/1.scm}等のアダプタライブラリが作られているからです)
233 @c COMMON
234
235 @c EN
236 A tip: To use Gauche's built-in features (the bindings that are
237 available by default in Gauche code) from R7RS code, import
238 @code{(gauche base)} library (@pxref{Importing gauche built-ins}):
239 @c JP
240 ヒント: Gaucheの組み込みの機能 (Gaucheコードでは最初から使える束縛) を
241 R7RSコードから使いたい場合は、@code{(gauche base)}ライブラリをimportしてください
242 (@ref{Importing gauche built-ins}参照)。
243 @c COMMON
244
245 @example
246 (import (gauche base))
247
248 filter @result{} #<closure filter>
249 @end example
250
251 @c EN
252 @subheading Running R7RS scripts
253 @c JP
254 @subheading R7RSスクリプトの実行
255 @c COMMON
256
257 @c EN
258 R7RS scripts always begin with @code{import} form. However, @code{r7rs#import}
259 has a different syntax and semantics
260 from @code{gauche#import}---so we employ a trick.
261 @c JP
262 R7RSスクリプトは必ず@code{import}フォームで始まります。
263 しかし、@code{r7rs#import}は@code{gauche#import}と文法や意味が異なります。
264 そこで、ちょっとしたトリックを使っています。
265 @c COMMON
266
267 @c EN
268 When @code{gosh} is started, it loads the given script file
269 in @code{user} module. We have a separate @code{user#import} macro, which
270 examines its arguments and if it is R7RS import syntax, switch to the
271 @code{r7rs.user} module and run the @code{r7rs#import}. Otherwise, it
272 runs @code{gauche#import}. @xref{Three forms of import}, for the details.
273 @c JP
274 @code{gosh}がスクリプトファイルを読み込むのは@code{user}モジュールです。
275 そこには@code{user#import}というマクロが用意してあり、
276 そのマクロは引数を調べて、それがR7RSのimportの構文であれば
277 @code{r7rs.user}モジュールに切り替えて@code{r7rs#import}を実行し、
278 そうでなければ@code{gauche#import}を実行します。
279 詳しくは@ref{Three forms of import}を参照してください。
280 @c COMMON
281
282 @c EN
283 An example of R7RS script:
284 @c JP
285 R7RSスクリプトの例です:
286 @c COMMON
287
288 @example
289 (import (scheme base) (scheme write))
290 (display "Hello, world!\n")
291 @end example
292
293 @c EN
294 If you're already familiar with Gauche scripts, keep in mind that
295 R7RS program doesn't treat @code{main} procedure specially; it
296 just evaluates toplevel forms from top to bottom. So the following
297 script doesn't output anything:
298 @c JP
299 Gaucheスクリプトを見慣れている人は、R7RSプログラムが@code{main}手続きを
300 特別扱いしないことに気をつけてください。R7RSプログラムは、トップレベルフォームを
301 順に評価してゆくだけです。したがって次のスクリプトは何も表示しません:
302 @c COMMON
303
304 @example
305 (import (scheme base) (scheme write))
306 (define (main args)
307 (display "Hello, world!\n")
308 0)
309 @end example
310
311 @c EN
312 To access the command-line arguments in R7RS scripts, use
313 @code{command-line} in @code{(scheme process-context)} library
314 (@pxref{R7RS process context}, also @pxref{Command-line arguments}).
315 @c JP
316 R7RSスクリプトからコマンドライン引数を利用するには、
317 @code{(scheme process-context)}ライブラリの@code{command-line}を使います
318 (@ref{R7RS process context} および @ref{Command-line arguments}参照)。
319 @c COMMON
320
321 @c EN
322 @subheading Using R7RS REPL
323 @c JP
324 @subheading R7RS REPLを使う
325 @c COMMON
326
327 @c EN
328 When @code{gosh} is invoked with @code{-r7} option and no script file is
329 given, it enters an R7RS REPL mode. For the convenience, the following
330 modules (``libraries'', in R7RS term) are pre-loaded.
331 @c JP
332 @code{gosh}が@code{-r7}オプションつきで起動され、スクリプトファイルが
333 与えられていなかった場合は、R7RS REPLモードになります。
334 使いやすいように、以下のモジュール (R7RS用語では「ライブラリ」)は
335 自動的にロードされます。
336 @c COMMON
337
338 @example
339 (scheme base) (scheme case-lambda) (scheme char)
340 (scheme complex) (scheme cxr) (scheme eval)
341 (scheme file) (scheme inexact) (scheme lazy)
342 (scheme load) (scheme process-context) (scheme read)
343 (scheme repl) (scheme time) (scheme write)
344 @end example
345
346 @c EN
347 Besides, the history variables @code{*1}, @code{*2}, @code{*3},
348 @code{*1+}, @code{*2+}, @code{*3+}, @code{*e} and @code{*history}
349 are available (@xref{Working in REPL}, for the details of history variables).
350 @c JP
351 さらに、ヒストリ変数@code{*1}、@code{*2}、@code{*3}、
352 @code{*1+}、@code{*2+}、@code{*3+}、@code{*e} および
353 @code{*history}も使えます (ヒストリ変数の詳細については@ref{Working in REPL}参照)。
354 @c COMMON
355
356 @c EN
357 You can know you're in R7RS REPL by looking at the prompt, where
358 @code{gosh} shows the current module (@code{r7rs.user}):
359 @c JP
360 R7RS REPLにいることはプロンプトを見ればわかります。
361 現在のモジュールが@code{r7rs.user}となっているからです。
362 @c COMMON
363
364 @example
365 gosh[r7rs.user]>
366 @end example
367
368 @c EN
369 To switch Gauche REPL from R7RS REPL, import @code{(gauche base)} and
370 select @code{user} module using @code{select-module}:
371 @c JP
372 R7RS REPLからGauche REPLにスイッチするには、@code{(gauche base)}を
373 インポートして@code{select-module}を使って@code{user}モジュールを選びます。
374 @c COMMON
375
376 @example
377 gosh[r7rs.user]> (import (gauche base))
378 #<undef>
379 gosh[r7rs.user]> (select-module user)
380 #<undef>
381 gosh>
382 @end example
383
384 @c EN
385 (You can @code{(select-module gauche)} but that's usually not what you
386 want to do---changing @code{gauche} module can have unwanted side effects.)
387 @c JP
388 (@code{(select-module gauche)}とする手もありますが、おすすめはしません。
389 @code{gauche}モジュールの中を変えると思いがけない副作用が生じるかもしれませんから。)
390 @c COMMON
391
392 @c EN
393 When you're working on R7RS code in file and load it into R7RS REPL
394 (for example, if you're using Emacs Scheme mode, C-c C-l does the job),
395 make sure the file is in proper shape as R7RS; that is, the file
396 must start with appropriate @code{import} declarations, or
397 the file contains @code{define-library} form(s). If you load
398 file without those forms, it is loaded into Gauche's @code{user} module
399 no matter what your REPL's current module is,
400 and the definitions won't be visible from @code{r7rs.user} module
401 by default.
402 @c JP
403 R7RSコードをファイルに書きだし、R7RS REPLにそのファイルをロードしてインタラクティブに
404 開発を進めている場合 (例えばEmacsのSchemeモードなら、C-c C-lでファイルがロードできます)、
405 そのファイルがR7RSとして正しい形式になっていることを確認してください。
406 つまり、ファイルは@code{import}宣言で始まるか、@code{define-library}形式
407 から構成されるものでなければなりません。それ以外の、単にSchemeコードが並べて
408 書いてあるだけのファイルをロードした場合、
409 それはREPLでの現在のモジュールが何であるかにかかわらずGaucheの@code{user}モジュールに
410 読み込まれるので、@code{r7rs.user}モジュールからはデフォルトでは見えません。
411 @c COMMON
412
413 @c EN
414 @subheading Switching from Gauche REPL
415 @c JP
416 @subheading Gauche REPLからのスイッチ
417 @c COMMON
418
419 @c EN
420 By default, @code{gosh} enters Gauche REPL when no script file is given.
421 @xref{Working in REPL}, for detailed explanation of using REPL.
422 @c JP
423 デフォルトでは、@code{gosh}はスクリプトファイルが与えられなければGaucheのREPLに
424 入ります。REPLの説明は@ref{Working in REPL}を参照してください。
425 @c COMMON
426
427 @c EN
428 To switch Gauche REPL to R7RS REPL, simply use r7rs-style import;
429 @code{user#import} knows you want R7RS and make a switch.
430 @c JP
431 Gauche REPLからR7RS REPLにスイッチするには、
432 単にr7rsスタイルのimportを使うだけです。@code{user#import}は
433 あなたが欲しいのがR7RSであることを察知して環境を切り替えます。
434 @c COMMON
435
436 @example
437 gosh> (import (scheme base))
438 #<undef>
439 gosh[r7rs.user]>
440 @end example
441
442 @c EN
443 If you don't start @code{gosh} with @code{-r7} option, however,
444 only the libraries you given to @code{user#import} are loaded at
445 this moment.
446 @c JP
447 ただし、@code{gosh}を@code{-r7}オプションつきで起動していなければ、
448 この時点でロードされているのは@code{user#import}で指定したライブラリだけです。
449 @c COMMON
450
451 @c EN
452 If you want to switch the ``vanilla'' r7rs environment, that is, even
453 not loading @code{(scheme base)}, then you can use @code{r7rs}
454 module and directly select @code{r7rs.user}:
455 @c JP
456 もし、「すっぴん」のR7RS環境、つまり@code{(scheme base)}でさえロードされていない
457 環境へと切り替えたければ、@code{r7rs}モジュールをuseして
458 直接@code{r7rs.user}モジュールを選択します。
459 @c COMMON
460
461 @example
462 gosh> (use r7rs)
463 gosh> (select-module r7rs.user)
464 gosh[r7rs.user]>
465 @end example
466
467 @c EN
468 If you do this, the only
469 bindings visible initially are @code{import} and @code{define-library};
470 even @code{define} is undefined!
471 You have to manually do @code{(import (scheme base))} etc. to start
472 writing Scheme in this environment.
473 @c JP
474 こうして切り替えた場合、使えるフォームは@code{import}と@code{define-library}
475 だけです (@code{define}でさえ定義されていません!)
476 この環境でSchemeを書くには、まず @code{(import (scheme base))} 等として
477 束縛をインポートする必要があります。
478 @c COMMON
479
480
481 @node Three forms of import, , Traveling between two worlds back and forth, R7RS integration
482 @subsection Three import forms
483 @c NODE 3つのimport形式
484
485 @c EN
486 For historical reasons, Gauche has three @code{import} forms; the original
487 Gauche's @code{import}, R7RS @code{import}, and the hybrid @code{import}.
488
489 Usually it is clear that the code is written in traditional Gauche
490 or in R7RS, and usage of @code{import} is typically idiomatic, so there's
491 not much confusion in practice. Only when you talk about @code{import}
492 outside of code, you might need to specify which one you're talking.
493
494 The hybrid @code{import} is what we described @code{user#import} in
495 the previous section (@pxref{Traveling between two worlds back and forth}).
496 It understands both of Gauche's @code{import} and
497 R7RS @code{import}.
498 So what you really need to know is the first two.
499 @c JP
500 歴史的な事情から、Gaucheには@code{import}形式が3つあります。
501 もともとのGaucheの@code{import}、R7RSの@code{import}、
502 そしてハイブリッドの@code{import}です。
503
504 通常、コードを読み書きしている時は、それが伝統的なGaucheコードかR7RSコードかは
505 明確ですし、また@code{import}の使われ方はだいたい決まっているので、
506 現場で混乱が起きることはありません。ただ、コードの外で@code{import}について
507 話す場合は、どの@code{import}のことかをはっきりさせるのが良いでしょう。
508
509 ハイブリッドの@code{import}は前節で説明した@code{user#import}です
510 (@ref{Traveling between two worlds back and forth}参照)。
511 @code{user#import}は
512 Gaucheの@code{import}とR7RSの@code{import}の両方の文法を理解できるので、
513 実際に知る必要のあるのは最初の2つの形式です。
514 @c COMMON
515
516 @c EN
517 Gauche's module system design is inherited from STk, and we've been
518 used @code{import} for purely name-space level operation; that is,
519 it assumes the module you import from already exists in memory.
520 Loading a file that defines the module (if necessary) is
521 done by separate primitives, @code{require}. In most cases one file
522 defines one module, and using that module means @code{require} it then
523 @code{import} it (it's so common that Gauche has a macro for it---@code{use}).
524 However, separating those two sometimes comes handy when you need
525 some nontrivial hacks. @xref{Using modules}, for the details of
526 Gauche's @code{import}.
527 @c JP
528 Gaucheのモジュールシステム設計はSTkを継承していて、
529 @code{import}は純粋に名前空間の操作として使われています。
530 つまり、既にメモリ上に存在するモジュールをインポートするということです。
531 そのモジュールが定義されているファイルを、(必要なら)ロードするという
532 操作は別のプリミティブ@code{require}により実現されます。
533 典型的には、ひとつのファイルがひとつのモジュールを定義していて、
534 そのモジュールを使うにはまずファイルを@code{require}し、
535 次にモジュールを@code{import}するということになります
536 (これはGaucheでは頻繁に出てくるので、@code{use}というマクロが定義されているくらいです)。
537 ファイルのロードとモジュールのインポートが分かれていることは、
538 たまに変わったハックが必要とされる時に役に立ちます。
539 Gaucheの@code{import}については@ref{Using modules}を参照してください。
540 @c COMMON
541
542 @c EN
543 R7RS leaves out the relation between modules (libraries) and files
544 in order to give implementation freedom. If necessary, its @code{import}
545 must load a file implicitly and transparently. So R7RS's @code{import}
546 is semantically Gauche's @code{use}.
547 @c JP
548 R7RSは実装に選択の余地を与えるため、モジュール(ライブラリ)とファイルの関係は
549 敢えて規定していません。R7RSの@code{import}は、
550 必要ならば暗黙のうちに、透過的にファイルをロードすることが期待されています。
551 つまり、R7RSの@code{import}はGaucheの@code{use}と意味的に同じと考えられます。
552 @c COMMON
553
554 @c EN
555 The hybrid @code{import} only appears at the beginning of the Scheme
556 scripts. It finds out whether the script is in the traditional Gauche
557 code or in the R7RS code. @xref{Traveling between two worlds back and forth}, for the details.
558 @c JP
559 ハイブリッド@code{import}はSchemeスクリプトの最初にのみ現れて、
560 実行されるスクリプトが伝統的なGaucheコードであるかR7RSコードであるかを
561 判断します。詳細は@ref{Traveling between two worlds back and forth}を参照してください。
562 @c COMMON
563
564 @c EN
565 Now we'll explain R7RS @code{import}:
566 @c JP
567 ではR7RSの@code{import}を説明します:
568 @c COMMON
569
570
571 @defspec import import-spec @dots{}
572 [R7RS]
573 @c EN
574 Imports libraries specified by @var{import-spec}s. What R7RS calls
575 libraries are what Gauche calls modules; they're the same thing.
576 @c JP
577 @var{import-spec}で指定されるライブラリをインポートします。
578 R7RSでいうライブラリは、Gaucheがモジュールと呼んできたものです。両者は同じものです。
579 @c COMMON
580
581 @c EN
582 R7RS libraries are named by a list of symbols or integers,
583 e.g. @code{(scheme base)} or @code{(srfi 1)}.
584 It is translated to Gauche's module name by joining the symbols
585 by periods; so, R7RS @code{(scheme base)} is Gauche's @code{scheme.base}.
586 Conversely, Gauche's @code{data.queue} is available as
587 @code{(data queue)} in R7RS. To use those two libraries,
588 R7RS program needs this form at the beginning.
589 @c JP
590 R7RSライブラリの名前はシンボルか整数のリストで表されます。
591 例: @code{(scheme base)}、@code{(srfi 1)}。
592 この名前は、ピリオドを挟んでシンボル名をつなげることで、Gaucheのモジュール名へと
593 変換されます。つまり、R7RSの@code{(scheme base)}はGaucheからは@code{scheme.base}
594 モジュールとして扱えます。逆にGaucheの@code{data.queue}モジュールは
595 R7RSからは@code{(data queue)}ライブラリとして扱えます。
596 R7RSプログラムからこれら二つのライブラリを使うには、プログラムの最初に
597 次のように記します。
598 @c COMMON
599
600 @example
601 (import (scheme base)
602 (data queue))
603 @end example
604
605 @c EN
606 It works just like Gauche's @code{use} forms; that is, if the named
607 module doesn't exist in the current process, it loads the file; then
608 the module's exported bindings become visible from the current module.
609 @c JP
610 これはGaucheで@code{use}フォームを使うのと同じです。つまり、もし
611 その名前を持つモジュールが現在のプロセス内に無ければまずファイルをロードし、
612 それからモジュールがexportしている束縛を現在のモジュールから見えるようにします。
613 @c COMMON
614
615 @example
616 (use scheme.base)
617 (use data.queue)
618 @end example
619
620 @c EN
621 (You may wonder what if R7RS library uses symbols with periods in them.
622 Frankly, we haven't decided yet. It'll likely be that we use some
623 escaping mechanism; for the time being you'd want to stick with
624 alphanumeric characters and hyphens as possible.)
625 @c JP
626 (勘の良い読者は、R7RSのライブラリがピリオドを中に含むシンボルを名前に使っていたら
627 どうなるのか疑問に思ったことでしょう。正直なところ、まだどうするか決めていません。
628 多分、何らかのエスケープ機構を用意することになると思いますが、
629 今のところ、できる限りモジュール名にはアルファベット、数字、ハイフンだけを
630 使うようにしておいて下さい。)
631 @c COMMON
632
633 @c EN
634 Just like Gauche's @code{use}, you can select which symbols to be
635 imported (or not imported), rename specific symbols, or add
636 prefix to all imported symbols. The formal syntax
637 of R7RS import syntax is as follows:
638 @c JP
639 R7RSの@code{import}フォームは、
640 Gaucheの@code{use}と同様、どのシンボルをimportするか/しないかを指定したり、
641 名前を変えてimportしたりプレフィクスを付加することができます。
642 R7RSの@code{import}の正式な構文は次の通りです。
643 @c COMMON
644
645 @smallexample
646 <import declaration> : (import <import-set> <import-set> ...)
647
648 <import-set> : <library-name>
649 | (only <import-set> <identifier> <identifier> ...)
650 | (except <import-set> <identifier> <identifier> ...)
651 | (prefix <import-set> <identifier>)
652 | (rename <import-set>
653 (<identifier> <identifier>)
654 (<identifier> <identifier>) ...)
655
656 <library-name> : (<identifier-or-base-10-integer>
657 <identifier-or-base-10-integer> ...)
658 @end smallexample
659 @end defspec
660
661 @node R7RS small language, R7RS large, R7RS integration, Library modules - R7RS standard libraries
662 @section R7RS small language
663 @c NODE R7RS small language
664
665 @menu
666 * R7RS library form::
667 * R7RS base library:: @code{scheme.base}
668 * R7RS case-lambda:: @code{scheme.case-lambda}
669 * R7RS char library:: @code{scheme.char}
670 * R7RS complex numbers:: @code{scheme.complex}
671 * R7RS cxr accessors:: @code{scheme.cxr}
672 * R7RS eval:: @code{scheme.eval}
673 * R7RS file library:: @code{scheme.file}
674 * R7RS inexact numbers:: @code{scheme.inexact}
675 * R7RS lazy evaluation:: @code{scheme.lazy}
676 * R7RS load:: @code{scheme.load}
677 * R7RS process context:: @code{scheme.process-context}
678 * R7RS read:: @code{scheme.read}
679 * R7RS repl:: @code{scheme.repl}
680 * R7RS time:: @code{scheme.time}
681 * R7RS write:: @code{scheme.write}
682 * R5RS compatibility:: @code{scheme.r5rs}
683 @end menu
684
685 @node R7RS library form, R7RS base library, R7RS small language, R7RS small language
686 @subsection R7RS library form
687 @c NODE R7RSライブラリ形式
688
689 @c EN
690 R7RS libraries are defined by @code{define-library} form.
691
692 In R7RS view, @code{define-library} form itself does not belong
693 to a Scheme code---it exists outside of the Scheme world.
694 It defines the boundary of
695 R7RS Scheme; inside @code{define-library} there is R7RS world,
696 but outside, it's not a business of R7RS.
697 For example, you can't generate
698 @code{define-library} by a macro, within R7RS specification.
699
700 In Gauche, we implement R7RS world inside Gauche world;
701 @code{define-library} itself is interpreted in the Gauche world.
702 In fact, @code{define-library} @emph{is} a Gauche macro.
703 However, if you're writing portable R7RS code, you should forget
704 how @code{define-library} is implemented, and do not put anything
705 outside of @code{define-library} form.
706 @c JP
707 R7RSのライブラリは@code{define-library}フォームで定義されます。
708
709 R7RSの観点では@code{define-library}フォーム自体はSchemeコードではありません。
710 それ自身はScheme世界の外にあります。@code{define-library}フォームが、
711 R7RS Schemeの境界となるのです。その内側はR7RSの世界であり、
712 その外側に関してR7RSは関知しません。例えば、R7RSの仕様の範囲内では、
713 @code{define-library}フォーム自体をマクロで生成する、ということはできません。
714
715 Gaucheでは、R7RSの世界をGaucheの世界の中に作っています。
716 @code{define-library}自体はGauche世界で解釈されます。実際、
717 @code{define-library}はGaucheのマクロとして実装されています。
718 けれどもR7RSのコードを書く際には、@code{define-library}がどう実装されているかは
719 気にする必要はありません。また、@code{define-library}の外側には
720 何も書かないようにしてください。
721 @c COMMON
722
723 @defmac define-library library-name library-decl @dots{}
724 [R7RS]
725 @c EN
726 Defines a library @var{library-name}, which is a list of
727 symbols or base-10 integer:
728 @c JP
729 @var{library-name}という名前を持つライブラリを定義します。
730 @var{library-name}はシンボルもしくは10進整数のリストです。
731 @c COMMON
732
733 @smallexample
734 <library-name> : (<identifier-or-base-10-integer>
735 <identifier-or-base-10-integer> ...)
736 @end smallexample
737
738 @c EN
739 Library declarations @var{library-decl}
740 can be export declarations, import declarations,
741 @code{begin}-list of Scheme code,
742 include forms, or @code{cond-expand} forms.
743 @c JP
744 ライブラリ宣言@var{library-decl}は、エクスポート宣言、
745 インポート宣言、@code{begin}に囲まれたSchemeコード、
746 インクルードフォーム、あるいは@code{cond-expand}フォームです。
747 @c COMMON
748
749 @smallexample
750 <library-decl> : (export <export-spec> @dots{})
751 | <import declaration>
752 | (begin <command-or-definition> @dots{})
753 | (include <string> <string2> @dots{})
754 | (include-ci <string> <string2> @dots{})
755 | (include-library-declarations
756 <string> <string2> @dots{})
757 | (cond-expand <cond-expand-clause>
758 <cond-expand-clause2> @dots{})
759 | (cond-expand <cond-expand-clause>
760 <cond-expand-clause2> @dots{}
761 (else <library-decl> @dots{}))
762 @end smallexample
763
764 @c EN
765 The @code{export} declaration is the same Gauche's @code{export}
766 form; @pxref{Using modules}.
767 @c JP
768 @code{export}宣言はGaucheの@code{export}フォームと同じです。
769 @ref{Using modules}参照。
770 @c COMMON
771
772 @c EN
773 The @code{import} declaration is R7RS's @code{import} form,
774 described in @ref{Three forms of import}.
775 @c JP
776 @code{import}宣言はR7RSの@code{import}フォームで、
777 @ref{Three forms of import}で説明しています。
778 @c COMMON
779
780 @c EN
781 The @code{include} and @code{include-ci} declarations
782 are the same as Gauche's; @pxref{Inclusions}.
783 Note that Gauche allows any code to be included---the content of
784 the named file is simply wrapped with @code{begin} and
785 substituted with these forms---but in R7RS definition,
786 what you include must contain only Scheme code
787 (not one of the library declarations or @code{define-library} form).
788 @c JP
789 @code{include}と@code{include-ci}フォームはGaucheのそれと同じです。
790 @ref{Inclusions}参照。Gaucheはインクルードされるコードの中身については
791 感知せず、単にその中身を@code{begin}で囲んで元のフォームと
792 置き換えるだけです。けれどもR7RSでは、これらのフォームが読み込むファイルには
793 Schemeコードのみが許されます(例えば@code{define-library}フォームや
794 他のライブラリ宣言フォームはだめです)。
795 @c COMMON
796
797 @c EN
798 The @code{include-library-declarations} declaration works like @code{include},
799 but the content of the read file is interpreted
800 as library declarations instead of Scheme code.
801 @c JP
802 @code{include-library-declarations}宣言は@code{include}宣言と
803 同じように動作しますが、読み込まれるファイルの中身はSchemeコードではなく
804 ライブラリ宣言として解釈されます。
805 @c COMMON
806
807 @c EN
808 The @code{cond-expand} declaration is also the same as Gauche's;
809 @pxref{Feature conditional}. When used directly below
810 @code{define-library}, it must expands to one of the
811 library declarations.
812 @c JP
813 @code{cond-expand}宣言もGaucheのそれと同じです。
814 @ref{Feature conditional}参照。
815 但し、@code{define-library}の直下で使われた場合は、
816 展開結果もライブラリ宣言になっている必要があります。
817 @c COMMON
818 @end defmac
819
820
821 @node R7RS base library, R7RS case-lambda, R7RS library form, R7RS small language
822 @subsection @code{scheme.base} - R7RS base library
823 @c NODE R7RS基本ライブラリ, @code{scheme.base} - R7RS基本ライブラリ
824
825 @deftp {Module} scheme.base
826 @mdindex scheme.base
827 @c EN
828 Exports bindings of R7RS @code{(scheme base)} library. From R7RS programs,
829 those bindings are available by @code{(import (scheme base))}.
830 @c JP
831 R7RSの@code{(scheme base)}ライブラリの束縛をエクスポートします。
832 R7RSプログラムからは、エクスポートされた束縛は@code{(import (scheme base))}とすることで
833 使えます。
834 @c COMMON
835 @end deftp
836
837 @c EN
838 @subheading Bindings common to Gauche's built-ins
839 @c JP
840 @subheading Gaucheの組み込み束縛と共通なもの
841 @c COMMON
842
843 @c EN
844 The following syntaxes and procedures are the same as Gauche's
845 builtins:
846 @c JP
847 以下の構文の手続きはGaucheの組み込みのものと同じです。
848 @c COMMON
849
850 @table @asis
851 @item Primitive expression types
852 @example
853 quote if include include-ci
854 @end example
855 @item Derived expression types
856 @example
857 cond case and or when unless cond-expand let let* letrec letrec*
858 let-values let*-values begin do make-parameter parameterize
859 guard quasiquote unquote unquote-splicing case-lambda
860 @end example
861 @item Macros
862 @example
863 let-syntax letrec-syntax syntax-rules syntax-error define-syntax
864 @end example
865 @item Variable definitions
866 @example
867 define-values
868 @end example
869 @item Record type definitions
870 @example
871 define-record-type
872 @end example
873 @item Equivalence predicates
874 @example
875 eqv? eq? equal?
876 @end example
877 @item Numbers
878 @example
879 number? complex? real? rational? integer? exact? exact-integer?
880 = < > <= >= zero? positive? negative? odd? even? max min + * - / abs
881 floor/ floor-quotient floor-remainder
882 truncate/ truncate-quotient truncate-remainder
883 quotient modulo remainder gcd lcm numerator denominator
884 floor ceiling truncate round rationalize square exact-integer-sqrt
885 expt inexact exact number->string string->number
886 @end example
887 @item Booleans
888 @example
889 not boolean? boolean=?
890 @end example
891 @item Pairs and lists
892 @example
893 pair? cons car cdr set-car! set-cdr! caar cadr cdar cddr null? list?
894 make-list list length append reverse list-tail list-ref list-set!
895 memq memv member assq assv assoc list-copy
896 @end example
897 @item Symbols
898 @example
899 symbol? symbol=? symbol->string string->symbol
900 @end example
901 @item Characters
902 @example
903 char? char=? char<? char>? char<=? char>=? char->integer integer->char
904 @end example
905 @item Strings
906 @example
907 string? make-string string string-length string-ref string-set!
908 string=? string<? string>? string<=? string>=? substring string-append
909 string->list list->string string-copy string-copy! string-fill!
910 string-map string-for-each
911 @end example
912 @item Vectors
913 @example
914 vector? make-vector vector vector-length vector-ref vector-set!
915 vector->list list->vector vector->string string->vector
916 vector-copy vector-copy! vector-append vector-fill!
917 @end example
918 @item Control features
919 @example
920 procedure? apply map call-with-current-continuation call/cc
921 values call-with-values dynamic-wind
922 @end example
923 @item Exception
924 @example
925 error
926 @end example
927 @item Environments and evaluation
928 @example
929 scheme-report-environment null-environment
930 @end example
931 @item Input and output
932 @example
933 input-port? output-port? port? current-input-port current-output-port
934 current-error-port close-port close-input-port close-output-port
935 open-input-string open-output-string get-output-string
936 read-char peek-char read-u8 peek-u8
937 read-line eof-object? eof-object char-ready? u8-ready?
938 newline write-char write-u8
939 @end example
940 @end table
941
942 @c EN
943 The following two identifiers are the ones bound in the @code{scheme}
944 module, which differ from the ones bound in the @code{gauche} module.
945 Notably, these don't recognize Gauche's extended lambda arguments
946 (@code{:key}, @code{:optional}, etc.).
947 @c JP
948 次の2つの識別子は、@code{scheme}モジュールにあるものがエクスポートされます。
949 これらは@code{gauche}モジュールの束縛とは異なることに注意してください。
950 Gaucheの拡張引数(@code{:key}、@code{:optional}等)は認識されません。
951 @c COMMON
952
953 @example
954 define lambda
955 @end example
956
957 @c EN
958 @subheading Bytevector utilities
959 @c JP
960 @subheading バイトベクタユーティリティ
961 @c COMMON
962
963 @c EN
964 R7RS's bytevectors are the same as Gauche's u8vectors.
965
966 The following procedures are the same as @code{gauche.uvector}'s
967 (@pxref{Bytevector compatibility}).
968 @c JP
969 R7RSのバイトベクタはGaucheのu8vectorと同じです。
970
971 以下の手続きは@code{gauche.uvector}のものと同じです。
972 (@ref{Bytevector compatibility}参照)。
973 @c COMMON
974
975 @example
976 bytevector bytevector? make-bytevector
977 bytevector-length bytevector-u8-ref bytevector-u8-set!
978 bytevector-copy bytevector-copy! bytevector-append
979 read-bytevector read-bytevector! write-bytevector
980 @end example
981
982 @c EN
983 The following procedures are the same as @code{gauche.vport}'s
984 (@pxref{Virtual ports}).
985 @c JP
986 以下の手続きは@code{gauche.vport}のものと同じです。
987 (@ref{Virtual ports}参照)。
988 @c COMMON
989
990 @example
991 open-input-bytevector open-output-bytevector get-output-bytevector
992 @end example
993
994 @c EN
995 And the following procedures are the same as @code{gauche.unicode}'s
996 (@pxref{Unicode transfer encodings}).
997 @c JP
998 そして以下の手続きは@code{gauche.unicode}のものと同じです。
999 (@ref{Unicode transfer encodings}参照)。
1000 @c COMMON
1001
1002 @example
1003 utf8->string string->utf8
1004 @end example
1005
1006 @c EN
1007 @subheading Control features
1008 @c JP
1009 @subheading 制御機能
1010 @c COMMON
1011
1012 @c EN
1013 The procedure @code{with-exception-handler} is the same as Gauche's built-in.
1014 @xref{Low-level exception handling mechanism}, for the explanation.
1015 @c JP
1016 手続き@code{with-exception-handler}はGauche組み込みのものと同じです。
1017 @ref{Low-level exception handling mechanism}で説明してあります。
1018 @c COMMON
1019
1020 @defun raise obj
1021 @defunx raise-continuable obj
1022 [R7RS base]
1023 @c MOD scheme.base
1024 @c EN
1025 Gauche's @code{raise} may return if @var{obj} isn't a
1026 @code{<serious-condition>}.
1027 Distinguishing continuable and noncontinuable exception throw by the
1028 procedure has an issue when your exception handler wants to reraise
1029 the condition (you don't know if the original condition is raised
1030 by @code{raise} or @code{raise-continuable}!). Yet R7RS adopted
1031 that model, so we compel.
1032
1033 R7RS @code{raise} is a wrapper of Gauche's @code{raise},
1034 which throws an error if Gauche's @code{raise} returns.
1035
1036 R7RS @code{raise-continuable} is currently just an alias of
1037 Gauche's @code{raise}---as long as you don't pass
1038 @code{<serious-condition>}, it may return. It is not exactly
1039 R7RS conformant---it won't return if you pass @code{<serious-condition>}
1040 or object of one of its subclasses (e.g. @code{<error>}), but
1041 it's weired to expect returning from raising @code{<error>}, isn't it?
1042 @c JP
1043 Gaucheの@code{raise}は、@var{obj}が@code{<serious-condition>}でなければ、
1044 例外ハンドラから戻って来ることを許しています。
1045 継続可能な例外報告と継続不可能な例外報告を手続きで区別するのは、
1046 例外ハンドラが渡されたコンディションを再び投げる場合に問題となります
1047 (元のコンディションが@code{raise}で投げられたのか@code{raise-continuable}で
1048 投げられたのか知る術がない!)。
1049 しかしR7RSではそのモデルを採用したため、何とか合わせようとしています。
1050
1051 R7RS版の@code{raise}はGaucheの@code{raise}のラッパーで、
1052 Gaucheの@code{raise}から戻って来たらエラーを投げるようにしています。
1053
1054 R7RSの@code{raise-continuable}は今のところGaucheの@code{raise}の
1055 別名になっています。@code{<serious-condition>}を渡さなければ、
1056 戻ってくることが可能です。R7RS準拠でないのは、
1057 @code{<serious-condition>}かそのサブクラスのオブジェクト(例えば@code{<error>})を
1058 @code{raise-continuable}に渡した場合ですが、
1059 @code{<error>}を投げて戻って来ることを期待するというのはちょっとおかしいですよね。
1060 @c COMMON
1061 @end defun
1062
1063 @defun error-object? exc
1064 [R7RS base]
1065 @c MOD scheme.base
1066 @c EN
1067 Defined as @code{(condition-has-type? exc <error>))}
1068 @c JP
1069 @code{(condition-has-type? exc <error>))}として定義されています。
1070 @c COMMON
1071 @end defun
1072
1073 @defun error-object-message exc
1074 [R7RS base]
1075 @c MOD scheme.base
1076 @c EN
1077 If @var{exc} is a @code{<message-condition>},
1078 returns its @code{message-prefix} slot;
1079 otherwise, returns an empty string.
1080 @c JP
1081 @var{exc}が@code{<message-condition>}であれば
1082 @code{message-prefix}の内容を、持っていなければ空文字列を返します。
1083 @c COMMON
1084 @end defun
1085
1086 @defun error-object-irritants exc
1087 [R7RS base]
1088 @c MOD scheme.base
1089 @c EN
1090 If @var{exc} is a @code{<message-condition>},
1091 returns its @code{message-args} slot;
1092 otherwise, returns an empty string.
1093 @c JP
1094 @var{exc}が@code{<message-condition>}であれば
1095 @code{message-args}の内容を、持っていなければ空文字列を返します。
1096 @c COMMON
1097 @end defun
1098
1099 @defun read-error? exc
1100 [R7RS base]
1101 @c MOD scheme.base
1102 @c EN
1103 Defined as @code{(condition-has-type? e <read-error>))}.
1104 @c JP
1105 @code{(condition-has-type? e <read-error>))}として定義されています。
1106 @c COMMON
1107 @end defun
1108
1109 @defun file-error? exc
1110 [R7RS base]
1111 @c MOD scheme.base
1112 @c EN
1113 At this moment, Gauche doesn't have distinct @code{<file-error>} condition,
1114 but most file errors are thrown as one of @code{<system-error>}s.
1115 This procedure checks error code of @code{<system-error>} and
1116 returns @code{#t} if the error is likely to be related to the filesystem.
1117 @c JP
1118 今のところ、Gaucheは独立した@code{<file-error>}コンディションを持っていませんが、
1119 ファイルエラーのほとんどは@code{<system-error>}として投げられます。
1120 この手続きは@code{<system-error>}のエラーコードを調べ、ファイルに起因するエラー
1121 の場合に@code{#t}を返すようにしています。
1122 @c COMMON
1123 @end defun
1124
1125 @c EN
1126 @subheading Input and output
1127 @c JP
1128 @subheading 入出力
1129 @c COMMON
1130
1131 @defun textual-port? port
1132 @defunx binary-port? port
1133 [R7RS base]
1134 @c MOD scheme.base
1135 @c EN
1136 Gauche's port can handle both, so these are equivalent to @code{port?}.
1137 @c JP
1138 Gaucheのポートはどちらも扱えるので、これらの手続きは@code{port?}と等価です。
1139 @c COMMON
1140 @end defun
1141
1142 @defun input-port-open? iport
1143 @defunx output-port-open? oport
1144 [R7RS base]
1145 @c MOD scheme.base
1146 @c EN
1147 Checks whether @var{iport}/@var{oport} is an input/output port @emph{and}
1148 it is not closed.
1149 @c JP
1150 @var{iport}/@var{oport}がそれぞれ入力/出力ポートであり、かつクローズされていなければ
1151 @code{#t}を返します。
1152 @c COMMON
1153 @end defun
1154
1155
1156 @defun flush-output-port :optional oport
1157 [R7RS base]
1158 @c MOD scheme.base
1159 @c EN
1160 An alias to @code{flush} (@pxref{Low-level output}).
1161 @c JP
1162 @code{flush}の別名です (@ref{Low-level output}参照)。
1163 @c COMMON
1164 @end defun
1165
1166 @defun features
1167 [R7RS base]
1168 @c MOD scheme.base
1169 @c EN
1170 Returns a list of symbols of supported feature identifiers,
1171 recognized by @code{cond-expand} (@pxref{Feature conditional}).
1172 @c JP
1173 サポートされている@code{feature-identifier}のリストを返します。
1174 @code{feature-identifier}については、@code{cond-expand}を参照してください
1175 (@ref{Feature conditional}参照)。
1176 @c COMMON
1177 @end defun
1178
1179
1180 @node R7RS case-lambda, R7RS char library, R7RS base library, R7RS small language
1181 @subsection @code{scheme.case-lambda} - R7RS case-lambda
1182 @c NODE R7RS case-lambda, @code{scheme.case-lambda} - R7RS case-lambda
1183
1184 @deftp {Module} scheme.case-lambda
1185 @mdindex scheme.case-lambda
1186 @c EN
1187 Exports bindings of R7RS @code{(scheme case-lambda)} library.
1188 From R7RS programs,
1189 those bindings are available by @code{(import (scheme case-lambda))}.
1190
1191 The only binding exported from this module is @code{case-lambda},
1192 and it is the same as Gauche's built-in @code{case-lambda};
1193 @pxref{Making procedures} for the details.
1194 @c JP
1195 R7RSの@code{(scheme case-lambda)}ライブラリの束縛をエクスポートします。
1196 R7RSプログラムからは、エクスポートされた束縛は
1197 @code{(import (scheme case-lambda))}とすることで使えます。
1198
1199 このモジュールからエクスポートされるのは@code{case-lambda}だけで、
1200 Gauche組み込みの@code{case-lambda}そのものです。
1201 詳しくは@ref{Making procedures}を参照してください。
1202 @c COMMON
1203 @end deftp
1204
1205
1206 @node R7RS char library, R7RS complex numbers, R7RS case-lambda, R7RS small language
1207 @subsection @code{scheme.char} - R7RS char library
1208 @c NODE R7RS文字ライブラリ, @code{scheme.char} - R7RS文字ライブラリ
1209
1210 @deftp {Module} scheme.char
1211 @mdindex scheme.char
1212 @c EN
1213 Exports bindings of R7RS @code{(scheme char)} library.
1214 From R7RS programs,
1215 those bindings are available by @code{(import (scheme char))}.
1216 @c JP
1217 R7RSの@code{(scheme char)}ライブラリの束縛をエクスポートします。
1218 R7RSプログラムからは、エクスポートされた束縛は
1219 @code{(import (scheme char))}とすることで使えます。
1220 @c COMMON
1221 @end deftp
1222
1223 @c EN
1224 The following procedures are the same as Gauche's builtin procedures;
1225 @pxref{Characters}.
1226 @c JP
1227 以下の手続きはGaucheの組み込みのものと同じです。@ref{Characters}参照。
1228 @c COMMON
1229
1230 @example
1231 char-alphabetic? char-ci<=? char-ci<? char-ci=? char-ci>=? char-ci>?
1232 char-downcase char-foldcase char-lower-case? char-numeric?
1233 char-upcase char-upper-case? char-whitespace?
1234 @end example
1235
1236 @c EN
1237 The following procedures are the same as the ones provided
1238 in @code{gauche.unicode} module (@pxref{Full string case conversion}).
1239 They use full case folding by Unicode standard (e.g. taking into
1240 account of German eszett).
1241 @c JP
1242 以下の手続きは@code{gauche.unicode}で提供されているものと同じです
1243 (@ref{Full string case conversion}参照)。Unicodeで定義されている
1244 フルセットの大文字小文字変換を使います(例えばドイツ語のエスツェットが考慮されます)。
1245 @c COMMON
1246
1247 @example
1248 string-ci<=? string-ci<? string-ci=? string-ci>=? string-ci>?
1249 string-downcase string-foldcase string-upcase
1250 @end example
1251
1252 @defun digit-value c
1253 [R7RS char]
1254 @c MOD scheme.char
1255 @c EN
1256 If @var{c} is a character with @code{Nd} general category---that is,
1257 if it represents a decimal digit---this procedure returns the value
1258 the character represents. Otherwise it returns @code{#f}.
1259 @c JP
1260 @var{c}が@code{Nd}カテゴリの文字、つまり十進数の数字を表す文字であれば、
1261 その文字が表す値を返します。それ以外の場合は@code{#f}を返します。
1262 @c COMMON
1263
1264 @example
1265 (digit-value #\3) @result{} 3
1266
1267 (digit-value #\z) @result{} #f
1268 @end example
1269
1270 @c EN
1271 Note that Unicode defines about two dozen sets of digit characters.
1272 @c JP
1273 Unicodeには20種類以上の数字が定義されています。
1274 @c COMMON
1275
1276 @example
1277 (digit-value #\x11068) @result{} 2
1278 @end example
1279
1280 @c EN
1281 Gauche's built-in procedure @code{digit->integer} has more general
1282 interface (@pxref{Characters}).
1283 @c JP
1284 Gauche組み込みの@code{digit->integer}はより汎用的なインタフェースを
1285 持っています(@ref{Characters}参照)。
1286 @c COMMON
1287
1288 @example
1289 (digit-value c) @equiv{} (digit->integer c 10 #t)
1290 @end example
1291 @end defun
1292
1293 @node R7RS complex numbers, R7RS cxr accessors, R7RS char library, R7RS small language
1294 @subsection @code{scheme.complex} - R7RS complex numbers
1295 @c NODE R7RS複素数, @code{scheme.complex} - R7RS複素数
1296
1297 @deftp {Module} scheme.complex
1298 @mdindex scheme.complex
1299 @c EN
1300 Exports bindings of R7RS @code{(scheme complex)} library.
1301 From R7RS programs,
1302 those bindings are available by @code{(import (scheme complex))}.
1303 @c JP
1304 R7RSの@code{(scheme complex)}ライブラリの束縛をエクスポートします。
1305 R7RSプログラムからは、エクスポートされた束縛は
1306 @code{(import (scheme complex))}とすることで使えます。
1307 @c COMMON
1308
1309 @c EN
1310 This module provides the following bindings, all of which are
1311 Gauche built-in (@pxref{Numerical conversions}).
1312 @c JP
1313 このモジュールは以下の束縛を提供します。
1314 全てGaucheの組み込みです(@ref{Numerical conversions}参照)。
1315 @c COMMON
1316
1317 @example
1318 angle imag-part magnitude make-polar make-rectangular real-part
1319 @end example
1320 @end deftp
1321
1322
1323 @node R7RS cxr accessors, R7RS eval, R7RS complex numbers, R7RS small language
1324 @subsection @code{scheme.cxr} - R7RS cxr accessors
1325 @c NODE R7RS cxrアクセサ, @code{scheme.cxr} - R7RS cxrアクセサ
1326
1327 @deftp {Module} scheme.cxr
1328 @mdindex scheme.cxr
1329 @c EN
1330 Exports bindings of R7RS @code{(scheme cxr)} library.
1331 From R7RS programs,
1332 those bindings are available by @code{(import (scheme cxr))}.
1333 @c JP
1334 R7RSの@code{(scheme complex)}ライブラリの束縛をエクスポートします。
1335 R7RSプログラムからは、エクスポートされた束縛は
1336 @code{(import (scheme complex))}とすることで使えます。
1337 @c COMMON
1338
1339 @c EN
1340 This module provides the following bindings, all of which are
1341 Gauche built-in (@pxref{List accessors and modifiers}).
1342 @c JP
1343 このモジュールは以下の束縛を提供します。
1344 全てGaucheの組み込みです(@ref{List accessors and modifiers}参照)。
1345 @c COMMON
1346
1347 @example
1348 caaar caadr cadar caddr cdaar cdadr cddar cdddr caaaar caaadr caadar
1349 caaddr cadaar cadadr caddar cadddr cdaaar cdaadr cdadar cdaddr cddaar
1350 cddadr cdddar cddddr
1351 @end example
1352 @end deftp
1353
1354 @node R7RS eval, R7RS file library, R7RS cxr accessors, R7RS small language
1355 @subsection @code{scheme.eval} - R7RS eval
1356 @c NODE R7RS eval, @code{scheme.eval} - R7RS eval
1357
1358 @deftp {Module} scheme.eval
1359 @mdindex scheme.eval
1360 @c EN
1361 Exports bindings of R7RS @code{(scheme eval)} library.
1362 From R7RS programs,
1363 those bindings are available by @code{(import (scheme eval))}.
1364 @c JP
1365 R7RSの@code{(scheme eval)}ライブラリの束縛をエクスポートします。
1366 R7RSプログラムからは、エクスポートされた束縛は
1367 @code{(import (scheme eval))}とすることで使えます。
1368 @c COMMON
1369
1370 @c EN
1371 This module exports @code{eval}, which is the same as Gauche's built-in
1372 (@pxref{Eval and repl}).
1373 @c JP
1374 このモジュールは@code{eval}をエクスポートします。これはGauche組み込みのevalと
1375 同じです(@ref{Eval and repl}参照)。
1376 @c COMMON
1377 @end deftp
1378
1379 @defun environment import-list @dots{}
1380 [R7RS eval]
1381 @c MOD scheme.eval
1382 @c EN
1383 This is R7RS way to create an environment specifier suitable to pass
1384 to @code{eval}. In Gauche, an environment specifier is just a
1385 module object.
1386 @c JP
1387 これはR7RSで@code{eval}に渡せる環境指定子を作る手段です。Gaucheでは、
1388 環境指定子は単なるモジュールオブジェクトです。
1389 @c COMMON
1390
1391 @c EN
1392 The argument is the same as what @code{r7rs#import} takes.
1393 This procedure creates an empty environment (as a fresh anonymous module;
1394 see @code{make-module} in @ref{Module introspection}, for the details),
1395 then imports the bindings as specified by @var{import-list}s.
1396
1397 The following example creates an environment that includes
1398 @code{scheme.base} bindings plus @code{select-module} syntax from Gauche.
1399 @c JP
1400 引数は@code{r7rs#import}が取るものと同じです。
1401 この手続きはまず空の環境(=無名のモジュールです。
1402 詳しくは@ref{Module introspection}の@code{make-module}参照)を作り、
1403 それから@var{import-list}に指定される束縛をインポートします。
1404
1405 以下の例は、@code{scheme.base}及びGauche組み込みの@code{select-module}を
1406 インポートした環境を作ります。
1407 @c COMMON
1408
1409 @example
1410 (environment
1411 '(scheme base)
1412 '(only (gauche base) select-module))
1413 @result{} #<module #f> ; an anonymous module
1414 @end example
1415 @end defun
1416
1417
1418 @node R7RS file library, R7RS inexact numbers, R7RS eval, R7RS small language
1419 @subsection @code{scheme.file} - R7RS file library
1420 @c NODE R7RSファイルライブラリ, @code{scheme.file} - R7RSファイルライブラリ
1421
1422 @deftp {Module} scheme.file
1423 @mdindex scheme.file
1424 @c EN
1425 Exports bindings of R7RS @code{(scheme file)} library.
1426 From R7RS programs,
1427 those bindings are available by @code{(import (scheme file))}.
1428 @c JP
1429 R7RSの@code{(scheme file)}ライブラリの束縛をエクスポートします。
1430 R7RSプログラムからは、エクスポートされた束縛は
1431 @code{(import (scheme file))}とすることで使えます。
1432 @c COMMON
1433 @end deftp
1434
1435 @c EN
1436 The following bindings provided in this module are
1437 Gauche built-in (@pxref{File ports}, and @ref{File stats}).
1438 @c JP
1439 次に挙げる束縛はGaucheの組み込みと同じです
1440 (@ref{File ports}及び@ref{File stats}参照)。
1441 @c COMMON
1442
1443 @example
1444 call-with-input-file call-with-output-file
1445 file-exists?
1446 open-input-file open-output-file
1447 with-input-from-file with-output-to-file
1448 @end example
1449
1450 @c EN
1451 The following binding is the same as one in @code{file.util}
1452 (@pxref{File operations}).
1453 @c JP
1454 以下の束縛は@code{file.util}で提供されるものと同じです
1455 (@ref{File operations}参照)。
1456 @c COMMON
1457
1458 @example
1459 delete-file
1460 @end example
1461
1462 @defun open-binary-input-file filename
1463 @defunx open-binary-output-file filename
1464 [R7RS file]
1465 @c MOD scheme.file
1466 @c EN
1467 In Gauche, ports are both textual and binary at the same time,
1468 so these R7RS procedures
1469 are just aliases of @code{open-input-file} and @code{open-output-file},
1470 respectively. @xref{File ports}.
1471 @c JP
1472 Gaucheでは、ポートは同時にテキストポートでもバイナリポートでもあるので、
1473 これらのR7RS手続きは単に
1474 @code{open-input-file}と@code{open-output-file}の別名になっています。
1475 @ref{File ports}参照。
1476 @c COMMON
1477 @end defun
1478
1479 @node R7RS inexact numbers, R7RS lazy evaluation, R7RS file library, R7RS small language
1480 @subsection @code{scheme.inexact} - R7RS inexact numbers
1481 @c NODE R7RS非正確数, @code{scheme.inexact} - R7RS非正確数
1482
1483 @deftp {Module} scheme.inexact
1484 @mdindex scheme.inexact
1485 @c EN
1486 Exports bindings of R7RS @code{(scheme inexact)} library.
1487 From R7RS programs,
1488 those bindings are available by @code{(import (scheme inexact))}.
1489 @c JP
1490 R7RSの@code{(scheme inexact)}ライブラリの束縛をエクスポートします。
1491 R7RSプログラムからは、エクスポートされた束縛は
1492 @code{(import (scheme inexact))}とすることで使えます。
1493 @c COMMON
1494
1495 @c EN
1496 This module provides the following bindings, all of which are
1497 Gauche built-in (@pxref{Arithmetics}, and @ref{Numerical predicates}).
1498 @c JP
1499 このモジュールは以下の束縛を提供します。全てGaucheの組み込みです
1500 (@ref{Arithmetics}及び@ref{Numerical predicates}参照)。
1501 @c COMMON
1502
1503 @example
1504 acos asin atan cos exp finite? infinite? log nan? sin sqrt tan
1505 @end example
1506 @end deftp
1507
1508 @node R7RS lazy evaluation, R7RS load, R7RS inexact numbers, R7RS small language
1509 @subsection @code{scheme.lazy} - R7RS lazy evaluation
1510 @c NODE R7RS遅延評価, @code{scheme.lazy} - R7RS遅延評価
1511
1512 @deftp {Module} scheme.lazy
1513 @mdindex scheme.lazy
1514 @c EN
1515 Exports bindings of R7RS @code{(scheme lazy)} library.
1516 From R7RS programs,
1517 those bindings are available by @code{(import (scheme lazy))}.
1518 @c JP
1519 R7RSの@code{(scheme inexact)}ライブラリの束縛をエクスポートします。
1520 R7RSプログラムからは、エクスポートされた束縛は
1521 @code{(import (scheme inexact))}とすることで使えます。
1522 @c COMMON
1523 @end deftp
1524
1525 @c EN
1526 The following bindings this module provides are Gauche built-ins
1527 (@pxref{Delay force and lazy}).
1528 @c JP
1529 以下の束縛は、Gauche組み込みです
1530 (@ref{Delay force and lazy}参照)。
1531 @c COMMON
1532
1533 @example
1534 delay force promise?
1535 @end example
1536
1537 @defspec delay-force promise
1538 [R7RS lazy]
1539 @c MOD scheme.lazy
1540 @c EN
1541 This is the same as Gauche's built-in @code{lazy}.
1542 @pxref{Delay force and lazy} for the discussion about when this
1543 form should be used.
1544 @c JP
1545 これはGauche組み込みの@code{lazy}と同じです。
1546 使い方については@ref{Delay force and lazy}の議論を参照してください。
1547 @c COMMON
1548 @end defspec
1549
1550 @defun make-promise obj
1551 [R7RS lazy]
1552 @c MOD scheme.lazy
1553 @c EN
1554 If @var{obj} is a promise, it is returned as is. Otherwise,
1555 A promise, which yields @var{obj} when forced, is returned.
1556 Because this is a procedure, expression passed as @var{obj} is
1557 eagerly evaluated, so this doesn't have effect on lazy evaluation,
1558 but can be used to ensure you have a promise.
1559 @c JP
1560 @var{obj}がプロミスならそのまま返されます。そうでなければ、
1561 forceされた時に@var{obj}が返されるようなプロミスが返されます。
1562 これは手続きなので、@var{obj}は@code{make-promise}を呼び出す前に
1563 評価されてしまいます。従って遅延評価には使えませんが、
1564 確実にプロミスを得たい場合に使えます。
1565 @c COMMON
1566
1567 @c EN
1568 This procedure is important on implementations where
1569 @code{force} only takes a promise, and portable code should
1570 use this procedure to yield a value that can be passed to @code{force}.
1571 @c JP
1572 @code{force}がプロミスのみを取るような実装ではこの手続きは重要です。
1573 ポータブルなコードは、@code{force}に渡すものがプロミスであることを
1574 確実にしたい場所でこの手続きを使うようにしてください。
1575 @c COMMON
1576
1577 @c EN
1578 If you write Gauche-specific code, however, @code{force} can take
1579 non-promise values, so you don't need this.
1580 @c JP
1581 Gaucheの@code{force}はプロミスでない値も取れるので、
1582 Gauche専用のコードを書いている時はこの手続きは不要です。
1583 @c COMMON
1584
1585 @c EN
1586 Note: Gauche has built-in @code{make-promise}, which behaves as
1587 defined in SRFI-226 and slightly different from this one
1588 (@pxref{Delay force and lazy}).
1589 @c JP
1590 註: Gaucheの組み込みの@code{make-promise}はSRFI-226で定義された動作で、
1591 この@code{make-promise}とは若干違います。
1592 (@ref{Delay force and lazy}参照)。
1593 @c COMMON
1594 @end defun
1595
1596
1597 @node R7RS load, R7RS process context, R7RS lazy evaluation, R7RS small language
1598 @subsection @code{scheme.load} - R7RS load
1599 @c NODE R7RS load, @code{scheme.load} - R7RS load
1600
1601 @deftp {Module} scheme.load
1602 @mdindex scheme.load
1603 @c EN
1604 Exports bindings of R7RS @code{(scheme load)} library.
1605 From R7RS programs,
1606 those bindings are available by @code{(import (scheme load))}.
1607 @c JP
1608 R7RSの@code{(scheme load)}ライブラリの束縛をエクスポートします。
1609 R7RSプログラムからは、エクスポートされた束縛は
1610 @code{(import (scheme load))}とすることで使えます。
1611 @c COMMON
1612 @end deftp
1613
1614 @defun load file :optional env
1615 [R7RS load]
1616 @c MOD scheme.load
1617 @c EN
1618 R7RS @code{load} takes environment as an optional argument,
1619 while Gauche @code{load} takes it as a keyword argument
1620 (among other keyword arguments). @xref{Loading Scheme file}.
1621
1622 In Gauche, @var{env} is just a module. In portable code,
1623 you can create a module with desired bindings with R7RS @code{environment}
1624 procedure; @pxref{R7RS eval}.
1625 @c JP
1626 R7RSの@code{load}は省略可能引数として環境を取ります。
1627 Gaucheの@code{load}では環境はキーワード引数で受け取られることに注意してください。
1628 @ref{Loading Scheme file}参照。
1629
1630 また、Gaucheでは環境は単にモジュールで良いのですが、
1631 ポータブルなコードではR7RSの@code{environment}手続きを使って
1632 環境を作る必要があります。@ref{R7RS eval}参照。
1633 @c COMMON
1634 @end defun
1635
1636
1637 @node R7RS process context, R7RS read, R7RS load, R7RS small language
1638 @subsection @code{scheme.process-context} - R7RS process context
1639 @c NODE R7RSプロセスコンテキスト, @code{scheme.process-context} - R7RSプロセスコンテキスト
1640
1641 @deftp {Module} scheme.process-context
1642 @mdindex scheme.process-context
1643 @c EN
1644 Exports bindings of R7RS @code{(scheme process-context)} library.
1645 From R7RS programs,
1646 those bindings are available by @code{(import (scheme process-context))}.
1647 @c JP
1648 R7RSの@code{(scheme process-context)}ライブラリの束縛をエクスポートします。
1649 R7RSプログラムからは、エクスポートされた束縛は
1650 @code{(import (scheme process-context))}とすることで使えます。
1651 @c COMMON
1652 @end deftp
1653
1654 @c EN
1655 The following bindings are the same as Gauche built-ins
1656 (@pxref{Command-line arguments}, and @ref{Program termination}):
1657 @c JP
1658 次の束縛はGauche組み込みのものと同じです
1659 (@ref{Command-line arguments}、および@ref{Program termination}参照):
1660 @c COMMON
1661
1662 @example
1663 command-line exit
1664 @end example
1665
1666 @c EN
1667 The following bindings are the same as SRFI-98
1668 (@pxref{Accessing environment variables}):
1669 @c JP
1670 次の束縛はSRFI-98のものと同じです
1671 (@ref{Accessing environment variables}参照):
1672 @c COMMON
1673
1674 @example
1675 get-environment-variable get-environment-variables
1676 @end example
1677
1678 @defun emergency-exit :optional (obj #t)
1679 [R7RS process-context]
1680 @c MOD scheme.process-context
1681 @c EN
1682 Terminate the program without running any clean-up procedures
1683 (@var{after} thunks of @code{dynamic-wind}). I/O buffers won't
1684 be flushed.
1685 Internally, it calls the @code{_exit(2)} system call directly.
1686
1687 The optional argument is used for the process exit code. R7RS
1688 does not specify the meaning of exit code except that @code{#t} indicates
1689 success and @code{#f} indicates failure. Portable code should only
1690 use these values. Gauche maps @code{#t} to exit code 0 and @code{#f}
1691 to exit code 1. For other values, see the entry of @code{exit}
1692 (@pxref{Program termination}).
1693 @c JP
1694 クリーンアップ手続きを飛ばしてプログラムを直ちに終了させます
1695 (@code{dynamic-wind}によって設定された@var{after}サンクは実行されません)。
1696 内部的には、@code{_exit(2)}システムコールを直接呼んでいます。
1697
1698 省略可能引数はプロセスの終了コードを指定します。
1699 R7RSでは具体的な終了コードの値は示されておらず、ただ@code{#t}が「成功」を、
1700 @code{#f}が「失敗」を意味するとされています。Gaucheでは@code{#t}を終了コード0に、
1701 @code{#f}を終了コード1に対応させています。ポータブルなコードでは真偽値のみを渡してください。
1702 これ以外の@var{code}の意味については、@code{exit}のエントリを参照してください。
1703 (@ref{Program termination})。
1704 @c COMMON
1705 @end defun
1706
1707 @node R7RS read, R7RS repl, R7RS process context, R7RS small language
1708 @subsection @code{scheme.read} - R7RS read
1709 @c NODE R7RS read, @code{scheme.read} - R7RS read
1710
1711 @deftp {Module} scheme.read
1712 @mdindex scheme.read
1713 @c EN
1714 Exports bindings of R7RS @code{(scheme read)} library.
1715 From R7RS programs,
1716 those bindings are available by @code{(import (scheme read))}.
1717
1718 The only binding exported from this module is @code{read},
1719 which is the same as Gauche's built-in. @xref{Reading data}.
1720 @c JP
1721 R7RS @code{(scheme read)}ライブラリの束縛をエクスポートします。
1722 R7RSプログラムからは、
1723 @code{(import (scheme read))}とすることでこれらの名前が使えるようになります。
1724
1725 このモジュールからエクスポートされるのは@code{read}のみで、
1726 これはGaucheでは組み込みになっています。@ref{Reading data}参照。
1727 @c COMMON
1728 @end deftp
1729
1730 @node R7RS repl, R7RS time, R7RS read, R7RS small language
1731 @subsection @code{scheme.repl} - R7RS repl
1732 @c NODE R7RS repl, @code{scheme.repl} - R7RS repl
1733
1734 @deftp {Module} scheme.repl
1735 @mdindex scheme.repl
1736 @c EN
1737 Exports bindings of R7RS @code{(scheme repl)} library.
1738 From R7RS programs,
1739 those bindings are available by @code{(import (scheme repl))}.
1740
1741 The only binding exported from this module is @code{interaction-environment},
1742 which is the same as Gauche's built-in. @xref{Eval and repl}.
1743 @c JP
1744 R7RS @code{(scheme repl)}ライブラリの束縛をエクスポートします。
1745 R7RSプログラムからは、
1746 @code{(import (scheme repl))}とすることでこれらの名前が使えるようになります。
1747
1748 このモジュールからエクスポートされるのは@code{interaction-environment}のみで、
1749 これはGaucheでは組み込みになっています。@ref{Eval and repl}参照。
1750 @c COMMON
1751 @end deftp
1752
1753
1754 @node R7RS time, R7RS write, R7RS repl, R7RS small language
1755 @subsection @code{scheme.time} - R7RS time
1756 @c NODE R7RS time, @code{scheme.time} - R7RS time
1757
1758 @deftp {Module} scheme.time
1759 @mdindex scheme.time
1760 @c EN
1761 Exports bindings of R7RS @code{(scheme time)} library.
1762 From R7RS programs,
1763 those bindings are available by @code{(import (scheme time))}.
1764 @c JP
1765 R7RS @code{(scheme time)}ライブラリの束縛をエクスポートします。
1766 R7RSプログラムからは、
1767 @code{(import (scheme time))}とすることでこれらの名前が使えるようになります。
1768 @c COMMON
1769 @end deftp
1770
1771 @defun current-second
1772 [R7RS time]
1773 @c MOD scheme.time
1774 @c EN
1775 Returns a real number represents the number of seconds since
1776 the midnight of Jan. 1, 1970 TAI (which is 23:59:52, Dec 31, 1969 UTC, that
1777 is, -8 seconds before Unix Epoch.) Number of leap seconds were
1778 inserted since then, and as of 2017, UTC is 37 seconds behind TAI. That means
1779 the number returned is 29 seconds larger than the unix time,
1780 which is returned from @code{sys-time} or @code{sys-gettimeofday}.
1781 @c JP
1782 国際原子時(TAI)の1970年1月1日0時から現在までの経過秒数を実数で返します。
1783 (これは、Unix Epochの8秒前、国際標準時(UTC)で1969年12月31日23:59:52に相当します)。
1784 この起点以来、閏秒がしばしば挿入されてきて、2017年現在、UTCはTAIより37秒遅れています。
1785 すなわち、この手続きが返す秒数は、@code{sys-time}や@code{sys-gettimeofday}が
1786 返すUnix timeより29秒大きい値です。
1787 @c COMMON
1788
1789 @c EN
1790 The reason that R7RS adopts TAI is that it is monotonic and suitable
1791 to take difference of two timepoints. The unix time returned by
1792 @code{sys-time} and @code{sys-gettimeofday} are defined in terms of
1793 UTC date and time, so if the interval spans across leap seconds,
1794 it won't reflect the actual number of seconds in the interval.
1795 (The precise definition is given in section 4.15 of
1796 IEEE Std 1003.1, 2013 Edition, a.k.a Single Unix Specification 4.)
1797 @c JP
1798 R7RSがTAIを採用したのは、それが狭義単調増加であり、二つの時刻の差をとるのに
1799 適しているからです。@code{sys-time}や@code{sys-gettimeofday}は
1800 UTCの日付と時間に基づいているので、二つの時刻が閏秒を挟んでいた場合、
1801 差は経過秒数を表しません。
1802 (Unix Timeの正確な定義については、
1803 IEEE Std 1003.1, 2013年版の4.15節、いわゆるSingle Unix Specification 4を参照)。
1804 @c COMMON
1805
1806 @c EN
1807 However, since we don't know yet when the next leap second happen,
1808 the current implementation just uses a fixed amount of offset
1809 from the unix time.
1810 @c JP
1811 ただ、次にいつ閏秒が来るかはわからないので、現在の実装では単純に
1812 Unix Timeから固定オフセットを引いています。
1813 @c COMMON
1814
1815 @c EN
1816 Just be aware the difference, or you'll be surprised if you
1817 pass the return value of @code{current-second} to the UTC time
1818 formatter such as @code{sys-strftime}, or compare it with
1819 the file timestamps which uses the unix time. You can convert
1820 between TAI and UTC using SRFI-19 (@pxref{SRFI-19 Date}).
1821 @c JP
1822 この差異があることは頭の隅に留めておいてください。
1823 でないと、@code{current-second}の戻り値を
1824 @code{sys-strftime}などUTC時刻のフォーマッタに渡したり、
1825 Unix Timeで表されたタイムスタンプと比較した時にびっくりするかもしれません。
1826 TAIとUTCはSRFI-19で変換できます (@ref{SRFI-19 Date})。
1827 @c COMMON
1828 @end defun
1829
1830 @defun current-jiffy
1831 [R7RS time]
1832 @c MOD scheme.time
1833 @c EN
1834 Returns an exact integer measuring a real (wallclock) time elapsed
1835 since some point in the past, which does not change while a
1836 process is running. The time unit is a @code{jiffies-per-second}-th
1837 second.
1838
1839 The absolute value of current jiffies doesn't matter, but
1840 the difference can be used to measure the time interval.
1841 @c JP
1842 過去のどこかの時点を基準とする、実経過時間を正確な整数で返します。
1843 基準時点はプロセスの起動ごとに変わるかもしれません。
1844 1単位は1秒の@code{jiffies-per-second}分の1です。
1845
1846 「現在のjiffy値」の絶対値に意味はありません。差を取って経過時間を測るのに使います。
1847 @c COMMON
1848 @end defun
1849
1850 @defun jiffies-per-second
1851 [R7RS time]
1852 @c MOD scheme.time
1853 @c EN
1854 Returns a constant to tell how many time units used in @code{current-jiffy}
1855 consists of a second. In the current Gauche implementation,
1856 this is 10^9 on 64bit architectures
1857 (that is, nanosecond resolution) and 10^4 on 32bit architectures
1858 (100 microseconds resolution).
1859
1860 The resolution for 32bit architectures
1861 is unfortunately rather coarse, but if we make it finer
1862 the current jiffy value easily becomes bignums, taking time
1863 to allocate and operate, beating the purpose of benchmarking.
1864 With the current choice, we have 53,867 seconds since process start
1865 before we spill into bignum on 32bit architecture.
1866 On 64bit architectures we have enough bits
1867 not to worry about bignums, with nanosecond resolution.
1868
1869 If you want to do more finer benchmarks on 32bit machines,
1870 you need to roll your own with @code{sys-clock-gettime-monotonic} or
1871 @code{sys-gettimeofday}.
1872 @c JP
1873 @code{current-jiffy}が返す時間単位が、1秒あたりいくつあるかを示す定数を返します。
1874 現在のGaucheの実装では、64ビットアークテクチャで10^9 (ナノ秒単位)、
1875 32ビットアーキテクチャで10^4 (100マイクロ秒単位)です。
1876
1877 32ビットアーキテクチャでの分解能がかなり粗いですが、
1878 jiffy値がbignumにオーバーフローするのを防ぐ方を優先しました。
1879 bignumになるとアロケーションが頻繁に起きるのでベンチマークに干渉してしまいます。
1880 現在の数値では、32ビットアーキテクチャだとプロセス開始後53,867杪でbignumになります。
1881 64ビットアーキテクチャではナノ秒単位で測ってもbignumになることを
1882 現実的に心配する必要はありません。
1883
1884 32ビットアーキテクチャでより精度の高いベンチマークを取りたい場合は、
1885 @code{sys-clock-gettime-monotonic}や@code{sys-gettimeofday}を使ってください。
1886 @c COMMON
1887 @end defun
1888
1889
1890 @node R7RS write, R5RS compatibility, R7RS time, R7RS small language
1891 @subsection @code{scheme.write} - R7RS write
1892 @c NODE R7RS write, @code{scheme.write} - R7RS write
1893
1894 @deftp {Module} scheme.write
1895 @mdindex scheme.write
1896 @c EN
1897 Exports bindings of R7RS @code{(scheme write)} library.
1898 From R7RS programs,
1899 those bindings are available by @code{(import (scheme write))}.
1900
1901 This module provides the following bindings, all of which are
1902 Gauche built-in (@pxref{Object output}).
1903 @c JP
1904 R7RS @code{(scheme write)}ライブラリの束縛をエクスポートします。
1905 R7RSプログラムからは、
1906 @code{(import (scheme write))}とすることでこれらの名前が使えるようになります。
1907
1908 このモジュールからは以下の束縛がエクスポートされます。
1909 いずれもGauche組み込みです (@ref{Object output}参照)。
1910 @c COMMON
1911
1912 @example
1913 display write write-shared write-simple
1914 @end example
1915 @end deftp
1916
1917 @node R5RS compatibility, , R7RS write, R7RS small language
1918 @subsection @code{scheme.r5rs} - R5RS compatibility
1919 @c NODE R5RS compatibility, @code{scheme.r5rs} - R5RS互換性
1920
1921 @deftp {Module} scheme.r5rs
1922 @mdindex scheme.r5rs
1923 @c EN
1924 This module is to provide R5RS environment in R7RS programs.
1925 The following bindings are exported. Note that @code{lambda}
1926 is @code{scheme#lambda}, without the support of
1927 extended formals (@code{:optional} etc.)
1928 @xref{Making procedures}, for the details of extended formals.
1929 @c JP
1930 このモジュールは、R7RSプログラム内でR5RS環境を実現します。
1931 次に挙げる束縛がエクスポートされます。
1932 ここでの@code{lambda}は@code{scheme#lambda}で、
1933 Gaucheの拡張機能 (@code{:optional}など) は認識されないことに注意してください。
1934 拡張された引数リストについては@ref{Making procedures}参照。
1935 @c COMMON
1936
1937 @example
1938 * + - / < <= = > >= abs acos and angle append apply asin assoc assq
1939 assv atan begin boolean? caaaar caaadr caaar caadar caaddr caadr
1940 caar cadaar cadadr cadar caddar cadddr caddr cadr
1941 call-with-current-continuation call-with-input-file
1942 call-with-output-file call-with-values car case cdaaar cdaadr cdaar
1943 cdadar cdaddr cdadr cdar cddaar cddadr cddar cdddar cddddr cdddr cddr
1944 cdr ceiling char->integer char-alphabetic? char-ci<=? char-ci<?
1945 char-ci=? char-ci>=? char-ci>? char-downcase char-lower-case?
1946 char-numeric? char-ready? char-upcase char-upper-case? char-whitespace?
1947 char<=? char<? char=? char>=? char>? char? close-input-port
1948 close-output-port complex? cond cons cos current-input-port
1949 current-output-port define define-syntax delay denominator display
1950 do dynamic-wind eof-object? eq? equal? eqv? eval even? exact->inexact
1951 exact? exp expt floor for-each force gcd if imag-part inexact->exact
1952 inexact? input-port? integer->char integer? interaction-environment
1953 lambda lcm length let let* let-syntax letrec letrec-syntax list
1954 list->string list->vector list-ref list-tail list? load log magnitude
1955 make-polar make-rectangular make-string make-vector map max member
1956 memq memv min modulo negative? newline not null-environment null?
1957 number->string number? numerator odd? open-input-file open-output-file
1958 or output-port? pair? peek-char positive? procedure? quasiquote quote
1959 quotient rational? rationalize read read-char real-part real? remainder
1960 reverse round scheme-report-environment set! set-car! set-cdr! sin
1961 sqrt string string->list string->number string->symbol string-append
1962 string-ci<=? string-ci<? string-ci=? string-ci>=? string-ci>?
1963 string-copy string-fill! string-length string-ref string-set!
1964 string<=? string<? string=? string>=? string>? string? substring
1965 symbol->string symbol? tan truncate values vector vector->list
1966 vector-fill! vector-length vector-ref vector-set! vector?
1967 with-input-from-file with-output-to-file write write-char zero?
1968 @end example
1969 @end deftp
1970
1971 @node R7RS large, , R7RS small language, Library modules - R7RS standard libraries
1972 @section R7RS large
1973 @c NODE R7RS large
1974
1975 @c EN
1976 R7RS large is still under development, and we're gradually
1977 adding support of the libraries that has been passed.
1978 @c JP
1979 R7RS largeはまだ策定途上ですが、既に決定したライブラリについては
1980 徐々にGaucheに追加してゆきます。
1981 @c COMMON
1982
1983 @c EN
1984 Currently R7RS-large has two editions (Red and Tangerine),
1985 and Gauche supports them.
1986 @c JP
1987 現在、R7RS-largeには2つのエディション (RedとTangerine) が
1988 制定されており、Gaucheでもこれらをサポートしています。
1989 @c COMMON
1990
1991 @menu
1992 * R7RS lists:: @code{scheme.list}
1993 * R7RS vectors:: @code{scheme.vector}
1994 * R7RS uniform vectors:: @code{scheme.vector.@@}
1995 * R7RS sort:: @code{scheme.sort}
1996 * R7RS sets:: @code{scheme.set}
1997 * R7RS character sets:: @code{scheme.charset}
1998 * R7RS hash tables:: @code{scheme.hash-table}
1999 * R7RS immutable lists:: @code{scheme.ilist}
2000 * R7RS random-access lists:: @code{scheme.rlist}
2001 * R7RS immutable deques:: @code{scheme.ideque}
2002 * R7RS immutable texts:: @code{scheme.text}
2003 * R7RS generators:: @code{scheme.generator}
2004 * R7RS lazy sequences:: @code{scheme.lseq}
2005 * R7RS stream:: @code{scheme.stream}
2006 * R7RS boxes:: @code{scheme.box}
2007 * R7RS list queues:: @code{scheme.list-queue}
2008 * R7RS ephemerons:: @code{scheme.ephemeron}
2009 * R7RS comparators:: @code{scheme.comparator}
2010 * R7RS regular expressions:: @code{scheme.regex}
2011 * R7RS mappings:: @code{scheme.mapping}
2012 * R7RS integer division:: @code{scheme.division}
2013 * R7RS bitwise operations:: @code{scheme.bitwise}
2014 * R7RS fixnum:: @code{scheme.fixnum}
2015 * R7RS flonum:: @code{scheme.flonum}
2016 * R7RS bytevectors:: @code{scheme.bytevector}
2017 * R7RS combinator formatting:: @code{scheme.show}
2018 @end menu
2019
2020 @node R7RS lists, R7RS vectors, R7RS large, R7RS large
2021 @subsection @code{scheme.list} - R7RS lists
2022 @c NODE R7RSリスト, @code{scheme.list} - R7RSリスト
2023
2024 @deftp {Module} scheme.list
2025 @mdindex scheme.list
2026 @c EN
2027 This module is a rich collection of list manipulation procedures,
2028 and same as @code{srfi.1}.
2029
2030 Note that Gauche supports quite a few @code{scheme.list}
2031 procedures as built-in.
2032 The following procedures can be used
2033 without loading @code{scheme.list} module. For the manual entries of
2034 these procedures, @ref{Pairs and lists}.
2035 @c JP
2036 このモジュールは、豊富なリスト操作手続きのコレクションです (@code{srfi.1}と同じです)。
2037
2038 Gaucheは@code{scheme.list}の手続きの多くを組み込みで提供しています。
2039 以下に挙げる手続きは@code{scheme.list}モジュールをロードしなくても使えます。
2040 これらの手続きの説明は、@ref{Pairs and lists}を参照してください。
2041 @c COMMON
2042
2043 @example
2044 null-list? cons* last member
2045 take drop take-right drop-right take! drop-right!
2046 delete delete! delete-duplicates delete-duplicates!
2047 assoc alist-copy alist-delete alist-delete!
2048 any every filter filter! fold fold-right find find-tail
2049 split-at split-at! iota
2050 @end example
2051 @end deftp
2052
2053 @subsubheading List constructors
2054
2055 @defun xcons cd ca
2056 [R7RS list]
2057 @c MOD scheme.list
2058 @c EN
2059 Equivalent to @code{(cons ca cd)}. Useful to pass to
2060 higher-order procedures.
2061 @c JP
2062 @code{(cons ca cd)} と同等です。高階手続きへ渡すのに便利です。
2063 @c COMMON
2064 @end defun
2065
2066 @defun list-tabulate n init-proc
2067 [R7RS list]
2068 @c MOD scheme.list
2069 @c EN
2070 Constructs an @var{n}-element list, in which
2071 each element is generated by @code{(@var{init-proc} @i{i})}.
2072 @c JP
2073 @var{n}個の要素をもつリストを構築し、それぞれの要素を
2074 @code{(@var{init-proc} @i{i})} で生成します。
2075 @c COMMON
2076 @example
2077 (list-tabulate 4 values) @result{} (0 1 2 3)
2078 @end example
2079 @end defun
2080
2081 @defun circular-list elt1 elt2 @dots{}
2082 [R7RS list]
2083 @c MOD scheme.list
2084 @c EN
2085 Constructs a circular list of the elements.
2086 @c JP
2087 指定した要素をもつ循環リストを構築します。
2088 @c COMMON
2089 @example
2090 (circular-list 'z 'q) @result{} (z q z q z q @dots{})
2091 @end example
2092 @end defun
2093
2094 @subsubheading List predicates
2095
2096 @defun not-pair? x
2097 [R7RS list]
2098 @c MOD scheme.list
2099 @c EN
2100 Same as @code{(lambda (x) (not (pair? x)))}.
2101
2102 SRFI-1 says: Provided as a procedure as it can be useful as
2103 the termination condition for list-processing procedures that wish to
2104 handle all finite lists, both proper and dotted.
2105 @c JP
2106 @code{(lambda (x) (not (pair? x)))}と同じです。
2107
2108 SRFI-1 では、「真性リストおよびドットリストの両方で、すべての有限リストを
2109 扱う手続き用の終端条件として便利なように用意した」とあります。
2110 @c COMMON
2111 @end defun
2112
2113 @defun list= elt= list @dots{}
2114 [R7RS list]
2115 @c MOD scheme.list
2116 @c EN
2117 Determines list equality by comparing every n-th element
2118 of given lists by the procedure @var{elt=}.
2119
2120 It is an error to apply @code{list=} to anything except proper lists.
2121
2122 The equality procedure must be consistent with @code{eq?}, i.e.
2123 @c JP
2124 @var{elt=} を用いて、n番目の要素をそれぞれ比較することで、
2125 与えられたリストの同値性を決定します。
2126
2127 @code{list=} を真性リスト以外に適用するとエラーになります。
2128
2129 同値性判定の手続きは @code{eq?} と整合性がなければなりません。すなわち
2130 @c COMMON
2131
2132 @example
2133 (eq? x y) @result{} (elt= x y).
2134 @end example
2135 @end defun
2136
2137 @subsubheading List selectors
2138
2139 @defun first pair
2140 @defunx second pair
2141 @defunx third pair
2142 @defunx fourth pair
2143 @defunx fifth pair
2144 @defunx sixth pair
2145 @defunx seventh pair
2146 @defunx eighth pair
2147 @defunx ninth pair
2148 @defunx tenth pair
2149 [R7RS list]
2150 @c MOD scheme.list
2151 @c EN
2152 Returns n-th element of the (maybe improper) list.
2153 @c JP
2154 リスト(非真性でも可)のn番目の要素を返します。
2155 @c COMMON
2156 @end defun
2157
2158 @defun car+cdr pair
2159 [R7RS list]
2160 @c MOD scheme.list
2161 @c EN
2162 Returns two values, @code{(car pair)} and @code{(cdr pair)}.
2163 @c JP
2164 @code{(car pair)} および @code{(cdr pair)} の二つの値を返します。
2165 @c COMMON
2166 @end defun
2167
2168 @subsubheading List miscellaneous routines
2169
2170 @defun zip clist1 clist2 @dots{}
2171 [R7RS list]
2172 @c MOD scheme.list
2173 @c EN
2174 Equivalent to @code{(map list clist1 clist2 @dots{})}.
2175 If @code{zip} is passed @var{n} lists, it returns a list as long as
2176 the shortest of these lists, each element of which is an @var{n}-element list
2177 comprised of the corresponding elements from the parameter lists.
2178 @c JP
2179 @code{(map list clist1 clist2 @dots{})} と同等です。
2180 @var{n} 本のリストが @code{zip} に渡された場合には、そのなかで一番短いものと
2181 同じ長さのリストを返します。返されたリストは、要素が @var{n} 要素のリストで、
2182 そのそれぞれが、引数として渡ってリストの対応する要素になっています。
2183 @c COMMON
2184
2185 @example
2186 (zip '(one two three)
2187 '(1 2 3)
2188 '(odd even odd even odd even odd even))
2189 @result{} ((one 1 odd) (two 2 even) (three 3 odd))
2190
2191 (zip '(1 2 3)) @result{} ((1) (2) (3))
2192 @end example
2193
2194 @c EN
2195 At least one of the argument lists must be finite:
2196 @c JP
2197 引数のリストのうち、少くともひとつは有限のリストでなければなりません。
2198 @c COMMON
2199
2200 @example
2201 (zip '(3 1 4 1) (circular-list #f #t))
2202 @result{} ((3 #f) (1 #t) (4 #f) (1 #t))
2203 @end example
2204 @end defun
2205
2206 @defun unzip1 list
2207 @defunx unzip2 list
2208 @defunx unzip3 list
2209 @defunx unzip4 list
2210 @defunx unzip5 list
2211 [R7RS list]
2212 @c MOD scheme.list
2213 @c EN
2214 @code{unzip1} takes a list of lists, where every list must
2215 contain at least one element, and returns a list containing the
2216 initial element of each such list.
2217 @code{unzip2} takes a list of lists, where every list
2218 must contain at least two elements, and returns two values:
2219 a list of the first elements, and a list of the second
2220 elements. @code{unzip3} does the same for the first
2221 three elements of the lists, and so on.
2222 @c JP
2223 @code{unzip1} はリストのリストを引数としてとります。それぞれの
2224 リストは少くとも一つの要素を含むものでなくてはなりません。結果として
2225 それぞれのリストの最初の要素のリストを返します。
2226 @code{unzip2} はリストのリストを引数としてとります。それぞれのリストは
2227 少くとも二つの要素を含むものでなくてはなりません。結果として二つの値を
2228 返します。最初の要素のリストと二番目の要素のリストです。@code{unzip3} は
2229 3番目までの要素について同様です。以下も同様です。
2230 @c COMMON
2231
2232 @example
2233 (unzip2 '((1 one) (2 two) (3 three))) @result{}
2234 (1 2 3) @r{and}
2235 (one two three)
2236 @end example
2237 @end defun
2238
2239 @subsubheading List fold, unfold & map
2240
2241 @defun pair-fold kons knil clist1 clist2 @dots{}
2242 @defunx pair-fold-right kons knil clist1 clist2 @dots{}
2243 [R7RS list]
2244 @c MOD scheme.list
2245 @c EN
2246 Like @code{fold} and @code{fold-right}, but the procedure @var{kons}
2247 gets each @code{cdr} of the given @var{clist}s, instead of @code{car}.
2248 @c JP
2249 @code{fold} および @code{fold-right} と同様ですが、@var{kons} 手続き
2250 は与えられた @var{clist} の @code{car} ではなく、@code{cdr} をとります。
2251 @c COMMON
2252
2253 @example
2254 (pair-fold cons '() '(a b c d e))
2255 @result{} ((e) (d e) (c d e) (b c d e) (a b c d e))
2256
2257 (pair-fold-right cons '() '(a b c d e))
2258 @result{} ((a b c d e) (b c d e) (c d e) (d e) (e))
2259 @end example
2260 @end defun
2261
2262 @defun unfold p f g seed :optional tail-gen
2263 [R7RS list]
2264 @c MOD scheme.list
2265 @c EN
2266 Fundamental recursive list constructor.
2267 Defined by the following recursion.
2268 @c JP
2269 基本リスト再帰構築子です。
2270 以下のように再帰的に定義されています。
2271 @c COMMON
2272
2273 @example
2274 (unfold p f g seed tail-gen) @equiv{}
2275 (if (p seed)
2276 (tail-gen seed)
2277 (cons (f seed)
2278 (unfold p f g (g seed))))
2279 @end example
2280
2281 @c EN
2282 That is, @var{p} determines where to stop, @var{g} is used to generate
2283 successive seed value from the current seed value, and @var{f} is used
2284 to map each seed value to a list element.
2285 @c JP
2286 ここでは、@var{p} は終了位置の判定、@var{g} は現在の「種」から次の「種」
2287 を生成するのに用い、@var{f} はそれぞれの「種」をリストの要素に変換する
2288 のに用いられます。
2289 @c COMMON
2290
2291 @example
2292 (unfold (pa$ = 53) integer->char (pa$ + 1) 48)
2293 @result{} (#\0 #\1 #\2 #\3 #\4)
2294 @end example
2295 @end defun
2296
2297 @defun unfold-right p f g seed :optional tail
2298 [R7RS list]
2299 @c MOD scheme.list
2300 @c EN
2301 Fundamental iterative list constructor.
2302 Defined by the following recursion.
2303 @c JP
2304 基本リスト反復構築子です。
2305 以下のように再帰的に定義されています。
2306 @c COMMON
2307
2308 @example
2309 (unfold-right p f g seed tail) @equiv{}
2310 (let lp ((seed seed) (lis tail))
2311 (if (p seed)
2312 lis
2313 (lp (g seed) (cons (f seed) lis))))
2314 @end example
2315
2316 @example
2317 (unfold-right (pa$ = 53) integer->char (pa$ + 1) 48)
2318 @result{} (#\4 #\3 #\2 #\1 #\0)
2319 @end example
2320 @end defun
2321
2322 @defun map! f clist1 clist2 @dots{}
2323 [R7RS list]
2324 @c MOD scheme.list
2325 @c EN
2326 The procedure @var{f} is applied to each element of @var{clist1} and
2327 corresponding elements of @var{clist2}s, and the result is collected
2328 to a list. Cells in @var{clist1} is reused to construct the result list.
2329 @c JP
2330 手続き @var{f} は @var{clist1} の各要素と @var{clist2} の対応する要素
2331 に適用され、結果はひとつのリストになります。@var{clist1} のセルは
2332 結果のリストを構築するのに再利用されます。
2333 @c COMMON
2334 @end defun
2335
2336 @defun map-in-order f clist1 clist2 @dots{}
2337 [R7RS list]
2338 @c MOD scheme.list
2339 @c EN
2340 A variant of @code{map}, but it guarantees to apply @var{f}
2341 on each elements of arguments in a left-to-right order.
2342 Since Gauche's @code{map} implementation follows the same order,
2343 this function is just a synonym of @code{map}.
2344 @c JP
2345 @code{map} の変形バージョンですが、@var{f} の適用順序が、引数として
2346 与えられたリストの要素の左から右への順であることを保証します。
2347 Gauche では @code{map} の実装はこの順になっているので、@code{map} と
2348 同意です。
2349 @c COMMON
2350 @end defun
2351
2352 @defun pair-for-each f clist1 clist2 @dots{}
2353 [R7RS list]
2354 @c MOD scheme.list
2355 @c EN
2356 Like @code{for-each}, but the procedure @var{f} is applied on
2357 @var{clist}s themselves first, then each @code{cdr}s of them, and so on.
2358 @c JP
2359 @code{for-each} と似ていますが、手続き @var{f} はまず @var{clist}自体に
2360 適用され、次ににそれらの@code{cdr} に適用され、となります。
2361 @c COMMON
2362
2363 @example
2364 (pair-for-each write '(a b c))
2365 @result{} @r{prints} (a b c)(b c)(c)
2366 @end example
2367 @end defun
2368
2369 @subsubheading List partitioning
2370
2371 @defun partition pred list
2372 @defunx partition! pred list
2373 [R7RS list]
2374 @c MOD scheme.list
2375 @c EN
2376 @code{filter} and @code{remove} simultaneously, i.e.
2377 returns two lists, the first is the result of filtering elements of
2378 @var{list} by @var{pred}, and the second is the result of
2379 removing elements of @var{list} by @var{pred}.
2380 @c JP
2381 @code{filter} と @code{remove} を同時に行い、
2382 2つのリストを返します。一つ目は @var{pred} により @var{list} の要素をフィルタリング
2383 した結果で、二つ目は @var{pred} により @var{list} の要素を削除した結果です。
2384 @c COMMON
2385 @example
2386 (partition odd? '(3 1 4 5 9 2 6))
2387 @result{} (3 1 5 9) (4 2 6)
2388 @end example
2389 @c EN
2390 @code{partition!} is the linear-update variant. It may destructively
2391 modifies @var{list} to produce the result.
2392 @c JP
2393 @code{partition!} はその場で更新されるバージョンです。結果を生成するために
2394 @var{list} を破壊的に更新するかもしれません。
2395 @c COMMON
2396 @end defun
2397
2398 @subsubheading List searching
2399
2400 @defun take-while pred clist
2401 @defunx take-while! pred list
2402 [R7RS list]
2403 @c MOD scheme.list
2404 @c EN
2405 Returns the longest initial prefix of @var{clist} whose elements all
2406 satisfy @var{pred}.
2407 @c JP
2408 @var{clist} の最初から、@var{pred} を満足する限りの最長部分要素を返します。
2409 @c COMMON
2410 @end defun
2411
2412 @defun drop-while pred clist
2413 [R7RS list]
2414 @c MOD scheme.list
2415 @c EN
2416 Drops the longest initial prefix of @var{clist} whose elements all
2417 satisfy @var{pred}, and returns the rest.
2418 @c JP
2419 @var{clist} の最初から、@var{pred} を満足する限りの最長部分要素を削除し、
2420 残りを返します。
2421 @c COMMON
2422 @end defun
2423
2424 @defun span pred clist
2425 @defunx span! pred list
2426 @defunx break pred clist
2427 @defunx break! pred list
2428 [R7RS list]
2429 @c MOD scheme.list
2430 @c EN
2431 @code{span} is equivalent to
2432 @code{(values (take-while pred clist) (drop-while pred clist))}.
2433 @code{break} inverts the sense of @var{pred}.
2434 @c JP
2435 @code{span} は @code{(values (take-while pred clist) (drop-while pred clist))}
2436 と等価です。@code{break} は @var{pred} の意味を反転します。
2437 @c COMMON
2438 @end defun
2439
2440 @defun list-index pred clist1 clist2 @dots{}
2441 [R7RS list]
2442 @c MOD scheme.list
2443 @c EN
2444 Returns the index of the leftmost element that satisfies @var{pred}.
2445 If no element satisfies @var{pred}, @code{#f} is returned.
2446 @c JP
2447 @var{pred} を満足する最も左の要素のインデックスを返します。
2448 @var{pred}を満たす要素が無い場合は@code{#f}を返します。
2449 @c COMMON
2450 @end defun
2451
2452 @subsubheading Association lists
2453
2454 @defun alist-cons key datum alist
2455 [R7RS list]
2456 @c MOD scheme.list
2457 @c EN
2458 Returns @code{(cons (cons @var{key} @var{datum}) @var{alist})}.
2459 This is an alias of the Gauche builtin procedure @code{acons}.
2460 @c JP
2461 @code{(cons (cons @var{key} @var{datum}) @var{alist})} を返します。
2462 これは、Gauche の組み込み手続き @code{acons} の別名です。
2463 @c COMMON
2464 @end defun
2465
2466 @subsubheading Lists as sets
2467
2468 @c EN
2469 These procedures use a list as a set, that is,
2470 the elements in a list matter, but their order doesn't.
2471
2472 All procedures in this category takes a comparison procedure
2473 @var{elt=}, as the first argument, which is used to determine
2474 two elements in the given sets are the same.
2475
2476 Since lists require linear time to search, those procedures aren't
2477 suitable to deal with large sets. @xref{R7RS sets}, if you
2478 know your sets will contain more than a dozen items or so.
2479
2480 See also @ref{Combination library}, which
2481 concerns combinations of elements in the set.
2482 @c JP
2483 これらの手続きはリストを集合としてあつかいます。すなわち、どのような
2484 要素があるかは重要ですが、その順序は重要ではありません。
2485
2486 この範疇にあるすべての手続きは、比較手続き @var{elt=} を最初の引数として
2487 とります。この比較手続きは与えられた二つの集合の要素が等しいかどうかを
2488 判定します。
2489
2490 リストは検索に線形時間を必要とするため、ここに挙げた手続きは
2491 大きな集合を扱うには向いていません。もし対象となる集合が
2492 二桁以上の要素を持つことが分かっているなら、@ref{R7RS sets}を
2493 参照してください。
2494
2495 集合の要素の組み合せについては @ref{Combination library}
2496 も参照してください。
2497 @c COMMON
2498
2499 @defun lset<= elt= list1 @dots{}
2500 [R7RS list]
2501 @c MOD scheme.list
2502 @c EN
2503 Returns @code{#t} iff all elements in @var{list1} are also included
2504 in @var{list2}, and so on.
2505 If no lists are given, or a single list is given,
2506 @code{#t} is returned.
2507 @c JP
2508 @var{list1} のすべての要素が @var{list2} (以降の集合)に含まれている
2509 ときに限り @code{#t} を返します。リストが与えられなかった場合
2510 および一つだけしか与えられなかった場合には、@code{#t} を返します。
2511 @c COMMON
2512 @end defun
2513
2514 @defun lset= elt= list1 list2 @dots{}
2515 [R7RS list]
2516 @c MOD scheme.list
2517 @c EN
2518 Returns @code{#t} if all elements in @var{list1} are in @var{list2},
2519 and all elements in @var{list2} are in @var{list1}, and so on.
2520 @c JP
2521 @var{list1} のすべての要素が @var{list2} に含まれており、かつ、
2522 @var{list2} のすべての要素が @var{list1} に含まれていれば、@code{#t}
2523 を返します。
2524 @c COMMON
2525
2526 @example
2527 (lset= eq? '(b e a) '(a e b) '(e e b a)) @result{} #t
2528 @end example
2529 @end defun
2530
2531 @defun lset-adjoin elt= list elt @dots{}
2532 [R7RS list]
2533 @c MOD scheme.list
2534 @c EN
2535 Adds @var{elt} @dots{} to the set @var{list}, if each one is not
2536 already a member of @var{list}. (The order doesn't matter).
2537 @c JP
2538 @var{elt} @dots{} を集合 @var{list} にまだなければ、追加します。
2539 (順序はとくに決っていません。)
2540 @c COMMON
2541
2542 @example
2543 (lset-adjoin eq? '(a b c) 'a 'e) @result{} '(e a b c)
2544 @end example
2545 @end defun
2546
2547 @defun lset-union elt= list1 @dots{}
2548 [R7RS list]
2549 @c MOD scheme.list
2550 @c EN
2551 Returns the union of the sets @var{list1} @dots{}.
2552 @c JP
2553 @var{list1} @dots{} の和集合を返します。
2554 @c COMMON
2555 @end defun
2556
2557 @defun lset-intersection elt= list1 list2 @dots{}
2558 [R7RS list]
2559 @c MOD scheme.list
2560 @c EN
2561 Returns a set of elements that are in every @var{list}s.
2562 @c JP
2563 すべての @var{list} に含まれる要素の集合を返します。
2564 @c COMMON
2565 @end defun
2566
2567 @defun lset-difference elt= list1 list2 @dots{}
2568 [R7RS list]
2569 @c MOD scheme.list
2570 @c EN
2571 Returns a set of elements that are in @var{list1} but not
2572 in @var{list2}. In n-ary case, binary difference operation is
2573 simply folded.
2574 @c JP
2575 @var{list1} には含まれていて、@var{list2} には含まれていない要素の集合を
2576 返します。引数が n 個与えられた場合には、差分をとる二項演算が
2577 畳み込まれます。
2578 @c COMMON
2579 @end defun
2580
2581 @defun lset-xor elt= list1 @dots{}
2582 [R7RS list]
2583 @c MOD scheme.list
2584 @c EN
2585 Returns the exclusive-or of given sets; that is, the returned
2586 set consists of the elements that are in either @var{list1} or @var{list2},
2587 but not in both. In n-ary case, binary xor operation is simply folded.
2588 @c JP
2589 与えられた集合の排他的論理和を返します。すなわち、@var{list1} および
2590 @var{list2} のどちらか一方にのみ属する要素からなる集合を返します。
2591 引数が n 個の場合には、xor の二項演算が畳み込まれます。
2592 @c COMMON
2593 @end defun
2594
2595 @defun lset-diff+intersection elt= list1 list2 @dots{}
2596 [R7RS list]
2597 @c MOD scheme.list
2598 @c EN
2599 Returns two sets, a difference and an intersection of given sets.
2600 @c JP
2601 与えられた集合の差集合と積集合のふたつの集合を返します。
2602 @c COMMON
2603 @end defun
2604
2605 @defun lset-union! elt= list @dots{}
2606 @defunx lset-intersection! elt= list1 list2 @dots{}
2607 @defunx lset-difference! elt= list1 list2 @dots{}
2608 @defunx lset-xor! elt= list1 @dots{}
2609 @defunx lset-diff+intersection! elt= list1 list2 @dots{}
2610 [R7RS list]
2611 @c MOD scheme.list
2612 @c EN
2613 Linear update variant of the corresponding procedures.
2614 The cells in the first list argument may be reused to construct the result.
2615 @c JP
2616 それぞれ対応する手続きのその場で更新するバージョンです。
2617 最初の引数のリストのセルが結果を構築するのに再利用されるかもしれません。
2618 @c COMMON
2619 @end defun
2620
2621 @node R7RS vectors, R7RS uniform vectors, R7RS lists, R7RS large
2622 @subsection @code{scheme.vector} - R7RS vectors
2623 @c NODE R7RSベクタ, @code{scheme.vector} - R7RSベクタ
2624
2625 @deftp {Module} scheme.vector
2626 @mdindex scheme.vector
2627 @c EN
2628 This module adds rich set of vector operations to the built-in / R7RS
2629 vector procedures.
2630 @c JP
2631 このモジュールは豊富なベクタ操作を提供します。
2632 @c COMMON
2633
2634 @c EN
2635 The following procedures are built-in.
2636 @xref{Vectors}, for the description. We only explain
2637 the procedures that are not built-in.
2638 @c JP
2639 以下の手続きはGaucheでは組み込みになっています。説明は@ref{Vectors}を参照してください。
2640 組み込みでない手続きについてのみ解説します。
2641 @c COMMON
2642
2643 @example
2644 make-vector vector vector?
2645 vector-ref vector-set! vector-length
2646 vector-fill! vector-copy vector-copy!
2647 vector-append vector->list list->vector
2648 reverse-list->vector vector->string string->vector
2649 vector-map vector-map! vector-for-each
2650 @end example
2651
2652 @c EN
2653 This module is @code{srfi.133}, which supersedes @code{srfi.43}
2654 (@pxref{Vector library (Legacy)}).
2655 Note that the interface of following procedures in @code{srfi.43}
2656 are changed for the consistency:
2657 @c JP
2658 このモジュールは@code{srfi.133}として制定され、
2659 @code{srfi.43}(@ref{Vector library (Legacy)})を置き換えるものです。
2660 @code{srfi.43}の手続きのうち、以下のものは一貫性からインタフェースが
2661 変更されていることに注意してください。
2662 @c COMMON
2663
2664 @example
2665 vector-map vector-map! vector-for-each
2666 vector-fold vector-fold-right vector-count
2667 @end example
2668
2669 @c EN
2670 Some of the functionalities
2671 of @code{srfi.43} version is supported by built-in procedures
2672 (e.g. Built-in @code{vector-map-with-index} is the same as
2673 @code{srfi.43}'s @code{vector-map}). So there's little point
2674 for new code to use @code{srfi.43}.
2675 @c JP
2676 @code{srfi.43}から削られた機能の一部は、
2677 Gaucheの組み込み手続きでサポートされています
2678 (例えば@code{srfi.43}の@code{vector-map}は組み込みの@code{vector-map-with-index}と
2679 同じです)。新しいコードで@code{srfi.43}を使う必要はほとんどないでしょう。
2680 @c COMMON
2681 @end deftp
2682
2683 @c EN
2684 @subheading Vector constructors
2685 @c JP
2686 @subheading ベクタ構成子
2687 @c COMMON
2688
2689 @defun vector-unfold f length seed @dots{}
2690 [R7RS vector]
2691 @c MOD scheme.vector
2692 @c EN
2693 Creates a vector of length @var{length}, filling elements
2694 left to right by calling @var{f} repeatedly.
2695
2696 The procedure @var{f} must take as many arguments as
2697 one plus number of seed values, and must return the same number
2698 of values. The first argument is the index. The first return
2699 value is used for the element of the result vector, and the
2700 rest of return values are passed to the next call of @var{f}.
2701 @c JP
2702 長さ@var{length}のベクタを作って返します。要素は左から右に、
2703 @var{f}を繰り返し呼ぶことで計算されます。
2704
2705 手続き@var{f}は、@var{seed}の数よりひとつ多い引数を取り、同数の値を返さなければなりません。
2706 引数の最初に渡されるのはインデックスです。戻り値の最初の値がそのインデックスの要素の初期値に
2707 使われ、残りの戻り値が次のシード値となります。
2708 @c COMMON
2709
2710 @example
2711 (vector-unfold (^[i] (* i i)) 5)
2712 @result{} #(0 1 4 9 16)
2713
2714 (vector-unfold (^[i x] (values (cons i x) (* x 2))) 8 1)
2715 @result{} #((0 . 1) (1 . 2) (2 . 4) (3 . 8)
2716 (4 . 16) (5 . 32) (6 . 64) (7 . 128))
2717 @end example
2718
2719 @c EN
2720 Note: This protocol is different from the list @code{unfold}
2721 and most of other @code{*-unfold} constructors (@pxref{R7RS lists}).
2722 For fixed-length strcuctures like vectors,
2723 it makes more sense to know the final length beforehand, rather than
2724 checking the termination condition for each iteration.
2725 @c JP
2726 註: このプロトコルは、リストの@code{unfold}コンストラクタや、それに倣った
2727 多くの@code{*-unfold}コンストラクタと異なることに注意してください。
2728 ベクタのような固定長構造体では、終端条件を繰り返しの度に検査するより、
2729 最初から長さが分かっている方が意味があります。
2730 @c COMMON
2731 @end defun
2732
2733 @defun vector-unfold-right f length seed @dots{}
2734 [R7RS vector]
2735 @c MOD scheme.vector
2736 @c EN
2737 Creates a vector of length @var{length}, filling elements
2738 right to left by calling @var{f} repeatedly.
2739 @c JP
2740 長さ@var{length}のベクタを作って返します。要素は右から左に、
2741 @var{f}を繰り返し呼ぶことで計算されます。
2742 @c COMMON
2743
2744 @c EN
2745 The procedure @var{f} must take as many arguments as
2746 one plus number of seed values, and must return the same number
2747 of values. The first argument is the index. The first return
2748 value is used for the element of the result vector, and the
2749 rest of return values are passed to the next call of @var{f}.
2750 @c JP
2751 手続き@var{f}は、@var{seed}の数よりひとつ多い引数を取り、同数の値を返さなければなりません。
2752 引数の最初に渡されるのはインデックスです。戻り値の最初の値がそのインデックスの要素の初期値に
2753 使われ、残りの戻り値が次のシード値となります。
2754 @c COMMON
2755
2756 @example
2757 (vector-unfold-right (^[i] (* i i)) 5)
2758 @result{} #(0 1 4 9 16)
2759
2760 (vector-unfold-right (^[i x] (values (cons i x) (* x 2))) 8 1)
2761 @result{} #((0 . 128) (1 . 64) (2 . 32) (3 . 16)
2762 (4 . 8) (5 . 4) (6 . 2) (7 . 1))
2763 @end example
2764 @end defun
2765
2766 @defun vector-reverse-copy vec :optional start end
2767 [R7RS vector]
2768 @c MOD scheme.vector
2769 @c EN
2770 Copies the vector @var{vec} with reversing its elements.
2771 Optional @var{start} and @var{end} arguments can limit
2772 the range of the input.
2773 @c JP
2774 ベクタ@var{vec}を要素を逆順にしてコピーします。
2775 省略可能引数@var{start}と@var{end}は元のベクタから取り出す範囲を限定します。
2776 @c COMMON
2777
2778 @example
2779 (vector-reverse-copy '#(a b c d e) 1 4)
2780 @result{} #(d c b)
2781 @end example
2782 @end defun
2783
2784 @defun vector-concatenate list-of-vectors
2785 [R7RS vector]
2786 @c MOD scheme.vector
2787 @c EN
2788 Same as @code{(apply vector-append list-of-vectors)}.
2789 @c JP
2790 @code{(apply vector-append list-of-vectors)}と同じです。
2791 @c COMMON
2792 @end defun
2793
2794 @defun vector-append-subvectors spec @dots{}
2795 [R7RS vector]
2796 @c MOD scheme.vector
2797 @c EN
2798 The number of arguments must be multiple of 3. The argument list
2799 must be in the following format, where each @var{vecN} is
2800 a vector, and @code{startN} and @code{endN} are nonnegative exact integers:
2801 @c JP
2802 引数の数は3の倍数でなければなりません。
2803 引数リストは次の形式をとります。ここで、@var{vecN}はベクタ、
2804 @var{startN}と@var{endN}は非負の正確な整数です。
2805 @c COMMON
2806
2807 @example
2808 vec1 start1 end1 vec2 start2 end2 @dots{}
2809 @end example
2810
2811 @c EN
2812 This procedure creates a new vector by concatenating subvectors
2813 specified by each triplet. That is, it works as if it's the following
2814 code, except it avoids copying each subvector:
2815 @c JP
2816 この手続きは、それぞれの3つ組で指定される部分ベクタをつなぎ合わせたベクタを
2817 作って返します。つまり、以下のコードと同様の動作をしますが、
2818 各部分ベクタのコピーは避けられます。
2819 @c COMMON
2820
2821 @example
2822 (vector-append (vector-copy vec1 start1 end1)
2823 (vector-copy vec2 start2 end2)
2824 @dots{})
2825 @end example
2826
2827 @c EN
2828 Here's an example:
2829 @c JP
2830 例を示します:
2831 @c COMMON
2832
2833 @example
2834 (vector-append-subvectors '#(a b c d e) 0 3
2835 '#(f g h i j) 2 5)
2836 @result{} #(a b c h i j)
2837 @end example
2838 @end defun
2839
2840
2841 @c EN
2842 @subheading Vector predicates
2843 @c JP
2844 @subheading ベクタ上の述語
2845 @c COMMON
2846
2847 @defun vector-empty? vec
2848 [R7RS vector]
2849 @c MOD scheme.vector
2850 @c EN
2851 Returns @code{#t} if @var{vec}'s length is zero, and
2852 @code{#f} if @var{vec}'s length is more than zero.
2853 Signals an error if @var{vec} is not a vector.
2854 @c JP
2855 ベクター@var{vec}の長さが0なら@code{#t}を、1以上なら@code{#f}を返します。
2856 @var{vec}がベクタでなければエラーが投げられます。
2857 @c COMMON
2858 @end defun
2859
2860 @defun vector= elt= vec @dots{}
2861 [R7RS vector]
2862 @c MOD scheme.vector
2863 @c EN
2864 Compares @var{vec}s element-wise, using given predicate @var{elt=}.
2865 Returns @code{#t} iff lengths of all the vectors are the same,
2866 and every corresponding elements are equal by @var{elt=}.
2867
2868 @var{Elt=} is always called with two arguments and must
2869 return @code{#t} iff two are the same.
2870
2871 When zero or one vector is passed, @var{elt=} won't be called
2872 and @var{vector=} always returns @code{#t}.
2873 @c JP
2874 @var{vec} @dots{}を要素ごとに比較してゆきます。要素間の比較には@var{elt=}が使われます。
2875 全てのベクタ引数が同じ長さで、対応する要素が@var{elt=}によって等しかった場合に、@code{#t}
2876 が返されます。
2877
2878 @var{elt=}は常に二つの引数を取り、
2879 等しければ@code{#t}を、そうでなければ@code{#f}を返します。
2880
2881 ゼロ個か1個のベクタが渡された場合は、@var{elt=}は全く呼ばれず、
2882 @code{vector=}は常に@code{#t}を返します。
2883 @c COMMON
2884 @end defun
2885
2886 @c EN
2887 @subheading Vector iteration
2888 @c JP
2889 @subheading ベクタ上の繰り返し
2890 @c COMMON
2891
2892 @defun vector-fold kons knil vec1 vec2 @dots{}
2893 [R7RS vector]
2894 @c MOD scheme.vector
2895 @c EN
2896 @var{Kons} is a procedure that takes @var{n}+1 arguments, where
2897 @var{n} is the number of given vectors. For each element of the
2898 given vectors, @var{kons} is called as
2899 @code{(@var{kons} @var{seed} @var{e_1i} @var{e_2i} @dots{})},
2900 where and @var{e_ni} is the @var{i}-th element
2901 of the vector @var{n}. If the lengths of the vectors differ,
2902 iteration stops when the shortest vector is exhausted.
2903 @c JP
2904 @var{kons}は与えられたベクタ引数@var{vec1} @var{vec2} @dots{}
2905 の数よりひとつ多い引数を取る手続きです。
2906 各ベクタの@var{i}番目の要素@var{e_1i} @var{e_2i} @dots{})に
2907 対して、@var{kons}が
2908 @code{(@var{kons} @var{seed} @var{e_1i} @var{e_2i} @dots{})}
2909 のように順次呼ばれます。ベクタの長さが異なっていた場合、最も短いベクタが尽きたところで
2910 繰り返しは停止します。
2911 @c COMMON
2912
2913 @c EN
2914 The initial value of @var{seed} is @var{knil}, and the return value
2915 from @var{kons} is used as the next seed value. The last return value
2916 of @var{kons} is returned from @code{vector-fold}.
2917 @c JP
2918 @var{seed}の初期値は@var{knil}で、@var{kons}の戻り値が次の@var{seed}として
2919 使われます。最後の@var{kons}の戻り値が@code{vector-fold}の戻り値となります。
2920 @c COMMON
2921
2922 @c EN
2923 The iteration is strictly left to right.
2924 @c JP
2925 繰り返しはベクタの左から右へと進みます。
2926 @c COMMON
2927
2928 @c EN
2929 Note that the seed value precedes elements, which is opposite to
2930 @code{fold} (@pxref{Mapping over collection}). It's an unfortunate
2931 historical glitch; @code{vector-fold-left} would be more consistent
2932 name.
2933 @c JP
2934 @var{seed}引数が要素の前に来ることに注意してください。これは
2935 @code{fold} (@ref{Mapping over collection}参照)とは逆です。
2936 歴史的に生じた不幸なすれちがいです。
2937 @code{vector-fold-left}であれば一貫性があったでしょう。
2938 @c COMMON
2939
2940 @example
2941 (vector-fold (^[a b] (cons b a)) '() '#(a b c d))
2942 @result{} (d c b a)
2943 @end example
2944 @end defun
2945
2946 @defun vector-fold-right kons knil vec1 vec2 @dots{}
2947 [R7RS vector]
2948 @c MOD scheme.vector
2949 @c EN
2950 Like @code{vector-fold}, but elements in the @var{vec1} @var{vec2} @dots{}
2951 are visited from right to left.
2952
2953 If the lengths of the vectors differ, this procedure only looks up to
2954 the number of elements of the shortest vector and ignores any excessive
2955 elements. See the second example below.
2956 @c JP
2957 @code{vector-fold}と似ていますが、@var{vec1} @var{vec2} @dots{}の各要素は
2958 右から左へと読まれます。
2959
2960 ベクタの長さが異なる場合は、最も短いベクタの要素数までを見て、残りは無視します。
2961 下の2番目の例を見てください。
2962 @c COMMON
2963
2964 @c EN
2965 Unlike @code{fold-right} (@pxref{Mapping over sequences}),
2966 the procedure @var{kons} takes the seed value in the
2967 first argument.
2968 @c JP
2969 @code{fold-right} (@ref{Mapping over sequences}参照)とは異なり、
2970 @var{kons}はシード値を最初の引数として受け取ります。
2971 @c COMMON
2972
2973 @example
2974 (vector-fold-right (^[a b] (cons b a)) '() '#(a b c d))
2975 @result{} (a b c d)
2976
2977 (vector-fold-right (^[s x y] (cons (list x y) s)) '()
2978 '#(a b c) '#(1 2 3 4))
2979 @result{} ((a 1) (b 2) (c 3))
2980 @end example
2981 @end defun
2982
2983 @defun vector-count pred vec1 vec2 @dots{}
2984 [R7RS vector]
2985 @c MOD scheme.vector
2986 @c EN
2987 Applies @var{pred} on each elements in argument vectors (if N vectors
2988 are given, @var{pred} takes N arguments, the first being
2989 @var{i}-th element of @var{vec1}, the second being @var{i}-th element
2990 of @var{vec2}, etc.) Then returns the number of times
2991 @var{pred} returned true value. The order @var{pred} applied
2992 to each element is unspecified.
2993 @c JP
2994 @var{pred}を引数のベクタの各要素に適用します
2995 (N個のベクタが与えられた場合、@var{pred}はN個の引数を取り、
2996 各ベクタの対応する要素が渡されます)。
2997 そして、@var{pred}が真の値を返した回数を正確な整数で返します。
2998 @var{pred}がどのような順番で適用されるかは規定されていません。
2999 @c COMMON
3000
3001 @example
3002 (vector-count odd? '#(0 1 2 3 4)
3003 @result{} 2
3004
3005 (vector-count < '#(7 3 9 1 5) '#(6 8 2 3 8 8))
3006 @result{} 3
3007 @end example
3008 @end defun
3009
3010 @defun vector-cumulate f seed vec
3011 [R7RS vector]
3012 @c MOD scheme.vector
3013 @c EN
3014 Returns a fresh vector with the same size of @var{vec}, with
3015 the elements calculated as follows:
3016 @c JP
3017 @var{vec}と同じ長さの新たなベクタを作り、以下の手順で要素を埋めてからそれを返します。
3018 @c COMMON
3019
3020 @c EN
3021 The first element of result vector is a result of procedure @var{f}
3022 called with @var{seed} and the first element of @var{vec}.
3023 @c JP
3024 結果の最初の要素は、@code{(@var{f} @var{seed} (vector-ref @var{vec} 0))}です。
3025 @c COMMON
3026
3027 @c EN
3028 The @var{i}-th element of result vector is a result of procedure @var{f}
3029 called with @var{i-1}-th element of result vector and @var{i}-th element
3030 of @var{vec}.
3031 @c JP
3032 @var{i}番目の要素は、@var{i-1}番目の結果と、@code{(vector-ref @var{vec} @var{i})}を
3033 引数にして@var{f}を呼び出した結果です。
3034 @c COMMON
3035
3036 @example
3037 (vector-cumulate string-append "z" '#("a" "b" "c"))
3038 @result{} #("za" "zab" "zabc")
3039 @end example
3040 @end defun
3041
3042
3043 @c EN
3044 @subheading Vector searching
3045 @c JP
3046 @subheading ベクタ上の検索
3047 @c COMMON
3048
3049 @defun vector-index pred vec1 vec2 @dots{}
3050 @defunx vector-index-right pred vec1 vec2 @dots{}
3051 [R7RS vector]
3052 @c MOD scheme.vector
3053 @c EN
3054 Returns the index of the first or the last elements in @var{vec1}
3055 @var{vec2} @dots{} that satisfy @var{pred}, respectively.
3056 Returns @code{#f} if no elements satisfy @var{pred}.
3057 In @code{vector-index}, comparison ends at the end of the shortest vector.
3058 For @code{vector-index-right}, all the vectors must have the same length.
3059 @c JP
3060 @var{vec1} @var{vec2} @dots{}の要素のうち@var{pred}を満たす最初のもの、
3061 あるいは最後のもののインデックスをそれぞれ返します。
3062 @var{pred}を満たす要素が無ければ@code{#f}が返されます。
3063 @code{vector-index}では、一番短いベクタの終端に達したら処理を終了します。
3064 @code{vector-index-right}では、全てのベクタは同じ長さでなければなりません。
3065 @c COMMON
3066 @end defun
3067
3068 @defun vector-skip pred vec1 vec2 @dots{}
3069 @defunx vector-skip-right pred vec1 vec2 @dots{}
3070 [R7RS vector]
3071 @c MOD scheme.vector
3072 @c EN
3073 Like @code{vector-index} and @code{vector-index-right}, except that
3074 the result of @var{pred} is negated. That is, returns the index
3075 of the first or the last elements that don't satisfy @var{pred}.
3076 @c JP
3077 @var{pred}の結果が逆であること以外は、
3078 @code{vector-index}および@code{vector-index-right}と同じです。
3079 すなわち、@var{pred}を満たさない最初あるいは最後の要素のインデックスが返されます。
3080 @c COMMON
3081 @end defun
3082
3083 @defun vector-binary-search vec value cmp :optional start end
3084 [R7RS+ vector]
3085 @c MOD scheme.vector
3086 @c EN
3087 Look for @var{value} in a sorted vector @var{vec}, and returns its
3088 index if it is found, or @code{#f} if it is not found.
3089
3090 Comparison of @var{value} and an element in @var{vec} is
3091 done by a procedure @var{cmp}, which takes two arguments,
3092 and should return a negative integer if the first argument is less than the
3093 second, 0 if they are the same, and a positive integer if the first
3094 is greater than the second.
3095
3096 Elements in @var{vec} must be ordered from smaller to greater
3097 w.r.t. @var{cmp}. Using that fact, this procedure performs
3098 binary search instead of linear search.
3099
3100 The optional arguments @var{start} and @var{end} are an
3101 extension to SRFI-133, and can be used to limit the range of the
3102 search in @var{start}-th element (inclusive) to
3103 @var{end}-th element (exclusive).
3104 @c JP
3105 ソートされたベクタ@var{vec}中から値@var{value}を探し、
3106 見つかればそのインデックスを、見つからなければ@code{#f}を返します。
3107
3108 @var{vec}の要素と@var{value}の比較は手続き@var{cmp}で行われます。
3109 @var{cmp}は二つの引数を取り、最初の引数の方が小さければ負の整数を、
3110 等しければ0を、最初の引数の方が大きければ正の整数を買えす手続きです。
3111
3112 @var{vec}の要素は@var{cmp}による比較に従い小さい方から順にソート済みで
3113 なければなりません。この手続きはその仮定のもとに、二分探索を行います。
3114
3115 省略可能な@var{start}と@var{end}引数は、Gauche独自の拡張です。指定された場合、
3116 @var{start}番目の要素(含む)から@var{end}番目の要素(含まない)までが探索の対象となります。
3117 @c COMMON
3118 @end defun
3119
3120 @defun vector-any pred vec1 vec2 @dots{}
3121 [R7RS vector]
3122 @c MOD scheme.vector
3123 @c EN
3124 Applies @var{pred} on each corresponding elements
3125 of @var{vec1} @var{vec2} @dots{} left to right, and
3126 as soon as @var{pred} returns non-@code{#f} value,
3127 the procedure stops iteration and returns the value.
3128
3129 If no elements that satisfy @var{pred} are found, it returns @code{#f}.
3130
3131 Vectors can have different lengths. Iteration stops at the end
3132 of the shortest.
3133 @c JP
3134 @var{vec1} @var{vec2} @dots{}の各ベクタの先頭から順に、
3135 ひとつづつ対応する要素を取って、それに@var{pred}を適用してゆきます。
3136 @var{pred}が真の値を返したら、直ちにその値を返します。
3137
3138 @var{pred}を満たす要素が見つからなければ、@code{#f}が返されます。
3139
3140 ベクタの長さは異なっていても構いません。最も短いベクタの要素を使い切ったところで
3141 探索は打ちきられます。
3142 @c COMMON
3143 @end defun
3144
3145 @defun vector-every pred vec1 vec2 @dots{}
3146 [R7RS vector]
3147 @c MOD scheme.vector
3148 @c EN
3149 Applies @var{pred} on each corresponding elements
3150 of @var{vec1} @var{vec2} @dots{} left to right.
3151 If all the elements (when the lengths of vectors differ, the
3152 first N elements where N is the length of the shortest) satisfy
3153 @var{pred}, returns the last result of @var{pred}.
3154 If any of the elements don't satisfy @var{pred},
3155 it returns @code{#f} immediately without looking further.
3156 @c JP
3157 @var{vec1} @var{vec2} @dots{}の各ベクタの先頭から順に、
3158 ひとつづつ対応する要素を取って、それに@var{pred}を適用します。
3159 全ての要素が@var{pred}を満たした場合(ベクタの長さが異なる場合は、
3160 最も短いベクタを使い切った時点)で、最後の@var{pred}の結果を返します。
3161 途中で@var{pred}が@code{#f}を返した場合は、その先は見ずに直ちに@code{#f}を返します。
3162 @c COMMON
3163
3164 @example
3165 (vector-every < '#(1 2 3 4 5) '#(2 3 4 4 5)
3166 @result{} #f
3167
3168 (vector-every (^[x y] (and (real? x) (real? y) (- x y)))
3169 '#(1 2 3)
3170 '#(2 4 6))
3171 @result{} -3
3172 @end example
3173 @end defun
3174
3175 @defun vector-partition pred vec
3176 [R7RS vector]
3177 @c MOD scheme.vector
3178 @c EN
3179 Allocates a fresh vector of the same size as @var{vec},
3180 then fill it with elements in @var{vec} that satisfy @var{pred},
3181 followed by elements that don't satisfy @var{pred}.
3182
3183 Returns two values, the newly created vector and
3184 an exact integer of the index of the first element that doesn't satisfy
3185 @var{pred} in the returned vector.
3186 @c JP
3187 @var{vec}と同じ大きさのベクタを新たにアロケートし、
3188 まず@var{vec}中の@var{pred}を満たす要素を順に詰めてゆき、
3189 その後を@var{pred}を満たさない要素で埋めます。
3190
3191 新たに作られたベクタと、その中で@var{pred}を満たさない最初の要素を指す
3192 インデックスの二つの値を返します。
3193 @c COMMON
3194
3195 @example
3196 (vector-partition odd? '#(1 2 3 4 5 6 7 8))
3197 @result{} #(1 3 5 7 2 4 6 8) @r{and} 4
3198 @end example
3199 @end defun
3200
3201 @c EN
3202 @subheading Vector mutators
3203 @c JP
3204 @subheading ベクタの変更子
3205 @c COMMON
3206
3207 @defun vector-swap! vec i j
3208 [R7RS vector]
3209 @c MOD scheme.vector
3210 @c EN
3211 Swaps vector @var{vec}'s @var{i}-th and @var{j}-th elements.
3212 Returns unspecified value.
3213 @c JP
3214 @var{vec}の@var{i}番目の要素と@var{j}番目の要素を交換します。
3215 戻り値はunspecifiedです。
3216 @c COMMON
3217
3218 @example
3219 (rlet1 v (vector 'a 'b 'c 'd 'e)
3220 (vector-swap! v 0 2))
3221 @result{} #(c b a d e)
3222 @end example
3223 @end defun
3224
3225 @defun vector-reverse! vec :optional start end
3226 [R7RS vector]
3227 @c MOD scheme.vector
3228 @c EN
3229 Reverse the elements of @var{vec}. Returns an undefined value.
3230 Optional @var{start} and @var{end} arguments can limit
3231 the range of operation.
3232 @c JP
3233 @code{vec}の要素を逆順に並べ替えます。戻り値は未定義です。
3234 省略可能引数@var{start}と@var{end}は影響が及ぶ範囲を限定します。
3235 @c COMMON
3236
3237 @example
3238 (rlet1 v (vector 'a 'b 'c 'd 'e)
3239 (vector-reverse! v 0 4))
3240 @result{} #(d c b a e)
3241 @end example
3242 @end defun
3243
3244 @defun vector-reverse-copy! target tstart source :optional sstart send
3245 [R7RS vector]
3246 @c MOD scheme.vector
3247 @c EN
3248 Like @code{vector-copy!}, but reverses the order of elements from @var{start}.
3249 @c JP
3250 @code{vector-copy!}と似ていますが、指定範囲を逆順にコピーします。
3251 @c COMMON
3252
3253 @example
3254 (rlet1 v (vector 'a 'b 'c 'd 'e)
3255 (vector-reverse-copy! v 2 '#(1 2)))
3256 @result{} #(a b 2 1 e)
3257 @end example
3258
3259 @c EN
3260 It is ok to pass the same vector to @var{target} and @var{source};
3261 it always works even if the regions of source and destination are
3262 overlapping.
3263 @c JP
3264 @var{target}と@var{source}に同じベクタを指定しても構いません。
3265 コピー範囲が重なっていても問題なく動作します。
3266 @c COMMON
3267
3268 @example
3269 (rlet1 v (vector 'a 'b 'c 'd 'e)
3270 (vector-reverse-copy! v 1 v 1))
3271 @result{} #(a e d c b)
3272 @end example
3273 @end defun
3274
3275 @defun vector-unfold! f rvec start end seeds @dots{}
3276 @defunx vector-unfold-right! f rvec start end seeds @dots{}
3277 [R7RS vector]
3278 @c MOD scheme.vector
3279 @c EN
3280 Fill @var{rvec} starting from index @var{start} (inclusive) and
3281 ending at index @var{end} (exclusive), with the elements
3282 calculated by @var{f}.
3283
3284 The procedure @var{f} takes the number of seed values @var{seeds} @dots{}
3285 plus one arguments. The first argument is the current index,
3286 followed by seed values. The same number of values
3287 as the arguments must be returned from @var{f}; the first return value
3288 is used to fill the current element of @var{rvec}, and the rest of the values
3289 are used as the next seed values.
3290
3291 The result vector is filled from left to right by @code{vector-unfold!},
3292 and right to left by @code{vector-unfold-right!}.
3293 The return value is unspecified.
3294 @c JP
3295 @var{rvec}の、@var{start}から@var{end}の直前までの範囲を@var{f}が算出する
3296 新たな要素で埋めます。
3297
3298 @var{f}は、@var{seeds} @dots{}の数よりひとつ多い引数を取ります。
3299 最初の引数は現在のインデックスで、それにシード値が続きます。
3300 @var{f}は引数と同数の値を返します。最初の戻り値が@var{rvec}を埋めるのに使われ、
3301 残りの戻り値は新たなシード値として次の@var{f}の呼び出しに使われます。
3302
3303 結果のベクタは、@code{vector-unfold!}では左から右へ、
3304 @code{vector-unfold-right!}では右から左へと埋められます。
3305 戻り値はunspecifiedです。
3306 @c COMMON
3307
3308 @example
3309 (let1 rvec (vector 'a 'b 'c 'd 'e 'f)
3310 (vector-unfold! (^[i] (+ i 1)) rvec 1 4)
3311 rvec)
3312 @result{} #(a 2 3 4 e f)
3313
3314 (let1 rvec (vector 'a 'b 'c 'd 'e 'f)
3315 (vector-unfold-right! (^[i] (+ i 1)) rvec 1 4)
3316 rvec)
3317 @result{} #(a 2 3 4 e f)
3318
3319 (let1 rvec (vector 'a 'b 'c 'd 'e 'f)
3320 (vector-unfold! (^[i x] (values x (* x 2))) rvec 1 5 10)
3321 rvec)
3322 @result{} #(a 10 20 40 80 f)
3323
3324 (let1 rvec (vector 'a 'b 'c 'd 'e 'f)
3325 (vector-unfold! (^[i x] (values x (* x 2))) rvec 1 5 10)
3326 rvec)
3327 @result{} #(a 80 40 20 10 f)
3328 @end example
3329 @end defun
3330
3331 @c EN
3332 @subheading Vector conversion
3333 @c JP
3334 @subheading ベクタの変換
3335 @c COMMON
3336
3337 @defun reverse-vector->list vec :optional start end
3338 [R7RS vector]
3339 @c MOD scheme.vector
3340 @c EN
3341 Same as @code{(reverse (vector->list vec start end))}, but more efficient.
3342 @c JP
3343 @code{(reverse (vector->list vec start end))}と同じですが、より効率的です。
3344 @c COMMON
3345 @end defun
3346
3347 @node R7RS uniform vectors, R7RS sort, R7RS vectors, R7RS large
3348 @subsection @code{scheme.vector.@@} - R7RS uniform vectors
3349 @c NODE R7RSユニフォームベクタ, @code{scheme.vector.@@} - R7RSユニフォームベクタ
3350
3351 @deftp {Module} scheme.vector.@@
3352 @mdindex scheme.vector.base
3353 @mdindex scheme.vector.u8
3354 @mdindex scheme.vector.s8
3355 @mdindex scheme.vector.u16
3356 @mdindex scheme.vector.s16
3357 @mdindex scheme.vector.u32
3358 @mdindex scheme.vector.s32
3359 @mdindex scheme.vector.u64
3360 @mdindex scheme.vector.s64
3361 @mdindex scheme.vector.f32
3362 @mdindex scheme.vector.f64
3363 @mdindex scheme.vector.c64
3364 @mdindex scheme.vector.c128
3365 @c EN
3366 @code{@@} is actually one of @code{u8}, @code{s8}, @code{u16}, @code{s16},
3367 @code{u32}, @code{s32}, @code{u64}, @code{s64}, @code{f32},
3368 @code{f64}, @code{c64} or @code{c128}.
3369 (Gauche's @code{gauche.uvector} module also provides @code{f16}
3370 and @code{c32} vectors.)
3371 @c JP
3372 @code{@@}は次のいずれかに置き換えて読んでください:
3373 @code{u8}, @code{s8}, @code{u16}, @code{s16},
3374 @code{u32}, @code{s32}, @code{u64}, @code{s64}, @code{f32},
3375 @code{f64}, @code{c64}, @code{c128}。
3376 (Gaucheの@code{gauche.uvector}モジュールはさらに@code{f16}と@code{c32}を
3377 提供します)。
3378 @c COMMON
3379
3380 @c EN
3381 These modules provides vectors that can hold specific range of numeric
3382 values. In Gauche we use @emph{packed} representation, meaning
3383 numbers are tightly stored in consecutive memory region.
3384 @c JP
3385 これらのモジュールは限られた範囲の数値だけを格納するベクタを提供します。
3386 Gaucheでは、数値は連続したメモリ領域に@emph{詰められて}格納されます。
3387 @c COMMON
3388
3389 @c EN
3390 Additionally, @code{scheme.vector.base} module exports basic procedures,
3391 @code{make-@@vector}, @code{@@vector}, @code{@@vector?}, @code{@@vector-length},
3392 @code{@@vector-ref}, @code{@@vector-set!},
3393 @code{@@vector->list}, @code{list->@@vector}, @code{@@?},
3394 for @code{@@} being over all element types.
3395 @c JP
3396 また、@code{scheme.vector.base}モジュールは全ての要素型についての
3397 基本手続き、つまり次の手続きの@code{@@}を全ての基本型で置換した手続きをまとめて
3398 エクスポートしています:
3399 @code{make-@@vector}、@code{@@vector}、@code{@@vector?}
3400 @code{@@vector-length}、@code{@@vector-ref}、@code{@@vector-set!}、
3401 @code{@@vector->list}、@code{list->@@vector}、@code{@@?}
3402 @c COMMON
3403
3404 @c EN
3405 The @code{gauche.uvector} module is a superset of these modules, and
3406 all procedures are described there. @xref{Uniform vectors} for the
3407 details.
3408 @c JP
3409 @code{gauche.uvector}モジュールはこれらのモジュールのスーパーセットで、
3410 このモジュールの全ての手続きはそちらで説明されています。
3411 @ref{Uniform vectors}を参照してください。
3412 @c COMMON
3413 @end deftp
3414
3415 @node R7RS sort, R7RS sets, R7RS uniform vectors, R7RS large
3416 @subsection @code{scheme.sort} - R7RS sort
3417 @c NODE R7RSソート, @code{scheme.sort} - R7RSソート
3418
3419 @deftp {Module} scheme.sort
3420 @mdindex scheme.sort
3421 @c EN
3422 Provides utilities to sort, and to work on sorted lists/vectors.
3423 This module is the same as @code{srfi.132}.
3424 @c JP
3425 ソートおよびソート済みのリストやベクタに関する手続きを提供します。
3426 このモジュールは@code{srfi.132}と同じです。
3427 @c COMMON
3428
3429 @c EN
3430 Gauche has built-in sort and merge procedures (@pxref{Sorting and merging}).
3431 This module has a bit different API. Notably, the ordering predicate
3432 comes first than the sequence to be sorted, and the procedures
3433 dealing with vectors uniformly support start/end arguments
3434 @c JP
3435 Gaucheは組み込みでソートとマージの手続きを用意していますが
3436 (@ref{Sorting and merging}参照)、
3437 このモジュールはAPIがちょっと異なります。特に、順序を決める述語が
3438 ソートすべきシーケンスより先に来ます。また、ベクタを扱う手続きは一様に
3439 start/end引数をサポートします。
3440 @c COMMON
3441
3442 @c EN
3443 This module also provide useful procedures working on sorted or
3444 partially sorted sequences.
3445 @c JP
3446 このモジュールはまた、(部分的に)ソートされた列に対する便利な手続きをいくつか
3447 定義しています。
3448 @c COMMON
3449 @end deftp
3450
3451 @defun list-sort elt< lis
3452 @defunx list-sort! elt< lis
3453 @defunx list-stable-sort elt< lis
3454 @defunx list-stable-sort! elt< lis
3455 [R7RS sort]
3456 @c MOD scheme.sort
3457 @c EN
3458 Sort elements in a list @var{lis} according to the ordering
3459 predicate @var{elt<}, which takes two elements from @var{lis}
3460 and returns true iff the first argument is strictly less
3461 than the second argument.
3462
3463 Returns a sorted list.
3464 The procedures with bang are linear update version. They are
3465 allowed, but not required, to reuse
3466 @var{lis}. The ``stable'' variation guarantees stable sort.
3467
3468 These are basically the same as Gauche's built-in
3469 @code{sort}, @code{sort!}, @code{stable-sort} and @code{stable-sort!},
3470 except the Gauche's version works on any sequences and takes
3471 arguments differently. (@xref{Sorting and merging}.)
3472 @c JP
3473 リスト@var{lis}の要素を比較述語@var{elt<}を使ってソートします。
3474 @var{elt<}は@var{lis}からの二要素を引数に取り、最初の引数が厳密に
3475 二番目の引数より小さい場合に限り@code{#t}を返します。
3476
3477 ソートされたリストが返されます。@code{!}つきの手続きは線形更新版で、
3478 @var{lis}を破壊的に再利用することが許されています (再利用しないかもしれません。
3479 したがって呼び出し側は常に戻り値を使う必要があります)。 ``stable'' がついている
3480 ものは安定ソートを行います。
3481
3482 これらは基本的にはGaucheの組み込み手続き
3483 @code{sort}、@code{sort!}、@code{stable-sort}、@code{stable-slot!}と
3484 同じです。ただ、Gaucheのは引数の順序と、任意のシーケンスを取れるところが異なります
3485 (@ref{Sorting and merging}参照)。
3486 @c COMMON
3487 @end defun
3488
3489
3490 @defun list-sorted? elt< lis
3491 [R7RS sort]
3492 @c MOD scheme.sort
3493 @c EN
3494 Returns true iff the list @var{list} is sorted according to the
3495 ordering predicate @var{elt<}.
3496
3497 See also @code{sorted?} in @ref{Sorting and merging}.
3498 @c JP
3499 リスト@var{list}が、順序述語@var{elt<}での比較において既にソート済みであれば
3500 真を、そうでなければ偽を返します。
3501
3502 @ref{Sorting and merging}の@code{sorted?}も参照。
3503 @c COMMON
3504 @end defun
3505
3506
3507 @defun list-merge elt< lis1 lis2
3508 @defunx list-merge! elt< lis1 lis2
3509 [R7RS sort]
3510 @c MOD scheme.sort
3511 @c EN
3512 Given two sorted lists @var{lis1} and @var{lis2}, returns
3513 a new sorted list according to the ordering predicate @var{elt<}.
3514
3515 Note that @code{list-merge!} works in-place, that is, all the pairs
3516 in @var{lis1} and @var{lis2} are reused.
3517
3518 See also @code{merge} and @var{merge!} in @ref{Sorting and merging}.
3519 @c JP
3520 ソート済みの二つのリスト@var{lis1}と@var{lis2}を合わせて、
3521 ソート済みのひとつのリストにして返します。要素は順序述語@var{elt<}で比較されます。
3522
3523 @code{list-merge!}は、結果のリストを得るために@var{lis1}と@var{lis2}の
3524 メモリを破壊的に再利用します。
3525
3526 @ref{Sorting and merging}の@code{merge}および@code{merge!}も参照。
3527 @c COMMON
3528 @end defun
3529
3530 @defun vector-sort elt< vec :optional start end
3531 @defunx vector-stable-sort elt< vec :optional start end
3532 [R7RS sort]
3533 @c MOD scheme.sort
3534 @c EN
3535 Sort elements in a vector @var{vec} according to the ordering
3536 predicate @var{elt<}, which takes two elements from @var{vec}
3537 and returns true iff the first argument is strictly less
3538 than the second argument. Returns a fresh sorted vector.
3539 The ``stable'' variation guarantees stable sort.
3540 @c JP
3541 ベクタ@var{vec}の要素を、順序述語@var{elt<}によってソートします
3542 @var{elt<}は@var{vec}の要素から2つの値を引数として取り、最初の引数が
3543 厳密に2番目の引数より小さい場合に真の値を、そうでなければ@code{#f}を返す手続きです。
3544 返り値はソートされた新たなベクタです。
3545 `stable'がついている手続きは安定ソートが保証されます。
3546 @c COMMON
3547
3548 @c EN
3549 When the optional @var{start} and/or @var{end} arguments are given,
3550 only the portion from @var{start} (inclusive) and
3551 @var{end} (exclusive) of @var{vec} are looked at.
3552 The result vector's length is @code{@var{end} - @var{start})}.
3553 When @var{end} is omitted, the length of @var{vec} is assumed.
3554 @c JP
3555 省略可能な@var{start}/@var{end}引数は、@var{vec}中のソートすべき範囲の
3556 インデックスを指定します。@var{start}は開始インデックス (範囲に含まれる)、
3557 @var{end}は終了インデックス (範囲に含まれない) です。
3558 返り値のベクタの長さは@code{@var{end} - @var{start})}になります。
3559 @var{end}が省略された場合は@var{vec}の最後までが対象になります。
3560 @c COMMON
3561
3562 @c EN
3563 See also @code{sort} and @code{stable-sort} in @ref{Sorting and merging}.
3564 @c JP
3565 @ref{Sorting and merging}の@code{sort}と@code{stable-sort}も参照。
3566 @c COMMON
3567 @end defun
3568
3569 @defun vector-sort! elt< vec :optional start end
3570 @defunx vector-stable-sort! elt< vec :optional start end
3571 [R7RS sort]
3572 @c MOD scheme.sort
3573 @c EN
3574 Sort elements ``in-place'' in a vector @var{vec} according to the ordering
3575 predicate @var{elt<}, which takes two elements from @var{vec}
3576 and returns true iff the first argument is strictly less
3577 than the second argument. Upon successful return,
3578 @var{vec}'s elements are sorted. Returns unspecified value; the
3579 caller must rely on the side effect.
3580 @c JP
3581 ベクタ@var{vec}の要素を、順序述語@var{elt<}を使って「その場で」ソートします。
3582 @var{elt<}は@var{vec}の要素から2つの値を引数として取り、最初の引数が
3583 厳密に2番目の引数より小さい場合に真の値を、そうでなければ@code{#f}を返す手続きです。
3584 手続きが返った時点で、@var{vec}の内容が書き換わっています。
3585 戻り値は未規定です。呼び出しは副作用のために呼ばれます。
3586 @c COMMON
3587
3588 @c EN
3589 Note that most of recent APIs with @code{!} is @emph{linear updating},
3590 meaning it may or may not change the argument, and the caller must use
3591 the return value. On the other hand, @code{vector-sort!} and
3592 @code{vector-stable-sort!} are purely for side effects,
3593 and use minimal space
3594 (@code{vector-sort!} doesn't need extra space, while
3595 @code{vector-stable-sort!} may allocate a temporary storage up to
3596 the size of the input).
3597 @c JP
3598 註: 最近追加された名前に@code{!}がつくAPIには、@emph{線形更新}であるものが多いです。
3599 線形更新の場合、引数が更新されるかどうかは不定であり、呼び出し側は返り値を使わねばなりません。
3600 一方、@code{vector-sort!}と@code{vector-stable-sort!}は純粋に副作用のために呼び、
3601 必要最低限のメモリを使うことが保証されています。
3602 (@code{vector-sort!}は固定メモリ量で実行されます。
3603 @code{vector-stable-sort!}は入力長とおなじ一時領域を使うかもしれません)。
3604 @c COMMON
3605
3606 @c EN
3607 When the optional @var{start} and/or @var{end} arguments are given,
3608 only the portion from @var{start} (inclusive) and
3609 @var{end} (exclusive) of @var{vec} are sorted; other elements
3610 will remain intact.
3611 When @var{end} is omitted, the length of @var{vec} is assumed.
3612 @c JP
3613 省略可能な@var{start}/@var{end}引数は、@var{vec}中のソートすべき範囲の
3614 インデックスを指定します。@var{start}は開始インデックス (範囲に含まれる)、
3615 @var{end}は終了インデックス (範囲に含まれない) です。
3616 返り値のベクタの長さは@code{@var{end} - @var{start})}になります。
3617 @var{end}が省略された場合は@var{vec}の最後までが対象になります。
3618 @c COMMON
3619
3620 @c EN
3621 See also @code{sort!} and @code{stable-sort!} in @ref{Sorting and merging}.
3622 @c JP
3623 @ref{Sorting and merging}の@code{sort!}と@code{stable-sort!}も参照。
3624 @c COMMON
3625 @end defun
3626
3627 @defun vector-sorted? elt< vec :optional start end
3628 [R7RS sort]
3629 @c MOD scheme.sort
3630 @c EN
3631 Returns true iff @var{vec} between @var{start} (inclusive)
3632 and @var{end} (exclusive) is sorted according to the ordering
3633 predicate @var{elt<}. If @var{start} and/or @var{end} is/are omitted,
3634 0 and the length of @var{vec} are assumed, respectively.
3635 @c JP
3636 @var{vec}の@var{start}番目 (含まれる) から @var{end}番目 (含まれない) までの
3637 要素が、順序述語@var{elt<}に照らしてソートされていれば@code{#t}を、
3638 そうでなければ@code{#f}を返します。
3639 @var{start}/@var{end}引数が省略された場合はそれぞれ0と@var{vec}の長さが使われます。
3640 @c COMMON
3641
3642 @c EN
3643 See also @code{sorted?} in @ref{Sorting and merging}.
3644 @c JP
3645 @ref{Sorting and merging}の@code{sorted?}も参照。
3646 @c COMMON
3647 @end defun
3648
3649
3650 @defun vector-merge elt< vec1 vec2 :optional start1 end1 start2 end2
3651 @defunx vector-merge! elt< rvec vec1 vec2 :optional rstart start1 end1 start2 end2
3652 [R7RS sort]
3653 @c MOD scheme.sort
3654 @c EN
3655 Merge two sorted vectors @var{vec1} and @var{vec2}
3656 into one vector, according to the
3657 ordering predicate @var{elt<}.
3658 @c JP
3659 ソート済みのベクタ@var{vec1}と@var{vec2}の要素を合わせて
3660 ひとつのソート済みのベクタを作ります。要素の並びは順序述語@var{elt<}で決まります。
3661 @c COMMON
3662
3663 @c EN
3664 The optional argument @var{start1} and @var{end1} restricts @var{vec1}'s
3665 portion to be looked at, and @var{start2} and @var{end2}
3666 restricts @var{vec2}'s portion to be looked at. Each is integer index
3667 to the corresponding vector, and the start index is inclusive, while
3668 the end index is exclusive.
3669 @c JP
3670 省略可能な引数@var{start1}、@var{end1}は@var{vec1}内の対象とする範囲を、
3671 @var{start2}、@var{end2}は@var{vec2}内の対象とする範囲を制限します。
3672 各引数は対応するベクタへの整数インデックスであり、start側は含まれ、end側は含まれません。
3673 @c COMMON
3674
3675 @c EN
3676 The functional version @code{vector-merge} allocates a fresh vector
3677 to hold the result, and returns it.
3678 @c JP
3679 関数的なバージョン@code{vector-merge}はマージ結果を格納する新たなベクタを
3680 作って返します。
3681 @c COMMON
3682
3683 @c EN
3684 The side-effecting version @code{vector-merge!} uses @var{rvec}.
3685 to hold the result.
3686 The procedure doesn't return a meaningful value.
3687 The optional @var{rstart} argument specifies
3688 the index of @var{rvec} from which the result is filled; the default
3689 is 0. The length of @var{rvec} must be greater than
3690 @var{rstart} + (@var{end1}-@var{start1}) + (@var{end2}-@var{start2}).
3691 @c JP
3692 副作用バージョン@code{vector-merge!}は、@var{rvec}引数に渡されるベクタに結果を格納します。
3693 戻り値は未規定です。省略可能引数@var{rstart}は@var{rvec}のどこから結果を格納するかの
3694 インデックスを指定し、省略時は0です。
3695 @var{rvec}の長さは
3696 @var{rstart} + (@var{end1}-@var{start1}) + (@var{end2}-@var{start2}) より
3697 大きくなければなりません。
3698 @c COMMON
3699 @end defun
3700
3701 @defun list-delete-neighbor-dups elt= lis
3702 @defunx list-delete-neighbor-dups! elt= lis
3703 @defunx vector-delete-neighbor-dups elt= vec :optional start end
3704 @defunx vector-delete-neighbor-dups! elt= vec :optional start end
3705 [R7RS sort]
3706 @c MOD scheme.sort
3707 @c EN
3708 From the given list @var{lis} or vector @var{vec},
3709 these procedures delete adjacent duplicate elements. Equivalence
3710 is checked by @var{elt=} procedure.
3711 @c JP
3712 リスト@var{lis}やベクタ@var{vec}の要素を順にスキャンし、
3713 隣り合う要素が重複していたらその一方を取り除きます。
3714 要素が等しいかどうかは@var{elt=}手続きで判断します。
3715 @c COMMON
3716
3717 @example
3718 (list-delete-neighbor-dups eq? '(m i s s i s s i p p i))
3719 @result{} (m i s i s i p i)
3720 @end example
3721
3722 @c EN
3723 The non-destructive versions @code{list-delete-neighbor-dups} and
3724 @code{vector-delete-neighbor-dups} returns a freshly allocated
3725 list and vector, respectively.
3726 @c JP
3727 非破壊的バージョン@code{list-delete-neighbor-dups}と
3728 @code{vector-delete-neighbor-dups}では、結果を格納するリストやベクタが新たに
3729 作られて返されます。
3730 @c COMMON
3731
3732 @c EN
3733 The destructive @code{list-delete-neighbor-dups!} works in-place,
3734 reusing pairs of @var{lis}. No allocation will be done.
3735 It is a single-pass iterative algorithm, and the first cell of input
3736 is the first cell of output (except when the input is an empty list).
3737 @c JP
3738 破壊的バージョン@code{list-delete-neighbor-dups!}はアロケーションを行わず、
3739 @var{lis}に含まれるペアを再利用して結果を格納します。
3740 これは1パスの繰り返しアルゴリズムを使い、入力が空リストでなければ、入力の最初のセルは
3741 出力の最初のセルになります。
3742 @c COMMON
3743
3744 @c EN
3745 The destructive @code{vector-delete-neighbor-dups!} has a bit different
3746 interface. It updates @var{vec} in-place, but since we can't change
3747 the length of the vector, it gathers the result from the beginning of
3748 the @var{vec}, then returns the next index @var{newend}
3749 of @var{vec}---that is,
3750 after calling this procedure, @code{[@var{start}, @var{newend})}
3751 holds the result.
3752 The elements between @code{[@var{newend}, @var{end})} will remain intact.
3753 @c JP
3754 破壊的バージョン@code{vector-delete-neighbor-dups!}はちょっと特殊なインタフェースです。
3755 @var{vec}を破壊的に変更して結果を格納しますが、ベクタの長さを変えることはできないので、
3756 結果は@var{vec}の先頭に詰められ、最終的に結果が格納された次のインデックス@var{newend}
3757 が返り値になります。
3758 つまり、この手続きを呼んだ後では、@var{vec}のうち@var{start}から@var{newend}
3759 までに結果が格納されている状態になっています。
3760 それ以外の@var{vec}の要素は変更されません。
3761 @c COMMON
3762
3763 @c EN
3764 The optional @var{start} and @var{end} arguments limits the region
3765 of @var{vec} to be looked at.
3766 @c JP
3767 省略可能な@var{start}、@var{end}引数は、@var{vec}内で対象とする範囲を
3768 整数インデックスで指定します。
3769 @c COMMON
3770
3771 @example
3772 (vector-delete-neighbor-dups eq? '#(a a a b b c c d d e e f f) 3 10)
3773 @result{} #(b c d e)
3774
3775 (let1 v '#(a a a b b c c d d e e f f)
3776 (cons (vector-delete-neighbor-dups! eq? v 3 10) v))
3777 @result{} (7 . #(a a a b c d e d d e e f f))
3778 @end example
3779
3780 @c EN
3781 Note: The @code{gauche.sequence} module provides neighbor duplicate
3782 deletion on generic sequences. Those procedures are implemented by
3783 the generic versions as shown below. @xref{Other operations over sequences},
3784 for the details.
3785 @c JP
3786 註: @code{gauche.sequsence}モジュールではジェネリックなシーケンスについて
3787 隣接要素の重複削除操作を提供しています。@code{scheme.sort}の各手続きに対応する
3788 ジェネリックなバージョンは次のとおりです。
3789 詳しくは@ref{Other operations over sequences}を参照。
3790 @c COMMON
3791 @table @code
3792 @item list-delete-neighbor-dups
3793 @code{delete-neighbor-dups}
3794 @item list-delete-neighbor-dups!
3795 @code{delete-neighbor-dups-squeeze!}
3796 @item vector-delete-neighbor-dups
3797 @code{delete-neighbor-dups}
3798 @item vector-delete-neighbor-dups!
3799 @code{delete-neighbor-dups!}
3800 @end table
3801 @end defun
3802
3803 @defun vector-select! elt< vec k :optional start end
3804 [R7RS sort]
3805 @c MOD scheme.sort
3806 @c EN
3807 Select @var{k}-th smallest element in @var{vec} according to the
3808 ordering predicate @var{elt<}. @var{K} is zero based, i.e. 0 means
3809 the smallest. The optional @var{start} and @var{end} arguments
3810 limits the range of @var{vec} to be looked at, and defaulted to
3811 0 and the length of @var{vec}, respectively.
3812 @var{K} must satisfy @code{@var{start} <= @var{k} < @var{end}}.
3813 @c JP
3814 @var{vec}の要素のうち、@var{k}番目に小さい要素を返します。
3815 大小比較は順序述語@var{elt<}で判断されます。
3816 @var{k}はゼロ起点で、つまり0なら最も小さな要素が返されます。
3817 省略可能な@var{start}、@var{end}引数は@var{vec}内の対象とする範囲を限定します。
3818 @code{0 <= @var{k} < (@var{end}-@var{start})} でなければなりません。
3819 @c COMMON
3820
3821 @c EN
3822 This procedure runs in O(n) time in average, and requires no extra stroage.
3823 This procedure may partially modify @var{vec}.
3824 @c JP
3825 この手続きは平均@code{O(n)}で走り、余分なメモリをアロケートしません。
3826 この手続きの実行中に@var{vec}の一部は変更されます。
3827 @c COMMON
3828 @end defun
3829
3830 @defun vector-separate! elt< vec k :optional start end
3831 [R7RS sort]
3832 @c MOD scheme.sort
3833 @c EN
3834 Find @var{k}-th smallerst element in @var{vec} (pivot) between
3835 between @var{start} and @var{end}, according to the ordering
3836 predicate @var{elt<}, then rearrange elements
3837 between @var{start} and @var{end} so that
3838 elements smaller than the pivot comes between @code{@var{start}} and
3839 @code{@var{start} + @var{k}}, and the rest of the elements come
3840 afterwards. When omitted, @var{start} is 0 and @var{end} is
3841 the length of the @var{vec}.
3842 @c JP
3843 @var{vec}中のインデックス@var{start}から@var{end}までの範囲で、
3844 @var{k}番目に小さい要素(ピボット)を見つけ、その範囲の要素を、
3845 「@code{@var{start}}から@code{@var{start} + @var{k}}までには
3846 ピボットより小さい要素、その後にピボット、そしてピボットより大きい要素」
3847 と言う具合に並べ替えます。大小比較は述語@var{elt<}に従います。
3848 @var{start}、@var{end}が省略された場合はそれぞれ0と@var{vec}の長さが使われます。
3849 @c COMMON
3850
3851 @c EN
3852 This can be used as a building block for in-place divide-and-conquer
3853 algorithms. Runs in O(n) time.
3854 @c JP
3855 これは、アロケーションを行わない「分割統治」型のアルゴリズムの部品として使えます。
3856 O(n)時間で完了します。
3857 @c COMMON
3858 @end defun
3859
3860 @defun vector-find-median elt< vec knil :optional mean
3861 @defunx vector-find-median! elt< vec knil :optional mean
3862 [R7RS sort]
3863 @c MOD scheme.sort
3864 @c EN
3865 Find median value of elements in @var{vec}, when ordered by
3866 the ordering predicate @var{elt<}. Non-destructive version
3867 @code{vector-find-median} runs in O(n) time. The destructive
3868 version @code{vector-find-median!} is specified to leave
3869 @var{vec} sorted, so it runs in O(n log n).
3870 @c JP
3871 @var{vec}の要素を比較述語@var{elt<}に従って並べた時の中央値を返します。
3872 非破壊バージョン@code{vector-find-median}はO(n)時間で走ります。
3873 破壊バージョン@code{vector-find-median!}は、副作用として
3874 @var{vec}が完全にソートされた状態になると規定されているので、O(n log n)時間かかります。
3875 @c COMMON
3876
3877 @enumerate
3878 @item
3879 @c EN
3880 If @var{vec} is empty, @var{knil} is returned. This is the only case
3881 @var{knil} is used.
3882 @c JP
3883 @var{vec}が空なら、@var{knil}が返されます。@var{knil}が使われるのはこの場合のみです。
3884 @c COMMON
3885 @item
3886 @c EN
3887 If @var{vec} has odd number of elements, the element falls in the exactly
3888 the midpoint when ordered, is returned.
3889 @c JP
3890 @var{vec}の要素が奇数個なら、順序で並べたときに中央に来る要素が返されます。
3891 @c COMMON
3892 @item
3893 @c EN
3894 If @var{vec} has even number of elements, the two elements closest to
3895 the midpoint is chosen and passed to the procedure @var{mean}, and
3896 its result is returned. The default of @var{mean} is an arithmetic
3897 mean of numbers.
3898 @c JP
3899 @var{vec}の要素が偶数個の場合は、中央に最も近い二つの要素が選びだされ、
3900 それが手続き@var{mean}に渡され、その結果が返り値となります。
3901 @var{mean}が省略された場合は、二つの数値の算術平均が使われます。
3902 @c COMMON
3903 @end enumerate
3904
3905 @example
3906 (vector-find-median < #() 0)
3907 @result{} 0
3908
3909 (vector-find-median < #(78 61 19 38 51) 0)
3910 @result{} 51
3911
3912 (vector-find-median < #(78 61 19 38 51 52) 0)
3913 @result{} 103/2
3914 @end example
3915 @end defun
3916
3917 @node R7RS sets, R7RS character sets, R7RS sort, R7RS large
3918 @subsection @code{scheme.set} - R7RS sets
3919 @c NODE R7RSセット, @code{scheme.set} - R7RSセット
3920
3921 @deftp {Module} scheme.set
3922 @mdindex scheme.set
3923 @c EN
3924 Sets and bags are unordered collection of Scheme values.
3925 A set doesn't count duplicates; if you add an item
3926 which is already in a set, you still have one item of the kind.
3927 A bag counts duplicates; if you add an item which
3928 is already in a bag, you have two items of the kind.
3929 @c JP
3930 セットとバッグは、Scheme値の順序づけのないコレクションです。
3931 セットは重複を考慮しません。既にセット中にある要素をさらに追加しても、
3932 その要素は依然として一つだけセット中にあると認識されます。
3933 一方、バッグは重複を数えます。既にバッグ中にひとつだけある要素と同じものを
3934 追加すると、バッグ中のその要素は二つと数えられます。
3935 @c COMMON
3936
3937 @c EN
3938 To check whether the items are ``the same'', sets and bags
3939 takes a comparator at construction time. The comparator
3940 doesn't need to have an ordering predicate (we don't need
3941 to order the elements) but has to have a hash function.
3942 @xref{Basic comparators}, for the details of comparators.
3943 @c JP
3944 要素が「同じ」であるかどうかの判定のため、セットとバッグは構築時に
3945 比較器を取ります。比較器は順序手続きを持っていなくても構いません
3946 (要素の順序づけは必要ありません)が、ハッシュ手続きは持っている必要があります。
3947 比較器について詳しくは@ref{Basic comparators}を参照してください。
3948 @c COMMON
3949
3950 @c EN
3951 This module is originally specified as @code{srfi.113}, and then
3952 incorporated to R7RS large.
3953 @c JP
3954 このモジュールは当初@code{srfi.113}として定義され、のちにR7RS largeに
3955 採用されました。
3956 @c COMMON
3957
3958 @c EN
3959 As a Gauche's extension, sets and bags implement collection protocol
3960 (@pxref{Collection framework}, for the details), and generic collection
3961 operations can be applied.
3962 @c JP
3963 Gauche独自拡張として、セットやバッグはコレクションプロトコルを実装しており、
3964 汎用のコレクション操作が適用できます
3965 (@ref{Collection framework}参照)。
3966 @c COMMON
3967
3968 @example
3969 (coerce-to <list> (set eq-comparator 'a 'b 'a 'b))
3970 @result{} (a b) ; @r{order may differ}
3971
3972 (coerce-to <list> (bag eq-comparator 'a 'b 'a 'b))
3973 @result{} (a a b b) ; @r{order may differ}
3974 @end example
3975 @end deftp
3976
3977 @subheading Constructors
3978
3979 @defun set comparator elt @dots{}
3980 @defunx bag comparator elt @dots{}
3981 [R7RS set]
3982 @c MOD scheme.set
3983 @c EN
3984 Creates a new set and bag from given elements @var{elt} @dots{}.
3985 Given @var{comparator} will be used to compare equality of elements.
3986 @c JP
3987 与えられた@var{elt} @dots{}を要素にもつセットとバッグをそれぞれ作って返します。
3988 比較器@var{comparator}は要素の等価性を判定するのに使われます。
3989 @c COMMON
3990
3991 @example
3992 (set->list (set eq-comparator 'a 'b 'a 'b))
3993 @result{} (a b)
3994
3995 (bag->list (bag eq-comparator 'a 'b 'a 'b))
3996 @result{} (a a b b)
3997 @end example
3998 @end defun
3999
4000 @defun set-unfold stop? mapper successor seed comparator
4001 @defunx bag-unfold stop? mapper successor seed comparator
4002 [R7RS set]
4003 @c MOD scheme.set
4004 @c EN
4005 Procedurally creates a set or a bag. The first three
4006 arguments, @var{stop?}, @var{mapper} and @var{successor},
4007 are all procedures that takes one argument, the current seed value.
4008 It may be easier to know their types:
4009 @c JP
4010 手続的にセットとバッグを作ります。
4011 最初の3つの引数@var{stop?}、@var{mapper}、@var{successor}は
4012 いずれも現在のシード値を唯一の引数に取る手続きです。
4013 型を考えるとわかりやすいでしょう:
4014 @c COMMON
4015
4016 @example
4017 seed :: Seed
4018 stop? :: Seed -> Boolean
4019 mapper :: Seed -> ElementType
4020 successor :: Seed -> Seed
4021 @end example
4022
4023 @c EN
4024 The @var{stop?} procedure takes the current seed value and
4025 returns a boolean value - if it is true, iteration stops.
4026 @c JP
4027 @var{stop?}手続きは現在のシード値を見て、繰り返しを停止すべきなら@code{#t}を、
4028 そうでなければ@code{#f}を返す手続きです。
4029 @c COMMON
4030
4031 @c EN
4032 The @var{mapper} procedure takes the current seed value
4033 and returns an item, which is to be included in the resulting set or bag.
4034 @c JP
4035 @var{mapper}手続きは現在のシード値から、セットやバッグに加えるべき要素を生成する
4036 手続きです。
4037 @c COMMON
4038
4039 @c EN
4040 The @var{successor} procedure takes the current seed value
4041 and returns the next seed value.
4042 @c JP
4043 @var{successor}手続きは現在のシード値から次のシード値を計算する手続きです。
4044 @c COMMON
4045
4046 @c EN
4047 And the @var{seed} argument gives the initial seed value.
4048 @c JP
4049 そして@var{seed}引数がシード値の初期値を与えます。
4050 @c COMMON
4051
4052 @example
4053 (set->list (set-unfold (^s (= s 75))
4054 integer->char
4055 (^s (+ s 1))
4056 65
4057 eqv-comparator))
4058 @result{} (#\D #\H #\A #\E #\I #\J #\B #\F #\C #\G)
4059 @end example
4060 @end defun
4061
4062 @c EN
4063 @subheading Predicates
4064 @c JP
4065 @subheading 述語
4066 @c COMMON
4067
4068 @defun set-contains? set obj
4069 @defunx bag-contains? bag obj
4070 [R7RS set]
4071 @c MOD scheme.set
4072 @c EN
4073 Check if @var{obj} is in the set or the bag.
4074 @c JP
4075 @var{obj}がそれぞれセット/バッグであることを検査します。
4076 @c COMMON
4077 @end defun
4078
4079 @defun set-empty? set
4080 @defunx bag-empty? bag
4081 [R7RS set]
4082 @c MOD scheme.set
4083 @c EN
4084 Returns @code{#t} iff the given set or bag is empty.
4085 @c JP
4086 セット/バッグが空なら@code{#t}を、そうでなければ@code{#f}を返します。
4087 @c COMMON
4088 @end defun
4089
4090 @defun set-disjoint? set1 set2
4091 @defunx bag-disjoint? bag1 bag2
4092 [R7RS set]
4093 @c MOD scheme.set
4094 @c EN
4095 Returns @code{#t} iff the given arguments (sets or bags) don't have
4096 common items. Both arguments must have the same comparator---otherwise
4097 an error is signaled.
4098 @c JP
4099 引数のセット/バッグがそれぞれ共通要素を持たなければ@code{#t}を、持っていれば@code{#f}を
4100 返します。引数のセット/バッグは同じ比較器を持っていなければならす、そうでなければ
4101 エラーが投げられます。
4102 @c COMMON
4103 @end defun
4104
4105 @c EN
4106 @subheading Accessors
4107 @c JP
4108 @subheading アクセサ
4109 @c COMMON
4110
4111 @defun set-member set obj default
4112 @defunx bag-member bag obj default
4113 [R7RS set]
4114 @c MOD scheme.set
4115 @c EN
4116 Returns an element in the given set or bag which is equal to @var{obj}
4117 in terms of the set's or the bag's comparator. If no such element is
4118 found, @var{default} will be returned.
4119 @c JP
4120 @var{obj}と等しい (セットやバッグの比較器を使って) 要素がセット/バッグにあれば
4121 その要素を、無ければ@var{default}を返します。
4122 @c COMMON
4123
4124 @c EN
4125 Note that the returned object doesn't need to be ``the same''
4126 as @var{obj} in a usual sense. See the following example:
4127 @c JP
4128 比較器の選び方によっては、要素が見つかっても返される値が@var{obj}と通常の意味で「等しい」
4129 とは限りません。次の例を参照。
4130 @c COMMON
4131
4132 @example
4133 (let1 s (set string-ci-comparator "abc" "def")
4134 (set-member s "ABC" #f))
4135 @result{} "abc"
4136 @end example
4137 @end defun
4138
4139 @defun set-element-comparator set
4140 @defunx bag-element-comparator bag
4141 [R7RS set]
4142 @c MOD scheme.set
4143 @c EN
4144 Returns the comparator used to compare the elements for the set or the bag.
4145 @c JP
4146 セット/バッグの比較器を返します。
4147 @c COMMON
4148 @end defun
4149
4150 @c EN
4151 @subheading Updaters
4152 @c JP
4153 @subheading アップデータ
4154 @c COMMON
4155
4156 @defun set-adjoin set elt @dots{}
4157 @defunx bag-adjoin bag elt @dots{}
4158 [R7RS set]
4159 @c MOD scheme.set
4160 @c EN
4161 Returns a newly created set or bag that contains all the elements
4162 in the original set/bag, plus given elements. The new set/bag's
4163 comparator is the same as the original set/bag's one.
4164 @c JP
4165 元の@var{set}/@var{bag}に、引数に与えられた@var{elt} @dots{}の要素を加えた
4166 セット/バッグを新たに作って返します。作られるセット/バッグの比較器は
4167 元の@var{set}/@var{bag}の比較器と同じになります。
4168 @c COMMON
4169 @end defun
4170
4171 @defun set-replace set elt
4172 @defunx bag-replace bag elt
4173 [R7RS set]
4174 @c MOD scheme.set
4175 @c EN
4176 Returns a newly created set/bag with the same comparator with
4177 the original set/bag, and the same elements, except that the elements
4178 equal to @var{elt} (in terms of set/bag's comparator) is replaced
4179 by @var{elt}. If the original set/bag doesn't contain an element
4180 equal to @var{elt}, the original one is returned.
4181 @c JP
4182 @var{set}/@var{bag}の要素のうち、@var{elt}と等しい
4183 (セット/バッグの比較器の意味で)要素があれば、元の要素を除いて@var{elt}を追加した
4184 セット/バッグを新たに作って返します。@var{elt}と等しい要素が元のセット/バッグに
4185 無ければ元のセット/バッグがそのまま返されます。
4186 @c COMMON
4187
4188 @example
4189 (let ((s (set string-ci-comparator "ABC" "def")))
4190 (set->list (set-replace s "abc")))
4191 @result{} ("abc" "def")
4192 @end example
4193 @end defun
4194
4195 @defun set-delete set elt @dots{}
4196 @defunx bag-delete bag elt @dots{}
4197 [R7RS set]
4198 @c MOD scheme.set
4199 @c EN
4200 Returns a newly created set or bag that has the same comparator
4201 and the same elements in the original set/bag, except that the
4202 item which is equal to @var{elt}.
4203 @c JP
4204 元の@var{set}/@var{bag}の要素から、@var{elt} @dots{}に等しいもの以外を
4205 要素に持つセット/バッグを作って返します。
4206 @c COMMON
4207 @end defun
4208
4209 @defun set-delete-all set elt-list
4210 @defunx bag-delete-all bag elt-list
4211 [R7RS set]
4212 @c MOD scheme.set
4213 @c EN
4214 Returns a newly created set or bag with the same comparator of
4215 the original set/bag, with the elements of the original set/bag
4216 except the ones listed in @var{elt-list}.
4217 @c JP
4218 元の@var{set}/@var{bag}の要素から、@var{elt-list}に含まれるもの以外を
4219 要素に持つセット/バッグを作って返します。
4220 @c COMMON
4221 @end defun
4222
4223 @defun set-adjoin! set elt @dots{}
4224 @defunx bag-adjoin! bag elt @dots{}
4225 @defunx set-replace! set elt
4226 @defunx bag-replace! bag elt
4227 @defunx set-delete! set elt @dots{}
4228 @defunx bag-delete! bag elt @dots{}
4229 @defunx set-delete-all! set elt-list
4230 @defunx bag-delete-all! bag elt-list
4231 [R7RS set]
4232 @c MOD scheme.set
4233 @c EN
4234 These are the linear update versions of their counterparts.
4235 It works just like the ones without @code{!}, except that
4236 the original set/bag @emph{may} be reused to produce the result,
4237 instead of new one being allocated.
4238 @c JP
4239 これらは、対応する(@code{!}を除いた名前の)手続きの線形更新版です。
4240 @code{!}のない版と同じ動作をしますが、結果を作るのに
4241 引数に渡されたセット/バッグを再利用するかもしれません。
4242 @c COMMON
4243
4244 @c EN
4245 Note that it's not guaranteed that the original
4246 set/bag is modified, so you should use the return value of them,
4247 instead of relying on the side effects.
4248 @c JP
4249 引数に渡したセット/バッグが必ず変更されるとは限らないので、
4250 呼出側は副作用に頼らず戻り値を結果として使う必要があります。
4251 @c COMMON
4252 @end defun
4253
4254 @defun set-search! set elt failure success
4255 @defunx bag-search! bag elt failure success
4256 [R7RS set]
4257 @c MOD scheme.set
4258 @c EN
4259 Lookup-and-modify procedures. The @var{failure} and @var{success}
4260 arguments are procedures.
4261 @c JP
4262 検索と変更を行う手続きです。@var{failure}と@var{success}引数は手続きです。
4263 @c COMMON
4264
4265 @c EN
4266 First, they search an item that matches @var{elt} in the given set/bag.
4267 If an item that matches @var{elt} is found, the @var{success} procedure
4268 is called with three arguments, as follows:
4269 @c JP
4270 まず、与えられたセット/バッグから@var{elt}に一致する要素が探されます。
4271 見つかった場合、@var{success}手続きが次のとおり3つの引数を伴って呼び出されます。
4272 @c COMMON
4273 @example
4274 (success item update remove)
4275 @end example
4276 @c EN
4277 wheras, @var{item} is the matched item in the set/bag.
4278 @c JP
4279 ここで@var{item}はset/bagのマッチした要素です。
4280 @c COMMON
4281
4282 @c EN
4283 The @var{update} argument is a procedure that takes two arguments,
4284 as @code{(update new-item retval)}. It returns two values:
4285 (1) A set/bag that are the same as the given one except
4286 that @var{item} is replaced with @var{new-item},
4287 and (2) @var{retval}.
4288
4289 The @var{remove} argument is a procedure that takes one argument,
4290 as @code{(remove retval)}. It returns two values:
4291 (1) A set/bag that are the same as the given one except
4292 @var{item} is removed, and (2) @var{retval}.
4293 @c JP
4294 @var{update}は引数を2つとる手続きで、@code{(update new-item retval)}のように
4295 呼ぶことができます。呼び出されると、2つの値を返します。
4296 (1) 元のセット/バッグの@var{item}を@var{new-item}に置き換えたセット/バッグ、
4297 (2) @var{retval}。
4298
4299 @var{remove}は引数を2つとる手続きで、@code{(remove retval)}のように
4300 呼ぶことができます。呼び出されると、2つの値を返します。
4301 (1) 元のセット/バッグから@var{item}が除かれたセット/バッグ、
4302 (2) @var{retval}。
4303 @c COMMON
4304
4305 @c EN
4306 If an item that matches @var{elt} is not found, the @var{failure} procedure
4307 is called with two arguments, as follows:
4308 @c JP
4309 @var{elt}に一致する要素が見つからなかった場合は、@var{failure}手続きが
4310 次のとおり2つの引数を伴って呼ばれます。
4311 @c COMMON
4312 @example
4313 (failure insert ignore)
4314 @end example
4315 @c EN
4316 The @var{insert} argument is a procedure that takes one argument,
4317 as @code{(insert retval)}. It returns two values:
4318 (1) a set/bag that has all the items in the given one plus @var{elt},
4319 and (2) @var{retval}.
4320
4321 The @var{ignore} argument is a procedure that takes one argument,
4322 as @code{(ignore retval)}. It returns two values:
4323 (1) the original set/bag, and (2) @var{retval}.
4324 @c JP
4325 @var{insert}引数はひとつの引数を取る手続きで、
4326 @code{(insert retval)}のように呼べます。これは二つの値を返します。
4327 (1)元のセット/バッグに@var{elt}を追加したセット/バッグ、(2)@var{retval}。
4328
4329 @var{ignore}引数はひとつの引数を取る手続きで、
4330 @code{(ignore retval)}のように呼べます。
4331 これは二つの値を返します。
4332 (1)元のセット/バッグ、(2)@var{retval}。
4333 @c COMMON
4334
4335 @c EN
4336 The original set/bag may be reused to produce the result by @var{update},
4337 @var{remove} and @var{insert} procedures.
4338 @c JP
4339 元のset/bagは、結果を格納するために
4340 @var{update}、@var{remove}、@var{insert}手続きによって再利用されるかもしれません。
4341 @c COMMON
4342
4343 @c EN
4344 The return values of @code{set-search!} and @code{bag-search!} is
4345 what either @var{success} or @var{failure} procedure returns.
4346 These caller-provided procedures should invoke the passed-in procedures
4347 (@var{update}, @var{remove}, @var{insert} or @var{ignore}) and return
4348 their results---which is a potentially modified set/bag
4349 (which may or may not be @code{eq?} to the passed one) and the @var{retval}.
4350 @c JP
4351 @var{set-search!}と@var{bag-search!}は、@var{success}もしくは@var{failure}が
4352 返した値をそのまま返します。これらの呼出側が渡す手続きは、
4353 それに渡される手続き(@var{update}, @var{remove}, @var{insert}, @var{ignore})の
4354 いずれかを呼び出し、その結果をそのまま返さねばなりません。
4355 従って全体の戻り値は、(変更されたかもしれない)セット/バッグと、@var{retval}ということに
4356 なります。
4357 @c COMMON
4358
4359 @c EN
4360 If there are more than one item that matches @var{elt} in a bag,
4361 @code{bag-search!} only invokes @var{success} for the first item
4362 it finds. You can recurse into @code{bag-search!} in the @var{success}
4363 procedure to visit all matching items. It is guaranteed that @var{success}
4364 and @var{failure} procedures are tail-called.
4365 @c JP
4366 もしバッグ中に@var{elt}に一致する要素が複数あった場合、@code{bag-search!}は
4367 最初の要素でのみ@var{success}を起動します。
4368 @var{success}手続きの中で@code{bag-search!}を再帰的に呼ぶことで
4369 全てのマッチする要素を処理することができます。@var{success}と@var{failure}は
4370 末尾呼び出しされることが保証されています。
4371 @c COMMON
4372 @end defun
4373
4374 @c EN
4375 @subheading The whole set
4376 @c JP
4377 @subheading セット全体
4378 @c COMMON
4379
4380 @defun set-size set
4381 @defunx bag-size bag
4382 [R7RS set]
4383 @c MOD scheme.set
4384 @c EN
4385 Returns the number of items in the set/bag.
4386 @c JP
4387 セット/バッグの中にある要素の数を返します。
4388 @c COMMON
4389 @end defun
4390
4391 @defun set-find pred set failure
4392 @defunx bag-find pred bag failure
4393 [R7RS set]
4394 @c MOD scheme.set
4395 @c EN
4396 Apply @var{pred} on each item in the set/bag, and returns the
4397 first item on which @var{pred} returns true. Since sets and bags
4398 are unordered, if there are more than one items that satisfy @var{pred},
4399 you won't know which one will be returned.
4400 @c JP
4401 @var{pred}をセット/バッグの各要素に順に適用し、@var{pred}が最初に真の値を返した
4402 要素を返します。セット/バッグに順序はないので、
4403 @var{pred}を満たす要素が複数あった場合にどれが買えされるかは不定です。
4404 @c COMMON
4405
4406 @c EN
4407 If there're no items that satisfy @var{pred}, a thunk @var{failure}
4408 is tail-called.
4409 @c JP
4410 @var{pred}を満たす要素がなかった場合は、引数を取らない手続き@var{failure}が
4411 末尾呼び出しされます。
4412 @c COMMON
4413
4414 @c EN
4415 NB: The API differs from @code{find} in @code{scheme.list} (built-in in Gauche),
4416 that @code{find} does not take @var{failure} procedure.
4417 @c JP
4418 註: このAPIは@code{scheme.list}で定義される@code{find} (Gaucheでは組み込み)
4419 と異なります。@code{find}は@var{failue}手続きを取りません。
4420 @c COMMON
4421 @end defun
4422
4423 @defun set-count pred set
4424 @defunx bag-count pred bag
4425 [R7RS set]
4426 @c MOD scheme.set
4427 @c EN
4428 Returns the number of items that satisfy @var{pred} in the set/bag.
4429 @c JP
4430 セット/バッグ中の@var{pred}を満たす要素の数を返します。
4431 @c COMMON
4432 @end defun
4433
4434 @defun set-any? pred set
4435 @defunx bag-any? pred bag
4436 [R7RS set]
4437 @c MOD scheme.set
4438 @c EN
4439 Returns @code{#f} iff any item in the set/bag satisfy @var{pred}.
4440 @c JP
4441 セット/バッグ中にひとつでも@var{pred}を満たす要素があれば@code{#t}を、
4442 そうでなければ@code{#f}を返します。
4443 @c COMMON
4444
4445 @c EN
4446 NB: It differs from @code{any} defined in @code{scheme.list} (built-in in Gauche)
4447 that @code{any} returns the true result of @var{pred}, while
4448 @code{set-any?} always returns a boolean value (hence the question mark).
4449 @c JP
4450 註: これは@code{scheme.list}で定義されている@code{any} (Gaucheでは組み込み)
4451 と異なります。@code{any}は@var{pred}が偽でない値を返したらそれをそのまま返しますが、
4452 @code{set-any?}は常に真偽値を返します (なのでクエスチョンマークがついています)。
4453 @c COMMON
4454 @end defun
4455
4456 @defun set-every? pred set
4457 @defunx bag-every? pred bag
4458 [R7RS set]
4459 @c MOD scheme.set
4460 @c EN
4461 Returns @code{#t} iff every item in the set/bag satisfy @var{pred}.
4462 @c JP
4463 セット/バッグ中の全ての要素が@var{pred}を満たせば@code{#t}を、
4464 そうでなければ@code{#f}を返します。
4465 @c COMMON
4466
4467 @c EN
4468 NB: It differs from @code{every} defined in @code{scheme.list} (built-in in Gauche)
4469 that @code{every} returns the last true result of @var{pred} when all the
4470 elements satisfy @var{pred}, while
4471 @code{set-every?} always returns a boolean value (hence the question mark).
4472 @c JP
4473 註: これは@code{scheme.list}で定義されている@code{every} (Gaucheでは組み込み)
4474 と異なります。@code{every}は全ての要素が@var{pred}を満たした場合、最後の@var{pred}の
4475 戻り値を返しますが、
4476 @code{set-every?}は常に真偽値を返します (なのでクエスチョンマークがついています)。
4477 @c COMMON
4478 @end defun
4479
4480 @c EN
4481 @subheading Mapping and folding
4482 @c JP
4483 @subheading マップと畳み込み
4484 @c COMMON
4485
4486 @defun set-map comparator proc set
4487 @defunx bag-map comparator proc bag
4488 [R7RS set]
4489 @c MOD scheme.set
4490 @c EN
4491 Create and return a new set/bag with the comparator @var{comparator},
4492 whose items are calculated by applying @var{proc} to each element
4493 in the original set/bag.
4494 @c JP
4495 与えられた@var{set}/@var{bag}の各要素に@var{proc}を適用した結果を要素として、
4496 @var{comparator}を比較器に使う新たなセット/バッグを作って返します。
4497 @c COMMON
4498 @end defun
4499
4500 @defun set-for-each proc set
4501 @defunx bag-for-each proc bag
4502 [R7RS set]
4503 @c MOD scheme.set
4504 @c EN
4505 Apply @var{proc} to each element in the set/bag. The result of @var{proc}
4506 is ignored. Return value is undefined.
4507 @c JP
4508 @var{set}/@var{bag}の各要素に@var{proc}を適用します。
4509 @var{proc}の戻り値は捨てられます。この手続き自体の戻り値は未定義です。
4510 @c COMMON
4511 @end defun
4512
4513 @defun set-fold proc seed set
4514 @defunx bag-fold proc seed bag
4515 [R7RS set]
4516 @c MOD scheme.set
4517 @c EN
4518 For each item in the set/bag, call @var{proc} with two arguments, an item
4519 and a seed value. What @var{proc} returns becomes the next seed value.
4520 The @var{seed} argument gives the initial seed value, and the last return
4521 value of @var{proc} will be the result of @code{set-fold}/@code{bag-fold}.
4522 @c JP
4523 与えられたセット/バッグの各要素に対し、@var{proc}を2つの引数を伴って呼び出します。
4524 @var{proc}の1つ目の引数はセット/バッグの要素、2つ目の引数はシード値です。
4525 最初のシード値は@var{seed}で与えられ、各@var{proc}の戻り値が次のシード値となります。
4526 全ての要素に@var{proc}が適用されたら、最後の@var{proc}の戻り値が
4527 @code{set-fold}/@code{bag-fold}の戻り値になります。
4528 @c COMMON
4529
4530 @example
4531 (bag-fold + 0 (bag eqv-comparator 1 1 2 2 3 3 4 4))
4532 @result{} 20
4533 @end example
4534 @end defun
4535
4536 @defun set-filter pred set
4537 @defunx bag-filter pred bag
4538 [R7RS set]
4539 @c MOD scheme.set
4540 @c EN
4541 Returns a newly created set/bag with the same comparator of the original
4542 set/bag, and its content consists of items from the original set/bag
4543 that satisfy @var{pred}.
4544 @c JP
4545 与えられたセット/バッグと同じ比較器を持つ新たなセット/バッグを作り、
4546 元の要素のうち述語@var{pred}を満たす要素だけを入れて返します。
4547 @c COMMON
4548
4549 @example
4550 (set->list (set-filter odd? (set eqv-comparator 1 2 3 4 5)))
4551 @result{} (1 3 5)
4552 @end example
4553 @end defun
4554
4555 @defun set-remove pred set
4556 @defunx bag-remove pred bag
4557 [R7RS set]
4558 @c MOD scheme.set
4559 @c EN
4560 Returns a newly created set/bag with the same comparator of the original
4561 set/bag, and its content consists of items from the original set/bag
4562 that does not satisfy @var{pred}.
4563 @c JP
4564 与えられたセット/バッグと同じ比較器を持つ新たなセット/バッグを作り、
4565 元の要素のうち述語@var{pred}を満たさない要素だけを入れて返します。
4566 @c COMMON
4567
4568 @example
4569 (set->list (set-remove odd? (set eqv-comparator 1 2 3 4 5)))
4570 @result{} (2 4)
4571 @end example
4572 @end defun
4573
4574 @defun set-partition pred set
4575 @defunx bag-partition pred bag
4576 [R7RS set]
4577 @c MOD scheme.set
4578 @c EN
4579 Returns two sets or bags, both have the same comparator of the original
4580 set or bag. The first one consists of the items from the original set/bag
4581 that satisfy @var{pred}, and the second one consists of the items that don't.
4582 @c JP
4583 与えられたセット/バッグと同じ比較器を持つ、二つのセット/バッグを返します。
4584 最初の戻り値には、元のセット/バッグの要素のうち@var{pred}を満たすもののみが含まれ、
4585 二番目の戻り値にはそうでない要素のみが含まれます。
4586 @c COMMON
4587
4588 @example
4589 (receive (in out) (set-remove odd? (set eqv-comparator 1 2 3 4 5))
4590 (values (set->list in)
4591 (set->list out)))
4592 @result{} (1 3 5) @r{and} (2 4)
4593 @end example
4594 @end defun
4595
4596 @defun set-filter! pred set
4597 @defunx bag-filter! pred bag
4598 @defunx set-remove! pred set
4599 @defunx bag-remove! pred bag
4600 @defunx set-partition! pred set
4601 @defunx bag-partition! pred bag
4602 [R7RS set]
4603 @c MOD scheme.set
4604 @c EN
4605 Linear update versions of their counterparts (the procedures without @code{!}).
4606 They work like their respective counterpart, but they are allowed (but not
4607 required) to reuse the original set/bag to produce the result(s).
4608 @c JP
4609 それぞれの@code{!}がない手続きの線形更新版です。
4610 @code{!}がない手続きと同様に動きますが、
4611 戻り値を作るために渡されたセット/バッグを破壊することが許されています。
4612 @c COMMON
4613
4614 @c EN
4615 Note that it is not guaranteed that the original set/bag is modified, so
4616 you have to use the return value(s) instead of relying on the side effects.
4617 @c JP
4618 元のセット/バッグが必ず変更されるとは限らないことに注意してください。
4619 副作用を当てにするのではなく、必ず戻り値を使う必要があります。
4620 @c COMMON
4621 @end defun
4622
4623 @c EN
4624 @subheading Copying and conversion
4625 @c JP
4626 @subheading コピーと変換
4627 @c COMMON
4628
4629 @defun set-copy set
4630 @defunx bag-copy bag
4631 [R7RS set]
4632 @c MOD scheme.set
4633 @c EN
4634 Returns a copy of the set/bag.
4635 @c JP
4636 与えられたセット/バッグのコピーを返します。
4637 @c COMMON
4638 @end defun
4639
4640 @defun set->list set
4641 @defunx bag->list bag
4642 [R7RS set]
4643 @c MOD scheme.set
4644 @c EN
4645 Returns a list of all items in the set/bag.
4646 Since sets and bags are unordered, there's no guarantee on the
4647 order of items.
4648 @c JP
4649 セット/バッグの持つ要素全てのリストを返します。
4650 セット/バッグは順序を持たないので、要素がどういう順序になるかは不定です。
4651 @c COMMON
4652 @end defun
4653
4654 @defun list->set comparator elt-list
4655 @defunx list->bag comparator elt-list
4656 [R7RS set]
4657 @c MOD scheme.set
4658 @c EN
4659 Creates a set or a bag with the given comparator, and
4660 the list of element. Functionally equivalent to the followings:
4661 @c JP
4662 与えられた比較器と要素のリストから、セット/バッグを作って返します。
4663 次のコードと機能的に等価です。
4664 @c COMMON
4665
4666 @example
4667 (apply set comparator elt-list)
4668 (apply bag comparator elt-list)
4669 @end example
4670 @end defun
4671
4672 @defun list->set! set elt-list
4673 @defunx list->bag! bag elt-list
4674 [R7RS set]
4675 @c MOD scheme.set
4676 @c EN
4677 Add items in @var{elt-list} to the existing set/bag, and returns
4678 the updated set/bag. The original set/bag may or may not be modified.
4679 Functionally equivalent to the followings:
4680 @c JP
4681 リスト@var{elt-list}の要素を与えられたセット/バッグに追加し、
4682 更新されたセット/バッグを返します。
4683 元のセット/バッグは破壊的に変更されるかもしれませんし、されないかもしれません。
4684 次のコードと機能的に等価です。
4685 @c COMMON
4686
4687 @example
4688 (apply set-adjoin! set elt-list)
4689 (apply bag-adjoin! bag elt-list)
4690 @end example
4691 @end defun
4692
4693 @defun bag->set bag
4694 @defunx set->bag set
4695 [R7RS set]
4696 @c MOD scheme.set
4697 @c EN
4698 Conversions between a bag and a set. Returns a newly created bag or set,
4699 respectively.
4700 @c JP
4701 バッグをセットに、あるいはセットをバッグに変換します。
4702 新に作られたセットあるいはバッグを返します。
4703 @c COMMON
4704
4705 @c EN
4706 If @var{bag} has duplicated items, @code{bag->set} coerces them to one
4707 item.
4708 @c JP
4709 元の@var{bag}に重複する要素が含まれていた場合、
4710 @code{bag->set}はそのうちひとつだけを含みます。
4711 @c COMMON
4712 @end defun
4713
4714 @defun set->bag! bag set
4715 [R7RS set]
4716 @c MOD scheme.set
4717 @c EN
4718 Returns a bag that contains all items in @var{set} plus
4719 all iterms in @var{bag}, which may be modified to create the result.
4720 Both @var{bag} and @var{set} must have the same comparator.
4721 @c JP
4722 @var{bag}に含まれる全ての要素に、@var{set}に含まれる要素を追加したバッグを返します。
4723 @var{bag}は破壊的に変更されるかもしれません。
4724 @var{bag}と@var{set}は同じ比較器を使っていなければなりません。
4725 @c COMMON
4726 @end defun
4727
4728
4729 @defun bag->alist bag
4730 [R7RS set]
4731 @c MOD scheme.set
4732 @c EN
4733 Returns a list of @code{(item . count)}, where @var{item} is
4734 an item in @var{bag}, and @var{count} is the number of that item
4735 in the bag.
4736 @c JP
4737 @var{bag}中の相異なる各要素@var{item}についてその個数を@var{count}としたとき、
4738 @code{(item . count)}のリストを返します。
4739 @c COMMON
4740 @end defun
4741
4742 @defun alist->bag comparator alist
4743 [R7RS set]
4744 @c MOD scheme.set
4745 @c EN
4746 Creates a new bag with @var{comparator}, and fills it according to
4747 @var{alist}, which must be a list of @code{(item . count)}.
4748 @c JP
4749 @var{alist}は要素とその個数のペア @code{(item . count)} のリストです。
4750 @var{comparator}を比較器として、それぞれの@var{item}を@var{count}個づつ
4751 含むようなバッグを作成して返します。
4752 @c COMMON
4753
4754 @c EN
4755 If there's duplicate items in @var{alist}, only fist one counts.
4756 @c JP
4757 @var{alist}中に重複する@var{item}があった場合、最初のもののみが考慮されます。
4758 @c COMMON
4759 @end defun
4760
4761 @c EN
4762 @subheading Subsets
4763 @c JP
4764 @subheading 部分集合
4765 @c COMMON
4766
4767 @defun set=? set1 set2 @dots{}
4768 @defunx bag=? bag1 bag2 @dots{}
4769 [R7RS set]
4770 @c MOD scheme.set
4771 @c EN
4772 Returns true iff all sets/bags have exactly same items.
4773 @c JP
4774 全てのセット/バッグが同じ要素を持っている場合に@code{#t}を、そうでなければ@code{#f}を
4775 返します。
4776 @c COMMON
4777 @end defun
4778
4779 @defun set<? set1 set2 @dots{}
4780 @defunx bag<? bag1 bag2 @dots{}
4781 @defunx set>? set1 set2 @dots{}
4782 @defunx bag>? bag1 bag2 @dots{}
4783 @defunx set<=? set1 set2 @dots{}
4784 @defunx bag<=? bag1 bag2 @dots{}
4785 @defunx set>=? set1 set2 @dots{}
4786 @defunx bag>=? bag1 bag2 @dots{}
4787 [R7RS set]
4788 @c MOD scheme.set
4789 @c EN
4790 These predicates checks inclusion relationship between sets or bags.
4791 For example, @code{(set<? @var{set1} @var{set2})} is @code{#t} iff @var{set1}
4792 is a proper subset of @var{set2}, and
4793 @code{(bag>=? @var{bag1} @var{bag2})} is @code{#t} iff
4794 @var{bag2} is a subset (including the 'equal to' case) of @var{bag1}, etc.
4795
4796 If more than two arguments are given, the predicate returns @code{#t} iff
4797 every consecutive arguments satisfies the relationship.
4798 @c JP
4799 これらの述語は集合の包含関係を判定します。例えば@code{(set<? @var{set1} @var{set2})}
4800 は@var{set1}が@var{set2}の真部分集合の時に@code{#t}を、そうでなければ@code{#f}を
4801 返し、@code{(bag>=? @var{bag1} @var{bag2})}は@var{bag2}が@var{bag1}の
4802 部分集合(等しい場合を含む)の時に@code{#t}を、そうでなければ@code{#f}を返すという具合です。
4803
4804 3つ以上の引数が与えられた場合、全ての隣り合う引数同士で関係が成り立っている時のみ
4805 @code{#t}が返されます。
4806 @c COMMON
4807 @end defun
4808
4809 @c EN
4810 @subheading Set theory operations
4811 @c JP
4812 @subheading 集合論演算
4813 @c COMMON
4814
4815 @defun set-union set1 set2 @dots{}
4816 @defunx bag-union bag1 bag2 @dots{}
4817 [R7RS set]
4818 @c MOD scheme.set
4819 @c EN
4820 Returns a newly allocated set or bag which is a union of all
4821 the sets/bags.
4822 @c JP
4823 与えられた全てのセット/バッグの和集合となるセット/バッグを新に作って返します。
4824 @c COMMON
4825 @end defun
4826
4827 @defun set-intersection set1 set2 @dots{}
4828 @defunx bag-intersection bag1 bag2 @dots{}
4829 [R7RS set]
4830 @c MOD scheme.set
4831 @c EN
4832 Returns a newly allocated set or bag which is an intersection of
4833 all the sets/bags.
4834 @c JP
4835 与えられた全てのセット/バッグの共通集合となるセット/バッグを新に作って返します。
4836 @c COMMON
4837 @end defun
4838
4839 @defun set-difference set1 set2 @dots{}
4840 @defunx bag-difference bag1 bag2 @dots{}
4841 [R7RS set]
4842 @c MOD scheme.set
4843 @c EN
4844 Returns a newly created set or bag that contains items in @var{set1}/@var{bag1}
4845 except those are also in @var{set2}/@var{bag2} @dots{}.
4846 @c JP
4847 @var{set1}/@var{bag1}の要素のうち、@var{set2}/@var{bag2} @dots{}に含まれないもの
4848 のみを集めたセット/バッグを新に作って返します。
4849 @c COMMON
4850
4851 @example
4852 (sort (set->list (set-difference (set eqv-comparator 1 2 3 4 5 6 7)
4853 (set eqv-comparator 3 5 7 9 11 13)
4854 (set eqv-comparator 4 8 16 32))))
4855 @result{} (1 2 6)
4856 @end example
4857 @end defun
4858
4859 @defun set-xor set1 set2
4860 @defunx bag-xor bag1 bag2
4861 [R7RS set]
4862 @c MOD scheme.set
4863 @c EN
4864 Returns a newly created set or bag that consists of items
4865 that are either in @var{set1}/@var{bag1} or @var{set2}/@var{bag2},
4866 but not in both.
4867 @c JP
4868 @var{set1}/@var{bag1}および@var{set2}/@var{bag2}に含まれる要素のうち、
4869 どちらか一方にしか含まれない要素のみを集めた集合を新に作って返します。
4870 @c COMMON
4871
4872 @example
4873 (sort (set->list (set-xor (set eqv-comparator 2 3 5 7 11 13 17)
4874 (set eqv-comparator 3 5 7 9 11 13 15))))
4875 @result{} (2 9 15 17)
4876 @end example
4877 @end defun
4878
4879 @defun set-union! set1 set2 @dots{}
4880 @defunx bag-union! bag1 bag2 @dots{}
4881 @defunx set-intersection! set1 set2 @dots{}
4882 @defunx bag-intersection! bag1 bag2 @dots{}
4883 @defunx set-difference! set1 set2 @dots{}
4884 @defunx bag-difference! bag1 bag2 @dots{}
4885 @defunx set-xor! set1 set2
4886 @defunx bag-xor! bag1 bag2
4887 [R7RS set]
4888 @c MOD scheme.set
4889 @c EN
4890 Linear update versions of their corresponding procedures.
4891 Those procedures works like their @code{!}-less counterparts,
4892 except that they are allowed to, but not required to, reuse
4893 @var{set1}/@var{bag1} to produce the result.
4894 @c JP
4895 それぞれ、対応する手続き(@code{!}のついていないもの)の線形更新版です。
4896 @code{!}のついていない版と同様に動作しますが、結果を生成するために
4897 @var{set1}/@var{bag1}を破壊的に変更するかもしれません。
4898 @c COMMON
4899
4900 @c EN
4901 The caller should always use the returned set/bag instead of
4902 relying on the side effects.
4903 @c JP
4904 呼び出し側は、副作用を期待するのではなく、常に戻り値を利用してください。
4905 @c COMMON
4906 @end defun
4907
4908 @c EN
4909 @subheading Bag-specific procedures
4910 @c JP
4911 @subheading バッグだけにある操作
4912 @c COMMON
4913
4914 @defun bag-sum bag1 bag2 @dots{}
4915 @defunx bag-sum! bag1 bag2 @dots{}
4916 [R7RS set]
4917 @c MOD scheme.set
4918 @c EN
4919 Returns a bag that gathers all the items in given bags, counting
4920 duplicates. The functional version @code{bag-sum} always
4921 creates new bag to return.
4922 The linear update version @code{bag-sum!} is allowed to,
4923 but not required to, modify @var{bag1} to produce the result.
4924 @c JP
4925 与えられた全てのバッグの要素を合わせたバッグを作って返します。
4926 重複する要素があればその分同じ要素が重ねられます。
4927 @var{bag-sum}は常に新たなバッグを作って返しますが、
4928 線形更新版の@var{bag-sum!}は結果を作るために@var{bag1}を破壊的に変更するかもしれません。
4929 @c COMMON
4930
4931 @example
4932 (sort (bag->list (bag-sum (bag eqv-comparator 1 1 2 4 5 5 6)
4933 (bag eqv-comparator 3 3 5 9))))
4934 @result{} (1 1 2 3 3 4 5 5 5 6 9)
4935 @end example
4936
4937 @c EN
4938 Note the difference from @code{bag-union}:
4939 @c JP
4940 @code{bag-union}との違いに注意してください。
4941 @c COMMON
4942
4943 @example
4944 (sort (bag->list (bag-union (bag eqv-comparator 1 1 2 4 5 5 6)
4945 (bag eqv-comparator 3 3 5 9))))
4946 @result{} (1 1 2 3 3 4 5 5 6 9)
4947 @end example
4948 @end defun
4949
4950 @defun bag-product n bag
4951 @defunx bag-product! n bag
4952 [R7RS set]
4953 @c MOD scheme.set
4954 @c EN
4955 Returns a bag that contains every item as @var{n}-times
4956 many as the original bag. A fresh bag is created and returned
4957 by @code{bag-product}, while @code{bag-product!} may reuse
4958 @var{bag} to produce the result.
4959 @c JP
4960 与えられたバッグの各要素数を@var{n}倍したバッグを返します。
4961 @code{bag-product}は常に新たなバッグを作りますが、
4962 @code{bag-product!}は結果を作るために@var{bag}を破壊的に変更するかもしれません。
4963 @c COMMON
4964
4965 @example
4966 (sort (bag->list (bag-product 2 (bag eq-comparator 'a 'b 'r 'a))))
4967 @result{} (a a a a b b r r)
4968 @end example
4969 @end defun
4970
4971 @defun bag-unique-size bag
4972 [R7RS set]
4973 @c MOD scheme.set
4974 @c EN
4975 Returns the number of unique elements in @var{bag}.
4976 @c JP
4977 @var{bag}中の、互いに異なる要素の数を返します。
4978 @c COMMON
4979
4980 @example
4981 (bag-unique-size (bag eqv-comparator 1 1 2 2 3 3 4))
4982 @result{} 4
4983 @end example
4984 @end defun
4985
4986 @defun bag-element-count bag elt
4987 [R7RS set]
4988 @c MOD scheme.set
4989 @c EN
4990 Returns the number of specified element @var{elt} in @var{bag}.
4991 @c JP
4992 @var{bag}中に@var{elt}がいくつあるかを返します。
4993 @c COMMON
4994
4995 @example
4996 (bag-element-count (bag eqv-comparator 1 1 2 2 2 3 3) 2)
4997 @result{} 3
4998 @end example
4999 @end defun
5000
5001 @defun bag-for-each-unique proc bag
5002 [R7RS set]
5003 @c MOD scheme.set
5004 @c EN
5005 For each unique item in @var{bag}, calls @code{proc} with two arguments:
5006 The item, and the count of the item in the bag.
5007 @c JP
5008 @var{bag}中の相異なる各要素について、@var{proc}を2つの引数で呼び出します。
5009 引数は、要素と、その要素の数です。
5010 @c COMMON
5011 @end defun
5012
5013 @defun bag-fold-unique proc seed bag
5014 [R7RS set]
5015 @c MOD scheme.set
5016 @c EN
5017 For each unique item in @var{bag}, calls @var{proc} with three arguments:
5018 The item, the count of the item, and the previous seed value.
5019 The @var{seed} argument provides the initial seed value; the result
5020 of @var{proc} is used for the next seed value, and the last
5021 result of @code{proc} is returned from @code{bag-fold-unique}.
5022 @c JP
5023 @var{bag}中の相異なる各要素について、@var{proc}を3つの引数で呼び出します。
5024 要素、その個数、そして一つ前のシード値です。
5025 @var{seed}引数が最初のシード値を与え、その後は各@var{proc}の戻り値が次のシード値となります。
5026 最後のシード値が@code{bag-fold-unique}の戻り値となります。
5027 @c COMMON
5028
5029 @example
5030 (sort (bag-fold-unique acons '()
5031 (bag equal-comparator "a" "a" "b" "b" "b" "c" "d"))
5032 string<? car)
5033 @result{} (("a" . 2) ("b" . 3) ("c" . 1) ("d" . 1))
5034 @end example
5035 @end defun
5036
5037 @defun bag-increment! bag elt count
5038 @defunx bag-decrement! bag elt count
5039 [R7RS set]
5040 @c MOD scheme.set
5041 @c EN
5042 Linearly update @var{bag} to increase or decrease the count of @var{elt} in it
5043 by @var{count}, which must be an exact integer. Note that the
5044 element count won't get below zero; if a bag has two @code{a}'s, and
5045 you call @code{(bag-decrement! bag 'a 100)}, you get a bag
5046 with zero @code{a}'s.
5047 @c JP
5048 @var{bag}中の要素@var{elt}の個数を@var{count}だけ増やし/減らします。
5049 線形更新手続きなので、@var{bag}は結果を作るために破壊的に変更されるかもしれません。
5050 要素の個数は負にはなりません。@code{a}が二つバッグに含まれている状態で
5051 @code{(bag-decrement! bag 'a 100)}を呼ぶと、
5052 @code{a}がひとつも含まれないバッグが返されます。
5053 @c COMMON
5054 @end defun
5055
5056 @c EN
5057 @subheading Comparators
5058 @c JP
5059 @subheading 比較器
5060 @c COMMON
5061
5062 @defvr {Comparator} set-comparator
5063 @defvrx {Comparator} bag-comparator
5064 [R7RS comparator]
5065 @c MOD scheme.set
5066 @c EN
5067 Comparators to be used to compare sets or bags. They don't provide
5068 comparison procedure, for you cannot define a total order among sets or bags.
5069 They do provide hash functions.
5070 @c JP
5071 セット同士、バッグ同士を比較する比較器です。
5072 セット/バッグに一般的な全順序関係は定義できないので、大小比較手続きは提供されません。
5073 ハッシュ手続きは提供されます。
5074 @c COMMON
5075 @end defvr
5076
5077
5078 @node R7RS character sets, R7RS hash tables, R7RS sets, R7RS large
5079 @subsection @code{scheme.charset} - R7RS character sets
5080 @c NODE R7RS文字集合, @code{scheme.charset} - R7RS文字集合
5081
5082 @deftp {Module} scheme.charset
5083 @mdindex scheme.charset
5084 @c EN
5085 Implements character set library, originally defined as SRFI-14.
5086 Note that the following
5087 character-set procedures and pre-defined charsets are Gauche's build-in.
5088 @xref{Character sets}.
5089 @c JP
5090 文字集合ライブラリを実装します。元はSRFI-14で定義されたものです。
5091 以下の文字集合手続きと定義済み文字集合はGauche組み込みになっているので、
5092 @ref{Character sets}を参照してください。
5093 @c COMMON
5094
5095 @example
5096 char-set char-set? char-set-contains?
5097 char-set-copy char-set-complement char-set-complement!
5098
5099 char-set:lower-case char-set:upper-case char-set:title-case
5100 char-set:letter char-set:digit char-set:letter+digit
5101 char-set:graphic char-set:printing char-set:whitespace
5102 char-set:iso-control char-set:punctuation char-set:symbol
5103 char-set:hex-digit char-set:blank char-set:ascii
5104 char-set:empty char-set:full
5105 @end example
5106
5107 @c EN
5108 In Gauche,
5109 the @code{<char-set>} class inherits @code{<collection>} and implements
5110 the collection protocol, so that the generic operations defined in
5111 @code{gauche.collection} can also be used (@pxref{Collection framework}).
5112 @c JP
5113 Gaucheでは@code{<char-set>}クラスは@code{<collection>}を継承し、
5114 コレクションプロトコルを実装しているので、@code{gauche.collection}モジュールで
5115 提供される操作も使えます (@ref{Collection framework}参照)。
5116 @c COMMON
5117 @end deftp
5118
5119 @menu
5120 * Character-set constructors::
5121 * Character-set comparison::
5122 * Character-set iteration::
5123 * Character-set query::
5124 * Character-set algebra::
5125 @end menu
5126
5127 @node Character-set constructors, Character-set comparison, R7RS character sets, R7RS character sets
5128 @subsubsection Character-set constructors
5129 @c NODE 文字集合の構築子
5130
5131 @defun list->char-set char-list :optional base-cs
5132 @defunx list->char-set! char-list base-cs
5133 [R7RS comparator]
5134 @c MOD scheme.charset
5135 @c EN
5136 Constructs a character set from a list of characters @var{char-list}.
5137 If @var{base-cs} is given, it must be a character set, and the characters
5138 in it are added to the result character set.
5139 @code{List->char-set!} is allowed, but not required, to reuse @var{base-cs}
5140 to store the result.
5141 @c JP
5142 与えられた文字のリスト@var{char-list}から文字集合を構築して返します。
5143 文字集合@var{base-cs}が与えられていた場合、返される文字集合は
5144 その文字集合に@var{char-list}中の文字を追加したものとなります。
5145 @code{list->char-set!}は、結果を格納するために@var{base-cs}を
5146 変更するかもしれません。
5147 @c COMMON
5148 @end defun
5149
5150 @defun string->char-set s :optional base-cs
5151 @defunx string->char-set! s base-cs
5152 [R7RS charset]
5153 @c MOD scheme.charset
5154 @c EN
5155 Like @code{list->char-set} and @code{list->char-set!},
5156 but take a list of characters from a string @var{s}.
5157 @c JP
5158 追加する文字をリストでなく文字列@var{s}で与えることを除けば
5159 @code{list->char-set}、@code{list->char-set!}と同じです。
5160 @c COMMON
5161 @end defun
5162
5163 @defun char-set-filter pred char-set :optional base-cs
5164 @defunx char-set-filter! pred char-set base-cs
5165 [R7RS charset]
5166 @c MOD scheme.charset
5167 @c EN
5168 Returns a character set containing every character @var{c} in
5169 @var{char-set} such that @code{(@var{pred} @var{c})} returns true.
5170 If a character set @var{base-cs} is given, its content is added to
5171 the result. The linear update version @code{char-set-filter!}
5172 is allowed, but not required, to modify @var{base-cs} to store the result.
5173 @c JP
5174 @var{char-set}内の文字のうち、@code{(@var{pred} @var{c})} が真の値を
5175 返すような@var{c}からなる文字集合を作成して返します。
5176 文字集合@var{base-cs}が与えられた場合は、その内容が結果に追加されます。
5177 @code{char-set-filter!}は、結果を格納するために@var{base-cs}を変更するかも
5178 しれません。
5179 @c COMMON
5180 @end defun
5181
5182 @defun ucs-range->char-set lower upper :optional error? base-cs
5183 @defunx ucs-range->char-set! lower upper error? base-cs
5184 [R7RS charset]
5185 @c MOD scheme.charset
5186 @c EN
5187 Creates a character set containing every character whose ISO/IEC 10646
5188 UCS-4 code lies in the half-open range [@var{lower},@var{upper}).
5189
5190 If the range contains unassigned codepoint, they are silently ignored.
5191
5192 If the range contains a valid codepoint which isn't supported in Gauche,
5193 it is ignored when @var{error?} is false (default),
5194 or an error is raised when @var{error?} has a true value.
5195 If you compile Gauche with utf-8 native encoding (default), all valid
5196 Unicode codepoints are supported. If Gauche is compiled with other native
5197 encoding, some codepoints are not supported.
5198
5199 If a character set @var{base-cs} is given, its content is added to
5200 the result. The linear update version @code{ucs-range->char-set!}
5201 is allowed, but not required, to modify @var{base-cs} to store the result.
5202 @c JP
5203 @var{lower}以上、@var{upper}未満のUnicodeコードポイントを持つ文字を服務
5204 文字集合を作って返します。
5205
5206 指定された範囲内に文字を割り当てられていないコードポイントがあった場合、
5207 それは単に無視されます。
5208
5209 指定された範囲内にある有効なコードポイントをGaucheがサポートしていない場合、
5210 @var{error?}が偽なら(デフォルト)それは単に無視され、真の値ならエラーが投げられます。
5211 デフォルトではGaucheはutf-8内部エンコーディングでコンパイルされていて、
5212 有効な全てのUnicodeコードポイントが扱えます。しかし、Gaucheをそれ以外の内部エンコーディング
5213 でコンパイルした場合は、サポートされないコードポイントがあります。
5214
5215 文字集合@var{base-cs}が与えられた場合、その内容が結果の文字集合に追加されます。
5216 @code{ucs-range->char-set!}は、結果を格納するために@var{base-cs}を
5217 再利用するかもしれません。
5218 @c COMMON
5219 @end defun
5220
5221 @defun integer-range->char-set lower upper :optional error? base-cs
5222 @defunx integer-range->char-set! lower upper error? base-cs
5223 @c MOD scheme.charset
5224 @c EN
5225 These are Gauche-specific procedures and not in @code{scheme.charset}.
5226 When Gauche is compiled with utf-8 native encoding (default), they are
5227 the same as @code{ucs-range->char-set} and @code{ucs-range->char-set!},
5228 respectively.
5229 If Gauche is compiled with other native encoding, these interprets
5230 the given range in its native encoding.
5231
5232 Meaning of @var{error?} and @var{base-cs} are the same as
5233 @code{ucs-char->char-set}.
5234 @c JP
5235 これらはGauche特有で、@code{scheme.charset}の仕様には含まれていません。
5236 Gaucheがutf-8内部エンコーディングでコンパイルされていた場合(デフォルト)、これらは
5237 それぞれ@code{ucs-range->charset}および@code{ucs->range-char-set!}と同じです。
5238 Gaucheがそれ以外の内部エンコーディングでコンパイルされていた場合は、
5239 範囲指定がそのエンコーディングでの文字コードで解釈されません。
5240
5241 @var{error?}および@var{base-cs}引数の意味は@code{ucs-char->char-set}と同じです。
5242 @c COMMON
5243 @end defun
5244
5245 @defun ->char-set x
5246 [R7RS charset]
5247 @c MOD scheme.charset
5248 @c EN
5249 A convenience function to coerce various kinds of objects to a char-set.
5250 The argument @var{x} can be a collection of characters,
5251 a char-set, or a character. If the argument is a char-set,
5252 it is returned as-is. If the argument is a character,
5253 a char-set with that single character is returned.
5254 @c JP
5255 様々な種類のオブジェクトを文字集合に変換する関数です。@var{x}に
5256 文字のコレクション、文字集合、あるいは文字を渡すことができます。
5257 引数が文字集合の場合はそれがそのまま返されます。
5258 引数が文字の場合は、その文字のみを含む文字集合が返されます。
5259 @c COMMON
5260
5261 @c EN
5262 Note: R7RS @code{(scheme charset)}'s
5263 @code{->char-set} only accepts a string, a char-set
5264 or a character as an argument. Gauche extends it so that it can
5265 accept any collection of characters.
5266 @c JP
5267 註: R7RS @code{(scheme charset)}の@code{->char-set}
5268 は文字列、文字集合、文字のいずれかのみを
5269 引数に取ります。Gaucheでは文字の任意のコレクションを取るように拡張しました。
5270 @c COMMON
5271 @end defun
5272
5273 @node Character-set comparison, Character-set iteration, Character-set constructors, R7RS character sets
5274 @subsubsection Character-set comparison
5275 @c NODE 文字集合の比較
5276
5277 @defun char-set= char-set1 @dots{}
5278 [R7RS charset]
5279 @c MOD scheme.charset
5280 @c EN
5281 Returns @code{#t} iff all the character sets have exactly the
5282 same members.
5283 @c JP
5284 与えられた文字集合が全て同じ要素を持っている場合に限り@code{#t}を返します。
5285 @c COMMON
5286
5287 @example
5288 (char-set=) @result{} #t
5289 (char-set= (char-set)) @result{} #t
5290 (char-set= (string->char-set "cba")
5291 (list->char-set #\a #\b #\c))
5292 @result{} #t
5293 @end example
5294
5295 @end defun
5296
5297 @defun char-set<= char-set1 @dots{}
5298 [R7RS charset]
5299 @c MOD scheme.charset
5300 @c EN
5301 Returns @code{#t} iff every char-set argument is a subset of
5302 the following char-sets. If no arguments are given, @code{#t} is returned.
5303 @c JP
5304 各char-set引数がそれ以降のchar-setの部分集合になっている場合に限り@code{#t}を返します。
5305 引数が無い場合は@code{#t}を返します。
5306 @c COMMON
5307 @end defun
5308
5309 @defun char-set-hash char-set :optional bound
5310 [R7RS charset]
5311 @c MOD scheme.charset
5312 @c EN
5313 Returns a non-negative exact integer as a hash value of @var{char-set}.
5314 If optional @var{bound} argument is given, it must be a positive integer
5315 that limits the range of the hash value, which will fall between
5316 0 to @code{(- bound 1)}, inclusive.
5317 @c JP
5318 @var{char-set}のハッシュ値を非負の正確な整数で返します。@var{bound}が与えられた場合、
5319 それは正の正確な整数でなければならず、戻り値は0から@code{(- bound 1)}まで(両端含む)の
5320 値を取ります。
5321 @c COMMON
5322 @end defun
5323
5324 @node Character-set iteration, Character-set query, Character-set comparison, R7RS character sets
5325 @subsubsection Character-set iteration
5326 @c NODE 文字集合のイテレーション
5327
5328 @defun char-set-cursor char-set
5329 [R7RS charset]
5330 @c MOD scheme.charset
5331 @c EN
5332 Returns an object that can point to a first character within @var{char-set}
5333 (here, `first' merely means the beginning of iteration; the order of
5334 iteration is implementation-dependent and you can't assume a specific
5335 order).
5336 The caller must treat the return value as an opaque object; it can only
5337 be used to pass as the @var{cursor} argument of @code{char-set-ref},
5338 @code{char-set-cursor-next} and @code{end-of-char-set?}.
5339 @c JP
5340 @var{char-set}中の最初の文字を指すオブジェクトを返します。
5341 (ここでの「最初」は文字集合を順にたどってゆく際の最初ということです。
5342 文字集合をたどる順は実装依存で、特定の順序を当てにしないようにしてください。)
5343 返されたオブジェクトは、そのまま@code{char-set-ref}、
5344 @code{char-set-cursor-next}、@code{end-of-char-set?}の@var{cursor}引数に
5345 渡す以外に使ってはいけません。
5346 @c COMMON
5347 @end defun
5348
5349 @defun char-set-ref char-set cursor
5350 [R7RS charset]
5351 @c MOD scheme.charset
5352 @c EN
5353 Returns a character in @var{char-set} pointed by @var{cursor}.
5354
5355 The @var{cursor} argument must be an object returned from
5356 @code{char-set-cursor} or @code{char-set-cursor-next} with @var{char-set}.
5357 The behavior is undefined if @var{cursor} is not a cursor
5358 created from @var{char-set}.
5359 @c JP
5360 @var{char-set}中の、@var{cursor}に指された文字を返します。
5361
5362 @var{cursor}は@code{char-set-cursor}か@code{char-set-cursor-next}によって
5363 @var{char-set}から作られたオブジェクトでなければなりません。
5364 @var{cursor}が@var{char-set}から作られたものでない場合の動作は未定義です。
5365 @c COMMON
5366 @end defun
5367
5368 @defun char-set-cursor-next char-set cursor
5369 [R7RS charset]
5370 @c MOD scheme.charset
5371 @c EN
5372 Returns a new cursor for the next character pointed by @var{cursor}
5373 within @var{char-set}.
5374
5375 The @var{cursor} argument must be an object returned from
5376 @code{char-set-cursor} or @code{char-set-cursor-next} with @var{char-set}.
5377 The behavior is undefined if @var{cursor} is not a cursor
5378 created from @var{char-set}.
5379 @c JP
5380 @var{char-set}中の、@var{cursor}が指している文字の次の文字を指す新たなカーソルを返します。
5381
5382 @var{cursor}は@code{char-set-cursor}か@code{char-set-cursor-next}によって
5383 @var{char-set}から作られたオブジェクトでなければなりません。
5384 @var{cursor}が@var{char-set}から作られたものでない場合の動作は未定義です。
5385 @c COMMON
5386 @end defun
5387
5388 @defun end-of-char-set? cursor
5389 [R7RS charset]
5390 @c MOD scheme.charset
5391 @c EN
5392 Returns @code{#t} iff @var{cursor} points to the end of the charset.
5393 @c JP
5394 @var{cursor}が文字集合の終端を指していたら@code{#t}を、そうでなければ@code{#f}を返します。
5395 @c COMMON
5396 @end defun
5397
5398 @defun char-set-fold kons knil char-set
5399 [R7RS charset]
5400 @c MOD scheme.charset
5401 @c EN
5402 Iterate over all characters in @var{char-set}, calling the procedure @var{kons}
5403 with a character and the seed value. The return value of @var{kons} becomes
5404 the next seed value, while @var{knil} gives the first seed value.
5405 Returns the last seed value. The order of traversal isn't specified.
5406 @c JP
5407 @var{char-set}中の全ての文字について、手続き@var{kons}を、文字とシード値を引数にして
5408 呼び出します。@var{knil}が最初のシード値を与え、@var{kons}の戻り値が次のシード値となります。
5409 最後のシード値が@code{char-set-fold}の戻り値となります。
5410 文字を取り出す順番は規定されていません。
5411 @c COMMON
5412 @end defun
5413
5414 @defun char-set-unfold pred fun gen seed :optional base-char-set
5415 @defunx char-set-unfold! pred fun gen seed base-char-set
5416 [R7RS charset]
5417 @c MOD scheme.charset
5418 @c EN
5419 Build a character set by calling @var{fun} on the seed value repeatedly.
5420 For each iteration, first @var{pred} is applied to the current seed value.
5421 If it returns true, a character set that gathers characters generated so far
5422 is returned. Otherwise, @var{fun} is called on the seed value,
5423 which must return a character. Then @var{gen} is called on the seed value
5424 to obtain the next seed value.
5425
5426 If @var{base-char-set} is given, a union of it and the generated characters
5427 is returned.
5428 The linear-update version @code{char-set-unfold!} may modify @var{base-char-set}
5429 to create the result.
5430 @c JP
5431 @var{fun}をシード値に適用して得られる文字から文字集合を作って返します。
5432 繰り返しの度に、まず@var{pred}が現在のシード値に対して呼ばれ、それが真の値を返したら
5433 繰り返しは終了で、それまで作られた文字を集めた集合が戻り値となります。
5434 そうでなければ@var{fun}がシード値を引数として呼ばれ、文字を返します。
5435 次に@var{gen}がシード値を引数として呼ばれ、次のシード値を作ります。
5436
5437 @var{base-char-set}が与えられた場合は、それと生成された文字との和集合が返されます。
5438 線形更新バージョンである@code{char-set-unfold!}は、@var{base-char-set}を破壊的に
5439 再利用するかもしれません。
5440 @c COMMON
5441 @end defun
5442
5443 @defun char-set-for-each proc char-set
5444 [R7RS charset]
5445 @c MOD scheme.charset
5446 @c EN
5447 Applies @var{proc} on each character in @var{char-set}. The return value
5448 of @var{proc} is discarded. Returns undefined value.
5449 @c JP
5450 @var{proc}を@var{char-set}中のそれぞれの文字に適用します。
5451 @var{proc}の戻り値は捨てられます。この手続きの戻り値は規定されません。
5452 @c COMMON
5453 @end defun
5454
5455 @defun char-set-map proc char-set
5456 [R7RS charset]
5457 @c MOD scheme.charset
5458 @c EN
5459 Applies @var{proc} on each character in @var{char-set}, which must
5460 return a character. Returns a new charset consists of the characters
5461 returned from @var{proc}.
5462 @c JP
5463 @var{proc}を@var{char-set}中のそれぞれの文字に適用します。
5464 @var{proc}の戻り値は文字でなければなりません。@var{proc}の戻り値の文字を集めた
5465 新たな文字集合を返します。
5466 @c COMMON
5467 @end defun
5468
5469 @node Character-set query, Character-set algebra, Character-set iteration, R7RS character sets
5470 @subsubsection Character-set query
5471 @c NODE 文字集合への問い合わせ
5472
5473 @defun char-set-every pred char-set
5474 @defunx char-set-any pred char-set
5475 @defunx char-set-count pred char-set
5476 [R7RS charset]
5477 @c MOD scheme.charset
5478 @c EN
5479 These procedures apply @var{pred} to each character in @var{char-set}.
5480
5481 @code{char-set-every} returns @code{#f} as soon as @var{pred} returns
5482 @code{#f}. Otherwise, it returns the result of the last application of
5483 @var{pred}.
5484
5485 @code{char-set-any} returns as soon as @var{pred} returns a true value,
5486 and the return value is the one @var{pred} returns.
5487 If @var{pred} returns @code{#f} for all characters, @code{#f} is returned.
5488
5489 @code{char-set-count} returns the number of times
5490 @var{pred} returns a true value.
5491
5492 Note that @var{char-set} can be huge (e.g. a complement of small char-set),
5493 which can make these procedures take very long.
5494 @c JP
5495 これらの手続きは、@var{pred}を@var{char-set}に含まれる各文字に適用します。
5496
5497 @code{char-set-every}は@var{pred}が@code{#f}を返したら直ちに@code{#f}を返します。
5498 @var{pred}が最後まで@code{#f}を返さなかった場合は、最後の@var{pred}の返り値が
5499 @code{char-set-every}の返り値となります。
5500
5501 @code{char-set-any}は@var{pred}が真の値を返した場合に直ちにその値を返します。
5502 @var{pred}が最後まで@code{#f}を返した場合には@code{#f}を返します。
5503
5504 @code{char-set-count}は@var{pred}が真の値を返した回数を返します。
5505
5506 @var{char-set}は非常に大きくなる可能性があり (例えばごく小さな文字集合の補集合)、
5507 その場合、これらの手続きは非常に長くかかり得ることに注意してください。
5508 @c COMMON
5509 @end defun
5510
5511 @defun char-set->list char-set
5512 @defunx char-set->string char-set
5513 [R7RS charset]
5514 @c MOD scheme.charset
5515 @c EN
5516 Returns a list of each character, or a string consisting of
5517 each character, in @var{char-set}, respectively.
5518 Be careful to apply this on a large char set.
5519 @c JP
5520 @var{char-set}に含まれる文字をリストあるいは文字列にして返します。
5521 大きな文字集合に適用する場合は注意してください。
5522 @c COMMON
5523 @end defun
5524
5525
5526 @node Character-set algebra, , Character-set query, R7RS character sets
5527 @subsubsection Character-set algebra
5528 @c NODE 文字集合に適用できる代数的関数
5529
5530 @defun char-set-adjoin char-set char1 @dots{}
5531 @defunx char-set-adjoin! char-set char1 @dots{}
5532 [R7RS charset]
5533 @c MOD scheme.charset
5534 @c EN
5535 Returns a character set that adds @var{char1} @dots{} to
5536 @var{char-set}.
5537
5538 The linear update version @code{char-set-adjoin!} may modify
5539 @var{char-set}.
5540 @c JP
5541 @var{char-set}に@var{char1} @dots{}を加えた文字集合を返します。
5542
5543 線形更新版の@code{char-set-adjon!}は@var{char-set}引数を破壊的に再利用するかもしれません。
5544 @c COMMON
5545 @end defun
5546
5547 @defun char-set-delete char-set char1 @dots{}
5548 @defunx char-set-delete! char-set char1 @dots{}
5549 [R7RS charset]
5550 @c MOD scheme.charset
5551 @c EN
5552 Returns a character set that removes @var{char1} @dots{} from @var{char-set}.
5553 It is noop if @var{char-set} doesn't have @var{char1} @dots{}.
5554
5555 The linear update version @code{char-set-delete!} may modify
5556 @var{char-set}.
5557 @c JP
5558 @var{char-set}から@var{char1} @dots{}を除いた文字集合を返します。
5559 @var{char1} @dots{}が@var{char-set}に含まれている必要はありません。
5560
5561 線形更新版の@code{char-set-delete!}は@var{char-set}引数を破壊的に再利用するかもしれません。
5562 @c COMMON
5563 @end defun
5564
5565 @defun char-set-union char-set @dots{}
5566 @defunx char-set-union! char-set1 char-set2 @dots{}
5567 [R7RS charset]
5568 @c MOD scheme.charset
5569 @c EN
5570 Returns a character set of all characters in any one of
5571 @var{char-set} @dots{}.
5572 Without arguments, returns an empty charset.
5573
5574 The linear update version @code{char-set-union!} may modify
5575 @var{char-set1}.
5576 @c JP
5577 @var{char-set} @dots{}内の少なくともひとつに含まれる文字の文字集合を返します。
5578 引数が無ければ空の文字集合を返します。
5579
5580 線形更新版の@code{char-set-union!}は@var{char-set1}引数を破壊的に再利用するかもしれません。
5581 @c COMMON
5582 @end defun
5583
5584 @defun char-set-intersection char-set @dots{}
5585 @defunx char-set-intersection! char-set1 char-set2 @dots{}
5586 [R7RS charset]
5587 @c MOD scheme.charset
5588 @c EN
5589 Returns a character set of every character that
5590 is in all of @var{char-set} @dots{}.
5591 Without arguments, returns @code{char-set:full}.
5592
5593 The linear update version @code{char-set-intersection!} may modify
5594 @var{char-set1}.
5595 @c JP
5596 @var{char-set} @dots{}の全てに共通して含まれる文字の文字集合を返します。
5597 引数が無ければ@code{char-set:full}を返します。
5598
5599 線形更新版の@code{char-set-intersection!}は@var{char-set1}引数を破壊的に再利用するかもしれません。
5600 @c COMMON
5601 @end defun
5602
5603 @defun char-set-difference char-set1 char-set2 @dots{}
5604 @defunx char-set-difference! char-set1 char-set2 @dots{}
5605 [R7RS charset]
5606 @c MOD scheme.charset
5607 @c EN
5608 Returns a character set of every character that is in @var{char-set1}
5609 but not in any of @var{char-set2} @dots{}.
5610
5611 The linear update version @code{char-set-difference!} may modify
5612 @var{char-set1}.
5613 @c JP
5614 @var{char-set1}に含まれ、しかし@code{char-set2} @dots{}のどれにも含まれない文字の文字集合を返します。
5615
5616 線形更新版の@code{char-set-difference!}は@var{char-set1}引数を破壊的に再利用するかもしれません。
5617 @c COMMON
5618 @end defun
5619
5620 @defun char-set-xor char-set @dots{}
5621 @defunx char-set-xor! char-set1 char-set2 @dots{}
5622 [R7RS charset]
5623 @c MOD scheme.charset
5624 @c EN
5625 With zero arguments, returns an empty charset.
5626 With one argument, it is returned as is.
5627 With two arguments, returns a character set of every character that
5628 is in either one of two sets, but not in both.
5629 With more than two arguments, it returns
5630 @code{(char-set-xor (char-set-xor set1 set2) set3 @dots{})}.
5631
5632 The linear update version @code{char-set-xor!} may modify
5633 @var{char-set1}.
5634 @c JP
5635 引数がない場合は空の文字集合を、引数が一つの場合はそれをそのまま返します。
5636 引数が二つの場合、そのどちらか一方に含まれるが両方には含まれない文字の文字集合を返します。
5637 引数が三つ以上の場合は@code{(char-set-xor (char-set-xor set1 set2) set3 @dots{})}を
5638 返します。
5639
5640 線形更新版の@code{char-set-xor!}は@var{char-set1}引数を破壊的に再利用するかもしれません。
5641 @c COMMON
5642 @end defun
5643
5644 @defun char-set-diff+intersection char-set1 char-set2 @dots{}
5645 @defunx char-set-diff+intersection! char-set1 char-set2 char-set3 @dots{}
5646 [R7RS charset]
5647 @c MOD scheme.charset
5648 @c EN
5649 Returns two values, the result of
5650 @code{(char-set-difference char-set1 char-set2 @dots{}} and the result of
5651 @code{(char-set-intersection char-set1 char-set2 @dots{}}.
5652 @c JP
5653 @code{(char-set-difference char-set1 char-set2 @dots{}}の結果と
5654 @code{(char-set-intersection char-set1 char-set2 @dots{}}の結果の
5655 二つの値を返します。
5656 @c COMMON
5657 @end defun
5658
5659
5660 @node R7RS hash tables, R7RS immutable lists, R7RS character sets, R7RS large
5661 @subsection @code{scheme.hash-table} - R7RS hash tables
5662 @c NODE R7RSハッシュテーブル, @code{scheme.hash-table} - R7RSハッシュテーブル
5663
5664 @deftp {Module} scheme.hash-table
5665 @mdindex scheme.hash-table
5666 @c EN
5667 This module provides hash table library, originally defined as @code{srfi.125}.
5668
5669 Hash table provided with this module is the same as Gauche's built-in
5670 hash table. However, SRFI-125 introduces procedures that conflict
5671 with Gauche's original procedures, so Gauche provides those procedures
5672 built-in but under aliases.
5673 @xref{Hashtables}, for the built-in hash table procedures.
5674
5675 With this module, procedures are provided as defined in R7RS. Use this
5676 module when you're writing portable code.
5677 @c JP
5678 このモジュールは、元々@code{srfi.125}で定義されていたハッシュテーブルのライブラリです。
5679
5680 このモジュールで提供されるハッシュテーブルはGaucheの組み込みハッシュテーブルそのものです。
5681 ただ、SRFI-125はいくつか、Gaucheの元々持っていた手続きと名前が衝突する手続きを
5682 定義しています。Gaucheはそれらの手続きに関しては異なる名前で組み込み手続きを
5683 用意しています。組み込みのハッシュテーブル手続きについては
5684 @ref{Hashtables}を参照してください。
5685
5686 このモジュールを使うと、手続きはR7RSで定義されたとおりの動作になります。
5687 ポータブルなコードを書く際にこのモジュールを使うと良いでしょう。
5688 @c COMMON
5689
5690 @c EN
5691 SRFI-125 also defines compatibility procedures with SRFI-69, although saying
5692 they're deprecated. Those deprecated procedures are supported in this
5693 module, too.
5694 @c JP
5695 SRFI-125はまた、SRFI-69で定義されたいくつかの手続きを、非推奨ながら
5696 互換性のためにサポートしています。これらの非推奨手続きも
5697 このモジュールで提供されます。
5698 @c COMMON
5699
5700 @c EN
5701 The following procedures are the same as Gauche's built-in.
5702 @c JP
5703 以下の手続きはGaucheの組み込みと同じです。
5704 @c COMMON
5705 @example
5706 hash-table? hash-table-contains? hash-table-exists?
5707 hash-table-empty? hash-table=? hash-table-mutable?
5708 hash-table-ref hash-table-ref/default
5709 hash-table-set! hash-table-update!/default
5710 hash-table-clear! hash-table-size hash-table-keys
5711 hash-table-values hash-table-copy hash-table-empty-copy
5712 hash-table->alist hash-table-union! hash-table-intersection!
5713 hash-table-difference! hash-table-xor!
5714 @end example
5715
5716 @c EN
5717 @xref{Hashtables}, for the description of those procedures.
5718 @c JP
5719 これらの手続きの説明は@ref{Hashtables}を参照してください。
5720 @c COMMON
5721
5722 @c EN
5723 The following procedures are also provided as Gauche's built-in,
5724 but with @code{-r7} suffix.
5725 @c JP
5726 以下の手続きは、Gaucheの組み込みでは@code{-r7}サフィックスをつけた名前で
5727 提供されています。
5728 @c COMMON
5729 @example
5730 hash-table hash-table-delete! hash-table-intern!
5731 hash-table-update! hash-table-pop! hash-table-find
5732 hash-table-count hash-table-map hash-table-for-each
5733 hash-table-map! hash-table-map->list
5734 hash-table-prune!
5735 @end example
5736 @end deftp
5737
5738 @defun make-hash-table comparator arg @dots{}
5739 @defunx make-hash-table equal-proc hash-proc arg @dots{}
5740 [R7RS hash-table]
5741 @c MOD scheme.hash-table
5742 @c EN
5743 This enhances built-in @code{make-hash-table} with the second form,
5744 that takes two procedures instead of one comparator, as SRFI-69.
5745
5746 In the SRFI-69 form, @var{equal-proc} is a procedure taking two keys
5747 to see if they are the same, and @var{hash-proc} is a procedure taking
5748 a key to calculate its hash value (nonnegative fixnum).
5749 The compatibility form is deprecated and should be avoided in the new code.
5750
5751 The optional @var{arg} @dots{} are implementation-dependent,
5752 and specify various properties of the created hash table.
5753 They are ignored in Gauche.
5754 @c JP
5755 この手続きは、組み込みの@code{make-hash-table}を拡張して二番目の形式を許したものです。
5756 二番目の形式は比較器のかわりに二つの手続きをとるもので、SRFI-69互換です。
5757
5758 SRFI-69互換形式では、@var{equal-proc}はふたつのキーを取りそれが等しいかどうかを
5759 返す述語、@var{hash-proc}は一つのキーを取りそのハッシュ値を非負の正確な整数で
5760 返す手続きです。
5761 この互換係式は非推奨で、新たなコードでは使うべきではありません。
5762
5763 省略可能な@var{arg} @dots{}引数は実装依存で、作られるハッシュテーブルの
5764 様々な特性を指定するものです。Gaucheでは無視されます。
5765 @c COMMON
5766 @end defun
5767
5768 @defun hash-table cmpr key value @dots{}
5769 [R7RS hash-table]
5770 @c MOD scheme.hash-table
5771 @c EN
5772 This is the same as built-in @code{hash-table-r7} (@pxref{Hashtables}).
5773
5774 Construct a new hash table with key-comparator @var{cmpr}. It is
5775 populated by @var{key} @var{value} @dots{}, which is a list with
5776 keys and values appear alternatively. It is an error if the length
5777 of key-value list is not even.
5778
5779 Note that SRFI-125 defines this procedure to return an immutable
5780 hash table if the implementation supports one. Gauche doesn't provide
5781 immutable hash tables (we do have immutable map
5782 instead, @pxref{Immutable map}), but when you're writing a portable
5783 program, be careful not to modify the table returned by this procedure.
5784 @c JP
5785 これは組み込みの@code{hash-table-r7}と同じです(@ref{Hashtables}参照)。
5786
5787 キーの比較とハッシュに比較器@var{cmpr}を使う新たなハッシュテーブルを作って返します。
5788 また、ハッシュテーブルの内容は@var{key} @var{value} @dots{}によって初期化されます。
5789 ここで引数はキーと値が交互に並んだものです。@var{key} @var{value} @dots{}部分の
5790 長さが偶数でなければエラーが投げられます。
5791
5792 SRFI-125では、この手続きは(実装がサポートしていれば)変更不可なハッシュテーブルを
5793 返すと規定されています。Gaucheは変更不可なハッシュテーブルを持っていないので、
5794 変更可能なハッシュテーブルが返りますが、ポータブルなコードを書く際には
5795 返されたテーブルを変更しないようにしてください。
5796 なお、Gaucheも変更不可なマップは持っています (@ref{Immutable map}参照)。
5797 @c COMMON
5798 @end defun
5799
5800 @defun alist->hash-table alist cmpr arg @dots{}
5801 @defunx alist->hash-table alist equal-proc hash-proc cmpr arg @dots{}
5802 [R7RS hash-table]
5803 @c MOD scheme.hash-table
5804 @c EN
5805 This enhances built-in @code{alist->hash-table} with the second form,
5806 that takes two procedures instead of one comparator, as SRFI-69.
5807
5808 In the SRFI-69 form, @var{equal-proc} is a procedure taking two keys
5809 to see if they are the same, and @var{hash-proc} is a procedure taking
5810 a key to calculate its hash value (nonnegative fixnum).
5811 The compatibility form is deprecated and should be avoided in the new code.
5812
5813 The optional @var{arg} @dots{} are implementation-dependent,
5814 and specify various properties of the created hash table.
5815 They are ignored in Gauche.
5816 @c JP
5817 この手続きは、組み込みの@code{alist->hash-table}を拡張して二番目の形式を許したものです。
5818 二番目の形式は比較器のかわりに二つの手続きをとるもので、SRFI-69互換です。
5819
5820 SRFI-69互換形式では、@var{equal-proc}はふたつのキーを取りそれが等しいかどうかを
5821 返す述語、@var{hash-proc}は一つのキーを取りそのハッシュ値を非負の正確な整数で
5822 返す手続きです。
5823 この互換係式は非推奨で、新たなコードでは使うべきではありません。
5824
5825 省略可能な@var{arg} @dots{}引数は実装依存で、作られるハッシュテーブルの
5826 様々な特性を指定するものです。Gaucheでは無視されます。
5827 @c COMMON
5828 @end defun
5829
5830 @defun hash-table-unfold p f g seed comparator :optional arg @dots{}
5831 [R7RS hash-table]
5832 @c MOD scheme.hash-table
5833 @c EN
5834 Same as Gauche's built-in @code{hash-table-unfold}, except that this
5835 allows optional arguments, which are ignored. They are
5836 implementation-specific parameters to tune the created hash tables.
5837 @xref{Hashtables}, for the detailed description.
5838 @c JP
5839 省略可能な@var{arg} @dots{}を許すことを除いて、
5840 Gauche組み込みの@code{hash-table-unfold}と同じです。
5841 @var{arg} @dots{}は作られるテーブルのパラメータを与える実装依存な引数で、
5842 Gaucheでは今のところ無視されます。
5843 詳しくは@ref{Hashtables}を参照してください。
5844 @c COMMON
5845 @end defun
5846
5847
5848 @defun hash-table-delete! ht key @dots{}
5849 [R7RS hash-table]
5850 @c MOD scheme.hash-table
5851 @c EN
5852 This is the same as built-in @code{hash-table-delete!-r7}.
5853
5854 Deletes entries associated with the given @var{key}s from the
5855 table @var{ht}. It is ok if @var{ht} doesn't have @var{key}.
5856 Returns the number of entries that are actually deleted.
5857
5858 It differs from built-in @code{hash-table-delete!} in two points:
5859 The built-in one can take exactly one @var{key}, and returns
5860 a boolean indicating if the entry is actually deleted.
5861 @c JP
5862 これは組み込みの@code{hash-table-delete!-r7}と同じです。
5863
5864 ハッシュテーブル@var{ht}から、@var{key} @dots{}を持つエントリを削除します。
5865 @var{ht}が@var{key}を持っていなくてもエラーにはなりません。
5866 実際に削除されたエントリの数を返します。
5867
5868 組み込みの@code{hash-table-delete!}と違うのは次の2点です。
5869 組み込みはkeyをひとつしか取らず、それが実際に削除されたかどうかをブール値で返します。
5870 @c COMMON
5871 @end defun
5872
5873 @defun hash-table-intern! ht key failure
5874 [R7RS hash-table]
5875 @c MOD scheme.hash-table
5876 @c EN
5877 This is the same as built-in @code{hash-table-intern!-r7}.
5878
5879 Search @var{key} in @var{ht}. If it is found, returns the associated
5880 value. If it is not found, call @var{failure} without artuments,
5881 and insert a new entry associating @var{key} and the value
5882 @var{failure} returns, and returns that new value.
5883 @c JP
5884 これは組み込みの@code{hash-table-intern!-r7}と同じです。
5885
5886 ハッシュテーブル@var{ht}からキー@var{key}を持つエントリを探し、
5887 見つかった場合はその値を返します。見つからなかった場合は、手続き@var{failure}を
5888 引数無しで呼び出し、その返り値を@var{key}に結びついた新たなエントリとして
5889 @var{ht}に追加し、また@code{hash-table-intern!}の返り値とします。
5890 @c COMMON
5891 @end defun
5892
5893 @defun hash-table-update! ht key updater :optional failure success
5894 [R7RS hash-table]
5895 @c MOD scheme.hash-table
5896 @c EN
5897 This is the same as built-in @code{hash-table-update!-r7}.
5898 It takes different optional arguments from built-in @code{hash-table-update!}.
5899 @c JP
5900 これは組み込みの@code{hash-table-update!-r7}と同じです。
5901 組み込みの@code{hash-table-update!}とは取る引数が異なります。
5902 @c COMMON
5903
5904 @c EN
5905 @var{Updater} is a procedure that takes one argument,
5906 @var{failure} is a thunk, and @var{success} is a procedure
5907 that takes one argument.
5908 @c JP
5909 @var{updater}は1引数の手続き、
5910 @var{failure}はサンク、@var{success}は1引数の手続きです。
5911 @c COMMON
5912
5913 @c EN
5914 Works the same as follows, except maybe more efficiently.
5915 @c JP
5916 次の式と同様に動作しますが、より効率が良いかもしれません。
5917 @c COMMON
5918 @example
5919 (hash-table-set! ht key (updater (hash-table-ref ht key failure success)))
5920 @end example
5921 @end defun
5922
5923 @defun hash-table-pop! ht
5924 [R7RS hash-table]
5925 @c MOD scheme.hash-table
5926 @c EN
5927 This is the same as built-in @code{hash-table-pop!-r7}.
5928 It is a completely different procedure as built-in @code{hash-table-pop!}.
5929 @c JP
5930 これは組み込みの@code{hash-table-pop!-r7}と同じです。
5931 組み込みの@code{hash-table-pop!}とは全く異なる手続きです。
5932 @c COMMON
5933
5934 @c EN
5935 Removes an arbitrary entry in the hash table @var{ht}, and
5936 returns the removed entry's key and value as two values.
5937 @c JP
5938 @var{ht}から任意のエントリをひとつ削除じ、削除したエントリのキーと値を
5939 二つの返り値として返します。
5940 @c COMMON
5941
5942 @c EN
5943 If @var{ht} is empty, an error is signalled.
5944 @c JP
5945 @var{ht}が空であればエラーが投げられます。
5946 @c COMMON
5947 @end defun
5948
5949 @defun hash-table-find proc ht failure
5950 [R7RS hash-table]
5951 @c MOD scheme.hash-table
5952 @c EN
5953 This is the same as built-in @code{hash-table-find-r7}.
5954 It takes different arguments from built-in @code{hash-table-find}.
5955 @c JP
5956 これは組み込みの@code{hash-table-find-r7}と同じです。
5957 組み込みの@code{hash-table-find}とは引数が異なります。
5958 @c COMMON
5959
5960 @c EN
5961 Calls @var{proc} with a key and a value of each entry in @var{ht},
5962 until @var{proc} returns non-false value. If @var{proc} returns
5963 non-false value, @code{hash-table-find} immediately returns it.
5964 If @var{proc} returns @code{#f} for all entries, calls a thunk
5965 @var{failure} and returns its result.
5966 @c JP
5967 @var{ht}内のひとつのキーと値を引数にして@var{proc}を呼び出します。
5968 @var{proc}が真の値を返したら、@code{hash-table-find}はそれを直ちに返します。
5969 そうでなければ、別のキーと値で@var{proc}を呼び出し、全てのキーと値について
5970 試すまで繰り返します。
5971 全てのキーと値について@var{proc}が偽を返した場合は、@var{failure}サンクを呼び出し
5972 それを結果とします。
5973 @c COMMON
5974 @end defun
5975
5976 @defun hash-table-count proc ht
5977 [R7RS hash-table]
5978 @c MOD scheme.hash-table
5979 @c EN
5980 This is the same as built-in @code{hash-table-count-r7}.
5981 @c JP
5982 これは組み込みの@code{hash-table-count-r7}と同じです。
5983 @c COMMON
5984
5985 @c EN
5986 Calls @var{proc} with a key and a value of each entry in @var{ht},
5987 and returns the number of times when @var{proc} returned true.
5988 @c JP
5989 ハッシュテーブル@var{ht}の各エントリについて@var{proc}をキーと値を引数にして呼び出し、
5990 @var{proc}が真の値を返した回数をこの手続きの値とします。
5991 @c COMMON
5992 @end defun
5993
5994 @defun hash-table-map proc cmpr ht
5995 [R7RS hash-table]
5996 @c MOD scheme.hash-table
5997 @c EN
5998 This is the same as built-in @code{hash-table-map-r7}.
5999 This is different from built-in @code{hash-table-map}.
6000 @c JP
6001 これは組み込みの@code{hash-table-map-r7}と同じです。
6002 組み込みの@code{hash-table-map}とは異なる手続きです。
6003 @c COMMON
6004
6005 @c EN
6006 Creates a fresh hashtable with a key comparator @var{cmpr}, then
6007 populate it by inserting the key and the result of applying @var{proc}
6008 on the value of each entry in @var{ht}.
6009 @c JP
6010 キーの比較を比較器@var{cmpr}で行う新たなハッシュテーブルを作成し、
6011 @var{ht}の各エントリのキーと値を@var{proc}に渡し、
6012 新たなハッシュテーブルにそのキーと@var{proc}の戻り値を新たなエントリとして作成します。
6013 @c COMMON
6014 @end defun
6015
6016 @defun hash-table-map! proc ht
6017 [R7RS hash-table]
6018 @c MOD scheme.hash-table
6019 @c EN
6020 This is the same as built-in @code{hash-table-map!-r7}.
6021 @c JP
6022 これは組み込みの@code{hash-table-map-r7!}と同じです。
6023 @c COMMON
6024
6025 @c EN
6026 Calls @var{proc} on the key and value of each entry in @var{ht}, and update
6027 the entry of the key with the result of @var{proc}.
6028 @c JP
6029 @var{proc}を@var{ht}の各エントリのキーと値を引数にして呼び出し、
6030 そのキーに対応する値を@var{proc}の戻り値で置き換えます。
6031 @c COMMON
6032 @end defun
6033
6034 @defun hash-table-map->list proc ht
6035 [R7RS hash-table]
6036 @c MOD scheme.hash-table
6037 @c EN
6038 This is the same as built-in @code{hash-table-map->list-r7},
6039 and same as built-in @code{hash-table-map} (not the @code{scheme.hash-table}'s
6040 @code{hash-table-map}) except the order of the arguments.
6041 @c JP
6042 これは組み込みの@code{hash-table-map->list-r7}と同じで、
6043 また組み込みの@code{hash-table-map}とは引数の順序が異なるだけの違いです
6044 (@code{scheme.hash-table}の@code{hash-table-map}は全然異なる手続きです)。
6045 @c COMMON
6046
6047 @c EN
6048 Apply @var{proc} on a key and a value of each entry in @var{ht},
6049 in arbitrary order, and returns a list of results.
6050 @c JP
6051 @var{ht}の各エントリのキーと値に対して@var{proc}を呼び出し、その結果をリストにして
6052 返します。エントリの順序は規定されません。
6053 @c COMMON
6054 @end defun
6055
6056 @defun hash-table-for-each proc ht
6057 @defunx hash-table-for-each ht proc
6058 [R7RS hash-table]
6059 @c MOD scheme.hash-table
6060 @c EN
6061 Apply @var{proc} on a key and a value of each entry in @var{ht}. The
6062 result of @var{proc} is discarded. Returns an unspecified value.
6063 @c JP
6064 @var{proc}を@var{ht}の各エントリのキーと値を引数にして呼び出します。
6065 @var{proc}の戻り値は捨てられます。この手続きの戻り値は定義されません。
6066 @c COMMON
6067
6068 @c EN
6069 This procedure allows arguments in both order for the compatibility---
6070 the first way is the @code{scheme.hash-table} recommended one,
6071 which is the same as built-in @code{hash-table-for-each-r7},
6072 and the latter way is compatible with SRFI-69, which is
6073 the same as built-in @code{hash-table-for-each}.
6074 @c JP
6075 この手続きは、互換性のために2通りの順序で引数を取ります。
6076 @code{scheme.hash-table}が推奨するのは最初の方法です。
6077 組み込みの@code{hash-table-for-each-r7}も同じです。
6078 二番目の呼び出しはSRFI-69で規定されていた方法で、
6079 組み込みの@code{hash-table-for-each}はこちらの順序です。
6080 @c COMMON
6081
6082 @c EN
6083 It is unfortunate that this compatibility thing is extremely confusing;
6084 especially in Gauche, you can make anything applicable, so the distinction
6085 between procedures and other objects is blurred.
6086 @c JP
6087 残念ながら、この互換性の問題は大きな混乱のもとになるでしょう。
6088 特にGaucheでは色々なオブジェクトを適用可能にできるので、
6089 手続きとそれ以外のオブジェクトの境目ははっきりしていません。
6090 @c COMMON
6091
6092 @c EN
6093 We recommend that you stick to one way or another within a module; if
6094 your module uses built-in interface, use @code{(hash-table-for-each ht proc)}.
6095 If your module imports @code{scheme.hash-table},
6096 use @code{(hash-table-for-each proc ht)}.
6097 @c JP
6098 ひとつのモジュール内では統一した順序で呼び出すことを推奨します。
6099 組み込みのハッシュテーブルAPIを使っているなら@code{(hash-table-for-each ht proc)}の
6100 順序を、@code{scheme.hash-table}をインポートしたなら
6101 @code{(hash-table-for-each proc ht)}という順序を使うと良いでしょう。
6102 @c COMMON
6103 @end defun
6104
6105 @defun hash-table-fold proc seed ht
6106 @defunx hash-table-fold ht proc seed
6107 [R7RS hash-table]
6108 @c MOD scheme.hash-table
6109 @c EN
6110 The @var{proc} argument takes three arguments, a key, a value, and
6111 the current seed value. The procedure applies @var{proc} for
6112 each entry in @var{ht}, using @var{seed} as the first seed value,
6113 and using the previous result of @var{proc} as the subsequent seed value.
6114 Returns the result of the last call of @var{seed}.
6115 @c JP
6116 @var{proc}は、キー、対応する値、シード値の3つの引数を取る手続きです。
6117 @code{hash-table-fold}はハッシュテーブル@var{ht}のそれぞれのエントリについて、
6118 @var{proc}を呼び出します。シード値の初期値は@var{seed}で、
6119 以降は一つ前の@var{proc}の戻り値が次のシード値として渡されてゆき、
6120 最後の@var{proc}呼び出しの戻り値が全体の戻り値となります。
6121 @c COMMON
6122
6123 @c EN
6124 This procedure allows arguments in both order for the compatibility---
6125 the first way is the @code{scheme.hash-table} recommended one,
6126 which is the same as built-in @code{hash-table-fold-r7},
6127 and the latter way is compatible with SRFI-69, which is
6128 the same as built-in @code{hash-table-fold}.
6129 @c JP
6130 この手続きもまた、互換性のために二つのインタフェースを用意しています。
6131 最初のインタフェースは@code{scheme.hash-table}ライブラリ推奨のもので、
6132 Gauche組み込みの@code{hash-table-fold-r7}と同じです。
6133 後者はSRFI-69およびGauche組み込みの@code{hash-table-fold}と同じです。
6134 @c COMMON
6135
6136 @c EN
6137 It is unfortunate that this compatibility thing is extremely confusing.
6138 We recommend that you stick to one way or another within a module; if
6139 your module uses built-in interface, use the second interface.
6140 If your module is for portable R7RS code,
6141 use the first interface.
6142 @c JP
6143 歴史的経緯とはいえ、ふたつの紛らわしいインタフェースが併存するのは残念なことです。
6144 一つのモジュール内では混乱を避けるため、どちらかに統一した方が良いでしょう。
6145 Gauche組み込みのハッシュテーブルインタフェースを他にも使っているなら後者で、
6146 ポータブルなR7RSコードを書いているなら前者で。
6147 @c COMMON
6148 @end defun
6149
6150 @defun hash-table-prune! proc ht
6151 [R7RS hash-table]
6152 @c MOD scheme.hash-table
6153 @c EN
6154 This is the same as built-in @code{hash-table-prune!-r7}.
6155 @c JP
6156 組み込みの@code{hash-table-prune!-r7}と同じです。
6157 @c COMMON
6158
6159 @c EN
6160 Apply @var{proc} on a key and a value of each entry in @var{ht},
6161 and deletes the entry if @var{proc} returns a true value.
6162 This procedure returns an unspecified value.
6163 @c JP
6164 @var{ht}の各エントリについて、@var{proc}をキーと値を引数として呼び出し、
6165 @var{proc}が真の値を返したエントリを@var{ht}から削除します。
6166 戻り値は規定されていません。
6167 @c COMMON
6168 @end defun
6169
6170 @defun hash-table-merge! ht1 ht2
6171 [R7RS hash-table]
6172 @c MOD scheme.hash-table
6173 @c DEPRECATED
6174 @c EN
6175 This is the same as @code{hash-table-union!}, and provided just
6176 for the compatibility with SRFI-69.
6177 @c JP
6178 これは@code{hash-table-union!}と同じで、
6179 SRFI-69との互換性のためだけに提供されています。
6180 @c COMMON
6181 @end defun
6182
6183 @defun hash obj :optional ignore
6184 @defunx string-hash obj :optional ignore
6185 @defunx string-ci-hash obj :optional ignore
6186 @defunx hash-by-identity obj :optional ignore
6187 [R7RS hash-table]
6188 @c MOD scheme.hash-table
6189 @c EN
6190 Provided for the compatibility with SRFI-69, and are deprecated.
6191 @c JP
6192 SRFI-69互換性のために提供されているハッシュ関数です。非推奨です。
6193 @c COMMON
6194
6195 @c EN
6196 The first three are the same as built-in @code{default-hash},
6197 @code{string-hash}, and @code{string-ci-hash}, except that
6198 these accept an optional second argument, which is ignored.
6199 Note that @code{hash-by-identity} is also defined as the same
6200 as @code{default-hash} except the ignored optional second argument,
6201 per SRFI-125, although the name suggests that it would work as if
6202 @code{eq-hash}.
6203 @c JP
6204 最初の3つの手続きは、無視される省略可能引数を取ることを除いて、
6205 組み込みの@code{default-hash}、@code{string-hash}、@code{string-ci-hash}
6206 とそれぞれ同じです。
6207 @code{hash-by-identity}も省略可能引数を除いては@code{default-hash}と
6208 同じです。名前から@code{eq-hash}のように思えるかもしれませんが、
6209 SRFI-125で@code{default-hash}と同じと規定されています。
6210 @c COMMON
6211
6212 @c EN
6213 Do not use these procedures in the new code; you can use comparators
6214 instead (@code{default-comparator}, @code{string-comparator},
6215 @code{string-ci-comparator} and @code{eq-comparator},
6216 @pxref{Predefined comparators}). If you do need hash function,
6217 you should still avoid @code{hash} and @code{hash-by-identity},
6218 and use @code{default-hash} and @code{eq-hash} instead.
6219 @c JP
6220 新しいコードではこれらを使わず、
6221 (@code{default-comparator}、@code{string-comparator}、
6222 @code{string-ci-comparator}、@code{eq-comparator}等の
6223 比較器を渡すようにしてください (@ref{Predefined comparators}参照)。
6224 たとえハッシュ関数を渡す必要があったとしても、
6225 @code{hash}と@code{hash-by-identity}の使用は避け、
6226 かわりに@code{default-hash}や@code{eq-hash}を使いましょう。
6227 @c COMMON
6228 @end defun
6229
6230 @defun hash-table-equivalence-function ht
6231 @defunx hash-table-hash-function ht
6232 [R7RS hash-table]
6233 @c MOD scheme.hash-table
6234 @c EN
6235 Provided for the compatibility with SRFI-69, and are deprecated.
6236 @c JP
6237 SRFI-69との互換性のために提供されている手続きで、非推奨です。
6238 @c COMMON
6239
6240 @c EN
6241 Returns the equivalence function and hash function of a hash table @var{ht}.
6242 @c JP
6243 ハッシュテーブル@var{ht}の等値判定手続きとハッシュ手続きをそれぞれ返します。
6244 @c COMMON
6245
6246 @c EN
6247 Note that SRFI-69's hash function takes an optional @var{bound} argument;
6248 so, if you build @var{ht} with a comparator or a hash function that does
6249 not take optional argument, @code{hash-table-hash-function} wraps the
6250 real hash function with a procedure that allows optional @var{bound}
6251 argument.
6252 @c JP
6253 SRFI-69ではハッシュ関数は省略可能な@var{bound}引数を取るというプロトコルになっています。
6254 そこで、@var{ht}が比較器、もしくは省略可能引数を取らないハッシュ関数から
6255 作られていた場合、@code{hash-table-hash-function}は元のハッシュ関数をラップして、
6256 省略可能引数@var{bound}を取るようにした手続きを返します。
6257 @c COMMON
6258
6259 @c EN
6260 For the introspection, we recommend to use
6261 built-in @code{hash-table-comparator} (@pxref{Hashtables}).
6262 @c JP
6263 ハッシュテーブルのイントロスペクションには、@code{hash-table-comparator}で
6264 比較器を取り出す方が良いでしょう (@ref{Hashtables}参照)。
6265 @c COMMON
6266 @end defun
6267
6268
6269 @node R7RS immutable lists, R7RS random-access lists, R7RS hash tables, R7RS large
6270 @subsection @code{scheme.ilist} - R7RS immutable lists
6271 @c NODE R7RS変更不可リスト, @code{scheme.ilist} - R7RS変更不可リスト
6272
6273 @deftp {Module} scheme.ilist
6274 @mdindex scheme.ilist
6275 @findex proper-ilist?
6276 @findex ilist?
6277 @findex dotted-ilist?
6278 @findex not-ipair?
6279 @findex null-ilist?
6280 @findex ilist=
6281 @findex icar
6282 @findex icdr
6283 @findex icaar
6284 @findex icadr
6285 @findex icdar
6286 @findex icddr
6287 @findex icaaar
6288 @findex icaadr
6289 @findex icadar
6290 @findex icaddr
6291 @findex icdaar
6292 @findex icdadr
6293 @findex icddar
6294 @findex icdddr
6295 @findex icaaaar
6296 @findex icaaadr
6297 @findex icaadar
6298 @findex icaaddr
6299 @findex icadaar
6300 @findex icadadr
6301 @findex icaddar
6302 @findex icadddr
6303 @findex icdaaar
6304 @findex icdaadr
6305 @findex icdadar
6306 @findex icdaddr
6307 @findex icddaar
6308 @findex icddadr
6309 @findex icdddar
6310 @findex icddddr
6311 @findex icar+icdr
6312 @findex ilist-ref
6313 @findex ifirst
6314 @findex isecond
6315 @findex ithird
6316 @findex ifourth
6317 @findex ififth
6318 @findex isixth
6319 @findex iseventh
6320 @findex ieighth
6321 @findex ininth
6322 @findex itenth
6323 @findex idrop
6324 @findex ilist-tail
6325 @findex itake-right
6326 @findex ilast
6327 @findex last-ipair
6328 @findex ilength
6329 @findex icount
6330 @findex ifor-each
6331 @findex ifold
6332 @findex ipair-fold
6333 @findex ireduce
6334 @findex ifold-right
6335 @findex ipair-fold-right
6336 @findex ireduce-right
6337 @findex ipair-for-each
6338 @findex imember
6339 @findex imemv
6340 @findex imemq
6341 @findex ifind-tail
6342 @findex iany
6343 @findex ievery
6344 @findex ilist-index
6345 @findex idrop-while
6346 @findex iassoc
6347 @findex iassq
6348 @findex iassv
6349 @findex iapply
6350 @findex make-ilist-comparator
6351 @findex make-improper-ilist-comparator
6352 @findex make-icar-comparator
6353 @findex make-icdr-comparator
6354 @findex make-ipair-comparator
6355 @c EN
6356 This module provides a set of procedures that handles immutable pairs
6357 and lists.
6358
6359 The standard allows an implementation to have mutable pairs and immutable
6360 pairs separately, so it defines immutable version of most @code{scheme.list}
6361 procedures. In Gauche, mutable pairs and immutable pairs are both
6362 abstract ``pairs'', and all procedures that accesses pairs (without modifying
6363 them) works seamlessly on both kind.
6364
6365 Consequently, the following procedures are just aliases of their
6366 non-immutable versions (just remove @code{i} prefix from them).
6367 Note that these procedures and variables in Gauche do not reject if the input is
6368 mutable pairs/lists, but such usage may not be portable
6369 (@pxref{Mutable and immutable pairs}).
6370 @c JP
6371 このモジュールは変更不可なペアとリストを扱う手続きを提供します。
6372
6373 規格では、Scheme実装は変更可能なペアと変更不可能なペアを別の型として持つことを許していて、
6374 そのためこのモジュールでは@code{scheme.list}にある多くの手続きの変更不可ペア用バージョンを
6375 提供しています。
6376 しかしGaucheは、変更可能なペアも変更不可なペアもどちらも「ペア」として扱い、
6377 ペアにアクセスする手続きは(ペアを破壊的変更しない限り)変更不可なペアにもそのまま使えます
6378 (@ref{Mutable and immutable pairs}参照)。
6379
6380 従って、このモジュールが提供する手続きは単に変更可能ペア用バージョンの別名になっています。
6381 (名前から@code{i}プレフィクスを除いたものが対応する手続きです)。
6382 このモジュールの手続きは、変更可能なペアが与えられてもエラーにしないことに注意してください。
6383 Gaucheではそれらを区別しませんが、区別する処理系ではエラーになるかもしれません。
6384 @c COMMON
6385
6386 @example
6387 proper-ilist? ilist? dotted-ilist? not-ipair?
6388 null-ilist? ilist=
6389 icar icdr icaar icadr
6390 icdar icddr icaaar icaadr
6391 icadar icaddr icdaar icdadr
6392 icddar icdddr icaaaar icaaadr
6393 icaadar icaaddr icadaar icadadr
6394 icaddar icadddr icdaaar icdaadr
6395 icdadar icdaddr icddaar icddadr
6396 icdddar icddddr icar+icdr ilist-ref
6397 ifirst isecond ithird ifourth
6398 ififth isixth iseventh ieighth
6399 ininth itenth
6400 idrop ilist-tail itake-right
6401 ilast last-ipair ilength icount
6402 ifor-each ifold ipair-fold ireduce
6403 ifold-right ipair-fold-right ireduce-right ipair-for-each
6404 imember imemv imemq ifind-tail
6405 iany ievery ilist-index idrop-while
6406 iassoc iassq iassv iapply
6407 make-ilist-comparator make-improper-ilist-comparator
6408 make-icar-comparator make-icdr-comparator
6409 make-ipair-comparator
6410 @end example
6411 @end deftp
6412
6413 @node R7RS random-access lists, R7RS immutable deques, R7RS immutable lists, R7RS large
6414 @subsection @code{scheme.rlist} - R7RS random-access lists
6415 @c NODE R7RSランダムアクセスリスト, @code{scheme.rlist} - R7RSランダムアクセスリスト
6416
6417 @deftp {Module} scheme.rlist
6418 @mdindex scheme.rlist
6419 @c EN
6420 This module provides an alternative datatype for pairs and lists,
6421 which are immutable and allows O(log n) random access, while
6422 maintaining O(1) @code{car} and @code{cdr} operations.
6423 This is originally defined as @code{srfi.101}. We call this datatype
6424 @emph{rlist} in the following explanation.
6425 @c JP
6426 このモジュールは、変更不可で、ランダムアクセスがO(log n)であるような、
6427 ペアとリストに替わるデータ構造を提供します。@code{car}と@code{cdr}はO(1)です。
6428 元は@code{srfi.101}として定められました。
6429 ここでは、このデータ型を@emph{rlist}と呼ぶことにします。
6430 @c COMMON
6431
6432 @c EN
6433 The srfi allows a Scheme implementation to adopt rlist
6434 as the built-in pairs and lists, so the procedure names are
6435 duplicated from the Scheme primitives. If you use this module,
6436 you might want to import with prefix
6437 (e.g. @code{(use scheme.rlist :prefix rlist:)}).
6438 @c JP
6439 このsrfiでは、組み込みのペアとリストとしてrlistを選択するScheme処理系も可能なように
6440 書かれています。そのため、手続き名がSchemeのペアやリストを扱うプリミティブと
6441 重複しています。このモジュールを使う際には、
6442 @code{(use scheme.rlist :prefix rlist:)}といった具合にプリフィクスつきで
6443 インポートすると良いでしょう。
6444 @c COMMON
6445
6446 @c EN
6447 In Gauche, we implement rlist on top of skew-list
6448 (@pxref{Skew binary random-access lists}). The main difference
6449 is that skew-list only allows proper lists, while rlist allows
6450 improper lists (the @code{cdr} of the last pair can be an arbitrary
6451 objects).
6452 @c JP
6453 Gaucheでは、rlistはskew-list (@ref{Skew binary random-access lists}参照) の上に
6454 実装されています。skew-listとの大きな違いは、skew-listは常に真正リストですが、
6455 rlistはドットリストが許されることです。(つまり、rlistの最後のペアの@code{cdr}には
6456 どんなオブジェクトも許されます。)
6457 @c COMMON
6458
6459 @c EN
6460 However, having improper lists makes things a lot complicated. If you just
6461 need a list with fast random access, you want to use skew-list.
6462 Use rlist only if you need to deal with improper lists.
6463 @c JP
6464 ただ、真正でないリストを扱うために内部では面倒なことをしています。
6465 速いランダムアクセス可能なリストが必要なら、skew-listをそのまま使った方が良いです。
6466 その上で非真正リストを扱う必要がある場合だけ、このモジュールを使うのが良いでしょう。
6467 @c COMMON
6468
6469 @c EN
6470 The following procedures behave just like the built-in counterparts,
6471 except they take/return rlists instead of ordinary pairs and lists.
6472 (NB: @code{list-ref} and @code{list-tail} here doesn't take the optional
6473 fallback argument, for they are Gauche's extension).
6474 @c JP
6475 次の手続きは、引数や戻り値がrlistであること以外は、組み込みの同名の手続きと同じ動作をします。
6476 (註: このモジュールの@code{list-ref}と@code{list-tail}は省略可能引数を取りません。
6477 通常のリストに対する@code{list-ref}と@code{list-tail}が省略可能引数を取るのは
6478 Gaucheの独自拡張だからです。)
6479 @c COMMON
6480
6481 @example
6482 pair? cons car cdr
6483 caar cadr cdar cddr
6484 caaar caadr cadar caddr
6485 cdaar cdadr cddar cdddr
6486 caaaar caaadr caadar caaddr
6487 cadaar cadadr caddar cadddr
6488 cdaaar cdaadr cdadar cdaddr
6489 cddaar cddadr cdddar cddddr
6490 null? list? list make-list
6491 length append reverse list-tail
6492 list-ref map for-each
6493 @end example
6494
6495 @c EN
6496 This module also exports a syntax @code{quote}, which denotes
6497 the literal rlist. @code{(quote (a (b c)))} becomes a literal
6498 rlist consists of elements @code{a}, and an rlist consists
6499 of @code{b} and @code{c}.
6500 @c JP
6501 このモジュールはまた、リテラルのrlistを書くめの@code{quote}という構文もエクスポートします。
6502 @code{(quote (a (b c)))}は、
6503 @code{a}および、「@code{b}と@code{c}を要素に持つrlist」のrlistになります。
6504 @c COMMON
6505
6506 @c EN
6507 Note that if you import @code{scheme.rlist} without suffix,
6508 the shorthand notation @code{'(a (b c))} refers to @code{scheme.rlist#quote},
6509 instead of built-in @code{quote}.
6510 @c JP
6511 @code{scheme.rlist}をプリフィクスなしでインポートした場合、
6512 @code{'(a (b c))}は組み込みの@code{quote}ではなく@code{scheme.rlist#quote}を
6513 使うことに注意してください。
6514 @c COMMON
6515 @end deftp
6516
6517 @defun list-set rlist k obj
6518 [R7RS rlist]
6519 @c MOD scheme.rlist
6520 @c EN
6521 Returns a new rlist which is the same as @var{rlist} except
6522 that its @var{k}-th element is replaced with @var{obj}.
6523 This is O(log n) operation where n is the length of @var{rlist}.
6524 @c JP
6525 元の@var{rlist}のうち、@var{k}番目の要素が@var{obj}に置き換えられた
6526 @var{rlist}を作って返します。@var{rlist}の長さをnとした時、
6527 O(log n)の操作です。
6528 @c COMMON
6529 @end defun
6530
6531 @defun list-ref/update rlist k proc
6532 [R7RS rlist]
6533 @c MOD scheme.rlist
6534 @c EN
6535 Returns two values, the result of @code{(list-ref rlist k)}
6536 and the result of @code{(list-set rlist k (proc (list-ref rlist k)))},
6537 but may be more efficient.
6538 @c JP
6539 @code{(list-ref rlist k)}の結果と、
6540 @code{(list-set rlist k (proc (list-ref rlist k)))}の結果という二つの値を返します。
6541 ただし、別々に呼び出すよりは効率が良いかもしれません。
6542 @c COMMON
6543 @end defun
6544
6545 @defun random-access-list->linear-access-list rlist
6546 [R7RS rlist]
6547 @c MOD scheme.rlist
6548 @c EN
6549 Convert a proper rlist to an ordinary list. An error is
6550 thrown when @var{rlist} is not proper.
6551 The conversion is only done in the ``spine'' of @var{rlist}; that is,
6552 if @var{rlist} is nested, only the outermost @var{rlist} is converted.
6553 @c JP
6554 真正のrlistと同じ要素を持つ通常のリストを返します。
6555 @var{rlist}が真正でなければエラーが投げられます。
6556 変換は@var{rlist}の「背骨」に対してのみ行われることに注意してください。
6557 @var{rlist}がネストしていた場合、一番外側の@var{rlist}だけが変換されます。
6558 @c COMMON
6559 @end defun
6560
6561 @defun linear-access-list->random-access-list list
6562 [R7RS rlist]
6563 @c MOD scheme.rlist
6564 @c EN
6565 Convert a proper ordinary list to an rlist.
6566 An error is thrown when @var{list} is not proper.
6567 The conversion is only done in the ``spine'' of @var{list}; that is,
6568 if @var{list} is nested, only the outermost @var{list} is converted.
6569 @c JP
6570 通常の真正リスト@var{list}と同じ要素を持つrlistを返します。
6571 @var{list}が真正でなければエラーが投げられます。
6572 変換は@var{list}の「背骨」に対してのみ行われることに注意してください。
6573 @var{list}がネストしていた場合、一番外側の@var{list}だけが変換されます。
6574 @c COMMON
6575 @end defun
6576
6577
6578 @node R7RS immutable deques, R7RS immutable texts, R7RS random-access lists, R7RS large
6579 @subsection @code{scheme.ideque} - R7RS immutable deques
6580 @c NODE R7RS変更不可な両端キュー, @code{scheme.ideque} - R7RS変更不可な両端キュー
6581
6582 @deftp {Module} scheme.ideque
6583 @mdindex scheme.ideque
6584 @c EN
6585 This module provides a functional double-ended queue
6586 (deque, pronounced as ``deck''),
6587 with amortized O(1) access of queue operations on either end.
6588 @c JP
6589 このモジュールは、関数的な両端キュー (deque:「デック」と読みます) を提供します。
6590 どちらの端からのキュー操作もO(1)償却時間で可能です。
6591 @c COMMON
6592
6593 @c EN
6594 It also serves as a convenient bidirectional list structures
6595 in a sense that operations from the end of the list is just as
6596 efficient as the ones from the front.
6597 @c JP
6598 dequeはまた、どちらの方向からでもトラバースできるリストとして使うこともできます。
6599 @c COMMON
6600
6601 @c EN
6602 Note: If you don't need immutability and wants space-efficient
6603 deque, you can also use @code{data.ring-buffer} as a deque
6604 (@pxref{Ring buffer}).
6605 @c JP
6606 註: 変更不可である必要がなく、メモリ効率の良いdequeが必要なら、
6607 @code{data.ring-buffer}をdequeとして使うことができます(@ref{Ring buffer}参照)。
6608 @c COMMON
6609
6610 @c EN
6611 This module was originally defined as @code{srfi.134}, then
6612 became a part of R7RS large.
6613 @c JP
6614 このモジュールは@code{srfi.134}として定義され、R7RS largeに取り込まれました。
6615 @c COMMON
6616
6617 @c EN
6618 Gauche's @code{data.ideque} is a superset of this module.
6619 @xref{Immutable deques}.
6620 @c JP
6621 Gaucheの@code{data.ideque}はこのモジュールのスーパーセットになっています
6622 (@ref{Immutable deques}参照)。
6623 @c COMMON
6624 @end deftp
6625
6626 @defun ideque element @dots{}
6627 [R7RS ideque]
6628 @c MOD scheme.ideque
6629 @c EN
6630 Returns an ideque with the given elements.
6631 @c JP
6632 @var{element} @dots{} を要素に持つidequeを作って返します。
6633 @c COMMON
6634 @end defun
6635
6636 @defun ideque-unfold p f g seed
6637 [R7RS ideque]
6638 @c MOD scheme.ideque
6639 @c EN
6640 Construct an ideque in the same way as @code{unfold} (@pxref{R7RS lists}),
6641 that is, a predicate @var{p} is applied to a current state value;
6642 if it returns true, the iteration stops. Otherwise, an item
6643 generator function @var{f} is applied to the current state value,
6644 and its value becomes an element of the ideque. Then a
6645 next state function @code{g} is applied to the current state value,
6646 and its result becomes the next state value, and we iterate.
6647 The result of @var{f} is gathered in order, and becomes the content
6648 of the returned ideque.
6649 The @var{seed} argument specifies the initial state value.
6650 @c JP
6651 リストを構築する@code{unfold}と同じ要領でidequeを左から構築します
6652 (@code{unfold}については@ref{R7RS lists}参照)。
6653
6654 各繰り返しにて、まず@var{p}が現在の状態値に適用されます。
6655 それが真の値を返したら繰り返しは終了です。
6656 そうでなければ、@var{f}が状態値に適用され、その結果がidequeの要素のひとつになります。
6657 次に@var{g}が状態値に適用され、その結果が次の繰り返しの状態値となります。
6658 @var{f}の結果が順に集められて、idequeの内容となります。
6659 @var{seed}引数は最初の状態値を与えます。
6660 @c COMMON
6661
6662 @example
6663 (ideque->list
6664 (ideque-unfold (cut > <> 10) square (cut + <> 1) 0))
6665 @result{} (0 1 4 9 16 25 36 49 64 81 100)
6666 @end example
6667 @end defun
6668
6669 @defun ideque-unfold-right p f g seed
6670 [R7RS ideque]
6671 @c MOD scheme.ideque
6672 @c EN
6673 Similar to @code{ideque-unfold}, but the generated elements are
6674 stored in the reverse order in the resulting ideque.
6675 @c JP
6676 @code{ideque-unfold}と同じようにidequeを作りますが、
6677 要素が右から生成されます。
6678 @c COMMON
6679
6680 @example
6681 (ideque->list
6682 (ideque-unfold-right (cut > <> 10) square (cut + <> 1) 0))
6683 @result{} (100 81 64 49 36 25 16 9 4 1 0)
6684 @end example
6685 @end defun
6686
6687 @defun ideque-tabulate size init
6688 [R7RS ideque]
6689 @c MOD scheme.ideque
6690 @c EN
6691 Create an ideque of length @var{size}, whose @var{i}-th element
6692 is computed by @code{(init @var{i})}.
6693 @c JP
6694 @var{size}の長さのidequeを作ります。左から@var{i}番目の要素は
6695 @code{(init @var{i})}で計算されます。
6696 @c COMMON
6697
6698 @example
6699 (ideque->list (ideque-tabulate 11 square))
6700 @result{} (0 1 4 9 16 25 36 49 64 81 100)
6701 @end example
6702 @end defun
6703
6704 @defun ideque? obj
6705 [R7RS ideque]
6706 @c MOD scheme.ideque
6707 @c EN
6708 Returns true iff @var{obj} is an ideque.
6709 @c JP
6710 @var{obj}がidequeなら@code{#t}を、そうでなければ@code{#f}を返します。
6711 @c COMMON
6712 @end defun
6713
6714 @defun ideque-empty? idq
6715 [R7RS ideque]
6716 @c MOD scheme.ideque
6717 @c EN
6718 Returns true iff an ideque @var{idq} is empty.
6719 @c JP
6720 @var{idq}が空なら@code{#t}を、そうでなければ@code{#f}を返します。
6721 @c COMMON
6722 @end defun
6723
6724 @defun ideque-add-front idq x
6725 @defunx ideque-add-back idq x
6726 [R7RS ideque]
6727 @c MOD scheme.ideque
6728 @c EN
6729 Returns an ideque with an item @var{x} added to the front or back of
6730 an ideque @var{idq}, respectively.
6731 These are O(1) operations.
6732 @c JP
6733 それぞれ、@var{x}がideque @var{idq}の前(左)または後(右)に付け加えられた
6734 idequeを返します。O(1)の操作です。
6735 @c COMMON
6736 @end defun
6737
6738 @defun ideque-front idq
6739 @defunx ideque-back idq
6740 [R7RS ideque]
6741 @c MOD scheme.ideque
6742 @c EN
6743 Returns the front or back element of an ideque @var{idq}, respectively.
6744 An error is thrown if @var{idq} is empty. Thess are O(1) operations.
6745 @c JP
6746 それぞれ、ideque @var{idq}の先頭または末尾の要素を返します。
6747 @var{idq}が空の場合はエラーが投げられます。
6748 O(1)の操作です。
6749 @c COMMON
6750 @end defun
6751
6752 @defun ideque-remove-front idq
6753 @defunx ideque-remove-back idq
6754 [R7RS ideque]
6755 @c MOD scheme.ideque
6756 @c EN
6757 Returns an ideque with the front or back element of @var{idq} removed,
6758 respectively.
6759 An error is thrown if @var{idq} is empty. These are O(1) operations.
6760 @c JP
6761 それぞれ、ideque @var{idq}の先頭または末尾の要素を取り除いたidequeを返します。
6762 @var{idq}が空の場合はエラーが投げられます。
6763 O(1)の操作です。
6764 @c COMMON
6765 @end defun
6766
6767 @defun ideque-reverse idq
6768 [R7RS ideque]
6769 @c MOD scheme.ideque
6770 @c EN
6771 Returns an ideque with the elements of @var{idq} in reverse order.
6772 This is O(1) operation.
6773 @c JP
6774 ideque @var{idq}の順序を逆にしたidequeを返します。
6775 O(1)の操作です。
6776 @c COMMON
6777 @end defun
6778
6779 @defun ideque= elt= idq @dots{}
6780 [R7RS ideque]
6781 @c MOD scheme.ideque
6782 @c EN
6783 Returns @code{#t} iff all ideques are of the same length,
6784 and each corresponding element compares equal by @var{elt=}, which
6785 is called with two arguments, one element from i-th ideque and
6786 another element from (i+1)-th ideque.
6787 @c JP
6788 引数のideque @var{idq} @dots{}が全て同じ長さで、対応する各要素が
6789 全て@var{elt=}で比較して等しい場合に@code{#t}を、そうでなければ@var{#f}を
6790 返します。@var{elt=}は、i番目のidequeの要素とi+1番目のidequeの要素を引数として
6791 呼ばれます。
6792 @c COMMON
6793
6794 @c EN
6795 If zero or one ideque is given, @var{elt=} won't be called at all
6796 and this procedure returns @code{#t}.
6797 @c JP
6798 idequeがひとつだけ、あるいは全く渡されなかった場合、@var{elt=}は呼ばれず、
6799 @code{#t}が返されます。
6800 @c COMMON
6801 @end defun
6802
6803 @defun ideque-ref idq n
6804 [R7RS ideque]
6805 @c MOD scheme.ideque
6806 @c EN
6807 Returns @var{n}-th element of @var{idq}. An error is signaled if
6808 @var{n} is out of range.
6809 @c JP
6810 ideque @var{idq}の@var{n}番目の要素を返します。
6811 @var{n}が範囲外の場合はエラーが投げられます。
6812 @c COMMON
6813 @end defun
6814
6815 @defun ideque-take idq n
6816 @defunx ideque-take-right idq n
6817 [R7RS ideque]
6818 @c MOD scheme.ideque
6819 @c EN
6820 Returns an ideque that has first or last @var{n} elements of @var{idq},
6821 respectively
6822 An error is signaled if @var{n} is greater than the length of @var{idq}.
6823 @c JP
6824 それぞれ、ideque @var{idq}の先頭から/末尾から@var{n}要素を内容とするidequeを
6825 返します。@var{n}が@var{idq}の長さより大きい場合はエラーが投げられます。
6826 @c COMMON
6827 @end defun
6828
6829 @defun ideque-drop idq n
6830 @defunx ideque-drop-right idq n
6831 [R7RS ideque]
6832 @c MOD scheme.ideque
6833 @c EN
6834 Returns an ideque that has elements of @var{idq} with
6835 first or last @var{n} elements removed, respectively.
6836 An error is signaled if @var{n} is greater than the length of @var{idq}.
6837 @c JP
6838 それぞれ、ideque @var{idq}の先頭から/末尾から@var{n}要素を取り除いたものを
6839 内容とするidequeを返します。
6840 @var{n}が@var{idq}の長さより大きい場合はエラーが投げられます。
6841 @c COMMON
6842 @end defun
6843
6844 @defun ideque-split-at idq n
6845 [R7RS ideque]
6846 @c MOD scheme.ideque
6847 @c
6848 Returns two ideques, the first one is @code{(ideque-take idq n)} and
6849 the second one is @code{(ideque-drop idq n)}.
6850 An error is signaled if @var{n} is greater than the length of @var{idq}.
6851 @c JP
6852 二つの値を返します。最初の値は@code{(ideque-take idq n)}の結果と等しく、
6853 次の値は@code{(ideque-drop idq n)}の結果と等しいです。
6854 @var{n}が@var{idq}の長さより大きい場合はエラーが投げられます。
6855 @c COMMON
6856 @end defun
6857
6858 @defun ideque-length idq
6859 [R7RS ideque]
6860 @c MOD scheme.ideque
6861 @c EN
6862 Returns the length of @var{idq}.
6863 @c JP
6864 ideque @var{idq}の長さを返します。
6865 @c COMMON
6866 @end defun
6867
6868 @defun ideque-append idq @dots{}
6869 [R7RS ideque]
6870 @c MOD scheme.ideque
6871 @c EN
6872 Returns an ideque that concatenates contents of given ideques.
6873 @c JP
6874 与えられたideque @var{idq} @dots{}を順につないだidequeqを返します。
6875 @c COMMON
6876 @end defun
6877
6878 @defun ideque-zip idq idq2 @dots{}
6879 [R7RS ideque]
6880 @c MOD scheme.ideque
6881 @c EN
6882 Returns an ideque whose i-th element is a list of i-th elements of given
6883 ideques. If the length of given ideques differ, the result terminates
6884 at the shortest ideque.
6885 @c JP
6886 ideque @var{idq} @var{idq2} @dots{} の各i番目の要素のリストを要素とする
6887 idequeを返します。元のidequeの要素数が異なる場合は、最も短いidequeに揃えます。
6888 @c COMMON
6889
6890 @example
6891 (ideque->list
6892 (ideque-zip (ideque 'a 'b 'c) (ideque 1 2) (ideque 'x 'y 'z)))
6893 @result{} ((a 1 x) (b 2 y))
6894 @end example
6895 @end defun
6896
6897 @defun ideque-map proc idq @dots{}
6898 [R7RS ideque]
6899 @c MOD scheme.ideque
6900 @c EN
6901 Applies @var{proc} to each element of @var{idq}, and returns
6902 an ideque containins the results in order.
6903 The dynamic order of calls of @var{proc} is unspecified.
6904 This is O(n) operation.
6905 @c JP
6906 @var{idq}の各要素について@var{proc}を適用し、その結果を順に返す新たなidequeを
6907 作って返します。@var{proc}がどういう順番で要素に適用されるかは不定です。
6908 O(n)時間かかります。
6909 @c COMMON
6910
6911 @c EN
6912 Note that R7RS ideque only supports single @var{idq} argument.
6913 It is Gauche's extension to allow more than one @var{idq} arguments;
6914 in that case, @var{proc} gets as many arguments
6915 as the given ideques, each argument taken from each ideque.
6916 The length of the result ideque is limited to the
6917 shortest length of the input ideques.
6918 @c JP
6919 R7RSのidequeライブラリは@var{idq}が一つの場合のみを定義しています。
6920 @var{idq}が二つ以上の場合はGaucheの拡張としてサポートされます。
6921 @var{idq}が二つ以上の場合、@var{proc}は入力の@var{idq}の数だけ引数を取ります。
6922 また、結果のidequeの長さは最短の入力で決まります。
6923 @c COMMON
6924
6925 @example
6926 (ideque->list (ideque-map square (ideque 1 2 3 4 5)))
6927 @result{} (1 4 9 16 25)
6928 (ideque->list (ideque-map + (ideque 1 2 3 4 5) (ideque 2 2 2)))
6929 @result{} (11 12 13)
6930 @end example
6931 @end defun
6932
6933 @defun ideque-filter-map proc idq @dots{}
6934 [R7RS ideque]
6935 @c MOD scheme.ideque
6936 @c EN
6937 Applies @var{proc} to each element of @var{idq}, and returns
6938 an ideque containins the results in order, except @code{#f}.
6939 The dynamic order of calls of @var{proc} is unspecified.
6940 @c JP
6941 @var{idq}の各要素に@var{proc}を適用し、その結果のうち@code{#f}でないものを
6942 集めたidequeを作って返します。
6943 @var{proc}がどういう順番で要素に適用されるかは不定です。
6944 @c COMMON
6945
6946 @c EN
6947 Note that R7RS ideque only supports single @var{idq} argument.
6948 It is Gauche's extension to allow more than one @var{idq} arguments;
6949 in that case, @var{proc} gets as many arguments
6950 as the given ideques, each argument taken from each ideque.
6951 The input is read until any of the @var{idq} reaches
6952 at the end.
6953 @c JP
6954 R7RSのidequeライブラリは@var{idq}が一つの場合のみを定義しています。
6955 @var{idq}が二つ以上の場合はGaucheの拡張としてサポートされます。
6956 @var{idq}が二つ以上の場合、@var{proc}は@var{idq}の数だけ引数を取ります。
6957 また、入力の@var{idq}のいずれかの最後まで到達した時に処理が終了します。
6958 @c COMMON
6959 @end defun
6960
6961 @defun ideque-for-each proc idq @dots{}
6962 @defunx ideque-for-each-right proc idq @dots{}
6963 [R7RS ideque]
6964 @c MOD scheme.ideque
6965 @c EN
6966 Applies @var{proc} to each element of @var{idq} from left to right
6967 (@code{ideque-for-each}) or right to left (@code{ideque-for-each-right}).
6968 Results of @var{proc} are discarded.
6969 @c JP
6970 @var{proc}を@var{idq}の要素に順に(@code{ideque-for-each}は左から右に、
6971 @code{ideque-for-each-right}は右から左に)適用します。@var{proc}の
6972 結果は捨てられます。
6973 @c COMMON
6974
6975 @c EN
6976 Returns an unspecified value.
6977 @c JP
6978 戻り値は未規定です。
6979 @c COMMON
6980
6981 @c EN
6982 Note that R7RS ideque only supports single @var{idq} argument.
6983 If more than one ideques are given, @var{proc} gets as many arguments
6984 as the given ideques, each argument taken from each ideque.
6985
6986 @code{ideque-for-each} takes each ideque's elements from leftmost ones,
6987 while @code{ideque-for-each-right} takes each ideque's elements from rightmost
6988 ones. Both ends when the shortest ideque is exhausted.
6989 @c JP
6990 R7RSのidequeライブラリは@var{idq}が一つの場合のみを定義しています。
6991 @var{idq}が二つ以上の場合、@var{proc}は@var{idq}の数だけ引数を取ります。
6992
6993 @code{ideque-for-each}は各idequeの要素を左から取るのに対し、
6994 @code{ideque-for-each-right}は各idequeの要素を右から取ります。
6995 どちらも最短のidequeを消費した時点で終了します。
6996 @c COMMON
6997
6998 @example
6999 (ideque-for-each ($ display $ list $)
7000 (ideque 'a 'b 'c 'd 'e)
7001 (ideque 1 2 3))
7002 @result{} @r{prints} (a 1)(b 2)(c 3)
7003
7004 (ideque-for-each-right ($ display $ list $)
7005 (ideque 'a 'b 'c 'd 'e)
7006 (ideque 1 2 3))
7007 @result{} @r{prints} (e 3)(d 2)(c 1)
7008 @end example
7009 @end defun
7010
7011 @defun ideque-fold proc knil idq @dots{}
7012 @defunx ideque-fold-right proc knil idq @dots{}
7013 [R7RS ideque]
7014 @c MOD scheme.ideque
7015 @end defun
7016
7017 @defun ideque-append-map proc idq @dots{}
7018 [R7RS ideque]
7019 @c MOD scheme.ideque
7020 @end defun
7021
7022 @defun ideque-filter pred idq
7023 @defunx ideque-remove pred idq
7024 [R7RS ideque]
7025 @c MOD scheme.ideque
7026 @end defun
7027
7028 @defun ideque-partition pred idq
7029 [R7RS ideque]
7030 @c MOD scheme.ideque
7031 @end defun
7032
7033 @defun ideque-find pred idq :optional failure
7034 @defunx ideque-find-right pred idq :optional failure
7035 [R7RS ideque]
7036 @c MOD scheme.ideque
7037 @end defun
7038
7039 @defun ideque-take-while pred idq
7040 @defunx ideque-take-while-right pred idq
7041 [R7RS ideque]
7042 @c MOD scheme.ideque
7043 @end defun
7044
7045 @defun ideque-drop-while pred idq
7046 @defunx ideque-drop-while-right pred idq
7047 [R7RS ideque]
7048 @c MOD scheme.ideque
7049 @end defun
7050
7051 @defun ideque-span pred idq
7052 @defunx ideque-break pred idq
7053 [R7RS ideque]
7054 @c MOD scheme.ideque
7055 @end defun
7056
7057 @defun ideque-any pred idq @dots{}
7058 @defunx ideque-every pred idq @dots{}
7059 [R7RS ideque]
7060 @c MOD scheme.ideque
7061 @end defun
7062
7063 @defun ideque->list idq
7064 @defunx list->ideque list
7065 [R7RS ideque]
7066 @c MOD scheme.ideque
7067 @end defun
7068
7069 @defun ideque->generator idq
7070 @defunx generator->ideque gen
7071 [R7RS ideque]
7072 @c MOD scheme.ideque
7073 @end defun
7074
7075 @node R7RS immutable texts, R7RS generators, R7RS immutable deques, R7RS large
7076 @subsection @code{scheme.text} - R7RS immutable texts
7077 @c NODE R7RS変更不可なテキスト, @code{scheme.text} - R7RS変更不可なテキスト
7078
7079 @deftp {Module} scheme.text
7080 @mdindex scheme.text
7081 @c EN
7082 This module provides @emph{text} type, an immutable string
7083 with O(1) random access. This is originally defined in SRFI-135.
7084 @c JP
7085 このモジュールは@emph{text}と呼ばれる、O(1)ランダムアクセスができる
7086 変更不可な文字列へのインタフェースを提供します。
7087 元はSRFI-135として規定されました。
7088 @c COMMON
7089
7090 @c EN
7091 In Gauche, a string with index access generally takes O(n) because of
7092 mulit-byte representation; however,
7093 if the string is ASCII-only or you precalculate string indexes,
7094 index access becomes O(1) (@pxref{String indexing}).
7095 So, a text in Gauche is just an immutable indexed string. It satisfies
7096 @code{string?}, too.
7097 @c JP
7098 Gaucheの文字列は一般的にはマルチバイト文字列のためインデックスアクセスはO(n)と
7099 なります。しかし、文字列がASCII文字のみからなる場合、
7100 あるいは文字列インデックスが付加されている場合(@ref{String indexing}参照)は、
7101 インデックスアクセスはO(1)になります。
7102 従って、Gaucheではtextは単なる変更不可でインデックスが付加された文字列であり、
7103 @code{string?}に対しても@code{#t}を返します。
7104 @c COMMON
7105
7106 @c EN
7107 Since text is not disjoint from string in Gauche, @emph{textual}
7108 type mentioned in this srfi
7109 is equivalent to a string type, and many @code{textual-*} procedures are
7110 just aliases to the corresponding @code{string-*} procedures.
7111
7112 However, if you're writing portable code, keep it in mind that
7113 some implementation may have disjoint text and string types.
7114 @c JP
7115 Gaucheではこのsrfiでいう@emph{textual}型は文字列型と全く同じであり、
7116 @code{textual-*}手続きの大半は対応する@code{string-*}手続きの単なる別名です。
7117
7118 しかし、ポータブルなコードを書いている場合は、処理系によってはtext型と文字列型が
7119 別の型である場合もあることに留意してください。
7120 @c COMMON
7121 @end deftp
7122
7123 @defun text? obj
7124 [R7RS text]
7125 @c MOD scheme.text
7126 @c EN
7127 Returns @code{#t} iff @var{obj} is a text, which is an immutable
7128 indexed string in Gauche. Note that a text type is not disjoint
7129 from a string in Gauche.
7130 @c JP
7131 @var{obj}がtext型なら@code{#t}を、そうでなければ@code{#f}を返します。
7132 Gaucheではtextは文字列インデックスが付加された変更不可な文字列です。
7133 文字列型とtext型が排他ではないことに注意してください。
7134 @c COMMON
7135 @end defun
7136
7137 @defun textual? obj
7138 [R7RS text]
7139 @c MOD scheme.text
7140 @c EN
7141 Returns @code{#t} iff @var{obj} is either a text or a string.
7142 In Gauche, this is just an alias of @code{string?}.
7143 @c JP
7144 @var{obj}がtext型か文字列型であれば@code{#t}を、そうでなければ@code{#f}を返します。
7145 Gaucheではこれは単に@code{string?}の別名です。
7146 @c COMMON
7147 @end defun
7148
7149 @defun textual-null? obj
7150 [R7RS text]
7151 @c MOD scheme.text
7152 @c EN
7153 Returns @code{#t} iff @var{obj} is an empty string/text. In Gauche
7154 this is just an alias of @code{string-null?}.
7155 @c JP
7156 @var{obj}が空の文字列かtextなら@code{#t}を、そうでなければ@code{#f}を返します。
7157 Gaucheではこれは単に@code{string-null?}の別名です。
7158 @c COMMON
7159 @end defun
7160
7161 @defun textual-every pred textual :optional start end
7162 @defunx textual-any pred textual :optional start end
7163 [R7RS text]
7164 @c MOD scheme.text
7165 @c EN
7166 Like @code{string-every} and @code{string-any}, but can work on both
7167 texts and strings. In Gauche, these are just aliases of
7168 @code{string-every} and @code{string-any}.
7169 @c JP
7170 textと文字列の両方に対して、@code{string-every}や@code{string-any}のように動作します。
7171 Gaucheではこれらは@code{string-every}、@code{string-any}の別名です。
7172 @c COMMON
7173 @end defun
7174
7175 @defun make-text len char
7176 [R7RS text]
7177 @c MOD scheme.text
7178 @c EN
7179 In Gauche it is same as @code{make-string}, except that the returned
7180 string is immutable and indexed, and you can't omit @var{char}.
7181 @c JP
7182 Gaucheではこれは@code{make-string}とほぼ同じですが、
7183 返される文字列は変更不可であり、また文字列インデックスが付加済みです。
7184 @var{char}を省略できないことに注意してください。
7185 @c COMMON
7186 @end defun
7187
7188 @defun text char @dots{}
7189 [R7RS text]
7190 @c MOD scheme.text
7191 @c EN
7192 Like @code{string}, but returned string is immutable and indexed.
7193 @c JP
7194 @code{string}と似ていますが、
7195 返される文字列は変更不可であり、また文字列インデックスが付加済みです。
7196 @c COMMON
7197 @end defun
7198
7199 @defun text-tabulate proc len
7200 [R7RS text]
7201 @c MOD scheme.text
7202 @c EN
7203 Like @code{string-tabulate}, but returned string is immutable and indexed
7204 (@pxref{String constructors}).
7205 @c JP
7206 @code{string-tabulate}と似ていますが、
7207 返される文字列は変更不可であり、また文字列インデックスが付加済みです。
7208 @ref{String constructors}参照。
7209 @c COMMON
7210 @end defun
7211
7212 @defun text-unfold p f g seed :optional base make-final
7213 @defunx text-unfold-right p f g seed :optional base make-final
7214 [R7RS text]
7215 @c MOD scheme.text
7216 @c EN
7217 Like @code{string-unfold} and @code{string-unfold-right},
7218 but returned string is immutable and indexed
7219 (@pxref{String constructors}). The mapper procedure @var{f} may return
7220 a string instead of a character.
7221 @c JP
7222 @code{string-unfold}および@code{string-unfold-right}と似ていますが、
7223 返される文字列は変更不可であり、文字列インデックス付加済みになります
7224 (@ref{String constructors}参照)。
7225 また、シードから要素を生成する手続き@var{f}は、
7226 文字だけでなく文字列を返すこともできます (その文字列の各文字が結果に挿入されます)。
7227 @c COMMON
7228 @end defun
7229
7230 @defun text-length text
7231 [R7RS text]
7232 @c MOD scheme.text
7233 @c EN
7234 Returns the length of @var{text}.
7235 An error is signaled if @var{text} is not a text.
7236 @c JP
7237 @var{text}の長さを返します。@var{text}がtextでなければエラーが報告されます。
7238 @c COMMON
7239 @end defun
7240
7241 @defun text-ref text index
7242 [R7RS text]
7243 @c MOD scheme.text
7244 @c EN
7245 Returns @var{index}-th character of the text. Guaranteed to be O(1).
7246 An error is signaled if @var{text} is not a text.
7247 @c JP
7248 textの@var{index}番目の文字を返します。O(1)アクセスが保証されます。
7249 @var{text}がtextでなければエラーが報告されます。
7250 @c COMMON
7251 @end defun
7252
7253 @defun textual-length textual
7254 [R7RS text]
7255 @c MOD scheme.text
7256 @c EN
7257 Returns the length of a text or a string.
7258 This is just an alias of @code{string-length} in Gauche.
7259 @c JP
7260 textあるいは文字列の長さを返します。
7261 Gaucheではこれは単に@code{string-length}の別名です。
7262 @c COMMON
7263 @end defun
7264
7265 @defun textual-ref textual index
7266 [R7RS text]
7267 @c MOD scheme.text
7268 @c EN
7269 Returns @var{index}-th character of the text.
7270 This is just an alias of @code{string-ref} in Gauche.
7271 @c JP
7272 textの@var{index}番目の文字を返します。
7273 Gaucheではこれは単に@code{string-ref}の別名です。
7274 @c COMMON
7275 @end defun
7276
7277 @defun textual->text textual
7278 [R7RS text]
7279 @c MOD scheme.text
7280 @c EN
7281 Takes a string, and returns an immutable, indexed string of the same
7282 content. If @var{textual} is already a such string, it is returned as is.
7283 @c JP
7284 文字列を受け取り、同じ内容の、文字列インデックス付加済みで変更不可な文字列を返します。
7285 @var{textual}が既にそういう文字列であれば、それがそのまま返されます。
7286 @c COMMON
7287 @end defun
7288
7289 @defun textual->string textual :optional start end
7290 @defunx textual->vector textual :optional start end
7291 @defunx textual->list textual :optional start end
7292 [R7RS text]
7293 @c MOD scheme.text
7294 @c EN
7295 Converts a textual to a fresh mutable string,
7296 a vector and a list, respectively.
7297 These are aliases of @code{string-copy}, @code{string->vector}
7298 and @code{string->list} in Gauche.
7299 @c JP
7300 @var{textual}を新たにアロケートされた変更可能な文字列、
7301 文字のベクタ、文字のリストにそれぞれ変換します。
7302 Gaucheではこれらは@code{string-copy}、@code{string->vector}、
7303 @code{string->list}の別名です。
7304 @c COMMON
7305 @end defun
7306
7307 @defun string->text string :optional start end
7308 @defunx vector->text char-vector :optional start end
7309 @defunx list->text char-list :optional start end
7310 [R7RS text]
7311 @c MOD scheme.text
7312 @c EN
7313 Convert a string, a vector of characters, and a list of characters
7314 to an immutable indexed string.
7315 If an immutable indexed string is given to @code{string->text} without
7316 start/end arguments, the input is returned as is.
7317 @c JP
7318 それぞれ、文字列、文字のベクタ、文字のリストを、
7319 文字列インデックス付きの変更不可な文字列に変換します。
7320 @code{string->text}に文字列インデックス付きの変更不可な文字列が渡された場合は
7321 それがそのまま返されます。
7322 @c COMMON
7323 @end defun
7324
7325 @defun reverse-list->text char-list
7326 [R7RS text]
7327 @c MOD scheme.text
7328 @c EN
7329 Same as @code{(list->text (reverse char-list))} but maybe more efficient.
7330 @c JP
7331 @code{(list->text (reverse char-list))}と同じですがより効率的な場合があります。
7332 @c COMMON
7333 @end defun
7334
7335 @defun textual->utf8 textual :optional start end
7336 [R7RS text]
7337 @c MOD scheme.text
7338 @c EN
7339 Returns a bytevector (u8vector) that contains utf8 encoding of the input
7340 textual. In Gauche, it is the same as @code{string->utf8}
7341 (@pxref{Unicode transfer encodings}).
7342 @c JP
7343 入力のtextまたは文字列をutf8エンコーディングのバイト列に変換し、バイトベクタ(u8vector)
7344 として返します。Gaucheではこれは@code{string->utf8}と同じです
7345 (@ref{Unicode transfer encodings}参照)。
7346 @c COMMON
7347 @end defun
7348
7349 @defun textual->utf16 textual :optional start end
7350 [R7RS text]
7351 @c MOD scheme.text
7352 @c EN
7353 Returns a bytevector (u8vector) that contains utf16 encoding of the input
7354 textual, with BOM attached, and in the native byteorder.
7355 In Gauche, it is the same as
7356 @code{(string->utf16 textual (native-endian) #t [start end])}
7357 (@pxref{Unicode transfer encodings}).
7358 @c JP
7359 入力のtextまたは文字列をutf16エンコーディングのバイト列
7360 (ネイティブバイトオーダー、BOMつき)に変換し、バイトベクタ(u8vector)
7361 として返します。Gaucheではこれは
7362 @code{(string->utf16 textual (native-endian) #t [start end])}と同じです
7363 (@ref{Unicode transfer encodings}参照)。
7364 @c COMMON
7365 @end defun
7366
7367 @defun textual->utf16be textual :optional start end
7368 @defunx textual->utf16le textual :optional start end
7369 [R7RS text]
7370 @c MOD scheme.text
7371 @c EN
7372 Returns a bytevector that contains utf16be and utf16le encoding of the input
7373 textual. No BOM is attached.
7374 In Gauche, they are the same as
7375 @code{(string->utf16 textual 'big-endian #f [start end])} and
7376 @code{(string->utf16 textual 'little-endian #t [start end])}
7377 (@pxref{Unicode transfer encodings}).
7378 @c JP
7379 入力のtextまたは文字列をutf16le/beエンコーディングのバイト列
7380 (BOMなし)に変換し、バイトベクタ(u8vector)として返します。Gaucheではこれはそれぞれ
7381 @code{(string->utf16 textual 'big-endian #f [start end])}および
7382 @code{(string->utf16 textual 'little-endian #t [start end])}と同じです
7383 (@ref{Unicode transfer encodings}参照)。
7384 @c COMMON
7385 @end defun
7386
7387 @defun utf8->text bytevector :optional start end
7388 [R7RS text]
7389 @c MOD scheme.text
7390 @c EN
7391 Converts a utf8 octet sequence stored in @var{bytevector} (u8vector) to a text.
7392 If the octet sequence begins with BOM sequence, it is interpreted
7393 as a character U+FEFF. Optional @var{start}/@var{end} arguments
7394 limits the input range of @var{bytevector}.
7395 @c JP
7396 @var{bytevector} (u8vector)に格納されたutf8オクテット列をtext
7397 (インデックス付き変更不可文字列) に変換して返します。
7398 入力がBOMで始まっていた場合、それは文字U+FEFFと解釈されます。
7399 省略可能な@var{start}/@var{end}引数は入力@var{bytevector}の範囲を制限します。
7400 @c COMMON
7401
7402 @c EN
7403 If the input contains an invalid utf-8 sequence, and Gauche's native
7404 encoding is utf-8, it is replaced by a unicode replacement character
7405 U+FFFD. (NB: SRFI-135 says it is an error.)
7406 @c JP
7407 入力にutf-8として不正なオクテットが含まれており、Gaucheが内部エンコーディングutf-8で
7408 コンパイルされていれば、そのオクテットはUnicode置換文字U+FFFDに変換されます。
7409 (SRFI-135ではその場合は「エラーである」と規定されているので、
7410 実際の処理は処理系依存になります)。
7411 @c COMMON
7412 @end defun
7413
7414 @defun utf16->text bytevector :optional start end
7415 @defunx utf16be->text bytevector :optional start end
7416 @defunx utf16le->text bytevector :optional start end
7417 [R7RS text]
7418 @c MOD scheme.text
7419 @c EN
7420 Converts a utf16 octet sequence stored in @var{bytevector} to a text.
7421 For @code{utf16->text}, the sequence may begin with BOM,
7422 in which case it determines the endianness.
7423 Otherwise, platform's native endianness is assumed.
7424 Fro @code{utf16be->text} and @code{utf16le->text}, the input is
7425 assumed to be in UTF16BE/UTF16LE respectively; if it begins with BOM
7426 it is treated as a character U+FEFF.
7427 @c JP
7428 @var{bytevector} (u8vector)に格納されたutf8オクテット列をtext
7429 (インデックス付き変更不可文字列) に変換して返します。
7430 @code{utf16->text}は、入力がBOMで始まっていればそれに従ってバイトオーダーを
7431 解釈し、BOMが無ければネイティブバイトオーダーを使います。
7432 @code{utf16be->text}と@code{utf16le->text}はそれぞれ
7433 入力がbig/little endianであることを前提に解釈します。先頭にBOMがあれば
7434 それはU+FEFFという文字になります。
7435 @c COMMON
7436
7437 @c EN
7438 Optional @var{start}/@var{end} arguments
7439 limits the input range of @var{bytevector}.
7440 @c JP
7441 省略可能な@var{start}/@var{end}引数は入力@var{bytevector}の範囲を制限します。
7442 @c JP
7443
7444 @c EN
7445 If the length of input (@var{end} - @var{start}, if the range is limited)
7446 isn't even, an error is thrown.
7447 @c JP
7448 入力のオクテット数 (入力範囲の制限がある場合は@var{end} - @var{start})が偶数で
7449 なければエラーが投げられます。
7450 @c COMMON
7451
7452 @c EN
7453 If the input contains an invalid utf-16 sequence (unpaired surrogates),
7454 it is replaced by a unicode replacement character U+FFFD.
7455 (NB: SRFI-135 says it is an error.)
7456 @c JP
7457 入力にutf-16として不正な列 (対になっていないサロゲート) が含まれていた
7458 場合、それはUnicode置換文字U+FFFDに変換されます。
7459 (SRFI-135ではその場合は「エラーである」と規定されているので、
7460 実際の処理は処理系依存になります)。
7461 @c COMMON
7462 @end defun
7463
7464 @defun subtext text start end
7465 @defunx subtextual textual start end
7466 [R7RS text]
7467 @c MOD scheme.text
7468 @c EN
7469 Returns a text between @var{start}-th (inclusive) and @var{end}-th (exclusive)
7470 characters in the input.
7471 @c JP
7472 入力のtext、あるいはtextual(textまたは文字列)の@var{start}番目の文字から
7473 @var{end}番目の文字の手前までを取り出してtext (インデックス付加済みの変更不可な文字列)
7474 として返します。
7475 @c COMMON
7476 @end defun
7477
7478 @defun textual-copy textual :optional start end
7479 [R7RS text]
7480 @c MOD scheme.text
7481 @c EN
7482 Returns a copy of @var{textual}, optionally limited between
7483 @var{start}/@var{end}, as a text.
7484 @c JP
7485 textまたは文字列のコピーをtextとして返します。
7486 省略可能な@var{start}/@var{end}引数は、
7487 コピーする範囲を@var{start}文字目から@var{end}文字目の手前までに制限します。
7488 @c COMMON
7489
7490 @c EN
7491 SRFI-135 specifies that even the input is a text, the returned one
7492 must be freshly allocated (as opposed to @code{subtextual}, which
7493 is allowed to return the result sharing the input).
7494 In Gauche, string body is immutable anyway,
7495 so it isn't a big deal.
7496 @c JP
7497 SRFI-135は、@code{textual-copy}が常に新たなtextをアロケートして返すことを
7498 要求しています (@code{subtextual}は戻り値が入力と共有されることを許します)。
7499 Gaucheでは、文字列本体はimmutableであり、
7500 文字列のコピーは文字列本体へのポインタをコピーするだけなので、
7501 どちらもあまり変わりませんが。
7502 @c COMMON
7503 @end defun
7504
7505 @defun textual-take textual nchars
7506 @defunx textual-drop textual nchars
7507 @defunx textual-take-right textual nchars
7508 @defunx textual-drop-right textual nchars
7509 @defunx textual-pad textual len :optional char start end
7510 @defunx textual-pad-right textual len :optional char start end
7511 @defunx textual-trim textual :optional pred start end
7512 @defunx textual-trim-right textual :optional pred start end
7513 @defunx textual-trim-both textual :optional pred start end
7514 [R7RS text]
7515 @c MOD scheme.text
7516 @c EN
7517 In Gauche, these are the same as corresponding string operations
7518 (@code{string-take}, @code{string-drop}, @code{string-take-right},
7519 @code{string-drop-right}, @code{string-pad}, @code{string-pad-right},
7520 @code{string-trim}, @code{string-tirm-right}, and @code{string-trim-both}),
7521 except that the returned string is always immutable and indexed.
7522 @xref{SRFI-13 String selection}, for these string procedures.
7523 @c JP
7524 Gaucheでは、結果が常に変更不可でインデックス付きになること以外は、
7525 対応する文字列操作
7526 (@code{string-take}、@code{string-drop}、@code{string-take-right}、
7527 @code{string-drop-right}、@code{string-pad}、@code{string-pad-right}、
7528 @code{string-trim}、@code{string-tirm-right}、@code{string-trim-both})
7529 と同じです。
7530 詳しくは@ref{SRFI-13 String selection}を参照してください。
7531 @c COMMON
7532 @end defun
7533
7534 @defun textual-replace textual1 textual2 start1 end1 :optional start2 end2
7535 [R7RS text]
7536 @c MOD scheme.text
7537 @c EN
7538 In Gauche, this is same as @code{string-replace},
7539 except that the returned string is always immutable and indexed.
7540 @xref{SRFI-13 Other string operations}, for the details.
7541 @c JP
7542 Gaucheでは、戻り値の文字列が常に変更不可かつインデックス付きになること以外は、
7543 @code{string-replace}と同じです。
7544 詳しくは@ref{SRFI-13 Other string operations}参照。
7545 @c COMMON
7546 @end defun
7547
7548 @defun textual=? textual1 textual2 textual3 @dots{}
7549 @defunx textual<? textual1 textual2 textual3 @dots{}
7550 @defunx textual>? textual1 textual2 textual3 @dots{}
7551 @defunx textual<=? textual1 textual2 textual3 @dots{}
7552 @defunx textual>=? textual1 textual2 textual3 @dots{}
7553 [R7RS text]
7554 @c MOD scheme.text
7555 @ EN
7556 In Gauche, these are just aliases of built-in
7557 @code{string=?}, @code{string<?}, @code{string>?},
7558 @code{string<=?} and @code{string>?}, respectively.
7559 @xref{String comparison}, for the details.
7560 @c JP
7561 Gaucheではこれらはそれぞれ組み込みの
7562 @code{string=?}、@code{string<?}、@code{string>?}、
7563 @code{string<=?}、@code{string>?}の別名です。
7564 詳しくは@ref{String comparison}参照。
7565 @c COMMON
7566 @end defun
7567
7568 @defun textual-ci=? textual1 textual2 textual3 @dots{}
7569 @defunx textual-ci<? textual1 textual2 textual3 @dots{}
7570 @defunx textual-ci>? textual1 textual2 textual3 @dots{}
7571 @defunx textual-ci<=? textual1 textual2 textual3 @dots{}
7572 @defunx textual-ci>=? textual1 textual2 textual3 @dots{}
7573 [R7RS text]
7574 @c MOD scheme.text
7575 @c EN
7576 In Gauche, these are just aliases of @emph{the unicode version} of
7577 @code{string-ci=?}, @code{string-ci<?}, @code{string-ci>?},
7578 @code{string-ci<=?} and @code{string-ci>?}, respectively.
7579 @xref{Full string case conversion}, for the details.
7580 @c JP
7581 Gaucheではこれらはそれぞれ@emph{unicodeバージョンの}
7582 @code{string-ci=?}、@code{string-ci<?}、@code{string-ci>?}、
7583 @code{string-ci<=?}、@code{string-ci>?}と同じです。
7584 詳しくは@ref{Full string case conversion}参照。
7585 @c COMMON
7586 @end defun
7587
7588 @defun textual-prefix-length textual1 textual2 :optional start1 end1 start2 end2
7589 @defunx textual-suffix-length textual1 textual2 :optional start1 end1 start2 end2
7590 @defunx textual-prefix? textual1 textual2 :optional start1 end1 start2 end2
7591 @defunx textual-suffix? textual1 textual2 :optional start1 end1 start2 end2
7592 [R7RS text]
7593 @c MOD scheme.text
7594 @c EN
7595 In Gauche, these are just aliases of @code{srfi.13}'s
7596 @code{string-prefix-length}, @code{string-suffix-length},
7597 @code{string-prefix?}, and @code{string-suffix?}, respectively.
7598 @xref{SRFI-13 String prefixes & suffixes}, for the details.
7599 @c JP
7600 Gaucheでは、これらはそれぞれ@code{srfi.13}の
7601 @code{string-prefix-length}、@code{string-suffix-length}、
7602 @code{string-prefix?}、@code{string-suffix?}の別名です。
7603 詳しくは@ref{SRFI-13 String prefixes & suffixes}参照。
7604 @c COMMON
7605 @end defun
7606
7607 @defun textual-index textual pred :optional start end
7608 @defunx textual-index-right textual pred :optional start end
7609 @defunx textual-skip textual pred :optional start end
7610 @defunx textual-skip-right textual pred :optional start end
7611 @defunx textual-contains textual-haystack textual-needle :optional start1 end1 start2 end2
7612 @defunx textual-contains-right textual-haystack textual-needle :optional start1 end1 start2 end2
7613 [R7RS text]
7614 @c MOD scheme.text
7615 @c EN
7616 In Gauche, these are just aliases of @code{srfi.13}'s
7617 @code{string-index}, @code{string-index-right},
7618 @code{string-skip}, @code{string-skip-right},
7619 @code{string-contains}, and @code{string-contains-right}, respectively.
7620 @xref{SRFI-13 String searching}, for the details.
7621 @c JP
7622 Gaucheでは、これらはそれぞれ@code{srfi.13}の
7623 @code{string-index}、@code{string-index-right}、
7624 @code{string-skip}、@code{string-skip-right}、
7625 @code{string-contains}、@code{string-contains-right}の別名です。
7626 詳しくは@ref{SRFI-13 String searching}参照。
7627 @c COMMON
7628 @end defun
7629
7630 @defun textual-upcase textual
7631 @defunx textual-downcase textual
7632 @defunx textual-foldcase textual
7633 @defunx textual-titlecase textual
7634 [R7RS text]
7635 @c MOD scheme.text
7636 @c EN
7637 In Gauche, these are the same as @code{string-upcase},
7638 @code{string-downcase}, @code{string-foldcase} and @code{string-titlecase}
7639 of @code{gauche.unicode}, respectively, except that the result is
7640 always an immutable and indexed string.
7641 @xref{Full string case conversion}, for the details.
7642 @c JP
7643 Gaucheでは、これらは戻り値が常に変更不可でインデックス付きの文字列になること以外は、
7644 @code{gauche.unicode}の@code{string-upcase}、
7645 @code{string-downcase}、@code{string-foldcase}、@code{string-titlecase}、
7646 @code{gauche.unicode}とそれぞれ同じです。
7647 詳しくは@ref{Full string case conversion}参照。
7648 @c COMMON
7649 @end defun
7650
7651 @defun textual-append textual @dots{}
7652 @defunx textual-concatenate textual-list
7653 [R7RS text]
7654 @c MOD scheme.text
7655 @c EN
7656 In Gauche, these are the same as @code{string-append} and
7657 @code{string-concatenate} respectively, except that the result
7658 is always an immutable and indexed string.
7659 @c JP
7660 Gaucheでは、これらは戻り値が常に変更不可でインデックス付きの文字列になること以外は、
7661 それぞれ@code{string-append}および@code{string-concatenate}と同じです。
7662 @c COMMON
7663 @end defun
7664
7665 @defun textual-concatenate-reversse args :optional final-textual end
7666 [R7RS text]
7667 @c MOD scheme.text
7668 @c EN
7669 The @var{args} must be a list of textuals (same as strings in Gauche).
7670 As to the optional arguments,
7671 @var{final-textual} must be a textual, and @var{end}
7672 must be a nonnegative exact integer, if provided.
7673
7674 Without optional arguments, this is the same as
7675 @code{string-concatenate-reverse} of @code{srfi.13}
7676 (@pxref{SRFI-13 String reverse & append}, except that
7677 the result is always an immutable and indexed string.
7678
7679 If @var{final-textual} is provided, it is appended to the last.
7680 If @var{end} is also provided, @code{(subtext final-textual 0 end)} is
7681 appended to the last.
7682 @c JP
7683 @var{args}はtextual (Gaucheでは文字列と同じ) のリストでなければなりません。
7684 また省略可能引数については、@var{final-textual}はtextual、
7685 @var{end}は非負の正確な整数でなければなりません。
7686
7687 省略可能引数が無い場合、これは戻り値が常に変更不可でインデックス付きの文字列に
7688 なること以外は、@code{srfi.13}の@code{string-concatenate-reverse}と同じです
7689 (@ref{SRFI-13 String reverse & append}参照)。
7690
7691 @var{final-textual}が与えられたら、それが結果の末尾に足されます。
7692 @var{end}も与えられたら、@code{(subtext final-textual 0 end)}が
7693 結果の末尾に足されます。
7694 @c COMMON
7695 @end defun
7696
7697 @defun textual-join textual-list :optional delimiter grammar
7698 [R7RS text]
7699 @c MOD scheme.text
7700 @c EN
7701 This is the same as @code{string-join} except that the result
7702 is always an immutable and indexed string
7703 (@pxref{String utilities}).
7704 @c JP
7705 戻り値が常に変更不可でインデックス付きの文字列になることを除き、
7706 @code{string-join}と同じです
7707 (@ref{String utilities}参照)。
7708 @c COMMON
7709 @end defun
7710
7711 @defun textual-fold kons knil textual :optional start end
7712 @defunx textual-fold-right kons knil textual :optional start end
7713 [R7RS text]
7714 @c MOD scheme.text
7715 @c EN
7716 These are just aliases of @code{srfi.13}'s
7717 @code{string-fold} and @code{string-fold-right},
7718 respectively (@pxref{SRFI-13 String mapping}).
7719 @c JP
7720 これらはそれぞれ@code{srfi.13}の@code{string-fold}および@code{string-fold-right}
7721 の別名です (@ref{SRFI-13 String mapping}参照)。
7722 @c COMMON
7723 @end defun
7724
7725 @defun textual-map proc textual1 textual2 @dots{}
7726 [R7RS text]
7727 @c MOD scheme.text
7728 @c EN
7729 For every corresponding characters from input textuals,
7730 @var{proc} is applied. It must return either a character or
7731 a text. The result of @var{proc} is concatenated into a new text
7732 and returned. Similar to @code{string-map}, but the difference is
7733 it allows 1-to-n mappinb by letting @var{proc} return a string.
7734 @c JP
7735 入力textualの、対応する文字それぞれに対して@var{proc}が適用されます。
7736 @var{proc}は文字かtextを返さねばなりません。
7737 @var{proc}の結果がtextとして集められて返されます。
7738 @code{string-map}と似ていますが、@var{proc}が文字列を返すことで1-to-nの
7739 マッピングが可能です。
7740 @c COMMON
7741
7742 @c EN
7743 The dynamic order in which @var{proc} is called is unspecified.
7744
7745 If more than one textual are given, it scans up to the shortest
7746 textual.
7747 @c JP
7748 @var{proc}が呼ばれる動的順序は規定されていません。
7749
7750 二つ以上のtextualが渡された場合、一番短いtextualの要素数だけ@var{proc}は呼ばれます。
7751 @c COMMON
7752
7753 @example
7754 (textual-map (^c (string c c)) "abc")
7755 @result{} "aabbcc"
7756 (textual-map (^[a b] (if (char<? a b) a b))
7757 "continuation" "parameterization")
7758 @result{} "canaietarioa"
7759 @end example
7760 @end defun
7761
7762 @defun textual-for-each proc textual1 textual2 @dots{}
7763 [R7RS text]
7764 @c MOD scheme.text
7765 @c EN
7766 For every corresponding characters from input textuals,
7767 @var{proc} is applied, from left to right order.
7768 The result of @var{proc} is discarded. The procedure returns
7769 an undefined value.
7770
7771 If more than one textual are given, it scans up to the shortest
7772 textual.
7773 @c JP
7774 入力textualの、対応する文字それぞれに対して左から右の順に@var{proc}が適用されます。
7775 @var{proc}の結果は捨てられます。
7776 @var{proc}の結果がtextとして集められて返されます。
7777
7778 二つ以上のtextualが渡された場合、一番短いtextualの要素数だけ@var{proc}は呼ばれます。
7779 @c COMMON
7780 @end defun
7781
7782 @defun textual-map-index proc textual :optional start end
7783 [R7RS text]
7784 @c MOD scheme.text
7785 @c EN
7786
7787 @c JP
7788 @c COMMON
7789 @end defun
7790
7791 @defun textual-for-each-index proc textual :optional start end
7792 [R7RS text]
7793 @c MOD scheme.text
7794 @end defun
7795
7796 @defun textual-count textual pred :optional start end
7797 [R7RS text]
7798 @c MOD scheme.text
7799 @end defun
7800
7801 @defun textual-filter pred textual :optional start end
7802 @defunx textual-remove pred textual :optional start end
7803 [R7RS text]
7804 @c MOD scheme.text
7805 @end defun
7806
7807 @defun textual-replicate textual from to :optional start end
7808 [R7RS text]
7809 @c MOD scheme.text
7810 @end defun
7811
7812 @defun textual-split textual delimiter :optional grammar limit start end
7813 [R7RS text]
7814 @c MOD scheme.text
7815 Like @code{string-split}, except that the returned strings are all
7816 immutable and indexed. @xref{String utilities}, for the details.
7817 @end defun
7818
7819
7820 @node R7RS generators, R7RS lazy sequences, R7RS immutable texts, R7RS large
7821 @subsection @code{scheme.generator} - R7RS generators
7822 @c NODE R7RSジェネレータ, @code{scheme.generator} - R7RSジェネレータ
7823
7824 @deftp {Module} scheme.generator
7825 @mdindex scheme.generator
7826 @c EN
7827 This module provides generators and accumulators.
7828 They were first defined in SRFI-121,
7829 then enhanced in SRFI-158, and finally
7830 incorporated R7RS large as @code{(scheme generator)}.
7831 @c JP
7832 このモジュールは、ジェネレータとアキュムレータを提供します。
7833 これらは最初にSRFI-121で定義され、SRFI-158で拡張された後、
7834 @code{(scheme generator)}としてR7RS largeに取り込まれました。
7835 @c COMMON
7836
7837 @c EN
7838 A generator is a thunk to generate a sequence of values, potentially
7839 terminated by EOF. Procedures to deal with generators are
7840 provided by @code{gauche.generator}, which is a superset of SRFI-121.
7841 @xref{Generators}, for the details.
7842 @c JP
7843 ジェネレータは引数と取らない手続きで、呼ばれる度に値を次々に返し、
7844 EOFを以って終端を示すものです。ジェネレータを扱う手続きは
7845 SRFI-121のスーパーセットである@code{gauche.generator}で提供されています。
7846 詳しくは@ref{Generators}を参照してください。
7847 @c COMMON
7848
7849 @c EN
7850 An accumulator is an opposite of generators.
7851 They are procedures
7852 that work as consumers. An accumulator takes one argument.
7853 When non-eof value is given, the value is stored, and when EOF
7854 is given, the accumulated value is returned.
7855 How the values are accumulated depends on the accumulator.
7856 @c JP
7857 アキュムレータはジェネレータの反対で、値を消費する手続きと考えられます。
7858 アキュムレータは一つの引数を取ります。EOF以外の値が与えられた場合は、
7859 それが内部に何らかの形で蓄えられ、EOFが与えられた場合、
7860 蓄えられた値が返されます。
7861 どのように値が蓄えられるかは各アキュムレータに依存します。
7862 @c COMMON
7863
7864 @c EN
7865 Once EOF is given, the accumulator is ``finalized''. Subsequent
7866 EOF makes it return the same accumulated value. It is undefined
7867 if other values are passed after EOF is passed.
7868 @c JP
7869 一度EOFが与えられると、アキュムレータは終了状態になります。
7870 その後何度EOFが与えられても同じ蓄積結果を返します。
7871 終了状態になったアキュムレータにEOF以外の値を与えた場合の動作は未定義です。
7872 @c COMMON
7873
7874 @c EN
7875 The accumulator can be used to parameterize procedures that yield
7876 aggregate objects. Consider the following procedure, which
7877 takes items from two generators and accumulate them alternatively.
7878 (Note that @code{glet*} is Gauche's procedure but not in SRFI-158).
7879 @c JP
7880 アキュムレータは、複合的なオブジェクトを生成する手続きで、
7881 実際に生成される値の型をパラメタライズするのに使えます。
7882 次の手続きを見てみましょう。これは二つのジェネレータから交互に値を取り、
7883 それを蓄積して返す手続きです。
7884 (@code{glet*}はGaucheの手続きですがSRFI-158には含まれていません。)
7885 @c COMMON
7886
7887 @example
7888 (define (intertwine acc gen1 gen2)
7889 (let loop ()
7890 (glet* ([a (gen1)]
7891 [b (gen2)])
7892 (acc a)
7893 (acc b)
7894 (loop)))
7895 (acc (eof-object)))
7896 @end example
7897
7898 @c EN
7899 The procedure can return various type of collections, without
7900 knowing the actual type---the passed accumulator determines it.
7901 @c JP
7902 この手続きは具体的に返される値が何かは関知しません。
7903 それは引数に与えられたアキュムレータにより決定されます。
7904 @c COMMON
7905
7906 @example
7907 (intertwine (list-accumulator) (giota 5) (giota 5 100))
7908 @result{} (0 100 1 101 2 102 3 103 4 104)
7909 (intertwine (vector-accumulator) (giota 5) (giota 5 100))
7910 @result{} #(0 100 1 101 2 102 3 103 4 104)
7911 (intertwine (bytevector-accumulator) (giota 5) (giota 5 100))
7912 @result{} #u8(0 100 1 101 2 102 3 103 4 104)
7913 @end example
7914
7915 @c EN
7916 Note: In Gauche, you can also use classes to parameterize returned
7917 container types (e.g. @code{map-to}),
7918 for many collection classes support @emph{builder protocol}.
7919 @xref{Collection framework}, for the details.
7920 Accumulator has the flexibility that you can provide more than one
7921 ways to construct return value on the same type (e.g. forward and reverse
7922 list).
7923 @c JP
7924 註: Gaucheでは、クラスを使うことで戻り値となるコンテナの型をパラメタライズできます
7925 (例: @code{map-to})。これは多くのコレクションクラスが@emph{builderプロトコル}を
7926 サポートしているからです。詳しくは@ref{Collection framework}を見てください。
7927 アキュムレータの利点は、同じ型の戻り値についても、異なる値の蓄積方法
7928 (例えばリストを順に蓄積するか逆順に蓄積するか、等)を提供できることです。
7929 @c COMMON
7930 @end deftp
7931
7932 @c EN
7933 The following generator procedures are explained in
7934 @code{gauche.generator} section (@pxref{Generators}):
7935 @c JP
7936 以下のジェネレータ手続きは、@code{gauche.generator}のセクションで
7937 解説してあります(@ref{Generators}参照)。
7938 @c COMMON
7939
7940 @itemize
7941 @item @ref{Generator constructors}:
7942 @example
7943 generator circular-generator make-iota-generator
7944 make-range-generator make-coroutine-generator
7945 make-unfold-generator make-for-each-generator
7946 list->generator
7947 vector->generator reverse-vector->generator
7948 string->generator bytevector->generator
7949 @end example
7950 @item @ref{Generator operations}:
7951 @example
7952 gcons* gappend gflatten
7953 ggroup gmerge gmap
7954 gcombine gfilter gremove
7955 gstate-filter ggroup
7956 gtake gdrop gtake-while
7957 gdrop-while gdelete gdelete-neighbor-dups
7958 gindex gselect
7959 @end example
7960 @item @ref{Generator consumers}:
7961 @example
7962 generator->list generator->reverse-list generator-map->list
7963 generator->vector generator->vector! generator->string
7964 generator-count generator-any generator-every
7965 generator-unfold
7966 @end example
7967 @item @ref{Folding generated values}:
7968 @example
7969 generator-fold generator-for-each generator-find
7970 @end example
7971 @end itemize
7972
7973 @c EN
7974 The following are accumulator procedures:
7975 @c JP
7976 以下はアキュムレータ手続きです。
7977 @c COMMON
7978
7979 @defun make-accumulator kons knil finalizer
7980 [R7RS generator]
7981 @c MOD scheme.generator
7982 @c EN
7983 Creates and returns an accumulator with a state,
7984 whose initial value is @var{knil}.
7985 When non-EOF value @var{v} is passed to the accumulator,
7986 @var{kons} is called as @code{(kons v state)}, and its result
7987 becomes the new state value. When EOF value is passed,
7988 @code{(finalizer state)} is called and its result becomes
7989 the result of accumulator.
7990 @c JP
7991 内部状態をひとつ持つアキュムレータを作って返します。
7992 状態は@var{khil}で初期化されます。
7993 EOFでない値@var{v}がアキュムレータに与えられる度に、手続き@var{kons}が
7994 @code{(kons v state)}と呼ばれ、その戻り値が新たな状態となります。
7995 EOFがアキュムレータに渡されると、@code{(finalizer state)}が呼ばれ、
7996 その結果がアキュムレータの戻り値となります。
7997 @c COMMON
7998 @end defun
7999
8000 @defun list-accumulator
8001 @defunx reverse-list-accumulator
8002 [R7RS generator]
8003 @c MOD scheme.generator
8004 @c EN
8005 Creates and returns accumulators that return accumulated value
8006 as a list, in the accumulated order (@code{list-accumulator})
8007 or the reverse order (@code{reverse-list-accumulator}).
8008 @c JP
8009 蓄積された値をリストとして返すアキュムレータを作って返します。
8010 @code{list-accumulator}ではリストは与えられた順に、
8011 @code{reverse-list-accumulator}では逆順になります。
8012 @c COMMON
8013 @end defun
8014
8015 @defun vector-accumulator
8016 @defunx reverse-vector-accumulator
8017 @defunx bytevector-accumulator
8018 [R7RS generator]
8019 @c MOD scheme.generator
8020 @c EN
8021 Returns accumulators that return accumulated value
8022 as a fresh vector or bytevector (u8vector),
8023 in the accumulated order (@code{vector-accumulator},
8024 @code{bytevector-accumulator})
8025 or the reverse order (@code{reverse-vector-accumulator}).
8026 There's no @code{reverse-bytevector-accumulator}.
8027 @c JP
8028 蓄積された値をベクタあるいはバイトベクタ(u8vector)として返すアキュムレータを
8029 作って返します。@code{vector-accumulator}と
8030 @code{bytevector-accumulator}では値は先頭から順に、
8031 @code{reverse-vector-accumulator}ではベクタの最後から逆順に詰められます。
8032 @code{reverse-bytevector-accumulator}はありません。
8033 @c COMMON
8034 @end defun
8035
8036 @defun vector-accumulator! vec at
8037 @defunx bytevector-accumulator! bvec at
8038 [R7RS generator]
8039 @c MOD scheme.generator
8040 @c EN
8041 The @var{vec} or @var{bvec} argument is a mutable vector or
8042 bytevector (u8vector), and is used as a buffer.
8043
8044 Returns an accumulator that stores the accumulated values in the
8045 buffer, starting from the index @var{at}.
8046 It is an error if the accumulator gets more values after
8047 the buffer reaches at the end.
8048
8049 Once EOF is passed to the accumulator, @var{vec} or @var{bvec}
8050 is returned, respectively.
8051 @c JP
8052 @var{vec}と@var{bvec}はそれぞれ変更可能なベクタとバイトベクタ(u8vector)です。
8053 この引数はバッファとして使われます。
8054
8055 与えられた値を、バッファのインデックス@var{at}から順に格納してゆくアキュムレータを
8056 作って返します。バッファの最後を越えて値を格納しようとした場合はエラーになります。
8057
8058 EOFが与えられたら、@var{vec}または@var{bvec}をそのまま返します。
8059 @c COMMON
8060 @end defun
8061
8062 @defun string-accumulator
8063 [R7RS generator]
8064 @c MOD scheme.generator
8065 @c EN
8066 Returns an accumulator that accepts characters and accumulates
8067 them to a string.
8068 @c JP
8069 文字を受け取り、それを蓄積して最後に文字列として返すアキュムレータを生成して返します。
8070 @c COMMON
8071 @end defun
8072
8073 @defun sum-accumulator
8074 @defunx product-accumulator
8075 @defunx count-accumulator
8076 [R7RS generator]
8077 @c MOD scheme.generator
8078 @c EN
8079 Returns accumulators that yield a scalar value.
8080
8081 The accumulator created by @code{sum-accumulator} and
8082 @code{product-accumulator} accepts numbers,
8083 and keep adding or multiplying it with the accumulated value
8084 (the default value is 0 and 1, respectively).
8085
8086 The accumulator created by @code{count-accumulator} accepts any
8087 objects and just counting it.
8088 @c JP
8089 スカラー値を生成するアキュムレータを作って返します。
8090
8091 @code{sum-accumulator}と@code{product-accumulator}で作られた
8092 アキュムレータはそれぞれ、
8093 数値を受け取り、それを蓄積された値に加算または乗算してゆきます。
8094 値の初期値はそれぞれ0と1です。
8095
8096 @code{count-accumulator}で作られたアキュムレータは
8097 任意のオブジェクトを受け取ります。
8098 EOFを受け取ったらそれまで受け取ったオブジェクトの数を返します。
8099 @c COMMON
8100 @end defun
8101
8102
8103 @node R7RS lazy sequences, R7RS stream, R7RS generators, R7RS large
8104 @subsection @code{scheme.lseq} - R7RS lazy sequences
8105 @c NODE R7RS遅延シーケンス, @code{scheme.lseq} - R7RS遅延シーケンス
8106
8107
8108 @deftp {Module} scheme.lseq
8109 @mdindex scheme.lseq
8110 This module provides lightweight lazy sequence (lseq), conceptually represented
8111 by a pair of element and generator. When the rest of sequence is
8112 taken, the generator is evaluated and yields another pair of element and
8113 generator, and so on. The overhead is one allocation of a pair per
8114 element. It is much lighter than streams (@pxref{Stream library}),
8115 which requires to create a thunk for every element.
8116
8117 Gauche already has built-in support for such lazy sequences;
8118 we go further to make it behave like ordinary pairs---that is, if you
8119 take cdr of a lazy pair, we automatically forces the generator so
8120 it is indistinguishable from an ordinary pair, modulo side effects.
8121 @xref{Lazy sequences}.
8122
8123 SRFI-127, the original srfi for this module,
8124 is a bit ambiguous whether its lazy sequence @emph{must} be
8125 implemented with a pair whose cdr is a generator procedure, or
8126 it refers to the pair+generator as a conceptual model. Considering
8127 of the purpose of lazy sequence, the concrete implementation shouldn't
8128 matter; that is, the user of lazy sequence should not count on the fact
8129 that the lseq is an improper list terminated by a generator procedure.
8130 Instead, an lseq should be treated as an opaque object that can be
8131 passed to @code{scheme.lseq} procedures.
8132
8133 With that premise, we implement this module as just a thin wrapper of
8134 Gauche's native lazy sequence. It is upper-compatible,
8135 except that the code that assumes the internal structure could break.
8136 Notably, the constructor @code{generator->lseq} is the same as
8137 Gauche's built-in, which returns Gauche's lseq, undistinguishable
8138 to the ordinary list.
8139
8140 @example
8141 (procedure? (generator->lseq (generator 1)))
8142 ;; => #t, in SRFI-127 reference implementation,
8143 ;; #f, in our implementation.
8144 @end example
8145 @end deftp
8146
8147 @defun lseq? x
8148 [R7RS lseq]
8149 @c MOD scheme.lseq
8150 Returns true iff @var{x} is an object that can be passed to
8151 lseq procedures. In Gauche, it returns @code{#t} if @var{x} is
8152 a pair or an empty list, since a lazy pair is indistinguishable
8153 from a pair.
8154 @end defun
8155
8156 @defun lseq=? elt=? lseq1 lseq2
8157 [R7RS lseq]
8158 @c MOD scheme.lseq
8159 Compare two lseqs element-wise using @code{elt=?} and returns @code{#t}
8160 iff two lseqs are equal.
8161 @end defun
8162
8163 @defun lseq-car lseq
8164 @defunx lseq-first lseq
8165 [R7RS lseq]
8166 @c MOD scheme.lseq
8167 Returns the first item of @var{lseq}. If @var{lseq} is empty, an error
8168 is raised. In Gauche, these are just aliases of @code{car}.
8169 @end defun
8170
8171 @defun lseq-cdr lseq
8172 @defunx lseq-rest lseq
8173 [R7RS lseq]
8174 @c MOD scheme.lseq
8175 Returns the rest of @var{lseq}. If @var{lseq} is empty, an error
8176 is raised. In Gauche, these are just aliases of @code{cdr}.
8177 @end defun
8178
8179 @defun lseq-take lseq k
8180 @defunx lseq-drop lseq k
8181 [R7RS lseq]
8182 @c MOD scheme.lseq
8183 Returns an lseq that has first @code{k} items,
8184 or an lseq that skips first @code{k} items, respectively.
8185
8186 An error is signaled when the resulting lseq of @code{lseq-take}
8187 reached at the end of sequence before @code{k} items are taken.
8188 It is different from Gauche's @code{ltake}, which simply returns @code{()}
8189 in such case.
8190
8191 On the other hand, @code{lseq-drop} is the same as @code{drop}
8192 in Gauche; it just drops @var{k} items from the head of input
8193 sequence, regardless of whether it is an ordinary list or lseq.
8194 @end defun
8195
8196 @defun lseq-realize lseq
8197 [R7RS lseq]
8198 @c MOD scheme.lseq
8199 Realizes all the elements in @var{lseq}, resulting an ordinary list.
8200 @end defun
8201
8202 @defun lseq->generator lseq
8203 [R7RS lseq]
8204 @c MOD scheme.lseq
8205 Creates a generator from @var{lseq}. In Gauche, this is same
8206 as @code{list->generator}.
8207 @end defun
8208
8209 @defun lseq-length lseq
8210 [R7RS lseq]
8211 @c MOD scheme.lseq
8212 Returns the length of @var{lseq}. All the elements in @var{lseq} are
8213 realized as the side effect. In Gauche, this is same as @code{length}.
8214 @end defun
8215
8216 @defun lseq-append lseq lseq2 @dots{}
8217 [R7RS lseq]
8218 @c MOD scheme.lseq
8219 Append one or more @var{lseq}s lazily. This is the same as @code{lappend}
8220 in Gauche.
8221 @end defun
8222
8223 @defun lseq-zip lseq lseq2 @dots{}
8224 [R7RS lseq]
8225 @c MOD scheme.lseq
8226 Returns a lazy sequence in which the first element is a list of
8227 first elements of @code{lseq}s, and so on.
8228 @end defun
8229
8230 @defun lseq-map proc lseq lseq2 @dots{}
8231 [R7RS lseq]
8232 @c MOD scheme.lseq
8233 Lazy map. The same as Gauche's @code{lmap}. Returns a lazy sequence.
8234 @end defun
8235
8236 @defun lseq-for-each proc lseq lseq2 @dots{}
8237 [R7RS lseq]
8238 @c MOD scheme.lseq
8239 This one consumes all the input lseqs, applying @var{proc} on
8240 each corresponding elements of the input sequences for the side
8241 effects. In Gauche, it is the same as @code{for-each}, for
8242 Gauche doesn't distinguish lseqs and ordinary lists.
8243 @end defun
8244
8245 @defun lseq-filter pred lseq
8246 @defunx lseq-remove pred lseq
8247 [R7RS lseq]
8248 @c MOD scheme.lseq
8249 Returns an lseq that contains elements from the input
8250 @var{lseq} that satisfy or don't satisfy @var{pred}, respectively.
8251 @code{Lseq-filter} is the same as Gauche's @code{lfilter}.
8252 @end defun
8253
8254 @defun lseq-take-while pred lseq
8255 @defunx lseq-drop-while pred lseq
8256 [R7RS lseq]
8257 @c MOD scheme.lseq
8258 These are the same as Gauche's @code{ltake-while} and @code{drop-while}
8259 (the latter doesn't have @code{l}-prefix, since it just drops items
8260 from the head of the input sequence, regardless of whether it is
8261 an ordinary list or an lseq.
8262 @end defun
8263
8264 @defun lseq-find pred lseq
8265 @defunx lseq-find-tail pred lseq
8266 @defunx lseq-any pred lseq
8267 @defunx lseq-every pred lseq
8268 @defunx lseq-index pred lseq
8269 @defunx lseq-member pred lseq :optional eq
8270 @defunx lseq-memq pred lseq
8271 @defunx lseq-memv pred lseq
8272 [R7RS lseq]
8273 @c MOD scheme.lseq
8274 In Gauche, these are the same as the corresponding list functions,
8275 @code{find}, @code{find-tail}, @code{any}, @code{every},
8276 @code{list-index}, @code{member}, @code{memq} and @code{memv}, respectively,
8277 for all of those functions won't look at input more than necessary
8278 so @var{lseq}s work just as well as ordinary lists.
8279 @end defun
8280
8281 @node R7RS stream, R7RS boxes, R7RS lazy sequences, R7RS large
8282 @subsection @code{scheme.stream} - R7RS stream
8283 @c NODE R7RSストリーム, @code{scheme.stream} - R7RSストリーム
8284
8285 @deftp {Module} scheme.stream
8286 @mdindex scheme.stream
8287 @c EN
8288 This module provides utilities for lazily evaluated streams.
8289 It is more heavyweight than lazy sequences (@pxref{Lazy sequences}),
8290 but it strictly implements ``as lazy as possible'' semantics---elements
8291 are never evaluated until it is actually accessed.
8292 @c JP
8293 遅延評価ストリームのユーティリティを提供するモジュールです。
8294 遅延シーケンス(@ref{Lazy sequences}参照)よりも重いですが、
8295 「可能な限り遅延する」セマンティクスを厳密に実装しています。
8296 つまり、要素は本当に必要とされるまで決して評価されません。
8297 @c COMMON
8298
8299 @c EN
8300 The following procedures are provided in Gauche's @code{util.stream} module;
8301 @pxref{Stream library} for their description:
8302 @c JP
8303 以下の手続きはGaucheの@code{util.streams}モジュールで提供されるものと同じです。
8304 説明は@ref{Stream library}を参照してください。
8305 @c COMMON
8306
8307 @example
8308 stream-null stream-cons stream? stream-null?
8309 stream-pair? stream-car stream-cdr stream-lambda
8310
8311 define-stream list->stream port->stream
8312 stream->list stream-append stream-concat stream-constant
8313 stream-drop-while stream-filter stream-fold
8314 stream-for-each stream-from stream-iterate stream-length
8315 stream-let stream-map stream-match stream-of
8316 stream-range stream-ref stream-reverse stream-scan
8317 stream-take-while stream-unfold stream-unfolds stream-zip
8318 @end example
8319
8320 @c EN
8321 The following macro and procedures have different interface from
8322 Gauche's @code{util.stream} module:
8323 @c JP
8324 以下のマクロと手続きはGaucheの@code{util.stream}とはインタフェースが異なります。
8325 @c COMMON
8326
8327 @example
8328 stream stream-take stream-drop
8329 @end example
8330 @end deftp
8331
8332 @defmac stream expr @dots{}
8333 [R7RS stream]
8334 @c MOD scheme.stream
8335 @c EN
8336 Returns a new stream whose elements are the result of @var{expr} @dots{}.
8337 Arguments won't be evaluated until required.
8338 @c JP
8339 @var{expr} @dots{}の結果を要素とする新たなストリームを作って返します。
8340 各@var{expr}は必要となるまで評価されません。
8341 @c COMMON
8342
8343 @c EN
8344 This differs from SRFI-40 and @code{util.stream}'s @code{stream},
8345 which is a procedure so arguments are evaluated
8346 (@pxref{Stream constructors}, for the details).
8347 @c JP
8348 SRFI-40および@code{util.stream}の@code{stream}は単なる手続きであり、
8349 各@var{expr}は呼び出し時に評価されてしまうことが異なります
8350 (@ref{Stream constructors}参照)。
8351 @c COMMON
8352 @end defmac
8353
8354
8355 @defun stream-take n stream
8356 @defunx stream-drop n stream
8357 [R7RS stream]
8358 @c MOD scheme.stream
8359 @c EN
8360 Returns a stream that contains first @var{n} elements from @var{stream},
8361 or elements without first @var{n} elements from it, respectively.
8362 If @var{stream} has less than @var{n} elements, @code{stream-take}
8363 returns a copy of the entire @var{stream}, while @code{stream-drop}
8364 returns a null stream.
8365 @c JP
8366 それぞれ、@var{stream}の最初の@var{n}要素を含むストリーム、
8367 および最初の@var{n}要素を除いたストリームを返します。
8368 @var{stream}の要素数が@var{n}より小さい場合、
8369 @code{stream-take}は@var{stream}全体のコピーを返し、
8370 @code{stream-drop}は空のストリームを返します。
8371 @c COMMON
8372
8373 @c EN
8374 Note that the argument order doesn't follow the Scheme tradition,
8375 which takes the main object (@var{stream} in this case) first, then
8376 the count. Procedures with the same name is provided in @code{util.stream}
8377 with the different argument order.
8378 @c JP
8379 引数順がSchemeの慣習と違っていることに注意してください。
8380 Schemeは通常、主となるオブジェクト(この場合は@var{stream})を第一引数に取ります。
8381 @code{util.stream}の同名の手続きはそうなっています。
8382 @c COMMON
8383 @end defun
8384
8385 @node R7RS boxes, R7RS list queues, R7RS stream, R7RS large
8386 @subsection @code{scheme.box} - R7RS boxes
8387 @c NODE R7RSボックス, @code{scheme.box} - R7RSボックス
8388
8389 @deftp {Module} scheme.box
8390 @mdindex scheme.box
8391 @c EN
8392 Gauche supports boxes built-in (@pxref{Boxes}), so this module
8393 is merely a facade that exports the following identifiers:
8394 @c JP
8395 Gaucheは組み込みでboxをサポートしています (@ref{Boxes}参照)。
8396 このモジュールは以下の識別子をエクスポートするラッパーです。
8397 @c COMMON
8398
8399 @example
8400 box box? unbox set-box!
8401 @end example
8402 @end deftp
8403
8404 @node R7RS list queues, R7RS ephemerons, R7RS boxes, R7RS large
8405 @subsection @code{scheme.list-queue} - R7RS list queues
8406 @c NODE R7RSリストキュー, @code{scheme.list-queue} - R7RSリストキュー
8407
8408 @deftp {Module} scheme.list-queue
8409 @mdindex scheme.list-queue
8410 @c EN
8411 A library of simple queue based on lists.
8412 Gauche has a queue support in @code{data.queue} module, which also
8413 includes MT-safe queue (@pxref{Queue}). This library is implemented
8414 on top of @code{data.queue}'s @code{<queue>} object and mainly provided
8415 for portable code.
8416 @c JP
8417 リストを元にしたキューのライブラリです。
8418 Gaucheは@code{data.queue}モジュールでキューをサポートしています
8419 (スレッドセーフなキューも含まれています。詳しくは@ref{Queue}を参照。)
8420 このモジュールは、主としてポータブルなコードのために、
8421 @code{data.queue}の@code{<queue>}の上に実装されています。
8422 @c COMMON
8423
8424 @c EN
8425 The list-queue is just an instance of @code{<queue>}, so you can
8426 pass a queue created by @code{make-queue} to @code{scheme.list-queue}
8427 API and
8428 a list-queue created by @code{make-list-queue} to Gauche's queue API.
8429 @c JP
8430 このモジュールでいうリストキューは@code{<queue>}のインスタンスそのものなので、
8431 @code{make-queue}で作ったキューを@code{scheme.list-queue}のAPIに渡したり、
8432 @code{make-list-queue}で作ったキューをGaucheのキューAPIに渡すこともできます。
8433 @c COMMON
8434
8435 @c EN
8436 Note: Some API of this library requires to return internal pairs the queue
8437 uses, for the efficiency.
8438 The pair's car/cdr will be mutated by subsequent queue operation,
8439 and also any mutation done on the pair would cause inconsistency
8440 in the original queue.
8441 @c JP
8442 註: このライブラリのAPIには、性能のために、
8443 キューが使う内部のペアをそのまま返すことを要求されている
8444 ものがあります。これらの内部ペアはキューの操作によって破壊的に変更される可能性があります。
8445 ユーザ側でも変更した場合、その後のキューの動作は保証されません。
8446 @c COMMON
8447 @end deftp
8448
8449 @defun make-list-queue lis :optional last
8450 [R7RS list-queue]
8451 @c MOD scheme.list-queue
8452 @c EN
8453 Creates and returns a list-queue whose initial content is @var{lis}.
8454 In Gauche, a list queue is just an instance of @code{<queue>} (@pxref{Queue}).
8455
8456 The cells in @var{lis} are owned by the queue; the caller shouldn't mutate
8457 it afterwards, nor assume its structure remains the same.
8458
8459 The optional @var{last} argument must be the last pair of @var{lis}.
8460 If it is passed, @code{make-list-queue} will skip scanning @var{lis}
8461 and just hold a reference to @var{last} as the tail of the queue.
8462 @c JP
8463 リスト@var{lis}の内容を初期値として持つリストキューを作って返します。
8464 Gaucheでは、リストキューは@code{<queue>}のインスタンスです(@ref{Queue}参照)。
8465
8466 @var{lis}の実体は作成されたキューの所有物となります。
8467 呼び出し側は、この関数を呼んだ後で@var{lis}を変更してはいけません。
8468 また、作成されたキューの操作によって@var{lis}の内容は変更されるでしょう。
8469
8470 省略可能な@var{last}引数は、もし与えられる場合は、@var{lis}の最後のペアで
8471 なければなりません。この引数が渡された場合、@code{make-list-queue}は自分で
8472 リストの末尾のペアを見つけるかわりに、呼び出し側を信頼して@var{last}を最後の
8473 ペアとして保持します。
8474 @c COMMON
8475 @end defun
8476
8477 @defun list-queue elt @dots{}
8478 [R7RS list-queue]
8479 @c MOD scheme.list-queue
8480 @c EN
8481 Creates and returns a list-queue whose initial content is @var{elt} @dots{}.
8482 In Gauche, a list queue is just an instance of @code{<queue>} (@pxref{Queue}).
8483 @c JP
8484 @var{elt} @dots{}を初期内容とするリストキューを作成して返します。
8485 Gaucheでは、リストキューは@code{<queue>}のインスタンスです(@ref{Queue}参照)。
8486 @c COMMON
8487 @end defun
8488
8489 @defun list-queue-copy queue
8490 [R7RS list-queue]
8491 @c MOD scheme.list-queue
8492 @c EN
8493 Returns a copy of a list-queue @var{queue}.
8494 @c JP
8495 リストキュー@var{queue}のコピーを返します。
8496 @c COMMON
8497 @end defun
8498
8499 @defun list-queue-unfold p f g seed :optional queue
8500 [R7RS list-queue]
8501 @c MOD scheme.list-queue
8502 @c EN
8503 Prepend @var{queue} with the items generated by
8504 @code{(unfold p f g seed)} and returns the updated queue.
8505 @xref{R7RS lists}, for @code{unfold}.
8506 If @var{queue} is omitted, a fresh queue is created.
8507 @c JP
8508 リストキュー@var{queue}の前に、@code{(unfold p f g seed)}で生成される
8509 要素を付け足して、@var{queue}を返します。
8510 @code{unfold}については@ref{R7RS lists}を参照してください。
8511 @var{queue}が省略された場合は新たに作成したキューを使います。
8512 @c COMMON
8513
8514 @example
8515 (list-queue-unfold (pa$ = 5) ; p
8516 (pa$ * 2) ; f
8517 (pa$ + 1) ; g
8518 0 ; seed
8519 (list-queue 'x 'y 'z))
8520 @result{} @r{a queue containing (0 2 4 6 8 x y z)}
8521 @end example
8522 @end defun
8523
8524 @defun list-queue-unfold-right p f g seed :optional queue
8525 [R7RS list-queue]
8526 @c MOD scheme.list-queue
8527 @c EN
8528 Append @var{queue} with the items generated by
8529 @code{(unfold-right p f g seed)} and returns the updated queue.
8530 @xref{R7RS lists}, for @code{unfold-right}.
8531 If @var{queue} is omitted, a fresh queue is created.
8532 @c JP
8533 @var{queue}の後ろに、@code{(unfold-right p f g seed)}で生成される
8534 要素を付け足して、@var{queue}を返します。
8535 @code{unfold-right}については@ref{R7RS lists}を参照してください。
8536 @var{queue}が省略された場合は
8537 新たに作成したキューを使います。
8538 @c COMMON
8539
8540 @example
8541 (list-queue-unfold-right (pa$ = 5) ; p
8542 (pa$ * 2) ; f
8543 (pa$ + 1) ; g
8544 0 ; seed
8545 (list-queue 'x 'y 'z))
8546 @result{} @r{a queue containing (x y z 8 6 4 2 0)}
8547 @end example
8548 @end defun
8549
8550 @defun list-queue? obj
8551 [R7RS list-queue]
8552 @c MOD scheme.list-queue
8553 @c EN
8554 Returns true iff @var{queue} is a list-queue.
8555 In Gauche, it is the same as @code{queue?} in the @code{data.queue} module.
8556 @c JP
8557 @var{queue}がリストキューなら@code{#t}を、そうでなければ@code{#f}を返します。
8558 Gaucheでは@code{data.queue}モジュールの@code{queue?}と同じです。
8559 @c COMMON
8560 @end defun
8561
8562 @defun list-queue-empty? queue
8563 [R7RS list-queue]
8564 @c MOD scheme.list-queue
8565 @c EN
8566 Returns true iff @var{queue} is empty.
8567 Same as @code{queue-empty?} of @code{data.queue}.
8568 @c JP
8569 @var{queue}が空なら@code{#t}を、そうでなければ@code{#f}を返します。
8570 @code{data.queue}の@code{queue-empty?}と同じです。
8571 @c COMMON
8572 @end defun
8573
8574 @defun list-queue-front queue
8575 [R7RS list-queue]
8576 @c MOD scheme.list-queue
8577 @c EN
8578 Returns the front element of the @var{queue}.
8579 An error is thrown if @var{queue} is empty.
8580 Same as @code{queue-front} of @code{data.queue}.
8581 @c JP
8582 @var{queue}の先頭の要素を返します。@var{queue}が空の場合はエラーを報告します。
8583 @code{data.queue}の@code{queue-front}と同じです。
8584 @c COMMON
8585 @end defun
8586
8587 @defun list-queue-back queue
8588 [R7RS list-queue]
8589 @c MOD scheme.list-queue
8590 @c EN
8591 Returns the rear element of the @var{queue}.
8592 An error is thrown if @var{queue} is empty.
8593 Same as @code{queue-rear} of @code{data.queue}.
8594 @c JP
8595 @var{queue}の末尾の要素を返します。@var{queue}が空の場合はエラーを報告します。
8596 @code{data.queue}の@code{queue-rear}と同じです。
8597 @c COMMON
8598 @end defun
8599
8600 @defun list-queue-list queue
8601 [R7RS list-queue]
8602 @c MOD scheme.list-queue
8603 @c EN
8604 Returns the internal list of @var{queue}.
8605 Note that the list would be modified by subsequent operations of @var{queue},
8606 and any modification on the list would make @var{queue} inconsistent.
8607 The primary purpose of this procedure is to implement other
8608 queue-related operations with small overhead.
8609
8610 If you merely need a cheap access the content of the queue,
8611 consider @code{list-queue-remove-all!}.
8612 That returns the list of elements of the queue without copying, and
8613 simultaneously reset the queue to empty, so it's safe.
8614 @c JP
8615 @var{queue}が内部的に保持している要素のリストを返します。
8616 返されたリストは、@var{queue}が操作されれば破壊的に変更される可能性があり、
8617 また返されたリストを破壊的に変更した場合は@var{queue}の一貫性が失われます。
8618 この手続きの主な目的は、他のキュー操作を効率よく実装することです。
8619
8620 単にキューの中身にオーバーヘッド無くアクセスしたい場合は、
8621 @code{list-queue-remove-all!}が使えないかどうか検討してください。
8622 そちらはキューの中身のリストを直接返すと同時にキュー自体を空にするので、安全です。
8623 @c COMMON
8624 @end defun
8625
8626 @defun list-queue-fist-last queue
8627 [R7RS list-queue]
8628 @c MOD scheme.list-queue
8629 @c EN
8630 Returns two values, the first and last pair of @var{queue}.
8631 If the queue is empty, two empty lists are returned.
8632
8633 This also returns the internal pair of the queue, so
8634 any subsequent operations of @var{queue} would change the contents
8635 of the pairs, and any modification on the pairs would make @var{queue}
8636 inconsistent.
8637 The purpose of this procedure is to implement other
8638 queue-related operations with small overhead. This procedure should
8639 not be used in general.
8640 @c JP
8641 @var{queue}の内部で要素を保持しているリストの先頭と末尾のペアを返します。
8642 キューが空の場合は、二つの空リストを返します。
8643
8644 この手続きも、@code{list-queue-list}と同じく、内部のリストを直接返すため、
8645 返されたリストは、@var{queue}が操作されれば破壊的に変更される可能性があり、
8646 また返されたリストを破壊的に変更した場合は@var{queue}の一貫性が失われます。
8647 この手続きの主な目的は、他のキュー操作を効率よく実装することであり、
8648 一般的な用途に使うべきではありません。
8649 @c COMMON
8650 @end defun
8651
8652 @defun list-queue-add-front! queue elt
8653 [R7RS list-queue]
8654 @c MOD scheme.list-queue
8655 @c EN
8656 Add @var{elt} to the front of @var{queue}.
8657 Same as @code{(queue-push! queue elt)} of @code{data.queue}.
8658 @c JP
8659 @var{elt}を@var{queue}の先頭に追加します。
8660 @code{data.queue}の@code{(queue-push! queue elt)}と同じです。
8661 @c COMMON
8662 @end defun
8663
8664 @defun list-queue-add-back! queue elt
8665 [R7RS list-queue]
8666 @c MOD scheme.list-queue
8667 @c EN
8668 Add @var{elt} to the back of @var{queue}.
8669 Same as @code{(enqueue! queue elt)} of @code{data.queue}.
8670 @c JP
8671 @var{elt}を@var{queue}の末尾に追加します。
8672 @code{data.queue}の@code{(enqueue! queue elt)}と同じです。
8673 @c COMMON
8674 @end defun
8675
8676 @defun list-queue-remove-front! queue
8677 [R7RS list-queue]
8678 @c MOD scheme.list-queue
8679 @c EN
8680 Remove an element from the front of @var{queue} and returns
8681 the removed element. Throws an error if @var{queue} is empty.
8682 Same as @code{dequeue!} of @code{data.queue}.
8683 @c JP
8684 @var{queue}の先頭から要素をひとつ取り除き、その取り除かれた要素を返します。
8685 @var{queue}が空ならエラーを報告します。
8686 @code{data.queue}の@code{(dequeue! queue elt)}と同じです。
8687 @c COMMON
8688 @end defun
8689
8690 @defun list-queue-remove-back! queue
8691 [R7RS list-queue]
8692 @c MOD scheme.list-queue
8693 @c EN
8694 Remove an element from the back of @var{queue} and returns the
8695 removed element. Throws an error if @var{queue} is empty.
8696 This isn't guaranteed to be efficient; it is O(n)
8697 operation where n is the number of elements.
8698 In general, if you need this operation frequently, you should
8699 consider double-ended queue. (@xref{Immutable deques}, and also
8700 @pxref{Ring buffer}.)
8701 @c JP
8702 @var{queue}の末尾から要素をひとつ取り除き、その取り除かれた要素を返します。
8703 @var{queue}が空ならエラーを報告します。
8704 この手続きは、キューの持つ要素数nに対してO(n)の時間がかかります。
8705 もしこの操作を頻繁に必要とするなら、デック(deque, 両端キュー)を使うことを
8706 検討すべきでしょう。(@ref{Immutable deques}および
8707 @ref{Ring buffer}参照。)
8708 @c COMMON
8709 @end defun
8710
8711 @defun list-queue-remove-all! queue
8712 [R7RS list-queue]
8713 @c MOD scheme.list-queue
8714 @c EN
8715 Remove all the elements from @var{queue} and returns them as a list.
8716 The list isn't copied---this is O(1) operation. This should be preferred
8717 over @code{list-queue-list}, for it's safer.
8718 In Gauche, this is the same as @code{dequeue-all!} in @code{data.queue}.
8719 @c JP
8720 @var{queue}を空にして、入っていた全ての要素をリストで返します。
8721 リストはコピーされません。つまりO(1)の操作です。
8722 可能なら、@code{list-queue-list}よりはこちらを使う方が安全です。
8723 Gaucheでは、これは@code{data.queue}の@code{deque-all!}と同じです。
8724 @c COMMON
8725 @end defun
8726
8727 @defun list-queue-set-list! queue lis :optional last
8728 [R7RS list-queue]
8729 @c MOD scheme.list-queue
8730 @c EN
8731 Modify @var{queue} to have the elements in @var{lis} as its element.
8732 The original content of @var{queue} is discarded. If the optional
8733 @var{last} argument is provided, it must be the last pair of @var{lis},
8734 and the procedure uses that instead of scanning @var{lis}, to achieve
8735 O(1) operation.
8736
8737 After calling this, @var{lis} is owned by @var{queue} and it may
8738 be mutated. The caller shouldn't change, or rely on @var{lis} afterwards.
8739 @c JP
8740 @var{queue}を変更して、@var{lis}の内容がキューの内容になるようにします。
8741 @var{queue}の元の内容は捨てられます。省略可能な@var{last}引数が渡される場合、
8742 それは@var{lis}の最後のペアでなければなりません。手続きは呼び出し元を信頼して、
8743 @var{lis}をスキャンせずに@var{last}を最後のペアと考えることで
8744 O(1)操作を実現しています。
8745
8746 この手続きを呼び出した後では、@var{lis}は@var{queue}に所有され、破壊的変更を
8747 受けます。この後で@var{lis}の内容をあてにしたり変更したりしてはいけません。
8748 @c COMMON
8749 @end defun
8750
8751 @defun list-queue-append queue @dots{}
8752 [R7RS list-queue]
8753 @c MOD scheme.list-queue
8754 @c EN
8755 Returns a fresh list-queue whose contents are concatenation of
8756 @var{queue}s. The contents of arguments are intact.
8757 This is O(n) operation where n is the total number of elements.
8758 @c JP
8759 与えられた@var{queue}を全部つないだ要素を持つリストキューを
8760 新たに作成して返します。引数のキューは変更されません。
8761 これは要素の総数nについてO(n)の操作となります。
8762 @c COMMON
8763 @end defun
8764
8765 @defun list-queue-append! queue @dots{}
8766 [R7RS list-queue]
8767 @c MOD scheme.list-queue
8768 @c EN
8769 Returns a list-queue whose contents are concatenation of
8770 @var{queue}s. During the operation, the contents of @var{queue}s
8771 may be mutated, and they shouldn't be used any longer. (In Gauche,
8772 to avoid accident, we actually empty all the @var{queue}s.)
8773 It is also noted that the result doesn't need to be @code{eq?} to
8774 any of the arguments.
8775 This is O(m) operation where m is the total number of queues
8776 (as opposed to the number of elements).
8777 @c JP
8778 与えられた@var{queue}の要素を全てつないだものを要素とするリストキューを
8779 返します。操作によって、@var{queue}の内容は破壊されることがあり、
8780 以降それらのキューを使ってはなりません
8781 (Gaucheでは、事故を避けるために、全ての@var{queue}を空にしています)。
8782 結果として返されるキューが、引数のどれとも@code{eq?}になる必要はない、
8783 ということに注意してください。
8784 これはキューの総数mに対してO(m)の操作です(要素の総数ではなく)。
8785 @c COMMON
8786 @end defun
8787
8788 @defun list-queue-concatenate queues
8789 [R7RS list-queue]
8790 @c MOD scheme.list-queue
8791 @code{(apply list-queue-append queues)}.
8792 @end defun
8793
8794 @defun list-queue-map proc queue
8795 [R7RS list-queue]
8796 @c MOD scheme.list-queue
8797 @c EN
8798 Returns a fresh list-queue whose elements are obtained by
8799 applying @var{proc} on every elements in @var{queue}.
8800 @c JP
8801 @var{proc}を@var{queue}の各要素に適用して得られた結果を要素とする
8802 新たなリストキューを返します。
8803 @c COMMON
8804 @end defun
8805
8806 @defun list-queue-map! proc queue
8807 [R7RS list-queue]
8808 @c MOD scheme.list-queue
8809 @c EN
8810 Replaces every element in @var{queue} by the result of
8811 application of @var{proc} on the element.
8812 @c JP
8813 @var{queue}の各要素を、それに@var{proc}を適用して得られた結果に
8814 置き替えます。
8815 @c COMMON
8816 @end defun
8817
8818 @defun list-queue-for-each proc queue
8819 [R7RS list-queue]
8820 @c MOD scheme.list-queue
8821 @c EN
8822 Applies @var{proc} on every element of @var{queue}.
8823 The results are discarded.
8824 @c JP
8825 @var{proc}を@var{queue}の各要素に適用します。結果は捨てられます。
8826 @c COMMON
8827 @end defun
8828
8829 @node R7RS ephemerons, R7RS comparators, R7RS list queues, R7RS large
8830 @subsection @code{scheme.ephemeron} - R7RS ephemeron
8831 @c NODE R7RS Ephemeron, @code{scheme.ephemeron} - R7RS Ephemeron
8832
8833 @deftp {Module} scheme.ephemeron
8834 @mdindex scheme.ephemeron
8835 @c EN
8836 This module defined @emph{ephemerons}, a weak reference
8837 structure to hold key-value association. This is originally
8838 defined as SRFI-142.
8839 @c JP
8840 このモジュールは@emph{ephemeron}と呼ばれる、
8841 キーとそれに関連づけられたデータについて弱参照を保持する構造を提供します。
8842 元々はSRFI-142で定義されました。
8843 @c COMMON
8844
8845 @c EN
8846 Gauche supports weak pointers in the form of weak vectors
8847 (@pxref{Weak vectors}), but it is known that a simple weak
8848 pointer (a single pointer that doesn't prevent the pointed
8849 object from being collected) isn't enough to implement
8850 weak key-value association such as mappings.
8851 @c JP
8852 Gaucheはweak vectorとして弱参照を提供しています
8853 (@ref{Weak vectors}参照)が、単なるweak pointer (それに指されている
8854 オブジェクトの回収を許す) だけでは、mappingのようなキーと値を関連付ける
8855 データ構造で弱参照を実現するには不十分なことが知られています。
8856 @c COMMON
8857
8858 @c EN
8859 An ephemeron is a record that points to a key and an associated
8860 datum, with the following characteristics:
8861 @c JP
8862 ephemeronはキーとデータへの参照を保持するレコードで、以下の性質を持ちます。
8863 @c COMMON
8864
8865 @enumerate
8866 @item
8867 @c EN
8868 Reference to the key is weak; it doesn't prevent the key from
8869 being collected if there's no strong reference to the key,
8870 @emph{except from the datum associated by the ephemeron}.
8871 @c JP
8872 キーへの参照はweakです。もし、キーへの強参照が、
8873 @emph{ephemeronを通じて対応しているデータからのものを除いて}
8874 存在しない場合、キーは回収されます。
8875 @c COMMON
8876
8877 @item
8878 @c EN
8879 Reference to the datum is also a kind of weak; it doesn't prevent the datum
8880 from being collected if there's no strong reference to the datum,
8881 @emph{and there's no strong reference to the associated key}.
8882 Note that the datum is retained as long as the key is retained,
8883 even there's no strong reference to the datum itself.
8884 @c JP
8885 データへの参照もある意味weakです。
8886 データへの強参照が存在せず、@emph{かつ対応するキーへの強参照が無い場合}、
8887 データは回収されます。
8888 データへの強参照が無くても、キーが生きていればデータは保持されるという点がポイントです。
8889 @c COMMON
8890 @end enumerate
8891
8892 @c EN
8893 Implementing the proper ephemeron requires deep integration with
8894 the GC. At this moment, Gauche's ephemeron is implemented separately
8895 from GC, and has the following limitations:
8896 @c JP
8897 ephemeronを完全に実装するには、GCとの統合が必要になります。
8898 今のところ、GaucheのephemeronはGCとは独立に実装されており、
8899 以下の制限があります:
8900 @c COMMON
8901
8902 @itemize @bullet
8903 @item
8904 @c EN
8905 If the datum has a strong reference to the associated key, the
8906 key won't be collected even if there's no other strong reference to it.
8907 @c JP
8908 データからキーへの強参照があると、キーは回収されません。
8909 @c COMMON
8910
8911 @item
8912 @c EN
8913 After the key is collected and there's no strong reference to
8914 the datum, @code{ephemeron-broken?} needs to be called in order
8915 to trigger the collection of the datum.
8916 @c JP
8917 キーが回収され、データへの強参照が無い状態になってから、データが回収されるには
8918 @code{ephemeron-broken?}が呼ばれる必要があります。
8919 @c COMMON
8920 @end itemize
8921
8922 @c EN
8923 Since the timing of collection isn't specified in the spec,
8924 Gauche's implementation still conforms SRFI-142, but in practice
8925 you need to be aware of these limitations. Eventually we want
8926 to support full ephemeron integrated with GC.
8927 @c JP
8928 いつ回収されるかについての規定は仕様にないので、Gaucheの現在の実装もSRFI-142の
8929 仕様は満たしているのですが、実際に使うにあたっては上記の制限を意識する必要があるでしょう。
8930 将来的にはGCと統合されたephemeronをサポートしたいと思っています。
8931 @c COMMON
8932
8933 @c EN
8934 Once the key and/or the datum is collected (we call such ephemeron
8935 ``broken''), referencing them returns a bogus value. The proper
8936 way to use an ephemeron @var{e} is the following pattern:
8937 @c JP
8938 キーあるいはデータが回収された後は (この状態のephemeronを ``broken'' と呼びます)、
8939 キーやデータを取り出そうとしても意味のある値は得られません。
8940 ephemeron @var{e}を使う正しい手順は次のパターンです:
8941 @c COMMON
8942
8943 @example
8944 (let ([k (ephemeron-key e)]
8945 [d (ephemeron-datum e)])
8946 (if (ephemeron-broken? e)
8947 (... k and d are invalid ...)
8948 (... k and d are valid ...)))
8949 @end example
8950
8951 @c EN
8952 You should take values, then check if the ephemeron isn't broken yet.
8953 If you call @code{ephemeron-broken?} first, there's a chance
8954 that the ephemeron is broken between the check and the time
8955 you reference it.
8956 @c JP
8957 つまり、値を取り出した後でephemeronがbrokenかどうかを調べます。
8958 先に@code{ephemeron-broken?}を呼んでしまうと、その呼び出しから
8959 値を取り出すまでの間にGCが走ってキーやデータが回収されてしまう可能性があります。
8960 @c COMMON
8961 @end deftp
8962
8963 @defun make-ephemeron key datum
8964 [R7RS ephemeron]
8965 @c MOD scheme.ephemeron
8966 @c EN
8967 Create a new ephemeron associating the @var{key} to the @var{datum}.
8968 @c JP
8969 @var{key}を@var{datum}に関連づけるephemeronを作って返します。
8970 @c COMMON
8971 @end defun
8972
8973 @defun ephemeron? obj
8974 [R7RS ephemeron]
8975 @c MOD scheme.ephemeron
8976 @c EN
8977 Returns @code{#t} iff @var{obj} is an ephemeron.
8978 @c JP
8979 @var{obj}がephemeronであれば@code{#t}を、そうでなければ@var{#f}を返します。
8980 @c COMMON
8981 @end defun
8982
8983
8984 @defun ephemeron-key ephemeron
8985 @defunx ephemeron-datum ephemeron
8986 [R7RS ephemeron]
8987 @c MOD scheme.ephemeron
8988 @c EN
8989 Returns the key and the datum of @var{ephemeron}, respectively.
8990 If the ephemeron is already broken, there's no guarantee
8991 on what is returned. Thus you should always call @code{ephemeron-broken?}
8992 @emph{after} calling these procedure to ensure the values are
8993 meaningful. See the @code{scheme.ephemeron} entry for the details.
8994 @c JP
8995 それぞれ、@var{ephemeron}のキーとデータを返します。
8996 ephemeronが既にbrokenだと、何が返されるかはわかりません。
8997 なので常に、これらの手続きで値を取り出した@emph{後で} @code{ephemeron-broken?}
8998 を呼んで値が有効かどうかチェックする必要があります。
8999 詳しくは上の@code{scheme.ephemeron}のエントリを参照してください。
9000 @c COMMON
9001 @end defun
9002
9003 @defun ephemeron-broken? ephemeron
9004 [R7RS ephemeron]
9005 @c MOD scheme.ephemeron
9006 @c EN
9007 Returns @code{#t} iff @var{ephemeron} has been broken, that is,
9008 its key and/or datum may be collected and cannot be reliably retrieved.
9009 See the @code{scheme.ephemeron} entry for the details.
9010 @c JP
9011 @var{ephemeron}がbrokenであれば@code{#t}を、そうでなければ@code{#f}を返します。
9012 brokenであるとは、キーや値が既に回収されてしまって取り出せないことを意味します。
9013 詳しくは@code{scheme.ephemeron}のエントリを参照してください。
9014 @c COMMON
9015 @end defun
9016
9017 @defun reference-barrier key
9018 [R7RS ephemeron]
9019 @c MOD scheme.ephemeron
9020 @c EN
9021 This procedure does nothing by itself,
9022 but guarantees @var{key} is strongly reference
9023 until returning from this procedure.
9024 @c JP
9025 この手続きはそれ自体は何もしませんが、
9026 この手続きが戻るまで@var{key}への参照が保持されることを保証します。
9027 @c COMMON
9028 @end defun
9029
9030
9031 @node R7RS comparators, R7RS regular expressions, R7RS ephemerons, R7RS large
9032 @subsection @code{scheme.comparator} - R7RS comparators
9033 @c NODE R7RS比較器, @code{scheme.comparator} - R7RS比較器
9034
9035 @deftp {Module} scheme.comparator
9036 @mdindex scheme.comparator
9037 @c EN
9038 This module defines comparators and related procedures.
9039 Originally called @code{srfi.128}.
9040 @c JP
9041 このモジュールは、比較器(comparator)とそれに関わる手続きを提供します。
9042 元々は@code{srfi.128}で定義されました。
9043 @c COMMON
9044
9045 @c EN
9046 Gauche supports comparators fully compatible to
9047 @code{scheme.comparator} built-in.
9048 @xref{Basic comparators}, for the following procedures
9049 defined in this module.
9050 @c JP
9051 Gaucheは@code{scheme.comparator}の上位互換である比較器を組み込みで提供しています。
9052 以下の手続きについては、@ref{Basic comparators}を参照してください。
9053 @c COMMON
9054
9055 @example
9056 comparator? comparator-ordered? comparator-hashable?
9057 make-comparator make-pair-comparator
9058 make-list-comparator make-vector-comparator
9059 make-eq-comparator make-eqv-comparator make-equal-comparator
9060
9061 boolean-hash char-hash char-ci-hash string-hash
9062 string-ci-hash symbol-hash number-hash
9063 hash-bound hash-salt
9064
9065 make-default-comparator default-hash
9066 comparator-register-default!
9067
9068 comparator-type-test-predicate comparator-equality-predicate
9069 comparator-ordering-predicate comparator-hash-function
9070 comparator-test-type comparator-check-type comparator-hash
9071
9072 =? <? >? <=? >=? comparator-if<=>
9073 @end example
9074 @end deftp
9075
9076 @c ----------------------------------------------------------------------
9077 @node R7RS regular expressions, R7RS mappings, R7RS comparators, R7RS large
9078 @subsection @code{scheme.regex} - R7RS regular expressions
9079 @c NODE R7RS正規表現, @code{scheme.regex} - R7RS正規表現
9080
9081 @deftp {Module} scheme.regex
9082 @mdindex scheme.regex
9083 @c COMMON
9084 @c EN
9085 This module provides operations on Scheme Regular Expressions (SRE).
9086 Originally defined as @code{srfi.115}.
9087 @c JP
9088 このモジュールは、Scheme正規表現(Scheme Regular Expressions, SRE)の操作を提供します。
9089 元々は@code{srfi.115}で定義されました。
9090 @c COMMON
9091
9092 @c EN
9093 Gauche has built-in support of regular expressions, and this module
9094 simply tranlsates SRE to Gauche's native regular expressions.
9095 The regular expression object returned from the @code{regexp} procedure
9096 in this module is Gauche's @code{<regexp>} object, for example.
9097 You can pass Gauche's regexp object to the procedures that expects
9098 compiled SRE in this module as well.
9099 @c JP
9100 Gaucheは組み込みで正規表現を提供していて、
9101 このモジュールはSREを組み込み正規表現に変換するだけです。
9102 例えばこのモジュールの@code{regexp}手続きが返す正規表現オブジェクトは、
9103 Gaucheの@code{<regexp>}オブジェクトに他なりません。
9104 また、このモジュールでコンパイルされた正規表現を期待している手続きに、
9105 Gaucheの正規表現オブジェクトを渡すこともできます。
9106 @c COMMON
9107 @end deftp
9108
9109 @c EN
9110 @subheading Scheme regular expression syntax
9111 @c JP
9112 @subheading Scheme正規表現構文
9113 @c COMMON
9114
9115 @c EN
9116 @subsubheading Syntax summary
9117 @c JP
9118 @subsubheading 構文のまとめ
9119 @c COMMON
9120
9121 @c EN
9122 SRE is just an S-expression with the structure summarized below.
9123 @c JP
9124 SREは以下にまとめられた構造を持つS式です。
9125 @c COMMON
9126
9127 @c EN
9128 With the exception of @code{or}, any syntax that takes multiple
9129 @code{<sre>} processes them in a sequence. In other words @code{(foo
9130 <sre> ...)} is equivalent to @code{(foo (seq <sre> ...))}.
9131 @c JP
9132 @code{or}を除き、複数の@code{<sre>}を引数に取る構文はそれら部分式を
9133 シーケンスとして処理します。言い換えれば、
9134 @code{(foo <sre> ...)}は@code{(foo (seq <sre> ...))}と同じということです。
9135 @c COMMON
9136
9137 @c EN
9138 Note: SRE uses the symbol @code{|} for alteration, but the vertical bar
9139 character is used for symbol escape in Gauche (and R7RS), so you have to
9140 write such symbol as @code{|\||}. We recommend to use @code{or} instead.
9141 @c JP
9142 註: SREは縦棒@code{|}を選択演算子に使っていますが、GaucheとR7RSでは
9143 @code{|}はシンボルのエスケープ文字に使われているので、SRE内で使いたければ@code{|\||}
9144 と書かなければなりません。@code{or}を使った方がわかりやすいでしょう。
9145 @c COMMON
9146
9147 @smallexample
9148 <sre> ::=
9149 | <string> ; A literal string match.
9150 | <cset-sre> ; A character set match.
9151 | (* <sre> ...) ; 0 or more matches.
9152 | (zero-or-more <sre> ...)
9153 | (+ <sre> ...) ; 1 or more matches.
9154 | (one-or-more <sre> ...)
9155 | (? <sre> ...) ; 0 or 1 matches.
9156 | (optional <sre> ...)
9157 | (= <n> <sre> ...) ; <n> matches.
9158 | (exactly <n> <sre> ...)
9159 | (>= <n> <sre> ...) ; <n> or more matches.
9160 | (at-least <n> <sre> ...)
9161 | (** <n> <m> <sre> ...) ; <n> to <m> matches.
9162 | (repeated <n> <m> <sre> ...)
9163
9164 | (|\|| <sre> ...) ; Alternation.
9165 | (or <sre> ...)
9166
9167 | (: <sre> ...) ; Sequence.
9168 | (seq <sre> ...)
9169 | ($ <sre> ...) ; Numbered submatch.
9170 | (submatch <sre> ...)
9171 | (-> <name> <sre> ...) ; Named submatch. <name> is
9172 | (submatch-named <name> <sre> ...) ; a symbol.
9173
9174 | (w/case <sre> ...) ; Introduce a case-sensitive context.
9175 | (w/nocase <sre> ...) ; Introduce a case-insensitive context.
9176
9177 | (w/unicode <sre> ...) ; Introduce a unicode context.
9178 | (w/ascii <sre> ...) ; Introduce an ascii context.
9179
9180 | (w/nocapture <sre> ...) ; Ignore all enclosed submatches.
9181
9182 | bos ; Beginning of string.
9183 | eos ; End of string.
9184
9185 | bol ; Beginning of line.
9186 | eol ; End of line.
9187
9188 | bow ; Beginning of word.
9189 | eow ; End of word.
9190 | nwb ; A non-word boundary.
9191 | (word <sre> ...) ; An SRE wrapped in word boundaries.
9192 | (word+ <cset-sre> ...) ; A single word restricted to a cset.
9193 | word ; A single word.
9194
9195 | bog ; Beginning of a grapheme cluster.
9196 | eog ; End of a grapheme cluster.
9197 | grapheme ; A single grapheme cluster.
9198
9199 | (?? <sre> ...) ; A non-greedy pattern, 0 or 1 match.
9200 | (non-greedy-optional <sre> ...)
9201 | (*? <sre> ...) ; Non-greedy 0 or more matches.
9202 | (non-greedy-zero-or-more <sre> ...)
9203 | (**? <m> <n> <sre> ...) ; Non-greedy <m> to <n> matches.
9204 | (non-greedy-repeated <sre> ...)
9205 | (atomic <sre> ...) ; Atomic clustering.
9206
9207 | (look-ahead <sre> ...) ; Zero-width look-ahead assertion.
9208 | (look-behind <sre> ...) ; Zero-width look-behind assertion.
9209 | (neg-look-ahead <sre> ...) ; Zero-width negative look-ahead assertion.
9210 | (neg-look-behind <sre> ...) ; Zero-width negative look-behind assertion.
9211
9212 | (backref <n-or-name>) ; Match a previous submatch.
9213 @c These are extensions
9214 @c | (if-look-ahead <test-sre> <then-sre> [<else-sre>]) ; Conditional pattern
9215 @c | (if-neg-look-ahead <test-sre> <then-sre> [<else-sre>]) ; Conditional pattern
9216 @c | (if-look-behind <test-sre> <then-sre> [<else-sre>]) ; Conditional pattern
9217 @c | (if-neg-look-behind <test-sre> <then-sre> [<else-sre>]) ; Conditional pattern
9218 @c | (if-backref <backref> <then-sre> [<else-sre>]) ; Conditional pattern
9219 @end smallexample
9220
9221 @c EN
9222 The grammar for @code{cset-sre} is as follows.
9223 @c JP
9224 @code{cset-sre}の構文は次のとおりです。
9225 @c COMMON
9226
9227 @smallexample
9228 <cset-sre> ::=
9229 | <char> ; literal char
9230 | "<char>" ; string of one char
9231 | <char-set> ; embedded SRFI 14 char set
9232 | (<string>) ; literal char set
9233 | (char-set <string>)
9234 | (/ <range-spec> ...) ; ranges
9235 | (char-range <range-spec> ...)
9236 | (or <cset-sre> ...) ; union
9237 | (|\|| <cset-sre> ...)
9238 | (and <cset-sre> ...) ; intersection
9239 | (& <cset-sre> ...)
9240 | (- <cset-sre> ...) ; difference
9241 | (- <difference> ...)
9242 | (~ <cset-sre> ...) ; complement of union
9243 | (complement <cset-sre> ...)
9244 | (w/case <cset-sre>) ; case and unicode toggling
9245 | (w/nocase <cset-sre>)
9246 | (w/ascii <cset-sre>)
9247 | (w/unicode <cset-sre>)
9248 | any | nonl | ascii | lower-case | lower
9249 | upper-case | upper | title-case | title
9250 | alphabetic | alpha | alphanumeric | alphanum | alnum
9251 | numeric | num | punctuation | punct | symbol
9252 | graphic | graph | whitespace | white | space
9253 | printing | print | control | cntrl | hex-digit | xdigit
9254
9255 <range-spec> ::= <string> | <char>
9256 @end smallexample
9257
9258 @c EN
9259 @subsubheading Basic patterns
9260 @c JP
9261 @subsubheading 基本パターン
9262 @c COMMON
9263
9264 @table @code
9265 @item <string>
9266
9267 @c EN
9268 A literal string.
9269 @c JP
9270 リテラル文字列。
9271 @c COMMON
9272
9273 @example
9274 (regexp-search "needle" "hayneedlehay")
9275 @result{} #<regexp-match>
9276 (regexp-search "needle" "haynEEdlehay")
9277 @result{} #f
9278 @end example
9279
9280 @item (seq <sre> ...)
9281 @itemx (: <sre> ...)
9282
9283 @c EN
9284 A sequence of patterns that should be matched in the same order. This
9285 is the same as RE syntax @code{(?:@i{re}@dots{})}
9286 @c JP
9287 パターンのシーケンス。入力はパターンに順にマッチしなければなりません。
9288 これは正規表現構文@code{(?:@i{re}@dots{})}と同じです。
9289 @c COMMON
9290
9291 @example
9292 (regexp-search '(: "one" space "two" space "three") "one two three")
9293 @result{} #<regexp-match>
9294 @end example
9295
9296 @item (or <sre> ...)
9297 @itemx (|\|| <sre> ...)
9298
9299 @c EN
9300 Matches one of the given patterns. This is the same as
9301 RE syntax @code{@i{pattern1}|@i{pattern2}|@dots{}}
9302 @c JP
9303 与えられたパターンのどれかにマッチします。
9304 これは正規表現構文@code{@i{pattern1}|@i{pattern2}|@dots{}}と同じです。
9305 @c COMMON
9306
9307 @example
9308 (regexp-search '(or "eeney" "meeney" "miney") "meeney")
9309 @result{} #<regexp-match>
9310 (regexp-search '(or "eeney" "meeney" "miney") "moe")
9311 @result{} #f
9312 @end example
9313
9314 @item (w/nocase <sre> ...)
9315
9316 Changes to match the given patterns case-insensitively. Sub-patterns
9317 can still be made sensitive with @code{w/case}. This is the same as
9318 RE syntax @code{(?i:@i{re}@dots{})}
9319
9320 @example
9321 (regexp-search "needle" "haynEEdlehay") @result{} #f
9322 (regexp-search '(w/nocase "needle") "haynEEdlehay")
9323 @result{} #<regexp-match>
9324
9325 (regexp-search '(~ ("Aab")) "B") @result{} #<regexp-match>
9326 (regexp-search '(~ ("Aab")) "b") @result{} #f
9327 (regexp-search '(w/nocase (~ ("Aab"))) "B") @result{} #f
9328 (regexp-search '(w/nocase (~ ("Aab"))) "b") @result{} #f
9329 (regexp-search '(~ (w/nocase ("Aab"))) "B") @result{} #f
9330 (regexp-search '(~ (w/nocase ("Aab"))) "b") @result{} #f
9331 @end example
9332
9333 @item (w/case <sre> ...)
9334
9335 Changes to match the given patterns case-sensitively. Sub-patterns can
9336 still be made case-insensitive. This is the same as RE syntax
9337 @code{(?-i:@i{re}@dots{})}. This is the default.
9338
9339 @example
9340 (regexp-search '(w/nocase "SMALL" (w/case "BIG")) "smallBIGsmall")
9341 @result{} #<regexp-match>
9342 (regexp-search '(w/nocase (~ (w/case ("Aab")))) "b") @result{} #f
9343 @end example
9344
9345 @item (w/ascii <sre> ...)
9346
9347 Limits the character sets and other predefined patterns to ASCII. This
9348 affects patterns or character sets like @code{any}, @code{alpha},
9349 @code{(word)}@dots{}
9350
9351 @example
9352 (regexp-search '(w/ascii bos (* alpha) eos) "English")
9353 @result{} #<regexp-match>
9354 (regexp-search '(w/ascii bos (* alpha) eos) "Ελληνική") @result{} #f
9355 @end example
9356
9357 @item (w/unicode <sre> ...)
9358
9359 Changes the character sets and other predefined patterns back to
9360 Unicode if @code{w/ascii} has been used in the outer scope. This is
9361 the default.
9362
9363 @example
9364 (regexp-search '(w/unicode bos (* alpha) eos) "English")
9365 @result{} #<regexp-match>
9366 (regexp-search '(w/unicode bos (* alpha) eos) "Ελληνική")
9367 @result{} #<regexp-match>
9368 @end example
9369
9370 @item (w/nocapture <sre> ...)
9371
9372 Disables capturing for all @code{submatch} and @code{submatch-named}
9373 inside.
9374
9375 @example
9376 (let ((number '($ (+ digit))))
9377 (cdr
9378 (regexp-match->list
9379 (regexp-search `(: ,number "-" ,number "-" ,number)
9380 "555-867-5309"))) ; @result{} '("555" "867" "5309")
9381 (cdr
9382 (regexp-match->list
9383 (regexp-search `(: ,number "-" (w/nocapture ,number) "-" ,number)
9384 "555-867-5309")))) @result{} '("555" "5309")
9385 @end example
9386 @end table
9387
9388 @subsubheading Repeating patterns
9389 @table @code
9390 @item (optional <sre> ...)
9391 @itemx (? <sre> ...)
9392
9393 Matches the pattern(s) one or zero times.
9394
9395 @example
9396 (regexp-search '(: "match" (? "es") "!") "matches!")
9397 @result{} #<regexp-match>
9398 (regexp-search '(: "match" (? "es") "!") "match!")
9399 @result{} #<regexp-match>
9400 (regexp-search '(: "match" (? "es") "!") "matche!")
9401 @result{} #f
9402 @end example
9403
9404 @item (zero-or-more <sre> ...)
9405 @itemx (* <sre> ...)
9406
9407 Matches the pattern(s) zero or more times.
9408
9409 @example
9410 (regexp-search '(: "<" (* (~ #\>)) ">") "<html>")
9411 @result{} #<regexp-match>
9412 (regexp-search '(: "<" (* (~ #\>)) ">") "<>")
9413 @result{} #<regexp-match>
9414 (regexp-search '(: "<" (* (~ #\>)) ">") "<html")
9415 @result{} #f
9416 @end example
9417
9418 @item (one-or-more <sre> ...)
9419 @itemx (+ <sre> ...)
9420
9421 Matches the pattern(s) at least once.
9422
9423 @example
9424 (regexp-search '(: "<" (+ (~ #\>)) ">") "<html>")
9425 @result{} #<regexp-match>
9426 (regexp-search '(: "<" (+ (~ #\>)) ">") "<a>")
9427 @result{} #<regexp-match>
9428 (regexp-search '(: "<" (+ (~ #\>)) ">") "<>")
9429 @result{} #f
9430 @end example
9431
9432 @item (at-least n <sre> ...)
9433 @itemx (>= n <sre> ...)
9434
9435 Matches the pattern(s) at least @code{n} times.
9436
9437 @example
9438 (regexp-search '(: "<" (>= 3 (~ #\>)) ">") "<table>")
9439 @result{} #<regexp-match>
9440 (regexp-search '(: "<" (>= 3 (~ #\>)) ">") "<pre>")
9441 @result{} #<regexp-match>
9442 (regexp-search '(: "<" (>= 3 (~ #\>)) ">") "<tr>")
9443 @result{} #f
9444 @end example
9445
9446 @item (exactly n <sre> ...)
9447 @itemx (= n <sre> ...)
9448
9449 Matches the pattern(s) exactly @code{n} times.
9450
9451 @example
9452 (regexp-search '(: "<" (= 4 (~ #\>)) ">") "<html>")
9453 @result{} #<regexp-match>
9454 (regexp-search '(: "<" (= 4 (~ #\>)) ">") "<table>")
9455 @result{} #f
9456 @end example
9457
9458 @item (repeated from to <sre> ...)
9459 @itemx (** from to <sre> ...)
9460
9461 Matches the pattern(s) at least @code{from} times and up to @code{to}
9462 times.
9463
9464 @example
9465 (regexp-search '(: (= 3 (** 1 3 numeric) ".") (** 1 3 numeric))
9466 "192.168.1.10")
9467 @result{} #<regexp-match>
9468 (regexp-search '(: (= 3 (** 1 3 numeric) ".") (** 1 3 numeric))
9469 "192.0168.1.10")
9470 @result{} #f
9471 @end example
9472 @end table
9473
9474 @subsubheading Submatch Patterns
9475 @table @code
9476 @item (submatch <sre> ...)
9477 @itemx ($ <sre> ...)
9478
9479 Captures the matched string. Each capture is numbered increasing from
9480 one (capture zero is the entire matched string). For nested captures,
9481 the numbering scheme is depth-first walk.
9482
9483 @item (submatch-named <name> <sre> ...)
9484 @itemx (-> <name> <sre> ...)
9485
9486 Captures the matched string and assigns a name to it in addition to a
9487 number. This is the equivalent of @code{(?<@i{name}>@i{re}@dots{})}
9488
9489 @item (backref <n-or-name>)
9490
9491 Matches a previously matched submatch. This is the same as
9492 RE syntax @code{\@i{n}} or @code{\k<@i{name}>}.
9493
9494 @c @item (if-backref <n> <then-sre> [<else-sre>])
9495
9496 @c Conditional matching. If the @code{<n>}-th capturing group has a
9497 @c match, @code{<then-sre>} pattern is tried; otherwise @code{<else-sre>}
9498 @c pattern is tried when provided.
9499
9500 @c This is Gauche extension and is the same as RE syntax
9501 @c @code{(?(@i{n})@i{then})} or @code{(?(@i{n})@i{then}|@i{else})}.
9502
9503 @end table
9504
9505 @subsubheading Character Sets
9506
9507 @table @code
9508 @item <char>
9509
9510 A character set contains a single character.
9511
9512 @example
9513 (regexp-matches '(* #\-) "---") @result{} #<regexp-match>
9514 (regexp-matches '(* #\-) "-_-") @result{} #f
9515 @end example
9516
9517 @item "<char>"
9518
9519 A character set contains a single character. This is technically
9520 ambiguous with SRE matching a literal string. However the end result
9521 of both syntaxes is the same.
9522
9523 @item <char-set>
9524
9525 A SRFI-14 character set.
9526
9527 Note that while currently there is no portable written representation
9528 of SRFI 14 character sets, you can use Gauche reader syntax
9529 @code{#[char-set-spec]}, @pxref{Character sets}.
9530
9531 @example
9532 (regexp-partition `(+ ,char-set:vowels) "vowels")
9533 @result{} ("v" "o" "w" "e" "ls")
9534 @end example
9535
9536 @item (char-set <string>)
9537 @itemx (<string>)
9538
9539 A character set contains the characters in the given string. This is
9540 the same as @code{`(char-set ,(string->char-set <string>))}.
9541
9542 @example
9543 (regexp-matches '(* ("aeiou")) "oui") @result{} #<regexp-match>
9544 (regexp-matches '(* ("aeiou")) "ouais") @result{} #f
9545 (regexp-matches '(* ("e\x0301")) "e\x0301") @result{} #<regexp-match>
9546 (regexp-matches '("e\x0301") "e\x0301") @result{} #f
9547 (regexp-matches '("e\x0301") "e") @result{} #<regexp-match>
9548 (regexp-matches '("e\x0301") "\x0301") @result{} #<regexp-match>
9549 (regexp-matches '("e\x0301") "\x00E9") @result{} #f
9550 @end example
9551
9552 @item (char-range <range-spec> ...)
9553 @itemx (/ <range-spec> ...)
9554
9555 A character set contains the characters within
9556 @code{<range-set>}. This is the same as RE syntax @code{[]}.
9557
9558 @example
9559 (regexp-matches '(* (/ "AZ09")) "R2D2") @result{} #<regexp-match>
9560 (regexp-matches '(* (/ "AZ09")) "C-3PO") @result{} #f
9561 @end example
9562
9563 @item (or <cset-sre> ...)
9564 @itemx (|\|| <cset-sre> ...)
9565
9566 A shorthand for @code{`(char-set ,(char-set-union <cset-sre>...))}.
9567
9568 @item (complement <cset-sre> ...)
9569 @itemx (~ <cset-sre> ...)
9570
9571 A shorthand for @code{`(char-set ,(char-set-complement <cset-sre>...))}.
9572
9573 @item (difference <cset-sre> ...)
9574 @itemx (- <cset-sre> ...)
9575
9576 A shorthand for @code{`(char-set ,(char-set-difference <cset-sre>...))}.
9577
9578 @example
9579 (regexp-matches '(* (- (/ "az") ("aeiou"))) "xyzzy")
9580 @result{} #<regexp-match>
9581 (regexp-matches '(* (- (/ "az") ("aeiou"))) "vowels")
9582 @result{} #f
9583 @end example
9584
9585 @item (and <cset-sre> ...)
9586 @itemx (& <cset-sre> ...)
9587
9588 A shorthand for @code{`(char-set ,(char-set-intersection <cset-sre>...))}.
9589
9590 @example
9591 (regexp-matches '(* (& (/ "az") (~ ("aeiou")))) "xyzzy")
9592 @result{} #<regexp-match>
9593 (regexp-matches '(* (& (/ "az") (~ ("aeiou")))) "vowels")
9594 @result{} #f
9595 @end example
9596
9597 @item (w/case <cset-sre>)
9598 @itemx (w/nocase <cset-sre>)
9599 @itemx (w/ascii <cset-sre>)
9600 @itemx (w/unicode <cset-sre>)
9601
9602 This is similar to the SRE equivalent, listed to indicate that they
9603 can also be applied on character sets.
9604
9605 @end table
9606
9607 @subsubheading Named Character Sets
9608
9609 Note that if @code{w/ascii} is in effect, these character sets will
9610 return the ASCII subset. Otherwise they return full Unicode ones.
9611
9612 @table @code
9613 @item any
9614
9615 Matches any character. This is the @code{.} in regular expression.
9616
9617 @item nonl
9618
9619 Matches any character other than @code{#\return} or @code{#\newline}.
9620
9621 @item ascii
9622
9623 A shorthand for @code{`(char-set ,char-set:ascii)}.
9624
9625 @item lower-case
9626 @itemx lower
9627
9628 A shorthand for @code{`(char-set ,char-set:lower-case)}.
9629
9630 @item upper-case
9631 @itemx upper
9632
9633 A shorthand for @code{`(char-set ,char-set:upper-case)}.
9634
9635 @item title-case
9636 @itemx title
9637
9638 A shorthand for @code{`(char-set ,char-set:title-case)}.
9639
9640 @item alphabetic
9641 @itemx alpha
9642
9643 A shorthand for @code{`(char-set ,char-set:letter)}.
9644
9645 @item numeric
9646 @itemx num
9647
9648 A shorthand for @code{`(char-set ,char-set:digit)}.
9649
9650 @item alphanumeric
9651 @itemx alphanum
9652 @itemx alnum
9653
9654 A shorthand for @code{`(char-set ,char-set:letter+digit)}.
9655
9656 @item punctuation
9657 @itemx punct
9658
9659 A shorthand for @code{`(char-set ,char-set:punctuation)}.
9660
9661 @item symbol
9662
9663 A shorthand for @code{`(char-set ,char-set:symbol)}.
9664
9665 @item graphic
9666 @itemx graph
9667
9668 A shorthand for @code{`(char-set ,char-set:graphic)}.
9669
9670 @example
9671 (or alphanumeric punctuation symbol)
9672 @end example
9673
9674
9675 @item whitespace
9676 @itemx white
9677 @itemx space
9678
9679 A shorthand for @code{`(char-set ,char-set:whitespace)}.
9680
9681 @item printing
9682 @itemx print
9683
9684 A shorthand for @code{`(char-set ,char-set:printing)}.
9685
9686 @item control
9687 @itemx cntrl
9688
9689 A character set contains ASCII characters with from 0 to 31.
9690
9691 @item hex-digit
9692 @itemx xdigit
9693
9694 A shorthand for @code{`(char-set ,char-set:hex-digit)}.
9695
9696 @end table
9697
9698 @subsubheading Boundary Assertions
9699
9700 @table @code
9701 @item bos
9702 @itemx eos
9703
9704 Matches the beginning of the string. If start/end parameters are
9705 specified, matches the start or end of the substring as specified.
9706
9707 @item bol
9708 @itemx eol
9709
9710 Matches the beginning or end of a line (or the string). For single
9711 line matching, this is the same as @code{bos} and @code{eos}. A line
9712 is interpreted the same way with @code{read-line}.
9713
9714 @item bow
9715 @itemx eow
9716
9717 Matches the beginning or the end of a word.
9718
9719
9720 @example
9721 (regexp-search '(: bow "foo") "foo") @result{} #<regexp-match>
9722 (regexp-search '(: bow "foo") "<foo>>") @result{} #<regexp-match>
9723 (regexp-search '(: bow "foo") "snafoo") @result{} #f
9724 (regexp-search '(: "foo" eow) "foo") @result{} #<regexp-match>
9725 (regexp-search '(: "foo" eow) "foo!") @result{} #<regexp-match>
9726 (regexp-search '(: "foo" eow) "foobar") @result{} #f
9727 @end example
9728
9729
9730 @item nwb
9731
9732 A shorthand for @code{(neg-look-ahead (or bow eow))}.
9733
9734 @item (word <sre> ...)
9735
9736 Matches the word boundary around the given SRE:
9737
9738 @example
9739 (: bow <sre> ... eow)
9740 @end example
9741
9742
9743 @item (word+ <cset-sre> ...)
9744
9745 Matches a single word composed of characters of the given characters
9746 sets:
9747
9748 @example
9749 (word (+ (and (or alphanumeric "_") (or cset-sre ...))))
9750 @end example
9751
9752
9753 @item word
9754
9755 A shorthand for @code{(word+ any)}.
9756
9757 @item bog
9758 @itemx eog
9759
9760 Matches the beginning or end of a graphame cluster.
9761 @xref{Unicode text segmentation}, for the low-level grapheme cluster
9762 segmentation.
9763
9764 @item grapheme
9765
9766 Matches a single grapheme cluster.
9767 @xref{Unicode text segmentation}, for the low-level grapheme cluster
9768 segmentation.
9769
9770 @end table
9771
9772 @subsubheading Non-Greedy Patterns
9773
9774 @table @code
9775
9776 @item (non-greedy-optional <sre> ...)
9777 @itemx (?? <sre> ...)
9778
9779 The non-greedy equivalent of @code{(optional <sre>...)}. This is the
9780 same as RE syntax @code{@i{re}??}
9781
9782 @item (non-greedy-zero-or-more< <sre> ...)
9783 @itemx (*? <sre> ...)
9784
9785 The non-greedy equivalent of @code{(zero-or-more <sre>...)}. This is
9786 the same as RE syntax @code{@i{re}*?}
9787
9788 @item (non-greedy-repeated <m> <n> <sre> ...)
9789 @itemx (**? <m> <n> <sre> ...)
9790
9791 The non-greedy equivalent of @code{(repeated <sre>...)}. This is the
9792 same as RE syntax @code{@i{re}@{@i{n},@i{m}@}?}
9793
9794 @item (atomic <sre> ...)
9795
9796 Atomic clustering. Once @code{<sre> ...} matches, the match is fixed;
9797 even if the following pattern fails, the engine won't backtrack to try
9798 the alternative match in @code{<sre> ...}. This is Gauche extension
9799 and is the same as RE syntax @code{(?>@i{pattern})}
9800
9801 @end table
9802
9803 @subsubheading Look Around Patterns
9804
9805 @table @code
9806 @item (look-ahead <sre> ...)
9807
9808 Zero-width look-ahead assertion. Asserts the sequence matches from the
9809 current position, without advancing the position. This is the same as
9810 RE syntax @code{(?=@i{pattern})}
9811
9812 @example
9813 (regexp-matches '(: "regular" (look-ahead " expression") " expression")
9814 "regular expression")
9815 @result{} #<regexp-match>
9816 (regexp-matches '(: "regular" (look-ahead " ") "expression")
9817 "regular expression")
9818 @result{} #f
9819 @end example
9820
9821
9822 @item (look-behind <sre> ...)
9823
9824 Zero-width look-behind assertion. Asserts the sequence matches behind
9825 the current position, without advancing the position. It is an error
9826 if the sequence does not have a fixed length. This is the same as RE
9827 syntax @code{(?<=@i{pattern})}
9828
9829 @item (neg-look-ahead <sre> ...)
9830
9831 Zero-width negative look-ahead assertion. This is the same as
9832 RE syntax @code{(?!@i{pattern})}
9833
9834 @item (neg-look-behind <sre> ...)
9835
9836 Zero-width negative look-behind assertion. This is the same as RE
9837 syntax @code{(?<!@i{pattern})}
9838
9839 @c @item (if-look-ahead <test-sre> <then-sre> [<else-sre>])
9840 @c @itemx (if-neg-look-ahead <test-sre> <then-sre> [<else-sre>])
9841 @c @itemx (if-look-behind <test-sre> <then-sre> [<else-sre>])
9842 @c @itemx (if-neg-look-behind <test-sre> <then-sre> [<else-sre>])
9843
9844 @c Conditional matching. If @code{<test-sre>} counts true,
9845 @c @code{<then-sre>} pattern is tried; otherwise @code{<else-sre>}
9846 @c pattern is tried when provided.
9847
9848 @c This is Gauche extension and the same as @code{(?(?=..)...)},
9849 @c @code{(?(?!..)...)}, @code{(?(?<=..)...)}, @code{(?(?<!..)...)}
9850 @c respectively.
9851
9852 @end table
9853
9854 @subheading Using regular expressions
9855
9856 @defun regexp @var{re}
9857 [R7RS regex]
9858 @c MOD scheme.regex
9859 Compiles the given Scheme Regular Expression into a @code{<regexp>}
9860 object. If @var{re} is already a regexp object, the object is
9861 returned as-is.
9862
9863 @end defun
9864
9865 @defmac rx @var{sre} @dots{}
9866 [R7RS regex]
9867 @c MOD scheme.regex
9868 A macro shorthand for @code{(regexp `(: @var{sre} ...))}.
9869 @end defmac
9870
9871 @defun regexp->sre @var{re}
9872 [R7RS regex]
9873 @c MOD scheme.regex
9874 Returns the SRE corresponding to the given given regexp object. Note
9875 that if the regexp object is not created from an SRE, it may contain
9876 features that cannot be expressed in SRE and cause an error.
9877 @end defun
9878
9879 @defun char-set->sre @var{char-set}
9880 [R7RS regex]
9881 @c MOD scheme.regex
9882 Returns the SRE of the given character set. Currently this is not
9883 optimized. If you convert @code{any} to SRE for example, you may get
9884 an SRE listing every single character.
9885 @end defun
9886
9887 @defun valid-sre? @var{obj}
9888 [R7RS regex]
9889 @c MOD scheme.regex
9890 Returns true iff @var{obj} can be safely passed to regexp.
9891 @end defun
9892
9893 @defun regexp? @var{obj}
9894 [R7RS regex]
9895 @c MOD scheme.regex
9896 Returns true iff @var{obj} is a regexp.
9897 @end defun
9898
9899 @defun regexp-matches @var{re} @var{str} [@var{start} [@var{end}]]
9900 [R7RS regex]
9901 @c MOD scheme.regex
9902 Returns an @code{<regexp-match>} object if re successfully matches the
9903 entire string @var{str} or optionally from @var{start} (inclusive) to
9904 @var{end} (exclusive), or @code{#f} is the match fails.
9905
9906 For convenience, @var{end} accepts @code{#f} and interprets it as the
9907 end of the string.
9908
9909 The regexp-match object will contain information needed to extract any
9910 submatches.
9911 @end defun
9912
9913 @defun regexp-matches? @var{re} @var{str} [@var{start} [@var{end}]]
9914 [R7RS regex]
9915 @c MOD scheme.regex
9916 Similar to @code{regexp-matches} but returns @code{#t} instead of a
9917 @code{<regexp-match>} object.
9918 @end defun
9919
9920 @defun regexp-search @var{re} @var{str} [@var{start} [@var{end}]]
9921 [R7RS regex]
9922 @c MOD scheme.regex
9923 Similar to @code{regexp-matches} except that @var{re} only has to
9924 match a substring in @var{str} instead.
9925 @end defun
9926
9927
9928 @defun regexp-fold @var{re} @var{kons} @var{knil} @var{str} [@var{finish} [@var{start} [@var{end}]]]
9929 [R7RS regex]
9930 @c MOD scheme.regex
9931 Calls the procedure @var{kons} for every match found in @var{str} with
9932 following four arguments:
9933
9934 @itemize
9935 @item
9936 The position of the end of the last matched string.
9937 @item
9938 The @code{<regexp-match>} object.
9939 @item
9940 The argument @var{str}.
9941 @item
9942 The result of the last @var{kons} call or @var{knil} if this is the
9943 first call.
9944 @end itemize
9945
9946 If @var{finish} is given, it is called after all matches with the same
9947 parameters as calling @var{kons} except that @code{#f} is passed
9948 instead of @code{<regexp-match>} and the result is returned. Otherwise
9949 the result of the last @var{kons} call is returned.
9950
9951 @example
9952 (regexp-fold 'word
9953 (lambda (i m str acc)
9954 (let ((s (regexp-match-submatch m 0)))
9955 (cond ((assoc s acc)
9956 => (lambda (x) (set-cdr! x (+ 1 (cdr x))) acc))
9957 (else `((,s . 1) ,@@acc)))))
9958 '()
9959 "to be or not to be")
9960 @result{} '(("not" . 1) ("or" . 1) ("be" . 2) ("to" . 2))
9961 @end example
9962 @end defun
9963
9964
9965 @defun regexp-extract @var{re} @var{str} [@var{start} [@var{end}]]
9966 [R7RS regex]
9967 @c MOD scheme.regex
9968 Returns a list of matched string or an empty list if no matches.
9969
9970 @example
9971 (regexp-extract '(+ numeric) "192.168.0.1")
9972 @result{} ("192" "168" "0" "1")
9973 @end example
9974 @end defun
9975
9976 @defun regexp-split @var{re} @var{str} [@var{start} [@var{end}]]
9977 [R7RS regex]
9978 @c MOD scheme.regex
9979 Returns a list of not matched substrings. This can be seen as the
9980 opposite of @code{regexp-extract} where the matched strings are
9981 removed instead of returned.
9982
9983 @example
9984 (regexp-split '(+ space) " fee fi fo\tfum\n")
9985 @result{} ("fee" "fi" "fo" "fum")
9986 (regexp-split '(",;") "a,,b,")
9987 @result{} ("a" "" "b" "")
9988 (regexp-split '(* numeric) "abc123def456ghi789")
9989 @result{} ("abc" "def" "ghi" "")
9990 @end example
9991 @end defun
9992
9993 @defun regexp-partition @var{re} @var{str} [@var{start} [@var{end}]]
9994 [R7RS regex]
9995 @c MOD scheme.regex
9996 Returns a list of all matched and not matched substrings. In other
9997 words it's the combination of @code{regexp-extract} and
9998 @code{regexp-split} where the boundary of matched strings are used to
9999 split the original string.
10000
10001 @example
10002 (regexp-partition '(+ (or space punct)) "")
10003 @result{} ("")
10004 (regexp-partition '(+ (or space punct)) "Hello, world!\n")
10005 @result{} ("Hello" ", " "world" "!\n")
10006 (regexp-partition '(+ (or space punct)) "¿Dónde Estás?")
10007 @result{} ("" "¿" "Dónde" " " "Estás" "?")
10008 (regexp-partition '(* numeric) "abc123def456ghi789")
10009 @result{} ("abc" "123" "def" "456" "ghi" "789")
10010 @end example
10011 @end defun
10012
10013 @defun regexp-replace @var{re} @var{str} @var{subst} [@var{start} [@var{end} [@var{count}]]]
10014 [R7RS regex]
10015 @c MOD scheme.regex
10016 Returns a new string where the first matched substring is replaced
10017 with @var{subst}. If @var{count} is specified, the @var{count}-th
10018 match will be replaced instead of the first one.
10019
10020 @var{subst} can be either a string (the replacement), an integer or a
10021 symbol to refer to the capture group that will be used as the
10022 replacement, or a list of those.
10023
10024 The special symbols @code{pre} and @code{post} use the substring to
10025 the left or right of the match as replacement, respectively.
10026
10027 @var{subst} could also be a procedure, which is
10028 called with the given match object and the result will be used as the
10029 replacement.
10030
10031 The optional parameters @var{start} and @var{end} essentially
10032 transform the substitution into this
10033
10034 @example
10035 (regexp-replace re (substring str start end) subst)
10036 @end example
10037
10038 except that @var{end} can take @code{#f} which is the same as
10039 @code{(string-length str)}.
10040
10041 @example
10042 (regexp-replace '(+ space) "one two three" "_")
10043 @result{} "one_two three"
10044 (regexp-replace '(+ space) "one two three" "_" 1 10)
10045 @result{} "ne_two th"
10046 (regexp-replace '(+ space) "one two three" "_" 0 #f 0)
10047 @result{} "one_two three"
10048 (regexp-replace '(+ space) "one two three" "_" 0 #f 1)
10049 @result{} "one two_three"
10050 (regexp-replace '(+ space) "one two three" "_" 0 #f 2)
10051 @result{} "one two three"
10052 @end example
10053
10054 Note that Gauche also has a builtin procedure of the same name, but
10055 works slightly differently, @pxref{Using regular expressions}.
10056 @end defun
10057
10058
10059 @defun regexp-replace-all @var{re} @var{str} @var{subst} [@var{start} [@var{end}]]
10060 [R7RS regex]
10061 @c MOD scheme.regex
10062 Returns a new string where all matches in @var{str} are replaced with
10063 @var{subst}. @var{subst} can also take a string, a number, a symbol or
10064 a procedure similar to @code{regexp-replace}.
10065
10066 @example
10067 (regexp-replace-all '(+ space) "one two three" "_")
10068 @result{} "one_two_three"
10069 @end example
10070
10071 Note that Gauche also has a builtin procedure of the same name, but
10072 works slightly differently, @pxref{Using regular expressions}.
10073 @end defun
10074
10075
10076 @defun regexp-match? @var{obj}
10077 [R7RS regex]
10078 @c MOD scheme.regex
10079 Returns true iff @var{obj} is a @code{<regexp-match>} object.
10080
10081 @example
10082 (regexp-match? (regexp-matches "x" "x")) @result{} #t
10083 (regexp-match? (regexp-matches "x" "y")) @result{} #f
10084 @end example
10085 @end defun
10086
10087
10088 @defun regexp-match-count @var{regexp-match}
10089 [R7RS regex]
10090 @c MOD scheme.regex
10091 Returns the number of matches in @var{match} except the implicit zero
10092 full match. This is just an alias of @code{rxmatch-num-matches} minus
10093 one.
10094
10095 @example
10096 (regexp-match-count (regexp-matches "x" "x")) @result{} 0
10097 (regexp-match-count (regexp-matches '($ "x") "x")) @result{} 1
10098 @end example
10099 @end defun
10100
10101 @defun regexp-match-submatch @var{regexp-match} @var{field}
10102 [R7RS regex]
10103 @c MOD scheme.regex
10104 This is an alias of @code{rxmatch-substring}
10105
10106 @example
10107 (regexp-match-submatch (regexp-search 'word "**foo**") 0) @result{} "foo"
10108 (regexp-match-submatch
10109 (regexp-search '(: "*" ($ word) "*") "**foo**") 0) @result{} "*foo*"
10110 (regexp-match-submatch
10111 (regexp-search '(: "*" ($ word) "*") "**foo**") 1) @result{} "foo"
10112 @end example
10113 @end defun
10114
10115 @defun regexp-match-submatch-start @var{regexp-match} @var{field}
10116 [R7RS regex]
10117 @c MOD scheme.regex
10118 This is an alias of @code{regexp-match-submatch-start}.
10119
10120 @example
10121 (regexp-match-submatch-start
10122 (regexp-search 'word "**foo**") 0) @result{} 2
10123 (regexp-match-submatch-start
10124 (regexp-search '(: "*" ($ word) "*") "**foo**") 0) @result{} 1
10125 (regexp-match-submatch-start
10126 (regexp-search '(: "*" ($ word) "*") "**foo**") 1) @result{} 2
10127 @end example
10128 @end defun
10129
10130 @defun regexp-match-submatch-end @var{regexp-match} @var{field}
10131 [R7RS regex]
10132 @c MOD scheme.regex
10133 This is an alias of @code{regexp-match-submatch-end}.
10134
10135 @example
10136 (regexp-match-submatch-end
10137 (regexp-search 'word "**foo**") 0) @result{} 5
10138 (regexp-match-submatch-end
10139 (regexp-search '(: "*" ($ word) "*") "**foo**") 0) @result{} 6
10140 (regexp-match-submatch-end
10141 (regexp-search '(: "*" ($ word) "*") "**foo**") 1) @result{} 5
10142 @end example
10143 @end defun
10144
10145 @defun regexp-match->list @var{regexp-match}
10146 [R7RS regex]
10147 @c MOD scheme.regex
10148 This is an alias of @code{rxmatch-substrings}
10149
10150 @example
10151 (regexp-match->list
10152 (regexp-search '(: ($ word) (+ (or space punct)) ($ word)) "cats & dogs"))
10153 @result{} '("cats & dogs" "cats" "dogs")
10154 @end example
10155 @end defun
10156
10157 @node R7RS mappings, R7RS integer division, R7RS regular expressions, R7RS large
10158 @subsection @code{scheme.mapping} - R7RS mappings
10159 @c NODE R7RSマップ, @code{scheme.mapping} - R7RSマッピング
10160
10161 @deftp {Module} scheme.mapping
10162 @deftpx {Module} scheme.mapping.hash
10163 @mdindex scheme.mapping
10164 @mdindex scheme.mapping.hash
10165 @c EN
10166 This module defines immutable mappings from keys to values.
10167 Originally called @code{srfi.146} and @code{srfi.146.hash}.
10168
10169 The @code{scheme.mapping} module provides @emph{mapping} objects,
10170 where keys have total order. The @code{scheme.mapping.hash} module
10171 provides @code{hashmap} objects, where keys can be hashed.
10172
10173 Currently, Gauche uses built-in @code{<tree-map>} for the mapping object
10174 (@pxref{Treemaps}),
10175 and built-in @code{<hash-table>} for the hashmap object (@pxref{Hashtables}).
10176 The actual implementation
10177 may be changed in future versions, so the user must not rely on the
10178 underlying implementations.
10179
10180 The caller must treat mappings and hashmaps as immutable object.
10181 The modules also provide ``linear update'' APIs, which is @emph{allowed}
10182 to mutate the mappings passed to the arguments, under assumption
10183 that the argument won't be used afterwards. The linear update APIs
10184 are marked with @code{!} at the end of the name.
10185 You should always use the returned value of the linear update APIs,
10186 for the side effect isn't guaranteed.
10187 @c JP
10188 このモジュールは、キーから値への変更不可なマッピングを提供します。
10189 元は@code{srfi.146}および@code{srfi.146.hash}として規定されました。
10190
10191 @code{scheme.mapping}モジュールは、キー間に全順序を定義できる@emph{mapping}オブジェクトを、
10192 @code{scheme.mapping.hash}モジュールは、ハッシュ可能なキーを使う@emph{hashmap}オブジェクト
10193 を提供します。
10194
10195 今のところ、Gaucheはmappingとして組み込みの@code{<tree-map>}を (@ref{Treemaps})、
10196 hashmapとして組み込みの@code{<hash-table>}を使っています。
10197 実際の実装は将来変わるかもしれないので、このモジュールを使う場合は具体的なデータ構造を
10198 仮定しないようにしてください。
10199
10200 呼び出し側では、mappingやhashmapは変更不可なオブジェクトとして扱わなければなりません。
10201 このモジュールでは「線形更新」版のAPIも提供されています。これは、
10202 呼び出し側で引数に渡すmappingやhashmapに二度とアクセスしない、という契約のもとに、
10203 渡されたmappingやhashmapを再利用するかもしれないインタフェースです。
10204 線形更新版のAPIは名前の末尾に@code{!}がつきます。
10205 ですが副作用は保証されていないので、線形更新版でも常に戻り値を利用する必要があります。
10206 @c COMMON
10207 @end deftp
10208
10209 @menu
10210 * Mappings::
10211 * Hashmaps::
10212 @end menu
10213
10214
10215 @node Mappings, Hashmaps, R7RS mappings, R7RS mappings
10216 @subsubsection Mappings
10217 @c NODE Mappings
10218
10219 @deftp {Class} <mapping>
10220 @clindex mapping
10221 @c MOD scheme.mapping
10222 @c EN
10223 The class for the mappings.
10224 On Gauche, this is just an alias of @code{<tree-map>}.
10225 @c JP
10226 mappingのクラス。Gaucheでは単に@code{<tree-map>}の別名です。
10227 @c COMMON
10228 @end deftp
10229
10230 @c EN
10231 @subsubheading Constructors
10232 @c JP
10233 @subsubheading コンストラクタ
10234 @c COMMON
10235
10236 @defun mapping comparator key value @dots{}
10237 [R7RS mapping]
10238 @c MOD scheme.mapping
10239 @c EN
10240 Creates a new mapping with the given @var{comparator},
10241 whose initial content is
10242 provided by @var{key} @var{value} @dots{}.
10243 @c JP
10244 @var{comparator}をキーの比較に用いる新たなmappingを作って返します。
10245 @var{key} @var{value} @dots{} がキー-値の組の初期値となります。
10246 @c COMMON
10247
10248 @c EN
10249 The @var{comparator} argument must be a comparator,
10250 with comparison/ordering procedure
10251 (@pxref{Basic comparators}).
10252 @c JP
10253 @var{comparator}は、順序手続きか比較手続きを持つ比較器でなければなりません
10254 (@ref{Basic comparators}参照)。
10255 @c COMMON
10256
10257 @c EN
10258 The @var{key} @var{value} @dots{} arguments must be
10259 even length, alternating keys and values.
10260 @c JP
10261 残りの引数 @var{key} @var{value} @dots{} は偶数個でなければならず、
10262 引数はキーと値を交互に並べたものです。
10263 @c COMMON
10264
10265 @example
10266 (define m (mapping default-comparator 'a 1 'b 2))
10267
10268 (mapping-ref m 'a) @result{} 1
10269 (mapping-ref m 'b) @result{} 2
10270 @end example
10271 @end defun
10272
10273 @defun mapping-unfold p f g seed comparator
10274 [R7RS mapping]
10275 @c MOD scheme.mapping
10276 @c EN
10277 Creates a new mapping, whose content is populated by
10278 three procedures, @var{p}, @var{f} and @var{g}, and
10279 a seed value @var{seed}, as follows.
10280 @c JP
10281 新たなmappingを作って返します。作られるmappingの内容は、
10282 3つの手続き@var{p}、@var{f}、@var{g}と初期シード値@var{seed}で決まります。
10283 @c COMMON
10284
10285 @c EN
10286 In each iteration, we have a current seed value, whose initial
10287 value is @var{seed}.
10288 @c JP
10289 繰り返しごとに、「現在のシード値」が参照されます。シード値の初期値は@var{seed}です。
10290 @c COMMON
10291
10292 @c EN
10293 First, @var{p}, a stop predicate, is applied to the current
10294 seed value. If it returns true, we stop iteration and returns
10295 the new mapping.
10296 @c JP
10297 まず、現在のシード値に@var{p} (停止述語)が適用されます。それが真の値を返したら、
10298 繰り返しは終了し、それまでに生成されたエントリを持つmappingが返されます。
10299 @c COMMON
10300
10301 @c EN
10302 Next, @var{f} is applied to the current seed value. It must
10303 return two values. The first one is for a key and the second
10304 one for the value. We add this pair to the mapping.
10305 @c JP
10306 次に、@var{f}が現在のシード値に適用されます。これは二つの値を返さなければなりません。
10307 最初の戻り値がキー、次の戻り値が値と解釈されます。この組がmappingに足されます。
10308 @c COMMON
10309
10310 @c EN
10311 Then, @var{g} is applied to the current seed value. The result
10312 becomes the seed value of the next iteration. And we iterate.
10313 @c JP
10314 それから、@var{g}が現在のシード値に適用されます。その戻り値が次の繰り返しでの
10315 シード値となります。これを繰り返します。
10316 @c COMMON
10317
10318 @c EN
10319 The following example creates a mapping that maps ASCII characters
10320 to their character codes:
10321 @c JP
10322 次の例は、ASCII文字をASCIIコードにマップするmappingを返します。
10323 @c COMMON
10324
10325 @example
10326 (mapping-unfold (cut >= <> 128)
10327 (^c (values (integer->char c) c))
10328 (cut + <> 1)
10329 0
10330 default-comparator)
10331 @end example
10332 @end defun
10333
10334 @defun mapping/ordered comparator key value @dots{}
10335 [R7RS mapping]
10336 @c MOD scheme.mapping
10337 @c EN
10338 A mapping constructor similar to @code{mapping},
10339 but keys are given in the ascending order
10340 w.r.t. the comparator. An implementation may use more efficient algorithm
10341 than @code{mapping}. In Gauche, this is the same as @code{mapping}
10342 at this moment.
10343 @c JP
10344 @code{mapping}と同様のコンストラクタですが、
10345 キーが@var{comparator}の基準で昇順になっていることを呼び出し側が保証します。
10346 実装によってはその事実を利用して@code{mapping}よりも効率的なアルゴリズムを
10347 使うかもしれません。Gaucheeでゃこれは今のところ@code{mapping}と同じです。
10348 @c COMMON
10349 @end defun
10350
10351 @defun mapping-unfold/ordered p f g seed comparator
10352 [R7RS mapping]
10353 @c MOD scheme.mapping
10354 @c EN
10355 A mapping constructor similar to @code{mapping-unfold},
10356 but keys are generated in the ascending order
10357 w.r.t. the comparator. An implementation may use more efficient algorithm
10358 than @code{mapping-unfold}.
10359 In Gauche, this is the same as @code{mapping-unfold} at this moment.
10360 @c JP
10361 @code{mapping-unfold}と同様のコンストラクタですが、
10362 キーが@var{comparator}の基準で昇順になっていることを呼び出し側が保証します。
10363 実装によってはその事実を利用して@code{mapping-unfold}よりも効率的なアルゴリズムを
10364 使うかもしれません。Gaucheeでゃこれは今のところ@code{mapping-unfold}と同じです。
10365 @c COMMON
10366 @end defun
10367
10368 @c EN
10369 @subsubheading Predicates
10370 @c JP
10371 @subsubheading 述語
10372 @c COMMON
10373
10374 @defun mapping? obj
10375 [R7RS mapping]
10376 @c MOD scheme.mapping
10377 @c EN
10378 Returns @code{#t} if @var{obj} is a mapping object, @code{#f} otherwise.
10379 @c JP
10380 @var{obj}がマッピングなら@code{#t}を、そうでなければ@code{#f}を返します。
10381 @c COMMON
10382 @end defun
10383
10384 @defun mapping-empty? m
10385 [R7RS mapping]
10386 @c MOD scheme.mapping
10387 @c EN
10388 The argument must be a mapping.
10389 Returns @code{#t} if @var{m} is empty, @code{#f} otherwise.
10390 In Gauche, this is same as @code{tree-map-empty?}
10391 (@pxref{Treemaps}).
10392 @c JP
10393 引数はマッピングでなければなりません。
10394 @var{m}が空なら@code{#t}を、そうでなければ@code{#f}を返します。
10395 Gaucheではこれは@code{tree-map-empty?}と同じです
10396 (@ref{Treemaps}参照)。
10397 @c COMMON
10398 @end defun
10399
10400 @defun mapping-contains? m key
10401 [R7RS mapping]
10402 @c MOD scheme.mapping
10403 @c EN
10404 @var{M} must be a mapping.
10405 Returns @code{#t} if @var{m} has an entry with @var{key},
10406 @code{#f} otherwise.
10407 In Gauche, this is same as @code{tree-map-exists?}
10408 (@pxref{Treemaps}).
10409 @c JP
10410 @var{m}はマッピングでなければなりません。
10411 @var{m}中に@var{key}をキーとするエントリをがあれば@code{#t}を、
10412 そうでなければ@code{#f}を返します。
10413 Gaucheではこれは@code{tree-map-exists?}と同じです
10414 (@ref{Treemaps}参照)。
10415 @c COMMON
10416 @end defun
10417
10418 @defun mapping-disjoint? m1 m2
10419 [R7RS mapping]
10420 @c MOD scheme.mapping
10421 @c EN
10422 Returns @code{#t} iff two mappings @var{m1} and @var{m2} have no keys
10423 in common, @code{#f} otherwise.
10424 @c JP
10425 二つのマッピング@var{m1}と@var{m2}の間に共通するキーがなければ@code{#t}を、
10426 そうでなければ@code{#f}を返します。
10427 @c COMMON
10428 @end defun
10429
10430 @c EN
10431 @subsubheading Accessors
10432 @c JP
10433 @subsubheading アクセサ
10434 @c COMMON
10435
10436 @defun mapping-ref m key :optional failure success
10437 [R7RS mapping]
10438 @c MOD scheme.mapping
10439 @c EN
10440 Get the value from a mapping @var{m} associated with @var{key},
10441 and calls @var{success} on the value, and returns its result.
10442 If @var{m} doesn't have @var{key}, @var{failure} is invoked with no
10443 arguments and its result is returned.
10444 Both @var{success} and @var{failure} is called in tail context.
10445 @c JP
10446 マッピング@var{m}からキー@var{key}を持つエントリを探し、その値が見つかれば
10447 それを引数として@var{success}を呼び、その結果を返します。
10448 @var{key}を持つエントリが見つからなかった場合は@var{failure}が引数無しで呼ばれ、
10449 その結果が返ります。
10450 @var{success}と@var{failure}はどちらも末尾位置で呼ばれます。
10451 @c COMMON
10452
10453 @c EN
10454 When @var{failure} is omitted and @var{key} is not found, an error
10455 is signaled. When @var{success} is omitted, @code{identity} is
10456 assumed.
10457 @c JP
10458 @var{failure}が省略された場合、キーが見つからなければエラーが投げられます。
10459 @var{success}が省略された場合は@code{identity}が使われます。
10460 @c COMMON
10461 @end defun
10462
10463 @defun mapping-ref/default m key default
10464 [R7RS mapping]
10465 @c MOD scheme.mapping
10466 @c EN
10467 Returns the value associated to @var{key} from a mapping @var{m}.
10468 If @var{m} doesn't have @var{key}, @var{default} is returned.
10469 @c JP
10470 マッピング@var{m}からキー@var{key}を持つエントリを探し、見つかればその値を、
10471 見つからなければ@var{default}を返します。
10472 @c COMMON
10473 @end defun
10474
10475 @defun mapping-key-comparator m
10476 [R7RS mapping]
10477 @c MOD scheme.mapping
10478 @c EN
10479 Returns a comparator used to compare keys in a mapping @var{m}.
10480 @xref{Basic comparators}, for the details of comparators.
10481 @c JP
10482 マッピング@var{m}がキーの比較に使う比較器を返します。
10483 比較器については@ref{Basic comparators}を参照してください。
10484 @c COMMON
10485 @end defun
10486
10487 @c EN
10488 @subsubheading Updaters
10489 @c JP
10490 @subsubheading 更新
10491 @c COMMON
10492
10493 @c EN
10494 Note that the basic premise of mappings srfi is to treat mappings
10495 as immutable. Each updating operation comes with a purely functional
10496 version (without bang) and a linear update version (with bang), but
10497 the linear update version may not require to destructively modify
10498 the passed mapping; it's merely a hint that it may reuse the
10499 argument for the efficiency. You always need to use the returned
10500 mapping as the result of update. If you use linear update versions,
10501 you shouldn't use the passed mapping afterwards, for there's no guarantee
10502 how the state of the passed mapping is.
10503 @c JP
10504 マッピングSRFIの前提は変更不可なデータ構造です。
10505 更新操作には、純粋に関数的なもの(エクスクラメーションマークがついていないもの)と、
10506 線形更新版(エクスクラメーションマークがついているもの)がありますが、
10507 線形更新版も必ずしも引数のマッピングを破壊的変更するとは限りません。
10508 線形更新版を使うことは、呼び出し側で引数に渡したマッピングを二度と使わない(から再利用してよい)
10509 ということを伝えるヒントにすぎません。
10510 線形更新版を使うときでも、常に戻り値を使うようにしてください。
10511 線形更新版に渡したマッピングは、その後どういう状態になっているか一切の保証がないので、
10512 そのマッピングを使わないようにしてください。
10513 @c COMMON
10514
10515 @defun mapping-adjoin m arg @dots{}
10516 @defunx mapping-adjoin! m arg @dots{}
10517 [R7RS mapping]
10518 @c MOD scheme.mapping
10519 @c EN
10520 The @var{arg} @dots{} are alternating between key and value. Returns
10521 a mapping that contains all the entries in @var{m} plus given
10522 keys and values, with the same comparator as @var{m}.
10523 Linear update version @code{mapping-adjoin!} may destructively modify
10524 @var{m} to create the return value, while @code{mapping-adjoin}
10525 creates a new mapping.
10526 @c JP
10527 @var{arg} @dots{}はキーと値が交互に並んだリストです。マッピング@var{m}に、
10528 @var{arg} @dots{}で与えられるキー-値のエントリを追加したマッピングを返します。
10529 線形更新版の@code{mapping-adjoin!}は戻り値を作るのに@var{m}を再利用するかもしれません。
10530 @var{mapping-adjoin}は常に新たなマッピングを作って返します。
10531 @c COMMON
10532
10533 @c EN
10534 Arguments are processed in order.
10535 If there's already an entry in @var{m} with the same key as given to
10536 @var{arg}, the original entry remains.
10537 See @code{mapping-set} below if you want to supersede the original entry.
10538 @c JP
10539 引数は現れる順番に処理されます。もし与えられたキーを持つエントリが@var{m}に既にあったなら、
10540 元のエントリが残されます。与えたキーの方を優先させたい場合は
10541 下の@code{mapping-set}を見てください。
10542 @c COMMON
10543
10544 @example
10545 (mapping-adjoin (mapping default-comparator 'a 1 'b 2) 'c 3 'a 4 'c 5)
10546 @result{} @r{mapping with @t{a} @arrow{} 1, @t{b} @arrow{} 2, @t{c} @arrow{} 3}
10547 @end example
10548 @end defun
10549
10550 @defun mapping-set m arg @dots{}
10551 @defunx mapping-set! m arg @dots{}
10552 [R7RS mapping]
10553 @c MOD scheme.mapping
10554 @c EN
10555 The @var{arg} @dots{} are alternating between key and value. Returns
10556 a mapping that contains all the entries in @var{m} plus given
10557 keys and values, with the same comparator as @var{m}.
10558 Linear update version @code{mapping-set!} may destructively modify
10559 @var{m} to create the return value, while @code{mapping-set}
10560 creates a new mapping.
10561 @c JP
10562 @var{arg} @dots{}はキーと値が交互に並んだリストです。マッピング@var{m}に、
10563 @var{arg} @dots{}で与えられるキー-値のエントリを追加したマッピングを返します。
10564 線形更新版の@code{mapping-set!}は戻り値を作るのに@var{m}を再利用するかもしれません。
10565 @var{mapping-set}は常に新たなマッピングを作って返します。
10566 @c COMMON
10567
10568 @c EN
10569 Arguments are processed in order.
10570 If there's already an entry in @var{m} with the same key as given to
10571 @var{arg}, the new key-value pair supersedes the old one.
10572 See @code{mapping-adjoin} above if you want to preserve the old entry.
10573 @c JP
10574 引数は現れる順番に処理されます。もし与えられたキーを持つエントリが@var{m}に既にあったなら、
10575 新たに与えた値で置き換えられます。元の値の方を優先させたい場合は
10576 上の@code{mapping-adjoin}を見てください。
10577 @c COMMON
10578
10579 @example
10580 (mapping-set (mapping default-comparator 'a 1 'b 2) 'c 3 'a 4 'c 5)
10581 @result{} @r{mapping with @t{a} @arrow{} 4, @t{b} @arrow{} 2, @t{c} @arrow{} 5}
10582 @end example
10583 @end defun
10584
10585 @defun mapping-replace m key value
10586 @defunx mapping-replace! m key value
10587 [R7RS mapping]
10588 @c MOD scheme.mapping
10589 @c EN
10590 If the mapping @var{m} has an entry of @var{key}, return a mapping
10591 with the value of the entry replaced for @var{value}. If @var{m} doesn't
10592 have an entry with @var{key}, @var{m} is returned unchanged.
10593
10594 Linear update version @code{mapping-replace!} may destructively modify
10595 @var{m} to produce the return value, while @code{mapping-replace}
10596 creates a new mapping.
10597 @c JP
10598 マッピング@var{m}に@var{key}を持つエントリがある場合、その値を@var{value}に
10599 置き換えたマッピングを返します。@var{m}が@var{key}を持っていなかったら@var{m}を
10600 そのまま返します。
10601
10602 線形更新版の@code{mapping-replace!}は戻り値を作るのに@var{m}を再利用するかもしれません。
10603 @var{mapping-replace}は常に新たなマッピングを作って返します。
10604 @c COMMON
10605
10606 @example
10607 (mapping-replace (mapping default-comparator 'a 1 'b 2) 'a 3)
10608 @result{} @r{mapping with @t{a} @arrow{} 3, @t{b} @arrow{} 2}
10609
10610 (mapping-replace (mapping default-comparator 'a 1 'b 2) 'c 3)
10611 @result{} @r{mapping with @t{a} @arrow{} 1, @t{b} @arrow{} 2}
10612 @end example
10613 @end defun
10614
10615
10616 @defun mapping-delete m key @dots{}
10617 @defunx mapping-delete! m key @dots{}
10618 [R7RS mapping]
10619 @c MOD scheme.mapping
10620 @c EN
10621 Returns a mapping that is the same as @var{m} except its entries with
10622 any of the given @var{key} @dots{} being removed. Keys that are
10623 not in @var{m} are ignored.
10624
10625 Linear update version @code{mapping-delete!} may destructively modify
10626 @var{m} to produce the return value, while @code{mapping-delete}
10627 creates a new mapping.
10628 @c JP
10629 マッピング@var{m}から、@var{key} @dots{}のいずれかのキーを持つエントリをすべて
10630 取り除いたマッピングを返します。@var{m}の中に無いキーは無視されます。
10631
10632 線形更新版の@code{mapping-delete!}は戻り値を作るのに@var{m}を再利用するかもしれません。
10633 @var{mapping-delete}は常に新たなマッピングを作って返します。
10634 @c COMMON
10635 @end defun
10636
10637 @defun mapping-delete-all m key-list
10638 @defunx mapping-delete-all! m key-list
10639 [R7RS mapping]
10640 @c MOD scheme.mapping
10641 @c EN
10642 Returns a mapping that is the same as @var{m} except its entries with
10643 any of the given keys in @var{key-list} being removed. Keys that are
10644 not in @var{m} are ignored.
10645
10646 Linear update version @code{mapping-delete-all!} may destructively modify
10647 @var{m} to produce the return value, while @code{mapping-delete-all}
10648 creates a new mapping.
10649 @c JP
10650 マッピング@var{m}から、@var{key-list}に含まれるキーを持つエントリを
10651 取り除いたマッピングを返します。@var{m}の中に無いキーは無視されます。
10652
10653 線形更新版の@code{mapping-delete-all!}は戻り値を作るのに@var{m}を再利用するかもしれません。
10654 @var{mapping-delete-all}は常に新たなマッピングを作って返します。
10655 @c COMMON
10656 @end defun
10657
10658
10659 @defun mapping-intern m key make-value
10660 @defunx mapping-intern! m key make-value
10661 [R7RS mapping]
10662 @c MOD scheme.mapping
10663 @c EN
10664 Looks up @var{key} in the mapping @var{m}, and returns two values,
10665 @var{m} and the associated value. If @var{m} does not contain an entry
10666 with @var{key}, a thunk @var{make-value} is invoked, and creates a new
10667 mapping that contains all entries in @var{m} plus a new entry with
10668 @var{key} and the return value of @var{make-value}, then returns the
10669 new mapping and the return value of @var{make-value}.
10670 @c JP
10671 マッピング@var{m}からキー@var{key}を持つエントリを探します。
10672 見つかった場合は、@var{m}自身とエントリの値を返します。
10673 見つからなかった場合、サンク@var{make-value}が引数無しで呼ばれ、
10674 @var{key}をキー、@var{make-value}の結果を値とするエントリを@var{m}に追加した
10675 マッピングと、@var{make-value}の結果が返されます。
10676 @c COMMON
10677
10678 @c EN
10679 Linear update version @code{mapping-intern!} may destructively modify
10680 @var{m} to produce the return value, while @code{mapping-intern}
10681 creates a new mapping.
10682 @c JP
10683 線形更新版の@code{mapping-intern!}は戻り値を作るのに@var{m}を再利用するかもしれません。
10684 @var{mapping-intern}は常に新たなマッピングを作って返します。
10685 @c COMMON
10686
10687 @example
10688 (mapping-intern (mapping default-comparator 'a 1) 'b (^[] 2))
10689 @result{}
10690 @r{mapping with @t{a} @arrow{} 1, @t{b} @arrow{} 2}
10691 @r{and}
10692 2
10693
10694 (mapping-intern (mapping default-comparator 'a 1) 'a (^[] 2))
10695 @result{}
10696 @r{mapping with @t{a} @arrow{} 1}
10697 @r{and}
10698 1
10699 @end example
10700 @end defun
10701
10702 @defun mapping-update m key updater :optional failure success
10703 @defunx mapping-update! m key updater :optional failure success
10704 [R7RS mapping]
10705 @c MOD scheme.mapping
10706 Semantically equivalent to this:
10707
10708 @example
10709 (mapping-set @var{m} @var{var}
10710 (@var{updater} (mapping-ref @var{m} @var{key} @var{failure} @var{success})))
10711 @end example
10712
10713 The @var{failure} and @var{success} optional arguments are procedures
10714 with zero and one arguments, respectively. When omitted,
10715 @var{failure} defaults to a thunk that raises an error,
10716 and @var{success} defaults to @code{identity}.
10717
10718 First, @var{key} is looked up in @var{m}. If an entry is found,
10719 the associated value is passed to @var{success}; otherwise,
10720 @var{failure} is called with no arguments. Either way, let the returned
10721 value be @var{v0}.
10722
10723 Then, @var{v0} is passed to @var{updater}. Let its result be @var{v1}.
10724
10725 Finally, a mapping with the same entries as @var{m} except the value of
10726 @var{key} is altered to @var{v1} is returned.
10727
10728 Linear update version @code{mapping-update!} may destructively modify
10729 @var{m} to produce the return value, while @code{mapping-update}
10730 creates a new mapping.
10731
10732 @example
10733 (mapping-update (mapping default-comparator 'a 1)
10734 'a (pa$ + 1))
10735 @result{} @r{mapping with @t{a} @arrow{} 2}
10736
10737 (mapping-update (mapping default-comparator)
10738 'a (pa$ + 1) (^[] 0))
10739 @result{} @r{mapping with @t{a} @arrow{} 1}
10740 @end example
10741 @end defun
10742
10743 @defun mapping-update/default m key updater default
10744 @defunx mapping-update!/default m key updater default
10745 [R7RS mapping]
10746 @c MOD scheme.mapping
10747 Search mapping @var{m} for a key @var{key}. If the entry is found,
10748 call @var{updater} with its value, and returns a mapping
10749 in which the entry with @var{key} having the result of @var{updater}
10750 as a value. If the entry with @var{key} is not found in @var{m},
10751 call @var{updater} with @var{default}, and returns a mapping
10752 in which the entry with @var{key} and the result of @var{updater}
10753 is added. Semantically, it is the same as the following:
10754
10755 @example
10756 (mapping-set m key (updater (mapping-ref/default m key default)))
10757 @end example
10758
10759 Linear update version @code{mapping-update/default!} may destructively modify
10760 @var{m} to produce the return value, while @code{mapping-update/default}
10761 creates a new mapping.
10762 @end defun
10763
10764 @defun mapping-pop m :optional failure
10765 @defunx mapping-pop! m :optional failure
10766 [R7RS mapping]
10767 @c MOD scheme.mapping
10768 Choose the least key from a mapping @var{m} and returns
10769 three values, (1) a mapping that has the same content as @var{m}
10770 except the entry with the chosen key, (2) the chosen key,
10771 and (3) the value associated with the chosen key.
10772 If @var{m} is empty, @var{failure} is called with no arguments
10773 in the tail context and its result(s) are returned.
10774 If @var{failure} is omitted, an error is signalled when @var{m} is empty.
10775
10776 Linear update version @code{mapping-update/pop!} may destructively modify
10777 @var{m} to produce the return value, while @code{mapping-update/pop}
10778 creates a new mapping.
10779 @end defun
10780
10781 @defun mapping-search m k failure success
10782 @defunx mapping-search! m k failure success
10783 [R7RS mapping]
10784 @c MOD scheme.mapping
10785 Search the key @var{k} from the mapping @var{m}. If the entry is
10786 found, the @var{success} procedure is tail-called as
10787 @code{(success @var{key} @var{value} @var{update} @var{remove})},
10788 where @var{key} and @var{value} are from the found entry, and
10789 @var{update} and @var{remove} are procedures as explained below.
10790 If no entry is found, the @var{failure} procedure is tail-called
10791 as @code{(failure @var{insert} @var{ignore})}, where
10792 the arguments are procedures as explained below.
10793
10794 The @var{success} procedure is expected to tail-call either @var{update}
10795 or @var{remove} procedures:
10796
10797 The @var{update} procedure passed to @var{success} takes
10798 takes three arguments, @var{new-key}, @var{new-value}, and @var{retval}.
10799 It creates a mapping which is the same as @var{m} except the original
10800 key's entry is removed, but a new entry with @var{new-key} and
10801 @var{new-value} is adjoined.
10802 Then it returns the new mapping and @var{retval}.
10803
10804 The @var{remove} procedure assed to @var{success} takes
10805 one argument, @var{retval}, and it creates a mapping which is
10806 the same as @var{m} except the searched entry is removed,
10807 and returns the new mapping and @var{retval}.
10808
10809 The @var{failure} procedure is expected to tail-call either
10810 @var{insert} or @var{ignore} procedures:
10811
10812 The @var{insert} procedure passed to @var{failure} takes
10813 two arguments, @var{value} and @var{retval}. It creates
10814 a new mapping that has all the entires of @var{m} and
10815 a new entry with @var{k} and @var{value}, and returns
10816 the new mapping and @var{retval}.
10817
10818 The @var{ignore} procedure takes one argument, @var{retval},
10819 and returns the original mapping @var{m} and @var{retval}.
10820
10821 Linear update version @code{mapping-search!} may destructively modify
10822 @var{m} to produce the return value, while @code{mapping-search}
10823 creates a new mapping.
10824 @end defun
10825
10826 @c EN
10827 @subsubheading The whole mapping
10828 @c JP
10829 @subsubheading マッピング全体
10830 @c COMMON
10831
10832 @defun mapping-size m
10833 [R7RS mapping]
10834 @c MOD scheme.mapping
10835 Returns the number of entries in the mapping @var{m}.
10836 @end defun
10837
10838 @defun mapping-find pred m failure
10839 [R7RS mapping]
10840 @c MOD scheme.mapping
10841 For each key in the mapping @var{m} in increasing order,
10842 calls @var{pred} with the key and the associated value.
10843 If @var{pred} returns a true value, immediately returns that key and the value
10844 as two values. If no entry satisfy @var{pred}, a thunk
10845 @var{failure} is tail-called.
10846 @end defun
10847
10848 @defun mapping-count pred m
10849 [R7RS mapping]
10850 @c MOD scheme.mapping
10851 For each key in the mapping @var{m} in increasing order,
10852 calls @var{pred} with the key and the associated value.
10853 Returns the number of times when @var{pred} returned a true value.
10854 @end defun
10855
10856 @defun mapping-any? pred m
10857 [R7RS mapping]
10858 @c MOD scheme.mapping
10859 Returns @code{#t} if any entry of the mapping @var{m}
10860 of which @var{pred} returns a true value with its key and its value.
10861 If no entries satisfy @var{pred}, @code{#f} is returned.
10862 @end defun
10863
10864 @defun mapping-every? pred m
10865 [R7RS mapping]
10866 @c MOD scheme.mapping
10867 Returns @code{#t} if every entry of the mapping @var{m}
10868 of which @var{pred} returns a true value with its key and its value.
10869 If any entry does not satisfy @var{pred}, @code{#f} is returned.
10870 @end defun
10871
10872 @defun mapping-keys m
10873 @defunx mapping-values m
10874 [R7RS mapping]
10875 @c MOD scheme.mapping
10876 Returns a fresh list of keys and values of the mapping @var{m},
10877 in the increasing order of keys.
10878 @end defun
10879
10880 @defun mapping-entries m
10881 [R7RS mapping]
10882 @c MOD scheme.mapping
10883 Returns two values, a fresh list of keys and a fresh list of values in the
10884 mapping @var{m}, in the increasing order of keys.
10885 @end defun
10886
10887 @c EN
10888 @subsubheading Mapping and folding
10889 @c JP
10890 @subsubheading マップと畳み込み
10891 @c COMMON
10892
10893 @defun mapping-map proc comparator m
10894 [R7RS mapping]
10895 @c MOD scheme.mapping
10896 The @var{proc} argument is a procedure that takes two arguments,
10897 a key and a value, and returns two values, a new key and a new value.
10898 This procedure applies @var{proc} on each key-value in a mapping @var{m},
10899 and returns a new mapping that uses @var{comparator} for its key
10900 comparator and contains all the new keys and values returned by @var{proc}.
10901
10902 If @var{proc} returns duplicate keys with regard to @var{comparator},
10903 one of the key-value associations enters the result mapping.
10904 There's no rule for which one is chosen.
10905 @end defun
10906
10907 @defun mapping-map/monotone proc comparator m
10908 @defunx mapping-map/monotone! proc comparator m
10909 [R7RS mapping]
10910 @c MOD scheme.mapping
10911 Similar to @var{mapping-map}, except that the caller guarantees
10912 the order of keys returned from @var{proc} w.r.t. @var{comparator}
10913 preserves the order of keys in @var{m}. The resulting new mapping
10914 is the same, but the impementation may take advantage of the knowledge
10915 for efficiency. In the current Gauche,
10916 @code{mapping-map/monotone} is the same as @code{mapping-map}.
10917
10918 The linear update version @code{mapping-map/monotone!} may reuse
10919 @var{m} to produce the output.
10920 @end defun
10921
10922 @defun mapping-for-each proc m
10923 [R7RS mapping]
10924 @c MOD scheme.mapping
10925 Calls @var{proc} on each entry in the mapping @var{m}, in increasing
10926 order of the keys. The entry's key and value are passed as arguments
10927 to @var{proc}. Result of @var{proc} is discarded.
10928 Returns an unspecified value.
10929 @end defun
10930
10931 @defun mapping-fold kons knil m
10932 [R7RS mapping]
10933 @c MOD scheme.mapping
10934 Calls @var{proc} on each entry in the mapping @var{m}, in increasing
10935 order of the keys. A procedure @var{kons} takes three arguments:
10936 the entry's key, the entry's value, and an accumlated value, whose
10937 initial value is @var{knil} and the previous result of @var{kons}
10938 subsequently. Returns the last result of @var{kons}.
10939 @end defun
10940
10941 @defun mapping-fold/reverse kons knil m
10942 [R7RS mapping]
10943 @c MOD scheme.mapping
10944 Liek @code{mapping-fold}, but calls @var{proc} for entris in
10945 decreasing order of keys in the mapping @var{m}.
10946 @end defun
10947
10948 @defun mapping-map->list proc m
10949 [R7RS mapping]
10950 @c MOD scheme.mapping
10951 Calls @var{proc} on each entry in the mapping @var{m}, in increasing
10952 order of the keys. The entry's key and value are passed as arguments
10953 to @var{proc}. The result of each call of @var{proc} is gathered
10954 into a list and returned.
10955 @end defun
10956
10957 @defun mapping-filter pred m
10958 @defunx mapping-filter! pred m
10959 [R7RS mapping]
10960 @c MOD scheme.mapping
10961 Returns a mapping that contains all the entries from the mapping @var{m}
10962 except those for which @var{pred} returns false. The procedure
10963 @var{pred} gets to arguments, an entry's key and an entry's value.
10964
10965 The functional version @code{mapping-filter} doesn't modify @var{m},
10966 while the linear-updating verison @code{mapping-filter!} may reuse
10967 @var{m} to create a result.
10968 @end defun
10969
10970 @defun mapping-remove pred m
10971 @defunx mapping-remove! pred m
10972 [R7RS mapping]
10973 @c MOD scheme.mapping
10974 Returns a mapping that contains all the entries from the mapping @var{m}
10975 except those for which @var{pred} returns a true value. The procedure
10976 @var{pred} gets to arguments, an entry's key and an entry's value.
10977
10978 The functional version @code{mapping-remove} doesn't modify @var{m},
10979 while the linear-updating verison @code{mapping-remove!} may reuse
10980 @var{m} to create a result.
10981 @end defun
10982
10983 @defun mapping-partition pred m
10984 @defunx mapping-partition! pred m
10985 [R7RS mapping]
10986 @c MOD scheme.mapping
10987 @end defun
10988
10989 @subsubheading Copying and conversion
10990
10991 @defun mapping-copy m
10992 [R7RS mapping]
10993 @c MOD scheme.mapping
10994 @end defun
10995
10996 @defun mapping->alist m
10997 [R7RS mapping]
10998 @c MOD scheme.mapping
10999 @end defun
11000
11001 @defun alist->mapping comparator alist
11002 [R7RS mapping]
11003 @c MOD scheme.mapping
11004 @end defun
11005
11006 @defun alist->mapping! m alist
11007 [R7RS mapping]
11008 @c MOD scheme.mapping
11009 @end defun
11010
11011 @defun alist->mapping/ordered comparator alist
11012 @defunx alist->mapping/ordered! m alist
11013 [R7RS mapping]
11014 @c MOD scheme.mapping
11015 @end defun
11016
11017 @subsubheading Submappings
11018
11019 @defun mapping=? comparator m1 m2 @dots{}
11020 [R7RS mapping]
11021 @c MOD scheme.mapping
11022 @end defun
11023
11024 @defun mapping<? comparator m1 m2 @dots{}
11025 @defunx mapping<=? comparator m1 m2 @dots{}
11026 @defunx mapping>? comparator m1 m2 @dots{}
11027 @defunx mapping>=? comparator m1 m2 @dots{}
11028 [R7RS mapping]
11029 @c MOD scheme.mapping
11030 @end defun
11031
11032 @subsubheading Set operations
11033
11034 @defun mapping-union m1 m2 @dots{}
11035 @defunx mapping-union! m1 m2 @dots{}
11036 [R7RS mapping]
11037 @c MOD scheme.mapping
11038 @end defun
11039
11040 @defun mapping-intersection m1 m2 @dots{}
11041 @defunx mapping-intersection! m1 m2 @dots{}
11042 [R7RS mapping]
11043 @c MOD scheme.mapping
11044 @end defun
11045
11046 @defun mapping-difference m1 m2 @dots{}
11047 @defunx mapping-difference! m1 m2 @dots{}
11048 [R7RS mapping]
11049 @c MOD scheme.mapping
11050 @end defun
11051
11052 @defun mapping-xor m1 m2 @dots{}
11053 @defunx mapping-xor! m1 m2 @dots{}
11054 [R7RS mapping]
11055 @c MOD scheme.mapping
11056 @end defun
11057
11058 @subsubheading Mappings with ordered keys
11059
11060 @defun mapping-min-key m
11061 @defunx mapping-max-key m
11062 [R7RS mapping]
11063 @c MOD scheme.mapping
11064 @end defun
11065
11066 @defun mapping-min-value m
11067 @defunx mapping-max-value m
11068 [R7RS mapping]
11069 @c MOD scheme.mapping
11070 @end defun
11071
11072 @defun mapping-min-entry m
11073 @defunx mapping-max-entry m
11074 [R7RS mapping]
11075 @c MOD scheme.mapping
11076 @end defun
11077
11078 @defun mapping-key-predecessor m obj failure
11079 @defunx mapping-key-successor m obj failure
11080 [R7RS mapping]
11081 @c MOD scheme.mapping
11082 @end defun
11083
11084 @defun mapping-range= m obj
11085 @defunx mapping-range< m obj
11086 @defunx mapping-range<= m obj
11087 @defunx mapping-range> m obj
11088 @defunx mapping-range>= m obj
11089 [R7RS mapping]
11090 @c MOD scheme.mapping
11091 @end defun
11092
11093 @defun mapping-range=! m obj
11094 @defunx mapping-range<! m obj
11095 @defunx mapping-range<=! m obj
11096 @defunx mapping-range>! m obj
11097 @defunx mapping-range>=! m obj
11098 [R7RS mapping]
11099 @c MOD scheme.mapping
11100 @end defun
11101
11102 @defun mapping-split m obj
11103 @defunx mapping-split! m obj
11104 [R7RS mapping]
11105 @c MOD scheme.mapping
11106 @end defun
11107
11108 @defun mapping-catenate comparator m1 key value m2
11109 @defunx mapping-catenate! m1 key value m2
11110 [R7RS mapping]
11111 @c MOD scheme.mapping
11112 @end defun
11113
11114 @subsubheading Comparators
11115
11116 @defun make-mapping-comparator comparator
11117 [R7RS mapping]
11118 @c MOD scheme.mapping
11119 @end defun
11120
11121 @defvar mapping-comparator
11122 [R7RS mapping]
11123 @c MOD scheme.mapping
11124 @end defvar
11125
11126
11127 @node Hashmaps, , Mappings, R7RS mappings
11128 @subsubsection Hashmaps
11129 @c NODE Hashmaps
11130
11131 @subsubheading Constructors
11132
11133 @defun hashmap comparator key value @dots{}
11134 [R7RS mapping]
11135 @c MOD scheme.mapping.hash
11136 Creates a new hashmap with the given @var{comparator},
11137 whose initial content is
11138 provided by @var{key} @var{value} @dots{}.
11139
11140 The @var{comparator} argument must be a comparator
11141 (@pxref{Basic comparators}).
11142
11143 The @var{key} @var{value} @dots{} arguments must be
11144 even length, alternating keys and values.
11145
11146 @example
11147 (define m (hashmap default-comparator 'a 1 'b 2))
11148
11149 (hashmap-ref m 'a) @result{} 1
11150 (hashmap-ref m 'b) @result{} 2
11151 @end example
11152 @end defun
11153
11154 @defun hashmap-unfold p f g seed comparator
11155 [R7RS mapping]
11156 @c MOD scheme.mapping.hash
11157 Creates a new hashmap, whose content is populated by
11158 three procedures, @var{p}, @var{f} and @var{g}, and
11159 a seed value @var{seed}, as follows.
11160
11161 In each iteration, we have a current seed value, whose initial
11162 value is @var{seed}.
11163
11164 First, @var{p}, a stop predicate, is applied to the current
11165 seed value. If it returns true, we stop iteration and returns
11166 the new hashmap.
11167
11168 Next, @var{f} is applied to the current seed value. It must
11169 return two values. The first one is for a key and the second
11170 one for the value. We add this pair to the hashmap.
11171
11172 Then, @var{g} is applied to the current seed value. The result
11173 becomes the seed value of the next iteration. And we iterate.
11174
11175 The following example creates a hashmap that maps ASCII characters
11176 to their character codes:
11177
11178 @example
11179 (hashmap-unfold (cut >= <> 128)
11180 (^c (values (integer->char c) c))
11181 (cut + <> 1)
11182 0
11183 default-comparator)
11184 @end example
11185 @end defun
11186
11187 @subsubheading Predicates
11188
11189 @defun hashmap? obj
11190 [R7RS mapping]
11191 @c MOD scheme.mapping.hash
11192 Returns @code{#t} iff @var{obj} is a hashmap object.
11193 @end defun
11194
11195 @defun hashmap-empty? m
11196 [R7RS mapping]
11197 @c MOD scheme.mapping.hash
11198 @var{M} must be a hashmap.
11199 Returns @code{#t} if @var{m} is empty, @code{#f} otherwise.
11200 In Gauche, this is same as @code{tree-map-empty?}
11201 (@pxref{Treemaps}).
11202 @end defun
11203
11204 @defun hashmap-contains? m key
11205 [R7RS mapping]
11206 @c MOD scheme.mapping.hash
11207 @var{M} must be a hashmap.
11208 Returns @code{#t} if @var{m} has an entry with @var{key},
11209 @code{#f} otherwise.
11210 In Gauche, this is same as @code{tree-map-exists?}
11211 (@pxref{Treemaps}).
11212 @end defun
11213
11214 @defun hashmap-disjoint? m1 m2
11215 [R7RS mapping]
11216 @c MOD scheme.mapping.hash
11217 Returns @code{#t} iff two hashmaps @var{m1} and @var{m2} have no keys
11218 in common. In other words, there's no such key K that
11219 satisfy both @code{(hashmap-contains? m1 K)} and
11220 @code{(hashmap-contains? m2 K)}.
11221 @end defun
11222
11223 @subsubheading Accessors
11224
11225 @defun hashmap-ref m key :optional failure success
11226 [R7RS mapping]
11227 @c MOD scheme.mapping.hash
11228 Get the value from a hashmap @var{m} associated with @var{key},
11229 and calls @var{success} on the value, and returns its result.
11230 If @var{m} doesn't have @var{key}, @var{failure} is invoked with no
11231 arguments and its result is returned.
11232 Both @var{success} and @var{failure} is called in tail context.
11233
11234 When @var{failure} is omitted and @var{key} is not found, an error
11235 is signaled. When @var{success} is omitted, @code{identity} is
11236 assumed.
11237 @end defun
11238
11239 @defun hashmap-ref/default m key default
11240 [R7RS mapping]
11241 @c MOD scheme.mapping.hash
11242 Returns the value associated to @var{key} from a hashmap @var{m}.
11243 If @var{m} doesn't have @var{key}, @var{default} is returned.
11244 @end defun
11245
11246 @defun hashmap-key-comparator m
11247 [R7RS mapping]
11248 @c MOD scheme.mapping.hash
11249 Returns a comparator used to compare keys in a hashmap @var{m}.
11250 @xref{Basic comparators}, for the details of comparators.
11251 @end defun
11252
11253 @subsubheading Updaters
11254
11255 Note that the basic premise of hashmaps srfi is to treat hashmaps
11256 as immutable. Each updating operation comes with a purely functional
11257 version (without bang) and a linear update version (with bang), but
11258 the linear update version may not require to destructively modiy
11259 the passed hashmap; it's merely a hint that it may reuse the
11260 argument for the efficiency. You always need to use the returned
11261 hashmap as the result of update. If you use linear update versions,
11262 you shouldn't use the passed hashmap afterwards, for there's no guarantee
11263 how the state of the passed hashmap is.
11264
11265 @defun hashmap-adjoin m arg @dots{}
11266 @defunx hashmap-adjoin! m arg @dots{}
11267 [R7RS mapping]
11268 @c MOD scheme.mapping.hash
11269
11270 @end defun
11271
11272 @defun hashmap-set m arg @dots{}
11273 @defunx hashmap-set! m arg @dots{}
11274 [R7RS mapping]
11275 @c MOD scheme.mapping.hash
11276 @end defun
11277
11278 @defun hashmap-replace m key value
11279 @defunx hashmap-replace! m key value
11280 [R7RS mapping]
11281 @c MOD scheme.mapping.hash
11282 @end defun
11283
11284
11285 @defun hashmap-delete m key @dots{}
11286 @defunx hashmap-delete! m key @dots{}
11287 [R7RS mapping]
11288 @c MOD scheme.mapping.hash
11289 @end defun
11290
11291 @defun hashmap-delete-all m key-list
11292 @defunx hashmap-delete-all! m key-list
11293 [R7RS mapping]
11294 @c MOD scheme.mapping.hash
11295 @end defun
11296
11297
11298 @defun hashmap-intern m key failure
11299 @defunx hashmap-intern! m key failure
11300 [R7RS mapping]
11301 @c MOD scheme.mapping.hash
11302 @end defun
11303
11304 @defun hashmap-update m key updater :optional failure success
11305 @defunx hashmap-update! m key updater :optional failure success
11306 [R7RS mapping]
11307 @c MOD scheme.mapping.hash
11308 @end defun
11309
11310 @defun hashmap-update/default m key updater default
11311 @defunx hashmap-update!/default m key updater default
11312 [R7RS mapping]
11313 @c MOD scheme.mapping.hash
11314 @end defun
11315
11316 @defun hashmap-pop m :optional failure
11317 @defunx hashmap-pop! m :optional failure
11318 [R7RS mapping]
11319 @c MOD scheme.mapping.hash
11320 @end defun
11321
11322 @defun hashmap-search m k failure success
11323 @defunx hashmap-search! m k failure success
11324 [R7RS mapping]
11325 @c MOD scheme.mapping.hash
11326 @end defun
11327
11328 @subsubheading The whole hashmap
11329
11330 @defun hashmap-size m
11331 [R7RS mapping]
11332 @c MOD scheme.mapping.hash
11333 @end defun
11334
11335 @defun hashmap-find pred m failure
11336 [R7RS mapping]
11337 @c MOD scheme.mapping.hash
11338 @end defun
11339
11340 @defun hashmap-count pred m
11341 [R7RS mapping]
11342 @c MOD scheme.mapping.hash
11343 @end defun
11344
11345 @defun hashmap-any? pred m
11346 @defunx hashmap-every? pred m
11347 [R7RS mapping]
11348 @c MOD scheme.mapping.hash
11349 @end defun
11350
11351 @defun hashmap-keys m
11352 @defunx hashmap-values m
11353 [R7RS mapping]
11354 @c MOD scheme.mapping.hash
11355 @end defun
11356
11357 @defun hashmap-entries m
11358 [R7RS mapping]
11359 @c MOD scheme.mapping.hash
11360 @end defun
11361
11362 @subsubheading Mapping and folding
11363
11364 @defun hashmap-map proc comparator m
11365 [R7RS mapping]
11366 @c MOD scheme.mapping.hash
11367 @end defun
11368
11369 @defun hashmap-for-each proc m
11370 [R7RS mapping]
11371 @c MOD scheme.mapping.hash
11372 @end defun
11373
11374 @defun hashmap-fold kons knil m
11375 [R7RS mapping]
11376 @c MOD scheme.mapping.hash
11377 @end defun
11378
11379 @defun hashmap-map->list proc m
11380 [R7RS mapping]
11381 @c MOD scheme.mapping.hash
11382 @end defun
11383
11384 @defun hashmap-filter pred m
11385 @defunx hashmap-filter! pred m
11386 [R7RS mapping]
11387 @c MOD scheme.mapping.hash
11388 @end defun
11389
11390 @defun hashmap-remove pred m
11391 @defunx hashmap-remove! pred m
11392 [R7RS mapping]
11393 @c MOD scheme.mapping.hash
11394 @end defun
11395
11396 @defun hashmap-partition pred m
11397 @defunx hashmap-partition! pred m
11398 [R7RS mapping]
11399 @c MOD scheme.mapping.hash
11400 @end defun
11401
11402 @subsubheading Copying and conversion
11403
11404 @defun hashmap-copy m
11405 [R7RS mapping]
11406 @c MOD scheme.mapping.hash
11407 @end defun
11408
11409 @defun hashmap->alist m
11410 [R7RS mapping]
11411 @c MOD scheme.mapping.hash
11412 @end defun
11413
11414 @defun alist->hashmap comparator alist
11415 [R7RS mapping]
11416 @c MOD scheme.mapping.hash
11417 @end defun
11418
11419 @defun alist->hashmap! m alist
11420 [R7RS mapping]
11421 @c MOD scheme.mapping.hash
11422 @end defun
11423
11424 @subsubheading Subhashmaps
11425
11426 @defun hashmap=? comparator m1 m2 @dots{}
11427 [R7RS mapping]
11428 @c MOD scheme.mapping.hash
11429 @end defun
11430
11431 @defun hashmap<? comparator m1 m2 @dots{}
11432 @defunx hashmap<=? comparator m1 m2 @dots{}
11433 @defunx hashmap>? comparator m1 m2 @dots{}
11434 @defunx hashmap>=? comparator m1 m2 @dots{}
11435 [R7RS mapping]
11436 @c MOD scheme.mapping.hash
11437 @end defun
11438
11439 @subsubheading Set operations
11440
11441 @defun hashmap-union m1 m2 @dots{}
11442 @defunx hashmap-union! m1 m2 @dots{}
11443 [R7RS mapping]
11444 @c MOD scheme.mapping.hash
11445 @end defun
11446
11447 @defun hashmap-intersection m1 m2 @dots{}
11448 @defunx hashmap-intersection! m1 m2 @dots{}
11449 [R7RS mapping]
11450 @c MOD scheme.mapping.hash
11451 @end defun
11452
11453 @defun hashmap-difference m1 m2 @dots{}
11454 @defunx hashmap-difference! m1 m2 @dots{}
11455 [R7RS mapping]
11456 @c MOD scheme.mapping.hash
11457 @end defun
11458
11459 @defun hashmap-xor m1 m2 @dots{}
11460 @defunx hashmap-xor! m1 m2 @dots{}
11461 [R7RS mapping]
11462 @c MOD scheme.mapping.hash
11463 @end defun
11464
11465 @subsubheading Comparators
11466
11467 @defun make-hashmap-comparator comparator
11468 [R7RS mapping]
11469 @c MOD scheme.mapping.hash
11470 @end defun
11471
11472 @defvar hashmap-comparator
11473 [R7RS mapping]
11474 @c MOD scheme.mapping.hash
11475 @end defvar
11476
11477 @c ----------------------------------------------------------------------
11478 @node R7RS integer division, R7RS bitwise operations, R7RS mappings, R7RS large
11479 @subsection @code{scheme.division} - R7RS integer division
11480 @c NODE R7RS整数除算, @code{scheme.division} - R7RS整数除算
11481
11482 @deftp {Module} scheme.division
11483 @mdindex scheme.division
11484 @c EN
11485 This module provides a comprehensive set of integer division operators.
11486
11487 Quotient and remainder in integer divisions can be defined in multiple
11488 ways, when you consider the choice of sign of the result with regard to
11489 the operands. Gauche has builtin procedures in several flavors:
11490 R5RS @code{quotient}, @code{remainder} and @code{modulo},
11491 R6RS @code{div}, @code{mod}, @code{div0} and @code{mod0},
11492 and R7RS @code{floor-quotient}, @code{floor-remainder}, @code{floor/},
11493 @code{truncate-quotient}, @code{truncate-remainder}, @code{truncate/}.
11494
11495 This module complements R7RS procedures, by adding @code{ceiling},
11496 @code{round}, @code{euclidean} and @code{balanced} variants.
11497
11498 The following procedures are in scheme.division but built-in in Gauche
11499 (@pxref{Arithmetics}).
11500 @c JP
11501 このモジュールは、様々な整数除算操作を包括的に提供します。
11502
11503 整数除算の商と剰余には、除数と被除数の符号の考慮によって、
11504 いくつかの定義が考えられます。
11505 Gaucheはそのうちいくつかの定義を組み込みで提供しています:
11506 R5RSの@code{quotient}、@code{remainder}、@code{modulo}、
11507 R6RSの@code{div}、@code{mod}、@code{div0}、@code{mod0}、
11508 そしてR7RSの
11509 @code{floor-quotient}、@code{floor-remainder}、@code{floor/}、
11510 @code{truncate-quotient}、@code{truncate-remainder}、@code{truncate/}、です。
11511
11512 このモジュールは、R7RSの手続きにさらに
11513 @code{ceiling}、
11514 @code{round}、@code{euclidean}、@code{balanced}のバリエーションを加えます。
11515
11516 scheme.divisionの以下の手続きについては組み込みになっているので、
11517 @ref{Arithmetics}を参照してください。
11518 @c COMMON
11519 @example
11520 floor-quotient floor-remainder floor/
11521 truncate-quotient truncate-remainder truncate/
11522 @end example
11523 @end deftp
11524
11525 @defun ceiling-quotient n d
11526 @defunx ceiling-remainder n d
11527 @defunx ceiling/ n d
11528 [R7RS division]
11529 @c MOD scheme.division
11530 @example
11531 ceiling-quotient = ceiling(n / d)
11532 ceiling-remainder = n - d * ceiling-quotient
11533 ceiling/ = values(ceiling-quotient, ceiling-remainder)
11534 @end example
11535 @end defun
11536
11537 @defun round-quotient n d
11538 @defunx round-remainder n d
11539 @defunx round/ n d
11540 [R7RS division]
11541 @c MOD scheme.division
11542 @example
11543 round-quotient = round(n/d)
11544 round-remainder = n - d * round-quotient
11545 round/ = values(round-quotient, round-remainder)
11546 @end example
11547 @end defun
11548
11549 @defun euclidean-quotient n d
11550 @defunx euclidean-remainder n d
11551 @defunx euclidean/ n d
11552 [R7RS division]
11553 @c MOD scheme.division
11554 @example
11555 euclidean-quotient = floor(n / d) if d > 0
11556 ceiling(n / d) if d < 0
11557 euclidean-remainder = n - d * euclidean-quotient
11558 euclidean/ = values(euclidean-quotient, euclidean-remainder)
11559 @end example
11560 @c EN
11561 The Eclidean variant satisfies a property @code{0 <= remainder < abs(d)}.
11562 These are the same as R6RS's @code{div}, @code{mod}, and @code{div-and-mod},
11563 except that they accept non-integers (@pxref{Arithmetics})
11564 @c JP
11565 Eclideanバリエーションは、@code{0 <= remainder < abs(d)}という関係を常に満たします。
11566 この定義はR6RSの@code{div}、@code{mod}および@code{div-and-mod}と同じです。
11567 但し、R6RS版は非整数を引数に取ることもできます(@ref{Arithmetics}参照)。
11568 @c COMMON
11569 @end defun
11570
11571 @defun balanced-quotient n d
11572 @defunx balanced-remainder n d
11573 @defunx balanced/ n d
11574 [R7RS division]
11575 @c MOD scheme.division
11576 @example
11577 balanced-quotient = roundup(n / d)
11578 balanced-remainder = n - d * balanced-quotient
11579 balanced/ = values(balanced-quotient, balanced-remainder)
11580 @c EN
11581 where roundup(x) rounds towards zero if |x| - floor(|x|) < 0.5,
11582 and away from zero if |x| - floor(|x|) >= 0.5,
11583 @c JP
11584 ここでroundup(x)は、|x| - floor(|x|) < 0.5 ならゼロの方向に、
11585 |x| - floor(|x|) >= 0.5 ならゼロと逆方向丸めます
11586 @c COMMON
11587 @end example
11588 @c EN
11589 The balanced variant satisfies a property
11590 @code{-abs(d/2) <= remainder < abs(d/2)}.
11591 These are the same as R6RS's @code{div0}, @code{mod0}, and
11592 @code{div0-and-mod0}, except that they accept non-integers
11593 (@pxref{Arithmetics}).
11594 @c JP
11595 Balancedバージョンは@code{-abs(d/2) <= remainder < abs(d/2)}という
11596 関係を常に満たします。これはR6RSの
11597 @code{div0}、@code{mod0}および@code{div0-and-mod0}と同じです。
11598 但し、R6RS版は非整数を引数に取ることもできます(@ref{Arithmetics}参照)。
11599 @c COMMON
11600 @end defun
11601
11602 @c ----------------------------------------------------------------------
11603 @node R7RS bitwise operations, R7RS fixnum, R7RS integer division, R7RS large
11604 @subsection @code{scheme.bitwise} - R7RS bitwise operations
11605 @c NODE R7RSビット演算, @code{scheme.bitwise} - R7RSビット演算
11606
11607 @deftp {Module} scheme.bitwise
11608 @mdindex scheme.bitwise
11609 @c EN
11610 This module provides comprehensive bitwise operations.
11611 Originally it was SRFI-151.
11612 It is mostly a superset of SRFI-60, with some change of names for the consistency
11613 and the compatibility (@pxref{Integers as bits}). We keep SRFI-60 for
11614 legacy code, while recommend this module to be used in the new code.
11615
11616 The following procedures are Gauche built-in.
11617 @xref{Basic bitwise operations}, for the description.
11618 @c JP
11619 このモジュールは包括的なビット演算手続きを提供します。
11620 元はSRFI-151で、
11621 ほぼSRFI-60のスーパーセットですが、いくつかの手続きは一貫性と互換性のために
11622 名前が変わりました(SRFI-60については@ref{Integers as bits}参照)。
11623 SRFI-60も以前のコードとの互換性のため残されますが、新たに書くコードは
11624 このモジュールを使うことを推奨します。
11625
11626 以下の手続きはGauche組み込みになっています。
11627 説明は@ref{Basic bitwise operations}を参照してください。
11628 @c COMMON
11629
11630 @example
11631 integer-length copy-bit bit-field
11632 @end example
11633 @end deftp
11634
11635 @c EN
11636 @subheading Basic operations
11637 @c JP
11638 @subheading 基本演算
11639 @c COMMON
11640
11641 @defun bitwise-not n
11642 [R7RS bitwise]
11643 @c MOD scheme.bitwise
11644 @c EN
11645 Returns the bitwise complement of @var{n}.
11646 Same as builtin @code{lognot} (@pxref{Basic bitwise operations}).
11647 @c JP
11648 @var{n}の各ビットを反転したものを返します。
11649 組み込みの@code{lognot}と同じです。(@ref{Basic bitwise operations}参照)。
11650 @c COMMON
11651 @end defun
11652
11653 @defun bitwise-and n @dots{}
11654 @defunx bitwise-ior n @dots{}
11655 @defunx bitwise-xor n @dots{}
11656 @defunx bitwise-eqv n @dots{}
11657 [R7RS bitwise]
11658 @c MOD scheme.bitwise
11659 @c EN
11660 When no arguments are given, these procedures returns @code{-1}, @code{0},
11661 @code{0} and @code{-1}, respectively. With one arguments, they return the
11662 argument as is. With two arguments, they return bitwise and, ior, xor,
11663 and eqv (complement of xor). With three or more arguments, they apply
11664 binary operations associaively, that is,
11665 @c JP
11666 引数が与えられない場合、これらはそれぞれ@code{-1}、@code{0}、@code{0}、@code{-1}を
11667 返します。引数がひとつの場合はそれをそのまま返します。
11668 引数が二つの場合は、それらのビット毎のand、ior、xor、及びeqv (xorの論理反転) を
11669 取ったものを返します。3引数以上は、2引数の計算から導かれます。
11670 @c COMMON
11671
11672 @example
11673 (bitwise-xor a b c)
11674 @equiv{} (bitwise-xor a (bitwise-xor b c))
11675 @equiv{} (bitwise-xor (bitwise-xor a b) c)
11676 @end example
11677
11678 @c EN
11679 Be careful that multi-argument @code{bitwise-eqv} does not produce
11680 bit 1 everywhere that all the argument's bit agree.
11681 @c JP
11682 この定義では、3引数以上の@code{bitwise-eqv}は
11683 「すべての引数の該当ビットが同じである時に1」とはならないことに注意してください。
11684 @c COMMON
11685
11686 @c EN
11687 The first three procedures are the same as built-in
11688 @code{logand}, @code{logior} and @code{logxor}, respectively
11689 (@pxref{Basic bitwise operations}).
11690 @c JP
11691 最初の3つの手続きはそれぞれ組み込みの
11692 @code{logand}、@code{logior}、@code{logxor}と同じです
11693 (@ref{Basic bitwise operations}参照)。
11694 @c COMMON
11695 @end defun
11696
11697 @defun bitwise-nand n0 n1
11698 @defunx bitwise-nor n0 n1
11699 @defunx bitwise-andc1 n0 n1
11700 @defunx bitwise-andc2 n0 n1
11701 @defunx bitwise-orc1 n0 n1
11702 @defunx bitwise-orc2 n0 n1
11703 [R7RS bitwise]
11704 @c MOD scheme.bitwise
11705 @c EN
11706 These operations are not associative.
11707 @c JP
11708 これらの手続きは2引数固定です。
11709 @c COMMON
11710
11711 @example
11712 nand n0 n1 @equiv{} (NOT (AND n0 n1))
11713 nor n0 n1 @equiv{} (NOT (OR n0 n1))
11714 andc1 n0 n1 @equiv{} (AND (NOT n0) n1)
11715 andc2 n0 n1 @equiv{} (AND n0 (NOT n1))
11716 orc1 n0 n1 @equiv{} (OR (NOT n0) n1)
11717 orc2 n0 n1 @equiv{} (OR n0 (NOT n1))
11718 @end example
11719 @end defun
11720
11721 @c EN
11722 @subheading Integer operations
11723 @c JP
11724 @subheading 整数演算
11725 @c COMMON
11726
11727 @defun arithmetic-shift n count
11728 [R7RS bitwise]
11729 @c MOD scheme.bitwise
11730 @c EN
11731 Shift @var{n} for @var{count} bits to left; if @var{count} is negative,
11732 it shifts @var{n} to right for @var{-count} bits.
11733
11734 Same as builtin @code{ash} (@pxref{Basic bitwise operations}).
11735 @c JP
11736 整数@var{n}を@var{count}ビット左シフトします。@var{count}が負ならば、
11737 @code{n}は@var{-count}ビット右にシフトされることになります。
11738
11739 これは組み込みの@code{ash}と同じです(@ref{Basic bitwise operations}参照)。
11740 @c COMMON
11741 @end defun
11742
11743 @defun bit-count n
11744 [R7RS bitwise]
11745 @c MOD scheme.bitwise
11746 @c EN
11747 If @var{n} is positive, returns the number of @code{1}'s in @var{n}.
11748 If @var{n} is negative, returns the number of @code{0}'s in @var{n}.
11749
11750 Same as builtin @code{logcount} (@pxref{Basic bitwise operations}).
11751 @c JP
11752 @var{n}が正の場合は@var{n}中の@code{1}であるビットの数を、
11753 @var{n}が負の場合は@var{n}中の@code{0}であるビットの数を返します。
11754
11755 組み込みの@code{logcount}と同じです(@ref{Basic bitwise operations}参照)。
11756 @c COMMON
11757 @end defun
11758
11759 @defun bitwise-if mask n0 n1
11760 [R7RS bitwise]
11761 @c MOD scheme.bitwise
11762 @c EN
11763 Returns integer, whose @var{n}-th bit is taken as follows:
11764 If the @var{n}-th bit of @var{mask} is 1, the @var{n}-th bit of @var{n0};
11765 otherwise, the @var{n}-th bit of @var{n1}.
11766 @c JP
11767 整数を返します。戻り値の@var{n}番目のビットは、@var{mask}の@var{n}番目のビットが
11768 1であれば@var{n0}の@code{n}番目のビット、0であれば@var{n1}の@code{n}番目のビット
11769 になります。
11770 @c COMMON
11771
11772 @example
11773 (bitwise-if #b10101100 #b00110101 #b11001010)
11774 @result{} #b01100110
11775 @end example
11776 @end defun
11777
11778 @c EN
11779 @subheading Single-bit operations
11780 @c JP
11781 @subheading 単一ビットの操作
11782 @c COMMON
11783
11784 @defun bit-set? index n
11785 [R7RS bitwise]
11786 @c MOD scheme.bitwise
11787 @c EN
11788 Returns @code{#t} or @code{#f} if @var{index}-th bit (counted from LSB)
11789 of @var{n} is @code{1} or @code{0}, respectively.
11790
11791 Same as built-in @code{logbit?} (@pxref{Basic bitwise operations}).
11792 @c JP
11793 @var{n}のLSBから数えて@var{index}番目(0ベース)のビットが@code{1}であれば
11794 @code{#t}を、@code{0}であれば@code{#f}を返します。
11795
11796 組み込みの@code{logbit?}と同じです(@ref{Basic bitwise operations}参照)。
11797 @c COMMON
11798 @end defun
11799
11800 @defun bit-swap index1 index2 n
11801 [R7RS bitwise]
11802 @c MOD scheme.bitwise
11803 @c EN
11804 Returns an integer with @var{index1}-th bit and @var{index2}-th bit are
11805 swapped. Index is counted from LSB.
11806 @c JP
11807 @var{n}の@var{index1}番目のビットと@var{index2}番目のビットを入れ替えた整数を
11808 返します。インデックスは0ベースでLSBから数えます。
11809 @c COMMON
11810 @end defun
11811
11812 @defun any-bit-set? mask n
11813 @defunx every-bit-set? mask n
11814 [R7RS bitwise]
11815 @c MOD scheme.bitwise
11816 @c EN
11817 Returns @code{#t} iff any/all bits set in @var{mask} are also set in @var{n}.
11818
11819 @code{any-bit-set?} is the same as built-in @code{logtest},
11820 except @code{logtest} accepts one or more arguments
11821 (@pxref{Basic bitwise operations}).
11822 @c JP
11823 @var{n}中で、@var{mask}でビットの立っている箇所のビットのいずれか(@code{any-bit-set?})
11824 あるいはすべて(@code{every-bit-set?})が@code{1}であれば@code{#t}を返し、
11825 それ以外では@code{#f}を返します。
11826
11827 @code{any-bit-set?}は組み込みの@code{logtest}とほぼ同じですが、
11828 @code{logtest}は可変長引数です
11829 (@ref{Basic bitwise operations}参照)。
11830 @c COMMON
11831 @end defun
11832
11833 @defun first-set-bit n
11834 [R7RS bitwise]
11835 @c MOD scheme.bitwise
11836 @c EN
11837 Returns the number of factors of two of integer @var{n}; that is,
11838 returns a maximum @code{k} such that @code{(expt 2 k)} divides
11839 @var{n} without a remainder.
11840 It is the same as the index of the least significant @code{1} in @var{n},
11841 hence the alias @code{first-set-bit}.
11842 @c JP
11843 @var{n}を割り切る@code{(expt 2 k)}のうち最大のkを返します。別の言い方をすれば、
11844 @var{n}のビット列のうち一番右にある@code{1}のインデックスを返します。
11845 @code{first-set-bit}の名前はそこからきています。
11846 @c COMMON
11847
11848 @example
11849 (first-set-bit 0) @result{} -1 ; @r{edge case}
11850 (first-set-bit 1) @result{} 0
11851 (first-set-bit 2) @result{} 1
11852 (first-set-bit 15) @result{} 0
11853 (first-set-bit 16) @result{} 4
11854 @end example
11855
11856 @c EN
11857 This is equivalent to Gauche's built-in @code{twos-exponent-factor}
11858 (@pxref{Basic bitwise operations}).
11859 @c JP
11860 これはGauche組み込みの@code{twos-exponent-factor}と同じです
11861 (@ref{Basic bitwise operations}参照)。
11862 @c COMMON
11863 @end defun
11864
11865 @c EN
11866 @subheading Bit field operations
11867 @c JP
11868 @subheading ビットフィールド操作
11869 @c COMMON
11870
11871 @defun bit-field-any? n start end
11872 @defunx bit-field-every? n start end
11873 [R7RS bitwise]
11874 @c MOD scheme.bitwise
11875 @c EN
11876 Returns @code{#t} iff any/all bits of @var{n} from @var{start} (inclusive)
11877 to @var{end} (exclusive) are set.
11878 @c JP
11879 @var{n}中の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までの
11880 ビットフィールドのうち、一つでもビットが立っていた場合(@code{bit-field-any?})、
11881 あるいは全てのビットが立っていた場合(@code{bit-field-every?})に@code{#t}を、
11882 それ以外に@code{#f}を返します。
11883 @c COMMON
11884 @end defun
11885
11886 @defun bit-field-clear n start end
11887 @defunx bit-field-set n start end
11888 [R7RS bitwise]
11889 @c MOD scheme.bitwise
11890 @c EN
11891 Returns @var{n} with the bits from @var{start} (inclusive)
11892 to @var{end} (exclusive) are set to all @code{0}'s/@code{1}'s.
11893 @c JP
11894 @var{n}中の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までの
11895 ビットを全て@code{0}あるいは@code{1}にした整数値を返します。
11896 @c COMMON
11897 @end defun
11898
11899 @defun bit-field-replace dst src start end
11900 [R7RS bitwise]
11901 @c MOD scheme.bitwise
11902 @c EN
11903 Returns @var{dst} with the bitfield from @var{start} to @var{end}
11904 are replaced with the least-significant (@var{end}-@var{start}) bits
11905 of @var{src.}
11906 @c JP
11907 @var{dst}中の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までの
11908 ビットフィールドを、@var{src}中の下位(@var{end}-@var{start})ビットで置き換えた
11909 値を返します。
11910 @c COMMON
11911
11912 @example
11913 (bit-field-replace #b101010 #b010 1 4) @result{} #b100100
11914 @end example
11915
11916 @c EN
11917 Same as built-in @code{copy-bit-field} (@pxref{Basic bitwise operations}).
11918 @c JP
11919 組み込みの@code{copy-bit-field}と同じです(@ref{Basic bitwise operations}参照)。
11920 @c COMMON
11921 @end defun
11922
11923 @defun bit-field-replace-same dst src start end
11924 [R7RS bitwise]
11925 @c MOD scheme.bitwise
11926 @c EN
11927 Returns @var{dst} with the bitfield from @var{start} to @var{end}
11928 are replaced with the @code{src}'s bitfield from @var{start} to @var{end}.
11929 @c JP
11930 @var{dst}中の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までの
11931 ビットフィールドを、
11932 @var{src}中の同じ位置にあるビットフィールドに置き換えた値を返します。
11933 @c COMMON
11934
11935 @example
11936 (bit-field-replace-same #b111111 #b100100 1 4) @result{} #b110101
11937 @end example
11938 @end defun
11939
11940 @defun bit-field-rotate n count start end
11941 [R7RS bitwise]
11942 @c MOD scheme.bitwise
11943 @c EN
11944 Rotate the region of @var{n} between @var{start}-th bit (inclusive) and
11945 @var{end}-th bit (exclusive) by @var{count} bits to the left.
11946 If @var{count} is negative, it rotates to the right by @var{-count}
11947 bits.
11948 @c JP
11949 @var{n}中の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までの
11950 ビットフィールドを、@var{count}ビットだけ左にローテートした値を返します。
11951 @var{count}が負の場合は@var{-count}ビットだけ右にローテートします。
11952 @c COMMON
11953
11954 @example
11955 (bit-field-rotate #b110100100010000 -1 5 9)
11956 @result{} 26768 ;#b110100010010000
11957
11958 (bit-field-rotate #b110100100010000 1 5 9)
11959 @result{} 26672 ;#b110100000110000
11960 @end example
11961 @end defun
11962
11963 @defun bit-field-reverse n start end
11964 [R7RS bitwise]
11965 @c MOD scheme.bitwise
11966 @c EN
11967 Reverse the order of bits of @var{n} between @var{start}-th bit
11968 (inclusive) and @var{end}-th bit (exclusive).
11969 @c JP
11970 @var{n}中の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までの
11971 ビットフィールドを逆順にしたものを返します。
11972 @c COMMON
11973
11974 @example
11975 (bit-field-reverse #b10100111 0 8)
11976 @result{} 229 ; #b11100101
11977 @end example
11978 @end defun
11979
11980 @c EN
11981 @subheading Bits conversion
11982 @c JP
11983 @subheading ビット変換
11984 @c COMMON
11985
11986 @defun bits->list n :optional len
11987 @defunx bits->vector n :optional len
11988 [R7RS bitwise]
11989 @c MOD scheme.bitwise
11990 @c EN
11991 Returns a list/vector of booleans of length @var{len},
11992 corresponding to each bit in non-negative integer @var{n}, LSB-first.
11993 When @var{len} is omitted, @code{(integer-length n)} is used.
11994 @c JP
11995 非負整数@var{n}を、長さ@var{len}の真偽値からなるリストまたはベクタにして返します。
11996 ビットはLSBから順に取り出されます。@var{len}が省略された場合は
11997 @code{(integer-length n)}が使われます。
11998 @c COMMON
11999
12000 @example
12001 (bits->vector #b101101110)
12002 @result{} #(#f #t #t #t #f #t #t #f #t)
12003 @end example
12004
12005 @c EN
12006 Note: SRFI-60 has a similar @code{integer->list}, but the order of
12007 bits is reversed.
12008 @c JP
12009 註: SRFI-60には@code{integer->list}という似た手続きがありますが、
12010 ビットの順番が逆です。
12011 @c COMMON
12012 @end defun
12013
12014 @defun list->bits bool-list
12015 @defunx vector->bits bool-vector
12016 [R7RS bitwise]
12017 @c MOD scheme.bitwise
12018 @c EN
12019 Returns an exact integer formed from boolean values in given list/vector,
12020 LSB first. The result will never be negative.
12021 @c JP
12022 真偽値のリストまたはベクタを受け取り、
12023 LSBから対応するビットを詰めた正確な整数を返します。
12024 返り値は負になることはありません。
12025 @c COMMON
12026
12027 @example
12028 (list->bits '(#f #t #t #t #f #t #t #f #t))
12029 @result{} #b101101110
12030 @end example
12031
12032 @c EN
12033 Note: SRFI-60 has a similar @code{list->integer}, but the order of
12034 bits is reversed.
12035 @c JP
12036 註: SRFI-60には@code{list->integer}という似た手続きがありますが、
12037 ビットの順番が逆です。
12038 @c COMMON
12039 @end defun
12040
12041 @defun bits bool @dots{}
12042 [R7RS bitwise]
12043 @c MOD scheme.bitwise
12044 @c EN
12045 Returns the integer coded by @var{bool}s, LSB first.
12046 The result will never be negative.
12047 @c JP
12048 真偽値@var{bool}の列をLSBから順にビットとして詰めた整数を返します。
12049 返り値は負になることはありません。
12050 @c COMMON
12051
12052 @example
12053 (bits #f #t #t #t #f #t #t #f #t)
12054 @result{} #b101101110
12055 @end example
12056
12057 @c EN
12058 Note: SRFI-60 has a similar @code{booleans->integer}, but the order of
12059 bits is reversed.
12060 @c JP
12061 註: SRFI-60には@code{booleans->integer}という似た手続きがありますが、
12062 ビットの順番が逆です。
12063 @c COMMON
12064 @end defun
12065
12066 @c EN
12067 @subheading Fold, unfold and generate
12068 @c JP
12069 @subheading Foldとunfoldとgenerate
12070 @c COMMON
12071
12072 @defun bitwise-fold kons knil n
12073 [R7RS bitwise]
12074 @c MOD scheme.bitwise
12075 @c EN
12076 Traverse bits in integer @var{n} from LSB to the @code{(integer-length n)} bit,
12077 applying @code{kons} on the bit as boolean
12078 and the seed value, whose initial value
12079 is given by @var{knil}. Returns the last result of @var{kons}.
12080 @c JP
12081 整数@var{n}のビットを、LSBから@code{(integer-length n)}ビット分、順に調べ、
12082 各ビットを真偽値とみなした値とシード値に@var{kons}を適用してゆきます。
12083 @var{kons}の戻り値が次のシード値となり、最後の@var{kons}の結果が返されます。
12084 @c COMMON
12085
12086 @example
12087 (bitwise-fold cons '() #b10110111)
12088 @result{} (#t #f #t #t #f #t #t #t)
12089 @end example
12090 @end defun
12091
12092 @defun bitwise-for-each proc n
12093 [R7RS bitwise]
12094 @c MOD scheme.bitwise
12095 @c EN
12096 Applies @var{proc} to the bit as boolean in @var{n}, from LSB to
12097 the @code{(integer-length n)} bit. The result is discarded.
12098 @c JP
12099 整数@var{n}の各ビットを真偽値とみなした値に対して、
12100 LSBから順に@code{(integer-length n)}ビット分、@var{proc}を適用してゆきます。
12101 @var{proc}の結果は捨てられます。
12102 @c COMMON
12103 @end defun
12104
12105 @defun bitwise-unfold p f g seed
12106 [R7RS bitwise]
12107 @c MOD scheme.bitwise
12108 @c EN
12109 Generates a non-negative integer bit by bit, from LSB to MSB.
12110 The @var{seed} gives the initial state value.
12111 For each iteration, @var{p} is applied to the current state value,
12112 and if it returns a true value, the iteration ends and @code{bitwise-unfold}
12113 returns the accumulated bits as an integer.
12114 Otherwise, @var{f} is applied to the current state value, and
12115 its result, coerced to a boolean value, determines the bit value.
12116 Then @var{g} is applied to the current state value to produce
12117 the next state value of the next iteration.
12118 @c JP
12119 非負整数をLSBから順に1ビットづつ生成します。
12120 @var{seed}は状態の値の初期値を与えます。
12121 各繰り返しにおいて、@var{p}が現在の状態の値に適用され、
12122 その結果が真ならば繰り返しは終了し@code{bitwise-unfold}は蓄積されたビットを整数として
12123 返します。
12124 そうでなければ、@var{f}が現在の状態の値に適用され、
12125 その結果が真の値なら対応するビットが1に、偽なら0になります。
12126 次いで@var{g}が現在の状態の値に適用され、その結果が次の繰り返しにおける状態の値となります。
12127 @c COMMON
12128
12129 @c EN
12130 The following expression produces a bitfield of width 100, where n-th bit
12131 indicates whether n is prime or not:
12132 @c JP
12133 次の式は、nビット目が、nが素数なら1になっているような100ビット長の整数を返します。
12134 @c COMMON
12135
12136 @example
12137 (use math.prime)
12138 (bitwise-unfold (cut = 100 <>)
12139 small-prime?
12140 (cut + 1 <>)
12141 0)
12142 @end example
12143 @end defun
12144
12145 @defun make-bitwise-generator n
12146 [R7RS bitwise]
12147 @c MOD scheme.bitwise
12148 @c EN
12149 Returns a generator that generates boolean values
12150 corresponding to the bits in @var{n}, LSB-first. The returned generator
12151 is infinite.
12152
12153 This is similar to @code{bits->generator} in @code{gauche.generator},
12154 except that the generator created by it stops at the integer
12155 length of @var{n} (@pxref{Generators}).
12156 @c JP
12157 整数nの各ビットをLSBから順に真偽値として生成するようなジェネレータを作って返します。
12158 返されるジェネレータは無限です。
12159
12160 これは@code{gauche.integer}の@code{bits->generator}と似ていますが、
12161 @code{bits->generator}が作るジェネレータの方は@var{n}の@code{integer-length}で止まります。
12162 詳しくは@ref{Generators}を参照してください。
12163 @c COMMON
12164 @end defun
12165
12166 @c ----------------------------------------------------------------------
12167 @node R7RS fixnum, R7RS flonum, R7RS bitwise operations, R7RS large
12168 @subsection @code{scheme.fixnum} - R7RS fixnums
12169 @c NODE R7RS fixnum, @code{scheme.fixnum} - R7RS fixnum
12170
12171 @deftp {Module} scheme.fixnum
12172 @mdindex scheme.finxum
12173 @c EN
12174 This module provides a set of fixnum-specific operations.
12175 Originally defined as SRFI-143.
12176
12177 A fixnum is a small exact integer that can be handled very efficiently.
12178 In Gauche, fixnum is 62bit wide on 64bit platforms, and
12179 30bit wide on 32bit platforms.
12180 @c JP
12181 このモジュールはfixnumに特化した操作を提供します。
12182 SRFI-143として制定されました。
12183
12184 fixnumは絶対値が小さめの正確な整数で、極めて効率的に処理できます。
12185 Gaucheのfixnumは、64ビット環境では62ビット、32ビット環境では30ビットの幅を持ちます。
12186 @c COMMON
12187
12188 @c EN
12189 Note that these procedures are defined only to work on fixnums,
12190 but it is not enforced. If you pass non-fixnum arguments, or
12191 the result falls out of range of fixnums, what happens is up to
12192 the implementation. Consider these procedures as the way to
12193 tell your intentions to the compiler for potential optimizations.
12194 @c JP
12195 このモジュールの手続きはfixnumの範囲でしか動作を定義されていませんが、
12196 それを強制するのではないことに注意してください。fixnumでない引数を
12197 渡したり、結果がfixnumの範囲外になった場合に何が起きるかは
12198 処理系依存とされています。これらの手続きは、プログラマがその意図を
12199 コンパイラに伝えて最適化を期待するためのものと考えると良いでしょう。
12200 @c COMMON
12201
12202 @c EN
12203 In the current Gauche architecture,
12204 generic numeric operators are just as efficient,
12205 so most procedures provided in this module are aliases to corresponding
12206 operators. However, we might employ some optimizations in future
12207 versions.
12208 @c JP
12209 現在のGaucheのアーキテクチャでは一般的な数値計算が効率よく実行できるようになっているので、
12210 これらの手続きは対応する手続きの単なる別名になっています。
12211 将来は、fixnum特有の最適化を導入するかもしれません。
12212 @c COMMON
12213
12214 @c EN
12215 The procedure @code{fixnum?} is built-in, and
12216 not explained here. @xref{Numerical predicates}.
12217 @c JP
12218 手続き@code{fixnum?}は組み込みなのでここでは説明しません。
12219 @ref{Numerical predicates}を参照してください。
12220 @c COMMON
12221 @end deftp
12222
12223 @defvar fx-width
12224 [R7RS fixnum]
12225 @c MOD scheme.fixnum
12226 @c EN
12227 A variable bound to an exact positive integer @var{w}, where @var{w}
12228 is the greatest number such that exact integers between
12229 @code{2^(w-1) - 1} and @code{-2^(w-1)} are all fixnums.
12230 This value is the same as the built-in procedure @code{fixnum-width}
12231 returns (@pxref{Arithmetics}).
12232
12233 In Gauche, it is usually @code{30} for 32bit platforms, and @code{62} for
12234 64bit platforms.
12235 @c JP
12236 @code{2^(w-1) - 1}から@code{-2^(w-1)}までの正確な整数が全てfixnumであるような
12237 最大の正整数@code{w}に束縛された変数です。
12238 組み込み手続き@code{fixnum-width}が返す値と同じです。
12239 (@ref{Arithmetics}参照)。
12240
12241 Gaucheでは、これは通常32ビット環境で@code{30}、64ビット環境で@code{62}です。
12242 @c COMMON
12243 @end defvar
12244
12245 @defvar fx-greatest
12246 @defvarx fx-least
12247 [R7RS fixnum]
12248 @c MOD scheme.fixnum
12249 @c EN
12250 Variables bound to the greatest fixnum and the least fixnum.
12251 They are the same as the built-in procedures
12252 @code{greatest-fixnum} and @code{least-fixnum} return, respectively
12253 (@pxref{Arithmetics}).
12254
12255 The following table shows the typical values on Gauche:
12256 @c JP
12257 最大および最小のfixnumに束縛された変数です。これらの値は
12258 組み込み手続き@code{greatest-fixnum}および@code{least-fixnum}が
12259 返すものと同じです(@ref{Arithmetics}参照)。
12260
12261 次の表はGaucheでの典型的な値を示します。
12262 @c COMMON
12263
12264 @multitable {Platform} {2,305,843,009,213,693,951} {-2,305,843,009,213,693,951}
12265 @headitem Platform @tab @code{fx-greatest} @tab @code{fx-least}
12266 @item 32bit @tab 536,870,911 @tab -536,870,912
12267 @item 64bit @tab 2,305,843,009,213,693,951 @tab -2,305,843,009,213,693,952
12268 @end multitable
12269 @end defvar
12270
12271 @defun fx=? i @dots{}
12272 @defunx fx<? i @dots{}
12273 @defunx fx<=? i @dots{}
12274 @defunx fx>? i @dots{}
12275 @defunx fx>=? i @dots{}
12276 [R7RS fixnum]
12277 @c MOD scheme.fixnum
12278 @c EN
12279 These are equivalent to built-in @code{=}, @code{<}, @code{<=},
12280 @code{>} and @code{>=}, except that you should use these only for fixnums.
12281 @c JP
12282 これらは、fixnumのみに適用しなければならないことを除き、組み込みの
12283 @code{=}、@code{<}、@code{<=}、@code{>}、@code{>=}と同じです。
12284 @c COMMON
12285 @end defun
12286
12287 @defun fxzero? i
12288 @defunx fxpositive? i
12289 @defunx fxnegative? i
12290 @defunx fxodd? i
12291 @defunx fxeven? i
12292 [R7RS fixnum]
12293 @c MOD scheme.fixnum
12294 @c EN
12295 These are equivalent to built-in @code{zero?}, @code{positive?},
12296 @code{negative?}, @code{odd?} and @code{even?},
12297 except that you should use these only for fixnums.
12298 @c JP
12299 これらは、fixnumのみに適用しなければならないことを除き、組み込みの
12300 @code{zero?}、@code{positive?}、@code{negative?}、@code{odd?}、@code{even?}と同じです。
12301 @c COMMON
12302 @end defun
12303
12304 @defun fxmax i j @dots{}
12305 @defunx fxmin i j @dots{}
12306 [R7RS fixnum]
12307 @c MOD scheme.fixnum
12308 @c EN
12309 These are equivalent to built-in @code{max} and @code{min},
12310 except that you should use these only for fixnums.
12311 @c JP
12312 これらは、fixnumのみに適用しなければならないことを除き、組み込みの
12313 @code{max}および@code{min}と同じです。
12314 @c COMMON
12315 @end defun
12316
12317 @defun fx+ i j
12318 @defunx fx- i j
12319 @defunx fx* i j
12320 [R7RS fixnum]
12321 @c MOD scheme.fixnum
12322 @c EN
12323 These are equivalent to built-in @code{+}, @code{-}
12324 and @code{*},
12325 except that these take exactly two arguments, and
12326 you should use these only for fixnums and
12327 when the result fits within fixnum range.
12328 @c JP
12329 これらは、常に2つの引数を取ること、
12330 fixnumのみに適用しなければならないこと、
12331 そして結果がfixnumの範囲に収まる場合だけに使わなければならないことを除き、
12332 組み込みの@code{+}、@code{-}、@code{*}と同じです。
12333 @c COMMON
12334 @end defun
12335
12336 @defun fxneg i
12337 [R7RS fixnum]
12338 @c MOD scheme.fixnum
12339 @c EN
12340 This is equivalent to single-argument @code{-},
12341 except that you should use this only for fixnums and
12342 when the result fits within fixnum range.
12343 @c JP
12344 これは、fixnumのみに適用しなければならないこと、
12345 そして結果がfixnumの範囲に収まる場合だけに使わなければならないことを除き、
12346 組み込みの単項@code{-}と同じです。
12347 @c COMMON
12348 @end defun
12349
12350 @defun fxquotient i j
12351 @defunx fxremainder i j
12352 @defunx fxabs i
12353 @defunx fxsquare i
12354 [R7RS fixnum]
12355 @c MOD scheme.fixnum
12356 @c EN
12357 These are equivalent to built-in @code{quotient}, @code{remainder},
12358 @code{abs} and @code{square},
12359 except that you should use these only for fixnums and
12360 when the result fits within fixnum range.
12361 @c JP
12362 これらは、fixnumのみに適用しなければならないこと、
12363 そして結果がfixnumの範囲に収まる場合だけに使わなければならないことを除き、
12364 組み込みの@code{quotient}、@code{remainder}、@code{abs}、@code{square}と
12365 同じです。
12366 @c COMMON
12367 @end defun
12368
12369 @defun fxsqrt i
12370 [R7RS fixnum]
12371 @c MOD scheme.fixnum
12372 @c EN
12373 This is equivalent to @code{exact-integer-sqrt} (not @code{sqrt}),
12374 except that you should use it only for fixnums.
12375 @xref{Arithmetics}.
12376 @c JP
12377 これらは、fixnumのみに適用しなければならないことを除き、
12378 @code{exact-integer-sqrt}と同じです。@code{sqrt}ではありません。
12379 @ref{Arithmetics}参照。
12380 @c COMMON
12381 @end defun
12382
12383 @defun fx+/carry i j k
12384 @defunx fx-/carry i j k
12385 @defunx fx*/carry i j k
12386 [R7RS fixnum]
12387 @c MOD scheme.fixnum
12388 @c EN
12389 These calculates @code{(+ i j k)}, @code{(- i j k)} and @code{(+ (* i j) k)},
12390 respectively, then split the result to the remainder value @code{R}
12391 in the fixnum range, and spilled value @code{Q}, and return those values.
12392 That is,
12393 @code{(+ (* Q (expt 2 fx-width)) R)} is the result of above calculations.
12394 Both @code{Q} and @code{R} fits in the fixnum range, and
12395 @code{- 2^(w-1) <= R < 2^(w-1)}, where @code{w} is @code{fx-width}.
12396 @c JP
12397 これらはそれぞれ、まず
12398 @code{(+ i j k)}、@code{(- i j k)}、@code{(+ (* i j) k)}を計算し、
12399 その結果をfixnumの範囲内に収まる剰余@code{R}と、溢れ@code{Q}に分割して
12400 2つの値として返します。
12401 すなわち、@code{(+ (* Q (expt 2 fx-width)) R)}が上記計算と一致します。
12402 @code{Q}と@code{R}は常にfixnumの範囲内であり、また@code{R}は
12403 @code{- 2^(w-1) <= R < 2^(w-1)}を満たします。ただし@code{w}は
12404 @code{fx-width}です。
12405 @c COMMON
12406
12407 @example
12408 (fx*/carry 1845917459 19475917581 4735374)
12409 @result{} -942551854601421179 @r{and} 8
12410
12411 (+ (* 8 (expt 2 fx-width)) -942551854601421179)
12412 @result{} 35950936292817682053
12413
12414 (+ (* 1845917459 19475917581) 4735374)
12415 @result{} 35950936292817682053
12416 @end example
12417
12418 @c EN
12419 These are primitives to implement extended-precision
12420 integer arithmetic on top of fixnum operations. In Gauche, however,
12421 you can just use built-in bignums. We provide these for the compatibility.
12422 @c JP
12423 これらは拡張精度整数演算をfixnum手続き上に効率よく実装するためのプリミティブです。
12424 ただ、Gaucheでは必要ならbignumを使えば良いので、これらは単に互換性のために提供しています。
12425 @c COMMON
12426 @end defun
12427
12428 @defun fxnot i
12429 @defunx fxand i @dots{}
12430 @defunx fxior i @dots{}
12431 @defunx fxxor i @dots{}
12432 @defunx fxarithmetic-shift i count
12433 @defunx fxlength i
12434 @defunx fxbit-count i
12435 @defunx fxcopy-bit index i boolean
12436 @defunx fxbit-set? index i
12437 @defunx fxbit-field i start end
12438 @defunx fxfirst-set-bit i
12439 [R7RS fixnum]
12440 @c MOD scheme.fixnum
12441 @c EN
12442 These are equivalent to @code{lognot}, @code{logand},
12443 @code{logior}, @code{logxor}, @code{ash}, @code{integer-length},
12444 @code{logcount},
12445 @code{copy-bit}, @code{logbit?}, @code{bit-field},
12446 and @code{twos-exponent-factor} respectively,
12447 except that you should use these only for fixnums.
12448 @xref{Basic bitwise operations}.
12449 @c JP
12450 これらはfixnumのみに適用しなければならないことを除き、
12451 組み込みの@code{lognot}、 @code{logand}、
12452 @code{logior}、 @code{logxor}、 @code{ash}、 @code{integer-length}、
12453 @code{logcount}、
12454 @code{copy-bit}、 @code{logbit?}、 @code{bit-field}、
12455 @code{twos-exponent-factor}とそれぞれ同じです。
12456 詳しくは@ref{Basic bitwise operations}参照。
12457 @c COMMON
12458 @end defun
12459
12460 @defun fxif mask i j
12461 @defunx fxbit-field-rotate i start end
12462 @defunx fxbit-field-rotate i start end
12463 [R7RS fixnum]
12464 @c MOD scheme.fixnum
12465 @c EN
12466 These are equivalent to SRFI-60's
12467 @code{bitwise-if}, @code{rotate-bit-field} and
12468 @code{reverse-bit-field},
12469 except that you should use these only for fixnums.
12470 @xref{Integers as bits}.
12471 @c JP
12472 これらはfixnumのみに適用しなければならないことを除き、
12473 SRFI-60の@code{bitwise-if}、@code{rotate-bit-field}、
12474 @code{reverse-bit-field}と同じです。
12475 @ref{Integers as bits}参照。
12476 @c COMMON
12477 @end defun
12478
12479
12480 @c ----------------------------------------------------------------------
12481 @node R7RS flonum, R7RS bytevectors, R7RS fixnum, R7RS large
12482 @subsection @code{scheme.flonum} - R7RS flonum
12483 @c NODE R7RS flonum, @code{scheme.flonum} - R7RS flonum
12484
12485 @deftp {Module} scheme.flonum
12486 @mdindex scheme.flonum
12487 @c EN
12488 This module provides a set of flonum-specific operations.
12489 Originally defined as SRFI-144.
12490
12491 In Gauche, a flonum is an IEEE 754 double-precision floating point number.
12492 @c JP
12493 このモジュールはflonumに特化した操作を提供します。
12494 SRFI-144として制定されました。
12495
12496 Gaucheでは、flonumはIEEE754倍精度浮動小数点数です。
12497 @c COMMON
12498
12499 @c EN
12500 Note that these procedures are defined only to work on flonums,
12501 but it is not enforced. If you pass non-flonum arguments,
12502 the result is undefined.
12503 Consider these procedures as the way to
12504 tell your intentions to the compiler for potential optimizations.
12505 @c JP
12506 このモジュールの手続きはflonumの範囲でしか動作を定義されていませんが、
12507 それを強制するのではないことに注意してください。flonumでない引数を
12508 渡した場合の動作は未定義です。これらの手続きは、プログラマがその意図を
12509 コンパイラに伝えて最適化を期待するためのものと考えると良いでしょう。
12510 @c COMMON
12511
12512 @c EN
12513 In the current Gauche architecture,
12514 generic numeric operators are just as efficient,
12515 so most procedures provided in this module are aliases to corresponding
12516 operators. However, we might employ some optimizations in future
12517 versions.
12518 @c JP
12519 現在のGaucheのアーキテクチャでは一般的な数値計算が効率よく実行できるようになっているので、
12520 これらの手続きは対応する手続きの単なる別名になっています。
12521 将来は、flonum特有の最適化を導入するかもしれません。
12522 @c COMMON
12523
12524 @c EN
12525 The procedure @code{flonum?} is built-in, and
12526 not explained here. @xref{Numerical predicates}.
12527 @c JP
12528 手続き@code{flonum?}は組み込みなのでここでは説明しません。
12529 @ref{Numerical predicates}を参照してください。
12530 @c COMMON
12531 @end deftp
12532
12533 @c EN
12534 @subheading Constants
12535 @c JP
12536 @subheading 定数
12537 @c COMMON
12538
12539 We also have a few constants in @code{math.const} module
12540 (@pxref{Mathematical constants}).
12541
12542 @defvr {Constant} fl-e
12543 [R7RS flonum]
12544 @c MOD scheme.flonum
12545 @c EN
12546 The base of natural logarithm e.
12547
12548 Gauche also has a constant @code{e} in @code{math.const}
12549 (@pxref{Mathematical constants}).
12550 @c JP
12551 自然対数の低e。
12552
12553 Gaucheの@code{math.const}モジュールにも定数eがあります
12554 (@ref{Mathematical constants}参照)。
12555 @c COMMON
12556 @end defvr
12557
12558 @defvr {Constant} fl-1/e
12559 [R7RS flonum]
12560 @c MOD scheme.flonum
12561 @code{(/ e)}.
12562 @end defvr
12563
12564
12565 @defvr {Constant} fl-e-2
12566 [R7RS flonum]
12567 @c MOD scheme.flonum
12568 @code{(square e)}.
12569 @end defvr
12570
12571 @defvr {Constant} fl-e-pi/4
12572 [R7RS flonum]
12573 @c MOD scheme.flonum
12574 @code{(expt e (/ pi 4))}.
12575 @end defvr
12576
12577 @defvr {Constant} fl-log2-e
12578 [R7RS flonum]
12579 @c MOD scheme.flonum
12580 @c EN
12581 @code{(log2 e)}. (Same as @code{(/ (log 2))}).
12582 @c JP
12583 @code{(log2 e)} (@code{(/ (log 2))}と同じ)
12584 @c COMMON
12585 @end defvr
12586
12587 @defvr {Constant} fl-log10-e
12588 [R7RS flonum]
12589 @c MOD scheme.flonum
12590 @c EN
12591 @code{(log10 e)}. (Same as @code{(/ (log 10))}).
12592 @c JP
12593 @code{(log10 e)} (@code{(/ (log 10))}と同じ)
12594 @c COMMON
12595 @end defvr
12596
12597 @defvr {Constant} fl-log-2
12598 [R7RS flonum]
12599 @c MOD scheme.flonum
12600 @code{(log 2)}.
12601 @end defvr
12602
12603 @defvr {Constant} fl-1/log-2
12604 [R7RS flonum]
12605 @c MOD scheme.flonum
12606 @code{(/ (log 2))}. (Same as @code{(log2 e)}).
12607 @end defvr
12608
12609 @defvr {Constant} fl-log-3
12610 [R7RS flonum]
12611 @c MOD scheme.flonum
12612 @code{(log 3)}.
12613 @end defvr
12614
12615 @defvr {Constant} fl-log-pi
12616 [R7RS flonum]
12617 @c MOD scheme.flonum
12618 @code{(log pi)}.
12619 @end defvr
12620
12621 @defvr {Constant} fl-log-10
12622 [R7RS flonum]
12623 @c MOD scheme.flonum
12624 @code{(log 10)}.
12625 @end defvr
12626
12627 @defvr {Constant} fl-1/log-10
12628 [R7RS flonum]
12629 @c MOD scheme.flonum
12630 @c EN
12631 @code{(/ (log 10))}. (Same as @code{(log10 e)}).
12632 @c JP
12633 @code{(/ (log 10))} (@code{(log10 e)}と同じ)
12634 @c COMMON
12635 @end defvr
12636
12637 @defvr {Constant} fl-pi
12638 [R7RS flonum]
12639 @c MOD scheme.flonum
12640 @code{pi}.
12641 @end defvr
12642
12643 @defvr {Constant} fl-1/pi
12644 [R7RS flonum]
12645 @c MOD scheme.flonum
12646 @code{(/ pi)}.
12647 @end defvr
12648
12649 @defvr {Constant} fl-2pi
12650 [R7RS flonum]
12651 @c MOD scheme.flonum
12652 @code{(* 2 pi)}.
12653 @end defvr
12654
12655 @defvr {Constant} fl-pi/2
12656 [R7RS flonum]
12657 @c MOD scheme.flonum
12658 @code{(/ pi 2)}.
12659 @end defvr
12660
12661 @defvr {Constant} fl-pi/4
12662 [R7RS flonum]
12663 @c MOD scheme.flonum
12664 @code{(/ pi 4)}.
12665 @end defvr
12666
12667 @defvr {Constant} fl-pi-squared
12668 [R7RS flonum]
12669 @c MOD scheme.flonum
12670 @code{(square pi)}.
12671 @end defvr
12672
12673 @defvr {Constant} fl-degree
12674 [R7RS flonum]
12675 @c MOD scheme.flonum
12676 @code{(/ pi 180)}.
12677 @end defvr
12678
12679 @defvr {Constant} fl-2/pi
12680 [R7RS flonum]
12681 @c MOD scheme.flonum
12682 @code{(/ 2 pi)}.
12683 @end defvr
12684
12685 @defvr {Constant} fl-2/sqrt-pi
12686 [R7RS flonum]
12687 @c MOD scheme.flonum
12688 @code{(/ 2 (sqrt pi))}.
12689 @end defvr
12690
12691 @defvr {Constant} fl-sqrt-2
12692 @code{(sqrt 2)}.
12693 @end defvr
12694
12695 @defvr {Constant} fl-sqrt-3
12696 [R7RS flonum]
12697 @c MOD scheme.flonum
12698 @code{(sqrt 3)}.
12699 @end defvr
12700
12701 @defvr {Constant} fl-sqrt-5
12702 [R7RS flonum]
12703 @c MOD scheme.flonum
12704 @code{(sqrt 5)}.
12705 @end defvr
12706
12707 @defvr {Constant} fl-sqrt-10
12708 [R7RS flonum]
12709 @c MOD scheme.flonum
12710 @code{(sqrt 10)}.
12711 @end defvr
12712
12713 @defvr {Constant} fl-1/sqrt-2
12714 [R7RS flonum]
12715 @c MOD scheme.flonum
12716 @code{(/ (sqrt 2))}.
12717 @end defvr
12718
12719 @defvr {Constant} fl-cbrt-2
12720 [R7RS flonum]
12721 @c MOD scheme.flonum
12722 @code{(expt 2 1/3)}.
12723 @end defvr
12724
12725 @defvr {Constant} fl-cbrt-3
12726 [R7RS flonum]
12727 @c MOD scheme.flonum
12728 @code{(expt 3 1/3)}.
12729 @end defvr
12730
12731 @defvr {Constant} fl-4thrt-2
12732 [R7RS flonum]
12733 @c MOD scheme.flonum
12734 @code{(expt 2 1/4)}.
12735 @end defvr
12736
12737 @defvr {Constant} fl-phi
12738 [R7RS flonum]
12739 @c MOD scheme.flonum
12740 @code{(/ (+ 1 (sqrt 5)) 2)}.
12741 @end defvr
12742
12743 @defvr {Constant} fl-log-phi
12744 [R7RS flonum]
12745 @c MOD scheme.flonum
12746 @code{(log fl-phi)}.
12747 @end defvr
12748
12749 @defvr {Constant} fl-1/log-phi
12750 [R7RS flonum]
12751 @c MOD scheme.flonum
12752 @code{(/ (log fl-phi))}.
12753 @end defvr
12754
12755 @defvr {Constant} fl-euler
12756 [R7RS flonum]
12757 @c MOD scheme.flonum
12758 Euler's constant.
12759 @end defvr
12760
12761 @defvr {Constant} fl-e-euler
12762 [R7RS flonum]
12763 @c MOD scheme.flonum
12764 @code{(exp fl-euler)}
12765 @end defvr
12766
12767 @defvr {Constant} fl-sin-1
12768 [R7RS flonum]
12769 @c MOD scheme.flonum
12770 @code{(sin 1)}
12771 @end defvr
12772
12773 @defvr {Constant} fl-cos-1
12774 [R7RS flonum]
12775 @c MOD scheme.flonum
12776 @code{(cos 1)}
12777 @end defvr
12778
12779 @defvr {Constant} fl-gamma-1/2
12780 [R7RS flonum]
12781 @c MOD scheme.flonum
12782 @code{(gamma 1/2)}
12783 @end defvr
12784
12785 @defvr {Constant} fl-gamma-1/3
12786 [R7RS flonum]
12787 @c MOD scheme.flonum
12788 @code{(gamma 1/3)}
12789 @end defvr
12790
12791 @defvr {Constant} fl-gamma-2/3
12792 [R7RS flonum]
12793 @c MOD scheme.flonum
12794 @code{(gamma 2/3)}
12795 @end defvr
12796
12797 @defvr {Constant} fl-gamma-1/3
12798 [R7RS flonum]
12799 @c MOD scheme.flonum
12800 @code{(gamma 1/3)}
12801 @end defvr
12802
12803 @defvr {Constant} fl-greatest
12804 @defvrx {Constant} fl-least
12805 [R7RS flonum]
12806 @c MOD scheme.flonum
12807 @c EN
12808 Bound to the largest/smallest positive finite flonum.
12809 Those are the same values returned from Gauche's built-in
12810 @code{greatest-positive-flonum} and
12811 @code{least-positive-flonum}, respectively
12812 (@pxref{Numerical comparison}).
12813 @c JP
12814 最大/最小の正の有限な浮動小数点数に束縛されています。
12815 これらは、Gaucheの組み込み手続き
12816 @code{greatest-positive-flonum}および
12817 @code{least-positive-flonum}が返す値とそれぞれ同じです
12818 (@ref{Numerical comparison}参照)。
12819 @c COMMON
12820 @end defvr
12821
12822 @defvr {Constant} fl-epsilon
12823 [R7RS flonum]
12824 @c MOD scheme.flonum
12825 @c EN
12826 The same as @code{(flonum-epsilon)} in Gauche
12827 (@pxref{Numerical comparison}).
12828 @c JP
12829 Gaucheの@code{(flonum-epsilon)}と同じです。
12830 (@ref{Numerical comparison}参照)。
12831 @c COMMON
12832 @end defvr
12833
12834 @defvr {Constant} fl-fast-fl+*
12835 [R7RS flonum]
12836 @c MOD scheme.flonum
12837 @c EN
12838 If this is @code{#t}, @code{(fl+* x y z)} executes as fast as,
12839 or faster than, @code{(fl+ (fl* x y) z)}. If not, @code{#f}.
12840 @c JP
12841 これが@code{#t}を返した場合、@code{(fl+* x y z)}は
12842 @code{(fl+ (fl* x y) z)}と同等の速度、もしくはより速く実行されます。
12843 @c COMMON
12844 @end defvr
12845
12846 @defvr {Constant} fl-integer-exponent-zero
12847 @defvrx {Constant} fl-integer-exponent-nan
12848 [R7RS flonum]
12849 @c MOD scheme.flonum
12850 @c EN
12851 These are exact integer values returned in special occasion
12852 from @code{flinteger-exponent}. The values themselves don't mean
12853 much; they're to be compared with the result of @code{flinteger-exponent}.
12854
12855 If its argument is 0, @code{flinteger-exponent} returns
12856 @code{fl-integer-exponent-zero}. If its argument is @code{+nan.0},
12857 @code{flinteger-exponent} returns @code{fl-integer-exponent-nan}.
12858 @c JP
12859 これらは、@code{flinteger-exponent}が特別な場合に返し得る正確な整数値です。
12860 値そのものに意味はなく、@code{flinteger-exponent}の結果と比較するために使われます。
12861
12862 @code{flinteger-exponent}は引数が0の時@code{fl-integer-exponent-zero}を、
12863 引数が@code{+nan.0}の時@code{fl-integer-exponent-nan}を返します。
12864 @c COMMON
12865 @end defvr
12866
12867 @c EN
12868 @subheading Constructors
12869 @c JP
12870 @subheading コンストラクタ
12871 @c COMMON
12872
12873 @defun flonum number
12874 [R7RS flonum]
12875 @c MOD scheme.flonum
12876 @c EN
12877 Returns a flonum that's equal to or (if there's no equivalent flnoum)
12878 the closest to @var{number}.
12879
12880 If @var{number} is not a real number,
12881 @code{+nan.0} is returned. (Note: SRFI-144 recommends it, but
12882 a conformant implementation may signal an error in such case.
12883 Portable code shouldn't rely on this behavior.)
12884 @c JP
12885 @var{number}と等しいflonum、もしくは等しい値がflonumで表現可能でなければもっとも近い
12886 flonumを返します。
12887
12888 @var{number}が実数でなければ@code{+nan.0}が返されます
12889 (これはSRFI-144で推奨されている動作ですが、処理系によってはエラーを投げても良いことに
12890 なっているので、ポータブルなコードを書くときは注意してください。)
12891 @c COMMON
12892 @end defun
12893
12894 @defun fladjacent x y
12895 [R7RS flonum]
12896 @c MOD scheme.flonum
12897 @c EN
12898 Returns a flonum adjacent to @var{x} in the direction of @var{y}.
12899 If @var{x} = @var{y}, @var{x} is returned.
12900 @c JP
12901 flonum @var{x}から@var{y}の方向に1最小単位だけ進めたflonumを返します。
12902 @var{x} = @var{y}なら、@var{x}そのものが返されます。
12903 @c COMMON
12904
12905 @example
12906 (fladjacent 1.0 2.0) @result{} 1.0000000000000002
12907 (fladjacent 1.0 0.0) @result{} 0.9999999999999999
12908 @end example
12909 @end defun
12910
12911 @defun flcopysign x y
12912 [R7RS flonum]
12913 @c MOD scheme.flonum
12914 @c EN
12915 Returns a flonum whose absolute value is @code{(abs x)} and whose
12916 sign is the sign of @var{y}.
12917 @c JP
12918 絶対値が@code{(abs x)}と同じで、符号が@var{y}と同じであるようなflonumを返します。
12919 @c COMMON
12920 @end defun
12921
12922
12923 @defun make-flonum x n
12924 [R7RS flonum]
12925 @c MOD scheme.flonum
12926 @c EN
12927 Returns a flonum @code{(* @var{x} (expt 2 @var{n}))}. It is the same
12928 as @code{ldexp} (@pxref{Numerical conversions}).
12929 @c JP
12930 @code{(* @var{x} (expt 2 @var{n}))}なるflonumを返します。
12931 Gaucheの@code{ldexp}と同じです (@ref{Numerical conversions}参照)。
12932 @c COMMON
12933 @end defun
12934
12935 @c EN
12936 @subheading Accessors
12937 @c JP
12938 @subheading アクセサ
12939 @c COMMON
12940
12941 @defun flinteger-fraction x
12942 [R7RS flonum]
12943 @c MOD scheme.flonum
12944 @c EN
12945 Returns two flnoums, the integral part of @var{x} and the fractional
12946 part of @var{x}. Same as @code{modf} (@pxref{Numerical conversions}).
12947
12948 If @var{x} is @code{+inf.0}, @code{+inf.0} and @code{0.0} is returned.
12949 If @var{x} is @code{-inf.0}, @code{-inf.0} and @code{-0.0} is returned.
12950 If @var{x} is @code{+nan.0}, @code{+nan.0} and @code{+nan.0} is returned.
12951 (These corner cases are not explicit in SRFI-144, but follows
12952 the POSIX specification of @code{modf}.)
12953 @c JP
12954 flonum @var{x}の整数部と小数部をそれぞれflonumとして返します。
12955 Gaucheの@code{modf}と同じです (@ref{Numerical conversions}参照)。
12956
12957 @var{x}が@code{+inf.0}なら、@code{+inf.0}と@code{0.0}が、
12958 @var{x}が@code{-inf.0}なら、@code{-inf.0}と@code{-0.0}が、
12959 そして@var{x}が@code{+nan.0}なら、@code{+nan.0}と@code{+nan.0}が返されます。
12960 (この動作はSRFI-144では指定されていません。GaucheはPOSIXの@code{modf}の動作に
12961 準じています)。
12962 @c COMMON
12963
12964 @example
12965 (flinteger-fraction fl-pi)
12966 @result{} 3.0 @r{and} 0.14159265358979312
12967 @end example
12968 @end defun
12969
12970 @defun flexponent x
12971 [R7RS flonum]
12972 @c MOD scheme.flonum
12973 @c EN
12974 Returns the exponent part of @var{x} as a flnoum. If @var{x} is
12975 a non-zero finite value, the result is an integer.
12976
12977 If @var{x} is zero, @code{-inf.0} is returned.
12978 If @var{x} is @var{+inf.0} or @code{-inf.0}, @code{+inf.0} is returned.
12979 @c JP
12980 flonum @var{x}の指数部をflonumとして返します。@var{x}がゼロでない有限値なら、
12981 結果は整数です。
12982
12983 @var{x}がゼロなら、@code{-inf.0}が、
12984 @var{x}が無限大なら、@code{+inf.0}が返されます。
12985 @c COMMON
12986
12987 @example
12988 (flexponent 1.0) @result{} 0.0
12989 (flexponent 1024.0) @result{} 10.0
12990 (flexponent 0.01) @result{} -7.0
12991 (flexponent fl-least) @result{} -1074.0
12992 @end example
12993 @end defun
12994
12995 @defun flinteger-exponent x
12996 [R7RS flonum]
12997 @c MOD scheme.flonum
12998 @c EN
12999 Returns the same as @code{flexponent} but as an exact integer.
13000
13001 If @var{x} is zero, the value of @code{fl-integer-exponent-zero} is
13002 returned.
13003 If @var{x} is @var{+inf.0} or @code{-inf.0}, a large
13004 implementation-dependent exact integer (usually it's so large that
13005 @code{(ldexp 1 (flinteger-exponent +inf.0))} becomes @code{+inf.0})
13006 is returned.
13007 If @var{x} is @code{+nan.0}, the value of
13008 @code{fl-integer-exponent-nan} is returned.
13009 @c JP
13010 @code{flexponent}と同様に@var{x}の指数部を返しますが、こちらは正確な整数を返します。
13011
13012 @var{x}がゼロの場合、定数@code{fl-integer-exponent-zero}が返されます。
13013 @var{x}が無限大の場合、非常に大きな正確な整数
13014 (@code{(ldexp 1 (flinteger-exponent +inf.0))}が@code{+inf.0}になるような
13015 値)が返されます。
13016 @var{x}が@code{+nan.0}の場合、定数@code{fl-integer-exponent-nan}が返されます。
13017 @c COMMON
13018 @end defun
13019
13020 @defun flnormalized-fraction-exponent x
13021 [R7RS flonum]
13022 @c MOD scheme.flonum
13023 @c EN
13024 Returns two values, a normalized mantissa of @var{x} with the same sign
13025 as @var{x} as a flonum, and an exact integer exponent of @var{x}. If it returns
13026 a value @var{y} and @var{n}, @code{x = (* y (expt 2 n))} and
13027 @code{x = (ldexp y n)}.
13028 This is the same as @code{frexp}
13029 (@pxref{Numerical conversions}).
13030 @c JP
13031 flonum @var{x}の正規化された仮数部 (符号は@var{x}と同じ)をflonumで、
13032 および@var{x}の指数部を正確な整数で2つの返り値として返します。
13033 それらを@var{y}と@var{n}とすれば、@code{x = (* y (expt 2 n))}であり、
13034 @code{x = (ldexp y n)}となります。
13035 この手続きはGaucheの@code{frexp}と同じです(@ref{Numerical conversions}参照)。
13036 @c COMMON
13037
13038 @c EN
13039 If @var{x} is non-zero finite value, the first value
13040 falls between 0.5 (inclusive) and 1.0 (exclusive).
13041 The corner cases are not explicit in SRFI-144, but Gauche follows
13042 @code{frexp}: If @var{x} is (minus) zero, it returns
13043 (minus) zero and 0; if @var{x} is infinity, it returns
13044 infinity (of the same sign) and 0; if @var{x} is @code{+nan.0},
13045 it returns @code{+nan.0} and 0.
13046 @c JP
13047 @var{x}がゼロでない有限の値ならば、
13048 最初の返り値は0.5以上で1.0より小さな値になります。
13049 コーナーケースについてはSRFI-144では規程されていませんが、Gaucheは
13050 @code{frexp}の仕様に沿って、次のようにしています。
13051 @var{x}が@code{0.0}(か@code{-0.0})なら、結果は@code{0.0}(か@code{-0.0})と@code{0}。
13052 @var{x}が無限大なら、同じ符号の無限大と@code{0}。
13053 @var{x}が@code{+nan.0}なら、@code{+nan.0}と@code{0}。
13054 @c COMMON
13055
13056 @example
13057 (flnormalized-fraction-exponent 12345.6789)
13058 @result{} 0.7535204406738282 @r{and} 14
13059 (make-flonum 0.7535204406738282 14)
13060 @result{} 12345.6789
13061 @end example
13062 @end defun
13063
13064 @defun flsign-bit x
13065 [R7RS flonum]
13066 @c MOD scheme.flonum
13067 @c EN
13068 Returns 0 if @var{x} is positive or @var{0.0},
13069 and 1 if it is negative (including @code{-0.0}).
13070 @code{(flsign-bit +nan.0)} is implementation-dependent.
13071
13072 There's also @code{flsgn}, if you need sign instead of a bit value.
13073 @c JP
13074 @var{x}が正もしくは@code{0.0}なら@code{0}を、
13075 負もしくは@code{-0.0}なら@code{1}を返します。
13076 @code{(flsign-bit +nan.0)}は実装依存です。
13077
13078 ビット値でなく符号が欲しい場合、@code{flsgn}も使えます。
13079 @c COMMON
13080 @end defun
13081
13082 @c EN
13083 @subheading Predicates
13084 @c JP
13085 @subheading 述語
13086 @c COMMON
13087
13088 @c EN
13089 (Note: @code{flonum?} is built-in; @pxref{Numerical predicates}).
13090 @c JP
13091 (註: @code{flonum?}は組み込みです。@ref{Numerical predicates}参照)。
13092 @c COMMON
13093
13094 @defun fl=? x y z @dots{}
13095 @defunx fl<? x y z @dots{}
13096 @defunx fl>? x y z @dots{}
13097 @defunx fl<=? x y z @dots{}
13098 @defunx fl>=? x y z @dots{}
13099 [R7RS flonum]
13100 @c MOD scheme.flonum
13101 @c EN
13102 Flonum specific version of numerical comparison predicates
13103 @code{=}, @code{<}, @code{>}, @code{<=} and @code{>=}, respectively.
13104
13105 Currently these are just an alias of the generic numerical comparison
13106 predicates; hence they don't reject when you pass non-flonum
13107 arguments, but doing so is not portable. These are to give
13108 compilers hints that you are passing flonums so that it can optimize.
13109
13110 Note that @code{-0.0} and @code{0.0} are the same in terms of
13111 these predicates, e.g. @code{(fl<? -0.0 0.0)} is @code{#f}.
13112
13113 If a @code{+nan.0} is passed to any of the arguments, these predicates returns
13114 @code{#f}.
13115 @c JP
13116 flonum専用の比較関数です。それぞれ
13117 @code{=}、@code{<}、@code{>}、@code{<=}、@code{>=}に対応します。
13118
13119 今のところGaucheではこれらは単に汎用の比較関数の別名となっています。
13120 なのでflonum以外の数値が渡されても動作しますが、そうすることはポータブルではありません。
13121 これらの関数の意図は、将来的にコンパイラに型についてのヒントを与え
13122 最適化を可能にすることです。
13123
13124 @code{-0.0}と@code{0.0}は数値比較においては等しいものと扱われることに
13125 注意してください。@code{(fl<? -0.0 0.0)}は@code{#f}になります。
13126
13127 引数に@code{+nan.0}がひとつでもあれば、結果は常に@code{#f}となります。
13128 @c COMMON
13129 @end defun
13130
13131 @defun flunordered? x y
13132 [R7RS flonum]
13133 @c MOD scheme.flonum
13134 @c EN
13135 Returns @code{#t} iff at least one of @var{x} or @var{y} is
13136 a @code{+nan.0}.
13137 @c JP
13138 @var{x}と@var{y}の少なくとも一方が@code{+nan.0}であれば@code{#t}を、
13139 そうでなければ@code{#f}を返します。
13140 @c COMMON
13141 @end defun
13142
13143 @defun flinteger? x
13144 [R7RS flonum]
13145 @c MOD scheme.flonum
13146 @c EN
13147 Returns @code{#t} if @var{x} is an integral flonum,
13148 @code{#f} otherwise.
13149 @c JP
13150 @var{x}が整数のflonumであれば@code{#t}を、
13151 そうでなければ@code{#f}を返します。
13152 @c COMMON
13153 @end defun
13154
13155 @defun flzero? x
13156 @defunx flpositive? x
13157 @defunx flnevative? x
13158 [R7RS flonum]
13159 @c MOD scheme.flonum
13160 @c EN
13161 Flonum-specific version of @code{zero?}, @code{positive?} and @code{negative?}.
13162 Note that @code{(flnegative? -0.0)} is @code{#f}.
13163 You need @code{flsign-bit} or @code{flsgn} to
13164 distinguish negative zero from zero.
13165 @c JP
13166 flonum専用の@code{zero?}、@code{positive?}、@code{negative?}です。
13167 @code{(flnegative? -0.0)}は@code{#f}であることに注意してください。
13168 負のゼロを普通のゼロと見分けるには@code{flsign-bit}や@code{flsgn}を使います。
13169 @c COMMON
13170 @end defun
13171
13172 @defun flodd? x
13173 @defunx fleven? x
13174 [R7RS flonum]
13175 @c MOD scheme.flonum
13176 @c EN
13177 Flonum-specific version of @code{odd?} and @code{even?}. An error is thrown
13178 if @var{x} is not an integer.
13179 @c JP
13180 flonum専用の@code{odd?}と@code{even?}です。
13181 @var{x}が整数でなければエラーが投げられます。
13182 @c COMMON
13183 @end defun
13184
13185 @defun flfinite? x
13186 @defunx flinfinite? x
13187 @defunx flnan? x
13188 [R7RS flonum]
13189 @c MOD scheme.flonum
13190 @c EN
13191 Flonum-specific version of @code{finite?}, @code{infinite?} and
13192 @code{nan?} (@pxref{Numerical predicates}).
13193 @c JP
13194 それぞれflonum専用の@code{finite?}、@code{infinite?}、
13195 @code{nan?}です (@ref{Numerical predicates}参照)。
13196 @c COMMON
13197 @end defun
13198
13199 @defun flnormalized? x
13200 @defunx fldenormalized? x
13201 [R7RS flonum]
13202 @c MOD scheme.flonum
13203 @c EN
13204 Returns @code{#t} iff @var{x} is a normalized/denormalized flonum,
13205 respectively.
13206 @c JP
13207 それぞれ、@var{x}が正規化浮動小数点数、非正規化浮動小数点数の場合に
13208 @code{#t}を返し、そうでなければ@code{#f}を返します。
13209 @c COMMON
13210 @end defun
13211
13212 @c EN
13213 @subheading Arithmetic
13214 @c JP
13215 @subheading 演算
13216 @c COMMON
13217
13218 @defun flmax x @dots{}
13219 @defunx flmin x @dots{}
13220 [R7RS flonum]
13221 @c MOD scheme.flonum
13222 @c EN
13223 Flonum-specific version of @code{min} and @code{max}, except that
13224 these can take no arguments, in which case @code{-inf.0}
13225 and @code{+inf.0} are returned, respectively.
13226
13227 Note that we don't check whether the arguments are flonums or not,
13228 but passing non-flonums are not portable.
13229 @c JP
13230 flonum専用の@code{min}と@code{max}です。汎用の@code{min}、@code{max}と
13231 異なり、引数がゼロ個でもエラーにならず、それぞれ@code{-inf.0}と
13232 @code{+inf.0}が返されます。
13233
13234 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13235 ポータブルではありません。
13236 @c COMMON
13237 @end defun
13238
13239 @defun fl+ x @dots{}
13240 @defunx fl* x @dots{}
13241 [R7RS flonum]
13242 @c MOD scheme.flonum
13243 @c EN
13244 Flonum-specific version of @code{+.} and @code{*.}
13245 (@pxref{Arithmetics}).
13246
13247 Note that we don't check whether the arguments are flonums or not,
13248 but passing non-flonums is not portable.
13249 @c JP
13250 flonum専用の@code{+.}と@code{-.}です (@ref{Arithmetics}参照)。
13251
13252 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13253 ポータブルではありません。
13254 @c COMMON
13255 @end defun
13256
13257 @defun fl+* x y z
13258 [R7RS flonum]
13259 @c MOD scheme.flonum
13260 @c EN
13261 Returns @code{(+ (* x y) z)}, but (potentially) faster, and more accurately.
13262 It calls C99 @code{fma} function internally. ``More accurately'' means
13263 that calculation is done in a single step, with rounding once at the end.
13264
13265 Note: As of release of 0.9.8, MinGW implementation of @code{fma} seems
13266 to produce slightly off value occasionally, as if it is calculated
13267 with the two steps (rounding after multiplication).
13268 @c JP
13269 @code{(+ (* x y) z)}の値を返しますが、
13270 プラットフォームによってはより速く正確な結果を返します。
13271 Gaucheは内部的にはC99の@code{fma}を呼んでいます。
13272 「より正確」というのは、乗算と加算が一度に行われ、丸めが最後に1回だけ起きることを
13273 指します。
13274
13275 註: 0.9.8リリース時点で、MinGWの@code{fma}実装は
13276 乗算と加算それぞれに丸めが入るようになっているので、
13277 しばしばわずかにずれた結果を返します。
13278 @c COMMON
13279 @end defun
13280
13281 @defun fl- x y @dots{}
13282 @defunx fl- x y @dots{}
13283 [R7RS flonum]
13284 @c MOD scheme.flonum
13285 @c EN
13286 Flonum-specific version of @code{-.} and @code{/.}
13287 (@pxref{Arithmetics}).
13288
13289 Note that we don't check whether the arguments are flonums or not,
13290 but passing non-flonums is not portable.
13291 @c JP
13292 flonum専用の@code{-.}と@code{/.}です (@ref{Arithmetics}参照)。
13293
13294 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13295 ポータブルではありません。
13296 @c COMMON
13297 @end defun
13298
13299 @defun flabs x
13300 [R7RS flonum]
13301 @c MOD scheme.flonum
13302 @c EN
13303 Flonum-specific version of @code{abs}
13304 (@pxref{Arithmetics}).
13305
13306 Note that we don't check whether the argument is a flonum or not,
13307 but passing non-flonum is not portable.
13308 @c JP
13309 flonum専用の@code{abs}です (@ref{Arithmetics}参照)。
13310
13311 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13312 ポータブルではありません。
13313 @c COMMON
13314 @end defun
13315
13316 @defun flabsdiff x y
13317 [R7RS flonum]
13318 @c MOD scheme.flonum
13319 @c EN
13320 Returns @code{(abs (- x y))}.
13321
13322 Note that we don't check whether the arguments are flonums or not,
13323 but passing non-flonum is not portable.
13324 @c JP
13325 @code{(abs (- x y))}を返します。
13326
13327 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13328 ポータブルではありません。
13329 @c COMMON
13330 @end defun
13331
13332 @defun flposdiff
13333 [R7RS flonum]
13334 @c MOD scheme.flonum
13335 @c EN
13336 Returns @code{(max (- x y) 0)}.
13337
13338 Note that we don't check whether the arguments are flonums or not,
13339 but passing non-flonum is not portable.
13340 @c JP
13341 @code{(max (- x y) 0)}を返します。
13342
13343 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13344 ポータブルではありません。
13345 @c COMMON
13346 @end defun
13347
13348 @defun flsgn x
13349 [R7RS flonum]
13350 @c MOD scheme.flonum
13351 @c EN
13352 Returns @code{1.0} if @var{x}'s sign bit is 0 (zero or positive),
13353 @code{-1.0} if it's 1 (negative). Same as @code{(flcopysign 1.0 x)},
13354 or @code{(if (zero? (flsign-bit x)) 1.0 -1.0)}.
13355 Note that @code{(flsgn 0.0)} is @code{1.0}, while
13356 @code{(flsgn -0.0)} is @code{-1.0}. The result of
13357 passing @code{+nan.0} is implementation-dependent, reflecting
13358 the sign bit of underlying representation; it returns either @code{1.0} or
13359 @code{-1.0} but you can't count on which.
13360
13361 To extract the sign bit, instead of obtaining a signed flonum,
13362 you can use @code{flsign-bit}.
13363 @c JP
13364 @var{x}の符号ビットが0 (ゼロまたは正)なら@code{1.0}を、
13365 1 (負および負のゼロ)の場合は@code{-1.0}を返します。
13366 @code{(flcopysign 1.0 x)}や@code{(if (zero? (flsign-bit x)) 1.0 -1.0)}
13367 と考えることもできます。
13368 @code{(flsgn 0.0)}の結果は@code{1.0}、
13369 @code{(flsng -0.0)}の結果は@code{-1.0}です。
13370 @code{+nan.0}を渡した場合の結果は実装上NaNの符号ビットがどうなっているかに
13371 よるので、結果は@code{1.0}か@code{-1.0}かのいずれかになりますが、
13372 どちらになるかはっきりしたことは言えません。
13373
13374 符号つきflonumではなく符号ビットそのものを取り出すには@code{flsign-bit}が使えます。
13375 @c COMMON
13376 @end defun
13377
13378 @defun flnumerator x
13379 @defunx fldenominator x
13380 [R7RS flonum]
13381 @c MOD scheme.flonum
13382 @c EN
13383 Flonum-specific version of @code{numerator} and @code{denominator}
13384 (@pxref{Arithmetics}).
13385
13386 For infinity and zero, denominator is 1.0.
13387
13388 Note that we don't check whether the arguments are flonums or not,
13389 but passing non-flonum is not portable.
13390 @c JP
13391 flonum専用の@code{numerator}と@code{denominator}です
13392 (@ref{Arithmetics}参照)。
13393
13394 無限大とゼロのdenominatorは@code{1.0}になります。
13395
13396 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13397 ポータブルではありません。
13398 @c COMMON
13399 @end defun
13400
13401 @defun flfloor x
13402 @defunx flceiling x
13403 @defunx flround x
13404 @defunx fltruncate x
13405 [R7RS flonum]
13406 @c MOD scheme.flonum
13407 @c EN
13408 Flonum-specific version of @code{floor}, @code{ceiling},
13409 @code{round} and @code{truncate}
13410 (@pxref{Arithmetics}).
13411
13412 Note that we don't check whether the arguments are flonums or not,
13413 but passing non-flonum is not portable.
13414 @c JP
13415 flonum専用の@code{floor}、@code{ceiling}、@code{round}、@code{truncate}です
13416 (@ref{Arithmetics}参照)。
13417
13418 引数がflonumかどうかはチェックしていませんが、flonum以外の引数を渡すことは
13419 ポータブルではありません。
13420 @c COMMON
13421 @end defun
13422
13423 @c EN
13424 @subheading Exponents and logarithms
13425 @c JP
13426 @subheading 指数対数関数
13427 @c COMMON
13428
13429 @defun flexp x
13430 [R7RS flonum]
13431 @c MOD scheme.flonum
13432 @c EN
13433 Flonum-specific version of @code{exp} (@pxref{Arithmetics}).
13434 Returns @code{(expt fl-e x)}.
13435 @c JP
13436 flonum専用の@code{exp}です (@ref{Arithmetics}参照)。
13437 @code{(expt fl-e x)}を返します。
13438 @c COMMON
13439 @end defun
13440
13441 @defun flexp2 x
13442 [R7RS flonum]
13443 @c MOD scheme.flonum
13444 @c EN
13445 Returns @code{(expt 2 x)}
13446 @c JP
13447 @code{(expt 2 x)}を返します。
13448 @c COMMON
13449 @end defun
13450
13451 @defun flexp-1 x
13452 [R7RS flonum]
13453 @c MOD scheme.flonum
13454 @c EN
13455 Returns @code{(- 1 (expt fl-e x))}, but is much more accurate
13456 when @var{x} is small. We call C's @code{expm1} internally.
13457 @c JP
13458 @code{(- 1 (expt fl-e x))}を返しますが、@var{x}が小さい場合はより正確です。
13459 内部的にはCの@code{expm1}を呼んでいます。
13460 @c COMMON
13461 @end defun
13462
13463 @defun flsquare x
13464 [R7RS flonum]
13465 @c MOD scheme.flonum
13466 @c EN
13467 Returns @code{(*. x x)}
13468 @c JP
13469 @code{(*. x x)}を返します。
13470 @c COMMON
13471 @end defun
13472
13473 @defun flsqrt x
13474 [R7RS flonum]
13475 @c MOD scheme.flonum
13476 @c EN
13477 Flonum-specific version of @code{sqrt}.
13478 @c JP
13479 flonum専用の@code{sqrt}です。
13480 @c COMMON
13481 @end defun
13482
13483 @defun flcbrt x
13484 [R7RS flonum]
13485 @c MOD scheme.flonum
13486 @c EN
13487 Returns cubic root of a flonum @var{x}.
13488 @c JP
13489 flonum @var{x}の3乗根を返します。
13490 @c COMMON
13491 @end defun
13492
13493 @defun flhypot x y
13494 [R7RS flonum]
13495 @c MOD scheme.flonum
13496 @c EN
13497 Calculates @code{(sqrt (* x x) (* y y))}, with avoiding
13498 overflow or underflow during the intermediate steps.
13499 @c JP
13500 @code{(sqrt (* x x) (* y y))}を計算しますが、
13501 中間結果でオーバーフローやアンダーフローが起きないように配慮されています。
13502 @c COMMON
13503 @end defun
13504
13505 @defun flexpt x y
13506 [R7RS flonum]
13507 @c MOD scheme.flonum
13508 @c EN
13509 Flonum-specific version of @code{expt} (@pxref{Arithmetics}).
13510 @c JP
13511 flonum専用の@code{expt}です(@ref{Arithmetics}参照)。
13512 @c COMMON
13513 @end defun
13514
13515 @defun fllog x
13516 [R7RS flonum]
13517 @c MOD scheme.flonum
13518 @c EN
13519 Flonum-specific version of @code{log} (@pxref{Arithmetics}).
13520 @c JP
13521 flonum専用の@code{log}です(@ref{Arithmetics}参照)。
13522 @c COMMON
13523 @end defun
13524
13525 @defun fllog1+ x
13526 [R7RS flonum]
13527 @c MOD scheme.flonum
13528 @c EN
13529 Returns @code{(log (+ x 1))}, but is more accurate than @code{log}
13530 when @var{x} is near zero.
13531 @c JP
13532 @code{(log (+ x 1))}を返しますが、@var{x}がゼロに近い場合により正確です。
13533 @c COMMON
13534 @end defun
13535
13536 @defun fllog2 x
13537 @defunx fllog10 x
13538 [R7RS flonum]
13539 @c MOD scheme.flonum
13540 @c EN
13541 Returns base-2 and base-10 logarithm of a flonum @var{x}, respectively.
13542 @c JP
13543 flonum @var{x}の2および10を底とする対数を返します。
13544 @c COMMON
13545 @end defun
13546
13547 @defun make-fllog-base x
13548 [R7RS flonum]
13549 @c MOD scheme.flonum
13550 @c EN
13551 Returns a procedure that calculates base-@var{x} logarithm.
13552 An error is signalled if @var{x} isn't a real number greater than 1.0.
13553 @c JP
13554 @var{x}を底とする対数を計算する手続きを返します。@var{x}が1.0より大きい実数でない
13555 場合はエラーが投げられます。
13556 @c COMMON
13557
13558 @example
13559 (define log5 (make-fllog-base 5.0))
13560
13561 (log5 25.0) @result{} 5.0
13562 @end example
13563 @end defun
13564
13565 @c EN
13566 @subheading Trigonometric functions
13567 @c JP
13568 @subheading 三角関数
13569 @c COMMON
13570
13571 @defun flsin x
13572 @defunx flcos x
13573 @defunx fltan x
13574 @defunx flasin x
13575 @defunx flacos x
13576 @defunx flatan x
13577 @defunx flatan y x
13578 @defunx flsinh x
13579 @defunx flcosh x
13580 @defunx fltanh x
13581 @defunx flasinh x
13582 @defunx flacosh x
13583 @defunx flatanh x
13584 [R7RS flonum]
13585 @c MOD scheme.flonum
13586 @c EN
13587 Flonum-specific version of @code{sin}, @code{cos}, @code{tan},
13588 @code{asin}, @code{acos}, @code{sinh}, @code{cosh}, @code{tanh},
13589 @code{asinh}, @code{acosh}, and @code{atanh}, respectively
13590 (@pxref{Arithmetics}).
13591 @c JP
13592 それぞれ、flonum専用の
13593 @code{sin}, @code{cos}, @code{tan},
13594 @code{asin}, @code{acos}, @code{sinh}, @code{cosh}, @code{tanh},
13595 @code{asinh}, @code{acosh}, @code{atanh}です
13596 (@ref{Arithmetics}参照)。
13597 @c COMMON
13598
13599 @c EN
13600 Note that @code{flatan} can take one or two arguments; if two arguments
13601 are passed, it calculates @code{(atan (/ y x)}.
13602 @c JP
13603 @code{flatan}は1つまたは2つの引数を取ります。@code{(flatan y x)}は
13604 @code{(flatan (/ y x))}を計算します (が、より正確です)。
13605 @c COMMON
13606 @end defun
13607
13608 @c EN
13609 @subheading Integer division
13610 @c JP
13611 @subheading 整数除算
13612 @c COMMON
13613
13614 @defun flquotient x y
13615 [R7RS flonum]
13616 @c MOD scheme.flonum
13617 @c EN
13618 Returns @code{(fltruncate (fl/ x y))}.
13619
13620 The result is always integer flonum, but @var{x} and @var{y} doesn't
13621 need to be integers.
13622 @c JP
13623 @code{(fltruncate (fl/ x y))} を返します。
13624
13625 結果は常に整数のflonumになります。引数@var{x}、@var{y}は整数である必要はありません。
13626 @c COMMON
13627
13628 @example
13629 (flquotient 14.0 4.0) @result{} 3.0
13630 (flquotient -14.0 4.0) @result{} -3.0
13631 (flquotient 14.0 2.5) @result{} 5.0
13632 (flquotient -14.2 2.8) @result{} -5.0
13633 @end example
13634 @end defun
13635
13636 @defun flremainder x y
13637 [R7RS flonum]
13638 @c MOD scheme.flonum
13639 @c EN
13640 Returns @code{(- x (* y (flquotient x y)))}.
13641 @c JP
13642 @code{(- x (* y (flquotient x y)))}を返します。
13643 @c COMMON
13644
13645 @example
13646 (flquotient 14.0 4.0) @result{} 2.0
13647 (flquotient -14.0 4.0) @result{} -2.0
13648 (flquotient 14.0 2.5) @result{} 1.5
13649 (flquotient -14.2 2.8) @result{} -0.1999999999999993 ; inexact calculation
13650 @end example
13651 @end defun
13652
13653 @defun flremquo x y
13654 [R7RS flonum]
13655 @c MOD scheme.flonum
13656 @c EN
13657 Returns two values:
13658 @c JP
13659 二つの値を返します:
13660 @c COMMON
13661 @itemize @bullet
13662 @item
13663 @c EN
13664 Remainder of @var{x} divided by @var{y}.
13665 (Same as @code{(flremainder x y)}, but we calculate it in different
13666 routines so the result may differ in a few ulp.
13667 @c JP
13668 @var{x}を@var{y}で割った余り。
13669 (@code{(flremainder x y)}と同じですが、異なる計算方法を使うので
13670 最後のビットで差が出るかもしれません)。
13671 @c COMMON
13672 @item
13673 @c EN
13674 Integer quotient of @var{x} divided by @var{y}, modulo 2^@var{n} (@var{n} >= 3), as
13675 an exact integer. Its sign is the same as @var{x}/@var{y}.
13676 @c JP
13677 2^@var{n} (@var{n} >= 3) を法とする、@var{x}割る@var{y}の商。
13678 正確な整数で、@var{x}/@var{y}と同じ符号を持ちます。
13679 @c COMMON
13680 @end itemize
13681
13682 @c EN
13683 This corresponds to C99's @code{remquo}.
13684 @c JP
13685 これはC99の@code{remquo}に相当します。
13686 @c COMMON
13687
13688 @c EN
13689 This function is useful to reduce the input for the periodic functions
13690 with symmetries.
13691 @c JP
13692 周期関数の入力を対称性を使って絞る時に便利です。
13693 @c COMMON
13694 @end defun
13695
13696
13697 @c EN
13698 @subheading Special functions
13699 @c JP
13700 @subheading 特殊関数
13701 @c COMMON
13702
13703 @defun flgamma x
13704 [R7RS flonum]
13705 @c MOD scheme.flonum
13706 @c EN
13707 Computes the value of gamma function for a flonum @var{x}.
13708 When @var{x} is integer, it is the same as the factorial of @var{x}-1.
13709
13710 This is same as Gauche's built-in @code{gamma} (@pxref{Arithmetics}).
13711 @c JP
13712 flonum @var{x}のガンマ関数を計算します。
13713 @var{x}が整数の時は、@var{x}-1の階乗と一致します。
13714
13715 これはGauche組み込みの@code{gamma}と同じです (@ref{Arithmetics}参照)。
13716 @c COMMON
13717 @end defun
13718
13719 @defun flloggamma x
13720 [R7RS flonum]
13721 @c MOD scheme.flonum
13722 @c EN
13723 Returns two values, @code{(log (abs (flgamma x)))} and the sign of
13724 @code{(flgamma x)} as 1.0 if it is positive and -1.0 if it is negative.
13725 @c JP
13726 @code{(log (abs (flgamma x)))}の値および、@code{(flgamma x)}の符号
13727 (正の場合は1.0、負の場合は-1.0)の二つの値を返します。
13728 @c COMMON
13729
13730 @c EN
13731 The first value is calculated by Gauche's built-in @code{lgamma}
13732 (@pxref{Arithmetics}). It's more accurate than using @code{gamma} then
13733 calling @code{log}. The second value is @code{+nan.0} when
13734 @var{x} is @code{-inf.0} or @code{+nan.0}.
13735 @c JP
13736 最初の値はGauche組み込みの@code{lgamma}で計算されます (@ref{Arithmetics}参照)。
13737 これは@code{gamma}を計算して@code{log}を取るより正確です。
13738 なお、@var{x}が@code{-inf.0}か@code{+nan.0}の場合、二番目の値は@code{+nan.0}になります。
13739 @c COMMON
13740 @end defun
13741
13742 @defun flfirst-bessel n x
13743 [R7RS flonum]
13744 @c MOD scheme.flonum
13745 @c EN
13746 Returns the @var{n}-th order Bessel function of the first kind.
13747 @c JP
13748 @var{n}階の第1種ベッセル関数の値を返します。
13749 @c COMMON
13750 @end defun
13751
13752 @defun flsecond-bessel n x
13753 [R7RS flonum]
13754 @c MOD scheme.flonum
13755 @c EN
13756 Returns the @var{n}-th order Bessel function of the second kind.
13757 @c JP
13758 @var{n}階の第2種ベッセル関数の値を返します。
13759 @c COMMON
13760 @end defun
13761
13762 @defun flerf x
13763 [R7RS flonum]
13764 @c MOD scheme.flonum
13765 @c EN
13766 Returns the error function erf(@var{x}).
13767 @c JP
13768 誤差関数erfです。
13769 @c COMMON
13770 @end defun
13771
13772 @defun flerfc x
13773 [R7RS flonum]
13774 @c MOD scheme.flonum
13775 @c EN
13776 Returns the complementary error function, 1 - erf(@var{x}).
13777 @c JP
13778 1 - erf(@var{x}) を計算します。
13779 @c COMMON
13780 @end defun
13781
13782 @c ----------------------------------------------------------------------
13783 @node R7RS bytevectors, R7RS combinator formatting, R7RS flonum, R7RS large
13784 @subsection @code{scheme.bytevector} - R7RS bytevectors
13785 @c NODE R7RSバイトベクタ, @code{scheme.bytevector} - R7RSバイトベクタ
13786
13787 @deftp {Module} scheme.bytevector
13788 @mdindex scheme.bytevector
13789 @c EN
13790 This module is taken from R6RS (@code{(rnrs bytevectors)} (note
13791 that R7RS uses singular form).
13792
13793 The bytevector in this module is u8vector in Gauche.
13794 @c JP
13795 このモジュールはR6RSの@code{(rnrs bytevectors)}からの輸入です
13796 (R7RSのライブラリ名は単数形であることに注意)。
13797
13798 Gaucheでは「バイトベクタ」はu8vectorです。
13799 @c COMMON
13800
13801 @c EN
13802 The following procedures are the same as in @code{gauche.uvector}.
13803 @xref{Bytevector compatibility}, for the explanations.
13804 @c JP
13805 以下の手続きは@code{gauche.uvector}のものと同じです。
13806 詳しくは@ref{Bytevector compatibility}を参照してください。
13807 @c COMMON
13808
13809 @example
13810 bytevector? make-bytevector bytevector-length
13811 bytevector=? bytevector-fill! bytevector-copy
13812 bytevector-u8-ref bytevector-u8-set! bytevector-s8-ref
13813 bytevector-s8-set! bytevector->u8-list u8-list->bytevector
13814 @end example
13815
13816 @c EN
13817 The following procedures are the same as in @code{gauche.unicode}.
13818 @xref{Unicode utilities}, for the explanations.
13819 @c JP
13820 以下の手続きは@code{gauche.unicode}のものと同じです。
13821 詳しくは@ref{Unicode utilities}を参照してください。
13822 @c COMMON
13823
13824 @example
13825 string->utf8 string->utf16 string->utf32
13826 utf8->string utf16->string utf32->string
13827 @end example
13828
13829 @c EN
13830 This module exports @code{bytevector-copy!}, which takes arguments
13831 in different order from
13832 R7RS base's (and @code{gauche.uvector}'s) @code{bytevector-copy!}.
13833 It is the same as @code{bytevector-copy!-r6} in @code{gauche.uvector}
13834 (@pxref{Bytevector compatibility}).
13835 @c JP
13836 このモジュールは@code{bytevector-copy!}をexportしていますが、
13837 R7RS baseおよび@code{gauche.unicode}に含まれる同名の手続きと引数の順序が異なります。
13838 @code{gauche.uvector}で@code{bytevector-copy!-r6}として定義されているものと
13839 同じになります(@ref{Bytevector compatibility}参照)。
13840 @c COMMON
13841 @end deftp
13842
13843 @defmac endianness symbol
13844 [R7RS bytevector]
13845 @c EN
13846 If @var{symbol} is a valid endianness symbol, returns it. Otherwise,
13847 raise an error at macro-expansion time. Useful to catch an error early,
13848 and explicitly indicates you mean endianness.
13849
13850 Valid symbols are listed in @ref{Endianness}. Only @code{big} and
13851 @code{little} are portable.
13852 @c JP
13853 @var{symbol}がエンディアンを示すシンボルであればそれをそのまま返し、
13854 そうでなければマクロ展開時にエラーを投げます。
13855 エラーを早期に検出するのに役立ちます。
13856 また、シンボルがエンディアンを示すという意図を明確にできます。
13857
13858 有効なシンボルは@ref{Endianness}を参照してください。
13859 @code{big}と@code{little}だけがポータブルです。
13860 @c COMMON
13861 @end defmac
13862
13863 @defun native-endianness
13864 [R7RS bytevector]
13865 @c EN
13866 Returns a symbol representing the native endianness.
13867 Same as Gauche's built-in @code{native-endian} (@pxref{Endianness}).
13868 @c JP
13869 システムのネイティブなエンディアンを示すシンボルを返します。
13870 Gauche組み込みの@code{native-endian}と同じです(@ref{Endianness}参照)。
13871 @c COMMON
13872 @end defun
13873
13874
13875 @defun bytevector-uint-ref bv pos endian size
13876 @defunx bytevector-sint-ref bv pos endian size
13877 [R7RS bytevector]
13878 @c EN
13879 Read @var{size} octets from u8vector @var{bv}, starting from @var{pos}-th
13880 octet, as an unsigned or signed integer, respectively.
13881 Similar to @code{binary.io}'s @code{get-uint} and @code{get-sint},
13882 with different argument order.
13883 @c JP
13884 u8vector @var{bv}の、@var{pos}番めのオクテットから@var{size}オクテットを、
13885 それぞれ符号なしと符号あり整数として読み取ります。
13886 @code{binary.io}モジュールの@code{get-uint}と@code{get-sint}に似ていますが、
13887 引数の順序は異なります。
13888 @c COMMON
13889
13890 @c EN
13891 They accept all valid endianness symbols in Gauche, but
13892 the portable code should only use @code{big} and @code{little} for
13893 @var{endian} argument.
13894 @c JP
13895 @var{endian}にはエンディアンを示すシンボルを渡します。
13896 @code{bit}と@code{little}のみがポータブルに使えます。
13897 @c COMMON
13898 @end defun
13899
13900 @defun bytevector-uint-set! bv pos val endian size
13901 @defunx bytevector-sint-set! bv pos val endian size
13902 [R7RS bytevector]
13903 @c EN
13904 Store an unsigned or signed integer @var{val} into an u8vector
13905 @var{bv} starting from @var{pos}-th octet, for @var{size} octets,
13906 respectively.
13907 Similar to @code{binary.io}'s @code{put-uint!} and @code{put-sint!},
13908 with different argument order.
13909 @c JP
13910 それぞれ、符号なし、および符号つき整数@var{val}をu8vector @var{bv}の
13911 @var{pos}番目のオクテットから@var{size}オクテットにわたって格納します。
13912 @code{binary.io}の@code{put-uint!}および@code{put-sint!}と
13913 引数の順序以外は同じです。
13914 @c COMMON
13915
13916 @c EN
13917 They accept all valid endianness symbols in Gauche, but
13918 the portable code should only use @code{big} and @var{little} for
13919 @var{endian} argument.
13920 @c JP
13921 @var{endian}引数には、Gaucheが許すエンディアンを示すシンボルなら何でも渡せますが、
13922 ポータブルなコードで使えるのは@code{big}と@var{little}だけです。
13923 @c COMMON
13924 @end defun
13925
13926 @defun bytevector->uint-list bv endian size
13927 @defunx bytevector->sint-list bv endian size
13928 [R7RS bytevector]
13929 @c EN
13930 Convert the u8vector @var{bv} to a list of unsigned or signed integer,
13931 each of which is represented by @var{size}-octets.
13932 The length of @var{bv} must be a multiple of @var{size}; otherwise
13933 an error is signaled.
13934 @c JP
13935 u8vector @var{bv}から@var{size}オクテットづつ取り出し、それをそれぞれ符号なし、
13936 および符号つき整数と解釈して、その整数のリストを返します。
13937 @var{bv}の長さが@var{size}の整数倍でなければエラーが投げられます。
13938 @c COMMON
13939
13940 @c EN
13941 They accept all valid endianness symbols in Gauche, but
13942 the portable code should only use @code{big} and @var{little} for
13943 @var{endian} argument.
13944 @c JP
13945 @var{endian}引数には、Gaucheが許すエンディアンを示すシンボルなら何でも渡せますが、
13946 ポータブルなコードで使えるのは@code{big}と@var{little}だけです。
13947 @c COMMON
13948 @end defun
13949
13950 @defun uint-list->bytevector lis endian size
13951 @defunx sint-list->bytevector lis endian size
13952 [R7RS bytevector]
13953 @c EN
13954 @var{Lis} must be a list of unsigned or signed integers, respectively.
13955 Creates a u8vector of length @code{(* size (length lis))}, and
13956 stores each integer into the u8vector using @var{size} octets,
13957 and returns the u8vector.
13958 @c JP
13959 @var{lis}はそれぞれ符号なしまたは符号つき整数のリストでなければなりません。
13960 @code{(* size (length lis))}のu8vectorが作られて、
13961 先頭から@var{size}オクテットごとに、リストの整数が詰められてゆきます。
13962 そしてそのu8vectorが返されます。
13963 @c COMMON
13964
13965 @c EN
13966 They accept all valid endianness symbols in Gauche, but
13967 the portable code should only use @code{big} and @var{little} for
13968 @var{endian} argument.
13969 @c JP
13970 @var{endian}引数には、Gaucheが許すエンディアンを示すシンボルなら何でも渡せますが、
13971 ポータブルなコードで使えるのは@code{big}と@var{little}だけです。
13972 @c COMMON
13973 @end defun
13974
13975 @defun bytevector-u16-ref bv k endian
13976 @defunx bytevector-s16-ref bv k endian
13977 @defunx bytevector-u32-ref bv k endian
13978 @defunx bytevector-s32-ref bv k endian
13979 @defunx bytevector-u64-ref bv k endian
13980 @defunx bytevector-s64-ref bv k endian
13981 @defunx bytevector-ieee-single-ref bv k endian
13982 @defunx bytevector-ieee-double-ref bv k endian
13983 [R7RS bytevector]
13984 @c EN
13985 Retrieve a numerical value from a u8vector @var{bv} starting at
13986 index @var{k}, using @var{endian}. These are the same as
13987 @code{get-u16}, @dots{} in @code{binary.io}, except that
13988 all arguments are mandatory. (Note that
13989 @code{ieee-single} and @code{ieee-double} corresponds to @code{f32} and
13990 @code{f64})). @xref{Binary I/O}, for the details.
13991
13992 They accept all valid endianness symbols in Gauche, but
13993 the portable code should only use @code{big} and @var{little} for
13994 @var{endian} argument.
13995 @c JP
13996 u8vector @var{bv}の@var{k}バイト目から所定のバイト数を、@var{endian}で指定された
13997 バイトオーダーを使って、数値として読み取ります。
13998 これらは引数が全て必須なのを除けば、
13999 Gaucheの@code{binary.io}にある@code{get-u16} @dots{}と同じです
14000 (@code{ieee-single}と@code{ieee-double}は@code{f32}と@code{f64}に相当します)。
14001 詳しくは@ref{Binary I/O}を参照してください。
14002
14003 @var{endian}引数には、Gaucheが許すエンディアンを示すシンボルなら何でも渡せますが、
14004 ポータブルなコードで使えるのは@code{big}と@var{little}だけです。
14005 @c COMMON
14006 @end defun
14007
14008 @defun bytevector-u16-native-ref bv k
14009 @defunx bytevector-s16-native-ref bv k
14010 @defunx bytevector-u32-native-ref bv k
14011 @defunx bytevector-s32-native-ref bv k
14012 @defunx bytevector-u64-native-ref bv k
14013 @defunx bytevector-s64-native-ref bv k
14014 @defunx bytevector-ieee-single-native-ref bv k
14015 @defunx bytevector-ieee-double-native-ref bv k
14016 [R7RS bytevector]
14017 @c EN
14018 Like @code{bytevector-u16-ref} etc., but uses native endianness.
14019 @c JP
14020 システムのネイティブバイトオーダーを使うこと以外は
14021 @code{bytevector-u16-ref} @dots{}と同じです。
14022 @c COMMON
14023 @end defun
14024
14025 @defun bytevector-u16-set! bv k val endian
14026 @defunx bytevector-s16-set! bv k val endian
14027 @defunx bytevector-u32-set! bv k val endian
14028 @defunx bytevector-s32-set! bv k val endian
14029 @defunx bytevector-u64-set! bv k val endian
14030 @defunx bytevector-s64-set! bv k val endian
14031 @defunx bytevector-ieee-single-set! bv k val endian
14032 @defunx bytevector-ieee-double-set! bv k val endian
14033 [R7RS bytevector]
14034 @c EN
14035 Store a numerical value into a u8vector @var{bv} starting at
14036 index @var{k}, using @var{endian}. These are the same as
14037 @code{put-u16!}, @dots{} in @code{binary.io}, except that
14038 all arguments are mandatory. (Note that
14039 @code{ieee-single} and @code{ieee-double} corresponds to @code{f32} and
14040 @code{f64}). @xref{Binary I/O}), for the details.
14041
14042 They accept all valid endianness symbols in Gauche, but
14043 the portable code should only use @code{big} and @var{little} for
14044 @var{endian} argument.
14045 @c JP
14046 数値をu8vector @var{bv}の@var{k}バイト目から所定のバイト数ぶん、
14047 @var{endian}で指定されたバイトオーダーを使って、格納します。
14048 これらは引数が全て必須なのを除けば、
14049 Gaucheの@code{binary.io}にある@code{put-u16!} @dots{}と同じです
14050 (@code{ieee-single}と@code{ieee-double}は@code{f32}と@code{f64}に相当します)。
14051 詳しくは@ref{Binary I/O}を参照してください。
14052
14053 @var{endian}引数には、Gaucheが許すエンディアンを示すシンボルなら何でも渡せますが、
14054 ポータブルなコードで使えるのは@code{big}と@var{little}だけです。
14055 @c COMMON
14056 @end defun
14057
14058 @defun bytevector-u16-native-set! bv k val
14059 @defunx bytevector-s16-native-set! bv k val
14060 @defunx bytevector-u32-native-set! bv k val
14061 @defunx bytevector-s32-native-set! bv k val
14062 @defunx bytevector-u64-native-set! bv k val
14063 @defunx bytevector-s64-native-set! bv k val
14064 @defunx bytevector-ieee-single-native-set! bv k val
14065 @defunx bytevector-ieee-double-native-set! bv k val
14066 [R7RS bytevector]
14067 @c EN
14068 Like @code{bytevector-u16-set!} etc., but uses native endianness.
14069 @c JP
14070 システムのネイティブバイトオーダーを使うこと以外は
14071 @code{bytevector-u16-set!} @dots{}と同じです。
14072 @c COMMON
14073 @end defun
14074
14075 @node R7RS combinator formatting, , R7RS bytevectors, R7RS large
14076 @subsection @code{scheme.show} - R7RS combinator formatting
14077 @c NODE R7RS combinator formatting, @code{scheme.show} - R7RS combinator formatting
14078
14079 @subsubheading Module structure
14080 @deftp {Module} scheme.show
14081 @mdindex scheme.show
14082 Exports bindings of R7RS @code{(scheme show)} library.
14083 From R7RS programs, those bindings are available by
14084 @code{(import (scheme show))}.
14085
14086 scheme.show is a combination of submodules scheme.show.base,
14087 scheme.show.color, scheme.show.columnar and scheme.show.unicode.
14088 @end deftp
14089
14090 @deftp {Module} scheme.show.base
14091 Exports bindings of R7RS @code{(scheme show base)} library.
14092 From R7RS programs, those bindings are available by
14093 @code{(import (scheme show base))}.
14094
14095 This contains most combinator formatting procedures.
14096 @end deftp
14097
14098 @deftp {Module} scheme.show.color
14099 Exports bindings of R7RS @code{(scheme show color)} library.
14100 From R7RS programs, those bindings are available by
14101 @code{(import (scheme show color))}.
14102
14103 This contains formatters to color text using ANSI escape codes.
14104 @end deftp
14105
14106 @deftp {Module} scheme.show.columnar
14107 Exports bindings of R7RS @code{(scheme show columnar)} library.
14108 From R7RS programs, those bindings are available by
14109 @code{(import (scheme show columnar))}.
14110
14111 This contains formatters to help format in columns.
14112 @end deftp
14113
14114 @deftp {Module} scheme.show.unicode
14115 Exports bindings of R7RS @code{(scheme show unicode)} library.
14116 From R7RS programs, those bindings are available by
14117 @code{(import (scheme show unicode))}.
14118 @end deftp
14119
14120 @subsubheading Usage
14121
14122 Combinator formatting provides a functionality similar to
14123 @code{format} from SRFI-28. But instead of writing a template string,
14124 you can use S-expressions, which are called ``formatters''. It's also
14125 extensible.
14126
14127 The two main concepts in combinator formatting are formatters and
14128 states. Formatters are procedures that specify how or what you want to
14129 output. Formatters can be composed to produce complex format. Normal
14130 types are also accepted where a procedure takes a formatter, they are
14131 formatted with @code{displayed}.
14132
14133 Format states let us customize control formatting, for example how
14134 many precision digits, what character for padding @dots{}. Format
14135 states can be changed locally with @code{with} or @code{with!}.
14136
14137 The entry point to combinator formatting is @code{show}, which takes a
14138 sequence of formatters and outputs to a port or returns a string.
14139
14140 @defun show @var{output-dest} @var{fmt} @dots{}
14141 [R7RS show base]
14142 @c MOD scheme.show.base
14143 This is the main entry for combinator formatting. All formatters are
14144 processed to produce a string to @var{output-dest} if it's a port. If
14145 @var{output-dest} is @code{#t}, the current output port is used. If
14146 @var{output-dest} is @code{#f}, the output string is returned.
14147 @code{show} return value is otherwise undefined. Non-formatters are
14148 also accepted and will be wrapped in @code{displayed} formatter.
14149
14150 @example
14151 (show #f "π = " (with ((precision 2)) (acos -1)) nl)
14152 @result{} "π = 3.14\n"
14153 @end example
14154 @end defun
14155
14156 @subsubheading Formatting Objects
14157
14158 @defun displayed @var{obj}
14159 [R7RS show base]
14160 @c MOD scheme.show.base
14161 The formatter that formats the object @var{obj} the
14162 same as @code{display}. This is the default formatter when you pass an
14163 object to @code{show}.
14164 @end defun
14165
14166 @defun written @var{obj}
14167 [R7RS show base]
14168 @c MOD scheme.show.base
14169 The formatter that formats the object @var{obj} the same as
14170 @code{write}. Formatting settings @code{numeric} and @code{precision}
14171 are respected for relevant number types as long as the result can
14172 still be passed to @code{read}.
14173 @end defun
14174
14175 @defun written-simply @var{obj}
14176 [R7RS show base]
14177 @c MOD scheme.show.base
14178 Similar to @code{written} but does not handle shared structures.
14179 @end defun
14180
14181 @defun pretty @var{obj}
14182 [R7RS show base]
14183 @c MOD scheme.show.base
14184 Pretty prints an object.
14185 @end defun
14186
14187 @defun pretty-simply @var{obj}
14188 [R7RS show base]
14189 @c MOD scheme.show.base
14190 Similar to @code{pretty} but does not handle shared structures.
14191 @end defun
14192
14193 @defun escaped @var{str} [@var{quote-ch} @var{esc-ch} @var{renamer}]
14194 [R7RS show base]
14195 @c MOD scheme.show.base
14196 Prints a string, adding @var{esc-ch} (@code{#\\} by default) in front
14197 of all @var{quote-ch} (@code{#\"} by default).
14198
14199 If @var{esc-ch} is @code{#f}, escape all @var{quote-ch} by doubling
14200 it.
14201
14202 If @var{renamer} is specified, it's a procedure that takes one
14203 character and returns another character or @code{#f}. It serves two
14204 purposes: to allow quoting more than one character and to replace them
14205 with something else. If the procedure returns @code{#f}, the character
14206 in question is not escaped. Otherwise the character is escaped and
14207 replaced with a new one.
14208
14209 @var{esc-ch} could also be a string, but this is Gauche specific behavior.
14210
14211 @example
14212 (show #t (escaped "hello \"world\"")) @result{} hello \"world\"
14213 (show #t (escaped "hello \"world\"" #\l)) @result{} he\l\lo "world"
14214 (show #t (escaped "hello \"world\"" #\l #\x)) @result{} hexlxlo "worxld"
14215 (show #t (escaped "hello \"world\""
14216 #\e #f
14217 (lambda (x) (if (char=? x #\o) #\O #f))))
14218 @result{} heelleO "weOrld"
14219 @end example
14220 @end defun
14221
14222 @defun maybe-escaped @var{str} @var{pred} [@var{quote-ch} @var{esc-ch} @var{renamer}]
14223 [R7RS show base]
14224 @c MOD scheme.show.base
14225 Determines if @var{str} needs to be escaped or not. If true, the
14226 string is wrapped with @var{quote-ch}. The original string is escaped
14227 with @code{escaped}.
14228
14229 The string needs to be escaped if any @var{quote-ch} or @var{esc-ch}
14230 is present, or any character that makes @var{pred} return @code{#t}.
14231
14232 @example
14233 (show #t (maybe-escaped "helloworld" char-whitespace?)) @result{} helloworld
14234 (show #t (maybe-escaped "hello world" char-whitespace?)) @result{} "hello world"
14235 (show #t (maybe-escaped "hello \"world\"" char-whitespace? #\")) @result{} "hello \"world\""
14236 @end example
14237
14238 @end defun
14239
14240 @subsubheading Formatting Numbers
14241
14242 @defun numeric @var{num} [@var{radix} @var{precision} @var{sign-rule} @var{comma-rule} @var{comma-sep} @var{decimal-sep}]
14243 [R7RS show base]
14244 @c MOD scheme.show.base
14245 Formats a number. The default values are from state variables below.
14246
14247 @example
14248 (show #f (numeric 1000)) @result{} "1000"
14249 (show #f (numeric 1000 8)) @result{} "1750"
14250 (show #f (numeric 1000 8 2)) @result{} "1750.00"
14251 (show #f (numeric 1000 8 2 #t)) @result{} "+1750.00"
14252 (show #f (numeric -1000 8 2 (cons "(" ")"))) @result{} "(1750.00)"
14253 (show #f (numeric 1000 8 2 #t 2)) @result{} "+17,50.00"
14254 (show #f (numeric 1000 8 2 #t 2 #\')) @result{} "+17'50.00"
14255 (show #f (numeric 1000 8 2 #t 2 #\' #\:)) @result{} "+17'50:00"
14256 @end example
14257
14258 @end defun
14259
14260 @defun numeric/comma @var{num} [@var{radix} @var{precision} @var{sign-rule}]
14261 [R7RS show base]
14262 @c MOD scheme.show.base
14263 Formats a number with default @var{comma-rule} 3. See @code{numeric}
14264 for details.
14265 @example
14266 (show #f (numeric/comma 1000)) @result{} "1,000"
14267 (show #f (with ((comma-sep #\.)) (numeric/comma 1000))) @result{} "1.000"
14268 @end example
14269
14270 @end defun
14271
14272 @defun numeric/si @var{num} [@var{base} @var{separator}]
14273 [R7RS show base]
14274 @c MOD scheme.show.base
14275 Formats a numeric with SI suffix. The default base is 1024 and uses
14276 suffix names like Ki, Mi, Gi@dots{}. Other bases (e.g. 1000) use
14277 suffixes k, M, G@dots{}. If @var{separator} is specified, it's
14278 inserted between the number and suffix.
14279
14280 @example
14281 (show #f (numeric/si 1024)) @result{} "1Ki"
14282 (show #f (numeric/si 200000 1000)) @result{} "200k"
14283 (show #f (numeric/si 1024 1024 #\/)) @result{} "1/Ki"
14284 @end example
14285
14286 @end defun
14287
14288 @defun numeric/fitted @var{width} @var{n} [@var{arg} @dots{}]
14289 [R7RS show base]
14290 @c MOD scheme.show.base
14291 Like @code{numeric} but if the result does not fit in @var{width}
14292 characters with current precision, outputs a string of hashes instead
14293 of the truncated and incorrect number.
14294
14295 @example
14296 (show #f (with ((precision 2)) (numeric/fitted 4 1.25))) @result{} "1.25"
14297 (show #f (with ((precision 2)) (numeric/fitted 4 12.345))) @result{} "#.##"
14298 @end example
14299
14300 @end defun
14301
14302 @subsubheading Formatting Space
14303
14304 @defvar nl
14305 Outputs a newline.
14306
14307 @example
14308 (show #f nl) @result{} "\n"
14309 @end example
14310 @end defvar
14311
14312 @defvar fl
14313 Short for ``fresh line'', make sures the following output is at the
14314 beginning of the line.
14315
14316 @example
14317 (show #f fl) @result{} ""
14318 (show #f "aaa" fl) @result{} "aaa\n"
14319 @end example
14320 @end defvar
14321
14322 @defvar nothing
14323 Outputs nothing. This is useful in combinators as default no-op in
14324 conditionals.
14325 @end defvar
14326
14327 @defun space-to @var{column}
14328 [R7RS show base]
14329 @c MOD scheme.show.base
14330 Appends @var{pad-char} to reach the given @var{column}.
14331
14332 @example
14333 (show #f "abcdef" (space-to 3) "a") @result{} " a"
14334 (show #f "abcdef" (space-to 3) "a") @result{} "abcdefa"
14335 @end example
14336 @end defun
14337
14338 @defun tab-to [@var{tab-width}]
14339 [R7RS show base]
14340 @c MOD scheme.show.base
14341 Outputs @var{pad-char} to reach the next tab stop.
14342 @end defun
14343
14344 @subsubheading Concatenation
14345
14346 @defun each @var{fmt} @dots{}
14347 [R7RS show base]
14348 @c MOD scheme.show.base
14349 @end defun
14350
14351 @defun each-in-list @var{list-of-fmts}
14352 [R7RS show base]
14353 @c MOD scheme.show.base
14354 @end defun
14355
14356 @defun joined @var{mapper} @var{list} [@var{sep}]
14357 [R7RS show base]
14358 @c MOD scheme.show.base
14359 Formats each element in @var{list} with @var{mapper} and inserts
14360 @var{sep} in between. @var{sep} by default is an empty string, but it
14361 could be any string or formatter.
14362
14363 @example
14364 (show #f (joined displayed (list "a" "b") " ")) @result{} "a b"
14365 (show #f (joined displayed (list "a" "b") nl)) @result{} "a\nb"
14366 @end example
14367 @end defun
14368
14369 @defun joined/prefix @var{mapper} @var{list} [@var{sep}]
14370 [R7RS show base]
14371 @c MOD scheme.show.base
14372 Similar to @code{joined} except the separator is inserted before
14373 every element.
14374
14375 @example
14376 (show #f (joined/prefix displayed '(usr local bin) "/")) @result{} "/usr/local/bin"
14377 @end example
14378 @end defun
14379
14380 @defun joined/suffix @var{mapper} @var{list} [@var{sep}]
14381 [R7RS show base]
14382 @c MOD scheme.show.base
14383 Similar to @code{joined} except the separator is inserted after every
14384 element.
14385
14386 @example
14387 (show #f (joined/suffix displayed '(1 2 3) nl)) @result{} "1\n2\n3\n"
14388 @end example
14389 @end defun
14390
14391 @defun joined/last @var{mapper} @var{last-mapper} @var{list} [@var{sep}]
14392 [R7RS show base]
14393 @c MOD scheme.show.base
14394 Similar to @code{joined} but @var{last-mapper} is used on the last
14395 element of @var{list} instead.
14396
14397 @example
14398 (show #f (joined/last displayed
14399 (lambda (last) (each "and " last))
14400 '(lions tigers bears)
14401 ", "))
14402 @result{} "lions, tigers, and bears"
14403 @end example
14404 @end defun
14405
14406 @defun joined/dot @var{mapper} @var{dot-mapper} @var{list} [@var{sep}]
14407 [R7RS show base]
14408 @c MOD scheme.show.base
14409 Similar to @code{joined} but if @var{list} is a dotted list, then
14410 formats the dotted value with @var{dot-mapper} instead.
14411 @end defun
14412
14413 @defun joined/range @var{mapper} @var{start} [@var{end} @var{sep}]
14414 [R7RS show base]
14415 @c MOD scheme.show.base
14416 @end defun
14417
14418 @subsubheading Padding and Trimming
14419
14420 @defun padded @var{width} @var{fmt} @dots{}
14421 [R7RS show base]
14422 @c MOD scheme.show.base
14423 Pads the output of @var{fmt}@dots{} on the left side with
14424 @var{pad-char} if it's shorter than @var{width} characters.
14425
14426 @example
14427 (show #f (padded 10 "abc")) @result{} " abc"
14428 (show #f (with ((pad-char #\-)) (padded 10 "abc"))) @result{} "-------abc"
14429 @end example
14430 @end defun
14431
14432 @defun padded/right @var{width} @var{fmt} @dots{}
14433 [R7RS show base]
14434 @c MOD scheme.show.base
14435 Similar to @code{padded} but except padding is on the right side instead.
14436 @end defun
14437
14438 @defun padded/both @var{width} @var{fmt} @dots{}
14439 [R7RS show base]
14440 @c MOD scheme.show.base
14441 Similar to @code{padded} but except padding is on both sides, keeping
14442 the @var{fmt} output at the center.
14443 @end defun
14444
14445 @defun trimmed @var{width} @var{fmt} @dots{}
14446 [R7RS show base]
14447 @c MOD scheme.show.base
14448 Trims the output of @var{fmt}@dots{} on the left so that the length is
14449 @var{width} characters or less. If @var{ellipsis} state variable is
14450 defined, it will be put on the left to denote trimming.
14451
14452 @example
14453 (show #f (trimmed 5 "hello world")) @result{} "world"
14454 (show #f (with ((ellipsis "..")) (trimmed 5 "hello world"))) @result{} "..rld"
14455 @end example
14456 @end defun
14457
14458 @defun trimmed/right @var{width} @var{fmt} @dots{}
14459 [R7RS show base]
14460 @c MOD scheme.show.base
14461 Similar to @code{trimmed} but the trimming is on the right.
14462 @end defun
14463
14464 @defun trimmed/both @var{width} @var{fmt} @dots{}
14465 [R7RS show base]
14466 @c MOD scheme.show.base
14467 Similar to @code{trimmed} but the trimming is on both sides, keeping
14468 the center of the output.
14469 @end defun
14470
14471 @defun trimmed/lazy @var{width} @var{fmt} @dots{}
14472 [R7RS show base]
14473 @c MOD scheme.show.base
14474 A variant of @code{trimmed} which generates each @code{fmt} in left to
14475 right order, and truncates and terminates immediately if more than
14476 @code{width} characters are generated. Thus this is safe to use with
14477 an infinite amount of output, e.g. from @code{written-simply} on an
14478 infinite list.
14479 @end defun
14480
14481 @defun fitted width @var{fmt} @dots{}
14482 [R7RS show base]
14483 @c MOD scheme.show.base
14484 A combination of @code{padded} and @code{trimmed}, ensures the output
14485 width is exactly @var{width}, truncating if it goes over and padding
14486 if it goes under.
14487 @end defun
14488
14489 @defun fitted/right @var{width} @var{fmt} @dots{}
14490 [R7RS show base]
14491 @c MOD scheme.show.base
14492 A combination of @code{padded/right} and @code{trimmed/right}, ensures
14493 the output width is exactly @var{width}, truncating if it goes over
14494 and padding if it goes under.
14495 @end defun
14496
14497 @defun fitted/both @var{width} @var{fmt} @dots{}
14498 [R7RS show base]
14499 @c MOD scheme.show.base
14500 A combination of @code{padded/both} and @code{trimmed/both}, ensures
14501 the output width is exactly @var{width}, truncating if it goes over
14502 and padding if it goes under.
14503 @end defun
14504
14505 @subsubheading Columnar Formatting
14506
14507 @defun columnar @var{column} @dots{}
14508 [R7RS show columnar]
14509 @c MOD scheme.show.columnar
14510 @end defun
14511
14512 @defun tabular @var{column} @dots{}
14513 [R7RS show columnar]
14514 @c MOD scheme.show.columnar
14515 @end defun
14516
14517 @defun wrapped @var{fmt} @dots{}
14518 [R7RS show columnar]
14519 @c MOD scheme.show.columnar
14520 @end defun
14521
14522 @defun wrapped/list @var{list-of-strings}
14523 [R7RS show columnar]
14524 @c MOD scheme.show.columnar
14525 @end defun
14526
14527 @defun wrapped/char @var{fmt} @dots{}
14528 [R7RS show columnar]
14529 @c MOD scheme.show.columnar
14530 @end defun
14531
14532 @defun justified @var{format} @dots{}
14533 [R7RS show columnar]
14534 @c MOD scheme.show.columnar
14535 @end defun
14536
14537 @defun from-file @var{pathname}
14538 [R7RS show columnar]
14539 @c MOD scheme.show.columnar
14540 @end defun
14541
14542 @defun line-numbers [@var{start}]
14543 [R7RS show columnar]
14544 @c MOD scheme.show.columnar
14545 @end defun
14546
14547 @subsubheading Colors
14548
14549 @defun as-red @var{fmt} @dots{}
14550 @defunx as-blue @var{fmt} @dots{}
14551 @defunx as-green @var{fmt} @dots{}
14552 @defunx as-cyan @var{fmt} @dots{}
14553 @defunx as-yellow @var{fmt} @dots{}
14554 @defunx as-magenta @var{fmt} @dots{}
14555 @defunx as-white @var{fmt} @dots{}
14556 @defunx as-black @var{fmt} @dots{}
14557 @defunx as-bold @var{fmt} @dots{}
14558 @defunx as-underline @var{fmt} @dots{}
14559 [R7RS show color]
14560 @c MOD scheme.show.color
14561 Outputs the ANSI escape code to make all @var{fmt}@dots{} a given
14562 color or style.
14563 @end defun
14564
14565 @subsubheading Unicode
14566
14567 @defun as-unicode @var{fmt} @dots{}
14568 [R7RS show unicode]
14569 @c MOD scheme.show.unicode
14570 @end defun
14571
14572 @defun unicode-terminal-width @var{str}
14573 [R7RS show unicode]
14574 @c MOD scheme.show.unicode
14575 @end defun
14576
14577 @subsubheading Higher Order Formatters and State
14578
14579 @defun fn ((@var{id} @var{state-var}) @dots{}) @var{expr} @dots{} @var{fmt}
14580 [R7RS show base]
14581 @c MOD scheme.show.base
14582 This is short for ``function'' and the analog to @code{lambda}. It
14583 returns a formatter which on application evaluates each @var{expr} and
14584 @var{fmt} in left-to-right order, in a lexical environment extended
14585 with each identifier id bound to the current value of the state
14586 variable named by the symbol @var{state-var}. The result of the
14587 @var{fmt} is then applied as a formatter.
14588
14589 As a convenience, any @code{(id state-var)} list may be abbreviated as
14590 simply @code{id}, indicating @var{id} is bound to the state variable
14591 of the same (symbol) name.
14592 @end defun
14593
14594 @defun with ((@var{state-var} @var{value}) @dots{}) @var{fmt} @dots{}
14595 [R7RS show base]
14596 @c MOD scheme.show.base
14597 This is the analog of @code{let}. It temporarily binds specified state
14598 variables with new values for @var{fmt} @dots{}.
14599 @end defun
14600
14601 @defun with! (@var{state-var} @var{value}) @var{fmt} @dots{}
14602 [R7RS show base]
14603 @c MOD scheme.show.base
14604 Similar to @code{with} but the value updates persist even after
14605 @code{with!}.
14606 @end defun
14607
14608 @defun forked @var{fmt1} @var{fmt2}
14609 [R7RS show base]
14610 @c MOD scheme.show.base
14611 Calls @var{fmt1} on (a conceptual copy of) the current state, then
14612 @var{fmt2} on the same original state as though @var{fmt1} had not
14613 been called (i.e. any potential state mutation by @var{fmt1} does not
14614 affect @var{fmt2}).
14615 @end defun
14616
14617 @defun call-with-output @var{formatter} @var{mapper}
14618 [R7RS show base]
14619 @c MOD scheme.show.base
14620 A utility, calls formatter on a copy of the current state (as with
14621 @code{forked}), accumulating the results into a string. Then calls the
14622 formatter resulting from @code{(mapper result-string)} on the original
14623 state.
14624 @end defun
14625
14626 @subsubheading Standard State Variables
14627
14628 @defvar port
14629 The current port output is written into, could be overriden to capture
14630 intermediate output.
14631 @end defvar
14632
14633 @defvar row
14634 The current row of the output.
14635 @end defvar
14636
14637 @defvar col
14638 The current column of the output.
14639 @end defvar
14640
14641 @defvar width
14642 The current line width, used for wrapping, pretty printing and
14643 columnar formatting.
14644 @end defvar
14645
14646 @defvar output
14647 The underlying standard formatter for writing a single string.
14648
14649 The default value outputs the string while tracking the current row
14650 and col. This can be overridden both to capture intermediate output
14651 and perform transformations on strings before outputting, but should
14652 generally wrap the existing output to preserve expected behavior.
14653 @end defvar
14654
14655 @defvar writer
14656 The mapper for automatic formatting of non-string/char values in
14657 top-level show, each and other formatters. Default value is
14658 implementation-defined.
14659 @end defvar
14660
14661 @defvar string-width
14662 A function of a single string. It returns the length in columns of
14663 that string, used by the default output.
14664 @end defvar
14665
14666 @defvar pad-char
14667 The character used for by padding formatters, @code{#\space} by default
14668 @end defvar
14669
14670 @defvar ellipsis
14671 The string used when truncating as described in @code{trimmed}.
14672 @end defvar
14673
14674 @defvar radix
14675 The radix for numeric output, 10 by default. Valid values are from 2
14676 to 36.
14677 @end defvar
14678
14679 @defvar precision
14680 The number of digits written after the decimal point for numeric
14681 output. The value is rounded if the numeric value written out requires
14682 more digits than requested precision. See the SRFI for exact rounding
14683 behavior.
14684 @end defvar
14685
14686 @defvar sign-rule
14687 If @code{#t}, always output the plus sign @code{+} for positive
14688 numbers. If @var{sign-rule} is a par of two strings, negative numbers
14689 are printed with the strings wrapped around (and no preceding negative
14690 sign @code{-}).
14691 @end defvar
14692
14693 @defvar comma-rule
14694 The number of digits between commans, specified by @var{comma-sep}.
14695 @end defvar
14696
14697 @defvar comma-sep
14698 The character used as comma for numeric formatting, @code{#\,} by
14699 default.
14700 @end defvar
14701
14702 @defvar decimal-sep
14703 The character to use for decimals in numeric formatting. The default
14704 depends on @var{comma-sep}, if it's @code{#\.}, then the decimal
14705 separator is @code{#\,}, otherwise it's @code{#\.}
14706 @end defvar
14707
14708 @defvar decimal-align
14709 @end defvar
14710
14711 @defvar word-separator?
14712 @end defvar
14713
14714
14715 @c Local variables:
14716 @c mode: texinfo
14717 @c coding: utf-8
14718 @c end: