FileName Class Reference

A file's name and handle for invoking many file system functions. More...

#include <file.h>

Collaboration diagram for FileName:

[legend]

List of all members.

Classes
struct	Accum
	An Accum object is a template class object whose role is to provide a generic interface for any standard sequence container to the accumulate_lines virtual interface. More...
struct	accumulate_lines
	A class of functor objects whose purpose is to provide a generic interface between the read_* functions, below, and some container used to hold lines read. More...
struct	FileNameSorter
struct	is_separator
	A functor that tells you if a specifed character is a path sepator. It is meant to be used as a parameter to StrTool::parse_words -- or any function needing a predicate indicating that a character is the path separator. More...
class	Tree
	A tree of file names, representing a directory hierarcy. More...
Public Types
typedef rep_t::const_iterator	const_iterator
	const Iterator to characters in the filename
typedef rep_t::iterator	iterator
	mutable iterator to characters in the file name
typedef FileStatus::file_size_t	off_t
	The data type of the file's size.
typedef std::string	rep_t
	actual representation of the file's name
typedef std::set< FileName, FileNameSorter >	sorted_names_t
	Alphabetically sorted set of FileNames.
Public Member Functions
rep_t	basename (bool remove_extension=false) const
	Get the filename part of the pathname.
iterator	begin ()
	Get a pointer to the first char in the name.
const_iterator	begin () const
	Get a pointer to the first char in the name.
char const *	c_str () const
	Get a old fashion C string from the filename.
bool	chmod (FileMode) const
	Set the mode (ie permissions, or attributes) on the file named by this to the mode specified.
void	convert_to_absolute_path ()
	Adds the name of the current directory to a file name if it has no directory part specified.
void	convertToDirectorySearchPattern (char const *pattern="*")
void	convertToDirectorySearchPattern (std::string const &pattern)
	Assume that this FileName is a directory name and add specified pattern to it to make it into a directory search pattern (or a simple filename if the pattern contains no wildcard characters).
bool	copy (FileName const &destination) const
	Copy the file whose name is specified '*this' into a new file whose name is specified in destination.
char const *	data () const
	Get a pointer to the non-nul terminated filename.
rep_t	dirname () const
	Get only the directory part of the pathname.
bool	empty () const
	return true if the filename is an emtpy string
iterator	end ()
	Get a ptr to first char after name.
const_iterator	end () const
	Get a ptr to first char after name.
void	erase (size_t o)
	Erase the character at offset o.
void	erase (size_t o, size_t l)
	Erase l characters at offset o.
void	erase (iterator a, iterator b)
	Erase a range of characters.
void	erase (iterator a)
	Erase the character at location.
bool	exists () const
FileName	expand_tildes () const
rep_t	extension () const
	Get the file name extension part of the pathname.
FileMode	file_mode () const
off_t	file_size () const
bool	file_stat (FileStatus *s, bool l=false) const
	Get status of named file, return true if error. If the optional second parameter is 'true' then read the status of the link corresponding to the file name. The default is to read through the link to get the status of the file or directory to which the link points.
bool	file_time (FileTime *t) const
	Inquire the file time.
	FileName (FileName const &r)
	copy construct
	FileName (std::string const &r)
	construct from a string
	FileName (char const *r)
	construct form a char const*
	FileName ()
	FileName() default constructor.
void	insert (size_t o, rep_t const &s)
	Insert a string at an offset.
void	insert (size_t o, char const *s)
	Insert a string at an offset.
void	insert (iterator a, char c)
	Insert a character at a location.
bool	is_absolute_path () const
bool	is_createable () const
bool	is_dir () const
bool	is_executable () const
bool	is_readable () const
bool	is_root_dir () const
bool	is_syntactically_valid () const
bool	is_writeable () const
bool	matches (rep_t pattern) const
bool	matches (char const *pattern) const
	Does the filename match a given naming patttern (shell style).
bool	mkdir (FileMode m=FileMode(" drwxrwxrwx")) const
	Make a directory whose name is given by this filename. Return true if an error occurred. The 'directory' bit of the FileMode is assumed -- and thus ignored.
	operator std::string & ()
	Convert to string &.
	operator std::string const & () const
	Convert to const string &.
