File System Library
[Libraries]

---

Detailed Description

Created: 23rd May 2006 Updated: 14th January 2007.

This library defines file system components.

The STL-containers provided by the STLSoft libraries include:

• The stlsoft::environment_block - WRONGLY PLACED!!!! This is a facade.
• The stlsoft::fixed_array
• The stlsoft::frequency_map
• The stlsoft::pod_vector
• The stlsoft::static_array
• The stlsoft::unsorted_map
• The stlsoft::fixed_array class templates

Classes
struct	filesystem_traits
	Traits for accessing the correct file-system functions for a given character type. More...
class	basic_findfile_sequence
	Presents an STL-like sequence interface over the items on the file-system. More...
class	basic_findfile_sequence_value_type
	Value type for the basic_findfile_sequence. More...
class	basic_findfile_sequence_const_input_iterator
	Iterator type for the basic_findfile_sequence supporting the Input Iterator concept. More...
struct	path_compare
	A function class that compares two file-system paths. More...
struct	path_exists
	Predicate that indicates whether a given path exists. More...
class	searchspec_sequence
	Provides multi-pattern functionality over a file-system search sequence class. More...
class	basic_current_directory
	A facade for the platform's basic_current_directory functionality. More...
class	current_directory_scope
	A facade for the platform's current_directory_scope functionality. More...
class	basic_cwd_stack
	Acts as a stack for current working directory changes, setting the current working directory with push(), and resetting to its previous value with pop(). More...
class	basic_file_path_buffer
	Class used for composing and decomposing file-system paths. More...
class	filesystem_traits
	Traits class for file-system operations. More...
class	memory_mapped_file
	A facade for the platform's memory mapped file API. More...
class	basic_path
	Class used for composing and decomposing file-system paths. More...
class	pipe
	A facade for the platform's pipe functionality. More...
class	readdir_sequence
	STL-like readonly sequence based on directory contents. More...
class	searchspec_sequence
	Provides multi-pattern functionality over a file-system search sequence class. More...
class	basic_current_directory_scope
	Current directory scoping class. More...
class	basic_file_path_buffer
	Acts as a buffer with sufficient size for any drive on the host machine. More...
struct	filesystem_traits
	Traits class for file-system operations. More...
struct	path_compare
	A function class that compares two file-system paths. More...
struct	path_exists
	Predicate that indicates whether a given path exists. More...
class	glob_sequence_exception
	The exception-type thrown by unixstl::glob_sequence. More...
class	glob_sequence
	STL-like readonly sequence based on the results of file-system wildcard matches. More...
class	memory_mapped_file
	Facade over the UNIX memory mapped file API. More...
class	basic_path
	Represents a path. More...
class	pipe
	Class which wraps the UNIX pipe() function. More...
class	readdir_sequence_exception
	Exception class thrown by unixstl::readdir_sequence. More...
class	readdir_sequence
	STL-like readonly sequence based on directory contents. More...
class	readdir_sequence::const_iterator
	Iterator for the readdir_sequence class. More...
class	basic_absolute_path
	Converts a relative path to an absolute path. More...
class	basic_current_directory_scope
	Current directory scoping class. More...
class	basic_file_path_buffer
	Acts as a buffer with sufficient size for any drive on the host machine. More...
struct	filesystem_traits
	Traits for accessing the correct file-system functions for a given character type. More...
class	basic_findfile_sequence
	Presents an STL-like sequence interface over the items on the file-system. More...
class	basic_findfile_sequence_value_type
	Value type for the basic_findfile_sequence. More...
class	basic_findfile_sequence_const_input_iterator
	Iterator type for the basic_findfile_sequence supporting the Input Iterator concept. More...
class	basic_findvolume_sequence
	Presents an STL-like sequence interface over the volumes on a system. More...
class	basic_findvolume_sequence_value_type
	Value type for the basic_findvolume_sequence. More...
class	basic_findvolume_sequence_const_iterator
	Iterator type for the basic_findvolume_sequence, supporting the Input Iterator concept. More...
struct	path_compare
	Binary predicate that compares two file-system paths. More...
struct	path_compare_env
	Binary predicate object that compares two file-system paths, after expanding environment variables in the compared path strings. More...
struct	path_exists
	Unary predicate that indicates whether a given path exists. More...
struct	path_exists_env
	Unary predicate that indicates whether a given path exists, after expanding environment variables in the path string. More...
struct	path_contains_file
	Unary predicate that searches for the existance of a given file in the directory presented in its function call argument. More...
