#85 Create new OWL class to encapsulate Windows code page functions

[Joe Slater]

While Unicode is recommended for new application development, there is still a need to support the use of code pages:

http://msdn.microsoft.com/en-us/library/windows/desktop/dd317752(v=vs.85).aspx

The attached file defines a proposed new class TCodePages to encapsulate the WINAPI functions dealing with code pages. The class has been tested and confirmed to work properly.

[Vidar Hasfjord]

Hi Joe,

Although, like you say, code pages should be obsoleted by Unicode, this functionality may be required for legacy code, and since it is core Windows functionality, encapsulating it is clearly within the remit of OWLNext.

I generally like your approach, especially the support for standard iteration. I recognise the Singleton pattern here, and I would ideally like it expressed in the conventional manner. This would allow you to replace the static file-local CodePageList with private state in the singleton.

Instead of the many indexing member functions, I would prefer to have these functions as members of TCodePage instead. E.g. I want to do codepages[i].GetName() instead of codepages.GetName(i).

Kudos for linking to MSDN in the documentation.

Code review:

• Use new-style Doxygen file description block with license link, e.g. see "include/owl/transfer.h".
• Don't use the "\class" tag in the documentation. Rationale: Doxygen figures out the class name automatically. Removing use of "\class" is on the TODO list for the existing documentation.
• Start Doxygen documentation with a brief descriptive sentence followed by period/full stop, in the leading verb style, e.g. "Encapsulates Windows code page functionality". Rationale: I have configured Doxygen to extract its brief description from the first sentence.
• Prefer using statements to typedef. Rationale: Modern style.
• Use an alias for the code page ID type, e.g. using TCodePageId = uint.
• Use int for indexes and sizes. Rationale: Refer to signed vs unsigned expert advice. Consensus seems to be to use signed types for quantities.
• Opening curly brace should be on its own line.
• Do not indent access specifiers.
• Types should have prefix "T"; ref. ListCodePage. Rename to TCodePageList; more clearly a noun, and matches variable CodePageList.
• Rename GetCount to size, Remove to clear and GetCodePageObject to at? Rationale: Follow standard container conventions consistently.
• Doxygen grouping tokens "@{" and "@}" outside Doxygen comments.
• Doxygen group descriptions must be tagged with "\name", not "\Code".
• Include the reference links to MSDN in Doxygen comments. Rationale: Should be part of the generated documentation. Tip: Leave out the argument part of the URL (e.g. "(v=vs.85)"), unless it is relevant.
• For BuildCodeList_, use two callback functions instead of one multiplexed one that depends on global state. Tip: Consider using lambdas instead of file-local callbacks.
• In GetIndex, use a standard algorithm to search.
• Make members const-correct.
• std::vector::resize does not deallocate; use std::vector::shrink_to_fit.

[Vidar Hasfjord]

Here is a self-contained version of BuildCodeList_ that eliminates the global variables. It can be used to initialise a private member of TCodePages, rewritten as a conventional singleton.

:::C++
//
// Builds the code page list.
// Note: This function uses static memory, hence is not thread-safe.
// Uses ::EnumSystemCodePages to query supported and installed code pages.
//
// Reference:
//   http://msdn.microsoft.com/en-us/library/windows/desktop/dd317825(v=vs.85).aspx
//   http://msdn.microsoft.com/en-us/library/windows/desktop/dd317809(v=vs.85).aspx
//
auto BuildCodeList_() -> TCodePages::TCodePageList
{
  using namespace std;
  static TCodePages::TCodePageList codepages;
  codepages.clear();
  auto addSupported = [](LPTSTR codePageString) -> BOOL
  {
    const auto idCodePage = static_cast<uint>(_ttol(codePageString));
    auto s = tstring{TCodePages::GetCodePageInfoEx(idCodePage).CodePageName};
    if (s.empty()) s = to_tstring(idCodePage); // Use code page value for empty names
    codepages.push_back({idCodePage, false, s});
    return TRUE;
  };
  ::EnumSystemCodePages(addSupported, CP_SUPPORTED);
  sort(begin(codepages), end(codepages));

  auto initInstalled = [](LPTSTR codePageString) -> BOOL
  {
    const auto idCodePage = static_cast<uint>(_ttol(codePageString));
    auto i = find_if(begin(codepages), end(codepages), 
      [&](const TCodePages::TCodePage& c) { return c.CodePageId == idCodePage; });
    if (i != end(codepages)) i->Installed = true;
    return TRUE;
  };
  ::EnumSystemCodePages(initInstalled, CP_INSTALLED);
  return codepages;
}

