Working With Strings

Encodings

The Beast API can handle string input and output using any of the following encodings:

• ANSI. This is the default string encoding in Visual Studio when working with 8-bit strings. Strings work like char* with ASCII characters only. You should use this encoding in your own project unless you need support for the wider range of characters accepted by Unicode encoding.
• UTF-8: 8-bit Unicode encoding.
• UTF-16: 16-bit Unicode encoding. This is the default string encoding in Visual Studio when working with Unicode strings.

The Beast API will attempt to detect automatically the string encoding used by the host application with the pre-processor. You can override the auto-detection by setting one of the following defines to specify the kind of encoding you want to use:

#define ILB_STRING_ANSI
#define ILB_STRING_UTF8
#define ILB_STRING_UTF16

If you choose to specify an encoding using one of those defines, make sure that you do this for all files that directly or indirectly use the Beast headers in order to avoid conflicts. See the beastapitypes.h file for the auto-detection and setup for strings.

Input strings

When you provide a string to the Beast API, you provide it as an ILBConstString object. This is a pointer to a zero-terminated string of characters. Depending on the string encoding being used, the character type will be different. If you use ANSI or UTF-8 encodings, you can build the ILBConstString from a string of char* characters; if you use UTF-16, you can build the ILBConstString from a string of wchar_t* characters.

Output strings

Beast also provides strings as output in some cases. This requires some memory management to ensure that the memory allocated for the string is released properly.

When a function in the Beast API provides a string as output, it provides it through an ILBStringHandle. You need to use this handle as follows:

1. Create a new ILBStringHandle before you call the Beast API function, and pass it as a parameter.
2. After the function has completed, call ILBGetLength() to determine the length of the string.
3. Allocate a buffer of the appropriate length, and copy the contents of the handle into that buffer by calling ILBCopy(). The length value indicated by the API gives the length of the string as the number of ILBCharType objects that make it up; the ILBCharType is determined by the string encoding currently in use. The length also includes the zero termination marker. The Beast API will never return a zero-length string; empty strings are represented as a single zero termination marker.
4. Once you have finished with the string handle, you need to release it by calling ILBReleaseString(). String handles are not managed through the Beast manager, so if you do not release a string handle that you have created, you will have a memory leak.

The typical way of handling return strings is to create a function that converts the string to the format used in the host application. For example, the following code block creates an std::string from an ILBStringHandle in C++:

std::string convertBeastString(ILBStringHandle h) {
   int32 len;
   ILBGetLength(h, &len);
   // Note that Beast strings give their length
   // including zero termination. We need to
   // make the std::string 1 character shorter
   // since std::string expects sizes without zero
   // termination.
   std::string result(len - 1, 0);
   ILBCopy(h, &result[0], len);
   ILBReleaseString(h);
   return result;
}