Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
10297 lines (8753 sloc) 331 KB
@node Library modules - R7RS standard libraries, Library modules - SRFIs, Library modules - Gauche extensions, Top
@chapter Library modules - R7RS standard libraries
@c NODE ライブラリモジュール - R7RS標準ライブラリ
@c EN
Gauche predates R7RS, and for the convenience, Gauche makes quite a few
procedures as built-in (@pxref{Core library}). Although the set of
Gauche's core features are mostly superset of R7RS, some functions
and syntaxes have different names and/or interface from R7RS.
R7RS fully-compatible syntaxes and functions are available
in the set of modules described in this chapter. Since R7RS
programs and libraries needs to follow a specific format
(@code{import} declaration or @code{define-library} form),
generally there's no ambiguity in whether you're looking at R7RS code
or Gauche-specific code. Also, it is totally transparent to load
R7RS library into Gauche-specific code or vice versa.
However, you need to be aware of which ``world'' you're in when
you code.
@c JP
GaucheはR7RS以前からあり、使い勝手のために非常に多くの組み込み手続きを
持っています(@ref{Core library}参照)。そのほとんどはR7RSのスーパーセットと
なっていますが、いくつかの手続きや構文は違う名前であったり、
違うインタフェースを取っていたりします。
R7RSと完全に互換な構文と関数は、本章で説明されるモジュール群によって提供されます。
R7RSプログラムとライブラリは特定の形式で書かれるので
(@code{import}宣言で始まるか、もしくは@code{define-library}フォーム)、
通常はR7RSのコードを見ているのかGauche特有のコードを見ているのかははっきり区別できます。
また、Gauche特有のコードからR7RSライブラリをロードすることも、その逆も、
全く透過的にできます。
但し、コードを書く時には、どちらの「世界」にいるのかを意識する必要があります。
@c COMMON
@c EN
If you're familiar with Gauche, take a look at
the section @ref{R7RS integration}, which describes how you can
go back and forth between Gauche and R7RS.
@c JP
Gaucheに慣れているプログラマは、まず@ref{R7RS integration}に目を通してください。
どうやってGaucheとR7RSの世界を行き来するか説明してあります。
@c COMMON
@menu
* R7RS integration::
* R7RS small language::
* R7RS large::
@end menu
@node R7RS integration, R7RS small language, Library modules - R7RS standard libraries, Library modules - R7RS standard libraries
@section R7RS integration
@c NODE R7RS統合
@menu
* Traveling between two worlds back and forth::
* Three forms of import::
@end menu
@node Traveling between two worlds back and forth, Three forms of import, R7RS integration, R7RS integration
@subsection Traveling between two worlds back and forth
@c NODE 二つの世界を往き来する
@c EN
When you start Gauche, either in REPL or as a script, you're in
@code{user} module, which @emph{inherits} @code{gauche} module.
Likewise, when you read a library, the initial module inherits
@code{gauche} module (until you call @code{select-module}).
That's why you can access all the built-in procedures of Gauche
without saying @code{(use something)}. (@xref{Module inheritance}, for
the details about inheriting modules).
@c JP
Gaucheを起動した直後は、それがREPLであってもスクリプトファイルの実行であっても、
トップレベルは@code{user}モジュールになっています。@code{user}モジュールは
@code{gauche}モジュールを@emph{継承}しています。
また、ライブラリを読み込む際にも、(@code{select-module}が呼ばれるまでは)
トップレベルは@code{gauche}を継承したモジュールになっています。
これが、@code{(use something)}等といちいち書かないでも
Gaucheの組み込み手続きを使える理由です。
(モジュールの継承については@ref{Module inheritance}を参照してください)。
@c COMMON
@c EN
On the other hand, R7RS requires to be explicit about which namespaces
you'll be using, by @code{import} form, e.g. @code{(import (scheme base))}.
Besides, R7RS library must be explicitly enclosed by @code{define-library} form.
Before the first @code{import} form of a program, or outside of
@code{define-library}, is beyond R7RS world---the standard defines
nothings about it.
@c JP
一方、R7RSでは@code{import}フォームによってどの名前空間を利用するか明示することが
求められています(例: @code{(import (scheme base))})。
また、R7RSライブラリはそれぞれ@code{define-library}フォームで囲う必要があります。
プログラムの最初の@code{import}より前、あるいはライブラリの@code{define-library}の
外側は、R7RSの世界の外であり、標準では何も規定していません。
@c COMMON
@c EN
These facts let Gauche to set up appropriate ``world'',
and you can use R7RS code and traditional Gauche code transparently.
@c JP
Gaucheはこれを利用して、適切な「世界」を設定し、R7RSコードと既存のGaucheコードを
透過的に混ぜられるようにしています。
@c COMMON
@c EN
NB: As explained in @ref{Three forms of import},
R7RS @code{import} is rather different from Gauche
@code{import}, so we note the former @code{r7rs#import} and the latter
@code{gauche#import} in this section for clarity. When you write code
don't use prefixes @code{r7rs#} and @code{gauche#}; just write @code{import}.
@c JP
註:@ref{Three forms of import}で説明しますが、
R7RSの@code{import}はGaucheの@code{import}と異なります。この節では
区別が必要な時は前者を@code{r7rs#import}、後者を@code{gauche#import}と
表記しますが、実際のコードでは@code{r7rs#}や@code{gauche#}といったプレフィクスを
つけずに、単に@code{import}と書いてください。
@c COMMON
@c EN
@subheading Loading R7RS libraries
@c JP
@subheading R7RSライブラリをロードする
@c COMMON
@c EN
The @code{define-library} form is defined as a macro in @code{gauche} module;
it sets up R7RS environment before evaluating its contents.
So, when you load an R7RS library (either from Gauche code via @code{use}
form, or from R7RS code via @code{r7rs#import} form),
Gauche starts loading the file in @code{gauche} module, but immediately
see @code{define-library} form, and the rest is handled in R7RS
environment.
@c JP
@code{define-library}フォーム自身は、@code{gauche}モジュール内のマクロとして
定義されていて、R7RS環境を設定してその中身を評価するコードに展開されます。
(Gaucheコードから@code{use}を使うか、
R7RSコードから@code{r7rs#import}フォームを使うかして)R7RSライブラリをロードすると、
Gaucheはファイルの評価を@code{gauche}モジュール内で始めますが、すぐに
@code{define-library}フォームに当たるので、その中身はR7RS環境で処理されることになります。
@c COMMON
@c EN
Suppose you have an R7RS library @code{(mylib foo)} with the following code:
@c JP
以下のコードを持つ、R7RSライブラリ@code{(mylib foo)}があるとしましょう。
@c COMMON
@example
(define-library (mylib foo)
(import (scheme base))
(export snoc)
(begin
(define (snoc x y) (cons y x))))
@end example
@c EN
It should be saved as @file{mylib/foo.scm} in one of the directories in
@code{*load-path*}.
@c JP
このファイルは@code{*load-path*}にあるディレクトリのどれかの下に、
@file{mylib/foo.scm}という名前で保存されなければなりません。
@c COMMON
@c EN
From R7RS code, this library can be loaded by @code{r7rs#import}:
@c JP
R7RSコードからは、このライブラリは@code{r7rs#import}フォームでロードできます。
@c COMMON
@example
(import (mylib foo))
(snoc 1 2) @result{} (2 . 1)
@end example
@c EN
To use this library from Gauche code, concatenate elements of library
names by @code{.} to get a module name, and @code{use} it:
@c JP
Gaucheコードからこのライブラリを使うには、ライブラリ名の各要素を@code{.}で
つなげたものをモジュール名として、@code{use}します。
@c COMMON
@example
(use mylib.foo)
(snoc 1 2) @result{} (2 . 1)
@end example
@c EN
@subheading Loading Gauche libraries
@c JP
@subheading Gaucheライブラリのロード
@c COMMON
@c EN
To use Gauche library @code{foo.bar} from R7RS code,
split the module name by @code{.} to make a list for the name
of the library. For example, @code{gauche.lazy} module can be
used from R7RS as follows:
@c JP
Gaucheライブラリの@code{foo.bar}をR7RSコードから使うには、
モジュール名を@code{.}で区切った名前のリストをライブラリ名として使います。
例えば@code{gauche.lazy}モジュールは次のとおりR7RSから使えます。
@c COMMON
@example
(import (gauche lazy))
@end example
@c EN
For SRFI modules, R7RS implementations have a convention to
name it as @code{(srfi n)}, and Gauche follows it.
The following code loads srfi-1 and srfi-13 from R7RS code:
@c JP
SRFIモジュールについては、R7RSでは慣習的に@code{(srfi n)}という
名前を使うので、Gaucheもそれに合わせています。R7RSコードから
srfi-1とsrfi-13を使うには、次のようにします。
@c COMMON
@example
(import (srfi 1) (srfi 13))
@end example
@c EN
(It's not that Gauche treat @code{srfi} name specially; installation
of Gauche includes adapter libraries such as @file{srfi/1.scm}.)
@c JP
(これが動くのは、Gaucheが@code{srfi}という名前を特別扱いしているのではなく、
Gaucheをインストールした時に@code{srfi/1.scm}等のアダプタライブラリが作られているからです)
@c COMMON
@c EN
A tip: To use Gauche's built-in features (the bindings that are
available by default in Gauche code) from R7RS code, import
@code{(gauche base)} library (@pxref{Importing gauche built-ins}):
@c JP
ヒント: Gaucheの組み込みの機能 (Gaucheコードでは最初から使える束縛) を
R7RSコードから使いたい場合は、@code{(gauche base)}ライブラリをimportしてください
(@ref{Importing gauche built-ins}参照)。
@c COMMON
@example
(import (gauche base))
filter @result{} #<closure filter>
@end example
@c EN
@subheading Running R7RS scripts
@c JP
@subheading R7RSスクリプトの実行
@c COMMON
@c EN
R7RS scripts always begin with @code{import} form. However, @code{r7rs#import}
has a different syntax and semantics
from @code{gauche#import}---so we employ a trick.
@c JP
R7RSスクリプトは必ず@code{import}フォームで始まります。
しかし、@code{r7rs#import}は@code{gauche#import}と文法や意味が異なります。
そこで、ちょっとしたトリックを使っています。
@c COMMON
@c EN
When @code{gosh} is started, it loads the given script file
in @code{user} module. We have a separate @code{user#import} macro, which
examines its arguments and if it is R7RS import syntax, switch to the
@code{r7rs.user} module and run the @code{r7rs#import}. Otherwise, it
runs @code{gauche#import}. @xref{Three forms of import}, for the details.
@c JP
@code{gosh}がスクリプトファイルを読み込むのは@code{user}モジュールです。
そこには@code{user#import}というマクロが用意してあり、
そのマクロは引数を調べて、それがR7RSのimportの構文であれば
@code{r7rs.user}モジュールに切り替えて@code{r7rs#import}を実行し、
そうでなければ@code{gauche#import}を実行します。
詳しくは@ref{Three forms of import}を参照してください。
@c COMMON
@c EN
An example of R7RS script:
@c JP
R7RSスクリプトの例です:
@c COMMON
@example
(import (scheme base) (scheme write))
(display "Hello, world!\n")
@end example
@c EN
If you're already familiar with Gauche scripts, keep in mind that
R7RS program doesn't treat @code{main} procedure specially; it
just evaluates toplevel forms from top to bottom. So the following
script doesn't output anything:
@c JP
Gaucheスクリプトを見慣れている人は、R7RSプログラムが@code{main}手続きを
特別扱いしないことに気をつけてください。R7RSプログラムは、トップレベルフォームを
順に評価してゆくだけです。したがって次のスクリプトは何も表示しません:
@c COMMON
@example
(import (scheme base) (scheme write))
(define (main args)
(display "Hello, world!\n")
0)
@end example
@c EN
To access the command-line arguments in R7RS scripts, use
@code{command-line} in @code{(scheme process-context)} library
(@pxref{R7RS process context}, also @pxref{Command-line arguments}).
@c JP
R7RSスクリプトからコマンドライン引数を利用するには、
@code{(scheme process-context)}ライブラリの@code{command-line}を使います
(@ref{R7RS process context} および @ref{Command-line arguments}参照)。
@c COMMON
@c EN
@subheading Using R7RS REPL
@c JP
@subheading R7RS REPLを使う
@c COMMON
@c EN
When @code{gosh} is invoked with @code{-r7} option and no script file is
given, it enters an R7RS REPL mode. For the convenience, the following
modules (``libraries'', in R7RS term) are pre-loaded.
@c JP
@code{gosh}が@code{-r7}オプションつきで起動され、スクリプトファイルが
与えられていなかった場合は、R7RS REPLモードになります。
使いやすいように、以下のモジュール (R7RS用語では「ライブラリ」)は
自動的にロードされます。
@c COMMON
@example
(scheme base) (scheme case-lambda) (scheme char)
(scheme complex) (scheme cxr) (scheme eval)
(scheme file) (scheme inexact) (scheme lazy)
(scheme load) (scheme process-context) (scheme read)
(scheme repl) (scheme time) (scheme write)
@end example
@c EN
Besides, the history variables @code{*1}, @code{*2}, @code{*3},
@code{*1+}, @code{*2+}, @code{*3+}, @code{*e} and @code{*history}
are available (@xref{Working in REPL}, for the details of history variables).
@c JP
さらに、ヒストリ変数@code{*1}、@code{*2}、@code{*3}、
@code{*1+}、@code{*2+}、@code{*3+}、@code{*e} および
@code{*history}も使えます (ヒストリ変数の詳細については@ref{Working in REPL}参照)。
@c COMMON
@c EN
You can know you're in R7RS REPL by looking at the prompt, where
@code{gosh} shows the current module (@code{r7rs.user}):
@c JP
R7RS REPLにいることはプロンプトを見ればわかります。
現在のモジュールが@code{r7rs.user}となっているからです。
@c COMMON
@example
gosh[r7rs.user]>
@end example
@c EN
To switch Gauche REPL from R7RS REPL, import @code{(gauche base)} and
select @code{user} module using @code{select-module}:
@c JP
R7RS REPLからGauche REPLにスイッチするには、@code{(gauche base)}を
インポートして@code{select-module}を使って@code{user}モジュールを選びます。
@c COMMON
@example
gosh[r7rs.user]> (import (gauche base))
#<undef>
gosh[r7rs.user]> (select-module user)
#<undef>
gosh>
@end example
@c EN
(You can @code{(select-module gauche)} but that's usually not what you
want to do---changing @code{gauche} module can have unwanted side effects.)
@c JP
(@code{(select-module gauche)}とする手もありますが、おすすめはしません。
@code{gauche}モジュールの中を変えると思いがけない副作用が生じるかもしれませんから。)
@c COMMON
@c EN
When you're working on R7RS code in file and load it into R7RS REPL
(for example, if you're using Emacs Scheme mode, C-c C-l does the job),
make sure the file is in proper shape as R7RS; that is, the file
must start with appropriate @code{import} declarations, or
the file contains @code{define-library} form(s). If you load
file without those forms, it is loaded into Gauche's @code{user} module
no matter what your REPL's current module is,
and the definitions won't be visible from @code{r7rs.user} module
by default.
@c JP
R7RSコードをファイルに書きだし、R7RS REPLにそのファイルをロードしてインタラクティブに
開発を進めている場合 (例えばEmacsのSchemeモードなら、C-c C-lでファイルがロードできます)、
そのファイルがR7RSとして正しい形式になっていることを確認してください。
つまり、ファイルは@code{import}宣言で始まるか、@code{define-library}形式
から構成されるものでなければなりません。それ以外の、単にSchemeコードが並べて
書いてあるだけのファイルをロードした場合、
それはREPLでの現在のモジュールが何であるかにかかわらずGaucheの@code{user}モジュールに
読み込まれるので、@code{r7rs.user}モジュールからはデフォルトでは見えません。
@c COMMON
@c EN
@subheading Switching from Gauche REPL
@c JP
@subheading Gauche REPLからのスイッチ
@c COMMON
@c EN
By default, @code{gosh} enters Gauche REPL when no script file is given.
@xref{Working in REPL}, for detailed explanation of using REPL.
@c JP
デフォルトでは、@code{gosh}はスクリプトファイルが与えられなければGaucheのREPLに
入ります。REPLの説明は@ref{Working in REPL}を参照してください。
@c COMMON
@c EN
To switch Gauche REPL to R7RS REPL, simply use r7rs-style import;
@code{user#import} knows you want R7RS and make a switch.
@c JP
Gauche REPLからR7RS REPLにスイッチするには、
単にr7rsスタイルのimportを使うだけです。@code{user#import}は
あなたが欲しいのがR7RSであることを察知して環境を切り替えます。
@c COMMON
@example
gosh> (import (scheme base))
#<undef>
gosh[r7rs.user]>
@end example
@c EN
If you don't start @code{gosh} with @code{-r7} option, however,
only the libraries you given to @code{user#import} are loaded at
this moment.
@c JP
ただし、@code{gosh}を@code{-r7}オプションつきで起動していなければ、
この時点でロードされているのは@code{user#import}で指定したライブラリだけです。
@c COMMON
@c EN
If you want to switch the ``vanilla'' r7rs environment, that is, even
not loading @code{(scheme base)}, then you can use @code{r7rs}
module and directly select @code{r7rs.user}:
@c JP
もし、「すっぴん」のR7RS環境、つまり@code{(scheme base)}でさえロードされていない
環境へと切り替えたければ、@code{r7rs}モジュールをuseして
直接@code{r7rs.user}モジュールを選択します。
@c COMMON
@example
gosh> (use r7rs)
gosh> (select-module r7rs.user)
gosh[r7rs.user]>
@end example
@c EN
If you do this, the only
bindings visible initially are @code{import} and @code{define-library};
even @code{define} is undefined!
You have to manually do @code{(import (scheme base))} etc. to start
writing Scheme in this environment.
@c JP
こうして切り替えた場合、使えるフォームは@code{import}と@code{define-library}
だけです (@code{define}でさえ定義されていません!)
この環境でSchemeを書くには、まず @code{(import (scheme base))} 等として
束縛をインポートする必要があります。
@c COMMON
@node Three forms of import, , Traveling between two worlds back and forth, R7RS integration
@subsection Three import forms
@c NODE 3つのimport形式
@c EN
For historical reasons, Gauche has three @code{import} forms; the original
Gauche's @code{import}, R7RS @code{import}, and the hybrid @code{import}.
Usually it is clear that the code is written in traditional Gauche
or in R7RS, and usage of @code{import} is typically idiomatic, so there's
not much confusion in practice. Only when you talk about @code{import}
outside of code, you might need to specify which one you're talking.
The hybrid @code{import} is what we described @code{user#import} in
the previous section (@pxref{Traveling between two worlds back and forth}).
It understands both of Gauche's @code{import} and
R7RS @code{import}.
So what you really need to know is the first two.
@c JP
歴史的な事情から、Gaucheには@code{import}形式が3つあります。
もともとのGaucheの@code{import}、R7RSの@code{import}、
そしてハイブリッドの@code{import}です。
通常、コードを読み書きしている時は、それが伝統的なGaucheコードかR7RSコードかは
明確ですし、また@code{import}の使われ方はだいたい決まっているので、
現場で混乱が起きることはありません。ただ、コードの外で@code{import}について
話す場合は、どの@code{import}のことかをはっきりさせるのが良いでしょう。
ハイブリッドの@code{import}は前節で説明した@code{user#import}です
(@ref{Traveling between two worlds back and forth}参照)。
@code{user#import}は
Gaucheの@code{import}とR7RSの@code{import}の両方の文法を理解できるので、
実際に知る必要のあるのは最初の2つの形式です。
@c COMMON
@c EN
Gauche's module system design is inherited from STk, and we've been
used @code{import} for purely name-space level operation; that is,
it assumes the module you import from already exists in memory.
Loading a file that defines the module (if necessary) is
done by separate primitives, @code{require}. In most cases one file
defines one module, and using that module means @code{require} it then
@code{import} it (it's so common that Gauche has a macro for it---@code{use}).
However, separating those two sometimes comes handy when you need
some nontrivial hacks. @xref{Using modules}, for the details of
Gauche's @code{import}.
@c JP
Gaucheのモジュールシステム設計はSTkを継承していて、
@code{import}は純粋に名前空間の操作として使われています。
つまり、既にメモリ上に存在するモジュールをインポートするということです。
そのモジュールが定義されているファイルを、(必要なら)ロードするという
操作は別のプリミティブ@code{require}により実現されます。
典型的には、ひとつのファイルがひとつのモジュールを定義していて、
そのモジュールを使うにはまずファイルを@code{require}し、
次にモジュールを@code{import}するということになります
(これはGaucheでは頻繁に出てくるので、@code{use}というマクロが定義されているくらいです)。
ファイルのロードとモジュールのインポートが分かれていることは、
たまに変わったハックが必要とされる時に役に立ちます。
Gaucheの@code{import}については@ref{Using modules}を参照してください。
@c COMMON
@c EN
R7RS leaves out the relation between modules (libraries) and files
in order to give implementation freedom. If necessary, its @code{import}
must load a file implicitly and transparently. So R7RS's @code{import}
is semantically Gauche's @code{use}.
@c JP
R7RSは実装に選択の余地を与えるため、モジュール(ライブラリ)とファイルの関係は
敢えて規定していません。R7RSの@code{import}は、
必要ならば暗黙のうちに、透過的にファイルをロードすることが期待されています。
つまり、R7RSの@code{import}はGaucheの@code{use}と意味的に同じと考えられます。
@c COMMON
@c EN
The hybrid @code{import} only appears at the beginning of the Scheme
scripts. It finds out whether the script is in the traditional Gauche
code or in the R7RS code. @xref{Traveling between two worlds back and forth}, for the details.
@c JP
ハイブリッド@code{import}はSchemeスクリプトの最初にのみ現れて、
実行されるスクリプトが伝統的なGaucheコードであるかR7RSコードであるかを
判断します。詳細は@ref{Traveling between two worlds back and forth}を参照してください。
@c COMMON
@c EN
Now we'll explain R7RS @code{import}:
@c JP
ではR7RSの@code{import}を説明します:
@c COMMON
@defspec import import-spec @dots{}
[R7RS]
@c EN
Imports libraries specified by @var{import-spec}s. What R7RS calls
libraries are what Gauche calls modules; they're the same thing.
@c JP
@var{import-spec}で指定されるライブラリをインポートします。
R7RSでいうライブラリは、Gaucheがモジュールと呼んできたものです。両者は同じものです。
@c COMMON
@c EN
R7RS libraries are named by a list of symbols or integers,
e.g. @code{(scheme base)} or @code{(srfi 1)}.
It is translated to Gauche's module name by joining the symbols
by periods; so, R7RS @code{(scheme base)} is Gauche's @code{scheme.base}.
Conversely, Gauche's @code{data.queue} is available as
@code{(data queue)} in R7RS. To use those two libraries,
R7RS program needs this form at the beginning.
@c JP
R7RSライブラリの名前はシンボルか整数のリストで表されます。
例: @code{(scheme base)}、@code{(srfi 1)}。
この名前は、ピリオドを挟んでシンボル名をつなげることで、Gaucheのモジュール名へと
変換されます。つまり、R7RSの@code{(scheme base)}はGaucheからは@code{scheme.base}
モジュールとして扱えます。逆にGaucheの@code{data.queue}モジュールは
R7RSからは@code{(data queue)}ライブラリとして扱えます。
R7RSプログラムからこれら二つのライブラリを使うには、プログラムの最初に
次のように記します。
@c COMMON
@example
(import (scheme base)
(data queue))
@end example
@c EN
It works just like Gauche's @code{use} forms; that is, if the named
module doesn't exist in the current process, it loads the file; then
the module's exported bindings become visible from the current module.
@c JP
これはGaucheで@code{use}フォームを使うのと同じです。つまり、もし
その名前を持つモジュールが現在のプロセス内に無ければまずファイルをロードし、
それからモジュールがexportしている束縛を現在のモジュールから見えるようにします。
@c COMMON
@example
(use scheme.base)
(use data.queue)
@end example
@c EN
(You may wonder what if R7RS library uses symbols with periods in them.
Frankly, we haven't decided yet. It'll likely be that we use some
escaping mechanism; for the time being you'd want to stick with
alphanumeric characters and hyphens as possible.)
@c JP
(勘の良い読者は、R7RSのライブラリがピリオドを中に含むシンボルを名前に使っていたら
どうなるのか疑問に思ったことでしょう。正直なところ、まだどうするか決めていません。
多分、何らかのエスケープ機構を用意することになると思いますが、
今のところ、できる限りモジュール名にはアルファベット、数字、ハイフンだけを
使うようにしておいて下さい。)
@c COMMON
@c EN
Just like Gauche's @code{use}, you can select which symbols to be
imported (or not imported), rename specific symbols, or add
prefix to all imported symbols. The formal syntax
of R7RS import syntax is as follows:
@c JP
R7RSの@code{import}フォームは、
Gaucheの@code{use}と同様、どのシンボルをimportするか/しないかを指定したり、
名前を変えてimportしたりプレフィクスを付加することができます。
R7RSの@code{import}の正式な構文は次の通りです。
@c COMMON
@smallexample
<import declaration> : (import <import-set> <import-set> ...)
<import-set> : <library-name>
| (only <import-set> <identifier> <identifier> ...)
| (except <import-set> <identifier> <identifier> ...)
| (prefix <import-set> <identifier>)
| (rename <import-set>
(<identifier> <identifier>)
(<identifier> <identifier>) ...)
<library-name> : (<identifier-or-base-10-integer>
<identifier-or-base-10-integer> ...)
@end smallexample
@end defspec
@node R7RS small language, R7RS large, R7RS integration, Library modules - R7RS standard libraries
@section R7RS small language
@c NODE R7RS small language
@menu
* R7RS library form::
* R7RS base library:: @code{scheme.base}
* R7RS case-lambda:: @code{scheme.case-lambda}
* R7RS char library:: @code{scheme.char}
* R7RS complex numbers:: @code{scheme.complex}
* R7RS cxr accessors:: @code{scheme.cxr}
* R7RS eval:: @code{scheme.eval}
* R7RS file library:: @code{scheme.file}
* R7RS inexact numbers:: @code{scheme.inexact}
* R7RS lazy evaluation:: @code{scheme.lazy}
* R7RS load:: @code{scheme.load}
* R7RS process context:: @code{scheme.process-context}
* R7RS read:: @code{scheme.read}
* R7RS repl:: @code{scheme.repl}
* R7RS time:: @code{scheme.time}
* R7RS write:: @code{scheme.write}
* R5RS compatibility:: @code{scheme.r5rs}
@end menu
@node R7RS library form, R7RS base library, R7RS small language, R7RS small language
@subsection R7RS library form
@c NODE R7RSライブラリ形式
@c EN
R7RS libraries are defined by @code{define-library} form.
In R7RS view, @code{define-library} form itself does not belong
to a Scheme code---it exists outside of the Scheme world.
It defines the boundary of
R7RS Scheme; inside @code{define-library} there is R7RS world,
but outside, it's not a business of R7RS.
For example, you can't generate
@code{define-library} by a macro, within R7RS specification.
In Gauche, we implement R7RS world inside Gauche world;
@code{define-library} itself is interpreted in the Gauche world.
In fact, @code{define-library} @emph{is} a Gauche macro.
However, if you're writing portable R7RS code, you should forget
how @code{define-library} is implemented, and do not put anything
outside of @code{define-library} form.
@c JP
R7RSのライブラリは@code{define-library}フォームで定義されます。
R7RSの観点では@code{define-library}フォーム自体はSchemeコードではありません。
それ自身はScheme世界の外にあります。@code{define-library}フォームが、
R7RS Schemeの境界となるのです。その内側はR7RSの世界であり、
その外側に関してR7RSは関知しません。例えば、R7RSの仕様の範囲内では、
@code{define-library}フォーム自体をマクロで生成する、ということはできません。
Gaucheでは、R7RSの世界をGaucheの世界の中に作っています。
@code{define-library}自体はGauche世界で解釈されます。実際、
@code{define-library}はGaucheのマクロとして実装されています。
けれどもR7RSのコードを書く際には、@code{define-library}がどう実装されているかは
気にする必要はありません。また、@code{define-library}の外側には
何も書かないようにしてください。
@c COMMON
@defmac define-library library-name library-decl @dots{}
[R7RS]
@c EN
Defines a library @var{library-name}, which is a list of
symbols or base-10 integer:
@c JP
@var{library-name}という名前を持つライブラリを定義します。
@var{library-name}はシンボルもしくは10進整数のリストです。
@c COMMON
@smallexample
<library-name> : (<identifier-or-base-10-integer>
<identifier-or-base-10-integer> ...)
@end smallexample
@c EN
Library declarations @var{library-decl}
can be export declarations, import declarations,
@code{begin}-list of Scheme code,
include forms, or @code{cond-expand} forms.
@c JP
ライブラリ宣言@var{library-decl}は、エクスポート宣言、
インポート宣言、@code{begin}に囲まれたSchemeコード、
インクルードフォーム、あるいは@code{cond-expand}フォームです。
@c COMMON
@smallexample
<library-decl> : (export <export-spec> @dots{})
| <import declaration>
| (begin <command-or-definition> @dots{})
| (include <string> <string2> @dots{})
| (include-ci <string> <string2> @dots{})
| (include-library-declarations
<string> <string2> @dots{})
| (cond-expand <cond-expand-clause>
<cond-expand-clause2> @dots{})
| (cond-expand <cond-expand-clause>
<cond-expand-clause2> @dots{}
(else <library-decl> @dots{}))
@end smallexample
@c EN
The @code{export} declaration is the same Gauche's @code{export}
form; @pxref{Using modules}.
@c JP
@code{export}宣言はGaucheの@code{export}フォームと同じです。
@ref{Using modules}参照。
@c COMMON
@c EN
The @code{import} declaration is R7RS's @code{import} form,
described in @ref{Three forms of import}.
@c JP
@code{import}宣言はR7RSの@code{import}フォームで、
@ref{Three forms of import}で説明しています。
@c COMMON
@c EN
The @code{include} and @code{include-ci} declarations
are the same as Gauche's; @pxref{Inclusions}.
Note that Gauche allows any code to be included---the content of
the named file is simply wrapped with @code{begin} and
substituted with these forms---but in R7RS definition,
what you include must contain only Scheme code
(not one of the library declarations or @code{define-library} form).
@c JP
@code{include}と@code{include-ci}フォームはGaucheのそれと同じです。
@ref{Inclusions}参照。Gaucheはインクルードされるコードの中身については
感知せず、単にその中身を@code{begin}で囲んで元のフォームと
置き換えるだけです。けれどもR7RSでは、これらのフォームが読み込むファイルには
Schemeコードのみが許されます(例えば@code{define-library}フォームや
他のライブラリ宣言フォームはだめです)。
@c COMMON
@c EN
The @code{include-library-declarations} declaration works like @code{include},
but the content of the read file is interpreted
as library declarations instead of Scheme code.
@c JP
@code{include-library-declarations}宣言は@code{include}宣言と
同じように動作しますが、読み込まれるファイルの中身はSchemeコードではなく
ライブラリ宣言として解釈されます。
@c COMMON
@c EN
The @code{cond-expand} declaration is also the same as Gauche's;
@pxref{Feature conditional}. When used directly below
@code{define-library}, it must expands to one of the
library declarations.
@c JP
@code{cond-expand}宣言もGaucheのそれと同じです。
@ref{Feature conditional}参照。
但し、@code{define-library}の直下で使われた場合は、
展開結果もライブラリ宣言になっている必要があります。
@c COMMON
@end defmac
@node R7RS base library, R7RS case-lambda, R7RS library form, R7RS small language
@subsection @code{scheme.base} - R7RS base library
@c NODE R7RS基本ライブラリ, @code{scheme.base} - R7RS基本ライブラリ
@deftp {Module} scheme.base
@mdindex scheme.base
@c EN
Exports bindings of R7RS @code{(scheme base)} library. From R7RS programs,
those bindings are available by @code{(import (scheme base))}.
@c JP
R7RSの@code{(scheme base)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は@code{(import (scheme base))}とすることで
使えます。
@c COMMON
@end deftp
@c EN
@subheading Bindings common to Gauche's built-ins
@c JP
@subheading Gaucheの組み込み束縛と共通なもの
@c COMMON
@c EN
The following syntaxes and procedures are the same as Gauche's
builtins:
@c JP
以下の構文の手続きはGaucheの組み込みのものと同じです。
@c COMMON
@table @asis
@item Primitive expression types
@example
quote if include include-ci lambda
@end example
@item Derived expression types
@example
cond case and or when unless cond-expand let let* letrec letrec*
let-values let*-values begin do make-parameter parameterize
guard quasiquote unquote unquote-splicing case-lambda
@end example
@item Macros
@example
let-syntax letrec-syntax syntax-rules syntax-error define-syntax
@end example
@item Variable definitions
@example
define define-values
@end example
@item Record type definitions
@example
define-record-type
@end example
@item Equivalence predicates
@example
eqv? eq? equal?
@end example
@item Numbers
@example
number? complex? real? rational? integer? exact? exact-integer?
= < > <= >= zero? positive? negative? odd? even? max min + * - / abs
floor/ floor-quotient floor-remainder
truncate/ truncate-quotient truncate-remainder
quotient modulo remainder gcd lcm numerator denominator
floor ceiling truncate round rationalize square exact-integer-sqrt
expt inexact exact number->string string->number
@end example
@item Booleans
@example
not boolean? boolean=?
@end example
@item Pairs and lists
@example
pair? cons car cdr set-car! set-cdr! caar cadr cdar cddr null? list?
make-list list length append reverse list-tail list-ref list-set!
memq memv member assq assv assoc list-copy
@end example
@item Symbols
@example
symbol? symbol=? symbol->string string->symbol
@end example
@item Characters
@example
char? char=? char<? char>? char<=? char>=? char->integer integer->char
@end example
@item Strings
@example
string? make-string string string-length string-ref string-set!
string=? string<? string>? string<=? string>=? substring string-append
string->list list->string string-copy string-copy! string-fill!
@end example
@item Vectors
@example
vector? make-vector vector vector-length vector-ref vector-set!
vector->list list->vector vector->string string->vector
vector-copy vector-copy! vector-append vector-fill!
@end example
@item Control features
@example
procedure? apply map call-with-current-continuation call/cc
values call-with-values dynamic-wind
@end example
@item Exception
@example
error
@end example
@item Environments and evaluation
@example
scheme-report-environment null-environment
@end example
@item Input and output
@example
input-port? output-port? port? current-input-port current-output-port
current-error-port close-port close-input-port close-output-port
open-input-string open-output-string get-output-string
read-char peek-char read-line eof-object? eof-object char-ready?
newline write-char
@end example
@end table
@c EN
@subheading Bytevector utilities
@c JP
@subheading バイトベクタユーティリティ
@c COMMON
@c EN
R7RS's bytevectors are the same as Gauche's u8vectors.
The following procedures are the same as @code{gauche.uvector}'s
(@pxref{Bytevector compatibility}).
@c JP
R7RSのバイトベクタはGaucheのu8vectorと同じです。
以下の手続きは@code{gauche.uvector}のものと同じです。
(@ref{Bytevector compatibility}参照)。
@c COMMON
@example
bytevector bytevector? make-bytevector
bytevector-length bytevector-u8-ref bytevector-u8-set!
bytevector-copy bytevector-copy! bytevector-append
@end example
@c EN
And the following procedures are the same as @code{gauche.unicode}'s
(@pxref{Unicode transfer encodings}).
@c JP
そして以下の手続きは@code{gauche.unicode}のものと同じです。
(@ref{Unicode transfer encodings}参照)。
@c COMMON
@example
utf8->string string->utf8
@end example
@c EN
@subheading Control features
@c JP
@subheading 制御機能
@c COMMON
@defun string-map proc str @dots{}
@defunx string-for-each proc str @dots{}
[R7RS base]
@c MOD scheme.base
@c EN
These take different arguments from
@code{string-map} and @code{string-for-each} in SRFI-13
(@pxref{SRFI-13 String mapping}),
so provided only in @code{scheme.base} module
to avoid confusion.
If you pass only one string argunemt, however, it works exactly
the same way in both @code{srfi-13} and @code{scheme.base}.
@c JP
これらの手続きはSRFI-13の@code{string-map}及び@code{string-for-each}
(@ref{SRFI-13 String mapping}参照)とは異なる引数を取るので、
混乱を避けるため@code{scheme.base}でのみ提供されます。
但し、文字列引数をひとつだけ渡す場合は、
@code{srfi-13}でも@code{scheme.base}でも全く同様に動作します。
@c COMMON
@end defun
@defun with-exception-handler handler thunk
[R7RS base]
@c MOD scheme.base
@c EN
@var{handler} is evaluated in the dynamic environment of the call to
@var{handler}, except that the current exception handler is that in
place for the call to @code{with-exception-handler}.
If the exception is not continuable, it is reraised after evaluating
@var{handler} and handled by the exception handler in place for the
call to @code{with-exception-handler}.
@c JP
@var{handler}は、@var{handler}呼び出し時の動的環境で評価されます。
ただし、@var{handler}内における例外ハンドラは、
@code{with-exception-handler}呼び出し時の例外ハンドラになります。
例外が継続不可能な場合、@var{handler}の評価後にさらに例外が発生し、それは
@code{with-exception-handler}呼び出し時の例外ハンドラで処理されます。
@c COMMON
@c EN
This slightly differs from Gauche's built-in @code{with-exception-handler},
which calls @var{handler} without replacing the current exception handler.
@xref{Handling exceptions}, for the details.
@c JP
これはGaucheの組み込みの@code{with-exception-handler}と微妙に異なります。
組み込みの方は、現在の例外ハンドラを置き換えずに@var{handler}を呼び出します。
詳しくは@ref{Handling exceptions}を参照してください。
@c COMMON
@end defun
@defun raise obj
@defunx raise-continuable obj
[R7RS base]
@c MOD scheme.base
@c EN
Gauche's @code{raise} may return if @var{obj} isn't a
@code{<serious-condition>}.
Distinguishing continuable and noncontinuable exception throw by the
procedure has an issue when your exception handler wants to reraise
the condition (you don't know if the original condition is raised
by @code{raise} or @code{raise-continuable}!). Yet R7RS adopted
that model, so we compel.
R7RS @code{raise} is a wrapper of Gauche's @code{raise},
which throws an error if Gauche's @code{raise} returns.
R7RS @code{raise-continuable} is currently just an alias of
Gauche's @code{raise}---as long as you don't pass
@code{<serious-condition>}, it may return. It is not exactly
R7RS conformant---it won't return if you pass @code{<serious-condition>}
or object of one of its subclasses (e.g. @code{<error>}), but
it's weired to expect returning from raising @code{<error>}, isn't it?
@c JP
Gaucheの@code{raise}は、@var{obj}が@code{<serious-condition>}でなければ、
例外ハンドラから戻って来ることを許しています。
継続可能な例外報告と継続不可能な例外報告を手続きで区別するのは、
例外ハンドラが渡されたコンディションを再び投げる場合に問題となります
(元のコンディションが@code{raise}で投げられたのか@code{raise-continuable}で
投げられたのか知る術がない!)。
しかしR7RSではそのモデルを採用したため、何とか合わせようとしています。
R7RS版の@code{raise}はGaucheの@code{raise}のラッパーで、
Gaucheの@code{raise}から戻って来たらエラーを投げるようにしています。
R7RSの@code{raise-continuable}は今のところGaucheの@code{raise}の
別名になっています。@code{<serious-condition>}を渡さなければ、
戻ってくることが可能です。R7RS準拠でないのは、
@code{<serious-condition>}かそのサブクラスのオブジェクト(例えば@code{<error>})を
@code{raise-continuable}に渡した場合ですが、
@code{<error>}を投げて戻って来ることを期待するというのはちょっとおかしいですよね。
@c COMMON
@end defun
@defun error-object? exc
[R7RS base]
@c MOD scheme.base
@c EN
Defined as @code{(condition-has-type? exc <error>))}
@c JP
@code{(condition-has-type? exc <error>))}として定義されています。
@c COMMON
@end defun
@defun error-object-message exc
[R7RS base]
@c MOD scheme.base
@c EN
If @var{exc} is a @code{<message-condition>},
returns its @code{message-prefix} slot;
otherwise, returns an empty string.
@c JP
@var{exc}が@code{<message-condition>}であれば
@code{message-prefix}の内容を、持っていなければ空文字列を返します。
@c COMMON
@end defun
@defun error-object-irritants exc
[R7RS base]
@c MOD scheme.base
@c EN
If @var{exc} is a @code{<message-condition>},
returns its @code{message-args} slot;
otherwise, returns an empty string.
@c JP
@var{exc}が@code{<message-condition>}であれば
@code{message-args}の内容を、持っていなければ空文字列を返します。
@c COMMON
@end defun
@defun read-error? exc
[R7RS base]
@c MOD scheme.base
@c EN
Defined as @code{(condition-has-type? e <read-error>))}.
@c JP
@code{(condition-has-type? e <read-error>))}として定義されています。
@c COMMON
@end defun
@defun file-error? exc
[R7RS base]
@c MOD scheme.base
@c EN
At this moment, Gauche doesn't have distinct @code{<file-error>} condition,
but most file errors are thrown as one of @code{<system-error>}s.
This procedure checks error code of @code{<system-error>} and
returns @code{#t} if the error is likely to be related to the filesystem.
@c JP
今のところ、Gaucheは独立した@code{<file-error>}コンディションを持っていませんが、
ファイルエラーのほとんどは@code{<system-error>}として投げられます。
この手続きは@code{<system-error>}のエラーコードを調べ、ファイルに起因するエラー
の場合に@code{#t}を返すようにしています。
@c COMMON
@end defun
@c EN
@subheading Input and output
@c JP
@subheading 入出力
@c COMMON
@defun textual-port? port
@defunx binary-port? port
[R7RS base]
@c MOD scheme.base
@c EN
Gauche's port can handle both, so these are equivalent to @code{port?}.
@c JP
Gaucheのポートはどちらも扱えるので、これらの手続きは@code{port?}と等価です。
@c COMMON
@end defun
@defun input-port-open? iport
@defunx output-port-open? oport
[R7RS base]
@c MOD scheme.base
@c EN
Checks whether @var{iport}/@var{oport} is an input/output port @emph{and}
it is not closed.
@c JP
@var{iport}/@var{oport}がそれぞれ入力/出力ポートであり、かつクローズされていなければ
@code{#t}を返します。
@c COMMON
@end defun
@defun open-input-bytevector u8vector
@defunx open-output-bytevector
@defunx get-output-bytevector port
[R7RS base]
@c MOD scheme.base
@c EN
These are basically the same as @code{open-input-uvector},
@code{open-output-uvector} and @var{get-output-uvector}
in @code{gauche.vport} (@pxref{Virtual ports}), except that
R7RS procedures only deal with @code{<u8vector>}.
@c JP
これらは基本的に@code{gauche.vport}の
@code{open-input-uvector}、
@code{open-output-uvector}、@var{get-output-uvector}
とそれぞれ同じです(@ref{Virtual ports}参照)。
但しR7RS版は@code{<u8vector>}しか受け付けません。
@c COMMON
@end defun
@defun read-u8 :optional iport
@defunx peek-u8 :optional iport
@defunx u8-ready? :optional iport
[R7RS base]
@c MOD scheme.base
@c EN
These are aliases to @code{read-byte}, @code{peek-byte} and @code{byte-ready?},
respectively.
@c JP
それぞれ@code{read-byte}、@code{peek-byte}、@code{byte-ready?}と
同じです。
@c COMMON
@end defun
@defun read-bytevector size :optional iport
[R7RS base]
@c MOD scheme.base
@c EN
Equivalent to @code{(read-uvector <u8vector> size iport)}.
@c JP
@code{(read-uvector <u8vector> size iport)}と等価です。
@c COMMON
@xref{Uvector block I/O}.
@end defun
@defun read-bytevector! bv :optional iport start end
[R7RS base]
@c MOD scheme.base
@c EN
An alias to @code{read-uvector!}. @xref{Uvector block I/O}.
@c JP
@code{read-uvector!}の別名です。@ref{Uvector block I/O}参照。
@c COMMON
@end defun
@defun write-u8
[R7RS base]
@c MOD scheme.base
@c EN
An alias to @code{write-byte}.
@c JP
@code{write-byte}の別名です。
@c COMMON
@end defun
@defun write-bytevector bv :optional oport start end
[R7RS base]
@c MOD scheme.base
@c EN
Equivalent to @code{write-uvector}. @xref{Uvector block I/O}.
@c JP
@code{write-uvector}と同じです。@ref{Uvector block I/O}参照。
@c COMMON
@end defun
@defun flush-output-port :optional oport
[R7RS base]
@c MOD scheme.base
@c EN
An alias to @code{flush}.
@c JP
@code{flush}の別名です。
@c COMMON
@end defun
@defun features
[R7RS base]
@c MOD scheme.base
@c EN
Returns a list of symbols of supported feature identifiers,
recognized by @code{cond-expand} (@pxref{Feature conditional}).
@c JP
サポートされている@code{feature-identifier}のリストを返します。
@code{feature-identifier}については、@code{cond-expand}を参照してください
(@ref{Feature conditional}参照)。
@c COMMON
@end defun
@node R7RS case-lambda, R7RS char library, R7RS base library, R7RS small language
@subsection @code{scheme.case-lambda} - R7RS case-lambda
@c NODE R7RS case-lambda, @code{scheme.case-lambda} - R7RS case-lambda
@deftp {Module} scheme.case-lambda
@mdindex scheme.case-lambda
@c EN
Exports bindings of R7RS @code{(scheme case-lambda)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme case-lambda))}.
The only binding exported from this module is @code{case-lambda},
and it is the same as Gauche's built-in @code{case-lambda};
@pxref{Making procedures} for the details.
@c JP
R7RSの@code{(scheme case-lambda)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme case-lambda))}とすることで使えます。
このモジュールからエクスポートされるのは@code{case-lambda}だけで、
Gauche組み込みの@code{case-lambda}そのものです。
詳しくは@ref{Making procedures}を参照してください。
@c COMMON
@end deftp
@node R7RS char library, R7RS complex numbers, R7RS case-lambda, R7RS small language
@subsection @code{scheme.char} - R7RS char library
@c NODE R7RS文字ライブラリ, @code{scheme.char} - R7RS文字ライブラリ
@deftp {Module} scheme.char
@mdindex scheme.char
@c EN
Exports bindings of R7RS @code{(scheme char)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme char))}.
@c JP
R7RSの@code{(scheme char)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme char))}とすることで使えます。
@c COMMON
@end deftp
@c EN
The following procedures are the same as Gauche's builtin procedures;
@pxref{Characters}.
@c JP
以下の手続きはGaucheの組み込みのものと同じです。@ref{Characters}参照。
@c COMMON
@example
char-alphabetic? char-ci<=? char-ci<? char-ci=? char-ci>=? char-ci>?
char-downcase char-foldcase char-lower-case? char-numeric?
char-upcase char-upper-case? char-whitespace?
@end example
@c EN
The following procedures are the same as the ones provided
in @code{gauche.unicode} module (@pxref{Full string case conversion}).
They use full case folding by Unicode standard (e.g. taking into
account of German eszett).
@c JP
以下の手続きは@code{gauche.unicode}で提供されているものと同じです
(@ref{Full string case conversion}参照)。Unicodeで定義されている
フルセットの大文字小文字変換を使います(例えばドイツ語のエスツェットが考慮されます)。
@c COMMON
@example
string-ci<=? string-ci<? string-ci=? string-ci>=? string-ci>?
string-downcase string-foldcase string-upcase
@end example
@defun digit-value c
[R7RS char]
@c MOD scheme.char
@c EN
If @var{c} is a character with @code{Nd} general category---that is,
if it represents a decimal digit---this procedure returns the value
the character represents. Otherwise it returns @code{#f}.
@c JP
@var{c}が@code{Nd}カテゴリの文字、つまり十進数の数字を表す文字であれば、
その文字が表す値を返します。それ以外の場合は@code{#f}を返します。
@c COMMON
@example
(digit-value #\3) @result{} 3
(digit-value #\z) @result{} #f
@end example
@c EN
Note that Unicode defines about two dozen sets of digit characters.
@c JP
Unicodeには20種類以上の数字が定義されています。
@c COMMON
@example
(digit-value #\x11068) @result{} 2
@end example
@c EN
Gauche's built-in procedure @code{digit->integer} has more general
interface (@pxref{Characters}).
@c JP
Gauche組み込みの@code{digit->integer}はより汎用的なインタフェースを
持っています(@ref{Characters}参照)。
@c COMMON
@example
(digit-value c) @equiv{} (digit->integer c 10 #t)
@end example
@end defun
@node R7RS complex numbers, R7RS cxr accessors, R7RS char library, R7RS small language
@subsection @code{scheme.complex} - R7RS complex numbers
@c NODE R7RS複素数, @code{scheme.complex} - R7RS複素数
@deftp {Module} scheme.complex
@mdindex scheme.complex
@c EN
Exports bindings of R7RS @code{(scheme complex)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme complex))}.
@c JP
R7RSの@code{(scheme complex)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme complex))}とすることで使えます。
@c COMMON
@c EN
This module provides the following bindings, all of which are
Gauche built-in (@pxref{Numerical conversions}).
@c JP
このモジュールは以下の束縛を提供します。
全てGaucheの組み込みです(@ref{Numerical conversions}参照)。
@c COMMON
@example
angle imag-part magnitude make-polar make-rectangular real-part
@end example
@end deftp
@node R7RS cxr accessors, R7RS eval, R7RS complex numbers, R7RS small language
@subsection @code{scheme.cxr} - R7RS cxr accessors
@c NODE R7RS cxrアクセサ, @code{scheme.cxr} - R7RS cxrアクセサ
@deftp {Module} scheme.cxr
@mdindex scheme.cxr
@c EN
Exports bindings of R7RS @code{(scheme cxr)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme cxr))}.
@c JP
R7RSの@code{(scheme complex)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme complex))}とすることで使えます。
@c COMMON
@c EN
This module provides the following bindings, all of which are
Gauche built-in (@pxref{List accessors and modifiers}).
@c JP
このモジュールは以下の束縛を提供します。
全てGaucheの組み込みです(@ref{List accessors and modifiers}参照)。
@c COMMON
@example
caaar caadr cadar caddr cdaar cdadr cddar cdddr caaaar caaadr caadar
caaddr cadaar cadadr caddar cadddr cdaaar cdaadr cdadar cdaddr cddaar
cddadr cdddar cddddr
@end example
@end deftp
@node R7RS eval, R7RS file library, R7RS cxr accessors, R7RS small language
@subsection @code{scheme.eval} - R7RS eval
@c NODE R7RS eval, @code{scheme.eval} - R7RS eval
@deftp {Module} scheme.eval
@mdindex scheme.eval
@c EN
Exports bindings of R7RS @code{(scheme eval)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme eval))}.
@c JP
R7RSの@code{(scheme eval)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme eval))}とすることで使えます。
@c COMMON
@end deftp
@defun eval expr environment
[R7RS eval]
@c MOD scheme.eval
@c EN
This is the same as Gauche's built-in @code{eval} (@pxref{Eval and repl}).
@c JP
Gauche組み込みの@code{eval}と同じです (@ref{Eval and repl}参照)。
@c COMMON
@end defun
@defun environment import-list @dots{}
[R7RS eval]
@c MOD scheme.eval
@c EN
This is R7RS way to create an environment specifier suitable to pass
to @code{eval}. In Gauche, an environment specifier is just a
module object.
@c JP
これはR7RSで@code{eval}に渡せる環境指定子を作る手段です。Gaucheでは、
環境指定子は単なるモジュールオブジェクトです。
@c COMMON
@c EN
The argument is the same as what @code{r7rs#import} takes.
This procedure creates an empty environment (as a fresh anonymous module;
see @code{make-module} in @ref{Module introspection}, for the details),
then imports the bindings as specified by @var{import-list}s.
The following example creates an environment that includes
@code{scheme.base} bindings plus @code{select-module} syntax from Gauche.
@c JP
引数は@code{r7rs#import}が取るものと同じです。
この手続きはまず空の環境(=無名のモジュールです。
詳しくは@ref{Module introspection}の@code{make-module}参照)を作り、
それから@var{import-list}に指定される束縛をインポートします。
以下の例は、@code{scheme.base}及びGauche組み込みの@code{select-module}を
インポートした環境を作ります。
@c COMMON
@example
(environment
'(scheme base)
'(only (gauche base) select-module))
@result{} #<module #f> ; an anonymous module
@end example
@end defun
@node R7RS file library, R7RS inexact numbers, R7RS eval, R7RS small language
@subsection @code{scheme.file} - R7RS file library
@c NODE R7RSファイルライブラリ, @code{scheme.file} - R7RSファイルライブラリ
@deftp {Module} scheme.file
@mdindex scheme.file
@c EN
Exports bindings of R7RS @code{(scheme file)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme file))}.
@c JP
R7RSの@code{(scheme file)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme file))}とすることで使えます。
@c COMMON
@end deftp
@c EN
The following bindings provided in this module are
Gauche built-in (@pxref{File ports}, and @ref{File stats}).
@c JP
次に挙げる束縛はGaucheの組み込みと同じです
(@ref{File ports}及び@ref{File stats}参照)。
@c COMMON
@example
call-with-input-file call-with-output-file
file-exists?
open-input-file open-output-file
with-input-from-file with-output-to-file
@end example
@c EN
The following binding is the same as one in @code{file.util}
(@pxref{File operations}).
@c JP
以下の束縛は@code{file.util}で提供されるものと同じです
(@ref{File operations}参照)。
@c COMMON
@example
delete-file
@end example
@defun open-binary-input-file filename
@defunx open-binary-output-file filename
[R7RS file]
@c MOD scheme.file
@c EN
In Gauche, ports are both textual and binary at the same time,
so these R7RS procedures
are just aliases of @code{open-input-file} and @code{open-output-file},
respectively. @xref{File ports}.
@c JP
Gaucheでは、ポートは同時にテキストポートでもバイナリポートでもあるので、
これらのR7RS手続きは単に
@code{open-input-file}と@code{open-output-file}の別名になっています。
@ref{File ports}参照。
@c COMMON
@end defun
@node R7RS inexact numbers, R7RS lazy evaluation, R7RS file library, R7RS small language
@subsection @code{scheme.inexact} - R7RS inexact numbers
@c NODE R7RS不正確数, @code{scheme.inexact} - R7RS不正確数
@deftp {Module} scheme.inexact
@mdindex scheme.inexact
@c EN
Exports bindings of R7RS @code{(scheme inexact)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme inexact))}.
@c JP
R7RSの@code{(scheme inexact)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme inexact))}とすることで使えます。
@c COMMON
@c EN
This module provides the following bindings, all of which are
Gauche built-in (@pxref{Arithmetics}, and @ref{Numerical predicates}).
@c JP
このモジュールは以下の束縛を提供します。全てGaucheの組み込みです
(@ref{Arithmetics}及び@ref{Numerical predicates}参照)。
@c COMMON
@example
acos asin atan cos exp finite? infinite? log nan? sin sqrt tan
@end example
@end deftp
@node R7RS lazy evaluation, R7RS load, R7RS inexact numbers, R7RS small language
@subsection @code{scheme.lazy} - R7RS lazy evaluation
@c NODE R7RS遅延評価, @code{scheme.lazy} - R7RS遅延評価
@deftp {Module} scheme.lazy
@mdindex scheme.lazy
@c EN
Exports bindings of R7RS @code{(scheme lazy)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme lazy))}.
@c JP
R7RSの@code{(scheme inexact)}ライブラリの束縛をエクスポートします。
R7RSプログラムからは、エクスポートされた束縛は
@code{(import (scheme inexact))}とすることで使えます。
@c COMMON
@end deftp
@c EN
The following bindings this module provides are Gauche built-ins
(@pxref{Delay force and lazy}).
@c JP
以下の束縛は、Gauche組み込みです
(@ref{Delay force and lazy}参照)。
@c COMMON
@example
delay force promise?
@end example
@defspec delay-force promise
[R7RS lazy]
@c MOD scheme.lazy
@c EN
This is the same as Gauche's built-in @code{lazy}.
@pxref{Delay force and lazy} for the discussion about when this
form should be used.
@c JP
これはGauche組み込みの@code{lazy}と同じです。
使い方については@ref{Delay force and lazy}の議論を参照してください。
@c COMMON
@end defspec
@defun make-promise obj
[R7RS lazy]
@c MOD scheme.lazy
@c EN
If @var{obj} is a promise, it is returned as is. Otherwise,
A promise, which yields @var{obj} when forced, is returned.
Because this is a procedure, expression passed as @var{obj} is
eagerly evaluated, so this doesn't have effect on lazy evaluation,
but can be used to ensure you have a promise.
@c JP
@var{obj}がプロミスならそのまま返されます。そうでなければ、
forceされた時に@var{obj}が返されるようなプロミスが返されます。
これは手続きなので、@var{obj}は@code{make-promise}を呼び出す前に
評価されてしまいます。従って遅延評価には使えませんが、
確実にプロミスを得たい場合に使えます。
@c COMMON
@c EN
This procedure is important on implementations where
@code{force} only takes a promise, and portable code should
use this procedure to yield a value that can be passed to @code{force}.
@c JP
@code{force}がプロミスのみを取るような実装ではこの手続きは重要です。
ポータブルなコードは、@code{force}に渡すものがプロミスであることを
確実にしたい場所でこの手続きを使うようにしてください。
@c COMMON
@c EN
If you write Gauche-specific code, however, @code{force} can take
non-promise values, so you don't need this.
@c JP
Gaucheの@code{force}はプロミスでない値も取れるので、
Gauche専用のコードを書いている時はこの手続きは不要です。
@c COMMON
@end defun
@node R7RS load, R7RS process context, R7RS lazy evaluation, R7RS small language
@subsection @code{scheme.load} - R7RS load
@c NODE R7RS load, @code{scheme.load} - R7RS load
@deftp {Module} scheme.load
@mdindex scheme.load
Exports bindings of R7RS @code{(scheme load)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme load))}.
@end deftp
@defun load file :optional env
[R7RS load]
@c MOD scheme.load
@c EN
R7RS @code{load} takes environment as an optional argument,
while Gauche @code{load} takes it as a keyword argument
(among other keyword arguments). @xref{Loading Scheme file}.
In Gauche, @var{env} is just a module. In portable code,
you can create a module with desired bindings with R7RS @code{environment}
procedure; @pxref{R7RS eval}.
@c JP
R7RSの@code{load}は省略可能引数として環境を取ります。
Gaucheの@code{load}では環境はキーワード引数で受け取られることに注意してください。
@ref{Loading Scheme file}参照。
また、Gaucheでは環境は単にモジュールで良いのですが、
ポータブルなコードではR7RSの@code{environment}手続きを使って
環境を作る必要があります。@ref{R7RS eval}参照。
@c COMMON
@end defun
@node R7RS process context, R7RS read, R7RS load, R7RS small language
@subsection @code{scheme.process-context} - R7RS process context
@c NODE R7RSプロセスコンテキスト, @code{scheme.process-context} - R7RSプロセスコンテキスト
@deftp {Module} scheme.process-context
@mdindex scheme.process-context
Exports bindings of R7RS @code{(scheme process-context)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme process-context))}.
@end deftp
The following bindings are the same as Gauche built-ins
(@pxref{Command-line arguments}, and @ref{Program termination}):
@example
command-line exit
@end example
The following bindings are the same as SRFI-98
(@pxref{Accessing environment variables}):
@example
get-environment-variable get-environment-variables
@end example
@defun emergency-exit :optional (obj 0)
[R7RS process-context]
@c MOD scheme.process-context
Terminate the program without running any clean-up procedures
(@var{after} thunks of @code{dynamic-wind}). Internally,
it calls the @code{_exit(2)} system call directly.
The optional argument is used for the process exit code.
This is almost the same
as Gauche's @code{sys-exit}, except that @code{sys-exit} requires
the exit code object (@pxref{Program termination}).
@end defun
@node R7RS read, R7RS repl, R7RS process context, R7RS small language
@subsection @code{scheme.read} - R7RS read
@c NODE R7RS read, @code{scheme.read} - R7RS read
@deftp {Module} scheme.read
@mdindex scheme.read
Exports bindings of R7RS @code{(scheme read)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme read))}.
The only binding exported from this module is @code{read},
which is the same as Gauche's built-in. @xref{Reading data}.
@end deftp
@node R7RS repl, R7RS time, R7RS read, R7RS small language
@subsection @code{scheme.repl} - R7RS repl
@c NODE R7RS repl, @code{scheme.repl} - R7RS repl
@deftp {Module} scheme.repl
@mdindex scheme.repl
Exports bindings of R7RS @code{(scheme repl)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme repl))}.
The only binding exported from this module is @code{interaction-environment},
which is the same as Gauche's built-in. @xref{Eval and repl}.
@end deftp
@node R7RS time, R7RS write, R7RS repl, R7RS small language
@subsection @code{scheme.time} - R7RS time
@c NODE R7RS time, @code{scheme.time} - R7RS time
@deftp {Module} scheme.time
@mdindex scheme.time
Exports bindings of R7RS @code{(scheme time)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme time))}.
@end deftp
@defun current-second
[R7RS time]
@c MOD scheme.time
Returns a real number represents the number of seconds since
the midnight of Jan. 1, 1970 TAI (which is 23:59:52, Dec 31, 1969 UTC, that
is, -8 seconds before Unix Epoch.) Number of leap seconds were
inserted since then, and as of 2014, UTC is 35 seconds behind TAI. That means
the number returned is 27 seconds larger than the unix time,
which is returned from @code{sys-time} or @code{sys-gettimeofday}.
The reason that R7RS adopts TAI is that it is monotonic and suitable
to take difference of two timepoints. The unix time returned by
@code{sys-time} and @code{sys-gettimeofday} are defined in terms of
UTC date and time, so if the interval spans across leap seconds,
it won't reflect the actual number of seconds in the interval.
(The precise definition is given in section 4.15 of
IEEE Std 1003.1, 2013 Edition, a.k.a Single Unix Specification 4.)
However, since we don't know yet when the next leap second happen,
the current implementation just uses a fixed amount of offset
from the unix time.
Just be aware the difference, or you'll be surprised if you
pass the return value of @code{current-second} to the UTC time
formatter such as @code{sys-strftime}, or compare it with
the file timestamps which uses the unix time. You can convert
between TAI and UTC using srfi-19 (@pxref{SRFI-19 Date}).
@end defun
@defun current-jiffy
[R7RS time]
@c MOD scheme.time
Returns an exact integer measuring a real (wallclock) time elapsed
since some point in the past, which does not change while a
process is running. The time unit is @code{(/ jiffies-per-second)}-th
second.
The absolute value of current jiffies doesn't matter, but
the difference can be used to measure the time interval.
@end defun
@defun jiffies-per-second
Returns a constant to tell how many time units used in @code{current-jiffy}
consists of a second. Currently this is 10^9 on 64bit architectures
(that is, nanosecond resolution) and 10^4 on 32bit architectures
(100 microseconds resolution).
The resolution for 32bit architectures
is unfortunately rather coarse, but if we make it finer
the current jiffy value easily becomes bignums, taking time
to allocate and operate, beating the purpose of benchmarking.
With the current choice, we have 53,867 seconds before we spill
into bignum. On 64bit architectures we have enough bits
not to worry about bignums, with nanosecond resolution.
If you want to do more finer benchmarks on 32bit machines,
you need to roll your own with @code{sys-clock-gettime-monotonic} or
@code{sys-gettimeofday}.
@end defun
@node R7RS write, R5RS compatibility, R7RS time, R7RS small language
@subsection @code{scheme.write} - R7RS write
@c NODE R7RS write, @code{scheme.write} - R7RS write
@deftp {Module} scheme.write
@mdindex scheme.write
Exports bindings of R7RS @code{(scheme write)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme write))}.
This module provides the following bindings, all of which are
Gauche built-in (@pxref{Object output}).
@example
display write write-shared write-simple
@end example
@end deftp
@node R5RS compatibility, , R7RS write, R7RS small language
@subsection @code{scheme.r5rs} - R5RS compatibility
@c NODE R5RS compatibility, @code{scheme.r5rs} - R5RS互換性
@deftp {Module} scheme.r5rs
@mdindex scheme.r5rs
This module is to provide R5RS environment in R7RS programs.
The following bindings are exported. Note that @code{lambda}
is @code{scheme#lambda}, without the support of
extended formals (@code{:optional} etc.)
@xref{Making procedures}, for the details of extended formals.
@example
* + - / < <= = > >= abs acos and angle append apply asin assoc assq
assv atan begin boolean? caaaar caaadr caaar caadar caaddr caadr
caar cadaar cadadr cadar caddar cadddr caddr cadr
call-with-current-continuation call-with-input-file
call-with-output-file call-with-values car case cdaaar cdaadr cdaar
cdadar cdaddr cdadr cdar cddaar cddadr cddar cdddar cddddr cdddr cddr
cdr ceiling char->integer char-alphabetic? char-ci<=? char-ci<?
char-ci=? char-ci>=? char-ci>? char-downcase char-lower-case?
char-numeric? char-ready? char-upcase char-upper-case? char-whitespace?
char<=? char<? char=? char>=? char>? char? close-input-port
close-output-port complex? cond cons cos current-input-port
current-output-port define define-syntax delay denominator display
do dynamic-wind eof-object? eq? equal? eqv? eval even? exact->inexact
exact? exp expt floor for-each force gcd if imag-part inexact->exact
inexact? input-port? integer->char integer? interaction-environment
lambda lcm length let let* let-syntax letrec letrec-syntax list
list->string list->vector list-ref list-tail list? load log magnitude
make-polar make-rectangular make-string make-vector map max member
memq memv min modulo negative? newline not null-environment null?
number->string number? numerator odd? open-input-file open-output-file
or output-port? pair? peek-char positive? procedure? quasiquote quote
quotient rational? rationalize read read-char real-part real? remainder
reverse round scheme-report-environment set! set-car! set-cdr! sin
sqrt string string->list string->number string->symbol string-append
string-ci<=? string-ci<? string-ci=? string-ci>=? string-ci>?
string-copy string-fill! string-length string-ref string-set!
string<=? string<? string=? string>=? string>? string? substring
symbol->string symbol? tan truncate values vector vector->list
vector-fill! vector-length vector-ref vector-set! vector?
with-input-from-file with-output-to-file write write-char zero?
@end example
@end deftp
@node R7RS large, , R7RS small language, Library modules - R7RS standard libraries
@section R7RS large
@c NODE R7RS large
@c EN
R7RS large is still under development, and we're gradually
adding support of the libraries that has been passed.
@c JP
R7RS largeはまだ策定途上ですが、既に決定したライブラリについては
徐々にGaucheに追加してゆきます。
@c COMMON
@c EN
Currently R7RS-large has two editions (Red and Tangerine).
Among the libraries in those editions,
the following are @emph{not} supported yet:
@c JP
現在、R7RS-largeには2つのエディション (RedとTangerine) が
制定されています。その中に定義されているライブラリのうち、
以下のものは@emph{まだ}サポートされていません:
@c COMMON
@example
scheme.ilist scheme.rlist scheme.text
scheme.bytevector scheme.show
@end example
@c EN
The following are supported libraries:
@c JP
以下のライブラリがサポートされているものです:
@c COMMON
@menu
* R7RS lists:: @code{scheme.list}
* R7RS vectors:: @code{scheme.vector}
* R7RS uniform vectors:: @code{scheme.vector.@@}
* R7RS sort:: @code{scheme.sort}
* R7RS sets:: @code{scheme.set}
* R7RS character sets:: @code{scheme.charset}
* R7RS hash tables:: @code{scheme.hash-table}
* R7RS immutable deques:: @code{scheme.ideque}
* R7RS generators:: @code{scheme.generator}
* R7RS lazy sequences:: @code{scheme.lseq}
* R7RS stream:: @code{scheme.stream}
* R7RS boxes:: @code{scheme.box}
* R7RS list queues:: @code{scheme.list-queue}
* R7RS ephemerons:: @code{scheme.ephemeron}
* R7RS comparators:: @code{scheme.comparator}
* R7RS regular expressions:: @code{scheme.regex}
* R7RS mappings:: @code{scheme.mapping}
* R7RS integer division:: @code{scheme.division}
* R7RS bitwise operations:: @code{scheme.bitwise}
* R7RS fixnum:: @code{scheme.fixnum}
* R7RS flonum:: @code{scheme.flonum}
@end menu
@node R7RS lists, R7RS vectors, R7RS large, R7RS large
@subsection @code{scheme.list} - R7RS lists
@c NODE R7RSリスト, @code{scheme.list} - R7RSリスト
@deftp {Module} scheme.list
@mdindex scheme.list
@c EN
This module is a rich collection of list manipulation procedures,
and same as @code{srfi-1}.
Note that Gauche supports quite a few @code{scheme.list}
procedures as built-in.
The following procedures can be used
without loading @code{scheme.list} module. For the manual entries of
these procedures, @ref{Pairs and lists}.
@c JP
このモジュールは、豊富なリスト操作手続きのコレクションです (srfi-1と同じです)。
Gaucheは@code{scheme.list}の手続きの多くを組み込みで提供しています。
以下に挙げる手続きは@code{scheme.list}モジュールをロードしなくても使えます。
これらの手続きの説明は、@ref{Pairs and lists}を参照してください。
@c COMMON
@example
null-list? cons* last member
take drop take-right drop-right take! drop-right!
delete delete! delete-duplicates delete-duplicates!
assoc alist-copy alist-delete alist-delete!
any every filter filter! fold fold-right find find-tail
split-at split-at! iota
@end example
@end deftp
@subsubheading List constructors
@defun xcons cd ca
[R7RS list]
@c MOD scheme.list
@c EN
Equivalent to @code{(cons ca cd)}. Useful to pass to
higher-order procedures.
@c JP
@code{(cons ca cd)} と同等です。高階手続きへ渡すのに便利です。
@c COMMON
@end defun
@defun list-tabulate n init-proc
[R7RS list]
@c MOD scheme.list
@c EN
Constructs an @var{n}-element list, in which
each element is generated by @code{(@var{init-proc} @i{i})}.
@c JP
@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{}
[R7RS list]
@c MOD scheme.list
@c EN
Constructs a circular list of the elements.
@c JP
指定した要素をもつ循環リストを構築します。
@c COMMON
@example
(circular-list 'z 'q) @result{} (z q z q z q @dots{})
@end example
@end defun
@subsubheading List predicates
@defun not-pair? x
[R7RS list]
@c MOD scheme.list
@c EN
Same as @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
@code{(lambda (x) (not (pair? x)))}と同じです。
SRFI-1 では、「真性リストおよびドットリストの両方で、すべての有限リストを
扱う手続き用の終端条件として便利なように用意した」とあります。
@c COMMON
@end defun
@defun list= elt= list @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@var{elt=} を用いて、n番目の要素をそれぞれ比較することで、
与えられたリストの同値性を決定します。
@code{list=} を真性リスト以外に適用するとエラーになります。
同値性判定の手続きは @code{eq?} と整合性がなければなりません。すなわち
@c COMMON
@example
(eq? x y) @result{} (elt= x y).
@end example
@end defun
@subsubheading List selectors
@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
[R7RS list]
@c MOD scheme.list
@c EN
Returns n-th element of the (maybe improper) list.
@c JP
リスト(非真性でも可)のn番目の要素を返します。
@c COMMON
@end defun
@defun car+cdr pair
[R7RS list]
@c MOD scheme.list
@c EN
Returns two values, @code{(car pair)} and @code{(cdr pair)}.
@c JP
@code{(car pair)} および @code{(cdr pair)} の二つの値を返します。
@c COMMON
@end defun
@subsubheading List miscellaneous routines
@defun zip clist1 clist2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@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
[R7RS list]
@c MOD scheme.list
@c EN
@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
@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
@subsubheading List fold, unfold & map
@defun pair-fold kons knil clist1 clist2 @dots{}
@defunx pair-fold-right kons knil clist1 clist2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@code{fold} および @code{fold-right} と同様ですが、@var{kons} 手続き
は与えられた @var{clist} の @code{car} ではなく、@code{cdr} をとります。
@c COMMON
@example
(pair-fold cons '() '(a b c d e))
@result{} ((e) (d e) (c d e) (b c d e) (a b c d e))
(pair-fold-right cons '() '(a b c d e))
@result{} ((a b c d e) (b c d e) (c d e) (d e) (e))
@end example
@end defun
@defun unfold p f g seed :optional tail-gen
[R7RS list]
@c MOD scheme.list
@c EN
Fundamental recursive list constructor.
Defined by the following recursion.
@c JP
基本リスト再帰構築子です。
以下のように再帰的に定義されています。
@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
@example
(unfold (pa$ = 53) integer->char (pa$ + 1) 48)
@result{} (#\0 #\1 #\2 #\3 #\4)
@end example
@end defun
@defun unfold-right p f g seed :optional tail
[R7RS list]
@c MOD scheme.list
@c EN
Fundamental iterative list constructor.
Defined by the following recursion.
@c JP
基本リスト反復構築子です。
以下のように再帰的に定義されています。
@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
@example
(unfold-right (pa$ = 53) integer->char (pa$ + 1) 48)
@result{} (#\4 #\3 #\2 #\1 #\0)
@end example
@end defun
@defun map! f clist1 clist2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
手続き @var{f} は @var{clist1} の各要素と @var{clist2} の対応する要素
に適用され、結果はひとつのリストになります。@var{clist1} のセルは
結果のリストを構築するのに再利用されます。
@c COMMON
@end defun
@defun map-in-order f clist1 clist2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@code{map} の変形バージョンですが、@var{f} の適用順序が、引数として
与えられたリストの要素の左から右への順であることを保証します。
Gauche では @code{map} の実装はこの順になっているので、@code{map} と
同意です。
@c COMMON
@end defun
@defun pair-for-each f clist1 clist2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
Like @code{for-each}, but the procedure @var{f} is applied on
@var{clist}s themselves first, then each @code{cdr}s of them, and so on.
@c JP
@code{for-each} と似ていますが、手続き @var{f} はまず @var{clist}自体に
適用され、次ににそれらの@code{cdr} に適用され、となります。
@c COMMON
@example
(pair-for-each write '(a b c))
@result{} @r{prints} (a b c)(b c)(c)
@end example
@end defun
@subsubheading List partitioning
@defun partition pred list
@defunx partition! pred list
[R7RS list]
@c MOD scheme.list
@c EN
@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
@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
@subsubheading List searching
@defun take-while pred clist
@defunx take-while! pred list
[R7RS list]
@c MOD scheme.list
@c EN
Returns the longest initial prefix of @var{clist} whose elements all
satisfy @var{pred}.
@c JP
@var{clist} の最初から、@var{pred} を満足する限りの最長部分要素を返します。
@c COMMON
@end defun
@defun drop-while pred clist
[R7RS list]
@c MOD scheme.list
@c EN
Drops the longest initial prefix of @var{clist} whose elements all
satisfy @var{pred}, and returns the rest.
@c JP
@var{clist} の最初から、@var{pred} を満足する限りの最長部分要素を削除し、
残りを返します。
@c COMMON
@end defun
@defun span pred clist
@defunx span! pred list
@defunx break pred clist
@defunx break! pred list
[R7RS list]
@c MOD scheme.list
@c EN
@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
@code{span} は @code{(values (take-while pred clist) (drop-while pred clist))}
と等価です。@code{break} は @var{pred} の意味を反転します。
@c COMMON
@end defun
@defun list-index pred clist1 clist2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
Returns the index of the leftmost element that satisfies @var{pred}.
If no element satisfies @var{pred}, @code{#f} is returned.
@c JP
@var{pred} を満足する最も左の要素のインデックスを返します。
@var{pred}を満たす要素が無い場合は@code{#f}を返します。
@c COMMON
@end defun
@subsubheading Association lists
@defun alist-cons key datum alist
[R7RS list]
@c MOD scheme.list
@c EN
Returns @code{(cons (cons @var{key} @var{datum}) @var{alist})}.
This is an alias of the Gauche builtin procedure @code{acons}.
@c JP
@code{(cons (cons @var{key} @var{datum}) @var{alist})} を返します。
これは、Gauche の組み込み手続き @code{acons} の別名です。
@c COMMON
@end defun
@subsubheading Lists as sets
@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.
Since lists require linear time to search, those procedures aren't
suitable to deal with large sets. @xref{R7RS sets}, if you
know your sets will contain more than a dozen items or so.
See also @ref{Combination library}, which
concerns combinations of elements in the set.
@c JP
これらの手続きはリストを集合としてあつかいます。すなわち、どのような
要素があるかは重要ですが、その順序は重要ではありません。
この範疇にあるすべての手続きは、比較手続き @var{elt=} を最初の引数として
とります。この比較手続きは与えられた二つの集合の要素が等しいかどうかを
判定します。
リストは検索に線形時間を必要とするため、ここに挙げた手続きは
大きな集合を扱うには向いていません。もし対象となる集合が
二桁以上の要素を持つことが分かっているなら、@ref{R7RS sets}を
参照してください。
集合の要素の組み合せについては @ref{Combination library}
も参照してください。
@c COMMON
@defun lset<= elt= list1 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@var{list1} のすべての要素が @var{list2} (以降の集合)に含まれている
ときに限り @code{#t} を返します。リストが与えられなかった場合
および一つだけしか与えられなかった場合には、@code{#t} を返します。
@c COMMON
@end defun
@defun lset= elt= list1 list2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@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{}
[R7RS list]
@c MOD scheme.list
@c EN
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
@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{}
[R7RS list]
@c MOD scheme.list
@c EN
Returns the union of the sets @var{list1} @dots{}.
@c JP
@var{list1} @dots{} の和集合を返します。
@c COMMON
@end defun
@defun lset-intersection elt= list1 list2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
Returns a set of elements that are in every @var{list}s.
@c JP
すべての @var{list} に含まれる要素の集合を返します。
@c COMMON
@end defun
@defun lset-difference elt= list1 list2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
Returns a set of elements that are in @var{list1} but not
in @var{list2}. In n-ary case, binary difference operation is
simply folded.
@c JP
@var{list1} には含まれていて、@var{list2} には含まれていない要素の集合を
返します。引数が n 個与えられた場合には、差分をとる二項演算が
畳み込まれます。
@c COMMON
@end defun
@defun lset-xor elt= list1 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
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
与えられた集合の排他的論理和を返します。すなわち、@var{list1} および
@var{list2} のどちらか一方にのみ属する要素からなる集合を返します。
引数が n 個の場合には、xor の二項演算が畳み込まれます。
@c COMMON
@end defun
@defun lset-diff+intersection elt= list1 list2 @dots{}
[R7RS list]
@c MOD scheme.list
@c EN
Returns two sets, a difference and an intersection of given sets.
@c JP
与えられた集合の差集合と積集合のふたつの集合を返します。
@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{}
[R7RS list]
@c MOD scheme.list
@c EN
Linear update variant of the corresponding procedures.
The cells in the first list argument may be reused to construct the result.
@c JP
それぞれ対応する手続きのその場で更新するバージョンです。
最初の引数のリストのセルが結果を構築するのに再利用されるかもしれません。
@c COMMON
@end defun
@node R7RS vectors, R7RS uniform vectors, R7RS lists, R7RS large
@subsection @code{scheme.vector} - R7RS vectors
@c NODE R7RSベクタ, @code{scheme.vector} - R7RSベクタ
@deftp {Module} scheme.vector
@mdindex scheme.vector
@c EN
This module adds rich set of vector operations to the built-in / R7RS
vector procedures.
@c JP
このモジュールは豊富なベクタ操作を提供します。
@c COMMON
@c EN
The following procedures are built-in.
@xref{Vectors}, for the description. We only explain
the procedures that are not built-in.
@c JP
以下の手続きはGaucheでは組み込みになっています。説明は@ref{Vectors}を参照してください。
組み込みでない手続きについてのみ解説します。
@c COMMON
@example
make-vector vector vector?
vector-ref vector-set! vector-length
vector-fill! vector-copy vector-copy!
vector-append vector->list list->vector
reverse-list->vector vector->string string->vector
vector-map vector-map! vector-for-each
@end example
@c EN
This module is @code{srfi-133}, which supersedes @code{srfi-43}
(@pxref{Vector library (Legacy)}).
Note that the interface of following procedures in @code{srfi-43}
are changed for the consistency:
@c JP
このモジュールは@code{srfi-133}として制定され、
@code{srfi-43}(@ref{Vector library (Legacy)})を置き換えるものです。
@code{srfi-43}の手続きのうち、以下のものは一貫性からインタフェースが
変更されていることに注意してください。
@c COMMON
@example
vector-map vector-map! vector-for-each
vector-fold vector-fold-right vector-count
@end example
@c EN
Some of the functionalities
of @code{srfi-43} version is supported by built-in procedures
(e.g. Built-in @code{vector-map-with-index} is the same as
@code{srfi-43}'s @code{vector-map}). So there's little point
for new code to use @code{srfi-43}.
@c JP
@code{srfi-43}から削られた機能の一部は、
Gaucheの組み込み手続きでサポートされています
(例えば@code{srfi-43}の@code{vector-map}は組み込みの@code{vector-map-with-index}と
同じです)。新しいコードで@code{srfi-43}を使う必要はほとんどないでしょう。
@c COMMON
@end deftp
@c EN
@subheading Vector constructors
@c JP
@subheading ベクタ構成子
@c COMMON
@defun vector-unfold f length seed @dots{}
[R7RS vector]
@c MOD scheme.vector
Creates a vector of length @var{length}, filling elements
left to right by calling @var{f} repeatedly.
The procedure @var{f} must take as many arguments as
one plus number of seed values, and must return the same number
of values. The first argument is the index. The first return
value is used for the element of the result vector, and the
rest of return values are passed to the next call of @var{f}.
@example
(vector-unfold (^[i] (* i i)) 5)
@result{} #(0 1 4 9 16)
(vector-unfold (^[i x] (values (cons i x) (* x 2))) 8 1)
@result{} #((0 . 1) (1 . 2) (2 . 4) (3 . 8)
(4 . 16) (5 . 32) (6 . 64) (7 . 128))
@end example
@end defun
@defun vector-unfold-right f length seed @dots{}
[R7RS vector]
@c MOD scheme.vector
Creates a vector of length @var{length}, filling elements
right to left by calling @var{f} repeatedly.
The procedure @var{f} must take as many arguments as
one plus number of seed values, and must return the same number
of values. The first argument is the index. The first return
value is used for the element of the result vector, and the
rest of return values are passed to the next call of @var{f}.
@example
(vector-unfold-right (^[i] (* i i)) 5)
@result{} #(0 1 4 9 16)
(vector-unfold-right (^[i x] (values (cons i x) (* x 2))) 8 1)
@result{} #((0 . 128) (1 . 64) (2 . 32) (3 . 16)
(4 . 8) (5 . 4) (6 . 2) (7 . 1))
@end example
@end defun
@defun vector-reverse-copy vec :optional start end
[R7RS vector]
@c MOD scheme.vector
Copies the vector @var{vec} with reversing its elements.
Optional @var{start} and @var{end} arguments can limit
the range of the input.
@example
(vector-reverse-copy '#(a b c d e) 1 4)
@result{} #(d c b)
@end example
@end defun
@defun vector-concatenate list-of-vectors
[R7RS vector]
@c MOD scheme.vector
Same as @code{(apply vector-append list-of-vectors)}.
@end defun
@defun vector-append-subvectors spec @dots{}
[R7RS vector]
@c MOD scheme.vector
The number of arguments must be multiple of 3. The argument list
must be in the following format, where each @var{vecN} is
a vector, and @code{startN} and @code{endN} are nonnegative integers:
@example
vec1 start1 end1 vec2 start2 end2 @dots{}
@end example
This procedure creates a new vector by concatenating subvectors
specified by each triplet. That is, it works as if it's the following
code, except it avoids copying each subvector:
@example
(vector-append (vector-copy vec1 start1 end1)
(vector-copy vec2 start2 end2)
@dots{})
@end example
Here's an example:
@example
(vector-append-subvectors '#(a b c d e) 0 3
'#(f g h i j) 2 5)
@result{} #(a b c h i j)
@end example
@end defun
@c EN
@subheading Vector predicates
@c JP
@subheading ベクタ上の述語
@c COMMON
@defun vector-empty? vec
[R7RS vector]
@c MOD scheme.vector
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{}
[R7RS vector]
@c MOD scheme.vector
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 Vector iteration
@c JP
@subheading ベクタ上の繰り返し
@c COMMON
@defun vector-fold kons knil vec1 vec2 @dots{}
[R7RS vector]
@c MOD scheme.vector
@var{Kons} is a procedure that takes @var{n}+1 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{seed} @var{e_1i} @var{e_2i} @dots{})},
where 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} (@pxref{Mapping over collection}). It's an unfortunate
historical glitch; @code{vector-fold-left} would be more consistent
name.
@example
(vector-fold (^[a b] (cons b a)) '() '#(a b c d))
@result{} (d c b a)
@end example
@end defun
@defun vector-fold-right kons knil vec1 vec2 @dots{}
[R7RS vector]
@c MOD scheme.vector
Like @code{vector-fold}, but elements in the @var{vec1} @var{vec2} @dots{}
are visited from right to left.
Unlike @code{fold-right} (@pxref{Mapping over sequences}),
the procedure @var{kons} takes the accumulated value in the
first argument.
@example
(vector-fold-right (^[a b] (cons b a)) '() '#(a b c d))
@result{} (a b c d)
@end example
@end defun
@defun vector-count pred vec1 vec2 @dots{}
[R7RS vector]
@c MOD scheme.vector
Applies @var{pred} on each elements in argument vectors (if N vectors
are given, @var{pred} takes N arguments, the first being
@var{i}-th element of @var{vec1}, the second being @var{i}-th element
of @var{vec2}, etc.) Then returns the number of times
@var{pred} returned true value. The order @var{pred} applied
to each element is unspecified.
@example
(vector-count odd? '#(0 1 2 3 4)
@result{} 2
(vector-count < '#(7 3 9 1 5) '#(6 8 2 3 8 8))
@result{} 3
@end example
@end defun
@defun vector-cumulate f seed vec
[R7RS vector]
@c MOD scheme.vector
Returns a fresh vector with the same size of @var{vec}, with
the elements calculated as follows:
The first element of result vector is a result of procedure @var{f}
called with @var{seed} and the first element of @var{vec}.
The @var{i}-th element of result vector is a result of procedure @var{f}
called with @var{i-1}-th element of result vector and @var{i}-th element
of @var{vec}.
@example
(vector-cumulate string-append "z" '#("a" "b" "c"))
@result{} #("za" "zab" "zabc")
@end example
@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{}
[R7RS vector]
@c MOD scheme.vector
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{}
[R7RS vector]
@c MOD scheme.vector
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 satisfy @var{pred}.
@end defun
@defun vector-binary-search vec value cmp :optional start end
[R7RS+]
@c MOD scheme.vector
@c EN
Look for @var{value} in a sorted 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 the 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
extension to SRFI-133, and can be used to limit the range of the
search in @var{start}-th element (inclusive) to
@var{end}-th element (exclusive).
@c JP
ソートされたベクタ@var{vec}中から値@var{value}を探し、
見つかればそのインデックスを、見つからなければ@code{#f}を返します。
@var{vec}の要素と@var{value}の比較は手続き@var{cmp}で行われます。
@var{cmp}は二つの引数を取り、最初の引数の方が小さければ負の整数を、
等しければ0を、最初の引数の方が大きければ正の整数を買えす手続きです。
@var{vec}の要素は@var{cmp}による比較に従い小さい方から順にソート済みで
なければなりません。この手続きはその仮定のもとに、二分探索を行います。
省略可能な@var{start}と@var{end}引数は、Gauche独自の拡張です。指定された場合、
@var{start}番目の要素(含む)から@var{end}番目の要素(含まない)までが探索の対象となります。
@c COMMON
@end defun
@defun vector-any pred vec1 vec2 @dots{}
[R7RS vector]
@c MOD scheme.vector
@c EN
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.
@c JP
@var{vec1} @var{vec2} @dots{}の各ベクタの先頭から順に、
ひとつづつ対応する要素を取って、それに@var{pred}を適用してゆきます。
@var{pred}が真の値を返したら、直ちにその値を返します。
@var{pred}を満たす要素が見つからなければ、@code{#f}が返されます。
ベクタの長さは異なっていても構いません。最も短いベクタの要素を使い切ったところで
探索は打ちきられます。
@c COMMON
@end defun
@defun vector-every pred vec1 vec2 @dots{}
[R7RS vector]
@c MOD scheme.vector
@c EN
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}.
If any of the elements don't satisfy @var{pred},
it returns @code{#f} immediately without looking further.
@c JP
@var{vec1} @var{vec2} @dots{}の各ベクタの先頭から順に、
ひとつづつ対応する要素を取って、それに@var{pred}を適用します。
全ての要素が@var{pred}を満たした場合(ベクタの長さが異なる場合は、
最も短いベクタを使い切った時点)で、最後の@var{pred}の結果を返します。
途中で@var{pred}が@code{#f}を返した場合は、その先は見ずに直ちに@code{#f}を返します。
@c COMMON
@example
(vector-every < '#(1 2 3 4 5) '#(2 3 4 4 5)
@result{} #f
(vector-every (^[x y] (and (real? x) (real? y) (- x y)))
'#(1 2 3)
'#(2 4 6))
@result{} -3
@end example
@end defun
@defun vector-partition pred vec
[R7RS vector]
@c MOD scheme.vector
@c EN
Allocates a fresh vector of the same size as @var{vec},
then fill it with elements in @var{vec} that satisfy @var{pred},
followed by elements that don't satisfy @var{pred}.
Returns two values, the newly created vector and
an exact integer of the index of the first element that doesn't satisfy
@var{pred} in the returned vector.
@c JP
@var{vec}と同じ大きさのベクタを新たにアロケートし、
まず@var{vec}中の@var{pred}を満たす要素を順に詰めてゆき、
その後を@var{pred}を満たさない要素で埋めます。
新たに作られたベクタと、その中で@var{pred}を満たさない最初の要素を指す
インデックスの二つの値を返します。
@c COMMON
@example
(vector-partition odd? '#(1 2 3 4 5 6 7 8))
@result{} #(1 3 5 7 2 4 6 8) @r{and} 4
@end example
@end defun
@c EN
@subheading Vector mutators
@c JP
@subheading ベクタの変更子
@c COMMON
@defun vector-swap! vec i j
[R7RS vector]
@c MOD scheme.vector
@c EN
Swaps vector @var{vec}'s @var{i}-th and @var{j}-th elements.
Returns unspecified value.
@c JP
@var{vec}の@var{i}番目の要素と@var{j}番目の要素を交換します。
戻り値はunspecifiedです。
@c COMMON
@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
(vector-swap! v 0 2))
@result{} #(c b a d e)
@end example
@end defun
@defun vector-reverse! vec :optional start end
[R7RS vector]
@c MOD scheme.vector
@c EN
Reverse the elements of @var{vec}. Returns an undefined value.
Optional @var{start} and @var{end} arguments can limit
the range of operation.
@c JP
@code{vec}の要素を逆順に並べ替えます。戻り値は未定義です。
省略可能引数@var{start}と@var{end}は影響が及ぶ範囲を限定します。
@c COMMON
@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
(vector-reverse! v 0 4))
@result{} #(d c b a e)
@end example
@end defun
@defun vector-reverse-copy! target tstart source :optional sstart send
[R7RS vector]
@c MOD scheme.vector
@c EN
Like @code{vector-copy!}, but reverses the order of elements from @var{start}.
@c JP
@code{vector-copy!}と似ていますが、指定範囲を逆順にコピーします。
@c COMMON
@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
(vector-reverse-copy! v 2 '#(1 2)))
@result{} #(a b 2 1 e)
@end example
@c EN
It is ok to pass the same vector to @var{target} and @var{source};
it always works even if the regions of source and destination are
overlapping.
@c JP
@var{target}と@var{source}に同じベクタを指定しても構いません。
コピー範囲が重なっていても問題なく動作します。
@c COMMON
@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
(vector-reverse-copy! v 1 v 1))
@result{} #(a e d c b)
@end example
@end defun
@defun vector-unfold! f rvec start end seeds @dots{}
@defunx vector-unfold-right! f rvec start end seeds @dots{}
[R7RS vector]
@c MOD scheme.vector
@c EN
Fill @var{rvec} starting from index @var{start} (inclusive) and
ending at index @var{end} (exclusive), with the elements
calculated by @var{f}.
The procedure @var{f} takes the number of seed values @var{seeds} @dots{}
plus one arguments. The first argument is the current index,
followed by seed values. The same number of values
as the arguments must be returned from @var{f}; the first return value
is used to fill the current element of @var{rvec}, and the rest of the values
are used as the next seed values.
The result vector is filled from left to right by @code{vector-unfold!},
and right to left by @code{vector-unfold-right!}.
The return value is unspecified.
@c JP
@var{rvec}の、@var{start}から@var{end}の直前までの範囲を@var{f}が算出する
新たな要素で埋めます。
@var{f}は、@var{seeds} @dots{}の数よりひとつ多い引数を取ります。
最初の引数は現在のインデックスで、それにシード値が続きます。
@var{f}は引数と同数の値を返します。最初の戻り値が@var{rvec}を埋めるのに使われ、
残りの戻り値は新たなシード値として次の@var{f}の呼び出しに使われます。
結果のベクタは、@code{vector-unfold!}では左から右へ、
@code{vector-unfold-right!}では右から左へと埋められます。
戻り値はunspecifiedです。
@c COMMON
@example
(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
(vector-unfold! (^[i] (+ i 1)) rvec 1 4)
rvec)
@result{} #(a 2 3 4 e f)
(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
(vector-unfold-right! (^[i] (+ i 1)) rvec 1 4)
rvec)
@result{} #(a 2 3 4 e f)
(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
(vector-unfold! (^[i x] (values x (* x 2))) rvec 1 5 10)
rvec)
@result{} #(a 10 20 40 80 f)
(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
(vector-unfold! (^[i x] (values x (* x 2))) rvec 1 5 10)
rvec)
@result{} #(a 80 40 20 10 f)
@end example
@end defun
@c EN
@subheading Vector conversion
@c JP
@subheading ベクタの変換
@c COMMON
@defun reverse-vector->list vec :optional start end
[R7RS vector]
@c MOD scheme.vector
@c EN
Same as @code{(reverse (vector->list vec start end))}, but more efficient.
@c JP
@code{(reverse (vector->list vec start end))}と同じですが、より効率的です。
@c COMMON
@end defun
@node R7RS uniform vectors, R7RS sort, R7RS vectors, R7RS large
@subsection @code{scheme.vector.@@} - R7RS uniform vectors
@c NODE R7RSユニフォームベクタ, @code{scheme.vector.@@} - R7RSユニフォームベクタ
@deftp {Module} scheme.vector.@@
@mdindex scheme.vector.base
@mdindex scheme.vector.u8
@mdindex scheme.vector.s8
@mdindex scheme.vector.u16
@mdindex scheme.vector.s16
@mdindex scheme.vector.u32
@mdindex scheme.vector.s32
@mdindex scheme.vector.u64
@mdindex scheme.vector.s64
@mdindex scheme.vector.f32
@mdindex scheme.vector.f64
@mdindex scheme.vector.c64
@mdindex scheme.vector.c128
@code{@@} is actually one of @code{u8}, @code{s8}, @code{u16}, @code{s16},
@code{u32}, @code{s32}, @code{u64}, @code{s64}, @code{f32},
@code{f64}, @code{c64} or @code{c128}.
(Gauche's @code{gauche.uvector} module also provides @code{f16}
and @code{c32} vectors.)
These modules provides vectors that can hold specific range of numeric
values. In Gauche we use @emph{packed} representation, meaning
numbers are tightly stored in consecutive memory region.
Additionally, @code{scheme.vector.base} module exports basic procedures
(@code{make-@@vector}, @code{@@vector}, @code{@@vector?}, @code{@@vector-length},
@code{@@vector-ref}, @code{@@vector-set!},
@code{@@vector->list}, @code{list->@@vector}, @code{@@?})
for all element types.
The @code{gauche.uvector} module is a superset of these modules, and
all procedures are described there. @xref{Uniform vectors} for the
details.
@end deftp
@node R7RS sort, R7RS sets, R7RS uniform vectors, R7RS large
@subsection @code{scheme.sort} - R7RS sort
@c NODE R7RSソート, @code{scheme.sort} - R7RSソート
@deftp {Module} scheme.sort
@mdindex scheme.sort
Provides utilities to sort, and to work on sorted lists/vectors.
This module is the same as @code{srfi-132}.
Gauche has built-in sort and merge procedures (@pxref{Sorting and merging}).
This module has a bit different API. Notably, the ordering predicate
comes first than the sequence to be sorted, and the procedures
dealing with vectors uniformly support start/end arguments
This module also provide useful procedures working on sorted or
partially sorted sequences.
@end deftp
@defun list-sort elt< lis
@defunx list-sort! elt< lis
@defunx list-stable-sort elt< lis
@defunx list-stable-sort! elt< lis
[R7RS sort]
@c MOD scheme.sort
Sort elements in a list @var{lis} according to the ordering
predicate @var{elt<}, which takes two elements from @var{lis}
and returns true iff the first argument is strictly less
than the second argument.
Returns a sorted list.
The procedures with bang are allowed, but not required, to reuse
@code{lis}. The ``stable'' variation guarantees stable sort.
These are basically the same as Gauche's built-in
@code{sort}, @code{sort!}, @code{stable-sort} and @code{stable-sort!},
except the Gauche's version works on any sequences and takes
arguments differently. (@xref{Sorting and merging}.)
@end defun
@defun list-sorted? elt< lis
[R7RS sort]
@c MOD scheme.sort
Returns true if the list @var{list} is sorted according to the
ordering predicate @var{elt<}.
See also @code{sorted?} in @ref{Sorting and merging}.
@end defun
@defun list-merge elt< lis1 lis2
@defunx list-merge! elt< lis1 lis2
[R7RS sort]
@c MOD scheme.sort
Given two sorted lists @var{lis1} and @var{lis2}, returns
a new sorted list according to the ordering predicate @var{elt<}.
Note that @code{list-merge!} works in-place, that is, all the pairs
in @var{lis1} and @var{lis2} are reused.
See also @code{merge} and @var{merge!} in @ref{Sorting and merging}.
@end defun
@defun vector-sort elt< vec :optional start end
@defunx vector-stable-sort elt< vec :optional start end
[R7RS sort]
@c MOD scheme.sort
Sort elements in a vector @var{vec} according to the ordering
predicate @var{elt<}, which takes two elements from @var{vec}
and returns true iff the first argument is strictly less
than the second argument. Returns a fresh sorted vector.
The ``stable'' variation guarantees stable sort.
When the optional @var{start} and/or @var{end} arguments are given,
only the portion from @var{start} (inclusive) and
@var{end} (exclusive) of @var{vec} are looked at.
The result vector's length is @code{@var{end} - @var{start})}.
When @var{end} is omitted, the length of @var{vec} is assumed.
See also @code{sort} and @code{stable-sort} in @ref{Sorting and merging}.
@end defun
@defun vector-sort! elt< vec :optional start end
@defunx vector-stable-sort! elt< vec :optional start end
[R7RS sort]
@c MOD scheme.sort
Sort elements ``in-place'' in a vector @var{vec} according to the ordering
predicate @var{elt<}, which takes two elements from @var{vec}
and returns true iff the first argument is strictly less
than the second argument. Upon successful return,
@var{vec}'s elements are sorted. Returns unspecified value; the
caller must rely on the side effect.
When the optional @var{start} and/or @var{end} arguments are given,
only the portion from @var{start} (inclusive) and
@var{end} (exclusive) of @var{vec} are sorted; other elements
will remain intact.
When @var{end} is omitted, the length of @var{vec} is assumed.
See also @code{sort!} and @code{stable-sort!} in @ref{Sorting and merging}.
@end defun
@defun vector-sorted? elt< vec :optional start end
[R7RS sort]
@c MOD scheme.sort
Returns true iff @var{vec} between @var{start} (inclusive)
and @var{end} (exclusive) is sorted according to the ordering
predicate @var{elt<}. If @var{start} and/or @var{end} is/are omitted,
0 and the length of @var{vec} are assumed, respectively.
See also @code{sorted?} in @ref{Sorting and merging}.
@end defun
@defun vector-merge elt< vec1 vec2 :optional start1 end1 start2 end2
@defunx vector-merge! elt< rvec vec1 vec2 :optional rstart start1 end1 start2 end2
[R7RS sort]
@c MOD scheme.sort
Merge two sorted vectors @var{vec1} and @var{vec2}
into one vector, according to the
ordering predicate @var{elt<}.
The optional argument @var{start1} and @var{end1} restricts @var{vec1}'s
portion to be looked at, and @var{start2} and @var{end2}
restricts @var{vec2}'s portion to be looked at.
The functional version @var{vector-merge} allocates a fresh vector
to hold the result, and returns it.
The side-effecting version @var{vector-merge!} uses @var{rvec}.
to hold the result. The procedure doesn't return a meaningful value.
The optional @var{rstart} argument specifies
the index of @var{rvec} from which the result is filled; the default
is 0.
@end defun
@defun list-delete-neighbor-dups elt= lis
@defunx list-delete-neighbor-dups! elt= lis
@defunx vector-delete-neighbor-dups elt= vec :optional start end
@defunx vector-delete-neighbor-dups! elt= vec :optional start end
[R7RS sort]
@c MOD scheme.sort
From the given list @var{lis} or vector @var{vec},
these procedures delete adjacent duplicate elements. Equivalence
is checked by @var{elt=} procedure.
@example
(list-delete-neighbor-dups eq? '(m i s s i s s i p p i))
@result{} (m i s i s i p i)
@end example
The non-destructive versions @code{list-delete-neighbor-dups} and
@code{vector-delete-neighbor-dups} returns a freshly allocated
list and vector, respectively.
The destructive @code{list-delete-neighbor-dups!} works in-place,
reusing pairs of @var{lis}. No allocation will be done.
The destructive @code{vector-delete-neighbor-dups!} has a bit different
interface. It updates @var{vec} in-place, but since we can't change
the length of the vector, it gathers the result from the beginning of
the @var{vec}, then returns the next index @var{newend}
of @var{vec}---that is,
after calling this procedure, @code{[@var{start}, @var{newend})}
holds the result.
The elements between @code{[@var{newend}, @var{end})} will remain intact.
The optional @var{start} and @var{end} arguments limits the region
of @var{vec} to be looked at.
@example
(vector-delete-neighbor-dups eq? '#(a a a b b c c d d e e f f) 3 10)
@result{} #(b c d e)
(let1 v '#(a a a b b c c d d e e f f)
(cons (vector-delete-neighbor-dups! eq? v 3 10) v))
@result{} (7 . #(a a a b c d e d d e e f f))
@end example
Note: The @code{gauche.sequence} module provides neighbor duplicate
deletion on generic sequences. Those procedures are implemented by
the generic versions as shown below. @xref{Other operations over sequences},
for the details.
@table @code
@item list-delete-neighbor-dups
@code{delete-neighbor-dups}
@item list-delete-neighbor-dups!
@code{delete-neighbor-dups-squeeze!}
@item vector-delete-neighbor-dups
@code{delete-neighbor-dups}
@item vector-delete-neighbor-dups!
@code{delete-neighbor-dups!}
@end table
@end defun
@defun vector-select! elt< vec k :optional start end
[R7RS sort]
@c MOD scheme.sort
Select @var{k}-th smallest element in @var{vec} according to the
ordering predicate @var{elt<}. @var{K} is zero based, i.e. 0 means
the smallest. The optional @var{start} and @var{end} arguments
limits the range of @var{vec} to be looked at, and defaulted to
0 and the length of @var{vec}, respectively.
@var{K} must satisfy @code{@var{start} <= @var{k} < @var{end}}.
This procedure runs in O(n) time, and requires no extra stroage.
This procedure may partially modify @var{vec}.
@end defun
@defun vector-separate! elt< vec k :optional start end
[R7RS sort]
@c MOD scheme.sort
Find @var{k}-th smallerst element in @var{vec} (pivot) between
between @var{start} and @var{end}, according to the ordering
predicate @var{elt<}, then rearrange elements
between @var{start} and @var{end} so that
elements smaller than the pivot comes between @code{@var{start}} and
@code{@var{start} + @var{k}}, and the rest of the elements come
afterwards. When omitted, @var{start} is 0 and @var{end} is
the length of the @var{vec}.
This can be used as a building block for in-place divide-and-conquer
algorithms. Runs in O(n) time.
@end defun
@defun vector-find-median elt< vec knil :optional mean
@defunx vector-find-median! elt< vec knil :optional mean
[R7RS sort]
@c MOD scheme.sort
Find median value of elements in @var{vec}, when ordered by
the ordering predicate @var{elt<}. Non-destructive version
@code{vector-find-median} runs in O(n) time. The destructive
version @code{vector-find-median!} is specified to leave
@var{vec} sorted, so it runs in O(n log n).
@enumerate
@item
If @var{vec} is empty, @var{knil} is returned. This is the only case
@var{knil} is used.
@item
If @var{vec} has odd number of elements, the element falls in the exactly
the midpoint when ordered, is returned.
@item
If @var{vec} has even number of elements, the two elements closest to
the midpoint is chosen and passed to the procedure @var{mean}, and
its result is returned. The default of @var{mean} is an arithmetic
mean of numbers.
@end enumerate
@example
(vector-find-median < #() 0)
@result{} 0
(vector-find-median < #(78 61 19 38 51) 0)
@result{} 51
(vector-find-median < #(78 61 19 38 51 52) 0)
@result{} 103/2
@end example
@end defun
@node R7RS sets, R7RS character sets, R7RS sort, R7RS large
@subsection @code{scheme.set} - R7RS sets
@c NODE R7RSセット, @code{scheme.set} - R7RSセット
@deftp {Module} scheme.set
@mdindex scheme.set
@c EN
Sets and bags are unordered collection of Scheme values.
A set doesn't count duplicates; if you add an item
which is already in a set, you still have one item of the kind.
A bag counts duplicates; if you add an item which
is already in a bag, you have two items of the kind.
@c JP
セットとバッグは、Scheme値の順序づけのないコレクションです。
セットは重複を考慮しません。既にセット中にある要素をさらに追加しても、
その要素は依然として一つだけセット中にあると認識されます。
一方、バッグは重複を数えます。既にバッグ中にひとつだけある要素と同じものを
追加すると、バッグ中のその要素は二つと数えられます。
@c COMMON
@c EN
To check whether the items are ``the same'', sets and bags
takes a comparator at construction time. The comparator
doesn't need to have an ordering predicate (we don't need
to order the elements) but has to have a hash function.
@xref{Basic comparators}, for the details of comparators.
@c JP
要素が「同じ」であるかどうかの判定のため、セットとバッグは構築時に
比較器を取ります。比較器は順序手続きを持っていなくても構いません
(要素の順序づけは必要ありません)が、ハッシュ手続きは持っている必要があります。
比較器について詳しくは@ref{Basic comparators}を参照してください。
@c COMMON
@c EN
This module is originally specified as @code{srfi-113}, and then
incorporated to R7RS large.
@c JP
このモジュールは当初@code{srfi-113}として定義され、のちにR7RS largeに
採用されました。
@c COMMON
@c EN
As a Gauche's extension, sets and bags implement collection protocol
(@pxref{Collection framework}, for the details), and generic collection
operations can be applied.
@c JP
Gauche独自拡張として、セットやバッグはコレクションプロトコルを実装しており、
汎用のコレクション操作が適用できます
(@ref{Collection framework}参照)。
@c COMMON
@example
(coerce-to <list> (set eq-comparator 'a 'b 'a 'b))
@result{} (a b) ; @r{order may differ}
(coerce-to <list> (bag eq-comparator 'a 'b 'a 'b))
@result{} (a a b b) ; @r{order may differ}
@end example
@end deftp
@subheading Constructors
@defun set comparator elt @dots{}
@defunx bag comparator elt @dots{}
[R7RS set]
@c MOD scheme.set
Creates a new set and bag from given elements @var{elt} @dots{}.
Given @var{comparator} will be used to compare equality of elements.
@example
(set->list (set eq-comparator 'a 'b 'a 'b))
@result{} (a b)
(bag->list (bag eq-comparator 'a 'b 'a 'b))
@result{} (a a b b)
@end example
@end defun
@defun set-unfold stop? mapper successor seed comparator
@defunx bag-unfold stop? mapper successor seed comparator
[R7RS set]
@c MOD scheme.set
Procedurally creates a set or a bag. The first three
arguments, @var{stop?}, @var{mapper} and @var{successor},
are all procedures that takes one argument, the current seed value.
It may be easier to know their types:
@example
seed :: Seed
stop? :: Seed -> Boolean
mapper :: Seed -> ElementType
successor :: Seed -> Seed
@end example
The @code{stop?} procedure takes the current seed value and
returns a boolean value - if it is true, iteration stops.
The @code{mapper} procedure takes the current seed value
and returns an item, which is to be included in the resulting set or bag.
The @code{successor} procedure takes the current seed value
and returns the next seed value.
And the @code{seed} argument gives the initial seed value.
@example
(set->list (set-unfold (^s (= s 75))
integer->char
(^s (+ s 1))
65
eqv-comparator))
@result{} (#\D #\H #\A #\E #\I #\J #\B #\F #\C #\G)
@end example
@end defun
@subheading Predicates
@defun set-contains? set obj
@defunx bag-contains? bag obj
[R7RS set]
@c MOD scheme.set
Check if @var{obj} is in the set or the bag.
@end defun
@defun set-empty? set
@defunx bag-empty? bag
[R7RS set]
@c MOD scheme.set
Returns @code{#t} iff the given set or bag is empty.
@end defun
@defun set-disjoint? set1 set2
@defunx bag-disjoint? bag1 bag2
[R7RS set]
@c MOD scheme.set
Returns @code{#t} iff the given arguments (sets or bags) don't have
common items. Both arguments must have the same comparator---otherwise
an error is signaled.
@end defun
@subheading Accessors
@defun set-member set obj default
@defunx bag-member bag obj default
[R7RS set]
@c MOD scheme.set
Returns an element in the given set or bag which is equal to @var{obj}
in terms of the set's or the bag's comparator. If no such element is
found, @var{default} will be returned.
Note that the returned object doesn't need to be ``the same''
as @var{obj} in a usual sense. See the following example:
@example
(let s (set string-ci-comparator "abc" def")
(set-member s "ABC" #f))
@result{} "abc"
@end example
@end defun
@defun set-element-comparator set
@defunx bag-element-comparator bag
[R7RS set]
@c MOD scheme.set
Returns the comparator used to compare the elements for the set or the bag.
@end defun
@subheading Updaters
@defun set-adjoin set elt @dots{}
@defunx bag-adjoin bag elt @dots{}
[R7RS set]
@c MOD scheme.set
Returns a newly created set or bag that contains all the elements
in the original set/bag, plus given elements. The new set/bag's
comparator is the same as the original set/bag's one.
@end defun
@defun set-replace set elt
@defunx bag-replace bag elt
[R7RS set]
@c MOD scheme.set
Returns a newly created set/bag with the same comparator with
the original set/bag, and the same elements, except that the elements
equal to @var{elt} (in terms of set/bag's comparator) is replaced
by @var{elt}. If the original set/bag doesn't contain an element
equal to @var{elt}, the original one is returned.
@example
(let ((s (set string-ci-comparator "ABC" "def")))
(set->list (set-replace s "abc")))
@result{} ("abc" "def")
@end example
@end defun
@defun set-delete set elt @dots{}
@defunx bag-delete bag elt @dots{}
[R7RS set]
@c MOD scheme.set
Returns a newly created set or bag that has the same comparator
and the same elements in the original set/bag, except that the
item which is equal to @var{elt}.
@end defun
@defun set-delete-all set elt-list
@defunx bag-delete-all bag elt-list
[R7RS set]
@c MOD scheme.set
Returns a newly created set or bag with the same comparator of
the original set/bag, with the elements of the original set/bag
except the ones listed in @var{elt-list}.
@end defun
@defun set-adjoin! set elt @dots{}
@defunx bag-adjoin! bag elt @dots{}
@defunx set-replace! set elt
@defunx bag-replace! bag elt
@defunx set-delete! set elt @dots{}
@defunx bag-delete! bag elt @dots{}
@defunx set-delete-all! set elt-list
@defunx bag-delete-all! bag elt-list
[R7RS set]
@c MOD scheme.set
These are the linear update versions of their counterparts.
It works just like the ones without @code{!}, except that
the original set/bag @emph{may} be reused to produce the result,
instead of new one being allocated.
Note that it's not guaranteed that the original
set/bag is modified, so you should use the return value of them,
instead of relying on the side effects.
@end defun
@defun set-search! set elt failure success
@defunx bag-search! bag elt failure success
[R7RS set]
@c MOD scheme.set
Lookup-and-modify procedures. The @var{failure} and @var{success}
arguments are procedures.
First, they search @var{elt} in the given set/bag.
If an item that matches @var{elt} is found, the @var{success} procedure
is called with three arguments, as follows:
@example
(success item update remove)
@end example
The @var{update} argument is a procedure that takes two arguments,
as @code{(update new-item retval)}. It replaces the matching @var{item} in the
set/bag with @var{new-item}, and returns @var{retval}.
The @var{remove} argument is a procedure that takes one argument,
as @code{(remove retval)}. It removes the matching @var{item} in
the set/bag, and returns @var{retval}.
If an item that matches @var{elt} is not found, the @var{failure} procedure
is called with two arguments, as follows:
@example
(failure insert ignore)
@end example
The @var{insert} argument is a procedure that takes one argument,
as @code{(insert retval)}. It inserts @var{elt} into the set/bag, and