Provides support for manipulating character values. More...

Inherited by SABytes, and SALongOrLob.

Public Member Functions
Constructors
Each of SAString constructors initializes a new SAString object with the specified data.
	SAString ()
	Constructs an empty SAString. More...

	SAString (const SAString &stringSrc)
	Copy constructor.

	SAString (SAChar ch, size_t nRepeat)
	Initializes SAString from a single character.

	SAString (const char *lpsz)
	Initializes SAString from an ANSI (multibyte) string (converts to SAChar)

	SAString (const wchar_t *lpsz)
	Initializes SAString from an ANSI (multibyte) string.

	SAString (const char *lpch, size_t nLength)
	Initializes SAString from subset of characters from an ANSI (multibyte) string (converts to SAChar)

	SAString (const wchar_t *lpch, size_t nLength)
	SA_UNICODE.

	SAString (const unsigned char *psz)
	Initializes SAString from unsigned characters (converts to SAChar)

	SAString (const void *pBuffer, size_t nLengthInBytes)
	Special constructor for binary data (no conversion to SAChar)

Attributes & Operations
size_t	GetLength () const
	Returns the data length (in characters). More...

bool	IsEmpty () const
	Tests whether a SAString object contains no characters. More...

void	Empty ()
	Clears contents to empty. More...

	operator const SAChar * () const
	Directly accesses characters stored in a SAString object as a C-style string. More...

void	MakeUpper ()
	Converts the object to uppercase.

void	MakeLower ()
	Converts the object to lowercase.

Overloaded assignment
const SAString &	operator= (const SAString &sSrc)
	Ref-counted copy from another SAString. More...

const SAString &	operator= (SAChar ch)
	Sets string content to single character. More...

const SAString &	operator= (char ch)
	Sets string content to single character. More...

const SAString &	operator= (const char *lpsz)
	Copies string content from ANSI (multi-byte) string (converts to SAChar) More...

const SAString &	operator= (const wchar_t *lpsz)
	Copies string content from UNICODE string (converts to SAChar) More...

const SAString &	operator= (const unsigned char *psz)
	Copies string content from unsigned chars. More...

String comparison
int	Compare (const SAChar *lpsz) const
	Compares two strings (case sensitive). More...

int	CompareNoCase (const SAChar *lpsz) const
	Compares two strings (case insensitive). More...

int	Collate (const SAChar *lpsz) const
	Compares two strings (case sensitive, uses locale-specific information). More...

Simple sub-string extraction
SAString	Mid (size_t nFirst) const
	Return all characters starting at zero-based nFirst. More...

SAString	Mid (size_t nFirst, size_t nCount) const
	Return nCount characters starting at zero-based nFirst. More...

SAString	Left (size_t nCount) const
	Extracts the left part of a string. More...

SAString	Right (size_t nCount) const
	Extracts the right part of a string. More...

SAChar	GetAt (size_t nPos) const
	Returns the character at the specified string position.

Trimming whitespace (either side)
void	TrimRight ()
	Removes whitespace starting from right edge. More...

void	TrimLeft ()
	Removes whitespace starting from left side. More...

Trimming anything (either side)
void	TrimRight (SAChar chTarget)
	Removes continuous occurrences of chTarget starting from right. More...

void	TrimRight (const SAChar *lpszTargets)
	Removes continuous occurrences of characters in passed string, starting from right. More...

void	TrimLeft (SAChar chTarget)
	Removes continuous occurrences of chTarget starting from left. More...

void	TrimLeft (const SAChar *lpszTargets)
	Removes continuous occurrences of characters in passed string, starting from left. More...

Advanced manipulation
size_t	Replace (const SAChar lpszOld, const SAChar lpszNew)
	Replaces indicated characters with other characters. More...

size_t	Insert (size_t nIndex, SAChar ch)
	Inserts a single character or a substring at the given index within the string. More...

size_t	Insert (size_t nIndex, const SAChar *pstr)
	Insert substring at zero-based index; concatenates if index is past end of string. More...

