path_io.h
Opening files by UTF-8 path, on every platform.
#include <sonore/path_io.h>- 10other declarations
On this page
Design notes
Every path in this SDK is UTF-8: what the file dialog returns, what files.h lists, what a plugin saves in its state. On macOS and Linux the C library agrees. On Windows it does not -- fopen, remove, rename and _mkdir read their argument in the ANSI code page -- so a path through a folder called "José" named a different file, and one through "Музыка" or "音楽" named nothing at all: a sample that would not load, a recording that could not be written, a settings file silently never saved, for exactly the users whose names or languages are not English.
These are the C library's own calls, with the path converted at the edge. Deliberately free of <windows.h>: wav.h and friends include this, and a header that writes a WAV file should not drag the Windows API in to do it.
Functions 10
- fn
inline std::wstring widen(const char* utf8)UTF-8 to UTF-16, by hand so this header needs no Windows API. A malformed sequence becomes U+FFFD, which names no file -- an open that fails rather than one that quietly reaches a different file.pathio::widen · path_io.h:38 - fn
inline std::string narrow(const wchar_t* wide)UTF-16 to UTF-8, for names the wide API hands back. An unpaired surrogate becomes U+FFFD.pathio::narrow · path_io.h:91 - fn
inline std::string narrow(const wchar_t* wide, size_t capacity)narrow() of a fixed-size field, such as a driver's name in a caps struct: at mostpathio::narrow · path_io.h:125capacityunits, so a name that fills its field with no terminator stops at the field's end instead of reading on into the struct. - fn
inline std::string environment(const char* name)An environment variable as UTF-8, or empty when it is not set. On Windows getenv answers in the ANSI code page, so a profile folder named after its user --pathio::environment · path_io.h:137C:\Users\Олег-- came back as question marks, and every settings file, log and licence under %APPDATA% went to a path that cannot exist. - fn
inline std::wstring widenPath(const char* utf8)A UTF-8 path as the wide API should be handed it: with the long-path prefix when it is too long for MAX_PATH. A plugin runs inside a DAW that has no long-path manifest, so even with LongPathsEnabled set every open, stat and mkdir under a deep folder failed at around 260 characters -- a sample library a few folders down a long user name is enough. The prefix turns off the API's normalising, so the path is made absolute and its separators backslashes first -- by _wfullpath, which takes long input when it is given the room, and keeps this header free of windows.h.pathio::widenPath · path_io.h:164 - fn
inline std::FILE* open(const char* path, const char* mode)fopen, by UTF-8 path. Shared for reading and writing as fopen is: a log the user is told to send must stay deletable while the plugin runs.pathio::open · path_io.h:178 - fn
inline int remove(const char* path)remove, by UTF-8 path. Zero on success, as remove returns.pathio::remove · path_io.h:188 - fn
inline int rename(const char* from, const char* to)rename, by UTF-8 path. Fails ifpathio::rename · path_io.h:200toexists on Windows, as rename does there; a caller that means to replace removes it first, or uses the platform's atomic replace. - fn
inline bool makeDirectory(const char* path)One directory level, by UTF-8 path. True if it now exists as a directory, whether this made it or it was there already.pathio::makeDirectory · path_io.h:211 - fn
inline bool isDirectoryAt(const char* path)Is there a directory at this UTF-8 path?pathio::isDirectoryAt · path_io.h:226