Working with other libraries, part 1: Loki performance testing in FastFormat

FastFormat's performance test programs are available from the command-line, via "make -e test.performance".

Since 0.2.1 alpha 2, the distribution has included support for testing against Boost's Boost.Format library. As long as you have an environment variable BOOST defined - under which the boost directory resides - then the above make command-line will provide you with performance tests including Boost.Format. That's reasonably easy to do, because Boost.Format is header-only.

With 0.2.1 beta 6, I needed to include Loki's SafeFormat library. This presented something of a challenge, however, because Loki comes as header+implementation, i.e. it has .cpp files.

FastFormat, like several other STLSoft-related, libraries builds an exhaustive set of configurations. For example, with Visual C++ 9, it builds debug multithreaded, debug multithreaded dll, release multithreaded, and release multithreaded dll. Loki's distribution includes VC++ project/solution files that only provide the multithreaded (not the multithreaded dll) configurations. Problem: how to use Loki.SafeFormat if Loki is detected (by presence of LOKI environment variable).

This problem had me somewhat vexed, so I did what I usually did when I can't think: I went for a ride.

Upon my return, I hit upon the solution: build a specific FastFormat-specific library containing only the source file for the SafeFormat part of Loki. If the makefile detects the definition of the LOKI variable, it will attempt to build the lib/loki.safefmt.ff.??? library (where ??? refers to the per-compiler/architecture/mode configuration).

If that library does not exist, it is linked from a corresponding object, which itself is built from a file src/loki.safefmt/loki.safefmt.cpp. If this file does not exist, it is automatically generated. This file contains exactly one (pre-processor) statement:

#include <../src/SafeFormat.cpp>

which includes the requisite file form the Loki source directory.

The reason this is done is to simplify the situation if the Loki source cannot be found. As you will be aware, failing to find a required file in a makefile-build can lead to less-then-clear error messages. By generating the file if it's not there, and by #include-ing the requisite Loki source file (SafeFormat.cpp), it'll be clearer to users if that file is missing, or in the wrong directory. It also seems preferable to distributing a Loki-related source file in the FastFormat distribution, merely to allow for comparative performance testing.

So, whether you use Loki or not, you can build and test FastFormat without needing any dependencies on it. All you need to include Loki.SafeFormat in the tests is to define the LOKI variable, in the same way as if you wish to include Boost.Format in the tests you define the BOOST variable.

Width/Alignment/Fill functionality for FastFormat (0.3) functionally complete

Work on FastFormat has been progressing substantially over the last few days, in preparation for:

• A series of articles to feature in Overload in 09
• Monolith

As part of this, the width/alignment/fill functionality has been proven in the (currently unreleased) 0.3 branch, so that minimum-width and/or maximum-width and/or alignment and/or fill may be specified. Let's consider a couple of examples.

1. Output a string that uses a single argument twice, with default formatting in each case:

ff::fmtln(std::cout, "x={0}; y={0};", "abc");

This prints x=abc; y=abc;


2. Specify a minimum width for the first parameter:

ff::fmtln(std::cout, "x={0}; y={0,10};", "abc");

This prints x=abc; y=       abc;


3. Specify a minimum width and right alignment (which is the default) for the first parameter:

ff::fmtln(std::cout, "x={0}; y={0,10,,>};", "abc");

This prints x=abc; y=       abc;



4. Specify a minimum width and left alignment for the first parameter:

ff::fmtln(std::cout, "x={0}; y={0,10,,<};", "abc");

This prints x=abc; y=abc       ;


5. Specify a minimum width and centre alignment for the first parameter:

ff::fmtln(std::cout, "x={0}; y={0,10,,^};", "abc");

This prints x=abc; y=   abc    ;


6. Specify a maximum width for the second parameter:

ff::fmtln(std::cout, "x={0}; y={0,,2};", "abc");

This prints x=abc; y=bc;


7. Specify a maximum width and left alignment for the second parameter:

ff::fmtln(std::cout, "x={0}; y={0,,2,<};", "abc");

This prints x=abc; y=ab;


The precise semantics of the alignment and fill (not shown above) options may still be changed, but the basis of the parameter syntax (four fields: index, min-width, max-width, alignment-and-fill) seem to work out well.

And the really great news late last night was that this new functionality has no appreciable cost over 0.2, so FastFormat is still head and shoulders ahead of Boost.Format, Loki.SafeFormat, and the IOStreams in performance (as it also is in robustness, expressiveness and flexibility).

I've released beta 7 of 0.2.1 today, and hope to be releasing an alpha of 0.3 in the next couple of weeks.

FastFormat now performance tested against Loki

As of 0.2.1 beta 6, FastFormat's performance test programs now also compare against Andrei Alexandrescu's Loki library's SafeFormat component. The results clearly demonstrate FastFormat's performance superiority over this library, as they do over C++'s standard IOStreams and Boost.Format.

Given the fact that FastFormat is more robust and more flexible than these other libraries, and is highly expressive, I think it's fair to now claim that it is the pre-eminent formatting library for C++. All that remains is to provide the planned width+alignment+fill functionality, and it'll be effectively complete.

I'll be looking for input/assistance in the new year for packaging and porting. If anyone wants to volunteer, you'll be most welcome.

Merry Christmas ... and a busy New Year

Just wanted to wish everyone a Merry Christmas, and a happy, and busy, New Year.

Definites in the coming year:

• publication of Breaking Up The Monolith; I've been writing like a crazy thing the last week, and now have Part 2 95+% complete and Part 3 ~33% complete
• non-beta release of Pantheios 1.0, followed swiftly by new features
• release of FastFormat 0.3, which will allow width/alignment specification in the format strings
• release of xCover, a code coverage library for C++ (which is already being used in the preparation of STLSoft 1.10)
• release of STLSoft 1.10, which will include new features, and a lot of tidying up and rationalising of the libraries 
• a brand new website for Synesis Software, including tutorials and blogs
• new articles and columns from me 

See you then.

Matt

recls 1.9 alpha process begun

I've finally got around to enhancing the old stalwart, recls, which (if you don't know) is a platform-independent file-system recursive-search library.

So, far, I've finished a source-file renaming process that I started over a year ago, and now I'm having a go at the tracing functionality. This was formerly implemented in terms of syslog() on UNIX and OutputDebugString() on Windows. Now, as may be obvious if you follow STLSoft-related library news, I'm thinking it'll be implemented in terms of Pantheios.

The issue here, though, is that there should be no unnecessary coupling between libraries, and I think it would be wrong to couple recls to Pantheios just to provide good logging facilities. So the challenge will be to work out a way to allow the two to work together if required, and to not do so if not. Preprocessor options, function pointers, callbacks, and all manner of other ideas are under consideration.

I'll let you know how it goes. (And you'll be able to see it, as I'm planning to release recls 1.9 alpha 1 as soon as the logging is done.)

simple_string evolution

I'm finally putting some time into getting stlsoft::(basic_)simple_string finished - it's only been, er, 6 years. :$

Anyhow, here's the thinking:

1. Round out all the currently-missing std::basic_string equivalency methods, so that it can act as a full functional replacement
   
2. Define its purpose. This is something that has confused STLSoft users over the years.
   
3. Provide compile-time selection of its nature, facilitating user-selected customisations of its implementation
   

The second point can be expressed as two main notions:

• It has a documented footprint, equivalent to a single char*, which is consistent across platforms/architectures/operating systems, allowing, for example, a user to pass a std::vector<stlsoft::simple_string> to a function taking an array of C-style strings
• It is, in some circumstances, more efficient than std::basic_string. Please note that superior efficiency is not a main design feature of the component, nor is it claimed in any general sense.

These changes will be included in forthcoming alpha releases of STLSoft 1.10.

Radio silence ...

Having had a protracted break from STLSoft-related blogging, I'm back.

I've been busy with clients, and with various coding and writing projects, of which more in the coming posts.

I'll be attempting to post daily for the next few weeks, as I make my way through the following tasks:

• STLSoft 1.10 alpha releases
• recls 1.9 alpha release
• FastFormat 0.2 beta releases
• Pantheios 1.0 non-beta release
• xCover first release
• ... and other things I've currently forgotten
  

Using STLSoft 1.10 alpha (delta) releases

Just a quick remark on the strategy for STLSoft 1.10. Essentially, the alpha releases will be forthcoming over the next few months, as components are moved over (and given the treatment) from the 1.9 branch, and new components are added. Each of these alpha releases is in the form of a delta-only distribution, meaning that you will have to first install STLSoft 1.9, and then either:

• Install the STLSoft 1.10 distribution over the top of the 1.9 installation, or
• Install STLSoft 1.10 to a separate area and then use include paths to cause your compiler(s) to see the 1.10 alpha files first

We do the latter, by:

1. Defining an STLSOFT environment variable pointing to the 1.9 distro root directory
2. Defining an STLSOFT_1_10 environment variable pointing to the 1.10 distro
3. Specifying the latter before the former to the compiler, as in "g++ -I$STLSOFT_1_10/include -I$STLSOFT/include my_file.cpp"

STLSoft 1.10 new additions: string_to_integer

Having not posted for over a month, there's a lot to catch up on.

I'm going to start with a series of short missives on the latest additions to STLSoft 1.10. (See this for how to install/use 1.10 alpha (delta) releases.) While I'm catching up with the releases, it's probably not going to go in order, so you'll have to be bear with me.

I'll start today with the new stlsoft::string_to_integer() functions, defined in the new include file stlsoft/conversion/string_to_integer.hpp. These are low-level string->number parsing functions. Their raison d'etre is performance - they'll be used in the forthcoming FastFormat 0.3 version, for high-speed parsing of replacement parameters - and for this they sacrifice some functionality, as discussed below.

They look like the following:

namespace stlsoft
{
int string_to_integer(char const* s, char const** endptr);
int string_to_integer(wchar_t const* s, wchar_t const** endptr);
int string_to_integer(char const* s, size_t len, char const** endptr);
int string_to_integer(wchar_t const* s, size_t len, wchar_t const** endptr);
} // namespace stlsoft

The functions in the first pair take a (non-NULL) pointer to a (nul-terminated) C-style string, along with an optional (may be NULL) pointer to pointer to C-style string, which will receive the pointer to the character terminating the parsing. In this aspect, these functions ape the functionality of the standard strtol() function. However, where they differ is that they do not accept a radix parameter: currently all conversion is decimal.

The second pair do not require nul-terminated strings, and instead use a length parameter. This is useful when parsing numbers out of string types that may not be null-terminated. (Again, this is found in FastFormat, which is the main driver for the release of these functions.)

These functions are very new, and will evolve further before STLSoft 1.10 beta. Three changes that are candidates to be introduced are:

• Supporting different radixes (although for radixes not in [8, 10, 16] it may be that they'd defer to strtol()).
• Support for different integer types. In fact, the four concrete functions are implemented in terms of two function templates whose integral type is a template parameter, so the groundwork is all there
• Support for truncation testing.

I'd like to hear from anyone on these, or other, features.

I'll do some specific performance tests on the functions at a later time. They've had some exposure as part of a larger performance test of the forthcoming FastFormat 0.3's new functionality, and have shown to confer a benefit over strtol() and its siblings.

Pantheios 1.0 countdown ... what do you want to see?

I'm on the home straight with the Pantheios 1.0 final (non-beta) release. I've started a discussion thread on the Pantheios Open Discussion forum to garner opinion from current (and future!) users as to what features should make it into 1.0 (and what will have to wait until future versions).

I'm very happy to hear contributions, so please give me your opinions.

Thanks

Release early, release often; FastFormat 0.2.1 (alpha 4)

The value of the open-source adage to "release early, release often" has shown itself once again, this time with respect to the FastFormat library. There are a large number of things to go into this library on its progress from 0.2 onwards, but it's been stuck for a month waiting for me to get my act together. Part of the delay is due to the fact that I let too many changes creep in, which complicates the testing and the formulation of the distribution (incl. just listing the changes).

So, I've just released 0.2.1 (alpha 4), which is a sound base for the future releases. It incorporates various minor fixes and adjustments, and a wholesale refactoring of the contract enforcement API. (An analogous refactoring has also been done for Pantheios, and is available in its latest release.)

STLSoft 1.10 coming: Contracts, Coverage, TR1, new components

It's been two years in the making, but the STLSoft 1.10 branch is finally about to begin showing its face to the world. There are a number of important new features to be introduced to the libraries, and we've reached the point where the 1.9 branch won't take more new features being stuffed into it.

Initially, the new branch will be presented as a series of "alpha delta" releases, each of which will rely on the 1.9 branch being visible in the include path (after 1.10, of course, to allow source interpositioning). That's largely because the task of bringing over all the 1.9 components at once is just too daunting.

So what's going to be new in 1.10? Well, that's a hard question to answer, largely because 1.10 is not likely to come out of alpha until 2009. However, there are some aspects that are already certain to go in:

• Improved contract enforcement support, separating out the different aspects of Contract Programming. Users will have the option to use xContract, the current assert()-based enforcement approach, or any other contract enforcement library they choose. (That xContract is itself implemented in terms of STLSoft confers a little complexity, but this will be handled by the separate compilation of the two libaries: in the compilation of xTests, STLSoft's contracts will be the old assert()-based ones.)
  
• Code coverage. This is in its infancy because the library it will use, xCover, is as yet unreleased
  
• Properties File library. This will provide full support for the Java Properties file format, with the usual high-performance tweaks (incl. memory mapping and string views)
• Reworking of all the per-compiler feature discrimination. Some early hints of how this will work are to be found in msvc.h and gcc.h
• TR1 components, to facilitate migration to these new components
  
• and lots more ... including user-requested functionality, so please get your requests in now.

If anyone wants to offer help in this marathon effort, you'll be spectacularly welcome.

Busy times; Pantheios.COM release

Things are really busy at the moment, what with my current commercial client and doing a fair chunk of the writing commitments that I've been dodging for much of this year.

I'm committed to writing 8 articles over the next year, about things to do with Monolith (FastFormat, Pantheios, Type-tunneling, Shims, and so on).

But in the meantime things are progressing on the libraries. Today I've released a new version of Pantheios.COM, which fixes incompatibility with early-binding automation clients (such as Visual Basic and Delphi).

STLSoft site moved to SourceForge

As part of the movement of STLSoft over to SourceForge, I've just put in the DNS changes. Expect a few hiccups in the next few hours, as the DNS record updates are rolled out, after which the new site should be available.

Please visit the site, http://stlsoft.org/, and provide feedback on the services/content provided there.

Also, please feel free to make use of the forums and the trackers. These will be preferred over this newsgroup, or direct emails, from this point onwards for keeping track of bugs, feature requests, tutorial questions, and so forth.

Matt

New library: xContract 0.3.3 released

xContract is a contract enforcement library for C and C++, written in C. Its notable features are:

• Phase Separation. It supports the separation of the three phases of contract enforcement: detection, reporting and response. Detection is achieved by simple boolean condition evaluation. Reporting is achieved via a callback function, either the stock xContract_violationReport() function, or one supplied by the user. Response is to terminate the process.
• The Principle of Irrecoverability. If the reporting receiver does not cause the process to terminate, then the library will always do so.
• The Principle of Removability. Enforcements may be enabled/disabled either at compile-time or at runtime according to the choices of the programmer
• Portability. It relies on no platform-specific or compiler-specific constructs. The only library it relies on is the 100% header-only, open-source STLSoft library. It works with a large number of C/C++ compilers.

xContract is the second of a triumvirate of C/C++ software quality assurance libraries provided by Synesis Software. The first library, xTests, is an automated testing library. The third, as yet unreleased, library, xCover, is an automated code coverage library.

makefiles and build directories

Further to a recent blog post, about object library naming conventions, there's also some debate about the makefile naming and build directory structure. Historically, there have been three main forms of build-dir+makefile-naming with most STLSoft-dependent libraries:

1. solo: e.g. the bc584 directory (for Borland C/C++ 5.84) contained the single makefile makefile
2. multi-os, e.g. the gcc34 directory (for GCC 3.4) contained the makefiles makefile.unix (for UNIX) and makefile.win32 (for Windows)
3. multi-arch, e.g. the vc8_x64 directory (for Visual C++ 8 (x64)) contained the makefile makefile (for 64-bit Windows)

Obviously, there's a degree of inconsistency there. Furthermore, using the multi-os form was a pain because it meant having to explictly write 'make -f makefile.unix' (or equivalent), rather than just make.

This has all changed now, and all projects will eventually adopt the new form, which is:

1. solo: e.g. the bc584 directory contains the single makefile makefile
2. multi-os, e.g. the gcc34.unix directory contains the makefile makefile, and the gcc34.win32 contains the makefile makefile
3. multi-arch, e.g. the vc8.x64 directory contains the makefile makefile
   

New Libraries coming ...

Commercial and publishing reasons are forcing me to do what I should have done a *long* time ago, and release several pending libraries in the coming days:
* xContract - a contract programming enforcement library; initially for C/C++
* xCover - a code coverage library for C and C++
* FastFormat - already available as an alpha, this will hit the non-alpha/non-beta status in the coming days; as the name implies, it's faster than all the competition put together ;-)
* Pantheios - in beta (and very popular) for two years, the world's fastest and most robust logging API library has waited long enough for a final 1.0 release.

Also, STLSoft is going to be moving to SourceForge in the next week or so, and it too will receive a face lift and an update to docs, tests, and so on.

If anyone wants to volunteer any help for any of these activities, you'd be extraordinarily welcome.

Cheers

Matt

xContract released

xContract is a contract enforcement library for C and C++, written in C. Its notable features are:

• Phase Separation. It supports the separation of the three phases of contract enforcement: detection, reporting and response. Detection is achieved by simple boolean condition evaluation. Reporting is achieved via a callback function, either the stock xContract_violationReport() function, or one supplied by the user. Response is to terminate the process.
• The Principle of Irrecoverability. If the reporting receiver does not cause the process to terminate, then the library will always do so.
• The Principle of Removability. Enforcements may be enabled/disabled either at compile-time or at runtime according to the choices of the programmer
• Portability. It relies on no platform-specific or compiler-specific constructs. The only library it relies on is the 100% header-only, open-source STLSoft library. It works with a large number of C/C++ compilers.

xContract is the second of a triumvirate of C/C++ software quality assurance libraries provided by Synesis Software. The first library, xTests, is an automated testing library. The third, as yet unreleased, library, xCover, is an automated code coverage library.

STLSoft moving to SourceForge

I've finally got myself together, and am moving STLSoft from the Synesis Software site to SourceForge.

Over the coming months you can expect to see the following changes:

• The distributions available solely from SF
  
• The stlsoft.org domain will be hosted on SF
• A wiki will be configured and built up
• Subversion repository (but not before 1.10 is released, and a whole lot of TODOs are TODONE)
• Blogs will be added
• Forums will be added

Moving blog to its own domain

Exactly what's said on the tin: I'm moving the blog to http://stlsoft-musings.net/

It might take a day or so to make it through DNS, but after that it should be sweet.

Defect in STLSoft's Windows Registry Library on 64-bit

One of STLSoft's users is reporting weird behaviour in the Windows Registry Library, when used on 64-bit Windows (x64).

It looks like the call to winstl::dl_call is defective, since x64 does not support different calling conventions.

I must confess I'd overlooked this potential issue - in part because I've still not got around to fully implementing the STLSoft internal automated testing harness - but I would still assume that the code would work, because the calling convention information, if any, would simply be ignored.

We're still looking into it. I'll post more when I know more ...

VOLE 0.6.1 broken by bad STLSoft 1.9.53 - 1.9.54 now released

A VOLE user reported problems with compiling VOLE 0.6.1, which are a result of (i) my having released an incomplete STLSoft 1.9.53, and (ii) when using GCC, which does not define UDATE, some of WinSTL's conversion shims - specifically to_FILETIME(DATE const&) and to_SYSTEMTIME(DATE const&) - were not available.

Both issues are now fixed, with the recently released STLSoft 1.9.54.

VOLE 0.6.1 released

VOLE version 0.6.1 is released.

It now supports time return values, of types DATE (via the VOLE type date_t), FILETIME, and SYSTEMTIME, as in:

vole::object obj = ...
SYSTEMTIME updated = obj.get_property<SYSTEMTIME>(L"Updated");

FastFormat 0.2.1 (alpha 3) released

FastFormat 0.2.1 (alpha 3) is released.

It contains a fix to a defect in the implicit link header, and also a lot of groundwork for widestring support in the near future. (Actually, all the widestring support is now in the core library - just the makefiles, examples and tests need to be correspondingly updated.)

Pantheios 1.0.1 (beta 156) released

Pantheios 1.0.1 beta 156 of is released.

It contains a revised naming convention for makefiles, such that every makefile is now in its

   own directory, and is called 'makefile'. The following examples
  illustrate:
     build/vc9/makefile            =>  build/vc9/makefile
     build/vc9_x64/makefile        =>  build/vc9.x64/makefile
     build/gcc34/makefile.win32    =>  build/gcc34.win32/makefile
     build/gcc34/makefile.unix     =>  build/gcc34.unix/makefile
     build/gcc41/makefile.unix     =>  build/gcc41.unix/makefile
     etc.

Pantheios release, and new CodeProject article

Pantheios 1.0.1 (beta 155) is released.

Also, a new article on Pantheios' Back-end Architecture is published on CodeProject.

STLSoft 1.9.52 released

Just a defect-fix release, to fixup some compiler warnings encountered on Win-64 compilation.

FastFormat is FAST: It's official!

I just posted some performance stats on the FastFormat website. I'll just give you the summary here:

• The Format API is faster than IOStreams by between ~140-730%, faster than MFC's CString::Format() by between ~300-400%, and faster than Boost.Format by between ~470-1600%! The only formatting API that gives it a run for some architecture/compiler/configurations is sprintf(), which is not type-safe, at between ~40-380%. (FastFormat's Format API is 100% type-safe.)
• The simpler Write API is faster than IOStreams by between ~270-1350%, faster than MFC's CString::Format() by around ~420%, and faster than Boost.Format by between ~630-1800%! Again, the only formatting API that gives it a run for some architecture/compiler/configurations is sprintf(), at between ~65-390%. (FastFormat's Write API is 100% type-safe.)