size_t	Delete (size_t nIndex, size_t nCount=1)
	Deletes a character or characters from a string. More...

Searching
size_t	Find (SAChar ch) const
	Finds a character or substring inside a larger string. More...

size_t	Find (SAChar ch, size_t nStart) const
	Find character starting at zero-based index and going right. More...

size_t	Find (const SAChar *lpszSub) const
	Finds first instance of substring. More...

size_t	Find (const SAChar *lpszSub, size_t nStart) const
	Finds first instance of substring starting at zero-based index. More...

size_t	ReverseFind (SAChar ch) const
	Finds a character inside a larger string; starts from the end. More...

size_t	FindOneOf (const SAChar *lpszCharSet) const
	Finds the first matching character from a set. More...

Simple formatting
void	Format (const SAChar *lpszFormat,...)
	Printf-like formatting using passed string. More...

void	FormatV (const SAChar *, va_list argList)
	Printf-like formatting using variable arguments parameter. More...

Access to string implementation buffer as "C" character array
SAChar *	GetBuffer (size_t nMinBufLength)
	Returns a pointer to the characters in the SAString. More...

void	ReleaseBuffer (size_t nNewLength=SIZE_MAX)
	Releases control of the buffer returned by GetBuffer. More...

Use LockBuffer/UnlockBuffer to turn ref counting off
SAChar *	LockBuffer ()
	Disables reference counting and protects the string in the buffer. More...

void	UnlockBuffer ()
	Enables reference counting and releases the string in the buffer. More...

Special buffer access routines to manipulate binary data
size_t	GetBinaryLength () const
	Returns a count of the bytes in the binary data buffer. More...

	operator const void * () const
	Returns pointer to const binary data buffer. More...

const void *	GetBinaryData () const
	Returns pointer to const binary data buffer. More...

void *	GetBinaryBuffer (size_t nMinBufLengthInBytes)
	Gets pointer to modifiable binary data buffer. More...

void	ReleaseBinaryBuffer (size_t nNewLengthInBytes)
	Releases control of the buffer returned by GetBinaryBuffer. More...

Special conversion functions (multi-byte <-> Unicode)
const wchar_t *	GetWideChars () const
	Returns pointer to const Unicode string, converts the data if needed. More...

size_t	GetWideCharsLength () const
	Returns the string length (in Unicode characters). More...

const char *	GetMultiByteChars () const
	Return pointer to const multi-byte string, converts the data if needed. More...

size_t	GetMultiByteCharsLength () const
	Returns the string length (in multi-byte characters). More...

const char *	GetUTF8Chars () const
	Returns pointer to const UTF8 string.

size_t	GetUTF8CharsLength () const
	Returns the string length (in UTF8 characters).

void	SetUTF8Chars (const char *szSrc, size_t nSrcLen=SIZE_MAX)
	Assigns the UTF8 data into SAString object.

const void *	GetUTF16Chars () const
	Returns pointer to const UTF16 string.

size_t	GetUTF16CharsLength () const
	Returns the string length (in UTF16 characters).

void	SetUTF16Chars (const void *szSrc, size_t nSrcLen=SIZE_MAX)
	Assigns the UTF16 data into SAString object.

String concatenation
const SAString &	operator+= (const SAString &string)
	Concatenates from another SAString.

const SAString &	operator+= (SAChar ch)
	Concatenates a single character.

const SAString &	operator+= (char ch)
	Concatenates an ANSI character after converting it to SAChar.

const SAString &	operator+= (const SAChar *lpsz)
	Concatenates from a SAChar string.

Detailed Description

Provides support for manipulating character values.

SAString is a subsidiary class. SAString object consists of a variable-length sequence of characters. The SAString class provides support for manipulating strings.

It is intended to replace and extend the functionality normally provided by the C run-time library string package. The SAString class supplies member functions and operators for simplified string handling. The class also provides constructors and operators for constructing, assigning, and comparing SAString objects and standard C++ string data types.

