11.1 binary.io - バイナリI/O

Module: binary.io

このモジュールは数値データを読み書きするバイナリ入出力用の基本手続きを提 供します。各データはポートあるいはユニフォームベクタ (gauche.uvector - ユニフォームベクタ参照)から読み込み、あるいはそれらへ書き出すことが できます。 構造をもつバイナリデータの入出力については、便利な packユーティリティがこのモジュールを使って実装されています (binary.pack - バイナリデータのパックを参照してください)。 スピードあるいはエンディアンの柔軟な制御などをやりたいときにこのモジュー ルが使えます。

バイナリのブロック入出力についてはgauche.uvector - ユニフォームベクタを参照してくだ さい。

エンディアン

このモジュールのほとんどの手続はオプション引数としてendian引数を とります。これはbig-endian、little-endian、 arm-little-endianのいずれかのシンボルでなければなりません。 エンディアン引数が省略された場合には、組込みパラメータdefault-endian の現在値が使われます。default-endianの初期値は その計算機でのエンディアンです。(read-u8の ような 8ビット入出力手続ではエンディアン引数は意味がありませんが、 一貫性のため受け入れるようにしてあります。)

Builtin Parameter: default-endian &optional value

value無しで呼ばれると、現在のデフォルトエンディアンの値を返します。 valueを伴って呼ばれると、その値をデフォルトエンディアンとします。 エンディアンの値は以下のいずれかのシンボルでなければなりません。

big-endian

ビッグエンディアン。整数値#x12345678は#x12 #x34 #x56 #x78 のようなバイトシーケンスとして出力されます。

little-endian

リトルエンディアン。整数値#x12345678は#x78 #x56 #x34 #x12 のようなバイトシーケンスとして出力されます。

arm-little-endian

