icu4c API proposal: enable better modularization

Goals:
1. Allow smaller application executables when using ICU static libraries.
2. Allow to build the common ICU library without any conversion code.

I propose to add and modify a small number of API functions to make
progress toward the two goals above.

Expiration: Thursday, 2004-sep-02

markus

Specifically:

* Add 2 functions to UnicodeString

New constructor from a const char * with only invariant characters
   UnicodeString("invariant characters", -1, US_INV)

New extract() function to extract a UnicodeString with only invariant
characters into a char * buffer
   extract(start, length, char *target, targetCapacity, US_INV)

Unlike the existing constructor and extract() function used for this
purpose, these will only perform invariant-character conversion, never
"real" conversion, and will thus not have a code dependency on the
conversion code. The US_INV parameter is to distinguish the function
signatures.

* Make some UnicodeSet functions not virtual

UnicodeSet has a rather arbitrary mix of virtual and non-virtual
functions, and is documented as not being designed for subclassing. I
propose to make some virtual functions - applyPattern() and toPattern() -
non-virtual, which then removes a code dependency of the core UnicodeSet
code (and its vtable) on other code like for character properties.

I could make all functions non-virtual that aren't inherited as virtual
from a base class, but it's not necessary. Opinions?

* Add UCONFIG_NO_CONVERSION to uconfig.h

As usual...

* Details for UnicodeString (unistr.h) and uconfig.h

For small executables using static ICU libraries, code interdependencies
need to be reduced. In C/C++ this means that implementation files should
depend on only a small number and depth of other implementation files. For
example, it should be possible to use most of UnicodeString without
depending on conversion code, and to use parts of the UnicodeSet API
without depending on character properties.

/**
  * Constant to be used in the UnicodeString(char *, int32_t, EInvariant)
constructor
  * which constructs a Unicode string from an invariant-character char *
string.
  * About invariant characters see utypes.h.
  * This constructor has no runtime dependency on conversion code and is
  * therefore recommended over ones taking a charset name string
  * (where the empty string "" indicates invariant-character conversion).
  *
  * @draft ICU 3.2
  */
#define US_INV UnicodeString::EInvariant::kInvariant

   /**
    * Constant to be used in the UnicodeString(char *, int32_t, EInvariant)
constructor
    * which constructs a Unicode string from an invariant-character char *
string.
    * Use the macro US_INV instead of the full qualification for this
value.
    *
    * @see US_INV
    * @draft ICU 3.2
    */
   enum EInvariant { kInvariant };

   /**
    * Copy the characters in the range
    * [<tt>start</TT>, <tt>start + length</TT>) into an array of
characters.
    * All characters must be invariant (see utypes.h).
    * Use US_INV as the last, signature-distinguishing parameter.
    *
    * This function does not write any more than <code>targetLength</code>
    * characters but returns the length of the entire output string
    * so that one can allocate a larger buffer and call the function again
    * if necessary.
    * The output string is NUL-terminated if possible.
    *
    * @param start offset of first character which will be copied
    * @param startLength the number of characters to extract
    * @param target the target buffer for extraction, can be NULL
    *               if targetLength is 0
    * @param targetLength the length of the target buffer
    * @param inv Signature-distinguishing paramater, use US_INV.
    * @return the output string length, not including the terminating NUL
    * @draft ICU 3.2
    */
   int32_t extract(int32_t start,
            int32_t length,
            char *target,
            int32_t targetCapacity,
            enum EInvariant inv) const;

   /**
    * Constructs a Unicode string from an invariant-character char *
string.
    * About invariant characters see utypes.h.
    * This constructor has no runtime dependency on conversion code and is
    * therefore recommended over ones taking a charset name string
    * (where the empty string "" indicates invariant-character conversion).
    *
    * Use the macro US_INV as the third, signature-distinguishing
parameter.
    *
    * For example:
    * \code
    * void fn(const char *s) {
    *   UnicodeString ustr(s, -1, US_INV);
    *   // use ustr ...
    * }
    * \endcode
    *
    * @param src String using only invariant characters.
    * @param length Length of src, or -1 if NUL-terminated.
    * @param inv Signature-distinguishing paramater, use US_INV.
    *
    * @see US_INV
    * @draft ICU 3.2
    */
   UnicodeString(const char *src, int32_t length, enum EInvariant inv);

/**
  * \def UCONFIG_NO_CONVERSION
  * This switch turns off all converters.
  *
  * @draft ICU 3.2
  */
#ifndef UCONFIG_NO_CONVERSION
#   define UCONFIG_NO_CONVERSION 0
#endif

#if UCONFIG_NO_CONVERSION
#   define UCONFIG_NO_LEGACY_CONVERSION 1
#endif