StringConvertor : A convertor class for managed-unmanaged string conversions that handles memory de-allocations

• Download source - 1.82 Kb

Contents

• Overview

• Class Reference

• Class usage tips

• Design notes

• Conclusion

• History

Overview

This article presents a C++/CLI class StringConvertor which can be used to make conversions between System::String and native types like a char*, BSTR etc. The class keeps track of allocated unmanaged memory handles and frees them automatically, so the caller needn't worry about freeing up unmanaged resources.

The class has several constructor overloads that accept various native types (as well as managed types) like char*, __wchar_t* etc and internally maintains a System::String object that can be extracted using the String operator or the ToString override. There are also various properties each exposing a native type like char*, BSTR etc which can be used to convert the string to your preferred unmanaged type.

The class reference follows with suitable examples. Make sure you read the Class usage tips section at the end though.

[Back to Contents]

Class Reference : StringUtilities::StringConvertor

Namespace

The StringConvertor class is declared in the StringUtilities namespace.

Constructors

String^ str1 = "Hello world";
StringConvertor sc1(str1);

const char* str2 = "Apples and oranges";
StringConvertor sc2(str2);

const __wchar_t* str3 = L"Apples and oranges";
StringConvertor sc3(str3);

array<Char>^ str4 = {'H', 'e', 'y', '.'};
StringConvertor sc4(str4);

BSTR str5 = SysAllocString(L"Interesting");
StringConvertor sc5(str5);
SysFreeString(str5);

std::string str6 = "STL is kinda handy";
StringConvertor sc6(str6);

std::wstring str7 = L"STL is kinda handy";
StringConvertor sc7(str7);

Methods

StringConvertor sc1(str1);
int len = sc1.ToString()->Length;
Console::WriteLine(len);

Operators

StringConvertor sc1(str1);
Console::WriteLine(sc1); //Operator String^ invoked

Properties

All properties in the class are read-only.

interior_ptr<const Char> p1 = sc1.InteriorConstCharPtr;
for(interior_ptr<const Char> tmp=p1; *tmp; tmp++)
    Console::Write(*tmp);

interior_ptr<Char> p2 = sc2.InteriorCharPtr;
for(interior_ptr<Char> tmp=p2; *tmp; tmp++)
    if(Char::IsLower(*tmp)) //swap case
        *tmp = Char::ToUpper(*tmp);
    else
        *tmp = Char::ToLower(*tmp);        
Console::WriteLine(sc2);

char* p3 = sc1.NativeCharPtr;
printf("%s \r\n", p3);

__wchar_t* p4 = sc1.NativeWideCharPtr;
printf("%S \r\n", p4);

LPTSTR p5 = sc1.NativeTCharPtr;
_tprintf(_T("%s \r\n"),p5);

array<Char>^ arr1 = sc5.CharArray;
for each(Char c in arr1)
    Console::Write(c);

BSTR b1 = sc5.BSTRCopy;
printf("BSTR contains %S \r\n", b1);

BSTR b1 = sc5.BSTRCopy;
b1[0] = L'X';
BSTR b2 = sc5.BSTRCopy;

std::string s1 = sc5.STLAnsiString;
printf("%s \r\n", s1.c_str());

std::wstring s2 = sc5.STLWideString;
printf("%S \r\n", s2.c_str());

[Back to Contents]

Class usage tips

Two of the primary purposes of the class are (1) to make it easy to convert from System::String to unmanaged types and vice-versa and (2) to free the user from the responsibility of freeing up the unmanaged memory allocations. The various properties and constructors handle the first role and the destructor handles the second one. When I say destructor, I mean destructor (not the finalizer), which means the destructor needs to get called as soon as the object goes out of scope or has served its purpose. For that, it's recommended that you either use the auto-variable non-handle declaration format or explicitly call delete on the StringConvertor object after use.

void SomeFunc(...)
{
    StringConvertor s1(...);

    //...

} //Destructor gets called

or

StringConvertor^ s1 = gcnew StringConvertor(...);

//...

delete s1; //Destructor gets called

Try to avoid making a StringConvertor a member of a long-living class (or better still, never make it a class-member). Always try and limit the scope and life-time of StringConvertor objects. While, a finalizer has been provided (for unanticipated circumstances), ideally, the finalizer should never need to be called. To help you with avoiding this, in debug builds, an exception gets thrown if the finalizer is ever called and in release builds, Trace::WriteLine is used to write a warning message to any active trace listeners.

When you have functions returning unmanaged strings (like a char*), you need to make sure that the pointer you return is allocated by you separately (since the pointer returned by StringConvertor will be freed when the StringConvertor goes out of scope. The snippets below show two functions, one returning a BSTR and the other returning a char*.

BSTR ReturnBSTR(String^ s)
{
    return SysAllocString(StringConvertor(s).BSTRCopy);
}

char* ReturnCharPointer(String^ s)
{
    StringConvertor sc(s);
    char* str = new char[sc.ToString()->Length + 1];
    strcpy(str, sc.NativeCharPtr);
    return str;
}

And when you've done using the strings returned by these functions, you need to free the pointers manually.

BSTR s = ReturnBSTR(gcnew String("Hello there"));
printf("%S \r\n",s);
SysFreeString(s);

char* str = ReturnCharPointer(gcnew String("Hello again"));
printf("%s \r\n",str);
delete[] str;

[Back to Contents]

Design notes

Most of the data conversions make use of the Marshal class from the System::Runtime::InteropServices namespace. Now most of these functions allocate memory in the native heap and the class uses two vector<> objects to keep track of all allocated memory handles. One vector<> stores all the pointers that need to be freed using Marshal::FreeHGlobal while the other one stores all the BSTR pointers that need to be freed using Marshal::FreeBSTR. The initialization and clean-up of these vectors is done by the StringConvertorBase class which is an abstract ref class that's the base class for the StringConvertor class.

Initially, I had designed the class so that the unmanaged pointers are cached, so that multiple calls to any of the properties that returned pointers to the native heap always returned the cached pointer. But I soon saw that this meant that, if the caller modifies data using one of these pointers, it dirties the internal state of the StringConvertor object which was obviously something that should not be allowed. Considering that, managed-unmanaged transitions should not be over-used and that in most frequent situations, the required life-time of the unmanaged data is very small, usually for making a function call, I assumed that any user of this class with any level of adequacy as a programmer would never abuse the class to such an extent that there'd be lots of unmanaged memory lying un-freed. So the vectors and the unmanaged pointers/handles they contain are freed up in the class destructor (as well as in the finalizer as a safety measure).

As earlier mentioned, if for any reason, you want to change the internal string of the StringConvertor object, use the InteriorCharPtr property and write to the buffer directly - but be very careful how you use it.

Why I left CString out?

Conversions to CString and from CString are so trivial, that it didn't make sense to add them to this class.

CString str("Hello");
String^ s = gcnew String(str); //CString to String
CString strnew(s); //String to CString

[Back to Contents]

Conclusion

I believe I've covered all the basic data types and that these types can be used to create any other more complex data types. For example, the BSTR can be used to make a CComBSTR or a _bstr_t, while the char* (or __wchar_t*) can be used to make a CString.

Suggestions and feedback are welcome.

[Back to Contents]

History

• May 15, 2005 : Class completed and article first published on The Code Project

[Back to Contents]