Public API Reference

iString Struct Reference
[Utilities]

This is a SCF-compatible interface for csString. More...

#include <iutil/string.h>

Inheritance diagram for iString:

[legend]List of all members.

Public Member Functions
virtual void	Append (const iString *Str, size_t Count=(size_t)-1)=0
	Append a string to this one.
virtual void	Append (const char *Str, size_t Count=(size_t)-1)=0
	Append a null-terminated C-string to this one.
virtual void	Clear ()=0
	Clear the string (so that it contains only a null terminator).
virtual csRef< iString >	Clone () const =0
	Get a copy of this string.
virtual bool	Compare (const iString *Str) const =0
	Check if another string is equal to this one.
virtual bool	CompareNoCase (const iString *Str) const =0
	Check if another string is equal to this one.
virtual void	Downcase ()=0
	Convert string to lowercase.
virtual void	Empty ()=0
	Clear the string (so that it contains only a null terminator).
virtual size_t	Find (const char *search, size_t pos=0) const =0
	Find the first occurrence of search in this string starting at pos.
virtual size_t	FindFirst (const char c, size_t p=(size_t)-1) const =0
	Find the first occurrence of a character in the string.
virtual size_t	FindLast (const char c, size_t p=(size_t)-1) const =0
	Find the last occurrence of a character in the string.
virtual void	Format (const char *format,...)=0
	Format this string using sprintf()-style formatting directives.
virtual void	FormatV (const char *format, va_list args)=0
	Format this string using sprintf() formatting directives in a va_list.
virtual char	GetAt (size_t n) const =0
	Get the n'th character.
virtual size_t	GetCapacity () const =0
	Return the current capacity.
virtual char *	GetData ()=0
	Get a pointer to the null-terminated character array.
virtual char const *	GetData () const =0
	Get a pointer to the null-terminated character array.
virtual size_t	GetGrowsBy () const =0
	Return the number of bytes by which the string grows.
virtual void	Insert (size_t Pos, iString const *Str)=0
	Insert another string into this one.
virtual bool	IsEmpty () const =0
	Check if string is empty.
virtual size_t	Length () const =0
	Query string length.
virtual	operator char const * () const =0
	Get a pointer to the null-terminated character array.
virtual bool	operator!= (const iString &Str) const =0
	Check if another string is not equal to this one.
virtual csRef< iString >	operator+ (const iString &iStr) const =0
	Concatenate two strings and return a third one.
virtual void	operator+= (const char *iStr)=0
	Append a null-terminated C-string to this string.
virtual void	operator+= (const iString &iStr)=0
	Append another string to this one.
virtual bool	operator== (const iString &Str) const =0
	Check if another string is equal to this one.
virtual char	operator[] (size_t n) const =0
	Get n'th character.
virtual char &	operator[] (size_t n)=0
	Get a modifiable reference to n'th character.
virtual void	Overwrite (size_t Pos, iString const *Str)=0
	Overlay another string onto a part of this string.
virtual void	Reclaim ()=0
	Set string buffer capacity to hold exactly the current content.
virtual void	Replace (const char *str, size_t count=(size_t)-1)=0
	Replace contents of this string with the contents of another.
virtual void	Replace (const iString *str, size_t count=(size_t)-1)=0
	Replace contents of this string with the contents of another.
virtual void	ReplaceAll (const char *search, const char *replacement)=0
	Find all occurrences of search in this string and replace them with replacement.
virtual void	SetAt (size_t n, char iChar)=0
	Set the n'th character.
virtual void	SetCapacity (size_t NewSize)=0
	Advise the string that it should allocate enough space to hold up to NewSize characters.
virtual void	SetGrowsBy (size_t)=0
	Advise the string that it should grow its allocated buffer by approximately this many bytes when more space is required.
virtual void	ShrinkBestFit ()=0
	Set string buffer capacity to hold exactly the current content.
