Friday, November 21, 2008

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.