Training
Module
Modify the content of strings using built-in string data type methods in C# - Training
Explore using the built-in string data type methods in C# to modify strings.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
The ATL class CComBSTR provides a wrapper around the BSTR data type. While CComBSTR
is a useful tool, there are several situations that require caution.
Although several CComBSTR
methods will automatically convert an ANSI string argument into Unicode, the methods will always return Unicode format strings. To convert the output string back to ANSI, use an ATL conversion class. For more information on the ATL conversion classes, see ATL and MFC String Conversion Macros.
// Declare a CComBSTR object. Although the argument is ANSI,
// the constructor converts it into UNICODE.
CComBSTR bstrMyString("Hello World");
// Convert the string into an ANSI string
CW2A szMyString(bstrMyString);
// Display the ANSI string
MessageBoxA(NULL, szMyString, "String Test", MB_OK);
If you're using a string literal to modify a CComBSTR
object, use wide character strings to reduce unnecessary conversions.
// The following converts the ANSI string to Unicode
CComBSTR bstr1("Test");
// The following uses a Unicode string at compile time
CComBSTR bstr2(L"Test");
As with any well-behaved class, CComBSTR
will free its resources when it goes out of scope. If a function returns a pointer to the CComBSTR
string, this can cause problems, as the pointer will reference memory that has already been freed. In these cases, use the Copy
method, as shown below.
// The wrong way to do it
BSTR * MyBadFunction()
{
// Create the CComBSTR object
CComBSTR bstrString(L"Hello World");
// Convert the string to uppercase
HRESULT hr;
hr = bstrString.ToUpper();
// Return a pointer to the BSTR. ** Bad thing to do **
return &bstrString;
}
// The correct way to do it
HRESULT MyGoodFunction(/*[out]*/ BSTR* bstrStringPtr)
{
// Create the CComBSTR object
CComBSTR bstrString(L"Hello World");
// Convert the string to uppercase
HRESULT hr;
hr = bstrString.ToUpper();
if (hr != S_OK)
return hr;
// Return a copy of the string.
return bstrString.CopyTo(bstrStringPtr);
}
It is possible to explicitly free the string contained in the CComBSTR
object before the object goes out scope. If the string is freed, the CComBSTR
object is invalid.
// Declare a CComBSTR object
CComBSTR bstrMyString(L"Hello World");
// Free the string explicitly
::SysFreeString(bstrMyString);
// The string will be freed a second time
// when the CComBSTR object goes out of scope,
// which is invalid.
As the CComBSTR
class allocates a buffer to perform certain operations, such as the +=
operator or Append
method, it is not recommended that you perform string manipulation inside a tight loop. In these situations, CStringT
provides better performance.
// This is not an efficient way to use a CComBSTR object.
CComBSTR bstrMyString;
HRESULT hr;
while (bstrMyString.Length() < 1000)
hr = bstrMyString.Append(L"*");
Passing the address of an initialized CComBSTR
to a function as an [out] parameter causes a memory leak.
In the example below, the string allocated to hold the string "Initialized"
is leaked when the function MyGoodFunction
replaces the string.
CComBSTR bstrLeak(L"Initialized");
HRESULT hr = MyGoodFunction(&bstrLeak);
To avoid the leak, call the Empty
method on existing CComBSTR
objects before passing the address as an [out] parameter.
Note that the same code would not cause a leak if the function's parameter was [in, out].
Training
Module
Modify the content of strings using built-in string data type methods in C# - Training
Explore using the built-in string data type methods in C# to modify strings.