struct	path_contains_file
	Unary predicate that searches for the existance of a given file in the directory presented in its function call argument. More...
class	memory_mapped_file
	Facade over the Win32 memory mapped file API. More...
class	basic_path
	Class used for composing and decomposing file-system paths. More...
class	pipe
	Class which wraps the Win32 pipe kernel object. More...
find_data_type const &	get_find_data () const
	Accessors.
char_type const *	get_filename () const
	Returns the filename part of the item.
char_type const *	get_short_filename () const
	Returns the short form of the filename part of the item.
char_type const *	get_path () const
	Returns the full path of the item.
char_type const *	c_str () const
	Returns the full path of the item.
	operator char_type const * () const
	Implicit conversion to a pointer-to-const of the full path.
bool	is_directory () const
	Indicates whether the entry is a directory.
bool	is_file () const
	Indicates whether the entry is a file.
bool	is_read_only () const
	Indicates whether the entry is read-only.
bool	equal (char_type const *rhs) const
bool	equal (class_type const &rhs) const
Typedefs
typedef basic_findfile_sequence< char, filesystem_traits< char >, throw_internet_exception_policy >	findfile_sequence_a
	Specialisation of the basic_findfile_sequence template for the ANSI character type char.
typedef basic_findfile_sequence < wchar_t, filesystem_traits < wchar_t >, throw_internet_exception_policy >	findfile_sequence_w
	Specialisation of the basic_findfile_sequence template for the Unicode character type wchar_t.
typedef basic_findfile_sequence< TCHAR, filesystem_traits< TCHAR >, throw_internet_exception_policy >	findfile_sequence
	Specialisation of the basic_findfile_sequence template for the Win32 character type TCHAR.
typedef basic_ftpdir_sequence < wchar_t, throw_internet_exception_policy, filesystem_traits< wchar_t > >	ftpdir_sequence_w
	Specialisation of the basic_ftpdir_sequence template for the Unicode character type wchar_t.
typedef basic_ftpdir_sequence < TCHAR, throw_internet_exception_policy, filesystem_traits< TCHAR > >	ftpdir_sequence
	Specialisation of the basic_ftpdir_sequence template for the Win32 character type TCHAR.
typedef basic_file_lines< char >	file_lines_a
	Specialisation of the basic_file_lines template for the ANSI character type char.
typedef basic_file_lines< wchar_t >	file_lines_w
	Specialisation of the basic_file_lines template for the Unicode character type wchar_t.
typedef file_lines_w	wfile_lines
	Alias for platformstl::file_lines_w;.
typedef basic_current_directory_scope < char, filesystem_traits < char > >	current_directory_scope_a
	Specialisation of the basic_current_directory_scope template for the ANSI character type char.
typedef basic_current_directory_scope < wchar_t, filesystem_traits < wchar_t > >	current_directory_scope_w
	Specialisation of the basic_current_directory_scope template for the Unicode character type wchar_t.
typedef basic_current_directory_scope < char, filesystem_traits < char > >	current_directory_scope
	Specialisation of the basic_current_directory_scope template for the ambient UNIX character type char.
typedef basic_file_path_buffer < char, stlsoft::allocator_selector < char >::allocator_type >	file_path_buffer_a
	Specialisation of the basic_file_path_buffer template for the ANSI character type char.
typedef basic_file_path_buffer < wchar_t, stlsoft::allocator_selector < wchar_t >::allocator_type >	file_path_buffer_w
	Specialisation of the basic_file_path_buffer template for the Unicode character type wchar_t.
typedef basic_file_path_buffer < char, stlsoft::allocator_selector < char >::allocator_type >	file_path_buffer
	Specialisation of the basic_file_path_buffer template for the ANSI character type char.
typedef basic_path< char, filesystem_traits< char > >	path_a
	Specialisation of the basic_path template for the ANSI character type char.
typedef basic_path< wchar_t, filesystem_traits< wchar_t > >	path_w
	Specialisation of the basic_path template for the Unicode character type wchar_t.
typedef basic_path< char, filesystem_traits< char > >	path
	Specialisation of the basic_path template for the ANSI character type char.
typedef basic_absolute_path< char >	absolute_path_a
	Specialisation of the basic_absolute_path template for the ANSI character type char.
typedef basic_absolute_path < wchar_t >	absolute_path_w
	Specialisation of the basic_absolute_path template for the Unicode character type wchar_t.
