# std::experimental::filesystem::u8path

> C++ Atlas: `cppatlas.com/w/cpp/experimental/fs/path/u8path` | Source: https://en.cppreference.com/w/cpp/experimental/fs/path/u8path | Domain: Technical specifications

Constructs a path p from a UTF-8 encoded sequence of chars, supplied either as an std::string, or as a null-terminated multibyte string, or as a [first, last) iterator pair.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <experimental/filesystem>

template< class Source >
path u8path( const Source& source ); // (1) (filesystem TS)

template< class InputIt >
path u8path( InputIt first, InputIt last ); // (2) (filesystem TS)
```

Constructs a path `p` from a UTF-8 encoded sequence of `char`s, supplied either as an `std::string`, or as a null-terminated multibyte string, or as a [`first`, `last`) iterator pair.

- If `path::value_type` is `char` and native encoding is UTF-8, constructs a path directly as if by `path(source)` or `path(first, last)`. Note: this is the typical situation of a POSIX system that uses Unicode, such as Linux.
- Otherwise, if `path::value_type` is `wchar_t` and native encoding is UTF-16 (this is the situation on Windows), or if `path::value_type` is `char16_t` (native encoding guaranteed UTF-16) or `char32_t` (native encoding guaranteed UTF-32), then first converts the UTF-8 character sequence to a temporary string `tmp` of type `path::string_type` and then the new path is constructed as if by `path(tmp)`.
- Otherwise (for non-UTF-8 narrow character encodings and for non-UTF-16 wchar_t), first converts the UTF-8 character sequence to a temporary UTF-32-encoded string `tmp` of type `std::u32string`, and then the new path is constructed as if by `path(tmp)` (this path is taken on a POSIX system with a non-Unicode multibyte or single-byte encoded filesystem).

### Parameters

- `source` - a UTF-8 encoded `std::string`, pointer to a null-terminated multibyte string, or an input iterator with char value type that points to a null-terminated multibyte string
- `first, last` - pair of *LegacyInputIterator*s that specify a UTF-8 encoded character sequence

**Type requirements**

- `InputIt` must meet the requirements of *LegacyInputIterator*.
- The value type of `InputIt` must be `char`.

### Return value

The path constructed from the input string after conversion from UTF-8 to the filesystem's native character encoding.

### Exceptions

May throw `filesystem_error` on underlying OS API errors or `std::bad_alloc` if memory allocation fails.

### Notes

On systems where native path format differs from the generic path format (neither Windows nor POSIX systems are examples of such OSes), if the argument to this function is using generic format, it will be converted to native.

### Example

```cpp
#include <clocale>
#include <cstdio>
#include <experimental/filesystem>
#include <fstream>
#include <iostream>
namespace fs = std::experimental::filesystem;

int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    std::locale::global(std::locale("en_US.utf8"));

    fs::path p = fs::u8path(u8"要らない.txt");

    // native string representation can be used with OS APIs
    std::ofstream(p) << "File contents"; // this uses operator string()
    if (std::FILE* f = std::fopen(p.c_str(), "r"))
    {
        int ch;
        while ((ch=fgetc(f))!= EOF) putchar(ch);
        std::fclose(f);
    }

    // multibyte and wide representation can be used for output
    std::cout.imbue(std::locale());
    std::cout << "\nFile name in narrow multibyte encoding: "
              << p.string() << '\n';

    std::wcerr.imbue(std::locale());
    std::wcerr << "File name in wide encoding: "
               << p.wstring() << '\n';

    fs::remove(p);
}
```

Possible output:

```text
File contents
File name in narrow multibyte encoding: 要らない.txt
File name in wide encoding: 要らない.txt
```

### See also

- [`path`](https://en.cppreference.com/w/cpp/experimental/fs/path): represents a path (class)

---
Attribution: content from https://en.cppreference.com/w/cpp/experimental/fs/path/u8path (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.