FileName	operator+ (std::string const &r) const
	concatenate the filename with a std::string to make a new filename
FileName	operator+ (char const *r) const
	concatenate the filename with a c style string to make a new filename
FileName	operator+ (FileName const &r) const
	append a file name to this file name
FileName &	operator+= (std::string const &r)
	append a string to this file name
FileName &	operator+= (char c)
	append a character to this file name
FileName &	operator+= (char const *p)
	append a string to this file name
bool	operator< (std::string const &rhs) const
	Compare this filename's string component against.
template<class T >
FileName &	operator= (T const &rhs)
	Assign this FileName from some other string source.
bool	operator== (char const *rhs) const
	compare a filename to a c style string
bool	operator== (std::string const rhs) const
	compare a filename to a string
bool	operator== (FileName const rhs) const
	Compare two filenames.
char &	operator[] (size_t i)
	Get a ref to the character at a specified offset from the start of the string.
char	operator[] (size_t i) const
	Get the character at a specified offset from the start of the string.
template<class Container >
std::string	read_file (Container &container, size_t *line_count_ptr=0)
	Read a whole file into a container of std::string's. Return any error text as a std::string as well. If the return string is empty then no errors have occurred.
std::string	read_lines (accumulate_lines &accum, size_t *line_count_ptr=0, bool removeCR=false)
	This function lets you read lines from the file whose name contained in this filename very quickly. You probably want to use the FileName::read_file function below instead of calling this function. It simplifies the interface significantly.
FileName	readlink (int *returnedMode=0) const
	Assume that this filename refers to a symbolic link file and attempt to read through the link to get the name of the thing it points to. If the optional mode pointer is passed in also read the symbolic link's file mode and return it in *returnMode; Note that normally the FileMode of a symbolic link is a mix of the attributes of the link itself and the thing it points to. The mix works like this:
bool	remove () const
	Remove the file named by this FileName.
bool	rename (FileName const &destination) const
	Rename the file whose name is specified '*this' into a new file whose name is specified in destination.
bool	rmdir () const
	Remove the directory named by this filename.
std::string	shorten (int max_chars) const
	Produce a string which is a shortened version of the filename by deleting excess characters and inserting an elipses in the middle to signify missing characters. The name will not refer to a real file (unless by accident).
size_t	size () const
	Get length of string.
size_t	slurp (std::list< std::string > *lines) const
	Read the whole file (binary read) into a list of strings return the number of lines read. This is the fastest way to read a file into a bunch of strings.
void	slurp (FileContents *f) const
	Read whole file (binary read) into a FileContents object and set its error method correctly.
rep_t	substr (size_t s, size_t l) const
	Get a substring given a start ofset a number of characters.
std::auto_ptr< Tree >	tree (bool only_dirs=false) const
	Get the subdirectory tree starting with this filename. If this filename refers to a normal file, then tree will have only one node. If this does not refer to a valid file, one node will be returned but the 'status' will indicate that it is not a good file. If this FileName is a directory, then the sub-directory tree will be returned. If any node's status is not avaialable, its status will indicate that.
bool	write (char const *begin, char const *end, bool binary_mode=true)
	Open the file whose name is contained in this FileName object and write the data found between begin and end to the file in either ascii or binary mode depending on the binary_mode flag. On unix, this flag is ignored. The file will be created with default umask permission.
bool	write (std::string const &file_contents, bool binary_mode=true)
	Write a string to a newly create file whose name is the contained in this filename. If the file previously existed, it will be deleted then recreated.
Static Public Member Functions
static int	compareIgnoringPathSeparatorDifferences (std::string const &l, std::string const &r)
static int	compareIgnoringPathSeparatorDifferences (char const *l, char const *r, size_t lsize, size_t rsize)
static FileName	find_executable (std::string progname, std::string path="")
	Search the specified path, or the current PATH environment variable for the named program.