typedef basic_absolute_path < TCHAR >	absolute_path
	Specialisation of the basic_absolute_path template for the Win32 character type TCHAR.
typedef basic_current_directory_scope < char, filesystem_traits < char > >	current_directory_scope_a
	Specialisation of the basic_current_directory_scope template for the ANSI character type char.
typedef basic_current_directory_scope < wchar_t, filesystem_traits < wchar_t > >	current_directory_scope_w
	Specialisation of the basic_current_directory_scope template for the Unicode character type wchar_t.
typedef basic_current_directory_scope < TCHAR, filesystem_traits < TCHAR > >	current_directory_scope
	Specialisation of the basic_current_directory_scope template for the Win32 character type TCHAR.
typedef basic_file_path_buffer < char, processheap_allocator < char > >	file_path_buffer_a
	Specialisation of the basic_file_path_buffer template for the ANSI character type char.
typedef basic_file_path_buffer < wchar_t, processheap_allocator < wchar_t > >	file_path_buffer_w
	Specialisation of the basic_file_path_buffer template for the Unicode character type wchar_t.
typedef basic_file_path_buffer < TCHAR, processheap_allocator < TCHAR > >	file_path_buffer
	Specialisation of the basic_file_path_buffer template for the ambeint character type TCHAR.
typedef basic_findfile_sequence< char, filesystem_traits< char > >	findfile_sequence_a
	Specialisation of the basic_findfile_sequence template for the ANSI character type char.
typedef basic_findfile_sequence < wchar_t, filesystem_traits < wchar_t > >	findfile_sequence_w
	Specialisation of the basic_findfile_sequence template for the Unicode character type wchar_t.
typedef basic_findfile_sequence< TCHAR, filesystem_traits< TCHAR > >	findfile_sequence
	Specialisation of the basic_findfile_sequence template for the Win32 character type TCHAR.
typedef basic_findvolume_sequence < char, filesystem_traits < char > >	findvolume_sequence_a
	Specialisation of the basic_findvolume_sequence template for the ANSI character type char.
typedef basic_findvolume_sequence < wchar_t, filesystem_traits < wchar_t > >	findvolume_sequence_w
	Specialisation of the basic_findvolume_sequence template for the Unicode character type wchar_t.
typedef basic_findvolume_sequence < TCHAR, filesystem_traits < TCHAR > >	findvolume_sequence
	Specialisation of the basic_findvolume_sequence template for the Win32 character type TCHAR.
typedef basic_path< char, filesystem_traits< char > >	path_a
	Specialisation of the basic_path template for the ANSI character type char.
typedef basic_path< wchar_t, filesystem_traits< wchar_t > >	path_w
	Specialisation of the basic_path template for the Unicode character type wchar_t.
typedef basic_path< TCHAR, filesystem_traits< TCHAR > >	path
	Specialisation of the basic_path template for the Win32 character type TCHAR.
Functions
template<typename S>
bool_t	create_directory_recurse (S const &dir)
	Creates the given directory, and any intermediate directories that do not exist.
bool	create_directory_recurse (char const *dir, unsigned short mode=0755)
	Creates the given directory, including all its parent directories, applying the given mode.
template<typename S>
bool	create_directory_recurse (S const &dir, unsigned short mode=0755)
	Creates the given directory, including all its parent directories, applying the given mode.
bool	remove_directory_recurse (char const *dir, int(*pfn)(void *param, charconst *subDir, struct stat const *st, struct dirent const *de, int err), void *param)
	Removes the given directory, and all its subdirectories.
bool	remove_directory_recurse (char const *dir)
	Removes the given directory, and all its subdirectories.
template<typename S>
bool	remove_directory_recurse (S const &dir)
template<typename C, typename T, typename A>
basic_path< C, T, A >	operator/ (basic_path< C, T, A > const &lhs, typename basic_path< C, T, A >::char_type const *rhs)
	Concatenates rhs to the path lhs.
template<typename C, typename T, typename A>
basic_path< C, T, A >	operator/ (typename basic_path< C, T, A >::char_type const *lhs, basic_path< C, T, A > const &rhs)
	Concatenates rhs to the path lhs.
template<typename C, typename T, typename A>
basic_path< C, T, A >	operator/ (basic_path< C, T, A > const &lhs, basic_path< C, T, A > const &rhs)
	Concatenates rhs to the path lhs.
bool	create_directory_recurse (char const *dir, LPSECURITY_ATTRIBUTES lpsa=NULL)
	Creates the given directory, including all its parent directories, applying the given mode.
