MGL::File::Path#

概要#

MGL::File::PathはMGLが扱うファイルパスを表現するためのクラスです。

このクラスはMGLに設定されたアロケータを用いてメモリリソースを確保し、パスを表す文字列の保持・管理を自身で行います。引数や定数などの参照のみを行う用途においては、文字列を自身で管理しないMGL::File::PathViewの使用を推奨します。

MGLにおけるファイルパスのフォーマットについてはファイルパスのフォーマットを参照してください。

注釈

このクラスが扱うchar型はUTF-8エンコーディングのみを扱います。もし将来C++20に移行することになった場合、char型からchar8_t型に変更する予定です。

宣言#

namespace MGL::File
{
    class Path;
}

メンバ情報#

種類

名前

内容

バージョン

関数

コンストラクタ

1.1.8+

関数

Append

パス要素の追加

1.1.8+

関数

Concat

パス文字列の追加

1.1.8+

関数

operator /=

パス要素の追加のオペレータ

1.1.8+

関数

operator +=

パス文字列の追加のオペレータ

1.1.8+

関数

GetLength

パス文字列の長さを取得

1.1.8+

関数

IsEmpty

パスが空であるかを取得

1.1.8+

関数

GetRoot

ルートパスを取得

1.1.8+

関数

GetMountName

マウント名を取得

1.1.8+

関数

GetRelativePath

ルートパスを除いたパスを取得

1.1.8+

関数

GetParent

親ディレクトリのパスを取得

1.1.8+

関数

GetFilename

ファイル名を取得

1.1.8+

関数

GetStem

拡張子を除いたファイル名を取得

1.1.8+

関数

GetExtension

ファイルの拡張子を取得

1.1.8+

関数

Clear

パス文字列を空にする

1.1.8+

関数

Set

パス文字列を設定する

1.1.8+

関数

GetCString

パス文字列をconst char *型で取得

1.1.8+

関数

operator const char *

const char *型へのキャスト

1.1.8+

コンストラクタ#

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        // (1) 予約サイズを指定して初期化
        Path(size_t reserveSize = 0) noexcept;

        // (2) パス文字列を指定して初期化
        Path(const char *path) noexcept;

        // (3) パス文字列と予約サイズを指定して初期化
        Path(const char *path, size_t reserveSize) noexcept;
    };
}

引数#

(1) 予約サイズを指定して初期化
size_t reserveSize

予約サイズ。省略または0指定時にはサイズ予約を行わない

(2) パス文字列を指定して初期化
const char * path

設定するパス文字列

(3) パス文字列と予約サイズを指定して初期化
const char * path

設定するパス文字列

size_t reserveSize

予約サイズ。0指定時にはサイズ予約を行わない

説明#

パス文字列または予約サイズを指定して初期化を行うためのコンストラクタです。

パス文字列はMGLのファイルパスのフォーマットに従い、UTF-8エンコーディングである必要があります。

予約サイズreserveSizeは、メモリリソースの再確保を行わずに格納可能なパス文字列の最大サイズです。単位は終端文字を含めたバイト数です。パス文字列の変更や追加などにより予約サイズを超えた場合、メモリリソースの再確保とコピーによって拡張が行われます。

予約サイズを指定せずにパス文字列を与えた場合、最低でもその文字列の格納に必要なサイズが予約されます。

利用例#

/*
 * "$resource/image"ディレクトリ内のファイル"character.png" へのパスを生成する例
 */

// (1) 予約サイズを指定して初期化
MGL::File::Path path1(256);         // 256バイト確保
path1.Set("$resource/image");       // ディレクトリパスを設定
path1.Append("character.png");      // ファイル名を追加

// (2) パス文字列を指定して初期化
MGL::File::Path path2("$resource/image");
path2.Append("character.png");      // ここでメモリの再確保が行われる場合がある

// (3) パス文字列と予約サイズを指定して初期化
MGL::File::Path path3("$resource/image", 256);
path3.Append("character.png");      // 256バイト内に収まるため、再確保は行われない

バージョン情報#

MGL 1.1.8から利用可能

関連#

Append#

パス要素の追加

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        Path &Append(const char *element) noexcept;
    };
}

引数#

const chat * element

追加するパス要素の文字列

戻り値#

MGL::File::Path &

自身の参照

説明#

現在のパスの末尾に要素elementを追加します。パスが区切り文字( / )で終端されていない場合は自動で挿入します。

この関数はoperator /=によって代替可能です。

利用例#

