21. Binary file

この章では、データを最小限のコストでファイルとやり取りする方法を学びます。

21.1 バイナリファイルとは

バイナリファイル は、データをテキストではなく バイナリデータ 形式で保存したものです。例えば 299792458 という int32 型の数値は、"299792458" という 9 文字（9 バイト) ではなく、00010001110111100111100001001010 のビット列で表される 4 バイトのデータとして保存します。

データをファイルに保存する際、テキスト形式で保存すると、テキストから数値、数値からテキストへの変換にコストがかかり、必要なサイズも大きくなります。一方、バイナリデータは変換のコストがかからず、コンパクトな固定サイズのデータ容量しか必要としません。

int32 や double などのプリミティブ型や、プリミティブ型で構成された trivially copyable なクラス (Point, Vec2, Rect, ColorF) などは、単純にデータをコピーするだけで容易にバイナリデータとして扱えますが、Array や String など、ポインタで内部データを管理するデータ型をバイナリデータとして適切に扱には少し手間がかかります。

この章の後半て説明する シリアライズ機能 を使うと、Array や String, その他いくつかの Siv3D の trivially copyable でないクラスを簡単にバイナリデータとして扱えるようになります。独自に定義した型をシリアライズに対応させることもできます。

21.2 バイナリファイルに単純な値を書き込む

ファイルにバイナリデータを書き込むには BinaryWriter の機能を使います。BinaryWriter のコンストラクタ引数に、書き込み先のファイルのパスを渡します。このファイルパスは、実行ファイルがあるフォルダ（開発中は App フォルダ）を基準とする相対パスか、絶対パスを使用します。ファイルが使用中だったり、ファイル名が不正なものだったりしてオープンに失敗したかどうかは if (!writer) で調べられます。

同名のファイルがすでに存在する場合はそれを破棄してからオープンし、存在しない場合は新しい空のファイルを作成してオープンします。

.BinaryWriter::write() に trivially copyable な型の値を渡すと、その値のバイナリデータをコピーしてファイルの末尾に追加で書き込みます。

# include <Siv3D.hpp>

// ゲームのスコアを記録する構造体
struct GameScore
{
    int32 a, b, c, d;
};

void Main()
{
    // 書き込み用のバイナリファイルをオープン
    BinaryWriter writer(U"test.bin");

    if (!writer) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test.bin`");
    }

    // int32 型の値 (4 バイト) を書き込む
    writer.write(777);

    // double 型の値 (8 バイト) を書き込む
    writer.write(3.1415);

    // Point 型の値 (8 バイト) を書き込む
    writer.write(Point(123, 456));

    // GameScore 型の値 (16 バイト) を書き込む
    const GameScore s = { 10, 20, 30, 40 };
    writer.write(s);

    while (System::Update())
    {

    } 

    // writer のデストラクタで自動的にファイルがクローズされる
}

21.3 バイナリファイルから単純な値を読み込む

バイナリファイルからバイナリデータを読み込むには BinaryReader の機能を使います。BinaryReader のコンストラクタ引数に、読み込みたいテキストファイルのパスを渡します。このファイルパスは、実行ファイルがあるフォルダ（開発中は App フォルダ）を基準とする相対パスか、絶対パスを使用します。リリース用のアプリを作るときには埋め込みリソースパスの使用を推奨します。ファイルが存在しない場合など、オープンに失敗したかどうかは if (!reader) で調べられます。

オープン直後は、読み込み位置はファイルの先頭にセットされています。BinaryReader::read() に trivially copyable な型の変数を参照で渡すと、読み込み位置を始点とし、その値のサイズ分のバイナリデータを読み込んでその変数にコピーし、読み込み位置をその分進めて true を返します。読み込み位置がすでにファイルの終端にあって、これ以上読み込めないときには false を返します。

# include <Siv3D.hpp>

// ゲームのスコアを記録する構造体
struct GameScore
{
    int32 a, b, c, d;
};

void Main()
{
    // バイナリファイルをオープン
    BinaryReader reader(U"test.bin");

    if (!reader) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test.bin`");
    }

    // int32 型の値 (4 バイト) を読み込む
    int32 n;
    reader.read(n);
    Print << n;

    // double 型の値 (8 バイト) を読み込む
    double d;
    reader.read(d);
    Print << d;

    // Point 型の値 (8 バイト) を読み込む
    Point pos;
    reader.read(pos);
    Print << pos;

    // GameScore 型の値 (16 バイト) を読み込む
    GameScore s;
    reader.read(s);
    Print << U"{}, {}, {}, {}"_fmt(s.a, s.b, s.c, s.d);

    while (System::Update())
    {

    }

    // reader のデストラクタで自動的にファイルがクローズされる
}

