nstring Class Reference

#include <nstring.h>

Public Member Functions
	~nstring ()
	nstring ()
	nstring (const char *arg)
	nstring (const char *data, size_t len)
	nstring (string_ty *arg)
	nstring (const nstring &arg)
nstring &	operator= (const nstring &arg)
unsigned char	back (void) const
nstring	basename (const nstring &suffix="") const
nstring	capitalize (void) const
	convert to title case
nstring	catenate (const nstring &arg) const
	join two strings together
nstring	cat_three (const nstring &str2, const nstring &str3) const
	joing strings together
void	clear (void)
const char *	c_str (void) const
nstring	dirname (void) const
nstring	downcase (void) const
	convert to lower case
bool	empty (void) const
bool	ends_with (const nstring &suffix) const
bool	ends_with_nocase (const nstring &suffix) const
bool	equal (const nstring &arg) const
	test string equality
nstring	field (char sep, int nth) const
	extract a field
nstring	first_dirname (void) const
unsigned char	front (void) const
nstring	get_extension (void) const
str_hash_ty	get_hash (void) const
string_ty *	get_ref (void) const
string_ty *	get_ref_copy (void) const
bool	gmatch (const char *pattern) const
bool	gmatch (const nstring &pattern) const
bool	gmatch (const nstring_list &pattern) const
nstring	html_quote (bool para=false) const
nstring	html_unquote (void) const
nstring	identifier (void) const
size_t	length (void) const
int	len_printable (int maxlen) const
nstring	operator+ (const nstring &arg) const
nstring &	operator+= (const nstring &arg)
	operator bool () const
	test a boolean
bool	operator! () const
bool	operator== (const nstring &rhs) const
bool	operator!= (const nstring &rhs) const
bool	operator< (const nstring &rhs) const
bool	operator<= (const nstring &rhs) const
bool	operator> (const nstring &rhs) const
bool	operator>= (const nstring &rhs) const
char	operator[] (size_t n) const
nstring	quote_c (void) const
	quote C meta-characters
nstring	quote_shell (void) const
	quote shell meta-characters
nstring	quote_cook (void) const
	quote Cook meta-characters
nstring	replace (const nstring &lhs, const nstring &rhs, int maximum=-1) const
size_t	size (void) const
nstring	snip (void) const
	remove excess white space
bool	starts_with (const nstring &prefix) const
nstring	substr (long start, long nbytes) const
long	to_long (void) const
nstring	trim (void) const
	remove excess white space
nstring	trim_extension (void) const
nstring	trim_first_directory (void) const
nstring	trim_lines (void) const
	remove excess white space
nstring	trim_right (void) const
nstring	upcase (void) const
	convert to upper case
nstring	url_quote (void) const
nstring	url_unquote (void) const
bool	valid (void) const
	check is valid
Static Public Member Functions
static nstring	format (const char *fmt,...)
	format text
static nstring	vformat (const char *fmt, va_list ap)
	format text
Static Private Member Functions
static string_ty *	get_empty_ref (void)
Private Attributes
string_ty *	ref

---

Detailed Description

The nstring class is used to represent a reference counted narrow string with fast equality comparison.

This is a narrow string class, using ordinary char as the internal character type. For wide strings, which use wchar_t as the internal character type, see the wstring class.

Definition at line 34 of file nstring.h.

---

Constructor & Destructor Documentation

nstring::~nstring

(

)

[inline]

The destructor.

This destructor is not virtual, do not derive from this class.

Definition at line 42 of file nstring.h.

nstring::nstring

(

)

[inline]

The default constructor.

Definition at line 51 of file nstring.h.

nstring::nstring

(

const char *

arg

)

[inline]

The constructor.

Definition at line 59 of file nstring.h.

nstring::nstring	(	const char *	data,
		size_t	len
	)		[inline]

The constructor.

Definition at line 67 of file nstring.h.

nstring::nstring

(

string_ty *

arg

)

[inline, explicit]

The constructor.

Definition at line 76 of file nstring.h.

nstring::nstring

(

const nstring &

arg

)

[inline]

The copy constructor.

Definition at line 84 of file nstring.h.

---

Member Function Documentation

unsigned char nstring::back

(

void

)

const

The back method is used to obtain the last character of the string, or NUL if the string is empty.

nstring nstring::basename

(

const nstring &

suffix = ""

)

const

