StringWrapper Documentation

Library	StringWrapper
File	StringWrapper.h
Author	Brodie Thiesfield [code at jellycan dot com]
Source	http://code.jellycan.com/stringwrapper/
Version	2.1

INTRODUCTION

The StringWrapper component classes provide a very thin wrapper around the ICU UnicodeString (UTF-16 Unicode strings) and a simple implementation of the same API for char strings (MBCS and ASCII).

The primary advantages of using this wrapper are:

• Both string types expose a very similar interface so users need to learn only a single string interface.
• All strings returned by "getBuffer() const" are always NULL terminated. Note that this guarantee is for the *const* version of the API, this guarantee is not provided by the raw ICU UnicodeString.
• Debug checking of correct use of dynamic buffer allocation (i.e. ensure that getBuffer(int32_t) is followed by releaseBuffer() and no other calls occur between the two).

The primary disadvantages of using this wrapper are:

• Only a subset of the UnicodeString API is exposed by WideString.
• Automatic string aliasing of read-only strings as supported by ICU is lost. It is still possible to manually cause a WideString to be an alias of another string, however this removes the guarantee of NULL-terminated buffers.
• Every modification to a WideString invokes two method calls on the UnicodeString (to ensure NULL terminated strings).

The StringWrapper classes are designed to be usable on any platform that ICU is available, however testing has been restricted to Windows and Linux only. It has been released under the MIT Licence, allowing free use in all software (including GPL and commercial).

USAGE SUMMARY

StringWrapper consists of only 2 files:

• StringWrapper.h provides the definition of the classes. Most methods are implemented inline.
• StringWrapper.cpp provides the implementation of some methods.

It is expected that the StringWrapper.h file will be included by another header file that will set up appropriate defines. The following defines are supported:

STRINGWRAPPER_ASSERT	Define this if necessary to be an assert function compatible with assert.h. Buffer and null-termination error checking will only occur when this has been defined.
STRINGWRAPPER_CLASS_API	If the StringWrapper classes are to be exported, define this to be the export for the class definitions.
STRINGWRAPPER_API	If the StringWrapper classes are to be exported, define this to be the export for the functions.
STRINGWRAPPER_NAMESPACE	If this define is set, then the StringWrapper classes will be defined within this namespace. If not defined then they will be part of the global namespace.

MIT LICENCE

The licence text below is the boilerplate "MIT Licence" used from: http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2007-2008, Brodie Thiesfield

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---