Welcome to the November 2004 edition of Riverace's ACE News and Tips newsletter. This issue contains an explanation of ACE's character-width facilities, news about what's coming up in the next ACE release, and a note about the latest ACE Fix Kit releases.

Please forward this newsletter to anyone you think may be interested! Anyone who wishes to receive their own copy of this newsletter can subscribe at http://www.riverace.com/subscribe2/index.mv. If you no longer wish to subscribe, removal directions are at the bottom of this page.

Please reply with any feedback you have on this newsletter, as well as ideas for information you'd like to see in upcoming newsletters. We want to be as helpful as possible, so please let us know how we can do that.

ACE Tip: Proper Use of ACE's Text-Width Macros and Types

Windows programmers tend to be more familiar with wide-character usage than do UNIX/POSIX programmers because of Windows' prominent use of UNICODE. However, UNIX/POSIX platforms offer support for wide-character usage as well, and it is becoming more and more necessary to understand how to make use of both narrow and wide characters as international markets for software expand. As usual, ACE offers a lot of support for your efforts in this area.

Background

APG chapter 1 contains background information on wide characters, but I'll summarize here. C (and C++) programmers are usually trained in the use of the char type for text character data. A char is a single byte but many languages in the world use character sets that require more than one byte to represent a character, hence the need for "wide characters". Some common character sets are ISO 10646 and UNICODE. To make text programming with wide characters possible, there is a native wchar_t type which represents a wide character. A wchar_t is usually either 2 or 4 bytes but it could be other sizes as well; it's a platform-specific detail. There is a set of system library functions to manipulate wide-character strings, analogous to those for narrow characters (strcpy(), printf(), etc.). However, unlike the narrow-character functions, the wide-character functions evolved more recently and are not uniform across all platforms. ACE's string manipulation methods in the ACE_OS namespace allow you to pass either narrow or wide characters, though, so you can manipulate strings of either width across all platforms that support both.

Configuration and Wide Character Capability

There are two dimensions to configuration for wide-character capability and use. The following two configuration macros can be placed in your config.h file before building ACE and your applications:

1. ACE_HAS_WCHAR. This indicates that the platform has compiler and system function support for wide characters. For example, the wchar_t type is valid. If you need a way to decide at compile time whether or not wide character capabilities in ACE are available, it's best to check for the presence of ACE_HAS_WCHAR.
2. ACE_USES_WCHAR. This indicates that the ACE types that allow switching between narrow and wide characters will be wide characters. When built with this option, ACE's internal character strings are wide, and the "switchable" character width type (more on this below) is wide.

Switching Between Narrow and Wide Characters

If your code needs to be buildable for both narrow and wide character environments, it can be very hard to decide how to program this in a way that doesn't make maintenance a burden. You wouldn't want to find every variable and class member declaration using character data and change between char and wchar_t for different builds. ACE offers the following facilities to make program coding and maintenance easier:

• ACE_TCHAR data type. ACE_TCHAR is a char when the ACE_USES_WCHAR configuration setting is not used, and it is a wchar_t when ACE_USES_WCHAR is set. You can use ACE_TCHAR to declare any character variable or member that needs to adapt to narrow or wide character usage.
• ACE_TEXT(string) macro. The syntax for defining literal characters and strings are also different for narrow and wide characters. ACE_TEXT helps your code adapt to use in either environment. For example, to use a string literal, you could use something like:

  const ACE_TCHAR *str = ACE_TEXT("string literal");

Converting Strings Between Different Character Widths

There are many string-using ACE methods defined with both char and wchar_t types. Others are defined in terms of ACE_TCHAR to switch depending on the setting of ACE_USES_WCHAR. When you have a need to convert strings between character widths, or make sure that a string is always in a certain width, ACE offers the following macros:

• ACE_TEXT_CHAR_TO_TCHAR(str). This macro insures that narrow-character str is in the same form as ACE_TCHAR, whatever it is at compile time.
• ACE_TEXT_WCHAR_TO_TCHAR(str). This macro insures that the wide-character str is in the same form as ACE_TCHAR, whatever it is at compile time.
• ACE_TEXT_ALWAYS_CHAR(str). This macro converts the ACE_TCHAR str to narrow character form if needed.
• ACE_TEXT_ALWAYS_WCHAR(str). This macro converts the ACE_TCHAR str to wide character form if needed.

In all of the above macros, remember that:

• No conversion is performed if not needed. For example, using ACE_TEXT_CHAR_TO_TCHAR(str) when ACE_TCHAR is a char simply substitutes str without any modification.
• The result of a conversion via these macros is temporary. When a conversion is needed, the macros use the ACE_Wide_To_Ascii and ACE_Ascii_To_Wide helper classes. This effectively substitutes a temporary object where the macro is, which works just as you'd expect when supplying an argument to a function, for example. If you know you need a translation and you need it to persist, you should use the helper objects directly. See the ACE_wrappers/ace/ace_wchar.h file for class declaration and usage instructions.

