File Class Reference

A file on the local file system. More...

#include <File.hpp>

Inheritance diagram for File:

Collaboration diagram for File:

Classes
class	FileIterator
	Non-recursive iteration over a directory's contents. More...
class	FileUriIterator
	Non-recursive iteration over a directory's contents (URI version). More...
class	RecursiveFileIterator
	Recursive iteration into a directory structure. More...
class	RecursiveFileUriIterator
	Recursive iteration into a directory structure (URI version). More...

Public Member Functions
	File ()=default
	Create an empty file URI. More...
	File (boost::filesystem::directory_entry entry_)
	Create a file from the supplied directory entry. More...
	File (const boost::filesystem::path &entry_)
	Create a file from the supplied Boost path. More...
	File (const std::string &path)
	Create a file path with the supplied path string. More...
	File (const char *path)
	Create a file path with the supplied path string. More...
	File (std::string_view path)
	Create a file path with the supplied path string. More...
	File (const std::string &path, const std::string &name)
	Create a file path with the supplied path string and filename string. More...
	File (const File &path, const std::string &name)
	Create a file path with the supplied path and filename. More...
	File (File &&file) noexcept
	Move an existing file URI into a new File URI. More...
	File (const File &file)
	Copy an existing file URI into a new File URI. More...
std::unique_ptr< Uri >	append (const std::string &pathComponent) const override
	Appends the path component to the supplied URI, returning a new URI. More...
std::unique_ptr< ByteReadResource >	byteReadResource () const override
	Get a byte read resource for the URI. More...
std::unique_ptr< ByteWriteResource >	byteWriteResource () override
	Get a byte write resource for the URI. More...
bool	canReadFrom () const override
	Can data be read from the URI via a read resource. More...
bool	canWriteTo () const override
	Can data be written to the URI via a write resource. More...
std::unique_ptr< Uri >	clone () const override
	Clone the concrete Uri. More...
bool	createDirectories () const
	Create all intermediate directories and the final directory. More...
void	dispatch (UriDispatcher &dispatcher) const override
	Visitor pattern dispatching. More...
bool	exists () const
	Returns true if an item exits in the file system for the file URI. More...
virtual FileIterator	fileIterator () const
	Get a non-recursive file iterator for this file (directory). More...
FileByteReadResource	getByteReadResource () const
	Get a file byte read resource for this file URI. More...
FileByteWriteResource	getByteWriteResource () const
	Get a file byte write resource for this file URI. More...
File	getChildEntry (std::string child) const
boost::filesystem::directory_entry	getEntry () const
	Get the underlying directory entry for this file URI. More...
std::chrono::system_clock::time_point	getModifiedTimestamp () const
	Get the modified time of the file. More...
File	getParentDirectory () const
	Get the parent directory of the file URI. More...
File	getSubDirectory (std::string subDirectory) const
	Create a new file representing the specified sub-directory of the file URI. More...
FileUtf32To8WriteResource	getUtf32To8WriteResource () const
	Get a file UTF-8 to UTF-32 write resource for this file URI. More...
FileUtf8To32ReadResource	getUtf8To32ReadResource () const
	Get a file UTF-8 to UTF-32 read resource for this file URI. More...
size_t	hashcode () const noexcept override
	Get the URI's hash code. More...
bool	isIterable () const override
	Does the URI have a non-recursive iterator (examples: file and zip archive URIs). More...
bool	isRecursivelyIterable () const override
	Does the URI have a recursive iterator (examples: file and zip archive URIs). More...
bool	isRegularDirectory () const override
	Returns true if the file URI points to a directory. More...
bool	isRegularFile () const override
	Returns true if the file URI points to a regular file. More...
std::unique_ptr< UriIterator >	iterator () const override
	Get a (non-recursive) iterator. More...
File	operator+ (const std::string &fragment) const
	Concatenate the supplied path fragment to the end of the path represented by the file. More...