bool	create_directory_recurse (wchar_t const *dir, LPSECURITY_ATTRIBUTES lpsa=NULL)
	Creates the given directory, including all its parent directories, applying the given mode.
template<typename S>
bool	create_directory_recurse (S const &dir, LPSECURITY_ATTRIBUTES lpsa=NULL)
	Creates the given directory, including all its parent directories, applying the given mode.
bool	remove_directory_recurse (char const *dir, int(*pfn)(void *param, charconst *subDir, WIN32_FIND_DATAA const *st, DWORD err), void *param)
	Removes the given directory, and all its subdirectories.
bool	remove_directory_recurse (wchar_t const *dir, int(*pfn)(void *param, wchar_tconst *subDir, WIN32_FIND_DATAW const *st, DWORD err), void *param)
	Removes the given directory, and all its subdirectories.
bool	remove_directory_recurse (wchar_t const *dir)
	Removes the given directory, and all its subdirectories.
STLSOFT_INLINE HANDLE	winstl__open_file_read_shared_a (char const *fileName, DWORD dwShareMode)
	Opens an existing file for shared read access.
STLSOFT_INLINE HANDLE	winstl__open_file_read_shared_w (wchar_t const *fileName, DWORD dwShareMode)
	Opens an existing file for shared read access.
STLSOFT_INLINE HANDLE	winstl__open_file_exclusive_a (char const *fileName)
	Opens an existing file for exclusive read access.
STLSOFT_INLINE HANDLE	winstl__open_file_exclusive_w (wchar_t const *fileName)
	Opens an existing file for exclusive read access.
HANDLE	open_file_read_shared (char const *fileName, DWORD dwShareMode)
	Opens an existing file for shared read access.
HANDLE	open_file_read_shared (wchar_t const *fileName, DWORD dwShareMode)
	Opens an existing file for shared read access.
HANDLE	open_file_exclusive (char const *fileName)
	Opens an existing file for exclusive read access.
HANDLE	open_file_exclusive (wchar_t const *fileName)
	Opens an existing file for exclusive read access.
template<typename S1, typename S2>
ws_uint64_t	load_text_file (S1 const &fileName, S2 &contents)
	Loads a text file into a string.
template<typename S, typename C>
C &	readlines (S const &fileName, C &container)
	Reads the lines of a text-file into a sequence container.
template<typename C, typename T, typename A>
basic_path< C, T, A >	operator/ (basic_path< C, T, A > const &lhs, typename basic_path< C, T, A >::char_type const *rhs)
	Concatenates rhs to the path lhs.
template<typename C, typename T, typename A>
basic_path< C, T, A >	operator/ (typename basic_path< C, T, A >::char_type const *lhs, basic_path< C, T, A > const &rhs)
	Concatenates rhs to the path lhs.
template<typename C, typename T, typename A>
basic_path< C, T, A >	operator/ (basic_path< C, T, A > const &lhs, basic_path< C, T, A > const &rhs)
	Concatenates rhs to the path lhs.
template<typename S, typename C>
size_t	path_squeeze (S const &path, C *buffer, size_t cchBuffer)
	Squeezes a path into a fixed length character buffer.

---

Typedef Documentation

typedef basic_absolute_path<TCHAR> absolute_path

Specialisation of the basic_absolute_path template for the Win32 character type TCHAR.

typedef basic_absolute_path< char > absolute_path_a

Specialisation of the basic_absolute_path template for the ANSI character type char.

typedef basic_absolute_path< wchar_t > absolute_path_w

Specialisation of the basic_absolute_path template for the Unicode character type wchar_t.

typedef basic_current_directory_scope<TCHAR, filesystem_traits<TCHAR> > current_directory_scope

Specialisation of the basic_current_directory_scope template for the Win32 character type TCHAR.

typedef basic_current_directory_scope<char, filesystem_traits<char> > current_directory_scope

Specialisation of the basic_current_directory_scope template for the ambient UNIX character type char.

typedef basic_current_directory_scope< char , filesystem_traits< char > > current_directory_scope_a

Specialisation of the basic_current_directory_scope template for the ANSI character type char.

typedef basic_current_directory_scope< char , filesystem_traits< char > > current_directory_scope_a

Specialisation of the basic_current_directory_scope template for the ANSI character type char.

typedef basic_current_directory_scope< wchar_t , filesystem_traits< wchar_t > > current_directory_scope_w

