Automatically reference-counted string container. More...

#include <String.h>

Classes
struct	Sort
	Sort an Array of Strings. More...

Public Member Functions
	String (void)
	Construct an empty string. More...

	String (const String &operand)
	Copy constructor. More...

	String (const FESTRING_I8 *operand)
	Construct using a signed byte buffer. More...

	String (const FESTRING_U8 *operand)
	Construct using a unsigned byte buffer. More...

	String (int operand)
	allow init as 0 in templates More...

String &	operator= (const String &operand)
	Compare to another String. More...

String &	operator= (const FESTRING_I8 *operand)
	Compare to a signed byte buffer (using 8-bit). More...

String &	operator= (const FESTRING_U8 *operand)
	Compare to an unsigned byte buffer (using 8-bit). More...

BWORD	equals (const String &operand) const
	checks if the string is equivalent More...

I32	compare (const String &operand) const
	Standard string compare: returns -1, 0, or 1 if the string is alphabetically less than, equal, or greater than the operand. More...

BWORD	operator< (const String &operand) const

String	pathname (void) const
	Return the substring preceding the last '/'. More...

String	basename (void) const
	Return the substring following the last '/'. More...

String	prechop (const String &prefix) const
	Return the substring after the prefix. More...

String	prechop (I32 count) const
	Return the substring without trailing characters. More...

String	chop (const String &suffix) const
	Return the substring before the suffix. More...

String	chop (I32 count) const
	Return the substring without trailing characters. More...

BWORD	contains (String find) const
	Returns TRUE if string contains the substring. More...

String	substitute (String find, String replace) const
	Return a string with replaced substrings. More...

String	substituteEnv (std::map< String, String > &a_rMap, BWORD a_alsoUseEnv=FALSE, BWORD a_throwMissing=FALSE) const
	Return a string with enviroment substitution. More...

String	substituteEnv (void)

String	stripComments (String a_start="/", String a_end="/", BWORD a_keepStart=FALSE, BWORD a_keepEnd=FALSE)
	Return a string with sections removed. More...

BWORD	dotMatch (const String &operand) const
	Compares to another string assuming the given string is a dot-delimited ordered list containing optional substrings. More...

void	forceUppercase (void)
	Force all applicable characters to upper case. More...

void	forceLowercase (void)
	Force all applicable characters to lower case. More...

U32	length (void) const
	Return the number of represented characters, but not necessarily the size of any buffer. More...

BWORD	empty (void) const
	Returns true if the contents have zero length. More...

String &	sPrintf (const char *fmt,...)
	Populate the string in the manner of sprintf(). More...

String &	catf (const char *fmt,...)
	Populate the string as with sPrintf(), but by concatenating the results to the existing string. More...

String &	cat (const char *operand)
	Append the current String with the given text. More...

String &	cat (const String &operand)
	Append the current String with the given String. More...

String &	cat (std::list< String > &strList, String sep="")
	Concatenate the strings in a list. More...

void	resize (U32 size, char c=' ')
	Add or remove characters to set the string length. More...

String	maybeQuote (String beginQuote, String endQuote) const
	Return the string, adding quotes if it contains a likely delimiter. More...

