Persisting Strings

The CVL persistence mechanism allows you to archive objects of type std::string and std::wstring.

Note: ccCvlString is a typedef of std::string for ANSI mode builds and std::wstring for Unicode mode builds.

Whenever you store a std::string (including a ccCvlString string in ANSI build mode) to a CVL archive, the 8-bit string is converted to a Unicode representation before it is written to the archive. This conversion is performed using the current C-runtime locale of your application. If the conversion cannot be performed using the current C-runtime locale, a ccBadUnicodeChar error is thrown.

CVL archives may contain two types of archived std::string objects.

In CVL archives created using versions of CVL prior to 7.1, std::string objects are archived as 8-bit strings. When std::string objects are loaded from these archives, the archived bytes are loaded without any processing.
In CVL archives created using CVL versions 7.1 and newer, std::string objects are archived as Unicode strings (as noted above). When std::string objects are loaded from these archives, the archived Unicode string is converted to an 8-bit representation using the current C-runtime locale of your application. If the conversion cannot be performed using the current C-runtime locale, a ccBadUnicodeChar error is thrown.

The persistence mechanism allows you to load an archived std::string into a std::wstring object as well as loading an archived std::wstring into a std::string object.

As shown in the table below, depending on the direction of the conversion and the type of archive, this may require an ANSI-to-Unicode conversion. This conversion is performed using your application’s current C-runtime locale setting. If the conversion cannot be performed, the system will throw ccBadUnicodeChar.

	Object Stored in Archive
Load into a std::string	Archive contains Unicode String is converted to 8-bit using C-runtime locale. Throws if conversion can’t be performed.	Archive contains Unicode String is converted to 8-bit using C-runtime locale. Throws if conversion can’t be performed.	Archive contains 8-bit data String is loaded into object as-is.
Load into a std::wstring	Archive contains Unicode String is loaded into object as-is.	Archive contains Unicode String is loaded into object as-is.	Archive contains 8-bit data String is converted to Unicode using C-runtime locale. Throws if conversion can’t be performed.

Object Stored in Archive

std::string

std::wstring

std::string
(pre-CVL 7.1 Archive)

Load into a

std::string

Archive contains Unicode

String is converted to 8-bit using C-runtime locale.

Throws if conversion can’t be performed.

Archive contains Unicode

String is converted to 8-bit using C-runtime locale.

Throws if conversion can’t be performed.

Archive contains 8-bit data

String is loaded into object as-is.

Load into a std::wstring

Archive contains Unicode

String is loaded into object as-is.

Archive contains Unicode

String is loaded into object as-is.

Archive contains 8-bit data

String is converted to Unicode using C-runtime locale.

Throws if conversion can’t be performed.

Archive string conversion

The conversion rules shown in the table above apply to both ANSI-mode and Unicode-mode applications.