File	operator/ (const char *component) const
	Append a path component to the path represented by the file. More...
File	operator/ (const std::string &component) const
	Append a path component to the path represented by the file. More...
File	operator/ (const std::string_view &component) const
	Append a path component to the path represented by the file. More...
template<typename ... T, template< typename ... > class Container>
File	operator/ (const Container< T ... > &container) const
	Append a sequence of path components to the path represented by the file. More...
File &	operator/= (const char *component)
	Append a path component to the path represented by the file in place. More...
File &	operator/= (const std::string &component)
	Append a path component to the path represented by the file in place. More...
File &	operator/= (const std::string_view &component)
	Append a path component to the path represented by the file in place. More...
bool	operator< (const File &rhs) const
	Return true if the current object is less than the supplied instance. More...
File &	operator= (const File &file)
	Copy assign the supplied file to this file. More...
File &	operator= (File &&file) noexcept
	Move assign the supplied file to this file. More...
File &	operator= (const boost::filesystem::directory_entry &entry_)
	Copy the supplied directory entry to this file. More...
File &	operator= (const boost::filesystem::path &path)
	Copy the supplied file system path to this file. More...
bool	operator== (const File &rhs) const
	Compare the supplied file to the current file. More...
bool	operator== (const Uri &rhs) const override
	Compare the supplied URI to the current URI. More...
virtual RecursiveFileIterator	recursiveFileIterator () const
	Get a recursive file iterator for this file (directory). More...
std::unique_ptr< RecursiveUriIterator >	recursiveIterator () const override
	Get a recursive iterator. More...
File	relative (const File &base) const
	Get the relative path of the current object, compared to the supplied file. More...
bool	removeFile () const
	Remove the file if it exists. More...
std::unique_ptr< Uri >	resolve (std::string_view path) const override
	Resolve the relative or absolute path, in reference to the current URI. More...
size_t	size () const
	Get the size of the file if it exists or -1 if the file does not exist. More...
File	toAbsolutePath () const
	Convert the file to an absolute path if it is relative, using the current working directory. More...
std::string	toRawString () const override
	Get a string representing the raw URI. More...
template<typename AllocatorT >
Balau::U8String< AllocatorT >	toRawString () const
	Get a string representing the raw URI. More...
std::string	toUriString () const override
	Get a string representing the URI, complete with scheme. More...
std::unique_ptr< Utf32To8WriteResource >	utf32To8WriteResource () override
	Get a UTF-32 to UTF-8 write resource for the URI. More...
std::unique_ptr< Utf8To32ReadResource >	utf8To32ReadResource () const override
	Get a UTF-8 to UTF-32 read resource for the URI. More...
Public Member Functions inherited from Uri
virtual	~Uri ()=default
	Destroy the URI instance. More...
std::shared_ptr< Uri >	cloneToShared () const
	Clone the concrete Uri to a shared pointer. More...

Static Public Attributes
static const boost::filesystem::path::value_type	separator = boost::filesystem::path::preferred_separator
	The path separator character for the platform. More...

Detailed Description

A file on the local file system.

Constructor & Destructor Documentation

File() [1/10]

File ( )

default

Create an empty file URI.

File() [2/10]

File ( boost::filesystem::directory_entry  entry_ )

inlineexplicit

Create a file from the supplied directory entry.

File() [3/10]

File ( const boost::filesystem::path &  entry_ )

inlineexplicit

Create a file from the supplied Boost path.

File() [4/10]

File ( const std::string &  path )

inlineexplicit

Create a file path with the supplied path string.

The path must be formatted correctly for the platform.

File() [5/10]

File ( const char *  path )

inlineexplicit

Create a file path with the supplied path string.

The path must be formatted correctly for the platform.

File() [6/10]

File ( std::string_view  path )

inlineexplicit

Create a file path with the supplied path string.

The path must be formatted correctly for the platform.

File() [7/10]

File ( const std::string &  path, const std::string &  name  )