読み込み位置の移動

BinaryReader::setPos() で、読み込み位置を指定した場所に移動できます。 BinaryReader::skip() で、指定したサイズ分読み飛ばすことができます。

# include <Siv3D.hpp>

// ゲームのスコアを記録する構造体
struct GameScore
{
    int32 a, b, c, d;
};

void Main()
{
    // バイナリファイルをオープン
    BinaryReader reader(U"test.bin");

    if (!reader) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test.bin`");
    }

    // 先頭から 4 バイト進んだ位置に移動
    reader.setPos(4);

    // double 型の値 (8 バイト) を読み込む
    double d;
    reader.read(d);
    Print << d;

    // 8 バイト分読み飛ばす
    reader.skip(8);

    // GameScore 型の値 (16 バイト) を読み込む
    GameScore s;
    reader.read(s);
    Print << U"{}, {}, {}, {}"_fmt(s.a, s.b, s.c, s.d);

    while (System::Update())
    {

    }

    // reader のデストラクタで自動的にファイルがクローズされる
}

21.4 ファイルをオープン・クローズするタイミングを制御する

BinaryReader のコンストラクタでファイルをオープンせずに、BinaryReader::open() でファイルをオープンすることもできます。オープンに成功した場合は true, 失敗した場合は false を返します。

また通常は BinaryReader のデストラクタが実行されるタイミングでファイルがクローズされますが、例えば内容を読み込んだあとにファイルを削除したり、別の内容を書き込みたい場合には、ファイルがオープンされたままだと操作ができないため、すぐにクローズしたいというケースがあるでしょう。そうしたときには BinaryReader::close() でファイルを明示的にクローズします。

# include <Siv3D.hpp>

void Main()
{
    BinaryReader reader;

    if (!reader.open(U"test.bin")) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test.bin`");
    }

    // int32 型の値 (4 バイト) を読み込む
    int32 n;
    reader.read(n);
    Print << n;

    // ファイルを明示的にクローズ
    reader.close();

    while (System::Update())
    {

    }
}

21.5 バイナリファイルに複雑なデータを書き込む

String や Array のように単純にコピーできない (trivially copyable でない) データをバイナリファイルで扱うのは少し手間がかかります。後述するシリアライズ機能を使えば簡単になりますが、まずはシリアライズ機能を使わないサンプルを紹介します。

# include <Siv3D.hpp>

void Main()
{
    // 書き込み用のバイナリファイルをオープン
    BinaryWriter writer(U"test-no-serialize.bin");

    if (!writer) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test-no-serialize.bin`");
    }

    // 書き込みたいテキスト
    const String text = U"Hello, Siv3D";

    // 書き込みたいテキストの長さ
    const uint64 length = text.length();

    // テキストの長さを書き込む
    writer.write(length);

    // テキストデータを書き込む
    writer.write(text.data(), sizeof(char32) * length);

    while (System::Update())
    {

    }

    // writer のデストラクタで自動的にファイルがクローズされる
}

21.6 バイナリファイルから複雑なデータを読み込む

前項に続いて、String や Array のように単純にコピーできない (trivially copyable でない) データを、シリアライズ機能を使わずにバイナリファイルで扱う方法です。

# include <Siv3D.hpp>

void Main()
{
    // バイナリファイルをオープン
    BinaryReader reader(U"test-no-serialize.bin");

    if (!reader) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test-no-serialize.bin`");
    }

    // 書き込みたいテキストの長さ
    uint64 length = 0;

    // 書き込みたいテキスト
    String text;

    // テキストの長さを読み込む
    reader.read(length);

    if (0 < length)
    {
        // テキストデータの読み込みのためにリサイズ
        text.resize(length);

        // テキストのサイズ分だけデータを読み込む
        reader.read(text.data(), sizeof(char32) * length);
    }

    Print << length;

    Print << text;

    while (System::Update())
    {

    }

    // reader のデストラクタで自動的にファイルがクローズされる
}

21.7 バイナリファイルに複雑なデータを書き込む（シリアライズ機能）

