basic_path Class Template Reference
[File System Library]

#include <winstl/filesystem/path.hpp>

Detailed Description

template<typename C, typename T = filesystem_traits<C>, typename A = processheap_allocator<C>>
class winstl::basic_path< C, T, A >

Class used for composing and decomposing file-system paths.

Parameters:

	C	The character type
	T	The traits type. On translators that support default template arguments, this defaults to filesystem_traits<C>
	A	The allocator type. On translators that support default template arguments, this defaults to processheap_allocator<C>

Note:: This class derives from the Synesis Software class Path, but has been influenced by other, later, ideas. The idea of using the / operator for path concatenation was sparked by the Boost implementation (although the details were not investigated prior to this implementation, so the two may have significant semantic differences). This has been added without requiring any major fundamental changes to the original push/pop-based interface


Construction
	basic_path ()
	Constructs an empty path.
	basic_path (char_type const *path)
	Constructs a path from a nul-terminated character string.
template<typename S>
	basic_path (S const &s)
	Constructs a path from a string object.
	basic_path (char_type const *path, size_type cch)
	Constructs a path from a slice of a character string.
	basic_path (class_type const &rhs)
	Copies the contents of `rhs`.
class_type &	operator= (class_type const &rhs)
	Copies the contents of `rhs`.
class_type &	operator= (char_type const *rhs)
	Copies the contents of `rhs`.
template<typename S>
class_type &	operator= (S const &s)
	Copies the contents of `s`.
static class_type	root (char_type const *s)
template<typename S>
static class_type	root (S const &s)
Attributes
char_type const *	get_file () const
	Returns a pointer to the part of the path after the last path name separator.
char_type const *	get_ext () const
	Returns a pointer to the extension, or to the empty string if there is no extension.
size_type	length () const
	Returns the length of the converted path.
size_type	size () const
	Returns the length of the converted path.
bool_type	empty () const
	Determines whether the path is empty.
char_type const *	c_str () const
	Conversion to a non-mutable (const) pointer to the path.
char_type const &	operator[] (size_type index) const
	Returns a non-mutable (const) reference to the character at the given index.
bool_type	exists () const
	Indicates whether the path represents an existing file system entry.
bool_type	is_rooted () const
	Indicates whether the path is rooted.
bool_type	is_absolute () const
	Indicates whether the path is absolute.
bool_type	has_sep () const
	Indicates whether the path has a trailing separator.
size_type	copy (char_type *buffer, size_type cchBuffer) const
	Copies the contents into a caller supplied buffer.
static size_type	max_size ()
	The maximum possible length of a path.
Public Types
Types
typedef C	char_type
	The char type.
typedef T	traits_type
	The traits type.
typedef A	allocator_type
	The allocator type.
typedef basic_path< C, T, A >	class_type
	The current parameterisation of the type.
typedef size_t	size_type
	The size type.
typedef bool	bool_type
	The Boolean type.
Public Member Functions
Operations
class_type &	push (class_type const &rhs, bool_type bAddPathNameSeparator=false)
	Appends the contents of `rhs` to the path.
class_type &	push (char_type const *rhs, bool_type bAddPathNameSeparator=false)
	Appends the contents of `rhs` to the path.
class_type &	push_ext (class_type const &rhs, bool_type bAddPathNameSeparator=false)
	Appends the contents of `rhs` to the path as an extension.
class_type &	push_ext (char_type const *rhs, bool_type bAddPathNameSeparator=false)
	Appends the contents of `rhs` to the path as an extension.
class_type &	push_sep ()
	Ensures that the path has a trailing path name separator.
class_type &	pop (bool_type bRemoveTrailingPathNameSeparator=true)
	Pops the last path element from the path.
class_type &	pop_sep () throw ()
	Ensures that the path does not have a trailing path name separator.
class_type &	pop_ext () throw ()
	Removes the extension, if any, from the file component of the path.
class_type &	operator/= (char_type const *rhs)
	Equivalent to push().
template<typename S>
class_type &	operator/= (S const &rhs)
	Equivalent to push().