String	maybeQuote (String quote="\) const

String	maybeUnQuote (String beginQuote, String endQuote) const
	Return the string, removing outer quotes if they exist. More...

String	maybeUnQuote (String quote="\) const

String	parse (String quote="\, String delimiters=" \\", BWORD eachDelimiter=FALSE)

I32	lines (void) const

String	line (I32 a_lineNumber) const

String &	vsPrintf (const char *fmt, va_list ap, int &size)
	Populate using variable arg format. More...

const FESTRING_I8 *	c_str (void) const
	Return the contents of the 8-bit buffer cast as signed bytes. More...

const FESTRING_U8 *	rawU8 (void) const
	Return the contents of the 8-bit buffer cast as unsigned bytes. More...

void	output (std::ostream &ostrm) const

void	input (std::istream &istrm)

String &	operator+= (const String &operand)

int	integer (void) const

Real	real (void) const

bool	match (const String a_pattern) const

bool	search (const String a_pattern) const

String	replace (const String a_pattern, const String a_replacement) const

String	convertGlobToRegex (void) const

U64	computeFowlerNollVo1 (void) const
	Compute Fowler-Noll-Vo hash function (64-bit FNV-1) More...

Static Public Member Functions
static String	join (const String &a_sep, std::list< String > &a_list)

static String	join (const String &a_sep, const String &a_1, const String &a_2)

static String	join (const String &a_sep, const String &a_1, const String &a_2, const String &a_3)

Private Member Functions
FESTRING_U8 *	buffer (void)

void	create (const FESTRING_I8 *operand)

void	init (void)

void	forceCase (BWORD upper)

Rep *	newRep (void)

void	deleteRep (void)

Private Attributes
FESTRING_U8	m_pLocal [FESTRING_LOCALSIZE]

I32	m_length

Rep *	m_pRep

Detailed Description

Automatically reference-counted string container.

Designed to behave as a native type, like float or int. All allocation worries are completely hidden.

To assign a string just use simple assignments.

String name("me");
name="you";
String id=name;

You can compare strings in a boolean or lexical fashion.

if(name!="Bob" && name.compare("M")<0)

...

To print a string in printf fashion, use c_str().

printf("%s\n",name.c_str());

Although the String encoding may start like a (char*) byte-wise, you should always use the c_str() method in conjunction with C-style string operations, especially variable argument functions like *printf.

A String object is 32 bytes. Strings shorter than FESTRING_LOCALSIZE (currently 16), including terminator, are stored in a local buffer and compared quickly as two 64-bit words or as a single 128-bit word, depending on the compiler. Longer strings are allocated and can be shared in assignment.

We would prefer to derive fe::String from std::string, just adding fe methods to the std::string buffer handling. But, as of Feb 2021, on gcc 8.3.0, same size small string operator==() is 3 times faster with fe::String than std::string. Also, std::string is forbidden from being ref counted, so passing std::string as an argument is a deep copy every time. You don't don't need a full mutex to protect the ref count, but a swap increment appears to take about 4ns (in 2021). The alternative of a deep copy on every string copy can be a little less, or a much much more, depending on the string length. But, for the sake of conformance, this task will likely happen eventually.

As a tight core class, String doesn't carry virtual functions.

Note: Based on Coral GPL_String; Reference: Stroustrup C++ Ref Man, 2nd ed., pg. 248; operator cast to (char*) intentionally omitted

Constructor & Destructor Documentation

◆ String() [1/5]

fe::String::String ( void )

inline

Construct an empty string.

Referenced by chop(), and prechop().

◆ String() [2/5]

fe::String::String ( const String & operand )

inline

Copy constructor.

◆ String() [3/5]

fe::String::String ( const FESTRING_I8 * operand )

inline

Construct using a signed byte buffer.

◆ String() [4/5]

fe::String::String ( const FESTRING_U8 * operand )

inline

Construct using a unsigned byte buffer.

◆ String() [5/5]

fe::String::String ( int operand )

inline

allow init as 0 in templates

Member Function Documentation

◆ basename()

String fe::String::basename ( void ) const

Return the substring following the last '/'.

If there is no '/', the entire text is returned.

Referenced by fe::Library::setLoader().

◆ c_str()

const FESTRING_I8* fe::String::c_str ( void ) const

inline

◆ cat() [1/3]

String & fe::String::cat ( const char * operand )

Append the current String with the given text.

References c_str(), and sPrintf().

Referenced by cat(), fe::Matrix< 3, 4, T >::copyTranslation(), fe::operator!=(), fe::Matrix< 3, 4, Real >::print(), fe::ext::SparseMatrix< F64 >::print(), and fe::Vector< 4, t_moa_real >::print().

◆ cat() [2/3]

String & fe::String::cat ( const String & operand )

inline

Append the current String with the given String.

References c_str().

◆ cat() [3/3]

String & fe::String::cat	(	std::list< String > &	strList,
		String	sep = `""`
	)

Concatenate the strings in a list.

References c_str(), and cat().

◆ catf()

String & fe::String::catf	(	const char *	fmt,
			...
	)

Populate the string as with sPrintf(), but by concatenating the results to the existing string.

References c_str(), sPrintf(), and vsPrintf().

Referenced by fe::Matrix< 3, 4, T >::copyTranslation(), fe::Matrix< 3, 4, Real >::print(), and fe::ext::SparseMatrix< F64 >::print().

◆ chop() [1/2]

String fe::String::chop ( const String & suffix ) const

Return the substring before the suffix.

If the string doesn't end with the suffix, the original text is returned.

Referenced by fe::Library::setLoader().

◆ chop() [2/2]

String fe::String::chop ( I32 count ) const

Return the substring without trailing characters.

This version does not care what the characters are

References length(), and String().

◆ compare()

I32 fe::String::compare ( const String & operand ) const

inline

Standard string compare: returns -1, 0, or 1 if the string is alphabetically less than, equal, or greater than the operand.

◆ computeFowlerNollVo1()

U64 fe::String::computeFowlerNollVo1 ( void ) const

Compute Fowler-Noll-Vo hash function (64-bit FNV-1)

References length(), and rawU8().

◆ contains()

BWORD fe::String::contains ( String find ) const

Returns TRUE if string contains the substring.

References c_str().

Referenced by fe::ext::SurfaceAccessibleHoudini::accessor().

◆ dotMatch()

BWORD fe::String::dotMatch ( const String & operand ) const

Compares to another string assuming the given string is a dot-delimited ordered list containing optional substrings.

Returns true if strings are exactly the same, or if they match only up to the length of the operand and the operand's terminating zero matches a period.

References c_str(), and length().

◆ empty()

BWORD fe::String::empty ( void ) const

inline

Returns true if the contents have zero length.

Referenced by fe::ext::ConnectedCatalog::configure(), fe::ext::GuidePostNetHost::connect(), fe::System::createParentDirectories(), fe::ext::SurfaceAccessibleBase::discardPattern(), fe::ext::MOAViewer::getDefaultBgColor(), fe::ext::SockAddr::getIp4Address(), fe::System::getVerbose(), and fe::ext::ConnectedCatalog::postSet().

◆ equals()

BWORD fe::String::equals ( const String & operand ) const

inline

checks if the string is equivalent

Referenced by fe::operator!=(), and fe::operator==().

◆ forceLowercase()

void fe::String::forceLowercase ( void )

inline

Force all applicable characters to lower case.

◆ forceUppercase()

void fe::String::forceUppercase ( void )

inline

Force all applicable characters to upper case.

◆ length()

U32 fe::String::length ( void ) const

inline

Return the number of represented characters, but not necessarily the size of any buffer.

Referenced by fe::BruteScan::charCount(), chop(), computeFowlerNollVo1(), dotMatch(), fe::ext::ImageIL::interpretSelect(), fe::ext::ImageOIIO::interpretSelect(), fe::System::localTime(), maybeUnQuote(), and prechop().

◆ maybeQuote()

String fe::String::maybeQuote	(	String	beginQuote,
		String	endQuote
	)		const

Return the string, adding quotes if it contains a likely delimiter.

References c_str().

◆ maybeUnQuote()

String fe::String::maybeUnQuote	(	String	beginQuote,
		String	endQuote
	)		const

Return the string, removing outer quotes if they exist.

References c_str(), and length().

◆ operator=() [1/3]

String & fe::String::operator= ( const String & operand )

inline

Compare to another String.

Referenced by output().

◆ operator=() [2/3]

String& fe::String::operator= ( const FESTRING_I8 * operand )

inline

Compare to a signed byte buffer (using 8-bit).

◆ operator=() [3/3]

String & fe::String::operator= ( const FESTRING_U8 * operand )

inline

Compare to an unsigned byte buffer (using 8-bit).

◆ output()

void fe::String::output ( std::ostream & ostrm ) const

Todo:: : string serialization currently hacked in.

only works for 8bit and does too much copying

References c_str(), and operator=().

◆ pathname()

String fe::String::pathname ( void ) const

Return the substring preceding the last '/'.

If there is no '/', no text is returned.

Referenced by fe::System::getExePath().

◆ prechop() [1/2]

String fe::String::prechop ( const String & prefix ) const

Return the substring after the prefix.

If the string doesn't begin with the prefix, the original text is returned.

Referenced by fe::Library::setLoader().

◆ prechop() [2/2]

String fe::String::prechop ( I32 count ) const

Return the substring without trailing characters.

This version does not care what the characters are

References length(), and String().

◆ rawU8()

const FESTRING_U8* fe::String::rawU8 ( void ) const

inline

Return the contents of the 8-bit buffer cast as unsigned bytes.

Referenced by computeFowlerNollVo1().

◆ resize()

void fe::String::resize	(	U32	size,
		char	c = `' '`
	)

Add or remove characters to set the string length.

If expanded, the given character is used to pad the string.

◆ sPrintf()

String & fe::String::sPrintf	(	const char *	fmt,
			...
	)

Populate the string in the manner of sprintf().

References vsPrintf().

Referenced by cat(), catf(), fe::ext::SplatterSystem::image(), fe::ext::GuidePostNetHost::listSpaces(), fe::System::localTime(), fe::operator!=(), fe::Vector< 4, t_moa_real >::print(), fe::Quaternion< Real >::print(), fe::ext::CameraEditable::rasterSpace(), and fe::Profiler::report().

◆ stripComments()

String fe::String::stripComments	(	String	a_start = `"/*"`,
		String	a_end = `"*/"`,
		BWORD	a_keepStart = `FALSE`,
		BWORD	a_keepEnd = `FALSE`
	)

Return a string with sections removed.

Each substring beginning with the given start up to the given end is removed.

If either of the keep options is on, the associated delimiting string is retained.

References c_str().

◆ substitute()

String fe::String::substitute	(	String	find,
		String	replace
	)		const

Return a string with replaced substrings.

References c_str().

◆ substituteEnv()

String fe::String::substituteEnv	(	std::map< String, String > &	a_rMap,
		BWORD	a_alsoUseEnv = `FALSE`,
		BWORD	a_throwMissing = `FALSE`
	)		const

Return a string with enviroment substitution.

Replace substrings like $VARIABLE and ${VARIABLE} with environment variables and or a map.

Without arguments, only environment variables are used for substitution.

A map can be provided for non-environment variables. In that case, the environment variable can optionally also be checked when a variable is not in the map.

If set to throw missing, a exception is thrown is a variable is found that can't be resolved.

◆ vsPrintf()

String & fe::String::vsPrintf	(	const char *	fmt,
		va_list	ap,
		int &	size
	)

Populate using variable arg format.

Referenced by catf(), and sPrintf().

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

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ String() [1/5]

◆ String() [2/5]

◆ String() [3/5]

◆ String() [4/5]

◆ String() [5/5]

Member Function Documentation

◆ basename()

◆ c_str()

◆ cat() [1/3]

◆ cat() [2/3]

◆ cat() [3/3]

◆ catf()

◆ chop() [1/2]

◆ chop() [2/2]

◆ compare()

◆ computeFowlerNollVo1()

◆ contains()

◆ dotMatch()

◆ empty()

◆ equals()

◆ forceLowercase()

◆ forceUppercase()

◆ length()

◆ maybeQuote()

◆ maybeUnQuote()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ output()

◆ pathname()

◆ prechop() [1/2]

◆ prechop() [2/2]

◆ rawU8()

◆ resize()

◆ sPrintf()

◆ stripComments()

◆ substitute()

◆ substituteEnv()

◆ vsPrintf()