MGL::File::Handle

概要

MGL::File::Handleはファイルに対するアクセス機能を提供するクラスです。

このクラスは処理の成否を手動でハンドリングする必要があります。例外を用いて失敗理由を取得したい場合はMGL::File::ThrowingHandleを使用してください。

宣言

namespace MGL::File
{
    class Handle;
}

メンバ情報

種類	名前	内容	バージョン
関数	コンストラクタ	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+
関数	GetResult	処理結果の取得	1.0.0+
関数	HasError	最後の処理結果でエラーが発生しているかを取得	1.0.0+

---

コンストラクタ

宣言

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

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

引数

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

引数なし

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

const MGL::File::PathView &path

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

MGL::File::OpenMode mode

オープンモード

説明

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

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

(2)はファイルハンドルの生成とオープンを同時に行います。

利用例

// (1) 空のハンドルを生成して読み込み専用でオープン
MGL::File::Handle handle;
handle.Open("$user/test.data")
if (!handle.IsOpen())
{
    // オープンに失敗した場合はここに到達
}

// (2) 生成と同時にファイルをオープン（効果は(1)と同等）
MGL::File::Handle handle("$user/test.data");
if (!handle.IsOpen())
{
    // オープンに失敗した場合はここに到達
}

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::Open

• MGL::File::PathView

---

Open

ファイルをオープン

宣言

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

引数

const MGL::File::PathView &path

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

MGL::File::OpenMode mode

オープンモード

戻り値

MGL::File::Result

処理結果

説明

指定されたモードでファイルをオープンし、処理結果をMGL::File::Resultで返します。

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

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

利用例

MGL::File::Handle handle;

auto result = handle.Open("$resource/image.png");

if (!result)
{
    printf("ファイルのオープンに失敗: %d\n", result.GetErrorCode());
}

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::OpenMode

• MGL::File::Handle::Close

• MGL::File::PathView

• ファイルパスのフォーマット

---

Close

ファイルをクローズ

宣言

namespace MGL::File
{
    class Handle
    {
    public:
        Result Close() noexcept;
    };
};

説明

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

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

ファイルがオープンされていない状態では、この関数は何もせずに成功を返します。

利用例

MGL::File::Handle handle("$resource/image.png");

if (handle.IsOpen())
{
    printf("ファイルのオープンに成功\n");
}

handle.Close();     // 明示的なクローズ処理
                    // もしファイルのオープンに失敗していた場合は何もしない

if (MGL::File::Handle handle2("$resource/image.png"); handle2.IsOpen())
{
    printf("ファイルのオープンに成功\n");
}

// この時点で handle2 は寿命が切れているため、クローズ処理も自動で行われている

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::Open

---

IsOpen

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

宣言

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

戻り値

bool

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

説明

ファイルハンドルがオープン済みかを取得します。

利用例

MGL::File::Handle handle("$resource/image.png");

if (handle.IsOpen())
{
    // ファイルのオープンに成功している場合はここに到達
}

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

if (handle.IsOpen())
{
    // クローズされたのでここには到達しない
}

バージョン情報

MGL 1.1.14

• constexprをMGL_MABYE_CONSTEXPRに変更

MGL 1.1.13

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

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::Open

• MGL::File::Handle::Close

---

Read

ファイルの読み込み

宣言

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

引数

void *buffer

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

size_t size

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

戻り値

size_t

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

説明

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

戻り値には実際に読み込んだバイト数が返されます。失敗した場合は0が返り、ハンドルが持つ処理結果にエラーが書き込まれます。

利用例