virtual csRef< iString >	Slice (size_t start, size_t len) const =0
	Copy and return a portion of this string.
virtual void	SubString (iString *sub, size_t start, size_t len) const =0
	Copy a portion of this string.
virtual void	Truncate (size_t Len)=0
	Truncate the string.
virtual void	Upcase ()=0
	Convert string to uppercase.

---

Detailed Description

This is a SCF-compatible interface for csString.

Definition at line 32 of file string.h.

---

Member Function Documentation

virtual void iString::Append	(	const iString *	Str,
		size_t	Count = (size_t)-1
	)			[pure virtual]

Append a string to this one.

Parameters:

	Str	String which will be appended.
	Count	Number of characters from Str to append; if -1 (the default), then all characters from Str will be appended.

Implemented in scfString.

virtual void iString::Append	(	const char *	Str,
		size_t	Count = (size_t)-1
	)			[pure virtual]

Append a null-terminated C-string to this one.

Parameters:

	Str	String which will be appended.
	Count	Number of characters from Str to append; if -1 (the default), then all characters from Str will be appended.

Implemented in scfString.

virtual void iString::Clear

(

)

[pure virtual]

Clear the string (so that it contains only a null terminator).

Remarks:

This is typically shorthand for Truncate(0), but more idiomatic in terms of human language.

Deprecated:

Use Empty() instead.

Implemented in scfString.

virtual csRef<iString> iString::Clone

(

)

const [pure virtual]

Get a copy of this string.

Implemented in scfString.

virtual bool iString::Compare

(

const iString *

Str

)

const [pure virtual]

Check if another string is equal to this one.

Parameters:

Str

Other string.

Returns:

True if they are equal; false if not.

Remarks:

The comparison is case-sensitive.

Implemented in scfString.

virtual bool iString::CompareNoCase

(

const iString *

Str

)

const [pure virtual]

Check if another string is equal to this one.

Parameters:

Str

Other string.

Returns:

True if they are equal; false if not.

Remarks:

The comparison is case-insensitive.

Implemented in scfString.

virtual void iString::Downcase

(

)

[pure virtual]

Convert string to lowercase.

Implemented in scfString.

virtual void iString::Empty

(

)

[pure virtual]

Clear the string (so that it contains only a null terminator).

Remarks:

This is typically shorthand for Truncate(0), but more idiomatic in terms of human language.

Implemented in scfString.

virtual size_t iString::Find	(	const char *	search,
		size_t	pos = 0
	)			const [pure virtual]

Find the first occurrence of search in this string starting at pos.

Parameters:

	search	String to locate.
	pos	Start position of search (default 0).

Returns:

First position of search, or (size_t)-1 if not found.

Implemented in scfString.

virtual size_t iString::FindFirst	(	const char	c,
		size_t	p = (size_t)-1
	)			const [pure virtual]

Find the first occurrence of a character in the string.

Parameters:

	c	Character to locate.
	p	Start position of search (default 0).

Returns:

First position of character, or (size_t)-1 if not found.

Implemented in scfString.

virtual size_t iString::FindLast	(	const char	c,
		size_t	p = (size_t)-1
	)			const [pure virtual]

Find the last occurrence of a character in the string.

Parameters:

	c	Character to locate.
	p	Start position of reverse search. Specify (size_t)-1 if you want the search to begin at the very end of string.

Returns:

Last position of character, or (size_t)-1 if not found.

Implemented in scfString.

virtual void iString::Format	(	const char *	format,
			...
	)			[pure virtual]

Format this string using sprintf()-style formatting directives.

Remarks:

Automatically allocates sufficient memory to hold result. Newly formatted string replaces previous string value.

See also:

Notes about string formatting in Crystal Space

Implemented in scfString.

virtual void iString::FormatV	(	const char *	format,
		va_list	args
	)			[pure virtual]

Format this string using sprintf() formatting directives in a va_list.

Returns:

Reference to itself.

Remarks:

Automatically allocates sufficient memory to hold result. Newly formatted string replaces previous string value.

See also:

Notes about string formatting in Crystal Space

Implemented in scfString.

virtual char iString::GetAt

(

size_t

n

)

const [pure virtual]

Get the n'th character.

Implemented in scfString.

virtual size_t iString::GetCapacity

(

)

const [pure virtual]

Return the current capacity.

Implemented in scfString.

virtual char* iString::GetData

(

)

[pure virtual]

Get a pointer to the null-terminated character array.

Returns:

A C-string pointer to the null-terminated character array; or zero if the string represents a null-pointer.

Warning:

This returns a non-const pointer, so use this function with care!

Deprecated:

Use the 'const' version of GetData() instead.

Implemented in scfString.

virtual char const* iString::GetData

(

)

const [pure virtual]

Get a pointer to the null-terminated character array.

Returns:

A C-string pointer to the null-terminated character array; or zero if the string represents a null-pointer.

Implemented in scfString.

virtual size_t iString::GetGrowsBy

(

)

const [pure virtual]

Return the number of bytes by which the string grows.

Remarks:

If the return value is zero, then the internal buffer grows exponentially by doubling its size, rather than by fixed increments.

Implemented in scfString.

virtual void iString::Insert	(	size_t	Pos,
		iString const *	Str
	)			[pure virtual]

Insert another string into this one.

Parameters:

	Pos	Position at which to insert the other string (zero-based).
	Str	String to insert.

Implemented in scfString.

virtual bool iString::IsEmpty

(

)

const [pure virtual]

Check if string is empty.

Returns:

True if the string is empty; false if it is not.

Remarks:

This is equivalent to the expression 'Length() == 0'.

Implemented in scfString.

virtual size_t iString::Length

(

)

const [pure virtual]

Query string length.

Returns:

The string length.

Remarks:

The returned length does not count the implicit null terminator.

Implemented in scfString.

virtual iString::operator char const *

(

)

const [pure virtual]

Get a pointer to the null-terminated character array.

Returns:

A C-string pointer to the null-terminated character array; or zero if the string represents a null-pointer.

Implemented in scfString.

virtual bool iString::operator!=

(

const iString &

Str

)

const [pure virtual]

Check if another string is not equal to this one.

Parameters:

Str

Other string.

Returns:

False if they are equal; true if not.

Remarks:

The comparison is case-sensitive.

Implemented in scfString.

virtual csRef<iString> iString::operator+

(

const iString &

iStr

)

const [pure virtual]

Concatenate two strings and return a third one.

Implemented in scfString.

virtual void iString::operator+=

(

const char *

iStr

)

[pure virtual]

Append a null-terminated C-string to this string.

Implemented in scfString.

virtual void iString::operator+=

(

const iString &

iStr

)

[pure virtual]

Append another string to this one.

Implemented in scfString.

virtual bool iString::operator==

(

const iString &

Str

)

const [pure virtual]

Check if another string is equal to this one.

Parameters:

Str

Other string.

Returns:

True if they are equal; false if not.

Remarks:

The comparison is case-sensitive.

Implemented in scfString.

virtual char iString::operator[]

(

size_t

n

)

const [pure virtual]

Get n'th character.

Implemented in scfString.

virtual char& iString::operator[]

(

size_t

n

)

[pure virtual]

Get a modifiable reference to n'th character.

Implemented in scfString.

virtual void iString::Overwrite	(	size_t	Pos,
		iString const *	Str
	)			[pure virtual]

Overlay another string onto a part of this string.

Parameters:

	Pos	Position at which to insert the other string (zero-based).
	Str	String which will be overlayed atop this string.

Remarks:

The target string will grow as necessary to accept the new string.

Implemented in scfString.

virtual void iString::Reclaim

(

)

[pure virtual]

Set string buffer capacity to hold exactly the current content.

Remarks:

If the string length is greater than zero, then the buffer's capacity will be adjusted to exactly that size. If the string length is zero, then the implementation may shrink the allocation so that it only holds the implicit null terminator, or it may free the string's memory completely.

Deprecated:

Use ShrinkBestFit() instead.

Implemented in scfString.

virtual void iString::Replace	(	const char *	str,
		size_t	count = (size_t)-1
	)			[pure virtual]

Replace contents of this string with the contents of another.

Parameters:

	str	String from which new content of this string will be copied.
	count	Number of characters to copy. If (size_t)-1 is specified, then all characters will be copied.

Implemented in scfString.

virtual void iString::Replace	(	const iString *	str,
		size_t	count = (size_t)-1
	)			[pure virtual]

Replace contents of this string with the contents of another.

Parameters:

	str	String from which new content of this string will be copied.
	count	Number of characters to copy. If (size_t)-1 is specified, then all characters will be copied.

Implemented in scfString.

virtual void iString::ReplaceAll	(	const char *	search,
		const char *	replacement
	)			[pure virtual]

Find all occurrences of search in this string and replace them with replacement.

Implemented in scfString.

virtual void iString::SetAt	(	size_t	n,
		char	iChar
	)			[pure virtual]

Set the n'th character.

Remarks:

The n'th character position must be a valid position in the string. You can not expand the string by setting a character beyond the end of string.

Implemented in scfString.

virtual void iString::SetCapacity

(

size_t

NewSize

)

[pure virtual]

Advise the string that it should allocate enough space to hold up to NewSize characters.

Remarks:

After calling this method, the string's capacity will be at least NewSize + 1 (one for the implicit null terminator). Never shrinks capacity. If you need to actually reclaim memory, then use Free() or Reclaim().

Implemented in scfString.

virtual void iString::SetGrowsBy

(

size_t

)

[pure virtual]

Advise the string that it should grow its allocated buffer by approximately this many bytes when more space is required.

This is an optimization to avoid excessive memory reallocation and heap management, which can be quite slow.

Remarks:

This value is only a suggestion. The actual value by which it grows may be rounded up or down to an implementation-dependent allocation multiple.

If the value is zero, then the internal buffer grows exponentially by doubling its size, rather than by fixed increments.

Implemented in scfString.

virtual void iString::ShrinkBestFit

(

)

[pure virtual]

Set string buffer capacity to hold exactly the current content.

Remarks:

If the string length is greater than zero, then the buffer's capacity will be adjusted to exactly that size. If the string length is zero, then the implementation may shrink the allocation so that it only holds the implicit null terminator, or it may free the string's memory completely.

Implemented in scfString.

virtual csRef<iString> iString::Slice	(	size_t	start,
		size_t	len
	)			const [pure virtual]

Copy and return a portion of this string.

Parameters:

	start	Start position of slice (zero-based).
	len	Number of characters in slice.

Returns:

The indicated string slice.

Implemented in scfString.

virtual void iString::SubString	(	iString *	sub,
		size_t	start,
		size_t	len
	)			const [pure virtual]

Copy a portion of this string.

Parameters:

	sub	String which will receive the indicated substring copy.
	start	Start position of slice (zero-based).
	len	Number of characters in slice.

Remarks:

Use this method instead of Slice() for cases where you expect to extract many substrings in a tight loop, and want to avoid the overhead of allocation of a new string object for each operation. Simply re-use 'sub' for each operation.

Implemented in scfString.

virtual void iString::Truncate

(

size_t

Len

)

[pure virtual]

Truncate the string.

Parameters:

Len

The number of characters to which the string should be truncated (possibly 0).

Remarks:

Will only make a string shorter; will never extend it. This method may or may not reclaim memory depending upon the implementation. If you positively need to reclaim memory after truncating the string, then invoke Reclaim().

Implemented in scfString.

virtual void iString::Upcase

(

)

[pure virtual]

Convert string to uppercase.

Implemented in scfString.

---

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

• iutil/string.h

---