Collaboration diagram

Description

SFXAnsiString and SFXWideString

In the BREW environment, there are two kinds of character types: the char type that represents single byte character or multi-byte character, and the AECHAR type that represents 2 byte character.

SophiaFramewok defines these two kinds of types as AChar and WChar respectively.

And SophiaFramework provides two kinds of String classes: the SFXAnsiString class for the string of AChar characters and the SFXWideString class for the string of WChar characters.

How to Empty a String

There are two methods to empty a string:

In the former method, its heap is not released. By block allocation support, to allocate new memory is unnecessary when a string is newly created in this heap. Therefore its processing speed is very fast.

In the latter method, its heap is released. Though the released heap is free for other tasks, its processing speed slows down.

Which method to choose depends upon the trade-off between processing speed and memory usage.

SFXAnsiString str = "The best C++ Programming Environment for BREW";

str = ";
// OR:
str.SetLength(0);

// the heap is not released

SFXAnsiString str = "The best C++ Programming Environment for BREW";

str.Clear();

// the heap is released

When short strings are frequently processed, the method of calling the SFXAnsiString::SetLength function is more efficient.

SFXAnsiString str;

str = "BREW";
...
str.SetLength(0);
...
str = "C++";
...
str.SetLength(0);
...
str = "GUI";
...
str.SetLength(0);
...
str = "XML";
...

Attach Function and Detach Function

The SFXAnsiString::Attach function delegates the control privilege of AChar string to the SFXAnsiString object. Therefore, it is unnecessary to release the memory of AChar string. The SFXAnsiString::Detach function has the reverse functionality.

Though the data is copied by using the SFXAnsiString::Set function and the substitution operator(=), while using the SFXAnsiString::Attach function and the SFXAnsiString::Detach function, data will not be copied.

When there is not enough heap for copying a several hundreds KB string, or to avoid the performance deterioration, use these functions.

What is delegation?: In object oriented programming, delegation means that an object have another deputy object behave like itself.

SFXAnsiString str;
ACharPtr ptr;

// allocate the memory and cast to the AChar string(ptr)
ptr = static_cast<ACharPtr>(MemoryAllocate(10240)); 
...

// delegate the control privilege of AChar string(ptr) to the SFXAnsiString object(str)
str.Attach(ptr, 10240);
// hereafter, the AChar string(ptr) will be handled as the SFXAnsiString object(str)

･･･

// after used, the allocated memory will be released automatically

SFXAnsiString str;
ACharPtr ptr;
SInt32 length;

str = "The best application for BREW.";

...

// delegate the control privilege of SFXAnsiString object(str) to the AChar string(ptr)
ptr = str.Detach(&length);
// hereafter, the SFXAnsiString object(str) will be handled as AChar string(ptr)

...

// after used, it is necessary to release the memory of AChar string(ptr) 
MemoryFree(ptr);

AttachSFXBuffer Function and DetachSFXBuffer Function

These functions are used to delegate the control privilege between the SFXAnsiString and SFXBuffer objects.

Related information : Attach Function and Detach Function

Reference

SFXWideString | SFXBuffer

Member

Description

When the SFXAnsiString class or the SFXWideString class is specified for the constructor of the SFXAnsiString class, the string is copied.

If the pointer of AChar or WChar is specified, it is interpreted and copied as a null-terminated string.

If the length is specified, binary string contains null can be processed, too.

When AChar is specified, only one character is made.

Reference

SFXAnsiString::Set | SFXAnsiString::operator=

Description

The internal string buffer is released.

Return value

Description

The Add function influences the character string. If want to keep the source string, use the Concat() function.

Reference

SFXAnsiString::Concat | SFXAnsiString::Sub | SFXAnsiString::Mul | SFXAnsiString::operator<< | operator+ | SFXAnsiString::operator+=

Description

The source string will not be modified by calling the AsLower() function.

Reference

SFXAnsiString::AsUpper | SFXAnsiString::ToLower

Description

If unable to convert, a specified value is returned to substitute.

Reference

SFXAnsiString::AsUInt32

Description

If unable to convert, a specified value is returned to substitute.

Reference

SFXAnsiString::AsSInt32

Description

The source string will not be modified by calling the AsUpper() function.

Reference

SFXAnsiString::AsLower | SFXAnsiString::ToUpper

Return value

Description