シリアライズ機能を使うと、シリアライズに対応したデータ型 (trivially copyable でない型も含む) を、少ない記述でバイナリファイルで扱えます。ファイルにシリアライズ機能を使ってバイナリデータを書き込むには Serializer<BinaryWriter> の機能を使います。Serializer<BinaryWriter> のコンストラクタ引数に、書き込み先のファイルのパスを渡します。実行ファイルがあるフォルダ（開発中は App フォルダ）を基準とする相対パスか、絶対パスを使用します。ファイルが使用中だったり、ファイル名が不正なものだったりしてオープンに失敗したかどうかは if (!writer.getWriter()) で調べられます。 Serializer<BinaryWriter>::operator() で値を渡すと、そのデータをシリアライズしてファイルの末尾に追加で書き込みます。

# include <Siv3D.hpp>

void Main()
{
    // 書き込み用のバイナリファイルをオープン
    Serializer<BinaryWriter> writer(U"test-serialize.bin");

    if (!writer.getWriter()) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test-serialize.bin`");
    }

    // 書き込みたいテキスト
    const String text = U"Hello, Siv3D";

    // バイナリファイルにシリアライズ対応型のデータを書き込む
    writer(text);

    while (System::Update())
    {

    }

    // writer のデストラクタで自動的にファイルがクローズされる
}

21.8 バイナリファイルから複雑なデータを読み込む（シリアライズ機能）

シリアライズ機能を使って書き込んだデータを読み込むには Deserializer<BinaryReader> の機能を使います。Deserializer<BinaryReader> のコンストラクタ引数に、読み込みたいテキストファイルのパスを渡します。このファイルパスは、実行ファイルがあるフォルダ（開発中は App フォルダ）を基準とする相対パスか、絶対パスを使用します。リリース用のアプリを作るときには埋め込みリソースパスの使用を推奨します。ファイルが存在しない場合など、オープンに失敗したかどうかは if (!reader.getReader()) で調べられます。 Deserializer<BinaryReader>::operator() で値を渡すと、そのデータをシリアライズしてファイルの末尾に追加で書き込みます。

# include <Siv3D.hpp>

void Main()
{
    // バイナリファイルをオープン
    Deserializer<BinaryReader> reader(U"test-serialize.bin");

    if (!reader.getReader()) // もしオープンに失敗したら
    {
        throw Error(U"Failed to open `test-serialize.bin`");
    }

    // 読み込み先のテキスト
    String text;

    // バイナリファイルからシリアライズ対応型のデータを読み込む
    // （自動でリサイズが行われる）
    reader(text);

    Print << text.length();

    Print << text;

    while (System::Update())
    {

    }

    // reader のデストラクタで自動的にファイルがクローズされる
}

21.9 ユーザ定義型をシリアライズに対応させる

ユーザが定義したクラスをシリアライズに対応させるには、template <class Archive> void SIV3D_SERIALIZE(Archive& archive) という public メンバ関数をクラスに実装します。archive() に、シリアライズに対応したオブジェクトを渡すコードを書くと、そのクラスはシリアライズ可能になり、Serializer や Deserializer で読み書きできるようになります。

# include <Siv3D.hpp>

// ユーザデータとゲームのスコアを記録する構造体
struct GameScore
{
    String name;

    int32 id;

    int32 score;

    // シリアライズに対応させるためのメンバ関数を定義する
    template <class Archive>
    void SIV3D_SERIALIZE(Archive& archive)
    {
        archive(name, id, score);
    }
};

void Main()
{   
    {
        // 記録したいデータ
        const Array<GameScore> scores =
        {
            GameScore{ U"Player1", 111, 1000 },
            GameScore{ U"Player2", 222, 2000 },
            GameScore{ U"Player3", 333, 3000 },
        };

        // バイナリファイルをオープン
        Serializer<BinaryWriter> writer(U"score.bin");

        if (!writer.getWriter()) // もしオープンに失敗したら
        {
            throw Error(U"Failed to open `score.bin`");
        }

        // シリアライズに対応したデータを記録
        writer(scores);

        // writer のデストラクタで自動的にファイルがクローズされる
    }

    // 読み込み先のデータ
    Array<GameScore> scores;
    {
        // バイナリファイルをオープン
        Deserializer<BinaryReader> reader(U"score.bin");

        if (!reader.getReader()) // もしオープンに失敗したら
        {
            throw Error(U"Failed to open `score.bin`");
        }

        // バイナリファイルからシリアライズ対応型のデータを読み込む
        // （自動でリサイズが行われる）
        reader(scores);

        // reader のデストラクタで自動的にファイルがクローズされる
    }

    // 読み込んだスコアを確認
    for (const auto& score : scores)
    {
        Print << U"{}(id: {}): {}"_fmt(score.name, score.id, score.score);
    }

    while (System::Update())
    {

    }   
}