inline

Create a file path with the supplied path string and filename string.

The path must be formatted correctly for the platform.

File() [8/10]

File ( const File &  path, const std::string &  name  )

inline

Create a file path with the supplied path and filename.

The path must be formatted correctly for the platform.

File() [9/10]

File ( File &&  file )

inlinenoexcept

Move an existing file URI into a new File URI.

File() [10/10]

File ( const File &  file )

inline

Copy an existing file URI into a new File URI.

Member Function Documentation

append()

std::unique_ptr<Uri> append ( const std::string &  pathComponent ) const

inlineoverridevirtual

Appends the path component to the supplied URI, returning a new URI.

If the URI type does not permit appending of path components, UnsupportedOperationException is thrown.

Implements Uri.

Reimplemented in ZipFile.

byteReadResource()

std::unique_ptr<ByteReadResource> byteReadResource ( ) const

inlineoverridevirtual

Get a byte read resource for the URI.

Exceptions

NotImplementedException	if the URI does not support reading
ResourceException	if the resource could not be created

Implements Uri.

Reimplemented in ZipFile.

byteWriteResource()

std::unique_ptr<ByteWriteResource> byteWriteResource ( )

inlineoverridevirtual

Get a byte write resource for the URI.

Exceptions

NotImplementedException	if the URI does not support writing
ResourceException	if the resource could not be created

Implements Uri.

Reimplemented in ZipFile.

canReadFrom()

bool canReadFrom ( ) const

inlineoverridevirtual

Can data be read from the URI via a read resource.

Implements Uri.

Reimplemented in ZipFile.

canWriteTo()

bool canWriteTo ( ) const

inlineoverridevirtual

Can data be written to the URI via a write resource.

Implements Uri.

Reimplemented in ZipFile.

clone()

std::unique_ptr<Uri> clone ( ) const

inlineoverridevirtual

Clone the concrete Uri.

Returns

a clone of the URI

Implements Uri.

Reimplemented in ZipFile.

createDirectories()

bool createDirectories ( ) const

inline

Create all intermediate directories and the final directory.

A successful call to this method with false returned indicates that the directories existed already.

Returns

true if one or more of the directories were created, false otherwise

Exceptions

filesystem_error

when there was an error attempting to create one or more of the directories

dispatch()

void dispatch ( UriDispatcher &  visitor ) const

inlineoverridevirtual

Visitor pattern dispatching.

Parameters

visitor

the visitor to visit

Implements Uri.

Reimplemented in ZipFile.

exists()

bool exists ( ) const

inline

Returns true if an item exits in the file system for the file URI.

Returns

true if an item exits in the file system for the file URI

fileIterator()

virtual FileIterator fileIterator ( ) const

inlinevirtual

Get a non-recursive file iterator for this file (directory).

Returns

a file iterator

Exceptions

boost::filesystem::filesystem_error

if the current object is not a directory

Reimplemented in ZipFile.

getByteReadResource()

FileByteReadResource getByteReadResource ( ) const

inline

Get a file byte read resource for this file URI.

Returns

a file byte read resource

getByteWriteResource()

FileByteWriteResource getByteWriteResource ( ) const

inline

Get a file byte write resource for this file URI.

Returns

a file byte write resource

getChildEntry()

File getChildEntry ( std::string  child ) const

inline

Todo:

document this

getEntry()

boost::filesystem::directory_entry getEntry ( ) const

inline

Get the underlying directory entry for this file URI.

Returns

a directory entry

getModifiedTimestamp()

std::chrono::system_clock::time_point getModifiedTimestamp ( ) const

inline

Get the modified time of the file.

Returns

the modified time of the file

getParentDirectory()

File getParentDirectory ( ) const

inline

Get the parent directory of the file URI.

Returns

the parent directory of the file URI

getSubDirectory()

File getSubDirectory ( std::string  subDirectory ) const

inline

Create a new file representing the specified sub-directory of the file URI.