$resource/imageディレクトリ内のファイルcharacter.pngへのパスを生成する例
MGL::File::Path path("$resource/image", 256);
path.Append("character.png");

MGL_TRACE("%s", path.GetCString());
処理結果
$resource/image/character.png

バージョン情報#

MGL 1.1.8から利用可能

関連#

Concat#

パス文字列の追加

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        // (1) 文字列を追加
        Path &Concat(const char *string) noexcept;

        // (2) 文字を追加
        Path &Concat(char character) noexcept;
    };
}

引数#

(1) 文字列を追加
const chat * string

追加するパス文字列

(2) 文字を追加
char character

追加する文字

戻り値#

MGL::File::Path &

自身の参照

説明#

現在のパスの末尾に文字または文字列を追加します。この関数はAppendとは異なり、区切り文字を挿入せずに単純に連結を行います。

この関数はoperator +=によって代替可能です。

利用例#

$resource/image/characterに拡張子.pngを追加する例
MGL::File::Path path("$resource/image/character", 256);
path.Concat(".png");

MGL_TRACE("%s", path.GetCString());
処理結果
$resource/image/character.png

バージョン情報#

MGL 1.1.8から利用可能

関連#

operator /=#

パス要素の追加のオペレータ

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        Path &operator /=(const char *element) noexcept;
    };
}

引数#

const chat * element

追加するパス要素の文字列

戻り値#

MGL::File::Path &

自身の参照

説明#

現在のパスの末尾に要素elementを追加します。パスが区切り文字( / )で終端されていない場合は自動で挿入します。

この関数の効果はAppendと同等です。

利用例#

$resource/imageディレクトリ内のファイルcharacter.pngへのパスを生成する例
MGL::File::Path path("$resource/image", 256);
path /= "character.png";

MGL_TRACE("%s", path.GetCString());
処理結果
$resource/image/character.png

バージョン情報#

MGL 1.1.8から利用可能

関連#

operator +=#

パス文字列の追加のオペレータ

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        // (1) 文字列を追加
        Path &operator +=(const char *string) noexcept;

        // (2) 文字を追加
        Path &operator +=(char character) noexcept;
    };
}

引数#

(1) 文字列を追加
const chat * string

追加するパス文字列

(2) 文字を追加
char character

追加する文字

戻り値#

MGL::File::Path &

自身の参照

説明#

現在のパスの末尾に文字または文字列を追加します。この関数はoperator /=とは異なり、区切り文字を挿入せずに単純に連結を行います。

この関数の効果はConcatと同等です。

利用例#

$resource/image/characterに拡張子.pngを追加する例
MGL::File::Path path("$resource/image/character", 256);
path += ".png";

MGL_TRACE("%s", path.GetCString());
処理結果
$resource/image/character.png

バージョン情報#

MGL 1.1.8から利用可能

関連#

GetLength#

パス文字列の長さを取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] size_t GetLength() const noexcept;
    };
}

戻り値#

size_t

パス文字列の長さ（終端文字を含まないバイト数）

説明#

パス文字列の長さを取得します。戻り値は終端文字を含まないバイト数です。

利用例#

$resource/image/character.pngのサイズを取得
MGL::File::Path path("$resource/image/character.png");

MGL_TRACE("length = %zu", path.GetLength());
処理結果
length = 29

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

IsEmpty#

パスが空であるかを取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] bool IsEmpty() const noexcept;
    };
}

戻り値#

bool

パスが空の場合はtrue、そうでなければfalse

説明#

このパスが空であるかを取得します。GetLength() == 0が成り立つ場合、この関数はtrueを返します。

利用例#

MGL::File::Path path;

MGL_TRACE("(1) pathは空で%s", path.IsEmpty() ? "ある" : "ない");

path += "$resource/";

MGL_TRACE("(2) pathは空で%s", path.IsEmpty() ? "ある" : "ない");
処理結果
(1) pathは空である
(2) pathは空でない

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

GetRoot#

ルートパスを取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetRoot() const noexcept;
    };
}

戻り値#

MGL::File::Path

ルートパス。失敗時は空のパス

説明#

現在のパスからルートパスを取得します。

MGLにおけるルートパスはマウント名の部分になります。POSIXにおける'/'や、Windowsにおけるドライブレター(C:など)とは異なる点にご注意ください。

パスにマウント名が含まれていない場合、この関数は空のパスを返します。