if (MGL::File::Handle handle("$resource/image.png"); handle.IsOpen())
{
    std::byte buffer[16];

    // 読み込み
    auto readSize = handle.Read(buffer, 16);

    // 読み込みに成功しているかをチェック
    if (handle.HasError())
    {
        printf("読み込み失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("%zuバイト読み込み成功。\n", readSize);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::GetResult

• MGL::File::Handle::HasError

---

Write

ファイルに書き込み

宣言

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

引数

void *buffer

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

size_t size

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

戻り値

size_t

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

説明

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

戻り値には実際に書き込んだバイト数が返されます。失敗した場合は0が返り、ハンドルが持つ処理結果にエラーが書き込まれます。

利用例

if (MGL::File::Handle handle("$user/test.data", MGL::File::OpenMode::Write); handle.IsOpen())
{
    const MGL::STL::string kTestMessage("Hello, MGL");

    // 書き込み
    auto writeSize = handle.Write(kTestMessage.c_str(), kTestMessage.size());

    // 書き込みに成功しているかをチェック
    if (handle.HasError())
    {
        printf("書き込み失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("%zuバイト書き込み成功。\n", writeSize);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::GetResult

• MGL::File::Handle::HasError

---

Seek

ストリーム位置を設定

宣言

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

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

引数

(1) int32_t型でオフセットを指定

MGL::File::SeekType seekType

シークタイプ

int32_t offset

オフセット

(2) size_t型でオフセットを指定

MGL::File::SeekType seekType

シークタイプ

size_t offset

オフセット

戻り値

size_t

設定後のストリーム位置

説明

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

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

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

シークに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合は0が返り、ハンドルの処理結果に失敗理由が書き込まれます。

利用例

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // 先頭から8バイト目にストリーム位置を設定
    auto position = handle.Seek(MGL::File::SeekType::Top, 8);

    // シークに成功しているかをチェック
    if (handle.HasError())
    {
        printf("シーク失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("現在のストリーム位置: %zu\n", position);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::SeekType

• MGL::File::Handle::Skip

---

Skip

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

宣言

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

引数

size_t size

スキップするサイズ

戻り値

size_t

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

説明

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

スキップに成功した場合、戻り値に現在のストリーム位置が返ります。失敗した場合は0が返り、ハンドルの処理結果に失敗理由が書き込まれます。

利用例

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // 現在のストリーム位置から8バイト分スキップ
    auto position = handle.Skip(8);

    // スキップに成功しているかをチェック
    if (handle.HasError())
    {
        printf("スキップ失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("現在のストリーム位置: %zu\n", position);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::Seek

---

GetOffset

ストリーム位置を取得

宣言

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

戻り値

size_t

現在のストリーム位置

説明

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

戻り値として現在のストリーム位置が返ります。処理に失敗した場合は0が返り、ハンドルの処理結果に失敗理由が書き込まれます。

利用例

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // 現在のストリーム位置から8バイト分スキップ
    handle.Skip(8);

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

    // 正しくストリーム位置が取得できたかチェック
    if (handle.HasError())
    {
        printf("取得失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("現在のストリーム位置: %zu\n", position);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.1.13

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

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::Seek

• MGL::File::Handle::Skip

---

IsEOF

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

宣言

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

戻り値

bool

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

説明

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

オープンしていないファイルハンドルに対して呼び出した場合など、取得に失敗している場合はtrueを返し、ハンドルの処理結果に失敗理由が書き込まれます。

利用例

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // ファイルの終端に達するまで1バイトづつ読み込んで表示
    while (!handle.IsEOF())
    {
        uint8_t byte;
        if (handle.Read(&byte, 1) == 1)
        {
            printf("%02X\n", byte);
        }
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.1.13

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

MGL 1.0.0

• 初回リリース

---

GetSize

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

宣言

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

戻り値

size_t

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

説明

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

取得に失敗した場合は0が返り、ハンドルが持つ処理結果にエラーが書き込まれます。

利用例

if (MGL::File::Handle handle("$user/test.data"); handle.IsOpen())
{
    // オープンしたファイルのサイズを取得
    auto size = handle.GetSize();

    // 取得に成功しているかをチェック
    if (handle.HasError())
    {
        printf("取得失敗: %d\n", handle.GetResult().GetErrorCode());
    }
    else
    {
        printf("ファイルサイズ: %zu\n", size);
    }
}
else
{
    printf("ファイルのオープンに失敗: %d\n", handle.GetResult().GetErrorCode());
}

バージョン情報

MGL 1.1.13

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

MGL 1.0.0

• 初回リリース

---

GetResult

処理結果の取得

宣言

namespace MGL::File
{
    class Handle
    {
    public:
        [[nodiscard]] constexpr const Result &GetResult() const noexcept;
    };
}

戻り値

MGL::File::Result

最後に実行した処理結果

説明

このハンドルが最後に実行した処理結果を取得します。

利用例

他の関数の利用例に含まれているた省略します。

バージョン情報

MGL 1.1.13

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

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Result

• MGL::File::Error

• MGL::File::Handle::HasError

---

HasError

最後の処理結果でエラーが発生しているかを取得

宣言

namespace MGL::File
{
    class Handle
    {
    public:
        [[nodiscard]] constexpr bool HasError() const noexcept;
    };
}

戻り値

bool

最後に実行した処理でエラーが発生している場合はtrue、成功している場合はfalse

説明

このハンドルが最後に実行した処理において、何らかのエラーが発生しているかを取得します。具体的な処理結果はGetResultにて取得します。

利用例

他の関数の利用例に含まれているた省略します。

バージョン情報

MGL 1.1.13

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

MGL 1.0.0

• 初回リリース

関連

• MGL::File::Handle::GetResult