Specialisation of the basic_current_directory_scope template for the Unicode character type wchar_t.

typedef basic_current_directory_scope< wchar_t , filesystem_traits< wchar_t > > current_directory_scope_w

Specialisation of the basic_current_directory_scope template for the Unicode character type wchar_t.

typedef basic_file_lines< char > file_lines_a

Specialisation of the basic_file_lines template for the ANSI character type char.

typedef basic_file_lines< wchar_t > file_lines_w

Specialisation of the basic_file_lines template for the Unicode character type wchar_t.

typedef basic_file_path_buffer<TCHAR, processheap_allocator<TCHAR> > file_path_buffer

Specialisation of the basic_file_path_buffer template for the ambeint character type TCHAR.

typedef basic_file_path_buffer< char , stlsoft:: allocator_selector < char >::allocator_type> file_path_buffer

Specialisation of the basic_file_path_buffer template for the ANSI character type char.

typedef basic_file_path_buffer< char , processheap_allocator< char > > file_path_buffer_a

Specialisation of the basic_file_path_buffer template for the ANSI character type char.

typedef basic_file_path_buffer< char , stlsoft:: allocator_selector < char >::allocator_type> file_path_buffer_a

Specialisation of the basic_file_path_buffer template for the ANSI character type char.

typedef basic_file_path_buffer< wchar_t , processheap_allocator< wchar_t > > file_path_buffer_w

Specialisation of the basic_file_path_buffer template for the Unicode character type wchar_t.

typedef basic_file_path_buffer< wchar_t , stlsoft:: allocator_selector < wchar_t >::allocator_type> file_path_buffer_w

Specialisation of the basic_file_path_buffer template for the Unicode character type wchar_t.

typedef basic_findfile_sequence<TCHAR, filesystem_traits<TCHAR> > findfile_sequence

Specialisation of the basic_findfile_sequence template for the Win32 character type TCHAR.

typedef basic_findfile_sequence<TCHAR , filesystem_traits<TCHAR> , throw_internet_exception_policy > findfile_sequence

Specialisation of the basic_findfile_sequence template for the Win32 character type TCHAR.

typedef basic_findfile_sequence< char , filesystem_traits< char > > findfile_sequence_a

Specialisation of the basic_findfile_sequence template for the ANSI character type char.

typedef basic_findfile_sequence< char , filesystem_traits< char > , throw_internet_exception_policy > findfile_sequence_a

Specialisation of the basic_findfile_sequence template for the ANSI character type char.

typedef basic_findfile_sequence< wchar_t , filesystem_traits< wchar_t > > findfile_sequence_w

Specialisation of the basic_findfile_sequence template for the Unicode character type wchar_t.

typedef basic_findfile_sequence< wchar_t , filesystem_traits< wchar_t > , throw_internet_exception_policy > findfile_sequence_w

Specialisation of the basic_findfile_sequence template for the Unicode character type wchar_t.

typedef basic_findvolume_sequence<TCHAR, filesystem_traits<TCHAR> > findvolume_sequence

Specialisation of the basic_findvolume_sequence template for the Win32 character type TCHAR.

typedef basic_findvolume_sequence< char , filesystem_traits< char > > findvolume_sequence_a

Specialisation of the basic_findvolume_sequence template for the ANSI character type char.

typedef basic_findvolume_sequence< wchar_t , filesystem_traits< wchar_t > > findvolume_sequence_w

Specialisation of the basic_findvolume_sequence template for the Unicode character type wchar_t.

typedef basic_ftpdir_sequence<TCHAR , throw_internet_exception_policy , filesystem_traits<TCHAR> > ftpdir_sequence

Specialisation of the basic_ftpdir_sequence template for the Win32 character type TCHAR.

typedef basic_ftpdir_sequence< wchar_t , throw_internet_exception_policy , filesystem_traits< wchar_t > > ftpdir_sequence_w

Specialisation of the basic_ftpdir_sequence template for the Unicode character type wchar_t.

typedef basic_path<TCHAR, filesystem_traits<TCHAR> > path

Specialisation of the basic_path template for the Win32 character type TCHAR.

typedef basic_path< char , filesystem_traits< char > > path

Specialisation of the basic_path template for the ANSI character type char.

typedef basic_path< char , filesystem_traits< char > > path_a

Specialisation of the basic_path template for the ANSI character type char.

typedef basic_path< char , filesystem_traits< char > > path_a

