MGL::File::ThrowingHandle#

概要#

MGL::File::ThrowingHandleはファイルに対するアクセス機能を提供し、失敗時に例外によって失敗理由を送出するクラスです。

失敗理由を手動でハンドリングしたい場合はMGL::File::Handleを使用してください。

宣言#

namespace MGL::File
{
    class ThrowingHandle;
}

メンバ情報#

種類

名前

内容

バージョン

関数

コンストラクタ

1.0.0+

関数

Open

ファイルをオープン

1.0.0+

関数

Close

ファイルをクローズ

1.0.0+

関数

IsOpen

ファイルがオープンされているかを取得

1.0.0+

関数

Read

ファイルの読み込み

1.0.0+

関数

Write

ファイルに書き込み

1.0.0+

関数

Seek

ストリーム位置を設定

1.0.0+

関数

Skip

ストリーム位置をスキップ

1.0.0+

関数

GetOffset

ストリーム位置を取得

1.0.0+

関数

IsEOF

ファイルストリームが終端に達しているかを取得

1.0.0+

関数

GetSize

オープンしているファイルのサイズを取得

1.0.0+

コンストラクタ#

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        // (1) 空のハンドルを生成
        constexpr ThrowingHandle() noexcept;

        // (2) 生成と同時にファイルをオープン
        ThrowingHandle(const PathView &path, OpenMode mode = OpenMode::Read);
    };
}

引数#

(1) 空のハンドルを生成

引数なし

(2) 生成と同時にファイルをオープン
const MGL::File::PathView &path

オープンするファイルのパス

MGL::File::OpenMode mode

オープンモード

例外#

(1) 空のハンドルを生成

送出しない

(2) 生成と同時にファイルをオープン
MGL::File::Result

失敗理由を表す処理結果

説明#

ファイルハンドルのコンストラクタです。

(1)は空のファイルハンドルを生成します。この方法で生成したハンドルはOpenを呼び出す必要があります。

(2)はファイルハンドルの生成とオープンを同時に行います。オープンに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

// (1) 空のハンドルを生成して読み込み専用でオープン
try
{
    MGL::File::ThrowingHandle handle;
    handle.Open("$user/test.data");
}
catch (const MGL::File::Result &result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

// (2) 生成と同時にファイルをオープン（効果は(1)と同等）
try
{
    MGL::File::ThrowingHandle handle("$user/test.data");
}
catch (const MGL::File::Result &result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

Open#

ファイルをオープン

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        void Open(const PathView &path, OpenMode mode = OpenMode::Read);
    };
}

引数#

const MGL::File::PathView &path

オープンするファイルのパス

MGL::File::OpenMode mode

オープンモード

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

指定されたモードでファイルをオープンします。オープンに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

ファイルパスはマウント名を含んだフォーマットになります。詳しくはファイルパスのフォーマットを参照してください。

modeを省略した場合はMGL::File::OpenMode::Readとして扱われます。

利用例#

try
{
    MGL::File::ThrowingHandle handle;

    // ファイルをオープン
    handle.Open("$user/test.data");
}
catch (const MGL::File::Result &result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

Close#

ファイルをクローズ

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        void Close();
    };
};

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

オープンしているファイルをクローズします。ファイルのクローズの動作は使用するデリゲートによって異なりますが、一般的にはハンドルはオープンされていない状態に戻ります。

ファイルをオープンしている状態でハンドルクラスの寿命が切れた場合、クローズ処理は自動で行われるため、通常はこの関数を明示的に呼び出す必要はありません。デリゲートがクローズ処理に失敗する可能性があり、その内容をハンドリングする必要がある場合において使用してください。

ファイルがオープンされていない場合、この関数は何もせず例外の送出も行いません。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    /*
     *  ファイルアクセス処理
     */

    handle.Close();     // 明示的なクローズ処理
                        // クローズ処理のエラーハンドリングを行わない場合は省略可能
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

IsOpen#

ファイルがオープンされているかを取得

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        [[nodiscard]] MGL_MAYBE_CONSTEXPR bool IsOpen() const noexcept;
    };
}

戻り値#

bool

オープンされている場合にtrue、されていない場合はfalse

説明#

ファイルハンドルがオープン済みかを取得します。この関数は例外を送出しません。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // ファイルがオープンされているかをチェック
    if (handle.IsOpen())
    {
        // オープンに失敗した場合は例外を送出するため、ここには必ず到達する
    }

    // ファイルをクローズ
    handle.Close();

    // ファイルがオープンされているかを再度チェック
    if (handle.IsOpen())
    {
        // クローズされたのでここには到達しない
    }
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.1.14
MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

MGL 1.0.0

  • 初回リリース

関連#

Read#

ファイルの読み込み

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        size_t Read(void *buffer, size_t size);
    };
}

引数#

void *buffer

読み込んだデータを格納するバッファのアドレス

size_t size

読み込むサイズ（バイト数）

戻り値#

size_t

実際に読み込んだバイト数

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

