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

@c EN
This chapter lists modules that provides SRFI functionalities.
Note that some of SRFI features are built in Gauche core and
not listed here.  @xref{Standard conformance}, for entire list
of supported SRFIs.
@c JP
この章ではSRFIの機能を提供するモジュールをリストします。
一部のSRFIはGaucheのコアに組み込まれており、
この章には挙げられていないことに注意して下さい。
サポートされている全てのSRFIのリストは@ref{Standard conformance}にあります。
@c COMMON

@c ----------------------------------------------------------------------
@menu
* Feature conditional::         srfi-0
* List library::                srfi-1
* Homogeneous vectors::         srfi-4
* A compatible let form with signatures and rest arguments::  srfi-5
* Feature-based program configuration language::  srfi-7
* Let-values::                  srfi-11
* String library::              srfi-13
* Character-set library::       srfi-14
* Time data types and procedures::  srfi-19
* Sources of random bits::      srfi-27
* Localization::                srfi-29
* A program argument processor::  srfi-37
* Eager comprehensions::        srfi-42
* Vector library::              srfi-43
* Requiring extensions::        srfi-55
* Integers as bits::            srfi-60
* Accessing environment variables::  srfi-98
@end menu

@node Feature conditional, List library, Library modules - SRFIs, Library modules - SRFIs
@section @code{srfi-0} - Feature conditional
@c NODE 機能条件式, @code{srfi-0} - 機能条件式

@deftp {Module} srfi-0
@mdindex srfi-0
@c EN
Provides SRFI-0 @code{cond-expand} macro form.
Now this module is autoloaded when @code{cond-expand} is used,
so you don't need to say @code{(use srfi-0)} explicitly.
Portable programs can't use 'use' form anyway.
@c JP
このモジュールは SRFI-0 の @code{cond-expand} マクロ形式を提供します。
現在、このモジュールは @code{cond-expand} を使用したときに、自動的に
ロードされますので、明示的に @code{(use srfi-0)} を書く必要はありません。
ポータブルなプログラムにするには、'use' 形式を使わない方が良いでしょう。
@c COMMON
@end deftp

@defmac cond-expand (feature-requirement command-or-definition @dots{}) @dots{}
[SRFI-0]
@c EN
This macro expands to @var{command-or-definition} @dots{} if Gauche
supports @var{feature-requirement}.
In a way, it can be used to absorb the different feature sets supported by
different Scheme implementations.

@var{feature-requirement} must be in the following syntax:
@c JP
Gauche が @var{feature-requirement} をサポートしていれば、このマクロは
@var{command-or-definition} @dots{} を展開します。
異るScheme の実装による機能の差異を吸収するのに使えると言えるでしょう。

@var{feature-requiremnt} は以下のような構文でなければなりません。
@c COMMON
@example
@var{feature-requirement}
  : @var{feature-identifier}
  | (and @var{feature-requirement} @dots{})
  | (or  @var{feature-requirement} @dots{})
  | (not @var{feature-requirement})
@end example

@c EN
@var{feature-identifier} is a symbol that indicates a feature.
If such a feature is supported in Gauche, it satisfies the
@var{feature-requirement}.  You can do boolean combination
of @var{feature-requirement}s to compose more complex conditions.

The macro tests each @var{feature-requirement} in order, and
if one is satisfied, the macro itself expands to the
corresponding @var{command-or-definition} @dots{}.

The last clause may begin with a symbol @code{else} instead of
@var{feature-requirement}.  If no condition is fulfilled before
it, then the macro expands to the @var{command-or-definition}s
of the else clause.  If there's no else clause and no condition
is fulfilled, an error is signalled.

Currently, Gauche recognizes srfi names (e.g. @code{srfi-1})
that it supports (@xref{Standard conformance}, for the list of
supported SRFIs), and a symbol @code{gauche} as @var{feature-identifier}.

Suppose you are writing a program that requires srfi-13 (string library).
In Gauche, the standard way to use srfi-13 is like this:
@c JP
@var{feature-identifier} は機能を示すシンボルです。ある機能が Gauche で
サポートされているなら、それは、@var{feature-requirement} を満たします。
より複雑な条件を構成するために、@var{feature-requirement} のブール代数による
組み合わせを用いることが出来ます。

このマクロは @var{feature-requirement} を順にテストし、そのひとつが
満たされたら、対応する @var{command-or-definition} @dots{} に展開されます。

最後の節は、@var{feature-requirement} ではなく、@code{else} で始めることも
できます。これ以前に満たされた条件がない場合には、このマクロは else 節の
@var{command-or-definition} に展開されます。もし、else 節がなく、
満たされる条件節がひとつもなければ、エラーが発生します。

現時点の Gauche では、サポートされている SRFI の機能は、srfi 名
(たとえば、@code{srfi-1})で識別されます(サポートされている SRFI に
ついては @ref{Standard conformance} を参照してください)。
また、シンボル @code{gauche} も @var{feature-identifier} として認識されます。

srfi-13 (文字列ライブラリ)を必要とするプログラムを書いているとしましょう。
Gauche では、標準的には、以下のようにします。
@c COMMON

@example
(use srfi-13)

@c EN
;; ... your program ...
@c JP
;; ... あなたのプログラム ...
@c COMMON
@end example

@c EN
However, the 'use' macro is Gauche specific and won't work
on other Scheme implementations.  You can write instead:
@c JP
しかし、この 'use' マクロは Gauche 専用で、他の Scheme の実装では
動作しません。代りに以下のように書くことができます。
@c COMMON

@example
(cond-expand
  (srfi-13
@c EN
    ;; ... your program ...
@c JP
    ;; ... あなたのプログラム ...
@c COMMON
  ))
@end example

@c EN
If the implementation supports @code{srfi-13}, the form expands
to your program.  Note that Gauche issues @code{(use srfi-13)}
for you in this case.

The above form signals an error if the implementation doesn't support
srfi-13.  However, you might want to run your program on such implementations
as well, by providing alternative library definitions.
@c JP
その実装が @code{srfi-13} をサポートしていれば、この形式は「あなたの
プログラム」に展開されます。Gauche では、この場合に
内部で@code{(use srfi-13)}を呼び出します。

上記のフォームは実装がsrfi-13をサポートしていなければエラーとなります。
そのような実装の上でもプログラムを走らせたい時は、
代替となるライブラリ定義を提供すると良いでしょう。
@c COMMON

@example
(cond-expand
 (srfi-13
@c EN
   ;; ... your program ...
@c JP
   ;; ... あなたのプログラム ...
@c COMMON
 )
 (else
   (load "my-srfi-13-implementation")
@c EN
   ;; ... your program ...
@c JP
   ;; ... あなたのプログラム ...
@c COMMON
 ))
@end example
@end defmac

@c ----------------------------------------------------------------------
@node List library, Homogeneous vectors, Feature conditional, Library modules - SRFIs
@section @code{srfi-1} - List library

@deftp {Module} srfi-1
@mdindex srfi-1
@c EN
SRFI-1 is a rich collection of list manipulation library
(@ref{srfi-1,[SRFI-1],SRFI-1}).
It is available by saying @code{(use srfi-1)}.
The implementation is based on Olin Shivers's reference implementation.
@c JP
SRFI-1 は、リスト操作ライブラリの豊富なコレクションです
(@ref{srfi-1,[SRFI-1],SRFI-1})。
このライブラリを使うには、@code{(use srfi-1)} として下さい。
Olin Shivers氏のリファレンス実装に基づいて実装されています。
@c COMMON
@end deftp

@menu
* SRFI-1 List constructors::    
* SRFI-1 List predicates::      
* SRFI-1 List selectors::       
* SRFI-1 List miscellaneous routines::  
* SRFI-1 Fold::                 
* SRFI-1 Filtering & Partitioning::  
* SRFI-1 Searching::            
* SRFI-1 Deletion::             
* SRFI-1 Association lists::    
* SRFI-1 Set operations::       
@end menu

@node SRFI-1 List constructors, SRFI-1 List predicates, List library, List library
@subsection List constructors
@c NODE SRFI-1 リスト構築子, リストの構築子

@defun xcons cd ca
@c EN
[SRFI-1] Equivalent to @code{(cons ca cd)}.  Useful to pass to
higher-order procedures.
@c JP
[SRFI-1] @code{(cons ca cd)} と同等です。高階手続きへ渡すのに便利です。
@c COMMON
@end defun

@defun cons* elt1 elt2 @dots{}
@c EN
[SRFI-1] Like @code{list}, but the last argument provides the tail of
the constructed list.  This is just a synonym of Gauche built-in procedure
@code{list*}.
@c JP
[SRFI-1] @code{list} と似ていますが、最後の引数が構築されたリストの
末尾になります。Gauche の組み込み手続き @code{list*} と同意です。
@c COMMON
@example
(cons* 1 2 3 4) @result{} (1 2 3 . 4)
(cons* 1) @result{} 1
@end example
@end defun

@defun list-tabulate n init-proc
@c EN
[SRFI-1] Constructs an @var{n}-element list, in which
each element is generated by @code{(@var{init-proc} @i{i})}.
@c JP
[SRFI-1] @var{n}個の要素をもつリストを構築し、それぞれの要素を
@code{(@var{init-proc} @i{i})} で生成します。
@c COMMON
@example
(list-tabulate 4 values) @result{} (0 1 2 3)
@end example
@end defun

@defun circular-list elt1 elt2 @dots{}
@c EN
[SRFI-1] Constructs a circular list of the elements.
@c JP
[SRFI-1] 指定した要素をもつ循環リストを構築します。
@c COMMON
@example
(circular-list 'z 'q) @result{} (z q z q z q @dots{})
@end example
@end defun

@defun iota count :optional (start 0) (step 1)
@c EN
[SRFI-1] Returns a list of numbers, starting from @var{start},
increasing by @var{step}.
@c JP
[SRFI-1] @var{start}から始まり、@var{step}ずつ増加する、
@var{count} 個の要素からなる数値のリストを返します。
@c COMMON
@example
(iota 5) @result{} (0 1 2 3 4)
(iota 5 0 -0.1) @result{} (0 -0.1 -0.2 -0.3 -0.4)
@end example
@end defun