For string objects, ACE also offers an easy way to portably change between narrow and wide characters. The ACE_CString and ACE_WString are string classes for narrow and wide characters, respectively. Analogous to the ACE_TCHAR width-switching type, ACE offers the ACE_TString type, which is defined as ACE_CString when ACE_USES_WCHAR is not set, and ACE_WString when it is.

For examples of these facilities, please see the ACE test suite source code in ACE_wrappers/tests or the APG example source code in ACE_wrappers/examples/APG.

If you have more questions about wide-character usage and ACE, please feel free to file a support request to get further clarification and information. If you're not a Riverace support customer, you can learn more about our support services at http://www.riverace.com/support.htm.

ACE.next: What's New?

The ACE development community is hard at work on the next version of ACE. Here are some of the things you can look forward to (items in bold are new or changed since last month):

• Native library path-searching. Previous ACE versions's implementation of ACE_DLL (used in loading dynamic services) implemented a search of the configured path-search to try and locate the desired library file (DLL) and then used the full pathname to load the library. This skirted some platforms's rules for path search and security settings. This has been changed in the next ACE version to make use of all of the native platform's path-search and security facilities.
• Improved wide-character support. Wide-character support has been included in ACE for many years on Windows (also known as Unicode builds). However, wide-character support for POSIX platforms has been sorely lacking. As ACE's reach expands, this has become a more important issue. Riverace is leading the completion of wide-character support in the next version of ACE. This support is also available now in the ACE 5.4b fix kit.
• GNU autotools support. Riverace is the lead developer in charge of adding auto-configure support to ACE. For native-build, non-Windows systems, autoconf will very likely become the way to configure and build ACE. This will help insure that ACE uses the latest features available on each supported platform, and reduce the work required to build ACE. No more picking the right config.h or platform_macros.GNU file. Just do ./configure then make. Ahhh...
• New compiler support. Support for g++ 3.4 and Microsoft Visual C++ 2005 are being added.
• Newer C++ Features Being Used. As the range of ACE-supported compilers matures and older compilers are taken out of service, ACE can make more use of newer C++ features while still maintaining its stellar portability record. For example, many methods that returned 1 or 0 as an int now return bool. Small steps, yes, but significant ones. You'll see more modern C++ usage as time goes on.

New ACE Fix Kits Released!

Riverace released ACE versions 5.3e and 5.4b, containing lots of new fixes and improvements to the ACE 5.3 and 5.4 release series, respectively. These kits provide fixes to previously released ACE versions, and are not beta test kits in the ACE develoment stream. The small price for these kits provides you with tremendous value in the ability to maintain stability in your projects while picking up important fixes to ACE.

New Project Coming Up?

If you're planning a new project to start soon, or find yourself grappling with how to apply ACE to your current project, remember that Riverace provides world-class development and consulting services with special expertise in ACE. We can help you be sure that your new system is designed to take full advantage of ACE's power and flexibility, getting your system delivered in the shortest possible time and with the highest level of quality. Please contact Steve Huston at 888-384-8154 (toll-free in the US) or +1 508-541-9180 to discuss how Riverace can help you.

Useful ACE Information

• Riverace-supported ACE Releases (don't forget, ACE Annual Support customers get no-charge access to all Fix Kits!)

• ACE Books are available via riverace.com from amazon.com
• Looking for ACE reference documentation? Please see www.riverace.com/docs.htm
• Need more help? Riverace is the premier support provider for ACE. We also offer hands-on design and consulting services to help you get the most out of ACE's power and flexibility.

Quotables

"I also wanted to take this opportunity to express my appreciation for the quality and responsiveness of your organization.  It is a very rare pleasure to work with an organization that provides in-depth technical support while remaining strongly customer focused - a fact you clearly demonstrate on every interaction.  With your help, we have been able to dramatically improve our development schedule while reducing the overall cost and resources required.  Riverace has exceeded our expectations without exception."

Christopher W. Midgley
Chief Technology Officer
LiveVault Corporation

This Newsletter...

... is produced by Riverace Corporation to educate the ACE user community about ACE and available ACE resources, give tips on how to use ACE more effectively, and explain how Riverace can help you make the most of this powerful toolkit.

About Us

Riverace Corporation is the premier support service provider for the ACE toolkit worldwide. Steve Huston, Riverace's President/CEO and founder, has over 20 years' experience developing network protocols and applications. He has coauthored three books on ACE's design and usage and is considered an expert by ACE users around the world. Riverace has been focused on providing world-class technical support and consulting services for ACE since 1997.