@node Core library, Object system, Macros, Top
@chapter Core library
@c NODE 組み込みライブラリ

@c ----------------------------------------------------------------------
@menu
* Types and classes::
* Equality and comparison::
* Numbers::
* Booleans::
* Undefined values::
* Pairs and lists::
* Symbols::
* Characters::
* Character sets::
* Strings::
* Regular expressions::
* Vector family::
* Dictionaries::
* Procedures and continuations::
* Parameters and dynamic states::
* Boxes::
* Lazy evaluation::
* Exceptions::
* Eval and repl::
* Input and output::
* Loading Programs::
* Sorting and merging::
* System interface::
* Development helper API::
@end menu

@node Types and classes, Equality and comparison, Core library, Core library
@section Types and classes
@c NODE 型とクラス

@c EN
Scheme is a dynamically and strongly typed language.  That is,
every value @emph{knows} its type at run-time, and the type
determines what kind of operations can be applied on the value.
@c JP
Schemeは動的な強い型付けの言語です。つまり、全ての値は
実行時に自分の型を知っていて、その型が値に適用できる操作を決定します。
@c COMMON

@c EN
The Scheme standard is pretty simple on types; basically,
an object being a type means the type predicate returns true on the object,
and that's all.  Gauche adopts a bit more elaborated system---types are
first-class objects and you can query various information.
@c JP
Scheme標準は、型についてはとても単純です。基本的に、オブジェクトがある型であるというのは、
そのオブジェクトに対して型述語が真を返す、それだけです。
Gaucheはもう少し込み入ったシステムを採用していて、型も第一級のオブジェクトになり
様々な情報を問い合わせることができます。
@c COMMON

@c EN
In Gauche, types are conventionally
named with brackets @code{<} and @code{>}, e.g. @code{<string>}.
It's nothing syntactically special with these brackets; they're valid
characters to consist of variable names.
@c JP
Gaucheでは慣習的に、型は@code{<string>}のように
@code{<}と@code{>}で囲まれた名前を持ちます。
この@code{<}や@code{>}は文法的には何ら特別な意味を持ちません。
普通に変数名として使える文字です。
@c COMMON

@menu
* Prescriptive and descriptive types::
* Generic type predicates::
* Predefined classes::
* Type expressions and type constructors::
* Native types::
@end menu

@node Prescriptive and descriptive types, Generic type predicates, Types and classes, Types and classes
@subsection Prescriptive and descriptive types
@c NODE 規範的な型と記述的な型

@c EN
Types are used in two ways.  A type can be seen as a template of
the actual values (instances)---that is, a type @emph{prescribes}
the structure of, and possible operations on, its instances.
In Gauche, such prescriptive types are represented by @emph{classes}.
Every value in Gauche belongs to a class, which can be queried with the
@code{class-of} procedure.  You can also define your own class with
@code{define-class} or @code{define-record-type}
(@pxref{Object system}, and @pxref{Record types}).
@c JP
型には2つの使われ方があります。まず、型は実際の値(インスタンス)のテンプレートと
見ることができます。つまり、型がインスタンスの構造と、それに適用できる操作を
あらかじめ決めている(prescribe)ということです。
Gaucheでは、このような規範的(prescriptive)な型は、@emph{クラス}で表現されます。
Gauche内での値は全て何かのクラスに属していて、
@code{class-of}手続きでそのクラスを取れます。また、ユーザは独自のクラスを
@code{define-class}や@code{define-record-type}で定義することもできます
(@ref{Object system}および@ref{Record types}参照)。
@c COMMON

@c EN
A type can also be seen as a constraint of a given
expression---that is, a type @emph{describes} what characteristics
a certain expression must have.   Gauche has entities
to represent such descriptive types separate from classes.
Descriptive types are created with @emph{type constructors}
(@pxref{Type expressions and type constructors}).
We also have a set of predefined descriptive types to communicate
to C libraries (@pxref{Native types}.
@c JP
型はまた、与えられた式についての制約と見ることもできます。
つまり、型がその式が持つべき特定の性質を記述する(describe)ということです。
Gaucheでは、クラスとは別に、そういった記述的(descriptive)な型を表現するエンティティを
用意しています。記述的な型は型コンストラクタで作ることができます
(@ref{Type expressions and type constructors}参照)。
また、Cライブラリとやりとりするための記述的な型も用意されています
(@ref{Native types}参照)。
@c COMMON

@c EN
A value is an instance of a class. For example,
@code{1} is an instance of @code{<integer>}, and @code{"xyz"}
is an instance of @code{<string>}.  This presctiptive type relationship
is checked with @code{is-a?} procedure: @code{(is-a? 1 <integer>)} and
@code{(is-a? "xyz" <string>)} both returns @code{#t}.
@c JP
値は、特定のクラスのインスタンスです。
例えば@code{1}は@code{<integer>}のインスタンスであり、
@code{"xyz"}は@code{<string>}のインスタンスです。
このprescriptiveな型の関係は、手続き@code{is-a?}で検査できます。
@code{(is-a? 1 <integer>)}、@code{(is-a? "xyz" <string>)}は
どちらも@code{#t}を返します。
@c COMMON

@c EN
On the other hand, you may have a procedure that takes either a number
or a string as an argument.  ``A number or a string'' is a type constraint,
and can be expressed as a descriptive type, @code{(</> <number> <string>)}.
Descriptive type relationship is checked with @code{of-type?} procedure:
@code{(of-type? 1 (</> <number> <string>))} and
@code{(of-type? "xyz" (</> <number> <string>))} both returns @code{#t}.
More conveniently, @code{(assume-type arg (</> <number> <string>))}
would raise an error if @var{arg} doesn't satisfy the given type constraint.
@c JP
一方、例えば手続きが数値か文字列を引数に取る、といったケースもあります。
「数値か文字列」というのは型に関する制約であり、descriptiveな型
@code{(</> <number> <string>)}として表現できます。
descriptiveな型の関係は手続き@code{of-type?}で検査できます。
@code{(of-type? 1 (</> <number> <string>))}、
@code{(of-type? "xyz" (</> <number> <string>))}はどちらも@code{#t}を返します。
また、@code{(assume-type arg (</> <number> <string>))}は
@var{arg}が与えられた型の制約を満たさなければエラーを投げます。
@c COMMON

@node Generic type predicates, Predefined classes, Prescriptive and descriptive types, Types and classes
@subsection Generic type predicates
@c NODE 汎用型述語

@c EN
A ``type predicate'' is a predicate that tells if an object is of a specific
type; e.g. @code{number?} tells you if the argument is a number.
Since types are first-class in Gauche, we have predicates that can tell
an object is of a @emph{given} type, as well as predicates to ask
the relationship between types.
@c JP
「型述語」は、与えられたオブジェクトが特定の型を持つかどうかを判定する述語です。
例えば@code{number?}は引数が数値かどうかを返します。
Gaucheでは型がファーストクラスなので、もう一歩進めて、
オブジェクトが@emph{与えられた}型を持つかどうかを判定する述語や、
型同士の関係を調べる述語が提供されています。
@c COMMON

@defun is-a? obj class
@c EN
This is a prescriptive types predicate.
Returns true iff @var{obj} is an instance of @var{class} or an instance
of descendants of @var{class}.
@c JP
これは規範的な型に関する述語です。
@var{obj}が@var{class}のインスタンスであるか、@var{class}のサブクラスの
インスタンスである場合に、真を返します。
@c COMMON

@example
(is-a? 3 <integer>)   @result{} #t
(is-a? 3 <real>)      @result{} #t
(is-a? 5+3i <real>)   @result{} #f
@end example

@c EN
Note: If @var{obj}'s class has been redefined, @code{is-a?} also
triggers instance update.
See @ref{Class redefinition} for the details.
@c JP
註：@var{obj}のクラスが再定義されていた場合、@code{is-a?}はインスタンスアップデートを
トリガします。@ref{Class redefinition}を参照してください。
@c COMMON
@end defun

@defun of-type? obj type
@c EN
This is a descriptie type predicate.
Returns true iff @var{obj} satisfies the constraints described by @var{type},
which can be either a class (in that case, this is the same as @code{is-a?}),
or a descriptive type (@pxref{Type expressions and type constructors} below).
@c JP
これは記述的な型を調べる述語です。
@var{obj}が@var{type}で記述される制約を満たすなら@code{#t}を、そうでなければ@code{#f}を
返します。@var{type}はクラスか(その場合は@code{is-a?}と同じです)、
記述型 (@pxref{Type expressions and type constructors}参照) です。
@c COMMON

@example
(of-type? 1   (</> <number> <string>)) @result{} #t
(of-type? "a" (</> <number> <string>)) @result{} #t
(of-type? 'a  (</> <number> <string>)) @result{} #f
@end example
@end defun

@defun subtype? sub super
@c EN
Returns @code{#t} if a type @var{sub} is a subtype of a type @var{super}
(includes the case that @var{sub} is @var{super}).
Otherwise, returns @code{#f}.
@c JP
型@var{sub}が型@var{super}のサブタイプであれば(@var{sub}と@var{super}が
同じである場合も含め)@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON

@c EN
In general, if @var{sub} is a subtype of @var{super}, an object that satisfies
the constraints of @var{sub} also satisfies the constraints of @var{super},
so you can use the object where objects of type @var{super} are expected.
In other words, @var{sub} is more restrictive than @var{super}.
If both @var{sub} and @var{super} are classes, @var{sub} being a subtype
of @var{super} means @var{sub} is a subclass of @var{super}.
@c JP
一般的に、@var{sub}が@var{super}のサブタイプであれば、
@var{sub}の制約を満たすオブジェクトは@var{super}が期待されている箇所で使うことが
できます。言い換えれば、@var{sub}の制約の方が@var{super}よりきついということです。
@var{sub}と@var{super}のどちらもがクラスの場合、@var{sub}が@var{super}の
サブタイプであるということは、@var{sub}が@var{super}のサブクラスであるということです。
@c COMMON

@example
(subtype? <integer> <real>) @result{} #t
(subtype? <char> (</> <char> <string>)) @result{} #t
(subtype? (</> <integer> <string>) (</> <number> <string>)) @result{} #t
@end example

@c EN
Note that we're not rigorous on this ``substitution principle'',
for we don't aim at guaranteeing type safety through static analysis.
For example, ``list of integers'' can be used in place of a generic list
most of the time, and @code{(subtype? (<List> <integer>) <list>)} is
@code{#t}.  However, if list is mutated, you can't replace
generic list with a list of integers---because mutators may try to
set non-integer in the list.   That kind of cases needs to be handled
separately, not on relying solely on @code{subtype?}.
@c JP
この「置換原則」は常に厳密に成り立つわけではないことに注意してください。
例えば「整数のリスト」は大抵の場合、ジェネリックなリストが期待されているところに
使えて、従って@code{(subtype? (<List> <integer>) <list>)}も@code{#t}を
返します。しかし、渡されたリストが変更される場合は、ジェネリックなリストを
整数のリストで置き換え可能とは限りません。コードはリストに整数でないものをセットしようとする
かもしれないからです。こういったケースは@code{subtype?}に頼るのではなく
個別に対応する必要があります。
@c COMMON
@end defun

@defun type? obj
@c EN
Returns @code{#t} if @var{obj} is a type (either a class or a descriptive
type), @code{#f} otherwise.

You can pass objects that returns @code{#t} for this predicate
to the second argument of @code{of-type?}, and the first or second argument
of @code{subtype?}.
@c JP
@var{obj}が型(クラスまたは記述型)であれば@code{#t}を、
そうでなければ@code{#f}を返します。

この述語が真を返すオブジェクトは、@code{of-type?}の第二引数、
もしくは@code{subtype?}の引数に渡せます。
@c COMMON
@end defun


@defun subclass? sub super
@c EN
Both arguments must be classes.  Returns @code{#t} iff @var{sub} is
a subclass of @var{super}.  A class is regarded as a subclass of
itself.
@c JP
引数はどちらもクラスでなければなりません。
@var{sub}が@var{super}のサブクラスであれば@code{#t}を、そうでなければ@code{#f}を
返します。クラスはそれ自身のサブクラスとみなされます。
@c COMMON
@end defun


@node Predefined classes, Type expressions and type constructors, Generic type predicates, Types and classes
@subsection Predefined classes
@c NODE 定義済みクラス

@c EN
We'll introduce classes for each built-in type as we go through
this chapter.  Here are a few basic classes to start with:
@c JP
組み込みの型に対応するクラスについては、この章の中で順に紹介してゆきます。
まずは次のいくつかのクラスから始めましょう。
@c COMMON

@deftp {Builtin Class} <top>
@clindex top
@c EN
This class represents the supertype of all the types in Gauche.
That is, for any class @code{X}, @code{(subtype? X <top>)} is @code{#t},
and for any object @code{x}, @code{(is-a? x <top>)} is @code{#t}.
@c JP
全ての型のスーパータイプを表現するクラスです。
つまり、どんなクラス@code{X}に対しても@code{(subtype? X <top>)}は@code{#t}であり、
どんなオブジェクト@code{x}に対しても@code{(is-a? x <top>)}は@code{#t}です。
@c COMMON
@end deftp

@deftp {Builtin Class} <bottom>
@clindex bottom
@c EN
This class represents the subtype of all the types in Gauche.
For any class @code{X}, @code{(subtype? <bottom> X)} is @code{#t},
and for any object @code{x}, @code{(is-a? x <bottom>)} is @code{#f}.
@c JP
全ての型のサブタイプを表現するクラスです。
どんなクラス@code{X}に対しても@code{(subtype? <bottom> X)}は@code{#t}であり、
どんなオブジェクト@code{x}に対しても@code{(is-a? x <bottom>)}は@code{#f}です。
@c COMMON

@c EN
There's no instance of @code{<bottom>}.
@c JP
@code{<bottom>}型のインスタンスは存在しません。
@c COMMON

@c EN
Note: Although @code{<bottom>} is subtype of other types,
the class precedence list (CPL) of @code{<bottom>} only contains
@code{<bottom>} and @code{<top>}.  It's because it isn't
always possible to calculate a linear list of all the types.
Even if it is possible, it would be expensive to check and update the
CPL of @code{<bottom>} every time a new class is defined or
an existing class is redefined.   Procedures @code{subtype?} and
@code{is-a?} treat @code{<bottom>} specially.

One of use case of @code{<bottom>} is @code{applicable?} procedure.
@xref{Procedure class and applicability}.
@c JP
註: @code{<bottom>}は全ての型のサブタイプですが、そのクラス順位リスト
(class precedence list, CPL)には@code{<bottom>}と@code{<top>}
以外のクラスは含まれていません。全ての型を線形に並べることは常に可能である
とは限らず、まだそうであったとしても新たなクラスの定義や既存のクラスの
再定義のたびに@code{<bottom>}のCPLを検査してアップデートすることは
高くつくでしょう。@code{subtype?}や@code{is-a?}といった手続きは
@code{<bottom>}を特別扱いしています。

@code{<bottom>}の使いどころのひとつは、@code{applicable?}手続きです。
@ref{Procedure class and applicability}を参照のこと。
@c COMMON
@end deftp

@deftp {Builtin Class} <object>
@clindex object
@c EN
This class represents a supertype of all user-defined classes.
@c JP
このクラスは、ユーザ定義されたクラスのスーパータイプを表現するクラスです。
@c COMMON
@end deftp

@defun class-of obj
@c EN
Returns a class metaobject of @var{obj}.
@c JP
@var{obj}のクラスを返します。
@c COMMON

@example
(class-of 3)         @result{} #<class <integer>>
(class-of "foo")     @result{} #<class <string>>
(class-of <integer>) @result{} #<class <class>>
@end example

@c EN
Note: In Gauche, you can redefine existing user-defined classes.
If the new definition has different configuration of the instance,
@code{class-of} on existing instance triggers instance updates;
@pxref{Class redefinition} for the details.  Using
@code{current-class-of} suppresses instance updates
(@pxref{Accessing instance}).
@c JP
註: Gaucheでは、ユーザ定義クラスを再定義することができます。
新たな定義でインスタンスの構造が変更された場合、以前のクラスから作られた
インスタンスに@code{class-of}を適用すると、インスタンスが新しいクラスに
適合するようにアップデートされます。詳しくは@ref{Class redefinition}を参照して
ください。インスタンスアップデートを避けるには@code{current-class-of}を
使います(@ref{Accessing instance}参照)。
@c COMMON
@end defun

@node Type expressions and type constructors, Native types, Predefined classes, Types and classes
@subsection Type expressions and type constructors
@c NODE 型の式と型コンストラクタ

@c EN
Types are first-class objects manipulatable at runtime in Gauche,
but they must be known at compile-time
in order to do optimizations or static analysis.  In certain places,
Gauche requires the the value of type-yielding expressions to be statically
computable.  We call such expressions @emph{type expressions}.
@c JP
型はGaucheでは実行時に扱える第一級のオブジェクトですが、
静的解析のためにはコンパイル時に型がわかる必要があります。
なので、いくつかの場所では、型を生成する式の値が静的に計算可能であることが要求されます。
そのような式を「型の式 (type expression)」と呼びます。
@c COMMON

@c EN
A type expression is either a global variable reference that are
constantly bound to a type, or a call of type constructor:
@c JP
型の式は、型に静的に束縛されたグローバル変数か、型コンストラクタの呼び出しです:
@c COMMON

@example
<type-expression> : <global-variable-constantly-bound-to-a-type>
                  | <type-constructor-call>

<type-constructor-call> : (<type-constructor> <type-constructor-argument> ...)

<type-constructor-argument> : <type-expression>
                            | <integer-constant>
                            | ->
                            | *
@end example

@c EN
All built-in classes, such as @code{<integer>}, are statically bound
(in precise terms, they are ``inlinable'' binding).  If you try to alter
it, a warning is issued, and the further bahvior will be undefined.
In future, we'll make it an error to alter the binding of
global variables bount to types.  Classes defined with @code{define-class} and
@code{define-record-type} are also bound as inlinable.
@c JP
@code{<integer>}のような全ての組み込みクラスは静的に束縛されています
(正確には、「インライン可能な」束縛になっています)。
そのような束縛を変更しようとすると警告が出され、それ以降の動作は保証されません。
将来的には、型に静的に束縛された変数を変更するのはエラーにするつもりです。
@code{define-class}や@code{define-record-type}で定義されるクラスも、
インライン可能な束縛になります。
@c COMMON

@c EN
Type constructors are special classes whose instances are
descriptive types.  Type constructors can be invoked as if they are
a procedure, but <type-constructor-call> above is recognized by
the compiler and the derived type is computed at compile-time.
So, at runtime you only see the resulting derived type instance.
@c JP
型コンストラクタはそれ自身がクラスで、
そのインスタンスが記述的な型オブジェクトになるものです。
型コンストラクタは構文的には手続き呼び出しのように使えますが、
上の<type-constructor-call>はコンパイラによって認識され、
コンパイル時に計算されて型オブジェクトになります。
なので、ランタイムには結果の型オブジェクトしか見えません。
@c COMMON

@c EN
For example, @code{<?>} is a type constructor that creates
``maybe''-like type, e.g. ``an integer or @code{#f}''.
(Do not confuse this with Maybe type
defined in SRFI-189, @pxref{Maybe and Either optional container types}).
A type expression @code{(<?> <integer>)} yields such type
(printed as @code{#<? <integer>>}):
@c JP
例えば、@code{<?>}は''maybe''のようなオプショナルな型を作る型コンストラクタです。
@code{(<?> <integer>)}は「@code{<integer>}か@code{#f}」を意味します
(SRFI-189 (@ref{Maybe and Either optional container types}参照) の
Maybe型と混同しないようにしてください)。
この型オブジェクトは @code{#<? <integer>>} と表示されます。
@c COMMON

@example
(<?> <integer>) @result{} #<? <integer>>
@end example

@c EN
It looks like a procedure call, but it s computed at compile time:
@c JP
型コンストラクタの呼び出しは手続き呼び出しのように見えますが、コンパイル時に計算されます。
@c COMMON

@example
gosh> (disasm (^[] (<?> <integer>)))
CLOSURE #<closure (#f)>
=== main_code (name=#f, cc=0x7f5cd76ab540, codevec=...):
signatureInfo: ((#f))
     0 CONST-RET #<? <integer>>
@end example

@deftp {Type Constructor} <?> type
@clindex ?
@c EN
@var{Type} must be a type expression.
This creates a maybe-like type, that is, the object is either
of @var{type} or @code{#f}.   Usually, @code{#f} indicates
that the value is invalid (e.g. the return value of @code{assoc}).
@c JP
@var{type}は型の式でなければなりません。
この型の式はmaybe型に似た型を作ります。オブジェクトは型@var{type}を持つか@code{#f}です。
@code{#f}は通常、それが無効な値であることを示します
(例: @code{assoc}の戻り値)。
@c COMMON

@c EN
This type has ambiguity when @code{#f} can be a meaningful value, but
traditionally been used a lot in Scheme, for it is lightweight.
We also have a ``proper'' Maybe type in SRFI-189
(@pxref{Maybe and Either optional container types}) but that involves
extra allocation to wrap the value.
@c JP
この型は、@code{#f}が意味を担う場合に曖昧性があるのですが、
軽量であるゆえにSchemeでは伝統的に多用されてきました。
「正しい」MaybeについてはSRFI-189 (@ref{Maybe and Either optional container types}参照)
により提供されているのですが、値をラップするごとに新たなアロケーションを必要とします。
@c COMMON

@c EN
So, those who came from functional programming may find this isn't
a right abstraction, but it has its place in the Scheme world.
@c JP
関数型言語から来た人には、これは正しい抽象化には見えないかもしれませんが、
Scheme界の中ではそれなりに実用的な型です。
@c COMMON
@end deftp

@deftp {Type Constructor} </> type @dots{}
@clindex /
@c EN
@var{Type} @dots{} must be type expressions.
This creates a @emph{union type} of @var{type} @dots{}.
For example, @code{(</> <string> <symbol>)} is a type that is
either a string or a symbol.
@c JP
@var{type} @dots{} はそれぞれ型の式でなければなりません。
この型コンストラクタは、@var{type} @dots{} のユニオン型を作ります。
例えば@code{(</> <string> <symbol>)}は文字列かシンボルであるような型を表します。
@c COMMON
@end deftp

@deftp {Type Constructor} <Tuple> type @dots{}
@clindex Tuple
@c EN
@var{Type} @dots{} must be type expressions, except that the
last argument that may be an identifier @code{*}.
This creates a @emph{product type} of @var{type} @dots{}.
@c JP
@var{type} @dots{}はそれぞれ型の式でなければなりません。
ただ、最後の要素にはシンボル@code{*}も許されます。
この型コンストラクタは、@var{type} @dots{} の直積型を作ります。
@c COMMON

@c EN
Actually, this type is looser than the product types in typical
statically-typed languages.  Our tuple is a subtype of list, with
types of each positional element are restricted with @var{type} @dots{}.
For example, @code{(<Tuple> <integer> <string>)} is a list of two
elements, the first one being an integer and the second being a string.
@c JP
実のところ、これは静的型付け言語の直積型よりも緩い型です。
Gaucheではタプルはリストのサブタイプで、リストの各位置の要素が
対応する@var{type}で制約されているものです。
例えば@code{(<Tuple> <integer> <string>)}は2要素のリストで、
最初が整数、次が文字列であるようなものを表します。
@c COMMON

@example
(of-type? '(3 "abc") (<Tuple> <integer> <string>)) @result{} #t
@end example

@c EN
If you need a more strict and disjoint product type, you can just create
a class or a record.
@c JP
より厳密な、他の型とは別であるような直積型が必要なら、クラスやレコードを作ってください。
@c COMMON

@c EN
If the last argument is @code{*}, the resulting type allows
extra elements after the typed elements.
@c JP
最後の要素が@code{*}である場合、結果の型は、
型が指定された要素のあとに任意個の要素を許します。
@c COMMON

@example
(of-type? '(3 "abc" 1 2) (<Tuple> <integer> <string> *)) @result{} #t
@end example
@end deftp

@deftp {Type Constructor} <^> type @dots{} @code{->} type @dots{}
@clindex ^
@c EN
Each @var{type} must be type expressions, except that the
one right before @code{->} and the last one may be an identifier @code{*}.

This creates a procedure type, with the constraints in
arguments and return types.
The @var{type} @dots{} before @code{->} are the argument types,
and the ones after @code{->} are the result types.
@c JP
@var{type} @dots{} はそれぞれ型の式でなければなりません。ただし、
@code{->} の直前、および最後の@var{type}は識別子@code{*}も許されます。

この型コンストラクタは引数および戻り値の型を制約する手続き型を作ります。
@code{->} の前の@var{type} @dots{} は引数の型を、
@code{->} の後のは戻り値の型を指定します。
@c COMMON

@c EN
The @code{*} in the last of argument type list and/or result type list
indicates extra elements are allowed.
@c JP
引数の型リストの最後に@code{*}がある場合は省略可能な追加の引数を、
戻り値の型リストの最後に@code{*}がある場合は追加の戻り値があることを示します。
@c COMMON

@c EN
In vanilla Scheme, all procedures belong to just one type, that responds
true to @code{procedure?}.  It is simple and flexible, but sometimes the
resolution is too coarse to do reasoning on the program.
@c JP
素のSchemeでは、全ての手続きは(@code{procedure?}が真を返すという意味で)
ひとつの型に属しています。これは簡単で柔軟ですが、
プログラムの解析をしたい場合には粗すぎる分類です。
@c COMMON

@c EN
In Gauche, we can attach more detailed type information in procedures.
In the current version, some built-in procedures already have such
type information, that can be retrieved with @code{procedure-type}:
@c JP
Gaucheでは手続きオブジェクトがより詳しい型情報を持てます。
現在のバージョンでは、組み込み手続きの一部に既に詳しい型情報が付加されていて、
@code{procedure-type}によって取り出すことができます。
@c COMMON

@example
(procedure-type cons) @result{} #<^ <top> <top> -> <pair>>
@end example

@c EN
Not all procedures have such information, though.  Do not expect the
rigorousness of statically typed languages.
@c JP
ただ、全ての手続きにこの情報が付加されているわけではありません。
静的型付け言語のような厳密さを期待しないでください。
@c COMMON

@c EN
At this moment, Scheme-defined procedures treats all argument types
as @code{<top>}.  We'll provide a way to attach type info in future.
@c JP
今のところ、Schemeで定義された手続きは全ての引数や戻り値を@code{<top>}型として
扱います。いずれより詳しい型情報を指定できるようにする予定です。
@c COMMON
@end deftp

@deftp {Type Constructor} <List> type :optional min-length max-length
@deftpx {Type Constructor} <Vector> type :optional min-length max-length
@clindex List
@clindex Vector
@c EN
@var{Type} must be a type expression.

These create a list or a vector type whose elements are of @var{type},
respectively.
For example, @code{(<List> <string>)} is a list of strings.
@c JP
@var{type}は型の式でなければなりません。

各要素が@var{type}であるようなリストもしくはベクタの型を作ります。
例えば@code{(<List> <string>)}は文字列のリストです。
@c COMMON

@c EN
The optional arguments must be a literal real numbers that limit
the minimum and maximum (inclusive) length of the list or the vector.
When omitted, @var{min-length}
is zero and @var{max-length} is @code{inf.0}.
@c JP
省略可能引数はどちらも実数でなければならず、
それぞれリストやベクタの長さの最小値と最大値(両端含む)を指定します。
省略された場合、@var{min-length}は0、@var{max-length}は無限大です。
@c COMMON

@c EN
Note: @code{subtype?} uses covariant subtyping, that is,
@code{(subtype? (<List> <string>) <list>)} is @code{#t}.
@c JP
註: @code{subtype?}は共変関係を見ます。つまり、
@code{(subtype? (<List> <string>) <list>)}は@code{#t}です。
@c COMMON
@end deftp

@deftp {Type Constructor}  <Assortment> constant @dots{}
@clindex Assortment
@c EN
@var{Constants} must be an expression that evaluates to a symbol,
a boolean or a number, at the compile time.  This type expression
creates a type whose instances are limited to the given constant values.
@c JP
@var{constants}はコンパイル時にシンボル、真偽値、あるいは数値に評価される式でなければなりません。
この型の式は、与えられた定数のみをインスタンスとみなす記述型を作ります。
@c COMMON

@example
(define (p obj)
  (of-type? obj (<Assortment> 'one 'two 'three)))

(p 'one)   @result{} #t
(p 'three) @result{} #t
(p 'four)  @result{} #f
@end example

@c EN
Mere membership test can be realized simply with a list or a set, but
the construction of assortment type is done in compile-time, and
potentially creates opportunities for optimizations or compile-time
checks.  For example, you can proclaim the argument is only allowed
with certain set of symbols:
@c JP
単なるメンバシップの検査ならリストやセットでもできますが、
assortment型の生成はコンパイル時に行われ、
最適化やコンパイル時検査の機会を増やします。
例えば、引数が特定のシンボルのいずれかしか取らないことを、次のような形で
宣言しておくことができるでしょう。
@c COMMON

@example
(define (p obj)
  (assume-type obj (<Assortment> 'one 'two 'three))
  ...)
@end example

@c EN
Currently, it is only used by a runtime check.  However, in futuer version
of Gauche, the compiler knows the argument @var{obj} must be one of these
symbols, and may use that information for static analysis.
@c JP
現在のところこれは実行時チェックに使われるだけですが、
将来のGaucheではコンパイラが、引数はこれらのシンボルしか許されないという情報を
静的解析に利用するかもしれません。
@c COMMON
@end deftp


@node Native types,  , Type expressions and type constructors, Types and classes
@subsection Native types
@c NODE ネイティブタイプ

@c EN
Native types are a set of predefined descriptive types that bridge
Scheme types and C types.  They can be used to access binary blobs
passed from a foreign functions, for example.
@c JP
ネイティブタイプは、Schemeの型とCの型の橋渡しをするためにあらかじめ定義されている型です。
外部の関数から渡されたバイナリデータの中身にアクセスする時などに使えます。
@c COMMON

@c EN
The core library only defines basic numeric types, which are used internally.
The complehensive support of native types is provided by
@code{gauche.native-type}.  @xref{Native type utilities}, for the details.
@c JP
コアライブラリでは、内部的にも使われるごく基本的な数値型のみが定義されています。
ネイティブタイプの完全なサポートは@code{gauche.native-type}モジュールで
提供されます。詳しくは@ref{Native type utilities}を参照してください。
@c COMMON

@c EN
An example of native types is @code{<int16>}, which corresponds to
C's @code{int16_t}.  You can use @code{<int16>} to check if a Scheme
object can be treated as that type:
@c JP
ネイティブタイプの一例は@code{<int16>}です。これはCの@code{int16_t}に相当します。
例えばCの@code{int16_t}としてSchemeオブジェクトを渡せるかどうかを
次のとおり検査できます。
@c COMMON

@example
(of-type? 357 <int16>)   @result{} #t
(of-type? 50000 <int16>) @result{} #f
@end example

@c EN
Or obtain size and alignment info on the running platform:
@c JP
また、実行中のプラットフォームにおけるその型のデータの大きさやアラインメントを知ることもできます。
@c COMMON

@example
gosh> (describe <int16>)
#<native-type <int16>> is an instance of class <native-type>
slots:
  name      : <int16>
  super     : #<class <integer>>
  c-type-name: "int16_t"
  size      : 2
  alignment : 2
@end example

@deftp {Native type} <fixnum>
@deftpx {Native type} <int>
@deftpx {Native type} <int8>
@deftpx {Native type} <int16>
@deftpx {Native type} <int32>
@deftpx {Native type} <int64>
@deftpx {Native type} <short>
@deftpx {Native type} <long>
@deftpx {Native type} <uint>
@deftpx {Native type} <uint8>
@deftpx {Native type} <uint16>
@deftpx {Native type} <uint32>
@deftpx {Native type} <uint64>
@deftpx {Native type} <ushort>
@deftpx {Native type} <ulong>
@deftpx {Native type} <float>
@deftpx {Native type} <double>
@deftpx {Native type} <size_t>
@deftpx {Native type} <ssize_t>
@deftpx {Native type} <ptrdiff_t>
@deftpx {Native type} <off_t>
@deftpx {Native type} <void>
@clindex fixnum
@clindex int
@clindex int8
@clindex int16
@clindex int32
@clindex int64
@clindex short
@clindex long
@clindex uint
@clindex uint8
@clindex uint16
@clindex uint32
@clindex uint64
@clindex ushort
@clindex ulong
@clindex float
@clindex double
@clindex size_t
@clindex ssize_t
@clindex ptrdiff_t
@clindex off_t
@clindex void
@c EN
Predefined native types.  The correspondence of Scheme and C types
are shown below:
@c JP
定義済みのネイティブタイプです。
Cの型との関係は次の表のとおりです。
@c COMMON

@example
Native type  Scheme       C            Notes
-----------------------------------------------------------------
<fixnum>     <integer>    ScmSmallInt  Integers within fixnum range

<int>        <integer>    int          Integers representable in C
<int8>       <integer>    int8_t
<int16>      <integer>    int16_t
<int32>      <integer>    int32_t
<int64>      <integer>    int64_t
<short>      <integer>    short
<long>       <integer>    long
<uint>       <integer>    uint         Integers representable in C
<uint8>      <integer>    uint8_t
<uint16>     <integer>    uint16_t
<uint32>     <integer>    uint32_t
<uint6r>     <integer>    uint64_t
<ushort>     <integer>    ushort
<ulong>      <integer>    ulong
<float>      <real>       float        Unboxed value casted to float
<double>     <real>       double

<size_t>     <integer>    size_t       System-dependent types
<ssize_t>    <integer>    ssize_t
<ptrdiff_t>  <integer>    ptrdiff_t
<off_t>      <integer>    off_t

<void>       -            void        (Used only as a return type.
                                        Scheme function returns #<undef>)
@end example

@c EN
@xref{Native type utilities}, for more complex types such as arrays
and structs.
@c JP
配列や構造体など、より複雑なネイティブタイプについては
@ref{Native type utilities}を参照してください。
@c COMMON
@end deftp


@node Equality and comparison, Numbers, Types and classes, Core library
@section Equality and comparison
@c NODE 等価性と比較

@c EN
Comparing two objects seems trivial, but if you look into deeper,
there are lots of subtleties hidden in the corners.  What should it
mean if two procedures are equal to each other?  How to order two
complex numbers?  It all depends on your purpose; there's no single
generic answer.  So Scheme (and Gauche) provides several options,
as well as the way to make your own.
@c JP
ふたつのオブジェクトを比較するというのは簡単な話のように思えるかもしれません。
しかし詳しく見てゆくと、一筋縄ではいかない特別なケースが出てきます。
ふたつの手続きが等しいとはどういうことでしょうか。
複素数を何らかの基準で順番に並べるにはどうすばいいでしょう。
一般的な回答は無く、目的によるとしか言えません。
そこで、Schemeでは(Gaucheも)、いくつかの選択肢を用意しておき、
さらに必要ならばユーザが独自の定義を与えることもできるようにしています。
@c COMMON

@menu
* Equality::
* Comparison::
* Hashing::
* Basic comparators::
@end menu

@node Equality, Comparison, Equality and comparison, Equality and comparison
@subsection Equality
@c NODE 等価

@c EN
Scheme has three different general equality test predicates.
Other than these, some types have their own comparison predicates.
@c JP
Schemeには等価性を判定する汎用的な述語が3つあります。
また、これらの他に、いくつかの型はその型同士で使える比較手続きを持っています。
@c COMMON

@defun eq? obj1 obj2
[R7RS base]
@c EN
This is the fastest and finest predicate.
Returns @code{#t} if @var{obj1} and @var{obj2} are identical
objects---that is, if they represents the same object on memory
or in a register.  Notably, you can compare two symbols or two keywords with
@code{eq?} to check if they are the same or not.
You can think @code{eq?} as a pointer comparison for
any heap-allocated objects.

Booleans can be compared with @code{eq?}, but you can't
compare characters and numbers reliably---objects with the same
numerical value may or may not @code{eq?} to each other.
If you identity comparison needs to include those objects,
use @code{eqv?} below.
@c JP
最も高速で、細かい区別ができる述語です。
@var{obj1}と@var{obj2}が同一(identical)のオブジェクト、
すなわち、メモリ上の同じオブジェクトを表している場合に@code{#t}を返します。
特に、二つのシンボルもしくは二つのキーワードが同一かどうかを比較するのに@code{eq?}が使えます。
ヒープアロケートされるオブジェクトに対しては、ポインタ比較と考えても良いでしょう。

真偽値も@code{eq?}で比較できますが、文字と数値はたとえ値が同じオブジェクトであっても
互いに@code{eq?}になるかどうかはわかりません。
同一性比較で文字や数値も扱う必要がある場合は、下の@code{eqv?}を使いましょう。
@c COMMON

@example
(eq? #t #t)               @result{} #t
(eq? #t #f)               @result{} #f
(eq? 'a 'a)               @result{} #t
(eq? 'a 'b)               @result{} #f
(eq? (list 'a) (list 'a)) @result{} #f
(let ((x (list 'a)))
  (eq? x x))              @result{} #t
@end example
@end defun

@defun eqv? obj1 obj2
[R7RS base]
@c EN
When @var{obj1} and @var{obj2} are both exact or both inexact numbers
(except NaN or -0.0),
@code{eqv?} returns @code{#t} iff @code{(= @var{obj1} @var{obj2})} is true.
-0.0 is only @code{eqv?} to -0.0.
@c JP
@var{obj1}と@var{obj2}がともに正確な数値、もしくはともに
(NaN、-0.0以外の)非正確な数値である場合、
@code{(= @var{obj1} @var{obj2})}が真であれば@code{#t}が、偽であれば@code{#f}が
返されます。
-0.0は-0.0とだけ@code{eqv?}です。
@c COMMON

@c EN
When @var{obj1} and @var{obj2} are both characters,
@code{eqv?} returns @code{#t} iff @code{(char=? @var{obj1} @var{obj2})} is true.
Otherwise, @code{eqv?} is the same as @code{eq?} on Gauche.
@c JP
@var{obj1}と@var{obj2}がともに文字である場合、
@code{(char=? @var{obj1} @var{obj2})}が真であれば@code{#t}が、偽であれば@code{#f}が
返されます。
それ以外の場合は、Gaucheでは@code{eqv?}は@code{eq?}と同じです。
@c COMMON

@example
(eqv? #\a #\a)             @result{} #t
(eqv? #\a #\b)             @result{} #f
(eqv? 1.0 1.0)             @result{} #t
(eqv? 1 1)                 @result{} #t
(eqv? 1 1.0)               @result{} #f
(eqv? (list 'a) (list 'a)) @result{} #f
(let ((x (list 'a)))
  (eqv? x x))              @result{} #t
@end example

@c EN
Note that comparison of NaNs has some peculiarity.
Any numeric comparison fails if there's at least one NaN in its argument.
Therefore, @code{(= +nan.0 +nan.0)} is always @code{#f}.   However,
Gauche @emph{may} return @code{#t} for @code{(eq? +nan.0 +nan.0)}
or @code{(eqv? +nan.0 +nan.0)}.
@c JP
NaNの比較には少々奇妙なところがあります。数値比較は、引数に一つでもNaNが
含まれていれば失敗します。したがって@code{(= +nan.0 +nan.0)}は常に@code{#f}と
なります。けれども、@code{(eq? +nan.0 +nan.0)} や
@code{(eqv? +nan.0 +nan.0)}は@code{#t}を返すことがあるかもしれません。
@c COMMON
@end defun

@defun equal? obj1 obj2
[R7RS+ base]
@c EN
If @var{obj1} and @var{obj2} are both aggregate types,
@code{equal?} compares its elements recursively.
Otherwise, @code{equal?} behaves the same as @code{eqv?}.

If @var{obj1} and @var{obj2} are not @code{eqv?} to each other,
not of builtin types, and the class of both
objects are the same, @code{equal?} calls the generic
function @code{object-equal?}.
By defining the method, users can extend the behavior of @code{equal?}
for user-defined classes.
@c JP
@var{obj1}と@var{obj2}がリストやベクタなどの複合型である場合、
@code{equal?}は再帰的に対応する要素同士を@code{equal?}で比較してゆきます。
そうでなければ、@code{equal?}は@code{eqv?}と同じようにふるまいます。

もし@code{obj1}と@var{obj2}が互いに@code{eqv?}でなく、
組み込み型でもなく、かつ両者のクラスが等しい場合、@code{equal?}は
ジェネリックファンクション@code{object-equal?}を呼びます。
@code{object-equal?}にメソッドを定義することにより、
ユーザ定義のデータ型に対する@code{equal?}の振るまいを拡張することができます。
@c COMMON

@example
(equal? (list 1 2) (list 1 2)) @result{} #t
(equal? "abc" "abc")           @result{} #t
(equal? 100 100)               @result{} #t
(equal? 100 100.0)             @result{} #f

@c EN
;; 0.0 and -0.0 is numerically equal (=), but eqv? distingushes them, so as equal?.
@c JP
;; 0.0と-0.0は数値としては等しい(=)ですが、eqv?は区別し、したがってequal?も区別します。
@c COMMON
(equal? 0.0 -0.0)              @result{} #f
@end example

@c EN
Note: This procedure correctly handles the case when
both @var{obj1} and @var{obj2} have cycles through pairs and vectors,
as required by R6RS and R7RS.  However, if the cycle involves
user-defined classes, @code{equal?} may fail to terminate.
@c JP
註: この手続きは、@var{obj1}と@var{obj2}がともにペアやベクタを介した
循環構造を持っている場合もR6RSやR7RSに規定されるように値を返します。
ただし、循環構造がユーザ定義データ型を間に挟んでいる場合は
終了しない可能性があります。
@c COMMON
@end defun

@deffn {Generic Function} object-equal? obj1 obj2
@c EN
This generic function is called when @code{equal?} is called on the objects
it doesn't know about.  You can define this method on your class
so that @code{equal?} can check equivalence.   This method is supposed
to return @code{#t} if @var{obj1} is equal to @var{obj2}, @code{#f}
otherwise.  If you want to check equivalence of elements recursively,
do not call @code{object-equal?} directly; call @code{equal?} on each element.
@c JP
@code{equal?}が未知のオブジェクトに対して呼ばれた場合、
このジェネリックファンクションが呼ばれます。自分で定義したクラスに対して
このメソッドを定義することにより、@code{equal?}で等価判定が行えるように
なります。メソッドは、@var{obj1}と@var{obj2}が等価ならば@code{#t}を、
そうでなければ@code{#f}を返さねばなりません。
オブジェクトの各要素に対して再帰的に等価判定を行いたい場合は、
@code{object-equal?}を直接呼ぶのではなく、@code{equal?}を各要素に対して
呼ぶようにして下さい。
@c COMMON

@example
(define-class <foo> ()
  ((x :init-keyword :x)
   (y :init-keyword :y)))

(define-method object-equal? ((a <foo>) (b <foo>))
  (and (equal? (slot-ref a 'x) (slot-ref b 'x))
       (equal? (slot-ref a 'y) (slot-ref b 'y))))

(equal? (make <foo> :x 1 :y (list 'a 'b))
        (make <foo> :x 1 :y (list 'a 'b)))
  @result{} #t

(equal? (make <foo> :x 1 :y (make <foo> :x 3 :y 4))
        (make <foo> :x 1 :y (make <foo> :x 3 :y 4)))
  @result{} #t
@end example
@end deffn

@deffn {Method} object-equal? (obj1 <top>) (obj2 <top>)
@c EN
This method catches @code{equal?} between two objects of a user-defined
class, in case the user doesn't define a specialized method for the class.

When called, it scans the registered default comparators that can handle
both @var{obj1} and @var{obj2},
and if it finds one, use the comparator's equality
predicate to see if two arguments are equal to each other.  When no
matching comparators are found, it just returns @code{#f}.
@xref{Predefined comparators}, about the default comparators:
Look for the entries of
@code{default-comparator} and @code{comparator-register-default!}.

Note: If you define @code{object-equal?} with exactly the same
specializers of this method,
you'll replace it and that breaks
@code{default-comparator} operation.  Future versions of Gauche
will prohibit such redefinition.  For now, be careful not to redefine
it accidentally.
@c JP
このメソッドは、ユーザ定義クラスの2つのインスタンスが@code{equal?}であるかを
調べる際に、そのクラスに特殊化したメソッドが無かった場合を捕まえるものです。

このメソッドが呼ばれると、まず登録されたデフォルト比較器の中に@var{obj1}と
@var{obj2}を共に処理できるものがあるかどうかを調べ、
あればその比較器の等価述語を使って比較します。デフォルト比較器が引数を処理できなければ
@code{#f}を返します。デフォルト比較器については
@ref{Predefined comparators}を参照してください。特に
@code{default-comparator}と@code{comparator-register-default!}の
項目を見てください。

註: もし、このメソッドと全く同じスペシャライザを
指定して@code{object-equal?}メソッドを定義すると、それはこのメソッドを
置き換えることになり、@code{default-comparator}の動作が壊れることになります。
将来のGaucheのバージョンではそのような再定義は禁止される予定です。
うっかりそういう再定義を行わないように気をつけてください。
@c COMMON
@end deffn

@c EN
Sometimes you want to test if two aggregate structures
are topologically equal, i.e., if one has a shared substructure,
the other has a shared substructure in the same way.
@code{Equal?} can't handle it; module @code{util.isomorph}
provides a procedure @code{isomorphic?} which does the job
(@pxref{Determine isomorphism}).
@c JP
しばしば、ふたつの複合型オブジェクトに関して、両者がトポロジー的に等しいこと、
すなわち一方が共有する部分構造を持っている場合にもう一方も同じように部分構造を
共有しているかどうかを調べたいことがあります。@code{equal?}はその目的には
使えません。モジュール@code{util.isomorph}の提供する@code{isomorphic?}が
その目的に使えます。(@ref{Determine isomorphism}参照)。
@c COMMON

@node Comparison, Hashing, Equality, Equality and comparison
@subsection Comparison
@c NODE 比較

@c EN
Equality only concern about whether two objects are equivalent or not.
However, sometimes we want to see the order among objects.  Again,
there's no single ``universal order''.  It doesn't make mathematical
sense to ask if one complex number is greater than another, but
having some artificial order is useful when you want a consistent
result of sorting a list of objects including numbers.
@c JP
等価性はオブジェクトが等しいかどうかしか判断しませんが、しばしば
オブジェクトの順序関係を調べたい場合もあります。
ここでも、唯一の「万能順序」があるわけではありません。例えばある複素数が
別の複素数より大きいか小さいかというのは数学的には意味をなしませんが、
数値を含むオブジェクトのリストをソートして一貫性のある結果を得たい場合は
何らかの適当な順序づけを決めておくことは役に立ちます。
@c COMMON

@defun compare obj1 obj2
@c EN
A general comparison procedure.  Returns -1 if @var{obj1} is less than
@var{obj2}, 0 if @var{obj1} is equal to @var{obj2}, and 1 if @var{obj1}
is greater than @var{obj2}.
@c JP
一般的な比較手続きです。@var{obj1}が@var{obj2}より小さければ-1を、
等しければ0を、大きければ1を返します。
@c COMMON

@c EN
If @var{obj1} and @var{obj2} are incomparable, an error is signalled.
However, @code{compare} defines total order between most Scheme objects,
so that you can use it on wide variety of objects.  The definition is
upper-compatible to the order defined in SRFI-114.
@c JP
@var{obj1}と@var{obj2}が比較できない場合はエラーとなりますが、
@code{compare}は多くのSchemeオブジェクト間に全順序を定義しているので、
様々なオブジェクトの比較に使うことができます。この全順序は、
SRFI-114で定義されているものの上位互換です。
@c COMMON

@c EN
Some built-in types are handled by this procedure reflecting
``natural'' order of comparison if any (e.g. real numbers are compared
by numeric values, characters are compared by @code{char<} etc.)
For convenience,
it also defines superficial order between objects that doesn't have
natural order; complex numbers are ordered first by their real part,
then their imaginary part, for example.  That is,
@code{1+i} comes before @code{2-i},
which comes before @code{2}, which comes before @code{2+i}.
@c JP
組み込みオブジェクトのうち、自然な順序が定義されているものはそれに従って順序づけられます
(例えば実数はその数値の大小で、文字は@code{char<}等を使って比較されます)。
また便宜上、通常の意味で大小が定義されないオブジェクトについても
ある程度表面的な順序が定義されます。例えば複素数は、まず実部の大小によって
順序づけられ、次に虚部の大小によって順序づけられます。
すなわち、@code{1+i}、@code{2-i}、@code{2}、@code{2+i}はこの順番に並びます。
@c COMMON

@c EN
Boolean false comes before boolean true.
@c JP
@code{#f}は@code{#t}より前に来ます。
@c COMMON

@c EN
Lists are ordered by dictionary order: Take the common prefix.
If either one is @code{()} and the other is not, @code{()} comes first.
If both tails are not empty, compare the heads of the tails.
(This makes empty list the ``smallest'' of all lists).
@c JP
リストは辞書順で比較されます。すなわち、まず共通のプリフィクスを除きます。
一方が@code{()}でもう一方がそうでなければ、@code{()}である方が先にきます。
どちらの尾部も空でなければ、尾部の先頭要素同士を比べます。
(この定義により、空リストは全てのリストの「最小」のものになります)。
@c COMMON

@c EN
Note that this definition covers the case when one of either arguments
are infinite list, or the both arguments are circular but have difference
in some of their eleemnts.  The only remaining case, when both are circular
and have the same contents, we regard them equivalent, since @code{equal?}
returns @code{#t} for such lists. The actual topology of two circular
lists may differ.
@c JP
上の定義はまた、リストの一方が循環リストの場合、また両方循環リストであっても
内容が異なる場合をカバーしていることに注意してください。
残るのは両方のリストが循環リストで、内容も同じ場合ですが、それらは等価とみなされます。
@code{equal?}も@code{#t}を返すからです。この場合、両循環リストのトポロジーは
異なっていても構いません。
@c COMMON

@example
(compare '#0=(a . #0#) '#1=(a a . #1#)) @result{} 0
@end example


@c EN
Vectors (including uniform vectors) are compared first by their
lengths, and if they are the same, elements are compared from left to right.
Note that it's different from lists and strings.
@c JP
(ユニフォームベクタを含む)ベクタは、まず長さで比較され、
長さが同じ場合は要素同士が左から比較されます。
リストや文字列とは異なることに注意。
@c COMMON

@example
(compare '(1 2 3) '(1 3))
  @result{} -1  ; (1 2 3) is smaller
(compare '#(1 2 3) '#(1 3))
  @result{} 1   ; #(1 3) is smaller
(compare "123" "13")
  @result{} -1  ; "123" is smaller
@end example

@c EN
If two objects are of subclasses of @code{<object>},
a generic function @code{object-compare} is called.
@c JP
二つのオブジェクトがともに@code{<object>}のサブクラスであれば、
ジェネリックファンクション@code{object-compare}が呼ばれます。
@c COMMON

@c EN
If two objects are of different types and at least one of them
isn't @code{<object>}, then they are ordered by their types.
SRFI-114 defines the order of builtin types as follows:
@c JP
二つのオブジェクトが異なる型で、少なくとも一方が@code{<object>}でない時は、
両者の型により順序が決まります。SRFI-114は組み込み型について
次の順序を定めています。
@c COMMON

@enumerate
@item
Empty list.
@item
Pairs.
@item
Booleans.
@item
Characters.
@item
Strings.
@item
Symbols.
@item
Numbers.
@item
Vectors.
@item
Uniform vectors
(u8 < s8 < u16 < s16 < u32 < s32 < u64 < s64 < f16 < f32 < f64)
@item
@c EN
All other objects.
@c JP
他のオブジェクトすべて
@c COMMON
@end enumerate
@end defun

@deffn {Generic Function} object-compare obj1 obj2
@c EN
Specializing this generic function extends @code{compare} procedure
for user-defined classes.

This method must return either @code{-1} (@var{obj1} precedes @var{obj2}),
@code{0} (@var{obj1} equals to @var{obj2}),
@code{1} (@var{obj1} succeeds @var{obj2}),
or @code{#f} (@var{obj1} and @var{obj2} cannot be ordered).
@c JP
このジェネリックファンクションを特殊化することで
@code{compare}手続きをユーザ定義クラスに対して動作するように拡張できます。

このメソッドは以下のいずれかの値を返さねばなりません。
@code{-1} (@var{obj1}は@var{obj2}より前)、
@code{0} (@var{obj1}と@var{obj2}は等しい)、
@code{1} (@var{obj1}は@var{obj2}より後)、
@code{#f} (@var{obj1}と@var{obj2}は順序づけできない)。
@c COMMON
@end deffn

@deffn {Method} object-compare (obj1 <top>) (obj2 <top>)
@c EN
This method catches @code{compare} between two objects of a
user-defined class, in case the user doesn't define a specialized
method for the class.

When called, it scans the registered default comparators that can
handle both @var{obj1} and @var{obj2},
and if it finds one, use the comparator's compare procedure
to determine the order of @var{obj1} and @var{obj2}.
When no matching comparators are found, it returns @code{#f}, meaning
two objects can't be ordered.
@xref{Predefined comparators}, about the default comparators:
Look for the entries of
@code{default-comparator} and @code{comparator-register-default!}.

Note: If you define @code{object-compare} with exactly the same
specializers of this method,
you'll replace it and that breaks
@code{default-comparator} operation.  Future versions of Gauche
will prohibit such redefinition.  For now, be careful not to redefine
it accidentally.
@c JP
このメソッドは、ユーザ定義クラスの2つのインスタンスを@code{compare}する
際に、そのクラスに特殊化したメソッドが無かった場合を捕まえるものです。

このメソッドが呼ばれると、まず登録されたデフォルト比較器の中に@var{obj1}と
@var{obj2}を共に処理できるものがあるかどうかを調べ、
あればその比較器の比較手続きを使って両者の順序を判定します。
デフォルト比較器が引数を処理できなければ
@code{#f}(「比較できない」)を返します。デフォルト比較器については
@ref{Predefined comparators}を参照してください。特に
@code{default-comparator}と@code{comparator-register-default!}の
項目を見てください。

註: もし、このメソッドと全く同じスペシャライザを
指定して@code{object-compare}メソッドを定義すると、それはこのメソッドを
置き換えることになり、@code{default-comparator}の動作が壊れることになります。
将来のGaucheのバージョンではそのような再定義は禁止される予定です。
うっかりそういう再定義を行わないように気をつけてください。
@c COMMON
@end deffn


@defun eq-compare obj1 obj2
@c EN
Returns -1 (less than), 0 (equal to) or 1 (greater than)
according to a certain total ordering of
@var{obj1} and @var{obj2}.   Both arguments can be any Scheme
objects, and can be different type of objects.
The following properties are guaranteed.

@itemize @bullet
@item
@code{(eq-compare x y)} is 0 iff @code{(eq? x y)} is @code{#t}.
@item
The result is consistent within a single run of the process
(but may differ between runs).
@end itemize

Other than these, no actual semantics are given to the ordering.

This procedure is useful when you need to order arbitrary Scheme
objects, but you don't care the actual order as far as it's consistent.
@c JP
とある全順序に従って@var{obj1}と@var{obj2}を比較し、前者が小さければ-1、
等しければ0、前者が大きければ1を返します。@var{obj1}と@var{obj2}は
どんなSchemeオブジェクトでも良く、また型が違っていても構いません。
次の二つの性質が保証されます。

@itemize @bullet
@item
@code{(eq? x y)}が@code{#t}なら、そしてその時に限り、
@code{(eq-compare x y)}は0。
@item
結果は、一回のプロセスの実行中で一貫している
(ただし、別のプロセスの実行では異なる結果を返すかもしれない)。
@end itemize

これらの性質以外には、順序についていかなる意味もありません。

この手続きは、任意のSchemeオブジェクトをとにかく順序づけたい
(一貫してさえいれば、実際の順序は何でも良い)、という場合に使います。
@c COMMON
@end defun

@node Hashing, Basic comparators, Comparison, Equality and comparison
@subsection Hashing
@c NODE ハッシュ

@c EN
Hash functions have close relationship with equality predicate,
so we list them here.

@c JP
ハッシュ関数は等価判定述語と関係が深いので、ここで説明します。
@c COMMON

@defun eq-hash obj
@defunx eqv-hash obj
@c EN
These are hash functions suitable to be used
with @code{eq?} and @code{eqv?}, respectively.
The returned hash value is system- and process-dependent,
and can't be carried over the boundary of the running process.

Note: don't hash numbers by @code{eq-hash}.  Two numbers
are not guaranteed to be @code{eq?} even if they are numerically equal.
@c JP
この2つはそれぞれ@code{eq?}および @code{eqv?}と一緒に使うのに適した
ハッシュ関数です。返り値のハッシュ値は、
システムおよびプロセスに依存する値です。動作しているプロセスの境界を
超えてもちまわることはできません。

注意: @code{eq-hash} をつかって、数をハッシュしてはいけません。
2つの数はたとえその値が等しくても @code{eq?} であることは保証されて
いません。
@c COMMON
@end defun

@defun default-hash obj
[R7RS+ comparator]
@c EN
This is a hash function suitable to be used with @code{equal?}.
In R7RS, this is defined in @code{scheme.comparator} (originally
in @code{srfi.128}).

If @var{obj} is either a number, a boolean, a character,
a symbol, a keyword, a string, a list, a vector or a uniform vector,
internal hash function is used to calculate the hash value.
If @var{obj} is other than that,
a generic function @code{object-hash} is called to calculate the hash value
(see below).

The hash value also depends on @code{hash-salt}, which differs
for every run of the process.
@c JP
@code{equal?}と一緒に使うのに適したハッシュ関数です。
R7RSでは、@code{scheme.comparator}ライブラリで定義されています
(元は@code{srfi.128})。

@var{obj} が、数値、真理値、文字、シンボル、キーワード、文字列、リスト、
ベクタ、ユニフォームベクタのいずれかならば、そのハッシュ値を求めるのには内部ハッシュ関数を
使います。
@var{obj} が、それ以外であれば、 @code{hash} は総称関数 @code{object-hash}
を呼んで、そのハッシュ値を計算します。

返されるハッシュ値は@code{hash-salt}の値にも依存します。@code{hash-salt}
はプロセスが走る度に異なる値をとります。
@c COMMON
@end defun

@defun portable-hash obj salt
@c EN
Sometimes you need to calculate a hash value that's ``portable'',
in a sense that the value won't change across multiple runs of
the process, nor between different platforms.  Such hash value can
be used with storing objects externally to share among processes.

This procedure calculates a hash value of @var{obj} with such
characteristics; the hash value is the same for the same
object and the same salt value.
Here ``same object'' roughly means having
the same external representation.  Objects @code{equal?} to each
other are same.  If you write out an object with @code{write},
and read it back, they are also the same objects in this sense.

This means objects without read/write invariance, such as
ports, can't be handled with @code{portable-hash}.  It is caller's
responsibility that @var{obj} won't contain such objects.

The @var{salt} argument is a nonnegative fixnum and gives variations
in the hash function.  You have to use the same salt to get consistent
results.

If @var{obj} is other than a number, a boolean, a character,
a symbol, a keyword, a string, a list, a vector, or a uniform vector,
this procedure calls
a generic function @code{object-hash} is called to calculate the hash value
(see below).
@c JP
時に、「ポータブル」なハッシュ値が必要になることがあります。ここでポータブルとは、
プロセスを何度実行しても、また異なるプラットフォームで実行しても、同じオブジェクト
に対して常に同じ値となることです。そのようなハッシュ値は、
プロセスの外に保存したり他のプロセスと共有するオブジェクトと一緒に使えます。

この手続きは@var{obj}についてその性質を持つハッシュ値を計算して返します。
つまり、同じオブジェクトと同じソルト値が渡されれば同じハッシュ値となる、ということです。
ここで、「同じオブジェクト」とは、だいたい外部表現が同じになるものと
考えて構いません。@code{equal?}であるもの同士は同じです。
また、オブジェクトを@code{write}で書き出して@code{read}で読み込んだものは
元のオブジェクトと同じになります。

このことから、read/write不変性をもたないオブジェクトは@code{portable-hash}
では扱えません。@var{obj}がそのようなオブジェクトを含まないことは
呼び出し側で保証する必要があります。

@var{salt}は非負のfixnumで、ハッシュ関数に変化をつけます。一貫した結果を
得るには同じソルト値を使わなければなりません。

@var{obj}が数値、真理値、文字、シンボル、キーワード、文字列、リスト、
ベクタ、ユニフォームベクタのいずれでもない場合、ハッシュ値を計算するのに
総称関数 @code{object-hash}が呼ばれます。
@c COMMON
@end defun

@defun legacy-hash obj
@c EN
Up to 0.9.4, Gauche had a hash function called @code{hash}
that was used in both @code{equal?}-hashtable @emph{and}
for the portable hash function.  It had a problem, though.
@c JP
バージョン0.9.4まで、Gaucheでは@code{hash}と呼ばれるハッシュ関数が
@code{equal?}ハッシュテーブル用のハッシュ計算と
ポータブルなハッシュ値の計算の両方を兼ねていました。
しかしそれには問題がありました。
@c COMMON

@enumerate
@item
@c EN
There was no way to salt the hash function, which makes the
hashtables storing externally provided data vulnerable
to collision attack.
@c JP
ハッシュ関数にソルトを与えることができなかったため、
外部からのデータによる衝突攻撃が可能だった
@c COMMON
@item
@c EN
The hash function behaves poorly, especially on flonums.
@c JP
ハッシュ関数自体があまり良くなかった(特に浮動小数点数)
@c COMMON
@item
@c EN
There are bugs in bignum and flonum hashing code that
have produced different results on different architectures.
@c JP
多倍長整数と浮動小数点数のハッシュ値計算で、
異なるアーキテクチャで異なる値を返してしまうバグがあった。
@c COMMON
@end enumerate

@c EN
Since there are existing hash values calculated with
the old hash function, we preserve the behavior of the
original @code{hash} function as @code{legacy-hash}.
Use this when you need to access old data.
(The @code{hash} function also behaves as @code{legacy-hash}
by default, but it has tweaks; see below.)
@c JP
既に@code{hash}で計算されたハッシュ値を利用しているデータがあるため、
以前の@code{hash}で提供していたハッシュ関数を@code{legacy-hash}として
保存することにしました。古いデータにアクセスする場合に使ってください。
(@code{hash}関数自体もデフォルトでは
@code{legacy-hash}と同様に振る舞いますが、ちょっとした仕掛けがあります。
下の説明を参照)。
@c COMMON

@c EN
The new code that needs portable hash value should use
@code{portable-hash} instead.
@c JP
新たに書くコードでポータブルなハッシュ値が必要なら
@code{portable-hash}を使ってください。
@c COMMON
@end defun

@deffn {Generic Function} object-hash obj rec-hash
@c EN
By defining a method for this generic function, objects of
user-defined types can have a hash value and can be used
in a @code{equal?} hash table.

The method has to return an exact non-negative integer,
and must return the same value for two object which are @code{equal?}.
Furthermore, the returned value must not rely on the platform
or state of the process, if @var{obj} is a portable object
(see @code{portable-hash} above for what is portable.)

If the method needs to get hash value of @var{obj}'s elements,
it has to call @var{rec-hash} on them.  It guarantees that
the proper hash function is called recursively.  So you can
count on @var{rec-hash} to calculate a portable hash value
when @code{object-hash} itself is called from @code{portable-hash}.

If @var{obj} has several elements,
you can call @code{combine-hash-value} on the elements'
hash values.
@c JP
この総称関数に対するメソッドを定義することにより、ユーザ定義された
型のオブジェクトはハッシュ値を持つことができ、@code{equal?}型のハッシュ
テーブルで利用できるようになります。

メソッドは正確な非負整数を返さなければなりません。また、
互いに@code{equal?}であるオブジェクト同士に対しては同じハッシュ値を
返さなければなりません。
さらに、@var{obj}がポータブル(「ポータブル」の意味については
上の@code{portable-hash}の説明を参照)の場合には、
ハッシュ値は実行中のプラットフォームやプロセスの状態に依存してはなりません。

メソッドが @var{obj} の要素のハッシュ値を必要とする場合には、
それらに対して、@var{rec-hash}を呼び出してください。そうすれば
適切なハッシュ関数が再帰的に呼び出されます。例えば@code{object-hash}が
@code{portable-hash}経由で呼び出されている場合、
@var{rec-hash}を呼べば同じソルト値でポータブルなハッシュ値が計算されます。

@var{obj}がいくつかの要素を持っている場合、各要素のハッシュ値を
まとめるには@code{combine-hash-value}を呼びます。
@c COMMON
@example
(define-class <myclass> () (x y))

;; user-defined equality function
(define-method object-equal? ((a <myclass>) (b <myclass>))
  (and (equal? (ref a 'x) (ref b 'x))
       (= (abs (ref a 'y)) (abs (ref b 'y)))))

;; user-defined hash function
(define-method object-hash ((a <myclass>) rec-hash)
  (combine-hash-value (rec-hash (ref a 'x))
                      (rec-hash (abs (ref a 'y)))))
@end example

@c EN
Note: The base method of @code{object-hash} hashes any object
to a single hash value (the actual value depends on @code{hash-salt}
if @code{object-hash} is called from @code{default-hash},
and a fixed constant value otherwise.
It's because object's equality semantics can be customized separately,
and we can't compute a non-constant hash value without knowing the
equality semantics.

This behavior is the last ``safety net''; in general, you should define
@code{object-hash} method on your class if the instances of your class
can ever be hashed.
@c JP
註: @code{object-hash}のベースメソッドは、どんな引数に対しても
単一の値を返します (具体的な値は、@code{object-hash}が
@code{default-hash}から呼ばれた場合は@code{hash-salt}に依存します。
それ以外の場合は固定値です)。
これは、オブジェクトの等価性が自由に設定できるからで、
等価性を知らずに意味のあるハッシュ値を計算できないからです。

この振る舞いは最後の安全ネットと考えるべきで、一般には自分で定義したクラスのインスタンスが
ハッシュされる可能性があるなら、必ず@code{object-hash}メソッドを定義するように
してください。
@c COMMON
@end deffn

@deffn {Method} object-hash (obj <top>) rec-hash
@deffnx {Method} object-hash (obj <top>)
@c EN
These two methods are defined by the system and ensures the
backward compatibility and the behavior of @code{default-comparator}.
@c JP
これら二つのメソッドはシステムで定義されており、
後方互換性および@code{default-comparator}の正しい振る舞いを保証しています。
@c COMMON
@end deffn

@defun combine-hash-value ha hb
@c EN
Returns a hash value which is a combination of two hash
values, @var{ha} and @var{hb}.  The guaranteed invariance
is that if @code{(= ha1 ha2)} and @code{(= hb1 hb2)}
then @code{(= (combine-hash-value ha1 hb1) (combine-hash-value ha2 hb2))}.
This is useful to write user-defined @code{object-hash} method.
@c JP
二つのハッシュ値@var{ha}と@var{hb}を組み合わせたハッシュ値を返します。
次の性質が保証されます：@code{(= ha1 ha2)} かつ @code{(= hb1 hb2)}
ならば @code{(= (combine-hash-value ha1 hb1) (combine-hash-value ha2 hb2))}。
これはユーザ定義の@code{object-hash}メソッドを書くのに便利です。
@c COMMON
@end defun

@defun hash obj
@c DEPRECATED
@c EN
Kept for the backward compatibility.

Calculate a hash value of @var{obj} suitable for @code{equal?} hash.
By default, it returns the same value as @code{legacy-hash}.  However,
if this is called from @code{default-hash} or @code{portable-hash}
(via @code{object-hash} method), it recurses to the calling hash
function.

The behavior is to keep the legacy code work.  Until 0.9.5,
@code{hash} is the only hash function to be used for both portable
hash and @code{equal?}-hash, and @code{object-hash} method takes single
argument (an object to hash) and calls @code{hash} recursively whenever it
needs to get a hash value of other objects pointed from the argument.

As of 0.9.5 we have more than one hash functions that calls
@code{object-hash}, so the method takes the hash function as
the second argument to recurse.  However, we can't just break
the legacy code; so there's a default method defined in
@code{object-hash} which is invoked when no two-arg method
is defined for the given object, and dispatches to one-arg method.
As far as the legacy @code{object-hash}
code calls @code{hash}, it calls proper function.
The new code shouldn't rely on this behavior, and must use
the second argument of @code{object-hash} instead.
@c JP
後方互換性のために残されています。

@code{equal?}ハッシュとして使える、@var{obj}のハッシュ値を返します。
デフォルトでは、この関数は@code{legacy-hash}と同じ値を返します。
しかし、この関数が@code{default-hash}か@code{portable-hash}から
(@code{object-hash}を経由して)呼ばれた場合は、呼び出したハッシュ関数へと
再帰します。

この振る舞いは既存のコードを動かすためのものです。0.9.5より前は、
@code{hash}が、ポータブルなハッシュ値にも@code{equal?}ハッシュテーブルにも
使えるハッシュ値を計算する唯一の関数でした。@code{object-hash}メソッドは
ハッシュ値を計算したいオブジェクトだけを引数に取り、もしそのオブジェクトが
指す他のオブジェクトのハッシュ値が欲しいなら、@code{hash}を再帰呼び出ししていました。

0.9.5から、@code{object-hash}はいくつかのハッシュ関数から呼び出されるようになり、
第2引数に再帰すべきハッシュ関数を取るようになりました。
けれども既存のコードを動かなくしてしまうわけにはいきません。そこで、
@code{object-hash}のデフォルトメソッド(2引数でマッチするメソッドが
無い場合に呼ばれるもの)が、1引数の@code{object-hash}を呼び出すように
定義されています。既存の@code{object-hash}が@code{hash}を呼び出していれば、
正しいハッシュ関数へと再帰するというわけです。
新たに書くコードはこの振る舞いに依存してはいけません。
2引数の@code{object-hash}メソッドを定義してください。
@c COMMON
@end defun


@defun boolean-hash bool
@defunx char-hash char
@defunx char-ci-hash char
@defunx string-hash str
@defunx string-ci-hash str
@defunx symbol-hash sym
@defunx number-hash num
[R7RS comparator]
@c EN
These are hash functions for specific type of objects,
defined in R7RS @code{scheme.comparator}.
In Gauche, these procedures are just a wrapper of @code{default-hash}
with type checks (and case folding when relevant).  These are
mainly provided to conform @code{scheme.comparator}; in your code you might
just want to use @code{default-hash} (or @code{eq-hash}/@code{eqv-hash},
depending on the equality predicate).
@c JP
これらは、R7RSの@code{scheme.comparator}で定義された、
特定の型のオブジェクト専用のハッシュ関数です。
Gaucheでは、これらの関数は単に引数の型チェックをして(必要なら大文字小文字の
区別をなくした後)、組み込みの@code{default-hash}を呼び出しているだけです。
これらは@code{scheme.comparator}で定義されているために提供されていますが、
特にポータビリティが必要でなければ@code{default-hash}
(あるいは、等価述語によっては@code{eq-hash}や
@code{eqv-hash})を呼んでしまう方が簡単だし高速です。
@c COMMON

@c EN
The case-folding versions, @code{char-ci-hash} and
@code{string-ci-hash}, calls @code{char-foldcase} and
@code{string-foldcase} respectively, on the argument before
passing it to @code{hash}.
(@xref{Characters}, for @code{char-foldcase}.
@xref{Full string case conversion}, for @code{string-foldcase}).
@c JP
大文字小文字を区別しない、@code{char-ci-hash}および@code{string-ci-hash}は、
引数にそれぞれ@code{char-foldcase}と@code{string-foldcase}を適用してから
@code{hash}に渡します。
(@code{char-foldcase}については@ref{Characters}を、
@code{string-foldcase}については@ref{Full string case conversion}を
参照してください。)
@c COMMON
@end defun

@defun hash-bound
@defunx hash-salt
[R7RS comparator]
@c EN
Both evaluates to an exact nonnegative integers.  In R7RS,
these are defined in @code{scheme.comparator}.

(Note: @code{scheme.comparator}
defines these as macros, in order to allow
implementations optimize runtime overhead.  In Gauche we use
procedures but the overhead is negligible.)

User-defined hash functions can limit the range of the result between
0 and @code{(hash-bound)}, respectively, without worrying to lose
quality of hash function.  (User-defined hash functions don't need
to honor @code{(hash-bound)} at all; hashtables takes modulo when
necessary.)

User-defined hash function can also take into account of the
value @code{(hash-salt)} into hash calculation; the salt value may
differ between runs of the Scheme processes, or even between
hash table instances.  It is to avoid collision attack.
Built-in hash functions already takes the salt value into account,
so if your hash function is combining the hash values of
primitive types, you don't need to worry about salt values.
@c JP
どちらも、正確な非負整数へと展開されます。R7RSでは、
@code{scheme.comparator}ライブラリで定義されています。

(註: @code{scheme.comparator}はこれらをマクロと定義しています。処理系が
ランタイムオーバヘッドを避けられるようにするためです。
Gaucheでは、呼び出しのオーバヘッドはそれほど問題にならないという
立場から、どちらも手続きにしています。)

ユーザ定義のハッシュ関数は、
結果を0と@code{(hash-bound)}の間に限定してもハッシュの質を落とさないことが
保証されます。(ユーザ定義のハッシュ関数は@code{(hash-bound)}を気にする
必要はありません。ハッシュテーブルが必要な時にモジュロを取ります)。

ユーザ定義のハッシュ関数はまた、@code{(hash-salt)}を計算に組み入れることが
できます。展開されるソルト値は、Schemeプロセスの実行ごとに異なる値を
取ったり、ハッシュテーブルごとに異なる値を取るかもしれません。
これは、コリジョン攻撃を回避するためのものです。
組み込みのハッシュ関数は既にソルト値を考慮しているので、
ユーザ定義ハッシュ関数がプリミティブ型のハッシュ値を組み合わせるだけの
場合は、ソルト値を気にする必要はありません。
@c COMMON
@end defun


@node Basic comparators,  , Hashing, Equality and comparison
@subsection Basic comparators
@c NODE 基本的な比較器

@c EN
Equality and comparison procedures are parameters in various
data structures.   A treemap needs to order its keys;
a hashtable needs to see if the keys are the same or not,
and it also need a hash function consistent with the equality predicate.
@c JP
等価性判定と大小比較は色々なデータ構造のパラメータになっています。
treemapはキーの大小を比較します。ハッシュテーブルはキーが等しいかどうかを調べ、
またハッシュ関数と等価性判定に一貫性が無ければなりません。
@c COMMON

@c EN
If we want to work on generic data structures, we need to abstract those
variations of comparison schemes.  So here comes the comparator,
a record that bundles closely-related comparison procedures together.
@c JP
ジェネリックなデータ構造を作りたければ、こういった比較についてのバリエーションを
抽象化する必要があります。そのために導入されたのが比較器(comparator)です。
これは、比較について関係の深いいくつかの手続きをまとめた構造体です。
@c COMMON

@c EN
There are two SRFIs that define comparators.  The one that was originally
called SRFI-128 has now become a part of R7RS large as
@code{scheme.comparator}, and we recommend new code to use it.
Gauche has all of @code{scheme.comparator}
procedures built-in.  The older, and rather complex one is SRFI-114;
Gauche also supports it mainly for the backward compatibility.
Importantly, Gauche's native @code{<comparator>} object is compatible
to both @code{scheme.comparator} and @code{srfi-114}
comparators.
@c JP
比較器を定義したSRFIは二つあります。SRFI-128と呼ばれていた規格は
R7RS largeに取り込まれ、@code{scheme.comparator}になりました。
新しいコードではそちらを使うべきです。
Gaucheは@code{scheme.comparator}のAPIを全て組み込みで提供します。
古く、より複雑なのがSRFI-114で、Gaucheはそちらは主に後方互換性のために
サポートしています。重要なのは、Gaucheの組み込みの@code{<comparator>}オブジェクトは
@code{scheme.comparator}の比較器としても
SRFI-114の比較器としても使えるということです。
@c COMMON

@menu
* Comparator class and constructors::
* Comparator predicates and accessors::
* Predefined comparators::
* Combining comparators::
@end menu

@node Comparator class and constructors, Comparator predicates and accessors, Basic comparators, Basic comparators
@subsubsection Comparator class and constructors
@c NODE 比較器クラスとコンストラクタ

@deftp {Builtin Class} <comparator>
@c EN
A comparator record that bundles the following procedures:
@c JP
以下の手続きをひとまとめにするレコードです。
@c COMMON

@c EN
@table @emph
@item Type test predicate
Checks if an object can be compared with this comparator.
@item Equality predicate
See if given two objects
are equal to each other; returns a boolean value.
@item Ordering predicate
Compare given two objects, and returns true iff the first one is
strictly precedes the second one.  That is, this is a less-than predicate.
@item Comparison procedure
Compare given two objects, and returns either -1 (the first one is less
than the second), 0 (they are equal), or 1 (the first one is greater
than the second).
@item Hash function
Returns a hash value of the given object.
@end table
@c JP
@table @emph
@item 型検査述語
オブジェクトがこの比較器によって扱えるかどうかを調べます。
@item 等価述語
二つのオブジェクトが等価かどうかを判定し、等価なら@code{#t}を、そうでなければ@code{#f}
を返します。
@item 順序手続き
二つのオブジェクトの大小関係を判定し、
最初のオブジェクトが二つ目のオブジェクトより小さければ@code{#t}を、
そうでなければ@code{#f}を返します。
@item 比較手続き
二つのオブジェクトの大小関係を判定し、
最初のオブジェクトの方が小さければ-1を、
二つが等しければ0を、
最初のオブジェクトの方が大きければ1を返します。
@item ハッシュ関数
オブジェクトのハッシュ値を返します。
@end table
@c COMMON

@c EN
@code{Scheme.comparator}'s
comparators use the ordering predicate,
while SRFI-114 comparators use the comparison procedure.
Gauche's @code{<comparator>} supports both by automatically
generating the missing one; that is, if you create a comparator
with @code{scheme.comparator} interface, by giving an ordering predicate,
Gauche automatically fills the comparison procedure, and
if you create one with SRFI-114 interface by giving a comparison
procedure, Gauche generates the ordering predicate.
@c JP
@code{scheme.comparator}の比較器は順序手続きを使い、
SRFI-114の比較器は比較手続きを使います。
Gaucheの@code{<comparator>}は両方をサポートするために、
自動的に欠けている手続きを補います。
つまり、順序手続きを与えて@code{scheme.comparator}のインタフェースで
比較器を作った場合、Gaucheは自動的に比較手続きを生成しますし、
比較手続きを与えてSRFI-114のインタフェースで比較器を作った場合は
順序手続きが自動生成されます。
@c COMMON

@c EN
A comparator may not have an ordering predicate / comparison procedure,
and/or a hash function.  You can check if the comparator
can be used for ordering or hashing by
@code{comparator-ordered?} and
@code{comparator-hashable?}, respectively.
@c JP
比較器は、順序/比較手続き、ハッシュ関数、あるいはその両方を欠いていることもあります。
比較器が順序づけやハッシュに使えるかどうかは、それぞれ
@code{comparator-ordered?}と
@code{comparator-hashable?}で調べることができます。
@c COMMON

@c EN
Some built-in data types such as hashtables (@pxref{Hashtables})
and treemaps (@pxref{Treemaps}), take a comparator in their constructors.
The sort and merge procedures also accept comparators
(@pxref{Sorting and merging}).
@c JP
Gauche組み込みのデータ型は、コンストラクタで比較器を取ることができます
(例:ハッシュテーブル(@ref{Hashtables}参照)、
ツリーマップ(@ref{Treemaps}参照))。
また、ソートとマージの手続きも比較器を受け取ることができます
(@ref{Sorting and merging}参照。
@c COMMON
@end deftp

@defun make-comparator type-test equal order hash :optional name
[R7RS comparator]
@c EN
Creates a new comparator form the given @var{type-test},
@var{equal}, @var{order} and @var{hash} functions, and returns it.
In R7RS, this is defined in @code{scheme.comparator}

See the description of @code{<comparator>} above for the role of
those procedures.
@c JP
与えられた@var{type-test}、@var{equal}、@var{order}、@var{hash}の
各関数をまとめて、新たな比較器を作って返します。
R7RSではこの関数は@code{scheme.comparator}で定義されています。

各関数の役割については上の@code{<comparator>}の説明を参照してください。
@c COMMON

@c EN
Note: Both @code{scheme.comparator}
and @code{srfi.114} defines @code{make-comparator},
but where @code{scheme.comparator} takes @var{order} argument,
@code{srfi.114} takes @var{compare} argument.
Since @code{scheme.comparator} is preferable, we adopt
it for the built-in interface, and give a different name
(@code{make-comparator/compare}) for SRFI-114 constructor.
@c JP
註: @code{scheme.comparator}と@code{srfi.114}は両方とも
@code{make-comparator}を定義していますが、
@code{scheme.comparator}が@var{order}手続きを取るところで
@code{srfi.114}は@var{compare}手続きを取ります。
@code{scheme.comparator}の方が推奨されるので、
Gaucheでは組み込みの@code{make-comparator}を@code{scheme.comparator}に合わせ、
SRFI-114の方は@code{make-comparator/compare}という名前にしてあります。
@c COMMON

@c EN
Actually, some arguments can be non-procedures, to use predefined
procedures, for the convenience.  Even if non-procedure arguments
are passed, the corresponding accessors (e.g.
@code{comparator-type-test-procedure} for the @code{type-test}
procedure) always return a procedure---either the given one
or the predefined one.
@c JP
各引数は、手続きでなく真偽値を取ることもできます。その場合、既に定義された
手続きが使えるので便利です。但し、引数に真偽値を渡した場合でも、
アクセサは補われた手続きの方を返します。
(例えば@code{type-test}引数に対応するアクセサは
@code{comparator-type-test-procedure}ですが、これは常に手続きを返します。)
@c COMMON

@c EN
The @var{type-test} argument must be either @code{#t} or
a predicate taking one argument to test suitability of
the object for comparing by the resulting comparator.
If it is @code{#t},
a procedure that always return @code{#t} is used.
@c JP
@code{type-test}引数は、@code{#t}もしくは1引数の手続きでなければなりません。
手続きの場合、それは渡されたオブジェクトが比較器の他の手続きに渡せるかどうかを
判定する述語です。@code{#t}の場合、どんなオブジェクトに対しても@code{#t}を
返す手続きが補われます。
@c COMMON

@c EN
The @var{equal} argument must
a predicate taking two arguments to test equality.
@c JP
@var{equal}引数は二つの引数を取りその等価性を判定する
述語でなければなりません。
@c COMMON

@c EN
the @var{order} argument must be either @code{#f} or
a procedure taking two arguments and returning a boolean value.
It must return @code{#t} iff the first argument strictly precedes
the second one.  If @code{#f} is passed, the comparator can not be
used for ordering.
@c JP
@var{order}手続きは@code{#f}もしくは二つの引数を取り真偽値を返す手続きで
なければなりません。手続きの場合、最初の引数が二番目の引数より厳密に手前に
ある場合にのみ@code{#t}を返します。@code{#f}が渡された場合は、
作られる比較器は順序づけには使えません。
@c COMMON

@c EN
The @var{hash} argument must be either @code{#f}, or
a procedure taking one argument and returning nonnegative exact
integer.  If @code{#f} is given, it indicates the comparator
can't hash objects; the predefined procedure just throws an error.
@c JP
@var{hash}引数は@code{#f}か、一つの引数を取り非負の正確な整数をハッシュ値と
して返す手続きでなければなりません。
@code{#f}が渡された場合は、この比較器ではハッシュ値を取れないことを意味します。
この場合、呼ばれたらエラーを投げる手続きが補われます。
@c COMMON

@c EN
The fifth, optional argument @var{name}, is Gauche's extension.
It can be any object but usually a symbol; it is only used when
printing the comparator, to help debugging.
@c JP
最後の、省略可能な引数@var{name}はGaucheの拡張です。
どんなオブジェクトでも構いませんが、通常はシンボルが渡されます。
これは比較器を出力する時に使われるだけですが、デバッグには役に立ちます。
@c COMMON
@end defun

@defun make-comparator/compare type-test equal compare hash :optional name
@c EN
This is SRFI-114 comparator constructor.  In SRFI-114, this is called
@code{make-comparator}.  Avoiding name conflict, we renamed it.
If you @code{(use srfi.114)} you get the original name @code{make-comparator}
(and the built-in @code{make-comparator} is shadowed).
This is provided for the backward
compatibility, and new code should use built-in @code{make-comparator} above.
@c JP
これはSRFI-114比較器のコンストラクタです。SRFI-114ではこれが
@code{make-comparator}と呼ばれていますが、名前の衝突を避けるために別の名前を用意しました。
@code{(use srfi.114)}した場合は、SRFI-114のコンストラクタが元の名前
で使えるようになります(組み込みの@code{make-comparator}がシャドウされます。)
これは後方互換性のために提供されています。
新たなコードは上に示した組み込みの@code{make-comparator}を使ってください。
@c COMMON

@c EN
It's mostly the same as @code{make-comparator} above, except
the following:
@c JP
以下の点を除き、上の@code{make-comparator}とほぼ同じです。
@c COMMON

@itemize
@item
@c EN
The third argument (@var{compare}) is a comparison procedure
instead of an ordering predicate.
It must be either @code{#f}, or a procedure taking two arguments
and returning either -1, 0, or 1, depending on whether the
first argument is less than, equal to,
or greater than the second argument.
If it is @code{#f}, it indicates the comparator can't order objects.
@c JP
第3引数(@var{compare})には順序手続きのかわりに比較手続きを渡します。
この引数は@code{#f}か、二つの引数を取りそれらの大小関係を
判定する手続きでなければなりません。手続きの場合、引数の最初の方が小さいか、
両者が等しいか、最初の方が大きいか、に応じて-1, 0, 1をそれぞれ返さなければ
なりません。@code{#f}の場合、対象とするオブジェクトの集合に全順序関係がつけられない
ことを表します。
@c COMMON
@item
@c EN
You can pass @code{#t} to the @var{equal} argument when you give
a comparison procedure.  In that case, equality is determined
by calling the comparison procedure and see if the result is 0.
@c JP
比較手続きを与えた場合、@var{equal}手続きに@code{#t}を渡すことができます。
その場合、等価性の判定は比較手続きが0を返すかどうかで行われます。
@c COMMON
@end itemize
@end defun

@node Comparator predicates and accessors, Predefined comparators, Comparator class and constructors, Basic comparators
@subsubsection Comparator predicates and accessors
@c NODE 比較器にまつわる述語とアクセサ


@defun comparator? obj
[R7RS comparator]
@c EN
Returns true iff @var{obj} is a comparator.
In R7RS, this is provided from @code{scheme.comparator}.
@c JP
@var{obj}が比較器である場合に@code{#t}を、そうでなければ@code{#f}を返します。
R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@deffn {Method} object-equal? (a <comparator>) (b <comparator>)
@c EN
Comparing two comparators by @code{equal?} compares their contents,
via this method.  Even @var{a} and @var{b} are comparators created
separately, they can be @code{equal?} if all of their slots are
the same.

This is Gauche's extension.  The standard says nothing about
equality of comparators, but it is sometimes useful if you can compare
two.
@c JP
二つの比較器が等価かどうかを@code{equal?}で調べた場合、
比較はこのメソッドを介して、各スロットが等価かどうかで判定されます。
比較器@var{a}と@var{b}が別々に作られたものであっても、各スロットの内容が
等価であれば@code{equal?}とみなされます。

これはGaucheの拡張です。標準は比較器同士の等価性については何も定義していません。
けれども、時には等価判定が便利なことがあります。
@c COMMON

@example
(equal? (make-comparator #t equal? #f hash 'foo)
        (make-comparator #t equal? #f hash 'foo))
  @result{} #t

@c EN
;; The following may be #t or #f, depending on how the anonymous
;; procedure is allocated.
@c JP
;; 次の式は、無名手続きがどのようにアロケートされるかによって、#tにも#fにも
;; なり得る。
@c COMMON
(equal? (make-comparator (^x x) eq? #f #f)
        (make-comparator (^x x) eq? #f #f))
@end example
@end deffn

@defun comparator-flavor cmpr
@c EN
Returns a symbol @code{ordering} if @var{cmpr} is created with
@code{scheme.comparator} constructor, and
returns @code{comparison} if @var{cmpr}
is created with SRFI-114 constructor.

Usually applications don't need to distinguish these two kinds of
comparators, for either kind of comparators can behave just as another
kind.  This procedure is for some particular cases when one
wants to optimize for the underlying comparator implementation.
@c JP
@var{cmpr}が@code{scheme.comparator}コンストラクタで作られた場合は
シンボル@code{ordering}を、
SRFI-114コンストラクタで作られた場合はシンボル@code{comparison}を返します。

アプリケーションは通常両者を区別する必要はありません。一方の比較器は
もう一方の比較器としても使うことができるからです。
比較器の実装に特化した最適化をしたい場合にのみ、区別が必要です。
@c COMMON
@end defun

@defun comparator-ordered? cmpr
@defunx comparator-hashable? cmpr
[R7RS comparator]
@c EN
Returns true iff a comparator @var{cmpr} can be used to order
objects, or to hash them, respectively.
In R7RS, this is provided from @code{scheme.comparator}.
@c JP
比較器@var{cmpr}が、オブジェクトの順序づけあるいはハッシュに使える
場合にそれぞれ@code{#t}を返します。
R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@defun comparator-type-test-procedure cmpr
@defunx comparator-equality-predicate cmpr
@defunx comparator-ordering-predicate cmpr
@defunx comparator-hash-function cmpr
[R7RS comparator]
@c EN
Returns type test procedure, equality predicate, ordering procedure
and hash function of comparator @var{cmpr}, respectively.
In R7RS, this is provided from @code{scheme.comparator}.

These accessors always return procedures; if you give @code{#f}
to the @var{order} or @var{hash} argument of the constructor,
@code{comparator-ordering-predicate} and
@code{comparator-hash-function} still return a procedure,
which will just raise an error.
@c JP
比較器の型検査述語、等価述語、順序手続きおよびハッシュ関数をそれぞれ返します。
R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。

これらの手続きは常に手続きを返します。@code{make-comparator}で
@var{order}や@var{hash}に@code{#f}を渡した場合でも、エラーを投げるだけの
手続きが返されます。
@c COMMON
@end defun

@defun comparator-comparison-procedure cmpr
[SRFI-114]
@c EN
This is a SRFI-114 procedure, but sometimes handy with
@code{scheme.comparator} comparators.
Returns a procedure that takes two objects
that satisfy the type predicates of @var{cmpr}.  The procedure
returns either -1, 0 or 1, depending on whether the first object
is less than, equal to, or greater than the second.  The comparator
must be ordered, that is, it must have an ordering predicate
(or a comparison procedure, if it is created by SRFI-114 constructor).
@c JP
これはSRFI-114の手続きですが、
@code{scheme.comparator}比較器でも時々便利なことがあります。
@var{cmpr}の型検査述語を満たす二つのオブジェクトを取り、-1、0、1のいずれかを
返す手続きを返します。二つのオブジェクトのうち最初の方が小さければ-1が、
等しければ0が、大きければ1が返されます。
比較器は大小比較可能でなけばなりません(順序手続きが渡されるか、
あるいはSRFI-114コンストラクタで比較手続きが渡されるか)。
@c COMMON
@end defun

@defun comparator-test-type cmpr obj
@defunx comparator-check-type cmpr obj
[R7RS comparator]
@c EN
Test whether @var{obj} can be handled by a comparator @var{cmpr},
by applying @var{cmpr}'s type test predicate.
The former (@code{comparator-test-type}) returns a boolean
values, while the latter (@code{comparator-check-type})
signals an error when @var{obj} can't be handled.

In R7RS, this is provided from @code{scheme.comparator}.
@c JP
@var{obj}が比較器@var{cmpr}で扱えるオブジェクトかどうかを、
@var{cmpr}の型検査述語を適用して調べます。
@code{comparator-test-type}は結果の真偽値を返します。
@code{comparator-check-type}は@var{obj}が扱えないオブジェクトである場合に
エラーを投げます。

R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@defun =? cmpr obj obj2 obj3 @dots{}
@defunx <? cmpr obj obj2 obj3 @dots{}
@defunx <=? cmpr obj obj2 obj3 @dots{}
@defunx >? cmpr obj obj2 obj3 @dots{}
@defunx >=? cmpr obj obj2 obj3 @dots{}
[R7RS comparator]
@c EN
Compare objects using a comparator @var{cmpr}.  All of
@var{obj}, @var{obj2}, @var{obj3} @dots{} must satisfy
the type predicate of @var{cmpr}.  When more than two objects
are given, the order of comparison is undefined.

In order to use @code{<?}, @code{<=?}, @code{>?} and @code{>=?},
comparator must be ordered.

In R7RS, this is provided from @code{scheme.comparator}.
@c JP
比較器@var{cmpr}を使ってオブジェクトを比較します。
@var{obj}, @var{obj2}, @var{obj3} @dots{}は全て@code{cmpr}の
型検査述語を満たさなければなりません。
3つ以上のオブジェクトが渡された場合、比較の順番は規定されていません。

@code{<?}、@code{<=?}、@code{>?}、@code{>=?}を使うためには
比較器は順序比較可能でなければなりません。

R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@defun comparator-hash cmpr obj
[R7RS comparator]
@c EN
Returns a hash value of @var{obj} with the hash function of
a comparator @var{cmpr}.  The comparator must be hashable,
and @var{obj} must satisfy comparator's type test predicate.

In R7RS, this is provided from @code{scheme.comparator}.
@c JP
比較器@var{cmpr}のハッシュ関数を使って@var{obj}のハッシュ値を計算して返します。
比較器はハッシュ計算可能でなければなりません。また、@var{obj}は
比較器の型検査述語を満たさなければなりません。

R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@defun comparator-compare cmpr a b
[SRFI-114]
@c EN
Order two objects @var{a} and @var{b}
using @var{cmpr}, and returns either one of
-1 (@var{a} is less than @var{b}),
0 (@var{a} equals to @var{b}), or
1 (@var{a} is greater than @var{b}).
Objects must satisfy @var{cmpr}'s type test predicate.

A simple comparison can be done by @code{<?} etc, but sometimes
three-way comparison comes handy.  So we adopt this procedure
from SRFI-114.
@c JP
ふたつのオブジェクト@var{a}と@var{b}の順序を調べ、
@var{a}が先 (小さい) なら -1を、
等しければ0を、
@var{a}が後 (大きい) なら 1を返します。
@var{a}と@var{b}はともに@var{cmpr}の型検査述語を満たさねばなりません。

単純な比較なら@code{<?}等の手続きでできますが、
時に3分岐の比較が便利なこともあります。そのため、SRFI-114から
この手続きを採用しました。
@c COMMON
@end defun

@node Predefined comparators, Combining comparators, Comparator predicates and accessors, Basic comparators
@subsubsection Predefined comparators
@c NODE 用意されている比較器

@defvar default-comparator
[SRFI-114]
@c EN
This variable bounds to a comparator that is used by default in
many context.

It can compare most of Scheme objects, even between objects with
different types.  In fact, it is defined as follows:
@c JP
この変数は、様々な場所でオブジェクトを比較する際のデフォルトとして使われる
比較器に束縛されています。

デフォルト比較器は次のとおり定義されており、
ほぼすべてのSchemeオブジェクト間の比較が出来ます。
@c COMMON

@example
(define default-comparator
  (make-comparator/compare #t equal? compare default-hash
                           'default-comparator))
@end example

@c EN
As you see in the definition, equality, ordering and hashing are
handled by @code{equal?}, @code{compare} and @code{default-hash},
respectively.  They takes care of builtin objects, and
also @code{equal?} and @code{compare} handle the case
when two objects of different types.
@c JP
定義からわかるように、等価述語、比較手続き、そしてハッシュ計算はそれぞれ
@code{equal?}、@code{compare}、@code{default-hash}で処理されます。
組み込みオブジェクト、及び二つの異なる型の間の比較についてはそれらが処理します。
@c COMMON

@c EN
For objects of user-defined classes,
those procedures call generic functions
@code{object-equal?}, @code{object-compare}, and @code{object-hash},
respectively.   Defining methods for them automatically extended
the domain of @code{default-comparator}.
@c JP
ユーザ定義クラスのオブジェクトについては、
上記手続きがそれぞれジェネリック関数
@code{object-equal?}、@code{object-compare}、@code{object-hash}を
呼び出します。これらのメソッドを定義することにより、
@code{default-comparator}の定義域も自動的に拡張されます。
@c COMMON

@c EN
@code{Scheme.comparator} defines another way to extend @code{default-comparator}.
See @code{comparator-register-default!} below for the details.
@c JP
@code{scheme.comparator}は、@code{default-comparator}を拡張する別の方法を定義しています。
下の@code{comparator-register-default!}の項を参照してください。
@c COMMON
@end defvar

@defun comparator-register-default! comparator
[R7RS comparator]
@c EN
In R7RS, this is provided from @code{scheme.comparator}.
This is the @code{scheme.comparator} way for user
programs to extend the behavior of
the @code{default-comparator}
(which is what @code{make-default-comparator} returns).

Note that, in Gauche, you can also extend default comparator's behavior
by defining specialized methods for @code{object-equal?},
@code{object-compare} and @code{object-hash}.
See the description of @code{default-comparator} above, for the details.
@c JP
R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
これは、@code{default-comparator}(@code{make-default-comparator}が
返す比較器)の振る舞いをユーザプログラムが拡張できるようにする、
@code{scheme.comparator}が定める方法です。

Gaucheでは、@code{object-equal?}、@code{object-compare}、@code{object-hash}に
特殊化したメソッドを定義することでも、デフォルト比較器を拡張できることに
留意してください。詳しくは上の@code{default-comparator}の説明を参照のこと。
@c COMMON

@c EN
In fact, Gauche uses those generic functions to
handle the registered comparators; methods specialized for
@code{<top>} are defined for these generic functions, which
catches the case when @code{default-comparator} is applied
on object(s) of user-defined classes that don't have specialized
methods defined for those generic functions.
The catching method examines registered comparators to find
one that can handle passed argument(s), and if it finds one,
use it.
@c JP
実際、Gaucheではこれらのジェネリックファンクションを使って、
登録されたデフォルト比較器を処理しています。これらのジェネリックファンクションには、
あらかじめ@code{<top>}に特殊化されたメソッドが定義されており、
@code{default-comparator}がユーザ定義クラスのオブジェクトに使われ、
かつそのクラスに特殊化されたメソッドが定義されていない場合を捕まえます。
そして、登録された比較器から与えられた引数に適用可能なものを探し、
見つかればそれを使います。
@c COMMON

@c EN
You might frown at this procedure having a global side-effect.
Well, @code{scheme.comparator} explicitly prohibits comparators registered
by this procedure alters the behavior of the default comparator
in the existing domain---it is only allowed to handle objects that
aren't already handled by the system's original default comparator
and other already registered comparators.  So, the only effect of
adding new comparator should make the default comparator
work on objects that had been previously raised an error.
@c JP
この手続きがグローバルな副作用を持つことに顔をしかめる人もいるかもしれません。
@code{scheme.comparator}では、
デフォルトの比較器や登録された比較器が既にカバーしている定義域と
重複する定義域を持つ比較器を登録することを禁じています。
言い換えれば、@code{comparator-register-default!}で定義できるのは、
デフォルトの比較器や既に登録された比較器が処理できないオブジェクトを扱う
比較器だけです。従って、新たな比較器を登録することによる副作用は、
それまで@code{default-comparator}が扱えなかったオブジェクトを
扱えるようになるというだけで、既に扱えていたオブジェクトに対する
@code{default-comparator}の動作が変わってしまうということはありません。
@c COMMON

@c EN
In reality, it is impossible to enforce the condition.  If you
register a comparator whose domain overlaps overlaps the domain
the default comparator (and its extensions via Gauche's methods),
the program becomes non-portable at that moment.  In the current version,
the comparators registered by @code{comparator-register-default!} has
the lowest precedence on the dispatch mechanism, but you shouldn't count
on that.
@c JP
尤も、現実にその条件を強制することは不可能です。
もし、既にデフォルトの比較器の定義域(および、Gaucheのメソッドにより拡張された定義域)
と重なるような定義域を持つ比較器を登録してしまったら、その時点でプログラムの
移植性は損なわれます。現在のバージョンでは、@code{comparator-register-default!}
で登録された比較器は最も低い優先度を持ちますが、その動作をあてにすべきではありません。
@c COMMON
@end defun

@defvar eq-comparator
@defvarx eqv-comparator
@defvarx equal-comparator
[SRFI-114]
@c EN
Built-in comparators that uses @code{eq?}, @code{eqv?} and @code{equal?}
for the equality predicate, respectively.  They accept any kind of
Scheme objects.  Each has corresponding hash functions
(i.e. @code{eq-hash} for @code{eq-comparator},
@code{eqv-hash} for @code{eqv-comparator} and
@code{default-hash} for @code{equal-comparator}).
Only @code{eq-comparator} is ordered, using @code{eq-compare} to
order the objects
(@pxref{Comparison}, for @code{eq-compare}).
@c JP
それぞれ、等価述語に@code{eq?}、@code{eqv?}、@code{equal?}を使う
組み込みの比較器です。全てのSchemeオブジェクトを受け付けます。
対応するハッシュ関数(@code{eq-comparator}は@code{eq-hash}、
@code{eqv-comparator}は@code{eqv-hash}、@code{equal-comparator}は
@code{hash})を備えています。
@code{eq-comparator}のみ、@code{eq-compare}を使った順序づけが可能です
(@code{eq-compare}については@ref{Comparison}参照)。
@c COMMON

@c EN
Note that @code{eq-comparator} and @code{eqv-comparator} are not
equivalent from what @code{make-eq-comparator} and @code{make-eqv-comparator}
return, respectively.  The latter two are defined in @code{scheme.comparator}
and specified to use @code{default-hash} for the hash function.  It is
heavier than @code{eq-hash}/@code{eqv-hash}, and it can't be used
for circular objects, nor for the mutable objects with which you want
to hash them by identity.  We provide @code{eq-comparator} and
@code{eqv-comparator} in case you want to avoid limitations of
@code{default-hash}.
@c JP
@code{eq-comparator}と@code{eqv-comparator}はそれぞれ、
@code{make-eq-comparator} and @code{make-eqv-comparator}が返す比較器とは
等価でないことに注意してください。後者の手続きは@code{scheme.comparator}
で規定されていますが、
ハッシュ関数には@code{default-hash}を使うように指定されています。
@code{default-hash}は@code{eq-hash}や@code{eqv-hash}より重く、
ループのある構造は扱えず、また変更可能なオブジェクトの同一性のみに基づいてハッシュ値を
計算するのには使えません。
こういった@code{default-hash}の制限を避けたい場合のために
@code{eq-comparator}と@code{eqv-comparator}を用意しました。
@c COMMON
@end defvar

@defvar boolean-comparator
@defvarx char-comparator
@defvarx char-ci-comparator
@defvarx string-comparator
@defvarx string-ci-comparator
[SRFI-114]
@c EN
Compare booleans, characters, and strings, respectively.
The @code{*-ci-*} variants uses case-insensitive comparison.
All have appropriate hash functions, too.

The string case-insensitive comparison uses Unicode full-string case
conversion (@pxref{Full string case conversion}).
@c JP
それぞれ、真偽値、文字、文字列を比較する比較器です。
@code{*-ci-*}がついている手続きは大文字小文字の区別をしません。
全て、適切なハッシュ関数も備えています。

文字列の大文字小文字の区別をしない比較は、Unicodeのfull-string case conversion
に従います (@ref{Full string case conversion}参照)。
@c COMMON
@end defvar

@defvar exact-integer-comparator
@defvarx integer-comparator
@defvarx rational-comparator
@defvarx real-comparator
@defvarx complex-comparator
@defvarx number-comparator
[SRFI-114]
@c EN
Compare exact integers, integers, rational numbers, real numbers,
complex numbers and general numbers, respectively.
In Gauche @code{number-comparator} is the same as @code{complex-comparator}.

The equality are determined by @code{=}.
For exact integer, integer, rational and real comparators,
the order is the numerical order.  Two complex numbers are
compared first by their real components, and then their imaginary
components only if the real components are the same.

Note that those comparator rejects NaN.
You need @code{make-inexact-real-comparator} in @code{srfi.114} module
to compare NaNs with your own discretion.
@xref{Comparators}, for the details.
@c JP
それぞれ、正確な整数、整数、有理数、実数、複素数、そして全ての数値を比較する比較器です。
Gaucheでは@code{number-comparator}は@code{complex-comparator}と同じです。

等価性は@code{=}により判定されます。
正確な整数、整数、有理数および実数の比較器では、比較手続きは数値の大小に基づいて
判定されます。複素数の比較においては、まず実部の大小が比べられ、実部が等しい場合に
虚部の大小が比べられます。

これらの比較器はNaNを扱いません。
NaNを扱いたい場合は、@code{srfi.114}モジュールの@code{make-inexact-real-comparator}
手続きを使って、NaNの比較方法を指定する必要があります。
詳しくは@ref{Comparators}を参照してください。
@c COMMON
@end defvar

@defvar pair-comparator
@defvarx list-comparator
@defvarx vector-comparator
@defvarx uvector-comparator
@defvarx bytevector-comparator
[SRFI-114]
@c EN
The default comparators to compare pairs, lists, vectors, uniform
vectors and bytevectors (which is synonym to @code{u8vector}).
Their respective elements are compared with the default comparators.

Note that lists are compared by dictionary order (@code{(1 2 3)} comes
before @code{(1 3)}), while in vector-families
shorter ones are ordered first (
@code{#(1 3)} comes before @code{#(1 2 3)}).
@c JP
ペア、リスト、ベクタ、ユニフォームベクタ、バイトベクタ(@code{u8vector}の別名)を
それぞれ比較するための比較器です。
各データ型の要素についてはデフォルトの比較器(@code{default-comparator)}が
使われます。

リストは辞書順で比較されますが(例:@code{(1 2 3)}は@code{(1 3)}より前)、
ベクタの仲間はまず長さが短いものが先に来て、それから内容で比較されることに注意してください
(@code{#(1 3)}は@code{#(1 2 3)}より前)。
@c COMMON
@end defvar

@defvar time-comparator
@c EN
A comparator to compare @code{<time>} objects (@pxref{Time}).
@c JP
@code{<time>}オブジェクトを比較する比較器です。@ref{Time}参照。
@c COMMON
@end defvar


@node Combining comparators,  , Predefined comparators, Basic comparators
@subsubsection Combining comparators
@c NODE 比較器を組み合わせる

@defun make-default-comparator
[R7RS comparator]
@c EN
Returns a default comparator.  In Gauche, this returns the
@code{default-comparator} object.
In R7RS, this is provided from @code{scheme.comparator}.
@c JP
デフォルト比較器を返します。Gaucheでは常に唯一の@code{default-comparator}が
返されます。
R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@defun make-eq-comparator
@defunx make-eqv-comparator
[R7RS comparator]
@c EN
Returns comparators that use @code{eq?} and @code{eqv?} for its
equality predicate, respectively.  Note that they use @code{default-hash}
for hash functions, as specified by @code{scheme.comparator},
which has a few drawbacks:
You can't use it if you want to hash based on identity of mutable objects,
it diverges on circular objects, and it is slow if applied on a large
structures.  We recommend to use @code{eq-comparator} or
@code{eqv-comparator} if possible (@pxref{Predefined comparators}).

In R7RS, this is provided from @code{scheme.comparator}.
@c JP
@code{eq?}および@code{eqv?}を等価述語に使う比較器をそれぞれ返します。
これらの関数が返す比較器のハッシュには、@code{default-hash}を使うことが
@code{scheme.comparator}で規定されていますが、それにはいくつか欠点があります。
変更可能なオブジェクトの同一性に基づいたハッシュ関数が欲しい場合は使えませんし、
循環するオブジェクトでは発散します。大きな構造をハッシュしようとすると遅くなります。
可能ならば、@code{eq-comparator}や@code{eqv-comparator}を
使うことを推奨します(@ref{Predefined comparators})参照。)

R7RSではこの手続きは@code{scheme.comparator}ライブラリで提供されます。
@c COMMON
@end defun

@defun make-reverse-comparator cmpr
[SRFI-114]
@c EN
Returns a comparator with the same type test predicate,
equality procedure, and hash function as the given comparator,
but the comparison procedure is flipped.
@c JP
与えられた比較器@var{cmpr}と同じ型検査述語、等価述語、ハッシュ関数を持ち、
大小比較だけが逆になっているような比較器を返します。
@c COMMON
@end defun

@defun make-key-comparator cmpr test key
@c EN
Suppose you have some kind of structure, but you only need to look
at one part of it to compare them.

Returns a new comparator that uses @var{test} as type test predicate.
Its equality predicate, comparison procedure and hash function are
constructed by applying @var{key} to the argument(s) then passing
the result to the corresponding procedure of @var{cmpr}.  If @var{cmpr}
lacks comparison procedure and/or hash function, so does the returned
comparator.
@c JP
何らかの構造体があって、その比較に際してはその中の一つの要素を見るだけで良い、
という場合に使える手続きです。

比較器を作って返します。型検査述語には@var{test}が使われます。
等価述語、比較手続き、ハッシュ関数については、それらの引数に@var{key}を適用して
得られた値を、比較器@var{cmpr}の対応する手続きに渡すような手続きとなります。
@var{cmpr}が比較手続きやハッシュ関数を欠いている場合は、
返される比較器も同様に比較手続きやハッシュ関数を欠いたものとなります。
@c COMMON

@c EN
In the following example, the tree-map @code{users} compares
the given user records only by the @code{username} slots:
@c JP
次の例では、ツリーマップ@code{users}は
userレコードの@code{username}スロットだけを見て比較を行います。
@c COMMON

@example
(use gauche.record)

(define-record-type user #t #t
  username      ; string
  password-hash ; string
  comment)      ; string

(define users   ; table of users, managed by tree-map
  (make-tree-map
    (make-key-comparator string-comparator user? user-username)))
@end example

@c EN
@xref{Composing comparators}, for additional procedures
to create comparator of aggregate types.
@c JP
集合型の比較器を作る手続きについては、@ref{Composing comparators}も参照してください。
@c COMMON
@end defun

@defun make-tuple-comparator cmpr1 cmpr2 @dots{}
@c EN
Creates a comparator that compares lists of the form @code{(x1 x2 @dots{})},
where each element is compared with the corresponding comparator.
For example, @code{(make-tuple-comparator c1 c2 c3)} will compare
three-element list, whose first elements are compared by @var{c1},
second elements by @var{c2} and third elements by @var{c3}.
@c JP
リスト@code{(x1 x2 @dots{})}の各要素をそれぞれ@var{cmpr1} @code{cmpr2} @dots{}
で比較するような比較器を返します。
例えば@code{(make-tuple-comparator c1 c2 c3)}が返すのは、
3要素のリストを受け入れ、最初の要素が@var{c1}で、二番目の要素が@var{c2}で、
最後の要素が@var{c3}で比較されるような比較器です。
@c COMMON

@c EN
@xref{Composing comparators}, for additional procedures
to create comparator of aggregate types.
@c JP
集合型の比較器を作る手続きについては、@ref{Composing comparators}も参照してください。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Numbers, Booleans, Equality and comparison, Core library
@section Numbers
@c NODE 数値

@c EN
Gauche supports the following types of numbers
@table @asis
@item multi-precision exact integer
There's no limit of the size of number except the memory of the machine.
@item multi-precision exact non-integral rational numbers.
Both denominator and numerator are represented by exact integers.
There's no limit of the size of number except the memory of the machine.
@item inexact floating-point real numbers
Using @code{double}-type of underlying C compiler, usually IEEE 64-bit
floating point number.
@item inexact floating-point complex numbers
Real part and imaginary part are represented by inexact floating-point
real numbers.
@end table
@c JP
Gaucheは次のタイプの数値をサポートしています。
@table @asis
@item 多倍長の正確な整数
メモリの許す限りの精度が扱えます。
@item 多倍長の正確な非整数の有理数
分母と分子は正確な整数で表現されます。
メモリの許す限りの精度が扱えます。
@item 浮動小数点の非正確な実数
実装に使われるC言語の@code{double}型で表現されます。通常IEEE 64bit浮動小数点数です。
@item 浮動小数点の非正確な複素数
実部と虚部はそれぞれ浮動小数点の非正確な実数で表現されます。
@end table
@c COMMON

@menu
* Number classes::
* Numerical predicates::
* Numerical comparison::
* Arithmetics::
* Numerical conversions::
* Basic bitwise operations::
* Endianness::
@end menu

@node Number classes, Numerical predicates, Numbers, Numbers
@subsection Number classes
@c NODE 数値クラス

@deftp {Builtin Class} <number>
@deftpx {Builtin Class} <complex>
@deftpx {Builtin Class} <real>
@deftpx {Builtin Class} <rational>
@deftpx {Builtin Class} <integer>
@clindex number
@clindex complex
@clindex real
@clindex rational
@clindex integer
@c EN
These classes consist a class hierarchy of number objects.
@code{<complex>} inherits @code{<number>}, @code{<real>} inherits
@code{<complex>},@code{<rational>} inherits @code{<real>}
 and @code{<integer>} inherits @code{<rational>}.

Note that these classes do not exactly correspond to the
number hierarchy defined in R7RS.  Especially,
only exact integers are the instances of the @code{<integer>}
class.  That is,
@c JP
数値オブジェクトのクラス階層を構成します。@code{<complex>}は
@code{<number>}を継承し、@code{<real>}は@code{<complex>}を継承し、
@code{<rational>}は@code{<real>}を継承し、
@code{<integer>}は@code{<rational>}を継承します。

これらのクラスはR7RSで定義されている数値の階層とは必ずしも対応しません。
特に、@code{<integer>}クラスのインスタンスはR7RSでいうexact integerのみになります。
@c COMMON
@lisp
(integer? 1)        @result{} #t
(is-a? 1 <integer>) @result{} #t
(is-a? 1 <real>)    @result{} #t

(integer? 1.0)        @result{} #t
(is-a? 1.0 <integer>) @result{} #f
(is-a? 1.0 <real>)    @result{} #t

(class-of (expt 2 100)) @result{} #<class <integer>>
(class-of (sqrt -3)) @result{} #<class <complex>>
@end lisp
@end deftp

@node Numerical predicates, Numerical comparison, Number classes, Numbers
@subsection Numerical predicates
@c NODE 数値に関する述語

@defun number? obj
@defunx complex? obj
@defunx real? obj
@defunx rational? obj
@defunx integer? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a number, a complex number, a real number,
a rational number or an integer, respectively.   In Gauche, a set of
numbers is the same as a set of complex numbers.
A set of rational numbers is the same as a set of real numbers,
except @code{+inf.0}, @code{-inf.0} and @code{+nan.0}
(since we have only limited-precision floating numbers).
@c JP
@var{obj}がそれぞれ数、複素数、実数、有理数、整数ならば@code{#t}を返します。
Gaucheでは、数の集合は複素数の集合と同一であり、有理数の集合は
@code{+inf.0}, @code{-inf.0}, @code{+nan.0}を除いた実数の集合と同一
(浮動小数点数が有限精度であるため)です。
@c COMMON

@example
(complex? 3+4i)   @result{} #t
(complex? 3)      @result{} #t
(real? 3)         @result{} #t
(real? -2.5+0.0i) @result{} #t
(real? #e1e10)    @result{} #t
(integer? 3+0i)   @result{} #t
(integer? 3.0)    @result{} #t

(real? +inf.0)     @result{} #t
(real? +nan.0)     @result{} #t
(rational? +inf.0) @result{} #f
(rational? +nan.0) @result{} #f
@end example

@c EN
Note: R6RS adopts more strict definition on exactness,
and notably, it defines a complex number with non-exact zero imaginary
part is not a real number.   Currently Gauche doesn't have
exact complex numbers, and automatically coerces complex
numbers with zero imaginary part to a real number.
Thus R6RS code that relies on the fact that @code{(real? 1+0.0i)} is
@code{#f} won't work with Gauche.
@c JP
R6RSでは正確性についてより厳密な定義がなされ、特に
非正確なゼロを虚数部に持つ複素数は実数ではないと規定されています。
Gaucheは今のところ正確な複素数を持たず、虚部がゼロの複素数は
自動的に実数に変換されます。従ってR6RSのコードのうち、
@code{(real? 1+0.0i)}が@code{#f}であることを当てにしているものは
うまく動かないでしょう。
@c COMMON
@end defun

@defun real-valued? obj
@defunx rational-valued? obj
@defunx integer-valued? obj
[R6RS]
@c EN
In Gauche these are just an alias of @code{real?}, @code{rational?}
and @code{integer?}.  They are provided for R6RS compatibility.

The difference of those and non @code{-valued} versions in R6RS is
that these returns @code{#t} if @var{obj} is a complex number
with nonexact zero imaginary part.   Since Gauche doesn't distinguish
complex numbers with zero imaginary part and real numbers, we don't
have the difference.
@c JP
Gaucheではこれらの手続きはそれぞれ@code{real?}、@code{rational?}、
および@code{integer?}の別名となっています。これらはR6RSコードとの互換性のために
提供されています。

R6RSで規定されている、これらの手続きと@code{-valued}がついていない手続きの違いは、
これらの手続きは非正確なゼロの虚部を持つ複素数に対しても@code{#t}を返すという
ことです。Gaucheではゼロの虚部を持つ複素数は実数とみなしているので、
この違いは現れません。
@c COMMON
@end defun

@defun exact? obj
@defunx inexact? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is an exact number and an inexact number,
respectively.
@c JP
@var{obj}がそれぞれ正確な数、非正確な数ならば@code{#t}を返します。
@c COMMON

@example
(exact? 1)       @result{} #t
(exact? 1.0)     @result{} #f
(inexact? 1)     @result{} #f
(inexact? 1.0)   @result{} #t

(exact? (modulo 5 3)) @result{} #t
(inexact? (modulo 5 3.0)) @result{} #f
@end example
@end defun

@defun exact-integer? obj
[R7RS base]
@c EN
Same as @code{(and (exact? obj) (integer? obj))}, but more efficient.
@c JP
@code{(and (exact? obj) (integer? obj))}と等価ですが、より高速です。
@c COMMON
@end defun

@defun zero? z
[R7RS base]
@c EN
Returns @code{#t} if a number @var{z} equals to zero.
@c JP
数値@var{z}がゼロに等しければ@code{#t}を返します。
@c COMMON

@example
(zero? 1)        @result{} #f
(zero? 0)        @result{} #t
(zero? 0.0)      @result{} #t
(zero? -0.0)     @result{} #t
(zero? 0.0+0.0i) @result{} #t
@end example
@end defun

@defun positive? x
@defunx negative? x
[R7RS base]
@c EN
Returns @code{#t} if a real number @var{x} is positive and negative,
respectively.  It is an error to pass a non-real number.
@c JP
実数@var{x}がそれぞれ正または負なら@code{#t}を返します。
非実数を渡すとエラーになります。
@c COMMON

@c EN
Note that minus zero (@code{-0.0}) is zero, not negative.
@c JP
マイナスゼロ(@code{-0.0})はゼロであって負ではないことに注意してください。
@c COMMON
@end defun

@defun negative-zero? x
@c EN
Returns @code{#t} if a number @var{x} is a minus zero (@code{-0.0}),
@code{#f} otherwise.
An error is signaled if @var{x} is not a number.
@c JP
数値@var{x}がマイナスゼロ(@code{-0.0})の場合に@code{#t}を、
そうでなければ@code{#f}を返します。@var{x}が数値でなければエラーが投げられます。
@c COMMON
@end defun

@defun finite? z
@defunx infinite? z
@defunx nan? z
[R7RS inexact]
@c EN
For real numbers, returns @code{#f} iff the given number
is finite, infinite, or NaN, respectively.

For non-real complex numbers, @code{finite?} returns @code{#t} iff
both real and imaginary components are finite, @code{infinite?}
returns @code{#t} if at least either real or imaginary component
is infinite, and @code{nan?} returns @code{#t} if at least either
real or imaginary component is NaN.  (Note: It is incompatible
to R6RS, in which these procedures must raise an error if
the given argument is non-real number.)

In R7RS, these procedures are in @code{(scheme inexact)} library.
@c JP
実数に対して、それが有限、無限、NaNであればそれぞれ@code{#t}を返します。

非実数の複素数に対しては、@code{finite?}は実数部と仮数部がともに
有限なら@code{#t}を、@code{infinite?}は実数部と仮数部の少なくともどちらかが
無限なら@code{#t}を、@code{nan?}は実数部と仮数部の少なくともどちらかが
NaNなら@code{#t}を返します。(これはR6RSとは非互換です。R6RSでは
これらの手続きは引数に非実数の数が与えられた場合はエラーを通知しなければならないからです。)

R7RSではこれらの手続きは@code{(scheme inexact)}ライブラリにあります。
@c COMMON
@end defun

@defun odd? n
@defunx even? n
[R7RS base]
@c EN
Returns @code{#t} if an integer @var{n} is odd and even,
respectively.  It is an error to pass a non-integral number.
@c JP
整数@var{n}がそれぞれ奇数または偶数なら@code{#t}を返します。
非整数を渡すとエラーになります。
@c COMMON

@example
(odd? 3)     @result{} #t
(even? 3)    @result{} #f
(odd? 3.0)   @result{} #t
@end example
@end defun

@defun fixnum? n
@defunx bignum? n
[R7RS fixnum]
@c EN
Returns @code{#t} iff @var{n} is an exact integer whose internal
representation is @emph{fixnum} and @emph{bignum}, respectively.
R7RS-large defines @code{fixnum?} in @code{scheme.fixnum} library;
@code{bignum?} is Gauche's extension.
Portable Scheme programs don't need to care about the internal
representation of integer.   These are for certain low-level
routines that does particular optimization.

@xref{R7RS fixnum}, for the comprehensive fixnum library.
@c JP
@var{n}が正確な整数で、かつ内部的にそれぞれ@emph{fixnum}もしくは@emph{bignum}
で表現されているときに@code{#t}を返します。R7RS-largeは
@code{scheme.fixnum}ライブラリで@code{fixnum?}を定義しています。
@code{bignum?}はGauche拡張です。
通常のSchemeプログラムは整数の内部表現を気にする必要はありません。
これらの手続きは、ある種の最適化を行う低レベル手続きのために用意されています。

fixnumを扱う包括的なライブラリは@ref{R7RS fixnum}を参照してください。
@c COMMON
@end defun

@defun flonum? x
[R7RS flonum]
@c EN
Returns @code{#t} if @var{x} is a number represented by a floating-point
number, @code{#f} otherwise.  In Gauche, inexact real numbers
are flonums.

@xref{R7RS flonum}, for comprehensive flonum library.
@c JP
@var{x}が浮動小数点数で表現される数値の場合に@code{#t}を、それ以外の場合に
@code{#f}を返します。Gaucheでは、非正確な実数がflonumです。

flonumを扱う包括的なライブラリは@ref{R7RS flonum}を参照してください。
@c COMMON
@end defun

@defun ratnum? x
@c EN
Returns @code{#t} if @var{x} is a number represented by an exact
non-integral number, or @code{#f} otherwise.  Internally, a number
that returns @code{#t} for it is represented as a pair of two
exact integers.

Usually you don't need to distinguish ratnums from exact integers; you
can treat them as exact numbers.  In performance-sensitive code, however,
ratnum slows down computation a lot and you may want to detect that case.
@c JP
@var{x}が正確な非整数の場合に@code{#t}を、そうでなければ@code{#f}を返します。
この述語に@code{#t}を返す数値は内部的には二つの正確な整数の組で表現されています。

通常、正確な整数とratnumとを区別する必要はありません。両方とも単なる正確数です。
ただ、性能が要求されるコードにおいて、ratnumの演算が入ると計算が重くなるので、
その状況を検出したい場合はあるかもしれません。
@c COMMON
@end defun

@node Numerical comparison, Arithmetics, Numerical predicates, Numbers
@subsection Numerical comparison
@c NODE 数値の比較

@defun = z1 z2 z3 @dots{}
[R7RS base]
@c EN
If all the numbers @var{z} are equal numerically, returns @code{#t}.
@c JP
与えられた全ての数値@var{z}が数値として等しければ@code{#t}を返します。
@c COMMON

@example
(= 2 2)          @result{} #t
(= 2 3)          @result{} #f
(= 2/4 1/2)      @result{} #t
@end example

@c EN
Exactness doesn't affect numerical comparison; inexact 1.0 and
exact 1 are @code{=} to each other.  Positive inexact zero (0.0) and
negative inexact zero (-0.0) are also @code{=} to each other.
To distinguish numerically equal
exact and inexact number, you have to use @code{eqv?} or @code{equal?}.
@c JP
正確性は数値としての比較には影響しません。非正確な1.0と正確な1は@code{=}とみなされます。
非正確な正のゼロ(0.0)と非正確な負のゼロも@code{=}です。
それらを区別するには、@code{eqv?}や@code{equal?}を使ってください。
@c COMMON

@example
(= 2 2.0)        @result{} #t
(= 2 2.0 2.0+0i) @result{} #t
(= -0.0 0.0)     @result{} #t

;; cf:
(eqv? 2 2.0)     @result{} #f
(eqv? -0.0 0.0)  @result{} #f
@end example

@c EN
Note that @code{+nan.0} would never @code{=} to any number, including itself.
@c JP
@code{+nan.0}は、それ自身を含めていかなる数値とも@code{=}になりません。
@c COMMON

@example
(= +nan.0 +inf.0)  @result{} #f
(= +nan.0 +nan.0)  @result{} #f

(let ((x +nan.0)) (= x x)) @result{} #f
@end example
@end defun

@defun < x1 x2 x3 @dots{}
@defunx <= x1 x2 x3 @dots{}
@defunx > x1 x2 x3 @dots{}
@defunx >= x1 x2 x3 @dots{}
[R7RS base]
@c EN
Returns @code{#t} If all the real numbers @var{x} are
monotonically increasing,
monotonically nondecreasing, monotonically decreasing, or monotonically
nonincreasing, respectively.
@c JP
与えられた全ての実数@var{x}がそれぞれ単調増加、単調非減少、単調減少、単調非増加している
場合に@code{#t}を返します。
@c COMMON

@c EN
Since @code{(= 0.0 -0.0)} is @code{#t}, @code{(> 0.0 -0.0)} is @code{#f}.
@c JP
@code{(= 0.0 -0.0)}は@code{#t}なので、@code{(> 0.0 -0.0)}は@code{#f}になります。
@c COMMON

@c EN
If any of the argument is NaN, the result is always @code{#f}.
Hence @code{(< x y) @result{} #f} does not imply @code{(>= x y) @result{} #t}.
@c JP
引数にNaNが入っていると結果は@code{#f}になります。
すなわち、@code{(< x y) @result{} #f}だからといって@code{(>= x y) @result{} #t}
とは限りません。
@c COMMON
@end defun

@defmac ineq v0 op0 v1 @dots{}
@c EN
N-ary nature of comparison procedures allows you to write something like
@code{(< 0 x 100)}.  However, if you have close/open range, you have to
fall back to verbose @code{(and (<= 0 x) (< x 100))}.  With @code{ineq}
(for inequality), you can write it as @code{(ineq 0 <= x < 100)}.

Formally, @code{(ineq v0 op0 v1 op1 @dots{} opN vN+1)} is expanded
into the following:
@c JP
比較手続きは3つ以上の引数を取れるので、例えば@code{(< 0 x 100)}のように
書くことができます。しかし、片方が開区間、もう片方が閉区間といった場合は
短く書くことができず、@code{(and (<= 0 x) (< x 100))}としなければ
なりませんでした。@code{ineq}マクロ(inequality=不等式)を使うと、
これを@code{(ineq 0 <= x < 100)}と書くことができます。

正式には、@code{(ineq v0 op0 v1 op1 @dots{} opN vN+1)}は
次のとおり展開されます。
@c COMMON

@example
(let ((_v0 v0) (_op0 op0) ... (_opN opN) (_vN+1 vN+1))
  (and (_op0 _v0 _v1)
       (_op1 _v1 _v2)
       ...
       (_opN _vN _vN+1)))
@end example

@c EN
The operator @var{op0} etc. does not need to be a numerical comparison;
any binary operator would do, but probably only comparison-like
operators make sense.
@c JP
演算@var{op0}などは二項演算子として使えさえすれば、
数値比較手続きである必要はありません。
ただ、上の展開が意味を持つのは基本的には何らかの比較手続きでしょう。
@c COMMON

@example
(ineq #\A char-ci<=? x char-ci<? y char-ci<=? #\Z)
@end example

@c EN
It is an error if the number of arguments are not odd.
@c JP
引数の数が奇数でない場合はエラーとなります。
@c COMMON
@end defmac

@defmac ineq/comprator cmp v0 op0 v1 @dots{}
@c EN
Similar to @code{ineq}, but the first argument @var{cmp} is passed
as the first argument to each operator.  For example:
@c JP
@code{ineq}と似ていますが、最初の引数@var{cmp}が各オペレータの最初の引数として
渡されます。例えば:
@c COMMON

@example
(ineq/comparator cmp a <=? b <? c)
@end example

@c EN
expans something as follows (in the actual expansion, arguments
are bound to temporary variables to avoid multiple evaluation):
@c JP
これはだいたい次の式に展開されます (実際は、複数回評価を避けるために、
各引数は一時変数に束縛されます):
@c COMMON

@example
(and (<=? cmp a b) (<? cmp b c))
@end example

@c EN
This is particularly useful to compare things with a comparator.
@xref{Comparator predicates and accessors}, for the details.
@c JP
これは比較器を使って比較したい場合にとりわけ便利です。
詳しくは@ref{Comparator predicates and accessors}を参照してください。
@c COMMON
@end defmac

@defun max x1 x2 @dots{}
@defunx min x1 x2 @dots{}
[R7RS base]
@c EN
Returns a maximum or minimum number in the given real numbers, respectively.
If any of the arguments are NaN, NaN is returned.
@c JP
与えられた実数のうち、それぞれ最大と最小のものを返します。
引数にNaNが含まれていた場合は、NaNが返されます。
@c COMMON

@c EN
See also @code{find-min} and @code{find-max} in
@ref{Selection and searching in collection}.
@c JP
@ref{Selection and searching in collection}の
@code{find-min}と@code{find-max}も参照。
@c COMMON
@end defun

@defun min&max x1 x2 @dots{}
@c EN
Returns a maximum and minimum number in the given real numbers.
@c JP
与えられた実数から、最大値と最小値の二つの値を返します。
@c COMMON

@c EN
See also @code{find-min&max} in
@ref{Selection and searching in collection}.
@c JP
@ref{Selection and searching in collection}の
@code{find-min&max}も参照。
@c COMMON
@end defun

@defun approx=? x y :optional relative-tolerance absolute-tolerance
@c EN
Returns @code{#t} iff two numbers are approximately equal within
the given error tolerance.

@itemize @bullet
@item
If at least one of @var{x} or @var{y} is NaN, returns @code{#f}.
@item
If either one is infinity, returns @code{#t} iff the other one is also
infinity of the same sign.
@item
Otherwise, return a boolean value computed as follows:
@example
(<= (abs (- x y))
    (max (* (max (abs x) (abs y)) relative-tolerance)
         absolute-tolerance))
@end example
@end itemize

If at least one of @var{x} or @var{y} are non-real complex
number, @code{magnitude} is used in place of @code{abs}.

When omitted, @var{relative-tolerance} is assumed to be
@code{(flonum-epsilon)}, and @var{absolute-tolerance} is
@code{(least-positive-flonum)}.
That is, by default, @code{approx=?} tolerates
1 ULP (unit in the last place) error.

The @var{absolute-tolerance} argument is useful when arguments are
close to zero, in which case relative tolerance becomes too small.
@c JP
二つの数値が与えられたエラー許容範囲内で等しいとみなせる場合に@code{#t}を、
そうでなければ@code{#f}を返します。

@itemize @bullet
@item
@var{x}と@var{y}の少なくとも一方がNaNであれば、常に@code{#f}を返します。
@item
一方が無限大である場合、もう一方も同じ符号の無限大である場合のみ@code{#t}を、
そうでなければ@code{#f}を返します。
@item
そうでない場合、次の式により一致が判定されます。
@example
(<= (abs (- x y))
    (max (* (max (abs x) (abs y)) relative-tolerance)
         absolute-tolerance))
@end example
@end itemize

@var{x}か@var{y}の少なくとも一方が非実数の複素数である場合は、
@code{abs}のかわりに@code{magnitude}が使われます。

省略された場合、@var{relative-tolerance}には
@code{(flonum-epsilon)}の値が、@var{absolute-tolerance}には
@code{(least-positive-flonum)}の値が使われます。
すなわち、デフォルトでは@code{approx=?}は
1 ULP (unit in the last place)のエラーを許容するということです。

@var{absolute-tolerance}引数は、引数がともにゼロに近く、
相対許容範囲が小さくなりすぎる場合に便利です。
@c COMMON
@end defun

@defun flonum-epsilon
@defunx greatest-positive-flonum
@defunx least-positive-flonum
@defunx least-positive-normalized-flonum
@c EN
Returns flonums with the following characteristics, respectively:
@table @code
@item flonum-epsilon
Returns the least positive flonum e such that, for a normalized
flonum @code{x}, @code{x} and @code{(* x (+ 1.0 e))} are distinguishable.
@item greatest-positive-flonum
Returns the greatest positive finite flonum.  It is
@code{DBL_MAX} in C.
@item least-positive-flonum
Returns the least positive flonum representable as floating-point
number.   If the platform supports denormalized flonum,
it returns the least positive denormalized floating-point number.  Otherwise,
it returns the least positive normalized floating-point number.
@item least-positive-normalized-flonum
Returns the least positive flonum representable as normalized floating-point
number.  It is @code{DBL_MIN} in C.
@end table
@c JP
それぞれ次の性質を持つ浮動小数点数を返します:
@table @code
@item flonum-epsilon
正規化浮動小数点数@code{x}に対し、@code{x}と@code{(* x (+ 1.0 e))}が
異なる値となるような最小の正の浮動小数点数。
@item greatest-positive-flonum
有限な最大の正の浮動小数点数。Cで言うところの@code{DBL_MAX}。
@item least-positive-flonum
最小の正の浮動小数点数。
プラットフォームが非正規化浮動小数点数をサポートしている場合は最小の
正の非正規化浮動小数点数が、そうでなければ
最小の正の正規化浮動小数点数が返ります。
@item least-positive-normalized-flonum
最小の正の正規化浮動小数点数。
@end table
@c COMMON

@c EN
NB: For portable programs, R7RS @code{scheme.flonum} module
provides constants @code{fl-epsilon}, @code{fl-greatest}, and
@code{fl-least} (@pxref{R7RS flonum}).
@c JP
註: ポータブルなプログラムは、R7RSの@code{scheme.flonum}が提供する
定数@code{fl-epsilon}、@code{fl-greatest}、@code{fl-least}を
使うことができます (@ref{R7RS flonum}参照)。
@c COMMON
@end defun

@defun flonum-min-normalized
@defunx flonum-min-denormalized
@c DEPRECATED
@c EN
These are old names for @code{least-positive-normalized-flonum} and
@code{least-positive-flonum}.  We renamed to make the semantics clear.

@itemize @bullet
@item
The new name alignes with @code{least-fixnum} and @code{greatest-fixnum}.
@item
@emph{Min} or @emph{least} could mean negative value farthest from zero.
Having @emph{positive} removes the ambiguity.
@item
Denormalized flonums may not be supported on the platform, so
having @emph{denormalized} in the name is misleading.
@end itemize
@c JP
これらは@code{least-positive-normalized-flonum}および
@code{least-positive-flonum}の旧い名前です。
意味を明確にするために名前を変えました。

@itemize @bullet
@item
新しい名前は@code{least-fixnum}/@code{greatest-fixnum}と統一性があります。
@item
@emph{min}や@emph{least}だけだと、ゼロから負の方向に一番離れている数の意味にも
取れるので、@emph{positive}をつけて曖昧性を排除しました。
@item
非正規化浮動小数点数はサポートされていないプラットフォームがあり得るので、
名前に@emph{denormalized}を入れるのを避けました。
@end itemize
@c COMMON
@end defun

@node Arithmetics, Numerical conversions, Numerical comparison, Numbers
@subsection Arithmetics
@c NODE 数値の演算

@defun + z @dots{}
@defunx * z @dots{}
[R7RS base]
@c EN
Returns the sum or the product of given numbers, respectively.
If no argument is given, @code{(+)} yields 0 and @code{(*)} yields 1.
@c JP
与えられた数の和と積をそれぞれ返します。引数が与えられない場合、
@code{(+)} は 0、 @code{(*)} は 1 となります。
@c COMMON
@end defun

@defun - z1 z2 @dots{}
@defunx / z1 z2 @dots{}
[R7RS base]
@c EN
If only one number @var{z1} is given, returns its
negation and reciprocal, respectively.

If more than one number are given, returns:
@example
@var{z1} - @var{z2} - @var{z3} @dots{}
@var{z1} / @var{z2} / @var{z3} @dots{}
@end example
respectively.
@c JP
一つだけ数値が与えられた場合、それぞれnegationと逆数を返します。

2つ以上の数値が与えられた場合、それぞれ次の結果を返します。
@example
@var{z1} - @var{z2} - @var{z3} @dots{}
@var{z1} / @var{z2} / @var{z3} @dots{}
@end example
@c COMMON

@example
(- 3)       @result{} -3
(- -3.0)    @result{} 3.0
(- 5+2i)    @result{} -5.0-2.0i
(/ 3)       @result{} 1/3
(/ 5+2i)    @result{} 0.172413793103448-0.0689655172413793i

(- 5 2 1)     @result{} 2
(- 5 2.0 1)   @result{} 2.0
(- 5+3i -i)   @result{} 5.0+2.0i
(/ 14 6)      @result{} 7/3
(/ 6+2i 2)    @result{} 3.0+1.0i
@end example

@c EN
Note: Gauche didn't have exact rational number support until 0.8.8;
before that, @code{/} coerced the result to inexact even if both
divisor and dividend were exact numbers, when the result wasn't
a whole number.  It is not the case anymore.

If the existing code relies on the old behavior, it runs
very slowly on the newer versions of Gauche, since the calculation
proceeds with exact rational arithmetics that is much slower than
floating point arithmetics.  You want to use @code{/.} below
to use fast inexact arithmetics (unless you
need exact results).
@c JP
註：0.8.8までGaucheは正確な有理数をサポートしておらず、
それ以前は除数と被除数がともに正確な数であっても商が整数にならなければ
結果は非正確な数へと変換されていました。今のGaucheはそうではありません。

既存のコードが以前のGaucheのふるまいを当てにしていた場合、
速度が大きく低下する可能性があります。正確な有理数の演算は
浮動小数点数の演算よりはるかに遅いからです。
(正確な結果を得たいのでない場合は)下に述べる@code{/.}を使うと良いでしょう。
@c COMMON
@end defun

@defun +. z @dots{}
@defunx *. z @dots{}
@defunx -. z1 z2 @dots{}
@defunx /. z1 z2 @dots{}
@c EN
Like @code{+}, @code{*}, @code{-}, and @code{/}, but the arguments
are coerced to inexact number.  So they always return inexact number.
These are useful when you know you don't need exact calculation
and want to avoid accidental overhead of bignums and/or exact
rational numbers.
@c JP
@code{+}、@code{*}、@code{-}、@code{/}と同様ですが、引数は非正確な
数へと変換され、結果も常に非正確な数となります。
正確数による計算が不要で、bignumや正確な有理数をうっかり使ってしまう
ことによるオーバヘッドを避けたい時に便利です。
@c COMMON
@end defun

@defun abs z
[R7RS+ base]
@c EN
For real number @var{z}, returns an absolute value of it.
For complex number @var{z}, returns the magnitude of the number.
The complex part is Gauche extension.
@c JP
実数の@var{z}に対しては、その絶対値を返します。
複素数の@var{z}に対しては、そのmagnitudeを返します。
複素数を扱うのはGaucheの拡張です。
@c COMMON
@example
(abs -1)   @result{} 1
(abs -1.0) @result{} 1.0
(abs 1+i)  @result{} 1.4142135623731
@end example
@end defun

@defun quotient n1 n2
@defunx remainder n1 n2
@defunx modulo n1 n2
[R7RS base]
@c EN
Returns the quotient, remainder and modulo of dividing an integer @var{n1}
by an integer @var{n2}.   The result is an exact number only if
both @var{n1} and @var{n2} are exact numbers.

Remainder and modulo differ when either one of the arguments is negative.
Remainder @var{R} and quotient @var{Q} have the following relationship.
@example
  @var{n1} = @var{Q} * @var{n2} + @var{R}
@end example
where @code{abs(@var{Q}) = floor(abs(@var{n1})/abs(@var{n2}))}.
Consequently, @var{R}'s sign is always the same as @var{n1}'s.

On the other hand, modulo works as expected for positive @var{n2},
regardless of the sign of @var{n1}
(e.g. @code{(modulo -1 @var{n2}) == @var{n2} - 1}).
If @var{n2} is negative, it is mapped to the positive case by
the following relationship.
@example
  modulo(@var{n1}, @var{n2}) = @minus{}modulo(@minus{}@var{n1}, @minus{}@var{n2})
@end example
Consequently, @var{modulo}'s sign is always the same as @var{n2}'s.
@c JP
整数@var{n1}を整数@var{n2}で割った商(quotient)および余り(remainder, modulo)
を返します。  @var{n1}と@var{n2}の両方が正確な数値の時のみ、戻り値は正確な数値になります。

@code{remainder}と@code{modulo} はどちらかの引数が負の時に異なる値を返します。
Remainder @var{R} と商 @var{Q} とは次の関係があります。
@example
  @var{n1} = @var{Q} * @var{n2} + @var{R}
@end example
ここで商について @code{abs(@var{Q}) = floor(abs(@var{n1})/abs(@var{n2}))}
ですから、@var{R}の符号は常に@var{n1}と同じになります。

一方、moduloは@var{n2}が正の時は@var{n1}の符号に関わらず期待したように動作します
(例: @code{(modulo -1 @var{n2}) == @var{n2} - 1})。
@var{n2}が負の場合は次の式によって正の場合にマップできます。
@example
  modulo(@var{n1}, @var{n2}) = @minus{}modulo(@minus{}@var{n1}, @minus{}@var{n2})
@end example
したがって、moduloの結果の符号は常に@var{n2}の符号と同じになります。
@c COMMON
@example
(remainder 10 3)    @result{} 1
(modulo 10 3)       @result{} 1

(remainder -10 3)   @result{} -1
(modulo -10 3)      @result{} 2

(remainder 10 -3)   @result{} 1
(modulo 10 -3)      @result{} -2

(remainder -10 -3)  @result{} -1
(modulo -10 -3)     @result{} -1
@end example
@end defun

@defun quotient&remainder n1 n2
@c EN
Calculates the quotient and the remainder of dividing integer @var{n1}
by integer @var{n2} simultaneously, and returns them as two values.
@c JP
整数@var{n1}を整数@var{n2}で割った商(quotient)および余り(remainder)
を同時に計算し、2つの値として返します。
@c COMMON
@end defun

@defun div x y
@defunx mod x y
@defunx div-and-mod x y
@defunx div0 x y
@defunx mod0 x y
@defunx div0-and-mod0 x y
[R6RS]
@c EN
These are integer division procedures introduced in R6RS.
Unlike @code{quotient}, @code{modulo} and @code{remainder},
these procedures can take non-integral values.
The dividend @var{x} can be an arbitrary real number,
and the divisor @var{y} can be non-zero real number.
@c JP
これらはR6RSで導入された整数除算手続きです。
@code{quotient}, @code{modulo}, @code{remainder}と違い、
これらの手続きは整数でない値を取ることもできます。
被除数@var{x}には任意の実数、除数@var{y}にはゼロ以外の実数が許されます。
@c COMMON

@c EN
@code{div} returns an integer @var{n}, and @code{mod} returns
a real number @var{m}, such that:

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}, and
@item
0 <= @var{m} < |@var{y}|.
@end itemize

Examples:
@c JP
@code{div}は整数@var{n}を、@code{mod}は実数@var{m}を返し、
それらは以下の関係を満たします。

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}
@item
0 <= @var{m} < |@var{y}|
@end itemize

例:
@c COMMON
@example
(div 123 10)     @result{} 12
(mod 123 10)     @result{} 3

(div 123 -10)    @result{} -12
(mod 123 -10)    @result{} 3

(div -123 10)    @result{} -13
(mod -123 10)    @result{} 7

(div -123 -10)   @result{} 13
(mod -123 -10)   @result{} 7

(div 123/7 10/9) @result{} 15
(mod 123/7 10/9) @result{} 19/21
;; 123/7 = 10/9 * 15 + 19/21

(div 14.625 3.75) @result{} 3.0
(mod 14.625 3.75) @result{} 3.375
;; 14.625 = 3.75 * 3.0 + 3.375
@end example

@c EN
For a nonnegative integer @var{x} and an integer @var{y},
The results of @code{div} and @code{mod} matches
those of @code{quotient} and @code{remainder}.  If @var{x}
is negative, they differ, though.
@c JP
@var{x}が非負の整数、@var{y}が整数である場合は、
@code{div}と@code{mod}の結果は@code{quotient}と@code{remainder}
の結果に一致します。しかし@var{x}が負になると結果は異なります。
@c COMMON

@c EN
@code{div-and-mod} calculates both @code{div} and @code{mod}
and returns their results in two values.
@c JP
@code{div-and-mod}は@code{div}と@code{mod}を同時に計算し、
結果を二つの値で返します。
@c COMMON

@c EN
@var{div0} and @var{mod0} are similar, except the range of @var{m}:
@c JP
@var{div0}と@var{mod0}は、@code{m}の値域が異なる以外は同じです。
@c COMMON

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}
@item
-|@var{y}|/2 <= @var{m} < |@var{y}|/2
@end itemize

@example
(div0 123 10)   @result{} 12
(mod0 123 10)   @result{} 3

(div0 127 10)   @result{} 13
(mod0 127 10)   @result{} -3

(div0 127 -10)  @result{} -13
(mod0 127 -10)  @result{} -3

(div0 -127 10)  @result{} -13
(mod0 -127 10)  @result{} 3

(div0 -127 -10) @result{} 13
(mod0 -127 -10) @result{} 3
@end example

@c EN
@code{div0-and-mod0} calculates both @code{div0} and @code{mod0}
and returns their results in two values.
@c JP
@code{div0-and-mod0}は@code{div0}と@code{mod0}を同時に計算し、
結果を二つの値で返します。
@c COMMON

@c EN
Here's a visualization of R6RS and R7RS division and modulo operations:
@url{http://blog.practical-scheme.net/gauche/20100618-integer-divisions}
It might help to grasp how they works.
@c JP
R6RSとR7RSの除算・剰余操作を可視化したものが
@url{http://blog.practical-scheme.net/gauche/20100618-integer-divisions}
にあります。
@c COMMON
@end defun

@defun floor-quotient n d
@defunx floor-remainder n d
@defunx floor/ n d
@defunx truncate-quotient n d
@defunx truncate-remainder n d
@defunx truncate/ n d
[R7RS base]
@c EN
These are integer division operators introduced in R7RS.  The names
explicitly indicate how they behave when numerator and/or denominator
is/are negative.

The arguments @var{n} and @var{d} must be an integer.  If any of them are
inexact, the result is inexact.  If all of them are exact, the result is
exact.  Also, @var{d} must not be zero.

Given numerator @var{n}, denominator @var{d}, quotient @var{q} and
remainder @var{r}, the following relations are always kept.

@example
r = n - dq
abs(r) < abs(d)
@end example

Now, @code{(floor-quotient n d)} and @code{(truncate-quotient n d)}
are the same as @code{(floor (/ n d))} and
@code{(truncate (/ n d))}, respectively.
The @code{*-remainder} counterparts are
derived from the above relation.

The @code{/}-suffixed version, @code{floor/} and @code{truncate/},
returns corresponding quotient and remainder as two values.
@c JP
R7RSで導入された整数除算オペレータです。除数や被除数が負の場合の振る舞いが、
名前によって明示されています。

引数@var{n}と@var{d}は整数でなけばなりません。
両方とも正確数であれば結果は正確数に、一方でも非正確数であれば
結果は非正確数になります。また、@var{d}はゼロであってはなりません。

被除数@var{n}、除数@var{d}、商@var{q}、剰余@var{r}には常に以下の関係が成り立ちます。

@example
r = n - dq
abs(r) < abs(d)
@end example

@code{(floor-quotient n d)}と @code{(truncate-quotient n d)}はそれぞれ
@code{(floor (/ n d))}と@code{(truncate (/ n d))}と同じです。
対応する@code{*-remainder}は、上記の関係から導かれます。

@code{floor/} と @code{truncate/}は、対応する商と剰余を二つの値として返します。
@c COMMON

@example
(floor-quotient 10 -3)     @result{} -4
(floor-remainder 10 -3)    @result{} -2
(truncate-quotient 10 -3)  @result{} -3
(truncate-remainder 10 -3) @result{} 1
@end example

@c EN
R7RS division library (@code{scheme.division}) introduces
other variation of integer divisions
(@pxref{R7RS integer division}).
@c JP
R7RS除算ライブラリ(@code{scheme.division})では、
他の整数除算のバリエーションが定義されています。
(@ref{R7RS integer division}参照)。
@c COMMON
@end defun

@defun gcd n @dots{}
@defunx lcm n @dots{}
[R7RS base]
@c EN
Returns the greatest common divisor or the least common multiplier
of the given integers, respectively
@c JP
与えられた整数の、最大公約数と最小公倍数をそれぞれ返します。
@c COMMON

@c EN
Arguments must be integers, but doesn't need to be exact.
If any of arguments is inexact, the result is inexact.
@c JP
引数は整数でなければなりませんが、正確数である必要はありません。
引数が一つでも非正確なら、結果は非正確数になります。
@c COMMON
@end defun

@defun continued-fraction x
@c EN
Returns a lazy sequence of regular continued fraction expansion of
finite real number @var{x}.  An error is raised if @var{x} is infinite or
NaN, or not a real number.
The returned sequence is lazy, so the terms are calculated as needed.
@c JP
有限の実数@var{x}の正規連分数展開を、遅延シーケンスで返します。
@var{x}が無限大、NaN、または非実数の場合はエラーが報告されます。
返り値は遅延シーケンスなので、係数は必要になる度に計算されます。
@c COMMON

@example
(continued-fraction 13579/2468)
  @result{} (5 1 1 122 1 9)

(+ 5 (/ (+ 1 (/ (+ 1 (/ (+ 122 (/ (+ 1 (/ 9))))))))))
  @result{} 13579/2468

(continued-fraction (exact 3.141592653589793))
  @result{} (3 7 15 1 292 1 1 1 2 1 3 1 14 3 3 2 1 3 3 7 2 1 1 3 2 42 2)

(continued-fraction 1.5625)
  @result{} (1.0 1.0 1.0 3.0 2.0)
@end example
@end defun


@defun numerator q
@defunx denominator q
[R7RS base]
@c EN
Returns the numerator and denominator of a rational number @var{q}.
@c JP
有理数@var{q}の分子と分母をそれぞれ返します。
@c COMMON
@end defun

@defun rationalize x ebound
[R7RS base]
@c EN
Returns the simplest rational approximation @var{q} of a real number @var{x},
such that the difference between @var{x} and @var{q} is no more than
the error bound @var{ebound}.

Note that Gauche doesn't have inexact rational number, so if @var{x}
and/or @var{ebound} is inexact, the result is coerced to
floating point representation.  If you want an exact result,
coerce the arguments to exact number first.
@c JP
実数@var{x}を、誤差@var{ebound}以内で近似した最も単純な有理数@var{q}を返します。

Gaucheは非正確な有理数をサポートしないので、引数の少なくとも一方が非正確数だと
結果の有理数が浮動小数点数へと変換され非正確数として返されることに注意してください。
結果を正確数で得たい場合は、引数を正確数で渡してください。
@c COMMON

@example
(rationalize 1234/5678 1/1000) @result{} 5/23

(rationalize 3.141592653589793 1/10000)
  @result{} 3.141509433962264
(rationalize (exact 3.141592653589793) 1/10000)
  @result{} 333/106
(rationalize (exact 3.141592653589793) 1/10000000)
  @result{} 75948/24175

;; Some edge cases
(rationalize 2 +inf.0) @result{} 0
(rationalize +inf.0 0) @result{} +inf.0
(rationalize +inf.0 +inf.0) @result{} +nan.0
@end example
@end defun


@defun floor x
@defunx ceiling x
@defunx truncate x
@defunx round x
[R7RS base]
@c EN
The argument @var{x} must be a real number.
@code{Floor} and @code{ceiling} return a maximum integer that
isn't greater than @var{x} and a minimum integer that isn't less
than @var{x}, respectively.
@code{Truncate} returns an integer that truncates
@var{x} towards zero.  @code{Round} returns an integer that is closest
to @var{x}.  If fractional part of @var{x} is exactly 0.5, @code{round}
returns the closest even integer.
@c JP
引数@var{x}は実数でなければなりません。@code{floor}と@code{ceiling}はそれぞれ
@var{x}を越えない最大の整数と、@var{x}を下回らない最小の整数を返します。
@code{truncate}は@var{x}の小数部をゼロの方向に向かって切捨てた整数を返します。
@code{round}は@var{x}に最も近い整数を返します。@var{x}の
小数部が0.5ぴったりだった場合は@code{round}は最も近い偶数を返します。
@c COMMON

@c EN
Following Scheme's general rule, the result is inexact if @var{x} is an
inexact number; e.g. @code{(round 2.3)} is @code{2.0}.  If you need
an exact integer by rounding an inexact number, you have to use @code{exact}
on the result, or use one of the following procedure (@code{(floor->exact} etc).
@c JP
Schemeの一般的な規則に従い、@var{x}が非正確数であれば結果も非正確となります。
例えば@code{(round 2.3)}の結果は@code{2.0}です。
もし、非正確な数を丸めて正確な整数を得たいのであれば、結果に@code{exact}を
適用するか、以下に示す@code{floor->exact}などの手続きを使ってください。
@c COMMON
@end defun

@defun floor->exact x
@defunx ceiling->exact x
@defunx truncate->exact x
@defunx round->exact x
@c EN
These are convenience procedures of the popular
phrase @code{(exact (floor x))} etc.
@c JP
これらは、頻出する@code{(exact (floor x))} 等を簡潔に書くための
手続きです。
@c COMMON
@end defun

@defun clamp x :optional min max
@c EN
Returns
@example
 @var{min} @r{if} @var{x} @code{<} @var{min}
 @var{x}   @r{if} @var{min} @code{<=} @var{x} @code{<=} @var{max}
 @var{max} @r{if} @var{max} @code{<} @var{x}
@end example
If @var{min} or @var{max} is omitted or @code{#f}, it is regarded
as @code{-inf.0} or @code{+inf.0}, respectively.
Returns an exact integer only if all the given numbers are exact integers.
@c JP
@example
 @var{min} @r{if} @var{x} @code{<} @var{min}
 @var{x}   @r{if} @var{min} @code{<=} @var{x} @code{<=} @var{max}
 @var{max} @r{if} @var{max} @code{<} @var{x}
@end example
を返します。もし@var{min}または@var{max}が省略されるか@code{#f}が与えられたら、
それぞれ @var{-∞} もしくは @var{+∞} と解釈されます。
与えられた全ての数値が正確な整数の場合に限り正確な整数を返します。
@c COMMON
@example
(clamp 3.1 0.0 1.0) @result{} 1.0
(clamp 0.5 0.0 1.0) @result{} 0.5
(clamp -0.3 0.0 1.0) @result{} 0.0
(clamp -5 0)        @result{} 0
(clamp 3724 #f 256) @result{} 256
@end example
@end defun


@defun exp z
@defunx log z :optional base
@defunx sin z
@defunx cos z
@defunx tan z
@defunx asin z
@defunx acos z
@defunx atan z
@defunx atan y x
[R7RS inexact]
@c EN
Transcendental functions.  Work for complex numbers as well.
In R7RS, these procedures are in the @code{(scheme inexact)} module.
@c JP
超越関数です。複素数も扱えます。
R7RSではこれらの手続きは@code{(scheme inexact)}モジュールにあります。
@c COMMON

@c EN
@code{exp} returns @i{e} raised to the power of @var{z}.  The one-argument
version of @code{log} returns the natural logarithm of @var{z}.
The two-argument version of @code{log} is added in R6RS, and returns
base @var{base} logarithm of @var{z}.
@c JP
@code{exp}は@i{e}の@var{z}乗を返します。
1引数の@code{log}は@var{z}の自然対数を返します。
2引数の@code{log}はR6RSで追加されたもので、
@var{base}を底とした@var{z}の対数を返します。
@c COMMON

@c EN
The two-argument version of @code{atan} returns
@code{(angle (make-rectangular x y))} for the real numbers @code{x} and @code{y}.
@c JP
2引数の@code{atan}は
実数@var{x}と@var{y}に対して
@code{(angle (make-rectangular x y))}を返します。
@c COMMON

@c EN
See also @code{real-exp} etc. below, for real-only version of these functions.
@c JP
実数に限定したこれらの関数については、下の@code{real-exp}等も参照してください。
@c COMMON
@end defun

@defun sinh z
@defunx cosh z
@defunx tanh z
@defunx asinh z
@defunx acosh z
@defunx atanh z
@c EN
Hyperbolic trigonometric functions.  Work for complex numbers as well.

See also @code{real-sinh} etc. below, for real-only version of these functions.
@c JP
双曲線関数です。複素数も扱えます。

実数に限定したこれらの関数については、下の@code{real-sinh}等も参照してください。
@c COMMON
@end defun

@defun radians->degrees rad
@defunx degrees->radians deg
@c EN
Convert radians to degrees and vice versa.
The argument must be a real number.
@c JP
ラジアンと度を変換します。引数は実数でなければなりません。
@c COMMON
@end defun

@defun sqrt z
[R7RS inexact]
@c EN
Returns a square root of a complex number @var{z}.
The branch cut scheme is the same as Common Lisp.
For real numbers, it returns a positive root.

If @var{z} is the square of an exact real number, the return value
is also an exact number.
@c JP
複素数@var{z}の平方根のひとつを返します。枝刈りの定義はCommon Lispと同じです。
実数に対しては正の平方根を返します。

@var{z}が正確な実数の平方である場合、戻り値は正確数となります。
@c COMMON

@example
(sqrt 2)      @result{} 1.4142135623730951
(sqrt -2)     @result{} 0.0+1.4142135623730951i
(sqrt 256)    @result{} 16
(sqrt 256.0)  @result{} 16.0
(sqrt 81/169) @result{} 9/13
@end example

@c EN
See also @code{real-sqrt} below, for inexact-real-only version of @code{sqrt}.
@c JP
不正確な実数に限定した@code{sqrt}については、下の@code{real-sqrt}も参照してください。
@c COMMON
@end defun

@defun exact-integer-sqrt k
[R7RS base]
@c EN
Given an exact nonnegative integer @var{k},
returns two exact nonnegative integer @var{s} and @var{r}
that satisfy the following equations:
@c JP
非負の正確な整数@var{k}に対し、次の式を満たす
非負の正確な整数@var{s}と@var{r}を返します。
@c COMMON

@example
@var{k} = (+ (* @var{s} @var{s}) @var{r})
@var{k} < (* (+ @var{s} 1) (+ @var{s} 1))
@end example

@example
(exact-integer-sqrt 782763574)
  @result{} 27977 @r{and} 51045
@end example
@end defun


@defun square z
[R7RS base]
@c EN
Returns @code{(* z z)}.
@c JP
@code{(* z z)}を返します。
@c COMMON
@end defun

@defun expt z1 z2
[R7RS base]
@c EN
Returns @var{z1}^@var{z2} (@var{z1} powered by @var{z2}),
where @var{z1} and @var{z2} are complex numbers.
@c JP
複素数@var{z1}, @var{z2}に対して、
@var{z1}^@var{z2} (@var{z1}の@var{z2}乗)を返します。
@c COMMON

@c EN
Scheme standard defines @code{(expt 0 0)} as 1 for convenience.
@c JP
Scheme標準では便宜上@code{(expt 0 0)}は1と定めています。
@c COMMON
@end defun

@defun expt-mod base exponent mod
@c EN
Calculates @code{(modulo (expt base exponent) mod)} efficiently.

The next example shows the last 10 digits of a mersenne prime
M_74207281 (2^74207281 - 1)
@c JP
@code{(modulo (expt base exponent) mod)} を効率よく計算します。

次の例は、メルセンヌ素数M_74207281 (2^74207281 - 1) の最後の10桁を
求めます。
@c COMMON

@example
(- (expt-mod 2 74207281 #e1e10) 1)
 @result{} 1086436351
@end example
@end defun

@defun real-exp x
@defunx real-expt x y
@defunx real-ln x
@defunx real-sqrt x
@defunx real-sin x
@defunx real-cos x
@defunx real-tan x
@defunx real-asin x
@defunx real-acos x
@defunx real-atan x
@defunx real-atan y x
[SRFI-94]
@c EN
Real-only version of elementary functions.  An error is signaled
unless the arguments are real numbers.

These are useful for performance-sensitive code, for they don't need to
check whether the input is complex.  Furthermore, they are subject to
constant folding.

Those names are defined in SRFI-94.  However, for the portable programs,
you may want to use @code{scheme.flonum} module, which is a part of
R7RS-large and defines
flonum-only versions of elementary functions (@pxref{R7RS flonum}).
@c JP
実数の範囲に限定した初等関数です。引数が実数でなかったらエラーが投げられます。

性能を気にするコードでは有用です。複素数の処理のためのチェックが省かれるのと、
定数畳み込みが行われやすくなります。

これらの名前はSRFI-94で定義されています。ただ、今ポータブルなコードを書きたいなら、
R7RS-largeの一部である@code{scheme.flonum}を使う方が良いでしょう。
そこではflonum限定の初等関数が定義されています(@ref{R7RS flonum}参照)。
@c COMMON

@c EN
Note: SRFI-94 defines @code{real-log}, which is a two-argument version
of real-only @code{log}, but it takes base argument first, which is
different from R7RS two-argument @code{log}.  To avoid confusion,
we don't support @code{real-log} in the core.
@c JP
註：SRFI-94は実数限定の2引数の@code{log}である@code{real-log}も定義しているのですが、
対数の底を最初の引数に取るようになっていて、R7RSの@code{log}とは逆です。
混乱を避けるため、コアでは@code{real-log}は提供していません。
@c COMMON
@end defun

@defun real-sinpi x
@defunx real-cospi x
@defunx real-tanpi x
@c EN
Returns sin(πx), cos(πx), and tan(πx), respectively.
An error is signaled if the argument is not a real number.
These come handy sometimes, as the following example show:
@c JP
それぞれsin(πx)、cos(πx)、tan(πx)を返します。
引数が実数でなければエラーを投げます。
下の例が示すように、これらはしばしば便利です：
@c COMMON

@example
(use math.const)
(real-sin pi)     @result{} 1.2246467991473532e-16
(real-sinpi 1.0)  @result{} 0.0

(real-cos (/ pi 2)) @result{} 6.123233995736766e-17
(real-cospi 0.5)    @result{} 0.0
@end example
@end defun

@defun real-sinh x
@defunx real-cosh x
@defunx real-tanh x
@defunx real-asinh x
@defunx real-acosh x
@defunx real-atanh x
@c EN
Real-only version of hyperbolic functions and their inverses.
An error is signaled if the argument is not a real number.
@c JP
実数限定の双曲線関数とその逆関数です。
引数が実数でなければエラーが投げられます。
@c COMMON
@end defun

@defun gamma z
@defunx log-gamma z
@c EN
Gamma function and natural logarithmic of Gamma function.
This is complex-domain function.
@c JP
ガンマ関数と、ガンマ関数の自然対数です。これは複素関数です。
@c COMMON
@end defun

@defun real-gamma x
@defunx real-log-gamma x
@defunx real-log-abs-gamma x
@c EN
Real-only version of gamma, log-gamma, and log of absolute value of gamma.

Note: C's math function @code{lgamma} is log of absolute value of gamma.
Taking absolute value allows it defined in all real values
(it returns @code{+inf.0} for nonpositive integers).
For the continuity of complex domain @code{log-gamma}, we provide
@code{real-log-gamma}, which throws an error for the input when
@code{gamma} gets negative.
@code{lgamma} function is provided as  @code{real-log-abs-gamma}
to avoid confusion.
@c JP
実数限定のガンマ関数、ガンマ関数の対数、そしてガンマ関数の絶対値の対数です。

註: Cの算術関数@code{lgamma}はガンマの絶対値の自然対数を返します。
絶対値を取ることで実数全域で定義されるからです (ゼロおよび負の整数に対しては
@code{+inf.0}を返します)。
複素関数としての@code{log-gamma}との連続性のため、@code{real-log-gamma}
はガンマの値が負になる入力に対してはエラーを投げます。
@code{lgamma}の機能は@code{real-log-abs-gamma}の名で提供されます。
@c COMMON
@end defun


@c NB: These should be moved to a separate subsection once we got
@c more fixnum-specific operation support.

@defun fixnum-width
@defunx greatest-fixnum
@defunx least-fixnum
[R6RS]
@c EN
These procedures return the width of fixnum (@var{w}),
the greatest integer representable by fixnum (@code{2^(@var{w}-1) - 1}),
and the least integer representable by fixnum (@code{- 2^(@var{w}-1)}),
respectively.  You might want to care the fixnum range when
you are writing a performance-critical section.

These names are defined in R6RS.  Common Lisp and ChezScheme have
@code{most-positive-fixnum} and @code{most-negative-fixnum}.
@c JP
これらの手続きは、fixnumで表現できる数値の幅 (@var{w}とします)、
fixnumで表現できる最大の整数値 (@code{2^(@var{w}-1) - 1})、および
fixnumで表現できる最小の整数値 (@code{- 2^(@var{w}-1)}) を
それぞれ返します。性能が重要になる部分では数値がfixnumの範囲に収まるかどうかを
気にかける必要があります。

これらの名前はR6RSで定義されました。Common LispとChezSchemeには
@code{most-positive-fixnum}および@code{most-negative-fixnum}があります。
@c COMMON

@c EN
NB: Before 0.9.5, @code{fixnum-width} had a bug
to return one smaller than the supposed value.
@c JP
註: 0.9.5以前の@code{fixnum-width}には本来より1小さい値を返すバグがありました。
@c COMMON
@end defun

@node Numerical conversions, Basic bitwise operations, Arithmetics, Numbers
@subsection Numerical conversions
@c NODE 数値の変換

@defun make-rectangular x1 x2
@defunx make-polar x1 x2
[R7RS complex]
@c EN
Creates a complex number from two real numbers, @var{x1} and @var{x2}.
@code{make-rectangular} returns @var{x1} + @b{i}@var{x2}.
@code{make-polar} returns @var{x1}@b{e}^(@b{i}@var{x2}).

In R7RS, these procedures are in the @code{(scheme complex)} library.
@c JP
二つの実数@var{x1}と@var{x2}から複素数を作ります。
@code{make-rectangular} は @var{x1} + @b{i}@var{x2} を返します。
@code{make-polar} は @var{x1}@b{e}^(@b{i}@var{x2}) を返します。

R7RSではこれらの手続きは@code{(scheme complex)}ライブラリにあります。
@c COMMON
@end defun

@defun real-part z
@defunx imag-part z
@defunx magnitude z
@defunx angle z
[R7RS complex]
@c EN
Decompose a complex number @var{z} and returns a real number.
@code{real-part} and @code{imag-part} return @var{z}'s real and imaginary
part, respectively.  @code{magnitude} and @code{angle} return
@var{z}'s magnitude and angle, respectively.

In R7RS, these procedures are in the @code{(scheme complex)} library.
@c JP
複素数@var{z}を取り、実数を返します。
@code{real-part}と@code{imag-part}は@var{z}の実数部と虚数部をそれぞれ返し、
@code{magnitude}と@code{angle}は@var{z}の絶対値と偏角をそれぞれ返します。

R7RSではこれらの手続きは@code{(scheme complex)}ライブラリにあります。
@c COMMON
@end defun

@defun decode-float x
@c EN
For a given finite floating-point number, returns
a vector of three exact integers, @code{#(@var{m}, @var{e}, @var{sign})},
where
@example
  @var{x} = (* @var{sign} @var{m} (expt 2.0 @var{e}))
  @var{sign} is either 1, 0 or -1.
@end example

If @var{x} is @code{+inf.0} or @code{-inf.0}, @var{m} is @code{#t}.
If @var{x} is @code{+nan.0}, @var{m} is @code{#f}.

The API is taken from ChezScheme.
@c JP
与えられた有限の浮動小数点数@var{x}に対して、
3つの正確な整数からなるベクタ @code{#(@var{m}, @var{e}, @var{sign})}
を返します。ここで、
@example
  @var{x} = (* @var{sign} @var{m} (expt 2.0 @var{e}))
  @var{sign} は 1, 0 または -1.
@end example
です。

特例として、@var{x}が@code{+inf.0}もしくは@code{-inf.0}の時は
@var{m}が@code{#t}に、
@var{x}が@code{+nan.0}の時は@var{m}が@code{#f}になります。

このAPIはChezSchemeから取られました。
@c COMMON

@example
(decode-float 3.1415926)
 @result{} #(7074237631354954 -51 1)
(* 7074237631354954 (expt 2.0 -51))
 @result{} 3.1415926

(decode-float +nan.0)
 @result{} #(#f 0 -1)
@end example
@end defun

@defun encode-float vector
@c EN
This is an inverse of @code{decode-float}.  @var{Vector} must be
a three-element vector as returned from @code{decode-float}.
@c JP
これは@code{decode-float}の逆関数です。@var{vector}は
@code{decode-float}が返す形式の3要素のベクタでなければなりません。
@c COMMON

@example
(encode-float '#(7074237631354954 -51 1))
 @result{} 3.1415926

(encode-float '#(#t 0 1))
 @result{} +inf.0
@end example
@end defun


@defun fmod x y
@defunx modf x
@defunx frexp x
@defunx ldexp x n
[POSIX]
@c EN
These procedures can be used to compose and decompose floating
point numbers.  @code{Fmod} computes the remainder of dividing @var{x}
by @var{y}, that is, it returns @var{x}-@var{n}*@var{y} where
@var{n} is the quotient of @var{x}/@var{y} rounded towards zero
to an integer.   @code{Modf} returns two values; a fractional
part of @var{x} and an integral part of @var{x}.   @code{Frexp}
returns two values, @var{fraction} and @var{exponent} of @var{x},
where @var{x} = @var{fraction} * 2^@var{exponent}, and
0.5 <= |@var{fraction}| < 1.0, unless @var{x} is zero.
(When @var{x} is zero, both @var{fraction} and @var{exponent} are zero).
@var{Ldexp} is a reverse operation of
@code{frexp}; it returns a real number @var{x} * 2^@var{n}.
@c JP
これらの手続きは、浮動小数点数を分解したり合成するのに使えます。
@code{fmod}は実数@var{x}を実数@var{y}で割った余りを返します。すなわち、
@var{x}/@var{y}を0に近いほうの整数に丸めた値を@var{n}とするとき、
@var{x}-@var{n}*@var{y}を返します。
@code{modf}は@var{x}の少数部と整数部を返します。
@code{frexp}は実数@var{x}を、仮数部と指数部に分解して返します。すなわち、
@var{x}が0でない限り、
@var{x} = @var{fraction} * 2^@var{exponent} かつ 0.5 <= |@var{fraction}| < 1.0
であるところの@var{fraction}と@var{exponent}を返します。
(@var{x}が0であれば、@var{fraction}と@var{exponent}はともに0となります。)
@code{ldexp}は@code{frexp}の逆関数で、@var{x} * 2^@var{n} を返します。
@c COMMON

@example
(fmod 32.1 10.0)  @result{} 2.1
(fmod 1.5 1.4)    @result{} 0.1
(modf 12.5)       @result{} 0.5 @r{and} 12.0
(frexp 3.14)      @result{} 0.785 @r{and} 2
(ldexp 0.785 2)   @result{} 3.14
@end example
@end defun

@c @defun logb x
@c @defunx ilogb x
@c [POSIX]
@c @c EN
@c These procedure returns exponent of flonum @var{x}.  The return value
@c of @code{logb} is a flonum, whereas the return value of @code{ilogb} is
@c an exact integer.

@c If @var{x} is 0, infinity, or NaN, @code{logb} returns @code{-inf.0},
@c @code{+inf.0} and @code{+nan.0}, respectively.  What @code{ilogb} returns
@c in those cases are platform-dependent, but it's consistent in one platform,
@c @c JP
@c 浮動小数点数@var{x}の指数部を返します。@code{logb}の戻り値は浮動小数点数、
@c @code{ilogb}の戻り値は正確な整数です。

@c @var{x}が0、±無限大、NaNの場合、@code{logb}はそれぞれ@code{-inf.0}、
@c @code{+inf.0}、@code{+nan.0}を返します。これらの場合に@code{ilogb}が返す値は
@c プラットフォームに依存しますが、一つのプラットフォームの上では一貫しています。
@c @c COMMON

@c @example
@c (logb 1)  @result{} 0.0
@c (ilogb 1) @result{} 0

@c (logb  2) @result{} 1.0
@c (logb -2) @result{} 1.0
@c (logb -0.5) @result{} -1.0

@c (logb 5.0e-324) @result{} -1074.0
@c (logb 1.7976931348623157e308) @result{} 1023.0

@c (logb 0) @result{} -inf.0
@c (logb +inf.0) @result{} +inf.0
@c (logb -inf.0) @result{} +inf.0
@c (logb +nan.0) @result{} +nan.0

@c (ilogb 0) @result{} -2147483648 ;; platform dependent
@c (ilogb +inf.0) @result{} 2147483647 ;; platform dependent
@c (ilogb +nan.0) @result{} -2147483648 ;; platform dependent
@c @end example
@c @end defun


@defun exact z
@defunx inexact z
[R7RS base]
@c EN
Returns an exact or an inexact representation of the
given number @var{z}, respectively.  Passing an exact number
to @code{exact}, and an inexact number to @code{inexact}, are no-op.

Gauche doesn't have exact complex number with non-zero imaginary part,
nor exact infinites and NaNs, so passing those to @code{exact} raises
an error.
@c JP
それぞれ数@var{z}の正確な表現および非正確な表現を返します。
正確数を@code{exact}に渡した場合や、非正確数を@code{inexact}に渡した場合は
渡した値がそのまま返されます。

Gaucheは、虚部がゼロでない正確な複素数や、正確な無限大/NaNをサポートしないので、
これらの数が@code{exact}に渡された場合はエラーとなります。
@c COMMON

@example
(inexact 1)    @result{} 1.0
(inexact 1/10) @result{} 0.1
@end example

@c EN
If an inexact finite real number is passed to @code{exact},
the simplest exact rational number within the precision of the
floating point representation is returned.
@c JP
非正確で有限な実数が@code{exact}に渡された場合は、
浮動小数点数演算の精度の中で最も簡単な表現となる正確な有理数が返されます。
@c COMMON

@example
(exact 1.0)     @result{} 1
(exact 0.1)     @result{} 1/10
(exact (/ 3.0)) @result{} 1/3
@end example

@c EN
For all finite inexact real number @var{x},
@code{(inexact (exact @var{x}))} is always @code{eqv?} to
the original number @var{x}.
@c JP
あらゆる有限の非正確な実数@var{x}について、
@code{(inexact (exact @var{x}))} は常に元の数@var{x}と
@code{eqv?}になります。
@c COMMON

@c EN
(Note that the inverse doesn't hold, that is, an exact number @var{n}
and @code{(exact (inexact @var{n}))} aren't necessarily the same.
It's because many (actually, infinite number of) exact numbers
can be mapped to one inexact number.)
@c JP
(その逆、つまり正確数 @var{n} と @code{(exact (inexact @var{n}))} は
必ずしも等しくならないことに注意してください。
ある非正確数へと写像される正確数は無数にあり得るためです。)
@c COMMON

@c EN
To specify the error tolerance when converting inexact real numbers
to exact rational numbers, use @code{rationalize} or @code{real->rational}.
@c JP
誤差の許容範囲を指定して非正確な実数を正確な有理数に直したい場合は、
@code{rationalize}および@code{real->rational}を参照してください。
@c COMMON
@end defun

@defun exact->inexact z
@defunx inexact->exact z
[R5RS]
@c EN
Converts exact number to inexact one, and vice versa.

In fact, @code{exact->inexact} returns the argument as is
if an inexact number is passed, and @code{inexact->exact}
returns the argument if an exact number is passed, so
in Gauche they are equivalent to @code{inexact} and @code{exact},
respectively.  Note that other R5RS implementation may raise
an error if passing an inexact number to @code{exact->inexact},
for example.

Generally @code{exact} and @code{inexact} are preferred,
for they are more concise, and you don't need to care
whether the argument is exact or inexact numbers.
These procedures are for compatibility with R5RS programs.
@c JP
それぞれ、正確数を非正確に変換、あるいはその逆を行います。

非正確な数を@code{exact->inexact}に渡したり、または正確な数を
@code{inexact->exact}に渡した場合、Gaucheではそれをエラーにせず
引数をそのまま返します。従ってこれらはGaucheでは
上の@code{inexact}および@code{exact}とそれぞれ等価です。
R5RS実装の中には、非正確数を@code{exact->inexact}に渡したりすると
エラーになるものもあり得るので、ポータブルなコードを書く場合は
注意してください。

一般的には、@code{exact}および@code{inexact}を使う方が
簡潔で良いでしょう。こちらの手続きはR5RSプログラムとの互換性の
ために用意されています。
@c COMMON
@end defun

@defun real->rational x :optional hi lo open?
@c EN
Find the simplest rational representation of a finite real
number @var{x} within the specified error bounds.  This is the low-level
routine called by @code{rationalize} and @code{exact}.
Typically you want to use @code{rationalize} (@pxref{Arithmetics})
for this purpose.  Use @code{real->rational} only when you need finer
control of error bounds.
@c JP
指定されたエラー範囲の中で、有限な実数@var{x}の正確な有理数表現のうち
最も簡単なものを返します。@code{rationalize}や@code{exact}はこの手続きを
下請けとして呼び出しています。通常は@code{rationalize} (@ref{Arithmetics}参照)
を使い、@code{real->rational}は誤差許容値をより細かく制御したい時のみ
使うのが良いでしょう。
@c COMMON

@c EN
The result
rational value @var{r} satisfies the following condition:
@c JP
返される有理数は次の条件を満たします。
@c COMMON

@example
(<= (- x lo) r (+ x hi))   ; when open? is #f
(<  (- x lo) r (+ x hi))   ; otherwise
@end example

@c EN
Note that both @var{hi} and @var{lo} must be nonnegative.

If @var{hi} and/or @var{lo} is omitted, it is determined by @var{x}:
if @var{x} is exact, @var{hi} and @var{lo} are defaulted to zero; if
@var{x} is inexact, @var{hi} and @var{lo} depend on
the precision of the floating point representation of @var{x}.
In the latter case, the @var{open?} also depends on @var{x}---it is true
if the mantissa of @var{x} is odd, and false otherwise, reflecting
the round-to-even rule.   So, if you call @code{real->rational} with
one finite number, you'll get the same result as @code{exact}:
@c JP
@var{hi}と@var{lo}は非負でなければなりません。

@var{hi}と@var{lo}の両方、もしくは一方が省略された場合、それは@var{x}の値に応じて
決定されます。@var{x}が正確数の場合、省略された@var{hi}/@var{lo}はゼロとみなされます。
@var{x}が非正確数の場合は、@var{x}の浮動小数点数表現の精度に基づいて
@var{hi}/@var{lo}が決定されます。後者の場合、@var{open?}の値もまた、
@var{x}の値で決まります。浮動小数点数の「偶数丸め」規則に対応して、
@var{x}の仮数部が奇数であれば@var{open?}は真、そうでなければ偽となります。
従って、@code{real->rational}にひとつの有限の数値だけを渡した場合、
その動作は@code{exact}と同じになります。
@c COMMON

@example
(real->rational 0.1) @result{} 1/10
@end example

@c EN
Passing zeros to the error bounds makes it return the exact
conversion of the floating number itself (that is, the exact
calculation of @code{(* sign mantissa (expt 2 exponent))}).
@c JP
エラー範囲にゼロを渡すと、引数の浮動小数点数の正確な数値表現
(つまり、@code{(* sign mantissa (expt 2 exponent))}を正確値で計算した結果)
が返されます。
@c COMMON

@example
(real->rational 0.1 0 0) @result{} 3602879701896397/36028797018963968
@end example

@c EN
(If you give both @var{hi} and @var{lo}, but omit @var{open?},
we assume closed range.)
@c JP
(@var{hi}と@var{lo}引数を与えて @var{open?}を省略した場合は、
閉じた範囲と考えます。)
@c COMMON
@end defun

@defun number->string z :optional base
@defunx number->string z :optional write-controls
[R7RS+ base]
@c EN
Converts a number @var{z} to its string representation.

The first form is specified in R7RS;
@var{radix} must be an exact integer between 2 and 36 inclusive,
the number is rendere with that radix.
If it is omitted, 10 is assumed.
If @var{z} is not an exact number, @var{radix} must be 10.

The second form is a Gauche extension, which allows more control
over the output format.  The optional argument is an instance of
@code{<write-controls>}.  @xref{Output controls}, for the details.
@c JP
数値@var{z}の文字列表現を返します。

最初の形式では、@var{radix}は2から36の間の正確な整数でなければなりません。
出力は@var{radix}進法で表現されます。
省略された場合は10とみなします。
@var{z}が正確数でない場合、@var{radix}は10でなければなりません。

二番目の形式はGaucheの拡張で、より細かい出力の制御を可能にします。
@var{write-controls}は@code{<write-controls>}のインスタンスです。
詳しくは@ref{Output controls}を参照してください。
@c COMMON

@example
(number->string 299792458) @result{} "299792458"
(number->string 299792458 16) @result{} "11de784a"

(number->string 299792458 (make-write-controls :base 16))
  @result{} "11de784a"

(number->string 1234/1000 (make-write-controls :exact-decimal #t))
  @result{} "#e1.234"
@end example
@end defun

@defun string->number string :optional radix default-exactness
@c EN
@code{String->number} takes a string @var{string} and parses it
as a number in radix @var{radix} system.  If the number contains
a decimal point, only radix 10 is allowed.  If the given string
can't be a number, @code{#f} is returned.

The @var{default-exactness} optional argument of @code{string->number}
is a Gauche's extension, and it must be either @code{#f} (default),
a symbol @code{exact}, or a symbol @code{inexact}.
If it is either symbol, it sets the exactness of the number if
no exactness prefix (@code{#e} or @code{#i}) is given.
If @var{string} has an exactness prefix, @var{default-exactness}
is irrelevant.
@c JP
@code{string->number}は文字列@var{string}を取り数値を返します。
入力が小数点を含んでいる場合は10進数表記しか認識されません。
与えられた文字列が数値を構成しない場合は@code{#f}が返されます。

@code{string->number}の省略可能引数@var{default-exactness}はGaucheの拡張で、
@code{#f} (デフォルト)あるいはシンボル@code{exact}または@code{inexact}の
いずれかでなければなりません。
シンボルが与えられた場合は、正確数か非正確数かがプレフィクス(@code{#e}もしくは@code{#i})
で明示されていない場合の正確性の解釈を指定します。
文字列に正確性のプレフィクスがついていた場合は@var{default-exactness}
の指定は無視されます。
@c COMMON

@example
(string->number "2.718281828459045" 10 'exact)
  @result{} 543656365691809/200000000000000
(string->number "#i2.718281828459045" 10 'exact)
  @result{} 2.718281828459045
(string->number "1/3" 10 'inexact)
  @result{} 0.3333333333333333
(string->number "#e1/3" 10 'inexact)
  @result{} 1/3
@end example
@end defun


@deffn {Generic Function} x->number obj
@deffnx {Generic Function} x->integer obj
@c EN
Generic coercion functions.  Returns `natural' interpretation of @var{obj}
as a number or an exact integer, respectively.
The default methods are defined for numbers and strings; a string is
interpreted by @code{string->number}, and if the string can't be
interpreted as a number, 0 is returned.
Other @var{obj} is simply converted to 0.
If @var{obj} is naturally interpreted
as a number that is not an exact integer, @code{x->integer} uses
@code{round} and @code{inexact->exact} to obtain an integer.

Other class may provide a method to customize the behavior.
@c JP
数値への強制型変換手続きです。
@var{obj}をそれぞれ数値もしくは正確な整数と解釈して返します。
数値と文字列に対してのメソッドは定義されています
(文字列は@code{string->number}を使って変換されます。
数値として解釈できない文字列に関しては0が返されます)。
その他の@var{obj}については単に0が返されます。
@code{x->integer}は、@var{obj}が数値として表現できるけれど正確な整数では
ない場合、@code{round}と@code{inexact->exact}によって正確な整数に変換します。

他のクラスはこのメソッドを定義することにより、独自の変換関数を提供することができます。
@c COMMON
@end deffn

@node Basic bitwise operations, Endianness, Numerical conversions, Numbers
@subsection Basic bitwise operations
@c NODE 基本的なビット演算

@c EN
These procedures treat integers as half-open bit vectors.
If an integer is positive, it is regarded as if infinite number
of zeros are padded to the left.  If an integer is negative,
it is regarded in 2's complement form, and infinite number of
1's are padded to the left.
@c JP
これらの手続きは整数を半無限のビットベクタとして扱います。
正の整数の場合、数値の左側に無限に0が続いていると見倣されます。
負の整数の場合、数値は2の補数で表現され、左側に無限に1が続いていると見倣されます。
@c COMMON

@c EN
In regard to the names of those operations, there are two groups
in the Scheme world; Gauche follows the names of the
original SLIB's ``logical'' module, which was rooted in CL.
Another group uses a bit long but descriptive name such as
@code{arithmetic-shift}.
@c JP
これらの操作の名前に関しては、Scheme界には大きく二つの流儀があります。
GaucheはSLIBの元々の``logical''モジュールに合わせました。
その起源はCommon Lispです。
もう一つの流儀では、@code{arithmetic-shift}といった、より長く記述的な名前を使います。
@c COMMON

@c EN
R7RS bitwise library
(@pxref{R7RS bitwise operations}) provides additional bitwise operations.
@c JP
R7RSビット演算ライブラリ(@pxref{R7RS bitwise operations})
は追加のビット演算を提供しています。
@c COMMON

@defun ash n count
[SRFI-60]
@c EN
Shifts integer @var{n} left with @var{count} bits.
If @var{count} is negative, @code{ash} shifts @var{n} right with
@minus{}@var{count} bits.
@c JP
整数@var{n}を左に整数@var{count}ビットだけシフトします。
@var{count}が負であれば、@minus{}@var{count}だけ@var{n}を右にシフトします。
@c COMMON

@example
; @r{Note: 6  @equiv{} [...00110], and}
; @r{      -6 @equiv{} [...11010]}
(ash 6 2)   @result{} 24  ;@r{[...0011000]}
(ash 6 -2)  @result{} 1   ;@r{[...0000001]}
(ash -6 2)  @result{} -24 ;@r{[...1101000]}
(ash -6 -2) @result{} -2  ;@r{[...1111110]}
@end example
@end defun

@defun logand n1 @dots{}
@defunx logior n1 @dots{}
@defunx logxor n1 @dots{}
[SRFI-60]
@c EN
Returns bitwise and, bitwise inclusive or and bitwise exclusive or
of integers @var{n1} @dots{}.   If no arguments are given, @code{logand}
returns @code{-1}, and @code{logior} and @code{logxor} returns @code{0}.
@c JP
整数@var{n1} @dots{}の、それぞれビット論理積、
ビット論理和、ビット排他的論理積を返します。
ゼロ個の引数が与えられた場合は、@code{logand}は@code{-1}を、
@code{logior}と@code{logxor}は@code{0}を返します。
@c COMMON
@end defun

@defun lognot n
[SRFI-60]
@c EN
Returns bitwise not of an integer @var{n}.
@c JP
整数@var{n}のビット否定を返します。
@c COMMON
@end defun

@defun logtest n1 n2 @dots{}
[SRFI-60]
@equiv{} @code{(not (zero? (logand @var{n1} @var{n2} @dots{})))}
@end defun

@defun logbit? index n
[SRFI-60]
@c EN
Returns @code{#t} if @var{index}-th bit of integer @var{n} is 1,
@code{#f} otherwise.
@c JP
整数@var{n}の@var{index}目のビットが1ならば@code{#t}を、0ならば@code{#f}を
返します。
@c COMMON
@end defun

@defun logset+clear n set-bits clear-bits
@c EN
Returns an integer such that @var{n}'s bit is set where @var{set-bits} is 1,
and cleared where @var{clear-bits} is 1.  If a bit is included in both
@var{set-bits} and @var{clear-bits}, it is cleared.

It is effectively the same as
@code{(logand (logior n set-bits) (lognot clear-bits))}.
@c JP
@var{n}のビットのうち、@var{set-bits}で1が立っているビットを立て、
@var{clear-bits}で1が立っているビットをクリアした整数を返します。

実質的に@code{(logand (logior n set-bits) (lognot clear-bits))}と同じです。
@c COMMON

@example
(logset+clear #b11000011 #b00001100 #b01000001)
  @result{} 142  ;; #b10001110
@end example
@end defun

@defun bit-field n start end
[R7RS bitwise]
@c EN
Extracts @var{start}-th bit (inclusive) to @var{end}-th bit (exclusive) from
an exact integer @var{n}, where @var{start} < @var{end}.
@c JP
整数@var{n}の@var{start}ビット目(含む)から@var{end}ビット目(含まない)までを
取り出した数値を返します。@var{start} < @var{end} でなければなりません。
@c COMMON
@end defun

@defun copy-bit index n bit
[R7RS bitwise]
@c EN
If @var{bit} is true, sets @var{index}-th bit of an exact integer @var{n}.
If @var{bit} is false, resets @var{index}-th bit of an exact integer @var{n}.
@c JP
@var{bit}が真の値なら、整数@var{n}の@var{index}ビット目をセットした数値を
返します。
@var{bit}が偽の値なら、整数@var{n}の@var{index}ビット目をリセットした数値を
返します。
@c COMMON
@end defun

@defun copy-bit-field n from start end
[SRFI-60]
@c EN
Returns an exact integer, each bit of which is the same as
@var{n} except the @var{start}-th bit (inclusive) to @var{end}-th
bit (exclusive), which is a copy of the lower
@code{(@var{end}-@var{start})}-th bits of an exact
integer @var{from}.
@c JP
正確な整数を返します。この整数の各ビットは@var{start}番目のビット(この
ビットを含む)から@var{end}番目のビット(このビットは含まない)の部分以外
は@var{n}と同じで、この区間のビットは、正確な数@var{from}の下位
@code{(@var{end}-@var{start})}ビットのコピーです。
@c COMMON

@example
(number->string (copy-bit-field #b10000000 -1 1 5) 2)
  @result{} "10011110"

(number->string (copy-bit-field #b10000000 #b010101010 1 7) 2)
  @result{} "11010100"
@end example

@c EN
Note: The API of this procedure was originally taken from SLIB,
and at that time,
the argument order was @code{(copy-bit-field n start end from)}.
During the discussion of SRFI-60 the argument order was changed
for the consistency, and the new versions of SLIB followed it.
We didn't realize the change until recently - before 0.9.4,
@emph{this procedure had the old argument order}.  Code that is using
this procedure needs to be fixed.  If you need your code to work
with both versions of Gauche, have the following definition
in your code.
@c JP
註：この手続きのAPIはSLIBから採られましたが、採用当時の引数の順序は
@code{(copy-bit-field n start end from)} でした。SRFI-60の
議論中に、一貫性のために引数順が変更され、SLIBの新しいバージョンも
それに追従しています。Gaucheではこの引数順の変更に最近まで気づいていなかったため、
0.9.4以前のバージョンでは@code{copy-bit-field}が古い引数順で定義されています。
この手続きを使っていたコードは0.9.4以降のGaucheで使う際に修正しなければなりません。
もしどちらのバージョンのGaucheでも動かす必要がある場合は、
回避策として@code{copy-bit-field}の定義を自前で持つのが良いでしょう。
@c COMMON

@example
(define (copy-bit-field to from start end)
  (if (< start end)
    (let1 mask (- (ash 1 (- end start)) 1)
      (logior (logand to (lognot (ash mask start)))
              (ash (logand from mask) start)))
    from))
@end example

@end defun

@defun logcount n
[SRFI-60]
@c EN
If @var{n} is positive, returns the number of @code{1}'s in the
bits of @var{n}.  If @var{n} is negative,
returns the number of @code{0}'s in the bits of 2's complement
representation of @var{n}.
@c JP
@var{n}が正なら、@var{n}のビットのうち@code{1}の個数を返します。@var{n}
が負なら、@var{n}の2に関する補数のビットのうち@code{0}の個数を返します。
@c COMMON

@c EN
@example
(logcount 0)      @result{} 0
(logcount #b0010) @result{} 1
(logcount #b0110) @result{} 2
(logcount #b1111) @result{} 4

(logcount #b-0001) @result{} 0  ;; 2's complement:  ....111111
(logcount #b-0010) @result{} 1  ;; 2's complement:  ....111110
(logcount #b-0011) @result{} 1  ;; 2's complement:  ....111101
(logcount #b-0100) @result{} 2  ;; 2's complement:  ....111100
@end example
@c JP
@example
(logcount 0)      @result{} 0
(logcount #b0010) @result{} 1
(logcount #b0110) @result{} 2
(logcount #b1111) @result{} 4

(logcount #b-0001) @result{} 0  ;; 2の補数:  ....111111
(logcount #b-0010) @result{} 1  ;; 2の補数:  ....111110
(logcount #b-0011) @result{} 1  ;; 2の補数:  ....111101
(logcount #b-0100) @result{} 2  ;; 2の補数:  ....111100
@end example
@c COMMON
@end defun

@defun integer-length n
[R7RS bitwise]
@c EN
Returns the minimum number of bits required to represent an
exact integer @var{n}.  Negative integer is assumed to be in
2's complement form.  A sign bit is not considered.
@c JP
正確な整数@var{n}を表現するのに必要な最小ビット数を返します。負の数は2
の補数で表現されるものと仮定しています。符号用のビットは考慮しません。
@c COMMON

@example
(integer-length 255)  @result{} 8
(integer-length 256)  @result{} 9

(integer-length -256)  @result{} 8
(integer-length -257)  @result{} 9
@end example
@end defun

@defun twos-exponent n
@c EN
If @var{n} is a power of two, that is, @code{(expt 2 k)} and @code{k >= 0},
then returns @code{k}.  Returns @code{#f} if @var{n} is not a power of two.
@c JP
@var{n}が2の冪乗@code{(expt 2 k)} (@code{k >= 0}) ならその冪 @code{k} を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun twos-exponent-factor n
@c EN
Returns maximum @var{k} such that @code{(expt 2 k)} is a factor of @var{n}.
In other words, returns the number of consecutive zero bits from LSB
of @var{n}.  When @var{n} is zero, we return @code{-1} for the
consistency of the following equivalent expression.
@c JP
@code{(expt 2 k)}が@var{n}の約数であるような最大の@var{k}を返します。
言い換えれば、@var{n}のLSBから連続するゼロビットの数を返します。
ただし@var{n}がゼロの場合は、下の等価式との一貫性から@code{-1}が返されます。
@c COMMON

@c EN
This can be calculated by the following expression; this procedure
is for speed to save creating intermediate numbers when @var{n} is bignum.
@c JP
これは次の式でも計算できますが、この手続きは@var{n}がbignumの場合にも
中間結果を作らないので若干速いです。
@c COMMON
@example
(- (integer-length (logxor n (- n 1))) 1)
@end example

@c EN
This procedure is also equivalent to SRFI-60's @code{log2-binary-factors} and
@code{first-set-bit} (@pxref{Integers as bits}).
@c JP
この手続きはまた、SRFI-60の@code{log2-binary-factors}および
@code{first-set-bit}と等価です(@ref{Integers as bits}参照)。
@c COMMON
@end defun

@node Endianness,  , Basic bitwise operations, Numbers
@subsection Endianness
@c NODE エンディアンネス

@c EN
In the Scheme world you rarely need to know about how the numbers
are represented inside the machine.  However, it matters
when you have to exchange data to/from the outer world in
binary representation.
@c JP
Schemeの世界では、数値がマシン上でどのように表現されているかを気にする
必要はほとんどありません。しかし、外の世界とバイナリ表現でデータを
やりとりする場合はそれが問題になります。
@c COMMON

@c EN
Gauche's binary I/O procedures, such as in
the @code{binary.io} module (@pxref{Binary I/O}) and
@code{write-uvector}/@code{read-uvector!}
(@pxref{Uniform vectors}), take optional @var{endian} argument
to specify the endianness.
@c JP
@code{binary.io}モジュール(@ref{Binary I/O}参照)や
@code{write-uvector}/@code{read-uvector!}(@ref{Uniform vectors}参照)
等、Gaucheのバイナリ入出力手続きはバイトオーダーを指定する
省略可能な@var{endian}引数を取ります。
@c COMMON

@c EN
Currently Gauche recognizes the following endiannesses.
@c JP
エンディアンの指定には次のシンボルを使います。
@c COMMON

@table @code
@item big-endian
@itemx big
@c EN
Big-endian.  With this endianness, a 32-bit integer @code{#x12345678}
will be written out as an octet sequence @code{#x12 #x34 #x56 #x78}.

Gauche has been using @code{big-endian}, but @code{scheme.bytevector}
incorporated in R7RS uses @code{big}, so we recognize both.
@c JP
ビッグエンディアン。32ビット整数値@code{#x12345678}は@code{#x12 #x34 #x56 #x78}
のようなバイトシーケンスとして出力されます。

Gaucheはずっと@code{big-endian}を使ってきましたが、
R7RS-largeに取り入れられた@code{scheme.bytevector}が@code{big}を使うので、
両方認識するようになっています。
@c COMMON
@item little-endian
@itemx little
@c EN
Little-endian.  With this endianness, a 32-bit integer @code{#x12345678}
is written out as an octet sequence @code{#x78 #x56 #x34 #x12}.

Gauche has been using @code{little-endian}, but @code{scheme.bytevector}
incorporated in R7RS uses @code{little}, so we recognize both.
@c JP
リトルエンディアン。32ビット整数値@code{#x12345678}は@code{#x78 #x56 #x34 #x12}
のようなバイトシーケンスとして出力されます。

Gaucheはずっと@code{little-endian}を使ってきましたが、
R7RS-largeに取り入れられた@code{scheme.bytevector}が@code{little}を使うので、
両方認識するようになっています。
@c COMMON
@item arm-little-endian
@c EN
This is a variation of @code{little-endian}, and used in ARM
processors in some specific modes.  It works just like @code{little-endian},
except reading/writing double-precision floating point number (@code{f64}),
which is written as two little-endian 32bit words ordered by big-endian
(e.g. If machine register's representation is @code{#x0102030405060708},
it is written as @code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}.
@c JP
これは@code{little-endian}のバリエーションで、ARMプロセッサの
特定のモードで使われるものです。倍精度浮動小数点数以外は@code{little-endian}
と同様に動作します。倍精度浮動小数点数については、ふたつのリトルエンディアンワードが
ビッグエンディアンの順で書き出されます (例えばマシンレジスタ上でのビットパターンが
@code{#x0102030405060708}の場合、出力は
@code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}となります)。
@c COMMON
@end table

@c EN
When the @var{endian} argument is omitted, those procedures
use the parameter @code{default-endian}:
@c JP
@var{endian}引数が省略された場合は、これらの手続きはパラメータ@code{default-endian}の
値を使います。
@c COMMON

@deffn {Parameter} default-endian
@c EN
This is a dynamic parameter (@pxref{Parameters}) to specify
the endianness the binary I/O routines use when its @var{endian}
argument is omitted.  The initial value of this parameter is
the system's native endianness.
@c JP
これは、バイナリ入出力ルーチンで@var{endian}指定が省略された場合に
共通して使われるエンディアンを指定する動的パラメータです
(@ref{Parameters}参照)。
このパラメータの初期値はシステムのネイティブエンディアンです。
@c COMMON
@end deffn

@c EN
The system's native endianness can be queried with the following
procedure:
@c JP
システムのネイティブエンディアンは次の手続きで得られます。
@c COMMON

@defun native-endian
@c EN
Returns a symbol representing the system's endianness.
@c JP
システムのエンディアンを示すシンボルを返します。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Booleans, Undefined values, Numbers, Core library
@section Booleans
@c NODE 論理値

@deftp {Builtin Class} <boolean>
@clindex boolean
@c EN
A boolean class.  Only @code{#t} and @code{#f} belong to this class.
@c JP
論理値のクラスです。@code{#t}と@code{#f}のみがこのクラスのインスタンスです。
@c COMMON
@end deftp

@defun not obj
[R7RS base]
@c EN
Returns @code{#t} if and only if @var{obj} is @code{#f},
and returns @code{#f} otherwise.
@c JP
@var{obj}が@code{#f}の時のみ@code{#t}を返し、それ以外の場合は@code{#f}を
返します。
@c COMMON
@end defun

@defun boolean? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a boolean value.
@c JP
@var{obj}が論理値である場合に@code{#t}を返します。
@c COMMON
@end defun

@defun boolean obj
[SRFI-235]
@c EN
Returns @code{#f} iff @var{obj} is @code{#f}, and returns @code{#t}
otherwise.  Convenient to coerce a value to boolean.
@c JP
@var{obj}が@code{#f}であるとき@code{#f}を返し、それ以外の場合は@code{#t}を
返します。値を論理値に変換したい場合に便利です。
@c COMMON
@end defun

@defun boolean=? a b c @dots{}
[R7RS base]
@c EN
Every argument must be a boolean value.  Returns @code{#t} iff all
values are the same, @code{#f} otherwise.
@c JP
全ての引数は論理値でなければなりません。全ての引数が等しい場合に
@code{#t}が、そうでなければ@code{#f}が返ります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Undefined values, Pairs and lists, Booleans, Core library
@section Undefined values
@c NODE 未定義値

@c EN
While working with Gauche, sometimes you encounter
a value printed as @code{#<undef>}, an @emph{undefined} value.
@c JP
Gaucheで作業していると、しばしば未定義値 @code{#<undef>}
に出会うことがあるでしょう。
@c COMMON

@example
gosh> (if #f #t)
#<undef>
@end example

@c EN
It is a value used as a filler where the actual value doesn't matter,
or there's no other suitable value, or the binding hasn't been calculated.
@c JP
この値は、値そのものに意味が無いこと、
ほかにふさわしい値が無いこと、あるいは束縛する値がまだ計算されていないことを示します。
@c COMMON

@c EN
Do not confuse undefined values with unbound variables;
A variable can be bound to @code{#<undef>}, for it is just
an ordinary first-class value.  On the other hand, an
unbound variable means there's no value associated with the variable.
@c JP
未定義値と未束縛の変数を混同しないようにしてください。
@code{#<undef>}は通常の第一級の値であり、変数に束縛しておくこともできます。
未束縛の変数は文字通り、変数が束縛されていない、すなわち値を持たないことを意味します。
@c COMMON

@c EN
However, @code{#<undef>} may be used in certain
occasions to indicate that a value is not provided for
the variable.  For example,
the toplevel variable can be bound to @code{#<undef>} if it is
defined by @code{(define variable)} form (@pxref{Definitions}).
An optional procedure parameter
without default value is bound to @code{#<undef>} if an
actual argument is not given (@pxref{Making procedures}).

Note that it cannot be distinguished from the case
a value is actually provided, and the value just happens
to be @code{#<undef>}.  If you get an @code{#<undef>},
you can say at most is that the value doesn't matter.
You shouldn't let it carry too much meanings.
@c JP
しかし、場合によっては、変数に特定の値が提供されていないことを
示すのに@code{#<undef>}が使われることもあります。
例えば、トップレベル変数は、@code{(define variable)}の形式で定義された場合に
@code{#<undef>}に束縛されます(@ref{Definitions}参照)。
また、既定値をもたない省略可能引数に実引数が提供されなかった
場合、引数の値は@code{#<undef>}となります (@ref{Making procedures}参照)。

これは実際に@code{#<undef>}が初期値として、あるいは引数として渡された場合と区別がつかない
ことに注意してください。@code{#<undef>}を受け取ってわかることは、
せいぜいその値にたいした意味がないということくらいです。
@code{#<undef>}に大きな意味を持たせすぎないようにしましょう。
@c COMMON

@c EN
The @code{#<undef>} value is counted as true value in generalized
boolean context,
since it is not @code{#f}.  However, branching based on @code{#<undef>}
is dangerous---a procedure that is defined to return unspecified value
may merely returning @code{#<undef>} as a provisional value; it will
change the return value in future.  Since the return value isn't specified,
no one should be using it.  The code that tests such result value as
a generalized boolean may break if the procedure changes the return value.

In fact, we've found that there are quite a few code that accidentally tests
@code{#<undef>} return value in conditionals.  They can be seeds
for future bugs, so we warn when @code{#<undef>} value
is used in the test of branches.  You can suppress the warning with
setting the environment variable @code{GAUCHE_ALLOW_UNDEFINED_TEST}.

One typical case of such accidental use of @code{#<undef>} branching
is in @code{and-let*}; the following code assumes @code{display} always return
@code{#<undef>}, which is counted as a true value, and expects the control
to proceeed to the next clause.  It'll break if @code{display} ever changes
so that it may return @code{#f} in some cases.
@c JP
@code{#<undef>}は一般化された真偽値としては真の値とみなされます
(偽になるのは@code{#f}のみですから)。
しかし、@code{#<undef>}の値を見て分岐するコードは危険です。
というのも、戻り値が規定されていない手続きが暫定的に@code{#<undef>}を返している
場合が良くあるからです。でも、それは将来変更されるかもしれません。
戻り値が規定されていない以上、戻り値に依存するコードは無いはずだからです。
もしうっかり、その戻り値に基づいて分岐しているコードがあると、変更があったときに
壊れてしまいます。

実のところ、@code{#<undef>}に依存して分岐しているコードが結構多いことがわかりました。
これは将来のバグの芽となるので、@code{#<undef>}が分岐テストに現れた場合には
警告が出されます。この警告をオフにするには
環境変数@code{GAUCHE_ALLOW_UNDEFINED_TEST}をセットしてください。

@code{#<undef>}をうっかり分岐テストに使ってしまう良くあるパターンは、
@code{and-let*}です。次のコードでは、@code{display}がテスト節に現れていますが、
このコードは@code{display}が常に@code{#<undef>}を返しそれが真の値であることから
次のテスト節に進むことを期待しています。けれども、@code{display}が場合によっては@code{#f}を
返すように変更されたら、このコードは壊れてしまいます。
@c COMMON

@example
(and-let* ([var (foo x y z)]
           [ (display var) ]    ;; branch on #<undef>
           [baz (bar var)])
  ...)
@end example

@c EN
Being said that, there are a couple of procedures
to deal with undefined values.
@c JP
以上の注意を念頭においた上で、未定義値を扱うには
次の手続きが利用できます。
@c COMMON

@defun undefined? obj
@c EN
Returns @code{#t} iff @var{obj} is an undefined value.
@c JP
@var{obj}が未定義値である場合に限り@code{#t}を返します。
@c COMMON
@end defun

@defun undefined
@c EN
Returns an undefined value.
@c JP
未定義値を返します。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Pairs and lists, Symbols, Undefined values, Core library
@section Pairs and lists
@c NODE ペアとリスト

@c EN
Pairs and lists are one of the most fundamental data structure in Scheme.
Gauche core provides all standard list procedures, plus some useful
procedures that are commonly supported in lots of implementations.
If they are not enough, you can find more procedures in the modules
described in @ref{R7RS lists} and
@ref{Combination library}.
See also @ref{Collection framework} and
@ref{Sequence framework} for generic collection/sequence
operations.
@c JP
ペアとリストはSchemeにおける最も基本的なデータ構造のひとつです。
Gaucheのコアは全ての標準のリスト手続きと、多くのScheme実装に見られる
便利な手続きのいくつかを提供します。それらで足りない場合は
さらに多くの手続きが@ref{R7RS lists}、
@ref{Combination library}
といったモジュールで提供されています。
また、リストに限らないジェネリックなシーケンス/コレクションの操作が
@ref{Collection framework}と
@ref{Sequence framework}で提供されています。
@c COMMON

@menu
* Pair and null class::
* Mutable and immutable pairs::
* List predicates::
* List constructors::
* List accessors and modifiers::
* Walking over lists::
* Other list procedures::
* Association lists::
* Extended pairs and pair attributes::
@end menu

@node Pair and null class, Mutable and immutable pairs, Pairs and lists, Pairs and lists
@subsection Pair and null class
@c NODE pairクラスとnullクラス

@deftp {Builtin Class} <list>
@clindex list
@c EN
An abstract class represents lists.   A parent class of @code{<null>}
and @code{<pair>}.   Inherits @code{<sequence>}.

Note that a circular list is also an instance of the @code{<list>} class,
while @code{list?} returns false on the circular lists and
dotted lists.
@c JP
リストを表す抽象クラスで、クラス@code{<null>}とクラス@code{<pair>}の親クラスです。
クラス@code{<sequence>}を継承します。

循環リストやドットリストも@code{<list>}クラスのインスタンスですが、
@code{list?}は偽の値を返すことに注意して下さい。
@c COMMON
@lisp
(use srfi.1)
(list? (circular-list 1 2)) @result{} #f
(is-a? (circular-list 1 2) <list>) @result{} #t
@end lisp
@end deftp

@deftp {Builtin Class} <null>
@clindex null
@c EN
A class of empty list.  @code{()} is the only instance.
@c JP
空リストのクラスです。@code{()}がこのクラスの唯一のインスタンスです。
@c COMMON
@end deftp

@deftp {Builtin Class} <pair>
@clindex pair
@c EN
A class of pairs.
@c JP
ペアのクラスです。
@c COMMON
@end deftp

@node Mutable and immutable pairs, List predicates, Pair and null class, Pairs and lists
@subsection Mutable and immutable pairs
@c NODE 変更可能なペアと変更不可なペア

@c EN
A pair may be either mutable or immutable.  You can desctructively
modify mutable pairs with @code{set-car!}, @code{set-cdr!}, or other
destructive procedures (usually they have @code{!} at the end).
An error is signaled when you try to modify an immutable pair.
@c JP
ペアには変更可能なものと変更不可なものがあります。
変更可能なペアは、@code{set-car!}や@code{set-cdr!}等の破壊的変更手続き
(通常、名前の最後に@code{!}がついています)で変更することが可能です。
変更不可なペアを変更しようとするとエラーが報告されます。
@c COMMON

@c EN
In Gauche, both type of pairs can be treated the same unless you try
to modify them.  Both satisfies the predicate @code{pair?}.  If you
need to test specifically if a pair is immutable, use @code{ipair?}
(@pxref{List predicates}).
The traditional constructor @code{cons} creates a mutable pair; you
can create an immutable pair with @code{ipair} (@pxref{List constructors}).
More procedures that use immutable pairs are defined in
R7RS-large @code{scheme.ilist} module (@pxref{R7RS immutable lists}).
@c JP
Gaucheでは、変更しようとしない限り、どちらのペアも全く同じように振る舞います。
@code{pair?}にはどちらも真を返します。ペアが変更不可であることを調べたければ
@code{ipair?}が使えます(@ref{List predicates}参照)。
伝統的なコンストラクタ@code{cons}は変更可能なペアを作ります。
変更不可なペアを作るには@code{ipair}を使ってください (@ref{List constructors}参照)。
変更不可なペアを特に扱う手続きは、R7RS-largeの@code{scheme.ilist}モジュールに
定義されています (@ref{R7RS immutable lists}参照)。
@c COMMON

@c EN
Note that quoted literals are immutable.
Old versions of Gauche wasn't supported immutable pairs and quoted literal lists
were mutable.  If your code accidentally mutate such pairs, you'll get an
error.  If you need to run such code without tracking down the error,
you can define the environment variable
@code{GAUCHE_MUTABLE_LITERALS}.
@c JP
クオートされたリテラルは変更不可です。
ただ、古いバージョンのGaucheは変更不可なペアを持っておらず、クオートされたリテラルリストも
変更可能でした。その頃に書かれたコードでうっかりリテラルを変更していたら、
現在のGaucheではエラーになってしまうでしょう。
問題を修正せずにどうしても古いコードのまま走らせたい場合は、環境変数
@code{GAUCHE_MUTABLE_LITERALS}を定義してください。
@c COMMON


@node List predicates, List constructors, Mutable and immutable pairs, Pairs and lists
@subsection List predicates
@c NODE リストに関する述語

@defun pair? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a pair, @code{#f} otherwise.
@c JP
@var{obj}がペアなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun ipair? obj
[R7RS ilist]
@c EN
Returns @code{#t} iff @var{obj} is an immutable pair, @code{#f} otherwise.

An immutable pair is indistinguishable from a mutable pair except using
this predicate, or when you attempt to modify it.
@xref{Mutable and immutable pairs}.
@c JP
@var{obj}が変更不可なペアなら@code{#t}を、そうでなければ@code{#f}を返します。

変更不可なペアは、この述語を使うか、あるいはそのペアを変更しようとした場合を除いては、
変更可能なペアと全く同じように動作します。
詳しくは@ref{Mutable and immutable pairs}参照。
@c COMMON
@end defun

@defun null? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is an empty list, @code{#f} otherwise.
@c JP
@var{obj}が空リストなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun null-list? obj
[R7RS list]
@c EN
Returns @code{#t} if @var{obj} is an empty list,
@code{#f} if @var{obj} is a pair.  If @var{obj} is neither
a pair nor an empty list, an error is signaled.

This can be used instead of @code{null?} to check the end-of-list
condition when you want to be more picky about non-proper lists.
@c JP
@var{obj} が空リストなら@code{#t}を、ペアなら@code{#f}を返し、
それ以外のときはエラーを報告します。

リスト終了条件を検査する時に、正しいリスト以外を除外したい場合に
@code{null?}の代わりに使えます。
@c COMMON
@end defun

@defun list? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a proper list, @code{#f} otherwise.
This function returns @code{#f} if @var{obj} is a dotted or circular list.

See also @code{proper-list?}, @code{circular-list?} and
@code{dotted-list?} below.
@c JP
@var{obj}が正しいリストなら@code{#t}を、そうでなければ@code{#f}を返します。
この手続きは@var{obj}がドットリストや循環リストなら@code{#f}を返します。

下に説明する、
@code{proper-list?}、@code{circular-list?}、@code{dotted-list?}
といった手続きも参照してください。
@c COMMON
@end defun


@defun proper-list? x
[R7RS list]
@c EN
Returns @code{#t} fif x is a proper list, that is, a finite list
terminated by @code{()}.
@c JP
@var{x} が真性リスト、つまり@code{()}で終端された有限のリストであれば
@code{#t} を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun circular-list? x
[R7RS list]
@c EN
Returns @code{#t} if x is a circular list.  A list is circular if
you follow @code{cdr} of the pairs you'll eventually get to a pair
you already visited.  It doesn't necessary that the head of the list
@var{x} is a part of the circle.  A list isn't circular by the
cycle that involves @var{car} of the paris.
@c JP
@var{x} が循環リストであれば @code{#t} を返します。リストを@code{cdr}方向に
辿って行って、既に訪れたペアに出会ったら、それは循環リストです。
リストの頭 (@code{x}) が循環に含まれている必要はありません。
また、@code{car}方向への循環があってもそれだけでは循環リストとはみなされません。
@c COMMON
@end defun

@defun dotted-list? x
[R7RS list]
@c EN
Returns @code{#t} if x is a finite, non-nil-terminated list.
This includes non-pair, non-() values (e.g. symbols, numbers),
which are considered to be dotted lists of length 0.
@c JP
@var{x} が有限の大きさで、空リストで終端していないリストなら
@code{#t} を返します。これには、ペアではなく、空リストでもない値(たとえば
シンボルや数値)のような長さ0のドットリストと考えられるものを含みます。
@c COMMON
@end defun


@node List constructors, List accessors and modifiers, List predicates, Pairs and lists
@subsection List constructors
@c NODE リストの作成

@defun cons obj1 obj2
[R7RS base]
@c EN
Constructs a mutable pair of @var{obj1} and @var{obj2} and returns it.
@c JP
@var{obj1}と@var{obj2}の変更可能なペアを作成して返します。
@c COMMON
@lisp
(cons 'a 'b) @result{} (a . b)
@end lisp
@end defun

@defun ipair obj1 obj2
[R7RS ilist]
@c EN
Constructs an immutable pair of @var{obj1} and @var{obj2} and returns it.
@c JP
@var{obj1}と@var{obj2}の変更不可なペアを作成して返します。
@c COMMON
@lisp
(ipair 'a 'b) @result{} (a . b)
@end lisp
@end defun

@defun make-list len :optional fill
[R7RS base]
@c EN
Makes a proper list of length @var{len}.  If optional argument
@var{fill} is provided, each element is initialized by it.  Otherwise
each element is undefined.
@c JP
長さ@var{len}の正規のリストを返します。引数@var{fill}が与えられていれば、各要素は
@var{fill}になります。そうでなければ各要素の値は不定です。
@c COMMON

@lisp
(make-list 5 #t) @result{} (#t #t #t #t #t)
@end lisp
@end defun

@defun list obj @dots{}
[R7RS base]
@c EN
Makes a list, whose elements are @var{obj} @dots{}.
@c JP
要素が@var{obj} @dots{}であるリストを作成します。
@c COMMON
@lisp
(list 1 2 3) @result{} (1 2 3)
(list) @result{} ()
@end lisp
@end defun

@defun ilist obj @dots{}
[R7RS ilist]
@c EN
Makes a list, whose elements are @var{obj} @dots{},
and which consists of immutable pairs.
@c JP
要素が@var{obj} @dots{}であり、変更不可なペアで作られたリストを作成します。
@c COMMON
@lisp
(ilist 1 2 3) @result{} (1 2 3)
(ilist) @result{} ()

(list-set! (ilist 1 2 3) 1 'a)
  @result{} ERROR: Attempt to modify an immutable pair: (2 3)
@end lisp
@end defun

@defun list* obj1 obj2 @dots{}
@defunx cons* obj1 obj2 @dots{}
[R7RS list]
@c EN
Like @code{list}, but the last argument becomes cdr of the last pair.
Two procedures are exactly the same.  Gauche originally had @code{list*},
and SRFI-1 (R7RS @code{(scheme list)})defines @code{cons*}.
@c JP
@code{list}とほぼ同じですが、最後の引数が作成されるリストの最後のペアのcdrになります。
二つの手続きは全く同じです。Gaucheはもともと@code{list*}を持っていましたが、
SRFI-1 (R7RS @code{(scheme list)}) が@code{cons*}という名前を定義しました。
@c COMMON
@example
(list* 1 2 3) @result{} (1 2 . 3)
(list* 1) @result{} 1
@end example
@end defun

@defun ilist* obj obj2 @dots{}
@defunx ipair* obj obj2 @dots{}
[R7RS ilist]
@c EN
Immutable counterparts of @code{list*}.  Creates an immutable list
from @code{obj} @dots{}, but the last argument is used as the @code{cdr}
of the last pair.

Both name works exactly the same.
R7RS @code{(scheme ilist)} defines @code{ipair*}.
@c JP
@code{list*}の変更不可バージョンです。
@code{obj} @dots{}からなる変更不可なリストを作りますが、最後の引数は
最後のペアの@code{cdr}になります。

どちらの名前も同じ動作ですが、R7RSの@code{(scheme ilist)}は
@code{ipair*}を定義しています。
@c COMMON
@example
(ilist* 1 2 3) @result{} (1 2 . 3)
(ilist* 1) @result{} 1
@end example
@end defun

@defun list-copy list
[R7RS base]
@c EN
Shallow copies @var{list}.
If @var{list} is circular, an error is thrown.
(Detecting circular list is Gauche's extension; R7RS allows
the procedure to diverge.)
@c JP
@var{list}の浅いコピーを行います。
@var{list}が循環リストの場合、エラーが投げられます。
(循環リストを検出するのはGaucheの拡張です。
R7RSではこの手続きは停止しなくても良いことになっています。)
@c COMMON
@end defun

@defun iota count :optional (start 0) (step 1)
[R7RS list]
@c EN
Returns a list of @var{count} numbers, starting from @var{start},
increasing by @var{step}.   @var{Count} must be a nonnegative
integer.  If both @var{start} and @var{step} are exact,
the result is a list of exact numbers; otherwise, it is a list
of inexact numbers.
@c JP
@var{start}から始まり、@var{step}ずつ増加する、
@var{count} 個の要素からなる数値のリストを返します。@var{count}は
非負の整数でなければなりません。@var{start}と@var{step}が
ともに正確数であれば、結果は正確数のリストになります。そうでなければ
結果は非正確数のリストです。
@c COMMON
@example
(iota 5)        @result{} (0 1 2 3 4)
(iota 5 1 3/7)  @result{} (1 10/7 13/7 16/7 19/7)
(iota 5 0 -0.1) @result{} (0 -0.1 -0.2 -0.3 -0.4)
@end example

@c EN
This creates a list eagerly.  If the list is short it is fast
enough, but if you want to count tens of thousands of numbers,
you may want to do so lazily.  See @code{liota} (@pxref{Lazy sequences}).
@c JP
この手続きはリストを最後まで作って返します。リストが短ければ
十分速いですが、何万という数をリストにしたければ、遅延リストを使った方が
良いかもしれません。@code{liota}を見てください(@ref{Lazy sequences}参照)。
@c COMMON
@end defun

@defmac cond-list clause @dots{}
@c EN
Construct a list by conditionally adding entries.
Each @var{clause} has a test and expressions.  When its test
yields true, the result of associated expression is used to
construct the resulting list.  When the
test yields false, nothing is inserted.
@c JP
条件によりエントリを追加することによりリストを構築します。
それぞれの@var{clause}は条件と式を持ちます。
条件が真であれば、関連する式の結果が結果のリストの構築に使われます。
条件が偽であれば、何も挿入されません。
@c COMMON

@c EN
@var{Clause} must be either one of the following form:
@table @code
@item (@var{test} @var{expr} @dots{})
@var{Test} is evaluated, and when it is true,
@var{expr} @dots{} are evaluated, and the return value
becomes a part of the result.  If no @var{expr} is given,
the result of @var{test} is used if it is not false.
@item (@var{test} => @var{proc})
@var{Test} is evaluated, and when it is true,
@var{proc} is called with the value, and the return
value is used to construct the result.
@item (@var{test} @@ @var{expr} @dots{})
Like @code{(test expr @dots{})}, except that the result of
the last @var{expr} must be a list, and it is spliced into
the resulting list, like unquote-splicing.
@item (@var{test} => @@ @var{proc})
Like @code{(test => proc)}, except that the result of
@var{proc} must be a list, and and it is spliced into
the resulting list, like unquote-splicing.
@end table
@c JP
@var{clause}は、以下のフォームのうちの1つでなければなりません。
@table @code
@item (@var{test} @var{expr} @dots{})
@var{test}が評価され、それが真ならば@var{expr} @dots{}が評価され、
戻り値が結果の一部となります。@var{expr}が与えられなければ、
@var{test}の結果が偽でなければその結果が使われます。
@item (@var{test} => @var{proc})
@var{test}が評価され、それが真ならば@var{proc}がその値とともに
呼ばれ、その戻り値が結果を構築するために使われます。
@item (@var{test} @@ @var{expr} @dots{})
@code{(test expr @dots{})}のように動作しますが、最後の@var{expr}の
値はリストでなければならず、それは結果のリストに(unquote-splicingのように)
スプライスされます。
@item (@var{test} => @@ @var{proc})
@code{(test => proc)}のように動作しますが、@var{proc}の戻り値
はリストでなければならず、それは結果のリストに(unquote-splicingのように)
スプライスされます。
@end table
@c COMMON

@example
(let ((alist '((x 3) (y -1) (z 6))))
 (cond-list ((assoc 'x alist) 'have-x)
            ((assoc 'w alist) 'have-w)
            ((assoc 'z alist) => cadr)))
  @result{} (have-x 6)

(let ((x 2) (y #f) (z 5))
  (cond-list (x @@ `(:x ,x))
             (y @@ `(:y ,y))
             (z @@ `(:z ,z))))
  @result{} (:x 2 :z 5)
@end example
@end defmac


@node List accessors and modifiers, Walking over lists, List constructors, Pairs and lists
@subsection List accessors and modifiers
@c NODE リストへのアクセスと変更

@defun car pair
@defunx cdr pair
[R7RS base]
@c EN
Returns car and cdr of @var{pair}, respectively.
@c JP
それぞれ@var{pair}のcarとcdrを返します。
@c COMMON
@end defun

@defun set-car! pair obj
@defunx set-cdr! pair obj
[R7RS base]
@c EN
Modifies car and cdr of @var{pair}, by @var{obj}, respectively.

Note: @code{(setter car)} @equiv{} @code{set-car!}, and
@code{(setter cdr)} @equiv{} @code{set-cdr!}.
@c JP
@var{pair}のcarもしくはcdrを@var{obj}で置き換えます。

注： @code{(setter car)} @equiv{} @code{set-car!} であり、
@code{(setter cdr)} @equiv{} @code{set-cdr!} です。
@c COMMON
@end defun

@defun caar pair
@defunx cadr pair
@findex cdar
@findex cddr
@findex caaar
@findex caadr
@findex cadar
@findex caddr
@findex cdaar
@findex cdadr
@findex cddar
@findex cdddr
@findex caaaar
@findex caaadr
@findex caadar
@findex caaddr
@findex cadaar
@findex cadadr
@findex caddar
@findex cadddr
@findex cdaaar
@findex cdaadr
@findex cdadar
@findex cdaddr
@findex cddaar
@findex cddadr
@dots{}
@end defun
@defun cdddar pair
@defunx cddddr pair
[R7RS base][R7RS cxr]
@c EN
@code{caar} @equiv{} @code{(car (car x))},
@code{cadr} @equiv{} @code{(car (cdr x))}, and so on.

In R7RS, more than two-level of accessors are defined in the
@code{(scheme cxr)} library.

The corresponding setters are also defined.
@c JP
@code{caar} @equiv{} @code{(car (car x))},
@code{cadr} @equiv{} @code{(car (cdr x))}, 等々。

R7RSでは、2レベルよりも深いアクセサは@code{(scheme cxr)}ライブラリに含まれます。

対応するsetterも定義されています。
@c COMMON
@example
(let ((x (list 1 2 3 4 5)))
  (set! (caddr x) -1)
  x)
  @result{} (1 2 -1 4 5)
@end example
@end defun

@defun length list
[R7RS base]
@c EN
Returns the length of a proper list @var{list}.
If @var{list} is a dotted list, an error is signaled.
If @var{list} is a circular list, this function diverges.
@c JP
正規のリスト@var{list}の長さを返します。
@var{list}がドットリストならばエラーが起きます。
@var{list}が循環リストの場合、この関数は無限ループします。
@c COMMON
@end defun

@defun length+ x
[R7RS list]
@c EN
If @var{x} is a proper list, returns its length.
For all other @var{x}, including a circular list,
it returns @code{#f}.

If you want a length of dotted list in terms of the number of pairs,
use @var{num-pairs} below.
@c JP
@var{x} が真性リストなら、その長さを返します。
@var{x} がそうでなければ(たとえ循環リストであっても)
@code{#f} を返します。

ドットリストの「長さ」を、構成するペアの数で知りたい場合は、
下の@code{num-pairs}が使えます。
@c COMMON
@end defun

@defun length=? lis lis-or-num
@defunx length<? lis lis-or-num
@defunx length<=? lis lis-or-num
@defunx length>? lis lis-or-num
@defunx length>=? lis lis-or-num
@c EN
These procedures compare the lengths of two lists,
or the length of list and a number.
They only need to look at the lists until it determine the result,
so it can be much more efficient than taking actual length of
lists to compare.  They can also handle dotted or circular lists.

The second argument can be another list or a real number.  It is not
a typical interface, but convenient nevertheless.

@example
(length<=? '(a b) '(a b c))  @result{} #t
(length>?  '(a b) '(a b c))  @result{} #f

;; Using number
(length=? '(a b c d e) 5)    @result{} #t

;; It can take any real number
(length>? '(a b c) 2.5)      @result{} #t

;; Dotted list counts number of pairs
(length=? '(a b . c) 2)      @result{} #t

;; Works with circular lists as infinite length
(length>? '(a . #0=(b . #0#)) 100000) @result{} #t
(length=? '#0=(a . #0#) '#1=(b b . #1#)) @result{} #t

;; Either one can be infinite lazy sequence, as far as
;; the other is finite.
(length<? (liota) 5)         @result{} #f
@end example
@c JP
これらの手続きは、ふたつのリストの長さ同士、あるいはひとつのリストの長さと
与えられた数とを比較します。
結果を得るのに必要なだけしかリストを読まないので、
それぞれのリストの長さを取って比較するよりもずっと効率的です。
また、ドットリストや循環リストも扱えます。

二番目の引数はリストか実数です。典型的なインタフェースからは逸脱していますが、
便利なので採用しました。

@example
(length<=? '(a b) '(a b c))  @result{} #t
(length>?  '(a b) '(a b c))  @result{} #f

;; 数で長さを指定
(length=? '(a b c d e) 5)    @result{} #t

;; どんな実数でも使える
(length>? '(a b c) 2.5)      @result{} #t

;; ドットリストはペアの数を数える
(length=? '(a b . c) 2)      @result{} #t

;; 循環リストは無限の長さを持つとみなす
(length>? '(a . #0=(b . #0#)) 100000) @result{} #t
(length=? '#0=(a . #0#) '#1=(b b . #1#)) @result{} #t

;; 一方が有限であれば、無限の遅延シーケンスもok
(length<? (liota) 5)         @result{} #f
@end example
@c COMMON
@end defun

@defun num-pairs lis
@c EN
Returns the number of pairs that consists a (proper, dotted, or circular)
list @var{lis}, in an exact integer.
If @var{lis} is a proper list, it is the same as @code{length}.
@c JP
リスト@var{lis}を構成するペアの数を正確な整数で返します。@var{lis}はドットリストや循環リスト
でも構いません。@var{lis}が正しいリストなら戻り値は@code{length}と同じです。
@c COMMON

@example
(num-pairs '(a b c d e))    @result{} 5
(num-pairs '())             @result{} 0
(num-pairs '(a b c d . e))  @result{} 4
(num-pairs 'a)              @result{} 0
(num-pairs '#0=(a b . #0#)) @result{} 2
(num-pairs '(a . #0=(b c . #0#))) @result{} 3
@end example
@end defun

@defun take x i
@defunx drop x i
[R7RS list]
@c EN
@code{take} returns the first i elements of list x.
@code{drop} returns all but the first i elements of list x.
@c JP
@code{take} はリスト @var{x} の最初のi個の要素を返します。
@code{drop} はリスト @var{x} の最初のi個の要素を除いたリストを返します。
@c COMMON
@example
(take '(a b c d e) 2) => (a b)
(drop '(a b c d e) 2) => (c d e)
@end example
@c EN
@var{x} may be any value:
@c JP
@var{x} はあらゆる値をとりえます。
@c COMMON
@example
(take '(1 2 3 . d) 2) => (1 2)
(drop '(1 2 3 . d) 2) => (3 . d)
(drop '(1 2 3 . d) 3) => d
@end example
@c EN
@code{drop} is exactly equivalent to performing @var{i} cdr operations
on @var{x}.  The returned value shares a common tail with @var{x}.
On the other hand, take always allocates a new list
for result if the argument is a list of non-zero length.

An error is signaled if @var{i} is past the end of list @var{x}.
See @code{take*} and @code{drop*} below for more tolerant version.

For generic subsequence extraction from any sequence, see @code{subseq}
in @ref{Slicing and filling sequences}.
@c JP
@code{drop} は @var{x} に @var{i} 回 cdr 操作をおこなうのと全く
同じです。返される値は、@var{x} と共通の末尾を共有します。一方、
take は、引数のリストが長さ0でないリストなら必ず新しいリストの
領域を確保します。

@var{i} がリスト @var{x} の終端を超えたらエラーが発生します。
より寛容な手続きについては、下の@code{take*}と@code{drop*}を見てください。

あらゆる並びからの部分並びを抽出する汎用的な方法に関しては、
@ref{Slicing and filling sequences} にある @code{subseq} を参照してください。
@c COMMON
@end defun

@defun take* list k :optional (fill? #f) (padding #f)
@defunx drop* list k
@c EN
More tolerant version of @code{take} and @code{drop}.
They won't raise an error even if @var{k} is larger than the size
of the given list.

If the list is shorter than @var{k} elements,
@code{take*} returns a copy of @var{list}
by default.   If @var{fill?} is true, @var{padding} is added
to the result to make its length @var{k}.

On the other hand, @code{drop*} just returns an empty list
when the input list is shorter than @var{k} elements.
@c JP
@code{take}と@code{drop}のより寛容なバージョンです。
これらの手続きは、リストが@code{k}より短くてもエラーを通知しません。

その場合、@code{take*}はデフォルトでは@var{list}のコピーを
返します。もし@var{fill?}が真であれば、足りない要素の部分に
@var{padding}を追加して@var{k}要素にしたリストを返します。

一方、@code{drop*}はリストの長さが不足する場合は単に空リストを返します。
@c COMMON

@example
(take* '(a b c d) 3)       @result{} (a b c)
(take* '(a b c d) 6)       @result{} (a b c d)
(take* '(a b c d) 6 #t)    @result{} (a b c d #f #f)
(take* '(a b c d) 6 #t 'z) @result{} (a b c d z z)
(drop* '(a b c d) 3)       @result{} (d)
(drop* '(a b c d) 5)       @result{} ()
@end example

@c EN
Note: For generic subsequence extraction from any sequence,
see @code{subseq} in @ref{Slicing and filling sequences}.
@c JP
注意: 一般的な、いかなるシーケンスからのサブシーケンスの抽出については、
@ref{Slicing and filling sequences}の@code{subseq}を見て下さい。
@c COMMON
@end defun

@defun take-right lis k
@defunx drop-right lis k
[R7RS list]
@c EN
@code{take-right} returns the last @var{k} elements of @var{lis}.
@code{drop-right} returns all but the last @var{k} elements of @var{lis}.
@c JP
@code{take-right} は @var{lis} の最後の @var{k}個の要素
からなるリストを返します。
@code{drop-right} は @var{lis} の最後の @var{k}個の要素を
除いたリスト返します。
@c COMMON
@example
(take-right '(a b c d e) 2) => (d e)
(drop-right '(a b c d e) 2) => (a b c)
@end example
@c EN
@var{lis} may be any finite list.
@c JP
@var{lis} は有限リストであればOKです。
@c COMMON
@example
(take-right '(1 2 3 . d) 2) => (2 3 . d)
(drop-right '(1 2 3 . d) 2) => (1)
(take-right '(1 2 3 . d) 0) => d
(drop-right '(1 2 3 . d) 0) => (1 2 3)
@end example
@c EN
@code{take-right}'s return value always shares a common
tail with @var{lis}.
@code{drop-right} always allocates a new list
if the argument is a list of non-zero length.

An error is signaled if @var{k} is larger than the length of @var{lis}.
See @code{take-right*} and @code{drop-right*} below, for more tolerant
version.
@c JP
@code{take-right} の返す値はいつでも @var{lis} の共通の末尾を共有します。
@code{drop-right} は、引数が長さが0でないリストなら、必ず新しいリストの
領域を確保します。

@var{k} がリスト @var{lis} の長さより大きければエラーが発生します。
より寛容なバージョンについては下の@code{take-right*}, @code{drop-right*}を
参照してください。
@c COMMON
@end defun

@defun take-right* list k :optional (fill? #f) (padding #f)
@defunx drop-right* list k
@c EN
Like @code{take*} and @code{drop*}, but counts from right of @var{list}.
If @var{list} is shorter than @var{k} elements, they won't raise
an error.  Instead, @code{drop-right*} just returns an empty list,
and @code{take-right*} returns @var{list} itself by default.
If @var{fill?} is true for @code{take-right*},
@var{padding} is added on the left of the result to make its length @var{k}.
The result still shares the @var{list}.
@c JP
@code{take*}及び@code{drop*}と同じですが、@var{list}の右端からカウントします。
これらは@var{list}が@var{k}要素より短い場合にもエラーを通知しません。
@code{drop-right*}はその場合は単に空リストを返します。
@code{take-right*}はその場合はデフォルトで@var{list}そのものを
返しますが、@var{fill?}が真であれば@var{list}の左側に
足りない分だけ@var{padding}を足したものを返します。その場合でも
結果の尾部は@var{list}と共有されます。
@c COMMON
@end defun

@defun take! lis k
@defunx drop-right! lis k
[R7RS list]
@c EN
Linear update variants of @code{take} and @code{drop-right}.
Those procedures may destructively modifies @var{lis}.

If @var{lis} is circular, @code{take!} may return a list
shorter than expected.
@c JP
@code{take} および @code{drop-right} の
その場で更新されるバージョンです。これらの
手続きは @var{lis} を破壊的に変更するかもしれません。

@var{lis} が循環リストなら、@code{take!} は期待されるものより短いリストを返す
可能性があります。
@c COMMON
@end defun

@defun list-tail list k :optional fallback
[R7RS base]
@c EN
Returns @var{k}-th cdr of @var{list}.
@var{list} can be a proper, dotted or circular list.
(If @var{list} is a dotted list, its last @code{cdr} is simply ignored).

If @var{k} is negative or larger than the length of @var{list},
the behavior depends on whether the optional @var{fallback} argument
is given or not.  If @var{fallback} is given, it is returned.
Otherwise, an error is signaled.
(The optional @var{fallback} argument is Gauche's extension to R7RS).
@c JP
@var{list}の@var{k}番目のcdrを返します。@var{list}は
正規のリストでもドットリストでも循環リストでも構いません。
(@var{list}がドットリストの場合、最後の@code{cdr}は無視されます)。

@var{k}の値が負であったり@var{list}の長さ以上の場合、
@var{fallback}引数が与えられていればそれが返され、
そうでなければエラーが報告されます。
(省略可能な@var{fallback}引数はGauche独自の拡張です)。
@c COMMON
@end defun

@defun list-ref list k :optional fallback
[R7RS+ base]
@c EN
Returns @var{k}-th element of @var{list}.
@var{list} can be a proper, dotted or circular list.

By default, @code{list-ref} signals an error if @var{k} is
negative, or greater than or equal to the length of @var{list}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.  This is an extension of Gauche.
@c JP
@var{list}の@var{k}番目の要素を返します。@var{list}は
正規のリストでもドットリストでも循環リストでも構いません。

もし@var{k}がリストの長さを超えていたり、負数であった場合は通常はエラーが起こります。
しかし、オプショナルな引数@var{fallback}が与えられていた場合は、エラーは起きず
@var{fallback}が返されます。これはGaucheの拡張です。
@c COMMON
@end defun

@defun list-set! list k v
[R7RS base]
@c EN
Modifies the @var{k}-th element of a @var{list} by @var{v}.
It is an error unless @var{k} is an exact integer between 0 and
one minus the length of @var{k} and @var{list} is mutable.
@c JP
リスト@var{list}の@var{k}番目の要素を@var{v}へと変更します。
@var{k}が0から(- リストの長さ 1)の範囲の正確な整数でない場合、
また@var{list}が変更可能なリストでない場合は
エラーが報告されます。
@c COMMON
@end defun


@defun last-pair list
[R7RS list]
@c EN
Returns the last pair of @var{list}.
@var{list} can be a proper or dotted list with at least one pair.
@c JP
@var{list}の最後のペアを返します。@var{list}は
ペアをひとつ以上持つ正規のリストかドットリストです。
@c COMMON

@example
(last-pair '(1 2 3))   @result{} (3)
(last-pair '(1 2 . 3)) @result{} (2 . 3)
(last-pair 1)          @result{} @i{error}
@end example
@end defun

@defun last pair
[R7RS list]
@c EN
Returns the last element of the non-empty, finite list @var{pair}.
It is equivalent to @code{(car (last-pair pair))}.
@c JP
空ではない有限リスト @var{pair} の最後の要素を返します。
これは、@code{(car (last-pair pair))} と同等です。
@c COMMON

@example
(last '(1 2 3))   @result{} 3
(last '(1 2 . 3)) @result{} 2
@end example
@end defun

@defun split-at x i
@defunx split-at! x i
[R7RS list]
@c EN
@code{split-at} splits the list @var{x} at index @var{i},
returning a list of the first @var{i} elements, and the remaining tail.
@c JP
@code{split-at} はリスト @var{x} をインデックス @var{i} の
位置で分割し、最初の @var{i} 個の要素からなるリストと、残りの末尾とを
返します。
@c COMMON
@example
(split-at '(a b c d e) 2) @result{} (a b) (c d e)
@end example
@c EN
@code{split-at!} is the linear-update variant. It may destructively
modifies @var{x} to produce the result.
@c JP
@code{split-at!} はその場で更新されるバージョンです。
これは @var{x} を破壊的に更新するかもしれません。
@c COMMON
@end defun

@defun split-at* list k :optional (fill? #f) (padding #f)
@c EN
More tolerant version of @code{split-at}.
Returns the results of @code{take*} and @code{drop*}.
@c JP
SRFI-1 (R7RS @code{(scheme list)})の@code{split-at}の寛容なバージョンです。
@code{take*}と@code{drop*}の結果を返します。
@c COMMON

@example
(split-at* '(a b c d) 6 #t 'z)
  @result{} (a b c d z z) @r{and} ()
@end example
@end defun

@defun slices list k :optional fill? padding
@c EN
Splits @var{list} into the sublists (slices) where the length of
each slice is @var{k}.
If the length of @var{list} is not a multiple of @var{k},
the last slice is dealt in the same way as @code{take*}; that is,
it is shorter than @var{k} by default, or added @var{padding} if
@var{fill?} is true.
@c JP
@var{list}を、それぞれの長さが@var{k}であるようなサブリスト(スライス)に
分割します。
@var{list}の長さが@var{k}の整数倍でない場合は、最後のスライスは
@code{take*}と同じ方法で扱われます。つまり、デフォルトでは@var{k}より
短いもの、あるいは@var{fill?}が真ならば@var{padding}が追加されます。
@c COMMON

@example
(slices '(a b c d e f g) 3)
  @result{} ((a b c) (d e f) (g))
(slices '(a b c d e f g) 3 #t 'z)
  @result{} ((a b c) (d e f) (g z z))
@end example
@end defun

@defun intersperse item list
@c EN
Inserts @var{item} between elements in the @var{list}.
(The order of arguments is taken from Haskell's intersperse).
@c JP
@var{list}の要素の間に@var{item}を挿入します。
(引数の順番は、Haskellのintersperseと同じです。)
@c COMMON

@example
(intersperse '+ '(1 2 3))  @result{} (1 + 2 + 3)
(intersperse '+ '(1))      @result{} (1)
(intersperse '+ '())       @result{} ()
@end example
@end defun

@node Walking over lists, Other list procedures, List accessors and modifiers, Pairs and lists
@subsection Walking over lists
@c NODE リストをたどる手続き

@defun map proc list1 list2 @dots{}
[R7RS+ base]
@c EN
Applies @var{proc} for each element(s) of given list(s),
and returns a list of the results.  R7RS doesn't specify
the application order of @code{map}, but Gauche guarantees
@var{proc} is always applied in order of the list(s).
Gauche's @code{map} also terminates as soon as one of
the list is exhausted.
@c JP
与えられたリストの各要素に対して@var{proc}を適用し、その結果をリストにして
返します。R7RSでは@var{proc}の適用順序が定められていませんが、Gaucheでは
常に@var{proc}はリスト内の順番で呼ばれます。
複数のリストが与えられた場合、最も短いリストが終了した時点で@var{proc}の適用を
打ち切ります。
@c COMMON

@example
(map car '((a b) (c d) (e f))) @result{} (a c e)

(map cons '(a b c) '(d e f))
  @result{} ((a . d) (b . e) (c . f))
@end example

@c EN
Note that the @code{gauche.collection} module (@pxref{Collection framework})
extends @code{map} to work on any type of collection.
@c JP
@code{gauche.collection}モジュール(@ref{Collection framework}参照)
を使うと、@code{map}がリスト以外のコレクション型に対しても動作するようになります。
@c COMMON
@end defun

@defun append-map f clist1 clist2 @dots{}
@defunx append-map! f clist1 clist2 @dots{}
[R7RS list]
@c EN
Functionally equivalent to the followings, though a bit more efficient:
@c JP
機能的には以下と同等ですが、若干効率が良いです:
@c COMMON

@example
  (apply append (map @var{f} @var{clist1} @var{clist2} @dots{}))
  (apply append! (map @var{f} @var{clist1} @var{clist2} @dots{}))
@end example
@c EN
At least one of the list arguments must be finite.
@c JP
引数のリストのうち少くともひとつは有限でなければなりません。
@c COMMON
@end defun


@defun map* proc tail-proc list1 list2 @dots{}
@c EN
Like @code{map}, except that @var{tail-proc} is applied to the @code{cdr}
of the last pair in the argument(s) to get the @code{cdr} of
the last pair of the result list.  This procedure allows improper
list to appear in the arguments.   If a single list is given,
@var{tail-proc} always receives a non-pair object.
@c JP
@code{map}とほぼ同じですが、引数の最後のペアの@code{cdr}に@var{tail-proc}が
適用され、その返り値が結果のリストの最後のペアの@code{cdr}になります。
この手続きは正規でないリストを引数に取ることができます。
引数のリストがひとつだけの場合、@var{tail-proc}の引数は必ずペアでないオブジェクトです。
@c COMMON

@example
(map* - / '(1 2 3 . 4)) @result{} (-1 -2 -3 . 1/4)

(define (proper lis)
  (map* values
        (lambda (p) (if (null? p) '() (list p)))
        lis))

(proper '(1 2 3))     @result{} (1 2 3)
(proper '(1 2 3 . 4)) @result{} (1 2 3 4)
@end example

@c EN
If more than one list are given, the shortest one determines
how @var{tail-proc} is called.  When @code{map*} reaches the
last pair of the shortest list, @var{tail-proc} is called with
cdrs of the current pairs.
@c JP
二つ以上のリストが与えられた場合は、最も短いリストが@var{tail-proc}の呼び出しを
決めます。@code{map*}が最も短いリストの最後のペアに達した時点で、
その時のそれぞれのペアのcdrが@var{tail-proc}へと渡されます。
@c COMMON

@example
(map* + vector '(1 2 3 4) '(1 2 . 3))
  @result{} (2 4 . #((3 4) 3))
@end example

@c EN
Note: The name @code{map*} is along the line of
@code{list*}/@code{cons*} that can produce improper list
(@xref{List constructors}, @pxref{R7RS lists}).
@c JP
註: @code{map*}という名前は、正規でないリストを作り得る@code{list*}/@code{cons*}からの
連想でつけられました
(@ref{List constructors}、@ref{R7RS lists}参照)。
@c COMMON
@end defun

@defun for-each proc list1 list2 @dots{}
[R7RS base]
@c EN
Applies @var{proc} for each element(s) of given list(s) in order.
The results of @var{proc} are discarded.  The return value of
@code{for-each} is undefined.  When more than one list is given,
@code{for-each} terminates as soon as one of the list is exhausted.
@c JP
手続き@var{proc}をリストの各エレメントに対して順に適用します。
@var{proc}の結果は捨てられます。@code{for-each}の戻り値は定義されていません。
複数のリストが与えられた場合、一番短いリストが終了した時点で@code{for-each}は終了します。
@c COMMON

@c EN
Note that the @code{gauche.collection} module (@pxref{Collection framework})
extends @code{for-each} to work on any type of collection.
@c JP
@code{gauche.collection}モジュール(@ref{Collection framework}参照)
を使うと、@code{for-each}がリスト以外のコレクション型に対しても動作するようになります。
@c COMMON
@end defun

@defun fold kons knil clist1 clist2 @dots{}
[R7RS list]
@c EN
The fundamental list iterator.
When it is given a single list
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en}),
then this procedure returns
@c JP
基本的なリスト反復演算子です。単一のリスト
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en})
を与えられたときには、以下を返します。
@c COMMON
@example
(@var{kons} @var{en} @dots{} (@var{kons} @var{e2} (@var{kons} @var{e1} @var{knil})) @dots{} )
@end example

@c EN
If @var{n} list arguments are provided, then the @var{kons}
function must take @var{n}+1 parameters: one element from each list, and
the "seed" or fold state, which is initially @var{knil}.
The fold operation terminates when the shortest list runs out of values.
At least one of the list arguments must be finite.

Examples:
@c JP
@var{n} 本のリストが与えられた場合には、@var{kons} 関数は @var{n}+1 個の引数
をとる関数でなければなりません。それぞれのリストから要素をひとつずつと、
初期値 @var{knil} である「種」あるいは畳み込み状態とよばれるものです。
この畳み込み演算は、もっとも短いリストの要素がなくなったところで終了します。
与えられるリストの少くともひとつは有限でなければなりません。

例:
@c COMMON
@example
(fold + 0 '(3 1 4 1 5 9)) @result{} 23 ;@r{sum up the elements}
(fold cons '() '(a b c d e)) @result{} (e d c b a) ;@r{reverse}
(fold cons* '() '(a b c) '(1 2 3 4 5))
    @result{} (c 3 b 2 a 1) ;@r{n-ary case}
@end example
@end defun

@defun fold-right kons knil clist1 clist2 @dots{}
[R7RS list]
@c EN
The fundamental list recursion operator.
When it is given a single list
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en}),
then this procedure returns
@c JP
基本的な再帰演算子です。単一のリスト
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en})
を与えられたときには、以下を返します。
@c COMMON
@example
(@var{kons} @var{e1} (@var{kons} @var{e2} @dots{} (@var{kons} @var{en} @var{knil})))
@end example

@c EN
If @var{n} list arguments are provided, then the @var{kons} function
must take @var{n}+1 parameters: one element from each list, and
the "seed" or fold state, which is initially @var{knil}.
The fold operation terminates when the shortest list runs out of values.
At least one of the list arguments must be finite.

Examples:
@c JP
@var{n} 本のリストが与えられた場合には、@var{kons} 関数は @var{n}+1 個の引数
をとる関数でなければなりません。それぞれのリストから要素をひとつずつと、
初期値 @var{knil} である「種」あるいは畳み込み状態とよばれものです。
この畳み込み演算は、もっとも短いリストの要素がなくなったところで終了します。
与えられるリストの少くともひとつは有限でなければなりません。

例:
@c COMMON
@example
(fold-right cons '() '(a b c d e))
   @result{} (a b c d e) ;@r{copy list}
(fold-right cons* '() '(a b c) '(1 2 3 4 5))
   @result{} (a 1 b 2 c 3) ;@r{n-ary case}
@end example
@end defun

@defun fold-left snok knil clist1 clist2 @dots{}
[R6RS]
@c EN
This is another variation of left-associative folding.
When it is given a single list
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en}),
then this procedure returns:
@c JP
これは左結合のfoldの別バージョンです。一つのリスト
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en})
が与えられた場合、次の値を返します。
@c COMMON
@example
(@var{snok} (@dots{} (@var{snok} (@var{snok} @var{knil} @var{e1}) @var{e2}) @dots{}) @var{en})
@end example

@c EN
Compare this with @code{fold} above; association is the same, but the order
of arguments passed to the procedure @var{snok} is reversed from the way
arguments are passed to @var{kons} in @code{fold}.   If @var{snok} is
commutative, @code{fold} and @code{fold-left} produces the same result.
@c JP
上の@code{fold}と見比べてみてください。結合の順序は同じですが、
@var{snok}に渡される引数の順序が、@code{fold}において@var{kons}に渡される
引数の順序とは逆になっています。@code{snok}が可換な演算であれば、
@code{fold}と@code{fold-left}の結果は同じになります。
@c COMMON

@example
(fold-left + 0 '(1 2 3 4 5)) @result{} 15

(fold-left cons 'z '(a b c d))
  @result{} ((((z . a) . b) . c) . d)

(fold-left (^[a b] (cons b a)) 'z '(a b c d))
  @result{} (d c b a . z)
@end example

@c EN
If more than one lists are given, @var{snok} is called with
the current seed value @var{knil} and each corresponding
element of the input lists
@code{clist1} @code{clist2} @dots{}.
@c JP
二つ以上のリストが渡された場合、@var{snok}は現在の@var{knil}値および
入力リスト@code{clist1} @code{clist2} @dots{} の対応する要素を引数として
呼び出されます。
@c COMMON

@example
(fold-left list 'z '(a b c) '(A B C))
  @result{} (((z a A) b B) c C)
@end example

@c EN
Note: Most functional languages have left- and right- associative
fold operations, which correspond to @code{fold-left} and @code{fold-right},
respectively.
(e.g. Haskell's @code{foldl} and @code{foldr}).  In Scheme, SRFI-1
first introduced @code{fold} and @code{fold-right}.  R6RS introduced
@code{fold-left}.  (However, in R6RS the behavior is undefined if the lengths of
@code{clist1} @code{clist2} @dots{} aren't the same, while in Gauche
@code{fold-left} terminates as soon as any one of the lists terminates.)
@c JP
註：多くの関数型言語で左結合および右結合の畳み込み操作が定義されていますが、
それは@code{fold-left}と@code{fold-right}に相当します。
(例: Haskellの@code{foldl}と@code{foldr}。)
Schemeでは、まずSRFI-1によって@code{fold}と@code{fold-right}が
左/右結合の畳み込み演算として導入され、R6RSで@code{fold-left}が定義されました。
(但し、R6RSの@code{fold-left}では@code{clist1} @code{clist2} @dots{}の
長さがすべて同じでない場合の動作は未定義ですが、Gaucheでは
最短のリストが終了した時点でそれまでの結果が返されます。)
@c COMMON
@end defun

@defun reduce f ridentity list
@defunx reduce-right f ridentity list
[R7RS list]
@c EN
Variant of @code{fold} and @code{fold-right}.   @var{f} must be a
binary operator, and @var{ridentity} is the value such that for
any value @var{x} that is valid as @var{f}'s input,
@c JP
@code{fold} および @code{fold-right} の変形バージョンです。
@var{f} は二項演算子でなければなりません。
また、@var{ridentity} は @var{f} の入力として許される
あらゆる値 @var{x} について以下を満していなければなりません。
@c COMMON
@example
 (f x ridentity) @equiv{} x
@end example

@c EN
These functions effectively do the same thing as @code{fold} or
@code{fold-right}, respectively, but omit the first
application of @var{f} to @var{ridentity}, using the above nature.
So @var{ridentity} is used only when @var{list} is empty.
@c JP
これらの関数は実質的に @code{fold} や @code{fold-right} と同じことを
行いますが、@var{ridentity}には上記の性質があるため、
@var{f}は@var{ridentity}には適用されません。
@var{ridentity}が使われるのは@var{list}が空の場合だけです。
@c COMMON
@end defun



@defun filter pred list
@defunx filter! pred list
[R7RS list]
@c EN
A procedure @var{pred} is applied on each element of @var{list},
and a list of elements that @var{pred} returned true on it is returned.
@c JP
手続き @var{pred} が @var{list} の各要素に適用され、
@var{pred} が真を返す要素のリストが返されます。
@c COMMON
@example
(filter odd? '(3 1 4 5 9 2 6)) @result{} (3 1 5 9)
@end example
@c EN
@code{filter!} is the linear-update variant.  It may destructively
modifies @var{list} to produce the result.
@c JP
@code{filter!} はその場で更新されるバージョンです。結果を生成するために
@var{list} を破壊的に変更するかもしれません。
@c COMMON
@end defun

@defun filter-map  f clist1 clist2 @dots{}
@c EN
[R7RS list]
Like @code{map}, but only true values are saved.
At least one of the list arguments must be finite.
@c JP
@code{map} と似ていますが、真になる場合の値のみが保存されます。
引数として与えられるリストの少くともひとつは有限でなければなりません。
@c COMMON
@example
(filter-map (lambda (x) (and (number? x) (* x x)))
            '(a 1 b 3 c 7))
  @result{} (1 9 49)
@end example
@end defun

@defun remove pred list
@defunx remove! pred list
[R7RS list]
@c EN
A procedure @var{pred} is applied on each element of @var{list},
and a list of elements that @var{pred} returned false on it is returned.
@c JP
手続き @var{pred} が @var{list} の各要素に適用され、
@var{pred} が偽を返す要素のリストが返されます。
@c COMMON
@example
(remove odd? '(3 1 4 5 9 2 6)) @result{} (4 2 6)
@end example
@c EN
@code{remove!} is the linear-update variant.  It may destructively
modifies @var{list} to produce the result.
@c JP
@code{remove!} はその場で更新されるバージョンです。結果を生成するために
@var{list} を破壊的に更新するかもしれません。
@c COMMON
@end defun

@defun find pred clist
[R7RS list]
@c EN
Applies @var{pred} for each element of @var{clist}, from
left to right, and returns the first element that @var{pred} returns
true on.  If no element satisfies @var{pred}, @code{#f} is returned.
@c JP
@var{clist} の各要素に対して左から右に @var{pred} を適用し、
@var{pred} が真を返す最初の要素を返します。@var{pred}を満たす要素が
無い場合は@code{#f}を返します。
@c COMMON
@end defun

@defun find-tail pred clist
[R7RS list]
@c EN
Applies @var{pred} for each element of @var{clist}, from left to right,
and when @var{pred} returns a true value, returns the pair whose car
is the element.  If no element satisfies @var{pred}, @code{#f} is returned.
@c JP
@var{clist} の各要素に対して左から右に @var{pred} を適用し、@var{pred} が
真を返す場合、その car がその要素であるペアを返します。
@var{pred}を満たす要素が無い場合は@code{#f}を返します。
@c COMMON
@end defun

@defun any pred clist1 clist2 @dots{}
[R7RS list]
@c EN
Applies @var{pred} across each element of @var{clist}s, and
returns as soon as @var{pred} returns a non-false value.
The return value of @code{any} is the non-false value @var{pred} returned.
If @var{clist}s are exhausted before @var{pred} returns a non-false
value, @code{#f} is returned.
@c JP
@var{clist} の各要素に @var{pred} を適用し、@var{pred}が偽でない
値を返したら直ちにその値を返します。
@var{pred}が偽でない値を返す前にリストの要素を使いきってしまったら
@code{#f}が返ります。
@c COMMON
@end defun

@defun every pred clist1 clist2 @dots{}
[R7RS list]
@c EN
Applies @var{pred} across each element of @var{clist}s, and
returns @code{#f} as soon as @var{pred} returns @code{#f}.
If all application of @var{pred} return a non-false value,
@code{every} returns the last result of the applications.
@c JP
@var{clist} の各要素に @var{pred} を順に適用し、@var{pred}が
偽を返した場合、直ちに偽を返します。全ての@var{pred}の適用が
偽でない値を返した場合は、最後に返された値が返されます。
@c COMMON
@end defun

@defun count pred clist1 clist2 @dots{}
[R7RS list]
@c EN
A procedure @var{pred} is applied to the @var{n}-th element
of given lists, from @var{n} is zero to the length of the
the shortest finite list in the given lists,
and the count of times @var{pred} returned true is returned.
@c JP
@var{n} をゼロから与えられたリストのうち最も短いリストの
長さまでとして、@var{pred} 手続きを与えられたリストの @var{n} 番目の要素に
それぞれ適用します。
@var{pred} が真を返した数が返ります。
@c COMMON

@example
(count even? '(3 1 4 1 5 9 2 5 6)) @result{} 3
(count < '(1 2 4 8) '(2 4 6 8 10 12 14 16)) @result{} 3
@end example

@c EN
At least one of the argument lists must be finite:
@c JP
引数で与えられるリストの少くともひとつは有限でなければなりません。
@c COMMON

@example
(count < '(3 1 4 1) (circular-list 1 10)) @result{} 2
@end example
@end defun


@defun delete x list :optional elt=
@defunx delete! x list :optional elt=
[R7RS list]
@c EN
Equivalent to
@c JP
以下と同等です。
@c COMMON
@example
  (remove (lambda (y) (elt= x y)) list)
  (remove! (lambda (y) (elt= x y)) list)
@end example
@c EN
The comparison procedure, @var{elt=}, defaults to @code{equal?}.
@c JP
比較手続き @var{elt=} はデフォルトでは @code{equal?} です。
@c COMMON
@end defun

@defun delete-duplicates list :optional elt=
@defunx delete-duplicates! list :optional elt=
[R7RS list]
@c EN
Removes duplicate elements from @var{list}.
If there are multiple equal elements in @var{list},
the result list only contains the first or leftmost of these
elements in the result. The order of these surviving elements
is the same as in the original list.
The comparison procedure, @var{elt=}, defaults to @code{equal?}.
@c JP
@var{list} から重複した要素を取り除きます。@var{list} 中に等しい要素が
複数ある場合、一番左がわにある最初のものだけが残ります。これらの
生き残った要素間の順番は最初のリストの順番が保存されます。
比較手続き @var{elt=} のデフォルト値は、@code{equal?} です。
@c COMMON
@end defun

@node Other list procedures, Association lists, Walking over lists, Pairs and lists
@subsection Other list procedures
@c NODE 他のリスト手続き

@defun append list @dots{}
[R7RS base]
@c EN
Returns a list consisting of the elements of the first @var{list} followed by
the elements of the other lists.  The resulting list is always newly
allocated, except that it shares structure with the last list argument.
The last argument may actually be any object; an improper list results
if the last argument is not a proper list.
@c JP
渡されたリストの要素を繋げたリストを返します。最後の引数の部分以外は新しいセルがアロケート
されて使われます。最後の引数は正規のリストである必要がありません。その場合、結果は正規でない
リストとなります。
@c COMMON
@end defun

@defun append! list @dots{}
[R7RS list]
@c EN
Returns a list consisting of the elements of the first @var{list} followed by
the elements of the other lists.  The cells in the lists except the last
one may be reused to construct the result.   The last argument may be
any object.
@c JP
渡されたリストの要素を繋げたリストを返します。最後の引数以外のリストのセルは、結果を
作成するために再利用されるかもしれません。
最後の引数は正規のリストである必要はありません。
@c COMMON
@end defun

@defun concatenate list-of-lists
@defunx concatenate! list-of-lists
[R7RS list]
@c EN
Equivalent to @code{(apply append @var{list-of-lists})} and
@code{(apply append! @var{list-of-lists})}, respectively, but this
can be a bit efficient by skipping overhead of @code{apply}.
@c JP
それぞれ、@code{(apply append @var{list-of-lists})} および
@code{(apply append! @var{list-of-lists})} と同等ですが、
@code{apply}のオーバヘッドが無い分、わずかに効率的です。
@c COMMON
@end defun

@defun reverse list :optional (tail '())
@defunx reverse! list :optional (tail '())
[R7RS+ base]
@c EN
Returns a list consisting of the elements of @var{list}
in the reverse order.
While @code{reverse} always returns
a newly allocated list, @code{reverse!} may reuse the cells
of @var{list}.  Even @var{list} is destructively modified
by @code{reverse!}, you should use its return value, for
the first cell of @var{list} may not be the first cell
of the returned list.

If an optional argument @var{tail} is given, it becomes
the tail of the returned list (@var{tail} isn't copied).
It is useful in the idiom to prepend the processed results
on top of already existing results.
@c JP
@var{list}の要素を逆順に並べたリストを返します。
@code{reverse}は常に新たにリストをアロケートしますが、
@code{reverse!}は結果を作るために@var{list}のセルを再利用するかもしれません。
但し、@var{list}の先頭のセルが@code{reverse!}の結果でも先頭になるとは
限らないので、@var{list}が変更されることを当てにするのではなく、
@code{reverse!}の戻り値を利用する必要があります。

省略可能引数@var{tail}が与えられた場合、それは結果のリストの末尾に
付け足されます (@var{tail}部分はコピーされません)。
これは、既にある結果のリストに新たに作った結果を付け足すイディオムで
便利です。
@c COMMON

@example
(reverse '(1 2 3 4 5)) @result{} (5 4 3 2 1)
(reverse '(1 2 3) '(a b)) @result{} (3 2 1 a b)
@end example

@c EN
The @var{tail} argument is Gauche's extension,
and it isn't in the traditional Scheme's @code{reverse}.
The rationale is the following correspondence:
@c JP
@var{tail}引数はGauche独自の拡張で、
伝統的なSchemeの@code{reverse}にはありませんが、
次の対応を考えると、そう不自然なことではありません。
@c COMMON

@example
(reverse xs)      @equiv{} (fold cons xs '())
(reverse xs tail) @equiv{} (fold cons xs tail)
@end example

@c EN
For portable code, @code{append-reverse}/@code{append-reverse!}
below can be used in place of two-argument @code{reverse}/@code{reverse!}.
@c JP
ポータブルなコードでは2引数の@code{reverse}/@code{reverse!}のかわりに
以下の@code{append-reverse}/@code{append-reverse!}が使えます。
@c COMMON
@end defun

@defun append-reverse rev-head tail
@defunx append-reverse! rev-head tail
[R7RS list]
@c EN
Equivalent to the two-argument @code{reverse} and @code{reverse!}.
Provided for SRFI-1 (R7RS @code{(scheme list)}) compatibility.
@c JP
2引数の@code{reverse}および@code{reverse!}と同等です。
SRFI-1 (R7RS @code{(scheme list)}) との互換のために用意されています。
@c COMMON
@end defun


@defun memq obj list
@defunx memv obj list
@defunx member obj list :optional obj=
[R7RS base]
@c EN
Searches @var{obj} in the @var{list}.  If @code{n}-th element of
@var{list} equals to @var{obj} (in the sense of @code{eq?} for @code{memq},
@code{eqv?} for @code{memv}, and @code{equal?} for @code{member}),
@code{(list-tail @var{list} @var{n})} is returned.
Otherwise, @code{#f} is returned.
@c JP
@var{list}から@var{obj}を探します。もし@var{list}の@var{n}番目の要素が
@var{obj}と同一ならば、@code{(list-tail @var{list} @var{n})}を返します。
@code{memq}は同一性の判定に@code{eq?}を、@code{memv}は@code{eqv?}を、
@code{member}は@code{equal?}を使います。
@var{obj}が@var{list}中に見つからなければ@code{#f}が返されます。
@c COMMON

@c EN
If the optional @var{obj=} argument of @code{member} is given,
it is used as a equivalence predicate
instead of @code{equal?}.
@c JP
@code{member}に省略可能引数@var{obj=}が与えられた場合は、
その手続きが@code{equal?}のかわりに@var{obj}と要素を比較するのに使われます。
@c COMMON
@example
(memq 'a '(a b c))          @result{} (a b c)
(memq 'b '(a b c))          @result{}  (b c)
(memq 'a '(b c d))          @result{} #f
(memq (list 'a) '(b (a) c)) @result{} #f
(memv 101 '(100 101 102))   @result{} (101 102)
@end example
@end defun

@node Association lists, Extended pairs and pair attributes, Other list procedures, Pairs and lists
@subsection Association lists
@c NODE 連想リスト

@c EN
An association list is a list of pairs.  Each @code{car} of a pair
is a key, and each @code{cdr} of a pair is an associated value.
It is the earliest data structure to represent mappings.

It takes O(N) to lookup so it's not suitable for large amount of data,
but it is still widely used since it's easy to realize immutable mapping
(the new entries can ``shadow''
the existing entries with the same key, allowing to ``change'' the content
without mutating existing maps).
@c JP
連想リストはペアのリストです。各ペアの@code{car}がキー、@code{cdr}がそのキーに
結びつけられた値です。これはマッピングを表現する最も初期のデータ構造でした。

値のルックアップにO(N)を要するのであまり大きなデータを扱うには向いていませんが、
不変データ構造を容易に実現できる (同じキーを持つエントリを追加すると既存のキーが「シャドウ」
されるため、既存のデータ構造を破壊することなく内容の変更が可能) ので、今でも広く使われています。
@c COMMON

@c EN
@subsubheading Basic constructor and accessors
@c JP
@subsubheading 基本コンストラクタとアクセサ
@c COMMON

@defun acons obj1 obj2 obj3
@c EN
Returns @code{(cons (cons @var{obj1} @var{obj2}) @var{obj3})}.
Useful to put an entry at the head of an associative list.

(This procedure is defined in SRFI-1 (R7RS @code{(scheme list)}) as @code{alist-cons}; @pxref{R7RS lists}).
@c JP
@code{(cons (cons @var{obj1} @var{obj2}) @var{obj3})} を返します。
連想リストの先頭に新しいエントリを加えるのに便利です。

(この手続きはSRFI-1 (R7RS @code{(scheme list)})では@code{alist-cons}という名前で定義されています。
@ref{R7RS lists}参照)。
@c COMMON

@lisp
(acons 'a 'b '((c . d))) @result{} ((a . b) (c . d))
@end lisp
@end defun

@defun assq obj list
@defunx assv obj list
@defunx assoc obj list :optional key=
[R7RS base]
@c EN
Each element in @var{list} should be a pair
(Gauche ignores non-pair element in @var{list}, but other R7RS
implementation may raise an error, so be aware of it when you're
writing a portable code).
These procedures search a pair whose car matches @var{obj}
(in the sense of @code{eq?} for @code{assq},
@code{eqv?} for @code{assv}, and @code{equal?} for @code{assoc})
from left to right, and return the leftmost matched pair if any.
If no pair matches, these return @code{#f}.
@c JP
@var{list}の各要素はペアでなければなりません
(Gaucheは@var{list}中のペアでない要素を単に無視しますが、
他のR7RS処理系はエラーを投げるかもしれないので、
ポータブルなコードを書いている時は注意してください)。
これらの手続きは、@var{list}の要素であるペアのうち、そのcarが
@var{obj}と一致するペアを左から探して行きます。もし見付かればそのペアが、
見付からなければ@code{#f}が返されます。
@code{assq}は比較関数に@code{eq?}を、@code{assv}は@code{eqv?}を、
@code{assoc}は@code{equal?}をそれぞれ用います。
@c COMMON

@c EN
If the optional argument of @code{assoc} is given,
it is called instead of @code{equal?}
to check the equivalence of @var{obj} and each key.
@c JP
@code{assoc}の省略可能引数が与えられた場合は、
その手続きが@code{equal?}のかわりに、
@var{obj}と各キーとの同一性判定に使われます。
@c COMMON
@end defun

@defun rassoc val alist :optional val=
@defunx rassq val alist
@defunx rassv val alist
@c EN
Reverse associations---given @var{val} is matched to the @emph{cdr}
of each element in @var{alist}, instead of the @emph{car}.
Handy to realize bidirectional associative list.
@code{Rassoc} takes an optional comparison function, whose default is
@code{equal?}.  @code{Rassq} and @code{rassv} uses @code{eq?} and @code{eqv?}.
@c JP
与えられる@var{val}が@var{alist}のそれぞれの要素で、@emph{car}の代わりに
@emph{cdr}にマッチするような逆になった連想リストです。
両方向の連想リストと理解すると簡単です。
@code{rassoc}は、そのデフォルトが@code{equal?}である、オプションの
比較関数を取ります。@code{rassq}は@code{eq?}、@code{rassv}は@code{eqv?}を
使います。
@c COMMON
@end defun

@c EN
@subsubheading Advanced operations
@c JP
@subsubheading 進んだ操作
@c COMMON


@defun alist-copy alist
[R7RS list]
@c EN
Returns a fresh copy of @var{alist}.
The spine of @var{alist} and each cell that points a key and a value
is copied.
@c JP
@var{alist} の新しい複製を返します。@var{alist} の背骨の部分、
およびキーと値を指す各セルは複製されます。
@c COMMON
@example
(define a (list (cons 'a 'b) (cons 'c 'd)))
a @result{} ((a . b) (c . d))

(define b (alist-copy a))
b @result{} ((a . b) (c . d))

(set-cdr! (car a) 'z)
a @result{} ((a . z) (c . d))
b @result{} ((a . b) (c . d))
@end example
@end defun

@defun alist-ref alist key :optional key= default
@c EN
Lookup @var{key} from an assoc list @var{alist},
in the symmetric way with other @code{*-ref} procedures.
Keys are compared with @var{key=}, which defaults to @code{equal?}.

This captures the common pattern of alist access:
@c JP
他の*-ref手続きと対称的な方法で、連想リスト@var{alist}から@var{key}を
探します。キーは@var{key=}で比較され、省略時は@code{equal?}が使われます。

これは、一般的な連想リストアクセスのパターンを提供します。
@c COMMON
@example
(alist-ref alist key default eq-fn)
  @equiv{}
  (cond [(assoc key alist eq-fn) => cdr]
        [else default])))
@end example

@c EN
If @var{default} is omitted, @code{#f} is used.
@c JP
@var{default}が省略されると、@code{#f}が使われます。
@c COMMON

@c EN
NB: This procedure supersedes a legacy @code{assoc-ref}, @code{assq-ref}
and @code{assv-ref}, by the following reasons:
Its name is very similar to @code{assoc} etc. but the
argument order is different, and most other modern alist operators
has the name prefix @code{alist-}.
Be aware that the optional arguments of @code{alist-ref} differs
from @code{assoc-ref}, when you update your code.  It is to make it
easier to cover the valiations of key equality procedures, e.g.
@code{(assq-ref alist key)} @equiv{} @code{(alist-ref alist key eq?)}.
@c JP
註: この手続きは、旧式の@code{assoc-ref}、@code{assq-ref}、@code{assv-ref}を
置き換えるものです。これらの手続きは、@code{assoc}等と似た名を持つのに
引数順が異なり、また新しい連想リスト操作は@code{alist-}をプレフィクスに持つという
原則からも外れていることから、非推奨となりました。
@code{assoc-ref}を使っているコードを@code{alist-ref}に書き換える際には、
省略可能引数の順序が異なっていることに注意してください。これは、@code{alist-ref}
で複数のバリエーションをカバーしやすくするためです。
例えば@code{(assq-ref alist key)}は@code{(alist-ref alist key eq?)}で
置き換えられます。
@c COMMON
@end defun

@defun alist-key alist val :optional val= default
@c EN
Returns a key that has the associated value equal to @var{val}.
This is to @code{alist-ref} as @code{rassoc} is to @code{assoc}.
The value is compared by @var{val=}, whose default is @code{equal?}.
If no entry's value matches @var{val}, @var{default} is returned,
whose default is @code{#f}.
@c JP
値が@var{val}に一致するようなキーを連想リスト@var{alist}から探して返します。
@code{alist-key}と@code{alist-ref}の関係は、
@code{assoc}に対する@code{rassoc}の関係に相当します。
値の等価性は@var{val=}で比較されます。デフォルトは@code{equal?}です。
@var{val}に一致する値を持つエントリが無かった場合は@var{default}が
返されます。そのデフォルトは@code{#f}です。
@c COMMON

@example
(alist-key alist val val= default)
  @equiv{}
  (cond ((rassoc val alist val=) => car)
        (else default))
@end example

@c EN
NB: This procedure supersedes legacy @code{rassoc-ref},
@code{rassq-ref}, and @code{rassv-ref}.  See @code{alist-ref}
entry above for the rationale.  Be aware of the order of
optional arguments, which differs from @code{rassoc-ref}.
@c JP
註: この手続きは旧式の@code{rassoc-ref}、@code{rassq-ref}、@code{rassv-ref}を
置き換えるものです。省略可能引数の順序が@code{rassoc-ref}と異なっていることに
注意してください。
@c COMMON
@end defun

@defun alist-set! alist key val :optional key=
@c EN
Returns an alist who has @code{(key . val)} pair added to the @code{alist}.
If @code{alist} already has an element with @var{key}, the element's
@emph{cdr} is destructively modified for @var{val}.
If @var{alist} doesn't have an element with @var{key}, a new pair
is created and appended in front of @var{alist}; so you should use
the return value to guarantee @var{key}-@var{val} pair is added.

The keys are compared with @var{key=}, whose default is @code{equal?}.

If you don't want to mutate the original alist, use @code{alist-adjoin} below.
@c JP
@code{alist}に@code{(key . val)}のペアが追加された連想リストを返します。
@code{alist}がすでに@var{key}をキーとする要素を持っている場合、
その要素の@emph{cdr}は破壊的に@var{val}に変更されます。
@var{alist}が@var{key}をキーとする要素を持っていない場合は、
新しいペアが作成され、@var{alist}の一番前に追加されます。
したがって、@var{key}-@var{val}ペアが追加されたことを保証するために
その戻り値を使うべきです。

キーは@var{key=}によって比較されます。デフォルトは@code{equal?}です。

元のalistを破壊したくない場合は、下の@code{alist-adjoin}を使ってください。
@c COMMON
@end defun

@defun alist-adjoin alist key val :optional key=
@c EN
A functional variation of @code{alist-set!}.

If @var{alist} contains an entry with @var{key}, returns a new associative list
where the value of the @var{key} is replaced for @var{val}. The order
of entries in @var{alist} is preserved.  If @var{alist} doesn't contain
the entry, it returns @code{(acons @var{key} @var{val} @var{alist})}.

The original @var{alist} is left unmodified.  The returned associative list may
share a part of its tail with the original @var{alist}, however.

The optional @var{key=} argument is a procedure with two arguments
to be used to compare the keys; the default is @code{equal?}.
@c JP
@code{alist-set!}の非破壊的バージョンです。

@var{alist}が@var{key}をキーとするエントリを持っていた場合、その値を@var{val}に
変えた新たな連想リストを作って返します。@var{alist}中のエントリの順序は保存されます。
もし@var{alist}中に@var{key}をキーとするエントリが無い場合は、
@code{(acons @var{key} @var{val} @var{alist})}が返されます。

元の@var{alist}は変更されません。但し、返された連想リストは@var{alist}と末尾部分を
共有するかもしれません。

@var{key=}引数は2引数を取る手続きで、キーの比較に使われます。
省略された場合は@code{equal?}が使われます。
@c COMMON
@end defun

@defun alist-delete key alist :optional key=
@defunx alist-delete! key alist :optional key=
[R7RS list]
@c EN
Deletes all cells in @var{alist} whose key is the same as @var{key}.
Comparison is done by a procedure @var{key=}.  The default is @code{equal?}.

The linear-update version @code{alist-delete!} may or may not modify
@var{alist}.
@c JP
@var{alist} から @var{key}と同じキーをもつすべてのセルを削除します。
比較は @var{key=} で行います。これのデフォルト値は @code{equal?} です。

その場で更新を行うバージョン @code{alist-delete!} は元の
@var{alist} を変更してしまうことがあります。
@c COMMON

@c EN
Note the order of arguments: Unfortunately, this procedure
doesn't follow the rule to take @var{alist} as the first argument
This is defined in srfi-1 and followed @code{assoc}.
@c JP
引数順についての注意: 残念なことに、この手続きは@var{alist}を最初の引数に取るという
原則から外れています。この手続きはSRFI-1で定義され、それは@code{assoc}
の引数順に合わせました。
@c COMMON
@end defun

@defun alist-merge [key=] reducer alist1 alist2 @dots{}
@c EN
Returns a new assoc list that contains all keys in
@var{alist1} @var{alist2} @dots{}.  If more than one input alist
have the same key, they are merged to a single entry using @var{reducer}
as follows:
Suppose values of those entries are @var{x}, @var{y}, and @var{z},
in the order of appearance in the input alists.  Then the
value of the resulting entry is
@code{(@var{reducer} @var{x} (@var{reducer} @var{y} @var{z})}.
@c JP
@var{alist1} @var{alist2} @dots{} に含まれている全てのキーを含むような
新たな連想リストを返します。同じキーを持つエントリが複数の入力連想リストに
含まれていた場合は、その値は@var{reducer}を用いて次のとおり計算されます:
入力に含まれる同じキーを持つエントリの値が順に@var{x}、@var{y}、@var{z}であったとすると、
結果の連想リストの値は
@code{(@var{reducer} @var{x} (@var{reducer} @var{y} @var{z})}。
@c COMMON

@example
(alist-merge + '((a . 1) (b . 2)) '((c . 3) (a . 4)) '((b . 5)))
 @result{} ((a . 5) (b . 7) (c . 3))
(alist-merge string=? append
  '(("a" 1) ("b" 2) ("c" 3))
  '(("b" 4) ("d" 5))
  '(("c" 6)))
 @result{} (("a" 1) ("b" 2 4) ("c" 3 6) ("d" 5))
@end example

@c EN
The order of entries of the result preserves the order of the input,
except the duplicate key entries are merged into the first one.
@c JP
結果のエントリの順序は、重複キーのエントリが最初のエントリにマージされていること以外は
入力の連想リストの順序を保存します。
@c COMMON

@c EN
Note: This assumes each alist doesn't have duplicate keys in itself.
To gether entries of the same keys in an alist, you can use
@code{group-collection->alist} in @code{gauche.collection}
(@pxref{Collection framework}).
@c JP
註: この手続きは、それぞれのalist内には重複するキーのエントリが無いことを仮定しています。
ひとつのalist内で同じキーを持つエントリを集めるには、
@code{gauche.collection}の@code{group-collection->alist}が使えます
(@ref{Collection framework}参照)。
@c COMMON
@end defun

@defun alist-update-in alist keys proc :optional key= default
@c EN
This procedure allows to update a nested associative list.
The @var{alist} argument is a (possibly nested) associative list,
@var{keys} are a list of keys, and @var{proc} is a procedure
that takes one argument.  First, the keys are looked up
recursively in @var{alist}; then its value is passed to @var{proc}.
The return value is a new (nested) associative list where the value
pointed by @var{keys} is replaced with the return value of @var{proc}.
@c JP
この手続きは、ネストした連想リストを更新するのに使えます。
@var{alist}はネストした連想リストです。
@var{keys}はキーのリストで、@var{proc}は1引数を取る手続きです。
まず、@var{keys}にあるキーを順に使って、ネストした連想リストから
値が取り出され、@var{proc}に渡されます。
手続きの戻り値は新しいネストした連想リストで、該当するエントリの値が
@var{proc}の戻り値に置き換えられたものとなります。
@c COMMON

@example
(alist-update-in '((a (b . 1) (c . 2))) '(a c) (cut + <> 1))
  @result{} ((a (b . 1) (c . 3))
@end example

@c EN
The order of entries are preserved.  The original @var{alist}
is left unmodified, but the returned value may share a part of
the structure with @var{alist}.
@c JP
エントリの順序は保存されます。元の@var{alist}は変更を受けませんが、
戻り値と部分構造を共有するかもしれません。
@c COMMON

@c EN
If @var{alist} doesn't have the entry specified by @var{keys},
a new entry is added.  A new entry is added at the beginning of
the sequence where specified key didn't exist.
@c JP
@var{alist}が@var{keys}で指定されるエントリを持たない場合は新たなエントリが
追加されます。新たなエントリは、キーが存在しないシーケンスの先頭に付け加えられます。
@c COMMON

@example
(assoc-update-in '((a (b . 1) (c . 2))) '(a d e) (^_ 99))
  @result{} ((a (d (e . 99)) (b . 1) (c . 3)))
@end example

@c EN
The @var{default} argument is passed to @var{proc} when there's
no entry with specified keys.  If omitted, @code{#f} is assumed.
@c JP
@var{default}引数は、キーに対応するエントリが存在しなかった場合に@var{proc}に
渡されます。省略値は@code{#f}です。
@c COMMON

@c EN
The optional @var{key=} argument is a procedure with two arguments
to be used to compare the keys; the default is @code{equal?}.
@c JP
@var{key=}引数は2引数を取る手続きで、キーの比較に使われます。
省略された場合は@code{equal?}が使われます。
@c COMMON

@c EN
Note: For destructively updating general nested aggregate structures,
setter of @code{~} is handy (@pxref{Universal accessor}).  You can modify
an entry in a hashtable in a vector in a list, for example.  Associative
list is a bit special, since you can't distinguish it from lists
(thus @code{~} can't be used), and it is mostly used in functional way.
So we added a special update procedure.
@c JP
註: ネストした集合データ構造の一部を破壊的に更新するには、
@code{~}のセッタが便利です(@ref{Universal accessor}参照)。
例えばハッシュテーブルのベクタのリスト、から一番奥のハッシュテーブルのエントリを
更新することが出来ます。しかし連想リストはちょっと特殊で、リストと型的に区別
できないため、@code{~}が使えません。連想リストはまた、関数的に使われることも
多いため、専用の更新手続きを用意しました。
@c COMMON
@end defun

@c EN
@subsubheading Deprecated procedures
@c JP
@subsubheading 非推奨の手続き
@c COMMON

@c EN
The following procedures are deprecated for the naming consistency.
Except a handful historical procedures (@code{assoc} etc.), associative
list operations are now named @code{alist-*} and takes alist as the
first argument as long as it is relevant.
@c JP
以下の手続きは、名前の一貫性のために非推奨となったものです。
@var{assoc}のような歴史的ないくつかの手続き以外は、現在の連想リスト操作は
@code{alist-*}と命名され、原則として連想リストを第一引数に取ります。
@c COMMON

@defun assoc-ref alist key :optional default key=
@defunx assq-ref alist key :optional default
@defunx assv-ref alist key :optional default
@c DEPRECATED
@c EN
@code{(assoc-ref alist key default key=)} @equiv{}
@code{(alist-ref alist key key= default)}.  Note the order of
the optional arguments.

@code{(assq-ref alist key default)} @equiv{}
@code{(alist-ref alist key eq? default)}.

@code{(assv-ref alist key default)} @equiv{}
@code{(alist-ref alist key eqv? default)}.
@c JP
@code{(assoc-ref alist key default key=)} @equiv{}
@code{(alist-ref alist key key= default)}.
省略可能引数の順序に注意。

@code{(assq-ref alist key default)} @equiv{}
@code{(alist-ref alist key eq? default)}.

@code{(assv-ref alist key default)} @equiv{}
@code{(alist-ref alist key eqv? default)}.
@c COMMON
@end defun

@defun rassoc-ref alist val :optioanl default val=
@defunx rassq-ref alist val :optional default
@defunx rassv-ref alist val :optional default
@c DEPRECATED
@c EN
@code{(rassoc-ref alist val default val=)} @equiv{}
@code{(alist-key alist val val= default)}.  Note the order of
the optional arguments.

@code{(rassq-ref alist val default)} @equiv{}
@code{(alist-key alist val eq? default)}.

@code{(rassv-ref alist key default)} @equiv{}
@code{(alist-key alist val eqv? default)}.
@c JP
@code{(rassoc-ref alist val default val=)} @equiv{}
@code{(alist-key alist val val= default)}.
省略可能引数の順序に注意。

@code{(rassq-ref alist val default)} @equiv{}
@code{(alist-key alist val eq? default)}.

@code{(rassv-ref alist key default)} @equiv{}
@code{(alist-key alist val eqv? default)}.
@c COMMON
@end defun

@defun assoc-set! alist key val :optional key=
@defunx assq-set! alist key val
@defunx assv-set! alist key val
@c DEPRECATED
@code{(assoc-set! alist key val key=)} @equiv{} @code{(alist-set! alist key val key=)}.

@code{(assq-set! alist key val)} @equiv{} @code{(alist-set! alist key val eq?)}.

@code{(assv-set! alist key val)} @equiv{} @code{(alist-set! alist key val eqv?)}.
@end defun

@defun assoc-adjoin alist key val :optional key=
@c DEPRECATED
@c EN
Same as @code{alist-adjoin}.
@c JP
@code{alist-adjoin}と同じです。
@c COMMON
@end defun

@defun assoc-update-in alist keys proc :optional default key=
@c DEPRECATED
@code{assoc-update-in alist keys proc default key=}
@equiv{}
@code{alist-update-in alist keys proc key= default}

@c EN
Note the order of optional arguments.
@c JP
省略可能引数の順序に注意。
@c COMMON
@end defun

@node Extended pairs and pair attributes,  , Association lists, Pairs and lists
@subsection Extended pairs and pair attributes
@c NODE 拡張ペアとペア属性

@c EN
Gauche has a special kind of pairs, called @emph{extended pairs}.
It behaves exactly the same as ordinary pairs, but you can associate
an attribute list to it.  Gauche uses it to keep source-code
location information, for example.
@c JP
Gaucheは、拡張ペア (extended pair) と呼ばれる特別なペアを持っています。
これは通常のペアと同じように振る舞いますが、属性リストを付加することができます。
例えば、Gaucheはソースコードの位置情報を保持するのに拡張ペアを使っています。
@c COMMON

@c EN
Extended pairs don't incur any overhead in accessing its car/cdr;
@code{set-car!}
and @code{set-cdr!} has a little overhead (another reason you should avoid
mutation!).
Internally it takes up twice
of memory than the ordinary pairs.
@c JP
拡張ペアのcar/cdrへのアクセスにオーバーヘッドは全くありません。
@code{set-car!}と@code{set-cdr!}
には少しだけオーバヘッドがあります (できるだけ副作用を避けましょう!)。
内部的に、拡張ペアは通常のペアの倍のメモリを使います。
@c COMMON

@c EN
Pair attributes are not written out in the external representation,
and not copied by @code{copy-list} and many other list procedures
that constructs the output list from the input list.
That is, they are easily lost.   Use them for the ancillary information
which is nice to have but not mandatory.
@c JP
ペア属性は外部表現には書き出されませんし、@code{copy-list}や、出力リストを
入力リストを元に新たに組み立てる多くのリスト手続きでコピーされません。
つまり、ペア属性は簡単に失われます。「あったら良いけど、必須ではない」という
補助的な情報に使うのが良いでしょう。
@c COMMON

@c EN
Keep in mind that code using extended pairs is not easily ported to
other Scheme implementations, although the
feature can be emulated with a separate weak hash table.
@c JP
また、拡張ペアを使ったコードは、弱参照ハッシュテーブルでエミュレートできるとはいえ、
他のScheme処理系には簡単に移植できないことに留意してください。
@c COMMON

@defun extended-pair? obj
@c EN
Returns @code{#t} iff @var{obj} is an extended pair.
@c JP
@var{obj}が拡張ペアなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun extended-cons car cdr :optional attrs
@c EN
Returns an extended pair of @var{car} and @var{cdr}.
If an optional @var{attrs} argument is given, it must be an alist,
specifying initial pair attributes.  By default, the pair attributes
of the created extended pair is empty.
@c JP
@var{car}と@var{cdr}からなる拡張ペアを作って返します。
@var{attrs}引数が与えられた場合、
それはペア属性の初期値を指定する連想リストでなければなりません。
デフォルトでは作られる拡張ペアのペア属性は空です。
@c COMMON
@end defun

@defun extended-list obj obj2 @dots{}
@c EN
Creates and returns a list of @var{obj} @var{obj2} @dots{}, but its
first pair is an extended pair.  Note that the subsequent pairs are
ordinary pairs.
@c JP
@var{obj} @var{obj2} @dots{}からなるリストを作って返しますが、
最初のペアが拡張ペアになっています。二番目以降のペアは通常のペアです。
@c COMMON
@end defun

@defun extended-list-copy obj
@c EN
Copies the ``spine'' of a (possibly dotted) list @var{obj}.
If it includes an extended pair, a new extended pair is created
sharing the same pair attributes. (Pair attribute list itself
isn't copied).
@c JP
@var{obj}の「背骨」にあたるリストをコピーします。@var{obj}はドットリストでも
構いません。
@var{obj}が拡張ペアを含んでいた場合は、ペア属性を共有する新たな拡張ペアが
作られます。(ペア属性自体はコピーされません)。
@c COMMON

@example
(define a (extended-cons 1 (extended-cons 2 3 '((A . B))) '((C . D))))

(define b (extended-list-copy a))

(pair-attributes b) @result{} ((C . D))
(pair-attributes (cdr b)) @result{} ((A . B))
@end example

@end defun

@defun pair-attributes pair
@c EN
Returns pair attributes of @var{pair} as an alist.
You can pass an ordinary pair, in which case an empty list is returned.
@c JP
@var{pair}のペア属性を連想リストとして返します。
通常のペアを引数に渡すこともできます。その場合は常に空リストが返ります。
@c COMMON

@example
(pair-attributes (extended-cons 'a 'b '((c . d) (e . f))))
  @result{} ((c . d) (e . f))

(pair-attributes (cons 'a 'b)
  @result{} ()
@end example
@end defun

@defun pair-attribute-get pair key :optional default
@c EN
Returns the value associated to the key @var{key} in the pair attributes
of @var{pair}.  @var{Key} can be any Scheme object, and compared with @code{eq?}.
If there's no value associated with the given key,
@var{default} is returned if it is given, otherwise an error is signaled.

You can pass an ordinary pair as @var{pair}; in that case, it is treated
with empty pair attributes.
@c JP
@var{pair}のペア属性のうち、キー@var{key}に結びつけられた値を返します。
@var{key}は任意のSchemeオブジェクトで、@code{eq?}で比較されます。
キーに結びついた値がない場合、@var{default}が与えられていればそれが返され、
与えられていなければエラーが投げられます。

通常のペアを@var{pair}に渡すこともできます。その場合、ペア属性は空として扱われます。
@c COMMON
@end defun

@defun pair-attribute-set! pair key value
@c EN
Adds a pair attribute of @var{key} with @var{value} to an extended pair
@var{pair}.  @var{Key} and @var{value} can be any Scheme object.
An error is thrown if @var{pair} is not an exteded pair.
@c JP
拡張ペア@var{pair}のペア属性@var{key}に値@var{value}をセットします。
@var{key}と@var{value}は任意のSchemeオブジェクトです。
@var{pair}が拡張ペアでなければエラーが投げられます。
@c COMMON

@c EN
This procedure does not mutate the exising alist, but rather makes
a necessary copy.  The pair attributes
are not supposed to be mutated frequently.
@c JP
この手続きは既存の連想リスト自体は変更せず、必要に応じてコピーします。
ペア属性は頻繁に変更される運用を想定していません。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Symbols, Characters, Pairs and lists, Core library
@section Symbols
@c NODE シンボル

@c EN
Gauche enhances Scheme symbols in a couple of ways:
@c JP
GaucheはSchemeシンボルを若干拡張しています。
@c COMMON

@table @b
@item Uninterned symbols
@c EN
Like Common Lisp, you can create an @emph{uninterned} symbol, which is
not registered to the internal table, so it is guaranteed not to be @code{eq?}
to any other symbols created by @code{string->symbol} or @code{read}.

Since Scheme's hygienic macro system automatically avoids name collisions,
uninterned symbols are less needed than Common Lisp, but it comes handy
when you want a unique object with some descriptive name.
@c JP
Common Lispのように、内部のテーブルに登録されない
「インターンされない(uninterned)」シンボルを作ることができます。
このシンボルは、他の@code{string->symbol}や@code{read}が作るシンボルと
決して@code{eq?}にならないことが保証されています。

Schemeの衛生的マクロは名前の衝突を自動的に回避するので、Common Lispほど
出番はありませんが、名前を持つユニークなオブジェクトが欲しい時には便利です。
@c COMMON
@item Keywords
@c EN
A symbol whose name begins with a colon (@code{:}) is automatically
bound to itself in @code{gauche.keyword} module.  By importing or inheriting
it, you can use such symbols as if they're self-evaluating object.  They're
extensively used in Gauche for passing keyword arguments.
@c JP
名前がコロン@code{:}で始まるシンボルは自動的に、@code{gauche.keyword}モジュール内で
自分自身に束縛されます。このモジュールをインポートするか継承すれば、
そういったシンボルをまるで自己評価オブジェクトのように使うことができます。
Gaucheではキーワード引数でこの機能を多用します。
@c COMMON
@end table

@menu
* Basic symbols::
* Uninterned symbols::
* Keywords::
* Keyword and symbol integration::
@end menu

@node Basic symbols, Uninterned symbols, Symbols, Symbols
@subsection Basic symbols
@c NODE 基本的なシンボル

@deftp {Builtin Class} <symbol>
@clindex symbol
@c EN
A class for symbols.
@c JP
シンボルを表すクラスです。
@c COMMON
@end  deftp

@deftp {Reader Syntax} @code{|@i{name}|}
@lxindex |
[R7RS]
@c EN
Denotes a symbol that has weird name, including the characters
that are not usually allowed in symbols.  It can also include
hex-escaped characters.
@c JP
シンボルの定義では通常許されないような文字を使った妙な名前のシンボルを表記するのに
使う構文です。16進数エスケープ表記を含めることもできます。
@c COMMON

@example
@c EN
;; @r{A symbol with spaces in its name}
@c JP
;; @r{空白を名前に含むシンボル}
@c COMMON
'|this is a symbol| @result{} |this is a symbol|

@c EN
;; @r{Unicode codepoint can be used following backslash-x escape,}
;; @r{and terminated by semicolon.}
@c JP
;; @r{Unicodeコードポイントを、バックスラッシュとxからなるエスケープに続けて}
;; @r{書くこともできます。セミコロンで終端します。}
@c COMMON
'|\x3bb;| @result{} λ
@end example

@c EN
If the interpreter is running in case-insensitive mode, this syntax
can be used to include uppercase characters in a symbol
(@pxref{Case-sensitivity}).
@c JP
インタプリタが大文字小文字を区別しないモードで走っている場合は、
大文字を含むシンボルを表記するときにも使えます (@ref{Case-sensitivity}参照)。
@c COMMON
@end deftp


@defun symbol? obj
[R7RS base]
@c EN
Returns true if and only if @var{obj} is a symbol.
@c JP
@var{obj}がシンボルなら@code{#t}を返します。
@c COMMON
@example
(symbol? 'abc)     @result{} #t
(symbol? 0)        @result{} #f
(symbol? 'i)       @result{} #t
(symbol? '-i)      @result{} #f
(symbol? '|-i|)    @result{} #t
@end example
@end defun


@defun symbol=? a b c @dots{}
[R7RS base]
@c EN
Every argument must be a symbol.  Returns @code{#t} iff
every pair of arguments are @code{eq?} to each other.
@c JP
全ての引数はシンボルでなければなりません。引数のどの二つの組み合わせを取っても
それが@code{eq?}である時に限り、@code{#t}が返ります。
@c COMMON
@end defun

@defun symbol->string symbol
[R7RS base]
@c EN
Returns the name of @var{symbol} in a string.  Returned
string is immutable.
@c JP
@var{symbol}の名前を文字列で返します。返される文字列は変更不可です。
@c COMMON

@example
(symbol->string 'foo) @result{} foo
@end example
@end defun

@defun string->symbol string
[R7RS base]
@c EN
Returns a symbol whose name is a string @var{string}.
@var{String} may contain weird characters.
@c JP
文字列@var{string}を名前に持つシンボルを返します。
@c COMMON

@example
(string->symbol "a") @result{} a
(string->symbol "A") @result{} A
(string->symbol "weird symbol name") @result{} |weird symbol name|
@end example
@end defun

@defun symbol-sans-prefix symbol prefix
@c EN
Both @var{symbol} and @var{prefix} must be symbols.
If the name of @var{prefix} matches the beginning part of the
name of @var{symbol}, this procedure returns a symbol whose
name is the name of @var{symbol} without the matched prefix.
Otherwise, it returns @code{#f}.
@c JP
@var{symbol}と@var{prefix}は共にシンボルでなければなりません。
@var{prefix}が@var{symbol}の先頭部分にマッチした場合、
@var{symbol}からマッチ部分を取り除いた名前を持つシンボルを返します。
マッチしない場合は@code{#f}を返します。
@c COMMON

@example
(symbol-sans-prefix 'foo:bar 'foo:) @result{} bar
(symbol-sans-prefix 'foo:bar 'baz:) @result{} #f
@end example
@end defun

@defun symbol-append interned? objs @dots{}
@defunx symbol-append objs @dots{}
@c EN
Returns a symbol with the name which is a concatenation of
string representation of @var{objs}.

If the first argument is a boolean, it is recognized as the
first form; the first argument specifies whether the resulting
symbol is interned or not.

Each other argument is converted to a string as follows:
If it is a keyword, its name (with the preceding @code{:}) is used.
For all other objects, @code{x->string} is used.  (The special treatment
of keyword is to keep the consistency before and after
keyword-symbol integration.  @xref{Keyword and symbol integration}, for
the details.)

This is upper-compatible to Bigloo's same name procedure, which
only allows symbols as the arguments and the result is always interned.
@c JP
@var{objs}の文字列表記をつなげた名前を持つシンボルを返します。

最初の引数が真偽値の場合は、最初の形式と解釈されます。@var{interned?}引数は
結果のシンボルがインターンされているかどうかを指定します。

それ以外の引数はそれぞれ次のとおり変換されます：キーワードであれば
(先頭の@code{:}を含む)名前に、それ以外は@code{x->string}を適用した結果に。
(キーワードを特別扱いするのは、キーワード-シンボル統合の後でも動作が
変わらないようにするためです。詳しくは@ref{Keyword and symbol integration}を
参照。)

これは、Biglooにある同名の手続きの上位互換になっています。Bigloo版は
シンボルのみを引数に許し、また結果は常にインターンされます。
@c COMMON

@example
(symbol-append 'ab 'cd) @result{} abcd
(symbol-append 'ab ':c 30) @result{} ab:c30
(symbol-append #f 'g 100) @result{} #:g100
@end example
@end defun

@node Uninterned symbols, Keywords, Basic symbols, Symbols
@subsection Uninterned symbols
@c NODE インターンされないシンボル

@deftp {Reader Syntax} @code{#:@i{name}}
@c EN
Denotes @emph{uninterned} symbol.  Uninterned symbols can be created
by @code{gensym} or @code{string->uninterned-symbol}.
@c JP
「インターンされていない」シンボルを表記します。インターンされていないシンボルは
@code{gensym}か@code{string->uninterned-symbol}で作ることができます。
@c COMMON

@c EN
Uninterned symbols are mainly for legacy macros to avoid
variable conflicts.   They are not registered in the internal
dictionary, so such symbols with the same name can't be @code{eq?}.
@c JP
インターンされていないシンボルは、良く伝統的なマクロで
変数衝突を避けるために使われます。インターンされていないシンボルは
内部のシンボルのテーブルに登録されないため、同じ名前のシンボルでも
@code{eq?}になりません。
@c COMMON

@example
(eq? '#:foo '#:foo) @result{} #f
(eq? '#:foo 'foo) @result{} #f
@end example

@c EN
To preserve @code{eq?}-ness of uninterened symbols,
you need to use @code{write-shared} which
shows shared structures.
@c JP
インターンされていないシンボルが含まれるS式を、
シンボルの同一性を保って表示するには、
@code{write-shared}を使います。
@c COMMON

@example
(write-shared (let1 s '#:foo (list s s)))
  @result{} @r{prints} (#0=#:foo #0#)

(write-shared (let ((s '#:foo) (t '#:foo)) (list s t s t)))
  @result{} @r{prints} (#0=#:foo #1=#:foo #0# #1#)
@end example
@end deftp

@defun symbol-interned? symbol
[SRFI-258]
@c EN
Returns @code{#t} if @var{symbol} is an interned symbol,
@code{#f} if it is an uninterned symbol.   An error is signaled
if @var{symbol} is not a symbol.
@c JP
シンボル@var{symbol}がインターンされていれば@code{#t}を、
そうでなければ@code{#f}を返します。シンボルでないものが渡された場合はエラーとなります。
@c COMMON

@c EN
This is included in SRFI-258 (@pxref{Uninterned symbols (SRFI)}).
@c JP
これはSRFI-258に含まれています(@ref{Uninterned symbols (SRFI)}参照)。
@c COMMON
@end defun

@defun string->uninterned-symbol string
[SRFI-258]
@c EN
Like @code{string->symbol}, but the created symbol is uninterned.
@c JP
@code{string->symbol}と似ていますが、作られたシンボルはインターンされません。
@c COMMON

@example
(string->uninterned-symbol "a") @result{} #:a
@end example

@c EN
This is included in SRFI-258 (@pxref{Uninterned symbols (SRFI)}).
@c JP
これはSRFI-258に含まれています(@ref{Uninterned symbols (SRFI)}参照)。
@c COMMON
@end defun


@defun gensym :optional prefix
@c EN
Returns a fresh, uninterned symbol.  The returned symbol can never
be @code{eq?} to other symbol within the process.
If @var{prefix} is given, which must be a string, it is used
as a prefix of the name of the generated symbol.  It is mainly for
the convenience of debugging.
@c JP
インターンされてない、新しいシンボルを作って返します。
返されるシンボルは、他のシンボルとは決して@code{eq?}にならないことが保証されます。
@var{prefix}が与えられた場合は、それは文字列でなければならず、
それが作られるシンボルのプレフィクスに使われます。これは主としてデバッグを
容易にするためのものです。
@c COMMON

@c EN
This is similar to SRFI-258's @code{generate-uninterned-symbol}
(@pxref{Uninterned symbols}).
@c JP
これはSRFI-258の@code{generate-uninterned-symbol}と似ています
(@ref{Uninterned symbols}参照)。
@c COMMON
@end defun



@node Keywords, Keyword and symbol integration, Uninterned symbols, Symbols
@subsection Keywords
@c NODE キーワード

@deftp {Builtin Class} <keyword>
@clindex keyword
@c EN
Keywords are a subtype of symbols that are automatically bound
to itself.
It is extensively used in named arguments (keyword arguments),
and keyword-value list.

See @ref{Making procedures} for how Gauche supports keyword
arguments, and @code{let-keywords} macro (@ref{Optional argument parsing})
for parsing keyword-value list manually.

NB: Keywords used to be a disjoint type from symbols.  We suppored
that compatibility mode with a special environment variable up to 0.9.15,
but no longer provide that mode.
@xref{Keyword and symbol integration}, if you need to update your code.
@c JP
キーワードは、自動的に自分自身に束縛されるシンボルのサブタイプです。
名前つき引数(キーワード引数)や、キーワード-値のリストで広く使われて
います。

Gaucheにおけるキーワード引数のサポートについては@ref{Making procedures}を、
また独自にキーワード-値リストをパーズする方法については
@code{let-keywords} マクロ(@ref{Optional argument parsing}) も参照して下さい。

註: キーワードはかつてはシンボルと独立した型でした。互換性のために、
0.9.15までは、環境変数によって以前の振る舞いに切り替えるモードがありましたが、
そのモードはサポートされなくなりました。
以前の振る舞いに依存しているコードがあれば@ref{Keyword and symbol integration}を
参考にアップデートしてください。
@c COMMON
@end  deftp

@deftp {Reader Syntax} @code{:@var{name}}
@c EN
Read to a keyword whose name is @var{:name}.
@c JP
名前が @var{:name} であるキーワードとして読み込まれます。
@c COMMON
@end deftp

@defun keyword? obj
@c EN
Returns @code{#t} if @var{obj} is a keyword.
@c JP
@var{obj} がキーワードであれば、@code{#t} を返します。
@c COMMON
@end defun

@defun make-keyword name
@c EN
Returns a keyword whose name is @var{name} prepended by @code{:}.
The @var{name} argument can be a string or a symbol.
@c JP
@var{name}の前に@code{:}を付加した名前を持つキーワードを返します。
@var{name}には文字列かシンボルが許されます。
@c COMMON
@example
(make-keyword "foo")  @result{} :foo

(make-keyword 'foo)   @result{} :foo
@end example
@end defun

@defun keyword->string keyword
@c EN
Returns the name (without the initial @code{:}) of the keyword
@var{keyword}, in a string.
(This is mainly to support legacy code written when keywords are disjoint from
symbols.)
@c JP
キーワード @var{keyword} の(先頭の@code{:}を除いた)名前を文字列で返します。
(これは主に、キーワードとシンボルが別の型だった頃の古いコードをサポートする
ためのものです。)
@c COMMON
@example
(keyword->string :foo) @result{} "foo"
@end example
@end defun

@defun get-keyword key kv-list :optional fallback
@c EN
A useful procedure to extract a value from key-value list.
A key-value list @var{kv-list} must contains even number of elements;
the first, third, fifth @dots{} elements are regarded as keys,
and the second, fourth, sixth @dots{} elements are the values of
the preceding keys.

This procedure looks for @var{key} from the keys, and if it finds one,
it returns the corresponding value.
If there are more than one matching keys, the leftmost one is taken.
If there is no matching key, it returns @var{fallback} if provided,
or signals an error otherwise.

It is an error if @var{kv-list} is not a proper, even-number element list.

Actually, `keywords' in the keyword-value list and the @var{key} argument
need not be a keyword---it can be any Scheme object.  Key comparison
is done by @code{eq?}.

This procedure is taken from STk.
@c JP
キー-値のリストから値を取り出すのに便利な手続きです。
キー-値のリスト @var{kv-list} は偶数個の要素を持たなければなりません。
1つ目、3つ目、5つ目、@dots{} の要素はキーとして扱われ、
2つ目、4つ目、6つ目、@dots{} の要素は、その前の要素をキーとした値と
なります。

この手続きは、キーの集合から @var{key} を探して、それが見つかれば、
対応する値を返します。
2つ以上のキーにマッチしたら、最左のものとなります。
マッチするキーがない場合、@var{fallback} が与えられていればそれを
返し、さもなければエラーを通知します。

@var{kv-list} が正しい偶数個の要素を持つリストでない場合は、エラーに
なります。

キーワード-値リストの `キーワード' と、@var{key} 引数は、実際には
キーワードである必要はありません。いかなる Scheme オブジェクトで
あっても良いです。キーの比較は、@code{eq?} によって行われます。

この手続きは、STk から導入されました。
@c COMMON

@example
(get-keyword :y '(:x 1 :y 2 :z 3))
  @result{} 2
(get-keyword 'z '(x 1 y 2 z 3))
  @result{} 3

(get-keyword :t '(:x 1 :y 2 :z 3))
  @result{} #<error>
(get-keyword :t '(:x 1 :y 2 :z 3) #f)
  @result{} #f
@end example
@end defun

@defmac get-keyword* key kv-list :optional fallback
@c EN
Like @code{get-keyword}, but @var{fallback} is evaluated only
if @var{kv-list} does not have @var{key}.
@c JP
@code{get-keyword} と同様ですが、@var{kv-list} が @var{key} を
含まない場合にのみ @var{fallback} が評価されることだけが違います。
@c COMMON
@end defmac

@defun delete-keyword key kv-list
@defunx delete-keyword! key kv-list
@c EN
Removes all the keys and values from @var{kv-list} for
keys that are @code{eq?} to @var{key}.
@c JP
@var{kv-list} から @var{key} に @code{eq?} であるキーをもつキーと値を
削除します。
@c COMMON

@c EN
@code{delete-keyword} doesn't change @var{kv-list}, but the returned
list may share the common tail of it.
@c JP
@code{delete-keyword} は @var{kv-list} を変更しません。しかし、
返されたリストは共通の末尾部分を共有します。
@c COMMON

@c EN
@code{delete-keyword!} doesn't allocate, and @emph{may} destructively
changes @var{kv-list}.  You still have to use the returned value,
for the original list may not be changed if its first key matches
@var{key}.
@c JP
@code{delete-keyword!} は新しくアロケートされることはありません。
そして、破壊的に @var{kv-list} を変更する@emph{可能性があります}。
最初のキーがマッチした場合元のリストは変更されないこともありえますが、
返り値のリストを使わなければいけません。
@c COMMON

@c EN
If there's no key that matches @var{key}, @var{kv-list} is returned.
@c JP
@var{key} にマッチするキーがない場合 @var{kv-list} が返ります。
@c COMMON

@example
(delete-keyword :y '(:x 1 :y 2 :z 3 :y 4))
 @result{} (:x 1 :z 3)
@end example

@end defun

@defun delete-keywords keys kv-list
@defunx delete-keywords! keys kv-list
@c EN
Similar to @code{delete-keyword} and @code{delete-keyword!}, but
you can specify a list of objects in @var{keys};
when a key in @var{kv-list} matches any of @var{keys},
the key and the following value is removed from @var{kv-list}.
@c JP
@code{delete-keyword}や@code{delete-keyword!}と似ていますが、
@var{keys}にオブジェクトのリストを指定できます。
@var{kv-list}中のキーが@var{keys}のうちのどれかに一致すれば、
そのキーと続く値が@var{kv-list}から取り除かれます。
@c COMMON

@example
(delete-keywords '(:x :y) '(:x 1 :y 2 :z 3 :y 4))
 @result{} (:z 3)
@end example

@end defun

@node Keyword and symbol integration,  , Keywords, Symbols
@subsection Keyword and symbol integration
@c NODE キーワードとシンボルの統合

@c EN
In older versions of Gauche, keywords are of disjoint type
from symbols, and they are self-evaluating objects.
To maintain the compatibility, the current Gauche makes
symbols that begins with @code{:} automatically bound to itself,
in @code{gauche.keyword} module.

The @code{gauche} module inherits @code{gauche.keyword}, so all the
keyword look like self-evaluating objects.
That allows most legacy Gauche code keep working, but there are some
catches.
@c JP
以前のGaucheでは、キーワードはシンボルとは異なる型を持ち、自分自身に評価される
オブジェクトでした。
互換性を保つため、現在のGaucheでは@code{:}で始まるシンボルは自動的に
(@code{gauche.keyword}モジュール内に)自分自身に束縛されるようになっています。

@code{gauche}モジュールは@code{gauche.keyword}モジュールを継承しているので、
キーワードはあたかも自己評価されるオブジェクトのように見えます。
これにより、古いGaucheコードもほぼ変更なしで動作します。
ただ、いくつか注意すべき点があります。
@c COMMON

@c EN
@subsubheading @code{(symbol? :key)} used to return @code{#f}, now returns @code{#t}
@c JP
@subsubheading @code{(symbol? :key)}は以前は@code{#f}を返したが、今は@code{#t}を返す
@c COMMON

@c EN
@code{keyword?} always returns @code{#t} on keywords, but
if you need to switch behavior depending whether an object is a symbol
or a keyword, you should test keyword-ness first.
@c JP
キーワードに対して@code{keyword?}は常に@code{#t}を返しますが、
シンボルかキーワードかで動作を変えるコードでは、キーワードの検査を先にするようにしてください。
@c COMMON

@example
@c EN
;; behaved differently in 0.9.7 and before
@c JP
;; 0.9.7以前は動作が異なる
@c COMMON
(cond
  [(symbol? x) (x-is-symbol)]
  [(keyword? x) (x-is-keyword)])

@c EN
;; works on all versions
@c JP
;; どのバージョンでも動く
@c COMMON
(cond
  [(keyword? x) (x-is-keyword)]
  [(symbol? x) (x-is-symbol)])
@end example

@c EN
@subsubheading Literal keywords in pattern matching
@c JP
@subsubheading パターンマッチ中のリテラルキーワード
@c COMMON

@c EN
In the old versions,
when keywords appear in a pattern of @code{util.match}
or @code{syntax-rules}, they only matched to themselves.
In the current version, such keywords in
a pattern are treated as pattern variables, since they are symbols.
@c JP
以前のバージョンでは、@code{util.match}や@code{syntax-rules}の
パターンにキーワードが現れた場合、それはキーワード自身とのみマッチしました。
現在のバージョンでは、キーワードはシンボルなので、パターン変数として扱われます。
@c COMMON

@example
@c EN
;; In the old versions
@c JP
;; 以前のバージョン
@c COMMON
(match '(a b) [(:key z) (list :key z)] [_ "nope"])
   @result{} "nope"

@c EN
;; In the current version
;; :key is treated just as a pattern variable
@c JP
;; 現在のバージョン
;; :keyは単なるパターン変数となる
@c COMMON
(match '(a b) [(:key z) (list :key z)] [_ "nope"])
   @result{} (a b)
@end example

@c EN
The same thing happens to the patterns in @code{syntax-rules}.

To make the code work in both versions, explicitly mark the keywords
as literals.
@c JP
@code{syntax-rules}でも同じことが起きます。

どのバージョンでも動くコードにするには、マッチさせたいキーワードが
リテラルであることを明示してください。
@c COMMON

@itemize @bullet
@item
@c EN
For @code{match}, quote the keywords you want to be treated as literals.
@c JP
@code{match}では、キーワードをクオートしてリテラルであることを示します。
@c COMMON
@example
(match '(a b) [(':key z) (list :key z)] [_ "nope"])
   @result{} "nope"
@end example

@item
@c EN
For @code{syntax-rules}, list the keywords as literals.
@c JP
@code{syntax-rules}では、キーワードをリテラルリストに含めてください。
@c COMMON
@example
(syntax-rules (:key)
  [(_ :key z) (list :key z)])  ;etc.
@end example
@end itemize

@c EN
@subsubheading Displaying keywords
@c JP
@subsubheading キーワードの表示
@c COMMON

@c EN
@code{(display :key)} used to print @code{key} (no colon), while it now
prints @code{:key}.

You can use @code{(display (keyword->string :key))} which prints @code{key}
in both versions.
@c JP
@code{(display :key)}は以前は@code{key}(コロン無し)を表示しましたが、
現在は@code{:key}を表示します。

@code{key}を表示したい場合は@code{(display (keyword->string :key))}とすれば、
どのバージョンでも同じように動作します。
@c COMMON

@c EN
@subsubheading For R7RS code, quote them or import Gauche modules
@c JP
@subsubheading R7RSコードではクオートするかGaucheのモジュールをインポートする
@c COMMON

@c EN
Keywords (symbols beginning with @code{:}) are automatically bound to itself
in the @code{gauche.keyword} module.

Gauche code inherits the @code{gauche} module by default, which inherits
@code{keyword}, so you can see the binding of the keyword by default.

In R7RS code, however, you don't inherit @code{gauche},
so symbols beginning with @code{:} are just ordinary symbols by default.
Usually you do @code{(import (gauche base))} to use Gauche built-ins,
and that makes binding of @code{gauche.keyword} available in your
code, too (since @code{gauche.base} inherits @code{gauche.keyword}).
But keep this in mind just in case you want to handle keywords in
your R7RS code separate from Gauche procedures---you have to either say
@code{(import (gauche keyword))} to get just the self-bound keywords,
or quote them.
@c JP
キーワード(@code{:}で始まるシンボル)は@code{gauche.keyword}モジュール
の中で自分自身に束縛されます。

Gaucheコードはデフォルトで@code{gauche}モジュールを継承し、
それが@code{keyword}モジュールを継承しているので、
キーワードの束縛は自動的に見えるようになります。

しかしR7RSコードでは@code{gauche}モジュールは継承されないので、
@code{:}で始まるシンボルもデフォルトではただのシンボルです。
通常、Gaucheの組み込み機能を使うには@code{(import (gauche base))}としますが、
こうするとキーワードの自分自身への束縛もインポートされるようになっています
(@code{gauche.base}が@code{gauche.keyword}も継承しているからです)。
ただ、Gaucheの手続きとは別にキーワードをR7RSコード中で使いたい場合は
注意してください。自己束縛されているキーワードだけが欲しければ
@code{(import (gauche keyword))}とする必要がありますし、
そうしない場合はキーワードに見えるシンボルでもクオートする必要があります。
@c COMMON

@example
(import (scheme base))

:foo @result{} @r{ERROR: unbound variable: :foo}

(import (gauche base))

:foo @result{} :foo
@end example

@c EN
In the following example, the R7RS library @code{foo} imports only
@code{copy-port} from @code{(gauche base)}; in that case,
you have to import @code{(gauche keyword)} separately
in order to use @code{:size} keyword without quoting.
(Or add @code{:size} explicitly in the imported symbol
list of @code{(gauche base)}.)
@c JP
次の例では、R7RSライブラリ@code{foo}が@code{(gauche base)}から
@code{copy-port}のみをインポートしています。こういった場合、
@code{:size}キーワードをクオートなしで使うには、@code{(gauche keyword)}も
別にインポートしなければなりません。
(あるいは、@code{(gauche base)}からインポートするシンボルのリストに
@code{:size}も明示するか)。
@c COMMON

@example
(define-library (foo)
  (import (scheme base)
          (only (gauche base) copy-port)
          (gauche keyword))
  (export cat)

  (begin
    (define (cat)
      (copy-port (current-input-port)
                 (current-output-port)
                 :size 4096))))
@end example


@c ----------------------------------------------------------------------
@node Characters, Character sets, Symbols, Core library
@section Characters
@c NODE 文字

@deftp {Builtin Class} <char>
@clindex char
@end  deftp

@deftp {Reader Syntax} @code{#\@i{charname}}
@lxindex #\
[R7RS+]
@c EN
Denotes a literal character.

When the reader reads @code{#\}, it fetches a subsequent character.
If it is one of @code{()[]@{@}" \|;#}, this is a character literal of itself.
Otherwise, the reader reads subsequent characters until it sees
a non word-constituent character.  If only one character is read,
it is the character.  Otherwise, the reader matches the read characters
with predefined character names.  If it doesn't match any, an error
is signaled.

The following character names are recognized.
These character names are case insensitive.
@table @code
@item space
Whitespace (ASCII #x20)
@item newline, nl, lf
Newline (ASCII #x0a)
@item return, cr
Carriage return (ASCII #x0d)
@item tab, ht
Horizontal tab (ASCII #x09)
@item page
Form feed (ASCII #x0c)
@item alarm
Bell (ASCII #x07)
@item backspace
Backspace (ASCII #x08)
@item escape, esc
Escape (ASCII #x1b)
@item delete, del
Delete (ASCII #x7f)
@item null
NUL character (ASCII #x00)
@item x@var{N}
A character whose Unicode codepoint is the integer @var{N},
when @var{N} is a hexadecimal integer.
This is R7RS lexical syntax.
@item u@var{N}
A character whose Unicode codepoint is the integer @var{N},
where @var{N} is 4-digit or 8-digit hexadecimal number.
This is legacy Gauche lexical syntax.  Use @code{\xN} syntax for
the new code.
@end table
@c JP
リテラルの文字オブジェクトを表現します。

リーダーは@code{#\}に出会うと、まず次の文字を読み込みます。それが文字
@code{()[]@{@}" \|;#} のいずれかならば、その文字自身となります。
そうでなければ、単語を構成しない文字に出会うまで文字が続けて読み込まれます。
もし一文字しか読まれなければ、その文字自身となります。そうでなければ
その単語が文字の名前として解釈されます。
それが有効な文字の名前でなければエラーとなります。

以下の文字の名前が認識されます。これらの文字の名前は大文字小文字を区別しません。
@table @code
@item space
スペース (ASCII #x20)
@item newline, nl, lf
改行文字 (ASCII #x0a)
@item return, cr
復帰文字 (ASCII #x0d)
@item tab, ht
水平タブ (ASCII #x09)
@item page
フォームフィード、改ページ (ASCII #x0c)
@item alarm
ベル (ASCII #x07)
@item backspace
バックスペース (ASCII #x08)
@item escape, esc
エスケープ (ASCII #x1b)
@item delete, del
デリート (ASCII #x7f)
@item null
NUL文字 (ASCII #x00)
@item x@var{N}
@var{N} が16進表記の整数であるとき、Unicodeコードポイントが整数@var{N}
であるような文字。これはR7RSの字句構文です。
@item u@var{N}
@var{N}が4桁または8桁の16進数整数であるとき、UCSコード@var{N}であるような文字。
これはGaucheの古い構文です。新規のコードでは@code{\xN}を使ってください。
@end table
@c COMMON

@example
@c EN
#\newline @result{} #\newline ; @r{newline character}
#\x0a     @result{} #\newline ; @r{ditto}
#\x41     @result{} #\A       ; @r{ASCII letter 'A'}
#\x3042   @result{} ; @r{Hiragana letter A}
#\x2a6b2  @result{} ; @r{JISX0213 Kanji 2-94-86}
@c JP
#\newline @result{} #\newline ; @r{改行文字}
#\x0a     @result{} #\newline ; @r{改行文字}
#\x41     @result{} #\A       ; @r{ASCII文字 'A'}
#\x3042   @result{} #\あ      ; @r{平仮名「あ」}
#\x2a6b2  @result{} ; @r{JISX0213 2-94-86}
@c COMMON
@end example
@end deftp

@defun char? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a character, @code{#f} otherwise.
@c JP
@var{obj}が文字なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun char=? char1 char2 char3 @dots{}
@defunx char<? char1 char2 char3 @dots{}
@defunx char<=? char1 char2 char3 @dots{}
@defunx char>? char1 char2 char3 @dots{}
@defunx char>=? char1 char2 char3 @dots{}
[R7RS base]
@c EN
Compares characters.  Character comparison is done in internal
character encoding.
@c JP
文字を比較します。比較は内部の文字エンコーディングで行われます。
@c COMMON
@end defun

@defun char-ci=? char1 char2 char3 @dots{}
@defunx char-ci<? char1 char2 char3 @dots{}
@defunx char-ci<=? char1 char2 char3 @dots{}
@defunx char-ci>? char1 char2 char3 @dots{}
@defunx char-ci>=? char1 char2 char3 @dots{}
[R7RS char]
@c EN
Compares characters in case-insensitive way.
The comparison is done in the internal character code
of the foldcase of the each character; see @code{char-foldcase} below.

In R7RS, these procedures are in the @code{(scheme char)} library.
@c JP
文字を、大文字小文字を区別せずに比較します。
比較はそれぞれの文字のfoldcaseの内部文字エンコーディングに基づいて行われます。
foldcaseについては下の@code{char-foldcase}を参照してください。

R7RSではこれらの手続きは@code{(scheme char)}ライブラリにあります。
@c COMMON
@end defun

@defun char-alphabetic? char
@defunx char-numeric? char
@defunx char-whitespace? char
@defunx char-upper-case? char
@defunx char-lower-case? char
@defunx char-title-case? char
[R7RS char][SRFI-129]
@c EN
Returns true if a character @var{char} is an alphabetic character
(Unicode character category @code{Lu}, @code{Ll}, @code{Lt},
@code{Lm}, @code{Lo}, @code{Nl}),
a numeric character
(Unicode character category @code{Nd}),
a whitespace character,
(Unicode character category @code{Zs}, @code{Zp}, @code{Zl}),
an upper case character
(Unicode character category @code{Lu}),
or a lower case character
(Unicode character category @code{Ll}), respectively.

In R7RS, these procedures except @code{char-title-case?}
are in the @code{(scheme char)} library,
while @code{char-title-case?} is defined in SRFI-129.
@c JP
文字@var{char}がそれぞれアルファベット
(Unicode文字カテゴリ @code{Lu}、@code{Ll}、@code{Lt}、
@code{Lm}、@code{Lo}、@code{Nl})、
数字 (Unicode文字カテゴリ @code{Nd})、
空白文字 (Unicode文字カテゴリ @code{Zs}、@code{Zp}、@code{Zl})、
大文字 (Unicode文字カテゴリ @code{Lu})、
小文字 (Unicode文字カテゴリ @code{Ll})の時に真の値を返します。

R7RSでは@code{char-title-case?}以外の手続きは
@code{(scheme char)}ライブラリにあります。
@code{char-title-case?}はSRFI-129で定義されます。
@c COMMON
@end defun

@defun char-word-constituent? char
@c EN
Returns @code{#t} iff @var{char} is a character R7RS allows to be
in an identifier name without escaping: ASCII alphanumeric characters,
extended alphabetic characters (@code{! $ % & * + - . / : < = > ? @ ^ _ ~}),
any characters whose category is
Lu, Ll, Lt, Lm, Lo, Mn, Mc, Me, Nd, Nl, No, Pd, Pc, Po, Sc, Sm, Sk, So, or Co,
Zero width non-joiner (U+200C), and Zero width joiner (U+200D).
@c JP
@var{char}がR7RSで識別子にエスケープなしで使える文字ならば@code{#t}を、
そうでなければ@code{#f}を返します。該当する文字は、ASCIIのアルファベットと数字、
拡張アルファベット@code{! $ % & * + - . / : < = > ? @ ^ _ ~}、
文字カテゴリが
Lu, Ll, Lt, Lm, Lo, Mn, Mc, Me, Nd, Nl, No, Pd, Pc, Po, Sc, Sm, Sk, So, Coの
いずれかであるもの、および
Zero width non-joiner (U+200C)とZero width joiner (U+200D)です。
@c COMMON
@end defun


@defun char-general-category char
[R6RS]
@c EN
Returns one of the following symbols, representing the Unicode general category of @var{char}.
@c JP
文字@var{char}のUnicode general categoryを表す、以下のシンボルのいずれかを返します。
@c COMMON

@multitable {aaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{Cc} @tab Other, Control
@item @code{Cf} @tab Other, Format
@item @code{Cn} @tab Other, Not Assigned
@item @code{Co} @tab Other, Private Use
@item @code{Cs} @tab Other, Surrogate
@item @code{Ll} @tab Letter, Lowercase
@item @code{Lm} @tab Letter, Modifier
@item @code{Lo} @tab Letter, Other
@item @code{Lt} @tab Letter, Titlecase
@item @code{Lu} @tab Letter, Uppercase
@item @code{Mc} @tab Mark, Spacing Combining
@item @code{Me} @tab Mark, Enclosing
@item @code{Mn} @tab Mark, Nonspacing
@item @code{Nd} @tab Number, Decimal Digit
@item @code{Nl} @tab Number, Letter
@item @code{No} @tab Number, Other
@item @code{Pc} @tab Punctuation, Connector
@item @code{Pd} @tab Punctuation, Dash
@item @code{Pe} @tab Punctuation, Close
@item @code{Pf} @tab Punctuation, Final quote
@item @code{Pi} @tab Punctuation, Initial quote
@item @code{Po} @tab Punctuation, Other
@item @code{Ps} @tab Punctuation, Open
@item @code{Sc} @tab Symbol, Currency
@item @code{Sk} @tab Symbol, Modifier
@item @code{Sm} @tab Symbol, Math
@item @code{So} @tab Symbol, Other
@item @code{Zl} @tab Separator, Line
@item @code{Zp} @tab Separator, Paragraph
@item @code{Zs} @tab Separator, Space
@end multitable

@c EN
Module @code{gauche.unicode} provides proceduers to deal with
Unicode East Asian Width property.  @xref{East asian width property}.
@c JP
@code{gauche.unicode}では、Unicodenの東アジア文字幅プロパティを扱う
手続きも提供しています。@ref{East asian width property}参照。
@c COMMON
@end defun

@defun char->integer char
@defunx integer->char n
[R7RS base]
@c EN
@code{char->integer} returns an exact integer of the unicode
codepont of the character @var{char}.
@code{integer->char} returns a character whose unicode codepoint
is an exact integer @var{n}.  The following expression is always
true for valid character @var{char}:
@example
(eq? char (integer->char (char->integer char)))
@end example

The result is undefined if you pass @var{n} to @code{integer->char}
that doesn't have a corresponding character.
@c JP
@code{char->integer}は文字@var{char}のUnicodeコードポイント
整数値を返します。@code{integer->char}は数値@var{n}をUnicodeコードポイントとする
文字を返します。有効な文字@var{char}に対して以下の式は常に真となります。
@example
(eq? char (integer->char (char->integer char)))
@end example

対応する文字が無い数値を@code{integer->char}に渡した
場合の結果は不定です。
@c COMMON

@c EN
If you need Unicode encoded value (e.g. utf8 octets or utf16 words) corresponding
to a character/codepoint, you can use @code{gauche.unicode} module.
@xref{Unicode transfer encodings}.
@c JP
もし文字/コードポイントに対するUnicodeのエンコードされた値
(UTF8オクテット列やUTF16ワード列)が必要なら、
@code{gauche.unicode}モジュールの手続きが使えます。
@ref{Unicode transfer encodings}参照。
@c COMMON
@end defun

@defun char->ucs char
@defunx ucs->char n
@c DEPRECATED
@c EN
These are the same as @code{char->integer} and @code{integer->char},
respectively.

Gauche used to be built with an internal encoding other than
utf-8, in which integer character codes differ from Unicode
codepoints.  These procedures can be used to guarantee
you can use Unicode codepoints.

Now that Gauche always uses utf-8, these procedures are no longer needed.
@c JP
それぞれ@code{char->integer}および@code{integer->char}と同じです。

Gaucheはかつて、utf-8以外の内部エンコーディングでもビルドすることができ、
その場合文字に対応する整数の文字コードはUnicodeコードポイントとは限りませんでした。
これらの手続きは確実にUnicode-コードポイントを扱いたい場合に使われました。

現在ではGaucheは内部エンコーディングにutf-8のみを使うので、
これらの手続きはもう必要なくなりました。
@c COMMON
@end defun

@defun char-upcase char
@defunx char-downcase char
@defunx char-titlecase char
@defunx char-foldcase char
[R7RS char][SRFI-129]
@c EN
Returns the upper case, lower case, title case and folded case of
@var{char}, respectively.
The mapping is done according to Unicode-defined character-by-character
case mapping.

R7RS defines @code{char-upcase}, @code{char-downcase}, and
@code{char-foldcase} in the @code{(scheme char)} library,
while @code{char-titlecase} is defined in SRFI-129.
R6RS defines all of them.
@c JP
@var{char}の大文字、小文字、titlecase、foldcaseを
それぞれ返します。
変換はUnicodeで定義された文字対文字のマッピングに従います。

R7RSは@code{(scheme char)}ライブラリで、@code{char-upcase}、
@code{char-downcase}、@code{char-foldcase}を定義しています。
@code{char-titlecase}はSRFI-129で定義されます。
R6RSは全ての手続きを提供しています。
@c COMMON

@c EN
The character-by-character case mapping doesn't consider a character
that may map to more than one characters; a notable example is
eszett (latin small letter sharp S, U+00df), which is
is mapped to two capital S's in string context,
but @code{char-upcase #\ß} returns #\ß.  To get a full mapping,
use @code{string-upcase} etc. in @code{gauche.unicode} module
(@pxref{Full string case conversion}).
@c JP
文字対文字のマッピングでは、一文字が複数文字に展開されるようなケースマッピングは
扱いません。有名な例はeszett (latin small letter sharp S, U+00df)で、
文字列のコンテキストでは二つの大文字のSへとマップされますが、
@code{char-upcase #\ß} は単に #\ß を返します。
完全なマッピングが必要なら、@code{gauche.unicode}モジュールの
@code{string-upcase}等が利用できます
(@ref{Full string case conversion}参照)。
@c COMMON
@end defun

@defun digit->integer char :optional (radix 10) (extended-range? #f)
@c EN
If given character @var{char} is a valid digit character in radix
@var{radix} number, the corresponding integer is returned.  Otherwise
@code{#f} is returned.
@c JP
文字@var{char}が @var{radix}進数の数字を構成するのに有効な文字であれば、
対応する整数が、そうでなければ@code{#f}が返されます。
@c COMMON
@example
(digit->integer #\4) @result{} 4
(digit->integer #\e 16) @result{} 14
(digit->integer #\9 8) @result{} #f
@end example

@c EN
If the optional @var{extended-range?} argument is true,
this procedure recognizes not only ASCII digits, but also
all characters with @code{Nd} general category---such as
FULLWIDTH DIGIT ZERO to NINE (U+ff10 - U+ff19).
@c JP
省略可能引数@var{extended-range?}に真の値が与えられると、
この手続きはASCIIの数字だけでなく、@code{Nd}カテゴリに属する
すべての文字、例えば
FULLWIDTH DIGIT ZEROからNINE (U+ff10 - U+ff19) も認識します。
@c COMMON

@c EN
R7RS has @code{digit-value}, which is equivalent to
@code{(digit->integer char 10 #t)}.
@c JP
R7RSには@code{digit-value}という手続きが定義されていて、それは
@code{(digit->integer char 10 #t)}と等価です。
@c COMMON

@c EN
Note: CommonLisp has a similar function in rather confusing name,
@code{digit-char-p}.
@c JP
Common Lispには同様の手続きが@code{digit-char-p}というやや曖昧な名で定義されています。
@c COMMON
@end defun

@defun integer->digit integer :optional (radix 10) (basechar1 #\0) (basechar2 #\a)
@c EN
Reverse operation of @code{digit->integer}.  Returns a character that
represents the number @var{integer} in the radix @var{radix} system.
If @var{integer} is out of the valid range, @code{#f} is returned.
@c JP
@code{digit->integer}の逆です。整数@var{integer}を @var{radix}進数 ひと桁で
表現するのに使われる文字を返します。@var{integer}がひと桁で表現できない数値の場合は
@code{#f}が返されます。
@c COMMON
@example
(integer->digit 13 16) @result{} #\d
(integer->digit 10) @result{} #f
@end example

@c EN
The optional @var{basechar1} argument specifies the character
that stands for zero; by default, it's @code{#\0}.  You can give
alternative character, for example, U+0660 (ARABIC-INDIC DIGIT ZERO)
to convert an integer to a arabic-indic digit character.
@c JP
省略可能引数@var{basechar1}はゼロに相当する文字を指定します。
デフォルトは@code{#\0}です。ここに、例えばU+0660 (ARABIC-INDIC DIGIT ZERO)
を与えれば、整数をアラビア・インド数字に変換できます。
@c COMMON

@c EN
Another optional @var{basechar2} argument is used for integers over 10.
The default value is @code{#\a}.  You can pass @code{#\A} to get
upper-case hex digits, for example.
@c JP
もうひとつの省略可能引数@var{basechar2}は、10を越える整数に使う文字の起点を
指定します。デフォルトは@code{#\a}です。ここに@code{#\A}を渡せば、
16進数表記で小文字のかわりに大文字を使うようになります。
@c COMMON

@c EN
Note: CommonLisp's @code{digit-char}.
@c JP
Common Lispの@code{digit-char}に当たります。
@c COMMON
@end defun

@defun gauche-character-encoding
@c DEPRECATED
@c EN
Returns a symbol @code{utf-8}.
This is kept for the backward compatibility with the code
written for pre-1.0 Gauche which may be compiled with internal
encodings other than utf-8.
@c JP
シンボル@code{utf-8}を返します。
これは、1.0以前のGaucheのために書かれたコードの互換性のために残されています。
かつてはutf-8以外の内部エンコーディングでGaucheをコンパイルすることが可能でした。
@c COMMON
@end defun

@defun supported-character-encodings
@c EN
Returns a list of string names of character encoding schemes
that are supported in the native multibyte encoding scheme.
@c JP
ネイティブなマルチバイトエンコーディングスキームでサポートされている
文字エンコーディングスキームの名前を表す文字列のリストを返します。
@c COMMON
@end defun



@c ----------------------------------------------------------------------
@node Character sets, Strings, Characters, Core library
@section Character Sets
@c NODE 文字集合

@deftp {Builtin Class} <char-set>
@clindex char-set
@c EN
Character set class.  Character set object represents a set of characters.
Gauche provides built-in support of character set creation and
a predicate that tests whether a character is in the set or not.

The class implements the collection protocol (@pxref{Collection framework}),
so that the standard collection methods provided in the
@code{gauche.collection} module can be used.

An instance of @code{<char-set>} is applicable to a character,
and works as a membership predicate; see @code{char-set-contains?} below.

Further operations, such as set algebra, is defined in SRFI-14
module (@pxref{R7RS character sets}).
@c JP
文字の集合を取り扱う、文字集合(キャラクタセット)のクラスです。
Gaucheは文字集合オブジェクトのサポートと、
ある文字がその集合に属するかどうかを調べる手続きを言語組み込みで持っています。

コレクションプロトコル (@ref{Collection framework}参照) を実装しているので、
@code{gauche.collection}で提供される標準のコレクションメソッドが使えます。

@code{<char-set>}のインスタンスは文字に関数のように適用することができ、
その文字が文字集合に属するかどうかを判定する述語として機能します。
下記の@code{char-set-contains?}を参照してください。

文字集合に関する他の操作、例えば集合演算などは、SRFI-14モジュール
(@ref{R7RS character sets}参照) で提供されています。
@c COMMON
@end deftp

@menu
* Character set literals::
* Predefined character sets::
* Character set operations::
@end menu

@node Character set literals, Predefined character sets, Character sets, Character sets
@subsection Character set literals
@c NODE 文字集合リテラル

@deftp {Reader Syntax} @code{#[@i{char-set-spec}]}
@lxindex #[
@c EN
You can write a literal character set in this syntax.
@i{char-set-spec} is a sequence of characters to be included
in the set.  You can include the following special sequences:
@table @code
@item @var{x}-@var{y}
Characters between @var{x} and @var{y}, inclusive.
@var{x} must be smaller than @var{y} in the Unicode codepoints.
@item ^
If @i{char-set-spec} begins with caret, the actual character set
is a complement of what the rest of @i{char-set-spec} indicates.
@item \x@var{N};
A character whose Unicode codepoint is a hexadecimal number @var{N}.
@item \u@var{XXXX}
@itemx \U@var{XXXXXXXX}
This is a legacy Gauche syntax, for a unicode character
whose Unicode codepoint is represented by 4-digit and 8-digit hexadecimal
numbers, respectively.
@item \s
Whitespace characters
(space, newline, tab, form feed, vertical tab, carriage return).
Members of @code{char-set:ascii-whitespace}.
@item \S
Complement of whitespace characters.
@item \d
Decimal digit characters.  Members of
@code{char-set:ascii-digits}.
@item \D
Complement of decimal digit characters.
@item \w
Word constituent characters (@code{#[A-Za-z0-9_]}).
Members of @code{char-set:ascii-word}.
@item \W
Complement of word constituent characters.
@item \\
A backslash character.
@item \-
A minus character.
@item \^
A caret character.
@item [:alnum:] @dots{}
Character set a la POSIX.  See the table below for the complete list of
recognized character set names.  The set name must be in all lower cases.
This notation only includes characters in ASCII range.
@item [:^alnum:] @dots{}
Complement set of @code{[:alnum:]} etc.
@item [:ALNUM:] @dots{}
Gauche's extension of character set a la POSIX; the name must be
all in upper cases, and includes full Unicode range.  See the table below
for the recognized names.
@item [:^ALNUM:] @dots{}
Complement set of @code{[:ALNUM:]} etc.
@end table
@c JP
この構文で、リテラル文字集合を記述することができます。
@i{char-set-spec}には集合に含める文字を列挙します。
次の特殊なシーケンスを含めることができます。
@table @code
@item @var{x}-@var{y}
文字@var{x}と文字@code{y}の間の文字全て。@var{x}と@var{y}も含みます。
@var{x}は@var{y}よりも内部文字コードで比較して小さくなければなりません。
@item ^
カレットが@i{char-set-spec}の最初に来た場合、以降に示される文字集合の
補集合がこの文字集合となります。
@item \x@var{N};
Unicodeコードポイントが@var{N}(16進数表記)の文字。
@item \s
空白文字(space, newline, tab, form feed, vertical tab, carriage return).
文字集合@code{char-set:ascii-whitespace}の要素。
@item \S
空白でない文字。(@code{\s}の補集合)
@item \d
10進数の数字。
文字集合@code{char-set:ascii-digit}の要素。
@item \D
@code{\d}の補集合
@item \w
単語を構成する文字の集合(@code{#[A-Za-z0-9_]})。
文字集合@code{char-set:ascii-word}の要素。
@item \W
@code{\W}の補集合
@item \\
バックスラッシュ文字
@item \-
マイナス文字
@item \^
カレット文字
@item [:alnum:] @dots{}
POSIX風文字集合表記。サポートされる名前については下の表を参照してください。
名前は全て小文字でなければなりません。この表記の文字集合はASCII範囲のみを含みます。
@item [:^alnum:] @dots{}
@code{[:alnum:]}等の補集合です。
@item [:ALNUM:] @dots{}
POSIX風文字集合表記のGauche拡張。名前は全て大文字でなければなりません。
この表記の文字集合はUnicode全範囲を対象とします。
サポートされる名前については下の表を参照してください。
@item [:^ALNUM:] @dots{}
@code{[:ALNUM:]}等の補集合です。
@end table
@c COMMON

@c EN
Here's the list of POSIX-style character class names:

@multitable @columnfractions .15 .85
@item @code{:alpha:} @tab ASCII alphabets.  @code{char-set:ascii-letter}, @code{#[A-Za-z]}
@item @code{:alnum:} @tab ASCII alphabets and digits.  @code{char-set:ascii-letter+digits}, @code{#[0-9A-Za-z]}.
@item @code{:blank:} @tab ASCII blanks.  @code{char-set:ascii-blank}, tab and space.
@item @code{:cntrl:} @tab ASCII control characters.  @code{char-set:ascii-control}, U+0000 to U+001f and U+007f.
@item @code{:digit:} @tab ASCII digits.  @code{char-set:ascii-digit}, @code{#[0-9]}.
@item @code{:graph:} @tab ASCII graphic characters.  @code{char-set:ascii-graphic}.
@item @code{:lower:} @tab ASCII lower-case alphabets.  @code{char-set:ascii-lower-case}, @code{#[a-z]}.
@item @code{:print:} @tab ASCII printing characters.  @code{char-set:ascii-printing}.
@item @code{:punct:} @tab POSIX punctuation characters.  @code{char-set:ascii-posix-punctuation} (see the note below).
@item @code{:upunct:} @tab ASCII punctuation characters.  @code{char-set:ascii-punctuation}. (This is not POSIX).
@item @code{:space:} @tab ASCII whitespaces. @code{char-set:ascii-whitespace}.
@item @code{:upper:} @tab ASCII upper-case characters.  @code{char-set:ascii-upper-case}, @code{#[A-Z]}.
@item @code{:word:} @tab ASCII word characters (not POSIX).  @code{char-set:ascii-word}, @code{#[0-9A-Za-z_]}.
@item @code{:xdigit:} @tab Hexadecimal digits.  @code{char-set:hex-digit}, @code{#[0-9a-fA-F]}.
@item @code{:ascii:} @tab ASCII characters (not POSIX).  @code{char-set:ascii}.
@item @code{:ALPHA:} @tab Unicode letters. @code{char-set:letter}.
@item @code{:ALNUM:} @tab Unicode letters and digits.  @code{char-set:letter+digits}.
@item @code{:BLANK:} @tab Unicode blanks (tab and category @code{Zs}).  @code{char-set:blank}.
@item @code{:CNTRL:} @tab Unicode control characters (category @code{Cc}).  @code{char-set:iso-control}.
@item @code{:DIGIT:} @tab Unicode digits (category @code{Nd}).  @code{char-set:digit}.
@item @code{:GRAPH:} @tab Unicode graphic characters (letter, digits, punctuation, symbol, and category @code{Nl} and @code{No}).  @code{char-set:graphic}.
@item @code{:LOWER:} @tab Unicode lower-case letters (category @code{Ll}).  @code{char-set:lower-case}, @code{#[a-z]}.
@item @code{:PRINT:} @tab Unicode printing characters (graphic and whitespace).  @code{char-set:printing}.
@item @code{:PUNCT:} @tab Extended POSIX punctuation characters (category @code{P*}).  @code{char-set:posix-punctuation} (see the note below).
@item @code{:UPUNCT:} @tab Unicode punctuation characters (category @code{P*}).  @code{char-set:punctuation}.
@item @code{:SPACE:} @tab Unicode whitespaces (tab, LF, vertical tab, FF, CR, and category @code{Z*}). @code{char-set:whitespace}.
@item @code{:TITLE:} @tab Unicode titlecase letters (category @code{Lt}).  @code{char-set:title-case}.
@item @code{:UPPER:} @tab Unicode upper-case letters (category @code{Lu}).  @code{char-set:upper-case}, @code{#[A-Z]}.
@item @code{:WORD:} @tab Unicode word characters.  @code{char-set:word}.
@item @code{:XDIGIT:} @tab Hexadecimal digits (same as @code{:xdigit:}).
@end multitable
@c JP
POSIX風文字集合表記で認識される名前は次のとおりです。

@multitable @columnfractions .15 .85
@item @code{:alpha:} @tab ASCIIアルファベット。@code{char-set:ascii-letter}, @code{#[A-Za-z]}
@item @code{:alnum:} @tab ASCIIアルファベットと数字。@code{char-set:ascii-letter+digits}, @code{#[0-9A-Za-z]}.
@item @code{:blank:} @tab ASCIIブランク文字。@code{char-set:ascii-blank}, tab and space.
@item @code{:cntrl:} @tab ASCII制御文字。@code{char-set:ascii-control}, U+0000 to U+001f and U+007f.
@item @code{:digit:} @tab ASCII数字。@code{char-set:ascii-digit}, @code{#[0-9]}.
@item @code{:graph:} @tab ASCIIグラフィック文字。@code{char-set:ascii-graphic}.
@item @code{:lower:} @tab ASCII小文字アルファベット。@code{char-set:ascii-lower-case}, @code{#[a-z]}.
@item @code{:print:} @tab ASCII印字可能文字。@code{char-set:ascii-printing}.
@item @code{:punct:} @tab POSIX句読点。@code{char-set:ascii-posix-punctuation}. (下の註を参照)
@item @code{:upunct:} @tab ASCII句読点。@code{char-set:ascii-punctuation}. (これはPOSIXにはありません)
@item @code{:space:} @tab ASCII空白文字。@code{char-set:ascii-whitespace}.
@item @code{:upper:} @tab ASCII大文字アルファベット。@code{char-set:ascii-upper-case}, @code{#[A-Z]}.
@item @code{:word:} @tab ASCII単語構成文字(POSIXではありません)。 @code{char-set:ascii-word}, @code{#[0-9A-Za-z_]}.
@item @code{:xdigit:} @tab 16進数の数字。@code{char-set:hex-digit}, @code{#[0-9a-fA-F]}.
@item @code{:ascii:} @tab ASCII文字 (POSIXではありません).  @code{char-set:ascii}.
@item @code{:ALPHA:} @tab Unicode通常文字。@code{char-set:letter}.
@item @code{:ALNUM:} @tab Unicode通常文字と数字。@code{char-set:letter+digits}.
@item @code{:BLANK:} @tab Unicodeブランク文字。@code{char-set:blank}.
@item @code{:CNTRL:} @tab Unicode制御文字。@code{char-set:iso-control}.
@item @code{:DIGIT:} @tab Unicode数字。@code{char-set:digit}.
@item @code{:GRAPH:} @tab Unicodeグラフィック文字。@code{char-set:graphic}.
@item @code{:LOWER:} @tab Unicode小文字。@code{char-set:lower-case}, @code{#[a-z]}.
@item @code{:PRINT:} @tab Unicode印字可能文字。@code{char-set:printing}.
@item @code{:PUNCT:} @tab 拡張POSIX句読点。@code{char-set:posix-punctuation}. (下の註を参照)
@item @code{:UPUNCT:} @tab Unicode句読点。@code{char-set:punctuation}.
@item @code{:SPACE:} @tab Unicode空白文字。@code{char-set:whitespace}.
@item @code{:UPPER:} @tab Unicode大文字。@code{char-set:upper-case}, @code{#[A-Z]}.
@item @code{:WORD:} @tab Unicode単語構成文字。@code{char-set:word}.
@item @code{:XDIGIT:} @tab 16進数の数字。(@code{:xdigit:}と同じ).
@end multitable
@c COMMON

@c EN
Here are some examples:

@example
#[aeiou]       ; @r{a character set consists of vowels}
#[a-zA-Z]      ; @r{alphabet}
#[[:alpha:]]   ; @r{alphabet (using POSIX notation)}
#[\\\-]        ; @r{backslash and minus}
#[]            ; @r{empty charset}
#[\x0d;\x0a;\x3000;] ; @r{carriage return, newline, and ideographic space}
@end example
@c JP
いくつか例を示します。

@example
#[aeiou]     ; @r{母音文字'a', 'e', 'i', 'o', 'u'の集合}
#[a-zA-Z]    ; @r{アルファベット}
#[[:alpha:]] ; @r{アルファベット (POSIX表記)}
#[\\\-]      ; @r{バックスラッシュとマイナス文字}
#[]          ; @r{空の文字集合}
#[ぁ-ん]     ; @r{平仮名の集合}
#[\x0d;\x0a;\x3000;]  ; @r{リターン, 改行, 全角空白}
@end example
@c COMMON

@c EN
Literal character sets are immutable, as other literal data.  An error
is signalled when you attempt to modify an immutable character set.
@c JP
リテラル文字集合は他のリテラルデータ同様、変更不可です。
変更しようとした場合はエラーが通知されます。
@c COMMON

@c EN
@b{Note for the compatibility 1}:
POSIX's definition of @code{[:punct:]} covers Unicode's punctuations
and symbols in ASCII range.  Up to 0.9.15, we use the Unicode punctuation
attribute for @code{[:punct:]}.  Since 0.9.16, we fixed it to cover POSIX
range, for the compatibility of sharing POSIX notation with other systems.
You can use @code{[:upunct:]} to specify Unicode punctuations.

For the backward compatibility, if the environment variable
@code{GAUCHE_CHARSET_UNICODE_PUNCTUATION} is defined, @code{[:punct:]}
and @code{[:PUNCT:]} mean Unicode punctuation
(@code{char-set:ascii-punctuation} and @code{char-set:punctuation}).
@c JP
@b{互換性への注 1}:
POSIXで定義される@code{[:punct:]}は、ASCII範囲でUnicodeのpunctuation
とsymbolの両方を含みます。0.9.15まではUnicodeのpunctuation属性を@code{[:punct:]}
に使っていましたが、他のシステムとの互換性のため、0.9.16からは
@code{[:punct:]}をPOSIXの定義に合わせました。
かわりに、@code{[:upunct:]}でUnicode句読点を指示することができます。

以前のバージョンとの互換性が必要な場合、
環境変数@code{GAUCHE_CHARSET_UNICODE_PUNCTUATION}を定義しておけば、
@code{[:punct:]}と@code{[:PUNCT:]}はUnicodeの句読点に限定されます
(@code{char-set:ascii-punctuation}および@code{char-set:punctuation})。
@c COMMON

@c EN
@b{Note for the compatibility 2}:
We used to recognize a syntax @code{\xNN} (two-digit hexadecimal number,
without semicolon terminator) as a character; for example,
@code{#[\x0d\x0a]} as a return and a newline.  We still support it
when we don't see the terminating semicolon, for the compatibility.
There are ambiguous cases: @code{#[\x0a;]} means only a newline
in the current syntax, but a newline and a semicolon in legacy syntax.

Setting the reader mode to @code{legacy} restores the old behavior.
Setting the reader mode to @code{warn-legacy} makes it work like the default
behavior, but prints warning when it finds legacy syntax.
@xref{Reader lexical mode}, for the details.

To write code that can work both in new and old syntax, use @code{\u} escape.
@c JP
@b{互換性への注 2}:
以前は、@code{\xNN} (2桁固定の16進数、終端のセミコロン無し) を文字と認識していました。
例えば@code{#[\x0d\x0a]}はリターン文字と改行文字集合を意味していました。
互換性のため、終端のセミコロンが見当たらない場合は古い構文もサポートされます。
しかし曖昧な場合もあります。@code{#[\x0a;]}は新しい構文では
改行文字のみのセットですが、古い構文では改行文字とセミコロンになります。

リーダのモードを@code{legacy}にセットすると、常に古い構文で認識されます。
リーダのモードを@code{warn-legacy}にセットすると、
デフォルトと同じように振る舞いますが、古い構文を見つけた場合は警告が出力されます。
詳しくは@ref{Reader lexical mode}を参照してください。

古い構文と新しい構文の両方で動作するコードが必要な場合は、@code{\u}エスケープを
使ってください。
@c COMMON
@end deftp

@node Predefined character sets, Character set operations, Character set literals, Character sets
@subsection Predefined character sets
@c NODE 定義済み文字集合

@c EN
We provide a bunch of predefined character sets, including the ones
defined in R7RS charset library (@pxref{R7RS character sets}).
Those character sets are immutable.
@c JP
定義済みの文字集合がいくつか提供されています。
R7RS文字集合ライブラリで定義されているものも含まれます(@ref{R7RS character sets}参照)。
これらの文字集合は変更不可です。
@c COMMON

@defvar char-set:letter
[R7RS charset]
@c EN
Letters (Unicode general category @code{Lu}, @code{Ll}, @code{Lt},
@code{Lm} and @code{Lo}).
@c JP
文字 (Unicodeカテゴリ@code{Lu}、@code{Ll}、@code{Lt}、@code{Lm}、@code{Lo})。
@c COMMON
@end defvar


@defvar char-set:lower-case
@defvarx char-set:upper-case
@defvarx char-set:title-case
[R7RS charset]
@c EN
Lower case, upper case and title case letters
(Unicode general category @code{Ll}, @code{Lu} and @code{Lt}, respectively).
@c JP
小文字、大文字、タイトルケース文字
(それぞれ、Unicodeカテゴリ@code{Ll}、@code{Lu}、@code{Lt})。
@c COMMON
@end defvar

@defvar char-set:digit
[R7RS charset]
@c EN
Digit characters (Unicode general category @code{Nd}).  Note that this
contains many more characters than ASCII @code{0} to @code{9}.  If you
need @code{#[0-9]}, use @code{char-set:ascii-digit}.
@c JP
数字 (Unicodeカテゴリ@code{Nd})。
これには非ASCIIの数字もたくさん含まれています。
ASCIIの数字(@code{#[0-9]})だけが欲しい時は@code{char-set:ascii-digit}を
使ってください。
@c COMMON
@end defvar

@defvar char-set:hex-digit
[R7RS charset]
@c EN
Digit characters used for hexadecimal, i.e. @code{#[0-9A-Fa-f]}.  This does
not contain other Unicode digit characters, for it isn't practical
to mix non-ascii digit characters with hexadecimal notation.
@c JP
16進数表記に使われる文字、つまり@code{#[0-9A-Fa-f]}。
これにはASCII外の文字は含まれません。
@c COMMON
@end defvar

@defvar char-set:letter+digit
[R7RS charset]
@c EN
Union of @code{char-set:letter} and @code{char-set:digit}.
@c JP
@code{char-set:letter}と@code{char-set:digit}の和集合です。
@c COMMON
@end defvar

@defvar char-set:graphic
[R7RS charset]
@c EN
Characters that has some glyph.  Union of letters, numbers, punctuations
and symbols.
@c JP
何らかのグリフを持っている文字。通常文字、数字、句読点、シンボルの和集合です。
@c COMMON
@end defvar

@defvar char-set:printing
[R7RS charset]
@c EN
Union of @code{char-set:graphic} and @code{char-set:whitespace}.
@c JP
@code{char-set:graphic}と@code{char-set:whitespace}の和集合です。
@c COMMON
@end defvar

@defvar char-set:whitespace
@defvarx char-set:blank
[R7RS charset]
@c EN
Whitespace and blank characters; @code{char-set:whitespace}
includes @code{#\tab}, @code{#\newline}, @code{#\u000B} (vertical tab),
@code{#\page}, @code{#\return}, and all characters in general category
@code{Zs}, @code{Zl}, @code{Zp}, while @code{char-set:blank}
includes @code{#\tab} and all characters in general category @code{Zs}.
Note that @code{char-set:whitespace} is the same set of characters
that Scheme reader treats as whitespace characters.
@c JP
空白文字およびブランク文字です。
空白文字@code{char-set:whitespace}は、
@code{#\tab}、@code{#\newline}、@code{#\u000B} (vertical tab)、
@code{#\page}、@code{#\return}、および
一般カテゴリ@code{Zs}、@code{Zl}、@code{Zp}の文字です。
一方、ブランク文字@code{char-set:blank}は、
@code{#\tab}と一般カテゴリ@code{Zs}の文字です。
@code{char-set:whitespace}は、Schemeのリーダが空白扱いにする文字の集合と一致します。
@c COMMON
@end defvar

@defvar char-set:iso-control
[R7RS charset]
@c EN
Control characters (Unicode general category @code{Cc}).
@c JP
制御文字 (Unicode一般カテゴリ@code{Cc})。
@c COMMON
@end defvar


@defvar char-set:punctuation
[R7RS charset]
@c EN
Punctuation characters (Unicode general category
@code{Pc}, @code{Pd}, @code{Ps}, @code{Pe}, @code{Pi}, @code{Pf}
and @code{Po}).
Note that this is differenct from POSIX's @code{[:punct:]} character set.
See @code{char-set:posix-punctuation} below.
@c JP
句読点 (Unicode一般カテゴリ
@code{Pc}, @code{Pd}, @code{Ps}, @code{Pe}, @code{Pi}, @code{Pf}, @code{Po})。
これはPOSIXの@code{[:punct:]}文字集合とは異なることに注意してください。
下の @code{char-set:posix-punctuation}参照。
@c COMMON
@end defvar

@defvar char-set:symbol
[R7RS charset]
@c EN
Symbol characters (Unicode general category @code{Sm}, @code{Sc},
@code{Sk} and @code{So}).
@c JP
シンボル文字 (Unicode一般カテゴリ
@code{Sm}, @code{Sc}, @code{Sk}, @code{So})。
@c COMMON
@end defvar

@defvar char-set:ascii
[R7RS charset]
@c EN
Contains all ASCII characters (U+0000 to U+007f).
@c JP
すべてのASCII文字 (U+0000 to U+007f)。
@c COMMON
@end defvar

@defvar char-set:empty
[R7RS charset]
@c EN
An empty character set.
@c JP
空の文字集合。
@c COMMON
@end defvar

@defvar char-set:full
[R7RS charset]
@c EN
A character set that includes all characters.
@c JP
すべての文字を含む文字集合。
@c COMMON
@end defvar

@defvar char-set:word
@c EN
A word constituent characters.  In the current version,
it is equivalent to @code{char-set:ascii-word} (@code{#[0-9A-Za-z_]})
but in future versions we may extend this to other Unicode characters.
If you intend to mean ASCII-only words, use @code{char-set:ascii-word}.
@c JP
単語を構成する文字。今のところ、これは@code{char-set:ascii-word}、
つまり@code{#[0-9A-Za-z_]}と同じです。
ただ、将来はUnicodeの全域に意味を拡張するかもしれません。
ASCIIの範囲内だけを扱いたい場合は@code{char-set:ascii-word}を使ってください。
@c COMMON
@end defvar


@defvar char-set:ascii-letter
@defvarx char-set:ascii-lower-case
@defvarx char-set:ascii-upper-case
@defvarx char-set:ascii-digit
@defvarx char-set:ascii-letter+digit
@defvarx char-set:ascii-graphic
@defvarx char-set:ascii-printing
@defvarx char-set:ascii-whitespace
@defvarx char-set:ascii-blank
@defvarx char-set:ascii-control
@defvarx char-set:ascii-punctuation
@defvarx char-set:ascii-symbol
@defvarx char-set:ascii-word
@c EN
These are intersection of @code{char-set:ascii} and
the corresponding char set without @code{ascii-}.
(@code{char-set:ascii-control} corresponds to @code{char-set:iso-control}).
@c JP
これらはそれぞれ、@code{ascii-}を除いた名前の文字集合と@code{char-set:ascii}と
の交わりです。
@c COMMON

@c EN
The @code{\d}, @code{\s} and @code{\w} notation in the char-set literal
and regexp literal corresponds to @code{char-set:ascii-digit},
@code{char-set:ascii-whitespace}, and @code{char-set:ascii-word},
respectively (not the Unicode set).
@c JP
文字集合リテラルおよび正規表現リテラルにおける
@code{\d}、@code{\s}、@code{\w}はそれぞれ
@code{char-set:ascii-digit}、
@code{char-set:ascii-whitespace}、@code{char-set:ascii-word}に
対応します (Unicode版ではなく)。
@c COMMON

@c EN
The POSIX character class notation, such as @code{[:alpha:]} in
char-set literal and regexp literal, refers to these ASCII-only
charsets.
@c JP
また、@code{[:alpha:]}などのPOSIX文字クラス表記もこちらのASCII版の方に対応します。
@c COMMON

@c EN
Note: We don't have @code{char-set:ascii-title-case} and
@code{char-set:ascii-hex-digit}.  There's no titlecase letter
in ASCII range.  And @code{char-set:hex-digit} is limited to ASCII
by definition.
@c JP
なお、@code{char-set:ascii-title-case}と@code{char-set:ascii-hex-digit}は
ありません。ASCIIの範囲内にtitlecaseにあたる文字はなく、
また@code{char-set:hex-digit}はそれ自体ASCII範囲に限定されています。
@c COMMON
@end defvar

@defvar char-set:posix-punctuation
@defvarx char-set:ascii-posix-punctuation
@c EN
@code{char-set:ascii-posix-punctuation} is a union of
@code{char-set:ascii-punctuation} and @code{char-set:ascii-symbol}.
POSIX character set predates Unicode, and POSIX's definition of punctuation
characters (used for @code{[:punct:]} notation) is splitted to
punctuations and symbols in Unicode.
To support POSIX's @code{[:punct:]}, we have this predefined character set.

POSIX leaves what characters beyond ASCII range to be in @code{[:punct:]}.
We make @code{[:PUNCT:]}, which is @code{char-set:posix-punctuation},
include all Unicode punctuations plus
@code{char-set:ascii-symbol}. It is compatible to Perl.
(That is, non-ascii symbols are not included.)
@c JP
@code{char-set:ascii-posix-punctuation}は
@code{char-set:ascii-punctuation}と@code{char-set:ascii-symbol}の和集合です。
POSIX文字集合はUnicodeより前に制定されました。
UnicodeはPOSIXの@code{[:punct:]}集合を句読点(punctuation)とシンボル(symbol)に
分割しました。
POSIXの@code{[:punct:]}をサポートするために、この文字集合が定義されました。

POSIXはASCII範囲意外について@code{[:punct:]}が何を含むかを実装依存にしています。
GaucheではUnicode範囲を含む@code{[:PUNCT:]}については、
Unicodeの句読点とASCIIのシンボルの和集合としました
(つまり、ASCII以外のシンボルは含まれません)。これはPerlと互換です。
@c COMMON
@end defvar

@defvar char-set:Lu
@defvarx char-set:Ll
@defvarx char-set:Lt
@defvarx char-set:Lm
@defvarx char-set:Lo
@defvarx char-set:Mn
@defvarx char-set:Mc
@defvarx char-set:Me
@defvarx char-set:Nd
@defvarx char-set:Nl
@defvarx char-set:No
@defvarx char-set:Pc
@defvarx char-set:Pd
@defvarx char-set:Ps
@defvarx char-set:Pe
@defvarx char-set:Pi
@defvarx char-set:Pf
@defvarx char-set:Po
@defvarx char-set:Sm
@defvarx char-set:Sc
@defvarx char-set:Sk
@defvarx char-set:So
@defvarx char-set:Zs
@defvarx char-set:Zl
@defvarx char-set:Zp
@defvarx char-set:Cc
@defvarx char-set:Cf
@defvarx char-set:Cs
@defvarx char-set:Co
@defvarx char-set:Cn
@c EN
Each character set contains the corresponding Unicode characters with
the given general category; e.g. @code{char-set:Lu} contains all characters
of the general category @code{Lu}.
@c JP
それぞれ、対応するUniocdeの一般カテゴリに属する文字の集合です。
例えば@code{char-set:Lu}は一般カテゴリ@code{Lu}の文字の集合です。
@c COMMON
@end defvar

@defvar char-set:L
@defvarx char-set:LC
@defvarx char-set:M
@defvarx char-set:N
@defvarx char-set:P
@defvarx char-set:S
@defvarx char-set:Z
@defvarx char-set:C
@c EN
Each character set contains the Unicode characters with the general
category starting with the letter; e.g. @code{char-set:L} is union
of @code{char-set:Lu}, @code{char-set:Ll}, @code{char-set:Lt},
@code{char-set:Lm} and @code{char-set:Lo}.

@code{char-set:LC} is for cased-letters, the union of
@code{char-set:Lt}, @code{char-set:Ll}, @code{char-set:Lu}.
@c JP
各文字集合は、その文字で始まるUnicodeの一般カテゴリのすべての文字の集合です。
例えば@code{char-set:L}は、@code{char-set:Lu}、
@code{char-set:Ll}、@code{char-set:Lt}、
@code{char-set:Lm}、@code{char-set:Lo}の和集合です。

@code{char-set:LC}は大文字小文字の区別のある文字の集合、つまり
@code{char-set:Lt}、@code{char-set:Ll}、@code{char-set:Lu}の和集合です。
@c COMMON
@end defvar

@node Character set operations,  , Predefined character sets, Character sets
@subsection Character set operations
@c NODE 文字集合の操作

@c EN
See also @ref{R7RS character sets} for the comprehensive character set
operations.
@c JP
包括的な文字集合操作については、@ref{R7RS character sets}も参照してください。
@c COMMON


@defun char-set? obj
[R7RS charset]
@c EN
Returns true if and only if @var{obj} is a character set object.
@c JP
@var{obj}が文字集合であれば真の値を返します。
@c COMMON
@end defun

@defun char-set-immutable? char-set
@c EN
Returns @code{#t} if @var{char-set} is an immutable char-set,
@code{#f} if it's a mutable char-set.
@c JP
@var{char-set}が変更不可の文字集合であれば@code{#t}を、変更可能な文字集合であれば
@code{#f}を返します。
@c COMMON
@end defun

@defun char-set-contains? char-set char
[R7RS charset]
@c EN
Returns true if and only if a character set object
@var{char-set} contains a character @var{char}.
@c JP
文字集合@var{char-set}が文字@var{char}を含んでいれば真の値を返します。
@c COMMON
@example
(char-set-contains? #[a-z] #\y) @result{} #t
(char-set-contains? #[a-z] #\3) @result{} #f

(char-set-contains? #[^ABC] #\A) @result{} #f
(char-set-contains? #[^ABC] #\D) @result{} #t

@c JP
(char-set-contains? #[あ-お] #\う) @result{} #t
(char-set-contains? #[あ-お] #\ぷ) @result{} #f
@c COMMON
@end example
@end defun

@deffn {Generic application} @var{char-set} @var{char}
@c EN
A char-set object can be applied to a character, and it
works just like @code{(char-set-contains? char-set char)}.
@c JP
文字集合オブジェクトは文字に適用されると、
@code{(char-set-contains? char-set char)} のように振る舞います。
@c COMMON

@example
(#[a-z] #\a) @result{} #t
(#[a-z] #\A) @result{} #f

(use gauche.collection)
(filter #[a-z] "CharSet") @result{} (#\h #\a #\r #\e #\t)
@end example
@end deffn

@defun char-set char @dots{}
[R7RS charset]
@c EN
Creates a character set that contains @var{char} @dots{}.
@c JP
文字@var{char} @dots{} からなる文字集合を作成して返します。
@c COMMON
@example
(char-set #\a #\b #\c)   @result{} #[a-c]
@c JP
(char-set #\あ #\い #\う) @result{} #[あいう]
@c COMMON
@end example
@end defun

@defun char-set-size char-set
[R7RS charset]
@c EN
Returns a number of characters in the given charset.
@c JP
文字集合に含まれる文字数を返します。
@c COMMON

@example
gosh> (char-set-size #[])
0
gosh> (char-set-size #[[:alnum:]])
62
@end example
@end defun

@defun char-set-copy char-set
[R7RS charset]
@c EN
Copies a character set @var{char-set}.
@c JP
@var{char-set}のコピーを作って返します。
@c COMMON
@end defun

@defun char-set-complement char-set
@defunx char-set-complement! char-set
[R7RS charset]
@c EN
Returns a complement set of @var{char-set}.  The former always
returns a new set, while the latter may reuse the given charset.
@c JP
@var{char-set}の補集合を返します。上の手続きは常に新たな集合を作って返しますが、
下の手続きは引数を変更して返す可能性があります。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Strings, Regular expressions, Character sets, Core library
@section Strings
@c NODE 文字列

@deftp {Builtin Class} <string>
@clindex string
@c EN
A string class.
@c JP
文字列のクラスです。
@c COMMON
@end deftp

@c EN
It should be emphasized that Gauche's @emph{internal} string object,
@emph{string body}, is immutable.
To comply R7RS in which strings are mutable, a Scheme-level
string object is an indirect pointer to a string body.
Mutating a string means that Gauche creates a new immutable
string body that reflects the changes, then swap the pointer
in the Scheme-level string object.

This may affect some assumptions on the cost of string operations.

@itemize
@item
Copying string is O(1), no matter how long the string is, since
the same string body is shared.
@item
Taking substring usually is also O(1), for the resulting string
shares the substring of the original string body.  Gauche may copy
a part of the string for better memory management, but the visible
cost should stay pretty close to O(1).  (However, note that accessing
to a specific point by index within the original string may cost
O(N) because of multibyte string; which is a different story).
@item
On the other hand, mutating a string cost O(N) where N is the length
of string, even for replacing a character.
@end itemize

Gauche does not attempt to make string mutation faster;
@code{(string-set! s k c)} is exactly as slow as to take
two substrings, before and after of k-th character, and
concatenate them with a single-character string inbetween.
So, just avoid string mutations; we believe it's a better practice.
See also @ref{String constructors}.
@c JP
GaucheではSchemeの文字列は、内部的には、変更不可能なオブジェクト(文字列実体)を
用いて表現されている、ということを強調しておきます。
文字列が変更可能であるR7RSの仕様を満たすために、Schemeレベルの文字列は
文字列実体への間接ポインタとなっています。文字列を変更すると、
変更を反映した新しいstring bodyが作成され、Schemeレベルの文字列が
新しい文字列実体を指すように変更されます。

このことから、文字列操作の性能を見積る場合に注意が必要です。

@itemize
@item
文字列のコピーは、それがどんなに長い文字列であっても常にO(1)です。
文字列実体は共有されるからです。
@item
部分文字列を取る操作も通常はO(1)です。文字列実体を部分的に共有するからです。
メモリ管理上の都合から文字列実体の一部がコピーされる可能性はありますが、
ほとんどの場合はO(1)とみなして構いません。(ただし、マルチバイト文字処理の都合上、
文字インデックスで文字列の途中を指定する操作は別途O(N)を要する場合があります)
@item
一方で、文字列の変更はたとえ1文字の変更であっても、文字列実体の長さNに
比例したO(N)のコストを必要とします。
@end itemize

Gaucheはそもそも文字列の変更に関して全く最適化を行っていません。
@code{(string-set! s k c)}は、k番目の文字の前後の部分文字列を取って、
c一文字の文字列を間に挟んで継ぎ足すことで新たな文字列を作るのと
全く同じコストがかかります。
文字列を変更不可として扱う方が良いプログラミングスタイルだと考えるからです。
@ref{String constructors}も参照してください。
@c COMMON

@c EN
R7RS string operations are very minimal.  Gauche supports some
extra built-in operations, and also a rich string library
defined in SRFI-13.   @xref{String library}, for details about SRFI-13.
@c JP
R7RSに定義されている文字列操作は非常に限られています。
Gaucheでは追加の組込み手続きのほか、
SRFI-13に定義されている豊富な文字列ライブラリを備えています。
SRFI-13については@ref{String library}を参照してください。
@c COMMON

@menu
* String syntax::
* String predicates::
* String constructors::
* String interpolation::
* String cursors::
* String indexing::
* String accessors & modifiers::
* String comparison::
* String utilities::
* Incomplete strings::
@end menu

@node String syntax, String predicates, Strings, Strings
@subsection String syntax
@c NODE 文字列の表記

@deftp {Reader Syntax} @code{"}@dots{}@code{"}
[R7RS+]
@c EN
Denotes a literal string.  Inside the double quotes, the following
backslash escape sequences are recognized.
@c JP
リテラル文字列です。ダブルクオートの中では、
以下のエスケープシーケンスが認識されます。
@c COMMON

@table @code
@item \"
@c EN
[R7RS] Double-quote character
@c JP
[R7RS] ダブルクオート文字
@c COMMON
@item \\
@c EN
[R7RS] Backslash character
@c JP
[R7RS] バックスラッシュ文字
@c COMMON
@item \n
@c EN
[R7RS] Newline character (ASCII 0x0a).
@c JP
[R7RS] 改行文字 (ASCII 0x0a)
@c COMMON
@item \r
@c EN
[R7RS] Return character (ASCII 0x0d).
@c JP
[R7RS] 復帰文字 (ASCII 0x0d)
@c COMMON
@item \f
@c EN
Form-feed character (ASCII 0x0c).
@c JP
フォームフィード (ASCII 0x0c)
@c COMMON
@item \t
@c EN
[R7RS] Tab character (ASCII 0x09)
@c JP
[R7RS] タブ文字 (ASCII 0x09)
@c COMMON
@item \a
@c EN
[R7RS] Alarm character (ASCII 0x07).
@c JP
[R7RS] アラーム文字 (ASCII 0x07)
@c COMMON
@item \b
@c EN
[R7RS] Backspace character (ASCII 0x08).
@c JP
[R7RS] バックスペース文字 (ASCII 0x08)
@c COMMON
@item \0
@c EN
ASCII NUL character (ASCII 0x00).
@c JP
NUL文字 (ASCII 0x00)
@c COMMON
@item \<whitespace>*<newline><whitespace>*
@c EN
[R7RS] Ignored.  This can be used to break a long string literal for readability.
This escape sequence is introduced in R6RS.
@c JP
[R7RS] 無視されます。長い文字列リテラルを読みやすさのために折り返す時に便利です。
このエスケープシーケンスはR6RSで導入されました。
@c COMMON
@item \x@var{N};
@c EN
[R7RS] A character whose Unicode codepoint is represented by
hexadecimal number @var{N}, which is any number of hexadecimal digits.
(See the compatibility notes below.)
@c JP
[R7RS] 16進数@var{N}で表現されたUnicodeコードポイントの文字。
16進数は何桁でも良い。(下の互換性に関する注参照。)
@c COMMON
@item \u@var{NNNN}
@c EN
A character whose UCS2 code is represented by four-digit
hexadecimal number @var{NNNN}.
@c JP
4桁の16進数@var{NNNN}によって示されるUCS2コードを持つ文字。
@c COMMON
@item \U@var{NNNNNNNN}
@c EN
A character whose UCS4 code is represented by eight-digit
hexadecimal number @var{NNNNNNNN}.
@c JP
8桁の16進数@var{NNNNNNNN}によって示されるUCS4コードを持つ文字。
@c COMMON
@end table

@c EN
The following code is an example of backslash-newline escape sequence:
@c JP
下はバックスラッシュ-改行エスケープシーケンスの使用例です。
@c COMMON
@example
(define *message* "\
  This is a long message \
  in a literal string.")

*message*
  @result{} "This is a long message in a literal string."
@end example

@c EN
Note the whitespace just after `message'.   Since any whitespaces
before `in' is eaten by the reader, you have to put a whitespace
between `message' and the following backslash.  If you want to include
an actual newline character in a string, and any indentation after it,
you can put '\n' in the next line like this:
@c JP
`message' の後の空白に注意してください。`in'の前の空白は読み込みルーチンによって
無視されてしまうので、空白を入れたければ`message'と続くバックスラッシュの間に
入れる必要があります。もし文字列中に実際に改行文字を入れ、さらにその後の
文字列をインデントさせたい場合は次のようにすると良いでしょう:
@c COMMON

@example
(define *message/newline* "\
  This is a long message, \
  \n   with a line break.")
@end example

@c EN
@b{Note for the compatibility}:
We used to recognize a syntax @code{\xNN} (two-digit hexadecimal number,
without semicolon terminator) as a character in a string; for example,
@code{"\x0d\x0a"} was the same as @code{"\r\n"}.  We still support it
when we don't see the terminating semicolon, for the compatibility.
There are ambiguous cases: @code{"\0x0a;"} means @code{"\n"} in the
current syntax, while @code{"\n;"} in the legacy syntax.

Setting the reader mode to @code{legacy} restores the old behavior.
Setting the reader mode to @code{warn-legacy} makes it work like the default
behavior, but prints warning when it finds legacy syntax.
@xref{Reader lexical mode}, for the details.
@c JP
@b{互換性に関する注}:
以前は、@code{\xNN} (2桁固定の16進数、終端のセミコロン無し) を
文字列中の文字と認識していました。
例えば@code{"\x0d\x0a"}は@code{"\r\n"}と同じでした。
互換性のため、終端のセミコロンが見当たらない場合は古い構文もサポートされます。
しかし曖昧な場合もあります。@code{"\x0a;"}は新しい構文では
@code{"\n"}と同じですが、、古い構文では@code{"\n;"}となります。

リーダのモードを@code{legacy}にセットすると、常に古い構文で認識されます。
リーダのモードを@code{warn-legacy}にセットすると、
デフォルトと同じように振る舞いますが、古い構文を見つけた場合は警告が出力されます。
詳しくは@ref{Reader lexical mode}を参照してください。
@c COMMON
@end deftp


@node String predicates, String constructors, String syntax, Strings
@subsection String predicates
@c NODE 文字列に関する述語

@defun string? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a string, @code{#f} otherwise.
@c JP
@var{obj}が文字列なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun string-immutable? obj
@c EN
Returns @code{#t} if @var{obj} is an immutable string, @code{#f} otherwise

String literals, and the strings returned from certain procedures such
as @code{symbol->string} are immutable.  To ensure you get
an immutable string in a program, you can use @code{string-copy-immutable}.
@c JP
@var{obj}が変更不可な文字列なら@code{#t}を、そうでなければ@code{#f}を返します。

文字列リテラルおよび、@code{symbol->string}などいくつかの手続きから
返される文字列は変更不可です。プログラム中で変更不可の文字列を確実に手に入れたい場合は
@code{string-copy-immutable}が使えます。
@c COMMON
@end defun

@defun string-incomplete? obj
@c EN
Returns @code{#t} if @var{obj} is an incomplete string, @code{#f} otherwise
@c JP
@var{obj}が不完全文字列なら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@node String constructors, String interpolation, String predicates, Strings
@subsection String constructors
@c NODE 文字列の作成

@defun make-string k :optional char
[R7RS base]
@c EN
Returns a string of length @var{k}.  If optional @var{char} is given,
the new string is filled with it.  Otherwise, the string is filled with
a whitespace.  The result string is always complete.

@example
(make-string 5 #\x) @result{} "xxxxx"
@end example

Note that the algorithm to allocate a string by @code{make-string} and
then fills it one character at a time is @emph{extremely} inefficient
in Gauche, and should be avoided.

In Gauche, a string is simply a pointer to an immutable string content.
If you mutate a string by, e.g. @code{string-set!}, Gauche allocates
whole new immutable string content, copies the original content with
modification, then swap the pointer of the original string.  It is no
more efficient than making a new copy.

You can use an output string port for a string construction
(@pxref{String ports}).
Even creating a list of characters and
using @code{list->string} is faster than using @code{make-string} and
@code{string-set!}.
@c JP
長さ@var{k}の文字列を作成して返します。
@var{char}が与えられればそれで内容を満たします。@var{char}が与えられなければ
空白文字で満たされます。常に完全な文字列が返されます。

@example
(make-string 5 #\x) @result{} "xxxxx"
(make-string 5 #\ふ) @result{} "ふふふふふ"
@end example

@code{make-string}で必要な長さの文字列をアロケートして、@code{string-set!}
で順番に埋めて行くアルゴリズムは、Gaucheでは@emph{極めて}非効率であることに
注意してください。

Gaucheの文字列オブジェクトは、変更不可能な文字列本体への単なるポインタです。
@code{string-set!}等の文字列を破壊的変更する操作は、
実際には変更箇所以外は元の文字列本体をコピーした新たな文字列本体をアロケートして、
元の文字列オブジェクトのポインタを差し替えるこようになっています。
従って、文字列のコピーを作るのと同等の効率となります。

文字列の順次作成に適しているのは文字列ポートです
(@ref{文字列ポート}参照)。それが使えない場合、
文字のリストを作成し、@code{list->string}で変換する方がまだ@code{make-string}と
@code{string-set!}を使うより良いでしょう。
@c COMMON
@end defun

@defun make-byte-string k :optional byte
@c EN
Creates and returns an incomplete string o size @var{k}.
If @var{byte} is given,
which must be an exact integer, and its lower 8 bits
are used to initialize every byte in the created string.
@c JP
大きさ@var{k}の不完全な文字列を作成して返します。
@var{byte}が与えられた場合は、その下位1バイトで文字列の各バイトを初期化します。
@var{byte}は正確な整数でなければなりません。
@c COMMON
@end defun

@defun string char @dots{}
[R7RS base]
@c EN
Returns a string consisted by @var{char} @dots{}.
@c JP
文字@var{char} @dots{} から構成された文字列を返します。
@c COMMON
@end defun

@deffn {Generic Function} x->string obj
@c EN
A generic coercion function.
Returns a string representation of @var{obj}.
The default methods are defined as follows: strings are returned
as is, numbers are converted by @code{number->string}, symbols are
converted by @code{symbol->string}, and other objects are
converted by @code{display}.

Other class may provide a method to customize the behavior.
@c JP
文字列への強制型変換手続きです。
@var{obj}の文字列表現を返します。
デフォルトのメソッドでは、文字列はそのまま返され、数値は@code{number->string}で、
シンボルは@code{symbol->string}で変換され、その他のオブジェクトは@code{display}表現
が使われます。

他のクラスはこのメソッドを定義することにより、独自の変換関数を提供することができます。
@c COMMON
@end deffn

@node String interpolation, String cursors, String constructors, Strings
@subsection String interpolation
@c NODE 文字列の補間

@c EN
The term "string interpolation" is used in various scripting languages
such as Perl and Python to refer to the feature to embed expressions
in a string literal, which are evaluated and then their results are
inserted into the string literal at run time.
@c JP
「文字列の補間(string interpolation)」という用語は、
PerlやPythonなど様々なスクリプト言語で、文字列リテラル内に式を埋め込んでおき
実行時に式を評価した値をそのリテラル内に埋め込む機能を指します。
@c COMMON

@c EN
Scheme doesn't define such a feature, but Gauche implements it as a
reader macro.
@c JP
Schemeはそのような機能を定義していませんが、Gaucheではリーダーマクロを使って
文字列の補間を実装しました。
@c COMMON

@deftp {Reader Syntax} @code{#}@var{string-literal}
@lxindex #"
@c EN
Evaluates to a string.  If @var{string-literal} contains the
character sequence @code{~@var{expr}}, where
@var{expr} is a valid external representation
of a Scheme expression, @var{expr} is evaluated and
its result is inserted in the original place (by using @code{x->string},
see @ref{String constructors}).
@c JP
文字列に評価されます。@var{string-literal}内に、@code{~@var{expr}}
というシーケンス(ここで@var{expr}は有効なScheme式の外部表現)が
現われたら、@var{expr}が評価されてその結果がもとの位置に埋め込まれます。
結果の文字列化には@code{x->string}が使われます(@ref{String constructors}参照)。
@c COMMON

@c EN
The tilde and the following expression must be adjacent (without containing
any whitespace characters), or it is not recognized as a special sequence.
@c JP
チルダと続く式とは、空白文字等を入れずに隣接していなければなりません。
そうでない場合は置換されません。
@c COMMON

@c EN
To include a tilde itself immediately followed by non-delimiting
character, use @code{~~}.
@c JP
すぐ後ろに非空白文字が来る場所にチルダ自身を埋め込みたい場合は
@code{~~}とします。
@c COMMON

@c EN
Other characters in the @var{string-literal} are copied as is.
@c JP
それ以外の@var{string-literal}内の文字シーケンスはそのままコピーされます。
@c COMMON

@c EN
If you use a variable as @var{expr} and need to delimit it from the
subsequent string, you can use the symbol escape syntax
using `|' character, as shown in the last two examples below.
@c JP
@var{Expr}に単独の変数を使う場合で、それに続く文字列と変数名を区切りたい
場合は、`|'文字を使ったシンボルエスケープ構文が使えます。下の例の最後の
2つを見て下さい。
@c COMMON

@example
#"This is Gauche, version ~(gauche-version)."
 @result{} "This is Gauche, version @VERSION@."

#"Date: ~(sys-strftime \"%Y/%m/%d\" (sys-localtime (sys-time)))"
 @result{} "Date: 2002/02/18"

(let ((a "AAA")
      (b "BBB"))
 #"xxx ~a ~b zzz")
 @result{} "xxx AAA BBB zzz"

#"123~~456~~789"
 @result{} "123~456~789"

(let ((n 7)) #"R~|n|RS")
 @result{} "R7RS"

(let ((x "bar")) #"foo~|x|.")
 @result{} "foobar"
@end example

@c EN
In fact, the reader expands this syntax into a macro call,
which is then expanded into a call of @code{string-append}
as follows:
@c JP
実は、リーダーはこの構文をマクロ呼び出しへと変換し、それが最終的には
@code{string-append}への呼び出しへと変換されます。
@c COMMON
@example
#"This is Gauche, version ~(gauche-version)."
 @equiv{}
(string-interpolate* ("This is Gauche, version "
                      (gauche-version)
                      "."))

;; then, it expands to...

(string-append "This is Gauche, version "
               (x->string (gauche-version))
               ".")
@end example

@c EN
(NB: The exact spec of @code{string-interpolate*} might change in future,
so do not rely on the current behavior.)
@c JP
(註: @code{string-interpolate*}の厳密な仕様は将来変わるかもしれないので、
現在の振る舞いに依存したコードは避けて下さい。)
@c COMMON

@c EN
Since the @code{#"..."} syntax is equivalent to a macro call
of @code{string-interpolate*}, which is provided in the Gauche module,
it must be visible from where you use the interpolation syntax.
When you write Gauche code, typically you implicitly inherit the Gauche
module so you don't need to worry; however, if you start from R7RS code,
make sure you import @code{string-interpolate*}
(by @code{(import (gauche base))}, for example) whenever you use
string interpolation syntax.  Also be careful not to shadow
@code{string-interpolate*} locally.
@c JP
@code{#"..."}構文はマクロ@code{string-interpolate*}の呼び出しと等価なので、
この構文を使う際にはGaucheモジュールの@code{string-interpolate*}が
見えている必要があります。Gaucheコードを書く場合、Gaucheモジュールはデフォルトで
継承されているので、普通は気にする必要はありません。R7RSコードから始めて
@code{#"..."}構文を使いたくなった場合は、@code{(import (gauche base))}等で
@code{string-interpolate*}を見えるようにしてください。
また、ローカルに@code{string-interpolate*}をシャドウしないように気をつけてください。
@c COMMON
@end deftp

@deftp {Reader Syntax} @code{#`}@var{string-literal}
@lxindex #`
@c EN
This is the old style of string-interpolation.  It is still recognized,
but discouraged for the new code.

Inside @var{string-literal}, you can use @code{,@var{expr}}
(instead of @code{~@var{expr}}) to
evaluate @var{expr}.  If comma isn't immediately followed by a
character starting an expression, it loses special meaning.
@c JP
これは文字列補間の古い書法です。まだ認識されますが、
新たなコードでは使わないでください。

@var{string-literal}の中で、(@code{~@var{expr}} ではなく)
@code{,@var{expr}} とマークされた部分の@var{expr}が評価されます。
コンマのすぐ次に式を開始する文字がこなければ、コンマはその効力を失います。
@c COMMON

@example
#`"This is Gauche, version ,(gauche-version)"
@end example
@end deftp


@c EN
@emph{Rationale of the syntax:}
There are wide variation of string interpolation syntax among scripting
languages.  They are usually linked with other syntax of the language
(e.g. prefixing @code{$} to mark evaluating place is in sync with variable
reference syntax in some languages).

The old style of string interpolation syntax was taken from quasiquote
syntax, because those two are conceptually
similar operations (@pxref{Quasiquotation}).
However, since comma character is frequently used in string literals,
it was rather awkward.

We decided that tilde is more suitable as the unquote character for
the following reasons.

@itemize
@item
Traditionally, Lisp's string formatter @code{format} uses @code{~} to introduce
format directives (@pxref{Formatting output}).  Lispers are used to
scan @code{~}'s in a string as variable portions.
@item
Gauche's @code{~} is a universal accessor, and the operator has a nuance
of ``taking something out of it''
(@pxref{Universal accessor}).
@item
Clojure, a new Lisp dialect, adopted @code{~} as the unquote character in
the quasiquote syntax, instead of commas.
@end itemize

Note that Scheme allows wider range of characters for valid identifier names
than usual scripting languages.
Consequently, you will almost always need to use `|' delimiters
when you interpolate the value of a variable.
For example, while you can write
@code{"$year/$month/$day $hour:$minutes:$seconds"} in Perl,
you should write @code{#"~|year|/~|month|/~day ~|hour|:~|minutes|:~seconds"}.
It may be better always to delimit direct variable references
in this syntax to avoid confusion.
@c JP
@emph{この構文を採用した理由:}
スクリプト言語の文字列補間構文には様々なバリエーションがありますが、通常、
その言語の他の構文と関連しているものが多いです
(例えば、@code{$}で変数参照する言語が、@code{$}を文字列中の評価部分に前置する等)。

Gaucheの古い形式の文字列補間構文では、準クオートの構文を流用していました
(@ref{Quasiquotation}参照)。準クオートと文字列補間は意味的に似ているからです。
けれども、コンマはそれ自体が文字列中によく出てくる文字なので、少々不格好な仕様でした。

そこで、以下のような理由から、チルダの方がアンクオート文字としてふさわしいと判断しました。

@itemize
@item
伝統的に、Lispの文字列フォーマッティング関数@code{format}では
@code{~}をフォーマット指示子の導入に使ってきました
(@ref{Formatting output}参照)。Lisperは文字列中で@code{~}を走査して
可変部分を見つけるのに慣れています。
@item
Gaucheは @code{~} を万能アクセサとして使っていて、この文字には「中から何かを取り出す」
ニュアンスを付加しています
(@ref{Universal accessor}参照)。
@item
新たなLisp方言であるClojureは、準クオート構文中のアンクオート文字に
コンマでなく @code{~} を採用しています。
@end itemize

Schemeは他のスクリプト言語より一般的により多くの文字を変数名に使うことが出来ることに注意して下さい。
結果として、変数の値を文字列に挿入する際、ほとんどの場合において変数名を`|'で区切る
必要があるでしょう。例えば、Perlでは
@code{"$year/$month/$day $hour:$minutes:$seconds"}
と書けたものが、Gaucheでは
@code{#`"~|year|/~|month|/~day ~|hour|:~|minutes|:~seconds"}
と書かねばなりません。
混乱を避けるためには、この構文内では常に直接の変数参照は`|'で区切るようにしておくのが良いかもしれません。
@c COMMON


@node String cursors, String indexing, String interpolation, Strings
@subsection String cursors
@c NODE 文字列カーソル

@c EN
String cursors are opaque objects that point into strings, similar to
indexes. Cursors however are more efficient. For example, to get a
character with @code{string-ref} using an index on a multibyte string,
Gauche needs to iterate from the beginning of the string until that
position, or @code{O(n)}. Using cursors you can access in @code{O(1)}
(for singlebyte (ASCII) strings or an indexed string,
Gauche does it in @code{O(1)} even with index.  @xref{String indexing},
for the details of indexed string.)
@c JP
文字列カーソルは文字列の中の文字を指示するオブジェクトです。文字列中の文字を指定するのに
インデックスも使えますが、カーソルの方が効率が良いです。例えば、
文字インデックスを使ってマルチバイト文字列中の文字を@code{string-ref}で取り出すには、
Gaucheは文字列の最初からその文字まで文字列をたどらなければならず、
インデックスnに対してO(n)かかります。カーソルを使えばO(1)でアクセスできます
(ASCII文字だけからなる文字列や、索引付加済み文字列では
文字インデックスを使ったアクセスもO(1)になります。
索引付加済み文字列については@ref{String indexing}を参照してください。)
@c COMMON

@c EN
For a string of length n, there can be n+1 cursors. The
last cursor at the end of the string does not point to any valid
character, it's usually used to determine if nothing is found.
@c JP
長さnの文字列には、n+1個のカーソルが存在し得ます。
一番最後のカーソルは文字列末尾を指し、該当する文字を持ちません。
探している文字が無いことを示す値としても使われます。
@c COMMON

@c EN
A string cursor is associated with a specific string and should not be
used with another string. A string cursor also becomes invalid when
the associated string is modified. Accessing an invalid cursor does
not always fail though. Running @code{gosh} with @code{-fsafe-string-cursors}
could help catch these issues, with some performance overhead.
@xref{Gosh command-line options}.
@c JP
文字列カーソルは特定の文字列と結びついていて、それ以外の文字列に対して使うのは無効です。
また、元の文字列が変更されると文字列カーソルは無効になります。
ただ、無効になったカーソルを使っても必ずしもエラーになるとは限りません。
@code{gosh}を@code{-fsafe-string-cursors}オプションつきで起動すると、
性能が落ちますがその種のエラーを検出することができます。
詳しくは@ref{Gosh command-line options}を参照してください。
@c COMMON

@c EN
Most of the time, string cursors aren't heap-allocated.  It is only
allocated in heap either (1) when it points at a huge byte index,
or (2) when you use @code{-fsafe-string-cursors} to enable extra
run-time check.

The threashold of byte index to cause a string cursor to be heap-allocated
is 2^56 on 64bit systems, and 2^24 on 32bit systems, in the current
implementation.  On 64bit systems you will never hit the threashold practically.
On 32bit systems you may, if you have a huge string, but you may want to
consider using other data structure rather than keeping such data in
one string object.
@c JP
ほとんどの場合、文字列カーソルはヒープアロケーションを伴いません。
文字列カーソルがヒープにアロケートされるのは (1)巨大なバイトインデックスを指す場合か、
(2)@code{-fsafe-string-cursors}を使って追加の実行時検査を有効にした場合です。

現在の実装では、カーソルがヒープアロケートされる閾値は、64bitシステムでは
2^56、32bitシステムでは2^24です。
64bitシステムでこの閾値を越えることは現実的にはありえないでしょう。
32bitシステムでは、超巨大な文字列オブジェクトを使った場合にあり得るかもしれませんが、
それほど大きなデータを扱うならば、
単一の文字列ではなくデータ構造を工夫した方が良いかもしれません。
@c COMMON

@c EN
Most procedures that take indexes in Gauche can also take
cursors. Relying on this though is unportable. For example, the
@code{substring} procedure in RnRS standards does not mention anything
about cursors even though the Gauche version accepts cursors. For
portable programs, you should only use cursors on procedures from
@code{srfi.130} module (@pxref{Cursor-based string library}).
@c JP
文字インデックスを取るGaucheの文字列手続きのほとんどはカーソルも受け付けます。
但し、それに依存したコードは移植性がありません。例えば@code{substring}は、
Gauche版ではインデックスもカーソルも使えますが、RnRSではインデックスしか許していません。
移植性のあるプログラムを書く際には、@code{srfi.130}モジュールにある手続きでのみ
カーソルを使うようにしてください (@ref{Cursor-based string library}参照)。
@c COMMON

@deftp {Builtin Class} <string-cursor>
@c EN
Represents a cursor. When printed out, you'll see the
@emph{byte offset} from the beginning of the string, not the character index.
@c JP
文字列カーソルのクラスです。書き出される時に表示される数字は、
文字インデックスではなく@emph{文字へのバイトオフセット}です。
@c COMMON

@example
(string-index->cursor "あかさたな" 2)
 @result{} #<string-cursor 6>
@end example
@end deftp

@defun string-cursor? @var{obj}
[SRFI-130]
@c EN
Returns @code{#t} if @var{obj} is a string cursor, @code{#f} otherwise.
@c JP
@var{obj}が文字列カーソルなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun string-cursor-start @var{str}
[SRFI-130]
@c EN
Returns a cursor pointing to the start of
a string @var{str}. It returns a valid cursor on an
empty string too. It's the same as @code{string-cursor-end} in that
case.
@c JP
文字列@var{str}の先頭を指す文字列カーソルを返します。
@var{str}が空文字列でも有効な文字列カーソルが返されます。
(@var{str}が空文字列の場合、@code{string-cursor-end}が返すカーソルは
同じものです)。
@c COMMON
@end defun

@defun string-cursor-end @var{str}
[SRFI-130]
@c EN
Returns a cursor pointing to the end of @var{str} (the point after
the last character.)  If @var{str} is empty, it is the same
as @code{string-cursor-start}.
This cursor does not point to any valid character of the string.
@c JP
文字列@var{str}の末尾(最後の文字の直後)を指す文字列カーソルを返します。
@var{str}が空文字列の場合、@code{string-cursor-start}が返すカーソルと
同じものが返されます。
このカーソルは有効な文字を指しません。
@c COMMON
@end defun

@defun string-cursor-next @var{str} @var{cur}
[SRFI-130]
@c EN
Returns the cursor into @var{str} following @var{cur}. @var{cur} can
also be an index.  An error is signaled if @var{cur} points to the end
of the string.
@c JP
文字列@var{str}中で、@var{cur}が指す文字の次を指すカーソルを返します。
@var{cur}に文字インデックスを渡すこともできます。@var{cur}が文字列末尾を
指している場合はエラーが投げられます。
@c COMMON
@end defun

@defun string-cursor-prev @var{str} @var{cur}
[SRFI-130]
@c EN
Returns the cursor into @var{str} preceding @var{cur}. @var{cur} can
also be an index.  An error is signaled if @var{cur} points to the
beginning of the string.
@c JP
文字列@var{str}中で、@var{cur}が指す文字の一つ前を指すカーソルを返します。
@var{cur}には文字インデックスを渡すこともできます。@var{cur}が文字列先頭を
指している場合はエラーが投げられます。
@c COMMON
@end defun

@defun string-cursor-forward @var{str} @var{cur} @var{n}
[SRFI-130]
@c EN
Returns the cursor into @var{str} following @var{cur} by @var{n}
characters. @var{cur} can also be an index.
@c JP
文字列@var{str}中で、カーソル@var{cur}が指す文字から@var{n}文字先を指す
カーソルを返します。@var{cur}に文字インデックスを渡すこともできます。
@c COMMON
@end defun

@defun string-cursor-back @var{str} @var{cur} @var{n}
[SRFI-130]
@c EN
Returns the cursor into @var{str} preceding @var{cur} by @var{n}
characters. @var{cur} can also be an index.
@c JP
文字列@var{str}中で、カーソル@var{cur}が指す文字から@var{n}文字前を指す
カーソルを返します。@var{cur}に文字インデックスを渡すこともできます。
@c COMMON
@end defun

@defun string-index->cursor @var{str} @var{index}
[SRFI-130]
@c EN
Convert an @var{index} to a cursor. If @var{index} is a cursor it will
be returned as-is.
@c JP
文字列インデックス@var{index}をカーソルに変換します。
@var{index}が既にカーソルであった場合はそれがそのまま返されます。
@c COMMON
@end defun

@defun string-cursor->index @var{str} @var{cur}
[SRFI-130]
@c EN
Convert a cursor to an index. If @var{cur} is a an index it will be
returned as-is.
@c JP
文字列カーソル@var{cur}をインデックスに変換します。
@var{cur}が既にインデックスであった場合はそれをそのまま返します。
@c COMMON
@end defun

@defun string-cursor-diff @var{str} @var{start} @var{end}
[SRFI-130]
@c EN
Returns the number of characters between @var{start} and @var{end}. It
should be non-negative if @var{start} precedes @var{end}, non-positive
otherwise. @var{start} and @var{end} also accept index.
@c JP
二つの文字列カーソル@var{start}と@var{end}の間にある文字数を返します。
@var{start}より@var{end}が後を指していれば結果は正に、
@var{end}が@var{start}より手前にあれば結果は負になります。
@var{start}と@var{end}は文字インデックスであっても構いません。
@c COMMON
@end defun

@defun string-cursor=? @var{cur1} @var{cur2}
@defunx string-cursor<? @var{cur1} @var{cur2}
@defunx string-cursor<=? @var{cur1} @var{cur2}
@defunx string-cursor>? @var{cur1} @var{cur2}
@defunx string-cursor>=? @var{cur1} @var{cur2}
[SRFI-130]
@c EN
Compares two cursors or two indexes (but not a cursor and an index)
and returns @code{#t} or @code{#f} accordingly.
@c JP
二つの文字列カーソル、もしくは二つのインデックスの前後関係を比較します
(カーソルとインデックスは比較できません)。
@c COMMON
@end defun

@node String indexing, String accessors & modifiers, String cursors, Strings
@subsection String indexing
@c NODE 文字列索引

@c EN
Since Gauche stores strings in multibyte encoding, random access
requires O(N) by default.  In most cases, string access is either
sequential or search-and-extract pattern, and Gauche provides direct
means for these operations, so you don't need to deal with indexed access.
However, there may be a case that you have need more efficient random
access string (mostly when porting third-party code, we imagine).
@c JP
Gaucheは文字列をマルチバイト形式で保持しているので、
デフォルトではランダムアクセスにO(N)の時間がかかります。
ほとんどの場合、文字列へのアクセスは最初から順に見て行くか、
検索してマッチした箇所を見るかで、Gaucheはそれらの操作をプリミティブで提供しているので、
文字列を文字のインデックスでアクセスする必要は滅多にないでしょう。
けれどもどうしても文字列をランダムにアクセスしたい場合があるかもしれません
(サードパーティ製のライブラリの移植、などが考えられます)。
@c COMMON

@c EN
There are a couple of ways to achieve O(1) random access.
@c JP
O(1)ランダムアクセスを実現する方法は二つばかりあります。
@c COMMON

@c EN
First, instead of integer character indexes,
you can use string cursors (@pxref{String cursors}).  It is defined
by @code{srfi.130}, and you can use the code that's using SRFI-130
as is, without worring about slow access.  However, if external interface
gives you integer character index, converting index to cursor and vice versa
takes O(N) after all.
@c JP
一つは、文字へのインデックスのかわりに、
文字列カーソルを使うことです(@ref{String cursors}参照)。
文字列カーソルは@code{srfi.130}で定義され、SRFI-130のインタフェースを使っている
コードはそのまま、効率的に動きます。ただ、もし外部に向けたインタフェースが
文字インデックスを要求していたなら、カーソルとインデックス間の相互変換のところで
O(N)時間がかかってしまいます。
@c COMMON

@c EN
There's another way.  You can precompute @emph{string index}, mapping from
integer character index to the position in the multibyte string.  It costs
O(N) of time and space to compute it, but once computed, you have
O(1) random access.  (We store positions for every K characters, where K
is between 16 to 256, so it won't take up as large storage as the
actual string body).
@c JP
もう一つの方法は、文字のインデックスとマルチバイト文字列内の位置を表す
@emph{文字列索引}をあらかじめ計算しておくことです。計算時にはO(N)の時間・空間
コストがかかりますが、一度計算すれば以降はO(1)でランダムアクセスできます。
(実際には、文字列の長さに応じて16から256文字ごとに位置を記録するので、
文字列本体に比べて索引はそれほどメモリを取りません)。
@c COMMON

@c EN
For portability, SRFI-135 Immutable Texts provides O(1) accessible string
as ``texts''.  On Gauche, a text is just an immutable string with
index attached.
@c JP
SRFI-135 (変更不可なテキスト) はO(1)アクセス可能な文字列を「テキスト」という型で
扱っています。Gaucheでは、テキストは単に文字列索引つきの変更不可な文字列です。
@c COMMON

@defun string-build-index! str
@c EN
Computes and attaches index to a string @var{str}, and returns @var{str}
itself.  The operation doesn't alter the content of @var{str}, and you can
pass immutable string as well.
@c JP
文字列@var{str}の索引を計算して、@var{str}自身を返します。
この操作は@var{str}自体の内容を変えるものではないため、変更不可な文字列にも適用できます。
@c COMMON

@c EN
If @var{str} is a single-byte string (ASCII-only, or incomplete),
or a short one (less than 64 octets), no index is attached.
It is ok to pass a string which already has an index; then index computation
is skipped.
@c JP
@var{str}がシングルバイト文字列(ASCIIのみからなるか、不完全な文字列)の場合、
あるいは短い(64バイト以下)の場合、索引は実際には計算されません。
また、既に索引がある文字列を渡しても構いません。その場合、単に索引の計算はスキップされます。
@c COMMON

@c EN
The index is attached to the string's content.  If you alter @var{str}
by e.g. @code{string-set!}, the index is discarded.
@c JP
索引は文字列の内容そのものに対してつけられます。@var{str}の内容を@code{string-set!}などで
置き換えた際には、索引は破棄されます。
@c COMMON
@end defun

@defun string-fast-indexable? str
@c EN
Returns @code{#t} iff index access of a string @var{str} is effectively O(1),
that is, @var{str} is either a single-byte string,
a short string, or a long multibyte string with index computed.
@c JP
文字列@var{str}への文字インデックスでのアクセスがO(1)で行える場合に@code{#t}を、
そうでなければ@code{#f}を返します。
@code{#t}が返されるのは、@var{str}がシングルバイト文字列か、
短い文字列か、文字列索引が付加された長い文字列である場合です。
@c COMMON
@end defun


@node String accessors & modifiers, String comparison, String indexing, Strings
@subsection String accessors & modifiers
@c NODE 文字列のアクセスと変更

@defun string-length string
[R7RS base]
@c EN
Returns a length of (possibly incomplete) string @var{string}.
@c JP
文字列@var{string}の長さ(文字数)を返します。
@var{string}は不完全な文字列であっても構いません。
@c COMMON
@end defun

@defun string-size string
@c EN
Returns a size of (possibly incomplete) @var{string}.
A size of string is a number of bytes @var{string} occupies on memory.
The same string may have different sizes if the native encoding scheme
differs.

For incomplete string, its length and its size always match.
@c JP
文字列@var{string}の大きさを返します。文字列の大きさは、
@var{string}が占めるメモリ上のバイト数で、これは文字列の内部エンコーディングに
依存します。同じ文字列であっても内部エンコーディングが違えば違う大きさになる場合も
あります。

不完全な文字列では、文字列の長さと大きさは常に一致します。
@c COMMON
@end defun

@defun string-ref cstring k :optional fallback
[R7RS+ base]
@c EN
Returns @var{k}-th character of a complete string @var{cstring}.
It is an error to pass an incomplete string.

By default, an error is signaled if @code{k} is out of range
(negative, or greater than or equal to the length of @var{cstring}).
However, if an optional argument @var{fallback} is given,
it is returned in such case.  This is Gauche's extension.

If @var{cstring} is a multibyte string without index attached,
this procedure takes O(@var{k}) time.  @xref{String indexing}, for
ensuring O(1) access.

@var{k} can also be a string cursor (also Gauche's extension).
Cursor acccess is O(1).
@c JP
完全な文字列@var{cstring}の@var{k}番目の文字を返します。
不完全な文字列を渡すのはエラーです。

@var{k}が負数であったり@var{cstring}の長さと同じかそれ以上であった場合には
エラーが報告されます。但し、引数@var{fallback}が与えられている場合にはエラーを
報告せず@var{fallback}が返されます。これはGaucheの拡張です。

@var{cstring}がマルチバイト文字列でインデックスが付加されていない場合、
この手続きはO(@var{k})時間かかります。O(1)アクセスを得る方法は
@ref{String indexing}を参照してください。

@var{k}に文字列カーソルを渡すこともできます (これもGaucheの拡張です)。
カーソルによるアクセスはO(1)です。
@c COMMON
@end defun

@defun string-byte-ref string k
@c EN
Returns @var{k-th} byte of a (possibly incomplete) string @var{string}.
Returned value is an integer in the range between 0 and 255.
@var{k} must be greater than or equal to zero, and less than
@code{(string-size @var{string})}.
@c JP
(多分、不完全な)文字列@var{string}の@var{k番目}のバイトを返します。
戻り値は、0から255の範囲の整数です。@var{k}は0以上、
@code{(string-size @var{string})}より小でなければなりません。
@c COMMON
@end defun

@defun string-set! string k char
[R7RS base]
@c EN
Substitute @var{string}'s @var{k}-th character by @var{char}.
@var{k} must be greater than or equal to zero, and less than
@code{(string-length @var{string})}.
Return value is undefined.

If @var{string} is an incomplete string, integer value of the lower 8 bits
of @var{char} is used to set @var{string}'s @var{k}-th byte.

See the notes in @code{make-string} about performance consideration.
@c JP
@var{string}の@var{k}番目の文字を@var{char}で置き換えます。
@var{k}は0以上、@code{(string-length @var{string})}より小でなければ
なりません。戻り値は未定義です。

@var{string}が不完全文字列の場合、@var{char}の下位8ビットの整数値は、
@var{string}の@var{k}番目のバイトをセットするために使われます。

パフォーマンス上の考慮点について、@code{make-string}の説明を参照して下さい。
@c COMMON
@end defun

@defun string-byte-set! string k byte
@c EN
Substitute @var{string}'s @var{k}-th byte by integer @var{byte}.
@var{byte} must be in the range between 0 to 255, inclusive.
@var{k} must be greater than or equal to zero, and less than
@code{(string-size @var{string})}.
If @var{string} is a complete string, it is turned to incomplete string
by this operation.
Return value is undefined.
@c JP
@var{string}の@var{k}番目のバイトを整数@var{byte}で置き換えます。
@var{byte}は0から255の範囲(255を含む)でなければなりません。
@var{k}は0以上、@code{(string-size @var{string})}より小である必要があります。
@var{string}が完全文字列の場合、この操作により不完全文字列になります。
戻り値は未定義です。
@c COMMON
@end defun

@node String comparison, String utilities, String accessors & modifiers, Strings
@subsection String comparison
@c NODE 文字列の比較

@defun string=? string1 string2 string3 @dots{}
[R7RS base]
@c EN
Returns @code{#t} iff all arguments are strings with the same content.
@c JP
全ての引数が内容の等しい文字列であれば@code{#t}を返します。
@c COMMON

@c EN
If any of arguments is incomplete string, it returns @code{#t} iff
all arguments are incomplete and have exactly the same content.
In other words, a complete string and an incomplete string never equal
to each other.
@c JP
もし引数に不完全文字列がひとつでもある場合、
全ての文字列が不完全でありかつ内容が同じである場合に限り@code{#t}が返ります。
言い換えれば、完全な文字列と不完全な文字列は決して等しくなりません。
@c COMMON
@end defun

@defun string<? string1 string2 string3 @dots{}
@defunx string<=? string1 string2 string3 @dots{}
@defunx string>? string1 string2 string3 @dots{}
@defunx string>=? string1 string2 string3 @dots{}
[R7RS base]
@c EN
Compares strings in codepoint order.  Returns @code{#t} iff
all the arguments are ordered.
@c JP
文字列同士をコードポイントの順序で比較します。全ての引数が順序どおりであれば
@code{#t}が、そうでなければ@code{#f}が返されます。
@c COMMON

@c EN
Comparison between an incomplete string and a complete string, or between
two incomplete strings, are done by octet-to-octet comparison.  If a
complete string and an incomplete string have exactly the same binary
representation of the content, a complete string is smaller.
@c JP
不完全文字列と完全文字列、もしくは不完全文字列同士の比較は、
内容のオクテット同士の比較となります。内容のバイナリ表現が一致する
完全文字列と不完全文字列を比較した場合は、完全文字列の方が小さいとみなされます。
@c COMMON
@end defun

@defun string-ci=? string1 string2 string3 @dots{}
@defunx string-ci<? string1 string2 string3 @dots{}
@defunx string-ci<=? string1 string2 string3 @dots{}
@defunx string-ci>? string1 string2 string3 @dots{}
@defunx string-ci>=? string1 string2 string3 @dots{}
@c EN
Case-insensitive string comparison.
@c JP
大文字小文字を無視する文字列比較です。
@c COMMON

@c EN
These procedures fold argument character-wise, according to
Unicode-defined character-by-character case mapping.  See
@code{char-foldcase} for the details (@ref{Characters}).
Character-wise case folding doesn't handles the case like
German eszett:
@c JP
これらの手続きは、引数に「文字ごとの大文字小文字変換」を適用します。
(変換にはUnicodeの文字単位の大文字小文字マッピングテーブルを使います)。
詳しくは@code{char-foldcase}の説明を見てください (@ref{Characters})。
文字ごとの大文字小文字変換は、ドイツ語のエスツェットのような特別な場合を
考慮しません。
@c COMMON

@example
(string-ci=? "\u00df" "SS") @result{} #f
@end example

@c EN
R7RS requires @code{string-ci}* procedures to use string case folding.
Gauche provides R7RS-conformant case insensitive comparison procedures
in @code{gauche.unicode} (@pxref{Full string case conversion}).
If you write in R7RS, importing
@code{(scheme char)} library, you'll use @code{gauche.unicode}'s
@code{string-ci}* procedures.
@c JP
R7RSでは、@code{string-ci}*手続きは文字列としての大文字小文字変換を要求しています。
Gaucheは、R7RSに準拠した大文字小文字の違いを無視する比較手続きを
@code{gauche.unicode}モジュールに用意しています(@ref{Full string case conversion}参照)。
R7RSでプログラミングする際に@code{(scheme char)}をインポートした場合は、
@code{gauche.unicode}モジュールの@code{string-ci=?}などが使われます。
@c COMMON
@end defun

@node String utilities, Incomplete strings, String comparison, Strings
@subsection String utilities
@c NODE 文字列を扱うその他の手続き

@defun substring string start end
[R7RS+ base]
@c EN
Returns a substring of @var{string}, starting from @var{start}-th
character (inclusive) and ending at @var{end}-th character (exclusive).
The @var{start} and @var{end} arguments must satisfy
@code{0 <= @var{start} < @var{N}},
@code{0 <= @var{end} <= @var{N}}, and
@code{@var{start} <= @var{end}}, where @var{N} is the length of the
string.

@var{start} and @var{end} can also be string cursors, but this is an
extension of Gauche.
@c JP
@var{string}の@var{start}番目の文字(これを含む)から、@var{end}番目の文
字(これを含まない)までの部分文字列を返します。引数@var{start}および
@var{end}は以下を満さなければなりません。
@code{0 <= @var{start} < @var{N}}、
@code{0 <= @var{end} <= @var{N}}、
@code{@var{start} <= @var{end}}。ただし、@var{N}は与えられた文字列の長
さです。
@c COMMON

@c EN
When @var{start} is zero and @var{end} is @var{N}, this procedure
returns a copy of @var{string}.
(See also @code{opt-substring} below, if you don't want to copy
if not necessary.)
@c JP
@var{start}がゼロでかつ@var{end}が@var{N}の場合には、@var{string}のコ
ピーが返ります。
(不必要な時にコピーを避けたければ、下の@code{opt-substring}が使えます)。
@c COMMON

@c EN
Actually, extended @code{string-copy} explained below
is a superset of @code{substring}.  This procedure is
kept mostly for compatibility of R7RS programs.
See also @code{subseq} in @ref{Sequence framework},
for the generic version.
@c JP
実は後述する拡張された@code{string-copy}は@code{substring}のスーパーセッ
トになっています。この手続きの役割は主にR7RSとの互換性のためです。
@ref{Sequence framework}のジェネリック版@code{subseq}も参照してください。
@c COMMON
@end defun

@defun opt-substring string :optional start end
@c EN
Like @code{substring}, returns a part of @var{string} between
@var{start}-th character (inclusive) and @var{end}-th character (exclusive).
However, if the entire @var{string} is used (e.g. @var{start} is 0 and
@var{end} is the length of @var{string}, or the arguments are omitted, etc.),
@var{string} is returned as is, without copying.

This is a typical handling of optional @var{start}/@var{end} indexes
for many string utilities.   Note that using @code{substring} forces
copying the input string even when it's not necessary.

Besides exact integers, @code{#f} or @code{#<undef>} is allowed
as @var{start} and @var{end}, to indicate the argument is missing.
In that case, 0 is assumed for @var{start}, and
the length of @var{string} is assumed for @var{end}.
@c JP
@code{substring}と同様に、@var{string}の@var{start}番目の文字(含む)から
@var{end}番目の文字(含まない)までを切り取った文字列を返します。
ただし、入力文字列全てが使われる場合(@var{start}が0で@var{end}が入力文字列長だとか、
それらが省略された場合だとか)は、コピーせずに@var{string}がそのまま返されます。

これは、多くの文字列処理関数で省略可能な@var{start}/@var{end}引数を扱う場合に
共通する処理です。
@code{substring}を使うと必ず文字列がコピーされることに注意してください。

@var{start}/@var{end}引数には、正確な整数のほか、
該当する引数が省略されたことを示すために@code{#f}と@code{#<undef>}が許されます。
引数が省略された場合、@var{start}は0、@var{end}は@var{string}の長さが使われます。
@c COMMON
@end defun


@defun string-append string @dots{}
[R7RS base]
@c EN
Returns a newly allocated string whose content is concatenation of
@var{string} @dots{}.
@c JP
@var{string} @dots{}を連結した内容を含む文字列を新しくアロケートして返
します。
@c COMMON

@c EN
See also @code{string-concatenate} in @ref{SRFI-13 String reverse & append}.
@c JP
@ref{SRFI-13 String reverse & append}の@code{string-concatenate}も参照
してください。
@c COMMON
@end defun

@defun string->list string :optional start end
@defunx list->string list
[R7RS base]
@c EN
Converts a string to a list of characters or vice versa.
@c JP
文字列を文字のリストへ、またはその逆の変換をします。
@c COMMON

@c EN
You can give an optional start/end indexes to @code{string->list}.
@c JP
@code{string->list}にはオプショナル引数として開始、終了位置のインデッ
クスを渡せます。
@c COMMON

@c EN
For @code{list->string}, every elements of @var{list} must be
a character, or an error is signaled.  If you want to build
a string out of a mixed list of strings and characters, you
may want to use @code{tree->string} in @ref{Lazy text construction}.
@c JP
@code{list->string}では@var{list}の要素はすべて文字でなければなりません。
そうでなければ、エラーシグナルがあがります。文字列や文字がまざったリス
トから文字列を構成したい場合には@ref{Lazy text construction}にある
@code{tree->string}が使えます。
@c COMMON
@end defun

@defun string-copy string :optional start end
[R7RS base]
@c EN
Returns a copy of @var{string}.  You can give @var{start} and/or
@var{end} index to extract the part of the original string
(it makes @code{string-copy} a superset of @code{substring} effectively).
@c JP
@var{string}のコピーを返します。@var{start}および/あるいは@var{end}の
位置インデックスを渡すと元の文字列の部分文字列を取り出せます。
(したがって@code{string-copy}は事実上@code{substring}のスーパーセット
です)。
@c COMMON

@c EN
If only @var{start} argument is given, a substring beginning from
@var{start}-th character (inclusive) to the end of @var{string} is
returned.  If both @var{start} and @var{end} argument are given,
a substring from @var{start}-th character (inclusive) to
@var{end}-th character (exclusive) is returned.
See @code{substring} above for the condition that @var{start} and
@var{end} should satisfy.
@c JP
@var{start}引数のみを与えた場合には、部分文字列は@var{start}番目の文字
(これを含む)から@var{string}の最後までで、それが返ります。
@var{start}と@var{end}の両方を与えたときは、部分文字列は@var{start}番
目の文字(これを含む)から、@var{end}番目の文字(これを含まない)までで、
それが返ります。@var{start}と@var{end}が満すべき条件については
前述の@code{substring}の項を見てください。
@c COMMON

@c EN
Node: R7RS's destructive version @code{string-copy!} is provided
by @code{srfi.13} module (@pxref{String library}).
@c JP
註: R7RSの破壊的バージョン@code{string-copy!}は@code{srfi.13}モジュールで
提供されます (@ref{String library}参照)。
@c COMMON
@end defun

@defun string-copy-immutable string :optional start end
@c EN
If @var{string} is immutable, return it as is.  Otherwise, returns
an immutable copy of @var{string}.  It is a dual of @code{string-copy}
which always returns a mutable copy.

The optional @var{start} and @var{end} argument may be a nonnegative
integer character index and/or string cursors to restrict the range
of @var{string} to be copied.
@c JP
@var{string}が変更不可であればそれをそのまま返し、変更可能であれば
変更不可なコピーを返します。
@code{string-copy}が常に変更可能なコピーを返すのと対照的です。

@var{start}と@var{end}は非負整数の文字インデックスか文字列カーソルで、
@var{string}中のコピーされる範囲を指定します。
@c COMMON
@end defun


@defun string-fill! string char :optional start end
[R7RS base]
@c EN
Fills @var{string} by @var{char}.  Optional
@var{start} and @var{end} limits the effective area.
@c JP
@var{string} を @var{char} で埋めます。
オプションの @var{start} と @var{end} は、影響を受ける領域を
制限します。
@c COMMON
@example
(string-fill! "orange" #\X)
  @result{} "XXXXXX"
(string-fill! "orange" #\X 2 4)
  @result{} "orXXge"
@end example

@c EN
See the notes in @code{make-string} about performance consideration.
@c JP
パフォーマンス上の考慮点について、@code{make-string}の説明を参照して下さい。
@c COMMON
@end defun

@defun string-join strs :optional delim grammar
@c EN
[SRFI-13] Concatenate strings in the list @var{strs},
with a string @var{delim} as `glue'.

The argument @var{grammar} may be one of the following symbol
to specify how the strings are concatenated.
@c JP
[SRFI-13] リスト @var{strs} 中にある文字列を、文字列 @var{delim} を'糊'
として連結します。

引数 @var{grammar} は、文字列がどのように連結されるかを指定する
シンボルで、以下のうちの一つです。
@c COMMON
@table @code
@item infix
@c EN
Use @var{delim} between each string.  This mode is default.
Note that this mode introduce ambiguity when @var{strs}
is an empty string or a list with a null string.
@c JP
それぞれの文字列の間に @var{delim} を使います。このモードが
デフォルトです。@var{strs} が空文字列かヌル文字列を含むリスト
である場合は、曖昧に(適当に)動作します。
@c COMMON
@example
(string-join '("apple" "mango" "banana") ", ")
  @result{} "apple, mango, banana"
(string-join '() ":")
  @result{} ""
(string-join '("") ":")
  @result{} ""
@end example
@item strict-infix
@c EN
Works like @code{infix}, but empty list is not allowed to @var{strs},
thus avoiding ambiguity.
@c JP
@code{infix} のように動作しますが、@var{strs} には空リストは
許されません。したがって、曖昧さはありません。
@c COMMON
@item prefix
@c EN
Use @var{delim} before each string.
@c JP
@var{delim} をそれぞれの文字列の前に補います。
@c COMMON
@example
(string-join '("usr" "local" "bin") "/" 'prefix)
  @result{} "/usr/local/bin"
(string-join '() "/" 'prefix)
  @result{} ""
(string-join '("") "/" 'prefix)
  @result{} "/"
@end example
@item suffix
@c EN
Use @var{delim} after each string.
@c JP
@var{delim} をそれぞれの文字列の後ろに補います。
@c COMMON
@example
(string-join '("a" "b" "c") "&" 'suffix)
  @result{} "a&b&c&"
(string-join '() "&" 'suffix)
  @result{} ""
(string-join '("") "&" 'suffix)
  @result{} "&"
@end example
@end table
@end defun

@defun string-scan string item :optional return
@defunx string-scan-right string item :optional return
@c EN
Scan @var{item} (either a string or a character) in @var{string}.
While @code{string-scan} finds the leftmost match, @code{string-scan-right}
finds the rightmost match.
@c JP
@var{string} から @var{item} (文字列あるいは文字)を探します。
@code{string-scan}は最も左にある一致を、
@code{string-scan-right}は最も右にある一致を見つけます。
@c COMMON

@c EN
The @var{return} argument specifies what value should be returned
when @var{item} is found in @var{string}.  It must be one of the
following symbols.
@c JP
引数 @var{return} は、@var{string} 中に @var{item} が見つかった
場合にどの値が返されるかを指定します。それは以下のシンボルのうちの
一つでなければなりません。
@c COMMON

@table @code
@item index
@c EN
Returns the index in @var{string} if @var{item} is found, or @code{#f}.
This is the default behavior.
@c JP
@var{item} が見つかった場合は@var{string} 内でのインデックス、
そうでなければ @code{#f} を返します。これがデフォルトの振る舞いです。
@c COMMON
@example
(string-scan "abracadabra" "ada") @result{} 5
(string-scan "abracadabra" #\c) @result{} 4
(string-scan "abracadabra" "aba") @result{} #f
@end example
@item before
@c EN
Returns a substring of @var{string} before @var{item}, or
@code{#f} if @var{item} is not found.
@c JP
@var{item} よりも前にある @var{string} の部分文字列、あるいは
@var{item} が見つからなければ @code{#f} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'before) @result{} "abrac"
(string-scan "abracadabra" #\c 'before) @result{} "abra"
@end example
@item after
@c EN
Returns a substring of @var{string} after @var{item}, or
@code{#f} if @var{item} is not found.
@c JP
@var{item} より後ろにある @var{string} の部分文字列、あるいは
@var{item} が見つからなければ @code{#f} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'after) @result{} "bra"
(string-scan "abracadabra" #\c 'after) @result{} "adabra"
@end example
@item before*
@c EN
Returns a substring of @var{string} before @var{item}, and
the substring after it.  If @var{item} is not found, returns
@code{(values #f #f)}.
@c JP
@var{item} の前にある @var{string} の部分文字列と後ろにある
@var{string} の部分文字列を返します。@var{item} が見つからない場合は、
@code{(values #f #f)} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'before*)
  @result{} "abrac" @r{and} "adabra"
(string-scan "abracadabra" #\c 'before*)
  @result{} "abra" @r{and} "cadabra"
@end example
@item after*
@c EN
Returns a substring of @var{string} up to the end of @var{item},
and the rest.  If @var{item} is not found, returns
@code{(values #f #f)}.
@c JP
@var{string} のうち、@var{item} の終端までの部分文字列とその残りを
返します。@var{item} が見つからなかった場合は、@code{(values #f #f)}
を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'after*)
  @result{} "abracada" @r{and} "bra"
(string-scan "abracadabra" #\c 'after*)
  @result{} "abrac" @r{and} "adabra"
@end example
@item both
@c EN
Returns a substring of @var{string} before @var{item} and
after @var{item}.  If @var{item} is not found, returns
@code{(values #f #f)}.
@c JP
@var{string} のうち、@var{item} の前と @var{item} の後ろの
部分文字列を返します。@var{item} が見つからない場合、
@code{(values #f #f)} を返します。
@c COMMON
@example
(string-scan "abracadabra" "ada" 'both)
  @result{} "abrac" @r{and} "bra"
(string-scan "abracadabra" #\c 'both)
  @result{} "abra" @r{and} "adabra"
@end example
@end table
@end defun

@defun string-split string splitter :optional grammar limit start end
@defunx string-split string splitter :optional limit start end
[SRFI-152+]
@c EN
Splits @var{string} by @var{splitter} and returns a list of strings.
@var{splitter} can be a character, a character set, a string,
a regexp, or a procedure.

If @var{splitter} is a character or a string, it is
used as a delimiter.  Note that SRFI-152's @code{string-split}
only allows strings for @var{splitter} (it also interprets the first
optional argument as a grammar; see below for the compatibility note.)

If @var{splitter} is a character set, any consecutive characters
that are member of the character set are used as a delimiter.

If a procedure is given to @var{splitter}, it is called for each
character in @var{string}, and the consecutive characters that caused
@var{splitter} to return a true value are used as a delimiter.
@c JP
@var{string} を @var{splitter} で分割し、文字列のリストを返します。
@var{splitter} には、文字、文字集合、文字列、正規表現、手続きが
使えます。

@var{splitter} が文字か文字列の場合、それがそのままデリミタとして使われます。
なお、SRFI-152の@code{string-split}はデリミタとして文字列しか許しません。
(また、省略可能引数の最初のものは常に@var{grammar}として扱われます。
後述する互換性への註を参照)。

@var{splitter} が文字集合の場合は、その文字集合に含まれる文字の
連続がデリミタとして使われます。

@var{splitter} に手続きが与えられた場合、@var{string} にある各文字に
対してその手続きが呼ばれ、@var{splitter} が真の値を返すような連続した
文字群がデリミタとして使われます。
@c COMMON

@example
(string-split "/aa/bb//cc" #\/)    @result{} ("" "aa" "bb" "" "cc")
(string-split "/aa/bb//cc" "/")    @result{} ("" "aa" "bb" "" "cc")
(string-split "/aa/bb//cc" "//")   @result{} ("/aa/bb" "cc")
(string-split "/aa/bb//cc" #[/])   @result{} ("" "aa" "bb" "cc")
(string-split "/aa/bb//cc" #/\/+/) @result{} ("" "aa" "bb" "cc")
(string-split "/aa/bb//cc" #[\w])  @result{} ("/" "/" "//" "")
(string-split "/aa/bb//cc" char-alphabetic?) @result{} ("/" "/" "//" "")

;; some boundary cases
(string-split "abc" #\/) @result{} ("abc")
(string-split ""    #\/) @result{} ("")
@end example

@c EN
The @var{grammar} argument is the same as @code{string-join} above; it
must be one of symbols @code{infix}, @code{strict-infix}, @code{prefix}
or @code{suffix}.  When omitted, @code{infix} is assumed.
@c JP
@var{grammar}引数の意味は上の@code{string-join}と同じです。
シンボル@code{infix}、@code{strict-infix}、@code{prefix}、
@code{suffix}のいずれかでなければなりません。
省略時は@code{infix}が指定されたのと同じです。
@c COMMON

@example
(string-split "/a/b/c/" "/" 'infix)  @result{} ("" "a" "b" "c" "")
(string-split "/a/b/c/" "/" 'prefix) @result{} ("a" "b" "c" "")
(string-split "/a/b/c/" "/" 'suffix) @result{} ("" "a" "b" "c")
@end example

@c EN
In general, the following relationship holds:
@c JP
一般的に、以下の関係が成り立ちます。
@c COMMON

@example
(string-join XS DELIM GRAMMAR) @result{} S
(string-split S DELIM GRAMMAR) @result{} XS
@end example

@c EN
If @var{limit} is given and not @code{#f}, it must be a nonnegative
integer and specifies the maximum number of match to the @var{splitter}.
Once the limit is reached, the rest of string is included in the result
as is.
@c JP
@var{limit}引数が与えられた場合、それは@code{#f}か非負整数でなければなりません。
非負整数の場合は@var{splitter}がマッチするデリミタの最大数を指定します。
デリミタがその数だけ見つかったら、残りの文字列は分割されずにそのまま結果に含められます。
@c COMMON

@example
(string-split "a.b..c" "." 'infix 0)   @result{} ("a.b..c")
(string-split "a.b..c" "." 'infix 1)   @result{} ("a" "b..c")
(string-split "a.b..c" "." 'infix 2)   @result{} ("a" "b" ".c")
@end example

@c EN
Compatibility note:
The @var{grammar} argument is added for the consistency of srfis
(SRFI-130, SRFI-152, @pxref{String library (reduced)}).
However, for the backward compatibility and
the convenience, it also accepts @var{limit} without @var{grammar} argument;
it is distinguishable since @var{grammar} is a symbol and
@var{limit} is an integer.
For the code that's compatible to SRFI-152, use the first form that takes
@var{grammar} argument.
@c JP
互換性への註:
@var{grammar}引数はSRFI-130およびSRFI-152(@ref{String library (reduced)}参照)
との一貫性のために追加されました。
しかし、互換性および簡便性のため、@var{grammar}を省略して@var{limit}を与えることも
できます。@var{grammar}はシンボルで@var{limit}は整数なので判別可能です。
SRFI-152と互換性のあるコードを書く場合は@var{grammar}引数を取る最初の形式を使ってください。
@c COMMON

@example
(string-split "a.b..c" "." 2)   @result{} ("a" "b" ".c")
@end example

@c EN
The @var{start} and @var{end} arguments limits input string
in the given range before splitting.
@c JP
@var{start}と@var{end}引数は分割する前に入力文字列を指定の範囲に制限します。
@c COMMON

@c EN
See also @code{string-tokenize} in
(@pxref{SRFI-13 Other string operations}).
@c JP
@code{string-tokenize} (@ref{SRFI-13 Other string operations})
も参照して下さい。
@c COMMON
@end defun

@defun string-map proc str str2 @dots{}
@defunx string-map proc str :optional start end
[R7RS base][SRFI-13]
@c EN
Applies @var{proc} over each character in the input string, and
gathers the characters returned from @var{proc} into a string and
returns it.  It is an error if @var{proc} returns non-character.

Because of historical reasons, this procedure has two interfaces.
The first one takes one or more input strings, and @var{proc} receives
as many characters as the number of input strings, each character
being taken from each string.  Iteration stops on the shortest string.
This is defined in R7RS-small, and consistent with @code{map},
@code{vector-map}, etc.

The second one takes only one string argument, and optional start/end
arguments, which may be nonnegative integer indexes or string cursors
to limit the input range of the string.  This is defined in SRFI-13,
string library.

The order in which @var{proc} is applied is not guaranteed to be left to right.
You shouldn't depend on the order.

If @var{proc} saves a continuation and it is invoked later, the result
already returned from @code{string-map} won't be affected
(as specified in R7RS).
@c JP
入力文字列中の各文字に対して@var{proc}を適用し、その結果の文字を集めた
文字列を返します。@var{proc}は文字を返さねばなりません。

歴史的経緯により、この手続きは2種類のインタフェースを持ちます。
最初のインタフェースは1個以上の文字列を取ります。
@var{proc}には文字列引数の数だけ、各文字列から取られた文字が渡されます。
繰り返しは最も短い文字列でストップします。これはR7RS-smallで定義され、
@code{map}、@code{vector-map}等と一貫性があります。

二番目のインタフェースでは、文字列引数はひとつだけで、省略可能な@var{start}/@var{end}
引数を取ります。@var{start}と@var{end}は非負整数のインデックスか
文字列カーソルで、入力文字列を使う範囲を制限します。
この形式はSRFI-13で定義されています。

@var{proc}が適用される順序は左から右とは限りません。順序に依存しないようにしてください。

@var{proc}が継続を補足し、それが再び起動された場合、既に@code{string-map}から
返された結果は影響を受けません。(R7RSで指定されています)
@c COMMON

@example
(string-map char-upcase "apple") @result{} "APPLE"
(string-map (^[a b] (if (char>? a b) a b)) "orange" "apple") @result{} "orpng"
(string-map char-upcase "pineapple" 0 4) @result{} "PINE"
@end example
@end defun


@defun string-for-each proc str str2 @dots{}
@defunx string-for-each proc str :optional start end
[R7RS base][SRFI-13]
@c EN
Applies @var{proc} over each character in the input string in left-to-right
order.  The results of @var{proc} is discarded.

Because of historical reasons, this procedure has two interfaces,
first one defined in R7RS and second one defined in SRFI-13.
See @code{string-map} above for the explanation.
@c JP
@var{proc}を入力文字列の各文字に左から右の順で適用します。@var{proc}の結果は捨てられます。

歴史的経緯から、この手続きは2種類のインタフェースを持ちます。
最初のインタフェースはR7RSで、二番目のインタフェースはSRFI-13で定義されています。
詳しくは上の@code{string-map}の項を参照してください。
@c COMMON
@end defun


@node Incomplete strings,  , String utilities, Strings
@subsection Incomplete strings
@c NODE 不完全文字列

@c EN
A string can be flagged as "incomplete" if it may contain
byte sequences that do not consist of a valid multibyte character
in the Gauche's native encoding.
@c JP
Gaucheの内部エンコーディングで正当なマルチバイト文字で構成されていない
ようなバイト列を含む文字列は「不完全文字列」となります。
@c COMMON

@c EN
Incomplete strings may be generated in several circumstances;
reading binary data as a string, reading a string data that has
been 'chopped' in middle of a multibyte character, or
concatenating a string with other incomplete strings, for example.
@c JP
不完全文字列が生成される状況はいくつかあります。たとえば、バイナリデー
タを文字列として読み込んだとき、マルチバイト文字の途中で切れた文字列を
読み込んだとき、別の不完全文字列が連結された場合などです。
@c COMMON

@c EN
Incomplete strings should be regarded as an exceptional case.
It used to be a way to handle byte strings, but now we have
u8vector (@pxref{Uniform vectors}) for that purpose.
In fact, we're planning to remove it in the future releases.
@c JP
不完全文字列は例外的な状況であるとみなすべきです。以前はバイト列を処理するのに
不完全文字列が使われていましたが、
現在はu8vector (@ref{Uniform vectors}参照)を使うことができるので、
将来のリリースでは削除する計画です。
@c COMMON

@c EN
Just in case, if you happen to get an incomplete string,
you can convert it to a complete string by @code{string-incomplete->complete}.
@c JP
万が一、不完全文字列に出会ってしまったら
@code{string-incomplete->complete}で完全な文字列に変換することができます。
@c COMMON

@deftp {Reader Syntax} @code{#**"}@dots{}@code{"}
@lxindex #**
@c EN
Denotes incomplete string.  The same escape sequences as the complete
string syntax are recognized.
@c JP
不完全な文字列のリテラル表記です。完全な文字列と同様のエスケープシーケンスが
使えます。
@c COMMON

@c EN
Rationale of the syntax: @code{#*} is used for bit vectors.
Since an incomplete strings is really a byte vector,
it has similarity.
@c JP
@code{#*} という構文はCommon Lispでビットベクタの表記に使われています。
不完全な文字列は実際はバイトベクタであることから、類似点を認めてこの構文を
採用しました。
@c COMMON

@c EN
Note: We used @code{#*"...."} for an incomplete string on 0.9.9 and
before.  It turned out that it couldn't coexist with bitvectors, for
@code{#*} is a valid bitvector literal (zero-length vector), and
@code{"} is a delimiter, so @code{#*"...."} can be parsed as
a zero-length bitvector followed by a string.  From 0.9.10, we changed
the incomplete string literal to @code{#**"..."}.  It's a bit lengthy,
but incomplete strings are anomalies and shouldn't be used often anyway.

For the backward compatibility, @code{#*"..."} is still read as an
incomplete string literal, unless the reader lexical mode
is @code{strict-r7} (@pxref{Reader lexical mode}, for the details).
If the reader lexical mode is @code{warn-legacy}, it is read as
an incomplete string, but a warning is issued.
If the mode is @code{strict-r7}, it is read as a zero-length
bitvector followed by a string.

In future releasers, @code{#*"..."} would be warned by default,
and later we'll gradually move to @code{strict-r7} behavior.
@c JP
註: 0.9.9までは、不完全文字列リテラルとして@code{#*"..."}を使っていました。
しかし、それはビットベクタリテラルと共存できないことが判明しました。
@code{#*}は有効なビットベクタリテラル(長さ0のビットベクタ)で、
また@code{"}はデリミタなので、@code{#*"...."}は長さ0のビットベクタと
通常の文字列、とパーズできてしまいます。
0.9.10からは、不完全文字列リテラルは@code{#**"..."}になりました。
ちょっと長いですが、もともと不完全文字列は例外的に現れるもので、
積極的に使うべきではありません。

後方互換性のため、デフォルトでは@code{#*"..."}はリーダー字句モードが
@code{strict-r7}でない限りは不完全文字列リテラルとして読まれます。
(リーダー字句モードについては@ref{Reader lexical mode}参照。)
リーダ字句モードが@code{warn-legacy}だった場合は、
このリテラルは不完全文字列として読まれますが、警告が出されます。
リーダ字句モードが@code{strict-r7}であれば、
このリテラルは長さ0のビットベクタと、通常の文字列として読まれます。

将来のリリースでは、デフォルトで@code{#*"..."}は警告を出すようにし、
その後@code{strict-r7}の振る舞いに移行する予定です。
@c COMMON
@end deftp


@defun string-incomplete->complete str :optional handling filler
@c EN
Reinterpret the content of an incomplete string @var{str}
and returns a newly created complete string from it.
@c JP
不完全文字列@var{str}の内容を再解釈して、あらたに完全文字列を返します。
@c COMMON
@c EN
The @var{handling} argument specifies how to handle the illegal
byte sequences in @var{str}.
@c JP
@var{handling}引数で@var{str}中の不正なバイト列の扱いかたを指定します。
@c COMMON
@table @asis
@item @code{#f}
@c EN
If @var{str} contains an illegal byte sequence, give up the
conversion and returns @code{#f}.  This is the default behavior.
@c JP
@var{str}が不正なバイト列を含んでいる場合、変換を諦めて@code{#f}を返し
ます。これがデフォルトのふるまいです。
@c COMMON
@item @code{:omit}
@c EN
Omit any illegal byte sequences.
@c JP
不正なバイト列を捨てます。
@c COMMON
@c EN
@item @code{:replace}
Replace each byte in illegal byte sequences by a character given
in @var{filler} argument, defaulted to @code{?}.
@c JP
@item 1文字
不正なバイト列中の各バイトを、@var{filler}引数に与えられ文字で置き換えます。
@var{filler}引数のデフォルトは@code{?}です。
@c COMMON
@c EN
@item @code{:escape}
Replace each byte in illegal byte sequences by a sequence of
@var{filler} @code{<hexdigit>} @code{<hexdigit>}.
Besides, the @var{filler} characters in the original string is replaced with
@var{filler} @var{filler}.
@c JP
@item @code{:escape}
不正なバイト列中の各バイトを、@var{filler} @code{<hexdigit>} @code{<hexdigit>}
の3文字で置き換えます。さらに、元文字列中に@var{filler}が登場した場合はそれぞれを
@var{filler} @var{filler} で置き換えます。
@c COMMON
@end table

@c EN
If @var{str} is already a complete string, its copy is returned.
@c JP
@var{str}が完全文字列なら、そのコピーが返されます。
@c COMMON

@c EN
The procedure always returns a complete string, except when
the @var{handling} argument is @code{#f} (default) and the input is an
incomplete string, in which case @code{#f} is returned.
@c JP
この手続きは、@var{handling}引数が@code{#f} (デフォルト) で入力が
不完全文字列だった場合に@code{#f}を返す以外は、常に完全文字列を返します。
@c COMMON

@example
(string-incomplete->complete #**"_abc")
  @result{} "_abc"     ; can be represented as a complete string

(string-incomplete->complete #**"_ab\x80;c")
  @result{} #f        ; can't be represented as a complete string

(string-incomplete->complete #**"_ab\x80;c" :omit)
  @result{} "_abc"     ; omit the illegal bytes

(string-incomplete->complete #**"_ab\x80;c" :replace #\_)
  @result{} "_ab_c"    ; replace the illegal bytes

(string-incomplete->complete #**"_ab\x80;c" :escape #\_)
  @result{} "__ab_80c" ; escape the illegal bytes and escape char itself
@end example
@end defun

@c ----------------------------------------------------------------------
@node Regular expressions, Vector family, Strings, Core library
@section Regular expressions
@c NODE 正規表現

@c EN
Gauche has a built-in regular expression engine which is mostly
upper-compatible of POSIX extended regular expression, plus
some extensions from Perl 5 regexp.

A special syntax is provided for literal regular expressions.
Also regular expressions are applicable, that is,
it works like procedures that match the given string to itself.
Combining with these two features enables writing some
string matching idioms compact.
@c JP
GaucheはPOSIXの拡張正規表現にほぼ上位互換で、さらに
Perl 5の正規表現から拡張機能を採り入れた正規表現エンジンを持っています。
Gaucheはまた、リテラル正規表現用の構文を備えています。

正規表現用のリテラル構文が用意されており、
また、正規表現オブジェクトは適用可能、つまり文字列に対して
手続きのように振る舞い、自分自身にマッチするかどうかを判定できるようになっています。
この二つの機能によって、文字列のマッチをスキャンするようなイディオムを
簡潔に書けるようになっています。
@c COMMON

@example
(find #/pattern/ list-of-strings)
  @result{} @i{match object} or #f
@end example

@menu
* Regular expression syntax::
* Using regular expressions::
* Inspecting and assembling regular expressions::
@end menu

@node Regular expression syntax, Using regular expressions, Regular expressions, Regular expressions
@subsection Regular expression syntax
@c NODE 正規表現の構文

@deftp {Reader Syntax} @code{#/@i{regexp-spec}/}
@deftpx {Reader Syntax} @code{#/@i{regexp-spec}/i}
@lxindex #/
@c EN
Denotes literal regular expression object.  When read, it becomes
an instance of @code{<regexp>}.
@c JP
リテラルの正規表現オブジェクトを表記します。読まれた際に@code{<regexp>}の
インスタンスとなります。
@c COMMON

@c EN
If a letter '@code{i}' is given at the end, the created regexp
becomes @emph{case-folding regexp}, i.e. it matches in the case-insensitive
way.
@c JP
末尾に文字@code{i}が与えられた場合は、マッチ時に大文字小文字を区別しない
正規表現オブジェクトとなります。
@c COMMON

@c EN
The advantage of using this syntax over @code{string->regexp} is
that the regexp is compiled only once.  You can use literal regexp
inside loop without worrying about regexp compilation overhead.
If you want to construct regexp on-the-fly, however, use @code{string->regexp}.
@c JP
@code{string->regexp}に対してこの構文を使う利点は、
正規表現のコンパイルが一度しか行われない点です。この構文は、
内部ループの中でも、正規表現のコンパイルのオーバヘッドを気にせずに
使うことができます。動的に正規表現を作成したい場合のみ@code{string->regexp}を
使って下さい。
@c COMMON
@end deftp

@c EN
Gauche's built-in regexp syntax follows POSIX extended regular
expression, with a bit of extensions taken from Perl.
(Scheme Regulare Expression (SRE) is also supported as an alternative
syntax; @pxref{R7RS regular expressions}, for the details of SRE.)
@c JP
Gaucheの組み込み正規表現構文はPOSIX拡張正規表現に準じたものに、
Perlの拡張の一部を採り入れたものです。
(別構文として、Scheme正規表現(SRE)もサポートされています。
SREについては@ref{R7RS regular expressions}を参照してください。)
@c COMMON

@table @code
@item @i{re}*
@c EN
Matches zero or more repetition of @i{re}.
@c JP
@i{re}の0回以上の繰り返しにマッチします。
@c COMMON

@item @i{re}+
@c EN
Matches one or more repetition of @i{re}.
@c JP
@i{re}の1回以上の繰り返しにマッチします。
@c COMMON

@item @i{re}?
@c EN
Matches zero or one occurrence of @i{re}.
@c JP
@i{re}の0回または1回の出現にマッチします。
@c COMMON

@item @i{re}@{@i{n}@}
@itemx @i{re}@{@i{n},@i{m}@}
@c EN
Bounded repetition.  @code{@i{re}@{@i{n}@}} matches exactly @i{n}
occurrences of @i{re}.
@code{@i{re}@{@i{n},@i{m}@}} matches at least @var{n} and at most
@var{m} occurrences of @i{re}, where @var{n} <= @var{m}.
In the latter form, either @var{n} or @var{m} can be omitted; omitted @var{n}
is assumed as 0, and omitted @var{m} is assumed infinity.
@c JP
回数に範囲のある繰り返しです。
@code{@i{re}@{@i{n}@}}は@i{re}の@i{n}回の繰り返しにマッチします。
@code{@i{re}@{@i{n},@i{m}@}}は@i{re}の@i{n}回以上、@i{m}回以下の
繰り返しにマッチします。但し@var{n} <= @var{m}とします。
2番目の形式では@var{n}か@var{m}のどちらかを省略することが
できます。@var{n}が省略された場合は0とみなされます。
@var{m}が省略された場合は無限大とみなされます。
@c COMMON

@item @i{re}*?
@itemx @i{re}+?
@itemx @i{re}??
@itemx @i{re}@{@i{n},@i{m}@}?
@c EN
Same as the above repetition construct, but these syntaxes
use "non-greedy" or "lazy" match strategy.  That is, they try to match
the minimum number of occurrences of @i{re} first, then retry
longer ones only if it fails.  In the last form
either @var{n} or @var{m} can be omitted.
Compare the following examples:
@c JP
上記の繰り返し構造とほぼ同じですが、これらの構文は「non-greedy」または
「lazy」と呼ばれるマッチ戦略を用います。すなわち、まず@i{re}がマッチする
最小の回数を試し、それが失敗したら順に繰り返しの回数を増やしてゆきます。
最後の形式では@var{n}か@var{m}のどちらかは省略できます。
次の例を比べてみてください：
@c COMMON

@example
(rxmatch-substring (#/<.*>/ "<tag1><tag2><tag3>") 0)
  @result{} "<tag1><tag2><tag3>"

(rxmatch-substring (#/<.*?>/ "<tag1><tag2><tag3>") 0)
  @result{} "<tag1>"
@end example

@item (@i{re}@dots{})
@c EN
Clustering with capturing.  The regular expression enclosed
by parenthesis works as a single @i{re}.  Besides, the string
that matches @i{re} @dots{} is saved as a @emph{submatch}.
@c JP
捕捉クラスタリング。括弧でくくられた正規表現の列がグループとして
扱われ、またそれにマッチした文字列はサブマッチとして保存されます。
@c COMMON

@item (?:@i{re}@dots{})
@c EN
Clustering without capturing.   @code{@i{re} @dots{}} works as
a single @i{re}, but the matched string isn't saved.
@c JP
捕捉無しクラスタリング。@code{@i{re} @dots{}}はグループとして
扱われますが、サブマッチとして保存されません。
@c COMMON

@item (?<@i{name}>@i{re}@dots{})
@c EN
Named capture and clustering.  Like @code{(@i{re}@dots{})},
but adds the name @i{name} to the matched substring.
You can refer to the matched substring by both index number
and the name.

When the same name appears more than once in a regular
expression, it is undefined which matched substring is
returned as the submatch of the named capture.
@c JP
名前つきの捕捉とクラスタリング。@code{(@i{re}@dots{})}と同様ですが、
マッチした文字列に名前@i{name}がつけられます。マッチした文字列には
インデックスの数字と名前のどちらでも参照できます。

同じ名前が複数回正規表現内に出現した場合、どの名前付き捕捉にマッチした
部分文字列が返されるかは不定です。
@c COMMON

@item (?i:@i{re}@dots{})
@itemx (?-i:@i{re}@dots{})
@c EN
Lexical case sensitivity control.
@code{(?i:@i{re}@dots{})} makes @i{re}@dots{} matches case-insensitively,
while @code{(?-i:@i{re}@dots{})} makes
@i{re}@dots{} matches case-sensitively.

Perl's regexp allows several more flags to appear between '?' and ':'.
Gauche only supports above two, for now.
@c JP
大文字小文字の区別の制御。
@code{(?i:@i{re}@dots{})}は@i{re}@dots{}が大文字小文字にかかわらず
マッチするようにします。
@code{(?-i:@i{re}@dots{})}はその逆です。

Perlの正規表現では'?'と':'の間に他のいくつかのフラグを使うことが
できますが、Gaucheでは今のところこのフラグのみをサポートしています。
@c COMMON

@item @i{pattern1}|@i{pattern2}|@dots{}
@c EN
Alternation.  Matches either one of patterns, where each
pattern is @i{re} @dots{}.
@c JP
パターンのいずれかにマッチします。
@c COMMON

@item \@i{n}
@c EN
Backreference.  @i{n} is an integer.
Matches the substring captured by the @i{n}-th capturing group.
(counting from 1).  When capturing groups are nested, groups
are counted by their beginnings.
If the @i{n}-th capturing group is in a repetition and has matched
more than once, the last matched substring is used.
@c JP
バックリファレンス。@i{n}は整数です。
@i{n}番目(1から数える)の捕捉カッコに捕捉された文字列と一致する場合に、\@i{n}が
マッチします。補足カッコがネストしている場合、開きカッコの順番で数えます。
@i{n}番目のカッコが繰り返しの中にあり、複数回マッチ
している場合は、最後にマッチした文字列との比較が行われます。
@c COMMON

@item \k<@i{name}>
@c EN
Named backreference.  Matches the substring captured by
the capturing group with the name @i{name}.
If the named capturing group is in a repetition and has matched
more than once, the last matched substring is used.
If there are more than one capturing group with @i{name},
matching will succeed if the input matches either one of the substrings
captured by those groups.
@c JP
名前によるバックリファレンス。
名前@i{name}を持つ捕捉カッコで捕捉された文字列と一致する場合に、
\k<@i{name}>がマッチします。参照しているカッコが繰り返しの中にあり、
複数回マッチしている場合は、最後にマッチした文字列との比較が行わ
れます。同じ名前@i{name}を持つ捕捉カッコが複数ある場合には、
それらのカッコの最後にマッチした文字列のいずれかと一致する場合、
マッチが成功します。
@c COMMON

@item .
@c EN
Matches any character (including newline).
@c JP
任意の1文字にマッチします。改行文字にもマッチします。
@c COMMON

@item [@i{char-set-spec}]
@c EN
Matches any of the character set specified by @i{char-set-spec}.
@xref{Character sets}, for the details of @i{char-set-spec}.
@c JP
@i{char-set-spec}で指定される文字集合内の文字にマッチします。
@i{char-set-spec}については@ref{Character sets}を参照して下さい。
@c COMMON

@item \s, \d, \w
@c EN
Matches a whitespace character (@code{char-set:ascii-whitespace},
@code{#[\u0009-\u000d ]}),
a digit character(@code{char-set:ascii-digit}, @code{#[0-9])}, or
a word-constituent character (@code{char-set:ascii-word}, @code{#[A-Za-z0-9_]}),
respectively.
Note that they don't include characters outside ASCII range.

Can be used both inside and outside of character set.
@c JP
それぞれ空白文字(@code{char-set:ascii-whitespace},
@code{#[\u0009-\u000d ]})、
数字(@code{char-set:ascii-digit}, @code{#[0-9])}、
単語を構成する文字(@code{char-set:ascii-word}, @code{#[A-Za-z0-9_]})にマッチします。
ASCIIの外の文字は含まれないことに注意してください。

文字集合内でも、その外でも使えます。
@c COMMON

@item \S, \D, \W
@c EN
Matches the complement character set of @code{\s}, @code{\d} and
@code{\w}, respectively.
@c JP
それぞれ@code{\s}、@code{\d}、@code{\w}で指定される文字集合の補集合の
文字にマッチします。
@c COMMON

@item ^, $
@c EN
Beginning and end of string assertion, when appears at the beginning
or end of the pattern, or optionally, beginning and end of line in
multi-line mode.
@c JP
それぞれ、パターンの最初または最後に指定された場合、
文字列の最初か最後にマッチします。
@c COMMON

@c EN
These characters loses special meanings and matches the characters
themselves if they appear in the position
other than the beginning of the pattern (for @code{^}) or the end
(for @code{$}).  For the sake of recognizing those characters,
lookahead/lookbehind
assertions (@code{(?=...)}, @code{(?!...)}, @code{(?<=...)},
@code{(?<!...)}) and atomic clustering (@code{(?>...)}) are
treated as if they are a whole pattern.  That is, @code{^} at the
beginning of those groupings are beginning-of-string assertion
no matter where these group appear in the containing regexp.
So as @code{$} at the end of these groupings.
@c JP
これらの文字は、パターンの最初(@code{^}の場合)か最後(@code{$}の場合)に
現れた時のみ特別な意味を持ち、それ以外の場所ではこれらの文字自身にマッチします。
これらの文字を特殊文字と認識する段階では、肯定および否定の先読み
(@code{(?=...)}, @code{(?!...)}, @code{(?<=...)}, @code{(?<!...)})と
アトミックなクラスタリング(@code{(?>...)})はあたかもそれが独立した
パターンであるかのように扱われます。つまり、@code{^}がこれらの構造の先頭に現れた
場合は、これらの構造が全体の正規表現中のどこにあるかには関わらず、文字列先頭への
マッチとみなされます。@code{$}がこれらの構造の末尾に現れたば場合も同様です。
@c COMMON

@item \b, \B
@c EN
Word boundary and non word boundary assertion, respectively.
That is, @code{\b} matches an empty string between
word-constituent character and non-word-constituent character,
and @code{\B} matches an empty string elsewhere.
@c JP
@code{\b}は単語の境界の空文字列にマッチします。
@code{\B}はその逆です。
@c COMMON

@item \;
@itemx \"
@itemx \#
@c EN
These are the same as @code{;}, @code{"}, and @code{#}, respectively,
and can be used to avoid confusing Emacs or other syntax-aware editors
that are not familiar with Gauche's extension.
@c JP
これらはそれぞれ@code{;}、@code{"}、および@code{#}と同じです。
Emacs等、Scheme構文を理解するエディタを混乱させないために使うことができます。
@c COMMON

@item (?=@i{pattern})
@itemx (?!@i{pattern})
@c EN
Positive/negative lookahead assertion.
Match succeeds if @i{pattern} matches (or does not match)
the input string from the current position, but this doesn't
move the current position itself, so that the following
regular expression is applied again from the current position.

For example, the following expression matches strings
that might be a phone number, except the numbers in Japan
(i.e. ones that begin with "81").
@c JP
肯定および否定の先読み。
@i{pattern}が文字列の現在の位置にマッチする(あるいはマッチ
しない)ときにマッチが成功しますが、現在の位置は変更しない
ので、後に続く正規表現は現在と同じ位置から適用されます。

例えば、次の表現は、電話番号のうち日本の番号("81"から始まるもの)
を除く文字列にマッチします。
@c COMMON

@example
\+(?!81)\d@{9,@}
@end example

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
@c EN
Positive/negative lookbehind assertion.
If the input string immediately before the current
input position matches @var{pattern}, this pattern
succeeds or fails, respectively.   Like lookahead
assertion, the input position isn't changed.

Internally, this match is tried by reversing
@var{pattern} and applies it to the backward
of input character sequence.  So you can
write any regexp in @var{pattern}, but if the
submatches depend on the matching order,
you may get different submatches from when
you match @var{pattern} from left to right.
@c JP
肯定および否定の後読み。
現在の位置の左側に@var{pattern}にマッチする文字列がある場合に
マッチが成功(あるいは失敗)します。先読みと同様、現在の位置は
変更しません。

内部的にこの表現は、@i{pattern}を逆転させたうえで、現在の位置
から左に向かってマッチを進めることで実現されています。したがって、
@i{pattern}には任意のものにマッチする表現を含めることができますが、
マッチの順番や長さが重要な場合(例えば2通りにマッチしうる捕捉の
カッコ)などは、左から右に現在位置が進むときとは異なる場所に
マッチするかもしれません。
@c COMMON

@item (?>@i{pattern})
@c EN
Atomic clustering.  Once @i{pattern} matches,
the match is fixed; even if the following pattern fails,
the engine won't backtrack to try the
alternative match in @i{pattern}.
@c JP
アトミックなクラスタリング。@i{pattern}がいったんマッチすると、
そのマッチは確定します。後続のパターンが失敗した場合でも、
@i{pattern}内にバックトラックして他のマッチが試みられることはありません。
@c COMMON

@item @i{re}*+
@itemx @i{re}++
@itemx @i{re}?+
@c EN
They are the same as (?>@i{re}*), (?>@i{re}+), (?>@i{re}?), respectively.
@c JP
それぞれ(?>@i{re}*)、(?>@i{re}+)、(?>@i{re}?)と同じです。
@c COMMON

@item (?@i{test-pattern} @i{then-pattern})
@itemx (?@i{test-pattern} @i{then-pattern}|@i{else-pattern})
@c EN
Conditional matching.   If @var{test-pattern} counts
true, @var{then-pattern} is tried; otherwise
@var{else-pattern} is tried when provided.

@var{test-pattern} can be either one of the following:

@table @code
@item (@i{integer})
Backreference.  If @var{integer}-th capturing group has a match,
this test counts true.

@item (?=@i{pattern})
@itemx (?!@i{pattern})
Positive/negative lookahead assertion.  It tries @var{pattern}
from the current input position without consuming input,
and if the match succeeds or fails, respectively, this
test counts true.

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
Positive/negative lookbehind assertion.  It tries @var{pattern}
backward from the left size of the current input position,
and if the match succeeds or fails, respectively, this
test counts true.
@end table
@c JP
条件つきマッチング。@var{test-pattern}が成功すれば
@var{then-pattern}へと、そうでなければ
@var{else-pattern}へと(もしあれば)マッチを進めます。

@var{test-pattern}には以下の形式が書けます。

@table @code
@item (@i{integer})
バックリファレンス。@var{integer}番目の捕捉クラスタリングのマッチに
成功していた場合に成功となります。

@item (?=@i{pattern})
@itemx (?!@i{pattern})
肯定および否定の先読み。入力の現在位置から、入力を消費することなく
@var{pattern}のマッチを試み、それがそれぞれ成功もしくは失敗した
場合に、この@var{test-pattern}を成功とみなします。

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
肯定および否定の後読み。入力の現在位置から左側に向かって、
@var{pattern}の逆向きにマッチを試みます、
それがそれぞれ成功もしくは失敗した場合に、
この@var{test-pattern}を成功とみなします。
@end table
@c COMMON
@end table

@node Using regular expressions, Inspecting and assembling regular expressions, Regular expression syntax, Regular expressions
@subsection Using regular expressions
@c NODE 正規表現を使う

@c EN
@subsubheading Regexp object and rxmatch object
@c JP
@subsubheading Regexpオブジェクトとrxmatchオブジェクト
@c COMMON

@deftp {Builtin Class} <regexp>
@clindex regexp
@c EN
Regular expression object.  You can construct a regexp object
from a string by @code{string->regexp} or @code{sre->regexp}
at run time.  Gauche also
has a special syntax to denote regexp literals, which construct
regexp object at loading time.

Gauche's regexp engine is fully aware of multibyte characters.
@c JP
正規表現オブジェクトのクラスです。@code{string->regexp}
あるいは@code{sre->regexp}を使って実行時に作成できます。
また、Gaucheはリテラルの正規表現を表す構文を持っており、
ロード時に作成することもできます。

Gaucheの正規表現エンジンはマルチバイト文字列に対応しています。
@c COMMON
@end deftp

@deftp {Builtin Class} <regmatch>
@clindex regmatch
@c EN
Regexp match object.  A regexp matcher @code{rxmatch} returns
this object if match.  This object contains all the information
about the match, including submatches.

The advantage of using match object, rather than substrings or
list of indices, is efficiency.  The regmatch object keeps internal
state of match, and computes indices and/or substrings only when
requested.  This is particularly effective for multibyte strings,
for index access is slow on them.
@c JP
正規表現マッチオブジェクトのクラスです。正規表現エンジン@code{rxmatch}は、
一致した場合にこのオブジェクトを返します。部分一致の情報を含めた
全てのマッチに関する情報がこのオブジェクトに含まれています。

一致した部分文字列やそのインデックスのリストではなく
マッチオブジェクトを返すことの利点は効率です。
regmatchオブジェクトはマッチの内部状態を保持しており、
要求された時にはじめて該当する部分文字列やインデックスを計算します。
これは特にマルチバイト文字列に有効です。マルチバイト文字列
へのインデックスアクセスは遅いからです。
@c COMMON
@end deftp

@defun string->regexp string :key case-fold multi-line
@c EN
Takes @var{string} as a regexp specification, and constructs
an instance of @code{<regexp>} object.
@c JP
文字列@var{string}を正規表現とみなして、@code{<regexp>}のインスタンスを
作成して返します。
@c COMMON

@c EN
If a true value is given to the keyword argument @var{case-fold},
the created regexp object becomes case-folding regexp.
(See the above explanation about case-folding regexp).
@c JP
キーワード引数@var{case-fold}に真の値が与えられた場合、作成される正規表現は
大文字小文字を区別しないものとなります。
(大文字小文字を区別しない正規表現に関しては上の説明を参照して下さい)。
@c COMMON

@c EN
If a true value is given to the keyword argument @var{multi-line},
@code{^} and @code{$} will assert the beginning and end of line in
addition to beginning and end of string. Popular line terminators (LF
only, CRLF and CR only) are recognized.
@c JP
キーワード引数@var{multi-line}に真の値が与えられた場合、
@code{^}と@code{$}はそれぞれ入力文字列の最初と最後に加え、
各行の先頭と末尾にもマッチします。
行の区切りはLFのみ、CRLF、あるいはCRのみのいずれも認識されます。
@c COMMON
@end defun

@defun sre->regexp sre :key multi-line
@c EN
Takes a scheme regexp @var{sre} and returns a @code{<regexp>} object. The
zero-th group is always captured.

If a false value is given to the keyword argument @var{multi-line},
which is the default,
@code{bol} and @code{eol} behave like @code{bos} and @code{eos}
(i.e. only match at the beginning or end of string).
@c JP
Scheme正規表現 @var{sre} を取り、コンパイルした@code{<regexp>}オブジェクトを
返します。正規表現全体が常に0番の捕捉グループになります。

キーワード引数@var{multi-line}に偽の値が与えられた場合
(デフォルト)、@code{bol}と@code{eol}はそれぞれ@code{bos}と@code{eos}のように
振る舞います (つまり、入力文字列の最初と最後にのみマッチします)。
@c COMMON
@end defun

@defun regexp? @var{obj}
@c EN
Returns true iff @var{obj} is a regexp object.
@c JP
@var{obj}が正規表現オブジェクトなら真の値を返します。
@c COMMON
@end defun

@defun regexp->string @var{regexp}
@c EN
Returns a source string describing the regexp @var{regexp}.
The returned string is immutable.
@c JP
正規表現@var{regexp}を記述する元になった文字列を返します。
返される文字列は変更不可な文字列です。
@c COMMON
@end defun

@defun regexp->sre @var{regexp}
@c EN
Returns a scheme regexp (SRE) describing the regexp @var{regexp}.
@xref{R7RS regular expressions}, for the details of SRE.
@c JP
正規表現@var{regexp}を生成するScheme正規表現式(SRE)を返します。
SREについて詳しくは@ref{R7RS regular expressions}を参照してください。
@c COMMON
@end defun

@defun regexp-num-groups regexp
@defunx regexp-named-groups regexp
@c EN
Queries the number of capturing groups, and an alist of named capturing
groups, in the given @var{regexp}, respectively.

The number of capturing groups corresponds to the number of matches
returned by @code{rxmatch-num-matches}.  Note that the entire regexp
forms a group, so the number is always positive.

The alist returned from @code{regexp-named-groups} has the group name
(symbol) in @code{car}, and its subgroup number in @code{cdr}.
Note that the order of groups in the alist isn't fixed.
@c JP
正規表現@var{regexp}中の、捕捉グループ(サブマッチに使われるグループ)の総数、
及び名前つき捕捉グループのalistをそれぞれ返します。

捕捉グループの総数は、この正規表現でマッチした場合のマッチオブジェクトの
@code{rxmatch-num-matches}と同じになります。正規表現全体もひとつのグループだと
みなされるので、総数は常に1以上です。

@code{regexp-named-groups}から返されるalistは
@code{car}に名前(シンボル)、@code{cdr}にそのサブマッチ番号を持つペアを
要素とします。alist内でのグループの順番は不定です。
@c COMMON

@example
(regexp-num-groups #/abc(?<foo>def)(ghi(?<bar>jkl)(mno))/)
  @result{} 5
(regexp-named-groups #/abc(?<foo>def)(ghi(?<bar>jkl)(mno))/)
  @result{} ((bar . 3) (foo . 1))
@end example
@end defun


@c EN
@subsubheading Trying a match
@c JP
@subsubheading マッチを試みる
@c COMMON

@defun rxmatch regexp string :optional start end
@c EN
@var{Regexp} is a regular expression object.
A string @var{string} is matched by
@var{regexp}.  If it matches, the function returns a @code{<regmatch>}
object.  Otherwise it returns @code{#f}.
@c JP
正規表現オブジェクト@var{regexp}に一致するものを文字列@var{string}から
探します。一致が見付かった場合は@code{<regmatch>}オブジェクトを返し、
見付からなかった場合は@code{#f}を返します。
@c COMMON

@c EN
If @var{start} and/or @var{end} can be integer indexes or string
cursors on @var{string}.  If given, only the substring between
@var{start} (inclusive) and @var{end} (exclusive) is searched.
@c JP
@var{start}と@var{end}は@var{string}に対する整数インデックスか
文字列カーソルで、与えられた場合は
@var{string}のうち@var{start}(含む)から@var{end}(含まない)までの
部分文字列が検索対象になります。
@c COMMON

@c EN
This is called @code{match}, @code{regexp-search} or @code{string-match}
in some other Scheme implementations.
@c JP
他のScheme処理系ではこれは
@code{match}、@code{regexp-search}、@code{string-match}など
様々な名で呼ばれています。
@c COMMON

@c EN
Internally, Gauche uses backtracking for regexp match.
When regexp has multiple match possibilities, Gauche saves
an intermediate result in a stack and try one choice, and if it fails
try another.  Depending on regexp, the saved results may grow linear
to the input.  Gauche allocates a fixed amount of memory for that,
and if there are too many saved results, you'll get the following
error:
@c JP
内部的に、Gaucheは正規表現のマッチにバックトラックを使っています。
複数のマッチの可能性がある場合、その時点の状態をスタックにセーブして一つの可能性を試し、
だめだったら戻ってもう一つの可能性を試します。正規表現によっては、
セーブする状態が入力の大きさに比例してしまう場合があります。
セーブする状態が大きくなりすぎると、次のエラーが投げられます。
@c COMMON

@example
ERROR: Ran out of stack during matching regexp #/.../. Too many retries?
@end example

@c EN
If you get this error, consider using hybrid parsing approach.
Our regexp engine isn't made to do everything-in-one-shot parsing;
in most cases, the effect of complex regexp can be achieved better
with more powerful grammar than regular grammar.
@c JP
このエラーが起きた場合、他のパーズ手法を組み合わせることを検討してください。
Gaucheの正規表現エンジンはそれ一つで何もかもやってしまうことを目的として作られては
いません。多くの場合、複雑な正規表現を駆使するよりも、
正規文法より強力な文法を使う方がうまくいきます。
@c COMMON

@c EN
To apply the match repeatedly on the input string, or to match
from the input stream (such as the data from the port),
you may want to check @code{grxmatch} in @code{gauche.generator}
(@pxref{Generator operations}).
@c JP
入力から複数のマッチを取り出したり、あるいはストリーム入力 (ポートから読み出すデータなど)
にマッチをかけたい場合は、@code{gauche.generator}モジュールの@code{grxmatch}
も使えるかもしれません (@ref{Generator operations}参照)。
@c COMMON
@end defun

@deffn {Generic application} @var{regexp} @var{string}
@c EN
A regular expression object can be applied directly to the string.
This works the same as @code{(rxmatch @var{regexp} @var{string})},
but allows shorter notation.   @xref{Applicable objects}, for
generic mechanism used to implement this.
@c JP
正規表現オブジェクトは直接文字列に対して適用することもできます。
これは@code{(rxmatch @var{regexp} @var{string})}と同じ動作をしますが、
表記が短くて済みます。この機能は@ref{Applicable objects} で述べているメカニズムを
使って実装されています。
@c COMMON
@end deffn

@c EN
@subsubheading Accessing the match result
@c JP
@subsubheading マッチの結果を取り出す
@c COMMON

@defun rxmatch-start match :optional (i 0)
@defunx rxmatch-end match :optional (i 0)
@defunx rxmatch-substring match :optional (i 0)
@c EN
@var{Match} is a match object returned by @code{rxmatch}.
If @var{i} equals to zero, the functions return
start, end or the substring of entire match, respectively.
With positive integer @var{I}, it returns those of @var{I}-th
submatches.  It is an error to pass other values to @var{I}.
@c JP
@code{rxmatch}が返すマッチオブジェクト@var{match}から情報を取り出します。
@var{i}が省略されるか0の場合、これらの手続きはそれぞれ一致した
文字列の開始インデックス、終了インデックス、および一致した部分文字列を
返します。@var{i}に正の整数が与えられた場合は、@var{i}番目のサブマッチ
に関する情報を返します。@var{i}にシンボルが与えられた場合は、名前
@var{i}を持つサブマッチの情報を返します。同じ名前@var{i}を持つ複数の
サブマッチがある場合には、成功したサブマッチの情報を返します。
@var{i}にそれ以外の値を与えるのはエラーです。
@c COMMON

@c EN
It is allowed to pass @code{#f} to @var{match} for convenience.
The functions return @code{#f} in such case.
@c JP
簡便のために、@var{match}に@code{#f}を渡すことも許されています。
その場合、これらの手続きは@code{#f}を返します。
@c COMMON

@c EN
These functions correspond to scsh's @code{match:start}, @code{match:end}
and @code{match:substring}.
@c JP
これらの手続きはScshで@code{match:start}、@code{match:end}、
@code{match:substring}と呼ばれているものと等価です。
@c COMMON
@end defun

@defun rxmatch-after match :optional (i 0)
@defunx rxmatch-before match :optional (i 0)
@c EN
Returns substring of the input string after or before @var{match}.
If optional argument is given, the @var{i}-th submatch is used
(0-th submatch is the entire match).
@c JP
マッチオブジェクト@var{match}の前および後の文字列を返します。
正の整数が@var{i}に与えられた場合はi番目のサブマッチの前および後の
文字列を返します。シンボルが与えられた場合は、その名前を持つ
サブマッチの前後の文字列を返します。
@c COMMON

@example
(define match (rxmatch #/(\d+)\.(\d+)/ "pi=3.14..."))

(rxmatch-after match) @result{} "..."
(rxmatch-after match 1) @result{} ".14..."

(rxmatch-before match) @result{} "pi="
(rxmatch-before match 2) @result{} "pi=3."
@end example
@end defun

@defun rxmatch-substrings match :optional start end
@defunx rxmatch-positions match :optional start end
@c EN
Retrieves multiple submatches (again, 0-th match is the entire match),
in substrings and in a cons of start and end position, respectively.
@c JP
複数のサブマッチ (0番目のサブマッチはマッチ全体) を取り出す手続きです。
それぞれ、部分文字列のリストと、開始位置と終了位置のコンスのリストが返されます。
@c COMMON

@example
(rxmatch-substrings (#/(\d+):(\d+):(\d+)/ "12:34:56"))
  @result{} ("12:34:56" "12" "34" "56")

(rxmatch-positions (#/(\d+):(\d+):(\d+)/ "12:34:56"))
  @result{} ((0 . 8) (0 . 2) (3 . 5) (6 . 8))
@end example

@c EN
For the convenience, you can pass @code{#f} to @var{match}; those
procedures returns @code{()} in that case.
@c JP
簡便のために、@var{match}に@code{#f}を渡すことも許されています。
その場合、これらの手続きは@code{()}を返します。
@c COMMON

@c EN
The optional @var{start} and @var{end} arguments specify the
range of submatch index.  If omitted, @var{start} defaults to 0 and
@var{end} defaults to @code{(rxmatch-num-matches match)}.
For example, if you don't need the whole match, you can give @code{1}
to @var{start} as follows:
@c JP
省略可能な@var{start}と@var{end}引数は取り出すサブマッチのインデックスの
範囲を指定します。省略された場合、@var{start}は0、
@var{end}は@code{(rxmatch-num-matches match)}の値が使われます。
例えばマッチ全体が不要なら、@var{start}に@code{1}を渡せば良いのです。
@c COMMON

@example
(rxmatch-substrings (#/(\d+):(\d+):(\d+)/ "12:34:56") 1)
  @result{} ("12" "34" "56")
@end example
@end defun


@defun rxmatch->string regexp string :optional selector @dots{}
@c EN
A convenience procedure to match a string to the given regexp,
then returns the matched substring, or @code{#f} if it doesn't match.

If no @var{selector} is given, it is the same as this:
@c JP
文字列に正規表現でマッチをかけ、マッチした文字列を得る、便利な関数です。
マッチしなかった場合は@code{#f}が帰ります。

@var{selector}が与えられなかった場合、この手続きは次の式と同じです。
@c COMMON

@example
(rxmatch-substring (rxmatch @var{regexp} @var{string}))
@end example

@c EN
If an integer is given as a selector, it returns the substring
of the numbered submatch.
@c JP
@var{selector}に整数が与えられた場合は、
それで指定されるサブマッチの文字列が返されます。
@c COMMON

@c EN
If a symbol @code{after} or @code{before} is given, it returns
the substring after or before the match.  You can give these symbols
and an integer to extract a substring before or after the numbered
submatch.
@c JP
@var{selector}にはシンボル@code{after}か@code{before}を与えることも出来ます。
その場合は、マッチした文字列の前や後の文字列が返されます。これらのシンボルの後に
さらにサブマッチを指定する整数を与えることもできます。
@c COMMON

@example
gosh> (rxmatch->string #/\d+/ "foo314bar")
"314"
gosh> (rxmatch->string #/(\w+)@@([\w.]+)/ "foo@@example.com" 2)
"example.com"
gosh> (rxmatch->string #/(\w+)@@([\w.]+)/ "foo@@example.com" 'before 2)
"foo@@"
@end example
@end defun

@deffn {Generic application} @var{regmatch} :optional @var{index}
@deffnx {Generic application} @var{regmatch} @code{'before} :optional @var{index}
@deffnx {Generic application} @var{regmatch} @code{'after} :optional @var{index}
@c EN
A regmatch object can be applied directly to the integer index,
or a symbol @code{before} or @code{after}.
They works the same as @code{(rxmatch-substring @var{regmatch} @var{index})},
@code{(rxmatch-before @var{regmatch})}, and
@code{(rxmatch-after @var{regmatch})}, respectively.
This allows shorter notation.  @xref{Applicable objects}, for
generic mechanism used to implement this.
@c JP
マッチオブジェクトは直接整数のインデックスもしくはシンボルに対して適用することが
できます。整数に適用したときは@code{(rxmatch-substring @var{regmatch} @var{index})}、
シンボル@code{before}のときは@code{(rxmatch-before @var{regmatch})}、シンボル
@code{after}のときは@code{(rxmatch-after @var{regmatch})}、そのほかのシンボルのときは
@code{(rxmatch-substring @var{regmatch} @var{symbol})}と同じ動作をします。

表記が短くて済みます。
この機能は@ref{Applicable objects} で述べているメカニズムを使って実装されています。
@c COMMON

@example
(define match (#/(\d+)\.(\d+)/ "pi=3.14..."))

  (match)           @result{} "3.14"
  (match 1)         @result{} "3"
  (match 2)         @result{} "14"

  (match 'after)    @result{} "..."
  (match 'after 1)  @result{} ".14..."

  (match 'before)   @result{} "pi="
  (match 'before 2) @result{} "pi=3."

(define match (#/(?<integer>\d+)\.(?<fraction>\d+)/ "pi=3.14..."))

  (match 1)         @result{} "3"
  (match 2)         @result{} "14"

  (match 'integer)  @result{} "3"
  (match 'fraction) @result{} "14"

  (match 'after 'integer)   @result{} ".14..."
  (match 'before 'fraction) @result{} "pi=3."
@end example
@end deffn

@defun rxmatch-num-matches match
@defunx rxmatch-named-groups match
@c EN
Returns the number of matches, and an alist of named groups and whose
indices, in @var{match}.
This corresponds @code{regexp-num-groups} and @code{regexp-named-groups}
on a regular expression that has been used to generate @var{match}.
These procedures are useful to inspect @var{match} object without having
the original regexp object.

The number of matches includes the "whole match", so it is always a positive
integer for a @code{<regmatch>} object.  The number also includes
the submatches that don't have value (see the examples below).
The result of @code{rxmatch-named-matches} also includes all the
named groups in the original regexp, not only the matched ones.

For the convenience, @code{rxmatch-num-matches} returns 0
and @code{rxmatch-named-groups} returns @code{()}
if @var{match} is @code{#f}.
@c JP
それぞれ、@var{match}の持つマッチの数、
および名前つきグループの名前とインデックスのalistを返します。
これらは、@var{match}を返した正規表現オブジェクトに対する
@code{regexp-num-groups}と@code{regexp-named-groups}手続きに対応します。
元の正規表現オブジェクトなしに、@var{match}の中身を調べたい時に便利です。

返されるマッチの数には「マッチ全体」も含まれます。
つまり、@code{<regmatch>}オブジェクトに対しては常に正の整数が返ることになります。
値を持たないマッチもカウントされます(下の例を参照)。
@code{rxmatch-named-matches}が返すalistについても、元の正規表現の持つ
名前つきグループの情報がマッチの有無によらず返されます。

簡便のために、@var{match}に@code{#f}を渡すこともできます。
その場合、@code{rxmatch-num-matches}は0を、
@code{rxmatch-named-groups}は@code{()}を返します。
@c COMMON

@example
(rxmatch-num-matches (rxmatch #/abc/ "abc")) @result{} 1
(rxmatch-num-matches (rxmatch #/(a(.))|(b(.))/ "ba")) @result{} 5
(rxmatch-num-matches #f) @result{} 0

(rxmatch-named-groups
 (rxmatch #/(?<h>\d\d):(?<m>\d\d)(:(?<s>\d\d))?/ "12:34"))
 @result{} ((s . 4) (m . 2) (h . 1))
@end example
@end defun

@c EN
@subsubheading Convenience utilities
@c JP
@subsubheading 便利なユーティリティ
@c COMMON

@defun regexp-replace regexp string substitution
@defunx regexp-replace-all regexp string substitution
@c EN
Replaces the part of @var{string} that matched to @var{regexp}
for @var{substitution}.  @code{regexp-replace} just replaces
the first match of @var{regexp}, while @code{regexp-replace-all}
repeats the replacing throughout entire @var{string}.
@c JP
@var{string}中で@code{regexp}にマッチした部分を@var{substitution}で
置き換えます。@code{regexp-replace}は最初にマッチした部分のみを置き換え、
@code{regexp-replace-all}は全てのマッチを置き換えます。
@c COMMON

@c EN
@var{substitution} may be a string or a procedure.  If it is a string,
it can contain references to the submatches by
digits preceded by a backslash (e.g. @code{\2})
or the named submatch reference (e.g. @code{\k<@var{name}>}.
@code{\0} refers to the
entire match.  Note that you need two backslashes to include
backslash character in the literal string; if you want to include a backslash
character itself in the @var{substitution}, you need four backslashes.
@c JP
@var{substitution}は文字列か手続きです。
文字列の場合、バックスラッシュに続く数値、もしくは
@code{\k<@var{name}>}という形式でサブマッチ文字列を参照できます
@code{\0}はマッチ文字列全体を参照します。文字列リテラルにバックスラッシュを
埋め込む場合は二つのバックスラッシュが必要であることに注意して下さい。
バックスラッシュそのものを@var{substitution}中で使いたい場合は
二つのバックスラッシュを重ねます; 文字列リテラルの場合は4つのバックスラッシュが
必要になります。
@c COMMON

@example
(regexp-replace #/def|DEF/ "abcdefghi" "...")
  @result{} "abc...ghi"
(regexp-replace #/def|DEF/ "abcdefghi" "|\\0|")
  @result{} "abc|def|ghi"
(regexp-replace #/def|DEF/ "abcdefghi" "|\\\\0|")
  @result{} "abc|\\0|ghi"
(regexp-replace #/c(.*)g/ "abcdefghi" "|\\1|")
  @result{} "ab|def|hi"
(regexp-replace #/c(?<match>.*)g/ "abcdefghi" "|\\k<match>|")
  @result{} "ab|def|hi"
@end example

@c EN
If @var{substitution} is a procedure, for every match in @var{string}
it is called with one argument, regexp-match object.  The returned
value from the procedure is inserted to the output string using
@code{display}.
@c JP
@var{substitution}が手続きである場合、@var{string}中の各マッチについて、
マッチオブジェクトを引数としてその手続きが呼ばれます。その手続きが返す
値を@code{display}で表現したものが置換文字列として使われます。
@c COMMON

@example
(regexp-replace #/c(.*)g/ "abcdefghi"
                (lambda (m)
                  (list->string
                   (reverse
                    (string->list (rxmatch-substring m 1))))))
 @result{} "abfedhi"
@end example

@c EN
Note: @code{regexp-replace-all} applies itself recursively to the remaining
of the string after match.  So the beginning of string assertion
in @var{regexp} doesn't only mean the beginning of input string.
@c JP
註: @code{regexp-replace-all} は文字列でマッチした部分の後ろの部分に
ついて再帰的に自分自身を適用します。従って、@var{regexp}が
文字列先頭のアサーション (@code{^}) を含んでいても、それは@var{string}の
先頭だけにマッチするとは限りません。
@c COMMON

@c EN
Note: If you want to operate on multiple matches in the string
instead of replacing it, you can use @code{lrxmatch} in @code{gauche.lazy}
module or @code{grxmatch} in @code{gauche.generator} module.  Both can
match a regexp @emph{repeatedly} and @emph{lazily} to the given string,
and @code{lrxmatch}
returns a lazy sequence of @code{regmatch}es, while @code{grxmatch}
returns a generator that yields @code{regmatch}es.
@c JP
註: 文字列中の、正規表現にマッチする部分すべてに対して何か操作をしたいが、
置き換えた文字列が欲しいわけではない、という場合は、
@code{gauche.lazy}モジュールの@code{lrxmatch}や、
@code{gauche.generator}モジュールの@code{grxmatch}が使えるでしょう。
これらは文字列に対して繰り返し正規表現でのマッチを、必要に応じて適用し、
前者はマッチオブジェクトの遅延シーケンスを、後者はマッチオブジェクトを生成する
ジェネレータを返します。
@c COMMON

@example
(map rxmatch-substring (lrxmatch #/\w+/ "a quick brown fox!?"))
 @result{} ("a" "quick" "brown" "fox")
@end example
@end defun

@defun regexp-replace* string rx1 sub1 rx2 sub2 @dots{}
@defunx regexp-replace-all* string rx1 sub1 rx2 sub2 @dots{}
@c EN
First applies @code{regexp-replace} or @code{regexp-replace-all} to
@var{string} with a regular expression @var{rx1} substituting for
@var{sub1}, then applies the function on the result string
with a regular expression @var{rx2} substituting for @var{sub2}, and
so on.  These functions are handy when you want to apply
multiple substitutions sequentially on a string.
@c JP
まず、@code{regexp-replace} あるいは @code{regexp-replace-all} を
正規表現 @var{rx1}、置換 @var{sub1} で @var{string} に適用し、
その結果にさらに @code{regexp-replace} あるいは
@code{regexp-replace-all} を正規表現 @var{rx2}、置換 @var{sub2} で
適用し、以下同様です。これらの関数はひとつの文字列上で複数回置換を行う
ときに便利です。
@c COMMON
@end defun

@defun regexp-quote string
@c EN
Returns a string with the characters that are special to regexp escaped.
@c JP
@var{string}中で、正規表現において特別な意味を持つ文字を全てエスケープした
文字列を返します。
@c COMMON

@example
(regexp-quote "[2002/10/12] touched foo.h and *.c")
 @result{} "\\[2002/10/12\\] touched foo\\.h and \\*\\.c"
@end example
@end defun


@c EN
In the following macros, @var{match-expr} is an expression
which produces a match object or @code{#f}. Typically
it is a call of @code{rxmatch}, but it can be any expression.
@c JP
以下のマクロにおいて、@var{match-expr}はマッチオブジェクトか
@code{#f}を生成する式でなければなりません。通常それは
@code{rxmatch}を呼ぶ式になりますが、それだけに限られるわけではありません。
@c COMMON

@defmac rxmatch-let match-expr (var @dots{}) form @dots{}

@c EN
Evaluates @var{match-expr}, and if matched, binds @var{var @dots{}}
to the matched strings, then evaluates @var{form}s.
The first @var{var} receives the entire match, and subsequent
variables receive submatches.  If the number of submatches are
smaller than the number of variables to receive them, the rest
of variables will get @code{#f}.
@c JP
@var{match-expr}を評価し、それがマッチオブジェクトを返したら、
マッチした文字列を@var{var @dots{}}に束縛し、@var{form}を評価します。
最初の@var{var}はマッチした文字列全体に束縛され、
以降の変数はサブマッチ文字列に束縛されます。実際のサブマッチ文字列が
与えられた変数より少なかった場合は、余った変数は@code{#f}に束縛されます。
@c COMMON

@c EN
It is possible to put @code{#f} in variable position, which says
you don't care that match.
@c JP
特定のマッチ文字列を受け取る必要が無いときは、その場所の
変数の変わりに@code{#f}を置いておくこともできます。
@c COMMON

@example
(rxmatch-let (rxmatch #/(\d+):(\d+):(\d+)/
                      "Jan  1 23:59:58, 2001")
   (time hh mm ss)
  (list time hh mm ss))
 @result{} ("23:59:58" "23" "59" "58")

(rxmatch-let (rxmatch #/(\d+):(\d+):(\d+)/
                      "Jan  1 23:59:58, 2001")
   (#f hh mm)
  (list hh mm))
 @result{} ("23" "59")
@end example

@c EN
This macro corresponds to scsh's @code{let-match}.
@c JP
このマクロはscshの@code{let-match}に相当します。
@c COMMON
@end defmac

@defmac rxmatch-if match-expr (var @dots{}) then-form else-form
@c EN
Evaluates @var{match-expr}, and if matched, binds @var{var} @dots{}
to the matched strings and evaluate @var{then-form}.
Otherwise evaluates @var{else-form}.
The rule of binding @var{var}s is the same as @code{rxmatch-let}.
@c JP
@var{match-expr}を評価し、それがマッチオブジェクトを返したら
マッチした文字列を変数@var{var} @dots{}に束縛して@var{then-form}を
評価します。マッチオブジェクトが返されなければ束縛は行われず、
@var{else-form}が評価されます。変数@var{var}をマッチ文字列に
束縛するルールは@code{rxmatch-let}と同じです。
@c COMMON

@example
(rxmatch-if (rxmatch #/(\d+:\d+)/ "Jan 1 11:22:33")
    (time)
  (format #f "time is ~a" time)
  "unknown time")
 @result{} "time is 11:22"

(rxmatch-if (rxmatch #/(\d+:\d+)/ "Jan 1 11-22-33")
    (time)
  (format #f "time is ~a" time)
  "unknown time")
 @result{} "unknown time"
@end example

@c EN
This macro corresponds to scsh's @code{if-match}.
@c JP
このマクロはscshの@code{if-match}に相当します。
@c COMMON
@end defmac

@defmac rxmatch-cond clause @dots{}
@c EN
Evaluate condition in @var{clause}s one by one.
If a condition of a clause satisfies, rest portion of the clause
is evaluated and becomes the result of @code{rxmatch-cond}.
@var{Clause} may be one of the following pattern.
@c JP
@var{clause}の条件を順に評価してゆき、条件を満たすものが現れたら
その@var{clause}の残りのフォームを評価し、最後のフォームの値を
@code{rxmatch-cond}の値とします。@var{clause}は以下のいずれかの
形式でなければなりません。
@c COMMON

@table @code
@item (@var{match-expr} (@var{var} @dots{}) @var{form} @dots{})
@c EN
Evaluate @var{match-expr}, which may return a regexp match
object or @code{#f}.  If it returns a match object, the matches
are bound to @var{var}s, like @var{rxmatch-let}, and @var{form}s
are evaluated.
@c JP
@var{match-expr}を評価し、それがマッチオブジェクトを返した場合は
マッチ文字列を変数@var{var} @dots{}に束縛した上で
@var{form} @dots{}を評価します。
@c COMMON

@item (test @var{expr} @var{form} @dots{})
@c EN
Evaluates @var{expr}.  If it yields true, evaluates @var{form}s.
@c JP
@var{expr}を評価し、それが真の値を返した場合は@var{form} @dots{}を評価します。
@c COMMON

@item (test @var{expr} => @var{proc})
@c EN
Evaluates @var{expr} and if it is true,
calls @var{proc} with the result of @var{expr} as the only argument.
@c JP
@var{expr}を評価し、それが真の値を返した場合は
それを唯一の引数として手続き@var{proc}を呼びます。
@c COMMON

@item (else @var{form} @dots{})
@c EN
If this clause exists, it must be the last clause.
If other clauses fail, @var{form}s are evaluated.
@c JP
この@var{clause}は、もし与えられたとすれば最後の@var{clause}でなければ
なりません。全ての@var{clause}が失敗した場合に、@var{form} @dots{}が
評価されます。
@c COMMON
@end table

@c EN
If no @code{else} clause exists, and all the other clause fail,
an undefined value is returned.
@c JP
@code{else} @var{clause}が与えられず、かつ全ての@var{clause}が
失敗した場合の戻り値は未定義です。
@c COMMON

@example
@c EN
;; @r{parses several possible date format}
@c JP
;; @r{何通りかの日付のフォーマットをパーズする}
@c COMMON
(define (parse-date str)
  (rxmatch-cond
    ((rxmatch #/^(\d\d?)\/(\d\d?)\/(\d\d\d\d)$/ str)
        (#f mm dd yyyy)
      (map string->number (list yyyy mm dd)))
    ((rxmatch #/^(\d\d\d\d)\/(\d\d?)\/(\d\d?)$/ str)
        (#f yyyy mm dd)
      (map string->number (list yyyy mm dd)))
    ((rxmatch #/^\d+\/\d+\/\d+$/ str)
        (#f)
     (errorf "ambiguous: ~s" str))
    (else (errorf "bogus: ~s" str))))

(parse-date "2001/2/3") @result{} (2001 2 3)
(parse-date "12/25/1999") @result{} (1999 12 25)
@end example

@c EN
This macro corresponds to scsh's @code{match-cond}.
@c JP
このマクロはscshの@code{match-cond}に相当します。
@c COMMON
@end defmac

@defmac rxmatch-case string-expr clause @dots{}
@c EN
@var{String-expr} is evaluated, and @var{clause}s are interpreted
one by one.  A @var{clause} may be one of the following pattern.
@c JP
@var{string-expr}がまず評価され、続いて@var{clause}が順に検査されます。
@var{clause}は以下のいずれかの形式でなければなりません。
@c COMMON

@table @code
@item (@var{re} (@var{var} @dots{}) @var{form} @dots{})
@c EN
@var{Re} must be a literal regexp object (@pxref{Regular expressions}).
If the result of @var{string-expr} matches @var{re},
the match result is bound to @var{var}s
and @var{form}s are evaluated, and @code{rxmatch-case} returns
the result of the last @var{form}.
@c JP
@var{re}はリテラル正規表現オブジェクトでなければなりません
(@ref{Regular expressions}参照)。@var{string-expr}の結果が文字列であり
@var{re}にマッチした場合は、マッチ文字列が変数@var{var} @dots{}に
束縛され、@var{form}が評価されます。最後の@var{form}の値が@code{rxmatch-case}
の値となります。
@c COMMON

@c EN
If @var{re} doesn't match the result of @var{string-expr},
@var{string-expr} yields non-string value, the interpretation proceeds
to the next clause.
@c JP
@var{string-expr}の結果の文字列が@var{re}にマッチしないか、
@var{string-expr}の結果が文字列以外であった場合は次の@var{clause}へと
処理が進みます。
@c COMMON

@item (test @var{proc} @var{form} @dots{})
@c EN
A procedure @var{proc} is applied on the result of @var{string-expr}.
If it yields true value, @var{form}s are evaluated, and
@code{rxmatch-case} returns the result of the last @var{form}.
@c JP
手続き@var{proc}が@var{string-expr}の結果を引数として呼ばれます。
それが真の値を返した場合は@var{form}が順に評価され、最後の@var{form}の
値が@code{rxmatch-case}の値として返されます。
@c COMMON

@c EN
If @var{proc} yields @code{#f}, the interpretation proceeds
to the next clause.
@c JP
@var{proc}が@code{#f}を返した場合は次の@var{clause}へと
処理が進みます。
@c COMMON

@item (test @var{proc} => @var{proc2})
@c EN
A procedure @var{proc} is applied on the result of @var{string-expr}.
If it yields true value, @var{proc2} is applied on the result,
and its result is returned as the result of @code{rxmatch-case}.
@c JP
手続き@var{proc}が@var{string-expr}の結果を引数として呼ばれます。
それが真の値を返した場合は、その値を引数として@var{proc2}が呼ばれ、
その返り値が@code{rxmatch-case}の値として返されます。
@c COMMON

@c EN
If @var{proc} yields @code{#f}, the interpretation proceeds
to the next clause.
@c JP
@var{proc}が@code{#f}を返した場合は次の@var{clause}へと
処理が進みます。
@c COMMON

@item (else @var{form} @dots{})
@c EN
This form must appear at the end of @var{clause}s, if any.
If other clauses fail, @var{form}s are evaluated,
and the result of the last @var{form} becomes the result of
@code{rxmatch-case}.
@c JP
このフォームは、与えられる場合は最後の@var{clause}でなければなりません。
他の全ての@var{clause}が失敗した場合に、@var{form}が順に評価され、最後の@var{form}の
値が@code{rxmatch-case}の値として返されます。
@c COMMON

@item (else => @var{proc})
@c EN
This form must appear at the end of @var{clause}s, if any.
If other clauses fail, @var{proc} is evaluated, which should
yield a procedure taking one argument.  The value of @var{string-expr}
is passed to @var{proc}, and its return values become the
return values of @code{rxmatch-case}.
@code{rx}
@c JP
このフォームは、与えられる場合は最後の@var{clause}でなければなりません。
他の全ての@var{clause}が失敗した場合に、@var{proc}が評価されます。
その値は一引数の手続きにならなければなりません。
その手続きが、@var{string-expr}の値を引数として呼ばれます。
@var{proc}の結果が@code{rxmatch-case}の値となります。
@c COMMON
@end table

@c EN
If no @code{else} clause exists, and all other clause fail,
an undefined value is returned.
@c JP
@code{else} @var{clause}が与えられず、かつ全ての@var{clause}が
失敗した場合の戻り値は未定義です。
@c COMMON

@c EN
The @code{parse-date} example above becomes simpler if you use
@code{rxmatch-case}
@c JP
上の@code{parse-date}の例は@code{rxmatch-case}を使うとより単純になります。
@c COMMON

@example
(define (parse-date2 str)
  (rxmatch-case str
    (test (lambda (s) (not (string? s))) #f)
    (#/^(\d\d?)\/(\d\d?)\/(\d\d\d\d)$/ (#f mm dd yyyy)
     (map string->number (list yyyy mm dd)))
    (#/^(\d\d\d\d)\/(\d\d?)\/(\d\d?)$/ (#f yyyy mm dd)
     (map string->number (list yyyy mm dd)))
    (#/^\d+\/\d+\/\d+$/                (#f)
     (errorf "ambiguous: ~s" str))
    (else (errorf "bogus: ~s" str))))
@end example
@end defmac

@node Inspecting and assembling regular expressions,  , Using regular expressions, Regular expressions
@subsection Inspecting and assembling regular expressions
@c NODE 正規表現の調査と合成

@c EN
When Gauche reads a string representation of regexp, first it parses
the string and construct an abstract
syntax tree (AST), performs some optimizations on it,
then compiles it into an instruction sequence to be
executed by the regexp engine.
@c JP
Gaucheはregexpの文字列表記を読むと、その文字列をパーズして
抽象構文木 (AST) を作り、それにいくらかの最適化を施したのち、
正規表現エンジンで実行されるインストラクション列へとコンパイルします。
@c COMMON

@c EN
The following procedures expose this process to
user programs.  It may be easier for programs to
manipulate an AST than a string representation.
@c JP
以下の手続きはこのプロセスをユーザプログラムに見せるものです。
プログラム的に正規表現をいじる場合は、文字列形式よりも
ASTの方が扱いやすいでしょう。
@c COMMON

@defun regexp-parse string :key case-fold multi-line
@c EN
Parses a string specification of regexp in @var{string}
and returns its AST, represented in S-expression.
See below for the spec of AST.
@c JP
正規表現の文字列表記である@var{string}をパーズし、S式で表現された
ASTを返します。ASTの仕様は下で述べます。
@c COMMON

@c EN
When a true value is given to the keyword argument @var{case-fold},
returned AST will match case-insensitively.
(Case insensitive regexp is handled in parser level,
not by the engine).
@c JP
@var{case-fold}キーワード引数に真の値が与えられた場合は、
大文字小文字を区別せずにマッチを行うASTが返されます
(エンジン自体に「大文字小文字を区別しない」モードがあるわけではなく、
パーザの段階で異なるASTが生成されます)。
@c COMMON
@end defun

@defun regexp-parse-sre sre
@c EN
Parses @var{sre} as a Scheme Regular Expression (SRE) as described in
SRFI-115 and returns its AST.
@xref{R7RS regular expressions}
@c JP
@var{sre}をSRFI-115で定義されるScheme正規表現(SRE)としてパーズし、
結果をASTで返します。
SREについて詳しくは@ref{R7RS regular expressions}を参照してください。
@c COMMON
@pxref{R7RS regular expressions}.
@end defun

@defun regexp-optimize ast
@c EN
Performs some rudimental optimization on the regexp AST,
returning regexp AST.

Currently it only optimizes some trivial cases.  The plan is
to make it cleverer in future.
@c JP
正規表現のASTに対して、いくつかの原始的な最適化を施して結果のASTを返します。

現在のところ、最適化はごく簡単なものです。将来はもっと賢くする予定です。
@c COMMON
@end defun

@defun regexp-compile ast :key multi-line
@c EN
Takes a regexp @var{ast} and returns a regexp object.
Currently the outermost form of @var{ast} must be
the zero-th capturing group.  (That is, @var{ast}
should have the form @code{(0 #f @var{x} @dots{})}.)
The outer grouping is always added
by @code{regexp-parse} to capture the entire regexp.
@c JP
正規表現のASTを受け取り、マッチに使える正規表現オブジェクトを返します。
渡されるASTの一番外側は、0番めの捕捉グループでなければなりません
(@var{ast}は@code{(0 #f @var{x} @dots{})}という形でなければ
ならない、ということです)。@code{regexp-parse}は常にこの捕捉グループを
追加します。正規表現にマッチした全体の文字列を捕捉するためです。
@c COMMON

@c EN
Note: The function does some basic check to see the given AST
is valid, but it may not reject invalid ASTs.  In such case,
the returned regexp object doesn't work properly.  It is
caller's responsibility to provide a properly constructed AST.
(Even if it rejects an AST, error messages are often
incomprehensible.  So, don't use this procedure as a AST validness checker.)
@c JP
註：この関数は渡されたASTが有効なものであるかどうかについて
簡単なチェックを行いますが、有効でないASTを受け入れてしまうかもしれません。
その場合、返される正規表現オブジェクトの動作は不定です。
正しい形式のASTを渡すのは呼出側の責任です
(この関数が有効でないASTを見つけてエラーにする場合でも、
そのエラーメッセージからどこがおかしいかを判断するのが難しい場合があります。
この手続きをASTが有効であるかどうかのチェッカーとして使うのは避けましょう。)
@c COMMON
@end defun

@defun regexp-ast regexp
@c EN
Returns AST used for the regexp object @var{regexp}.
@c JP
正規表現オブジェクト@var{regexp}が使っているASTを返します。
@c COMMON
@end defun

@defun regexp-unparse ast :key (on-error :error)
@c EN
From the regexp's @var{ast}, reconstruct the string representation
of the regexp.  The keyword argument @var{on-error} can be
a keyword @code{:error} (default) or @code{#f}.  If it's the former,
an error is signaled when @var{ast} isn't valid regexp AST.
If it's the latter, @code{regexp-unparse} just returns @code{#f}.
@c JP
正規表現の@var{ast}から、その正規表現の文字列表記を再構成して返します。
キーワード引数@var{on-error}は、キーワード@code{:error} (デフォルト)
もしくは@code{#f}です。それが@code{:error}の場合、@var{ast}が不正
であればエラーが報告され、@code{#f}の場合は@code{regexp-unparse}から
@code{#f}が返されます。
@c COMMON
@end defun

@c EN
This is the structure of AST.  Note that this is originally
developed only for internal use, and not very convenient to manipulate
from the code (e.g. if you insert or delete a subtree, you have to
renumber capturing groups to make them consistent.)
@c JP
以下にASTの構造を示します。この仕様は当初、内部的に使うためだけに設計されたので、
コードで直接いじるのには若干不便です (例えば、部分木を削除したり
追加した場合、捕捉グループの番号を振りなおして一貫性を保つ必要があるかもしれません。)
@c COMMON

@smallexample
<ast> : <clause>   ; special clause
      | <item>     ; matches <item>

<item> : <char>       ; matches char
       | <char-set>   ; matches char set
       | (comp . <char-set>) ; matches complement of char set
       | any          ; matches any char
       | bos | eos    ; beginning/end of string assertion
       | bol | eol    ; beginning/end of line assertion
       | bow | eow | wb | nwb ; word-boundary/negative word boundary assertion
       | bog | eog    ; beginning/end of grapheme assertion

<clause> : (seq <ast> ...)       ; sequence
       | (seq-uncase <ast> ...)  ; sequence (case insensitive match)
       | (seq-case <ast> ...)    ; sequence (case sensitive match)
       | (alt <ast> ...)         ; alternative
       | (rep <m> <n> <ast> ...) ; repetition at least <m> up to <n> (greedy)
                               ; <n> may be `#f'
       | (rep-min <m> <n> <ast> ...)
                               ; repetition at least <m> up to <n> (lazy)
                               ; <n> may be `#f'
       | (rep-while <m> <n> <ast> ...)
                               ; like rep, but no backtrack
       | (<integer> <symbol> <ast> ...)
                               ; capturing group.  <symbol> may be #f.
       | (cpat <condition> (<ast> ...) (<ast> ...))
                               ; conditional expression
       | (backref . <integer>) ; backreference by group number
       | (backref . <symbol>)  ; backreference by name
       | (once <ast> ...)      ; standalone pattern.  no backtrack
       | (assert . <asst>)     ; positive lookahead assertion
       | (nassert . <asst>)    ; negative lookahead assertion

<condition> : <integer>     ; (?(1)yes|no) style conditional expression
       | (assert . <asst>)  ; (?(?=condition)...) or (?(?<=condition)...)
       | (nassert . <asst>) ; (?(?!condition)...) or (?(?<!condition)...)

<asst> : <ast> ...
       | ((lookbehind <ast> ...))
@end smallexample

@c ----------------------------------------------------------------------
@node Vector family, Dictionaries, Regular expressions, Core library
@section Vector family
@c NODE ベクタの仲間

@c EN
Vectors are fixed-size, O(1) accessible sequence of values.
Scheme has traditionally offered a vector of arbitrary objects, which is
described in @ref{Vectors}.

In R7RS-large, there're also homogeneous numeric vectors (uvectors),
which can contain fixed range of numeric objects efficiently.
We explain them in @ref{Uniform vectors}.

Gauche also supports bitvectors, which can contain sequence of bits.
@xref{Bitvectors}, for the details.

Finally, weak vectors are a vector of arbitrary objects using
weak pointers.  @xref{Weak vectors}.
@c JP
ベクタは固定長でO(1)アクセス可能な値の並びです。
Schemeは伝統的に、任意の値を格納できるベクタを提供してきました。
これは@ref{Vectors}で説明されます。

R7RS-largeでは、均質な数値型だけを効率よく格納できるベクタ(uvector)も定義されています。
@ref{Uniform vectors}を見てください。

Gaucheはまた、ビット列を格納するビットベクタも提供します。
@ref{Bitvectors}で説明します。

最後に、weakベクタは任意の要素をweakポインタを使って格納できるベクタです。
@ref{Weak vectors}参照。
@c COMMON

@c EN
Vectors can be used as 1-dimensional array with its origin fixed to 0.
If you need more general arrays, e.g. multi-dimensional or non-0 origin,
you can use @code{gauche.array} (@pxref{Arrays}).
@c JP
ベクタは0オリジンに固定された1次元配列のように扱えますが、
より汎用的な配列(2次元以上の配列や、0オリジンでない配列)が必要なら、
@code{gauche.array}モジュールが使えます(@ref{Arrays}参照)。
@c COMMON

@menu
* Vectors::
* Uniform vectors::
* Bitvectors::
* Weak vectors::
@end menu

@node Vectors, Uniform vectors, Vector family, Vector family
@subsection Vectors
@c NODE ベクタ

@deftp {Builtin Class} <vector>
@clindex vector
@c EN
A vector is a simple 1-dimensional array of Scheme objects.
You can access its element by index in constant time.
Once created, a vector can't be resized.

Class @code{<vector>} inherits @code{<sequence>} and
you can use various generic functions such as @code{map} and @code{fold}
on it.   @xref{Collection framework}, and @xref{Sequence framework}.

If you keep only a homogeneous numeric type, you may be able
to use uniform vectors (@pxref{Uniform vectors}).

R7RS defines bytevectors; in Gauche, they're just @code{u8vector}s
in @code{gauche.uvector} module (r7rs modules defines aliases.
@pxref{R7RS base library}).

@xref{R7RS vectors}, for additional operations on vectors.
@c JP
ベクタはSchemeオブジェクトの単純な一次元配列です。
インデックスを用いて定数時間でその要素にアクセスできます。
一度作成されたベクタはその大きさを変えることはできません。

@code{<vector>}クラスはまた@code{<sequence>}クラスを継承し、
@code{map}や@code{fold}など様々な総称関数を使うことができます。
@ref{Collection framework} と
@ref{Sequence framework} を参照して下さい。

数値しか要素に持たないベクタを使う場合、
ユニフォームベクタも使えるかもしれません (@ref{Uniform vectors}参照)。

R7RSはバイトベクタを定義しています。Gaucheではそれは単に
@code{gauche.uvector}モジュールの@code{u8vector}です
(R7RSモジュールは別名を定義しています。@ref{R7RS base library}参照。)

より多くのベクタに対する操作が@ref{R7RS vectors}で提供されています。
@c COMMON
@end deftp

@defun vector? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is a vector, @code{#f} otherwise.
@c JP
@var{obj}がベクタなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun make-vector k :optional fill
[R7RS base]
@c EN
Creates and returns a vector with length @var{k}.
If optional argument @var{fill} is given, each element of the vector
is initialized by it.  Otherwise, the initial value of each element
is undefined.
@c JP
長さ@var{k}のベクタを作成して返します。
省略可能な引数@var{fill}が与えられていれば、ベクタの各要素はその値で
初期化されます。そうでなければベクタの各要素の値は不定です。
@c COMMON
@end defun

@defun vector obj @dots{}
[R7RS base]
@c EN
Creates a vector whose elements are @var{obj} @dots{}.
@c JP
要素が@var{obj} @dots{}であるようなベクタを作成して返します。
@c COMMON
@end defun

@defun vector-tabulate len proc
@c EN
Creates a vector of length @var{len},
initializing @var{i}-th
element of which by @code{(@var{proc} @var{i})}
for all @var{i} between @code{0} and @var{len}
@c JP
長さ@var{len}のベクタを作成し、@code{0}以上@var{len}未満の@var{i}について
@var{i}番目の要素を@code{(@var{proc} @var{i})}の値で初期化します。
@c COMMON

@example
(vector-tabulate 5 (^x (* x x)))
  @result{} #(0 1 4 9 16)
@end example
@end defun

@defun vector-length vector
[R7RS base]
@c EN
Returns the length of a vector @var{vector}.

With @code{gauche.collection} module,
you can also use a method @code{size-of}.
@c JP
ベクタ@var{vector}の長さを返します。

@code{gauche.collection}モジュールをロードしていれば、
メソッド@code{size-of}も同じ目的で使えます。
@c COMMON
@end defun

@defun vector-ref vector k :optional fallback
[R7RS+ base]
@c EN
Returns @var{k}-th element of vector @var{vector}.

By default, @code{vector-ref} signals an error if @var{k} is
negative, or greater than or equal to the length of @var{vector}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.  This is an extension of Gauche.

With @code{gauche.sequence} module,
you can also use a method @code{ref}.
@c JP
ベクタ@var{vector}の@var{k}番目の要素を返します。

@code{vector-ref}は@var{k}が負の値であったりベクタの長さより
大きかったりした場合はエラーを通知します。但し、省略可能な引数@var{fallback}
が与えられている場合はその値が返されます。これはGaucheの拡張です。

@code{gauche.sequence}モジュールをロードしていれば、
メソッド@code{ref}も同じ目的で使えます。
@c COMMON
@end defun

@defun vector-set! vector k obj
[R7RS base]
@c EN
Sets @var{k}-th element of the vector @var{vector} to @var{obj}.
It is an error if @var{k} is negative or greater than or equal to the
length of @var{vector}.

With @code{gauche.sequence} module, you can also use
a setter method of @code{ref}.
@c JP
ベクタ@var{vector}の@var{k}番目の要素を@var{obj}に変更します。
@var{k}が負数であったりベクタの長さより大きい場合はエラーとなります。

@code{gauche.sequence}モジュールをロードしていれば、
メソッド@code{ref}のsetterメソッドも使えます。
@c COMMON
@end defun

@defun vector->list vector :optional start end
@defunx list->vector list :optional start end
[R7RS+ base]
@c EN
Converts a vector to a list, or vice versa.

The optional @var{start} and @var{end} arguments
limit the range of the source.
(R7RS don't define @var{start} and @var{end} arguments
for @code{list->vector}.)
@c JP
ベクタをリストに変換したり、その逆を行う手続きです。

省略可能な引数@var{start}と@var{end}を与えることにより、
値を取り出す範囲を制限することができます。
(R7RSの@code{list->vector}は@var{start}と@var{end}引数を規定していません。)
@c COMMON
@example
(vector->list '#(1 2 3 4 5))     @result{} (1 2 3 4 5)
(list->vector '(1 2 3 4 5))      @result{} #(1 2 3 4 5)
(vector->list '#(1 2 3 4 5) 2 4) @result{} (3 4)
(list->vector (circular-list 'a 'b 'c) 1 6)
  @result{} #(b c a b c)
@end example

@c EN
With @var{gauche.collection} module, you can use
@code{(coerce-to <list> @var{vector})} and
@code{(coerce-to <vector> @var{list})} as well.
@c JP
@code{gauche.collection}モジュールをロードしていれば、
@code{(coerce-to <list> @var{vector})} と
@code{(coerce-to <vector> @var{list})} も同じ目的で使えます。
@c COMMON
@end defun

@defun reverse-list->vector list :optional start end
[R7RS vector]
@c EN
Without optional arguments, it returns the same thing as
@code{(list->vector (reverse list))}, but does not
allocate the intermediate list.   The optional @var{start} and
@var{end} argument limits the range of the input list.
@c JP
省略可能引数が無い場合、
@code{(list->vector (reverse list))}と同じ結果を返しますが、
中間リストを作りません。省略可能引数@var{start}および@var{end}が
与えられた場合は、それは@var{list}の範囲を指定します。
@c COMMON
@example
(reverse-list->vector '(a b c d e f g) 1 5)
  @result{} #(e d c b)
@end example
@end defun

@defun vector->string vector :optional start end
@defunx string->vector string :optional start end
[R7RS base]
@c EN
Converts a vector of characters to a string, or vice versa.
It is an error to pass a vector that contains other than characters
to @code{vector->string}.

The optional @var{start} and @var{end} arguments
limit the range of the source.
@c JP
文字のベクタを文字列に変換したり、その逆を行う手続きです。
@code{vector->string}に、文字以外の要素を含むベクタを渡した場合はエラーになります。

省略可能な引数@var{start}と@var{end}を与えることにより、
値を取り出す範囲を制限することができます。

@c COMMON
@example
(vector->string '#(#\a #\b #\c #\d #\e))     @result{} "abcde"
(string->vector "abcde")                     @result{} #(#\a #\b #\c #\d #\e)
(vector->string '#(#\a #\b #\c #\d #\e) 2 4) @result{} ("cd")
@end example

@c EN
With @var{gauche.collection} module, you can use
@code{(coerce-to <string> @var{vector})} and
@code{(coerce-to <vector> @var{string})} as well.
@c JP
@code{gauche.collection}モジュールをロードしていれば、
@code{(coerce-to <string> @var{vector})} と
@code{(coerce-to <vector> @var{string})} も同じ目的で使えます。
@c COMMON
@end defun

@defun vector-fill! vector fill :optional start end
[R7RS base]
@c EN
Sets all elements in a vector @var{vector} to @var{fill}.

Optional @var{start} and @var{end} limits the range
of effect between @var{start}-th index (inclusive) to
@var{end}-th index (exclusive).  @var{Start} defaults to
zero, and @var{end} defaults to the length of @var{vector}.
@c JP
ベクタ@var{vector}の全ての要素を@var{fill}に変更します。

省略可能な引数@var{start}と@var{end}が与えられた場合、
@var{start}番目の要素から@var{end}-1番目の要素までのみに
@var{fill}を格納します。@var{start}と@var{end}の既定値は
それぞれ0と@var{vector}の大きさです。
@c COMMON
@end defun

@defun vector-copy vector :optional start end fill
[R7RS base]
@c EN
Copies a vector @var{vector}.  Optional @var{start} and @var{end}
arguments can be used to limit the range of @var{vector} to be copied.
If the range specified by @var{start} and @var{end} falls outside of
the original @var{vector}, the @var{fill} value is used to fill
the result vector.
@c JP
ベクタ@var{vector}をコピーします。引数@var{start}と@var{end}を与えることで
コピーされる範囲を制限することができます。
@var{start}と@var{end}で指定される範囲が元の@var{vector}の範囲を越えた
場合は、その部分が@var{fill}で埋められます。
@c COMMON

@example
(vector-copy '#(1 2 3 4 5))     @result{} #(1 2 3 4 5)
(vector-copy '#(1 2 3 4 5) 2 4) @result{} #(3 4)
(vector-copy '#(1 2 3 4 5) 3 7 #f) @result{} #(4 5 #f #f)
@end example
@end defun

@defun vector-copy! target tstart source :optional sstart send
[R7RS base]
@c EN
Copies the content of @var{source} vector into the @var{target} vector
starting from @var{tstart} in the target.  The @var{target} vector
must be mutable.
Optional @var{sstart} and @var{send} limits the range of source
vector.
@c JP
ベクタ@var{source}の内容をベクタ@var{target}のインデックス@var{tstart}以降に
コピーします。@var{target}は変更可能でなければなりません。
省略可能な@var{sstart}と@var{send}引数はコピー元ベクタの範囲を限定します。
@c COMMON

@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-copy! v 2 '#(1 2)))
  @result{} #(a b 1 2 e)
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-copy! v 2 '#(1 2 3 4) 1 3))
  @result{} #(a b 2 3 e)
@end example

@c EN
An error is raised if the portion to be copied is greater than
the room in the target (that is, between @var{tstart} to the end).
@c JP
コピーされるデータが、コピー先の領域(@var{tstart}から末尾まで)より
大きい場合はエラーが報告されます。
@c COMMON

@c EN
It is ok to pass the same vector to @var{target} and @var{source};
it always works even if the regions of source and destination are
overlapping.
@c JP
@var{target}と@var{source}に同じベクタを渡しても構いません。
コピー元とコピー先の領域に重なりがある場合でもこの手続きは使えます。
@c COMMON
@end defun

@defun vector-append vec @dots{}
[R7RS base]
@c EN
Returns a newly allocated vector whose contents are concatenation
of elements of @var{vec} in order.
@c JP
ベクタ@var{vec}を順に継ぎ足した内容を持つベクタを新たに作成して返します。
@c COMMON

@example
(vector-append '#(1 2 3) '#(a b)) @result{} #(1 2 3 a b)
(vector-append) @result{} #()
@end example
@end defun

@defun vector-map proc vec1 vec2 @dots{}
[R7RS base]
@c EN
Returns a new vector, @var{i}-th of which is calculated
by applying @var{proc} on the list of each @var{i}-th element
of @var{vec1} @var{vec2} @dots{}.
The length of the result vector is the same as the shortest vector
of the arguments.
@c JP
ベクタ@var{vec1} @var{vec2} @dots{}の各@var{i}番目の要素に@var{proc}を
適用したものを@var{i}番目の要素とする新たなベクタを作って返します。
結果のベクタの長さは、引数のベクタのうち最も短いものと同じになります。
@c COMMON

@example
(vector-map + '#(1 2 3) '#(4 5 6 7))
 @result{} #(5 7 9)
@end example

@c EN
The actual order @var{proc} is called is undefined, and may change
in the future versions, so @var{proc} shouldn't use side effects
affected by the order.
@c JP
@var{proc}が呼ばれる順番は定義されておらず、将来のバージョンで変わるかもしれないので、
@var{proc}では順序に影響されるような副作用を起こしてはいけません。
@c COMMON

@c EN
Note: If you use @code{gauche.collection}, you can get the same
function by @code{(map-to <vector> proc vec1 vec2 @dots{})}.
@c JP
註: @code{gauche.collection}をuseして
@code{(map-to <vector> proc vec1 vec2 @dots{})} としても同じ機能は得られます。
@c COMMON
@end defun

@defun vector-map-with-index proc vec1 vec2 @dots{}
@c EN
Like @code{vector-map}, but @var{proc} receives the current index
as the first argument.
@c JP
@code{vector-map}と似ていますが、@var{proc}の第1引数に
現在のインデックスが渡されます。
@c COMMON

@example
(vector-map-with-index list '#(a b c d e) '#(A B C))
 @result{} #((0 a A) (1 b B) (2 c C))
@end example

@c EN
This is what SRFI-43 calls @code{vector-map}.  @xref{Vector library (Legacy)}.
@c JP
これがSRFI-43で@code{vector-map}と呼ばれている手続きです。
@ref{Vector library (Legacy)}参照。
@c COMMON

@c EN
Note: If you use @code{gauche.collection}, you can get the same
function by @code{(map-to-with-index <vector> proc vec1 vec2 @dots{})}.
@c JP
註: @code{gauche.collection}をuseして
@code{(map-to-with-index <vector> proc vec1 vec2 @dots{})}
としても同じ機能は得られます。
@c COMMON
@end defun

@defun vector-map! proc vec1 vec2 @dots{}
[R7RS vector]
@c EN
For each index @var{i}, calls @var{proc} with @var{i}-th index
of @var{vec1} @var{vec2} @dots{}, and set the result back to
@var{vec1}.  The value is calculated up to the minimum
length of input vectors.
@c JP
各インデックス@var{i}について、ベクタ@var{vec1} @var{vec2} @dots{}の
@var{i}番目の要素を引数として@var{proc}を呼び出した結果、@var{vec1}の
@var{i}番目の要素にセットします。ベクタの長さが異なる場合は最も短いベクタ
の範囲が計算されます。
@c COMMON

@example
(rlet1 v (vector 1 2 3)
  (vector-map! ($ + 1 $) v))
  @result{} #(2 3 4)

(rlet1 v (vector 1 2 3 4)
  (vector-map! + v '#(10 20)))
  @result{} #(11 22 3 4)
@end example
@end defun

@defun vector-map-with-index! proc vec1 vec2 @dots{}
@c EN
Like @code{vector-map!}, but @var{proc} receives the current
index as the first argument.  This is equivalent to SRFI-43's
@code{vector-map!} (@pxref{Vector library (Legacy)}).
@c JP
@code{vector-map!}と似ていますが、@var{proc}の第1引数に
現在のインデックスが渡されます。SRFI-43で@code{vector-map!}
と定義されているものと同じ動作です (@ref{Vector library (Legacy)}参照)。
@c COMMON

@example
(rlet1 v (vector 'a 'b 'c)
  (vector-map-with-index! list v))
  @result{} #((0 a) (1 b) (2 c))
@end example

@end defun

@defun vector-for-each proc vec1 vec2 @dots{}
[R7RS base]
@c EN
For all @var{i} below the minimum length of input vectors,
calls @var{proc} with @var{i}-th elements of @var{vec1} @var{vec2}
@dots{}, in increasing order of @var{i}.
@c JP
0から渡されたベクタのうち一番短いものの最大のインデックスまでの@var{i}について、
@var{vec1} @var{vec2} @dots{}のそれぞれ@var{i}番目の要素を引数に
@var{proc}を呼び出します。
@c COMMON

@example
(vector-for-each print '#(a b c))
 @result{} @r{prints @code{a}, @code{b} and @code{c}}.
@end example
@end defun

@defun vector-for-each-with-index proc vec1 vec2 @dots{}
@c EN
Like @code{vector-for-each}, but @var{proc} receives the current index
in the first argument.

This is equivalent to SRFI-43's @code{vector-for-each}.
@xref{Vector library (Legacy)}.
@c JP
@code{vector-for-each}と似ていますが、@var{proc}の第1引数に
現在のインデックスが渡されます。

この手続きはSRFI-43の@code{vector-for-each}と等価です。
@ref{Vector library (Legacy)}参照。
@c COMMON
@end defun

@node Uniform vectors, Bitvectors, Vectors, Vector family
@subsection Uniform vectors
@c NODE ユニフォームベクタ

@c EN
Uniform vectors, or homogeneous numeric vectors, are a special
type of vectors whose elements are of the same numeric type.
It was introduced originally as SRFI-4, revised by SRFI-160,
and now a part of R7RS large (as @code{scheme.vector.@@}).
@c JP
ユニフォームベクタ、あるいは同質な数値ベクタは、
要素として特定の数値型のみを格納する特別なベクタです。
もともとSRFI-4として導入され、SRFI-160で改訂されたのち、
R7RS largeの一部となりました(@code{scheme.vector.@@}モジュール)。
@c COMMON

@c EN
The @code{@@} part is actually one of the following tags, indicating
the type of elements:
@c JP
@code{@@}の部分は実際には要素の型を示す以下のタグのいずれかです。
@c COMMON

@table @code
@item u8
@c EN
Unsigned 8-bit integer - an exact integer between 0 and 255.
@c JP
8ビット符号無し整数 - 0から255までの正確な整数。
@c COMMON
@item s8
@c EN
Signed 8-bit integer - an exact integer between -128 and 127.
@c JP
8ビット符号つき整数 - -128から127までの正確な整数。
@c COMMON
@item u16
@c EN
Unsigned 16-bit integer - an exact integer between 0 and 65535.
@c JP
16ビット符号無し整数 - 0から65535までの正確な整数。
@c COMMON
@item s16
@c EN
Signed 16-bit integer - an exact integer between -32678 and 32767.
@c JP
16ビット符号つき整数 - -32768から32767までの正確な整数。
@c COMMON
@item u32
@c EN
Unsigned 32-bit integer - an exact integer between 0 and 2^32 - 1.
@c JP
32ビット符号無し整数 - 0から 2^32 - 1 までの正確な整数。
@c COMMON
@item s32
@c EN
Signed 32-bit integer - an exact integer between -(2^31) and 2^31 - 1.
@c JP
32ビット符号つき整数 - -(2^31) から 2^31 - 1 までの正確な整数。
@c COMMON
@item u64
@c EN
Unsigned 64-bit integer - an exact integer between 0 and 2^64 - 1.
@c JP
64ビット符号無し整数 - 0から 2^64 - 1 までの正確な整数。
@c COMMON
@item s64
@c EN
Signed 64-bit integer - an exact integer between -(2^63) and 2^63 - 1.
@c JP
64ビット符号つき整数 - -(2^63) から 2^63 - 1 までの正確な整数。
@c COMMON
@item f16
@c EN
16-bit floating point number (10-bit mantissa and 5-bit exponent),
as inexact real.
@c JP
16ビット浮動小数点数(仮数部10ビット、指数部5ビット)で表される非正確な実数
@c COMMON
@item f32
@c EN
IEEE single-precision floating point number
as inexact real.
@c JP
IEEE単精度浮動小数点数で表される非正確な実数
@c COMMON
@item f64
@c EN
IEEE double-precision floating point number
as inexact real.
@c JP
IEEE倍精度浮動小数点数で表される非正確な実数
@c COMMON
@item c32
@c EN
Inexact complex, consists of a pair of 16-bit floating point numbers.
@c JP
2つの16ビット浮動小数点数で表される非正確な複素数
@c COMMON
@item c64
@c EN
Inexact complex, consists of a pair of IEEE single-precision floating
point numbers.
@c JP
2つのIEEE単精度浮動小数点数で表される非正確な複素数
@c COMMON
@item c128
@c EN
Inexact complex, consists of a pair of IEEE double-precision floating
point numbers.
@c JP
2つのIEEE倍精度浮動小数点数で表される非正確な複素数
@c COMMON
@end table

@c EN
There are some advantages of using uniform vectors over normal
(heterogeneous) vectors.  It may be more compact than the normal
vectors.  Some operations (especially Gauche's extension of vector
arithmetic operations) can bypass type check and conversion of
individual elements, thus be more efficient.  And it is much easier
and efficient to communicate with external libraries that require
homogeneous array of numbers; for example, OpenGL binding of Gauche
uses uniform vectors extensively.
@c JP
通常のベクタではなくユニフォームベクタを使うことにより得られる利点がいくつかあります。
まず、ユニフォームベクタは通常のベクタよりもコンパクトです。
いくつかのオペレーション(特に、Gaucheの拡張仕様であるベクタ上の数値演算)では、
型検査と型変換を個々の要素に対して行わなくても良いため、
極めて効率の良い演算が可能です。さらに、
数値の配列を扱う外部のライブラリとのインタフェースが容易です。
例えば、GaucheのOpenGLバインディングではユニフォームベクタを多用しています。
@c COMMON

@c EN
Gauche has only a handful primitive operations on uniform vectors
as a built-in, but the @code{gauche.uvector} module, or
@code{scheme.vector.@@} module (@code{(scheme vector @@)} library
in R7RS programs), provide a complehensive set of operations.
@xref{Uniform vector library}, and @pxref{R7RS uniform vectors}.
@c JP
Gaucheは組み込みではごく基本的な手続きしか提供しませんが、
@code{gauche.uvector}モジュールや@code{scheme.vector.@@}モジュール
(R7RSでは@code{(scheme vector @@)}ライブラリ)では包括的な操作を提供しています。
@ref{Uniform vector library}および@ref{R7RS uniform vectors}参照。
@c COMMON

@c EN
@subsubheading Uvector classes
@c JP
@subsubheading uvectorクラス
@c COMMON

@deftp {Abstract Class} <uvector>
@c EN
The base class of uniform vector classes.  It inherits @code{<sequence>}
(@pxref{Sequence framework}).
@c JP
ユニフォームベクタクラスのベースクラスです。@code{<sequence>}を継承します
(@ref{Sequence framework}参照)。
@c COMMON
@end deftp


@deftp {Builtin Class} <@@vector>
@clindex s8vector
@clindex u8vector
@clindex s16vector
@clindex u16vector
@clindex s32vector
@clindex u32vector
@clindex s64vector
@clindex u64vector
@clindex f16vector
@clindex f32vector
@clindex f64vector
@clindex c32vector
@clindex c64vector
@clindex c128vector
@c MOD gauche.uvector
@c EN
A class for @@vector, where @code{@@} is one of the uvector tags
(@code{u8}, @code{s8}, @dots{}).
It inherits @code{<uvector>}.

It implements sequence protocol (@pxref{Sequence framework})),
so you can convert a sequence of
real numbers into a uvector using @code{coerce-to},
if every elements is valid for the uvector.
@c JP
@@vectorのクラス。@code{@@}の部分はuvectorタグ
(@code{u8}、@code{s8}、@dots{}) です。
@code{<uvector>}を継承します。

sequenceプロトコル(@ref{Sequence framework}参照)を実装しているので、
数値の並びを@code{coerce-to}を使ってuvectorに変換することができます。
ただし各要素はuvectorの要素として有効な範囲の値でなればなりません。
@c COMMON

@example
(use gauche.sequence)
(coerce-to <u8vector> '(1 2 3)) @result{} #u8(1 2 3)
@end example
@end deftp

@c EN
@subsubheading Uvector literals
@c JP
@subsubheading uvectorリテラル
@c COMMON

@deftp {Reader Syntax} @code{#u8(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s8(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#u16(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s16(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#u32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#u64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#f16(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#f32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#f64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#c32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#c64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#c128(@var{n} @dots{})}
@lxindex #s8
@lxindex #u8
@lxindex #s16
@lxindex #u16
@lxindex #s32
@lxindex #u32
@lxindex #s64
@lxindex #u64
@lxindex #f16
@lxindex #f32
@lxindex #f64
@lxindex #c32
@lxindex #c64
@lxindex #c128
@c EN
Denotes a literal homogeneous vector.

(Note: R7RS bytevector is the same as u8vector, and can be written
as @code{#u8(@dots{})}.)
@c JP
リテラルの単一型のベクタを記述します。

(註: R7RSのバイトベクタはu8vectorと同じで、@code{#u8(@dots{})}で表記できます。)
@c COMMON
@example
#s8(3 -2 4)
#u32(4154 88357 2 323)
#f32(3.14 0.554525 -3.342)
@end example

@c EN
Gauche also supports SRFI-207 (String-notated bytevector) style bytevector
literal.  It is a prefix @code{#u8} followed by a string literal, in which
only ASCII characters and escaped single-octets (i.e. @code{\xNN;} where
@code{N} is a hexadecimal digit) are allowed.  It allows to naturally
use bytevectors as a bytestring.
@xref{String-notated bytevectors}, for operations on bytestrings.
@c JP
Gaucheはまた、SRFI-207 (文字列表示のバイトベクタ) 形式の
バイトベクタリテラルをサポートします。これは、@code{#u8}プレフィクスの後に
文字列リテラルが続くものです。ただしその文字列リテラルには、
ASCII文字か@code{\xNN;} (@code{N}は十六進数) でエスケープされたオクテットのみが
許されます。この表記で、バイトベクタをバイトストリングとして自然に扱うことができます。
バイトストリングの操作に関しては@ref{String-notated bytevectors}を参照してください。
@c COMMON

@example
#u8"ABC\x00;D" @result{} #u8(65 66 67 0 68)
@end example
@end deftp

@c EN
@subsubheading Uvector constructors
@c JP
@subsubheading uvectorのコンストラクタ
@c COMMON

@defun make-s8vector len :optional fill
@defunx make-s8vector len :optional fill
@defunx make-u8vector len :optional fill
@defunx make-s16vector len :optional fill
@defunx make-u16vector len :optional fill
@defunx make-s32vector len :optional fill
@defunx make-u32vector len :optional fill
@defunx make-s64vector len :optional fill
@defunx make-u64vector len :optional fill
@defunx make-f16vector len :optional fill
@defunx make-f32vector len :optional fill
@defunx make-f64vector len :optional fill
@defunx make-c32vector len :optional fill
@defunx make-c64vector len :optional fill
@defunx make-c128vector len :optional fill
[R7RS vector.@@]
@c EN
Constructs a @@vector of length @var{len}.  The elements are
initialized by a number @var{fill}.   For exact integer vectors,
@var{fill} must be an exact integer and in the valid range.
If @var{fill} is omitted, the content of the vector is undefined.
@c JP
長さ@var{len}の@@vectorを作成して返します。各要素は@var{fill}で
初期化されます。正確な整数のベクタに対しては、@var{fill}は正確な整数でなければならず、
また有効な範囲内の値でなければなりません。
@var{fill}が省略された場合、各要素の初期値は不定です。
@c COMMON
@example
(make-u8vector 4 0) @result{} #u8(0 0 0 0)
@end example
@end defun

@c EN
@subsubheading Uvector generic operations
@c JP
@subsubheading uvectorのジェネリックな操作
@c COMMON

@defun uvector? obj
@c EN
Returns @code{#t} iff @var{obj} is one of the uniform vectors.
See below for predicates for specific type of uvector.
@c JP
@var{obj}がユニフォームベクタのいずれかなら@code{#t}を、
そうでなければ@code{#f}を返します。
特定の型のuvectorを検査する述語については後で説明します。
@c COMMON
@end defun

@defun uvector-length uv
@c EN
Returns the length (the number of elements) of uvector @var{uv}.
An error is raised if @var{uv} is not a uvector.

Type specific length procedures are provided in @code{scheme.vector.@@}
and @code{gauche.uvector} (@pxref{Uniform vector library}).

To get the size of the binary data the content of the uvector actually
occupies, use @code{uvector-size} in @code{gauche.uvector}.
@c JP
uvector@var{uv}の長さ(要素数)を返します。
@var{uv}がuvectorでなければエラーを投げます。

特定の型のuvectorの長さを取る手続きは、@code{scheme.vector.@@}および
@code{gauche.uvector}にあります (@ref{Uniform vector library}参照)。

uvectorの内容がバイナリデータとして占有する大きさを知りたければ、
@code{gauche.uvector}の@code{uvector-size}が使えます。
@c COMMON
@end defun

@defun uvector-ref uv k :optional fallback
@c EN
Generic uvector accessor.  Returns @var{k}-th element of a uniform
vector @var{uv}.  If @var{k} is out-of-range, @var{fallback} is
returned if provided, or an error is thrown otherwise.

This is handy to write a generic code that works on any kind of
uniform vector, but this is slower than the specific versions.
Gauche's compiler recognizes the specific versions of referencer and
generate very efficient code for them, while this generic version
becomes a normal procedure call.   In inner-loop it can make a big
difference.

See below for the type-specific accessors.

@code{(setter uvector-ref)} is @code{uvector-set!}.
@c JP
汎用的なuvectorのアクセサです。uvector @var{uv}の@var{k}番目の
要素を返します。@var{k}が範囲外の場合、@var{fallback}が与えられていればそれが
返され、そうでなければエラーが投げられます。

この手続きは様々な種類のユニフォームベクタに対して動作するような一般的なコードを
書く際にとても便利ですが、それぞれの種類のユニフォームベクタ専用の
アクセサに比べると遅いです。Gaucheのコンパイラは@code{@@vector-ref}の
呼び出しを認識して非常に効率の良いコードを出すのに対し、
この手続きは通常の手続き呼び出しになるからです。内部のループ内で呼び出す場合、
これは大きな差になるかもしれません。

型ごと専用のアクセサは下で説明します。

なお、@code{(setter uvector-ref)}は@code{uvector-set!}です。
@c COMMON
@end defun

@defun uvector-set! uv k val :optional clamp
@c EN
Generic uvector setter.  Mutate @var{k}-th element of
uvector @var{uv} with @var{val}.
An error is thrown if @var{k} is out-of-range, or @var{uv} is immutable.

Optional @var{clamp} argument specifies the behavior when
@var{val} is out of valid range.  It can be @code{#f} or
one of the symbols @code{low}, @code{high}, or @code{both}.
@xref{Uniform vector library}, for the meanings of the clamp argument.
The default is @code{#f}, which raises an error on out-of-range value.
@c JP
汎用的なuvectorのセッターです。uvector @var{uv}の@var{k}番目の要素を
@var{val}で置き換えます。
@var{k}が範囲外であったり、
@var{uv}が変更不可である場合はエラーが投げられます。

省略可能な引数@var{clamp}が、@var{val}が正しい範囲外の数であった場合の動作を指定します。
この引数は@code{#f}か、
シンボル@code{low}、@code{high}、@code{both}のいずれかでなければなりません。
この意味については@ref{Uniform vector library}を参照してください。
デフォルトは@code{#f}で、範囲外の値についてはエラーを投げます。
@c COMMON
@end defun


@c EN
@subsubheading Uvector type-specific operations
@c JP
@subsubheading uvectorの型ごとの操作
@c COMMON

@c EN
Type-specific predicates, accessors and modifiers are provided in the core
library; all the rest are in @code{scheme.vector.@@} or @code{gauche.uvector}
(@pxref{Uniform vector library}).
@c JP
型ごとの述語、アクセサ、セッタはここで提供されます。
他の手続きについては@code{scheme.vector.@@}や@code{gauche.uvector}を
利用してください (@ref{Uniform vector library}参照)。
@c COMMON

@deffn {Function} @@vector? obj
@findex s8vector?
@findex u8vector?
@findex s16vector?
@findex u16vector?
@findex s32vector?
@findex u32vector?
@findex s64vector?
@findex u64vector?
@findex f16vector?
@findex f32vector?
@findex f64vector?
@findex c32vector?
@findex c64vector?
@findex c128vector?
[R7RS vector.@@]
@c EN
Returns @code{#t} iff @var{obj} is a @@vector, @code{#f} otherwise.
The @code{@@} part is one of the uvector tags (@code{u8} etc.).
@c JP
@var{obj}が@@vectorなら@code{#t}を、そうでなければ@code{#f}を返します。
@code{@@}の部分はuvectorタグ(@code{u8}等)です。
@c COMMON
@end deffn

@deffn {Function} @@vector-ref vec k :optional fallback
@findex u8vector-ref
@findex s8vector-ref
@findex u16vector-ref
@findex s16vector-ref
@findex u32vector-ref
@findex s32vector-ref
@findex u64vector-ref
@findex s64vector-ref
@findex f16vector-ref
@findex f32vector-ref
@findex f64vector-ref
@findex c32vector-ref
@findex c64vector-ref
@findex c128vector-ref
[R7RS vector.@@]
@c EN
Returns the @var{k}-th element of @@vector @var{vec}.
The @code{@@} part is one of the uvector tags (@code{u8} etc.).

If the index @var{k} is out of the valid range, an error is signaled
unless an optional argument @var{fallback} is given; in that case,
@var{fallback} is returned.

Note that the generic function @code{ref} can be used as well,
if you import @code{gauche.collection}.
@c JP
@@vector @var{vec}の@var{k}番目の要素を返します。
@code{@@}の部分はuvectorタグ(@code{u8}等)です。

@var{k}が有効な範囲外であった場合、通常はエラーが通知されますが、
省略可能な引数@var{fallback}が与えられている場合はそれが返されます。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{ref}を使うこともできます。
@c COMMON

@example
(u16vector-ref '#u16(111 222 333) 1) @result{} 222

(use gauche.collection)
(ref '#u16(111 222 333) 1) @result{} 222
@end example

@c EN
Setter of @code{@@vector-ref} is @code{@@vector-set!}.
@c JP
@code{@@vector-ref}のsetterは@code{@@vector-set!}です。
@c COMMON

@example
(use gauche.uvector)
(define v (u8vector 1 2 3))
(set! (u8vector-ref v 1) 99)

v @result{} #u8(1 99 3)
@end example
@end deffn

@deffn {Function} @@vector-set! vec k n :optional clamp
@findex u8vector-set!
@findex s8vector-set!
@findex u16vector-set!
@findex s16vector-set!
@findex u32vector-set!
@findex s32vector-set!
@findex u64vector-set!
@findex s64vector-set!
@findex f16vector-set!
@findex f32vector-set!
@findex f64vector-set!
@findex c32vector-set!
@findex c64vector-set!
@findex c128vector-set!
[R7RS vector.@@]
@c EN
Sets a number @var{n} to the @var{k}-th element of @@vector @var{vec}.
The @code{@@} part is one of the uvector tags (@code{u8} etc.).

Optional @var{clamp} argument specifies the behavior when
@var{n} is out of valid range.   It can be @code{#f} or
one of the symbols @code{low}, @code{high}, or @code{both}.
@xref{Uniform vector library}, for the meanings of the clamp argument.
The default is @code{#f}, which raises an error on out-of-range value.

Note that the setter of the generic function @code{ref} can be used as well,
if you import @code{gauche.collection}.
@c JP
@@vector @var{vec}の@var{k}番目の要素に数値@var{n}をセットします。
@code{@@}の部分はuvectorタグ(@code{u8}等)です。
省略可能な引数@var{clamp}が、@var{n}が正しい範囲外の数であった場合の動作を指定します。
この引数は@code{#f}か、
シンボル@code{low}、@code{high}、@code{both}のいずれかでなければなりません。
この意味については@ref{Uniform vector library}を参照してください。
デフォルトは@code{#f}で、範囲外の値についてはエラーを投げます。

モジュール@code{gauche.collection}をインポートしていれば、
総称関数@code{ref}のsetter手続きを使うこともできます。
@c COMMON
@example
(let ((v (s32vector -439 852 8933)))
  (s32vector-set! v 1 4)
  v)
 @result{} #s32vector(-439 4 8933)

(use gauche.collection)
(let ((v (s32vector -439 852 8933)))
  (set! (ref v 1) 4)
  v)
 @result{} #s32vector(-439 4 8933)
@end example
@end deffn

@c EN
@subsubheading Conversion between strings and uvectors
@c JP
@subsubheading 文字列とuvectorの変換
@c COMMON

@c EN
Two sets of conversion procedures are provided.  The first set is
to convert strings to u8/s8 vector and vice versa, taking multibyte
representation of a string as a byte vector.  The second set is
to convert strings to u32/s32 vector and vice versa, regarding
a string as a sequence of Unicode codepoints.
@c JP
二種類の変換手続きが提供されます。
最初のは、文字列とu8/s8ベクタとを相互に変換するもので、
文字列のマルチバイト表現をバイトベクタとみなします。
もうひとつは文字列とu32/s32ベクタとを相互に変換するもので、
文字列をUnicodeコードポイントの列とみなします。
@c COMMON

@c EN
For portable Scheme code, SRFI-181 provides conversion between
strings and bytevectors, specifying character encodings
(@pxref{Transcoded ports}).
@c JP
ポータブルなSchemeコードを書くには、SRFI-181が提供する
文字列とバイトベクタの変換手続きが使えるでしょう。
文字エンコーディングを指定することもできます
(@ref{Transcoded ports}参照)。
@c COMMON

@defun string->s8vector string :optional start end immutable?
@defunx string->u8vector string :optional start end immutable?
@c EN
Returns an s8vector or u8vector whose byte sequence is the same
as the internal representation of the given string.
Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} (not the byte position) inside @var{string} to be
converted.

By default, the content of the string is copied to a newly created
mutable uvector.  However, if a true value is given to the
optional @var{immutable?} argument, the result is an immutable
uvector, and it may avoid copying the string body (note that
in Gauche, the body of string is immutable; @code{string-set!} creates
a new body, so changing the original string won't affect the
uvector created by @code{string->u8vector} with @code{immutable?} flag.)

These procedures are useful when you want to access byte
sequence of the string randomly.
@c JP
与えられた文字列の内部表現のバイト列と同じバイト列を持つs8vectorもしくは
u8vectorを返します。省略可能な範囲引数@var{start}、@var{end}は、
変換される文字列中の文字位置を指定します (バイト位置ではないことに注意)。

デフォルトでは、元の文字列の内容が新たに作られる変更可能なユニフォームベクタへと
コピーされ、そのベクタが返されます。しかし、省略可能引数@var{immutable?}に
真の値が渡された場合、返されるユニフォームベクタは変更不可能となり、
また文字列本体のコピーが避けられる可能性があります。
(Gaucheでは、文字列本体は変更不可能で、@code{string-set!}は新たな
文字列本体を作り出します。したがって@code{string->u8vector}の
@code{immutable?}に@code{#t}を渡してユニフォームベクタを作った後、
元の文字列を変更しても、作られたユニフォームベクタは変更されません。)

これらの手続きは、文字を構成するバイト列をランダムにアクセスしたい場合などに
有用です。
@c COMMON

@example
(string->u8vector "abc") @result{} #u8(97 98 99)

@c JP
;; 内部コードがEUCの場合
(string->u8vector "いろは") @result{} #u8(164 164 164 237 164 207)
@c COMMON
@end example

@example
(string->u8vector "very large string .... " 0 -1 #t)
@c EN
  @result{} #u8(...)  ; @r{immutable, sharing content with the original string}
@c JP
  @result{} #u8(...)  ; @r{変更不可、元の文字列と内容を共有}
@c COMMON
@end example

@end defun

@defun string->s8vector! target tstart string :optional start end
@defunx string->u8vector! target tstart string :optional start end
@c EN
@var{Target} must be an s8vector or a u8vector, respectively.
@var{Target} must be mutable.
Like copies the raw byte representation of @var{string}
into @var{target} beginning from index @var{tstart}.
@c JP
@var{target} は、それぞれ s8vector あるいは u8vector でなければなりません。
@var{target} は、変更可能でなければなりません。
@var{string} の生バイト表現を @var{target} へインデックス @var{tstart}
からコピーします。
@c COMMON

@c EN
Returns @var{target}.
@c JP
@var{target} を返します。
@c COMMON

@example
(let ((target (make-u8vector 10 0)))
  (string->u8vector! target 3 "abcde"))
 @result{} #u8(0 0 0 97 98 99 100 101 0 0)
@end example

@end defun

@defun s8vector->string vec :optional start end terminator
@defunx u8vector->string vec :optional start end terminator
@c EN
Converts a byte sequence in s8vector or u8vector to a string that
has the same byte sequence.  Optional range arguments @var{start} and
@var{end} specifies the byte position in @var{vec} to be converted.

The optional @var{terminator} argument can be an exact integer or
@code{#f} (default).  If it is an exact integer, and it appears
in @var{vec}, the string terminates right before it.
For example, you can give 0 as @var{terminator}
to read a NUL-terminated string from a buffer.

@example
(u8vector->string '#u8(65 66 0 67 68) 0 5)   @result{} "AB\0CD"
(u8vector->string '#u8(65 66 0 67 68) 0 5 0) @result{} "AB"
@end example

Note that these procedure may result an incomplete string if
@var{vec} contains a byte sequence invalid as utf-8 encoding.
@c JP
与えられたs8vectorもしくはu8vector @var{vec}のバイト列と同じ内部バイト列を
持つ文字列を作成して返します。省略可能な範囲引数@var{start}、@var{end}は、
@var{vec}中の変換されるべき範囲をバイト位置で指定します。

省略可能引数@var{terminator}は正確な整数か@code{#f}でなければなりません
(@code{#f}がデフォルト)。正確な整数が与えられた場合、@var{vec}の中に
その数値が現れれば、その直前までが結果の文字列となります。
例えば0を与えることで、バッファからNUL終端された文字列を読むことができます。

@example
(u8vector->string '#u8(65 66 0 67 68) 0 5)   @result{} "AB\0CD"
(u8vector->string '#u8(65 66 0 67 68) 0 5 0) @result{} "AB"
@end example

@var{vec}中のバイト列がutf-8として不正な値を持っていた場合は、
不完全な文字列が返されます。
@c COMMON
@end defun

@defun string->s32vector string :optional start end endian
@defunx string->u32vector string :optional start end endian
@c EN
Returns an s32vector or u32vector whose elements are
the internal codes of the characters in the string.
Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} inside @var{string} to be
converted.
@c JP
与えられた文字列@var{string}の各文字の内部コードを値として持つ
s32vectorもしくはu32vectorを返します。
省略可能な範囲引数@var{start}、@var{end}は、
変換される文字列中の文字位置を指定します。
@c COMMON

@c EN
The optional @var{endian} argument specifies the endianness to store
codepoint value into the uvector.  When omitted or @code{#f},
we use the platform's
native endianness.  You can give a symbol @code{big-endian}, @code{big},
@code{little-endian}, @code{little} or @code{arm-little-endian} to use a specific
endianness.  Note that when you access the resulting uvector,
the platform's native endianness is used.
@c JP
省略可能な@var{endian}引数は、uvectorにコードポイント値を格納する際の
バイトオーダーを指定します。省略された場合や@code{#f}の場合は、
プラットフォームのネイティブバイトオーダーが使われます。
シンボル@code{big-endian}、@code{big}、
@code{little-endian}、@code{little}、@code{arm-little-endian}で
特定のバイトオーダーを指定できます。
結果のuvectorにアクセスする時にはネイティブバイトオーダーが使われることに注意してください。
@c COMMON

@c EN
These procedures are useful when you want to access
the characters in the string randomly.
@c JP
これらの手続きは、文字列中の文字をランダムにアクセスする場合に便利です。
@c COMMON


@end defun

@defun string->s32vector! target tstart string :optional start end endian
@defunx string->u32vector! target tstart string :optional start end endian
@c EN
@var{Target} must be a mutable s32vector or u32vector, respectively.
Fill the @var{target} from position @var{tstart} with the codepoint
of each character of @var{string}, until either @var{string} is exhausted
or @var{target} is filled to the end.

Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} inside @var{string} to be
considered.
@c JP
@var{target}は変更可能なs32vectorもしくはu32vectorでなければなりません。
@var{target}の場所@var{tstart}から、@var{string}の各文字のコードポイントを
順に埋めてゆきます。@var{target}ベクタの終端に達するか、文字が無くなるまで繰り返します。

省略可能な引数@var{start}と@var{end}は@var{string}内の文字位置のインデックスで、
考慮する@var{string}の範囲を制限します。
@c COMMON

@c EN
The optional @var{endian} argument specifies the endianness to store
codepoint value into the uvector.  When omitted or @code{#f},
we use the platform's
native endianness.  You can give a symbol @code{big-endian}, @code{big},
@code{little-endian}, @code{little} or @code{arm-little-endian} to use a specific
endianness.  Note that when you access the resulting uvector,
the platform's native endianness is used.
@c JP
省略可能な@var{endian}引数は、uvectorにコードポイント値を格納する際の
バイトオーダーを指定します。省略された場合や@code{#f}の場合は、
プラットフォームのネイティブバイトオーダーが使われます。
シンボル@code{big-endian}、@code{big}、
@code{little-endian}、@code{little}、@code{arm-little-endian}で
特定のバイトオーダーを指定できます。
結果のuvectorにアクセスする時にはネイティブバイトオーダーが使われることに注意してください。
@c COMMON
@end defun

@defun s32vector->string vec :optional start end terminator endian
@defunx u32vector->string vec :optional start end terminator endian
@c EN
Without @var{start} and @var{end}, these procedures work like this:
@c JP
@var{start}と@var{end}を考えなければ、
これらの手続きは次のコードのような動作をします：
@c COMMON
@example
(lambda (vec) (map-to <string> integer->char vec)))
@end example
@c EN
Optional range arguments @var{start} and @var{end} limits
the range of conversion between them.
@c JP
省略可能な範囲引数@var{start}、@var{end}は、
@var{vec}中の変換されるべき範囲を指定します。
@c COMMON

@c EN
The optional @var{terminator} argument must be an exact
integer or @code{#f} (default).  If an integer is given,
and the integer is found in the input,
the output string terminates right before it.
@c JP
省略可能引数@var{terminator}は、正確な整数か@code{#f}でなければ
なりません (@code{#f}がデフォルト)。正確な整数が与えられ、
入力にその数値が見つかった場合は、出力の文字列はその直前で
打ちきられます。
@c COMMON

@c EN
The optional @var{endian} argument specifies the endianness to store
codepoint value into the uvector.  When omitted or @code{#f},
we use the platform's
native endianness.  You can give a symbol @code{big-endian}, @code{big},
@code{little-endian}, @code{little} or @code{arm-little-endian} to use a specific
endianness.
@c JP
省略可能な@var{endian}引数は、uvectorにコードポイント値を格納する際の
バイトオーダーを指定します。省略された場合や@code{#f}の場合は、
プラットフォームのネイティブバイトオーダーが使われます。
シンボル@code{big-endian}、@code{big}、
@code{little-endian}、@code{little}、@code{arm-little-endian}で
特定のバイトオーダーを指定できます。
@c COMMON

@example
(u32vector->string '#u32(65 66 0 67 68) 0 5 0) @result{} "AB"
@end example
@end defun


@node Bitvectors, Weak vectors, Uniform vectors, Vector family
@subsection Bitvectors
@c NODE ビットベクタ

@c EN
A bitvector is a sequence of bits.  Each bit can be considered either
an exact integer 0/1, or a boolean values @code{#f}/@code{#t}.
In the former view, it is similar to a uniform vector, but it has the
interface sufficiently different from uvectors and we provided it as
a disjoint type.

Gauche provides a handful of procedures in the core,
and @code{gauche.bitvector} provides comprehensive utilities.
@xref{Bitvector utilities}, for the details.
For the portable programs, SRFI-178 defines bitvector library,
which is a subset of what Gauche provides (@pxref{Bitvector library}).
@c JP
ビットベクタはビットの並びです。各「ビット」は、0/1の数値としても、
@code{#f}/@code{#t}の論理値としても解釈可能です。
最初の見方では、ビットベクタをユニフォームベクタの一種と考えることもできますが、
インタフェースがそこそこ違っているので、別の型としました。

Gaucheはコアでごく基本的な手続きを提供し、また
@code{gauche.bitvector}モジュールで包括的なビットベクタユーティリティを提供します
(@ref{Bitvector utilities}参照)。
ポータブルなプログラムを書く場合は、SRFI-178がビットベクタライブラリを定義しているので
それを使うと良いでしょう。SRFI-178はGaucheの提供するもののサブセットになっています
(@ref{Bitvector library}参照)。
@c COMMON

@deftp {Builtin class} <bitvector>
@clindex bitvector
@c EN
Bitvector class.  Inherits @code{<sequence>}, so generic sequence opertaions
can be used.  (Generic @code{ref} uses @code{bitvector-ref/int}, for
it matches the external representation of a bitvector.)
@c JP
ビットベクタクラス。@code{<sequence>}を継承し、ジェネリックなシーケンス操作も使えます。
(ジェネリックな@code{ref}については、
外部表現との親和性から@code{bitvector-ref/int}が使われます)。
@c COMMON
@end deftp

@deftp {Reader Syntax} @code{#*@var{b}@dots{}}
@lxindex #*
[SRFI-178]
@c EN
A bitvector literal is @code{#*} followed by zero or more binary digits
@code{0} or @code{1}.
@c JP
ビットベクタリテラルは、@code{#*}のあとに@code{0}や@code{1}が0個以上続いたものです。
@c COMMON

@example
#*10010010           ; bitvector of length 8
#*                   ; bitvector of length 0
@end example

@c EN
A bitvector literal is delimited by one of delimiter characters or an EOF.
@c JP
ビットベクタリテラルはデリミタ文字かEOFで区切られます。
@c COMMON

@example
#*10010abc           ; error
#*10001(a b c)       ; a bitvector, followed by a list
@end example

@c EN
Note: With this rule, @code{#*"..."} should be read as a zero-length
bitvector followed by a string, for @code{"} is a delimiter.  However,
Gauche used that syntax for incomplete strings (our overlook!).
Since incomplete string literals is rare (incomplete strings are
something that unexpectedly happen in the practical situation, but
not to be used actively), we changed incomplete string literals to
@code{#**"..."} since 0.9.10 (@pxref{Incomplete strings}).
@c JP
註: このルールでは、@code{#*"..."}は、
長さゼロのビットベクタと文字列、と解釈されるべきです。@code{"}は区切り文字ですから。
しかし、Gaucheでは長らくこの構文を不完全文字列に使っていました。
(長さゼロのビットベクタがあることを見落としてました!)
不完全文字列の外部表記が必要になることは滅多にないので
(不完全文字列は現実のデータを扱う際にどうしても「生じてしまう」もので、
積極的に使うべきではありません)、
その表記は0.9.10から@code{#**"..."}に変更されました (@ref{Incomplete strings})。
@c COMMON

@c EN
For the backward compatibility, the current version reads @code{#*"..."}
as an incomplete string.  If the reader lexical mode is
@code{warn-legacy} (@pxref{Reader lexical mode}), such literals are
warned.  We'll gradually migrate to make @code{#*"..."} read
as a bytevector followed by a string.
@c JP
後方互換性のため、現在のバージョンでは@code{#*"..."}は不完全文字列として読まれます。
リーダー字句モードが@code{warn-legacy}であれば、この形のリテラルに対して警告が出されます
(@ref{Reader lexical mode})。
将来的には@code{#*"..."}はビットベクタと文字列として読まれるように徐々に以降する予定です。
@c COMMON
@end deftp

@defun bit->integer bit
@defunx bit->boolean bit
[SRFI-178]
@c EN
Many bitvector operations can accept bit as a boolean (@code{#f}/@code{#t})
or an exact integer (0/1).  These are utility procedures to obtain
desired type.  The @var{bit} argument must be either one of @code{#f}, @code{#t},
0 or 1.  They return 0/1 and @code{#f}/@code{#t}, respectively.
An error is signalled if @var{bit} is other than those values.
@c JP
ビットベクタAPIでビットが必要なところには、論理値(@code{#f}/@code{#t})あるいは
正確な整数 (0/1)を渡すことができます。これらの手続きは有効なビット値をそれぞれ0/1もしくは
@code{#f}/@code{#t}に揃えます。@var{bit}が有効なビット値でなければエラーが投げられます。
@c COMMON
@end defun

@defun bitvector b @dots{}
[SRFI-178]
@c EN
Creates and returns a bitvector whose elements are @var{b} @dots{}.
Each argument must be a bit (boolean or 0 or 1).
@c JP
要素が@var{b} @dots{}であるビットベクタを作って返します。
各引数はビット値でなければなりません (論理値か0か1)。
@c COMMON

@example
(bitvector 0 1 0 0 1 0 0 0 1) @result{} #*010010001
(bitvector) @result{} #*
@end example
@end defun

@defun make-bitvector len :optional init
[SRFI-178]
@c EN
Creates and returns a bitvector with length @var{len}, and all elements
being initialized by @var{init}, which must be a bit
(boolean or 0 or 1).

If @var{init} is omitted, the content of the bitvector is undefined
(currently we fill it with 0, but don't count on it.)
@c JP
長さ@var{len}のビットベクタを作って返します。各要素は@var{init}で初期化されます。
@var{init}はビット値(論理値か0か1)でなければなりません。

@var{init}が省略された場合、ビットベクタの内容は未定義です。
(今のところ0で初期化されますが、それをあてにしてはいけません)。
@c COMMON

@example
(make-bitvector 5 #f)  @result{} #*00000
(make-bitvector 7 1)   @result{} #*1111111
@end example
@end defun

@defun bitvector? obj
[SRFI-178]
@c EN
Return @code{#t} iff @var{obj} is an bitvector.
@c JP
@var{obj}がビットベクタなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun list->bitvector lis
[SRFI-178]
@c EN
@var{Lis} must be a list of bits (0, 1 or booleans).  Returns a bitvector
whose elements consist of elements of @var{lis}.
@c JP
@var{lis}はビット値(論理値、0、1)のリストでなければなりません。
それらの値を要素とするビットベクタを作って返します。
@c COMMON

@example
(list->bitvector '(#t #f #t #t #f))  @result{} #*10110
(list->bitvector '(0 1 1 1 0 1 0 1)) @result{} #*01110101
@end example
@end defun

@defun string->bitvector s
[SRFI-178]
@c EN
If @var{s} is a valid bitvector literal (@code{#*@var{b}...} where @var{b}
is either @code{0} or @code{1}), returns a bitvector represented by
the string.  Otherwise, @code{#f} is returned.
@c JP
@code{s}がビットベクタリテラルとして有効な文字列
(@code{#*@var{b}...}で@var{b}が@code{0}か@code{1})
であれば、それで表現されるビットベクタを返します。そうでなければ@code{#f}が返されます。
@c COMMON

@example
(string->bitvector "#*1010001") @result{} #*1010001
(string->bitvector "#*1001020") @result{} #f
@end example

@c EN
Note that this isn't a sequence-conversion, but rather a conversion from
external representation.
@c JP
これはシーケンスとしての変換ではなく、外部表現からの変換であることに注意してください。
@c COMMON
@end defun

@defun bitvector->string bv
[SRFI-178]
@c EN
Convert a bitvector @var{bv} to a string representation @code{#*@var{b}...}.
@c JP
ビットベクタ@var{bv}の外部表現@code{#*@var{b}...}を文字列として返します。
@c COMMON

@example
(bitvector->string #*1001010) @result{} "#*1001010"
@end example

@c EN
Note that this isn't a sequence-conversion, but rather a conversion to
external representation.
@c JP
これはシーケンスとしての変換ではなく、外部表現への変換であることに注意してください。
@c COMMON
@end defun

@defun bitvector-ref/int bv k :optional fallback
@defunx bitvector-ref/bool bv k :optional fallback
[SRFI-178+]
@c EN
Retrieves the @var{k}-th bit of a bitvector @var{bv} as an integer or
a boolean value, respectively.  If @var{k} is out of range,
@var{fallback} is returned if it is given, or an error is raised otherwise.
The @var{fallback} argument is Gauche's extension.
@c JP
ビットベクタ@var{bv}の@var{k}番目の要素を、それぞれ整数0/1か論理値として返します。
@var{k}が範囲外だった場合、@var{fallback}が与えられていればそれが返され、
与えられていなければエラーが投げられます。
@var{fallback}引数はGaucheの拡張です。
@c COMMON

@example
(bitvector-ref/int #*1010001 0)  @result{} 1
(bitvector-ref/bool #*1010001 0) @result{} #t
@end example

@c EN
If you use a universal accessor @code{ref}/@code{~}, it returns
the bit value as an integer (@pxref{Universal accessor}).
@c JP
万能アクセサ@code{ref}/@code{~}をビットベクタに使った場合は、
整数値が返されます (@ref{Universal accessor})。
@c COMMON

@example
(~ #*11001001 1) @result{} 1
@end example
@end defun

@defun bitvector-set! bv k bit
[SRFI-178]
@c EN
Sets the @var{k}-th bit of a bitvector @var{bv} with @var{bit}, which must
be either one of 0, 1, @code{#f} or @code{#t}.  An error is raised
if @var{k} is out of range.
@c JP
ビットベクタ@var{bv}の@var{k}番目の要素にビット値@var{bit}をセットします。
@var{bit}は0、1、@code{#f}、@code{#t}のいずれかでなければなりません。
@var{k}が範囲外ならエラーが投げられます。
@c COMMON

@c EN
This procedure is set as the setter of @code{bitvector-ref/int} and
@code{bitvector-ref/bool}.
Since a bitvector is a sequence, you can also use
@code{(setter ref)}/@code{(setter ~)}:
@c JP
この手続きは@code{bitvector-ref/int}と@code{bitvector-ref/bool}のsetterとして
設定されています。また、ビットベクタはシーケンスなので、
@code{(setter ref)}/@code{(setter ~)}も使えます。
@c COMMON

@example
(rlet1 z (make-bitvector 5 0)
  (set! (~ z 2) #t))
  @result{} #00100
@end example
@end defun

@defun bitvector-copy bv :optional start end
[SRFI-178]
@c EN
Returns a copy of a bitvector @var{bv}.  If optional @var{start} and
@var{end} indexes are given, the copy is limited in that range,
where @var{start} is inclusive and @var{end} is exclusive.
@c JP
ビットベクタ@var{bv}のコピーを作って返します。
省略可能引数@var{start}、@var{end}でインデックスが与えられた場合は、
その範囲内がコピーされます。@var{start}は含まれ、@var{end}は含まれません。
@c COMMON

@example
(bitvector-copy #*101001000 3)   @result{} #*001000
(bitvector-copy #*100101000 2 7) @result{} #*01010
@end example
@end defun

@defun bitvector-copy! target tstart src :optional sstart send
[SRFI-178]
@c EN
Copy a bitvector @var{src} into a mutable bitvector @var{target} starting
from @var{tstart}, mutating @var{target}.  Optional @var{sstart} and
@var{send} delimits the range in @var{src}.
@c JP
ビットベクタ@var{src}の内容を、
変更可能なビットベクタ@var{target}の@var{tstart}インデックス以降にコピーして
@var{target}の内容を書き換えます。省略可能な@var{sstart}、@var{send}は
@var{src}のコピーされる範囲を限定します。
@c COMMON

@example
(rlet1 v (make-bitvector 10 0)
  (bitvector-copy! v 3 #*101101110 2 6))
  @result{} #*0001101000
@end example
@end defun

@defun bitvector-any-value? bv bit :optional start end
@defunx bitvector-every-value? bv bit :optional start end
@c EN
Check if any or every bit of a bitvector @var{bv} is @var{bit}, respectively.
You can pass a boolean value or an exact integer 0 or 1 as @var{bit}.

Optional @var{start}/@var{end} arguments limit the range of bitvector
to look at.
@c JP
それぞれ、ビットベクタ@var{bv}の少なくともひとつ/全てのビットが@var{bit}であるかどうかを
調べます。@var{bit}には真偽値もしくは正確な整数0または1を渡すことができます。

省略可能引数@var{start}/@var{end}は検査する範囲を指定します。
@c COMMON

@example
;; See if at least one '1'
(bitvector-any-value? #*000100 1)   @result{} #t
(bitvector-any-value? #*000000 #t)  @result{} #f

;; See if at least one '0'
(bitvector-any-value? #*110111 #f)  @result{} #t
(bitvector-any-value? #*111111 0)   @result{} #f

;; See if all bits are '1'
(bitvector-every-value? #*11111 #t) @result{} #t
(bitvector-every-value? #*00000 1)  @result{} #f

;; See if all bits are '0'
(bitvector-every-value? #*11111 #f) @result{} #f
(bitvector-every-value? #*00000 0)  @result{} #t
@end example
@end defun

@c EN
The following procedures expose bitvector's internal data.  They are
useful to do tricks such as dumping bitvectors in binary format.  However,
keep in mind that the binary representation of bitvectors may differ
among architectures, or even between Gauche versions.
@c JP
以下の手続きはビットベクタの内部データへのアクセスを可能にします。
これは、例えばビットベクタをバイナリ形式で保存したい、といった場合に便利です。
しかし、ビットベクタの内部表現はアーキテクチャごと、あるいはGaucheの
バージョン間でも異なる可能性があることに留意してください。
@c COMMON

@defun bitvector-word-bits
@c EN
Returns the number of bits in a ``word'' or ``chunk'', with which
a bitvector keeps its internal data.  When you convert between
a bitvector and a uniform vector, the size and boundaries of
the uniform vector must be aligned with the word size.
@c JP
ビットベクタが内部的に扱う「ワード」あるいは「チャンク」の大きさを
ビット数で返します。ビットベクタとユニフォームベクタを相互変換する
場合、ユニフォームベクタの大きさや境界はワード境界に揃っていなければなりません。
@c COMMON
@end defun

@defun bitvector->uvector/shared bv :optional class
@c EN
@var{class} must be a uniform vector class.  If omitted, @code{<u8vector>}
is assumed.

Returns a uniform vector of @var{class}, which shares the internal storage
with a bitvector @var{bv}.
The size of the returned uvector, counted in bits, is always
a multiple of @code{(bitvector-word-bits)}.

If @var{bv}'s size isn't
a multiple of @code{(bitvector-word-bits)}, the remaining bits are padded
with an unspecified value.
Because of this padding, converting a bitvector by
@code{bitvector->uvector/shared} and then converting it back by
@code{uvector->bitvector/shared} may not result in a bitvector @code{equal?}
to the original one.

Since the storage is shared, changes to one are visible in the other.

The order of bits depends on the underlying architecture, or even on
Gauche's version, so you should not assume its portability.
@c JP
@var{class}はユニフォームベクタのクラスでなければなりません。
省略された場合は@code{<u8vector>}が仮定されます。

ビットベクタ@var{bv}と内部領域を共有する、@var{class}のユニフォームベクタを
返します。返されたユニフォームベクタのサイズは、ビット数で数えると、
常に@code{(bitvector-word-bits)}の倍数になります。

@var{bv}のサイズが@code{(bitvector-word-bits)}の倍数でない場合、
余ったビットは未規定の値でパディングされます。このパディングのため、
ビットベクタを@code{bitvector->uvector/shared}で変換し、それを
@code{uvector->bitvector/shared}で戻したとしても、結果のビットベクタが
元のビットベクタと@code{equal?}になるとは限りません。

記憶領域は共有されているため、一方への変更は他方にも反映されます。

ビットの順序は基盤となるアーキテクチャや、場合によってはGaucheの
バージョンに依存します。可搬性は仮定しないでください。
@c COMMON
@end defun

@defun uvector->bitvector/shared uv :optional start end
@c EN
Returns a bitvector which shares the internal storage of a uvector
@var{uv}, in the region specified by @var{start} and @var{end} element
indexes.  If they are omitted, the entire uniform vector is covered.
@var{start} and @var{end} must be aligned with the word boundary
@code{(bitvector-word-bits)}.

The order of bits depends on the underlying architecture, or even on
Gauche's version, so you should not assume its portability.

Since the storage is shared, changes to one are visible in the other.
@c JP
ユニフォームベクタ@var{uv}の内部記憶を共有するビットベクタを返します。
共有される領域は、要素インデックスである@var{start}と@var{end}で指定します。
これらを省略した場合は、ユニフォームベクタ全体が対象となります。
@var{start}と@var{end}はワード境界@code{(bitvector-word-bits)}に
揃っていなければなりません。

ビットの順序は基盤となるアーキテクチャや、場合によってはGaucheの
バージョンに依存します。可搬性は仮定しないでください。

記憶領域は共有されているため、一方への変更は他方にも反映されます。
@c COMMON
@end defun


@node Weak vectors,  , Bitvectors, Vector family
@subsection Weak vectors
@c NODE Weakベクタ

@c EN
A weak pointer is a reference to an object that doesn't prevent
the object from being garbage-collected.
Gauche provides weak pointers as a @emph{weak vector} object.
A weak vector is like a vector of objects, except each object
can be garbage collected if it is not referenced from objects
other than weak vectors.   If the object is collected, the
entry of the weak vector is replaced for @code{#f.}
@c JP
Weak ポインタとは、それが参照しているオブジェクトがガベージコレクトされることを
許すようなポインタです。
Gaucheは@emph{weak ベクタ}オブジェクトによってweak ポインタの機能を提供します。
Weak ベクタは通常のベクタに似ていますが、要素のオブジェクトがweak ベクタ以外から
参照されていない場合、オブジェクトはガベージコレクトされ、weak ベクタの該当するエントリは
@code{#f}で置き換えられます。
@c COMMON
@example
gosh> (define v (make-weak-vector 1))
v
gosh> (weak-vector-ref v 0)
#f
gosh> (weak-vector-set! v 0 (cons 1 1))
#<undef>
gosh> (weak-vector-ref v 0)
(1 . 1)
gosh> (gc)
#<undef>
gosh> (gc)
#<undef>
gosh> (weak-vector-ref v 0)
#f
@end example

@c EN
@xref{R7RS ephemerons}, for R7RS-large way of weak pointers.
@c JP
R7RS-largeでのweakポインタについては@ref{R7RS ephemerons}を参照してください。
@c COMMON

@deftp {Builtin Class} <weak-vector>
@clindex weak-vector
@c EN
The weak vector class.  Inherits @code{<sequence>} and @code{<collection>},
so you can use
@code{gauche.collection} (@pxref{Collection framework}) and
@code{gauche.sequence} (@pxref{Sequence framework}).
@c JP
Weak ベクタのクラスです。@code{<sequence>}と@code{<collection>}を継承しているので、
@code{gauche.collection} (@ref{Collection framework}参照) と
@code{gauche.sequence} (@ref{Sequence framework}参照) も使えます。
@c COMMON
@example
(coerce-to <weak-vector> '(1 2 3 4))
  @result{} a weak vector with four elements
@end example
@end deftp

@defun make-weak-vector size
@c EN
Creates and returns a weak vector of size @var{size}.
@c JP
大きさ@var{size}のweak ベクタを作成して返します。
@c COMMON
@end defun

@defun weak-vector-length wvec
@c EN
Returns the length of a weak vector @var{wvec}.
@c JP
weak ベクタ @var{wvec}の大きさを返します。
@c COMMON
@end defun

@defun weak-vector-ref wvec k :optional fallback
@c EN
Returns @var{k}-th element of a weak vector @var{wvec}.

By default, @code{weak-vector-ref} signals an error if @var{k} is
negative, or greater than or equal to the size of @var{wvec}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.

If the element has been garbage collected, this procedure returns
@var{fallback} if it is provided,  @code{#f} otherwise.

With @code{gauche.sequence} module,
you can also use a method @code{ref}.
@c JP
weak ベクタ @var{wvec}の@var{k}番目の要素を返します。

@code{weak-vector-ref}は@var{k}が負の値であったりベクタの長さより
大きかったりした場合はエラーを通知します。但し、省略可能な引数@var{fallback}
が与えられている場合はその値が返されます。

該当する要素が既にガベージコレクトされていた場合、@var{fallback}が
与えられていればそれが、そうでなければ@code{#f}が返されます。

@code{gauche.sequence}モジュールをロードしていれば、
メソッド@code{ref}も同じ目的で使えます。
@c COMMON
@end defun

@defun weak-vector-set! wvec k obj
@c EN
Sets @var{k}-th element of the weak vector @var{wvec} to @var{obj}.
It is an error if @var{k} is negative or greater than or equal to the
size of @var{wec}.
@c JP
weak ベクタ @var{wvec}の@var{k}番目の要素を@var{obj}に変更します。
@var{k}が負数であったりベクタの長さより大きい場合はエラーとなります。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Dictionaries, Procedures and continuations, Vector family, Core library
@section Dictionaries
@c NODE ディクショナリ

@c EN
A dictionary is a data structure that associates key to value.
Gauche provides hashtables (@pxref{Hashtables}) and treemaps (@pxref{Treemaps})
as the built-in dictionaries.  Some additional libraries provide more
dictionary-type data structures.

A generic interface is defined as a dictionary framework
(@pxref{Dictionary framework}), by which you can use dictionaries without
knowing its details.

R7RS also defines an abstract dictionary interface as @emph{mapping};
@pxref{R7RS mappings}, for the details.
@c JP
ディクショナリは、キーと値を結びつけるデータ構造です。
Gaucheは組み込みのディクショナリとして、ハッシュテーブル(@ref{Hashtables}参照)と
ツリーマップ(@ref{Treemaps}参照)を用意しています。
ライブラリには他にもディクショナリとして振る舞うデータ構造がいくつか提供されます。

さらに、ディクショナリ汎用のインタフェースが、
ディクショナリフレームワークとして提供されます (@ref{Dictionary framework}参照)。
ディクショナリの種類に関わらない操作を書くのに使えます。

R7RSでは、抽象化されたディクショナリインタフェースを@emph{マッピング}として定義しています。
@ref{R7RS mappings}を参照してください。
@c COMMON

@menu
* Hashtables::
* Treemaps::
@end menu

@node Hashtables, Treemaps, Dictionaries, Dictionaries
@subsection Hashtables
@c NODE ハッシュテーブル

@c EN
R7RS-large defines hashtable (@code{scheme.hash-table} module,
@pxref{R7RS hash tables}) but its API is not completely consistent
with Gauche's original hashtables and other native APIs.

Rather than mixing different flavor of APIs, we keep Gauche's native
API consistent, and provide R7RS procedures that are inconsistent
with aliases---specifically, those procedures are suffixed with @code{-r7}
in @code{gauche} module.  For portable programs, you can import
@code{scheme.hash-table} to get R7RS names.
@c JP
R7RS-largeにはハッシュテーブルが定義されています
(@code{scheme.hash-table}モジュール、@ref{R7RS hash tables}参照)。
しかし、そのAPIはGaucheにもともとあったハッシュテーブルや他のネイティブAPIと一貫性を
欠いている部分があります。

APIをごちゃまぜにするよりは、GaucheのネイティブなAPIの一貫性を保つことを重視し、
R7RSの手続きのうちGaucheにそぐわないものは、組み込み関数では別名
(サフィックス@code{-r7}がついたもの)をつけて提供しています。
ポータブルなコードを書く場合は、@code{scheme.hash-table}をインポートすれば
R7RSの名前が使えます。
@c COMMON

@deftp {Builtin Class} <hash-table>
@clindex hash-table
@c EN
Hash table class.  Inherits @code{<collection>} and @code{<dictionary>}.

Gauche doesn't provide immutable hash tables for now.
(If you need immutable maps, @pxref{Immutable map}).
@c JP
ハッシュテーブルのクラスです。@code{<collection>}と@code{<dictionary>}を
継承します。

Gaucheは今のところ、変更不可なハッシュテーブルは提供しません。
(変更不可なマップが必要な場合は、@ref{Immutable map}を参照してください。)
@c COMMON
@end deftp

@c EN
@subheading Hash table properties
@c JP
@subheading ハッシュテーブルのプロパティ
@c COMMON

@defun hash-table? obj
[R7RS hash-table]
@c EN
Returns @code{#t} iff @var{obj} is a hash table.
@c JP
@var{obj}がハッシュテーブルであれば@code{#t}を返します。
@c COMMON
@end defun

@defun hash-table-mutable? ht
[R7RS hash-table]
@c EN
Returns @code{#t} iff a hash table @var{ht} is mutable.
Gauche doesn't have immutable hash tables, so this procedure always
returns @code{#t} for any hash tables.
@c JP
ハッシュテーブル@var{ht}が変更可能なら@code{#t}を返します。
Gaucheは変更不可なハッシュテーブルを持たないので、
どんなハッシュテーブルに関しても手続きは@code{#t}を返します。
@c COMMON
@end defun

@defun hash-table-comparator ht
@c EN
Returns a comparator used in the hashtable @var{ht}.
@c JP
ハッシュテーブル@var{ht}で使われている比較器を返します。
@c COMMON
@end defun

@defun hash-table-num-entries ht
@defunx hash-table-size ht
[R7RS hash-table]
@c EN
Return the number of entries in the hash table @var{ht}.
R7RS name is @code{hash-table-size}.
@c JP
ハッシュテーブル@var{ht}中の要素の個数を返します。
R7RSの名前は@code{hash-table-size}.
@c COMMON
@end defun

@defun hash-table-type ht
@c DEPRECATED
@c EN
This is a deprecated API, superseded by @code{hash-table-comparator}.

Returns one of symbols @code{eq?}, @code{eqv?}, @code{equal?},
@code{string=?}, @code{general}, indicating the type of the hash table @var{ht}.
@c JP
これは古いAPIで、@code{hash-table-comparator}によって置き換えられました。

ハッシュテーブル@var{ht}のタイプに応じて、シンボル
@code{eq?}、@code{eqv?}、@code{equal?}、@code{string=?}、
@code{general}のいずれかを返します。
@c COMMON
@end defun


@c EN
@subheading Hash table constructors and converters
@c JP
@subheading ハッシュテーブルのコンストラクタとコンバータ
@c COMMON

@defun make-hash-table :optional comparator
[R7RS+ hash-table]
@c EN
Creates a hash table.  The @var{comparator} argument
specifies key equality and hash function using a comparator
(@pxref{Basic comparators}).  If omitted, @code{eq-comparator}
is used.  Note that in R7RS, @var{comparator}
argument can't be omitted.

As Gauche's extension, the @var{comparator} argument can also
be one of the symbols
@code{eq?}, @code{eqv?}, @code{equal?} or @code{string=?}.
If it is one of those symbols, @code{eq-comparator},
@code{eqv-comparator}, @code{equal-comparator} and
@code{string-comparator} will be used, respectively.

The comparator must have hash function, of course.  @xref{Hashing},
for the built-in hash functions.  In general, comparators derived from
other comparators having hash functions also have appropriate
hash functions.
@c JP
ハッシュテーブルを作成します。@var{comparator}引数には、
キーの等価判定とハッシュに使う比較器(@ref{Basic comparators}参照)を渡します。
省略された場合は@code{eq-comparator}が使われます。
(R7RSでは@var{comparator}は省略できません。)

Gauche独自拡張として、@var{comparator}にシンボル
@code{eq?}、@code{eqv?}、@code{equal?}、@code{string=?}のいずれかを
指定することもできます。
@code{eq-comparator}、
@code{eqv-comparator}、@code{equal-comparator}、
@code{string-comparator}が使われます。

比較器はハッシュ関数を持っていなければなりません。組み込みのハッシュ関数については
@ref{Hashing}を参照してください。比較器を組み合わせて作られた比較器については、
元の比較器がハッシュ関数を持っていれば、通常は適切なハッシュ関数が設定されます。
@c COMMON
@end defun

@defun hash-table-from-pairs comparator key&value @dots{}
@c EN
Constructs and returns a hash table from given
list of arguments.
The @var{comparator} argument is the same as of @code{make-hash-table}.
Each @var{key&value} must be a pair, and its car is used as a key
and its cdr is used as a value.

Note: This is called @code{hash-table} by 0.9.5.  R7RS introduced
a procedure with the same name, but different interface.
We see R7RS version makes more sense, so we'll eventually switch to it,
but the transition will take long time.
The R7RS interface is available as
@code{hash-table-r7}, and we urge you to use it in the new code,
and replace existing @code{hash-table} with @code{hash-table-from-pairs}.
@c JP
与えられたキーと値の列からハッシュテーブルを構築して
返します。@var{comparator}引数の意味は@code{make-hash-table}と同じです。
各@var{key&value}はペアでなければならず、そのcarがキー、cdrが値として使われます。

註：これは0.9.5まで@code{hash-table}と呼ばれていた手続きです。
R7RSは同名で異なるインタフェースを持つインタフェースを定義しました。
そちらの方が使いやすいので、長期的にはR7RSインタフェースへとスイッチする予定ですが、
それはかなり将来のことになります。
R7RSインタフェースは@code{hash-table-r7}という名前で利用可能なので、
新たなコードはそちらを使うことを強くお勧めします。
また、既存のコードで@code{hash-table}を使っていたら、
@code{hash-table-from-pairs}に直してください。
@c COMMON

@example
(hash-table-from-pairs 'eq? '(a . 1) '(b . 2))
  @equiv{}
  (rlet1 h (make-hash-table 'eq?)
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2))
@end example
@end defun

@defun hash-table comparator key&value @dots{}
@c EN
An alias of @code{hash-table-from-pairs} above.  R7RS introduced the same name
procedure with different interface (see @code{hash-table-r7} below), and
we'd like to switch to it in future.  For now, use either
@code{hash-table-from-pairs} or @code{hash-table-r7},
or import @code{scheme.hash-table} and write in R7RS.
@c JP
@code{hash-table-from-pairs}の別名です。
R7RSが同名で別インタフェースの手続き(下の@code{hash-table-r7}参照)を導入し、
将来的にはGaucheもそちらに移行する予定です。なので今のところ、
@code{hash-table-from-pairs}か@code{hash-table-r7}を使うか、
@code{scheme.hash-table}をインポートしてR7RSとして書いてください。
@c COMMON
@end defun

@defun hash-table-r7 comparator args @dots{}
@c EN
Create and returns a hash table using @var{comparator}.
The @var{args} @dots{} are the contents, alternating keys and values.

This is defined as @code{hash-table} in R7RS @code{scheme.hash-table}
(@pxref{R7RS hash tables}).
@c JP
@var{comparator}を比較器に使うハッシュテーブルを作って返します。
@var{args} @dots{}はキーと値を交互に並べたもので、ハッシュテーブルの内容を指定します。

これはR7RS @code{scheme.hash-table}で@code{hash-table}と定義されている手続きです
(@ref{R7RS hash tables}参照)。
@c COMMON

@example
(hash-table-r7 'eq? 'a 1 'b 2)
  @equiv{}
  (rlet1 h (make-hash-table 'eq?)
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2))
@end example

@c EN
Note: An R7RS compliant implementation of @code{hash-table}
may return an immutable hash table.  Since Gauche doesn't have
immutable hash tables (we have immutable maps instead; @pxref{Immutable map}),
we return mutable hash tables.  However, the portable program should
refrain from mutating the returned hash tables.
@c JP
註: R7RS準拠の実装には、@code{hash-table}が変更不可なハッシュテーブルを
返すものがあります。Gaucheは変更不可なハッシュテールを持っていないので
(変更不可なマップならあります: @ref{Immutable map}参照)、
変更可能なハッシュテーブルが返されます。
ただ、ポータブルなプログラムを書いている場合は、この手続きが返したハッシュテーブルを
変更しないように注意してください。
@c COMMON
@end defun

@defun hash-table-unfold p f g seed comparator :rest args
[R7RS hash-table]
@c EN
Constructs and returns a new hash table with those repetitive steps.
Each iteration keeps the current seed value, whose initial value is @var{seed}.
@enumerate
@item
Apply a stop predicate @var{p} to the current seed value.  If it returns
a true value, stop.
@item
Apply a value producer @var{f} to the current seed value.  It must return
two values, which are used as a key and the corresponding value, of the
hash table.
@item
Apply a next procedure @var{g} to the current seed value.  The value
it returns becomes the next seed value.
@end enumerate
@c JP
次の手順で新たなハッシュテーブルを作り返します。
各繰り返しは「現在のシード値」を参照しますが、その初期値は@var{seed}です。
@enumerate
@item
停止述語@var{p}を現在のシード値に適用します。それが真の値を返したら、そこで終了です。
@item
生産手続き@var{f}を現在のシード値に適用します。@var{f}は二つの値を返さねばなりません。
最初の値がキー、二番目がキーに対応する値として、作られているハッシュテーブルに挿入されます。
@item
手続き@var{g}が現在のシード値に適用され、その戻り値が次の繰り返しでのシード値となります。
@end enumerate
@c COMMON
@end defun

@defun hash-table-copy ht :optional mutable?
[R7RS hash-table]
@c EN
Returns a new copy of a hash table @var{ht}.

R7RS defines this procedure to return an immutable hash table if
the implementation supports one, unless the optional @var{mutable?}
argument is provided and not false.  Gauche doesn't have immutable
hash tables so it ignores the optional argument and
always returns a mutable hash table.  But when you write
a portable programs, keep it in mind.
@c JP
ハッシュテーブル@var{ht}のコピーを作って返します。

R7RSは、実装が変更不可なハッシュテーブルをサポートする場合、
@var{mutable?}引数に真の値が与えられない限りは、
この手続きは変更不可なハッシュテーブルを返すと規定しています。
Gaucheは変更不可なハッシュテーブルを持たないので、@var{mutable?}引数は無視され、
常に変更可能なハッシュテーブルが返されますが、
ポータブルなコードを書いている場合は気をつけてください。
@c COMMON
@end defun

@defun hash-table-empty-copy ht
[R7RS hash-table]
@c EN
Returns a new mutable empty hash table that has the same properties as
the given hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}と同じ性質を持つ空の変更可能なハッシュテーブルを作成して
返します。
@c COMMON
@end defun

@defun alist->hash-table alist :optional comparator
[R7RS+ hash-table]
@c EN
Creates and returns a hash table that has entries of
each element in alist, using its car as the key and
its cdr as the value.  The @var{comparator} argument
is the same as in @code{make-hash-table}.  The default value
of @var{comparator} is @code{eq-comparator}.

R7RS doesn't allow to omit @var{comparator}.
@c JP
alistに含まれるそれぞれの要素をエントリとして持つハッシュテーブルを
作成して返します。その時、要素のcarがキーとして、要素のcdrが値として
使われます。@var{comparator}引数の意味は@code{make-hash-table}と同じです。
@var{comparator}のデフォルト値は@code{eq-comparator}です。

R7RSでは@var{comparator}は省略不可です。
@c COMMON
@end defun

@defun hash-table->alist hash-table
[R7RS hash-table]
@example
  (hash-table-map h cons)
@end example
@end defun

@c EN
@subheading Hash table lookup and mutation
@c JP
@subheading ハッシュテーブルのルックアップと変更
@c COMMON

@defun hash-table-get ht key :optional default
@c EN
Search @var{key} from a hash table @var{ht}, and returns its value
if found.  If the key is not found in the table and @var{default} is
given, it is returned.  Otherwise an error is signaled.
@c JP
キー@var{key}をハッシュテーブル@var{ht}から探します。見つかればキーに対応する
値を返します。キーが見つからなかった場合、@var{default}が与えられていればそれを
返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun hash-table-put! ht key value
@c EN
Puts a key @var{key} with a value @var{value} to the hash table @var{ht}.
@c JP
キー@var{key}と対応する値@var{value}をハッシュテーブル@var{ht}に挿入します。
@c COMMON
@end defun

@deffn {Method} ref (ht <hash-table>) key :optional default
@deffnx {Method} {(setter ref)} (ht <hash-table>) key value
@c EN
Method versions of @code{hash-table-get} and @code{hash-table-put!}.
@c JP
@code{hash-table-get}と@code{hash-table-put!}のメソッド版です。
@c COMMON
@end deffn

@defun hash-table-ref ht key :optional failure success
[R7RS hash-table]
@c EN
This is R7RS way to look up a hash table.

Look up a value associated to the @var{key} in the table @var{ht},
then pass it to a procedure @var{success}, and returns its value.
If @var{success} is omitted, an identity function is used.

If there's no association for @var{key} in @var{ht},
a thunk @var{failure} is called and its result is returned.
The default value of @var{failure} throws an error.

It is more general than Gauche's @code{hash-table-get}, but if you
need to simply return a fallback value in case of failure, you need
to wrap it with a clojure, which is annoying.  In R7RS, you can
use @code{hash-table-ref/default} below.
@c JP
これがR7RS方式のハッシュテーブルルックアップです。

ハッシュテーブル@var{ht}中の、@var{key}に結びつけられた値を探し、
それを手続き@var{success}に渡して、その結果を返します。
@var{success}が省略された場合は単に値そのものが返されます。

@var{key}に対応する値が@var{ht}に無い場合は、引数を取らない手続き@var{failure}が
呼ばれ、その結果が返されます。@var{failure}が省略されていた場合はエラーが報告されます。

これはGaucheの@code{hash-table-get}よりも汎用的ですが、
キーが見つからなかった場合に単純に既定値を返したいといった場合に、
それをいちいちクロージャで包むのは面倒です。R7RSではそのために
下に説明する@code{hash-table-ref/default}があります。
@c COMMON
@end defun

@defun hash-table-ref/default ht key default
[R7RS hash-table]
@c EN
Looks up @var{key} in a hash table @var{ht} and returns the associated
value.  If there's no @var{key} in the table, returns @var{default}.

This is same as Gauche's @code{hash-table-get}, except that
@var{default} is not optional.  We provide both, for
@code{hash-table-get} is short and handy.
@c JP
ハッシュテーブル@var{ht}から@var{key}を探し、対応する値を返します。
@var{key}が見つからない場合は@var{default}を返します。

これは、@var{default}が省略できないことを除いては、Gaucheの
@code{hash-table-get}と同じです。@code{hash-table-get}の方が短くて便利なので
両方提供しています。
@c COMMON
@end defun

@defun hash-table-set! ht args @dots{}
[R7RS hash-table]
@c EN
This is R7RS version to put associations into a hash table.
The @var{args} @dots{} is a list of alternating keys and values; so,
unlike Gauche's @code{hash-table-put!}, you can insert more than
one associations at once.  It is an error if @var{args} @dots{} have
odd number of arguments.
@c JP
これが、ハッシュテーブルに新たなエントリを追加するR7RS式のインタフェースです。
@var{args} @dots{}にはキーと値を交互に並べたリストを指定します。
Gaucheの@code{hash-table-put!}と違い、いくつものエントリを一度に追加することができます。
@var{args} @dots{}が偶数要素でなければエラーです。
@c COMMON

@example
(hash-table-set! ht 'a 1 'b 2)
  @equiv{}
  (begin (hash-table-put! ht 'a 1)
         (hash-table-put! ht 'b 2))
@end example
@end defun

@defun hash-table-intern!-r7 ht key failure
@c EN
This is defined in R7RS as @code{hash-table-intern!}.  We add @code{-r7}
suffix to remind that it takes a failure thunk,
which is consistent with R7RS hash-table interface but not Gauche's way.

Lookup @var{key} in @var{ht}.  If there's already an entry, it just returns
the value.
Otherwise, it calls a thunk @var{failure}, and insert the association
of @var{key} and the return value of @var{failure} into @var{ht},
and returns the value.
@c JP
これはR7RSで@code{hash-table-intern!}として定義されています。
Gaucheの慣習と異なり、R7RSの方式で@var{failure}にサンクを取ることを強調するために
@code{-r7}サフィックスをつけました。

@var{ht}から@var{key}を探します。もし既にエントリがあれば、その値を返します。
エントリが無ければ、サンク@var{failure}を呼び、その戻り値を@var{key}に対応する
値として@var{ht}に挿入して、@var{failure}の戻り値を返します。
@c COMMON
@end defun

@defun hash-table-exists? ht key
@defunx hash-table-contains? ht key
[R7RS hash-table]
@c EN
Returns @code{#t} if a hash table @var{ht} has a key @var{key}.

R7RS name is @code{hash-table-contains?}.
@c JP
ハッシュテーブル@var{ht}にキー@var{key}を持つエントリがあれば@code{#t}を返します。

R7RSでの名前は@code{hash-table-contains?}です。
@c COMMON
@end defun

@defun hash-table-delete! ht key
@c EN
Deletes an entry that has a key @var{key} from the hash table @var{ht}.
Returns @code{#t} if the entry has exist, or @code{#f} if the entry
hasn't exist.   The same function is called @code{hash-table-remove!} in STk
(except that it returns an undefined value); I use `delete' for consistency
to SRFI-1, SRFI-13 and other parts of the libraries.

Note: This is different from R7RS @code{hash-table-delete!}, so we provide
R7RS interface with an alias @code{hash-table-delete!-r7}.
@c JP
ハッシュテーブル@code{ht}からキー@var{key}を持つエントリを削除します。
@var{key}を持つエントリが実際に存在して削除された場合は@code{#t}を、
エントリが存在しなかった場合は@code{#f}を返します。
この手続きはSTkで@code{hash-table-remove!}と呼ばれているものです
(STkのは戻り値が定義されていませんが)。GaucheではSRFI-1, SRFI-13やその他の
ライブラリとの一貫性のために `delete' を採用しました。

註: これはR7RSの@code{hash-table-delete!}と異なります。
R7RSインタフェースは@code{hash-table-delete!-r7}という別名で提供されます。
@c COMMON
@end defun

@defun hash-table-delete!-r7 ht key @dots{}
@c EN
Delets entries that have @var{key} @dots{} from the hash table @var{ht}.
The @var{key} which isn't in @var{ht} has no effect.  Returns the number
of entries actually deleted.

This is called @code{hash-table-delete!} in R7RS, and so as in
@code{scheme.hash-table}.  We provide this under different name,
for Gauche's @code{hash-table-delete!} returns a boolean value.
@c JP
@var{key} @dots{}を持つエントリをハッシュテーブル@var{ht}から削除します。
@var{ht}に含まれなかったキーは単に無視されます。実際に削除されたエントリの数が返されます。

これはR7RSで@code{hash-table-delete!}と呼ばれており、
@code{scheme.hash-table}でもその名前で提供されます。
Gaucheの@code{hash-table-delete!}は真偽値を返すので、
組み込みとしては別名で提供することにしました。
@c COMMON
@end defun

@defun hash-table-clear! ht
[R7RS hash-table]
@c EN
Removes all entries in the hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}の全てのエントリを削除します。
@c COMMON
@end defun

@defun hash-table-push! ht key value
@c EN
Conses @var{value} to the existing value for the key @var{key} in the
hash table @var{ht} and makes it the new value for @var{key}.
If there's no entry for @var{key}, an entry
is created with the value @code{(list @var{value})}.

Works the same as the following code, except that this function
only looks up the @var{key} once, thus it's more efficient.
@c JP
ハッシュテーブル@var{ht}中の、キー@var{key}に対応する値に@var{value}をコンスし、
それを@var{key}に対する新たな値とします。もし@var{key}に対応する値がまだ無ければ、
新たなエントリが作成され、@code{(list @var{value})}がその値となります。

この手続きは次のコードと同じ動作をしますが、キーの探索が一度しか行われないためより高速です。
@c COMMON
@example
(hash-table-put! @var{ht} @var{key}
    (cons @var{value} (hash-table-get @var{ht} @var{key} '())))
@end example
@end defun

@defun hash-table-pop! ht key :optional default
@c EN
Looks for the value for the key @var{key} in the hash table @var{ht}.
If found and it is a pair, replaces the value for its cdr and returns
car of the original value.  If no entry for @var{key} is in the table,
or the value is not a pair, the table is not modified and
the procedure returns @var{default} if given, or signals an error otherwise.

During the operation the key is looked for only once, thus runs
efficiently.

Note: R7RS has @code{hash-table-pop!} but its totally different.
We provide R7RS version as an alias @code{hash-table-pop!-r7}
@c JP
ハッシュテーブル@var{ht}中のキー@var{key}に対応する値が存在し、かつペアで
あった場合に、そのエントリーを元の値のcdrで置き換え、元の値のcarを返します。
@var{key}に対応する値が存在しないかペアではなかった場合、テーブルは変更されず、
@var{default}が与えられていればそれが返され、与えられていなければエラーが報告されます。

値が置き換えられる場合でもキーの探索は一度しか行われないため効率が良いです。

註：R7RSも@code{hash-table-pop!}を定義していますが、全く違う操作です。
そこで、R7RSバージョンは@code{hash-table-pop!-r7}として提供しています。
@c COMMON
@end defun

@defun hash-table-pop!-r7 ht
@c EN
Removes one arbitrary entry from @var{ht}, and returns the removed
entry's key and value as two values.  If @var{ht} is empty, an error
is thrown.

This is called @code{hash-table-pop!} in R7RS, and so as in
@code{scheme.hash-table}.
@c JP
ハッシュテーブル@var{ht}中の任意のエントリをひとつ削除し、
そのエントリのキーと値を二つの戻り値として返します。
@var{ht}が空ならエラーが報告されます。

R7RSではこれが@code{hash-table-pop!}と呼ばれていて、
@code{scheme.hash-table}でもその名前で提供されます。
@c COMMON
@end defun

@defun hash-table-update! ht key proc :optional default
@c EN
A more general version of @code{hash-table-push!} etc.
It works basically as the following code piece,
except that the lookup of @var{key} is only done once.
@c JP
@code{hash-table-push!}等のより一般的なバージョンです。
ハッシュテーブルの探索が一度しか行われないことを除いては、
基本的に次のように動作します。
@c COMMON
@example
(let ((tmp (@var{proc} (hash-table-get @var{ht} @var{key} @var{default}))))
  (hash-table-put! @var{ht} @var{key} tmp)
  tmp)
@end example

@c EN
For example, when you use a hash table to count the occurrences
of items, the following line is suffice to increment the counter
of the item, regardless of whether @var{item} has already appeared or not.
@c JP
例えば、ハッシュテーブルを使ってオブジェクトの個数を数えているとしましょう。
次の1行で、オブジェクト@var{item}が既に出現したかどうかを気にせずに
その個数をインクリメントできます。
@c COMMON

@example
(hash-table-update! ht item (cut + 1 <>) 0))
@end example

@c EN
R7RS provides @code{hash-table-update!} with different interface,
so we provide R7RS version as an alias @code{hash-table-update!-r7}.
@c JP
R7RSも@code{hash-table-update!}を定義していますが、インタフェースが異なるので、
GaucheではR7RS版を別名@code{hash-table-update!-r7}として提供します。
@c COMMON
@end defun

@defun hash-table-update!-r7 ht key updater :optional failure success
@c EN
This is R7RS version of @code{hash-table-update!}.  With no optional
arguments, it works like Gauche's @code{hash-table-update!}.  But in
practice you often needs to specify the behavior when @var{key} hasn't
been in @var{ht}, in which case R7RS differs from Gauche.

The R7RS version works like this but potentially more efficiently:
@c JP
これがR7RS版の@code{hash-table-update!}です。
省略可能引数を全て省略した場合はGaucheの@code{hash-table-update!}と同じになりますが、
実際には@var{key}が@var{ht}に無かった場合の振る舞いを指定する必要があることが多く、
その場合R7RSのインタフェースはGaucheと異なってきます。

R7RS版は、効率を除けば次のとおり動作します。
@c COMMON

@example
(hash-table-put! ht key (updater (hash-table-ref ht key failure success)))
@end example
@end defun

@defun hash-table-update!/default ht key updater default
[R7RS hash-table]
@c EN
This is the same as Gauche's @code{hash-table-update!}, except that
the default value can't be omitted.
@c JP
これは@var{default}が省略できないことを除けば、
Gaucheの@code{hash-table-update!}と同じです。
@c COMMON
@end defun

@c EN
@subheading Hash table scanners
@c JP
@subheading ハッシュテーブルの走査
@c COMMON

@defun hash-table-for-each ht proc
@defunx hash-table-map ht proc
@c EN
A procedure @var{proc} is called with two arguments, a key and its associated
value, over all the entries in the hash table @var{ht}.
@c JP
ハッシュテーブル@var{ht}内の全てのエントリについて、各エントリのキーと値を
2つの引数として手続き@var{proc}を呼びます。
@c COMMON

@c EN
@code{hash-table-map} returns a list of the result of @var{proc},
while @code{hash-table-for-each} discards the result of @var{proc}
and returns @code{#<undef>}.  The order of the result of @code{hash-table-map}
is unspecified.
@c JP
@code{hash-table-map}は@var{proc}の結果をリストにして返します。
@code{hash-table-for-each}は@var{proc}の結果を捨てて@code{#<undef>}を返します。
@code{hash-table-map}の値の順序は未定義です。
@c COMMON
@end defun

@defun hash-table-fold ht kons knil
@c EN
For all entries in the hash table @var{ht},
a procedure @var{kons} is called with three arguments;
a key, its associated value, and the previous return value of @var{kons}.
The first call of @var{kons} receives @var{knil} as the third argument.
The return value of the last call of @var{kons} is returned
from @code{hash-table-fold}.
@c JP
ハッシュテーブル@var{ht}内の全てのエントリについて@var{kons}を呼びます。
@var{kons}には3つの引数が渡されます。
各エントリのキーと値、および一つ前の@var{kons}の返り値です。
最初の@var{kons}の呼び出しの時には、第3引数に@var{knil}が渡されます。
最後の@var{kons}の返り値が@code{hash-table-fold}の返り値となります。
@c COMMON
@end defun

@defun hash-table-find ht pred :optional failure
@c EN
Apply @var{pred} with each key and value in the hash table @var{ht}.
Once @var{pred} returns a true value, that return value is immediately returned
from @code{hash-table-find}.
If no key-value satisfies @var{pred}, a thunk @var{failure} is
invoked and its result is returned.  If @var{failure} is
omitted, @code{(lambda () #f)} is assumed.
@c JP
@var{pred}をハッシュテーブル@var{ht}の各エントリのキーと値を引数にして
呼び出し、それが真の値を返したら直ちにそれを戻り値とします。
@var{pred}を満たすキーと値が無ければ、無引数の手続き@var{failure}が呼び出され、
その値が戻り値となります。@var{failure}が省略された場合は
@code{(lambda () #f)}が使われます。
@c COMMON

@c EN
Note: The convention starting from SRFI-1 is that
@code{*-find} returns an item in the collection that
satisfy the predicate, while @code{*-any} returns a non-false
value the predicate returns.  SRFI-125 broke the convention.
The justification given in SRFI-125 discussion
was that the ``any'' semantics is strictly upper-compatible to the
``find'' semantics so we can combine two.  So far, though, SRFI-125
is the only exception of this convention.
@c JP
註: SRFI-1から始まった慣習では、@code{*-find}というAPIは
述語を満たすようなコレクション内の要素を返し、@code{*-any}というAPIが
述語が偽でない値を返した時にその値をそのまま返り値とします。
SRFI-125が慣習を破った理由は、
``any''のセマンティクスで従来の ``find'' の動作もエミュレートできるので
``find''が ``any'' の動作も兼ねてしまえばよいというものです。
しかし、現在までのところ、この慣習を破っているのはSRFI-125のみです。
@c COMMON

@example
@c EN
;; Find if hash tables ha and hb has a common key.
@c JP
;; ハッシュテーブルhaとhbに共通のキーがあるかどうか調べる
@c COMMON
(hash-table-find ha (^[k v] (hash-table-exists? hb k)))
@end example
@end defun

@defun hash-table-keys ht
@defunx hash-table-values ht
@c EN
Returns all the keys or values of hash table @var{ht} in a list,
 respectively.
@c JP
それぞれ、ハッシュテーブル@var{ht}内の全てのキーまたは値をリストにして返します。
@c COMMON
@end defun

@c EN
@subheading Hash table as sets
@c JP
@subheading 集合としてのハッシュテーブル
@c COMMON

@defun hash-table-compare-as-sets ht1 ht2 :optional value=? fallback
@c EN
A hash table can be viewed as a set of pairs of key and value.
This procedure compares two hash tables @var{ht1} and @var{ht2} as such
sets.

The key comparators of two tables must match (in terms of @code{equal?}
of the comparators).  Otherwise, an error is signaled.

Two elements of the set are equal to each other iff their keys match
with the equality predicate of the key comparator, and their values
match with @var{value=?} procedure.  If omitted, @code{equal?} is
used for @var{value=?}
@c JP
ハッシュテーブルは、キーと値の組を要素とする集合とみなすことができます。
この手続きは二つのハッシュテーブル@var{ht1}と@var{ht2}を集合として比較します。

二つのハッシュテーブルのキー比較器は同じ (@code{equal?}の意味で)
でなければなりません。そうでない場合はエラーが投げられます。

二つの要素は、キー同士がキー比較器によって等価と判断され、かつ
値同士が@var{value=?}手続きによって等価と判断された場合に等しいとみなされます。
@var{value=?}が省略された場合は@code{equal?}が使われます。
@c COMMON

@c EN
There can be four cases.
@itemize
@item
If @var{ht1} is a pure subset of @var{ht2}, returns -1 (@var{ht1} is smaller
than @var{ht2}).
@item
If @var{ht2} is a pure subset of @var{ht1}, returns 1 (@var{ht1} is greater
than @var{ht2}).
@item
If @var{ht1} and @var{ht2} contains exactly the same elements,
returns 0 (@var{ht1} equals to @var{ht2}).
@item
Neither @var{ht1} nor @var{ht2} is a subset of another.  In this case,
@var{fallback} is returned if it is given, or an error is thrown.
@end itemize
@c JP
4通りの結果が有り得ます。
@itemize
@item
@var{ht1}が@var{ht2}の純粋部分集合である場合は-1が返されます
(@var{ht1} ＜ @var{ht2})。
@item
@var{ht2}が@var{ht1}の純粋部分集合である場合は1が返されます
(@var{ht1} ＞ @var{ht2})。
@item
@var{ht1}と@var{ht2}がまったく同じだけの要素を含んでいる場合は0が返されます
(@var{ht1} ＝ @var{ht2})。
@item
@var{ht1}と@var{ht2}がお互いに相手の部分集合でない場合は、
@var{fallback}が与えられていればそれが返され、
省略された場合はエラーが投げられます。
@end itemize
@c JP
@c COMMON
@end defun

@defun hash-table=? value-cmpr ht1 ht2
[R7RS hash-table]
@c EN
This also compares two hash tables @var{ht1} and @var{ht2} as sets,
and returns true iff two are the same.  That is, every element in @var{ht1}
is also in @var{ht2} and vice versa.

Two element are the same iff their keys are the same in terms of
the equality predicate of the tables' key comparator, and their values
are the same in terms of the equality predicate of a comparator
@var{value-cmpr}.

It is an error if @var{ht1} and @var{ht2} has different key comparators.
See also @code{hash-table-compare-as-sets} above.
@c JP
この手続きも@var{ht1}と@var{ht2}を集合として比較し、
二つのテーブルが等しい集合である場合、つまり@var{ht1}の要素がすべて@var{ht2}の要素でもあり、
またその逆も真である場合に@code{#t}を、そうでなければ@code{#f}を返します。

二つの要素は、キー同士がキー比較器によって等価と判定され、かつ
また値同士が比較器@var{value-cmpr}によって等価と判定された場合に
等しいとみなされます。

@var{ht1}と@var{ht2}のキー比較器が異なっていた場合はエラーが投げられます。
上の@code{hash-table-compare-as-sets}も参照してください。
@c COMMON
@end defun

@defun hash-table-union! ht1 ht2
@defunx hash-table-intersection! ht1 ht2
@defunx hash-table-difference! ht1 ht2
@defunx hash-table-xor! ht1 ht2
[R7RS hash-table]
@c EN
Perform set operations on two hashtables @var{ht1} and @var{ht2},
and modify @var{ht1} to store the result.
Note that these procedures only look at the keys for operation; if
the values of the same key differ between @var{ht1} and @var{ht2},
the value in @var{ht1} is taken.
@c JP
二つのハッシュテーブル間で集合演算を行い、結果を@var{ht1}に格納します。
これらの手続きでは、集合の要素としてキーだけを見ます。
もし同じキーを持つ要素の値が@var{ht1}と@var{ht2}で異なっていた場合、
@var{ht1}の値が優先されます。
@c COMMON

@itemize
@item
@c EN
The union operation picks each entry that is in at least one of @var{ht1}
or @var{ht2}.
@c JP
unionは、@var{ht1}か@var{ht2}の少なくとも一方に入っている要素を集めます。
@c COMMON
@item
@c EN
The intersection operation picks each entry that is both in @var{ht1} and
@var{ht2}.
@c JP
intersectionは、@var{ht1}と@var{ht2}の両方に含まれる要素のみを集めます。
@c COMMON
@item
@c EN
The difference operation picks each entry that is in @var{ht1} but
not in @var{ht2}.
@c JP
differenceは、@var{ht1}に含まれるが@var{ht2}には含まれない要素のみを集めます。
@c COMMON
@item
@c EN
The xor operation picks each entry that is in only one of @var{ht1} or
@var{ht2}, but not in both.
@c JP
xorは、@var{ht1}か@var{ht2}の一方のみに含まれる要素のみを集めます。
@c COMMON
@end itemize
@end defun


@c ----------------------------------------------------------------------
@node Treemaps,  , Hashtables, Dictionaries
@subsection Treemaps
@c NODE ツリーマップ

@deftp {Builtin Class} <tree-map>
@clindex tree-map
@c EN
Tree map class.   Tree maps are a data structure that maps key objects
to value objects.  It's like hash tables except tree maps uses
balanced tree internally.  Insertion and lookup is O(log n).
@c JP
ツリーマップクラス。ツリーマップはキーオブジェクトから値オブジェクトへ
の写像をあらわすデータ構造です。ツリーマップでは平衡木を使うということ
以外はハッシュテーブルと同じです。ツリーマップでは挿入と検索の手間は
O(log n)です。
@c COMMON

@c EN
Unlike hashtables, a tree map keeps the order of the keys, so
it is easy to traverse entries in the order of keys, to find
minimum/maximum keys, or to find a key closest to the given value.
@c JP
ハッシュテーブルとはちがい、キーの順序は保存されます。したがってキーの
順序どおりにトラバースするのは簡単で、キーの最小値/最大値を見つけたり、
指定したキーにもっとも近いキーを探すのも簡単です。
@c COMMON

@c EN
The @code{<tree-map>} class inherits @code{<sequence>} and
@code{<ordered-dictionary>}.
@c JP
@code{<tree-map>}クラスは@code{<sequence>}および
@code{<ordered-dictionary>}を継承しています。
@c COMMON
@end deftp

@defun make-tree-map :optional comparator
@defunx make-tree-map key=? key<?
@c EN
Creates and returns an instance of @code{<tree-map>}.
The keys are compared by @var{comparator},
whose default is @code{default-comparator}.
The comparator must have a comparison procedure, for
we need a total order in the keys.
@xref{Basic comparators}, for the details.

For the backward compatibility, @code{make-tree-map} also
accepts a procedure as a @var{comparator}; the procedure must
take two keys and returns either @code{-1}, @code{0}, or @code{1},
depending on whether the first key is less than, equal to, or
greater than the second key, respectively.  In other words, it
is a comparison procedure of a comparator.

The second form of @code{make-tree-map} is also for the
backward compatibility; it takes two procedures, each must
be a procedure that takes two keys; the first one returns
@code{#t} iff two keys are equal, and the second one returns
@code{#t} iff the first key is strictly smaller than the second.
@c JP
@code{<tree-map>}オブジェクトを作成して返します。
キーは比較器@var{comparator}を使って比較されます。@var{comparator}の
デフォルト値は@code{default-comparator}です。キーには全順序関係が必要なので、
比較器は比較手続きを持っていなければなりません。
詳しくは@ref{Basic comparators}を参照してください。

互換性のため、@code{make-tree-map}は@var{comparator}引数に
単なる手続きを取ることもできます。渡される手続きは2引数を取り、
最初の引数が2番目の引数より小さいか、等しいか、大きいかに応じて
@code{-1}、@code{0}、@code{1}をそれぞれ返します。つまり
この手続きは比較器の比較手続きそのものです。

@code{make-tree-map}の2番目の呼び出し形式も互換性のためのものです。
それぞれ2引数の2つの手続きを取り、
最初の手続き@var{key=?}は、2つのキーが等しい場合にのみ真を返し、
2番目の手続き@var{key<?}は、最初のキーが2番目のキーより前にある(小さい)場合にのみ
真を返すようにします。
@c COMMON
@end defun

@defun tree-map-comparator tree-map
@c EN
Returns the comparator used in the tree map.
@c JP
@var{tree-map}で使われている比較器を返します。
@c COMMON
@end defun

@defun tree-map-copy tree-map
@c EN
Copies and returns  @var{tree-map}.  Modification
on the returned tree doesn't affect the original tree.
@c JP
@var{tree-map}のコピーを作り、それを返します。返された木に対す
る破壊的操作は、元の木に影響を与えません。
@c COMMON
@end defun

@defun tree-map-empty? tree-map
@c EN
Returns @code{#t} if @var{tree-map} doesn't have any elements,
or @code{#f} otherwise.
@c JP
@var{tree-map}が要素を持たないなら@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun tree-map-num-entries tree-map
@c EN
Returns the number of elements in @var{tree-map}.
@c JP
@var{tree-map}内の要素の個数を返します。
@c COMMON
@end defun

@defun tree-map-exists? tree-map key
@c EN
Returns @code{#t} if @var{tree-map} has an entry with @var{key},
or @code{#f} otherwise.
@c JP
@var{tree-map}にキー@var{key}を持つエントリがあれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun tree-map-get tree-map key :optional fallback
@c EN
Looks for @var{key} in @var{tree-map}.  If the entry is found,
returns a value corresponding to the key.  Otherwise, returns
@var{fallback} if it is provided, or signals an error.
@c JP
キー@var{key}を@var{tree-map}から探します。見つかれば@var{key}に対応する値を返
します。キーが見つからなかった場合、@var{fallback}が与えられていればそれ
を返し、そうでなければエラーを報告します。
@c COMMON
@end defun

@defun tree-map-put! tree-map key value
@c EN
Inserts an entry with a @var{key} and corresponding @var{value}
into @var{tree-map}.  If there already exists an entry with a
key which is equivalent (under @var{key=?}), the entry is modified
to have @var{value}.
@c JP
キー@var{key}と対応する値@var{value}を@var{tree-map}に挿入します。もし、@var{key}と、
@var{key=?}における意味で同じキーがすでに存在する場合、キーに対応する値
は新たな値に置き換えられます。
@c COMMON
@end defun

@defun tree-map-delete! tree-map key
@c EN
Deletes an entry with @var{key} from @var{tree-map} if such an entry
exists, and returns @code{#t}.
If @var{tree-map} doesn't have such an entry, @code{#f} is returned.
@c JP
@var{tree-map}からキー@var{key}を持つエントリを削除します。@var{key}を持つエン
トリが実際に存在して削除された場合は@code{#t}を、エントリが存在しなかっ
た場合は@code{#f}を返します。
@c COMMON
@end defun

@defun tree-map-clear! tree-map
@c EN
Removes all entries in @var{tree-map}.
@c JP
@var{tree-map}内の全てのエントリを削除します。
@c COMMON
@end defun

@defun tree-map-update! tree-map key proc :optional fallback
@c EN
A generalized version of @code{tree-map-push!} etc.
It works like the following code, except that searching
for the key is done only once.
@c JP
@code{tree-map-push!}等のより一般的なバージョンです。木の探索が一度
しか行われないことを除いては、基本的に次のように動作します。
@c COMMON
@example
(let ((tmp (proc (tree-map-get @var{tree-map} @var{key} @var{fallback}))))
  (tree-map-put! @var{tree-map} @var{key} tmp)
  tmp)
@end example
@end defun

@defun tree-map-push! tree-map key value
@c EN
Looks for an entry with @var{key} in @var{tree-map}.  If it exists,
the procedure conses @var{value} to the original value and makes
it as a new value.
Otherwise, the procedure creates a new entry for the @var{key}
and makes @code{(list @var{value})} its value.
@c JP
@var{tree-map}中の、キー@var{key}に対応する値に@var{value}をコンスし、
それを@var{key}
に対する新たな値とします。もし@var{key}に対応する値がまだ無ければ、新た
なエントリが作成され、@code{(list @var{value})}がその値となります。
@c COMMON
@end defun

@defun tree-map-pop! tree-map key :optional fallback
@c EN
Looks for an entry with @var{key} in @var{tree-map}.  If it exists
and its value is a pair, then the procedure updates
its value with @code{cdr} of the original value, and returns
@code{car} of the original entry.   If such an entry does not
exist, or has a non-pair value, the procedure doesn't
modify @var{tree-map} and returns @var{fallback} if it is given,
otherwise reports an error.
@c JP
@var{tree-map}中のキー@var{key}に対応する値が存在し、かつペアであった場合
に、そのエントリの値を元の値のcdrで置き換え、元の値のcarを返します。
@var{key}に対応する値が存在しないかペアではなかった場合、@var{tree-map}は
変更されず、@var{fallback}が与えられていればそれが返され、与えられていな
ければエラーが報告されます。
@c COMMON
@end defun

@defun tree-map-min tree-map
@defunx tree-map-max tree-map
@c EN
Returns a pair of a key and its value with the minimum
or maximum key, respectively.   If @var{tree-map} is empty,
@code{#f} is returned.
@c JP
それぞれ、@var{tree-map}に含まれる最小および最大のキーを探索し、その
キーと値のペアを返します。@var{tree-map}が空だった場合は@code{#f}が返されます。
@c COMMON
@end defun

@defun tree-map-pop-min! tree-map
@defunx tree-map-pop-max! tree-map
@c EN
Looks for an entry with minimum or maximum key, respectively,
then deletes the entry from @var{tree-map} and returns
a pair of the key and its value of the original entry.
If @var{tree-map} is empty, @code{#f} is returned.
@c JP
それぞれ、@var{tree-map}に含まれる最小および最大のキーを探索し、そ
のエントリを@var{tree-map}から削除したうえで、そのキーと値のペアを
返します。@var{tree-map}が空だった場合は@code{#f}が返されます。
@c COMMON
@end defun

@defun tree-map-fold tree-map proc seed
@defunx tree-map-fold-right tree-map proc seed
@c EN
Iterate over elements in @var{tree-map}, applying
@var{proc} which has a type @code{(key, value, seed) -> seed}.
The difference of @code{tree-map-fold} and @code{tree-map-fold-right}
is the associative order of applying @var{proc},
just like the difference between @code{fold} and @code{fold-right}.
@c JP
@var{tree-map}の各要素に対し、@code{(key, value, seed) -> seed} の型を持つ
@var{proc}を適用してゆきます。
@code{tree-map-fold}と@code{tree-map-fold-right}の違いは
@code{fold}の@code{fold-right}違いと同じ、すなわち
結合の方向にあります。
@c COMMON
@example
tree-map-fold:
  (proc Kn Vn (proc Kn-1 Vn-1 ... (proc K0 V0 seed)))

tree-map-fold-right
  (proc K0 V0 (proc K1 V1 ... (proc Kn Vn seed)))
@end example

@c EN
Some examples:
@c JP
例:
@c COMMON
@example
(define tree (alist->tree-map '((3 . a) (7 . b) (5 . c)) = <))

(tree-map-fold tree list* '())
   @result{} (7 b 5 c 3 a)
(tree-map-fold-right tree list* '())
   @result{} (3 a 5 c 7 b)
@end example
@end defun

@defun tree-map-map tree-map proc
@c EN
Calls @var{proc}, which must take two arguments,
with each key/value pair in @var{tree-map},
and collect the results into a list and returns it.  The order
of results corresponds to the order of keys---that is, the first element
of the result list is what @var{proc} returns with minimum key and its value,
and the last element of the result list is what @var{proc} returns
with the maximum key and its value.
(Note: Like @code{map}, the order that @var{proc} is actually called
is unspecified; @var{proc} is better to be side-effect free.)
@c JP
2引数を取る手続き@var{proc}を、@var{tree-map}の各キーおよび値のペアに
対して呼び出し、結果をリストにして返します。
結果のリストは、キーの昇順に並んでいます。つまり、最小のキーとその値で呼び出した
@var{proc}の結果が最初の要素に、最大のキーとその値で呼び出した@var{proc}の
結果が最後の要素になります。
(@code{map}と同様、実際に@var{proc}が呼ばれる順序は保証されていません。
したがって@var{proc}は副作用の無いものにすべきです)。
@c COMMON
@end defun

@defun tree-map-for-each tree-map proc
@c EN
Calls @var{proc}, which must take two arguments,
with each key/value pair in @var{tree-map},
in the increasing order of the keys.  @var{proc} is called purely
for side effects; the returned values are discarded.
@c JP
2引数を取る手続き@var{proc}を、@var{tree-map}の各キーおよび値のペアに対して、
キーの昇順に呼び出します。@var{proc}は副作用のためだけに呼ばれ、結果は捨てられます。
@c COMMON
@end defun

@defun tree-map-floor tree-map probe :optional fallback-key fallback-value
@defunx tree-map-ceiling tree-map probe :optional fallback-key fallback-value
@defunx tree-map-predecessor tree-map probe :optional fallback-key fallback-value
@defunx tree-map-successor tree-map probe :optional fallback-key fallback-value
@c EN
These procedures search the entry which has the closest key
to the given @var{probe}.  If such an entry is found, returns
two values, its key and its value.  Otherwise, returns two values,
@var{fallback-key} and @var{fallback-value}, both defaulted to @code{#f}.

The criteria of ``closest'' differ slightly among these procedures;
@code{tree-map-floor} finds the maximum key which is no greater than
@var{probe}; @code{tree-map-ceiling} finds the minimum key which is
no less than @var{probe}; @code{tree-map-predecessor} finds the
maximum key which is strictly less than @var{probe};
and @code{tree-map-successor} finds the minimum key which
is strictly greater than @var{probe}.
@c JP
これらの手続きは、@var{probe}に最も近いキーを持つエントリを@var{tree-map}から
探します。そのようなエントリが見つかれば、該当するキーと値が2つの戻り値となります。
見つからない場合は、@var{fallback-key}と@var{fallback-value}が
2つの戻り値として返されます。それぞれの省略時の値は@code{#f}です。

それぞれの手続きは異なった「最も近い」の基準を持っています。
@code{tree-map-floor}は@var{probe}以下で最大のキーを、
@code{tree-map-ceiling}は@var{probe}以上で最小のキーを、
@code{tree-map-predecessor}は@var{probe}未満で最大のキーを、
@code{tree-map-successor}は@var{probe}を越える最小のキーを探します。
@c COMMON
@end defun

@defun tree-map-floor-key tree-map probe :optional fallback-key
@defunx tree-map-ceiling-key tree-map probe :optional fallback-key
@defunx tree-map-predecessor-key tree-map probe :optional fallback-key
@defunx tree-map-successor-key tree-map probe :optional fallback-key
@c EN
Like @code{tree-map-floor} etc., but only returns the key of
the found entry (or @var{fallback-key} if there's no entry which satisfies
the criteria).
@c JP
@code{tree-map-floor}等と同様ですが、見つかったエントリのキーのみを返します。
該当エントリが見つからない場合は@var{fallback-key}の値(デフォルトは@code{#f})が
返されます。
@c COMMON
@end defun

@defun tree-map-floor-value tree-map probe :optional fallback-value
@defunx tree-map-ceiling-value tree-map probe :optional fallback-value
@defunx tree-map-predecessor-value tree-map probe :optional fallback-value
@defunx tree-map-successor-value tree-map probe :optional fallback-value
@c EN
Like @code{tree-map-floor} etc., but only returns the value of
the found entry (or @var{fallback-value} if there's no entry which satisfies
the criteria).
@c JP
@code{tree-map-floor}等と同様ですが、見つかったエントリの値のみを返します。
該当エントリが見つからない場合は@var{fallback-value}の値(デフォルトは@code{#f})が
返されます。
@c COMMON
@end defun

@defun tree-map->generator/key-range tree-map :key > >= < <= descending
@c EN
Returns a generator (@pxref{Generators}) that yields pairs of key and value
such that the key is in the specified range.
If the @var{descending} keyword argument is @code{#f} (default),
it yields the pairs with increasing keys; otherwise,
it yields them with descending keys.

The keyword argument @code{>} and @code{>=} specifies the lower bound
of the key, including and excluding the given key value itself, respectively.
If both are given, either one of them is considered.

The keyword argument @code{<} and @code{<=} specifies the upper bound
of the key, including and excluding the given key value itself, respectively.
If both are given, either one of them is considered.
@c JP
キーが指定された範囲に入っているようなキーと値のペアを生成するジェネレータを作って
返します (@ref{Generators}参照)。
もし@var{descending}キーワード引数が@code{#f}(デフォルト値)なら、ペアは
キーの昇順に生成されます。それが真の値なら、ペアはキーの降順に生成されます。

キーワード引数@code{>}と@code{>=}はキーの下限を指定します。前者は指定値を含み、
後者は含みません。両方指定された場合はどちらかひとつだけが有効です。

キーワード引数@code{<}と@code{<=}はキーの下限を指定します。前者は指定値を含み、
後者は含みません。両方指定された場合はどちらかひとつだけが有効です。
@c COMMON

@example
(define tm (alist->tree-map '((0 . a) (1 . b) (2 . c) (3 . d) (4 . e))
                            default-comparator))


(use gauche.generator)

(generator->list
  (tree-map->generator/key-range tm :>= 1 :< 4))
  @result{} ((1 . b) (2 . c) (3 . d))

(generator->list
  (tree-map->generator/key-range tm :>= 1 :< 4 :descending #t))
  @result{} ((3 . d) (2 . c) (1 . b))

(generator->list
  (tree-map->generator/key-range tm :<= 2))
  @result{} ((0 . a) (1 . b) (2 . c))

(generator->list
  (tree-map->generator/key-range tm :> 2))
  @result{} ((3 . d) (4 . e))
@end example
@end defun


@defun tree-map-keys tree-map
@defunx tree-map-values tree-map
@c EN
Returns a list of all keys and all values, respectively.
The keys and values are in ascending order of the keys.
@c JP
それぞれ、@var{tree-map}内の全てのキーまたは値をリストにして返しま
す。返されるリストの要素はキーの昇順に並んでいます。
@c COMMON
@end defun

@defun tree-map->alist tree-map
@c EN
Returns a list of pairs of keys and values for all entries.
The pairs are in ascending order of the keys.
@c JP
@var{tree-map}含まれる要素を連想リストにして返します。返される連
想リストのキーは昇順に並んでいます。
@c COMMON
@end defun

@defun alist->tree-map alist :optional comparator
@defunx alist->tree-map alist key=? key<?
@c EN
Creates a new tree map with the @var{comparator} or
@var{key=?}/@var{key<?} procedures, then
populates it with @var{alist}, each pair in which are
interpreted as a cons of a key and its value.
The meaning of @var{comparator}, @var{key=?} and @var{key<?} are
the same as @code{make-tree-map}.
@c JP
@var{comparator}または@var{key=?}, @var{key<?} によって新たなtreemapを作成し、
連想リスト@var{alist}に含まれる要素を追加した上で返します。
@var{alist}の各ペアのcarがキーに、cdrが値に使われます。
@var{comparator}, @var{key=?}, @code{key<?}引数の意味は
@code{make-tree-map}と同じです。
@c COMMON
@end defun

@c EN
The following two procedures compares two tree maps with slightly different
views.
@c JP
以下の二つの手続きは二つのツリーマップを比較しますが、見方が異なります。
@c COMMON

@defun tree-map-compare-as-sets tree-map1 tree-map2 :optional value=? fallback
@c EN
Compares two tree maps as sets of entries.  If we look at tree maps
as sets of entries, we can define a partial order between two maps;
they are equal to each other if they have exactly the same entries,
and tree-map A is smaller than tree-map B if A us a strict subset of B.

If @var{tree-map1} and @var{tree-map2} are the same, 0 is
returned.  If @var{tree-map1} is smaller than @var{tree-map2}, -1
is returned.  If @var{tree-map1} is greater than @var{tree-map2}, 1
is returned.

If one argument isn't subset of the other, we can't determine the order.
In such a case, if @var{fallback} is given, it is returned.  Otherwise,
an error is signalled.

The comparators of @var{tree-map1} and @var{tree-map2} must be
the same (@code{equal?}), otherwise an error is signalled.
@xref{Basic comparators}, about the comparators.

An entry is equal to another entry if their keys match in terms
of the comparator of the tree-map, and also their values match
with the provided @var{value=?} predicate, which is defaulted to
@code{equal?}.
@c JP
二つのツリーマップを、エントリの集合として比較します。エントリの集合として見れば、
ツリーマップ間に半順序関係を定義できます。すなわち、全てのエントリが等しければ
ツリーマップ同士も等しく、ツリーマップAがツリーマップBの真部分集合であれば
AはBより小さい、とします。

@var{tree-map1}と@var{tree-map2}が等しければ0が、
@var{tree-map1}の方が@var{tree-map2}より小さければ-1が、
@var{tree-map1}の方が@var{tree-map2}より大きければ1が返されます。

どちらのツリーマップも相手の部分集合になっていない場合は、順序が決められません。
その場合、@var{fallback}引数が与えられていればその値が返され、
与えられていなければエラーが報告されます。

@var{tree-map1}と@var{tree-map2}の比較器は@code{equal?}の意味で
等しくなければなりません。比較器については@ref{Basic comparators}を参照してください。

エントリは、それぞれのキーがツリーマップの比較器による比較で等しく、
かつ対応する値が@var{value=?}手続きによる比較で等しい場合にのみ等しいとみなされます。
@var{value=?}が省略された場合は@code{equal?}が使われます。
@c COMMON

@example
(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (2 . b) (3 . c)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} 0

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} -1

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c) (4 . d) (2 . b)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} 1

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c) (4 . d)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} ERROR: tree-maps can't be ordered

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c) (4 . d)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator)
 eq?
 #f)
 @result{} #f
@end example
@end defun

@defun tree-map-compare-as-sequences tree-map1 tree-map2 :optional value-cmp
@c EN
Compares two tree maps as sequence of entries, ordered by keys.
If both maps have entries with the same key, we use a comparator
@var{value-cmp} to break the tie (naturally, @var{value-cmp} must
have ordering predicate.)
If @var{value-cmp} is omitted, @code{default-comparator} is used.

The comparators of @var{tree-map1} and @var{tree-map2} must be
the same (@code{equal?}), otherwise an error is signalled.
@xref{Basic comparators}, about the comparators.

If @var{tree-map1} and @var{tree-map2} are the same, 0 is
returned.  If @var{tree-map1} is smaller than @var{tree-map2}, -1
is returned.  If @var{tree-map1} is greater than @var{tree-map2}, 1
is returned.

Unlike @code{tree-map-compare-as-sets}, this procedure defines total order
of tree maps which share the same comparator.
@c JP
二つのツリーマップを、キーの順序で並べられたエントリのシーケンスとして比較します。
両マップにキーが同じであるエントリがあった場合は、
対応する値同士を@var{value-cmp}比較器で比べます
(従って、@var{value-cmp}は比較述語を持っていなければなりません。)
@var{value-cmp}が省略された場合は@code{default-comparator}が使われます。

@var{tree-map1}と@var{tree-map2}の比較器は@code{equal?}の意味で
等しくなければなりません。比較器については@ref{Basic comparators}を参照してください。

@var{tree-map1}と@var{tree-map2}が等しければ0が、
@var{tree-map1}の方が@var{tree-map2}より小さければ-1が、
@var{tree-map1}の方が@var{tree-map2}より大きければ1が返されます。

@code{tree-map-compare-as-sets}と異なり、
この手続きは比較器が同じであるようなツリーマップについて全順序関係を定義します。
@c COMMON

@example
(tree-map-compare-as-sequences
 (alist->tree-map '((1 . a) (3 . c)) default-comparator)
 (alist->tree-map '((3 . c) (2 . b)) default-comparator))
 @result{} -1

(tree-map-compare-as-sequences
 (alist->tree-map '((2 . b) (3 . d)) default-comparator)
 (alist->tree-map '((3 . c) (2 . b)) default-comparator))
 @result{} 1
 @end example
@end defun

@c ----------------------------------------------------------------------
@node Procedures and continuations, Parameters and dynamic states, Dictionaries, Core library
@section Procedures and continuations
@c NODE 手続きと継続

@c EN
In Scheme, @emph{procedures} are fundamental blocks to build
a program (@pxref{Making procedures}).
A procedure represents a certain computation,
possibly parameterized, and can be @emph{applied} to the actual
arguments to execute the computation.  Scheme also provides
the means to extract the continuation of the current computation
and wraps it in a procedure (@pxref{Continuations}).
@c JP
Schemeでは、プログラムを組み立てる最も基本となるブロックが@emph{手続き}です
(@ref{Making procedures}も参照)。
手続きは、特定の計算を表現します。引数を取ることも出来ます。
そして、実引数に@emph{適用}されると、その計算を実行します。
Schemeはまた、現在の計算の継続を取り出して手続きにラップして返す手段を
提供しています(@ref{Continuations}参照)。
@c COMMON

@c EN
Gauche extends the concept of procedure application, allowing
you to apply any object as if it's a procedure;
for example, you can set up Gauche to
accept @code{("abc" 2)} can be a valid application syntax.
@xref{Applicable objects}, for the details.
@c JP
Gaucheは手続きの適用の概念を拡張し、どんなオブジェクトでもそれが手続きであるかのように
適用できるようにしました。例えば@code{("abc" 2)}が有効な適用であるように
Gaucheをセットアップすることができます。
詳しくは@ref{Applicable objects}を参照してください。
@c COMMON

@menu
* Procedure class and applicability::
* Universal accessor::
* Combinators::
* Optional argument parsing::
* Procedure arity::
* Applicable objects::
* Continuations::
* Continuation prompts::
* Continuation marks::
* Multiple values::
* Folding generated values::
@end menu

@node Procedure class and applicability, Universal accessor, Procedures and continuations, Procedures and continuations
@subsection Procedure class and applicability
@c NODE procedureクラスと適用可能性

@deftp {Builtin Class} <procedure>
@clindex procedure
@c EN
Represents a procedure.  Ordinary Scheme procedures created by @code{lambda}
is an instance of this class, as well as built-in primitive procedures
written in C.  Note that, in Gauche, other type of objects can behave
as a procedure; so checking whether an object is a procedure or not doesn't
mean much unless you want to mess around with Gauche internals.
@c JP
手続きのクラスです。@code{lambda}で作られた手続きや
組み込みのプリミティブ手続きはこのクラスのインスタンスです。
Gaucheではどんな型のオブジェクトも適用可能にできるので、あるオブジェクトが
@code{<procedure>}クラスのインスタンスであるかとうかということは
あまり気にする必要はありません。Gaucheの中身をいじってみる時以外は。
@c COMMON
@end deftp

@defun procedure? obj
[R7RS base]
@c EN
Returns @code{#t} if @var{obj} is @emph{inherently} applicable
objects, @code{#f} otherwise.  By @emph{inherently} applicable
we mean Gauche unconditionally understands that @var{obj} can be called
as a procedure; an instance of @code{<procedure>} is so,
as well as generic functions (@code{<generic>}) and methods (@code{<method>}).
@xref{Generic function and method}, for the details.
@c JP
@var{obj}が@emph{生得的}に適用可能なオブジェクトであれば@code{#t}を、
そうでなければ@code{#f}を返します。@emph{生得的}にというのは、
Gaucheが最初から手続きとして呼び出せるオブジェクトとして備えているもの、程度の意味です。
@code{<procedure>}クラスのインスタンスや、
ジェネリックファンクションやメソッドがそうです。
(ジェネリックファンクションとメソッドに関しては
@ref{Generic function and method}を参照してください)。
@c COMMON

@c EN
Since you can make any type of objects applicable at any time
(@pxref{Applicable objects}), the fact that @code{procedure?} returned
@code{#f} doesn't mean that the object cannot be applied.
To check if an object can be applied or not, use @code{applicable?} below.
@c JP
Gaucheでは、どんなオブジェクトも適用可能にすることができます
(@ref{Applicable objects}参照)。従って、@code{procedure?}が@code{#f}を
返したからといってそのオブジェクトを手続きのように呼び出せないとは限りません。
オブジェクトが適用可能かどうかをより正確に調べるには、
下に説明する@code{applicable?}を使ってください。
@c COMMON
@end defun

@defun apply proc arg1 @dots{} args
[R7RS base]
@c EN
Calls a procedure @var{proc} with a list of arguments,
@code{(@var{arg1} @dots{} . @var{args})}.
The last argument @var{args} must be a proper list.
Returns (a) value(s) @var{proc} returns.
@c JP
@code{(@var{arg1} @dots{} . @var{args})}を引数として手続き@var{proc}を呼びます。
最後の引数@var{args}は正規のリストでなければなりません。 @var{proc}が返す
値をそのまま返します。
@c COMMON
@example
(apply list 'a 'b '(c d e)) @result{} (a b c d e)

(apply + 1 2 '(3 4 5))      @result{} 15
@end example
@end defun

@defun applicable? obj class @dots{}
@c EN
Checks if @var{obj} can be called with the types of arguments
listed in @var{class} @dots{}.  That is,
when @code{(applicable? foo <string> <integer>)} returns @code{#t},
then you can call @code{foo} as @code{(foo "x" -2)}, for example.
(It doesn't mean you won't get an error; @code{foo} may be accept
only nonnegative integers, which you cannot tell from the result of
@code{applicable?}.  But if @code{applicable?} returns @code{#t},
Gauche won't complain ``foo is not applicable'' when you call @code{foo}.
@c JP
それぞれの型が@var{class} @dots{}であるような引数リストを伴って
@var{obj}を呼び出すことができるかどうかを調べます。
例えば@code{(applicable? foo <string> <integer>)}が@code{#t}を
返したなら、@code{foo}を@code{(foo "x" -2)}のように呼び出せるということです。
(これは、エラーが出ないことを保証するものではありません。@code{foo}は
もしかする非負整数しか受け取れないかもしれませんが、そのことは
@code{applicable?}の結果からはわかりません。でも、@code{applicable?}が@code{#t}を
返したなら、@code{foo}を呼び出した時に``foo is not applicable''と
Gaucheに文句を言われることはありません。)
@c COMMON

@c EN
This procedure takes applicable objects into account.  So, for example,
@code{(applicable? #/a/ <string>)} returns @code{#t}, for the regular
expressions are applicable to a string (@pxref{Regular expressions}).
@c JP
この手続きは適用可能オブジェクトも考慮に入れます。
従って、例えば@code{(applicable? #/a/ <string>)}は@code{#t}を返します。
正規表現は文字列に適用可能だからです (@ref{Regular expressions}参照)。
@c COMMON

@c EN
For generic functions, @code{applicable?} returns @code{#t} if it has
at least one method such that each of its specifiers is a superclass
of the corresponding @var{class} argument given to @code{applicable?}.
@c JP
ジェネリックファンクションに対しては、
渡された@var{class}引数それぞれが、対応する特定化子と一致するかサブクラスになっている
ようなメソッドが最低ひとつあれば、@code{applicable?}は@code{#t}を返します。
@c COMMON

@example
(define-method foo ((x <sequence>) (y <integer>)) #f)

(applicable? foo <sequence> <integer>) @result{} #t
(applicable? foo <string> <integer>) @result{} #t
(applicable? foo <hash-table> <integer>) @result{} #f
(applicable? foo <string> <real>) @result{} #f
@end example

@c EN
The second example returns @code{#t} since @code{<string>} is
a subclass of @code{<sequence>}, while
the third example returns @code{#f} since @code{<hash-table>}
isn't a subclass of @code{<sequence>}.  The fourth example
returns @code{#f} since @code{<real>} isn't a subclass of @code{<integer>}.
@c JP
2番目の例では、@code{<string>}は@code{<sequence>}のサブクラスなので
@code{#t}が返ります。一方、3番目の例では@code{<hash-table>}は
@code{<sequence>}のサブクラスではないので@code{#f}となります。
4番めの例が@code{#f}なのは、@code{<real>}が@code{<integer>}のサブクラスではないからです。
@c COMMON

@c EN
Traditional Scheme procedures (such as ones created by @code{lambda})
only cares the number of arguments but not their types; it accepts
any type as far as the number of arguments matches.  To check such
a condition, pass @code{<top>} as the argument class.  (@code{<top>} is
a superclass of all classes.)
@c JP
伝統的なSchemeの手続き (@code{lambda}で作られるようなもの) は
引数の数のみで呼び出し可能かどうかが判断されます。オブジェクトが
引数の型にかかわらず、特定の個数の引数を取るかどうかを判定するには、
@var{class}引数に@code{<top>}を渡します。(@code{<top>}は
全てのクラスのスーパークラスです。)
@c COMMON

@example
(applicable? cons <top> <top>) @result{} #t
@end example

@c EN
If you want to check an object is applicable to a certain
number of @emph{some} class of arguments, you can pass @code{<bottom>}
as the argument class instead.   (@code{<bottom>} is a subclass of all
classes.)
@c JP
逆に、@emph{何らかの}特定の型の引数を取るかどうかを調べたい場合は、
@code{<bottom>}を渡してください。(@code{<bottom>}は全てのクラスのサブクラスです。)
@c COMMON

@example
(define-method foo ((x <sequence>) (y <integer>)) #f)

(applicable? foo <top> <top>) @result{} #f
(applicable? foo <bottom> <bottom>) @result{} #t
@end example

@c EN
@xref{Types and classes}, for the details of @code{<top>}, @code{<bottom>} and
Gauche's type handling.
@c JP
@code{<top>}, @code{<bottom>}クラスおよびGaucheでの型の扱いについては
@ref{Types and classes}を参照してください。
@c COMMON
@end defun

@defun procedure-type proc
@c EN
The argument must be a procedure.  Returns a descriptive type
of the @var{proc}, as much as the system knows.
@xref{Types and classes}, for the details of procedure types.
@c JP
引数は手続きでなければなりません。手続き@var{proc}の記述的な型を、
わかる範囲で返します。
手続きの型について詳しくは@ref{Types and classes}を参照してください。
@c COMMON

@c EN
The ``type'' returned by this procedure is just a hint.
Currently, most Scheme-defined procedures doesn't have much type info.
@c JP
この手続きで返される型は一種のヒントにすぎません。
今のところ、ほとんどのSchemeで定義された手続きからは、あまり詳しい型情報は取れません。
@c COMMON

@example
(procedure-type filter) @result{} #<^ <top> <top> -> *>
@end example

@c EN
Some of subrs (C-defined procedures) has a bit more info, derived
from C type information.
@c JP
subr (Cで定義された手続き) の中には、Cの型情報を使って多少詳しい情報が
取れるものもあります。
@c COMMON
@example
(procedure-type cons) @result{} #<^ <top> <top> -> <pair>>
@end example

@c EN
Eventually we'll improve this system to return more precise type info,
and use it for optimizations and other static analysis.
@c JP
いずれ、より正確な型情報を取れるようにして、
最適化やその他の静的解析に使えるようにする予定です。
@c COMMON
@end defun


@node Universal accessor, Combinators, Procedure class and applicability, Procedures and continuations
@subsection Universal accessor
@c NODE 万能アクセサ

@defun ~ obj key keys @dots{}
@defunx {(setter ~)} obj key keys @dots{}
@c EN
The procedure @code{~} can be used to access a part of various
aggregate types.
@c JP
手続き@code{~}は、様々な集合型のオブジェクトの部分にアクセスするのに使えます。
@c COMMON

@example
;; Access to an element of a sequence by index
(~ '(a b c) 0)       @result{} a
(~ '#(a b c) 2)      @result{} c
(~ "abc" 1)          @result{} #\b
(~ '#u8(10 20 30) 1) @result{} 20

;; Access to an element of a collection by key
(~ (hash-table 'eq? '(a . 1) '(b . 2)) 'a)
  @result{} 1

;; Access to a slot of an object by slot name
(~ (sys-localtime (sys-time)) 'hour)
  @result{} 20
@end example

@c EN
The access can be chained:
@c JP
アクセスはチェインすることができます。
@c COMMON

@example
(~ '#((a b c) (d e f) (g h i)) 1 2) @result{} f

(~ (hash-table 'eq? '(a . "abc") '(d . "def")) 'a 2)
  @result{} #\c
@end example

@c EN
You can think @code{~} as left-associative, that is,
@c JP
@code{~}は左結合します。つまり、
@c COMMON
@example
(~ x k j) @equiv{} (~ (~ x k) j)
@end example
@c EN
and so on.
@c JP
等。
@c COMMON

@c EN
The generalized setter @code{set!} can be used with @code{~} to
replace the specified element.
@c JP
一般化された@code{set!}を@code{~}に使えば、アクセスされる要素を置き換えることができます。
@c COMMON

@example
(define z (vector 'a 'b 'c))
(set! (~ z 1) 'Z)

z @result{} #(a Z c)

(define z (vector (list (vector 'a 'b 'c)
                        (vector 'd 'e 'f)
                        (vector 'g 'h 'i))
                  (list (vector 'a 'b 'c)
                        (vector 'd 'e 'f)
                        (vector 'g 'h 'i))))

z @result{} #((#(a b c) #(d e f) #(g h i))
     (#(a b c) #(d e f) #(g h i)))

(set! (~ z 1 2 0) 'Z)
z @result{}  #((#(a b c) #(d e f) #(g h i))
     (#(a b c) #(d e f) #(Z h i)))
@end example
@end defun

@c EN
Internally, a call to @code{~} is implemented by a generic
function @code{ref}.  See @ref{Object system} for more about
generic functions.
@c JP
@code{~}は内部的にジェネリックファンクション@code{ref}を使って実現されています。
ジェネリックファンクションについて詳しくは@ref{Object system}を参照してください。
@c COMMON

@deffn {Generic function} ref object key :optional args @dots{}
@deffnx {Generic function} {(setter ref)} object key value
@c EN
Many aggregate types defines a specialized method of these
to provide uniform access and mutation.   Meaning of
optional arguments @var{args} of @code{ref} depends
on each specialized method,
but it is common that the first optional argument of @code{ref}
is a @emph{fallback} value, which is to be returned when
@var{object} doesn't have a meaningful association with @var{key}.
@c JP
多くの集合型はこのジェネリックファンクションを特殊化し、
統一されたアクセス方法と変更方法を提供しています。
@code{ref}のオプショナル引数@var{args}の意味はメソッド毎に異なりますが、
最初のオプショナル引数は、@var{object}の@var{key}に対する値が無い場合の
フォールバック値として使われるのが普通です。
@c COMMON

@c EN
The manual entry of each aggregate type shows the specialized
method and its semantics in detail.
@c JP
正確な動作の定義は、@code{ref}メソッドを提供しているクラスごとに説明されています。
@c COMMON
@end deffn

@c EN
Conceptually, @code{~} can be understood as follows:
@c JP
@code{~}の動作は次のコードで理解できるでしょう。
@c COMMON

@example
(define ~
  (getter-with-setter
   (case-lambda
     [(obj selector) (ref obj selector)]
     [(obj selector . more) (apply ~ (ref obj selector) more)])
   (case-lambda
     [(obj selector val) ((setter ref) obj selector val)]
     [(obj selector selector2 . rest)
      (apply (setter ~) (ref obj selector) selector2 rest)])))
@end example

@c EN
(Gauche may use some short-cut for optimization, though,
so this code may not reflect the actual implementation.)
@c JP
(Gaucheは最適化のためにいくつかの型で短絡経路を使うこともあるので、
実際の実装とは異なります)
@c COMMON

@node Combinators, Optional argument parsing, Universal accessor, Procedures and continuations
@subsection Combinators
@c NODE コンビネータ

@c EN
Gauche has some primitive procedures that allows combinatory programming.
@c JP
Gaucheには、combinatory programmingに使えるいくつかの基本手続きがあります。
@c COMMON

@defun pa$ proc arg @dots{}
@c EN
Partial application.  Returns a procedure, and when it is
called with arguments @var{m} @dots{}, it is equivalent to call
@code{(proc arg @dots{} m @dots{})}.
@c JP
部分適用。手続きを返します。その手続きが引数@var{m} @dots{}を伴って
呼ばれた場合、それは@code{(proc arg @dots{} m @dots{})}と等価になります。
@c COMMON

@example
(define add3 (pa$ + 3))
(add3 4) @result{} 7

(map (pa$ * 2) '(1 2 3)) @result{} (2 4 6)
@end example

@c EN
Macros @code{cut} and @code{cute} defined in SRFI-26 provide
a similar abstraction, with a bit more flexible but less compact
notation.  @xref{Making procedures}.
@c JP
SRFI-26で定義されているマクロ@code{cut}と@code{cute}も似たような抽象化の
方法を提供しますが、@code{pa$}より多少柔軟性が高く、その分やや冗長です。
@ref{Making procedures}を参照して下さい。
@c COMMON

@c EN
SRFI-235 defines @code{left-section}, which is effectively the same
as @code{pa$} (@pxref{Combinators (SRFI)}).
@c JP
SRFI-235で定義される@code{left-section}は実質的に@code{pa$}と同じです。
@ref{Combinators (SRFI)}参照。
@c COMMON
@end defun

@defun apply$ proc
@defunx map$ proc
@defunx for-each$ proc
@c EN
Partial application versions of @code{apply}, @code{map} and @code{for-each}.
@c JP
@code{apply}, @code{map}と@code{for-each}の部分適用版です。
@c COMMON

@example
(define map2* (map$ (pa$ * 2)))
(map2* '(1 2 3)) @result{} (2 4 6)
@end example

@end defun

@defun count$ pred
@defunx fold$ kons :optional knil
@defunx fold-right$ kons :optional knil
@defunx reduce$ f :optional ridentity
@defunx reduce-right$ f :optional ridentity
@defunx filter$ pred
@defunx remove$ pred
@defunx partition$ pred
@defunx member$ item
@defunx find$ pred
@defunx find-tail$ pred
@defunx any$ pred
@defunx every$ pred
@defunx delete$ pred
@defunx assoc$ item
@c EN
Partial application versions of some SRFI-1 (R7RS @code{(scheme list)})
procedures (@pxref{R7RS lists}).
@c JP
SRFI-1 (R7RS @code{(scheme list)})
(@ref{R7RS lists}参照)の手続に対応する部分適用版手続。
@c COMMON
@end defun

@defun .$ f @dots{}
@defunx compose f @dots{}
@c EN
Combine procedures.  All arguments must be procedures.
When two procedures are given, @code{(.$ f g)} is equivalent to
the following code:
@c JP
複数の手続きを結合します。引数は全て手続きでなければなりません。
2つの引数が渡された時、@code{(.$ f g)}は次の式と等価です。
@c COMMON
@example
(lambda args (call-with-values (lambda () (apply g args)) f))
@end example

@c EN
When more than two arguments are passed, they are composed
as follows:
@c JP
2つ以上の引数が渡された場合は、次のように結合されます。
@c COMMON
@example
(.$ f g h ...) @equiv{} (.$ (.$ f g) h ...)
@end example

@c EN
Some examples:
@c JP
いくつか例を示します。
@c COMMON

@example
(define not-zero? (.$ not zero?))
(not-zero? 3) @result{} #t
(not-zero? 0) @result{} #f

(define dot-product (.$ (apply$ +) (map$ *)))
(dot-product '(1 2 3) '(4 5 6)) @result{} 32
@end example

@c EN
A couple of edge cases: if only one argument is given, the argument
itself is returned.  If no arguments are given, the procedure @code{values}
is returned.
@c JP
境界のケース：ひとつだけ引数が渡された場合は、その引数がそのまま返されます。
引数が全く渡されなかった場合は手続き@var{values}が返されます。
@c COMMON

@c EN
SRFI-210 provides @code{compose-left} and @code{compose-right};
@pxref{Procedures and syntax for multiple values}.
@c JP
なお、SRFI-210に@code{compose-left}と@code{compose-right}が定義されています。
@ref{Procedures and syntax for multiple values}参照。
@c COMMON
@end defun

@defun identity obj
@c EN
Returns @var{obj}.  You can use @code{values} to get the same
effect for the porable code,
but using this emphasizes that you're dealing with exactly one value.
@c JP
@var{obj}を返します。ポータブルなコードでは@code{values}を使って同じ効果を
得ることができますが、これを使うことにより単一の値を扱っていることを強調できます。
@c COMMON

@c EN
Note: SRFI-210 introduces multi-valued @code{identity} (unfortunately), which is
a synonym to @code{values} (@pxref{Procedures and syntax for multiple values}).
@c JP
註: SRFI-210は複数の値を扱う@code{identity}を(残念ながら)導入してしまいました。
それは@code{values}の別名にすぎません。
@ref{Procedures and syntax for multiple values}参照。
@c COMMON
@end defun

@defun constantly obj @dots{}
[SRFI-235]
@c EN
Returns a procedure that takes arbitrary number of arguments, discards
them, and returns @var{obj} obj @dots{}.
Same as @code{(^ _ (values obj @dots{}))}.
@c JP
任意個の引数をとり、それらを無視して@var{obj}を返す関数を返します。
@code{(^ _ (values obj @dots{}))}と同じです。
@c COMMON
@end defun

@defun complement pred
[SRFI-235]
@c EN
Returns a procedure that reverses the meaning of the predicate @var{pred}.
That is, for the arguments for which @var{pred} returns true return
false, and vice versa.
@c JP
述語@var{pred}の意味を逆にした手続きを返します。すなわち、@var{pred}が真を
返すような引数にたいして偽を返す、またその逆も同様であるような手続きです。
@c COMMON

@example
(map (complement even?) '(1 2 3)) @result{} '(#t #f #t)
(map (complement =) '(1 2 3) '(1 1 3)) @result{} '(#f #t #f)
((complement (lambda () #f))) @result{} #t
@end example
@end defun

@defun flip proc
[SRFI-235]
@c EN
Returns a procedure that passes its arguments to @var{proc} in
reverse order, that is, @code{((flip proc) a b @dots{} y z)} is
@code{(proc z y @dots{} b a)}.
@c JP
渡された引数を逆順で@var{proc}に渡すような手続きを返します。すなわち、
@code{((flip proc) a b @dots{} y z)}は
@code{(proc z y @dots{} b a)}と同じです。
@c COMMON
@end defun

@defun swap proc
[SRFI-235]
@c EN
@var{Proc} must be a procedure that takes two arguments or more.
Returns a procedure that passes its first and second arguments
swapped to @var{proc}, that is,
@code{((swap proc) a b arg @dots{})} is
@code{(proc b a arg @dots{})}.
@c JP
@var{proc}は2つ以上の引数を取る手続きでなければなりません。
渡された引数の最初と2番めの引数の順序を入れ替えて@var{proc}を呼び出す手続きを
返します。すなわち、
@code{((swap proc) a b arg @dots{})}は
@code{(proc b a arg @dots{})}と同じです。
@c COMMON
@end defun

@defun any-pred pred @dots{}
@c EN
Returns a procedure which applies given argument(s) to
each predicate @var{pred}.  If any @var{pred} returns
a non-@code{#f} value, the value is returned.  If all the @var{pred}s
return @code{#f}, @code{#f} is returned.
@c JP
与えられた引数をそれぞれ述語@var{pred}に適用する手続きを返します。
いずれかの@var{pred}が@code{#f}でない値を返す場合、その値を返します。
全ての@var{pred}が@code{#f}を返す場合、@code{#f}を返します。
@c COMMON

@example
(define string-or-symbol? (any-pred string? symbol?))
(string-or-symbol? "abc") @result{} #t
(string-or-symbol? 'abc)  @result{} #t
(string-or-symbol? 3)     @result{} #f

(define <> (any-pred < >))
(<> 3 4) @result{} #t
(<> 3 3) @result{} #f

((any-pred (cut memq <> '(a b c))
           (cut memq <> '(1 2 3)))
 'b)  @result{} '(b c)
@end example
@end defun

@defun every-pred pred @dots{}
@c EN
Returns a procedure which applies given argument(s) to
each predicate @var{pred}.  If every @var{pred} returns
a non-@code{#f} value, the value returned by the last @var{pred}
is returned.  If any @var{pred} returns @code{#f}, @code{every-pred}
returns @code{#f} without calling further @var{pred}s.
@c JP
与えられた引数をそれぞれ述語@var{pred}に適用する手続きを返します。
全ての@var{pred}が@code{#f}でない値を返す場合、戻り値は最後の
@var{pred}の戻り値になります。いずれかの@var{pred}が@code{#f}を
返す場合、@code{every-pred}はそれ以降の@var{pred}を呼び出さずに
@code{#f}を返します。
@c COMMON

@example
((every-pred odd? positive?) 3)  @result{} #t
((every-pred odd? positive?) 4)  @result{} #f
((every-pred odd? positive?) -3) @result{} #f

(define safe-length (every-pred list? length))
(safe-length '(a b c))  @result{} 3
(safe-length "aaa")     @result{} #f
@end example
@end defun

@node Optional argument parsing, Procedure arity, Combinators, Procedures and continuations
@subsection Optional argument parsing
@c NODE 省略可能引数のパージング

@c EN
Gauche supports optional and keyword arguments in extended
lambda syntax (@pxref{Making procedures}).  However, you can
also use the following macros to parse optional and keyword
arguments, without relying Gauche's extension.
@c JP
Gaucheは省略可能引数やキーワード引数を拡張lambda構文で
サポートしています (@ref{Making procedures}参照)。
けれども、Gauche拡張に頼らずに、以下のマクロを使って独自にこれらの引数を
パーズすることもできます。
@c COMMON

@example
(define (foo a b :optional (c #f) (d 'none))
  body ...)

@c EN
;; is roughly equivalent to ...
@c JP
;; は次の式とだいたい同じ:
@c COMMON

(define (foo a b . args)
  (let-optionals* args ((c #f) (d 'none))
    body ...))
@end example

@c EN
Explicitly parsing the extended arguments may be useful for
portable programs, since it is rather straightforward to
implement those macros rather than extend lambda syntax.

Those macros can also be useful to factor out common
argument parsing routines.
@c JP
明示的に拡張引数をパーズする方法は、ポータブルなコードを書く時に
役に立つでしょう。以下のマクロを実装するのは、lambdaの構文を
拡張するより簡単だからです。

また、共通する拡張引数の処理ルーチンを括り出す場合にもこれらのマクロは有用です。
@c COMMON

@defmac let-optionals* restargs (var-spec @dots{}) body @dots{}
@defmacx let-optionals* restargs (var-spec @dots{} . restvar) body @dots{}
@c EN
Given a list of values @var{restargs}, binds variables according
to @var{var-spec}, then evaluates @var{body}.
@c JP
与えられた値のリスト@var{restargs}を、@var{var-spec}にしたがって
変数に束縛し、@var{body}を評価します。
@c COMMON

@c EN
@var{Var-spec} can be either a symbol, or a list of two elements
and its car is a symbol.  The symbol is the bound variable name.
The values in @var{restargs} are bound to the symbol in order.
If there are not as many values in @var{restargs} as @var{var-spec},
the rest of @var{symbol}s are bound to the default values, determined
as follows: If @var{var-spec} is just a symbol, the default value is
undefined.  If @var{var-spec} is a list, the default value is
the result of evaluation of the second element of the list.
In the latter case the second
element is only evaluated when there are not enough arguments.
The binding proceeds in the order of @var{var-spec}, so the second
element may refer to the bindings of previous @var{var-spec}.
@c JP
@var{var-spec}はシンボルか、そのcarがシンボルである2要素のリストの
いずれかです。シンボルは束縛された変数名です。
@var{restargs}にある値は、順番にシンボルに束縛されます。
@var{restargs}に@var{var-spec}に示される数の値がない場合は、
残りの@var{symbol}は以下に従ってデフォルト値が束縛されます。
@var{var-spec}が単なるシンボルなら、デフォルト値は未定義です。
@var{var-spec}がリストなら、デフォルト値はリストの2番目の要素を
評価した結果です。後者の場合、2番目の要素は十分な引数がない場合にのみ
評価されます。
束縛は@var{var-spec}の順番にしたがって行われるので、2番目の要素は
以前の@var{var-spec}のバインディングを参照するかも知れません。
@c COMMON

@c EN
In the second form, @var{restvar} must be a symbol and bound to
the list of values whatever left from @var{restargs} after binding
to @var{var-spec}.
@c JP
2番目のフォームでは、@var{restvar}はシンボルでなければならず、
@var{var-spec}に束縛された後、@var{restargs}に残っている値のリストに
束縛されます。
@c COMMON

@c EN
It is not an error if @var{restarg} has more values than @var{var-spec}s.
The extra values are simply ignored in the first form.
@c JP
@var{restarg}が@var{var-spec}よりも多い値を持っていてもエラーでは
ありません。最初のフォームでは、余分な値は単に無視されます。
@c COMMON

@example
(define (proc x . args)
  (let-optionals* args ((a 'a)
                        (b 'b)
                        (c 'c))
    (list x a b c)))

(proc 0)         @result{} (0 a b c)
(proc 0 1)       @result{} (0 1 b c)
(proc 0 1 2)     @result{} (0 1 2 c)
(proc 0 1 2 3)   @result{} (0 1 2 3)

(define (proc2 . args)
  (let-optionals* args ((a 'a) . b)
    (list a b)))

(proc2)          @result{} (a ())
(proc2 0)        @result{} (0 ())
(proc2 0 1)      @result{} (0 (1))
(proc2 0 1 2)    @result{} (0 (1 2))

(define (proc3 . args)
  (let-optionals* args ((a 0)
                        (b (+ a 1))
                        (c (+ b 1)))
    (list a b c)))

(proc3)          @result{} (0 1 2)
(proc3 8)        @result{} (8 9 10)
(proc3 8 2)      @result{} (8 2 3)
(proc3 8 2 -1)   @result{} (8 2 -1)
@end example
@end defmac

@defmac get-optional restargs default
@c EN
This is a short version of @code{let-optionals*} where you have only
one optional argument.  Given the optional argument list @var{restargs},
this macro returns the value of optional argument if one is given,
or the result of @var{default} otherwise.  @var{Default} is not
evaluated unless @var{restargs} is an empty list.
@c JP
これは@code{let-optionals*}の短いバージョンで、オプショナル引数が
1つしかないときに使います。オプショナル引数のリストとして@var{restargs}が
与えらると、このマクロはオプショナル引数が与えられていればその値を返し、
そうでなければ@var{default}の結果を返します。@var{default}は@var{restargs}が
空リストでなければ評価されません。
@c COMMON

@example
(define (proc x . maybe-opt)
  (let ((option (get-optional maybe-opt #f)))
    (list x option)))

(proc 0)         @result{} (0 #f)
(proc 0 1)       @result{} (0 1)
@end example
@end defmac

@defmac let-keywords restarg (var-spec @dots{}) body @dots{}
@defmacx let-keywords restarg (var-spec @dots{} . restvar) body @dots{}
@c EN
This macro is for keyword arguments.  @var{Var-spec} can be
one of the following forms:
@c JP
このマクロはキーワード引数のためのものです。@var{var-spec}は
以下のフォームのうちのいずれかです。
@c COMMON

@table @code
@item (@var{symbol} @var{expr})
@c EN
If the @var{restarg} contains keyword which has the same name as @var{symbol},
binds @var{symbol} to the corresponding value.  If such a keyword doesn't
appear in @var{restarg}, binds @var{symbol} to the result of @var{expr}.
@c JP
@var{restarg}が@var{symbol}と同じ名前を持つキーワードを含んでいる場合、
@var{symbol}を対応する値に束縛します。そのようなキーワードが@var{restarg}に
ない場合は、@var{symbol}を@var{expr}の結果に束縛します。
@c COMMON
@item (@var{symbol} @var{keyword} @var{expr})
@c EN
If the @var{restarg} contains keyword @var{keyword},
binds @var{symbol} to the corresponding value.  If such a keyword doesn't
appear in @var{restarg}, binds @var{symbol} to the result of @var{expr}.
@c JP
@var{restarg}がキーワード@var{keyword}を含む場合、
@var{symbol}を対応する値に束縛します。そのようなキーワードが@var{restarg}に
ない場合、@var{symbol}を@var{expr}の結果に束縛します。
@c COMMON
@end table

@c EN
The default value @var{expr} is only evaluated when the keyword is
not given to the @var{restarg}.
@c JP
デフォルト値@var{expr}は、@var{restarg}にキーワードが与えられてなかった
場合にのみ評価されます。
@c COMMON

@c EN
If you use the first form, @code{let-keyword} throws an error
when @code{restarg} contains a keyword argument that is not listed
in @var{var-spec}s.
When you want to allow keyword arguments other than listed in
@var{var-spec}s, use the second form.

In the second form, @var{restvar} must be either a symbol or @code{#f}.
If it is a symbol, it is bound to a list of keyword arguments
that are not processed by @var{var-spec}s.  If it is @code{#f},
such keyword arguments are just ignored.
@c JP
1番目のフォームでは、@var{var-spec}にないキーワード引数が@var{restarg}に
現れるとエラーとなります。
他のキーワード引数を許したい場合は次の2番目のフォームを使ってください。

2番目のフォームでは、@var{restvar}はシンボルか@code{#f}でなければなりません。
シンボルのときは、@var{var-spec}に束縛されなかった@var{restargs}のキーワード
リストが@var{restvar}に束縛されます。@code{#f}のときは、それらの@var{restargs}
のキーワードは単に無視されます。
@c COMMON

@example
(define (proc x . options)
  (let-keywords options ((a 'a)
                         (b :beta 'b)
                         (c 'c)
                         . rest)
    (list x a b c rest)))

(proc 0)         @result{} (0 a b c ())
(proc 0 :a 1)    @result{} (0 1 b c ())
(proc 0 :beta 1) @result{} (0 a 1 c ())
(proc 0 :beta 1 :c 3 :unknown 4) @result{} (0 a 1 3 (:unknown 4))
@end example
@end defmac

@defmac let-keywords* restarg (var-spec @dots{}) body @dots{}
@defmacx let-keywords* restarg (var-spec @dots{} . restvar) body @dots{}
@c EN
Like @code{let-keywords}, but the binding is done in the order of
@var{var-spec}s.  So each @var{expr} can refer to the variables bound by
preceding @var{var-spec}s.
@c JP
このマクロは@code{let-keywords}とほぼ同じですが、束縛が@var{var-spec}での
順番に行われるところが異なります。@var{expr}は以前の@var{var-spec}により
束縛された変数を参照できます。
@c COMMON
@end defmac

@node Procedure arity, Applicable objects, Optional argument parsing, Procedures and continuations
@subsection Procedure arity
@c NODE 手続きのアリティ

@c EN
Interface to query procedure's arity.
The API is taken from MzScheme (PLT Scheme).
@c JP
手続きのアリティを問い合わせるインターフェースです。
APIは、MzScheme (PLT Scheme)を参考にしました。
@c COMMON

@defun arity @var{proc}
@c EN
Given procedure @var{proc},
returns an integer, an @emph{arity-at-least} object, or
a list of integer(s) and @emph{arity-at-least} objects.
@c JP
手続き@var{proc}を与え、整数、@emph{arity-at-least}オブジェクト、
整数と@emph{arity-at-least}オブジェクトからなるリストのいずれかを
返します。
@c COMMON

@c EN
An integer result indicates @var{proc} takes exactly that number
of arguments.  An @emph{arity-at-least} indicates @var{proc} takes
at least @code{(arity-at-least-value @emph{arity-at-least})}
arguments.   The list indicates there are multiple procedures
with different arities.
@c JP
整数の戻り値は、@var{proc}が正確にその数の引数を取ることを表します。
@emph{arity-at-least}は、@var{proc}が最低でも
引数@code{(arity-at-least-value @emph{arity-at-least})}を取ることを
表します。リストは、異なるアリティを持つ複数の手続きがあることを
表します。
@c COMMON

@c EN
Since one can add methods to an existing procedure or generic function
at any moment in Gauche, the value returned by @code{arity} only
indicates the current state of the procedure.  It will change
if new method is added to the procedure/generic-function.
@c JP
Gaucheではいつでも、既存の手続きやジェネリック関数にメソッドを追加
できるので、@code{arity}が返す値はその手続きの現在の状態を示すに
過ぎません。その手続きやジェネリック関数に新しいメソッドが追加
されると、それも変更されます。
@c COMMON

@example
(arity cons) @result{} 2
(arity list) @result{} #<arity-at-least 0>
(arity make) @result{} (#<arity-at-least 1>)
@end example
@end defun

@defun arity-at-least? @var{obj}
@c EN
Returns true if @var{obj} is an arity-at-least object.
@c JP
@var{obj}がarity-at-leastオブジェクトなら、真を返します。
@c COMMON
@end defun

@defun arity-at-least-value @var{arity-at-least}
@c EN
Returns the number of required arguments the arity-at-least object
indicates.
@c JP
arity-at-leastオブジェクトが表す必須引数の数を返します。
@c COMMON
@end defun

@defun procedure-arity-includes? @var{proc} @var{k}
@c EN
If a procedure @var{proc} can take @var{k} arguments, returns @code{#t}.
Otherwise returns @code{#f}.
@c JP
手続き@var{proc}が引数@var{k}を取れる場合、@code{#t}を返します。
そうでなければ@code{#f}を返します。
@c COMMON
@end defun


@node Applicable objects, Continuations, Procedure arity, Procedures and continuations
@subsection Applicable objects
@c NODE 適用可能なオブジェクト

@c EN
Gauche has a special hook to make an arbitrary object @emph{applicable}.
@c JP
Gaucheでは、特別な組み込みの機構によって任意のオブジェクトを
「適用可能」にすることができます。
@c COMMON

@deffn {Generic Function} object-apply @var{object} @var{arg} @dots{}
@c EN
If an object that is neither a procedure nor a generic function
is applied to some arguments,
the object and the arguments are passed to a generic function
@code{object-apply}.

This can be explained better by examples.
@c JP
手続きでもジェネリックファンクションでもないオブジェクトが何らかの引数に
適用されたとき、そのオブジェクトと引数がジェネリックファンクション@code{object-apply}
に渡されます。

この機能は、具体的な例を挙げた方が説明し易いでしょう。
@c COMMON
@end deffn

@c EN
For example, suppose you try to evaluate the
following expression:
@c JP
例えば、次のような式を評価しようとしたとします。
@c COMMON

@example
("abcde" 2)
@end example

@c EN
The operator evaluates to a string, which is neither a procedure
nor a generic function.  So Gauche interprets the expression
as if it were like this:
@c JP
オペレータは文字列に評価されますから、手続きでもジェネリックファンクションでも
ありません。そこで、Gaucheはこの式を、あたかも次のような式が与えられた
かのように解釈します。
@c COMMON

@example
(object-apply "abcde" 2)
@end example

@c EN
Gauche doesn't define a method of @code{object-apply} that takes
@code{<string>} and @code{<integer>} by default, so this signals an error.
However, if you define such a method:
@c JP
デフォルトでは、@code{<string>}と@code{<integer>}を引数とする
@code{object-apply}のメソッドは定義されていないので、
この式はエラーになります。しかし、次のようなメソッドを定義すると：
@c COMMON

@example
(define-method object-apply ((s <string>) (i <integer>))
  (string-ref s i))
@end example

@c EN
Then the first expression works as if a string is @emph{applied} on
the integer:
@c JP
最初の式はまるで文字列が整数に適用されたかのように動作します。
@c COMMON

@example
("abcde" 2) @result{} #\c
@end example

@c EN
This mechanism works on almost all occasions where a procedure is allowed.
@c JP
このメカニズムは手続きが許されるほとんどの箇所で使うことができます。
@c COMMON

@example
(apply "abcde" '(1))   @result{} (#\b)
(map "abcde" '(3 2 1)) @result{} (#\d #\c #\b)
@end example

@c EN
Among Gauche built-in objects, @code{<regexp>} object and
@code{<regmatch>} object have @code{object-apply} defined.
@xref{Regular expressions}.
@c JP
Gauche組み込みオブジェクトのうち、@code{<regexp>}オブジェクトと
@code{<regmatch>}オブジェクトに対しては@code{object-apply}メソッドが定義されて
います。@ref{Regular expressions}を参照して下さい。
@c COMMON

@c EN
Note: Defining @code{object-apply} method affect globally.  Although it is cool
to define @code{object-apply} on strings as in the above example,
it is not recommended as a general trick, for
it'll change the behavior of string across the entire program.

Keep the above example personal experiments.  In general, you should
only define @code{object-apply} on your own classes.
@c JP
註: @code{object-apply}メソッドの定義はグローバルに影響します。
上の例のように文字列に@code{object-apply}を定義するのはおもしろいですが、
一般的なトリックとしては推奨されません。これによってプログラム全体での
文字列の振る舞いが変わってしまうからです。

上の例は個人的な実験に留めておきましょう。一般的には、
自分で定義したクラスに対してのみ@code{object-apply}を定義するのが良いです。
@c COMMON


@deffn {Generic Function} {(setter object-apply)} @var{object} @var{arg} @dots{} @var{value}
@c EN
If a form of applying an applicable object appears in the first position
of @code{set!} form, this method is called, that is:
@c JP
適用可能オブジェクトを適用するフォームが@code{set!}フォームの第一ポジションに
現れた場合、そのフォームは下に示すように展開され、このメソッドが呼ばれます。
@c COMMON
@example
(set! (@var{object} @var{arg} @dots{}) @var{value})
 @result{} ((setter object-apply) @var{object} @var{arg} @dots{} @var{value})
@end example
@end deffn




@node Continuations, Continuation prompts, Applicable objects, Procedures and continuations
@subsection Continuations
@c NODE 継続


@defun call-with-current-continuation proc
@defunx call/cc proc
[R7RS base]
@c EN
Encapsulates the current continuation to a procedure
(``continuation procedure''), and calls @var{proc} with it.
When @var{proc} returns, its value becomes @code{call/cc}'s value.
When the continuation procedure is invoked with zero or more arguments
somewhere, the further calculation is abandoned and @code{call/cc} returns
with the arguments given to the continuation procedure.
@c JP
現在の継続を手続き (継続手続き) にパッケージ化して、それを引数として
@var{proc}を呼び出します。@var{proc}が戻ったら、その返り値が@code{call/cc}の
値となります。作成された継続手続きがどこかで0個または複数個の引数を伴って呼ばれたら、
あたかも@code{call/cc}から戻ったかのように実行が継続されます。その場合、
@code{call/cc}は、継続手続きに与えられた引数を複数の値として返します。
@c COMMON

@c EN
First class continuation is one of the most distinct feature of Scheme, but
this margin is too small to contain explanation.
Please consult to the appropriate documents.
@c JP
ファーストクラスの継続はSchemeの最も特徴的な機能のひとつですが、それを
十分に説明するにはこの本の余白は狭すぎます。適切なドキュメントを参照してください。
@c COMMON

@c EN
There's a nontrivial interaction between C language runtime and
Scheme continuation.   Suppose the following scenario:
@c JP
Schemeの継続とC言語の実行環境との間に、ちょっとわかりずらい干渉が生じることがあります。
次のシナリオを考えます。
@c COMMON

@enumerate
@item
@c EN
An application's C runtime calls back a Scheme routine.  For example,
GUI framework calls back a draw routine written in Scheme.
@c JP
アプリケーションのCランタイムがSchemeで書かれた手続きをコールバックします。
例えば、GUIフレームワークがSchemeで書かれた描画ルーチンを呼ぶ、というようなケースを考えてください。
@c COMMON
@item
@c EN
A continuation is captured in the Scheme routine.
@c JP
そのSchemeルーチンで継続が捕捉される。
@c COMMON
@item
@c EN
The Scheme routine returns to the C runtime.
@c JP
Schemeルーチンが終了してCランタイムに制御を戻す。
@c COMMON
@item
@c EN
The continuation captured in 2 is invoked.
@c JP
2で捕捉した継続が起動される。
@c COMMON
@end enumerate

@c EN
It is no problem to invoke the continuation, but if the control
is about to return to the Scheme routine to the C runtime (that is,
to execute step 3 again), an error is signaled as follows.
@c JP
継続を起動すること自体には問題は無いのですが、
制御がSchemeからCへと再び戻ろうとすると (つまり、step 3が再び実行されようとすると)
次のようなエラーが投げられます。
@c COMMON

@example
*** ERROR: attempt to return from a ghost continuation.
@end example

@c EN
This is because C routines don't expect the calling function to return
more than once.  The C stack frame on which the Scheme callback was
originally called
is likely to be deallocated or modified at the time the continuation
is invoked.

If you think of a continuation as a chain of control
frames, growing from root towards upward,
you can imagine that, once a control returns to the C world, the chain is
cut at the boundary.  You can still execute such rootless
continuations, but you have to move the control away from it before it tries
to return to its root that no longer exists.
You can call another continuation, or raise an exception, for example.
@c JP
これは、Cの世界では関数が1回より多く戻ってくることを想定していないからです。
最初にSchemeのコールバックが呼ばれた時のCのスタックフレームは、
継続が再び呼ばれた時には状態が変わっているか、捨てられてしまっているでしょう。

継続を、根から上へ向かって成長する制御フレームの連鎖のようにイメージした場合、
Cの世界へ戻った時点でその連鎖が断ち切られる、と考えることができます。
そのような根無しの継続も実行することはできますが、既に失った根に戻る前に
別の箇所へと制御を移さねばなりません。他の箇所で捕まえた継続を呼んだり、
例外を投げるといったことが考えられます。
@c COMMON

@c EN
Using partial continuations (or delimited continuations) is another
way to avoid such complications.
@xref{Partial continuations}.
@c JP
部分継続(限定継続)を使うのも手です。
@ref{Partial continuations}を参照してください。
@c COMMON
@end defun

@defmac let/cc var body @dots{}
@c EN
This macro expands to :
@c JP
このマクロは次のように展開されます :
@c COMMON
@code{(call/cc (lambda (@var{var}) @var{body} @dots{}))}.
@c EN
The API is taken from PLT Scheme.
@c JP
APIはPLT Schemeから取りました。
@c COMMON
@end defmac


@defun dynamic-wind before body after
[R7RS base]
@c EN
This is a primitive to manage @emph{dynamic environment}.
Dynamic environment is a set of states which are kept during execution
of a certain expression.  For example, the current output ports
are switched @emph{during} execution of @code{with-output-to-port}.
They can be nested dynamically, as opposed to
the lexical environment, in which nesting is determined statically
from the program source.

@var{Before}, @var{body} and @var{after} are all procedures with
no arguments.
In normal situation, @code{dynamic-wind} calls @var{before}, then @var{body},
then @var{after}, then returns whatever value(s) @var{body} returned.

The intention is that the @var{before} thunk sets up the dynamic
environment for execution of @var{body}, and the @var{after} thunk
restores it to the previous state.

If a control flow goes out from @var{body} by invoking a continuation
captured outside of the dynamic scope of @code{dynamic-wind}
(for example, an error is signaled in @var{body}),
@var{after} is called.

If a control flow goes into @var{body} by invoking a continuation
captured inside @var{body} from outside of the dynamic
scope of @code{dynamic-wind}, @var{before} is called.
@c JP
これは@emph{動的環境}を管理するための基本手続きです。
動的環境とは、ある式を実行している間、維持される状態のセットのことです。
例えば「現在の出力ポート」というのは、@code{with-output-to-port}手続きの
@emph{実行中}だけ切り替えることができます。
動的環境は動的にネストできます。これは、プログラムのソースから静的に
ネストが決定できる字句環境とは異なります。

@var{before}、@var{body}および@var{after} は引数を取らない手続きです。
@code{dynamic-wind}はまず@var{before}を呼び出し、続いて@var{body}を呼び出し、
続いて@var{after}を呼び出します。そして@var{body}が返した値を返します。

@var{before}手続きが@var{body}を実行するための動的環境を
設定し、@var{after}手続きが動的環境を元に戻す、ということが意図されています。

もし@code{dynamic-wind}のダイナミックスコープの外で捕捉された継続が
@var{body}の中で呼ばれることにより制御が@var{body}から飛び出した場合、
(@var{body}の中でエラーが起こった場合などが考えられます)、
@var{after}が呼ばれます。

もし、@var{body}の中で捕捉された継続が@code{dynamic-wind}のダイナミックスコープの
外で呼ばれることにより制御が@var{body}の中へ飛び込んだ場合、
@var{before}が呼ばれます。
@c COMMON
@example
(letrec ((paths '())
         (c #f)
         (add (lambda (s) (push! paths s))))
  (dynamic-wind
   (lambda () (add 'connect))
   (lambda ()
     (add (call/cc (lambda (c0) (set! c c0) 'talk1))))
   (lambda () (add 'disconnect)))
  (if (< (length paths) 4)
      (c 'talk2)
      (reverse paths)))
 @result{} (connect talk1 disconnect connect talk2 disconnect)
@end example

@c EN
Note: Since @var{after} is guaranteed to be called when
an error causes @var{body} to abort, it may appear tempting
to use @code{dynamic-wind} to use resource clean-up, just like
@code{try-catch} construct in Java.  It's @emph{not} for that.
Since the control may return to @var{body}, the situation
@code{dynamic-wind} handles should be considered more like
a context switch.

For resource clean-up, you can use exception handling mechanism
such as @code{guard} and @code{unwind-protect}
(@pxref{High-level exception handling mechanism}),
which is built on top of @code{dynamic-wind}.

As a rule of thumb, @var{after} should do things that can be
reverted by @var{before}, such as manipulating error handler stack
(instead of actually handling errors).
@c JP
註：エラーにより@var{body}が中断された時に必ず@var{after}が呼ばれることから、
@code{dynamic-wind}を例えばJavaの@code{try-catch}構文のように考えて
リソースの後処理などに使いたくなるかもしれません。
しかし@code{dynamic-wind}はそのためのものでは@emph{ありません}。
一旦離れた制御が@var{body}に再び戻ってくる可能性があるので、
@code{dynamic-wind}が管理するのはむしろコンテキストスイッチに近い状況です。

リソースの後処理には、@code{guard}や@code{unwind-protect}などの例外処理
が使えます(@ref{High-level exception handling mechanism}参照)。
それらは@code{dynamic-wind}を使って構築されています。

基本的な指針として、@var{after}は常に@var{before}によって効果を戻せる
処理だけを行うべきです。例えば、(エラーを直接処理するのではなく)
エラーハンドラスタックを操作する、といった具合に。
@c COMMON
@end defun

@node Continuation prompts, Continuation marks, Continuations, Procedures and continuations
@subsection Continuation prompts
@c NODE 継続プロンプト

@c EN
Continuations are often explained as ``the rest of computation''.
It is enough for theorists to write papers, but in practice,
we cannot reify the computations ``from now on for ever''.  There has
to be an end--it may be until a single program terminates, or
until a server returns a response to a request, or a REPL
prints the result of evaluation.  Implementations
have chosen the ``end'' of continuations suitable for there needs.
Sometimes, though, the ambiguity caused confusion.
@c JP
継続はよく「計算の残りの部分」と説明されます。理論家が論文を書くにはそれで充分なんですが、
現実には、「未来永劫の計算全て」を具体化することはできません。
どこかに終わりがないと困ります。それはひとつのプログラムの終了かもしれませんし、
サーバーがリクエストに対するレスポンスを送り終えるまでかもしれませんし、
REPLが与えられた式の評価結果を出力し終わるまでかもしれませんが。
従来は、実装が必要に応じて継続の「終わり」を選んできたのですが、
これはしばしば混乱の元になっていました。
@c COMMON

@c EN
Continuation prompts are to make the ``end'' of continuation explicit.
It is called a prompt because, in the interactive environment,
REPL prompt is usually delimits the continuation.  If you think
of activation records as a stack, a continuation prompt is
the ``bottom'' of the stack.
@c JP
継続プロンプトは、継続の「終わり」を明示するものです。
「プロンプト」の名前の由来は、インタラクティブな環境ではREPLのプロンプトが
継続の区切りになっていることです。アクティベーションレコードを良くあるスタックモデルで
理解するなら、継続プロンプトはスタックの「底」にあたります。
@c COMMON

@c EN
Furthermore, you can have multiple kinds of continuation prompts,
so that multiple features that use continuation prompts independently
won't step on each other.
@c JP
さらに、複数種類の継続プロンプトを使うことができます。これは、
継続プロンプトを利用して実装された複数の独立した機能が、うっかり干渉し合わないように
するためのものです。
@c COMMON

@c EN
(Partial continuations can also be defined on top of continuation prompts,
and SRFI-226 indeed defines so.  We'll integrate existing partial
continuations with continuation prompts in future versions.)
@c JP
(部分継続は継続プロンプトを使って実装でき、実際、SRFI-226はそのように定義しています。
Gaucheの従来の部分継続は将来のバージョンで継続プロンプトと統合される予定です。)
@c COMMON

@defun make-continuation-prompt-tag :optional name
[SRFI-226]
@c EN
Creates and returns a new continuation prompt tag,
which is an opaque object to specify the boundary
of continuation frames.  A new boundary can be introduced
with @code{call-with-continuation-prompt}.  You can nest bounded
continuation frames with the smae continuation prompt tag.  Operations
that takes a continuation prompt tag seraches the innermost boundary
with the tag.

The optional @var{name} argument is the name of the continuation
prompt tag.  It is for display purpose only to help diagnostics.
@c JP
新たな継続プロンプトタグを作って返します。
継続プロンプトタグは、継続フレームの境界を指定するのに使うオブジェクトです。
新しい境界は@code{call-with-continuation-prompt}で導入されます。
ひとつの継続プロンプトタグを使いまわして、継続フレームの境界をネストすることもできます。
継続プロンプトタグを取る手続きは、そのタグを持つ最も内側の境界を使います。

省略可能な@var{name}は継続プロンプトタグの名前です。
これは単に、診断を容易にするために表示するためだけのものです。
@c COMMON
@end defun

@defun default-continuation-prompt-tag
[SRFI-226]
@c EN
Returns a default continuation prompt tag.
When the program starts, the initial continuation boundary
has the default continaution prompt tag.
Most procedures that takes an optional continuation prompt tag
assumes the default tag if the argument is omitted.
@c JP
デフォルト継続プロンプトタグを返します。
プログラムが開始された時、最初の継続フレームの境界はデフォルト継続プロンプトタグを持ちます。
継続プロンプトタグを省略可能引数として取る手続きはほとんど、
省略時にデフォルト継続プロンプトタグを使います。
@c COMMON
@end defun

@defun continuation-prompt-tag? obj
[SRFI-226]
@c EN
Returns @code{#t} if @var{obj} is a continuation prompt tag,
@code{#f} otherwise.
@c JP
@var{obj}が継続プロンプトタグなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun call-with-continuation-prompt thunk :optional prompt-tag abort-handler
[SRFI-226]
@c EN
Calls @var{thunk} with a continuation delimited by a continuation prompt tag
@var{prompt-tag}.  If @var{prompt-tag} is omitted, the default prompt
tag is assumed.

The @var{abort-handler} is a procedure to be called when, during executing
@var{thunk}, its continuation is aborted by
@code{abort-current-continuation}.  The objects passed to
@code{abort-current-continuation} are passed to @var{abort-handler},
which is called with the continuation of @var{call-with-continuation-prompt}
itself.  If @var{thunk} doesn't abort the continuation,
@var{abort-handler} won't be called.

When @var{abort-handler} is omitted, it installs a default abort handler,
which work in a very specific way.  First, it takes one argument, which must
be a thunk (let's call it @var{continuation-thunk} for now).
The default abort handler reinstates
the continuation with the continuation prompt tag @var{prompt-tag} and
calls the continuation thunk.  Say, it works like a trampoline to push
back the control to the same context as @var{thunk} is called.
@c JP
継続プロンプトタグ@var{prompt-tag}で区切られた継続の上で@var{thunk}を呼び出します。
@var{prompt-tag}が省略された場合はデフォルト継続プロンプトタグが使われます。

@var{abort-handler}は手続きで、@var{thunk}実行中にその継続が
@code{abort-current-continuation}によって破棄された場合に呼ばれます。
@code{abort-current-continuation}に渡されるオブジェクトが@var{abort-handler}
に引数として渡されます。
@var{abort-handler}自身は、@code{call-with-continuation-prompt}の継続の上で
実行されます。
@var{thunk}が実行中に継続を破棄しなかった場合は@var{abort-handler}は呼ばれません。

@var{abort-handler}が省略された場合はデフォルトのアボートハンドラが使われますが、
それはちょっと特殊な動作をします。まず、デフォルトアボートハンドラは
一つだけ引数を取り、それはサンクでなければなりません
(ここでは@var{continuation-thunk}と呼ぶことにします)。
デフォルトアボートハンドラは@var{prompt-tag}で区切られた継続を改めて導入し、
@var{continuation-thunk}を呼び出します。いわば、トランポリンのように、
@var{thunk}がもともと呼ばれた文脈に制御を戻すようなものです。
@c COMMON

@c EN
See the entry of @code{abort-current-continuation} below
for exmaples.
@c JP
例については下の@code{abort-current-continuation}の項を参照してください。
@c COMMON
@end defun

@defun abort-current-continuation prompt-tag obj @dots{}
[SRFI-226]
@c EN
Aborts all active procedure calls in the current continuation up to
the continuation prompt tagged with @var{prompt-tag}.  The control
goes to the abort handler installed by the most recent
@code{call-with-continuation-prompt} with the @var{prompt-tag}.
The rest of the arguments @var{obj} @dots{} are passed to the
abort handler.

When the current continuation does not have a continuation prompt
tagged with @var{prompt-tag}, a @code{<continuation-violation>} error
is thrown.
@c JP
現在の継続から、@var{prompt-tag}でタグ付けられた継続プロンプトまでの
継続を破棄して、その@var{prompt-tag}を導入した
@code{call-with-continuation-prompt}のアボートハンドラに制御を移します。
残りの引数@var{obj} @dots{}はアボートハンドラに引数として渡されます。

現在の継続の先に@var{prompt-tag}を持つ継続プロンプトが無かった場合は
@code{<continuation-violation>}エラーが投げられます。
@c COMMON

@example
(let ([tag (make-continuation-prompt-tag)])
 (call-with-continuation-prompt
   (^[] (+ 1 (abort-current-continuation tag 'foo 'bar) 2))
   tag
   list))
 @result{} (foo bar)
@end example

@c EN
If a dynamic handlers are inserted in the continuation frames
to be aborted, their `after' handlers are executed before
the abort handler is called.
@c JP
もし動的ハンドラが破棄される継続フレーム中に挿入されていたら、
その　`after' ハンドラはアボートハンドラの前に実行されます。
@c COMMON

@example
(let ((tag (make-continuation-prompt-tag)))
 (call-with-continuation-prompt
   (^[]
     (dynamic-wind
       (^[] #f)
       (^[] (abort-current-continuation tag 'foo))
       (^[] (print 'yo))))
   tag
   print))
 @result{} @r{prints @code{yo}, then prints @code{foo}}.
@end example
@end defun


@c EN
You may wonder the difference between the traditional @code{call/cc}
and the combination of @code{call-with-continuation-prompt} and
@code{abort-current-continuation}.  Actually the latter is more
lower-level construct, and @var{call/cc} is a high-level construct
implemented on top of it.
@c JP
ここまで読んできて、従来の@code{call/cc}に対して、
@code{call-with-continuation-prompt}と@code{abort-current-continuation}
の組み合わせがどう違うのかと思ったかもしれません。
実は後者はより低レベルの構造で、@code{call/cc}はその上に実装される高レベル構造なのです。
@c COMMON

@node Continuation marks, Multiple values, Continuation prompts, Procedures and continuations
@subsection Continuation marks
@c NODE 継続マーク

@c EN
Continuation marks are a set of key-value associations
attached to continuation frames.  Keys and values are arbitrary
Scheme object.  It sounds obscure, but it allows to implement
various useful language features; notably, the new @code{parameterize}
is implemented on top of continuation marks, allowing its body
to be evaluated in tail context (@pxref{Parameters}).
@c JP
継続マークは、継続フレームに付加されるキーと値の関連です。
キーと値には任意のSchemeオブジェクトが使えます。
これだけ聞いてもなんだかよく分からないかもしれませんが、
継続マークを使って色々便利な言語機能を実装することができます。
例えば、新しい@code{parameterize}は本体を末尾コンテクストで評価することが
できますが、それは継続マークを使って実装されているからです。
@c COMMON

@itemize @bullet
@item
@c EN
You can have dynamic-scoped data without compromizing tail-calls.
Using @code{dynamic-wind} requires to run the `after' thunk after
evaluating the body, so if you wrap a tail expression with it,
the original expression won't be in tail context anymore.
Continuation marks, on the other hand, will be discarded when
the continuation frame they are attached to is `popped', so you
don't need to clean up after the body is executed.  So the body
is exected in the tail context if the dynmaic-scope itself
is in tail context.
@c JP
適切な末尾呼び出し条件を犠牲にすることなしに、動的スコープを持つデータを実装できます。
@code{dynamic-wind}を使う方法だと、本体を実行したあとに `after' サンクを
実行しなければならないので、元の式が末尾位置にあったとしても、
@code{dynamic-wind}でくるむと末尾位置でなくなってしまいます。
継続マークは、それが付加された継続フレームが「ポップ」されると
一緒に捨てられるため、本体実行後に後始末コードを走らせる必要がありません。
なので元の式が末尾位置にあれば、本体を末尾位置で実行することができます。
@c COMMON
@item
@c EN
Since tail expression shares a continuation frame with its
caller, you can detect whether an expression is evaluated
at the tail position @emph{at run-time}.
@c JP
末尾式は継続フレームを呼び出し元と共有するので、
ある式が末尾位置で実行されるかどうかを@emph{実行時に}判定することができます。
@c COMMON
@end itemize

@c EN
In general, though, continuations marks are low-level tools
to construct high-level features, rather than to be
used as day-to-day tools.
@c JP
ただ、一般的には継続マークは他の高レベルな言語機能を
実装するための低レベルなツールと考えるべきでしょう。
日常的なコードで使うものではありません。
@c COMMON

@c EN
@subsubheading Marking a continuation frame
@c JP
@subsubheading 継続フレームをマークする
@c COMMON

@defspec with-continuation-mark key value expr
[SRFI-226]
@c EN
Both @var{key} and @var{value} are evaluated, and
adds the key-value association as a mark to the current continuation,
then evaluate @var{expr} with the same continuation as this form.
That is, if this form is in the tail context, @var{expr} is
evaluated in the same tail context.
@c JP
まず@var{key}と@var{value}が評価され、そのキー-値の関連が
現在の継続のマークに追加されます。
そして、@var{expr}がこのフォームの継続と同じ継続で評価されます。
つまり、このフォーム自体が末尾コンテクストにあれば、
@var{expr}も末尾コンテクストで評価されます。
@c COMMON

@c EN
If the current continuation is already marked with @var{key}, then its value
is replaced with @var{value}.
@c JP
現在の継続フレームのマークに既に@var{key}があれば、その値が@var{value}で置き換えられます。
@c COMMON
@end defspec

@defmac with-continuation-marks ((key value) @dots{}) expr
[SRFI-226]
@c EN
All @var{key}s and @var{value}s are evaluted, then
add those key-value associations as marks to the current continuation,
then evaluate @var{expr} with the same continuation as this form.
@c JP
@var{key}と@var{value}がすべて評価された後、それらキー-値ペア全てが
現在の継続のマークに追加され、同じ継続で@var{expr}が評価されます。
@c COMMON
@end defmac

@c EN
@subsubheading Extracting continuation marks
@c JP
@subsubheading 継続マークを取り出す
@c COMMON

@defun call-with-immediate-continuation-mark key proc :optional fallback
[SRFI-226]
@c EN
Tail-calls @var{proc} with the value for @var{key} associated
in the current continuation.  If the current continuation doesn't have
a value for @var{key}, @var{fallback} is passed to @var{proc} instead.
If @var{fallback} is omitted, @code{#f} is assumed.
@c JP
現在の継続のマーク中の@var{key}に対応する値を引数として、@var{proc}を末尾呼び出しします。
現在の継続のマーク中に@var{key}がなければ@var{fallback}が使われます。
@var{fallback}が省略された場合は@code{#f}が使われます。
@c COMMON

@example
(with-continuation-mark 'a 'b
  (call-with-immediate-continuation-mark 'a list))
 @result{} (b)

(with-continuation-mark 'a 'b
  (cons (call-with-immediate-continuation-mark 'a list) 1))
 @result{} ((#f) . 1)
@end example
@end defun

@defun continuation-marks cont :optional prompt-tag
[SRFI-226]
@c EN
Returns a continuation mark set object, which contains continuation
marks of the confinutaion frames between the continuation @var{cont}
and the continuation delimited by @var{prompt-tag}.  If @var{prompt-tag}
is omitted, default prompt tag is assumed.
@c JP
継続@var{cont}から@var{prompt-tag}で区切られる継続フレームまでの継続マークを
集めた、継続マークセットオブジェクトを返します。
@var{prompt-tag}が省略された場合はデフォルトプロンプトタグが使われます。
@c COMMON
@end defun

@defun current-continuation-marks :optional prompt-tag
[SRFI-226]
@c EN
Returns a continuation mark set object, which contains continuation
marks of the confinutaion frames between the current continuation
and the continuation delimited by @var{prompt-tag}.  If @var{prompt-tag}
is omitted, default prompt tag is assumed.
@c JP
現在の継続から@var{prompt-tag}で区切られる継続フレームまでの継続マークを
集めた、継続マークセットオブジェクトを返します。
@var{prompt-tag}が省略された場合はデフォルトプロンプトタグが使われます。
@c COMMON
@end defun

@c EN
@subsubheading Continuation mark set
@c JP
@subsubheading 継続マークセット
@c COMMON

@defun continuation-mark-set? obj
[SRFI-226]
@c EN
Returns @code{#t} if @var{obj} is a continuation mark set,
@code{#f} otherwise.
@c JP
@var{obj}が継続マークセットなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun continuation-mark-set->list mark-set key :optional prompt-tag
[SRFI-226]
@c EN
Pick up values associated to @var{key} from a continuation mark set
@var{mark-set}, and returns a fresh list of them.  A value in more
recent continuation frames come earlier in the list.

You can pass @code{#f} to @var{mark-set} to make the procedure
use @code{(current-continuation-marks prompt-tag)}.

It searches the mark set up to the continuation frame delimited
by a continuation prompt @var{prompt-tag}.
If @var{prompt-tag} is omitted, the default prompt tag is used.
@c JP
継続マークセット@var{mark-set}から、@var{key}を持つマークに対応する値を
全て取り出し、新しいリストにして返します。より新しい継続フレームに対応する値ほど
リストの先頭の方に置かれます。

@var{mark-set}に@code{#f}を渡すこともできます。その場合、
@code{(current-continuation-marks prompt-tag)}が使われます。

@var{key}は、継続マークセット中の、@var{prompt-tag}で指定される継続プロンプト
に対応する継続マークまで探されます。@var{prompt-tag}が省略された場合は
デフォルトプロンプトタグが使われます。
@c COMMON
@end defun

@defun continuation-mark-set-first mark-set key :optional fallback prompt-tag
[SRFI-226]
@c EN
Returns the most recent value associated with @var{key} in the
continuation mark set @var{mark-set}.  If there's a mark with @var{key} exists,
it matches @code{(car (continuation-mark-set->list key prompt-tag)}.

If there's no mark with @var{key} in the mark set, @var{fallback}
is returned.  If @var{fallback} is omitted, @code{#f} is assumed.

If @var{prompt-tag} is omitted, the default prompt tag is used.
@c JP
継続マークセット@var{mark-set}のうち、@var{key}に結びつけられた最も新しい値を
返します。もし@var{key}がマークセットの中にあるなら、
値は@code{(car (continuation-mark-set->list key prompt-tag)}と同じになります。

@var{key}がマークセット中に無い場合は@var{fallback}が返ります。
@var{fallback}が省略された場合は@code{#f}になります。

@var{prompt-tag}が省略された場合はデフォルトプロンプトタグが使われます。
@c COMMON
@end defun

@c EN
@subsubheading Continuation mark key
@c JP
@subsubheading 継続マークキー
@c COMMON

@c EN
You can use arbitrary Scheme object as keys for continuation marks,
but you if you're writing libraries, you want to make sure that
your keys won't conflict with the keys used by other parts of the code.

A continuation mark key is an opaque object that is guaranteed to
be different (in terms of @code{equal?}) to other continuation mark keys.
@c JP
継続マークのキーには任意のSchemeオブジェクトを使えますが、
例えばライブラリを書いている場合、使っているキーが偶然他で使われているキーと
かぶってしまうのは望ましくありません。

継続マークキーは、他の継続マークキーと(@code{equal?}で)等しくならないことが
保証されているオブジェクトです。
@c COMMON

@defun make-continuation-mark-key :optional name
[SRFI-226]
@c EN
Returns a newly created continuation key, which is guaranteed never
to be equal to any prior or future continuation mark keys.

The optional @var{name} argument is for debugging purpose.
@c JP
これ以前の継続マークキーとも、以降のマークキーとも決して重ならない
新たな継続マークキーを作って返します。

@var{name}引数はデバッグ用です。
@c COMMON

@c EN
Note that SRFI-226 does not require a continuation mark key has disjoint
types from other Scheme types.  Currently, Gauche uses an uninterned
symbol as a continuation mark key.  It may be changed in future,
so do not count on it.
@c JP
SRFI-226は継続マークキーが他のSchemeオブジェクトと異なる型であることを
要請していないことに注意してください。今のところ、Gaucheではインターンされていない
シンボルを継続マークキーとして返しています。これは将来変わるかもしれないので、
それに依存したコードは書かないようにしてください。
@c COMMON
@end defun

@defun continuation-mark-key? obj
[SRFI-226]
@c EN
Returns @code{#t} if @var{obj} can be an object returned by
@code{make-continuation-mark-key}, @code{#f} otherwise.

Note that SRFI-226 does not require a continuation mark key has a disjoint
type, so this may return @code{#t} for an object that's not
created by @code{make-continuation-mark-key}.
In fact, Gauche currently uses an uninterned symbol for a continuation
mark key, and this procedure returns @code{#t} for any symbols.
@c JP
@var{obj}が@code{make-continuation-mark-key}が返したオブジェクトである可能性が
あれば@code{#t}を、そうでなければ@code{#f}を返します。

SRFI-226は継続マークキーが独自の型を持つことを要請していないので、この手続きは
@var{obj}が@code{make-continuation-mark-key}で作られたものでなくても@code{#t}を
返し得ることに注意してください。
実際、Gaucheは今のところインターンされていないシンボルを継続マークキーとして
返しているので、この手続きはシンボルに対して@code{#t}を返します。
@c COMMON
@end defun

@node Multiple values, Folding generated values, Continuation marks, Procedures and continuations
@subsection Multiple values
@c NODE 多値

@defun values obj @dots{}
[R7RS base]
@c EN
Returns @var{obj} @dots{} as multiple values.
Caller can capture multiple values by a built-in syntax
@code{receive} or @code{let-values}
(@ref{Binding constructs}), or the R7RS procedure
@code{call-with-values} described below.
@c JP
@var{obj} @dots{} を多値として返します。
呼び出し側は、組み込み構文の @code{receive}や@code{let-values}
(@ref{Binding constructs}参照)か、
下に説明するR7RSの手続き@code{call-with-values}を使って多値を受け取ることが
できます。
@c COMMON
@example
(values 1 2) @result{} 1 @r{and} 2
@end example
@end defun

@defun call-with-values producer consumer
[R7RS base]
@c EN
Call a procedure @var{producer} with no argument.
Then applies a procedure @var{consumer} on the
value(s) @var{producer} returned.  Returns the value(s) @var{consumer}
returns.
@c JP
手続き@var{producer}を引数無しで呼びます。そして、それが返した値
を引数として@var{consumer}を呼びます。@var{consumer}が返す値を
返します。
@c COMMON
@example
(call-with-values (lambda () (values 1 2)) cons)
  @result{} (1 . 2)
@end example
@end defun

@defmac values-ref mv-expr k
@c EN
Returns @var{k}-th value of what @var{mv-expr} returns.
Conceptually, it is the same as the following code.
@c JP
@var{mv-expr}が返す多値の@var{k}-番目の値を返します。概念としては、
以下のコードと同じです。
@c COMMON
@example
(call-with-values (lambda () mv-expr) (lambda r (list-ref r k)))
@end example
@c EN
This macro uses shortcuts for the typical cases like @var{k} is zero.

Similar to Common Lisp's @code{nth-value}, but the argument order
is flipped to match other Scheme's @code{*-ref} procedures.
@c JP
このマクロは k がゼロであるような典型的な場合にはより単純な形へと
展開されます。

Common Lisp の @code{nth-value} に似ていますが、引数の順が逆になっています。
Scheme の他の@code{*-ref} 手続きと合わせるためです。
@c COMMON

@c EN
SRFI-210's @code{value/mv} is an enhancement of @code{values-ref}
(@pxref{Procedures and syntax for multiple values}).
@c JP
SRFI-210の@code{value/mv}は@code{values-ref}の拡張になっています
(@ref{Procedures and syntax for multiple values}参照)。
@c COMMON

@example
(values-ref mv-expr k) @equiv{} (value/mv k mv-expr)
@end example
@end defmac

@defmac values->list mv-expr
@c EN
Evaluates @var{mv-expr}, puts all the results into a list
and returns it.   It is called @code{multiple-value-list} in
Common Lisp.
@c JP
@var{mv-expr}を評価し、結果の値をリストにして返します。Common Lispで
@code{multiple-value-list}と呼ばれているものです。
@c COMMON

@example
(values->list (div-and-mod 10 3)) @result{} (3 1)

(values->list 1) @result{} (1)
@end example

@c EN
SRFI-210's @code{list/mv} is an enhancement of @code{values->list}
(@pxref{Procedures and syntax for multiple values}).
@c JP
SRFI-210の@code{list/mv}は@code{values->list}の拡張になっています
(@ref{Procedures and syntax for multiple values}参照)。
@c COMMON

@example
(values->list mv-expr) @equiv{} (list/mv mv-expr)
@end example
@end defmac

@node Folding generated values,  , Multiple values, Procedures and continuations
@subsection Folding generated values
@c NODE 生成された値の畳み込み

@c EN
Sometimes a procedure is used as a @emph{generator} of a series
of values, by yielding one value at a time.  Customary an EOF
object is used to mark the end of the series.  For example,
@code{read-char} is such a procedure that yields a series
of characters, terminated by EOF.
@c JP
一回呼ばれる度にひとつの値を生成するような手続きは、
一連の値を生成する@emph{ジェネレータ}として使われることがあります。
値の終端を表すマークとしては、慣例としてEOFが使われます。
例えば@code{read-char}はそうした、一連の文字を生成し、終端としてEOFを返す手続きです。
@c COMMON

@c EN
Since it is such a handy abstraction, Gauche provides a
set of utilities (see @ref{Generators}) to construct and generators
out of various sources, including other generators.
@c JP
こうした抽象化は手軽であるため、Gaucheは、他のジェネレータを含むさまざまなソースから
ジェネレータを構築するユーティリティをひとそろい提供しています。
@c COMMON

@c EN
The generated values needs to be consumed eventually.  Here we
provide several procedures to do that.  These are useful
when combined with input procedures like @code{read}, so we
have them built-in instead of putting them in a separate module.
@c JP
生成された値は最終的に消費されなければなりません。そのための手続きもいくつか
提供されています。こうした手続きは、@code{read}のような入力手続きと組み合わせるのに
有用です。このため、別のモジュールに分割するのではなく、組み込み手続きになっています。
@c COMMON

@defun generator-fold proc seed gen gen2 @dots{}
[R7RS generator]
@c EN
Works like @code{fold} on the generated values by generator
procedures @var{gen} @var{gen2} @dots{} (@xref{Walking over lists},
for the details of @code{fold}).
@c JP
ジェネレータである手続き @var{gen} @var{gen2} @dots{} が生成する値に対して
 @code{fold} のように働きます(@code{fold}の詳細は@ref{Walking over lists}参照)。
@c COMMON

@c EN
When one generator is given, for each value @var{v} generated by @var{gen},
@var{proc} is called as @code{(@var{proc} @var{v} @var{r})}, where
@var{r} is the current accumulated result; the initial value of the
accumulated result is @var{seed},
and the return value from @var{proc} becomes the next accumulated result.
When @var{gen} returns EOF, the accumulated result at that time is returned
from @code{generator-fold}.
@c JP
引数としてジェネレータがひとつ与えられると、その @var{gen} が生成する各値 @var{v} に
対して、@var{proc} が @code{(@var{proc} @var{v} @var{r})} のように呼び出されます。
@var{r}は現在の積算結果であり、その初期値は @var{seed} です。そして、@var{proc} が
返す値が次回の @var{proc} 呼び出し時の積算値として渡されることになります。
@var{gen}がEOFを返すと、その時点の積算値が @code{generator-fold} から値として
返されます。
@c COMMON

@c EN
When more than one generator is given, @var{proc} is
called as @code{(@var{proc} @var{v1} @var{v2} @dots{} @var{r})},
where @var{v1}, @var{v2} @dots{} are the values yielded from
@var{gen}, @var{gen2}, @dots{}, respectively, and @var{r} is
the current accumulated result.  The iteration terminates when
any one of the generators returns EOF.
@c JP
2つ以上のジェネレータが渡された場合は、@var{proc}は
@code{(@var{proc} @var{v1} @var{v2} @dots{} @var{r})} のように呼び出されます。
@var{v1}, @var{v2} @dots{} はそれぞれ @var{gen}, @var{gen2}, @dots{} が生成
した値であり、@var{r}は現在の積算値です。ジェネレータのどれかひとつ以上がEOFを返すと、
イテレーションは終了します。
@c COMMON

@example
(with-input-from-string "a b c d e"
  (cut generator-fold cons 'z read))
  @result{} (e d c b a . z)
@end example
@end defun

@defun generator-fold-right proc seed gen gen2 @dots{}
@c EN
Works like @code{fold-right} on the generated values by generator
procedures @var{gen} @var{gen2} @dots{} (@pxref{Walking over lists},
for the details of @code{fold-right}).
@c JP
ジェネレータである手続き@var{gen} @var{gen2} @dots{}が生成する値に対して
@code{fold-right}のように働きます(@code{fold-right}の詳細は@ref{Walking over lists}参照)。
@c COMMON

@c EN
This is provided for completeness, but it isn't a good way to
handle generators; in order to combine values right-associatively,
we should read all the values from the generators (until any one
of the generator returns EOF), then start
calling @var{proc} as
@c JP
この手続きは完全性のために提供されていますが、ジェネレータとの相性はあまり良くありません。
値を右結合で計算していくためには、ジェネレータから(少なくともどれかひとつのジェネレータがEOFを返すまで)
全ての値を読み取らなければなりません。そうして初めて @var{proc} の呼び出しが始まることになります。
@c COMMON
@example
(proc v0_0 v1_0 ... (proc v0_1 v1_1 ... (proc v0_n v1_n ... seed) ...))
@end example
@c EN
where @var{vn_m} is the @var{m}-th value yielded by @var{n}-th generator.
@c JP
@var{vn_m}は、@var{n}番目のジェネレータが@var{m}回目の呼び出しで返した値です。
@c COMMON

@example
(with-input-from-string "a b c d e"
  (cut generator-fold-right cons 'z read))
  @result{} (a b c d e . z)
@end example

@c EN
As you see, keeping all intermediate values kind of defeats the
benefit of generators.
@c JP
ごらんのように、全ての中間値を保持することで、ジェネレータの利点が
ある意味帳消しになってしまうのです。
@c COMMON
@end defun

@defun generator-for-each proc gen gen2 @dots{}
[R7RS generator]
@c EN
A generator version of @code{for-each}.  Repeatedly applies @var{proc} on
the values yielded by @var{gen}, @var{gen2} @dots{} until any one of
the generators yields EOF.  The values returned from @var{proc} are discarded.
@c JP
ジェネレータ版の@code{for-each}です。@var{gen}, @var{gen2} @dots{} が生成する
値に対して、ジェネレータのどれかがEOFを返すまで @var{proc} を繰り返し適用していきます。
@var{proc}が返す値は無視されます。
@c COMMON

@c EN
This is a handy procedure to consume generated values with side effects.
@c JP
これは、生成される値を副作用で消費するのに便利です。
@c COMMON
@end defun

@defun generator-map proc gen gen2 @dots{}
@c EN
A generator version of @code{map}.  Repeatedly applies @var{proc} on
the values yielded by @var{gen}, @var{gen2} @dots{} until any one of
the generators yields EOF.   The values returned from @var{proc}
are collected into a list and returned.
@c JP
ジェネレータ版の@code{map}です。@var{gen}, @var{gen2} @dots{} が生成する
値に対して、ジェネレータのどれかがEOFを返すまで @var{proc} を繰り返し適用していきます。
@var{proc}が返す値をひとつのリストに束ねて返します。
@c COMMON

@example
(with-input-from-string "a b c d e"
  (cut generator-map symbol->string read))
  @result{} ("a" "b" "c" "d" "e")
@end example

@c EN
The same effects can be achieved by combining @code{generator->list}
and @code{gmap} (@pxref{Generator operations}).  This procedure
is provided for the backward compatibility.
@c JP
@code{generator->list}と@code{gmap}(@ref{Generator operations}参照)の組み合わせと
同じ挙動を実現します。この手続きは後方互換性のために提供されています。
@c COMMON

@example
(generator->list (gmap proc gen gen2 @dots{}))
@end example
@end defun

@defun generator-find pred gen
[R7RS generator]
@c EN
Returns the first item from the generator @var{gen} that satisfies
the predicate @var{pred}.
@c JP
ジェネレータ@var{gen}から返された中から、述語@var{pred}を満たす最初の要素を返します。
@c COMMON

@c EN
The following example returns the first line matching the regexp
@code{#/XYZ/} from the file @file{foo.txt}.
@c JP
以下の例は、ファイル@file{foo.txt}の中から正規表現@code{#/XYZ/}にマッチする最初の行を返します。
@c COMMON

@example
(with-input-from-file "foo.txt"
  (cut generator-find #/XYZ/ read-line))
@end example

@c EN
Note: If you want to pick all the lines matching the regexp,
like the @code{grep} command,
you can use @code{gfilter} and @code{generator->list}.
@c JP
註: @code{grep}コマンドのように、正規表現にマッチする全ての行を取り出したいなら、
@code{gfilter}と@code{generator->list}が使えます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Parameters and dynamic states, Boxes, Procedures and continuations, Core library
@section Parameters and dynamic states
@c NODE パラメータと動的状態

@c EN
A @emph{parameter} is Scheme's way to implement dynamically scoped variables.
It is codified in SRFI-39 and incorporated into R7RS.
@c JP
「パラメータ」はSchemeで動的スコープを持つ変数を実現します。
もともとSRFI-39で仕様が定められ、R7RSからは言語の一部になりました。
@c COMMON

@c EN
@b{Note:} Starting from 0.9.13, we're adopting SRFI-226 semantics
of parameters, which behaves slightly different from our legacy parameters.
@xref{Transition to SRFI-226 parameters}, for the details.
@c JP
@b{註:} 0.9.13より、パラメータのセマンティクスを従来のものからSRFI-226で定義される
ものに切り替えつつあります。両者は微妙に振る舞いが異なります。
詳しくは@ref{Transition to SRFI-226 parameters}で説明しています。
@c COMMON

@c EN
It is a special procedure created by @code{make-parameter}.  It accepts
zero or one argument.  When called without an argument, it returns the
value in the current dynamic environment.
If an argument is passed, it alters its value
with the given value in the current dynamic environment,
and returns the previous value.
@c JP
パラメータは@code{make-parameter}で作られる特殊な手続きで、
ゼロ個または1個の引数を取ります。引数無しで呼ばれた場合は現在の動的環境での値を返し、
引数つきで呼び出された場合はその引数を現在の動的環境での値にセットして
以前の値を返します。
@c COMMON

@c EN
Using @code{parameterize} macro, which is similar to @code{let} syntactially,
rebinds the parameters' value during execution of its body, dynamically
rather than lexically.
@c JP
@code{parameterize}マクロは@code{let}に構文的に似ていて、
本体の実行の間、パラメータの値を一時的に置き換えます。
これは字句的(静的スコープ)ではなく動的スコープで動作します。
@c COMMON

@example
(define var (make-parameter 0))

(define (show-var) (print (var)))

(show-var)  ; prints 0

(parameterize ((var 1))
  (show-var))    ; prints 1


(define f)

(parameterize ((var 2))
  (set! f (lambda () (show-var))))

(f) ; prints 0, since its out of the dynamic extent of var=2
@end example

@c EN
A parameter's value can be mutated by calling the parameter with
the new value:
@c JP
パラメータの値はまた、新たな値を引数としてパラメータを呼ぶことで変更することができます。
@c COMMON

@example
(define var (make-parameter 0))

(var) ; @result{} 0

(var 1)

(var) ; @result{} 1

;; Gauche extension: you can use set! too
(set! (var) 2)

(var) ; @result{} 2
@end example

@c EN
Originally, parameters in Scheme were simply a hack with an ordinary procedure
and @code{dynamic-wind} to emulate dynamically scoped variables.
The same mechanism have been used to manage dynamically scoped states, too.

As the experience accumulated, however, it is learned that it's better
to treat dynamically scoped variables and dynamically scoped states
differently; efficient implementations differ, and they have slightly
different semantics with delimited continuations.  SRFI-226 incorporated
this distinction.

As of Gauche 0.9.13, we adopt this distinction, too.
@xref{Difference of parameters and dynamic states}, for the details.
@c JP
元々、Schemeのパラメータは通常の手続きと@code{dynamic-wind}を使って
動的束縛の変数をエミュレートするハックでした。
同じメカニズムはまた、動的な状態の管理にも使うことができました。

しかし使い込まれてゆくうちに、動的変数と動的状態は別に扱った方が良いという
知見が得られてきました。効率の良い実装が異なるのと、
限定継続があると振る舞いに差があるためです。
SRFI-226でこの違いが明確化されました。

Gaucheも0.9.13からこの区別を採り入れています。
詳しくは@ref{Difference of parameters and dynamic states}を参照してください。
@c COMMON

@c EN
If you're a long time Gauche user (thanks!), remember to check
out the changes on 0.9.13 and how to transition to it
(@pxref{Transition to SRFI-226 parameters}).
@c JP
これまで長くGaucheを使っていた方は、一度0.9.13での変更点と
移行方法をチェックしておいてください
(@ref{Transition to SRFI-226 parameters}参照)。
@c COMMON

@menu
* Parameters::
* Dynamic states::
* Difference of parameters and dynamic states::
* Transition to SRFI-226 parameters::
@end menu

@node Parameters, Dynamic states, Parameters and dynamic states, Parameters and dynamic states
@subsection Parameters
@c NODE パラメータ

@c EN
Because of historical reasons,
parameters come with three flavors; their differences are subtle,
and only visible when you use @emph{mutation} in @emph{multi-thread code}.
If you only use parameters for dynamic binding (i.e. within R7RS spec),
all flavors of parameters behave the same.
@c JP
歴史的事情から、パラメータには、少しだけ振る舞いが違う3つの種類があります。
但し、その違いはマルチスレッドコードで破壊的変更をしない限りは見えません。
R7RSの範囲、すなわちパラメータを動的束縛にだけ使っている場合は、
どのパラメータも同じように振る舞います。
@c COMMON

@c EN
The three flavors are @emph{shared parameters}, @emph{thread parametres},
and @emph{legacy parameters}.  The first two is defined in SRFI-226
(though it doesn't use the term ``shared'', for the ordinary parameters
are shared parameters).  The third one is compatible to the parameters
in Gauche 0.9.12 and before.

The following table shows whether a mutation in one thread is visible from
another thread:

@multitable {Toplevel mutation visible?===} {AAAAAA===} {AAAAAA===} {AAAAAA===}
@headitem @tab Share @tab Thread @tab Legacy
@item Toplevel mutation visible? @tab yes @tab no @tab no
@item Dynamic mutation visible? @tab yes @tab no @tab yes
@end multitable

Here, ``toplevel mutation'' is a mutation done for a parameter
outside of any @code{parameterize} form, and ``dynamic mutation''
is a mutation done for a parameter in a dynamic scope of
@code{parameterize} form:

@example
(define p (make-parameter 0))

(p 1) ; toplevel mutation

(parameteize ((p 2))
  (p 3)  ; dynamic mutaiton
  )

(p 4) ; toplevel mutation
@end example

For the shared and legacy parameters, dynamic mutation is only visible
for the thread that shares the same dynamic binding.
@c JP
その3つの種類は、@emph{共有パラメータ}、@emph{スレッドパラメータ}、
そして@emph{レガシーパラメータ}です。
最初のふたつはSRFI-226で定義されます。
(SRFI-226では「共有パラメータ」とは呼んでいませんが、@code{make-parmaeter}で
作られる通常のパラメータが共有パラメータになります)。
最後のものはGauche 0.9.12以前と互換なパラメータです。

次の表に、パラメータの破壊的変更が他のスレッドから見えるかどうかをまとめます。

@multitable {トップレベルの変更が見えるか?===} {AAAAAA===} {AAAAAA===} {AAAAAA===}
@headitem  @tab 共有 @tab スレッド @tab レガシー
@item トップレベルの変更が見えるか? @tab yes @tab no @tab no
@item 動的範囲での変更が見えるか?  @tab yes @tab no @tab yes
@end multitable

ここで「トップレベルの変更」とは@code{parameterize}がされていない動的環境での
変更、「動的範囲での変更」とは@code{parameterize}が有効な動的環境での変更です。

@example
(define p (make-parameter 0))

(p 1) ; トップレベルの変更

(parameteize ((p 2))
  (p 3)  ; 動的範囲での変更
  )

(p 4) ; トップレベルの変更
@end example

共有パラメータとレガシーパラメータについては、
動的範囲での変更が見えるのは、同じ動的環境を共有しているスレッド間のみです。
@c COMMON

@defun make-parameter value :optional converter
@defunx make-shared-parameter value :optional converter
@defunx make-thread-parameter value :optional converter
@defunx make-legacy-parameter value :optional converter
[R7RS base][SRFI-226]
@c EN
Creates a parameter whose initial value is @var{value}.
If an optional argument @var{converter} is given, it must be
a procedure that takes one argument and returns one value;
whenever the parameter's value is about to change, the procedure
is called with the given value, and the value the procedure
returns will be the parameter's value.  The converter procedure
can raise an error or reject to change the parameter's value.
@c JP
初期値が@var{value}であるパラメータを作成します。
もし省略可能な引数@var{converter}が与えられた場合、
それは一つの引数を取る手続きでなければなりません。
パラメータの値が変更されようとした時、@var{converter}は与えられた値を
引数として呼ばれ、@var{converter}が返した値がパラメータの新しい値と
なります。@var{converter}はエラーを報告したりパラメータの値を変えずに置くことも
可能です。
@c COMMON

@c EN
As described above (@pxref{Parameters}), parameters have three
flavors; @code{make-shared-parameter}, @code{make-thread-parameter},
and @code{make-legacy-parameter} creates shared, thread, and legacy
parameters, respectively.
@c JP
上で説明したように(@ref{Parameters}参照)、パラメータには3種類あります。
@code{make-shared-parameter}、@code{make-thread-parameter}、
@code{make-legacy-parameter}はそれぞれ
共有パラメータ、スレッドパラメータ、レガシーパラメータを作ります。
@c COMMON

@c EN
For the compatibility, @code{make-parameter} behaves differently
depending on which module you uses.

@itemize @bullet
@item
The @code{make-parameter} in @code{gauche} module works as
@code{make-legacy-parameter} in 0.9.13, but it will be switched
to @code{make-shared-parameter} in future versions.  To keep
the legacy code working, you should either use @code{gauche.parameter}
module, or replace @code{make-parameter} for @code{make-legacy-parameter}.
@item
If you use @code{gauche.parameter}, @code{make-parameter}
works as @code{make-legacy-parameter}.  This won't change, since
@code{gauche.parameter} is kept for the backward compatibility.
@item
If you use @code{srfi.226}, @code{make-parameter} is as SRFI-226
defines, that is, @code{make-shared-parameter}.
@end itemize
@c JP
互換性のため、@code{make-parameter}はどのモジュールをuseするかで
動作が変わります。

@itemize @bullet
@item
@code{gauche}モジュールの@code{make-parameter}は、0.9.13では
互換性のために@code{make-legacy-parameter}と同じ動作ですが、
将来は@code{make-shared-parameter}に切り替わります。
以前のコードを使いつづけるには、@code{gauche.parameter}モジュールをuseするか、
@code{make-parameter}を@code{make-legacy-parameter}に置き換えてください。
@item
@code{gauche.parameter}モジュールをuseすると、
@code{make-parameter}は@code{make-legacy-parameter}と同じ動作になります。
これは今後も変わりません。@code{gauche.parameter}は互換性のためのモジュールとなります。
@item
@code{srfi.226}をuseした場合、@code{make-parameter}はSRFI-226で
定義されているとおり、すなわち@code{make-shared-parameter}の動作となります。
@end itemize
@c COMMON

@c EN
NB: R7RS defines @code{make-parameter}.  SRFI-226 defines
@code{make-parameter} and @code{make-thread-parameter}.
The other two names, @code{make-shared-parameter} and
@code{make-legacy-parameter}, are Gauche specific.
@c JP
註: R7RSは@code{make-parameter}を、
SRFI-226は@code{make-parameter}と@code{make-thread-parameter}を
定義しています。
他のふたつ、@code{make-shared-parameter}と
@code{make-legacy-parameter}はGauche独自の名前です。
@c COMMON

@c EN
NB: In 0.9.9 and before, this procedure returns a parameter
object, and we used @code{object-apply} method to make it behave
like a procedure.  However, R7RS explicitly defines the return
values to be a procedure; notably, portable code expects
@code{(procedure? (make-parameter 'z))} returns @code{#t}.
As of 0.9.10, we switched @code{make-parameter} to return
a procedure.  It won't change the external behavior, except
when you test the parameter @var{p} with
@code{(is-a? p <parameter>)}; you have to use @code{parameter?} instead.
@c JP
註: 0.9.9までは、この手続きはパラメータオブジェクトを返していました。
パラメータオブジェクトは @code{object-apply}メソッドによって手続きであるかのように
振る舞います。しかし、R7RSは@code{make-parameter}が手続きを返すように
規定しており、ポータブルなコードでは
@code{(procedure? (make-parameter 'z))}は@code{#t}でなければなりません。
0.9.10から、@code{make-parameter}は手続きを返すようになりました。
通常のパラメータの使い方をしている限り、外部に見える振る舞いは変わりません。
ただし、@code{make-parameter}で作られたオブジェクトかどうかを
@code{(is-a? p <parameter>)}でテストしているコードは
後述する@code{parameter?}を使うように変更する必要があります。
@c COMMON
@end defun

@defmac parameterize ((param value) @dots{}) body @dots{}
[R7RS base][SRFI-226]
@c EN
Evaluates @var{body} @dots{}, with
change parameter @var{param}'s value to the given @var{value} within
the dynamic scope of @var{body} @dots{}.
Returns the value(s) of the result of the last @var{body}.
@c JP
@var{body} @dots{}を評価します。
但し、@var{body} @dots{} の実行中のみ、パラメータ@var{param}の値を
@var{value}に変更します。最後の@var{body}の返した値を返します。
@c COMMON

@c EN
If @code{parameterize} form is at a tail position and all @var{param}s
are parameter objects , @var{body} is
also evaluated at a tail position.  (This is required by SRFI-226,
though not required by R7RS).
@c JP
@code{parameterize}フォームが末尾位置にあり、
全ての@var{param}がパラメータに評価された場合、
@var{body}は末尾位置で評価されます。
(これはR7RSでは要請されていませんが、SRFI-226で要請されます)。
@c COMMON

@c EN
Note that R7RS and SRFI-226 requires @var{param} to be evaluated
to a parameter.  Gauche's @code{parameterize} has been acceping
dynamic states as well, but such usage is
deprecated; you should use @code{temporarily} instead (@pxref{Dynamic states}).
To ease transition, Gauche 0.9.13 checks if every @var{param} yields a
parameter, at runtime, and if not, it switches to the legacy implementation
which does @emph{not} evaluate @var{body} at a tail position.
In future we remove this compatibility feature.  If you want to
check your code is compatible to the new spec, add @code{(use srfi.226)}
to your code.
@c JP
R7RSとSRFI-226は@var{param}がパラメータへと評価されることを要求しています。
Gaucheは伝統的に、@var{param}に動的状態も許してきましたが、
そのような使い方は非推奨となりました。動的状態の切り替えには@code{temporarily}を
使うようにしてください (@ref{Dynamic states}参照)。
経過措置として、
Gauche 0.9.13では実行時に全ての@var{param}がパラメータに評価されたかどうかを
チェックし、パラメータ以外のものが混じっている場合は旧式の実装へと切り替えます
(その場合、@var{body}は末尾位置では評価されません)。
将来のバージョンではこの措置は無くなります。現在のコードが将来に渡って使えるかどうか
確かめるにはコードに@code{(use srfi.226)}を加えてみてください。
@c COMMON

@c EN
Some examples:
@c JP
例：
@c COMMON
@example
(define a (make-parameter 1))
(a) @result{} 1
(a 2) @result{} 1
(a) @result{} 2
(parameterize ((a 3))
  (a)) @result{} 3
(a) @result{} 2
@end example
@end defmac

@defun parameter? obj
[SRFI-226]
@c EN
Returns @code{#t} iff @var{obj} is an object created by
@code{make-parameter}.
@c JP
@var{obj}が@code{make-parameter}で作られたものであった場合は@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun current-parameterization
[SRFI-226]
@c EN
Returns a @emph{parameterization} object that reifies
the current dynamic bindings of parameters.  It can be
passed to @code{call-with-parameterization} to carry over
the parameterization.
@c JP
現在のパラメータの動的束縛の状態を具体化した@emph{パラメタライゼーション}オブジェクト
を返します。@emph{パラメタライゼーション}は@code{call-with-parameterization}に
渡すことで別の継続へと受け渡すことができます。
@c COMMON
@end defun

@defun parameterization? obj
[SRFI-226]
@c EN
Returns @code{#t} if @var{obj} is a parameterization,
@code{#f} otherwise.
@c JP
@var{obj}がパラメタライゼーションなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun call-with-parameterization parameterization thunk
[SRFI-226]
@c EN
Invoke @var{thunk} with a continuation same as
the call of @code{call-with-parameterization} except its
parameterization is swapped with @var{parameterization}.
That is, if the call to this form is in a tail context,
the call to @var{thunk} is also a tail context.
@c JP
@code{call-with-parameterization}の呼び出しの継続から
パラメタライゼーションだけ@var{parameterization}と置き換えた継続のもとで
@var{thunk}を呼び出します。
すなわち、この手続きが末尾コンテクストで呼ばれたなら、
@var{thunk}の呼び出しも末尾コンテクストになります。
@c COMMON

@example
@end example
@end defun


@defmac parameterize/dynwind ((param value) @dots{}) body @dots{}
@c EN
This handles the parameter bindings using @code{dynamic-wind}.
It is fully compatible with pre-0.9.13 @code{parameterize}.
This form is mainly provided to make legacy code work.
@c JP
これは@code{dynamic-wind}を使ってパラメータ束縛を管理するフォームです。
0.9.13より前の@code{parameterize}と全く同じ動作をします。
このフォームは主に、レガシーコードを動かすために提供されています。
@c COMMON

@c EN
This differs from the current @code{parameterize} in the following points:
@c JP
これは現在の@var{parameterize}と、次の点が異なります。
@c COMMON

@itemize @bullet
@item
@c EN
You can use non-parameter procedure (a procedure which isn't
created by @code{make-parameter}) as @var{param}, as long as it
follows the parameter protocol.  Note that if you want to use
such 'parameter-like' procedures to manage dynamic states,
you should use @code{temporarily} below (@pxref{Dynamic states}).
@c JP
パラメータと同じプロトコルに従う限り、@code{make-parameter}で作られたのではない
手続きを@var{param}に渡すことができます。
新しいコードでそのような「パラメータっぽい」手続きを動的状態の管理に使いたい場合は、
下の@code{temporarily}を使ってください (@ref{Dynamic states}参照)。
@c COMMON

@item
@c EN
The last expression of @var{body} is @emph{not} evaluated in the
tail context, even this form itself is in the tail context.
@c JP
このフォーム自体が末尾位置にあっても、@var{body}の最後の式は
末尾コンテクストでは評価されません。
@c COMMON

@item
@c EN
This can handle the 'observer' feature of the legacy
parameters introduced by @code{gauche.parameter}.  Our experience
shows the feature has been hardly used, and is incompatible with SRFI-226
semantics, so we deprecated it.
@c JP
@code{gauche.parameter}モジュールで有効になる、
レガシーなパラメータの 'observer' 機能は、このフォームを使わないと実現できません。
ただ、我々ののこれまでの経験ではこの機能はほとんど使われておらず、
SRFI-226とも非互換なので、今後は非推奨としました。
@c COMMON
@end itemize

@c EN
Note: If you use @code{gauche.parameter} module, it shadows built-in
@code{parameterize} with its own @code{parameterize}, the latter of which
is an alias of @code{parameterize/dynwind}, so that the compatibility
is kept.  New code should not use @code{gauche.parameter} module.
@xref{Parameters (legacy)}.
@c JP
註：@code{gauche.parameter}モジュールをuseすると、組み込みの@code{parameterize}
の束縛はモジュール独自の@code{parameterize}でシャドウされ、それは
@code{parameterize/dynwind}の別名となります。これはコードの互換性を保つためです。
新しいコードでは@code{gauche.parmaeter}をuseすべきではありません。
詳しくは@ref{Parameters (legacy)}参照。
@c COMMON
@end defmac


@node Dynamic states, Difference of parameters and dynamic states, Parameters, Parameters and dynamic states
@subsection Dynamic states
@c NODE 動的状態

@c EN
A dynamic state is a state associated to a certain dynamic extent
of the code execution. (In SRFI-226, it is called ``parameter-like objects'').

It can be managed with a procedure that
follows this protocol:
@c JP
動的状態とは、特定の動的エクステントに結びつけられた状態です。
(SRFI-226では「パラメータのようなオブジェクト(parameter-like object)」と
呼ばれています)。

動的状態は次のプロトコルを持つ手続きにより実現されます:
@c COMMON

@itemize @bullet
@item
@c EN
The procedure can be called with zero or one argument.
@c JP
手続きは0個または1個の引数を取る
@c COMMON
@item
@c EN
If it is called without arguments, it returns the current state.
@c JP
引数なしで呼ばれた場合、現在の値を返す
@c COMMON
@item
@c EN
If it is called with one argument, the state is set to the argument.
(The return value is ignored).
@c JP
1引数で呼ばれた場合、引数を状態の新たな値とする。
(戻り値は無視される)
@c COMMON
@end itemize

@c EN
You can use @code{temporarily} macro in place of @code{parameterize} to
change the state dynamically.
@c JP
@code{parameterize}のかわりに@code{temporarily}マクロを使って
状態を動的に変えることができます。
@c COMMON

@example
(define state
  (let val 0
    (case-lambda
      [() val]
      [(newval) (set! val newval)])))

(define (get-state) (state))

(get-state) @result{} 0

(temporarily ([state 1])
  (get-state)) @result{} 1
@end example

@c EN
If you just manage a value, it is not much different from a parameter
(without a converter) and @code{parameterize}.
However, unlike @code{parameterize}, it is guaranteed that state is
reset by calling the dynamic state with the previous value,
when the control goes out of the dynamic scope.
You can do
more than just changing the internal values inside the procedure,
such as switching state of external resource.
@c JP
値を変えるだけなら、これは(converterなしの)パラメータと@code{parameterize}を
使うのと大して変わらないように見えるでしょう。
けれど、@code{parameterize}と違って、@code{temporarily}の動的環境から
出たり再入したりした場合に、手続きが1引数で呼ばれることが保証されています。
従って、その時に外部リソースの状態も一緒に変えるなど、
値を保存する以外のアクションを取ることができます。
@c COMMON

@defmac temporarily ((proc value) @dots{}) body @dots{}
[SRFI-226]
@c EN
Evaluates @var{proc}s and @var{value}s.  Each @var{proc} must yield a
dynamic state, i.e. a procedure that takes zero or one arguments.
@c JP
まず@var{proc}と@var{value}が評価されます。@var{proc}は動的状態、
すなわち0個または1個の引数をとる手続きを返さなければなりません。
@c COMMON

@c EN
Then the current state each @var{proc} represents is changed
to @var{value} during evaluating @var{body} @dots{}.  The state
is restored when the control leaves @var{body} @dots{}.
The results of the last expression of @var{body} will be returned.
@c JP
そして、@var{proc}が保持する値が@var{value}に置き換えられ、
@var{body} @dots{} が評価されます。制御が@var{body} @dots{}を
離れる際に、@var{proc}が保持する値が元の値に復元されます。
@var{body}の最後の式の値が@code{temporarily}の値となります。
@c COMMON

@c EN
Whenver control trasfers out of @var{body}, or reenters to @var{body},
the state of each @var{proc} is saved and restored.
@c JP
制御が@var{body}から脱出したり、再入したりする度に、
それぞれの@var{proc}が保持する値が回復されます。
@c COMMON
@end defmac


@node Difference of parameters and dynamic states, Transition to SRFI-226 parameters, Dynamic states, Parameters and dynamic states
@subsection Difference of parameters and dynamic states
@c NODE パラメータと動的状態の違い

@c EN
At a first grance, parameters and dynamic states look almost same; both
are procedures taking zero or one arguments; when called with no arguments,
it returns the ``current'' value; when called with one argument,
it replaces the ``current'' value with the given argument.
@c JP
一見すると、パラメータと動的状態はほとんど同じに見えます。
どちらも0個または1個の引数を取る手続きで、
引数無しで呼ばれたら「現在の」値を返し、
引数つきで呼ばれたら「現在の」値を置き換えると。
@c COMMON

@c EN
The difference is that the ``state'' of a parameter, or a parameterization,
is tied to a continuation.
If a continuation frame where @code{parameterize} is evaluated is
popped, the parameterization simply goes away with it, and the previous
parameterization (tied to the previous continuation) automatically
becomes visible, instead of the explicit operation of restoring
the previous value.   That's why the body of @code{parameterize}
can be evaluated in tail context---we don't have a restore
operation to perform after the body is evaluated.
@c JP
違いは、パラメータの状態、「パラメタライゼーション」が継続と結びつけられていることです。
@code{parameterize}が評価される継続フレームがポップされると、
それに結びつけられていたパラメタライゼーションは消滅し、
ポップ後に見えている継続に結びつけられていたパラメタライゼーションが
自動的に見えるようになります。つまり、明示的に
「@code{parameterize}の外側の値を回復する」というアクションが不要です。
これが、@code{parameterize}のボディが末尾コンテクストで実行可能な理由です。
ボディを実行した後で値を回復するというアクションを走らせる必要がないからです。
@c COMMON

@c EN
On the other hand, dynamic states rely on the `after' handler
of @code{dyanmic-wind} to restore the state, hence
the body in @code{temporarily} can't be evaluated in a tail context.
@c JP
一方、動的状態は@code{dynamic-wind}のafterサンクを使って状態の復帰を行います。
なので@code{temporarily}のボディは末尾コンテクストでは実行されません。
@c COMMON

@c EN
You want to use dynamic states when the change of state requires
some actions other than storing a value, e.g. notifying the change
to a resource manager.  When a dynamic state procedure is called with
a new value, you can take necessary actions.
Restoration of parameter values after
leaving a dynamic extent is implicit; you can't know when the
parameter value is restored.
@c JP
単に値を置き換える以外のアクション、例えば状態の変更をリソース管理モジュールに
通知したい、といったものがあるなら、動的状態を使うのが良いでしょう。
動的状態の値が変更されるときは必ず動的状態手続きが引数つきで呼ばれるので、
その時に必要なアクションをトリガできます。
パラメータだと、動的エクステントを離れる時に値は暗黙に復帰されるので、
値が変わったことの通知を受けることができません。
@c COMMON

@c EN
Parameters can have @emph{converter} procedure to coerce
the value to be set.  Dynamic states aren't supposed to have the
converter procedure, though.  If the dynamic extent is inactivated and then
resumed by continuations, the dynamic value needs to be restored
without passing through the converter procedure, so it requires
additional protocol, which isn't standardized.
@c JP
パラメータはまた、converter手続きを使って、セットされる値を変換することができますが、
動的状態はconvertert手続きを使いません。
というのも、継続によって動的エクステントが一時中断され後で復帰した場合に、
動的状態の値を戻すためにはconverterをバイパスして値をセットしなければならないからです。
そうするためには別のプロトコルが必要ですが、その点に関しては標準と呼べるものがありません。
@c COMMON

@node Transition to SRFI-226 parameters,  , Difference of parameters and dynamic states, Parameters and dynamic states
@subsection Transition to SRFI-226 parameters
@c NODE SRFI-226パラメータへの移行

@c EN
@subsubheading First, here's rule of thumb:
@c JP
@subsubheading まず、大まかなルールを:
@c COMMON

@itemize @bullet
@item
@c EN
If you bind parameters only with @code{parameterize}, you won't see
any changes.
@c JP
パラメータの値を@code{parameterize}で束縛しているだけなら、違いはありません。
@c COMMON
@item
@c EN
If the code explicitly use @code{gauche.parameter}, it'll preserve
the previous behavior.  This helps legacy code to keep working.
@c JP
コード中で明示的に@code{gauche.parameter}をuseしている場合は、
以前の振る舞いのままになります。レガシーコードが壊れてしまうことはありません。
@c COMMON
@item
@c EN
For other code, you can gradually revise your code as follows:
@c JP
そうでない場合、以下の方針でコードを徐々にアップデートしてください。
@c COMMON
@itemize @minus
@item
@c EN
If you used parameters as thread-local storage, replace it with
@emph{thread locals} (@pxref{Thread local storage}).
@c JP
パラメータをスレッドローカル変数として使っている場合は、かわりに
@emph{スレッドーローカル}を使うようにします(@ref{Thread local storage}参照)。
@c COMMON
@item
@c EN
If you manage dynamic state with @code{parameterize}, replace
it with @code{temporarily} (@pxref{Dynamic states}).
@c JP
動的状態と@code{parameterize}で変更している場合は、
かわりに@code{temporarily}を使うようにします
(@ref{Dynamic states}参照)。
@c COMMON
@item
@c EN
If you used parameters for both thread-local storage @emph{and} dynamic
binding, use @code{make-thread-parameter} @emph{and}
@code{parameterize/dynwind}, in place of
@code{make-parameter} and @code{parameterize}.
(@pxref{Parameters}).
@c JP
パラメータを、スレッドローカル変数かつ動的束縛として使っている場合は、
@code{make-parameter}と@code{parameterize}のかわりに
@code{make-thread-parameter}と@code{parameterize/dynwind}を使うようにします。
@c COMMON
@end itemize
@end itemize

@c EN
@subsubheading Under the hood:
@c JP
@subsubheading ボンネットの下:
@c COMMON

@c EN
Here we call the parameter implementation before 0.9.13 as ``legacy model'',
while the one in 0.9.13 and later as ``new model''.
@c JP
ここでは0.9.13より前のパラメータ実装を「旧モデル」、
0.9.13とそれ以降を「新モデル」と呼ぶことにします。
@c COMMON

@c EN
In the legacy model, parameterization is realized by swapping
each parameter's value in dynamic wind's before and after thunk.
Roughly speaking, @code{parameterize} is expanded as follows
(this assumes Gauche's parameter protocol that returns previous
value when a new value is set.  Also, we omit consideration of
converter, for simplicity):
@c JP
旧モデルでは、パラメタライゼーションはdynamic-windのbefore/afterサンクで
パラメータの値を入れ替えることで実現されていました。
おおまかに言えば、@code{parameterize}は次のように展開されます
(Gaucheのパラメータは変更した時に以前の値を返す、というのを使っています。
また、説明の単純化のためにconverterの処理は省略しています):
@c COMMON

@example
(parameterize ((param expr)) body @dots{})
 @equiv{}
(let ((p param) (v expr))
  (dynamic-wind
   (lambda () (set! v (p v)))
   (lambda () body @dots{})
   (lambda () (set! v (p v)))))
@end example

@c EN
This model directly replaces the value of the parameter in the dynamic
scope of @var{body} @dots{}.  So the parameter value needs to be
thread-specific, otherwise the swapping of the value would be visible
from other threads, which is not desirable.
@c JP
このモデルは@var{body} @dots{}を実行している間、
パラメータの値を直接置き換えています。このモデルを取る場合、
パラメータの値はスレッドごとにせざるを得ません。
でないとあるスレッドが動的スコープに入る度に他のスレッドから見えるパラメータの値が
変わっちゃいます。
@c COMMON

@c EN
Note that even parameter value is thread-specifc, you can still
invoke a continuation captured in a different thread and expect
the parameter values are carried over, for the switching conitnuation
triggers execution of before/after thunks, which restores the
values of parameters in the thread that invokes the continuation.
@c JP
このモデルでは、パラメータの値がスレッドごとでも、ある動的環境で捕捉された継続を別のスレッドで
起動したら、捕捉されたパラメータの値は新たなスレッドに引き継がれます。
継続の呼び出し時にdynamic-windのbefore/afterサンクが実行されて、
継続捕捉時のパラメータの値が復元されるからです。
@c COMMON

@c EN
Also keep in mind that the body can't be in tail context even
the parameterize form is, since you have to execute @emph{after} thunk
after the body is evaluated.
@c JP
もうひとつ、このモデルでは、parameterizeフォームが末尾位置にあっても
bodyは末尾呼び出しできないということに留意してください。
bodyの後でafterサンクを実行しないとならないからです。
@c COMMON

@c EN
In the new model, we keep a chain of dynamic binding frames,
and parameter value is looked up from it.  The dynamic chain is a part of
continuation, so when a continuation is popped, the dynamic frame
created in the current continuation frame is also popped implicitly.
With this model, @code{parameterize} is expanded something like this:
@c JP
新モデルでは、動的束縛のフレームのチェインを持っていて、
パラメータの値はまずそこから探されます。動的束縛のチェインは継続の一部なので、
継続がポップされると、その継続フレームで使われていた動的束縛のフレームも
自動的にポップされます。このモデルでは@code{parameterize}は概念的に
こんな感じで展開されます:
@c COMMON

@example
(parameterize ((param expr)) body @dots{})
 @equiv{}
((lambda (p v)
   (push-dynamic-frame! p v)
   body @dots{})
 param expr)
@end example

@c EN
Here, @code{push-dynamic-frame!} is a hypothetical procedure that pushes
new dynamic frame in the current continuation.
When the control returns to the continuation of the parameterize
form, the additional dynamic frame is popped automatically
so we don't need a special operation.  If a continuation is captured
in @var{body}, the dynamic frame chain is saved along the continuation.
When the continuation is invoked in another thread, the dynamic frame chain
is restored.
This allows the body to be run in tail context if @code{parameterize}
itself is in tail context.
@c JP
@code{push-dynamic-frame!}は新しい動的束縛フレームを
現在の継続にプッシュする仮想的な手続きです。
制御がparameterizeフォームの継続に渡った時には、プッシュされた動的束縛フレームは
自動的にポップされているので、特別な後処理が必要ありません。
@var{body}実行中に継続が捕捉された場合、動的束縛フレームのチェインも継続とともに
保存されるので、その継続が別のスレッドで起動されたら、動的束縛フレームも復元されます。
このことから、@code{parameterize}が末尾位置にあれば、
@var{body}も末尾式として評価されます。
@c COMMON

@c EN
If you mutate parameter value (as opposed to binding it with
@code{parameterize}), the dynamic frame is mutated.  If the frame
is shared between multiple threads, those mutations are visible immediately;
they're pretty much the same as lexical frames, except the scopes.
@c JP
このモデルでは、@code{parameterize}を使わずに直接パラメータの値を変更した場合、
その変更は動的束縛フレームに反映されます。したがって同じ動的束縛フレームが
複数スレッドで共有されていれば、この変更は直ちに他のスレッドからも見えます。
@c COMMON

@c EN
SRFI-226 thread parameters are required to contain mutations within
a thread.  So we create a new thread-local whenever a thread parameter
is dynamically bound by @code{parameterize} and keep the parameter's
value in it.  The mutation on a thread
parameter is never visible from other thread, even if the dynamic
frames are shared, or a continuation having it is passed to another
thread.  So, be careful using thread parameters.  For example,
if you create a future (@pxref{Futures}), the expression in it
is evaluated in another thread, so it may not see the same
value in thread parameters as the caller.  Thread parameters
also incur overhead for every @code{parameterize}, to allocate
a new thread local.
@c JP
SRFI-226スレッドパラメータは、破壊的変更がスレッド内に止まることを要求します。
なので、スレッドパラメータを@code{parameterize}する度に、スレッドローカルが
作られてパラメータの動的な値はそこに格納されます。
スレッドパラメータの破壊的変更は、同じ動的環境がスレッド間で共有されていたり、
継続が他のスレッドに渡されて実行された場合などでも、他のスレッドには見えません。
スレッドパラメータを使う時はこの点に留意してください。
例えばfutureを作った場合、式は別スレッドで実行されるので、作成側で
見えているスレッドパラメータの値と式内で見えるそれが異なる可能性があります
(@ref{Futures}参照)。
スレッドパラメータはまた、@code{parameterize}ごとにスレッドローカルを
アロケートするので遅いです。
@c COMMON

@c EN
The new model also restricts @code{parameterize} to bind
only parameters. ``Parameter-like'' objects, a procedure that
merely follows the parameter protocol, can't be handled
in @code{parameterize}.  You should separate them and use
@code{temporarily} for the latter (@pxref{Dynamic states}).

To ease transition, 0.9.13's @code{parameterize} checks if the given
``parameters'' are all actual parameters at run-time, and if not,
it evalues as if the form is @code{parameterize/dynwind} instead.
This kind of loose behavior tends to be the source of bugs,
so we'll eventually make it stricter.  You can check if your code
is conforming the new model by using @code{(use srfi.226.parameter)}.
@c JP
新モデルでは、@code{parameterize}で動的束縛できるのはパラメータに限られます。
パラメータプロトコルに従っているだけの「パラメータのような」手続きは
@code{parameterize}では処理できません。それらは別にして、
@code{tempporarily}を使ってください (@ref{Dynamic states}参照)。

経過措置として、0.9.13の@code{parameterize}は実行時にパラメータが
本当のパラメータであるかどうか検査し、そうでなければ
@code{parameterize/dynwind}に切り替えて実行します。
ただ、こういった緩い仕様はバグのもとになるので、
将来のリリースでは@code{parameterize}はパラメータ以外はエラーにするでしょう。
現在のコードが新モデルで動くかどうかは@code{(use srfi.226.parameter)}としておけば
確かめられます。
@c COMMON


@c ------------------------------------------------------------
@node Boxes, Lazy evaluation, Parameters and dynamic states, Core library
@section  Boxes
@c NODE ボックス

@c EN
A box is a mutable container that can hold (possibly multiple) values.
It can be used as a minimal data storage, or a sort of mutable indirect
``pointer''.
@c JP
ボックスは0個以上の値を格納できる変更可能なコンテナです。
小さなデータストア、あるいは間接参照のための「ポインタ」として使うことができます。
@c COMMON

@c EN
Traditionally, a list or a vector has been used for this purpose.
However, such datatypes imply sequences of objects,   Using boxes
emphasizes your intention is just for indirection, and not so much for
sequencing.
@c JP
伝統的に、この目的にはリストやベクタが使われてきました。
しかし、リストやベクタはオブジェクトの列を扱うものと考えられます。
ボックスを使うことにより、目的がオブジェクトの列ではなく間接参照であると強調できます。
@c COMMON

@c EN
It is originally introduced by SRFI-111, which was later adopted in
R7RS-large as @code{scheme.box}.  SRFI-195 enhances it to deal with
multiple values.
@c JP
ボックスはSRFI-111で導入され、R7RS-largeに@code{scheme.box}として採り入れられました。
SRFI-195はボックスを多値に拡張しました。
@c COMMON

@c EN
The srfis leave some details to implementations.  Here are our choices:
@c JP
SRFIではいくつかの詳細を実装依存にしています。Gaucheの選択は次のとおりです。
@c COMMON
@itemize
@item
@c EN
We don't support autoboxing; that is, it is an error to pass non-box
value to the procedure expecting boxed value and vice versa.
@c JP
暗黙に値とボックスを変換するオートボクシングはサポートしません。つまり、
ボックスを期待しているところにそうでない値を渡したり、その逆をするとエラーになります。
@c COMMON
@item
@c EN
Comparing two boxes with @code{equal?} compares their contents when
two are not @code{eqv?}.  In the spec, when two boxes are @code{eqv?}
then they must also be @code{equal?} to each other, but it's up
to the implementation when two are not @code{eqv?}.
@c JP
二つのボックスを@code{equal?}で比較すると、ボックス自体が@code{eqv?}でない場合、
その内容を@code{equal?}で比較します。
SRFIでは、二つのボックスが@code{eqv?}でない場合の@code{equal?}の振る舞いは
規定されていません。
@c COMMON
@end itemize

@c EN
When you're writing portable code, be careful not to depend on the
@code{equal?} behavior.
@c JP
ポータブルなコードを書いている時は、上記@code{equal?}の振る舞いに依存しないように
気をつけてください。
@c COMMON

@defun box val @dots{}
[R7RS box][SRFI-195]
@c EN
Returns a fresh box object that contains the value @code{val} @dots{}.
@c JP
@code{val} @dots{}を内容とする新たなボックスを作って返します。
@c COMMON
@end defun

@defun box? obj
[R7RS box]
@c EN
Returns @code{#t} iff @var{obj} is a box object.
@c JP
@var{obj}がボックスなら@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun box-arity box
[SRFI-195]
@c EN
Returns the number of values @var{box} holds.
@c JP
@var{box}が保持している値の数を返します。
@c COMMON
@end defun

@defun unbox box
[R7RS box]
@c EN
Returns @var{box}'s content.  If @var{box} has N values,
it returns N values.
@c JP
@var{box}の内容を返します。@var{box}がN個の値を保持していれば、N個の値が返されます。
@c COMMON

@c EN
NB: If @var{box} is a single-valued box, @code{unbox} can be used
with generalized setters.  This is Gauche's extension.
@c JP
註: @var{box}が一つの値だけを保持している場合、@code{unbox}は一般化セッターと
一緒に使えます。これはGaucheの独自拡張です。
@c COMMON

@example
(define b (box 1))
(set! (unbox b) 2)
b @result{} #<box 2>

(define b (box '()))
(push! (unbox b) 'x)
(push! (unbox b) 'y)
b @result{} #<box (y x)>
@end example
@c COMMON

@end defun

@defun unbox-value box i
[SRFI-195]
@c EN
Returns @var{i}-th value held in @var{box}.
@c JP
@var{box}の値のうち、@var{i}番めのものを返します。
@c COMMON

@c EN
NB: This can be used with generalized setters.  This is Gauche's extension.
@c JP
註: これは一般化セッターと一緒に使えます。Gaucheの独自拡張です。
@c COMMON

@example
(define mb (box 10 20 30))
(inc! (unbox-value mb 1)
mb @result{} #<mv-box[3] 10 21 30>
@end example

@c EN
Generic referencer also works with boxes.
@c JP
boxにはジェネリックな参照も使えます。
@c COMMON

@example
(define mb (box 10 20 30))
(inc! (~ mb 1))
mb @result{} #<mv-box[3] 10 21 30>

(define b (box 10))
(inc! (~ b 0))
b @result{} #<box 11>
@end example
@end defun

@defun set-box! box val @dots{}
[R7RS box][SRFI-195]
@c EN
Alters the content of @var{box} with @var{val} @dots{}.
The numer of values must match the arity of the box.
Returns unspecified value.
@c JP
@var{box}の内容を@var{val} @dots{}で置き換えます。
値の数はボックスのアリティと同じでなければなりません。
戻り値は未定義です。
@c COMMON
@end defun

@defun set-box-value! box i val
[SRFI-195]
@c EN
Alters @var{i}-th value of @var{box} with @var{val}.
Returns unspecified value.
@c JP
@var{box}の@var{i}番めの値を@var{val}で置き換えます。
戻り値は未定義です。
@c COMMON
@end defun

@c ------------------------------------------------------------
@node Lazy evaluation, Exceptions, Boxes, Core library
@section  Lazy evaluation
@c NODE 遅延評価

@c EN
Gauche has two primitive lazy evaluation mechanisms.
@c JP
Gaucheには、ふたつの組み込みの遅延評価メカニズムがあります。
@c COMMON

@c EN
The first one is an explicit mechanism, defined in the Scheme
standard: You mark
an expression to be evaluated lazily by @code{delay},
and you use @code{force} to make the evaluation happen when
needed.  Gauche also support another primitive @code{lazy},
as defined in SRFI-45, for space-efficient tail-recursive
lazy algorithms.
@c JP
ひとつめはScheme標準で定められている、明示的なメカニズムです。遅延評価したい式を
@code{delay}構文でマークし、値が必要になったところで@code{force}により
評価を強制します。Gaucheはさらに、SRFI-45で導入された、
末尾再帰アルゴリズムでメモリを効率的に利用するための@code{lazy}というプリミティブも
サポートしています。
@c COMMON

@c EN
The second one is a lazy sequence, in which evaluation happens
implicitly.  From a Scheme program, a lazy sequence just looks
as a list---you can take its @code{car} and @code{cdr}, and
you can apply @code{map} or other list procedures on it.  However,
internally, its element isn't calculated until it is required.
@c JP
もうひとつは遅延シーケンスです。こちらは評価を@code{force}で明示する必要が
ありません。Schemeプログラムからは、遅延シーケンスは通常のリストと全く
同じに見えます。@code{car}や@code{cdr}を使ったり、@code{map}を始めとする
様々なリスト手続きをそのまま適用することができます。けれども内部的には、
遅延シーケンスの要素は必要になるまで計算されません。
@c COMMON

@menu
* Delay force and lazy::
* Lazy sequences::
@end menu


@node Delay force and lazy, Lazy sequences, Lazy evaluation, Lazy evaluation
@subsection  Delay, force and lazy
@c NODE Delayとforceとlazy

@c EN
Scheme has traditionally provided an explicit delayed evaluation mechanism
using @code{delay} and @code{force}.  After R5RS, however,
it is found that it didn't mix well with tail-recursive
algorithms: It required unbound memory, despite that the
body of the algorithm could be expressed in iterative manner.
SRFI-45 showed that introducing another primitive syntax @code{lazy}
addresses the issue.
For the detailed explanation please look at the SRFI-45 document.
Here we explain how to use those primitives.
@c JP
Schemeは伝統的に、@code{delay}と@code{force}を使った
明示的な遅延評価メカニズムを提供してきました。しかし、R5RSの後で、
それが末尾再帰的なアルゴリズムとの相性がよくないことがわかりました。
末尾再帰的なアルゴリズムの本体が反復的に表現できるにもかかわらず、
メモリを際限なく要求してしまうのです。SRFI-45によって、
新たなプリミティブ構文@code{lazy}を使えばその問題が回避できることが示されました。
詳しい議論はSRFI-45のドキュメントを見てください。
ここではこれらのプリミティブの使い方を説明します。
@c COMMON

@defspec delay expression
@defspecx lazy expression
[R7RS lazy][SRFI-45]
@c EN
These forms creates a @emph{promise} that delays the evaluation
of @var{expression}.  @var{Expression} will be evaluated
when the promise is passed to @code{force}.
@c JP
これらの形式は@var{expression}の評価を遅延する@emph{プロミス}を生成し
ます。@var{Expression} はこのプロミスが@code{force}にわたったときに評
価されます。
@c COMMON

@c EN
If @var{expression} itself is expected to yield a promise,
you should use @code{lazy}.  Otherwise, you should use @code{delay}.
If you can think in types, the difference may be clearer.
@c JP
@var{expression}自身がプロミスを返す式なら@code{lazy}を、
そうでなければ、@code{delay}を使います。
型で考えるとわかりやすいでしょう。
@c COMMON

@example
lazy  : Promise a -> Promise a
delay : a -> Promise a
@end example

@c EN
Since we don't have static typing, we can't enforce this usage.
The programmer has to choose appropriate one from the context.
Generally, @code{lazy} appears only to surround the entire
body of function that express a lazy algorithm.
@c JP
Schemeでは静的な型付けをしないので、この使い分けを強制することができません。
文脈にしたがってプログラマが適切に選択する必要があります。
一般的には@code{lazy}は遅延アルゴリズムを表現している関数本体全体を囲む場合
にのみ出現します。
@c COMMON

@c EN
NB: In R7RS, @code{lazy} is called @code{delay-force}, for the operation
is conceptually similar to @code{(delay (force expr))} (note that the
type of @code{force} is @code{Promise a -> a}).
@c JP
註: R7RSでは@code{lazy}は@code{delay-force}と呼ばれています。概念的に
@code{(delay (force expr))}という操作と考えられるからです
(@code{force}の型は@code{Promise a -> a}であると考えられます)。
@c COMMON

@c EN
For the real-world example of use of @code{lazy},
you may want to check the implementation of @code{util.stream}
(@pxref{Stream library}).
@c JP
@code{lazy}の実用的な使用例については@code{util.stream}
(@ref{Stream library})の実装をチェックするといいでしょう。
@c COMMON

@c EN
Note that @var{expression} may be evaluated more than once;
it may require the value of its own promise recursively, or more than one
thread may evaluate @var{expression} simultaneously.
In general, you shouldn't have side-effecting computation
in @var{expression}---even if it is only evaluated once,
you may not exactly know when the evaluation occur, so
having side-effects there is a bad idea.
(See @code{force} below for multi-thread semantics).
@c JP
@var{expression}は一回以上評価され得ることに気をつけてください。
@var{expression}の評価中に再帰的にそれ自身のプロミスの値を必要とするかも
しれませんし、複数のスレッドが@var{expression}の計算を並行して行うかもしれません。
一般的に、@var{expression}の中に副作用を持つ式を入れるべきではありません。
たとえ@var{expression}が一度しか評価されないとしても、
それがいつ評価されるかわからないかもしれないわけですから、
副作用を持つのはまずいでしょう。
(複数のスレッドがある場合のセマンティクスについては下の@code{force}を
参照してください)。
@c COMMON
@end defspec

@defun eager obj @dots{}
@defunx make-promise obj @dots{}
[SRFI-45][SRFI-226]
@c EN
Returns a promise that returns @var{obj} @dots{}.
The name @code{eager} is introduced in SRFI-45.  It takes single argument,
but Gauche enhanced it to take multiple values.
SRFI-226 defines @code{make-promise}, which is the same
as multi-value @code{eager}.
(Note that R7RS-small also defines @code{make-promise} in
@code{scheme.lazy} library (@pxref{R7RS lazy evaluation}).
It is slightly different that it only takes one argument,
and if the argument is a promise, it will be returned as is.
This change is intentional; see SRFI-226 for the details.)
@c JP
@var{obj} @dots{}を返すプロミスを作って返します。
@code{eager}という名前はSRFI-45で導入されました。SRFI-45では一つの引数のみを
取るように定義されていますが、Gaucheでは複数の値を取って複数の値を返せるように
拡張されています。SRFI-226は@code{make-promise}を定義しましたが、
それは複数の値を取る@code{eager}と同じです。
(R7RS-smallも@code{scheme.lazy}ライブラリで@code{make-promise}を
定義しています(@ref{R7RS lazy evaluation}参照)が、
この組み込み版とは少し異なります。
R7RS版はひとつだけ引数を取るのと、引数が既にプロミスならそのまま返されます。
この変更は意図的なものです。詳しくはSRFI-226を参照してください)。
@c COMMON

@c EN
Since that these are procedures, arguments are evaluated
before they are called; so they work as a type converter
(@code{a -> Promise a}) without delaying the evaluation.
Used mainly to construct promise-returning functions.
@c JP
これらは通常の手続きなので、引数の評価は遅延されせん。
評価を遅延することなく型変換(@code{a -> Promise a})だけを行いたい
場合に使います。プロミスを返すことが要求される手続きで使われます。
@c COMMON
@end defun

@defun force promise
[R7RS lazy][SRFI-226]
@c EN
If @var{promise} is not a promise, it is just returned.

Otherwise, if @var{promise}'s value hasn't been computed,
@code{force} makes @var{promise}'s encapsulated expression
be evaluated in the same parameterization where the promise
is created, and returns the result.

Once @var{promise}'s value is computed, it is memorized in it
so that subsequent @code{force} on it won't cause the computation.
@c JP
もし、@var{promise}がプロミスでなければ、それをそのまま返します。

そうではない場合で、もし@var{promise}の値がまだ計算されていない場合には、
@code{force}は@var{promise}が内包している式を
@var{promise}が作られた時点でのパラメタライゼーションで評価し、その結果を返します。

いったん、@var{promise}の値が計算されると、その値はメモ化され、あとで
再び@code{force}されても、再計算がおこなわれることはありません。
@c COMMON

@c EN
In Gauche, if the delayed expression yields multiple values, @code{force}
yields multiple values as well.  (It is unspecified in R7RS).

@c JP
Gaucheでは、遅延された式が複数の値を返した場合、@code{force}もそれらの値を返します。
(R7RSではその場合の動作は未定義です)。
@c COMMON

@c EN
Note that if uncomputed promise is forced simultaneously
by more than one thread, its expression may be evaluated concurrently.
The first delivered value becomes the value of the promise; if another
thread finishes computation and see the value of promise is already
determined, it discards its computation result and returns the determined
value.
@c JP
まだ計算されていないプロミスが複数のスレッドで同時にforceされた場合、
プロミスに内包される式の計算は複数のスレッドで並行して進行します。
一番最初に出た結果がプロミスの値として確定します。
他のスレッドは、自分の計算が終わった時に既にプロミスの値が確定していたら、
自分の計算結果を捨てて確定済みの値を返します。
@c COMMON

@c EN
The following example shows the promise is evaluated with the
parameterization of @code{delay}:
@c JP
下の例は、プロミスが@code{delay}のあるパラメタライゼーションで評価される
ことを示しています:
@c COMMON

@example
(define p (make-parameter 1))

(let1 v (parameterize ((p 2)) (delay (p)))
  (parameterize ((p 3))
    (force v)))
  @result{} 2
@end example

@c EN
Note: R7RS defines @code{force} to evaluate the unevaluated promise's body
in the dynamic environment of the caller of @code{force}, but it is
regarded as a mistake.  In general, you shouldn't care which @code{force} call
actually evaluates the promise's body, so the result shouldn't depend
on the context of @code{force} call.  SRFI-226 addressed it.
@c JP
註: R7RSでは未評価のプロミス本体は@code{force}の呼び出された動的環境で
評価されるとしていましたが、これは間違いであったとみなされています。
一般的に、どの@code{force}の呼び出しが実際にプロミス本体を評価するのかは
気にされるべきではなく、従ってどこで@code{force}を呼び出すかによって結果が変わるのは
おかしいからです。SRFI-226でこれは正されました。
@c COMMON
@end defun

@defun promise? obj
[R7RS lazy]
@c EN
Returns @code{#t} iff @var{obj} is a promise object.
@c JP
@var{obj}がプロミスオブジェクトである場合に
@code{#t}を返します。
@c COMMON
@end defun

@c TODO: example - use lazy tarai function

@node Lazy sequences,  , Delay force and lazy, Lazy evaluation
@subsection  Lazy sequences
@c NODE 遅延シーケンス

@c EN
@subsubheading Introduction
@c JP
@subsubheading イントロダクション
@c COMMON

@c EN
A lazy sequence is a list-like structure
whose elements are calculated lazily.
Internally we have a special type of pairs, whose @code{cdr}
is evaluated on demand.
However, in Scheme level, you'll never see a distinct
``lazy-pair'' type.   As soon as you try to access a
lazy pair, Gauche automatically @emph{force} the delayed
calculation, and the lazy pair turns into an ordinary pair.
@c JP
遅延シーケンスはリストのようなデータ構造ですが、要素は必要になるまで
計算されません。内部的には、これは@code{cdr}の評価が遅延される特別な種類の
ペアを使って実現されています。しかし、Schemeのレベルで
「遅延ペア」のような特別なデータ型が見えることは決してありません。
遅延ペアにアクセスしようとした途端、Gaucheは自動的に
遅延されていた計算を@emph{force}して、遅延ペアは通常のペアに変化してしまうからです。
@c COMMON

@c EN
It means you can pass lazy sequences to ordinary list-processing
procedures such as @code{car}, @code{cdr} or @code{map}.
@c JP
これはつまり、遅延シーケンスを@code{car}、@code{cdr}、@code{map}といった
通常のリスト処理手続きにそのまま渡せるということです。
@c COMMON

@c EN
Look at the following example; @code{generator->lseq}
takes a procedure that generates one value at a time, and
returns a lazy sequence that consists of those values.
@c JP
次の例を見てください。@code{generator->lseq}は、
「呼ばれる度に次の値を返す」という手続きを取り、返される値からなる遅延シーケンス
にして返す手続きです。
@c COMMON

@example
(with-input-from-file "file"
  (^[] (let loop ([cs (generator->lseq read-char)] [i 0])
         (match cs
           [() #f]
           [(#\c (or #\a #\d) #\r . _) i]
           [(c . cs) (loop cs (+ i 1))]))))
@end example

@c EN
It returns the position of the first occurrence of
character sequence ``car'' or ``cdr'' in the file @file{file}.
The loop treats the lazy sequence just like an ordinary list, but
characters are read as needed, so once the sequence is
found, the rest of the file won't be read.  If we do
it eagerly, we would have to read the entire file first no matter how
big it is, or to give up using the mighty @code{match} macro and
to write a basic state machine that reads one character one at a time.
@c JP
このコードは、ファイル@file{file}中に最初に出現する
``car''または``cdr''という文字列の場所を返します。
ループは遅延シーケンスを通常のリストのように扱っていますが、
文字は必要に応じて読まれ、目的の文字列が見つかれば残りは読まれません。
これを遅延無しでやろうとすると、一旦全てのファイルを読み込んでリストに
変換するか、あるいは便利な@code{match}マクロを使うのを諦めて
一文字つづ読み込んで処理する原始的な状態機械を書くしかないでしょう。
@c COMMON

@c EN
Other than implicit forcing, Gauche's lazy sequences are
slightly different than the typical lazy stream implementations in Scheme
in the following ways:
@c JP
暗黙のforceの他にも、Gaucheの遅延シーケンスは
Schemeの典型的な遅延ストリーム実装に比べて次のような違いがあります。
@c COMMON

@enumerate
@item
@c EN
When you construct a lazy sequence in an iterative lazy algorithm,
only @code{cdr} side of the lazy pair is lazily evaluated;
the @code{car} side is evaluated immediately.  On the other hand, with
@code{stream-cons} in @code{util.stream} (@pxref{Stream library}),
both @code{car} and @code{cdr} sides won't be evaluated until
it is absolutely needed.
@c JP
遅延シーケンスを、繰り返しによる怠惰なアルゴリズムから構築する際に、
遅延ペアの@code{cdr}側のみが遅延評価の対象となります。
ペアの@code{car}側は直ちに評価されます。
一方、@code{util.stream}の@code{stream-cons}では、
@code{car}と@code{cdr}のどちらも遅延評価の対象となり、
必要となるまで評価されません (@ref{Stream library}参照)。
@c COMMON
@item
@c EN
Gauche's lazy sequence always evaluates @emph{one item ahead}.
Once you get a lazy pair, its @code{car} part is already
calculated, even if you don't use it.  In most cases
you don't need to care, for calculating one item more
is a negligible overhead.  However, when you create
a self-referential lazy structure, in which the earlier
elements of a sequence is used to calculate the latter
elements of itself, a bit of caution is needed;
a valid code for fully lazy circular structure may not
terminate in Gauche's lazy sequences.  We'll show a
concrete example later.  This bit of eagerness
is also visible when side effects are involved;
for example, lazy character sequence reading from a port
may read one character ahead.
@c JP
Gaucheの遅延シーケンスは、常に@emph{ひとつ余分に}評価します。
遅延ペアを手にした段階で、その中身にアクセスするかしないかにかかわらず、
既にその@code{car}は評価済みであるということです。
ひとつ余分に計算してしまうことのコストは、通常はあまり問題にならないでしょう
(全てを余分に計算するよりは良いわけですから)。けれども、自分自身を参照
する遅延データ構造、つまり、遅延シーケンスの次の要素を計算するために
そのシーケンスの前の方の要素を参照する必要がある場合は注意が必要です。
遅延評価言語で正しい自己参照遅延データの生成コードが、
そのままではGaucheで停止しなくなる場合があります。後で例を示します。
また、評価に副作用がある場合にもこの差異が観測される場合があります。
例えば、ポートから一文字づつ読む遅延シーケンスは、
見かけよりも一文字余分に読むことになるでしょう。
@c COMMON
@end enumerate

@c EN
Note: R7RS @code{scheme.lseq} (SRFI-127)
provides a portable alternative of lazy sequence
(@pxref{R7RS lazy sequences}).  It uses
dedicated APIs (e.g. @code{lseq-cdr}) to operate on lazy sequences
so that portable implementation is possible.  In Gauche, we just
use our built-in lazy sequence as SRFI-127 lazy sequence; if you
want your code to be portable, consider using SRFI-127, but be careful
not to mix lazy sequences and ordinary lists; Gauche won't complain,
but other Scheme implementation may choke on it.
@c JP
註: ポータブルな遅延シーケンスはR7RSの@code{scheme.lseq} (SRFI-127)でも提供されています
(@ref{R7RS lazy sequences}参照)。SRFI-127では、遅延シーケンスを扱う
専用のAPI (@code{lseq-cdr}等) を提供することで、ポータブルな実装を可能にしています。
GaucheではSRFI-127の遅延シーケンスはGaucheの組み込み遅延シーケンスそのものです。
移植性が重要であれば、SRFI-127を使うのが良いでしょう。但し、遅延シーケンスと
通常のリストを混ぜないように気をつけてください。Gaucheは問題なく処理しますが、
他のScheme処理系は喉を詰まらせてしまうかもしれません。
@c COMMON

@c EN
@subsubheading Primitives
@c JP
@subsubheading プリミティブ
@c COMMON

@defun generator->lseq generator
@defunx generator->lseq item @dots{} generator
[R7RS lseq]
@c EN
Creates a lazy sequence that consists of items produced
by @var{generator}, which is just a procedure with zero arguments that yields
an item at a time.  Returning EOF marks the end of the sequence
(EOF itself isn't included in the sequence).
For example, @code{read-char} can work as a generator.
Gauche has a set of convenient utilities to deal with generators
(@pxref{Generators}).
@c JP
ジェネレータ手続き@var{generator}から生成される値の列を、遅延シーケンスとして返します。
ジェネレータ手続きは引数を取らない手続きで、呼ばれる度に次の値を返すようなものです。
EOFが返されたら、シーケンスの終了とみなされます (EOF自体はシーケンスには含まれません)。
例えば@code{read-char}はそのまま@var{generator}に渡せます。
ジェネレータ手続きを作ったり加工したりする便利なユーティリティが
@code{gauche.generator}モジュールで提供されています (@ref{Generators}参照)。
@c COMMON

@c EN
In the second form, the returned lazy sequence is prepended by
@var{item} @dots{}.  Since there's no way to distinguish lazy
pairs and ordinary pairs, you can write it as
@code{(cons* item @dots{} (generator->lseq generator))},
but that's more verbose.
@c JP
二番目の形式では、@var{item} @dots{}が遅延シーケンスの先頭に
配置されます。遅延ペアと通常のペアは区別できないので、これは
@code{(cons* item @dots{} (generator->lseq generator))}とも書けますが、
少々冗長になるでしょう。
@c COMMON

@c EN
Internally, Gauche's lazy sequence is optimized to be built
on top of generators, so this procedure is the most efficient
way to build lazy sequences.
@c JP
内部的には、Gaucheの遅延シーケンスはジェネレータを使うように最適化
されています。遅延シーケンスを作る最も効率の良い方法はこの手続きを使うことです。
@c COMMON

@c EN
Note: SRFI-127 also has @code{generator->lseq}, which is exactly
the same as this in Gauche.
@c JP
註: SRFI-127も@code{generator->lseq}を定義していますが、Gaucheではそれは
この手続きと同じものです。
@c COMMON
@end defun

@defmac lcons car cdr
@c EN
Returns a lazy pair consists of @var{car} and @var{cdr}.
The expression @var{car} is evaluated at the call of @code{lcons},
but evaluation of @var{cdr} is delayed.
@c JP
@var{car}と@var{cdr}からなる遅延ペアを作って返します。
@var{car}は@code{lcons}を呼び出した時点で評価されますが、
@var{cdr}の評価は遅延されます。
@c COMMON

@c EN
You can't distinguish a lazy pair from an ordinary pair.  If you
access either its @code{car} or @code{cdr}, or even you ask @code{pair?}
to it, its cdr part is implicitly forced and you get an ordinary pair.
@c JP
遅延ペアと通常のペアを区別する方法はありません。ペアの@code{car}や@code{cdr}に
アクセスしたり、それどころか@code{pair?}によって型を確かめただけでも、
遅延ペアのcdr側はforceされて、遅延ペアは通常のペアへと変化します。
@c COMMON

@c EN
Unlike @code{cons}, @var{cdr} should be an expression that yields
a (lazy or ordinary) list, including an empty list.
In other words, lazy sequences can always be a null-terminated list
when entirely forced; there are no ``improper lazy sequences''.
(Since Scheme isn't statically typed, we can't force the @var{cdr}
expression to be a proper list before actually evaluating it.
Currently if @var{cdr} expression yields non-list, we just ignore
it and treat as if it yielded an empty list.)
@c JP
@code{cons}と違って、遅延ペアの@var{cdr}はリスト (遅延でも通常でも) を返す
関数でなければなりません。遅延シーケンスは全てforceされたら、
常に空リストで終端されているリストになる、と言っても良いでしょう。つまり、
ドット対を最後に持つような「不完全なリスト」に対応する「不完全な遅延シーケンス」
というものはありません。(Schemeは静的型ではないので、実際に評価するまで
@var{cdr}が完全なリストを生成することを保証することができません。
現在の実装では、@var{cdr}がリストでない値を生成した場合、
それを単に無視して空リストが返されたかのように扱います)。
@c COMMON

@example
(define z (lcons (begin (print 1) 'a) (begin (print 2) '())))
@c EN
 @result{} ; prints '1', since the car part is evaluated eagerly.
@c JP
 @result{} ; car部はすぐに評価されるので、'1'が表示される
@c COMMON

@c EN
(cdr z) @result{} () ;; and prints '2'
@c JP
(cdr z) @result{} () ;; そして'2'が表示される
@c COMMON

@c EN
;; This also prints '2', for accessing car of a lazy pair forces
;; its cdr, even the cdr part isn't used.
@c JP
;; これも'2'を表示する。遅延ペアのcarにアクセスすると、その時点で
;; cdr部の評価もforceされるので。
@c COMMON
(car (lcons 'a (begin (print 2) '()))) @result{} a

@c EN
;; So as this; asking pair? to a lazy pair causes forcing its cdr.
@c JP
;; これも同じ。pair?と聞くだけで遅延ペアはforceされる
@c COMMON
(pair? (lcons 'a (begin (print 2) '()))) @result{} #t

@c EN
;; To clarify: This doesn't print '2', because the second lazy
;; pair never be accessed, so its cdr isn't evaluated.
@c JP
;; 念のため。次の例では'2'は出力されない。二番目の遅延ペアはアクセス
;; されていないので、そのcdrも評価されない。
@c COMMON
(pair? (lcons 'a (lcons 'b (begin (print 2) '())))) @result{} #t
@end example

@c EN
Now, let me show you a case where ``one item ahead'' evaluation becomes
an issue.  The following is an elegant definition of infinite
Fibonacci sequence using self-referential lazy structure
(@code{lmap} is a lazy map, defined in @code{gauche.lazy} module):
@c JP
Gaucheの「一つ先の要素まで計算」が問題となる例も見ておきましょう。
次の例は、自己参照する遅延シーケンスを使った、とても美しい無限フィボナッチ数列の
定義です (@code{lmap}は遅延バージョンのmapで、@code{gauche.lazy}モジュールで
提供されています)。
@c COMMON

@example
(use gauche.lazy)  ;; for lmap
(define *fibs* (lcons* 0 1 (lmap + *fibs* (cdr *fibs*)))) ;; BUGGY
@end example

@c EN
Unfortunately, Gauche can't handle it well.
@c JP
残念ながら、Gaucheではこれはうまく動きません。
@c COMMON

@example
(car *fibs*)
 @result{} 0
(cadr *fibs*)
 @result{} *** ERROR: Attempt to recursively force a lazy pair.
@end example

@c EN
When we want to access the second argument (@code{cadr}) of @code{*fibs*},
we take the car of the second pair,
which is a lazy pair of @code{1} and @code{(lmap ...)}.  The lazy pair
is forced and its cdr part needs to be calculated.  The first thing
@code{lmap} returns needs to see the first and second element of @code{*fibs*},
but the second element of @code{*fibs*} is what we're calculating now!
@c JP
@code{*fibs*}の二番目の要素(@code{cadr})にアクセスするということは、
@code{*fibs*}の二番目のペアのcarを取るということです。@code{*fibs*}の
二番目のペアは@code{1}と@code{(lmap ...)}の遅延ペアになっています。
carを取ろうとした時点でこの遅延ペアはforceされ、そのcdrが計算されます。
@code{lmap}が最初に返さなければならないのは、@code{*fibs*}の一番目と二番目の
要素の和です。しかし@code{*fibs*}の二番目の要素は、今まさにアクセスしようと
している値です!
@c COMMON

@c EN
We can workaround this issue by
avoiding accessing the immediately preceding value.
Fibonacci numbers F(n) = F(n-1) + F(n-2) = 2*F(n-2) + F(n-3), so we
can write our sequence as follows.
@c JP
この問題は、ある要素を計算するために直前の要素を参照しなければ回避できます。
フィボナッチ数はF(n) = F(n-1) + F(n-2) = 2*F(n-2) + F(n-3)と変形できるので、
遅延フィボナッチシーケンスはこう定義できます。
@c COMMON

@example
(define *fibs*
  (lcons* 0 1 1 (lmap (^[a b] (+ a (* b 2))) *fibs* (cdr *fibs*))))
@end example

@c EN
And this works!
@c JP
これでok!
@c COMMON

@example
(take *fibs* 20)
  @result{} (0 1 1 2 3 5 8 13 21 34 55 89 144 233
     377 610 987 1597 2584 4181)
@end example

@c EN
Many lazy algorithms are defined in terms of fully-lazy cons
at the bottom.  When you port such algorithms to Gauche using @code{lcons},
keep this bit of eagerness in mind.
@c JP
多くの遅延アルゴリズムは、完全な遅延評価をするconsを基礎にしています。
そういったアルゴリズムを@code{lcons}を使ってGaucheに移植する際には、
Gaucheのこのちょっとした「熱心さ」に気をつけてください。
@c COMMON

@c EN
Note also that @code{lcons} needs to create a thunk to delay
the evaluation.  So the algorithm to construct lazy list using
@code{lcons} has an overhead of making closure for each item.
For performance-critical part,
you want to use @code{generator->lseq} whenever possible.
@c JP
@code{lcons}は、実行の度にcdr部の評価を遅延するためのクロージャを
作るということにも注意してください。@code{lcons}を使った遅延アルゴリズムでは
要素ひとつにつきクロージャをひとつ作るオーバヘッドがかかります。
性能が重要な部分では、可能な限り@code{generator->lseq}を使いましょう。
@c COMMON
@end defmac

@c EN
@subsubheading Utilities
@c JP
@subsubheading ユーティリティ
@c COMMON

@defmac lcons* x @dots{} tail
@defmacx llist* x @dots{} tail
@c EN
A lazy version of @code{cons*} (@pxref{List constructors}).
Both @code{lcons*} and @code{llist*} do the same thing; both
names are provided for the symmetry to @code{cons*}/@code{list*}.
@c JP
遅延バージョンの@code{cons*}です (@ref{List constructors}参照)。
@code{lcons*}と@code{llist*}は全く同じです。
@code{cons*}/@code{list*}との対称性から両方の名前が定義されています。
@c COMMON

@c EN
The @var{tail} argument should be an expression that yields a
(possibly lazy) list.   It is evaluated lazily.  Note that
the preceding elements @var{x} @dots{} are evaluated eagerly.
The following equivalences hold.
@c JP
@var{tail}引数は(遅延もしくは通常の)リストを生成する式でなければなりません。
@var{tail}引数の評価は遅延されます。@var{x} @dots{}引数はすぐに
評価されます。次の関係が成り立ちます。
@c COMMON

@example
(lcons* a)           @equiv{} a
(lcons* a b)         @equiv{} (lcons a b)
(lcons* a b ... y z) @equiv{} (cons* a b @dots{} (lcons y z))
@end example
@end defmac

@defun lrange start :optional end step
@c EN
Creates a lazy sequence of numbers starting from @var{start},
increasing by @var{step} (default 1), to the maximum value that doesn't
exceed @var{end}.  The default of @var{end} is @code{+inf.0},
so it creates an infinite list.  (Don't type just
@code{(lrange 0)} in REPL, or it won't terminate!)
@c JP
@var{start}から@var{step}づつ増加し、@var{end}を越える直前までの遅延数列を
返します。@var{step}のデフォルトは1、@var{end}のデフォルトは無限大です。
@var{end}を省略すると無限数列になるので、REPLで安易に
@code{(lrange 0)}など評価しないようにしましょう。
@c COMMON

@c EN
If any of @var{start} or @code{step} is inexact, the resulting sequence
has inexact numbers.
@c JP
@var{start}と@var{step}の少なくとも一方が非正確数なら、
非正確数列が返されます。
@c COMMON

@example
(take (lrange -1) 3) @result{} (-1 0 1)

(lrange 0.0 5 0.5)
  @result{} (0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5)

(lrange 1/4 1 1/8)
  @result{} (1/4 3/8 1/2 5/8 3/4 7/8)
@end example
@end defun

@defun liota :optional (count +inf.0) (start 0) (step 1)
@c EN
A lazy version of @code{iota} (@pxref{List constructors}); returns
a lazy sequence of @var{count} integers (default: positive infinity),
starting from @var{start} (default: 0), stepping by @var{step} (default: 1).
@c JP
遅延バージョンの@code{iota}です (@ref{List constructors}参照)。
@var{start}(デフォルト0)から@var{step}(デフォルト1)づつ増加する、
@var{count}個(デフォルト無限大)の遅延数列を返します。
@c COMMON

@c EN
Just like @code{iota}, the result consists of exact numbers
if and only if both @var{start} and @var{step} are exact; otherwise
the result consists of inexact numbers.
@c JP
@code{iota}と同様、@var{start}と@var{step}の両方が正確数の時に限り、
結果は正確数のリストとなり、そうでなければ非正確数のリストとなります。
@c COMMON
@end defun

@defun port->char-lseq :optional port
@defunx port->byte-lseq :optional port
@defunx port->string-lseq :optional port
@defunx port->sexp-lseq :optional port
@c EN
These are the same as the following expressions, respectively.
They are provided for the convenience, since this pattern appears
frequently.
@c JP
これらの手続きは以下の式とそれぞれ同等です。このパターンは良く現れるので、
簡便のために用意しました。
@c COMMON

@example
(generator->lseq (cut read-char port))
(generator->lseq (cut read-byte port))
(generator->lseq (cut read-line port))
(generator->lseq (cut read port))
@end example

@c EN
If @var{port} is omitted, the current input port is used.

Note that the lazy sequence may buffer some items, so
once you make an lseq from a port, only use the resulting lseq
and don't ever read from @var{port} directly.
@c JP
@var{port}が省略された場合はcurrent-input-portが使われます。

遅延シーケンスが入力をいくらかバッファする可能性があるので、
一度lseqを作った後では、@var{port}から直接読み出しをしないようにしてください。
@c COMMON

@c EN
Note that the lazy sequence terminates when EOF is read from the port,
but the port isn't closed.  The port should be managed in larger
dynamic extent where the lazy sequence is used.
@c JP
遅延シーケンスはポートがEOFを返した時点で終端となりますが、
ポート自体はクローズされないことに注意してください。ポートの管理は、
遅延シーケンスを使う部分全体を囲むような大きな動的エクステントで
行う必要があります。
@c COMMON

@c EN
You can also convert input data into various lists by
the following expressions (@pxref{Input utility functions}).
Those procedures read the port eagerly until EOF and returns
the whole data in a list, while @code{lseq} versions read
the port lazily.
@c JP
入力ポートを色々なリストに変換するには、他に次のような手続きがあります
(@ref{Input utility functions}参照)。@code{lseq}版がポートを
必要に応じて読むのに対し、
これらの手続きはポートをEOFに達するまで一気に読み込み、
全てのデータをリストにしてから返します。
@c COMMON

@example
(port->list read-char port)
(port->list read-byte port)
(port->string-list port)
(port->sexp-list port)
@end example

@c EN
Those procedures make (lazy) lists out of ports.  The opposite can be
done by @code{open-input-char-list} and @code{open-input-byte-list};
@xref{Virtual ports}, for the details.
@c JP
これらの手続きは、ポートからリストを作りだします。反対の手続きとして、
@code{open-input-char-list}と@code{open-input-byte-list}があります
(@ref{Virtual ports}参照)。
@c COMMON
@end defun


@c EN
See also @ref{Lazy sequence utilities}, for more utility procedures
that creates lazy sequences.
@c JP
遅延シーケンスを作るユーティリティ関数は他にもたくさん提供されています。
@ref{Lazy sequence utilities}を参照してください。
@c COMMON

@c EN
@subsubheading Examples
@c JP
@subsubheading 例
@c COMMON

@c EN
Let's consider calculating an infinite sequence of prime numbers.
(Note: If you need prime numbers in your application, you don't
need to write one; just use @code{math.prime}. @pxref{Prime numbers}).
@c JP
素数の無限列を計算してみましょう。(註:
アプリケーションで素数が必要な場合は、わざわざ書かなくても
@code{math.prime}が使えます。@ref{Prime numbers}参照。)
@c COMMON

@c EN
Just pretend we already have some prime numbers
calculated in a variable @code{*primes*}, and you need
to find a prime number equal to or grater than @var{n}
(for simplicity, we assume @var{n} is an odd number).
@c JP
まず、既にある程度の計算済みの素数列が@code{*primes*}にあるとします。
すると、与えられた@var{n}以上の素数をひとつ見つける手続きが次のとおり書けます
(@var{n}は奇数とします。)
@c COMMON

@example
(define (next-prime n)
  (let loop ([ps *primes*])
    (let1 p (car ps)
      (cond [(> (* p p) n) n]
            [(zero? (modulo n p)) (next-prime (+ n 2))]
            [else (loop (cdr ps))]))))
@end example

@c EN
This procedure loops over the list of prime numbers, and
if no prime number @var{p} less than or equal to @code{(sqrt n)}
divides @var{n}, we can say @var{n} is prime.  (Actual test
is done by @code{(> (* p p) n)} instead of @code{(> p (sqrt n))},
for the former is faster.)
If we find some @var{p} divides @var{n}, we try a new value
@code{(+ n 2)} with @code{next-prime}.
@c JP
この手続きは素数列をループし、@code{(sqrt n)}以下の素数で
@var{n}を割ろうとします。一つも割りきれる素数がなければ、@var{n}が素数です。
(実際の条件は、@code{(> p (sqrt n))}より効率の良い@code{(> (* p p) n)}を
使っています)。
@var{n}を割り切る素数があった場合は、
@code{next-prime}を再帰的に呼んで@code{(+ n 2)}を試します。
@c COMMON

@c EN
Using @code{next-prime}, we can make a generator that keeps generating
prime numbers.  The following procedure returns a generator
that returns primes above @var{last}.
@c JP
@code{next-prime}を使うと、次々に素数を生成してゆくジェネレータを書くことができます。
次の手続きは@var{last}より大きい素数を次々に生成するジェネレータです。
@c COMMON

@example
(define (gen-primes-above last)
  (^[] (set! last (next-prime (+ last 2))) last))
@end example

@c EN
Using @code{generator->lseq}, we can turn the generator returned
by @code{gen-primes-above} into a lazy list, which can be used
as the value of @code{*prime*}.  The only caveat is that we need
to have some pre-calculated prime numbers:
@c JP
@code{generator->lseq}を使えば、
@code{gen-primes-above}を遅延シーケンスに変換することができ、
それを@code{*prime*}の値とすることができます。最初の方の素数を計算するために、
あらかじめ計算済みの素数をいくつか用意しておくのがポイントです。
@c COMMON

@example
(define *primes* (generator->lseq 2 3 5 (gen-primes-above 5)))
@end example

@c EN
Be careful not to evaluate @code{*primes*} directly on REPL,
since it contains an infinite list and it'll blow up your REPL.
You can look at the first 20 prime numbers instead:
@c JP
@code{*primes*}を直接REPLで評価しないように。無限リストなので、
REPLの表示が終わらなくなります。
かわりに、例えばこんなふうにして最初の20個の素数を見たり:
@c COMMON

@example
(take *primes* 20)
 @result{} (2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71)
@end example

@c EN
Or find what the 10000-th prime number is:
@c JP
10000番目の素数は何かを見たり:
@c COMMON

@example
(~ *primes* 10000)
 @result{} 104743
@end example

@c EN
Or count how many prime numbers there are below 1000000:
@c JP
あるいは1000000以下の素数はいくつあるかを調べたりできます:
@c COMMON

@example
(any (^[p i] (and (>= p 1000000) i)) *primes* (lrange 0))
 @result{} 78498
@end example

@c EN
Note: If you're familiar with the lazy functional approach, this example
may look strange.  Why do we use side-effecting generators
while we can define a sequence of prime numbers in
pure functional way, as follows?
@c JP
註：遅延評価な関数型言語に慣れたプログラマには、この例は奇妙に見えるかもしれません。
わざわざ副作用のあるジェネレータを経由しないでも、
次に示すとおり、素数列は純粋に関数的な方法で定義できます。
@c COMMON

@example
(use gauche.lazy)

(define (prime? n)
  (not (any (^p (zero? (mod n p)))
            (ltake-while (^k (<= (* k k) n)) *primes*))))

(define (primes-from k)
  (if (prime? k)
    (lcons k (primes-from (+ k 2)))
    (primes-from (+ k 2))))

(define *primes* (llist* 2 3 5 (primes-from 7)))
@end example

@c EN
(The module @code{gauche.lazy} provides @code{ltake-while}, which
is a lazy version of @code{take-while}.  We don't need lazy version
of @code{any}, since it immediately stops when the predicate returns
a true value.)
@c JP
(@code{gauche.lazy}モジュールには、@code{take-while}の
遅延バージョン@code{ltake-while}が定義されています。
@code{any}については、遅延バージョンは必要ありません。@code{any}はもともと
述語が真を返したら直ちに評価をやめて残りは見ないからです)。
@c COMMON

@c EN
The use of @code{lcons} and co-recursion in @code{primes-from}
is a typical idiom in functional programming.  It's perfectly ok
to do so in Gauche; except that the generator version is @emph{much} faster
(when you take first 5000 primes, generator version ran 17 times faster
than co-recursion version on the author's machine).
@c JP
@code{primes-from}での@code{lcons}を使った余再帰は、
関数型プログラミングでの典型的なイディオムです。もちろん、
Gaucheでもこのようなコードを書くことに何の問題もありません。
ただし、Gaucheではジェネレータを使った方が@emph{ずっと}効率が良くなります
(筆者のマシンでは、最初の5000個の素数を計算するのに、
ジェネレータ版は余再帰版より17倍速いです)。
@c COMMON

@c EN
It doesn't mean you should avoid co-recursive code; if an algorithm
can be expressed nicely in co-recursion, it's perfectly ok.  However,
watch out the subtle semantic difference from lazy functional
languages---straightforward porting may or may not work.
@c JP
だからといって何が何でも余再帰を避けるべきということにはなりません。
アルゴリズムが余再帰で自然にかけるならそうして構わないでしょう。
ただその場合でも、遅延評価な関数型言語とのセマンティクスの違いを
いつも気をつけるようにしてください。単に遅延評価アルゴリズムのコードを
そのまま移植しても動くとは限りません。
@c COMMON

@c ----------------------------------------------------------------------
@node Exceptions, Eval and repl, Lazy evaluation, Core library
@section Exceptions
@c NODE 例外

@c EN
Gauche's exception system consists of three components;
(1) the way to signal an exceptional case has occurred,
(2) the way to specify how to handle such a case,
and (3) the standard objects (@emph{conditions})
to communicate the code that
signals an exceptional case and the code that handles it.
@c JP
Gaucheの例外システムは次の3つのコンポーネントから構成されています。
(1)例外状況が発生したことを通知する方法、
(2)例外状況をどのように処理するかを指定する方法、
(3)例外状況を知らせたコードとそれを処理するコードがやりとりするための
標準オブジェクト(@emph{コンディション})。
@c COMMON

@c EN
Those three components are typically used together, so first
we explain the typical usage patterns using examples.  Then
we describe each feature in detail.
@c JP
普通これらの3つのコンポーネントは一緒に使われます。
そこで、最初に例を用いて典型的な使い方について説明し、
そのあとでそれぞれの機能について詳しく解説します。
@c COMMON

@c EN
Note for terminology: some languages use the word @emph{exception}
to refer to an object used to communicate the code that encountered
an exceptional situation with a handler that deals with it.
Gauche uses a term @emph{condition} to refer to such objects,
following SRFI-35.  @emph{Exception} is the situation, and
@emph{condition} is a runtime object that describes it.
@c JP
用語について: いくつかの言語では@emph{例外(exception)}というと、
例外的状況に遭遇したコードとそのハンドラがやりとりをするために用られる
オブジェクトのことを指します。Gaucheではそのようなオブジェクトのことを言うときには、
SRFI-35にならって@emph{コンディション(condition)}を使います。
@emph{例外}というのは、状況であり、@emph{コンディション}はそれを記述する
実行時のオブジェクトです。
@c COMMON

@menu
* Exception handling overview::
* Signaling exceptions::
* Handling exceptions::
* Conditions::
* Warnings::
@end menu

@node Exception handling overview, Signaling exceptions, Exceptions, Exceptions
@subsection Exception handling overview
@c NODE 例外処理の概要

@c EN
@subsubheading Catching specific errors
@c JP
@subsubheading 特定のエラーを捕まえる
@c COMMON

@c EN
One of the most typical exception handling is to catch a
specific error raised by some built-in or library procedures.
A macro @code{guard} can be used for such a purpose.  The code
looks like this:
@c JP
最もよくある例外処理のひとつは、組み込みあるいは
ライブラリの手続きから発生した特定のエラーを捕捉するというものです。
@code{guard}マクロがこのような目的の場合に使えます。
コードは以下のような感じになるでしょう。
@c COMMON

@example
(guard (exc [(condition-has-type? exc <read-error>)
             (format #t "read error!")
             'read-error]
            [else 'other-error])
  (read-from-string "(abc"))
@end example

@c EN
The cadr of @code{guard} clause is a form of
@code{(@var{variable} @var{clause} @dots{})}.  In this example,
the variable is @code{exc}, and it has two clauses.
Each @var{clause} has the form like the one in @code{cond}.
@c JP
@code{guard}節の cadr 部は @code{(@var{variable} @var{clause} @dots{})} という
形式です。この例では、変数は @code{exc}で、2つの節があります。
それぞれの @var{clause} は @code{cond} と似た形式になります。
@c COMMON

@c EN
The cddr of @code{guard} is the body, a list of expressions.  This
example has only one expression, @code{(read-from-string "(abc")}.
@c JP
@code{guard} の cddr 部は本体で、式のリストです。この例では、式は
@code{(read-from-string "(abc")} のひとつだけです。
@c COMMON

@c EN
@code{guard} starts executing its body.
@code{read-from-string} raises an error of type @code{<read-error>}
when it encounters syntactic errors.  The form @code{guard} intercepts
the error, and binds the condition object to the variable @var{exc},
then checks the clauses following @var{exc} in a similar manner
to @code{cond}---in this case, the thrown condition is of type
@code{<read-error>}, so the test of the first clause is satisfied,
and the rest of clause is executed, i.e. @code{"read error!"} is
printed and a symbol @code{read-error} is returned.
@c JP
@code{guard} はその本体部を実行するところから始めます。
@code{read-from-string} は構文エラーに出くわすと、@code{<read-error>}型の
エラーを発生させます。@code{guard}フォームがこのエラーを捕捉し、
そのコンディションオブジェクトを変数@var{exc}に束縛し、@var{exc}の後の
節を、@code{cond}と同じようにチェックします。この場合、投げられた
コンディションは @code{<read-error>}なので、最初の節のテストを満し、
その節の残りの部分が実行されます。すなわち、@code{"read error!"} が
印字され、シンボル @code{read-error} が返ります。
@c COMMON

@c EN
If you're familiar with other languages, you may recognize the
pattern.  The cddr of @code{guard} form is like @var{try} clause
of C++/Java or the cadr of @code{handler-case} of Common Lisp;
and the cdadr of @code{guard} form is like @code{catch} clauses
or the cddr of @code{handler-case}.
@c JP
他の言語を使い慣れていれば、同じパターンであることがわかると思います。
@code{guard} フォームの cddr 部は、C++やJavaの @var{try} 節、あるいは、
Common Lisp の @code{handler-case} の cadr 部に似ています。
また、@code{guard} フォームの cdadr 部は、@code{catch} 節あるいは、
@code{handler-case} の cddr 部に似ています。
@c COMMON

@c EN
In the test expressions it is common to check the type of
thrown condition.  The function @code{condition-has-type?} is
defined in SRFI-35 but it's rather lengthy.  Gauche's condition
classes can also work like a predicate, so you can write the
above expression like this.
@c JP
テスト式においては、投げられたコンディションのタイプをチェックする
のが普通です。@code{condition-has-type?} という関数が
SRFI-35 で定義されていますが、これはちょっと冗長です。Gauche の
コンディションクラスは述語のようにも使えるようになっており、上の
式は以下のように書くこともができます。
@c COMMON

@example
(guard (exc [(<read-error> exc)
             (format #t "read error!")
             'read-error]
            [else 'other-error])
  (read-from-string "(abc"))
@end example

@c EN
@emph{Note:} Generally you can't use @code{is-a?} to test if
the thrown condition is of a specific type, since a condition
may be @emph{compound}.  See @ref{Conditions} about compound
conditions.
@c JP
@emph{注意事項:} 一般的には、投げられたコンディションが特定の
タイプであるかをチェックするのに@code{is-a?}は使えません。
コンディションが合成されたものである可能性があるからです。
合成されたコンディションについての
詳細は @ref{Conditions} を参照してください。
@c COMMON

@c EN
If no tests of @var{clause}s satisfy and no @code{else} clause is given,
the exception `falls off' the @code{guard} construct, i.e.
it will be handled by the outer level of @code{guard} form or
top-level.  For example, the following @code{guard} form
only handles @code{<read-error>} and @code{<system-error>};
if the body throws other type of conditions, it must be handled
by outer level.
@c JP
もし、@var{clause} のどのテストも満されず、かつ @code{else} 節があたえられて
いなければ、その例外は @code{guard} から「抜け」ます。すなわち、@code{guard}
の外側のレベルあるいはトップレベルで処理されることになります。たとえば、
以下の @code{guard} フォームでは、@code{<read-error>} と
@code{<system-error>} としか処理できず、もし、本体が他のタイプのコンディション
を投げてきたら、その外側のレベルで処理しなければなりません。
@c COMMON

@example
(guard (exc [(<read-error> exc) (handle-read-error)]
            [(<system-error> exc) (handle-system-error)])
  body @dots{})
@end example

@c EN
See @ref{Handling exceptions} for more details on @code{guard} and
other lower-level exception handling constructs.
@c JP
@code{guard}および他の低レベルの例外処理の構成についての詳細は
@ref{Handling exceptions} を参照してください。
@c COMMON


@c EN
@subsubheading Signaling exceptions from your code
@c JP
@subsubheading 自分のコードから例外を通知する
@c COMMON

@c EN
The generic way to signal an exception is to use @code{raise} procedure.
@c JP
例外を通知する一般的な方法は @code{raise}手続きを使うことです。
@c COMMON

@example
(raise @var{condition})
@end example

@c EN
You can pass any object to @var{condition}; its interpretation
solely depends on the exception handler.  If you know the code
raises an integer as a condition, you can catch it by @code{guard}
as this:
@c JP
@var{condition}にはどんなオブジェクトでも渡すことができます。
それをどのように解釈するかはひとえに例外ハンドラにかかってます。
もし、コンディションとして整数があがってくるというのが判っていれば、
@code{guard} で以下のように捕捉することができます。
@c COMMON

@example
(guard (exc [(integer? exc) 'raised])
  (raise 3))
@end example

@c EN
However, as a convention, it is preferable to use an instance
of @code{<condition>} or one of its subclasses.  A macro @code{condition}
can be used to create a condition object.  The following examples
show how to create a condition with some slot values and then raise it.
@c JP
とはいうものの、@code{<condition>} あるいはそのサブクラスのインスタンスを
使うのが好ましいというのが通例です。@code{condition} マクロはコンディション
オブジェクトを作成するのに使えます。以下の例は、いくつかのスロット値をもち
それらを発生させるコンディションの作りかたを示したものです。
@c COMMON

@example
;; create and raise an error condition
(raise (condition
        (<error> (message "An error occurred."))))

;; create and raise a system error condition
(raise (condition
        (<system-error> (message "A system error occurred.")
                        (errno EINTR))))
@end example

@c EN
See @ref{Conditions} for the details of @code{condition} macro
and what kind of condition classes are provided.
@c JP
@code{condition} マクロおよび、どのようなコンディションクラスが用意
されているかの詳細については @ref{Conditions} を参照してください。
@c COMMON

@c EN
The most common type of condition is an error condition, so
a convenience procedure @code{error} and @code{errorf} are
provided.  They create an error condition with a message and
raise it.
@c JP
最も一般的なコンディションのタイプはエラーコンディションなので、
@code{error} および @code{errorf} という便利な手続きが
用意されています。これらはメッセージ付きのエラーコンディションを
生成し、それを発生させます。
@c COMMON

@example
;; `error' concatenates the arguments into a message.
(unless (integer? obj)
  (error "Integer expected, but got:" obj))

;; `errorf' uses format to create a message.
(unless (equal? x y)
  (errorf "~s and ~s don't match" x y))
@end example

@c EN
Unlike the exception throwing constructs in some languages,
such as @code{throw} of C++/Java, which abandons its continuation,
Scheme's @code{raise} may return to its caller.   If you don't
want @code{raise} to return, a rule of thumb is always to pass
one of error conditions to it; then Gauche guarantees @code{raise}
wont return.   See the description of @code{raise} in
@ref{Signaling exceptions} for more details.
@c JP
いくつかの言語での例外を投げる機構、たとえば、
C++やJavaの @code{throw} はその継続を破棄します。これとは違い
Schemeの @code{raise} はその呼び出し元へ戻ることができます。もし、
@code{raise} で元へもどらないで欲しいのなら、簡便な方法としては、
常にエラーコンディションの一つをわたるようにするというのがあります。
そうすると Gauche では @code{raise} は戻らないことを保証します。
@code{raise}の詳細については、@ref{Signaling exceptions}を参照してください。
@c COMMON

@c EN
Note: R7RS adopted slightly different semantics; it splits
@code{raise} and @code{raise-continuable}, the former is for
noncontinuable exception (if the exception handler returns,
it raises another error), and the latter is for continuable
exception.  When you're in R7RS environment, R7RS-compatible
@code{raise} will be used instead of this @code{raise}.
@c JP
註: R7RSでは少し違ったセマンティクスを採用しています。
@code{raise}は継続不可能な例外を投げるものとして(もし例外ハンドラから
制御が戻ってきたら、別のエラーを報告します)、
別に継続可能な例外を投げる@code{raise-continuable}という手続きを
設けました。R7RS環境にいるときは、本項の@code{raise}ではなく
R7RS互換の@code{raise}が見えるようになっています。
@c COMMON

@c EN
@subsubheading Defining your own condition
@c JP
@subsubheading 独自のコンディションを定義する
@c COMMON

@c EN
You can also define your own condition classes
to pass application-specific information from the point of
raising exception to the handlers.
@c JP
独自のコンディションクラスを定義することが可能で、そうすることで、
アプリケーション固有の情報を例外が発生した点からハンドラへ渡すことが
できます。
@c COMMON

@c EN
To fit to Gauche's framework (SRFI-35), it is desirable that
the new condition class inherits a built-in @code{<condition>} class
or one of its descendants, and also is an instance of a metaclass
@code{<condition-meta>}.
@c JP
Gauche のフレームワーク(SRFI-35)に適合させるためには、新しく定義する
コンディションクラスは組み込みの @code{<condition>} クラスあるいは
その子孫を継承し、また、メタクラス @code{<condition-meta>}
のインスタンスであることが望まれます。
@c COMMON

@c EN
One way of ensuring the above convention as well as increasing
portability is to use @code{define-condition-type} macro, defined
in @code{srfi.35}.
@c JP
可搬性を増すと同時に上の慣例を確実にするための方法のひとつは、
@code{define-condition-type}マクロを使うことです。これは、
@code{srfi.35}で定義されています。
@c COMMON

@example
(define-condition-type <myapp-error> <error>
  myapp-error?
  (debug-info myapp-error-debug-info)
  (reason myapp-error-reason))
@end example

@c EN
This defines a condition type (which is a class in Gauche)
@code{<myapp-error>}, with a predicate @code{myapp-error?}
and slots with accessors.   Then you can use the new
condition type like the following code:
@c JP
これは、(Gauche内のクラス)@code{<myapp-err>}を定義するもので、
このクラスには@code{myapp-error?}という述語とアクセサのあるスロット
があります。こうすれば、以下のようなコードで新しいコンディション
型が使えます。
@c COMMON

@example
(guard (exc
         [(myapp-error? exc)
          (let ([debug-info (myapp-error-debug-info exc)]
                [reason (myapp-error-reason exc)])
            ... handle myapp-error ...)])
  ...
  ...
  (if (something-went-wrong)
    (raise (condition
             (<myapp-error> (debug-info "during processing xxx")
                            (reason "something went wrong")))))
  ...
  ...
  )
@end example

@c EN
If you don't mind to lose srfi compatibility, you can use
Gauche's extended @code{error} and @code{errorf} procedures to write
more concise code to raise a condition of subtype of @code{<error>}:
@c JP
SRFIとの互換性が重要でないなら、Gaucheの拡張された@code{error}手続きを
使うと@code{<error>}のサブタイプであるコンディションを投げるコードを
より簡潔に書くことができます。
@c COMMON

@example
  (if (something-went-wrong)
    (error <myapp-error>
           :debug-info "during processing xxx"
           :reason "something went wrong"))
@end example


@c EN
See the description of @code{define-condition-type} macro
for how the condition type is implemented in Gauche's object system.
@c JP
Gauche のオブジェクトシステムでコンディション型がどのように実装されているかは
@code{define-condition-type}マクロの解説を参照してください。
@c COMMON

@node Signaling exceptions, Handling exceptions, Exception handling overview, Exceptions
@subsection Signaling exceptions
@c NODE 例外の通知

@c EN
@subsubheading Signaling errors
@c JP
@subsubheading エラーの通知
@c COMMON

@c EN
The most common case of exceptions is an error.
Two convenience functions to signal an error condition
in simple cases are provided.
To signal a compound condition, you can use @code{raise} as explained below.
@c JP
最も良くある例外ケースはエラーです。単純なエラーを通知するために、
ふたつの簡単な関数が用意されています。
複合コンディションを通知する必要がある場合は
下で説明する@code{raise}手続きを使って下さい。
@c COMMON

@defun error string arg @dots{}
@defunx error condition-type keyword-arg @dots{} string arg @dots{}
[R7RS+ base][SRFI-23+]
@c EN
Signals an error.  The first form creates an @code{<error>}
condition, with a message consists of @var{string} and @var{arg} @dots{},
and raises it.  It is compatible to R7RS and SRFI-23's @code{error} behavior.
@c JP
エラーを通知します。最初の形式は、
@var{string}と@var{arg} @dots{}からなるメッセージを持つ
@code{<error>}コンディションを作成それを@code{raise}します。
この形式はR7RS及びSRFI-23の@code{error}と互換です。
@c COMMON

@example
gosh> (define (check-integer x)
        (unless (integer? x)
           (error "Integer required, but got:" x)))
check-integer
gosh> (check-integer "a")
*** ERROR: Integer required, but got: "a"
Stack Trace:
_______________________________________
@end example

@c EN
The second form can be used to raise an error other than the
@code{<error>} condition.  @var{condition-type} must be
a condition type (see @ref{Conditions} for more explanation of
condition types).  It may be followed by keyword-value list
to initialize the condition slots, and then optionally followed by
a string and other objects that becomes an error message.
@c JP
2番目の形式は@code{<error>}以外のエラーコンディションを通知したいときに
使います。@var{condition-type}はコンディションタイプ
でなければなりません (コンディションタイプについては@ref{Conditions}を
参照して下さい)。その後に、キーワードと値のリストを与えることで
コンディションのスロットを初期化することができます。また、その後に
メッセージを構成する文字列と他のオブジェクトのリストを与えることができます。
@c COMMON

@example
(define-condition-type <my-error> <error> #f
  (reason)
  (priority))

...
  (unless (memq operation *supported-operations*)
    (error <my-error>
           :reason 'not-supported :priority 'urgent
           "Operation not supported:" operation))
...
@end example
@end defun

@defun errorf fmt-string arg @dots{}
@defunx errorf condition-type keyword-arg @dots{} fmt-string arg @dots{}
@c EN
Similar to @code{error}, but the error message is formatted by
@code{format}, i.e. the first form is equivalent to:
@c JP
@code{error}に似ていますが、エラーメッセージは@code{format}によりフォーマット
されます。すなわち、最初のフォームは以下と等価です。
@c COMMON
@example
(define (errorf fmt . args)
  (error (apply format #f fmt args)))
@end example

@c EN
The second form can be used to raise an error other than an
@code{<error>} condition.  Meaning of @var{condition-type} and
@var{keyword-arg}s are the same as @code{error}.
@c JP
2番目の形式は@code{<error>}以外のエラーコンディションを通知するのに
使えます。@var{condition-type}, @var{keyword-arg}の意味については
@code{error}と同じです。
@c COMMON
@end defun

@defun assertion-violation who message obj @dots{}
[R6RS]
@c EN
Throws an @code{<assertion-violation>} condition.  This is provided for
R6RS compatiblity.  Gauche's implementation can be described
roughly as the following equivalence:
@c JP
@code{<assertion-violation>}コンディションを投げます。
これはR6RSとの互換性のために提供されており、
Gaucheでの実装はおよそ以下の等価性で説明できます。
@c COMMON

@example
(assertion-violation who message obj @dots{})
 @equiv{} (error <assertion-violation> #"~|who|: ~|message|" (list obj @dots{}))
@end example

@c EN
If you give @code{#f} to @var{who}, however, the error message
only consists with @var{message}.
@c JP
但し、@var{who}に@code{#f}を与えた場合は、@var{message}のみがエラーメッセージとして
使われます。
@c COMMON
@end defun

@c EN
@subsubheading Signaling generic conditions
@c JP
@subsubheading 一般的な条件の通知
@c COMMON

@defun raise condition
[SRFI-18][R7RS base]
@c EN
This is the base mechanism of signaling exceptions.

The procedure invokes the current exception handler.
The argument @var{condition} represents the nature of the exception,
and passed to the exception handler.
Gauche's built-in and library functions always use
an instance of @code{<condition>} or one of its subclasses as @var{condition},
but you can pass any Scheme object to @code{raise}.  The interpretation
of @var{condition} is up to the exception handler.

@emph{Note:} Unlike some of the mainstream languages in which
"throwing" an exception never returns, you can set up an exception
handler in the way that @code{raise} may return.  The details
are explained in @ref{Handling exceptions}.

If you don't want @code{raise} to return, the best way is to
pass a condition which is an instance of @code{<serious-condition>}
or one of its subclasses.  Gauche's internal mechanism
guarantees raising such an exception won't return.
See @ref{Conditions} for the hierarchy of built-in conditions.

R7RS adopted slightly different semantics regarding returning from
@code{raise}; in R7RS, @code{raise} never returns---if the exception
handler returns, another exception is raised.
R7RS has @code{raise-continuable} to explicitly allow returning from
the exception handler.  For portable programs, always
pass @code{<serious-condition>} or its subclasses to @code{raise}.
@c JP
これは、例外事態を通知する基本となるメカニズムです。

この手続きは現在の例外ハンドラを呼び出します。引数@var{condition}は
例外の性質を表現するのに使われ、例外ハンドラに渡されます。
Gaucheの組み込み手続きやライブラリ手続きは常に、@code{<condition>}クラス
もしくはそのサブクラスのインスタンスを@var{condition}として用いますが、
ユーザは任意のオブジェクトを@code{raise}に渡すこともできます。
渡された@var{condition}の解釈は例外ハンドラに任されます。

@emph{注意事項:} いくつかの主流の言語では、例外を「投げる」と制御はそこに
戻りません。Gaucheでは@code{raise}から戻って来れるように
セットアップすることが可能です。詳細は@ref{Handling exceptions}を
参照してください。

@code{raise}から戻って来ることが無いようにしたい場合は、
@code{<serious-condition>}やそのサブクラスのインスタンスを@var{condition}
として@code{raise}に渡すのが確実です。
組み込みコンディションのクラス階層については@ref{Conditions}を参照して下さい。

R7RSではやや異なるセマンティクスを採用しています。R7RSの@code{raise}は
決して戻りません---もしハンドラが戻ってきた場合は、別の例外が投げられます。
R7RSは@code{raise-continuable}という別の手続きで、ハンドラから
戻っても良いことを明示します。ポータブルなプログラムでは、
@code{raise}には常に@code{<serious-condition>}かそのサブクラスを
渡すようにするのが良いでしょう。
@c COMMON
@end defun


@node Handling exceptions, Conditions, Signaling exceptions, Exceptions
@subsection Handling exceptions
@c NODE 例外の処理

@menu
* High-level exception handling mechanism::
* Behavior of unhandled exception::
* Low-level exception handling mechanism::
@end menu

@node High-level exception handling mechanism, Behavior of unhandled exception, Handling exceptions, Handling exceptions
@subsubsection High-level exception handling mechanism
@c NODE 上位レベルの例外処理機構

@defmac guard (var clause @dots{}) body @dots{}
[R7RS base]
@c EN
This is @emph{the} high-level form to handle errors in Gauche.
@c JP
これはGaucheでのエラー処理の高水準フォームです。
@c COMMON

@c EN
@var{var} is a symbol, and @var{clause}s are the same form as
@code{cond}'s clauses, i.e. each clause can be either one of
the following forms:
@c JP
@var{var} はシンボルで @var{clause} は @code{cond} 節と同じ形式です。
つまり、各節は以下の形式のどれかひとつです。
@c COMMON
@enumerate
@item
@code{(@var{test} @var{expr} @dots{})}
@item
@code{(@var{test} => @var{proc})}
@end enumerate

@c EN
The last @var{clause} may be @code{(else @var{expr} @dots{})}.
@c JP
最後の@var{clause}は@code{(else @var{expr} @dots{})}という形式も許されます。
@c COMMON

@c EN
This form evaluates @var{body} @dots{} and returns the value(s) of
the last @var{body} expression in normal case.
If an exception is raised during the evaluation of body expressions,
the raised exception is bound to a variable @var{var}, then
evaluates @var{test} expression of each clause.  If one of @var{test}
expressions returns true value, then the corresponding @var{expr}s
are evaluated if the clause is the first form above, or an @var{proc}
is evaluated and the result of @var{test} is passed to the procedure
@var{proc} if the clause is the second form.
@c JP
このフォームは通常の場合には @var{body} @dots{} を評価し最後の
@var{body} の式の値を返します。本体の式を評価している最中に例外が
発生した場合、発生した例外を変数 @var{var} に束縛し、その後
各節の @var{test} 式を評価します。もし、@var{test} 式のひとつが
真値を返したとき、その節が上述の最初の形式であれば、対応する
@var{expr} が評価されます。あるいは、節が二番目の形式であれば、
手続き@var{proc}に@var{test}の結果が渡されます。
@c COMMON

@c EN
When the @var{test}(s) and @var{expr}(s) in the clauses are evaluated,
the exception handler that is in effect of the caller of @code{guard} are
installed; that is, if an exception is raised again within @var{clause}s,
it is handled by the @emph{outer} exception handler or @code{guard} form.
@c JP
指定された節の @var{test} および @var{expr} が評価されるとき、
@code{guard}を呼び出した時点での例外ハンドラが設定されます。つまり、
@var{clause} 内部で再び例外が発生した場合、その例外は、@emph{外側の}
例外ハンドラまたは @code{guard} フォームで処理されます。
@c COMMON

@c EN
If no @var{test} returns true value and the last @code{clause} is
@code{else} clause, then the associated @var{expr}s are evaluated.
If no @var{test} returns true value and there's no @code{else} clause,
the raised exception is re-raised, to be handled by the outer exception
handler.
@c JP
もし、どの @var{test} も真値を返さず、最後の @code{clause} が
@code{else} 節であれば、それに結びつけられた @var{expr} が評価されます。
もし、どの @var{test} も真値を返さず、@code{else} 節がなければ、再び
例外が発生し、外側の例外ハンドラで処理されます。
@c COMMON

@c EN
When the exception is handled by one of @code{clause}s, @code{guard}
returns the value(s) of the last @var{expr} in the handling clause.
@c JP
例外が @code{clause} のどれかで処理された時には、@code{guard} は
それを処理した節の最後の @var{expr} の値を返します。
@c COMMON

@c EN
The @var{clause}s are evaluated in the same dynamic environment as
the @code{guard} form, i.e. any @code{dynamic-wind}s inside @code{body}
are unwound before evaluation of the @var{clause}s.  It is different
from the lower level forms
@code{with-error-handler} and @code{with-exception-handler}, whose
handler is evaluated before the dynamic environment are unwound.
@c JP
@var{clause}は@code{guard}と同じ動的環境で評価されます。すなわち、
@code{body}中の@code{dynamic-wind}は@var{clause}の評価の前に
巻戻されます。これは低レベル関数の@code{with-error-handler}や
@code{with-exception-handler}とは異なることに注意してください。
これら低レベル関数では例外ハンドラが呼ばれてから動的環境が巻戻されます。
@c COMMON

@example
(let ([z '()])
  (guard (e [else (push! z 'caught)])
    (dynamic-wind (lambda () (push! z 'pre))
                  (lambda () (error "foo"))
                  (lambda () (push! z 'post))))
  (reverse z))
 @result{} (pre post caught)

(guard (e [else (print 'OUTER) #f])
  (with-output-to-string
    (lambda ()
      (print 'INNER)
      (error "foo"))))
@c EN
 @result{} prints OUTER to the current output port of guard,
      not to the string port.
@c JP
 @result{} OUTERを文字列ポートではなくguard実行時の
      current-output-portに出力。
@c COMMON
@end example
@end defmac

@defmac unwind-protect expr cleanup @dots{}
@c EN
Executes @var{expr}, then executes @var{cleanup}s, and
returns the result(s) of @var{expr}.  If an uncontinuable exception is raised
within @var{expr}, @var{cleanup}s are executed before the
exception escapes from the @code{unwind-protect} form.
For example, the following code calls @code{start-motor},
@code{drill-a-hole}, and @code{stop-motor} in order if
everything goes ok, and if anything goes wrong in @code{start-motor}
or @code{drill-a-hole}, @code{stop-motor} is still called
before the exception escapes @code{unwind-protect}.
@c JP
@var{expr}を実行してから@var{cleanup} @dots{}を実行し、@var{expr}の結果を返します。
@var{expr}内で継続不可能な例外が挙がった場合、その例外が@code{unwind-protect}フォー
ムを抜ける前に、@var{cleanup} @dots{}が実行されます。たとえば、以下のコードで
はなにも問題が起きなければ、@code{start-motor}、@code{drill-a-hole}、
@code{stop-motor}が、この順で呼ばれます。何か不具合が
@code{start-motor}あるいは@code{drill-a-hole}で起った場合でも、例外が
@code{unwind-protect}を抜ける前に@code{stop-motor}が呼ばれます。
@c COMMON

@example
(unwind-protect
  (begin (start-motor)
         (drill-a-hole))
  (stop-motor))
@end example

@c EN
The @var{cleanup} forms are evaluated in the same dynamic environment
as @code{unwind-protect}.
If an exception is thrown within @var{cleanup}, it will be
handled outside of the @code{unwind-protect} form.
@c JP
@var{cleanup}フォームは@code{unwind-protect}と同じ動的環境で評価されま
す。例外が@var{cleanup}内で投げられた場合その例外は、
@code{unwind-protect}フォームの外側で処理されることになります。
@c COMMON

@c EN
Although this form looks similar to @code{dynamic-wind}, they
work at different layers and should not be confused.
@code{dynamic-wind} is the bottom-level
building block and used to manage current exception handlers,
current i/o ports, parameters, etc.
@code{dynamic-wind}'s @var{before} and @var{after} thunks are
called whenever any of those control flow transition occurs.
On the other hand, @code{unwind-protect} only cares about
the Gauche's exception system.  @code{unwind-protect}'s @var{cleanup}
is called only when @var{expr} exits normally or
throws Gauche's exception.
In the above example, if control escapes from @code{drill-a-hole}
by calling a continuation captured outside of @code{unwind-protect},
@var{cleanup} is not called; because the control may return to
@code{drill-a-hole} again.  It can happen if user-level thread
system is implemented by @code{call/cc}, for example.
@c JP
このフォームは@code{dynamic-wind}と似ていますが、この2つは動作するレイ
ヤが違いますので混同しないようにしてください。
@code{dynamic-wind}は最下位レイヤのもので、現在の例外ハンドラ、現在の入出力
ポート、パラメータなどを管理するのに用います。
@code{dynamic-wind}の@var{before}および@var{after}のサンクは
対応する制御フローの遷移が起きたときに必ず呼ばれます。
一方、@code{unwind-protect}はGaucheの例外システムの面倒しか見ません。
@code{unwind-protect}の@var{cleanup}は@var{expr}が正常終了するか
Gaucheの例外を投げたときにのみ呼びだされます。上述の例で、@code{unwind-protect}の外側で
補足された継続が呼ばれ、制御が@code{drill-a-hole}を抜けると、
@var{cleanup}は呼ばれません。制御が再び@code{drill-a-hole}に戻る可能性
があるからです。たとえば、ユーザレベルのスレッドシステムが
@code{call/cc}で実装されているような場合にこのようなことが起こる可能性
があります。
@c COMMON

@c EN
You can go back to the body @var{expr}
from outside of @code{unwind-protect} by invoking continuations
captured within @var{expr}.

However, keep in mind that once @var{cleanup} are executed,
some resources might not be available in @var{expr}.
We still allow it since the reexecuted part of @var{expr} may not
depend on the resources cleaned up with @var{cleanup}.

Even if @var{expr} returns (normally or abnormally),
@var{cleanup} only executed once, in the first time.
@c JP
@var{expr}内で捕捉された継続を@code{unwind-protect}の外側で起動することで、
@var{expr}内に再び戻ることは可能です。

ただ、ひとたび@var{cleanup}が実行されてしまったら、それによってクリーンアップ
されたリソースは@var{expr}内から使えなくなっているという可能性に留意してください。
そういったリソースに依存しない計算なら再実行できるので、再起動自体は禁止されていません。

@var{expr}から複数回戻った場合(通常の評価でもエラーでも)、@var{cleanup}が
実行されるのは最初の時のみです。
@c COMMON

@c EN
The name of this form is taken from Common Lisp.  Some Scheme
systems have similar macros in different names, such as
@code{try-finally}.
@c JP
このフォームの名前はCommon Lispから取りました。同様のマクロに
@code{try-finally}というような別の名前を使っているSchemeの処理系もあります。
@c COMMON
@end defmac


@defun with-error-handler handler thunk
@c DEPRECATED
@c EN
Makes @var{handler} the active error handler and executes @var{thunk}.
If @var{thunk} returns normally, the result(s) will be returned.
If an error is signaled during execution of @var{thunk},
@var{handler} is called with one argument, an exception object
representing the error, with the continuation of @code{with-error-handler}.
That is, @code{with-error-handler} returns whatever value(s) @var{handler}
returns.
@c JP
@var{handler}をアクティブなエラーハンドラにし、@var{thunk}を実行します。
@var{thunk}が正常に戻ったら、その結果が返されます。
@var{thunk}の実行中にエラーが通知されたら、エラーを表す例外オブジェクトを
1引数とする@var{handler}が、@code{with-error-handler}の継続とともに呼ばれます。
すなわち、@code{with-error-handler}は、@var{handler}が返す値を返します。
@c COMMON

@c EN
If @var{handler} signals an error, it will be handled by the
handler installed when @code{with-error-handler} called.
@c JP
@var{handler}がエラーを通知したら、それは@code{with-error-handler}が
呼ばれたときにインストールされていたハンドラにより処理されます。
@c COMMON

@c EN
The dynamic environment where @var{handler} is executed is
the same as the error occurs.  If @code{dynamic-wind} is used
in @var{thunk}, its @var{after} method is called after @var{handler}
has returned, and before @code{with-error-handler} returns.
@c JP
@var{handler}が実行される場合の動的な環境は、エラーが起きたときのそれと
同じです。@var{thunk}内で@code{dynamic-wind}が使われていたら、
その@var{after}メソッドは@var{handler}が戻った後、かつ@code{with-error-handler}が
戻る前に呼ばれます。
@c COMMON

@c EN
Note: Using this procedure directly is @emph{no longer recommended}, since
@code{guard} is more safe and portable.  We'll keep this for
a while for the backward compatibility, but we recommend to rewrite
code to use @code{guard} instead of this.
The common idiom of "cleanup on error"
code:
@c JP
註: この手続きを直接使うことはもはや@emph{推奨されません}。@code{guard}の方が
より安全でポータブルだからです。互換性を保つためまだしばらくは
この手続きを残しますが、この手続きを使っているコードを@code{guard}によって
書き直すことを推奨します。「エラー時に後始末をする」というよくある次のような処理は：
@c COMMON
@example
(with-error-handler (lambda (e) (cleanup) (raise e))
  (lambda () body @dots{}))
@end example
@c EN
should be written like this:
@c JP
次のように書き直すことができます。
@c COMMON
@example
(guard (e [else (cleanup) (raise e)])
  body @dots{})
@end example
@end defun

@node Behavior of unhandled exception, Low-level exception handling mechanism, High-level exception handling mechanism, Handling exceptions
@subsubsection Behavior of unhandled exception
@c NODE 処理されなかった例外のふるまい

@c EN
If an exception is raised where no program-defined exception handler is
installed, the following action is taken.
@c JP
プログラムで定義した例外ハンドラを設定していないところで例外が発生した
場合以下のようなことが起ります。
@c COMMON

@enumerate
@item
@c EN
If an unhandled exception occurs within a thread other than the primordial
one, it terminates the thread, and the thrown condition
is wrapped by @code{<uncaught-exception>} condition and stored in the
thread object.  If other thread calls @code{thread-join!} to retrieve
result, the the @code{<uncaught-exception>} is thrown in that thread.
Note that no messages are displayed when the original uncaught exception
is thrown.  @xref{Thread programming tips}, for the details.
@c JP
もしメインスレッド以外のスレッドで捕捉されない例外が起きた場合、そのスレッドは終了し、
投げられた例外は@code{<uncaught-exception>}でラップされて
スレッドオブジェクトに保存されます。他のスレッドが@code{thread-join!}で
スレッドの結果を取り出そうとした時に、その@code{<uncaught-exception>}が投げられます。
元の捕捉されない例外が起きた時点では何もメッセージなどが表示されないことに注意してください。
詳しくは@ref{Thread programming tips}を参照。
@c COMMON
@item
@c EN
Otherwise,
if the program is running interactively (in repl), the information
of the thrown exception and stack trace are displayed, and
the program returns to the toplevel prompt.
@c JP
そうでなく、プログラムが対話的に走っている場合(REPL)、投げられた例外の情報とスタッ
クトレースが表示され、プログラムはトップレベルのプロンプトに戻ります。
@c COMMON
@item
@c EN
If the program is running non-interactively, the information
of the thrown exception and stack trace are displayed, then
the program exits with an exit status @code{EX_SOFTWARE} (70).
@c JP
そうでなく、プログラムが対話的に走っているのではない場合は、投げられた例外の情報と
スタックトレースが表示された後、プログラムは終了コード
@code{EX_SOFTWARE} (70)で終了します。
@c COMMON
@end enumerate

@c EN
The default error message and stack trace in the above case 2 and case 3
is printed by @code{report-error} procedure.  You can use it
in your error handler if you need the same information.
@c JP
上の2と3でのエラーメッセージとスタックトレースは、@code{report-error}手続きによって
出力されています。自分のエラーハンドラ内で同じ情報を出力したければ
これを使うことができます。
@c COMMON

@defun report-error exn :optional sink
@c EN
Prints type and message of a thrown condition object @var{exn},
then print the current stack trace.  This is the procedure
the system calls when you see an error reported on REPL.

Since you can @code{raise} any object, @var{exn} can be any
object; it's not needed to be an instance of @code{<condition>}.
A suitable message is chosen by @code{report-error}.

You can specify where the output goes by the optional @var{sink}
argument: If it is an output port, the output goes there; you can
also pass @code{#t} for the current output port and @code{#f} for
the output string port, just like @code{format}.  That is, when
you pass @code{#f}, the message goes to a temporary output string
port, and gathered string is returned.  For all the other cases,
an undefined value is returned.  If @var{sink} is omitted or
any other object listed above, the current error port is used.

Internally, this procedure calls @code{print-default-error-heading}
and @code{print-additional-error-heading}
to print the info about @var{exn}, then prints the stack trace.
You can call those procedures separately if you don't want
the stack trace.

Note: As of 0.9.5, this procedure prints stack trace of
the context where @code{report-error} is called, rather than
the context where @var{exn} is thrown.  It doesn't matter much
as far as you call @code{report-error} directly inside the
error handler, but in general what
you want to print is the latter, and we have a plan to
attach stack trace info to @code{<condition>} object in future.
@c JP
投げられたコンディションオブジェクト@var{exn}の型とメッセージを表示し、
それからスタックトレースを出力します。REPLでエラーが報告される時の
表示を出しているのがこの手続きです。

@code{raise}は任意のオブジェクトをコンディションとして投げることが出来るので、
@var{exn}も@code{<condition>}オブジェクトの
インスタンスである必要はなく、どんな型でも許されます。
@code{report-error}は適切なメッセージを選んで表示します。

出力の行き先は省略可能引数@var{sink}で指定できます。出力ポートを渡せば
そこに出力されます。また、@code{format}と同様に、@code{#t}を渡すことで
現在の出力ポートに、@code{#f}を渡すことで一時的な文字列ポートに出力できます。
@code{#f}を渡した場合、一時的な文字列ポートに出力された文字列が
返り値となります。その他の場合は未定義値が返されます。
@var{sink}が省略されるか、上記以外の値であった場合は
現在のエラーポートが使われます。

内部的に、この手続きは@var{exn}の情報を表示するために
@code{print-default-error-heading}および
@code{print-additional-error-heading}を呼び、その後スタックトレースを表示します。
スタックトレースが不要な場合、これらの手続きを直接呼ぶこともできます。


註: 0.9.5の時点で、この手続きは@var{exn}が投げられたコンテキストでの
スタックトレースではなく、@code{report-error}自身が呼ばれたコンテキストでの
スタックトレースを表示します。@code{report-error}をエラーハンドラから
直接呼んでいる限りにおいてはあまり違いは出ませんが、一般的に望ましいのは
前者なので、将来的には@code{<condition>}オブジェクトにスタックトレース情報を
つける予定があります。
@c COMMON
@end defun

@defun print-default-error-heading exn out
@c EN
Prints the first line of the default error report regarding
the thrown condition @var{exn} to an output port @var{out}.
@c JP
投げられたコンディション@var{exn}について、デフォルトのエラーレポートの
1行目を出力ポート@var{out}に書き出します。
@c COMMON

@c EN
If @var{exn} is a @code{<condition>}, the message
consists of the condition class name (without brackets, and capitalized),
followed by the message of the condition:
@c JP
@var{exn}が@code{<condition>}なら、
コンディションクラス名(からブラケットを取り除き、大文字化したもの)と、
コンディションメッセージが出力されます:
@c COMMON

@example
*** READ-ERROR: Read error at "foo":line 1: EOF inside a list (starting from line 1)
@end example

@c EN
If @var{exn} is not a @code{<condition>}, it assumes that the exception is
intended to be caught but somehow escaped, so it prints something
like this:
@c JP
@var{exn}が@code{<condition>}でない場合は、
本来補足されるべきであったコンディションがすり抜けたとみなし、
例えば次のようなメッセージが出力されます:
@c COMMON

@example
*** ERROR: unhandled exception: foo
@end example

@c EN
This is called by @code{report-error}, but you can use this procedure
separately.
@c JP
この手続きは@code{report-error}が使っていますが、
この手続きだけを直接呼び出すことも可能です。
@c COMMON
@end defun

@defun print-additional-error-heading exn out
@c EN
Prints the additional information of the thrown condition
@var{exn} to an output port @var{out}.
@c JP
投げられたコンディション@var{exn}について、追加の情報を出力ポート@var{out}に書き出します。
@c COMMON

@c EN
If @var{exn} is not a @code{<condition>}, no information is printed.
@c JP
@var{exn}が@code{<condition>}でなければ、何も出力されません。
@c COMMON

@c EN
If @var{exn} is a compound condition, it is decomposed into
individual conditions.
@c JP
@var{exn}が複合コンディションの場合は、まず個々のコンディションに分解されます。
@c COMMON

@c EN
Then, for each condition that does not inherit @code{<mixin-condition>},
@code{report-additional-condition} method is invoked on it.
Afterwards,
for each of the remaining conditions (those inherit @code{<mixin-condition>}),
@code{report-additional-condition} method is invoked on it.
@c JP
次に、各コンディションのうち@code{<mixin-condition>}を継承していない
コンディションについて@code{report-additional-condition}メソッドが呼ばれ、
最後に@code{<mixin-condition>}を継承しているコンディションについて
@code{report-additional-condition}メソッドが呼ばれます。
@c COMMON

@c EN
For example, when you see the following error report:
@c JP
例えば、次のようなエラーレポートがあった場合:
@c COMMON

@example
*** UNBOUND-VARIABLE-ERROR: unbound variable: load
    NOTE: `load' is exported from the following modules:
     - scheme.r5rs
     - scheme.load
    While loading "/home/shiro/src/Gauche/src/../src/ttt.scm" at line 3
    While compiling "./tttt.scm" at line 1: (use ttt)
    While loading "./tttt.scm" at line 1
@end example

@itemize @bullet
@item
@c EN
The first line (beginning with @code{***}) is printed by
@code{print-default-error-heading}.  The rest is printed
by @code{print-additional-error-heading}.
@c JP
最初の行(@code{***}で始まる行)は
@code{print-default-error-heading}が出しています。
残りは@code{print-additional-error-heading}が出しています。
@c COMMON
@item
@c EN
The thrown condition is a compound condition of
@code{<unbound-variable-error>}, @code{<load-condition-mixin>},
@code{<compile-error-mixin>},
and another @code{<load-condition-mixin>}.
@c JP
投げられたコンディションは、
@code{<unbound-variable-error>}、@code{<load-condition-mixin>}、
@code{<compile-error-mixin>}、そしてもうひとつの
@code{<load-condition-mixin>}の複合コンディションです。
@c COMMON
@item
@c EN
The three lines beginning with @code{NOTE} is printed by
@code{report-additional-condition} method of
@code{<unbound-variable-error>}.
@c JP
@code{NOTE}から始まる3行は、@code{<unbound-variable-error>}の
@code{report-additional-condition}メソッドが出力しています。
@c COMMON
@item
@c EN
The @code{While loading ...} lines are printed by
@code{report-additional-condition} method of
@code{<load-condition-mixin>}.
@c JP
@code{While loading ...}の行は@code{<load-condition-mixin>}の
@code{report-additional-condition}メソッドが出力しています。
@c COMMON
@item
@c EN
The @code{While compiling ...} line is printed by
@code{<compile-error-mixin>}.
@c JP
@code{While compiling ...}の行は@code{<compile-error-mixin>}の
@code{report-additional-condition}メソッドが出力しています。
@c COMMON
@end itemize

@c EN
This is called by @code{report-error}, but you can use this procedure
separately.
@c JP
この手続きは@code{report-error}が使っていますが、
この手続きだけを直接呼び出すことも可能です。
@c COMMON
@end defun

@deffn {Generic Function} report-additional-condition condition out
@c EN
Used to print additional information about a condition object
@var{condition}, to an output port @var{out}.
Some built-in conditions specializes this generic function.
See @code{print-additional-error-heading} above for an example.
@c JP
コンディションオブジェクト@var{condition}についての追加の情報を
出力ポート@var{out}に出力します。
いくつかの組み込みのコンディションはこのジェネリックファンクションを特定化しています。
具体例は上の@code{print-additional-error-heading}の項を見てください。
@c COMMON
@end deffn


@node Low-level exception handling mechanism,  , Behavior of unhandled exception, Handling exceptions
@subsubsection Low-level exception handling mechanism
@c NODE 下位レベルの例外処理機構

@c EN
This layer provides SRFI-18 compatible simple exception mechanism.
You can override the behavior of higher-level constructs such as
@code{with-error-handler} by using @code{with-exception-handler}.
@c JP
このレイヤはSRFI-18互換のシンプルな例外メカニズムを提供します。
@code{with-error-handler}のような高次元の構造の振る舞いを、
@code{with-exception-handler}を使って上書きすることができます。
@c COMMON

@c EN
Note that it is a double-edged sword.  You'll get a freedom to
construct your own exception handling semantics, but the Gauche
system won't save if something goes wrong.   Use these primitives
when you want to customize the system's higher-level semantics
or you are porting from other SRFI-18 code.
@c JP
これは諸刃の剣であることに注意して下さい。あなたは独自の例外処理
セマンティクスを構築する自由がありますが、Gaucheシステムは何か
間違いがあっても救ってくれません。システムの高次元のセマンティクスを
カスタマイズしたいか、他のSRFI-18準拠のコードを移植している場合にのみ、
これらのプリミティブを使って下さい。
@c COMMON

@defun current-exception-handler
[SRFI-18]
@c EN
Returns the current exception handler.
@c JP
現在の例外ハンドラを返します。
@c COMMON
@end defun

@defun exception-handler-stack
[SRFI-226]
@c EN
Returns a fresh list of handlers in the current exception handler stack.
The most recent one coming first.
@c JP
現在の例外ハンドラスタックにある例外ハンドラのリストを返します。
リストは新にアロケートされたもので、最後に設定されたハンドラが最初に来ます。
@c COMMON
@end defun


@defun with-exception-handler handler thunk
[R7RS base][SRFI-34]
@c EN
A procedure @var{handler} must take one argument.  This procedure
sets @var{handler} to the current exception handler and calls
@var{thunk}.
(Note that this slightly differs from SRFI-18 @code{with-exception-handler};
we'll explain it below.)
@c JP
@var{handler}は1引数を取る手続きです。この手続きは、@var{handler}を
現在の例外ハンドラにセットし、@var{thunk}を呼び出します。
(この手続きはSRFI-18の@code{with-exception-handler}と微妙に異なります。)
@c COMMON
@end defun

@c EN
When an exception is raised by @code{raise} or @code{error},
@var{handler} is called with the thrown condition in the
exactly same dynamic environment of @code{raise} or @code{error},
except that the exception handler at the time @code{with-exception-handler}
is called is restored.
@c JP
例外が@code{raise}や@code{error}で通知されると、
投げられたコンディションを引数として@var{handler}が
呼び出し元の動的環境のうち、例外ハンドラだけが@code{with-exception-handler}
呼び出し時点のものに置き換えられた環境で呼び出されます。
@c COMMON

@c EN
Note: SRFI-18 specifies the exception handler installed with
@code{with-exception-handler} will be called with exactly the same
dynamic environment, including the exception handler settings.
It means if an exception is raised within the handler, it will be
caught with the same handler.  The reasoning is that
@code{with-exception-handler} is the bottom layer and kept as simple
as possible, and further semantics should be built on top of it.

Until 0.9.10 we supported SRFI-18 semantics natively, and provided
R7RS semantics on top of it.  However, the bare SRFI-18 semantics
turned out to be error prone--users tended to assume errors from a handler
would be handled by outer handler, and were perplexed when they ran into
infinite recursion of handlers (which eventually caused a segfault, for
the recursion eats up C stack).  We decided to switch to R7RS semantics,
for it is virtually always what users want.
@c JP
註: SRFI-18の@code{with-exception-handler}では、
例外ハンドラは例外発生箇所と全く同じ動的環境で呼び出されるとしています。
つまり例外ハンドラ中で例外が発生すると、同じハンドラが再び呼ばれます。
これは、@code{with-exception-handler}を最も基本的なレイヤとして、
その上に必要なセマンティクスを実装することが意図されていたからです。

0.9.10まではGaucheの組み込みの@code{with-exception-handler}はSRFI-18の
セマンティクスで、その上にR7RSの@code{with-exception-handler}が実装されていました。
しかし、SRFI-18セマンティクスは非常に使い方を間違えられやすかったのです。
ユーザはハンドラ中で発生した例外は外側のハンドラで処理されると思い込みがちでした。
正しくハンドラの置き換えを行わないと、ハンドラ中の例外はハンドラへの無限再帰を引き起こし、
Cのスタックを食いつぶしてsegfaultします。実質的に全ての場合においてユーザが期待するのは
R7RSセマンティクスなので、切り替えることにしました。
@c COMMON

@c EN
If an exception is raised by @code{error}, or the thrown condition
inherits @code{<serious-condition>}, it is prohibited to return from
@var{handler}.  If @var{handler} ever returns in such cases, another
error is signaled, with replacing the current exception handler to the
outer handler.  So the caller of @code{error}, or the caller of @code{raise}
with @code{<serious-condition>}, can assume it never returns.
@c JP
例外が@code{error}により投げられた場合、あるいは投げられたコンディションが
@code{<serious-condition>}を継承していた場合、
@var{handler}から戻ることは禁止されます。もし戻ってしまったら、
ハンドラを外側のものに置き換えた上で別のエラーが投げられます。
したがって、@code{error}の呼び出し元、あるいは@code{<serious-condition>}を
引数とした@code{raise}の呼び出し元は、
その呼び出しが決して戻らないと考えて構いません。
@c COMMON

@c EN
The behavior of those procedures can be explained in
the following conceptual Scheme code.
@c JP
これらの手続きの振る舞いは、次の概念的なSchemeコードによって
説明されるでしょう。
@c COMMON

@example
@c EN
;; @r{Conceptual implementation of low-level exception mechanism.}
;; @r{Suppose %xh is a list of exception handlers}
@c JP
;; @r{低レベルな例外メカニズムの概念的な実装}
;; @r{%xhは例外ハンドラのリスト}
@c COMMON

(define (current-exception-handler) (car %xh))

(define (raise exn)
  (let ((prev %xh))
    (dynamic-wind
      (lambda () (set! %xh (cdr %xh)))
      (lambda ()
        (receive r ((current-exception-handler) exn)
          (if (uncontinuable-exception? exn)
            (raise (@r{@i{make-error}} "returned from uncontinuable exception"))
            (apply values r))))
      (lambda () (set! %xh prev)))))

(define (with-exception-handler handler thunk)
  (let ((prev %xh))
    (dynamic-wind
      (lambda () (set! %xh (cons handler %xh)))
      thunk
      (lambda () (set! %xh prev)))))
@end example


@node Conditions, Warnings, Handling exceptions, Exceptions
@subsection Conditions
@c NODE コンディション

@c EN
@subsubheading Built-in Condition classes
@c JP
@subsubheading 組み込みコンディションクラス
@c COMMON

@c EN
Gauche currently has the following hierarchy of built-in condition
classes.  It approximately reflects SRFI-35 and SRFI-36 condition hierarchy,
although they have Gauche-style class names.  If there's a corresponding
SRFI condition type, the class has the SRFI name as well.
@c JP
現在のところGaucheには以下の組み込みコンディションクラスの階層があります。
これは、おおよそのところ SRFI-35 および SRFI-36 のコンディションの階層を
反映したものですが、Gauche風のクラス名になっています。対応する SRFI の
コンディションタイプがあるものについては、SRFI でのクラス名も使えます。
@c COMMON

@example
  <condition>
    +- <compound-condition>
    +- <serious-condition>
    |    +- <serious-compound-condition> ; also inherits <compound-condition>
    +- <message-condition>
         +- <error>                      ; also inherits <serious-condition>
              +- <system-error>
              +- <assertion-violation>
              +- <unhandled-signal-error>
              +- <continuation-violation>
              +- <read-error>
              +- <io-error>
                   +- <port-error>
                        +- <io-read-error>
                        |    +- <io-decoding-error>
                        +- <io-write-error>
                        |    +- <io-encoding-error>
                        +- <io-closed-error>
                        +- <io-unit-error>
                        +- <io-invalid-position-error>
@end example

@c EN
Note that some conditions may occur simultaneously; for example,
error during reading from a file because of device failure may consist
both @code{<system-error>} @emph{and} @code{<io-read-error>}.
In such cases, a @emph{compound condition} is raised.
So you can't just use, for instance, @code{(is-a? obj <io-read-error>)}
to check if @code{<io-read-error>} is thrown.
See the "Condition API" section below.
@c JP
いくつかのコンディションが同時に発生することがあることに注意してください。
たとえば、ファイルの読み込がデバイスの欠陥により失敗した場合は、
@code{<system-error>} @emph{および} @code{<io-read-error>} の両方からなる
エラーとなるでしょう。
このような場合、@emph{合成したコンディション (compound condition)} が発生します。
したがって、たとえば、@code{<io-read-error>} が投げられたかどうかをチェック
するのに、単に @code{(is-a? obj <io-read-error>)} を使えばよいというわけ
にはいきません。
後述の「コンディション API」の節を参照してください。
@c COMMON

@deftp {Metaclass} <condition-meta>
@clindex condition-meta
@c EN
Every condition class is an instance of this class.
This class defines @code{object-apply} so that you can use
a condition class as a predicate, e.g.:
@c JP
すべてのコンディションクラスはこのクラスのインスタンスです。
このクラスは @code{object-apply} を定義していますので、
コンディションクラスは述語として使うことができます。たとえば、
@c COMMON

@example
(<error> obj) @equiv{} (condition-has-type? obj <error>)
@end example
@end deftp


@deftp {Class} <condition>
@deftpx {Condition Type} &condition
@clindex condition
@vindex &condition
[SRFI-35]
@c EN
The root class of the condition hierarchy.
@c JP
コンディションの階層のルートクラスです。
@c COMMON
@end deftp

@deftp {Class} <compound-condition>
@clindex compound-condition
@c EN
Represents a compound condition.  A compound condition can be
created from one or more conditions by @code{make-compound-condition}.
Don't use this class directly.
@c JP
合成コンディションを表現します。合成コンディションは
@code{make-compound-condition} を用いて1つ以上のコンディションから
生成することができます。このクラスを直接使ってはいけません。
@c COMMON

@c EN
A compound condition returns @code{#t} for @code{condition-has-type?}
if any of the original conditions has the given type.
@c JP
合成コンディションは@code{condition-has-type?} に対して、
元のコンディションのどれかが、与えられたタイプなら、@code{#t} を返します。
@c COMMON
@end deftp

@deftp {Class} <serious-condition>
@deftpx {Condition Type} &serious
@clindex serious-condition
@vindex &serious
[SRFI-35]
@c EN
Conditions of this class are for the situations that are too serious
to ignore or continue.  Particularly, you can safely assume that
if you @code{raise} this type of condition, it never returns.
@c JP
このクラスのコンディションは無視して先を続けることはできない深刻な
状況のためにあります。特に、このタイプのコンディションを @code{raise}
したら、それは元には絶対に戻らないと考えて問題ありません。
@c COMMON
@end deftp

@deftp {Class} <serious-compound-condition>
@clindex serious-compound-condition
@c EN
This is an internal class to represent a compound condition
with any of its component condition is serious.   Inherits both
@code{<compound-condition>} and @code{<serious-condition>}.
@code{make-compound-condition} uses this class if the passed
conditions includes a serious one.
Don't use this class directly.
@c JP
深刻なコンディションを含む合成コンディションを表現するための
内部クラスです。@code{<compound-condition>} および
@code{<serious-condition>} の両方を継承しています。
@code{make-compound-condition} は深刻なコンディションを含む複数の
コンディションを渡されると、このクラスを使います。このクラスを
直接使ってはいけません。
@c COMMON
@end deftp

@deftp {Class} <message-condition>
@deftpx {Condition Type} &message
@clindex message-condition
[SRFI-35]
@c EN
This class represents a condition with a message.  It has one slot.
@c JP
このクラスはメッセージ付のコンディションを表現し、スロットを一つ
もっています。
@c COMMON

@defivar {<message-condition>} message
@c EN
A message.
@c JP
メッセージ
@c COMMON

@end defivar
@end deftp

@deftp {Class} <error>
@deftpx {Condition Type} &error
@clindex error
@vindex &error
[SRFI-35]
@c EN
Indicates an error.  Inherits @code{<serious-condition>}
and @code{<message-condition>}, thus has @code{message} slot.
@c JP
エラーを表します。@code{<serious-condition>} および
@code{<message-condition>} を継承しています。したがって、
@code{message} スロットを持っています。
@c COMMON

@c EN
Note: SRFI-35 @code{&error} condition only inherits @code{&serious}
and not @code{&message}, so you have to use compound condition
to attach a message to the error condition.  Gauche uses multiple
inheritance here, largely because of backward compatibility.
To write a portable code, an error condition should be used
with a message condition, like this:
@c JP
注意事項: SRFI-35 の@code{&error}コンディションは @code{&serious}
のみを継承し、@code{&message} は継承していません。したがって、
このエラーコンディションにメッセージを付与するためには、
合成コンディションを使わなければなりません。Gauche は
主として過去のバージョンとの互換性を確保するために、
ここで多重継承を用いています。
可搬性のあるコードを書くには、以下のようにメッセージコンディション
付きのエラーコンディションを使うべきです。
@c COMMON

@example
(condition
  (&message (message "Error message"))
  (&error))
@end example
@end deftp

@defun message-condition? obj
@defunx serious-condition? obj
@defunx error? obj
[SRFI-35]
@c EN
These are SRFI-35 compatible predicates to see if @var{obj} is
a condition of type @code{&message}, @code{&serious}, and @code{&error},
respectively.
@c JP
これらはSRFI-35互換の述語で、それぞれ@var{obj}が
@code{&message}、@code{&serious}、あるいは@code{&error}型のコンディションであるか
どうかを検査します。
@c COMMON
@end defun


@deftp {Class} <system-error>
@clindex system-error
@c EN
A subclass of @code{<error>}.
When a system call returns an error, this type of exception is
thrown.  The @code{message} slot usually contains the description
of the error (like the one from @code{strerror(3)}).
Besides that, this class has one more instance slot:
@c JP
@code{<error>} のサブクラス。
システムコールがエラーを返したとき、この型の例外が投げられます。
@code{message} スロットには通常エラーの(@code{strerror(3)}のような)説明が
含まれています。それ以外に、このクラスにはもうひとつ次のような
インスタンススロットがあります。
@c COMMON

@defivar {<system-error>} errno
@c EN
Contains an integer value of system's error number.

Error numbers may differ among systems.  Gauche defines
constants for typical Unix error values (e.g. @code{EACCES}, @code{EBADF},
etc), so it is desirable to use them instead of literal numbers.
See the description of @code{sys-strerror} in @ref{System inquiry}
for available constants.
@c JP
システムのエラー番号の整数値を持ちます。

エラー番号はシステムによって異なる可能性があります。Gaucheは典型的な
Unixのエラー番号に対して定数を定義している(例: @code{EACCES}, @code{EBADF})ので、
それを使うと良いでしょう。定義されている定数に関しては
@ref{System inquiry}の@code{sys-strerror}の説明を参照してください。
@c COMMON
@end defivar

@c EN
This class doesn't have corresponding SRFI condition type,
but important to obtain OS's raw error code.  In some cases,
this type of condition is compounded with other condition
types, like @code{<io-read-error>}.
@c JP
このクラスには対応する SRFI のコンディションタイプがありませんが、
OSの生のエラーコードを取得するのに重要です。いくつかのケースで
このタイプのコンディションは他の、たとえば @code{<io-read-error>}
のようなコンディションと合成されます。
@c COMMON
@end deftp

@deftp {Class} <assertion-violation>
@clindex assertion-violation
@c EN
This is a subclass of @code{<error>}, and thrown when a program
detects a condition that supposed to be satisfied is not satisfied.

It is thrown by macros @code{assert}, @code{assume}, and
@code{assume-type} (@pxref{Conditionals}), and also
a procedure @code{assertion-violation} (@pxref{Signaling exceptions}).
It is also thrown when the built-in procedures detect runtime type errors.
@c JP
これは@code{<error>}のサブクラスで、
満たされるべき条件が満たされていないことをプログラムが発見した場合に
投げられます。

このコンディションを投げるマクロには@code{assert}、@code{assume}、
@code{assume-type}が(@ref{Conditionals}参照)、
手続きには@code{assertion-violation}があります
(@ref{Signaling exceptions}参照)。
また、組み込み手続きが実行時型エラーを検出した場合にも投げられます。
@c COMMON
@end deftp

@deftp {Class} <unhandled-signal-error>
@clindex unhandled-signal-error
@c EN
A subclass of @code{<error>}.  The default handler of most of
signals raises this condition.   See @ref{Handling signals} for
the details.
@c JP
@code{<error>}のサブクラス。多くのシグナルのデフォルトハンドラは
このコンディションを投げます。詳しくは@ref{Handling signals}を
参照してください。
@c COMMON
@defivar {<unhandled-signal-error>} signal
@c EN
An integer indicating the received signal number.
There are constants defined for typical signal numbers; see
@ref{Signals and signal sets}.
@c JP
受け取ったシグナル番号を示す整数値。典型的なシグナル番号については
定数が定義されています。@ref{Signals and signal sets}を参照のこと。
@c COMMON
@end defivar
@end deftp

@deftp {Class} <read-error>
@deftpx {Condition Type} &read-error
@clindex read-error
@vindex &read-error
[SRFI-36]
@c EN
A subclass of @code{<error>}.
When the reader detects a lexical or syntactic error during
reading an S-expression, this type of condition is raised.
@c JP
@code{<error>} のサブクラス。リーダがS式を読み込み中に、字句エラー
または構文エラーを検出したとき、この型のコンディションが投げられます。
@c COMMON

@defivar {<read-error>} port
@c EN
A port from which the reader is reading.
(NB: SRFI-36's @code{&read-error} doesn't have this slot.  Portable
program shouldn't rely on this slot).
@c JP
リーダがS式を読みこんでいたポート。
(註: SRFI-36 の @code{&read-error} はこのスロットを定義していません。
ポータブルなプログラムを書く場合はこのスロットを使わないで下さい)。
@c COMMON
@end defivar

@defivar {<read-error>} line
@c EN
A line count (1-base) of the input where the reader raised this error.
It may be -1 if the reader is reading from a port that doesn't keep
track of line count.
@c JP
リーダがこのエラーを発生させたときの入力行カウント(1がベース)。
リーダが行カウントを保持しないポートから読み込むときには、-1 となる。
@c COMMON
@end defivar

@defivar {<read-error>} column
@defivarx {<read-error>} position
@defivarx {<read-error>} span
@c EN
These slots are defined in SRFI-36's @code{&read-error}.
For the time being, these slots always hold @code{#f}.
@c JP
これらのスロットは、SRFI-36 の @code{&read-error} で定義されています。
今のところ、これらのスロットは常に @code{#f} を保持するようになっています。
@c COMMON
@end defivar

@end deftp

@deftp {Class} <io-error>
@deftpx {Condition Type} &io-error
@clindex io-error
@vindex &io-error
[SRFI-36]
@c EN
A base class of I/O errors.  Inherits @code{<error>}.
@c JP
I/O エラーのベースとなるクラス。@code{<error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <port-error>
@deftpx {Condition Type} &io-port-error
@clindex port-error
@vindex &io-port-error
[SRFI-36]
@c EN
An I/O error related to a port.   Inherits @code{<io-error>}.
@c JP
ポート関連の I/O エラー。@code{<io-error>} を継承しています。
@c COMMON

@defivar <port-error> port
@c EN
Holds the port where the error occurred.
@c JP
エラーを起したポートを保持。
@c COMMON
@end defivar
@end deftp

@deftp {Class} <io-read-error>
@deftpx {Condition Type} &io-read-error
@clindex io-read-error
@vindex &io-read-error
[SRFI-36]
@c EN
An I/O error during reading from a port.  Inherits @code{<port-error>}.
@c JP
ポートから読み込み中の I/O エラー。@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <io-write-error>
@deftpx {Condition Type} &io-write-error
@clindex io-write-error
@vindex &io-write-error
[SRFI-36]
@c EN
An I/O error during writing to a port.  Inherits @code{<port-error>}.
@c JP
ポートへの書き出し中の I/O エラー。@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <io-closed-error>
@deftpx {Condition Type} &io-closed-error
@clindex io-closed-error
@vindex &io-closed-error
[SRFI-36]
@c EN
An I/O error when read/write is attempted on a closed port.
Inherits @code{<port-error>}.
@c JP
クローズされたポートで読み込み/書き出しをしようしたときの I/O エラー。
@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <io-unit-error>
@clindex io-unit-error
@c EN
An I/O error when the read/write is requested with a unit
that is not supported by the port (e.g. a binary I/O is requested
on a character-only port).   Inherits @code{<port-error>}.
@c JP
対象となるポートでサポートされていない単位での読み/書き要求
(たとえば、キャラクタ専用ポートでのバイナリ I/O 要求)の際の I/O エラー。
@code{<port-error>} を継承しています。
@c COMMON
@end deftp

@deftp {Class} <continuation-violation>
@deftpx {Condition Type} &continuation
@clindex continuation-violation
@vindex &continuation
[SRFI-226]
@c EN
An error thrown on violation of requirements related to continuations.
A typical case is that a requested continuation prompt tag doesn't
exist in the context.  @xref{Continuation prompts}, for the details.
@c JP
継続に関する制約が破られた場合に投げられるエラーです。
典型的なのは、指定された継続プロンプトタグがコンテクスト中に見つからない場合です。
詳しくは@ref{Continuation prompts}を参照してください。
@c COMMON
@end deftp

@defun make-continuation-violation prompt-tag
[SRFI-226]
@c EN
Creates a new continuation violation condition, with @var{prompt-tag}
as the continuation prompt tag that caused the violation.
@c JP
@code{<continuation-violation>}コンディションを作ります。
@var{prompt-tag}は原因となった継続プロンプトタグです。
@c COMMON
@end defun

@defun continuation-violation? obj
[SRFI-226]
@c EN
Returns @code{#t} if @var{obj} is a @code{<continuation-violation>}
condition, @code{#f} otherwise.
@c JP
@var{obj}が@code{<continuation-violation>}コンディションなら
@code{#t}を、そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun continuation-violation-prompt-tag condition
[SRFI-226]
@c EN
Extract the value of @var{prompt-tag} slot
from @var{condition}, which must be a @code{<continuation-violation>}
condition.
@c JP
@code{<continuation-violation>}コンディションである@var{condition}の、
@var{prompt-tag}スロットの値を取り出します。
@c COMMON
@end defun


@c EN
@subsubheading Condition API
@c JP
@subsubheading コンディションAPI
@c COMMON

@defmac define-condition-type name supertype predicate field-spec @dots{}
[SRFI-35+]
@c EN
Defines a new condition type.  In Gauche, a condition type is
a class, whose metaclass is @code{<condition-meta>}.
@c JP
新しいコンディションタイプを定義します。Gaucheでは、コンディションタイプは
クラスであり、そのメタクラスは @code{<condition-meta>} です。
@c COMMON

@c EN
@var{Name} becomes the name of the new type, and also the variable
of that name is bound to the created condition type.
@var{Supertype} is the name of the supertype (direct superclass)
of this condition type.  A condition type must inherit from
@code{<condition>} or its descendants.
(Multiple inheritance can't be specified by this form, and generally
should be avoided in condition type hierarchy.  Instead, you
can use compound conditions, which don't introduce multiple inheritance.)
@c JP
@var{name} が新しいタイプの名前になり、この名前の変数が作成された
コンディションタイプに束縛されます。@var{supertype} はこのコンディション
タイプのスーパータイプ(直接のスーパークラス)の名前です。コンディション
タイプは @code{<condition>} を継承するか、その子孫を継承しなければ
なりません。(この形式では、多重継承を指定することはできません。
一般的にいって、コンディションタイプの階層の中では多重継承は避ける
べきです。そのかわりに、合成コンディションを使えます。合成コンディションは
多重継承を使いません。)
@c COMMON

@c EN
A variable @var{predicate} is bound to a predicate procedure for
this condition type.
@c JP
変数 @var{predicate} はこのコンディションタイプ用の述語手続きに
束縛されます。
@c COMMON

@c EN
Each @code{field-spec} is a form of @code{(field-name accessor-name)},
and the condition will have fields named by @var{field-name}, and
a variable @var{accessor-name} will be bound to a procedure that
accesses the field.   In Gauche, each field becomes a slot of
the created class.

Gauche extends SRFI-35 to allow @var{predicate} and/or @code{accessor-name}
to be @code{#f}, or @code{accessor-name} to be omitted,
if you don't need to them to be defined.
@c JP
各 @code{field-spec} は @code{(field-name accessor-name)} の形式で
このコンディションは、フィールド名は @var{field-name} で決まります。
変数 @var{accessor-name} はそのフィールドにアクセスする手続きに
束縛されます。Gauche では、それぞれのフィールドは生成された
クラスのスロットとなります。

GaucheはSRFI-35を拡張して、@var{predicate}や@var{accessor-name}を
定義する必要が無い場合はその位置に@code{#f}を指定できるようにしています。
@var{accessor-name}が必要無い場合はそれを省略することもできます。
@c COMMON

@c EN
When @code{define-condition-type} is expanded into a class
definition, each slot gets a @code{:init-keyword} slot option
with the keyword whose name is the same as the slot name.
@c JP
@code{define-condition-type}がクラス定義に展開される際に、
各スロットは@code{:init-keyword}スロットオプションにスロット名と
同名のキーワードを取るように定義されます。
@c COMMON
@end defmac

@defun condition-type? obj
[SRFI-35]
@c EN
Returns @code{#t} iff @var{obj} is a condition type.  In Gauche,
it means @code{(is-a? obj <condition-meta>)}.
@c JP
@var{obj}がコンディションタイプである場合で、その場合にかぎり、
@code{#t} を返します。Gauche では @code{(is-a? obj <condition-meta>)}
と同じです。
@c COMMON
@end defun

@defun make-condition-type name parent field-names
[SRFI-35]
@c EN
A procedural version to create a new condition type.
@c JP
新しいコンディションタイプを生成する手続き版です。
@c COMMON
@end defun

@defun make-condition type field-name value @dots{}
[SRFI-35]
@c EN
Creates a new condition of condition-type @var{type}, and
initializes its fields as specified by @code{field-name} and @code{value}
pairs.
@c JP
コンディションタイプ @var{type} のコンディションを生成し、
@code{field-name} および @code{value} のペアで指定されたように
フィールドを初期化します。
@c COMMON
@end defun

@defun condition? obj
[SRFI-35]
@c EN
Returns @code{#t} iff @var{obj} is a condition.  In Gauche,
it means @code{(is-a? obj <condition>)}.
@c JP
@var{obj} がコンディションである場合で、その場合にかぎり、
@code{#t} を返します。Gauche では @code{(is-a? obj <condition>)} と
同じです。
@c COMMON
@end defun

@defun condition-has-type? obj type
[SRFI-35]
@c EN
Returns @code{#t} iff @var{obj} belongs to a condition type @var{type}.
Because of compound conditions, this is not equivalent to @code{is-a?}.
@c JP
@var{obj} がコンディションタイプ @var{type} に属している場合で、その
場合にかぎり、@code{#t} を返します。合成コンディションがあるので、
これは、@code{is-a?} と同じではありません
@c COMMON
@end defun

@defun condition-ref condition field-name
[SRFI-35]
@c EN
Retrieves the value of field @var{field-name} of @var{condition}.
If @var{condition} is a compound condition, you can access to the
field of its original conditions; if more than one original condition
have @var{field-name}, the first one passed to @code{make-compound-condition}
has precedence.
@c JP
@var{condition} のフィールド @var{field-name} の値を検索します。
@var{condition} が合成コンディションであれば、元のコンディションの
フィールドにアクセスできます。もし、複数の元のコンディションが、
@var{field-name} を持つ場合には、最初に @code{make-compound-condition}
に渡されたものが優先されます。
@c COMMON

@c EN
You can use @code{slot-ref} and/or @code{ref} to access to the field
of conditions; compound conditions define a @code{slot-missing} method
so that @code{slot-ref} behaves as if the compound conditions have all the
slots of the original conditions.  Using @code{condition-ref} increases
portability, though.
@c JP
コンディションのフィールドにアクセスするには、@code{slot-ref} および
@code{ref} の両方あるいはどちらかを使えます。合成コンディションでは、
@code{slot-missing} メソッドが定義されますので、@code{slot-ref} は
あたかも、合成コンディションが元になったコンディションの全てのスロットを
もつかのように振舞います。しかしながら、@code{condition-ref} を
使う方が可搬性が増します。
@c COMMON
@end defun

@defun condition-message condition :optional fallback
[SRFI-35+]
@c EN
This is a convenience procedure to retrieve a message if
@var{condition} has a type @code{<message-condition>},
and returns @var{fallback} otherwise.  If @var{fallback}
is omitted, @code{#f} is assumed.

Often, in a generic routine you want to intercept a raised
condition and retrieve a message for logging or user feedback.
Since any object can be raised in Scheme, an exception may not
contain the message slot, and you need to check the type
of the condition.  We've written such code enough so that we
add this procedure.
@c JP
@var{condition}が@code{<message-condition>}を持っていれば
その@code{message}スロットを、そうでなければ@var{fallback}を返す手続きです。
@var{fallback}が省略された場合は@code{#f}が指定されたとみなします。

投げられたコンディションを一度捕まえてメッセージを記録したりユーザに見せたりする
一般的なコードはよくあります。Schemeでは任意のオブジェクトを@code{raise}できるため、
捕まえたコンディションがメッセージスロットを持っているとは限りません。
従ってそういったコードはいちいちコンディションの型を検査して分岐することになります。
そのパターンは充分によくあるので、この手続きが追加されました。
@c COMMON
@end defun

@defun make-compound-condition condition0 condition1 @dots{}
[SRFI-35]
@c EN
Returns a compound condition that has all @var{condition0} @var{condition1}
@dots{}.  The returned condition's fields are the union of all the fields
of given conditions; if any conditions have the same name of fields,
the first one takes precedence.   The returned condition also has
condition-type of all the types of given conditions.
(This is not a multiple inheritance.  See @code{<compound-condition>} above.)
@c JP
@var{condition0} @var{condition1} @dots{} のすべてを持つ合成コンディション
を返します。返されたコンディションのフィールドは、与えられたコンディション
のすべてのフィールドの和集合になります。同じ名前のフィールドを持つ
コンディションがある場合には最初に与えられものが優先されます。
返されたコンディションは元になったコンディションのすべてのタイプの
コンディションタイプをもつことになります。
(これは多重継承ではありません。上の @code{<compound-condition>} を参照)
@c COMMON
@end defun

@defun extract-condition condition condition-type
[SRFI-35]
@c EN
@var{Condition} must be a condition and have type @var{condition-type}.
This procedure returns a condition of @var{condition-type},
with field values extracted from @var{condition}.
@c JP
@var{condition} はコンディションで、@var{condition-type}タイプで
なければなりません。この手続きは @var{condition-type} のコンディション
を返し、@var{condition} からとりだされた値のフィールドを持ちます。
@c COMMON
@end defun

@defmac condition type-field-binding @dots{}
[SRFI-35]
@c EN
A convenience macro to create a (possibly compound) condition.
@var{Type-field-binding} is a form of
@code{(@var{condition-type} (@var{field-name} @var{value-expr}) @dots{})}.
@c JP
コンディションを生成するのに便利なマクロ。
合成されたコンディションも生成できます。
@var{Type-field-binding} は、
@code{(@var{condition-type} (@var{field-name} @var{value-expr}) @dots{})}
という形式になります。
@c COMMON

@example
(condition
  (type0 (field00 value00) ...)
  (type1 (field10 value10) ...)
  ...)
 @equiv{}
(make-compound-condition
  (make-condition type0 'field00 value00 ...)
  (make-condition type1 'field10 value10 ...)
  ...)
@end example
@end defmac

@node Warnings,  , Conditions, Exceptions
@subsection Warnings
@c NODE 警告

@c EN
Issuing warnings isn't systematically connected to exceptions, but
pragmatically it's used in unusual situations one step before
exceptions.  So we list it here.
@c JP
警告を出すことは例外とシステム的には関係ありませんが、
実際には「例外まではいかないけれど正常でない状態」の時に使われます。
なのでここで説明します。
@c COMMON

@defun warn fmt arg @dots{}
@c EN
Display @code{"WARNING: "}, then
the string obtained by @code{(format @var{fmt} @var{arg} @dots{})},
to the current error port.
(No extra newline is printed; it is recommended to end @var{fmt} with
a newline.)

It is to tell the user that @emph{something in the code}
needs imminent attention, e.g. the new version of the library
fixed a bug but detects the caller relies on the old buggy behavior.

It should be used sparingly, though, for the user to see this warning
message may not be the people who neeeds to read it (e.g. author of
the program that triggers the warning).
It shouldn't be used to warn to the end user's misuse of the software.
In such cases, the program can take more adequate way to notify the user
in the context.

The warning message can be suppressed if the environment variable
@code{GAUCHE_SUPPRESS_WARNING} is set.
@c JP
文字列@code{"WARNING: "}と、
@code{(format @var{fmt} @var{arg} @dots{})}で生成される文字列を
現在のエラーポートに出力します
(最後に改行文字は自動的に出力されません。@var{fmt}を改行文字で終えることを
推奨します。)

これは、@emph{コードに関して}何か直ちに気をつけることをユーザに伝えるものです。
例えば、ライブラリの新版がバグフィクスしたのだけれど、
呼び出し側が以前のバグの振る舞いに依存した呼び出し方をしているのを検出した場合、等。

この手続きは控え目に使ってください。警告を目にするユーザは、
本来それを知るべき人々 (警告を発生させたプログラムの作者等)
とは異なるかもしれません。
ユーザがソフトウェアの使い方を誤ったことに対する警告に使うべきではありません。
そういった場合は、ソフトウェアが状況に沿ったより適切な方法で
ユーザに通知すべきです。

警告メッセージは環境変数@code{GAUCHE_SUPPRESS_WARNING}が設定されている場合は
出力されません。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Eval and repl, Input and output, Exceptions, Core library
@section Eval and repl
@c NODE eval と repl

@defun eval expr env
[R7RS eval]
@c EN
Evaluate @var{expr} under the environment @var{env}.
In Gauche, @var{env} is just a @code{<module>} object.
@c JP
@var{expr}を環境@var{env}内で評価します。
Gaucheにおいて、@var{env}は単なる@code{<module>}オブジェクトです。
@c COMMON
@end defun

@c EN
R5RS and R7RS provide a portable way to obtain environment.
R5RS way is described below.  R7RS way is
described in @ref{R7RS eval}.
@c JP
R5RSとR7RSは、環境@var{env}を得るポータブルな方法を定義しています。
R5RSの方法を以下に示します。R7RSの方法は@ref{R7RS eval}を参照してください。
@c COMMON

@defun null-environment version
@defunx scheme-report-environment version
@defunx interaction-environment
[R5RS]
@c EN
Returns an environment specifier which can be used as the second
argument of @code{eval}.   Right now an environment specifier
is just a module.  @code{(null-environment 5)} returns
a @code{null} module, which contains just the syntactic bindings
specified in R5RS, @code{(scheme-report-environment 5)}
returns a @code{scheme} module, which contains syntactic and procedure
bindings in R5RS, and @code{(interaction-environment)} returns
a @code{user} module that contains all the Gauche built-ins plus
whatever the user defined.
It is possible that the Gauche adopts a first-class environment object
in future, so do not rely on the fact that the environment specifier
is just a module.
@c JP
@code{eval}の第2引数として使われる環境識別子を返します。
現時点では、環境識別子は単にモジュールです。
@code{(null-environment 5)}は、R5RSで規定されている単なる構文的な
束縛を含む@code{null}モジュールを返します。
@code{(scheme-report-environment 5)}は、R5RSで規定されている
構文的な束縛と手続きの束縛を含む@code{scheme}モジュールを返します。
@code{(interaction-environment)}は、全てのGaucheのビルトインと
ユーザ定義の全てを含んだ@code{user}モジュールを返します。
将来、Gaucheがファーストクラスの環境オブジェクトを採用する可能性が
あるので、環境識別子が単なるモジュールであることを当てにしないで
下さい。
@c COMMON

@c EN
An error is signaled if a value other than 5 is passed as @var{version}
argument.
@c JP
引数@var{version}に5以外の値を渡すとエラーが通知されます。
@c COMMON
@end defun

@defun read-eval-print-loop :optional reader evaluator printer prompter
@c EN
This exports @code{Gosh}'s default read-eval-print loop to applications.
Each argument can be @code{#f}, which indicates it to use Gauche's
default procedure(s), or a procedure that satisfies the
following conditions.
@c JP
@code{gosh}のデフォルトのread-eval-printループをアプリケーションに
エクスポートします。それぞれの引数は、Gaucheのデフォルトの手続きを使うことを
示す@code{#f}であっても良いですし、以下の条件を満たす手続きであっても構いません。
@c COMMON

@table @emph
@item reader
@c EN
A procedure that takes no arguments.  It is supposed to read an expression
and returns it.
@c JP
引数を取らない手続きです。式を読み込んでそれを返すことを期待されます。
@c COMMON
@item evaluator
@c EN
A procedure that takes two arguments, an expression and an environment
specifier.  It is supposed to evaluate the expression and returns zero or
more value(s).
@c JP
式と環境識別子を2引数として取る手続きです。式を評価して、0個以上の値を
返すことを期待されます。
@c COMMON
@item printer
@c EN
A procedure that takes zero or more arguments.   It is supposed to
print out these values.   The result of this procedure is discarded.
@c JP
0個以上の引数を取る手続きです。それらの値を出力することを期待されます。
この手続きの戻り値は無視されます。
@c COMMON
@item prompter
@c EN
A procedure that takes no arguments.  It is supposed to print
out the prompt.   The result of this procedure is discarded.
@c JP
引数を取らない手続きです。プロンプトを出力することを期待されます。
この手続きの戻り値は無視されます。
@c COMMON
@end table

@c EN
Given those procedures, @code{read-eval-print-loop} runs as follows:
@c JP
これらの手続きが与えられると、@code{read-eval-print-loop}は以下のように
動作します。
@c COMMON

@enumerate
@item
@c EN
Prints the prompt by calling @var{prompter}.
@c JP
@var{prompter}を呼んでプロンプトを出力します。
@c COMMON
@item
@c EN
Reads an expression by calling @var{reader}.  If it returns EOF,
exits the loop and returns from @code{read-eval-print-loop}.
@c JP
@var{reader}を呼んで式を読み込みます。EOFが返されたら、ループを終了し
@code{read-eval-print-loop}から戻ります。
@c COMMON
@item
@c EN
Evaluates an expression by calling @var{evaluator}
@c JP
@var{evaluator}を呼んで式を評価します。
@c COMMON
@item
@c EN
Prints the result by calling @var{printer}, then repeats from 1.
@c JP
@var{printer}を呼んで結果を出力し、その後、1から繰り返します。
@c COMMON
@end enumerate

@c EN
When an error is signaled from one of those procedures, it is
captured and reported by the default escape handler, then
the loop restarts from 1.
@c JP
これらの手続きのうちの1つからエラーが通知されると、そのエラーは
デフォルトのエスケープハンドラにより捕捉・報告され、その後、
ループが1から再開します。
@c COMMON

@c EN
It is OK to capture a continuation within those procedures
and re-invoke them afterwards.
@c JP
これらの手続きの内部で継続を捕捉し、後で再起動することは
許されています。
@c COMMON

@c EN
Note: The module @code{gauche.interactive} also defines
@code{read-eval-print-loop} which handles line editing.
If you import @code{gauche.interactive}, be aware that the original
@code{read-eval-print-loop} may be shadowed.
The line-editing version of @code{read-eval-print-loop} has
the same API, except that the user-provided @var{reader} argument is ignored.
@c JP
註: @code{gauche.interactive}ではREPLでの行編集をサポートする
@code{read-eval-print-loop}手続きを定義しています。
@code{gauche.interactive}をインポートした場合、Gaucheの元の
@code{read-eval-print-loop}がシャドウされるかもしれないことに注意してください。
@code{gauche.interactive}の@code{read-eval-print-loop}は
同じインタフェースを持ちますが、ユーザが提供する@var{reader}は無視されます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Input and output, Loading Programs, Eval and repl, Core library
@section Input and Output
@c NODE 入出力

@menu
* Ports::
* Port and threads::
* Common port operations::
* File ports::
* String ports::
* Coding-aware ports::
* Input::
* Output::
@end menu

@node Ports, Port and threads, Input and output, Input and output
@subsection Ports
@c NODE ポート

@deftp {Builtin Class} <port>
@clindex port
@c EN
A port class.   A port is Scheme's way of abstraction of I/O channel.
Gauche extends a port in number of ways so that it can be used
in wide range of applications.
@c JP
Portは、Schemeにおいて抽象化された入出力のインタフェースを提供します。
Gaucheはportにいくつかの拡張を行い、いろいろなアプリケーションに対応できるようにしました。
@c COMMON

@table @asis
@c EN
@item Textual and binary I/O
R7RS defines textual and binary ports.  In Gauche, most ports
can mix both text I/O and binary I/O.  It is cleaner to think
the two is distinct, for they are sources/sinks of different types of
objects and you don't need to mix textual and binary I/O.

In practice, however, a port is often a tap to an
untyped pool of bytes and you may want to decide
interpret it later.  One example is the standard I/O; in Unix-like
environment, it's up to the program to use pre-opened ports
for textual or binary I/O.  R7RS defines the initial ports
for @code{current-input-port} etc. are textual ports; in Gauche,
you can use either way.
@c JP
@item テキストとバイナリI/O
R7RSはテキストポートとバイナリポートを定義しています。
Gaucheでは、ほとんどのポートはテキストI/OとバイナリI/Oを混ぜて使えます。
概念的には、異なる型のオブジェクトのソース/シンクは別物と考える方が綺麗ですし、
ひとつのポートでテキストI/OとバイナリI/Oを混在して使うことは滅多にありません。

しかし現実には、ポートを型の無いデータの集まりにつながったものとして、
データをどう解釈するかは後から決めたい、という場合があります。
例えば標準入出力です。Unix的な環境では、あらかじめオープンされている標準入出力
に対してテキストI/Oを行うかバイナリI/Oを行うかはプログラムに任されています。
R7RSでは、@code{current-input-port}等の初期値はテキストポートであると
規定しています。Gaucheではどちらにも使うことができます。
@c COMMON

@c EN
@item Conversion
Some ports can be used to convert a data stream from one format
to another; one of such applications is character code conversion
ports, provided by @code{gauche.charconv} module
(@pxref{Character code conversion}, for details).
SRFI-181 also provides this feature (@pxref{Transcoded ports}).
@c JP
@item 変換
ポートはまた、データストリームを変換するのにも使えます。例えば@code{gauche.charconv}
モジュールでは、文字コード間の変換を行うポートを提供しています
(詳しくは@ref{Character code conversion}を参照)。
SRFI-181もこの機能を提供します(@ref{Transcoded ports}参照)。
@c COMMON

@c EN
@item Extra features
There are also a ports with special functionality.
A coding-aware port (@pxref{Coding-aware ports}) recognizes a special
"magic comment" in the file to know which character encoding the
file is written.
Virtual ports (@pxref{Virtual ports}) allows you to program the
behavior of the port in Scheme.  It is also provided by
SRFI-181 (@pxref{Custom ports}).

Ports can be combined to provide communication channel.
@xref{Plumbing ports}, for utilities to do so.
@c JP
@item 追加機能
また、特殊な機能を実現するポートもあります。
コーディング認識ポート(@ref{Coding-aware ports}参照)は
ファイル中の特殊なコメントを認識して、そのファイルがどの文字エンコーディング
で書かれているかを検出します。
仮想ポート(@ref{Virtual ports}参照)はSchemeでふるまいをプログラムできる
ポートを提供します。同様の機能はSRFI-181にもあります
(@ref{Custom ports})。

ポートを組み合わせて通信チャネルを作ることもできます。
@ref{Plumbing ports}で説明しています。
@c COMMON
@end table

@end deftp

@node Port and threads, Common port operations, Ports, Input and output
@subsection Port and threads
@c NODE ポートとスレッド

@c EN
The builtin port operations locks the port internally, so that port access
from multiple threads will be serialized.
(It is required by SRFI-18, BTW).
Here, "builtin port operations" are the port access functions
that takes a port and does some I/O or query on it,
such as @code{read}/@code{write}, @code{read-char}/@code{write-char},
@code{port->string}, etc.
Note that @code{call-with-*} and @code{with-*} procedures do not
lock the port during calling the given procedures, since the
procedure may pass the reference of the port to the other thread,
and Gauche wouldn't know if that's the case.
@c JP
組み込みのポート操作関数は内部的にポートをロックして、
複数のスレッドからの同一のポートへのアクセスがポートの内部状態を壊さないように
しています。
(SRFI-18によって要求されている動作です)。
ここで「組み込みのポート操作関数」はGaucheにより提供される、
ポートを引数に取り何らかのI/O動作や問い合わせを行う手続きで、
@code{read}/@code{write}、@code{read-char}/@code{write-char}、
@code{port->string}等を含みます。
但し、@code{call-with-*}や@code{with-*}系関数は、
与えられた手続きを呼ぶ際にはポートをロックしません。
その手続きが別のスレッドにポートを渡すかもしれず、Gaucheにはそれを知ることが
できないからです。
@c COMMON

@c EN
This means you don't need to be too paranoia to worry about
ports under multithreaded environment.  However, keep it in
mind that this locking mechanism is meant to be a safety net
from breaking the port's internal state, and not to be
a general mutex mechanism.  It assumes port accesses rarely
conflict, and uses spin lock to reduce the overhead of majority
cases.  If you know there will be more than one thread accessing
the same port, you should use explicit mutex to avoid conflicts.
@c JP
従って、マルチスレッド環境でポートへのアクセス競合により
ポートの内部状態を壊してしまうんじゃないか、などとあまり神経質に
なる必要はありません。但し、このロック機構はあくまで予想外の
アクセス競合によってポートがおかしな状態になってしまうことを
防ぐための安全ネットであって、一般的な排他制御機構として使われる
ことは想定していないのに注意して下さい。このロックの実装は、
ポートへのアクセス競合は例外的な場合のみであると仮定し、
通常のアクセスにおけるオーバヘッドを避けるために、スピンロックを
使用します。もし、意図的にポートアクセスが競合するようなコードを書く場合は、
明示的に排他制御をしてください。
@c COMMON

@defun with-port-locking port thunk
@c EN
Executes @var{thunk}, while making the calling thread
hold the exclusive lock of @var{port} during the dynamic extent
of @var{thunk}.

Calls of the builtin port functions during the lock is held
would bypass mutex operations and yield better performance.

Note that the lock is held during the dynamic extent of @var{thunk};
so, if @var{thunk} invokes a continuation captured outside of
@code{with-port-locking}, the lock is released.  If the continuation
captured within @var{thunk} is invoked afterwards, the lock is re-acquired.

@code{With-port-locking} may be nested.  The lock is valid during
the outermost call of @code{with-port-locking}.

Note that this procedure uses the port's built-in lock mechanism
which uses busy wait when port access conflicts.  It should be
used only for avoiding fine-grain lock overhead; use explicit
mutex if you know there will be conflicts.
@c JP
@var{port}をロックし、@var{thunk}を実行します。
ロックは@var{thunk}のダイナミックエクステントの期間有効です。

@var{port}がロックされている期間での組み込みのポートアクセス関数の
呼び出しは排他制御をバイパスするため、性能向上が見込まれます。

ロックの有効期間は@var{thunk}のダイナミックエクステントなので、
@var{thunk}内から@code{with-port-locking}の外で捕捉された
継続を呼んだ場合、ロックは解放されます。その後、@var{thunk}内で
捕捉された継続が呼ばれた場合、再びロックが獲得されます。

@code{with-port-locking}はネスト可能です。ロックは最も外側の
@code{with-port-locking}の期間中有効となります。

この手続きはポート組込みのロック機構を利用します。つまり、ポートアクセスが
競合した場合はbusy waitになるということです。この手続きはあくまで
頻繁なロックによるオーバヘッドを回避するためのものです。
もし本当に競合が予測される場合は明示的に排他制御を行ってください。
@c COMMON
@end defun

@node Common port operations, File ports, Port and threads, Input and output
@subsection Common port operations
@c NODE ポート共通の操作

@defun port? obj
@defunx input-port? obj
@defunx output-port? obj
[R7RS base]
@c EN
Returns true if @var{obj} is a port, an input port and an output port,
respectively.  @code{Port?} is not listed in the
R5RS standard procedures, but mentioned in the "Disjointness of Types"
section.
@c JP
@var{obj} がそれぞれポート、入力ポート、出力ポートなら真を返します。
@code{port?}はR5RSの"Standard Procedures"の項には
載っていませんが、"Disjointness of Types"の項に挙げられています。
@c COMMON
@end defun

@defun port-closed? port
@c EN
Returns true if @var{obj} is a port and it is already closed.
A closed port can't be reopened.
@c JP
@var{obj}がポートであり、既に閉じられていた場合に真を返します。
一度閉じたポートは再び開くことはできません。
@c COMMON
@end defun

@deffn {Parameter} current-input-port
@deffnx {Parameter} current-output-port
@deffnx {Parameter} current-error-port
[R7RS base]
@c EN
Returns the current input, output and error output port, respectively.

R7RS defines that the initial values of these ports are textual ports.
In Gauche, initial ports can handle both textual and binary I/O.
@c JP
現在の入力ポート、出力ポート、エラー出力ポートをそれぞれ返します。

R7RSではこれらのポートの初期値はテキストポートであると規定されています。
Gaucheでは、これらのポートの初期値はテキスト入出力もバイナリ入出力も扱えます。
@c COMMON

@c EN
Values of the current ports can be temporarily changed by @code{parameterize}
(@pxref{Parameters}), though you might want the convenience procedures
such as @code{with-output-to-string} or @code{with-input-from-file}
in typical cases.
@c JP
現在のポートの値は@code{parameterize}を使って一時的に変更できます
(@ref{Parameters}参照)。もっとも、典型的な場合には
より簡単な@code{with-output-to-string}や@code{with-input-from-file}などの
手続きが使えるでしょう。
@c COMMON

@example
(let1 os (open-output-string)
  (parameterize ((current-output-port os))
    (display "foo"))
  (get-output-string os))
 @result{} "foo"
@end example
@end deffn

@deffn {Parameter} current-trace-port
@c EN
A paremeter that holds an output port which debug trace goes to.
The initial value is the same as the initial value of @code{current-error-port}.
@c JP
デバッグトレース出力に使われる出力ポートを保持するパラメータです。
初期値は@code{current-error-port}の初期値と同じです。
@c COMMON

@c EN
The @code{debug-print} feature (@pxref{Debugging aid}) and
the macro trace feature (@pxref{Tracing macro expansion}) uses
this port.
@c JP
@code{debug-print}機能(@ref{Debugging aid}参照)と、
マクロトレース機能(@ref{Tracing macro expansion}参照)がこのポートを使っています。
@c COMMON
@end deffn


@deffn {Parameter} standard-input-port
@deffnx {Parameter} standard-output-port
@deffnx {Parameter} standard-error-port
@c EN
Returns standard i/o ports at the time the program started.
These ports are the default values
of @code{current-input-port}, @code{current-output-port}
and @code{current-error-port}, respectively.

You can also change value of these procedures by @code{parameterize},
but note that (1) @code{current-*-port}s are initialized before
the program execution, so changing values of @code{standard-*-port}
won't affect them, and (2) changing values these procedures only affect
Scheme-world, and does not change system-level stdio file descriptors
low-level libraries referring.
@c JP
プログラム開始時点の標準入出力ポートを返します。これらの値が
@code{current-input-port}、@code{current-output-port}、
@code{current-error-port}のデフォルトとなります。

これらの手続きの値も@code{parameterize}で変えることができますが、
(1) @code{current-*-port}はプログラム実行前に初期化されるので、
プログラム中で@code{standard-*-port}を変更しても影響は及ばない、
(2) これらの手続きの値の変更はScheme世界だけのことで、低レベルライブラリが
参照しているシステムのstdioファイルディスクリプタは変更されない、
という点に注意してください。
@c COMMON
@end deffn

@defun with-input-from-port port thunk
@defunx with-output-to-port port thunk
@defunx with-error-to-port port thunk
@c EN
Calls @var{thunk}.  During evaluation of thunk, the current input port, current
output port and current error port are set to @var{port}, respectively.
Note that @var{port} won't be closed after thunk is executed.
@c JP
それぞれ入力、出力、エラーポートを@var{port}にセットした状態で@var{thunk}を呼び出します。
@code{port}は@var{thunk}実行後にも閉じられないことに注意してください。
@c COMMON
@end defun

@defun with-ports iport oport eport thunk
@c EN
Does the above three functions at once.
Calls @var{thunk} while the current input, output, and error ports are
set to @var{iport}, @var{oport}, and @var{eport}, respectively.
You may pass @code{#f} to any port argument(s) if you don't need
to alter the port(s).

Note that @var{port} won't be closed after thunk is executed.
(Unfortunately, recent Scheme standards added a similar
named procedure, @code{call-with-port},
which does close the port.  See below.)
@c JP
上の3つの動作を同時に行う手続きです。
入力、出力、エラーの各ポートをそれぞれ@var{iport}, @var{oport}, @var{eport}に
セットして@var{thunk}を呼び出します。変更する必要がないポートの引数には
@code{#f}を渡すことができます。

@code{port}は@var{thunk}実行後にも閉じられないことに注意してください
(最近のScheme標準は良く似た名前の手続き@code{call-with-port}を追加しましたが、
生憎そちらはポートを閉じる仕様になっています。@code{call-with-port}については
下で説明します。)
@c COMMON
@end defun

@defun close-port port
@defunx close-input-port port
@defunx close-output-port port
[R7RS base]
@c EN
Closes the port.  @code{Close-port} works both input and
output ports, while @code{close-input-port} and @code{close-output-port}
work only for the respective ports and throws an error if another type
of port is passed.

Theoretically, only @code{close-port} would suffice; having those three
is merely for historical reason.
R5RS has @code{close-input-port} and @code{close-output-port};
R6RS and R7RS support all three.
@c JP
ポートを閉じます。@code{close-port}は入力ポートも出力ポートも閉じられますが、
@code{close-input-port}と@code{close-output-port}はそれぞれ対応するポートのみに
使え、異なる種類のポートが渡されたらエラーを通知します。

理屈の上では、@code{close-port}だけあれば十分です。3つ手続きがあるのは歴史的理由です。
R5RSには@code{close-input-port} and @code{close-output-port}だけがありました。
R6RSとR7RSは3つ全てをサポートしています。
@c COMMON
@end defun


@defun call-with-port port proc
[R7RS base]
@c EN
Calls @var{proc} with one argument, @var{port}.  After @var{proc} returns,
or it throws an uncaptured error, @var{port} is closed.  Value(s) returned
from @var{proc} will be the return value(s) of @code{call-with-port}.

@c JP
@var{proc}を、@var{port}を引数として呼び出します。@var{proc}からリターンするか、
エラーが投げられた場合は@var{port}がクロースざれます。
@var{proc}が返す値がそのまま@code{call-with-port}の返り値となります。
@c COMMON
@end defun

@defun port-type port
@c EN
Returns the type of @var{port} in one of the symbols @code{file},
@code{string} or @code{proc}.
@c JP
@var{port}のタイプを、シンボル@code{file}、@code{string}、@code{proc}の
いずれかで返します。
@c COMMON
@end defun

@defun port-name port
@c EN
Returns the name of @var{port}.  If the port is associated to a file,
it is the name of the file.   Otherwise, it is some description of the port.
@c JP
@var{port}の名前を返します。ポートがファイルに関連付けられている場合は、ポートの名前は
ファイル名です。そうでない場合、ポートを説明する文字列が返されます。
@c COMMON
@end defun

@defun port-buffering port
@defunx {(setter port-buffering)} port buffering-mode
@c EN
If @var{port} is type of file port (i.e. @code{(port-type @var{port})}
returns @code{file}), these procedures gets and sets the port's
buffering mode.  For input ports, the port buffering mode may be
either one of @code{:full}, @code{:modest} or @code{:none}.
For output ports, @code{port-buffering}, it may be
one of @code{:full}, @code{:line} or @code{:none}.
@xref{File ports}, for explanation of those modes.

If @code{port-buffering} is applied to ports other than file ports,
it returns @code{#f}.  If the setter of port-buffering is
applied to ports other than file ports, it signals an error.
@c JP
ファイルポート(@code{(port-type @var{port})}が@code{file}を返すもの)
に対して、そのバッファリングモードを読みだし、もしくは変更します。
入力ポートではバッファリングモードは
@code{:full}、 @code{:modest}、@code{:none}のいずれかです。
出力ポートでは
@code{:full}、 @code{:line}、@code{:none}のいずれかです。
バッファリングモードの詳細な説明は、@ref{File ports} を参照してください。

@code{port-buffering}がファイルポート以外のポートに対して呼ばれた場合は
@code{#f}を返します。@code{port-buffering}のsetterが
ファイルポート以外のポートに対して呼ばれた場合はエラーとなります。
@c COMMON
@end defun

@defun port-link! input-port output-port
@defunx port-unlink! port
@c EN
An input port and an output port can be @emph{linked}.  After being
linked, attempt to read from @var{input-port} causes flushing
@var{output-port}'s buffer.  A port cannot be linked to more
than one port.
@c JP
入力ポートと出力ポートを@emph{リンク}することができます。
リンクされている入力ポートから読み出そうとすると、まず出力ポートのバッファが
フラッシュされます。ポートは2つ以上のポートとリンクすることはできません。
@c COMMON

@c EN
By default, standard input port is linked to standard output port.
@c JP
デフォルトでは、標準入力ポートと標準出力ポートがリンクされています。
@c COMMON

@c EN
The @code{port-link!} procedure links the given input port and
output port.  Both port must not be already linked, or an error
is signaled.
@c JP
@code{port-link!}は引数の入力ポートと出力ポートをリンクします。
どちらのポートもリンクされていない状態でなければなりません。
さもなくばエラーが投げられます。
@c COMMON

@c EN
The @code{port-unlink!} procedure removes the link between the given
port and another port, if there's a link.  If the given port
is not linked, it does nothing.
@c JP
@code{port-unlink!}は、与えられたポートが他のポートとリンクされていたら
そのリンクを解除します。リンクされていないポートが与えられた場合は何もしません。
@c COMMON

@c EN
You can use @code{link} slot of the port to see if a port is
linked or not, and if linked, to which port.
@c JP
ポートの@code{link}スロットを見れば、ポートがリンクされているか、
またされている場合はどのポートか、がわかります。
@c COMMON
@end defun


@defun port-current-line port
@c EN
Returns the current line count of @var{port}.  This information is
only available on file-based port, and as long as you're doing
sequential character I/O on it.  Otherwise, this returns -1.
@c JP
@var{port}の現在の行番号を返します。行番号は、ファイルに関連付けられたポートで
かつシーケンシャルなキャラクタI/Oを行っている場合のみ有効です。それ以外の場合は
-1を返します。
@c COMMON
@end defun

@defun port-file-number port :optional dup?
@c EN
Returns an integer file descriptor, if the @var{port} is associated
to the system file I/O.  Returns @code{#f} otherwise.

If a true value is passed to @var{dup?}, the procedure calls @code{dup(2)}
and returns a duplicated file descriptor.  In such case, the returned
file descriptor can be closed independently with the port, and it is
caller's responsibility to close it (by @code{sys-close}) once it's done.
@c JP
@var{port}がファイルに関連付けられている場合、そのファイルディスクリプタ番号を
返します。それ以外の場合は@code{#f}を返します。

@var{dup?}引数に真の値が与えられると、この手続きは@code{dup(2)}を呼んで
複製したファイルディスクリプタを返します。この場合、返されたファイルディスクリプタは
呼び出し側が責任を持って閉じなければなりません (@code{sys-close}が使えます)。
@c COMMON
@end defun

@defun port-position port
[SRFI-192]
@c EN
Returns the current position of @var{port}.  For the input port,
the current position is where the next data will be read from,
and for the output port, it is where the next data will be written to.
(Note that @code{peek-char}/@code{peek-byte} won't move the current position).

If @var{port} is a simple file port or a string port, the position is
represented as an integer byte offset from the top of the stream.
If it is more complicated ports, such as the one doing the character encoding
conversion, the port position may not be available, or returned
object may not correspond to the byte offset.
If @var{port} is a procedural (virtual) port (@pxref{Virtual ports}),
the returned value can
be an arbitrary Scheme object, it can only
be valid to be used for @code{set-port-position!}.

An error is thrown if @var{port} doesn't support port positions.
You can use @code{port-has-port-position?} to check if the port supports
port positions.

For portable code: SRFI-192 defines the following conditions.

@itemize @bullet
@item
Return value is an arbitrary Scheme object and you should treat it as an
opaque object.  In general, it is only
safe to pass it to the @code{set-port-position!} on the same port.
@item
If the port is a binary port and the returned position is a nonnegative
exact integer, it represents the byte offset of the position.
@end itemize
@c JP
@var{port}の現在の位置を返します。現在の位置とは、
入力ポートでは次の読み込みでデータが読まれる位置、
出力ポートでは次の書き込みでデータが書かれる位置です。
(@code{peek-char}/@code{peek-byte}では現在の位置は動きません)。

@var{port}が単純なファイルポートや文字列ポートなら、
ポートの位置はストリームの先頭からのバイトオフセットを表す正確な整数です。
より複雑なポート、例えば文字エンコーディング変換ポートでは、
ポート位置を取ることはできないか、取れた場合でもその値はバイトオフセットに対応するとは
限りません。
仮想ポート(@ref{Virtual ports}参照)では、現在位置は任意のSchemeオブジェクトで、
@code{set-port-position!}に渡す以外に使うことはできません。

@var{port}がポート位置をサポートしていなければエラーが投げられます。
ポート位置をサポートしているかどうかは@code{port-has-port-position?}で調べられます。

ポータブルなコードを書くときは、以下のSRFI-192の条件に気をつけてください。

@itemize @bullet
@item
ポート位置は任意のSchemeオブジェクトであり、
同じポートに対して@code{set-port-position!}するのにだけ使うことができます。
@item
ただし、ポートがバイナリポートで、位置が正確な非負整数の場合は、
それはバイトオフセットを表しています。
@end itemize
@c COMMON
@end defun

@defun port-has-port-position? port
[SRFI-192]
@c EN
Returns @code{#t} iff the port supports @code{port-position} procedure.
@c JP
ポートが@code{port-position}手続きをサポートしていれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun

@defun set-port-position! port pos
[SRFI-192]
@c EN
Sets the current position of @var{port} to @var{pos}.  For the input port,
the current position is where the next data will be read from,
and for the output port, it is where the next data will be written to.

Interpretation of @var{pos} is up to the @var{port},
and generally it  must be an object returned previously
by @code{port-position} on the same port.  If @var{port} is a simple
file port (a port opened on file, without CES conversion) or
an input string port, you may pass a nonnegative exact integer as the byte
offset.

An error is signaled if the position is not settable, or @var{pos} is
not acceptable as a position for @var{port}.  You can check if position
of @var{port} is settable by @code{port-has-set-port-position!?}.
@c JP
@var{pos}を@var{port}の現在の位置としてセットします。
現在の位置とは、
入力ポートでは次の読み込みでデータが読まれる位置、
出力ポートでは次の書き込みでデータが書かれる位置です。

@var{pos}の解釈は@var{port}に依存します。一般的には、
@var{port}に対する@code{port-position}で以前返されたオブジェクトしか渡せません。
ただし、@var{port}が単純なファイルポート(ファイルに対してオープンされ、
文字コード変換などを行っていないポート)や入力文字列ポートならば、
非負の正確な整数をバイトオフセットとして渡すことができます。

ポートが位置のセットを許さない場合や、@var{pos}が位置として不正な場合は
エラーが投げられます。@var{port}に位置がセットできるかどうかは
@code{port-has-set-port-position!?}で検査できます。
@c COMMON
@end defun

@defun port-has-set-port-position!? port
[SRFI-192]
@c EN
Returns @code{#t} iff the port supports @code{set-port-position!} procedure.
@c JP
ポートが@code{set-port-position!}手続きをサポートしていれば@code{#t}を、
そうでなければ@code{#f}を返します。
@c COMMON
@end defun


@defun port-seek port offset :optional whence
@c DEPRECATED
@c EN
Use @code{port-position} and @code{set-port-position!} for the new code.
@c JP
新しいコードには@code{port-position}および@code{set-port-position!}を使ってください。
@c COMMON

@c EN
If the given @var{port} allows random access, this procedure sets
the read/write pointer of the @var{port} according to the given @var{offset}
and @var{whence}, then returns the updated offset (number of bytes
from the beginning of the data).  If @var{port} is not random-accessible,
@code{#f} is returned.  In the current version, file ports and
input string ports are fully random-accessible.  You can only query
the current byte offset of output string ports.
@c JP
@var{port}がランダムアクセス可能なポートの場合、
この手続きは@var{port}のread/writeポインタを@var{offset}と@var{whence}の値によって
設定し、新たなread/writeポインタの値(データの先頭からのバイトオフセット)を
返します。@var{port}がランダムアクセス可能でない場合は@code{#f}が返されます。
現在のバージョンでは、ファイルポートおよび入力文字列ポートがランダムアクセス可能です。
出力文字列ポートは現在のポインタの値を問い合わせる動作だけが可能です。
@c COMMON

@c EN
Note that port position is represented by byte count, not character count.
@c JP
ポートのポインタはバイト数で表現され、文字数とは異なることに注意して下さい。
@c COMMON

@c EN
It is allowed to seek after the data if @var{port} is an output
file port.  See POSIX lseek(2) document for details of the behavior.
For input file port and input string port, you can't seek after the data.
@c JP
@var{port}が出力ファイルポートの場合は、データの終端を超えた位置までseek
することが可能です。その場合の動作はPOSIXのlseek(2)に準じます。
入力ファイルポートや入力文字列ポートではデータの終端以降にseekすることはできません。
@c COMMON

@c EN
The @var{whence} argument must be a small integer that represents
from where @var{offset} should be counted.   The following constant
values are defined.
@c JP
@var{whence}引数は、@var{offset}の基準を指定する小さな整数です。
以下の定数が定義されています。
@c COMMON

@table @code
@item SEEK_SET
@c EN
@var{Offset} represents the byte count from the beginning of the data.
This is the default behavior when @var{whence} is omitted.
@c JP
@var{offset}はデータ先頭からのバイト数を指定します。
@var{whence}が省略された場合のデフォルトの動作です。
@c COMMON

@item SEEK_CUR
@c EN
@var{Offset} represents the byte count relative to the current read/write
pointer.  If you pass 0 to @var{offset}, you can get the current
port position without changing it.
@c JP
@var{offset}は現在のread/writeポインタからの相対バイト数を指定します。
@var{offset}が0であれば、ポインタを動かさずに現在のポート位置を知ることができます。
@c COMMON

@item SEEK_END
@c EN
@var{Offset} represents the byte count relative to the end of the data.
@c JP
@var{offset}はデータの終端からの相対バイト数を指定します。
@c COMMON
@end table
@end defun

@defun port-tell port
@c DEPRECATED
@c EN
Use @code{port-position} insead in the new code.

Returns the current read/write pointer of @var{port} in byte count,
if @var{port} is random-accessible.   Returns @code{#f} otherwise.
This is equivalent to the following call:
@c JP
新しいコードでは@code{port-position}を使ってください。

@var{port}の現在のread/writeポインタの値をバイト数で返します。
@var{port}がランダムアクセス可能でない場合は@code{#f}が返されます。
これは以下の呼び出しと等価です。
@c COMMON
@example
(port-seek @var{port} 0 SEEK_CUR)
@end example
@end defun

@defun copy-port src dst :key (unit 0) (size #f)
@c EN
Copies data from an input port @var{src} to an output port @var{dst},
until eof is read from @var{src}.
@c JP
@var{src}からEOFまでデータを読みだし、@var{dst}へ書き出します。
@c COMMON

@c EN
The keyword argument @var{unit} may be zero, a positive exact integer,
a symbol @code{byte} or a symbol @code{char}, to specify the unit
of copying.  If it is an integer, a buffer of the size
(in case of zero, a system default size) is used to copy,
using block I/O.  Generally it is the fastest if you copy
between normal files.   If @var{unit} is a symbol @code{byte},
the copying is done byte by byte, using C-version of @code{read-byte}
and @code{write-byte}.  If @var{unit} is a symbol @code{char},
the copying is done character by character, using C-version of
@code{read-char} and @code{write-char}.
@c JP
キーワード引数@var{unit}は0以上の整数か、シンボル@code{byte}もしくは@code{char}
でなければなりません。これはデータをコピーする単位を指定します。
整数ならば、その大きさ(0の場合はシステム規定の大きさ)のバッファが確保され、
ブロックI/Oを使って転送が行われます。通常のファイルをコピーする場合などはこれが
速いでしょう。もし@var{unit}がシンボル@code{byte}であれば、バイト毎
に読みだし／書き込みが行われます。@var{unit}がシンボル@code{char}であれば、
キャラクタ毎に読みだし／書き込みが行われます。
@c COMMON

@c EN
If nonnegative integer is given to the keyword argument @var{size},
it specifies the maximum amount of data to be copied.  If @var{unit}
is a symbol @code{char}, @var{size} specifies the number of characters.
Otherwise, @var{size} specifies the number of bytes.
@c JP
キーワード引数@var{size}に非負の整数が与えられた場合、それはコピーされるデータの
最大量を指定します。@var{unit}がシンボル@code{char}の場合は@var{size}は
コピーされる文字数を、そうでない場合はバイト数を指定します。
@c COMMON

@c EN
Returns number of characters copied when @var{unit} is a symbol
@code{char}.  Otherwise, returns number of bytes copied.
@c JP
@var{unit}がシンボル@code{char}の場合はコピーされた文字数を返し、
そうでない場合はコピーされたバイト数を返します。
@c COMMON
@end defun

@node File ports, String ports, Common port operations, Input and output
@subsection File ports
@c NODE ファイルポート

@menu
* Opening file ports::
* Character encoding of file I/O::
* File descriptor ports::
@end menu

@node Opening file ports, Character encoding of file I/O, File ports, File ports
@subsubsection Opening file ports
@c NODE ファイルポートのオープン

@defun open-input-file filename :key if-does-not-exist buffering element-type encoding conversion-buffer-size conversion-illegal-output
@defunx open-output-file filename :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size conversion-illegal-output
[R7RS+ file]
@c EN
Opens a file @var{filename} for input or output, and
returns an input or output port associated with it, respectively.

The keyword arguments specify precise behavior.
@c JP
ファイル@var{filename}を入力または出力用にオープンし、
入力ポートまたは出力ポートを作成して返します。

キーワード引数により、動作を細かく指定できます。
@c COMMON

@table @code
@item :if-exists
@c EN
This keyword argument can be specified only for @code{open-output-file}, and
specifies the action when the @var{filename} already exists.
One of the following value can be given.
@c JP
このキーワード引数は@code{open-output-file}のみに指定でき、
@var{filename}が既に存在した場合の動作を指定します。次の値のいずれかを与えることができます。
@c COMMON
@table @code
@item :supersede
@c EN
The existing file is truncated.  This is the default behavior.
@c JP
既存のファイルが長さ0に縮められます。これが既定の動作です。
@c COMMON
@item :append
@c EN
The output data will be appended to the existing file.
@c JP
既存のファイルにこれから書き出す内容が追加されます。
@c COMMON
@item :overwrite
@c EN
The output data will overwrite the existing content.
If the output data is shorter than the existing file, the rest of
existing file remains.
@c JP
既存のファイルにこれから書き出す内容が上書きされます。
書き出されるデータが既存のファイルのデータよりも短い場合、
残りの部分はそのまま残されます。
@c COMMON
@item :error
@c EN
An error is signaled.
@c JP
エラーが報告されます。
@c COMMON
@item #f
@c EN
No action is taken, and the function returns @code{#f}.
@c JP
何もせず、@code{#f}を返します。
@c COMMON
@end table

@item :if-does-not-exist
@c EN
This keyword argument specifies the action when @var{filename} does not exist.
@c JP
このキーワード引数は@var{filename}が存在しない場合の動作を指定します。
@c COMMON
@table @code
@item :error
@c EN
An error is signaled.  This is the default behavior of
@code{open-input-file}.
@c JP
エラーを報告します。これが@code{open-input-file}の既定の動作です。
@c COMMON
@item :create
@c EN
A file is created.  This is the default behavior of @code{open-output-file}.
The check of file existence and creation is done atomically; you can
exclusively create the file by specifying @code{:error} or @code{#f} to
@var{if-exists}, along this option.
You can't specify this value for @code{open-input-file}.
@c JP
ファイルが作成されます。これが@code{open-output-file}の既定の動作です。
ファイルの存在のチェックと作成はアトミックに行われます。
このオプションに加え、@var{if-exists}オプションに@code{:error}か@code{#f}を
指定することで、排他的にファイルを作成することができます。
@code{open-input-file}に対してはこの値を指定することはできません。
@c COMMON
@item #f
@c EN
No action is taken, and the function returns @code{#f}.
@c JP
何もせず、@code{#f}を返します。
@c COMMON
@end table

@item :buffering
@c EN
This argument specifies the buffering mode.  The following values are
allowed.
The port's buffering mode can be get/set by @code{port-buffering}.
(@pxref{Common port operations}).
@c JP
この引数はバッファリングモードを指定します。以下の値が設定できます。
ポートのバッファリングモードは手続き@code{port-buffering}
(@ref{Common port operations}参照)によって
読みだし/変更可能です。
@c COMMON
@table @code
@item :full
@c EN
Buffer the data as much as possible.  This is the default mode.
@c JP
出来る限りデータをバッファリングします。これがデフォルトのモードです。
@c COMMON
@item :none
@c EN
No buffering is done.  Every time the data is written (to an output port)
or read (from an input port), the underlying system call is used.
Process's standard error port is opened in this mode by default.
@c JP
バッファリングを行いません。出力ポートにデータが書き出されるか、
入力ポートからデータが読み込まれる度に、下位にあるシステムコールが呼ばれます。
プロセスの標準エラーポートはこのモードでオープンされています。
@c COMMON
@item :line
@c EN
This is valid only for output ports.  The written data is buffered, but
the buffer is flushed whenever a newline character is written.
This is suitable for interactive output port.  Process's standard
output port is opened in this mode by default.
@c JP
このモードは出力ポートにのみ有効です。書き出されたデータはバッファに
貯められますが、改行文字が書かれたらフラッシュされます。
このモードは対話的な出力ポートなどに便利です。
プロセスの標準出力ポートはこのモードでオープンされています。
@c COMMON
@item :modest
@c EN
This is valid only for input ports.  This is almost the same as the mode
@code{:full}, except that @code{read-uvector} may return less data
than requested if the requested amount of data is not immediately available.
(In the @code{:full} mode, @code{read-uvector} waits the entire data to be
read).   This is suitable for the port connected to a pipe or network.
@c JP
このモードは入力ポートにのみ有効です。ほとんど@code{:full}バッファリングモードと
同じですが、@code{read-uvector}はポートに要求されたデータより少ないデータしか
無かった場合、要求された量がたまるまで待つのではなく、今あるデータだけを
返します(@code{:full}の場合は@code{read-uvector}はすべてのデータが到着するまで
待ちます)。このモードはポートがパイプやネットワークに接続されている場合に
便利です。
@c COMMON
@end table

@item :element-type
@c EN
This argument specifies the type of the file.
@c JP
この引数はファイルのタイプを指定します。
@c COMMON
@table @code
@item :binary
@c EN
The file is opened in "binary" mode. (This is the default)
@c JP
ファイルはバイナリモードでオープンされます。(これがデフォルトです。)
@c COMMON
@item :character
@c EN
The file is opened in "character" (or "text") mode.
@c JP
ファイルはキャラクタモード(テキストモード)でオープンされます。
@c COMMON
@end table
@c EN
Note: This flag makes difference only on Windows-native platforms,
and only affect the treatment of line terminators.  In character
mode, writing @code{#\newline} on the output causes CR + LF characters to be
written, instead of just LF.  And reading CR + LF sequence returns
just @code{#\newline}.

On Unix, both mode are the same.

Note that Gauche doesn't distinguish character (textual) port and
binary port.  So this flag really matters only on Windows line
terminators.
@c JP
註: このフラグで違いが出るのはWindowsネイティブ版のみです。
キャラクタモードでは、@code{#\newline}文字をを出力するとCR + LFが書き出され、
またCR + LFシーケンスは単一の@code{#\newline}として読まれます。

Unixでは両者に違いはありません。

なお、Gaucheにはテキストポートとバイナリポートの区別はありません。
したがってこのフラグはWindowsの行終端文字の扱いのみのためにあります。
@c COMMON

@item :encoding
@c EN
This argument specifies character encoding of the file.   The argument
is a string or a symbol that names a character encoding scheme (CES).

For @code{open-input-file}, it can be a wildcard CES (e.g. @code{*jp})
to guess the file's encoding heuristically
(@pxref{Autodetecting the encoding scheme}),
or @code{#t}, in which case we assume the input file itself has magic
encoding comment and use @code{open-coding-aware-port}
(@pxref{Coding-aware ports}).

If this argument is given, Gauche automatically loads
@code{gauche.charconv} module and converts the input/output characters
as you read to or write from the port.
See @ref{Supported character encoding schemes}, for the details of
character encoding schemes.

If this argument is omitted, the value of the parameter
@code{default-file-encoding} is assumed for the file's character encoding
(@pxref{Character encoding of file I/O}).
@c JP
この引数はファイルの文字エンコーディングを指定します。引数は文字列かシンボルで、
文字エンコーディングスキーム(CES)の名前を渡します。

@code{open-input-file}では、ここにワイルドカードCES (例: @code{*jp}) を
渡して、入力ファイルのエンコーディングを推測させることもできます
(@ref{Autodetecting the encoding scheme}参照)。
また、ここに@code{#t}を渡すと、入力ポートはCoding aware portでラップされます
(@ref{Coding-aware ports}参照)。入力ファイルがエンコーディング指定の
マジックコメントを持っていることが期待できる場合に便利です。

この引数が与えられた場合、Gaucheは自動的に@code{gauche.charconv}モジュールを
ロードし、ポートの入出力時に文字コード変換を行います。
CESについて詳しくは@ref{Supported character encoding schemes}を参照してください。

この引数が省略された場合は、パラメータ@code{default-file-encoding}
の値が指定されたものとみなされます (@ref{Character encoding of file I/O}参照)。
@c COMMON

@item :conversion-buffer-size
@c EN
This argument may be used with the @var{encoding} argument to specify
the buffer size of character encoding conversion.  It is passed as
a @var{buffer-size} argument of the conversion port constructors
(@pxref{Conversion ports}).

Usually you don't need to give this argument; but if you need to guess
the input file encoding, larger buffer size may work better since guessing
routine can have more data before deciding the encoding.
@c JP
この引数は、文字エンコーディング変換に使うバッファサイズを指定するために
@var{encoding}引数と共に使うことができます。渡された値はそのまま
文字コード変換ポートのコンストラクタの@var{buffer-size}引数に渡されます
(@ref{Conversion ports}参照)。

この引数を指定する必要は滅多にありませんが、入力ファイルの文字エンコーディングを
推測しなければならない場合、大きめのバッファサイズの方が精度が上がります。
推測ルーチンがより多くのデータを見て文字エンコーディングを決定できるからです。
@c COMMON

@item :conversion-illegal-output
@c EN
This argument may be used with the @var{encoding} argument to specify
the behavior when the source character can't be mapped to the destination
character.  It must be either a symbol @code{raise} or a symbol
@code{replace}, and is passed as @var{illegal-output} argument to the
conversion port.  @xref{Conversion ports}, for the details.
@c JP
この引数は@var{encode}引数と一緒に使うことで、
文字エンコーディング変換において、元の文字に対応する文字が変換先に無い場合の振る舞いを
指定できます。値はシンボル@code{raise}か@code{replace}でなければならず、
それはそのまま変換ポートの@var{illegal-output}引数に渡されます。
詳しくは@ref{Conversion ports}を参照してください。
@c COMMON
@end table

@c EN
By combination of @var{if-exists} and @var{if-does-not-exist} flags,
you can implement various actions:
@example
(open-output-file "foo" :if-exists :error)
 @result{} ;@r{opens "foo" exclusively, or error}

(open-output-file "foo" :if-exists #f)
 @result{} ;@r{opens "foo" exclusively, or returns} #f

(open-output-file "foo" :if-exists :append
                        :if-does-not-exist :error)
 @result{} ;@r{opens "foo" for append only if it already exists}
@end example
@c JP
@var{if-exists}と@var{if-does-not-exist}フラグの組合せにより、
色々な動作を実現できます。
@example
(open-output-file "foo" :if-exists :error)
 @result{} ;@r{"foo"を排他的にオープンするかエラーを報告する}

(open-output-file "foo" :if-exists #f)
 @result{} ;@r{"foo"を排他的にオープンするか}#f@r{を返す}

(open-output-file "foo" :if-exists :append
                        :if-does-not-exist :error)
 @result{} ;@r{"foo"が既に存在する場合に限り、それを追加モードでオープン}
@end example
@c COMMON

@c EN
To check the existence of a file without opening it,
use @code{sys-access} or @code{file-exists?} (@pxref{File stats}).
@c JP
ファイルをオープンせずにその存在をチェックするには、
@code{sys-access}か@code{file-exists?}を使って下さい (@ref{File stats}参照)。
@c COMMON

@c EN
Note for portability: Some Scheme implementations (e.g. STk) allows
you to specify a command to @var{filename} and reads from, or
writes to, the subprocess standard input/output.  Some other scripting
languages (e.g. Perl) have similar features.  In Gauche,
@code{open-input-file} and @code{open-output-file} strictly operates
on files (what the underlying OS thinks as files).
However, you can use ``process ports'' to invoke
other command in a subprocess and to communicate it.
@xref{Process ports}, for details.
@c JP
移植性に関する註：Schemeシステムによっては、@var{filename}のところに
シェルコマンドを指定して、サブプロセスの標準入出力と通信できるようにするものが
あります。他のスクリプティング言語(例：Perl)にも同様の機能があります。
Gaucheでは、@code{open-input-file}と@code{open-output-file}は
あくまでファイル (OSがファイルとして扱うもの) のみに対して使えます。
サブプロセスと通信するためには、「プロセスポート」という機能が提供されています。
@ref{Process ports}を参照して下さい。
@c COMMON
@end defun

@defun call-with-input-file string proc :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx call-with-output-file string proc :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R7RS+ file]
@c EN
Opens a file specified by @var{string} for input/output,
and call @var{proc} with one argument, the file port.  When @var{proc}
returns, or an error is signaled from @var{proc} that is not captured
within @var{proc}, the file is closed.
@c JP
@var{string}で示されるファイルを入力または出力用にオープンし、
作成されたポートを引数として手続き@var{proc}を呼び出します。
@var{proc}が正常終了するか、@var{proc}内で捕捉されないエラーが起きた場合に
ファイルはクローズされます。
@c COMMON

@c EN
The keyword arguments have the same meanings of
@code{open-input-file} and @code{open-output-file}'s.  Note that
if you specify @code{#f} to @var{if-exists} and/or @var{if-does-not-exist},
@var{proc} may receive @code{#f} instead of a port object when
the file is not opened.
@c JP
キーワード引数は
@code{open-input-file}及び@code{open-output-file}のものと同じ意味を持ちます。
@var{if-exists}や@var{if-does-not-exist}に@code{#f}を指定した場合、
ファイルがオープンされなかった場合は@var{proc}にポートではなく@code{#f}が渡される
ことに注意して下さい。
@c COMMON

@c EN
Returns the value(s) @code{proc} returned.
@c JP
@var{proc}が返す値を返します。
@c COMMON
@end defun

@defun with-input-from-file string thunk :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx with-output-to-file string thunk :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R7RS file]
@c EN
Opens a file specified by @var{string} for input or output
and makes the opened port as the current input or output port,
then calls @var{thunk}.  The file is closed when @var{thunk}
returns or an error is signaled from @var{thunk} that is not
captured within @var{thunk}.

Returns the value(s) @code{thunk} returns.

The keyword arguments have the same
meanings of @code{open-input-file} and @code{open-output-file}'s,
except that when @code{#f} is given to @var{if-exists} and
@var{if-does-not-exist} and the opening port is failed,
@var{thunk} isn't called at all and @code{#f} is returned
as the result of @code{with-input-from-file} and
@code{with-output-to-file}.
@c JP
@var{string}で示されるファイルを入力または出力用にオープンし、オープンされた
ポートを現在の入力または出力ポートに設定して、@var{thunk}を呼び出します。
@var{thunk}が戻るか、@var{thunk}内で捕捉されないエラーが生じた際にファイルは閉じられます。

@var{thunk}が返す値を返します。

キーワード引数は
@code{open-input-file}及び@code{open-output-file}のものと同じ意味を持ちます。
但し@var{if-exists}や@var{if-does-not-exist}に@code{#f}が指定され、
ファイルがオープンできなかった場合は、@var{thunk}は呼ばれずに
直ちに@code{#f}が返されます。
@c COMMON
@end defun

@c EN
@emph{Notes on semantics of closing file ports:}
R7RS states, in the description of @code{call-with-port} et al.,
that @emph{"If @emph{proc} does not return, then the port will
not be closed automatically unless it is possible
to prove that the port will never again be used for read or write
operation."}
@c JP
@emph{ポートを閉じるセマンティクスについて:}
R7RSは@code{call-with-port}等の説明において、次のように述べています。
「@emph{procが戻って来なかった場合、今後ポートが読み書きに一切使われないことが
証明できない限りは、ポートは自動的には閉じられない}」。
@c COMMON

@c EN
Gauche's implementation slightly misses this criteria; the mere fact
that an uncaptured error is thrown in @var{proc} does not prove
the port will never be used.  Nevertheless, it is very difficult
to think the situation that you can do meaningful operation on
the port after such an error is signaled; you'd have no idea
what kind of state the port is in.  In practical programs, you
should capture error explicitly inside @var{proc} if you still want
to do some meaningful operation with the port.
@c JP
Gaucheの実装は若干この条件には反しています。捕捉されないエラーが@var{proc}から
発せられたというだけでは、そのポートが今後一切使われないかどうかはわかりません。
しかし実際には、そのようなエラーが発せられた後でポートに対して意味のある操作をするのは
非現実的です。ポートがどのような状態にあるかわからないわけですから。
現実的なプログラムでは、ポートに対して意味のある操作をしつづけたいのなら、
@var{proc}の中で明示的にエラーをハンドルすべきでしょう。
@c COMMON

@c EN
Note that if a continuation captured outside @code{call-with-input-file}
et al. is invoked inside @var{proc}, the port is not closed.
It is possible that the control returns later into the @var{proc},
if a continuation is captured in it (e.g. coroutines).
The low-level exceptions (@pxref{Low-level exception handling mechanism})
also doesn't ensure closing the port.
@c JP
@code{call-with-input-file}の外で捕捉された継続を@var{proc}内で呼んだ場合には
ポートは閉じられないことに注意して下さい。後で@var{proc}へと制御が戻ってくるかも
しれないからです (コルーチン等)。また、
低レベルの例外メカニズム(@ref{Low-level exception handling mechanism}
参照)を利用した場合、エラー時にポートを閉じるのはプログラマの責任になります。
@c COMMON

@node Character encoding of file I/O, File descriptor ports, Opening file ports, File ports
@subsubsection Character encoding of file I/O
@c NODE ファイルI/Oにおける文字エンコーディング

@deffn {Parameter} default-file-encoding
@c EN
A character encoding name assumed when you omit @var{encoding}
keyword arguments in file port opening procedures, such as
@code{open-input-port}, @code{call-with-output-file}, etc.
The default value is @code{utf-8}.
@c JP
ファイルポートをオープンする、@code{open-input-port}や@code{call-with-output-file}
等の手続きに@var{encoding}キーワード引数を指定しなかった場合、
このパラメータの値が文字エンコーディング名として使われます。
デフォルトの値は@code{utf-8}です。
@c COMMON

@c EN
In most circumstances, you don't need to change the value of this parameter.
These days, utf-8 became de facto in data exchange, so
you need to specify @var{encoding} argument explicitly only when you know
you're dealing with non-utf8 data.
@c JP
ほとんどの場合、このパラメータの値を変える必要はないでしょう。
データ交換にはutf-8がデファクトとなった現代では、utf8でないデータを
扱う時のみ@var{encoding}を指定するだけで事足ります。
@c COMMON

@c EN
However, suppose you have exising system that assumes, say, latin-1 encoding,
and you've been using Gauche with @code{none} CES encoding (which means
Gauche just treats an octet as a character).
Gauche uses utf-8 exclusively in its internal encoding since 0.9.14,
and if you switch to it, you would need to check every file opening
calls to make sure they have @code{:encoding latin-1}.  That would be a lot
of work.
@c JP
ただ、例えばこれまでGaucheの内部エンコーディングを@code{none}でコンパイルしていて
(これはGaucheが文字を8ビット固定長で扱うことを意味します)、システムがLatin-1エンコーディング
でデータを扱っていたとしましょう。
Gaucheは0.9.14から内部エンコーディングをutf-8のみにしたので、
バージョンを上げる際に、
全てのファイルオープン手続きを調べて@code{:encoding latin-1}をつけて回らないとなりません。
それはかなり大きな変更となるでしょう。
@c COMMON

@c EN
You can change this parameter to @code{latin-1} instead, and the exiting
calls work as if @code{:encoding latin-1} is attached unless it already
has explicit @code{:encoding}.
@c JP
そういう場合には、このパラメータを@code{latin1}にセットすることで、
これまで@code{:encoding}がついていなかったファイルオープン手続きを
あたかも@code{:encoding latin-1}が付加されているかのように振る舞わせることができます。
@c COMMON

@c EN
Note that source code is loaded using coding aware ports
(@pxref{Coding-aware ports}), with the default encoding being
Gauche's native encoding.  The value of this parameter doesn't have
effect.  Use encoding magic comment to specify the encoding of
source code.
@c JP
ソースコードをloadする場合は、内部エンコーディングをデフォルトとする
コーディング認識ポートが使われることに注意してください (@ref{Coding-aware ports}参照)。
内部エンコーディングとソースエンコーディングが異なる場合は、
文字エンコーディングを指定するマジックコメント@code{coding:coding-name}を使ってください。
@c COMMON
@end deffn


@node File descriptor ports,  , Character encoding of file I/O, File ports
@subsubsection File descriptor ports
@c NODE ファイルディスクリプタポート

@defun open-input-fd-port fd :key buffering name owner?
@defunx open-output-fd-port fd :key buffering name owner?
@c EN
Creates and returns an input or output port on top of the given
file descriptor.  @var{Buffering} specifies the buffering mode
as described in @code{open-input-file} entry above; the default
is @code{:full}.  @var{Name} is used for the created port's name
and returned by @code{port-name}.

A boolean flag @code{owner?} specifies whether @var{fd} should be
closed when the port is closed.  If it is @code{#f}, closing port
doesn't close @var{fd}.  If it s @code{#t}, closing port automatically
closes @code{fd}.  It can also be a symbol @code{dup}, in which case
@code{fd} is duplicated (by @code{dup(2)} system call) and the
resulting port owns the new fd which will be closed automatically--but
@var{fd} itself remains open, and can be closed independently.
@c JP
与えられたファイルディスクリプタにアクセスする入力または出力ポートを
作成して返します。@var{buffering} は@code{open-input-file} の項で
説明されたポートのバッファリングモードを指定します。デフォルトは@code{:full}です。
@var{name}は@code{port-name}によって返されるポートの名前を指定します。

@var{owner?} は、このポートを閉じた時に@var{fd}もクローズすべきかどうかを
指定します。@code{#f}ならポートを閉じても@var{fd}はそのままです。
@code{#t}ならポートを閉じた時に@var{fd}も自動的に閉じられます。
また、シンボル@code{dup}を渡すこともできて、その場合は内部で@var{fd}が
@code{dup(2)}システムコールによって複製され、新しいfdをポートが所有します。
新たなfdはポートが閉じると自動的に閉じられますが、@var{fd}自体は閉じられません。
また、@var{fd}をポートとは独立して閉じることができます。
@c COMMON
@end defun

@defun port-fd-dup! toport fromport
@c EN
Interface to the system call @code{dup2(2)}.
Atomically closes the file descriptor associated to @var{toport},
creates a copy of the file descriptor associated to @var{fromport},
and sets the new file descriptor to @var{toport}.
Both @var{toport} and @var{fromport} must be file ports.
Before the original file descriptor of @var{toport} is closed,
any buffered output (when @var{toport} is an output port) is flushed,
and any buffered input (when @var{toport} is an input port) is discarded.

`Copy' means that, even the two file descriptors differ in their values,
they both point to the same system's open file table entry.  For example
they share the current file position; after @var{port-fd-dup!},
if you call @code{port-seek} on @var{fromport}, the change is also visible
from @var{toport}, and vice versa.  Note that this 'sharing' is in the
system-level; if either @var{toport} or @var{fromport} is buffered,
the buffered contents are not shared.

This procedure is mainly intended for programs that needs to control
open file descriptors explicitly; e.g. a daemon process would want to redirect
its I/O to a harmless device such as @file{/dev/null}, and a shell process
would want to set up file descriptors before executing the child process.
@c JP
システムの@code{dup2(2)}のインタフェースです。
アトミックに@var{toport}のファイルディスクリプタをクローズし、@var{fromport}の
ファイルディスクリプタを複製したものを@var{toport}に設定します。
@var{toport}、@var{fromport}はいずれもファイルポートでなければなりません。

ファイルディスクリプタが「複製」されると、ふたつのディスクリプタ番号が異なっていても
それらはシステムのオープンファイルテーブルの同じエントリを指します。
例えば、現在の(システムレベルでの)ファイル上の読み書き位置は共有されます。
@code{port-fd-dup!}の後で、@code{port-seek}を@var{fromport}に
対して呼び出せば、その変更は@var{toport}の読み書き位置にも影響を与えるでしょうし、
その逆もまたあります。ただし、共有されるのはシステムレベルの情報のみで、
@var{toport}や@var{fromport}がバッファリングされている場合、バッファの内容は
共有されません。

この手続きは、主にファイルディスクリプタを明示的に制御する必要のあるプログラム
のために用意されています。例えばデーモンプロセスがその入出力を@file{/dev/null}などの
無難なデバイスに切り替えたり、シェルプロセスが子プロセスを@code{exec}する前に
そのファイルディスクリプタをセットアップしたりするような場合です。
@c COMMON
@end defun

@node String ports, Coding-aware ports, File ports, Input and output
@subsection String ports
@c NODE 文字列ポート

@c EN
String ports are the ports that you can read from or write to
memory.
@c JP
文字列ポートは、メモリ上のデータと関連付けられたポートです。
@c COMMON

@defun open-input-string string :key name
[R7RS base][SRFI-6]
@c EN
Creates an input string port that has the content @var{string}.
This is a more efficient way to access a string in order
rather than using @code{string-ref} with incremental index.

@example
(define p (open-input-string "foo x"))
(read p) @result{} foo
(read-char p) @result{} #\space
(read-char p) @result{} #\x
(read-char p) @result{} #<eof>
(read-char p) @result{} #<eof>
@end example
@c JP
@var{string}を内容とする入力文字列ポートを作って返します。
文字列に逐次的にアクセスする場合、インデックスをインクリメントしながら
@code{string-ref}を呼び出すより効率の良い方法です。
@example
(define p (open-input-string "文字 列"))
(read p) @result{} 文字
(read-char p) @result{} #\space
(read-char p) @result{} #\列
(read-char p) @result{} #<eof>
(read-char p) @result{} #<eof>
@end example
@c COMMON

@c EN
The @var{name} keyword argument is a Gauche extension.
By default, the created port is named as @code{(input string port)}.
It is mainly used for debugging.  You can specify alternative name with
this argument.
As Gauche's convention, file ports has the source file path as its name,
so port names for debugging information should be parenthesized
not to be taken as pathnames.
@c JP
@var{name}キーワード引数はGaucheの拡張です。
デフォルトでは、作られるポートの名前は@code{(input string port)}になります。
ポートの名前は主にデバッグのために使われます。この引数で代わりの名前を指定できます。
Gaucheの慣習として、ファイルポートは元ファイルのパス名を名前に持つので、
ポート名にデバッグ用途の情報を載せる場合はパス名と区別しやすいよう括弧に入れるのが良いでしょう。
@c COMMON

@example
gosh> (open-input-string "")
#<iport (input string port) 0x215c0c0>
gosh> (open-input-string "" :name "(user input)")
#<iport (user input) 0x22a4e40>
@end example
@end defun

@defun get-remaining-input-string port
@c EN
@var{Port} must be an input string port.
Returns the remaining content of the input port.
The internal pointer of @var{port} isn't moved, so the
subsequent read from @var{port} isn't affected.
If @var{port} has already reached to EOF, a null string is returned.
@c JP
@var{port}は入力文字列ポートでなければなりません。
入力ポートに残っている文字列を返します。
@var{port}の内部ポインタは動かされないので、@var{port}に対するreadは
影響を受けません。@var{port}が既にEOFに達していた場合は、空文字列が返されます。
@c COMMON

@example
(define p (open-input-string "abc\ndef"))
(read-line p)                  @result{} "abc"
(get-remaining-input-string p) @result{} "def"
(read-char p)                  @result{} #\d
(read-line p)                  @result{} "ef"
(get-remaining-input-string p) @result{} ""
@end example
@end defun


@defun open-output-string :key name
[R7RS base][SRFI-6]
@c EN
Creates an output string port.   Anything written to the
port is accumulated in the buffer, and can be obtained
as a string by @code{get-output-string}.
This is a far more efficient way to construct a string
sequentially than pre-allocate a string and fill it with
@code{string-set!}.
@c JP
出力文字列ポートを作成して返します。このポートに書き出された文字列は
内部のバッファにたくわえられ、@code{get-output-string} で取り出すことが
できます。
これは、順番に文字列を構成する方法として、あらかじめ文字列をアロケートして
@code{string-set!}で埋めて行くよりもずっと効率の良い方法です。
@c COMMON

@c EN
The @var{name} keyword argument is a Gauche extension.
By default, the created port is named as @code{(output string port)}.
It is mainly used for debugging.  You can specify alternative name with
this argument.
As Gauche's convention, file ports has the source file path as its name,
so port names for debugging information should be parenthesized
not to be taken as pathnames.
@c JP
@var{name}キーワード引数はGaucheの拡張です。
デフォルトでは、作られるポートの名前は@code{(output string port)}になります。
ポートの名前は主にデバッグのために使われます。この引数で代わりの名前を指定できます。
Gaucheの慣習として、ファイルポートは元ファイルのパス名を名前に持つので、
ポート名にデバッグ用途の情報を載せる場合はパス名と区別しやすいよう括弧に入れるのが良いでしょう。
@c COMMON

@example
gosh> (open-output-string)
#<oport (output string port) 0x22a4c00>
gosh> (open-output-string :name "(temporary output)")
#<oport (temporary output) 0x22a49c0>
@end example
@end defun

@defun get-output-string port
[R7RS base][SRFI-6]
@c EN
Takes an output string port @code{port} and returns a string
that has been accumulated to @code{port} so far.
If a byte data has been written to the port, this function
re-scans the buffer to see if it can consist a complete string;
if not, an incomplete string is returned.
@c JP
出力文字列ポート@code{port}を取り、それまでそのポートに蓄積された
文字列を返します。バイトデータがそのポートに書き出されていた場合、
この手続きはまず内部バッファをスキャンし、結果が完全な文字列で表現できるかどうかを
調べます。もし表現できなければ、不完全な文字列が返されます。
@c COMMON

@c EN
This doesn't affect the @var{port}'s operation, so you can keep
accumulating content to @var{port} after calling @code{get-output-string}.
@c JP
これは@var{port}の操作には影響をあたえません。@code{get-output-string}を
呼んだ後でも、@var{port}に内容を蓄積しつづけることができます。
@c COMMON
@end defun

@defun call-with-input-string string proc
@defunx call-with-output-string proc
@defunx with-input-from-string string thunk
@defunx with-output-to-string thunk
@c EN
These utility functions are trivially defined as follows.
The interface is parallel to the file port version.
@c JP
これらのユーティリティ関数は次に定義されるような動作をします。
インタフェースはファイルポートを扱う類似の関数と揃えてあります。
@c COMMON
@example
(define (call-with-output-string proc)
  (let ((out (open-output-string)))
    (proc out)
    (get-output-string out)))

(define (call-with-input-string str proc)
  (let ((in (open-input-string str)))
    (proc in)))

(define (with-output-to-string thunk)
  (let ((out (open-output-string)))
    (with-output-to-port out thunk)
    (get-output-string out)))

(define (with-input-from-string str thunk)
  (with-input-from-port (open-input-string str) thunk))
@end example
@end defun

@defun call-with-string-io str proc
@defunx with-string-io str thunk
@example
(define (call-with-string-io str proc)
  (let ((out (open-output-string))
        (in  (open-input-string str)))
    (proc in out)
    (get-output-string out)))

(define (with-string-io str thunk)
  (with-output-to-string
    (lambda ()
      (with-input-from-string str
        thunk))))
@end example
@end defun

@defun write-to-string obj :optional writer
@defunx read-from-string string :optional start end
@c EN
These convenience functions cover common idioms using string ports.
@example
(write-to-string obj writer)
  @equiv{}
  (with-output-to-string (lambda () (writer obj)))

(read-from-string string)
  @equiv{}
  (with-input-from-string string read)
@end example
The default value of @var{writer} is the procedure @code{write}.
The default values of @var{start} and @var{end} is 0 and
the length of @var{string}.

Portability note: Common Lisp has these functions, with
different optional arguments.
STk has @code{read-from-string} without optional argument.
@c JP
文字列ポートを使う定型句をユーティリティ関数にしました。
@example
(write-to-string obj writer)
  @equiv{}
  (with-output-to-string (lambda () (writer obj)))

(read-from-string string)
  @equiv{}
  (with-input-from-string string read)
@end example
@var{writer}の既定値は@code{write}です。@var{start}, @var{end}は
省略されればそれぞれ0と文字列の長さになります。

移植性への註：Common Lispに同名の関数があります。必須引数の動作は同じですが、
省略可能な引数は異なります。
STkには@code{read-from-string}がありますが、省略可能な引数は取りません。
@c COMMON
@end defun

@node Coding-aware ports, Input, String ports, Input and output
@subsection Coding-aware ports
@c NODE コーディング認識ポート

@c EN
A coding-aware port is a special type of procedural input port that
is used by @code{load} to read a program source.  The port recognizes
the magic comment to specify the character encoding of the
program source, such as @code{;; -*- coding: utf-8 -*-}, and makes
an appropriate character encoding conversion.
See @ref{Multibyte scripts} for the details of coding magic comment.
@c JP
コーディング認識ポートは特殊な手続的入力ポートで、@code{load}が
プログラムソースコードを読む際に使われています。このポートは
@code{;; -*- coding: utf-8 -*-}のような、プログラムソースの
文字エンコーディングを指定する特殊なコメントを認識し、適切な
文字エンコーディング変換を行います。
特殊なコメントでソースの文字エンコーディングを指定することについては、
@ref{Multibyte scripts}を参照して下さい。
@c COMMON

@defun open-coding-aware-port iport
@c EN
Takes an input port and returns an input coding aware port,
which basically just pass through the data from @var{iport} to
its reader.  However, if a magic comment appears within the
first two lines of data from @var{iport}, the coding aware port
applies the necessary character encoding conversion to the rest of the
data as they are read.
@c JP
入力ポートを引数としてとりコーディング認識入力ポートを返します。
基本的には @var{iport} からの入力データをリーダにわたしているだけです。
しかし、@var{iport} からの入力データの最初の2行以内に、特別なマジックコメント
が現れた場合、コーディング認識ポートは、その後に読み込まれるデータについて
必要な文字エンコーディング変換を行います。
@c COMMON

@c EN
The passed port, @var{iport}, is "owned" by the created coding-aware
port.  That is, when the coding-aware port is closed, @var{iport} is
also closed.  The content read from @var{iport} is buffered in the
coding-aware port, so other code shouldn't read from @var{iport}.
@c JP
引数として渡されたポート、@var{iport} は生成されたコーディング認識
ポートによって所有されます。つまり、コーディング認識ポートがクローズ
されると、@var{iport} もクローズされます。@var{iport} から読み込まれた
内容はコーディング認識ポート内でバッファリングされます。したがって、
別のコードで @var{iport} から読み出しを行うべきではありません。
@c COMMON

@c EN
By default, Gauche's @code{load} uses a coding aware port to read
the program source, so that the coding magic comment works for
the Gauche source programs (see @ref{Loading Scheme file}).
However, since the mechanism itself
is independent from @code{load}, you can use this port for
other purposes; it is particularly useful to write a function
that processes Scheme source programs which may have the coding
magic comment.
@c JP
デフォルトでは、Gauche の @code{load} はプログラムソースを読むのに
コーディング認識ポートを使います。したがって、文字エンコーディングを
示す特別なマジックコメントは、Gauche のソースプログラムでは有効になります
(@ref{Loading Scheme file}参照)。ただし、この機構自身は @code{load} とは
独立しており、このポートを別の目的で利用できます。特にコーディングの
マジックコメントがある Scheme のソースプログラムを処理する関数を書くときに
便利です。
@c COMMON
@end defun

@node Input, Output, Coding-aware ports, Input and output
@subsection Input
@c NODE 入力

@c EN
For the input-related procedures, the optional @var{iport} argument must be
an input port, and when omitted, the current input port is assumed.
@c JP
入力に関する手続きで、省略可能な引数@var{iport}は入力ポートでなければなりません。
省略された場合が現在の入力ポートが使われます。
@c COMMON

@menu
* Reading data::
* Reader lexical mode::
* Read-time constructor::
* Input utility functions::
@end menu

@node Reading data, Reader lexical mode, Input, Input
@subsubsection Reading data
@c NODE データの読み込み

@defun read :optional iport
[R7RS base]
@c EN
Reads an S-expression from @var{iport} and returns it.
Gauche recognizes the lexical structure specified in R7RS,
and some additional lexical structures listed in @ref{Lexical structure}.

If @var{iport} has already reached to the end of file,
an eof object is returned.

The procedure reads up to the last character that consists the S-expression,
and leaves the rest in the port.  It's not like CommonLisp's @code{read},
which consumes whitespaces after S-expression by default.
@c JP
@var{iport}からS式をひとつ読み込んで返します。
GaucheはR7RSに定義されている構文要素に加え、@ref{Lexical structure}に
定義されている拡張構文要素を認識します。

@var{iport}が既にEOFに達していた場合は、EOFオブジェクトが返されます。

この手続きはS式を構成する最後の文字までを読み、その後の文字はポートに
残します。これは、S式に続く空白文字も読み込むCommonLispの@code{read}の
振る舞いとは異なります。
@c COMMON
@end defun

@defun read-with-shared-structure :optional iport
@defunx read/ss :optional iport
[SRFI-38]
@c EN
These procedures are defined in SRFI-38 to recognize shared substructure
notation (@code{#n=}, @code{#n#}).   Gauche's builtin @code{read} recognizes
the SRFI-38 notation, so these are just synonyms to @code{read}; these
are only provided for SRFI-38 compatibility.
@c JP
これらの手続きは、SRFI-38 で定義されていて、共有構造を表す記法
(@code{#n=}, @code{#n#})を認識できます。Gauche の組み込み @code{read} は
この SRFI-38 の記法を認識します。それゆえ、これらの手続きは、@code{read}
と同じで、SRFI-38 との互換性のために用意されています。
@c COMMON
@end defun

@defun read-char :optional iport
[R7RS base]
@c EN
Reads one character from @var{iport} and returns it.
If @var{iport} has already
reached to the end, returns an eof object.
If the byte stream in @var{iport} doesn't consist a valid character,
the behavior is undefined.  (In future, a port will have a option
to deal with invalid characters).
@c JP
@var{iport}から1文字読み込んで返します。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@var{iport}にあるバイトストリームが正しい文字を構成しない場合、
ふるまいは未定義です。(将来はポート側に、不正な文字に対する対応を決める
オプションを設ける予定です)。
@c COMMON
@end defun

@defun peek-char :optional iport
[R7RS base]
@c EN
Reads one character in @var{iport} and returns it, keeping the character
in the @var{port}.
If the byte stream in @var{iport} doesn't consist a valid character,
the behavior is undefined.  (In future, a port will have a option
to deal with invalid characters).
@c JP
@var{iport}から1文字読み込んで返します。文字はそのまま@var{iport}に留まります。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@var{iport}にあるバイトストリームが正しい文字を構成しない場合、
ふるまいは未定義です。(将来はポート側に、不正な文字に対する対応を決める
オプションを設ける予定です)。
@c COMMON
@end defun

@defun read-byte :optional iport
@defunx read-u8 :optional iport
[R7RS base]
@c EN
Reads one byte from an input port @var{iport}, and returns it as an integer
in the range between 0 and 255.
If @var{iport} has already reached EOF, an eof object is returned.

This is traditionally called @code{read-byte}, and
R7RS calls it @code{read-u8}.  You can use either.
@c JP
入力ポート@var{iport}から1バイト読み込み、0から255までの整数値として返します。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。

これは伝統的に@code{read-byte}と呼ばれてきましたが、
R7RSでは@code{read-u8}と名づけています。どちらも使えます。
@c COMMON
@end defun

@defun peek-byte :optional iport
@defunx peek-u8  :optional iport
[R7RS base]
@c EN
Peeks one byte at the head of an input port @var{iport}, and returns
it as an integer in the range between 0 and 255.
If @var{iport} has already reached EOF, an eof object is returned.

This is traditionally called @code{peek-byte}, and
R7RS calls it @code{peek-u8}.  You can use either.
@c JP
入力ポート@var{iport}の先頭の1バイトを見て、それを0から255までの整数値として返します。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。

これは伝統的に@code{peek-byte}と呼ばれてきましたが、
R7RSでは@code{peek-u8}と名づけています。どちらも使えます。
@c COMMON
@end defun

@defun read-line :optional iport allow-byte-string?
[R7RS base]
@c EN
Reads one line (a sequence of characters terminated by newline or EOF)
and returns a string.  The terminating newline is not included.
This function recognizes popular line terminators (LF only, CRLF, and CR only).
If @var{iport} has already reached EOF, an eof object is returned.
@c JP
入力ポートから、行末もしくはEOFまで読み込んで文字列として返します。
よく使われる行末 (LF only, CRLF, and CR only) を認識します。
戻り値にはこれらの行末文字は含まれません。
@var{iport}が既にEOFに達していた場合はeofオブジェクトを返します。
@c COMMON

@c EN
If a byte sequence is read from @var{iport}
which doesn't constitute a valid character in the native encoding,
@code{read-line} signals an error by default.  However, if a true value
is given to the argument @var{allow-byte-string?},
@code{read-line} returns a byte string (incomplete string) in such case,
without reporting an error.
It is particularly useful if you read from a source whose
character encoding is not yet known; for example, to read XML document,
you need to check the first line to see if there is a charset parameter
so that you can then use an appropriate character conversion port.
This optional argument is Gauche's extension to R7RS.
@c JP
@var{iport}から、内部文字エンコーディングでは文字を構成し得ないバイトシーケンスが
読まれた場合、デフォルトでは@code{read-line}はエラーを通知します。
しかし、省略可能な引数@var{allow-byte-string?}に真の値が与えられた場合は、
@code{read-line}はエラーを通知せず、かわりにバイト文字列 (不完全な文字列) を
返します。この動作は、特に文字エンコーディングが不明なソースから読み込む際に
便利です。例えばXMLドキュメントを読み込む際、最初の行のcharsetパラメータを
チェックしてから適切な文字エンコーディング変換ポートを使うといった用途などです。
この動作はGauche独自の拡張です。
@c COMMON
@end defun

@defun read-string nchars :optional iport
[R7RS base]
@c EN
Read @var{nchars} characters, or as many characters as available
before EOF, and returns a string that consists of those characters.
If the input has already reached EOF, an eof object is returned.
@c JP
@var{nchars}文字を読み込み、もしくはそれ以前にEOFに達したら読めただけの文字を
使って文字列を作って返します。もし入力が既にEOFに達していた場合は
EOFを返します。
@c COMMON
@end defun

@defun consume-trailing-whitespaces :optional iport
@c EN
Reads and discards consecutive whitespace characters up to (including)
the first EOL, from @var{iport}.  If @var{iport} is omitted,
the current input port is used.
@c JP
@var{iport}から、連続する空白文字を、最初の行末文字を読むまで読み込んで捨てます。
@var{iport}が省略された場合は現在の入力ポートが使われます。
@c COMMON

@c EN
This is mainly for interactive REPL when the input is line
buffered.  Suppose you're reading user's input using @code{read}.
If the input is line buffered, @code{read} won't see any input until
the user type @code{RET}.  It means if the user type
@code{(read-line)RET}, then @code{read} returns @code{(read-line)},
and if you evaluate it immediately, it reads @code{RET}.
@c JP
これは主にラインバッファリングがある入力でインタラクティブなREPLを走らせる
ためのものです。入力を@code{read}で読み込んでいるとしましょう。
入力がラインバッファされていたら、ユーザがRETをタイプしてはじめて@code{read}が
入力を読むことになります。ということは、ユーザが@code{(read-line)RET}とタイプしたなら、
@code{read}は@code{(read-line)}を返し、もしそれを即座にevalするなら、
それは入力に残っているRETを読み込むことになるでしょう。
@c COMMON

@c EN
That is not users typically expect; the user wants to type the
input for @code{read-line}.  Hence, it is useful to consume trailing
@code{RET} after reading the user's initial input.
@c JP
これはユーザが通常期待する動作とは異なります。
ユーザは、@code{read-line}が実行された時点で、入力にタイプした行を読んで欲しいと
思うでしょう。したがって、ユーザの最初の入力のあと、バッファに残っているRETを含めた
空白文字を捨てておくことが役に立ちます。
@c COMMON
@end defun

@defun read-block nbytes :optional iport
@c DEPRECATED
@c EN
Use @code{read-uvector} instead (@pxref{Uvector block I/O}).
@c JP
@code{read-uvector}を使ってください(@ref{Uvector block I/O}参照)。
@c COMMON

@c EN
Reads @var{nbytes} bytes from @var{iport}, and returns an incomplete
string consisted by those bytes.  The size of returned string may
shorter than @var{nbytes} when @var{iport} doesn't have enough bytes
to fill.
If @var{nbytes} is zero, a null string is always returned.

If @var{iport} has already reached EOF, an eof object is returned.
@c JP
@var{nbytes}バイトのデータを@var{iport}から読み込み、
不完全な文字列として返します。@var{iport}に十分なデータが無い場合、
返される文字列は@var{nbytes}より短いかもしれません。
@var{nbytes}が0の場合は、常に空文字列が返されます。

@var{iport}が既にEOFに達していた場合はEOFオブジェクトが返されます。
@c COMMON

@c EN
If @var{iport} is a file port, the behavior of @code{read-block}
differs by the buffering mode of the port (@xref{File ports}, for
the detail explanation of buffering modes).
@c JP
@var{iport}がファイルポートだった場合、@code{read-block}は
ポートのバッファリングモードによってふるまいが異なります
(バッファリングモードの詳細については@ref{File ports}を参照して下さい)。
@c COMMON
@itemize @bullet
@item
@c EN
If the buffering mode is @code{:full}, @code{read-block} waits
until @var{nbytes} data is read, except it reads EOF.
@c JP
バッファリングモードが@code{:full}の場合、@code{read-block}は
EOFを読まない限り、@var{nbytes}のデータが読まれるまで待ちます。
@c COMMON
@item
@c EN
If the buffering mode is @code{:modest} or @code{:none}, @code{read-block}
returns shorter string than @var{nbytes} even if it doesn't reach EOF,
but the entire data is not available immediately.
@c JP
バッファリングモードが@code{:modest}か@code{:none}である場合、
@code{read-block}はEOFが読まれなくても、すぐに読めるデータが@var{nbytes}よりも
少ない場合はそのデータだけを返します。
@c COMMON
@end itemize

@c EN
If you want to write a chunk of bytes to a port,
you can use either @code{display} if the data is in string,
or @code{write-uvector} in @code{gauche.uvector} (@pxref{Uvector block I/O})
if the data is in uniform vector.
@c JP
データブロックをポートに書き出すには、データが文字列で表現されている
場合は単純に@code{display}が使えます。データがuniform vectorで表現されている
場合は@code{gauche.uvector}モジュールの@code{write-uvector}が
使えます (@ref{Uvector block I/O}参照)。
@c COMMON
@end defun

@defun eof-object
[R7RS base]
@c EN
Returns an EOF object.
@c JP
EOFオブジェクトを返します。
@c COMMON
@end defun


@defun eof-object? obj
[R7RS base]
@c EN
Returns true if @var{obj} is an EOF object.
@c JP
@var{obj}がEOFオブジェクトなら@code{#t}を返します。
@c COMMON
@end defun

@defun char-ready? :optional port
[R7RS base]
@c EN
If a character is ready to be read from @var{port}, returns @code{#t}.

For now, this procedure actually checks only if next @emph{byte} is
immediately available from @var{port}.   If the next byte is a part of
a multibyte character, the attempt to read the whole character may block,
even if @code{char-ready?} returns @code{#t} on the port.
(It is unlikely to happen in usual situation, but theoretically it can.
If you concern, use @code{read-uvector} to read the input as a byte
sequence, then use input string port to read characters.)
@c JP
@var{port}から文字が読み出せる状態ならば@code{#t}を返します。

今のところ、この手続きは@var{port}から少なくとも1バイト読み出せる状態なら@code{#t}
を返します。そのバイトがマルチバイト文字を構成する場合、@code{char-ready?}を返した
ポートから文字全てを読み込もうとすると、ブロックする可能性があります。
(通常の使用状況ではそのようなことは起きないでしょうが、理論的には起こり得ます。
慎重を期したい場合は@code{read-uvector}でバイトシーケンスとして読み込んだ後、
入力文字列ポート等を使って文字毎に読むようにして下さい。)
@c COMMON
@end defun

@defun byte-ready? :optional port
@defunx u8-ready?  :optional port
[R7RS base]
@c EN
If one byte (octet) is ready to be read from @var{port}, returns
@code{#t}.

This is traditionally called @code{byte-ready?}, and
R7RS calls it @code{u8-ready?}.  You can use either.
@c JP
@var{port}から1バイトをすぐに読み込める状態なら@code{#t}を返します。

これは伝統的に@code{byte-ready?}と呼ばれてきましたが、
R7RSでは@code{u8-ready?}と名づけています。どちらも使えます。
@c COMMON
@end defun

@node Reader lexical mode, Read-time constructor, Reading data, Input
@subsubsection Reader lexical mode
@c NODE リーダー字句モード

@deffn {Parameter} reader-lexical-mode
@c EN
Get/set the reader lexical mode.  Changing this parameter
switches behavior of the reader concerning some corner cases
of the lexical syntax, where legacy Gauche syntax and R7RS syntax
aren't compatible.
@c JP
現在のリーダ字句モードを表すパラメータです。
このパラメータの値を変えることにより、旧来のGaucheとR7RSで非互換となる
コーナーケースの字句構文についての解釈を変更できます。
@c COMMON

@c EN
In general, you don't need to change this parameter directly.
The lexical syntax matters at the read-time, while changing this parameter
happens at the execution-time; unless you know the exact timing when
each phase occurs, you might not get what you want.
@c JP
一般的には、このパラメータを直接変える必要のある場合は少ないでしょう。
字句構文は読み込み時に問題となりますが、パラメータの変更は実行時に起こります。
いつ、何が起きるかを正確に把握しているのでない限り、意図したとおりの効果は
得られないかもしれません。
@c COMMON

@c EN
The hash-bang directive @code{#!gauche-legacy} and @code{#!r7rs}
indirectly affects this parameter; the first one sets the reader
mode to @code{legacy}, and the second one to @code{strict-r7}.
@c JP
hash-bang指示子 @code{#!gauche-legacy} および @code{#!r7rs} は
間接的にこのパラメータに影響を与えます。@code{#!gauche-legacy}は
リーダモードを@code{legacy}に、@code{#!r7rs}は@code{strict-r7}に
変更します。
@c COMMON

@c EN
The command-line argument @code{-fwarn-legacy} sets the default
reader mode to @code{warn-legacy}.
@c JP
コマンドライン引数の@code{-fwarn-legacy}はデフォルトのリーダモードを
@code{warn-legacy}にセットします。
@c COMMON

@c EN
Change to this parameter during @code{load} is delimited within that @code{load};
once @code{load} is done, the value of this parameter is reset
to the value when @code{load} is started.
@c JP
@code{load}中にこのパラメータを変更した場合、その効果は@code{load}の期間中に
留まります。その@code{load}が終了した時点で、
@code{load}開始時のリーダモードが復元されます。
@c COMMON

@c EN
The parameter takes one of the following symbols as a value.
@c JP
このパラメータは値として次のシンボルのうちいずれかを取ります。
@c COMMON

@table @code
@item permissive
@c EN
This is the default mode.  It tries to find a reasonable
compromise between two syntax.
@c JP
これがデフォルトのモードです。二つの構文の、ほどほどの妥協点を見つけようとします。
@c COMMON

@c EN
In string literals, hex escape sequence
is first interpreted as R7RS lexical syntax.  If the syntax doesn't
conform R7RS hex escape, it is interpreted as legacy Gauche hex escape
syntax.  For example, @code{"\x30;a"} is read as @code{"0a"}, for
the hex escape sequence including the terminating semicolon is read
as R7RS hex escape sequence.  It also reads @code{"\x30a"} as
@code{"0a"}, for the legacy Gauche hex escape always takes two hexadecimal
digits without the terminator.  With this mode, you can use R7RS
hex escape syntax for the new code, and yet almost all legacy Gauche
code can be read without a problem.
However, if the legacy code has a semicolon followed by hex escape,
it is interpreted as R7RS syntax and the incompatibility arises.
@c JP
文字列リテラル中の16進数エスケープシーケンスは、まず
R7RSの字句構文で解釈されます。もしそれがR7RSの16進数エスケープシーケンスの
構文に沿っていなかった場合は、旧来のGaucheの構文で解釈されます。
例えば、@code{"\x30;a"} は、セミコロンがR7RSのエスケープシーケンスの終端と
みなされ、@code{"0a"} と読まれます。一方で @code{"\x30a"} も @code{"0a"} と
読まれます。終端のセミコロンが無く、有効なR7RSの構文でないため、
旧来のGaucheのエスケープシーケンスとして2桁固定で解釈されるからです。
このモードでは、新たなコードでR7RSエスケープシーケンスを利用できるうえ、
ほとんどの既存のGaucheコードはそのまま走ります。
しかし、もし既存のGaucheコードで、たまたま2桁の16進数エスケープの直後に
セミコロンがあった場合、それはR7RSとして読まれ、非互換性が生じます。
@c COMMON

@item strict-r7
@c EN
Strict R7RS compatible mode.
When the reader encounters the hash-bang directive @code{#!r7rs},
the rest of file is read with this mode.
@c JP
厳密にR7RS互換なモード。
リーダが、hash-bang指示子@code{#!r7rs}に出会うと、ファイルの残りの部分は
このモードで読まれます。
@c COMMON

@c EN
In this mode, Gauche's extended lexical syntax will raise an error.

Use this mode to ensure the code can be read on other R7RS implementations.
@c JP
このモードでは、Gaucheの拡張字句構文はエラーとなります。

他のR7RS実装でも読めるコードであることを確認したい場合に使ってください。
@c COMMON

@item legacy
@c EN
The reader works as the legacy Gauche (version 0.9.3.3 and before).
When the reader encounters the hash-bang directive @code{#!gauche-legacy},
the rest of file is read with this mode.

This only matters when you want to read two-digit hex escape
followed by semicolon as a character plus a semicolon, e.g.
@code{"\x30;a"} as @code{"0;a"} instead of @code{"0a"}.
We expect such a sequence rarely appears in the code,
but if you dump a data in a string literal format, you may
have such sequence (especially in incomplete string literals).
@c JP
リーダは以前の(0.9.3.3及びそれ以前の)Gaucheと同じように動作します。
リーダがhash-bang指示子@code{#!gauche-legacy}に出会うと、ファイルの残りの部分は
このモードで読まれます。

このモードが必要になるのは、2桁の16進数エスケープの直後にセミコロンが来ているリテラルを、
文字＋セミコロンと読みたい場合だけです。例えば
@code{"\x30;a"}を@code{"0a"}でなく@code{"0;a"}と読みたい、等。
こういうケースはコードではほとんど無いと思いますが、
データを文字列リテラルとしてダンプしてある場合、それも不完全な文字列として
ダンプしてある場合に、こういった並びが出現しているかもしれません。
@c COMMON

@item warn-legacy
@c EN
The reader works as the @code{permissive} mode,
but warns if it reads legacy hex-escape syntax.
This mode is default when @code{-fwarn-legacy} command-line
argument is given to @code{gosh}.

This is useful to check if you have any incompatible escape sequence
in your code.
@c JP
リーダは@code{permissive}モードと同様に動作しますが、
旧来の16進数エスケープに出会うと警告を発します。
@code{gosh}に@code{-fwarn-legacy}コマンドライン引数が与えられた場合は
これがデフォルトのモードになります。

コードの中に非互換なエスケープシーケンスが無いかどうか調べるのに役立ちます。
@c COMMON
@end table
@end deffn


@node Read-time constructor, Input utility functions, Reader lexical mode, Input
@subsubsection Read-time constructor
@c NODE 読み込み時コンストラクタ

@c EN
Read-time constructor, defined in SRFI-10, provides an easy way
to create an external representation of user-defined structures.
@c JP
SRFI-10で定義されている読み込み時コンストラクタは、ユーザ定義の構造の
外部表現を作るための簡単な方法を提供します。
@c COMMON

@deftp {Reader Syntax} @code{#,(@var{tag} @var{arg} @dots{})}
@lxindex #,
[SRFI-10]
@c EN
Gauche maintains a global table that associates a @var{tag} (symbol)
to @emph{a constructor procedure}.
@c JP
Gaucheは@var{tag} (シンボル)を@emph{コンストラクタ手続き}に関連付ける
グローバルなテーブルを管理しています。
@c COMMON

@c EN
When the reader encounters this syntax, it reads @var{arg} @dots{},
finds a reader constructor associated with @var{tag}, and
calls the constructor with @var{arg} @dots{} as arguments,
then inserts the value returned by the constructor as the result
of reading the syntax.
@c JP
リーダーがこの構文に出会ったとき、@var{arg} @dots{}を読み込み、
@var{tag}に関連付けられた読み込みコンストラクタを探し、
@var{arg} @dots{}を引数としてそのコンストラクタを呼び出し、
その構文を読み込んだ結果としてそのコンストラクタが返した値を挿入します。
@c COMMON

@c EN
Note that this syntax is processed inside the reader---the
evaluator doesn't see any of @var{arg}s, but only sees the object
the reader returns.
@c JP
この構文はリーダー内部で処理されることに注意して下さい。評価器は
@var{arg}を見ず、リーダーが返したオブジェクトしか見ません。
@c COMMON
@end deftp

@defun define-reader-ctor @var{tag} @var{procedure}
@c EN
[SRFI-10]
Associates a reader constructor @var{procedure} with @var{tag}.

Examples:
@c JP
[SRFI-10]
読み込みコンストラクタ@var{procedure}を@var{tag}に関連付けます。

例:
@c COMMON
@example
(define-reader-ctor 'pi (lambda () (* (atan 1) 4)))

#,(pi) @result{} 3.141592653589793

'(#,(pi)) @result{} (3.141592653589793)

(define-reader-ctor 'hash
  (lambda (type . pairs)
    (let ((tab (make-hash-table type)))
      (for-each (lambda (pair)
                  (hash-table-put! tab (car pair) (cdr pair)))
                pairs)
      tab)))

(define table
 #,(hash eq? (foo . bar) (duh . dah) (bum . bom)))

table @result{} #<hash-table eq? 0x80f9398>
(hash-table-get table 'duh) @result{} dah
@end example

@c EN
Combined with @code{write-object} method (@pxref{Output}),
it is easy to make a user-defined class written in the form
it can be read back:
@c JP
@code{write-object}メソッド(@ref{Output}参照)と組み合わせて、
読み戻ることが可能なフォームで書かれたユーザ定義のクラスを
作ることが簡単になります。
@c COMMON

@example
(define-class <point> ()
  ((x :init-value 0 :init-keyword :x)
   (y :init-value 0 :init-keyword :y)))

(define-method write-object ((p <point>) out)
  (format out "#,(<point> ~s ~s)" (ref p 'x) (ref p 'y)))

(define-reader-ctor '<point>
  (lambda (x y) (make <point> :x x :y y)))
@end example

@end defun

@c EN
@emph{NOTE:} The extent of the effect of @code{define-reader-ctor}
is not specified in SRFI-10, and might pose a compatibility problem
among implementations that support SRFI-10.
(In fact, the very existence of @code{define-reader-ctor} is
up to an implementation choice.)
@c JP
@emph{注意:} @code{define-reader-ctor}の効果の範囲はSRFI-10には
規定されておらず、SRFI-10をサポートする実装においても互換性の問題を
起こすことがあるかもしれません。
(実際に、@code{define-reader-ctor}の存在そのものが実装の選択に
任されています。)
@c COMMON

@c EN
In Gauche, at least for the time being, @code{define-reader-ctor}
take effects as soon as the form is compiled and evaluated.  Since
Gauche compiles and evaluates each toplevel form in order, @var{tag}
specified in @code{define-reader-ctor} can be used immediately after that.
However, it doesn't work if the call of @code{define-reader-ctor} and
the use of @var{tag} is enclosed in a @code{begin} form, for the entire
@code{begin} form is compiled at once before being evaluated.
@c JP
Gaucheでは、現時点においては、@code{define-reader-ctor}はそのフォームが
コンパイルされ評価された時点で効力を持ちます。
Gaucheはトップレベルのフォームを順番にコンパイル・評価するので、
@code{define-reader-ctor}で指定された@var{tag}は、その指定の直後から
使えます。
しかし、@code{define-reader-ctor}の呼び出しと@var{tag}の使用が
@code{begin}フォームで囲まれている場合は、@code{begin}フォーム全体は
評価される前に一度にコンパイルされるため、うまく動作しません。
@c COMMON

@c EN
Other implementations may require to read the entire file before
making its @code{define-reader-ctor} call effective.  If so, it
effectively prevents one from using @code{define-reader-ctor} and
the defined @var{tag} in the same file.   It is desirable to separate
the call of @code{define-reader-ctor} and the use of @var{tag}
in the different files if possible.
@c JP
他の実装では、@code{define-reader-ctor}の呼び出しが効力を持つようにする
前にファイル全体を読み込むことを要求するかも知れません。
その場合は、@code{define-reader-ctor}と定義された@var{tag}の使用を
同じファイルに置く事は実質的に不可能です。
可能ならば、@code{define-reader-ctor}の呼び出しと、@var{tag}の使用は
異なるファイルに分離されることが望まれます。
@c COMMON

@c EN
Another issue about the current @code{define-reader-ctor} is that
it modifies the global table of Gauche system, hence it is not modular.
The code written by different people might use the same tags,
and yield an unexpected result.   In future versions, Gauche may
have some way to encapsulate the scope of @var{tag}, although
the author doesn't have clear idea yet.
@c JP
現在の@code{define-reader-ctor}に関するもう1つの問題は、それが
Gaucheシステムのグローバルテーブルを変更してしまうことで、それゆえに
モジュール性が良くありません。
複数人によって書かれたコードは同じタグを使っているかも知れず、
期待されない結果を引き起こすかも知れません。
作者にはまだ明確なアイデアがありませんが、将来のバージョンでは、
Gaucheには@var{tag}のスコープをカプセル化する方法が導入されるかも
しれません。
@c COMMON


@node Input utility functions,  , Read-time constructor, Input
@subsubsection Input utility functions
@c NODE 入力ユーティリティ手続き

@defun port->string port
@defunx port->list reader port
@defunx port->string-list port
@defunx port->sexp-list port
@c EN
Generally useful input procedures.  The API is taken from
scsh and STk.
@c JP
便利な入力手続きです。APIはScshとSTkから取りました。
@c COMMON

@c EN
@code{port->string} reads @var{port}
until EOF and returns the accumulated data as a string.
@c JP
@code{port->string}は@var{port}をEOFまで読み込み、
読んだものを文字列として返します。
@c COMMON

@c EN
@code{port->list} applies @var{reader} on @var{port} repeatedly, until
@var{reader} returns an EOF, then returns the list of objects
@var{reader} returned.
Note that @var{port} isn't closed.
@c JP
@code{port->list}は手続き@var{reader}を@var{port}に繰り返し適用し、
結果をリストに蓄積します。@var{reader}がEOFを返したら
蓄積されたリストを返します。
@var{port}自体はクローズされないことに注意してください。
@c COMMON

@c EN
@code{port->string-list} is a @code{port->list} specialized
by @code{read-line}, and
@code{port->sexp-list} is a @code{port->list} specialized
by @code{read}.
@c JP
@code{port->string-list}は@code{port->list}を
@code{read-line}で特定化したもので、
@code{port->sexp-list}は@code{port->list}を
@code{read}で特定化したものです。
@c COMMON

@c EN
If the input contains an octet sequence that's not form a valid
character in the Gauche's native character encoding,
@code{port->string} and @code{port->string-list} may return
incomplete string(s).
If you want to deal with binary data, consider using
@code{port->uvector} in @code{gauche.uvector} (@pxref{Uvector block I/O}).
@c JP
もし入力にGaucheの内部エンコーディングにおいて有効な文字をつくらない
バイト列が含まれていた場合、@code{port->string}と@code{port->string-list}
の返り値には不完全な文字列が含まれている可能性があります。
入力をバイナリデータとして扱いたい場合は、
@code{gauche.uvector}の@code{port->uvector}を使って下さい
(@ref{Uvector block I/O}参照)。
@c COMMON
@end defun

@defun port-fold fn knil reader
@defunx port-fold-right fn knil reader
@defunx port-for-each fn reader
@defunx port-map fn reader
@c DEPRECATED
@c EN
Convenient iterators over the input read by @var{reader}.

Since these procedures are not really about ports,
they are superseded by @code{generator-fold},
@code{generator-fold-right}, @code{generator-for-each}
and @code{generator-map}, respectively.  @xref{Folding generated values},
for the details.

We provide these only for the backward compatibility.
@c JP
@var{reader}によって読まれる入力に対する便利な繰り返し手続きです。

実際にはこれらの手続きはポートからの入力以外にも使えるため、それぞれ
@code{generator-fold}, @code{generator-fold-right},
@code{generator-for-each}, @code{generator-map}によって置き換えられました。
詳しくは@ref{Folding generated values}を参照してください。

これらの手続きは後方互換性のためだけに提供されています。
@c COMMON
@end defun

@node Output,  , Input, Input and output
@subsection Output
@c NODE 出力

@menu
* Layers of output routines::
* Output controls::
* Object output::
* Formatting output::
* Low-level output::
@end menu

@node Layers of output routines, Output controls, Output, Output
@subsubsection Layers of output routines
@c NODE 出力ルーチンの階層

@c EN
Gauche has quite a few output procedures which may confuse newcomers.
The following table will help to understand how to use those procedures:
@c JP
Gaucheにはたくさんの出力手続きがあり、慣れないうちはどれを使えばよいか迷ってしまう
かもしれません。次の表は様々な出力手続きを分類するものです。
@c COMMON

@table @asis
@c EN
@item Object writers
Procedures that write out Scheme objects.
Although there exist more low-level procedures,
these are regarded as a basic layer of output routines,
since it works on a generic Scheme object as a single unit.
They come in two flavors:

@itemize @bullet
@item
Write-family procedures: @code{write}, @code{write-shared}, @code{write-simple}--these are to produce @emph{external representation} of Scheme objects,
which can be generally read back by @code{read} without losing
information as much as possible@footnote{In a sense, this is somewhat similar to
what is called ``serialization'' or ``marshalling'' in other programming
language; you can @code{write} out a generic Scheme object on disk or
to wire, and @code{read} it to get an object equivalent to the original
one.  In Lisp-family languages, this is called @emph{read/write invariance}
and is a built-in feature.
Note that some objects do not have this invariance
in nature, so sometimes you need to make your own serializer/marshaller.}.
The external representation of most Scheme objects
are the ones you write literal data in program, so this is the default way
of writing Scheme objects out.
@item
Display-family procedures:
@code{display}, @code{print}, @code{newline}.
These are to produce plain-text output suitable for human readers.
@end itemize
@c JP
@item オブジェクトの出力
Schemeオブジェクトを出力する手続きです。
もっと低レベルの手続きもありますが、一般にはこの層が出力ルーチンの基本であると
みなされています。Schemeのオブジェクト単位で操作をするからです。
この手続き群はさらに次の二つのグループに分かれます。

@itemize @bullet
@item
Write族手続き: @code{write}, @code{write-shared}, @code{write-simple}---これらは、Schemeオブジェクトの@emph{外部表現}を出力します。出力されたものは一般に、
@code{read}を使って、可能な限り情報を失わずに読み戻すことができます@footnote{ある意味、
これは他のプログラミング言語でシリアライズやマーシャライズと呼ばれている操作に
似ています。一般のSchemeオブジェクトをディスクやネットワークに@code{write}して、
それを@code{read}すれば、元のオブジェクトと等価なオブジェクトが得られるわけです。
Lisp族言語では、これは@emph{read/write invariance}と呼ばれ、組み込みの機能と
なっています。但しオブジェクトによってはこの性質を持たないものもあり、
そういうオブジェクトを扱う時は専用のシリアライザを書く必要があります。}。
Schemeオブジェクトの外部表現は、リテラルデータをプログラム中に記述するのと
同じ書き方なので、これがSchemeオブジェクトを出力する際のデフォルトの表現になっています。
@item
Display族手続き: @code{display}, @code{print}, @code{newline}.
これらは人間に読みやすいプレーンテキストな出力を生成します。
@end itemize
@c COMMON

@c EN
@item High-level formatting output
To produce output in specific width, alignment, etc: @code{format}.
This corresponds to C's @code{printf}.
@c JP
@item 高レベル整形出力
出力を指定の桁数に揃えたり、どちらかに寄せたり、といった書式を指定できる手続きが
@code{format}です。Cの@code{printf}のようなものです。
@c COMMON

@c EN
@item Low-level type-specific output
Procedures that deal with raw data.
@itemize @bullet
@item
To output a character or a byte: @code{write-char}, @code{write-byte}.
@item
To output a string or an array of binary data: @code{write-string},
@code{write-uvector}.
@item
To flush the output buffer: @code{flush}, @code{flush-all-ports}.
@end itemize
@c JP
@item 低レベル、特定の型用の出力
「生」のデータを扱う手続きです。
@itemize @bullet
@item
文字毎やバイト毎の出力: @code{write-char}, @code{write-byte}
@item
文字列やバイナリデータの配列の出力: @code{write-string},
@code{write-uvector}
@item
出力バッファのフラッシュ: @code{flush}, @code{flush-all-ports}
@end itemize
@c COMMON
@end table

@node Output controls, Object output, Layers of output routines, Output
@subsubsection Output controls
@c NODE 出力制御

@deftp {Class} <write-controls>
@clindex write-controls
@c EN
You can control several aspects of Lisp structure output via
@code{<write-controls>} object.  The object output routines
(e.g. @code{write, display}) and the high-level output routines
(e.g. @code{format}) can take optional write-controls.
@c JP
Lisp構造の出力形式は、
@code{<write-controls>}オブジェクトによって制御することができます。
Lispオブジェクトを出力するルーチン(@code{write, display}等)や、
高レベル出力手続き(@code{format}等)は出力制御オブジェクトを取ることができます。
@c COMMON

@c EN
The following example may give you some ideas on what
write controls can do:
@c JP
以下の例で、出力制御の様子がわかると思います。
@c COMMON

@example
(write '(1 10 100 1000)
       (make-write-controls :base 16 :radix-prefix #t))
 @r{prints} (#x1 #xa #x64 #x3e8)

(write (iota 100)
       (make-write-controls :length 5))
 @r{prints} (0 1 2 3 4 ...)
@end example

@c EN
The @code{make-write-controls} procedure returns a write-controls object,
which has the following slots (those slot names are taken from Common Lisp's
print control variables):
@c JP
@code{make-write-controls}手続きは出力制御オブジェクトを作って返します。
出力制御オブジェクトは以下のスロットを持ちます
(これらのスロット名はCommon Lispの対応するプリント制御変数から取られました)。
@c COMMON

@defivar <write-controls> length
@c EN
If this slot has a nonnegative integer, it determines the maximum number
of items displayed for lists and vectors (including uniform vectors).
If the sequence has more elements than the limit, an ellipsis is printed
in place.  If this slot is @code{#f} (default), sequence will be written
out fully.
@c JP
このスロットが非負整数の場合、それはリストとベクタ(ユニフォームベクタを含む)の
要素が表示される最大数を指定します。もしリストやベクタがその最大数より
多くの要素を持っている場合、残りの要素は表示されず、代わりに
エリプシスが表示されます。このスロットが@code{#f}(デフォルト)であれば、
すべての要素が表示されます。
@c COMMON
@end defivar

@defivar <write-controls> level
@c EN
If this slot has a nonnegative integer, it determines the maximum depth
of the structure (lists and vectors) to be displayed.  If the structure
has deeper node, it will be printed as @code{#}.
If this slot is @code{#f} (default), no depth limit is enforced.
@c JP
このスロットが非負整数の場合、それは構造体(リストとベクタ)が表示される
最大の深さを指定します。もし構造体がより深いノードを持っている場合、
そのノードの代わりに@code{#}が表示されます。
このスロットが@code{#f}(デフォルト)であれば、すべての要素が表示されます。
@c COMMON
@end defivar

@defivar <write-controls> base
@c EN
This slot must have an integer between 2 and 36, inclusive, and specifies
the radix used to print exact numbers.  The default value is 10.
@c JP
このスロットは2以上36以下の整数でなければならず、
正確な整数を印字する基数を指定します。デフォルトは10です。
@c COMMON
@end defivar

@defivar <write-controls> radix-prefix
@c EN
This slot must have a boolean value.  If it is true, radix prefix
is always printed before exact numbers.  The default value is @code{#f}.

(NB: This slot used to be called @code{radix}.
It was confusing with @code{base}, so we changed it since 0.9.16.  Old
name is still recognized but deprecated.)
@c JP
このスロットは真偽値を持ちます。真であれば、
正確な整数の前に常に基数プレフィクスが表示されます。
デフォルトは@code{#f}です。

(註: このスロットは以前は@code{radix}と呼ばれていましたが、
@code{base}と混同しやすいので0.9.16から@code{radix-prefix}になりました。
以前の名前も認識されますが、非推奨です。)
@c COMMON
@end defivar

@defivar <write-controls> pretty
@c EN
If this slot has true value,
@emph{pretty printing} is used, that is, newlines and indentations are
inserted
to show nested data structures fit in the specified width of columns.
@c JP
このスロットが真の値の場合、
指定されたカラム幅内で、改行やインデントを適宜挿入してネストした構造を見やすく表示する、
@emph{プリティプリント}機能を使います。
@c COMMON
@end defivar

@defivar <write-controls> width
@c EN
If this slot has a nonnegative integer, it specifies the display
column width used for pretty printing.
@c JP
このスロットが非負整数の場合、プリティプリントで使われる表示幅を指定します。
@c COMMON
@end defivar

@defivar <write-controls> indent
@c EN
This slot must be a nonnegative exact integer.  If this is greater than zero,
and the @code{pretty} slot is true,
that number of whitespaces are written out after the pretty printer emits
a newline.  That is, the second and after lines are indented.
If the @code{pretty} slot is false, this slot is ignored and no indentation
is done.

Note that the first line is not indended; the intention is that pretty
printing begins at a certain column, so that no whitespace insetion
is needed for the first line but the rest of lines need to be indented
to align to the beginning of pretty print.
@c JP
このスロットの値は非負の正確な整数でなければなりません。
このスロットの値がゼロより大きく、@code{pretty}スロットが偽でなければ、
プリティプリンタは改行文字を出力した後にこのスロットの数だけ空白文字を出力します。
つまり、2行め以降がインデントされることになります。
@code{pretty}スロットが偽であればこのスロットは無視されインデントも行われません。

最初の行はインデントされないことに注意してください。
想定する使い方は、あるカラムからプリティプリントを開始することです。この場合、
1行目はそのまま出力できますが、2行目以降を1行目と揃うようにインデントする必要があります。
@c COMMON
@end defivar

@defivar <write-controls> string-length
@c EN
This slot must be a nonnegative exact integer or @code{#f}.
If its value is an integer, string literals longer than the value
are truncated during output; an ellipsis is shown after truncated
content, before closing double-quotes.
@c JP
このスロットは非負整数か@code{#f}です。非負整数の場合、その長さ以上の文字列リテラルは
切り詰めて表示されます。このスロットの値ぶんの文字が出力されたのち、
エリプシスとダブルクオートが出力されます。
@c COMMON
@end defivar

@defivar <write-controls> exact-decimal
@c EN
This slot holds a boolean value.  If it's @code{#f} (default), exact
non-integral rationals are printed in fractional from.  If it's true,
exact rationals are prited with decimal notation, with @code{#e} prefix.
If the denominator has factors rather than 2 and 5,
it is printed with repeating decimal notation (@pxref{Lexical structure}).
However, if the length of repeating cycle is too long, it gives up
and falls back to fractional form.
@c JP
このスロットは真偽値を持ちます。@code{#f}の場合、
正確な非整数の有理数は分数として表示されますが、
真の場合、@code{#e}プレフィクスをつけた小数として表示されます。
有理数の分母に2と5以外の因数がある場合は循環小数表記が使われます
(@ref{Lexical structure}参照)。ただし、循環部の長さが長くなりすぎる
場合は諦めて分数表記になります。
@c COMMON

@example
(define wc (make-write-controls :exact-decimal #t))

(number->string 1234/1000 wc)
  @result{} "#e1.234"
(number->string (expt 1/2 10) wc)
  @result{} "#e0.0009765625"
(number->string 5/7 wc)
  @result{} "#e0.#714285"  @r{; repeating decimal notation}
(number->string 1/2063 wc)
  @result{} "1/2063" @r{; it has repeating cycle of 1031 digits, so we give up.}
@end example
@end defivar

@defivar <write-controls> array
@c EN
This slot can have one of the symbols @code{compact} (default),
@code{dimensions}, or @code{reader-ctor}.
It controls how arrays are printed.
@xref{Array literal syntax}, for the details.
@c JP
このスロットはシンボル@code{compact} (デフォルト)、
@code{dimensions}、@code{reader-ctor}のいずれかを持ち、
配列の表示方式を制御します。
詳しくは@ref{Array literal syntax}を参照してください。
@c COMMON
@end defivar

@defivar <write-controls> complex
@c EN
This slot can have one of the symbols @code{rectangular} (default),
@code{polar}, @code{polar-pi}, or @code{vector}.
It controls how compilex numbers are printed.
(@code{vector} style uses uniform-vector like
representation @code{#c(@var{real-part} @var{imag-part})}, which is compatible
to Common Lisp).

The following table shows how @code{(sqrt (sqrt -5))} is printed
with each complex printing mode.
@c JP
このスロットはシンボル@code{rectangular} (デフォルト)、
@code{polar}、@code{polar-pi}、@code{vector}のいずれかを持ち、
複素数の表示方式を制御します。
(@code{vector}スタイルはユニフォームベクタに似た
@code{#c(@var{real-part} @var{imag-part})}という表記を使います。
これはCommon Lispと互換性があります)。

以下の表は、各方式で@code{(sqrt (sqrt -5))}がどう表示されるかを
示します。
@c COMMON

@table @code
@item rectangular
@code{1.057371263440564+1.057371263440564i}
@item polar
@code{1.4953487812212205@@0.7853981633974483}
@item polar-pi
@code{1.4953487812212205@@0.25pi}
@item vector
@code{#c(1.057371263440564 1.057371263440564)}
@end table
@end defivar

@c EN
A write-controls object is immutable.  If you need a controls object
with a slight variation of an existing controls object,
use @code{write-controls-copy}.
@c JP
出力制御オブジェクトは変更不可です。もし既に存在する制御オブジェクトを
少し変えたものが欲しければ、@code{write-controls-copy}が使えます。
@c COMMON

@c EN
Note: When we introduced @code{<write-controls>} object in 0.9.5,
we used slot names as @code{print-length}, @code{print-pretty} etc.,
mirroring Common Lisp's special variables.  However, the @code{print-} part
is redundant, as it is a part of a class dedicated to print control.  So
we changed the slot names as of 0.9.6.
The procedures @code{make-write-controls} and @code{write-controls-copy}
accepts both old and new names for the backward compatibility.  The old
code that directly refers to the slots needs to be rewritten (we think
there're a not a lot).  We'll drop the old name support in 1.0 release.
@c JP
註: 0.9.5で@code{<write-controls>}オブジェクトを導入した際には、
Common Lispのスペシャル変数の名前をそのまま反映した
@code{print-length}、@code{print-pretty}等をスロット名としていました。
しかし出力制御オブジェクトの一部であることがわかっている以上、@code{print-}の部分は冗長です。
そこで0.9.6からスロット名を変えました。
互換性のために、@code{make-write-controls}と@code{write-controls-copy}は
古いスロット名でのキーワード引数も認識します。
スロットを直接指定してアクセスしているコードは修正の必要があります。
1.0リリース時に古いスロット名のサポートを落とす予定です。
@c COMMON
@end deftp

@defun make-write-controls :key length level base radix-prefix pretty width indent string-length exact-decimal array complex
@c EN
Creates and returns a write-controls object.
@c JP
出力制御オブジェクトを作って返します。
@c COMMON
@end defun

@defun write-controls-copy controls :key length level base radix-prefix pretty width indent string-length exact-decimal array complex
@c EN
Returns a copy of another write-controls object @var{controls}.
If keyword arguments are given, those values override the
original values.
@c JP
出力制御オブジェクト@var{controls}のコピーを返します。もしキーワード引数が
与えられれば、その要素が置き換えられます。
@c COMMON
@end defun

@c EN
Note: The high-level output procedures can be recursively called
via @code{write-object} method.  In that case, the write controls
of the root output call will be automatically inherited to the
recursive output calls to the same port.
@c JP
高レベル出力手続きは@code{write-object}メソッドを経由して再帰的に
呼ばれる可能性があります。その場合、大元の出力手続き呼び出しに渡された
出力制御オブジェクトが、同じポートに対して出力する再帰的に呼ばれる
出力手続きへと自動的に引き継がれます。
@c COMMON

@node Object output, Formatting output, Output controls, Output
@subsubsection Object output
@c NODE オブジェクトの出力

@c EN
For the following procedures, the optional @var{port} argument must be
an output port, and when omitted, the current output port is assumed.
@c JP
以下の手続きで、省略可能な引数@var{port}は出力ポートでなければなりません。
省略された場合が現在の出力ポートが使われます。
@c COMMON

@c EN
Some procedures take @var{port/controls} argument, which can be either
an output port or @code{<write-controls>} object.  For example, @code{write}
takes up to two such optional arguments; that is, you can call it
as @code{(write obj)}, @code{(write obj port)},
@code{(write obj controls)}, @code{(write obj port controls)}
or @code{(write obj controls port)}.  When omitted, the port is assumed
to be the current output port, and the controls is assumed to be the default
controls.
@c JP
いくつかの手続きは@var{port/controls}引数を取ります。これは、出力ポート
もしくは@code{<write-controls>}オブジェクトでなければなりません。例えば
@code{write}は二つまでそういった引数を取ります。すなわち、@code{write}は
以下のいずれの形式でも呼び出すことができます:
@code{(write obj)}、@code{(write obj port)}、
@code{(write obj controls)}、@code{(write obj port controls)}、
@code{(write obj controls port)}。
省略された場合、ポートは現在の出力ポート、出力制御についてはデフォルトの出力制御が
使われます。
@c COMMON

@defun write obj :optional port/controls1 port/controls2
@defunx write-shared obj :optional port/controls1 port/controls2
@defunx write-simple obj :optional port/controls1 port/controls2
[R7RS+ write]
@c EN
The @code{write}-family procedures are used to write an
external representation of Scheme object,
which can be read back by @code{read} procedure.  The three
procedures differ in a way to handle shared or circular structures.
@c JP
@code{write}族の手続きは、Schemeオブジェクトの外部表現を出力します。
外部表現は一般に、@code{read}手続きによって読み戻せば、
元のオブジェクトと同等のオブジェクトとなります。
この3つの手続きの違いは、共有構造および循環構造の扱いにあります。
@c COMMON

@c EN
@code{Write} is circular-safe; that is, it uses datum label notation
(@code{#n=} and @code{#n#}) to show cycles.  It does not use datum label
notation for non-circular structures that are merely shared
(see the second example).
@c JP
@code{write}は循環構造に対して安全です。データに循環がある場合は
データラベル記法(@code{#n=}と@code{#n#})を用いてそれを表現します。
循環の無い、単に共有されているだけの構造についてはデータラベル記法を使いません
(二番目の例参照)。
@c COMMON

@example
(let1 x (list 1)
  (set-cdr! x x)   ; create a cycle
  (write x))
 @result{} @r{shows} #0=(1 . #0#)

(let1 x (list 1)
  (write (list x x)))
 @result{} @r{shows} ((1) (1))
@end example

@c EN
@code{Write-shared} is also circular-safe, and it also shows
shared structures using datum labels.  Use this if you need
to preserve topology of a graph structure.
@c JP
@code{write-shared}も循環構造に対して安全で、さらに共有構造も
データラベル記法で表示します。グラフ構造のトポロジーを維持する必要がある
場合はこの手続きを使ってください。
@c COMMON

@example
(let1 x (list 1)
  (write-shared (list x x)))
 @result{} @r{shows} (#0=(1) #0#)
@end example

@c EN
Finally, @code{write-simple} writes out the object recursively
without taking account of shared or circular structures.  This is fast,
for it doesn't need to scan the structure before actually writing out.
However, it won't stop when a circular structure is passed.
@c JP
最後に、@code{write-simple}はオブジェクトを、共有構造や循環構造を考慮せずに
再帰的に表示します。これは出力前に共有構造の検出パスを走らせる必要がないので
高速です。しかし、渡されたデータに循環があった場合は出力が止まらなくなります。
@c COMMON

@c EN
When these procedures encounter an object of
a user-defined class, they call the generic function @code{write-object}.
@c JP
これらの手続きが表示中にユーザ定義クラスのオブジェクトに
出会った場合は、ジェネリックファンクション@code{write-object}を呼び出します。
@c COMMON

@c EN
Historical context: @code{Write} has been in Scheme standards, but
handling of circular structures hasn't been specified until R7RS.
In fact, until Gauche 0.9.4,
@code{write} diverged for circular structures.
SRFI-38 introduced the datum-label notation and
@code{write-with-shared-structure} and @code{write/ss} procedures
to produce such notation, and Gauche supported it.
R7RS clarified this issue, and Gauche 0.9.4 followed.
@c JP
歴史的経緯: @code{write}は以前のScheme標準にもありましたが、
循環構造があった場合の振る舞いはR7RSになるまで規定されていませんでした。
実際、Gauche 0.9.4より前の@code{write}は、循環構造を渡されると停止しません。
SRFI-38はデータラベル記法および、それを表示するための
@code{write-with-shared-structure}と@code{write/ss}手続きを導入し、
Gaucheもそれをサポートしていました。
R7RSでこの問題は明確にされ、Gaucheも0.9.4からそれに沿っています。
@c COMMON
@end defun


@defun write-with-shared-structure obj :optional port
@defunx write/ss obj :optional port
@defunx write* obj :optional port
[SRFI-38]
@c EN
These are aliases of @code{write-shared} above.
@c JP
これらは上記の@code{write-shared}の別名です。
@c COMMON

@c EN
Gauche has been used the name @code{write*} for long, which is
taken from STklos.  SRFI-38 defines @code{write-with-shared-structure}
and @code{write/ss}.  These names are kept for the backward compatibility.
New code should use @code{write-shared}.
@c JP
Gaucheは、STklosから取った@code{write*}という名前を長く使ってきましたが、
SRFI-38によって@code{write-with-shared-structure}と@code{write/ss}が
定義されました。これらの名前は互換性のためだけに残してあります。
新たなコードには@code{write-shared}を使ってください。
@c COMMON
@end defun


@defun display obj :optional port/controls1 port/controls2
[R7RS write]
@c EN
Produces a human-friendly representation of an object @var{obj}
to the output port.

If @var{obj} contains cycles, @code{display} uses datum-label notation.

When @code{display} encounters an object of
a user-defined class, it calls the generic function @code{write-object}.
@c JP
オブジェクト@var{obj}の人に読みやすい表現を、出力ポートに書き出します。

@var{obj}が循環構造を含んでいる場合は、データラベル記法を使って出力します。

@code{display}が表示中にユーザ定義クラスのオブジェクトに
出会った場合は、ジェネリックファンクション@code{write-object}を呼び出します。
@c COMMON

@example
(display "\"Mahalo\", he said.")
 @result{} @r{shows} "Mahalo", he said.

(let ((x (list "imua")))
  (set-cdr! x x)
  (display x))
 @result{} @r{shows} #0=(imua . #0#)
@end example
@end defun


@defun print expr @dots{}
@c EN
Displays @var{expr}s (using @code{display}) to the current output port,
then writes a newline.
@c JP
@var{expr} @dots{} を@code{display}を使って現在の出力ポートに表示し、
最後に改行を書き出します。
@c COMMON
@end defun

@defun pprint obj :key port controls width length level newline indent
@c EN
Pretty prints @var{obj} to @var{port}, which is defaulted to the current
output port.  The same effect is achieved by passing the @code{write} procedure
a write control with @code{pretty} slot setting to @code{#t}
(in fact, it is how @code{pprint} is implemented), but this procedure
provides more convenient interface when you want to play with the
pretty printer.

By default, @code{pprint} prints a newline after writing @var{obj}.
You can suppress this newline by passing @code{#f} to @var{newline} keyword
argument.

To customize pretty printing, you can pass a write control object
to the @var{controls} keyword argument (the @code{pretty} slot of
@var{controls} is ignored; it'll always printed prettily).
Furthermore, you can override @code{width}, @code{length}, @code{level},
and @code{indent}
slots of @var{controls}.  If you omit @var{controls}, a reasonable default
value is assumed.
@xref{Output controls}, for the detail of write controls.
@c JP
@var{obj}を@var{port}に整形出力(prettyprint)します。
@var{port}が省略された場合は現在の出力ポートが使われます。
この手続きと同じ効果は、@code{write}手続きに@code{pretty}スロットを@code{#t}にした
出力制御オブジェクトを渡すことでも得られます
(実際、内部的には@code{pprint}はそうやって@code{write}を呼び出しているだけです)
が、手軽に整形出力を試してみたい場合にこの手続きは便利です。

デフォルトでは、@code{pprint}は@var{obj}を出力した後に改行します。
この動作を抑制するには@var{newline}に@code{#f}を渡してください。

出力の整形をカスタマイズするには、@var{controls}キーワード引数に出力制御オブジェクトを
渡します(渡された制御オブジェクトの@code{pretty}スロットは無視されます;
常に出力は整形されます)。さらに、出力制御オブジェクトの
@code{width}、@code{length}、@code{level}、@code{indent}スロットを、
それぞれのキーワード引数でオーバライドできます。
@var{controls}を省略した場合は適切なデフォルト値が使われます。
出力制御の詳細については@ref{Output controls}を参照してください。
@c COMMON

@example
(pprint (make-list 6 '(gauche droite)))
 @result{} @r{prints}
  ((gauche droite) (gauche droite) (gauche droite) (gauche droite)
   (gauche droite) (gauche droite))

(pprint (make-list 6 '(gauche droite)) :width 20)
 @result{} @r{prints}
  ((gauche droite)
   (gauche droite)
   (gauche droite)
   (gauche droite)
   (gauche droite)
   (gauche droite))

(pprint (make-list 6 '(gauche droite)) :length 3)
 @result{} @r{prints}
  ((gauche droite) (gauche droite) (gauche droite) …)

(pprint (make-list 6 '(gauche droite)) :level 1)
 @result{} @r{prints}
  (# # # # # #)
@end example
@end defun

@deffn {Method} write-object (obj <object>) port
@c EN
You can customize how the object is printed out by this method.
@c JP
このメソッドを使って、オブジェクトをどのように印字するかをカスタマイズ
できます。
@c COMMON

@example
(define-class <user> ()
  ((id :init-keyword :id)
   (first-name :init-keyword :first-name)
   (middle-name :init-keyword :middle-name)
   (last-name :init-keyword :last-name)))

(define-method write-object ((user <user>) port)
  (format port "#<user ~d: ~a, ~a ~a>"
          (~ user'id) (~ user'last-name) (~ user'first-name) (~ user'middle-name)))
@end example

@example
gosh> (make <user> :id 1000 :first-name "Eva" :middle-name "Lu" :last-name "Ator")
#<user 1000: Ator, Eva Lu>
@end example

@c EN
Note: You're not supposed to call @code{write-object} directly.
Most built-in objects are handled directly within basic output procedures
(@code{write}, @code{display} etc.) and only objects not
handled there are passed to @code{write-object}.  You should call
those basic procedures, or other high-level output procedures like
@code{format}, in your @code{write-object} definition.
@c JP
註: @code{write-object}を直接呼び出すことは想定されていません。
組み込みオブジェクトの多くは基本的な出力手続き
(@code{write}, @code{display}など)で直接処理され、
そうでないオブジェクトの表示のみが@code{write-object}に任されます。
独自の@code{write-object}メソッドを定義する場合、
その中では基本的続きか@code{format}などの高レベル出力手続きを呼ぶように
してください。
@c COMMON
@end deffn

@defun newline :optional port
[R7RS base]
@c EN
Writes a newline character to @var{port}.
This is equivalent to @code{(write-char #\newline port)},
@code{(display "\n" port)}.  It is kept for a historical reason.
@c JP
@var{port}に改行文字を書き出します。@code{(write-char #\newline port)}や
@code{(display "\n" port)}と書いても同じことですが、歴史的な理由から
残されています。
@c COMMON
@end defun

@defun fresh-line :optional port
@c EN
If the output column is at the beginning of line, do nothing and
returns @code{#f}.  Otherwise, writes a newline character and returns @code{#t}.
It is handy when you want to make sure the next output starts
from the beginning of line, but do not want to produce an extra blank line.

This procedure is taken from Common Lisp.
@c JP
出力カラムが行頭であれば何もせず@code{#f}を返します。そうでなければ@code{#\newline}
を出力して@code{#t}を返します。
次の出力を行頭から始めたいけれど、余分な空行は出力したくない、という時に便利です。

この手続きはCommon Lispから取りました。
@c COMMON

@c EN
Not all situations allow this procedure to know the port's output column;
especially, if you mix textual and binary data to output, the column
tracking becomes unreliable.  If this procedure can't detrmine the
column position, it emits a newline character.
@c JP
常にポートの出力カラムがわかるとは限りません。特に、テキスト出力とバイナリ出力を
混ぜた場合、出力カラムのトラッキングは信頼できないものとなります。
出力カラムが特定できない場合は、この手続きは改行文字を出力します。
@c COMMON
@end defun



@node Formatting output, Low-level output, Object output, Output
@subsubsection Formatting output
@c NODE フォーマット出力



@defun format [d/c1 [d/c2]] format-string arg @dots{}
[SRFI-28+]
@c EN
Format @var{arg} @dots{} according to @var{format-string}.
This function is a subset of CommonLisp's @code{format} function,
with a bit of extension.  It is also a superset of SRFI-28,
Basic format strings.
@c JP
@var{string} の指示に従い、@var{arg} @dots{}をフォーマットします。
この手続きはCommonLispの@code{format}のサブセットに、Gauche独自の拡張を
加えたものです。また、これはSRFI-28 "Basic format strings" のスーパーセットに
なっています。
@c COMMON

@c EN
The procedure has unusual signature.  The two optional arguments,
@var{d/c1} and @var{d/c2}, can be an object to specify the destination,
or a @code{<write-controls>} object to tailor
@code{~s} and @code{~a} output
(@pxref{Output controls}).
You can give none, either one of them,
or both, in any order.
@c JP
この手続きは奇妙なシグネチャを持っています。
最初の二つの省略可能引数、@var{d/c1}と@var{d/c2}は、
出力先を指定するオブジェクトか、@code{~s}と@code{~a}の出力形式をカスタマイズする
@code{<write-controls>}オブジェクトです(@ref{Output controls}参照)。
それらをどちらも渡さないことも、どちらかだけを渡すことも、両方渡すこともできます。
両方渡す場合の順番は自由です。
@c COMMON

@c EN
Note: SRFI-28's @code{format} does not take optional arguments before
@var{format-string}
@c JP
註: SRFI-28の@code{format}は@var{format-string}の前に省略可能引数を取りません。
@c COMMON

@c EN
If you give an object to specify destination, it must be either an output
port or a boolean value.
If it is an output port, the
formatted result is written to it; if it is @code{#t},
the result is written to the current output port;
if it is @code{#f}, the formatted result is returned as a string.
@var{Dest} can be omitted, as SRFI-28 @code{format};
it has the same effects as giving @code{#f} to the @var{dest}.
@c JP
出力先を指定するオブジェクトを渡す場合、それは出力ポートか真偽値でなければなりません。
それが出力ポートであれば、フォーマットされた
結果はそのポートに書き出されます。@var{port}が@code{#t}であれば、結果は
現在の出力ポートに書き出されます。@var{port}が@code{#f}であれば、結果は
文字列として@code{format}から返されます。
@var{dest}は省略することもできます。その場合は、@code{dest}に@code{#f}
を指定したのと同じ動作をします(SRFI-28の@code{format})。
@c COMMON

@c EN
@var{string} is a string that contains format directives.
A format directive is a character sequence begins with tilde, `@code{~}',
and ends with some specific characters.  A format directive takes
the corresponding @var{arg} and formats it.  The rest of string is
copied to the output as is.
@c JP
@var{string}はフォーマット指示子を含んだ文字列です。
フォーマット指示子はチルダ`@code{~}'から始まり、特定の文字で終了する文字の並びで、
それぞれのフォーマット指示子が対応する@var{arg}を取りフォーマットします。
@var{string}内のフォーマット指示子以外の文字列はそのまま出力されます。
@c COMMON

@example
(format #f "the answer is ~s" 42)
  @result{} "the answer is 42"
@end example

@c EN
The format directive can take one or more @var{parameters}, separated
by comma characters.  A parameter may be an integer or a character;
if it is a character, it should be preceded by a quote character.
Parameter can be omitted, in such case the system default value is
used.  The interpretation of the parameters depends on the
format directive.
@c JP
フォーマット指示子は一つ以上のコンマで区切られたパラメータを取ることもできます。
パラメータは整数か文字です。文字の場合、クオート文字に続けてその文字を置きます。
パラメータが省略された場合は既定値が使われます。パラメータの意味はフォーマット指示子毎に
異なります。
@c COMMON

@c EN
Furthermore, a format directive can take two
additional flags: atmark `@code{@@}' and colon `@code{:}'.  One or
both of them may modify the behavior of the format directive.
Those flags must be placed immediately before the directive
character.
@c JP
さらに、フォーマット指示子は2種類のフラグ、`@code{@@}' と `@code{:}' を
取ることができます。これらの組合せでフォーマットの動作が変わります。フラグは
(もしあれば)パラメータの後、指示子の文字の直前に置かれなければなりません。
@c COMMON

@c EN
If a character `@code{v}' or `@code{V}' is in the place of the
parameter, the value of the parameter is taken from the format's
argument.  The argument must be either an integer, a character, or
@code{#f} (indicating that the parameter is effectively omitted).
@c JP
パラメータの位置に文字 `@code{v}' か `@code{V}' を置くこともできます。
その場合、パラメータの値が引数リストから取られます。対応する引数は整数か
文字、または@code{#f}でなければなりません。@code{#f}の場合はそのパラメータが
省略されたのと同じになります。
@c COMMON

@c EN
Some examples:

@table @code
@item ~10,2s
A format directive @code{~s}, with two parameters, 10 and 2.
@item ~12,,,'*A
A format directive @code{~a}, with 12 for the first parameter and
a character `@code{*}' for the fourth parameter.  The second and
third parameters are omitted.
@item ~10@@d
A format directive @code{~d}, with 10 for the first parameter and
`@code{@@}' flag.
@item ~v,vx
A format directive @code{~x}, whose first and second parameter will
be taken from the arguments.
@end table
@c JP
いくつかの例です。

@table @code
@item ~10,2s
パラメータ10と2を伴う、フォーマット指示子@code{~s}。
@item ~12,,,'*A
第1パラメータに数値12、第4パラメータに文字`@code{*}'を取るフォーマット指示子@code{~a}。
第2と第3のパラメータは省略されています。
@item ~10@@d
フォーマット指示子@code{~d}。パラメータ10と`@code{@@}'フラグがついています。
@item ~v,vx
フォーマット指示子@code{~x}。第1パラメータと第2パラメータは引数リストから取られます。
@end table
@c COMMON

@c EN
The following is a complete list of the supported format directives.
Either upper case or lower case character can be used for the format
directive; usually they have no distinction, except noted.
@c JP
以下にサポートされているフォーマット指示子を示します。フォーマット指示子の文字自体は
大文字であっても小文字であっても構いません。特に断りのない限り両者は同じ動作をします。
@c COMMON

@table @asis
@item @b{~A}
@c EN
Parameters: @var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}

Ascii output.  The corresponding argument is printed by @code{display}.
If an integer @var{mincol} is given, it specifies the minimum number
of characters to be output; if the formatted result is shorter than
@var{mincol}, a whitespace is padded to the right (i.e. the result
is left justified).
@c JP
パラメータ: @var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}

ASCII出力。対応する引数が@code{display}を使ってフォーマットされます。
整数が@var{mincol}に与えられた場合、それは出力される最小の文字数を指定します。
引数のフォーマット結果が@var{mincol}より短ければ、空白が右に追加されます(つまり、
左詰めになります)。
@c COMMON

@c EN
The @var{colinc}, @var{minpad} and @var{padchar} parameters
control, if given, further padding.  A character @var{padchar} replaces
the padding character for the whitespace.  If an integer @var{minpad}
is given and greater than 0, at least @var{minpad} padding character
is used, regardless of the resulting width.  If an integer @var{colinc}
is given, the padding character is added (after @var{minpad}) in chunk
of @var{colinc} characters, until the entire width exceeds @var{mincol}.
@c JP
@var{colinc}、@var{minpad}、そして@var{padchar}は更に細かいパディング方法を
指定します。@var{padchar}に文字が与えられた場合、それが空白文字の代わりにパディング文字と
して使われます。@var{minpad}に0以上の整数が与えられた場合、少なくともその数だけの
パディング文字が追加されます。@var{colinc}が指定された場合、
追加されるパディング文字の数が@var{colinc}の倍数に調整されます。
@c COMMON

@c EN
If atmark-flag is given, the format result is right justified, i.e.
padding is added to the left.
@c JP
アトマーク `@code{@@}' フラグが与えられた場合、結果は右詰めになります。
@c COMMON

@c EN
The @var{maxcol} parameter, if given, limits the maximum number of characters
to be written.  If the length of formatted string exceeds
@var{maxcol}, only @var{maxcol} characters are written.
If colon-flag is given as well and the length of formatted string
exceeds @var{maxcol}, @var{maxcol} - 4 characters are written and
a string ``@code{ ...}'' is attached after it.
@c JP
@var{maxcol}パラメータは与えられていれば書かれる文字数の上限を指定します。
フォーマット後の文字列の長さが@var{maxcol}を超えた場合、@var{maxcol}文字だけが
書かれます。コロン `@code{:}' フラグが同時に与えられていれば、
@var{maxcol} - 4 文字が書かれた後、文字列``@code{ ...}''が書かれます。
@c COMMON

@example
(format #f "|~a|" "oops")
  @result{} "|oops|"
(format #f "|~10a|" "oops")
  @result{} "|oops      |"
(format #f "|~10@@a|" "oops")
  @result{} "|      oops|"
(format #f "|~10,,,'*@@a|" "oops")
  @result{} "|******oops|"
@c JP
(format #f "|~10,,,'☆a|" "oops")
  @result{} "|oops☆☆☆☆☆☆|"
@c COMMON

(format #f "|~,,,,10a|" '(abc def ghi jkl))
  @result{} "|(abc def gh|"
(format #f "|~,,,,10:a|" '(abc def ghi jkl))
  @result{} "|(abc de ...|"
@end example

@item @b{~S}
@c EN
Parameters: @var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}

S-expression output.  The corresponding argument is printed
by @code{write}.  The semantics of parameters and flags are the same
as @code{~A} directive.
@c JP
パラメータ: @var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}

S式出力。対応する引数が@code{write}を使ってフォーマットされます。
パラメータの意味は@code{~A}指示子と同じです。
@c COMMON

@example
(format #f "|~s|" "oops")
  @result{} "|\"oops\"|"
(format #f "|~10s|" "oops")
  @result{} "|\"oops\"    |"
(format #f "|~10@@s|" "oops")
  @result{} "|    \"oops\"|"
(format #f "|~10,,,'*@@s|" "oops")
  @result{} "|****\"oops\"|"
@c JP
(format #f "|~10,,,'★s|" "oops")
  @result{} "|\"oops\"★★★★|"
@c COMMON
@end example

@item @b{~W}
@c EN
Parametres: None

Write prettily.  Without flags, it just works like @code{~S}.  If
a colon flag is given, it works like pretty print, i.e. @code{pretty}
slot of the write context is true.  If an atmark flag is given,
it works like @code{length} and @code{level} slots of the write
context is @code{#f}, i.e. temporarily turn off length and level limits.

The indent of pretty print is set at the position where @code{~W} begins,
so that if the output spans multiple lines, the second and following lines
are indented properly.
@c JP
パラメータ: なし

きれいな出力。フラグが無ければ@code{~S}と全く同じですが、
コロンフラグが与えられるとプリティプリントを行います。つまり、
@code{<write-context>}の@code{pretty}スロットが一時的に真になります。
また、アトマークフラグが与えられると、S式の長さ制限および深さ制限を一時的にオフにします。
つまり、@code{<write-context>}の@code{length}と@code{level}スロットを@code{#f}
にします。

プリティプリントのインデントは@code{~W}の出力開始位置にセットされるので、
プリティプリントによって出力が複数行になった場合も開始位置に揃うようにインデントされます。
@c COMMON

@example
(format #t "Result: ~:w\n" (make-list 40 'aaaa))
 @result{} @r{prints:}
Result: (aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa
         aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa
         aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa aaaa)
@end example


@item @b{~C}
@c EN
Parameters: None

Character output.  The argument must be a character, or an error is
signaled.  If no flags are given, the character is printed with @code{display}.
If atmark-flag is given, the character is printed with @code{write}.
@c JP
パラメータ: なし

文字出力。対応する引数は文字でなければなりません(そうでなければエラーが報告されます)。
フラグが無ければ文字は@code{display}で表示されます。
アトマークフラグが与えられた場合は@code{write}で表示されます。
@c COMMON

@item @b{~D}
@c EN
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Decimal output.  The argument is formatted as an decimal integer.
If the argument is not an integer, all parameters are ignored
(after processing `@code{v}' parameters) and
it is formatted by @code{~A} directive.
@c JP
パラメータ: @var{mincol},@var{padchar},@var{commachar},@var{interval}

10進出力。対応する引数が10進数表記でフォーマットされます。もし引数が数値でなければ、
全てのパラメータは(`@code{v}'パラメータの処理後に)無視され、
引数は@code{~A}でフォーマットされます。
@c COMMON

@c EN
If an integer parameter @var{mincol} is given, it specifies minimum
width of the formatted result; if the result is shorter than it,
@var{padchar} is padded on the left (i.e. the result is right
justified).  The default of @var{padchar} is a whitespace.
@c JP
もし@var{mincol}に整数が与えられたら、それが最小の文字数を指定します。
結果の文字数がそれより少なければ、文字@var{padchar}が左に追加されます(右詰めになります)。
@var{padchar}が省略された場合は空白文字が使われます。
@c COMMON

@example
(format #f "|~d|" 12345)
  @result{} "|12345|"
(format #f "|~10d|" 12345)
  @result{} "|     12345|"
(format #f "|~10,'0d|" 12345)
  @result{} "|0000012345|"
@end example

@c EN
If atmark-flag is given, the sign `@code{+}' is printed for the
positive argument.
@c JP
アトマーク `@code{@@}' フラグが与えられた場合、正の引数に対して `@code{+}' が
先頭につけられます。
@c COMMON

@c EN
If colon-flag is given, every @var{interval}-th digit of
the result is grouped and @var{commachar} is inserted between them.
The default of @var{commachar} is `@code{,}', and the default of
@var{interval} is 3.
@c JP
コロンフラグ `@code{:}' が与えられた場合、結果の文字は@var{interval}文字毎に
まとめられ、間に文字@var{commachar}が挿入されます。デフォルトでは3文字毎にコンマが
挿入されます。
@c COMMON

@example
(format #f "|~:d|" 12345)
  @result{} "|12,345|"
(format #f "|~,,'_,4:d|" -12345678)
  @result{} "|-1234_5678|"
@end example

@item @b{~B}
@c EN
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Binary output.  The argument is formatted as a binary integer.
The semantics of parameters and flags are the same as
the @code{~D} directive.
@c JP
パラメータ: @var{mincol},@var{padchar},@var{commachar},@var{interval}

2進出力。対応する引数が2進数の整数としてフォーマットされます。
パラメータの意味は@code{~D}と同じです。
@c COMMON

@item @b{~O}
@c EN
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Octal output.  The argument is formatted as an octal integer.
The semantics of parameters and flags are the same as
the @code{~D} directive.
@c JP
パラメータ: @var{mincol},@var{padchar},@var{commachar},@var{interval}

8進出力。対応する引数が8進数の整数としてフォーマットされます。
パラメータの意味は@code{~D}と同じです。
@c COMMON

@item @b{~X}
@itemx @b{~x}
@c EN
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Hexadecimal output.
The argument is formatted as a hexadecimal integer.
If `@code{X}' is used, upper case alphabets are used for
the digits larger than 10.  If `@code{x}' is used, lower case
alphabets are used.
The semantics of parameters and flags are the same as
the @code{~D} directive.
@c JP
パラメータ: @var{mincol},@var{padchar},@var{commachar},@var{interval}

16進出力。対応する引数が16進数の整数としてフォーマットされます。
フォーマット指示文字に `@code{X}' が与えられた場合は `@code{ABCDEF}' が桁文字として
使われ、 `@code{x}' が与えられた場合は `@code{abcdef}' が桁文字として使われます。
パラメータの意味は@code{~D}と同じです。
@c COMMON

@example
(format #f "~8,'0x" 259847592)
  @result{} "0f7cf5a8"
(format #f "~8,'0X" 259847592)
  @result{} "0F7CF5A8"
@end example

@item @b{~R}
@itemx @b{~r}
@c EN
Parameters: @var{radix},@var{mincol},@var{padchar},@var{commachar},@var{interval}

Radix.  If the argument is an exact number,
the directive @code{~@var{n}R} prints out the argument
in radix @var{n}.  For example, @var{~10R} is the same as @code{~D}.
The @var{radix} parameter must be between 2 and 36, inclusive.
Other paramters are are the same as @code{~D} directive.

If the argument is other than an exact number, it is formatted
just as @code{~A}.

If uppercase @code{R} is used, uppercase alphabets are used
for base-11 and above.  If lowercase @code{r} is used,
lowercase alphabats are used.

If atmark-flag is given, it behaves differently; it prints out the
numeric argument in Roman numerals, e.g. @code{MMXXIII} for 2023.
Adding colon-flag with atmark-flag, it uses a variation of Roman
numerals (@code{IIII} for 4 instead of @code{IV}, for example).
The argument must be a positive exact integer in this case.
Common Lisp only supports up to 4,999 since the Roman numeral 5,000
can't be written in ASCII.  Unicode has Roman numeral up to 100,000,
however, so we support up to 499,999.
Again, the distinction of @code{R} and @code{r}
is reflected to the ASCII alphabets used in the output.

If neither @var{radix} nor atmark-flag is given, Common Lisp
prints the number in English.  We haven't supported it yet,
and an error is raised.
@c JP
パラメータ: @var{radix},@var{mincol},@var{padchar},@var{commachar},@var{interval}

基数(Radix)。引数が正確数であれば、
@code{~@var{n}R}は引数を基数@var{n}の数値としてフォーマットします。
例えば@code{~10R}は@code{~D}と同じです。
@var{radix}パラメータは2以上36以下でなければなりません。
他のパラメータの意味は@code{~D}と同じです。

引数が正確数以外の場合は、@code{~A}のようにフォーマットします。

大文字@code{R}が使われた場合、11進数以上では大文字アルファベットが使われます。
小文字@code{r}の場合は小文字アルファベットが使われます。

アトマークフラグが与えられた場合は違った動作になります。
引数は正の正確な整数でなければならず、それがローマ数字で表示されます
(例えば2023なら@code{MMXXIII}となります)。
アトマークに加えてコロンフラグも与えられると、4を@code{IV}のかわりに@code{IIII}
と表示する変化形を使います。
ローマ数字の5,000はASCIIでは表せないので、Common Lispはこの機能は
4,999までしかサポートしていません。が、Unicodeにはローマ数字が100,000まで
あるので、Gaucheでは499,999までをサポートします。
@code{R}と@code{r}の区別は出力の大文字小文字に反映されます。

@var{radix}もアトマークフラグも与えられない場合、
Common Lispでは引数の数字を英語表記で出力します。
この機能はまだ実装されておらず、エラーが投げられます。
@c COMMON
@example
(format #f "~36R" 123456789) @result{} "21I3V9"
(format #f "~36r" 123456789) @result{} "21i3v9"
(format #f "~@@R" 1999)  @result{} "MCMXCIX"
(format #f "~@@:R" 1999) @result{} "MDCCCCLXXXXVIIII"
(format #f "~@@r" 1999)  @result{} "mcmxcix"
(format #f "~@@R" 123456) @result{} "ↈↂↂMMMCDLVI"
@end example


@item @b{~F}
@c EN
Parameters: @var{width},@var{digits},@var{scale},@var{ovfchar},@var{padchar}

Floating-number output.
If the argument is a real number, it is formatted as a decimal floating number.
The @var{width} parameter defines the width of the field; the number is
written out right-justified, with the left room padded with @var{padchar},
whose default is @code{#\space}.  When the formatted output can't fit
in @var{width}, @var{ovfchar} is output @var{width} times if it is given,
or the entire output is shown if @var{ovfchar} is omitted.
@c JP
パラメータ: @var{width},@var{digits},@var{scale},@var{ovfchar},@var{padchar}

浮動小数点数出力。
引数が実数ならば、その十進小数表現が出力されます。
@var{width}パラメータは出力幅を指定します。もしフォーマット結果がその幅に足りなければ、
左側に@var{padchar}が詰められます。@var{padchar}のデフォルトは@code{#\space}です。
フォーマット結果が@var{width}を越える場合、@var{ovfchar}が指定されていれば、
@var{width}個の@var{ovfchar}が出力され、指定されていなければ@var{width}を無視して
必要なだけの桁数が出力されます。
@c COMMON

@example
(format "~6f" 3.14)          @result{} "  3.14"
(format "~6f" 3.141592)      @result{} "3.141592"
(format "~6,,,'#f" 3.141592) @result{} "######"
(format "~6,,,,'*f" 3.14)    @result{} "**3.14"
@end example

@c EN
The @var{digits} parameter specifies number of digits shown below the
decimal point.  Must be nonnegative integer.  When omitted, enough digits
to identify the flonum uniquely is generated (same as using
@code{write} and @code{display}---when you read back the number, you'll
get exactly the same flonum.)
@c JP
@var{digits}パラメータは小数点以下に表示される桁数を指定します。非負整数でなければなりません。
省略された場合は、引数の浮動小数点数を一意に同定できる最小の精度で出力されます
(@code{write}や@code{display}で出力した場合と同じです。その文字列を@code{read}すれば、
全く同じ浮動小数点数が得られます)。
@c COMMON

@example
(format "~6,3f" 3.141592)    @result{} " 3.142"
(format "~6,0f" 3.141592)    @result{} "    3."
(format "~10,4f" 355/113)    @result{} "    3.1416"
(format "~10,4f" 3)          @result{} "    3.0000"
@end example

@c EN
If the @var{scale} parameter is given, the argument is multiplied by
@code{(expt 10 scale)} before printing.
@c JP
@var{scale}パラメータが与えられた場合、引数が表示前に@code{(expt 10 scale)}倍
されます。
@c COMMON

@c EN
If the @code{@@} flag is given, plus sign is printed before the non-negative
number.
@c JP
@code{@@}フラグが与えられると、引数が非負の場合にプラス記号が出力されます。
@c COMMON

@example
(format "~8,3@@f" 3.141592)   @result{} "  +3.142"
@end example

@c EN
When @var{digits} is smaller than the digits required to represent
the flonum unambiguously, we round at @var{digits}+1 position.  By default,
it is done based on the value the flonum represents---that is, we choose
the rounded value closer to the actual value of the flonum.
It can sometimes lead to unintuitive results, however.  Suppose you want
to round 1.15 at 100ths (that is, round to nearest 10ths).  Unlike
elementary math class, it gives you 1.1.  That's because the flonum
represented by 1.15 is actually tiny bit smaller than 1.15, so it's closer to
1.1 than 1.2.  We show it as 1.15 since no other flonums are closer to
1.15.
@c JP
@var{digits}が浮動小数点数を一意に同定するための桁数に足りない場合は、
小数点以下@var{digits}桁に丸められます。デフォルトでは、この丸めは
浮動小数点数の真の値に基づいて行われます。つまり、真の値に近い方の表現が選ばれます。
これはたまに、非直感的な結果になることがあります。
例えば1.15を1/100の位で丸めて(1/10単位にして)みると、
小学校でやる算数と異なり、1.1が出力されます。
この理由は、1.15と表記される浮動小数点数が実際には1.15よりわずかに小さく、従って
1.1により近いからです。本当は1.15でないものを1.15と表示しているのは、
1.15により近い浮動小数点数が他に無く、1.15が該当する浮動小数点数を一意に同定する
最も短い表現だからです。
@c COMMON

@c EN
But in casual applications, users may perplexed with this behavior.
So we support another rounding mode, which we call notational rounding.
It is based on the notation used for the flonum.  In that mode,
rounding 1.15 to nearest 10ths yields 1.2.  You can get it by
adding @code{:} flag.
@c JP
しかし日常的なアプリケーションでこういう振る舞いがあると、ユーザが混乱してしまうかもしれません。
そこでもう一つ、表示に基づいた丸め(notational rounding)モードを用意しました。
このモードでは、浮動小数点数の表示に基づいた丸めを行います。従って
1.15を1/100の位で丸めると1.2になります。このモードは@code{:}フラグで指定できます。
@c COMMON

@example
(format "~6,1f" 1.15)  @result{} "   1.1"
(format "~6,1:f" 1.15) @result{} "   1.2"
@end example

@c EN
If the argument is a complex number, each of its component is formatted
by @code{~f} with given parameters.  (This behavior differs from Common Lisp,
which prints complex numbers as if @code{~d} is given,
with the @var{width} parameter if any).
@c JP
引数が複素数の場合、各要素が@code{~f}を使って整形されます。
パラメータも各要素に適用されます。(この振る舞いはCommon Lispと異なります。
Common Lispでは@code{~f}に複素数が与えられると、あたかも@code{~d}を使った
かのように整形されます。パラメータは@var{w}だけが考慮されます。)
@c COMMON

@example
(format "~8,3f" 2@@0.1pi) @result{} "1.902+0.618i"
@end example

@item @b{~E}
@c EN
Parameters: @var{width},@var{digits},@var{expdigits},@var{scale},@var{ovfchar},@var{padchar},@var{expchar}

Exponential floating number format.
If the argument is a real number, it is formatted as a decimal floating number
with the exponential part.  Compare @code{~f} and @code{~e}:
@c JP
パラメータ: @var{width},@var{digits},@var{expdigits},@var{scale},@var{ovfchar},@var{padchar},@var{expchar}

指数形式浮動小数点数出力。
引数が実数ならば、その十進小数表現が指数形式で出力されます。
@code{~f}と@code{~e}を比べてみましょう:
@c COMMON

@example
(format "~f" 0.1234) @result{} "0.1234"
(format "~e" 0.1234) @result{} "1.234e-1"
@end example

@c EN
The parameters @var{width}, @var{digits}, @var{scale}, @var{ovfchar}, and
@var{padchar} are the same as @code{~f}.  The @code{@@} flags and
@code{:} flag behave the same, too.

@var{expdigits} specifies the minimum number of digits in the exponent
field:
@c JP
@var{width}、@var{digits}、@var{scale}、@var{ovfchar}、
@var{padchar}パラメータ、および@code{@@}フラグと
@code{:}フラグは@code{~f}と同じです。

@var{expdigits}は指数部の最小桁数を指定します。
@c COMMON

@example
(format "~,,3e" 0.1234) @result{} "1.234e-001"
(format "~,,3e" 1234  ) @result{} "1.234e003"
@end example

@c EN
@var{expchar} specifies the exponent delimiter character, in place
of @code{e}:
@c JP
@var{expchar}は指数部の区切りの文字(デフォルトは@code{e})を置き換えます。
@c COMMON

@example
(format "~,,,,,,'se" 12345) @result{} "1.2345s4"
@end example


@item @b{~G}
@c EN
Parameters: @var{width},@var{digits},@var{expdigits},@var{scale},@var{ovfchar},@var{padchar},@var{expchar}

General floating number format.
This formats the argument like @code{~f}, i.e. without exponent part,
when the argument's absolute value is not
too big or too small, and switches to exponential display like @code{~e} if the
absolute value exceeds the limit.  This is handy when you don't know
the dynamic range of the number.

Parameters and flags behaves the same as @code{~e}.
@c JP
パラメータ: @var{width},@var{digits},@var{expdigits},@var{scale},@var{ovfchar},@var{padchar},@var{expchar}

一般的な浮動小数点数表示。
これは引数の絶対値が大きすぎでも小さすぎでもない時には@code{~f}のように
指数部の無い形式を、限界を超えた場合は@code{~e}のように指数形式を使って
出力します。表示する数の範囲がわかっていない場合に便利です。

パラメータとフラグは@code{~e}と同じです。
@c COMMON

@item @b{~$}
@c EN
Parameters: @var{digits},@var{idigits},@var{width},@var{padchar}

Floating-point formatting suitable for currency display.  The @var{digits}
parameter specifies the number of digits after the decimal point (default 2).
The @var{idigits} parameter specifies the minimum number of digits before
the decimal point (default 1).  The @var{width} parameter specifies the
mininum number of characters for the entire display,
and if the number of printed characters are smaller than it,
@var{padchar} is displayed on the left to fill the blank.  The default
of @var{width} is 0, and the default of @var{padchar} is @code{#\space}.

If @code{@@} flag is given and the argument is nonnegative, @code{+} is
displayed.

If @code{:} flag is given, the sign is displayed first, before any
padding characters.

If the argument isn't a real number, the object is formatted as if
@code{~wD} directive is given (where @var{w} is @var{width}).

Gauche specific: The number is rounded with notational rounding (see the
description of @code{~F} above for the rounding mode).
@c JP
パラメータ: @var{digits},@var{idigits},@var{width},@var{padchar}

通貨の表示に適した浮動小数点数フォーマット。
@var{digits}は小数点以下に表示される桁数で、デフォルトは2です。
@var{idigits}は小数点より前に表示される最小の桁数で、デフォルトは1です。
@var{width}パラメータは全体の最少文字数を指定し、表示すべき文字がそれより少ない場合は
@var{padchar}が左側に足されます。@var{width}のデフォルトは0、
@var{padchar}のデフォルトは@code{#\space}です。

@code{@@}フラグが与えられた場合、非負の値に@code{+}符号が表示されます。

@code{:}フラグが与えられた場合、符号があればそれはパディングより前に表示されます。

引数が実数でない場合は、あたかも@code{~wD} (@code{w}は@var{width}) が指定
されたかのように表示されます。

Gauche特有の機能として、数値は表示に基づいた丸め(notational rounding)で
丸められます。表示に基づいた丸めについては上の@code{~F}の項の説明を参照してください。
@c COMMON

@example
(map (cut format "~$" <>) '(1.23 4.5 6))
  @result{} '("1.23" "4.50" "6.00")
@end example


@item @b{~?}
@c EN
Parameters: None

Recursive formatting.  The argument for this directive must be a string
which is interpreted as a format string.  The arguments for the given directive
should be given in the next argument, as a list.

@example
(format "~s~?~s" '< "~s ~s" '(a b) '>)
  @result{} "<a b>"
@end example

If @code{@@} flag is given, the arguments for the given directive
is taken from the following arguments.

@example
(format "~s~@@?~s" '< "~s ~s" 'a 'b '>)
  @result{} "<a b>"
@end example
@c JP
パラメータ: なし

再帰的フォーマッティング。この指示子はまず文字列を引数に取り、それをフォーマット文字列と
解釈します。そしてさらに次の引数(それはリストでなければなりません)を、そのフォーマット文字列
への引数と解釈します。

@example
(format "~s~?~s" '< "~s ~s" '(a b) '>)
  @result{} "<a b>"
@end example

@code{@@}フラグが与えられた場合は、最初の引数をフォーマット文字列と解釈した後で、
続く引数を必要なだけそのフォーマット文字列の引数として使います。

@example
(format "~s~@@?~s" '< "~s ~s" 'a 'b '>)
  @result{} "<a b>"
@end example
@c COMMON

@item @b{~*}
@c EN
Parameter: @var{count}

Moves the argument counter @var{count} times forward, effectively skips
next @var{count} arguments.  The default value of @var{count} is 1,
hence skip the next argument.  If a colon-flag is given, moves the argument
counter backwards, e.g. @code{~:*} makes the next directive to process
last argument again.  If an atmark-flag is given, @var{count} specifies
absolute position of the arguments, starting from 0.
@c JP
パラメータ: @var{count}

引数のカウンタを@var{count}だけ後方にずらします。つまり、@var{count}個の引数が
無視されることになります。@var{count}のデフォルト値は1です。
コロンフラグが与えられた場合は引数カウンタを前方に動かします。
例えば@code{~:*}は次のディレクティブが直前に使った引数を再び使うようにします。
アトマークフラグが与えられた場合は、@var{count}が引数の絶対位置を示します。
0が最初の引数です。
@c COMMON

@item @b{~P}
@c EN
Parameters: none

Plural.  If argument is an exact integer 1, do nothing.  Otherwise,
print @code{s}.

If an atmark-flag is given, print @code{y} for the argument 1, and
print @code{ies} for other argument values.

If a colon-flag is given, back up one argument before processing.

Note: 1.0 is regarded as plural.
@c JP
パラメータ: なし

複数形(plural)。引数が正確な1であれば何もせず、そうでなければ@code{s}を出力します。

アトマークフラグが与えられた場合は、引数が正確な1なら@code{y}を、
そうでなければ@code{ies}を出力します。

コロンフラグが与えられた場合は、引数をひとつ戻ってから処理します。

註: 1.0は複数とみなされます。
@c COMMON

@example
(format "~a book~:p, ~a book~:p, ~a pon~:@@p, ~a pon~:@@p" 1 2 1 2)
 @result{} "1 book, 2 books, 1 pony, 2 ponies"
@end example


@item @b{~&}
@c EN
Parameter: @var{count}

Fresh line.  If the output position is at the beginning of line,
do nothing; otherwise, output @code{#\newline}, just like
@code{fresh-line} procedure (@pxref{Object output}).

If @var{count} is given and greater than 1, output @code{(- count 1)}
newline characters after the fresh line operation.  If @var{count} is 0,
do nothing.
@c JP
パラメータ: @var{count}

出力位置が行の頭なら何もせず、そうでなければ@code{#\newline}文字を出力します。
@code{fresh-line}手続きと同じです (@ref{Object output}参照)。

もし@var{count}が与えられて1より大きければ、@code{fresh-line}の後に
@code{(- count 1)}個の@code{#\newline}を出力します。
@var{count}が0なら何もしません。
@c COMMON

@item @b{~~}
@itemx @b{~%}
@itemx @b{~t}
@itemx @b{~|}
@c EN
Parameter: @var{count}

Output a @code{#\~}, @code{#\newline}, @code{#\tab} and @code{#\page},
respectively.    If @var{count} is given, output the specified number
of characters.
@c JP
パラメータ: @var{count}

それぞれ、文字@code{#\~}、@code{#\newline}、@code{#\tab}、@code{#\page}を
ひとつ出力します。@var{count}が与えられた場合はその個数出力します。
@c COMMON

@c EN
@item @b{~} followed by newline
@c JP
@item @b{~} とそれに続く改行
@c COMMON
@c EN
Parameters: none

Ignored newline.  As Scheme supports backslash-newline escape in
string literals, this is not necessary, but provided for Common Lisp
compatibility.  Without flags, the newline after the tilde, and any
following whitespace characters (@code{char-whitespace?}) are ignored.
With a colon flag, the newline immediately after the tilde is ignored
but the following whitespace characters are preserved.  With an atmark
flag, the newline immediately after the tilde is kept
but the following whitespace characters are ignored.
@c JP
パラメータ: なし

改行の無視。Schemeはリテラル文字列の中でバックスラッシュ+改行のエスケープで
無視される改行を入れられるのでこれは必要ないのですが、Common Lispとの互換性のために
サポートされています。
フラグが無ければ、チルドに続く改行文字と、そのあとに続く空白文字(@code{char-whitespace?})
を無視します。コロンフラグが与えられたら、チルドの直後の改行文字だけ無視します。
アトマークフラグが与えられたら、
チルド直後の改行文字は残しますが、その後に続く空白文字は無視します。
@c COMMON

@example
(format "abc~\n   def") @result{} "abcdef"
(format "abc~:\n   def") @result{} "abc   def"
(format "abc~@@\n   def") @result{} "abc\ndef"

(format "abc~:\n   \ndef") @result{} "abc   \ndef"
@end example

@item @b{~[}
@c EN
Parameters: none

Conditional formatting.  It can take one of three forms:
@c JP
パラメータ: なし

条件分岐。以下の3つの形をとります。
@c COMMON

@table @asis
@item @b{~[}@i{fmt0}@b{~;}@i{fmt1}@b{~;}...@b{~]}
@c EN
Consume one argument.  If it is not an exact integer, an error
is signaled.  If it is 0, the format string @i{fmt0} is selected.
If it is 1, @i{fmt1} is selected; and so on.  If there's no
corresponding format string, it acts like an empty format string by default.
However, if the last separator is @b{~:;} instead of @b{~;},
the following format string acts as the 'default' format string.
@c JP
引数をひとつ消費します。それが正確な整数でなければエラーが投げられます。
それが0なら@i{fmt0}が、1なら@i{fmt0}が、…という具合に選択されます。
該当するフォーマット文字列が無ければ空のフォーマット文字列として振る舞います。
ただし、最後の区切りを@b{~;}ではなく@b{~:;}にすることで、
それに続くフォーマット文字列を「デフォルト」のフォーマット文字列とすることができます。
@c COMMON

@item @b{~:[}@i{fmt-alternative}@b{~;}@i{fmt-consequence}@b{~]}
@c EN
Consume one argument.  If it is @code{#f}, @i{fmt-alternative} is
selected.  If it is true, @i{fmt-consequence} is selected.
(Note that it is the reverse of @code{if}.  Think false as 0 and true as 1).
@c JP
引数をひとつ消費します。それが偽なら@i{fmt-alternative}が、
真なら@i{fmt-consequence}が選択されます
(@code{if}と順序が逆であることに注意してください。偽を0、真を1と考えると良いでしょう)。
@c COMMON

@item @b{~@@[}@i{fmt-consequence}@b{~]}
@c EN
Peek one argument.  If it is @code{#f}, consume it and ignore
@i{fmt-consequence}.  If it is true, process @i{fmt-consequence}.
Hence, @i{fmt-consequence} usually contains a directive
to consume one argument.
@c JP
引数を消費せずに調べます。それが偽なら、その引数を消費した上で空のフォーマット文字列として
振る舞います。それが真なら、@i{fmt-consequence}を選択します。
従って、@i{fmt-consequence}は通常、引数をひとつ消費するフォーマット指示子を含みます。
@c COMMON
@end table

@example
(map (cut format "~[zero~;one~;two~]" <>) '(0 1 2 3))
  @result{} ("zero" "one" "two" "")
(map (cut format "~[zero~;one~;two~:;other~]" <>) '(0 1 2 3 -1))
  @result{} ("zero" "one" "two" "other" "other")
(map (cut format "~:[no~;yes~]" <>) '(#f #t))
  @result{} ("no" "yes")
(map (cut format "~@@[I got ~a~]" <>) '(#f rhythm))
  @result{} ("" "I got rhythm")
@end example

@item @b{~@{}
@c EN
Parameter: @var{maxiter}

Iteration.  Iterates the body (between @code{~@{} and @code{~@}})
over the elements of a list argument.
@c JP
パラメータ: @var{maxiter}

繰り返し。@code{~@{}と@code{~@}}の間のフォーマット指示を、
リストで与えられる引数の要素に繰り返し適用します。
@c COMMON

@c EN
In the basic form @code{~@{@var{body}~@}}, the next argument must be
a list, and @var{body} is applied repeatedly, consuming elements from
the list on each directive, until all the elements are used up.
Note: If @var{body} has multiple directives and the list is used
up in the middle of @var{body}, an error is signalled.  The list needs
to be used up at the end of iteration.
@c JP
基本的な形@code{~@{@var{body}~@}}では、次の引数はリストでなければ
ならず、@var{body}が繰り返し適用され、そのなかで引数を消費する指示子が
あればそれがリストから順に取られます。全ての要素が消費されたら繰り返しが終わります。
註: @var{body}に複数の指示子があって、@var{body}の途中でリストが使い切られて
しまった場合は、エラーが投げられます。リストは@var{body}の終わりでちょうど
使い切られなければなりません。
@c COMMON

@example
(format "~@{~a ~@}" '(1 2 3))
  @result{} "1 2 3 "

(format "~@{~a ~@}" '())
  @result{} ""
@end example

@c EN
If the @code{@@} flag is given (@code{~@@@{}), the remaining arguments
(instead of a single list argument) are used as the iteration source.
@c JP
@code{@@}フラグが与えられた場合(@code{~@@@{})は、残りの引数全てを
リストみなして、それに対して@var{body}を繰り返します。
@c COMMON

@example
(format "~@@@{~a ~@}" 1 2 3)
  @result{} "1 2 3 "
@end example

@c EN
If the @code{:} flag is given (@code{~:@{}), the argument must be a list
of sublists, and each iteration processes one sublist.
@c JP
@code{:}フラグが与えられた場合(@code{~:@{})は、引数はリストのリストでなければ
なりません。内側のリストが@var{body}への引数リストとして使われます。
@c COMMON

@example
(format "~:@{~a-~a ~@}" '((1 2) (3 4) (5 6)))
  @result{} "1-2 3-4 5-6 "
@end example

@c EN
When both @code{:} and @code{@@} flags are given (@code{~:@@@{}),
each remaining argument is a sublist.
@c JP
@code{:}と@code{@@}の両方のフラグが与えられた場合(@code{~:@@@{})は
両者の組み合わせ、つまり残りの引数はそれぞれがリストで、各リストが
@var{body}への引数リストになります。
@c COMMON

@example
(format "~:@@@{~a-~a ~@}" '(1 2) '(3 4))
  @result{} "1-2 3-4 "
@end example

@c EN
The parameter @var{maxiter} limits the number of iterations.
It must be an exact integer.
@c JP
パラメータ@var{maxiter}が与えられた場合は、それは正確な整数でなければならず、
繰り返しの最高回数を指定します。
@c COMMON

@example
(format "~2@{~a ~@}" '(1 2 3 4 5))
  @result{} "1 2 "
@end example

@c EN
If @code{@@} flag is not given, unused portion of the list argument
are discarded.
If @code{@@} flag is present, the rest of arguments are available
for subsequent directives.
@c JP
@code{@@}フラグがない場合、リスト引数の使われなかった部分は捨てられます。
@code{@@}フラグが与えられた場合は、残りの引数のうち使われなかった部分は
続くフォーマット指示子で使うことができます。
@c COMMON

@c EN
If the closing delimiter has the @code{:} flag (@code{~:@}}),
the body is executed at least once, even if the list is empty.
@c JP
閉じ波括弧に@code{:}フラグが与えられた場合(@code{~:@}})、
入力リストが空でも@var{body}は少なくとも一回、実行されます。
@c COMMON

@example
(format "~@{done ~:@}" '())
  @result{} "done "
@end example

@c EN
If the body is empty (@code{~@{~@}}), the next argument is used as
a format string for the body.
@c JP
@var{body}が空の場合(@code{~@{~@}})、次の引数が
@var{body}のフォーマット文字列として使われます。
@c COMMON

@example
(format "~@{~@}" "~a " '(1 2 3))
  @result{} "1 2 3 "
@end example

@end table
@end defun


@node Low-level output,  , Formatting output, Output
@subsubsection Low-level output
@c NODE 低レベル出力

@defun write-char char :optional port
[R7RS base]
@c EN
Write a single character @var{char} to the output port @var{port}.
@c JP
文字@var{char}をポートに出力します。
@c COMMON
@end defun

@defun write-byte byte :optional port
@defunx write-u8 byte :optional port
[R7RS base]
@c EN
Write a byte @var{byte} to the port.
@var{byte} must be an exact integer in range between 0 and 255.

This is traditionally called @code{write-byte}, and
R7RS calls it @code{write-u8}.  You can use either.
@c JP
出力ポートに1バイトのデータ@var{byte}を書き出します。
@var{byte}は0から255の間の正確な整数でなければなりません。

これは伝統的に@code{write-byte}と呼ばれてきましたが、
R7RSでは@code{write-u8}と名づけています。どちらも使えます。
@c COMMON
@end defun

@defun write-string string :optional oport start end
[R7RS base]
@c EN
If the optional @var{start} and @var{end} arguments are omitted,
it is the same as @code{(display string oport)}.  The optional
arguments restricts the range of @var{string} to be written.
@c JP
@var{start}と@var{end}引数が省略された場合は@code{(display string oport)}と
同じです。それらが与えられた場合は、@var{string}中の指定範囲のみが出力されます。
@c COMMON
@end defun


@defun flush :optional port
@defunx flush-all-ports
@c EN
Output the buffered data in @var{port}, or all ports, respectively.

R7RS's @code{flush-output-port} is the same as @code{flush}.
The @code{scheme.base} module defines the name as an alias to
@code{flush} (@pxref{R7RS base library}).

The function "flush" is called in variety of ways on the various
Scheme implementations: @code{force-output} (Scsh, SCM),
@code{flush-output} (Gambit), or @code{flush-output-port} (Bigloo).
The name @code{flush} is taken from STk and STklos.
@c JP
それぞれ、@var{port}、および全てのポートにバッファされているデータを
全て書き出します。

R7RSでは@code{flush}は@code{flush-output-port}と呼ばれています。
Gaucheでは@code{scheme.base}モジュールで@code{flush}の別名として
提供しています(@ref{R7RS base library}参照)。

手続き"flush"はScheme実装によって様々な名前で呼ばれています：
@code{force-output} (Scsh, SCM)、
@code{flush-output} (Gambit)、@code{flush-output-port} (Bigloo) 等。
@code{flush}の名前はSTkとSTklosから取りました。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Loading Programs, Sorting and merging, Input and output, Core library
@section Loading Programs
@c NODE プログラムのロード

@menu
* Loading Scheme file::
* Loading dynamic library::
* Require and provide::
* Autoload::
* Operations on libraries::
@end menu

@node Loading Scheme file, Loading dynamic library, Loading Programs, Loading Programs
@subsection Loading Scheme file
@c NODE Schemeファイルのロード

@defun load file :key paths (error-if-not-found #t) environment ignore-coding
[R7RS+ load]
@c EN
Loads @var{file}, that is, read Scheme expressions in @var{file} and
evaluates them.
An extension ``@code{.scm}'' may be omitted from @var{file}.

If @var{file} doesn't begin with ``/'' or ``./'' or ``../'',
it is searched from the system file search list,
stored in a parameter @code{(load-paths)}.
Or you can explicitly specify the search path by passing
a list of directory names to the keyword argument @var{paths}.

On success, @code{load} returns the string pathname of the file
actually loaded.
If the specified file is not found, an error is signaled unless
the keyword argument @var{error-if-not-found} is @code{#f}, in
which case @code{load} returns @code{#f}.

By default, @code{load} uses a coding-aware port
(@pxref{Coding-aware ports}) so that the "@code{coding:}" magic
comment at the beginning of the source file is effective.
(See @ref{Multibyte scripts}, for the details of
the coding magic comment).  If a true value is given to the
keyword argument @var{ignore-coding}, @code{load} doesn't
create the coding-aware port and directly reads from the
file port.

If a module is given to the keyword argument @var{environment},
@code{load} works as if the given module is selected at the beginning
of the loaded file.

The current module is preserved; even @code{select-module} is
called in @var{file}, the module in which @code{load} is called
is restored afterwards.

Gauche's @code{load} is upper-compatible to R5RS @code{load}, but
R7RS @code{load} differs in optional arguments; @pxref{R7RS load}.

If you want to load a library file, it's better to use `@code{use}'
(@pxref{Defining and selecting modules}), or `@code{require}' described below.
@xref{Compilation}, for difference between @code{load} and @code{require}.
@c JP
@var{file}をロードします。すなわち、@var{file}に書かれたScheme式を順次読み込んで
評価します。@var{file}の拡張子 (``@code{.scm}'') は省略できます。

@var{file}が ``/'', ``./'' または ``../'' で始まっていない場合は、
システムファイルサーチパス (パラメータ@code{(load-paths)} に格納されています)
の中から該当ファイルが探されます。あるいは、キーワード引数@var{paths}にディレクトリ名の
リストを渡すことによりサーチパスを指定することもできます。

ロードに成功した場合は、実際にロードされたファイルのパス名が文字列で返されます。
指定ファイルがみつからない場合はエラーとなりますが、もしキーワード引数
@code{error-if-not-found}に@code{#f}が与えられていれば単に@code{load}から
@code{#f}が返されます。

デフォルトでは、@code{load}はコーディング認識ポート(@ref{Coding-aware ports}参照)を
使ってソースファイルを読み込むので、ファイル先頭の"@code{coding:}" コメントによる
文字エンコーディング指定が有効になります。
(codingコメントについては@ref{Multibyte scripts}を参照)。
但し、キーワード引数@var{ignore-coding}に真の値が渡された場合、
@code{load}はcoding-aware portを作成せず、直接ファイルポートから
ソースを読み込みます。

キーワード引数@var{environment}にモジュールが渡された場合は、
あたかもそのモジュールがファイルの先頭でselectされたかのように
@code{load}されます。

カレントモジュールは保存されます。つまり、@var{file}中で@code{select-module}によって
カレントモジュールを変更しても、@code{load}が終わったら@code{load}を読んだ時点の
モジュールに戻ります。

Gaucheの@code{load}はR5RSの@code{load}の上位互換ですが、
R7RSの@code{load}は省略可能引数が異なります。@ref{R7RS load}参照。

ライブラリファイルをロードする場合は、`@code{use}' (@ref{Defining and selecting modules}参照) を
使うか、下に説明する`@code{require}' を使う方が良いでしょう。
@code{load}と@code{require}の違いについては@ref{Compilation}を参照してください。
@c COMMON
@end defun

@deffn {Parameter} load-paths
@c EN
A parameter keeping a list of directories that are searched by @code{load},
@code{require}, @code{use}, and @code{include}.

It is important that the value of this parameter is consulted at the compile
time by @code{require}, etc.  Changing it at runtime may not
produce desired results.
If you want to add other directories to the search path globally,
do not modify the value of this parameter directly; use @code{add-load-path},
described below, instead.  It is a special form recognized by the compiler.

If you're writing a meta-compiler, e.g. your code kicks a compiler
as a subcomponent, you may want to @code{parameterize} this value
so that the effect is contained in the dynamic extent of the
subordinate compiler.
@c JP
@code{load}、@code{require}、@code{use}、@code{include}
がファイルを探すディレクトリのリストを保持しているパラメータです。

このパラメータの値は、@code{require}等によってコンパイル時に
参照されることに注意してください。
実行時にこの値を変えても思うように動かないかもしれません。
もしグローバルなサーチパスにディレクトリを追加したい場合は、
この変数を直接変更せずに、下に説明する@code{add-load-path}を用いて下さい。

もし、一種のメタコンパイラ、つまりコンパイラを構成要素として呼び出すようなコード
を書いているなら、その下位のコンパイラの動的エクステントの間だけ
ロードパスを変更するのに@code{parameterize}が使えます。
@c COMMON

@c EN
NB: We used to keep load paths in a global variable @code{*load-path*}.
For the backward compatibility, it is now an identifier macro that expands
into @code{(load-paths)}.  We encourage you to update such code.
@c JP
註: 以前は、ロードパスの情報はグローバル変数@code{*load-path*}に格納されていました。
互換性のため、同名の識別子マクロが定義されていて、@code{(load-paths)}へと
展開されます。古い名前を参照しているコードは@code{load-paths}へ書き換えることを
推奨します。
@c COMMON
@end deffn

@defspec add-load-path path flag @dots{}
@c EN
Adds a path @var{path} to the library load path list.
@var{Path} must be a literal string, for load paths must be
known at compilation time.
If @var{path} is a relative path, it is resolved relative to
the current working directory, unless @code{:relative} flag is given.
@c JP
パス@var{path}をライブラリロードパスのリストに加えます。
ロードパスはコンパイル時に確定している必要があるので、
@var{path}はリテラル文字列でなければなりません。
@var{path}が相対パスの場合、@code{:relative}フラグが与えられて
いなければ、プロセスの現在のワーキングディレクトリからの相対と解釈されます。
@c COMMON

@c EN
@var{Path} doesn't need to exist; nonexisting paths in load path list
are simply ignored.  However, if @var{path} does exist, @code{add-load-path}
searches for architecture-dependent paths; see below.
@c JP
@var{path}は存在する必要はありません。ロードパスに存在しないディレクトリが含まれていても
単に無視されるだけです。ただ、@var{path}が存在する場合、@code{add-load-path}は
アーキテクチャ依存パスも探します。後で詳しく説明します。
@c COMMON

@c EN
Each @var{flag} argument may be one of the followings.
@c JP
以下の値が@var{flag}引数として認識されます。
@c COMMON

@table @code
@item :after
@c EN
Append @var{path} to the end of the current list of load paths.
By default, @var{path} is added in front of the load path list.
@c JP
@var{path}を現在のロードパスリストの末尾に加えます。
デフォルトでは、@var{path}はロードパスリストの先頭に加えられます。
@c COMMON
@item #t
@c EN
The same as @code{:after}.  This is for the backward compatibility.
@c JP
@code{:after}と同じです。互換性のために認識されます。
@c COMMON
@item :relative
@c EN
Interpret @var{path} as a relative path to the directory of
the current file, instead of the current working directory.
If the current file can't be determined (e.g. evaluated in REPL, or
the expression is read from a socket), this flag is ignored.
@c JP
@var{path}を、(カレントワーキングディレクトリではなく)
現在ロード中のファイルのあるディレクトリからの相対パスとして
解釈します。現在ロード中のファイルが不明な場合 (REPLから
評価されたり、ソケットから読まれたりしている場合) は、このフラグは無視されます。
@c COMMON
@end table

@c EN
Use this form instead of changing @code{load-paths} directly.
This form is a special form and recognized by the compiler;
if you change @code{load-paths}, it is in effect at run time,
and that may be too late for @code{use} or @code{require}.
@c JP
ロードパスを変更したい場合、@code{load-paths}を直接替えずにこのフォームを
使って下さい。このフォームはコンパイル時に解釈されるのに対し、@code{load-paths}を
書き換えるコードは実行時に解釈されます。@code{use} や @code{require} は
コンパイル時のロードパスを使うので、@code{load-paths}への変更は反映されないかもしれません。
@c COMMON

@c EN
Furthermore,
@code{add-load-path} looks for the architecture dependent directories
under the specified path and if it exists, sets up the internal
path list for dynamic loading correctly.   Suppose you have
your Scheme module in @code{/home/yours/lib}, and that requires
a dynamic loadable library.  You can put the library under
@code{/home/yours/lib/@var{ARCH}/}, where @var{ARCH} is
the value @code{(gauche-architecture)} returns (@pxref{Environment inquiry}).
Then you can have compiled libraries for multiple platforms and
Gauche can still find the right library.
@c JP
更に、@code{add-load-path}は@var{path}の下にアーキテクチャ依存のディレクトリが
ないかどうかを探し、あればそれを内部の共有ライブラリサーチパスに追加します。
例えばあなたが自分のSchemeモジュールを@code{/home/yours/lib}に入れていて、
それが共有ライブラリを必要としていたとします。手続き@code{gauche-architecture}
(@ref{Environment inquiry}参照)が返す値を@var{ARCH}として、
共有ライブラリを@code{/home/yours/lib/@var{ARCH}/}に置いておくと、
共有ライブラリはそこからロードされます。この方法を取ると、複数のプラットフォーム用に
別々にコンパイルされた共有ライブラリを管理することができます。
@c COMMON
@end defspec

@defun load-from-port port
@c EN
Reads Scheme expressions from an input port @var{port} and evaluates
them, until EOF is read.

Note that unless you pass a coding-aware port to @var{port},
the "@code{coding:}" magic comment won't be handled.
@c JP
入力ポート@var{port}から、EOFを読むまで繰り返しScheme式を読み込み評価します。

@var{port}にコーディング認識ポートを渡さない限り、"@code{coding:}"コメント
による文字コード変換は行われないことに注意して下さい。
@c COMMON
@end defun

@defun current-load-port
@defunx current-load-path
@defunx current-load-history
@defunx current-load-next
@c EN
These procedures allows you to query the current context of loading.
They returns the following values when called inside a file being loaded:
@table @code
@item current-load-port
Returns the port object from which this form is being loaded.
@item current-load-path
Returns the pathname of the file from which this form is being loaded.
Note that this may return @code{#f} if the source of @code{load} is
not a file.
@item current-load-history
Returns a list of pairs of a port and a line number (integer),
representing the nesting of loads.  Suppose you load
@file{foo.scm}, and from its line 7 it loads @file{bar.scm},
and from its line 18 it loads @file{baz.scm}.   If you call
@code{current-load-history} in the file @file{baz.scm}, you'll get
@example
((#<port "foo.scm"> . 7) (#<port "bar.scm"> . 18))
@end example
@item current-load-next
Returns a list of remaining directories to be searched
at the time this file is found.   Suppose the @code{(load-paths)}
is @code{("." "../lib" "/home/gauche/lib" "/share/gauche/lib")}
and you load @file{foo.scm}, which happens to be in @file{../lib/}.
Then, inside @file{foo.scm}, @code{current-load-next} returns:
@example
("/home/gauche/lib" "/share/gauche/lib")
@end example
@end table

When called outside of @code{load}, these procedures returns
@code{#f}, @code{#f}, @code{()} and @code{()}, respectively.
@c JP
これらの手続きによって、現在のロードのコンテクストを知ることができます。
ロードされているファイルの中でこれらの手続きを呼ぶと、次のような値が返されます。
@table @code
@item current-load-port
現在のフォームがロードされている入力ポート。
@item current-load-path
現在のフォームがロードされているファイル。
ロードのソースがファイルでない場合、この値は@code{#f}。
@item current-load-history
入力ポートと行番号のペアのリストで、ロードのネスティングを示したもの。
例えばあなたが@file{foo.scm}をロードし、そのファイルの7行目で
@file{bar.scm}がロードされ、そのファイルの18行目で@file{baz.scm}が
ロードされたとします。@code{current-load-history}を@file{baz.scm}中で
呼ぶと、それは次のような値を返します。
@example
((#<port "foo.scm"> . 7) (#<port "bar.scm"> . 18))
@end example
@item current-load-next
現在のファイルがロードされた時点での、ファイルサーチパスの残りを返します。
例えば @code{(load-paths)} が
@code{("." "../lib" "/home/gauche/lib" "/share/gauche/lib")}で、
あなたが@file{foo.scm}をロードしたところ、それが@file{../lib/}中に見つかったと
しましょう。このとき、@file{foo.scm}中で@code{current-load-next}を呼べば
@example
("/home/gauche/lib" "/share/gauche/lib")
@end example
が返されます。
@end table

@code{load}されていない状態で呼ばれた時は、これらの手続きはそれぞれ@code{#f}、
@code{#f}、@code{()}、@code{()}を返します。
@c COMMON
@end defun


@node Loading dynamic library, Require and provide, Loading Scheme file, Loading Programs
@subsection Load dynamic library
@c NODE ダイナミックライブラリのロード

@defun dynamic-load file :key init-function
@c EN
Loads and links a dynamic loadable library (shared library) @var{file}.
@var{File} shouldn't contain the suffix (``.so'' on most systems);
@code{dynamic-load} adds it, for it may differ among platforms.

The keyword argument @var{init-function} specifies the initialization
function name of the library in a string.  By default, if the file
basename (without extension) is ``foo'', the initialization function
name is ``Scm_Init_foo''.

Usually a dynamic loadable library is provided with wrapping Scheme
module, so the user doesn't have to call this function directly.

There's no way to unload the loaded libraries.
@c JP
ダイナミックローダブルライブラリ(共有ライブラリ)@var{file}をロードしてリンクします。
@var{file}にはサフィックス(``.so'' 等) を含めないで下さい。システムによって
サフィックスは異なるため、@code{dynamic-load}がそれを追加します。

キーワード引数@var{init-function}は共有ライブラリ中の初期化関数の名前を
指定します。デフォルトでは、サフィックスを除くファイル名が ``foo'' の場合、
初期化関数名は ``Scm_Init_foo'' となります。

通常、共有ライブラリはSchemeモジュール中でロードされるので、モジュールユーザが
直接この手続きを呼ぶ必要はほとんどないでしょう。

一度ロードされた共有ライブラリをアンロードすることはできません。
@c COMMON
@end defun


@node Require and provide, Autoload, Loading dynamic library, Loading Programs
@subsection Require and provide
@c NODE requireとprovide

@c EN
@code{Require} and @code{provide} are a traditional Lisp way to ensure
loading a library file only once.  If you require a @emph{feature}
for the first time, a library file that provides it is loaded
and the fact that the @emph{feature} is provided is memorized.
Subsequent request of the same feature doesn't need to load the file.
@c JP
@code{require}と@code{provide}は、Lispでライブラリファイルを一度だけ
読み込むことを保証するための伝統的な方法です。
ある@emph{feature}を最初に@code{require}すると、その機能を提供する
ライブラリファイルがロードされ、その機能が提供されたということが記憶されます。
2回め以降のその@emph{feature}のリクエストではファイルはロードされません。
@c COMMON

@c EN
In Gauche, the @code{use} syntax (@pxref{Using modules}) hides
the require mechanism under the hood so you hardly need to see
these forms.  These are provided just in case if you want to
do some non-trivial management of libraries and thus want to
bypass Gauche's standard mechanism.
@c JP
Gaucheでは@code{use}構文 (@ref{Using modules}参照) が
requireのメカニズムをボンネットの下に隠してくれるので、
これらの式を直接目にする必要はほとんどありません。
もしあなたがちょっと変わった方式でライブラリを構成したくて、したがって
Gaucheの標準的なメカニズムをバイパスしたい場合に限り、使うようにしてください。
@c COMMON

@defspec require feature
@c EN
If @var{feature} is not loaded, load it.  @var{Feature} must be a string,
and it is taken as a file name (without suffix) to be loaded.
This loading takes place at compile time.

If you load SLIB module, @code{require} is extended.  @pxref{SLIB} for
details.
@c JP
@var{feature}がまだロードされていなければロードします。@var{feature}は文字列で
なければなりません。それがそのまま(サフィックスを除く)ファイル名としてロードパスから
探されます。@code{require}の解釈はコンパイル時に行われます。

SLIBモジュールをロードすると、@code{require}が拡張されます。詳しくは@ref{SLIB}を
参照して下さい。
@c COMMON

@c EN
If the loaded file does not contain @code{provide} form at all,
the @var{feature} is automatically provided, as if
@code{(provide @var{feature})} is called at the end of the loaded
file.  We call this @emph{autoprovide} feature.
@c JP
もしロードされたファイルが@code{provide}フォームを含んでいなかった場合、
あたかもファイルの最後に@code{(provide @var{feature})}があったかのように、
@var{feature}が自動的にprovideされます。これを
@emph{autoprovide}機能と呼んでいます。
@c COMMON

@c EN
Note that @code{require} first sets the current module to
an immutable module called @code{gauche.require-base}
and then load the file.  The files
loaded by @code{require} usually have @code{define-module}/@code{select-module}
or @code{define-library} for the first thing, so you rarely notice the
@code{gauche.require-base} module.  However, if the loaded file
has toplevel defines or imports (@code{use}'s) without specifying
a module, you'll get an error like the following:
@c JP
@code{require}は、ファイルをロードする前に現在のモジュールを
@code{gauche.require-base}という変更不可なモジュールにセットします。
@code{require}されるファイルは通常、最初に@code{define-module}/@code{select-module}
か@code{define-library}フォームを持つので、この@code{gauche.require-base}モジュール
を目にすることはほとんど無いでしょう。
ただ、もしロードされたファイルがモジュールを指定すること無くトップレベルの
変数を定義したり他のモジュールを@code{import}(@code{use})しようとした場合、
次のようなエラーとなります。
@c COMMON

@example
*** ERROR: Attempted to create a binding (a) in a sealed
module: #<module gauche.require-base>
@end example

@c EN
Rationale: Generally it's difficult to guarantee
when the specified file is loaded by @code{require} (because some other
module may already have required it).  If we just used the caller's current
module, there would be a couple of issues: The form @code{define-module} or
@code{define-library} may not be visible from the current module, and
you can't guarantee if the toplevel defines without specifying modules
in the loaded file inserts the caller's current module, since they may
have been loaded into a different module.
It is just a bad idea to insert
toplevel definitions or to import other modules without specifying which
module you put them in.  So we made them an error.
@c JP
理由: @code{require}されているファイルがどのタイミングで読まれるかを
正確にコントロールするのは難しいです(他のモジュールが既にrequireしているかも
しれないので)。もし呼び出し側の現在のモジュールをそのまま使った場合、二つの
問題が生じ得ます。(1)呼び出し側の現在のモジュールから、
@code{define-module}や@code{define-library}が見えているとは限りません。
(2)モジュールを指定しないトップレベル定義が呼び出し側の現在のモジュールに
定義を追加することは保証されません(既に別のモジュールへと読みこまれているかもしれません)。
モジュールを指定しないトップレベル定義やimportを持つファイルをrequireすることは、
単に悪いアイディアです。したがってそういう事例はエラーとすることにしました。
@c COMMON
@end defspec

@defun provide feature
@c EN
Adds @var{feature} to the system's provided feature list, so that
the subsequent @code{require} won't load the same file again.
@c JP
@var{feature}をシステムのprovideされたフィーチャーリストに加えます。
以降、@var{feature}が@code{require}されてもファイルはふたたびロードされません。
@c COMMON

@c EN
Because of the autoproviding, i.e. @code{require}
automatically provides the required feature, you hardly need to
use a @code{provide} form explicitly.   There are a couple of scenarios that
you may want to use a @code{provide} form:
@c JP
@code{require}が要求された機能を自動的に@code{provide}されたかのように
扱うAutoprovide機能があるために、@code{provide}を明示的に呼ぶ必要は
ほとんど無いでしょう。@var{provide}を使いたいシチュエーションとしては
次のようなものが考えられます。

@c COMMON

@itemize
@item
@c EN
To provide a feature (or features) that is/are different from
the one that caused loading the file.

Suppose feature X supersedes feature Y and providing
compatible APIs of Y but with different implementation.
Once @file{X.scm} is loaded, you don't want @file{Y.scm} to be loaded;
so you want to tell the user that @file{X.scm} also provides the feature Y.
Adding @code{(provide "X")} and @code{(provide "Y")} at the end of
@file{X.scm} accomplish that.  (Note: If you add a provide form,
@code{require} no longer autoprovides the feature, so you need
to specify @code{(provide "X")} in @file{X.scm} explicitly to
provide X as well.)

Of course, this doesn't prevent users from loading @file{Y.scm} by
specifying @code{(require "Y")} before @code{(require "X")}.
It should be considered just as a workaround in a production
where other solutions are costly, instead of a permanent solution.
@c JP
そのファイルをロードすることになったfeatureとは異なるfeature (複数可) を
provideしたい場合。

例えばfeature Xがfeature Yを置き換えるものだとします。
XはYのAPIを全て提供しますが、実装は異なります。この場合、
@file{X.scm}が一度ロードされたら、@file{Y.scm}をロードしてほしくないと思うでしょう。
@file{X.scm}に @code{(provide "X")} と @code{(provide "Y")} の両方を
書いておくことで、@file{X.scm}がfeature Yもprovideすると明示すれば、それが実現できます。
(注：@code{provide}が呼ばれると、@code{require}のautoprovide機能は
抑制されるため、@file{X.scm}中で@code{(provide "X")}も指定する必要があります。)

もちろんこのの方法では、ユーザが @code{(require "Y")} を @code{(require "X")}
より先に書いてしまったら@file{Y.scm}はロードされてしまいます。
この方法は、現場において、永久的な解決が高コストになるような場合のとりあえずの
回避処置と考えるべきでしょう。
@c COMMON

@item
@c EN
To provide no features at all.  Passing @code{#f} as @var{feature}
prevents autoproviding by @code{require} without providing any
feature.

This should also be a temporary solution.  One possible scenario is
that you are changing @file{X.scm} very frequently during
development and you want @code{(require "X")} always causes loading
the file.  Don't forget to remove @code{(provide #f)} when you release
the file, though.  Besides, for interactive reloading, consider
using @code{gauche.reload} (@pxref{Reloading modules}) instead.
@c JP
featureを全く@code{provide}しない。
@var{feature}引数に@code{#f}を渡すことで、何のfeatureも@code{provide}することなく
@code{require}によるautoprovidingを抑制できます。

これもまた、何らかの一時的な解決と考えるべきです。たとえば開発中に、
@file{X.scm}を頻繁に変更するために@code{(require "X")}が常に
そのファイルをロードするようにさせたい、といった場合が考えられます。
@file{X.scm}のリリースの前に @code{(provide #f)} を消しておくことを
忘れないように。また、インタラクティブにリロードしたいならば
@code{gauche.reload} (@ref{Reloading modules}参照) を使うことを
おすすめします。
@c COMMON
@end itemize

@end defun

@defun provided? feature
@c EN
Returns @code{#t} if @var{feature} is already provided.
@c JP
@var{feature}が既にprovideされていれば@code{#t}を返します。
@c COMMON
@end defun

@node Autoload, Operations on libraries, Require and provide, Loading Programs
@subsection Autoload

@defmac autoload file/module item @dots{}
@c EN
Sets up @var{item} @dots{} to be autoloaded.
That is, when an @var{item} is referenced for the first time,
@var{file/module} is loaded before the @var{item} is evaluated.
This delays the loading of @var{file/module} until it is needed.
@c JP
@var{item} @dots{} がオートロードされるように設定します。すなわち、
次に@var{item}が参照された時、それが実際に評価される前に@var{file/module}がロード
されるようにします。これによって、必要とされる時まで@var{file/module}のロードを遅らせる
ことができます。
@c COMMON

@c EN
You can specify either a string file name or a symbol module name
to @var{file/module}.  If it is a string, the named file is
loaded.  If it is a symbol, the named module is loaded (using the
same rule as of @code{use}), then the binding of @var{item} in the
@var{file/module} is imported to the module used the autoload
(@xref{Defining and selecting modules}, for details of @code{use}).
@c JP
引数@var{file/module}には、文字列かシンボルを指定できます。文字列の場合は
そのファイルがロードされます。シンボルの場合、その名のモジュールが(@code{use}と
同じルールで)ロードされ、@var{item}が@var{file/module}から
オートロードを呼び出したモジュールへとインポートされます。
(モジュールの@code{use}の詳細については@ref{Defining and selecting modules}を参照して下さい)。
@c COMMON

@c EN
@var{Item} can be either a variable name (symbol),
a form @code{(:macro @var{symbol})},
or a form @code{(:id-macro @var{symbol})},
If it is a symbol,
the named file/module is loaded when the variable is
about to be evaluated.  If it is the latter form,
the named file/module is loaded when the symbol
is about to be dealt with the compiler as a macro call
or as an identifier macro call,
which enables autoloading macros.
(@xref{Identifier transformer}, for the identifier macros).
@c JP
@var{item}は変数名(シンボル)か、@code{(:macro @var{symbol})}というフォーム
でなければなりません。変数名の場合は、その変数が評価されようとした時に
指定のファイル／モジュールがロードされます。後者のフォームの場合は、
そのシンボルがマクロ呼び出し(あるいは識別子マクロ呼び出し)として
コンパイルされようとした時に指定のファイル／モジュールがロードされます。
後者はマクロのオートロードになります。
(識別子マクロについては@ref{Identifier transformer}を参照してください。)
@c COMMON

@c EN
@var{file/module} must define @var{symbol} in it, or an error is signaled
when @var{file/module} is autoloaded.
@c JP
@var{symbol}は@var{file/module}の中で定義されなければなりません。
そうでなければロード時にエラーが報告されます。
@c COMMON

@c EN
The following is an example of autoloading procedures.
@c JP
手続きのオートロードの例を示します。
@c COMMON
@example
(autoload "foo" foo0 foo1)
(autoload "bar" bar0 bar1)

(define (foobar x)
  (if (list? x)
      (map bar0 x)
      (foo0)))

@c EN
(foobar '(1 2)) ; @r{"bar" is loaded at this moment}

(foobar #f)     ; @r{"foo" is loaded at this moment}
@c JP
(foobar '(1 2)) ; @r{この時点で "bar" がロードされる}

(foobar #f)     ; @r{この時点で "foo" がロードされる}
@c COMMON
@end example

@c EN
Note that if you set to autoload macro, the file/module is loaded
immediately when such form that uses the macro is compiled,
regardless of the piece of
the code is executed or not.
@c JP
マクロのオートロードを設定した場合、指定のファイルまたはモジュールは、
そのマクロを使っているフォームが実行されるされないにかかわらず、
コンパイラがそのフォームを見た時点でロードされることに注意してください。
@c COMMON
@end defmac

@node Operations on libraries,  , Autoload, Loading Programs
@subsection Operations on libraries
@c NODE ライブラリの操作

@c EN
There are several procedures you can use to check if
certain libraries and/or modules are installed in the system.

In the following descriptions, @var{pattern} is either a
symbol or a string.  If it is a symbol, it specifies
a module name (e.g. @code{foo.bar}).  If it is
a string, it specifies a partial pathname of the library
(e.g. @code{"foo/bar"}), which will be searched under
library search paths.
You can also use glob-like metacharacters @code{*} and
@code{?} in @var{pattern}.
@c JP
ある特定のライブラリおよび/あるいはモジュールがシステムにインストールされ
ているかどうかをチェックするための手続きがいくつかあります。

以下の説明の中では、@var{pattern}はシンボルまたは文字列です。シンボル
である場合にはモジュール名(たとえば、@code{foo.bar})を指定します。
文字列である場合にはライブラリの部分パス(たとえば、@code{"foo/bar"})を
指定します。これはライブラリサーチパス以下で検索されます。
@var{pattern}には@code{glob}のメタ文字と同じ意味で @code{*} と @code{?} を
使うこともできます。
@c COMMON

@defun library-fold pattern proc seed :key paths strict? allow-duplicates?
@c EN
A basic iterator for library/module files.
This procedure searches Scheme program files which matches
@var{pattern}, under directories listed in @var{paths}
(the default is the standard file load paths, @code{(load-paths)}).
For each matched file, it calls @var{proc} with three arguments:
the matched module or library name, the full path of the program
file, and the state value.  @var{Seed} is used as the initial
state value, and the value @var{proc} returns is used as the state
value for the next call of @var{proc}.  The value returned from
the last @var{proc} becomes the return value of @code{library-fold}.
@c JP
ライブラリ/モジュールファイルに対する基本イテレータ。この手続きは
@var{pattern} にマッチする Scheme のプログラムファイルを検索します。
検索は @var{paths} (デフォルトは標準のファイルロードパス、
@code{load-paths})にリストされたディレクトリ以下でおこなわれます。
マッチしたファイル毎に、@var{proc} が、そのマッチしたモジュール名あるいは
ライブラリ名、そのプログラムファイルのフルパス、状態値、の3つの引数を
ともなって呼びだされます。@var{seed}は、初期状態値として使われ、
@var{proc} が返す値は次の @var{proc} の呼出し時に状態値として使われます。
最後の @var{proc} から返された値は @code{library-fold} の値として返ります。
@c COMMON

@c EN

@c JP
@c COMMON

@c EN
If @var{pattern} is a symbol and the keyword argument @var{strict?}
is @code{#t} (which is the default), this procedure calls
@code{library-has-module?} on the files whose name seems to
match the given pattern of module name, in order to find out
the file really implements the module.  It can be a time consuming
process if you try to match large number of modules; you can pass
@code{#f} to @var{strict?} to avoid the extra check.
If @var{pattern} is a string, matching is done only for file names
so @var{strict?} is ignored.
@c JP
@var{pattern} がシンボルでかつ、キーワード引数 @var{strict?} が
@code{#t} (デフォルト値)であれば、この手続きは
あたえられたモジュール名のパターンにマッチするようにみえるファイル名に
たいして @code{library-has-module?} を適用して、
本当にそのモジュールを実装しているファイルを見付けます。
大量のモジュールにマッチさせようとすると、時間がかる可能性があります。
@code{#f} を @var{strict?} に渡すことで、余分なチェックを回避できます。
@var{pattern} が文字列だった場合、照合はファイル名に対してのみ行われ、
@var{strict?}は無視されます。
@c COMMON

@c EN
By default, if there are more than one files that have the same name
that matches @var{pattern} in @var{paths}, only the first
one appears in @var{paths} is taken.  This gives you
the file you'll get if you use @code{require} or @code{use}
for that library.  If you want to iterate all of matching files,
pass @code{#t} to the @var{allow-duplicates?} keyword argument.

Here are some examples (the result may differ in your environment).
@c JP
デフォルトでは、@var{path} 中の @var{pattern} にマッチする同じ名前をもつ
2つ以上のファイルがあるばあい、@var{path} に最初に出現したものだけが
採用されます。そのライブラリに対して、@code{require} あるいは
@code{use} を用いたをつかった場合に得られるのはこのファイルです。
すべてのマッチしたファイルについて反復したければ、@var{allow-duplicates?}
キーワード引数に @code{#t} を渡します。
@c COMMON
@c EN
@example
(library-fold 'srfi.1 acons '())
 @result{} ((srfi.1 . "../lib/srfi/1.scm"))

(library-fold "srfi.1" acons '())
 @result{} (("srfi.1" . "../lib/srfi/1.scm"))

;; Note the returned list is in a reverse order of
;; how @code{acons} is called.
(library-fold 'srfi.1 acons '() :allow-duplicates? #t)
 @result{} ((srfi.1 . "/usr/share/gauche-0.98/0.9.13/lib/srfi/1.scm")
   (srfi.1 . "../lib/srfi.1.scm"))

;; Finds available dbm implementations
(library-fold 'dbm.* acons '())
 @result{} ((dbm.cdb . "/usr/share/gauche-0.98/0.9.13/lib/dbm/cdb.scm")
   (dbm.gdbm . "../lib/dbm/gdbm.scm")
   (dbm.ndbm . "../lib/dbm/ndbm.scm")
   (dbm.odbm . "../lib/dbm/odbm.scm"))
@end example
@c JP
@example
(library-fold 'srfi.1 acons '())
 @result{} ((srfi.1 . "../lib/srfi/1.scm"))

(library-fold "srfi.1" acons '())
 @result{} (("srfi.1" . "../lib/srfi/1.scm"))

;; @code{acons} が呼ばれるのとは逆順のリストが
;; 返ることに注意してください
(library-fold 'srfi.1 acons '() :allow-duplicates? #t)
 @result{} ((srfi.1 . "/usr/share/gauche-0.98/0.9.13/lib/srfi/1.scm")
   (srfi.1 . "../lib/srfi.1.scm"))

;; 利用可能な dbm の実装を見付けます
(library-fold 'dbm.* acons '())
 @result{} ((dbm.cdb . "/usr/share/gauche-0.98/0.9.13/lib/dbm/cdb.scm")
   (dbm.gdbm . "../lib/dbm/gdbm.scm")
   (dbm.ndbm . "../lib/dbm/ndbm.scm")
   (dbm.odbm . "../lib/dbm/odbm.scm"))
@end example
@c COMMON
@end defun

@defun library-map pattern proc :key paths allow-duplicates? strict?
@defunx library-for-each pattern proc :key paths allow-duplicates? strict?
@c EN
@code{Map} and @code{for-each} version of iterator over matched
libraries/modules.  See @code{library-fold} above for detailed
operation of matching and the meanings of keyword arguments.

@var{Proc} receives two arguments, the matched module/library name
and full path of the file.  @code{Library-map} returns a list
of results of @var{proc}.  @code{Library-for-each} discards
the results.
@c JP
マッチしたライブラリ/モジュール上のイテレータの @code{map}版および
@code{for-each}版。照合操作とキーワード引数の詳細については上述の
@code{library-fold}を参照してください。

@var{proc}は、マッチしたモジュール/ファイル名と、そのファイルの
フルパスの 2 つの引数をうけとります。@code{library-for-each} は
結果を捨てます。
@c COMMON

@example
(library-map 'srfi.4 list :allow-duplicates? #t)
 @result{} ((srfi.4 "../lib/srfi/4.scm")
            (srfi.4 "/usr/share/gauche-0.98/0.9.13/lib/srfi/4.scm"))

(library-map 'dbm.* (lambda (m p) m))
 @result{} (dbm.odbm dbm.ndbm dbm.gdbm dbm.cdb)
@end example
@end defun

@defun library-exists? mod/path :key paths force-search? strict?
@c EN
Search a library or a module specified by @var{mod/path},
and returns a true value if it finds one.  @var{Paths} and @var{strict?}
keyword arguments have the same meaning as @code{library-fold}.

Unlike the iterator procedures above, this procedure first
checks loaded libraries and modules in the calling process,
and returns true if it finds @var{mod/path} in it,
without looking into the filesystem.   Passing @code{#t} to
@var{force-search?} keyword arguments skips the checking of
loaded libraries and modules.
@c JP
@var{mod/path} で指定されたライブラリあるいはモジュールを検索し、
もしあれば、真値を返します。キーワード引数 @var{paths} および
@var{strict?} は @code{library-fold} のそれと同じ意味です。

上述のイテレータ手続きとはちがい、この手続きは呼び出しの過程で
最初に既にロードされているライブラリおよびモジュールをチェックします。
もしそのときに @var{mod/path} を見つけたら、真値を返し、ファイル
システムを見にいくことはありません。キーワード引数 @var{force-search?}
に @code{#t} を渡せば、すでにロードされいるライブラリおよびモジュール
のチェックはスキップされます。
@c COMMON
@end defun


@defun library-has-module? path module
@c EN
Returns @code{#t} iff a file specified by @var{path} exists and
appears to implement a module named by @code{module}.  @var{path} must be
an actual filename.
@c JP
@var{path} で指定したファイルが存在し、かつ、@code{module} で名指しされた
モジュールが実装されている場合でその場合に限り、@code{#t} を返します。
@var{path} は実際のファイル名でなければなりません。
@c COMMON

@example
(library-has-module? "./test/foo/bar.scm" 'foo.bar)
 @result{} #t ;; @r{if ./test/foo/bar.scm implements module foo.bar}.
@end example

@c EN
This procedure assumes a typical layout of the source code
to determine if the given file implements the module, i.e.,
it reads the first form of the code and see if it is a
@code{define-module} form that is defining the given module.
@c JP
この手続きは典型的なソースコードの配置を仮定して、与えられたファイルが
そのモジュールを実装しているかどうかを決定します。すなわち、
まずそのコードのフォームを読み、与えられたモジュールを定義している
@code{define-module} フォームかどうかを見ます。
@c COMMON
@end defun

@c ----------------------------------------------------------------------
@node Sorting and merging, System interface, Loading Programs, Core library
@section Sorting and merging
@c NODE ソートとマージ

@c EN
The interface of sorting and merging API complies SRFI-95, with the
following extensions:
@c JP
ソートとマージのインタフェースはSRFI-95に準拠し、さらに次の点で拡張されています。
@c COMMON

@itemize @bullet
@item
@c EN
You can sort not only lists, vectors and strings, but
any sequence (an instance of @code{<sequence>}).
@c JP
リスト、ベクタ、文字列だけでなく、あらゆるシーケンス
(@code{<sequence>}のインスタンス)をソートできます。
@c COMMON
@item
@c EN
You can use both comparison procedures
and comparators (@pxref{Basic comparators}) to specify the order.
@c JP
順序を指定するのに、比較関数も比較器(@ref{Basic comparators}参照)も
使うことができます。
@c COMMON
@item
@c EN
You can omit comparison procedure; in that case,
elements are compared with @code{default-comparator}.
@c JP
比較関数を省略できます。省略された場合、
要素同士は@code{default-comparator}を使って比較されます。
@c COMMON
@end itemize

@defun sort seq :optional cmp keyfn
@defunx sort! seq :optional cmp keyfn
[SRFI-95+]
@c EN
Sorts elements in a sequence @var{seq}
in ascending order and returns the sorted sequence.
@code{sort!} destructively reuses the original sequence.

You can pass an instance of any @code{<sequence>} as @var{seq};
the same type of sequence will be returned.  For @code{sort}, the
sequence type must have builder interface so that @code{sort} can
build a new sequence of the same type (See @ref{Fundamental iterator creators},
for the builder interface).
For @code{sort!}, @var{seq} must be mutable.

The sorting order is specified by @code{cmp}.  It must be
either a procedure or a comparator.
If it is a procedure, it
must take two elements of @var{seq}, and returns @code{#t}
if the first argument strictly precedes the second.
If it is a comparator, it must have the comparison procedure.
If omitted, @code{default-comparator} is used.

If the optional argument @var{keyfn} is given, the elements are
first passed to it and the results are used for comparison.
It is guaranteed that @var{keyfn} is called at most once per
element.
@c JP
シーケンス@var{seq}の要素を昇順にソートし、
ソートされたシーケンスを返します。
@code{sort!}は、オリジナルのシーケンスを破壊的に再利用します。

@var{seq}には@code{<sequence>}クラスのインスタンスを渡すことができます。
同じ型のシーケンスが返されます。@code{sort}の場合、
@var{seq}と同じ型のシーケンスを新たに作る必要があるので、
@var{seq}の型はビルダーインタフェースを実装していなければなりません
(ビルダーインタフェースについては@ref{Fundamental iterator creators}を参照)。
@code{sort!}の場合、@var{seq}は変更可能でなければなりません。

ソート順は@code{cmp}で指定されます。これは手続きか比較器でなければなりません。
手続きの場合は、@var{seq}のふたつの要素を
引数に取り、最初の要素が厳密に2番目の要素より先行する場合に
@code{#t}を返します。
比較器の場合は、比較手続きを持つものでなければなりません。
省略された場合は@code{default-comparator}が使われます。

省略可能な手続き引数@var{keyfn}が与えられた場合、
要素はまず@var{keyfn}に渡され、その結果が比較に使われます。
@var{keyfn}は各要素に対してたかだか1回しか呼ばれないことが保証されます。
@c COMMON

@example
(sort '(("Chopin" "Frederic")
        ("Liszt" "Franz")
        ("Alkan" "Charles-Valentin"))
      string<?
      car)
  @result{} (("Alkan" "Charles-Valentin")
      ("Chopin" "Frederic")
      ("Liszt" "Franz"))
@end example

@c EN
In the current implementation, quicksort and heapsort
algorithm is used when both @var{cmp} and @var{keyfn} is omitted,
and merge sort algorithm is used otherwise.  That is, the sort
is stable if you pass at least @var{cmp} (note that to guarantee
stability, @var{cmp} must return @code{#f} when given identical arguments.)
SRFI-95 requires stability, but also requires @var{cmp} argument,
so those procedures are upper-compatible to SRFI-95.
@c JP
現在の実装では、@var{cmp}が省略された場合は
クィックソートとヒープソートを使い、
@var{cmp}が与えられた場合はマージソートを使っています。
すなわち、少なくとも@var{cmp}を指定すれば、ソートは安定であることが
保証されます (ただし、安定であるためには
@var{cmp}は等しい引数が与えられた時に必ず@code{#f}を返さなければなりません)。
SRFI-95は安定性を要求しますが、同時に@var{cmp}が与えられることも要求するので、
これらの手続きはSRFI-95の上位互換です。
@c COMMON

@c EN
If you want to keep a sorted set of objects to which you
add objects one at at time, you can also use treemaps
(@pxref{Treemaps}).  If you only need to find out
a few maximum or minimum elements instead of sorting
all the elements, heaps can be used (@pxref{Heap}).
@c JP
なお、オブジェクトをひとつづつ集合に追加しつつ、常にソートされた
状態に保ちたい場合は、treemapの使用を考えても良いでしょう (@ref{Treemaps}参照)。
また、最大または最小から数要素だけを必要とする場合は、
全ての要素をソートするかわりにヒープが使えます (@ref{Heap}参照)。
@c COMMON
@end defun

@defun sorted? seq :optional cmp keyfn
[SRFI-95+]
@c EN
Returns @code{#t} iff elements in @var{seq} are in sorted order.
You can pass any sequence to @var{seq}.
The optional argument @var{cmp} and @var{keyfn} are the same as
@code{sort}.

In SRFI-95, @var{cmp} can't be omitted.
@c JP
@var{seq}の要素がソートされている時に限り@code{#t}を返します。
@var{seq}にはどんなシーケンスを渡すこともできます。
省略可能引数@var{cmp}と@var{keyfn}の意味は@code{sort}と同じです。

SRFI-95では@var{cmp}は必須になっています。
@c COMMON
@end defun


@defun merge a b :optional cmp keyfn
@defunx merge! a b :optional cmp keyfn
[SRFI-95+]
@c EN
Arguments @var{a} and @var{b} are lists, and their elements are
sorted using a compare function or a comparator @var{cmp}.  These procedures
merges two list and returns a list, whose elements are sorted
using @var{cmp}.  The destructive version @code{merge!} reuses
cells in @var{a} and @var{b}; the returned list is @code{eq?} to
either @var{a} or @var{b}.

In SRFI-95, @var{cmp} can't be omitted.
@c JP
引数@var{a}と@var{b}はリストで、比較関数または比較器@var{cmp}によって
既にソートされているものとします。これらの手続きは二つのソート済みリストを
マージして、ソートされた一つのリストにします。@code{merge!}は破壊的バージョンで、
@var{a}と@var{b}のセルを再利用します。戻り値は@var{a}か@var{b}に対して@code{eq?}と
なります。

SRFI-95では@var{cmp}は必須になっています。
@c COMMON
@end defun

@c EN
The following procedures are for the backward compatibility.  Their
features are already covered by extended @code{sort} and @code{sort!}.
@c JP
以下の手続きは後方互換性のために残されていますが、その機能は
拡張された@code{sort}および@code{sort!}によってカバーされています。
@c COMMON


@defun stable-sort seq :optional cmp keyfn
@defunx stable-sort! seq :optional cmp keyfn
@c EN
Sort a sequence @var{seq}, using stable sort algorithm.
Arguments @var{cmp} and @var{keyfn} are the same as @code{sort}
and @code{sort!}.

In fact, @code{sort} and @code{sort!} now uses stable algorithm
when @var{cmp} is provided, so these procedures are redundant,
unless you want to omit @var{cmp} and yet guarantee stable sort.
@c JP
安定ソートアルゴリズムを使って、シーケンス @var{seq}をソートします。
@var{cmpfn}と@var{keyfn}引数は@code{sort}および@code{sort!}と同じです。

実のところ、現在では@var{sort}と@var{sort!}は@var{cmp}が与えられれば
安定ソートアルゴリズムを使うので、これらの手続きは
どうしても@var{cmp}を省略しつつ安定ソートしたい、という場合でなければ
使う必要はありません。
@c COMMON
@end defun

@defun sort-by seq keyfn :optional cmp
@defunx sort-by! seq keyfn :optional cmp
@defunx stable-sort-by seq keyfn :optional cmp
@defunx stable-sort-by! seq keyfn :optional cmp
@c EN
Variations of sort procedures that takes a key extracting function.
These are redundant now, for @code{sort} etc. takes optional @var{keyfn}.
@c JP
比較のためのキーを取り出す関数を取る、ソート手続きの別バージョンです。
@code{sort}等の手続きが省略可能な@var{keyfn}を取るようになったので、
現在ではこれらの関数は冗長です。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node System interface, Development helper API, Sorting and merging, Core library
@section System interface
@c NODE システムインタフェース

@c EN
Gauche supports most of POSIX.1 functions and other system functions
popular among Unix variants as built-in procedures.
@c JP
GaucheはPOSIX.1の多くの関数と、さまざまなUnixで共通して使われているシステム関数へのインタフェースを
組込み手続きとして提供しています。
@c COMMON

@c EN
Lots of Scheme implementations provide some sort of system interface
under various APIs.  Some are just called by different names
(e.g, @code{delete-file} or @code{remove-file} or @code{unlink} to delete
a file), some do more abstraction introducing new Scheme objects.
Instead of just picking one of such interfaces, I decided to implement
Gauche's system interface API in two layers; the lower level layer,
described in this section, follows the operating system's API
as close as possible.  On top of that, the higher-level APIs are
provided, with considering compatibility to the existing systems.
@c JP
多くのScheme実装はいろいろな形で何らかのシステムインタフェースを提供
しています。名前だけが違うもの(例：@code{delete-file}、@code{remove-file}
、@code{unlink}) もあれば、新しいSchemeオブジェクトを導入して
抽象化を行っているものもあります。Gaucheでは、既存のAPIのどれかを
そのまま真似るのではなく、2つのレイヤを提供することにしました。
この章で述べられる低レベルレイヤは、OSのインタフェースに似せたものを実装します。
その上に、既存のシステムと互換性のある高レベルのインタフェースが実装されます。
@c COMMON

@c EN
The low level system interface has the name @code{sys-}@var{name}
and usually correspond to the system call @var{name}.
I tried to keep the interface similar whenever reasonable.
@c JP
@code{sys-}@var{name}という名前を持つ手続きは、多くの場合、
システムコール@var{name}に対応しています。
可能な限り、インタフェースが似るようにしました。
@c COMMON

@c EN
Gauche restarts a system call after it is interrupted by a signal by default.
See @ref{Signal} for the details.
@c JP
なお、システムコールがシグナルによって割り込まれた場合、
そのシステムコールは原則としてリスタートされます。
詳しくは@ref{Signal}を参照して下さい。
@c COMMON

@c EN
If you are familiar with system programming in C,
see also @ref{C to Scheme mapping}, which shows
correspondence between C standard library functions
and Gauche procedures.
@c JP
Cによるシステムプログラミングに慣れている方は、
@ref{C to Scheme mapping}も参考にして下さい。
Cの標準ライブラリとGaucheの手続きとの対応が示してあります。
@c COMMON

@menu
* Program termination::
* Command-line arguments::
* Environment inquiry::
* Filesystems::
* Unix groups and users::
* Locale::
* Signal::
* System inquiry::
* Time::
* Process management::
* I/O multiplexing::
* Garbage collection::
* Memory mapping::
* Miscellaneous system calls::
@end menu

@node Program termination, Command-line arguments, System interface, System interface
@subsection Program termination
@c NODE プログラムの終了

@c EN
Gauche has a few ways to terminate itself (other than returning
from @code{main}).  The @code{exit} procedure is a graceful way
with all proper cleanups.  @code{sys-exit} and @code{sys-abort}
may be used in emergency where proper cleanup is impossible.
@c JP
Gaucheは(@code{main}から返る以外に)自分自身を終了させる方法をいくつか
提供しています。@code{exit}手続きが、正しいクリーンアップを行って
優雅に終了する方法です。一方、正しいクリーンアップが不可能な非常事態には
@code{sys-exit}か@code{sys-abort}を使います。
@c COMMON


@defun exit :optional (code 0) (fmtstr #f) args @dots{}
[R7RS+ process-context]
@c EN
Terminates the current process with the exit code @var{code}.
The optional @var{code} argument specifies the exit status; @code{#t}
indicates a success (exit code 0),
@code{#f} indicates a failure (exit code 1),
and an exact integer specifies other exit code (only the lower 8 bits are
used).  Any other values of @var{code} makes the exit code to be
70 (@code{EX_SOFTWARE}.
Note that R7RS does not specify how @var{code} is translated to OS's
exit status, except that @code{#t} indicates a success and @code{#f}
indicates a failure.  Portable code should only pass @code{#t} or @code{#f}.

When a string is given to @var{fmtstr}, it is passed to
@code{format} (@pxref{Output}), with the rest arguments @var{args},
to produce a message to the standard error port
(@emph{not} the current error port; see @ref{Common port operations}).
@c JP
現在のプロセスを終了し、@var{code}を終了コードにします。
@var{code}が@code{#t}なら成功を意味し、終了コードは0に、
@var{code}が@code{#f}なら失敗を意味し、終了コードは1に、
そして正確な整数の場合はその下位8bitが終了コードとして使われます。
@var{code}がそれ以外のオブジェクトの場合は、
終了コードは70 (@code{EX_SOFTWARE})になります。
(R7RSでは、@code{code}は@code{#t}の時正常終了、@code{#f}のとき異常終了を示す
ということ以外に、具体的にOSレベルのどういった値になるかは規定していません。
ポータブルなコードでは@code{#t}か@code{#f}のみを使うのが良いでしょう。)

@var{fmtstr}文字列が与えられた場合、それは残りの引数@var{args}と
ともに@code{format}に渡され、standard error portにメッセージとして
印字されます (@code{current-error-port}ではありません。
@ref{Common port operations}参照。また、@code{format}については
@ref{Output}参照。)
@c COMMON

@c EN
In fact, the exiting procedure is a bit more complicated.
The precise steps of exiting is as follow.
@c JP
実のところ、プロセス終了の手続きはもう少し複雑です。
正確な段階を次に説明します。
@c COMMON

@enumerate
@item
@c EN
The value of parameter @code{exit-handler} is checked.
If it is not @code{#f}, the value is called as a procedure
with three arguments: @var{code}, @var{fmtstr}, and a list of rest
arguments.  It is the default procedure of @code{exit-handler}
that prints out the message to the standard error port.
If an error occurs within exit handler, it is captured and
discarded.  Other exceptions are not caught.
@c JP
パラメータ@code{exit-handler}の値がチェックされます。
もしそれが@code{#f}でなければ、それは3引数の手続きとみなされ、
@var{code}、@var{fmtstr}、そして残りの引数のリストを引数として
呼び出されます。実はメッセージを標準エラー出力に出しているのは
デフォルトの@code{exit-handler}です。
終了ハンドラの中でエラーが起きた場合、そのエラーは捕捉され捨てられます。
エラー以外の例外は捕捉されません。
@c COMMON

@item
@c EN
The @var{after} thunks of the active dynamic winds are invoked.
Any exceptions raised in @var{after} thunks are captured and discarded.
@c JP
アクティブな@code{dynamic-wind}の@var{after}サンクが順に呼び出されます。
@var{after}サンク中で発生した例外は捕捉され捨てられます。
@c COMMON

@item
@c EN
The clean-up handlers registered via C API @code{Scm_AddCleanupHandler}
are invoked.  These are usually responsible for under-the-hood cleanup
jobs for each application that embeds Gauche.  From the Scheme world
there's not much to care.
@c JP
C APIの@code{Scm_AddCleanupHandler}で登録されたクリーンアップハンドラが
呼ばれます。このハンドラは通常、Gaucheを内蔵しているアプリケーション特有の
クリーンアップをするために使われます。Schemeの世界からはあまり気にする必要は
ないでしょう。
@c COMMON

@item
@c EN
The unclosed output buffered ports are flushed.
@c JP
まだ閉じられていない出力ポートのバッファが掃き出されます。
@c COMMON

@item
@c EN
The process exits with an integer derived from @var{code}
as an exit code, via @code{exit(3)}.
@c JP
@code{exit(3)}を呼び、プロセスは@var{code}から導出される整数値を終了コードとして終了します。
@c COMMON
@end enumerate

@c EN
The @code{exit-handler} mechanism allows the application to hook its
exit operation.   Note that it is not for simple cleanup jobs;
@code{dynamic-wind}, @code{guard} or @code{unwind-protect} are more appropriate.
@code{exit-handler} is for more specific use just upon application exit.
For example, GUI applications may want to post a dialog
instead of printing to stderr.

For this reason, the library code shouldn't change @code{exit-handler};
only the application knows what to do when it exits.

Another useful case is when you
want to call a third-party code which calls @code{exit} inside.  In
that case you may swap the @code{exit-handler} for the one
that raises a non-error exception while calling the third-party code.
Non-error exception isn't caught in @code{exit}, effectively
interrupts the steps explained above.   (Yet the @var{after} thunks
of dynamic handlers are processed just like normal exception
handling case.)
Your application code can then capture the exception.
You can use @code{parameterize}
to swap @code{exit-handler} dynamically
and thread-safely (@pxref{Parameters}).
@c JP
@code{exit-handler}のメカニズムはアプリケーションが終了処理をフックすることを
可能にします。ただし、単純なクリーンアップ処理のためのものではありません
(クリーンアップ処理には
@code{dynamic-wind}, @code{guard}あるいは@code{unwind-protect}を使う方が
適切です。)
@code{exit-handler}はもっと「アプリケーションの終了」という特定の事態に
対して何か処理を行いたい場合に使います。
例えばGUIアプリケーションはメッセージを標準エラー出力ではなく
ダイアログとして表示する、というようなことです。

従って、ライブラリコードは@code{exit-handler}に触るべきではありません。
アプリケーションの終了時に何をすべきかを知っているのはアプリケーション自身なのですから。

別の使いどころとしては、サードパーティ製のコードで中で@code{exit}が
呼ばれる可能性のあるものを安全に呼び出したいという場合があります。
そのコードを呼び出している間だけ、@code{exit-handler}を
エラーではない例外を発生させる手続きへと差し替えます。
エラーではない例外は@code{exit}では捕捉されないので、実質的に
上で説明したような終了処理のステップは中断されることになります
(但し、ダイナミックハンドラの@var{after}サンクは通常の例外発生時と
同じように処理されます)。
アプリケーションコードの方でその例外を捕捉してやればよいのです。
@code{parameterize}を使えば@code{exit-handler}を動的に、
かつスレッドセーフに差し替えることが容易になります
(@ref{Parameters}参照)。
@c COMMON

@example
(guard (e [(eq? e 'exit-called) (handle-exit-as-desired)])
  (parameterize ((exit-handler (lambda (c f a) (raise 'exit-called))))
    (call-third-party-library)))
@end example

@c EN
Generally, calling @code{exit} while other threads are running
should be avoided, since it only rewinds the dynamic handlers active
in the calling threads, and other threads will be killed abruptly.
If you have to do so for some reason,
you may be able to use @code{exit-handler} to tell to other threads
that the application is exiting.  (There's no general way, and
Gauche doesn't even have a list of all running threads; it's application's
responsibility).
@c JP
一般的に、他のスレッドが走っている時に@code{exit}を呼ぶことは推奨されません。
@code{exit}手続きは該当スレッド上でアクティブなダイナミックハンドラしか巻き
戻さないので、他のスレッドはいきなり終了させられてしまいます。
しかし@code{exit}を呼ばざるを得ない場合には、
@code{exit-handler}を使って他のスレッドにアプリケーションが終了しつつあることを
伝えられるかもしれません (但しGauche自身は走っているスレッドのリストといった
情報は持っていないので、アプリケーションごとに固有のロジックを実装する必要が
あります。)
@c COMMON

@c EN
Note on design: Some languages integrates exit handling
into exception handling, treating exit as a kind of exception.
It is a tempting idea, so much that we've tried it.  It didn't
work out well in Gauche; a big annoyance was that when
an @var{after} thunk raised an exception during
rewinding @code{dynamic-wind}s, it shadowed the original
@emph{exit} exception.
@c JP
設計に関する覚書: 終了を一種の例外とすることで、
終了処理を例外処理と統合している言語もあります。
良いアイディアに思えたので我々もそのような実装を試してみましたが、
Gaucheではうまくいきませんでした。大きな理由のひとつは、
@code{dynamic-wind}の巻き戻し中に@var{after}で例外が
発生すると、その例外がもともとの「終了」例外を隠してしまうことでした。
@c COMMON
@end defun

@deffn {Parameter} exit-handler
@c EN
A parameter that holds an exit handler, a procedure to be called
when @code{exit} is called.  It takes three arguments,
the exit code, the format string and the list of arguments for the format
string.  See @code{exit} above for the details.

Its value can also be @code{#f}, in that case, no handler will
be called.

The default handler shows the formatted message to
the standard error port.

If the handler raises an error, it is captured and discarded.
If the handler raises other conditions, it won't be captured
and propagate to outer controls.
@c JP
@code{exit}が呼ばれた時に呼び出されるexit handlerを保持するパラメータです。
exit handlerは、終了コード、フォーマット文字列、フォーマット文字列の引数のリスト、
の3つの引数を取る手続きです。上の@code{exit}の項を参照してください。

exit handlerの値は@code{#f}にすることもできます。
その場合はハンドラは呼ばれません。

デフォルトのハンドラは、与えられた引数でフォーマットした文字列を
標準エラー出力に出します。

ハンドラがエラーを投げた場合、それは補足され無視されます。
エラー以外のコンディションを投げた場合は補足されないので、
外側の制御機構に処理が任されます。
@c COMMON
@end deffn

@defun sys-exit code
[POSIX]
@c EN
Terminates the current process with the exit code @var{code}.
If @var{code} is @code{#t}, the exit code is 0;
if it is @code{#f}, the exit code is 1;
if it is an exact integer, its lower 8 bits is used for the
exit code.  If @var{code} is any other value,
exit code is 70 (@code{EX_SOFTWARE}).
(This is the same as @code{exit}).

This procedure calls @code{_exit(2)} directly.
No cleanup is done.  Unflushed file output is discarded.
@c JP
現在のプロセスを終了し、@var{code}を終了コードにします。
@var{code}が@code{#t}なら終了コードは0、
@code{#f}なら終了コードは1、
そして正確な整数の場合は下位8bitが終了コードとして使われます。
それ以外の値では終了コードは70 (@code{EX_SOFTWARE})になります。
(@code{exit}と同じです)。

この手続きは@code{_exit(2)}を直接コールします。
クリーンアップは一切行われません。
フラッシュされてないファイルバッファの内容は捨てられます。
@c COMMON
@end defun

@defun sys-abort
[POSIX]
@c EN
Calls POSIX abort().  This usually terminates the running process
and dumps core.  No cleanup is done.
@c JP
POSIXのabort()を呼びます。通常、現在のプロセスは終了され、コアダンプされます。
クリーンアップは一切行われません。
@c COMMON
@end defun

@node Command-line arguments, Environment inquiry, Program termination, System interface
@subsection Command-line arguments
@c NODE コマンドライン引数

@c EN
The recommended way to get command-line arguments passed to a
Scheme script is the argument to the @code{main} procedure
(@pxref{Writing Scheme scripts}).  For the convenience,
there are a few ways to access to the command-line arguments
globally.
@c JP
Schemeスクリプトに渡されたコマンドライン引数を受け取るには、
@var{main}関数の引数を使うのが推奨される方法です
(@pxref{Writing Scheme scripts})。
ただ、簡便のために、どこからでもコマンドライン引数にアクセスできる
インターフェースもいくつか用意してあります。
@c COMMON

@c EN
Note that a Scheme code may not always be called with a command-line
argument---for example, an application-embedded Scheme scriptlet may
not have the concept of command-line at all.  That's why the @code{main}
argument is preferred, since it is an explicit interface; if @code{main}
is called, the caller is responsible to pass in something.
@c JP
Schemeコードが実行される時、常にコマンドライン引数が存在するわけではない
ことに注意してください。例えばアプリケーションに埋め込まれたSchemeコード片にとっては、
コマンドライン引数は意味を持ちません。なるべく@code{main}関数の引数を使うべき、
というのはそのためです。@code{main}関数の引数は明示的だからです。
@code{main}が呼ばれたなら、呼び出す側は意識してコマンドライン引数を渡している
わけですから。
@c COMMON

@c EN
That said, here are how to access the command-line arguments:
@c JP
この注意を念頭に置いておいてください。
以下にコマンドライン引数にアクセスする方法を示します。
@c COMMON

@deffn {Parameter} command-line
[R7RS+ process-context][SRFI-193]
@c EN
When called without arguments, it returns a list of command-line arguments,
including the program name in the first element, as a list of strings.
@c JP
引数なしで呼ばれた場合は、コマンドライン引数のリストを文字列のリストとして返します。
最初の要素はプログラム名です。
@c COMMON

@c EN
When Gauche is used as an embedded language, it is application's discretion
to set up this parameter.  If the application does nothing, this parameter
will have an empty list.  When you use this parameter in the library
you have to deal with that situation.
@c JP
Gaucheが埋め込み言語として使われた場合、このパラメータの値はアプリケーションの
設定に依存します。アプリケーションが何もしていなければ、
このパラメータの値は空リストとなります。ライブラリ中でこのパラメータの値を
使う場合は、その可能性を念頭に置いてください。
@c COMMON

@c EN
When called with one argument, a list of string, it will become the
new value of the parameter.  You can use @code{parameterize} to
switch the value of @code{command-line} dynamically
(@pxref{Parameters}).  Note that R7RS only defines zero-argument
@code{command-line}.
@c JP
一つの引数で呼び出すこともできます。その場合、引数は文字列のリストでなければなりません。
渡された引数が、新たなパラメータの値となります。
@code{parameterize}を使って@code{command-line}の値を
動的に変えることができます (@ref{Parameters}参照)。
R7RSは、ゼロ引数の@code{command-line}のみ定義しています。
@c COMMON
@end deffn

@deffn {Parameter} script-file
[SRFI-193]
@c EN
While a Scheme program is run as a @emph{script}, this parameter holds
the absolute path of the Scheme source file being run.  Run as a script
means either it is passed as the script file to @code{gosh}, or
the file is directly @code{load}ed from the toplevel REPL.

If this function is called from the context outside of script execution,
@code{#f} is returned.
@c JP
Schemeプログラムが@emph{スクリプト}として実行されている期間中、
このパラメータはそのスクリプトの絶対パスを保持しています。
スクリプトとして実行とは、@code{gosh}にスクリプトファイルとして渡されるか、
トップレベルREPLから直接@code{load}される場合です。

この関数がスクリプト実行期間中以外に呼ばれた場合は@code{#f}が返ります。
@c COMMON
@end deffn


@defvar *program-name*
@defvarx *argv*
@c DEPRECATED
@c EN
These variables are bound to the program name and the list of command-line
arguments, respectively.  In Gauche scripts that are invoked by @code{gosh}
command, @code{*program-name*} is usually the name of the script, as
given to @code{gosh}.  When @code{gosh} is invoked interactively,
@code{*program-name*} contains a zero-length string @code{""},
and @code{*argv*} is an empty list.

These variables exist in @code{user} module.

They are mainly kept for the backward compatibility.
These names are compatible to STk, but other Scheme implementation uses
different conventions.  The @code{command-line} parameter above is
preferred.

When Gauche is used as an embedded language, it's the host application's
discretion to set up these variables.  Generally, you can't count on
those variables to exist.  That's another reason you should avoid
using them.
@c JP
これらの変数はそれぞれ、プログラム名および、コマンドライン引数のリストに束縛されます。
@code{gosh}を使ってGaucheスクリプトを実行しているなら、@code{*program-name*}は
(@code{gosh}に与えられたとおりの) スクリプト名になっています。@code{gosh}が
インタラクティブREPLとして起動された場合は@code{*program-name*}は
空文字列@code{""}で、@code{*argv*}は空リストです。

これらの変数は@code{user}モジュールにあります。

これは主として互換性のためだけに残されています。STkと互換な名前ですが、
他のScheme実装へはポータブルではありません。上の@code{command-line}パラメータの
方がお勧めです。

Gaucheが埋め込み言語として使われている場合、これらの変数を設定するかどうかは
ホストアプリケーションに任されます。一般には、これらの変数が必ず存在している
とは限りません。これもまた、他の方法を使うべき理由です。
@c COMMON
@end defvar


@node Environment inquiry, Filesystems, Command-line arguments, System interface
@subsection Environment inquiry
@c NODE 環境の問い合わせ

@defun sys-getenv name
[POSIX]
@c EN
Returns the value of the environment variable @var{name} as a string,
or @code{#f} if the environment variable is not defined.

For the portable code, you may want to use SRFI-98's
@code{get-environment-variable} (@pxref{Accessing environment variables}),
which is also in R7RS.

Note: Most systems doesn't guarantee thread-safety of @code{getenv} while
environment is being modified; however, Gauche mutexes environment
accessing/mutating APIs internally, so you don't need to worry
about the race condition as far as you use Gauche procedures.
@c JP
環境変数@var{name}の値を文字列で返します。もし@var{name}が定義されていなければ、
@code{#f}が返ります。

ポータブルなコードでは、SRFI-98およびR7RSの@code{get-environment-variable}を
使うのが良いでしょう(@ref{Accessing environment variables}参照)。

註: 多くのシステムでは、環境が変更されている最中の@code{getenv}のスレッド安全性を
保証していませんが、Gaucheは内部的に環境へのアクセスと変更のAPIを排他制御しているので、
Gaucheの手続きを使っている限りにおいてはスレッド安全です。
@c COMMON
@end defun

@defun sys-environ
@c EN
Returns the current environment as a list of strings.  Each string
is a form of @code{NAME=VALUE}, where @code{NAME} is the name of
the environment variable and @code{VALUE} is its value.  @code{NAME}
never contains a character @code{#\=}.  This is useful when you want
to obtain the all environment variables of the current process.
Use @code{sys-getenv} if you want to query a specific environment
variable.
@c JP
現在の環境を文字列のリストとして返します。それぞれの文字列は
@code{NAME=VALUE}というフォーマットになっています。ここで@code{NAME}は
環境変数名、@code{VALUE}はその値です。@code{NAME}が文字@code{#\=}を含
むことはありません。この手続きは現在のプロセスの環境変数をすべて取得し
たい場合に便利です。特定の環境変数の値が欲しい場合には
@code{sys-getenv}を使ってください。
@c COMMON
@end defun

@defun sys-environ->alist :optional envlist
@c EN
A convenience procedure for @code{sys-environ}.  When the list of
environment strings (like what @code{sys-environ} returns) is given
to @var{envlist}, this procedure splits name and value of
each environment variable and returns an assoc list.
@c JP
@code{sys-environ}の便利版。環境リスト(@code{sys-environ}が返すような
形式のもの)を@var{envlist}として与えると、この手続きは各環境変数を名前
と値に分けて連想リストにして返します。
@c COMMON

@c EN
When @var{envlist} is omitted, this procedure calls @code{sys-environ}
to get the current environment variables.
@c JP
@var{envlist}を省略すると、この手続きは@code{sys-environ}を呼んで現在
の環境変数を取得します。
@c COMMON

@c EN
For the portable code, you may want to use SRFI-98's
@code{get-environment-variables} (@pxref{Accessing environment variables}),
which is also in R7RS.
@c JP
ポータブルなコードでは、SRFI-98およびR7RSの
@code{get-environment-variables} (@ref{Accessing environment variables}参照),
を使うのが良いでしょう。
@c COMMON

@example
(sys-environ->alist '("A=B" "C=D=E"))
  => (("A" . "B") ("C" . "D=E"))
@end example
@end defun


@defun sys-setenv name value :optional overwrite
@defunx sys-putenv name=value
@c EN
@var{sys-setenv} inserts an environment variable @var{name} with
the value @var{value}.
Both @var{name} and @var{value} must be a string.
If the optional argument @var{overwrite} is @code{#f} (default),
the environment is untouched if a variable with @var{name} already
exists.   If @var{overwrite} is true, the variable is overwritten.
@c JP
@var{sys-setenv}は環境変数@var{name}とその値@var{value}を
プロセスの実行環境に挿入します。
ただし、省略可能引数@var{overwrite}が@code{#f}(デフォルト値)の場合、
@var{name}が既に存在したら実行環境は変更されません。
@var{overwrite}が真の値であれば、環境変数は上書きされます。
@c COMMON

@c EN
For @code{sys-putenv}, you have to give a single string
with the form of @code{NAME=VALUE}, that is, concatenating @var{name}
and @var{value} with @code{#\=}.  If the environment variable with
the same name exists, it will be overwritten.
@c JP
@code{sys-putenv}では、環境変数を名前と値を@code{#\=}でつないだ
@code{NAME=VALUE}という形式で指定します。
同名の環境変数が既に存在する場合は常に上書きされます。
@c COMMON

@c EN
These API reflects POSIX @code{setenv(3)} and @code{putenv(3)}.
However, unlike @code{putenv(3)}, modifying the string passed
to @code{sys-putenv} afterwards won't affect the environment.
@c JP
これらのAPIはPOSIXの@code{setenv(3)}と@code{putenv(3)}のインタフェースを
反映しています。しかし、@code{putenv(3)}と違って
@code{sys-putenv}に渡した文字列はコピーされるので、後でその文字列を
破壊的変更してもプロセスの実行環境に影響はありません。
@c COMMON

@c EN
These procedures are only available when a feature identifier
@code{gauche.sys.setenv} exists.  Use @code{cond-expand}
(@pxref{Feature conditional}) to check their availability.
@c JP
これらの手続きは機能識別子@code{gauche.sys.setenv}がある場合のみ使えます。
下の例のように@code{cond-expand}で使えるかどうかチェックしてください
(@ref{Feature conditional}参照)。
@c COMMON

@example
(cond-expand
 [gauche.sys.setenv
   ... use sys-setenv or sys-putenv ... ]
 [else
   ... fallback code ...])
@end example

@c EN
These procedures are thread-safe as far as you access and modify
the environment through Gauche API.
@c JP
これらの手続きは、他の方法で環境変数を変更しない限り、スレッドセーフです。
@c COMMON
@end defun

@defun sys-unsetenv name
@defunx sys-clearenv
@c EN
Remove the environment variable with @var{name} (@code{sys-unsetenv}),
or all environment variables.  @code{sys-clearenv} is handy
when you need to run subprocess, but you cannot trust the inherited
environment.

These procedures are only available when a feature identifier
@code{gauche.sys.unsetenv} exists.  Use @code{cond-expand}
(@pxref{Feature conditional}) to check their availability.
@c JP
@code{sys-unsetenv}は環境変数@var{name}を、また
@code{sys-clearenv}は全ての環境変数をプロセスの実行環境から取り除きます。
@code{sys-clearenv}は、子プロセスを走らせる際に予期せぬ環境変数を
注入されないようにするのに便利です。

これらの手続きは機能識別子@code{gauche.sys.unsetenv}がある場合のみ使えます。
下の例のように@code{cond-expand}で使えるかどうかチェックしてください
(@ref{Feature conditional}参照)。
@c COMMON

@example
(cond-expand
 [gauche.sys.unsetenv
   ... use sys-unsetenv or sys-clearenv ... ]
 [else
   ... fallback code ...])
@end example
@end defun


@c EN
SRFI-98 (@pxref{Accessing environment variables}) also defines
a subset of above procedures to access to the environment variables.
Portable programs may want to use them instead.
@c JP
SRFI-98 (@ref{Accessing environment variables}参照) にも、
環境変数を読み出すための、上記の手続きのサブセットにあたるものが
定義されています。ポータブルなコードにしたければそちらも見てみてください。
@c COMMON


@defun gauche-version
@defunx gauche-architecture
@defunx gauche-library-directory
@defunx gauche-architecture-directory
@defunx gauche-site-library-directory
@defunx gauche-site-architecture-directory
@c EN
These functions returns a string that tells information about Gauche
runtime itself.
@c JP
これらの手続きはGaucheランタイムの情報を文字列で返します。
@c COMMON
@end defun

@defun version-alist
[SRFI-176]
@c EN
Returns an alist of various runtime information.
The information is the same as what displayed with @code{gosh -V}.
@c JP
様々なランタイムの情報をalistで返します。
@code{gosh -V}で表示される情報と同じです。
@c COMMON

@c EN
The result is affected by the value of the environemnt variable
@code{GAUCHE_VERSION_INFO_EXCLUSION}.  @xref{Environment variables},
for details.
@c JP
結果は環境変数@code{GAUCHE_VERSION_INFO_EXCLUSION}に影響を受けます。
詳しくは@ref{Environment variables}を参照してください。
@c COMMON
@end defun

@defun sys-available-processors
@c EN
Returns the number of available processors on the running platform.
Return value is always a positive exact integer.  If Gauche can't
get the information, 1 is returned.

However,
If an environment variable @code{GAUCHE_AVAILABLE_PROCESSORS} is
defined and its value can be interpreted as a positive integer,
then the value is returned regardless of what the hardware/OS tells.
@c JP
現在Gaucheが走っているプラットフォームで使えるプロセッサの個数を返します。
戻り値は常に正の正確な整数です。Gaucheがこの情報を入手できなかった場合は
1が返ります。

但し、もし環境変数@code{GAUCHE_AVAILABLE_PROCESSORS}が定義されていて、
その値が正の整数と解釈できるものだった場合、ハードウェア/OSがどう言おうと
環境変数の値が返されます。
@c COMMON
@end defun

@node Filesystems, Unix groups and users, Environment inquiry, System interface
@subsection Filesystems
@c NODE ファイルシステム

@c EN
System calls that deal with filesystems.
See also @ref{Filesystem utilities}, which defines high-level APIs
on top of the procedures described here.
@c JP
ファイルシステムに関するシステムコール群です。
ここで述べる手続きの上に、より高レベルなAPIがモジュール@code{file.util}として
実装されています。@ref{Filesystem utilities}を参照して下さい。
@c COMMON

@menu
* Directories::
* Directory manipulation::
* Pathnames::
* File stats::
* Other file operations::
@end menu

@node Directories, Directory manipulation, Filesystems, Filesystems
@subsubsection Directories
@c NODE ディレクトリ

@c EN
See also @ref{Directory utilities} for high-level API.
@c JP
高レベルAPIに関しては@ref{Directory utilities}も参照して下さい。
@c COMMON

@defun sys-readdir path
@c EN
@var{path} must be a string that denotes valid pathname of an existing
directory.  This function returns a list of strings of the directory
entries.  The returned list is not sorted.  An error is signaled
if @var{path} doesn't exists or is not a directory.
@c JP
@var{path}は存在するディレクトリを示すパス名でなければなりません。
この手続きはディレクトリの全エントリを文字列のリストとして返します。
リストはソートされません。@var{path}が存在しなかったり、ディレクトリでなかった場合は
エラーとなります。
@c COMMON
@end defun

@defun glob pattern :key separator folder sorter
@defunx sys-glob pattern :key separator folder sorter
@c EN
Provides a traditional Unix glob(3) functionality;
returns a list of pathnames that matches the given @var{pattern}.
@c JP
伝統的なUnixのglob(3)の機能を提供します。この手続きは@var{pattern}とマッ
チするパス名のリストを返します。
@c COMMON

@c EN
This feature used to be a wrapper of system-provided @code{glob} function,
hence it was named @code{sys-glob}.  However, as of Gauche version 0.8.12,
it was reimplemented in Scheme on top of other system calls, to overcome
incompatibilities between platforms and for the opportunity to put
more functionalities.  So we renamed it @code{glob}.
The old name @code{sys-glob} is kept for compatibility, but new
programs should use @code{glob}.
@c JP
この機能は、かつてはプラットフォームが提供する@code{glob}関数をラップする
もので、@code{sys-glob}という名前でした。しかし、プラットフォーム間の非互
換性を解消し機能の追加を容易にするために、Gauche 0.8.12以降、システムコー
ルの上にSchemeで再実装されています。そのため、@code{glob}と改名してあ
ります。古い方の名前@code{sys-glob}は互換性のために残してありますが、
新たにプログラムを書くときは@code{glob}を使ってください。
@c COMMON

@c EN
The @var{pattern} argument may be a single @emph{glob pattern}, or
a list of glob patterns.  If a list is given, pathnames that matches
any one of the pattern are returned.  If you're a unix user,
you already know how it works.
@c JP
引数@var{pattern}は単一の@emph{グロブパターン}もしくは、グ
ロブパターンのリストです。リストが渡されたときには、
最低1つのパターンにマッチするパス名がすべて返されます。
Unixのユーザならglobの動作は馴染み深いものでしょう。
@c COMMON

@example
gosh> (glob "*.scm")
("ext.scm" "test.scm")
gosh> (glob "src/*.[ch]")
("src/ext.c" "src/ext.h")
gosh> (glob '("*.scm" "src/*.c"))
("ext.scm" "src/ext.c" "test.scm")
@end example

@c EN
Unlike shell's glob, if there's no matching pathnames, @code{()} is returned.
@c JP
シェルのグロブとはちがって、マッチするパス名がないときは、@code{()}が返ります。
@c COMMON

@c EN
By default, the result is sorted using built-in @code{sort} procedure
(@pxref{Sorting and merging}).  You can pass alternative procedure
to @var{sorter} argument; it should be a procedure that takes single
list, and returns a sorted list.  It can also be @code{#f}, in which
case the result isn't sorted at all.
@c JP
デフォルトでは、結果は組み込みの@code{sort}手続きによりソートされて返されます
(@ref{Sorting and merging}参照)。@var{sorter}キーワード引数で
代わりのソート手続きを指定できます。@var{sorter}手続きはひとつのリストを受け取り、
それをソートして返します。また、@var{sorter}引数に@code{#f}を渡すと、
結果はソートされずに返されます。
@c COMMON

@c EN
In fact, globbing is a very useful tool to search hierarchical
data structure in general, not limited to the filesystems.
So the @code{glob} function is implemented separately from
the filesystem.  Using keyword arguments,
you can glob from any kind of tree data structure.
It is just that their default values are set to look at
the filesystems.
@c JP
グロブはファイルシステムに限らず階層的なデータ構造を検索するのに非常に便利なツールです。
したがって、@code{glob}関数はファイルシステムからは切り離して実装されています。
キーワード引数を使うことで、どのようなツリー状のデータ構造からでもグロブできます。
デフォルト値がファイルシステム用に設定されているにすぎません。
@c COMMON

@c EN
The @var{separator} argument should be a char-set, and used
to split the @var{pattern} into components.  Its default is
@code{#[/]}.  It is not used to the actual pathnames to match.
@c JP
引数@var{separator}は文字の集合を与えます。これを使って@var{pattern}を
コンポーネントに分割します。デフォルトは@code{#[/]}です。実際のパス名
をマッチさせるのには使われません。
@c COMMON

@c EN
The @var{folder} is a procedure that walks through the data
structure.  It is called with five arguments:
@c JP
@var{folder}はデータ構造をトラバースするための手続きです。この手続きは
引数を5つとります。
@c COMMON

@example
(folder @var{proc} @var{seed} @var{parent} @var{regexp} @var{non-leaf?})
@end example

@c EN
@var{proc} is a procedure that takes two arguments.  The @var{folder}
should call @var{proc} with every node in the @var{parent} whose
component name matches @var{regexp}, passing around the seed value
just like @code{fold}.  It should return the final value returned
by @var{proc}.  For example, if @code{cons} is given to @var{proc}
and @code{()} is given to @var{seed}, the return value of the folder
is a list of nodes that matches the @var{regexp}.
@c JP
@var{proc}は引数を2つ取る手続きです。@var{folder}は、@var{parent}内で
コンポーネントとなる名前が@var{regexp}とマッチする各ノードと、
@code{fold}と同様に順に渡されるシード値とで、@var{proc}を呼びます。
@var{folder}は@var{proc}が最後に返した値を返します。たとえば、
@code{cons}が@var{proc}として、@code{()}が@var{seed}として渡されれば、
folder手続きが返す値は@var{regexp}とマッチするノードのリストになります。
@c COMMON

@c EN
The representation of a node is up to the implementation of
@var{folder}.  It can be a
pathname, or some sort of objects, or anything.  The @code{glob}
procedure does not care what it is; the @code{glob} procedure
merely passes the node to subsequent call to @code{folder} as
@var{parent} argument, or returns a list of nodes as the result.
@c JP
ノードの表現がどうなるかは@var{folder}の実装によります。
パス名であったり、オブジェクトであったりするかもしれません。
@code{glob}手続きはノードの表現については感知しません。
@code{glob}手続きがやることはノードを次に呼ぶ
@code{folder}に@var{parent}引数として渡して、
その結果のノードリストを返すだけです。
@c COMMON

@c EN
The @var{parent} argument is basically a node, and
@var{folder} traverses its children to find the match.
The exception is the initial call of @var{folder}---
at the beginning @code{glob} knows nothing about each node.
When @code{glob} needs to match an absolute path, it
passes @code{#t}, and when @code{glob} needs to match a relative path,
it passes @code{#f}, as the initial @var{parent} value.
@c JP
@var{parent}引数は基本的にはノードで、@var{folder}はその子ノードを
対象にマッチするものを探索します。
例外は最初に@var{folder}が呼ばれる時です。その時点では@code{glob}は
ノードについて何も知らないので、
絶対パスでマッチをかける場合は@code{#t}を、
相対パスでマッチをかける場合は@code{#f}を最初の@var{parent}の値として渡します。
@c COMMON

@c EN
The @var{regexp} argument is used to filter the child nodes.
It should be matched against the component name of the child,
not including its directory names.  As a special case, it can
be a symbol @code{dir?}; if that's the case, the folder should
return @var{node} itself, but it may indicate @var{node}
@emph{as a directory}; e.g. if @var{node} is represented as a pathname,
the folder returns a pathname with trailing directory separator.
As special cases,
if @var{node} is a boolean value and @var{regexp} is @code{dir?},
the folder should return the node representing root node or
current node, respectively; e.g. if @var{node} is represented
as a pathname, the folder may return @code{"/"} and @code{"./"}
for those cases.
@c JP
@var{regexp}引数は子ノードをフィルターするのに使い、ディレクトリ名を含
まない、子のコンポーネントである名前に対して照合されるものです。特別な
場合として、シンボル@code{dir?}にすることができます。この場合は、folder
は@var{node}そのものを返し、@var{node}は@emph{ディレクトリ}と見なされ
ます。すなわち、@var{node}がパス名を表わす場合には、folderはディレクト
リ区切り子が最後に付いたパス名を返します。
特別な場合として、@var{node}がブール値でかつ
@var{regexp}が@code{dir?}である場合、folderはルートノードをあらわすノー
ドあるいはカレントノードを返すことになっています。すなわち、@var{node}
はパス名を表す場合、folderは@code{"/"}または@code{"./"}を返します。
@c COMMON

@c EN
The @var{non-leaf} argument is a boolean flag.  If it is true,
the filter should omit the leaf nodes from the result (e.g. only
include the directories).
@c JP
@var{non-leaf}引数はブール値フラッグです。真なら、フィルタは結果からリー
フノードをのぞきます(すなわち、ディレクトリだけが含まれるようになり
ます)。
@c COMMON

@c EN
Now, here's the precise spec of glob pattern matching.
@c JP
ここからはグロブパターンマッチングの細かい仕様をみていきます。
@c COMMON

@c EN
Each glob pattern is a string to match pathname-like strings.
@c JP
各グロブパターンはパス名様式文字列にマッチする文字列です。
@c COMMON

@c EN
A pathname-like string is a string consists of one or more
@emph{components}, separated by @emph{separator}s.
The default separator is @code{#[/]}; you can change it
with @var{separator} keyword argument.
A component cannot contain separators, and cannot
be a null string.  Consecutive separators are
regarded as a single separator.  A pathname-like
string optionally begins with, and/or ends with a separator character.
@c JP
パス名様式文字列は1つ以上の@emph{セパレータ}で区切られた
@emph{コンポーネント}から構成される文字列です。
デフォルトのセパレータは@code{#[/]}です。キーワード引数@var{separator}
を使うとこれを変更できます。コンポーネントにはセパレータを含められませ
ん。また空文字列にすることもできません。連続したセパレータは単一のセパ
レータとみなされます。パス名様式の文字列は状況に応じてセパレータから始
めたり、セパレータで終端したりできます(両方をやるのも可)。
@c COMMON

@c EN
A glob pattern also consists of components and separator
characters.  In a component, following characters/syntax have special
meanings.
@c JP
グロブパターンもコンポーネントとセパレータ文字から構成されます。コンポー
ネントにおいては、以下の文字、構文は特別な意味を持ちます。
@c COMMON

@table @code
@item *
@c EN
When it appears at the beginning of a component, it matches
zero or more characters except a period (@code{.}).  And it
won't match if the component of the input string begins with
a period.

Otherwise, it matches zero or more sequence of any characters.
@c JP
これがコンポーネントの先頭に表われた場合、0個以上のピリオド(@code{.})
を除く文字にマッチします。入力文字列のコンポーネントがピリオドではじま
るような文字列の場合にはマッチしません。

先頭以外の場所では、0個以上の文字の列にマッチします。
@c COMMON

@item **
@c EN
If a component is just @code{**}, it matches zero or more
number of components that match @code{*}.  For example, @code{src/**/*.h}
matches all of the following patterns.
@c JP
コンポーネントが@code{**}だけの場合、これは@code{*}にマッチする0個以上の
コンポーネントにマッチします。例えば@code{src/**/*.h}は
次のようなパターン全てにマッチします。
@c COMMON
@example
src/*.h
src/*/*.h
src/*/*/*.h
src/*/*/*/*.h
...
@end example

@item ?
@c EN
When it appears at the beginning of a component, it matches
a character except a period (@code{.}).  Otherwise, it matches
any single character.
@c JP
コンポーネントの先頭にあらわれた場合、ピリオド(@code{.})以外の一文字に
マッチします。先頭以外の場所では任意の一文字にマッチします。
@c COMMON

@item [@i{chars}]
@c EN
Specifies a character set.  Matches any one of the set.
The syntax of @i{chars} is the same as Gauche's character set
syntax (@pxref{Character sets}).  For the compatibility of the
traditional glob, the @code{!} character can be used to complement
the character set, e.g. @code{[!abc]} is the same as @code{[^abc]}.
@c JP
文字の集合を指定します。その集合に含まれる文字のどれかにマッチします。
@i{chars}の構文はGaucheの文字集合を表す構文と同じです
(@ref{Character sets}参照)。伝統的なグロブとの互換性のために、@code{!}
文字をつかって、補集合で文字集合を表わすこともできるようになっています。
すなわち、@code{[!abc]}は@code{[^abc]}と同じです。
@c COMMON

@item \
@c EN
Include the next character literally in the pattern.  This can be used
to include above special characters in the pattern.
@c JP
次の文字をそのままパターンに含めます。上の特殊文字をそのままパターンに入れたい
時に使えます。
@c COMMON
@end table
@end defun

@defun glob-fold pattern proc seed :key separator folder sorter
@c EN
This is a low-level construct of the glob function.
Actually, @var{glob} is simply written like this:
@c JP
これはグロブ関数の低レベル版です。実際@var{glob}は以下のように書いたの
と同じです。
@c COMMON
@example
(define (glob patterns . opts)
  (apply glob-fold patterns cons '() opts))
@end example

@c EN
The meaning of @var{pattern}, @var{separator}, @var{folder} and
@var{sorter}
is the same as explained above.
@c JP
@var{pattern}、@var{separator}、@var{folder}および@var{sorter}の意味を前述のものと同
じです。
@c COMMON

@c EN
For each pathname that matches @var{pattern}, @code{glob-fold}
calls @var{proc} with the pathname and a seed value.  The initial
seed value is @var{seed}, and the value @var{proc} returns becomes
the next seed value.  The result of the last call to @var{proc}
becomes the result of @code{glob-fold}.  If there's no matching
pathnames, @var{proc} is never called and @var{seed} is returned.
@c JP
@var{pattern}にパス名ごとに@code{glob-fold}は@var{proc}をパス名とシー
ド値で呼びます。最初のシード値は@var{seed}で、@var{proc}が返す値は次の
シード値になります。最後の@var{proc}の呼び出し結果は@code{glob-fold}の
結果となります。マッチするパス名が存在しないときは、@var{proc}は呼ばれ
ずに、@var{seed}が返ります。
@c COMMON
@end defun

@defun make-glob-fs-fold :key root-path current-path
@c EN
This is a utility function to generate a procedure suitable to
pass the @var{folder} keyword argument of @code{glob-fold} and @code{glob}.
Without arguments, this returns the same procedure which is used
in @code{glob-fold} and @code{glob} by default.
@c JP
これは@code{glob-fold}や@code{glob}の@var{folder}キーワード引数に
渡せる形の手続きを作るユーティリティ手続きです。
引数を渡さなければ、@code{glob-fold}や@code{glob}がデフォルトで使うのと
同じ手続きが返ります。
@c COMMON

@c EN
The keyword arguments @var{root-path} and @var{current-path} specify
the paths where @code{glob-fold} starts to search.
@c JP
キーワード引数@var{root-path}および@var{current-path}はそれぞれ、
@code{glob-fold}が探索を開始するディレクトリを指定します。
@c COMMON

@example
gosh> (glob "/tmp/*.scm")
("/tmp/x.scm" "/tmp/y.scm")
gosh> (glob "/*.scm"
            :folder (make-glob-fs-fold :root-path "/tmp"))
("/tmp/x.scm" "/tmp/y.scm")
gosh> (glob "*.scm"
            :folder (make-glob-fs-fold :current-path "/tmp"))
("/tmp/x.scm" "/tmp/y.scm")
@end example
@end defun

@c EN
@xref{File stats}, to check if a path is actually a directory.
@c JP
パスがディレクトリかどうかチェックする方法は、@ref{File stats}を参照してください。
@c COMMON

@node Directory manipulation, Pathnames, Directories, Filesystems
@subsubsection Directory manipulation
@c NODE ディレクトリ操作

@defun sys-remove filename
[POSIX]
@c EN
If @var{filename} is a file it is removed.
On some systems this may also work on an empty directory,
but portable scripts shouldn't depend on it.
@c JP
@var{filename}がファイルであればそれを消去します。
システムによっては@var{filename}が空のディレクトリであっても動作しますが、
移植性を気にする場合はその動作に依存しない方が良いでしょう。
@c COMMON
@end defun

@defun sys-rename old new
[POSIX]
@c EN
Renames a file @var{old} to @var{new}.  The new name
can be in different directory from the old name, but both paths
must be on the same device.
@c JP
ファイル@var{old}を@var{new}にリネームします。新しい名前は
古い名前と異なるディレクトリにあってもかまいませんが、両者は同じデバイス上に
なければなりません。
@c COMMON
@end defun

@defun sys-tmpnam
[POSIX]
@c EN
Creates a file name which is supposedly unique, and returns it.
This is in POSIX, but its use is discouraged because of potential
security risk.  Use @code{sys-mkstemp} below if possible.
@c JP
ユニークなファイル名を作成して返します。この関数はPOSIXに含まれていますが、
セキュリティ上の問題が指摘されており、使わない方が良いとされています。
可能なら下にあげる@code{sys-mkstemp}を使って下さい。
@c COMMON
@end defun

@defun sys-mkstemp template
@c EN
Creates and opens a file that has unique name, and returns two values;
opened port and the created filename.  The file is created exclusively,
avoiding race conditions.   @var{template} is used as the prefix
of the file.  Unlike Unix's mkstemp, you don't need padding characters.
The file is opened for writing, and its permission is set to 600.
@c JP
ユニークな名前を持つファイルを作成してオープンし、オープンされたポートとファイル名の
二つの値を返します。ファイルは排他的に作成されるため、レースコンディションは起こりません。
@var{template}はファイル名のプレフィックスに使われます。Unixのmkstempと違って、
パディングキャラクタをつける必要はありません。ファイルは書き込み用としてオープンされ、
パーミッションは600にセットされます。
@c COMMON
@end defun

@defun sys-mkdtemp template
@c EN
Creates a directory that has unique name, and returns the name.
@var{template} is used as the prefix of the directory.  Unlike Unix's
mkdtemp, you don't need padding characters.  The directory's
permission is set to 700.
@c JP
ユニークな名前を持つディレクトリを作成し、その名前を返します。
@var{template}はディレクトリ名のプレフィックスに使われます。
Unixのmkdtempと違って、パディングキャラクタをつける必要はありません。
ディレクトリのパーミッションは700にセットされます。
@c COMMON
@end defun

@defun sys-link existing new
[POSIX]
@c EN
Creates a hard link named @var{new} to the existing file @var{existing}.
@c JP
既存のファイル@var{existing}に対し、@var{new}という名のハードリンクを作成します。
@c COMMON
@end defun

@defun sys-unlink pathname
[POSIX]
@c EN
Removes @var{pathname}.  It can't be a directory.
Returns @code{#t} if it is successfully removed, or
@code{#f} if @var{pathname} doesn't exist.
An error is signaled otherwise.
@c JP
@var{pathname}で示されるファイルを消去します。
@var{pathname}はディレクトリであってはなりません。
もし消去に成功したら@code{#t}が、@var{pathname}が存在しなければ@code{#f}が返されます。
他の場合はエラーが通知されます。
@c COMMON

@c EN
There are similar procedures, @code{delete-file}/@code{remove-file}
in @code{file.util} module, while they raises an error when the
named pathname doesn't exist (@pxref{File operations}).
@c JP
@code{file.util}モジュールに似た手続き@code{delete-file}/@code{remove-file}が
ありますが、そちらはファイルが存在しない場合にエラーを投げます
(@ref{File operations}参照)。
@c COMMON

@c EN
R7RS defines @code{delete-file}, which you may want to use in portable
programs.
@c JP
R7RSは@code{delete-file}を定義しています。ポータブルなプログラムでは
そちらを使うのが良いでしょう。
@c COMMON
@end defun

@defun sys-unlink-eventually obj :optional unlink-empty-dirs
@c EN
@var{Obj} must be either a file port or @code{#<dlobj>}.
This procedure try to unlink the referenced file eventually.

On Unix-like platforms, we can just unlink it and still keep using @var{obj}.
On Windows, however, it is not allowed to remove files that are still open,
so this procedure registers @var{obj} internally, and at the end of
the process it closes each @var{obj} (if it is still open) and removes
the referenced file.   Note that if the process dies unexpectedly,
this cleanup may not be done.

The optional argument @var{unlink-empty-dirs} must be a nonnegative
exact integer.  If given an not zero, this procedure tries to
remove that many layers of directories as far as the removal
of the file or the subdirectory results empty directory.  If the
removal does not result an empty directory, it is left intact.

This procedure is intended to clean up a temporary stuff.
Suppose the process creates a temporary directory
@code{/tmp/foo-temp-53abbc/} and a dynamic loadable object
@code{foo.dll} in it, then dynamic links it.  It can call
@code{(sys-unlink-eventually <dlobj> 1)}.  Upon process
exit, @code{foo.dll} is removed, which results the containing
directory @code{foo-temp-53abbc} empty, so it is removed as well
since @code{1} is given to @var{unlink-empty-dirs}.
@c JP
@var{obj}はファイルポートか@code{#<dlobj>}でなければなりません。
この手続きは、背後にあるファイルがいずれ消去されるように手配します。

Unix系プラットフォームでは、直ちにファイルは消去されます。それでも
@var{obj}を使い続けることができます。
しかしWindowsはオープンされているファイルを消去することを許していません。
そこで、@var{obj}を内部的に登録しておき、
プロセス終了時に参照されているファイルを消去します。
(@var{obj}がその時点でまだオープンされていればクローズされます)。
但し、プロセスが突然死した場合などにクリーンアップが走らない可能性はあります。

省略可能引数@var{unlink-empty-dirs}は非負の正確な整数でなければならず、
与えられたらその数のディレクトリ階層を(それが要素の削除の結果として空になるなら)
削除します。他のファイルやディレクトリが残っている場合は
そのディレクトリは削除されません。

この手続きは一時的な要素のクリーンアップを意図しています。
例えば、プロセスが一時ディレクトリ@code{/tmp/foo-temp-53abbc/}を作り、
その中に動的ロード可能ファイル@code{foo.dll}を作って動的リンクしたとしましょう。
@code{(sys-unlink-eventually <dlobj> 1)}を呼んでおくと、
プロセス終了時に@code{foo.dll}は削除され、するとディレクトリ
@code{foo-temp-53abbc/}が空になるのでそれも削除されます。
@c COMMON
@end defun


@defun sys-symlink existing new
@c EN
Creates a symbolic link named @var{new} to the pathname @var{existing}.
On systems that doesn't support symbolic links,
this function is unbound.
@c JP
@var{existing}を指す@var{new}という名のシンボリックを作成します。
シンボリックリンクをサポートしないシステムでは、この手続きは定義されません。
@c COMMON
@end defun

@defun sys-readlink path
@c EN
If a file specified by @var{path} is a symbolic link, its content is
returned.  If @var{path} doesn't exist or is not a symbolic link, an
error is signaled.
On systems that don't support symbolic links,
this function is unbound.
@c JP
@var{path}で示されるファイルがシンボリックリンクならば、それが指すパスを返します。
もし@var{path}が存在しなかったり、シンボリックリンクでなければ、エラーが通知されます。
シンボリックリンクをサポートしないシステムでは、この手続きは定義されません。
@c COMMON
@end defun

@defun sys-mkdir pathname mode
[POSIX]
@c EN
Makes a directory @var{pathname} with mode @var{mode}.
(Note that @var{mode} is masked by the current umask;
see @code{sys-umask} below).
The parent directory of @var{pathname} must exist and be writable
by the process.  To create intermediate directories at once, use
@code{make-directory*} in @code{file.util} (@ref{Directory utilities}).
@c JP
ディレクトリ@var{pathname}をモード@var{mode}で作成します。
(@var{mode}はさらにumaskでマスクされることに注意して下さい；下の@code{sys-umask}
参照)。
@var{pathname}の親ディレクトリは存在して、プロセスが書き込めるようになっていなければ
なりません。中間のディレクトリも一度に作成するには、
@code{file.util}の@code{make-directory*}が使えます
(@ref{Directory utilities})。
@c COMMON
@end defun

@defun sys-rmdir pathname
[POSIX]
@c EN
Removes a directory @var{pathname}.  The directory must be empty.
To remove a directory with its contents, use @code{remove-directory*}
in @code{file.util} (@ref{Directory utilities}).
@c JP
ディレクトリ@var{pathname}を消去します。ディレクトリは空でなければなりません。
ディレクトリの内容も一緒に消去するには、@code{file.util}の@code{remove-directory*}
が使えます(@ref{Directory utilities})。
@c COMMON
@end defun

@defun sys-umask :optional mode
[POSIX]
@c EN
Sets umask setting to @var{mode}.  Returns previous umask setting.
If @var{mode} is omitted or @code{#f}, just returns the current umask without
changing it.
See @code{man umask} for more details.
@c JP
umaskを@var{mode}にセットします。変更される前のumaskを返します。
@var{mode}が省略されるか@code{#f}が渡された場合、
現在のumaskを変更せずにその値を返します。
umaskについては@code{man umask}を参照してください。
@c COMMON
@end defun

@node Pathnames, File stats, Directory manipulation, Filesystems
@subsubsection Pathnames
@c NODE パス名

@c EN
See also @ref{Pathname utilities}, for high-level APIs.
@c JP
高レベルのAPIに関しては@ref{Pathname utilities}も参照して下さい。
@c COMMON

@defun sys-normalize-pathname pathname :key absolute expand canonicalize
@c EN
Converts @var{pathname} according to the way specified by keyword arguments.
More than one keyword argument can be specified.
@c JP
与えられたキーワード引数によって@var{pathname}を以下のように変換します。
キーワード引数は同時に複数指定できます。
@c COMMON
@table @code
@item absolute
@c EN
  If this keyword argument is given and true, and @var{pathname} is not
  an absolute pathname, it is converted to an absolute pathname by
  appending the current working directory in front of @var{pathname}.
@c JP
  このキーワード引数に真の値が与えられて、@var{pathname}が絶対パスでない場合、
  @var{pathname}の前にプロセスのワーキングディレクトリを足して絶対パスにします。
@c COMMON
@item expand
@c EN
  If this keyword argument is given and true, and @var{pathname} begins
  with `@code{~}', it is expanded as follows:
@c JP
  このキーワード引数に真の値が与えられて、@var{pathname}が`@code{~}' で始まっていた
  場合、以下のように展開されます。
@c COMMON
@itemize @bullet
@item
@c EN
    If @var{pathname} is consisted entirely by ``@code{~}'', or begins
    with ``@code{~/}'', then the character ``@code{~}'' is replaced
    for the pathname of the current user's home directory.
@c JP
    @var{pathname}が``@code{~}''のみであるか、または``@code{~/}''で始まっている
    場合、文字``@code{~}''が現在のプロセスのユーザのホームディレクトリに置き換えられます。
@c COMMON
@item
@c EN
    Otherwise, characters following `@code{~}' until either `@code{/}' or
    the end of @var{pathname} are taken as a user name, and the user's
    home directory is replaced in place of it.  If there's no such
    user, an error is signaled.
@c JP
    上記以外の場合、`@code{~}'以降、`@code{/}'か@var{pathname}の終端までの文字列
    がユーザ名とみなされ、そのユーザのホームディレクトリに置換されます。もし該当するユーザが
    いなければエラーとなります。
@c COMMON
@end itemize
@item canonicalize
@c EN
  Tries to remove pathname components ``@code{.}'' and ``@code{..}''.
  The pathname interpretation is done purely in textural level, i.e.
  it doesn't access filesystem to see the conversion reflects the
  real files.  It may be a problem if there's a symbolic links to
  other directory in the path.
@c JP
  パス名から ``@code{.}'' や ``@code{..}'' を除き、単純化します。
  この操作は実際のファイルシステムを参照せずに行われます。元のパス名がディレクトリへの
  シンボリックリンクを含んでいた場合、単純化されたパス名は正しくないかもしれません。
@c COMMON
@end table
@end defun

@defun sys-basename pathname
@defunx sys-dirname pathname
@c EN
@code{sys-basename} returns a basename, that is the last component of
@var{pathname}.  @code{sys-dirname} returns the components of @var{pathname}
but the last one.   If @var{pathname} has a trailing `@code{/}',
it is simply ignored.
@c JP
@code{sys-basename}は与えられたパスのベース名、すなわち最後のコンポーネントを返します。
@code{sys-dirname}は与えられたパスのディレクトリ名、すなわち最後のコンポーネント以外の
コンポーネントを返します。@var{pathname}の末尾が`@code{/}'である場合、その文字は
無視されます。
@c COMMON
@example
(sys-basename "foo/bar/bar.z") @result{} "bar.z"
(sys-basename "coo.scm") @result{} "coo.scm"
(sys-basename "x/y/") @result{} "y"
(sys-dirname "foo/bar/bar.z") @result{} "foo/bar"
(sys-dirname "coo.scm") @result{} "."
(sys-dirname "x/y/") @result{} "x"
@end example
@c EN
These functions doesn't check if @var{pathname} really exists.
@c JP
この手続きは@var{pathname}が存在するかどうかはチェックしません。
@c COMMON

@c EN
Some boundary cases:
@c JP
特殊なケース：
@c COMMON
@example
(sys-basename "") @result{} ""
(sys-dirname "") @result{} "."

(sys-basename "/") @result{} ""
(sys-dirname "/") @result{} "/"
@end example
@c EN
Note: The above behavior is the same as Perl's @code{basename} and
@code{dirname}.   On some systems, the command @code{basename}
may return @code{"/"} for the argument @code{"/"}, and
@code{"."} for the argument @code{"."}.
@c JP
註：このふるまいはPerlの@code{basename}および@code{dirname}と同様です。
システムによっては、コマンドの@code{basename}は@code{"/"}に対して@code{"/"}を、
@code{"."}に対して@code{"."}を返すものがあります。
@c COMMON
@end defun

@defun sys-realpath pathname
@c EN
@code{sys-realpath} returns an absolute pathname of @var{pathname}
that does not include ``@code{.}'', ``@code{..}'' or symbolic links.
If @var{pathname} does not exist, it includes a dangling symbolic
link, or the caller doesn't have enough permission to access to
the path, an error is signaled.
@c JP
@code{sys-realpath}は``@code{.}'', ``@code{..}''およびシンボリックリン
クを含まない@var{pathname}の絶対パスを返します。@var{pathname}自体が存在しなかったり、
存在しないパスを指すシンボリックリンクが含まれていたり、関連するパスへのアクセス権限が
不足している場合はエラーが通知されます。
@c COMMON

@c EN
Note: the POSIX @code{realpath(3)} function is known to be unsafe, so
Gauche avoids using it and implements @code{sys-realpath} in its own.
@c JP
注：POSIXの@code{realpath(3)}は安全でない場合があるので、
Gaucheは内部でCランタイムの@code{realpath}を呼ばずに、
独自に@code{sys-realpath}の機能を実装しています。
@c COMMON
@end defun

@defun sys-tmpdir
@c EN
Returns the default directory name suitable to put temporary files.

On Unix-like systems, the environment variable @code{TMPDIR} and @code{TMP}
are first checked, then falls back to @code{/tmp}.

On Windows-native systems, it uses @code{GetTempPath} Windows API.
It checks environment variables @code{TMP}, @code{TEMP}, and
@code{USERPROFILE} in this order, and falls back to Windows system
directory.

On both platforms, the returned pathname may not exist, or
may not be writable by the calling process.

In general, user programs and libraries are recommended to use
@code{temporary-directory} (@pxref{Directory utilities}) instead;
@code{sys-tmpdir} should be used only
if you now the raw value the platform provides.
@c JP
一時ファイルを置くためのデフォルトのディレクトリ名を返します。

Unix系システムでは、環境変数@code{TMPDIR}と@code{TMP}がこの順でチェックされ、
フォールバックとして@code{/tmp}が返されます。

Windowsネイティブの環境では、@code{GetTempPath} Windows APIを呼びます。
これは環境変数@code{TMP}、@code{TEMP}、@code{USERPROFILE}を順に調べ、
いずれも定義されていなければWindowsシステムディレクトリを返します。

いずれのプラットフォームでも、返されたパス名は存在しないかもしれず、
また書き込み可能ではないかもしれないことに注意してください。

一般的に、ユーザプログラムやライブラリは@code{temporary-directory}
(@ref{Directory utilities}参照) の方を利用するのが良いでしょう。
@code{sys-tmpdir}はプラットフォームが推奨する生の値を知りたい場合に
限り使ってください。
@c COMMON
@end defun

@node File stats, Other file operations, Pathnames, Filesystems
@subsubsection File stats
@c NODE ファイルの状態

@c EN
See also @ref{File attribute utilities}, for high-level APIs.
@c JP
高レベルのAPIに関しては@ref{File attribute utilities}も参照して下さい。
@c COMMON

@defun file-exists? path
[R7RS file]
@c EN
Returns true if @var{path} exists.
@c JP
@var{path}が存在していれば@code{#t}を返します。
@c COMMON
@end defun

@defun file-is-regular? path
@defunx file-is-directory? path
@c EN
Returns true if @var{path} is a regular file, or is a directory,
respectively.   They return false if @var{path} doesn't
exist at all.
@c JP
それぞれ、@var{path}が存在するか、存在してそれがレギュラーファイルであるか、
存在してそれがディレクトリであれば@code{#t}を返します。
@c COMMON
@end defun

@deftp {Builtin Class} <sys-stat>
@clindex sys-stat
@c EN
An object that represents @code{struct stat}, attributes of an
entry in the filesystem.   It has the following read-only slots.
@c JP
ファイルシステム内のエントリの属性を表す、@code{struct stat}のラッパー
オブジェクトです。以下に示す読みだし専用のスロットを持ちます。
@c COMMON

@defivar <sys-stat> type
@c EN
A symbol represents the type of the file.
@c JP
ファイルのタイプを示すシンボルです。
@c COMMON
@c EN
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{regular} @tab a regular file
@item @code{directory} @tab a directory
@item @code{character} @tab a character device
@item @code{block} @tab a block device
@item @code{fifo} @tab a fifo
@item @code{symlink} @tab a symbolic link
@item @code{socket} @tab a socket
@end multitable
@c JP
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{regular} @tab 通常のファイル
@item @code{directory} @tab ディレクトリ
@item @code{character} @tab キャラクタデバイス
@item @code{block} @tab ブロックデバイス
@item @code{fifo} @tab FIFO
@item @code{symlink} @tab シンボリックリンク
@item @code{socket} @tab ソケット
@end multitable
@c COMMON
@c EN
If the file type is none of the above, @code{#f} is returned.
@c JP
以上のどれにも当てはまらない場合は@code{#f}が返されます。
@c COMMON

@c EN
Note: Some operating systems don't have the @code{socket} file type
and returns @code{fifo} for socket files.   Portable programs should
check both possibilities to see if the given file is a socket.
@c JP
注：いくつかのオペレーティングシステムでは@code{socket}ファイルタイプを
@code{fifo}と区別せず、どちらに対しても@code{fifo}を返します。
ポータブルなプログラムを書くときは注意して下さい。
@c COMMON
@end defivar

@defivar <sys-stat> perm
@c EN
An exact integer for permission bits of @code{struct stat}.
It is the same as lower 9-bits of "mode" slot; provided for the convenience.
@c JP
パーミッションビットマスク。"mode"スロットの下位9ビットと同じですが、
便利なので独立したスロットとして提供されます。
@c COMMON
@end defivar

@defivar <sys-stat> mode
@defivarx <sys-stat> ino
@defivarx <sys-stat> dev
@defivarx <sys-stat> rdev
@defivarx <sys-stat> nlink
@defivarx <sys-stat> uid
@defivarx <sys-stat> gid
@defivarx <sys-stat> size
@c EN
An exact integer for those information of @code{struct stat}.
@c JP
@code{struct stat}の該当するフィールドの値。正確な整数です。
@c COMMON
@end defivar

@defivar <sys-stat> atime
@defivarx <sys-stat> mtime
@defivarx <sys-stat> ctime
@c EN
A number of seconds since Unix Epoch for those information of @code{struct stat}.
@c JP
@code{struct stat}の該当するフィールドの値を、Unix Epochからの秒数で。
@c COMMON
@end defivar

@defivar <sys-stat> atim
@defivarx <sys-stat> mtim
@defivarx <sys-stat> ctim
@c EN
Timestamps represented in @code{<time>} object (@pxref{Time}).
If the system supports it, this allows up to nanosecond precision.
@c JP
@code{<time>}オブジェクトで表されたタイムスタンプ (@ref{Time}参照)。
システムがサポートしていれば、ナノ秒単位のタイムスタンプを得ることができます。
@c COMMON
@end defivar

@end deftp

@defun sys-stat path
@defunx sys-fstat port-or-fd
[POSIX]
@c EN
Returns a @code{<sys-stat>} object of @var{path}, or
the underlying file of @var{port-or-fd}, which
may be a port or a positive exact integer file descriptor, respectively.

If @var{path} is a symbolic link, a stat of the file the link points
to is returned from @code{sys-stat}.

If @var{port-or-fd} is not associated to a file, @code{sys-fstat} returns
@code{#f}.
@c JP
与えられたパス名@var{path}、またはポートかファイルディスクリプタ
@var{port-or-fd}で示されるファイルの情報を@code{<sys-stat>}オブジェクトで
返します。

@code{sys-stat}は、@var{path}がシンボリックリンクであった場合は
リンクの指す先のファイルに関する情報を返します。

@code{sys-fstat}は、@var{port-or-fd}がファイルに関係ないポートであった
場合は@code{#f}を返します。
@c COMMON
@end defun

@defun sys-lstat path
@c EN
Like @code{sys-stat}, but it returns a stat of a symbolic link
if @var{path} is a symbolic link.
@c JP
@code{sys-stat}と同じですが、@var{path}がシンボリックリンクであった
場合はリンクそのものの情報を返します。
@c COMMON
@end defun

@example
gosh> (describe (sys-stat "gauche.h"))
#<<sys-stat> 0x815af70> is an instance of class <sys-stat>
slots:
  type      : regular
  perm      : 436
  mode      : 33204
  ino       : 28704826
  dev       : 2049
  rdev      : 0
  nlink     : 1
  uid       : 500
  gid       : 500
  size      : 68857
  atime     : 1747126496
  mtime     : 1745056721
  ctime     : 1745056721
  atim      : #<time-utc 1747126496.478966778>
  mtim      : #<time-utc 1745056721.769596817>
  ctim      : #<time-utc 1745056721.769596817>
@end example

@defun sys-stat->mode stat
@defunx sys-stat->ino stat
@defunx sys-stat->dev stat
@defunx sys-stat->rdev stat
@defunx sys-stat->nlink stat
@defunx sys-stat->size stat
@defunx sys-stat->uid stat
@defunx sys-stat->gid stat
@defunx sys-stat->atime stat
@defunx sys-stat->mtime stat
@defunx sys-stat->ctime stat
@defunx sys-stat->file-type stat
@c DEPRECATED
@c EN
Use @code{slot-ref} to access information of @code{<sys-stat>} object.
@c JP
@code{<sys-stat>}オブジェクトの情報にアクセスするには@code{slot-ref}を
使って下さい。
@c COMMON
@end defun

@defun sys-access pathname amode
[POSIX]
@c EN
Returns a boolean value of indicating whether access of @var{pathname}
is allowed in @var{amode}.   This procedure signals an error
if used in a suid/sgid program (see the note below).
@var{amode} can be a combinations (logical or) of
following predefined flags.
@c JP
@var{pathname}へのアクセスが
@var{mode}に示されるモードで許可されているかどうかを示す真偽値を返します。
この手続きは、suid/sgidプログラムで使われるとエラーとなります(下記註参照)。
@var{mode}は以下に示す定数のコンビネーション(logical or)です。
@c COMMON
@table @code
@item R_OK
@vindex R_OK
@c EN
Checks whether @var{pathname} is readable by the current user.
@c JP
@var{pathname}をカレントユーザが読み出し可能かどうか
@c COMMON
@item W_OK
@vindex W_OK
@c EN
Checks whether @var{pathname} is writable by the current user.
@c JP
@var{pathname}へカレントユーザが書き込み可能かどうか
@c COMMON
@item X_OK
@vindex X_OK
@c EN
Checks whether @var{pathname} is executable (or searchable in case
@var{pathname} is a directory) by the current user.
@c JP
@var{pathname}をカレントユーザが実行可能かどうか(@var{pathname}が
ディレクトリの場合はサーチ可能かどうか)
@c COMMON
@item F_OK
@vindex F_OK
@c EN
Checks whether @var{pathname} exists or not, regardless of
the access permissions of @var{pathname}.  (But you need to have
access permissions of the directories containing @var{pathname}).
@c JP
@var{pathname}のパーミッションフラグにかかわらず、@var{pathname}が
存在するかどうか (但し@var{pathname}があるディレクトリの読みだし許可は必要)。
@c COMMON
@end table

@c EN
@emph{Note:} Access(2) is known to be a security hole if used
in suid/sgid program to check the real user's privilege of
accessing the file.
@c JP
@emph{註:} access(2)は、suid/sgidプログラム中で
実ユーザの権限を確かめるために使われた場合、セキュリティホールと
なります。
@c COMMON
@end defun

@defun sys-chmod path mode
@defunx sys-fchmod port-or-fd mode
@c EN
Change the mode of the file named @var{path} or an opened
file specified by @var{port-or-fd} to @var{mode}.
@var{mode} must be a small positive integer whose lower 9 bits
specifies POSIX style permission.
@c JP
名前@var{path}を持つ、もしくは@var{port-or-fd}で指定される
ファイルのパーミッションビットを@var{mode}に変更します。
@var{mode}は小さな正の正確な整数で、POSIXスタイルのパーミッションビットマスク
でなければなりません。
@c COMMON
@end defun

@defun sys-chown path owner-id group-id
@c EN
Change the owner and/or group of the file named @var{path}
to @var{owner-id} and @var{group-id} respectively.
@var{owner-id} and @var{group-id} must be an exact integer.
If either of them is -1, the corresponding ownership is not changed.
@c JP
ファイル@var{path}のオーナーとグループを@var{owner-id}と@var{group-id}
で示されるものに変更します。@var{owner-id}と@var{group-id}は正確な整数で
なければなりません。どちらかに-1が渡された場合は、対応する情報は変更されません。
@c COMMON
@end defun

@defun sys-utime path :optional atime mtime
@c EN
Change the file's access time and modification time to @var{atime}
and @var{mtime}, respectively.   The arguments can be either @code{#f}
(indicating the current time), @code{#t} (do not change),
a real numebr (number of seconds from Epoch),
or @code{<time>} object (@xref{Time}).

See also @code{touch-file} (@pxref{File operations}).
@c JP
ファイルのアクセスタイムと変更タイムを@var{atime}と@var{mtime}が示す
値にセットします。@var{atime}/@var{mtime}引数に許されるのは、
@code{#f} (現在の時刻)、@code{#t} (変更なし)、
実数 (Epochからの秒数)、あるいは@code{<time>}インスタンスです
(@ref{Time}参照)。

@ref{File operations}の@code{touch-file}も参照して下さい。
@c COMMON
@end defun

@node Other file operations,  , File stats, Filesystems
@subsubsection Other file operations
@c NODE 他のファイル操作

@defun sys-chdir dir
[POSIX]
@c EN
An interface to @code{chdir(2)}.
See also @code{current-directory} (@pxref{Directory utilities}).
@c JP
@code{chdir(2)}へのインタフェースです。
@code{current-directory}(@ref{Directory utilities})も参照して下さい。
@c COMMON
@end defun

@defun sys-pipe :key (buffering :line)
@c EN
[POSIX] Creates a pipe, and returns two ports.
The first returned port is an input port and the second is an output port.
The data put to the output port can be read from the input port.
@c JP
[POSIX] パイプを作り、ポートを2つ返します。
最初に返されるポートは入力ポートで、2番目に返されるポートは出力ポートです。
出力ポートへ書き出したデータは、入力ポートから読み込めます。
@c COMMON

@c EN
@var{Buffering} can be @code{:full}, @code{:line} or @code{:none},
and specifies the buffering mode of the ports opened on the pipe.
@xref{File ports}, for details of the buffering mode.
The default mode is sufficient for typical cases.
@c JP
@var{buffering}は@code{:full}、@code{:line}、@code{:none}のいずれかで、
パイプ上に開かれたポートのバッファリングモードを指定します。
バッファリングモードの詳細については、@ref{File ports}を参照して下さい。
通常のケースでは、デフォルトのモードで間に合うでしょう。
@c COMMON

@example
(receive (in out) (sys-pipe)
  (display "abc\n" out)
  (flush out)
  (read-line in)) @result{} "abc"
@end example

@c EN
Note: the returned value is changed from version 0.3.15, in which
@code{sys-pipe} returned a list of two ports.
@c JP
注意: 戻り値はバージョン0.3.15から変更されています。それまでは、
@code{sys-pipe}は2つのポートのリストを返します。
@c COMMON
@end defun

@defun sys-mkfifo path mode
@c EN
[POSIX] creates a fifo (named pipe) with a name @var{path} and mode
@var{mode}.  @var{Mode} must be a positive exact integer to represent
the file mode.
@c JP
[POSIX] 名前が@var{path}でモードが@var{mode}のFIFO(名前付きパイプ)を
作ります。@var{mode}はファイルのモードを表す正の正確整数でなければ
なりません。
@c COMMON
@end defun

@defun sys-isatty port-or-fd
@c EN
[POSIX] @var{port-or-fd} may be a port or an integer file descriptor.
Returns @code{#t} if the port is connected to the console, @code{#f}
otherwise.
@c JP
[POSIX] @var{port-or-fd}はポートか整数のファイルディスクリプタです。
ポートがコンソールに接続されていれば@code{#t}を、そうでなければ@code{#f}を
返します。
@c COMMON
@end defun

@defun sys-ttyname port-or-fd
@c EN
[POSIX] @var{port-or-fd} may be a port or an integer file descriptor.
Returns the name of the terminal connected to the port,
or @code{#f} if the port is not connected to a terminal.
@c JP
[POSIX] @var{port-or-fd}はポートか整数のファイルディスクリプタです。
ポートに接続された端末の名前か、ポートが端末に接続されていなければ
@code{#f}を返します。
@c COMMON
@end defun

@defun sys-truncate path length
@defunx sys-ftruncate port-or-fd length
[POSIX]
@c EN
Truncates a regular file named by @var{path} or referenced by @var{port-or-fd}
to a size of @var{length} bytes.
If the file is larger than @var{length} bytes, the extra data is discarded.
If the file is smaller than that, zero is padded.
@c JP
@var{path}あるいは@var{port-or-fd}によって指定される通常ファイルの長さを
@var{length}にします。
ファイルが@var{length}より長かった場合、余分なデータは捨てられます。
ファイルが@var{length}より短かった場合、残りの部分にはゼロが詰められます。
@c COMMON
@end defun

@node Unix groups and users, Locale, Filesystems, System interface
@subsection Unix groups and users
@c NODE Unixのグループとユーザ

@subsubheading Unix groups

@deftp {Builtin Class} <sys-group>
@clindex sys-group
@c EN
Unix group information.  Has following slots.
@c JP
Unixのグループの情報です。以下のスロットを持ちます。
@c COMMON

@defivar <sys-group> name
@c EN
Group name.
@c JP
グループ名。
@c COMMON
@end defivar

@defivar <sys-group> gid
@c EN
Group id.
@c JP
グループID
@c COMMON
@end defivar

@defivar <sys-group> passwd
@c EN
Group password.
@c JP
グループパスワード。
@c COMMON
@end defivar

@defivar <sys-group> mem
@c EN
List of user names who are in this group.
@c JP
このグループに属するユーザ名のリスト。
@c COMMON
@end defivar

@end deftp

@defun sys-getgrgid gid
@defunx sys-getgrnam name
[POSIX]
@c EN
Returns @code{<sys-group>} object from an integer group id @var{gid}
or a group name @var{name}, respectively.
If the specified group doesn't exist, @code{#f} is returned.
@c JP
グループID@var{gid}もしくはグループ名@var{name}で示されるグループの情報を
@code{<sys-group>}で返します。該当するグループが存在しない場合は
@code{#f}が返されます。
@c COMMON
@end defun

@defun sys-gid->group-name gid
@defunx sys-group-name->gid name
@c EN
Convenience function to convert between group id and group name.
@c JP
グループIDとグループ名を相互変換する便利な手続きです。
@c COMMON
@end defun

@subsubheading Unix users

@deftp {Builtin Class} <sys-passwd>
@clindex sys-passwd
@c EN
Unix user information.  Has following slots.
@c JP
Unixのユーザの情報です。以下のスロットを持ちます。
@c COMMON

@defivar <sys-passwd> name
@c EN
User name.
@c JP
ユーザ名。
@c COMMON
@end defivar

@defivar <sys-passwd> uid
@c EN
User ID.
@c JP
ユーザID
@c COMMON
@end defivar

@defivar <sys-passwd> gid
@c EN
User's primary group id.
@c JP
ユーザのプライマリグループID。
@c COMMON
@end defivar

@defivar <sys-passwd> passwd
@c EN
User's (encrypted) password.  If the system uses the shadow password file,
you just get obscure string like "x".
@c JP
ユーザの(暗号化された)パスワード。システムがシャドウパスワードファイルを
使っている場合は、 "x" のような無意味な文字列が入っています。
@c COMMON
@end defivar

@defivar <sys-passwd> gecos
@c EN
Gecos field.
@c JP
Gecosフィールド。
@c COMMON
@end defivar

@defivar <sys-passwd> dir
@c EN
User's home directory.
@c JP
ユーザのホームディレクトリ。
@c COMMON
@end defivar

@defivar <sys-passwd> shell
@c EN
User's login shell.
@c JP
ユーザのログインシェル。
@c COMMON
@end defivar

@defivar <sys-passwd> class
@c EN
User's class (only available on some systems).
@c JP
ユーザのクラス。(特定のシステムでのみ有効)。
@c COMMON
@end defivar

@end deftp

@defun sys-getpwuid uid
@defunx sys-getpwnam name
[POSIX]
@c EN
Returns @code{<sys-passwd>} object from an integer user id @var{uid}
or a user name @var{name}, respectively.
If the specified user doesn't exist, @code{#f} is returned.
@c JP
ユーザID@var{uid}もしくはユーザ名@var{name}で示されるユーザの情報を
@code{<sys-passwd>}で返します。該当するユーザが存在しない場合は
@code{#f}が返されます。
@c COMMON
@end defun

@defun sys-uid->user-name uid
@defunx sys-user-name->uid name
@c EN
Convenience functions to convert between user id and user name.
@c JP
ユーザIDとユーザ名を相互変換する便利な手続きです。
@c COMMON
@end defun


@subsubheading Password encryption

@defun sys-crypt key salt
@c EN
This is the interface to @code{crypt(3)}.   @var{Key} and @var{salt}
must be a string, and an encrypted string is returned.
On systems where @code{crypt(3)} is not available, call to this
function signals an error.

This routine is only for the code that needs to check password
against the system's password database.
If you are building user database on your own, you @emph{must} use
@code{crypt.bcrypt} module (@pxref{Password hashing}) instead of
this routine.
@c JP
これは、@code{crypt(3)}へのインターフェースです。@var{key}と@var{salt}は
文字列でなければならず、暗号化された文字列が返されます。
@code{crypt(3)}が利用できないシステムでこの関数を呼ぶとエラーが通知されます。

このルーチンは、システムのパスワードデータベースを使ってパスワードチェックを
しなければならない時以外に使うべきではありません。独自のパスワードデータベースを
新たに作る場合は、@code{crypt.bcrypt}モジュール(@ref{Password hashing})を
使ってください。
@c COMMON
@end defun

@node Locale, Signal, Unix groups and users, System interface
@subsection Locale
@c NODE ロケール

@defun sys-setlocale category locale
[POSIX]
@c EN
Sets/gets the locale of the category @var{category} to the locale @var{locale}.
@var{category} must be an exact integer; the following pre-defined
variables are available.  @var{locale} must be a string locale name,
or @code{#f} if you're merely querying the current locale.

Returns the locale name on success, or @code{#f} if the system
couldn't change the locale.  If you pass @code{#f} to the @var{locale},
it returns the current locale name without changing it.
@c JP
カテゴリー@var{category}のロケールを@var{locale}にセットします。
@var{category}は整数でなければなりません；以下の変数が@var{category}の
ために定義されています。@var{locale}はロケールを表す文字列か@code{#f}です。

成功した場合は新しいロケール名を、ロケールが変更できなかった場合は@code{#f}を
返します。@var{locale}に@code{#f}を渡した場合は、ロケールの変更はせずに
単に現在のロケールの値を文字列で返します。
@c COMMON
@end defun

@defvar  LC_ALL
@defvarx LC_COLLATE
@defvarx LC_CTYPE
@defvarx LC_MONETARY
@defvarx LC_NUMERIC
@defvarx LC_TIME
@c EN
Predefined variables for possible @var{category} value of
@code{sys-setlocale}.
@c JP
@code{sys-setlocale}の@var{category}に渡せる数値を定義しています。
@c COMMON
@end defvar

@defun sys-localeconv
[POSIX]
@c EN
Returns an assoc list of various information for formatting numbers
in the current locale.
@c JP
現在のロケールで数値をフォーマットする際に必要な様々な情報をassoc listに
して返します。
@c COMMON
@end defun

@c EN
An example session.  It may differ on your system settings.
@c JP
例を示します。あなたのシステム設定によっては異なる結果になるかもしれません。
@c COMMON
@example
(sys-localeconv)
 @result{}
   ((decimal_point . ".") (thousands_sep . "")
    (grouping . "") (int_curr_symbol . "")
    (currency_symbol . "") (mon_decimal_point . "")
    (mon_thousands_sep . "") (mon_grouping . "")
    (positive_sign . "") (negative_sign . "")
    (int_frac_digits . 127) (frac_digits . 127)
    (p_cs_precedes . #t) (p_sep_by_space . #t)
    (n_cs_precedes . #t) (n_sep_by_space . #t)
    (p_sign_posn . 127) (n_sign_posn . 127))

(sys-setlocale LC_ALL "fr_FR")
 @result{} "fr_FR"

(sys-localeconv)
 @result{}
  ((decimal_point . ",") (thousands_sep . "")
   (grouping . "") (int_curr_symbol . "FRF ")
   (currency_symbol . "F") (mon_decimal_point . ",")
   (mon_thousands_sep . " ") (mon_grouping . "\x03\x03")
   (positive_sign . "") (negative_sign . "-")
   (int_frac_digits . 2) (frac_digits . 2)
   (p_cs_precedes . #f) (p_sep_by_space . #t)
   (n_cs_precedes . #f) (n_sep_by_space . #t)
   (p_sign_posn . 1) (n_sign_posn . 1))
@end example

@node Signal, System inquiry, Locale, System interface
@subsection Signal
@c NODE  シグナル

@c EN
Gauche can send out operating system's signals to the other processes
(including itself) and can handle the incoming signals.
@c JP
Gaucheでは、OSのシグナルを自分自身や他のプロセスに送ったり、
送られたシグナルを処理することができます。
@c COMMON

@c EN
In multithread environment, all threads share the signal
handlers, and each thread has its own signal mask.
See @ref{Signals and threads}, for details.
@c JP
マルチスレッド環境では、全てのスレッドがシグナルハンドラを共有し、
各スレッドが独自のシグナルマスクを持ちます。
詳しくは@ref{Signals and threads}を参照して下さい。
@c COMMON

@c EN
When a system call is interrupted by a signal,
and a programmer defines a handler for the signal that doesn't transfer
control to other context, the system call is restarted after
the handler returns by default.
@c JP
システムコールがシグナルによって割り込まれ、
プログラマがシグナルハンドラをセットしており、そのハンドラが別コンテキストに
制御を移さずに戻った場合、そのシステムコールは原則としてハンドラからの復帰後に
リスタートされます。
@c COMMON

@c EN
Here are some calls that are not simply restarted by signal interruption.
@c JP
シグナル割り込みによって単純にリスタートされないものは次の通りです。
@c COMMON

@table @code
@item close
@c EN
This may be called through @code{sys-close}, @code{close-port}, or even
implicitly when the underlying file is closed.   When a signal interrupts
this call, the passed fd is no longer in use.  Simply restarting it can
be a race if another thread just grabs the fd.
@c JP
これは@code{sys-close}や@code{close-port}、さらには低層のファイルが自動的に
クローズされる場合に呼ばれます。シグナルがこのシステムコールを中断して@code{EINTR}が
返った時点で、渡されたファイルディスクリプタは無効になっており、もし他のスレッドがその
ディスクリプタを直後に再利用していたら、リスタートするのは競合を引き起こします。
@c COMMON

@item dup2
@c EN
This is called via @code{port-fd-dup!}.  When @code{dup2} returns
@code{EINTR}, the @var{newfd} is no longer in use and some other thread
may grab it before restarting it.
@c JP
このコールは@code{port-fd-dup!}から呼ばれます。@code{dup2}が@code{EINTR}を
返した時、@var{newfd}は使われない状態になっており、他のスレッドが直後にそれを使う
可能性があるのでリスタートは危険です。
@c COMMON

@item sleep
@itemx nanosleep
@c EN
These calls tells the remaining time when they are interrupted.
We restart them with that remaining time, not the original argument,
so that the total sleep time would be close to what was given originally.
@c JP
これらのコールは中断された場合に残りの時間を教えてくれます。
Gaucheではリスタート時に元の引数でなく残りの時間を渡すので、スリープする全体の時間は
おおよそ最初に与えられた時間となります。
@c COMMON
@end table

@c EN
On Windows native platforms, signals don't work except
some limited support of @code{sys-kill}.
@c JP
Windowsネイティブ環境では、@code{sys-kill}の限定的なサポートを
除いてシグナルは動作しません。
@c COMMON

@menu
* Signals and signal sets::
* Sending signals::
* Handling signals::
* Masking and waiting signals::
* Signals and threads::
@end menu

@node Signals and signal sets, Sending signals, Signal, Signal
@subsubsection Signals and signal sets
@c NODE シグナルとシグナルセット

@c EN
Each signal is referred by its signal number (a small integer)
defined on the underlying operating system.
Variables are pre-defined to the system's signal number.
System's signal numbers may be architecture dependent, so you should
use those variables rather than using literal integers.
@c JP
シグナルはオペレーティングシステムで定義された小さな整数値で表現されます。
システムのシグナル番号に束縛された変数が定義されています。
システムのシグナル番号はアーキテクチャによって異なるので、
なるべく変数を利用するようにして下さい。
@c COMMON

@defvar  SIGABRT
@defvarx SIGALRM
@defvarx SIGCHLD
@defvarx SIGCONT
@defvarx SIGFPE
@defvarx SIGHUP
@defvarx SIGILL
@defvarx SIGINT
@defvarx SIGKILL
@defvarx SIGPIPE
@defvarx SIGQUIT
@defvarx SIGSEGV
@defvarx SIGSTOP
@defvarx SIGTERM
@defvarx SIGTSTP
@defvarx SIGTTIN
@defvarx SIGTTOU
@defvarx SIGUSR1
@defvarx SIGUSR2
@c EN
These variables are bound to the signal numbers of POSIX signals.
@c JP
これらの変数はPOSIXで定義された対応するシグナルの番号に束縛されています。
@c COMMON
@end defvar

@defvar  SIGTRAP
@defvarx SIGIOT
@defvarx SIGBUS
@defvarx SIGSTKFLT
@defvarx SIGURG
@defvarx SIGXCPU
@defvarx SIGXFSZ
@defvarx SIGVTALRM
@defvarx SIGPROF
@defvarx SIGWINCH
@defvarx SIGPOLL
@defvarx SIGIO
@defvarx SIGPWR
@c EN
These variables are bound to the signal numbers of system-dependent
signals.  Not all of them may be defined on some systems.
@c JP
これらの変数はシステム依存のシグナル番号に束縛されています。
全てのシステムで全てのシグナルがサポートされているわけではありません。
@c COMMON

@c EN
For portable code, you can use SRFI-238's codeset (@pxref{Codesets}).
@c JP
ポータブルなコードには、SRFI-238のコードセットを使うこともできます
(@ref{Codesets}参照)。
@c COMMON
@end defvar

@c EN
Besides each signal numbers, you can refer to a set of signals
using a @code{<sys-sigset>} object.
It can be used to manipulate the signal mask, and to install a signal
handler to a set of signals at once.
@c JP
それぞれのシグナル番号の他に、@code{<sys-sigset>}オブジェクトを使って
シグナルの集合を扱うことができます。シグナルの集合はシグナルマスクを操作したり、
ひとつのシグナルハンドラを多数のシグナルに同時に設定したりする際に使えます。
@c COMMON

@defun sys-strsignal signum
[POSIX]
@c EN
Interface to @code{strsignal(3)}.  The argument must be an exact
integer.

Returns the system message associated with the signal with the number
@var{signum}, as a string.
if no such message is available, or @var{signum} is not a valid signal number,
this function may return @code{#f} or some generic message provided
by the system.
@c JP
@code{strsignal(3)}へのインタフェースです。引数は正確な整数でなければなりません。

シグナル番号@var{signum}のシグナルに結びつけられたメッセージを文字列で返します。
もしメッセージが無かったり、@var{signum}が有効なシグナル番号でなかったら、
この関数は@code{#f}を返すか、システムが提供する一般的なメッセージを返します。
@c COMMON

@c EN
For portable code, you can use SRFI-238's codeset (@pxref{Codesets}).
@c JP
ポータブルなコードには、SRFI-238のコードセットを使うこともできます
(@ref{Codesets}参照)。
@c COMMON
@end defun


@deftp {Class} <sys-sigset>
@clindex sys-sigset
@c EN
A set of signals.   An empty sigset can be created by
@c JP
シグナルの集合を表します。空のシグナルの集合は次の式で作成できます：
@c COMMON
@example
(make <sys-sigset>) @result{} #<sys-sigset []>
@end example
@end deftp

@defun sys-sigset signal @dots{}
@c EN
Creates and returns an instance of @code{<sys-sigset>}
with members @var{signal} @dots{}.  Each @var{signal}
may be either a signal number, another @code{<sys-sigset>}
object, or @code{#t} for all available signals.
@c JP
@var{signal} @dots{}をメンバーとする@code{<sys-sigset>}の
インスタンスを作成して返します。
各@var{signal}にはシグナル番号、他の@code{<sys-sigset>}オブジェクト、あるいは
@code{#t}を渡すことができます。@code{#t}を渡した場合は全てのシグナルが
対象となります。
@c COMMON

@example
(sys-sigset SIGHUP SIGINT) @result{} #<sys-sigset [HUP|INT]>
@end example
@end defun

@defun sys-sigset-add! sigset signal @dots{}
@defunx sys-sigset-delete! sigset signal @dots{}
@c EN
@var{Sigset} must be a @code{<sys-sigset>} object.
Those procedures adds and removes the specified signals from
@var{sigset} respectively, and returns the result.  @var{sigset} itself
is also modified.

@var{signal} may be either a signal number, another @code{<sys-sigset>}
object, or @code{#t} for all available signals.
@c JP
@var{sigset}は@code{<sys-sigset>}オブジェクトでなければなりません。
これらの手続きは@var{sigset}に指定されたシグナルを追加、
もしくは@var{sigset}から指定されたシグナルを削除します。
変更された@var{sigset}が返されます。

@var{signal}にはシグナル番号、他の@code{<sys-sigset>}オブジェクト、あるいは
@code{#t}を渡すことができます。@code{#t}を渡した場合は全てのシグナルが
対象となります。
@c COMMON
@end defun

@defun sys-sigset-fill! sigset
@defunx sys-sigset-empty! sigset
@c EN
Fills @var{sigset} by all available signals, or empties @var{sigset}.
@c JP
システムで定義された全てのシグナルを@var{sigset}にセット、
もしくは@var{sigset}を空にします。
@c COMMON
@end defun

@defun sys-signal-name signal
@c EN
Returns the human-readable name of the given signal number.
(Note that signal numbers are system-dependent.)
@c JP
シグナル番号の名前を返します。(シグナル番号はシステムに依存します)。
@c COMMON

@c EN
For portable code, you can use SRFI-238's codeset (@pxref{Codesets}).
@c JP
ポータブルなコードには、SRFI-238のコードセットを使うこともできます
(@ref{Codesets}参照)。
@c COMMON

@example
(sys-signal-name 2) @result{} "SIGINT"
@end example
@end defun

@node Sending signals, Handling signals, Signals and signal sets, Signal
@subsubsection Sending signals
@c NODE シグナルの送出

@c EN
To send a signal, you can use @code{sys-kill} which works like
@code{kill(2)}.
@c JP
シグナルを送るには、@code{sys-kill}を使うことができます。
これはシステムの@code{kill(2)}のように動作します。
@c COMMON

@defun sys-kill pid sig
[POSIX]
@c EN
Sends a signal @var{sig} to the specified process(es).  @var{Sig}
must be a positive exact integer.  @var{pid} is an exact integer and
specifies the target process(es):
@c JP
シグナル@var{sig}を指定されたプロセス(群)に送ります。
@var{sig}は正確な正整数でなければなりません。@var{pid}は正確な整数でなければ
ならず、次のルールで対象となるプロセスを指定します。
@c COMMON
@itemize @bullet
@item
@c EN
If @var{pid} is positive, it is the target process id.
@c JP
@var{pid}が正ならば、それがそのまま対象となるプロセスIDです。
@c COMMON
@item
@c EN
If @var{pid} is zero, the signal is sent to every process in the process
group of the current process.
@c JP
@var{pid}がゼロならば、シグナルは現在のプロセスのプロセスグループ内の全ての
プロセスに送られます。
@c COMMON
@item
@c EN
If @var{pid} is less than -1, the signal is sent to every process in
the process group @var{-pid}.
@c JP
@var{pid}が-1より小さければ、シグナルはプロセスグループIDが@var{-pid}である
全てのプロセスに送られます。
@c COMMON
@end itemize

@c EN
On Windows native platforms, @code{sys-kill} may take positive integer
or a process handle (@code{<win:handle>} instance) as @var{pid}.
Only @code{SIGKILL}, @code{SIGINT} and @code{SIGABRT} are allowed
as @var{sig}; Gauche uses @code{TerminateProcess} to terminate
the target process for @code{SIGKILL},
and sends the target process
@code{CTRL_C_EVENT} and @code{CTRL_BREAK_EVENT} for
@code{SIGINT} and @code{SIGABRT}, respectively.
@c JP
Windowsネイティブ環境では、@code{sys-kill}は@var{pid}に正整数か
プロセスハンドル(@code{<win:handle>}のインスタンス)を取ります。
@var{sig}がサポートするのは@code{SIGKILL}、@code{SIGINT}、@code{SIGABRT}
のみです。@code{SIGKILL}に対しては@code{TerminateProcess}を使って
対象プロセスを終了させます。@code{SIGINT}と@code{SIGABRT}に対しては
対象プロセスにそれぞれ@code{CTRL_C_EVENT}と@code{CTRL_BREAK_EVENT}を
送ります。
@c COMMON
@end defun

@c EN
There's no Scheme equivalence for @code{raise()}, but you can use
@code{(sys-kill (sys-getpid) @var{sig})}.
@c JP
POSIXの@code{raise()}に対応するScheme関数はありませんが、
@code{(sys-kill (sys-getpid) @var{sig})} で同じことができます。
@c COMMON

@node Handling signals, Masking and waiting signals, Sending signals, Signal
@subsubsection Handling signals
@c NODE シグナルの処理

@c EN
You can register signal handling procedures in Scheme.
(In multithread environment, signal handlers are shared by all
threads; see @ref{Signals and threads} for details).
@c JP
Schemeでシグナルを処理する手続きを登録できます。
(マルチスレッド環境では、シグナルハンドラの設定は全てのスレッドで共有されます。
@ref{Signals and threads}を参照して下さい)。
@c COMMON

@c EN
When a signal is delivered to the Scheme process, the VM just records it
and processes it later at a 'safe point' where the state of VM is consistent.
We call the signal is @emph{pending} when it is registered by the VM
but not processed yet.
@c JP
シグナルがSchemeプロセスに送られると、VMはそれを記録し、
VMの状態が一貫している「安全なポイント」に達した時に処理します。
シグナルがVMに記録され、しかしまだ処理されていない状態を、
シグナルが保留されていると呼ぶことにします。
@c COMMON

@c EN
(Note that this makes handling of some signals such as @code{SIGILL}
useless, for the process can't continue sensible execution after
recording the signal).
@c JP
(このメカニズムのため、@code{SIGILL}のようなシグナルはSchemeレベルでは
処理できません。そのシグナルを記録した後でプロセスが意味のある処理を続行できない
からです)。
@c COMMON

@c EN
If the same signal is delivered more than once before VM processes
the first one, the second one and later have no effect.  (This is consistent
to the traditional Unix signal model.)  In other words,
for each VM loop a signal handler can be invoked at most once per
each signal.
@c JP
VMがシグナルを処理する前に同じシグナルが到着した場合、後に到着した方の
シグナルは無効になります。(これは伝統的なUnixのシグナル処理と同様です)。
言い替えれば、各VM loop毎に、シグナルハンドラは各シグナルについて
たかだか1回しか呼ばれません。
@c COMMON

@c EN
When too many signals of the same kind are pending,
Gauche assumes something has
gone wrong (e.g. infinite loop inside C-routine) and aborts the
process.  The default of this limit is set rather low (3), to allow
unresponsive interactive script to be terminated by typing Ctrl-C
three times.  Note that the counter is individual for each signal;
Gauche won't abort if one @code{SIGHUP} and two @code{SIGINT}s are
pending, for example.  You can change this limit by
@code{set-signal-pending-limit} described below.
@c JP
同じシグナルがたくさん保留された状態になった場合、
Gaucheは異常事態が起きたとみなし (例えばCルーチンで無限ループに
入った等)、プロセスをabortします。デフォルトではこの限界は
かなり低い値(3)に設定されています。これは、インタラクティブスクリプトが
反応しなくなった場合にCtrl-Cを3回打てば強制終了できる、という場合を
想定しているためです。この限界を調べるカウンタはシグナル毎にあるので、
例えば@code{SIGHUP}がひとつ、@code{SIGINT}がふたつ保留になった、
といった場合はabortしません。この限界は下で述べる@code{set-signal-pending-limit}
で変更することができます。
@c COMMON

@c EN
When you're using the @code{gosh} interpreter, the default
behavior for each signal is as in the following table.
@c JP
@code{gosh}インタプリタを使っている場合、デフォルトでのシグナルの処理は
次のように設定されています。
@c COMMON

@table @code
@item SIGABRT, SIGILL, SIGKILL, SIGSTOP, SIGSEGV, SIGBUS
@c EN
Cannot be handled in Scheme.  @code{Gosh} follows the system's
default behavior.
@c JP
Schemeでは処理できません。@code{gosh}ではこれらのシグナルを受けると
システムのデフォルトの動作をします。
@c COMMON
@item SIGCHLD, SIGTSTP, SIGTTIN, SIGTTOU, SIGWINCH
@c EN
No signal handles are installed for these signals by @code{gosh},
so the process follows the system's default behavior.
A Scheme programs can install its own signal handler if necessary.
@c JP
@code{gosh}は初期状態ではこれらのシグナルのハンドラを設定せず、
システムのデフォルトの振るまいに任せます。Schemeプログラムは必要ならば
これらのシグナルのハンドラを設定できます。
@c COMMON
@item SIGCONT
@c EN
If @code{gosh} is running with input editing mode, a signal handler
is installed to restore terminal status.  Otherwise, no signal
handler is installed by default, and a Scheme program can
install its own signal handler if necessary.
@c JP
@code{gosh}が入力編集モードで起動している場合は、端末状態を回復する
シグナルハンドラが設定されています。それ以外の場合はシグナルハンドラは
設定されず、Schemeプログラムは必要ならば独自のハンドラを設定できます。
@c COMMON
@item SIGHUP, SIGQUIT, SIGTERM
@c EN
@code{Gosh} installs a signal handler for these signals
       that exits from the application with code 0.
@c JP
@code{gosh}はこれらのシグナルに対して、終了コード0でアプリケーションを
       終了するシグナルハンドラをセットします。
@c COMMON
@item SIGPIPE
@c EN
@code{Gosh} installs a signal handler that does nothing---that is,
this signal is effectively ignored by default.

It is a design choice.  Since Gauche delays actual handling
of signals, @code{SIGPIPE} would be handled after the system call
that tries to write to a broken pipe returns with @code{EPIPE}.
That makes the signal a lot less useful, for we can handle the
situation with error handlers for @code{<system-error>} with @code{EPIPE}.

The default Unix behavior of @code{SIGPIPE} is to terminate
the process.  It is useful for the traditional command-line tools
that are often piped together---if one of downstream commands fails,
the upstream process receives @code{SIGPIPE} and the entire
command chain is shut down without a fuss.  The signal is, however, rather an
annoyance for other types of output such as sockets.

Gauche does support this ``exit when pipe gets stuck'' convention
by ports.   A port can be configured as @emph{sigpipe sensitive};
if writing to that port caused @code{EPIPE}, it terminates the
process.  By default, standard output and standard error output
are configured in that way.
@c TODO: In the port section, explain how to configure so.
@c JP
@code{Gosh}は何もしないシグナルハンドラを設定します。
つまり、事実上このシグナルはデフォルトで無視されます。

この設計の意図は次のとおりです。Gaucheはシグナルの処理を安全な
ポイントまで遅延するため、@code{SIGPIPE}はそれを発生させた
システムコールが@code{EPIPE}を返した後で処理されることになります。
この事実によって、@code{SIGPIPE}を処理する必要性は大きく低下します。
書き出した先のパイプが壊れていた場合には@code{EPIPE}の@code{<system-error>}
をハンドルすれば良いからです。

Unixのデフォルトの@code{SIGPIPE}処理は、プロセスを終了させます。
これは伝統的な、パイプでつないでゆくコマンドラインツールにとっては
便利な振る舞いです。下流のコマンドが失敗した場合、上流のコマンドは
@code{SIGPIPE}を受け取るので、つながれたすべてのコマンドが
静かに終了するからです。
けれども、ソケットなど他の種類の出力に対しては、このシグナルは
しばしば邪魔になります。

Gaucheは、この「パイプが詰まったら終了する」という慣習を、
ポートによってサポートします。ポートを「SIGPIPEを感知する」モード
にセットすることができます。そのようなポートへの書き込みが
@code{EPIPE}を発生させる状況になったら、プロセスが終了します。
デフォルトでは、標準出力および標準エラー出力のポートが
このモードになっています。
@c COMMON
@item SIGPWR, SIGXCPU, SIGUSR1, SIGUSR2
@c EN
On Linux platforms with thread support, these signals are used
       by the system and not available for Scheme.  On other systems,
       these signals behaves the same as described below.
@c JP
Linuxプラットフォームでスレッドを使用している場合は、
       これらのシグナルはシステムで使用されるため、Schemeからは使用できません。
       他のシステムではこれらのシグナルは下記の「他のシグナル」と同じ動作と
       なります。
@c COMMON
@c EN
@item other signals
@code{Gosh} installs the default signal handler, which raises
@code{<unhandled-signal-error>} condition (see @ref{Conditions}).
Scheme programs can override it by its own signal handler.
@c JP
@item 他のシグナル
@code{gosh}はデフォルトのシグナルハンドラを設定します。
デフォルトのシグナルハンドラは@code{<unhandled-signal-error>}コンディションを
通知します(@ref{Conditions}参照)。
Schemeプログラムはシグナル毎に独自のハンドラを設定することが可能です。
@c COMMON
@end table

@c EN
If you're using Gauche embedded in some other application,
it may redefine the default behavior.
@c JP
@code{gosh}でなく、他のアプリケーションに埋め込まれたGaucheを使っている場合、
Schemeレベルでのシグナルの使用をアプリケーションが制限している場合があります。
@c COMMON

@c EN
Use the following procedures to get/set signal handlers from Scheme.
@c JP
Schemeからシグナルハンドラを設定するには以下の手続きを使って下さい。
@c COMMON

@defun set-signal-handler! signals handler :optional sigmask
@c EN
@var{Signals} may be a single signal number or a @code{<sys-sigset>}
object, and @var{handler} should be either @code{#t}, @code{#f},
@code{#<undef>}, or a procedure that takes one argument.
If @var{handler} is a procedure, it will be called when the process
receives one of specified signal(s), with the received signal
number as an argument.

By default, the signals in @var{signals} are blocked
(in addition to the signal mask in effect at that time) during
@var{handler} is executed, so that @var{handler} won't be
reentered by the same signal(s).  You can provide
a @code{<sys-sigset>} object to the @var{sigmask} arg
to specify the signals to be blocked explicitly.
Note that the signal mask
is per-thread; if more than one thread unblocks a signal, the handler
may still be invoked during execution of the handler (in other thread)
even if you specify @var{sigmask}.  You have to set the threads'
signal mask properly to avoid such situation.

It is safe to do anything in @var{handler}, including throwing
an error or invoking continuation captured elsewhere.  (However,
continuations captured inside @var{handler} will be invalid
once you return from @var{handler}).
@c JP
@var{signals}はシグナル番号か@code{<sys-sigset>}オブジェクト、
@var{handler}は@code{#t}、@code{#f}、@code{#<undef>}、
一つの引数を取る手続きのいずれかでなければなりません。
@var{handler}が手続きの場合、プロセスが指定されたシグナル(のうちのいずれか)を
受けた時に、そのシグナル番号を引数として@var{handler}が呼ばれます。

デフォルトでは、@var{handler}は、@var{signals}に含まれる
シグナルが(その時点で有効なシグナルマスクに加えて)ブロックされた状態で
実行されます。オプショナルな@var{sigmask}引数に
@code{<sys-sigset>}オブジェクトを渡すことで、
ブロックすべきシグナルを明示することもできます。
ただ、シグナルマスクはスレッド毎であることに注意して下さい。
もし複数のスレッドがあるシグナルをブロックしていない場合、例え@var{sigmask}
を指定していたとしても、ひとつのスレッドで@var{handler}を実行中に
別のスレッドで並行して@var{handler}が呼ばれる可能性はあります。
各スレッドのシグナルマスクを適切に設定することでそのようなケースを
避けるようにして下さい。

@var{handler}の中でできる操作にはほとんど制限がありません。
@var{handler}からエラーを投げたり、他の場所で補捉された継続を呼ぶことも
できます。但し、@var{handler}内で補捉した継続は@var{handler}から
戻った時点で無効になります。
@c COMMON

@c EN
If @var{handler} is @code{#t}, the operating system's default
behavior is set to the specified signal(s).  If @var{handler}
is @code{#f}, the specified signals(s) will be ignored.
@c JP
@var{handler}が@code{#t}の場合、指定されたシグナルにはオペレーティングシステムの
デフォルトの振るまいが設定されます。
@var{handler}が@code{#f}の場合、指定されたシグナルは無視されます。
@c COMMON

@c EN
If @var{handler} is @code{#<undef>} (@pxref{Undefined values}),
it indicates Gauche to leave the current OS's signal handler as it is.
This value isn't as much use in @code{set-signal-handler!} as
in @code{get-signal-handler}: If @code{#<undef>} is passed
to @code{set-signal-handler!}, it immediately returns without
modifying anything.   However, if you get @code{#<undef>}
from @code{get-signal-handler}, you can know that the
signal handler behavior hasn't been modified by Gauche.
(Note that once Gauche ever installs a signal handler,
there is no way to revert back to make @code{get-signal-handler}
return @code{#<undef>}).
@c JP
@var{handler}が@code{#<undef>}
(@ref{Undefined values}参照) であった場合は、
Gaucheはその時点のOSレベルのシグナルハンドラを変更しません。
この引数は@code{set-signal-handler!}に対してはあまり
意味を持ちません; 何もせずに返るだけだからです。
しかし、@code{get-signal-handler}で@code{#<undef>}が
返った場合、Gaucheがそのシグナルハンドラを一度もいじっていないことを
示します。
(一度でもGaucheがシグナルハンドラをインストールした場合、
@code{get-signal-handler}が@code{#<undef>}を再び
返すことはありません。)
@c COMMON

@c EN
Note that signal handler setting is shared among threads in
multithread environment.  The handler is called from the thread
which is received the signal.  See @ref{Signals and threads}
for details.
@c JP
マルチスレッドプログラムでは、
シグナルハンドラの設定はスレッド間で共有されることに注意して下さい。
ハンドラはシグナルを受けたスレッドで実行されます。
詳しくは@ref{Signals and threads}を参照して下さい。
@c COMMON
@end defun

@defun get-signal-handler signum
@defunx get-signal-handler-mask signum
@c EN
Returns the handler setting, or signal mask setting, of a signal @var{signum},
respectively.  See @code{set-signal-handler!} for the meaning of
the return value of @code{get-signal-handler}.
@c JP
シグナル@var{signum}に設定されたハンドラもしくはシグナルマスクを
それぞれ返します。@code{get-signal-handler}が返す値の意味については
@code{set-signal-handler!}を参照してください。
@c COMMON
@end defun

@defun get-signal-handlers
@c EN
Returns an associative list of all signal handler settings.
Car of each element of returned list is a @code{<sys-sigset>} object,
and cdr of it is the handler (a procedure or a boolean value)
of the signals in the set.
@c JP
現在の全てのシグナルハンドラの設定を連想リストにして返します。
返されるリストの各要素のcarには@code{<sys-sigset>}オブジェクトが、
cdrにはそれらのシグナルに対応するハンドラ(手続きもしくはブール値)がセットされて
います。
@c COMMON
@end defun

@defun get-signal-pending-limit
@defunx set-signal-pending-limit limit
@c EN
Gets/sets the maximum number of pending signals per each signal type.
If the number of pending signals exceeds this limit, Gauche aborts
the process.  See the explanation at the beginning of this section
for the details.  @var{Limit} must be a nonnegative exact integer.
In the current implementation the maximum number of @var{limit} is 255.
Setting limit to zero makes the number of pending signals unlimited.
@c JP
それぞれ、同一のシグナルをいくつまで保留することを許すかの現在の限界値を
読み出し、また設定します。
同一のシグナルが限界値を越える回数、処理されないまま保留された場合、
Gaucheはプロセスを強制終了します。本節の冒頭の説明を参照してください。
@var{limit}は非負の正確な整数でなければなりません。
現在の実装では、@var{limit}に設定できる最大値は255です。
また、@var{limit}に0を設定すると、無制限にシグナルを保留できるようになります。
@c COMMON
@end defun


@defmac with-signal-handlers (handler-clause @dots{}) thunk
@c EN
A convenience macro to install signal handlers temporarily
during execution of @var{thunk}.
(Note: though this is convenient, this has certain dangerous
properties described below.  Use with caution.)
@c JP
@var{thunk}の実行中だけシグナルハンドラを一時的に設定する便利なマクロです
(このマクロは便利ですが下に述べるような多少危険な性質もあるので、
注意して使って下さい)。
@c COMMON

@c EN
Each @var{Handler-clause} may be one of the following forms.
@table @code
@item (@var{signals} @var{expr} @dots{})
@var{Signals} must be an expression that will yield either a signal,
a list of signals, or a @code{<sys-sigset>} object.
Installs a signal handler for @var{signals} that evaluates
@var{expr} @dots{} when one of the signals in @var{signals} is delivered.

@item (@var{signals} => @var{handler})
This form sets the handler of @var{signals} to @var{handler},
where @var{handler} should be either @code{#t}, @code{#f}
or a procedure that takes one argument.

If @var{handler} is a procedure, it will be called when the process
receives one of specified signal(s), with the received signal
number as an argument.
If @var{handler} is @code{#t}, the operating system's default
behavior is set to the specified signal(s).  If @var{handler}
is @code{#f}, the specified signals(s) will be ignored.
@end table
@c JP
@var{handler-clause}は以下のいずれかの形式です
@table @code
@item (@var{signals} @var{expr} @dots{})
@var{signals}は、評価された時に単独のシグナル番号、シグナル番号のリスト、
あるいは@code{<sys-sigset>}オブジェクトを生成する式でなければなりません。
@var{signals}に含まれるシグナルを受け取った時に、@var{expr} @dots{}を
評価するようなハンドラを設定します。

@item (@var{signals} => @var{handler})
@var{signals}は上と同じです。@var{signals}に含まれるシグナルに
対して、処理@var{handler}を設定します。

@var{handler}は@code{#t}、@code{#f}、一つの引数を取る手続きのいずれか
でなければなりません。
@var{handler}が手続きの場合、プロセスが指定されたシグナル(のうちのいずれか)を
受けた時に、そのシグナル番号を引数として@var{handler}が呼ばれます。
@var{handler}が@code{#t}の場合、指定されたシグナルにはオペレーティングシステムの
デフォルトの振るまいが設定されます。
@var{handler}が@code{#f}の場合、指定されたシグナルは無視されます。
@end table
@c COMMON

@c EN
When the control exits from @var{thunk}, the signal handler setting
before @code{with-signal-handlers} are recovered.
@c JP
@var{thunk}から制御が抜けた時に、@code{with-signal-handlers}が呼ばれた時点での
シグナルハンドラが再設定されます。
@c COMMON

@c EN
@emph{CAVEAT:} If you're setting more than one signal handlers,
they are installed in serial.  If a signal is delivered before
all the handlers are installed, the signal handler state may be
left inconsistent.  Also note that the handler setting is a global state;
you can't set "thread local" handler by @code{with-signal-handlers},
although the form may be misleading.
@c JP
@emph{注意：} このフォームで一つ以上のシグナルハンドラを設定する場合、
それらは順にシステムに設定されます。全てのハンドラの設定が終る前に
シグナルが届いた場合、シグナルハンドラの設定や再設定が不完全なままになる
かもしれません。また、シグナルハンドラはグローバルな設定であり、
「スレッドローカル」なハンドラを設定することはできませんが、
@code{with-signal-handlers}の形式はそれを誤解させるかもしれません。
@c COMMON
@end defmac

@node Masking and waiting signals, Signals and threads, Handling signals, Signal
@subsubsection Masking and waiting signals
@c NODE シグナルのマスクと待機

@c EN
A Scheme program can set a signal mask, which is a set of signals
to be blocked from delivery.   If a signal is delivered
which is completely blocked in the process, the signal becomes
"pending".  The pending signal may be delivered once the signal
mask is changed not to block the specified signal.
(However, it depends on the operating system whether the pending
signals are queued or not.)
@c JP
Schemeプログラムで、送出がブロックされるシグナルの集合であるシグナルマスク
をセットできます。プロセスで完全にブロックされるシグナルが送出されると、
そのシグナルは``保留''となります。保留されたシグナルは、指定されたシグナルを
ブロックしないようにシグナルマスクが変更されると送出されるかもしれません。
(しかし、保留されたシグナルがキューに入れられるかどうかはオペレーティング
システムに依存します。)
@c COMMON

@c EN
In multithread environment, each thread has its own signal mask.
@c JP
マルチスレッドの環境では、スレッド毎に独自のシグナルマスクを持ちます。
@c COMMON

@defun sys-sigmask how mask
@c EN
Modifies the current thread's signal mask, and returns the previous
signal mask.   @var{Mask} should be a @code{<sys-sigset>} object
to specify the new mask, or @code{#f} if you just want to query
the current mask without modifying one.

If you give @code{<sys-sigset>} object to @var{mask},
@var{how} argument should be one of the following
integer constants:
@c JP
現在のスレッドのシグナルマスクを変更し、以前のシグナルマスクを返します。
@var{mask}には新しいマスクを指定する@code{<sys-sigset>}オブジェクトか、
あるいはマスクを変更せず現在のマスクを得るだけなら@code{#f}を渡します。

@var{mask}に@code{<sys-sigset>}オブジェクトを渡した場合、
引数@var{how}は以下の整数定数のうちの1つでなければなりません。
@c COMMON
@table @code
@item SIG_SETMASK
@c EN
Sets @var{mask} as the thread's signal mask.
@c JP
@var{mask}をそのスレッドのシグナルマスクとしてセットします。
@c COMMON
@item SIG_BLOCK
@c EN
Adds signals in @var{mask} to the thread's signal mask.
@c JP
そのスレッドのシグナルマスクに@var{mask}にあるシグナルを追加します。
@c COMMON
@item SIG_UNBLOCK
@c EN
Removes signals in @var{mask} from the thread's signal mask.
@c JP
そのスレッドのシグナルマスクから@var{mask}にあるシグナルを削除します。
@c COMMON
@end table
@end defun

@defun sys-sigsuspend mask
@c EN
Atomically sets thread's signal mask to @var{mask} and
suspends the calling thread.  When a signal that is not blocked
and has a signal handler installed is delivered, the associated
handler is called, then @code{sys-sigsuspend} returns.
@c JP
アトミックに、スレッドのシグナルマスクを@var{mask}にセットし、
呼び出しているスレッドを一時停止します。ブロックされておらずシグナル
ハンドラがインストールされているシグナルが送出されると、関連
付けられたハンドラが呼ばれ、@code{sys-sigsuspend}は戻ります。
@c COMMON
@end defun

@defun sys-sigwait mask
[POSIX]
@c EN
@var{Mask} must be a @code{<sys-sigset>} object.
If any of signals in @var{mask} is/are pending in the OS,
atomically clears one of them and returns the signal number
of the cleared one.   If there's no signal in @var{mask}
pending, @code{sys-sigwait} blocks until any of the signals
in @var{mask} arrives.

You have to block all signals in @var{mask} in all threads
before calling @code{sys-sigwait}.  If there's a thread
that doesn't block the signals, the behavior of
@code{sys-sigwait} is undefined.

Note: @code{Sys-sigwait} uses system's @code{sigwait} function,
whose behavior is not defined if there's a signal
handler on the signals it waits.  To avoid complication,
@code{sys-sigwait} resets the handlers set to the signals
included in @var{mask} before calling @code{sigwait} to @code{SIG_DFL},
and restores them after @code{sigwait} returns.  If another thread
changes signal handlers while @code{sys-sigwait} is waiting,
the behavior is undefined; you shouldn't do that.
@c JP
@var{mask}は@code{<sys-sigset>}オブジェクトでなければなりません。
アトミックに、保留されたシグナルから@var{mask}にあるシグナルの1つを
クリアし、クリアしたシグナルの番号を返します。@var{mask}にある
シグナルが1つも保留されていなければ、@code{sys-sigwait}はシグナルが
届くまでブロックします。

@code{sys-sigwait}を呼ぶ前に、@var{mask}にある全てのシグナルを、
全スレッドからブロックしておく必要があります。シグナルをブロックして
いないスレッドがある場合、@code{sys-sigwait}の動作は未定義です。

註：@code{sys-sigwait}はシステムの@code{sigwait}関数を呼び出しますが、
この関数は待つべきシグナルにシグナルハンドラが設定されていた場合の
振る舞いが未定義となっています。困ったことになるのを避けるために、
@code{sys-sigwait}はまず@var{mask}に含まれるシグナルに
ハンドラが設定されていたらそれを@code{SIG_DFL}にリセットしてから
@code{sigwait}を呼び出し、それが戻った後でハンドラを元に戻します。
@code{sys-sigwait}が待っている間に他のスレッドでシグナルハンドラを
変更してはいけません。そうした場合の動作は不定です。
@c COMMON
@end defun

@node Signals and threads,  , Masking and waiting signals, Signal
@subsubsection Signals and threads
@c NODE シグナルとスレッド

@c EN
The semantics of signals looks a bit complicated in the multithread
environment.   Nevertheless, it is pretty comprehensible once
you remember a small number of rules.  Besides,
Gauche sets up the default behavior easy to use,
while allowing programmers to do tricky stuff.
@c JP
シグナルのセマンティクスはマルチスレッド環境では少々複雑に見えます。
しかし、いくつかのルールを覚えてしまえば、とても理解しやすいものでも
あります。さらにGaucheでは、プログラマの簡単に使えるようにデフォルトの
振る舞いをセットアップしています。
@c COMMON

@c EN
If you don't want to be bothered by the details, just remember
one thing, with one sidenote.
@strong{By default}, signals are handled by the
primordial (main) thread.  However, if the main thread
is suspended on mutex or condition variable,
the signal may not be handled at all, so be careful.
@c JP
細かいことは知りたくないという場合は、
次の1つのことだけを覚えておいて下さい。
@strong{デフォルトでは}、シグナルはメインスレッドで処理されます。
しかし、メインスレッドがmutexや条件変数で一時停止している場合は、
シグナルは全く処理されないので注意が必要です。
@c COMMON

@c EN
Now, if you are curious about the details, here are the rules:
@c JP
詳細に興味がある場合は、ここにルールがあります。
@c COMMON
@itemize @bullet
@item
@c EN
The signal handler setting is shared by all threads.
@c JP
シグナルハンドラのセッティングは、全てのスレッドで共有されます。
@c COMMON
@item
@c EN
The signal mask is thread-specific.
@c JP
シグナルマスクはスレッド固有です。
@c COMMON
@item
@c EN
If a process receives an asynchronous signal (think it as a signal
delivered from other processes), one thread is chosen, out of
threads which don't block that signal.
@c JP
プロセスが非同期のシグナルを受け取ったら(他のプロセスからシグナルが
送出されたと考えて下さい)、そのシグナルをブロックしていないスレッドの
うちから任意の1つのスレッドが選ばれます。
@c COMMON
@item
@c EN
The signal handler is run on the chosen thread.
However, if the chosen thread is waiting for acquiring a mutex lock
or a condition variable, the handling of signal will be delayed
until the thread is restarted.   Signal delivery itself doesn't
restart the thread.
@c JP
シグナルハンドラは選択されたスレッドにおいて実行されます。
しかし、選択されたスレッドがmutexのロックの獲得や条件変数を待っている
場合は、シグナルの処理はそのスレッドが再開するまで遅延されます。
シグナルの送出自体はスレッドを再開しません。
@c COMMON
@end itemize

@c EN
Now, these rules have several implications.
@c JP
これらのルールにはいくつかの暗黙の了解があります。
@c COMMON

@c EN
If there are more than one thread that don't block a particular
signal, you can't know which thread receives the signal.
Such a situation is much less useful in Gauche than C programs
because of the fact that the signal handling can be delayed indefinitely
if the receiver thread is waiting on mutex or condition variable.
So, it is recommended to make sure, for each signal, there is only one
thread that can receive it.
@c JP
特定のシグナルをブロックしないスレッドが複数ある場合、
どのスレッドがそのシグナルを受け取るかを知る術はありません。
そのような状況は、GaucheにおいてはCプログラムよりもさらに不便です。
なぜなら、受信側のスレッドがmutexや条件変数で待機している場合、
シグナル処理は無期限に遅延されうるからです。
したがって、それぞれのシグナルについて、それを受け取ることのできるスレッドが
常にただの1つしかないようにすることを推奨します。
@c COMMON

@c EN
In Gauche, all threads created by @code{make-thread}
(@pxref{Thread procedures}) blocks all the signals by default
(except the reserved ones).   This lets all the signals
to be directed to the primordial (main) thread.
@c JP
Gaucheでは、@code{make-thread}(@ref{Thread procedures}参照)
で作られた全てのスレッドは、デフォルトで全てのシグナル(予約済みを除く)
をブロックします。これは、全てのシグナルがメインスレッドへ
送られるということです。
@c COMMON

@c EN
Another strategy is to create a thread dedicated for handling
signals.  To do so, you have to block the signals in the
primordial thread, then create the signal-handling thread,
and within that thread you unblock all the signals.
Such a thread can just loop on @code{sys-pause}.
@c JP
もう1つの戦略は、シグナル処理のみを行うスレッドを作る方法です。

もしシステムが@code{sys-sigwait}をサポートしていれば、ハンドル
したい全てのシグナルを全てのスレッドでブロックしておき、シグナル
処理専用のスレッドで@code{sys-sigwait}を呼び出してシグナルの
受信を待つことができます。@code{sys-sigwait}の返り値がシグナル番号
なので、その値でディスパッチしてください。この方法ではシグナル
ハンドラが呼び出されることはありません。

@code{sys-sigwait}を使わないのであれば、メインスレッドでシグナルを
ブロックして、シグナル処理専用スレッドを作り、そのスレッドで全ての
シグナルを受け付けることができます。そのようなスレッドは@code{sys-pause}
で単にループしていれば良いでしょう。@code{sys-pause}がシグナルで中断
されると、シグナルハンドラがシグナル処理専用スレッドで呼び出されます。
@c COMMON

@example
(thread-start!
  (make-thread
    (lambda ()
      (sys-sigmask SIG_SETMASK (make <sys-sigset>)) ;;empty mask
      (let loop () (sys-pause) (loop)))))
@end example

@c EN
Complicated application may want to control per-thread signal
handling precisely.   You can do so, just make sure that
at any moment only the designated thread unblocks the desired
signal.
@c JP
複雑なアプリケーションでは、正確にスレッド毎のシグナル処理を
制御したいかもしれません。それは、いつでも、指定されたスレッドのみが
望むシグナルをブロックしないようにすれば、可能です。
@c COMMON

@node System inquiry, Time, Signal, System interface
@subsection System inquiry
@c NODE システムへの問い合わせ

@defun sys-uname
@c EN
[POSIX] Returns a list of five elements,
@code{(@var{sysname} @var{nodename} @var{release} @var{version} @var{machine})}.
@c JP
[POSIX] 次の5要素のリストを返します。
@code{(@var{sysname} @var{nodename} @var{release} @var{version} @var{machine})}。
@c COMMON
@end defun

@defun sys-gethostname
@c EN
Returns the host name.  If the system doesn't have gethostname(),
the second element of the list returned by @code{sys-uname} is used.
@c JP
ホスト名を返します。システムでgethostname()が使えない場合、
@code{sys-uname}が返すリストの2番目の要素が使われます。
@c COMMON
@end defun

@defun sys-getdomainname
@c EN
Returns the domain name.  If the system doesn't have getdomainname(),
@code{"localdomain"} is returned.
@c JP
ドメイン名を返します。システムでgetdomainname()が使えない場合、
@code{"localdomain"}が返されます。
@c COMMON
@end defun

@defun sys-getcwd
@c EN
[POSIX] Returns the current working directory by a string.
If the current working directory couldn't be obtained from the system,
an error is signaled.   See also @code{sys-chdir}
 (@pxref{Other file operations}), @code{current-directory}
(@pxref{Directory utilities}).
@c JP
[POSIX] 現在の作業ディレクトリを文字列で返します。
システムから現在の作業ディレクトリが得られない場合は、エラーが通知されます。
@code{sys-chdir}(@ref{Other file operations}参照)、@code{current-directory}
(@ref{Directory utilities}参照)も参照して下さい。
@c COMMON
@end defun

@defun sys-getgid
@defunx sys-getegid
@c EN
[POSIX] Returns integer value of real and effective group id of the
current process, respectively.
Use @code{sys-gid->group-name} or @code{sys-getgrgid} to obtain
the group's name and other information associated to the returned
group id (@pxref{Unix groups and users}).
@c JP
[POSIX] 現在のプロセスの実グループIDと実効グループIDをそれぞれ整数で返します。
返されたグループIDからグループ名その他の情報を得るには
@code{sys-gid->group-name}や@code{sys-getgrgid}を使って下さい
(@ref{Unix groups and users}参照)。
@c COMMON
@end defun

@defun sys-setgid gid
@c EN
[POSIX] Sets the effective group id of the current process.
@c JP
[POSIX] 現在のプロセスの実効グループIDをセットします。
@c COMMON
@end defun

@defun sys-getuid
@defunx sys-geteuid
[POSIX]
@c EN
Returns integer value of real and effective user id of the
current process, respectively.
Use @code{sys-uid->user-name} or @code{sys-getpwuid} to obtain
the user's name and other information associated to the returned
user id (@pxref{Unix groups and users}).
@c JP
現在のプロセスの実ユーザIDと実効ユーザIDをそれぞれ整数で返します。
返されたユーザIDからユーザ名その他の情報を得るには
@code{sys-uid->user-name}や@code{sys-getpwuid}を使って下さい
(@ref{Unix groups and users}参照)。
@c COMMON
@end defun

@defun sys-setuid uid
[POSIX]
@c EN
Sets the effective user id of the current process.
@c JP
現在のプロセスの実効ユーザIDをセットします。
@c COMMON
@end defun

@defun sys-setugid?
@c EN
Returns true iff the process is running with suid/sgid-ed (that is,
the program's suid and/or sgid bit is set.)

Note: If the platform has @code{issetugid()} call, we use it.
Otherwise, we remember whether the real (user|group) id and the
effective (user|group) id differ or not at the initialization time.
(In the latter case, we can't detect the case that the process
changes [e]uid/[e]gid before initializing Gauche; keep it in mind if
libgauche is used as an embedded Scheme engine).
@c JP
プロセスがsuid/sgidされていたら@code{#t}を、そうでなければ@code{#f}を返します。

註：プラットフォームが@code{issetugid()}を持っていればそれを呼びます。
そうでない場合は、初期化時に実uid/gidと実効uid/gidが異なるかどうかを
記録しています。(後者の場合、Gaucheが組み込みSchemeエンジンとして使われていて、
プロセスがGauche初期化前に[e]uid/[e]gidを変更していたケースは検出できないことに
留意してください)。
@c COMMON
@end defun

@defun sys-getgroups
@c EN
[POSIX] Returns a list of integer ids of supplementary groups.
@c JP
[POSIX] 補助的なグループのIDの整数のリストを返します。
@c COMMON
@end defun

@defun sys-setgroups gids
@c EN
Sets the current process's groups to the given
list of integer group ids.
The caller must have the appropriate privilege.

This procedure is only available when the feature id
@code{gauche.sys.setgroups} exists.  Use @code{cond-expand} for
the portable program:
@c JP
現在のプロセスのグループIDのリストを、
引数@var{gids}で与えたグループIDのリストに置き換えます。
呼び出すプロセスは適切な特権を持っていなければなりません。

この手続きは、機能識別子@code{gauche.sys.setgroups}があるときのみ
使えます。ポータブルなコードでは@code{cond-expand}を用いてください。
@c COMMON

@example
(cond-expand
  [gauche.sys.setgroups (sys-setgroups '(0 1))]
  [else])
@end example
@end defun

@defun sys-getlogin
@c EN
[POSIX] Returns a string of the name of the user logged in on the
controlling terminal of the current process.
If the system can't determine the information, @code{#f} is returned.
@c JP
[POSIX] 現在のプロセスの制御端末にログインしているユーザの名前を文字列で
返します。システムがその情報を決定できない場合、@code{#f}が返されます。
@c COMMON
@end defun

@defun sys-getpgrp
@c EN
[POSIX] Returns a process group id of the current process.
@c JP
[POSIX] 現在のプロセスのプロセスグループIDを返します。
@c COMMON
@end defun

@c @defun sys-setpgrp
@c Sets the process group id of the current process to the current
@c process id.   Equivalent to @code{sys-setpgid(0, 0)}.
@c @end defun

@defun sys-getpgid pid
@c EN
Returns a process group id of the process specified by @var{pid}.
If @var{pid} is zero, the current process is used.
@c JP
@var{pid}で指定されたプロセスのプロセスグループIDを返します。
@var{pid}が0の場合、現在のプロセスが使われます。
@c COMMON

@c EN
Note that @code{getpgid()} call is not in POSIX.  If the system
doesn't have @code{getpgid()}, @code{sys-getpgid} still works if
@var{pid} is zero (it just calls @code{sys-getpgrp}), but signals
an error if @var{pid} is not zero.
@c JP
@code{getpgid()}はPOSIXではないことに注意して下さい。
システムに@code{getpgid()}がない場合、@var{pid}が0ならば
@code{sys-getpgid}は動作しますが(それは単に@code{sys-getpgrp}を呼びます)、
@var{pid}が0でない場合はエラーが通知されます。
@c COMMON
@end defun

@defun sys-setpgid pid pgid
@c EN
[POSIX] Sets the process group id of the process @var{pid} to @var{pgid}.
If @var{pid} is zero, the process ID of the
current process is used.  If @var{pgid} is zero, the process ID
of the process specified by @code{pid} is used.  (Hence
@code{sys-setpgid(0, 0)} sets the process group id of the
current process to the current process id).
@c JP
[POSIX] プロセス@var{pid}のプロセスグループIDを@var{pgid}にセットします。
@var{pid}が0ならば、現在のプロセスのプロセスIDが使われます。
@var{pgid}が0ならば、@code{pid}で指定されたプロセスのプロセスIDが
使われます。
(したがって、@code{sys-getpgid(0, 0)}は、現在のプロセスのプロセス
グループIDを現在のプロセスIDにセットします。)
@c COMMON
@end defun

@defun sys-setsid
@c EN
[POSIX] Creates a new session if the calling process is
not a process group leader.
@c JP
[POSIX] 呼んでいるプロセスがプロセスグループリーダでなければ、
新しいセッションを作ります。
@c COMMON
@end defun

@defun sys-getpid
@defunx sys-getppid
@c EN
[POSIX] Returns the current process id and the parent process id,
respectively.
@c JP
[POSIX] 現在のプロセスIDと親プロセスのIDをそれぞれ返します。
@c COMMON
@end defun

@defun sys-times
[POSIX]
@c EN
Returns a list of five integers, each signifies the following
value.  The unit of time is @emph{tick}, whose value is determined
by the last element.
@c JP
それぞれ以下の値を示す、5つの整数のリストを返します。
時間の単位は@emph{ティック}で、その大きさは最後の要素で決まります。
@c COMMON
@enumerate
@item
@c EN
User time spent in the current process (@code{tms_utime}).
@c JP
現在のプロセスで費やされたユーザ時間 (@code{tms_utime}).
@c COMMON
@item
@c EN
System time spent in the current process (@code{tms_stime}).
@c JP
現在のプロセスで費やされたシステム時間 (@code{tms_stime}).
@c COMMON
@item
@c EN
User time spent in the children of the current process (@code{tms_cutime}).
@c JP
現在のプロセスの子プロセス達が費やしたユーザ時間 (@code{tms_cutime}).
@c COMMON
@item
@c EN
System time spent in the children of the current process (@code{tms_cstime}).
@c JP
現在のプロセスの子プロセス達が費やしたシステム時間 (@code{tms_cstime}).
@c COMMON
@item
@c EN
The number of ticks per second (@code{sysconf(_SC_CLK_TCK)} or @code{CLOCKS_PER_SEC})
@c JP
1秒あたりのティック数 (@code{sysconf(_SC_CLK_TCK)} もしくは @code{CLOCKS_PER_SEC})
@c COMMON
@end enumerate
@end defun

@defun sys-ctermid
@c EN
[POSIX]  Returns the name of the controlling terminal of the process.
This may be just a @code{"/dev/tty"}.   See also @code{sys-ttyname}.
@c JP
[POSIX] プロセスの制御端末の名前を返します。
これは単に@code{``/dev/tty''}かもしれません。@code{sys-ttyname}も参照して下さい。
@c COMMON
@end defun

@defun sys-getrlimit resource
@defunx sys-setrlimit resource current :optional maximum
[POSIX]
@c EN
Get and set resource limits respectively.
@var{Resource} is an integer constant to specify the resource
of concern.  The following constants are defined.
(The constants marked as bsd and/or linux indicates that they
are not defined in POSIX but defined in BSD and/or Linux.
Other systems may or may not have them.  Consult @code{getrlimit}
manpage of your system for the details.)
@c JP
プロセスのリソースリミットを取得あるいは設定します。
@var{resource}はリソースの種類を指定する整数値です。
以下にリストする定数が定義されています。
(@code{bsd}、@code{linux}とマークされている値は、POSIXでは
定義されていないけれどBSDもしくはLinuxで定義されていることを示します。
他のプラットフォームでそれらが定義されているかどうかは、
該当システムの@code{getrlimit}のマニュアルを参照してください。)

@c COMMON

@example
RLIMIT_AS                      RLIMIT_CORE
RLIMIT_CPU                     RLIMIT_DATA
RLIMIT_FSIZE                   RLIMIT_LOCKS
RLIMIT_MEMLOCK (bsd/linux)     RLIMIT_MSGQUEUE (linux)
RLIMIT_NICE (linux)            RLIMIT_NOFILE
RLIMIT_NPROC (bsd/linux)       RLIMIT_RSS (bsd/linux)
RLIMIT_RTPRIO (linux)          RLIMIT_SIGPENDING (linux)
RLIMIT_SBSIZE                  RLIMIT_STACK
RLIMIT_OFILE
@end example
@end defun

@defun sys-nice inc
[POSIX]
@c EN
Adds @var{inc}, which must be an exact integer, to the current process's
nice value.  Only the root user can specify negative @var{inc} value.
Returns the new nice value.
@c JP
現在のプロセスのnice値に@var{inc}を加算します。@var{inc}は正確な整数でなければなりません。
ルートユーザのみが@var{inc}に負の値を指定できます。
新たなnice値を返します。
@c COMMON
@end defun

@defun sys-strerror errno
@c EN
@var{Errno} must be an exact nonnegative integer representing
a system error number.  This function returns a string describing
the error.
@c JP
@var{errno}はシステムエラー番号を表現する非負正確整数でなければなりま
せん。この関数はエラーを説明する文字列を返します。
@c COMMON

@c EN
For portable code, you can use SRFI-238's codeset (@pxref{Codesets}).
@c JP
ポータブルなコードには、SRFI-238のコードセットを使うこともできます
(@ref{Codesets}参照)。
@c COMMON

@c EN
To represent @var{errno}, the following constants are defined.
Each constant is bound to an exact integer representing the system's
error number.  Note that the actual value may differ among systems,
and some of these constants may not be defined on some systems.
@c JP
@var{errno}を表現するのに、以下の定義済み定数が使えます。各定数はシス
テムエラーを表現する非負正確整数に束縛されています。実際の値はシステム
ごとに違い、またシステムによっては定義されていない定数があるということ
に注意してください。
@c COMMON

@example
E2BIG             EHOSTDOWN         ENETDOWN          ENXIO
EACCES            EHOSTUNREACH      ENETRESET         EOPNOTSUPP
EADDRINUSE        EIDRM             ENETUNREACH       EOVERFLOW
EADDRNOTAVAIL     EILSEQ            ENFILE            EPERM
EADV              EINPROGRESS       ENOANO            EPFNOSUPPORT
EAFNOSUPPORT      EINTR             ENOBUFS           EPIPE
EAGAIN            EINVAL            ENOCSI            EPROTO
EALREADY          EIO               ENODATA           EPROTONOSUPPORT
EBADE             EISCONN           ENODEV            EPROTOTYPE
EBADF             EISDIR            ENOENT            ERANGE
EBADFD            EISNAM            ENOEXEC           EREMCHG
EBADMSG           EKEYEXPIRED       ENOKEY            EREMOTE
EBADR             EKEYREJECTED      ENOLCK            EREMOTEIO
EBADRQC           EKEYREVOKED       ENOLINK           ERESTART
EBADSLT           EL2HLT            ENOMEDIUM         EROFS
EBFONT            EL2NSYNC          ENOMEM            ESHUTDOWN
EBUSY             EL3HLT            ENOMSG            ESOCKTNOSUPPORT
ECANCELED         EL3RST            ENONET            ESPIPE
ECHILD            ELIBACC           ENOPKG            ESRCH
ECHRNG            ELIBBAD           ENOPROTOOPT       ESRMNT
ECOMM             ELIBEXEC          ENOSPC            ESTALE
ECONNABORTED      ELIBMAX           ENOSR             ESTRPIPE
ECONNREFUSED      ELIBSCN           ENOSTR            ETIME
ECONNRESET        ELNRNG            ENOSYS            ETIMEDOUT
EDEADLK           ELOOP             ENOTBLK           ETOOMANYREFS
EDEADLOCK         EMEDIUMTYPE       ENOTCONN          ETXTBSY
EDESTADDRREQ      EMFILE            ENOTDIR           EUCLEAN
EDOM              EMLINK            ENOTEMPTY         EUNATCH
EDOTDOT           EMSGSIZE          ENOTNAM           EUSERS
EDQUOT            EMULTIHOP         ENOTSOCK          EWOULDBLOCK
EEXIST            ENAMETOOLONG      ENOTTY            EXDEV
EFAULT            ENAVAIL           ENOTUNIQ          EXFULL
EFBIG
@end example
@end defun

@defun sys-errno->symbol k
@defunx sys-symbol->errno symbol
@c EN
These procedures convert between integer error number and the symbol
of its unix name (e.g. @code{EINTR}).

If the given error number or name isn't available on the running
platform, those procedures return @code{#f}.  See @code{sys-strerror}
above for potentially available error names.

Valid error names and their actual values differ among platforms.
These procedures make it easy to write portable meta-code that deal
with system errors.

@c TODO: Note about Windows platforms.
@c JP
これらの手続きは、整数のエラー番号と、Unixでのエラー名を表すシンボル(例:@code{EINTR})とを
相互に変換します。

与えられたエラー番号もしくはエラー名が実行中のプラットフォームで有効でない場合は
@code{#f}が返されます。使えるかもしれないエラー名については上の@code{sys-strerror}
の項を参照してください。

有効なエラー名およびその整数値はプラットフォーム毎に異なります。
これらの手続きは、システムエラーを扱うメタなコードをポータブルに書く時に役立つでしょう。
@c COMMON

@c EN
For portable code, you can use SRFI-238's codeset (@pxref{Codesets}).
@c JP
ポータブルなコードには、SRFI-238のコードセットを使うこともできます
(@ref{Codesets}参照)。
@c COMMON
@end defun

@node Time, Process management, System inquiry, System interface
@subsection Time
@c NODE 時間

@c EN
Gauche has two representations of time, one is compatible to POSIX API,
and the other is compatible to SRFI-18, SRFI-19 and SRFI-21.
Most procedures accept both representations; if not, the representation
the procedure accepts is indicated as either 'POSIX time' or 'SRFI time'.
@c JP
Gaucheでは時間は2種類の表現を持ちます。ひとつはPOSIX APIとコンパチブルな
表現で、もう一つはSRFI-18、SRFI-19、SRFI-21とコンパチブルな表現です。
多くの手続きはどちらの表現も理解しますが、そうでない場合は
適用可能な表現を'POSIX time'または'SRFI time'と表記します。
@c COMMON

@c EN
POSIX time is represented by a real number which is a number of seconds
since Unix Epoch (Jan 1, 1970, 0:00:00GMT).
Procedure @code{sys-time}, which corresponds to POSIX @code{time(2)},
returns this time representation.
@c JP
POSIX timeは実数で、Unix Epoch(Jan 1, 1970, 0:00:00GMT)からの秒数で
表現されます。POSIXの@code{time(2)}に対応する@code{sys-time}手続きは
この表現を返します。
@c COMMON

@c EN
SRFI-compatible time is represented by an object of @code{<time>} class,
which keeps seconds and nanoseconds, as well as the type of the time
(UTC, TAI, duration, process time, etc).
@code{Current-time} returns this representation.
@c JP
SRFI互換の時間は@code{<time>}クラスのインスタンスとして表現され、
秒、およびナノ秒のスロットを持ちます。
また、時間の種別(UTC、TAI、期間、プロセス時間、他)も保持しています。
@code{Current-time}はこの表現を返します。
@c COMMON

@subsubheading POSIX time

@defun sys-time
@c EN
[POSIX] Returns the current time in POSIX time
(the time since Epoch (00:00:00 UTC, January 1, 1970),
measured in seconds).  It may be a non-integral number, depending on
the architecture.

Note that POSIX's definition of ``seconds since the Epoch'' doesn't
take leap seconds into account.
@c JP
[POSIX] 現在の時間を POSIX 時間(エポック(00:00:00 UTC, January 1, 1970)
からの秒数)で返します。マシンのアーキテクチャによっては、非正確数で
あるかもしれません。
@c COMMON
@end defun

@defun sys-gettimeofday
@c EN
Returns two values.  The first value is a number of seconds,
and the second value is a fraction in a number of microseconds,
since 1970/1/1 0:00:00 UTC.   If the system doesn't have
@code{gettimeofday} call, this function calls @code{time()};
in that case, microseconds portion is always zero.
@c JP
2つの値を返します。1970/1/1 0:00:00 UTC を基準として、
1つ目の値は秒数、2つ目の値は端数をマイクロ秒で表したものです。
システムが @code{gettimeofday} 呼び出しをサポートしていない場合、
この手続きは @code{time()} を呼び出し、その場合はマイクロ秒の
部分はいつも 0 です。
@c COMMON
@end defun

@deftp {Builtin Class} <sys-tm>
@clindex sys-tm
@c EN
Represents @code{struct tm}, a calendar date.  It has the following slots.
@c JP
カレンダーである、@code{struct tm} を表します。以下のスロットを持ちます。
@c COMMON
@defivar <sys-tm> sec
@c EN
Seconds. 0-61.
@c JP
秒。0-61。
@c COMMON
@end defivar
@defivar <sys-tm> min
@c EN
Minutes. 0-59.
@c JP
分。0-59。
@c COMMON
@end defivar
@defivar <sys-tm> hour
@c EN
Hours.  0-23.
@c JP
時。0-23。
@c COMMON
@end defivar
@defivar <sys-tm> mday
@c EN
Day of the month, counting from 1.  1-31.
@c JP
月の日。1 から数える。1-31。
@c COMMON
@end defivar
@defivar <sys-tm> mon
@c EN
Month, counting from 0.  0-11.
@c JP
月。0 から数える。0-11。
@c COMMON
@end defivar
@defivar <sys-tm> year
@c EN
Years since 1900, e.g. 102 for the year 2002.
@c JP
1900年からの年数。例えば、102 なら 2002年。
@c COMMON
@end defivar
@defivar <sys-tm> wday
@c EN
Day of the week.  Sunday = 0 .. Saturday = 6.
@c JP
曜日。日曜は 0 .. 土曜は 6。
@c COMMON
@end defivar
@defivar <sys-tm> yday
@c EN
Day of the year.  January 1 = 0 .. December 31 = 364 or 365.
@c JP
1年の中での日数。1月1日は 0 .. 12月31日は 364 か 365。
@c COMMON
@end defivar
@defivar <sys-tm> isdst
@c EN
A flag that indicates if the daylight saving time is in effect.
Positive if DST is in effect, zero if not, or negative if unknown.
@c JP
夏時間が有効であるかどうかを指定するフラグ。有効なら正の数、無効なら 0、
分からなければ負の数。
@c COMMON
@end defivar
@end deftp

@defun sys-gmtime time
@defunx sys-localtime time
@c EN
[POSIX] Converts @var{time} to @code{<sys-tm>} object, represented in GMT
or local timezone, respectively.   @var{Time} can be either POSIX-time or
SRFI-time.
@c JP
[POSIX] @var{time} を @code{<sys-tm>} オブジェクトに変換します。
標準時での表現かローカルタイムゾーンでの表現かで使い分けます。
@var{Time} は POSIX 時間か SRFI 時間です。
@c COMMON
@end defun

@defun sys-ctime time
@c EN
[POSIX] Converts @var{time} to it string representation, using POSIX ctime().
@var{Time} can be either POSIX-time or SRFI-time.
@c JP
[POSIX] @var{time} を POSIX の ctime() を使って文字列表現に変換します。
@var{Time} は POSIX 時間か SRFI 時間です。
@c COMMON
@end defun

@defun sys-difftime time1 time0
@c EN
[POSIX] Returns the difference of two times in the real number of seconds.
@var{Time0} and @var{time1} can be either POSIX-time or SRFI-time.
@c JP
[POSIX] 2つの時間の差を、秒の実数で返します。@var{Time0} と@var{time1} は
POSIX 時間か SRFI 時間です。
@c COMMON
@end defun

@defun sys-asctime tm
@c EN
[POSIX] Converts @code{<sys-tm>} object @var{tm} to a string representation.
@c JP
[POSIX] @code{<sys-tm>} オブジェクトである @var{tm} を文字列表現に変換します。
@c COMMON
@end defun

@defun sys-strftime format tm
@c EN
[POSIX] Converts @code{<sys-tm>} object @var{tm} to a string representation,
according to a format string @var{format}.
See your system's manual entry of @code{strftime} for the
supported @var{format}.

It may return an empty string if the formatting results in an unusually
lengthy string.
@c JP
[POSIX] @code{<sys-tm>} オブジェクトである @var{tm} を、フォーマット文字列
@var{format} に従って文字列表現に変換します。
@var{format}の書き方はシステムの@code{strftime}のマニュアルエントリを参照してください。

フォーマット結果が異常に長い文字列になる場合は、空文字列が返されることがあります。
@c COMMON
@end defun

@defun sys-mktime tm
@c EN
[POSIX] Converts @code{<sys-tm>} object @var{tm}, expressed as local time,
to the POSIX-time (number of seconds since Epoch).
@c JP
[POSIX] ローカルタイムとして表現された @code{<sys-tm>} オブジェクトである
@var{tm} を POSIX 時間(エポックからの秒数)に変換します。
@c COMMON
@end defun

@defun sys-tm->alist tm
@c DEPRECATED
@c EN
Converts @code{<sys-tm>} instance to a list of
@code{(@var{slot-name} . @var{value}}.
This is only kept for the backward compatibility.  You can access
@code{<sys-tm>} object with @code{slot-ref} and @code{~}
@c JP
@code{<sys-tm>}のインスタンスを@code{(@var{slot-name} . @var{value}}の
リストに変換します。
これは互換性のためだけに提供されています。
@code{<sys-tm>}の内容にアクセスするには@code{slot-ref}や@code{~}を使ってください。
@c COMMON
@end defun


@subsubheading SRFI time

@deftp {Builtin Class} <time>
@clindex time
@c EN
The @code{<time>} object also represents a point of time.
@c JP
ある時刻を表す@code{<time>}オブジェクトです。
@c COMMON

@clindex time
@defivar <time> type
@c EN
Indicates time type.  @code{time-utc} is the default, and that
represents the number of seconds since Unix Epoch.
SRFI-19 (@pxref{Time data types and procedures}) adds more types.
@c JP
timeの型を表します。デフォルトは@code{time-utc}で、Unixエポックからの
秒数を表します。SRFI-19(@ref{Time data types and procedures}参照)
ではさらに型が追加されています。
@c COMMON
@end defivar
@defivar <time> second
@c EN
Second part of the time.
@c JP
timeの秒の部分です。
@c COMMON
@end defivar
@defivar <time> nanosecond
@c EN
Nanosecond part of the time.
@c JP
timeのナノ秒の部分です。
@c COMMON
@end defivar
@end deftp

@defun current-time
@c EN
[SRFI-18][SRFI-21]
Returns the @code{<time>} object representing the current time in
@code{time-utc}.   @xref{Time data types and procedures}, for
it redefines @code{current-time} to allow optional argument to
specify time type.
@c JP
[SRFI-18][SRFI-21]
現在の時間を@code{time-utc}で表す@code{<time>}オブジェクトを返します。
@ref{Time data types and procedures}では、@code{current-time}が再定義され、
timeの型を指定するオプショナル引数を受け付けるようにされています。
@c COMMON
@end defun

@defun time? obj
[SRFI-18][SRFI-19][SRFI-21]
@c EN
Returns @code{#t} if @var{obj} is a time object.
@c JP
@var{obj}がtimeオブジェクトなら@code{#t}を返します。
@c COMMON
@end defun

@defun absolute-time obj :optional current-time
@c EN
The argument must be either a @code{<time>} object, a real number,
or @code{#f}.  If it is an absolute @code{<time>} object, it specifies
an absolute point of time.  If it is a @code{<time>} object of
@code{time-duration} type, it is taken as a relative time from the current time.
If it is a real number, it specifies
the number of seconds from the current time.

This procedure returns @code{#f} if the argument is @code{#f},
and a UTC @code{<time>} object for an absolute point of time otherwise.

Most procedures that takes `timeout' argument accepts @code{<time} object,
real number or @code{#f}.  This procedure is useful to process
such argument in the same way.
@c JP
引数は@code{<time>}オブジェクト、実数、もしくは@code{#f}でなければなりません。
絶対時刻を表す@code{<time>}オブジェクトの場合は絶対時刻を、
@code{time-duration}型の@code{<time>}オブジェクトの場合は現在時刻からの相対時間を、
実数の場合は現在時刻からの相対秒数を示します。

この手続きは、引数が@code{#f}なら@code{#f}を、そうでなければ
絶対時刻に変換したUTC @code{<time>}オブジェクトを返します。

timeout引数を取る多くの手続きが、同じ形式の引数を取ります。
この手続きはそれらと同様に時刻を扱うのに便利です。
@c COMMON

@c EN
The optional @var{current-time} is, if provided, must be an
absolute @code{<time>} object or @code{#f}.  If it is a @code{<time>}
object, it is used as the current time instead of the actual current time.
@c JP
省略可能な@var{current-time}オブジェクトは、もし与えられたなら
絶対時刻の@code{<time>}オブジェクトか@code{#f}でなければなりません。
@code{<time>}オブジェクトの場合は、実際の現在時刻のかわりに
それが現在時刻として使われます。
@c COMMON
@end defun

@defun seconds+ time x
[SRFI-226+]
@c EN
Returns a time object that is @var{x} seconds after the given @var{time}.
The type of returned time object is the same as @var{time}.
The argument @var{x} must be a finite real number.  If it is negative,
returnd time is before the given time.

This procedure is mainly to write code compatibe to SRFI-226.
For Gauche-specific code, you can use @code{absolute-time} above.

@xref{SRFI-19 Time procedures}, for another way to compute with time
difference by @code{add-duration}/@code{subtract-duration}.
@c JP
与えられた@var{time}より@var{x}秒後を表すtimeオブジェクトを作って返します。
返されるtimeオブジェクトの型は@var{time}と同じです。
@var{x}は有限の実数です。@var{x}が負の場合は、与えられた時間より前の時間が返ります。

この手続きはSRFI-226準拠のコードを書くために用意されています。
Gauche専用のコードなら上の@code{absolute-time}も使えます。

時間の計算には、SRFI-19の@code{add-duration}/@code{subtract-duration}
も使えます。@ref{SRFI-19 Time procedures}を参照してください。
@c COMMON
@end defun


@defun time->seconds time
@defunx seconds->time seconds
[SRFI-18][SRFI-21]
@c EN
Converts between time object and the number of seconds (POSIX-time).
@var{Time} argument of @code{time->seconds} has to be a @code{<time>} object.
@c JP
timeオブジェクトと秒数(POSIX時間)を変換します。
@code{time->seconds}の引数@var{time}は、@code{<time>}オブジェクトで
なければなりません。
@c COMMON
@end defun


@node Process management, I/O multiplexing, Time, System interface
@subsection Process management
@c NODE プロセス管理

@c EN
The following procedures provide pretty raw, direct interface
to the system calls.
See also @ref{High-level process interface}, which provides
more convenient process handling on top of these primitives.
@c JP
以下の手続きは、システムコールに対する直接的なインタフェースを提供します。
@ref{High-level process interface}も合わせて参照して下さい。
より高レベルの便利な手続きが定義されています。
@c COMMON

@subsubheading Fork and exec

@defun sys-system command
@c EN
[POSIX]
Runs @var{command}, which must be a string, in a subprocess.
@var{command} is usually passed
to @code{sh}, so the shell metacharacters are interpreted.
@c JP
[POSIX]
サブプロセスで文字列@var{command}を実行します。@var{command}は通常、
@code{sh}へ渡されるので、シェルのメタキャラクタは解釈されます。
@c COMMON

@c EN
If the operating system fails to spawn a subshell, a @code{<system-error>}
is thrown.  Otherwise, it waits until the subshell terminates, and
the integer termination status of the subshell is
returned.
@c JP
OSがサブシェル実行に失敗した場合は、@code{<system-error>}エラーが投げられます。
そうでなければ、この手続きはサブシェルが終了するまで待ち、サブシェルの
終了ステータス(termination status)を整数で返します。
@c COMMON

@c EN
The termination status must be interpreted as the same way as
the return value of @code{sys-wait}, described below.  For example,
if you want to get exit status, you have to test the result with
@code{sys-wait-exited?}, then apply @code{sys-wait-exit-status}.
@c JP
終了ステータスは@code{sys-wait}の戻り値と同じように解釈できます。
例えば、exit statusを取るにはまず戻り値を@code{sys-wait-exited?}で検査して、
それから@code{sys-wait-exit-status}を適用します。
@c COMMON

@c EN
In general, analyzing the result of @code{sys-system} properly is cumbersome,
for nonzero code may indicate subshell's abnormal exit or signalled status
or the command's abnormal exit or signalled status.
We recommend to use @code{do-process} etc. of @code{gauche.process}
module if you need to handle subprocess' exit status
(@pxref{High-level process interface}).
@c JP
一般的に、@code{sys-system}の戻り値をきちんと解析するのは面倒です。
というのも、ゼロでない場合、それはサブシェル本体の異常終了もしくはシグナルによる終了
を表しているかもしれないし、@var{command}の異常終了もしくはシグナルによる終了
を表しているかもしれないからです。
サブプロセスの終了コードを精査する必要がある場合は、
@code{gauche.process}モジュールの@code{do-process}等を使うことを推奨します
(@ref{High-level process interface}参照)。
@c COMMON

@c EN
On Windows native platforms this will pass the argument to @code{cmd.exe}.
We strongly discourage invoking @code{cmd.exe} with externally
supplied arguments, since it is impossible to safely escape
arbitrary string for @code{cmd.exe} arguments on Windows.
@c JP
Windowsネイティブな環境では、引数は@code{cmd.exe}に渡されます。
外部から供給された文字列を引数にして@code{cmd.exe}を呼び出すことは
避けてください。Windowsの@code{cmd.exe}に渡す任意の文字列を安全にエスケープすることは
事実上不可能です。
@c COMMON
@end defun

@defun sys-fork
@c EN
[POSIX]
Fork the current process.  Returns 0 if you're in the child process,
and a child process' pid if you're in the parent process.
All the opened file descriptors are shared between the parent and
the child.  See @code{fork(2)} of your system for details.
@c JP
[POSIX]
現在のプロセスをフォークします。子プロセスにいるならば0が返り、
親プロセスにいるならば子プロセスのプロセスIDが返ります。
全ての開かれているファイルディスクリプタは、親プロセスと子プロセスで
共有されます。詳細は、システムの@code{fork(2)}を参照して下さい。
@c COMMON

@c EN
If the child process runs some Scheme code and exits instead of
calling @code{sys-exec}, it should call @code{sys-exit}
instead of @code{exit} to terminate itself.
Normal exit call tries to flush the file
buffers, and on some OS it messes up the parent's file buffers.
@c JP
子プロセスが@code{sys-exec}を呼ぶ代わりにSchemeコードを実行して
終了する場合は、@code{exit}ではなく@code{sys-exit}を呼ぶ必要があります。
通常のexitの呼び出しはファイルバッファのフラッシュを試み、
OSによっては親のファイルバッファを混乱させるでしょう。
@c COMMON

@c EN
It should be noted that @code{sys-fork} is not safe when
multiple threads are running.  Because @code{fork(2)} copies
the process' memory image which includes any mutex state,
a mutex which is locked by another thread at the time of @code{sys-fork}
remains locked in the child process, nevertheless the child process
doesn't have the thread that unlock it!
(This applies to the internal mutexes as well, so even you don't
use Scheme mutex explicitly, this situation can always happen.)

If what you want is to spawn another program in a multi-threaded application,
use @code{sys-fork-and-exec} explained below.
If you absolutely need to run Scheme code in the
child process, a typical technique is that you fork a manager process
at the beginning of application, and whenever you need a new process
you ask the manager process to fork one for you.
@c JP
@code{sys-fork}は複数のスレッドが走っている時には安全ではないことに
注意してください。@code{fork(2)}システムコールはプロセスのメモリイメージを
複製しますが、それには他のスレッドでロックされているmutexも含まれます。
もし@code{sys-fork}の瞬間に他のスレッドが何かをロックしていたとすれば、
子プロセスでもその資源はロックされたままになりますが、
その時子プロセスはもはやその資源をアンロックするスレッドを持っていません。
(これは内部で使っているmutexにも起こり得るため、Schemeレベルでmutexを
全く使っていないとしても防ぐことはできません)。

やりたいことが、マルチスレッドアプリケーションで別プログラムをspawnする
ことであるなら、下に説明する@code{sys-fork-and-exec}を使ってください。
どうしても別プロセスでSchemeコードを走らせたいのなら、よくある方法は、
アプリケーションの起動後すぐにマネージャプロセスとなる子プロセスをfork
しておき、新たなプロセスが欲しくなったらそのマネージャプロセスに
forkを依頼するという方法です。
@c COMMON

@c EN
This procedure is not available on Windows native platforms.
@c JP
Windowsネイティブな環境ではこの手続きは使えません。
@c COMMON
@end defun

@defun sys-exec command args :key directory iomap sigmask environment
@c EN
[POSIX+]
Execute @var{command} with @var{args}, a list of arguments.
The current process image is replaced by @var{command},
so this function never returns.
@c JP
[POSIX+]
@var{command}を引数のリストである@var{args}を伴って実行します。
現在のプロセスイメージは@var{command}に置き換えられるので、
この関数は戻りません。
@c COMMON

@c EN
All elements of @var{args} must be strings.  The first element of
@var{args} is used as @code{argv[0]}, i.e. the program name.
@c JP
@var{args}の全ての要素は文字列でなければなりません。
@var{args}の最初の要素は、@code{argv[0]}、すなわちプログラム名として
使われます。
@c COMMON

@c EN
(NB: On Windows, you can invoke batch files (@file{*.bat}, @file{*.cmd})
using @code{sys-exec} and @code{sys-fork-and-exec}, but you can't
use characters @code{()%!^<>&|"} within the command-line arguments,
since there's no comprehensive way to escape them safely.
You can pass them if you directly invoke an executable file.)
@c JP
(註: Windowsでは、@code{sys-exec}と@code{sys-fork-and-exec}で
バッチファイル(@file{*.bat}, @file{*.cmd})を起動することもできます。
ただその場合、コマンドライン引数に文字@code{()%!^<>&|"}のいずれかを含めることは
できません。これらの文字を安全にエスケープする包括的な方法が無いからです。
実行可能ファイルを直接指定する場合はこの制限はありません。)
@c COMMON

@c EN
The keyword argument @var{directory} must be a string of a
directory name or @code{#f}.
If it is a string, @code{sys-exec} change current working directory
there before executing the program.
@c JP
キーワード引数@var{directory}は文字列によるディレクトリ名
か@code{#f}でなければなりません。
文字列だった場合、@code{sys-exec}はプログラムを実行する前に
カレントワーキングディレクトリを指定ディレクトリに移動します。
@c COMMON

@c EN
The @var{iomap} keyword argument, when provided, specifies how the
open file descriptors are treated.  It must be the following format:
@c JP
キーワード引数の@var{iomap}は、与えられた場合は、開かれている
ファイルディスクリプタがどのように扱われるかを指定します。
この引数は以下のフォーマットでなければなりません。
@c COMMON
@example
((@i{to-fd} . @i{from-port-or-fd}) @dots{})
@end example
@c EN
@i{To-fd} must be an integer,
and @i{from-port-or-fd} must be an integer file descriptor or a port.
Each element of the list makes the file descriptor of @i{from-port-or-fd}
of the current process be mapped to the file descriptor @i{to-fd}
in the executed process.
@c JP
@i{to-fd}は整数でなければならず、@i{from-port-or-fd}は整数のファイル
ディスクリプタかポートでなければなりません。
リストのそれぞれの要素は、現在のプロセスの@i{from-port-or-fd}の
ファイルディスクリプタを、実行されているプロセスのファイルディスクリプタ
@i{to-fd}にマップさせます。
@c COMMON

@c EN
If @var{iomap} is provided,
any file descriptors other than specified in the iomap list will be closed
before @code{exec()}.  Otherwise, all file descriptors in the current
process remain open.
@c JP
@var{iomap}が与えられると、iomapリストで指定されていないいかなるファイル
ディスクリプタも@code{exec()}の前に閉じられます。さもなければ、現在のプロセスの
全てのファイルディスクリプタは開かれたままになります。
@c COMMON

@example
(sys-exec "ls" '("ls" "-l")) @result{} ;; ls is executed.

(let ((out (open-output-file "ls.out")))
  (sys-exec "ls" '("ls" "-l") :iomap `((2 . 1) (1 . ,out)))
   @result{}
  ;; ls is executed, with its stderr redirected
  ;; to the current process's stdout, and its
  ;; stdout redirected to the file "ls.out".
@end example

@c EN
The @var{sigmask} keyword argument can be an instance of @code{<sys-sigset>}
or @code{#f} (@xref{Signal}, for the details of signal masks).
If it is an instance of @code{<sys-sigset>}, the signal mask of calling
thread is replaced by it just before @code{exec(2)} is called.
It is useful, for example, to run an external program from a thread where
all signals are blocked (which is the default; see @ref{Signals and threads}).
Without setting @var{sigmask}, the @code{exec}ed process inherits
calling thread's signal mask and become a process that blocks all signals,
which is not very convenient in most cases.
@c JP
@var{sigmask}キーワード引数には、@code{<sys-sigset>}のインスタンスか
@code{#f}を渡すことができます (シグナルマスクについては@ref{Signal}を
参照して下さい)。@code{<sys-sigset>}のインスタンスを渡した場合、
この関数を呼び出したスレッドのシグナルマスクが、@code{exec(2)}を呼ぶ
直前にそれによって置き換えられます。
これは、全てのシグナルをブロックしているスレッドから外部プログラムを走らせる
ような場合に便利です (@ref{Signals and threads}で述べるように、
新たなスレッドは全てのシグナルをデフォルトでブロックします)。
このような場合に@var{sigmask}を設定しないと、@code{exec}されたプロセスは
スレッドのシグナルマスクを継承し、ほとんどのシグナルを受け付けないプロセスと
なってしまうからです。通常、それはあまり便利ではありません。
@c COMMON

@c EN
Finally, @var{environment} keyword argument specifies
the environment where the new process sees.
If it is @code{#f} (default), the new process sees the same enviornment
of the caller process.
Otherwise, it must be a list of strings.
Each string must be a form of @code{"NAME=VALUE"}, where @var{NAME}
is the name of envionemnt variable, and @var{VALUE} is its value.
Environment variable's name cannot contain @code{=}, while its value can.
This format is compatible with what @code{sys-environ} returns
(@pxref{Environment inquiry}),
so that you can get the current enviornment with @code{sys-environ},
add/remove/modify some of its entries, and pass it to this argument.
@c JP
最後に、@var{environment}キーワード引数は新たなプロセスから見える環境を指定します。
デフォルト値は@code{#f}で、その場合は新たなプロセスは現在のプロセスの環境を引き継ぎます。
そうでなければ、引数は文字列のリストでなければならず、
各文字列は@code{"NAME=VALUE"}の形式でなければなりません。
@var{NAME}が環境変数の名前を、@var{VALUE}がその値を示します。
@var{NAME}は@code{=}を含むことはできませんが、@var{VALUE}に@code{=}を含めることは
できます。
この形式は@code{sys-environ}が返す形式と互換です
(@ref{Environment inquiry}参照)。
したがって、@code{sys-environ}で取得した環境にエントリを追加したり、
そこからエントリを削除したりしてこの引数に渡すことができます。
@c COMMON

@c EN
When @code{sys-exec}
encounters an error, most of the time it raises an error condition.
Once the file descriptors are permuted, however, it would be impractical
to handle errors in reasonable way (you don't even know stderr is still
available!), so Gauche simply exits on the error.
@c JP
@code{sys-exec}がエラーに遭遇すると、たいていの場合エラー条件を投げます。
しかし一旦ファイルディスクリプタの順番が変えられると、合理的な方法でエラーを処理する
ことは実行不可能です(標準エラーがまだ有効かどうかさえ知る術がありません)。
したがって、その場合はGaucheはエラー時には単に終了するだけです。
@c COMMON

@c EN
On Windows native platforms, only redirections of stdin, stdout and stderr
are handled.   Singal mask is ignored, for Windows doesn't have
signals as the means of interprocess communication.
@c JP
Windowsネイティブ環境では、標準入力、標準出力、標準エラー出力に
関するリダイレクションのみが処理されます。Windowsはプロセス間通信としての
シグナルをサポートしないので、シグナルマスクは無視されます。
@c COMMON
@end defun

@defun sys-fork-and-exec command args :key directory iomap sigmask detached environment
@c EN
Like @code{sys-exec}, but executes @code{fork(2)} just before
remapping I/O, altering signal mask and call @code{execvp(2)}.
Returns child's process id.  The meanings of arguments are
the same as @code{sys-exec}.

It is strongly recommended to use this procedure instead of
@code{sys-fork} and @code{sys-exec} combination when you need
to spawn another program while other threads are running.
No memory allocation nor lock acquisition is done between
@code{fork(2)} and @code{execvp(2)},
so it's pretty safe in the multithreaded environment.
@c JP
@code{sys-exec}と同じですが、ファイルディスクリプタとシグナルマスクを変更して
@code{execvp(2)}を実行する直前に、@code{fork(2)}を実行します。
子プロセスのプロセスidを返します。引数の意味は@code{sys-exec}と同じです。

他のスレッドが走っている環境下で別プログラムをspawnしたい場合は、
@code{sys-fork}と@code{sys-exec}を別々に使うのではなく、
この手続きを使ってください。
この手続き中では、@code{fork(2)}と@code{execvp(2)}の間で
メモリアロケーションもロックの獲得も行われないため、
マルチスレッド環境で実行しても安全になっています。
@c COMMON

@c EN
On Windows native platforms, this procedure returns a
Windows handle object (@code{<win:handle>}) of the created
process instead of an integer process ID.  See below for
Windows process handle specific API.

Like @code{sys-exec}, only redirections of stdin, stdout and stderr
are handled on Windows native platforms.
@c JP
Windowsネイティブ環境では、この手続きはプロセスIDではなく
作られたプロセスに対するWindowsのハンドルオブジェクト
(@code{<win:handle>}) を返します。Windowsプロセスハンドル
特有の手続きについては後に述べます。

また、@code{sys-exec}同様、Windowsネイティブ環境では、標準入力、標準出力、標準エラー出力に
関するリダイレクションのみが処理されます。
@c COMMON

@c EN
When a true value is given to the @var{detached} keyword argument,
the executed process is detached from the current process group
and belongs to its own group.
That is, it won't be affected to the signal sent to the process group
the caller process currently belongs to.
It is a part of the common idioms to start a daemon process.

On Unix platforms, besides the executed process gets its own session
by @code{setsid(2)}, it performs extra @code{fork(2)} to make its
parent be the @code{init} process (pid=1).
(Note: It means the running process is actually a grandchild of the
calling process, although that relationship isn't preserved.
The returned pid is the running process's one,
not the intermediate process that exits immediately.)

On Windows native platforms,
this flag causes the new process to be
created with the @code{CREATE_NEW_PROCESS_GROUP} creation flag.
@c JP
@var{detached}キーワード引数に真の値が与えられた場合、
実行されるプロセスは現在のプロセスグループからは切り離されます。
つまり、現在のプロセスグループに送られるシグナルを、新しいプロセスは受け取りません。
この動作はデーモンプロセスを作る際の標準的な手順のひとつです。

Unixでは、実行されるプロセスが@code{setsid(2)}を呼んで
独自のセッションを作るだけでなく、余分な@code{fork(2)}
を実行することで親を@code{init}プロセス (pid=1) に切り替えます。
(つまり、実行されるプロセスは実は呼び出すプロセスの孫にあたります。
親子関係はなくなりますが。返されるpidは実際に走っているこのプロセスのもので、
すぐに終了する中間プロセスのものではありません。)

Windowsネイティブ環境では、このフラグがあると
プロセス作成時に@code{CREATE_NEW_PROCESS_GROUP}フラグが使われます。
@c COMMON
@end defun

@subsubheading Wait

@defun sys-wait
@c EN
[POSIX] Calls system's @code{wait(2)}.  The process suspends its execution
until one of the child terminates.  Returns two exact integer values,
the first one is the child's process id, and the second is a status code.
The status code can be interpreted by the following functions.
@c JP
[POSIX] システムの@code{wait(2)}を呼びます。プロセスは、子プロセスの1つが
終了するまでその実行を一時停止します。2つの正確整数、1つ目は子プロセスのID、
2つ目はステータスコードを返します。ステータスコードは以下の関数によって
解釈できます。
@c COMMON
@end defun

@defun sys-waitpid pid :key nohang untraced
@c EN
[POSIX] This is an interface to @code{waitpid(3)}, an extended version of
wait.
@c JP
[POSIX] これは、waitの拡張バージョンである、@code{waitpid(3)}への
インターフェースです。
@c COMMON

@c EN
@var{pid} is an exact integer specifying which child(ren) to be waited.
If it is a positive integer,
it waits for that specific child.  If it is zero, it waits for any
member of this process group.  If it is -1, it waits for any child process.
If it is less than -1, it waits for any child process whose process group
id is equal to the absolute value of @var{pid}.
@c JP
@var{pid}は、待つべき子プロセスを指定する正確な整数です。正の整数ならば、
特定の子プロセスを待ちます。0ならば、このプロセスグループのいずれかの
メンバを待ちます。-1ならば、いずれかの子プロセスを待ちます。
-1よりも小さければ、プロセスグループIDが@var{pid}の絶対値と等しいいずれかの
子プロセスを待ちます。
@c COMMON

@c EN
If there's no child process to wait, or a specific @var{pid} is
given but it's not a child process of the current process,
an error (@code{<system-error>}, @code{ECHILD}) is signaled.
@c JP
待つべき子プロセスが存在しない場合や、@var{pid}に具体的なプロセスIDが
与えられたがそれが現在のプロセスの子プロセスでない場合は
エラー(@code{<system-error>}, @code{ECHILD})となります。
@c COMMON


@c EN
The calling process suspends until one of those child process is terminated,
unless true is specified to the keyword argument @var{nohang}.
@c JP
キーワード引数@var{nohang}に真値が指定されていなければ、
呼んでいるプロセスは、それらの子プロセスのうちの1つが終了するまで一時停止します。
@c COMMON

@c EN
If true is specified to the keyword argument @var{untraced},
the status of stopped child process can be also returned.
@c JP
キーワード引数@var{untraced}に真値が指定されていれば、
停止した子プロセスのステータスも返ります。
@c COMMON

@c EN
The return values are two exact integers, the first one is the child
process id, and the second is a status code.  If @var{nohang} is true and
no child process status is available, the first value is zero.
@c JP
戻り値は2つの正確整数で、1つ目は子プロセスのID、2つ目はステータスコードです。
@var{nohang}が真で子プロセスのステータスが利用できない場合は、1つ目の値は0です。
@c COMMON

@c EN
On Windows native platforms, this procedure may also accept
a Windows process handle (@code{<win:handle>}) object as @var{pid} to
wait the specific process.  You can pass @code{-1} as @var{pid}
to wait for any children, but you cannot wait for a specific
process group.
@c JP
Windowsネイティブ環境では、この関数は@var{pid}にWindowsプロセスハンドル
(@code{<win:handle>})オブジェクトを受け取ることもできます。
その場合はそのハンドルの指すプロセスの終了を待ちます。
また、@code{-1}を渡していずれかの子プロセスの終了を待つこともできますが、
特定のプロセスグループの中の子プロセスを待つことはできません。
@c COMMON
@end defun

@defun sys-wait-exited? status
@defunx sys-wait-exit-status status
@c EN
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-wait} or @code{sys-waitpid}.
@code{sys-wait-exited?} returns @code{#t} if the child process is
terminated normally.   @code{sys-wait-exit-status} returns the exit
code the child process passed to @code{exit(2)}, or the return value
of @code{main()}.
@c JP
[POSIX]
引数は@code{sys-wait}か@code{sys-waitpid}の2番目の値として返される
終了ステータスです。子プロセスが正常終了したら、@code{sys-wait-exited?}は
@code{#t}を返します。@code{sys-wait-exit-status}は、子プロセスが
@code{exit(2)}に渡した終了コードか、@code{main()}の戻り値を返します。
@c COMMON
@end defun

@defun sys-wait-signaled? status
@defunx sys-wait-termsig status
@c EN
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-wait} or @code{sys-waitpid}.
@code{sys-wait-signaled?} returns @code{#t} if the child process
is terminated by an uncaught signal.
@code{sys-wait-termsig} returns the signal number that terminated the child.
@c JP
[POSIX]
引数は、@code{sys-wait}か@code{sys-waitpid}の2つ目の戻り値である終了ステータスです。
子プロセスが捕捉されないシグナルで終了した場合は、@code{sys-wait-signaled?}は
@code{#t}を返します。
@code{sys-wait-termsig}は、子プロセスを終了したシグナルの番号を返します。
@c COMMON
@end defun

@defun sys-wait-stopped? status
@defunx sys-wait-stopsig status
@c EN
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-waitpid}.
@code{sys-wait-stopped?} returns @code{#t} if the child process is
stopped.   This status can be caught only by @code{sys-waitpid} with
true @var{untraced} argument.  @code{sys-wait-stopsig} returns the
signum number that stopped the child.
@c JP
[POSIX]
引数は、@code{sys-waitpid}の2つ目の戻り値である終了ステータスです。
子プロセスが停止されれば、@code{sys-wait-stopped?}は@code{#t}を
返します。このステータスは、@code{sys-waitpid}が@var{untraced}引数に
真値を持っている場合にのみ捕捉されます。@code{sys-wait-stopsig}は
子プロセスを停止させたシグナルの番号を返します。
@c COMMON
@end defun

@c EN
On Windows native platforms, exit code is not structured as on Unix.
You cannot distinguish a process being exited voluntarily or
by forced termination.  Gauche uses exit code @code{#xff09} to
terminate other process with @code{sys-kill},
and the above @code{sys-wait-*} procedures are adjusted accordingly,
so that @code{sys-wait-signaled?} can likely to be used to check
whether if the child process is terminated by Gauche.
(@xref{Signal}, for the details of signal support on Windows.)
@code{Sys-wait-stopped?} never returns true
on Windows native platforms (yet).
@c JP
Windowsネイティブ環境では、終了コードはUnixのように構造化されておらず、
プロセスが自発的に終了したか強制的に終了させられたかを判断する一般的な方法は
ありません。Gauche自身は他のプロセスを@code{sys-kill}で
終了させる場合に終了コード@code{#xff09}を送り、上の@code{sys-wait-*}
手続きもそれに合わせてあります。従ってGaucheによって終了させられたプロセスでは
@code{sys-wait-signaled?}でそのことを検出できる可能性が高いでしょう。
(Windows上のシグナルのサポートについては@ref{Signal}を参照してください。)
Windowsネイティブ環境では、@code{sys-wait-stopped?}が真を返すことは
(今のところ)ありません。
@c COMMON

@c EN
@subsubheading Windows specific utilities
@c JP
@subsubheading Windows特有のユーティリティ
@c COMMON

@c EN
The following procedures are to access Windows process handle.
They are only available on Windows native platforms.
@c JP
以下の手続きはWindowsのプロセスハンドルにアクセスするものです。
Windowsネイティブ環境でのみ提供されます。
@c COMMON

@defun sys-win-process? obj
[Windows]
@c EN
Returns @code{#t} iff @var{obj} is a Windows process handle object.
@c JP
@var{obj}がWindowsプロセスハンドルの場合に@code{#t}を、それ以外では@code{#f}を
返します。
@c COMMON
@end defun

@defun sys-win-process-pid handle
[Windows]
@c EN
Returns an integer PID of the process represented by
a Windows process handle @var{handle}.  An error is signaled
if @var{handle} is not a valid Windows process handle.

Note that the API to get a pid from a process handle is only
provided on or after Windows XP SP1.  If you call this
procedure on Windows version before that, @code{-1} will be
returned.
@c JP
Windowsプロセスハンドル@var{handle}が示すプロセスの、整数のpid値を
返します。@var{handle}が有効なWindowsプロセスハンドルでない場合はエラーが
通知されっす。

プロセスハンドルからプロセスIDを得るAPIはWindows XP SP1から提供されるように
なりました。それ以前のWindowsでこの手続きを呼ぶと@code{-1}が返されます。
@c COMMON
@end defun


@node I/O multiplexing, Garbage collection, Process management, System interface
@subsection I/O multiplexing
@c NODE I/Oの多重化

@c EN
The interface functions for @code{select(2)}.
The higher level interface is provided on top of these
primitives; see @ref{Simple dispatcher}.
@c JP
@code{select(2)}へのインターフェース関数です。
これらのプリミティブの上に構築された高次元のインターフェースが
提供されています。@ref{Simple dispatcher}を
参照して下さい。
@c COMMON

@deftp {Builtin Class} <sys-fdset>
@clindex sys-fdset
@c EN
Represents @code{fd_set}, a set of file descriptors.  You can make
an empty file descriptor set by make method:
@c JP
ファイルディスクリプタの集合である@code{fd_set}を表します。
makeメソッドによって、空のファイルディスクリプタの集合を作れます。
@c COMMON
@example
(make <sys-fdset>)
@end example
@end deftp

@defun sys-fdset elt @dots{}
@c EN
Creates a new @code{<sys-fdset>} instance with file descriptors
specified by @var{elt} @dots{}.  Each @var{elt} can be an
integer file descriptor, a port, or a @code{<sys-fdset>} instance.
In the last case, the descriptors in the given fdset is copied
to the new fdset.
@c JP
@var{elt} @dots{}で指定されたファイルディスクリプタを持つ
新たな@code{<sys-fdset>}のインスタンスを作成して返します。
各@var{elt}は、ファイルディスクリプタを指定する整数、ポート、
もしくは@code{<sys-fdset>}のインスタンスでなければなりません。
最後の場合は、与えられたfdsetに含まれるディスクリプタが
新たなfdsetにコピーされます。
@c COMMON
@end defun

@defun sys-fdset-ref fdset port-or-fd
@defunx sys-fdset-set! fdset port-or-fd flag
@c EN
Gets and sets specific file descriptor bit of @var{fdset}.
@var{port-or-fd} may be a port or an integer file descriptor.
If @var{port-or-fd} is a port that doesn't have associated file descriptor,
@code{sys-fdset-ref} returns @code{#f}, and @code{sys-fdset-set!} doesn't
modify @var{fdset}.  @var{flag} must be a boolean value.
@c JP
@var{fdset}の特定のファイルディスクリプタビットを取得・セットできます。
@var{port-or-fd}は関連付けられたファイルディスクリプタを持っていないポートで、
@code{sys-fdset-ref}は@code{#f}を返し、@code{sys-fdset-set!}は@var{fdset}を
変更しません。@var{flag}は真偽値でなければなりません。
@c COMMON

@c EN
You can use generic setter of @code{sys-fdset-ref} as this:
@c JP
下記のように、@code{sys-fdset-ref}のジェネリックなセッタが使えます。
@c COMMON
@example
(set! (sys-fdset-ref fdset port-or-fd) flag)
  @equiv{} (sys-fdset-set! fdset port-or-fd flag)
@end example
@end defun

@defun sys-fdset-copy! dest-fdset src-fdset
@c EN
Copies the content of @var{src-fdset} into @var{dest-fdset}.
Returns @var{dest-fdset}.
@c JP
@var{src-fdset}の内容を@var{dest-fdset}にコピーします。
@var{dest-fdset}を返します。
@c COMMON
@end defun

@defun sys-fdset-clear! fdset
@c EN
Empties and returns @var{fdset}.
@c JP
@var{fdset}の内容をクリアし、それ自身を返します。
@c COMMON
@end defun

@defun sys-fdset->list fdset
@defunx list->sys-fdset fds
@c EN
Converts an fdset to a list of integer file descriptors and vice versa.
In fact, @code{list->sys-fdset} works just like
@code{(lambda (fds) (apply sys-fdset fds))}, so it accepts ports
and other fdsets as well as integer file descriptors.
@c JP
fdsetを整数のファイルディスクリプタのリストに変換し、またその逆を行います。
実際は、@code{list->sys-fdset}は
@code{(lambda (fds) (apply sys-fdset fds))} のように動作するため、
整数のファイルディスクリプタ以外にポートや他のfdsetを与えることもできます。
@c COMMON
@end defun

@defun sys-fdset-max-fd fdset
@c EN
Returns the maximum file descriptor number in @var{fdset}.
@c JP
@var{fdset}にある最大のファイルディスクリプタ番号を返します。
@c COMMON
@end defun

@defun sys-select readfds writefds exceptfds :optional timeout
@defunx sys-select! readfds writefds exceptfds :optional timeout
@c EN
Waits for a set of file descriptors to change status.
@var{readfds}, @var{writefds}, and @var{exceptfds} are @code{<fdset>}
objects to represent a set of file descriptors to watch.
File descriptors in @var{readfds} are watched to see if characters
are ready to be read.   File descriptors in @var{writefds} are
watched if writing to them is ok.  File descriptors in @var{exceptfds}
are watched for exceptions.  You can pass @code{#f} to one or more
of those arguments if you don't care about watching the condition.
@c JP
ステータスを変更するためにファイルディスクリプタの集合を待ちます。
@var{readfds}、@var{writefds}、@var{exceptfds}は、注目するファイル
ディスクリプタの集合を表す@code{<fdset>}オブジェクトです。
@var{readfds}にあるファイルディスクリプタは、文字を読み込む準備が
出来たかどうかを検査するために監視されています。
@var{writefds}にあるファイルディスクリプタはそこへ書き込むことができる
ようになったか監視されています。@var{exceptfds}にあるファイルディスクリプタは
例外のために監視されています。条件を監視する必要がない場合は、これらの引数の
1つ以上に@code{#f}を渡すことができます。
@c COMMON

@c EN
@var{timeout} specifies maximum time @code{sys-select} waits for
the condition change.  It can be a real number, for number of microseconds,
or a list of two integers, the first is the number of seconds and
the second is the number of microseconds.  If you pass @code{#f},
@code{sys-select} waits indefinitely.
@c JP
@var{timeout}は@code{sys-select}が条件の変更を待つ最大の時間を指定します。
それは、マイクロ秒を表す実数か、1つ目が秒数で2つ目がマイクロ秒である
2つの整数からなるリストです。@code{#f}を渡すと、@code{sys-select}は
永久に待ちます。
@c COMMON

@c EN
@code{sys-select} returns four values.  The first value is a number
of descriptors it detected status change.  It may be zero if
timeout expired.  The second, third and fourth values are @code{<fdset>}
object that contains a set of descriptors that changed status
for reading, writing, and exception, respectively.
If you passed @code{#f} to one or more of @var{readfds},
@var{writefds} and @var{exceptfds}, the corresponding return value
is @code{#f}.
@c JP
@code{sys-select}は4つの値を返します。1つ目の値は、ステータスの変更を
検知したディスクリプタの数です。timeoutが経過したら0になるでしょう。
2、3、4番目の値は、それぞれ読み込み、書き出し、例外のステータスを変更
するディスクリプタの集合を含む@code{<fdset>}オブジェクトです。
@var{readfds}、@var{writefds}、@var{exceptfds}のうちの1つ以上に@code{#f}を
渡すと、対応する戻り値は@code{#f}になります。
@c COMMON

@c EN
@code{sys-select!} variant works the same as @code{sys-select}, except
it modifies the passed @code{<fdset>} arguments.
@code{sys-select} creates new @code{<fdset>} objects and
doesn't modify its arguments.
@c JP
@code{sys-select!}の仲間は、それが渡された引数@code{<fdset>}を変更することを
除けば、@code{sys-select}と同じように動作します。
@code{sys-select}は、新しい@code{<fdset>}オブジェクトを作り、その
引数を変更しません。
@c COMMON
@end defun


@node Garbage collection, Memory mapping, I/O multiplexing, System interface
@subsection Garbage collection
@c NODE ガベージコレクション

@c EN
The garbage collector runs implicitly whenever it is necessary,
and you don't usually need to worry about it.  However, in case
if you do need to worry, here are a few procedures you can use.
@c JP
ガベージコレクタは必要になった時に自動的に走るので、普段気にする必要はないでしょう。
けれどももし気にする必要が出てきた時は、いくつか使える手続きがあります。
@c COMMON

@defun gc
@c EN
Trigger a full GC.  It may be useful if you want to reduce
interference of GC in certain parts of code by calling this
immediately before that.
@c JP
フルGCを起動します。GCの影響をなるべく排除したいコードがある場合、
その直前にこの手続きを呼ぶことで影響を減らせるかもしれません。
@c COMMON
@end defun

@defun gc-stat
@c EN
Returns a list of lists, each inner list contains a keyword and
related statistics number (integer).
@c JP
GCに関する統計情報を返します。返り値はリストのリストで、
内側のリストはキーワードと対応する統計の整数値からなります。
@c COMMON

@example
(gc-stat)
 @result{}
    ((:total-heap-size 7925760) (:free-bytes 524288) (:bytes-since-gc 473792)
     (:total-bytes 9925872) (:unmapped-bytes 0) (:heap-size-full 7925760)
     (:free-bytes-full 524288) (:allocated-bytes-before-gc 9452080)
     (:non-gc-bytes 0) (:gc-cycle 4) (:num-markers 15)
     (:bytes-reclaimed-since-gc 947824) (:reclaimed-bytes-before-gc 1615840)
     (:explicitly-freed-bytes-since-gc 0) (:obtained-from-os-bytes 9302016))
@end example

@c EN
The meaning of each keyword is as follows.  The list of available keywords
may change depending on GC version.
(The descriptions about @code{GC_*()} calls and @code{GC_prof_stats_s}
are for those who know Boehm GC.)
@c JP
それぞれのキーワードの意味は次のとおりです。
なお、返されるキーワードはGCのバージョンによって変わる可能性があります。
@c COMMON

@table @code
@item :total-heap-size
@c EN
Heap size in bytes, not including the area unmapped to OS.
(The value @code{GC_get_heap_size()} returns.)
@c JP
OSがマップしていない領域を除く、GCが使っているヒープ領域のサイズ
(@code{GC_get_heap_size()}の戻り値)。
@c COMMON
@item :heap-size-full
@c EN
Heap size in bytes, including the area unmapped to OS.
(The value of @code{heapsize_full} field of @code{GC_prof_stats_s}.)
@c JP
OSがマップしていない領域を含めた、GCが使っているヒープ領域のサイズ
(@code{GC_prof_stats_s}の@code{heapsize_full}フィールドの値)。
@c COMMON
@item :free-bytes
@c EN
Total bytes contained in free blocks.
(The value @code{GC_get_free_bytes()} returns.)
@c JP
フリーブロックの総バイト数
(@code{GC_get_free_bytes()}の戻り値)。
@c COMMON
@item :free-bytes-full
@c EN
Total bytes contained in free and unmapped blocks.
(The value of @code{free_bytes_full} field of @code{GC_prof_stat_s}.)
@c JP
フリーブロックとマップされていないブロックの総バイト数
(@code{GC_prof_stat_s}の@code{free_bytes_full}フィールドの値)。
@c COMMON
@item :unmapped-bytes
@c EN
Amount of memory unmapped to OS.
(The value @code{GC_get_unmapped_bytes()} returns.)
@c JP
OSにマップされていないメモリの量
(@code{GC_get_unmapped_bytes()}の戻り値)。
@c COMMON
@item :bytes-since-gc
@c EN
Number of bytes allocated since the recent collection.
(The value @code{GC_get_bytes_since_gc()} returns).
@c JP
最後のGC以降にアロケートされたバイト数
(@code{GC_get_bytes_since_gc()}の戻り値)。
@c COMMON
@item :allocated-bytes-before-gc
@c EN
Number of bytes allocated before the recent collection.
This value may wrap if the process has allocated so many bytes.
(The value of @code{allocd_bytes_before_gc} field of @code{GC_prof_stat_s}.)
@c JP
最後のGCまでにアロケートされた延べバイト数。
メモリを大量にアロケートするプロセスではこの値はラップアラウンドするかもしれません。
(@code{GC_prof_stat_s}の@code{allocd_bytes_before_gc}フィールドの値。)
@c COMMON
@item :non-gc-bytes
@c EN
Number of bytes not considered for collection.
(The value of @code{non_gc_bytes} field of @code{GC_prof_stat_s}.)
@c JP
GCの対象にならない領域のバイト数
(@code{GC_prof_stat_s}の@code{non_gc_bytes}フィールドの値)。
@c COMMON
@item :gc-cycle
@c EN
Garbage collection cycle number.  The value may wrap.
(The value of @code{gc_no} field of @code{GC_prof_stat_s}.)
@c JP
これまでのGCの回数。この値はラップアラウンドするかもしれません
(@code{GC_prof_stat_s}の@code{gc_no}フィールドの値)。
@c COMMON
@item :num-markers
@c EN
Number of marker threads, excluding the initiating one.
(The value of @code{markers_m1} field of @code{GC_prof_stat_s}.)
@c JP
最初のマーカースレッドを除く、マーカースレッドの数
(@code{GC_prof_stat_s}の@code{markers_m1}フィールドの値)。
@c COMMON
@item :bytes-reclaimed-since-gc
@c EN
Approx. number of reclaimed bytes after the recent collection.
(The value of @code{bytes_reclaimed_since_gc} field of @code{GC_prof_stat_s}.)
@c JP
最後のGCで回収されたバイト数の概数
(@code{GC_prof_stat_s}の@code{bytes_reclaimed_since_gc}フィールドの値)。
@c COMMON
@item :reclaimed-bytes-before-gc
@c EN
Approx. number of bytes reclaimed before the recent collection.
The value may wrap.
(The value of @code{reclaimed_bytes_before_gc} field of @code{GC_prof_stat_s}.)
@c JP
最後のGCまでに回収されたバイト数の概数。
この値はラップアラウンドするかもしれません
(@code{GC_prof_stat_s}の@code{reclaimed_bytes_before_gc}フィールドの値)。
@c COMMON
@item :explicitly-freed-bytes-since-gc
@c EN
Number of bytes freed explicitly since the recent collection.
(The value of @code{expl_freed_bytes_since_gc} field of @code{GC_prof_stat_s}.)
@c JP
最後のGC以降に明示的に開放されたバイト数
(@code{GC_prof_stat_s}の@code{expl_freed_bytes_since_gc}フィールドの値)。
@c COMMON
@item :obtained-from-os-bytes
@c EN
Total amount of memory obtained from OS in bytes.
(The value of @code{obtained_from_os_bytes} field of @code{GC_prof_stat_s}.)
@c JP
OSから獲得したメモリの総バイト数
(@code{GC_prof_stat_s}の@code{obtained_from_os_bytes}フィールドの値)。
@c COMMON
@end table
@end defun

@node Memory mapping, Miscellaneous system calls, Garbage collection, System interface
@subsection Memory mapping
@c NODE メモリマッピング

@deftp {Class} <memory-region>
@c EN
An object representing a mapped memory pages.  It is returned
from @code{sys-mmap}, and can be passed to @code{make-view-uvector}
to access.  It has the following read-only slots.
@c JP
マップされたメモリ領域を表すオブジェクトです。@code{sys-mmap}によって返され、
@code{make-view-uvector}に渡してアクセスできます。以下の読み取り専用スロットを
持っています。
@c COMMON

@defivar {<memory-region>} address
@c EN
The address of the mapping.  Not useful in the Scheme world, but
you may need to pass this to foreign functions.
@c JP
マッピングされたアドレス。Schemeの世界では意味がありませんが、
外部関数に渡すことはできます。
@c COMMON
@end defivar

@defivar {<memory-region>} size
@c EN
The size of the mapping, in bytes.
@c JP
マッピングの大きさをバイト数で。
@c COMMON
@end defivar

@defivar {<memory-region>} protection
@c EN
The bitmask represents memory protection.  It is a bitwise OR of integer
constants
@code{PROT_READ}, @code{PROT_WRITE}, @code{PROT_EXEC} and @code{PROT_NONE}.
See @code{sys-mmap} below for thedetails.
@c JP
メモリ保護属性のビットマスク。整数定数
@code{PROT_READ}、@code{PROT_WRITE}、@code{PROT_EXEC}、@code{PROT_NONE}
の組み合わせのbitwise orです。詳しくは下の@code{sys-mmap}を参照。
@c COMMON
@end defivar

@defivar {<memory-region>} flags
@c EN
the flags passed to the @code{sys-mmap}.  See @code{sys-mmap} below
for the details.
@c JP
@code{sys-mmap}に渡されたフラグ。下の@code{sys-mmap}を参照。
@c COMMON
@end defivar
@end deftp

@defun sys-mmap port prot flags size :optional offset
[POSIX]
@c EN
Maps files into memory using @code{mmap(2)} (or
@code{MapViewOfFileEx} on Windows).  Returns
a @code{<memory-region>} object, which can be accessed
via @code{make-view-uvector}.
@c JP
@code{mmap(2)} (Windowsでは@code{MapViewOfFileEx}) を使って
ファイルをメモリにマップします。マップされたメモリは
@code{<memory-region>}オブジェクトとして返され、
@code{make-view-uvector}でアクセスできます。
@c COMMON

@c EN
The @var{port} argument must be either a port or @code{#f}.
If it is a port, it must have underlying file.  If it is @code{#f},
the mapping becomes ``anonymous'' (not backed with a file); in that
case, @code{MAP_ANONYMOUS} flag must also be specified in @var{flags}.
@c JP
@var{port}引数はポートか@code{#f}でなければならず、ポートの場合は
ファイルと結びつけられていなければなりません。この引数が@code{#f}の場合は、
ファイルの裏打ちがない「匿名の」メモリ領域がマップされます。この場合、
@var{flags}引数に@code{MAP_ANONYMOUS}が指定されていなければなりません。
@c COMMON

@c EN
The @var{prot} argument specifies the protection bits of the
memory region; it must be an integer created by bitwise-OR
of the following constants:
@c JP
@var{port}引数はメモリ領域の保護属性を指定します。以下の定数のbitwise or
でなければなりません。
@c COMMON
@table @code
@item PROT_EXEC
@c EN
The mapped pages may be executed.
@c JP
メモリページに実行可能属性を付加。
@c COMMON
@item PROT_READ
@c EN
The mapped pages may be read.
@c JP
メモリページに読み取り可能属性を付加。
@c COMMON
@item PROT_WRITE
@c EN
The mapped pages may be written.
@c JP
メモリページに書き込み可能属性を付加。
@c COMMON
@item PROT_NONE
@c EN
Pages may not be accessed.
@c JP
ページにはアクセスできない。
@c COMMON
@end table

@c EN
The @var{flags} argument must be an integer created by bitwise-OR
of the following constants:
@c JP
@var{flags}引数は、以下の定数のbitwise orでなければなりません。
@c COMMON
@table @code
@item MAP_SHARED
@c EN
The mapping is shared among processes.  If you update the mapped
pages, other processes mapping the same region can see it, too.
@c JP
マッピングはプロセス間で共有される。マップされたページを変更した場合、
その変更は同じ領域をマップしている他のプロセスからも見える。
@c COMMON
@item MAP_PRIVATE
@c EN
The mapping is private to this process.  If you update the mapped
pages, it stays in the process and is not visible from outside.
@c JP
マッピングはプロセスだけに止まる。マップされたページを変更しても、
それは外からは見えない。
@c COMMON
@item MAP_ANONYMOUS
@c EN
The pages don't have a backing file.
@c JP
マップされたページはファイルに結びつけられない。
@c COMMON
@end table

@c EN
The @var{size} argument must be a positive exact integer, and the
@var{offset} argument must be a non-negative exact integer.  They specify
the region of the file to be mapped; @var{size} bytes starting
from @var{offset} bytes.  The @var{offset} must be a multiple of
the page size.  If @var{offfset} is omitted, 0 is assumed.
If you're mapping non-file-backed memory (when @var{port} is @code{#f}),
@var{offset} is ignored.
@c JP
@var{size}は正の正確な整数、@var{offset}は非負の正確な整数でなければなりません。
それらはファイル中のマップすべき領域を指定します。@var{offset}バイト目から始まる、
@var{size}バイトの領域です。@var{offset}はページサイズの倍数でなければならず、
省略された場合は0となります。マッピングがファイルと結びつけられていない場合
(@var{port}が@code{#f}の場合)、@var{offset}は無視されます。
@c COMMON

@c EN
You don't need to @code{unmap} the mapped pages explicitly; when the created
@code{<memory-region>} object is garbage collected, the memory
is unmapped.
@c JP
マップされたメモリを陽に@code{unmap}する必要はありません。
@code{<memory-region>}オブジェクトがガベージコレクトされる時に、メモリはunmapされます。
@c COMMON
@end defun

@defun make-view-uvector mem class length :optional offset immutable?
@c EN
This procedure creates a uniform vector that works as a ``window''
to the memory region @var{mem}, which must be
a @code{<memory-region>} object.  If the underlying memory content
changes, it is visible through the uvector.  If the memory region is
writeble and you mutate the uvector, it is reflected to the underlying
memory region.
@c JP
この手続きはメモリ領域@var{mem}の「窓」になるユニフォームベクタを作って返します。
@var{mem}は@code{<memory-region>}オブジェクトでなければなりません。
マップされているメモリ領域に変化があれば、uvectorの内容も変化します。
メモリが書き込み可能でマップされていれば、uvectorを変更するとそれが
メモリにも反映されます。
@c COMMON

@c EN
The @var{class} argument must be one of the uniform vector class
(e.g. @code{<u8vector>}), and @var{length} is the length of the
uvector to be created.  The length is the number of elements,
not the number of bytes.  The memory is accessed with the native
endianness.  @var{Length} can be @code{#f}, in that case up to the end of the
memory region is used.
@c JP
@var{class}はユニフォームベクタのクラスでなければなりません (例: @code{<u8vector>})。
@var{length}は作られるユニフォームベクタの長さ(要素数)です。
メモリはネイティブバイトオーダーでアクセスされます。@var{length}は@code{#f}でも良く、
その場合はメモリ領域の最後までが使われます。
@c COMMON

@c EN
The @var{offset} argument specifies the offset from the beginning of
memory region, in number of @emph{bytes}.  It must be a multiple
of the uvector's element size.
@c JP
@var{offset}引数はメモリ領域先頭からのオフセットをバイト数で指定します。
これはユニフォームベクタの要素サイズの倍数でなければなりません。
@c COMMON

@c EN
If the memory region is read-only (i.e. it is mapped without @code{PROT_WRITE}),
the resulting uvector is immutable.  Otherwise, it is mutable by default,
but ynou can give a true value to @var{immutable?} argument to create
an immutable uvector.
@c JP
メモリ領域が読み出し専用であれば(つまり、@code{PROT_WRITE}属性なしでマップされていれば)、
返されるユニフォームベクタは変更不可になります。そうでなければデフォルトで変更可能な
ユニフォームベクタが返されますが、@var{immutable?}引数に真の値を与えることで、
変更不可なユニフォームベクタを得ることもできます。
@c COMMON

@c EN
The memory region isn't garbage collected as long as there're uvectors
that referencing the region.
@c JP
メモリ領域は、それを参照しているユニフォームベクタが生きている限りは
ガベージコレクトされません。
@c COMMON
@end defun


@node Miscellaneous system calls,  , Memory mapping, System interface
@subsection Miscellaneous system calls
@c NODE その他のシステムコール

@defun sys-pause
@c EN
[POSIX]
Suspends the process until it receives a signal whose
action is to either execute a signal-catching function or to terminate
the process.  This function only returns when the signal-catching
function returns.  The returned value is undefined.
@c JP
[POSIX]
シグナルキャッチ関数の実行かプロセスの終了を指示するシグナルを
受け取るまでプロセスを一時停止します。この関数は、シグナルキャッチ関数が
戻ったときにのみ戻ります。戻り値は未定義です。
@c COMMON

@c EN
Note that just calling @code{pause()} doesn't suffice the above semantics
in Scheme-level.  Internally this procedure calls @code{sigsuspend()}
with the current signal mask.
@c JP
Schemeレベルでは、@code{pause()}を呼ぶだけでは上記のセマンティクスを
満足しません。内部的にこの手続きは現在のシグナルマスクを伴って、
@code{sigsuspend()}を呼びます。
@c COMMON
@end defun

@defun sys-alarm seconds
@c EN
[POSIX] Arranges a SIGALRM signal to be delivered after @var{seconds}.
The previous settings of the alarm clock is canceled.  Passing zero
to @var{seconds} doesn't schedule new alarm.
Returns the number of seconds remaining until previously scheduled
alarm was due to be delivered (or zero if no alarm is active).
@c JP
[POSIX] SIGALRMシグナルが@var{seconds}秒後に送出されるように準備します。
以前のアラームクロックのセッティングはキャンセルされます。
@var{seconds}に0を渡すと、新しいアラームをスケジューリングしません。
以前にスケジューリングされていたアラームが送出されるまでの残り時間を
秒数で返します(アラームがアクティブでない場合は0を返します)。
@c COMMON
@end defun

@defun sys-sleep seconds :optional (no-retry #f)
[POSIX]
@c EN
Suspends the calling thread until the specified number of seconds elapses.

Note that libc's @code{sleep(3)} could return before the specified interval
if the calling thread receives a signal; in that case,
@code{sys-sleep} automatically restarts @code{sleep(3)} again with
remaining time interval
(after invoking Scheme signal handlers if there's any) by default.
So you can count on the thread does sleep at least the specified
amount of time.

If you do want @code{sys-sleep} to return prematurely upon receiving
a signal, you can give a true value to an optional argument @var{no-retry}.

The reason that we retries by default is that Gauche's GC may use
signals to synchronize between threads.   If GC is invoked by one thread
While another thread is sleeping on @code{sleep(3)}, it may return
prematurely.  It could happen often if other threads allocate a lot,
which could make @code{sys-sleep} unreliable.

Returns zero if it sleeps well (which is always the case if @var{no-retry}
is false), or the number of unslept seconds if it is woke up by a signal.
@c JP
指定された秒数が経過するまで、呼び出したスレッドを一時停止します。

libcの@code{sleep(3)}は、シグナルを受けると指定時間経過前であっても
戻ってきます。その場合@code{sys-sleep}はデフォルトで、(Schemeのシグナルハンドラが
あればそれを呼び出した後)残り時間を引数にして再び@code{sleep(3)}を呼び出します。
従って@code{sys-sleep}を呼び出したスレッドは、少なくとも指定した時間、
眠れることが保証されます。

もし@code{sys-sleep}がシグナルを受けた場合にすぐ戻ってきてほしければ、
省略可能引数@code{no-retry}に真の値を渡してください。

デフォルトで@code{sleep(3)}を再呼び出しする理由は、GaucheのGCが
スレッド間同期にシグナルを使う場合があるからです。
もし一つのスレッドが@code{sys-sleep}で待っている間にもうひとつのスレッドが
GCをトリガすると、@code{sys-sleep}が時間経過前に戻ってくる可能性があります。
他のスレッドがたくさんアロケートする場合、@code{sys-sleep}はすぐに
戻ってきてしまい、信頼できなくなるかもしれません。

指定時間が満了した場合(@var{no-retry}が偽であれば常にそうです)、
@code{sys-sleep}は0を返し、
シグナルによって一時停止が解除された場合は、満了までの秒数を返します。
@c COMMON

@c EN
To be portable across POSIX implementation, keep @var{seconds} less than
65536.
@c JP
POSIX実装間でポータブルにするためには、@var{seconds}を65536より小さく保って
下さい。
@c COMMON

@c EN
Some systems may be using @code{alarm(2)} to implement @code{sleep(3)},
so you shouldn't mix @code{sys-sleep} and @code{sys-alarm}.
@c JP
システムによっては@code{sleep(3)}の実装に@code{alarm(2)}を用いている可能性があるので、
@code{sys-sleep}と@code{sys-alarm}を混ぜて使うことはおすすめしません。
@c COMMON
@end defun

@defun sys-nanosleep nanoseconds :optional (no-retry #f)
[POSIX]
@c EN
Suspends the calling thread until the specified number of nanoseconds elapses.
The argument @var{nanoseconds} can be
a @code{<time>} object (@pxref{Time}), or a real number.

The system's @code{nanosleep(2)} could return before the specified interval
if the calling thread receives a signal; in that case,
@code{sys-nanosleep} automatically restarts @code{nanosleep(2)} again with
remaining time interval
(after invoking Scheme signal handlers if there's any) by default.
So you can count on the thread does sleep at least the specified
amount of time.

The reason that we retries by default is that Gauche's GC may use
signals to synchronize between threads.   If GC is invoked by one thread
while another thread is sleeping on @code{nanosleep(2)}, it may return
prematurely.  It could happen often if other threads allocate a lot,
which could make @code{sys-nanosleep} unreliable.

Returns @code{#f} if @var{nanoseconds} elapsed (which is always
the case if @code{no-retry} is @code{#f}),
or a @code{<time>}
object that indicates the remaining time if @code{sys-nanosleep}
is interrupted by a signal.
@c JP
指定されたナノ秒が経過するまで、呼び出したスレッドを一時停止します。
引数@var{nanoseconds}は@code{<time>}オブジェクト(@ref{Time}参照)か
実数です。

システムの@code{nanosleep(2)}は、シグナルを受けると指定時間経過前であっても
戻ってきますが、@code{sys-nanosleep}はデフォルトで、(Schemeのシグナルハンドラが
あればそれを呼び出した後)残り時間を引数にして再び@code{nanosleep(2)}を呼び出します。
従って@code{sys-nanosleep}を呼び出したスレッドは、少なくとも指定した時間、
眠れることが保証されます。

もし@code{sys-nanosleep}がシグナルを受けた場合にすぐ戻ってきてほしければ、
省略可能引数@code{no-retry}に真の値を渡してください。

デフォルトで@code{nanosleep(2)}を再呼び出しする理由は、GaucheのGCが
スレッド間同期にシグナルを使う場合があるからです。
もし一つのスレッドが@code{sys-nanosleep}で待っている間にもうひとつのスレッドが
GCをトリガすると、@code{sys-nanosleep}が時間経過前に戻ってくる可能性があります。
他のスレッドがたくさんアロケートする場合、@code{sys-nanosleep}はすぐに
戻ってきてしまい、信頼できなくなるかもしれません。

@var{nanoseconds}が経過した場合の返り値は@code{#f}です。
@code{no-retry}が偽であれば常にそうなります。
@code{sys-nanosleep}がシグナルによって割り込まれた場合は、
残りの時間を表す@code{<time>}オブジェクトを返します。
@c COMMON

@example
;@r{wait for 0.5 sec}
(sys-nanosleep 500000000)

;@r{wait for 1.3 sec}
(sys-nanosleep (make <time> :second 1 :nanosecond 300000000))
@end example

@c EN
Note: On Windows native platforms, this function is emulated using
@code{Sleep}.  The argument is rounded up to millisecond resolution,
and it won't be interrupted by a signal.
@c JP
Windowsネイティブ環境では、この関数は@code{Sleep}によってエミュレートされます。
引数はミリ秒の単位に切り上げられます。またシグナルによって中断されることはありません。
@c COMMON
@end defun

@defun sys-random
@defunx sys-srandom seed
@c EN
A pseudo random number generator.
@code{sys-random} returns a random number between 0 and a positive
integer @var{rand_max}, inclusive.  This is a straightforward
interface to @code{random(3)}.  If the underlying system doesn't have
@code{random(3)}, @code{lrand48(3)} is used.
@c JP
擬似的な乱数ジェネレータです。
@code{sys-random}は0から@var{rand_max}(それ自体を含む)までの間で乱数を
返します。これは@code{random(3)}への直接的なインターフェースです。
システムに@code{random(3)}がない場合、@code{lrand48(3)}が使われます。
@c COMMON

@c EN
@code{sys-srandom} sets the seed of the random number generator.
It uses either @code{srandom(3)} or @code{srand48(3)}, depending on
the system.
@c JP
@code{sys-srandom}は乱数ジェネレータの種をセットします。
システムによって、@code{srandom(3)}か@code{srand48(3)}を使います。
@c COMMON

@c EN
The intention of these functions are to provide an off-the-stock handy
random number generator (RNG) for applications that doesn't
sensitive to the quality and/or speed of RNG.  For serious statistics
analysis, use Mersenne Twister RNG in @code{math.mt-random}
module (@pxref{Mersenne-Twister random number generator}).
@c JP
これらの関数の意図は、乱数ジェネレータ(RNG; random number generator)の
品質や速度を気にしないアプリケーションに、簡便なRNGを提供することです。
本格的な統計分析には、@code{math.mt-random}モジュールのMersenne Twister RNGを
使って下さい(@ref{Mersenne-Twister random number generator}参照)。
@c COMMON
@end defun

@defvar RAND_MAX
@c EN
Bound to a positive integer that @code{sys-random} may return.
@c JP
@code{sys-random}が返す正の整数に束縛されます。
@c COMMON
@end defvar

@defun sys-get-osfhandle port-or-fd
[Windows]
@c EN
This procedure is only available on Windows native platforms.
Returns a Windows file handle associated to the given port or
integer file descriptor.   Throws an error if the given argument
does not have associated file handle.
@c JP
この手続きはWindowsネイティブ版だけにあります。
与えられたポートまたは整数のファイルディスクリプタに対応する
Windowsファイルハンドルを返します。引数がファイルハンドルに
対応していなかった場合はエラーが投げられます。
@c COMMON
@end defun


@c ----------------------------------------------------------------------
@node Development helper API,  , System interface, Core library
@section Development helper API
@c NODE 開発補助API

@c EN
Gauche has some basic built-in APIs to help developers
to analyze the program.
@c JP
Gauche には開発者がプログラムを解析するための基本的な組込みAPIがあります。
@c COMMON

@menu
* Debugging aid::
* Profiler API::
@end menu

@node Debugging aid, Profiler API, Development helper API, Development helper API
@subsection Debugging aid
@c NODE デバッグ補助

@defmac debug-print expr
@c EN
This macro prints @var{expr} in a source form, then evaluates it,
then prints out the result(s), and returns them.
@c JP
このマクロは@var{expr}をそのフォームのまま印字してから、その式を評価し、
評価の結果を印字し、その値を返します。
@c COMMON

@c EN
The output goes to the current trace port
(@pxref{Common port operations}).
@c JP
出力は現在のトレース出力ポート (@code{current-trace-port})
に行きます (@ref{Common port operations}参照)。
@c COMMON

@c EN
The special reader syntax @code{#?=@var{expr}} is expanded into
@code{(debug-print @var{expr})}.  See @ref{Debugging}, for the
details.
@c JP
特殊リーダー構文 @code{#?=@var{expr}} は
@code{(debug-print @var{expr})} に展開されます。
詳細については @ref{Debugging} を参照してください。
@c COMMON
@end defmac

@deffn {Parameter} debug-print-width
@c EN
This parameter specifies the maximum width of information to be
printed by @code{debug-print}.  If the information takes more
columns than the value of this parameter, it is truncated.
@c JP
このパラメータは@code{debug-print}が印字する情報の最大幅を指定するもの
です。このパラメータが保持する値よりも大きいカラム数の情報は丸められま
す。
@c COMMON

@c EN
To show all the information, set @code{#f} to this parameter.
@c JP
すべての情報を表示したければ、このパラメータに@code{#f}を設定してくだ
さい。
@c COMMON
@end deffn

@defmac debug-funcall (proc arg @dots{})
@c EN
This macro prints the value of @var{arg}s right before calling
@var{proc} and the result(s) of the call afterwards.
@c JP
このマクロは@var{proc}を呼び出す直前に全ての@var{arg}の値を表示し、
そして@var{proc}の呼び出し後に全ての戻り値を表示します。
@c COMMON

@c EN
The output goes to the current trace port
(@pxref{Common port operations}).
@c JP
出力は現在のトレース出力ポート (@code{current-trace-port})
に行きます (@ref{Common port operations}参照)。
@c COMMON

@c EN
The special reader syntax @code{#?,@var{expr}} is expanded into
@code{(debug-funcall @var{expr})}.  See @ref{Debugging}, for the
details.
@c JP
特別なリーダ構文 @code{#?,@var{expr}} は @code{(debug-funcall @var{expr})}
に展開されます。詳しくは @ref{Debugging} を参照してください。
@c COMMON
@end defmac

@defmac debug-print-conditionally test expr
@defmacx debug-funcall-conditionally test (proc arg @dots{})
@c EN
Works like @code{debug-print} and @code{debug-funcall}, but
prints out the debug info ony when @var{test} evaluates to true.

These are functionally equivalent to the following code:
@c JP
@code{debug-print}および@code{debug-funcall}のように動作しますが、
@var{test}が真の値に評価された時のみデバッグ出力を表示します。

これらは次のコードと機能的には同じです。
@c COMMON

@example
(if test
  (debug-print expr)
  expr)

(if test
  (debug-funcall (proc arg @dots{}))
  (proc arg @dots{}))
@end example

@c EN
The special reader syntax @code{#??=@var{test} @var{expr}} and
@code{#??,@var{test} @var{expr}} are expanded into
@code{(debug-print-conditionally @var{test} @var{expr})} and
@code{(debug-funcall-conditionally @var{test} @var{expr})}, respectively.
See @ref{Debugging}, for the details.
@c JP
特別なリーダ構文 @code{#??=@var{test} @var{expr}} および
@code{#??,@var{test} @var{expr}} はそれぞれ
@code{(debug-print-conditionally @var{test} @var{expr})} と
@code{(debug-funcall-conditionally @var{test} @var{expr})} に展開されます。
詳しくは @ref{Debugging} を参照してください。
@c COMMON
@end defmac

@defun debug-source-info obj
@c EN
Retrieves source information attached to @var{obj}.
The source information is returned as a list of source file name
and an integer line number.  If no source information is available
in @var{obj}, @code{#f} is returned.
@c JP
@var{obj}に付加されているソースコード情報を検索します。ソースコード情
報とはソースコードファイル名と行番号のリストです。@var{obj}にソースコー
ド情報が付加されていなければ、@code{#f}が返されます。
@c COMMON
@end defun

@defun source-code closure
@c EN
Returns the source code of @var{closure}, if available.
Otherwise, @code{#f} is returned.

Currently, only the code that's directly read from Scheme source
is available; if the Scheme code is precompiled, the source code
isn't saved.   It may be changed in future.
@c JP
@var{closure}のソースコードが取り出せればそれを返します。そうでなければ
@code{#f}を返します。

現在、Schemeソースから直接読み込まれた場合のみ、ソースコードが取り出せます。
プリコンパイルされたSchemeコードではソースコードは保存されません。
将来は変更されるかもしれません。
@c COMMON
@end defun

@defun source-location procedure
@c EN
Returns the location (a list of filename and line number) where @var{procedure}
is defined, if available.  Otherwise, @code{#f} is returned.
@c JP
@var{procedure}が定義された場所(ファイル名と行番号)がわかればそれをリストにして
返します。わからなければ@code{#f}が返ります。
@c COMMON

@example
gosh> (use rfc.http)
gosh> (source-location http-get)
("/usr/share/gauche-0.9/0.9.5/lib/rfc/http.scm" 443)
@end example

@c EN
If @var{procedure} is a subr or a precompiled closure, the filename
may not be a complete pathname.
@c JP
@var{procedure}がsubrやプリコンパイルされた手続きの場合、
ファイル名は完全なパスではないかもしれません。
@c COMMON

@example
gosh> (source-location cons)
("liblist.scm" 46)
@end example
@end defun

@defun disasm closure
@c EN
Disassemble the compiled body of @var{closure} and print it.
It may not be very useful unless you're tracking a compiler bug,
or trying to tune the program to its limit.
@c JP
コンパイル済の@var{closure}の本体部分をディスアセンブルして印字します。
これはコンパイラのバグをなんとかしようという場合か、限界まで
チューンしようとしないかぎりは役には立たないでしょう。
@c COMMON

@c EN
If you're reading the disassembler output, keep in mind that
the compiled code vector may have some dead code; they are produced
by the jump optimization, but the compiler doesn't bother to eliminate
them.
@c JP
このディスアセンブラの出力結果を読む場合には、コンパイルされたコードに
はデッドコードが含まれている可能性があることを心してください。デッドコー
ドはジャンプ最適化によって生成されるのですが、コンパイラはこれをわざわ
ざ除去することはしていません。
@c COMMON
@end defun

@defun debug-label obj
@c EN
This returns a string that is quasi-unique to an object @var{obj}.
``Quasi-unique'' means the label is unique to the @var{obj}---
the same (@code{eq?}) objs returns the same string, and
if two objs return different string they aren't @code{eq?} to each other---
@emph{until next GC occurs}.

This is mostly for printing out anonymous objects that doesn't
have any other good way to distinguish each other.
Note that uniqueness isn't guaranteed
across GCs, you shouldn't use the returned value as the key to identify
the objects.
@c JP
この手続きは、@var{obj}についてほぼユニークな文字列を返します。
「ほぼ」ユニークというのは、
@emph{次のGCが起きるまでは}、オブジェクトが同じ文字列を返したら@code{eq?}であり、
また@code{eq?}でないオブジェクト同士は異なる文字列を返すということです。

この文字列は、他に区別の手段がないような無名オブジェクトを印字する時に
使われることを想定しています。GCをまたいだ唯一性は保証されないので、
この手続きが返す文字列をオブジェクトを同定するキーとして使ってはいけません。
@c COMMON
@end defun


@node Profiler API,  , Debugging aid, Development helper API
@subsection Profiler API
@c NODE プロファイラAPI

@c EN
These are the functions to control Gauche's built-in profiler.
See @ref{Using profiler} for the explanation of the profiler.
@c JP
ここに挙げている関数は、Gauche の組込みプロファイラを制御するためのも
のです。プロファイラの説明については @ref{Using profiler} を参照してく
ださい。
@c COMMON

@c EN
Note that the profiler isn't guaranteed to work correctly yet in
multi-threaded program, since the interaction between @code{setitimer}
and threads are platform-dependent.
@c JP
注意：現時点ではプロファイラはマルチスレッドプログラムでは正しく動作する
保証はありません。@code{setitimer}とスレッドの相互作用が
プラットフォーム依存だからです。
@c COMMON

@defun profiler-start
@c EN
Starts the sampling profiler.   If the profiler is already started,
nothing is done.
@c JP
標本化プロファイラを始動します。プロファイラが既に始動しいる場合
には何もしません。
@c COMMON
@end defun

@defun profiler-stop
@c EN
Stop the sampling profiler, and save the sampled data into
the internal structure.   If there are already saved sampled data,
the newly obtained data is added to it.
If the profiler isn't running, nothing is done.
@c JP
標本化プロファイラを停止し、標本データを内部データ構
造に保存します。既に標本データが保存されていた場合には、新
しく収集された標本データがその後に追加されます。もしプロファイラが動いてい
なかった場合には何もしません。
@c COMMON
@end defun

@defun profiler-reset
@c EN
Stop the profiler if it is running.  Then discard the
saved sampled data.
@c JP
もしプロファイラが動いていればそれを停止し、保存されていた標本データ
を破棄します。

@c COMMON
@end defun

@defun profiler-show :key sort-by max-rows
@c EN
Show the saved sampled data.
@c JP
格納されている標本データを表示します。
@c COMMON

@c EN
The keyword argument @var{sort-by} may be one of the symbols
@code{time}, @code{count}, or @code{time-per-call}, to specify
how the result should be sorted.  The default is @code{time}.
@c JP
キーワード引数 @var{sort-by} は指定する場合は、@code{time}、
@code{count} または @code{time-per-call} のどれかひとつです。
これで結果の整列順を指定します。デフォルトでは @code{time}です。
@c COMMON

@c EN
The keyword argument @var{max-rows} specifies the max number of
rows to be shown.  If it is @code{#f}, all the data is shown.
@c JP
キーワード引数 @var{max-rows} では結果を表示する最大行数を指定します。
この値が @code{#f} であればすべてのデータが表示されます。
@c COMMON
@end defun

@defun with-profiler thunk
@c EN
A convenience procedure.
Call @var{thunk} with the sampling profiler running,
and show the result to the current output port afterwards.
Returns value(s) thunk yields.
The profiler is reset after the result is shown.

You can't nest this construct; the innermost @code{with-profiler}
will reset the profiler, invalidates any outer @code{with-profiler}.
@c JP
手軽にプロファイリングするための手続きです。
プロファイラをonにして@var{thunk}を呼び出し、結果をcurrent output port
に出力します。@var{thunk}の戻り値が式の戻り値となります。
結果表示後、プロファイラはリセットされます。

この手続きをネストすることはできません。最も内側の@code{with-profiler}が
結果をリセットしてしまうので、外側の@code{with-profiler}に全ての情報が渡らないからです。
@c COMMON
@end defun



@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