static FileName	find_file_in_path (std::string filename, std::string path="")
	Search a path for a given file -- executable or not. See find_executable for the general idea. This function, finds any file, not just executables.
static int	find_matching (rep_t pattern, sorted_names_t *l, int options=0)
static int	find_matching (char const *pattern, sorted_names_t *matches, int options=0)
	A static method that finds a list of FileName's matching a specified pattern by reading the file system directory and comparing the file names to the requested pattern.
static FileName	getcwd ()
	static function to get the current working directory as a filename
static FileName	mktemp (FileName dir="./")
	static function that will return a FileName with the name of a temporary file in the specified directory.
Static Public Attributes
static char	PATH_separator = ':'
	Either : or ; depending on the os This variable defines what character separates components of the PATH environment variable.
Private Member Functions
std::auto_ptr< Tree >	tree_helper (std::string const &path, bool only_dirs=false, int depth=0) const
	used by tree() to recurse through directory hierarchies
Private Attributes
rep_t	impl_
	The string that is the file name.
Friends
std::string	operator+ (char const *lhs, FileName const &rhs)
	global free function to concatenate c style strings and filenames producing std::strings'
std::string	operator+ (std::string const &lhs, FileName const &rhs)
	global free function to concatenate strings and filenames, producing std::strings
bool	operator== (char const *lhs, FileName const &rhs)
	global free function to compare a c style string to a filename
bool	operator== (std::string const &lhs, FileName const &rhs)
	global free function to compare a std::string to a filename

---

Detailed Description

A file's name and handle for invoking many file system functions.

FileName is a generalized utility class for performing file operations. A FileName has much in common with std::string but adds many additional member functions that are associated with operating systems calls involving files:

• is_dir()
• is_link()
• exists()
• basename()
• dirname()
• convert_to_absolute_path()
• mkdir()
• and many more.

Basically this class has everything in it but the kitchen sink.

A FileName is not a string, but it can be converted to a string &, or string const & with high speed.

Definition at line 490 of file file.h.

---

Member Typedef Documentation

typedef rep_t::const_iterator const_iterator

const Iterator to characters in the filename

Definition at line 528 of file file.h.

typedef rep_t::iterator iterator

mutable iterator to characters in the file name

Definition at line 529 of file file.h.

typedef FileStatus::file_size_t off_t

The data type of the file's size.

Definition at line 527 of file file.h.

typedef std::string rep_t

actual representation of the file's name

Definition at line 526 of file file.h.

typedef std::set<FileName, FileNameSorter> sorted_names_t

Alphabetically sorted set of FileNames.

Definition at line 524 of file file.h.

---

Constructor & Destructor Documentation

FileName

(

)

FileName() default constructor.

Definition at line 605 of file file.h.

FileName

(

char const *

r

)

construct form a char const*

Definition at line 609 of file file.h.

FileName

(

std::string const &

r

)

construct from a string

Definition at line 614 of file file.h.

FileName

(

FileName const &

r

)

copy construct

Definition at line 619 of file file.h.

---

Member Function Documentation

rep_t basename

(

bool

remove_extension = false

)

const

Get the filename part of the pathname.

Returns:

the file name part of a pathname (including extension)

Definition at line 436 of file file.cxx.

Here is the caller graph for this function:

iterator begin

(

)

Get a pointer to the first char in the name.

Definition at line 541 of file file.h.

const_iterator begin

(

)

const

Get a pointer to the first char in the name.

Definition at line 538 of file file.h.

Here is the caller graph for this function:

char const* c_str

(

)

const

Get a old fashion C string from the filename.

Definition at line 543 of file file.h.

Here is the caller graph for this function:

bool chmod

(

FileMode

mode

)

const

Set the mode (ie permissions, or attributes) on the file named by this to the mode specified.

Definition at line 1740 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

static int compareIgnoringPathSeparatorDifferences	(	std::string const &	l,
		std::string const &	r
	)			[static]

Returns:

a signed integer indicating the comparison of l and r while ignoring / vs \ differences. negative means that l is less than r, positive means that it is greater

Definition at line 1210 of file file.h.

