SAString

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 SAStringoperator= (const SAString &sSrc)
 Ref-counted copy from another SAString. More...
 
const SAStringoperator= (SAChar ch)
 Sets string content to single character. More...
 
const SAStringoperator= (char ch)
 Sets string content to single character. More...
 
const SAStringoperator= (const char *lpsz)
 Copies string content from ANSI (multi-byte) string (converts to SAChar) More...
 
const SAStringoperator= (const wchar_t *lpsz)
 Copies string content from UNICODE string (converts to SAChar) More...
 
const SAStringoperator= (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
SACharGetBuffer (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
SACharLockBuffer ()
 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 SAStringoperator+= (const SAString &string)
 Concatenates from another SAString.
 
const SAStringoperator+= (SAChar ch)
 Concatenates a single character.
 
const SAStringoperator+= (char ch)
 Concatenates an ANSI character after converting it to SAChar.
 
const SAStringoperator+= (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
lpszThe 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
lpszThe 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
lpszThe 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
nFirstThe 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
nFirstThe zero-based index of the first character in this SAString object that is to be included in the extracted substring.
nCountThe 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
nCountThe 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
nCountThe 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
chTargetThe 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
lpszTargetListA 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
chTargetThe 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
lpszTargetsA 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
lpszOldA pointer to a string containing the character to be replaced by lpszNew.
lpszNewA 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
nIndexThe index of the character before which the insertion will take place.
chThe 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
nIndexThe index of the character before which the insertion will take place.
pstrA 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
nIndexThe index of the first character to delete.
nCountThe 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
chA 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
chA single character to search for.
nStartThe 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
lpszSubA 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
nStartThe 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.
lpszSubA 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
chThe 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
lpszCharSetString 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
nMinBufLengthThe 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
nNewLengthThe 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
nMinBufLengthInBytesThe 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
nNewLengthInBytesThe 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.