Concatenation and comparison operators, together with simplified memory management, make SAString objects easier to use than ordinary character arrays.

Remarks: SAString is based on the SAChar data type. If the symbol SA_UNICODE is defined for your program, SAChar is defined as type wchar_t, a 16-/32-bit character type; otherwise, it is defined as char, the normal 8-bit character type (default, SA_UNICODE is not defined). Under Unicode, then, SAString objects are composed of 16-bit characters. Without Unicode, they are composed of 8-bit char type. When not using SA_UNICODE, SAString is enabled for multibyte character sets. Note that for multibyte strings, SAString still counts, returns, and manipulates strings based on 8-bit characters, and your application must interpret multibyte lead and trail bytes itself. SAString objects follow "value semantics". A SAString object represents a unique value. Think of a SAString as an actual string, not as a pointer to a string. A SAString object represents a sequence of a variable number of characters. SAString objects can be thought of as arrays of characters. When SAString objects are copied, the Library increments a reference count rather than copying the data. This makes passing parameters by value and returning SAString objects by value more efficient. These operations cause the copy constructor to be called, sometimes more than once. Incrementing a reference count reduces that overhead for these common operations and makes using SAString a more attractive option. As each copy is destroyed, the reference count in the original object is decremented. The original SAString object is not destroyed until its reference count is reduced to zero.

Constructor & Destructor Documentation

◆ SAString()

SAString::SAString ( )

Constructs an empty SAString.

Because the constructors copy the input data into new allocated storage, you should be aware that memory exceptions may result. Note that some of these constructors act as conversion functions. This allows you to substitute, for example, an const char* where a SAString object is expected.

Member Function Documentation

◆ GetLength()

size_t SAString::GetLength ( ) const

Returns the data length (in characters).

Returns: Returns the number of characters in a SAString object.

Remarks: Call this member function to get a count of characters in this SAString object. The count does not include a null terminator. For multibyte character sets, GetLength counts each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two bytes.

See also: IsEmpty

◆ IsEmpty()

bool SAString::IsEmpty ( ) const

Tests whether a SAString object contains no characters.

Returns: Nonzero if the SAString object has 0 length; otherwise 0.

Remarks: Tests a SAString object for the empty condition.

See also: GetLength | GetMultiByteCharsLength | GetWideCharsLength

◆ Empty()

void SAString::Empty ( )

Clears contents to empty.

Makes this SAString object an empty string and frees memory as appropriate.

◆ operator const SAChar *()

SAString::operator const SAChar * ( ) const

Directly accesses characters stored in a SAString object as a C-style string.

Returns: A character pointer to the string's data.

Remarks: This useful casting operator provides an efficient method to access the null-terminated C string contained in a SAString object. No characters are copied; only a pointer is returned. Be careful with this operator. If you change a SAString object after you have obtained the character pointer, you may cause a reallocation of memory that invalidates the pointer.

◆ operator=() [1/6]

const SAString & SAString::operator= ( const SAString & stringSrc )

Ref-counted copy from another SAString.

Remarks: The SAString assignment (=) operator reinitializes an existing SAString object with new data. If the destination string (that is, the left side) is already large enough to store the new data, no new memory allocation is performed.

◆ operator=() [2/6]

const SAString & SAString::operator= ( SAChar ch )

Sets string content to single character.

SA_UNICODE.

Remarks: The SAString assignment (=) operator reinitializes an existing SAString object with new data. If the destination string (that is, the left side) is already large enough to store the new data, no new memory allocation is performed.

◆ operator=() [3/6]

const SAString & SAString::operator= ( char ch )

Sets string content to single character.

Remarks: The SAString assignment (=) operator reinitializes an existing SAString object with new data. If the destination string (that is, the left side) is already large enough to store the new data, no new memory allocation is performed.

◆ operator=() [4/6]

const SAString & SAString::operator= ( const char * lpsz )

