C++ in Action: Move your C++ projects to C++Builder 10 Seattle
Date: Wednesday December 9, 2015
Slides for today's webinar. Learn the fastest way migrate your projects to C++Builder 10 Seattle and build/update data-rich, hyper connected, visually engaging applications for Windows 10, Mobile, IoT and more using Standard C++11.
Boost Fertility New Invention Ups Success Rates.pdf
C++ in Action Webinar: Move your C++ projects to C++Builder 10 Seattle
1. C++ in Action Webinar:
Move your C++ projects to C++Builder 10 Seattle
Al Mannarino - al.mannarino@embarcadero.com
David Intersimone - davidi@embarcadero.com
2. Agenda
• Quickly migrate your C++Builder projects to C++Builder 10 Seattle
– Crossing the Unicode Chasm
– C++11 for Windows 32-bit and 64-bit
• Update your UI/UX with the new Windows 10 look and feel
• Add Application Tethering to your existing VCL and FireMonkey apps
• Using the Parallel Programming Library for Mobile and Desktop Apps
• Q&A
3. Migration Effort Depends on What You Currently Use
• The migration effort involves several aspects
– IDE and Plug-Ins
– Projects, Project Options
– Language Features
– Frameworks – VCL and FMX
– Built-In and 3rd Party Components and Libraries
• Technology Partner Directory and GetIt Package Manager
– Unicode (if you are using pre-C++Builder 2009 releases)
• Unicode and Migration Center
• https://www.embarcadero.com/rad-in-action/migration-upgrade-center
4. Clang Enhanced RAD C++ for Windows and Mobile
• C++11 standard for Win32, Win64, iOS and Android
• Precompiled Headers
• RAD PME (Property Method Event)
• Rich RTTI (Run Time Type Information)
• Automatic Reference Counting (ARC) for mobile
4
#include <iostream>
int _tmain(int argc, _TCHAR* argv[])
{
char array[] = {'C', '+', '+', '1', '1'};
for (auto &i : array) {
printf("%c", i);
}
std::cin.get();
return 0;
}
6. C++ Libraries
• Dinkumware STL for Windows / OS X
– v6.50 for bcc64 and bcc32c
– v5.01 for bcc32 and bccosx.
• STL for iOS – included in iOS SDK
• STL for Android – included in SDK/NDK
• Boost for Windows – install using GetIt Package Manager
– Win32 – v1.39
– Win64 - v1.55
6
7. C++ Win32 – Choosing C++11 or Classic C++0x
• Project | Options
– C++ Compiler | Classic Compiler
• Use ‘classic’ Borland compiler
– False = BCC32C (Clang)
– True = BCC32 (C++0x)
• Default = true
7
8. Windows 64-bit
• Introduced in C++Builder XE3
• Windows 64-bit Clang-enhanced C++11 compiler
• Supports VCL and FMX
9. Windows 64-bit
• BCC64 produces 64-bit Windows packages (.bpl files),
beginning in the XE6 release
– You can also do static linking to a 64-bit Windows package
– You can consume packages using C++Builder 64-bit Windows.
• Note that C++Builder does not produce dylibs for the Mac,
or packages for the iOS and Android platforms
– For these platforms, static libraries can be used
10. Windows 64-bit
• size_t is defined as an unsigned integral type
– Win32 and Win64 - this is the same size as a pointer.
– Win32’s "ILP32" data model, int (and long) and pointers are 32-bit.
– In Win64’s "LLP64" data model: long long and pointers are 64-bit,
while int (and long) are still 32-bit.
• The size of LRESULT, WPARAM and LPARAM are 64-bits
• Requires 32-bit design time components for the IDE
11. Windows 64-bit
• _WIN32 is defined (as the integer 1) for both Win32 and
Win64 targets
• _WIN64 is defined only for Win64 targets; because _WIN32
is also defined, check _WIN64 first
• Assembly language programming
– Assembler follows AT&T model
– No mixing of assembly code in a block of Pascal or C++.
– Functions must be written completely in assembly, Pascal, or C++.
12. Windows 32 and 64-bit Built-In Types
http://docwiki.embarcadero.com/RADStudio/Seattle/en/64-bit_Windows_Data_Types_Compared_to_32-bit_Windows_Data_Types
13. Windows 32 and 64-bit Built-In Types
http://docwiki.embarcadero.com/RADStudio/Seattle/en/64-bit_Windows_Data_Types_Compared_to_32-bit_Windows_Data_Types
14. New VCL Controls in C++Builder 10 Seattle
• A great set of new VCL “visual controls”
• Native VCL controls map common Windows 10 UI elements
• 5 new controls – work on Windows 7,8,10
– RelativePanel
– ToggleSwitch
– SearchBox
– SplitView
– ActivityIndicator
14
15. VCL for Windows 10
• New in “10 Seattle”:
Universal Windows Platform integration
• WinRT API mapping and Object Pascal interfaces
– Windows 10 Notifications
– Windows 10 Contracts
15
17. C++ in Action!
C++ Builder 10 Seattle
Unicode Migration
Al Mannarino
Principal Software Consultant
Al.Mannarino@embarcadero.com
@AlMannarino1
18. Agenda – Unicode in C++ Builder
• Unicode in C, C++, Visual Component Library (VCL), WinAPI
• New C and C++ data types for C-style strings
• VCL string classes
• “_TCHAR maps to“ option
• tchar.h
• Converting text to and from Unicode
• Load and Save Unicode characters to files
19. Introduction to Unicode in C++ Builder
• Full Unicode support throughout the VCL and RTL.
• Unicode is critical for internationalization
• Migrating to Unicode
1. You may not have to migrate to Unicode to use C++Builder?
• Code that uses the C runtime library, the STL, or the Windows API (for
example) can continue to use ANSI.
• Convert to Unicode when passing data to or from the VCL.
– migrating only the VCL portion of your code can simplify the task of
upgrading to 10 Seattle.
21. Moving projects from previous versions
Option 1: Open your project files and/or project groups in C++ Builder
– .dpr, .bdsproj, .dprog
– IDE will update the project file
– Re-Build
– Look at any errors and warnings and fix
Option 2: Don't let C++ Builder convert your older projects.
– Copy your files into a new folder
– Create a new project of the same Project type
– And add your source files to it.
– It's a little more effort at first but it saves you a lot later on.
25. AnsiStringT<CodePage> template example
• We pass Cyrillic data from CodePage 1251 to 65001 and
back to Unicode without data loss:
const wchar_t* data = L"Чего я сказать?";
{
// Illustrates handling of Cyrillic data from
// CP 1251 -> CP_UTF8 -> UnicodeString without loss!
AnsiStringT<1251> cp1251Str = data;
assert(cp1251Str.CodePage() == 1251);
UTF8String utf8Str = cp1251Str;
assert(utf8Str.CodePage() == CP_UTF8);
UnicodeString us1 = cp1251Str;
UnicodeString us2(utf8Str);
assert(us1 == us2);
assert(us1 == data);
assert(us2 == data);
}
26. String Handling and Unicode
• string[<1-255>] is known as ShortString in C++.
• String literals - prefixes
– L as in L"This“ – Unicode string that works with the Windows API
– u as in u”This” – UTF-16 string – char16_t string literal
– U as in U”This” – UTF-32 string – same as char32_t string literal
• Length() is a member of UnicodeString/AnsiString/WideString in C++
• use <string>.Length()
• Checking for UnicodeStrings
– UnicodeString::IsLeadSurrogate(int index)
– UnicodeString::IsTrailSurrogate(int index)
27. Unicode in Windows API
• Windows API includes both Unicode and ANSI variants.
– MessageBox
• MessageBoxA - takes ANSI strings
• MessageBoxW - takes wide (UTF-16) strings.
• CharNext(), CharPrev(), and CompareString()
28. New C and C++ data types for C-style strings
• char16_t (example u”Hello, world! u263A”)
• identical semantics to wchar_t
• char32_t (example U"Hello, world! u263A”)
• C++ has AnsiStringT<CodePage> template
– AnsiString = AnsiStringT<0>
– UTF8String = AnsiStringT<65001>
– RawByteString = AnsiStringT<0xffff>
– You can create your own AnsiString types.
29. “_TCHAR maps to“ option
• “wchar_t” – use the Wide Char Windows API calls and data structures
• “char” – use the narrow character Windows API calls and data structures
30. tchar.h
TCHAR defined as
char for non-Unicode builds
wchar_t for Unicode builds
_T, which is removed by the preprocessor for non- Unicode builds and is defined as
L for Unicode builds.
_T("Hello, world!") and the preprocessor converts it to a char literal ("Hello, world!")
wchar_t literal (L"Hello, world!") as appropriate.
wcscat(), wcscpy(), wcscmp(), etc. for Unicode builds
wprintf(), wscanf(), swprintf(), etc. for Unicode builds
fgetwc(), fgetws(), fputwc(), etc. for Unicode builds
_wtoi(), _wtof(),wcstol(), etc. for Unicode builds.
32. Load and Save Unicode characters to files
• LoadFromFile
• SaveToFile
• TEncoding
– Default
– UTF8
– UTF16 (Big & Little Endian)
– Byte Order Mark (BOM) support
– Create descendants for user specific encodings
33. Tips for migrating legacy C++ Builder to 10 Seattle
• VCL functions that used to accept arguments of type char* now require wchar_t*.
• VCL object properties that returned AnsiString now return UnicodeString.
• If the argument is a string constant all you have to do is place the letter L in front of it.
• If you are using type String in code, now maps to UnicodeString and no longer to AnsiString.
• UnicodeString.c_str() returns wchar_t* and AnsiString.c_str() still returns char*.
• Use AnsiOf / UnicodeOf functions instead of replacing all String with AnsiString.
• fopen(AnsiOf(... can easily be replaced by _wfopen(...
• fnsplit(AnsiOf(... can easily be replaced by _wfnsplit(...
• sscanf(UnicodeOf(... can be replaced by swscanf(..
• string functions such as strcpy, etc. all you have to do is replace str with wcs in most cases.
• strncpy(s1, s2, sizeof(s1)-1) gets replaced with wcsncpy(s1, s2, sizeof(s1)/2-1)
• “_TCHAR maps to” wchar_t.
• Replace AnsiCompare, AnsiPos, and AnsiCompareIC with Compare, Pos, and CompareIC
• Plus many more tips…..
34. Summary
Minimal Migration:
1. Check your third-party libraries for 10
Seattle.
2. Convert project to 10 Seattle
3. “_TCHAR maps to” is set to “char.”
4. Replace String with AnsiString.
5. Handle interactions between Unicode VCL
code and your ANSI application code.
6. Look at variadic macros.
• Overview on Unicode in C, C++, VCL and the Windows API.
• Overview on how to migrate a C++Builder application to Unicode.
Complete Migration:
1. Check your third-party libraries for 10 Seattle.
2. Before converting to 10 Seattle:
1. Replace AnsiString with String
2. Mark string literals (“Hello”) with _T macro.
3. Replace C library routines with their tchar.h equivalents.
3. Add C++ typedefs
4. Convert project to 10 Seattle
5. “_TCHAR maps to” is set to “char.”
6. Introduce AnsiString, RawByteString, and
UTF8String
7. Handle ANSI verus Unicode issues
8. Look at variadic macros.
9. Any strings that can indexed or split?
35.
36. AppTethering
• Enhance your existing VCL and FMX apps
• Using app tethering, your applications can easily:
– Discover other applications that are using app tethering
– Run actions remotely
– Share data between applications
36
37. Parallel Programming Libary
• TTask – create one or more parallel tasks
– WaitForAll
– WaitForAny
• TParallel::For – parallel for loop
• TTask::Future – wait for a future value to be set
http://docwiki.embarcadero.com/RADStudio/Seattle/en/Using_the_Parallel_Programming_Library
38. Other Areas to Explore – Watch CodeRageX Replays
• FireDAC for MongoDB
• AppAnalytics
• Beacons and BeaconFence
• BluetoothLE and IoT
• DataSnap
• Embarcadero Mobility Services (EMS)
• Konopka Signature VCL Controls
• CodeSite Studio
• RAD Solution Pack for VCL and FMX
39. Benefits of Moving to C++Builder 10 Seattle
The fastest way to
build visually
engaging apps for
Windows 10, Mac,
and Mobile
Hyper connected
with Bluetooth,
App Tethering,
Beacons, for the
Internet of Things
Incredible Windows
10 support – WinRT
components and
new VCL controls
Twice the power of the IDE, for building larger projects
40. Special Offer – Free RAD Solution Pack
• The RAD Solution Pack is the ultimate collection of VCL tools and components
for C++Builder to enhance your applications and boost your productivity.
• Purchase a new user license or upgrade of RAD Studio 10, or C++Builder 10
Architect between November 11 and December 18, 2015 and receive the VCL
Solution Pack — FREE! Get it all with this incredible promotion.
• No waiting. Receive your free products with your order confirmation!
• Available from the Embarcadero Online Store, an Embarcadero reseller
partner, or Embarcadero Sales.
• See terms and conditions
http://www.embarcadero.com/radoffer
41. Special Offer – Free Konopka VCL Controls and CodeSite
• Purchase a new user license or upgrade of RAD Studio 10 or C++Builder 10
Professional, Enterprise or Ultimate between November 11 and December 18,
2015 and receive Konopka Signature VCL Controls and CodeSite Studio 5.
• No waiting. Receive your free products with your order confirmation!
• Available from the Embarcadero Online Store, an Embarcadero reseller
partner, or Embarcadero Sales.
• See terms and conditions
http://www.embarcadero.com/radoffer
42. Special Offer – Upgrade Price up to 45% off
• Registered users of any earlier version qualify for the upgrade price when they
purchase with Update Subscription
• Purchase version 10 Seattle at the Upgrade price through December 31, 2015
when you purchase with Update Subscription. All earlier version users can
upgrade during this special offer period.
• Available from the Embarcadero Online Store, an Embarcadero reseller
partner, or Embarcadero Sales.
http://www.embarcadero.com/radoffer
43. Special Offer – Free Bonus Pack
• Get these Free Bonuses with your purchase of RAD Studio or C++Builder 10
– VCL and FireMonkey Premium Styles
– Mida Converter Basic
– New Object Pascal Handbook by Marco Cantu
http://www.embarcadero.com/radoffer
Hello and welcome to this C++ in Action Webinar!
My name is AL Mannarino, and I’m one of the Embarcadero Software Consultants.
This session will focus on helping you migrate your legacy C++ Builder Apps to Unicode.
We at Embarcadero are often asked to help migrate legacy C++ Builder code to the current C++ Builder versions, including the current C++ Builder 10 Seattle. So, over time, we have learned tips and techniques to help with your Unicode migration. Once you get a handle on these tips and techniques, developers have reported it didn't take long to convert their applications and the applications migrate fairly smoothly.
A major benefit for migrating to Unicode is to get the full benefits of internationalization, plus you’ll gain all the significant features and enhancements in the newer versions of C++ Builder, like Windows 10 support and being able to create desktop application controls in the style of Windows 10, create FireMonkey Multi-Device apps to deploy to Windows, MacOS X, Android and iOS, C++ 11 and the Clang-based C++ compilers, just to name a few.
Windows 10, Mac, Mobile, IoT and more using Standard C++. Quickly and easily update VCL and FMX applications to Windows 10 with the new Windows 10 VCL Controls, Styles, and Universal Windows Platform services components.
Enjoy an enhanced development experience with double the available memory for large projects, extended multi-monitor support, and enhanced Object Inspector. C++Builder enables developers to deliver applications up to 5x faster across multiple desktop, mobile, cloud, and database platforms including 32-bit and 64-bit Windows 10.
We’ll look at working with Unicode in C++ Builder. As you know, for string data type, C++Builder offers several choices; your code can use C-style characters and strings, or C++ string objects, or VCL String objects, and each of these has its own set of Unicode variations. Also, the Windows API provides both ANSI and Unicode variants.
We’ll look at the new C and C++ data types for C-Style strings (wchar_t, char16_t, char32_t ).
We’ll look at the new Unicode VCL string classes. Starting with RAD Studio 2009, the VCL offers several string classes which support ANSI, UTF-8, and UTF-16 encodings. We’ll see that most member functions of these new VCL string classes operate just the same as they did for the before Unicode String class.
We’’’ look at how to use the “_TCHAR maps to “ option that determines whether or not the UNICODE preprocessor macro is defined, and that determines whether you get the ANSI variant or the wide-string (UTF-16) variant.
We’ll look at the standard Windows header tchar.h that includes macros designed to let you write code that compiles as either ANSI or Unicode. We’ll see how this can help when converting code one portion at a time. We’ll see how this header is valuable to write character-width-agnostic code that can compile as ANSI or Unicode, and that lets you prepare for the migration in your previous versions of C++Builder without breaking compilation.
We’ll look at converting text to and from Unicode, because we need to know how to convert between the various Unicode encodings and the various ANSI encodings. We’ll see the two easiest ways for doing this are using the Windows API and using the VCL.
Lastly, we’ll also look at how to load and save Unicode characters to files, because you can use Unicode characters with VCL components like Tmemo, TListBox, Tcombox, Tedit, etc, so we need if any modifications are needed to our C++ Builder programs to handle Unicode characters for these components.
Since C++Builder 2009, we now have full Unicode support throughout the VCL and RTL.
Unicode is critical for internationalization
Migrating to Unicode will be easier than you think.
The first key realization in migrating to Unicode for C++Builder is this:
You do not have to migrate to Unicode to use C++Builder.
Why do you ask?
C++ is a diverse language, permitting the use of many libraries and several programming paradigms, and while your code that uses the VCL needs to be Unicode-aware, your code that uses the C runtime library, the STL, or the Windows API (for example) can continue to use ANSI and only convert to Unicode when passing data to or from the VCL.
A complete migration to Unicode is necessary to gain the full benefits of internationalization, but migrating only the VCL portion of your code can simplify the task of upgrading to 10 Seattle while letting you gain the significant benefits offered in the current 10 Seattle release.
[such as Windows 10 support and being able to create desktop application controls in the style of Windows 10, create FireMonkey Multi-Device apps to deploy to Windows, MacOS X, Android and iOS, C++ 11 and the Clang-based C++ compilers, just to name a few.
Windows 10, Mac, Mobile, IoT and more using Standard C++. Quickly and easily update VCL and FMX applications to Windows 10 with the new Windows 10 VCL Controls, Styles, and Universal Windows Platform services components.
Enjoy an enhanced development experience with double the available memory for large projects, extended multi-monitor support, and enhanced Object Inspector. C++Builder enables developers to deliver applications up to 5x faster across multiple desktop, mobile, cloud, and database platforms including 32-bit and 64-bit Windows 10].
Whether you choose to make your entire application Unicode-aware or to upgrade only the portions that interact with the VCL, we’ll discuss several C and C++ development techniques that can make the task much easier.
For a C++ Builder Unicode Migration resource to start with, if you have not read it already, take a look at this Migrating legacy C++ Builder Apps to C++ Builder 10 Seattle blog post on our Embarcadero Community WebSite: http://community.embarcadero.com/blogs/entry/migrating-legacy-c-builder-apps-to-c-builder-10-seattle
It provides tips and techniques to help with your C++ Builder migration working with Unicode in C, C++, and the VCL.
Once you get a handle on these tips, C++ Builder customers have reported it didn't take long to migrate than a day to convert a project with about 60,000 lines of code.
To move your legacy C++ Builder Apps to C++ Builder 10 Seattle, you have two options. Option 1 is to just open your old project files and/or project groups in C++ Builder, the IDE will update the project file. Rebuild the project. Looks at any compile and/or link errors or warnings and fix as needed.
Or you have Option #2, which is what I recommend. Don't let C++ Builder convert your older projects.
Instead, copy your source files into a new folder.
In C++ Builder 10 Seattle, create a new project of the same Project type.
And then start adding your source files to the new project.
It is a little more effort at first, doing it this way, but it will save you a lot later on.
Looking at Unicode in C, here are samples C with examples of Unicode literals, escape codes, and preprocessor macros.
C developers are used to using <string.h> functions such as strlen(), (stir length), strcpy(), (Stir copy) and strcat() (stir cat) to manipulate C-style strings.
In Unicode, there are corresponding functions for manipulating C-style wchar_t strings. Most wchar_t functions are defined both in <wchar.h> (wide char header) and in the “traditional” header file (<string.h> for plain string manipulation, using <stdio.h> (standard IO) for I/O, etc.).
- For wchar_t string manipulation, use wcslen(), wcscpy(), wcscat(), and so on. (Replace “str” with “wcs”.) Wide String Copy (wcs)
- For wchar_t file I/O, use functions like fgetws() and fputwc() instead of fgets() and fputc(). (Insert “w” before the data type.)
- printf(), sscanf(), and so on become wprintf(), swscanf(), and so on. (Insert “w” before “printf” or “scanf”.) Take note to not confuse swprintf() (wide character sprintf()) with wsprintf() (the Windows implementation of sprintf()).
- File and directory manipulation functions, such as fopen(), opendir(), mkdir(), and _unlink(), become _wfopen(), _wopendir(), _wmkdir(), and _wunlink(). (Add “_w” to the beginning.) These let you manipulate files and directories with Unicode characters in their names.
Format specifiers for wprintf and wscanf.and wscanf.
For Unicode in C++,
String manipulation in C++ generally involves the use of the std::string class, as well as the various <iostream> classes for input, output, and string buffering.
Developers familiar with Boost may also use classes such as boost::regex or boost::format to help with string manipulation.
As it turns out, like we see in the code in this slide, switching to the wchar_t version of these classes is quite easy. All you need to do is just prefix a w to each class name.
This code shows sample char string code in C++ and its corresponding wchar_t code. We see a string becomes a wstring and a stringstream becomes a wstringstream.
Most text-related classes (including <iostream>) in the C++ Standard Library and in Boost are actually typedefs for template classes.
For example, std::string is actually a typedef for std::basic_string<char>, and std::wstring is a typedef for std::basic_string<wchar_t>.
Because std::basic_string is a template, it can be instantiated on any char-like data type that you wish. This means that, if you need to work with C++0x‘s char16_t or char32_t data types, you can use std::basic_string<char16_t> instead of std:: string, use std::basic_fstream<char32_t> instead of std::fstream, and so on.
Looking at Unicode in VCL, we see the VCL offers these six (6) string classes which support ANSI, UTF-8, and UTF-16 encodings:
- AnsiString corresponds to the old String class. It contains 8-bit (char) data in the system default code page.
- UnicodeString is the new class, containing 16-bit (wchar_t) data in the UTF-16 encoding.
- WideString still exists from previous versions of RAD Studio. It corresponds to COM‘s BSTR data type and contains 16-bit (wchar_t) data like UnicodeString. Because UnicodeString uses C++Builder‘s own memory management and reference counting, it‘s often faster than WideString, so unless you need easy interoperability with COM, you should use the new UnicodeString class.
- AnsiStringT is a class template that contains 8-bit (char) data encoded in any code page; the code page is given as the template parameter. (AnsiString is actually a typedef for AnsiStringT<0>.) The requirement that the code page be given as a template parameter prevents you from using AnsiStringT with arbitrary code pages at runtime, so if you need that capability, you may need to instead use RawByteString (below) or use one of the C or C++ string manipulation methods instead of using the VCL.
- UTF8String is an AnsiStringT instantiation using the UTF-8 encoding.
- RawByteString contains 8-bit (char) data in an unspecified code page. The VCL will avoid applying any code page conversions to RawByte- Strings; it becomes the calling code‘s responsibility to correctly handle code pages issues. Using RawByteString can have several advantages: since each code page is otherwise a separate compile- time type, RawByteString lets you write a single routine that can handle any code page; it removes any VCL overhead of doing code page conversions itself; and it prevents possible loss of data from automatically converting text data into encodings that can‘t represent some characters.
Good news is most member functions of these new string classes operate just the same as they did for the old non-Unicode String class, before C++ Builder 2009.
The printf-type methods (printf(), sprintf(), vprintf(), cat_printf(), cat_sprintf(), and cat_sprintf()) deserve special mention.
Like C‘s wprintf() and wscanf() functions, their treatment of the “%s” and “%c” format specifiers depends on whether they‘re called on an AnsiString or UnicodeString instance.
Refer back to Table 1 for details - Format specifiers for wprintf and wscanf.and wscanf.
Here’s an example on using the AnsiStringT<CodePage> template to pass Unicode Cyrillic data from CodePage 1251 to 65001 and back to Unicode without data loss. That’s very cool!
Windows-1251 is a popular 8-bit character encoding, designed to cover languages that use the Cyrillic script such as Russian, Bulgarian, Serbian Cyrillic and other languages. It is the most widely used for encoding the Bulgarian, Serbian and Macedonian languages
CodePage 65001 is Unicode (UTF-8)
Here some useful String Handling and Unicode with C++
- A ShortString string occupies as many bytes as its maximum length plus one. The first byte contains the current dynamic length of the string, and the following bytes contain the characters of the string.
The length byte and the characters are considered unsigned values. The maximum string length is 255 characters plus a length byte (string[255]).
String literals – prefixes, here’s examples on how to use capital L, lowercase u and uppercase U, for Unicode, UTF-16 and UTF-32 string literals.
Length() is a member of UnicodeString/AnsiString/WideString in C++ And you use <string>.Length(), for the length of the string.
Not sure if these are still methods?
SubStr in C++:
AnsiString::SubStr(...)
UnicodeString::SubStr(...)
SubString in C++ works the same with AnsiString and UnicodeString.
System::UnicodeString::SubString returns a new System::UnicodeString instance that is a substring of this System::UnicodeString instance. The substring contains count characters beginning at index, which is a character index.
For checking for UnicodeStrings, you can use:
System::UnicodeString::IsLeadSurrogate – That returns true if the indexed element is a lead surrogate and false otherwise.
System::UnicodeString::IsTrailSurrogate – That returns true if the indexed element is a trail surrogate and false otherwise.
With both methods, the index is an element index into the string, not a character or byte index.
Looking at Unicode in Windows API.
The Windows API includes both Unicode and ANSI variants.
For example, the MessageBox function is actually two different functions: MessageBoxA, which takes ANSI strings, and MessageBoxW, which takes wide (UTF-16) strings. MessageBox itself is a macro that resolves to MessageBoxA or MessageBoxW depending on your preprocessor macros and project options.
You‘re also free to explicitly call one API variant or the other, regardless of your project options, simply by calling MessageBoxA or MessageBoxW directly.
Other Windows API functions dealing with text or string data have similar variants.
Which variant you get is determined by whether or not the UNICODE preprocessor macro is defined.
In C++Builder, this macro is automatically defined depending on your project‘s options. In upcoming slides, well see how you can change the UNICODE preprosesssor macro using the “_TCHAR maps to” option.
To change this option from the IDE, go under the Project | Options | C++ (Shared Options) | “_TCHAR maps to ” option.
If it‘s set to “char”, then the UNICODE preprocessor macro is left undefined and the ANSI variant of the Windows API is used.
If it‘s set to “wchar_t”, then the UNICODE macro is defined and the wide-string (UTF-16) variant of the Windows API is used.
And we’ll also see in a moment how the UNICODE macro also affects the use of standard Windows tchar.h in writing code that can compile as ANSI or Unicode.
Lastly on this slide, the Windows API also includes functions such as CharNext(), CharPrev(), and CompareString() that are capable of dealing with complexities such as composite characters and surrogate pairs.
So all of this is good!
Working with Unicode introduces several more C and C++ data types for C-style strings. I mentioned these previous under Unicode in C, and Unicode in VCL, but they also apply to C++, just to be complete.
char16_t, char32_t: specifies the two new character types for holding UTF-16 and UTF- 32 data, respectively.
char16_t values are written as u"Hello, world! \u263A".
char32_t values are written as U"Hello, world! \u263A".
Lastly, C++ has AnsiStringT is a class template that contains 8-bit (char) data encoded in any code page; the code page is given as the template parameter.
(AnsiString is actually a typedef for AnsiStringT<0>.) The requirement that the code page be given as a template parameter prevents you from using AnsiStringT with arbitrary code pages at runtime, so if you need that capability, you may need to instead use RawByteString as we see on this slide.
And, if needed, you can create your own AnsiString types.
In the C++ Builder IDE, the “_TCHAR maps to“ option controls the floating definition of _TCHAR.
The choices are:
wchar_t (this is the typical default; for C++ applications that use the VCL or FireMonkey)
or
char (this is the default for C++ applications that do not use the VCL or FireMonkey, such as C++ console applications)
Before you can set this option to wchar_t, your project must have an entry point called _tmain or _tWinMain.
New projects (created with RAD Studio) have these entry points by default, but imported projects might need to have these entry points added by hand.
And that’s another reason, when you are migrate your legacy projects to the newer 10 Seattle, to first create a NEW Project (VCL or FireMonkey), and then copy your source code into the new project.
Selecting wchar_t does the following:
- Sets the UNICODE and _UNICODE defines.
- Instructs the linker to use a library of wide versions.
- Instructs the C++ RTL, standard library, and Windows API functions to float to their wide definitions.
If you select char, _TCHAR does not float to a wide definition.
To change this option from the IDE. It’s under the Project | Options | C++ (Shared Options) | the “_TCHAR maps to ” option.
If it‘s set to “char”, then the UNICODE preprocessor macro is left undefined and the ANSI variant is used.
If it‘s set to “wchar_t”, then the UNICODE macro is defined and the wide-string (UTF-16) variant is used.
Also, when set to “wchar_t”, the core header file, tchar.h, defines the macros for Unicode builds, and in writing code that can compile as ANSI or Unicode.
We’ll see using the tchar.h in the next slide.
So, for C++ code that interacts with the Windows API and VCL is better off with having _TCHAR set to wchar_t.
In Summary:
Setting “_TCHAR maps to” to wchar_t gives you:
1. UNICODE and _UNICODE macro defined by compiler internally
2. <tchar.h> - the core header that this feature backs and all the _txxxx symbols it offers.
3. main()/WinMain() being renamed [users have to do that explicitly for their old projects]
4. VCL now defaults to the 'W' flavor of Windows API/Structures. This means that C++ code that interacts with Windows API and VCL is better off with _TCHAR set to wchar_t.
The UNICODE macro also affects the use of the standard Windows header tchar.h (that we’ll look at soon) in writing code that can compile as ANSI or Unicode.
How to use the Windows tchar.h header file with Unicode?
It can be valuable to write character-width-agnostic code that can compile as ANSI or Unicode.
If you‘re planning on a complete Unicode migration as part of an upgrade to C++Builder 10 Seattle, character-width-agnostic code lets you prepare for the migration in your previous version of C++Builder without breaking compilation.
If portions of your C++ code base are cross platform, you may want those portions to use wide characters (UTF-16) on Windows but narrow characters (ANSI or UTF-8) on other platforms.
Windows provides the tchar.h header file to help with this.
Depending on whether the _UNICODE preprocessor macro is defined (as we just discussed in the last slide by setting C++Builder‘s “_TCHAR maps to” option), tchar.h defines the following macros for Unicode builds.
TCHAR, which is defined as char for non-Unicode builds and wchar_t for Unicode builds
_T, which is removed by the preprocessor for non- Unicode builds and is defined as L for Unicode builds. This means that you can write _T("Hello, world!") and have the preprocessor convert it to a char literal ("Hello, world!") or wchar_t literal (L"Hello, world!") as appropriate.
_tcscat(), _tcscpy(), _tcscmp(), etc., which are defined as strcat(), strcpy(), strcmp(), etc. for non-Unicode builds and wcscat(), wcscpy(), wcscmp(), etc. for Unicode builds
_tprintf(), _tscanf(), _stprintf(), etc., which are defined as printf(), scanf(), printf(), etc. for non-Unicode builds and wprintf(), wscanf(), swprintf(), etc. for Unicode builds
_fgettc(), _fgetts(), _fputtc(), etc., which are defined as fgetc(), fgets(), fputc(), etc. for non-Unicode builds and fgetwc(), fgetws(), fputwc(), etc. for Unicode builds
_ttoi(), _ttof(), _tcstol(), etc., which are defined as atoi, atof(), strtol(), etc. for non- Unicode builds and _wtoi(), _wtof(),wcstol(), etc. for Unicode builds.
Let’s take a look at an application that uses _TCHAR Maps to and the tchar.h to get a betting understanding on how to use them..
Macros are also provided for file- and directory- manipulation functions (so that you can manipulate ANSI or Unicode filenames as appropriate). See include\ tchar.h for a complete list of available macros. Using these macros is very simple:
TCHAR buffer[100];
_tcscpy(buffer, _T("Hello"));
_tcscat(buffer, _T(" world!"));
As we are getting to the end of this session, let me give you this one more tip from the blog post I mentioned earlier on “Migrating legacy C++ Builder Apps to C++ Builder 10 Seattle”.
For Unicode migration, many folks suggest replacing all occurrences of String with AnsiString.
We believe it’s better to don’t replace all occurrences of String with AnsiString, but instead define these two functions,
and use them wherever one type is returned and the other type is required and vice versa.
NOTE: Careful: what makes these functions convenient to use, i.e. the static buffer, can also cause undesired behavior.
Make sure AnsiOf/UnicodeOf is not called as an argument of a function that may itself call AnsiOf/UnicodeOf, or that AnsiOf/UnicodeOf is not used for two or more arguments of the same function.
With these two functions, we are using two Windows API functions; WideCharToMultiByte(), which converts from UTF-16 to the encoding of your choice (UTF-8 or any of the various ANSI encodings); and MultiByteToWideChar(), which converts from the encoding of your choice to UTF-16. You can look at the Microsoft documentation on these functions.
The last item we’ll look at is, How do I deal with the loading and saving of Unicode items? How do I work with the Encoding and Decoding?
For Example, if we are using a ListBox, how can I Save and Load the items from a file?
For the LoadFromFile and the SaveToFile methods, you have a second parameter, with is the Tencoding class.
The Tencoding class has a static property where you can specify the encoding, either ASCII or UTF-8 or UNICODE or Unicode Big Endian.
Note: If you don’t supply the second Tencoding parameter, then it’s a NULL Pointer, and in the run time, if he sees a NULL pointer, it will use DEFAULT encoding. DEFAULT encoding will be whatever the desktop you are running on, such as Japanese, Chinese, or a USA desktop, or whatever you set the codepage for your application, then it will use that encoding.
But if you want to control it and you know you are going to put Unicode characters in a ListBox ot Memo or DBMemo or dealing with Unicode characters in a database in a TEXT or BLOB field, then you’ll want to take control of the encoding.
If you look at the Tencoding class, it comes from System.SYSUtils.hpp, it’s a DELPHI class with different field types like:
Default – users’ active CodePage
UTF8
UTF16 (Big & Little Endian)
Byte Order Mark (BOM) support
Create descendants for user specific encodings
Let’s run an app and see how we use Tencoding to SaveToFile and Load From File.
For additional tips and techniques on migrating your legacy C++ Builder code to 10 Seattle, start with the blog post I mentioned a few times called “Migrating legacy C++ Builder Apps to C++ Builder 10 Seattle” on the community.embarcadero.com/blogs website.
It offers tips and techniques like we see on this side, plus many more….
All VCL functions that used to accept arguments of type char* (for example Application->MessageBox) now require wchar_t*.
VCL object properties that returned AnsiString now return UnicodeString (for example Label->Caption).
If the argument is a string constant all you have to do is place the letter L in front of it. It is more difficult if you are passing a variable as an argument.
If you are using the type String in your code it now maps to UnicodeString and no longer to AnsiString.
UnicodeString.c_str() returns wchar_t* and AnsiString.c_str() still returns char*.
Plus many more tips….
This ends what we had time to cover for this session on C++ Builder Unicode Migration. Hopefully it gave you an overview of Unicode in C, C++, Visual Component Library (VCL) and the Windows API,
And an Overview on how to migrate a C++ Builder application to Unicode, and provided some useful tips and techniques for doing the migration.
For an overview approach for migrating your application to C++Builder 10 Seattle:, here’s what you can do for a Minimal Migration and a Complete Migration.
And remember, Embarcadero is here is help, so let us know any any Unicode Migration Issues you are having, and we should be able to help!
1. Check your third-party libraries and make sure that they‘re compatible with C++Builder 10 Seattle.
2. Before switching to C++Builder 10 Seattle:
a. Replace AnsiString with String.
b. Mark string literals (“Hello”) with tchar.h‘s _T macro.
c. Replace C library routines with their tchar.h equivalents.
3. Add C++ typedefs such as tstring so that C++ string manipulation will work after the switch to Unicode.
4. Convert your project to C++Builder 10 Seattle. Under Project |Options, C++ (Shared) | “_TCHAR maps to” is set to “wchar_t.”
5. Introduce AnsiString, RawByteString, and UTF8String in places where you need to continue to manipulate narrow character text.
6. Use string shims, C++ overloading, and similar techniques as needed to handle remaining ANSI versus Unicode issues.
7. Run the type-safe printf() transformer on your code to catch any issues with variadic macros.
8. Review your code for places where you assume that strings can be arbitrarily indexed or split; this is no longer the case with Unicode.
Gradually switch to Unicode, as time and business cases permit, to gain the full benefits of Unicode.
Hope this helps in your migrations.
Please let me know what specific C++ Builder Unicode issues you are having.
Embarcadero is here to help!
For Additional Resources for Migrating legacy C++ Builder, please visit the blog post “Migrating legacy C++ Builder Apps to C++ Builder 10 Seattle” on the community.embarcadero.com/blogs website, and you will see all these additional resources to help with your migration.
Hope this helps in your migrations.
Please let me know what specific C++ Builder Unicode issues you are having. Embarcadero is here to help!
