@node Library modules - SRFIs, Library modules - Utilities, Library modules - R7RS standard libraries, Top
@chapter Library modules - SRFIs
@c NODE ライブラリモジュール - SRFI

@c EN
This chapter lists modules that provides SRFI functionalities.
Note that some of SRFI features are built in Gauche core and
not listed here.  The SRFIs that have been adopted to R7RS-large
are described in @ref{Library modules - R7RS standard libraries}.

@xref{Standard conformance}, for entire list
of supported SRFIs.

(Even if a srfi is not listed here, you can still say
@code{(use srfi.N)} or @code{(import (srfi N))}, as far as
srfi N is supported by Gauche.)
@c JP
この章ではSRFIの機能を提供するモジュールをリストします。
一部のSRFIはGaucheのコアに組み込まれており、
この章には挙げられていないことに注意して下さい。
また、R7RS-largeに取り入れられたsrfiは@ref{Library modules - R7RS standard libraries}で解説しています。

サポートされている全てのSRFIのリストは@ref{Standard conformance}にあります。

(ここに挙げられていないSRFIでも、サポートされているものについては
@code{(use srfi.N)}や@code{(import (srfi N))}と書くことができます。)
@c COMMON

@c EN
Note that we use a hyphen to refer to a SRFI as a specification
(e.g. SRFI-13) but use a hierarchical name for the module
(e.g. @code{srfi.13} as a Gauche's module, or @code{(srfi 13)} as
a R7RS library).
@c JP
ここで、仕様としてのSRFIを指す場合はハイフンを使い(例: SRFI-13)、
モジュール名としては階層的な名前を使う(例: Gaucheモジュールとしては@code{srfi.13}、
R7RSライブラリとしては@code{(srfi 13)})ということに注意してください。
@c COMMON


@c ----------------------------------------------------------------------
@menu
* Testing availability of SRFIs::
* SRFIs that have become R7RS-large::
* Homogeneous vectors::         srfi.4
* A compatible let form with signatures and rest arguments::  srfi.5
* Feature-based program configuration language::  srfi.7
* String library::              srfi.13
* Time data types and procedures::  srfi.19
* Sources of random bits::      srfi.27
* Localization::                srfi.29
* A program argument processor::  srfi.37
* Eager comprehensions::        srfi.42
* Vector library (Legacy)::     srfi.43
* Requiring extensions::        srfi.55
* Integers as bits::            srfi.60
* A Scheme API for test suites::  srfi.64
* Octet vectors::               srfi.66
* Basic hash tables::           srfi.69
* Octet-addressed binary blocks::  srfi.74
* Lightweight testing::         srfi.78
* Type-restricted numerical functions::  srfi.94
* Accessing environment variables::  srfi.98
* Purely functional random-access pairs and lists::  srfi.101
* Basic socket interface::      srfi.106
* Portable runtime environment inquiry::  srfi.112
* Comparators::                 srfi.114
* Simple adjustable-size strings::  srfi.118
* Timer APIs::                  srfi.120
* Titlecase procedures::        srfi.129
* Cursor-based string library::  srfi.130
* Minimal unique types::        srfi.137
* String library (reduced)::    srfi.152
* First-class dynamic extents::  srfi.154
* Homogeneous numeric vector libraries::  srfi.160
* Comparator sublibrary::       srfi.162
* POSIX API::                   srfi.170
* Two safer subsets of R7RS::   srfi.172
* Hooks (srfi)::                srfi.173
* POSIX timespecs::             srfi.174
* ASCII character library::     srfi.175
* Bitvector library::           srfi.178
* JSON::                        srfi.180
* Custom ports::                srfi.181
* Linear adjustable-length strings::  srfi.185
* Maybe and Either optional container types::  srfi.189
* Coroutine generators::        srfi.190
* Port positioning::            srfi.192
* Command line::                srfi.193
* Random data generators (SRFI)::  srfi.194
* Range objects::               srfi.196
* Pipeline operators::          srfi.197
* String-notated bytevectors::  srfi.207
* Enums and enum sets::         srfi.209
* Procedures and syntax for multiple values::  srfi.210
* Central log exchange::        srfi.215
* SICP prerequisites::          srfi.216
* Integer sets::                srfi.217
* Define higher-order lambda::  srfi.219
* Generator/accumulator sub-library::  srfi.221
* Compound objects::            srfi.222
* Control features::            srfi.226
* Optional arguments::          srfi.227
* Composing comparators::       srfi.228
* Tagged procedures::           srfi.229
* Atomic operations::           srfi.230
* Flexible curried procedures::  srfi.232
* Topological sorting::         srfi.234
* Combinators (SRFI)::          srfi.235
* Codesets::                    srfi.238
* Destructuring lists::         srfi.239
* Syntactic monads::            srfi.247
* Property testing::            srfi.252
* Data type checking::          srfi.253
* Uninterned symbols (SRFI)::   srfi.258
* Tagged procedures with type safety::  srfi.259
@end menu

@node Testing availability of SRFIs, SRFIs that have become R7RS-large, Library modules - SRFIs, Library modules - SRFIs
@section Testing availability of SRFIs
@c NODE SRFIが使えるかどうかテストする

@c EN
To test availability of a SRFI with @code{cond-expand}
(@pxref{Feature conditional}), you can use @code{(library library-name)}
feature requirement.  You can use both Gauche-style and R7RS-style
library name notation.
@c JP
特定のSRFIが使えるかどうかを@code{cond-expand}で検査する場合は、機能要請式
@code{(library @code{library-name})}が使えます (@ref{Feature conditional}参照)。
@var{library-name}にはGauche方式のモジュール名もR7RS方式のライブラリ名も使えます。
@c COMMON

@example
;; Use 'library' feature requirement with Gauche module name
(cond-expand
  [(library srfi.13) (use srfi.13) ...]
  [else ...])

;; Use 'library' feature requirement with R7RS library name
(cond-expand
  [(library (srfi 13)) (import (srfi 13)) ...]
  [else ...])
@end example

@c EN
Alternatively you can use a SRFI name as a feature identifier.
@emph{This use is deprecated}.  This is an old style used before R7RS.
With this style, if the feature is fulfilled, the necessary libraries
are implicitly imported, so you don't need to have @code{use} or
@code{import} forms (but that means you can't control the imports
with @code{only}, @code{rename}, @code{prefix} etc.)
@c JP
他に、SRFI名を直接機能識別子として使うこともできます。
@emph{ただし、この機能は非推奨です}。これはR7RS以前の方式です。
この指定を使った場合、機能条件が満たされたならば、必要なモジュールは自動的にインポート
されているので、@code{use}や@code{import}でインポートする必要はありません。
ただそれは、@code{only}、@code{rename}、@code{prefix}節などでインポートする
識別子を制御できないということでもあります。
@c COMMON

@example
;; DEPRECATED.  Use 'srfi-N' feature identifier.
;; If the feature is fulfilled, you can assume the module is already 'use'd.
(cond-expand
  [srfi-13 ...]
  [else ...])
@end example

@c EN
If @code{srfi-N} is used as a feature identifier, a warning is
issued when an environment variable @code{GAUCHE_WARN_SRFI_FEATURE_ID} is
set.  In future this warning will be the default.  We urge the users
to update their code to use @code{(library srfi.N)} form.
@c JP
@code{srfi-N}が機能識別子として使われた場合、
環境変数@code{GAUCHE_WARN_SRFI_FEATURE_ID}がセットされていれば
警告が表示されます。将来はデフォルトで警告するようになります。
@code{srfi-N}機能識別子を使っているユーザは、なるべく早く
@code{(library srfi.N)}へと書き換えるようにしてください。
@c COMMON


@node SRFIs that have become R7RS-large, Homogeneous vectors, Testing availability of SRFIs, Library modules - SRFIs
@section SRFIs that have become R7RS-large
@c NODE R7RS-largeになったSRFI

@c EN
Here's a list of SRFIs that have become a part of R7RS-large,
ordered by SRFI numbers.
@c JP
以下に、R7RS-largeに取り入れられたSRFIのリストを番号順に示します。
@c COMMON

@table @asis
@item SRFI-1 List library
@code{scheme.list} (@pxref{R7RS lists}).
@item SRFI-14 Character-set library
@code{scheme.char-set} (@pxref{R7RS character sets}).
@item SRFI-41 Streams
@code{scheme.stream} (@pxref{R7RS stream}).
@item SRFI-101 Purely functional random-access pairs and lists
@code{scheme.rlist} (@pxref{R7RS random-access lists}).
@item SRFI-111 Boxes
@code{scheme.box} (@pxref{R7RS boxes}).
@item SRFI-113 Sets and bags
@code{scheme.set} (@pxref{R7RS sets}).
@item SRFI-115 Scheme Regular Expressions
@code{scheme.regex} (@pxref{R7RS regular expressions}).
@item SRFI-116 Immutable list library
@code{scheme.ilist} (@pxref{R7RS immutable lists}).
@item SRFI-117 Queues based on lists
@code{scheme.list-queue} (@pxref{R7RS list queues}).
@item SRFI-121 Generators
@code{scheme.generator} (@pxref{R7RS generators}).
@item SRFI-124 Ephemerons
@code{scheme.ephemeron} (@pxref{R7RS ephemerons}).
@item SRFI-125 Intermediate hash tables
@code{scheme.hash-table} (@pxref{R7RS hash tables}).
@item SRFI-127 Lazy sequences
@code{scheme.lseq} (@pxref{R7RS lazy sequences}).
@item SRFI-128 Comparators (reduced)
@code{scheme.comparator} (@pxref{R7RS comparators}).
@item SRFI-132 Sort library
@code{scheme.sort} (@pxref{R7RS sort}).
@item SRFI-133 Vector library
@code{scheme.vector} (@pxref{R7RS vectors}).
@item SRFI-134 Immutable deques
@code{scheme.ideque} (@pxref{R7RS immutable deques}).
@item SRFI-135 Immutable texts
@code{scheme.text} (@pxref{R7RS immutable texts}).
@item SRFI-141 Integer division
@code{scheme.division} (@pxref{R7RS integer division}).
@item SRFI-143 Fixnums
@code{scheme.fixnum} (@pxref{R7RS fixnum}).
@item SRFI-144 Flonums
@code{scheme.flonum} (@pxref{R7RS flonum}).
@item SRFI-146 Mappings
@code{scheme.mapping}, @code{scheme.mapping.hash} (@pxref{R7RS mappings}).
@item SRFI-151 Bitwise operations
@code{scheme.bitwise} (@pxref{R7RS bitwise operations}).
@item SRFI-158 Generators and accumulators
@code{scheme.generator} (@pxref{R7RS generators}).
@item SRFI-159 Combinator formatting
@code{scheme.show} (@pxref{R7RS combinator formatting}).
@item SRFI-160 Homogeneous numeric vector libraries
@code{scheme.vector.@@} (@pxref{R7RS uniform vectors}).
@end table


@c ----------------------------------------------------------------------
@node Homogeneous vectors, A compatible let form with signatures and rest arguments, SRFIs that have become R7RS-large, Library modules - SRFIs
@section @code{srfi.4} - Homogeneous vectors
@c NODE 単一型のベクタ, @code{srfi.4} - 単一型のベクタ

@deftp {Module} srfi.4
@mdindex srfi.4
@c EN
SRFI-4 is now implemented in @code{gauche.uvector} module
@xref{Uniform vectors}.
This module simply inherits @code{gauche.uvector} for backward-compatibility.
@c JP
SRFI-4は、@code{gauche.uvector}モジュールとして実装されています。
@ref{Uniform vectors}参照。
このモジュールは後方互換性のために単に@code{gauche.uvector}を継承しています。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node A compatible let form with signatures and rest arguments, Feature-based program configuration language, Homogeneous vectors, Library modules - SRFIs
@section @code{srfi.5} - A compatible let form with signatures and rest arguments
@c NODE シグネチャとrest引数に互換性のあるlet形式, @code{srfi.5} - シグネチャとrest引数に互換性のあるlet形式

@deftp {Module} srfi.5
@mdindex srfi.5
@c EN
This module provides SRFI-5's extended @code{let} syntax.
@c JP
このモジュールは SRFI-5 の拡張 @code{let} 構文を提供します。
@c COMMON
@end deftp

@defmac let ((var val) @dots{} [. (rest val @dots{})]) body @dots{}
@defmacx let name ((var val) @dots{} [. (rest val @dots{})]) body @dots{}
@defmacx let (name (var val) @dots{} [. (rest val @dots{})]) body @dots{}
[SRFI-5]
@c MOD srfi.5
@c EN
The @code{let} syntax is extended in two ways.
@c JP
@code{let} 構文は 2通りの拡張がされています。
@c COMMON

@c EN
@itemize @bullet
@item
The extended @code{let} syntax accepts the @var{name} identifier (for
named let syntax) within the list of bindings (as in the third
syntax above).
@item
The extended @code{let} syntax accepts the rest parameter binding
which works like the rest parameter in the @code{lambda} syntax.
@end itemize

See SRFI-5 document for rationale of this extension.
@c JP
@itemize @bullet
@item
拡張 @code{let} 構文は、@var{name} 束縛リスト中で(名前付き let 構文用の)
識別子を許します(上の3つめの構文)。
@item
拡張 @code{let} 構文は、@code{lambda} 構文の rest パラメータと同様の
働きをする rest パラメータ束縛を許します。
@end itemize

この拡張に関する理論的根拠については SRFI-5 のドキュメントを参照してください。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node Feature-based program configuration language, String library, A compatible let form with signatures and rest arguments, Library modules - SRFIs
@section @code{srfi.7} - Feature-based program configuration language
@c NODE 機能ベースプログラム設定言語, @code{srfi.7} - 機能ベースプログラム設定言語

@deftp {Module} srfi.7
@mdindex srfi.7
@c EN
This module provides a program configuration metalanguage
(@code{program} form) defined in srfi-7.
@c JP
このモジュールは、SRFI-7 で定義されている
プログラム設定メタ言語(@code{program} フォーム)を提供します。

@c EN
Gauche autoloads @code{srfi.7} module, so you don't need
to say @code{(use srfi.7)} explicitly.
@c JP
Gauche は @code{srfi.7} モジュールを autoload するので、@code{(use srfi.7)} と
明示的に書く必要はありません。

@c EN
Note that the @code{program} form isn't necessary to be a
Scheme expression.  SRFI-7 allows an implementation to preprocess
the @code{program} form to produce a Scheme program, then
executes it with different means.
@c JP
@code{program} フォームは Scheme の式である必要がないことに注意してください。
SRFI-7 では、この @code{program}フォームを処理して Scheme プログラムを
生成してから、それを別の方法で実行するような実装を許しています。

@c EN
Gauche implements @code{program} form as a macro, so it can
evaluates the form directly.  Nonetheless, it doesn't make sense
to mix @code{program} form and other forms in one file,
or expecting a return value of @code{program} form.
@c JP
Gauche @code{program} フォームをマクロとして実装しているので、
フォーム自体を直接、評価することができます。とはいえ、@code{program}
フォームと他のフォームを一つのファイル中で混在させたり、@code{program}
フォームの返り値を期待するのは、よいことではありません。

@c EN
A typical usage of @code{program} form is to prepare a single
file which just contains @code{program} form.  (It can load
other files using @code{files} clause (see below) within the
@code{program} form.)   To execute such a program file in Gauche,
you can just load it.
@c JP
@code{program}フォームの典型的な使い方は、@code{program} フォームのみを
含む単一のファイルを用意することです。(@code{program}フォーム中で
@code{files} 節(後述)を用いて他のファイルをロードすることが可能です。)
このようなプログラムファイルを Gauche で実行するには、単にそれを
ロードするだけです。
@c COMMON
@end deftp

@deffn {Configuration Language} program program-clause program-clause2 @dots{}
[SRFI-7]
@c MOD srfi.7
@c EN
This is a configuration language to structure a Scheme program,
based on availability of the features.

A Scheme program is constructed from the @code{program} form.
Gauche evaluates the constructed Scheme program on-the-fly.

Each @var{program-clause} needs to be one of the "Program Clauses" below.
@c JP
これは Scheme プログラムを構成する設定言語で、機能の利用可能性に基づいて
います。

Scheme のプログラムは、この @code{program}フォームから構築されます。
Gauche は構築された Scheme のプログラムをそのまま実行します。

各 @var{program-clause} は以下の "Program Clause" のどれか一つである
必要があります。
@c COMMON
@end deffn

@deffn {Program Clause} requires feature-id feature-id2 @dots{}
[SRFI-7]
@c EN
The @var{feature-id}'s are the same as SRFI-0's
(@pxref{Feature conditional}).
It tells that the following code requires these @var{feature-id}'s.

If a feature-id which is not supported in Gauche is given,
an error is signaled.
@c JP
@var{feature-id} は SRFI-0 のものと同じです
(@pxref{Feature conditional})。
あとに続くコードが @var{feature-id} を必要とすることを教えます。

Gauche ではサポートされていない feature-id が与えられた場合には、
エラーシグナルが発生します。
@c COMMON
@end deffn

@deffn {Program Clause} files filename @dots{}
[SRFI-7]
@c EN
Inserts the content of the @var{filename}s into a program.
In Gauche, this clause just causes @var{filename}s to be loaded
into the current module.
@c JP
プログラムに @var{filename}の内容を挿入します。Gauche では
単に、現在のモジュール中への @var{filename} のロードをひきおこします。
@c COMMON
@end deffn

@deffn {Program Clause} code scheme-expression @dots{}
[SRFI-7]
@c EN
The @var{scheme-expression}s are inserted into a program.
@c JP
@var{scheme-expression} がプログラムに挿入されます。
@c COMMON
@end deffn

@deffn {Program Clause} feature-cond clause clause2 @dots{}
[SRFI-7]
@c EN
@var{Clause} is a following form:
@c JP
@var{clause} は以下のようなフォームです。
@c COMMON
@example
(@var{requirement} @var{program-clause} @var{program-clause2} @dots{})
@end example

@c EN
Where @var{requirement} should be one of the following:
@c JP
ここでは、@var{requirement} は以下のもののどれかひとつでなければなりません。
@c COMMON
@itemize @bullet
@item
@var{feature-id}
@item
@code{(and @var{requirement} @dots{})}
@item
@code{(or @var{requirement} @dots{})}
@item
@code{(not @var{requirement})}
@end itemize

@c EN
The @var{requirement} of the last @var{clause} may be @code{else}.

Gauche checks each @var{requirement} one by one, and if it finds
a fulfilled @var{requirement}, inserts the @var{program-clause}s
in that @var{clause} into the program.
@c JP
最後の @var{clause} の @var{requirement} は @code{else} になるでしょう。

Gauche はそれぞれの @var{requirement} をひとつずつチェックし、
満された @var{requirement} が見つかると、その@var{clause}中の
@var{program-clause} をプログラムに挿入します。
@c COMMON
@end deffn

@c ----------------------------------------------------------------------
@node String library, Time data types and procedures, Feature-based program configuration language, Library modules - SRFIs
@section @code{srfi.13} - String library
@c NODE 文字列ライブラリ, @code{srfi.13} - 文字列ライブラリ

@deftp {Module} srfi.13
@mdindex srfi.13
@c EN
Defines a large set of string-related procedures.
@c JP
文字列に関連する手続きの大きなセットを定義しています。
@c COMMON

@c EN
It was one of the earliest popular srfis, but some of
the procedures were turned out not to align well with recent Scheme
developments.  @xref{String library (reduced)},
and @ref{Cursor-based string library} adapts this srfis to more
``modern'' form.  Consider to use them for newer development.
@c JP
これは広く使われた初期のsrfiのひとつですが、いくつかの手続きは
その後のSchemeの発展と相性が良くないということがわかってきました。
@ref{String library (reduced)}や@ref{Cursor-based string library}では
このsrfiをより「現代的」なものにしようとしています。
新規に開発する場合はそれらのsrfiを見てみると良いでしょう。
@c COMMON

@c EN
Many procedures in this srfi specifies the position of a character
in a string with an integer index.  Although it's portable, it is not
optimal for multibyte strings.  Gauche natively supports string cursors,
which is more efficient than integer indexes (@pxref{String cursors}).
All SRFI-13 procedures
that accepts integer indexes can also accept string cursors.
@c JP
このsrfiの多くの手続きは、文字列中の文字の位置を整数のインデックスで表します。
これはポータブルですが、マルチバイト文字列では効率が悪いです。
Gaucheは組み込みでより効率のよい文字列カーソルをサポートしており(@ref{String cursors})、
SRFI-13の手続きは全て文字列インデックスを受け取るところに文字列カーソルも
渡せるようになっています。
@c COMMON
@end deftp

@menu
* SRFI-13 General conventions::
* SRFI-13 String predicates::
* SRFI-13 String constructors::
* SRFI-13 String selection::
* SRFI-13 String comparison::
* SRFI-13 String prefixes & suffixes::
* SRFI-13 String searching::
* SRFI-13 String case mapping::
* SRFI-13 String reverse & append::
* SRFI-13 String mapping::
* SRFI-13 String rotation::
* SRFI-13 Other string operations::
* SRFI-13 String filtering::
* SRFI-13 Low-level string procedures::
@end menu

@node SRFI-13 General conventions, SRFI-13 String predicates, String library, String library
@subsection General conventions
@c NODE 一般規約

@c EN
There are a few common factors in string library API, which I don't
repeat in each function description
@c JP
文字列ライブラリのAPIにはいくつか共通するものがありますが、
それぞれの関数の説明において繰り返しません。
@c COMMON

@table @emph
@c EN
@item argument convention
@c JP
@item 引数の仕様
@c EN
The following argument names imply their types.
@c JP
以下の引数名はその型を暗に表しています。
@c COMMON
@table @asis
@item @var{s}, @var{s1}, @var{s2}
@c EN
Those arguments must be strings.
@c JP
これらの引数は文字列でなければなりません。
@c COMMON
@item @var{char/char-set/pred}
@c EN
This argument can be a character, a character-set object,
or a predicate that takes a single character and returns a boolean value.
``Applying @var{char/char-set/pred} to a character'' means,
if @var{char/char-set/pred} is a character, it is compared to the given
character; if @var{char/char-set/pred} is a character set, it is
checked if the character set contains the given character; if
@var{char/char-set/pred} is a procedure, it is applied
to the given character.  ``A character satisfies @var{char/char-set/pred}''
means such application to the character yields true value.
@c JP
この引数は、文字、文字集合オブジェクト、あるいは1つの文字を引数に取り
真偽値を返す述語のいずれかです。``文字に@var{char/char-set/pred}を適用する''
の意味はそれぞれ、@var{char/char-set/pred}が文字ならば与えられた文字と比較される、
@var{char/char-set/pred}が文字集合ならばその文字集合に与えられた文字が
含まれるかを検査する、@var{char/char-set/pred}が述語ならばそれを与えられた
文字に適用する、となります。``ある文字が@var{char/char-set/pred}を満足する''
とは、その文字への前述のような適用が真値を返すという意味になります。
@c COMMON

@item @var{start}, @var{end}
@c EN
Lots of SRFI-13 functions takes these two optional arguments, which
limit the area of input string from @var{start}-th character
(inclusive) to @var{end}-th character (exclusive),
where the operation is performed.
When specified, the condition
0 <= @var{start} <= @var{end} <= @var{length of the string} must be
satisfied.  Default value of @var{start} and @var{end} is
0 and the length of the string, respectively.
@c JP
SRFI-13の関数の多くは、その操作が実行される対象入力文字列の
範囲を限定する開始インデックスと終了インデックスをオプショナルな
引数として取ります。開始(@var{start}番目)の文字は含まれ、
終了(@var{end}番目)の文字は含まれません。
これらが指定されるとき、0 <= @var{start} <= @var{end} <= @var{length of the string}が
満たされなければなりません。@var{start}と@var{end}のデフォルト値は、
それぞれ0と文字列の長さです。
@c COMMON
@end table

@c EN
@item @code{shared} variant
@c JP
@item @code{shared}バージョン
@c EN
Some functions have variants with ``/shared'' attached to its name.
SRFI-13 defines those functions to allow to share the part of input
string, for better performance.  Gauche doesn't have a concept of
shared string, and these functions are mere synonyms of their
non-shared variants.  However, Gauche @emph{internally} shares
the storage of strings, so generally you don't need to worry
about the overhead of copying substrings.
@c JP
いくつかの関数は、その名前に``/shared''が付きます。
SRFI-13では、それらの関数はより良いパフォーマンスのために
入力文字列の一部を共有しても良いと定義しています。
Gaucheは、共有文字列という概念を持っていませんし、
それらの関数は単に共有でないバージョンの変名に過ぎません。
しかし、Gaucheは@emph{内部的には}文字列の保存場所を共有しているので、
一般的には部分文字列をコピーするオーバヘッドについて心配する
必要はありません。
@c COMMON

@c EN
@item @code{right} variant
@c JP
@item @code{right}バージョン
@c EN
Most functions works from left to right of the input string.
Some functions have variants with ``-right'' to its name,
that works from right to left.
@c JP
ほとんどの関数は、入力文字列を左から右へと扱います。
いくつかの関数は、その名前に``-right''が付き、右から左へと
扱うものがあります。
@c COMMON

@end table

@node SRFI-13 String predicates, SRFI-13 String constructors, SRFI-13 General conventions, String library
@subsection String predicates
@c NODE 文字列についての述語

@defun string-null? s
[SRFI-13]
@c MOD srfi.13
@c EN
Returns @code{#t} if @var{s} is an empty string, @code{""}.
@c JP
@var{s}が空文字列、@code{""}なら、@code{#t}を返します。
@c COMMON
@end defun

@defun string-every char/char-set/pred s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Sees if every character in @var{s} satisfies
@var{char/char-set/pred}.  If so, @code{string-every} returns
the value that is returned at the last application of @var{char/char-set/pred}.
If any of the application returns @code{#f}, @code{string-every}
returns @code{#f} immediately.
@c JP
@var{s}に含まれる全ての文字が@var{char/char-set/pred}を
満足するかを検査します。満足するならば、@code{string-every}は
最後に適用された@var{char/char-set/pred}が返した値を戻り値とします。
どの適用も@code{#f}を返した場合は、@code{string-every}はすぐに
@code{#f}を返します。
@c COMMON
@end defun

@defun string-any char/char-set/pred s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Sees if any character in @var{s} satisfies
@var{char/char-set/pred}.  If so, @code{string-any} returns
the value that is returned by the application.   If no character
satisfies @var{char/char-set/pred}, @code{#f} is returned.
@c JP
@var{s}に含まれるいずれかの文字が@var{char/char-set/pred}
を満足するかを検査します。いずれかの文字が満足するならば、
@code{string-any}はその適用が返した値を戻り値とします。
どの文字も@var{char/char-set/pred}を満たさなければ、@code{#f}が返ります。
@c COMMON
@end defun

@node SRFI-13 String constructors, SRFI-13 String selection, SRFI-13 String predicates, String library
@subsection String constructors
@c NODE 文字列の構築子

@defun string-tabulate proc len
[SRFI-13]
@c MOD srfi.13
@c EN
@var{proc} must be a procedure that takes an integer
argument and returns a character.  @code{string-tabulate}
creates a string, whose @var{i}-th character is calculated by
@code{(proc i)}.
@c JP
@var{proc}は整数を1つ引数として取り文字を返す手続きで
なければなりません。@code{string-tabulate}は、その@var{i}番目の
文字が@code{(proc i)}で計算されるような文字列を返します。
@c COMMON
@example
(string-tabulate
  (lambda (i) (integer->char (+ i #x30))) 10)
 @result{} "0123456789"
@end example
@end defun

@defun string-unfold p f g seed :optional base make-final
[SRFI-13]
@c MOD srfi.13
@c EN
A fundamental string builder.  The @var{p}, @var{f} and @var{g} are
procedures, taking the current seed value.  The stop predicate @var{p}
determines when to stop: If it returns a true value, string building
stops.  The mapping function @var{f} returns a character
from the current seed value.  The next seed function @var{g} returns
a next seed value from the current seed value.  The @var{seed} argument
gives the initial seed value.
@c JP
基本的な文字列構築手続きです。
@var{p}、@var{f}、@var{g}は手続きで、現在のシード値を受けとります。
停止述語@var{p}はいつ繰り返しを止めるかを判断します。それが真の値を返したら、
文字列構築は終了し、それまでに生成された文字が集められて文字列として返されます。
@var{f}はシード値から文字を生成する手続きです。@var{g}はシード値から次のシード値を
生成します。@var{seed}引数はシード値の初期値を指定します。
@c COMMON

@example
(string-unfold (^n (= n 10))
               (^n (integer->char (+ n 48)))
               (^n (+ n 1))
               0)
  @result{} "0123456789"
@end example

@c EN
The optional argument @var{base} is, when given, prepended to the
result string.  Another optional argument @var{make-final}
is a procedure that takes the last return value of @var{g} and
returns a string that becomes the suffix of the result string.
@c JP
省略可能引数@var{base}は、与えられれば生成される文字列のプレフィクスとなります。
@var{make-final}は手続きで、繰り返しが終了した後の最後のシード値を受け取り、
文字列のサフィックスを返します。
@c COMMON

@example
(string-unfold (^n (= n 10))
               (^n (integer->char (+ n 48)))
               (^n (+ n 1))
               0 "foo" x->string)
  @result{} "foo012345678910"
@end example
@end defun

@defun string-unfold-right p f g seed :optional base make-final
[SRFI-13]
@c MOD srfi.13
@c EN
Another fundamental string builder.  The meanings of arguments
are the same as @code{string-unfold}.  The only difference is
that the string is build right-to-left.  The optional @var{base},
if given, becomes the suffix of result, and the result of
@var{make-final} becomes the prefix.
@c JP
もうひとつの基本的な文字列構築器です。引数の意味は@code{string-unfold}と
同じですが、@var{f}の返す文字が右から左へと並べられます。
また、章句可能な@var{base}引数はサフィックスに、
@var{make-final}が返す文字列はプレフィクスになります。
@c COMMON

@example
(string-unfold-right (^n (= n 10))
                     (^n (integer->char (+ n 48)))
                     (^n (+ n 1))
                     0 "foo" x->string)
  @result{} "109876543210foo"
@end example
@end defun


@defun reverse-list->string char-list
[SRFI-13]
@c MOD srfi.13
@equiv{} @code{(list->string (reverse char-list))}.
@end defun

@node SRFI-13 String selection, SRFI-13 String comparison, SRFI-13 String constructors, String library
@subsection String selection
@c NODE 文字列の選択

@defun substring/shared s start :optional end
[SRFI-13]
@c MOD srfi.13
@c EN
In Gauche, this is the same as @code{substring}, except
that the @var{end} argument is optional.
@c JP
Gaucheでは、引数@var{end}がオプショナルであることを除いて、
@code{substring}と同じです。
@c COMMON
@example
(substring/shared "abcde" 2) @result{} "cde"
@end example
@end defun

@defun string-copy! target tstart s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Copies a string @var{s} into a string
@var{target} from the position @var{tstart}.
The @var{target} string must be mutable.
Optional @var{start} and @var{end} arguments limits the range of @var{s}.
If the copied string run over the end of @var{target}, an error is
signaled.
@c JP
文字列@var{s}を、文字列@var{target}の@var{tstart}番目以降へコピーします。
@var{target}文字列は変更可能でなければなりません。
オプションの引数@var{start}と@var{end}は、@var{s}の範囲を制限します。
コピーされた文字列が@var{target}の終端を越えたらエラーが通知されます。
@c COMMON
@example
(define s (string-copy "abcde"))
(string-copy! s 2 "ZZ")
s @result{} "abZZe"
@end example

@c EN
It is ok to pass the same string to @var{target} and @var{s}; this
always work even if the regions of source and destination are overlapping.
@c JP
@var{target}と@var{s}に同じ文字列を渡しても構いません。コピー元とコピー先の
領域が重なっていても、コピーは常に正しく行われます。
@c COMMON

@c EN
Note that Gauche encourages you to treat strings as immutable objects.
Internally, a string is an indirect pointer to a immutable entity, and
mutating a string means copying the original entity and creating a new one.
It doesn't ``save allocations''.
Always use the functional version @code{string-copy} unless you
absolutely need to replace a string in-place.
@xref{String utilities}.
@c JP
Gaucheでは、文字列を変更不可なオブジェクトとして扱うことを強く推奨しています。
内部的に、文字列オブジェクトは変更不可な文字列の実体へのポインタとなっています。
文字列を変更すると、新たな文字列実体がアロケートされそれが変更されるので、
破壊的手続きを使えばメモリアロケーションが節約できるということはありません。
どうしても文字列そのものを破壊的変更したい場合でない限りは、
非破壊版の@code{string-copy}を使いましょう。@ref{String utilities}参照。
@c COMMON
@end defun

@defun string-take s nchars
@defunx string-drop s nchars
@defunx string-take-right s nchars
@defunx string-drop-right s nchars
[SRFI-13]
@c MOD srfi.13
@c EN
Returns the first @var{nchars}-character string of @var{s}
(@code{string-take}) or the string without first @var{nchars}
(@code{string-drop}).  The @code{*-right} variation counts from
the end of string.  It is guaranteed that the returned string is
always a copy of @var{s}, even no character is dropped.
@c JP
@code{string-take}は、@var{s}の最初の@var{nchars}文字からなる文字列を返します。
@code{string-drop}は、@var{s}から最初の@var{nchars}文字からなる文字列を
除いた残りを返します。@code{*-right}バージョンは、文字列の最後から数えます。
返される文字列はいつも@var{s}のコピーであり、どの文字も削除されないことが
保証されています。
@c COMMON
@example
(string-take "abcde" 2) @result{} "ab"
(string-drop "abcde" 2) @result{} "cde"

(string-take-right "abcde" 2) @result{} "de"
(string-drop-right "abcde" 2) @result{} "abc"
@end example
@end defun

@defun string-pad s len :optional char start end
@defunx string-pad-right s len :optional char start end
[SRFI-13]
@c MOD srfi.13
@c EN
If a string @var{s} is shorter than @var{len},
returns a string of @var{len} where @var{char} is
padded to the left or right, respectively.
If @var{s} is longer than @var{len}, the rightmost
or leftmost @var{len} chars are taken.
@var{Char} defaults to @code{#\space}.
If @var{start} and @var{end} are provided,
the substring of @var{s} is used as the source.
@c JP
文字列@var{s}が@var{len}より短い場合は、@var{char}がそれぞれ左か
右にパディングされた長さ@var{len}の文字列を返します。
@var{s}が@var{len}よりも長い場合は、@var{len}文字が右端か左端から
取り除かれます。@var{Char}のデフォルト値は@code{#\space}です。
@var{start}と@var{end}が与えられると、@var{s}の部分文字列がソース
文字列として使われます。
@c COMMON

@example
(string-pad "abc" 10)    @result{} "       abc"
(string-pad "abcdefg" 3) @result{} "efg"

(string-pad-right "abc" 10) @result{} "abc       "

(string-pad "abcdefg" 10 #\+ 2 5)
  @result{} "+++++++cde"
@end example
@end defun

@defun string-trim s :optional char/char-set/pred start end
@defunx string-trim-right s :optional char/char-set/pred start end
@defunx string-trim-both s :optional char/char-set/pred start end
[SRFI-13]
@c MOD srfi.13
@c EN
Removes characters that match @var{char/char-set/pred}
from @var{s}.  @code{String-trim} removes the characters from
left of @var{s}, @code{string-trim-right} does from right,
and @code{string-trim-both} does from both sides.
@c JP
@var{s}から@var{char/char-set/pred}にマッチする文字を削除します。
@code{String-trim}は@var{s}の左から文字を削除し、
@code{string-trim-right}は右から、@code{string-trim-both}は
両端から削除します。
@c COMMON
@c EN
@var{Char/char-set/pred} defaults to @code{#[\s]}, i.e. a char-set
of whitespaces.
If @var{start} and @var{end} are provided,
the substring of @var{s} is used as the source.
@c JP
@var{Char/char-set/pred}のデフォルト値は@code{#[\s]}、つまり空白文字の
文字集合です。@var{start}と@var{end}が与えられると、@var{s}の部分文字列が
ソース文字列として使われます。
@c COMMON

@example
(string-trim "   abc  ")       @result{} "abc  "
(string-trim-right "   abc  ") @result{} "   abc"
(string-trim-both "   abc  ")  @result{} "abc"
@end example
@end defun

@node SRFI-13 String comparison, SRFI-13 String prefixes & suffixes, SRFI-13 String selection, String library
@subsection String comparison
@c NODE 文字列の色々な比較

@defun string-compare s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
@defunx string-compare-ci s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Compares two strings @var{s1} and @var{s2} codepoint-wise from left.
When mismatch is found at the index @var{k} of @var{s1},
calls @var{proc<} with @var{k} if @var{s1}'s codepoint is smaller than
the corresponding @var{s2}'s, or calls @var{proc>} if @var{s1}'s one is
greater than @var{s2}'s.  If two strings are the same, calls @var{proc=}
with the index of the last compared position in @var{s1}.
@c JP
文字列@var{s1}と@var{s2}をコードポイント毎に左から比較します。
不一致が@var{s1}のインデックス@var{k}で見つかった場合、対応する@var{s2}の
コードポイントより@var{s1}のコードポイントの方が小さければ
@var{proc<}を@var{k}を引数にして呼び出し、逆に大きければ
@var{proc>}を@var{k}を引数にして呼び出します。
二つの文字列が等しければ、@var{proc=}が、@var{s1}の比較された最後のインデックスを
引数にして呼び出されます。
@c COMMON

@example
(string-compare "abcd" "abzd"
                (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)))
  @result{} (< 2)

(string-compare "abcd" "abcd"
                (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)))
  @result{} (= 3)
@end example

@c EN
The optional arguments restricts
the range of the input strings; however, the index passed to one
of the procedures is always an index from the beginning of @var{s1}.
@c JP
省略可能引数は入力の文字列の比較すべき範囲を制限します。
但し、@var{proc<}、@var{proc=}、@var{proc>}に渡されるインデックスは
常に@var{s1}の最初から数えたものになります。
@c COMMON

@example
(string-compare "zzabcdyy" "abcz"
   (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)) 2 6 0 4)
 @result{} (< 5)

(string-compare "zzabcdyy" "abcz"
   (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)) 2 5 0 3)

 @result{} (= 4)
@end example

@c EN
The case-insensitive variant, @code{string-compare-ci}, compares
each codepoint with character-wise case-folding.  It won't consider
special case folding such as German eszett.
@c JP
@code{string-compare-ci}は大文字小文字を区別しない比較です。
文字毎の大文字小文字変換を行って比較するので、文字列の長さが変わる
大文字小文字変換のケース (ドイツ語のエスツェット等) は考慮されません。
@c COMMON
@end defun

@defun string= s1 s2 :optional start1 end1 start2 end2
@defunx string<> s1 s2 :optional start1 end1 start2 end2
@defunx string< s1 s2 :optional start1 end1 start2 end2
@defunx string<= s1 s2 :optional start1 end1 start2 end2
@defunx string> s1 s2 :optional start1 end1 start2 end2
@defunx string>= s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Compare two strings @var{s1} and @var{s2}.  Optional arguments
can limit the portion of strings to be compared.
Comparison is done by character-wise.

Note: The builtin procedures @code{string=?} etc. can also be
used for character-wise string comparison, but they take
arguments differently.  @xref{String comparison}.
@c JP
二つの文字列@var{s1}と@var{s2}を比較します。省略可能引数で
それぞれの文字列の一部のみを比較するように指定できます。
比較は文字ごとに行われます。

註: 組み込み手続きの@code{string=?}等も文字毎の比較に使えますが、
引数の取り方が違います。@ref{String comparison}参照。
@c COMMON
@end defun

@defun string-ci= s1 s2 :optional start1 end1 start2 end2
@defunx string-ci<> s1 s2 :optional start1 end1 start2 end2
@defunx string-ci< s1 s2 :optional start1 end1 start2 end2
@defunx string-ci<= s1 s2 :optional start1 end1 start2 end2
@defunx string-ci> s1 s2 :optional start1 end1 start2 end2
@defunx string-ci>= s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Compare two strings @var{s1} and @var{s2} in case-insensitive way.
Optional arguments can limit the portion of strings to be compared.
Case folding and comparison is done by character-wise, so they don't
consider case folding that affects multiple characters.

Note: We have two other sets of string comparison operations,
both are named as @code{string-ci=?} etc.
The builtin version (@pxref{String comparison}) does character-wise
comparison.  The one in @code{gauche.unicode} uses full-string
case conversion (@pxref{Full string case conversion}).
R7RS version is the latter.
@c JP
二つの文字列@var{s1}と@var{s2}を、大文字小文字を区別せずに比較します。
省略可能引数でそれぞれの文字列の一部のみを比較するように指定できます。
大文字小文字の畳み込みと比較は文字ごとに行われます。複数の文字に
影響を与えるような大文字小文字の畳み込みは考慮しません。

註: Gaucheには他に2種類の大文字小文字を区別しない文字列比較手続き群があります。
どちらも@code{string-ci=?}等のようにクエスチョンマーク付きの名前を持っています。
Gauche組み込みのものは文字毎に大文字小文字を畳み込みます
(@ref{String comparison}参照)。一方、@code{gauche.unicode}にあるものは
文字列としての畳み込みを行います(@ref{Full string case conversion}参照)。
R7RS版は後者です。
@c COMMON
@end defun

@defun string-hash s :optional bound start end
@defunx string-hash-ci s :optional bound start end
[SRFI-13]
@c MOD srfi.13
@c EN
(Note: Gauche has builtin @code{string-hash} and @code{string-ci-hash}
according to SRFI-128. @xref{Hashing}, for the details.
SRFI-13's API is upper-compatible to SRFI-128's.  The underlying
hash algorithm is the same as the builtin ones, so @code{string-hash}
returns the same value as the builtin ones for the same string
if optional arguments are omitted.
On the other hand, the builtin @code{string-ci-hash} uses string case
folding (e.g. German eszett and @code{SS} are the same), while
SRFI-13's @code{string-hash-ci} uses character-wise case folding.
Unless there's a strong reason, we recommend new code should use
builtin SRFI-128 version instead of SRFI-13.)

Calculates hash value of a string @var{s}.  For @code{string-hash-ci},
character-wise case folding is done before calculating the hash value.

If the optional @var{bound} argument is given, it must be a positive
exact integer, and the return value is limited below it.
The optional @var{start} and @var{end} arguments allows
using that portion for calculation.
@c JP
(註: Gaucheは、SRFI-128に準拠した@code{string-hash}と@code{string-ci-hash}を
組み込みで持っています。詳しくは@ref{Hashing}参照。
SRFI-13のAPIはSRFI-128の上位互換になっています。内部で使っているハッシュ
アルゴリズムは一緒なので、省略可能引数を全て省略したSRFI-13の@code{string-hash}は、
組み込みの@code{string-hash}と同じ値を返します。
一方、組み込みの@code{string-ci-hash}は文字列として大文字小文字の畳み込みを
行います(ドイツ語のエスツェットと@code{SS}は等しく扱われます)が、SRFI-13の
@code{string-hash-ci}は文字毎に大文字小文字を畳み込むように定められているので、
結果が異なる可能性があります。特に強い理由がなければ、新しいコードは
組み込みのSRFI-128版を使うことをおすすめします。)

文字列@var{s}のハッシュ値を計算して返します。@code{string-hash-ci}では
ハッシュ値を計算する前に各文字について大文字小文字を畳み込みを行います。

省略可能引数@var{bound}は、与えられたなら正の正確な整数でなければならず、
返される値は0から@code{(- bound 1)}までの値に制限されます。
@var{start}と@var{end}は、与えられれば@var{s}中の対象となる部分文字列を
指定します。
@c COMMON
@end defun

@node SRFI-13 String prefixes & suffixes, SRFI-13 String searching, SRFI-13 String comparison, String library
@subsection String prefixes & suffixes
@c NODE 文字列のプリフィックスとサフィックス

@defun string-prefix-length s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-length s1 s2 :optional start1 end1 start2 end2
@defunx string-prefix-length-ci s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-length-ci s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Returns the length of the longest common prefix/suffix of two strings,
@var{s1} and @var{s2}.  The optional arguments restrict the range of
search.  The @code{*-ci} variations use case folding character comparison.
@c JP
二つの文字列@var{s1}と@var{s2}の、共通するプレフィクスもしくはサフィックスの
長さを返します。省略可能引数はそれぞれの文字列の探索範囲を限定します。
@code{*-ci}版は文字ごとに、大文字小文字を区別しない比較を行います。
@c COMMON

@example
(string-prefix-length "abacus" "abalone")   @result{} 3
(string-prefix-length "machine" "umbrella") @result{} 0
(string-suffix-length "peeking" "poking")   @result{} 4

(string-prefix-length "obvious" "oblivious" 2 7 4 9)
  @result{} 5
@end example
@end defun

@defun string-prefix? s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix? s1 s2 :optional start1 end1 start2 end2
@defunx string-prefix-ci? s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-ci? s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Returns true iff @var{s1} is a prefix or suffix of @var{s2}, respectively.
The optional arguments limit the range of @var{s1} and @var{s2} to look at.
The @code{*-ci} variations use case folding character comparison.
@c JP
それぞれ、@var{s1}が@var{s2}のプレフィクスまたはサフィックスになっていた場合に
@code{#t}を、それ以外の場合に@code{#f}を返します。
省略可能引数はそれぞれの文字列の探索範囲を限定します。
@code{*-ci}版は文字ごとに、大文字小文字を区別しない比較を行います。
@c COMMON

@example
(string-prefix? "sch" "scheme")   @result{} #t
(string-prefix? "lisp" "scheme")  @result{} #f

(string-suffix? "eme" "scheme")   @result{} #t
(string-suffix? "eme" "lisp")     @result{} #f

(string-prefix? "mit-scheme" "scheme-family" 4) @result{} #t
@end example
@end defun

@node SRFI-13 String searching, SRFI-13 String case mapping, SRFI-13 String prefixes & suffixes, String library
@subsection String searching
@c NODE 文字列の探索

@defun string-index s char/char-set/pred :optional start end
@defunx string-index-right s char/char-set/pred :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Looks for the first element in a string @var{s}
that matches @var{char/char-set/pred}, and returns its index.
If @var{char/char-set/pred} is not found in @var{s}, returns @code{#f}.
Optional @var{start} and @var{end} limit the range of @var{s} to search.
@c JP
文字列@var{s}の中で、@var{char/char-set/pred}にマッチする
最初の要素を探し、そのインデックスを返します。
@var{s}の中に@var{char/char-set/pred}が見つからない場合は、@code{#f}を
返します。オプションの@var{start}と@var{end}は、@var{s}の中で検索対象と
なる範囲を制限します。
@c COMMON
@example
(string-index "Aloha oe" #\a) @result{} 4
(string-index "Aloha oe" #[Aa]) @result{} 0
(string-index "Aloha oe" #[\s]) @result{} 5
(string-index "Aloha oe" char-lower-case?) @result{} 1
(string-index "Aloha oe" #\o 3) @result{} 6
@end example

@c EN
See also the Gauche built-in procedure @code{string-scan}
(@ref{String utilities}), if you need speed over portability.
@c JP
ポータビリティよりも速度を重視する場合は、Gaucheのビルトイン手続き
@code{string-scan}(@ref{String utilities})を参照して下さい。
@c COMMON
@end defun

@defun string-skip s char/char-set/pred :optional start end
@defunx string-skip-right s char/char-set/pred :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Looks for the first element that does not match
@var{char/char-set/pred} and returns its index.
If such element is not found, returns @code{#f}.
Optional @var{start} and @var{end} limit the range of @var{s} to search.
@c JP
@var{char/char-set/pred}にマッチしない最初の要素を探し、
そのインデックスを返します。そのような要素が見つからない場合、@code{#f}を
返します。オプションの@var{start}と@var{end}は、@var{s}の中で検索対象と
なる範囲を制限します。
@c COMMON
@end defun

@defun string-count s char/char-set/pred :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Counts the number of elements in @var{s}
that matches @var{char/char-set/pred}.
Optional @var{start} and @var{end} limit the range of @var{s} to search.
@c JP
@var{s}の中で、@var{char/char-set/pred}にマッチする要素の数を
カウントします。オプションの@var{start}と@var{end}は、@var{s}の中で検索対象と
なる範囲を制限します。
@c COMMON
@end defun

@defun string-contains s1 s2 :optional start1 end1 start2 end2
@defunx string-contains-ci s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Looks for a string @var{s2} inside another string @var{s1}.
If found, returns an index in @var{s1} from where the matching string
begins.  Returns @code{#f} otherwise.
Optional @var{start1}, @var{end1}, @var{start2} and @var{end2}
limits the range of @var{s1} and @var{s2}.

See also the Gauche built-in procedure @code{string-scan}
(@ref{String utilities}), if you need speed over portability.
@c JP
@var{s1}の中で、文字列@var{s2}を探します。見つかった場合は、
@var{s1}でマッチした文字列が始まるインデックスを返します。そうでなければ、
@code{#f}を返します。
オプションの@var{start1}、@var{end1}、@var{start2}、@var{end2}は、
@var{s1}と@var{s2}の範囲を制限します。

ポータビリティよりも速度を重視する場合は、Gaucheのビルトイン手続き
@code{string-scan}(@ref{String utilities})を参照して下さい。
@c COMMON
@end defun

@node SRFI-13 String case mapping, SRFI-13 String reverse & append, SRFI-13 String searching, String library
@subsection String case mapping
@c NODE 文字列のケース(大文字小文字)マッピング

@defun string-titlecase s :optional start end
@defunx string-titlecase! s :optional start end
@defunx string-upcase s :optional start end
@defunx string-upcase! s :optional start end
@defunx string-downcase s :optional start end
@defunx string-downcase! s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Converts a string @var{s} to titlecase, upcase or downcase,
respectively.  These operations uses character-by-character
mapping provided by @code{char-upcase} etc.  That is, @code{string-upcase}
and @code{string-downcase} can be understood as follow:
@c JP
文字列@var{s}をタイトルケース、大文字、小文字にそれぞれ変換します。
これらの手続きは、文字ごとに@code{char-upcase}等を使った変換を行います。
すなわち、@code{string-upcase}と@code{string-downcase}は以下の操作と
考えることができます。
@c COMMON

@example
(string-upcase s)
  @equiv{} (string-map char-upcase s)
(string-downcase s)
  @equiv{} (string-map char-downcase s)
@end example

@c EN
If you need full case mapping that handles the case when
a character is mapped to more than one characters, use
the procedures with the same name in @code{gauche.unicode} module
(@pxref{Full string case conversion}).
@c JP
一文字がケース変換によって複数文字になるような場合も考慮したい場合は、
@code{gauche.unicode}モジュールに定義されている同名の手続きを使ってください
(@ref{Full string case conversion}参照)。
@c COMMON

@c EN
The linear-update version @code{string-titlecase!}, @code{string-upcase!}
and @code{string-downcase!} destroys @var{s} to store the result.
Note that in Gauche, using those procedures doesn't save anything,
since string mutation is expensive by design.  They are provided merely
for completeness.
@c JP
@code{string-titlecase!}、@code{string-upcase!}、
@code{string-downcase!}はその場で更新するバージョンで、@var{s}を破壊的に
変更します。ただし、Gaucheでは文字列の変更は新たな文字列を作るのと効率的に
何ら変わりがありません。これらの手続きは互換性のためだけに用意されています。
@c COMMON
@end defun


@node SRFI-13 String reverse & append, SRFI-13 String mapping, SRFI-13 String case mapping, String library
@subsection String reverse & append
@c NODE 文字列の反転と追加

@defun string-reverse s :optional start end
@defunx string-reverse! s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Returns a string in which the character positions are reversed
from @var{s}.  @code{string-reverse!} modifies @var{s}.
@c JP
@var{s}の文字の位置を逆順にした文字列を返します。
@code{string-reverse!}は@var{s}そのものを変更します。
@c COMMON
@example
(string-reverse "mahalo") @result{} "olaham"
(string-reverse "mahalo" 3) @result{} "ola"
(string-reverse "mahalo" 1 4) @result{} "aha"

(let ((s (string-copy "mahalo")))
  (string-reverse! s 1 5)
  s)
  @result{} "mlahao"
@end example
@end defun

@defun string-concatenate string-list
[SRFI-13]
@c MOD srfi.13
@c EN
Concatenates list of strings.
@c JP
文字列のリストを連結します。
@c COMMON
@example
(string-concatenate '("humuhumu" "nukunuku" "apua" "`a"))
  @result{} "humuhumunukunukuapua`a"
@end example
@end defun

@defun string-concatenate/shared string-list
@defunx string-append/shared s @dots{}
[SRFI-13]
@c MOD srfi.13
@c EN
``Shared'' version of @code{string-concatenate} and
@code{string-append}.  In Gauche, these are just synonyms of them.
@c JP
@code{string-concatenate}と@code{string-append}の``共有''
バージョンです。Gaucheでは、これらは単に別名です。
@c COMMON
@end defun

@defun string-concatenate-reverse string-list
@defunx string-concatenate-reverse/shared string-list
[SRFI-13]
@c MOD srfi.13
@c EN
Reverses @var{string-list} before concatenation.
``Shared'' version works the same in Gauche.
@c JP
@var{string-list}を連結する前に逆順にします。
Gaucheでは、``共有''バージョンは全く同じ動作をします。
@c COMMON
@end defun

@node SRFI-13 String mapping, SRFI-13 String rotation, SRFI-13 String reverse & append, String library
@subsection String mapping
@c NODE 文字列のマッピング

@defun string-map! proc s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
@code{string-map!} applies @var{proc} on every character of @var{s},
and stores the results into @var{s}.  It is an error if @var{proc} returns
non-character.
@c JP
@code{string-map!}は、@var{s}の全ての文字に対して@var{proc}を
適用し、その結果を@var{s}に格納します。
@var{proc}は文字を返さねばなりません。
@c COMMON
@example
(let ((s (string-copy "wikiwiki")))
  (string-map! char-upcase s 4)
  s)
  @result{} "wikiWIKI"
@end example
@end defun

@defun string-fold kons knil s :optional start end
@defunx string-fold-right kons knil s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Like @var{fold} and @var{fold-right} (@pxref{Walking over lists}),
but works on a string instead of a list.
@c JP
文字列に対して動作する@var{fold}や@var{fold-right} (@ref{Walking over lists}参照)
です。
@c COMMON

@example
(string-fold cons '() "abcde")
  @result{} (#\e #\d #\c #\b #\a)
(string-fold-right cons '() "abcde")
  @result{} (#\a #\b #\c #\d #\e)
@end example
@end defun

@defun string-for-each-index proc s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Call @var{proc} on each index of the string @var{s}, from left to right.
The result of @var{proc} is discarded.
The optional @var{start} and @var{end} arguments can be an integer
index or a string cursor, restricting the range
of the input string to be traversed.
@c JP
@var{proc}を@var{s}の各文字について、左から右の順に呼びます。@var{proc}の結果は
捨てられます。
省略可能な@var{start}と@var{end}引数は整数の文字インデックスか
文字列カーソルで、対象となる文字列の範囲を制限します。
@c COMMON
@end defun

@node SRFI-13 String rotation, SRFI-13 Other string operations, SRFI-13 String mapping, String library
@subsection String rotation
@c NODE 文字列のローテーション

@defun xsubstring s from :optional to start end
[SRFI-13]
@c MOD srfi.13
@c EN
Takes a substring of infinite repetition of string @var{s}
between index @var{from} (inclusive) and index @var{to} (exclusive).
If @var{to} is omitted, the length of @var{s} is assumed.
@c JP
@var{s}が左右に無限に繰り替えされているとみなし、その整数インデックス
の@var{from}から@var{to}までを切り出して返します。
@var{to}が省略された場合は@var{s}の長さが使われます。
@c COMMON

@c EN
For example, if @var{s} is @code{"abcde"}, we repeat it
infinitely to both sides.  So @var{5n}-th character for integer @var{n}
is always @code{#\a}, which extends negative @var{n} as well.
@c JP
例えば、@var{s}が@code{abcde}の場合、まずそれを無限の
文字列@code{...abcdeabcdeabcde...}とみなします。
つまり整数@var{n}に対して@var{5n}番目の文字は常に@code{#\a}です。
これは@var{n}が負の領域にも拡張されます。
@c COMMON

@example
(xsubstring "abcde" 2 10)
  @result{} "cdeabcde"
(xsubstring "abcde" -9 -2)
  @result{} "bcdeabc"
@end example

@c EN
The optional @var{start} and @var{end} arguments can be an integer
index or a string cursor, it works as
@code{(xsubstring (substring s start end) from to)}.
@c JP
省略可能な@var{start}と@var{end}引数は整数の文字インデックスか
文字列カーソルで、与えられた場合、
@code{(xsubstring (substring s start end) from to)}と同じ動作となります。
@c COMMON
@end defun

@defun string-xcopy! target tstart s sfrom :optional sto start end
[SRFI-13]
@c MOD srfi.13
@c EN
It works as
@code{(string-copy! target tstart (xsubstring s sfrom sto start end))}.
@c JP
@code{(string-copy! target tstart (xsubstring s sfrom sto start end))}
と同じ動作をします。
@c COMMON
@end defun

@node SRFI-13 Other string operations, SRFI-13 String filtering, SRFI-13 String rotation, String library
@subsection Other string operations
@c NODE 他の文字列操作

@defun string-replace s1 s2 start1 end1 :optional start2 end2
[SRFI-13]
@c MOD srfi.13
@c EN
Returns a new string whose content is a copy of a string @var{s1}, except
the part beginning from the index
@var{start1} (inclusive) and ending at the index @var{end1} (exclusive)
is replaced by a string @var{s2}.   When optional @var{start2} and @var{end2}
arguments are given, @var{s2} is trimmed first according to them.
The size of the @emph{gap}, @code{(- @var{end1} @var{start1})}, doesn't
need to be the same as the size of the inserted string.
Effectively, this is the same as the following code.
@c JP
文字列@var{s1}の@var{start1}文字目(inclusive)から@var{end1}文字目(exclusive)
までを文字列@var{s2}に置き換えた文字列を新たに作って返します。@var{s1}, @var{s2}は
変更されません。
オプショナルな引数@var{start2}、@var{end2}が与えられた場合は、
@var{s2}がまずそれらによって切り取られて置換文字列として使われます。
置き換える隙間の大きさ、つまり@code{(- @var{end1} @var{start1})}は
@var{s2}と同じ長さである必要はありません。
実質的に、この手続きは次のコードと等価です。
@c COMMON

@example
(string-append (substring s1 0 start1)
               (substring s2 start2 end2)
               (substring s1 end1 (string-length s1)))
@end example
@end defun

@defun string-tokenize s :optional token-set start end
[SRFI-13]
@c MOD srfi.13
@c EN
Splits the string @var{s} into a list of substrings,
where each substring is a maximal non-empty contiguous
sequence of characters from the character set @var{token-set}.
The default of @var{token-set} is @code{char-set:graphic}
(@pxref{Predefined character sets}).

See also Gauche's built-in @code{string-split} (@pxref{String utilities}),
which provides similar features but different criteria.
@c JP
文字列 @var{s} を、@var{token-set} で指定される文字集合で
構成される、空でない最大限連続した文字のシーケンスのそれぞれを
要素とするリストを返します。
@var{token-set} のデフォルト値は @code{char-set:graphic}
(@ref{Predefined character sets}参照)。

同様の機能を提供する、しかし異なる基準を持つ、Gauche の組み込み手続き
@code{string-split} (@ref{String utilities} 参照) も見て下さい。
@c COMMON
@end defun

@node SRFI-13 String filtering, SRFI-13 Low-level string procedures, SRFI-13 Other string operations, String library
@subsection String filtering
@c NODE 文字列のフィルタリング

@defun string-filter char/char-set/pred s :optional start end
@defunx string-delete char/char-set/pred s :optional start end
[SRFI-13]
@c MOD srfi.13
@c EN
Returns a string consists of characters in a string @var{s}
that passes (or don't pass) the test indicated by @var{char/char-set/pred},
respectively.
@c JP
それぞれ、文字列@var{s}中の文字のうち@var{char/char-set/pred}で示される
テストを通る、または通らない文字からなる文字列を返します。
@c COMMON

@example
(string-filter char-upper-case? "Hello, World!")
  @result{} "HW"

(string-delete char-upper-case? "Hello, World!")
  @result{} "ello, orld!"

(string-delete #\l "Hello, World!")
  @result{} "Heo, Word!"

(string-filter #[\w] "Hello, World!")
  @result{} "HelloWorld"
@end example

@c EN
Note: SRFI-13 was revised after finalization to switch
the order of arguments @var{char/char-set/pred} and @var{s} was.
At the time of finalization, the order was
@code{(string-filter s pred)} and Gauche implemented it accordingly.
However, most existing implementations follows the revised order,
since that was what the SRFI-13 reference implementation had.

So, from 0.9.4, we revised the API to comply the current
SRFI-13 spec, but we also accept the old order as well
not to break the old code.
We recommend the new code to use the new order.
@c JP
註: SRFI-13は制定後に改訂され、引数@var{char/char-set/pred}と@var{s}の
順序が逆になりました。制定時点では引数順は
@code{(string-filter s pred)}で、Gaucheもそれに従って実装していました。
しかし既存の実装のほとんどは@code{(string-filter pred s)}という順序に
なっています。SRFI-13の参照実装がそうだったからです。

0.9.4からGaucheも現在のSRFI-13の実装に合わせましたが、
以前の仕様で書かれたコードとの互換性を保つため、
引数順を逆にしても動作するようになっています。
新しく書かれるコードは、現在のSRFI-13の引数順を使うのが良いでしょう。
@c COMMON
@end defun

@node SRFI-13 Low-level string procedures,  , SRFI-13 String filtering, String library
@subsection Low-level string procedures
@c NODE 低レベルな文字列に関する手続き

@c EN
Here are some helper procedures useful
to write other string-processing utilities similar to SRFI-13:
@c JP
SRFI-13に似せた他の文字列処理ユーティリティを書くのに便利なヘルパー関数です。
@c COMMON


@defun string-parse-start+end proc s args
@defunx string-parse-final-start+end proc s args
[SRFI-13]
@c MOD srfi.13
@c EN
Most SRFI-13 procedures takes optional start and end arguments.
These procedures looks for them in the rest arguments @var{args},
and if they're not provided, gives the default values.
@c JP
多くのSRFI-13の手続きは、省略可能引数としてstartとend引数を取ります。
この手続きは、残余引数リスト@var{args}にstartとendが指定されているかを調べ、
指定されていればそれらを、されていなければ適切なデフォルト値を返します。
@c COMMON

@c EN
The @var{proc} argument is the name (symbol) of the procedure,
to be used in the error condition, and @var{s} is the string to be processed.
@c JP
@var{proc}はエラー通知に使われる手続きの名前 (シンボル)、
@var{s}は処理すべき文字列です。
@c COMMON

@c EN
Both expects an optional @var{start} argument at the beginning of @var{args},
followed by an optional @var{end} argument.  If the @var{end} argument
is missing, the length of @var{s} is assumed.  If the @var{start} argument
is also missing, @code{0} is assumed.
If arguments are provided, they must be exact integers,
and @code{0} <= @var{start} <= @code{end} <= @code{(string-length @var{s})} must
be satisfied; otherwise, an error is signaled.
@c JP
どちらの手続きも、@var{args}の最初に@var{start}引数があり、その次に@var{end}引数が
あることを期待します。@var{end}引数が省略されていた場合は@var{s}の長さが、
@var{start}引数も省略されていた場合は@code{0}が使われます。
引数が与えられた場合は、それらは正確な整数で
@code{0} <= @var{start} <= @code{end} <= @code{(string-length @var{s})}
を満たしていなければなりません。そうでなければエラーが投げられます。
@c COMMON

@c EN
If more than two arguments are in @var{args}, @code{string-parse-final-start+end}
raises an error (in other words, it requires that the argument list
end with the @var{end} argument at most), while @code{string-parse-start+end}
permits it and returns the result of arguments, along with start and
end indexes.
@c JP
@var{args}に二つ以上の引数が含まれていた場合、
@code{string-parse-final-start+end}はエラーを通知します
(つまり、最長でも引数リストが@var{end}引数で終わる場合に使えます)。
一方、@code{string-parse-start+end}は、余分な引数を許し、それを
start/endの値とともに返します。
@c COMMON

@c EN
Both function return three values: The rest of the argument list,
the start index, and the end index.
@c JP
どちらの関数も3つの値を返します。余分な引数のリスト、startの値、endの値です。
@c COMMON
@end defun

@defmac let-string-start+end (start end [rest]) proc-exp s-exp args-exp body @dots{}
[SRFI-13]
@c MOD srfi.13
@end defmac

@defun check-substring-spec proc s start end
@defunx substring-spec-ok? s start end
[SRFI-13]
@c MOD srfi.13
@end defun

@defun make-kmp-restart-vector s :optional c= start end
[SRFI-13]
@c MOD srfi.13
@end defun

@defun kmp-step pat rv c i c= p-start
[SRFI-13]
@c MOD srfi.13
@end defun

@defun string-kmp-partial-search pat rv s i :optional c= p-start s-start s-end
[SRFI-13]
@c MOD srfi.13
@end defun

@c ----------------------------------------------------------------------
@node Time data types and procedures, Sources of random bits, String library, Library modules - SRFIs
@section @code{srfi.19} - Time data types and procedures
@c NODE 時間のデータ型と手続き, @code{srfi.19} - 時間のデータ型と手続き

@deftp {Module} srfi.19
@mdindex srfi.19
@c EN
This SRFI defines various representations of time and date, and
conversion methods among them.
@c JP
このSRFIは、時間と日付に関する様々な表現と、それらの間の変換メソッドを提供します。
@c COMMON

@c EN
On Gauche, time object is supported natively by @code{<time>} class
(@pxref{Time}).  Date object is supported by @code{<date>} class
described below.
@c JP
Gaucheでは、timeオブジェクトは@code{<time>}クラスとして組み込みで
サポートされています(@ref{Time}参照)。dateオブジェクトは以下で説明する
@code{<date>}クラスとしてサポートされます。
@c COMMON
@end deftp

@menu
* SRFI-19 Time types::
* SRFI-19 Time queries::
* SRFI-19 Time procedures::
* SRFI-19 Date::
* SRFI-19 Date reader and writer::
@end menu

@node SRFI-19 Time types, SRFI-19 Time queries, Time data types and procedures, Time data types and procedures
@subsection Time types
@c NODE 時間のタイプ

@c EN
Time type is represented by a symbol.  This module defines
the following constant variables that is bound to its name, for
convenience.
@c JP
時間のタイプはシンボルで表現されます。
このモジュールでは以下の定数が自分の名前に束縛された形で提供されています。
@c COMMON

@defvr {Constant} time-utc
[SRFI-19]
@c MOD srfi.19
@c EN
UTC time.  Gauche's built-in @code{current-time} always returns
this type (@pxref{Time}).
@c JP
UTC timeです。Gaucheの組み込みの@code{current-time}は常にこのタイプの時間を
返します (@ref{Time}参照)。
@c COMMON
@end defvr

@defvr {Constant} time-tai
[SRFI-19]
@c MOD srfi.19
@c EN
International Atomic Time.  This time is a bit larger than UTC, due to
the leap seconds.
@c JP
International Atomic Time。この時間は閏秒による調整を受けないため、
UTCより若干大きな値を取ります。
@c COMMON
@end defvr

@defvr {Constant} time-monotonic
[SRFI-19]
@c MOD srfi.19
@c EN
Implementation-dependent monotonically increasing time.
In Gauche, this is the same as @code{time-tai}.
@c JP
実装依存の、単調増加する時間。Gaucheの実装ではこれは@code{time-tai}と同じです。
@c COMMON
@end defvr

@defvr {Constant} time-duration
[SRFI-19]
@c MOD srfi.19
@c EN
Duration between two absolute time points.
@c JP
二つの絶対的な時点の間の期間。
@c COMMON
@end defvr

@defvr {Constant} time-process
[SRFI-19]
@c MOD srfi.19
@c EN
CPU time in current process.
Gauche calculates this from user time and system time returned by
POSIX times(3).
@c JP
現在のプロセスのCPU時間。
Gaucheは、POSIX time(3)コールが返すユーザ時間とシステム時間の合計からこの値を
計算します。
@c COMMON
@end defvr

@defvr {Constant} time-thread
[SRFI-19]
@c MOD srfi.19
@c EN
CPU time in current thread.
In the current implementation, this is the same as @code{time-process}.
@c JP
現在のスレッドのCPU時間。
現在の実装ではこれは@code{time-process}と同じです。
@c COMMON
@end defvr

@node SRFI-19 Time queries, SRFI-19 Time procedures, SRFI-19 Time types, Time data types and procedures
@subsection Time queries
@c NODE 時間に関する問い合わせ

@defun current-time :optional time-type
[SRFI-19]
@c MOD srfi.19
@c EN
Extends Gauche built-in @code{current-time} (@pxref{Time}) to take
optional @var{time-type} argument to specify the desired time type.
@var{time-type} must be one of the types described in @ref{SRFI-19 Time types}.
@c JP
Gauche組み込みの@code{current-time} (@ref{Time}参照)を拡張して、
必要な時間のタイプを省略可能な引数@var{time-type}で指定できるようにしています。
可能な@var{time-type}の値は@ref{SRFI-19 Time types}で説明されているものです。
@c COMMON
@end defun

@defun current-date :optional tz-offset
[SRFI-19]
@c MOD srfi.19
@c EN
Returns the current date as an instance of @code{<date>} class
(@pxref{SRFI-19 Date}).  If @var{tz-offset} is given, it must be
an offset from UTC in number of seconds.  If @var{tz-offset} is
not given, returns the date in local time zone.
@c JP
現在の日付を@code{<date>}クラスのインスタンスとして返します(@ref{SRFI-19 Date}参照)。
@var{tz-offset}が与えられた場合、それがUTCからのオフセットを表す秒数として
使われます。@var{tz-offset}が与えられなかった場合はローカルタイムゾーンで
表現された日付が返されます。
@c COMMON
@end defun

@defun current-julian-day
[SRFI-19]
@c MOD srfi.19
@c EN
Returns the current julian day, a point in time as a real number of
days since -4714-11-24T12:00:00Z (November 24, -4714 at noon, UTC).
@c JP
現在のユリウス日(Julian day)を返します。Julian dayは
-4714-11-24T12:00:00Z (November 24, -4714 at noon, UTC) からの日数を
実数で表現したものです。
@c COMMON
@end defun

@defun current-modified-julian-day
[SRFI-19]
@c MOD srfi.19
@c EN
Returns the current modified julian day, a point in time as a real
number of days since 1858-11-17T00:00:00Z
(November 17, 1858 at midnight, UTC).
@c JP
現在の修正ユリウス日(Modified julian day)を返します。Modified julian dayは
1858-11-17T00:00:00Z (November 17, 1858 at midnight, UTC)
からの日数を実数で表現したものです。
@c COMMON
@end defun

@defun time-resolution :optional type
[SRFI-19]
@c MOD srfi.19
@c EN
Returns clock resolution of the time type @var{type} in nanoseconds,
as an exact positive integer.  If @var{type} is omitted, @code{time-utc}
is assumed.

Note: In the current implementation, the return value isn't actual
resolution, but a value that's guaranteed to be equal to or greater
than the actual resolution.
@c JP
時間タイプ@var{type}を計測する時計の粒度を、ナノセコンド単位の正整数として返します。
@var{type}が省略された場合は@code{time-utc}になります。

註: 現在の実装では、これは正確な粒度そのものではなく、
正確な粒度と等しいかより大きい値を返します。
@c COMMON
@end defun


@node SRFI-19 Time procedures, SRFI-19 Date, SRFI-19 Time queries, Time data types and procedures
@subsection Time procedures
@c NODE 時間に関する手続き

@defun make-time type nanoseconds seconds
[SRFI-19]
@c MOD srfi.19
@c EN
Returns an instance of @code{<time>} class with specified initial values.
Equivalent to @code{(make <time> :type type :second seconds :nanosecond nanoseconds)}.
@c JP
与えられた初期値を持つ@code{<time>}クラスのインスタンスを返します。
@code{(make <time> :type type :second seconds :nanosecond nanoseconds)}
と等価です。
@c COMMON
@end defun

@defun time-type time
@defunx time-second time
@defunx time-nanosecond time
@defunx set-time-type! time type
@defunx set-time-second! time second
@defunx set-time-nanosecond! time nanosecond
[SRFI-19]
@c MOD srfi.19
@c EN
Getter and setter of @code{<time>} object slots.
@c JP
@code{<time>}オブジェクトのスロットのアクセサです。
@c COMMON
@end defun

@defun copy-time time
[SRFI-19]
@c MOD srfi.19
@c EN
Returns a new instance of @code{<time>} whose content is the same as
given @var{time}
@c JP
与えられた@var{time}と同じ内容の新しい@code{<time>}オブジェクトを返します。
@c COMMON
@end defun

@defun time=? time0 time1
@defunx time<? time0 time1
@defunx time<=? time0 time1
@defunx time>? time0 time1
@defunx time>=? time0 time1
[SRFI-19]
@c MOD srfi.19
@c EN
Compares two times.  Types of both times must match.
@c JP
二つの時間を比較します。時間のタイプは一致していなければなりません。
@c COMMON
@end defun

@defun time-difference time0 time1
@defunx time-difference! time0 time1
[SRFI-19]
@c MOD srfi.19
@c EN
Returns the difference of two times, in @code{time-duration} time.
Types of both times must match.
@code{Time-difference!} modifies @var{time0} to store the result.
@c JP
二つの時間の差を@code{time-duration}タイプの時間として返します。
二つの時間のタイプは一致していなければなりません。
@code{Time-difference!}は結果を格納するために@var{time0}を変更します。
@c COMMON
@end defun

@defun add-duration time0 time-duration
@defunx add-duration! time0 time-duration
@defunx subtract-duration time0 time-duration
@defunx subtract-duration! time0 time-duration
[SRFI-19]
@c MOD srfi.19
@c EN
Adds or subtracts @var{time-duration} to or from @var{time0}.
Type of returned time is the same as @var{time0}.  Type of
@var{time-duration} must be @code{time-duration}.
@code{add-duration!} and @code{subtract-duration!} reuse
@var{time0} to store the result.

See also @code{seconds+} (@ref{Time}).
@c JP
@var{time-duration}を@var{time0}に加算、または@var{time0}から減算します。
返される時間のタイプは@var{time0}と同じです。@var{time-duration}のタイプは
@code{time-duration}でなければなりません。
@code{add-duration!}と@code{subtract-duration!}は結果を格納するのに
@var{time0}を再利用します。

@ref{Time}の@code{seconds+}も参照してください。
@c COMMON
@end defun

@node SRFI-19 Date, SRFI-19 Date reader and writer, SRFI-19 Time procedures, Time data types and procedures
@subsection Date
@c NODE 日付

@deftp {Class} <date>
@clindex date
@c MOD srfi.19
@c EN
Represents a date.
@c JP
日付を表現します。
@c COMMON

@defivar <date> nanosecond
@c EN
Nanosecond portion of the date by an integer between 0 and 999,999,999,
inclusive.
@c JP
日付のナノ秒部分、0 から 999,999,999 までの整数です。
@c COMMON
@end defivar

@defivar <date> second
@c EN
Second portion of the date by an integer between 0 and 60, inclusive.
(60 for leap second).
@c JP
日付の秒部分、0 から 60 までの整数です。(60 は閏秒)
@c COMMON
@end defivar

@defivar <date> minute
@c EN
Minute portion of the date by an integer between 0 and 59, inclusive.
@c JP
日付の分部分、0 から 59 までの整数です。
@c COMMON
@end defivar

@defivar <date> hour
@c EN
Hour portion of the date by an integer between 0 and 23, inclusive.
@c JP
日付の時部分、0 から 23 までの整数です。
@c COMMON
@end defivar

@defivar <date> day
@c EN
Day portion of the date by an integer between 0 and 31, inclusive.
The actual upper bound of the day is determined by the year and the month.
(Note: 1 is for the first day; 0 is allowed by the specification,
but I don't see why).
@c JP
日付の日部分、0 から 31 日までの整数です。実際の上限は年と月によって決定
されます。(註: 1 は朔日(ついたち)、0 は仕様では認められていますが、
なぜなのかはわかりません。)
@c COMMON
@end defivar

@defivar <date> month
@c EN
Month portion of the date by an integer between 1 and 12, inclusive.
1 for January, 2 for February, and so on.
(Note: this is different from POSIX's @code{<sys-tm>} convention).
@c JP
日付の月部分、1 から 12 までの整数です。1 は一月、2 は二月、以下同様です。
(註: これは POSIX の @code{<sys-tm>} の命名法とは異ります。)
@c COMMON
@end defivar

@defivar <date> year
@c EN
Year portion of the date.
@c JP
日付の年部分です。
@c COMMON
@end defivar

@defivar <date> zone-offset
@c EN
The number of seconds east of GMT for this timezone, by an integer.
@c JP
このタイムゾーンが GMT より何秒東にあるかを示す整数です。
@c COMMON
@end defivar
@end deftp

@defun make-date nanosecond second minute hour day month year zone-offset
[SRFI-19]
@c MOD srfi.19
@c EN
Makes a @code{<date>} object from the given values.
Note: this procedure does not check if the values are in the valid range.
@c JP
与えられた値から @code{<date>} オブジェクトを作成します。
註: この手続きは与えられた値が正しい範囲であるかどうかをチェックしません。
@c COMMON
@end defun

@defun date? obj
[SRFI-19]
@c MOD srfi.19
@c EN
Returns true iff @var{obj} is a @code{<date>} object.
@c JP
@var{obj} が @code{<date>} オブジェクトである場合にかぎり真を返します。
@c COMMON
@end defun

@defun date-nanosecond date
@defunx date-second date
@defunx date-minute date
@defunx date-hour date
@defunx date-day date
@defunx date-month date
@defunx date-year date
@defunx date-zone-offset date
[SRFI-19]
@c MOD srfi.19
@c EN
Accessors.
@c JP
アクセサです。
@c COMMON
@end defun

@defun date-year-day date
@defunx date-week-day date
@defunx date-week-number date day-of-week-starting-week
[SRFI-19]
@c MOD srfi.19
@c EN
Calculates the day number in the year (1 for January 1st),
the day number in the week (0 for Sunday, 1 for Monday, ...),
and the ordinal week of the year which holds this date,
ignoring a first partial week, respectively.

@var{Day-of-week-starting-week} is the integer corresponding to
the day of the week which is to be considered the first day of
the week (Sunday=0, Monday=1, etc.).
@c JP
それぞれ、一年の何日目(一月一日が 1)か、何曜日(日曜日が 0、月曜日が 1
など)か、一年のうち何週目(一年の最初の週が一週間に満たない場合はその
週は無視)かを計算します。
@c COMMON
@end defun

@defun date->julian-day date
@defunx date->modified-julian-day date
@defunx date->time-monotonic date
@defunx date->time-tai date
@defunx date->time-utc date
[SRFI-19]
@c MOD srfi.19
@c EN
Conversions from date to various date/time types.
@c JP
日付から様々な様式の日付/時間に変換します。
@c COMMON
@end defun

@defun julian-day->date jd :optional tz-offset
@defunx julian-day->time-monotonic jd
@defunx julian-day->time-tai jd
@defunx julian-day->time-utc jd
[SRFI-19]
@c MOD srfi.19
@c EN
Conversions from julian-day to various date/time types.
@c JP
ユリウス日からから様々な様式の日付/時間に変換します。
@c COMMON
@end defun

@defun modified-julian-day->date jd :optional tz-offset
@defunx modified-julian-day->time-monotonic jd
@defunx modified-julian-day->time-tai jd
@defunx modified-julian-day->time-utc jd
[SRFI-19]
@c MOD srfi.19
@c EN
Conversions from modified julian-day to various date/time types.
@c JP
修正ユリウス日から様々な様式の日付/時間に変換します。
@c COMMON
@end defun

@defun time-monotonic->date time :optional tz-offset
@defunx time-monotonic->julian-day time
@defunx time-monotonic->modified-julian-day time
@defunx time-monotonic->time-tai time
@defunx time-monotonic->time-tai! time
@defunx time-monotonic->time-utc time
@defunx time-monotonic->time-utc! time
[SRFI-19]
@c MOD srfi.19
@c EN
Conversions from time-monotonic to various date/time types.
@c JP
time-monotonic形式から様々な様式の日付/時間に変換します。
@c COMMON
@end defun

@defun time-tai->date time :optional tz-offset
@defunx time-tai->julian-day time
@defunx time-tai->modified-julian-day time
@defunx time-tai->time-monotonic time
@defunx time-tai->time-monotonic! time
@defunx time-tai->time-utc time
@defunx time-tai->time-utc! time
[SRFI-19]
@c MOD srfi.19
@c EN
Conversions from time-tai to various date/time types.
@c JP
time-tai形式から様々な様式の日付/時間に変換します。
@c COMMON
@end defun

@defun time-utc->date time :optional tz-offset
@defunx time-utc->julian-day time
@defunx time-utc->modified-julian-day time
@defunx time-utc->time-monotonic time
@defunx time-utc->time-monotonic! time
@defunx time-utc->time-tai time
@defunx time-utc->time-tai! time
[SRFI-19]
@c MOD srfi.19
@c EN
Conversions from time-utc to various date/time types.
@c JP
UTC 形式から様々な様式の日付/時間に変換します。
@c COMMON
@end defun

@node SRFI-19 Date reader and writer,  , SRFI-19 Date, Time data types and procedures
@subsection Date reader and writer
@c NODE 日付の読み書き

@defun date->string date :optional format-string
[SRFI-19+]
@c MOD srfi.19
@c EN
Converts a @code{<date>} object to a string, according
to the format specified by @var{format-string}.
If @var{format-string} is omitted, @code{"~c"} is assumed.
@c JP
@code{<date>}オブジェクトを文字列に変換します。書式は
@var{format-string}で指定します。@var{format-string}が省略された場合に
は@code{"~c"}が指定されたものとします。
@c COMMON

@c EN
A format string is copied to output, except a sequence begins with
@code{~} which is replaced with the following rules:
@c JP
書式文字列は出力にコピーされます。ただし、@code{~}で始まる並びの部分は
以下の規則にしたがって書き換えられます。
@c COMMON

@c EN
@table @code
@item ~~
A literal @code{~}.
@item ~a
Locale's abbreviated weekday name (Sun...Sat).
@item ~A
Locale's full weekday name (Sunday...Saturday).
@item ~b
Locale's abbreviate month name (Jan...Dec).
@item ~B
Locale's full month name (January...December).
@item ~c
Locale's date and time (e.g., @code{"Fri Jul 14 20:28:42-0400 2000"}).
@item ~d
Day of month, zero padded (01...31).
@item ~D
Date (mm/dd/yy).
@item ~e
Day of month, blank padded ( 1...31).
@item ~f
Seconds+fractional seconds, using locale's decimal separator (e.g. 5.2).
@item ~h
Same as @code{~b}.
@item ~H
Hour, zero padded, 24-hour clock (00...23).
@item ~I
Hour, zero padded, 12-hour clock (01...12).
@item ~j
Day of year, zero padded.
@item ~k
Hour, blank padded, 24-hour clock ( 0...23).
@item ~l
Hour, blank padded, 12-hour clock ( 1...12).
@item ~m
Month, zero padded (01...12).
@item ~M
Minute, zero padded (00...59).
@item ~n
New line.
@item ~N
Nanosecond, zero padded.
@item ~p
Locale's AM or PM.
@item ~r
Time, 12 hour clock, same as @code{"~I:~M:~S ~p"}.
@item ~s
Number of full seconds since "the epoch" (in UTC).
@item ~S
Second, zero padded (00...60).
@item ~t
Horizontal tab.
@item ~T
Time, 24 hour clock, same as @code{"~H:~M:~S"}.
@item ~U
Week number of year with Sunday as first day of week (00...53).
@item ~V
ISO8601 Week number of year with Monday as first day of week.
The week with the first Thursday is week 01.  If there's a partial
week before that, it becomes week 52 or 53 of the preceding year
(01...53).
@item ~w
Day of week (0...6).
@item ~W
Week number of year with Monday as first day of week (00...52).
@item ~x
Locale's date representation, for example: @code{"07/31/00"}.
@item ~X
Locale's time representation, for example: @code{"06:51:44"}.
@item ~y
Last two digits of year (00...99).
@item ~Y
Year.
@item ~z
Time zone in RFC-822 style.
@c @item ~Z
@c Symbol time zone (not-implemented).
@item ~1
ISO-8601 year-month-day format, e.g. @code{"2001-02-03"}.
@item ~2
ISO-8601 hour-minute-second-timezone format, e.g. @code{"04:56:12-1000"}.
@item ~3
ISO-8601 hour-minute-second format, e.g. @code{"04:56:12"}.
@item ~4
ISO-8601 year-month-day-hour-minute-second-timezone format,
e.g. @code{"2001-02-03T04:56:12-1000"}.
@item ~5
ISO-8601 year-month-day-hour-minute-second format,
e.g. @code{"2001-02-03T04:56:12"}.
@end table
@c JP
@table @code
@item ~~
文字@code{~}そのもの。
@item ~a
ロケールによる曜日省略形(Sun...Sat)
@item ~A
ロケールによる曜日完全形(Sunday...Saturday)
@item ~b
ロケールによる月省略形(Jan...Dec)
@item ~B
ロケールによる月完全形(January...December)
@item ~c
ロケールによる日付時刻(例えば @code{"Fri Jul 14 20:28:42-0400 2000"})
@item ~d
月日にち、0を補填(01...31)
@item ~D
日付(mm/dd/yy)
@item ~e
月日にち、空白補填( 1...31)
@item ~f
秒 + 小数秒、小数点はロケールによるセパレータ(たとえば、5.2)
@item ~h
@code{~b} に同じ
@item ~H
時、0を補填、24時制(00...23)
@item ~I
時、0を補填、12時制(01...12)
@item ~j
年日にち、0補填(001...366)
@item ~k
時、空白補填、24時制( 0...23)
@item ~l
時、空白補填、12時制( 1...12)
@item ~m
月、0補填、(01...12)
@item ~M
分、0補填、(00...59)
@item ~n
改行
@item ~N
ナノ秒、0補填
@item ~p
ロケールによるAM、PM
@item ~r
時刻、12時制、@code{"~I:~M:~S ~p"}と同じ
@item ~s
エポックからの経過秒(UTC)
@item ~S
秒、0補填(00...60)
@item ~t
水平タブ
@item ~T
時刻、24時制、@code{"~H:~M:~S"}と同じ
@item ~U
年経過週、週は日曜はじまり(00...53)
@item ~V
ISO8601形式の年経過週、週は月曜はじまり。年の最初の木曜日を含む週が01となり、
それ以前の週にはみ出た部分は前年の52または53週となる (01...53)
@item ~w
曜日を表す数字、日曜が0 (0...6)
@item ~W
年経過週、週は月曜日はじまり(00...52)
@item ~x
ロケールによる日付、例えば @code{"07/31/00"}
@item ~X
ロケールによる時刻、24時制、例えば @code{"06:51:44"}
@item ~y
西暦の下2桁(00...99)
@item ~Y
西暦
@item ~z
RFC-2822スタイルのタイムゾーン
@c @item ~Z
@c Symbol time zone (not-implemented).
@item ~1
ISO-8601 の「年-月-日」形式。例えば @code{"2001-02-03"}
@item ~2
ISO-8601 の「時-分-秒タイムゾーン」形式。例えば @code{"04:56:12-1000"}
@item ~3
ISO-8601 の「時:分:秒」形式。例えば @code{"04:56:12"}
@item ~4
ISO-8601 の「西暦-月-日T時:分:秒タイムゾーン」形式。
例えば @code{"2001-02-03T04:56:12-1000"}
@item ~5
ISO-8601 の「西暦-月-日T時:分:秒」形式。
例えば @code{"2001-02-03T04:56:12"}
@end table
@c COMMON

@c EN
Note: currently Gauche doesn't honor process's locale setting,
and it always formats the date as if the locale is "C".  It may
be changed in future, so you shouldn't rely on, for example,
@code{~a} always formatted as "Sun".."Sat".
@c JP
注意：現時点でGaucheはロケールの設定には従っておらず、常にロケールが
"C" に設定されているものとしてフォーマットします。これについては将来変
更する可能性がありますので、現在の振舞いを前提として、たとえば、
@code{~a}が常に"Sun".."Sat"のようにフォーマットされることを前提にプロ
グラムしてはいけません。
@c COMMON

@c EN
There's no portable way to ensure you'll get "C" locale formats
since there's no standard way to set process's locale yet.
However, Gauche provides a way to ensure the locale to be "C",
as an extension to srfi-19.
Insert @code{@@} between @code{~} and the directive
character, such as @code{~@@a}.
@c JP
いまのところプロセスのロケールを設定する標準的な方法がないので、
"C"ロケール形式を取得できるかどうかを確かめるポータブルな方法がありま
せん。とはいえ、Gaucheでは SRFI-19の拡張として"C"ロケールであることを
確認する方法を提供しています。@code{@@} を @code{~} とディレクティブ文
字の間に挿入し、@code{~@@a} のようにします。
@c COMMON
@end defun

@defun string->date string template-string
[SRFI-19]
@c MOD srfi.19
@c   [NB] srfi-19's string->date is broken, in both spec and reference
@c   implementation.  I'm wondering whether I should change string->date
@c   to make usable, or introduce another procedure, like string->date*,
@c   which fixes the problem.
@c
@c Both procedures parse a string representation of date in @var{string},
@c according to the format given in @var{template-string}.

@c The input string must match the @var{template-string},
@c except tilde-directives described below, which matches
@c one or more component(s) of the date.  If the input string
@c is parsed successfully, a @code{<date>} object is returned
@c with the matched components are filled.

@c If the input string does not match @var{template-string},
@c an error is signaled.  (The SRFI-19 spec doesn't explicitly
@c state what happens if @code{string->date} doesn't accept the
@c input, which actually reduces usability of @code{string->date}

@c but the reference implementation signals an error, and
@c it would be safe to assume


@c @table @code
@c @item ~~
@c Matches literal @code{~}.
@c @item ~a
@c Skip to an alphanumeric character, then matches abbreviated
@c weekday in locale.  Match result is ignored.
@c @item ~A
@c Skip to an alphanumeric character, then matches full
@c weekday in locale.  Match result is ignored.
@c @item ~b
@c Skip to an alphanumeric character, then matches abbreviated
@c month name in locale.  Sets the month component of the date.
@c @item ~B
@c Skip to an alphanumeric character, then matches full
@c month name in locale.  Sets the month component of the date.
@c @item ~d
@c Skip to a numeric character, then matches the day of month.
@c Sets the month component of the date.
@c @item ~e

@c ~e	any	day of month, blank padded	date-day
@c ~h	char-alphabetic?	same as ~b	nothing
@c ~H	char-numeric?	hour	date-hour
@c ~k	any	hour, blank padded	date-hour
@c ~m	char-numeric?	month	date-month
@c ~M	char-numeric?	minute	date-minute
@c ~S	char-numeric?	second	date-second
@c ~y	any	2-digit year	date-year within 50 years
@c ~Y	char-numeric?	year	date-year
@c ~z	any	time zone	date-zone-offset@end table

@end defun

@c ----------------------------------------------------------------------
@node Sources of random bits, Localization, Time data types and procedures, Library modules - SRFIs
@section @code{srfi.27} - Sources of Random Bits
@c NODE ランダムビットのソース, @code{srfi.27} - ランダムビットのソース

@deftp {Module} srfi.27
@mdindex srfi.27
@c EN
This module provides SRFI-27 pseudo random generator interface,
using Mersenne Twister algorithm
(@pxref{Mersenne-Twister random number generator}) as the backbone.
@c JP
このモジュールはメルセンヌツイスタアルゴリズム
(@ref{Mersenne-Twister random number generator} 参照)
を基礎に用いたSRFI-27疑似乱数発生器インタフェースを提供します。
@c COMMON

@c EN
The random sources provided in this module is thread safe; multiple thread
can use the same random source without breaking its internal state.
@c JP
このモジュールが提供する乱数発生源はスレッドセーフです。
複数のスレッドが同じ乱数発生源を使っても内部状態を壊してしまうことはありません。
@c COMMON
@end deftp

@defun random-integer n
[SRFI-27]
@c MOD srfi.27
@c EN
Returns a random exact integer between [0, @var{n}-1], inclusive,
using the default random source.
To set a random seed for this procedure, use @code{random-source-randomize!}
or @code{random-source-pseudo-randomize!} on @code{default-random-source}.
@c JP
デフォルトの乱数発生源を用いて、0 から @var{n}-1 までの正確な整数の乱数を
返します。この手続きの乱数のシードを設定するには
@code{default-random-source} に対して
@code{random-source-randomize!} あるいは、
@code{random-source-pseudo-randomize!} を用います。
@c COMMON
@end defun

@defun random-real
[SRFI-27]
@c MOD srfi.27
@c EN
Returns a random real number between (0, 1), exclusive,
using the default random source.
To set a random seed for this procedure, use @code{random-source-randomize!}
or @code{random-source-pseudo-randomize!} on @code{default-random-source}.
@c JP
デフォルトの乱数発生源を用いて、0 より大きく、1 未満の実数乱数を返します。
この手続きの乱数のシードを設定するには @code{default-random-source} に対して
@code{random-source-randomize!} あるいは、
@code{random-source-pseudo-randomize!} を用います。
@c COMMON
@end defun

@defvar default-random-source
[SRFI-27]
@c MOD srfi.27
@c EN
Keeps the default random source that is used by @code{random-integer}
and @code{random-real}.
@c JP
@code{random-integer} および @code{random-real} が利用するデフォルトの
乱数発生源を保持しています。
@c COMMON
@end defvar

@defun make-random-source
[SRFI-27]
@c MOD srfi.27
@c EN
Creates and returns a new random source.
In the current Gauche implementation, it is just a @code{<mersenne-twister>}
object.  It may be changed in the future implementation.
@c JP
乱数の発生源を生成し返します。
現在の Gauche の実装では、これは @code{<mersenne-twister>} のオブジェクトです。
将来の実装では変更される可能性があります。
@c COMMON
@end defun

@defun random-source? obj
[SRFI-27]
@c MOD srfi.27
@c EN
Returns @code{#t} if @var{obj} is a random source object.
@c JP
@var{obj} が乱数発生源オブジェクトであれば、@code{#t} を返します。
@c COMMON
@end defun

@defun random-source-state-ref s
@defunx random-source-state-set! s state
[SRFI-27]
@c MOD srfi.27
@c EN
Gets and sets the "snapshot" of the state of the random source @var{s}.
@var{State} is an opaque object whose content depends on the backbone
generator.
@c JP
乱数発生源 @var{s} の状態の「スナップショット」を獲得あるいは設定します。
@var{state} は背後にある発生器に依存する内容をもつ不透明なオブジェクトです。
@c COMMON
@end defun

@defun random-source-randomize! s
[SRFI-27]
@c MOD srfi.27
@c EN
Makes an effort to set the state of the random source @var{s} to
a truly random state.  The current implementation uses the current
time and the process ID to set the random seed.
@c JP
乱数発生源 @var{s} の状態を完全にランダムな状態にしようとします。
現在の実装では乱数のシードを設定するのに、現在の時刻とプロセス ID を
使います。
@c COMMON
@end defun

@defun random-source-pseudo-randomize! s i j
[SRFI-27]
@c MOD srfi.27
@c EN
Changes the state of the random source @var{s} into the initial state
of the (@var{i}, @var{j})-th independent random source,
where @var{i} and @var{j} are non-negative integers.
This procedure can be used to reuse a random source @var{s} as large
number of independent random source, indexed by two non-negative integers.
Note that this procedure is entirely deterministic.
@c JP
乱数発生源 @var{s} の状態を発生源とは独立した (@var{i}, @var{j}) 番の
初期状態に設定します。@var{i} および @var{j} は非負の整数です。
この手続きは乱数発生源 @var{s} を二つの非負整数でインデックス付した、
大規模の独立の乱数発生源として再利用するときに利用できます。
この手続きは、完全な決定性があることに注意してください。
@c COMMON
@end defun

@defun random-source-make-integers s
[SRFI-27]
@c MOD srfi.27
@c EN
Returns a procedure, that takes one integer argument @var{n} and
returns a random integer between 0 and @var{n}-1 inclusive for every
invocation, from the random source @var{s}.
@c JP
呼出しのたびに乱数発生源 @var{s} より、 0 から @var{n}-1 までの整数の
乱数を返す、一つの整数 @var{n} を引数としてとる手続きを、返します。
@c COMMON
@end defun

@defun random-source-make-reals s :optional unit
[SRFI-27]
@c MOD srfi.27
@c EN
Returns a procedure, that takes no argument and
returns a random real between 0 and 1 exclusive for
every invocation, from the random source @var{s}.
If @var{unit} is given, the random real the returned procedure
generates will be quantized by the given @var{unit}, where
0 < @var{unit} < 1.
@c JP
呼出しのたびに乱数発生源 @var{s} から 0 より大きく 1 未満の実数乱数を
返す、無引数の手続きを返します。
@var{unit} が与えられた場合、返された手続きが生成する実数乱数は
@var{unit} 単位に量子化されます。@var{unit} は、 0 より大きく 1 未満で
なければなりません。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Localization, A program argument processor, Sources of random bits, Library modules - SRFIs
@section @code{srfi.29} - Localization
@c NODE 地域化, @code{srfi.29} - 地域化

@deftp {Module} srfi.29
@mdindex srfi.29
@mdindex srfi.29.bundle
@mdindex srfi.29.format
@c EN
This module implements the message localization mechanism
defined in SRFI-29.

In fact, this module consists of two submodules,
@code{srfi.29.bundle} and @code{srfi.29.format}.
The module @code{srfi.29} extends both submodules.
It is because srfi-29's definition of the @code{format}
procedure is incompatible to Gauche's native @code{format}
(thus Common Lisp's @code{format}) in the handling of
@code{~@@*} directive.

So I splitted the module into two, @code{srfi.29.format}
which contains srfi-29's @code{format}, and @code{srfi.29.bundle}
which contains the rest ("bundle" API).
If a program wishes a complete compatibility of
srfi-29, use @code{srfi.29} module, which overrides
Gauche's native @code{format}.   If a program just wants
srfi-29's "bundle" API, but wants to keep Gauche's @code{format},
use @code{srfi.29.bundle}.

A localization feature is also provided by @code{text.gettext} module
(@pxref{Localized messages}),
which is a preferable way of message localization in Gauche.
This module is provided mainly for porting code that uses
srfi-29 features.
@c JP
このモジュールは SRFI-29 で定義されたメッセージの地域化機構を実装したものです。

実際には、このモジュールは2つのサブモジュール、@code{srfi.29.bundle}
および @code{srfi.29.format} で構成されています。@code{srfi.29}モジュールは
このふたつのモジュールをextendしています。このようにしているのは、
SRFI-29 での @code{format} 手続きの定義が Gauche ネイティヴの(すなわち
Common Lisp の) @code{format} とでは @code{~@@*} 指令の扱い
において互換性がないからです。

そんなわけで、SRFI-29 の @code{format} を含む @code{srfi.29.format} と
それ以外(「バンドル」API)を含む @code{srfi.29.bundle} に分離しました。
プログラムを SRFI-29 と完全に互換性のあるものにしたければ、@code{srfi.29}
モジュールを使って下さい。こうすると Gauche ネイティヴの
@code{format} が上書きされます。SRFI-29 の「バンドル」API を使いたいだけで、
Gauche の @code{format} をそのままにしておきたいなら、@code{srfi.29.bundle}
を使って下さい。

地域化機能は @code{text.gettext} モジュールによっても提供され
(@pxref{Localized messages})、Gauche でメッセージの地域化をするのなら
@code{text.gettext} を使うのが好ましい方法です。@code{srfi.29} モジュールは
主として SRFI-29 の機能を使っているコードをポーティングするためにあります。
@c COMMON
@end deftp

@c EN
@subheading Bundle specifier
@c JP
@subheading バンドル指定子
@c COMMON

@c EN
A @emph{bundle specifier} is an arbitrary list of symbols,
but typically it takes the form like:
@c JP
@emph{バンドル指定子}はシンボルを要素とする任意のリストです。しかし
典型的には以下のようなフォームになります。
@c COMMON
@example
@code{(@var{package} @var{language} @var{country} @var{details} @dots{})}
@end example
@c EN
Where @var{package} specifies the software package,
@var{language} and @var{country} specifies language and country code,
and @var{details} gives other informations like encoding.

The values for the default bundle specifier can be obtained
by the following parameters.
@c JP
ここで、@var{package} はソフトウェアパッケージを指定し、
@var{language} および @var{country} は言語と国コードを指定、そして、
@var{details} はエンコーディングのようなそのほかの情報を指定します。

デフォルトのバンドル指定子の値は以下のようなパラメータで取得可能です。
@c COMMON

@deffn {Parameter} current-language
@deffnx {Parameter} current-country
@deffnx {Parameter} current-locale-details
[SRFI-29]
@c MOD srfi.29
@c EN
The @code{current-language} and @code{current-country} parameters
keep the ISO 639-1 language code and ISO 3166-1 country code
respectively, both as symbols.
The @code{current-locale-details} keeps a list of auxiliary
local informations, such as encodings.

These parameters are initialized if @code{LANG} environment
variable is set in the form of @code{lang_country.encoding} format.
For example, if the @code{LANG} setting is @code{ja_JP.eucJP},
those parameters are @code{ja}, @code{jp}, and @code{(eucjp)},
respectively.   If @code{LANG} is @code{C} or undefined,
the default values are @code{en}, @code{us}, and @code{()}, respectively.
@c JP
@code{current-language} および @code{current-country} パラメータは
ISO 639-1 の言語コードと ISO 3166-1 の国コードをそれぞれシンボルで
保持しています。@code{current-locale-details} はエンコーディングのような
補助的な地域情報のリストを保持しています。

これらのパラメータは、環境変数 @code{LANG} が @code{lang_country.encoding}
フォーマットの形式で設定されていれば、初期化されます。たとえば、
@code{LANG} が @code{ja_JP.eucJP} に設定されていれば、それらの
パラメータはそれぞれ @code{ja}、@code{jp}、@code{(eucjp)} に設定されます。
@code{LANG} が @code{C} であるかあるいは定義されていなければ、
デフォルト値は、それぞれ @code{en}、@code{us}、@code{()} です。
@c COMMON
@end deffn

@c EN
@subheading Bundle preparation
@c JP
@subheading バンドル準備
@c COMMON

@defun declare-bundle! bundle-specifier association-list
[SRFI-29]
@c MOD srfi.29
@c EN
Put the association list of template key (symbol) and the locale-specific
message (string) into the bundle database, with @var{bundle-specifier}
as the key.
@c JP
テンプレートキー(シンボル)と特定ロケールのメッセージ(文字列)の連想リストを
@var{bundle-specifier} をキーとして、バンドルデータベースに入れます。
@c COMMON
@end defun

@c EN
Gauche currently supports only in-memory bundle database.
That is, you have to call @code{declare-bundle!} within the application
in order to lookup the localized messages.
@c JP
Gauche は現在のところメモリ上のバンドルデータベースのみサポートしています。
つまり、地域化されてメッセージを探しあてるには、そのアプリケーション内で
@code{declare-bundle!} を呼ぶ必要があるということです。
@c COMMON

@defun save-bundle! bundle-specifier
@defunx load-bundle! bundle-specifier
[SRFI-29]
@c MOD srfi.29
@c EN
Since Gauche doesn't support persistent bundle database yet,
these procedures does nothing and returns @code{#f}.
(It is still conforming behavior of srfi-29).
@c JP
Gauche は今のところ永続バンドルデータベースをサポートしていないので、
これらの手続きはなにもせず @code{#f} を返します
(これはいまのところ srfi-29 の振舞いと適合しています)。
@c COMMON
@end defun

@c EN
@subheading Retrieving localized message
@c JP
@subheading 地域化されたメッセージの検索
@c COMMON

@defun localized-template package-name message-template-name
[SRFI-29]
@c MOD srfi.29
@c EN
Retrieves localized message, associated with a symbol
@var{message-template-name} in the package @var{package-name}.
@c JP
地域化されたメッセージを検索します。当該メッセージは
@var{package-name} パッケージの中で、@var{message-template-name}
シンボルと関連つけられています。
@c COMMON
@end defun

@c EN
@subheading Extended format procedure
@c JP
@subheading 拡張された format 手続き
@c COMMON

@defun format format-string args
[SRFI-29]
@c MOD srfi.29
@c EN
SRFI-29 extends SRFI-28's @code{format} procedure spec
(which supports @code{~a}, @code{~s}, @code{~%} and @code{~~} directives),
in order to support argument repositioning.

A directive @code{~N@@*}, where N is an integer or can be omitted,
causes the next directive to retrieve a value from @var{N}-th
optional argument.  The referenced value isn't consumed,
and won't affect the processing of subsequent directives.

Although SRFI-28 spec is compatible to
Gauche's native @code{format} (@pxref{Output}),
this SRFI-29 extension isn't.
Specifically, the @code{~N@@*} directive of Gauche's @code{format}
changes the argument pointer to points @var{N}-th optional argument,
thus it affects all the subsequent arguments.

Because of this incompatibility, this function is defined in
a separate module, @code{srfi.29.format}.  If you use @code{srfi.29},
which extends @code{srfi.29.bundle} and @code{srfi.29.format},
the @code{format} procedure will be overridden by srfi-29's @code{format}
in your module.  If you want to keep Gauche's native @code{format},
use @code{srfi.29.bundle} only.
@c JP
SRFI-29 は SRFI-28 の @code{format} 手続きの仕様(これは @code{~a}、
@code{~s}、@code{~%} および @code{~~} 指令をサポートしている)を
引数再配置をサポートするために拡張しています。

@code{~N@@*} 指令は @var{N}-番目のオプション引数から値を引き出す次の
指令の契機となります。参照された値が消費されることはありません。また、
参照された値がその後につづく指令の処理に影響を与えることはありません。

SRFI-28 の仕様は Gauche ネイティヴの @code{format} (@pxref{Output}) と
互換性がありますが、この SRFI-29 の拡張には互換性がありません。
具体的には、Gauche ネイティヴの @code{format} の @code{~N@@*} 指定は
引数ポインタを @var{N}-番目のオプション引数を指すように変更します。
それゆえ、そのあとに続くすべての引数に影響をあたえます。

この非互換性があるために、この関数は、分離したモジュール
@code{srfi.29.format} で定義されています。@code{srfi.29.bundle} と
@code{srfi.29.format} を拡張する @code{srfi.29} を使うと、@code{format}
手続きは SRFI-29 の @code{format} でそのモジュール内で上書きされます。
Gauche ネイティヴの @code{format} を使いたければ、@code{srfi.29.bundle}
だけを使うようにしてください。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node A program argument processor, Eager comprehensions, Localization, Library modules - SRFIs
@section @code{srfi.37} - args-fold: a program argument processor
@c NODE args-fold プログラム引数処理, @code{srfi.37} - args-fold プログラム引数処理

@deftp {Module} srfi.37
@mdindex srfi.37
@c EN
This module implements @code{args-fold},
yet another procedure to process command-line
arguments, defined in SRFI-37.

Unlike @code{gauche.parseopt}
(@pxref{Parsing command-line options}),
@code{args-fold} provides functional interface, i.e.
the user's states are explicitly passed via parser's argument and
return values, and also follows POSIX and GNU getopt guidelines,
including long options.
@c JP
このモジュールは、@code{args-fold} を実装しています。
これは、SRFI-37で定義されている
コマンドライン引数の処理をするもうひとつの手続きです。

@code{gauche.parseopt} (@ref{Parsing command-line options}
参照) とは違って、@code{args-fold} は関数的なインタフェースです。すなわち、
利用者側の状態は、パーザの引数を通じて明示的に渡され、値が返ります。
また、ロングオプションを含む、POSIX および GNU の getopt のガイドラインに
準拠しています。
@c COMMON
@end deftp

@defun args-fold args options unrecognized-proc operand-proc :rest seeds
[SRFI-37]
@c MOD srfi.37
@c EN
Processes program options @var{args} from left to right,
according to given option specification @var{options},
and two procedures @var{unrecognized-proc} and @var{operand-proc}.

@var{Options} is a list of option objects, explained below.
Each option object keeps the name(s) of the option,
a flag to specify whether the option takes
an argument or not, and a procedure to process that option
(we'll call it @emph{option procedure}).

@code{Args-fold} recognizes both single-character options (short options)
and long options.  A short option must begin with single hyphen
(e.g. @code{-a}), while long option must begin with double hyphens
(e.g. @code{--help}).   Short options can be
concatenated, e.g. @code{-abc} or @code{-a -b -c}.
Both a short option and a long option can take
required or optional arguments.   Required short-option argument
can appear with or without space after the option, e.g.
@code{-afoo} or @code{-a foo}.
Long-option argument can appear after character '@code{=}' or
space, e.g. @code{--long=foo} or @code{--long foo}.

When @code{args-fold} encounters a command-line argument that cannot
be an option argument, and doesn't begin with hyphen, the argument is
treated as an @emph{operand}.   @code{Args-fold} allows operands and
options to be interleaved.  However, if @code{args-fold} encounters
'@code{--}', the rest of arguments are treated as operands,
regardless of beginning with hyphen or not.

When the given option matches one of option object in @var{options},
the option procedure is called as follows:
@c JP
与えられたオプション仕様 @var{options} および、ふたつの手続き
@var{unrecognized-proc} と @var{operand-proc} とにしたがって、プログラム
引数 @var{args} を左から右へ処理します。

@var{options} はオプションオブジェクトのリストで以下のようなものです。
各オプションオブジェクトはオプションの名前、そのオプションが引数を
とるかどうかを指定するフラグ、そのオプションを処理する手続き
(今後これを @emph{オプション手続き}とよびます)を保持しています。

@code{args-fold} は単一文字のオプション(ショートオプション)と
ロングオプションの両方を認識します。ショートオプションは単一の
ハイフンで始まって(たとえば、@code{-a})いなければなりません。一方、
ロングオプションは二つのハイフンで始まって(たとえば、@code{--help})
いなければなりません。ショートオプションは連結することが可能で、
たとえば、@code{-abc} あるいは @code{-a -b -c} と書くことができます。
ショートオプション、ロングオプションはともに、必須引数あるいはオプショナル
引数を取ることができます。ショートオプションの必須引数は当該オプション
あとに空白なしあるいは空白をいれて指定することができます。たとえば、
@code{-afoo} あるいは @code{-a foo} が可能です。ロングオプションの
引数は'@code{=}'文字あるいは空白をはさみます。たとえば、
@code{--long=foo} または @code{--long foo} です。

@code{args-fold} はオプションの引数ではなく、ハイフンで始まっていない
コマンドライン引数を@emph{オペランド}としてとりあつかいます。
@code{args-fold} はオペランドとオプションが交互に出現するのを許します。
しかし、'@code{--}' に出逢うと、のこりは、ハイフンで始まっていようと
なかろうと、オペランドとして扱われます。

与えられたオプションが @var{options} 内のオプションオブジェクトのひとつ
にマッチすれば、オプション手続きが以下のように呼出されます。
@c COMMON

@example
(@var{option-proc} @var{option} @var{name} @var{arg} @var{seed} @dots{})
@end example

@c EN
where @var{option} is the matched option object, @var{name} is
the string actually used to specify the option, @var{arg} is
the option argument (or @code{#f} if there's none), and
@var{seed} @dots{} is the user's state information.
@var{Option-proc} must return as many arguments as @var{seed}s.

When @code{args-fold} encounters an option that doesn't match
any of the option objects, it creates a new option object
for the option and calls @var{unrecognized-proc}
with the same arguments as @var{option-proc}.

When @code{args-fold} finds an operand, @var{operand-proc}
is called as follows:
@c JP
ここで、@var{option} はマッチしたオプションオブジェクトで、@var{name}
は実際にオプションを指定するのに使われた文字列、@var{arg} はそのオプション
の引数(あるいは存在しなければ、@code{#f})、そして @var{seed} @dots{} は
利用者側の状態情報です。@var{option-proc} は @var{seed} と同じ数だけ
値を返さなければなりません。

@code{args-fold} がオペランドを見つけたら、@var{operand-proc} が
以下のように呼出されます。
@c COMMON

@example
(@var{operand-proc} @var{operand} @var{seed} @dots{})
@end example

@c EN
@var{Operand-proc} must return as many arguments as @var{seed}s.

The caller's state should be explicitly passed around seed arguments
and return values.  The initial seed values are @var{seed}s given
to @code{args-fold}.  The values returned from option procedure,
@var{unrecognized-proc} and @var{operand-proc} are used as the seed
arguments of next invocation of those procedures.  The values
returned from the last call to the procedures are returned
from @code{args-fold}.
@c JP
@var{operand-proc} は @var{seed} と同じ数だけ
値を返さなければなりません。

呼出し側の状態は明示的にシード引数で渡され、戻されます。初期のシード値は
@code{args-fold} に与えた @var{seed} です。この値は、オプション手続き
@var{unrecognized-proc} と @var{operand-proc} によって戻され、
次にこれらのオプション手続きの呼出し時にシード引数として使われます。
これらの手続きの最後の呼出しから返されたこの値は @code{args-fold} によって
返されます。
@c COMMON
@end defun

@defun option names require-arg? optional-arg? processor
[SRFI-37]
@c MOD srfi.37
@c EN
Creates an option object with the passed properties.

@var{Names} is a list of characters and/or strings.
A character is used for a short option, and a string is used
for a long option.

Two flags, @var{require-arg?} and @var{optional-arg?}
indicates whether the option should take an option argument,
or may take an option argument.

@var{Processor} is the option processor procedure.

Note that, if an option argument is passed using '@code{=}'
character, it is passed to the option procedure even if
the option has @code{#f} in both @var{require-arg?}
and @var{optional-arg?}.  It is up to the option procedure
to deal with the argument.

It should also be noted that the optional option argument
for a short option is only recognized if it is given
without whitespace after the short option.  That is, if
a short option '@code{d}' is marked to take optional option argument,
then '@code{-dfoo}' is interpreted as '@code{-d}' with argument '@code{foo}',
but '@code{-d foo}' is interpreted as '@code{-d}' without argument
and an operand @code{foo}.  If '@code{d}' is marked to
take required option argument, however, both are interpreted
as '@code{-d}' with argument '@code{foo}'.
@c JP
渡されたプロパティでオプションオブジェクトを作成します。

@var{names} は文字と(あるいは)文字列のリストです。文字はショートオプションに
使い、文字列はロングオプションに使います。

ふたつのフラグ @var{require-arg?} と @var{optional-arg?} はオプションが
必須引数をとるか、あるいは、オプショナル引数をとるかを示します。

@var{processor} はそのオプションの処理をする手続きです。

オプションの引数が '@code{=}' つきで渡された場合には、
たとえ @var{require-arg?}、@var{optional-arg?} がともに @code{#f}
であっても、そのオプションの引数はオプション処理手続きに渡されることに
注意してください。オプション手続きにその引数を処理させようとします。

ショートオプションに対するオプショナルなオプションの引数は、オプションに
つづいてスペースなしで指定されたときにだけ認識されることにも
注意してください。たとえば、ショートオプション @code{d} がオプショナル
引数をもつことになっているとき、'@code{-dfoo}' は '@code{-d}' が引数
'@code{foo}' をもつと解釈されますが、'@code{-d foo}' は引数なしの
'@code{-d}' とオペランド '@code{foo}' と解釈されてしまいます。もし、
'@code{-d}' が必須引数をもつと設定されているなら、両方ともに
'@code{-dfoo}' は '@code{-d}' が引数 '@code{foo}' をもつと解釈されます。
@c COMMON
@end defun

@defun option? obj
[SRFI-37]
@c MOD srfi.37
@c EN
Returns @code{#t} if @var{obj} is an option object,
@code{#f} otherwise.
@c JP
@var{obj} がオプションオブジェクトなら @code{#t} を返し、
そうでなければ、@code{#f} を返します。
@c COMMON
@end defun

@defun option-names option
@defunx option-required-arg? option
@defunx option-optional-arg? option
@defunx option-processor
[SRFI-37]
@c MOD srfi.37
@c EN
Returns the properties of an option object @var{option}.
@c JP
オプションオブジェクト @var{option} のプロパティを返します。
@c COMMON
@end defun

@c EN
A simple example:
@c JP
簡単な例:
@c COMMON

@example
(use srfi.37)

(define options
 (list (option '(#\d "debug") #f #t
               (lambda (option name arg debug batch paths files)
                 (values (or arg "2") batch paths files)))
       (option '(#\b "batch") #f #f
               (lambda (option name arg debug batch paths files)
                 (values debug #t paths files)))
       (option '(#\I "include") #t #f
               (lambda (option name arg debug batch paths files)
                 (values debug batch (cons arg paths) files)))))

(define (main args)
  (receive (debug-level batch-mode include-paths files)
    (args-fold (cdr args)
               options
               (lambda (option name arg . seeds)         ; unrecognized
                 (error "Unrecognized option:" name))
               (lambda (operand debug batch paths files) ; operand
                 (values debug batch paths (cons operand files)))
               0      ; default value of debug level
               #f     ; default value of batch mode
               '()    ; initial value of include paths
               '()    ; initial value of files
               )
     (print "debug level = " debug-level)
     (print "batch mode = " batch-mode)
     (print "include paths = " (reverse include-paths))
     (print "files = " (reverse files))
     0))
@end example

@c ----------------------------------------------------------------------
@node Eager comprehensions, Vector library (Legacy), A program argument processor, Library modules - SRFIs
@section @code{srfi.42} - Eager comprehensions
@c NODE 先行評価的内包表記, @code{srfi.42} - 先行評価的内包表記

@deftp {Module} srfi.42
@mdindex srfi.42
@c EN
This module provides a generic comprehension mechanism, which some other
languages (e.g. Haskell and Python) offer as a built-in mechanism.
It provides a rich set of operators so it can be used not only as a list
generator but as a generic loop construct (actually, some may say
it is as powerful/evil as Common Lisp's @emph{loop} macro).
@c JP
このモジュールはジェネリックな内包表記(comprehension)機構を提供します。
この機構は他の言語(Haskell、Pythonなど)では組み込みの機構になっていま
す。この機構は豊富な操作手続を提供しているので、リストジェネレータとい
うだけではなく、ジェネリックなループ構文(Common Lisp の @emph{loop} マ
クロ並みに強力/邪悪だという人もいます)を提供しています。
@c COMMON

@c EN
It runs eagerly as the name suggests, that is, if it generates a list, it
creates the entire list when evaluated, instead of generate the
elements @emph{on demand}.  Thus it can't represent an infinite
sequence, which Haskell's comprehension naturally does.  Gauche offers
a few alternatives to deal with lazy, possibly infinite, sequences:
See @ref{Lazy sequences}, @ref{Generators} and @ref{Stream library}.
@c JP
この機構は名前の通り、先行評価的に走ります。すなわち、リストを生成する場合、評価時
にすべてのリストを生成します。要素を@emph{要求駆動的}に生成するわけで
はありません。それゆえ、無限列を表現することはできません。それが自然に
できる Haskell とは違います。Gaucheは、遅延生成される有限/無限列を
扱う方法を他にいくつか提供しています。
@ref{Lazy sequences}、@ref{Generators}、@ref{Stream library}を
参照してください。
@c COMMON
@end deftp


@c EN
@subheading Eager comprehension examples
@c JP
@subheading 先行評価的内包表記の例
@c COMMON

@c EN
Let's begin with some examples.
@c JP
いくつかの例からはじめましょう。
@c COMMON

@c EN
Generate a list of squares for the first five integers:
@c JP
5番目までの整数の自乗のリストを生成しましょう。
@c COMMON
@example
(list-ec (: i 5) (* i i)) @result{} (0 1 4 9 16)
@end example

@c EN
@code{list-ec} is a comprehension macro that generates a list.
The first form @code{(: i 5)} is called a @var{qualifier}, which
specifies a set of values to repeat over (here it is each integer
from 0 below 5).
The last form
@code{(* i i)} is called a @var{body}, which is an ordinary Scheme expression
evaluated for each values generated by the @var{qualifier}.
@c JP
@code{list-ec}はリストを生成する内包表記マクロです。
最初のフォーム@code{(: i 5)}は@var{qualifier}と呼ばれ、
繰り返しを行う値の集合を指定します (この例では0以上5未満の整数)。
最後のフォーム@code{(* i i)}は@var{body}と呼ばれ、
@var{qualifier}によって生成される値それぞれにつき評価される通常のScheme式です。
@c COMMON

@c EN
A comprehension can have more than one qualifiers.
Next example generate set of pair of numbers @code{(x y)}, where @code{x}
is between 2 (inclusive) and 5 (exclusive),
and @code{y} is between 1 (inclusive) and x (exclusive).
@c JP
内包表記は複数のqualifierを持つことができます。
次の例は数の対@code{(x y)}の集合を生成します。ここで@code{x}は
2以上 5未満、@code{y}は1以上 x 未満です。
@c COMMON

@example
(list-ec (: x 2 5) (: y 1 x) (list x y))
  @result{} ((2 1) (3 1) (3 2) (4 1) (4 2) (4 3))
@end example

@c EN
The qualifiers works as @emph{nested}; that is, @code{(: x 2 5)}
specifies to repeat the rest of the clauses---@code{(: y 1 x)} and
@code{(list x y)}.
@c JP
複数のqualifierはネストするように動作します。つまり、@code{(: x 2 5)}は
残りの節---@code{(: y 1 x)} および @code{(list x y)} を繰り返すように
指定しているということです。
@c COMMON

@c EN
The above two examples can be written in Haskell as the followings:
@c JP
上の2つの例はHaskellで書くと以下のようになります。
@c COMMON

@example
[ i*i   | i <- [0..4] ]
[ (x,y) | x <- [2..4], y <- [1..x-1] ]
@end example

@c EN
Note the differences: (1) In Haskell, the body expression to yield the
elements comes first, followed by qualifiers (selectors).  In SRFI-42, the body
expression comes last.  (2) In SRFI-42, range operator's lower bound
is inclusive but its upper bound is exclusive.
@c JP
違いに注意：(1) Haskellでは要素になる本体部が先にきて、そのあとに修飾
部(セレクタ)がきます。SRFI-42では本体部は最後になります。(2) SRFI-42で
は範囲指定の下限はそれを含み、上限はそれを含みません。
@c COMMON

@c EN
List a set of numbers @code{(a b c d)}, where @code{a^3+b^3 = c^3+d^3}:
@c JP
@code{a^3+b^3 = c^3+d^3}を満すような数字の集合@code{(a b c d)}を列挙し
ましょう。
@c COMMON
@example
(define (taxi-number n)
  (list-ec (: a 1 n)
           (: b (+ a 1) n)
           (: c (+ a 1) b)
           (: d (+ c 1) b)
           (if (= (+ (expt a 3) (expt b 3))
                  (+ (expt c 3) (expt d 3))))
           (list a b c d)))
@end example

@c EN
If you want to change values of more than one variable
simultaneously, instead of nesting, you can bundle the qualifiers
like this:
@c JP
複数の変数を(ネストするのではなく)同時に変化させたい場合は、
複数のqualifierを次のようにまとめることができます。
@c COMMON

@example
(list-ec (:parallel (: x '(a b c d)) (: y '(1 2 3 4)))
         (list x y))
  @result{} ((a 1) (b 2) (c 3) (d 4))
@end example

@c EN
You can generate not only a list, but other sequences:
@c JP
リストだけではなく、他のシーケンスも生成できます。
@c COMMON
@example
(vector-ec (: i 5) i) @result{} #(0 1 2 3 4)
(string-ec (: i 5) (integer->char (+ i 65))) @result{} "ABCDE"
@end example

@c EN
Or apply folding operations:
@example
(sum-ec (: i 1 100) i)
  @result{} 4950    ;; sum of integers from 1 below 100.
(product-ec (: i 1 10) i)
  @result{} 362880 ;; ... and product of them.
@end example
@c JP
畳み込み演算も適用できます。
@example
(sum-ec (: i 1 100) i)
  @result{} 4950    ;; 1以上100未満の整数の和
(product-ec (: i 1 10) i)
  @result{} 362880 ;;  1以上10未満の整数の積
@end example
@c COMMON

@c EN
@subheading Comprehension macros
@c JP
@subheading 内包表記マクロ
@c COMMON

@c EN
Each comprehension takes the following form.
@c JP
それぞれの内包表記は以下のような形式になります。
@c COMMON
@example
(@var{comprehension-macro} @var{qualifier} @dots{} @var{body})
@end example

@c EN
It evaluates @var{body} repeatedly as specified by @var{qualifier} @dots{}.
Depending on the type of comprehension,
the results of @var{body} may be either collected to create an
aggregate (list, vector, string, ...), folded by some operator
(sum, product, min, max, ...), or simply discarded.
@c JP
@var{qualifier} @dots{}の指定に従って@var{body}をくりかえし評価します。内包表記の種類
によって、@var{body}の結果は(リスト、ベクタ、文字列などに)集約されるか、
(sum、product、min、maxなどによって)畳み込まれるか、あるいは、単に捨て
られます。
@c COMMON

@c EN
Each @var{qualifier} specifies how to repeat the following
@var{qualifiers} and @var{body}.  A @var{qualifier} can be a
generational qualifier that yields a set of values to loop
over, or a control qualifier that specify a condition
to exclude some values.  See the Qualifiers heading below.
@c JP
それぞれの@var{qualifier}は、それ以降の@var{qualifier}と@var{body}
をどのように繰り返すかを指定します。@var{qualifier}には、繰り返しに
使う値を生成する生成的@var{qualifier}と、条件によって値を繰り返しから
省く制御的@var{qualifier}があります。以下のQualifiersの節を参照してください。
@c COMMON

@c EN
A few comprehensions takes extra values before @var{qualifiers} or
after @var{body}.
@c JP
いくつかの内包表記では、追加の値が@var{qualifiers}の前か、@var{body}
の後に置かれます。
@c COMMON

@defmac do-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
Repeats @var{body}.  The results of @var{body} is discarded.
This is for side-effecting operations.
@c JP
@var{body}を繰り返します。@var{body}の返り値は捨てられます。
この形式は副作用目的で使います。
@c COMMON
@end defmac

@defmac list-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
Repeats @var{body} and collects the results into a list.
@c JP
@var{body}を繰り返し、結果をリストに集めて返します。
@c COMMON
@end defmac

@defmac append-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
Repeats @var{body}, which must yield a list.
Returns a list which is the concatenation of all lists returned by @var{body}.
@c JP
@var{body}を繰り返し、その結果のリストを結合して返します。
@var{body}は必ずリストを返さなければなりません。
@c COMMON
@end defmac

@defmac string-ec qualifier @dots{} body
@defmacx string-append-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
Repeats @var{body}, which must yield a character (in @code{string-ec})
or a string (in @code{string-append-ec}).  Returns a string that
consists of the results of @var{body}.
@c JP
@var{body}を繰り返します。@var{body}は@code{string-ec}では文字へ、
@code{string-append-ec}では文字列へと評価されなければなりません。
結果を集め、または結合した文字列が買えされます。
@c COMMON
@end defmac

@defmac vector-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
Repeats @var{body} and collects the results into a vector.
@c JP
@var{body}を繰り返し、結果をベクタに集めて返します。
@c COMMON
@end defmac

@defmac uvector-ec class qualifier @dots{} body
@c MOD srfi.42
@c EN
Repeats @var{body} and collects the results into a uniform vector
of class @var{class}.  This is a Gauche's extension and not a part of
SRFI-42.
@c JP
@var{body}を繰り返し、結果をクラス@var{class}のユニフォームベクタに集めて返します。
これはGaucheの拡張で、SRFI-42には含まれていません。
@c COMMON

@example
(uvector-ec <u8vector> (: i 10))
 @result{} #u8(0 1 2 3 4 5 6 7 8 9)
@end example
@end defmac

@defmac vector-of-length-ec k qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
This is like @code{vector-ec}, except that the length of the
result vector is known to be @var{k}.  It can be more efficient
than @code{vector-ec}.  Unless the comprehension repeats exactly
@var{k} times, an error is signaled.
@c JP
@code{vector-ec}と似ていますが、最終的なベクタの長さが@var{k}と分かっている時に
使えます。あらかじめベクタをアロケートしておけるので@code{vector-ec}より効率が良いです。
繰り返しが正確に@var{k}回にならなかった場合はエラーが投げられます。
@c COMMON
@end defmac

@defmac uvector-of-length-ec class k qualifier @dots{} body
@c MOD srfi.42
@c EN
Like @code{vector-of-length-ec}, but creates a uniform vector
of class @var{lass} instead of a vector.  This is more efficient
than @code{uvector-ec}.
This is a Gauche's extension and not a part of
SRFI-42.
@c JP
@code{vector-ec}と似ていますが、ベクタではなくクラス@var{class}の
ユニフォームベクタを作って返します。
あらかじめユニフォームベクタをアロケートしておけるので
@code{uvector-ec}より効率が良いです。
これはGaucheの拡張で、SRFI-42には含まれていません。
@c COMMON
@end defmac


@defmac sum-ec qualifier @dots{} body
@defmacx product-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
@var{body} must yield a numeric value.  Returns sum of and product of
the results, respectively.
@c JP
@var{body}は数値を生成しなければなりません。繰り返しによって生成される数値の和と積を
それぞれ返します。
@c COMMON
@end defmac

@defmac min-ec qualifier @dots{} body
@defmacx max-ec qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
@var{body} must yield a real number.  Returns maximum and minimum value
of the results, respectively.  @var{body} must be evaluated at least once,
or an error is signaled.
@c JP
@var{body}は実数値を生成しなければなりません。
最初および最大の結果をそれぞれ返します。@var{body}は最低1回は実行されねばならず、
そうでなければエラーが投げられます。
@c COMMON
@end defmac

@defmac any?-ec qualifier @dots{} test
@defmacx every?-ec qualifier @dots{} test
[SRFI-42]
@c MOD srfi.42
@c EN
Evaluates @var{test} for each iteration, and returns
@code{#t} as soon as it yields non-@code{#f} (for @code{any?-ec}),
or returns @code{#f} as soon as it yields @code{#f} (for @code{every?-ec}).
Unlink the comprehensions introduced above, these stop evaluating
@var{test} as soon as the condition meets.
If the qualifiers makes no iteration, @code{#f} and @code{#t} are
returned, respectively.
@c JP
繰り返しのたびに@var{test}を評価し、@code{any?-ec}では@var{test}が偽でない
値を返したら直ちに@code{#t}を、@code{every?-ec}では@var{test}が偽を返したら
直ちに@code{#f}を、それぞれ返します。これまで上で説明してきた
内包表記とは異なり、これらは@var{test}が条件を満たしたら繰り返しを打ち切ります。
もし繰り返しが一度もなされなかった場合、それぞれ@code{#f}と@code{#t}が戻り値となります。
@c COMMON
@end defmac

@defmac first-ec default qualifier @dots{} body
@defmacx last-ec default qualifier @dots{} body
[SRFI-42]
@c MOD srfi.42
@c EN
First initializes the result by the value of the expression @var{default},
then start iteration, and returns the value of the first and last
evaluation of @var{body}, respectively.  In fact, @code{first-ec}
only evaluates @var{body} at most once.
@c JP
まず結果を@var{default}式の値で初期化し、繰り返しを開始します。
そして、最初または最後の@var{body}の値をそれぞれ返します。
実際のところ、@code{first-ec}は@var{body}をたかだか一回しか評価しません。
@c COMMON

@c EN
These forms are most useful when used with control qualifiers.
For example, the following @code{first-ec} returns the @emph{first}
set of distinct integers (@var{x}, @var{y}, @var{z}),
where @var{x}*@var{x}+@var{y}*@var{y}+@var{z}*@var{z} becomes a square
of another integer @var{w}.
@c JP
これらのフォームは、フロー制御のqualifierと一緒に使うことで効果を発揮します。
例えば、下の@code{first-ec}は、それぞれ異なる3つの正整数(@var{x}, @var{y}, @var{z})で、
@var{x}*@var{x}+@var{y}*@var{y}+@var{z}*@var{z}が@var{w}の平方と等しくなるような
組み合わせのうち最初のものを返します。
@c COMMON

@example
(first-ec #f (:integers w) (: z 1 w) (: y 1 z) (: x 1 y)
          (if (= (* w w) (+ (* x x) (* y y) (* z z))))
          (list x y z w))
@end example

@c EN
Note that the first qualifier, @code{(:integers w)}, generates
infinite number of integers; if you use @code{list-ec} instead of
@code{first-ec} it won't stop.
@c JP
@code{(:integers w)}は無限に整数列を生成することに注意してください。
@code{first-ec}のかわりに@code{list-ec}を使うと、評価は終了しません。
@c COMMON
@end defmac

@defmac fold-ec seed qualifier @dots{} expr proc
@defmacx fold3-ec seed qualifier @dots{} expr init proc
[SRFI-42]
@c MOD srfi.42
@c EN
Reduces the values produced by @var{expr}.
@c JP
@var{expr}が生成する値をまとめます。
@c COMMON

@c EN
Suppose @var{expr} produces a sequence of values
@var{x0}, @var{x1}, @dots{}, @var{xN}.  @code{Fold-ec}
calculates the following value:
@c JP
@var{expr}が生成する値を@var{x0}, @var{x1}, @dots{}, @var{xN}とした場合、
@code{fold-ec}は次の値を計算します:
@c COMMON

@example
(@var{proc} @var{xN} (@dots{}(@var{proc} @var{x1} (@var{proc} @var{x0} @var{seed}))@dots{}))
@end example

@c EN
It's similar to @code{fold}, except that @var{proc} is evaluated
within the scope of @var{qualifier} @dots{} so you can refer to the
variables introduced by them.  On the other hand,
@var{seed} is outside of the scope of @var{qualifier}s.
@c JP
@code{fold}と似ていますが、@var{proc}は@var{qualifier} @dots{}のスコープ内で
評価されるので、それらが導入する変数を参照することができます。
ただし@var{seed}は@var{qualifier}のスコープの外で評価されます。
@c COMMON

@c EN
@code{Fold3-ec} is almost the same but the initial value calculation.
In @code{fold3-ec}, @var{seed} is only used when @var{qualifier}s
makes no iteration.  Otherwise it calculates the following value:
@c JP
@code{fold3-ec}は初期値の計算以外は同じです。
@code{fold3-ec}では、@var{seed}は@var{qualifier}が一度も繰り返しを行わなかった
場合にのみ使われます。そうでなければ以下の値が計算されます:
@c COMMON

@example
(@var{proc} @var{xN} (@dots{}(@var{proc} @var{x1} (@var{init} @var{x0}))@dots{}))
@end example

@end defmac

@subheading Qualifiers

@c EN
@subsubheading Generational qualifiers
@c JP
@subsubheading 生成的qualifier
@c COMMON

@c EN
This type of qualifiers generates (possibly infinite) values
over which the rest of clauses iterate.
@c JP
このタイプのqualifierは、いくつかの値(無限個のこともあります)を次々に
生成し、各値について残りの節を繰り返します。
@c COMMON

@c EN
In the following descriptions, @var{vars} refers to either
a single identifier, or a series of identifier and a form
@code{(index @var{identifier2})}.  The single identifier
in the former case and the first identifier in the latter case
name the variable to which each generated value is bound.
The @var{identifier2} in the latter case names a variable
to which a series of integers, increasing with each generated
element, is bound.   See the following example:
@c JP
以下の説明において、@var{vars}というのはひとつの識別子か、
識別子とフォーム@code{(index @var{identifier2})}の並びです。
最初の形式での識別子、あるいは二番目の形式での最初の識別子は、
生成された値が束縛される変数です。二番目の形式の@var{identifier2}は、
0から始まり値が生成されるたびにインクリメントされる整数値が束縛されます。
次の例を見てください。
@c COMMON

@example
(list-ec (: x '(a b c)) x)
  @result{} (a b c)
(list-ec (: x (index y) '(a b c)) (cons x y))
  @result{} ((a . 0) (b . 1) (c . 2))
@end example

@deffn {EC Qualifier} : vars arg1 args @dots{}
@c EN
A generic dispatcher of generational qualifiers.
An appropriate generational qualifier is selected based on the
types of @var{arg1} @var{args} @dots{}.
@c JP
@var{arg1} @var{args} @dots{} の型に基づいて、以下の生成的qualifierの
いずれかにディスパッチされる、汎用的なqualifierです。
@c COMMON
@end deffn

@deffn {EC Qualifier} :list vars arg1 args @dots{}
@deffnx {EC Qualifier} :vector vars arg1 args @dots{}
@deffnx {EC Qualifier} :uvector vars arg1 args @dots{}
@deffnx {EC Qualifier} :string vars arg1 args @dots{}
@c EN
@var{Arg1} @var{args} @dots{} should be all lists, vectors, uniform vectors
or strings,
respectively.  Repeats the subsequent clauses while binding
each element from those args bound to @var{vars}.
(The @code{:uvector} qualifier is Gauche's extension.)
@c JP
それぞれのフォームにおいて、
@var{arg1} @var{args} @dots{}は全てリスト、ベクタ、ユニフォームベクタ、
あるいは文字列でなければなりません。
各要素を@var{vars}に束縛して続く節を繰り返します。
(@code{:uvector}はGaucheの独自拡張です。)
@c COMMON

@example
(list-ec (:string c "ab" "cd") c) @result{} (#\a #\b #\c #\d)
@end example

@c EN
If the arguments given to the generic qualifier @code{:} are
all lists, vectors, uniform vectors or strings, then these qualifiers are used.
@c JP
汎用qualifier@code{:}に渡された引数が全てリスト、ベクタ、ユニフォームベクタあるいは文字列
であった場合は、これらのqualifierが使われます。
@c COMMON
@end deffn

@deffn {EC Qualifier} :integers vars
@c EN
Generates infinite series of increasing integers, starting from 0.
@c JP
0から始まり1づつ増加しつづける無限正確整数列を生成します。
@c COMMON
@end deffn

@deffn {EC Qualifier} :range vars stop
@deffnx {EC Qualifier} :range vars start stop
@deffnx {EC Qualifier} :range vars start stop step
@deffnx {EC Qualifiter} :range vars range
@c EN
The first three forms
generates a series of exact integers, starting from
@var{start} (defaults to 0) and stops below @var{stop},
stepping by @var{step} (defaults to 1).  Giving a negative
integer to @var{step} makes a decreasing series.
@c JP
最初の3つの形式は、
@var{start}から始まり、@var{step}づつ増加し、@var{stop}を越えないような
正確な整数列を生成します。@var{start}が省略された場合は0、
@var{step}が省略された場合は1が使われます。
@var{step}に負数を与えれば減少列も作れます。
@c COMMON

@example
(list-ec (:range v 5) v)      @result{} (0 1 2 3 4)
(list-ec (:range v 3 8) v)    @result{} (3 4 5 6 7)
(list-ec (:range v 1 8 2) v)  @result{} (1 3 5 7)
(list-ec (:range v 8 1 -2) v) @result{} (8 6 4 2)
@end example

@c EN
If one, two or three exact integer(s) is/are given to the generic
qualifier @code{:}, this qualifier is used.
@c JP
汎用qualifier@code{:}に1個から3個の正確な整数が与えられた場合は、
このqualifierが使われます。
@c COMMON

@c EN
If a range object (@pxref{Range}) is given to this qualifier,
as in the fourth form,
this generates each element in the range sequentially.
@c JP
最後の形式のように、レンジオブジェクト (@ref{Range}参照) が与えられた場合は、
そのレンジの要素を順に生成します。
@c COMMON
@end deffn

@deffn {EC Qualifier} :real-range vars stop
@deffnx {EC Qualifier} :real-range vars start stop
@deffnx {EC Qualifier} :real-range vars start stop step
@c EN
Generates a series of real numbers, starting from
@var{start} (defaults to 0) and stops below @var{stop},
stepping by @var{step} (defaults to 1).  If all the arguments
are exact numbers, the result consists of exact numbers; if any
of the arguments are inexact, the result consists of inexact numbers.
@c JP
@var{start}から始まり、@var{step}づつ増加し、@var{stop}を越えないような
実数列を生成します。@var{start}が省略された場合は0、
@var{step}が省略された場合は1が使われます。
全ての引数が正確数であれば正確な数列が、ひとつでも非正確数が混じって入れば
非正確な数列が生成されます。
@c COMMON

@example
(list-ec (:real-range v 5.0) v)
  @result{} (0.0 1.0 2.0 3.0 4.0)
(list-ec (:real-range v 1 4 1/3) v)
  @result{} (1 4/3 5/3 2 7/3 8/3 3 10/3 11/3)
(list-ec (:real-range v 1 5.0 1/2) v)
  @result{} (1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5)
@end example

@c EN
If one, two or three real numbers is/are given to the generic
qualifier @code{:}, and any one of them isn't an exact integer,
then this qualifier is used.
@c JP
汎用qualifier@code{:}に1個から3個の実数が与えられ、そのうちどれかひとつでも
正確な整数でないものがあれば、このqualifierが使われます。
@c COMMON
@end deffn

@deffn {EC Qualifier} :char-range vars min max
@c EN
Generates a series of characters, starting from @var{min} and
ending at @var{max} (inclusive).  The characters are enumerated
in the order defined by @code{char<=?} (@pxref{Characters}).
@c JP
文字@var{min}から@var{max}まで(両端含む)の文字を順に生成します。
文字順は@code{char<=?}で比べられるのと同じ順になります (@ref{Characters}参照)。
@c COMMON

@example
(list-ec (:char-range v #\a #\e) v)
  @result{} (#\a #\b #\c #\d #\e)
@end example

@c EN
If two characters are given to the generic
qualifier @code{:}, this qualifier is used.
@c JP
汎用qualifier@code{:}に2つの文字が与えられた場合は、
このqualifierが使われます。
@c COMMON
@end deffn

@deffn {EC Qualifier} :port vars port
@deffnx {EC Qualifier} :port vars port read-proc
@c EN
Generates a series of values read from an input port @var{port},
by the procedure @var{read-proc} (defaults to @code{read}).  The
series terminates when EOF is read.
@c JP
入力ポート@var{port}から、@var{read-proc}を使って読まれる値を、
EOFに出会うまで次々に生成します。@var{read-proc}が省略された場合は@code{read}
が使われます。
@c COMMON

@example
(call-with-input-string "a \"b\" :c"
  (^p (list-ec (:port v p) v)))
  @result{} (a "b" :c)
@end example

@c EN
If one or two arguments are given to the generic
qualifier @code{:} and the first one is an input port,
then this qualifier is used.
@c JP
汎用qualifier@code{:}に2つの引数が与えられ、最初の引数が入力ポートであれば、
このqualifierが使われます。
@c COMMON
@end deffn

@deffn {EC Qualifier} :generator vars gen
@c EN
This is Gauche's extension and not defined in SRFI-42.
@var{gen} must be a procedure with zero arguments.
This qualifier repeats until @var{gen} returns EOF.

Gauche has a set of utilities to create and operate on
such procedures; see @ref{Generators}.
@c JP
これはSRFI-42には定義さていない、Gauche独自の拡張です。
@var{gen}は引数と取らない手続きです。このqualifierは
@var{gen}がEOFを返すまで繰り返します。

Gaucheは、そのような手続きを作ったり操作したりする便利な関数群を
提供しています。@ref{Generators}を参照してください。
@c COMMON

@example
(use gauche.generator)
(list-ec (:generator v (grange 1 8)) v)
  @result{} (1 2 3 4 5 6 7)
@end example

@c EN
If one argument is given to the generic
qualifier @code{:} and it is applicable without arguments,
then this qualifier is used.
@c JP
汎用qualifier@code{:}に1つの引数が与えられ、それが引数無しで呼び出し可能なものであれば、
このqualifierが使われます。
@c COMMON
@end deffn

@deffn {EC Qualifier} :collection vars coll
@c EN
This is Gauche's extension and not defined in SRFI-42.
@var{coll} must be an instance of @code{<collection>} or its subclass.
(@pxref{Collection framework}).
This qualifier repeats over the elements in the collection.

If srfi-42 has a specialized qualifier, it is faster to use it
(e.g. a vector is also a collection, but using @code{:vector} is
faster than @code{:collection}).
@c JP
これはSRFI-42には定義さていない、Gauche独自の拡張です。
@var{coll}は@code{<collection>}クラスかそのサブクラスのインスタンスでなければなりません
(@ref{Collection framework}参照)。
このqualifierはコレクションの各要素に対して繰り返します。

特定の型に特化したqualifierがある場合はそちらを使う方が速いです
(例えば、ベクタはコレクションでもありますが、@code{:collection}を使うより
@code{:vector}を使う方が速いです。)
@c COMMON

@c EN
If one argument is given to the generic
qualifier @code{:} and it is a collection other than the specific
types supported directly in SRFI-42, this qualifer is used.
@c JP
汎用qualifier@code{:}に1つの引数が与えられ、
それがSRFI-42で用意されている型以外のコレクションであれば、
このqualifierが使われます。
@c COMMON
@end deffn

@deffn {EC Qualifier} :parallel generator @dots{}
@c EN
This is used to run through multiple generators in parallel.
It terminates when any one of @var{generator} is exhausted.
@c JP
複数のジェネレータ節を並列に走査するのに使います。
@var{generator}のどれかが値を使い切った時点で止まります。
@c COMMON

@example
(list-ec (:parallel (: x '(a b c))
                    (: y "defg"))
  (cons x y))
 @result{} ((a . #\d) (b . #\e) (c . #\f))

;; Compare with this:
(list-ec (: x '(a b c))
         (: y "defg")
  (cons x y))
 @result{} ((a . #\d) (a . #\e) (a . #\f) (a . #\g)
     (b . #\d) (b . #\e) (b . #\f) (b . #\g)
     (c . #\d) (c . #\e) (c . #\f) (c . #\g))
@end example
@end deffn

@deffn {EC Qualifier} :let vars expr
@c EN
Evaluate @var{expr}, and bind the result to @var{vars} and execure
the following clauses once.
If @var{vars} has an index var, it is bound to 0.
It is effectively the same as @code{(:list vars (list expr))}.
@c JP
@var{expr}を評価し、その値を@var{vars}に束縛して1回だけ以降の節を実行します。
@var{vars}にインデックス変数があればそれは0に束縛されます。
実効的には@code{(:list vars (list expr))}と同じです。
@c COMMON
@end deffn

@deffn {EC Qualifier} :while g-qualifier expr
@deffnx {EC Qualifier} :until generator expr
@c EN
Generates values from  @var{g-qualifier} while/until @var{expr} evaluates true.
Here, @var{g-qualifier} is one of generative EC qualifiers.  The variable
bound in @var{g-qualifier} is visible from @var{expr}.
@c JP
@var{g-qualifier}は生成的qualifierです。@var{g-qualifier}が生成する値によって
@var{expr}が真の値である間/真の値になるまで、値を生成しつづけます。@var{expr}内では
@var{g-qualifier}が束縛する変数が使えます。
@c COMMON

@example
(use math.prime)
(sum-ec (:while (: p (index k) *primes*) (<= k 100)) p)
@end example
@end deffn


@deffn {EC Qualifier} :dispatched vars dispatch arg1 args @dots{}
@end deffn

@deffn {EC Qualifier} :do (lb @dots{}) ne1? (ls @dots{})
@deffnx {EC Qualifier} :do (let (ob @dots{}) oc @dots{}) (lb @dots{}) ne1? (let (ib @dots{}) ic @dots{}) ne2? (ls @dots{})
@end deffn

@c EN
@subsubheading Control qualifiers
@c JP
@subsubheading フロー制御qualifier
@c COMMON

@deffn {EC Qualifier} if test
@c EN
Evaluates @var{test}, and if it yields false, stops that iteration
and start the next iteration.
@c JP
@var{test}を評価し、それが偽だった場合はその回の繰り返しを中止し、次の繰り返しに移ります。
@c COMMON

@c EN
The following examples returns a list of pythagorian triplets @code{(a b c)},
which satisfies @code{a^2 + b^2 = c^2}, less than 100.
@c JP
次の例は、@code{a^2 + b^2 = c^2}を満たすピタゴラス数@code{(a b c)}の組を、
c < 100 の範囲で列挙します。
@c COMMON

@example
(list-ec (: c 1 100) (: a 1 c) (: b a c)
         (if (= (square c) (+ (square a) (square b))))
         (list a b c))
  @result{} ((3 4 5) (6 8 10) (5 12 13) (9 12 15) (8 15 17) @dots{})
@end example
@end deffn

@deffn {EC Qualifier} not test
@deffnx {EC Qualifier} and test @dots{}
@deffnx {EC Qualifier} or test @dots{}
@c EN
A shorthand of @code{(if (not test))}, @code{(if (and test @dots{}))}, and
@code{(if (or test @dots{}))}.
@c JP
それぞれ@code{(if (not test))}、@code{(if (and test @dots{}))}、
@code{(if (or test @dots{}))}の略記です。
@c COMMON
@end deffn

@deffn {EC Qualifier} begin command @dots{} expr
@c EN
During iteration, evaluates @var{command} @dots{} for side effects
before evalutes @var{expr}.  The result of @var{command}s are discarded.
@c JP
繰り返しの途中に、@var{expr}を評価する前に@var{command} @dots{}を副作用のために評価します。
@var{command}の結果は捨てられます。
@c COMMON
@end deffn

@deffn {EC Qualifier} nested qualifier @dots{}
@c EN
Splices @var{qualifier} @dots{}.  For example,
@code{(list-ec (: a 2) (nested (: b 2) (: c 2)) (: d 2) (list a b c d))}
is equivalent to
@code{(list-ec (: a 2) (: b 2) (: c 2) (: d 2) (list a b c d))}.
@c JP
@var{qualifier} @dots{}をこの箇所にスプライシングします。たとえば
@code{(list-ec (: a 2) (nested (: b 2) (: c 2)) (: d 2) (list a b c d))} は
@code{(list-ec (: a 2) (: b 2) (: c 2) (: d 2) (list a b c d))} と同じです。
@c COMMON
@end deffn


@c ----------------------------------------------------------------------
@node Vector library (Legacy), Requiring extensions, Eager comprehensions, Library modules - SRFIs
@section @code{srfi.43} - Vector library (legacy)
@c NODE ベクタライブラリ(旧式), @code{srfi.43} - ベクタライブラリ(旧式)

@deftp {Module} srfi.43
@mdindex srfi.43
@c EN
This module is effectively superseded by R7RS and SRFI-133.
There are a few procedures that are not compatible with R7RS and
SRFI-133, and this module remains to support
legacy code that depends on them.

@xref{Vectors}, and @pxref{R7RS vectors}, for the ``modern'' versions
of vector library.  New code should use them.

The following procedures in SRFI-43 are built-in.
@xref{Vectors}, for the description.
@c JP
このモジュールは実効的に、R7RSとSRFI-133に取って代わられています。
いくつかの手続きはR7RSやSRFI-133の同名の手続きとは非互換で、
このモジュールはSRFI-43に依存している既存のコードのためだけに
残されています。

「現代的な」ベクタライブラリは、@ref{Vectors}と@ref{R7RS vectors}
で説明されています。新たなコードはそちらを使うべきです。

以下のSRFI-43の手続きは組み込みになっています。
説明は@ref{Vectors}を参照してください。
@c COMMON

@example
make-vector     vector          vector?         vector-ref
vector-set!     vector-length   vector-fill!    vector-copy
vector-copy!    vector-append   vector->list    list->vector
reverse-list->vector
@end example

@c EN
The following procedures in SRFI-43 are supported by SRFI-133.
@xref{R7RS vectors}, for the description.
@c JP
以下のSRFI-43の手続きはSRFI-133でも同様にサポートされています。
説明は@ref{R7RS vectors}を参照してください。
@c COMMON

@example
vector-unfold         vector-unfold-right   vector-reverse-copy
vector-reverse-copy!  vector-concatenate    vector-empty?
vector=               vector-index          vector-index-right
vector-skip           vector-skip-right     vector-binary-search
vector-any            vector-every          vector-swap!
reverse-vector->list
@end example

@c EN
We explain the procedures that are not listed above.
@c JP
ここでは上に挙げられていない手続きを説明します。
@c COMMON
@end deftp

@defun vector-fold kons knil vec1 vec2 @dots{}
@defunx vector-fold-right kons knil vec1 vec2 @dots{}
[SRFI-43]
@c MOD srfi.43
@c EN
Like @code{vector-fold} and @code{vector-fold-right}
in SRFI-133, but @var{kons}
takes an extra argument, the current index, as its first argument.
So @var{kons} must accept @var{n}+2 arguments, where
@var{n} is the number of given vectors.
It is called as @code{(kons <index> <cumulated-value> <elt1> <elt2> ...)}.
@c JP
SRFI-133の@code{vector-fold}と@code{vector-fold-right}と似ていますが、
@var{kons}手続きは追加で、現在のインデックスを第一引数として取ります。
従って、@var{n}を引数で与えられたベクタの数とすると、
@var{kons}は@var{n+2}個の引数を取らなければなりません。
@var{kons}は@code{(kons <index> <cumulated-value> <elt1> <elt2> ...)}
のように呼ばれます。
@c COMMON

@c EN
Gauche has @code{fold-with-index} (@pxref{Mapping over sequences})
that can be used to fold vectors with index, but the argument order
of @var{kons} is slightly different: It passes the index, each
element from argument vectors, then cumulated values.
@c JP
Gaucheには@code{fold-with-index}があって、ベクタをインデックスつきで
foldするのに使えます(@ref{Mapping over sequences})が、
@var{kons}が受け取る引数の順序が違います: インデックスの次に
各ベクタの要素、そして最後に累積された値が来ます。
@c COMMON

@example
(use srfi.43)
(vector-fold list '() '#(a b c) '#(d e f))
  @result{} (2 (1 (0 () a d) b e) c f)

(use gauche.sequence)
(fold-with-index list '() '#(a b c) '#(d e f))
  @result{} (2 c f (1 b e (0 a d ())))
@end example
@end defun

@defun vector-map f vec1 vec2 @dots{}
@defunx vector-map! f vec1 vec2 @dots{}
@defunx vector-for-each f vec1 vec2 @dots{}
@defunx vector-count f vec1 vec2 @dots{}
[SRFI-43]
@c MOD srfi.43
@c EN
Like @code{vector-map} and @code{vector-for-each} of R7RS,
and @code{vector-map!} and @code{vector-count} in @code{srfi-133},
except @var{f} takes
an extra argument, the current index, as its first argument.
@c JP
R7RSの@code{vector-map}および@code{vector-for-each}、
そして@code{srfi-133}の@code{vector-map!}および@code{vector-cout}と
ほぼ同じですが、@var{f}が現在のインデックスを最初の引数として(他の引数より前に)
取ります。
@c COMMON

@c EN
Gauche provides @code{vector-map-with-index},
@code{vector-map-with-index!} and @code{vector-for-each-with-index}
which are the same as SRFI-43's @code{vector-map}, @code{vector-map!}
and @code{vector-for-each}, respectively.  @xref{Vectors}.
@c JP
GaucheはSRFI-43の@code{vector-map}、@code{vector-map!}、
@code{vector-for-each}互換な手続きをそれぞれ
@code{vector-map-with-index}、
@code{vector-map-with-index!}、@code{vector-for-each-with-index}という
名前で提供しています。@ref{Vectors}参照。
@c COMMON

@example
(vector-map list '#(a b c))
 @result{} #((0 a) (1 b) (2 c))
(vector-map list '#(a b c) '#(d e f g))
 @result{} #((0 a d) (1 b e) (2 c f))
(vector-count = '#(0 2 2 4 4))
 @result{} 3
@end example

@c EN
(Note: The @code{vector-count} example calls @code{=} with
two arguments, the current index and the element, for each element
of the input vector.  So it counts the number of
occasions when the element is equal to the index.)
@c JP
(註: @code{vector-count}は@code{=}を二つの引数、現在のインデックスと
ベクタの要素で呼び出します。従ってこの例は、ベクタの要素がインデックスと一致する
場合を数えています。)
@c COMMON

@c EN
The generic @code{map} and @code{for-each}
in @code{gauche.collection} can be used
on vectors, but the mapped procedure is called without index, and the result
is returned as a list.
@code{(vector-map f vec1 vec2 @dots{})} is operationally equivalent to
@code{(map-to-with-index <vector> f vec1 vec2 @dots{})}.
See @ref{Collection framework} and @ref{Sequence framework}.
@c JP
@code{gauche.collection}のジェネリックな@code{map}や@code{for-each}は
ベクタに対しても使えますが、マップされる手続きはインデックスを取らず、
また結果はリストになります。
@code{(vector-map f vec1 vec2 @dots{})}は機能的には
@code{(map-to-with-index <vector> f vec1 vec2 @dots{})}と同じになります。
詳しくは@ref{Collection framework}と@ref{Sequence framework}を参照してください。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Requiring extensions, Integers as bits, Vector library (Legacy), Library modules - SRFIs
@section @code{srfi.55} - Requiring extensions
@c NODE require の拡張, @code{srfi.55} - require の拡張

@deftp {Module} srfi.55
@mdindex srfi.55
@c EN
This module defines @code{require-extension} macro, a yet another way
to write portable scripts.  See @ref{Feature conditional} and
@ref{Feature-based program configuration language} for other means of
ensuring specific features.
@c JP
このモジュールでは @code{require-extension} マクロが定義されています。
これは、ポータブルなスクリプトを書くためのもうひとつ別の方法です。
指定した特性を確認する他の方法については、@ref{Feature conditional}
および@ref{Feature-based program configuration language}を見てください。
@c COMMON

@c EN
This module is autoloaded when you use @code{require-extension}, so
you don't need explicitly say @code{(use srfi.55)}; for portable scripts,
you shouldn't.
@c JP
このモジュールは、@code{require-extension}を使った際に自動的にロードさ
れます。それゆえ明示的に@code{(use srfi.55)}する必要はありませんし、ポー
タビリティのためにはするべきではありません。
@c COMMON
@end deftp

@defmac require-extension clause @dots{}
[SRFI-55]
@c MOD srfi.55
@c EN
Make extension(s) specified by @var{clause}s available in the rest
of the program.
@c JP
@var{clause}で指定した拡張を以降のプログラムで利用可能にします。
@c COMMON

@c EN
A @var{clause} takes the following form:
@c JP
@var{clause}は以下の形式になります。
@c COMMON
@example
(@var{extension-id} @var{extension-arg} @dots{})
@end example

@c EN
Currently, only @code{srfi} is supported as @var{extension-id}, and
its arguments are SRFI numbers.
@c JP
現時点では、@code{srfi}のみ@var{extension-id}として使えます。その引数
はSRFIの番号です。
@c COMMON

@c EN
For example, the following form:
@c JP
たとえば、以下の
@c COMMON
@example
(require-extension (srfi 1 13 14))
@end example

@c EN
Roughly corresponds to Gauche's @code{use} forms:
@c JP
は以下の Gauche の @code{use} 形式にほぼ対応します。
@c COMMON
@example
(use srfi.1)
(use srfi.13)
(use srfi.14)
@end example
@end defmac

@c ----------------------------------------------------------------------
@node Integers as bits, A Scheme API for test suites, Requiring extensions, Library modules - SRFIs
@section @code{srfi.60} - Integers as bits
@c NODE 整数に対するビット操作, @code{srfi.60} - 整数に対するビット操作

@deftp {Module} srfi.60
@mdindex srfi.60
@c EN
This srfi provides bit operations on integers, regarding them
as 2's complement representation.  It is compatible to SLIB's @code{logical}
module.
@c JP
このsrfiは、2の補数表現とみなした正確な整数に対するビット演算を提供します。
SLIBの@code{logical}モジュールと互換です。
@c COMMON

@c EN
The newer SRFI-151 (@pxref{R7RS bitwise operations}) provides the same
functionality and more, with more consistent naming.  We recommend
new code to use SRFI-151, while we keep SRFI-60 for the backward
compatibility.
@c JP
より新しいSRFI-151 (@ref{R7RS bitwise operations})はこのsrfiの機能を
カバーし、新しい機能を加え、さらに一貫性のある名前を採用しています。
新に書くコードにはSRFI-151を使ってください。
SRFI-60は後方互換性のために残されています。
@c COMMON

@c EN
The following procedures are Gauche built-in.
@xref{Basic bitwise operations}, for the description.
@c JP
以下の手続きはGauche組み込みです。
@ref{Basic bitwise operations}を参照してください。
@c COMMON

@example
lognot           logand           logior           logxor
logtest          logcount         integer-length   logbit?
copy-bit         bit-field        copy-bit-field   ash
@end example

@c EN
The following procedures are defined in SRFI-151.
@xref{R7RS bitwise operations}, for the description.
@c JP
以下の手続きはSRFI-151で定義されています。
@ref{R7RS bitwise operations}を参照してください。
@c COMMON

@example
bitwise-not      bitwise-and      bitwise-ior      bitwise-xor
arithmetic-shift bit-count        bitwise-if       bit-set?
copy-bit         first-set-bit
@end example
@end deftp

@c EN
We describe procedures that are unique in SRFI-60 below.
@c JP
SRFI-60特有の手続きを以下に説明します。
@c COMMON

@defun bitwise-merge mask n0 n1
[SRFI-60]
@c MOD srfi.60
@c EN
Same as @code{bitwise-if} (@pxref{R7RS bitwise operations}).
@c JP
@code{bitwise-if}と同じです(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@defun any-bits-set? mask n
[SRFI-60]
@c MOD srfi.60
@c EN
Same as builtin @code{logtest} (@pxref{Basic bitwise operations}).
It is also called @code{any-bit-set?} in SRFI-151 (@pxref{R7RS bitwise operations}).
@c JP
組み込みの@code{logtest}と同じです (@ref{Basic bitwise operations}参照)。
SRFI-151では@code{any-bit-set?}と呼ばれています
(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@defun log2-binary-factors n
[SRFI-60]
@c MOD srfi.60
@c EN
It is also called as @code{first-set-bit} in this srfi, which is also
in SRFI-151 (@pxref{R7RS bitwise operations}).
This is equivalent to Gauche's built-in  @code{twos-exponent-factor}
(@pxref{Basic bitwise operations}).
@c JP
これはこのsrfiの@code{first-set-bit}の別名で、@code{first-set-bit}の方は
SRFI-151で提供されています(@ref{R7RS bitwise operations}参照)。
また、Gaucheの組み込みである@code{twos-exponent-factor}とも同じです
(@ref{Basic bitwise operations}参照)。
@c COMMON
@end defun

@defun rotate-bit-field n count start end
[SRFI-60]
@c MOD srfi.60
@c EN
This is equivalent to @code{bit-field-rotate} in SRFI-151
(@pxref{R7RS bitwise operations}).
@c JP
SRFI-151の@code{bit-field-rotate}と同じです(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@defun reverse-bit-field n start end
[SRFI-60]
@c MOD srfi.60
@c EN
This is equivalent to @code{bit-field-reverse} in SRFI-151
(@pxref{R7RS bitwise operations}).
@c JP
SRFI-151の@code{bit-field-reverse}と同じです(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@defun integer->list n :optional len
[SRFI-60]
@c MOD srfi.60
@c EN
Breaks @var{n} to each bits, representing @code{1} as @code{#t} and
@code{0} as @code{#f}, LSB last, and returns a list of them.
If a nonnegative integer @var{len} is given, it specifies the length
of the result.   If it is omitted, @code{(integer-length n)} is used.
@c JP
整数nをビットに分割し、論理値のリストとして返します。
@code{1}であるビットが@code{#t}に、
@code{0}であるビットが@code{#f}にマップされます。MSBが最初、LSBが最後になります。
非負整数@var{len}が与えられた場合は、それが結果の長さを指定します。
そうでなければ @code{(integer-length n)}が結果の長さになります。
@c COMMON

@example
(integer->list 10)   @result{} (#t #f #t #f)
(integer->list 10 6) @result{} (#f #f #t #f #t #f)
@end example

@c EN
SRFI-151 has similar procedure @code{bits->list}, with a reversed bit
order (LSB first) (@pxref{R7RS bitwise operations}).
@c JP
SRFI-151の@code{bits->list}は、ビット順が逆 (LSBが最初) であることを除けば
これと同じです(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@defun list->integer lis
[SRFI-60]
@c MOD srfi.60
@c EN
Takes a list of boolean values, replaces the true value for @code{1}
and the false value for @code{0}, and compose an integer regarding
each value as a binary digit.  If @var{n} is nonnegative integer,
@code{(eqv? (list->integer (integer->list n)) n)} is true.
@c JP
論理値のリストを取り、@code{#t}を@code{1}、@code{#f}を@code{0}と解釈して、
各ビットからなる整数を返します。@var{n}を非負整数とすると、
@code{(eqv? (list->integer (integer->list n)) n)}が成り立ちます。
@c COMMON

@example
(list->integer '(#f #t #f #t #f)) @result{} 10
@end example

@c EN
SRFI-151 has similar procedure @code{list->bits}, with a reversed bit
order (LSB first) (@pxref{R7RS bitwise operations}).
@c JP
SRFI-151の@code{list->bits}は、ビット順が逆 (LSBが最初) であることを除けば
これと同じです(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@defun booleans->integer bool @dots{}
[SRFI-60]
@c MOD srfi.60
@equiv{} @code{(list->integer (list @var{bool} @dots{}))}

@c EN
SRFI-151 has similar procedure @code{bits}, with a reversed bit
order (LSB first) (@pxref{R7RS bitwise operations}).
@c JP
SRFI-151の@code{bits}は、ビット順が逆 (LSBが最初) であることを除けば
これと同じです(@ref{R7RS bitwise operations}参照)。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node A Scheme API for test suites, Octet vectors, Integers as bits, Library modules - SRFIs
@section @code{srfi.64} - A Scheme API for test suites
@c NODE SchemeテストスイートAPI, @code{srfi.64} - SchemeテストスイートAPI

@deftp {Module} srfi.64
@mdindex srfi.64
@c EN
This module defines API to write a portable test suite.  In Gauche,
it is adapted to work with @code{gauche.test} native test framework
(@pxref{Unit testing}).
@c JP
このモジュールはポータブルなテストスイートを書くAPIを提供します。
Gaucheでは、このsrfiは@code{gauche.test}と協調して動くようになっています
(@ref{Unit testing}参照)。
@c COMMON

@c EN
If SRFI-64 tests are run during @code{gauche.test}
the tests becomes a part of the whole @code{gauche.test} suite.
@c JP
@code{gauche.test}が有効な状態で、SRFI-64テストを走らせた場合、
それらのテストは@code{gauche.test}の一部として実行されます。
@c COMMON

@c EN
The recommended way is to write a test suite in pure srfi-64, then include
it from the gauche test script:
@c JP
推奨されるテストの書き方は、ポータブルなテストをsrfi-64のみで書き、
Gaucheテストスクリプトから次のとおりincludeすることです。
@c COMMON

@example
(use gauche.test)
(test-start "the tests")
;; portable test
(include "test-suite-in-srfi-64")

;; gauche-specific test, if needed
...

(test-end)
@end example

@c EN
If @file{test-suite-in-srfi-64.scm} is run by itself, it uses SRFI-64's
default reporting system.  If it is run within @code{gauche.test} script,
the results are reported via @code{gauche.test}, consolidated with other
Gauche test results.
@c JP
@file{test-suite-in-srfi-64.scm}をそれ単独で走らせた場合は、
SRFI-64のデフォルトのテスト報告形式で結果が報告されます。
@code{gauche.test}スクリプトからincludeして走らせた場合は、
結果が@code{gauche.test}の報告形式を使って、他のGaucheテストと合わせて報告されます。
@c COMMON
@end deftp

@menu
* SRFI-64 test runner::
* SRFI-64 test API::
@end menu

@node SRFI-64 test runner, SRFI-64 test API, A Scheme API for test suites, A Scheme API for test suites
@subsection Test runner

In SRFI-64, tests are run with an active @emph{test runner} which collects
test results and emits reports.  It allows users to provide custom runners
to handle tailored reports suitable to the specific tests.

@subsubheading Test runner object

@deftp {Record} test-runner
[SRFI-64]
@c MOD srfi.64

@end deftp

@defun test-runner? obj
[SRFI-64]
@c MOD srfi.64
@end defun

@deftp {Parameter} test-runner-current
[SRFI-64]
@c MOD srfi.64
@end deftp

@defun test-runner-get
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-simple
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-null
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-factory :optional factory
[SRFI-64]
@c MOD srfi.64
@end defun


@subsubheading Running tests with a specified runner

@defun test-apply [runner] specifier @dots{} procedure
[SRFI-64]
@c MOD srfi.64
@end defun

@defmac test-with-runner runner decl-or-expr @dots{}
[SRFI-64]
@c MOD srfi.64
@end defmac


@subsubheading Latest result properties

A runner holds a single alist to keep the latest result properties.
Except the @code{result-kind} property, which is set by every basic
test procedures, the usage of properties are up to the test runner
and/or test writer.

@defun test-result-clear runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-result-ref runner pname :optional default
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-result-set! runnre pname value
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-result-remove runner pname
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-result-alist runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-result-kind :optional runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-passed? :optional runner
[SRFI-64]
@c MOD srfi.64
@end defun

@subsubheading Keeping track of test status

@defun test-runner-pass-count runner
@defunx test-runner-fail-count runner
@defunx test-runner-xpass-count runner
@defunx test-runner-xfail-count runner
@defunx test-runner-skip-count runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-test-name runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-group-path runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-group-stack runner
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-aux-value runner
@defunx test-runner-aux-value! runner value
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-reset runner
[SRFI-64]
@c MOD srfi.64
@end defun

@subsubheading Callbacks

@defun test-runner-on-test-begin runner
@defunx test-runner-on-test-begin! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-on-test-end runner
@defunx test-runner-on-test-end! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-on-group-begin runner
@defunx test-runner-on-group-begin! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-on-group-end runner
@defunx test-runner-on-group-end! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-on-bad-count runner
@defunx test-runner-on-bad-count! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-on-bad-end-name runner
@defunx test-runner-on-bad-end-name! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-runner-on-final runner
@defunx test-runner-on-final! runner proc
[SRFI-64]
@c MOD srfi.64
@end defun


@defun test-on-test-begin-simple runner
@defunx test-on-test-end-simple runner
@defunx test-on-group-begin-simple runner
@defunx test-on-group-end-simple runner
@defunx test-on-bad-count-simple runner actual-count expected-count
@defunx test-on-bad-end-name-simple runner begin-name end-name
[SRFI-64]
@c MOD srfi.64
@end defun

@node SRFI-64 test API,  , SRFI-64 test runner, A Scheme API for test suites
@subsection Test API

@subsubheading Test grouping

SRFI-64 tests can be grouped, and groups can be nested.

@defun test-begin suite-name :optional count
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-end :optional suite-name
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-group suite-name body @dots{}
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-group-with-cleanup suite-name body @dots{} cleanup
[SRFI-64]
@c MOD srfi.64
@end defun

@subsubheading Individual tests

@defmac test-assert [test-name] expr
[SRFI-64]
@c MOD srfi.64
@end defmac

@defmac test-eqv [test-name] expected test-expr
@defmacx test-eq [test-name] expected test-expr
@defmacx test-equal [test-name] expected test-expr
[SRFI-64]
@c MOD srfi.64
@end defmac

@defmac test-approximate [test-name] extected test-expr margin
[SRFI-64]
@c MOD srfi.64
@end defmac

@defmac test-error [[test-name] error-type] test-expr
[SRFI-64]
@c MOD srfi.64
@end defmac

@defun test-read-eval-string string
[SRFI-64]
@c MOD srfi.64
@end defun

@defmac test-expect-fail specifier
[SRFI-64]
@c MOD srfi.64
@end defmac


@subsubheading Conditional tests

@defun test-match-name name
@defunx test-match-nth n :optional count
@defunx test-match-any specifier @dots{}
@defunx test-match-all specifier @dots{}
[SRFI-64]
@c MOD srfi.64
@end defun

@defun test-skip specifier
[SRFI-64]
@c MOD srfi.64
@end defun


@c ----------------------------------------------------------------------
@node Octet vectors, Basic hash tables, A Scheme API for test suites, Library modules - SRFIs
@section @code{srfi.66} - Octet vectors
@c NODE オクテットベクタ, @code{srfi.66} - オクテットベクタ

@deftp {Module} srfi.66
@mdindex srfi.66
@c EN
This module defines procedures to deal with @code{u8vector}s; they are
almost a subset of @code{srfi.160} and @code{gauche.uvector}
(@pxref{Uniform vectors}, except one procedure, @code{u8vector-copy!},
which has different argument orders (unfortunate historical artifacts).
@c JP
このモジュールは@code{u8vector}に特化した手続きを定義します。
ほぼ@code{srfi.160}および@code{gauche.uvector}のサブセットです。
(@pxref{Uniform vectors})。例外は@code{u8vector-copy!}で、
これは不幸な歴史的事情から、@code{gauche.uvector}と引数順が異なります。
@c COMMON

@c EN
There's no reason to use this srfi except porting code that relies
on @code{srfi.66}.
@c JP
@code{srfi.66}に依存するコードを移植するのでなければ、
このモジュールを使う場面は無いでしょう。
@c COMMON

@c EN
The following procedures are the same as @code{gauche.uvector}:
@c JP
以下の手続きは@code{gauche.uvector}と同じです。
@c COMMON

@example
u8vector?       make-u8vector      u8vector
u8vector->list  list->u8vector
u8vector-length u8vector-ref       u8vector-set!
u8vector=?      u8vector-compare   u8vector-copy
@end example
@end deftp

@defun u8vector-copy! src sstart target tstart n
[SRFI-66]
@c MOD srfi.66
@c EN
Copy the content of an u8vector @var{src}, starting from @var{sstart}
for @var{n} octets, into an u8vector @var{target} beginning from
@var{tstart}.  The @var{target} u8vector must be mutable.
@c JP
u8vectorである@var{src}の、インデックス@var{sstart}から@var{n}オクテットを、
u8vector @var{target}のインデックス@var{tstart}からにコピーします。
@var{target}は変更可能なu8vectorでなければなりません。
@c COMMON

@c EN
Note that @code{gauche.uvector} has also @code{u8vector-copy!},
but its argument order is as follows, where @var{send}
is @code{(+ @var{sstart} @var{n})}:
@c JP
@code{gauche.uvector}も@code{u8vector-copy!}を提供しますが、
引数が異なります。@var{send}を@code{(+ @var{sstart} @var{n})}として、
次のとおりです:
@c COMMON

@example
(u8vector-copy! target tstart src sstart send)
@end example

@c EN
Gauche's argument order is consistent with @code{vector-copy!} of
R7RS, SRFI-43 and SRFI-133.

We recommend to use @code{srfi.66} only for porting third-party
libraries to avoid confusion.
@c JP
Gaucheの引数順は、R7RS、SRFI-43およびSRFI-133の@var{vector-copy!}と
一貫性があります。

混乱を避けるため、
@code{srfi.66}モジュールはサードパーティライブラリを移植する際に必要な場合に限り
使うと良いでしょう。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Basic hash tables, Octet-addressed binary blocks, Octet vectors, Library modules - SRFIs
@section @code{srfi.69} - Basic hash tables
@c NODE 基本的なハッシュテーブル, @code{srfi.69} - 基本的なハッシュテーブル

@deftp {Module} srfi.69
@mdindex srfi.69
@c EN
This module has been superseded by R7RS @code{scheme.hash-table}
(@pxref{R7RS hash tables}).  New code should use it instead.
@c JP
このモジュールはR7RSの@code{scheme.hash-table}により更改されています。
(@ref{R7RS hash tables}参照)。新たなコードはそちらを使うようにしてください。
@c COMMON

@c EN
This is a thin adaptor on Gauche's built-in hashtables
(@pxref{Hashtables}).  This is provided for the compatibility
to the portable libraries; the hashtable object created by
this module's @code{make-hash-table} is the same as the one
created by Gauche's built-in, and you can pass the table to
both APIs.
@c JP
このモジュールは、Gauche組み込みのハッシュテーブルのごく薄いラッパーです
(@ref{Hashtables}参照)。このsrfiを要求するライブラリへの互換性のためだけに
提供されています。このモジュールの@code{make-hash-table}で作られるハッシュテーブルは
Gauche組み込みのハッシュテーブルそのものなので、どちらのAPIにも渡せます。
@c COMMON
@end deftp

@c EN
Here's a summary of difference between SRFI-69 and Gauche's built-in
hash table API:
@c JP
SRFI-69とGaucheのAPIの違いを挙げておきます:
@c COMMON

@itemize
@item
@c EN
The constructor @code{make-hash-table}, as well as @code{alist->hash-table},
takes equality predicate and hash function, instead of a single
comparator argument as Gauche does.
@c JP
コンストラクタ@code{make-hash-table}および@code{alist->hash-table}は、
Gaucheでは比較器を取りますが、SRFI-69では等価述語とハッシュ関数を取ります。
@c COMMON
@item
@c EN
The hash function passed to SRFI-69's @code{make-hash-table}
takes two arguments, an object to calculate a hash value,
and a positive integer that limits the range of the hash value.
@c JP
SRFI-69の@code{make-hash-table}に渡されるハッシュ関数は、
ハッシュ値を計算するオブジェクトに加え、ハッシュ値の範囲を指定する整数を取ります。
@c COMMON
@item
@c EN
SRFI-69's primary hash table accessor is @code{hash-table-ref},
which takes a thunk to be called when the table doesn't have an
entry for the given key, while Gauche's @code{hash-table-get} takes
a fallback value for that.
SRFI-69 also has @code{hash-table-ref/default},
which takes a fallback value like Gauche's @code{hash-table-get},
but the default value can't be omitted.
@c JP
SRFI-69の基本アクセサである@code{hash-table-ref}は、
キーが登録されていなかった場合のデフォルト値を得るために、サンクを取ります。
Gaucheの@code{hash-table-ref}はデフォルト値そのものを取ります。
SRFI-69の@code{hash-table-ref/default}が、Gaucheの@code{hash-table-ref}に
相当します。(但し@code{hash-table-ref/default}はデフォルト値を省略できません)。
@c COMMON
@item
@c EN
SRFI-69's @code{hash-table-update!} and @code{hash-table-update!/default}
to Gauche's @code{hash-table-update!} is the same as
@code{hash-table-ref}, @code{hash-table-ref/default} and
@code{hash-table-get}.
@c JP
SRFI-69の@code{hash-table-update!}と@code{hash-table-update!/default}に対する
Gaucheの@code{hash-table-update!}は、
@code{hash-table-ref}と@code{hash-table-ref/default}に対する
@code{hash-table-get}の関係と同じです。
@c COMMON
@item
@c EN
The basic iterator of SRFI-69 is called @code{hash-table-walk},
which is Gauche's @code{hash-table-for-each}.  The srfi name is chosen
to avoid conflict with existing Scheme implementations.
@c JP
Gaucheの@code{hash-table-for-each}に相当するイテレータはSRFI-69では
@code{hash-table-walk}です。
srfiは既存の実装と名前がぶつからないようにこの名前を採用しました。
@c COMMON
@end itemize

@c EN
The following procedures are the same as Gauche's built-in ones.
@xref{Hashtables}, for the details.
@c JP
以下の手続きはGauche組み込みのものと同じです。
@ref{Hashtables}を参照してください。
@c COMMON

@example
hash-table?       hash-table-delete!   hash-table-exists?
hash-table-keys   hash-table-values    hash-table-fold
hash-table->alist hash-table-copy
@end example


@defun make-hash-table :optional eq-pred hash-proc :rest args
[SRFI-69]
@c MOD srfi.69
@c EN
Creates a new hashtable and returns it.  This is the same name
as Gauche's built-in procedure, but the arguments are different.
@c JP
新たなハッシュテーブルを作って返します。Gauche組み込みのものと同じ名前ですが、
引数が異なります。
@c COMMON

@c EN
The @var{eq-pred} argument is an equality predicate; it takes
two arguments and returns @code{#t} if two are the same,
and @code{#f} if not.  When omitted, @code{equal?} is used.
@c JP
@var{eq-pred}は等価判定述語です。
二つの引数を取り、それらが等価であるとみなされる場合に@code{#t}を返します。
省略された場合は@code{equal?}が使われます。
@c COMMON

@c EN
The @var{hash-proc} argument is a hash function.
It takes two arguments: an object to hash, and a positive
integer to limit the range of the hash value.  (Note that
Gauche's native hash functions takes only one argument.)
When omitted, Gauche tries to choose appropriate hash function
if @code{eq-pred} is known one (@code{eq?}, @code{eqv?},
@code{equal?}, @code{string=?} or @code{string-ci=?}).
Otherwise we use @code{scheme.hash-table}'s @code{hash} procedure
(@pxref{R7RS hash tables}).
But there's no guarantee that the generic @code{hash}
works appropriately; you should give
suitable @var{hash-proc} if you pass custom @var{eq-pred}.
@c JP
@var{hash-proc}はハッシュ関数です。ハッシュ値を計算したいオブジェクトと、
ハッシュ値の範囲を指定する正の整数の、二つの引数を取ります。
(Gaucheの組み込みのハッシュ関数は一つの引数しか取らないことに注意してください)。
省略された場合、Gaucheは@code{eq-pred}が既知の関数
(@code{eq?}、@code{eqv?}、@code{equal?}、@code{string=?}、
@code{string-ci=?})であればそれにふさわしいハッシュ関数を提供し、
そうでなければ@code{scheme.hash-table}の@code{hash}を使います
(@ref{R7RS hash tables}参照)。
ただ、ジェネリックな@code{hash}が常にふさわしいとは限りません。
@var{eq-pred}を渡したなら、適切な@var{hash-proc}も渡すべきです。
@c COMMON

@c EN
The returned hash table is an instance of Gauche's native
hash table.  You can pass it to Gauche's builtin procedures.
@c JP
返されるハッシュテーブルはGaucheのネイティブハッシュテーブルです。
従ってそれをGaucheの組み込み関数に渡すこともできます。
@c COMMON

@c EN
SRFI-69 allows implementation-specific arguments @var{args} to be
passed to @code{make-hash-table}.  At this moment, Gauche
ignores them.
@c JP
SRFI-69は@code{make-hash-table}に実装依存の余分な引数@var{args}
を渡すことを許しています。今のところ、Gaucheは余分な引数は単に無視します。
@c COMMON
@end defun

@defun alist->hash-table alist :optional eq-pred hash-fn :rest args
[SRFI-69]
@c MOD srfi.69
@c EN
Like Gauche's builtin @code{alist->hash-table}, but takes
@var{eq-pred} and @var{hash-fn} separately,
instead of a single comparator.
@c JP
組み込みの@code{alist->hash-table}と似てますが、
単一の比較器ではなく
@var{eq-pred}と@var{hash-fn}を別々に取ります。
@c COMMON

@c EN
The @var{alist} argument is a list of pairs.  The car of each
pair is used for a key, and the cdr for its value.
@c JP
@var{alist}引数はペアのリストです。それぞれのペアの
carがキー、cdrが対応する値になります。
@c COMMON

@c EN
See @code{make-hash-table} above for the description of
@var{eq-pred}, @var{hash-fn} and @var{args}.
@c JP
@var{eq-pred}、@var{hash-fn}、および@var{args}についての詳細は
上の@code{make-hash-table}を参照してください。
@c COMMON
@end defun

@defun hash-table-equivalence-function ht
@defunx hash-table-hash-function ht
[SRFI-69]
@c MOD srfi.69
@c EN
Returns equivalence function and hash function of the
hashtable @var{ht}.
@c JP
ハッシュテーブル@var{ht}の等価判定述語とハッシュ関数をそれぞれ返します。
@c COMMON

@c EN
Note that SRFI-69's hash function takes an optional
@var{bound} argument.   Since our underlying hash tables
don't use bound argument, we actually wrap the internal hash function
to allow the optional bound argument.
@c JP
SRFI-69のハッシュ関数は省略可能な@var{bound}引数を取ることになっています。
Gaucheのハッシュテーブルのハッシュ関数は@var{bound}引数を取らないので、
@code{hash-table-hash-function}が返す関数はラッパーをかませて
省略可能な@var{bound}引数を取るようにしています。
@c COMMON
@end defun

@defun hash-table-ref ht key :optional thunk
[SRFI-69]
@c MOD srfi.69
@c EN
Looks up the value corresponding to @var{key} in a hash table @var{ht}.
If there's no entry for @var{key}, @var{thunk} is called
without arguments, and its result is returned.
The default of @var{thunk} is to signal an error.
@c JP
ハッシュテーブル@var{ht}からキー@var{key}を探し、対応する値を返します。
@var{key}がテーブル中に無かった場合、@var{thunk}が引数なしで呼ばれ、
その結果が戻り値となります。
@var{thunk}の省略時の値はエラーを投げる手続きです。
@c COMMON

@c EN
This convention differs from Gauche's built-in @code{hash-table-get},
which takes optonal @var{default} argument to be returned when the key
doesn't exist (@pxref{Hashtables}).  The following equivalence holds:
@c JP
このインタフェースGauche組み込みの@code{hash-table-get}と異なることに
注意してください。@code{hash-table-get}は省略可能な@var{default}引数を取り、
キーが見つからなかった場合はそれを返します(@ref{Hashtables}参照)。
次の関係が成り立ちます。
@c COMMON

@example
(hash-table-get ht key default) @equiv{} (hash-table-ref ht key (^[] default))
@end example
@end defun

@defun hash-table-ref/default ht key default
[SRFI-69]
@c MOD srfi.69
@c EN
Looks up the value corresponding to @var{key} in a hash table @var{ht}.
If the key doesn't exist, @var{default} is returned.
This is like Gauche's @code{hash-table-get}, but @var{default} can't be
omitted (@pxref{Hashtables}).
@c JP
ハッシュテーブル@var{ht}からキー@var{key}に対応する値を探して返します。
キーが見つからなければ@var{default}が返されます。
組み込みの@code{hash-table-get}と似ていますが、@var{default}
は省略できません(@ref{Hashtables}参照)。
@c COMMON
@end defun

@defun hash-table-set! ht key val
[SRFI-69]
@c MOD srfi.69
@c EN
This is the same as Gauche's @code{hash-table-put!} (@pxref{Hashtables}).
@c JP
Gaucheの@code{hash-table-put!}と同じです(@ref{Hashtables}参照)。
@c COMMON
@end defun

@defun hash-table-update! ht key proc :optional thunk
@defunx hash-table-update!/default ht key proc default
[SRFI-69]
@c MOD srfi.69
@c EN
Calls @var{proc} with the value associated to @var{key} in @var{ht},
and replace the value in @var{ht} with the result of @var{proc}.
The following functional equivalences hold, though these procedures
may be more efficient.
@c JP
@var{ht}中の@var{key}に対応する値を引数として@var{proc}を呼び出し、
@var{ht}中の値を@var{proc}の戻り値で置き換えます。
以下の機能的な等価性が成り立ちますが、これらの手続きの方が効率的かもしれません。
@c COMMON

@example
(hash-table-update! ht key proc thunk)
 @equiv{} (hash-table-set! ht key (proc (hash-table-ref ht key thunk)))

(hash-table-update!/default ht key proc default)
 @equiv{} (hash-table-set! ht key (proc (hash-table-ref/default ht key default)))
@end example

@c EN
Note that Gauche's built-in @code{hash-table-update!} is different, for
it takes optional @var{default} argument instead of @var{thunk}
(@pxref{Hashtables}).
@c JP
Gauche組み込みの@code{hash-table-update!}は@var{thunk}ではなく@var{default}
を取る点で異なっていることに注意してください(@ref{Hashtables}参照)
@c COMMON
@end defun

@defun hash-table-size ht
[SRFI-69]
@c MOD srfi.69
@c EN
Returns the number of entries in a hash table @var{ht}.  The same as Gauche's
@code{hash-table-num-entries}.
@c JP
ハッシュテーブル@var{ht}中のエントリの数を返します。
Gaucheの@code{hash-table-num-entries}と同じです。
@c COMMON
@end defun

@defun hash-table-walk ht proc
[SRFI-69]
@c MOD srfi.69
@c EN
For each entry in a hash table @var{ht},
calls @var{proc} with two arguments, a key and its value.
It's the same as Gauche's @code{hash-table-for-each}.
@c JP
ハッシュテーブル@var{ht}の各エントリにつき、
キーと値を引数として@var{proc}を呼びます。
Gaucheの@code{hash-table-for-each}と同じです。
@c COMMON
@end defun

@defun hash-table-merge! ht1 ht2
[SRFI-69]
@c MOD srfi.69
@c EN
Add all entries in a hash table @var{ht2} into a hash table @var{ht1},
and returns @var{ht1}.  Note that @var{ht1} is destructively modified.
If an entry with the same key exists in both @var{ht1} and @var{ht2},
its value in @var{ht1} is replaced with @var{ht2}'s.
@c JP
@var{ht2}の全てのエントリを@var{ht1}に追加し、@var{ht1}を返します。
@var{ht1}は破壊的に変更されることに注意してください。
同じキーを持つエントリが@var{ht1}と@var{ht2}の両方にあった場合は、
@var{ht2}の値で@var{ht1}のエントリが上書きされます。
@c COMMON
@end defun

@defun hash obj :optional bound
[SRFI-69]
@c MOD srfi.69
@c EN
Like Gauche's @code{hash}, except this one can take @var{bound} argument;
if provided, it must be a positive integer, and the return value
is limited between 0 and @code{(- bound 1)}, inclusive.
@c JP
Gaucheの@code{hash}と似ていますが、省略可能な@var{bound}引数を取ります。
@var{bound}引数は与えられるなら正の整数でなければならず、
返される値が0から@code{(- bound 1)} (両端含む) までに制限されます。
@c COMMON
@end defun

@defun string-hash obj :optional bound
@defunx string-ci-hash obj :optional bound
[SRFI-69]
@c MOD srfi.69
@c EN
These are like SRFI-13's (@pxref{String library}), except
these don't take @var{start} and @var{end} argument.
@c JP
SRFI-13の同名の手続きと似ていますが、@var{start}/@var{end}引数は取りません
(@ref{String library}参照)。
@c COMMON
@end defun

@defun hash-by-identity obj :optional bound
[SRFI-69]
@c MOD srfi.69
@c EN
This is Gauche's @code{eq-hash}, except this one can take bound argument.
@c JP
@var{bound}引数を取ること以外はGaucheの@code{eq-hash}と同じです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Octet-addressed binary blocks, Lightweight testing, Basic hash tables, Library modules - SRFIs
@section @code{srfi.74} - Octet-addressed binary blocks
@c NODE オクテットを単位とするバイナリブロック, @code{srfi.74} - オクテットを単位とするバイナリブロック

@deftp {Module} srfi.74
@mdindex srfi.74
@c EN
This module provides procedures to deal with @emph{blob},
or a sequence of octets.  In Gauche, a blob is simply an u8vector.
@c JP
このモジュールは、オクテットの列である@var{blob}を扱う手続きを提供します。
Gaucheではblobは単なるu8vectorです。
@c COMMON

@c EN
Most functionalities of this module is available
in @code{binary.io} module (@pxref{Binary I/O}), and in fact
this module is a thin wrapper to it.
We provide this module for the compatibility.
If you're writing Gauche-specific code, we recommend to use
@code{binary.io} directly.
@c JP
このモジュールの機能はほとんど@code{binary.io}モジュールにあり、
実際、@code{binary.io}の薄いラッパーとして実装されています
(@ref{Binary I/O})。
このモジュールは互換性のために提供されています。Gauche専用のコードを書くなら
@code{binary.io}を直接使うのが良いでしょう。
@c COMMON
@end deftp

@defmac endianness e
[SRFI-74]
@c MOD srfi.74
@c EN
The argument @var{e} must be one of the symbols @code{big}, @code{little},
or @code{native}.  It expands to the implementation-specific
endianness designator.  In Gauche, the result is one of the
symbols; @pxref{Endianness}, for the details.
@c JP
@var{e}はシンボル@code{big}、@code{little}、@code{native}のいずれかでなければ
なりません。これは、エンディアンネスを示す実装依存のオブジェクトへと展開されます。
Gaucheではそれは単なるシンボルです。詳しくは@ref{Endianness}を参照してください。
@c COMMON
@end defmac

@defun make-blob size
[SRFI-74]
@c MOD srfi.74
@c EN
Returns a freshly created blob that can hold @var{size} octets.
In Gauche, this is the same as @code{(make-u8vector size)}.
@c JP
@var{size}オクテットの大きさを持つblobを新に作って返します。
Gaucheではこれは@code{(make-u8vector size)}と同じです。
@c COMMON
@end defun

@defun blob? obj
[SRFI-74]
@c MOD srfi.74
@c EN
Returns @code{#t} if @var{obj} is a blob, @code{#f} otherwise.
In Gauche, this is the same as @code{(u8vector? obj)}.
@c JP
@var{obj}がblogなら@code{#t}を、そうでなければ@code{#f}を返します。
Gaucheではこれは@code{(u8vector? obj)}と同じです。
@c COMMON
@end defun

@defun blob-length blob
[SRFI-74]
@c MOD srfi.74
@c EN
Returns the size of the blob, in octets.  In Gauche,
this is the same as @code{(u8vector-length blob)}.
@c JP
blogのオクテットで測ったサイズを返します。
Gaucheeではこれは@code{(u8vector-length blob)}と同じです。
@c COMMON
@end defun

@defun blob-uint-ref size endian blob pos
@defunx blob-sint-ref size endian blob pos
[SRFI-74]
@c MOD srfi.74
@c EN
Read an unsigned or signed integer of @var{size} octets beginning
at the position of @var{pos} from @var{blob}, respectively.

These are wrappers of @code{(get-uint size blob pos endian)}
and @code{(get-sint size blob pos endian)} in @code{binary.io}
module (@pxref{Binary I/O}), except that
@code{blob-uint-ref}/@code{blob-sint-ref} only accept u8vector
as @var{blob}.
@c JP
@var{size}オクテットからなる符号なし/符号つき整数を、@var{blob}の@var{pos}
オクテット目から取り出します。

これはそれぞれ、@code{binary.io}モジュールを使った
@code{(get-uint size blob pos endian)}および
@code{(get-sint size blob pos endian)}のラッパーです
(@ref{Binary I/O})。
ただし、@code{blob-uint-ref}/@code{blob-sint-ref}は
@var{blob}としてu8vectorしか受け付けません。
@c COMMON
@end defun

@defun blob-uint-set! size endian blob pos val
@defunx blob-sint-set! size endian blob pos val
[SRFI-74]
@c MOD srfi.74
@c EN
Store an unsigned or signed integer @var{val} of @var{size} octets
into @var{blob} starting at the position of @var{pos}, respectively.

These are wrappers of @code{(put-uint! size blob pos val endian)}
and @code{(put-sint! size blob pos val endian)} in @code{binary.io}
module (@pxref{Binary I/O}), except that
@code{blob-uint-set!}/@code{blob-sint-set!} only accept u8vector
as @var{blob}.
@c JP
@var{size}オクテットからなる符号なし/符号つき整数@var{val}を、
@var{blob}の@var{pos}オクテット目から格納します。

これはそれぞれ、@code{binary.io}モジュールを使った
@code{(put-uint! size blob pos val endian)}および
@code{(put-sint! size blob pos val endian)}のラッパーです
(@ref{Binary I/O})。
ただし、@code{blob-uint-set!}/@code{blob-sint-set!}は
@var{blob}としてu8vectorしか受け付けません。
@c COMMON
@end defun

@defun blob-u8-ref blob pos
@defunx blob-u8-set! blob pos val
@defunx blob-s8-ref blob pos
@defunx blob-s8-set! blob pos val
[SRFI-74]
@c MOD srfi.74
@c EN
Get/set an unsigned or signed integer as a octet at @var{pos}
from/to @var{blob}.

These are wrappers of @code{get-u8}, @code{put-u8!},
@code{get-s8} and @code{put-s8!} in @code{binary.io}, respectively.
@c JP
1オクテットの符号つき/符号なし整数を@var{blob}の@var{pos}位置から読み出し/に書き込みます。

これらはそれぞれ、@code{binary.io}モジュールの
@code{get-u8}、@code{put-u8!}、@code{get-s8}および@code{put-s8!}と同じです。
@c COMMON
@end defun

@defun blob-u16-ref endian blob pos
@defunx blob-u16-set! endian blob pos val
@defunx blob-s16-ref endian blob pos
@defunx blob-s16-set! endian blob pos val
@defunx blob-u32-ref endian blob pos
@defunx blob-u32-set! endian blob pos val
@defunx blob-s32-ref endian blob pos
@defunx blob-s32-set! endian blob pos val
@defunx blob-u64-ref endian blob pos
@defunx blob-u64-set! endian blob pos val
@defunx blob-s64-ref endian blob pos
@defunx blob-s64-set! endian blob pos val
[SRFI-74]
@c MOD srfi.74
@c EN
Get/set an unsigned or signed integer of the indicated length
at @var{pos} from/to @var{blob}, using the specified @var{endian}.

These are wrappers of corresponding @code{get-XX} and @code{put-XX!}
in @code{binary.io}; note that the argument orders differ, though.
@c JP
それぞれのサイズの符号つき/符号なし整数を
@var{blob}の@var{pos}位置から@var{endian}のバイトオーダで読み出し/に書き込みます。

これらはそれぞれ、@code{binary.io}モジュールの
@code{get-XX}および@code{put-XX!}手続きのラッパーです。
引数順序が異なることに注意してください。
@c COMMON
@end defun

@defun blob-u16-native-ref blob pos
@defunx blob-u16-native-set! blob pos val
@defunx blob-s16-native-ref blob pos
@defunx blob-s16-native-set! blob pos val
@defunx blob-u32-native-ref blob pos
@defunx blob-u32-native-set! blob pos val
@defunx blob-s32-native-ref blob pos
@defunx blob-s32-native-set! blob pos val
@defunx blob-u64-native-ref blob pos
@defunx blob-u64-native-set! blob pos val
@defunx blob-s64-native-ref blob pos
@defunx blob-s64-native-set! blob pos val
[SRFI-74]
@c MOD srfi.74
@c EN
Get/set an unsigned or signed integer of the indicated length
at @var{pos} from/to @var{blob}, using the native endianness.

These are wrappers of corresponding @code{get-XX} and @code{put-XX!}
in @code{binary.io}; note that the argument orders differ, though.

Note: SRFI-74 only requires these procedures to work with alined @var{pos},
which is the multiple of the size of the integer in octets.
Gauche doesn't have such restriction, but keep this in mind when
you're writing a portable code.
@c JP
それぞれのサイズの符号つき/符号なし整数を
@var{blob}の@var{pos}位置からネイティブバイトオーダで読み出し/に書き込みます。

これらはそれぞれ、@code{binary.io}モジュールの
@code{get-XX}および@code{put-XX!}手続きのラッパーです。
引数順序が異なることに注意してください。

註: SRFI-74は、これらの手続きは@var{pos}がアラインされている場合、
すなわち扱う整数のオクテットでの大きさの整数倍のときだけ動作すれば良いとしています。
Gaucheではそういう制約はありませんが、ポータブルなコードを書く場合は気をつけて下さい。
@c COMMON
@end defun

@defun blob=? blob1 blob2
[SRFI-74]
@c MOD srfi.74
@c EN
This is the same as @code{u8vector=?} in @code{gauche.uvector}.
@c JP
これは@code{gauche.uvector}の@code{u8vector=?}と同じです。
@c COMMON
@end defun

@defun blob-copy! src sstart target tstart n
[SRFI-74]
@c MOD srfi.74
@c EN
Copy @var{n} octets from the source blob @var{src} starting from @var{sstart}
into the target blob @var{target} starting from @var{tstart}.

Note that the order of arguments differs from other @code{*-copy!}
procedures (e.g. R7RS's @code{string-copy!} and @code{vector-copy!},
and @code{gauche.uvector}'s @code{u8vector-copy!})), which have the
following signature: @code{(*-copy! target tstart src sstart send)}
@c JP
blobである@var{src}の@var{ssatrt}から@var{n}オクテットを、
@var{target} blobの@var{tstart}からの位置にコピーします。

引数の順序が他の@code{*-copy!}手続きと異なっているのに注意してください
(R7RSの@code{string-copy!}、@code{vector-copy!}、および@code{gauche.uvector}の
@code{u8vector-copy!}等は、@code{(*-copy! target tstart src sstart send)}
という順序で引数を取ります。)
@c COMMON
@end defun

@defun blob-copy blob
[SRFI-74]
@c MOD srfi.74
@c EN
Returns a fresh copy of @var{blob}.  The same as @code{u8vector-copy}
in @code{gauche.uvector}.
@c JP
@var{blob}の新たなコピーを返します。
@code{gauche.uvecto}の@code{u8vector-copy}と同じです。
@c COMMON
@end defun

@defun blob->u8-list blob
@defunx u8-list->blob list
[SRFI-74]
@c MOD srfi.74
@c EN
Wrappers of @code{u8vector->list} and @code{list->u8vector}, except
those don't take optional start/end arguments.
@c JP
@code{u8vector->list}および@code{list->u8vector}のラッパーです。
ただし、省略可能なstart/end引数は取りません。
@c COMMON
@end defun

@defun blob->uint-list size endian blob
@defunx blob->sint-list size endian blob
[SRFI-74]
@c MOD srfi.74
@c EN
Read a sequence of unsigned or signed integers of @var{size} octets from
@var{blob} with @var{endian}, and returns them as a list.
@c JP
それぞれ@var{size}オクテットからなる、バイトオーダー@var{endian}の符号つき/符号なし
整数を連続して@var{blob}から読み出し、リストにして返します。
@c COMMON

@example
(blob->uint-list 3 (endianness big) '#u8(0 0 1 0 0 2 0 0 3))
  @result{} (1 2 3)
@end example
@end defun

@defun uint-list->blob size endian list
@defunx sint-list->blob size endian list
[SRFI-74]
@c MOD srfi.74
@c EN
Convert a @var{list} of unsigned or signed integers to a blob.
The resulting blob has @code{(* size (length list))} octets.
Each integer occupies @var{size} octets.
@c JP
符号なし/符号つき整数のリスト@var{list}をblobにして返します。
作られるblobの大きさは@code{(* size (length list))}オクテットで、
sそれぞれの整数が@var{size}オクテットを占めます。
@c COMMON

@example
(uint-list->blob 3 (endianness little) '(1 2 3))
  @result{} #u8(1 0 0 2 0 0 3 0 0)
@end example
@end defun

@c ----------------------------------------------------------------------
@node Lightweight testing, Type-restricted numerical functions, Octet-addressed binary blocks, Library modules - SRFIs
@section @code{srfi.78} - Lightweight testing
@c NODE 軽量なテスト, @code{srfi.78} - 軽量なテスト

@deftp {Module} srfi.78
@mdindex srfi.78
@c EN
This srfi defines @code{check} and @code{check-ec} macro, along
with a few helper procedures, to write tests.  Especially,
@code{check-ec} uses the same comprehension style as SRFI-42
to run test expressions with various combinations of input easily.
@c JP
このsrfiは、テストを書くためのマクロ@code{check}と@code{check-ec}、
およびいくつかの補助手続きを定義します。
特に、@code{check-ec}はSRFI-42スタイルの内包表記で
パラメータを様々に変えてテストしたい式を評価することができます。
@c COMMON

@c EN
We implemented this module to work with @code{gauche.test}
(@pxref{Unit testing}).
Specifically,
if the check macros are invoked while @code{gauche.test} is active
(that is, between @code{test-start} and @code{test-end}), the check
macros are simply a wrapper of Gauche's @code{test} macro; the results
are tracked and reported by @code{gauche.test}.
@c JP
Gaucheでは、このモジュールは@code{gauche.test}とうまく協働するようになっています
(@ref{Unit testing}参照)。
@code{gauche.test}がアクティブ (つまり@code{test-start}と@code{test-end}の間)に
checkマクロが呼ばれた場合、それは@code{gauche.test}の@code{test}マクロの
ラッパーとなり、テストの結果は@code{gauche.test}側でまとめられて報告されます。
@c COMMON

@c EN
If this module is used without @code{gauche.test}, however, it works as
specified by the srfi, including reporting.  So, a tests using this srfi
can be run in both ways---if it is loaded by itself, it runs as vanilla SRFI-78,
and if it is included in a test file that uses @code{gacuhe.test}, it runs
as a part of @code{gauche.test}.
@c JP
このモジュールが@code{gauche.test}と一緒ではなく、単独で使われた場合は、
結果報告も含めsrfiで述べられている通りに動きます。つまり、このsrfiで書かれた
テストは2通りの方法で実行できるということです。それ単独でロードされた場合は
素のSRFI-78として、そして@code{gauche.test}を使うテストファイルからincludeされた
場合は@code{gauche.test}の一部として。
@c COMMON
@end deftp

@defmac check expr => expected
@defmacx check expr (=> equal) expected
[SRFI-78]
@c MOD srfi.78
@c EN
Evaluate @var{expected} and @var{equal}, then evaluate @var{expr} and
compare the results of @var{expected} and @var{expr} using @var{equal}.
In the first form, @code{equal?} is used as @var{equal}.
@c JP
@var{expected}と@var{equal}を評価し、次に@var{expr}を評価してその結果を
@var{expected}の結果と@var{equal}を使って比べます。
最初の形式では、@var{equal}として@code{equal?}が使われます。
@c COMMON
@end defmac

@defmac check-ec qualifier @dots{} expr => expected (argument @dots{})
@defmacx check-ec qualifier @dots{} expr (=> equal) expected (argument @dots{})
@defmacx check-ec qualifier @dots{} expr => expected
@defmacx check-ec qualifier @dots{} expr (=> equal) expected
[SRFI-78]
@c MOD srfi.78
@c EN
Evaluates @var{expr}, @var{equal} and @var{expected} repeatedly
in the environment where the @var{qualifier}s bind variables,
and each time the results of @var{expr} and @var{equal} are
compared with @var{equal}.  If the results don't agree,
the failure is recorded with the given @var{argument} @dots{}, which can
be useful to diagnose which combination of bindings the test failed on.
Single failure stops the iteration.  If the results of @var{expr} and
@var{expected} agrees on all the iterations, the entire @code{check-ec}
is regarded as success.
@c JP
@var{qualifier}で指定される変数束縛の全ての組み合わせの下で、
@var{expr}、@var{equal}、@var{expected}を繰り返し評価し、
その度に@var{expr}と@var{expected}を@var{equal}で比較します。
もし異なっていれば、それが失敗として記録され、@code{check-ec}全体が失敗として
終了します。全ての組み合わせにおいて@var{expr}と@var{expected}の結果が一致すれば、
@code{check-ec}全体が成功とみなされます。
@c COMMON

@c EN
The way @var{qualifier}s work is the same as SRFI-42.
@xref{Eager comprehensions}, for the details.
@c JP
@var{qualifier}の指定方法はSRFI-42に準じます。
詳しくは@ref{Eager comprehensions}を参照してください。
@c COMMON

@c EN
The following example tests Fermat numbers (2^2^n + 1) are primes.
It fails since F_5 is a composite.
@c JP
次のテストは、フェルマー数 (2^2^n + 1) が素数かどうかを順に調べています。
F_5は合成数なのでテストは失敗します。
@c COMMON

@example
(use math.prime)
(check-ec (: n 6)
          (:let fn (+ (expt 2 (expt 2 n)) 1))
          (bpsw-prime? fn)
          => #t (n))
 @result{}
 @r{prints} Checking (bpsw-prime? fn), expecting #t => ERROR: got #f, with n: 5
@end example

@c EN
When combined with @code{data.random}, @code{check-ec} can be used
for property testing.
@c JP
@code{data.random}と組み合わせると、@code{check-ec}はプロパティテストにも
使えます。
@c COMMON

@example
(use data.random)
(check-ec (:parallel (: n 100)   ; try 100 times
                     (:let xs (list-of (fixnums$))))  ; list of random fixnums
          (reverse (reverse xs)) => xs)  ; reverse . reverse == identity
@end example

@c EN
The entire @code{check-ec} form is treated as one check for the sake of
reporting.
@c JP
レポートの観点からは、@code{check-ec}全体がひとつのチェックとして扱われます。
@c COMMON
@end defmac

@defun check-report
[SRFI-78]
@c MOD srfi.78
@c EN
If this module is used stand-alone, prints the summary of test results
to the current output port.

If this module is running inside @code{gauche.test}, this does nothing.
Reporting is done by @code{gauche.test}.
@c JP
このモジュールが単独で使われた場合、現在の出力ポートにこれまでのテスト結果のまとめを
出力します。

このモジュールが@code{gauche.test}と一緒に使われた場合は何もしません。
テスト結果報告は@code{gauche.test}によって行われます。
@c COMMON
@end defun

@defun check-set-mode! mode
[SRFI-78]
@c MOD srfi.78
@c EN
Sets how the test progress and result will be reported.  This only has
an effect when check is run without @code{gauche.test}.
@c JP
テストの進行と結果をどう報告するかを指定します。これは@code{gauche.test}と一緒に
使われた時には意味を持ちません。
@c COMMON

@c EN
Valid @var{mode} is one of the following symbols:
@c JP
@var{mode}には次のシンボルのいずれかを指定します。
@c COMMON
@table @code
@item off
@c EN
Do not report the result at all, even from @code{(check-report)}.
@c JP
@code{(check-report)}も含め、結果は一切報告しません。
@c COMMON
@item summary
@c EN
Report the summary of the results when @code{(chec-report)} is called.
@c JP
@code{(chec-report)}が呼ばれた時にまとめを報告するだけです。
@c COMMON
@item report-failed
@c EN
In addition to @code{summary}, report any failed checks as they occur.
@c JP
@code{summary}の動作に加え、チェックが失敗した場合にその都度報告します。
@c COMMON
@item report
@c EN
In addition to @code{summary}, report each result of check as they occur.
@c JP
@code{summary}の動作に加え、チェック毎にその成功失敗を報告します。
@c COMMON
@end table

@c EN
The default is @code{report}.
@c JP
デフォルトは@code{report}です。
@c COMMON
@end defun

@defun check-reset!
[SRFI-78]
@c MOD srfi.78
@c EN
Clears the internal state to keep track of number of performed checks and
failed checks, etc.  This doesn't affect @code{gauche.test} bookkeeping.
@c JP
内部のテスト結果記録をクリアします。@code{gauche.test}の結果記録には影響を及ぼしません。
@c COMMON
@end defun

@defun check-passed? expected-total-count
[SRFI-78]
@c MOD srfi.78
@c EN
This can be used to programatically query whether the expected number
of tests are passed since the last @code{check-reset!} or the beginning.
The @var{expected-total-count} must be a number, and it returns @code{#t}
iff the internal count of passed test matches it and there is no failed checks.

This works even if checks are run with @code{gauche.test}.
However, only the tests using @code{check} and @code{check-ec} are counted.
@c JP
これはプログラム内から、最後の@code{check-reset!}もしくはプログラム開始以降に
期待した数のテストが成功したかどうかを調べるのに使えます。
@var{expected-total-count}には期待される成功したテストの数を渡します。
テスト失敗がなく、成功したテストの数が@var{expected-total-count}に一致すれば
@code{#t}が、そうでなければ@code{#f}が返されます。

これは@code{gauche.test}と一緒に使った場合でも有効です。ただし、
カウントされるのは@code{check}と@code{check-ec}の結果のみです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Type-restricted numerical functions, Accessing environment variables, Lightweight testing, Library modules - SRFIs
@section @code{srfi.94} - Type-restricted numerical functions
@c NODE 型を制限した数値関数, @code{srfi.94} - 型を制限した数値関数

@deftp {Module} srfi.94
@mdindex srfi.94
@c EN
This module provides arithmetic functions specialized for reals
and exact integers.  Similar to @code{scheme.fixnum} (@pxref{R7RS fixnum})
and @code{scheme.flonum} (@pxref{R7RS flonum}) in a sense of restricting
types of range and domains, but this srfi procedures cover wider range
(e.g. @code{real-*} procedures can accept all real numbers include
exact integers, and @code{integer-*} procedures can accept both fixnums
and bignums).
@c JP
このモジュールは実数および正確な整数に特化した数値演算関数を提供します。
定義域や値域の型を制約するという意味では
@code{scheme.fixnum} (@ref{R7RS fixnum}参照) や
@code{scheme.flonum} ((@ref{R7RS flonum})参照) と似ていますが、
このSRFIの関数はそれらのモジュールよりは広い範囲をカバーします
(例えば@code{real-*}手続きは正確な整数を含めた全ての実数を
対象としますし、@code{integer-*}手続きはfixnumだけでなくbignumも
扱えます)。
@c COMMON

@c EN
This module is provided mostly for the completeness.  Generally useful
procedures are already built-in, so you don't need to use this
module to use them.  Furthermore, some SRFI-94 procedures have the
same name of Gauche's built-in but behave slightly differently, so
just importing everything from @code{srfi.94} may cause unexpected effect.
If you need certain srfi-94 specific procedures, we recommend you to import
them selectively.
@c JP
このモジュール自体は完全性のために用意してあります。
一般的に有用と思われる関数については組み込みになっているので、
わざわざこのモジュールをuseする必要はありません。
さらに、SRFI-94の手続きのいくつかはGaucheの組み込み手続きと同じ名前を
持ちながら振る舞いが多少異なったりするので、
@code{srfi.94}をまるごとインポートすると思いがけない副作用があるかもしれません。
特定の、SRFI-94特有の手続きを使いたい場合は、それに絞ってインポートすることを
お勧めします。
@c COMMON

@c EN
The following procedures are built-in.  @xref{Arithmetics} for the details.
@c JP
以下の手続きは組み込みになっています。詳しくは@ref{Arithmetics}を参照してください。
@c COMMON
@example
real-exp          real-tan          atan              make-rectangular
real-ln           real-asin         real-sqrt         make-polar
real-sin          real-acos         integer-expt
real-cos          real-atan         real-expt
@end example

@c EN
The following procedures are redefined in this module, shadowing
Gauche's built-in procedures.   See the description
of each entry for the difference.
@c JP
以下の手続きはこのモジュールで定義され、インポートすると
組み込み手続きをシャドウします。違いについてはそれぞれの
エントリの記述を参照してください。
@c COMMON
@example
quotient     modulo       remainder    mod         abs
@end example
@end deftp

@defun real-log base x
[SRFI-94]
@c MOD srfi.94
@c EN
The arguments must be nonnegative reals.  Returns logarithm of @var{x}
with base @var{base}, computed as
@code{(/ (real-ln x) (real-ln base))}.

Note that R7RS's @code{log} takes @var{x} first, then optional @var{base}.
Gauche doesn't provide this procedure as built-in to avoid confusion.
@c JP
引数は非負の実数でなければなりません。
@var{base}を底とする@var{x}の対数を@code{(/ (real-ln x) (real-ln base))}
で計算して返します。

R7RSの@code{log}は@var{x}を最初に取り、
省略可能な@var{base}で底を指定することに注意してください。
Gaucheがこの手続きを組み込みとして提供していないのは、
引数順の混乱を避けるためです。
@c COMMON
@end defun

@defun integer-sqrt n
[SRFI-94]
@c MOD srfi.94
@c EN
This is the same as @code{exact-integer-sqrt} (@pxref{Arithmetics}).
@c JP
これは@code{exact-integer-sqrt}と同じです
(@ref{Arithmetics}参照)。
@c COMMON
@end defun

@defun integer-log base k
[SRFI-94]
@c MOD srfi.94
@c EN
Both arguments must be exact integers, and @var{base} must be
positive, while @var{x} must be nonnegative.

Returns a maximum exact integer @var{n} such that @code{(<= (expt base n) k)}.

The order of arguments is the same as @code{real-log}---not @code{log}.
@c JP
引数は正確な整数でなければならず、@var{base}は正数、
@var{x}は非負でなければなりません。

@code{(<= (expt base n) k)}となるような最大の正確な整数@var{n}を返します。

引数の順序は@code{real-log}と同じ、すなわち@code{log}とは異なります。
@c COMMON

@example
(integer-log 2 1500) @result{} 10
@end example
@end defun

@defun abs x
[SRFI-94]
@c MOD srfi.94
@c EN
While Gauche's built-in @code{abs} can take a non-real number
(in which case, it acts like @code{magnitude}), this version
throws an error.
@c JP
Gauche組み込みの@code{abs}は実数でない複素数を取ることができて、
その場合は@code{magnitude}のように振る舞いますが、
この手続きはエラーを投げます。
@c COMMON
@end defun

@defun quo n d
@defunx mod n d
@defunx rem n d
[SRFI-94]
@c MOD srfi.94
@c EN
Real version of @code{quotient}, @code{modulo}, and @code{remainder}
(@pxref{Arithmetics}).

Returns quotient, modulo, and remainder of @var{n} divided by @var{d}.
Arguments doesn't need to be integers.  If both are exact, the result
is exact.
@c JP
@code{quotient}、@code{modulo}、@code{remainder}の実数への拡張版です。

@var{n}を@var{d}で割った時の商および余りを返します。
引数は整数である必要はありません。両方とも正確数であれば結果も正確数となります。
@c COMMON

@c EN
@code{quo} returns @code{(truncate (/ n d))}.
@code{rem} returns @code{(- n (* d (quo n d)))}.
@code{mod} returns @code{(- n (* d (floor (/ n d))))}.
@c JP
@code{quo}は@code{(truncate (/ n d))}を、
@code{rem}は@code{(- n (* d (quo n d)))}を、
そして@code{mod}は@code{(- n (* d (floor (/ n d))))}を返します。
@c COMMON

@c EN
Note: R6RS defined different divison operators, @code{div}, @code{mod},
@code{div0}, and @code{mod0}
(@pxref{Arithmetics}).
They can take non-integer arguments, but unfortunately, they behave
differently from SRFI-94.  SRFI-94's @code{quo} behaves the same as
R6RS's @code{div0}, and SRFI-94's @code{rem} behaves the same as
R6RS's @code{mod0}.
@c JP
註: R6RSは異なる除算オペレータ、@code{div}、@code{mod}、
@code{div0}、および@code{mod0}を定義しました(@ref{Arithmetics}参照)。
これらも非整数を取ることができますが、残念なことに
SRFI-94とは振る舞いが異なります。SRFI-94の@code{quo}は
R6RSの@code{div0}と、SRFI-94の@code{rem}は
R6RSの@code{mod0}と、それぞれ同じふるまいです。
@c COMMON

@example
(quo 2/3 1/5)    @result{} 3
(mod 2/3 1/5)    @result{} 1/15
(rem 2/3 1/5)    @result{} 1/15

(quo 2/3 -1/5)   @result{} -3
(mod 2/3 -1/5)   @result{} -2/15
(rem 2/3 -1/5)   @result{} 1/15

(quo -2/3 1/5)   @result{} -3
(mod -2/3 1/5)   @result{} 2/15
(rem -2/3 1/5)   @result{} -1/15

(quo -2/3 -1/5)  @result{} 3
(mod -2/3 -1/5)  @result{} -1/15
(rem -2/3 -1/5)  @result{} -1/15

@c EN
;; For comparison- R6RS procedures
@c JP
;; 比較のため: R6RS手続き
@c COMMON
(use gauche.base)
(div 2/3 1/5)    @result{} 3
(mod 2/3 1/5)    @result{} 1/15
(div0 2/3 1/5)   @result{} 3
(mod0 2/3 1/5)   @result{} 1/15

(div 2/3 -1/5)   @result{} -3
(mod 2/3 -1/5)   @result{} 1/15
(div0 2/3 -1/5)  @result{} -3
(mod0 2/3 -1/5)  @result{} 1/15

(div -2/3 1/5)   @result{} -4
(mod -2/3 1/5)   @result{} 2/15
(div0 -2/3 1/5)  @result{} -3
(mod0 -2/3 1/5)  @result{} -1/15

(div -2/3 -1/5)  @result{} 4
(mod -2/3 -1/5)  @result{} 2/15
(div0 -2/3 -1/5) @result{} 3
(mod0 -2/3 -1/5) @result{} -1/15
@end example
@end defun

@defun quotient n d
@defunx modulo n d
@defunx remainder n d
[SRFI-94]
@c MOD srfi.94
@c EN
SRFI-94 version of these procedures throws an error if the arguments
are not exact integers.  Otherwise they behave the same
as built-in (@pxref{Arithmetics}).
@c JP
SRFI-94のバージョンは、引数が正確な整数でなければエラーを投げます。
それ以外は組み込みと同じように振る舞います
(@ref{Arithmetics}参照)。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Accessing environment variables, Purely functional random-access pairs and lists, Type-restricted numerical functions, Library modules - SRFIs
@section @code{srfi.98} - Accessing environment variables
@c NODE 環境変数へのアクセス, @code{srfi.98} - 環境変数へのアクセス

@deftp {Module} srfi.98
@mdindex srfi.98
@c EN
This srfi defines a portable way to access the underlying system's
environment variables.  Gauche supports such procedures built-in
(@pxref{Environment inquiry}),
but portable programs may want to use srfi API instead.
@c JP
このsrfiはシステムの環境変数にアクセスするポータブルな方法を定義しています。
Gaucheは組み込みで環境変数にアクセスする手続きを持っていますが
(@ref{Environment inquiry}参照)、
ポータブルなコードを書くにはこちらのAPIを使うのが良いでしょう。
@c COMMON
@end deftp

@defun get-environment-variable name
[SRFI-98]
@c MOD srfi.98
@c EN
Returns a string value of an environment variable named by a string @var{name}.
If the named environment variable doesn't exist, @code{#f} is returned.

This is equivalent to @code{sys-getenv}.
@c JP
文字列@var{name}で指定される名前を持つ環境変数の値を文字列で返します。
そのような環境変数が存在しなければ、@code{#f}が返されます。

この手続きは@code{sys-getenv}と等価です。
@c COMMON
@example
(get-environment-variable "PATH")
  @result{} "/bin:/usr/sbin:/usr/bin"
@end example
@end defun

@defun get-environment-variables
[SRFI-98]
@c MOD srfi.98
@c EN
Returns an assoc list of the name and the value of each environment
variable.

This is equivalent to @code{sys-environ->alist} without
the optional argument.
@c JP
全ての環境変数の名前と値の連想リストを返します。

この手続きは、省略引数を取らない時の@code{sys-environ->alist}と等価です。
@c COMMON
@example
(get-environment-variables)
  @result{} (("PATH" . "/bin:/usr/sbin:/usr/bin")
        @dots{})
@end example
@end defun

@c ----------------------------------------------------------------------
@node Purely functional random-access pairs and lists, Basic socket interface, Accessing environment variables, Library modules - SRFIs
@section @code{srfi.101} - Purely functional random-access pairs and lists
@c NODE 純粋に関数的でランダムアクセス可能なペアとリスト, @code{srfi.101} - 純粋に関数的でランダムアクセス可能なペアとリスト

@deftp {Module} srfi.101
@mdindex srfi.101
@c EN
SRFI-101 has become a part of R7RS large.
@xref{R7RS random-access lists}.
@c JP
SRFI-101はR7RS largeに採り入れられました。
@ref{R7RS random-access lists}を参照してください。
@c COMMON

@c EN
Special treatment of @code{cond-expand}: The feature conditional
@code{cond-expand} implicitly makes the checked library loaded
if available.  That is, you can usually say
@code{(cond-expand (srfi-N <code>))} where @code{<code>} can assume
SRFI-N is already available, without saying @code{(use srfi.N)}.

However, @code{srfi.101} exports the names that conflicts with
standard primitive pair and list operators, and importing
it without prefix or renaming would surprise you.
To avoid confusion, we don't automatically use @code{srfi.101}
even if it is used as feature conditional.

The recommended way is to use @code{library} feature requirements,
and use @code{srfi.101} with your desired prefix, e.g.
@code{(cond-expand ((library srfi.101) (use srfi.101 :prefix ra:)))}.
@c JP
@code{cond-expand}の特別な扱いについて: @code{cond-expand}は
チェックした機能が使える場合には、必要なライブラリを暗黙にロードします。
つまり、@code{(cond-expand (srfi-N <code>))} とした場合、@code{srfi-N}が
サポートされていれば@code{<code>}の中で@code{(use srfi.N)}とする必要はありません。

しかし、@code{srfi-101}は組み込みの重要なリストやペア操作手続きと同じ名前の
手続きをたくさんエクスポートしているので、プレフィクスやリネーム無しで
インポートすると、びっくりするようなことになるでしょう。
混乱を避けるため、SRFI1-101に限っては、それが機能識別子として使われても
@code{srfi.101}は自動的にはインポートされません。

推奨の方法は、@code{library}指定を使い、明示的なプレフィクスつきで@code{srfi.101}を
useすることです。例えば：
@code{(cond-expand ((library srfi.101) (use srfi.101 :prefix ra:)))}。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node Basic socket interface, Portable runtime environment inquiry, Purely functional random-access pairs and lists, Library modules - SRFIs
@section @code{srfi.106} - Basic socket interface
@c NODE 基本的なソケットインタフェース, @code{srfi.106} - 基本的なソケットインタフェース

@deftp {Module} srfi.106
@mdindex srfi.106
@c EN
A portable basic socket interface.

Although comprehensive network API is provided by @code{gauche.net}
(@pxref{Networking}), it is Gauche-specific.  This srfi provides
a small subset of socket operations, but it offers a portable way
to create applications that needs simple networking.

Note that some procedures have the same name as the ones in @code{gauche.net},
but the interface may differ.

A socket object created by this srfi's API is an instance
of Gauche's @code{<socket>}, so it can be passed to the API
in @code{gauche.net} and vice versa.

The following procedures are exactly the same as defined in @code{gauche.net}.
@xref{Networking}, for the details.
@c JP
ポータブルなソケットインタフェースです。

Gaucheは@code{gauche.net}モジュールで包括的なネットワークAPIを提供しています
(@ref{Networking}参照)。しかしそれはGauche特有のものです。
このsrfiはソケット操作の小さなサブセットを提供し、
簡単なネットワーキングを必要とするアプリケーションをポータブルに書けるようにします。

@code{gauche.net}と同じ名前を持ち、インタフェースが異なる手続きがあることに注意してください。

このsrfiのAPIで作られるソケットオブジェクトはGaucheの@code{<socket>}オブジェクト
そのものなので、@code{gauche.net}のAPIに渡したり、またその逆も可能です。

以下にあげる手続きは@code{gauche.net}のものと全く同一です。
説明は@ref{Networking}を参照してください。
@c COMMON

@example
socket-accept        socket-shutdown       socket-close
socket-input-port    socket-output-port
@end example
@end deftp

@c EN
@subheading Socket object
@c JP
@subheading ソケットオブジェクト
@c COMMON

@defun make-client-socket node service :optional ai-family ai-socktype ai-flags ai-protocol
[SRFI-106]
@c MOD srfi.106
@c EN
Creates and returns a socket to
communicate with the node @var{node} and @var{service}.
If the socket type is connection-oriented (that is, @var{ai-socktype} is
@code{*sock-stream*}, which is the default),
the returned socket is already connected.
@c JP
ノード@var{node}のサービス@var{service}と通信するためのソケットを作って返します。
ソケットの型がコネクション指向なら(つまり、@var{ai-socktype}が
@code{*sock-stream*}なら、これはデフォルトですが)、
返されるソケットは既にコネクトされた状態になっています。
@c COMMON

@c EN
Both @var{node} and @var{service} must be strings.
The @var{node} argument is passed to @code{getaddrinfo(3)} to resolve
to the server IP address(es).
A service name solely consists of decimal digits is interpreted as
a port number.
@c JP
@var{node}と@var{service}は文字列でなければなりません。
@var{node}は@code{getaddrinfo(3)}に渡されてサーバのIPアドレスに解決されます。
@var{service}が数字のみで構成されていた場合はポート番号とみなされます。
@c COMMON

@c EN
The default value of optional arguments are as follows:
@code{*af-inet*} for @var{ai-family},
@code{*sock-stream*} for @var{ai-socktype},
@code{(socket-merge-flags *ai-v4mapped* *ai-addrconfig*)} for
@var{ai-flags}, and @code{*ipproto-ip*} for @var{ai-protocol}.
See below for valid flag values.
@c JP
省略可能引数のデフォルト値は次の通りです:
@var{ai-family}は@code{*af-inet*}、
@var{ai-socktype}は@code{*sock-stream*}、
@var{ai-flags}は@code{(socket-merge-flags *ai-v4mapped* *ai-addrconfig*)}、
そして@var{ai-protocol}は@code{*ipproto-ip*}。
有効なフラグの種類については下を参照してください。
@c COMMON

@c EN
This API differs from @code{make-client-socket} in @code{gauche.net}.
@c JP
@code{gauche.net}の@code{make-client-socket}とはAPIが異なることに注意してください。
@c COMMON

@example
(make-client-socket "127.0.0.1" "80")
 @result{} a <socket> connected to port 80 of localhost
@end example
@end defun

@defun make-server-socket service :optional ai-family ai-socktype ai-protocol
[SRFI-106]
@c MOD srfi.106
@c EN
Creates and returns a server socket that binds and listens at
the port specified by
@var{service}, which must be a string.  A service name solely consists
of decimal digits is interpreted as a port number.
@c JP
@var{service}で指定されるポートで待ち受けるサーバソケットを作って返します。
@var{service}は文字列でなければなりません。@var{service}が全て数字で構成されていた
場合はポート番号と解釈されます。
@c COMMON

@c EN
The default value of optional arguments are as follows:
@code{*af-inet*} for @var{ai-family},
@code{*sock-stream*} for @var{ai-socktype},
and @code{*ipproto-ip*} for @var{ai-protocol}.
See below for valid flag values.
@c JP
省略可能引数のデフォルト値は次の通りです:
@var{ai-family}は@code{*af-inet*}、
@var{ai-socktype}は@code{*sock-stream*}、
@var{ai-protocol}は@code{*ipproto-ip*}。
有効なフラグの種類については下を参照してください。
@c COMMON

@c EN
This API differs from @code{make-server-socket} in @code{gauche.net}.
@c JP
@code{gauche.net}の@code{make-server-socket}とはAPIが異なることに注意してください。
@c COMMON
@end defun

@defun socket? obj
[SRFI-106]
@c MOD srfi.106
@c EN
Equivalent to @code{(is-a? obj <socket>)}.
@c JP
@code{(is-a? obj <socket>)}と同じです。
@c COMMON
@end defun

@c EN
@subheading Communication
@c JP
@subheading 通信
@c COMMON

@defun socket-send socket u8vector :optional flags
[SRFI-106]
@c MOD srfi.106
@c EN
Almost same as @code{socket-send} in @code{gauche.net}, except that
this procedure only accepts a u8vector as the message.
(The one in @code{gauche.net} can take a string as well.)

Returns the number of octets that are actually sent.
@c JP
@code{gauche.net}の@code{socket-send}とほぼ同じですが、
@code{gauche.net}のものが文字列も引数に取ることができるのに対し、
こちらはu8vectorのみを受け付けます。

実際に送られたオクテット数を返します。
@c COMMON
@end defun

@defun socket-recv socket size :optional flags
[SRFI-106]
@c MOD srfi.106
@c EN
This is like @code{socket-recv} in @code{gauche.net}, except that
this procedure returns the received data in u8vector,
instead of a string.  If the peer has shut down the connection,
this procedure returns an empty u8vector, @code{#u8()}.

The @var{size} argument specifies the maximum size of the receiving
data.  The returned vector may be shorter if that much data is received.
@c JP
@code{gauche.net}の@code{socket-recv}に似ていますが、こちらは
文字列ではなくu8vectorを返します。もし通信の相手がコネクションを閉じていた場合は、
空のu8vector @code{#u8()}が返されます。

@var{size}引数は受信データの最大のサイズを指定します。
受信データがそれより小さい場合は返されるベクタもそれに合わせて短くなります。
@c COMMON
@end defun

@c EN
@subheading Flags
@c JP
@subheading フラグ
@c COMMON

@c EN
The srfi provides common names for constants of typical socket flags,
as well as macros that map symbolic name(s) to the flags.
@c JP
このsrfiでは、典型的なソケットフラグを表す定数と、
名前からフラグ値を求めるマクロも提供しています。
@c COMMON

@defun socket-merge-flags flag @dots{}
[SRFI-106]
@c MOD srfi.106
@c EN
Merge bitwise flags.  This is simply @code{logior} in Gauche.
@c JP
与えられた@var{flag} @dots{}をビット演算でマージします。
Gauche組み込みの@code{logior}と実質的に同じです。
@c COMMON
@end defun

@defun socket-purge-flags base-flag flag @dots{}
[SRFI-106]
@c MOD srfi.106
@c EN
Drop the bitwise flags in @var{base-flag} that are set
in @var{flag} @dots{}.
@c JP
@var{base-flag}のビットのうち、@var{flag} @dots{}で示されるビットを0にします。
@c COMMON
@end defun

@subsubheading Address family

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *af-inet*
@vindex *af-inet6*
@vindex *af-unspec*
@item @code{*af-inet*} @tab @code{AF_INET}
@item @code{*af-inet6*} @tab @code{AF_INET6}
@item @code{*af-unspec*} @tab @code{AF_UNSPEC}
@end multitable

@defmac address-family name
[SRFI-106]
@c MOD srfi.106
@c EN
@var{Name} can be either one of symbols
@code{inet}, @code{inet6}, or @code{unspec}, and
the macro expands into the value of @code{*af-inet*},
@code{*af-inet6*} or @code{*af-unspec*}, respectively.

If @var{name} is other object, an error is signaled.
@c JP
@var{name}がシンボル@code{inet}、@code{inet6}、@code{unspec}のいずれかであれば、
それぞれ@code{*af-inet*}、@code{*af-inet6*}、@code{*af-unspec*}の値へと展開されます。

@var{name}がそれ以外のオブジェクトならエラーが報告されます。
@c COMMON
@end defmac


@subsubheading Socket domain

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *sock-stream*
@vindex *sock-dgram*
@item @code{*sock-stream*} @tab @code{SOCK_STREAM}
@item @code{*sock-dgram*} @tab @code{SOCK_DGRAM}
@end multitable

@defmac socket-domain name
[SRFI-106]
@c MOD srfi.106
@c EN
@var{Name} can be either one of symbols
@code{stream} or @code{datagram}, and the macro
expands into the value of @code{*sock-stream*} and
@code{*sock-dgram*}, respectively.

If @var{name} is other object, an error is signaled.
@c JP
@var{name}がシンボル@code{stream}、@code{datagram}のいずれかであれば、
それぞれ@code{*sock-stream*}、@code{*sock-dgram*}の値へと展開されます。

@var{name}がそれ以外のオブジェクトならエラーが報告されます。
@c COMMON
@end defmac


@subsubheading Address info

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *ai-canonname*
@vindex *ai-numerichost*
@vindex *ai-v4mapped*
@vindex *ai-all*
@vindex *ai-addrconfig*
@item @code{*ai-canonname*} @tab @code{AI_CANONNAME}
@item @code{*ai-numerichost*} @tab @code{AI_NUMERICHOST}
@item @code{*ai-v4mapped*} @tab @code{AI_V4MAPPED}
@item @code{*ai-all*} @tab @code{AI_ALL}
@item @code{*ai-addrconfig*} @tab @code{AI_ADDRCONFIG}
@end multitable

@defmac address-info name @dots{}
[SRFI-106]
@c MOD srfi.106
@c EN
Maps combination of names @code{canoname}, @code{numerichost},
@code{v4mapped}, @code{all} and @code{addrconfig}
to the combination of corresponding flags.

An error is signaled if other symbols are passed.
(Note: @code{canoname} for @code{*ai-canonname*}).
@c JP
シンボル@code{canoname}、@code{numerichost}、
@code{v4mapped}、@code{all}、@code{addrconfig}の組み合わせを、
対応するビットフラグの組み合わせへと展開します。

他のシンボルが渡された場合はエラーが報告されます。
(註: @code{*ai-canonname*}に対応するのは@code{canoname}です)。
@c COMMON
@end defmac

@c EN
@subsubheading Protocol
@c JP
@subsubheading プロトコル
@c COMMON

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *ipproto-ip*
@vindex *ipproto-tcp*
@vindex *ipproto-udp*
@item @code{*ipproto-ip*} @tab @code{IPPROTO_IP}
@item @code{*ipproto-tcp*} @tab @code{IPPROTO_TCP}
@item @code{*ipproto-udp*} @tab @code{IPPROTO_UDP}
@end multitable

@defmac ip-protocol name
[SRFI-106]
@c MOD srfi.106
@c EN
Maps one of names @code{ip}, @code{tcp}, and @code{udp}
to the corresponding flag value.  An error is signaled
if other symbol is passed.
@c JP
シンボル@code{ip}、@code{tcp}、and @code{udp}を
それぞれ対応するフラグの値へと展開します。
他のシンボルが渡されたらエラーを報告します。
@c COMMON
@end defmac

@c EN
@subsubheading Message type
@c JP
@subsubheading メッセージタイプ
@c COMMON

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *msg-none*
@vindex *msg-peek*
@vindex *msg-oob*
@vindex *msg-waitall*
@item @code{*msg-none*} @tab 0
@item @code{*msg-peek*} @tab  @code{MSG_PEEK}
@item @code{*msg-oob*} @tab   @code{MSG_OOB}
@item @code{*msg-waitall*} @tab @code{MSG_WAITALL}
@end multitable

@defmac message-type name @dots{}
[SRFI-106]
@c MOD srfi.106
@c EN
Maps combination of names @code{none}, @code{peek},
@code{oob} and @code{wait-all}
to the combination of corresponding flags.

An error is signaled if other symbols are passed.
(Note: @code{wait-all} for @code{*msg-waitall*}).
@c JP
シンボル@code{none}、@code{peek}、
@code{oob}、@code{wait-all}の組み合わせを、
対応するビットフラグの組み合わせへと展開します。

他のシンボルが渡された場合はエラーが報告されます。
(註: @code{*msg-waitall*}に対応するのは@code{wait-all}です)。
@c COMMON
@end defmac

@c EN
@subsubheading Shutdown method
@c JP
@subsubheading シャットダウン
@c COMMON

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *shut-rd*
@vindex *shut-wr*
@vindex *shut-rdwr*
@item @code{*shut-rd*} @tab @code{SHUT_RD}
@item @code{*shut-wr*} @tab @code{SHUT_WR}
@item @code{*shut-rdwr*} @tab @code{SHUT_RDWR}
@end multitable

@defmac shutdown-method name @dots{}
[SRFI-106]
@c MOD srfi.106
@c EN
Maps combination of names @code{read} and @code{write}
to the combination of corresponding flags.

An error is signaled if other symbols are passed.
@c JP
シンボル@code{code}と@code{write}の組み合わせを対応するビットマスクの値へと展開します。

他のシンボルが渡された場合はエラーが報告されます。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node Portable runtime environment inquiry, Comparators, Basic socket interface, Library modules - SRFIs
@section @code{srfi.112} - Environment inquiry
@c NODE ポータブルな実行環境の問い合わせ, @code{srfi.112} - 実行環境の問い合わせ

@deftp {Module} srfi.112
@mdindex srfi.112
@c EN
This srfi provides a portable way to obtain runtime information.
@c JP
このsrfiは実行時の情報を問い合わせるポータブルな方法を提供します。
@c COMMON
@end deftp

@defun implementation-name
[SRFI-112]
@c MOD srfi.112
@c EN
The name of the implementation.
Returns a string @code{"Gauche"}.
@c JP
実装の名前。文字列@code{"Gauche"}が返ります。
@c COMMON
@end defun

@defun implementation-version
[SRFI-112]
@c MOD srfi.112
@c EN
Returns a string of Gauche's version.  The same as @code{gauche-version}
(@pxref{Environment inquiry}).
@c JP
Gaucheのバージョンを示す文字列が返ります。
@code{gauche-version}と同じです (@ref{Environment inquiry}参照)。
@c COMMON
@end defun

@defun cpu-architecture
[SRFI-112]
@c MOD srfi.112
@c EN
Returns a string of CPU architecture info, such as @code{"x86_64"}.
Same as the @code{machine} field of the return value of @code{sys-uname}
(@pxref{System inquiry}).
@c JP
CPUアーキテクチャの情報(@code{"x86_64"}など)を文字列で返します。
@code{sys-uname}の@code{machine}フィールドと同じです(@ref{System inquiry}参照)。
@c COMMON
@end defun

@defun machine-name
[SRFI-112]
@c MOD srfi.112
@c EN
Returns the host name.  Same as the @code{nodename} field of
the return value of @code{sys-uname}.
(@pxref{System inquiry}).
@c JP
ホスト名を返します。@code{sys-uname}の@code{nodename}フィールドと同じです
(@ref{System inquiry}参照)。
@c COMMON
@end defun

@defun os-name
[SRFI-112]
@c MOD srfi.112
@c EN
Returns the OS name.  Same as the @code{sysname} field
of the return value of @code{sys-uname}.
@c JP
OSの名前を返します。@code{sys-uname}の@code{sysname}フィールドと同じです
(@ref{System inquiry}参照)。
@c COMMON
@end defun

@defun os-version
[SRFI-112]
@c MOD srfi.112
@c EN
Returns the OS version.  Same as the @code{release} field
of the return value of @code{sys-uname}.
@c JP
OSのバージョンを返します。@code{sys-uname}の@code{release}フィールドと同じです
(@ref{System inquiry}参照)。
@c COMMON
@end defun

@c EN
Here's an example of output.  It is likely to differ on your environment.
@c JP
出力の例を示します。あなたの実行環境では多分違った値になるでしょう。
@c COMMON

@example
gosh> (implementation-name)
"Gauche"
gosh> (implementation-version)
"0.9.5"
gosh> (cpu-architecture)
"x86_64"
gosh> (machine-name)
"scherzo"
gosh> (os-name)
"Linux"
gosh> (os-version)
"3.2.0-89-generic"
@end example


@c ----------------------------------------------------------------------
@node Comparators, Simple adjustable-size strings, Portable runtime environment inquiry, Library modules - SRFIs
@section @code{srfi.114} - Comparators
@c NODE 比較器, @code{srfi.114} - 比較器

@deftp {Module} srfi.114
@mdindex srfi.114
@c EN
This module is provided for the compatibility of code using SRFI-114.
The new code should use SRFI-128, which is fully built-in.
@c JP
このモジュールはSRFI-114を使っているコードとの互換性のために提供されています。
新規コードはSRFI-128を使ってください。そちらは組み込みになっています。
@c COMMON

@c EN
Note that SRFI-114's @code{make-comparator} has different interface from
built-in (SRFI-128) @code{make-comparator}.
If you simply say @code{(use srfi.114)} or @code{(import (srfi 114))},
it shadows the built-in one.  If you need to use some of SRFI-114
procedures, it's better to import them selectively.
@c JP
SRFI-114の@code{make-comparator}は組み込み(SRFI-128)の@code{make-comparator}
と異なるインタフェースを持つことに注意してください。
単に@code{(use srfi.114)}や@code{(import (srfi 114))}とすると、
組み込みの@code{make-comparator}がシャドウされます。
SRFI-114のいくつかの手続きだけを使いたいなら、それらを選択的にインポートするのが良いでしょう。
@c COMMON

@c EN
Note that comparators created with SRFI-114 procedures are the same
type as the ones created with SRFI-128 procedures and can be used
interchangebly.
@c JP
SRFI-114手続きで作られる比較器は、SRFI-128で作られる比較器と同じ型で、
互いにどちらの手続きにも渡すことができます。
@c COMMON

@c EN
The following procedures are built-in.  @xref{Basic comparators}, for
the detailed documentation.   Those are also exported from @code{srfi.114}
for the compatibility.
@c JP
以下の手続きは組み込みで提供されます。
説明は@ref{Basic comparators}を参照してください。
互換性のために、これらは@code{srfi.114}モジュールからもエクスポートされます。
@c COMMON

@table @asis
@c EN
@item Predicates
@c JP
@item 述語
@c COMMON
@code{comparator?},

@c EN
@item Standard comparators
@c JP
@item 標準比較器
@c COMMON
@code{boolean-comparator},
@code{char-comparator},
@code{char-ci-comparator},
@code{string-comparator},
@code{string-ci-comparator},
@code{symbol-comparator},
@code{exact-integer-comparator},
@code{integer-comparator},
@code{rational-comparator},
@code{real-comparator},
@code{complex-comparator},
@code{number-comparator},
@code{pair-comparator},
@code{list-comparator},
@code{vector-comparator},
@code{bytevector-comparator},
@code{uvector-comparator}

@c EN
@item The default comparator
@c JP
@item デフォルト比較器
@c COMMON
@code{default-comparator}

@c EN
@item Wrapped equality predicates
@c JP
@item 等価述語のラッパー
@c COMMON
@code{eq-comparator},
@code{eqv-comparator},
@code{equal-comparator}

@c EN
@item Accessors
@c JP
@item アクセサ
@c COMMON
@code{comparator-equality-predicate},
@code{comparator-comparison-procedure},
@code{comparator-hash-function}

@c EN
@item Primitive applicators
@c JP
@item 基本的適用手続き
@c COMMON
@code{comparator-test-type},
@code{comparator-check-type},
@code{comparator-compare},
@code{comparator-hash}

@c EN
@item Comparison predicates
@c JP
@item 比較手続き
@c COMMON
@code{=?},
@code{<?},
@code{<=?},
@code{>?},
@code{>=?}
@end table

@end deftp

@c EN
@subsubheading Basic comparator interface
@c JP
@subsubheading 比較器の基本的なインタフェース
@c COMMON

@defun make-comparator type-test equal compare hash :optional name
[SRFI-114+]
@c MOD srfi.114
@c EN
This is SRFI-114 style comparator constructor.  The optional @var{name}
argument is Gauche's extension.
@c JP
SRFI-114形式の比較器コンストラクタです。省略可能引数@var{name}はGaucheの拡張です。
@c COMMON

@c EN
This is the same as built-in @code{make-comparator/compare}.
@xref{Basic comparators}, for the details.
@c JP
この手続きは組み込みの@code{make-comparator/compare}と同じです。
詳しくは@ref{Basic comparators}を参照してください。
@c COMMON

@c EN
Do not confuse this with built-in (SRFI-128) @code{make-comparator};
if you @code{(use srfi.114)}, this one shadows the built-in one.
@c JP
組み込み (SRFI-128) の@code{make-comparator}と混同しないようにしてください。
単に@code{(use srfi.114)}とすると、組み込みのそれがSRFI-114でシャドウされます。
@c COMMON

@c EN
Note that a comparator works for both SRFI-114 and SRFI-128 procedures,
regardless of how it is constructed.
@c JP
比較器はどちらで作られたかにかかわらず、SRFI-114の手続きにもSRFI-128の手続きにも
渡すことができます。
@c COMMON
@end defun

@defun comparator-comparison-procedure? c
@defunx comparator-hash-function? c
[SRFI-114]
@c MOD srfi.114
@c EN
Returns true iff a comparator @var{c} can be used to order objects
or to hash them, respectively.  These are aliases of
built-in @code{comparator-ordered?} and @code{comparator-hashable?}.
@c JP
それぞれ、比較器@var{c}が順序付けに使える場合、ハッシュに使える場合に@code{#t}を
返す述語です。
これらはそれぞれ組み込みの@code{comparator-ordered?}及び
@code{comparator-hashable?}の別名です。
@c COMMON
@end defun

@defun comparator-type-test-procedure c
[SRFI-114]
@c MOD srfi.114
@c EN
Returns type test predicate of a comparator @var{c}.
This is an alias of built-in @code{comparator-type-test-predicate}.
@c JP
比較器@var{c}の型検査述語を返します。
これは組み込みの@code{comparator-type-test-predicate}の別名です。
@c COMMON
@end defun

@defun comparator-equal? c a b
[SRFI-114]
@c MOD srfi.114
@c EN
Checks equality of @var{a} and @var{b} using the equality predicate
of a comparator @var{c}.  This can be also written in @code{=?}, which
is built-in (@pxref{Comparator predicates and accessors}).
@c JP
比較器@var{c}の等価述語を使って@var{a}と@var{b}が等しいかどうか検査します。
組み込みの@code{=?}を使って同等の処理を書くことができます
(@ref{Comparator predicates and accessors})参照。
@c COMMON
@example
(=? c a b)
@end example
@end defun

@c EN
@subsubheading Auxiliary comparator constructors
@c JP
@subsubheading 追加の比較器コンストラクタ
@c COMMON

@defun make-inexact-real-comparator epsilon rounding nan-handling
[SRFI-114]
@c MOD srfi.114
Returns a comparator for inexact real numbers, taking into
account of errors and NaNs.

The basic idea is that we compare two finite real numbers
after rounding them to @var{epsilon} interval, which must be
a nonnegative real number.
(Note that it's not to compare two numbers ``close enough'', as often
being done to compare inexact numbers.  ``Close enough'' scheme
won't be transitive.)

The rounding mode is specified by the @var{rounding} argument.
It can be either one of the symbols @code{round}, @code{ceiling},
@code{floor} or @code{truncate}, or a procedure that takes
two arguments, a real number and an epsilon, and returns
the rounded result of the first argument according to the
given epsilon.

The @var{nan-handling} argument determines how to handle the
case to compare NaN and non-NaN numbers.  (If both are NaNs,
this comparator regards them as equal).  It can be either
one of the followings:
@table @asis
@item @code{min}
If it's a symbol @code{min}, NaN is compared as smaller than
all other real numbers, even than @code{-inf.0}.
@item @code{max}
If it's a symbol @code{min}, NaN is compared as greater than
all other real numbers, even than @code{+inf.0}.
@item @code{error}
If it's a symbol @code{error}, an error is signaled.
@item a procedure taking one argument
The procedure is invoked with the real number which is not NaN.
If it ever returns, it must return either 1, 0 or -1, for
it's used as the result of the comparison procedure of
the comparator.  However, since the procedure doesn't know
@emph{which} argument is non-NaN, it's hard to have consistent
semantics; the best bet is to throw a custom error.
@end table

@example
(define c (make-inexact-real-comparator 0.1 'round 'error))

(comparator-compare c 0.112 0.098) @result{} 0
(comparator-compare c 0.131 0.172) @result{} -1
@end example

Note: Rounding to the nearest epsilon interval would involve
scaling inexact numbers, and that may reveal small difference
between the actual number and its notation.  For example,
an inexact real number denoted as @code{0.15} is actually
slightly smaller than @code{15/100}, and rounding with epsilon
@code{0.1} would result @code{0.1}, not @code{0.2}.
@end defun

@defun make-car-comparator cmpr
@defunx make-cdr-comparator cmpr
[SRFI-114]
@c MOD srfi.114
@c EN
Returns comparators that accept pairs, and compare them with
their car or cdr by @var{cmpr}, respectively.

Using @code{make-key-comparator}, these cam be written as follows
(@pxref{Combining comparators}, for @code{make-key-comparator}).
@c JP
ペアを受け取り、その@code{car}のみまたは@code{cdr}のみを@var{cmpr}で
比較するような比較器を返します。

@code{make-key-comparator}を使えばこれらは以下の通りに書けます。
(@code{make-key-comparator}については@ref{Combining comparators}を参照)。
@c COMMON
@example
(define (make-car-comparator cmpr)
  (make-key-comparator cmpr pair? car))

(define (make-cdr-comparator cmpr)
  (make-key-comparator cmpr pair? cdr))
@end example
@end defun

@defun make-list-comparator element-comparator
@defunx make-vector-comparator element-comparator
@defunx make-bytevector-comparator element-comparator
[SRFI-114]
@c MOD srfi.114
Returns a new comparator that compares lists, vectors and
bytevectors element-wise using @var{element-comparator},
respectively.  These are more general versions of
@code{list-comparator}, @code{vector-comparator} and
@code{bytevector-comparator}, which use @code{default-comparator}
as @var{element-comparator}.

For a list comparator, it is an error to pass improper lists.

Note that comparing sequences of different lengths is slightly
different between lists and vector/bytevectors.  List comparator
uses ``dictionary'' order, so @code{(1 3)} comes after @code{(1 2 3)},
assuming elements are compared numerically.
For vectors and bytevectors, shorter one always precedes the other,
so @code{#(1 3)} comes before @code{#(1 2 3)}.
@end defun

@defun make-listwise-comparator type-test element-comparator empty? head tail
[SRFI-114]
@c MOD srfi.114
More general version of @code{make-list-comparator}.
Returns a comparator that compares structures which can be
traversed using three procedures, @var{empty?}, @var{head} and @var{tail}.
Each of those procedure receives a structure to be compared, and @var{empty?}
must return @code{#t} iff the structure is empty, @var{head}
must return the first element in the structure, and @var{tail}
must return the same type of structure containing all the elements
but the head.  The @var{type-test} predicate checks if the arguments
passed to the comparator to be a suitable structure.

That is, @code{make-list-comparator} can be written in
@code{make-listwise-comparator} as follows.
@example
(make-list-compartator element-comparator)
  @equiv{}
  (make-listwise-comparator list? element-comparator null? car cdr)
@end example

This can be used to compare list-like structures.  For example,
the following call returns a comparator that compares elements
of two lazy streams (@pxref{Stream library}).

@example
(make-listwise-comparator stream?
                          element-comparator
                          stream-null?
                          stream-car
                          stream-cdr)
@end example
@end defun

@defun make-vectorwise-comparator type-test element-comparator length ref
[SRFI-114]
@c MOD srfi.114
More general version of @code{make-vector-comparator}.
Returns a comparator that compares structures which can be
traversed using two procedures, @var{length} and @var{ref}.
The @var{length} procedure must return the number of elements in the
structure.  The @var{ref} procedure receives a structure and a nonnegative
exact integer index @var{k}, and must return @var{k}-th element
of the structure.

That is, the following equivalence holds:
@example
(make-vector-comparator element-comparator)
  @equiv{}
  (make-vectorwise-comparator vector? element-comparator
                              vector-length vector-ref)

(make-bytevector-comparator element-comparator)
  @equiv{}
  (make-vectorwise-comparator u8vector? element-comparator
                              u8vector-length u8vector-ref)
@end example
@end defun

@defun make-pair-comparator car-comparator cdr-comparator
[SRFI-114]
@c MOD srfi.114
Creates a comparator that compares pairs, with their cars
by @var{car-comparator} and their cdrs by @var{cdr-comparator}.
@end defun

@defun make-improper-list-comparator element-comparator
[SRFI-114]
@c MOD srfi.114
This may be understood as recursive pair comparator; if objects
to be compared are pairs, we recurse their cars then their cdrs.
If objects to be compared are not pairs, we use @var{element-comparator}
to compare them.
@end defun

@defun make-selecting-comparator comparator1 comparator2 @dots{}
[SRFI-114]
@c MOD srfi.114
This creates a comparator that works any one of the given comparators;
the objects to be compared are type-tested with each of the comparators
in order, and the first comparator that accepts all objects will be used.
@end defun

@defun make-refining-comparator comparator1 comparator2 @dots{}
[SRFI-114]
@c MOD srfi.114
This is similar to @code{make-selecting-comparator}, except that
if the first comparator that accepts given objects to compare finds
they are equal (or 0 by the comparison procedure), it tries other
comparators down the list, if any.
@end defun

@defun make-reverse-comparator comparator
[SRFI-114]
@c MOD srfi.114
Returns a comparator that just reverses the comparison order of
@var{comparator}.
@end defun

@defun make-debug-comparator comparator
[SRFI-114]
@c MOD srfi.114
@end defun

@subsubheading Comparison procedure constructors

@defun make-comparison< lt-pred
@defunx make-comparison> gt-pred
@defunx make-comparison<= le-pred
@defunx make-comparison>= ge-pred
@defunx make-comparison=/< eq-pred lt-pred
@defunx make-comparison=/> eq-pred gt-pred
[SRFI-114]
@c MOD srfi.114
Utility procedures to create a comparison procedure (the one returns
-1, 0, or 1) from the given predicate.  For example,
@code{make-comparison<} can be defined as follows:

@example
(define (make-comparison< pred)
  (^[a b] (cond [(pred a b) -1]
                [(pred b a) 1]
                [else 0])))
@end example
@end defun

@subsubheading Comparison syntax

@defmac if3 expr less equal greater
[SRFI-114]
@c MOD srfi.114
Three-way @code{if}: Evaluates @var{expr}, and then evaluates
either one of @var{less}, @var{equal}, or @var{greater},
depending on the value of @var{expr} is either less than zero,
equal to zero, or greater than zero, respectively.
@end defmac

@defmac if=? expr consequent :optional alternate
@defmacx if<? expr consequent :optional alternate
@defmacx if>? expr consequent :optional alternate
@defmacx if<=? expr consequent :optional alternate
@defmacx if>=? expr consequent :optional alternate
@defmacx if-not=? expr consequent :optional alternate
[SRFI-114]
@c MOD srfi.114
Conditional evaluation according to comparison expression @var{expr};
that is, @code{if@var{OP}?} evaluates @var{consequent} if
@code{(@var{OP} expr 0)} is true, otherwise it evaluates @var{alternate}
when provided.

@example
(if<? (compare 10 20) 'yes)      @result{} yes
(if>=? (compare 10 20) 'yes 'no) @result{} no
@end example
@end defmac

@subsubheading Comparison predicate constructors

@defun make=? comparator
@defunx make<? comparator
@defunx make>? comparator
@defunx make<=? comparator
@defunx make>=? comparator
[SRFI-114]
@c MOD srfi.114
@example
((make=? comparator) obj1 obj2 obj3 @dots{})
  @equiv{} (=? comparator obj1 obj2 obj3 @dots{})
@end example
@end defun

@subsubheading Interval comparison predicates


@defun in-open-interval? [comparator] obj1 obj2 obj3
@defunx in-closed-interval? [comparator] obj1 obj2 obj3
@defunx in-open-closed-interval? [comparator] obj1 obj2 obj3
@defunx in-closed-open-interval? [comparator] obj1 obj2 obj3
[SRFI-114]
@c MOD srfi.114
Check if @var{obj1}, @var{obj2} and @var{obj3} has the following
relationships:

@example
(and (op1 obj1 obj2) (op2 obj2 obj3))
@end example

Where each of @var{op1} and @var{op2} can be
@code{(make<? comparator)} (if that end is @emph{open}),
or @code{(make<=? comparator)} (if that end is @emph{closed}).

When @var{comparator} is omitted, the default comparator is used.

@example
(use srfi.42)
(list-ec (: x 0 5) (list x (in-closed-open-interval? 1 x 3)))
  @result{} ((0 #f) (1 #t) (2 #t) (3 #f) (4 #f))
@end example
@end defun

@subsubheading Min/max comparison procedures

@code{comparator-min} and @code{comparator-max} are the
same as @code{srfi.162}.  @xref{Comparator sublibrary}.


@c ----------------------------------------------------------------------
@node Simple adjustable-size strings, Timer APIs, Comparators, Library modules - SRFIs
@section @code{srfi.118} - Simple adjustable-size strings
@c NODE 簡単な可変長文字列, @code{srfi.118} - 簡単な可変長文字列

@deftp {Module} srfi.118
@mdindex srfi.118
@c EN
This SRFI defines two string mutating operations that can change
the length of the string: @code{string-append!} and @code{string-replace!}.

Note that, in Gauche, the body of strings is immutable; when you mutate
a string, Gauche creates a fresh new string body and just switch a pointer
in the original string to point the new string body.  So it is not a
problem to implement this SRFI in Gauche, but it also means you won't
get any performance benefit by using these operations.  Using immutable
counterparts (@code{string-append} and @code{string-replace}) gives
you the same performance.  (Be aware that the interface is slightly
different from the immutable versions.)

We provide this module only for the compatibility.  Gauche-specific
programs should stay away from this module.  Particularly, avoid
code like the example in SRFI-118 document (build a string by
@code{append!}-ing small chunks at a time)---they're quadratic on Gauche.
@c JP
このSRFIは、文字列の長さを変えるような破壊的変更を行う文字列操作ルーチンを
提供します。

Gaucheでは、文字列の本体は変更不可になっています。
文字列の破壊的変更は、
実際には新たな文字列本体を作成して、元の文字列が指している本体とポインタを
置き換えることで実現されます。
ですのでこのsrfiをGaucheに実装すること自体は全く問題ないのですが、
これらのAPIを使ったからといって性能上の恩恵にあずかれるわけではありません。
変更不可な文字列を@code{string-append} and @code{string-replace}で
切り貼りするのと、性能的には何ら変わりません。
(このモジュールのAPIは、変更不可文字列を扱うAPIと若干異なることに注意してください。)

このモジュールは、互換性のためだけ提供されます。
Gaucheに依存したプログラムはこのモジュールを使う必要はないでしょう。
特に、SRFI-118のドキュメントにある例は避けるのが懸命です
(文字列を、小さな塊ごとに破壊的にappendしてゆくという実装ですが、
Gaucheではそれは文字列の長さの2乗に比例した時間がかかってしまいます)。
@c COMMON
@end deftp

@defun string-append! string values @dots{}
[SRFI-118]
@c MOD srfi.118
@c EN
The @var{string} argument must be a mutable string.
Modify @var{string} by appending @var{values}, each of which is
either a character or a string.
@c JP
@var{string}引数は変更可能な文字列でなければなりません。
残りの引数@var{values}はそれぞれ文字または文字列です。それらを@var{string}に
破壊的に追加します。
@c COMMON

@example
(rlet1 a (string-copy "abc")
  (string-append! a #\X "YZ"))
 @result{} "abcXYZ"
@end example
@end defun

@defun string-replace! dst dst-start dst-end src :optional src-start src-end
[SRFI-118]
@c MOD srfi.118
@c EN
The @var{dst} argument must be a mutable string.
Replace @var{dst} between @var{dst-start} (inclusive) and
@var{dst-end} (exclusive) with a string @var{src}.  The optional
arguments @var{src-start} and @var{src-end} limits the region of
@var{src} to be used.
@c JP
@var{dst}引数は変更可能な文字列でなければなりません。
@var{dst}中の、@var{dst-start}(inclusive)から@var{dst-end}(exclusive)までの
内容が文字列@var{src}で置き換えられます。省略可能引数
@var{src-start}と@var{src-end}で、@var{src}の使う部分を制限することができます。
@c COMMON

@c EN
Be aware that the order of arguments differ from
SRFI-13's @code{string-replace} (@pxref{SRFI-13 Other string operations});
@code{string-replace!} resembles to @code{string-copy!} (also in SRFI-13),
rather than @code{string-replace}.
@c JP
引数の順序がSRFI-13の@code{string-replace}とは異なることに
注意して下さい (@ref{SRFI-13 Other string operations}参照)。
@code{string-replace!}の引数順は同じくSRFI-13にある@code{string-copy!}に
似せてあります。
@c COMMON

@example
(rlet1 a (string-copy "abc")
  (string-replace! a 1 2 "XYZ"))
 @result{} "aXYZc"
@end example
@end defun


@c ----------------------------------------------------------------------
@node Timer APIs, Titlecase procedures, Simple adjustable-size strings, Library modules - SRFIs
@section @code{srfi.120} - Timer APIs
@c NODE タイマーAPI, @code{srfi.120} - タイマーAPI

@deftp {Module} srfi.120
@mdindex srfi.120
@c EN
This srfi provides a device to run tasks in a specified time.

In Gauche, this is a thin wrapper of @code{control.scheduler} module
(@pxref{Scheduler}, for the details).  Use this module if you need portability.
@c JP
このsrfiは、タスクを指定した時間に実行するデバイスを提供します。

Gaucheではこれは@code{control.scheduler}の薄いラッパーです。
(詳しくは@ref{Scheduler}参照)。このモジュールは移植性が必要な場合に利用すると良いでしょう。
@c COMMON
@end deftp

@defun make-timer :optional error-handler
[SRFI-120]
@c MOD srfi.120
@c EN
Create a new timer, with @var{error-handler} as an error hander.
The @var{error-handler} argument must be @code{#f} or
a procedure that takes one argument.
If it is a procedure, it is called when the task thunk raises an error,
with the raised condition as an argument.  Its return value is ignored.
If omitted, @code{#f} is assumed.

In Gauche, returned timer object is just an instance of @code{<scheduler>},
and @var{error-handler} is set in its @code{error-handler} slot.
@xref{Scheduler}, for the details.
@c JP
新たなタイマーを作って返します。@var{error-handler}引数は@code{#f}もしくは
引数をひとつ取る手続きです。手続きであれば、タスクのサンクがエラーを上げた時に、
投げられたコンディションを引数にして呼び出されます。その返り値は無視されます。
省略された場合は@code{#f}とされます。

Gaucheでは、返されるタイマーオブジェクトは@code{<scheduler>}のインスタンスで、
@var{error-handler}引数は@code{error-handler}スロットに渡されます。
詳しくは@ref{Scheduler}を見てください。
@c COMMON
@end defun

@defun timer? obj
[SRFI-120]
@c MOD srfi.120
@c EN
Returns @code{#t} iff @var{obj} is a timer
(an instance of @code{<scheduler>}).

Same as @code{scheduler?} in @code{control.scheduler} (@pxref{Scheduler}).
@c JP
@var{obj}がタイマー (@code{<scheduler>}のインスタンス)であれば@code{#t}を、
そうでなければ@code{#f}を返します。

@code{control.scheduler}の@code{scheduler?}と同じです (@ref{Scheduler}参照)。
@c COMMON
@end defun

@defun timer-cancel! timer
[SRFI-120]
@c MOD srfi.120
@c EN
Stops the timer.  No tasks in the queue will be executed, and
no new tasks is accepted.  Once timer is canceled, it can't be restarted.

If the timer's tasks ever raised an error, and either the timer doesn't
have an error handler, or an error handler itself raises an error, then
the condition object is kept in the timer and reraised from this procedure.

See also @code{scheduler-terminate!} in @code{control.scheduler}
(@pxref{Scheduler}).
@c JP
タイマーを止めます。まだ残っているタスクはもう実行されず、
また新しいタスクを登録することもできません。
一旦止められたタイマーをリスタートすることはできません。

タイマーのタスクがエラーを投げて、タイマーがerror-handlerを持っていないか、
あるいはエラーを処理したerror-handlerがその中でさらにエラーを投げた場合、
投げられたコンディションはタイマー中に保存され、この手続きからreraiseされます。

@code{control.scheduler}の@code{scheduler-terminate!}も参照してください
(@ref{Scheduler})。
@c COMMON
@end defun

@defun timer-schedule! timer thunk when :optional period
[SRFI-120]
@c MOD srfi.120
@c EN
Creates a new task to run @var{thunk} in the @var{timer}, at @var{when}.
The @var{when} argument specifies the relative time from the moment
this procedure is called.  It must be either an integer as the number
of @emph{milliseconds}, or a time delta object created by
@code{make-timer-delta}.

If the @var{period} argument is given and non zero, the task will be
repeated in every period.
It must be a nonnegative integer in milliseconds
or a time delta object.  If it is zero, task is non-repeating.

Retuns a task-id, which can be used to reschedule or remove the task
later.  The srfi specifies a task id to be any printable Scheme object;
Gauche uses an integer.

Note: In Gauche, a time delta object is a SRFI-19 @code{time-duration}
time (@pxref{SRFI-19 Time types}).

This is implemented on top of @code{scheduler-schedule!} in
@code{control.scheduler} (@pxref{Scheduler}), but note that
the unit of @var{when} and @var{period} is different from it.
@c JP
@var{thunk}を@var{when}で指定される時点に実行するタスクを作成します。
@var{when}は正確な非負整数か、@code{make-timer-delta}が返す時間差オブジェクト
でなければならず、この手続きを呼び出した時点からの相対時間を指定します。
整数の場合はミリ秒単位です。

@var{period}引数が与えられてゼロでない場合、タスクは指定間隔で繰り返されます。
@var{period}引数も@var{when}と同様、非負整数のミリ秒か時間差オブジェクトです。
@var{period}がゼロの場合はタスクは繰り返しません。

戻り値はタスクIDで、それを使ってタスクをリスケジュールしたり削除したりできます。
SRFIではタスクIDは「print可能であること」としか規定されていません。
Gaucheは整数を使っています。

註: Gaucheでは、時間差オブジェクトはSRFI-19の@code{time-duration}タイプの
@code{<time>}オブジェクトです。@ref{SRFI-19 Time types}参照。

この手続きは@code{control.scheduler}の@code{scheduler-schedule!}を
使って実装されています(@ref{Scheduler}参照)が、
@var{when}と@var{period}の単位が異なっていることに注意してください。
@c COMMON
@end defun

@defun timer-reschedule! timer task-id when :optional period
[SRFI-120]
@c MOD srfi.120
@c EN
Change the timing when task identified by @var{task-id} in @var{timer}
is executed.  The @var{task-id} should be the object returned
from previous @code{timer-schedule!} on the same @var{timer}.
@c JP
@var{timer}中で@var{task-id}で指定されるタスクの実行時間を変更します。
@var{task-id}はこれ以前に@code{timer-schedule!}を@var{timer}に適用して
返されたオブジェクトでなければなりません。
@c COMMON

@c EN
The semantics of @var{when} and @var{period} are the same as
@code{timer-schedule!}.
@c JP
@var{when}と@var{period}の意味は@code{timer-schedule!}と同じです。
@c COMMON

@c EN
If there's no task with @var{task-id} in @var{timer} (including the
case that the task was one-shot and already run), an error is thrown.
(The behavior is undefined in the srfi).
@c JP
@var{task-id}に該当するタスクが無い場合 (一回きりのタスクとして既に実行されてしまって
いる場合も含みます) にはエラーが投げられます。(srfiではこの場合の動作は規定されていません)
@c COMMON

@c EN
This procedure returns @var{task-id}.
@c JP
返り値は@var{task-id}です。
@c COMMON

@c EN
This is implemented on top of @code{scheduler-reschedule!} in
@code{control.scheduler} (@pxref{Scheduler}), but note that
the unit of @var{when} and @var{period} is different from it.
@c JP
この手続きは@code{control.scheduler}の@code{scheduler-reschedule!}を
使って実装されています(@ref{Scheduler}参照)が、
@var{when}と@var{period}の単位が異なっていることに注意してください。
@c COMMON

@end defun

@defun timer-task-remove! timer task-id
[SRFI-120]
@c MOD srfi.120
@c EN
Removes the task specified by @var{task-id} from the @var{timer}.
Returns @code{#t} if the task is actually removed, @code{#f} if
the timer doesn't have the specified task.
@c JP
@var{timer}中の、@var{task-id}で指定されるタスクを取り除きます。
タスクが実際に取り除かれたら@code{#t}を、指定のタスクが存在しなければ@code{#f}を返します。
@c COMMON
@end defun

@defun timer-task-exists? timer task-id
[SRFI-120]
@c MOD srfi.120
@c EN
Returns @code{#t} iff the timer has a task specified by @var{task-id}.
A non-repeated task is automatically removed from @var{timer} once executed.
@c JP
@var{timer}が@var{task-id}で指定されるタスクを持っていれば@code{#t}を、
そうでなければ@code{#f}を返します。
繰り返さないタスクは実行されたら@var{timer}から自動的に除かれます。
@c COMMON
@end defun

@defun make-timer-delta n unit
[SRFI-120]
@c MOD srfi.120
@c EN
A constructor for time-delta object.  It can be passed to @var{when}
and @var{period} arguments of @code{timer-schedule!} and
@code{timer-reschedule!}.
@c JP
時間差オブジェクトのコンストラクタです。時間差オブジェクトは@code{timer-schedule!}と
@code{timer-reschedule!}の@var{when}と@var{period}引数に渡すことができます。
@c COMMON

@c EN
In Gauche, a time-delta object is an instance of @code{<time>} with
@code{time-duration} type (@pxref{SRFI-19 Time types}).
The srfi doesn't specify the concrete
implementation, though, so portable code should use this procedure.
@c JP
Gaucheでは時間差オブジェクトは@code{time-duration}型の@code{<time>}オブジェクト
のインスタンスです(@ref{SRFI-19 Time types}参照)。
このSRFIでは時間差オブジェクトの具体的な実装は指定されていないので、
ポータブルなコードではこの手続きを使って時間差オブジェクトを得るのが良いでしょう。
@c COMMON

@c EN
@var{n} is an integer, and @code{unit} must be one of the following symbols:
@code{h} (hour), @code{m} (minute), @code{s} (second),
@code{ms} (millisecond), @code{us} (microsecond) or @code{ns} (nanosecond).
@c JP
@var{n}は整数、@code{unit}は以下のシンボルのいずれかです:
@code{h} (時間)、@code{m} (分)、@code{s} (秒)、
@code{ms} (ミリ秒)、@code{us} (マイクロ秒)、@code{ns} (ナノ秒)。
@c COMMON
@end defun

@defun timer-delta? obj
[SRFI-120]
@c MOD srfi.120
@c EN
Returns @code{#t} iff @var{obj} is a time-delta object,
which is, in Gauche, an instance of @code{<time>} object with
@code{time-duration} type.
@c JP
@var{obj}が時間差オブジェクトなら@code{#t}を、そうでなければ@code{#f}を返します。
Gaucheでは時間差オブジェクトは@code{time-duration}型の@code{<time>}オブジェクトの
インスタンスです。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Titlecase procedures, Cursor-based string library, Timer APIs, Library modules - SRFIs
@section @code{srfi.129} - Titlecase procedures
@c NODE Titlecase手続き, @code{srfi.129} - Titlecase手続き

@deftp {Module} srfi.129
@mdindex srfi.129
@c EN
This srfi defines 3 procedures handling titlecase of characters.
All of the procedures are supported by Gauche, and this module
serves as a compatiblity interface.
@c JP
このsrfiは、文字のtitlecaseを扱う3つの手続きを定義しています。
全ての手続きはGaucheでサポートされているので、このモジュールは互換性のための
インタフェースを提供するだけです。
@c COMMON

@c EN
These two procedures are built-in (@pxref{Characters}):
@c JP
次の2つの手続きは組み込みです (@ref{Characters}参照):
@c COMMON
@example
char-title-case?
char-titlecase
@end example

@c EN
The following procedure is provided in @code{gauche.unicode}
(@pxref{Full string case conversion}).
@c JP
次の手続きは@code{gauche.unicode}で提供されています
(@ref{Full string case conversion}参照):
@c COMMON
@example
string-titlecase
@end example

@end deftp

@c ----------------------------------------------------------------------
@node Cursor-based string library, Minimal unique types, Titlecase procedures, Library modules - SRFIs
@section @code{srfi.130} - Cursor-based string library
@c NODE カーソルを使う文字列ライブラリ, @code{srfi.130} - カーソルを使う文字列ライブラリ

@deftp {Module} srfi.130
@mdindex srfi.130
@c EN
This is an reduced version of @code{srfi.13} that supports cursors in
addition to indexes. The consistency with R7RS and recent srfis are
also considered.
@c JP
これは@code{srfi.13}の縮小バージョンで、インデックスの箇所に文字列カーソルも
使えるようにしたものです。APIにはR7RSと最近のsrfiとの一貫性も考慮してあります。
@c COMMON

@c EN
Gauche supports string cursors natively (@pxref{String cursors}), so
all built-in and SRFI-13 string procedures that takes string indexes
can als otake string cursors as well.  You want to use this module
explicitly, though, if you're writing a portable code.
@c JP
Gaucheは文字列カーソルを組み込みでサポートしており(@ref{String cursors}参照)、
文字列インデックスを引数に取る組み込み手続きやSRFI-13手続きはインデックスの箇所に
文字列カーソルを渡すことができます。ただ、ポータブルなコードを書いている場合は、
このモジュールを明示的に使うのが良いでしょう。
@c COMMON

@c EN
The following are built-in.  @xref{String cursors}, for the details.
@c JP
以下の手続きは組み込みです。@ref{String cursors}を参照してください。
@c COMMON

@example
string-cursor?        string-cursor-start    string-cursor-end
string-cursor-next    strig-cursor-prev      string-cursor-forward
string-cursor-back    string-cursor=?        string-cursor<?
string-cursor<=?      string-cursor>?        string-cursor>=?
string-cursor-diff    string-cursor->index   string-index->cursor
@end example

@c EN
The following procedures are simply aliases of the builtin version
without the @code{/cursor} or @code{/cursors} suffix.
@c JP
以下の手続きは@code{/cursor}や@code{/cursors}サフィックスを除いた
組み込み手続きの単なる別名になっています。
@c COMMON

@example
string->list/cursors  string->vector/cursors string-copy/cursors
string-ref/cursor     substring/cursors
@end example

@c EN
The following procedures are defined in SRFI-13.  @xref{String library},
for the details.  Note: Some of those procedures in SRFI-13 accept
only indexes.  In SRFI-130, both indexes
and cursors are accepted.  Our SRFI-13 implementation shares the same
procedure with SRFI-130, so they accept both indexes and cursors but
such code won't be portable as SRFI-13.
@c JP
以下の手続きはSRFI-13で定義されています (@ref{String library}参照)。
SRFI-13でインデックスのみを受け取る手続きは、SRFI-130で
インデックスと文字列カーソル両方を受け取るように拡張されています。
GaucheではSRFI-13とSRFI-130の手続きは同じコードを利用していて、
従って常にインデックスも文字列カーソルも使えますが、
SRFI-13としてインポートした手続きに文字列カーソルを渡すのはポータブルではありません。
@c COMMON

@example
string-null?       string-any         string-every       string-tabulate
string-unfold      string-unfold-right                   reverse-list->string
string-take        string-drop        string-take-right  string-drop-right
string-pad         string-pad-right   string-trim        string-trim-right
string-trim-both   string-replace     string-prefix-length
string-suffix-length                  string-prefix?     string-suffix
string-concatenate string-concatenate-reverse            string-count
string-filter      string-reverse
@end example

@c EN
The following procedures are the same as SRFI-152, except that
the arguments that takes integer indexes can also accept string cursors
(@pxref{String library (reduced)}):
@c JP
以下の手続きは、整数インデックスを取る引数が文字列カーソルも取れるという点を除いて、
SRFI-152にあるものと同じです (@ref{String library (reduced)}参照):
@c COMMON

@example
string-replicate   string-remove      string-split
@end example

@c EN
The following procedures are also defined in SRFI-13, but SRFI-130 redefines
them to return a string cursor instead of an integer index.  They are
described below.
@c JP
以下の手続きはSRFI-13の同名の手続きと異なり、インデックスではなく文字列カーソルを返します。
以下で詳しく説明します。
@c COMMON

@example
string-index        string-index-right
string-skip         string-skip-right
string-contains     string-contains-right
@end example
@end deftp

@defun string-index string pred :optional start end
@defunx string-index-right string pred :optional start end
@defunx string-skip string pred :optional start end
@defunx string-skip-right string pred :optional start end
[SRFI-130]
@c MOD srfi.130
@c EN
Find the position of a character that satisfies @var{pred}
(@code{string-index}/@code{string-index-right}), or
does not satisfy @var{pred}
(@code{string-skip}/@code{string-skip-right}), in a @var{string}.
The chacter is searched from left to right in
@code{string-index}/@code{string-skip}, and
right to left in @code{string-index-right}/@code{string-skip-right}.
@c JP
@var{pred}を満たす(@code{string-index}/@code{string-index-right})
もしくは満たさない(@code{string-skip}/@code{string-skip-right})最初の文字
の位置を返します。
@code{string-index}/@code{string-skip}は左から、
@code{string-index-right}/@code{string-skip-right}は右から該当する文字を探します。
@c COMMON

@c EN
While SRFI-13's procedures of the same names returns integer index,
these returns a string cursor instead.
@c JP
SRFI-13の同名の手続きが整数の文字インデックスを返すのに対し、
これらは文字列カーソルを返します。
@c COMMON

@c EN
The returned cursor from @code{string-index}/@code{string-skip}
points the leftmost character that satisfies/does not satsify @var{pred},
while the returned cursor from
@code{string-index-right} points the next (right) character of the rightmost
one that satisfies/does not satisfy @var{pred}.
If there're no characters that satisfy @var{pred},
@code{string-index} returns a cursor at the end
of the string, while @code{string-index-right}
returns a cursor at the beginning of the string.
(The @code{*-skip} variation reverses the condition).
@c JP
@code{string-index}が返すカーソルは、
@var{pred}を満たす最も左の文字を指しています。
一方、@code{string-index-right}が返すカーソルは、
@var{pred}を満たす最も右の文字の次(一つ右)を指しています。
また、ひとつも@var{pred}を満たす文字が無かった場合、
@code{string-index}は文字列の最後(最後の文字の次)を指すカーソルを、
@code{string-index-right}は文字列の先頭を指すカーソルを返します。
(@code{*-skip}は条件が逆になるだけです)。
@c COMMON

@c EN
(This is easier to understand if you think the cursor is between characters;
if we scan a string from left to right, the cursor looks at the
character on its right; if we scan from right to left, the cursor looks at
the character on its left.)
@c JP
(この仕様は、カーソルが文字の「間」にあると考える方がわかりやすいかもしれません。
左から右に文字列を見て行く時は、カーソルは自分の右側の文字を見ます。
右から左に見て行く時は、自分の左側の文字を見ます。)
@c COMMON

@c EN
Be aware that they still return a cursor even no characters satisfy the
condition, while SRFI-13 versions return @code{#f} in such cases.
@c JP
条件を満たす文字が無かった時にもカーソルが返されることに注意してください。
SRFI-13のバージョンではその場合は@code{#f}が返されていました。
@c COMMON

@c EN
The optional @var{start}/@var{end} can be string cursors or integer
indexes to limit the region of @var{string} to search.
@c JP
省略可能な@var{start}/@var{end}引数は文字列カーソルか整数の文字インデックスで、
探索領域を限定します。
@c COMMON

@example
(define *s* "abc def ghi")

(string-cursor->index *s* (string-index *s* char-whitespace?))
  @result{} 3

(string-cursor->index *s* (string-index *s* char-whitespace? 4))
  @result{} 7

(string-cursor->index *s* (string-index-right *s* char-whitespace?))
  @result{} 8

(string-cursor->index *s* (string-index-right *s* char-whitespace? 0 7))
  @result{} 4
@end example
@end defun

@defun string-contains haystack needle :optional start1 end1 start2 end2
@defunx string-contains-right haystack needle :optional start1 end1 start2 end2
[SRFI-130]
@c MOD srfi.130
@c EN
Search for a substring @var{needle} in a string @var{haystack}.
The substring is searched from left to right (@code{string-contains})
or right to left (@code{string-contains-right}).
@c JP
文字列@var{haystack}の中から部分文字列@var{needle}を探します。探索方向は、
@code{string-contains}では左から右へ@code{string-contains-right}では
右から左です。
@c COMMON

@c EN
While SRFI-13's procedures of the same names returns an integer index
of the beginning of the substring if found,
these procedures returns a string cursor
of the beginning of @var{haystack}.
@c JP
SRFI-13の同名の手続きは、見つかった部分文字列の開始位置を整数インデックスで
返しますが、これらの手続きは文字列カーソルで返します。
@c COMMON

@c EN
If @var{haystack} doesn't countain @var{needle}, they return @code{#f}.
@c JP
@var{haystack}が@var{needle}中に無ければ@code{#f}が返されます。
@c COMMON
@end defun

@defun string-for-each-cursor proc string :optional start end
[SRFI-130]
@c MOD srfi.130
@c EN
Calls @var{proc} with each cursor of @var{string}, from left to right,
excluding the post-end cursor.  This is the cursor version of
@code{string-for-each-index} in SRFI-13 (@pxref{SRFI-13 String mapping}).
@c JP
@var{proc}を@var{string}中の各文字列カーソル位置(左から右へ)を引数にして
順に呼び出します。ただし最後のカーソル(末尾文字の次の位置)については@var{proc}
を呼びません。
SRFI-13の@code{string-for-each-index}の文字列カーソル版です。
@c COMMON

@example
(define s "abc")
(string-for-each-cursor (^c (display (string-ref/cursor s c))) s)
 @result{} @r{displays} abc
@end example
@end defun

@c ----------------------------------------------------------------------
@node Minimal unique types, String library (reduced), Cursor-based string library, Library modules - SRFIs
@section @code{srfi.137} - Minimal unique types
@c NODE 最小限の一意の型, @code{srfi.137} - 最小限の一意の型

@deftp {Module} srfi.137
@mdindex srfi.137
This SRFI provides a simple way to create disjoint types.
It's so simple that it's easy to write a portable implementation.
It can also be a basis of libraries that requires objects with their own
distinct types.

The system is minimal, both in a way that it can be implemented
on the very basic features of Scheme, and in a way that it provides
a single API.  If you're writing Gauche code, or even portable R7RS,
you may choose fancier abstraction utilities such as Gauche classes
or R7RS records.  This SRFI is useful for code that can only
assume rudimental Scheme implementation, and this module comes handy
when you want to run such code in Gauche.

(In Gauche, this module is implemented on top of Gauche's object system.)
@end deftp

@defun make-type type-payload
[SRFI-137]
@c MOD srfi.137
Returns 5 procedures.  They collectively define a conceptual unique type.

@table @var
@item (type-accessor)
Returns @var{type-payload}.
@item (constructor instance-payload)
Returns a newly allocated instance of this type, holding @var{instance-payload}
in it.  The returned object is of a type disjoint to any other existing types.
@item (predicate obj)
Returns @code{#t} if @var{obj} is an object created by @var{constructor}.
@item (accessor instance)
Returns @var{instance-payload} of @var{instance}.
The argument must be an object created by @var{constructor}.
@item (make-subtype type-payload)
Returns 5 procedures, associated to a newly created type which is
subtype of the originaltype.
@end table

In our implementation, @code{make-type} creates a fresh new class,
and @var{constructor} creats an instance of the class.
The SRFI does not provide the means to access the underlying class,
but in Gauche you can use @code{class-of} on the instance to obtain it.
(Of course, messing with the underlying class is inherently unportable.)
@end defun

@c ----------------------------------------------------------------------
@node String library (reduced), First-class dynamic extents, Minimal unique types, Library modules - SRFIs
@section @code{srfi.152} - String library (reduced)
@c NODE 文字列ライブラリ(簡略版), @code{srfi.152} - 文字列ライブラリ(簡略版)

@deftp {Module} srfi.152
@mdindex srfi.152
@c EN
This is an improved version of @code{srfi.13}.  The spec is actually smaller
than SRFI-13 (hence 'reduced' in the title) by removing bells and whistles.
The consistency with R7RS and recent srfis are also considered.

The following are built-in.  @xref{Strings}, for the details.
@c JP
これは@code{srfi.13}の改良版です。
@code{srfi.13}から余分なものを取り除き、R7RSや最近のsrfiとの一貫性を
改善したもので、実際は@code{srfi.13}より小さくなっています。

以下に示す手続きは組み込みです。詳しくは@ref{Strings}を参照してください。
@c COMMON

@example
string?            make-string        string             string-length
string->vector     string->list       vector->string     list->string
string-ref         string-set!        substring          string-copy
string=?           string<?           string<=?          string>?
string>=?          string-append      string-join        string-split
string-map         string-for-each    read-string        write-string
string-fill!
@end example

@c EN
The following procedures are defined to use Unicode string case folding,
and @code{gauche.unicode} module provides them.
@xref{Full string case conversion}, for the details.
Note that Gauche's
built-in versions uses character-wise case folding, which differs
from string case folding on some characters (German eszett, for example).
@c JP
以下に示す手続きはUnicodeの文字列の大文字小文字変換を使うように定義されていて、
元は@code{gauche.unicode}で提供されています。
説明は@ref{Full string case conversion}を参照してください。
Gaucheの組み込みにも同名の手続きがありますが、それらは文字ごとに
大文字小文字変換を行うので、文字列としての大文字小文字変換とは異なります
(ドイツ語のエスツェット等)。
@c COMMON

@example
string-ci=?   string-ci<?   string-ci<=?  string-ci>?   string-ci>=?
@end example

@c EN
The following procedures are defined in SRFI-13.  @xref{String library},
for the details.  Note: Some of those procedures in SRFI-13 that require
predicate allows a char-set or a character to be passed instead
(e.g. @code{string-filter}).  In SRFI-152, only predicate is allowed.
Our SRFI-152 implementation shares the same procedure with SRFI-13, so
they accept the same arguments as SRFI-13's, but such code won't be
portable as SRFI-152.
@c JP
以下に示す手続きはSRFI-13で定義されています。
説明は@ref{String library}を参照してください。
SRFI-13ではこれらの手続きのいくつかは、述語引数として手続きだけでなく文字集合や
文字を取ることができます(例: @code{string-filter})。
SRFI-152では手続きしか許していません。Gaucheの実装ではこれらの手続きは
SRFI-13のものと同じなのでSRFI-13のような使い方ができますが、
SRFI-152として移植性のあるコードを書く際には手続きだけを渡すように気をつけてください。
@c COMMON

@example
string-null?       string-any         string-every       string-tabulate
string-unfold      string-unfold-right      reverse-list->string
string-take        string-drop        string-take-right  string-drop-right
string-pad         string-pad-right   string-trim        string-trim-right
string-trim-both   string-replace     string-prefix-length string-suffix-length
string-prefix?     string-suffix?     string-index       string-index-right
string-skip        string-skip-right  string-contains    string-concatenate
string-concatenate-reverse            string-fold        string-fold-right
string-count       string-filter      string-copy!
@end example
@end deftp

@c EN
We describe procedures unique to this module below.
@c JP
以降では、SRFI-152特有の手続きについて説明します。
@c COMMON

@defun string-remove pred string :optional start end
[SRFI.152]
@c MOD srfi.152
@c EN
Returns a substring of @var{string} between @var{start} and @var{end},
except characters that satisfy @var{pred}.   In other words,
it is @code{(string-filter (complement pred) string start end)}.

This is called @var{string-delete} in @code{srfi.13}.  Being changed
to take only a predicate (but not a character), it is renamed for
the consistency of other srfi (e.g. @code{filter}, @code{remove} and
@code{delete} in SRFI-1.)
@c JP
@var{string}の@var{start}と@var{end}インデックス間から、
述語@var{pred}を満たす文字を除いた部分文字列を返します。
@code{(string-filter (complement pred) string start end)}と同じです。

これは@code{srfi.13}で@var{string-delete}と呼ばれていた手続きに相当します。
第一引数に述語手続きだけを取るようにし、また他のsrfiとの一貫性を重視して
名前が変えられました(例えばSRFI-1の@code{filter}、@code{remove}、@code{delete}の
関係を考えてください)。
@c COMMON

@example
(string-remove char-whitespace?
               "Quick fox jumps over the lazy dog"
               3 22)
 @result{} "ckfoxjumpsovert"
@end example
@end defun

@defun string-replicate string from to :optional start end
[SRFI-152]
@c MOD srfi.152
@c EN
Extended substring.  It is called @code{xsubstring} in SRFI-13, but
renamed for the consistency.

Extract a substring of @var{string} between @var{start} and @var{end},
and conceptually create a bidirectional infinite string by repeating
the substring to both direction.  For example, suppose @var{string}
is @code{"abcde"}, @var{start} is 1, and @var{end} is 4.  So we repeat
the substring @code{"bcd"}, with one @code{b} falling on the index zero:
@c JP
拡張版substringです。SRFI-13では@code{xsubstring}と呼ばれていましたが、
一貫性のため名前が変えられました。

@var{string}のインデックス@var{start}から@var{end}までの部分文字列をとり、
それを両側に無限に繰り返した文字悦を考えます。
例えば@var{string}が@code{"abcde"}であり、@var{start}が1、@var{end}が4なら、
@code{"bcd"}が無限に繰り替えされた文字列を考えます。この文字列がソース文字列となります。
@code{b}がインデックスの起点です。
@c COMMON

@example
... b  c  d  b  c  d  b  c  d  b  c  d  b ...
   -6 -5 -4 -3 -2 -1  0  1  2  3  4  5  6
@end example

@c EN
Then we extract a substring between @var{from} and @var{to}
out of this infinite string.
@c JP
このソース文字列から、インデックス@var{from}と@var{to}の間の部分文字列を取り出し返します。
@c COMMON

@example
(string-replicate "abcde" 2 10 1 4)
  @result{} "dbcdbcdb"
(string-replicate "abcde" -5 -3 1 4)
  @result{} "cdbcdbcd"
@end example
@end defun

@defun string-segment string k
[SRFI-152]
@c MOD srfi.152
@c EN
Splits @var{string} by every @var{k} characters and returns
a list of those strings.  The last string may be shorter than @var{k}.
@c JP
@var{string}を@var{k}文字ごとに分割して、そのリストを返します。
最後の文字列は@var{k}文字より短いかもしれません。
@c COMMON

@example
(string-segment "abcdefghijklmn" 3)
 @result{} ("abc" "def" "ghi" "jkl" "mn")
@end example

@c EN
We have a similar procedure on lists, @code{slices}
(@pxref{List accessors and modifiers}).
@c JP
類似の手続きとして、@code{slices}があります。
(@ref{List accessors and modifiers}参照)。
@c COMMON
@end defun

@defun string-contains-right string1 string2 :optional start1 end1 start2 end2
[SRFI-152]
@c MOD srfi.152
@c EN
Like @code{string-contains}, looks for a needle @var{string2} from
a haystack @var{string1}, but if it is found, returns the start index
of the @emph{last} match, instead of the first match.  The returned index
is in @var{string1}.  The optional arguments limit the range of a needle
and a haystack.  If a needle isn't found, @code{#f} is returned.

An edge case: If a needle is empty (e.g. @var{string2} is empty,
or @var{start2} = @var{end2}), it always matches right after the haystack,
so @var{end1} is returned.
@c JP
@code{string-contains}と同様、
ソース文字列@var{string1}から探索文字列@var{string2}を探しますが、
見つかった場合は最初ではなく最後のマッチの開始インデックスを返します。
開始インデックスは@var{string1}に対するものです。
省略可能引数は@var{string1}、@var{string2}それぞれの対象とする文字列を制限します。
探索文字列@var{string2}が見つからなかった場合は@code{#f}が返されます。

エッジケースとして、探索文字列が空文字列の場合 (@var{string2}が空であるとか、
@var{start2} = @var{end2}である場合)は、
それは常にソース文字列の一番右端とマッチします。つまり@var{end1}が戻り値になります。
@c COMMON

@example
(string-contains-right "Little Lisper" "Li")
  @result{} 7
@end example
@end defun

@defun string-take-while string pred :optional start end
@defunx string-take-while-right string pred :optional start end
[SRFI-152]
@c MOD srfi.152
@c EN
Returns the longest prefix or suffix of @var{string} in which all characters
satisfy @var{pred}.

Note: The order of @var{pred} and the source object is different from
other @code{take-while}-style procedures, such as @code{take-while}
(@ref{R7RS lists}), @code{ideque-take-while} (@ref{R7RS immutable deques}),
and @code{lseq-take-while} (@ref{R7RS lazy sequences}).
@c JP
@var{string}から、全ての文字が述語@var{pred}を満たすような最長のプレフィクスまたは
サフィックスを返します。

註: @var{pred}引数と対象とするオブジェクトの順序が、
他の@code{take-while}系手続き、
@code{take-while}(@ref{R7RS lists})、
@code{ideque-take-while} (@ref{R7RS immutable deques})、
@code{lseq-take-while} (@ref{R7RS lazy sequences})等とは逆であることに
注意してください。
@c COMMON
@end defun

@defun string-drop-while string pred :optional start end
@defunx string-drop-while-right string pred :optional start end
[SRFI-152]
@c MOD srfi.152
@c EN
Returns the longest prefix or suffix of @var{string} in which all characters
does not satisfy @var{pred}.

Note: The order of @var{pred} and the source object is different from
other @code{drop-while}-style procedures, such as @code{drop-while}
(@ref{R7RS lists}), @code{ideque-drop-while} (@ref{R7RS immutable deques}),
and @code{lseq-drop-while} (@ref{R7RS lazy sequences}).
@c JP
@var{string}から、全ての文字が述語@var{pred}を満たさないような最長のプレフィクスまたは
サフィックスを返します。

註: @var{pred}引数と対象とするオブジェクトの順序が、
他の@code{drop-while}系手続き、
@code{drop-while}(@ref{R7RS lists})、
@code{ideque-drop-while} (@ref{R7RS immutable deques})、
@code{lseq-drop-while} (@ref{R7RS lazy sequences})等とは逆であることに
注意してください。
@c COMMON
@end defun

@defun string-span string pred :optional start end
@defunx string-break string pred :optional start end
[SRFI-152]
@c MOD srfi.152
@c EN
Find the longest prefix of @var{string} between @var{start} and @var{end}
in which all characters satisy / do not satisfy @var{pred}, and returns
the prefix and the rest of substring as two values.
@c JP
@var{string}の@var{start}から@var{end}までの範囲のうち、
全ての文字が述語@var{pred}を満たす、あるいは満たさないような最長のプレフィクスをみつけ、
そのプレフィクスと、残りの部分文字列を二つの値として返します。
@c COMMON

@example
(string-break "foo@@example.com" (cut eqv? <> #\@@))
 @result{} "foo" @r{and} "@@example.com"

(string-break "foo@@example.com" (cut eqv? <> #\@@) 1 10)
 @result{} "oo" "@@exampl"

@c EN
;; This is Gauche specific - a char-set can work as a predicate:
@c JP
;; Gaucheでは文字集合を述語手続きとしても使える
@c COMMON
(string-span "VAR_1 = $VAR_2" #[\w])
 @result{} "VAR_1" @r{and} " = $VAR_2"
@end example

@c EN
Note: The order of @var{pred} and the source object is different from
@code{span} and @code{break} in @code{scheme.list}
(@pxref{R7RS lists}).
@c JP
@var{pred}引数とソースオブジェクトの順が、
@code{scheme.list}の@code{span}、@code{break}と逆であることに注意
(@ref{R7RS lists}参照)。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node First-class dynamic extents, Homogeneous numeric vector libraries, String library (reduced), Library modules - SRFIs
@section @code{srfi.154} - First-class dynamic extents
@c NODE 第一級の動的エクステント, @code{srfi.154} - 第一級の動的エクステント

@deftp {Module} srfi.154
@mdindex srfi.154
@c EN
This module provides a convenient way to reify the dynamic environment.
A continuation captured by @code{call/cc} includes the dynamic environment,
as well as the control flow.  Sometimes you only want the dynamic environment
part.  A dynamic extent is a reified dynamic environment.
@c JP
このモジュールは、動的環境を簡単に取り出す手段を提供します。
@code{call/cc}によって捕捉される継続は、制御フローと同時に動的環境を保持しますが、
時には動的環境だけが欲しい場合があります。
動的エクステントは、具象化された動的環境です。
@c COMMON

@c EN
Let's see an example.  You want a procedure that prints out
a message to the error port, so you wrote this @code{print-error}:
@c JP
例で見てみましょう。メッセージをエラー出力に出したいので、
こんな@code{print-error}を書いたとします:
@c COMMON

@example
(define print-error
  (lambda (msg) (display msg (current-error-port))))
@end example

@c EN
However, if @code{print-error} is called while the current error port
is altered, it is affected.  It is supposed to be so, that's
the point of @code{current-error-port}.
@c JP
ところで、@code{print-error}が呼ばれた時点で現在のエラー出力ポートが置き換えられていたら、
出力先は変わります。もちろん、そのための@code{current-error-port}なのですから、
これは想定された動作です。
@c COMMON

@example
(call-with-output-string
  (^p (with-error-to-port p (^[] (print-error "abc\n")))))
 @result{} "abc\n"
@end example

@c EN
If you do want @code{print-error} to use the error port
at the time it is defined, you have to extract the dynamic value
at the moment.
@c JP
けれども、@code{print-error}が定義された時点でのエラー出力ポートを常に使いたい
場合はどうすれば良いでしょうか。ひとつの方法は、定義時のエラー出力ポートの
動的な値を保存しておくことです：
@c COMMON

@example
(define print-error
  (let1 eport (current-error-port)
    (lambda (msg) (display msg eport))))
@end example

@c EN
This would be quickly cumbersome when you need to capture multiple
dynamic values, or the original @code{print-error} is called indirectly
and you can't modify it the way shown above.
@c JP
しかし、これは捕捉したい動的な値が増えればややこしくなりますし、
@code{print-error}が自分の触れない箇所で定義されていて書き換えられない場合も
面倒です。
@c COMMON

@c EN
Using @code{dynamic-lambda} addresses this issue.  It not only captures
the lexical environment, but also the dynamic environment when it
is evaluated.  So the @code{current-error-port} in its body
returns the current error port at the time of @code{print-error}
being defined, not when it is called:
@c JP
@code{dynamic-lambda}は、レキシカルな環境だけでなくそれが評価された時点の
動的環境をも捕捉することでこの問題を解決します。
次の例では、@code{current-error-port}は@code{print-error}が定義された時点の
値を返します：
@c COMMON

@example
(define print-error
  (dynamic-lambda (msg) (display msg (current-error-port))))
@end example
@end deftp

@defun current-dynamic-extent
[SRFI-154]
@c MOD srfi.154
@c EN
Returns a dynamic-extent object that reifies the current dynamic
environment.
@c JP
現在の動的環境を具象化した動的エクステントオブジェクトを返します。
@c COMMON
@end defun

@defun dynamic-extent? obj
[SRFI-154]
@c MOD srfi.154
@c EN
Returns @code{#t} iff @var{obj} is a dynamic-extent object.
@c JP
@var{obj}が動的エクステントオブジェクトの時のみ@code{#t}を返します。
@c COMMON
@end defun

@defun with-dynamic-extent dynext thunk
[SRFI-154]
@c MOD srfi.154
@c EN
Calls the @var{thunk} in the dynamic extent @var{dynext}, and
returns the values yielded by @var{thunk}.
@c JP
動的環境を動的エクステント@var{dynext}で置き換えた状態で
@var{thunk}を呼びます。@var{thunk}が返した値が戻り値となります。
@c COMMON
@end defun

@defmac dynamic-lambda formals body @dots{}
[SRFI-154]
@c MOD srfi.154
@c EN
Like @code{lambda}, but this not only captures the lexical environment,
but also the dynamic environment.  Yields a procedure.

Note: Since @code{dynamic-lambda} needs to swap the dynamic environment
after executing @var{body}, the last expression of @var{body} isn't
called in the tail context even if the procedure created by
@code{dynamic-lambda} is called in tail context.
@c JP
@code{lambda}のように振る舞いますが、レキシカルな環境だけでなく、
評価時の動的環境も捕捉します。手続きを返します。

註: @code{dynamic-lambda}は最後の@var{body}の実行が終わった後で動的環境を
戻さなければならないので、@code{dynamic-lambda}で作られた手続きが末尾呼び出し
されたとしても、@var{body}の末尾式は末尾呼び出しにはなりません。
@c COMMON
@end defmac



@c ----------------------------------------------------------------------
@node Homogeneous numeric vector libraries, Comparator sublibrary, First-class dynamic extents, Library modules - SRFIs
@section @code{srfi.160} - Homogeneous numeric vector libraries
@c NODE 均質な数値ベクタライブラリ, @code{srfi.160} - 均質な数値ベクタライブラリ

@deftp {Module} srfi.160
@mdindex srfi.160
@c EN
This is an enhancement of SRFI-4, Homogeneous vectors
(@pxref{Homogeneous vectors}), and then become a part
of R7RS-large (@pxref{R7RS uniform vectors}).

In Gauche, all the procedures in this module are provided
as a part of @code{gauche.uvector} module
(@pxref{Uniform vectors}), and described there.

This module only exports the procedures defined in @code{srfi.160}.
@c JP
これはSRFI-4の拡張で (@ref{Homogeneous vectors}参照)、
R7RS-largeの一部になりました (@ref{R7RS uniform vectors}参照)。

Gaucheでは、このモジュールの全ての手続きは @code{gauche.uvector}
モジュールで提供されているので、そちらで説明されています
(@ref{Uniform vectors}参照)。

このモジュールは、@code{srfi.160}で定義されている手続きのみをエクスポートします。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node Comparator sublibrary, POSIX API, Homogeneous numeric vector libraries, Library modules - SRFIs
@section @code{srfi.162} - Comparator sublibrary
@c NODE 比較器のサブライブラリ, @code{srfi.162} - 比較器のサブライブラリ

@deftp {Module} srfi.162
@mdindex srfi.162
@c EN
This is a supplement of SRFI-128, comparators.  It provides
a few comparator procedures, as well as several useful
pre-defined comparators, listed below.
Theese pre-defined comparators are already built in Gauche,
so see @ref{Predefined comparators} for the details.
@c JP
これはSRFI-128(比較器)への追加です。いくつかの比較器手続きと、
以下に示す便利な定義済み比較器を提供します。
Gaucheではこれらの定義済み比較器は組み込みになっているので、
詳細は@ref{Predefined comparators}を参照してください。
@c COMMON

@example
default-comparator    boolean-comparator    real-comparator
char-comparator       char-ci-comparator    string-comparator
string-ci-comparator  pair-comparator       list-comparator
vector-comparator     eq-comparator         eqv-comparator
equal-comparator
@end example
@end deftp

@defun comparator-min comparator obj obj2 @dots{}
@defunx comparator-max comparator obj obj2 @dots{}
[SRFI-162]
@c MOD srfi.162
@c EN
Find the object in @var{obj1} @var{obj2} @dots{} that is
minimum or maximum compared by @var{comparator}.
Note: SRFI-114 provides the same procedures.
@c JP
@var{obj1} @var{obj2} @dots{}のうちから、
@var{comparator}に基づいた最小あるいは最大の値を返します。
SRFI-114にも同じ手続きがあります。
@c COMMON

@example
(comparator-min list-comparator '(a c b) '(a d) '(a c))
  @result{} (a c)
@end example
@end defun

@defun comparator-min-in-list comparator list
@defunx comparator-max-in-list comparator list
[SRFI-162]
@c MOD srfi.162
@c EN
Find the object in @var{list} that is minimum or maximum compared
by @var{comparator}.  It is an error if @var{list} is empty.
@c JP
@var{list}中のオブジェクトのうちから、
@var{comparator}に基づいた最小あるいは最大の値を返します。
@var{list}が空の場合はエラーが投げられます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node POSIX API, Two safer subsets of R7RS, Comparator sublibrary, Library modules - SRFIs
@section @code{srfi.170} - POSIX API

@deftp {Module} srfi.170
@mdindex srfi.170
@c EN
This module provides a portable interface to a part of POSIX API,
mainly filesystem interface.
@c JP
このモジュールは、ファイルシステムインタフェースを中心としたPOSIX APIの一部を
ポータブルなインタフェースとして提供します。
@c COMMON

@c EN
In Gauche, it is a thin wrapper of Gauche's native system interface
(@pxref{System interface}).  You may want to use this module for
a portable code.
@c JP
GaucheではこのモジュールはGaucheのネイティブシステムインタフェース
(@ref{System interface})の薄いラッパーになっています。
ポータブルなコードを書く場合にこのモジュールは便利でしょう。
@c COMMON
@end deftp

@c EN
@subheading POSIX Error
@c JP
@subheading POSIXエラー
@c COMMON

@defun posix-error? obj
[SRFI-170]
@c MOD srfi.170
@c EN
Returns @code{#t} iff @var{obj} is a condition thrown due to
underlying POSIX-layer error.  On Gauche, POSIX-layer condition
is the same as @code{<system-error>} (@pxref{Conditions}).
@c JP
@var{obj}がPOSIXレイヤから投げられたコンディションである場合に@code{#t}を返します。
Gaucheeでは、POSIXレイヤのコンディションは@code{<system-error>}の
インスタンスです (@ref{Conditions}参照)。
@c COMMON
@end defun

@defun posix-error-name err
[SRFI-170]
@c MOD srfi.170
@c EN
The argument must be a POSIX-layer condition, that is,
an object that satisfies @code{posix-error?}.  In Gauche,
it is a @code{<system-error>} object.

Returns the POSIX error name (symbol)
of the given condition, such as @code{ENOENT}.

See also @code{sys-errno->symbol} (@pxref{System inquiry}).
@c JP
引数はPOSIX層のコンディション、つまり@code{posix-error?}を満たすオブジェクトで
なければなりません。Gaucheではそれは@code{<system-error>}オブジェクトです。

与えられたコンディションのPOSIXエラー名をシンボルで返します
(例: @code{ENOENT})。

@code{sys-errno->symbol}も参照してください
(@ref{System inquiry})。
@c COMMON
@end defun

@defun posix-error-message err
[SRFI-170]
@c MOD srfi.170
@c EN
The argument must be a POSIX-layer condition, that is,
an object that satisfies @code{posix-error?}.  In Gauche,
it is a @code{<system-error>} object.

Returns the error message (string) describing the error,
e.g. @code{"No such file or directory"}.

See also @code{sys-strerror} (@pxref{System inquiry}).
@c JP
引数はPOSIX層のコンディション、つまり@code{posix-error?}を満たすオブジェクトで
なければなりません。Gaucheではそれは@code{<system-error>}オブジェクトです。

与えられたコンディションのPOSIXエラーメッセージを文字列で返します
(例: @code{"No such file or directory"})。

@code{sys-strerror}も参照してください
(@ref{System inquiry})。
@c COMMON
@end defun

@subheading I/O

@defun open-file fname port-type flags :optional permission buffer-mode
[SRFI-170]
@c MOD srfi.170
Opens a file named by @var{fname} and returns a port to read or write
the file.  You have finer control than
@code{open-input-file}/@code{open-output-file}.

The @code{port-type} argument must be either one of the value
of the constant @code{binary-input}, @code{textual-input},
@code{binary-output}, @code{textual-output} and
@code{binary-input/output}.  The direction of the returned port
is determined by this argument.

Gauche doesn't distinguish textual ports and binary ports.

The @var{flags} argument is a bitwise ior of
zero or more of the following bitmasks:
@code{open/append}, @code{open/create}, @code{open/exclusive},
@code{open/nofollow} and @code{open/truncate}.  These corresponds
to the POSIX flags @code{O_APPEND}, @code{O_CREAT}, @code{O_EXCL},
@code{O_NOFOLLOW} and @code{O_TRUNC}.  Gauche exposes the POSIX flags
in @code{gauche.fcntl} (@pxref{Low-level file operations}).

Note: POSIX @code{open(2)} also requires one of the bitmasks
@code{O_RDONLY}, @code{O_WRONLY} and @code{O_RDWR}.  These flags
are deduced from the @var{port-type} argument.

The optional @var{permission} is an integer permission bits
to be used when a new file is created.  The actual permission bits
are also affected by the current @code{umask}.

The optional @var{buffer-mode} is a value of either one of the followings:
@code{buffer-none}, @code{buffer-block}, and @code{buffer-line}.
@end defun

@defun fd->port fd port-type :optional buffer-mode
[SRFI-170]
@c MOD srfi.170
Creates a Scheme port wrapping an integer file descriptor @var{fd}.
The descriptor shouldn't be used by other Scheme ports.  After calling
this procedure, no I/O should be done via @var{fd} directly; the descriptor
is ``owned'' by the port, and will be closed once the port is closed.

The @code{port-type} argument must be either one of the value
of the constant @code{binary-input}, @code{textual-input},
@code{binary-output}, @code{textual-output} and
@code{binary-input/output}.  The direction must match how @var{fd} was
opened.

The optional @var{buffer-mode} is a value of either one of the followings:
@code{buffer-none}, @code{buffer-block}, and @code{buffer-line}.
@end defun

@defvr {Constant} binary-input
@defvrx {Constant} textual-input
@defvrx {Constant} binary-output
@defvrx {Constant} textual-output
@defvrx {Constant} binary-input/output
[SRFI-170]
@c MOD srfi.170
Constants to be used as @var{port-type} argument of
@code{open-file} and @code{fd->port}.
@end defvr

@defvr {Constant} buffer-none
@defvrx {Constant} buffer-block
@defvrx {Constant} buffer-line
[SRFI-170]
@c MOD srfi.170
Constants to be used as @var{buffer-mode} argument of
@code{open-file} and @code{fd->port}.
@end defvr

@defvr {Constant} open/append
@defvrx {Constant} open/create
@defvrx {Constant} open/exclusive
@defvrx {Constant} open/nofollow
@defvrx {Constant} open/truncate
[SRFI-170]
@c MOD srfi.170
Bitmask constants to be used as @var{flags} argument of
@code{open-file}.
@end defvr

@subheading File System

@defun create-directory fname :optional permission
@defunx create-fifo fname :optional permission
@defunx create-hard-link old-fname new-fname
@defunx create-symlink old-fname new-fname
[SRFI-170]
@c MOD srfi.170
Corresponds to Gauche's built-in @code{sys-mkdir}, @code{sys-mkfifo},
@code{sys-link} and @code{sys-symlink}.

The default value of @var{permission} is @code{#o775} for
@code{create-directory}, and @code{#o664} for @code{create-fifo}
(It's not optoinal for Gauche's built-in).

On Windows, @code{create-fifo} and @code{create-symlink} are
not supported.  Procedures exist, but raise an error when called.
@end defun

@defun read-symlink name
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-readlink}.
@end defun

@defun rename-file old new
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-rename}.
@end defun

@defun delete-directory name
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-rmdir}.  The directory must be empty.

To remove directory that may not be empty,
you can use @code{delete-directory*}
in @code{file.util} (@pxref{Directory utilities}).
@end defun

@defun set-file-owner fname uid gid
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-chown}.  The @var{uid} and @var{gid} arguments
should be an integer uid/gid, or the value of the constant
@code{owner/unchanged} and @code{group/unchanged}, respectively,
to indicate to keep the original value.
@end defun

@defvr {Constant} owner/unchanged
@defvrx {Constant} group/unchanged
[SRFI-170]
@c MOD srfi.170
Constants to be passed as @var{uid} and @var{gid} arguments
of @code{set-file-owner}, respectively.
@end defvr


@defun set-file-times funame :optional atime mtime
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-utime}.  The @var{atime} and @var{mtime}
arguments must be a @code{<time>} object (@pxref{Time}), or
either one of the values of constants @code{time/now} or
@code{time/unchanged}.  The constant @code{time/now}
indicates the time when the procedure is called,
and the constant @code{time/unchanged} indicates the
corresponding timestamp remains the same.
@end defun

@defvr {Constant} time/now
@defvrx {Constant} time/unchanged
[SRFI-170]
@c MOD srfi.170
Constants that can be passed to @var{atime} and @var{mtime}
arguments of @code{set-file-times}.
@end defvr

@defun truncate-file fname-or-port len
[SRFI-170]
@c MOD srfi.170
The first argument can be a string filename or a open port associated
to a file.  If it is a filename, @code{sys-truncate} is called,
and if it is a port, @code{sys-ftruncate} is called.
@end defun

@defun file-info fname-or-port follow?
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-stat}, @code{sys-lstat} or @code{sys-fstat}.

The first argument can be a string filename or a open port associated
to a file.  If it is a filename, @code{sys-stat} or @code{sys-lstat}
is called depending on whether @var{follow?} is @code{#t} or @code{#f}.
If it is a port, @code{sys-fstat} is called.

Returns a file-info object, which is a @code{<sys-stat>} instance
in Gauche (@pxref{File stats}).
@end defun

@defun file-info? obj
[SRFI-170]
@c MOD srfi.170
Returns @code{#t} iff @var{obj} is a file-info object, which is
a @code{<sys-stat>} instance in Gauche (@pxref{File stats}).
@end defun

@defun file-info:device file-info
@defunx file-info:inode file-info
@defunx file-info:mode file-info
@defunx file-info:nlinks file-info
@defunx file-info:uid file-info
@defunx file-info:gid file-info
@defunx file-info:rdev file-info
@defunx file-info:size file-info
@defunx file-info:blksize file-info
@defunx file-info:blocks file-info
@defunx file-info:atime file-info
@defunx file-info:mtime file-info
@defunx file-info:ctime file-info
[SRFI-170]
@c MOD srfi.170
Accessorso of file-info object (@code{<sys-stat>}) (@pxref{File stats}).
Access its @code{dev}, @code{ino}, @code{mode}, @code{nlink},
@code{uid}, @code{gid}, @code{rdev}, @code{size},
@code{blksize}, @code{blocks}, @code{atim}, @code{mtim}, @code{ctim}
slots, respectively.

Note: @code{<sys-stat>}'s @code{atime}, @code{mtime} and @code{ctime}
contains integer for the backward compatibility, while
@code{file-info:atime}, @code{file-info:mtime} and @code{file-info:ctime}
returns @code{<time>} object.
@end defun

@defun file-info-directory? file-info
@defunx file-info-fifo? file-info
@defunx file-info-symlink? file-info
@defunx file-info-regular? file-info
@defunx file-info-socket? file-info
@defunx file-info-device? file-info
[SRFI-170]
@c MOD srfi.170
Returns true iff the file-info object (@code{<sys-stat>} is of the
respective type.  (@code{file-info-device?} returns true if
the file is either block or character device).
It corresponds to the @code{type} slot of @code{<sys-stat>}.
@end defun

@defun set-file-mode fname mode-bits
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-chmod}.
@end defun

@defun directory-files dir :optional dotfiles?
[SRFI-170]
@c MOD srfi.170
Returns a list of filenames in the directory named @var{dir}.
Similar to @code{directory-list} in @code{file.util}
(@pxref{Directory utilities}), but (1) it never includes
@code{.} and @code{..} (as true value is given to @code{:children?}
argument of @code{directory-list}), and (2) it doesn't include
files beginning with @code{.} by default, unless @code{dotfiles?} is true.
@end defun

@defun make-directory-files-generator dir :optional dotfiles?
[SRFI-170]
@c MOD srfi.170
Returns a generator (@pxref{Generators}) that generates file names
in the directory named @var{dir}.  The names never include
@code{.} and @code{..}, and the filenames beginning with @code{.} is
omitted unless @var{dotfiles?} is true.
@end defun

@defun open-directory dir :optional dotfiles?
@defunx read-directory dir-object
@defunx close-directory dir-object
[SRFI-170]
@c MOD srfi.170
This is a directory scanner API more close to POSIX @code{opendir},
@code{readdir} and @code{closedir}.  A directory object is opened
with @code{open-directory}, and its entries (filenames) can be read
one by one using @code{read-directory}.  If the file names are exausted,
@code{read-directory} returns an EOF object.  A directory object
must be closed with @code{close-directory}.

The filenames to be retrieved are the same as @code{directory-files}; that is,
@code{.} and @code{..} are never included, and names beginning with @code{.}
is exluded unless @var{dotfiles?} is true.
@end defun

@defun real-path path
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-realpath}.
@end defun

@defun file-space path-or-port
[SRFI-170]
@c MOD srfi.170
Returns the free space of a file system where a file specified by
@var{path-or-port} resides, in number of bytes.
@end defun

@deffn {Parameter} temp-file-prefix
[SRFI-170]
@c MOD srfi.170
A parameter holding a path prefix to be used by @code{create-temp-file}
and @code{call-with-temporary-filename}.  In Gauche,
the default value is set to
@code{(build-path (temporary-directory) (x->string (sys-getpid)))}.
@xref{Temporary files and directories}, for the description of
@code{temporary-directory}.
@end deffn

@defun create-temp-file :optional prefix
[SRFI-170]
@c MOD srfi.170
@end defun

@defun call-with-temporary-filename maker :optional prefix
[SRFI-170]
@c MOD srfi.170
@end defun

@subheading Process state

Note: For SRFI-170's @code{current-directory}, we reuse
@code{file.util}'s one.  @xref{Directory utilities}, for the description.

@defun umask
[SRFI-170]
@c MOD srfi.170
Returns the current umask value.
Gauche's @code{sys-umask} without argument.
@end defun

@defun set-umask! mask
[SRFI-170]
@c MOD srfi.170
Sets @var{mask}, which must be a nonnegative exact integer,
as the current umask.
Gauche's @code{sys-umask}, except that it returns unspecified value.
@end defun

@defun set-current-directory! dir
[SRFI-170]
@c MOD srfi.170
Sets the process's current working directory to @var{dir}.
Gauche's @code{sys-chdir}.
It can also be done with @code{current-working-directory} in @code{file.util}
(@pxref{Directory utilities}).
@end defun

@defun pid
[SRFI-170]
@c MOD srfi.170
Returns the current process id.  Gauche's @code{sys-getpid}.
@end defun

@defun nice :optional delta
[SRFI-170]
@c MOD srfi.170
Increments the current process's nice value by @var{delta}, which must
be an exact integer.  The lower the nice value is, the more chance
the process gets run.  If omitted, @var{delta} is assumed to be 1.
Gauche's @code{sys-nice}.
@end defun

@defun user-uid
@defunx user-gid
@defunx user-effective-uid
@defunx user-effecitve-gid
@defunx user-supplementary-gids
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-getuid}, @code{sys-getgid}, @code{sys-geteuid},
@code{sys-getegid}, and @code{sys-getgroups}, respectievly.
@end defun

@subheading User and group database access

@defun user-info uid-or-name
[SRFI-170]
@c MOD srfi.170
Returns a user-info object, which is a @code{<sys-passwd>} instance
in Gauche, of a user specified by @var{uid-or-name}, which must be
an exact integer uid or a string username.
If it is an uid, @var{sys-getpwuid} is called, and if it is a username
@code{sys-getpwnam} is called.
@end defun

@defun user-info? obj
[SRFI-170]
@c MOD srfi.170
Returns @code{#t} iff @var{obj} is a user-info object (@code{<sys-passwd>}).
@end defun

@defun user-info:name uinfo
@defunx user-info:uid uinfo
@defunx user-info:gid uinfo
@defunx user-info:home-dir uinfo
@defunx user-info:shell uinfo
@defunx user-info:full-name uinfo
[SRFI-170]
@c MOD srfi.170
Returns the value of @var{name}, @code{uid}, @code{gid}, @code{dir},
@code{shell} and @var{gecos} slots of a user-info object (@code{<sys-passwd})
@var{uinfo}.
@end defun

@defun user-info:parsed-full-name uinfo
[SRFI-170]
@c MOD srfi.170
@end defun

@defun group-info gid-or-name
[SRFI-170]
@c MOD srfi.170
Returns a group-info object, which is a @code{<sys-group>} instance
in Gauche, of a group specified by @var{gid-or-name}, which must be
an exact integer gid or a string groupname.
If it is an gid, @var{sys-getgrgid} is called, and if it is a groupname
@code{sys-getgrnam} is called.
@end defun

@defun group-info? obj
[SRFI-170]
@c MOD srfi.170
Returns @code{#t} iff @var{obj} is a group-info object (@code{<sys-group}).
@end defun

@defun group-info:name ginfo
@defunx group-info:gid ginfo
[SRFI-170]
@c MOD srfi.170
Returns the value of @code{name} and @code{gid} slot of a group info
(@code{<sys-group>}).
@end defun

@subheading Time

@defun posix-time
[SRFI-170]
@c MOD srfi.170
Same as @code{current-time} (@pxref{Time}).  Return value is a @code{<time>}
instance of @code{time-utc}.
@end defun

@defun monotonic-time
[SRFI-170]
@c MOD srfi.170
Returns a @code{<time>} instance of @code{time-monotonic}, representing
a elapsed time since an unspecified epoch.  It is guaranteed to monotonically
increasing during the lifetime of the process, even if the system clock
is modified.
@end defun

@subheading Environment variables

@xref{Accessing environment variables}, for getting environment variables.
This srfi defines the means to modify them.

@defun set-enviroment-variable! name value
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-setenv} with the third argument being @code{#t}
(overwrite the existing value).
@end defun

@defun delete-environment-variable! name
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-unsetenv}.
@end defun

@subheading Terminal device control

@defun terminal? port
[SRFI-170]
@c MOD srfi.170
Gauche's @code{sys-isatty}.
@end defun

@c ----------------------------------------------------------------------
@node Two safer subsets of R7RS, Hooks (srfi), POSIX API, Library modules - SRFIs
@section @code{srfi.172} - Two safer subsets of R7RS
@c NODE 二つの安全なR7RSサブセット, @code{srfi.172} - 二つの安全なR7RSサブセット

@deftp {Module} srfi.172
@deftpx {Module} srfi.172.functional
@mdindex srfi.172
@mdindex srfi.172.functional
@c EN
This module exports a subset of R7RS-small bindings that can be used
relatively safely in the quasi-sandbox environment.  To realize
a true sandbox, the runtime needs more measures such as preventing
resource hogging and the data structure that allows
loopholes from being passed to those procedures.
However, this module can be a good starting point.
@c JP
このモジュールは、R7RS-smallのうちほぼサンドボックスとして使えるような、
制限された比較的安全な束縛をエクスポートします。
「ほぼ」というのは、完全に安全なサンドボックスにするには束縛の制限以外の対策も
必要だからです。例えばリソースを無制限に消費するコードを走るのを防いだり、
渡すことでループホールが作られてしまうようなデータが渡らないようにする、等です。
このモジュールはそういった環境を作る起点として使えるでしょう。
@c COMMON

@c EN
The submodule @code{srfi.172.functional} further resricts exported
bindings to side-effect free ones.
@c JP
サブモジュール@code{srfi.172.functional}は、そこからさらに副作用の無い関数のみに
限定した束縛をエクスポートします。
@c COMMON

@c EN
The bindings exported by @code{srfi.172} are as follows:
@c JP
@code{srfi.172}がエクスポートする束縛は次のとおりです:
@c COMMON

@example
- * / + < <= = => > >= abs acos and angle append apply asin assoc assq
assv atan begin boolean? boolean=? bytevector bytevector?
bytevector-append bytevector-copy bytevector-copy!
bytevector-length bytevector-u8-ref bytevector-u8-set! caaaar
caaadr caaar caadar caaddr caadr caar cadaar cadadr cadar caddar
cadddr caddr cadr call/cc call-with-current-continuation
call-with-port call-with-values car case case-lambda cdaaar cdaadr
cdaar cdadar cdaddr cdadr cdar cddaar cddadr cddar cdddar cddddr
cdddr cddr cdr ceiling char? char<? char<=? char=? char>? char>=?
char->integer char-alphabetic? char-ci<? char-ci<=? char-ci=?
char-ci>? char-ci>=? char-downcase char-foldcase char-lower-case?
char-numeric? char-upcase char-upper-case? char-whitespace?
close-input-port close-output-port close-port complex? cond
cond-expand cons cos delay delay-force denominator digit-value do
dynamic-wind else eof-object eof-object? eq? equal? eqv? error
error-object? error-object-irritants error-object-message even?
exact exact? exact-integer? exact-integer-sqrt exp expt finite?
floor floor/ floor-quotient floor-remainder force for-each gcd
get-output-bytevector get-output-string guard if imag-part inexact
inexact? infinite? input-port? integer? integer->char lambda lcm
length let let* let*-values letrec letrec* let-values list list?
list->string list->vector list-copy list-ref list-set! list-tail
log magnitude make-bytevector make-list make-parameter make-polar
make-promise make-rectangular make-string make-vector map max
member memq memv min modulo nan? negative? newline not null?
number? number->string numerator odd? open-input-bytevector
open-input-string open-output-bytevector open-output-string or
output-port? pair? peek-char peek-u8 parameterize port? positive?
procedure? promise? quasiquote quote quotient raise
raise-continuable rational? rationalize read-bytevector
read-bytevector! read-char read-error? read-line read-string
read-u8 real? real-part remainder reverse round set! set-car!
set-cdr! sin sqrt square string string? string<? string<=?
string=? string>? string>=? string->list string->number
string->utf8 string->vector string-append string-ci<? string-ci<=?
string-ci=? string-ci>? string-ci>=? string-copy string-copy!
string-downcase string-fill! string-foldcase string-for-each
string-length string-map string-ref string-set! string-upcase
substring symbol? symbol=? symbol->string tan textual-port?
truncate truncate/ truncate-quotient truncate-remainder unless
unquote unquote-splicing utf8->string values vector vector?
vector->list vector->string vector-append vector-copy vector-copy!
vector-fill! vector-for-each vector-length vector-map vector-ref
vector-set! when with-exception-handler write-bytevector
write-char write-string write-u8 zero?
@end example

@c EN
The module @code{srfi.172.functional} exports the above bindings
except for:
@c JP
@code{srfi.172.functional}がエクスポートするのは、上のリストから
以下のものを除いた束縛です。
@c COMMON

@itemize @bullet
@item
@code{set!}
@item
@c EN
Procedures whose names end with @code{!}:
@c JP
@code{!}で終わる手続き:
@c COMMON
@code{bytevector-copy!}, @code{bytevector-u8-set!}, @code{list-set!},
@code{read-bytevector!}, @code{set-car!}, @code{set-cdr!},
@code{string-copy!}, @code{string-fill!}, @code{string-set!},
@code{vector-copy!}, @code{vector-fill!}, @code{vector-set!}
@item
@c EN
Procedures whose names contain @code{port}:
@c JP
@code{port}が含まれる手続き:
@c COMMON
@code{call-with-port}, @code{close-input-port},
@code{close-output-port}, @code{close-port}, @code{input-port?},
@code{output-port?}, @code{port?}, @code{textual-port?}
@item
@c EN
Procedures whose names begin with @code{read}:
@c JP
@code{read}で始まる手続き:
@c COMMON
@code{read-bytevector}, @code{read-bytevector!}, @code{read-char},
@code{read-error?}, @code{read-line}, @code{read-string},
@code{read-u8}
@item
@c EN
Procedures whose names begin with @code{peek}:
@c JP
@code{peek}で始まる手続き:
@c COMMON
@code{peek-char}, @code{peek-u8}
@item
@c EN
Procedures whose names begin with @code{write}:
@c JP
@code{write}で始まる手続き:
@c COMMON
@code{write-bytevector}, @code{write-char},
@code{write-string}, @code{write-u8}
@end itemize
@end deftp

@c ----------------------------------------------------------------------
@node Hooks (srfi), POSIX timespecs, Two safer subsets of R7RS, Library modules - SRFIs
@section @code{srfi.173} - Hooks (srfi)
@c NODE フック(srfi), @code{srfi.173} - フック(srfi)

@deftp {Module} srfi.173
@mdindex srfi.173
@c EN
This module provides hooks, which manages a list of
closures to be called.

It is based on Guile's hooks, which Gauche supports in
@code{gauche.hook} module (@pxref{Hooks}).  This srfi
is a thin layer on top of @code{gauche.hook}.

The following procedures are the same as @code{gauche.hook}:
@c JP
このモジュールは、呼ばれるべきクロージャのリストを管理する「フック」を提供します。

GaucheではもともとGuileにあったhookの仕様を
@code{gauche.hook}モジュールとして採り入れています
(@ref{Hooks}参照)。
このsrfiは@code{gauche.hook}に薄いレイヤをかぶせたものです。

以下の手続きは@code{gauche.hook}のものと同じです。
@c COMMON

@example
make-hook     hook?      hook->list
@end example
@end deftp

@defun hook-add! hook proc
[SRFI-173]
@c MOD srfi.173
@c EN
Add a procedure @var{proc} to a hook @var{hook}.   The procedure
must accept the number of arguments that matches the arity of the hook.
It is the same as @code{(add-hook! hook proc)} of @code{gauche.hook}.
@c JP
手続き@var{proc}をフック@var{hook}に追加します。手続きは、フックのアリティと
同じ数の引数を受け付けなければなりません。
これは@code{gauche.hook}の@code{(add-hook! hook proc)}と同じです。
@c COMMON
@end defun

@defun hook-delete! hook proc
[SRFI-173]
@c MOD srfi.173
@c EN
Delete @var{proc} from @var{hook}.  If @var{proc} isn't in @var{hook},
do nothing.  It is the same as @code{(delete-hook! hook proc)}
of @code{gauche.hook}.
@c JP
@var{proc}を@var{hook}から削除します。@var{proc}が@var{hook}に登録されていない
場合は何もしません。
@code{gauche.hook}の@code{(delete-hook! hook proc)}と同じです。
@c COMMON
@end defun

@defun hook-reset! hook
[SRFI-173]
@c MOD srfi.173
@c EN
Remove all the procedures registered in @var{hook}.
It is the same as @code{(reset-hook! hook)} of @code{gauche.hook}.
@c JP
@var{hook}に登録された全ての手続きを削除します。
@code{gauche.hook}の@code{(reset-hook! hook)}と同じです。
@c COMMON
@end defun

@defun hook-run hook args @dots{}
[SRFI-173]
@c MOD srfi.173
@c EN
Apply all the procedures from @var{hook} to the @var{args}.
The order of the procedure isn't specified in the srfi, though
Gauche preserves the order (see @code{run-hook}
(@pxref{Hooks}).
@c JP
@var{hook}に登録された手続き全てを順次、@var{args}を引数として呼び出します。
srfiでは手続きを呼び出す順番は指定されていません。
Gaucheは登録された順序で呼び出します
(@ref{Hooks}の@code{run-hook}参照)。
@c COMMON
@end defun

@defun list->hook arity list
[SRFI-173]
@c MOD srfi.173
@c EN
Creates a new hook with specified @var{arity} (which is a non-negative
exact integer), which has the procedures in @var{list}.
All the procedures must accept @var{arity} number of arguments.
@c JP
アリティ@var{arity} (非負の正確な整数) を持つフックを作り、
手続きのリスト@var{list}中の手続きをフックに登録して、そのフックを返します。
全ての手続きは@var{arity}個の引数を受け付けなくてはなりません。
@c COMMON
@end defun

@defun list->hook! hook list
[SRFI-173]
@c MOD srfi.173
@c EN
Replace the list of procedures in @var{hook} with procedures
in @var{list}.
All the procedures must accept the number of arguments
the same as @var{hook}'s arity.
@c JP
フック@var{hook}に登録された手続きのリストを、@var{list}にある手続きと
置き換えます。
全ての手続きは@var{arity}個の引数を受け付けなくてはなりません。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node POSIX timespecs, ASCII character library, Hooks (srfi), Library modules - SRFIs
@section @code{srfi.174} - POSIX timespecs

@deftp {Module} srfi.174
@mdindex srfi.174
@c EN
Note: This srfi is originally intended to be used with SRFI-170
(@pxref{POSIX API}), but it turned out this was not enough to support
the latter--notably, we need SRFI-19 type argument in the constructor.
@c JP
註: このsrfiはSRFI-170 (@ref{POSIX API}参照)で使うための補助ライブラリとして
作られたのですが、その後の議論で不十分であることがわかりました。
特に、SRFI-19の時間の型をコンストラクタで指定することが不可欠だとわかったのです。
@c COMMON

@c EN
Consequently, it is likely that this srfi will be superseded later.
We deprecate using this srfi; if you need a portable time representation,
SRFI-19 is the best choice at this moment.  @xref{Time data types and procedures},
for the details.
@c JP
従って、このsrfiは将来のsrfiで置き換えられる可能性が高く、使用は非推奨です。
ポータブルな時間の表現が必要であれば、SRFI-19を使ってください
(@ref{Time data types and procedures}参照)。
@c COMMON
@end deftp

@defun timespec secs nsecs
[SRFI-174]
@c MOD srfi.174
Creates and returns a timespec, whose second part is @var{secs} and
nanosecond part is @var{nsecs}.  The second part must be an exact
integer; if it is positive, it's the number of seconds since
Epoch (Jan 1, 1970 UTC), and if it's negative, it's before the Epoch.
The nanosecond part is a nonnegative integer less than 1e9, and represents
the fraction of seconds in nanosecond resolution.  Note that if the second
part is negative, the nanosecond part counts toward past.

This is the same as @code{(make-time time-utc nsecs secs)} of
SRFI-19.  Note the order of arguments.
@end defun

@defun timespec? obj
[SRFI-174]
@c MOD srfi.174
Returns @code{#t} iff @var{obj} is a @code{<time>} object.  It doesn't
check the type of time.
@end defun

@defun timespec-seconds ts
@defunx timespec-nanosecods ts
[SRFI-174]
@c MOD srfi.174
Returns second and nanosecond part of the @code{<time>} object.
Same as @code{time-second} and @code{time-nanosecond} of SRFI-19
(note that we use plurals in this srfi).
@end defun

@defun inexact->timespec v
[SRFI-174]
@c MOD srfi.174
Convert an inexact real number @var{v} to a timespec.  The integral part
of @var{v} is the seconds after (when @var{v} is positive)
or before (when @var{v} is negative) the Epoch, and the fractional part
is rounded into nanosecond resolution.
@end defun

@defun timespec->inexact ts
[SRFI-174]
Convert a timespec into an inexact real number in seconds.
@c MOD srfi.174
@end defun

@defun timespec=? ts1 ts2
[SRFI-174]
@c MOD srfi.174
Returns @code{#t} iff two timespecs are the same.
It is the same as @code{time=?} in SRFI-19.
@end defun

@defun timespec<? ts1 ts2
[SRFI-174]
@c MOD srfi.174
Returns @code{#t} iff a timespec @var{ts1} is strictly before
the timespec @var{ts2}.  It is the same as @code{time<?} in SRFI-19.
@end defun

@defun timespec-hash ts
[SRFI-174]
@c MOD srfi.174
Compute a hash value of a timespec @var{ts}.  It is same as
passing a @code{<time>} object to @code{default-hash}, and
affected by the current hash salt value (@pxref{Hashing}).
@end defun

@c ----------------------------------------------------------------------
@node ASCII character library, Bitvector library, POSIX timespecs, Library modules - SRFIs
@section @code{srfi.175} - ASCII character library
@c NODE ASCII文字ライブラリ, @code{srfi.175} - ASCII文字ライブラリ

@deftp {Module} srfi.175
@mdindex srfi.175
@c EN
This module provides a set of character/string utilities that deal with
ASCII characters and codepoints.  It is particulary useful for small
Scheme implementations that only handles, and a portable
code that only concerns, ASCII characters.
@c JP
ASCII文字とASCIIコードポイントを扱うユーティリティを提供するモジュールです。
ASCIIだけを対象とする小さなScheme実装や、ASCIIだけを対象とするポータブルな
コードを書きたい場合に便利です。
@c COMMON

@c EN
Since Gauche supports full Unicode, you may not need to use this module
to write Gauche-specific code.  This is mainly for the compatibility.
@c JP
GaucheはUnicodeの全ての文字を扱えるので、Gauche用のコードを書いている時には
敢えてこのモジュールを使う必要は無いでしょう。互換性のために用意しています。
@c COMMON

@c EN
One of the characteristics of this module is that many procedures can
take an integer in place of a character; an integer between 0 and 127
is interpreted as an ASCII codepoint.  An integer outside the range
is interpreted as an non-ASCII codepoint.  Such argument is noted
as @var{char-or-code} in the description.  It is handy while you're
dealing with a binary file which may contain some ASCII text in it.
@c JP
このモジュールに特徴的なのは、多くの手続きで、文字のかわりに整数を取れることです。
0と127の間の正確な整数はASCIIコードポイントと解釈されます。
それ以外の整数は非ASCIIコードポイントと解釈されます。
文字と整数の両方を取れる引数は、@var{char-or-code}と表記しています。
例えばバイナリファイルの一部にASCIIテキストが含まれるものを扱う際に便利でしょう。
@c COMMON
@end deftp

@defun ascii-codepoint? obj
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{obj} is an exact integer between 0 and 127,
inclusive.
@c JP
@var{obj}が0..127の範囲の正確な整数であれば@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun ascii-bytevecotr? obj
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{obj} is a bytevector (@code{u8vector}) and
all of its elements are between 0 and 127, inclusive.
@c JP
@var{obj}がバイトベクタ(@code{u8vector})で、全ての要素が0..127の範囲に収まっていれば
@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun ascii-char? obj
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{obj} is an ASCII character.
@c JP
@var{obj}がASCII文字であれば@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun ascii-string? obj
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{obj} is a string and all of its elements
are ASCII characters.
@c JP
@var{obj}が文字列で、その中の全ての文字がASCII文字なら@code{#t}を、そうでなければ
@code{#f}を返します。
@c COMMON
@end defun

@defun ascii-control? char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{char-or-code} is in the range of
ASCII control characters
@c JP
@var{char-or-code}がASCII制御文字の範囲なら@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON

@example
(ascii-control? #\tab) @result{} #t
(ascii-control? #\A)   @result{} #f

(ascii-control? 127)   @result{} #t
(ascii-control? 255)   @result{} #f
@end example

@c EN
Note: The accepted character range corresponds to
@code{char-set:ascii-control} (@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は@code{char-set:ascii-control}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-non-control? char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{char-or-code} is in the range of ASCII but
not a control character.
@c JP
@var{char-or-code}がASCIIの範囲でかつ制御文字でなければ@code{#t}を、
そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun ascii-space-or-tab? char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{char-or-code} is a tab or a whitespace.
@c JP
@var{char-or-code}がタブ文字かASCII空白文字であれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun ascii-other-graphic? char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{char-or-code} is in the range of ASCII
graphic characters but not a letter nor a digit.
@c JP
@var{char-or-code}がASCIIの範囲で、アルファベットと数字以外の
グラフィック文字であれば@code{#t}を返します。
@c COMMON

@c EN
Note: The accepted character range corresponds to
@code{(char-set-difference char-set:ascii-graphic char-set:ascii-letter+digit)}
(@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は
@code{(char-set-difference char-set:ascii-graphic char-set:ascii-letter+digit)}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-alphanumeric? char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{char-or-code} is in the ASCII alphabet or digit
range.
@c JP
@var{char-or-code}がASCIIアルファベットか数字であれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON

@c EN
Note: The accepted character range corresponds to
@code{char-set:ascii-letter+digit}
(@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は
@code{char-set:ascii-letter+digit}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-alphabetic? char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{#t} iff @var{char-or-code} is in the ASCII alphabet range.
@c JP
@var{char-or-code}が
@c COMMON

@c EN
Note: The accepted character range corresponds to
@code{char-set:ascii-letter}
(@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は
@code{char-set:ascii-letter}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-numeric? char-or-code
[SRFI-175]
@c MOD srfi.175
Returns @code{#t} iff @var{char-or-code} is in the ASCII digit range.

@c EN
Note: The accepted character range corresponds to
@code{char-set:ascii-digit}
(@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は
@code{char-set:ascii-digit}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-whitespace? char-or-code
[SRFI-175]
@c MOD srfi.175
Returns @code{#t} iff @var{char-or-code} is one of the ASCII whitespaces.

@c EN
Note: The accepted character range corresponds to
@code{char-set:ascii-whitespace}
(@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は
@code{char-set:ascii-whitespace}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-upper-case? char-or-code
@defunx ascii-lower-case? char-or-code
[SRFI-175]
@c MOD srfi.175
Returns @code{#t} iff @var{char-or-code} is one of upper/lower case
ASCII alphabets.

@c EN
Note: The accepted character range corresponds to
@code{char-set:ascii-upper-case}/@code{char-set:ascii-lower-case}
(@pxref{Predefined character sets}).
@c JP
@code{#t}が返される文字の集合は
@code{char-set:ascii-upper-case}/@code{char-set:ascii-lower-case}と
一致します (@ref{Predefined character sets}参照)。
@c COMMON
@end defun

@defun ascii-ci=? char-or-code1 char-or-code2
@defunx ascii-ci<? char-or-code1 char-or-code2
@defunx ascii-ci<=? char-or-code1 char-or-code2
@defunx ascii-ci>? char-or-code1 char-or-code2
@defunx ascii-ci>=? char-or-code1 char-or-code2
[SRFI-175]
@c MOD srfi.175
@c EN
Each argument may be a character or a codepoint.  If the argument
falls into ASCII upper case letters, it is converted to the corresponding
lower case letter codepoint, and then two are compared as codepoints.
Two arguments don't need to be of the same type.
@c JP
各引数は文字かコードポイントです。引数がASCIIの大文字に相当する場合、それは対応する小文字の
コードポイントに変換され、その後コードポイント同士の比較結果が返されます。
二つの引数の型が一致している必要はありません。
@c COMMON

@c EN
It is allowed to pass non-ascii range; if it is a non-ASCII character,
its codepoint of the native encoding is taken (no case-folding is considered),
and compared as codepoints.  Of course the result are not portable, except
that any non-ASCII character has a codepoint greater than any ASCII characters.
@c JP
ASCII範囲外の引数を渡すことは許されます。非ASCII文字は内部エンコーディングによるコードポイント
に変換されます(大文字小文字は考慮されません)。非ASCII文字はASCII文字より大きい、
ということ以外、結果は処理系依存になります。
@c COMMON
@end defun

@defun ascii-string-ci=? string1 string2
@defunx ascii-string-ci<? string1 string2
@defunx ascii-string-ci<=? string1 string2
@defunx ascii-string-ci>? string1 string2
@defunx ascii-string-ci>=? string1 string2
[SRFI-175]
@c MOD srfi.175
@c EN
Compares two strings with ASCII case folding.   Argument strings may
contain non-ASCII characters; such characters are compared without
case folding.
@c JP
ASCII文字の範囲で大文字小文字を考慮せずに、二つの文字列を比較します。
文字列は非ASCII文字を含んでいても構いません。それらについては大文字小文字の考慮はせず、
内部エンコーディングのコードポイントを使って比較します。
@c COMMON
@end defun

@defun ascii-upcase char-or-code
@defunx ascii-downcase char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
If the argument represents a ASCII upper/lower case letter,
returns the corresponding lower/upper case character or codepoint.
The type of the return value is the same as the argument.
If the argument is a character or a codepoint other than that,
it is returned as is.
@c JP
引数がASCIIの大文字/小文字に相当する場合、対応する小文字/大文字の文字またはコードポイントを
返します。戻り値は引数と同じ型になります。
引数がそれ以外の文字に相当する場合は、そのまま返されます。
@c COMMON
@end defun

@defun ascii-control->graphic char-or-code
@defunx ascii-graphic->control char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
ASCII control characters (@code{#\x00}, @code{#\x01} .. @code{#\x1f},
and @code{#\x7f})
are sometimes noted as @code{^@@}, @code{^A} .. @code{^_}, and @code{^?}.
These procedures converts the control character and corresponding
graphical character (the one comes after @code{^}), and vice versa.
The type of the return value is the same as the argument.
@c JP
ASCII制御文字(@code{#\x00}, @code{#\x01} .. @code{#\x1f},
and @code{#\x7f})はしばしば、
@code{^@@}, @code{^A} .. @code{^_} および @code{^?} のように
表記されます。これらの手続きは、制御文字とその表記 (@code{^}の後に来る文字)とを
相互に変換するものです。
戻り値の型は引数と同じになります。
@c COMMON

@c EN
If the argument isn't an ASCII control character / a graphical character
that corresponds to an ASCII control character, @code{#f} is returned.
@c JP
引数がASCII制御文字/制御文字に対応するASCII表示文字でなければ、@code{#f}が返ります。
@c COMMON
@end defun

@defun ascii-mirror-bracket char-or-code
[SRFI-175]
@c MOD srfi.175
@c EN
There are four pairs of brackets in ASCII: @code{(} and @code{)},
@code{@{} and @code{@}}, @code{[} and @code{]}, and @code{<} and @code{>}.
If @var{char-or-code} is either one of these eight chars or codepoints,
returns the corresponding bracket.
The type of the return value is the same as the argument.
@c JP
ASCIIには4ペアの括弧があります。@code{(}と@code{)}、
@code{@{}と@code{@}}、@code{[}と@code{]}、そして@code{<}と@code{>}です。
引数@var{char-or-code}がこれら8文字のいずれかに相当する場合に、
それと対になる文字またはコードポイントを返します。
戻り値の型は引数と同じになります。
@c COMMON

@c EN
If the argument is a char or a codepoint other than those brackets,
@code{#f} is returned.
@c JP
引数が括弧の文字またはコードポイントでなければ、@code{#f}が返されます。
@c COMMON
@end defun

@defun ascii-nth-digit n
[SRFI-175]
@c MOD srfi.175
@c EN
Returns a digit character representing the number @var{n}.
If @var{n} is not an exact integer between 0 and 9, inclusive,
@code{#f} is returned.
@c JP
数値@var{n}を表すASCII数字文字を返します。@var{n}が0から9までの正確な整数でない
場合は@code{#f}を返します。
@c COMMON

@example
(ascii-nth-digit 3) @result{} #\3
@end example

@c EN
See also @code{integer->digit} (@pxref{Characters}).
@c JP
@code{integer->digit} (@ref{Characters})も参照。
@c COMMON
@end defun

@defun ascii-nth-upper-case n
@defunx ascii-nth-lower-case n
[SRFI-175]
@c MOD srfi.175
@c EN
Returns @code{(modulo @var{n} 26)}-th character of upper/lower case
ASCII alphabet.
@c JP
@code{(modulo @var{n} 26)}番目のASCII大文字/小文字アルファベットを返します。
@c COMMON

@example
(ascii-nth-upper-case 0) @result{} #\A
(ascii-nth-lower-case 1) @result{} #\b

(ascii-nth-upper-case 25) @result{} #\Z
(ascii-nth-lower-case 26) @result{} #\a
@end example

@c EN
See also @code{integer->digit} (@pxref{Characters}).
@c JP
@code{integer->digit} (@ref{Characters})も参照。
@c COMMON
@end defun

@defun ascii-digit-value char-or-code limit
[SRFI-175]
@c MOD srfi.175
@c EN
If @var{char-or-code} represents an ASCII decimal digits and
the corresponding number is less than @var{limit},
returns the number.  Otherwise, returns @code{#f}.
@c JP
@var{char-or-code}がASCII数字文字またはそのコードポイントであり、
それが表す数値が@var{limit}未満であればその数値を、
そうでなければ@code{#f}を返します。
@c COMMON

@example
(ascii-digit-value #\5 10) @result{} 5
(ascii-digit-value #\9 8)  @result{} #f

(ascii-digit-value 48 10)  @result{} 0
@end example

@c EN
See also @code{digit->integer} (@pxref{Characters}).
@c JP
@code{digit->integer} (@ref{Characters})も参照。
@c COMMON
@end defun

@defun ascii-upper-case-value char-or-code offset limit
@defunx ascii-lower-case-value char-or-code offset limit
[SRFI-175]
@c MOD srfi.175
@c EN
If @var{char-or-code} is n-th ASCII upper/lower case alphabet,
and @var{n} is less than @var{limit}, returns @code{(+ @var{n} @var{offset})}.
Otherwise returns @code{#f}.
@c JP
@var{char-or-code}がn番目のASCII大文字/小文字またはそのコードポイントで、
nが@var{limit}未満であれば、@code{(+ @var{n} @var{offset})}を返します。
そうでなければ@code{#f}を返します。
@c COMMON

@example
(ascii-upper-case-value #\E 10 6) @result{} 14
(ascii-lower-case-value #\z 0 26) @result{} 25
@end example

@c EN
See also @code{digit->integer} (@pxref{Characters}).
@c JP
@code{digit->integer} (@ref{Characters})も参照。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Bitvector library, JSON, ASCII character library, Library modules - SRFIs
@section @code{srfi.178} - Bitvector library
@c NODE ビットベクタライブラリ, @code{srfi.178} - ビットベクタライブラリ

@deftp {Module} srfi.178
@mdindex srfi.178
@c EN
Gauche supports all SRFI-178 operations by built-in procedures
and the module @code{gauche.bitvector}.
@c JP
GaucheはSRFI-178の全ての手続きを、組み込みか@code{gauche.bitvector}モジュールでサポートしています。
@c COMMON

@c EN
The following procedures are built-in.  @xref{Bitvectors}, for the description.
@c JP
以下の手続きは組み込みです。@ref{Bitvectors}を参照してください。
@c COMMON

@example
bit->integer      bit->boolean
bitvector         make-bitvector     list->bitvector
bitvector?        bitvector-length
string->bitvector bitvector->string
bitvector-ref/int bitvector-ref/bool
bitvector-set!    bitvector-copy     bitvector-copy!
@end example

@c EN
The following procedures are provided in @ref{Bitvector utilities}.
@c JP
以下の手続きは@ref{Bitvector utilities}で説明されます。
@c COMMON

@example
bitvector-unfold  bitvector-unfold-right  bitvector-reverse-copy
bitvector-append  bitvector-concatenate   bitvector-append-subbitvectors
bitvector-emtpy?  bitvector=?
bitvector-take    bitvector-take-right
bitvector-drop    bitvector-drop-right
bitvector-segment
bitvector-fold/int       bitvector-fold/bool
bitvector-fold-right/int bitvector-fold-right/bool
bitvector-map/int        bitvetor-map/bool
bitvector-map!/int       bitvetor-map!/bool
bitvector-map->list/int  bitvector-map->list/bool
bitvector-for-each/int   bitvector-for-each/bool
bitvector-prefix-length  bitvector-suffix-length
bitvector-prefix?        bitvector-suffix?
bitvector-pad            bitvector-pad-right
bitvector-trim           bitvector-trim-right        bitvector-trim-both
bitvector-swap!          bitvector-reverse!          bitvector-reverse-copy!
bitvector->list/int      bitvector->list/bool
reverse-bitvector->list/int reverse-bitvector->list/bool
reverse-list->bitvector
bitvector->vector/int    bitvector->vector/bool
reverse-bitvector->vector/int reverse-bitvector->vector/bool
vector->bitvector        reverse-vector->bitvector
bitvector->integer
integre->bitvector
make-bitvector/int-generator make-bitvector/bool-generator
make-bitvector-accumulator
bitvector-not            bitvector-not!
bitvector-and            bitvector-and!
bitvector-ior            bitvector-ior!
bitvector-xor            bitvector-xor!
bitvector-eqv            bitvector-eqv!
bitvector-nand           bitvector-nand!
bitvector-nor            bitvector-nor!
bitvector-andc1          bitvector-andc1!
bitvector-andc2          bitvector-andc2!
bitvector-orc1           bitvector-orc1!
bitvector-orc2           bitvector-orc2!
bitvector-logical-shift
bitvector-count          bitvector-count-run
bitvector-if
bitvector-first-bit
bitvector-field-any?     bitvector-field-every?
bitvector-field-clear    bitvector-field-clear!
bitvector-field-set      bitvector-field-set!
bitvector-field-replace  bitvector-field-replace!
bitvector-field-replace-same bitvector-field-replace-same!
bitvector-field-rotate
bitvector-field-flip     bitvector-field-flip!
@end example
@end deftp

@c ----------------------------------------------------------------------
@node JSON, Custom ports, Bitvector library, Library modules - SRFIs
@section @code{srfi.180} - JSON

@deftp {Module} srfi.180
@mdindex srfi.180
@c EN
This srfi defines the means of parsing and constructin JSON.

In Gauche, this module is implemented on top of @code{rfc.json} module
(@pxref{JSON parsing and construction}).
Notably, the parameter @code{json-nesting-depth-limit} is the same
as the one in @code{rfc.json}.
@c JP
このsrfiはJSONフォーマットをパーズ、および構築する手段を定義します。

Gaucheでは、このモジュールは@code{rfc.json}の上に実装されています
(@ref{JSON parsing and construction}参照)。
特に、@code{json-nesting-depth-limit}パラメータは@code{rfc.json}のものと同じです。
@c COMMON

@c EN
Gauche's @code{rfc.json} is more flexible in terms of mapping
JSON objects to Scheme objects.  On the other hand, @code{srfi.180}
provides a streaming parser/generator, which allows the caller
to process input as it is read, instead of waiting the entire
input to be parsed.
@c JP
Gaucheの@code{rfc.json}は、JSONオブジェクトとSchemeオブジェクト間のマッピングを
カスタマイズできるという点でより柔軟です。一方、
@code{srfi.180}はストリーミングパーザとジェネレータを提供しており、
入力を全て読んでからパーズ結果を得るのではなく、入力を読みながら処理することができます。
@c COMMON
@end deftp

@c EN
@subheading Predicates and parameters
@c JP
@subheading 述語とパラメータ
@c COMMON

@defun json-error? obj
[SRFI-180]
@c MOD srfi.180
@c EN
JSON reader and writer raise a condition that satisfies
this predicate when it encounters invalid JSON syntax and/or object,
or the input exceeds the limits specified by
@code{json-nesting-depth-limit} or
@code{json-number-of-character-limit} parameters.
@c JP
JSONのリーダとライターは、不正なJSON構文や、JSONで表現できないオブジェクトに
行き当たった場合、あるいは入力がパラメータ@code{json-nesting-depth-limit}や
や@code{json-number-of-character-limit}で示される限度を越えた場合に、
この述語を満たすコンディションオブジェクトを投げます。
@c COMMON

@c EN
Since @code{srfi.180} is implemented on top of @code{rfc.json},
which raises a condition @code{<json-parse-error>} for input and
@code{<json-construct-error>} for the output, this predicate simply
returns @code{#t} iff @var{obj} is an instance of either class.
@xref{JSON parsing and construction}, for the detail of these conditions.
@c JP
Gaucheでは@code{srfi.180}は@code{rfc.json}上に実装されていて、
@code{rfc.json}はパーズ時のエラーには@code{<json-parse-error>}を、
構築時のエラーには@code{<json-construct-error>}を投げるので、
この述語は@var{obj}がそれらのクラスのどちらかのインスタンスであれば
@code{#t}を返します。
これらのコンディションについては@ref{JSON parsing and construction}を参照してください。
@c COMMON
@end defun

@defun json-error-reason err
[SRFI-180]
@c MOD srfi.180
@c EN
Returns a string explaining the reason for the error @var{err},
if @var{err} is a JSON error object (an object that satisfies
@code{json-error?}).
@c JP
@var{err}がJSONエラーオブジェクト (@code{json-error?}を満たすオブジェクト)
であった場合、エラーの理由を説明する文字列を返します。
@c COMMON

@c EN
In Gauche, a JSON error object is an instance of either
@code{<json-parse-error>} or @code{<json-construct-error>})
conditions, and @code{json-error-reason} simply returns the content of
its @code{message} slot.
@c JP
GaucheではJSONエラーオブジェクトは@code{<json-parse-error>}か
@code{<json-construct-error>}コンディションタイプのインスタンスであり、
@code{json-error-reason}は単にコンディションオブジェクトの@code{message}スロットの
値を返します。
@c COMMON
@end defun

@defun json-null? obj
[SRFI-180]
@c MOD srfi.180
@c EN
Returns @code{#t} iff @var{obj} is the symbol @code{null}.
@c JP
@var{obj}がシンボル@code{null}であれば@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@deffn {Parameter} json-number-of-character-limit
[SRFI-180]
@c MOD srfi.180
@c EN
A parameter that holds a real value.  If the number of characters
of input JSON text exceeds the value while @code{json-generator},
@code{json-fold} or @code{json-read} is processing the input,
a JSON error is thrown.
@c JP
実数を値に持つパラメータです。@code{json-generator}、@code{json-fold}、
および@code{json-read}で入力のJSONテキストの文字数がこの値を越えた場合、
JSONエラーが投げられます。
@c COMMON
@end deffn

@c EN
@subheading JSON reader
@c JP
@subheading JSONリーダ
@c COMMON

@defun json-generator :optional port-or-generator
[SRFI-180]
@c MOD srfi.180
@c EN
Streaming parser.  The input @var{port-or-generator} must be
an input port, or a char generator.
@c JP
ストリーミングパーザ。
@var{port-or-generator}は入力ポートか、文字のジェネレータでなければなりません。
@c COMMON

@c EN
Each time it is called, it returns one of the following values, parsed
from the input.
@c JP
この手続きは、呼ばれる度に、必要なだけ入力を読んで次のいずれかの値を返します。
@c COMMON

@c EN
@table @asis
@item string
JSON string.
@item real number
JSON number.
@item @code{#t}, @code{#f}
JSON @code{true} and @code{false}
@item @code{null}
JSON @code{null}
@item @code{array-start}
The beginning of an array.  What follows is the array's element,
up to the matching @code{array-end}.
@item @code{array-end}
The ending of an array.
@item @code{object-start}
The beginning of an object.  What follows is alternating
string keys and JSON values, up to the matching @code{object-end}.
@item @code{object-end}
The ending of an object.
@item EOF
After one top-level JSON value is read, the generator returns EOF.
@end table
@c JP
@table @asis
@item 文字列
JSON文字列
@item 実数
JSON数値
@item @code{#t}, @code{#f}
JSONの@code{true}と@code{false}
@item @code{null}
JSONの@code{null}
@item @code{array-start}
配列の開始。次に対応する@code{array-end}が出てくるまで、
配列の要素をストリーミングで返す。
@item @code{array-end}
配列の終了。
@item @code{object-start}
オブジェクトの開始。この後、文字列のキーとJSONの値が交互に返される。
終了は@code{object-end}で示される。
@item @code{object-end}
オブジェクトの終了。
@item EOF
ひとつのトップレベルのJSON値が全て読まれたら、ジェネレータはEOFを返す。
@end table
@c COMMON


The generator internally tracks the state, and raises
@code{<json-parse-error>} when the input contains invalid JSON text.
See also @code{json-error?} above.

If the input contains more than one toplevel JSON value, you have to
call @code{json-generator} after the previous generator is exhausted.

Note that if a toplevel JSON value is a number, @code{true}, @code{false}
or @code{null}, the parser need to read one character ahead to recognize
the value.  So the subsequent call of @code{json-generator} won't read
a character immediately following those values.

Generally, multiple toplevel values uses delimiters for each values
so it won't be an issue.  See @code{json-lines-read} and
@code{json-sequence-read} below.
@end defun

@defun json-fold proc array-start array-end object-start object-end seed :optional port-or-generator
[SRFI-180]
@c MOD srfi.180
A procedure to translate JSON pasring result to Scheme object on the fly.

The @var{port-or-generator} argument is either an input port,
or a char generator, defaulted to the current input port.
It is first passed to @code{json-generator} to
get a generator of parser events.  Then, @code{json-fold} retrieves
value from the generator and take one of the following actions:

@itemize
@item
If it generates a string, a number, a boolean or @code{null},
calls @code{(proc obj seed)} where @var{obj} is the generated value
and @var{seed} is the current seed value, and make the result a new seed value.
@item
If it generates @code{array-start}, save the current seed, calls
@code{(array-start seed)} and make the result a new seed value.
@item
If it generates @code{array-end}, calls @code{(array-end seed)}, let
the result be @var{arr}, recover the seed value saved
at the corresponding @code{array-start}, and calls
@code{(proc arr recovered-seed)}.  Let the result a new seed value.
@item
If it generates @code{object-start}, save the current seed, calls
@code{(object-start seed)} and make the result a new seed value.
@item
If it generates @code{object-end}, calls @code{(object-end seed)}, let
the result be @var{obj}, recover the seed value saved
at the corresponding @code{object-start}, and calls
@code{(proc obj recovered-seed)}.  Let the result a new seed value.
@item
If it generates EOF, returns the seed value as the result of
@code{json-fold}.
@end itemize
@end defun

@defun json-read :optional port-or-generator
[SRFI-180]
@c MOD srfi.180
Read one JSON value or object from @var{port-or-generator}, which
should be an input port or a char generator.  If it is omitted,
the current input port is used.

JSON strings and numbers are mapped to Scheme strings and numbers.
JSON @code{true} and @code{false} become @code{#t} and @code{#f}.
JSON @code{null} becomes a symbol @code{null}.
JSON arrays become Scheme vectors, and JSON objects
become Scheme alist, in which keys are converted to symbols.

If the input contains invalid JSON text, a @code{<json-parse-error>}
is thrown.

See also @code{parse-json} in @code{rfc.json}
(@pxref{JSON parsing and construction}).

@example
(call-with-input-string
  "[@{\"a\":1@}, @{\"b\":true, \"c\":\"foo\"@}, null]"
  json-read)
  @result{} #(((a . 1))
      ((b . #t) (c . "foo"))
      null)
@end example
@end defun

@defun json-lines-read :optional port-or-generator
[SRFI-180]
@c MOD srfi.180
Returns a generator that yields a JSON values at a time,
read from the source in JSON Lines format
(@url{http://jsonlines.org/}), which contains multiple
toplevel JSON values separated with @code{#\newline}.
The input @var{port-or-generator} should be an input port
or a char generator, defaulted to the current input port.

See @code{json-read} above about the mapping from JSON values to Scheme
values.
@end defun

@defun json-sequence-read :optional port-or-generator
[SRFI-180]
@c MOD srfi.180
Returns a generator that yields a JSON values at a time,
read from the source in JSON Text Sequence format
(RFC7464, @url{https://tools.ietf.org/html/rfc7464}).
The input @var{port-or-generator} should be an input port
or a char generator, defaulted to the current input port.

JSON Text Sequence can contain multiple JSON values,
each one leaded by one or more consecutive U+001E.
If it encounters text unparsable as JSON, that segment (until next U+001E)
is silently ignored.  Returns a list of read JSON values.

See @code{json-read} above about the mapping from JSON values to Scheme
values.

See also @code{construct-json} in @code{rfc.json}
(@pxref{JSON parsing and construction}).
@end defun

@subheading JSON writer

@defun json-accumulator port-or-accumlator
[SRFI-180]
@c MOD srfi.180
This is dual to @code{json-generator}.  The @code{port-or-accumulator}
should be an output port or an accumulator that accepts a character or
a string.  This procedure
returns an accumulator that accepts the events such as
@code{json-generator} generates.
@end defun

@defun json-write obj :optional port-or-accumulator
[SRFI-180]
@c MOD srfi.180
Write @var{obj} as a JSON to @var{port-or-accumulator}, which
must be an output port or an accumulator that accepts a character or
a string.
@end defun

@c ----------------------------------------------------------------------
@node Custom ports, Linear adjustable-length strings, JSON, Library modules - SRFIs
@section @code{srfi.181} - Custom ports
@c NODE カスタムポート, @code{srfi.181} - カスタムポート

@deftp {Module} srfi.181
@mdindex srfi.181
@c EN
This srfi defines a way to implement a port in Scheme.
Gauche has native support of such ports (@pxref{Virtual ports}),
but this srfi is useful for portable code.
@c JP
このsrfiは、ポートをSchemeで実装する方法を定義します。
Gaucheは仮想ポートとしてそういう機能を提供しています(@ref{Virtual ports})が、
ポータブルなコードを書く場合はこのsrfiが便利でしょう。
@c COMMON

@c EN
The interface is upper compatible to R6RS.
@c JP
インタフェースはR6RSの上位互換になっています。
@c COMMON

@c EN
Note that R7RS Scheme distinguishes binary and textual ports,
while Gauche ports can handle both.
@c JP
R7RSではバイナリポートとテキストポートは区別されますが、
Gaucheのポートはバイナリもテキストもどちらも読み書きできます。
@c COMMON
@end deftp

@menu
* Creating custom ports::
* Transcoded ports::
@end menu

@node Creating custom ports, Transcoded ports, Custom ports, Custom ports
@subsection Creating custom ports
@c NODE カスタムポートの作成

@defun make-custom-binary-input-port id read! get-pos set-pos! close
@defunx make-custom-textual-input-port id read! get-pos set-pos! close
[SRFI-181]
@c MOD srfi.181
@c EN
Creates a new binary and textual input port and returns it, respectively.
@c JP
それぞれ、新たなバイナリポートとテキストポートを作って返します。
@c COMMON

@c EN
The @var{id} argument is an arbitrary Scheme procedure.  SRFI doesn't
specify how it is used.  In Gauche, @var{id} will be returned
with @code{port-name} procedure (@pxref{Common port operations}).
@c JP
@var{id}引数は任意のSchemeオブジェクトです。このsrfiではそれがどう使われるかは
規定されません。Gaucheでは、@var{id}に渡した値は
@code{port-name}手続きで得ることができます(@ref{Common port operations}参照)。
@c COMMON

@c EN
The @var{read!} argument is a procedure to be called
as @code{(read! @var{buffer} @var{start} @var{count})}.
For @code{make-custom-binary-input-port}, @var{buffer} is a
bytevector (u8vector).
For @code{make-custom-textual-input-port}, @var{buffer} is either
a string or a vector of characters (Gauche's implementation always
use a vector, but portable code should handle both).
@c JP
@var{read!}引数は手続きで、
@code{(read! @var{buffer} @var{start} @var{count})}のように呼び出されます。
@code{make-custom-binary-input-port}では、@var{buffer}は
バイトベクタ(u8vector)です。
@code{make-custom-textual-input-port}では、@var{buffer}は文字列か
文字のベクタです(Gaucheでは常に文字のベクタが渡されますが、
ポータブルなコードはどちらにも対応できるように書かれなければなりません)。
@c COMMON

@c EN
It should generate up to @var{count} bytes/characters of data and fill
@var{buffer} beginning from @var{start}, then return the number of
bytes/characters generated.
It should generate at least 1 byte/character if there's still data.
To indicate the end of the data, it writes no data and returns 0.
@c JP
@var{read!}手続きは、最大で@var{count}個のバイトもしくは文字を生成し、
それを@var{buffer}の@var{start}番目から書き込んで、
生成されたバイト/文字数を返します。
@var{read!}手続きは入力データがあるなら、
少なくとも1バイト/文字をバッファに書き込まなければなりません。
入力データがもう無いことを示すには、バッファを変更せず、0を返します。
@c COMMON

@c EN
The @var{get-pos} argument is a procedure to be called without arguments,
and returns an implementation-dependent object that indicates
the current position of the input stream.  The `current position' is
where next @var{read!} will generate the data.  This can be @code{#f}
if the port doesn't provide positions.
@c JP
@var{get-pos}引数は、引数を取らない手続きで、呼ばれたら入力ストリーム中の現在の位置を
示す処理系依存のオブジェクトを返します。「現在の位置」とは、次に@var{read!}が呼ばれた
時に読み出される位置です。カスタムポートが位置情報を扱う必要がなければ、
この引数は@code{#f}で構いません。
@c COMMON

@c EN
For @code{make-custom-binary-input-port}, there's a special rule that
if @var{get-pos} returns an exact integer, it should be a byte position
in the stream.
@c JP
ただし、@code{make-custom-binary-input-port}については、
@var{get-pos}が正確な整数を返す場合、
それは入力ストリーム中のバイト位置でなければなりません。
@c COMMON

@c EN
The @var{set-pos!} argument is a procedure to be called with one argument,
a new position.
It should set the source's position so that next @var{read!} starts
generating data from there.  The passed position is something that has
been returned by @var{get-pos}, or, for @code{make-custom-binary-input-port},
an exact integer that indicates the byte offset from the beginning of
the input.   This argument can be @code{#f} if the port doesn't
support setting positions.  The returned value of @var{set-pos!} is
ignored.
@c JP
@var{set-pos!}引数はひとつの引数を取る手続きです。
渡された引数は以前の@var{get-pos}が返した値か、
@code{make-custom-binary-input-port}の場合は、
入力先頭からのバイトオフセットです。
この手続きは、次の@var{read!}が指定位置からデータを読み出すように内部状態を更新します。
カスタムポートが位置情報のセットをサポートしなくて良いなら、この引数は@code{#f}で
構いません。
@c COMMON

@c EN
If the position passed to @var{set-pos!} is invalid,
an error that satisfy @code{i/o-invalid-position-error?} should be
thrown.  Portably, it can be done by throwing a condition created
by @code{make-i/o-invalid-position-error} (@pxref{Port positioning}).
For Gauche-specific code, you can throw a condition
@code{<io-invalid-position-error>}.
@c JP
@var{set-pos!}に渡された位置情報が不正なものであった場合、それは
@code{i/o-invalid-position-error?}を満たすエラーを投げなければなりません。
ポータブルに書くには、@code{make-i/o-invalid-position-error}で作った
エラーオブジェクトを投げます(@ref{Port positioning}参照)。
Gauche特有のコードで良ければ、
@code{<io-invalid-position-error>}コンディションを投げても良いです。
@c COMMON

@c EN
The @var{close} argument is a procedure to be called without
argument, when the custom port is closed.  It can be @code{#f} if you
don't need a special cleanup.
@c JP
@var{close}引数は、カスタムポートがクローズされた時に呼び出される、
引数を取らない手続きです。特にクローズ時のクリーンアップが不要であれば
@code{#f}を渡すこともできます。
@c COMMON
@end defun

@defun make-custom-binary-output-port id write! get-pos set-pos! close :optional flush
@defunx make-custom-textual-output-port id write! get-pos set-pos! close :optional flush
[SRFI-181]
@c MOD srfi.181
@c EN
Creates a new binary and textual out port and returns it, respectively.
@c JP
それぞれ、バイナリ出力ポートおよびテキスト出力ポートを作成して返します。
@c COMMON

@c EN
The @var{id} argument is an arbitrary Scheme object.  This SRFI doesn't
specify how it is used.  In Gauche, @var{id} will be returned
with @code{port-name} procedure (@pxref{Common port operations}).
@c JP
@var{id}は任意のSchemeオブジェクトです。このSRFIはその用途について特に規定しません。
Gaucheでは、@code{port-name}手続きによって@var{id}を得ることができます
(@ref{Common port operations}参照)。
@c COMMON

@c EN
The @var{write!} argument is a procedure to be called as
@code{(write! @var{buffer} @var{start} @var{count})}.
For @code{make-custom-binary-output-port}, @var{buffer} is a bytevector.
For @code{make-custom-textual-output-port}, @var{buffer} is either
a string or a vector of characters (Gauche's implementation always
use a vector, but portable code should handle both).
@c JP
@var{write!}引数は、@code{(write! @var{buffer} @var{start} @var{count})}のように
呼び出される手続きです。@code{make-custom-binary-output-port}では
@var{buffer}はバイトベクタで、@code{make-custom-textual-output-port}では
@var{buffer}は文字列もしくは文字のベクタです(Gaucheでは常にベクタが渡されますが、
ポータブルなコードではどちらが来ても良いように書いておく必要があります)。
@c COMMON

@c EN
The @var{write!} procedure writes data in @var{buffer}
starting from @var{start}, upto @var{count} items at maximum,
to the external sink.  It must return the number
of actual items written.
@c JP
@var{write!}手続きは、@var{buffer}のインデックス@var{start}から最大@var{count}要素
を外部のシンクへと書き出し、実際に書き出された要素数を返します。
@c COMMON

@c EN
The @var{get-pos} argument should be a procedure without taking argument,
or @code{#f}.  If it is a procedure, it should return the position
of the sink where the next @var{write!} writes to.  The position
can be an arbitrary Scheme object, but for
@code{make-custom-binary-output-port}, a position represented as
an exact integer should correspond to the byte offset in the port.
@c JP
@var{get-pos}引数は、引数を取らない手続きか@code{#f}でなければなりません。
手続きの場合、呼ばれたら、次の@var{write!}が書き込むであろうシンクの位置を返します。
位置は任意のSchemeオブジェクトが許されますが、
@code{make-custom-binary-output-port}の場合、@var{get-pos}が
正確な整数を返すならそれはポートのバイトオフセットでなければなりません。
@c COMMON

@c EN
The @var{set-pos!} argument is a procedure to be called with one argument,
a new position, or @code{#f}.
It should set the sink's position so that next @var{write!} starts
to write data from there.  The passed position is something that has
been returned by @var{get-pos}, or, for @code{make-custom-binary-output-port},
an exact integer that indicates the byte offset from the beginning of
the output.   This argument can be @code{#f} if the port doesn't
support setting positions.  The returned value of @var{set-pos!} is
ignored.
@c JP
@var{set-pos!}引数は引数をひとつ取る手続きか@code{#f}でなければなりません。
手続きの場合、引数はシンクの位置を示すオブジェクトで、次の@var{write!}が
その位置から書き込まれるようにポートと状態をセットします。
位置を示すオブジェクトは、同じポートに対して@var{get-pos}が以前返した位置か、
もしくは@code{make-custom-binary-output-port}の場合、ポートの先頭からの
バイトオフセットを示す正確な整数です。@var{set-pos!}が@code{#f}の場合は、
ポートは位置を変える手段を持ちません。@var{set-pos!}の戻り値は無視されます。
@c COMMON

@c EN
If the position passed to @var{set-pos!} is invalid,
an error that satisfy @code{i/o-invalid-position-error?} should be
thrown.  Portably, it can be done by throwing a condition created
by @code{make-i/o-invalid-position-error} (@pxref{Port positioning}).
For Gauche-specific code, you can throw a condition
@code{<io-invalid-position-error>}.
@c JP
@var{set-pos!}に渡された引数が位置を示すオブジェクトとして不適切だった場合は、
述語@code{i/o-invalid-position-error?}を満たすエラーを投げなければなりません。
ポータブルなコードでは、@code{make-i/o-invalid-position-error}を使って
そのようなエラーを作ることができます (@ref{Port positioning}参照)。
Gauche特有のコードなら、@code{<io-invalid-position-error>}コンディションを
投げることもできます。
@c COMMON

@c EN
The @var{close} argument is a procedure to be called without
argument, when the port is closed.  It can be @code{#f} if you
don't need a special cleanup.
@c JP
@var{close}引数は引数を取らない手続きで、ポートが閉じられた時に呼ばれます。
ポートが閉じられた時に特にすることが無ければ@code{#f}を渡しても構いません。
@c COMMON

@c EN
The @var{flush} argument, if provided and not @code{#f},
should be a procedure taking no arguments.  It is called when
the port is requested to flush the data buffered in the sink, if any.
@c JP
@var{flush}引数は、引数を取らない手続きか@code{#f}です。
ポートが、バッファされたデータが確実にシンクに書き出されたことを保証したい時に
呼ばれます。
@c COMMON
@end defun

@defun make-custom-binary-input/output-port id read! write! get-pos set-pos! close :optional flush
[SRFI-181]
@c MOD srfi.181
@c EN
Creates a bidirectional binary i/o port.  Since Gauche doesn't distinguish
binary and textual ports, you can use the returned port for textual i/o as well,
but portable code must avoid it.
@c JP
バイナリ入出力ポートを作って返します。Gaucheはバイナリポートと
テキストポートを区別しないので、作られたポートをテキスト入出力に使うこともできますが、
ポータブルなコードではそれは避けるべきでしょう。
@c COMMON

@c EN
(The reason textual input/output port is not defined in the SRFI is that
it is difficult to define a consistent semantics agnostic to the internal
representation of character stream.  In Gauche, we immediately convert
characters to the octet stream of internal character encoding.)
@c JP
(このSRFIではテキスト入出力ポートは定義されません。
というのも、文字ストリームの内部表現とは独立した一貫性のあるセマンティクスを
定義するのが難しいからです。Gaucheでは文字の入出力は
内部エンコーディングに従ったオクテット列の入出力とみなします。)
@c COMMON

@c EN
The arguments, @var{id}, @var{read!}, @var{write!},
@var{get-pos}, @var{set-pos!}, @var{close} and @var{flush} are
the same as @code{make-custom-binary-input-port} and
@code{make-custom-binary-output-port}.
@c JP
引数@var{id}、@var{read!}、@var{write!}、@var{get-pos}、@var{set-pos!}、
@var{close}、@var{flush}の意味は、
@code{make-custom-binary-input-port}および@code{make-custom-binary-output-port}
のそれらと同じです。
@c COMMON
@end defun

@node Transcoded ports,  , Creating custom ports, Custom ports
@subsection Transcoded ports
@c NODE 符号変換ポート

@c EN
A transcoded port is a portable way to read/write characters in
an encodings other than the system's default one.  This API is
defined first in R6RS, and adopted in SRFI-181.
@c JP
符号変換ポートとは、システムの文字エンコーディング以外の符号化方式でエンコードされた
文字の読み書きをポータブルにする方法です。
このAPIは当初R6RSで定義され、SRFI-181に採用されました。
@c COMMON

@c EN
In SRFI-181 (and R6RS) world, strings and characters are all
an abstract entity without the concept of encodings (internally,
you can think them being encoded in the system's native encoding),
and the explicit encodings only matter when you refer to the outside
resource, e.g. files or a binary data represented in a bytevector.
Therefore, conversions are only defined between binary ports (external world)
and textual ports (internal), or a bytevector (external world) and
a string (internal).
@c JP
SRFI-181(およびR6RS)の世界では、文字列と文字はエンコーディングという概念を持たない
抽象化されたオブジェクトです (内部的には、システムのネイティブエンコーディングで
保持されていると考えて良いでしょう)。
従って、エンコーディングを考える必要があるのは、
外部から与えられる、ファイルやバイトベクタに格納されたバイナリデータを扱いたい時だけです。
従って符号変換は、バイナリポート(外部世界)とテキストポート(内部世界)の間か、
バイトベクタ(外部世界)と文字列(内部世界)の間でのみ定義されます。
@c COMMON

@c EN
Here's some terms:
@c JP
用語の定義:
@c COMMON

@c EN
@table @emph
@item Codec
A codec specifies a character encoding scheme.
@item EOL-style
Specifies (non)converson of EOL character(s).
@item Transcoder
A transcoder bundles a codec, an eol-style, and error handling mode.
@end table
@c JP
@table @emph
@item コーデック
文字エンコーディング方式(CES)を特定するオブジェクトです
@item 行末スタイル
行末文字の扱いを指定する名前
@item トランスコーダ
コーデック、行末スタイル、エラー処理をまとめるオブジェクト
@end table
@c COMMON

@c EN
NB: For Gauche-specific code, you can use @code{gauche.charconv} module
(@pxref{Character code conversion}) that provides more options.
@c JP
註: Gauche特有のコードなら、@code{gauche.charconv}モジュールがさらに柔軟な
機能を提供しています(@ref{Character code conversion}参照)。
@c COMMON

@c EN
@subsubheading Transcoders
@c JP
@subsubheading トランスコーダ
@c COMMON

@defun make-transcoder codec eol-style error-handling
[SRFI-181]
@c MOD srfi.181
@c EN
Creates and returns a transcoder with the given parameters.
A transcoder is an immutable object.
@c JP
与えられたパラメータをまとめたトランスコーダを作って返します。
トランスコーダは変更不可なオブジェクトです。
@c COMMON

@c EN
The @var{codec} argument must be a codec object, either created by
@code{make-codec} or one of the predefined codecs; see below.
@c JP
@var{codec}引数は@code{make-codec}で作られるか、あらかじめ作られている
コーデックオブジェクトです。下で説明します。
@c COMMON

@c EN
The @var{eol-style} argument is one of the following symbols to specify
End-of-likne style:
@c JP
@var{eol-style}引数は行末文字の処理を指定する、次のシンボルのいずれかです。
@c COMMON

@table @code
@item none
@c EN
End-of-line character is passed as-is.
@c JP
行末文字の変換を行いません。
@c COMMON
@item lf
@c EN
Output port converts @code{#\newline} to @code{LF} octet.
Input port converts any line ending to @code{#\newline}.
@c JP
出力ポートは@code{#\nelwine}文字を@code{LF}オクテットに変換します。
入力ポートはどんな行末文字でも@code{#\newline}に変換します。
@c COMMON
@item crlf
@c EN
Output port converts @code{#\newline} to @code{CR-LF} octet sequence.
Input port converts any line ending to @code{#\newline}.
@c JP
出力ポートは@code{#\nelwine}文字を@code{CR-LF}オクテット列に変換します。
入力ポートはどんな行末文字でも@code{#\newline}に変換します。
@c COMMON
@end table

@c EN
The @var{error-handling} argument is a symbol to specify the behavior
when an encoding or decoding error occurs.
It can be one of the following symbols.
@c JP
@var{error-handling}引数は、エンコードもしくはデコードできない文字があったときの
振る舞いを指定する、以下のシンボルのいずれかです。
@c COMMON

@table @code
@item replace
@c EN
Octets that do not consist a valid character encoding are replaced
with @code{#\xFFFD} (or @code{#\?} if the target encoding of an output
transcoding port does not contain @code{#\xFFFD}.)
@c JP
有効な文字エンコーディングにならないオクテットは文字@code{#\xFFFD}に置き換えられます
(出力変換ポートで変換先の文字セットが@code{#\xFFFD}を持っていない場合は@code{#\?}が
使われます)。
@c COMMON
@item raise
@c EN
Raise an error with a condition satisfying @code{i/o-encoding-error?}.
The erroneous octet are consumed and next I/O on the port continues
with the next character.
@c JP
@code{i/o-encoding-error?}を満たすコンディションを伴ってエラーを投げます。
原因になったオクテットは消費され、次のI/Oは次の文字から続行されます。
@c COMMON
@end table
@end defun

@defun native-transcoder
[SRFI-181]
@c MOD srfi.181
@c EN
Returns a singleton of the transcoder representing systems native
(internal) codec and eol-style.  In Gauche, the native codec
is the codec uses Gauche's native encoding
(returned by @code{gauche-character-encoding}, @pxref{Characters}),
and eol-style is @code{none}.
@c JP
システム内部で使われているコーデックおよび行末スタイルを表すトランスコーダを返します。
Gaucheでは、内部コーデックは内部文字エンコーディング
(@code{gauche-character-encoding}が返すもの。@ref{Characters}参照)
を使うコーデックで、行末スタイルは@code{none}です。
@c COMMON
@end defun

@defun transcoded-port binary-port transcoder
[SRFI-181]
@c MOD srfi.181
@c EN
Creates a transcoded port wrapping @var{binary-port}, performing the
conversion specified by @var{transcoder}.

If @var{binary-port} is an input port, it returns an input port,
converting the CES specified in @var{transcoder} to the system's
native encoding.

If @var{binary-port} is an output port, it returns an output port,
converting the system's native encoding to the CES specified in
@var{transcoder}.

In Gauche, conversion is done by conversion ports.
@xref{Conversion ports}, for the details.
@c JP
@var{binary-port}をラップし、@var{transcoder}により符号変換を行うポートを返します。

@var{binary-port}が入力ポートなら、返されるのはテキスト入力ポートで、
@var{transcoder}が指定する方式で符号化された外部データを読み込む際に
内部エンコーディングへと変換します。

@var{binary-port}が出力ポートなら、返されるのはテキスト出力ポートで、
内部エンコーディングによる文字や文字列を出力する際に、
@var{transcoder}が指定する方式へと変換します。

Gaucheでは符号変換は変換ポートで行われます。
詳しくは@ref{Conversion ports}を参照してください。
@c COMMON
@end defun

@defun bytevector->string bytevector transcoder
[SRFI-181]
@c MOD srfi.181
@c EN
Decode the binary data in @var{bytevector} as the CES specified
by @var{transcoder}, and returns a string in the native encoding.

It is a wrapper of Gauche's @code{ces-convert}; @pxref{Conversion ports}.
@c JP
@var{bytevector}に格納されたバイナリデータを、
@var{transcoder}で指定される符号化方式によるものとみなして、
それを内部エンコーディングによる文字列に変換したものを返します。

Gaucheの@code{ces-convert}のラッパーです (@ref{Conversion ports}参照)。
@c COMMON
@end defun

@defun string->bytevector string transcoder
[SRFI-181]
@c MOD srfi.181
@c EN
Encode the string in the CES specified by @var{transcoder},
and returns a bytevector.

It is a wrapper of Gauche's @code{ces-convert-to}; @pxref{Conversion ports}.
@c JP
文字列を、@var{transcoder}が指定する符号化方式に変換したものをバイトベクタとして返します。

Gaucheの@code{ces-convert-to}のラッパーです (@ref{Conversion ports}参照)。
@c COMMON
@end defun

@c EN
@subsubheading Codecs
@c JP
@subsubheading コーデック
@c COMMON

@defun make-codec name
[SRFI-181]
@c MOD srfi.181
@c EN
Returns a codec representing a character encoding scheme named by
@var{name}.  A portable code should only use string for @var{name},
while Gauche accepts a symbol as well.

If @var{name} isn't recognized as a supported codec name,
a condition that satisfies @code{unknown-encoding-error?} is thrown.
@c JP
@var{name}で指定される文字符号化方式を表すコーデックを返します。
ポータブルなコードでは@var{name}に文字列を渡してください。Gaucheではシンボルも
受け付けます。

@var{name}がサポートされているコーデックの名前でなければ、
述語@code{unknown-encoding-error?}を満たすコンディションを伴ってエラーが投げられます。
@c COMMON
@end defun

@defun unknown-encoding-error? obj
[SRFI-181]
@c MOD srfi.181
@c EN
If the system sees unknown or unsupported codec, a condition
that satisfies this predicate is thrown.
@c JP
システムが認識しないあるいはサポートしないコーデックを使うように指示された場合、
この述語を満たすコンディションが投げられます。
@c COMMON
@end defun

@defun unknown-encoding-error-name obj
[SRFI-181]
@c MOD srfi.181
@c EN
The argument must be an unknown encoding error condition
that satisfies @code{unknown-encoding-error?}.  It returns
the name that caused the condition to be thrown.
@c JP
引数は述語@code{unknown-encoding-error?}を満たすコンディションでなければなりません。
このコンディションの原因となったコーデック名を返します。
@c COMMON
@end defun

@defun latin-1-codec
@defunx utf-8-codec
@defunx utf-16-codec
[SRFI-181]
@c MOD srfi.181
@c EN
A pre-defined codecs for @code{latin-1} (ISO8859-1),
@code{utf-8}, and @code{utf-16}.
@c JP
あらかじめ作られている、
@code{latin-1} (ISO8859-1)、@code{utf-8}、および@code{utf-16}コーデックを返します。
@c COMMON

@c EN
The @code{utf-16} codec recognizes
BOM when used for input; if no BOM is found, UTF-16BE is assumed.
When used for output, @code{utf-16} always attaches BOM.
@c JP
@code{utf-16}コーデックは入力にBOMがあればそのバイトオーダーを使い、
無ければUTF-16BEを使います。
出力に使われた場合は常にBOMを出力します。
@c COMMON
@end defun

@c EN
@subsubheading EOL style
@c JP
@subsubheading 行末スタイル
@c COMMON

@defun native-eol-style
[SRFI-181]
@c MOD srfi.181
@c EN
Returns the default eol style.  In Gauche, it is @code{none}.
@c JP
デフォルトの行末スタイルを返します。Gaucheでは@code{none}です。
@c COMMON
@end defun

@c EN
@subsubheading Transcoding errors
@c JP
@subsubheading 変換エラー
@c COMMON

@defun i/o-decoding-error? obj
[SRFI-181]
@c MOD srfi.181
@c EN
When an input transcoded port encounters a sequence that's not valid
for the input codec, a condition that satisfies this predicate
is thrown.

In Gauche, such condition is @code{<io-decoding-error>}.
@c JP
入力変換ポートがコーデックとして不正なバイトシーケンスに出会った場合、
この述語を満たすコンディションが投げられます。

Gaucheではそのコンディションは@code{<io-decoding-error>}のインスタンスです。
@c COMMON
@end defun

@defun i/o-encoding-error? obj
[SRFI-181]
@c MOD srfi.181
@c EN
When an output transcoded port encounters a character that can't be
encoded in the output codec, and the handling mode is @code{raise},
a condition that satisfies this predicate is thrown.

In Gauche, such condition is @code{<io-encoding-error>}.
@c JP
出力変換ポートが出力しようとした文字がコーデックで表わせず、
エラーハンドリングモードが@code{raise}である場合、
この述語を満たすコンディションが投げられます。

Gaucheではそのコンディションは@code{<io-encoding-error>}のインスタンスです。
@c COMMON
@end defun

@defun i/o-encoding-error-char i/o-encoding-condition
[SRFI-181]
@c MOD srfi.181
@c EN
Retries the character that caused the @code{<io-encoding-error>} is thrown.
@c JP
@code{<io-encoding-error>}コンディションの原因となった文字を返します。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Linear adjustable-length strings, Maybe and Either optional container types, Custom ports, Library modules - SRFIs
@section @code{srfi.185} - Linear adjustable-length strings
@c NODE 線形更新な可変長文字列, @code{srfi.185} - 線形更新な可変長文字列

@deftp {Module} srfi.185
@mdindex srfi.185
@c EN
This module provides a linear-update version of @code{string-append}
and @code{string-replace}.  ``Linear update'' means the caller
won't access the first string argument, hence the implementation
@emph{can} reuse it to store the result, for the efficiency.
@c JP
このモジュールは@code{string-append}と@code{string-replace}の線形更新版を提供します。
「線形更新」とは、この関数を呼び出した後は引数が使われないことが前提になっているという
意味で、従って処理系は結果を格納するために引数を破壊的に再利用することが許されています。
@c COMMON

@c EN
Note that, in Gauche, a string is just a pointer to an immutable
string body.  Mutation of a string is actually constructing a new
string body and swapping the pointer, so it has no performance
advantage to immutable versions.  And in fact, we implement
these without mutating their arguments.
@c JP
しかしGaucheでは、文字列は変更不可な文字列本体へのポインタであって、
文字列の変更は新たな文字列本体を作ってポインタを差し替える操作にすぎず、
文字列を破壊的に再利用するメリットは全くありません。
従ってこのsrfiのAPIは単に非破壊版を呼び出すだけになっています。
@c COMMON

@c EN
This module also provides macros with the same name as @code{srfi.118}
procedures (@pxref{Simple adjustable-size strings}), which @code{set!}
the result to its first argument, so they can work as a drop-in
replacement to @code{srfi.118}.
@c JP
このモジュールはまた、@code{srfi.118}の手続き(@ref{Simple adjustable-size strings}参照)
と同名のマクロを提供しています。マクロは結果を引数に渡された式に
@code{set!}する式に展開されるので、一見@code{srfi.118}と同じように使うことができます。
@c COMMON
@end deftp

@defun string-append-linear! dst str-or-char @dots{}
[SRFI-185]
@c MOD srfi.185
@c EN
Returns a string which is a concatenation of a string @var{dst}
and the arguments.  The second argument an after can be
a string or a character.  The caller shouldn't access @var{dst}
after calling this procedure, for the implementation may destructively
reuse the string passed to @var{dst}.   Although Gauche won't
mutate @var{dst}, other implementations may, so portable code
should adhere this restriction.
@c JP
文字列@var{dst}と他の引数を全部つなげた文字列を返します。
2番目以降の引数は文字でも文字列でも構いません。呼び出し元は、この関数を読んだ後は
@var{dst}が指す文字列にアクセスしてはいけません。実装は@var{dst}が指す文字列を
破壊的に再利用して結果を格納することが許されています。Gaucheは@var{dst}を
破壊しませんが、ポータブルなコードでは@var{dst}を使わないようにしてください。
@c COMMON

@c EN
You can't count on @var{dst} being mutated; you always have to use the returned
string.
@c JP
@var{dst}が破壊することをあてにしてはいけません。
常に戻り値の文字列を使うようにしてください。
@c COMMON

@example
(string-append-linear! "abc" "def" #\g "hij")
  @result{} "abcdefghij"
@end example
@end defun

@defun stirng-replace-linear! dst dst-start dst-end src :optional src-start src-end
[SRFI-185]
@c MOD srfi.185
@c EN
Returns copy of a string @var{dst} except
the portion of from @var{dst-start} (inclusive)
to @var{dst-end} (exclusive), by a string @var{src} (from @var{src-start}
to @var{src-end}).
The caller shouldn't access @var{dst}
after calling this procedure, for the implementation may destructively
reuse the string passed to @var{dst}.   Although Gauche won't
mutate @var{dst}, other implementations may, so portable code
should adhere this restriction.
@c JP
文字列@var{dst}のうち、@var{dst-start}(含まれる)から@var{dst-end}(含まれない)
までの範囲を、文字列@var{src}(の@var{src-start}と@var{src-end}の範囲)で置き換えた
文字列を返します。
呼び出し元は、この関数を読んだ後は
@var{dst}が指す文字列にアクセスしてはいけません。実装は@var{dst}が指す文字列を
破壊的に再利用して結果を格納することが許されています。Gaucheは@var{dst}を
破壊しませんが、ポータブルなコードでは@var{dst}を使わないようにしてください。
@c COMMON

@c EN
Gauche allows string cursors, as well as integer character index,
in @var{dst-start}, @var{dst-end}, @code{src-start} and @var{src-end} arguments.
(@xref{String cursors}).
@c JP
Gaucheでは、@var{dst-start}、@var{dst-end}、@code{src-start}、@var{src-end}
引数に、整数の文字インデックスだけでなく文字列カーソルも使えます。
(@ref{String cursors}参照)。
@c COMMON
@end defun

@defmac string-append! dst string-or-char @dots{}
@defmacx string-replace! dst dst-start dst-end src :optional src-start src-end
[SRFI-185]
@c MOD srfi.185
@c EN
These macros expand into the following forms:
@c JP
これらのマクロは次の形に展開されます。
@c COMMON

@example
(set! dst (string-append-linear! dst string-or-char @dots{}))

(set! dst (string-replace-linear! dst dst-start dst-end src src-start src-end))
@end example

@c EN
Hence they can be used for the code that expects @var{dst} to contain
the result after calling these macros.
Gauche supports generalized @code{set!}, so @var{dst} can be
a procedure call with a setter defined.
@c JP
つまり、呼び出した後に@var{dst}に変更された文字列が格納されることを想定している
箇所に使えます。Gaucheは一般化された@code{set!}を持っているので、
@var{dst}にはセッターが定義されている手続き呼び出しも使えます。
@c COMMON

@example
(define x (list (string-copy "abc")))

(string-append! (car x) #\d #\e #\f)

x @result{} ("abcdef")
@end example

@c EN
The code that uses SRFI-118 (@pxref{Simple adjustable-size strings}) is
likely to be replaced using these macros.
@c JP
SRFI-118 (@ref{Simple adjustable-size strings}参照)を使っているコードは、
このマクロで置き換えられることも多いでしょう。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node Maybe and Either optional container types, Coroutine generators, Linear adjustable-length strings, Library modules - SRFIs
@section @code{srfi.189} - Maybe and Either: optional container types
@c NODE MaybeとEither、オプショナルなコンテナ型, @code{srfi.189} - MaybeとEither、オプショナルなコンテナ型

@deftp {Module} srfi.189
@mdindex srfi.189
@c EN
Maybe and Either types are immutable container types
that can ``wrap'' zero or more values.  Maybe can be used
in the context where the value(s) may be missing (as opposed to
``zero values'').  Either can be used in the context where
the value(s) can be correct ones or erroneous ones.
@c JP
MaybeとEitherは、任意個の値を「ラップ」する変更不可なコンテナ型です。
Maybeは値が「有効な値が無い」という状況で使えます
(これは「ゼロ個の値を生成する」とは異なります)。
Eitherは「正常動作の時の値」と「エラー時の値」を区別したい状況で使えます。
@c COMMON

@c EN
If you're familiar with functional languages like Haskell, you may
already know them.  They are useful when used in the monadic pattern; that is,
you can code as if the chain of calculations never fails,
yet whenever the calculation fail at one place,
the rest of chain is canceled and just the failure is returned.
@c JP
Haskellのような関数型言語に親しんでいるなら、これらの型については既に
ご存知でしょう。これらの型はモナドで使うととても便利です。
例えば、処理の連なりをまるで失敗が起きないかのように書きながら、
もし失敗が起きたら自動的に残りの処理がキャンセルされて失敗情報が帰ってくる、
というふうにできます。
@c COMMON

@c EN
Maybe is a union of two types, Just and Nothing.  Just wraps
valid value(s), while Nothing indicates there's no meaningful values.
Either is a union of two types, Right and Left.  Right wraps
valid value(s), while Left indicates an error, carrying some information
as its payload.
@c JP
Maybeは2つの型、JustとNothingのユニオン型です。
Justは有効な値(複数可)をラップし、Nothingは「有効な値がない」ことを示します。
Eitherは2つの型、RightとLeftのユニオン型です。
Rightは有効な値(複数可)をラップしLeftはエラー時の情報をラップします。
@c COMMON

@c EN
Unlike other languages, though, Just, Right and Left can carry
arbitrary number of values, reflecting Scheme's multiple values.
Suppose you have a procedure @code{f} that returns two values.
When you lift @code{f} to Maybe monad, the lifted procedure @code{mf}
may return @code{Just} with two values or @code{Nothing}.
Although most of the time we use single value in practice, keep
that in mind to read the reference.
@c JP
Schemeには多値があるので、他の言語と違ってJust、Right、Leftは
任意個の値を持てることに注意してください。
例えば2つの値を返す手続き@code{f}をMaybeモナドの圏に持ち上げた手続き@code{mf}は、
2つの値を持つ@code{Just}か@code{Nothing}を返すようになります。
ほとんどの場合は単一の値を扱うことになるでしょうが、
リファレンスを読む際には多値の場合の可能性を頭に置いておいてください。
@c COMMON
@end deftp

@menu
* Maybe and Either types and predicates::
* Maybe and Either constructors::
* Maybe and Either accessors::
* Maybe and Either sequence operations::
* Maybe and Either protocol converters::
* Maybe and Either syntactic utilities::
* Trivalent logic::
@end menu

@node Maybe and Either types and predicates, Maybe and Either constructors, Maybe and Either optional container types, Maybe and Either optional container types
@subsection Types and predicates
@c NODE MaybeとEither - 型と述語, 型と述語

@deftp {Class} <maybe>
@deftpx {Class} <just>
@deftpx {Class} <nothing>
@c MOD srfi.189
@c EN
Maybe classes.  @code{<just>} and @code{<nothing>} are subclasses of
@code{<maybe>}.  An instance of @code{<just>} carries zero or more
values (payload), while an instance of @code{<nothing>} doesn't carry
information.
@c JP
Maybe型のクラスです。@code{<just>}と@code{<nothing>}は@code{<maybe>}のサブクラスです。
@code{<just>}のインスタンスは任意個の値(ペイロード)を保持できます。
@code{<nothing>}のインスタンスは値を保持しません。
@c COMMON

@c EN
The @code{<maybe>} class itself is an abstract class and can't
create an instance of its own.
Instances of @code{<just>} and @code{<nothing>} should be created with
constructor procedures @code{just} and @code{nothing}.
@c JP
@code{<maybe>}クラス自体は抽象クラスで、それ自身のインスタンスは作りません。
@code{<just>}と@code{<nothing>}のインスタンスはそれぞれ
コンストラクタ@code{just}および@code{nothing}で作ります。
@c COMMON
@end deftp

@deftp {Class} <either>
@deftpx {Class} <right>
@deftpx {Class} <left>
@c MOD srfi.189
@c EN
Either classes.  @code{<right>} and @code{<left>} are subclasses of
@code{<either>}.  An instance of either class carry zero or more
values (payload); it is customary to use @code{<right>} to propagate
the legitimate results of compuation, while use @code{<left>} to
propagate erroneous conditions whose payload describes what's wrong.
@c JP
Either型のクラスです。@code{<right>}と@code{<left>}は@code{<either>}のサブクラスです。
どちらのインスタンスは任意個の値(ペイロード)を保持できます。
慣習として、@code{<right>}は正常な計算結果を運ぶのに使われ、
@code{<left>}は異常が生じた時に何が異常かの情報を運ぶのに使われます。
@c COMMON

@c EN
The @code{<either>} class is an abstract class and can't
create an instance of its own.
Instances of @code{<right>} and @code{<left>} should be created with
constructor procedures @code{right} and @code{left}.
@c JP
@code{<either>}クラス自体は抽象クラスで、それ自身のインスタンスは作りません。
@code{<right>}と@code{<left>}のインスタンスはそれぞれ
コンストラクタ@code{right}および@code{left}で作ります。
@c COMMON
@end deftp

@defun maybe? obj
@defunx just? obj
@defunx nothing? obj
[SRFI-189]
@c MOD srfi.189
@c EN
Type predicates.
Returns @code{#t} iff @var{obj} is a Maybe, a Just, or a Nothing,
respectively.
@c JP
型検査述語です。
それぞれ、@var{obj}がMaybe, Just, Nothingである場合に@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun either? obj
@defunx right? obj
@defunx left? obj
[SRFI-189]
@c MOD srfi.189
@c EN
Type predicates.
Returns @code{#t} iff @var{obj} is a Either, a Right, or a Left,
respectively.
@c JP
型検査述語です。
それぞれ、@var{obj}がEither, Right, Leftである場合に@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun maybe= elt= maybe1 maybe @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Equality predicate of Maybes.  It returns @code{#t} iff
all of @var{maybe1} @var{maybe} @dots{} are Nothings,
or Justs with their respective payload objects are the same
using @var{elt=}.
@c JP
Maybeについての等価判定述語です。NothingはNothingのみと等価であり、
Justはその対応するペイロード同士が全て@code{elt=}で比較して等価な場合にのみ
等価です。
@c COMMON
@end defun

@defun either= elt= either1 either @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Equality predicate of Eithers.  It returns @code{#t} iff
all of @var{either11} @var{either} @dots{} are the same
types (all Rights, or all Lefts), with
respective payload objects are the same
using @var{elt=}.
@c JP
Eitherについての等価判定述語です。
Rightは同じペイロードを持つRightのみと、
Leftは同じペイロードを持つLeftのみと等価です。
ペイロード同士は@code{elt=}で比較されます。
@c COMMON
@end defun

@node Maybe and Either constructors, Maybe and Either accessors, Maybe and Either types and predicates, Maybe and Either optional container types
@subsection Constructors
@c NODE MaybeとEither - コンストラクタ, コンストラクタ

@defun just obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Returns a Just with @var{obj} @dots{} as its payload.
@c JP
@var{obj} @dots{}をペイロードに持つJustのインスタンスを返します。
@c COMMON
@end defun

@defun nothing
[SRFI-189]
@c MOD srfi.189
@c EN
Returns a Nothing.
@c JP
Nothingのインスタンスを返します。
@c COMMON
@end defun

@defun right obj @dots{}
@defunx left obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Returns a Right or a Left respectively, with @var{obj} @dots{}
as its payload.
@c JP
@var{obj} @dots{}をペイロードに持つ、それぞれRightとLeftのインスタンスを返します。
@c COMMON
@end defun

@defun list->just objs
@defunx list->right objs
@defunx list->left objs
[SRFI-189]
@c MOD srfi.189
@c EN
Returns a Just, Right or Left respectively, with
@var{objs} as its payload.
@c JP
リストで与えられるオブジェクトをペイロードに持つ、Just、Right、Left
のインスタンスをそれぞれ返します。
@c COMMON
@end defun

@defun maybe->either maybe obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{maybe} argument must be a Maybe.
If it is a Just, then a Right with the same payload is returned.
If it is a Nothing, a Left with @var{obj} @dots{} as its payload.
@c JP
@var{maybe}引数はMaybeでなければなりません。
引数がJustの場合は。同じペイロードを持つRightが、
Nothingの場合は、@var{obj} @dots{}をペイロードに持つLeftが返されます。
@c COMMON
@end defun

@defun either->maybe either
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{either} argument must be an Either.
If it is a Right, then a Just with the same payload is returned.
If it is a Left, a Nothing is returned.
@c JP
@var{either}引数はEitherでなければなりません。
引数がRightの場合は。同じペイロードを持つJustが、
Leftの場合はNothingが返されます。
@c COMMON
@end defun

@defun either-swap either
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{either} argument must be an Either.
If it is a Right, a Left with the same payload argument is returned.
If it is a Left, a Right with the same payload argument is returned.
@c JP
@var{either}引数はEitherでなければなりません。
引数がRightの場合は。同じペイロードを持つLeftが、
Leftの場合は同じペイロードを持つRightが返されます。、
@c COMMON
@end defun

@node Maybe and Either accessors, Maybe and Either sequence operations, Maybe and Either constructors, Maybe and Either optional container types
@subsection Accessors
@c NODE MaybeとEither - アクセサ, アクセサ

@defun maybe-ref maybe failure :optional success
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{maybe} argument must be a Maybe.  If it's a Nothing,
a procedure @var{failure} is tail-called with no arguments.
If it's Just, a procedure @var{success} is tail-called with its
payload object(s).  If @var{success} is omitted, @code{values} is used.
@c JP
@var{maybe}引数はMaybeでなければなりません。
それがNothingなら、手続き@var{failure}が引数なしで末尾呼び出しされます。
Justの場合は手続き@var{success}が、Justのペイロードを引数として末尾呼び出しされます。
@var{success}が省略された場合は@code{values}が使われます。
@c COMMON

@example
(maybe-ref (just 1 2) (^[] (error 'huh?)) +)
  @result{} 3
@end example
@end defun

@defun either-ref either failure :optional success
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{either} argument must be an Either.
If it's a Left, a procedure @var{failure} is called with
its payload object(s).  If it's a Right, a procedure
@var{success} is called with its payload object(s).
If @var{success} is omitted, @code{values} is used.
@c JP
@var{either}引数はEitherでなければなりません。
それがLeftなら、手続き@var{failure}が、
Rightの場合は手続き@var{success}がペイロードを引数として末尾呼び出しされます。
@var{success}が省略された場合は@code{values}が使われます。
@c COMMON
@end defun

@defun maybe-ref/default maybe default @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{maybe} argument must be a Maybe.  If it's a Nothing,
@var{default} @dots{} are returned as multiple values.
If it's a Just, its payload object(s) is/are returned as multiple values.
@c JP
@var{maybe}引数はMaybeでなければなりません。
それがNothingなら、@var{default} @dots{}が値として返されます。
Justの場合はそのペイロードが値として返されます。
@c COMMON

@example
(maybe-ref/default maybe obj @dots{})
 @equiv{} (maybe-ref maybe (^[] (values obj @dots{})))
@end example
@end defun

@defun either-ref/default maybe default @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{either} argument must be an Either.  If it's a Left,
@var{default} @dots{} are returned as multiple values (the Left's payload
is discarded).
If it's a Right, its payload object(s) is/are returned as multiple values.
@c JP
@var{either}引数はEitherでなければなりません。
それがLeftなら、そのペイロードは捨てられ、
@var{default} @dots{}が値として返されます。
Rightの場合はそのペイロードが値として返されます。
@c COMMON

@example
(either-ref/default either obj @dots{})
 @equiv{} (either-ref either (^ _ (values obj @dots{})))
@end example
@end defun

@defun maybe-join maybe
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe} is a Nothing,
it is returned.  If it's a Just and its only payload is a Maybe,
the inner Maybe is returned.  Other cases raise an error.
@c JP
@var{maybe}がNothingならそのまま返されます。
それがJustで、一つだけの値を持ち、その値がMaybeならそれが返されます。
それ以外の場合はエラーが投げられます。
@c COMMON
@end defun

@defun either-join either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{either} is a Left, it is returned.
If it is a Right and its only payload is an Either,
the inner Either is returned.  Other cases raise an error.
@c JP
@var{either}がLeftならそのまま返されます。
それがRightで、一つだけの値を持ち、その値がEitherならそれが返されます。
それ以外の場合はエラーが投げられます。
@c COMMON
@end defun

@defun maybe-bind maybe mproc mproc2 @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Monadic @var{bind} operation.  The @var{maybe} argument must be a Maybe,
and each @var{mproc} @var{mproc2} @dots{} must be a procedure that returns
a Maybe.

If @var{maybe} is a Nothing, it is returned.
If it is a Just, its payload object(s) is/are applied to a procedure
@var{mproc}, which must return a Maybe.  If @var{mproc2} @dots{} are
given, the same operation is repeated on them.
@c JP
モナドの@var{bind}です。@var{maybe}はMaybeでなければならず、
@var{mproc} @var{mproc2} @dots{}のそれぞれはMaybeを返す手続きでなければなりません。

@var{maybe}がNothingならそれがそのまま返されます。
Justの場合は、そのペイロードを引数として@var{mproc}が呼ばれます。
@var{mproc2} @dots{}があれば同様に操作が繰り返されます。
@c COMMON

@example
(maybe-bind m p p2)
  @equiv{} (maybe-bind (maybe-bind m p) p2)
@end example
@end defun

@defun either-bind either mproc mproc2 @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Monadic @var{bind} operation.  The @var{either} argument must be an Either,
and each @var{mproc} @var{mproc2} @dots{} must be a procedure
that returns an Either.

If @var{either} is a Left, it is returned as is.
If it is a Right, its payload object(s) is/are applied to a procedure
@var{mproc}, which must return an Either.  If @var{mproc2} @dots{} are
given, the same operation is repeated on them.
@c JP
モナドの@var{bind}です。@var{either}はEitherでなければならず、
@var{mproc} @var{mproc2} @dots{}のそれぞれはEitherを返す手続きでなければなりません。

@var{either}がLeftならそれがそのまま返されます。
Rightの場合は、そのペイロードを引数として@var{mproc}が呼ばれます。
@var{mproc2} @dots{}があれば同様に操作が繰り返されます。
@c COMMON

@example
(either-bind e p p2)
  @equiv{} (either-bind (either-bind e p) p2)
@end example
@end defun

@defun maybe-compose mproc mproc2 @dots{}
@defunx either-compose mproc mproc2 @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Each argument must be a procedure taking zero or more arguments
and return a Maybe/an Either.   Returns a procedure that accepts zero or more
arguments and returns a Maybe/an Either.
@c JP
@var{mproc} @var{mproc2} @dots{} はそれぞれ、ゼロ個以上の引数を取り
Maybe/Eitherを返す手続きでなければなりません。
返り値は、ゼロ個以上の引数を取りMaybe/Eitherを返す手続きになります。
@c COMMON

@c EN
When the returned procedure is called, it first calls @var{mproc};
if it returns a Nothing/Left, or there's no more mprocs, the result is
returned.  If the result is a Just, its payload is applied
to the next mproc, and so on.
@c JP
作られた手続きが呼ばれると、まず@var{mproc}が呼ばれます。それがNothing/Left
を返した場合、あるいはもう@var{mproc}が無い場合はそれがそのまま返されます。
Just/Rightの場合は、そのペイロードを引数として次の@var{mproc}が呼ばれ、
それが繰り返されます。
@c COMMON

@example
(maybe-bind m p p2 ...)
  @result{} (maybe-ref m (^[] (nothing))
              (maybe-compose p p2 ...))
@end example
@end defun


@node Maybe and Either sequence operations, Maybe and Either protocol converters, Maybe and Either accessors, Maybe and Either optional container types
@subsection Sequence operations
@c NODE MaybeとEither - シーケンス操作, シーケンス操作

@c EN
A Maybe and an Either can be a container of @emph{zero or one element}, and
we have several procedures that employ this view.
(Note: For this purpose, we treat multiple payload values as a whole,
since they are processed in one step---as if we don't regard
multiple procedure arguments and multiple return values as a sequence
of individual values.)
@c JP
MaybeとEitherは、@emph{0個または1個の要素を持つ}シーケンスとみなせます。
この視点からMaybe/Eitherを扱う手続きがいくつかあります
(註: この用途においては、複数のペイロードはひとまとめにして1要素と
して扱われます。手続き呼び出しや手続きからのリターンが、いくつ引数や返り値が
あってもワンステップと考えられるのと同様です)。
@c COMMON

@defun maybe-length maybe
@defunx either-length either
[SRFI-189]
@c MOD srfi.189
@c EN
Returns 0 if @var{maybe}/@var{either} is a Nothing/Left, and
1 if it is a Just/Right.  An error is thrown if the argument
isn't a Maybe/an Either.
@c JP
@var{maybe}/@var{either}がNothing/Leftなら0を、
Just/Rightなら1を返します。
引数がMaybe/Eitherでなければエラーが投げられます。
@c COMMON
@end defun

@defun maybe-filter pred maybe
@defunx either-filter pred either obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe}/@var{either} is a Nothing/Left,
returns a Nothing/a Left of @var{obj} @dots{}.
If @var{maybe}/@var{either} is a Just/a Right, apply @var{pred} on
its payload value(s).  If @var{pred} returns a true value,
@var{maybe}/@var{either} is returned; otherwise,
a Nothing/a Left of @var{obj} @dots{} is returned.

An error is thrown if @var{maybe}/@var{either} isn't a Maybe/an Either.
@c JP
@var{maybe}/@var{either}がNothing/Leftなら、
それぞれNothingもしくは@var{obj} @dots{}をペイロードに持つLeftを返します。
@var{maybe}/@var{either}がJust/Rightなら、そのペイロードを引数として
@var{pred}を呼び、それが真の値を返したら
@var{maybe}/@var{either}がそのまま返されます。
そうでなければNothingもしくは@var{obj} @dots{}をペイロードに持つLeftが返されます。
@c COMMON
@end defun

@defun maybe-remove pred maybe
@defunx either-remove pred either obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Like @code{maybe-filter}/@code{either-filter}, but the meaning of
@var{pred} is reversed.
@c JP
@var{pred}の意味が逆になることを除いて、
@code{maybe-filter}/@code{either-filter}と同じです。
@c COMMON
@end defun

@defun maybe-sequence mappable cmap :optional aggregator
@defunx either-sequence mappable cmap :optional aggregator
[SRFI-189]
@c MOD srfi.189
@c EN
This converts a collection of Maybes/Eithers to a Maybe/an Either of
a collection.  The input collection and the collection in the output can
be of different type.
@c JP
この手続きは、Maybe/Eitherのコレクションを、
コレクションのMaybe/Eitherへと変換します。
入力となるコレクションと出力となるコレクションの型は違っていても構いません。
@c COMMON

@c EN
It's easier to explain using Haskell-ish type signatures, although
it's not precisely specified.  Suppose @code{Container x} is
some kind of a collection of
type @code{x}, and @code{a*} is multiple values of arbitrary types.
@c JP
これは、Haskell的なタイプシグネチャを使った方が(厳密ではありませんが)
わかりやすいでしょう。
@code{Container x}を何らかの型@var{x}のオブジェクトのコレクション、
@code{a*}を任意の型の多値とします。
@c COMMON

@example
Mappable   = Container Maybe a*
CMap       = ((Maybe a* -> b) -> Container Maybe a* -> Container' b
Aggregator = a* -> b

maybe-sequence :: Mappable -> CMap -> Aggregator -> Container' b
@end example

@c EN
If all the elements in the input is Justs,
the @var{cmap} maps the first argument procedure
over the input container (@var{mappable}),
and gathers the result into another container.  It can be any containers,
as long as it matches the @var{mappable} argument.  For example, @var{mappable}
may be a vector of Maybes, and @var{cmap} can be @code{vector-map}--in that case,
both @code{Container} and @code{Container'} are vectors.
Or, @var{mappable} may be a list of Maybes, and @var{cmap} can be
@code{(cut map-to <string> <> <>)}, then @code{Container} is a list and
@code{Container'} is a string.
@c JP
入力コンテナの要素が全てJustであれば、
@var{cmap}は最初の引数である手続き入力のコンテナ@var{mappable}の各要素に適用し、
結果を別のコンテナに集積します。@var{mappable}と型があってさえいれば、
各コンテナの型は任意です。
例えば@var{mappable}にMaybeのベクタ、@var{cmap}に@code{vector-map}を
渡すことができます。この場合、@code{Container}と@code{Container'}の型は
どちらもベクタです。あるいは、@var{mappable}はMaybeのリストで、
@var{cmap}に@code{(cut map-to <string> <> <>)}を渡すこともできます。
この場合、@code{Container}はリスト、@code{Container'}は文字列となります。
@c COMMON

@c EN
The types @code{a*} and @code{b} is determined by the @var{aggregator}
procedure, whose default value is @code{list}.
@c JP
@code{a*}と@code{b}の型は@var{aggregator}手続きにより決定されます。
デフォルトの値は@code{list}です。
@c COMMON

@example
(use gauche.sequence) ; generic map
(map-sequence (vector (just 'a 'b) (just 'c 'd 'e) (just 'f))
              map
              vector)
  @result{} #<Just (#(a b) #(c d e) #(f))>
@end example

@c EN
If there's Nothing in the input container, it is returned.
@c JP
入力コンテナの中にNothingがあればそれがそのまま返されます。
@c COMMON

@c EN
The operation of @code{either-sequence} is similar, with replacing
Just/Nothing with Right/Left.  If input sequence contains Lefts,
the first Left is returned as is.
@c JP
@code{either-sequence}の動作も、Just/NothingをRight/Leftに入れ替える
だけで同様です。入力シーケンスにLeftが含まれていた場合は
最初のLeftがそのまま返されます。
@c COMMON
@end defun

@defun maybe-map proc maybe
@defunx either-map proc either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe}/@var{either} is a Nothing/Left, it is returned as is.
If it is a Just/Right, its payload value(s) is/are passed to @var{proc},
and the result is returned.
@c JP
@var{maybe}/@var{either}がNothing/Leftならばそれがそのまま返されます。
Just/Rightである場合は、そのペイロードが@var{proc}に渡され、結果が
Just/Rightにくるんで返されます。
@c COMMON

@example
(maybe-map quotient&remainder (just 18 4))
 @result{} #<Just 4 2>
@end example
@end defun

@defun maybe-for-each proc maybe
@defunx either-for-each proc either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe}/@var{either} is a Nothing/Left, these procedures do nothing.
Otherwise, @var{proc} is applied to the argument's payload values.
The result of @var{proc} is discarded.  Returns an unspecified value.
@c JP
@var{maybe}/@var{either}がNothing/Leftならば何もしません。
Just/Rightならば、そのペイロードを引数として@var{proc}が呼ばれます。
@var{proc}の結果は捨てられます。
@c COMMON
@end defun

@defun maybe-fold kons knil maybe
@defunx either-fold kons knil either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe}/@var{either} is a Nothing/Left, @var{knil} is returned.
Otherwise, @var{kons} is called with the argument's payload values, plus
@var{knil}.  What @var{kons} returns becomes the result.
@c JP
@var{maybe}/@var{either}がNothing/Leftなら@var{knil}が返されます。
Just/Rightならそのペイロードおよび@var{knil}を引数として@var{kons}が呼ばれ、
その結果が返されます。
@c COMMON

@example
(maybe-fold vector 'z (just 'a 'b))
  @result{} #(a b z)
@end example
@end defun

@defun maybe-unfold p f g seed @dots{}
@defunx either-unfold p f g seed @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
First, the stop predicate @var{p} is applied to @var{seed} @dots{}.
If it returns a true value, a Nothing / a Left of @var{seed} @dots{} is
returned.  Otherwise, next seed generator @var{g} is applied to
@var{seed} @dots{},
which should return the same number of values as seeds, and passed
to @var{p}.  If @var{p} returns false, it is an error
(since Maybe/Either as a sequence can have at most 1 element).
If @var{p} returns true, @var{f} is applied to @var{seed} @dots{},
then the results are wrapped in a Just/Right to be returned.
@c JP
まず、終了述語@var{p}が@var{seed} @dots{}を引数として呼ばれます。
それが真の値を返したら、Nothingおよび@var{seed} @dots{}をペイロードとする
Leftがそれぞれ返されます。
そうでなければ次のシードを生成する@var{g}が@var{seed} @dots{}を引数として
呼ばれます。@var{g}は引数と同じ数の値を返さねばなりません。
@var{g}の戻り値は@var{p}に渡され終了条件がチェックされます。
もし@var{p}が真の値を返さなかったらエラーが投げられます
(シーケンスとしてのMaybe/Eitherはたかだか1個の要素しか持てないので)。
そうでなければ、@var{seed} @dots{}が値生成手続き@var{f}に渡され、
その結果がJust/Rightにラップされて返されます。
@c COMMON
@end defun


@node Maybe and Either protocol converters, Maybe and Either syntactic utilities, Maybe and Either sequence operations, Maybe and Either optional container types
@subsection Protocol converters
@c NODE MaybeとEither - プロトコル変換, プロトコル変換

@defun maybe->list maybe
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe} is a Just, returns a list of its payload values.
If it is a Nothing, an empty list is retured.
(When the return value is an empty list, it can be either
@var{maybe} is Nothing, or a Just with no value.)
@c JP
@var{maybe}がJustならば、そのペイロードのリストが返されます。
Nothingならば空リストが返されます。
(戻り値が空リストになるのは、@var{maybe}がNothingである場合と
ゼロ個のペイロードを持つJustである場合があります)
@c COMMON

@c EN
Note that this is not a convertion from ``Maybe as a sequence''
to a list.  Regarded as a sequence, a Just always contain
one element, which can have multiple values.  This procedure
conceptually resembles to @code{values->list}.
@c JP
これは「シーケンスとしてのMaybe」をリストに変換するものではないことに
注意してください。シーケンスとして見た場合、Justはつねに一つだけの
要素を持ちます。ただ、その要素が多値である場合があります。
この手続きは概念的には@code{values->list}に似ています。
@c COMMON
@end defun

@defun list->maybe lis
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{lis} is an empty list, a Nothing is returned.
Otherwise, a Just that has elements in @var{lis} as payload values
is returned.
@c JP
@var{lis}が空リストならNothingが、そうでなければ
@var{lis}の各要素をペイロードとして持つJustが返されます。
@c COMMON

@c EN
Note that @code{(list->maybe (maybe->list x))} isn't an identity
mapping---if @var{x} is a Just with zero payload values, you'll get
a Nothing.
@c JP
@code{(list->maybe (maybe->list x))}は恒等関数ではないことに
注意して下さい。@var{x}がゼロ個のペイロードを持つJustの場合、
この式はNothingを返します。
@c COMMON
@end defun

@defun either->list either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{either} is a Right, returns a list of its payload values.
If it is a Left, returns an empty list.
(When the return value is an empty list, it can be either
@var{either} is Left, or a Right with no value.)
@c JP
@var{maybe}がRightならば、そのペイロードのリストが返されます。
Leftならば空リストが返されます。
(戻り値が空リストになるのは、@var{either}がLeftである場合と
ゼロ個のペイロードを持つRightである場合があります)
@c COMMON
@end defun

@defun list->either lis obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{lis} is an empty list, a Left of @var{obj} @dots{} is returned.
Otherwise, a Right that has elements in @var{lis} as payload values
is returned.
@c JP
@var{lis}が空リストなら@var{obj} @dots{}をペイロードとして持つLeftが、
そうでなければ@var{lis}の各要素をペイロードとして持つRightが返されます。
@c COMMON
@end defun

@defun maybe->truth maybe
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe} is a Nothing, @code{#f} is returned.
Otherwise, it must be a Just with one value, and its value is returned.
If @var{maybe} is a Just and it doesn't have exactly one value, an error
is thrown.  If you want to deal with arbitrary number of payload values,
use @code{maybe->list-truth}.

Note that if you get @code{#f}, you can't distinguish if the input
is @code{(nothing)} or @code{(just #f)}.    This procedure can be seen as
an adaptor between Maybe interface and the traditional ``quasi-maybe''
pattern used in place
of true maybe type---e.g. @code{find} returns @code{#f} if no elements
satisfied the predicate, but can't handle if the element that satisfies
the predicate is @code{#f}.
@c JP
@var{maybe}がNothingなら@code{#f}が、ペイロードとして値をひとつだけ持つJustなら
その値が返されます。ペイロードに1つ以外の値を持つJustだった場合は
エラーが投げられます。任意のペイロードを扱いたい場合は
下の@code{maybe->list-truth}を使って下さい。

@code{#f}が帰って来た場合に、元がNothingだったのか@code{#f}を値として
持つJustだったのか区別できないことに注意してください。
この手続きは、Maybeインタフェースと、従来の「Maybe的な」インタフェースとの
橋渡しをします。例えば@code{find}は述語を満たす要素が無かった場合に
@code{#f}を返しますが、「述語を満たす要素」が@code{#f}である場合を扱えません。
その意味で「Maybe的な」インタフェースは不完全なんですが、それを期待している
従来のコードにMaybeを使った結果を返したい場合にこの手続きが使えます。
@c COMMON
@end defun

@defun truth->maybe obj
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{obj} is @code{#f}, returns a Nothing.
Otherwise, returns a Just with @var{obj} as its payload.
@c JP
@var{obj}が@code{#f}ならNothingを、そうでなければ
@var{obj}をペイロードに持つJustを返します。
@c COMMON

@c EN
Note that @code{(truth->maybe (maybe->truth x))} isn't an identity mapping---
if @var{x} is a Just wrapping @code{#f}, you'll get a Nothing.
@c JP
@code{(truth->maybe (maybe->truth x))}は恒等関数ではないことに注意して下さい。
@var{x}が@code{(just #f)}だった場合、この式の値はNothingになります。
@c COMMON
@end defun

@defun either->truth either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{either} is a Left, @code{#f} is returned.
Otherwise, it must be a Right with one value, and its value is returned.
@c JP
@var{either}がLeftなら@code{#f}が、
ひとつの値を持つRightならその値が返されます。
@c COMMON

@c EN
If @var{either} is a Right and it doesn't have exactly one value, an error
is thrown.  If you want to deal with arbitrary number of payload values,
use @code{either->list-truth}.
@c JP
@var{either}が一つ以外の値を持つRightであった場合はエラーが投げられます。
任意個のペイロードを持つRightを扱いたい場合は
@code{either->list-truth}が使えます。
@c COMMON
@end defun

@defun truth->either obj fail-obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{obj} is @code{#f}, returns a Left with @var{fail-obj} @dots{} is
returned.
Otherwise, returns a Right with @var{obj} as its payload.
@c JP
@var{obj}が@code{#f}なら@var{fail-obj} @dots{}をペイロードに持つLeftが、
そうでなければ@var{obj}をペイロードに持つRightが返されます。
@c COMMON
@end defun

@defun maybe->list-truth maybe
[SRFI-189]
@c MOD srfi.189
@c EN
Like @code{maybe->list}, it returns @code{#f} if @var{maybe} is a Nothing.
If @var{maybe} is a Just, however, it returns a list of its payload values.
@c JP
@code{maybe->list}と同じように、@var{maybe}がNothingの場合は@code{#f}を
返しますが、Justの場合はペイロードのリストを返します。
@c COMMON
@end defun

@defun list-truth->maybe lis-or-false
[SRFI-189]
@c MOD srfi.189
@c EN
The argument must be @code{#f} of a list.  If it is @code{#f}, a Nothing
is returned.  If it is a list, a Just with elements of the list is
returned.

@code{(list-truth->maybe (maybe->list-truth x))} is an identity mapping.
@c JP
引数はリストか@code{#f}でなければなりません。
引数が@code{#f}ならばNothingが返されます。
引数がリストの場合は、それらの各要素をペイロードとするJustが返されます。

@code{(list-truth->maybe (maybe->list-truth x))}はxの恒等写像です。
@c COMMON
@end defun

@defun either->list-truth either
[SRFI-189]
@c MOD srfi.189
@c EN
Like @code{either->list}, it returns a list of payload values if
@var{either} is a Right.  If @var{either} is a Left,
however, it returns @code{#f}.
@c JP
@code{either->list}と同じように、@var{either}がRightならば
そのペイロードの値のリストが返されます。
しかし@var{either}がLeftの場合は@code{#f}が返されます。
@c COMMON
@end defun

@defun list-truth->either lis-or-false fail-objs @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{list-or-false} argument must be @code{#f} of a list.
If it is @code{#f}, a Left with @var{fail-objs} @dots{}
is returned.  If it is a list, a Right with elements of the list is
returned.
@c JP
@var{list-or-false}引数はリストか@code{#f}でなければなりません。
@code{#f}の場合は、@var{fail-objs} @dots{}をペイロードとするLeftが、
リストの場合はその各要素をペイロードとするRightが返されます。
@c COMMON
@end defun

@defun maybe->generation maybe
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe} is a Nothing, an EOF object is returned.
Otherwise, it must be a Just with one value, and its value is returned.
If @var{maybe} is a Just and it doesn't have exactly one value, an error
is thrown.
@c JP
@var{maybe}がNothingならEOFを、
ペイロードをひとつ持つJustならその値を返します。
それ以外の場合はエラーが投げられます。
@c COMMON
@end defun

@defun generation->maybe obj
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{obj} is an EOF value, a Nothing is returned.
Otherwise, a Just wrapping @var{obj} is returned.
@c JP
@var{obj}がEOFならNothingが、
そうでなければ@var{obj}をペイロードとするJustが返されます。
@c COMMON
@end defun

@defun either->generation either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{either} is a Left, an EOF object is returned.
Otherwise, it must be a Right with one value, and its value is returned.
If @var{either} is a Right and it doesn't have exactly one value, an error
is thrown.
@c JP
@var{either}がLeftならEOFを、
ペイロードをひとつ持つRightならその値を返します。
それ以外の場合はエラーが投げられます。
@c COMMON
@end defun

@defun generation->either obj fail-objs @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{obj} is an EOF value, a Left with @var{fail-objs} @dots{} is returned.
Otherwise, a Right wrapping @var{obj} is returned.
@c JP
@var{obj}がEOなら@var{fail-objs} @dots{}をペイロードに持つLeftが、
そうでなければ@var{obj}をペイロードに持つRightが返されます。
@c COMMON
@end defun

@defun maybe->values maybe
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe} is a Just, returns its payload as multiple values.
If it is a Nothing, returns no values.
(Note that a Just with zero values also returns no values.)
@c JP
@var{maybe}がJustなら、そのペイロードを多値で返します。
Nothingならゼロ個の値を返します。
(ゼロ個のペイロードを持つJustだった場合もゼロ個の値が返されることに注意してください)。
@c COMMON
@end defun

@defun values->maybe producer
[SRFI-189]
@c MOD srfi.189
@c EN
It first invokes a procedure @var{producer} with no values.
If it returns zero values, a Nothing is returned; otherwise,
a Just with those values are returned.
@c JP
まず手続き@var{producer}を引数なしで呼び出します。
それがゼロ個の値を返した場合はNothingが、そうでなければ
値をペイドーロとするJustが返されます。
@c COMMON
@end defun

@defun either->values either
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{either} is a Right, returns its payload as multiple values.
If it is a Left, returns no values.
(Note that a Right with zero values also returns no values.)
@c JP
@var{either}がRightなら、そのペイロードを多値で返します。
Leftならゼロ個の値を返します。
(ゼロ個のペイロードを持つRightだった場合もゼロ個の値が返されることに注意してください)。
@c COMMON
@end defun

@defun values->either producer fail-obj @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
It first invokes a procedure @var{producer} with no values.
If it returns zero values, a Left with @var{fail-obj} @dots{} as
its payload is returned.
If it returns one or more values,
a Right with those values are returned.
@c JP
まず手続き@var{producer}を引数なしで呼び出します。
それがゼロ個の値を返した場合は、@var{fail-obj} @dots{}をペイロードとする
Leftが、そうでなければ値をペイドーロとするRightが返されます。
@c COMMON
@end defun

@defun maybe->two-values maybe
[SRFI-189]
@c MOD srfi.189
@c EN
If @var{maybe} is a Just with exactly one value, the value and @code{#t}
is returned.  If @var{maybe} is a Nothing, two @code{#f} is returned.
An error is thrown if @var{maybe} has a Just with zero or more than two
values.

The second value allows the caller to distinguish whether the input is
a Nothing or a Just with @code{#f} in the payload.
@c JP
@var{maybe}がひとつのペイロードを持つJustであれば、その値と@code{#t}を
2つの値として返します。
@var{maybe}がNothingならば、2つの@code{#f}を返します。
@var{maybe}がそれ以外の場合はエラーが投げられます。

2つ目の値によって、呼び出し側は引数がNothingだったのか
@code{#f}をペイロードに持つJustだったのかを区別できます。
@c COMMON
@end defun

@defun two-values->maybe producer
[SRFI-189]
@c MOD srfi.189
@c EN
The inverse of @code{maybe->two-values}.  A procedure @var{producer}
is called with no arguments.  It must return two values, a possible
payload value, and a boolean.  If the second value is true,
a Just with the first value is returned.  If the second value is @code{#f},
a Nothing is returned (the first return value is ignored).
@c JP
@code{maybe->two-values}の逆です。
手続き@var{producer}が引数無しで呼ばれます。それは2つの値を返さねばなりません。
2つ目の値が真ならば、1つ目の値をペイロードとするJustが、
そうでなければNothingが返されます(1つ目の値は捨てられます)。
@c COMMON
@end defun

@defun exception->either pred thunk
[SRFI-189]
@c MOD srfi.189
@c EN
A procedure @var{thunk} is called without argument, wrapped by an
exception handler.  If @var{thunk} raises a condition, it is
examined by @var{pred}.  If @var{pred} returns true on the condition,
the exception is wrapped by a Left and returned.
If @var{pred} returns @code{#f}, the exception is reraised.
If no exception is raised, the result(s) of @var{thunk} is wrapped
by a Right and returned.
@c JP
例外ハンドラを設定したうえで、手続き@var{thunk}が引数なしで呼ばれます。
@var{thunk}が例外を投げた場合、そのコンディションオブジェクトが@var{pred}に
渡されます。@var{pred}が真を返した場合は、コンディションがLeftにラップされて
返されます。@var{pred}が@code{#f}を返した場合は同じ例外が再び投げられます。
例外が投げられなかった場合は、@var{thunk}の戻り値がRightにラップされて
返されます。
@c COMMON
@end defun

@node Maybe and Either syntactic utilities, Trivalent logic, Maybe and Either protocol converters, Maybe and Either optional container types
@subsection Syntactic utilities
@c NODE MaybeとEither - 構文ユーティリティ, 構文ユーティリティ

@defmac maybe-if mtest then else
[SRFI-189]
@c MOD srfi.189
@c EN
If the @var{mtest} expression yields a Just, evaluates @var{then}.
If the @var{mtest} expression yeilds a Nothing, evaluates @var{else}.
If the @var{mtest} expression doesn't produce a Maybe, an error
is thrown.
@c JP
@var{mtest}を評価し、それがJustだった場合は@var{then}を、
Nothingだった場合は@var{else}を評価します。
@var{etest}がMaybeを生成しなかった場合はエラーが投げられます。
@c COMMON
@end defmac

@defmac maybe-and maybe @dots{}
@defmacx either-and either @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Evaluates @var{maybe}/@var{either} from left to right, as far as
each yields a Just/Right.  If every expression yields a Just/Right,
the last one is returned.  If it encounters an expression that
yields a Nothing/Left, it stops evaluating the rest of expressions and
returns the Nothing/Left.

If expressions yield something other than Maybe/Either, an error is thrown.
@c JP
@var{maybe}/@var{either}を左から順に、結果がJust/Rightである限り評価してゆきます。
全ての引数がJust/Rightに評価されたなら、最後の値が返されます。
途中でNothing/Leftが得られた場合はそこで評価を打ち切り、そのNothing/Leftを返します。

式がMaybe/Eitherを生成しなかった場合はエラーが投げられます。
@c COMMON
@end defmac

@defmac maybe-or maybe @dots{}
@defmacx either-or either @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Evaluates @var{maybe}/@var{either} from left to right, as far as
each yields a Nothing/Left.   If it encounters an expression that
yields a Just/Right, it stops evaluating the rest of expressions and
returns it.

If expressions yield something other than Maybe/Either, an error is thrown.
@c JP
@var{maybe}/@var{either}を左から順に、結果がNothing/Leftである限り評価してゆきます。
全ての引数がNothing/Leftに評価されたなら、最後の値が返されます。
途中でJust/Rightが得られた場合はそこで評価を打ち切り、そのJust/Rightを返します。

式がMaybe/Eitherを生成しなかった場合はエラーが投げられます。
@c COMMON
@end defmac

@defmac maybe-let* ( claw @dots{} ) body @dots{}
@defmacx either-let* ( claw @dots{} ) body @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
This is a Maybe/Either version of @code{and-let*}.
@c JP
これは@code{and-let*}のMaybe/Eitherバージョンです。
@c COMMON

@c EN
Each @var{claw} can be either one of the following forms:
@table @code
@item @var{identifier}
The @var{identifier}'s value is taken.  It must be a Maybe/an Either,
or an error is signaled.
If it is a Just/Right, evaluation proceeds to the next claw.
If it is a Nothing/Left, evaluation stops and the value is returned
immediately.
@item (@var{identifier} @var{expression})
The @var{expression} is evaluated.  It must yield a Maybe/an Either,
or an error is signaled.
If it is a Just/Right, @var{identifier} is bound to its payload,
and the rest of @var{claw}s and @var{body} are processed with the scope
of @var{identifier}.  If it is a Nothing/Left, evaluation stops and
the value is returned immediately.
An error is signaled if a Just/Right doesn't carry exactly one value.
@item ( @var{expression} )
The @var{expression} is evaluated.  It must yield a Maybe/an Either,
or an error is signaled.
If it is a Just/Right, evaluation proceeds to the next claw.
If it is a Nothing/Left, evaluation stops and the value is returned
immediately.
@end table
@c JP
各@var{claw}は次のいずれかの形式です。
@table @code
@item @var{identifier}
@var{identifier}の値が取り出されます。
それがMaybe/Eitherでなければエラーが投げられます。
それがJust/Rightである場合は、次のclawに評価が進みます。
Nothing/Leftだった場合は評価がそこで打ち切られ、その値が直ちに返されます。
@item (@var{identifier} @var{expression})
@var{expression}が評価されます。
それがMaybe/Eitherでなければエラーが投げられます。
それがJust/Rightである場合は、@var{identifier}がそのペイロードに束縛され、
その束縛が見える環境で残りの@var{claw}と@var{body}が評価されます。
Nothing/Leftだった場合は評価がそこで打ち切られ、その値が直ちに返されます。
@var{expression}が生成するJust/Rightは、ペイロードとして値をひとつ持つ
ものでなければなりません。そうでなければエラーが投げられます。
@item ( @var{expression} )
@var{expression}が評価されます。
それがMaybe/Eitherでなければエラーが投げられます。
それがJust/Rightである場合は、次のclawに評価が進みます。
Nothing/Leftだった場合は評価がそこで打ち切られ、その値が直ちに返されます。
@end table
@c COMMON

@c EN
After all @var{claws} are processed and none yields a Nothing/Left,
@var{body} @dots{} are evaluated, and the result of the last @var{body}
becomes the result of the form.
@c JP
全ての@var{claw}が評価されいずれもNothing/Leftでなかった場合は、@var{body} @dots{}
が評価され、最後の@var{body}の評価値がこのフォームの結果となります。
@c COMMON
@end defmac

@defmac maybe-let*-values ( mv-claw @dots{} ) body @dots{}
@defmacx either-let*-values ( mv-claw @dots{} ) body @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
Multi-value payload version of @code{maybe-let*}/@code{either-let*}.
@c JP
多値ペイロードを使える@code{maybe-let*}/@code{either-let*}です。
@c COMMON

@c EN
Each @var{claw} can be either one of the following forms:
@table @code
@item @var{identifier}
The @var{identifier}'s value is taken.  It must be a Maybe/an Either,
or an error is signaled.
If it is a Just/Right, evaluation proceeds to the next claw.
If it is a Nothing/Left, evaluation stops and the value is returned
immediately.
@item (@var{formals} @var{expression})
The @var{formals} is the same as the formals of the lambda form, that
is, a proper or dotted list of identifiers.

The @var{expression} is evaluated.  It must yield a Maybe/an Either,
or an error is signaled.
If it is a Just/Right, identifiers in the @var{formals} are bound
with the payload of the Just/Right,
and the rest of @var{claw}s and @var{body} are processed with the scope
of those identifiers.  If it is a Nothing/Left, evaluation stops and
the value is returned immediately.
An error is signaled if the formals doesn't match the payload
of the Just/Right.
@item ( @var{expression} )
The @var{expression} is evaluated.  It must yield a Maybe/an Either,
or an error is signaled.
If it is a Just/Right, evaluation proceeds to the next claw.
If it is a Nothing/Left, evaluation stops and the value is returned
immediately.
@end table
@c JP
各@var{claw}は次のいずれかの形式です。
@table @code
@item @var{identifier}
@var{identifier}の値が取り出されます。
それがMaybe/Eitherでなければエラーが投げられます。
それがJust/Rightである場合は、次のclawに評価が進みます。
Nothing/Leftだった場合は評価がそこで打ち切られ、その値が直ちに返されます。
@item (@var{formals} @var{expression})
@var{formals}はlambdaの引数リストと同じ形式、すなわち、
識別子の正式なリストかドットリストです。

@var{expression}が評価されます。
それがMaybe/Eitherでなければエラーが投げられます。
それがJust/Rightである場合は、@var{formals}の各がそのペイロードに束縛され、
その束縛が見える環境で残りの@var{claw}と@var{body}が評価されます。
Nothing/Leftだった場合は評価がそこで打ち切られ、その値が直ちに返されます。
Just/Rightのペイロードと@var{formals}がマッチしない場合はエラーが投げられます。
@item ( @var{expression} )
@var{expression}が評価されます。
それがMaybe/Eitherでなければエラーが投げられます。
それがJust/Rightである場合は、次のclawに評価が進みます。
Nothing/Leftだった場合は評価がそこで打ち切られ、その値が直ちに返されます。
@end table
@c COMMON

@c EN
After all @var{claws} are processed and none yields a Nothing/Left,
@var{body} @dots{} are evaluated, and the result of the last @var{body}
becomes the result of the form.
@c JP
全ての@var{claw}が評価されいずれもNothing/Leftでなかった場合は、@var{body} @dots{}
が評価され、最後の@var{body}の評価値がこのフォームの結果となります。
@c COMMON
@end defmac

@defmac either-guard pred body @dots{}
[SRFI-189]
@c MOD srfi.189
@c EN
The @var{body} @dots{} is evaluated, and the value(s) it produces
are wrapped in a Right and returned.  If an exception occurs in
@var{body} @dots{}, the thrown condition is passed to a predicate @var{pred}.
If the condition satisfies the predicate, it is wrapped in a Left
and returned.  Otherwise, the condition is reraised with
@code{raise-continuable.}
@c JP
@var{body} @dots{} が評価され、その結果がRightにラップされて返されます。
もし@var{body} @dots{}の実行中にエラーが起きた場合、
投げられたコンディションが@var{pred}に渡されます。@var{pred}が真の値を返した場合は
それがLeftにラップされて返されます。@var{pred}が@code{#f}を返した場合は
コンディションが@code{raise-continuable}で再び投げられます。
@c COMMON
@end defmac

@node Trivalent logic,  , Maybe and Either syntactic utilities, Maybe and Either optional container types
@subsection Trivalent logic

This section describes procedures that deal with trivalent logic---a value can
be a false value (@code{Just #f}), a true value
(@code{Just} with anything other than @code{#f}), and @code{Nothing}.

If any of the arguments is @code{Nothing}, the result becomes @code{Nothing}
(except @code{tri=?}).

All the argument must be Maybe type, or an error is signalled.

@defun tri-not maybe
[SRFI-189]
@c MOD srfi.189
Returns @code{Just #t} if @var{maybe} is trivalent-false,
@code{Just #f} if @var{maybe} is triavlent-true, and
@code{Nothing} if @var{maybe} is @code{Nothing}.
@end defun

@defun try=? maybe @dots{}
[SRFI-189]
@c MOD srfi.189
Returns @code{Just #t} if arguments are either all trivalent-true
or all trivalent-false.  Otherwise return @code{Just #f}.
Note that if any of the argument is @code{Nothing}, the result is
@code{Just #f} (even all arguments are @code{Nothing}).
@end defun

@defun try-and maybe @dots{}
[SRFI-189]
@c MOD srfi.189
Returns @code{Just #t} if all arguments are trivalent-true,
@code{Just #f} if all arguments are @code{Just} but at least one
of them is @code{Just #f}, and @code{Nothing} if any of the arguments
is @code{Nothing}.  If there's no arguments, @code{Just #t} is returned.

This is not a shortcut operation like @code{and}.
@end defun

@defun try-or maybe @dots{}
[SRFI-189]
@c MOD srfi.189
Returns @code{Just #f} if all arguments are trivalent-false,
@code{Just #t} if all arguments are @code{Just} but at least one
of them is trivalent-true, and @code{Nothing} if any of the arguments
is @code{Nothing}.  If there's no arguments, @code{Just #f} is returned.

This is not a shortcut operation like @code{or}.
@end defun

@defun try-merge maybe @dots{}
[SRFI-189]
@c MOD srfi.189
If all arguments are @code{Nothing}, @code{Nothing} is returned.
Otherwise, first @code{Just} is returned.
@end defun

@c ----------------------------------------------------------------------
@node Coroutine generators, Port positioning, Maybe and Either optional container types, Library modules - SRFIs
@section @code{srfi.190} - Coroutine generators
@c NODE コルーチンジェネレータ,  @code{srfi.190} - コルーチンジェネレータ

@deftp {Module} srfi.190
@mdindex srfi.190
@c EN
This module provides a macro, @code{coroutine-generator},
that simplifies defining a generator-based coroutine.
@c JP
このモジュールは、ジェネレータを元にしたコルーチンの定義を簡単にするマクロ
@code{coroutine-generator}を提供します。
@c COMMON
@end deftp

@defmac coroutine-generator body @dots{}
[SRFI-190]
@c MOD srfi.190
@c EN
Returns a generator procedure.  When called first,
the created generator procedure executes @var{body} from the beginning.
If a syntax @code{yield} appears within @var{body}, it is evaluated to
the yielding procedure.  When the yielding procedure is called, the
continuation of the rest of @var{body} is saved and the control returns
to the caller of the generator.  When the generator is called again,
it resumes from the saved continuation.  If @var{body} evaluates to the
last expression, it's the end of generator and the generator returns EOF.
@c JP
ジェネレータ手続きを返します。作られたジェネレータ手続きは、最初に呼ばれると
@var{body}を最初から順に実行します。
@var{body}の中に構文@code{yield}が現れた場合、
それは制御を譲る手続き(yielding procedure)に評価され、
それが呼ばれると@var{body}の残りの部分の継続が保存されて制御がジェネレータの
呼び出し元に戻ります。ジェネレータが再び呼ばれると、保存されていた継続が再起動されます。
@var{body}の最後の式の評価が終わると、
ジェネレータからEOFが返されてジェネレータの終端となります。
@c COMMON

@c EN
The @code{coroutine-generator} expression can be similary expressed
with @code{make-coroutine-generator} (@pxref{Generator constructors}),
by explicitly introducing a variable bound to the yielding procedure:
@c JP
@code{coroutine-generator}とほぼ同じことは、
@code{make-coroutine-generator}を使って制御を譲る手続きを受け取る変数を明示
することでも実現できます(@ref{Generator constructors}参照)。
@c COMMON

@example
(make-coroutine-generator
  (lambda (yield) body @dots{}))
@end example

@c EN
The difference is that, with this SRFI,
@var{yield} is not a lexically bound variable, but rather
a syntax parameter (@pxref{Syntax parameters}).
@c JP
違いは、このSRFIでは@var{yield}はレキシカル変数ではなく構文パラメータであることです
(@ref{Syntax parameters}参照)。
@c COMMON
@end defmac

@defmac yield
[SRFI-190]
@c MOD srfi.190
@c EN
A syntax parameter that evaluates to the yielding procedure
within @code{coroutine-generator}.  It is an error if it appears outside of
the body of @code{coroutine-generator}.
@c JP
@code{coroutine-generator}の中では、制御を譲る手続きへと評価される
構文パラメータです。@code{coroutine-generator}で使われた場合はエラーとなります。
@c COMMON
@end defmac

@defmac define-coroutine-generator name body @dots{}
@defmacx define-coroutine-generator (name . formals) body @dots{}
[SRFI-190]
@c MOD srfi.190
@c EN
These are shorthand of the following:
@c JP
それぞれ以下の形式の略記です。
@c COMMON

@example
(define name (coroutine-generator body @dots{}))

(define (name . formals) (coroutine-generator body @dots{}))
@end example
@end defmac

@c ----------------------------------------------------------------------
@node Port positioning, Command line, Coroutine generators, Library modules - SRFIs
@section @code{srfi.192} - Port positioning
@c NODE ポート位置,  @code{srfi.192} - ポート位置

@deftp {Module} srfi.192
@mdindex srfi.192
@c EN
This srfi defines procedures to get and set the current position of
the port.

This feature is already supported in the Gauche core, so the following
procedure is described in @ref{Common port operations}.
@c JP
このsrfiはポートの現在の位置を取得したり設定したりする手続きを提供します。

この機能はGaucheのコアでサポートされており、以下の手続きは
@ref{Common port operations}で説明されています:
@c COMMON
@example
port-position
port-has-port-position?
set-port-position!
port-has-set-port-position?
@end example
@end deftp

@defun make-i/o-invalid-position-error pos
[SRFI-192]
@c MOD srfi.192
@c EN
This portably creates a condition suitable to be raised from
@code{set-port-position!} when the given position object can't
be accepted.  The @var{pos} argument is the offending position object.
@c JP
これは、@code{set-port-position!}が不正な位置情報を受け取った時に
投げるべきコンディションを作成するポータブルな手続きです。
@var{pos}引数は問題となった位置情報でう。
@c COMMON

@c EN
In Gauche, such condition is represented by
@code{<io-invalid-position-error>} class, which is a subclass
of @code{<port-error>}.
@c JP
Gaucheでは、その場合のコンディションは@code{<port-error>}のサブクラスである
@code{<io-invalid-position-error>}のインスタンスで表されています。
@c COMMON

@c EN
If you raise a condition created with this procedure from
the @code{set-position!} callback of the custom ports
(@pxref{Custom ports}), Gauche intercepts it and adds
the port information to the condition.
@c JP
カスタムポート(@ref{Custom ports}参照)の@code{set-position!}コールバック手続き
の中で、この手続きで作ったコンディションを投げた場合、
Gaucheはその例外をインターセプトして、ポートの情報をコンディションに付け加えます。
@c COMMON
@end defun

@defun i/o-invalid-position-error? obj
[SRFI-192]
@c MOD srfi.192
@c EN
Returns @code{#t} iff @var{obj} is an i/o-invalid-position-error
condition (or a compound condition that includes it).

In Gauche, it is the same as
@code{(condition-has-type? @var{obj} <io-invalid-position-error>)}.
@c JP
@var{obj}がi/o-invalid-position-errorか、
それを含む複合コンディションであれば@code{#t}を、そうでなければ@code{#f}を返します。

Gaucheでは、これは
@code{(condition-has-type? @var{obj} <io-invalid-position-error>)}
と同じことです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Command line, Random data generators (SRFI), Port positioning, Library modules - SRFIs
@section @code{srfi.193} - Command line
@c NODE コマンドライン,  @code{srfi.193} - コマンドライン

@deftp {Module} srfi.193
@mdindex srfi.193
@c EN
This srfi clarifying how the command line arguments can be accessed
via R7RS @code{command-line}, plus a few supporting APIs.
@c JP
このsrfiは、R7RSの@code{command-line}が返す値についての仕様を
明確化し、またいくつかのサポートAPIを定義しています。
@c COMMON

@c EN
The following procedures are built-in.  @xref{Command-line arguments},
for the details.
@c JP
次の手続きは組み込みになっています。
@ref{Command-line arguments}を参照してください。
@c COMMON

@example
command-line          script-file
@end example
@end deftp

@defun command-name
[SRFI-193]
@c MOD srfi.193
@c EN
If the first element of @code{command-line} is an empty string,
returns @code{#f}.  Otherwise, returns the first element without directory
name and obvious extension (@code{.scm}, @code{.exe}) stripped.
@c JP
@code{command-line}の最初の要素が空文字列であれば@code{#f}を、
そうでなければ@code{command-line}の最初の要素からディレクトリパスと
典型的な拡張子(@code{.scm}、@code{.exe})を除いた名前を返します。
@c COMMON

@c EN
For example, if you run a Scheme script @code{foo.scm}
as a program, this procedure returns @code{foo}.  If you compile
your script to an executable on Windows as the name
@code{/usr/local/bin/foo.exe}, this procedure still returns @code{foo}.
In general, if you are running a Scheme program as some sort of 'command',
this procedure returns its name.  The exception is when you're running
a REPL, in which case this procedure returns @code{#f}.
@c JP
例えば、Schemeスクリプトを@code{/usr/local/bin/foo.scm}を
プログラムとして走らせたら、この手続きは@code{foo}を返します。
このスクリプトをWindows実行可能形式にコンパイルして
@code{/usr/local/bin/foo.exe}に置いたとしても、やはりこの手続きは@code{foo}を返します。
一般に、Schemeプログラムを何らかの形で「コマンド」として走らせた場合、
その「コマンド名」にふさわしいものが返されます。例外はREPLを走らせている場合で、
@code{#f}が返されます。
@c COMMON

@c EN
This is useful for diagnostic messages, for example.
@c JP
これは診断メッセージ等に便利です。
@c COMMON
@end defun

@defun command-args
[SRFI-193]
@c MOD srfi.193
@c EN
Returns the cdr of @code{(command-line)}.
@c JP
@code{(commnand-line)}のcdrを返します。
@c COMMON
@end defun

@defun script-directory
[SRFI-193]
@c MOD srfi.193
@c EN
Returns the directory part of @code{(script-file)}, if it has a string path.
It always ends with the directory separator.
If @code{(script-file)} is @code{#f}, @code{#f} is returned.
@c JP
@code{(script-file)}の値が文字列なら、そのディレクトリ部分を返します。
この場合、返される文字列の末尾は必ずディレクトリ区切り文字になっています。
@code{(script-file)}が@code{#f}なら@code{#f}が返されます。
@c COMMON

@c EN
This is useful, for example, to find an auxiliary files relative to the
script location.
@c JP
これは例えば、補助ファイルをスクリプトからの相対位置で探すのに便利です。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Random data generators (SRFI), Range objects, Command line, Library modules - SRFIs
@section @code{srfi.194} - Random data generators (SRFI)
@c NODE SRFIランダムデータジェネレータ, @code{srfi.194} - ランダムデータジェネレータ (SRFI)

@deftp {Module} srfi.194
@mdindex srfi.194
This module provides a set of generators (@pxref{Generators}) that yield
random data of specific distributions.

Gauche has its own random data generator module @code{data.random}
(@pxref{Random data generators}), which was a basis of this SRFI,
although procedure names are adjusted to match other SRFIs.
This SRFI also adds several advanced random data generators.
@end deftp

@subheading Random sources

@deffn {Parameter} current-random-source
[SRFI-194]
@c MOD srfi.194
The value of this parameter must be a SRFI-27 random source.
Generators created in this module use the value of this parameter
at the time of creation as a random source.  Changing this after
a generator is created won't affect its behavior.

In Gauche, this is just an alias of @code{random-data-random-source}
of @code{data.random}.  Rebinding either one affects both @code{srfi.194}
and @code{data.random} procedures (@pxref{Random data generators}).
@end deffn

@defun with-random-source random-source thunk
[SRFI-194]
@c MOD srfi.194
Calls @var{thunk} while binding the parameter @code{current-random-source}
to @var{random-source}, which must be a random source
object of srfi-27.
@end defun

@defun make-random-source-generator i
[SRFI-194]
@c MOD srfi.194
Returns a fresh generator that creates
a new random source by @code{make-random-source}, and
process it with @code{random-source-pseudo-randomize!} with @var{i},
and internal counter @var{j}, starting from 0 and incremented
every time the generator is called.
@xref{Sources of random bits}, for the details of
@code{make-random-source} and
@code{random-source-pseudo-randomize!}.
@end defun

@subheading Uniform distributions

@defun make-random-integer-generator lower-bound upper-bound
[SRFI-194]
@c MOD srfi.194
Creates and returns a generator that generates exact integers
between @var{lower-bound} (inclusive) and @var{upper-bound}
(exclusive).
Same as calling @code{(integers$ (- upper-bound lower-boud) lower-bound)}
of @code{data.random} (@pxref{Random data generators}).

Note that this is different from @code{integers-between$}, which
includes the upper bound.
@end defun

@defun make-random-u1-generator
@defunx make-random-u8-generator
@defunx make-random-s8-generator
@defunx make-random-u16-generator
@defunx make-random-s16-generator
@defunx make-random-u32-generator
@defunx make-random-s32-generator
@defunx make-random-u64-generator
@defunx make-random-s64-generator
[SRFI-194]
@c MOD srfi.194
Creates and returns a generator of fixed-range exact integers.
Calling @code{make-random-u1-generator} is the same as
@code{(integers$ 2)}, and other generators are
the same as @code{uint8s$}, @code{sint8s$}, etc., of
@code{data.random} (@pxref{Random data generators}).
@end defun

@defun clamp-real-number lower-bound upper-bound value
[SRFI-194]
@c MOD srfi.194
All arguments must be real numbers, and @var{lower-bound} must be
less than or equal to @var{upper-bound}.  If @var{value} is between
two bounds, it is returned as is.  If it is smaller than @var{lower-bound},
@var{lower-bound} is returned.
If it is greater than @var{upper-bound}, @var{upper-bound} is returned.

Similar to Gauche's build-in @code{clamp}, with different argument
order (@pxref{Arithmetics}).
@end defun

@defun make-random-real-generator lower-bound upper-bound
[SRFI-194]
@c MOD srfi.194
Returns a fresh generator that produces a real number between
@var{lower-bound} and @var{upper-bound}, both inclusive.

It is the same as @code{reals-between$} of @code{data.random}
(@pxref{Random data generators}).
@end defun

@defun make-random-rectangular-generator re-lower-bound re-upper-bound im-lower-bound im-upper-bound
@defunx make-random-polar-generator [origin] mag-lower-bound mag-upper-bound :optional angle-lower-bound angle-upper-bound
[SRFI-194]
@c MOD srfi.194
Returns a fresh generator that produces a complex number
uniformly within the area specified by the arguments.
They are the same as @code{complexes-rectangular$} and
@code{complexes-polar$} of @code{data.random}
(@pxref{Random data generators}), respectively.
See their entries for the details.
@end defun

@defun make-random-boolean-generator
[SRFI-194]
@c MOD srfi.194
Returns a fresh generator that produces random boolean values.
It is the same as @code{booleans$} of @code{data.random}
(@pxref{Random data generators}).
@end defun

@defun make-random-char-generator string
[SRFI-194]
@c MOD srfi.194
Returns a fresh generator that produces characters uniformly
sampled from @var{string}.   The order of characters within @var{string}
is irrelevant.  You can repeat characters in @var{stirng} to increase
the chance of that characters to be produced.

It is an error if @var{string} is empty.

This is not the same as @code{chars$}, but rather a type-restricted
case of @code{samples$} of @code{data.random}
(@pxref{Random data generators}).
@end defun

@defun make-random-string-generator k string
[SRFI-194]
@c MOD srfi.194
Returns a fresh generator that produces a random string
of length @var{k} and consisting characters uniformly
sampled from @var{string}.

It is an error if @var{string} is empty.

This is not the same as @code{strings-of} of @code{data.random}.
Rather, this can be written as
@code{(strings-of (integers$ k) (samples$ str))}
(@pxref{Random data generators}).
@end defun

@subheading Nonuniform distributions

@defun make-bernoulli-generator p
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-binomial-generator n p
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-categorical-generator weight-vec
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-normal-generator :optional mean deviation
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-exponential-generator mean
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-geometric-generator p
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-poisson-geneartor L
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-zipf-generator N :optional s q
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-sphere-generator n
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-ellipsoid-generator axes
[SRFI-194]
@c MOD srfi.194
@end defun

@defun make-ball-generator dimensions
[SRFI-194]
@c MOD srfi.194
@end defun

@subheading Generator operations

@defun gsampling generator @dots{}
[SRFI-194]
@c MOD srfi.194
@end defun


@c ----------------------------------------------------------------------
@node Range objects, Pipeline operators, Random data generators (SRFI), Library modules - SRFIs
@section @code{srfi.196} - Range objects
@c NODE レンジオブジェクト, @code{srfi.196} - レンジオブジェクト

@deftp {Module} srfi.196
@mdindex srfi.196
@c EN
This srfi defines @emph{range} object, an abstract immutable sequence.

Gauche's @code{data.range} module provides superset of @code{srfi.196}.
This module re-exports the following procedures from it for the portable
code.
@xref{Range}, for the description of the procedures.
@c JP
このsrfiはレンジオブジェクトを定義します。
レンジオブジェクトは、変更不可なシーケンスを抽象化したものです。

Gaucheは@code{data.range}モジュールで@code{srfi.196}のスーパーセットを
提供しています。このモジュールは、ポータブルなコードのために以下の手続きを
再エクスポートするだけのものです。
レンジオブジェクトについて詳しくは@ref{Range}を参照してください。
@c COMMON

@example
range              numeric-range         iota-range
vector-range       string-range          range-append
range?             range=?               range-length
range-ref          range-first           range-last
range-split-at     subrange              range-segment
range-take         range-take-right
range-drop         range-drop-right
range-count        range-any             range-every
range-map          range-map->list       range-map->vector
range-for-each     range-filter-map      range-filter-map->list
range-filter       range-filter->list
range-remove       range-remove->list
range-fold         range-fold-right      range-reverse
range-index        range-index-right
range-take-while   range-take-while-right
range-drop-while   range-drop-while-right
range->list        range->vector         range->string
vector->range      range->generator
@end example
@end deftp

@c ----------------------------------------------------------------------
@node Pipeline operators, String-notated bytevectors, Range objects, Library modules - SRFIs
@section @code{srfi.197} - Pipeline operators
@c NODE パイプラインオペレータ, @code{srfi.197} - パイプラインオペレータ

@deftp {Module} srfi.197
@mdindex srfi.197
@c EN
This module provides a set of macros to compose multiple operations.
It is similar to Clojure's ``threading macro''.
@c JP
このモジュールは、複数の操作を組み合わせるマクロを提供します。
Clojureの「スレッドマクロ」に似たものです。
@c COMMON

@c EN
When you're passing a result of some procedure to another procedure and
so on, sometimes you get a deeply nested expression:
@c JP
ひとつの関数適用の結果を別の関数に渡して…というのをつなげてゆくと、
しばしば式のネストが深くなってしまいます:
@c COMMON

@example
(g (f (e (d (c (b (a arg)))))))
@end example

@c EN
In Gauche, you can also write the above expression with @code{$} macro
(@pxref{Making procedures}):
@c JP
Gaucheでは@code{$}マクロを使えば上の式はこうも書けます
(@ref{Making procedures}参照):
@c COMMON

@example
($ g $ f $ e $ d $ c $ b $ a arg)
@end example

@c EN
Deep nesting is avoided, but it's still right-to-left, and the placement
of argument to receive the previous result is limited to the last position.
@c JP
ネストは浅くなりましたが、適用順は依然として右から左で、
また前の結果を引数として渡す位置が最後の引数に限られます。
@c COMMON

@c EN
With @code{chain} macro in this module, you can write it
from left to right:
@c JP
このモジュールの@code{chain}マクロを使うと、
上の式は左から右にデータを流すように書けます:
@c COMMON

@example
(chain (a arg) (b _) (c _) (d _) (e _) (f _) (g _))
@end example

@c EN
The @code{_} in the second expressions and after indicates the place
where previous result is passed.
It is conceptually expanded to the following:
@c JP
2番目以降の式中の@code{_}は、前の結果をその位置の引数で受け取ることを示します。
上の式は概念的には次の式と等価です。
@c COMMON

@example
(let* ((tmp (a arg))
       (tmp (b tmp))
       (tmp (c tmp))
       (tmp (d tmp))
       (tmp (e tmp)))
  (g tmp))
@end example

@c EN
Because the placeholder is explicit, you can pass additional arguments:
@c JP
引数をはめ込む場所を明示できるので、他の引数も自由に渡せます:
@c COMMON

@example
(chain x (y a _) (z _ b))
 @equiv{}
 (let* ((tmp x)
        (tmp (y a tmp)))
   (z tmp b))
@end example

@c EN
Or even use multiple values:
@c JP
多値を受け取って複数の引数として渡すこともできます:
@c COMMON

@example
(chain mv-expr (f _ _) (g _ _))
 @equiv{}
 (let*-values (((tmp1 tmp2) mv-expr)
               ((tmp1 tmp2) (f tmp1 tmp2)))
   (g tmp1 tmp2))
@end example

@c EN
@xref{Combinators (SRFI)}, for procedural way to compose chaining
procedure calls.
@c JP
なお、手続き的に手続き呼び出しをチェインするように合成する手段としては
@ref{Combinators (SRFI)}もあります。
@c COMMON
@end deftp

@defmac chain initial-value [placeholder [ellipsis]] step @dots{}
[SRFI-197]
@c MOD srfi.197
@c EN
The optional @var{placeholder} and @var{ellipsis} are, if given,
literal symbols.   It replaces the default placeholder and ellipsis
symbols, @code{_} and @code{...}, respectively.
@c JP
省略可能な@var{placeholder}と@var{ellipsis}引数は、
リテラルシンボルでなければなりません。与えられた場合は、
デフォルトのプレースホルダ@code{_}とエリプシス@code{...}を置き換えます。
@c COMMON

@c EN
Each @var{step} is @code{(@var{datum} @dots{})}, where each @var{datum}
must be either an expression,  placeholder symbol, or the ellipsis symbol.
The ellipsis symbol must appear in the last position, if any,
and must immediately follow the placeholder symbol.
@c JP
各@var{step}は@code{(@var{datum} @dots{})}の形で、
@var{datum}は式、プレースホルダ、あるいはエリプシスです。
但し、エリプシスは最後の要素としてのみ許され、現れた場合は直前がプレースホルダ
でなければなりません。
@c COMMON

@c EN
Conceptually, each @var{step} becomes a procedure that takes as
many arguments as the placeholders.  If the @var{step} ends with
ellipsis symbol, the last placeholder works as the ``rest'' arguments.
@c JP
概念的には、各@var{step}はプレースホルダの数だけ引数を取る手続きへと展開されます。
手続きに渡された引数は順にプレースホルダの箇所に充てられます。
@var{step}の最後がエリプシスだった場合は、直前のプレースホルダが ``rest'' 引数として
動作します。
@c COMMON

@c EN
If a @var{step} expects more than one value, the previous @var{step}
or @var{initial-value} is expected to yield that many values.
@c JP
@var{step}が一つ以上の値を期待する場合、直前の@var{step}もしくは
@var{initial-value}は同じ数だけの値を生成せねばなりません。
@c COMMON

@example
(chain expr (f _ a _ ...))
  @equiv{}
  (let*-values (((tmp1 . tmp2) expr))
    (apply f tmp1 a tmp2))
@end example
@end defmac

@defmac chain-and initial-value [placeholder] step @dots{}
[SRFI-197]
@c MOD srfi.197
@c EN
A variant of @code{chain} that stops and returns @code{#f}
immedialy when the intermediate result becomes @code{#f}.
@c JP
@code{chain}の変種で、中間の結果が@code{#f}になった場合にその後の@var{step}の
評価を行わず直ちに@code{#f}を返します。
@c COMMON

@c EN
The @var{initial-value} is an expression that yields one value.
The @var{placeholder} is a literal symbol to be used as the placeholder
in @var{step}; if omitted, @code{_} is used.
@c JP
@var{initial-value}はひとつの値を返す式です。
@var{placeholder}は@var{step}中でプレースホルダーとして使われるリテラルシンボルです。
省略時には@code{_}が使われます。
@c COMMON

@c EN
Unlike @code{chain}, a @var{step} can only contain zero or one placeholder
symbol.  If @var{step} doesn't contain placeholder symbol, the previous
@var{step}'s result isn't passed, but it is still checked if it's @code{#f}.
@c JP
@code{chain}と違い、各@var{step}はたかだか1個のプレースホルダーしか
含むことができません。@var{step}がプレースホルダーを含んでいない場合、
直前の@var{step}の結果は操作を打ちきるかどうかの判定のみに使われ、その後捨てられます。
@c COMMON
@end defmac

@defmac chain-when initial-value [placeholder] ([guard] step) @dots{}
[SRFI-197]
@c MOD srfi.197
@c EN
A variant of @code{chain} where you can select whether each @var{step}
is applied or skipped.
@c JP
@code{chain}の変種で、@var{step}を適用するかどうかを選べるものです。
@c COMMON

@c EN
Each @var{step} can have at most one placeholder symbol, just as
@code{chain-and}.
@c JP
@code{chain-and}と同じく、各@var{step}はプレースホルダーをたかだか1個までしか
含むことができません。
@c COMMON

@c EN
Each @var{guard} is an expression.  For each step, @var{guard} is
evaluated, and if it yields a true value, the previous result is
passed to the placeholder in the corresponding @var{step}.  If
@var{guard} yields @code{#f}, however, @var{step} is skipped and
the previous value is passed through to the next step.
@c JP
各@var{guard}は式です。各ステップで、まず@var{guard}が評価され、
それが真ならば直前に実行された結果がプレースホルダーに束縛されて
対応する@var{step}が実行されます。@var{guard}が偽ならば、
@var{step}は実行されず、直前の結果が次のステップへと持ち越されます。
@c COMMON

@example
(chain-when expr ((p? x) (f _)) ((q? x) (g _)))
 @equiv{}
 (let* ([tmp expr]
        [tmp (if (p? x) (f tmp) tmp)])
   (if (q? x) (g tmp) tmp))
@end example
@end defmac

@defmac chain-lambda [placeholder [ellipsis]] step @dots{}
[SRFI-197]
@c MOD srfi.197
@example
(chain-lambda step @dots{})
  @equiv{} (lambda args (chain (apply values args) step @dots{}))
@end example
@end defmac

@defmac nest [placeholder] step @dots{} initial-value
[SRFI-197]
@c MOD srfi.197
@c EN
Similar to @code{chain}, except the order of steps is right-to-left.

Each @var{step} must have exactly one placeholder symbol, for
this macro simply nests the steps:
@c JP
@code{chain}と似ていますが、評価順が右から左になります。

各@var{step}はひとつだけプレースホルダーシンボルを持たなければなりません。
このマクロは単にステップをネストした式に変換するだけです。
@c COMMON

@example
(nest (f a _) (g _ b) (h _) expr)
 @equiv{} (f a (g (h expr) b))
@end example
@end defmac

@defmac nest-reverse initial-value [placeholder] step @dots{}
[SRFI-197]
@c MOD srfi.197
@c EN
Similar to @code{nest} except the nesting is in reverse order.

Each @var{step} must have exactly one placeholder symbol, for
this macro simply nests the steps:
@c JP
@code{nest}の評価順が逆になったものです。

各@var{step}はひとつだけプレースホルダーシンボルを持たなければなりません。
このマクロは単にステップをネストした式に変換するだけです。
@c COMMON

@example
(nest expr (h _) (g _ b) (f a _))
 @equiv{} (f a (g (h expr) b))
@end example
@end defmac

@c ----------------------------------------------------------------------
@node String-notated bytevectors, Enums and enum sets, Pipeline operators, Library modules - SRFIs
@section @code{srfi.207} - String-notated bytevectors
@c NODE 文字列表示のバイトベクタ, @code{srfi.207} - 文字列表示のバイトベクタ

@deftp {Module} srfi.207
@mdindex srfi.207
@c EN
This SRFI defines an alternative representation of bytevectors, and
provides a bunch of procedures that can treat a bytevector as a bytestring.
@c JP
このSRFIはバイトベクタの別形式の外部表現を定義し、
バイトベクタをバイト列(bytestring)として扱える多くの手続きを提供します。
@c COMMON

@c EN
Gauche supports 'string' representation of bytevectors natively.
The reader can recognize bytevectors both in the numeric format
(e.g. @code{#u(65 66 67 68)}) and the string format
(e.g. @code{#u8"ABCD"}).  The writer writes bytevectors in the numeric
format by default, but you can switch it to string format
when @code{bytestring} slot of @code{<wrtie-controls>} is true.
@c JP
Gaucheはバイトベクタの「文字列」表現を組み込みでサポートしています。
リーダーは、数値形式(例: @code{#u(65 66 67 68)})、
文字列形式(例: @code{#u8"ABCD"})、のどちらでも読むことができます。
ライターはデフォルトで数値形式を使いますが、
@code{<write-controls>}の@code{bytestring}スロットを真にすると
文字列形式を使うようになります。
@c COMMON

@example
gosh> #u8(65 66 67 68)
#u8(65 66 67 68)
gosh> ,pm bytestring #t
Current print mode:
       length :  50           base :  10  exact-decimal :  #f
        level :  10   radix-prefix :  #f          array : compact
       pretty :  #t  string-length : 256        complex : rectangular
        width :  79     bytestring :  #t
gosh> #u8(65 66 67 68)
#u8"ABCD"
@end example
@end deftp

@defun bytestring arg @dots{}
[SRFI-207]
@c MOD srfi.207
@c EN
Each argument must be either one of the followings, and the procedure
returns a new bytevector which is concatenation of the given arguments.
@c JP
各引数はそれぞれ以下のいずれかでなければなりません。
手続きは与えられた引数を全部つなげた新たなバイトベクタを作って返します。
@c COMMON

@itemize @bullet
@item
@c EN
An exact integer, between 0 and 255 inclusive.
@c JP
0から255までの間の整数
@c COMMON
@item
@c EN
An ASCII character.
@c JP
ASCII文字
@c COMMON
@item
@c EN
A bytevector
@c JP
バイトベクタ
@c COMMON
@item
@c EN
A string of ASCII characters
@c JP
ASCII文字列
@c COMMON
@end itemize

@c EN
An error is signaled if anything other than above is given.
@c JP
上記以外のオブジェクトが引数に与えられた場合はエラーが投げられます。
@c COMMON

@example
(bytestring "lor" #\r #\x65 #u8(#x6d))
  @result{} #u8(108 111 114 114 101 109)  ; #u8"lorrem"
@end example
@end defun

@defun make-bytestring lis
[SRFI-207]
@c MOD srfi.207
@c EN
Returns a new bytevector whose content is a concatenation of
elements in @var{lis}.  Each element must be either an exact integer
between 0 and 255 inclusive, an ASCII character, a bytevector
or an ASCII string.  It is effectively the same as
@code{(apply bytestring lis)}.
@c JP
@var{lis}の要素をつなげた内容を持つバイトベクタを作って返します。
@var{lis}の各要素は、0以上255以下の正確な整数、ASCII文字、
バイトベクタ、あるいはASCII文字列のいずれかでなければなりません。
実質的には@code{(apply bytestring lis)}と同じです。
@c COMMON
@end defun

@defun make-bytestring! bv at lis
[SRFI-207]
@c MOD srfi.207
@c EN
Fill a bytevector @var{bv} starting from index @var{at} with the
elements in @var{lis}.  Each element must be either an exact integer
between 0 and 255 inclusive, an ASCII character, a bytevector
or an ASCII string.

Returns an undefined value.
@c JP
バイトベクタ@var{bv}の、インデックス@var{at}以降を、
@var{lis}の要素で埋めます。
@var{lis}の各要素は、0以上255以下の正確な整数、ASCII文字、
バイトベクタ、あるいはASCII文字列のいずれかでなければなりません。

戻り値は未定義です。
@c COMMON

@example
(rlet1 bv (make-u8vector 10)
  (make-bytestring! bv 1 '("ab" #\c #u8"de")))
  @result{} #u8(0 97 98 99 100 101 0 0 0 0)
@end example
@end defun

@defun bytevector->hex-string bv
@defunx hex-string->bytevector string
[SRFI-207]
@c MOD srfi.207
@c EN
Convert a bytevector to hexadecimal digit string, and vice versa.

A condition that satisfies @code{bytestring-error?} is thrown
by @code{hex-string->bytevector} if @var{string} contains a letter
not valid as a hexadecimal digits.
@c JP
それぞれ、バイトベクタと十六進数文字列とを相互に変換します。

@code{hex-string->bytevector}が、引数中に十六進数と解釈できない
文字に出会った場合は、@code{bytestring-error?}を満たすコンディションが投げられます。
@c COMMON

@example
(bytevector->hex-string #u8"aloha")
  @result{} "616c6f6861"
(hex-string->bytevector "616C6F6861")
  @result{} #u8(97 108 111 104 97)  ; #u8"aloha"
@end example
@end defun

@defun bytevector->base64 bv :optional digits
@defunx base64->bytevector string :optional digits
[SRFI-207]
@c MOD srfi.207
@c EN
Encode a bytevector @var{bv} to Base64 encoded string, and vice versa.

A condition that satisfies @code{bytestring-error?} is thrown
by @code{base64->bytevector} if @var{string} contains a letter
not valid in Base64 encoded string.  Whitespace characters in @var{string}
are silently ignored, though.
@c JP
それぞれ、バイトベクタとBase64文字列とを相互に変換します。

@code{hex-string->bytevector}が、引数がBase64と解釈できない
場合は、@code{bytestring-error?}を満たすコンディションが投げられます。
但し、空白文字は許されて、それは単に無視されます。
@c COMMON

@c EN
By default, they use standard Base64 mappings.  You can specify
a string of two ASCII characters in @var{digits} to alter
mapping of 62nd and 63rd digits; the 'URL-safe' variant
of Base64 can be achieved by passing @code{"-_"} as @var{digits}.
@c JP
デフォルトでは標準のBase64マッピングが使われます。
マッピングの62と63に使う代わりの文字を、2文字のASCII文字列列として
@var{digits}に渡すことで、それらの文字のマッピングを変更できます。
いわゆる「URL安全」なBase64バリエーションを使うには、
@code{"-_"}を@var{digits}に渡します。
@c COMMON

@c EN
@xref{Base64 encoding/decoding}, for Gauche-specific Base64 library
that provides more APIs.
@c JP
Gauche特有のBase64ライブラリには他のAPIも提供されています。
@ref{Base64 encoding/decoding}を参照してください。
@c COMMON
@end defun

@defun bytestring->list bv :optional start end
[SRFI-207]
@c MOD srfi.207
Converts each element of a bytevector @var{bv} to
either a character (if the element is an integer between 32 and 127,
inclusive) or an integer, and returns a list of converted elements.
If you pass the resulting list to @code{make-bytestring}, you can obtain
the same bytevector as @var{bv}.

If you pass the optional @var{start} and @var{end} indexes,
only the specified range of @var{bv} is considered.
@end defun

@defun make-bytestring-generator arg @dots{}
[SRFI-207]
@c MOD srfi.207
Returns a generator that works as the same as
@code{(uvector->generator (bytestring @var{arg} @dots{}))},
but this can skip creating intermediate bytestrings.
@end defun

@defun bytestring-pad bv len char-or-u8
@defunx bytestring-pad-right bv len char-or-u8
[SRFI-207]
@c MOD srfi.207
Returns a newly allocated bytevector of at least @var{len} long.
If @var{bv} is shorter than @var{len}, the rest is padded with
@var{char-or-u8} (which can be either an ASCII character or
an exact integer between 0 and 255).  The pad is added to the left
with @code{bytestring-pad}, and to the right with @code{bytestring-pad-right}.

This is a bytestring version of @code{string-pad} and @code{string-pad-right}
(@pxref{SRFI-13 String selection}).
@end defun

@defun bytestring-trim bv pred
@defunx bytestring-trim-right bv pred
@defunx bytestring-trim-both bv pred
[SRFI-207]
@c MOD srfi.207
Remove octets that satisfies @var{pred}
at the beginning / at the end / at both ends of a bitvector @var{bv}.
The procedure @var{pred} receives an exact integer between 0 and 255.

They always return a fresh bytevector, even when no octets are trimmed.

This is a bytestring version of @code{string-trim},
@code{string-trim-right}, and @code{string-trim-both}
(@pxref{SRFI-13 String selection}).
@end defun

@defun bytrestring-replace bv1 bv2 start1 end1 :optional start2 end2
[SRFI-207]
@c MOD srfi.207
Returns a new bytevector whose content is a copy of a bytevector
@var{bv1}, except the part beginning from the index
@var{start1} (inclusive) and ending at the index @var{end1} (exclusive)
is replaced by a byvetvector @var{bv2}.
When optional @var{start2} and @var{end2}
arguments are given, @var{bv2} is trimmed first accordingly.
The size of the @emph{gap}, @code{(- @var{end1} @var{start1})}, doesn't
need to be the same as the size of the inserted bytevector.
Effectively, this is the same as the following code.

@example
(bytevector-append (subseq bv1 0 start1)
                   (subseq bv2 start2 end2)
                   (subseq bv1 end1 (bytevector-length bv1)))
@end example

This is a bytestring version of @code{string-replace}
(@pxref{SRFI-13 Other string operations}).
@end defun

@defun bytestring<? bv1 bv2
@defunx bytestring<=? bv1 bv2
@defunx bytestring>? bv1 bv2
@defunx bytestring>=? bv1 bv2
[SRFI-207]
@c MOD srfi.207
Compare two bytevectors lexicographically.  These are bytestring
version of @code{string<?} (@pxref{String comparison}).

There's no @code{bytestring=?}, for you can check equality of bytevectors
by @code{bytevector=?} in @code{scheme.bytevector} and
@code{gauche.uvector} (@pxref{Bytevector compatibility}).

Note that @code{bytevector-comparator} compares bytevectors
differently.  The comparator first compares the lengths, and only
uses elements when both vectors are of the same length
(@pxref{Predefined comparators}).

@example
(bytestring<? #u8"abc" #u8"ac") @result{} #t
(<? bytevector-comparator #u8"abc" #u8"ac") @result{} #f
@end example

This contrasts SRFI-207's view of bytevectors as a string of bytes,
with the view of them as an array of bytes.
@end defun

@defun bytestring-index bv pred :optional start end
@defunx bytestring-index-right bv pred :optional start end
[SRFI-207]
@c MOD srfi.207
Returns the first or last index of the octet that satisfies @var{pred}
in a bytevector @var{bv}.  The optional @var{start} and @var{end}
arguments limit the range to search.

These are bytestring version of @code{string-index} and
@code{string-index-right} (@pxref{SRFI-13 String searching}).
@end defun

@defun bytestring-break bv pred
@defunx bytestring-span bv pred
[SRFI-207]
@c MOD srfi.207
Returns two bytevectors, the first one is a maximum prefix of @var{bv}
whose element does not / does satisfy @var{pred}, and the second one
is the rest of @var{bv}.

@example
(bytestring-break #u8"abracadabra" (cut = <> 100))
 @result{} #u8(97 98 114 97 99 97) @r{and} #u8(100 97 98 114 97)
(bytestring-span #u8(1 2 3 4 5 4 3 2 1) (cut < <> 5))
 @result{} #u8(1 2 3 4) @r{and} #u8(5 4 3 2 1)
@end example
@end defun

@defun bytestring-join bv-list delim :optional grammar
[SRFI-207]
@c MOD srfi.207
Given list of bytevectors @var{bv-list}, concatenates the bytevectors
with a delimiter @var{delim}, which can be an exact integer
between 0 and 255 inclusive, an ASCII character, a bytevector
or a string of ASCII characters.

The @var{grammar} argument must be one of the symbols @code{infix},
@code{strict-infix}, @code{suffix}, and @code{prefix}, as in
@code{string-join} (@pxref{String utilities}).  The difference
between @code{infix} and @code{strict-infix} is that the former
allows to join zero byvectors (returns @code{#u8()}), while the
latter raises an error when @var{bv-list} is empty.  When omitted,
@code{infix} is assumed.

@example
(bytestring-join '(#u8"a" #u8"b" #u8"c") 0) @result{} #u8(97 0 98 0 99)
(bytestring-join '(#u8"a" #u8"b" #u8"c") 0 'prefix) @result{} #u8(0 97 0 98 0 99)
(bytestring-join '(#u8"a" #u8"b" #u8"c") 0 'suffix) @result{} #u8(97 0 98 0 99 0)
@end example
@end defun

@defun bytestring-split bv delim :optional grammar
[SRFI-207]
@c MOD srfi.207
Split a bytevector @var{bv} with @var{delim}, which must be
either an exact integer between 0 and 255 inclusive or an ASCII character,
and returns a list of bytevectors.  Delimiters themselves are not included
in the result.

The @var{grammar} argument is, if given, either one of the symbols
@code{infix}, @code{strict-infix}, @code{prefix}, or @code{suffix},
similar to @code{bytestring-join}.  If it is @code{prefix}/@code{suffix},
the preceding/succeeding @var{delim} is ignored, if any.  There are no
difference between @code{infix} and @code{strict-infix}.  The default
is @code{infix}.

@example
(bytestring-split #u8"abracadabra" #\a)
 @result{} (#u8() #u8(98 114) #u8(99) #u8(100) #u8(98 114) #u8())
(bytestring-split #u8"abracadabra" #\a 'prefix)
 @result{} (#u8(98 114) #u8(99) #u8(100) #u8(98 114) #u8())
(bytestring-split #u8"abracadabra" #\a 'suffix)
 @result{} (#u8() #u8(98 114) #u8(99) #u8(100) #u8(98 114))
@end example
@end defun

@defun read-textual-bytestring prefix :optional port
[SRFI-207]
@c MOD srfi.207
This parses a textual representation of a bytestring read from
@var{port} (defaults to the current input port) and returns a bytevector.
If @var{prefix} is false, it assumes the preceding @code{"#u8"} has
already been read.  If the input can't be parsed as a valid
textual representation of a bytestring, an error satisfying
@code{bytestring-error?} is raised.

@example
(with-input-from-string "#u8\"abc\\x80;\"" (cut read-textual-bytestring #t))
  @result{} #u8(97 98 99 128)
@end example
@end defun

@defun write-textual-bytestring bv :optional port
[SRFI-207]
@c MOD srfi.207
Writes a bytevector @var{bv} in the textual representation to
@var{port} (defaults to the current output port).

@example
(write-textual-bytestring #u8(65 66 128 255 0))
 @result{} @r{prints} #u8"AB\x80;\xff;\x00;"
@end example
@end defun

@defun write-binary-bitestring port arg @dots{}
[SRFI-207]
@c MOD srfi.207
@example
Works like @code{(write-textual-bytestring (bytestring arg @dots{}) port)},
but without creating the intermediate bytevector.
If any arguments are invalid to construct a bytevector, an error
satisfying @code{bytestring-error?} signaled.
@end example
@end defun

@defun bytestring-error? obj
[SRFI-207]
@c MOD srfi.207
Returns @code{#t} if @var{obj} is a condition thrown from
bytestring operations.
@end defun


@c ----------------------------------------------------------------------
@node Enums and enum sets, Procedures and syntax for multiple values, String-notated bytevectors, Library modules - SRFIs
@section @code{srfi.209} - Enums and enum sets
@c NODE enumとenum集合,  @code{srfi.209} - enumとenum集合

@deftp {Module} srfi.209
@mdindex srfi.209
Enums are objects to represent a finite set of options.  Traditionally
Lisp-family languages have used symbols or keywords for the purpose,
but it is error prone that you can pass arbitrary symbols which can only
be checked at runtime.

The enums in this srfi allows the user to define and use enums statically,
that is, checked at macro-expansion time.

There are three kind of objects involved in the enum system:

@table @strong
@item Enum type
An enum type defines all possible enums that can belong to the type.
It can be created at macro-expansion time with @code{define-enum},
or at run-time with @code{make-enum-type}.  It is an immutable object.
@item Enum
An enum is an object that belong to a certain enum type.  Each enum
has a name (a symbol unique within the enum type),
an ordinal (nonnegative contiguous exact integer), and
a value (arbitrary Scheme value, defaults to the name).
Enums are instantiated at the same time as an enum type is instantiated.
It is also an immutable object.
@item Enum set
An enum set is a subset of enums from the enums in a certain enum type.
An efficient set operation over an enum set is provided.
@end table
@end deftp

@subheading Enum types

@defmac define-enum type-name (name-value @dots{}) make-set
[SRFI-209]
@c MOD srfi.209
The high-level declarative interface.  This defines a new
enum type and interface macros.

The enums the enum type contains are specified with @var{name-value} @dots{},
each of which must be either a symbol, or a form @code{(symbol value)}.
If it is a symbol, it is used both as the enum name and its value.
If it is @code{(symbol value)}, the symbol is used as the enum name
and the value is used as its value.

The @var{type-name} argument must be an identifier and
is bound to a macro, which takes a single
symbol as an argument.  When invoked, it expands into an enum object.

The @var{make-set} argument must also be an identifier and
is bound to a macro, which takes zero or more symbols and
expands into an enum set object.

Since @var{type-name} and @var{make-set} are macros, the given enum name(s)
can be statically checked at expansion time.

@example
(define-enum fruits (apple orange banana mango papaya) fruit-set)

(fruits apple) @result{} #<enum apple>
(fruits mango) @result{} #<enum mango>

(fruit-set oragne mango papaya)
  @result{} #<enum-set fruits (orange mango papaya)>
@end example
@end defmac

@defun make-enum-type list :optional name
[SRFI-209]
@c MOD srfi.209
A procedural interface to create enum type and associated enums.

This procdure first creates enums according to @var{list}.
Each element
must be either a symbol, or a form @code{(symbol value)}.
If it's the former, the symbol is used both as the enum name and
its value.  If it's the latter, the symbol is used as the enum name
and the value is used as its value.
Note that enum objects can only be created with this procedure
(or the high-level macro) along with an enum type.

Each enum also gets a nonnegative integer @var{ordinal}, in the
order of @var{list}, starting from zero.

The optional @var{name} argument is a Gauche's extension.  It attaches
@var{name} to the created enum-type.  It is only for debugging aid,
and printed when you write the enum type.

Enum type is immutable. Once created, its enum members cannot be changed.

@example
(make-enum-type '(one two three))
  @result{} #<enum-type (one ...)>
(make-enum-type '(one two three) 'counts)
  @result{} #<enum-type counts>
@end example
@end defun

@defun enum-type? obj
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if @var{obj} is an enum-type, @code{#f} otherwise.
@end defun

@defun enum-type-size etype
[SRFI-209]
@c MOD srfi.209
Returns the number of enums the enum type @var{etype} has.
@end defun

@defun enum-min etype
@defunx enum-max etype
[SRFI-209]
@c MOD srfi.209
Returns the minimun and maximum enum the enum type @var{etype} has.

@example
(define fruits (make-enum-type '(apple orange banana mango papaya)))

(enum-min fruits) @result{} #<enum apple>
(enum-max fruits) @result{} #<enum papaya>
@end example

They throw an error if @var{etype} has no enums.
@end defun

@defun enum-type-enums etype
[SRFI-209]
@c MOD srfi.209
Returns a list of enums the enum type @var{etype} has, in the order
of their ordinals.

@example
(define fruits (make-enum-type '(apple orange banana mango papaya)))

(enum-type-enums fruits)
  @result{} (#<enum apple> #<enum orange> #<enum banana>
     #<enum mango> #<enum papaya>)
@end example
@end defun

@defun enum-type-names etype
[SRFI-209]
@c MOD srfi.209
Returns a list of names of enums the enum type @var{etype} has, in the order
of their ordinals.

@example
(define fruits (make-enum-type '(apple orange banana mango papaya)))

(enum-type-names fruits)
  @result{} (apple orange banana mango papaya)
@end example
@end defun

@defun enum-type-values etype
[SRFI-209]
@c MOD srfi.209
Returns a list of the values of the enums the enum type @var{etype} has,
in the order of their ordinals.
@end defun

@defun enum-type-contains? etype enum
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} iff enum type @var{etype} contains @var{enum},
@code{#f} otherwise.
@end defun

@defun enum-name->enum etype symbol
[SRFI-209]
@c MOD srfi.209
Returns an enum object in @var{etype} whose name is @var{symbol}.
If @var{etype} doesn't have an enum of such name, @code{#f} is returned.
@end defun

@defun enum-ordinal->enum etype n
[SRFI-209]
@c MOD srfi.209
Returns @var{n}-th enum of @var{etype}.
If @var{n} is over the range of enums in @var{etype}, @code{#f} is returned.
@end defun

@defun enum-name->ordinal etype symbol
[SRFI-209]
@c MOD srfi.209
Returns the ordinal of the enum in @var{etype} whose name is @var{symbol}.
An error is thrown if @var{etype} doesn't have such symbol.
@end defun

@defun enum-name->value etype symbol
[SRFI-209]
@c MOD srfi.209
Returns the value of the enum in @var{etype} whose name is @var{symbol}.
An error is thrown if @var{etype} doesn't have such symbol.
@end defun

@defun enum-ordinal->name etype n
[SRFI-209]
@c MOD srfi.209
Returns the name of the @var{n}-th enum of @var{etype}.
An error is thrown if @var{n} is out of the range.
@end defun

@defun enum-ordinal->value etype n
[SRFI-209]
@c MOD srfi.209
Returns the value of the @var{n}-th enum of @var{etype}.
An error is thrown if @var{n} is out of the range.
@end defun

@defun make-enum-comparator etype
[SRFI-209]
@c MOD srfi.209
Returns a comparator that can compare two enums that belong to @var{etype}.
@xref{Comparators}, for the details of comparators.
@end defun

@subheading Enums

@defun enum-type enum
@defunx enum-name enum
@defunx enum-ordinal enum
@defunx enum-value enum
[SRFI-209]
@c MOD srfi.209
Returns enum's type (@code{<enum-type>} instance), enum's name (symbol),
enum's ordinal (nonnegative exact integer), and enum's value (any object),
respectively.

Note that enum objects can only be constructed with the enum type
it belongs (by @code{define-enum} or @code{make-enum-type}), and
they are immutable.
@end defun

@defun enum? obj
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if @var{obj} is an enum, @code{#f} otherwise.
@end defun

@defun enum=? enum0 enum1 enums ...
@defunx enum<? enum0 enum1 enums ...
@defunx enum<=? enum0 enum1 enums ...
@defunx enum>? enum0 enum1 enums ...
@defunx enum>=? enum0 enum1 enums ...
[SRFI-209]
@c MOD srfi.209
These comapres enums by its ordinals.  All the enums must belong
to the same enum type, or an error is thrown.
@end defun

@defun enum-next enum
[SRFI-209]
@c MOD srfi.209
Returns the next enum of @var{enum}, that is,
an enum that belongs to the same enum type as @var{enum} and
has an incremented ordinal.  If @var{enum} is the last enum of
its type, @code{#f} is returned.
@end defun

@defun enum-prev enum
[SRFI-209]
@c MOD srfi.209
Returns the previous enum of @var{enum}, that is,
an enum that belongs to the same enum type as @var{enum} and
has a decremented ordinal.  If @var{enum} is the first enum of
its type, @code{#f} is returned.
@end defun

@subheading Enum sets

@defun enum-type->enum-set etype
[SRFI-209]
@c MOD srfi.209
Returns an enum set that contains all enums in the enum type @var{etype}.
@end defun

@defun enum-set etype enum @dots{}
[SRFI-209]
@c MOD srfi.209
Returns an enum set that contains @var{enum} @dots{} of an enum type
@var{etype}.  An error is thrown unless all @var{enum} @dots{} belong
to @var{etype}.
@end defun

@defun enum-empty-set etype
[SRFI-209]
@c MOD srfi.209
Returns an empty enum set for the enum type @var{etype}.
@end defun

@defun list->enum-set etype enum-list
[SRFI-209]
@c MOD srfi.209
Returns an enum set of an enum type @var{etype}, contaning enums
listed in @var{enum-list}.  If @var{enum-list} contains anything
other than enums from @var{etype}, an error is thrown.
@end defun

@defun enum-set-projection etype-or-eset eset
[SRFI-209]
@c MOD srfi.209
The @var{etype-or-eset} argument must be an enum type or an enum set.
Returns a new enum set on an enum type @var{etype-or-eset} (if it is
an enum set, its enum type is used), which contains enums
having the same names as the names of enums contained in @var{eset}.
The @var{eset}'s enum type doesn't need to be the same as the
result enum set.
@end defun

@defun enum-set-copy eset
[SRFI-209]
@c MOD srfi.209
Returns a copy of an enum set @var{eset}.
@end defun

@defun enum-set? obj
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if @var{obj} is an enum set, @code{#f} otherwise.
@end defun

@defun enum-set-contains? eset enum
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if @var{enum} is a member of @var{eset}, @code{#f} otherwise.
@end defun

@defun enum-set-empty? eset
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if @var{eset} is empty.
@end defun

@defun enum-set-disjoint? eset1 eset2
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if two enum sets on the same enum type share
no common enums.  An error is thrown unless @var{eset1} and @var{eset2}
are for the same enum type..
@end defun

@defun enum-set=? eset1 eset2
@defunx enum-set<? eset1 eset2
@defunx enum-set<=? eset1 eset2
@defunx enum-set>? eset1 eset2
@defunx enum-set>=? eset1 eset2
[SRFI-209]
@c MOD srfi.209
This determines subset relationship of two enum sets.  Both enum sets
must be for the same enum type, or an error is thrown.
@end defun

@defun enum-set-subset? eset1 eset2
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if the @emph{names} of the member of enum set @var{eset1}
is a subset of the names of the member of @var{eset2}.  Otherwise
returns @code{#f}.  Unlike @code{enum-set<?}, two enum set can be
of different enum types.  Comparison is done with the names only.
@end defun

@defun enum-set-any? pred eset
@defunx enum-set-every? pred eset
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if any or every application of @var{proc} to the
elemens of enum set @var{eset} yields true.  Otherwise returns @code{#f}.
@end defun

@defun enum-set-type eset
[SRFI-209]
@c MOD srfi.209
Returns the enum type of the enum set @var{eset}.
@end defun

@defun enum-set-size eset
[SRFI-209]
@c MOD srfi.209
Returns the number of elements in the enum set @var{eset}.
@end defun

@defun enum-set->enum-list eset
[SRFI-209]
@c MOD srfi.209
Returns a list of enums contained in the enum set @var{eset},
in the increasing order of enumcs.
@end defun

@defun enum-set-adjoin eset enum @dots{}
@defunx enum-set-adjoin! eset enum @dots{}
[SRFI-209]
@c MOD srfi.209
Returns an enum set that contains all the members in the enum set @var{eset}
plus @var{enum} @dots{}.  All @var{enum}s must belong to the same enum type
of @var{eset}.

The linear update version @code{enum-set-adjoin!} may modify @var{eset}
to produce the result.
@end defun

@defun enum-set-delete eset enum @dots{}
@defunx enum-set-delete! eset enum @dots{}
[SRFI-209]
@c MOD srfi.209
Returns an enum set that contains all the members in the enum set @var{eset}
except @var{enum} @dots{}.  All @var{enum}s must belong to the same enum type
of @var{eset}.

The linear update version @code{enum-set-delete!} may modify @var{eset}
to produce the result.
@end defun

@defun enum-set-delete-all eset list @dots{}
@defunx enum-set-delete-all! eset list @dots{}
[SRFI-209]
@c MOD srfi.209
Returns an enum set that contains all the members in the enum set @var{eset}
the enums in @var{list}.  An error is thrown if
@var{list} contains non-enums, or enums that do not belong to the same
enum type of @var{eset}.

The linear update version @code{enum-set-delete-all!} may modify @var{eset}
to produce the result.
@end defun

@defun enum-set-count pred eset
[SRFI-209]
@c MOD srfi.209
Applies @var{pred} on each enum in @var{eset}, and returns the number
of times when @var{pred} yields a true value.
@end defun

@defun enum-set-filter pred eset
@defunx enum-set-remove pred eset
[SRFI-209]
@c MOD srfi.209
Returns a new enum set that contains the enums that satisfy or
do not satisfy @var{pred}.
@end defun

@defun enum-set-map->list proc eset
[SRFI-209]
@c MOD srfi.209
Applies @var{proc} on each enum in @var{eset},
and returns a list of the results, in the increasing order of enums.
@end defun

@defun enum-set-for-each proc eset
[SRFI-209]
@c MOD srfi.209
Applies @var{proc} on each enum in @var{eset} in the increasing order.
The results of @var{proc} are discarded.
@end defun

@defun enum-set-fold kons knil eset
[SRFI-209]
@c MOD srfi.209
For each enum in @var{eset},
apply @var{kons} on it and the current
state value, whose initial value is @var{knil}.  The result
of @var{kons} is used as the state value of the next iteration.
The last result of @var{kons} is returned.
The @var{eset} is traversed in increasing order.
@end defun

@defun enum-set-complement eset
@defunx enum-set-complement! eset
[SRFI-209]
@c MOD srfi.209
Returns an enum set of the same enum type as @var{eset}, but
contains enums that are not contained in @var{eset}.
The linear updating version @code{enum-set-complement!} may reuse
the storage of @var{eset}.
@end defun

@defun enum-set-union eset1 eset2
@defunx enum-set-union! eset1 eset2
[SRFI-209]
@c MOD srfi.209
Two enum sets must be of the same enum type.
Returns an enum set of the same type
that contains enums each of which is in at least
either of @var{eset1} or @var{eset2}.
The linear updating version @code{enum-set-union!} may reuse
the storage of @var{eset1}.
@end defun

@defun enum-set-intersection eset1 eset2
@defunx enum-set-intersection! eset1 eset2
[SRFI-209]
@c MOD srfi.209
Two enum sets must be of the same enum type.
Returns an enum set of the same type
that contains enums each of which is in both
@var{eset1} and @var{eset2}.
The linear updating version @code{enum-set-intersection!} may reuse
the storage of @var{eset1}.
@end defun

@defun enum-set-difference eset1 eset2
@defunx enum-set-difference! eset1 eset2
[SRFI-209]
@c MOD srfi.209
Two enum sets must be of the same enum type.
Returns an enum set of the same type
that contains enums each of which is in @var{eset1}
but not in @var{eset2}.
The linear updating version @code{enum-set-difference!} may reuse
the storage of @var{eset1}.
@end defun

@defun enum-set-xor eset1 eset2
@defunx enum-set-xor! eset1 eset2
[SRFI-209]
@c MOD srfi.209
Two enum sets must be of the same enum type.
Returns an enum set of the same type
that contains enums each of which is in either @var{eset1}
or @var{eset2}, but not both.
The linear updating version @code{enum-set-xor!} may reuse
the storage of @var{eset1}.
@end defun

@subheading R6RS enumeration compatibility

R6RS also has enumerations, but it does not have separate @emph{enum} object,
nor explicitly deal with enum types.
Symbols are used to represent each enum, and enum types are
implicitly dealt with enum sets.

@defmac define-enumeration type-name (name-value @dots{}) make-set
[SRFI-209]
@c MOD srfi.209
Creates a new enum type and defines a macro named @var{type-name}
and @var{make-set}.  VEry similar to @code{define-enum}, except that
the macro invocation @code{(@var{type-name} @var{symbol})} returns
the symbol itself instead of an enum object.
@end defmac

@defun make-enumeration symbol-list
[SRFI-209]
@c MOD srfi.209
Creates a new enum type with the enums each of which has the name
given in @var{symbol-list}.  Returns a fresh enum set containing
all the enums.  The created enum type ca be obtained with
@code{enum-set-type}.
@end defun

@defun enum-set-universe eset
[SRFI-209]
@c MOD srfi.209
Returns a fresh enum set that contains all the enums of the enum type
of the given enum set @var{eset}.
It is basically @code{(enum-type->enum-set (enum-set-type eset))}.
@end defun

@defun enum-set-costructor eset
[SRFI-209]
@c MOD srfi.209
Returns a procedure that accepts a list of symbols as an argument,
and returns a fresh enum set that contains the enums whose names
are given in the list.
@end defun

@defun enum-set-member? symbol eset
[SRFI-209]
@c MOD srfi.209
Returns @code{#t} if @var{symbol} is the name of a member of @var{eset},
or @code{#f} @var{symbol} is a valid name of the enum type of
@var{eset} but not in @var{eset}.  An error is signaled
if @var{symbol} is not a valid name of enums in the enum type.
@end defun

@defun enum-set-indexer eset
[SRFI-209]
@c MOD srfi.209
Returns a procedure that takes one argument, a symbol, and
returns the ordinal of the enum that has the given symbol as a name.
If the given symbol is not a name of any enums in the enum type
of @var{eset}, @code{#f} is returned.  Note that the enum with the
given symbol does not need to be in @var{eset}; basically, @var{eset}
is used only to obtain the enum type.
@end defun

@defun enum-set->list eset
[SRFI-209]
@c MOD srfi.209
Returns a list of the names of the members of @var{eset}.
Same as @code{(map enum-name (enum-set->enum-list eset))}.
@end defun

@c ----------------------------------------------------------------------
@node Procedures and syntax for multiple values, Central log exchange, Enums and enum sets, Library modules - SRFIs
@section @code{srfi.210} - Procedures and syntax for multiple values
@c NODE 多値のための手続きと構文,  @code{srfi.210} - 多値のための手続きと構文

@deftp {Module} srfi.210
@mdindex srfi.210
@c EN
This module provides macros and procedures to blend multiple-value
expressions naturally into the ordinary single-value expressions.
@c JP
このモジュールは、複数の値を返す式を通常の単一の値を扱う式にうまく混ぜて使えるようにする
マクロや手続きを提供します。
@c COMMON
@end deftp

@defmac with-values producer consumer
[SRFI-210]
@c MOD srfi.210
@c EN
A shorthand notation of @code{(call-with-values (^[] producer) consumer)}.
@c JP
@code{(call-with-values (^[] producer) consumer)}の略記です。
@c COMMON
@end defmac

@defmac case-receive producer clause @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
A shorthand notation of
@code{(with-values producer (case-lambda clause @dots{}))}.
@c JP
@code{(with-values producer (case-lambda clause @dots{}))}の略記です。
@c COMMON
@end defmac

@defmac apply/mv operator operand @dots{} producer
[SRFI-210]
@c MOD srfi.210
@c EN
Similar to @code{apply}, but the multiple values yielded
from the last argument (@var{producer}) is turned into the tail of
the argument list; that is,
@code{(apply operator operand @dots{} (values->list producer))}.
@c JP
@code{apply}と似ていますが、最後の引数@var{producer}は複数の値を返すことができ、
それが@var{operator}への引数リストの末尾に付け加えられます。
つまり@code{(apply operator operand @dots{} (values->list producer))}と同じです。
@c COMMON
@end defmac

@defmac call/mv proc producer @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
Calls @var{proc} with the argument produced by the expression
@var{producer} @dots{} and 'splicing' their result(s) into a single
argument list.
@c JP
@var{producer} @dots{}の各式が返す多値をリストにしてつなぎあわせたものを
引数リストにして@var{proc}を呼び出します。
@c COMMON

@example
(call/mv list (values 1 2 3) (values 4 5 6))
  @result{} (1 2 3 4 5 6)
@end example
@end defmac

@defmac list/mv element @dots{} producer
@defmacx vector/mv element @dots{} producer
@defmacx box/mv element @dots{} producer
[SRFI-210]
@c MOD srfi.210
@c EN
Returns a list, a vector, or a box, consisting of @var{element} @dots{}
and the value(s) produced by @var{producer}.
@c JP
@var{element} @dots{}および、@var{producer}が返す多値のそれぞれを要素とする
リスト、ベクタ、ボックスを作って返します。
@c COMMON

@c EN
Single-argument @code{list/mv} is the same as Gauche's @code{values->list}
(@pxref{Multiple values}).
@c JP
@code{list/mv}に引数をひとつだけ渡した場合は、Gauche組み込みの@code{values->list}
と同じです(@ref{Multiple values}参照)。
@c COMMON

@example
(list/mv 1 2 (values 3 4 5))   @result{} (1 2 3 4 5)
(vector/mv 1 2 (values 3 4 5)) @result{} #(1 2 3 4 5)
(box/mv 1 2 (values 3 4 5))    @result{} #<mv-box[5] 1 2 3 4 5>
@end example
@end defmac

@defmac value/mv index element @dots{} producer
[SRFI-210]
@c MOD srfi.210
@c EN
Returns the same value as
@code{(list-ref (list/mv element @dots{} producer) index)}.
@c JP
@code{(list-ref (list/mv element @dots{} producer) index)}と同じ値を返します。
@c COMMON

@c EN
With no @var{element} @dots{}, it is the same as Gauche's @code{values-ref}
(@pxref{Multiple values}) except the argument order.
@c JP
@var{element} @dots{}が無い場合は、Gauche組み込みの@code{values-ref}の
引数順をひっくり返したものになります(@ref{Multiple values}参照)。
@c COMMON
@end defmac

@defmac coarity producer
[SRFI-210]
@c MOD srfi.210
@c EN
Evaluate @var{producer}, and returns the number of values it yielded.
@c JP
@var{producer}を評価し、結果の値の数を返します。
@c COMMON
@end defmac

@defmac bind/mv producer transducer @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
Evaluate @var{producer}, and passes its results to the first @var{transducer}
as arguments.  The values returned by the first @var{transducer}
are passed to the next @var{transducer} as arguments, and so on.
Returns the results of the last @var{transducer}.
The call to the last @var{transducer} is tail-call.
@c JP
@var{producer}を評価し、その結果の値(複数かもしれない)を引数として
最初の@var{transducer}を呼びます。それが値(複数かもしれない)を返したらそれらを
引数として二番目の@var{transducer}を呼び、以下同様にして最後の@var{transducer}が
返す値(複数かもしれない)を返します。最後の@var{transducer}は末尾呼び出しされます。
@c COMMON

@c EN
If no @var{transducer}s are given, it returns the results of
@var{producer}.
@c JP
@var{transducer}が与えられなければ、@var{producer}の結果の値(複数かもしれない)が
そのまま返されます。
@c COMMON
@end defmac

@defun list-values lis
@defunx vector-values vec
@defunx box-values box
[SRFI-210]
@c MOD srfi.210
@c EN
Turn the content of @var{lis}, @var{vec} or @var{box} into multiple values.
@c JP
リスト@var{lis}、ベクタ@var{vec}、ボックス@var{box}の中身を複数の値として返します。
@c COMMON

@c EN
Note that @code{box-values} is the same as @code{unbox}, but provided here
for the naming consistency (@pxref{Boxes}).
@c JP
@code{box-values}は@code{unbox}と同じですが、
名前付けの一貫性のために用意されています (@ref{Boxes}参照)。
@c COMMON
@end defun

@defun value index obj @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
Returns the @var{index}-th value of @var{obj} @dots{}.
@c JP
@var{obj} @dots{}の@var{index}番目の値を返します。
@c COMMON
@end defun

@defun identity obj @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
Synonym of @code{values}.  Note that this is different from
Gauche's built-in @code{identity}, which takes exactly one argument
(@pxref{Combinators}).
@c JP
@code{values}と同じです。
Gaucheの組み込みの@code{identity}はこれと違い正確に一つの値だけを取ることに
注意してください (@ref{Combinators}参照)。
@c COMMON
@end defun

@defun compose-left transducer @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
Each @var{transducer} must be a procedure.
Returns a procedure that applies the first @var{transducer} to its
arguments, then applies the next @var{transducer} to the result(s)
of the first one, and so on.  Returns the result(s) returned from
the last @var{transducer}.  If no @var{tranducer}s are given,
returned procedure is the same as @code{values}.
@c JP
各@var{transducer}は手続きでなければなりません。
合成された手続きを返します。その手続きは、渡された引数をまず最初の@var{transducer}
に渡し、その結果(複数かもしれない)を次の@var{transducer}に渡し、ということを続けて
最後の@var{transducer}の結果(複数かもしれない)を返します。
@var{tranducer}がひとつも渡されない場合は@code{values}と同じです。
@c COMMON

@c EN
This can be written using Gauche's built-in @code{compose} as follows
(@pxref{Combinators}):
@c JP
これはGauche組み込みの@code{compose}を使って次のように書けます(@ref{Combinators}参照)。
@c COMMON

@example
(define (compose-left . procs) (apply compose (reverse procs)))
@end example
@end defun

@defun compose-right transducer @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
Each @var{transducer} must be a procedure.
Returns a procedure that applies the last @var{transducer} to its
arguments, then applies the previous @var{transducer} to the result(s)
of the last one, and so on.  Returns the result(s) returned from
the first @var{transducer}.  If no @var{tranducer}s are given,
returned procedure is the same as @code{values}.
@c JP
各@var{transducer}は手続きでなければなりません。
合成された手続きを返します。その手続きは、渡された引数をまず最後の@var{transducer}
に渡し、その結果(複数かもしれない)をひとつ前の@var{transducer}に渡し、ということを続けて
最初の@var{transducer}の結果(複数かもしれない)を返します。
@var{tranducer}がひとつも渡されない場合は@code{values}と同じです。
@c COMMON

@c EN
This is the same as Gauche's built-in @code{compose}
(@pxref{Combinators}).
@c JP
これはGauche組み込みの@code{compose}と同じです(@ref{Combinators}参照)。
@c COMMON
@end defun

@defun map-values proc
[SRFI-210]
@c MOD srfi.210
@c EN
Returns a procedure that takes any number of arguments, applys @var{proc}
on each argument, and returns the results as multiple values.
The behavior is undefined if @var{proc} doesn't return a single value.
@c JP
手続きを作って返します。その手続きは、任意個の引数を取り、それぞれに@var{proc}を適用して、
その結果を多値として返すものです。
@var{proc}が一つ以外の値を返した場合の動作は未定義です。
@c COMMON

@example
((map-values (cut + <> 1)) 1 2 3)
  @result{} 2, 3, 4
@end example
@end defun

@defun bind/list lis transducer @dots{}
@defunx bind/box box transducer @dots{}
@defunx bind obj transducer @dots{}
[SRFI-210]
@c MOD srfi.210
@c EN
These are @emph{bind} operation in Monads.  The first argument
is the source of data; they're first expanded into values (for
@code{bind/list}, each element of @var{lis} is taken; for @code{bind/box},
it is unboxed, and for @code{bind}, @var{obj} is the singleton value).
Those values are passed as arguments to the first @var{transducer},
and its result(s) are passed as argumenst to the second @var{transducer}
and so on.  The value(s) returned by the last @var{transducer} becomes
the result(s) of those procedures.  These can be written using
@code{compose-left} and procedure application:
@c JP
これらはモナドのbindです。最初の引数はデータのソースで、それぞれが多値へと展開されます
(@code{bind/list}ではリスト@var{lis}の各要素が多値に、
@code{bind/box}ではボックス@var{box}の各要素が多値に、
@code{bind}では@var{obj}が唯一の値になります)。
それが引数として最初の@var{transducer}に渡されます。
その結果(複数かもしれない)が次の@var{transducer}に渡されます。
そうしていって最後の@var{transducer}の返す値(複数かもしれない)が全体の結果となります。
これらは@code{compose-left}を使って次のとおり書けます。
@c COMMON

@example
(bind/list lis proc @dots{})
  @equiv{} (apply (compose-left proc @dots{}) lis)
(bind/box box proc @dots{})
  @equiv{} (apply/mv (compose-left proc @dots{}) (unbox box))
(bind obj proc @dots{})
  @equiv{} ((compose-left proc @dots{}) obj)
@end example
@end defun

@c ----------------------------------------------------------------------
@node Central log exchange, SICP prerequisites, Procedures and syntax for multiple values, Library modules - SRFIs
@section @code{srfi.215} - Central log exchange
@c NODE 中央ログ交換局,  @code{srfi.215} - 中央ログ交換局

@deftp {Module} srfi.215
@mdindex srfi.215
@c EN
This module abstracts a logging mechanism so that the code
can produce log messages in the same way regardless of
the underlying log system.

In Gauche, the default logging system is set to use @code{gauche.logger}
(@pxref{User-level logging}).  For Gauche-specific code,
you can directly use @code{gauche.logger}.  This module is convenient
when you're writing portable code.
@c JP
このモジュールはログ機構を抽象化して、具体的にどういうログシステムが使われているかに
かかわらず統一的な方法でログメッセージを送り出す方法を提供します。

Gaucheでは、デフォルトのログシステムは@code{gauche.logger}を使うように設定してあります
(@pxref{User-level logging})。
Gauche特定のコードを書いているなら@code{gauche.logger}を直接使っても良いでしょう。
このモジュールはポータブルなコードを書く場合に便利です。
@c COMMON
@end deftp

@deffn {Parameter} current-log-callback
[SRFI-215]
@c MOD srfi.215
@c EN
The value of this parameter must be a procedure that takes a single
argument, a log message packet.

A log message packet is an alist, with symbols as keys.  Their values can
be a string, an exact integer, a bytevector (u8vector),
or an instance of @code{<error>}.  SRFI doesn't specify what
will happen if other types of values are given.  Gauche converts
them to strings before this callback is called, but a portable program
should avoid passing values other than listed above.

Two keys, @code{SEVERITY} and @code{MESSAGE}, are always present,
with an exact integer value and a string as their values, respectively.
The severity value is between 0 and 7, inclusive, and corresponding
constans are defined; see below.
Users can use other keys freely, though SRFI-215 suggests some
common key names so check them up.

SRFI-215 also suggests that the default log callback procedure buffers
log messages, and pass them to a user-provided callback when this
parameter is set/rebound.  In our implementation, the default
callback directly sends logs to @code{log-format}
(@pxref{User-level logging}), for your convenience.
@c JP
このパラメータの値は引数を一つ取る手続きでなければなりません。
引数はログメッセージオブジェクトです。

ログメッセージオブジェクトは連想リストで、キーは常にシンボルです。
値は、文字列、正確な整数、バイトベクタ(u8vector)、@code{<error>}のインスタンス、
のいずれかです。SRFIではそれ以外の値が渡された場合の動作は規定されていません。
Gaucheではそれ以外の値はコールバックに渡す前に文字列に変換しますが、
ポータブルなプログラムでは上に列挙された値に留めておくべきです。

キー@code{SEVERITY}と@code{MESSAGE}は常に存在し、
それぞれ正確な整数と文字列を値に持ちます。
@code{SEVERITY}の値は0から7まで(両端含む)です。
その意味を示す定数が定義されているので下のエントリを参照してください。
ユーザはその他のキーを自由に使えます。
ただ、SRFI-215はいくつかの共通するキーを提示しているので見ておくと良いでしょう。

SRFI-25はまた、デフォルトのコールバックはログメッセージをバッファし、
このコールバックの値が変えられた時に貯められたメッセージを新たなコールバックに渡すことを提案しています。
しかし我々の実装では、デフォルトのコールバックは直接@code{log-format}に
ログを流します (@ref{User-level logging}参照)。
@c COMMON

@end deffn

@deffn {Parameter} current-log-fields
[SRFI-215]
@c MOD srfi.215
@c EN
This parameter holds a key-value list, @code{(key1 value1 key2 value2 @dots{})},
that are automatically appended to the fields passed to @code{send-log}.
The effect is as if that procedure was always invoked as
@code{(apply send-log severity message key value ... (current-log-fields))}.

When you set/rebind this parameter, the passed value is validated
to be a valid key-value arguments for @code{send-log}.
@c JP
このパラメータは@code{(key1 value1 key2 value2 @dots{})}の形のキー-値リストで、
その内容が@code{send-log}が呼ばれた時にそのフィールドリストに自動的に付け加えられます。
つまり、@code{send-log}は
@code{(apply send-log severity message [key value] ... (current-log-fields))}
と呼ばれたかのように振る舞うということです。

このパラメータをセット/再束縛した時点で、渡された値が@code{send-log}の引数として
ふさわしいかどうかが検査されます。
@c COMMON
@end deffn

@defun send-log severity message @dots{}
[SRFI-215]
@c MOD srfi.215
@c EN
A single-stop API to construct a log message packet and dispatch to
the current log callback.

The @var{severity} argument must be an exact integer between 0 and
7, inclusive.  It will be the value of @code{SEVERITY} key in the
log message packet.  There are constants defined for each severity
value: @code{EMERGENCY}, @code{ALERT}, @code{CRITICAL}, @code{ERROR},
@code{WARNING}, @code{NOTICE}, @code{INFO}, and @code{DEBUG}.
The @var{message} argument is a string and
will be the value of @code{MESSAGE} key in the log message packet.

The rest of the argument must be a key-value list.
The @code{SEVERITY} and @code{MESSAGE} keys are prepended,
and value of @code{current-log-fields} are appended,
and the entire key-value list is converted to an alist
to construct a log message packet.
See @code{current-log-callback} above for the
valid keys and values.

This procedure does not return a meaningful value.
@c JP
ログメッセージパケットを作って現在のログコールバックに送信します。

@var{severity}引数は0から7までの正確な整数でなければなりません。
これはログメッセージパケットの@code{SEVERITY}キーに対する値となります。
各値を意味する次の定数が定義されています:
@code{EMERGENCY}、@code{ALERT}、@code{CRITICAL}、@code{ERROR}、
@code{WARNING}、@code{NOTICE}、@code{INFO}、@code{DEBUG}。
@var{message}引数は文字列で、ログメッセージパケットの
@code{MESSAGE}キーに対する値となります。

残りの引数はキー-値リストです。これに@code{SEVERITY}と@code{MESSAGE}が
前置され、@code{current-log-fields}の値が後置され、全体がalistに変換されて
ログメッセージパケットとなります。有効なキーと値については
上の@code{current-log-callback}を参照してください。

この手続きは意味のある値は返しません。
@c COMMON

@example
(send-log INFO (string-append "User " username " logged in")
          'USERNAME username 'REMOTE_IP remote-ip)
@end example
@end defun

@defvr {Constant} EMERGENCY
@defvrx {Constant} ALERT
@defvrx {Constant} CRITICAL
@defvrx {Constant} ERROR
@defvrx {Constant} WARNING
@defvrx {Constant} NOTICE
@defvrx {Constant} INFO
@defvrx {Constant} DEBUG
[SRFI-215]
@c MOD srfi.215
@c EN
Bound to exact integers from 0 to 7, respectively, to indicate the severity
of the incident to be logged.
@c JP
それぞれ正確な整数0から7に束縛され、ログされる事象の深刻度を示します。
@c COMMON
@end defvr


@c ----------------------------------------------------------------------
@node SICP prerequisites, Integer sets, Central log exchange, Library modules - SRFIs
@section @code{srfi.216} - SICP prerequisites
@c NODE SICP用ライブラリ,  @code{srfi.216} - SICP用ライブラリ

@deftp {Module} srfi.216
@mdindex srfi.216
@c EN
This module provides several utility procedures to write code and
implement exercises of ``Structure and Interpretation of Computer Programs''.
@c JP
このモジュールは、『計算機プログラムの構造と解釈』(SICP)の練習課題を実装するための
いくつかのユーティリティを提供します。
@c COMMON

@c EN
We provide this module for the portability, i.e. to run existing
code that depends on this module.  If you're studying SICP and
writing code by yourself using Gauche, we recommend you to
install Gauche-compat-sicp extension
(@url{https://github.com/shirok/Gauche-compat-sicp}), for it takes care
of Gauche-specific matters.
@c JP
このモジュールを提供する主な目的は、このモジュールに依存している既存のコードの移植性のためです。
SICPの課題をGaucheで解きながら学んでいる場合は、
Gauche-compat-sicp拡張
(@url{https://github.com/shirok/Gauche-compat-sicp})を使うことをおすすめします。
Gauche特有の問題への対応が入っています。
@c COMMON
@end deftp

@defvr {Constant} true
@defvrx {Constant} false
@defvrx {Constant} nil
[SRFI-216]
@c MOD srfi.216
@c EN
Constants bound to @code{#t}, @code{#f}, and @code{()}, respectively.
@c JP
それぞれ@code{#t}、@code{#f}、@code{()}に束縛された定数です。
@c COMMON
@end defvr

@defun runtime
[SRFI-216]
@c MOD srfi.216
@c EN
Returns an exact integer monotonically increasing from certain point
of time in the past.  The absolute value doesn't matter, but you can
use differences of calls to @code{runtime} to compare relative elapsed time.
@c JP
過去のある時点から、時間経過によって単調増加する正確な整数を返します。
具体的な値に意味はありませんが、二つの@code{runtime}呼び出しの差を取ることで
相対的な時間経過を比較することができます。
@c COMMON
@end defun

@defun random n
[SRFI-216]
@c MOD srfi.216
@c EN
The argument @var{n} must be a positive real number.  Returns a random
nonnegative integer less than @var{n}.
@c JP
@var{n}は正の実数でなければなりません。@var{n}未満のランダムな非負整数を返します。
@c COMMON

@c EN
If @var{n} is exact, an exact integer is returned.  Otherwise, an inexact
integeer is returned.
@c JP
@var{n}が正確数なら、正確な整数が返ります。
そうでなければ不正確な整数が返ります。
@c COMMON
@end defun

@defun parallel-execute thunk thunk2 @dots{}
[SRFI-216]
@c MOD srfi.216
@c EN
Run given thunks in parallel using threads.  Returns an undefined
value after all thunks are completed.
@c JP
与えられた@var{thunk}を、スレッドを使って並列に実行します。
全ての@var{thunk}の実行が終了したら、未定義の値を返します。
@c COMMON
@end defun

@defun test-and-set! pair
[SRFI-216]
@c MOD srfi.216
@c EN
The argument must be a mutable pair.
If its @code{car} is @code{#f}, set it to @code{#t} and returns @code{#f}.
Otherwise returns @code{#t} without modifying the argument.
The operation is performed atomically.
@c JP
引数は変更可能なペアでなければなりません。
その@code{car}が@code{#f}なら、それを@code{#t}に変えて@code{#f}を返します。
そうでなければ引数は変更せずに@code{#f}を返します。
この操作はアトミックに行われます。
@c COMMON
@end defun

@defmac cons-stream a b
[SRFI-216]
@c MOD srfi.216
@c EN
Expands into @code{(cons a (delay b))}.  Note that the @code{car} side
of stream (@var{a}) is eagerly evaluated.
@c JP
@code{(cons a (delay b))}へと展開されます。@code{car}部分にあたる
@var{a}は積極的に評価されることに注意してください。
@c COMMON

@c EN
This is not compatible with @code{util.stream}'s @code{stream-cons}
(@pxref{Stream primitives}).  The reason SICP need this as primitive
is that SICP does not use macros, so it can't define its own
syntactic abstraction.
@c JP
これは@code{util.stream}の@code{stream-cons}と異なります
(@ref{Stream primitives}参照)。SICPはマクロを陽に使わないので、
このオペレータがプリミティブとして用意されている前提で書かれています。
@c COMMON
@end defmac

@defvr {Constant} the-empty-stream
[SRFI-216]
@c MOD srfi.216
@c EN
A singleton instance of the empty stream.  This should be used with
the following @code{stream-null?}.  Note that this is not compatible with
@code{stream-null} of @code{util.stream} (@pxref{Stream primitives}).
@c JP
空のストリームを表すシングルトンインスタンスです。
これは、次の@code{stream-null?}と一緒に使われなければなりません。
@code{util.stream}の@code{stream-null}と互換性はありません
(@ref{Stream primitives}参照)。
@c COMMON
@end defvr

@defun stream-null? obj
[SRFI-216]
@c MOD srfi.216
@c EN
Returns @code{#t} if @var{obj} is equivalent to @code{the-empty-stream},
@code{#f} otherwise.
Note that this is not the same as @code{stream-null?} of @code{util.stream}
(@pxref{Stream primitives}).
@c JP
@var{obj}が@code{the-empty-stream}であれば@code{#t}を、
そうでなければ@code{#f}を返します。
これは@code{util.stream}の@code{stream-null?}とは異なります
(@ref{Stream primitives}参照)。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Integer sets, Define higher-order lambda, SICP prerequisites, Library modules - SRFIs
@section @code{srfi.217} - Integer sets
@c NODE 整数集合,  @code{srfi.217} - 整数集合

@deftp {Module} srfi.217
@mdindex srfi.217
@c EN
This srfi defines a set whose element is limited to fixnums.

Although general sets are provided by @code{scheme.set}
(@pxref{R7RS sets}), this module may take advantage of limited-type
elements to optimize storage and operations.

It also provides range-based operations, which aren't available in
the general sets.
@c JP
このsrfiは要素がfixnumに限定されたセットを定義します。

汎用のセットは@code{scheme.set}で提供されています(@ref{R7RS sets}参照)が、
このモジュールは要素が限定されていることを利用してコンパクトにセットを保持します。

また、汎用のセットにはない、キーの範囲を使った操作も提供しています。
@c COMMON
@end deftp

@subheading Constructors

@defun iset element @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns a fresh iset contains @var{element} @dots{}.
Each @var{element} must be a fixnum.
@c JP
@var{element} @dots{} を要素とする新たなisetを作って返します。
各@var{element}はfixnumでなければなりません。
@c COMMON
@end defun

@defun iset-unfold p f g seed
[SRFI-217]
@c MOD srfi.217
@c EN
Constructs an iset whose element is computed procedurally.

The @var{p} argument is called with a current seed value.  If it returns
@code{#t}, the iteration ends.

The @var{f} argument is called with a current seed value, and returns
a fixnum to be included into the set.

The @var{g} argument is called with a current seed value, and returns
the next seed value.

The @var{seed} argument gives the initial seed.
@c JP
手続的に要素を計算して整数集合を作ります。

@var{p}は現在の状態値を引数に取り、それが@code{#t}を返せば繰り返しを終了します。

@var{f}は現在の状態値を引数に取り、集合に含めるべきfixnumを返します。

@var{g}は現在の状態値を引数に取り、次の状態値を返します。

@var{seed}は状態値の初期値を指定します。
@c COMMON

@example
(iset->list
 (iset-unfold (cut > <> 10) (cut * <> 2) (cut + <> 1) 0))
 @result{} (0 2 4 6 8 10 12 14 16 18 20)
@end example
@end defun

@defun make-range-iset start end :optional step
[SRFI-217]
@c MOD srfi.217
@c EN
Creates an iset that contains each fixnum in
@code{(numeric-range @var{start} @var{end} @var{step})}.
@xref{Range}, for the details of ranges.
@c JP
@code{(numeric-range @var{start} @var{end} @var{step})}で生成されるレンジ
に含まれるfixnumを要素とする整数集合を作って返します。
レンジについては@ref{Range}を参照してください。
@c COMMON

@example
(iset->list (make-range-iset 0 5))
 @result{} (0 1 2 3 4)
@end example
@end defun

@c EN
@subheading Predicates
@c JP
@subheading 述語
@c COMMON

@defun iset? obj
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @code{#t} iff @var{obj} is an iset.
@c JP
@var{obj}が整数集合なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun iset-contains? iset element
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @code{#t} iff @var{iset} contains @var{element}.
@c JP
@var{iset}が@var{element}を要素に持っていれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun iset-empty? iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @code{#t} iff @var{iset} is empty.
@c JP
@var{iset}が空なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun iset-disjoint? iset1 iset2
[SRFI-217]
@c MOD srfi.217
@c EN
Both arguments must be an iset.  Returns @code{#t} iff no element belongs
to both isets.
@c JP
引数はともに整数集合でなければなりません。
両方に共通する要素が無ければ@code{#t}を、あれば@code{#f}を返します。
@c COMMON
@end defun

@c EN
@subheading Accessors
@c JP
@subheading アクセサ
@c COMMON

@defun iset-member iset element default
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @var{element} if it is contained in @var{iset}, otherwise @var{default}.
@c JP
@var{element}が@var{iset}の要素であればそれを、
でなければ@var{default}を返します。
@c COMMON
@end defun

@defun iset-min iset
@defunx iset-max iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns the minimum and the maximum element in @var{iset}.  If
@var{iset} is empty, returns @code{#f}.
@c JP
@var{iset}の最小または最大の要素を返します。
@var{iset}が空の場合は@code{#f}を返します。
@c COMMON
@end defun

@c EN
@subheading Updaters
@c JP
@subheading 更新
@c COMMON

@defun iset-adjoin iset elt1 elt2 @dots{}
@defunx iset-adjoin! iset elt1 elt2 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that includes all the elements in @var{iset},
plus @var{elt1} @var{elt2} @dots{}.
An error is thrown if @var{elt1} @var{elt2} @dots{} include other than
fixnums.
@c JP
@var{iset}の要素に、@var{elt1} @var{elt2} @dots{}を加えたものを要素として持つ
整数集合を返します。@var{elt1} @var{elt2} @dots{} にfixnum以外のものが
含まれていたらエラーが投げられます。
@c COMMON

@c EN
The linear update version @code{iset-adjoin!} may reuse @var{iset}
to store the result, but the caller must always use its return value.
@c JP
線形更新版@code{iset-adjoin!}は結果を作るのに@var{iset}を再利用するかもしれません。
ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
@c COMMON
@end defun

@defun iset-delete iset elt1 elt2 @dots{}
@defunx iset-delete! iset elt1 elt2 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that includes the elements in @var{iset}
except the ones matching one of @var{elt1} @var{elt2} @dots{}.
@c JP
@var{iset}の要素から、@var{elt1} @var{elt2} @dots{}を除いたものを含む
整数集合を返します。
@c COMMON

@c EN
The linear update version @code{iset-delete!} may reuse @var{iset}
to store the result, but the caller must always use its return value.
@c JP
線形更新版@code{iset-delete!}は結果を作るのに@var{iset}を再利用するかもしれません。
ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
@c COMMON
@end defun

@defun iset-delete-all iset elt-list
@defunx iset-delete-all! iset elt-list
[SRFI-217]
@c MOD srfi.217
@c EN
The @var{elt-list} argument must be a list of fixnums.
Returns an iset that includes the elements in @var{iset}
except the ones in @var{elt-list}.
@c JP
@var{elt-list}引数はfixnumのリストでなければなりません。
@var{iset}の要素から、@var{elt-list}に含まれるfixnumを取り除いたものを要素とする
整数集合を返します。
@c COMMON

@c EN
The linear update version @code{iset-delete-all!} may reuse @var{iset}
to store the result, but the caller must always use its return value.
@c JP
線形更新版@code{iset-delete-all!}は結果を作るのに@var{iset}を再利用するかもしれません。
ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
@c COMMON
@end defun

@defun iset-delete-min iset
@defunx iset-delete-min! iset
@defunx iset-delete-max iset
@defunx iset-delete-max! iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns two values: The minimum or the maximum element in @var{iset},
and a new iset that contains elements in @var{iset} except the
minimum/maximum element.   An error is thrown if @var{iset} is empty.
@c JP
二つの値を返します。@var{iset}の最小もしくは最大の要素と、
その要素を取り除いた整数集合です。@var{iset}が空の場合はエラーが投げられます。
@c COMMON

@c EN
The linear update version @code{iset-delete-min!}/@code{iset-delete-max!}
may reuse @var{iset} to store the result,
but the caller must always use its return value.
@c JP
線形更新版@code{iset-delete-min!}/@code{iset-delete-mac!}は結果を作るのに
@var{iset}を再利用するかもしれません。
ただしそれは保証されていないので、呼び出し側は常に返り値を利用してください。
@c COMMON
@end defun

@defun iset-search iset element failure success
@defunx iset-search! iset element failure success
[SRFI-217]
@c MOD srfi.217
@c EN
Search @var{iset} for matching @var{element} from lowest to highest value.
They return two values, a (possibly updated) iset, and auxiliary
value as explained below.  The @var{failure} and @var{success}
arguments are both procedures.
@c JP
@var{iset}の要素のうち@var{element}と一致するものを下から順に探します。
戻り値は二つで、一つ目は整数集合、二つ目は以下に説明する補助値です。
@var{failure}と@var{success}はともに手続きです。
@c COMMON

@c EN
If @var{element} is found, the @var{success} procedure is called
with three arguments: the matching element of @var{iset}, a procedure
@var{update}, and a procedure @var{remove}.  The @var{success} procedure
can either return or tail call one of either @var{update} or @var{remove}.
@c JP
@var{element}が見つかった場合、@var{success}が3つの引数で呼び出されます:
マッチした要素、手続き@var{update}、そいて手続き@var{remove}です。
@var{success}手続きはそのまま戻るか、@var{update}か@var{remove}のどちらかを
末尾呼び出しすることができます。
@c COMMON

@c EN
The @var{update} procedure
can be invoked with two arguments, @var{new-element} and @var{obj}; if
called, @var{new-element} replaces @var{element} in @var{iset}, and
@code{iset-search} returns the new iset and @var{obj}.
The @var{remove} procedure can be invoked with one argument, @var{obj}.
It removes the matching element from @var{iset} and @code{iset-search}
returns the new iset and @var{obj}.
When those procedures are tail-called from @var{success}, those values
become the return values of @code{iset-search}.
@c JP
@var{update}手続きは二つの引数@var{new-element}と@var{obj}を取ります。
呼ばれると、この手続きは@var{iset}の要素@var{element}を@var{new-element}
で置き換えた整数集合および@var{obj}を戻り値として返します。
@var{remove}手続きは一つの引数@var{obj}を取り、@var{iset}から@var{element}
を除いた整数集合および@var{obj}を戻り値として返します。
@var{success}手続きからこれらの手続きが末尾呼び出しされていれば、
この整数集合と@var{obj}がそのまま@code{iset-search}の戻り値となります。
@c COMMON

@c EN
If @var{element} is not found, the @var{failure} procedure is called
with two arguments, @var{insert} and @var{ignore}, both procedures
and @var{failure} is expected to tail-call one of them.
@c JP
@var{element}が見つからなかった場合、@var{failure}手続きが二つの引数、
@var{insert}と@var{ignore}を伴って呼ばれます。これらはそれぞれが手続きで、
@var{failure}はどちらかを末尾呼び出ししなければなりません。
@c COMMON

@c EN
The @var{insert} procedure can be called with one argument, @var{obj}.
It causes @code{iset-search} to return a new iset that contains all
the elements from @var{iset} plus @var{element}, and @var{obj}.
The @var{ignore} procedure can be called with one argument, @var{obj}.
It causes @code{iset-search} to return the original @var{iset} and
@var{obj}.
@c JP
@var{insert}手続きはひとつの引数@var{obj}を取り、
@var{element}を@var{iset}に追加した整数集合と@var{obj}を戻り値とします。
@var{ignore}手続きはひとつの引数@var{obj}を取り、
@var{iset}そのものと@var{obj}を戻り値とします。
@c COMMON

@c EN
The linear update version, @code{iset-search!}, may reuse @var{iset}
for the updated iset.
@c JP
線形更新版の@code{iset-search!}では、結果の整数集合を作るために
@var{iset}が破壊的に変更されるかもしれません。
@c COMMON
@end defun

@c EN
@subheading The whole iset
@c JP
@subheading 集合全体への操作
@c COMMON

@defun iset-size iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns the number of elements in @var{iset}.
@c JP
@var{iset}の要素数を返します。
@c COMMON
@end defun

@defun iset-find pred iset failure
[SRFI-217]
@c MOD srfi.217
@c EN
Returns the smallest element of @var{iset} that satisfies @var{pred}.
If no element satisfies @var{pred}, @var{failure} is called with no
arguments, and its result is returned from @code{iset-find}.
@c JP
@var{iset}の要素のうち、述語@var{pred}を満たす最小の要素を返します。
もし@var{pred}を満たす要素が見つからなかったら、手続き@var{failure}を引数無しで
呼び出しその結果を返します。
@c COMMON
@end defun

@defun iset-count pred iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns the number of elements in @var{iset} that satisfy @var{pred}.
@c JP
@var{iset}の要素のうち、述語@var{pred}を満たすものの個数を返します。
@c COMMON
@end defun

@defun iset-any? pred iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @code{#t} if any element in @var{iset} satisfies @var{pred},
@code{#f} otherwise.
@c JP
@var{iset}の要素のうち@var{pred}を満たすものがひとつでもあれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@c COMMON
@end defun

@defun iset-every? pred iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @code{#t} if every element in @var{iset} satisfies @var{pred},
@code{#f} otherwise.
@c JP
@var{iset}の要素が全て@var{pred}を満たしたら@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@c EN
@subheading Mapping and folding
@c JP
@subheading マップとfold
@c COMMON

@defun iset-map proc iset
[SRFI-217]
@c MOD srfi.217
@c EN
Creates and returns a new iset whose elements consist of
the result of @var{proc} applied to each element of the given @var{iset}.
An error is signaled if @var{proc} doesn't return a fixnum.
@c JP
@var{iset}の各要素に@var{proc}を適用し、その結果を集めた@var{iset}を作って返します。
@var{proc}の戻り値がfixnumでなければエラーが投げられます。
@c COMMON

@c EN
Note that the size of the result set may be smaller than the input,
if @var{proc} isn't injective.
@c JP
@var{proc}が単射でなければ、返される整数集合は元の@var{iset}より小さくなります。
@c COMMON

@c EN
The order of @var{proc}'s application is unspecified.
@c JP
@var{proc}が適用される順序は不定です。
@c COMMON
@end defun

@defun iset-for-each proc iset
[SRFI-217]
@c MOD srfi.217
@c EN
Applies @var{proc} to each element in @var{iset} in increasing order.
The result of @var{proc} is discarded.  Returns unspecified result.
@c JP
@var{proc}を@var{iset}の各要素に、要素の昇順に適用します。
@var{proc}の結果は捨てられます。戻り値は指定されません。
@c COMMON
@end defun

@defun iset-fold kons knil iset
@defunx iset-fold-right kons knil iset
[SRFI-217]
@c MOD srfi.217
@c EN
Like @code{fold}/@code{fold-right}, apply @var{kons} on each element
in @var{iset}, increasing or decreasing order,
passing the result to the previous @var{kons}, or @var{knil}
for the first iteration.  Returns the last result of @var{kons}.
If @var{iset} is empty, @var{kons} is never called and @var{knil} is
returned as is.
@c JP
@code{fold}/@code{fold-right}と同じように、@var{kons}を@var{iset}の各要素と
直前の@var{kons}の結果を引数にして呼び出してゆきます。最初の@var{kons}の呼び出しには
@var{knil}が使われます。要素はそれぞれ昇順/降順に呼び出されます。
最後の@var{kons}の結果が戻り値になります。
@var{iset}が空なら、@var{kons}は呼ばれず@var{knil}がそのまま返されます。
@c COMMON

@example
(iset-fold cons '() (iset 2 3 5 7 11))
  @result{} (11 7 5 3 2)
(iset-fold-right cons '() (iset 2 3 5 7 11))
  @result{} (2 3 5 7 11)
@end example
@end defun

@defun iset-filter pred iset
@defunx iset-filter! pred iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that contains the elements in @var{iset} that satisfy @var{pred}.
The linear-update version @code{iset-filter!} may reuse given @var{iset}
to store the result.
@c JP
@var{iset}の要素のうち、述語@var{pred}を満たすものだけを集めた整数集合を作って返します。
線形更新版@code{iset-filter!}は結果を作るために@var{iset}を再利用するかもしれません。
@c COMMON
@end defun

@defun iset-remove pred iset
@defunx iset-remove! pred iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that contains the elements in @var{iset} that do not satisfy
@var{pred}.
The linear-update version @code{iset-remove!} may reuse given @var{iset}
to store the result.
@c JP
@var{iset}の要素のうち、述語@var{pred}を満たさないものだけを集めた整数集合を作って返します。
線形更新版@code{iset-remove!}は結果を作るために@var{iset}を再利用するかもしれません。
@c COMMON
@end defun

@defun iset-partition pred iset
@defunx iset-partition! pred iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns two isets, first one consisting of the elements in @var{iset} that
satisfy @var{pred}, and the second one consisting of the elements that
don't.
The linear-update version @code{iset-partition!} may reuse given @var{iset}
to store one of the results.
@c JP
ふたつの整数集合を返します。一つ目は、@var{iset}の要素のうち述語@var{pred}を満たすもの、
二つ目は満たさないものを集めた集合です。
線形更新版@code{iset-partition!}は結果を作るために@var{iset}を再利用するかもしれません。
@c COMMON
@end defun

@c EN
@subheading Copying and conversion
@c JP
@subheading コピーと変換
@c COMMON

@defun iset-copy iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns a copy of @var{iset}.
@c JP
@var{iset}のコピーを返します。
@c COMMON
@end defun

@defun iset->list iset
[SRFI-217]
@c MOD srfi.217
@c EN
Returns a list of elements in @var{iset}, in increasing order.
@c JP
@var{iset}の要素を昇順に並べたリストを返します。
@c COMMON
@end defun

@defun list->iset list
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that contains elements in @var{list}.  The elements
in @var{list} must be fixnums.  Duplicate elements are consolidated.
@c JP
@var{list}はfixnumのリストでなければなりません。
それらを要素として持つ整数集合を作って返します。重複する要素はひとつにまとめられます。
@c COMMON
@end defun

@defun list->iset! iset list
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset consists of the elements from @var{iset} and @var{list}.
All the elements must be fixnums.
It may reuse the given @var{iset} to store the result.
@c JP
@var{iset}に、fixnumのリスト@var{list}を要素として足した整数集合を返します。
引数@var{iset}は結果を作るために破壊的に再利用されるかもしれません。
@c COMMON
@end defun

@c EN
@subheading Subsets
@c JP
@subheading 部分集合
@c COMMON

@defun iset=? iset1 iset2 iset3 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns @code{#t} iff all given isets contains the same elements.
@c JP
与えられた整数集合すべてが同じ要素を含んでいれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun iset<? iset1 iset2 iset3 @dots{}
@defunx iset<=? iset1 iset2 iset3 @dots{}
@defunx iset>? iset1 iset2 iset3 @dots{}
@defunx iset>=? iset1 iset2 iset3 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
These compares subset relationships between isets.
@code{(iset<=? iset1 iset2)} is @code{#t} iff every element of @var{iset1}
is contained in @var{iset2}, and so on.
@c JP
整数集合間の包含関係を比較します。
例えば@code{(iset<=? iset1 iset2)}は、@var{iset1}の全ての要素が@var{iset2}に
含まれている場合(@var{iset1}が@var{iset2}の部分集合である場合)に@code{#t}、
そうでなければ@code{#f}となります。
@c COMMON
@end defun

@c EN
@subheading Set theory operations
@c JP
@subheading 集合演算
@c COMMON

@defun iset-union iset1 iset2 iset3 @dots{}
@defunx iset-union! iset1 iset2 iset3 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that is a union of given isets.  Functional version
@code{iset-union} always returns a fresh iset.  Linear update version
@code{iset-union!} may reuse @var{iset1} to produce the result.
@c JP
与えられた整数集合の和集合を返します。
@code{iset-union}は関数的で、常に新たな整数集合を作って返します。
線形更新版の@code{iset-union!}は、結果を作るために@var{iset1}を破壊的に再利用する
かもしれません。
@c COMMON
@end defun

@defun iset-intersection iset1 iset2 iset3 @dots{}
@defunx iset-intersection! iset1 iset2 iset3 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that is an intersction of the given iset.  Functional version
@code{iset-intersection} always returns a fresh iset.  Linear update version
@code{iset-intersection!} may reuse @var{iset1} to produce the result.
@c JP
与えられた整数集合全てに共通する要素を含む整数集合を返します。
@code{iset-intersection}は関数的で、常に新たな整数集合を作って返します。
線形更新版の@code{iset-intersection!}は、結果を作るために@var{iset1}を破壊的に再利用する
かもしれません。
@c COMMON
@end defun

@defun iset-difference iset1 iset2 iset3 @dots{}
@defunx iset-difference! iset1 iset2 iset3 @dots{}
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that has elements in @var{iset1} but not
in @var{iset2} @var{iset3} @dots{}.
Functional version
@code{iset-difference} always returns a fresh iset.  Linear update version
@code{iset-difference!} may reuse @var{iset1} to produce the result.
@c JP
@var{iset1}の要素のうち、@var{iset2}, @code{iset3} @dots{}に含まれないものを
集めた整数集合を返します。
@code{iset-difference}は関数的で、常に新たな整数集合を作って返します。
線形更新版の@code{iset-difference!}は、結果を作るために@var{iset1}を破壊的に再利用する
かもしれません。
@c COMMON
@end defun

@defun iset-xor iset1 iset2
@defunx iset-xor! iset1 iset2
[SRFI-217]
@c MOD srfi.217
@c EN
Returns an iset that has elements, each of which is either in @var{iset1}
or @var{iset2} but not in both.
Functional version
@code{iset-xor} always returns a fresh iset.  Linear update version
@code{iset-xor!} may reuse @var{iset1} to produce the result.
@c JP
@var{iset1}と@var{iset2}のどちらか一方のみに含まれている要素を集めた整数集合を
返します。
@code{iset-xor}は関数的で、常に新たな整数集合を作って返します。
線形更新版の@code{iset-xor!}は、結果を作るために@var{iset1}を破壊的に再利用する
かもしれません。
@c COMMON
@end defun

@c EN
@subheading Intervals and ranges
@c JP
@subheading 区間
@c COMMON

@defun iset-open-interval iset low high
@defunx iset-closed-interval iset low high
@defunx iset-open-closed-interval iset low high
@defunx iset-closed-open-interval iset low high
[SRFI-217]
@c MOD srfi.217
@c EN
Extract elements in @var{iset} that are in the range
specified by @var{low} and @var{high}, which must be real numbers.
The `open' and `close' in the name indicates whether
the boundary is included; @code{iset-open-interval} doesn't include
both boundary, @code{iset-close-interval} includes both
boundary, @code{iset-open-closed-interval} includes @var{high} but
not @var{low} @code{set-closed-open-interval} inclues @var{low}
but not @var{high}.
@c JP
@var{iset}の要素のうち、実数@var{low}と@var{high}で指定される区間内の
要素のみを含む@var{iset}を返します。下限@var{low}、上限@var{high}それぞれを
区間に含むか含まないかで4種類のバリエーションがあります。
@code{iset-open-interval}は共に含まず、
@code{iset-close-interval}は共に含み、
@code{iset-open-closed-interval}は@var{low}を含まず@var{high}は含み、
@code{iset-closed-open-interval}は@var{low}を含み@var{high}は含みません。
@c COMMON

@example
(iset->list (iset-open-interval (iset 2 3 5 7 11) 2 7))
  @result{} (3 5)
(iset->list (iset-closed-interval (iset 2 3 5 7 11) 2 7))
  @result{} (2 3 5 7)
(iset->list (iset-open-closed-interval (iset 2 3 5 7 11) 2 7))
  @result{} (3 5 7)
(iset->list (iset-closed-open-interval (iset 2 3 5 7 11) 2 7))
  @result{} (2 3 5)
@end example
@end defun

@defun isubset= iset k
@defunx isubset< iset k
@defunx isubset<= iset k
@defunx isubset> iset k
@defunx isubset>= iset k
[SRFI-217]
@c MOD srfi.217
@c EN
Returns a subset of @var{iset} whose elements are equal to,
less than, less than or equal to, greater than, and greater than or
equal to, @var{k}, which must be a real number.
@c JP
@var{iset}の要素のうち、それぞれ、
実数@var{k}と等しい要素のみを含む部分集合、
@var{k}未満の要素のみを含む部分集合、
@var{k}以下の要素のみを含む部分集合、
@var{k}超過の要素のみを含む部分集合、
@var{k}以上の要素のみを含む部分集合を返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Define higher-order lambda, Generator/accumulator sub-library, Integer sets, Library modules - SRFIs
@section @code{srfi.219} - Define higher-order lambda
@c NODE 高階lambdaの定義,  @code{srfi.219} - 高階lambdaの定義

@deftp {Module} srfi.219
@mdindex srfi.219
@c EN
This srfi enhances @code{define} form to allow defining
function-returning-function compactly.  It works as follows:
@c JP
このsrfiは、関数を返す関数を簡単に定義できるように@code{define}を拡張します。
次のように動作します。
@c COMMON

@example
(define ((f a b) c d) ...)
 @equiv{} (define (f a b) (lambda (c d) ...))
 @equiv{} (define f (lambda (a b) (lambda (c d) ...)))

(define (((f a) b) c) ...)
 @equiv{} (define ((f a) b) (lambda (c) ...))
 @equiv{} (define (f a) (lambda (b) (lambda (c) ...)))
 @equiv{} (define f (lambda (a) (lambda (b) (lambda (c) ...))))
@end example

@c EN
This feature has been traditionally supported in many
implementations, including Gauche.  So you can use this feature
without using @code{srfi.193}.   This module is provided for
the portable code.
@c JP
この機能は伝統的に多くの実装でサポートされており、Gaucheも例外ではありません。
従って@code{srfi.193}を使わないでもこの機能を使うことはできます。
ポータブルなコードを書く必要がある場合にこのモジュールを使うと良いでしょう。
@c COMMON

@c EN
Note: Gauche has two @code{define}s: A ``vanilla'' @code{define} that
works as defined in R7RS, and an ``extended'' @code{define} that
supports extended lambda arguments.  If you import @code{srfi.193},
it imports the former, hence extended lambda arguments are not available.
It's what you need for the portable code.
@c JP
Gaucheはふたつの@code{define}を持っています。
R7RSで定義されているとおりの「素の」@code{define}と、
拡張ラムダ引数をサポートしている「拡張」@code{define}です。
@code{srfi.193}をインポートすると前者の@code{define}がインポートされます。
ポータブルなコードに必要なのは前者だからです。
@c COMMON
@end deftp

@c ----------------------------------------------------------------------
@node Generator/accumulator sub-library, Compound objects, Define higher-order lambda, Library modules - SRFIs
@section @code{srfi.221} - Generator/accumulator sub-library
@c NODE ジェネレータ/アキュムレータ サブライブラリ, @code{srfi.221} - ジェネレータ/アキュムレータ サブライブラリ

@deftp {Module} srfi.221
@mdindex srfi.221
@c EN
This srfi adds several utility procedures to the generator library
(@pxref{Generators}, for Gauche's native support of generators;
@pxref{R7RS generators}, for R7RS-large spec).
@c JP
このsrfiは、ジェネレータライブラリにいくつか有用な手続きを追加するものです。
(Gaucheのネイティブなジェネレータについては@ref{Generators}を、
R7RS-largeのジェネレータについては@ref{R7RS generators}を参照。)
@c COMMON
@end deftp

@defun gcompose-left constructor operation @dots{}
@defunx gcompose-right constructor operation @dots{}
[SRFI-221]
@c MOD srfi.221
@c EN
The @var{constructor} argument is a thunk that returns a generator.
Each @var{operation} is a procedure that takes a generator and returns
a generator.
@c JP
@var{constructor}は引数を取らずジェネレータを返す手続き、
各@var{operation}はジェネレータを取りジェネレータを返す手続きです。
@c COMMON

@c EN
These procedures creates and returns a generator that is a composition
of given operations on top of the one constructed by @var{constructor}.
@code{gcompose-left} applies @var{operation}s left to right (left-associative),
while @code{gcompose-right} does right to left (right-associative).
@c JP
これらの手続きは、@var{constructor}で作られるジェネレータに@var{operations}を
合成したジェネレータを作って返します。
@code{gcompose-left}は@var{operator}を左から右に(左結合)、
@code{gcompose-right}は右から左に(右結合)適用します。
@c COMMON

@example
(use gauche.generator)
(use srfi.221)

(generator->list
  (gcompose-left
    (cut make-iota-generator 100)
    (cut gfilter even? <>)
    (cut ggroup <> 5)))
 @result{} ((0 2 4 6 8) (10 12 14 16 18) (20 22 24 26 28)
     (30 32 34 36 38) (40 42 44 46 48) (50 52 54 56 58)
     (60 62 64 66 68) (70 72 74 76 78) (80 82 84 86 88)
     (90 92 94 96 98))

;; The same result can be obtained with:
(generator->list
  (gcompose-right
    (cut ggroup <> 5)
    (cut gfilter even? <>)
    (cut make-iota-generator 100)))
@end example
@end defun

@defun accumulate-generated-values accumulator generator
[SRFI-221]
@c MOD srfi.221
@c EN
Calls @var{generator} repeatedly, accumulating the values into
@var{accumulator}, until @var{generator} is exhausted.  Then it
retrieves and returns the accumulated value.
@xref{R7RS generators}, for the details of accumulators.
@c JP
@var{generator}を繰り返し呼び、得られる値を@var{accumulator}に蓄積してゆきます。
@var{generator}が尽きたら、蓄積された値を返します。
アキュムレータについては@ref{R7RS generators}を参照してください。
@c COMMON

@c EN
It is a generalization of @code{generator->list} type of converter;
you can pass an accumulator that returns the desired type of result.
@c JP
これは、@code{generator->list}のような変換器の一般化です。
渡すアキュムレータによって、どういうオブジェクトに変換するかが決まります。
@c COMMON
@end defun

@defun genumerate gen
[SRFI-221]
@c MOD srfi.221
@c EN
Returns a generator that yields pairs, each of which consists of
an exact integer count and the value yielded by @var{gen}.
The count starts from 0 and incremented.
@c JP
0から始まる整数と、@var{gen}が生成する値とのペアを次々に生成するジェネレータを返します。
@c COMMON

@example
(generator->list (genumerate (list->generator '(a b c d e))))
  @result{} ((0 . a) (1 . b) (2 . c) (3 . d) (4 . e))
@end example
@end defun

@defun gchoice choice-gen source-gen @dots{}
[SRFI-221]
@c MOD srfi.221
@c EN
All arguments are generators.
Returns a generator that yields a value from one of @var{source-gen}s,
according to @var{choice-gen}.
@c JP
引き数は全てジェネレータです。
@var{choice-gen}ジェネレータの値に従って@var{source-gen}を選び、そのジェネレータが
生成する値を返すようなジェネレータを作って返します。
@c COMMON

@c EN
The @var{choice-gen} must be a generator that yields exact integers
between 0 and one minus the number of @var{source-gen}s.
@c JP
@var{choice-gen}は0から@var{source-gen}の数マイナス1までの正確な整数を
返すジェネレータです。
@c COMMON

@c EN
Each time the resulting generator is invoked, @var{choice-gen} is called.
If it is exhausted, the resulting generator is also exhausted.
@c JP
結果のジェネレータが呼ばれると、まず@var{choice-gen}が呼ばれます。
それが既に尽きていたら、結果のジェネレータも尽きます。
@c COMMON

@c EN
Otherwise, the @var{source-gen} indexed by the result of @var{choice-gen}
is called, and if it isn't exhausted, the value is returned.
@c JP
そうでなければ、@var{choice-gen}の値番目の@var{source-gen}が選ばれて呼ばれ、
それが尽きてなければその結果が返されます。
@c COMMON

@c EN
If the selected @var{source-gen} is exhausted, @var{choice-gen} is retried
until non-exhausted @var{source-gen} yields a value.  If all @var{source-gen}
is exhausted, the resulting generator is also exhausted.
@c JP
選ばれた@var{source-gen}が既に尽きていた場合、尽きていない@var{source-gen}が選ばれるまで
@var{choice-gen}が繰り返し呼ばれます。全ての@var{source-gen}が尽きた場合は
結果のジェネレータも尽きます。
@c COMMON
@end defun

@defun stream->generator stream
[SRFI-221]
@c MOD srfi.221
@c EN
Returns a generator that yields each element of a lazy stream @var{stream}.
Lazy streams are defined in R7RS-large @code{scheme.stream}
(@pxref{R7RS stream}), which is a subset of Gauche's @code{util.stream}
(@pxref{Stream library}).
@c JP
遅延ストリーム@var{stream}の要素を次々に生成するジェネレータを返します。
遅延ストリームは、R7RS-largeの@code{scheme.stream}で定義されています
(@ref{R7RS stream}参照)。それはGaucheの@code{util.stream}のサブセットです
(@ref{Stream library}参照)。
@c COMMON
@end defun

@defun generator->stream generator
[SRFI-221]
@c MOD srfi.221
@c EN
Returns a lazy stream whose elements consist of the values
generated by @var{generator}
Lazy streams are defined in R7RS-large @code{scheme.stream}
(@pxref{R7RS stream}), which is a subset of Gauche's @code{util.stream}
(@pxref{Stream library}).
@c JP
@var{generator}が生成する値を要素とする遅延ストリームを返します。
遅延ストリームは、R7RS-largeの@code{scheme.stream}で定義されています
(@ref{R7RS stream}参照)。それはGaucheの@code{util.stream}のサブセットです
(@ref{Stream library}参照)。
@c COMMON

@c EN
See also @code{generator->lseq} (@pxref{Lazy sequences}),
which returns a lazy sequence defined in R7RS-large @code{scheme.lseq}.
In Gauche, lazy sequences are integrated to ordinary lists and more
lightweight than lazy streams.
@c JP
なお、R7RS-largenの@code{scheme.lseq}で定義される遅延シーケンスを返す
@code{genreator->lseq}もあります (@ref{Lazy sequences}参照)。
Gaucheでは、遅延シーケンスは通常のリストと統合されていて、遅延ストリームより軽いです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Compound objects, Control features, Generator/accumulator sub-library, Library modules - SRFIs
@section @code{srfi.222} - Compound objects
@c NODE 複合オブジェクト, @code{srfi.222} - 複合オブジェクト

@deftp {Module} srfi.222
@mdindex srfi.222
@c EN
Compound objects are encapsulation of an immutable sequence of objects.
Any objects other than a compound object can be included in a compound object;
if you try to create a compound object including compound objects,
it is 'flattened'---that is, the source's subobjects are retrieved
and each one is put into the new compound object.
@c JP
複合オブジェクトは、オブジェクトの並びをまとめたもので、それ自体は変更不可なオブジェクトです。
複合オブジェクト以外の任意オブジェクトを要素とすることができます。
複合オブジェクトを含めようとした場合は、
その要素が取り出されてそれぞれ結果の複合オブジェクトに埋め込まれます。
つまり複合オブジェクトがネストすることはありません。
@c COMMON

@c EN
This is an abstraction of the compound condition (@pxref{Conditions}),
although Gauche's compound conditions are not built on this.
@c JP
これは複合コンディション (@pxref{Conditions}) の機能を抽象化したものです。
ただし、Gaucheでは複合コンディション自体は複合オブジェクトとしては実装されていません。
@c COMMON

@c EN
This module is mainly provided for the compatibility; used with
R7RS records (@pxref{Record types}), you can have a portable
multiple inheritance of records.
@c JP
このモジュールは主に互換性のために提供されています。
R7RSレコード(@pxref{Record types})と併用すれば、
移植可能な形でレコードの多重継承を扱うことができます。
@c COMMON
@end deftp

@defun make-compound obj @dots{}
[SRFI-222]
@c MOD srfi.222
@c EN
Returns a compound objects having @var{obj} @dots{} as its subobjects.
Each @var{obj} can any Scheme object, but
if @var{obj} is a compound object itself, it is expanded into its
subobjects:
@c JP
@var{obj} @dots{}をサブオブジェクトとして持つ複合オブジェクトを作って返します。
@var{obj}は任意のSchemeオブジェクトですが、それが複合オブジェクトだった場合は、
そのサブオブジェクトがそこに展開されて使われます。
@c COMMON

@example
(make-compound 1 2 3)
 @result{} #<compound-object (1 2 3)>
(make-compund 0 (make-compound 1 2 3) 4 5)
 @result{} #<compound-object (0 1 2 3 4 5)>
@end example
@end defun

@defun compound? obj
[SRFI-222]
@c MOD srfi.222
@c EN
Returns @code{#t} iff @var{obj} is a compound object.
@c JP
@var{obj}が複合オブジェクトなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun compound-subobjects obj
[SRFI-222]
@c MOD srfi.222
@c EN
If @var{obj} is a compound, returns a list of its subobjects.
Otherwise, returns a 1-element list of @var{obj}.

That is, it always returns a list of non-compound objects.
@c JP
@var{obj}が複合オブジェクトなら、そのサブオブジェクトのリストを、
そうでなければ@var{obj}ひとつを要素とするリストを返します。

すなわち、返されるのは常に、複合オブジェクトを含まないオブジェクトのリストです。
@c COMMON
@end defun

@defun compound-length obj
[SRFI-222]
@c MOD srfi.222
@c EN
If @var{obj} is a compound, returns the number of its subobjects.
Otherwise, returns 1.
@c JP
@var{obj}が複合オブジェクトなら持っているサブオブジェクトの数を、
そうでなければ1を返します。
@c COMMON
@end defun

@defun compound-ref obj k
[SRFI-222]
@c MOD srfi.222
@c EN
Returns @var{k}-th subobject of @var{obj} if it is a compound.
Othrewise, @var{k} must be zero and @var{obj} itself is returned.
@c JP
@var{obj}が複合オブジェクトなら@var{k}番目のサブオブジェクトを返します。
そうでなければ、@var{k}は0でなければならず、その場合@var{obj}自身が返されます。
@c COMMON

@c EN
An error is thrown if @var{k} is not a nonnegative exact integer
or out of range.
@c JP
@var{k}が非負の正確な整数でなかったり、指定可能範囲外であればエラーが投げられます。
@c COMMON
@end defun

@defun compound-map mapper obj
[SRFI-222]
@c MOD srfi.222
@c EN
Returns a compound object whose subobjects are result of applying
@var{mapper} on each subobject of @var{obj}.  If @var{obj} is not
a compound, it is treated as if a compound with @var{obj} as a sole
subobject.  Note that if @var{mapper} returns a compound, its subobjects
are spliced in place.  Thus the number of subobjects of the result may differ
from the number of subobjects of @var{obj}.
@c JP
@var{obj}の持つサブオブジェクトそれぞれに@var{mapper}を適用し、その結果を集めた
複合オブジェクトを作って返します。@var{obj}が複合オブジェクトでなければ、
あたかも@var{obj}自身を唯一のサブオブジェクトとする複合オブジェクトであるかのように
扱われます。@var{mapper}が複合オブジェクトを返した場合、そのサブオブジェクトが
取り出されて結果に使われることに注意してください。つまり、
結果の持つサブオブジェクトの数は、@var{obj}の持つサブオブジェクトと異なる場合があります。
@c COMMON

@example
(compound-map (cut + 1 <>) (make-compound 1 2 3))
 @result{} #<compound (2 3 4)>
(compound-map (cut make-compound <> 'x) (make-compound 1 2 3))
 @result{} #<compound (1 x 2 x 3 x)>
(compound-map (cut + 1 <>) 3)
 @result{} #<compound (4)>
@end example
@end defun

@defun compound-map->list mapper obj
[SRFI-222]
@c MOD srfi.222
@c EN
Returns a list of results of applying @var{mapper} on each subobjects
of @var{obj}.  If @var{obj} is not a compound, @var{mapper} is directly
applied on @var{obj}.
@c JP
@var{mapper}を@var{obj}の各サブオブジェクトに適用し、結果のリストを返します。
@var{obj}が複合オブジェクトでなければ、@var{mapper}を直接@var{obj}に適用し、
結果をリストにくるんで返します。
@c COMMON

@c EN
Unlike @code{compound-map}, the result of @var{mapper} appears as is
in the result list, even when it is a compound object.  Hence the
length of the result list always matches @code{(compound-length obj)}.
@c JP
@code{compound-map}と異なり、@var{mapper}の結果が複合オブジェクトであった場合でも
それがそのまま結果のリストに現れます。つまり、結果のリストの長さは常に
@code{(compound-length obj)}と同じです。
@c COMMON

@example
(compound-map->list (cut + 1 <>) (make-compound 1 2 3))
 @result{} (2 3 4)
(compound-map->list (cut make-compound <> 'x) (make-compound 1 2 3))
 @result{} (#<compound (1 x)> #<compound (2 x)> #<compound (3 x)>)
(compound-map->list (cut + 1 <>) 3)
 @result{} (4)
@end example
@end defun

@defun compound-filter pred obj
[SRFI-222]
@c MOD srfi.222
@c EN
Collect subobjects of @var{obj} that satisfies @var{pred}, and
returns a compound that consists of them.  If @var{obj} is not a compound,
it is treated as if it is a compound with @var{obj} as a sole subobject.
@c JP
@var{obj}のサブオブジェクトにそれぞれ@var{pred}を適用し、それが真の値を返した
サブオブジェクトのみを集めて新たな複合オブジェクトを作って返します。
@var{obj}が複合オブジェクトでなければ、あたかもそれ自身を唯一のサブオブジェクトに持つ
複合オブジェクトのように扱われます。
@c COMMON

@example
(compound-filter odd? (make-compound 1 2 3))
 @result{} #<compound (1 3)>
(compound-filter odd? 1)
 @result{} #<compound (1)>
(compound-filter odd? 2)
 @result{} #<compound ()>
@end example
@end defun

@defun compound-predicate pred obj
[SRFI-222]
@c MOD srfi.222
@c EN
Returns @code{#t} if @var{obj} satisfies @var{pred},
or any of @var{obj}'s subobjects satisfies @var{pred}
when @var{obj} is a compound.  Returns @code{#f} otherwise.
@c JP
@var{obj}が述語@var{pred}を満たすか、@var{obj}が複合オブジェクトであり
いずれかのサブオブジェクトが@var{pred}を満たせば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun compound-access pred acc default obj
[SRFI-222]
@c MOD srfi.222
@c EN
If @var{obj} satisfies @var{pred}, @var{acc} is applied ot @var{obj}
and the result is returned.  Otherwise, if @var{obj} is a compound,
@var{pred} is applied on each subobject, and @var{acc} is applied
on the first subobject that satisfies @var{pred}, and the result
is returned.  If none of the case is satisfied, @var{default} is returned.
@c JP
@var{obj}が述語@var{pred}を満たした場合、@var{obj}に@var{acc}が適用され、
その結果が返されます。そうでなく、@var{obj}が複合オブジェクトの場合は、
そのサブオブジェクトが順に@var{pred}を満たすかどうか検査され、最初に満たした
サブオブジェクトに対して@var{acc}が適用され、その結果が返されます。
全てに当てはまらない場合は@var{default}が返されます。
@c COMMON

@example
(define-record-type <foo> make-foo foo?
  (f foo-f))

(define-record-type <bar> make-bar bar?
  (b bar-b))

(define c (make-compound (make-foo "foo!") (make-bar "bar!") '(ca . cd)))

(compound-access foo? foo-f 'none c) @result{} "foo!"
(compound-access bar? bar-b 'none c) @result{} "bar!"
(compound-access pair? car  'none c) @result{} ca
(compound-access char? char->integer 'none c) @result{} none
@end example
@end defun

@c ----------------------------------------------------------------------
@node Control features, Optional arguments, Compound objects, Library modules - SRFIs
@section @code{srfi.226} - Control features
@c NODE 制御機構, @code{srfi.226} - 制御機構

@deftp {Module} srfi.226
@mdindex srfi.226
@c EN
This srfi enhances the semantics of Scheme's fundamental concepts
such as continuations and dynamic environments, to support multi-threaded
programs and delimited continuations.  Some R7RS primitives such as
@code{call/cc} and @code{dynamic-wind} are extended
to be consistent with the enhanced execution model.
@c JP
このSRFIは、Schemeの根本的な概念である継続や動的環境のセマンティクスを、
マルチスレッドプログラムや限定継続をサポートできるように拡大するものです。
@code{call/cc}や@code{dynamic-wind}といったいくつかのR7RSプリミティブは、
拡大されたセマンティクスに一致するように拡張されます。
@c COMMON

@c EN
The thread API is mostly compatible with SRFI-18, and so as with
Gauche's thread API (@pxref{Threads}).
@c JP
スレッドAPIはSRFI-18およびGaucheのスレッドAPIとほぼ互換です (@ref{Threads}参照)。
@c COMMON

@c EN
Since the enhanced features are tightly coupled with runtime, most
APIs in this srfi is implemented as built-ins in Gauche.
This section gives you the overview of SRFI-226 APIs and pointers
to the documents.
@c JP
拡大された機能はランタイムと固く結びついているので、
このSRFIのAPIは主にGaucheの組み込みとして実装されています。
この節では、SRFI-226のAPIの一覧とドキュメントへのポインタを示します。
@c COMMON

@c EN
In 0.9.13, Gauche only implements part of SRFI-226.  We'll cover its entirety
in future releases.
@c JP
0.9.13の時点では、GaucheはSRFI-226の一部のみを実装しています。
将来のリリースで全てをカバーする予定です。
@c COMMON

@c EN
SRFI-226 is an upward compatible extension of R7RS.  However, Gauche has also
extended R7RS control features in regards of multi-threaded
programs, and there are subtle incompatibilites.  We'll move to
full SRFI-226 compatibility, but we also provide backward-compatible
interface.  If you use @code{srfi.226}, you'll get SRFI-226
behavior.
@c JP
SRFI-226はR7RSの上位互換になっています。
ただ、GaucheはGaucheでR7RSの制御機構をマルチスレッド向けに拡張していて、
SRFI-226と非互換であった部分があります。
徐々にSRFI-226互換に移行してゆきますが、後方互換なインタフェースも提供します。
@code{srfi.226}をuseした場合はSRFI-226の振る舞いになります。
@c COMMON
@end deftp

@c EN
Here's a list of SRFI-226 APIs and how Gauche supports them.
@c JP
以下が、SRFI-226のAPIのリストとGaucheのサポート状況です。
@c COMMON

@table @b
@item Continuation prompts
@table @code
@item &continuation
@itemx make-continuation-violation
@itemx continuation-violation?
@itemx continuation-violation-prompt-tag
@xref{Conditions}
@item make-continuation-prompt-tag
@itemx default-continuation-prompt-tag
@itemx continuation-prompt-tag?
@itemx call-with-continuation-prompt
@itemx abort-current-continuation
@xref{Continuation prompts}.
@end table

@item Continuations
@table @code
@item call-with-non-comosable-continuation
@itemx call-with-composable-continuation
Not implemented yet.
@item call-with-current-continuation
@itemx call/cc
@xref{Continuations}.
@item call-in-continuation
@itemx call-in
Not implemented yet.
@item call-with-continuation-barrier
Not implemented yet.
@item continuation-prompt-available?
Not implemented yet.
@item dynamic-wind
@xref{Continuations}.
@item unwind-protect
@xref{High-level exception handling mechanism}.
@end table

@item Shift and reset
@table @code
@item shift-at
@itemx reset-at
Not implemented yet.
@item shift
@itemx reset
@xref{Partial continuations}.  However, current implementation
of @code{shift}/@code{reset} hasn't integrated to SRFI-226 model
yet.
@end table

@item Inspection
@table @code
@item continuation?
@itemx non-composable-continuation?
Not implemented yet.
@end table

@item Continuation marks
@table @code
@item with-continuation-mark
@itemx with-continuation-marks
@itemx call-with-immediate-continuation-mark
@itemx continuation-marks
@itemx current-continuation-marks
@itemx continuation-mark-set?
@itemx continuation-mark-set->list
@itemx continuation-mark-set-first
@xref{Continuation marks}.
@item continuation-mark-set->list*
@itemx continuation-mark-set->iterator
Not implemented yet.
@item make-continuation-mark-key
@itemx continuation-mark-key?
@xref{Continuation marks}.
@end table

@item Parameter objects
@table @code
@item make-parameter
@itemx make-thread-parameter
@xref{Parameters}.  Gauche's built-in @code{make-parameter} works
in a compatibility mode for now.  If you use @code{srfi.226},
@code{make-parameter} works as specified in SRFI-226.
@item parameter?
@xref{Parameters}.
@item parameterize
@xref{Parameters}.  Gauche's built-in @code{parameterize} works
in a compatibility mode for now.  If you use @code{srfi.226},
@code{make-parameter} works as specified in SRFI-226.
@item current-parameterization
@itemx parameterization?
@itemx call-with-parameterization
@xref{Parameters}.
@item temporarily
@xref{Dynamic states}.
@end table

@item Fluids
@table @code
@item define-fluid
@itemx define-thread-fluid
@itemx define-fluidified
@itemx fluid-let
@itemx fluid-let*
@itemx fluid-parameter
Not implemented yet.
@end table

@item Initial continuations
@table @code
@item call-with-initial-continuation
Not implemented yet.
@end table

@item Promises
@table @code
@item delay
@itemx promise?
@itemx force
@itemx make-promise
@xref{Delay force and lazy}.
Gauche's built-ins are SRFI-226 compatible.
@end table

@item Exceptions
@table @code
@item with-exception-handler
@itemx current-exception-handler
@itemx exception-handler-stack
@xref{Low-level exception handling mechanism}.
Gauche's built-ins are SRFI-226 compatible.
@item raise
@itemx raise-continuable
@xref{Signaling exceptions}.
@item guard
@xref{High-level exception handling mechanism}.
@end table

@item Conditions
@table @code
@item &parameterization
@itemx make-parameterization-condition
@itemx parameterization-condition?
@itemx condition-parameterization
Not implemented yet.
@item &continuation-marks
@itemx make-continuation-marks-condition
@itemx continuation-marks-condition?
@itemx condition-continuation-marks
Not implemented yet.
@item &exception-handler-stack
@itemx make-exception-handler-stack-condition
@itemx exception-handler-stack-condition?
@itemx condition-exception-handler-stack
Not implemented yet.
@end table

@item Time objects
@table @code
@item time?
@itemx current-time
@itemx seconds+ time
@xref{Time}.
@end table

@item Threads
@table @code
@item &thread
@itemx make-thread-condition
@itemx thread-condition?
@itemx &uncaught-exception
@itemx make-uncaught-exception
@itemx uncaught-exception-condition?
@itemx uncaught-exception-condition-reason
@itemx &thread-already-terminated
@itemx make-thread-already-terminated-condition
@itemx thread-already-terminated-condition?
@itemx &thread-timeout
@itemx make-thread-timeout-condition
@itemx thread-timeout-condition?
@itemx &thread-abandoned-mutex
@itemx make-thread-abandoned-mutex-condition
@itemx thread-abandoned-mutex-condition?
@itemx &concurrent-modification
@itemx make-concurrent-modification-violation
@itemx concurrent-modification-violation?
@xref{Thread exceptions}.
@item make-thread
@itemx thread?
@itemx current-thread
@itemx thread-start!
@itemx thread-yield!
@itemx thread-sleep!
@itemx thread-terminate!
@itemx thread-schedule-terminate!
@itemx thread-join!
@xref{Threads}.

@item make-mutex
@itemx mutex?
@itemx mutex-state
@itemx mutex-lock!
@itemx mutex-unlock!
@xref{Mutex}.

@item make-condition-variable
@itemx condition-variable?
@itemx condition-variable-signal!
@itemx condition-variable-broadcast!
@xref{Condition variable}.

@item make-thread-local
@itemx thread-local?
@itemx tlref
@itemx tlset!
@xref{Thread local storage}.

@item current-interrupt-level
@itemx disable-interrupts!
@itemx enable-interrupts!
@itemx with-interrupts-disabled
@itemx with-interrupts-enabled
@itemx thread-interrupt!
Not implemented yet.
@end table
@end table



@c ----------------------------------------------------------------------
@node Optional arguments, Composing comparators, Control features, Library modules - SRFIs
@section @code{srfi.227} - Optional arguments
@c NODE 省略可能引数, @code{srfi.227} - 省略可能引数

@deftp {Module} srfi.227
@deftpx {Module} srfi.227.definitions
@mdindex srfi.227
@mdindex srfi.227.definitions
@c EN
This srfi provies macros to specify optional arguments portably.
Gauche supports optional arguments in extended formals
(@pxref{Making procedures}), but it is not portable.
@c JP
このsrfiは、ポータブルに省略可能引数を書く方法を提供します。
Gaucheは拡張引数構文で省略可能引数を指定できますが、ポータブルではありません
(@ref{Making procedures}参照)。
@c COMMON

@c EN
The main module, @code{srfi.227}, exports macros
@code{opt-lambda}, @code{opt*-lambda}, @code{let-optionals}, and
@code{let-optionals*}.  Note that this @code{let-optionals*} has different
semantics from Gauche's built-in @code{let-optionals*}.
@c JP
モジュール@var{srfi.227}はマクロ
@code{opt-lambda}、@code{opt*-lambda}、@code{let-optionals}、
@code{let-optionals*}をexportします。この@code{let-optionals*}は
Gauche組み込みの@code{let-optionals*}と異なることに注意してください。
@c COMMON

@c EN
The submodule @code{srfi.227.definitions} exports two more
macros, @code{define-optionals} and @code{define-optionals*}.
@c JP
サブモジュール@code{srfi.227.definitions}はさらに2つのマクロ、
@code{define-optionals}と@code{define-optionals*}をexportします。
@c COMMON
@end deftp

@defmac opt-labmda opt-formals body @dots{}
@defmacx opt*-lambda opt-formals body @dots{}
[SRFI-227]
@c MOD srfi.227
@c EN
Evaliates to a procedure, similar to @code{lambda}.
@c JP
@code{lambda}と同じように、手続きへと評価されます。
@c COMMON

@c EN
The @var{opt-formals} is either one of the following form:
@c JP
@var{opt-formals}は以下のいずれかの形式です。
@c COMMON
@example
(@var{var} @dots{} (@var{optvar} @var{init}) @dots{})
(@var{var} @dots{} (@var{optvar} @var{init}) @dots{} . @var{restvar})
@end example

@c EN
@var{Var}, @var{optvar}, and @var{restvar} are identifiers.
Each @var{init} is an expression.
@c JP
@var{var}、@code{optvar}、@code{restvar}は識別子で、
@var{init}は式です。
@c COMMON

@c EN
@var{Var} @dots{} are required arguments.  @var{Optvar} @dots{} are
optional arguments, and when no corresponding parameter is provided,
@var{init} is evaluated and used as the value of the argument.
@c JP
@var{var} @dots{}は必須引数を指定します。
@var{optvar} @dots{}は省略可能引数で、与えられた実引数が足りない場合は
対応する@var{init}が評価されその値に束縛されます。
@c COMMON

@c EN
In the first form, giving exessive arguments throws an error; in the
second form, excessive arguments are bound to @var{restvar} as a list.
@c JP
最初の形式では、余分な引数が与えられるとエラーが投げられます。
二番目の形式では、余分な引数はリストとして@var{restvar}に束縛されます。
@c COMMON

@c EN
The scope of @var{init} differs between @code{opt-lambda} and
@var{opt-lambda*}.  With @code{opt-lambda}, @var{init}s are evaluated
in the scope where @code{opt-lambda} is placed.  With @var{opt*-lambda},
the scope of @var{init}s also includes preceding @var{var}s and @var{optvar}s.
@c JP
@var{init}のスコープは@code{opt-lambda}と@code{opt*-lambda}で異なります。
@code{opt-lambda}では、@var{init}は@code{opt-lambda}が置かれた環境で評価されます。
@code{opt*-lambda}ではそれに加え、先行する@var{var}と@var{optvar}も
スコープに含まれます。
@c COMMON

@example
(let ((x 1))
  ((opt-lambda (x (y (+ x 1))) (list x y)) 10))
 @result{} (10 2)

(let ((x 1))
  ((opt*-lambda (x (y (+ x 1))) (list x y)) 10))
 @result{} (10 11)
@end example

@c EN
Note: @code{(opt*-lambda (v @dots{} (w init) @dots{}) body @dots{}} is the same
as Gauche's
@code{(lambda (v @dots{} :optional (w init) @dots{}) body @dots{})}.
@c JP
@code{(opt*-lambda (v @dots{} (w init) @dots{}) body @dots{}}は
Gaucheの拡張引数を使った
@code{(lambda (v @dots{} :optional (w init) @dots{}) body @dots{})}
と同じです。
@c COMMON
@end defmac

@defmac let-optionals expr opt-formals body @dots{}
@defmacx let-optionals* expr opt-formals body @dots{}
[SRFI-227]
@c MOD srfi.227
@c EN
Syntax sugar to decompose the result of @var{expr} using @var{opt-formals}:
@c JP
@var{opt-formal}を使って@var{expr}の結果を分解する糖衣構文です。
@c COMMON

@example
(let-optionals expr opt-formals body @dots{})
 @equiv{} ((opt-lambda opt-formals body @dots{}) expr)

(let-optionals* expr opt-formals body @dots{})
 @equiv{} ((opt*-lambda opt-formals body @dots{}) expr)
@end example

@c EN
Note: Gauche has built-in @code{let-optionals*}, which is different
from this srfi.  Gauche's doesn't allow requried parameters.
@xref{Making procedures}, for the details.
@c JP
註: Gaucheの組み込みの@code{let-optionals*}は、
必須パラメータを取らないという点でこのsrfiと異なります。
@ref{Making procedures}参照。
@c COMMON
@end defmac

@defmac define-optionals (name . opt-formals) body @dots{}
@defmacx define-optionals* (name . opt-formals) body @dots{}
[SRFI-227]
@c MOD srfi.227.definitions
@c EN
These two forms are provided in a submodule @code{srfi.227.definitions}.
@c JP
これら2つのフォームはサブモジュール@code{srfi.227.definitions}で提供されます。
@c COMMON

@example
(define-optionals (name . opt-formals) body @dots{})
 @equiv{} (define name (opt-lambda opt-formals body @dots{}))

(define-optionals* (name . opt-formals) body @dots{})
 @equiv{} (define name (opt*-lambda opt-formals body @dots{}))
@end example
@end defmac


@c ----------------------------------------------------------------------
@node Composing comparators, Tagged procedures, Optional arguments, Library modules - SRFIs
@section @code{srfi.228} - Composing comparators
@c NODE 比較器の合成, @code{srfi.228} - 比較器の合成

@deftp {Module} srfi.228
@mdindex srfi.228
@c EN
This module provides a few utility procedures to compose
comparators for typical aggregates.  For the details
of comparators, @pxref{Basic comparators}, and @pxref{Comparators}.
@c JP
このモジュールは、典型的な集合型のために比較器を合成するいくつかのユーティリティを
提供します。比較器については
@ref{Basic comparators}と@ref{Comparators}を参照してください。
@c COMMON
@end deftp

@defun make-wrapper-comparator type-test unwrap contents-comparator
[SRFI-228]
@c MOD srfi.228
@c EN
Creates a comparator for objects that wraps other entities.
@c JP
何らかの要素をくるむオブジェクトのための比較器を作ります。
@c COMMON

@c EN
First it tests the given object with @var{type-test}; then, it calls
@var{unwrap} on it to extract contents, and use @code{contents-comparator}
on the exracted contents.
@c JP
作られた比較器は、@var{type-test}で適合性を調べ、適合するなら
@var{unwrap}をオブジェクトに適用して、得られた結果について
@code{contents-comparator}を使って比較します。
@c COMMON

@c EN
For example, suppose you want to deal with a string inside a box.
You can create a comparator for such structs (@code{strbox-comparator})
as follows:
@c JP
例えば、文字列をboxに入れたものを扱うとしましょう。
そういうオブジェクトのための比較器@code{strbox-comparator}は、次のとおり定義できます。
@c COMMON

@example
(define (strbox? obj)
  (and (box? obj) (string? (unbox obj))))

(define strbox-comparator
  (make-wrapper-comparator strbox? unbox string-comparator))
@end example

@c EN
Then you can compare to strboxes with @code{<?} etc., or make
a hashtable or treemap by passing @code{strbox-comparator} as a comparator.
@c JP
こう定義しておけば、boxに入った文字列を@code{<?}等で比較したり、
ハッシュテーブルやツリーマップに格納したりすることができます。
@c COMMON
@end defun

@defun make-product-comparator comparator @dots{}
[SRFI-228]
@c MOD srfi.228
@c EN
Creates a comparator for objects of a @emph{common} type of the types
dealt with given comparators.  Combined with @code{make-wrapper-comparator},
this can also be used to create a comparator for the product types.
@c JP
与えられた比較器が扱う型に共通する型のための比較器を作ります。
@code{make-wrapper-comparator}と合わせると、直積型の比較器を簡単に作れます。
@c COMMON

@c EN
The type predicate of the resulting comparator is satisfied iff
the object satisfies every type predicates of @var{comparator}s.
@c JP
作られる比較器の型検査述語は、与えられた@var{comparator}の型検査述語全てを満たす時に
満たされるものです。
@c COMMON

@c EN
The equality predicate is satisfied iff two objects are equal
to each other according to all @var{comparator}s.
@c JP
作られる比較器の等価判定述語は、全ての@var{comparator}の等価判定を満たす時に
満たされます。
@c COMMON

@c EN
The ordering predicate is defined only if all the @var{comparator}s
have ordering predicate.   Two objects can be ordered by applying
ordering predicate of @var{comparator}s left to right.  If an ordering
predicate returns true, the ordering predicate of the product comparator
immediately returns true.  Otherwise, two objects are checked with
the equality predicate of the current comparator.  If two objects are
not equal, or no more comparators are left, then the ordering predicate
of the product comparator returns @code{#f}.  Otherwise, the next
comparator is tried.
@c JP
順序判定述語は、@var{comparator}全てが順序判定述語を持つ場合に限り定義され、
次のとおり動作します。二つのオブジェクトは、@var{comparator}の左から順に、
その順序判定述語に渡されます。最初の@var{comparator}の順序判定述語が真を返したら
全体の順序判定述語は直ちに真を返します。そうでなければ、最初の@var{comparator}の
等価判定述語が呼ばれ、それが偽を返したら全体の順序判定述語は直ちに偽を返します。
最初の@var{comparator}の等価判定述語が真であれば、次の@var{comparator}に進み、
同様に繰り返します。次の@var{comparator}が無くなれば偽が返されます。
@c COMMON

@c EN
The hash function is defined only if all the @var{comparator}s
have hash functions.  Each hash function is called, and the
results are combined to produce the final hash value.
@c JP
ハッシュ関数は@var{comparator}全てがハッシュ関数を持つ場合に限り定義されます。
それぞれの@var{comparator}のハッシュ関数がオブジェクトに対して呼ばれ、
そのハッシュ値を組み合わせたものが全体のハッシュ値となります。
@c COMMON

@c EN
The following example defines a comparator of a record type
based on the comparators of the fields.
@c JP
次の例は、レコード型の比較器を、フィールドの比較器から合成します。
@c COMMON

@example
(define-record-type <member> make-member member?
  (name member-name)  ; string
  (age member-age))   ; integer

(define member-comparator
  (make-product-comparator
   (make-wrapper-comparator member? member-name string-comparator)
   (make-wrapper-comparator member? member-age integer-comparator)))
@end example
@end defun

@defun make-sum-comparator comparator @dots{}
[SRFI-228]
@c MOD srfi.228
@c EN
Creates a comparator for objects of a @emph{union} type of the types
dealt with the given comparators.
@c JP
与えられた比較器が扱う型のユニオン型を扱える比較器を作ります。
@c COMMON

@c EN
The type predicate of the created comparator
is satisfied if the given object satisfies a type
predicate of any one of the given comparators.  The leftmost comparator
that the object satisfies is called the @emph{relevant comparator}.
@c JP
返される型検査述語は、与えられたオブジェクトが@var{comparator} @dots{}の
型検査述語のいすれかを満たせば真を返します。
最初に型検査述語が満たされた比較器を「妥当な比較器」と呼びます。
@c COMMON

@c EN
The equality predicate is satisfied if the two objects share the
relevant comparator and are equal to each other with regard to the
comparator.
@c JP
等価判定述語は、二つの引数の妥当な比較器が等しく、
その比較器の等価判定述語が真を返した場合にのみ真となります。
@c COMMON

@c EN
The ordering predicate works as follows: First, relevant comparators
of two given objects are picked.  If the relevant comparator of
the first object is to the left of the relevant comparator of
the second, the ordering predicate of the sum comparator is satisfied.
If the first one is to the right of the second one, the ordering predicate
is unsatisfied.  If two objects share the relevant comparator,
they are oreder by the ordering predicate of the relevant comparator.
@c JP
順序判定述語は次のとおり動作します。
まず、各引数の妥当な比較器が選ばれます。最初の引数の妥当な比較器が
二番目の引数の妥当な比較器より左にあれば、順序判定述語は満たされます
(つまり最初の引数の方が「小さい」とみなされます)。
最初の引数の妥当な比較器が二番目のそれより右にあれば、順序判定述語は満たされません。
二つの引数の妥当な比較器が等しければ、その順序判定述語の結果がそのまま返されます。
@c COMMON

@c EN
The hash function returns the hash value computed by the relevant
comparator of the given object.
@c JP
ハッシュ関数は、引数の妥当な比較器のハッシュ関数をそのまま使います。
@c COMMON
@end defun

@defvar comparator-one
[SRFI-228]
@c MOD srfi.228
@c EN
This is a comparator that works as a unit element for the product
comparator.  It accepts any object and all values are equal; that is,
its type predcate and its equality predicate always return @code{#t},
its ordering predicate always returns @code{#f}, and its hash
function always returns 0.
@c JP
これは直積型の比較器の単位元として動作する比較器です。
いかなるオブジェクトも許容し、全てのオブジェクトを等価とみなします。
つまり、その型検査述語と等価判定述語は常に@code{#t}を返します。
順序判定述語は常に@code{#f}を返し、ハッシュ関数は常に0を返します。
@c COMMON
@end defvar

@defvar comparator-zero
[SRFI-228]
@c MOD srfi.228
@c EN
This is a comparator that works as a unit element for the sum
comparator.  Its domain is empty; that is, its type predicate always
returns @code{#f}, and it is an error to invoke its equality predicate,
ordering predicate and hash function.
@c JP
これはユニオン型の比較器の単位元として動作する比較器です。
この比較器が対象とする定義域は空集合です。すなわち、型検査述語は常に@code{#f}を返します。
等価判定述語、順序判定述語、およびハッシュ関数はエラーを投げます。
@c COMMON
@end defvar

@c ----------------------------------------------------------------------
@node Tagged procedures, Atomic operations, Composing comparators, Library modules - SRFIs
@section @code{srfi.229} - Tagged procedures
@c NODE 手続きタグ, @code{srfi.229} - 手続きタグ

@deftp {Module} srfi.229
@mdindex srfi.229
@c EN
This srfi allows to attach auxiliary information (tag) to a procedure.
A tag can be attached when a procedure is created, and later retrieved.
A procedure itself should be considered as an immutable entity,
so you can't attach or remove a tag to an existing procedure
(although you can attach a mutable structure as a tag and mutate
it later; much like the closed environment can be mutated).
@c JP
このsrfiは、手続きに補助的な情報(タグ)を付加できるようにするものです。
タグは手続きを作るときに与えることができて、後で取り出すことができます。
手続きは変更不可なオブジェクトであり、従って既にある手続きにタグを追加したり
取り除いたりすることはできません。(ただ、変更可能な構造をタグとして付加して、
その構造を後で変更することはできます。クロージャに閉じ込まれた環境を
変更できるのと同じです)。
@c COMMON
@end deftp

@defmac lambda/tag expr formals body @dots{}
[SRFI-229]
@c MOD srfi.229
@c EN
Evaluates @var{expr}, and returns a procedure that is
the same as @code{(lambda formals body @dots{})} except that
the value of @var{expr} is attached as a tag to the resulting
procedure.   The tag can be retrieved with @code{procedure-tag}.
@c JP
@var{expr}を評価し、その値をタグとして持つ手続き@code{(lambda formals body @dots{})}を
返します。タグは@code{procedure-tag}で取り出すことができます。
@c COMMON
@end defmac

@defmac case-lambda/tag expr clause @dots{}
[SRFI-229]
@c MOD srfi.229
@c EN
Each @var{clause} is @code{(formals body @dots{})}, much like
the ordinary @code{case-lambda}.

First evaluates @var{expr}, and returns a procedure that is
the same as @code{(case-lambda clause @dots{})}, excpet that
the value of @var{expr} is attached as a tag to the resulting
procedure.   The tag can be retrieved with @code{procedure-tag}.
@c JP
各@var{clause}は、通常の@code{case-lambda}と同様に
@code{(formals body @dots{})}という形式です。

まず@var{expr}を評価し、その値をタグとして持つ、
@code{(case-lambda clause @dots{})}で作られる手続きを返します。
タグは@code{procedure-tag}で取り出すことができます。
@c COMMON
@end defmac

@defun procedure/tag? obj
[SRFI-229]
@c MOD srfi.229
@c EN
Returns @code{#t} iff @var{obj} is a procedure and has a tag.
@c JP
@var{obj}が手続きであり、タグを持っていたら@code{#t}を返します。
@c COMMON
@end defun

@defun procedure-tag proc
[SRFI-229]
@c MOD srfi.229
@c EN
Returns a tag of @var{proc}, which must be a tagged procedure.
If @var{proc} is not a procedure or not tagged, an error
is signaled.
@c JP
@var{proc}がタグ付き手続きであればそのタグを返します。
@var{proc}がタグ付き手続きでなければエラーが投げられます。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Atomic operations, Flexible curried procedures, Tagged procedures, Library modules - SRFIs
@section @code{srfi.230} - Atomic operations
@c NODE アトミックな操作, @code{srfi.230} - アトミックな操作

@deftp {Module} srfi.230
@mdindex srfi.230
This srfi defines a set of data types and operations that perform
certain dereference and modification operations atomically.
The interface is similar to C++'s atomic operation library.

The srfi also defines sevaral relaxed memory order constraints.
In the current Gauche operations, those operation involves VM-level
procedure calls and all operations are done with sequentially consistent
order, no matter what @var{memory-order} argument is.
Other Scheme implementations that inline-compiles these
operations may emit more efficient code with relaxed memory orders.

Gauche's implementation does utilize lock-free atomic operations,
so they may still faster than using mutexes (@pxref{Mutex}).
@end deftp

@subheading Memory order

@defmac memory-order symbol
[SRFI-230]
@c MOD srfi.230
If @var{symbol} must be one of the following symbols specifying
memory order: @code{relaxed}, @code{aquire}, @code{release},
@code{aquire-release}, or @code{sequentially-consistent},
it is returned as is.  Otherwise, a syntax error is thrown.
This can be used instaed of @code{quote} to statically check
the validity of the symbol.

In Gauche's current implementation, all atomic operations are
done in @code{sequentially-consistent}, no matter what memory order
you specify.  Portable code may use more relaxed order and expect
it runs more efficiently on other implementations.
@end defmac

@defun memory-order? obj
[SRFI-230]
@c MOD srfi.230
Returns @code{#t} if @var{obj} is one of the valid symbols as
memory order, @code{#f} otherwise.
@end defun

@subheading Atomic flag

An atomic flag is a storage that holds a boolean value.
The initial value is @code{#f}.
Referencing the flag can only be done with
@code{atomic-flag-test-and-set!}, which turns the value to @code{#t}.

@defun make-atomic-flag
[SRFI-230]
@c MOD srfi.230
Returns a newly created atomic flag.  Its value is @code{#f}.
@end defun

@defun atomic-flag? obj
[SRFI-230]
@c MOD srfi.230
Returns @code{#t} if @code{obj} is an atomic flag,
@code{#f} otherwise.
@end defun

@defun atomic-flag-test-and-set! flag :optional memory-order
[SRFI-230]
@c MOD srfi.230
Set @var{flag}'s value to @code{#t} and returns its previous value,
atomically.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-flag-clear! flag :optional memory-order
[SRFI-230]
@c MOD srfi.230
Reset @var{flag}'s value to @code{#f}.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@subheading Atomic box

An atomic box is a storage that holds a Scheme value.

@defun make-atomic-box val
[SRFI-230]
@c MOD srfi.230
Creates a new atomic box whose value is @var{val}.
@end defun

@defun atomic-box? obj
[SRFI-230]
@c MOD srfi.230
Returns @code{#t} if @code{obj} is an atomic box,
@code{#f} otherwise.
@end defun

@defun atomic-box-ref abox :optional memory-order
[SRFI-230]
@c MOD srfi.230
Returns the content of atomic box @var{abox}.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-box-set! abox val :optional memory-order
[SRFI-230]
@c MOD srfi.230
Sets @var{val} as the content of atomic box @var{abox},
and returns an undefined value.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-box-swap! abox val :optional memory-order
[SRFI-230]
@c MOD srfi.230
Sets @var{val} as the content of atomic box @var{abox},
and returns the previous content, atomically.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.

@example
(define b (make-atomic-box 'foo))

(atomic-box-swap! box 'bar)   @result{} foo
(atomic-box-ref box)          @result{} bar
@end example

@end defun

@defun atomic-box-compare-and-swap! abox expected desired :optional memory-order
[SRFI-230]
@c MOD srfi.230
Compares the content of atomic box @var{abox} and @var{expected}.
If both are the same (in @code{eq?} sense), sets @var{desired} as the
new value of @var{abox}.  Returns the previous content.  All operations
are done atomically.

You can know the content is altered if @code{(eq? return-value expected)}
is true.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@subheading Atomic fxbox

An atomic fxbox is a storage that can hold a fixnum.
It provides atomic fetcy-compute-store opertaions as well.

@defun make-atomic-fxbox fxval
[SRFI-230]
@c MOD srfi.230
Creates a new atomic box whose value is @var{fxval}.
@end defun

@defun atomic-fxbox? obj
[SRFI-230]
@c MOD srfi.230
Returns @code{#t} if @code{obj} is an atomic fxbox,
@code{#f} otherwise.
@end defun

@defun atomic-fxbox-ref fxbox :optional memory-order
[SRFI-230]
@c MOD srfi.230
Returns the content of atomic fxbox @var{fxbox}.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-fxbox-set! fxbox fxval :optional memory-order
[SRFI-230]
@c MOD srfi.230
Sets @var{fxval} as the content of atomic fxbox @var{fxbox},
and returns an undefined value.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-fxbox-swap! fxbox fxval :optional memory-order
[SRFI-230]
@c MOD srfi.230
Sets @var{fxval} as the content of atomic fxbox @var{fxbox},
and returns the previous content, atomically.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-fxbox-compare-and-swap! fxbox expected desired :optional memory-order
[SRFI-230]
@c MOD srfi.230
Compares the content of atomic fxbox @var{fxbox} and @var{expected}.
If both are the same (in @code{eq?} sense), sets @var{desired} as the
new value of @var{fxbox}.  Returns the previous content.  All operations
are done atomically.

You can know the content is altered if @code{(eq? return-value expected)}
is true.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-fxbox+/fetch! fxbox fxval :optional memory-order
@defunx atomic-fxbox-/fetch! fxbox fxval :optional memory-order
@defunx atomic-fxbo-and/fetch! fxbox fxval :optional memory-order
@defunx atomic-fxbo-ior/fetch! fxbox fxval :optional memory-order
@defunx atomic-fxbo-xor/fetch! fxbox fxval :optional memory-order
[SRFI-230]
@c MOD srfi.230
Retrieves the value of atomic fxbox @var{fxbox}, calculates
@code{(+ prev-val fxval)}, @code{(- prev-val fxval)},
@code{(logand prev-val fxval)}, @code{(logior prev-val fxval}),
or @code{(logxor prev-val fxval)}, respectively,
then store the result to @var{fxbox}, and returns the previous value.
The entire sequence of operations are done atomically.

This does not check the numerical overflow.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@subheading Atomic pair

An atomic pair is a storage that can hold two Scheme values,
and both can be updated at once atomically.

@defun make-atomic-pair val1 val2
[SRFI-230]
@c MOD srfi.230
Creates a new atomic pair that has two values, @var{val1} and @var{val2}.
@c MOD srfi.230

@end defun

@defun atomic-pair? obj
[SRFI-230]
@c MOD srfi.230
Returns @code{#t} if @code{obj} is an atomic pair,
@code{#f} otherwise.
@end defun

@defun atomic-pair-ref apair :optional memory-order
[SRFI-230]
@c MOD srfi.230
Atomically dereference the two values @var{apair} holds,
and returns them as the two return values.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-pair-set! apair val1 val2 :optional memory-order
[SRFI-230]
@c MOD srfi.230
Atomically stores @var{val1} and @var{val2} to an atomic pair @var{apair}.
Returns an undefined value.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-pair-swap! apair val1 val2 :optional memory-order
[SRFI-230]
@c MOD srfi.230
Atomically stores @var{val1} and @var{val2} to an atomic pair @var{apair}
and returns the previous values.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@defun atomic-pair-compare-and-swap! abox expected1 expected2 desired1 desired2 :optional memory-order
[SRFI-230]
@c MOD srfi.230
Compare two values in atomic box @var{abox} with @var{expected1} and
@var{expected2}, respectively.  If each corresponding values are
the same (in @code{eq?} sense), store @var{desired1} and @var{desired2}
to @var{abox}.  Always returns teh original values.
The whole operations are done atomically.

You can know the values are altered by comparing returned values
and expected values.

Gauche uses sequentially consistent order regardless of
the @var{memory-order} argument.
@end defun

@subheading Memory synchronization

@defun atomic-fence memory-order
[SRFI-230]
@c MOD srfi.230
Synchronize memory according to at least @var{memory-order}
constraints.  In the current version of Gauche,
regardless of @var{memory-order},
the memory is synchronized with sequentially consistent manner.
@end defun

@c ----------------------------------------------------------------------
@node Flexible curried procedures, Topological sorting, Atomic operations, Library modules - SRFIs
@section @code{srfi.232} - Flexible curried procedures
@c NODE 柔軟なカリー化された手続き, @code{srfi.232} - 柔軟なカリー化された手続き

@deftp {Module} srfi.232
@mdindex srfi.232
@c EN
This srfi provides macros to define a procedure that can accept
less than or more than the given formal parameters.  If the number of given
parameters is less than the required parameters, it becomes partial
application; a procedure that will take the remaining parameters is returned.
If the number of given parameters is more than the maximum number of
parameters, then the excessive parameters are passed to the result
of the original procedure, assuming the original procedure returns
a procedure.
@c JP
このモジュールは、定義時に指定された仮引数よりも少なかったり多かったりする実引数を取れる
手続きを定義するマクロを提供します。
このマクロで定義された手続きが、仮引数よりも少ない実引数を渡された場合は、
部分適用となり、残りの引数を受け取る手続きが返されます。
もし仮引数よりも多い実引数が渡された場合、仮引数分の実引数が手続きにまず渡され、
その戻り値(手続きであることが期待されます)に残りの実引数が渡されます。
@c COMMON

@c EN
Currying in the strict sense converts n-ary procedures to nested 1-ary
procedures:
@c JP
厳密な意味でのカリー化は、n引数の手続きをネストした1引数の手続きに変換することです。
@c COMMON

@example
(lambda (a b c) body)
  @result{} (lambda (a) (lambda (b) (lambda (c) body)))
@end example

@c EN
However, with Scheme, you need nested parentheses to give all
the parameters to it:
@c JP
Schemeでは、この方法でカリー化された手続きにすべての引数を渡そうとすると、
括弧をネストしなければなりません。
@c COMMON

@example
(((f 1) 2) 3)
@end example

@c EN
The procedure created with this srfi allows more than one parameters
to be passed at once.  The following calls to @code{f} all yield the
same result:
@c JP
これに対し、このsrfiで作られる手続きには、複数の引数をまとめて渡すことができます。
以下の例で、@code{f}の呼び出しはすべて同じ動作となります。
@c COMMON

@example
(define-curried (f a b c) body)

(f 1 2 3)
(((f 1) 2) 3)
((f 1 2) 3)
((f 1) 2 3)
@end example

@c EN
Moreover, the procedure can take more parameters than the formals,
assuming that the procedure with full parameters return a procedure
that takes extra parameters.  In other words, the following
equivalance holds:
@c JP
さらに、仮引数よりも多くの実引数を@code{f}に渡すことができます。ここで、
@code{f}は(追加の引数を取る)手続きを返すことが期待されています。
つまり、次のような等価性が成り立ちます。
@c COMMON

@example
(f 1 2 3 4 5 6) @equiv{} ((f 1 2 3) 4 5 6)
@end example
@end deftp

@defmac curried formals body @dots{}
[SRFI-232]
@c MOD srfi.232
@c EN
Returns a procedure just like @var{(lambda formals body @dots{})},
except that the returned procedure may take less or more parameters
than the specified in @var{formals}.
@c JP
@var{(lambda formals body @dots{})}と同じように手続きを作って返しますが、
作られた手続きは@var{formals}で指定されるより少なかったり多かったりする引数を
取ることができます。
@c COMMON

@c EN
If it is given with less parameters than the required ones, it works
as partial application; the result is a procedure that will accept
the remaining parameters.
@c JP
呼び出し時に渡される引数が過少な場合は、部分適用として動作し、
残りの引数を受け取る手続きが返されます。
@c COMMON

@example
(define f (curried (a b c d) (+ a b c d)))

@c EN
(f 1 2 3 4) @result{} 10        ; ordinary application
(f 1 2) @result{} #<procedure>  ; partial application, like (pa$ f 1 2)
((f 1 2) 3 4) @result{} 10      ; fulfilling the remaining argument
(((f 1 2) 3) 4) @result{} 10    ; partial application can be nested
(((f 1) 2 3) 4) @result{} 10    ; ... and can be grouped in any way
@c JP
(f 1 2 3 4) @result{} 10        ; 通常の呼び出し
(f 1 2) @result{} #<procedure>  ; 部分適用。(pa$ f 1 2)と同じ
((f 1 2) 3 4) @result{} 10      ; 残りの引数を提供
(((f 1 2) 3) 4) @result{} 10    ; 部分適用はネストでき、
(((f 1) 2 3) 4) @result{} 10    ; ... また一回の呼び出しでいくつも引数を渡せる
@c COMMON
@end example

@c EN
The procedure can accept more parameters than the ones given to
@var{formals}, even @var{formals} does not specify the ``rest'' parameter.
If @var{formals} takes the rest parameter, the excess arguments are passed
to it.  If not, the result of the procedure with required parameters
are applied over the excess arguments.
@c JP
また、@var{formals}が「残余引数」を指定していなくても、返される手続きは@var{formals}より
多くの引数を取ることができます。@var{formals}が残余引数を取る場合は、
余分な実引数は残余引数として渡されます。そうでなければ、必要な引数だけが手続きにまず
渡され、その戻り値がもう一度、残りの引数とともに呼び出されます。
@c COMMON

@example
(define f (curried (a b c) (^[x] (* x (+ a b c)))))

(f 1 2 3 4) @result{} 24  ; @equiv{} ((f 1 2 3) 4)
@end example

@c EN
If no arguments are given to the procedure,
it returls the procedure itself:
@c JP
引数が渡されなかった場合は、手続き自身が返ります。
@c COMMON

@example
(((f)) 1 2 3) @equiv{} (f 1 2 3)
@end example

@c EN
As a special case, @code{(curried () body)} and @code{(curried identifier body)}
are the same as @code{(lambda () body)} and @code{(lambda identifier body)},
respectively.
@c JP
特別な場合として、
@code{(curried () body)}および@code{(curried identifier body)}は、それぞれ
@code{(lambda () body)}および@code{(lambda identifier body)}と同じです。
@c COMMON
@end defmac

@defmac define-curried (name . formals) body @dots{}
[SRFI-232]
@c MOD srfi.232
@c EN
A shorthand of @code{(define name (curried formals body @dots{}))}.
@c JP
@code{(define name (curried formals body @dots{}))}の略記です。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node Topological sorting, Combinators (SRFI), Flexible curried procedures, Library modules - SRFIs
@section @code{srfi.234} - Topological sorting
@c NODE トポロジカルソート, @code{srfi.234} - トポロジカルソート

@deftp {Module} srfi.234
@mdindex srfi.234
@c EN
This module implements topological sort algorithm.

The SRFI is an enhancement of Gauche's @code{util.toposort} module
(@pxref{Topological sort (legacy)}).
As this SRFI is finalized, we encourage new code to use this for
richer features and portability.  Original @code{util.toposort} has
become a thin wrapper of this module.
@c JP
このモジュールはトポロジカルソートを実装しています。

このSRFIはもともとGaucheの@code{util.toposort}を拡張して作られました
(@pxref{Topological sort (legacy)})。
このSRFIがfinalizeされたので、新たなコードではこちらのSRFIを使うことを推奨します。
元の@code{util.toposort}は今ではこのSRFIの薄いラッパーになっています。
@c COMMON
@end deftp

@defun topological-sort graph :optional eq node-array
[SRFI-234]
@c MOD srfi.234
@c EN
Returns a list of node, ordered to satisfy the dependency graph
represented by @var{graph}.
@c JP
@var{graph}で表される依存関係を満たすように整列したノードのリストを返します。
@c COMMON

@c EN
@var{Graph} represents a directed acyclic graph (DAG) by a list
of connections, where each connection is the form
@example
(<node> <downstream> <downstream2> ...)
@end example
that means a node @code{<node>} is connected to other nodes
@code{<downstream>} etc.   @code{<node>} can be arbitrary
object.  Their equality is compared by a procedure @var{eq},
which is @code{equal?} by default.
@c JP
@var{graph}は有向非循環グラフ(DAG)を接続のリストで表したものです。
各接続は次の形式です。
@example
(<node> <downstream> <downstream2> ...)
@end example
これは、@code{<node>}から他のノード@code{<downstream>} @dots{}への
接続があることを示してます。@code{<node>}はどんなオブジェクトであっても構いません。
ノード同士の等しさは@var{eq}引数で比較され、そのデフォルトは@code{equal?}です。
@c COMMON

@c EN
If the graph contains cycles, @code{#f} is returned.
@c JP
グラフに循環があった場合は@code{#f}が返されます。
@c COMMON

@example
(topological-sort '((shirt tie belt)
                    (tie jacket)
                    (belt jacket)
                    (watch)
                    (pants shoes belt)
                    (undershorts pants shoes)
                    (socks shoes)))
 @result{} (socks undershorts watch shirt tie pants belt jacket shoes)
@end example

@c EN
If the optional @var{node-array} is given and not @code{#f}, it must
be a vector of nodes, and @var{graph} uses integer indices
of the nodes in place of nodes themselves.  The comparison
predicate @var{eq} is applied on the indices.  Once the nodes are
sorted, they are looked up from @var{node-array}, and a list of
nodes is returned.
@c JP
省略可能引数@var{node-array}が与えられ、それが@code{#f}でない場合、
それはノードのベクタでなければなりません。その場合、@var{graph}はノード自体ではなく
@var{node-array}へのインデックスで表現されます。
トポロジカルソートが終了したら、結果は@var{node-array}にあるノードのリストで
返されます。
@c COMMON
@end defun

@defun topological-sort/details graph :optional eq node-array
[SRFI-234]
@c MOD srfi.234
@c EN
Like @code{topological-sort}, but returns three values for
further information.  The meanings of arguments are the same
as @code{topological-sort}.

If nodes can be topologically sorted, the first return value
is a sorted list of nodes, and the second and the third values are
@code{#f}.
@c JP
@code{topological-sort}と似ていますが、より詳しい情報を3つの戻り値で返します。
引数の意味は@code{topological-sort}と同じです。

ノードがトポロジカルソート可能であれば、最初の戻り値はソートされたノードのリスト、
二番目と三番目の戻り値は@code{#f}です。
@c COMMON

@c EN
If nodes cannot be topologically sorted, the first return value
is @code{#f}, the second return value is an error message,
and the third value is a list of nodes that provides information
of at least one cycle.
@c JP
ノードがトポロジカルソート可能でない場合、最初の戻り値は@code{#f}、
二番目の戻り値はエラーメッセージ、そして三番目の戻り値は
少なくともひとつの循環についての情報を与えるノードのリストです。
@c COMMON
@end defun

@defun edgelist->graph edgelist :optional retriever
[SRFI-234]
@c MOD srfi.234
@c EN
Converts a list of edges @var{edgelist} to a graph acceptable by
@code{topolocial-sort}.  Each edge is a list of two nodes, representing
a directed edge @code{(@var{from-node} @var{to-node})}.
The returned graph is a list of
@code{(@var{from-node} @var{downstream-node} @var{downstream-node2} @dots{})}.
@c JP
エッジのリスト@var{edgelist}を、@code{topological-sort}に渡せる形式のグラフへと
変換します。各エッジは@code{(@var{from-node} @var{to-node})}の形式で、
@var{from-node}から@var{to-node}への直接の接続があることを示します。
返されるグラフは、
@code{(@var{from-node} @var{downstream-node} @var{downstream-node2} @dots{})}
を要素とするリストです。
@c COMMON

@c EN
The optional argument @var{retriever} is called
as @code{(@var{retriever} @var{from-node} @var{graph})} to get a
graph entry starting with @var{from-node}.  When omitted, @code{assoc}
is used.  If you need to compare nodes in a special way different from
@code{equal?}, you can give a customized procedure.
@c JP
省略可能引数@var{retriever}は、グラフから@var{from-node}を起点とする
エントリを抜きだす手続きで、@code{(@var{retriever} @var{from-node} @var{graph})}
のように呼ばれます。デフォルトは@code{assoc}です。
扱うグラフのノードが@code{equal?}で単純に比較できないものである場合に、
この引数に必要な機能を持つ手続きを渡すことができます。
@c COMMON

@example
(edgelist->graph '((a b) (a c) (b e) (c b)))
 @result{} ((a b c) (b e) (c b))
@end example
@end defun

@defun edgelist/inverted->graph edgelist :optional retriever
[SRFI-234]
@c MOD srfi.234
@c EN
Like @code{edgelist->graph}, but take each edge entry
as @code{(@var{to-node} @var{from-node})}.
@c JP
@code{edgelist->graph}と似ていますが、エッジリストの各エントリは
@code{(@var{to-node} @var{from-node})}と解釈されます。
@c COMMON

@example
(edgelist/inverted->graph '((a b) (a c) (b e) (a e)))
 @result{} ((b a) (c a) (e b a))
@end example
@end defun

@defun graph->edgelist graph
[SRFI-234]
@c MOD srfi.234
@c EN
Given @var{graph}, which is a list of
@code{(@var{from-node} @var{downstream-node} @var{downstream-node1} @dots{})},
returns a list of edges, each of which being
@code{(@var{from-node} @var{to-node})}.
This is an inverse operation of @code{edgelist->graph}.
@c JP
@code{(@var{from-node} @var{downstream-node} @var{downstream-node1} @dots{})}
のリストである@var{graph}を取り、
@code{(@var{from-node} @var{to-node})}のリストであるエッジリストを返します。
これは@code{edgelist->graph}の逆関数です。
@c COMMON
@end defun

@defun graph->edgelist/inverted graph
[SRFI-234]
@c MOD srfi.234
@c EN
Given @var{graph}, which is a list of
@code{(@var{from-node} @var{downstream-node} @var{downstream-node1} @dots{})},
returns a list of edges, each of which being
@code{(@var{to-node} @var{from-node})}.
This is an inverse operation of @code{edgelist/inverted->graph}.
@c JP
@code{(@var{from-node} @var{downstream-node} @var{downstream-node1} @dots{})}
のリストである@var{graph}を取り、
@code{(@var{to-node} @var{from-node})}のリストであるエッジリストを返します。
これは@code{edgelist/inverted->graph}の逆関数です。
@c COMMON
@end defun

@defun connected-components graph
[SRFI-234]
@c MOD srfi.234
@c EN
Returns a list of node lists, where each list of nodes consists of
a connected component of a directed graph @var{graph}.
The format of @var{graph} argument is the same as @code{topological-sort},
i.e. @code{((node downstream @dots{}) @dots{})}.
@c JP
有向グラフ@var{graph}から、連結成分(connected component)のノードリストのリストを返します。
@var{graph}のフォーマットは@code{topological-sort}に渡すものと同じ、
すなわち@code{((node downstream @dots{}) @dots{})}のリストです。
@c COMMON

@c EN
A connected component is a group of nodes such that from any node in the group
can reach any other nodes in the same group.
@c JP
連結成分とは、グラフ内のノードのグループで、そのグループ内のどのノードから出発しても
グループ内の他のノードに到達できるようなものです。
@c COMMON

@example
(connected-components '((1 2 3) (2 1) (3 4) (4 3)))
  @result{} ((4 3) (1 2))
@end example

@c EN
Note: The order of result list, and the order of each node group in the
list, don't matter.  Mathematically, they should be sets instead of
lists.
@c JP
註: 結果のリストの順序、また各ノードグループのリストの順序に意味はありません。
数学的には、これらはリストよりもセットであるべきものです。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Combinators (SRFI), Codesets, Topological sorting, Library modules - SRFIs
@section @code{srfi.235} - Combinators (SRFI)
@c NODE コンビネータ (SRFI), @code{srfi.235} - コンビネータ (SRFI)

@deftp {Module} srfi.235
@mdindex srfi.235
@c EN
This srfi provides combinator utilities.  Gauche provides some frequently-used
combinators built-in.  This module augments it.
@c JP
このSRFIはコンビネータのユーティリティを提供します。
Gaucheは組み込みでよく使われるコンビネータを持っていますが、このSRFIはそれを補強します。
@c COMMON

@c EN
The following procedures are built-in; @pxref{Combinators}, for the details.
@c JP
以下の手続きは組み込みです。詳しくは@ref{Combinators}を参照してください。
@c COMMON

@example
constantly  complement  flip  swap  boolean
@end example
@end deftp

@c EN
@subheading Combinator utilities
@c JP
@subheading コンビネータユーティリティ
@c COMMON

@c EN
Procedures that takes procedure(s) and returns a procedure.
@c JP
手続きを取って手続きを返す手続きです。
@c COMMON

@defun on-left proc
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a two argument procedure, which ignores its right argument
and calls @var{proc} with the left argument.
@c JP
2つの引数を取る手続きを返します。その手続きが呼ばれると、右側の引数を無視して
左側の引数を@var{proc}に渡します。
@c COMMON

@example
((on-left car) '(a b) '(c d)) @result{} a
@end example
@end defun

@defun on-right proc
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a two argument procedure, which ignores its left argument
and calls @var{proc} with the right argument.
@c JP
2つの引数を取る手続きを返します。その手続きが呼ばれると、左側の引数を無視して
右側の引数を@var{proc}に渡します。
@c COMMON

@example
((on-right car) '(a b) '(c d)) @result{} c
@end example
@end defun

@defun conjoin pred @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure taking any number of arguments and that behaves
as follows: For each argument, calls @var{pred} @dots{} left to right;
if any of @var{pred} returns @code{#f}, stop and immediately returns
@code{#f}.  If all predicates returns a true value for all arguments,
returns the last result.  If no @var{pred}s are given, or no arguments are given,
returns @code{#t}.
@c JP
任意個の引数を取る、次の動作をする関数を返します。
各引数に対し、@var{pred} @dots{}を左から順に適用します。@var{pred}が@code{#f}を
返したらただちに@code{#f}を返します。全ての引数に対し、全ての@var{pred}が真の値を
返したら、最後の評価値を返します。@var{pred}がゼロ個の場合、もしくは返された関数が
引数無しで呼び出された場合は@code{#t}を返します。
@c COMMON

@example
((conjoin char? digit->integer) #\1 #\2 #\3) @result{} 3
((conjoin char? digit->integer) #\1 #\a #\3) @result{} #f
@end example

@end defun

@defun disjoin pred @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure taking any number of arguments and that behaves
as follows: For each argument, calls @var{pred} @dots{} left to right;
if any of @var{pred} returns a true value, stop and immediately returns
that value.  If all predicates returns @code{#f} for all arguments,
returns @code{#f}.  If no @var{pred}s are given, or no arguments are given,
returns @code{#f}.
@c JP
任意個の引数を取る、次の動作をする関数を返します。
各引数に対し、@var{pred} @dots{}を左から順に適用します。@var{pred}が真の値を
返したらただちにその値を返します。全ての引数に対し、全ての@var{pred}が@code{#f}を
返したら、@code{#f}を返します。@var{pred}がゼロ個の場合、もしくは返された関数が
引数無しで呼び出された場合は@code{#f}を返します。
@c COMMON

@example
((disjoin integer? char?) 'a 'b 'c) @result{} #f
((disjoin integer? char?) #\a 'b 'c) @result{} #t
@end example

@end defun

@defun each-of proc @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure that works, when applied to arguments, applies
each @var{proc} on the arguments in turn.  The result of
@var{proc}s are discarded.
@c JP
手続きを返します。返された手続きは、適用された際に、
各@var{proc}を順に呼び出します。@var{proc}の結果は捨てられます。
@c COMMON

@example
(define (f x y) (print (+ x y)))
(define (g x y) (print (* x y)))

((each-of f g) 2 7)
  @result{} #<undef>; @r{prints} 9 @r{and} 14
@end example
@end defun

@defun all-of pred
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure that takes one argument, a list.
The returned procedure tries to apply @var{pred} to each element
of @var{list} in turn.
If @var{pred} returns @var{#f}, immediately returns @var{#f}.  Otherwise,
returns the last result of @var{pred}. If the returned procedure
is applied to an empty list, @code{#t} is returned.

The following equivalence holds:
@c JP
リストをひとつ取る手続きを返します。
返された手続きは、リストの要素に順に@var{pred}を適用してゆきます。
それが@code{#f}を返したらそこで適用を打ち切り@code{#f}を返します。
そうでなければ最後の@var{pred}の適用結果を返します。
空リストに適用された場合は@code{#t}を返します。

次の等価性が成り立ちます:
@c COMMON
@example
((all-of pred) list) @equiv{} (every pred list)
@end example
@end defun

@defun any-of pred
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure that takes one argument, a list.
The returned procedure applies @var{pred} to each element
of @var{list} in turn.
If @var{pred} returns a true value, immediately returns it.  Otherwise,
returns @code{#f}.   If the returned procedure
is applied to an empty list, @code{#f} is returned.

The following equivalence holds:
@c JP
リストをひとつ取る手続きを返します。
返された手続きは、リストの要素に順に@var{pred}を適用してゆきます。
それが真の値を返したらそこで適用を打ち切りその値を返します。
そうでなければ@code{#f}を返します
空リストに適用された場合は@code{#f}を返します。

次の等価性が成り立ちます:
@c COMMON
@example
((any-of pred) list) @equiv{} (any pred list)
@end example
@end defun

@defun on reducer mapper
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure such that @code{(apply (on reducer mapper) args)}
works as if @code{(apply reducer (map mapper args))}.
@c JP
@code{(apply (on reducer mapper) args)}が
@code{(apply reducer (map mapper args))}と同じ動作になるような手続きを返します。
@c COMMON

@example
(define square-sum (on + square))

(square-sum 1 2 3 4 5) @result{} 55
@end example
@end defun

@defun left-section proc arg @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure such that, when applied to more args, calls @var{proc}
with @var{arg} @dots{} and the given args.  In other words,
returns a specialized procedure with the left argument(s) are given
as @var{arg} @dots{}.

In Gauche, this is the same as @code{(pa$ arg @dots{})} (@pxref{Combinators}).
@c JP
手続きを返します。その手続きを引数@var{x} @dots{}で呼び出すことは、
@var{(@var{proc} @var{arg} @dots{} @var{x} @dots{})} と同じ効果をもたらします。
言い換えれば、右側の引数を@var{arg} @dots{}で固定した手続きを返します。

Gaucheではこれは@code{(pa$ arg @dots{})}と同じです(@ref{Combinators}参照)。
@c COMMON

@example
((left-section list 'a 'b 'c) 'd 'e 'f)
 @result{} (a b c d e f)
@end example
@end defun

@defun right-section proc arg @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure such that, when applied to more args, calls @var{proc}
with the newly given args concatenated with
@code{(reverse (list @var{arg} @dots{})}).
@c JP
手続きを返します。その手続きを引数@var{x} @dots{}で呼び出すことは、
@code{(apply @var{proc} @var{x} @dots{} (reverse (list @var{arg} @dots{})))}
と同じ効果をもたらします。
@c COMMON

@example
((right-section list 'a 'b 'c) 'd 'e 'f)
 @result{} (d e f c b a)
@end example

@c EN
The reason that @var{arg} @dots{} is reversed is because of
this invariance:
@c JP
@var{arg} @dots{}を逆順にするのは次の不変条件を満たすためです。
@c COMMON

@example
(right-section proc arg arg1 @dots{})
 @equiv{} (right-section (right-section proc arg) arg1 @dots{})
@end example
@end defun

@defun apply-chain proc proc2 @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Returns a procedure such that it applies the last procedure to the
given arguments, then applies the previous procedure on the
returned value(s), and so on.  Returns the result(s) of @var{proc}.
@c JP
手続きを返します。その手続きに引数を渡すと、
まず最後の@var{proc}がその引数で呼ばれ、
その戻り値(複数可)を引数としてその手前の@var{proc}が呼ばれ…という具合に
進み、先頭の@var{proc}の戻り値が手続きの戻り値となります。
@c COMMON

@example
((apply-chain car cdr) '(a b c d)) @result{} b
((apply-chain list div-and-mod) 10 3) @result{} (3 1)
@end example

@c EN
@xref{Pipeline operators}, for another way to chain procedure calls.
@c JP
手続き呼び出しをチェインする別のやり方として、
@ref{Pipeline operators}があります。
@c COMMON
@end defun

@defun arguments-drop proc n
@defunx arguments-drop-right proc n
@defunx arguments-take proc n
@defunx arguments-take-right proc n
[SRFI-235]
@c MOD srfi.235
Returns a procedure such that @var{proc} is applied on the argument
list after taking/dropping @var{n} arguments.  That is,
@code{(arguments-drop proc n)} is
@code{(^ args (apply proc (drop args n)))}, and so on.

@example
((arguments-drop list 2) 'a 'b 'c 'd 'e)       @result{} (c d e)
((arguments-drop-right list 2) 'a 'b 'c 'd 'e) @result{} (a b c)
((arguments-take list 2) 'a 'b 'c 'd 'e)       @result{} (a b)
((arguments-take-right list 2) 'a 'b 'c 'd 'e) @result{} (d e)
@end example
@end defun

@defun group-by key-proc :optional equal
[SRFI-235]
@c MOD srfi.235
Returns a procedure that takes one list argument.  It applies
@var{key-proc} to each element of the list to get keys, and then
elements with the same key are grouped into a fresh list, and
returns list of such groups.
The keys are compared with @var{equal}, which defaults to @code{equal?}.
Within each group, elements that appears left in the original list
also appears on the left.

@code{((group-by key-proc eq-proc) lis)} works like
@code{(group-collection lis :key key-proc :test eq-proc)}, except
that @code{group-collection} can take any collection
(@pxref{Selection and searching in collection}).

@example
((group-by (cut string-ref <> 0) char-ci=?)
 '("apricot" "Banana" "Apple" "blueberry"))
 @result{} (("apricot" "Apple") ("Banana" "blueberry"))
@end example
@end defun

@c EN
@subheading Syntax-like procedures
@c JP
@subheading 構文に対応する手続き
@c COMMON

@defun begin-procedure thunk @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Calls @var{thunk} @dots{} from left to right.  Discats their results
except the last one(s), which will be the result(s) of this procedure.
@c JP
@var{thunk} @dots{}を左から順に呼び出します。最後の@var{thunk}の呼び出し
以外の結果は捨てられます。最後の@var{thunk}の呼び出し結果が返されます。
@c COMMON

@c EN
If no @var{thunk}s are given, returns @code{#<undef>}.
@c JP
@var{thunk}がひとつも与えられなかった場合は@code{#<undef>}が返されます。
@c COMMON
@end defun

@defun if-procedure value then-thunk else-thunk
[SRFI-235]
@c MOD srfi.235
@c EN
If @var{value} is true, calls @var{then-thunk} and returns its
result(s).  Otherwise, calls @var{else-thunk} and returns its result(s).
@c JP
@var{value}が真なら@var{then-thunk}を呼び、その結果を返します。
そうでなければ@var{else-thunk}を呼び、その結果を返します。
@c COMMON
@end defun

@defun when-procedure value thunk @dots{}
@defunx unless-procedure value thunk @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
If @var{value} evaluates to true/false, calls each @var{thunk} in turn
and returns an undefined value, respectively.
Otherwise, returns imediately.
@c JP
@var{value}が真または偽の値に評価されたら、
各@var{thunk}を順に呼び出して、未定義値を返します。
そうでなければ直ちに返ります。
@c COMMON
@end defun

@defun value-procedure value then-proc else-thunk
[SRFI-235]
@c MOD srfi.235
@c EN
If @var{value} evaluates to true, apply @var{then-proc} on it and returns
its result(s).  Otherwise, call @var{else-thunk} and returns
its result(s).
@c JP
@var{value}が真の値に評価されたら、
その値を引数に@var{then-proc}を呼び出しその戻り値を返します。
そうでなければ、@var{else-thunk}を引数なしで呼び出しその戻り値を返します。
@c COMMON
@end defun

@defun case-procedure value thunk-alist :optional else-thunk
[SRFI-235]
@c MOD srfi.235
@c EN
The @var{thunk-alist} argument is a list of pairs of a value and
a thunk.  First, @var{value} is evaluated, then the result
is searched from the cars of @var{thunk-alist}, using @code{eqv?}.
If there's a matching entry, its thunk is called and its result(s) is/are
returned.  If there's no matching entry, @var{else-thunk} is invoked
if present and its result(s) is/are returned.
If there's neither @var{else-thunk}, an undefined value is returned.
@c JP
@var{thunk-alist}引数は、値とサンクのペアのリストです。
まず@var{value}が評価され、その値が@var{thunk-alist}中のペアのcarの値と順に@var{eqv?}
で比較されます。一致するエントリが見つかったら、そのペアのcdrにあるサンクが呼ばれ、
その結果が戻り値となります。一致するエントリが無い場合、
@var{else-thunk}が与えられていればそれが呼ばれてその結果が戻り値となり、
与えられていなければ未定義値が返されます。
@c COMMON
@end defun

@defun and-procedure thunk @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Calls @var{thunk} @dots{} left to right, until it yields
@code{#f}, and returns @code{#f}.  If all @var{thunk}s yields
true value, returns the result of the last @code{thunk}.
If no @var{thunk}s are given, returns @code{#t}.
@c JP
@var{thunk} @dots{}を左から順に呼んでいきます。@code{#f}を返すサンクがあれば
そこで評価を打ち切り@code{#f}を返します。最後のサンクまでどれも@code{#f}を返さなければ、
最後のサンクの結果を戻り値とします。@var{thunk}がひとつも与えられなかった場合は
@code{#t}を返します。
@c COMMON
@end defun

@defun eager-and-procedure thunk @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Calls all @var{thunk}s, then checks their results.  If any
of the result is @code{#f}, returns @code{#f}.
Otherwise, returns the last result of @var{thunk}.
If no @var{thunk}s are given, returns @code{#t}.
@c JP
@var{thunk} @dots{}をまず全て呼び出し、それから結果を調べます。
どれかひとつでも@code{#f}があったら@code{#f}を返します。
そうでなければ、最後の@var{thunk}の結果を返します。
@var{thunk}がひとつも与えられなかった場合は@code{#t}を返します。
@c COMMON
@end defun

@defun or-procedure thunk @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Calls @var{thunk} @dots{} left to right, until it yields
a true value, and returns that value.  If all @var{thunk}s yields
@code{#f}, returns @code{#f}.  If no @var{thunk}s are given,
returns @code{#t}.
@c JP
@var{thunk} @dots{}を左から順に呼んでいきます。真の値を返すサンクがあれば
そこで評価を打ち切りその値を返します。最後のサンクまでどれも真の値を返さなければ
@code{#f}を返します。@var{thunk}がひとつも与えられなかった場合は
@code{#t}を返します。
@c COMMON
@end defun

@defun eager-or-procedure thunk @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Calls all @var{thunk}s, then checks their results from left to right,
and returns the first true value.  If all the results are @code{#f},
or no @var{thunk}s are given, returns @code{#f}.
@c JP
@var{thunk} @dots{}をまず全て呼び出し、それから結果を左から右へ調べ、
最初に出会った真の値を返します。全てが@code{#f}であったり、
@var{thunk}がひとつも与えられなかった場合は@code{#f}を返します。
@c COMMON
@end defun

@defun funcall-procedure thunk
[SRFI-235]
@c MOD srfi.235
@c EN
Just call @var{thunk} and returns its result(s).
This is useful to pass to other procedures, e.g.
@code{(map funcall-procedure list-of-procedures)}.
@c JP
@var{thunk}を呼び出しその結果を返します。
これは他の手続きに渡すのに便利です。例えば：
@code{(map funcall-procedure list-of-procedures)}。
@c COMMON
@end defun

@defun loop-procedure thunk
[SRFI-235]
@c MOD srfi.235
@c EN
Calls @var{thunk} repeatedly forever.  Nonlocal escape is the only
way to break out.
@c JP
繰り返し@var{thunk}を呼びます。@var{thunk}からの大域脱出のみが
ループを抜ける方法です。
@c COMMON
@end defun

@defun while-procedure thunk
@defunx until-procedure thunk
[SRFI-235]
@c MOD srfi.235
@c EN
Calls @var{thunk} repeatedly while/until it returns a true value,
respectively.
@c JP
それぞれ、@var{thunk}が真の値を返す限り(while)、あるいは真の値を返すまで(until)、
繰り返し@var{thunk}を呼びつづけます。
@c COMMON
@end defun

@c EN
@subheading Auxiliary utilities
@c JP
@subheading 補助ユーティリティ
@c COMMON

@defun always obj @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Ignores arguments and always returns @code{#t}.
Same as @code{(constantly #t)}.
@c JP
引数を無視して常に@code{#t}を返す手続きです。
@code{(constantly #t)}と同じです。
@c COMMON
@end defun

@defun never obj @dots{}
[SRFI-235]
@c MOD srfi.235
@c EN
Ignores arguments and always returns @code{#f}.
Same as @code{(constantly #f)}.
@c JP
引数を無視して常に@code{#f}を返す手続きです。
@code{(constantly #f)}と同じです。
@c COMMON
@end defun

@c EN
Note: @code{boolean} is provided in the core (@pxref{Booleans}).
@c JP
註: @code{boolean}は組み込みです (@ref{Booleans}参照)。
@c COMMON

@c ----------------------------------------------------------------------
@node Codesets, Destructuring lists, Combinators (SRFI), Library modules - SRFIs
@section @code{srfi.238} - Codesets
@c NODE コードセット, @code{srfi.238} - コードセット

@deftp {Module} srfi.238
@mdindex srfi.238
@c EN
This module provides a unified interface for system-defined set of
code values, such as errno or signal numbers.
@c JP
このモジュールは、エラー番号やシグナル番号のような、システムが提供するコード値の集合を
扱うための統一的なインタフェースを提供します。
@c COMMON

@c EN
In Gauche, we have predefined integer constants for errnos (e.g. @code{EINTR})
and signals (e.g. @code{SIGINT}) in @code{gauche} module, and
we have built-in procedures to convert integer code to
symbols (@code{sys-errno->symbol}, @code{sys-signal-name})
and to string messages (@code{sys-strerror}, @code{sys-strsignal}).
You may want to use this srfi for portable code, though.
@c JP
Gaucheはエラー番号(errno)を表す整数定数(例:@code{EINTR})とシグナル番号を
表す整数定数(例@code{SIGINT})を@code{gauche}モジュールで提供していて、
また整数を対応するシンボルに変換する手続き
(@code{sys-errno->symbol}, @code{sys-signal-name})
および整数から記述的なメッセージを得る手続き
(@code{sys-strerror}, @code{sys-strsignal})
を組み込みにしてます。
ただ、ポータブルなコードを書きたい場合はこのSRFIは有用でしょう。
@c COMMON
@end deftp

@defun codeset? obj
[SRFI-238]
@c MOD srfi.238
@c EN
Returns @code{#t} if @var{obj} is an object that can be used as a @var{codeset}
argument for this srfi's API, @code{#f} otherwise.
In Gauche, @var{obj} must be either a symbol @code{errno} or @code{signal}.
@c JP
@var{obj}がこのsrfiのAPIの@var{codeset}引数に渡せるものなら@code{#t}を、
そうでなければ@code{#f}を返します。
Gaucheでは@var{obj}はシンボル@code{errno}か@code{signal}でなければなりません。
@c COMMON
@end defun

@defun codeset-symbols codeset
[SRFI-238]
@c MOD srfi.238
@c EN
Returns a list of symbols defined in a codeset designated by @var{codeset}.
In Gauche, @var{codeset} must be a symbol.  If it does not name a supported
codeset, an empty list is returned.
@c JP
@var{codeset}引数で表されるコードセットが定義しているシンボルのリストを返します。
Gaucheでは@var{codeset}はシンボルでなければなりません。
それが定義済みコードセットに対応しないシンボルだった場合は空リストが返されます。
@c COMMON

@example
(codeset-symbols 'errno)
 @result{} (EPERM ENOENT ESRCH EINTR EIO ...)
@end example
@end defun

@defun codeset-symbol codeset code
@defunx codeset-number codeset code
@defunx codeset-message codeset code
[SRFI-238]
@c MOD srfi.238
@c EN
Returns a symbol, an exact integer, or a message string associated to
the @var{code} in the codeset designated by @var{codeset}, respectively
@c JP
それぞれ、@var{codeset}で指定されるコードセット中の@var{code}に対応する
シンボル、正確な整数、あるいはメッセージ文字列を返します。
@c COMMON

@c EN
The @var{code} argument can be either a symbol or an exact integer.
The @var{codeset} argument must be a symbol.
@c JP
@var{code}引数はシンボルまたは正確な整数です。
@var{codeset}引数はシンボルでなければなりません。
@c COMMON

@c EN
If @var{codeset} is not a name of supported codesets (in Gauche,
we have @code{errno} and @code{signale}), or @var{code} is not in
the specified codeset, @code{#f} is returned.
@c JP
@var{codeset}がGaucheでサポートするコードセットを指定しないシンボルだったり、
@var{code}が指定されたコードセット中のコードを指定しない場合は@code{#f}が返ります。
@c COMMON

@example
(codeset-symbol 'errno 'EINTR) @result{} EINTR
(codeset-symbol 'errno EINTR)  @result{} EINTR  ; Gauche has predefined constant

(codeset-number 'errno 'EINTR) @result{} 4      ; Actual number is platform dependent
(codeset-number 'errno 4)      @result{} 4

(codeset-message 'errno EINTR) @result{} "Interrupted system call"

(codeset-message 'errno 'NoSuchErrno) @result{} #f
@end example
@end defun

@c ----------------------------------------------------------------------
@node Destructuring lists, Syntactic monads, Codesets, Library modules - SRFIs
@section @code{srfi.239} - Destructuring lists
@c NODE リストの分解, @code{srfi.239} - リストの分解

@deftp {Module} srfi.239
@mdindex srfi.239
@c EN
This module provides a pattarn-matching macro specialized for
the common pattern appearing frequently in list processing code.
It can be seen as a subset of @code{match} (@pxref{Pattern matching});
if you're writing Gauche-specific code, you don't need this module.
However, this is useful for portable code.
@c JP
このモジュールは、リスト処理のコードで頻繁に現れるパターンに特化した
パターンマッチングの機能を提供します。
Gauche用のコードを書いているなら、機能としてはGaucheの@code{match}のサブセットになるので
このモジュールを使う必要はありません(@ref{Pattern matching}参照)が、
ポータブルなコードを書いている時は有用でしょう。
@c COMMON
@end deftp

@defmac list-case expr clause @dots{}
[SRFI-239]
@c MOD srfi.239
@c EN
Each @var{clause} must be one of the following forms:
@c JP
各@var{clause}は以下のいずれかの形をとります。
@c COMMON

@itemize @bullet
@item
@code{((@var{var1} . @var{var2}) @var{body} @dots{})}
@item
@code{(() @var{body} @dots{})}
@item
@code{(@var{var} @var{body} @dots{})}
@end itemize

@c EN
Here, @var{var}, @var{var1}, @var{var2} are identifiers.
The order of clauses does not matter, and not all three forms need
to be present.
@c JP
ここで、@var{var}、@var{var1}、@var{var2}は識別子です。
@var{clause}は順不同で、3つ全てが揃っていなくても構いません。
@c COMMON

@c EN
First @var{expr} is evaluated.  If it is a pair, the first type of
clause is selected, and @var{body} @dots{} are evaluated with
the environment where the pair's car is bound to @var{var1} and the pair's
cdr is bound to @var{var2}.
If it is an empty list, the second type of clause is selected,
and its @var{body} @dots{} are evaluated.
Otherwise, the third type of clause is selected,
its @var{body} @dots{} are evaluated where
the value of @var{expr} is bound to @var{var}.
@c JP
まず@var{expr}が評価されます。それがペアなら、最初の形式の節が選択され、
@var{var1}がペアのcarに、@var{var2}がcdrに束縛された環境で@var{body} @dots{}が
評価されます。
@var{expr}の値が空リストなら2番めの形式の節が選択され、
@var{body} @dots{}が評価されます。
それ以外の場合は3番めの形式の節が選択され、
@var{expr}の値が@var{var}に束縛された環境で
@var{body} @dots{}が評価されます。
@c COMMON

@c EN
The identifier @code{_} has special meaning in @var{var}, @var{var1},
and @var{var2}; it is not bound and the corresponding value is simply discarded.
@c JP
@var{var}、@var{var1}、@var{var2}に@code{_}が使われた場合、
該当する値は束縛されず捨てられます。
@c COMMON

@c EN
If not all three forms are present and the result of @var{expr} does not
match the provided clauses, an error is thrown.
Note that, unlike @code{match},
if the first type of clause isn't provided, a pair does not
match the third type of clause
@c JP
3つ全ての節が揃っていなくて、@var{expr}の結果にマッチする節がなければ、
エラーが報告されます。
@code{match}と違い、最初の形式の節が指定されていない場合に、
ペアは3番めの形式の節とはマッチしません。
@c COMMON
@end defmac

@c ----------------------------------------------------------------------
@node Syntactic monads, Property testing, Destructuring lists, Library modules - SRFIs
@section @code{srfi.247} - Syntactic monads
@c NODE 構文的モナド, @code{srfi.247} - 構文的モナド

@deftp {Module} srfi.247
@mdindex srfi.247
This module provide a macro-defining macro, @code{define-syntactic-monad},
that captures a typical pattern of adding implicit or hidden
arguments.
@end deftp

@defmac define-syntactic-monad name formal @dots{}
[SRFI-247]
@c MOD srfi.247
@end defmac


@c ----------------------------------------------------------------------
@node Property testing, Data type checking, Syntactic monads, Library modules - SRFIs
@section @code{srfi.252} - Property testing
@c NODE プロパティテスト, @code{srfi.252} - プロパティテスト

@deftp {Module} srfi.252
@mdindex srfi.252
@c EN
Property testing is to feed random input to a component to be tested
and see if it satisfies certain properties hold.  The method was made
popular with Haskell's QuickCheck.
@c JP
プロパティテストは、テストしたいコンポーネントにランダムな入力を供給して
満たすべき属性(プロパティ)が満たされるかをテストする方法です。
HaskellのQuickCheckによってポピュラーになりました。
@c COMMON

@c EN
This module provides two groups of APIs; one for running property tests,
and another for generating random input.
@c JP
このモジュールでは、プロパティテストを実行するためのAPI群と、
ランダムな入力を生成するためのAPI群のふたつを提供します。
@c COMMON

@c EN
The test procedures are integrated with @code{gauche.test}
(@pxref{Unit testing}).  The SRFI is designed to be used with
SRFI-64 (@pxref{A Scheme API for test suites}); in Gauche, you can
run them with either of modules.
@c JP
テスト手続きは@code{gauche.test}と統合されています
(@ref{Unit testing}参照)。また、このSRFIはSRFI-64と併せて使えるように
設計されており、GaucheでもSRFI-64と併用することができます
(@ref{A Scheme API for test suites}参照)。
@c COMMON

@c EN
The random input generators are built on top of @code{data.random}
(@pxref{Random data generators}).  They are provided for
the convenience; you can use any generator to create input feed.
@c JP
ランダムな入力を生成するジェネレータは@code{data.random}の上に
構築されています (@ref{Random data generators}参照)。
これは簡便のために提供されています。必要なら、独自にジェネレータを作っても構いません。
@c COMMON
@end deftp

@c EN
@subheading Testing forms
@c JP
@subheading テストフォーム
@c COMMON

@defmac test-property property-check generator-list :optional runs
@defmacx test-property-expect-fail property-check generator-list :optional runs
@defmacx test-property-skip property-check generator-list :optional runs
@defmacx test-property-error property-check generator-list :optional runs
@defmacx test-property-error-type error-type property-check generator-list :optional runs
[SRFI-252]
@c MOD srfi.252
@c EN
Calls @var{property-check} over the arguments generated by
the generators in @var{generator-list} as many times as @var{runs}.
@c JP
@var{generator-list}にあるジェネレータが生成した値を引数として、
@var{property-check}を呼びます。それを@var{runs}回繰り返します。
@c COMMON

@c EN
@var{property-check} is an expression that evaluates to
a procedure accepts input, and returns
@code{#t} if the property is satisfied, @code{#f} if not.
The input is fed from generators listed in @var{generator-list};
it must have as many generators as the number of arguments
@var{property-check} accepts.
@c JP
@var{property-check}は手続きに評価される式で、プロパティが満たされたら@code{#t}を、
そうでなければ@code{#f}を返します。
引数は@var{generator-list}にリストされた各ジェネレータが生成します。
@var{generator-list}は@var{property-check}が受け取る引数と
同数のジェネレータから構成されていなければなりません。
@c COMMON

@c EN
The optional argument @var{runs} must be a nonnegative exact integer
to specify how many times @var{property-check} should be run.
If omitted, the system default is used, which is 30 in Gauche.
The default runs may be changed in future.
@c JP
省略可能な@var{runs}引数は非負の整数で、@var{property-check}を何回呼び出すかを
指定します。省略された場合はシステムのデフォルトが使われます
(Gaucheでは今のところ30。但し将来変わる可能性はあります)。
@c COMMON

@c EN
@code{Test-property} is the basic one; the test passes when every
@var{property-check} invocation returns true.
@code{Test-property-expect-fail}, on the other hand, passes
when every @var{property-check} returns false (thus, expected failure).
@code{Test-property-skip} does not run @var{property-check}, just
counts @var{runs} attempts as skipped tests.
@code{Test-property-error} expects all invocations of @var{property-check}
raises an error.
Finally, @code{test-property-error} and
@code{test-property-error-type} expect all @var{property-check} invocations
raise an error.  Additionally, @code{test-property-error-type}
expects the raised error is of type @var{error-type},
which should be a condition type.
@c JP
@code{test-property}が最も基本的なもので、全ての@var{property-check}の呼び出しが
成功であれば成功します。
@code{test-property-expect-fail}は逆に、全ての@var{properyt-check}
の呼び出しが失敗した場合に成功します (つまり、失敗することを期待したチェックです)。
@code{test-property-skip}は@var{property-check}は呼び出さず、
@var{runs}回のテストをスキップしたということだけを記録します。
最後に、@code{test-property-error}と@code{test-property-error-type}は
@var{property-check}が常にエラーを投げることを期待します。
@code{test-property-error-type}はそれに加え、投げられるエラーが
@var{error-type}コンディションタイプであることを期待します。
@c COMMON

@c EN
This SRFI is designed to be used with SRFI-64, but you can use these
directly with @code{gauche.test} without loading @code{srfi.64}.
@c JP
SRFIではこれらのテストはSRFI-64のフレームワーク上で実行されることを
想定していますが、@code{srfi.64}をロードせずに@code{gauche.test}のテストの
一環として実行することも可能です。
@c COMMON
@end defmac

@defun property-test-runner
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a SRFI-64 test runner object specialized for property testing.
In Gauche, this simply returns SRFI-64 simple runner, but other
implementations may have some additional features.  It is recommended
that portable code sets the runner created with this procedure
before calling property test procedures.
@c JP
プロパティテストのための、SRFI-64 テストランナーオブジェクトを返します。
Gaucheではこれは単にSRFI-64 simple runnerを返しますが、
他の実装では機能を追加したランナーが返されるかもしれません。
ポータブルなコードを書いている時は、
このテストランナーを使ってプロパティテストを行うと良いでしょう。
@c COMMON
@end defun

@c EN
@subheading Generators
@c JP
@subheading ジェネレータ
@c COMMON

@c EN
These are procedures that create generators of specific types.
You can find similar generator procedurs in @code{data.random}
(@pxref{Random data generators})
and @code{srfi.194} (@pxref{Random data generators (SRFI)}),
but the procedures here creates generators with one specific
property suitable for testing: They start generating certain
pre-defined values--typical, or boundary values--before generating
random values.
@c JP
以下の手続きは特定の型のオブジェクトを生成するジェネレータを作ります。
@code{data.random}(@ref{Random data generators}参照)や
@code{srfi.194}(@ref{Random data generators (SRFI)}参照)にも
似たような手続きがありますが、このモジュールのジェネレータ作成手続きで
作られるジェネレータには、プロパティテストに適した特性があります。
それは、ランダムな値を生成する前に、決められた一連の値(典型的な値および
境界値)を生成するということです。
@c COMMON

@c EN
All created generators captures the value of parameter
@code{random-data-random-source} (@pxref{Random data generators}) when created.
If you want to have reproducible results, you can provide your own
random source.
@c JP
以下の手続きで作られるジェネレータは、作成時の
@code{random-data-random-source}パラメータの値を取り込みます
(@ref{Random data generators}参照)。
テストを再現可能にしたい場合は、自前のランダムソースを使うことができます。
@c COMMON

@defun boolean-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a generator that yields @code{#t} and @code{#f}, then
a random boolean values in equal probability.
@c JP
@code{#t}、@code{#f}、そしてそれに続いて二つの真偽値を等確率でランダムに
生成するジェネレータを作って返します。
@c COMMON

@c EN
See also @code{booleans$} in @code{data.random}
(@pxref{Random data generators}).
@c JP
@code{data.random}の@code{booleans$}も参照
(@ref{Random data generators})。
@c COMMON
@end defun

@defun bytevector-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a generator that yields an empty bytevector @code{#u8()} first,
then bytevectors of random length and random content subsequently.
@c JP
まず空のバイトベクタ @code{#u8()} を生成し、続いて
ランダムな長さでランダムな内容を持つバイトベクタを生成するジェネレータを作って返します。
@c COMMON

@c EN
In Gauche, it is realized as follows (@pxref{Random data generators},
for @code{sequences-of} and @code{integers$}).
The constant @code{sequence-max-size} is currently 33 but may be
changed.
@c JP
Gaucheではこの手続きは、@code{sequences-of}と@code{integers$}を
使って次のとおり実装されています(@ref{Random data generators}参照)。
定数@code{sequence-max-size}は今の所33ですが、将来変更されるかもしれません。
@c COMMON
@example
(gcons* '#u8()
        (sequences-of <u8vector>
                      (integers$ sequence-max-size)
                      (integers$ 256))))
@end example
@end defun

@defun char-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a character generator that yields @code{#\null}, then
random characters subsequently.

Currently we use heuristically weighted sampling, so that ASCII
characters tends to appear a lot, although entire Unicode range
characters can appear.

See also @code{chars$} in @code{data.random}
(@pxref{Random data generators}).
@c JP
最初に@code{#\null}を、その後はランダムな文字を返すジェネレータを
作って返します。

今のところ、経験的に重み付けしたサンプリングを使っていて、
ASCII文字が出やすくなっていますが、全てのUnicode文字が生成される
可能性があります。

@code{data.random}の@code{chars$}も参照してください
(@ref{Random data generators})。
@c COMMON
@end defun

@defun string-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a string generator that yields an empty string @code{""},
then strings of random length and random content subsequently.

In Gauche, it is effectively equivalent to the following code
(@pxref{Random data generators},
for @code{strings-of} and @code{integers$}).
The constant @code{sequence-max-size} is currently 33 but may be
changed.
@c JP
まず空文字列、その後はランダムな長さのランダムな文字列を生成する
ジェネレータを作って返します。

Gaucheの実装は、次のコードと実質的に等価です
(@code{strings-of}と@code{integers$}については@ref{Random data generators}参照)。
定数@code{sequence-max-size}は今の所33ですが変更されるかもしれません。
@c COMMON
@example
(gcons* ""
  (strings-of (integers$ sequence-max-size)
              (rlet1 g (char-generator)
                (g))))          ; discard initial #\null
@end example
@end defun

@defun symbol-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a symbol generator that yields a symbol whose name
is empty (@code{||}), then symbols of random length and
random content subsequently.   It is basically
@code{(gmap string->symbol (string-generator))}.
@c JP
まず空の名前のシンボル(@code{||})、続いてランダムな長さのランダムな名前を持つ
シンボルを生成するジェネレータを作って返します。
基本的には@code{(gmap string->symbol (string-generator))}と考えて良いです。
@c COMMON
@end defun

@defun complex-generator
@defunx inexact-complex-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a generator that yields the following inexact complex
numbers, followed by random complex numbers.
@c JP
以下の複素数を順に生成し、続いてランダムな複素数を生成するジェネレータを
作って返します。
@c COMMON

@example
0.0 -0.0 0.5 -0.5 1.0 -1.0
0.0+1.0i 0.0-1.0i -0.0+1.0i -0.0-1.0i
0.5+0.5i 0.5-0.5i -0.5+0.5i -0.5-0.5i
1.0+1.0i 1.0-1.0i -1.0+1.0i -1.0-1.0i
+inf.0+inf.0i +inf.0-inf.0i -inf.0+inf.0i -inf.0-inf.0i
+nan.0+nan.0i
+inf.0 -inf.0 +nan.0
@end example

@c EN
Note: SRFI specifies generators created by @code{complex-generator} to return
both exact and inexact complex numbers if the implementation supports
them.  Gauche doesn't have exact complex numbers, so it is the
same as @code{inexact-complex-generator}.
@c JP
註: SRFIでは、@code{complex-generator}が作るジェネレータは
実装がサポートしていれば正確な複素数と非正確な複素数のどちらも返すと
されています。Gaucheは正確な複素数を持っていないので、
これは@code{inexact-complex-generator}と同じです。
@c COMMON

@c EN
In Gauche's implementation, a random complex number is created by
uniformly sampled finite flonums for real and imaginary parts.
Note that ``uniformly sampled finite flonums'' are not the same
as ``uniformly sampled real numbers''; See @code{finite-flonums$}
of @code{data.random}
for the details (@pxref{Random data generators}).
@c JP
Gaucheの実装では、ランダムな複素数は、実部と虚部をそれぞれ
有限浮動小数点数の集合から一様にサンプリングして作っています。
「一様にサンプリングした有限浮動小数点数」は、
「一様にサンプリングした実数」とは異なることに注意してください。
詳しくは@code{data.random}の@code{finite-flonums$}を参照
(@ref{Random data generators})。
@c COMMON
@end defun

@defun exact-complex-generator
@defunx exact-integer-complex-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Gauche does not support exact complex numbers, and these procedures
raise an error when called.
@c JP
Gaucheは正確な複素数をサポートしていないので、
これらの手続きは呼ばれたらエラーを投げます。
@c COMMON
@end defun

@defun integer-generator
@defunx exact-integer-generator
@defunx inexact-integer-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Return generators that yields integers, exact integers,
and inexact integers, respectively.
@c JP
整数、正確な整数、非正確な整数をそれぞれ生成するジェネレータを作って返します。
@c COMMON

@c EN
The exact integer generator always yield @code{0}, @code{1}, and @code{-1}
at the beginning, then random integers follow.
@c JP
正確な整数のジェネレータは、まず@code{0}、@code{1}、@code{-1}を
順に生成してから、続いてランダムな整数を生成します。
@c COMMON

@c EN
The inexact integer generator always yield @code{0.0}, @code{-0.0},
@code{1.0}, and @code{-1.0}
at the beginning, then random integers follow.
@c JP
非正確な整数のジェネレータは、まず@code{0.0}、@code{-0.0}、
@code{1.0}、@code{-1.0}を
順に生成してから、続いてランダムな整数を生成します。
@c COMMON

@c EN
The general integer generator created by @code{integer-generator}
samples evenly from an exact integer genratgor and an inexact
integer generator.
@c JP
@code{integer-generator}が返す一般の整数のジェネレータは、
正確な整数のジェネレータと不正確な整数のジェネレータから当確率で
ランダムにサンプリングします。
@c COMMON

@c EN
Since the range of exact integers is only bounded by the memory,
uniform sampling from the entire possible range is infeasible;
almost all samples would become a huge integer.  Instead, we split
integer range into 3: relatively small integers,
fixnums, and bignums, and sample evenly from these three generators.
Small integers and fixnums are sampled uniformly within its range,
and bignums are sampled according to the power law; so, we see
a lot more bignums closer to fixnum range, with occasional really big
numbers sprinkled in.
@c JP
正確な整数の範囲はメモリの許す限り大きくできるので、
可能な値の範囲から一様サンプリングするのは現実的ではありません。
ほとんど全てのサンプルは非常に大きな整数になってしまうでしょう。
かわりにGaucheでは、整数の範囲を3つに区切りました。
比較的小さな整数、fixnum、そしてbignumです。
小さな整数とfixnumは範囲内で一様サンプリングされます。
bignumはべき乗則によってサンプリングされます。
従って、生成されるbignumの多くはfixnumに近いレンジになり、
時折非常に大きな整数が混ざるという感じになります。
@c COMMON
@end defun

@defun rational-generator
@defunx exact-rational-generator
@defunx inexact-rational-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Return generators that yields rational numbers, exact rational numbers,
and inexact rational numbers, respectively.
@c JP
それぞれ、有理数、正確な有理数、そして不正確な有理数を生成するジェネレータを
作って返します。
@c COMMON

@c EN
The exact rational number generator yields
@code{0}, @code{1}, @code{-1}, @code{1/2}, and @code{-1/2} at
the beginning, then generate @code{(/ a b)} where @code{a}, @code{b}
are generated in the same way as @code{exact-integer-generator}'s
distribution, except 0 is excluded from @code{b}.
@c JP
正確な有理数ジェネレータは、最初に
@code{0}、@code{1}、@code{-1}、@code{1/2}、@code{-1/2}を順に生成し、
その後は@code{exact-integer-generator}と同じ分布で生成した
正確な整数@code{a}、@code{b}を使って@code{(/ a b)}を生成します
(@code{b}から0は除外します)。
@c COMMON

@c EN
The inexact rational number generator yields
@code{0.0}, @code{-0.0}, @code{0.5}, @code{=0.5}, @code{1.0}, and @code{-1.0}
at the beginning, then proceed to generate random inexact rational numbers.
In Gauche, inexact rational numbers are finite flonums, and we uniformly
samples from all possible finite flonums (which is @emph{not} the same
as uniform sample from a range of real numbers).
See @code{finite-flonums$} in @ref{Random data generators}.
@c JP
非正確な有理数ジェネレータは、最初に
@code{0.0}、@code{-0.0}、@code{0.5}、@code{=0.5}、@code{1.0}、@code{-1.0}
を順に生成し、その後は非正確な有理数をランダムに生成します。
Gaucheでは非正確な有理数は有限な浮動小数点数で表されるので、
可能な有限浮動小数点数から一様サンプリングした値を使います
(これは表現可能な実数範囲からの一様サンプリングではありません)。
詳しくは@ref{Random data generators}の@code{finite-flonums$}
を参照してください。
@c COMMON

@c EN
The general rational number generator created by @code{rational-generator}
evenly samples from an exact rational number generator and
an inexact rational number generator.
@c JP
@code{rational-generator}が返す一般の有理数ジェネレータは、
正確な有理数ジェネレータと非正確な有理数ジェネレータから等確率で
サンプリングします。
@c COMMON
@end defun

@defun real-generator
@defunx exact-real-generator
@defunx inexact-real-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Return generators that yields real numbers, exact real numbers,
and inexact real numbers, respectively.
@c JP
それぞれ、実数、正確な実数、そして不正確な実数を生成するジェネレータを
作って返します。
@c COMMON

@c EN
In Gauche, the set of exact real numbers are exactly the same as
the set of exact rational numbers (infinites and NaNs are inexact),
so @code{exact-real-generator} is the same as
@code{exact-rational-generator}.
@c JP
Gaucheでは、正確な実数の集合は正確な有理数の集合と一致します
(無限大およびNaNは非正確だからです)。
従って、@code{exact-real-generator}は
@code{exact-rational-generator}と同じです。
@c COMMON

@c EN
The inexact real number generator yields
@code{0.0}, @code{-0.0}, @code{0.5}, @code{-0.5},
@code{1.0}, @code{-1.0}, @code{+inf.0},  @code{-inf.0}, and @code{+nan.0}
at the beginning, followed by inexact real numbers uniformly sampled
from all possible finite flonums (which is @emph{not} the same
as uniform sample from a range of real numbers).
See @code{finite-flonums$} in @ref{Random data generators}.
@c JP
非正確な実数のジェネレータは、まず
@code{0.0}、@code{-0.0}、@code{0.5}、@code{-0.5},
@code{1.0}、@code{-1.0}、@code{+inf.0}、@code{-inf.0}、@code{+nan.0}を
順に生成し、以降は可能な有限浮動小数点数から一様サンプリングした値を使います
(これは表現可能な実数範囲からの一様サンプリングではありません)。
詳しくは@ref{Random data generators}の@code{finite-flonums$}
を参照してください。
@c COMMON

@c EN
The general real number generator created by @code{real-generator}
evenly samples from an exact real number generator and
an inexact real number generator.
@c JP
@code{real-generator}が返す一般の実数ジェネレータは、
正確な実数ジェネレータと非正確な実数ジェネレータから等確率で
サンプリングします。
@c COMMON
@end defun

@defun number-generator
@defunx exact-number-generator
@defunx inexact-number-generator
[SRFI-252]
@c MOD srfi.252
@c EN
In Gauche, the set of exact numbers is the same as
the set of exact rational numbers (we don't have exact complex),
and the set of inexact numbers
is the same as the set of inexact complex numbers.
Thus @code{exact-number-generator} is the same as
@code{exact-rational-generator}, and
@code{inexact-number-generator} is the same as
@code{inexact-complex-generator}.
@c JP
Gaucheでは、正確な数の集合は(正確な複素数を持ってないので)
正確な有理数の集合と等しく、非正確な数の集合は
非正確な複素数の集合と等しいです。
従って、@code{exact-number-generator}は
@code{exact-rational-generator}と同じ、
@code{inexact-number-generator}は
@code{inexact-complex-generator}と同じです。
@c COMMON

@c EN
The general number generator created by @code{number-generator}
evenly samples from an exact number generator and
an inexact number generator.
@c JP
@code{number-generator}が返す一般の数ジェネレータは、
正確な数ジェネレータと非正確な数ジェネレータから等確率で
サンプリングします。
@c COMMON
@end defun

@defun list-generator-of elt-generator :optional max-length
@defunx vector-generator-of elt-generator :optional mex-length
[SRFI-252]
@c MOD srfi.252
@c EN
Return generators that yield an empty list or vector
first, then lists or vectors of random length
up to @var{max-length},
and elements generated by @var{elt-generator}, respectively.
Similar to @code{lists-of}/@code{vectors-of} in @code{data.random}.
@c JP
最初に空リスト/空ベクタを、以降は@var{max-length}を最大長とする
ランダムな長さのリストおよびベクタを
それぞれ生成するジェネレータを作って返します。
返されるリストやベクタの要素は、ジェネレータ@var{elt-generator}で
作られます。
@code{data.random}の@code{lists-of}/@code{vectors-of}と似ています。
@c COMMON

@c EN
When @var{max-length} is omitted, we leave the length to the default
of @code{lists-of}/@code{vectors-of},
 which is determined by the parameter
@code{default-sizer} in @code{data.random}.
@xref{Random data generators}, for the details.
@c JP
@var{max-length}が省略された場合は、@code{lists-of}/@code{vectors-of}の
デフォルトに任せます。それは@code{data.random}のパラメータ
@code{default-sizer}で制御されます。
詳しくは@ref{Random data generators}を参照してください。
@c COMMON
@end defun

@defun pair-generator-of car-generator :optional cdr-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a generator that yields pairs, whose car is generated
with @code{car-generator} and whose cdr is generated
with @code{cdr-generator}.  If @var{cdr-generator} is omitted,
@code{car-generator} is used.
@c JP
ペアを生成するジェネレータを作って返します。
@code{cdr-generator}が指定された場合、各ペアのcarは
@code{car-generator}、cdrは@code{cdr-generator}で生成します。
@code{cdr-generator}が省略された場合、carとcdr両方に@code{car-generator}を
使います。
@c COMMON
@end defun

@defun procedure-generator-of value-generator
[SRFI-252]
@c MOD srfi.252
@c EN
Returns a generator that yields procedures, which accepts
any number of arguments and returns a value generated with
@var{value-generator}.
@c JP
手続きを生成するジェネレータを作って返します。
各手続きは任意個の引数を取り、@code{value-generator}が生成する
値を戻り値とします。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Data type checking, Uninterned symbols (SRFI), Property testing, Library modules - SRFIs
@section @code{srfi.253} - Data type checking
@c NODE データ型検査, @code{srfi.253} - データ型検査

@deftp {Module} srfi.253
@mdindex srfi.253
@c EN
This SRFI defines forms to check the types of variables and arguments.
@c JP
このSRFIは、変数や引数の値の型を検査するフォームを定義します。
@c COMMON
@end deftp

@defmac check-arg type-pred expr :optional caller
[SRFI-253]
@c MOD srfi.253
@c EN
Checks that @var{expr} conforms to @var{type-pred}.
The @var{type-pred} argument is either a type predicate that returns
true if the value of @var{expr} has the expected type,
or a type object to be passed to @code{of-type?} for checking.
(Note: Passing a type object is Gauche's extension to the SRFI).
@c JP
@var{expr}が@var{type-pref}に合致しているかどうかをチェックします。
@var{type-pred}は@var{expr}の値を受け取って合致してれば真の値を返す
型述語か、@var{of-type?}に渡せる型オブジェクトです。
(型オブジェクトを渡すのはSRFIに対するGaucheの拡張です)。
@c COMMON

@c EN
SRFI specifies the check is optional; an implementation may choose
to omit the check for higher-optimization level, for example.
Currently Gauche always perform the check, but we may add
some options to omit it in future.
@c JP
SRFIの仕様では、検査は必ずしも行わなくて良いことになっています。
例えば実装は最適化レベルを上げた場合に検査を省略するかもしれません。
Gaucheは今のところ必ず検査しますが、
将来検査を省くオプションを導入する可能性はあります。
@c COMMON

@c EN
The optional @var{caller} argument (evaluated) can be used
to indicate who is signalling the error.
@c JP
省略可能な引数@var{caller} (評価されます)は、
エラーの発生箇所(手続き名など)を示すのに使えます。
@c COMMON

@c EN
NB: Gauche has provided undocumented @code{check-arg} macro for long time,
to be used in early SRFIs.  Since existing code may rely on it,
we still provide it in the core (@code{srfi.253} merely re-exports it),
but the users should use @code{srfi.253} explicitly if they want
@code{check-arg} marco.  Doing so is portable as well.
Built-in support may be dropped in future.
@c JP
注: Gaucheは、ごく初期のSRFIで使うために非公式に@code{check-arg}マクロを
持っていました。既存のライブラリがっそれに依存している可能性があるので、
今でもこのマクロはコアで提供され、@code{srfi.253}は単にそれを再エクスポート
しています。ただ、ユーザは@code{check-arg}マクロを使いたければ
@code{srfi.253}を明示的にuseしてください。その方がポータブルですし。
組み込みの@code{check-arg}は将来無くすかもしれません。
@c COMMON
@end defmac

@c EN
The rest of the module consists of helper macro for common Scheme
forms that call @code{check-arg}.
@c JP
モジュールの残りは、典型的なパターンを
@code{check-arg}を呼び出す式に展開するマクロです。
@c COMMON

@defmac values-checked (type-pred @dots{}) val @dots{}
[SRFI-253]
@c MOD srfi.253
@c EN
Returns multiple values listed in @var{val} @dots{},
but each of @var{val} is checked with the corresponding @var{type}
by @code{(check-arg type val)}.  In other words, you can add
type checking to @code{(values val @dots{})}.
@c JP
@var{val} @dots{}に並べられた複数の値を返しますが、
各値は対応する@var{type}を@code{(check-arg type val)}のように使って
検査されます。@code{(values val @dots{})}に型検査を追加したものと
考えることもできます。
@c COMMON
@end defmac

@defmac check-case expr (type-pred body @dots{}) @dots{} :optional (else else-body @dots{})
[SRFI-253]
@c MOD srfi.253
@c EN
Evaluates @var{expr}, and it is checked against each @var{type-pred} in the
same way as @code{check-arg}, in order.  That is, @var{type-pred} must be
a type predicate or a type object.
@c JP
@var{expr}を評価し、その値を順に@var{type-pred}で、@code{check-arg}と同じように
検査してゆきます(つまり、@var{type-pred}は型述語か型オブジェクトです)。
@var{epxr}の値が求める型に合致したら、そこで検査を打ち切り、
続く@var{body} @dots{}を評価して最後の値を返します。
@c COMMON

@c EN
If the value of @var{expr} satisfies no @var{type-pred}, @var{else-body} @dots{}
are evaluated if the @code{else} clause is provided, or an
error is thrown (Gauche always throws an error in that case,
but SRFI does not require it.)
@c JP
@var{expr}の値がいずれの@var{type-pred}も満たさなかった場合、
@code{else}節があれば@var{else-body} @dots{}が評価され、
なければエラーが投げられます
(Gaucheは常にエラーを投げますが、
SRFIはエラーを必ず投げることは要求していません)。
@c COMMON

@c EN
See also @code{typecase} (@pxref{Conditionals}).
@c JP
@code{typecase}も見て下さい (@ref{Conditionals})。
@c COMMON
@end defmac

@defmac lambda-checked formals+ body @dots{}
@defmacx case-lambda-checked (formals+ body @dots{}) @dots{}
[SRFI-253]
@c MOD srfi.253
@c EN
Like @code{lambda} and @code{case-lambda}, but you can
put @code{(@var{arg} @var{type-pred})} in place of an argument
in the formals, excep the ``rest'' argument.
Such argument is checked with
@code{(check-arg @var{arg} @var{type-pred} 'lambda-checked)}.
@c JP
@code{lambda}、@code{case-lambda}と似ていますが、
@var{formals}の各引数 (最後の残余引数以外)
に@code{(@var{arg} @var{type-pred})}を置くことができます。その引数は
@code{(check-arg @var{arg} @var{type-pred} 'lambda-checked)}で
検査されます。
@c COMMON

@example
(lambda-checked (obj (i integer?) (j integer?) . opts)
  ...)

@equiv{}
(lambda (obj i j . opts)
  (check-arg i integer? 'lambda-checked)
  (check-arg j integer? 'lambda-checked)
  ...)
@end example
@end defmac

@defmac define-checked (name . formals+) body @dots{}
@defmacx define-checked name type-pred value
[SRFI-253]
@c MOD srfi.253
@c EN
The first form is a shorthand of
@code{(define name (lambda-checked formals+ body @dots{}},
except that @code{'@var{name}} is passed to the @var{caller} argument
of @code{check-arg}.

The second form is a shorthand of
@code{(define name (values-checked (type-pred) value)}.
@c JP
最初の形式は
@code{(define name (lambda-checked formals+ body @dots{}}
の短縮形です。ただし、@code{'@var{name}}が@code{check-arg}
の@var{caller}引数に渡されます。

二番目の形式は
@code{(define name (values-checked (type-pred) value)}の短縮形です。
@c COMMON
@end defmac

@defmac define-record-type-checked type-name (constructor arg @dots{}) predicate field @dots{}
[SRFI-253]
@c MOD srfi.253
@c EN
Defines a record type with checked constructor and field
accessors/modifiers, like @code{define-record-type}.

Each field is the form either @code{(field-name type-red accessor-name)} or
@code{(field-name type-pred accessor-name modifier-name)}, where
@var{type-pred} is used with @code{values-checked} and @code{check-arg}
to ensure that accessor and modifier return
checked data and check new data respectively.
@code{define-record-type-checked} also guarantees that initial values
passed to constructor are satisfying the predicates provided in field
specification.
@c JP
@code{define-record-type}と同様に、レコード型とその
コンストラクタ、フィールドアクセサ、フィールドモディファイアを定義します。

各フィールドは@code{(field-name type-red accessor-name)}もしくは
@code{(field-name type-pred accessor-name modifier-name)}の形式で、
@var{type-pred}が@code{values-checked}や@code{check-arg}によって
アクセサが返す値とモディファイアが受けとる値を検査するのに使われます。
また、コンストラクタに渡された値がフィールドに対する正しい型かどうかも検査されます。
@c COMMON
@end defmac


@c ----------------------------------------------------------------------
@node Uninterned symbols (SRFI), Tagged procedures with type safety, Data type checking, Library modules - SRFIs
@section @code{srfi.258} - Uninterned symbols (SRFI)
@c NODE インターンされないシンボル(SRFI), @code{srfi.258} - インターンされないシンボル(SRFI)

@deftp {Module} srfi.258
@mdindex srfi.258
@c EN
This SRFI defines a common interface to handle uninterned symbols.

Uninterned symbols are the symbols that are not registered to the
internal hashtables mapping names to symbols. Ordinary symbols
are registered, so when symbols with the same name are read,
they are guaranteed to be @code{eq?} to each other.
On the other hand, there's no way to get a symbol @code{eq?} to an
existing uninterned symbol, except
being passed a direct reference to it.

It is handy for legacy Lisp
macros to avoid name collisions, for uninterned symbols created
during macro expansion will never conflict with symboss created
elsewhere.
@c JP
このSRFIは、インターンされないシンボルについての共通のインタフェースを定義しています。

インターンされないシンボルとは、内部の名前からシンボルへのハッシュテーブルに登録
されないシンボルのことです。通常のシンボルは名前が登録されているので、
同じ名前のシンボルを読んだらそれがシンボルとして@code{eq?}になることが保証されています。
インターンされないシンボルは、そのシンボルへの参照を直接受け渡しする以外に、
@code{eq?}であるシンボルを入手する方法がありません。

インターンされないシンボルは、レガシーなLispマクロにおいて名前の衝突を避けるために
便利に使われてきました。マクロ展開時に作られたインターンされないシンボルは
プログラム中の他のシンボルと決して衝突しないからです。
@c COMMON

@c EN
With its hygiene macro system, Scheme does not need uninterned symbols
to avoid name conflicts in macros (@pxref{Macros}).
Nevertheless, many Scheme implementations,
including Gauche, provide this facility, partly to ease porting
other Lisp idioms, or a handy way to get a unique object.
@c JP
Schemeには衛生的マクロシステムがあるので、マクロで名前衝突を避けるために
インターンされないシンボルを使う必要はありません(@ref{Macros}参照)。
それでも、Gaucheを含む多くのScheme実装ではこの機能を提供しています。
他のLispのイディオムを移植したり、単に実行時にユニークなオブジェクトを得るのに
便利だからです。
@c COMMON

@c EN
This SRFI is defined so that the user program can access uninterned
symbosl portably, if the implementation provides one.
@c JP
このSRFIは、インターンされないシンボルを提供している実装間でポータブルな
インタフェースを提供するためのものです。
@c COMMON

@c EN
Gauche has the following two procedures defined in this SRFI as built-in:
@c JP
Gaucheでは、SRFI-258のうち次の２つの手続きは組み込みです。
@c COMMON

@example
string->uninterned-symbol
symbol-interned?
@end example

@c EN
@xref{Uninterned symbols}, for the details.
@c JP
詳しくは@ref{Uninterned symbols}を参照してください。
@c COMMON
@end deftp

@defun generate-uninterned-symbol :optional prefix
[SRFI-258]
@c MOD srfi.258
@c EN
Creates and returns a fresh uninterned symbol.  Similar to
@code{gensym} (@pxref{Uninterned symbols}), but this allows both symbol
and string in @var{prefix}.
@c JP
新たなインターンされないシンボルを作って返します。
@code{gensym}と似ていますが、こちらは@var{prefix}にシンボルも文字列も使えます
(@xref{Uninterned symbols}参照)。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Tagged procedures with type safety,  , Uninterned symbols (SRFI), Library modules - SRFIs
@section @code{srfi.259} - Tagged procedures with type safety
@c NODE 型安全な手続きタグ, @code{srfi.259} - 型安全な手続きタグ

@deftp {Module} srfi.259
@mdindex srfi.259
@c EN
This SRFI is an extension of the concept of tagged procedures
introduced by SRFI-229 (@pxref{Tagged procedures}).
@c JP
このSRFIは、SRFI-229 (@ref{Tagged procedures}参照)で導入された
タグ付き手続きの概念を拡張するものです。
@c COMMON

@c EN
SRFI-229 allows to attach arbitrary object to a procedure.
It opened possibilities to implement interesting features
on top of a very simple primitive.  However, since the type and
use of tag object is totally up to the user, it can be difficult
to compose libraries that relies on procedure tags.  What if two
libraries chose to use the same type of tags (e.g. symbols)?
What if one library wants to add a tag to a procedure that is already
tagged by another library?
@c JP
SRFI-229では手続きに任意のオブジェクトをタグとして付加することができました。
それは非常に単純なメカニズムの上に興味深い機能を実装する可能性を開きましたが、
タグオブジェクトの型や使い方は完全にユーザ任せのため、
手続きタグを違う形で活用しているライブラリ同士の組み合わせが
困難になる場合があります。
例えば、別々のライブラリがともに同じ型(例:シンボル)をタグとして使っていたら?
あるいは、既に他のライブラリがタグ付けしている手続きにさらにタグをつけたかったら?
@c COMMON

@c EN
This SRFI addresses that issue.  It creates a unique kind of procedure
tags that can only be attached and queried by the designated procedures,
so it won't intefere with other libraries' use of tags.
@c JP
このSRFIはその問題を解決するものです。
特定の手続きからだけ、タグ付けし、検査し、アクセスできるようにするユニークな
手続きタグ型を導入できるようにします。
異なる型の手続きタグ同士は干渉しません。
@c COMMON

@c EN
The reference implementation of this SRFI is implemented on top of
SRFI-229, allowing users to peek under the hood if they use SRFI-229
@code{procedure-tag}.  In Gauche, we implement this SRFI directly
in the Gauche's native mechanism, so SRFI-259 procedure tags are orthogonal
to SRFI-229 procedure tags.
@c JP
このSRFIの参照実装はSRFI-229の手続きタグの上に作られていたので、
ユーザがSRFI-229の@code{procedure-tag}を使って中身を覗くことができました。
Gaucheの実装では、このSRFIをGaucheのネイティブな機構の上に直接実装していて、
SRFI-229の手続きタグとは直交するものになっています。
@c COMMON
@end deftp

@defmac define-procedure-tag tagger pred accessor
[SRFI-259]
@c MOD srfi.259
@c EN
Construct a unique procedure tag type, orthogonal to any other
procedure tags.  Arguments @var{tagger}, @var{pred}, and @var{accessor}
must be identifiers, and are bound to procedures to utilize the new
procedure tag type.
@c JP
他の手続きタグ型と直交する、一意の手続きタグ型を作ります。
引数@var{tagger}、@var{pred}、@var{accessor}はそれぞれ識別子で、
新たな手続き型タグを使うための次のような手続きに束縛されます。
@c COMMON

@c EN
The identifier @var{tagger} is bound to a procedure that takes
a value and a procedure, and returns a tagged procedure that works
the same as the given procedure, associating the given value to the
given procedure with this specific tag type.
If the given procedure is already tagged by other tag types, the
returned procedure has both tag types, keeping values of each type
separately.
@c JP
@var{tagger}は値と手続きを取り、元の手続きと同様に動作し、
かつ与えられた値をこの手続きタグ型の値として持つ手続きを返します。
与えられた手続きが既に他の型の手続きタグでタグ付けされていた場合、
返される手続きは両方の手続きタグを持ちます。
@c COMMON

@c EN
The identifier @var{pred} is bound to a predicate, that returns
@code{#t} if the argument is a procedure with this tag type, @code{#f}
otherwise.
@c JP
@var{pred}は引数がこの手続きタグ型でタグづけされた手続きであれば@code{#t}を、
そうでなければ@code{#f}を返す述語に束縛されます。
@c COMMON

@c EN
The identifier @var{accessor} is bound to a procedure that takes
a procedure with this tag type, and returns the associated value.
It is an error to pass objects other than procedures with this tag type.
@c JP
@var{accessor}はこの手続きタグ型でタグづけされた手続きを取り、そのタグ型の
値を返します。引数がこの手続きタグ型でタグづけされた手続きでない場合は
エラーが投げられます。
@c COMMON

@c EN
A tag type created by this macro is conceptually anonymous,
but for the debugging aid, Gauche uses @var{tagger} as a part of
tag type name.
@c JP
このマクロで作られる手続きタグ型は概念的には無名の型ですが、
デバッグの助けのために、Gaucheは@var{tagger}を型名の一部に使います。
@c COMMON
@end defmac



@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