Copies string content from ANSI (multi-byte) string (converts to SAChar)

Remarks: The SAString assignment (=) operator reinitializes an existing SAString object with new data. If the destination string (that is, the left side) is already large enough to store the new data, no new memory allocation is performed.

◆ operator=() [5/6]

const SAString & SAString::operator= ( const wchar_t * lpsz )

Copies string content from UNICODE string (converts to SAChar)

Remarks: The SAString assignment (=) operator reinitializes an existing SAString object with new data. If the destination string (that is, the left side) is already large enough to store the new data, no new memory allocation is performed.

◆ operator=() [6/6]

const SAString & SAString::operator= ( const unsigned char * psz )

Copies string content from unsigned chars.

Remarks: The SAString assignment (=) operator reinitializes an existing SAString object with new data. If the destination string (that is, the left side) is already large enough to store the new data, no new memory allocation is performed.

◆ Compare()

int SAString::Compare ( const SAChar * lpsz ) const

Compares two strings (case sensitive).

Returns: Returns zero if the strings are identical, < 0 if this SAString object is less than lpsz, or > 0 if this SAString object is greater than lpsz.

Parameters

lpsz	The other string used for comparison.

Remarks: Compares this SAString object with another string. Function performs a case-sensitive comparison of the strings, and is not affected by locale.

See also: CompareNoCase Collate

◆ CompareNoCase()

int SAString::CompareNoCase ( const SAChar * lpsz ) const

Compares two strings (case insensitive).

Returns: Returns zero if the strings are identical (ignoring case), < 0 if this SAString object is less than lpsz (ignoring case), or > 0 if this SAString object is greater than lpsz (ignoring case).

Parameters

lpsz	The other string used for comparison.

Remarks: Compares this SAString object with another string. Function performs a case-insensitive comparison of the strings, and is not affected by locale.

◆ Collate()

int SAString::Collate ( const SAChar * lpsz ) const

Compares two strings (case sensitive, uses locale-specific information).

Returns: Returns zero if the strings are identical, < 0 if this SAString object is less than lpsz, or > 0 if this SAString object is greater than lpsz.

Parameters

lpsz	The other string used for comparison.

Remarks: Compares this SAString object with another string. Function performs a case-sensitive comparison of the strings according to the code page currently in use.

◆ Mid() [1/2]

SAString SAString::Mid ( size_t nFirst ) const

Return all characters starting at zero-based nFirst.

Returns: SAString object that contains a copy of the specified range of characters. Note that the returned SAString object may be empty.

Remarks: Extracts a substring of length nCount characters from this SAString object, starting at position nFirst(zero - based).The function returns a copy of the extracted substring. For multibyte character sets(default, SA_UNICODE is not defined), nCount refers to each 8 - bit character; that is, a lead and trail byte in one multibyte character are counted as two characters.

Parameters

nFirst The zero-based index of the first character in this SAString object that is to be included in the extracted substring.

◆ Mid() [2/2]

SAString SAString::Mid	(	size_t	nFirst,
		size_t	nCount
	)		const

Return nCount characters starting at zero-based nFirst.

Parameters

nFirst	The zero-based index of the first character in this SAString object that is to be included in the extracted substring.
nCount	The number of characters to extract from this SAString object. If this parameter is not supplied, then the remainder of the string is extracted.

◆ Left()

SAString SAString::Left ( size_t nCount ) const

Extracts the left part of a string.

Return first nCount characters in string.

Returns: SAString object containing a copy of the specified range of characters. Note that the returned SAString object may be empty.

Parameters

nCount The number of characters to extract from this SAString object.

Remarks: Extracts the first (that is, leftmost) nCount characters from this SAString object and returns a copy of the extracted substring. If nCount exceeds the string length, then the entire string is extracted. For multibyte character sets (default, SA_UNICODE is not defined), nCount refers to each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two characters.

◆ Right()

SAString SAString::Right ( size_t nCount ) const

Extracts the right part of a string.