The basename method is used to generate a new string from this one with any leading directory components removed. If specified, also remove a trailing suffix.

const char* nstring::c_str

(

void

)

const [inline]

The c_str method is used to obtain a pointer to the underlying C string (guaranteed to the NUL terminated).

Definition at line 190 of file nstring.h.

nstring nstring::capitalize

(

void

)

const

convert to title case

The str_capitalize function is used to create a new string where the first letter or each word of the inopuyt string are upper case, and the remaining letters in each word are lower case. (Sometimes called Title Case.)

Returns:

a pointer to a string in dynamic memory.

nstring nstring::cat_three	(	const nstring &	str2,
		const nstring &	str3
	)		const

joing strings together

The str_cat_three function is used to join three strings together to form a new string. The are joined in the order given.

Parameters:

str2	A string to be joined. Will not be modified.
str3	A string to be joined. Will not be modified.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

nstring nstring::catenate

(

const nstring &

arg

)

const [inline]

join two strings together

The str_catenate function is used to join two strings togther to form a new string. The are joined in the order given.

Parameters:

arg	A string to be joined. Will not be modified.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

Definition at line 151 of file nstring.h.

void nstring::clear

(

void

)

The clear method is used to delete to contents of the string, and replace it with the empty string/

nstring nstring::dirname

(

void

)

const

The dirname method is used to extract the directory part of a filename. If there is no directory part, "." is returned.

nstring nstring::downcase

(

void

)

const

convert to lower case

The str_downcase function is used to create a new string where the upper case characters in the input string are converted to lower case.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

bool nstring::empty

(

void

)

const [inline]

Definition at line 222 of file nstring.h.

bool nstring::ends_with

(

const nstring &

suffix

)

const

The ends_with method is ised to test whether this string ends with the given suffix.

Parameters:

suffix

The string to test for.

bool nstring::ends_with_nocase

(

const nstring &

suffix

)

const

The ends_with_nocase method is ised to test whether this string ends with the given suffix. The comparison will be case insensitive.

Parameters:

suffix

The string to test for.

bool nstring::equal

(

const nstring &

arg

)

const [inline]

test string equality

The str_equal function is used to test to see if two strings are exactly the same.

Parameters:

arg	A string to be compared. Will not be modified.

Note:

Users shall always write code as if they did not know that a string equality test is a pointer equality test.

Returns:

Non-zero if the strings are equal, zero if the strings are unequal.

Definition at line 266 of file nstring.h.

nstring nstring::field	(	char	sep,
		int	nth
	)		const

extract a field

The str_field function is used to extract the nth field, where each field is separated by the sep string.

Parameters:

sep	The string which separates each field.
nth	The number of the field to be extracted. Zero based. If too high, the emtry string is returned.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

nstring nstring::first_dirname

(

void

)

const

The first_dirname method is used to extract the first directory part of a filename. If there is no directory part, "." is returned.

static nstring nstring::format	(	const char *	fmt,
			...
	)		[static]

format text

The format function is used to create a new string by interpreting the fmt string. All formats understood by the ANSI C printf(3) are understood by this function (but probably not your favorite proprietary extension).

Parameters:

fmt	The format string to be interpreted when constructing the return value.

Returns:

a pointer to a string in dynamic memory.

unsigned char nstring::front

(

void

)

const [inline]

The front method is used to obtain the first character of the string, or NUL if the string is empty.

Definition at line 323 of file nstring.h.

static string_ty* nstring::get_empty_ref

(

void

)

[static, private]

The get_empty_ref() class method is used to get a pointer to an underlying string object of length zero.

nstring nstring::get_extension

(

void

)

const

The get_extension method is used to build a new string containing the file extension, if any, without the dot. For example, the string "a/b.c" will return "c".

str_hash_ty nstring::get_hash

(

void

)

const [inline]

The get_hash method is used to access the has value of this key. While this is an internal implementation feature, it is often extremely handy to have a pre-calculated hash value for a string, and so it is made public.

Definition at line 340 of file nstring.h.

string_ty* nstring::get_ref

(

void

)

const [inline]

The get_ref method is used to extract the reference to the underlying reference counted string object. If the ref pointer is NULL a pointer to a common empty string object is returned.

Once the sources cease using string_ty directly, this method will become private.

Definition at line 351 of file nstring.h.

string_ty* nstring::get_ref_copy

(

void

)

const [inline]