Specialisation of the basic_path template for the ANSI character type char.

typedef basic_path< wchar_t , filesystem_traits< wchar_t > > path_w

Specialisation of the basic_path template for the Unicode character type wchar_t.

typedef basic_path< wchar_t , filesystem_traits< wchar_t > > path_w

Specialisation of the basic_path template for the Unicode character type wchar_t.

typedef file_lines_w wfile_lines

Alias for platformstl::file_lines_w;.

---

Function Documentation

char_type const* c_str

(

)

const [inherited]

Returns the full path of the item.

bool winstl::create_directory_recurse	(	S const &	dir,
		LPSECURITY_ATTRIBUTES	lpsa = NULL
	)			[inline]

Creates the given directory, including all its parent directories, applying the given mode.

Parameters:

	dir	The path of the directory to create
	lpsa	The security attributes with which each directory is to be created

bool winstl::create_directory_recurse	(	wchar_t const *	dir,
		LPSECURITY_ATTRIBUTES	lpsa = NULL
	)			[inline]

Creates the given directory, including all its parent directories, applying the given mode.

Parameters:

	dir	The path of the directory to create
	lpsa	The security attributes with which each directory is to be created

bool winstl::create_directory_recurse	(	char const *	dir,
		LPSECURITY_ATTRIBUTES	lpsa = NULL
	)			[inline]

Creates the given directory, including all its parent directories, applying the given mode.

Parameters:

	dir	The path of the directory to create
	lpsa	The security attributes with which each directory is to be created

bool unixstl::create_directory_recurse	(	S const &	dir,
		unsigned short	mode = 0755
	)			[inline]

Creates the given directory, including all its parent directories, applying the given mode.

Parameters:

	dir	The path of the directory to create
	mode	The permissions with which each directory is to be created

bool unixstl::create_directory_recurse	(	char const *	dir,
		unsigned short	mode = 0755
	)			[inline]

Creates the given directory, including all its parent directories, applying the given mode.

Parameters:

	dir	The path of the directory to create
	mode	The permissions with which each directory is to be created

bool_t platformstl::create_directory_recurse

(

S const &

dir

)

[inline]

Creates the given directory, and any intermediate directories that do not exist.

char_type const* get_filename

(

)

const [inherited]

Returns the filename part of the item.

find_data_type const& get_find_data

(

)

const [inherited]

Accessors.

Returns a non-mutating reference to find-data

char_type const* get_path

(

)

const [inherited]

Returns the full path of the item.

char_type const* get_short_filename

(

)

const [inherited]

Returns the short form of the filename part of the item.

bool is_directory

(

)

const [inherited]

Indicates whether the entry is a directory.

bool is_file

(

)

const [inherited]

Indicates whether the entry is a file.

bool is_read_only

(

)

const [inherited]

Indicates whether the entry is read-only.

ws_uint64_t winstl::load_text_file	(	S1 const &	fileName,
		S2 &	contents
	)			[inline]

Loads a text file into a string.

Parameters:

	fileName	The name/path of the text file to load. Can be nul-terminated C-style string, or a string object
	contents	A reference to a string instance into which the contents will be loaded (with the assign() method)

Returns:

The number of bytes read from the file

std::string       contents;
winstl::uint64_t  numBytes = winstl::load_text_file("mytextfile.ext", contents);

Remarks:

The character type of the text file is assumed (and controlled) to be that of the contents parameter. For example, if contents is of type std::wstring then the file will be processed as if it contains wchar_t.

Note:

When used with a compiler that does not support partial template specialisation, the use of string types for which explicit specialisations are not defined will fail. Hence, using stlsoft::simple_string (which is the specialisation stlsoft::basic_simple_string<char>) will succeed because a specialisation of stlsoft::string_traits exists for that type. The same applies for stlsoft::simple_wstring, std::string and std::wstring. However, if you attempt to use a specialisation of a string class template for which an explicit specialisation of stlsoft::string_traits does not exist then you will experience a compile-time error in the implementation of winstl::load_text_file_impl(). To correct this, you must either provide an explicit specialisation of stlsoft::string_traits for your type, or use a type for which a specialisation of stlsoft::string_traits does exist.

This problem does not occur for compilers that support partial template specialisation.

HANDLE winstl::open_file_exclusive

(

wchar_t const *

fileName

)

[inline]

Opens an existing file for exclusive read access.

HANDLE winstl::open_file_exclusive

(

char const *

fileName

)

[inline]