[Joe Slater]

Hi Vidar,

I recognise the Singleton pattern here, and I would ideally like it expressed in the conventional manner
 

I've simplifed the class. It is now completely a static class. A user is free to instantiate if they wish, but it does nothing other than to perhaps provide a shorter name to reference the member functions:

:::C++
TCodePages tcp;
tcp.SetANSICodePageId(mycp);
// instead of
TCodePages::SetANSICodePageId(mycp);

I would prefer to have these [indexing] functions as members of TCodePage
 

A major part of the simplification was getting rid of all that. I now have a member function that returns a const reference to the container. The user can use any of the std::vector routines they wish that are allowed for a const. This eliminates the need for replicating all of those functions.

Use new-style Doxygen file description block with license link, e.g. see "transfer.h"
 

Okay, its nice to have a proper example. Well, mostly anyway, as it doesn't follow the "rules" completely.

Don't use the "\class" tag in the documentation
 

Done.

Start Doxygen documentation with a brief descriptive sentence followed by period/full stop.
 

Done, even though "transfer.h" doesn't always do that.

Prefer using statements to typedef.
 

Done.

using TCodePageId = uint.
 

Done.

Use int for indexes and sizes.
 

Not done. It would seem that the designers of the standard (e.g., vector and string) agree with me. Indexes and sizes are unsigned quantities; signed values make no sense. Since I've gotten rid of most of that, it no longer matters anyway.

Opening curly brace should be on its own line.
 

Done, even though "transfer.h" doesn't always do that (e.g., namespace owl {).

Types should have prefix "T"
 

Done.

Rename GetCount to size, GetCodePageObject to at.
 

No longer applicable.

Rename Remove to clear
 

Done.

Doxygen grouping tokens "@{" and "@}" outside Doxygen comments.
 

Done (if I understood correctly).

Doxygen group descriptions must be tagged with "\name", not "\Code".
 

Done (my mistake; I knew that).

Include the reference links to MSDN in Doxygen comments. Leave out the argument part of the URL (e.g. "(v=vs.85)"), unless it is relevant.
 

Done.

In GetIndex, use a standard algorithm to search.
 

I do not know of any that will for a match return the index of the container. That is crucial. Not done. While I'm not posting the entire updated source yet until you respond, here is the updated Doxygen example:

:::C++
// The following sample code illustrates retrieving the current code page identifier,
// loading the code page list in a TComboBox control, initializing the selection of
// the control to the currently selected code page identifier, and changing the
// current code page to the user selection.
//
TComboBox* cbox = new TComboBox(/*...*/);
// ...
for (auto &cp : TCodePages::GetCodePageList())
  cbox->AddString(cp.Name);
auto iCur = TCodePages::GetIndex(TCodePages::GetANSICodePageId());
if (iCur != TCodePages::CodePageNotFound) cbox->SetSelIndex(iCur);
// ...
auto iSel = cbox->GetSelIndex();
if (iSel >= 0) TCodePages::SetANSICodePageId(TCodePages::GetCodePageList().at(iSel).CodePageId);

Make members const-correct.
 

No longer applicable.

std::vector::resize does not deallocate; use std::vector::shrink_to_fit.
 

If this source of information is credible, neither one necessarily does:

shrink_to_fit
resize

So I have included them both, in hopes that a given implementation will deallocate for at least one of them.

For BuildCodeList_, use two callback functions… Consider using lambdas.
 

Done.

Here is a self-contained version of BuildCodeList_…
 

While I have implemented most of that, I have not gotten rid of the global variables. Your method causes the code page list to be cleared and recreated every time it is called, which defeated the purpose of my design. It needs to be created only once; otherwise it is memory and performance inefficient. Having the code page list local to that function makes it inaccessible to the other functions that need it. And it would appear that perhaps you intended for the calling functions to take the return value and make a persistent copy of it which would also be memory and performance inefficient. So CodePageList and builtList remain global.

Using builtList instead of just checking CodePageList.empty() was an attempt to thwart off multi-threading issues (albeit an imperfect one), as well as the possibility that Windows simply could (in theory) not return any supported code pages in which it would just keep trying repeatedly.

Note: This function uses static memory, hence is not thread-safe.
 