The get_ref_copy method is used to extract a copy of the reference to the underlying reference counted string object. If the ref pointer is NULL a pointer to a common empty string object is returned.

Once the sources cease using string_ty directly, this method will become private.

Definition at line 367 of file nstring.h.

bool nstring::gmatch

(

const char *

pattern

)

const

The gmatch function is used to match the string against a file globbing pattern.

Parameters:

pattern

The pattern to try against the string.

Returns:

bool; true if matches pattern, false if does not.

bool nstring::gmatch

(

const nstring &

pattern

)

const

The gmatch function is used to match the string against a file globbing pattern.

Parameters:

pattern

The pattern to try against the string.

Returns:

bool; true if matches pattern, false if does not.

bool nstring::gmatch

(

const nstring_list &

pattern

)

const

The gmatch function is used to match the string against a set of file globbing patterns.

Parameters:

pattern

The patterns to try against the string.

Returns:

bool; true if matches at least one pattern, false if does not match any pattern.

nstring nstring::html_quote

(

bool

para = false

)

const

The html_quote method is used to form a string suitable for use withing an HTML paragraph. This means that special characters and unprintable characters are replaced with &&#23;DDD; escape sequences. Some special characters are also replaced, e.g. '<' as &lt;

Parameters:

para	Whether or not to translate and as

and
, respectively. Defaults to false (no translation).

nstring nstring::html_unquote

(

void

)

const

The html_unquote method is used to form a normal string given text from an HTML paragraph. This means that &&#23;DDD; escape sequences are replaced by single bytes. Some special characters are also replaced, e.g. '<' as &lt;

Note:

unicode values (DDD > 255) are not understood.

nstring nstring::identifier

(

void

)

const

The identifier method is used to convert all non-C-identifier characters in the string to underscores. The intention is to create a valid C identifier from the string.

int nstring::len_printable

(

int

maxlen

)

const

The len_printable method may be used to determine the "printable length" of a string. This means the first maxlen characters, or up until the first newline, whichever is least.

Parameters:

maxlen

The longest desired string (0 < maxlen < INT_MAX)

Returns:

int, suitable for passing to %.*s

size_t nstring::length

(

void

)

const [inline]

Definition at line 447 of file nstring.h.

nstring::operator bool

(

)

const

test a boolean

The str_bool function is used to test the value of a string, as if it contained a number. If it doesn't contain a number, it is as if the strings was "1".

Returns:

False if the numeric value in the strings was zero, or the empty string. True if the numeric value in the string was non-zero, or the string was non-numeric.

bool nstring::operator!

(

)

const

The logical netation operator. Returns the negation of the bool() operator.

bool nstring::operator!=

(

const nstring &

rhs

)

const [inline]

The not-equal-to operator.

Parameters:

rhs	The right hans side of the comparison.

Definition at line 532 of file nstring.h.

nstring nstring::operator+

(

const nstring &

arg

)

const [inline]

Definition at line 470 of file nstring.h.

nstring& nstring::operator+=

(

const nstring &

arg

)

[inline]

Definition at line 480 of file nstring.h.

bool nstring::operator<

(

const nstring &

rhs

)

const

The less-than operator.

Parameters:

rhs	The right hans side of the comparison.

bool nstring::operator<=

(

const nstring &

rhs

)

const

The less-than-or-equal operator.

Parameters:

rhs	The right hans side of the comparison.

nstring& nstring::operator=

(

const nstring &

arg

)

[inline]

The assignment operator.

Definition at line 93 of file nstring.h.

bool nstring::operator==

(

const nstring &

rhs

)

const [inline]

The equal-to operator.

Parameters:

rhs	The right hans side of the comparison.

Definition at line 519 of file nstring.h.

bool nstring::operator>

(

const nstring &

rhs

)

const

The greater-than operator.

Parameters:

rhs	The right hans side of the comparison.

bool nstring::operator>=

(

const nstring &

rhs

)

const

The greater-than-or-equal operator.

Parameters:

rhs	The right hans side of the comparison.

char nstring::operator[]

(

size_t

n

)

const [inline]

The indexing operator is used to extract the nth character of a string. Indexes out of range will result in the NUL character being returned.

Parameters:

n	The character to extract. Zero based.

Returns:

The character requested, or NUL if the index is out of range.

Definition at line 582 of file nstring.h.

nstring nstring::quote_c

(

void

)

const

quote C meta-characters