Return nCount characters from end of string.

Returns: SAString object that contains a copy of the specified range of characters. Note that the returned SAString object may be empty.

Parameters

nCount The number of characters to extract from this SAString object.

Remarks: Extracts the last (that is, rightmost) nCount characters from this SAString object and returns a copy of the extracted substring. If nCount exceeds the string length, then the entire string is extracted. For multibyte character sets (default, SA_UNICODE is not defined), nCount refers to each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two characters.

◆ TrimRight() [1/3]

void SAString::TrimRight ( )

Removes whitespace starting from right edge.

Remarks: Call the version of this member function with no parameters to trim trailing whitespace characters from the string. When used with no parameters, TrimRight removes trailing newline, space, and tab characters from the string. Use the versions of this function that accept parameters to remove a particular character or a particular group of characters from the end of a string.

◆ TrimLeft() [1/3]

void SAString::TrimLeft ( )

Removes whitespace starting from left side.

Remarks: Call the version of this member function with no parameters to trim leading whitespace characters from the string. When used with no parameters, TrimLeft removes newline, space, and tab characters. Use the versions of this function that accept parameters to remove a particular character or a particular group of characters from the beginning of a string.

◆ TrimRight() [2/3]

void SAString::TrimRight ( SAChar chTarget )

Removes continuous occurrences of chTarget starting from right.

Parameters

chTarget The target characters to be trimmed.

◆ TrimRight() [3/3]

void SAString::TrimRight ( const SAChar * lpszTargetList )

Removes continuous occurrences of characters in passed string, starting from right.

Parameters

lpszTargetList A pointer to a string containing the target characters to be trimmed.

◆ TrimLeft() [2/3]

void SAString::TrimLeft ( SAChar chTarget )

Removes continuous occurrences of chTarget starting from left.

Parameters

chTarget The target characters to be trimmed.

◆ TrimLeft() [3/3]

void SAString::TrimLeft ( const SAChar * lpszTargets )

Removes continuous occurrences of characters in passed string, starting from left.

Parameters

lpszTargets A pointer to a string containing the target characters to be trimmed.

◆ Replace()

size_t SAString::Replace	(	const SAChar *	lpszOld,
		const SAChar *	lpszNew
	)

Replaces indicated characters with other characters.

Returns: The number of replaced instances of the character. Zero if the string isn't changed. Parameters

Parameters

lpszOld	A pointer to a string containing the character to be replaced by lpszNew.
lpszNew	A pointer to a string containing the character replacing lpszOld.

Remarks: Call this member function to replace instances of the substring lpszOld with instances of the string lpszNew .

◆ Insert() [1/2]

size_t SAString::Insert	(	size_t	nIndex,
		SAChar	ch
	)

Inserts a single character or a substring at the given index within the string.

Insert character at zero-based index; concatenates if index is past end of string.

Returns: Returns the length of the changed string.

Remarks: Call this member function to insert a single character or a substring at the given index within the string. The nIndex parameter identifies the first character that will be moved to make room for the character or substring. If nIndex is zero, the insertion will occur before the entire string.If nIndex is higher than the length of the string, the function will concatenate the present string and the new material provided by either ch or pstr.

Parameters

nIndex	The index of the character before which the insertion will take place.
ch	The character to be inserted.

◆ Insert() [2/2]

size_t SAString::Insert	(	size_t	nIndex,
		const SAChar *	pstr
	)

Insert substring at zero-based index; concatenates if index is past end of string.

Parameters

nIndex	The index of the character before which the insertion will take place.
pstr	A pointer to the substring to be inserted.

◆ Delete()

size_t SAString::Delete	(	size_t	nIndex,
		size_t	nCount = `1`
	)

Deletes a character or characters from a string.

Returns: Returns the length of the changed string.

Parameters

nIndex	The index of the first character to delete.
nCount	The number of characters to be removed.

Remarks: Call this member function to delete a character or characters from a string starting with the character at nIndex.If nCount is longer than the string, the remainder of the string will be removed.