static int compareIgnoringPathSeparatorDifferences	(	char const *	l,
		char const *	r,
		size_t	lsize,
		size_t	rsize
	)			[static]

Returns:

a signed integer indicating the comparison of l and r while ignoring / vs \ differences. negative means that l is less than r, positive means that it is greater

Definition at line 1160 of file file.h.

void convert_to_absolute_path

(

)

Adds the name of the current directory to a file name if it has no directory part specified.

Definition at line 578 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

void convertToDirectorySearchPattern

(

char const *

pattern = "*"

)

Assume that this FileName is a directory name and add specified pattern to it to make it into a directory search pattern (or a simple filename if the pattern contains no wildcard characters). If this is a directory, or it ends in / or \, add * to the end as needed to make this a directory search pattern.

Parameters:

pattern

is the "*.c", or other pattern you are trying to construct from this directory.

Definition at line 2449 of file file.cxx.

Here is the call graph for this function:

void convertToDirectorySearchPattern

(

std::string const &

pattern

)

Assume that this FileName is a directory name and add specified pattern to it to make it into a directory search pattern (or a simple filename if the pattern contains no wildcard characters).

If this is a directory, or it ends in / or \, add * to the end as needed to make this a directory search pattern.

Parameters:

pattern

is the "*.c", or other pattern you are trying to construct from this directory.

Definition at line 774 of file file.h.

Here is the caller graph for this function:

bool copy

(

FileName const &

destination

)

const

Copy the file whose name is specified '*this' into a new file whose name is specified in destination.

Directories cannot be copied using this function -- and error will result.

Parameters:

destination

The name of the file where the copy goes.

Returns:

true if an error occurred.

Definition at line 1686 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

char const* data

(

)

const

Get a pointer to the non-nul terminated filename.

Definition at line 544 of file file.h.

Here is the caller graph for this function:

rep_t dirname

(

)

const

Get only the directory part of the pathname.

Returns:

the directory part of self by removing the filename part and leaving the trailing /.

Definition at line 511 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool empty

(

)

const

return true if the filename is an emtpy string

Definition at line 559 of file file.h.

Here is the caller graph for this function:

iterator end

(

)

Get a ptr to first char after name.

Definition at line 542 of file file.h.

const_iterator end

(

)

const

Get a ptr to first char after name.

Definition at line 539 of file file.h.

Here is the caller graph for this function:

void erase

(

size_t

o

)

Erase the character at offset o.

Definition at line 555 of file file.h.

void erase	(	size_t	o,
		size_t	l
	)

Erase l characters at offset o.

Definition at line 554 of file file.h.

void erase	(	iterator	a,
		iterator	b
	)

Erase a range of characters.

Definition at line 553 of file file.h.

void erase

(

iterator

a

)

Erase the character at location.

Definition at line 552 of file file.h.

Here is the caller graph for this function:

bool exists

(

)

const

Returns:

true if the filename refers to an existing file.

Definition at line 792 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileName expand_tildes

(

)

const

Returns:

a copy of self with ~ expansion handled. For example:

~/.bashrc becomes /home/user/.bashrc

and

~lboggs/.bashrc

becomes

/home/lboggs/.bashrc

Note that the prefix, /home/, is just an example. The real results will depend on the home directory of the specified user -- as determined by passwd() method.

Definition at line 2369 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

string extension

(

)

const

Get the file name extension part of the pathname.

Returns:

the file name extension part of a filename.

Definition at line 1771 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileMode file_mode

(

)

const

Returns:

FileMode of the named file

Definition at line 982 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileName::off_t file_size

(

)

const

Returns:

the size of named file (or -1 on error)

Definition at line 998 of file file.cxx.

Here is the call graph for this function:

bool file_stat	(	FileStatus *	s,
		bool	l = false
	)			const

Get status of named file, return true if error. If the optional second parameter is 'true' then read the status of the link corresponding to the file name. The default is to read through the link to get the status of the file or directory to which the link points.

Parameters:

[in]	s	The place to store the status of the file whose name is contained in *this.
[in]	l	A default flag indicating that if the filename referes to a link the then data for the link should be read instead of for the link itself. Normally, this is not set, the default is the most desireable form. Only directory display programs need read the link itself.

Definition at line 804 of file file.cxx.

Here is the caller graph for this function:

bool file_time

(

FileTime *

t

)

const

Inquire the file time.

Parameters:

t

A pointer to a FileTime data structure to hold the time.

Returns:

true if an error occurred.

Definition at line 1012 of file file.cxx.

Here is the call graph for this function:

FileName find_executable	(	std::string	progname,
		std::string	path = ""
	)			[static]

Search the specified path, or the current PATH environment variable for the named program.

Parameters:

	progname	is the name of an executable to search for
	path	is a platform specific directory path (unix: colon separated, windows: semicolon separated)

Returns:

the name of the found file -- or empty string.

How this works varies a bit from os to os. If no path is specified, or the path is an empty string, the current PATH environment variable will be used for the search. On Windows, the PATH variable is separated by spaces and semicolons but on unix it is separated by only colons. Further, on Windows, the program name may not include the file name extension which is one of .bat, .com, .exe, .cmd. On these systems, this will be automatically appended during the search.

Definition at line 1416 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileName find_file_in_path	(	std::string	filename,
		std::string	path = ""
	)			[static]

Search a path for a given file -- executable or not. See find_executable for the general idea. This function, finds any file, not just executables.

Parameters:

	filename	is the name of the file to search for
	path	is a directory search path dependend in form on the os you are on.

Returns:

the name of the found file -- or empty string.

Definition at line 1517 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

static int find_matching	(	rep_t	pattern,
		sorted_names_t *	l,
		int	options = 0
	)			[static]

A static method that finds a list of FileName's matching a specified pattern by reading the file system directory and comparing the file names to the requested pattern.

Parameters:

	pattern	is the search pattern: "*.exe", "/home/dir/files*.*", etc.
	matches	is a set of strings into which to place the matching filenames.
	options	is selector for the kinds of files you want to include -- see below.

Returns:

a count of the matching files.

The 'options' parameter specifies flags to be interpreted with respect to the returned list of matching filenames. The value passed to options are a bit mask with the following intepretation:

       0x00 -- all files are included in the output data but the results
               do not contain the pathnames specified in the pattern, 
               only the basename's of the matches.
    
       0x01 -- all files are included in the output data and the results
               _do_ contain the pathname specified in the pattern.
    
       0x02 -- only directories are included but no paths are included.
    
       0x03 -- only directories, and the paths are included.
    
       0x04 -- NO directories are included and no paths are included
       0x05 -- NO directories are included but the paths are.

Definition at line 830 of file file.h.

int find_matching	(	char const *	pattern,
		sorted_names_t *	matches,
		int	options = 0
	)			[static]

A static method that finds a list of FileName's matching a specified pattern by reading the file system directory and comparing the file names to the requested pattern.

Parameters:

	pattern	is the search pattern: "*.exe", "/home/dir/files*.*", etc.
	matches	is a set of strings into which to place the matching filenames.
	options	is selector for the kinds of files you want to include -- see below.

Returns:

a count of the matching files.

The 'options' parameter specifies flags to be interpreted with respect to the returned list of matching filenames. The value passed to options are a bit mask with the following intepretation:

       0x00 -- all files are included in the output data but the results
               do not contain the pathnames specified in the pattern, 
               only the basename's of the matches.
    
       0x01 -- all files are included in the output data and the results
               _do_ contain the pathname specified in the pattern.
    
       0x02 -- only directories are included but no paths are included.
    
       0x03 -- only directories, and the paths are included.
    
       0x04 -- NO directories are included and no paths are included
       0x05 -- NO directories are included but the paths are.

Definition at line 1080 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileName getcwd

(

)

[static]

static function to get the current working directory as a filename

Definition at line 2105 of file file.cxx.

Here is the caller graph for this function:

void insert	(	size_t	o,
		rep_t const &	s
	)

Insert a string at an offset.

