MGL::File::PathView#

概要#

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

このクラスは自身で文字列を保持せず、外部から与えられたポインタ変数を通して参照のみを行います。メモリアロケータが使用できない状況やパフォーマンスに影響を与える場合などにおいて、const char *型やMGL::File::Pathの代替として使用することを想定しています。

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

重要

不正な参照を避けるため、メンバ変数などにパスを保持する場合はMGL::File::Pathを使用する必要があります。詳細はコンストラクタの解説を参照してください。

注釈

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

宣言#

namespace MGL::File
{
    class PathView;
}

種類

名前

内容

バージョン

関数

コンストラクタ

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+

関数

GetCString

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

1.1.8+

関数

operator const char *

const char *型へのキャスト

1.1.8+

コンストラクタ#

宣言#

namespace MGL::File
{
    class PathView
    {
    public:
        // (1) const char *型からパスを生成
        constexpr PathView(const char *path) noexcept;

        // (2) MGL::File::Pathからパスを生成
        PathView(const Path &path) noexcept
    };
}

引数#

(1) const char \*型からパスを生成
const char * path

初期化するパス文字列

(2) MGL::File::Pathからパスを生成
const MGL::File::Path &path

初期化するパス文字列

説明#

パス文字列へのポインタ変数から初期化するためのコンストラクタです。

このクラスは内部で文字列へのアドレスのみを保持します。 (2)のMGL::File::Pathから初期化した場合においても、MGL::File::Path::GetCStringで得られるアドレスのみを保持します。したがって、引数に指定する値は、このクラスの生存期間中は変更されることのない値である必要があります。

引数にnullptrを指定した場合、そのパスは空のパスとして扱われます。

ヒント

このクラスの安全性はconst char *型と同等であると考えてください。次に挙げる用途においてはパフォーマンス的に優位となりますが、それ以外の多くの場合はMGL::File::Pathの使用を推奨します。

  • パスを受ける関数の引数

  • プログラムに埋め込む定数

利用例#

// (1) const char *型からパスを生成
constexpr MGL::File::PathView kImagePath("$resource/image/character.png");

// (2) MGL::File::Pathからパスを生成
MGL::File::Path path("$resource/image/character.png");
MGL::File::PathView pathView(path);
パフォーマンスTips
// ファイルパスを扱う関数
//      もし引数に MGL::File::Path を使用した場合、呼び出しの度に
//      メモリリソースの確保と文字列のコピーが行われる。
//      MGL::File::PathView であれば、メモリの確保も文字列のコピーも行われない。
void AnyFileProcess(const MGL::File::PathView &path) noexcept
{
    // pathを使用した処理
    // pathの内容を保存したい場合は MGL::File::Path で保持する
}

// 呼び出し元関数
void CallerFunction() noexcept
{
    // const char *型で渡す場合
    // (1)が呼び出される
    AnyFileProcess("$resource/image.png");

    // MGL::File::Pathを渡す場合
    // (2)が呼び出される
    MGL::File::Path path("$resource/image.png");    // ここではアロケータが使用される
    AnyFileProcess(path);       // AnyFileProcess(path.GetCString()) と等価
}

バージョン情報#

MGL 1.1.8から利用可能

関連#

Append#

パス要素の追加

宣言#

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

引数#

const chat * element

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

戻り値#

MGL::File::Path

新たに生成されたパス

説明#

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

このクラスは読み取り専用であるため自身のパスは変更せず、新規にMGL::File::Pathを生成して返します。

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

利用例#

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

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

バージョン情報#

MGL 1.1.8から利用可能

関連#

Concat#

パス文字列の追加

宣言#

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

        // (2) 文字を追加
        [[nodiscard]] Path Concat(char character) const noexcept;
    };
}

引数#

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

追加するパス文字列

(2) 文字を追加
char character

追加する文字

戻り値#

MGL::File::Path

新たに生成されたパス

説明#

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

このクラスは読み取り専用であるため自身のパスは変更せず、新規にMGL::File::Pathを生成して返します。

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

利用例#

$resource/image/characterに拡張子.pngを追加する例
constexpr MGL::File::PathView kImageFilePath("$resource/image/character");
auto path = kImageFilePath.Concat(".png");

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

バージョン情報#

MGL 1.1.8から利用可能

関連#

operator /=#

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

宣言#

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

引数#

const chat * element

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

戻り値#

MGL::File::Path

新たに生成されたパス

説明#

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

このクラスは読み取り専用であるため自身のパスは変更せず、新規にMGL::File::Pathを生成して返します。

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

利用例#

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

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

バージョン情報#

MGL 1.1.8から利用可能

関連#

operator +=#

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

宣言#

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

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

引数#

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

追加するパス文字列

(2) 文字を追加
char character

追加する文字

戻り値#

MGL::File::Path

新たに生成されたパス

説明#

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

このクラスは読み取り専用であるため自身のパスは変更せず、新規にMGL::File::Pathを生成して返します。

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

利用例#

$resource/image/characterに拡張子.pngを追加する例
constexpr MGL::File::PathView kImageFilePath("$resource/image/character");
auto path = kImageFilePath += ".png";

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

バージョン情報#

MGL 1.1.8から利用可能

関連#

GetLength#

パス文字列の長さを取得

宣言#

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

戻り値#

size_t

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

説明#

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

利用例#

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

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

バージョン情報#

MGL 1.1.8から利用可能。

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

IsEmpty#

パスが空であるかを取得

宣言#

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

戻り値#

bool

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

説明#

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

利用例#

constexpr MGL::File::PathView kPath1("$resource/image/character.png");
constexpr MGL::File::PathView kPath2("");
constexpr MGL::File::PathView kPath3(nullptr);

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

バージョン情報#

MGL 1.1.8から利用可能。

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

関連#

GetRoot#

ルートパスを取得

宣言#

namespace MGL::File
{
    class PathView
    {
    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::PathView 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 PathView
    {
    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::PathView 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 PathView
    {
    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::PathView 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 PathView
    {
    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::PathView 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 PathView
    {
    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::PathView 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 PathView
    {
    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::PathView 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 PathView
    {
    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::PathView 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]]属性を付与。

関連#

GetCString#

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

宣言#

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

戻り値#

const char *

const char *型のパス文字列

説明#

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

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

利用例#

constexpr MGL::File::PathView kPath("$resource/image/character.png");

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

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

バージョン情報#

MGL 1.1.8から利用可能。

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

関連#

operator const char *#

const char \*型へのキャスト

宣言#

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

戻り値#

const char *

const char *型のパス文字列

説明#

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

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

利用例#

constexpr MGL::File::PathView kPath("$resource/image/character.png");

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

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

バージョン情報#

MGL 1.1.8から利用可能

関連#