◆ Find() [1/4]

size_t SAString::Find ( SAChar ch ) const

Finds a character or substring inside a larger string.

Find character starting at left, SIZE_MAX if not found.

Returns: The zero-based index of the first character in this SAString object that matches the requested substring or characters; SIZE_MAX if the substring or character is not found.

Parameters

ch	A single character to search for.

Remarks: Searches this string for the first match of a substring. The function is overloaded to accept both single characters (similar to the run-time function strchr) and strings (similar to strstr ).

◆ Find() [2/4]

size_t SAString::Find	(	SAChar	ch,
		size_t	nStart
	)		const

Find character starting at zero-based index and going right.

Parameters

ch	A single character to search for.
nStart	The index of the character in the string to begin the search with, or 0 to start from the beginning. The character at nStart is excluded from the search if nStart is not equal to 0.

◆ Find() [3/4]

size_t SAString::Find ( const SAChar * lpszSub ) const

Finds first instance of substring.

Parameters

lpszSub A substring to search for.

◆ Find() [4/4]

size_t SAString::Find	(	const SAChar *	lpszSub,
		size_t	nStart
	)		const

Finds first instance of substring starting at zero-based index.

Parameters

nStart	The index of the character in the string to begin the search with, or 0 to start from the beginning. The character at nStart is excluded from the search if nStart is not equal to 0.
lpszSub	A substring to search for.

◆ ReverseFind()

size_t SAString::ReverseFind ( SAChar ch ) const

Finds a character inside a larger string; starts from the end.

Returns: The index of the last character in this SAString object that matches the requested character; SIZE_MAX if the character is not found.

Parameters

ch	The character to search for.

Remarks: Searches this SAString object for the last match of a substring. The function is similar to the run-time function strrchr.

◆ FindOneOf()

size_t SAString::FindOneOf ( const SAChar * lpszCharSet ) const

Finds the first matching character from a set.

Returns: The zero-based index of the first character in this string that is also in lpszCharSet; SIZE_MAX if there is no match.

Parameters

lpszCharSet String containing characters for matching.

Remarks: Searches this string for the first character that matches any character contained in lpszCharSet .

◆ Format()

void SAString::Format	(	const SAChar *	lpszFormat,
			...
	)

Printf-like formatting using passed string.

Formats the string as sprintf does.

Remarks: Call this member function to write formatted data to a SAString in the same way that sprintf formats data into a C - style character array.This function formats and stores a series of characters and values in the SAString.Each optional argument(if any) is converted and output according to the corresponding format specification in lpszFormat.

See also: FormatV

◆ FormatV()

void SAString::FormatV	(	const SAChar *	lpszFormat,
		va_list	argList
	)

Printf-like formatting using variable arguments parameter.

Formats the string as vsprintf does.

Remarks: Call this member function to write a formatted string and a variable list of arguments to a SAString object in the same way that vsprintf formats data into a C-style character array. This function formats and stores a series of characters and values in the SAString. The string and arguments are converted and output according to the corresponding format specification in lpszFormat.

See also: Format

◆ GetBuffer()

SAChar * SAString::GetBuffer ( size_t nMinBufLength )

Returns a pointer to the characters in the SAString.

Parameters

nMinBufLength The minimum size of the character buffer in characters. This value does not include space for a null terminator.

Returns: A pointer to the object's (null-terminated) character buffer.

Remarks: Returns a pointer to the internal character buffer for the SAString object. If you use the pointer returned by GetBuffer to change the string contents, you must call ReleaseBuffer before using any other SAString member functions. The buffer memory will be freed automatically when the SAString object is destroyed.

◆ ReleaseBuffer()

void SAString::ReleaseBuffer ( size_t nNewLength = SIZE_MAX )

Releases control of the buffer returned by GetBuffer.

Parameters

nNewLength The new length of the string in characters, not counting a null terminator. If the string is null-terminated, the -1 default value sets the SAString size to the current length of the string.