@node SRFI-1 List predicates, SRFI-1 List selectors, SRFI-1 List constructors, List library
@subsection List predicates
@c NODE SRFI-1 リストの述語, リストの述語

@defun proper-list? x
@c EN
[SRFI-1] Returns @code{#t} if x is a proper list.
@c JP
[SRFI-1] @var{x} が真性リストであれば @code{#t} を返します。
@c COMMON
@end defun

@defun circular-list? x
@c EN
[SRFI-1] Returns @code{#t} if x is a circular list.
@c JP
[SRFI-1] @var{x} が循環リストであれば @code{#t} を返します。
@c COMMON
@end defun

@defun dotted-list? x
@c EN
[SRFI-1] 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
[SRFI-1] @var{x} が有限の大きさで、空リストで終端していないリストなら
@code{#t} を返します。これには、ペアではなく、空リストもない値(たとえば
シンボルや数値)のような長さ0のドットリストと考えられるものを含みます。
@c COMMON
@end defun

@defun null-list? list
@c EN
[SRFI-1] Returns @code{#t} if @var{list} is the empty list @code{()},
and @var{#f} otherwise.
@c JP
[SRFI-1] @var{list} が空リスト @code{()} なら @code{#t} を返します。
それ以外のときは @var{#f} を返します。
@c COMMON
@end defun

@defun not-pair? x
@c EN
[SRFI-1] @code{(lambda (x) (not (pair? x)))}.

SRFI-1 says: Provided as a procedure as it can be useful as
the termination condition for list-processing procedures that wish to
handle all finite lists, both proper and dotted. 
@c JP
[SRFI-1] @code{(lambda (x) (not (pair? x)))}と同じです。

SRFI-1 では、「真性リストおよびドットリストの両方で、すべての有限リストを
扱う手続き用の終端条件として便利なように用意した」とあります。
@c COMMON
@end defun

@defun list= elt= list @dots{}
@c EN
[SRFI-1] Determines list equality by comparing every n-th element
of given lists by the procedure @var{elt=}.

It is an error to apply @code{list=} to anything except proper lists.

The equality procedure must be consistent with @code{eq?}, i.e.
@c JP
[SRFI-1] @var{elt=} を用いて、n番目の要素をそれぞれ比較することで、
与えられたリストの同値性を決定します。

@code{list=} を真性リスト以外に適用するとエラーになります。

同値性判定の手続きは @code{eq?} と整合性がなければなりません。すなわち
@c COMMON
@example
(eq? x y) @result{} (elt= x y).
@end example
@end defun

@node SRFI-1 List selectors, SRFI-1 List miscellaneous routines, SRFI-1 List predicates, List library
@subsection List selectors
@c NODE SRFI-1 リスト選択子, リスト選択子

@defun  first pair
@defunx second pair
@defunx third pair
@defunx fourth pair
@defunx fifth pair
@defunx sixth pair
@defunx seventh pair
@defunx eighth pair
@defunx ninth pair
@defunx tenth pair
@c EN
[SRFI-1] Returns n-th element of the (maybe improper) list.
@c JP
[SRFI-1] リスト(非真性でも可)のn番目の要素を返します。
@c COMMON
@end defun

@defun car+cdr pair
@c EN
[SRFI-1] Returns two values, @code{(car pair)} and @code{(cdr pair)}.
@c JP
[SRFI-1] @code{(car pair)} および @code{(cdr pair)} の二つの値を返します。
@c COMMON
@end defun

@defun take x i
@defunx drop x i
@c EN
[SRFI-1] @code{take} returns the first i elements of list x.
@code{drop} returns all but the first i elements of list x. 
@c JP
[SRFI-1]
@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 signalled if @var{i} is past the end of list @var{x}.
@xref{Additional list library}, for more tolerant version
of @code{take} and @code{drop}.

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

@var{i} がリスト @var{x} の終端を超えたらエラーが発生します。
より寛容なバージョンの @code{take} と @code{drop} については、
@xref{Additional list library} を参照してください。

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

@defun take-right flist i
@defunx drop-right flist i
@c EN
[SRFI-1] @code{take-right} returns the last @var{i} elements of @var{flist}.
@code{drop-right} returns all but the last @var{i} elements of @var{flist}. 
@c JP
[SRFI-1] @code{take-right} は @var{flist} の最後の @var{i}個の要素
からなるリストを返します。
@code{drop-right} は @var{flist} の最後の @var{i}個の要素を
除いたリスト返します。
@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{flist} may be any finite list.
@c JP
@var{flist} は有限リストであれば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{flist}.
@code{drop-right} always allocates a new list
if the argument is a list of non-zero length.

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

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

@defun take! x i
@defunx drop-right! x i
@c EN
[SRFI-1]  Linear update variants of @var{take} and @var{drop-right}.
Those procedures may destructively modifies @var{x}.

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

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

@defun split-at x i
@defunx split-at! x i
@c EN
[SRFI-1] @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
[SRFI-1] @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 last pair
@c EN
[SRFI-1] Returns the last element of the non-empty, finite list @var{pair}.
It is equivalent to @code{(car (last-pair pair))}.
Note that @code{last-pair} is Gauche built-in procedure.
@c JP
[SRFI-1] 空ではない有限リスト @var{pair} の最後の要素を返します。
これは、@code{(car (last-pair pair))} と同等です。

註: @code{last-pair} は Gauche の組み込み手続きです。
@c COMMON
@end defun

@node SRFI-1 List miscellaneous routines, SRFI-1 Fold, SRFI-1 List selectors, List library
@subsection List miscellaneous routines
@c NODE 種々のリスト処理ルーチン

@defun length+ x
@c EN
[SRFI-1] If @var{x} is a proper list, returns its length.
Otherwise, returns @code{#f}.
@c JP
[SRFI-1] @var{x} が真性リストなら、その長さを返します。さもなければ、
@code{#f} を返します。
@c COMMON
@end defun

@defun concatenate list-of-lists
@defunx concatenate! list-of-lists!
@c EN
[SRFI-1] Equivalent to @code{(apply append @var{list-of-lists})} and
@code{(apply append! @var{list-of-lists})}, respectively.
@c JP
[SRFI-1] それぞれ、@code{(apply append @var{list-of-lists})} および
@code{(apply append! @var{list-of-lists})} と同等です。
@c COMMON
@end defun

@defun append-reverse rev-head tail
@defunx append-reverse! rev-head tail
@c EN
[SRFI-1] @code{append-reverse} returns @code{(append (reverse rev-head) tail)}.
@code{append-reverse!} is the linear-update variant.
@c JP
[SRFI-1] @code{append-reverse} は @code{(append (reverse rev-head) tail)} を
返します。@code{append-reverse!} はその場で更新されるバージョンです。
@c COMMON
@end defun

@defun zip clist1 clist2 @dots{}
@c EN
[SRFI-1] Equivalent to @code{(map list clist1 clist2 @dots{})}.
If @code{zip} is passed @var{n} lists, it returns a list as long as
the shortest of these lists, each element of which is an @var{n}-element list
comprised of the corresponding elements from the parameter lists. 
@c JP
[SRFI-1] @code{(map list clist1 clist2 @dots{})} と同等です。
@var{n} 本のリストが @code{zip} に渡された場合には、そのなかで一番短いものと
同じ長さのリストを返します。返されたリストは、要素が @var{n} 要素のリストで、
そのそれぞれが、引数として渡ってリストの対応する要素になっています。
@c COMMON
@example
(zip '(one two three) 
     '(1 2 3)
     '(odd even odd even odd even odd even))
     @result{} ((one 1 odd) (two 2 even) (three 3 odd))

(zip '(1 2 3)) @result{} ((1) (2) (3))
@end example
@c EN
At least one of the argument lists must be finite: 
@c JP
引数のリストのうち、少くともひとつは有限のリストでなければなりません。
@c COMMON
@example
(zip '(3 1 4 1) (circular-list #f #t)) 
     @result{} ((3 #f) (1 #t) (4 #f) (1 #t))
@end example
@end defun

@defun unzip1 list
@defunx unzip2 list
@defunx unzip3 list
@defunx unzip4 list
@defunx unzip5 list
@c EN
[SRFI-1] @code{unzip1} takes a list of lists, where every list must
contain at least one element, and returns a list containing the
initial element of each such list.
@code{unzip2} takes a list of lists, where every list
must contain at least two elements, and returns two values:
a list of the first elements, and a list of the second
elements. @code{unzip3} does the same for the first
three elements of the lists, and so on.
@c JP
[SRFI-1] @code{unzip1} はリストのリストを引数としてとります。それぞれの
リストは少くとも一つの要素を含むものでなくてはなりません。結果として
それぞれのリストの最初の要素のリストを返します。
@code{unzip2} はリストのリストを引数としてとります。それぞれのリストは
少くとも二つの要素を含むものでなくてはなりません。結果として二つの値を
返します。最初の要素のリストと二番目の要素のリストです。@code{unzip3} は
3番目までの要素について同様です。以下も同様です。
@c COMMON
@example
(unzip2 '((1 one) (2 two) (3 three))) @result{}
   (1 2 3) @r{and}
   (one two three)
@end example
@end defun

@defun count pred clist1 clist2 @dots{}
@c EN
[SRFI-1] 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
[SRFI-1] @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

@node SRFI-1 Fold, SRFI-1 Filtering & Partitioning, SRFI-1 List miscellaneous routines, List library
@subsection List fold, unfold & map
@c NODE リストの畳み込み(fold)、解きほぐし(unfold)、および写像(map)

@defun fold kons knil clist1 clist2 @dots{}
@c EN
[SRFI-1] 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
[SRFI-1] 基本リスト反復演算子です。単一のリスト
@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{}
@c EN
[SRFI-1] 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
[SRFI-1] 基本リスト再帰演算子です。単一のリスト
@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 pair-fold kons knil clist1 clist2 @dots{}
@defunx pair-fold-right kons knil clist1 clist2 @dots{}
@c EN
[SRFI-1] 
Like @code{fold} and @code{fold-right}, but the procedure @var{kons}
gets each @code{cdr} of the given @var{clist}s, instead of @code{car}.
@c JP
[SRFI-1]
@code{fold} および @code{fold-right} と同様ですが、@var{kons} 手続き
は与えられた @var{clist} の @code{car} ではなく、@code{cdr} をとります。
@c COMMON
@end defun

@defun reduce f ridentity list
@defunx reduce-right f ridentity list
@c EN
[SRFI-1]
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
[SRFI-1]
@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 unfold p f g seed :optional tail-gen
@c EN
[SRFI-1]
Fundamental recursive list constructor.
Defined by the following recursion.
@c JP
[SRFI-1]
基本リスト再帰構築子です。
以下のように再帰的に定義されています。
@c COMMON

@example
(unfold p f g seed tail-gen) @equiv{}
   (if (p seed)
       (tail-gen seed)
       (cons (f seed)
             (unfold p f g (g seed))))
@end example
@c EN
That is, @var{p} determines where to stop, @var{g} is used to generate
successive seed value from the current seed value, and @var{f} is used
to map each seed value to a list element.
@c JP
ここでは、@var{p} は終了位置の判定、@var{g} は現在の「種」から次の「種」
を生成するのに用い、@var{f} はそれぞれの「種」をリストの要素に変換する
のに用いられます。
@c COMMON
@end defun

@defun unfold-right p f g seed :optional tail
@c EN
[SRFI-1]
Fundamental iterative list constructor.
Defined by the following recursion.
@c JP
[SRFI-1]
基本リスト反復構築子です。
以下のように再帰的に定義されています。
@c COMMON

@example
(unfold-right p f g seed tail) @equiv{}
  (let lp ((seed seed) (lis tail))
    (if (p seed)
        lis
        (lp (g seed) (cons (f seed) lis))))
@end example
@end defun

@defun append-map f clist1 clist2 @dots{}
@defunx append-map! f clist1 clist2 @dots{}
@c EN
[SRFI-1]
Equivalent to
@c JP
[SRFI-1]
以下と同等です。
@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! f clist1 clist2 @dots{}
@c EN
[SRFI-1]
The procedure @var{f} is applied to each element of @var{clist1} and
corresponding elements of @var{clist2}s, and the result is collected
to a list.  Cells in @var{clist1} is reused to construct the result list.
@c JP
[SRFI-1]
手続き @var{f} は @var{clist1} の各要素と @var{clist2} の対応する要素
に適用され、結果はひとつのリストになります。@var{clist1} のセルは
結果のリストを構築するのに再利用されます。
@c COMMON
@end defun

@defun map-in-order f clist1 clist2 @dots{}
@c EN
[SRFI-1] A variant of @code{map}, but it guarantees to apply @var{f}
on each elements of arguments in a left-to-right order.
Since Gauche's @code{map} implementation follows the same order,
this function is just a synonym of @code{map}.
@c JP
[SRFI-1] @code{map} の変形バージョンですが、@var{f} の適用順序が、引数として
与えられたリストの要素の左から右への順であることを保証します。
Gauche では @code{map} の実装はこの順になっているので、@code{map} と
同意です。
@c COMMON
@end defun

@defun pair-for-each f clist1 clist2 @dots{}
@c EN
[SRFI-1]
Like @code{for-each}, but the procedure @var{f} is applied on each @code{cdr}
of @var{clist}s.
@c JP
@code{for-each} と似ていますが、手続き @var{f} は各リスト @var{clist} の
@code{cdr} に適用されます。
@c COMMON
@end defun

@defun filter-map  f clist1 clist2 @dots{}
@c EN
[SRFI-1]
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

@node SRFI-1 Filtering & Partitioning, SRFI-1 Searching, SRFI-1 Fold, List library
@subsection List filtering & partitioning
@c NODE リストのフィルタおよび分割

@defun filter pred list
@defunx filter! pred list
@c EN
[SRFI-1] 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
[SRFI-1] 手続き @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 remove pred list
@defunx remove! pred list
@c EN
[SRFI-1] 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
[SRFI-1] 手続き @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 partition pred list
@defunx partition! pred list
@c EN
[SRFI-1] @code{filter} and @code{remove} simultaneously, i.e. 
returns two lists, the first is the result of filtering elements of
@var{list} by @var{pred}, and the second is the result of
removing elements of @var{list} by @var{pred}.
@c JP
[SRFI-1] @code{filter} と @code{remove} を同時に行い、
2つのリストを返します。一つ目は @var{pred} により @var{list} の要素をフィルタリング
した結果で、二つ目は @var{pred} により @var{list} の要素を削除した結果です。 
@c COMMON
@example
(partition odd? '(3 1 4 5 9 2 6))
  @result{} (3 1 5 9) (4 2 6)
@end example
@c EN
@code{partition!} is the linear-update variant.  It may destructively
modifies @var{list} to produce the result.
@c JP
@code{partition!} はその場で更新されるバージョンです。結果を生成するために
@var{list} を破壊的に更新するかもしれません。
@c COMMON
@end defun

@node SRFI-1 Searching, SRFI-1 Deletion, SRFI-1 Filtering & Partitioning, List library
@subsection List searching
@c NODE リストの探索

@defun find pred clist
@c EN
[SRFI-1] 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
[SRFI-1] @var{clist} の各要素に対して左から右に @var{pred} を適用し、
@var{pred} が真を返す最初の要素を返します。@var{pred}を満たす要素が
無い場合は@code{#f}を返します。
@c COMMON
@end defun

@defun find-tail pred clist
@c EN
[SRFI-1]
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
[SRFI-1]
@var{clist} の各要素に対して左から右に @var{pred} を適用し、@var{pred} が
真を返す場合、その car がその要素であるペアを返します。
@var{pred}を満たす要素が無い場合は@code{#f}を返します。
@c COMMON
@end defun

@defun take-while pred clist
@defunx take-while! pred list
@c EN
[SRFI-1]
Returns the longest initial prefix of @var{clist} whose elements all
satisfy @var{pred}.
@c JP
[SRFI-1]
@var{clist} の最初から、@var{pred} を満足する限りの最長部分要素を返します。
@c COMMON
@end defun

@defun drop-while pred clist
@c EN
[SRFI-1]
Drops the longest initial prefix of @var{clist} whose elements all
satisfy @var{pred}, and returns the rest.
@c JP
[SRFI-1]
@var{clist} の最初から、@var{pred} を満足する限りの最長部分要素を削除し、
残りを返します。
@c COMMON
@end defun

@defun span pred clist
@defunx span! pred list
@defunx break pred clist
@defunx break! pred list
@c EN
[SRFI-1]
@code{span} is equivalent to
@code{(values (take-while pred clist) (drop-while pred clist))}.
@code{break} inverts the sense of @var{pred}.
@c JP
[SRFI-1]
@code{span} は @code{(values (take-while pred clist) (drop-while pred clist))} 
と等価です。@code{break} は @var{pred} の意味を反転します。
@c COMMON
@end defun

@defun any pred clist1 clist2 @dots{}
@c EN
[SRFI-1]
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
[SRFI-1]
@var{clist} の各要素に @var{pred} を適用し、@var{pred}が偽でない
値を返したら直ちにその値を返します。
@var{pred}が偽でない値を返す前にリストの要素を使いきってしまったら
@code{#f}が返ります。
@c COMMON
@end defun

@defun every pred clist1 clist2 @dots{}
@c EN
[SRFI-1]
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
[SRFI-1]
@var{clist} の各要素に @var{pred} を順に適用し、@var{pred}が
偽を返した場合、直ちに偽を返します。全ての@var{pred}の適用が
偽でない値を返した場合は、最後に返された値が返されます。
@c COMMON
@end defun

@defun list-index pred clist1 clist2 @dots{}
@c EN
[SRFI-1]
Returns the index of the leftmost element that satisfies @var{pred}.
If no element satisfies @var{pred}, @code{#f} is returned.
@c JP
[SRFI-1]
@var{pred} を満足する最も左の要素のインデックスを返します。
@var{pred}を満たす要素が無い場合は@code{#f}を返します。
@c COMMON
@end defun

@node SRFI-1 Deletion, SRFI-1 Association lists, SRFI-1 Searching, List library
@subsection List deletion
@c NODE リストの削除

@defun delete x list :optional elt=
@defunx delete! x list :optional elt=
@c EN
[SRFI-1]
Equivalent to
@c JP
[SRFI-1]
以下と同等です。
@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=
@c EN
[SRFI-1]
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
[SRFI-1]
@var{list} から重複した要素を取り除きます。@var{list} 中に等しい要素が
複数ある場合、一番左がわにある最初のものだけが残ります。これらの
生き残った要素間の順番は最初のリストの順番が保存されます。
比較手続き @var{elt=} のデフォルト値は、@code{equal?} です。
@c COMMON
@end defun

@node SRFI-1 Association lists, SRFI-1 Set operations, SRFI-1 Deletion, List library
@subsection Association lists
@c NODE 連想リスト

@defun alist-cons key datum alist
@c EN
[SRFI-1] Returns @code{(cons (cons @var{key} @var{datum}) @var{alist})}.
This is an alias of the Gauche builtin procedure @code{acons}.
@c JP
[SRFI-1] @code{(cons (cons @var{key} @var{datum}) @var{alist})} を返します。
これは、Gauche の組み込み手続き @code{acons} の別名です。
@c COMMON
@end defun

@defun alist-copy alist
@c EN
[SRFI-1] 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
[SRFI-1] @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-delete key alist :optional =
@defunx alist-delete! key alist :optional =
@c EN
[SRFI-1]
Deletes all cells in @var{alist} whose key is the same as @var{key}.
Comparison is done by a procedure @var{=}.  The default is @code{eqv?}.

The linear-update version @code{alist-delete!} may or may not modify
@var{alist}.
@c JP
[SRFI-1]
@var{alist} から @var{key}と同じキーをもつすべてのセルを削除します。
比較は @var{=} で行います。これのデフォルト値は @code{eqv?} です。

その場で更新を行うバージョン @code{alist-delete!} は元の
@var{alist} を変更してしまうことがあります。
@c COMMON
@end defun

@node SRFI-1 Set operations,  , SRFI-1 Association lists, List library
@subsection Lists as sets
@c NODE 集合としてのリスト

@c EN
These procedures use a list as a set, that is,
the elements in a list matter, but their order doesn't.

All procedures in this category takes a comparison procedure
@var{elt=}, as the first argument, which is used to determine
two elements in the given sets are the same.

See also @ref{Combination library}, which
concerns combinations of elements in the set.
@c JP
これらの手続きはリストを集合としてあつかいます。すなわち、どのような
要素があるかは重要ですが、その順序は重要ではありません。

この範疇にあるすべての手続きは、比較手続き @var{elt=} を最初の引数として
とります。この比較手続きは与えられた二つの集合の要素が等しいかどうかを
判定します。

集合の要素の組み合せについては @ref{Combination library}
も参照してください。
@c COMMON

@defun lset<= elt= list1 @dots{}
@c EN
[SRFI-1]
Returns @code{#t} iff all elements in @var{list1} are also included
in @var{list2}, and so on.
If no lists are given, or a single list is given,
@code{#t} is returned.
@c JP
[SRFI-1]
@var{list1} のすべての要素が @var{list2} (以降の集合)に含まれている
ときに限り @code{#t} を返します。リストが与えられなかった場合
および一つだけしか与えられなかった場合には、@code{#t} を返します。
@c COMMON
@end defun

@defun lset= elt= list1 list2 @dots{}
@c EN
[SRFI-1]
Returns @code{#t} if all elements in @var{list1} are in @var{list2},
and all elements in @var{list2} are in @var{list1}, and so on.
@c JP
[SRFI-1]
@var{list1} のすべての要素が @var{list2} に含まれており、かつ、
@var{list2} のすべての要素が @var{list1} に含まれていれば、@code{#t}
を返します。
@c COMMON

@example
(lset= eq? '(b e a) '(a e b) '(e e b a)) @result{} #t
@end example
@end defun

@defun lset-adjoin elt= list elt @dots{}
@c EN
[SRFI-1]
Adds @var{elt} @dots{} to the set @var{list}, if each one is not
already a member of @var{list}.  (The order doesn't matter).
@c JP
[SRFI-1]
@var{elt} @dots{} を集合 @var{list} にまだなければ、追加します。
(順序はとくに決っていません。)
@c COMMON

@example
(lset-adjoin eq? '(a b c) 'a 'e) @result{} '(e a b c)
@end example
@end defun

@defun lset-union elt= list1 @dots{}
@c EN
[SRFI-1]
Returns the union of the sets @var{list1} @dots{}.
@c JP
[SRFI-1]
@var{list1} @dots{} の和集合を返します。
@c COMMON
@end defun

@defun lset-intersection elt= list1 list2 @dots{}
@c EN
[SRFI-1]
Returns a set of elements that are in every @var{list}s.
@c JP
[SRFI-1]
すべての @var{list} に含まれる要素の集合を返します。
@c COMMON
@end defun

@defun lset-difference elt= list1 list2 @dots{}
@c EN
[SRFI-1]
Returns a set of elements that are in @var{list1} but not
in @var{list2}.  In n-ary case, binary differece operation is
simply folded.
@c JP
[SRFI-1]
@var{list1} には含まれていて、@var{list2} には含まれていない要素の集合を
返します。引数が n 個与えられた場合には、差分をとる二項演算が
畳み込まれます。
@c COMMON
@end defun

@defun lset-xor elt= list1 @dots{}
@c EN
[SRFI-1]
Returns the exclusive-or of given sets; that is, the returned
set consists of the elements that are in either @var{list1} or @var{list2},
but not in both.   In n-ary case, binary xor operation is simply folded.
@c JP
[SRFI-1]
与えられた集合の排他的論理和を返します。すなわち、@var{list1} および
@var{list2} のどちらか一方にのみ属する要素からなる集合を返します。
引数が n 個の場合には、xor の二項演算が畳み込まれます。
@c COMMON
@end defun

@defun lset-diff+intersection elt= list1 list2 @dots{}
@c EN
[SRFI-1]
Returns two sets, a difference and an intersection of given sets.
@c JP
[SRFI-1]
与えられた集合の差集合と積集合のふたつの集合を返します。
@c COMMON
@end defun

@defun lset-union! elt= list @dots{}
@defunx lset-intersection! elt= list1 list2 @dots{}
@defunx lset-difference! elt= list1 list2 @dots{}
@defunx lset-xor! elt= list1 @dots{}
@defunx lset-diff+intersection! elt= list1 list2 @dots{}
@c EN
[SRFI-1]
Linear update variant of the corresponding procedures.
The cells in the first list argument may be reused to construct the result.
@c JP
[SRFI-1]
それぞれ対応する手続きのその場で更新するバージョンです。
最初の引数のリストのセルが結果を構築するのに再利用されるかもしれません。
@c COMMON
@end defun

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@c ----------------------------------------------------------------------
@c @node Record types, Let-values, Feature-based program configuration language, Library modules - SRFIs
@c @section @code{srfi-9} - Record types
@c @c NODE レコード型, @code{srfi-9} - レコード型

@c @deftp {Module} srfi-9
@c @mdindex srfi-9
@c @c EN
@c Contains a macro to use record types.  A record type is implemented on
@c top of Gauche's object system.

@c The SRFI-9 record type is not as powerful as the object system, but
@c it will be useful if you want your program to be portable.

@c See also @ref{SLIB-compatible record type},
@c which provides an SCM-compatible
@c procedural interface of record types.
@c @c JP
@c このモジュールはレコード型を使うマクロを含んでいます。レコード型は
@c Gauche のオブジェクトシステム上で実装されています。

@c SRFI-9 のレコード型はオブジェクトシステムほどには強力ではありませんが、
@c ポータブルなプログラムを書くときには役に立ちます。

@c ちなみに、レコード型に対するSCMコンパチブルな
@c 手続き的APIを提供する@ref{SLIB-compatible record type}モジュールもあります。
@c @c COMMON
@c @end deftp

@c @defmac define-record-type name (constructor init-tag @dots{}) predicate (field accessor [modifier]) @dots{}
@c @c EN
@c Creates a record type and binds it to @var{name}.
@c In Gauche, a record type is just a subclass of @code{<record>}.

@c @var{constructor} is bound to a procedure that creates an instance
@c of the record type,
@c which takes as many arguments as @var{init-tag} @dots{}.  Each
@c @var{init-tag} corresponds to one of the field name, and the fields
@c of the created record instance is initialized accordingly.  Not all
@c of fields need to appear in @var{init-tag}; uninitialized fields remain
@c unbound.

@c @var{predicate} is bound to a procedure that takes one argument, and
@c returns #t if the argument is an instance of the defined record type,
@c #f otherwise.

@c Followings are field specifications.  The record has fields
@c @var{field} @dots{}, and each field can be accessed by a method
@c @var{accessor}.  If @var{modifier} is given to the field, it is bound
@c to a method that sets the value to the field.

@c Example:
@c @c JP
@c レコード型を作成し、それを @var{name} に束縛します。Gauche では、
@c レコード型は @code{<record>} のサブクラスです。

@c @var{constructor} はそのレコード型のインスタンスを作成する手続きに
@c 束縛されており、@var{init-tag} @dots{} として多くの引数をとります。
@c それぞれの @var{init-tag} はフィールド名に対応しており、作成された
@c レコード型のインスタンスのフィールドはそれぞれの  @var{init-tag} 
@c にしたがって、初期化されます。@var{init-tag} には全てのフィールドが
@c ある必要なはく、初期化されないフィールドは、未束縛のままになります。

@c @var{predicate} は、一つの引数をとり、もしその引数が、定義された
@c レコード型のインスタンスであれば、@code{#t} を返し、さもなければ、
@c @code{#f} を返すような手続きに束縛されます。

@c そのあとは、フィールドの仕様です。レコードはフィールド
@c @var{field} @dots{} をもち、それぞれのフィールドはメソッド
@c @var{accessor} によってアクセス可能です。そのフィールドに対して
@c @var{modifier} が与えられていれば、それは、そのフィールドの
@c 値をセットするメソッドに束縛されます。

@c 例:
@c @c COMMON
@c @example
@c (define-record-type pare
@c   (kons x y) pare?
@c   (x kar set-kar!)
@c   (y kdr))
@c  @result{} #<class pare>

@c (pare? (kons 2 3)) @result{} #t
@c (pare? (cons 2 3)) @result{} #f

@c (kar (kons 2 3)) @result{} 2
@c (kdr (kons 2 3)) @result{} 3

@c (let ((x (kons 2 3)))
@c   (set-kar! x -1)
@c   (kar x)) @result{} -1
@c @end example

@c @c EN
@c Conceptually, the above example is expanded into the following
@c sequence of forms.
@c @c JP
@c 概念的には、上の例は以下の形式のならびに展開されます。
@c @c COMMON
@c @example
@c (define-class pare (<record>) (x y))
@c (define (kons x y)
@c   (let ((obj (make pare)))
@c     (slot-set! obj 'x x) 
@c     (slot-set! obj 'y y)
@c     obj))
@c (define (pare? obj) (is-a? obj pare))
@c (define-method kar ((obj pare))
@c   (slot-ref obj 'x))
@c (define-method set-kar! ((obj pare) value)
@c   (slot-set! obj 'x value))
@c (define-method kdr ((obj pare))
@c   (slot-ref obj 'y))
@c @end example

@c @end defmac

@c ----------------------------------------------------------------------
@node Let-values, String library, Feature-based program configuration language, Library modules - SRFIs
@section @code{srfi-11} - Let-values

@deftp {Module} srfi-11
@mdindex srfi-11
@c EN
Defines two macros, @code{let-values} and @code{let*-values}.
They are convenient to use with multiple values (@ref{srfi-11,,[SRFI-11]}).

@c JP
二つのマクロ、@code{let-values} と @code{let*-values} を定義しています。
これらは、多値とともに利用すると便利です。(@ref{srfi-11,,[SRFI-11]})

@c COMMON
@end deftp

@defmac let-values ((vars expr) @dots{}) body @dots{}
[SRFI-11]
@c EN
@var{vars} are a list of variables. @var{expr} is evaluated, and
its first return value is bound to the first variable in @var{vars},
its second return value to the second variable, and so on, then
@var{body} is evaluated.
The scope of @var{expr}s are the outside of @code{let-values} form,
like @code{let}.
@c JP
@var{vars} は変数のリストです。@var{expr} は評価され、最初の返り値は、
@var{vars} の最初の変数に束縛されます。二番目の返り値は、@var{vars} の
二番目の変数に束縛され、以下同様です。そのあと、@var{body} が評価されます。
@var{expr} のスコープは @code{let} と同様に、@code{let-values} の
外側になります。
@c COMMON

@example
(let-values (((a b) (values 1 2))
             ((c d) (values 3 4)))
  (list a b c d)) @result{} (1 2 3 4)

(let ((a 1) (b 2) (c 3) (d 4))
  (let-values (((a b) (values c d))
               ((c d) (values a b)))
    (list a b c d))) @result{} (3 4 1 2)
@end example

@c EN
@var{vars} can be a dotted list or a single symbol, like the
lambda parameters.
@c JP
@var{vars} lambda パラメータと同様に、ドット付リストでも、
単一のシンボルでもかまいません。
@c COMMON

@example
(let-values (((x . y) (values 1 2 3 4)))
  y) @result{} (2 3 4)

(let-values ((x (values 1 2 3 4)))
  x) @result{} (1 2 3 4)
@end example

@c EN
If the number of values returned by @var{expr} doesn't match
what @var{vars} expects, an error is signalled.
@c JP
@var{expr} によって返された値の数と @var{vars} が期待する数とが一致しない
場合にはエラーになります。
@c COMMON
@end defmac

@defmac let*-values ((vars expr) @dots{}) body @dots{}
[SRFI-11]
@c EN
Same as @code{let-values}, but each @var{expr}'s scope includes
the preceding @var{vars}.
@c JP
@code{let-values}と同じですが、各 @var{expr} のスコープが先行する @var{vars}
を含みます。
@c COMMON

@example
(let ((a 1) (b 2) (c 3) (d 4))
  (let*-values (((a b) (values c d))
                ((c d) (values a b)))
    (list a b c d))) @result{} (3 4 3 4)
@end example
@end defmac

@c ----------------------------------------------------------------------
@node String library, Character-set library, Let-values, Library modules - SRFIs
@section @code{srfi-13} - String library
@c NODE 文字列ライブラリ, @code{srfi-13} - 文字列ライブラリ

@deftp {Module} srfi-13
@mdindex srfi-13
@c EN
Defines a large set of string-related functions.
In Gauche, those functions are splitted to number of files
and the form @code{(use srfi-13)} merely sets up autoloading of
those files.  So it is not likely to slow down the script startup.
@c JP
文字列に関連する関数の大きなセットを定義しています。
Gaucheでは、それらの関数はいくつかのファイルに分割されており、
@code{(use srfi-13)}というフォームは単にそれらのファイルの
オートロードのセットアップをするだけです。
したがって、スクリプトのスタートアップを遅くするようなことは
ありません。
@c COMMON
@c EN
See SRFI-13 (@ref{srfi-13, [SRFI-13], SRFI-13})
for the detailed specification and discussion of design issues.
This manual serves as a reference of function API.
Some SRFI-13 functions are Gauche built-in and not listed here.
@c JP
詳細な仕様とデザインに関する議論については、SRFI-13 (@ref{srfi-13, [SRFI-13], SRFI-13})
を参照して下さい。
このマニュアルは、関数のAPIのリファレンスとして提供されます。
いくつかのSRFI-13の関数は、Gaucheのビルトインになっており、
ここにはリストされていないものもあります。
@c COMMON
@c EN
Note: SRFI-13 documents suggests the name of the module that
implements these functions to be ``string-lib'' and ``string-lib-internals''.
Gauche uses the name ``srfi-13'' for consistency.
@c JP
注意: SRFI-13のドキュメントは、これらの関数を実装するモジュールの
名前を``string-lib''と``string-lib-internals''とすることを推奨しています。
Gaucheでは、一貫性のために``srfi-13''と名付けています。
@c COMMON
@end deftp

@menu
* SRFI-13 General conventions::  
* SRFI-13 String predicates::   
* SRFI-13 String Constructors::  
* SRFI-13 String Selection::    
* SRFI-13 String Comparison::   
* SRFI-13 String Prefixes & Suffixes::  
* SRFI-13 String searching::    
* SRFI-13 String case mapping::  
* SRFI-13 String reverse & append::  
* SRFI-13 String mapping::      
* SRFI-13 String rotation::     
* SRFI-13 other string operations::  
* SRFI-13 String filtering::    
* SRFI-13 Low-level string procedures::  
@end menu

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

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

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

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

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

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

@end table

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

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

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

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

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

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

@end defun

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

@node SRFI-13 String Selection, SRFI-13 String Comparison, SRFI-13 String Constructors, String library
@subsection String selection
@c NODE 文字列の選択

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

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

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

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

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

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

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

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

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

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

@node SRFI-13 String Comparison, SRFI-13 String Prefixes & Suffixes, SRFI-13 String Selection, String library
@subsection String comparison
@c NODE 文字列の色々な比較

@defun string-compare s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
@defunx string-compare-ci s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
[SRFI-13]
@end defun

@defun string= s1 s2 :optional start1 end1 start2 end2
@defunx string<> s1 s2 :optional start1 end1 start2 end2
@defunx string< s1 s2 :optional start1 end1 start2 end2
@defunx string<= s1 s2 :optional start1 end1 start2 end2
@defunx string> s1 s2 :optional start1 end1 start2 end2
@defunx string>= s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@end defun

@defun string-ci= s1 s2 :optional start1 end1 start2 end2
@defunx string-ci<> s1 s2 :optional start1 end1 start2 end2
@defunx string-ci< s1 s2 :optional start1 end1 start2 end2
@defunx string-ci<= s1 s2 :optional start1 end1 start2 end2
@defunx string-ci> s1 s2 :optional start1 end1 start2 end2
@defunx string-ci>= s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@end defun

@defun string-hash s :optional bound start end 
@defunx string-hash-ci s :optional bound start end 
[SRFI-13]
@end defun

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

@defun string-prefix-length s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-length s1 s2 :optional start1 end1 start2 end2
@defunx string-prefix-length-ci s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-length-ci s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@end defun

@defun string-prefix? s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix? s1 s2 :optional start1 end1 start2 end2
@defunx string-prefix-ci? s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-ci? s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@end defun

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

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

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

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

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

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

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

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

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

@defun string-titlecase s :optional start end
@defunx string-titlecase! s :optional start end
@defunx string-upcase s :optional start end
@defunx string-upcase! s :optional start end
@defunx string-downcase s :optional start end
@defunx string-downcase! s :optional start end
[SRFI-13]
Converts a string @var{s} to titlecase, upcase or downcase,
respectively.  These operations uses character-by-character
mapping provided by @code{char-upcase} etc.  That is, @code{string-upcase}
and @code{string-downcase} can be understood as follow:

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

If you need full case mapping that handles the case when
a character is mapped to more than one characters, use
the procedures with the same name in @code{text.unicode} module
(@xref{Full string case conversion}).

The linear-update version @code{string-titelcase!}, @code{string-upcase!}
and @code{string-downcase!} destroys @var{s} to store the result.
Note that in Gauche, using those procedures doesn't save anything,
since string mutation is expensive by design.  They are provided merely
for completeness.
@end defun


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

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

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

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

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

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

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

@defun string-map proc s :optional start end
@defunx string-map! proc s :optional start end
@c EN
[SRFI-13] @code{string-map} applies @var{proc} on every character of @var{s},
and collects the results into a string and returns it.
On the other hand, @code{string-map!} modifies @var{s}.
@c JP
[SRFI-13] @code{string-map}は、@var{s}の全ての文字に対して@var{proc}を
適用し、その結果を文字列に集めそれを返します。
一方、@code{string-map!}は@var{s}そのものを変更します。
@c COMMON
@example
(string-map char-upcase "wikiwiki") @result{} "WIKIWIKI"
(string-map char-upcase "wikiwiki" 4) @result{} "WIKI"

(let ((s (string-copy "wikiwiki")))
  (string-map! char-upcase s 4)
  s)
  @result{} "wikiWIKI"
@end example
@end defun

@defun string-fold kons knil s :optional start end
@defunx string-fold-right kons knil s :optional start end
[SRFI-13]
@end defun

@defun string-unfold p f g seed :optional base make-final
[SRFI-13]
@end defun

@defun string-unfold-right p f g seed :optional base make-final
[SRFI-13]
@end defun

@defun string-for-each proc s :optional start end
[SRFI-13]
@end defun

@defun string-for-each-index proc s :optional start end
[SRFI-13]
@end defun

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

@defun xsubstring s from :optional to start end
[SRFI-13]
@end defun

@defun string-xcopy! target tstart s sfrom :optional sto start end
[SRFI-13]
@end defun

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

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

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

@end defun

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

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

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

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

@defun string-filter s char/char-set/pred :optional start end
@defunx string-delete s char/char-set/pred :optional start end
[SRFI-13]
@end defun

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

@defun string-parse-start+end proc s args
@defunx string-parse-final-start+end proc s args
[SRFI-13]
@end defun

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

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

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

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

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

@c ----------------------------------------------------------------------
@node Character-set library, Time data types and procedures, String library, Library modules - SRFIs
@section @code{srfi-14} - Character-set library
@c NODE 文字集合ライブラリ, @code{srfi-14} - 文字集合ライブラリ

@deftp {Module} srfi-14
@mdindex srfi-14
@c EN
Implements the character set library defined in SRFI-14
(@ref{srfi-14,,SRFI-14}).  Note that several basic character-set
operations are Gauche's build-in functions.  @xref{Character set}.
@c JP
SRFI-14で定義された文字セットライブラリを実装します
(@ref{srfi-14,,SRFI-14})。
基本的な文字セットの操作はGauche組み込みになっています(@ref{Character set}参照)。
このモジュールでは多くのユーティリティ手続きが追加されます。
@c COMMON
@end deftp

@menu
* SRFI-14 Character-set constructors::  
* SRFI-14 Character-set Comparison::  
* SRFI-14 Character-set iteration::  
* SRFI-14 Character-set query::  
* SRFI-14 Character-set algebra::  
* SRFI-14 Predefined character-set::  
@end menu

@node SRFI-14 Character-set constructors, SRFI-14 Character-set Comparison, Character-set library, Character-set library
@subsection Character-set constructors
@c NODE 文字セットの構築子

@defun list->char-set char-list :optional base-cs
@defunx list->char-set! char-list base-cs
[SRFI-14]
@c EN
Constructs a character set from a list of characters @var{char-list}.
If @var{base-cs} is given, it must be a character set, and the characters
in it are added to the result character set.
@code{List->char-set!} is allowed, but not required, to reuse @var{base-cs}
to store the result.
@c JP
与えられた文字のリスト@var{char-list}から文字セットを構築して返します。
文字セット@var{base-cs}が与えられていた場合、返される文字セットは
その文字セットに@var{char-list}中の文字を追加したものとなります。
@code{list->char-set!}は、結果を格納するために@var{base-cs}を
変更するかもしれません。
@c COMMON
@end defun

@defun string->char-set s :optional base-cs
@defunx string->char-set! s base-cs
[SRFI-14]
@c EN
Like @code{list->char-set} and @code{list->char-set!}, 
but take a list of characters from a string @var{s}.
@c JP
追加する文字をリストでなく文字列@var{s}で与えることを除けば
@code{list->char-set}、@code{list->char-set!}と同じです。
@c COMMON
@end defun

@defun char-set-filter pred char-set :optional base-cs
@defunx char-set-filter! pred char-set base-cs
[SRFI-14]
@c EN
Returns a character set containing every character @var{c} in
@var{char-set} such that @code{(@var{pred} @var{c})} returns true.
If a character set @var{base-cs} is given, its content is added to 
the result.  The linear update version @code{char-set-filter!}
is allowed, but not required, to modify @var{base-cs} to store the result.
@c JP
@var{char-set}内の文字のうち、@code{(@var{pred} @var{c})} が真の値を
返すような@var{c}からなる文字セットを作成して返します。
文字セット@var{base-cs}が与えられた場合は、その内容が結果に追加されます。
@code{char-set-filter!}は、結果を格納するために@var{base-cs}を変更するかも
しれません。
@c COMMON
@end defun

@defun ucs-range->char-set lower upper :optional error? base-cs
@defunx ucs-range->char-set! lower upper error? base-cs
[SRFI-14]
@c EN

@c JP
@c COMMON
@end defun

@defun integer-range->char-set lower upper :optional error? base-cs
@defunx integer-range->char-set! lower upper error? base-cs
@c EN
@c JP
@c COMMON
@end defun

@defun ->char-set x
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@node SRFI-14 Character-set Comparison, SRFI-14 Character-set iteration, SRFI-14 Character-set constructors, Character-set library
@subsection Character-set comparison
@c NODE 文字セットの比較

@defun char-set= char-set1 @dots{}
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set<= char-set1 @dots{}
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-hash char-set :optional bound
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@node SRFI-14 Character-set iteration, SRFI-14 Character-set query, SRFI-14 Character-set Comparison, Character-set library
@subsection Character-set iteration
@c NODE 文字セットのイテレーション

@defun char-set-cursor char-set
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-ref char-set cursor
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-cursor-next char-set cursor
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun end-of-char-set? ccursor
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-fold kons knil char-set
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-unfold pred fun gen seed :optional base-char-set
@defunx char-set-unfold! pred fun gen seed base-char-set
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-for-each proc char-set
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@defun char-set-map proc char-set
[SRFI-14]
@c EN
@c JP
@c COMMON
@end defun

@node SRFI-14 Character-set query, SRFI-14 Character-set algebra, SRFI-14 Character-set iteration, Character-set library
@subsection Character-set query
@c NODE 文字セットへの問い合わせ

@defun char-set-size char-set
[SRFI-14]
@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-every pred char-set
@defunx char-set-any pred char-set
@defunx char-set-count pred char-set
[SRFI-14]
@c EN
These procedures apply @var{pred} to each character in @var{char-set}.

@code{char-set-every} returns @code{#f} as soon as @var{pred} returns
@code{#f}.  Otherwise, it returns the result of the last application of
@var{pred}.

@code{char-set-any} returns as soon as @var{pred} returns a true value,
and the return value is the one @var{pred} returns.
If @var{pred} returns @code{#f} for all characters, @code{#f} is returned.

@code{char-set-count} returns the number of times
@var{pred} returns a true value.

Note that @var{char-set} can be huge (e.g. a complement of small char-set),
which can make these procedures take very long.
@c JP
これらの手続きは、@var{pred}を@var{char-set}に含まれる各文字に適用します。

@code{char-set-every}は@var{pred}が@code{#f}を返したら直ちに@code{#f}を返します。
@var{pred}が最後まで@code{#f}を返さなかった場合は、最後の@var{pred}の返り値が
@code{char-set-every}の返り値となります。

@code{char-set-any}は@var{pred}が真の値を返した場合に直ちにその値を返します。
@var{pred}が最後まで@code{#f}を返した場合には@code{#f}を返します。

@code{char-set-count}は@var{pred}が真の値を返した回数を返します。

@var{char-set}は非常に大きくなる可能性があり (例えばごく小さな文字セットの補集合)、
その場合、これらの手続きは非常に長くかかり得ることに注意してください。
@c COMMON
@end defun

@defun char-set->list char-set
@defunx char-set->string char-set
[SRFI-14]
@c EN
Returns a list of each character, or a string consisting of 
each character, in @var{char-set}, respectively.
Be careful to apply this on a large char set.
@c JP
@var{char-set}に含まれる文字をリストあるいは文字列にして返します。
大きな文字セットに適用する場合は注意してください。
@c COMMON
@end defun


@node SRFI-14 Character-set algebra, SRFI-14 Predefined character-set, SRFI-14 Character-set query, Character-set library
@subsection Character-set algebra
@c NODE 文字セットに適用できる代数的関数

@defun char-set-adjoin char-set char1 @dots{}
@defunx char-set-adjoin! char-set char1 @dots{}
[SRFI-14]
@c EN
Returns a character set that adds @var{char1} @dots{} to
@var{char-set}.
@c JP
@var{char-set}に@var{char1} @dots{}を加えた文字集合を返します。
@c COMMON
@end defun

@defun char-set-delete char-set char1 @dots{}
@defunx char-set-delete! char-set char1 @dots{}
[SRFI-14]
@end defun

@defun char-set-complement char-set
@defunx char-set-complement! char-set
[SRFI-14]
@end defun

@defun char-set-union char-set @dots{}
@defunx char-set-union! char-set1 char-set2 @dots{}
[SRFI-14]
@end defun

@defun char-set-intersection char-set @dots{}
@defunx char-set-intersection! char-set1 char-set2 @dots{}
[SRFI-14]
@end defun

@defun char-set-difference char-set1 char-set2 @dots{}
@defunx char-set-difference! char-set1 char-set2 @dots{}
[SRFI-14]
@end defun

@defun char-set-xor char-set @dots{}
@defunx char-set-xor! char-set1 char-set2 @dots{}
[SRFI-14]
@end defun

@defun char-set-diff+intersection char-set1 char-set2 @dots{}
@defunx char-set-diff+intersection! char-set1 char-set2 char-set3 @dots{}
[SRFI-14]
@end defun



@node SRFI-14 Predefined character-set,  , SRFI-14 Character-set algebra, Character-set library
@subsection Predefined character-set
@c NODE 定義済みの文字セット

@defvar char-set:letter
[SRFI-14]
@end defvar

@defvar char-set:blank
[SRFI-14]
@end defvar

@defvar char-set:iso-control
[SRFI-14]
@end defvar

@defvar char-set:digit
@defvarx char-set:hex-digit
[SRFI-14]
@end defvar

@defvar char-set:graphic
[SRFI-14]
@end defvar

@defvar char-set:lower-case
@defvarx char-set:upper-case
@defvarx char-set:title-case
[SRFI-14]
@end defvar

@defvar char-set:printing
[SRFI-14]
@end defvar

@defvar char-set:punctuation
[SRFI-14]
@end defvar

@defvar char-set:whitespace
[SRFI-14]
@end defvar

@defvar char-set:symbol
[SRFI-14]
@end defvar

@defvar char-set:ascii
[SRFI-14]
@end defvar

@defvar char-set:empty
[SRFI-14]
@end defvar

@defvar char-set:full
[SRFI-14]
@end defvar

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

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

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

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

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

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

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

@defvr {Constant} time-tai
[SRFI-19]
@c EN
International Atomic Time.  This time is a bit larger than UTC, due to
the leap seconds.
@c JP
International Atomic Time。この時間は閏秒を計算に入れており、
UTCより若干大きな値を取ります。
@c COMMON
@end defvr

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

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

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

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

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

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

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

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

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

@defun time-resolution
[SRFI-19]
@end defun


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

@defun make-time type nanoseconds seconds
[SRFI-19]
@c EN
Returns an instance of @code{<time>} class with specified initial values.
Equivalent to @code{(make <time> :type type :second seconds :nanosecond nanoseconds)}.

(This function had been defined incorrectly before release 0.6.8; 
the arguments @var{seconds} and @var{nanoseconds} were switched.
Please check your code if it uses @code{make-time}).
@c JP
与えられた初期値を持つ@code{<time>}クラスのインスタンスを返します。
@code{(make <time> :type type :second seconds :nanosecond nanoseconds)}
と等価です。

(この関数は0.6.8より前のリリースでは間違って定義されていました。
@var{seconds}と@var{nanoseconds}の引数が逆になっていたのです。
@code{make-time}を使っているコードは注意して下さい)。
@c COMMON
@end defun

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

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

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

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

@defun add-duration time0 time-duration
@defunx add-duration! time0 time-duration
@defunx subtract-duration time0 time-duration
@defunx subtract-duration! time0 time-duration
[SRFI-19]
@c EN
Adds or subtracts @var{time-duration} to or from @var{time0}.
Type of returned time is the same as @var{time0}.  Type of
@var{time-duration} must be @code{time-duration}.
@code{add-duration!} and @code{subtract-duration!} reuse
@var{time0} to store the result.
@c JP
@var{time-duration}を@var{time0}に加算、または@var{time0}から減算します。
返される時間のタイプは@var{time0}と同じです。@var{time-duration}のタイプは
@code{time-duration}でなければなりません。
@code{add-duration!}と@code{subtract-duration!}は結果を格納するのに
@var{time0}を再利用します。
@c COMMON
@end defun

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

@end defun

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

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

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

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

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

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

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

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

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

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

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

@defun random-source-make-reals s :optional unit
[SRFI-27]
@c EN
Returns a procedure, that takes no argument and
returns a random real between 0 and 1 exclusive for
every invocation, from the random source @var{s}.
If @var{unit} is given, the random real the returned procedure
generates will be quantized by the given @var{unit}, where 
0 < @var{unit} < 1.
@c JP
呼出しのたびに乱数発生源 @var{s} から 0 より大きく 1 未満の実数乱数を
返す、無引数の手続きを返します。
@c COMMON
@end defun

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@defun option names require-arg? optional-arg? processor
@c EN
Creates an option object with the passed properties.

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

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

@var{Processor} is the option processor procedure.

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

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

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

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

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

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

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

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

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

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

@example
(use srfi-37)

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

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

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

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

@c EN
It also runs eagerly, that is, if it generates a list, it
creates the entire list when evaluated, instead of generate the
elements @emph{on demand}.  Thus it can't represent an infinite
sequence, which Haskell's comprehension naturally does.  In Scheme,
you can use streams built on top of delayed evaluation for
such purpose (@xref{Stream library}).
@c JP
この機構は先行評価的に走ります。すなわち、リストを生成する場合、評価時
にすべてのリストを生成します。要素を@emph{要求駆動的}に生成するわけで
はありません。それゆえ、無限列を表現することはできません。それが自然に
できる Haskell とは違います。Schemeにおいては無限列を扱うのなら遅延評
価をするように構築されたストリームが使えます
(@ref{Stream library}参照)。
@c COMMON
@end deftp

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@defmac do-ec qualifier @dots{} body
[SRFI-42]
Repeats @var{body}.  The results of @var{body} is discarded.
This is for side-effecting operations.
@end defmac

@defmac list-ec qualifier @dots{} body
[SRFI-42]
Repeats @code{body} and collects the results into a list.
@end defmac

@defmac append-ec qualifier @dots{} body
[SRFI-42]
Repeats @code{body}, which must yield a list.
Returns a list which is the concatenation of all lists retured by @var{body}.
@end defmac

@defmac string-ec qualifier @dots{} body
@defmacx string-append-ec qualifier @dots{} body
[SRFI-42]
Repeats @var{body}, which must yield a character (in @code{string-ec})
or a string (in @code{string-append-ec}).  Returns a string that
consists of the results of @var{body}.
@end defmac

@defmac vector-ec qualifier @dots{} body
[SRFI-42]
Repeats @var{body} and collects the results into a vector.
@end defmac

@defmac vector-of-length-ec k qualifier @dots{} body
[SRFI-42]
This is like @code{vector-ec}, except that the length of the
result vector is known to be @var{k}.  It can be more efficient
than @code{vector-ec}.  Unless the comprehension repeats exactly
@code{k} times, an error is signaled.
@end defmac

@defmac sum-ec qualifier @dots{} body
@defmacx product-ec qualifier @dots{} body
[SRFI-42]
@var{body} must yield a numeric value.  Returns sum of and product of
the results, respectively.
@end defmac

@defmac min-ec qualifier @dots{} body
@defmacx max-ec qualifier @dots{} body
[SRFI-42]
@var{body} must yield a numeric value.  Returns maximum and minimum value
of the results, respectively.  @var{body} must be evaluated at least once,
or an error is signalled.
@end defmac

@defmac any?-ec qualifier @dots{} test
@defmacx every?-ec qualifier @dots{} test
[SRFI-42]
Evaluates @var{test} for each iteration, and returns
@code{#t} as soon as it yields non-@code{#f} (for @code{any-ec?}),
or returns @code{#f} as soon as it yields @code{#f} (for @code{every?-ec}).
Unlink the comprehensions introduced above, these stop evaluating
@var{test} as soon as the condition meets.  
If the qualifiers makes no iteration, @code{#f} and @code{#t} are
returned, respectively.
@end defmac

@defmac first-ec default qualifier @dots{} body
@defmacx last-ec default qualifier @dots{} body
[SRFI-42]
First initializes the result by the value of the expression @var{default}, 
then start iteration, and returns the value of the first and last 
evaluation of @var{body}, respectively.  In fact, @code{first-ec}
only evaluates @var{body} at most once.

These procedures are most useful when used with control qualifiers.
For example, the following @code{first-ec} returns the @emph{first}
set of distinct integers (@var{x}, @var{y}, @var{z}),
where @var{x}*@var{x}+@var{y}*@var{y}+@var{z}*@var{z} becomes a square
of another integer @var{w}.

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

Note that the first qualifier, @code{(:integers w)}, generates
infinite number of integers; if you use @code{list-ec} instead of
@code{first-ec} it won't stop.
@end defmac

@defmac fold-ec seed qualifier @dots{} expr proc
@defmacx fold3-ec seed qualifier @dots{} expr init proc
[SRFI-42]
Reduces the values produced by @var{expr}.

Suppose @var{expr} produces a sequence of values
@var{x0}, @var{x1}, @dots{}, @var{xN}.  @code{Fold-ec}
calculates the following value:

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

It's similar to @code{fold}, except that @var{proc} is evaluated 
within the scope of @var{qualifier} @dots{} so you can refer to the
variables introduced by them.  On the other hand,
@var{seed} is outside of the scope of @var{qualifier}s.

@code{Fold-ec3} is almost the same but the initial value calculation.
In @code{fold-ec3}, @var{seed} is only used when @var{qualifier}s
makes no iteration.  Otherwise it calculates the following value:

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

@end defmac

@subheading Qualifiers

@subsubheading Generational qualifiers

This type of qualifiers generates (possibly infinite) values
over which the rest of clauses iterate.

In the following descriptions, @var{vars} refers to either
a single identifier, or a series of identifier and a form
@code{(index @var{identifier2})}.  The single identifier
in the former case and the first identifier in the latter case
name the variable to which each generated value is bound.
The @var{identifier2} in the latter case names a variable
to which a series of integers, increasing with each generated
element, is bound.   See the following example:

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

@deffn {EC Qualifier} : vars arg1 args @dots{}
A generic dispatcher of generational qualifiers.
@end deffn

@deffn {EC Qualifier} :list vars arg1 args @dots{}
@deffnx {EC Qualifier} :vector vars arg1 args @dots{}
@deffnx {EC Qualifier} :string vars arg1 args @dots{}
@end deffn

@deffn {EC Qualifier} :integers vars
@end deffn

@deffn {EC Qualifier} :range vars stop
@deffnx {EC Qualifier} :range vars start stop
@deffnx {EC Qualifier} :range vars start stop step
@end deffn

@deffn {EC Qualifier} :real-range vars stop
@deffnx {EC Qualifier} :real-range vars start stop
@deffnx {EC Qualifier} :real-range vars start stop step
@end deffn

@deffn {EC Qualifier} :char-range vars min max
@end deffn

@deffn {EC Qualifier} :port vars port
@deffnx {EC Qualifier} :port vars port read-proc
@end deffn

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

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

@deffn {EC Qualifier} :let vars expr
@end deffn

@deffn {EC Qualifier} :parallel generator @dots{}
@end deffn

@deffn {EC Qualifier} :while generator expr
@end deffn

@deffn {EC Qualifier} :until generator expr
@end deffn

@subsubheading Control qualifiers

@deffn {EC Qualifier} if test
@end deffn

@deffn {EC Qualifier} not test
@deffnx {EC Qualifier} and test @dots{}
@deffnx {EC Qualifier} or test @dots{}
@end deffn

@deffn {EC Qualifier} begin command @dots{} expr
@end deffn

@deffn {EC Qualifier} nested qualifier @dots{}
@end deffn


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

@deftp {Module} srfi-43
@mdindex srfi-43
@c EN
This module provides library functions for vectors.
Some of srfi-43 procedures are built-in; see @ref{Vectors}.
@c JP
このモジュールはベクタ用のライブラリ関数を提供します。
SRFI-43のいくつかの関数は組み込みになっています。@ref{Vectors}を見てく
ださい。
@c COMMON
@end deftp

@c EN
@subheading Vector constructors
@c JP
@subheading ベクタ構成子
@c COMMON

@defun vector-unfold f length seed @dots{}
[SRFI-43]
@end defun

@defun vector-unfold-right f length seed @dots{}
[SRFI-43]
@end defun

@defun vector-reverse-copy vec :optional start end
[SRFI-43]
@end defun

@defun vector-append vec @dots{}
[SRFI-43]
Returns a newly allocated vector whose contents are concatenation
of elements of @var{vec} in order.
@end defun

@defun vector-concatenate list-of-vectors
[SRFI-43]
Acts like @code{(apply vector-append list-of-vectors)}, though
this may be more efficient.
@end defun

@c EN
@subheading Vector predicates
@c JP
@subheading ベクタ上の述語
@c COMMON

@defun vector-empty? vec
[SRFI-43]
Returns @code{#t} if @var{vec}'s length is zero, and
@code{#f} if @var{vec}'s length is more than zero.
Signals an error if @var{vec} is not a vector.
@end defun

@defun vector= elt= vec @dots{}
[SRFI-43]
Compares @var{vec}s element-wise, using given predicate @var{elt=}.
Returns @code{#t} iff lengths of all the vectors are the same,
and every corresponding elements are equal by @var{elt=}.
@var{Elt=} is always called with two arguments and must
return @code{#t} iff two are the same. 
@end defun

@c EN
@subheading Iteration over vectors
@c JP
@subheading ベクタ上の反復
@c COMMON

@defun vector-fold kons knil vec1 vec2 @dots{}
[SRFI-43]
@var{Kons} is a procedure that takes @var{n}+2 arguments, where
@var{n} is the number of given vectors.  For each element of the
given vectors, @var{kons} is called as
@code{(@var{kons} @var{i} @var{seed} @var{e_1i} @var{e_2i} @dots{})},
where @var{i} is the index, and @var{e_ni} is the @var{i}-th element
of the vector @var{n}.  If the lengths of the vectors differ,
iteration stops when the shortest vector is exhausted.

The initial value of @var{seed} is @var{knil}, and the return value
from @var{kons} is used as the next seed value.  The last return value
of @var{kons} is returned from @code{vector-fold}.

The iteration is strictly left to right.

Note that the seed value precedes elements, which is opposite to
@code{fold} (@xref{Mapping over collection}).  It's an unfortunate
historical glitch; @code{vector-fold-left} would be more consistent
name.
@end defun

@defun vector-fold-right kons knil vec1 vec2 @dots{}
[SRFI-43]
Like @code{vector-fold}, but iterates right to left.
@end defun

@defun vector-map f vec1 vec2 @dots{}
@defunx vector-map! f vec1 vec2 @dots{}
@defunx vector-for-each f vec1 vec2 @dots{}
@defunx vector-count f vec1 vec2 @dots{}
[SRFI-43]
The argument @var{f} is a procedure that takes @var{n}+1 arguments where
@var{n} is the number of given vectors.   These procedures call @var{f}
for each element of the given vectors as
@code{(@var{f} @var{i} @var{e_1i} @var{e_2i} @dots{})},
where @var{i} is the index, and @var{e_ni} is the @var{i}-th element
of the vector @var{n}.   If the lengths of the vectors differ, iteration
only covers the shortest vector.

@code{vector-map} creates a fresh vector out of the result of applications
of @var{f} and returns it.
@code{vector-map!} reuses @var{vec1} to
store the result and returns @var{vec1}; hence @var{vec1} must be mutable.

@code{vector-for-each} is for side-effects.  It discards the result of
@var{f}.

@code{vector-count} counts the number of times @var{f} returned a true value.

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

Note: The generic @code{map} and @code{for-each}
in @code{gauche.collection} can be used
on vectors, but the procedure is called without index, and the result
is returned as a list.
@code{(vector-map f vec1 vec2 @dots{})} is operationally equivalent to
@code{(map-to-with-index <vector> f vec1 vec2 @dots{})}.
See @ref{Collection framework} and @ref{Sequence framework}.
@end defun

@c EN
@subheading Vector searching
@c JP
@subheading ベクタ上の検索
@c COMMON

@defun vector-index pred vec1 vec2 @dots{}
@defunx vector-index-right pred vec1 vec2 @dots{}
[SRFI-43]
Returns the index of the first or the last elements in @var{vec1}
@var{vec2} @dots{} that satisfy @var{pred}, respectively.
Returns @code{#f} if no elements satisfy @var{pred}.
In @code{vector-index}, comparison ends at the end of the shortest vector.
For @code{vector-index-right}, all the vectors must have the same length.
@end defun

@defun vector-skip pred vec1 vec2 @dots{}
@defunx vector-skip-right pred vec1 vec2 @dots{}
[SRFI-43]
Like @code{vector-index} and @code{vector-index-right}, except that
the result of @var{pred} is negated.  That is, returns the index
of the first or the last elements that don't sastisfy @var{pred}.
@end defun

@defun vector-binary-search vec value cmp :optional start end
[SRFI-43+]
Look for @var{value} in a vector @var{vec}, and returns its
index if it is found, or @code{#f} if it is not found.
Comparison of @var{value} and an element in @var{vec} is
done by a procedure @var{cmp}, which takes two arguments,
and should return a negative integer if the first argument is less than the
second, 0 if they are the same, and a positive integer if the first
is greater than tne second.

Elements in @var{vec} must be ordered from smaller to greater
w.r.t. @var{cmp}.  Using that fact, this procedure performs
binary search instead of linear search.

The optional arguments @var{start} and @var{end} are an
extention to SRFI-43, and can be used to limit the range of the
search in @var{start}-th element (inclusive) to
@var{end}-th element (exclusive).
@end defun

@defun vector-any pred vec1 vec2 @dots{}
[SRFI-43]
Applies @var{pred} on each corresponding elements 
of @var{vec1} @var{vec2} @dots{} left to right, and
as soon as @var{pred} returns non-@code{#f} value, 
the procedure stops iteration and returns the value.

If no elements that satisfy @var{pred} are found, it returns @code{#f}.

Vectors can have different lengths.  Iteration stops at the end
of the shortest.
@end defun

@defun vector-every pred vec1 vec2 @dots{}
[SRFI-43]
Applies @var{pred} on each corresponding elements 
of @var{vec1} @var{vec2} @dots{} left to right.
If all the elements (when the lengths of vectors differ, the
first N elements where N is the length of the shortest) satisfy
@var{pred}, returns the last result of @var{pred}.   Otherwise
returns @code{#t}.
@end defun

@c EN
@subheading Vector mutators
@c JP
@subheading ベクタの変更子
@c COMMON

@defun vector-swap! vec i j
[SRFI-43]
Swaps vector @var{vec}'s @code{i}-th and @code{j}-th elements.
@end defun

@defun vector-reverse! vec :optional start end
[SRFI-43]
@end defun

@defun vector-copy! target tstart source :optional sstart send
[SRFI-43]
@end defun

@defun vector-reverse-copy! target tstart source :optional sstart send
[SRFI-43]
@end defun

@c EN
@subheading Vector conversion
@c JP
@subheading ベクタの変換
@c COMMON

@defun reverse-vector->list vec :optional start end
[SRFI-43]
@end defun

@defun reverse-list->vector list :optional start end
[SRFI-43]
@end defun

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

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

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

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

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

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

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

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

@c ----------------------------------------------------------------------
@node Integers as bits, Accessing environment variables, Requiring extensions, Library modules - SRFIs
@section @code{srfi-60} - Integers as bits
@c NODE 整数に対するビット操作, @code{srfi-60} - 整数に対するビット操作

@deftp {Module} srfi-60
@mdindex srfi-60
This srfi provides bit operations on integers, regarding them
as 2's complement representation.

Most of the funcionalities in this module are already provided
as builtin procedures (@xref{Bitwise operations}).  This srfi
defines popular aliases for many of those procedures, thus
has better portability.  There are also several additional
procedures than Gauche's builtin bitwise operations.
@end deftp

@subsection Bitwise operators

@defun lognot n
@defunx bitwise-not n
Same as builtin @code{lognot} (@xref{Bitwise operations}).
@end defun

@defun logand n @dots{}
@defunx bitwise-and n @dots{}
Same as builtin @code{logand} (@xref{Bitwise operations}).
@end defun

@defun logior n @dots{}
@defunx bitwise-ior n @dots{}
Same as builtin @code{logior} (@xref{Bitwise operations}).
@end defun

@defun logxor n @dots{}
@defunx bitwise-xor n @dots{}
Same as builtin @code{logxor} (@xref{Bitwise operations}).
@end defun

@defun bitwise-if mask n0 n1
Returns integer, whose @var{n}-th bit is taken as follows:
If the @var{n}-th bit of @var{mask} is 1, the @var{n}-th bit of @var{n0};
otherwise, the @var{n}-th bit of @var{n1}.

@example
(bitwise-if #b10101100 #b00110101 #b11001010)
 @result{} #b01100110
@end example
@end defun

@defun logtest mask n
@defunx any-bits-set? mask n
Same as builtin @code{logtest} (@xref{Bitwise operations}).
@end defun

@subsection Integer properties

@defun logcount n
@defunx bit-count n
Same as builtin @code{logcount} (@xref{Bitwise operations}).
@end defun

@defun integer-length n
Same as builtin @code{integer-length} (@xref{Bitwise operations}).
@end defun

@defun log2-binary-factors n
@defunx first-set-bit n
Returns the number of factors of two of integer @var{n}; that is,
returns a maximum @var{k} such that @code{(expt 2 k)} divides
@var{n} without a remainder.
It is the same as the index of the least significant @code{1} in @var{n},
hence the alias @code{first-set-bit}.

@example
(log2-binary-factors 0) @result{} -1   ; @r{edge case}
(log2-binary-factors 1) @result{} 0
(log2-binary-factors 2) @result{} 1
(log2-binary-factors 15) @result{} 0
(log2-binary-factors 16) @result{} 4
@end example
@end defun

@subsection Bit within word

@defun logbit? index n
@defunx bit-set? index n
Same as builtin @code{logbit?} (@xref{Bitwise operations}).
@end defun

@defun copy-bit index n bit
Same as builtin @code{copy-bit} (@xref{Bitwise operations}).
@end defun

@subsection Field of bits

@defun bit-field n start end
Same as builtin @code{bit-field} (@xref{Bitwise operations}).
@end defun

@defun copy-bit-field to from start end
Same as builtin @code{copy-bit-field} (@xref{Bitwise operations}).
@end defun

@defun ash n count
@defunx arithmetic-shift n count
Same as builtin @code{ash} (@xref{Bitwise operations}).
@end defun

@defun rotate-bit-field n count start end
Rotate the region of @var{n} between @var{start}-th bit (inclusive) and
@var{end}-th bit (exclusive) by @var{count} bits.

@example
(rotate-bit-field #b110100100010000 -1 5 9)
 @result{} 26768 ; #b110100010010000

(rotate-bit-field #b110100100010000 1 5 9)
 @result{} 26672 ; #b110100000110000
@end example
@end defun

@defun reverse-bit-field n start end
Reverse the order of bits of @var{n} between @var{start}-th bit
(inclusive) and @var{end}-th bit (exclusive).

@example
(reverse-bit-field #b10100111 0 8)
 @result{} 229 ; #b11100101
@end example

@end defun

@subsection Bit as booleans

@defun integer->list n :optional len
Breaks @var{n} to each bits, representing @code{1} as @code{#t} and
@code{0} as @code{#f}, LSB last, and returns a list of them.
If a nonnegative integer @var{len} is given, it specifies the length
of the result.   If it is omitted, @code{(integer-length n)} is used.

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

@defun list->integer lis
Takes a list of boolean values, replaces the true value for @code{1}
and the false value for @code{0}, and compose an integer regarding
each value as a binary digit.  If @var{n} is nonnegative integer,
@code{(eqv? (list->integer (integer->list n)) n)} is true.

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

@defun booleans->integer bool @dots{}
@equiv{} @code{(list->integer (list @var{bool} @dots{}))}
@end defun

@c ----------------------------------------------------------------------
@node Accessing environment variables,  , Integers as bits, Library modules - SRFIs
@section @code{srfi-98} - Accessing environemnt variables
@c NODE 環境変数へのアクセス, @code{srfi-98} - 環境変数へのアクセス

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

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

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

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

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

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

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


@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
