Wrapper for the libKJB type Word_list (useful for globs). More...

#include <l_word_list.h>

Classes
class	const_iterator
	iterator class used to traverse and read the list More...

Public Member Functions
	Word_list (const char pattern, int(filter)(const char *)=kjb_c::is_file)
	Construct by searching for a Glob pattern, seeking files. More...

	Word_list (const std::string &pattern, int(filter)(const char )=kjb_c::is_file)
	Construct by searching for a Glob pattern, seeking files. More...

	Word_list (int num_words=0)
	take non-negative word-count; generate that many empty entries. More...

	Word_list (int argc, const char const argv)
	construct a word list from an "argv" style array of arguments. More...

	Word_list (const Word_list &that)
	copy ctor (slow) creates a deep copy of an existing word list. More...

Word_list &	operator= (const Word_list &that)
	assignment operator deep-copies contents of given list. More...

size_t	size () const
	Number of entries in the word list (could be empty, though). More...

int	count_strings () const
	return the number of non-empty entries in the list More...

const kjb_c::Word_list *	c_ptr () const
	Return the underlying C representation (as const) More...

size_t	match (const std::string &word) const
	Searches the word list for an entry, looking for an exact match. More...

const char *	operator[] (size_t index) const
	Access an entry of the word list; this performs range checking. More...

void	append (const std::string &word)
	insert a given string into the list (maybe increasing its size). More...

void	trim_empty_entries_at_tail ()
	remove all empty entries from back (only) of the list. More...

	operator std::vector< std::string > () const
	Convert the word list into a STL vector of STL strings. More...

Word_list	operator+ (const Word_list &that) const
	concatenate two word lists More...

	~Word_list ()
	dtor releases memory of underlying C structure More...

const_iterator	begin () const
	synonym for cbegin More...

const_iterator	end () const
	synonym for cend More...

const_iterator	cbegin () const
	generate, return const_iterator to front of list More...

const_iterator	cend () const
	generate, return const_iterator pointing one-past-last entry More...

Detailed Description

Wrapper for the libKJB type Word_list (useful for globs).

This class is useful mostly because of the glob-related constructors. If you don't need globs, then consider using vector<string> instead. This container does not offer any deletion operations, at least currently. But it does at least offer input iterators.

How to use iterators

When you dereference a valid const_iterator generated by this class, the result is like a const char*. For example, the following shows how to produce a very basic directory listing of regular filenames in the current working directory:

Word_list wl("*");
std::copy(wl.begin(), wl.end(),
          std::ostream_iterator<const char*>(std::cout, " "));

Glob

A glob(7) is what they call Unix filename pattern-matching expressions, such as "*.cpp" or "/tmp/????.pid" or the like. We wrap function kjb_c::kjb_glob in some of the ctors for this class – please see its man page.

Constructor & Destructor Documentation

kjb::Word_list::Word_list	(	const char *	pattern,
		int()(const char )	filter = `kjb_c::is_file`
	)

inline

Construct by searching for a Glob pattern, seeking files.

Parameters

[in]	pattern	A string containing a filename "glob" pattern
[in]	filter	Optional parameter specifying the kind of directory entry wanted: defaults to kjb_c::is_file, the common choice, but also can be kjb_c::is_directory or others.

Exceptions

kjb::Result_error	if the file globbing fails (see note).
kjb::KJB_error	if memory allocation fails.

See Also: Glob

Note: Please see documentation for kjb_c::kjb_glob() for behavior. The resulting Word_list will indicate, via size(), the number of matches for the glob pattern. Clearly the number of matches could be zero, which is not regarded as an error. No matter the size, the resulting word list will lack any "empty" entries. All entries (if any) will point to a null-terminated string.

kjb::Word_list::Word_list	(	const std::string &	pattern,
		int()(const char )	filter = `kjb_c::is_file`
	)

inline

Construct by searching for a Glob pattern, seeking files.

Parameters

[in]	pattern	A string containing a filename "glob" pattern
[in]	filter	Optional parameter specifying the kind of directory entry wanted: defaults to kjb_c::is_file, the common choice, but also can be kjb_c::is_directory or others. Please see the documentation for the other ctor for further discussion.

kjb::Word_list::Word_list ( int num_words = 0 )

inline

take non-negative word-count; generate that many empty entries.

Exceptions

KJB_error if anything (such as memory allocation) fails.

kjb::Word_list::Word_list	(	int	argc,
		const char const	argv
	)

inline

construct a word list from an "argv" style array of arguments.

kjb::Word_list::Word_list ( const Word_list & that )

inline

copy ctor (slow) creates a deep copy of an existing word list.

Exceptions

KJB_error if anything (such as memory allocation) fails.

kjb::Word_list::~Word_list ( )

inline

dtor releases memory of underlying C structure

Member Function Documentation

void kjb::Word_list::append ( const std::string & word )

inline

insert a given string into the list (maybe increasing its size).

If the list contains empty entries, the given word will go into the first one encountered. Otherwise the list is reallocated and grown, and the given word goes in the first newly-created entry.

Exceptions

KJB_error if anything (such as memory allocation) fails.

Warning: This operation can alter the size() of the object by an unspecified amount (not a plus-one increment, in general).

const_iterator kjb::Word_list::begin ( ) const

inline

synonym for cbegin

const kjb_c::Word_list* kjb::Word_list::c_ptr ( ) const

inline

Return the underlying C representation (as const)

const_iterator kjb::Word_list::cbegin ( ) const

inline

generate, return const_iterator to front of list

const_iterator kjb::Word_list::cend ( ) const

inline

generate, return const_iterator pointing one-past-last entry

int kjb::Word_list::count_strings ( ) const

inline

return the number of non-empty entries in the list

const_iterator kjb::Word_list::end ( ) const

inline

synonym for cend

size_t kjb::Word_list::match ( const std::string & word ) const

inline

Searches the word list for an entry, looking for an exact match.

Returns: If found, returns the index of the entry. Otherwise, it returns size().

Warning: Please test for the not-found possibility!; This does NOT follow the same API as kjb_c::search_word_list.; This is a linear-time search, i.e., slow.

kjb::Word_list::operator std::vector< std::string > ( ) const

inline

Convert the word list into a STL vector of STL strings.

Word_list kjb::Word_list::operator+ ( const Word_list & that ) const

inline

concatenate two word lists

Word_list& kjb::Word_list::operator= ( const Word_list & that )

inline

assignment operator deep-copies contents of given list.

Exceptions

KJB_error if anything (such as memory allocation) fails.

const char* kjb::Word_list::operator[] ( size_t index ) const

inline

Access an entry of the word list; this performs range checking.

Warning: The object can contain empty entries: the result might be NULL.

size_t kjb::Word_list::size ( ) const

inline

Number of entries in the word list (could be empty, though).

A word list entry might point to a null-terminated string, or it might be empty, i.e., (char*)NULL. This counts all the entries, empty or not.

Note: The append operation can alter the size by an unspecified amount.

void kjb::Word_list::trim_empty_entries_at_tail ( )

inline

remove all empty entries from back (only) of the list.

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

/work/kobus/src/lib/l_cpp/l_word_list.h

Classes

Public Member Functions

Detailed Description

How to use iterators

Glob

Constructor & Destructor Documentation

Member Function Documentation