The SFXAnsiString::Attach function is more efficient than the SFXAnsiString::Set function, since the AChar string is not copied and the problem on insufficient memory or performance deterioration can be avoided.

The memory the allocated to AChar string will be released automatically when the SFXAnsiString object is released. To release the memory allocated to the AChar string explicitly, it is necessary to call the SFXAnsiString::Detach function.

Example

SFXAnsiString str;
ACharPtr ptr;

// allocate the memory and cast to the AChar string(ptr)
ptr = static_cast<ACharPtr>(MemoryAllocate(10240));

...

// delegate the control privilege of AChar string(ptr) to the SFXAnsiString object(str)
str.Attach(ptr, 10240);
// hereafter, the AChar string(ptr) can be handled as the SFXAnsiString object(str)

･･･

// after used, the allocated memory will be released automatically

Reference

SFXAnsiString::Detach

Return value

Description

The SFXAnsiString::AttachSFXBuffer function is more efficient than the SFXAnsiString::Set function, since the SFXBuffer object is not copied and the problem on insufficient memory or performance deterioration can be avoided.

The SFXBuffer object instance will be released automatically when the SFXAnsiString object is released. To release the SFXBuffer object explicitly, it is necessary to call the SFXAnsiString::DetachSFXBuffer function.

Example

SFXAnsiString str;
SFXBuffer buffer;

// allocate the memory for the SFXBuffer object(buffer)
buffer.SetSize(10240);

...

// delegate the control privilege of SFXBuffer object(buffer) to the SFXAnsiString object(str)
str.AttachSFXBuffer(&buffer);
// hereafter, the SFXBuffer object(buffer) can be handled as the SFXAnsiString object(str)

･･･

// after used, the allocated memory will be released automatically

Reference

SFXAnsiString::Attach | SFXAnsiString::Detach | SFXAnsiString::DetachSFXBuffer

Description

It releases the heap.

Return value

Reference

SFXAnsiString::Equals | operator== | operator!=

Return value

Return the concatenated string.

Description

The SFXAnsiString::Concat function concatenates the end of source string with a specified string. The source string will not be modified.

Reference

SFXAnsiString::Add | operator+ | SFXAnsiString::operator+=

Return value

Description

If the string after overwriting exceeds the end of source string, the source string is restored and return SFERR_INVALID_PARAM.

Return value

Return the AChar string which the SFXAnsiString object has.

Description

The SFXAnsiString::Detach function is more efficient than the SFXAnsiString::GetChar function, since the SFXAnsiString object is not copied and the problem on insufficient memory or performance deterioration can be avoided.

Example

SFXAnsiString str;
ACharPtr ptr;
SInt32 length;

str = "The best application for BREW.";

...

// delegate the control privilege of the SFXAnsiString object(str) to the AChar string(ptr)
ptr = str.Detach(&length);
// hereafter, the SFXAnsiString object(str) will be handled as the AChar string(ptr)

...

// after used, it is necessary to release the memory of AChar string(ptr) 
MemoryFree(ptr);

Reference

SFXAnsiString::Attach

Return value

Description

The SFXAnsiString object is not copied and the problem on insufficient memory or performance deterioration can be avoided.

Example

SFXAnsiString str;
SFXBuffer buffer;

str = "The best application for BREW.";

...

// delegate the control privilege of SFXAnsiString object(str) to the SFXBuffer object(buffer)
str.DetachSFXBuffer(&buffer);  
// hereafter, the SFXAnsiString object(str) will be handled as the SFXBuffer object(buffer)

･･･

// after used, the SFXBuffer object(buffer) will be released automatically

Reference

SFXAnsiString::Attach | SFXAnsiString::AttachSFXBuffer | SFXAnsiString::Detach

Description

Return the reference to the instance of enpty string as the return value of function.

Return value

Reference

SFXAnsiString::StartsWith

Return value

Reference

SFXAnsiString::Compare | operator== | operator!=

Return value

Description

To search from other than the beginning, specify the starting index to match with. (The origin index is 0.)

Reference

SFXAnsiString::LastIndexOf

Description

The SFXAnsiString::Format function is almost the same as the printf function in C language, the format on float is not available.

Example

SIntN year = 2003;
SIntN month = 8;
SFXAnsiString str = SFXAnsiString::Format("%d Year %d Month ", year, month);

Reference

BREW API VSNPRINTF

Description

The SFXAnsiString::FormatV fun