Returns

a new file representing the specified sub-directory of the file URI

getUtf32To8WriteResource()

FileUtf32To8WriteResource getUtf32To8WriteResource ( ) const

inline

Get a file UTF-8 to UTF-32 write resource for this file URI.

Returns

a file UTF-8 to UTF-32 write resource

getUtf8To32ReadResource()

FileUtf8To32ReadResource getUtf8To32ReadResource ( ) const

inline

Get a file UTF-8 to UTF-32 read resource for this file URI.

Returns

a file UTF-8 to UTF-32 read resource

hashcode()

size_t hashcode ( ) const

inlineoverridevirtualnoexcept

Get the URI's hash code.

Returns

the hash code

Implements Uri.

isIterable()

bool isIterable ( ) const

inlineoverridevirtual

Does the URI have a non-recursive iterator (examples: file and zip archive URIs).

Implements Uri.

Reimplemented in ZipFile.

isRecursivelyIterable()

bool isRecursivelyIterable ( ) const

inlineoverridevirtual

Does the URI have a recursive iterator (examples: file and zip archive URIs).

Implements Uri.

Reimplemented in ZipFile.

isRegularDirectory()

bool isRegularDirectory ( ) const

inlineoverridevirtual

Returns true if the file URI points to a directory.

Returns

true if the file URI points to a directory

Implements Uri.

Reimplemented in ZipFile.

isRegularFile()

bool isRegularFile ( ) const

inlineoverridevirtual

Returns true if the file URI points to a regular file.

Returns

true if the file URI points to a regular file

Implements Uri.

Reimplemented in ZipFile.

iterator()

std::unique_ptr<UriIterator> iterator ( ) const

inlineoverridevirtual

Get a (non-recursive) iterator.

This will throw a NotImplementedException if the URI does not have an iterator.

Implements Uri.

Reimplemented in ZipFile.

operator+()

File operator+ ( const std::string &  fragment ) const

inline

Concatenate the supplied path fragment to the end of the path represented by the file.

Returns

a new file instance with the concatenated fragment

operator/() [1/4]

File operator/ ( const char *  component ) const

inline

Append a path component to the path represented by the file.

Returns

a new file instance with the appended path component

operator/() [2/4]

File operator/ ( const std::string &  component ) const

inline

Append a path component to the path represented by the file.

Returns

a new file instance with the appended path component

operator/() [3/4]

File operator/ ( const std::string_view &  component ) const

inline

Append a path component to the path represented by the file.

Returns

a new file instance with the appended path component

operator/() [4/4]

File operator/ ( const Container< T ... > &  container ) const

inline

Append a sequence of path components to the path represented by the file.

Template Parameters

T	the string type in the container
Container	the container type

Parameters

container

the container containing the components to append

Returns

a new file instance with the appended path components

operator/=() [1/3]

File& operator/= ( const char *  component )

inline

Append a path component to the path represented by the file in place.

Returns

the current object

operator/=() [2/3]

File& operator/= ( const std::string &  component )

inline

Append a path component to the path represented by the file in place.

Returns

the current object

operator/=() [3/3]

File& operator/= ( const std::string_view &  component )

inline

Append a path component to the path represented by the file in place.

Returns

the current object

operator<()

bool operator< ( const File &  rhs ) const

inline

Return true if the current object is less than the supplied instance.

Returns

true if the current object is less than the supplied instance

operator=() [1/4]

File& operator= ( const File &  file )

inline

Copy assign the supplied file to this file.

Returns

the current object

operator=() [2/4]

File& operator= ( File &&  file )

inlinenoexcept

Move assign the supplied file to this file.

Returns

the current object

operator=() [3/4]

File& operator= ( const boost::filesystem::directory_entry &  entry_ )

inline

Copy the supplied directory entry to this file.

Returns

the current object

operator=() [4/4]

File& operator= ( const boost::filesystem::path &  path )

inline