Definition at line 558 of file file.h.

void insert	(	size_t	o,
		char const *	s
	)

Insert a string at an offset.

Definition at line 557 of file file.h.

void insert	(	iterator	a,
		char	c
	)

Insert a character at a location.

Definition at line 556 of file file.h.

Here is the caller graph for this function:

bool is_absolute_path

(

)

const

Returns:

true if the filename begins with root directory

Definition at line 1893 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool is_createable

(

)

const

Returns:

true if writeable or parent dir is writeable

Definition at line 964 of file file.cxx.

Here is the call graph for this function:

bool is_dir

(

)

const

Returns:

true if the named file exists and is a directory

Definition at line 924 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool is_executable

(

)

const

Returns:

true if the named file exists and is executable

Definition at line 939 of file file.cxx.

Here is the call graph for this function:

bool is_readable

(

)

const

Returns:

true if the named file exists and is readable

Definition at line 956 of file file.cxx.

Here is the call graph for this function:

bool is_root_dir

(

)

const

Returns:

true if filename is / on unix or c:\ on windows

Definition at line 1914 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool is_syntactically_valid

(

)

const

Returns:

true if the file name has no bad characters in it.

Definition at line 766 of file file.cxx.

Here is the call graph for this function:

bool is_writeable

(

)

const

Returns:

true if the named file exists and is writeable

Definition at line 948 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool matches

(

rep_t

pattern

)

const

Does the filename match a given naming patttern (shell style).

Parameters:

pattern

is a file name search pattern: "*.c", etc.

Returns:

true if the file name matches the pattern.

Definition at line 708 of file file.h.

bool matches

(

char const *

pattern

)

const

Does the filename match a given naming patttern (shell style).

Parameters:

pattern

is a file name search pattern: "*.c", etc.

Returns:

true if the file name matches the pattern.

Definition at line 1027 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool mkdir

(

FileMode

m = FileMode(" drwxrwxrwx")

)

const

Make a directory whose name is given by this filename. Return true if an error occurred. The 'directory' bit of the FileMode is assumed -- and thus ignored.

Returns:

true if an error occurs.

Definition at line 1641 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileName mktemp

(

FileName

dir = "./"

)

[static]

static function that will return a FileName with the name of a temporary file in the specified directory.

Parameters:

dir

is the name of a directory where the temporary file will go.

Returns:

a FileName object with the name of a file that does not yet exist in the specified directory. The name will be some numeric pattern.

That is, this function produces the name of a file in the specified directory that does not yet exist -- for use in creating temporary files. The directory parameter is optional -- the default being the current directory.

When specifying a directory name, you must supply the trailing slash and you may also include a prefix for the file. Here are some valid examples:

       FileName::mktemp();
       FileName::mktemp("/tmp/");
       FileName::mktemp("../../junk_");

Definition at line 1371 of file file.cxx.

Here is the call graph for this function:

operator std::string &

(

)

Convert to string &.

Definition at line 536 of file file.h.

operator std::string const &

(

)

const

Convert to const string &.

Definition at line 537 of file file.h.

FileName operator+

(

std::string const &

r

)

const

concatenate the filename with a std::string to make a new filename

Definition at line 1126 of file file.h.

FileName operator+

(

char const *

r

)

const

concatenate the filename with a c style string to make a new filename

Definition at line 1117 of file file.h.

FileName operator+

(

FileName const &

r

)

const

append a file name to this file name

Definition at line 1108 of file file.h.

FileName& operator+=

(

std::string const &

r

)

append a string to this file name

Definition at line 594 of file file.h.

FileName& operator+=

(

char

c

)

append a character to this file name

Definition at line 583 of file file.h.

FileName& operator+=

(

char const *

p

)

append a string to this file name

Definition at line 573 of file file.h.

bool operator<

(

std::string const &

rhs

)

const

Compare this filename's string component against.

Definition at line 561 of file file.h.

FileName& operator=

(

T const &

rhs

)

Assign this FileName from some other string source.

Definition at line 1136 of file file.h.

bool operator==