これはlittle-endianのバリエーションで、ARMプロセッサの 特定のモードで使われるものです。倍精度浮動小数点数以外はlittle-endian と同様に動作します。倍精度浮動小数点数については、ふたつのリトルエンディアンワードが ビッグエンディアンの順で書き出されます (例えばマシンレジスタ上でのビットパターンが #x0102030405060708の場合、出力は #x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05となります)。

デフォルトエンディアン値はスレッドローカルです。parameterize (gauche.parameter - パラメータ参照)を用いることで、この値を特定のダイナミックスコープの 間だけ変更することができます。

ポートを用いたI/O

Function: read-u8 &optional port endian

Function: read-u16 &optional port endian

Function: read-u32 &optional port endian

Function: read-u64 &optional port endian

それぞれ指定したエンディアンでportから8、16、32、64ビット符号無 整数を読み込みます。portが省略された場合は、現在の入力ポートが使 われます。portが整数の読み込みが完了する前にEOFに到達してしまっ た場合にはEOFが返ります。

Function: read-s8 &optional port endian

Function: read-s16 &optional port endian

Function: read-s32 &optional port endian

Function: read-s64 &optional port endian

それぞれ指定したエンディアンでportから8、16、32、64ビット、2の補 数符号付き整数を読み込みます。portが省略された場合は、現在の入力 ポートが使われます。portが整数の読み込みが完了する前にEOFに到 達してしまった場合にはEOFが返ります。

Function: read-uint size &optional port endian

Function: read-sint size &optional port endian

さらに柔軟性が高く、sizeオクテットの符号無しあるいは符号付き整数 をportから指定のエンディアンで読み込みます。 portが整数の読み込みが完了する前にEOFに到 達してしまった場合にはEOFが返ります。

Function: read-ber-integer &optional port

X.209のBER圧縮形式整数を読み込みます。BER圧縮形式整数は128進符号無し整 数です。最上位桁が最初にきます。最下位桁のバイトをのぞき、すべてのバイ トの最上位ビットはオンになっています。

Function: write-u8 val &optional port endian

Function: write-u16 val &optional port endian

Function: write-u32 val &optional port endian

Function: write-u64 val &optional port endian

それぞれ指定したエンディアンでportへ 8、16、32、64ビット、符号無 し整数として表現されている非負整数valを書き出します。 valはそれぞれ指定したビット数の範囲で表現できる値でなければなり ません。portが省略された場合は、現在の出力ポートが使われます。

Function: write-s8 val &optional port endian

Function: write-s16 val &optional port endian

Function: write-s32 val &optional port endian

Function: write-s64 val &optional port endian

それぞれ指定したエンディアンでportへ 8、16、32、64ビット、2の補 数符号付き整数として表現されている整数valを書き出します。 valはそれぞれ指定したビット数の範囲で表現できる値でなければなり ません。portが省略された場合は、現在の出力ポートが使われます。

Function: write-uint size val &optional port endian

Function: write-sint size val &optional port endian

さらに柔軟性が高く、sizeオクテットの符号無しあるいは符号付き整数 valをportへ、指定のエンディアンで書き出します。 portが省略された場合は、現在の出力ポートが使われます。

Function: write-ber-integer val &optional port

BER圧縮形式の非負整数valをportへ書き出します。 BER圧縮形式については前述のread-ber-integerを見てください。

Function: read-f16 &optional port endian

Function: read-f32 &optional port endian

Function: read-f64 &optional port endian

それぞれ、16、32、64ビットの浮動小数点数を読み込みます。 32ビットはIEEE754単精度、64ビットは倍精度の浮動小数点数です。 16ビット浮動小数点数は、1ビットの符号、5ビットの指数、10ビットの仮数からなる、 HDRイメージフォーマット等に使われている形式です。

portが省略された場合には、 現在の入力ポートが使われます。portが数値の読み込みが完了する前に EOFに到達してしまった場合にはEOFが返ります。

Function: write-f16 val &optional port endian

Function: write-f32 val &optional port endian

Function: write-f64 val &optional port endian

実数値valを、それぞれ16、32、64ビットの浮動小数点数として 書き出します。 portが省略された場合には、現在の出力ポートが使われます。

ユニフォームベクタを用いたI/O

以下のルーチンでは、引数 uv は任意の型のユニフォームベクタをとり えます。u8vector ではない場合には (uvector-alias <u8vector> uv) が呼ばれたのと同様の扱いになります。すなわち、 uvectorの内容を保持するメモリイメージから直接読み込まれます。pos 引数は当該のメモリ領域の最初からのバイト位置を指定するのに使います(こ れはユニフォームベクタの要素のサイズにかかわらず、つねにバイト位置です)。

Function: get-u8 uv pos &optional endian

Function: get-u16 uv pos &optional endian

Function: get-u32 uv pos &optional endian

Function: get-u64 uv pos &optional endian

Function: get-s8 uv pos &optional endian

Function: get-s16 uv pos &optional endian

Function: get-s32 uv pos &optional endian

Function: get-s64 uv pos &optional endian

Function: get-f16 uv pos &optional endian

Function: get-f32 uv pos &optional endian

Function: get-f64 uv pos &optional endian

ユニフォームベクタ uv のバイト位置 pos から指定したフォー マットで数値を読み込み、その数値を返します。指定した位置が当該ユニフォー ムベクタの内容のある範囲外を参照するものであった場合、エラーを示すシグ ナルがあがります。

Function: get-u16be uv pos

Function: get-u16le uv pos

Function: get-u32be uv pos

Function: get-u32le uv pos

Function: get-u64be uv pos

Function: get-u64le uv pos

Function: get-s16be uv pos

Function: get-s16le uv pos

Function: get-s32be uv pos

Function: get-s32le uv pos

Function: get-s64be uv pos

Function: get-s64le uv pos

Function: get-f16be uv pos

Function: get-f16le uv pos

Function: get-f32be uv pos

Function: get-f32le uv pos

Function: get-f64be uv pos

Function: get-f64le uv pos

これらは、get-* 手続のエンディアン(ビッグエンディアン be あるいはリトルエンディアン le)を指定した版です。スピードを要求 されるコードではオプション引数処理のオーバーヘッドを避けるためこちらを 使うのがいいでしょう。

Function: put-u8! uv pos val &optional endian

Function: put-u16! uv pos val &optional endian

Function: put-u32! uv pos val &optional endian

Function: put-u64! uv pos val &optional endian

Function: put-s8! uv pos val &optional endian

Function: put-s16! uv pos val &optional endian

Function: put-s32! uv pos val &optional endian

Function: put-s64! uv pos val &optional endian

Function: put-f16! uv pos val &optional endian

Function: put-f32! uv pos val &optional endian

Function: put-f64! uv pos val &optional endian

数値 val をユニフォームベクタ uv のバイト位置 pos か ら指定されたフォーマットで書き出します。指定した位置が当該ユニフォーム ベクタの内容のある範囲外を参照するものであった場合、エラーを示すシグナ ルがあがります。

Function: put-u16be! uv pos val

Function: put-u16le! uv pos val

Function: put-u32be! uv pos val

Function: put-u32le! uv pos val

Function: put-u64be! uv pos val

Function: put-u64le! uv pos val

Function: put-s16be! uv pos val

Function: put-s16le! uv pos val

Function: put-s32be! uv pos val

Function: put-s32le! uv pos val

Function: put-s64be! uv pos val

Function: put-s64le! uv pos val

Function: put-f16be! uv pos val

Function: put-f16le! uv pos val

Function: put-f32be! uv pos val

Function: put-f32le! uv pos val

Function: put-f64be! uv pos val

Function: put-f64le! uv pos val

これらは、put-* 手続のエンディアン(ビッグエンディアン be あるいはリトルエンディアン le)を指定した版です。スピードを要求 されるコードではオプション引数処理のオーバーヘッドを避けるためこちらを 使うのがいいでしょう。

互換性への注

read-u8 などは read-binary-uint8 と呼ばれていたもので、 read-f32 や read-f64 はそれぞれ read-binary-float、 read-binary-double と呼ばれていたものです。 これらの古い名前は後方互換のためいまのところサポートされていますが、使 用については非推奨とします。この変更は名前の短縮とユニフォームベクタと の一貫性維持のために行われました。

This document was generated by Shiro Kawai on November, 22 2009 using texi2html 1.78.