STLSoft 1.9.51 released

This latest release contains only two changes, but they're interesting nonetheless.

The first is a workaround for a defect in VC6. This was found in stlsoft::conversion_error, and comes about as follows. stlsoft::conversion_error is defined along the lines of:


class conversion_error_base

  : public std::runtime_error

{

  . . .

public: // Construction

  virtual ~conversion_error_base() = 0;

  . . .

};



class conversion_error

  : public conversion_error_base

{

  . . .

};



The highlighted line is the problem for VC++ 6. The code it generates is defective such that when an instance of any derived class is thrown, the exception does not get thrown, merely hangs about in the current scope, and the program execution carries on as if no exception was thrown.

The second change is a correction for a defect in the string access shim functions for the SYSTEMTIME type, whereby conversion of an invalid time resulted in a fault, because the calculation for the total length of the resultant string did not take account the fact that the Windows Time API functions returns 0 if the time instance is invalid. The consequence of fixing this defect has resulted in some nice refactoring, so there's some silver lining.

Coming soon: releases of VOLE, flecxx, Pantheios, and FastFormat.

FastFormat is unleashed: v0.2.1 (alpha 1) released

FastFormat is an Open Source C/C++ Output/Formatting library, whose design parameters are 100% type-safety, efficiency, genericity and extensibility. It is simple to use and extend, highly-portable (platform and compiler-independent) and, best of all, it upholds the C tradition of you only pay for what you use.

FastFormat supports output/formatting of statements of arbitrary complexity, consisting of heterogeneous types.

FastFormat writes to output "sinks", which can be of arbitrary type. It implicitly supports any type that is structurally conformant with the standard library's string, and the library includes adaptors to allow writing to std::ostream, FILE*, speech (currently Windows-only), STLSoft's auto_buffer, C-style string buffers, and character buffers. Adaptation to a new type merely requires the definition of a single function.

FastFormat is fast. The processing of each statement involves at most one memory allocation to hold the entire statement, and each statement element is measured and copied exactly once. As a consequence, the library is on a par with (the type-unsafe) C's Streams (printf()-family) of functions, faster than C++'s IOStreams, and considerably faster than Boost.Format. Comprehensive performance analyses are underway; initial results of a realistic scenario on Windows (32-bit) with Visual C++ 9 shows FastFormat is approximately 3 x faster than C's Streams, 6 x faster than C++'s IOStreams, and 17 x faster than Boost.Format.

FastFormat supports I18N/L10N by using numbered arguments, enabling reordering of arguments by exchanging format strings. The library comes with a number of resource bundles, classes whose instances can load sets of localised resource strings for use as format strings.

FastFormat does not contain any compiler-specific or platform-specific constructs. It supports UNIX (including Linux and Mac OS-X), and Windows, and should work with any operating system. It is known to be compatible with Comeau (4.3.3+), GCC (3.4+), Intel (8+), Metrowerks (8+), Microsoft Visual C++ (6.0+), and should work with any reasonably modern C++ compiler.

