File handling utilities.

Files
file	file.hpp
	Defines the file class.
file	file_view.hpp
	Defines the file_view class.
file	glob.hpp
	Defines utilities for handling glob patterns.
file	path_location.hpp
	functions to locate files and directories.
file	resource_view.hpp
	Defines resource_view.
file	URI.hpp
	Defines the URI class.
file	URL.hpp
	Defines the URL class.

Data Structures
class	hi::v1::file
	A File object. More...
class	hi::v1::file_view
	Map a file into virtual memory. More...
class	hi::v1::glob_pattern
	A glob pattern. More...
class	hi::v1::const_resource_view
	A read-only view of a resource. More...
class	hi::v1::URI
	A Uniform Resource Identifier. More...
class	hi::v1::URL
	Universal Resource Locator. More...

Enumerations
enum class	hi::v1::seek_whence { hi::v1::seek_whence::begin , hi::v1::seek_whence::current , hi::v1::seek_whence::end }
	The position in the file to seek from. More...
enum class	hi::v1::access_mode {   hi::v1::access_mode::read = 0x1 , hi::v1::access_mode::write = 0x2 , hi::v1::access_mode::rename = 0x4 , hi::v1::access_mode::read_lock = 0x10 ,   hi::v1::access_mode::write_lock = 0x20 , hi::v1::access_mode::open = 0x100 , hi::v1::access_mode::create = 0x200 , hi::v1::access_mode::truncate = 0x400 ,   hi::v1::access_mode::random = 0x1000 , hi::v1::access_mode::sequential = 0x2000 , hi::v1::access_mode::no_reuse = 0x4000 , hi::v1::access_mode::write_through = 0x8000 ,   hi::v1::access_mode::create_directories = 0x10000 , hi::v1::access_mode::open_for_read = open | read , hi::v1::access_mode::open_for_read_and_write = open | read | write , truncate_or_create_for_write = create_directories | open | create | truncate | write }
	The mode in which way to open a file. More...
enum class	hi::v1::path_location {   hi::v1::path_location::resource_dirs , hi::v1::path_location::executable_file , hi::v1::path_location::executable_dir , hi::v1::path_location::library_file ,   hi::v1::path_location::library_dir , hi::v1::path_location::data_dir , hi::v1::path_location::log_dir , hi::v1::path_location::preferences_file ,   hi::v1::path_location::system_font_dirs , hi::v1::path_location::font_dirs , hi::v1::path_location::theme_dirs }
	File and Directory locations. More...

Functions
generator< std::filesystem::path >	hi::v1::glob (glob_pattern pattern)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (std::string_view pattern)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (std::string pattern)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (char const *pattern)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (std::filesystem::path pattern)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (path_location location, std::filesystem::path ref)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (path_location location, std::string_view ref)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (path_location location, std::string ref)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::glob (path_location location, char const *ref)
	Find paths on the filesystem that match the glob pattern.
generator< std::filesystem::path >	hi::v1::get_paths (path_location location)
	Get a set of paths.
std::optional< std::filesystem::path >	hi::v1::find_path (path_location location, std::filesystem::path const &ref) noexcept
	Find a path.
std::filesystem::path	hi::v1::get_path (path_location location)
	Get the single and only path.

Detailed Description

This module contains file handling utilities:

• file and file_view class to read, write and rename files.
• path_location, get_paths(), find_path() to find files and directories on the system.
• glob_pattern, glob() to find files and directories based on a glob pattern.
• URI, URL for managing URLs for local and remote resources.

File and file-views

file is a RAII object holding an handle to an open file. You can use access_mode flags to control how a file is opened:

• reading, writing,
• if it should create a new file,
• truncate the an already existing file,
• create the directories when creating a file.

A file_view is a RAII object holding a memory-mapping of the file. This object allows easy and fast access to the data in a file, as-if the file was a std::span<> or std::string_view.

Path locations

The path-locations functions are used to find files and directories based on the context of the operating system, the user account and application.

For example fonts are located in multiple places:

• the font-directory where a user can install their own fonts,
• the font-directory that is part of the application's resources, and
• the font-directory which is shared between all users of the operating system.

To iterate over all the font directories:

for (auto const &path : hi::get_paths(path_location::font_dirs)) {
    std::cout << path.string() << std::endl;
}

To find the first matching file in one of the font directories:

if (auto const &path : hi::find_path(path_location::font_dirs, "arial.ttf")) {
    std::cout << path->string() << std::endl;
}

glob

To find files based on a pattern using wild cards like * you can use the glob utilities.

The constructor of the glob_pattern object parses a string or std::filesystem::path which contain one or more of the following tokens:

Token	Description
foo	Matches the text "foo".
?	Matches any single character except '/'.
[abcd]	Matches a single character that is 'a', 'b', 'c' or 'd'.
[a-d]	Matches a single character that is 'a', 'b', 'c' or 'd'.
[-a-d]	Matches a single character that is '-', 'a', 'b', 'c' or 'd'.
{foo,bar,baz}	Matches the text "foo", "bar" or "baz".
*	Matches zero or more character except '/'.
/‍**‍/	Matches one or more directories. A single slash or zero or more characters between two slashes.