Remarks: Use ReleaseBuffer to end use of a buffer allocated by GetBuffer. If you know that the string in the buffer is null-terminated, you can omit the nNewLength argument. If your string is not null-terminated, then use nNewLength to specify its length. The address returned by GetBuffer is invalid after the call to ReleaseBuffer or any other SAString operation.

◆ LockBuffer()

SAChar * SAString::LockBuffer ( )

Disables reference counting and protects the string in the buffer.

Returns: A pointer to a SAString object or null-terminated string.

Remarks: Call this member function to lock a string in the buffer.
By calling LockBuffer, you create a copy of the string, and then set the reference count to -1. When the reference count is set to -1, the string in the buffer is considered to be in a "locked" state. While in a locked state, the string is protected in two ways:

No other string can get a reference to the data in the locked string, even if that string is assigned to the locked string.
The locked string will never reference another string, even if that other string is copied to the locked string.

By locking the string in the buffer, you ensure that the string's exclusive hold on the buffer will remain intact.
After you have finished with LockBuffer, call UnlockBuffer to reset the reference count to 1.

◆ UnlockBuffer()

void SAString::UnlockBuffer ( )

Enables reference counting and releases the string in the buffer.

Remarks: Call this member function to unlock the buffer that was previously secured by calling LockBuffer. UnlockBuffer resets the reference count to 1.
The SAString destructor implies UnlockBuffer to ensure that you do not leave the buffer locked when the destructor is called.

◆ GetBinaryLength()

size_t SAString::GetBinaryLength ( ) const

Returns a count of the bytes in the binary data buffer.

Returns: A count of the bytes in the binary data block represented by the SAString object.

Remarks: Call this member function to get a count of the bytes in this SAString object.
GetBinaryLength method was implemented specially for working with binary data. This method always returns the length of SAString object data in bytes. This method is specially usefull for Unicode build (SA_UNICODE is defined) where character size is not equal to one byte. For non-Unicode build (default, SA_UNICODE is not defined) GetBinaryLength behaves identically to GetLength.

◆ operator const void *()

SAString::operator const void * ( ) const

Returns pointer to const binary data buffer.

Returns: A pointer to the binary data buffer.

Remarks: This useful casting operator provides an efficient method to access the binary data contained in a SAString object. No bytes are copied; only a pointer is returned. Be careful with this operator. If you change a SAString object after you have obtained the bytes pointer, you may cause a reallocation of memory that invalidates the pointer.

◆ GetBinaryData()

const void * SAString::GetBinaryData ( ) const

Returns pointer to const binary data buffer.

Returns: A pointer to the binary data buffer.

Remarks: Returns the ponter to the binary data contained in a SAString object. No bytes are copied only a pointer is returned. Be careful - if you change SAString object after you have obtained the bytes pointer, you may cause a reallocation of memory that invalidates the pointer.

◆ GetBinaryBuffer()

void * SAString::GetBinaryBuffer ( size_t nMinBufLengthInBytes )

Gets pointer to modifiable binary data buffer.

Parameters

nMinBufLengthInBytes The minimum size of the binary data buffer in bytes.

Returns: A pointer to the binary data contained in the SAString object.

Remarks: GetBinaryBuffer method was implemented specially for working with binary data. This method is specially usefull for Unicode build (SA_UNICODE is defined) where character size is not equal to one byte. For non-Unicode build (default, SA_UNICODE is not defined) GetBinaryBuffer behaves identically to GetBuffer, except it casts the result to void*.
If you use the pointer returned by GetBinaryBuffer to change the string contents, you must call ReleaseBinaryBuffer before using any other SAString member functions.
The buffer memory will be freed automatically when the SAString object is destroyed.

◆ ReleaseBinaryBuffer()

void SAString::ReleaseBinaryBuffer ( size_t nNewLengthInBytes )

Releases control of the buffer returned by GetBinaryBuffer.

Parameters