先頭に'$'を含まないマウント名のみを取得したい場合はGetMountNameを使用してください。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png"
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto rootPath = path.GetRoot();

    MGL_TRACE("%s -> %s", path.GetCString(), rootPath.GetCString());
}
処理結果
$resource/foo.png -> $resource
$resource/foo/bar.png -> $resource
/foo.png ->
/foo/bar.png ->

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

GetMountName#

マウント名を取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetMountName() const noexcept;
    };
}

戻り値#

MGL::File::Path

マウント名。失敗時は空のパス

説明#

現在のパスからマント名を取得します。パスにマウント名が含まれていない場合、この関数は空のパスを返します。

先頭に'$'を含むパスを取得したい場合はGetRootを使用してください。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png"
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto mountName = path.GetMountName();

    MGL_TRACE("%s -> %s", path.GetCString(), mountName.GetCString());
}
処理結果
$resource/foo.png -> resource
$resource/foo/bar.png -> resource
/foo.png ->
/foo/bar.png ->

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

GetRelativePath#

ルートパスを除いたパスを取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetRelativePath() const noexcept;
    };
}

戻り値#

MGL::File::Path

ルートパスを除いたパス

説明#

現在のパスからルートパスを除いたパスを取得します。

MGLにおけるルートパスはマウント名の部分になります。POSIXにおける'/'や、Windowsにおけるドライブレター(C:など)とは異なる点にご注意ください。

パスにマウント名が含まれていない場合、この関数は現在のパスをそのまま返します。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png"
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto rootPath = path.GetRoot();

    MGL_TRACE("%s -> %s", path.GetCString(), rootPath.GetCString());
}
処理結果
$resource/foo.png -> foo.png
$resource/foo/bar.png -> foo/bar.png
/foo.png -> /foo.png
/foo/bar.png -> /foo/bar.png

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

GetParent#

親ディレクトリのパスを取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetParent() const noexcept;
    };
}

戻り値#

MGL::File::Path

親ディレクトリのパス。失敗時は空のパス

説明#

現在のパスから親ディレクトリのパスを取得します。

この関数はパスの先頭から最後の区切り文字の前までをコピーして返します。パスに区切り文字が含まれていない場合や、パスの先頭が区切り文字である場合は空のパスを返します。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png",
    "foo.png",
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto parentPath = path.GetParent();

    MGL_TRACE("%s -> %s", path.GetCString(), parentPath.GetCString());
}
処理結果
$resource/foo.png -> $resource
$resource/foo/bar.png -> $resource/foo
/foo.png ->
/foo/bar.png -> /foo
foo.png ->

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

GetFilename#

ファイル名を取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetFilename() const noexcept;
    };
}

戻り値#

MGL::File::Path

ファイル名。失敗時は空のパス

説明#

現在のパスからファイル名を取得します。

この関数は最後の区切り文字の次の文字から末尾までをコピーして返します。パスの末尾が区切り文字である場合や、マウント名のみのパスである場合、この関数は空のパスを返します。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png",
    "$resource"
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto filename = path.GetFilename();

    MGL_TRACE("%s -> %s", path.GetCString(), filename.GetCString());
}
処理結果
$resource/foo.png -> foo.png
$resource/foo/bar.png -> bar.png
/foo.png -> foo.png
/foo/bar.png -> bar.png
$resource ->

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

GetStem#

拡張子を除いたファイル名を取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetStem() const noexcept;
    };
}

戻り値#

MGL::File::Path

拡張子を除いたパス

説明#

現在のパスから拡張子を除いたファイル名を取得します。

拡張子はファイル名に含まれる最後の'.'以降の文字列になります。例外として、ファイル名の先頭が'.'である場合（POSIXにおける隠しファイル）は拡張子として扱われません。

foo.tar.gzなどの複数の拡張子を持つファイル名の場合、最後の拡張子(.gz)だけが拡張子として扱われます。

パスが拡張子を持たない場合、ファイル名が有効であればそのファイル名をそのまま返します。パスがファイル名を持たない場合は空のパスを返します。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png",
    "/foo/bar/",
    "foo.tar.gz",
    "/foo/.bar"
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto stemPath = path.GetStem();

    MGL_TRACE("%s -> %s", path.GetCString(), stemPath.GetCString());
}
処理結果
$resource/foo.png -> foo
$resource/foo/bar.png -> bar
/foo.png -> foo
/foo/bar.png -> bar
/foo/bar/ ->
foo.tar.gz -> foo.tar
/foo/.bar -> .bar

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

GetExtension#