Then the glob() function will search for files and directories matching this pattern. glob() is also overloaded to directly parse a pattern and combine it with path_location.

For example to find all the files in the font directories:

for (auto const &path : hi::glob(path_location::font_dirs, "**‍/‍
    *.ttf ")) {
    std::cout
    << path.string() << std::endl;
}

URL / URI

The URI, URL and URN terms can be confusing, here is a short explanation.

• A URI (Unique Resource Identifier) is a specification for parsing and writing identifiers.
• A URL (Unique Resource Locator) is a type of URI which is used to address things.
• A URN (Unique Resource Name) is a type of URI which is used to name things.

HikoGUI currently implements dereferencing of the following types of URLs:

• relative path: A relative path does not start with a scheme and can be joined with a base URL to get an absolute URL.
• file-URL: A file accessible via the operating system. This scheme supports the following features:
  • relative paths (can not be joined using URL joining),
  • absolute path (relative to the current drive or file-share),
  • relative path on a specific drive,
  • absolute path on a specific drive and file-share,
  • conversion of drive to a file-share name,
  • the server name may be part of the double-slash "//" path or the authority.
• resource-URL: A relative path that converts into a file-path by searching for the first file in one of the directories of path_location::resource_dirs.

Both file: and resource: URLs may be implicitly converted to a std::filesystem::path.

Enumeration Type Documentation

access_mode

enum class hi::v1::access_mode

strong

The mode in which way to open a file.

These flags can be combined by using OR.

Enumerator
read	Allow read access to a file.
write	Allow write access to a file.
rename	Allow renaming an open file.
read_lock	Lock the file for reading, i.e. shared-lock.
write_lock	Lock the file for writing, i.e. exclusive-lock.
open	Open file if it exist, or fail.
create	Create file if it does not exist, or fail.
truncate	After the file has been opened, truncate it.
random	Hint the data should not be prefetched.
sequential	Hint that the data should be prefetched.
no_reuse	Hint that the data should not be cached.
write_through	Hint that writes should be send directly to disk.
create_directories	Create directory hierarchy, if the file could not be created.
open_for_read	Default open a file for reading.
open_for_read_and_write	Default open a file for reading and writing.

path_location

enum class hi::v1::path_location

strong

File and Directory locations.

Enumerator
resource_dirs	The location of application resources.
executable_file	A single file where the current running executable is located.
executable_dir	The directory where the executable is located.
library_file	A single file where the current running HikoGUI shared library is located. If HikoGUI is build as a static library then this will return the current executable instead.
library_dir	The single directory where the HikoGUI shared library is located.
data_dir	The single directory where the data for the application is stored for the current user account.
log_dir	The single directory where to store the log files.
preferences_file	A single file where to store or load the application preferences file for the current user account.
system_font_dirs	The directories where the system fonts are stored.
font_dirs	The directories where the fonts for the system and resource fonts are located.
theme_dirs	The directories where the themes are located.

seek_whence

enum class hi::v1::seek_whence

strong

The position in the file to seek from.

Enumerator
begin	Start from the beginning of the file.
current	Continue from the current position.
end	Start from the end of the file.

Function Documentation

find_path()

std::optional< std::filesystem::path > hi::v1::find_path ( path_location location, std::filesystem::path const & ref )

inlinenodiscardnoexcept

Find a path.

Parameters

location	The location to search for filesystem-object.
ref	A relative path to the filesystem-object.

Returns

The the first full path to the filesystem-object found in the location. Or empty if the path is not found.

get_path()

std::filesystem::path hi::v1::get_path ( path_location location )

inlinenodiscard

Get the single and only path.

Parameters

location

The location.

Returns

The path.

Exceptions

When	there is not exactly one path.

get_paths()

generator< std::filesystem::path > hi::v1::get_paths ( path_location location )

nodiscard

Get a set of paths.

Parameters

location

The location.

Returns

A list of paths belonging to the location.

glob() [1/9]

generator< std::filesystem::path > hi::v1::glob ( char const * pattern )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [2/9]

generator< std::filesystem::path > hi::v1::glob ( glob_pattern pattern )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [3/9]

generator< std::filesystem::path > hi::v1::glob ( path_location location, char const * ref )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

location	The path-location to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [4/9]

generator< std::filesystem::path > hi::v1::glob ( path_location location, std::filesystem::path ref )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

location	The path-location to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [5/9]

generator< std::filesystem::path > hi::v1::glob ( path_location location, std::string ref )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

location	The path-location to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [6/9]

generator< std::filesystem::path > hi::v1::glob ( path_location location, std::string_view ref )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

location	The path-location to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [7/9]

generator< std::filesystem::path > hi::v1::glob ( std::filesystem::path pattern )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [8/9]

generator< std::filesystem::path > hi::v1::glob ( std::string pattern )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [9/9]

generator< std::filesystem::path > hi::v1::glob ( std::string_view pattern )

inlinenodiscard

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.