Here is an example from which I adapted, which claims to be multi-thread-safe, but it was written in MFC and I do not know the equivalent non-MFC to implement:

http://www.codeproject.com/Articles/16638/Enumerating-System-Code-Pages

Perhaps you could enlighten me, and I will implement it.

[Joe Slater]

Here is a PDF document that might be of interest with respect to multi-threading: C++ and the Perils of Double-Checked Locking.

[Vidar Hasfjord]

Hi Joe,

The following is just advice and my opinion. This class does not affect the rest of OWLNext, so I'll leave you in charge of it's design and implementation. Put it together the way you want it! :-)

I've simplifed the class. [...] A user is free to instantiate if they wish

In other words, you still do not use the conventional Singleton pattern. Any particular reason for that? If not, it would be good to have recognisability and consistency (we use Singleton in a few other places in OWLNext).

For your convenience, here is an outline of the Meyers Singleton:

:::C++
class TCodePages
{
public:

  static auto GetInstance() -> const TCodePages&
  {
    static TCodePages c;
    return c;
  }

  //...

private:

  TCodePages();

  TCodePageList CodePageList;

};

The private constructor makes the class non-instantiable by clients. CodePageList is now a member (not a global), and the Meyers trick, using a static local variable, ensures that it is created only once, and on demand, i.e. it is not created if not used. The private constructor would initialise CodePageList using something like my suggested factory function BuildCodeList_. Hence no need for your boolean builtList global flag. See rule 10 and 21 of "C++ Coding Standards" (Sutter/Alexandrescu).

The linked pages in my previous post has further links to more information about Singletons.

["transfer.h"] doesn't follow the "rules" completely.

Right, "transfer.h" may itself need some improvements. In this case, I only refer to it as an example of the file description block, though.

[Using signed quantities] Not done. It would seem that the designers of the standard (e.g., vector and string) agree with me.

I've spent a fair amount of time on eliminating issues due to signed/unsigned mismatches in OWLNext already, most caused by the ill-advised decision by those designers. :-)

Edit: I am unfair on the designers here. They had to work with design constraints, in particular portability to 8-bit and 16-bit platforms where an extra bit really counts. See Alf's answer to the question "Why is size_t unsigned?" at StackOverflow.

Note that Bjarne Stroustrup himself warns about using unsigned integers in "The C++ Programming Language" (section 4.4) and many coding standards (including Google's C++ Style Guide) follow his advice. Here is an article that argues the case against unsigned quantities:

http://www.soundsoftware.ac.uk/c-pitfall-unsigned

In any case, we should try to be consistent. This is difficult in OWLNext since the Windows API uses signed quantities and the C++ containers do not. But, the current practised coding standard in OWLNext is to use signed quantities. So, casts are generally toward signed (e.g. static_cast<int>(c.size())). I've now included this as a rule in our Coding Standards.

I do not know of any [standard algorithm] that will for a match return the index of the container.

You can use find_if and distance:

:::C++
auto i = find_if(b, e, [&](const TCodePage& c) 
  { return c.CodePageId == idCodePage; });
return i != e ? distance(b, i) : -1;

Aside: By the way, this is a nice example of why indexes should be signed. Here distance naturally returns a signed value (iterator_traits::difference_type).

I have included [both shrink_to_fit and resize], in hopes that a given implementation will deallocate for at least one of them.

Any sane implementation of shrink_to_fit will deallocate (at least some) excessive capacity. Note that resize sets the size, which is different. A vector has size and capacity. The latter can be larger than the former. shrink_to_fit will never change the size (i.e. remove elements). So you need to remove the elements explicitly. But use clear() instead of resize(0). It is clearer (pun intended).

While I have implemented most of [BuildCodeList_], I have not gotten rid of the global variables.

Please do. :-)

Note that in my suggested Singleton solution, BuildCodeList_ is called at most once. You don't need anything extra (i.e. your globals) to arrange for that. It is handled by the Meyers trick.

[multi-threading issues]

By using thread-local storage (now standard) for the static codepages in my BuildCodeList_, the function becomes fully thread-safe.