Opens an existing file for exclusive read access.

HANDLE winstl::open_file_read_shared	(	wchar_t const *	fileName,
		DWORD	dwShareMode
	)			[inline]

Opens an existing file for shared read access.

HANDLE winstl::open_file_read_shared	(	char const *	fileName,
		DWORD	dwShareMode
	)			[inline]

Opens an existing file for shared read access.

operator char_type const *

(

)

const [inherited]

Implicit conversion to a pointer-to-const of the full path.

basic_path<C, T, A> winstl::operator/	(	basic_path< C, T, A > const &	lhs,
		basic_path< C, T, A > const &	rhs
	)			[inline]

Concatenates rhs to the path lhs.

basic_path<C, T, A> winstl::operator/	(	typename basic_path< C, T, A >::char_type const *	lhs,
		basic_path< C, T, A > const &	rhs
	)			[inline]

Concatenates rhs to the path lhs.

basic_path<C, T, A> winstl::operator/	(	basic_path< C, T, A > const &	lhs,
		typename basic_path< C, T, A >::char_type const *	rhs
	)			[inline]

Concatenates rhs to the path lhs.

basic_path<C, T, A> unixstl::operator/	(	basic_path< C, T, A > const &	lhs,
		basic_path< C, T, A > const &	rhs
	)			[inline]

Concatenates rhs to the path lhs.

basic_path<C, T, A> unixstl::operator/	(	typename basic_path< C, T, A >::char_type const *	lhs,
		basic_path< C, T, A > const &	rhs
	)			[inline]

Concatenates rhs to the path lhs.

basic_path<C, T, A> unixstl::operator/	(	basic_path< C, T, A > const &	lhs,
		typename basic_path< C, T, A >::char_type const *	rhs
	)			[inline]

Concatenates rhs to the path lhs.

size_t winstl::path_squeeze	(	S const &	path,
		C *	buffer,
		size_t	cchBuffer
	)			[inline]

Squeezes a path into a fixed length character buffer.

Parameters:

	path	The path
	buffer	Pointer to the buffer into which the sqeezed path will be written. If NULL, function returns required size (=== len(path) + 1)
	cchBuffer	The number of available characters inc buffer. This value in inclusive of the required nul-terminator

Returns:

The number of characters required (if buffer is NULL), or the number of characters written (if buffer is non-NULL). In both cases, it includes the one required for the nul-terminator

Remarks:

The squeeze algorithm is as follows. The path is split into volume+directory and file+ext. If the buffer is too small to fit the file+ext, then the result will be a squeezed form of file+ext. If the buffer is too small to fit the volume+...+file+ext, then the result will be file+ext. If the buffer is too small to fit the entire path, then the result will be volume+part_of_directory+...+file+ext. Otherwise the result will be the full path.

C& winstl::readlines	(	S const &	fileName,
		C &	container
	)			[inline]

Reads the lines of a text-file into a sequence container.

Parameters:

	fileName	The name of the text-file to load
	container	Reference to the sequence container to which each line read from fileName will be appended (via its push_back() method)

Returns:

The container reference

std::vector<std::string>  lines;

winstl::readlines("mytextfile.ext", lines);

Remarks:

The container type's value_type must provide a two-parameter constructor whose parameters types are char_type const* (where char_type is the value_type of the string type S) and size_t, indicating the pointer to the beginning and the length of the C-style string that represents the line read from the file denoted by fileName.

Note:

When used with a compiler that does not support partial template specialisation, the use of string types for which explicit specialisations are not defined will fail. Hence, using stlsoft::simple_string (which is the specialisation stlsoft::basic_simple_string<char>) will succeed because a specialisation of stlsoft::string_traits exists for that type. The same applies for stlsoft::simple_wstring, std::string and std::wstring. However, if you attempt to use a specialisation of a string class template for which an explicit specialisation of stlsoft::string_traits does not exist then you will experience a compile-time error in the implementation of winstl::load_text_file_impl(). To correct this, you must either provide an explicit specialisation of stlsoft::string_traits for your type, or use a type for which a specialisation of stlsoft::string_traits does exist.

This problem does not occur for compilers that support partial template specialisation.

bool winstl::remove_directory_recurse

(

wchar_t const *

dir

)

[inline]

Removes the given directory, and all its subdirectories.

bool winstl::remove_directory_recurse	(	wchar_t const *	dir,
		int(*)(void *param, wchar_tconst *subDir, WIN32_FIND_DATAW const *st, DWORD err)	pfn,
		void *	param
	)			[inline]