The quote_c method is used to create a new string which quotes the C meta-characters in the input string.

nstring nstring::quote_cook

(

void

)

const

quote Cook meta-characters

The quote_cook method is used to create a new string which quotes the Cook meta-characters in the input string. If no quoting is required, none will be used.

nstring nstring::quote_shell

(

void

)

const

quote shell meta-characters

The quote_shell method is used to create a new string which quotes the shell meta-characters in the input string.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

nstring nstring::replace	(	const nstring &	lhs,
		const nstring &	rhs,
		int	maximum = -1
	)		const

The replace method may be used to alter a string by replacing one constant substring with another.

Note:

The replacement is not done in situ. The original string is unaltered.

Parameters:

lhs	The substring to look for.
rhs	The substring to replace lhs if found.
maximum	The maximum number of times to perform the replacement. Defaults to "infinity".

Returns:

A new string with the replacements made.

size_t nstring::size

(

void

)

const [inline]

Definition at line 650 of file nstring.h.

nstring nstring::snip

(

void

)

const

remove excess white space

The snip method is used to remove white space from the beginning and end of the string. Interior white space is left unchanged.

Returns:

another string

bool nstring::starts_with

(

const nstring &

prefix

)

const

The starts_with method is ised to test whether this string starts with the given prefix.

Parameters:

prefix

The string to test for.

nstring nstring::substr	(	long	start,
		long	nbytes
	)		const

The substr method may be used to extract a substring from this string. (Named for compatibility with std::string.)

Parameters:

start	The offset into the string where the substring starts. If negative, is measured from the end.
nbytes	The number of bytes to extract, if that many available. If negative, measured to the left (text not reversed).

Returns:

a string, note that it could be less than nbytes long.

long nstring::to_long

(

void

)

const

The to_long method attempts to turn a string into a long value. It returns zero on failure. The radix is always 10.

nstring nstring::trim

(

void

)

const

remove excess white space

The trim method is used to remove white space from the beginning and end of the string, and replace all other runs of one or more white space characters with a single space.

Returns:

another string

nstring nstring::trim_extension

(

void

)

const

The trim_extension method is used to build a new string without the file extension. For example, the string "a/b.c" will return "a/b".

nstring nstring::trim_first_directory

(

void

)

const

The trim_first_directory method may be used to trim the left-most directory from a path. If there is no slash, the string is returned with no change.

nstring nstring::trim_lines

(

void

)

const

remove excess white space

The trim_lines method is used to remove white space from the beginning and end of lines within the string, and replace all other runs of one or more white space characters with a single space.

Returns:

another string

nstring nstring::trim_right

(

void

)

const

The trim_right method is used to trim while space from the right hand side (the end) of the given string.

nstring nstring::upcase

(

void

)

const

convert to upper case

The str_upcase function is used to create a new string where the lower case characters in the input string are converted to upper case.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

nstring nstring::url_quote

(

void

)

const

The url_quote mwthod is used to form a string suitable for use within an HTML href="" string, or similar. This means that special characters and unprintable characters are replaced with NN escape sequences.

nstring nstring::url_unquote

(

void

)

const

The url_unquote method is used to form a normal string given an HTML href="" string, or similar. This means that NN escape sequences are replaced with single bytes.

bool nstring::valid

(

void

)

const [inline]

check is valid

The str_validate function is used to confirm that the given string pointer, str, points to a valid string. Usually used for debugging, often in assert()s.

Returns:

Non-zero if valid, zero if invalid.

Definition at line 793 of file nstring.h.

static nstring nstring::vformat	(	const char *	fmt,
		va_list	ap
	)		[static]

format text

The str_vformat function is used to create a new string by interpreting the fmt string. All formats understood by the ANSI C printf(3) are understood by this function (but probably not your favorite proprietary extension). In addition the 'S' specifier expects a string_ty * argument.

Parameters:

fmt	The format string to be interpreted when constructing the return value.
ap	Where to obtain additional arguments required by the fmt string.

Returns:

a pointer to a string in dynamic memory. Use str_free() when finished with. The contents of the structure pointed to shall not be altered.

---

Field Documentation

string_ty* nstring::ref [private]

The ref instance variable is used to remember the location of the object common to all of the references. The is never the NULL pointer.

Definition at line 833 of file nstring.h.

---

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

• /home/archives/aegis/branch.4/branch.25/delta28933.505/common/nstring.h