void	clear ()
	Removes all content.
class_type &	make_absolute (bool_type bRemoveTrailingPathNameSeparator=true)
	Converts the path to absolute form.
class_type &	canonicalise (bool_type bRemoveTrailingPathNameSeparator=true)
	Canonicalises the path.
Comparison
bool_type	equivalent (char_type const *rhs) const
	Determines whether the instance holds a string that refers to the same file-system entity as the given string.
bool_type	equivalent (class_type const &rhs) const
	Evaluates whether the two instances hold strings that refer to the same file-system entity.
bool_type	equal (char_type const *rhs) const
	Evaluates whether the instance holds an identical string.
bool_type	equal (class_type const &rhs) const
	Evaluates whether the two instances hold identical strings.
Classes
struct	part_type

Member Typedef Documentation

typedef C char_type

The char type.

typedef T traits_type

The traits type.

typedef A allocator_type

The allocator type.

typedef basic_path<C, T, A> class_type

The current parameterisation of the type.

typedef size_t size_type

The size type.

typedef bool bool_type

The Boolean type.

Constructor & Destructor Documentation

basic_path ( )

Constructs an empty path.

 winstl::path  p;

 assert(0 == p.size());
 assert("" == p);

basic_path ( char_type const * path ) [explicit]

Constructs a path from a nul-terminated character string.

 winstl::path  p("C:\\Windows");

 assert(10 == p.size());
 assert("C:\\Windows" == p);
 assert("C:\\WINDOWS" == p);
 assert("c:\\windows" == p);

Precondition:: len(path) <= size()

basic_path ( S const & s ) [inline, explicit]

Constructs a path from a string object.

Remarks:: The string object may be any type for which the c_str_len and c_str_data String Access Shims are defined. The following example shows the use of a window handle (HWND). Other types supported are std::exception, std::string, stlsoft::simple_string, winstl::error_desc, and many more

 HWND          hwndParent = . . .
 HWND          hwnd       = winstl::CreateEdit(hwndParent, "C:\\Windows", ES_LEFT, 0, 0, 10, 10, 1001);
 winstl::path  p(hwnd);

 assert(10 == p.size());
 assert("C:\\Windows" == p);
 assert("C:\\WINDOWS" == p);
 assert("c:\\windows" == p);

References stlsoft_ns_qual.

basic_path	(	char_type const *	path,
		size_type	cch
	)

Constructs a path from a slice of a character string.

winstl::path p("C:\\Windows\\system32", 10);

assert(10 == p.size()); assert("C:\\Windows" == p); assert("C:\\WINDOWS" == p); assert("c:\\windows" == p);

basic_path ( class_type const & rhs )

Copies the contents of rhs.

Member Function Documentation

class_type& operator= ( class_type const & rhs )

Copies the contents of rhs.

class_type& operator= ( char_type const * rhs )

Copies the contents of rhs.

class_type& operator= ( S const & s ) [inline]

Copies the contents of s.

References stlsoft_ns_qual.

class_type& push	(	class_type const &	rhs,
		bool_type	bAddPathNameSeparator = `false`
	)

Appends the contents of rhs to the path.

class_type& push	(	char_type const *	rhs,
		bool_type	bAddPathNameSeparator = `false`
	)

Appends the contents of rhs to the path.

class_type& push_ext	(	class_type const &	rhs,
		bool_type	bAddPathNameSeparator = `false`
	)

Appends the contents of rhs to the path as an extension.

class_type& push_ext	(	char_type const *	rhs,
		bool_type	bAddPathNameSeparator = `false`
	)

Appends the contents of rhs to the path as an extension.

class_type& push_sep ( )

Ensures that the path has a trailing path name separator.

Remarks:: If the path currently contains path name separators, and they are all forward slashes '/', then a forward slash will be used; otherwise a backslash '\' will be used.

class_type& pop ( bool_type bRemoveTrailingPathNameSeparator = true )

Pops the last path element from the path.