nNewLengthInBytes The new length of the binary data buffer represented by the SAString object in bytes.

Remarks: Use ReleaseBinaryBuffer to end use of a buffer allocated by GetBinaryBuffer. Use nNewLength to specify its length. The address returned by GetBinaryBuffer is invalid after the call to ReleaseBinaryBuffer or any other SAString operation.

◆ GetWideChars()

const wchar_t * SAString::GetWideChars ( ) const

Returns pointer to const Unicode string, converts the data if needed.

Returns: A pointer to const Unicode string.

Remarks: Special conversion function allows you to get a Unicode string both in Unicode and non-Unicode builds.
In Unicode built (SA_UNICODE is defined) this method acts like operator const SAChar*.
In non-Unicode build (default, SA_UNICODE is not defined) this method converts the SAString object to Unicode string on the fly.

◆ GetWideCharsLength()

size_t SAString::GetWideCharsLength ( ) const

Returns the string length (in Unicode characters).

Returns: A string length in Unicode characters.

Remarks: This special function allows you to get a number of Unicode characters in the given string both in Unicode and non-Unicode builds.
In Unicode built (SA_UNICODE is defined) this method acts like GetLength.
In non-Unicode build (default, SA_UNICODE is not defined) this method converts the SAString object to Unicode string and returns the number of Unicode characters on the fly.

◆ GetMultiByteChars()

const char * SAString::GetMultiByteChars ( ) const

Return pointer to const multi-byte string, converts the data if needed.

Returns: A character pointer to const multibyte string.

Remarks: Special conversion function allows you to get a multibyte string both in Unicode and non-Unicode builds.
In Unicode build (SA_UNICODE is defined) this method converts the SAString object to multibyte string on the fly.
In non-Unicode built (default, SA_UNICODE is not defined) this method acts like operator const SAChar*.

◆ GetMultiByteCharsLength()

size_t SAString::GetMultiByteCharsLength ( ) const

Returns the string length (in multi-byte characters).

Returns: A count of characters in the multibyte string.

Remarks: This special function allows you to get a number of multibyte characters in the given string both in Unicode and non-Unicode builds.
In Unicode build (SA_UNICODE is defined) this method converts the SAString object to multibyte string and returns the number of multibyte characters on the fly.
In non-Unicode built (default, SA_UNICODE is not defined) this method acts like GetLength.

Build

Class Library

Server Specific Guides

Public Member Functions

String concatenation

Detailed Description

Constructor & Destructor Documentation

◆ SAString()

Member Function Documentation

◆ GetLength()

◆ IsEmpty()

◆ Empty()

◆ operator const SAChar *()

◆ operator=() [1/6]

◆ operator=() [2/6]

◆ operator=() [3/6]

◆ operator=() [4/6]

◆ operator=() [5/6]

◆ operator=() [6/6]

◆ Compare()

◆ CompareNoCase()

◆ Collate()

◆ Mid() [1/2]

◆ Mid() [2/2]

◆ Left()

◆ Right()

◆ TrimRight() [1/3]

◆ TrimLeft() [1/3]

◆ TrimRight() [2/3]

◆ TrimRight() [3/3]

◆ TrimLeft() [2/3]

◆ TrimLeft() [3/3]

◆ Replace()

◆ Insert() [1/2]

◆ Insert() [2/2]

◆ Delete()

◆ Find() [1/4]

◆ Find() [2/4]

◆ Find() [3/4]

◆ Find() [4/4]

◆ ReverseFind()

◆ FindOneOf()

◆ Format()

◆ FormatV()

◆ GetBuffer()

◆ ReleaseBuffer()

◆ LockBuffer()

◆ UnlockBuffer()

◆ GetBinaryLength()

◆ operator const void *()

◆ GetBinaryData()

◆ GetBinaryBuffer()

◆ ReleaseBinaryBuffer()

◆ GetWideChars()

◆ GetWideCharsLength()

◆ GetMultiByteChars()

◆ GetMultiByteCharsLength()