However, this is not needed. Since this function is only called during the initialisation of a local static (the Meyers Singleton), which is guaranteed to be properly synchronised by the C++ standard, a race condition can never occur. (Note: Initialisation of local statics, such as used by the Meyers Singleton, wasn't thread-safe until C++11. So I assume a compliant compiler in my argument here.)

Here is a PDF document [Meyers/Alexandrescu article on double-checked locking]

I've read this aspirin-promoting article before, thank you very much. :-)

For a C++11 perspective on this issue, see:

http://preshing.com/20130930/double-checked-locking-is-fixed-in-cpp11

PS. If you are interested in multi-threading, see my article "Multi-threading and OWLNext" which I wrote during preparations for 6.32, in which I performed a light review of the OWLNext code in this regard.

[Joe Slater]

Hi Vidar,

The following is just advice and my opinion… Put it together the way you want it
 

I appreciate that, but I do wish to comply with the OWLNext standards in place. And again I appreciate your patience with me as I am in new information overload (e.g., multi-threading, multi-byte, Unicode, standard containers and strings, OWLNext, OWLNext Coding Standards, C++11, TurtoiseSVN, SourceForge, …). I will catch up to the 21st century! :-)

But use clear() instead of resize(0)
 

I was. I had clear, resize, and shrink_to_fit — in that order. But this is now a mute point (more to come).

Regarding signed vs. unsigned…

See Alf's answer to the question "Why is size_t unsigned?" at StackOverflow.
 

Note that there are more up votes for my opinion on this matter. :-)

Here is an article that argues the case against unsigned quantities: www.soundsoftware.ac.uk/c-pitfall-unsigned
 

It is ironic that you'd reference an audio/music source, as I develop such as well. And thanks; I needed a good laugh! :-)

If you take an unsigned 0 and subtract 1 from it, the result wraps around, leaving a very large number (2^32-1 with the typical 32-bit integer size).
 

Most likely likewise for signed values: (MIN_INT - 1) tends to give you MAX_INT. But even worse, since doing so is undefined in C, there's no telling what you'll get.

Intuitively the two types seem to map fairly reasonably to mathematical notions of integers and natural numbers… Unfortunately, this is not a reliable intuition.
 

An empty statement.

[example] the programmer should simply have checked that total was big enough before doing the calculation. Well, yes—but they didn't, and the programmer of this example was very far from stupid and inexperienced.
 

You don't have to be stupid and inexperienced to make a mistake. Here, the author correctly identifies the source of the logic problem, but procedes to blame it on unsigned and compilers. Put the blame where it belongs.

“Unsigned has a bigger range.” Only a bit bigger.
 

Spoken like a true politician. For a 32-bit int, only one bit means 2 billion valid values I'm throwing away needlessly if I buy into this argument.

Consider TPoint and TSize… computing TSize from a TPoint(MIN_INT, MIN_INT) and TPoint(MAX_INT, MAX_INT) will no doubt given me invalid values since TSize uses signed values (not OWLNext's fault; Microsoft's).

As a mathematician as well, I believe in proper representation of math principles as best as possible. Call a spade a spade.

Enough of the soap box; back to relevant discussion.

For your convenience, here is an outline of the Meyers Singleton
 

Thanks. That was quite helpful. I have implemented this as-is, with exceptions…

I moved GetInstance to private; I saw no reason it should be made publicly available.

I still have CodePageList implemented in an anonymous namespace, rather than a data member. There are a couple of reasons for this…

One, I was led to believe in my recent OWLNext activity that functions and variables should not be in the class definition unless really needed. And in this case, it isn't.

Two, the lambda Windows callback functions couldn't readily get to it.

the current practised coding standard in OWLNext is to use signed quantities
 

For this reason, I have changed GetIndex to return an int. It's quite unlikely there will ever be 2G+ code pages, and this is antiquated technology as well.

[GetIndex] You can use find_if and distance
 

Thanks; that was useful and informative. But as a self-proclaimed efficiency expert, I dug around and chose to implement std::equal_range since it performs a binary search and the list is sorted.

Please do [get rid of buildList]
 

I have, because it makes little sense now using the Meyers Singleton method. However, it originally had an additional purpose such that clear (f.k.a., Remove) could be used, and the list would get reloaded as needed. Now that can't be done and be thread-safe. So I have also removed the clear function; I had no need for it, but my efficiency pedanticism wanted me to make it available. Now I fear it is too dangerous to implement, as an application that used it could not thread-safely have the list re-created.

Due to the numerous changes from the original, I have attached the latest files.

[Vidar Hasfjord]

Hi Joe,

[Regarding new things to learn,] I will catch up to the 21st century!

Thanks for contributing to the modernising of OWLNext. This is a direction I have championed, and it is good to have support.