Note:: In previous versions, this operation did not remove the left-most path component. That behaviour is no longer supported, and the method will now leave the path instance empty in that case.

class_type& pop_sep ( ) throw ()

Ensures that the path does not have a trailing path name separator.

Note:: Does not trim the separator character from the root designator
This method is idempotent.

class_type& pop_ext ( ) throw ()

Removes the extension, if any, from the file component of the path.

Note:: This method is idempotent.

class_type& operator/= ( char_type const * rhs )

Equivalent to push().

class_type& operator/= ( S const & rhs ) [inline]

Equivalent to push().

References stlsoft_ns_qual.

void clear ( )

Removes all content.

class_type& make_absolute ( bool_type bRemoveTrailingPathNameSeparator = true )

Converts the path to absolute form.

class_type& canonicalise ( bool_type bRemoveTrailingPathNameSeparator = true )

Canonicalises the path.

Canonicalises the path, removing all "./" parts and evaluating all "../" parts. Any path with only one part will not be canonicalised. A leading '.' will be preserved if no other '..' or "normal" parts are contained.

Parameters:

bRemoveTrailingPathNameSeparator

Removes any trailing separator, even if no other changes have been made.

char_type const* get_file ( ) const

Returns a pointer to the part of the path after the last path name separator.

Note:: If the path represents a directory, the name of the directory will be returned, except if the path is terminated by the path name separator
If the path contains no path name separator, the full path will be returned

char_type const* get_ext ( ) const

Returns a pointer to the extension, or to the empty string if there is no extension.

size_type length ( ) const

Returns the length of the converted path.

size_type size ( ) const

Returns the length of the converted path.

Remarks:: Equivalent to length()

static size_type max_size ( ) [static]

The maximum possible length of a path.

bool_type empty ( ) const

Determines whether the path is empty.

char_type const* c_str ( ) const

Conversion to a non-mutable (const) pointer to the path.

char_type const& operator[] ( size_type index ) const

Returns a non-mutable (const) reference to the character at the given index.

Note:: The behaviour is undefined if index >= size().

bool_type exists ( ) const

Indicates whether the path represents an existing file system entry.

bool_type is_rooted ( ) const

Indicates whether the path is rooted.

bool_type is_absolute ( ) const

Indicates whether the path is absolute.

bool_type has_sep ( ) const

Indicates whether the path has a trailing separator.

size_type copy	(	char_type *	buffer,
		size_type	cchBuffer
	)			const

Copies the contents into a caller supplied buffer.

Parameters:

	buffer	Pointer to character buffer to receive the contents. May be NULL, in which case the method returns size().
	cchBuffer	Number of characters of available space in `buffer`.

bool_type equivalent ( char_type const * rhs ) const

Determines whether the instance holds a string that refers to the same file-system entity as the given string.

///

    /// winstl::path  p("C:\\Windows\\system32\\..");
    ///
    /// assert(p != "C:\\WINDOWS\\");
    /// assert(!p.equal("C:\\WINDOWS\\"));
    /// assert(p.equivalent("C:\\WINDOWS\\"));
    ///

///

bool_type equivalent ( class_type const & rhs ) const

Evaluates whether the two instances hold strings that refer to the same file-system entity.

Remarks:: See equivalent() for an example.

Note:: The string comparison is case-insensitive.

bool_type equal ( char_type const * rhs ) const

Evaluates whether the instance holds an identical string.

Note:: The string comparison is case-insensitive.

bool_type equal ( class_type const & rhs ) const

Evaluates whether the two instances hold identical strings.

Note:: The string comparison is case-insensitive.

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

winstl/filesystem/path.hpp

basic_path Class Template Reference [File System Library]

Detailed Description

template<typename C, typename T = filesystem_traits<C>, typename A = processheap_allocator<C>> class winstl::basic_path< C, T, A >

Construction

Attributes

Public Types

Public Member Functions

Classes

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

basic_path Class Template Reference
[File System Library]

template<typename C, typename T = filesystem_traits<C>, typename A = processheap_allocator<C>>
class winstl::basic_path< C, T, A >