現在のストリーム位置から最大でsizeバイト分のデータを読み込み、その内容をbufferへと格納します。読み込み後はストリームのオフセットが更新されます。

戻り値には実際に読み込んだバイト数が返されます。

読み込みに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    std::byte buffer[16];

    // 読み込み
    auto readSize = handle.Read(buffer, 16);
    printf("%zuバイト読み込み成功。\n", readSize);
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

Write#

ファイルに書き込み

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        size_t Write(const void *buffer, size_t size);
    };
}

引数#

void *buffer

書き込むデータが格納されているアドレス

size_t size

書き込むサイズ（バイト数）

戻り値#

size_t

実際に書き込んだバイト数

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

指定したbufferの内容を、現在のストリーム位置からsizeバイト分だけファイルに書き込みます。書き込み後はストリームのオフセットが更新されます。

戻り値には実際に書き込んだバイト数が返されます。

書き込みに失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data", MGL::File::OpenMode::Write);

    const MGL::STL::string kTestMessage("Hello, MGL");

    // 書き込み
    auto writeSize = handle.Write(kTestMessage.c_str(), kTestMessage.size());
    printf("%zuバイト書き込み成功。\n", writeSize);
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

Seek#

ストリーム位置を設定

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        // (1) int32_t 型でオフセットを指定
        size_t Seek(SeekType seekType, int32_t offset);

        // (2) size_t 型でオフセットを指定
        size_t Seek(SeekType seekType, size_t offset);
    };
}

引数#

(1) int32_t型でオフセットを指定
MGL::File::SeekType seekType

シークタイプ

int32_t offset

オフセット

(2) size_t型でオフセットを指定
MGL::File::SeekType seekType

シークタイプ

size_t offset

オフセット

戻り値#

size_t

設定後のストリーム位置

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

オープン済みのファイルのストリーム位置を変更します。

seekTypeは続くoffsetの基準位置を指定します。詳細はMGL::File::SeekTypeの説明を参照してください。

(1)と(2)の違いはオフセットの型のみです。seekTypeにMGL::File::SeekType::Currentを指定した場合において、オフセットに負数を指定する場合にint32_t型を利用します。

シークに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // 先頭から8バイト目にストリーム位置を設定
    auto position = handle.Seek(MGL::File::SeekType::Top, 8);

    printf("現在のストリーム位置: %zu\n", position);
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

Skip#

ストリーム位置をスキップ

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        size_t Skip(size_t size);
    };
}

引数#

size_t size

スキップするサイズ

戻り値#

size_t

スキップ後のストリーム位置

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

オープン済みのファイルのストリーム位置をsizeバイト分先に進めます。この関数はSeekにSeekType::Currentを指定した場合と等価です。

スキップに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // 現在のストリーム位置から8バイト分スキップ
    auto position = handle.Skip(8);

    printf("現在のストリーム位置: %zu\n", position);
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

GetOffset#

ストリーム位置を取得

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        [[nodiscard]] size_t GetOffset();
    };
}

戻り値#

size_t

現在のストリーム位置

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

オープン済みのファイルのストリーム位置を取得します。

戻り値として現在のストリーム位置が返ります。失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // 現在のストリーム位置から8バイト分スキップ
    handle.Skip(8);

    // 現在のストリーム位置を取得
    auto position = handle.GetOffset();

    printf("現在のストリーム位置: %zu\n", position);
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

MGL 1.0.0

  • 初回リリース

関連#

IsEOF#

ファイルストリームが終端に達しているかを取得

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        [[nodiscard]] bool IsEOF();
    };
}

戻り値#

bool

ストリーム位置が終端に達していればtrue、そうでなければfalse

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

オープン済みのファイルに対し、現在のストリーム位置が終端に達しているかを取得します。

オープンしていないファイルハンドルに対して呼び出した場合など、取得に失敗した場合は失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // ファイルの終端に達するまで1バイトづつ読み込んで表示
    while (!handle.IsEOF())
    {
        uint8_t byte;
        handle.Read(&byte, 1);

        printf("%02X\n", byte);
    }
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

MGL 1.0.0

  • 初回リリース

GetSize#

オープンしているファイルのサイズを取得

宣言#

namespace MGL::File
{
    class ThrowingHandle
    {
    public:
        [[nodiscard]] size_t GetSize();
    };
}

戻り値#

size_t

オープンしているファイルのサイズ（バイト数）

例外#

MGL::File::Result

失敗理由を表す処理結果

説明#

オープン済みのファイルのサイズを取得します。この関数の戻り値はシーク可能な最大オフセットと同値です。

取得に失敗した場合、失敗理由を表すMGL::File::Resultを例外として送出します。

利用例#

try
{
    MGL::File::ThrowingHandle handle("$user/test.data");

    // ファイルサイズを取得して表示
    auto size = handle.GetSize();
    printf("ファイルサイズ: %zu\n", size);
}
catch (const MGL::File::Result &result)
{
    printf("ファイルアクセス失敗: %d\n", result.GetErrorCode());
}

バージョン情報#

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

MGL 1.0.0

  • 初回リリース