With regard to learning modern C++, I recommend one of Stroustrup's latest books, e.g. his short introduction "A tour of C++", which is well regarded by experts, or his teaching text book "Programming - Principles and Practice using C++", which takes the modern approach to teaching C++. For coding standards, I recommend "C++ Coding Standards" (Sutter/Alexandrescu). For detailed knowledge about C++ and pitfalls, see Meyers' and Sutter's books ("Efficient C++" and "Exceptional C++", respectively). For C++ meta-programming, I recommend "Modern C++ Design" (Alexandrescu) and "C++ Template Metaprogramming" (Abrahams/Gurtovoy). And, get the seminal text on Design Patterns (Gamma/Helms/Johnson/Vlissides), if it is not already on your book shelf.

[article arguing against unsigned] thanks; I needed a good laugh! :-)

Reading that, at first I thought you found the article well-written and humorous, like I did, but then, as you proceeded to attack its arguments, I understood it was a dismissive comment, and my heart sank. :-)

I think the author argues a very good point, which I have seen argued elsewhere as well, and which is one that convinced me to change (I used to follow the standard library and use size_t everywhere): We do not think in terms of modulo arithmetic when we write expressions, so we do easily make mistakes when unsigned quantities are involved. Another take on this by some other author went something like this: "With modulo arithmetic there is a huge discontinuity at 0, and it is too close for comfort".

Since we are developing a library for Windows Desktop applications, and we have 64-bit integer types readily available, I do not buy range arguments for unsigned, as far as OWLNext is concerned.

Regardless, thanks for falling into line with my stated coding standard for OWLNext.

I moved GetInstance to private; I saw no reason it should be made publicly available.

This is highly unconventional and odd for a Singleton. The point of a Singleton is that it is an ordinary class in every way except that its construction is restricted to allow only one instance (or none) to exist throughout the program. Hence, the constructor is made private and access is only provided through GetInstance.

I guess the reason for your design is that your eyes were clouded by your already existing static member functions that access static state. With a conventional Singleton, these would be ordinary members accessing the Singleton's private state.

Another way of looking at it is that you should be able to convert a Singleton into an ordinary class, just by replacing GetInstance by a public constructor.

I was led to believe in my recent OWLNext activity that functions and variables should not be in the class definition unless really needed. And in this case, it isn't.

Touche. :-)

But note the rationale for that advice: Implementation hiding. There are better ways to achieve implementation hiding than disfiguring a Singleton into the unrecognisable. Use the Pimpl idiom if you must. However, you already expose your internal container in your class interface, so it wouldn't hide much in this case.

So my bottom line recommendation is to make your member functions non-static and follow the conventional outline of the Meyers Singleton. It will be instantly recognisable by any programmer with design patterns experience, hence more maintainable.

Two, the lambda Windows callback functions couldn't readily get to it.

See my BuildCodeList_ for how to solve that using a function-local static. Then rewrite your constructor using member initialisation like so:

:::C++
TCodePages::TCodePages()
  : CodePageList(BuildCodeList_())
{}

If you want to fully optimize (and I guess you do :-), you can use std::move to ensure there is no copying of the list involved:

:::C++
auto BuildCodeList_() -> TCodePages::TCodePageList
{
  static TCodePages::TCodePageList codepages;

  // ... use `codepages` in your callbacks ...

  return std::move(codepages);
}

Alternatively, if you are more inclined to think in C, use a static pointer:

:::C++
auto BuildCodeList_() -> TCodePages::TCodePageList
{
  TCodePages::TCodePageList codepages;
  static TCodePages::TCodePageList* pCodepages;
  pCodepages = &codepages;

  // ... use `pCodepages` in your callbacks ...

  return codepages; // No copying here, see RVO.
}

See "Return value optimization" on why this doesn't involve copying in modern compilers.

std::equal_range

Since you are not really interested in the upper bound of the match, you can simply use std::lower_bound. However, note that, on small lists, a binary search may not actually be faster than a linear search, due to the overhead of the more complex logic, branching and memory access pattern. So this could be a premature optimisation (ref. item 8 in "C++ Coding Standards").

I notice you have put inlined functions in the class definition, rather than out-of-class in the header (which is the convention used by the OWL designers). I actually like your style better. The counter-argument is that it makes the class definition less readable, but this is less relevant today with outlining features in editors (just collapse all member definitions to get a better overview), and with code browsers and Doxygen documentation, we have better ways to get the overview of a class anyway.