ファイルの拡張子を取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] Path GetExtension() const noexcept;
    };
}

戻り値#

MGL::File::Path

拡張子を除いたパス

説明#

現在のパスからファイル名の拡張子を取得します。

拡張子はファイル名に含まれる最後の'.'以降の文字列になります。例外として、ファイル名の先頭が'.'である場合（POSIXにおける隠しファイル）は拡張子として扱われません。

foo.tar.gzなどの複数の拡張子を持つファイル名の場合、最後の拡張子(.gz)だけが拡張子として扱われます。

ファイル名が取得できない場合、またはファイル名が拡張子を持たない場合は空のパスを返します。

利用例#

constexpr const char *kPathArray[] =
{
    "$resource/foo.png",
    "$resource/foo/bar.png",
    "/foo.png",
    "/foo/bar.png",
    "/foo/bar/",
    "foo.tar.gz",
    "/foo/.bar"
};

for (const auto *pathString : kPathArray)
{
    MGL::File::Path path(pathString);

    auto extension = path.GetExtension();

    MGL_TRACE("%s -> %s", path.GetCString(), extension.GetCString());
}
処理結果
$resource/foo.png -> .png
$resource/foo/bar.png -> .png
/foo.png -> .png
/foo/bar.png -> .png
/foo/bar/ ->
foo.tar.gz -> .gz
/foo/.bar ->

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

Clear#

パス文字列を空にする

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        void Clear() noexcept;
    };
}

説明#

パス文字列を空の文字列で上書きし、空のパスを生成します。

ヒント

この関数はコンストラクタで生成した空のパスとは異なり、元のメモリリソースを引き継ぎます。パフォーマンスの観点から、代入演算子を用いた初期化よりもこちらの関数の利用を推奨します。

利用例#

MGL::File::Path path("$resource/image/character.png");

MGL_TRACE("(1) %s", path.GetCString());

path.Clear();

MGL_TRACE("(2) %s", path.GetCString());
処理結果
(1) $resource/image/character.png
(2)

バージョン情報#

MGL 1.1.8から利用可能

関連#

Set#

パス文字列を設定する

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        void Set(const char *path) noexcept;
    };
}

引数#

const char * path

設定するパス文字列

説明#

パス文字列を引数で設定した文字列で上書きします。

ヒント

この関数はコンストラクタで生成したパスとは異なり、元のメモリリソースを引き継ぎます。パフォーマンスの観点から、代入演算子を用いた文字列の設定よりもこちらの関数の利用を推奨します。

利用例#

MGL::File::Path path("$resource/image/character.png");

MGL_TRACE("(1) %s", path.GetCString());

path.Set("$resource/image.png");

MGL_TRACE("(2) %s", path.GetCString());
処理結果
(1) $resource/image/character.png
(2) $resource/image.png

バージョン情報#

MGL 1.1.8から利用可能

関連#

GetCString#

パス文字列をconst char \*型で取得

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        [[nodiscard]] const char *GetCString() const noexcept;
    };
}

戻り値#

const char *

const char *型のパス文字列

説明#

このパスが保持しているパス文字列をconst char *型で取得します。

通常、このクラスは暗黙的にconst char *型へ変換されます。暗黙的な型変換に問題がある場合にこちらの関数を使用してください。

利用例#

MGL::File::Path path("$resource/image/character.png");

// 可変長引数は暗黙的な型変換を行えないため、明示的にこの関数を使用する
MGL_TRACE("%s", path.GetCString());

// puts() のような const char *型の引数に対してはそのまま渡せる
puts(path);

バージョン情報#

MGL 1.1.8から利用可能。

MGL 1.1.13から、戻り値に[[nodiscard]]属性を付与。

関連#

operator const char *#

const char \*型へのキャスト

宣言#

namespace MGL::File
{
    class Path
    {
    public:
        operator const char *() const noexcept;
    };
}

戻り値#

const char *

const char *型のパス文字列

説明#

このパスが保持しているパス文字列をconst char *型に変換するためのオペレータです。

パスはこのオペレータを通して暗黙的にconst char *への変換が行われます。暗黙的な変換に問題がある場合はGetCStringを使用してください。

利用例#

MGL::File::Path path("$resource/image/character.png");

// 可変長引数は暗黙的な型変換を行えないため、GetCString()を使用する
MGL_TRACE("%s", path.GetCString());

// puts() のような const char *型の引数に対してはそのまま渡せる
puts(path);

バージョン情報#

MGL 1.1.8から利用可能

関連#