(

char const *

rhs

)

const

compare a filename to a c style string

Definition at line 1252 of file file.h.

bool operator==

(

std::string const

rhs

)

const

compare a filename to a string

Definition at line 1238 of file file.h.

bool operator==

(

FileName const

rhs

)

const

Compare two filenames.

Definition at line 1224 of file file.h.

char& operator[]

(

size_t

i

)

Get a ref to the character at a specified offset from the start of the string.

Definition at line 549 of file file.h.

char operator[]

(

size_t

i

)

const

Get the character at a specified offset from the start of the string.

Definition at line 546 of file file.h.

std::string read_file	(	Container &	container,
		size_t *	line_count_ptr = 0
	)

Read a whole file into a container of std::string's. Return any error text as a std::string as well. If the return string is empty then no errors have occurred.

Parameters:

	container	can be any sequence container that should holds lines of text from the input file (as std::string)
	line_count_ptr	is a pointer to the location where the count of read lines will be stored.

Returns:

errorString is a string describing any problems you might have encountered.

This function differs from the FileName::slurp() method in that slurp reads the entire file into a single giant array of characters. This function reads it into a any container of std::strings which you define. Note that on large files, vector<std::string> gives you O(N) inserts whereast list<std::string> gives you O(1) inserts. A skiprope<std::string> would give you O(ln(N)) inserts as well as O(ln(N)) array indexing -- unlike the list which has none what so ever.

Definition at line 990 of file file.h.

string read_lines	(	FileName::accumulate_lines &	accum,
		size_t *	line_count_ptr = 0,
		bool	removeCR = false
	)

This function lets you read lines from the file whose name contained in this filename very quickly. You probably want to use the FileName::read_file function below instead of calling this function. It simplifies the interface significantly.

Parameters:

	accum	is an container-wrapper that will hold the input data.
	line_count_ptr	is an optional pointer to a size_t holding the count of read lines.
	removeCR	is an optional boolean that tells the function to remove a trailing \r character, i

Returns:

a string containing the strerror() contents or "" if no errors.

You must create a FilenName::accumulate_lines object to serve as an interface to the container into which you are storing the read lines. The lines will be read in binary mode. The line separator, \n, will not be included in the strings returned -- nor will any single trailing \r (On unix you must set the removeCR flag to get the trailing \r removed. On windows, this is neither necessary nor helpful.)

This function returns a std::string contain any error message that might have occurred. If the return value is empty, then no error occurred.

Do not attempt to use the push_back method to do anything but accumulate lines. The read_lines algorithm handles very long lines, but it has a fixed size internal buffer. As the data is read from the file it is stored in this internal buffer. When a line exceeds the length of this buffer, partial lines will be pushed into the the container. The back() function will subsequently be called to get access to the most recently pushed partial line so that the partial line can be completed using the std::string::append method.

See the body of FileName::read() below for an example of using read_lines().

Definition at line 1991 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

FileName readlink

(

int *

returnedMode = 0

)

const

Assume that this filename refers to a symbolic link file and attempt to read through the link to get the name of the thing it points to. If the optional mode pointer is passed in also read the symbolic link's file mode and return it in *returnMode; Note that normally the FileMode of a symbolic link is a mix of the attributes of the link itself and the thing it points to. The mix works like this:

• the link bit in the FileMode::mode gets populated with one if the file is actually a symbolic link.

• The other bits in the mode get populated with the mode of the target of the link.

If the does not exist or is not a symbolic link, then the returned value is empty string. If the file is a symbolic link then an absolute path will be returned.

Definition at line 2471 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool remove

(

)

const

Remove the file named by this FileName.

Returns:

true on error.

Definition at line 1621 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool rename

(

FileName const &

destination

)

const

Rename the file whose name is specified '*this' into a new file whose name is specified in destination.

Parameters:

destination

A FileName containing the new name for the file.

Returns:

true if an error occurred

Definition at line 1753 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool rmdir

(

)

const

Remove the directory named by this filename.

Returns:

true if an error occurred

Definition at line 1633 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

string shorten