Aside: I am a little torn about were we should put our Doxygen documentation. Now it goes with definitions, which means both header and implementation files are affected. There is an argument for putting it all in the implementation files to reduce build dependencies and decrease header size (faster build?). But separating class documentation from the definition means more hassle (in particular, we would need to use the tag \class <name>, which may get out of sync). I welcome your view on this.

Nitpicks:

• Use of the inline specifier within a class definition is redundant.
• For ABI stability, resist inlining. Remember, we can change implementation files while retaining ABI stability. This stability-enhancing feature is lost if you include code in headers. This is on my TODO list for the whole library; there is currently far too much use of inlining.
• FindCodePage is a file-local helper, so it should have a trailing underscore (Coding Standards).
• Naming: Acronyms within entity names should be CamelCase (Coding Standards), e.g. "SetAnsiCodePageId", not "SetANSICodePageId".
• Do not indent preprocessor directives; keep them at column 0. Also, for readability, my preference and recommendation is now to add empty lines before and after a directive.
• Avoid preprocessor directives interspersed within the code (Coding Standards). Instead, define macros at the top of the file, and use those macros in the code instead, e.g. auto SetAnsiCodePageId(/*...*/) -> bool {return OWL_SET_ACP_(idCodePage);}. For Windows CE, this macro will call ::SetACP. Otherwise, it will expand to false. However, try to keep such macros to the implementation files, as not to pollute the client's global namespace.

[Joe Slater]

Hi Vidar,

I got sidelined with TListViewCtrl.

This is highly unconventional and odd for a Singleton.
 

I'm okay with that. This is not about creating a Meyers Singleton. This is about creating the code page list thread-safely. If it helps, call it the new Slater-Meyers convention. :-)

make your member functions non-static
 

I'm not okay with that. All but two of the functions, do not need the code page list. And I do not wish to punish users with creating the code page list when not needed for those functions.

I guess the reason for your design is that your eyes were clouded by your already existing static member functions…
 

Not clouded, but rather quite clear. These are static functions.

resist inlining
 

No, I can't do that. That would result in putting the registers and flags on the stack, jumping to a new address emptying the processor instruction cache, only to do the simple operation to do, restoring the registers and flags on the stack, and jumping to the caller address emptying the processor instruction cache. That's just too much of a performance penalty, even with the fast processors we have today. MS perhaps recognized this, as Vista to Windows 7 was mostly just optimizing code.

[equal_range] you can simply use std::lower_bound
 

Yep, I missed that one; thanks. But don't you think upper_bound would be better? :-)

inlined functions in the class definition
 

I think it makes it clearer, but also more efficient in that the header file is smaller.

torn about were we should put our Doxygen documentation
 

My feelings are this… For class definitions, inline member functions, and class definitions within a class (e.g., enums), they go in the header. But for non-inline member functions defined in a .cpp file, they go there simply for reducing the size of the header file. I'm not as concerned about compiler efficiency as I am ultimate application efficiency. I do believe compilers can handle comment lines rather quickly (if not, they need optimizing!).

Ideally, there should be no reason why users need to examine header or source files. I find myself still in the habit of doing that, because the original OWL not only had errant information in the help files, but missing information (i.e., undocumented features). Unfortunately, OWLNext is still lacking documented functions. Be rest-assured, that any contributions I make, will not be amiss (intentionally) of Doxygen comments.

the inline specifier within a class definition is redundant
 

Well, there is the case of the unlikely One Definition Rule. But I have conceded and removed the inline keyword.

FindCodePage should have a trailing underscore
 

Of course; I knew that. It now does, as well as the local CodePageList.

Acronyms within entity names should be CamelCase
 

Done, with ANSI and OEM.

Do not indent preprocessor directives
 

Done.

Avoid preprocessor directives interspersed within the code
 

Done.

keep such macros to the implementation files
 

Since it applies to the header file with inline functions, I un-define them at the end of the header file. Leaving it here as an inline function allows developers to not have to rebuild a special CE version of the library (unless OWLNext has other CE-specific non-inlines). Only the app that gets generated may have special builds.

continue work on this on the trunk
 

Done [r2966]. With the restriction of 8-character filenames having been lifted, I have appropriately pluralized the filenames — with apologies to the Norwegians. :-)

I believe I'm done with this, and changing the status.