Removes the given directory, and all its subdirectories.

bool winstl::remove_directory_recurse	(	char const *	dir,
		int(*)(void *param, charconst *subDir, WIN32_FIND_DATAA const *st, DWORD err)	pfn,
		void *	param
	)			[inline]

Removes the given directory, and all its subdirectories.

Parameters:

	dir	The path of the directory to remove
	pfn	Pointer to a callback function, which will receive notifications and requests for file/directory deletion. The semantics of the parameters are specified in the note below
	param	Caller-supplied parameter, passed through to the callback function

Note:

If no callback function is specified, then the function will remove only empty subdirectories, i.e. no files will be removed. To remove files, a function must be

The semantics of the callback function's parameters are as follows:

If the err param is ~0 (-1 on UNIX), then the dir param specifies

the name of the current directory being traversed. All other params are unspecified. The return value is ignored.

If the err param is 0 and the st param is NULL, then dir specifies

the name of a directory that has been successfully removed. All other params are unspecified. The return value is ignored.

If the err param is 0 and the st param is not NULL, then dir specifies

the name of the currently traversing directory, st specifies the stat information and the name of the entry within directory dir that is a candidate for removal. Return >0 to enable removal of this entry, or 0 to prevent removal and cancel the overall operation, or <0 to prevent removal and continue. All other params are unspecified. The return value is ignored.

If the err param is any other value, and the st param is NULL, then

the dir param specifies the name of a directory that could not be deleted and err specifies the errno value associated with the failure. All other params are unspecified. The return value is ignored.

If the err param is any other value, and the st param is not NULL, then

the dir param specifies the name of a directory within which an entry could not be deleted, st specifies the stat information and the name of the entry that could not be deleted, and err specifies the errno value associated with the failure. All other params are unspecified. The return value is ignored.

bool unixstl::remove_directory_recurse

(

char const *

dir

)

[inline]

Removes the given directory, and all its subdirectories.

bool unixstl::remove_directory_recurse	(	char const *	dir,
		int(*)(void *param, charconst *subDir, struct stat const *st, struct dirent const *de, int err)	pfn,
		void *	param
	)			[inline]

Removes the given directory, and all its subdirectories.

Parameters:

	dir	The path of the directory to remove
	pfn	Pointer to a callback function, which will receive notifications and requests for file/directory deletion. The semantics of the parameters are specified in the note below
	param	Caller-supplied parameter, passed through to the callback function

Note:

If no callback function is specified, then the function will remove only empty subdirectories, i.e. no files will be removed. To remove files, a function must be

The semantics of the callback function's parameters are as follows:

If the err param is ~0 (-1 on UNIX), then the dir param specifies

the name of the current directory being traversed. All other params are unspecified. The return value is ignored.

If the err param is 0 and the st param is NULL, then dir specifies

the name of a directory that has been successfully removed. All other params are unspecified. The return value is ignored.

If the err param is 0 and the st param is not NULL, then dir specifies

the name of the currently traversing directory, st specifies the stat information for the entry to be deleted, and de specifies the name of the entry within directory dir that is a candidate for removal. Return true to enable removal of this entry, or false to prevent removal (and cancel the overall operation). All other params are unspecified. The return value is ignored.

If the err param is any other value, and the st param is NULL, then

the dir param specifies the name of a directory that could not be deleted and err specifies the errno value associated with the failure. All other params are unspecified. The return value is ignored.

If the err param is any other value, and the st param is not NULL, then

the dir param specifies the name of a directory within which an entry could not be deleted, st specifies the stat information of the entry that could not be deleted, de specifies the name of the entry that could not be deleted, and err specifies the errno value associated with the failure. All other params are unspecified. The return value is ignored.

STLSOFT_INLINE HANDLE winstl__open_file_exclusive_a

(

char const *

fileName

)

Opens an existing file for exclusive read access.

STLSOFT_INLINE HANDLE winstl__open_file_exclusive_w

(

wchar_t const *

fileName

)

Opens an existing file for exclusive read access.

STLSOFT_INLINE HANDLE winstl__open_file_read_shared_a	(	char const *	fileName,
		DWORD	dwShareMode
	)

Opens an existing file for shared read access.

STLSOFT_INLINE HANDLE winstl__open_file_read_shared_w	(	wchar_t const *	fileName,
		DWORD	dwShareMode
	)

Opens an existing file for shared read access.

---