(

int

max_chars

)

const

Produce a string which is a shortened version of the filename by deleting excess characters and inserting an elipses in the middle to signify missing characters. The name will not refer to a real file (unless by accident).

Shorten a filename for display purposes only.

Definition at line 1948 of file file.cxx.

Here is the caller graph for this function:

size_t size

(

)

const

Get length of string.

Definition at line 540 of file file.h.

Here is the caller graph for this function:

size_t slurp

(

std::list< std::string > *

lines

)

const

Read the whole file (binary read) into a list of strings return the number of lines read. This is the fastest way to read a file into a bunch of strings.

Ok, so the name is stupid -- what would you have called it?

Definition at line 1798 of file file.cxx.

Here is the call graph for this function:

void slurp

(

FileContents *

f

)

const

Read whole file (binary read) into a FileContents object and set its error method correctly.

Definition at line 1327 of file file.cxx.

Here is the caller graph for this function:

rep_t substr	(	size_t	s,
		size_t	l
	)			const

Get a substring given a start ofset a number of characters.

Definition at line 567 of file file.h.

Here is the caller graph for this function:

std::auto_ptr< FileName::Tree > tree

(

bool

only_dirs = false

)

const

Get the subdirectory tree starting with this filename. If this filename refers to a normal file, then tree will have only one node. If this does not refer to a valid file, one node will be returned but the 'status' will indicate that it is not a good file. If this FileName is a directory, then the sub-directory tree will be returned. If any node's status is not avaialable, its status will indicate that.

Definition at line 2230 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

std::auto_ptr< FileName::Tree > tree_helper	(	std::string const &	path,
		bool	only_dirs = false,
		int	depth = 0
	)			const [private]

used by tree() to recurse through directory hierarchies

Definition at line 2152 of file file.cxx.

Here is the call graph for this function:

Here is the caller graph for this function:

bool write	(	char const *	begin,
		char const *	end,
		bool	binary_mode = true
	)

Open the file whose name is contained in this FileName object and write the data found between begin and end to the file in either ascii or binary mode depending on the binary_mode flag. On unix, this flag is ignored. The file will be created with default umask permission.

Parameters:

	begin	is the pointer to the beginning of the data to be written.
	end	is the end of the buffer to be written
	binary_mode	(windows only) controls the io mode.

Definition at line 2129 of file file.cxx.

Here is the call graph for this function:

bool write	(	std::string const &	file_contents,
		bool	binary_mode = true
	)

Write a string to a newly create file whose name is the contained in this filename. If the file previously existed, it will be deleted then recreated.

Parameters:

	file_contents	is the content of the newly created file
	binary_mode	is a flag indicating that binary mode will be used to write the file (Windows only).

Returns:

true if an error occurred -- see errno.

The file will be created using default umask protections and will be written be written as either ascii or binary base on the binary_mode flag. On unix this flag is ignored.

Definition at line 2119 of file file.cxx.

Here is the caller graph for this function:

---

Friends And Related Function Documentation

std::string operator+	(	char const *	lhs,
		FileName const &	rhs
	)			[friend]

global free function to concatenate c style strings and filenames producing std::strings'

Definition at line 1153 of file file.h.

std::string operator+	(	std::string const &	lhs,
		FileName const &	rhs
	)			[friend]

global free function to concatenate strings and filenames, producing std::strings

Definition at line 1146 of file file.h.

bool operator==	(	char const *	lhs,
		FileName const &	rhs
	)			[friend]

global free function to compare a c style string to a filename

Definition at line 1281 of file file.h.

bool operator==	(	std::string const &	lhs,
		FileName const &	rhs
	)			[friend]

global free function to compare a std::string to a filename

Definition at line 1267 of file file.h.

---

Member Data Documentation

rep_t impl_ [private]

The string that is the file name.

Definition at line 532 of file file.h.

char PATH_separator = ':' [static]

Either : or ; depending on the os This variable defines what character separates components of the PATH environment variable.

Definition at line 1050 of file file.h.

---

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

• include/cxxtls/file.h
• lib/file.cxx