FastFormat is completely free and includes source released under a BSD-style license. Commercial customisations and related consultancy are provided by Synesis Software Pty Ltd; http://synesis.com.au/contact.html)

Release 0.2.1 alpha 1 is the first public release.

Note: this release of FastFormat requires STLSoft 1.9.50, or later. Download from http://stlsoft.org/

Download from: http://sourceforge.net/project/showfiles.php?group_id=177382&package_id=204396

Discuss at: http://sourceforge.net/forum/forum.php?forum_id=612781

FastFormat website: http://fastformat.org/

When good compilers go BAD! A sorry tale of unhelpfulness from GCC

I've just added a new inserter class, w2m, to the world's fastest logging API library, Pantheios, in leiu of the widestring support that'll come in version 1.1+.

The initial implementation of the class uses STLSoft's auto_buffer, to be especially efficient in the case where the length of the string to be converted falls below a threshold - 64 in this case.

As with all other inserter classes, it does not provide copy semantics, neither copy constructor nor copy assignment operator.

All is well until I try to compile with GCC, which "helpfully" informs me that it can't generate a copy-constructor. (auto_buffer does not define a copy-constructor by design; you can read about why in section 16.2.3 of Extended STL, volume 1. Somewhat surprising that, given that I'd expressly told it not to try, by declaring, but not defining said copy constructor.

So, I've now got to spend a couple of hours implementing some custom memory management code to ensure portability. Great!

FastFormat about to drop ... and it's FAST!

I'm now less than two days away from releasing FastFormat. All that's left to do is:

• verify on 64-bit Linux
• do the docs (a basic first cut; nothing mega good)
• try and find out why DMC++ does not like it (as usual, it's the odd-man-out with templates)
• do a decently comprehensive lot of performance tests

As a first go at verifying the performance, I've run a test which formats thusly:

std::string arg0 = "abc";

const char arg1[] = "def";

stlsoft::simple_string arg2 = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";


fastformat::fmt(s, "The first param '{0}', and the second '{1}', and the first again '{0}'. Finally the third '{2}'", arg0, arg1, arg2);


Note: this is for one compiler (VC++ 9), and one scenario (described above), so we can't draw any way-out conclusions as yet. But the first results are pretty encouraging to say the least:

IOStreams: 679561us
Boost.Format: 1901109us
sprintf(): 346776us
FastFormat: 112016us
IOStreams:FastFormat: 6.067
Boost.Format:FastFormat: 16.97
sprintf:FastFormat(): 3.096

These numbers mean that, for that scenario with that compiler, FastFormat is 3x faster than sprintf, 6x faster than the IOStreams, and 17x than Boost.Format.

Given that it's 100% type-safe, infinitely extensible, and supports I18N/L10N, I hope that it's going to be well received.

... FastFormat?

For those long-suffering waitees for the long-promised revolution in string formatting that is FastFormat, I promise that the wait won't be much longer. I've got a few things on my plate over the next few days, and then FF is top of the list. All that's left to do is sort out a few distro issues, and tidy up the docs, and we're ready to rock and roll. (At least for an alpha version, anyway.)

CMake; Pantheios

I just received my recently-ordered copy of "Mastering CMake" (Martin & Hoffman), and plan to make good use of it next week, as I investigate options in reducing the management overhead of my various open-source libraries.

If anyone's got any useful experience, I'd be glad to hear it.

I'll let you know how it goes

Matt

btw, the latest release of Pantheios, 1.0.1 beta 152, contains the long-requested feature of a source-only distribution, cutting download size for people who prefer to get the docs online from ~4.8 MB to ~2.5.

Pantheios 1.0.1 (beta 150) released

Pantheios is an Open Source C/C++ Logging API library, offering an optimal combination of 100% type-safety, efficiency, genericity and extensibility. It is simple to use and extend, highly-portable (platform and compiler-independent) and, best of all, it upholds
the C tradition of you only pay for what you use.

Pantheios supports logging of message statements of arbitrary complexity, consisting of heterogeneous types.

Pantheios supports filtering of log messages based on severity level including (but not limited to) the eight levels defined by the SysLog protocol.

Pantheios supports back-end output, individually and in combination, to stderr/stdout, SysLog (including a custom implementation of the SysLog protocol for Windows), Windows debugger, Windows event log, COM Error Object, Speech, or any custom back-end extension you care to write. Importantly, Pantheios is readily extended to use the existing transport mechanisms of feature-rich logging libraries such as ACE, log4cpp, log4cplus, log4cxx.

Pantheios does not contain any compiler-specific or platform-specific constructs. It supports UNIX (including Linux and Mac OS-X), and Windows, and should work with any operating system. It is known to be compatible with Borland (5.5.1+), Comeau (4.3.3+), Digital Mars (8.45+), GCC (3.2+), Intel (6+), Metrowerks (8+), Microsoft Visual C++ (5.0+), and should work with any reasonably modern C++ compiler.

Pantheios is completely free and includes source released under a BSD-style license. Commercial customisations (of front-/back-ends are provided by Synesis Software Pty Ltd; http://synesis.com.au/contact.html)

Release 1.0.1 beta 150 incorporates:
* fixed defect in fe.N, whereby a negative catch-all severity ceiling would not be respected
* other minor adjustments/improvements to fe.N
* added unit-test for fe.N
* bundles xTests 0.8.5
* NOTE: Now requires STLSoft 1.9.48
* NOTE: These are breaking changes. Any code using the extant fe.N front-end library will need to be edited and re-compiled

Note: this release of Pantheios requires STLSoft 1.9.48, or later.

Download from: http://sourceforge.net/project/showfiles.php?group_id=141831&package_id=155759

Discuss at: http://sourceforge.net/forum/forum.php?forum_id=475313

VOLE 0.5.1 released

Version 0.5.1 of VOLE released.

Changes:

• renamed coercion level nonDestructiveTruncation to nonDestructiveCoercion
• added com_return_traits<float>
• added com_return_traits<double>
• changed behaviour for com_return_traits<bool>, com_return_traits<short>, com_return_traits<int>, com_return_traits<long>, com_return_traits<std::string> and com_return_traits<std::wstring>
• added test.unit.return_traits.builtins
• added test.unit.return_traits.std_types

xTests 0.8.5 released

Version 0.8.5 of xTests released.

Changes:

• added call to XTESTS_TEST_PASSED() when an expected exception is received
• added more integer specialisations of xtests_failure_reporter<>
• fixed a defect in the approximate comparison of negative floating-point numbers

1.9.48 released

Just released 1.9.48, which contains an essentail fix to stlsoft::trim_all(), and a number of additions to COMSTL.

The language that never ends ...

It has been said (alas, a reference escapes me at this time) that nobody can know all of C++.

Well, today I've just had another proof of it (not that I ever thought I knew all the language). Question: what's wrong with the following code?

  bool fn()
  {
    void* p = 0;

    return p;
  }

Answer: absolutely nothing. Yes, that's right, you can convert an "rvalue of arithmetic, enumeration, pointer, or pointer-to-member type" to an rvalue of type bool(C++ Standard: 4.12.)

Who'd a thought it?!

I found upon this because I'm changing the way some of the type conversions work in VOLE as part of the new functionality of version 0.5. As well as adding specialisations of vole::com_return_traits<> for float and double, I'm adding comprehensive (i.e. a cartesian product of from-type, to-type and coercion level) unit-tests for the builtins' specialisations. I thought that com_return_traits<bool> was too permissive, in allowing any of the basic integral types to be converted when the coercion level is naturalPromotion. Turns out I was wrong!

makefiles and build directories

Further to a recent blog post, about object library naming conventions, there's also some debate about the makefile naming and build directory structure. Historically, there have been three main forms of build-dir+makefile-naming with most STLSoft-dependent libraries:

1. solo: e.g. the bc584 directory (for Borland C/C++ 5.84) contained the single makefile makefile
2. multi-os, e.g. the gcc34 directory (for GCC 3.4) contained the makefiles makefile.unix (for UNIX) and makefile.win32 (for Windows)
3. multi-arch, e.g. the vc8_x64 directory (for Visual C++ 8 (x64)) contained the makefile makefile (for 64-bit Windows)

Obviously, there's a degree of inconsistency there. Furthermore, using the multi-os form was a pain because it meant having to explictly write 'make -f makefile.unix' (or equivalent), rather than just make.

This has all changed now, and all projects will eventually adopt the new form, which is:

1. solo: e.g. the bc584 directory contains the single makefile makefile
2. multi-os, e.g. the gcc34.unix directory contains the makefile makefile, and the gcc34.win32 contains the makefile makefile
3. multi-arch, e.g. the vc8.x64 directory contains the makefile makefile
   

Synesis Software Object Library Naming Conventions explained ... I think

I'm writing up some docs as part of the seemingly never-ending process of getting Pantheios ready for its 1.0 final release. Part of this is documenting the object library naming conventions.

For a given Synesis Software project (Pantheios, FastFormat, UNIXEm, shwild, etc.), the object libraries are named according to the following convention:

  [lib]<library-name>.<major-version>.<module-name>
  .<compiler-name>[.<os-arch-tag>]
  [.<threading-tag>][.<nox-tag>][.<debug-tag>].{a|lib}

Some examples might help.

For the Pantheios core library for VC++ 9 in DLL configuration and debug mode the library name would be:

  pantheios.1.core.vc9.dll.debug.lib

For the Pantheios core library for GCC 4.2 in multithreaded configuration on UNIX the library name would be:

  libpantheios.1.core.gcc42.mt.a

So far so good. Let's jazz it up a little. Consider the NoX - No eXception - builds, which are usually only provided for VC++ 6. Let's say we now want a NoX build of the single-threaded VC debug object library:

  pantheios.1.core.vc6.nox.debug.lib

And the multithreaded (non-DLL) version:

  pantheios.1.core.vc6.mt.nox.debug.lib

Where this starts to fall down is in two ways: when emulating UNIX builds on Windows, and when defining x64 builds of UNIX. For a first example, let's look at the UNIX-emulation, non-NoX variant of the last VC 6 one:

  pantheios.1.core.vc6.unix.mt.debug.lib

Even this has a certain consistency about it. But where it currently really starts to fall down is with the 64-bit Windows versions of things. Consider an x64 version of the VC 9 configuration. It is currently:

  pantheios.1.core.vc9_x64.mt.debug.lib

Ideally this should be changed to:

  pantheios.1.core.vc9.x64.mt.debug.lib

But then if we're emulating 64-bit UNIX on x64, how would we represent this? Would it be:

  pantheios.1.core.vc9.unix.x64.mt.debug.lib

or:

  pantheios.1.core.vc9.x64.unix.mt.debug.lib

or:

  pantheios.1.core.vc9.unix_x64.mt.debug.lib

I'm keen to get some external opinions on this, as the inconsistency can't stand, but making such changes now will be significant.

The other aspect of this issue is that all the changes to all Synesis libraries will have to be made pretty much at once. This is sticky stuff ...

2008's the year for STLSoft

And as part of that effort I'll be attempting to do daily blogs on the subject. This being the first (and least informative).

In the last couple of days I've transferred the unit-tests for stlsoft::auto_buffer and stlsoft::frequency_map to the new unit-testing framework (using xTests). I'm hoping to do move at least one component under test each day, until they're all done.

1.9.46 released

This takes into account fixes to defects in stlsoft::pod_vector, and a few other sundry issues.

The next release, due out tomorrow, will incorporate application of parentheses in contract enforcement statements that are currently confusing GCC 4.3.

I'm hoping that there'll be a change of packaging in 1.9.48, within the next week or so.

Back from holiday: Aug=>Dec 08 plans

My family and I were in Europe visiting friends and family from late June to late July, and I have been catching up with things, mostly commercial, since we got back, so there's not been a lot happening with STLSoft and the other libraries. (I have, of course, cranked out a few more beta releases of Pantheios ...)


Now we're back, I have work sketched out for the rest of the year on four fronts:

• commercial activities:
  
• I'm helping a client rescue and move forward a C++/COM codebase that's been going for 12+ years. This is a huge challenge, but I think we're going to have a lot of fun
• I'm also taking on a few more commercial customisations of Pantheios
• writing:
• books: "Breaking Up The Monolith" will be getting a big lot of time in Sept and onwards, with the intent to finish it before the end of the year; am also starting a couple of other, less demanding, books
  
• articles: I'm planning to get back to writing articles, hopefully for DDJ, ACCU, and others, this year
• libraries:
• Pantheios - get it out of beta, and on the 1.1, 1.2, 1.3 development track; nearly there, honest!
• FastFormat - release the first public alpha before the end of this month
• xContract and xCover - release first public alphas soon
• STLSoft - get 1.10 out, including better distributions (incl. new unit-testing facilities), and docs
• websites
• need to get the Synesis Software website redone - it's not exactly full of wow! at the moment. ;-)
• Pantheios site has been redesigned, and just needs replacing
• STLSoft website: intention here is to have docs, articles, blogs (not just for me), and other stuff

So, that's a list of my modest ambitions for the remainder of 2008. Wish me luck!

Fluffing around

In the last post I promised to get flecxx and FastFormat launched or die. Well, I got half there in launching flecxx (and I'm still here).

FastFormat's almost ready to go; it's just that work is getting in the way. In the meantime, I have cleaned up recls and released it - first one since Oct 07 - and now I'm free and clear to work on recls 1.9 (which will be released via SourceForge, where all of recls will be eventually moved).

As for FastFormat, it's going to be this coming weekend, for sure. Honest!

flecxx, FastFormat and other stuff ...

Well, the time has finally arrived, and I've got my shit together, and I am going to release either/both flecxx and FastFormat this weekend, or die in the effort.

The first thing will be to release STLSoft 1.9.43, as there're a few changes (mostly to do with reducing the clash with the "Safe String Library" with VC++ 8+) that're required for the current versions of the two libraries.

Then I'll be attempting to get the unit- and component-tests completed for them, putting together the distributions, and then letting them loose on the world.

For those who've not yet been exposed to the pitifully inadequate propaganda regarding these libraries, they can be summarised as follows:

flecxx is a very simple, lightweight (no runtime costs, and 100% header-only) library that removes abstraction dissonance. The classic example of abstraction dissonance in the C++ standard library is the pitiful requirement to invoke c_str() in order to allow std::string arguments to be passed to the constructors of std::[if]stream. This and many other vexing syntactic intrusions of leaking abstractions are handled by flecxx.

FastFormat is a much bigger chicken. It uses the Shims-based Type Tunneling also used by Pantheios (and which allows it to be at once 100% type-safe and orders of magnitude more efficient than any other logging libraries), and provides output/formatting to all types of things, including formatting strings, writing to stdout/cout, speech synthesis, logging, etc. etc. As well as very high speed, 100% type-safety (something that is not available with either the C standard library's printf() family or the C++ standard library's IOStreams!), extensibility, expressiveness and portability, FastFormat also offers support for I18N/L15N.

Consider the following examples:

std::cout& sink1 = std::cout;
std::string sink2;
stlsoft::simple_string sink3;

char const* arg0 = "cat";
std::string arg1("sat");
stlsoft::simple_string arg2("mat");

fastformat::fmt(sink1, "the {0} {1} on the {2}", arg0, arg1, arg2);
fastformat::fmt(sink2, "the {0} {1} on the {2}", arg0, arg1, arg2);
fastformat::fmt(sink3, "the {0} {1} on the {2}", arg0, arg1, arg2);

The example illustrates the use of three different sink types (std::cout, std::string, stlsoft::simple_string), and three different argument types (std::string, stlsoft::simple_string, C-style string), used in combination with each other.

The format strings in this example are all C-style strings. They can equally be any other string type, e.g.

std::string fmt1("the {0} {1} on the {2}");
stlsoft::simple_string fmt2("the {0} {1} on the {2}");

fastformat::fmt(sink3, fmt1, arg0, arg1, arg2);
fastformat::fmt(sink3, fmt2, arg0, arg1, arg2);

Because the format arguments are numbered, it is straightforward to support languages whose grammer require different ordering. Should we require the same logical string to render the arguments in a different order, we can do this easily:

fastformat::fmt(sink1, "on the {2} {1} the {0}", arg0, arg1, arg2);

This can be taken further, and in fact is taken further by the provision of resource bundles. The stock resource bundles provided by the library include Windows INI format, Properties File, and Record-JAR. Thus, I18N/L15N is easily supported by loading a locale-dependent resource bundle file, and looking up the formats by name, as in:

fastformat::properties_bundle bundle("GermanFormats.txt");

fastformat::fmt(sink1, bundle["cat-sat-fmt"], arg0, arg1, arg2);

In another post - hopefully after FastFormat has been released this coming w/e - I'll talk further about how to use it, and why it is so efficient.

1.9.38 - Win64 on its way

Ok, so we're still currently defining _CRT_SECURE_NO_DEPRECATE in the Pantheios VC8+ makefiles, but other than that, we're on for Win64-bit in several of the STLSoft-dependent libraries. So far, I've verified xTests, shwild and Pantheios on Win64. (Neither xTests nor shwild need to use _CRT_SECURE_NO_DEPRECATE in order to build correctly with VC8+.)

As for STLSoft itself, it's still pretty far from complete for Win64, but as each dependent library is moved across, more of STLSoft itself will be readied. As time goes by, I'm gradually reworking and improving the unit-/component-tests used on the library, and will be making sure that each test is compatible with Win64 building. Eventually, we'll get the whole thing across. ;-)

1.9.36 FreeBSD compatibility for free!

Just want to let you know about, and simultaneously give thanks to Sergey Nikulov for, FreeBSD compatibility in STLSoft (as of 1.9.36) and Pantheios (as of 1.0.1 beta 128).

I'm still working on Win64, and will continue with that effort. But it's now very cool that Pantheios is working on Win32, Linux 32, Linux 64, Solaris 32, Solaris 64 and FreeBSD.

1.9.x roadmap (Apr / May 08)

Ok, yes, 1.9 should have been dead and buried a year ago, to be surplanted by the wonderful 1.10, but the real world's got this bad habit of getting in the way. (And I've been putting in heaps on Pantheios.)

So 1.9.x is still living, and there's quite a bit to do on it. The currently envisioned roadmap is as follows:

• 1.9.35 will be released in the next 24 hours, and will contain an update to the Windows Registry library's winstl::basic_reg_value, comprising the new value_multi_sz() method, whose original implementation was kindly provided by Austin Ziegler
• 1.9.36 A first stab at full x64 support
• 1.9.37 getting all the Safe String library compatibility done. This is going to be a big effort. :-(
• 1.9.38 A second stab at full x64 support, since I'm unlikely to have it down pat the first go.
• 1.9.39 This'll likely comprise the ATL/MFC stuff that Claudio's been asking for since, er, early last year :$
• 1.9.40 This'll probably include a (#define-reenableable) removal of the stuff in stlsoft/std/*.hpp, as this is eminently bettered by the new flecxx library, that is due to be released very, very soon.

Other than that, I'm going to try and get the 1.10 preview releases started. Given the time ... ;-)

Sun Pro C/C++ compatibility with 1.9.33: step 1

The latest release - 1.9.33 - is now available, and contains modifications to enable compatibility with the Sun Pro C and C++ compilers (version 5.9).

The modifications were something of a marathon effort, and it might be good to spread the information around for anyone contemplating porting STLSoft to another C++ compiler.

In this post, I'll discuss how to get the basic support in there, which is basically recognising the Sun Pro compilers and defining their features

Recognising the Sun Pro compilers

I began with the position that I was confident on, based on Jonathan Wakely's efforts with Pantheios, to whit: Pantheios and STLSoft work with Sun Pro when the -library=stlport4 flag is defined to sunCC (the Sun Pro C++ compiler).

In order to achieve this, all that was required was to discriminate the Sun Pro compiler in include/stlsoft/stlsoft.h, and provide a compiler compatibility file: include/stlsoft/internal/cccap/sunpro.h.

In include/stlsoft/stlsoft.h, insert the following between the Metrowerks and VectorC discriminations:

#elif defined(__SUNPRO_C) || \
      defined(__SUNPRO_CC)
 /* Sanity check on language/compiler */
# ifdef __cplusplus
#  ifdef __SUNPRO_C
#   error __SUNPRO_C should not be defined by the Sun C compiler in C++ compilation
#  endif /* __SUNPRO_C */
#  ifndef __SUNPRO_CC
#   error __SUNPRO_CC should be defined by the Sun C++ compiler in C++ compilation
#  endif /* !__SUNPRO_CC */
# else /* ? __cplusplus */
#  ifndef __SUNPRO_C
#   error __SUNPRO_C should be defined by the Sun C compiler in C compilation
#  endif /* !__SUNPRO_C */
#  ifdef __SUNPRO_CC
#   error __SUNPRO_CC should not be defined by the Sun C++ compiler in C compilation
#  endif /* __SUNPRO_CC */
# endif /* __cplusplus */

# define STLSOFT_COMPILER_IS_SUNPRO
# ifdef __cplusplus
#  define STLSOFT_COMPILER_LABEL_STRING         "Sun Pro C++"
#  if (0x0590 == (__SUNPRO_CC & 0xFFF0))
#   define STLSOFT_COMPILER_VERSION_STRING      "Sun Pro C++ v5.9"
#  else /* ? __SUNPRO_CC */
#   error Currently only version v5.9 of the Sun Pro C++ compiler is supported by the STLSoft libraries
#  endif /* __SUNPRO_CC */
# else /* ? __cplusplus */
#  define STLSOFT_COMPILER_LABEL_STRING         "Sun Pro C"
#  if (0x0590 == (__SUNPRO_C & 0xFFF0))
#   define STLSOFT_COMPILER_VERSION_STRING      "Sun Pro C v5.9"
#  else /* ? __SUNPRO_CC */
#   error Currently only version v5.9 of the Sun Pro C compiler is supported by the STLSoft libraries
#  endif /* __SUNPRO_CC */
# endif /* __cplusplus */

In include/stlsoft/stlsoft.h, insert the following between the Metrowerks and VectorC compiler compatibility inclusions

#elif defined(STLSOFT_COMPILER_IS_SUNPRO)
# include <stlsoft/internal/cccap/sunpro.h>

Defining the Sun Pro compilers' features

Define a new file include/stlsoft/internal/cccap/sunpro.h, containing all the required definitions that describe the capabilities of the C and C++ compilers. The important bits are:

/* /////////////////////////////////////////////////////////////////////////
 * File:        stlsoft/internal/cccap/sunpro.h
 *
 * Purpose:     Compiler feature discrimination for SunPro C / SunPro C++.
 *
 * Created:     24th April 2008
 * Updated:     25th April 2008
 *
 * Thanks:      To Jonathan Wakeley and Lars Ivar Igesund for help with
 *              getting STLSoft (and Pantheios) compatible with Solaris.
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2008, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# error This file must not be included independently of stlsoft/stlsoft.h
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */

/** \file stlsoft/internal/cccap/sunpro.h
 *
 * Compiler feature discrimination for SunPro C / SunPro C++.
 * (\ref group__library__internal).
 */

#ifdef STLSOFT_INCL_H_STLSOFT_CCCAP_SUNPRO
# error This file cannot be included more than once in any compilation unit
#endif /* STLSOFT_INCL_H_STLSOFT_CCCAP_SUNPRO */

/* ////////////////////////////////////////////////////////////////////// */

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_H_STLSOFT_CCCAP_SUNPRO_MAJOR      1
# define STLSOFT_VER_H_STLSOFT_CCCAP_SUNPRO_MINOR      0
# define STLSOFT_VER_H_STLSOFT_CCCAP_SUNPRO_REVISION   2
# define STLSOFT_VER_H_STLSOFT_CCCAP_SUNPRO_EDIT       2
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Auto-generation and compatibility
 */

/*
[<[STLSOFT-AUTO:NO-DOCFILELABEL]>]
[<[STLSOFT-AUTO:NO-UNITTEST]>]
*/

/* /////////////////////////////////////////////////////////////////////////
 * Helper definitions
 *
 * NOTE: These are #undef'd at the end of this file
 */

#ifdef __cplusplus
# define _STLSOFT_SUNPRO_VER_   __SUNPRO_CC
#else /* ? __cplusplus */
# define _STLSOFT_SUNPRO_VER_   __SUNPRO_C
#endif /* __cplusplus */

#define _STLSOFT_SUNPRO_VER_MAJOR   ((_STLSOFT_SUNPRO_VER_ & 0xff00) >> 8)
#define _STLSOFT_SUNPRO_VER_MINOR   ((_STLSOFT_SUNPRO_VER_ & 0x00f0) >> 4)

/* /////////////////////////////////////////////////////////////////////////
 * Compiler features
 */

#if (5 != _STLSOFT_SUNPRO_VER_MAJOR) || \
    (9 != _STLSOFT_SUNPRO_VER_MINOR)
# error The STLSoft libraries have only been verified with Sun Pro 5.9.x. Please contact Synesis Software
#endif /* major.minor */

/* ///////////////////////////////////////////////
 * Pre-processor / compiler
 */

/* Messaging
 */

/* #define STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT */

/* Support for #pragma once
 */

/* #define STLSOFT_CF_PRAGMA_ONCE_SUPPORT */

/* Support for __FUNCTION__
 */

/* #define STLSOFT_CF_FUNCTION_SYMBOL_SUPPORT */

/* Variadic Macros
 *
 * Feature was buggy at one point, require 5.5 to be safe.
 */

#if _STLSOFT_SUNPRO_VER_ > 0x0550
# define STLSOFT_CF_SUPPORTS_VARIADIC_MACROS
#endif /* _STLSOFT_SUNPRO_VER_ */

/* ///////////////////////////////////////////////
 * Types
 */

/* bool */
#if defined(__cplusplus) && \
    defined(_BOOL)
# define STLSOFT_CF_NATIVE_BOOL_SUPPORT
#endif /* __cplusplus */

/* char (sign) */
/* #define STLSOFT_CF_CHAR_IS_UNSIGNED */

/* wchar_t */
#ifdef _WCHAR_T
# define STLSOFT_CF_NATIVE_WCHAR_T_SUPPORT
#endif

/* /////////////////////////////////////
 * Integral types
 *
 * The purpose of this section is to define the following types:
 *
 *  - 8-bit signed and unsigned integers
 *  - 16-bit signed and unsigned integers
 *  - 32-bit signed and unsigned integers
 *  - (optionally) 64-bit signed and unsigned integers
 *
 * and to define, where appropriate the following symbols (used for
 * overloading):
 *
 *  - STLSOFT_CF_CHAR_DISTINCT_INT_TYPE
 *  - STLSOFT_CF_SHORT_DISTINCT_INT_TYPE
 *  - STLSOFT_CF_INT_DISTINCT_INT_TYPE
 *  - STLSOFT_CF_LONG_DISTINCT_INT_TYPE
 *  - STLSOFT_CF_LONG_LONG_DISTINCT_INT_TYPE
 *
 * which indicate that a given type is not used in the size-specific types.
 */


#if defined(_LP64) || \
    defined(__LP64__)
# define _STLSOFT_SIZEOF_CHAR           (1)
# define _STLSOFT_SIZEOF_SHORT          (2)
# define _STLSOFT_SIZEOF_INT            (4)
# define _STLSOFT_SIZEOF_LONG           (8)
# define _STLSOFT_SIZEOF_LONG_LONG      (8)
#else /* ? data model */
# define _STLSOFT_SIZEOF_CHAR           (1)
# define _STLSOFT_SIZEOF_SHORT          (2)
# define _STLSOFT_SIZEOF_INT            (4)
# define _STLSOFT_SIZEOF_LONG           (4)
# define _STLSOFT_SIZEOF_LONG_LONG      (8)
#endif /* data model */


#if 0
#if defined(__sparcv9)
# error Use of Sun Pro has not yet been verified on 64-bit Sparc. Please contact Synesis Software
#elif defined(__amd64)
# error Use of Sun Pro has not yet been verified on x64. Please contact Synesis Software
# ifndef __LP64__
#  error LP64 memory model is assumed on x64. Please contact Synesis Software
# endif /* __LP64__ */
# define _STLSOFT_SIZEOF_CHAR           (1)
# define _STLSOFT_SIZEOF_SHORT          (2)
# define _STLSOFT_SIZEOF_INT            (4)
# define _STLSOFT_SIZEOF_LONG           (8)
# define _STLSOFT_SIZEOF_LONG_LONG      (8)
#elif defined(__sparc) || \
      defined(__i386)
# define _STLSOFT_SIZEOF_CHAR           (1)
# define _STLSOFT_SIZEOF_SHORT          (2)
# define _STLSOFT_SIZEOF_INT            (4)
# define _STLSOFT_SIZEOF_LONG           (4)
# define _STLSOFT_SIZEOF_LONG_LONG      (8)
#else /* ? data model */
# error Use of Sun Pro has not been verified on any operation system other than x86, x64 and Sparc. Please contact Synesis Software
#endif /* data model */
#endif /* 0 */

/* 8-bit integer */
#define STLSOFT_CF_8BIT_INT_SUPPORT
#define STLSOFT_SI08_T_BASE_TYPE        signed      char
#define STLSOFT_UI08_T_BASE_TYPE        unsigned    char

/* 16-bit integer */
#define STLSOFT_CF_16BIT_INT_SUPPORT
#define STLSOFT_SI16_T_BASE_TYPE        signed      short
#define STLSOFT_UI16_T_BASE_TYPE        unsigned    short

/* 32-bit integer */
#define STLSOFT_CF_32BIT_INT_SUPPORT
#define STLSOFT_SI32_T_BASE_TYPE        signed      int
#define STLSOFT_UI32_T_BASE_TYPE        unsigned    int
#define STLSOFT_CF_LONG_DISTINCT_INT_TYPE

/* 64-bit integer */
#define STLSOFT_CF_64BIT_INT_SUPPORT
#define STLSOFT_CF_64BIT_INT_IS_long_long
#define STLSOFT_SI64_T_BASE_TYPE        signed      long long
#define STLSOFT_UI64_T_BASE_TYPE        unsigned    long long

/* ///////////////////////////////////////////////
 * Language features
 */

/* Anonymous unions */
#ifdef __cplusplus
# define STLSOFT_CF_ANONYMOUS_UNION_SUPPORT
#endif /* __cplusplus */

/* Member constants */
#ifdef __cplusplus
# define STLSOFT_CF_MEMBER_CONSTANT_SUPPORT
#endif /* __cplusplus */

/* Static assertions */
#define STLSOFT_CF_STATIC_ASSERT_SUPPORT

/* sign of modulus of negative numbers */
#define STLSOFT_CF_NEGATIVE_MODULUS_POSITIVE_GIVES_NEGATIVE_RESULT

/* RTTI support */
#ifdef __cplusplus
# define STLSOFT_CF_RTTI_SUPPORT
#endif /* __cplusplus */

/* Exception support */
#ifdef __cplusplus
# define STLSOFT_CF_EXCEPTION_SUPPORT
#endif /* __cplusplus */

#ifdef __cplusplus
# define STLSOFT_CF_THROW_BAD_ALLOC
#endif /* __cplusplus */

/* Namespace support */
#ifdef __cplusplus
# define STLSOFT_CF_NAMESPACE_SUPPORT
#endif /* __cplusplus */

#ifdef __cplusplus
# define STLSOFT_CF_std_NAMESPACE
#endif /* __cplusplus */

/* return void */
#ifdef __cplusplus
# define STLSOFT_CF_COMPILER_SUPPORTS_RETURN_VOID
#endif /* __cplusplus */

/* Template support */
#ifdef __cplusplus
# define STLSOFT_CF_TEMPLATE_SUPPORT
#endif /* __cplusplus */

/* #define STLSOFT_CF_TEMPLATE_TYPE_REQUIRED_IN_ARGS */

/*  */
/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_FUNCTION_SIGNATURE_FULL_ARG_QUALIFICATION_REQUIRED

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_EXCEPTION_SIGNATURE_SUPPORT

/* !!! Assumed. Not yet verified !!! */ /* #define STLSOFT_CF_EXCEPTION_SPEC_EXPENSIVE */

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_FUNDAMENTAL_ARGUMENT_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEM_FUNC_AS_TEMPLATE_PARAM_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEMBER_TEMPLATE_OVERLOAD_DISCRIMINATED

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEMBER_TEMPLATE_CTOR_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEMBER_TEMPLATE_CTOR_OVERLOAD_DISCRIMINATED

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEMBER_TEMPLATE_RANGE_METHOD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_MEMBER_TEMPLATE_CLASS_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_SPECIALISATION_SYNTAX

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_OUTOFCLASSFN_QUALIFIED_TYPE_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_std_char_traits_AVAILABLE

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_PARENT_TYPES_CAN_BE_USED_IN_NON_TEMPLATE

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_PARENT_TYPES_CAN_BE_USED_IN_TEMPLATE

#define STLSOFT_CF_EXPLICIT_KEYWORD_SUPPORT

#define STLSOFT_CF_MUTABLE_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TYPENAME_PARAM_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TYPENAME_TYPE_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TYPENAME_TYPE_DEF_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TYPENAME_TYPE_MIL_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TYPENAME_TYPE_RET_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_QUALIFIER_KEYWORD_SUPPORT

/* !!! Assumed. Not yet verified !!! */ /* #define STLSOFT_CF_MOVE_CONSTRUCTOR_SUPPORT */

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_ADL_LOOKUP_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_TEMPLATE_TEMPLATE_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_VENEER_SUPPORT

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_ALLOCATOR_BASE_EXPENSIVE

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_COMPILER_WARNS_NO_PUBLIC_DTOR

/* Shims are supported?
 */
/* #define STLSOFT_CF_TEMPLATE_SHIMS_NOT_SUPPORTED */

/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_OPERATOR_BOOL_AS_OPERATOR_POINTER_TO_MEMBER_SUPPORT
/* !!! Assumed. Not yet verified !!! */ #define STLSOFT_CF_OPERATOR_NOT_VIA_OPERATOR_POINTER_TO_MEMBER_SUPPORT

#if defined(_STLSOFT_CUSTOM_ASSERT)
 /* You have defined the pre-processor symbol _STLSOFT_CUSTOM_ASSERT,
  * which stipulates that you will be providing your own assert. This
  * requires that you have defined _STLSOFT_CUSTOM_ASSERT() as a macro
  * taking 1 parameter (the condition to assert).
  *
  * Suppose you have a function _DisplayAssert(), which has the
  * following signature:
  *
  *   void _DisplayAssert(char const* file, int line, char const* expression);
  *
  * Presumably you would also have your own assert macro, say MY_ASSERT(),
  * defined as:
  *
  *   #define MY_ASSERT(_x) ((void)((!(_x)) ? ((void)(_DisplayAssert(__FILE__, __LINE__, #_x))) : ((void)0)))
  *
  * so you would simply need to define _STLSOFT_CUSTOM_ASSERT() in terms of
  * MY_ASSERT(), as in:
  *
  *  #define _STLSOFT_CUSTOM_ASSERT(_x)    MY_ASSERT(_x)
  *
  * where
  */
# define __STLSOFT_CF_ASSERT_SUPPORT
# define STLSOFT_CF_ASSERT_SUPPORT
# define STLSOFT_ASSERT(_x)                     _STLSOFT_CUSTOM_ASSERT(_x)
# if defined(_STLSOFT_CUSTOM_ASSERT_INCLUDE)
#  define   __STLSOFT_CF_ASSERT_INCLUDE_NAME    _STLSOFT_CUSTOM_ASSERT_INCLUDE
# else
#  error You must define _STLSOFT_CUSTOM_ASSERT_INCLUDE along with _STLSOFT_CUSTOM_ASSERT()
# endif /* !_STLSOFT_CUSTOM_ASSERT_INCLUDE */
#else /* ? _STLSOFT_CUSTOM_ASSERT */
# define __STLSOFT_CF_ASSERT_SUPPORT
# define STLSOFT_CF_ASSERT_SUPPORT
/* # define   __STLSOFT_CF_USE_cassert */
# define __STLSOFT_CF_ASSERT_INCLUDE_NAME       <assert.h>
# define STLSOFT_ASSERT(_x)                     assert(_x)
#endif /* _STLSOFT_CUSTOM_ASSERT */

/* /////////////////////////////////////////////////////////////////////////
 * Calling convention
 */

#define STLSOFT_CF_CDECL_SUPPORTED

#ifdef STLSOFT_CF_CDECL_SUPPORTED
# define STLSOFT_CDECL
#endif /* STLSOFT_CF_CDECL_SUPPORTED */

/* /////////////////////////////////////////////////////////////////////////
 * Inline assembler
 */

/* #define STSLSOFT_INLINE_ASM_SUPPORTED */
/* #define STSLSOFT_ASM_IN_INLINE_SUPPORTED */

/* /////////////////////////////////////////////////////////////////////////
 * inline support
 */

#define STLSOFT_CF_C99_INLINE

/* /////////////////////////////////////////////////////////////////////////
 * If <cwchar> gets included after <stdio.h> or <cstdio> then it fails to
 * declare mbstate_t and various wchar functions, so include it now to try
 * and reduce problem (too late if <stdio.h> has already been included.)
 * http://forum.java.sun.com/thread.jspa?messageID=10035724
 */

#ifdef STLSOFT_LINUX_STDIO_ORDER_BUG
# ifdef __cplusplus
#  include <cwchar>
# endif /* __cplusplus */
#endif /* STLSOFT_LINUX_STDIO_ORDER_BUG */

/* /////////////////////////////////////////////////////////////////////////
 * Compiler warning suppression
 */

/* /////////////////////////////////////////////////////////////////////////
 * Helper definitions
 */

#undef _STLSOFT_SUNPRO_VER_
#undef _STLSOFT_SUNPRO_VER_MAJOR
#undef _STLSOFT_SUNPRO_VER_MINOR

/* ////////////////////////////////////////////////////////////////////// */

I hope that's clear. ;-)

In the next post I'll discuss the other changes required to get Pantheios built with the -library=libCstd

Fit vs Fat

No, this has nothing to do with my ongoing exploits in eeking out greater and greater performance of my aging hulk.

Rather, it's about an approach to library design that errs on the side of providing the minimum possible, rather than the maximum potential permutations of functionality.

Of course, age, learning, evolving paradigms, and backwards-compatibility all tend to result in accretion of functionality. And there's nothing going to happen in 1.9.x to start removing code. But as of 1.10 I'd like to rewrite several popular libraries to address the crustification.

To guide me in this, I'm looking for users to write in and make their complaints/requests.

Obvious (to me) candidates for face-lifts include:

• FileSystem Library
• System Library
• Windows Registry Library (see include/winstl/registry/*)
• Windows Controls
• Error Library (in fact this is already happening)
• Containers Library
• String Library (see this post)

Do you have any more? If so, please let me know, either here or on the STLSoft newsgroup.

static_string semantics redux

I'm currently using stlsoft::static_string to test the soon-to-be-released FastFormat library. (btw, if you're a user/reader of mine, you're probably heartily sick of the phrase "soon-to-be-released", I hear ya!)

static_string is a std::string-like string class that has a fixed internal buffer. It relies on contracts to force on the user respect for its limitations, to whit you may not attempt to cause the string contents to exceed the internal size.

That's all very well and good, as it's clear. What's probably not so cool is that people tend not to either grok, or want to respect, the principles of contract programming.

So it's occuring to me that static_string should evolve for STLSoft 1.10 and change its contracts from "you may not try to expand me beyond my capacity limit" to "if you try and expand me beyond my capacity limit" I will inform you (by an exception).

There's another evolution that would be good, and that's one that would be able to work atop an external character buffer. But that brings the notion of policy classes into play, and they suck in general.

So, I'm starting to think that we'll have either a separate class (template), or a base utility template that gets specialised in two different ways by, say, static_string and external_string class templates.

Watch this space ...

STLSoft 1.10 preview

There're several things that've been waiting to go into the 1.10 release for quite a while - some over 2 years! - and it's beyond ridiculous.

So, from the end of this week onwards, I'm going to make a preview release of the next version of the library available alongside the main release. The first version of this will contain only the platformstl::properties_file component, whic his needed for the soon-to-be-released alpha release of the much-delayed FastFormat library.

This simple but sophisticated properties file reader class provides a non-mutable vector like interface, along the following lines:

class properties_file
{
public: /// Member Types
  typedef stlsoft::string_view view_type;
  typedef values_map_type::value_type value_type;
  typedef values_map_type::const_iterator const_iterator;
  typedef size_t size_type;

public: /// Construction
  explicit properties_file(char const* fileName);

public: /// Accessors
  view_type operator [](char const* propertyName) const;

  size_type size() const;

  const_iterator begin() const;
  const_iterator end() const;

  . . .
};




The only exotic part of it is the use of stlsoft::string_view, rather than a string value type. I'll discuss this in more depth in a future post; for now you can rest assured that it's to do with not allocating any memory we don't need to. ;-)

STLSoft 1.9.31 released

This release includes some refactoring of the exception hierarchy of the main project (STLSoft) and several sub-projects (COMSTL, UNIXSTL and WinSTL).

The root exception used to be stlsoft::os_exception, as a nod to the fact that the two main sub-projects - UNIXSTL and WinSTL - are STL extensions over UNIX and Windows APIs. However, that's never seemed to sit comfortably, so this is now changes. The root exception is stlsoft::project_exception, from which stlsoft::os_exception derives.

The exceptions in UNIXSTL and WinSTL continue to derive from stlsoft::os_exception, but those of COMSTL now derive direct from stlsoft::project_exception.

Coming up:

This refactoring underpins further refactoring around exception/error handling, in the Windows Registry library in particular, which itself will underpin functional enhancements to that library (originally requested (and implemented) by Austin Ziegler). This stuff's likely to appear in 1.9.33

The next release (1.9.32) is likely to contain compatibility fixes for SunStudio (on Intel at first; the Solaris stuff's likely to be another week or so).