Copy the supplied file system path to this file.

Returns

the current object

operator==() [1/2]

bool operator== ( const File &  rhs ) const

inline

Compare the supplied file to the current file.

Returns

true if the supplied file is equal to the current file.

operator==() [2/2]

bool operator== ( const Uri &  rhs ) const

inlineoverridevirtual

Compare the supplied URI to the current URI.

Returns

true if the supplied URI is equal to the current URI.

Implements Uri.

Reimplemented in ZipFile.

recursiveFileIterator()

virtual RecursiveFileIterator recursiveFileIterator ( ) const

inlinevirtual

Get a recursive file iterator for this file (directory).

Returns

a recursive file iterator

Exceptions

boost::filesystem::filesystem_error

if the current object is not a directory

Reimplemented in ZipFile.

recursiveIterator()

std::unique_ptr<RecursiveUriIterator> recursiveIterator ( ) const

inlineoverridevirtual

Get a recursive iterator.

This will throw a NotImplementedException if the URI does not have a recursive iterator.

Implements Uri.

Reimplemented in ZipFile.

relative()

File relative ( const File &  base ) const

inline

Get the relative path of the current object, compared to the supplied file.

Returns

the relative path of the current object, compared to the supplied file

removeFile()

bool removeFile ( ) const

inline

Remove the file if it exists.

Returns

true if the file was removed

resolve()

std::unique_ptr<Uri> resolve ( std::string_view  path ) const

inlineoverridevirtual

Resolve the relative or absolute path, in reference to the current URI.

If the supplied path contains a scheme prefix, the URI fromString function will be called to create a new unrelated URI instance.

This method will determine the base path to use by applying the following rules.

• If the URI path ends with a forward slash (or is a directory for file URIs), the base path is the URI path.
• Otherwise, the rightmost path element is stripped from the URI path to form the base path.

Parameters

path	a relative or absolute path, or a full URI

Returns

a new URI

Implements Uri.

Reimplemented in ZipFile.

size()

size_t size ( ) const

inline

Get the size of the file if it exists or -1 if the file does not exist.

Exceptions

IOException

if there was an error when getting the file size

toAbsolutePath()

File toAbsolutePath ( ) const

inline

Convert the file to an absolute path if it is relative, using the current working directory.

Returns

a copy of the file converted to an absolute path

toRawString() [1/2]

std::string toRawString ( ) const

inlineoverridevirtual

Get a string representing the raw URI.

This may or may not be the same as the string returned by toUriString().

Returns

a string representing the raw URI

Implements Uri.

toRawString() [2/2]

Balau::U8String<AllocatorT> toRawString ( ) const

inlinevirtual

Get a string representing the raw URI.

This may or may not be the same as the string returned by toUriString().

Returns

a string representing the raw URI

Implements Uri.

toUriString()

std::string toUriString ( ) const

inlineoverridevirtual

Get a string representing the URI, complete with scheme.

Returns

a string representing the URI, complete with scheme

Implements Uri.

utf32To8WriteResource()

std::unique_ptr<Utf32To8WriteResource> utf32To8WriteResource ( )

inlineoverridevirtual

Get a UTF-32 to UTF-8 write resource for the URI.

Exceptions

NotImplementedException	if the URI does not support writing
ResourceException	if the resource could not be created

Implements Uri.

Reimplemented in ZipFile.

utf8To32ReadResource()

std::unique_ptr<Utf8To32ReadResource> utf8To32ReadResource ( ) const

inlineoverridevirtual

Get a UTF-8 to UTF-32 read resource for the URI.

Exceptions

NotImplementedException	if the URI does not support reading
ResourceException	if the resource could not be created

Implements Uri.

Reimplemented in ZipFile.

Member Data Documentation

separator

const boost::filesystem::path::value_type separator = boost::filesystem::path::preferred_separator

static

The path separator character for the platform.

---

The documentation for this class was generated from the following file:

• File.hpp (7)