ICU-491.11.1.tar.gz
[apple/icu.git] / icuSources / i18n / unicode / translit.h
index 415c0885b740e308b62d7ebec8ad94885dccde18..f2a1d1bc7e6083c51035df881211bbec4f0d0490 100644 (file)
@@ -1,6 +1,6 @@
 /*
 **********************************************************************
-* Copyright (C) 1999-2004, International Business Machines
+* Copyright (C) 1999-2011, International Business Machines
 * Corporation and others. All Rights Reserved.
 **********************************************************************
 *   Date        Name        Description
 
 #include "unicode/utypes.h"
 
+/**
+ * \file 
+ * \brief C++ API: Tranforms text from one format to another.
+ */
 #if !UCONFIG_NO_TRANSLITERATION
 
 #include "unicode/uobject.h"
@@ -30,6 +35,7 @@ class NormalizationTransliterator;
 class TransliteratorIDParser;
 
 /**
+ *
  * <code>Transliterator</code> is an abstract class that
  * transliterates text from one format to another.  The most common
  * kind of transliterator is a script, or alphabet, transliterator.
@@ -53,7 +59,7 @@ class TransliteratorIDParser;
  * <code>transliterate()</code>.  (However, this does <em>not</em>
  * mean that threads may share transliterators without synchronizing
  * them.  Transliterators are not immutable, so they must be
- * synchronized when shared between threads.)  This1 might seem to
+ * synchronized when shared between threads.)  This might seem to
  * limit the complexity of the transliteration operation.  In
  * practice, subclasses perform complex transliterations by delaying
  * the replacement of text until it is known that no other
@@ -271,6 +277,7 @@ private:
         void*   pointer;
     };
 
+#ifndef U_HIDE_INTERNAL_API
     /**
      * Return a token containing an integer.
      * @return a token containing an integer.
@@ -284,6 +291,7 @@ private:
      * @internal
      */
     inline static Token pointerToken(void*);
+#endif  /* U_HIDE_INTERNAL_API */
 
     /**
      * A function that creates and returns a Transliterator.  When
@@ -343,6 +351,7 @@ protected:
 
     friend class TransliteratorParser; // for parseID()
     friend class TransliteratorIDParser; // for createBasicInstance()
+    friend class TransliteratorAlias; // for setID()
 
 public:
 
@@ -366,7 +375,7 @@ public:
      * @see #registerInstance
      * @stable ICU 2.0
      */
-    virtual Transliterator* clone() const { return 0; }
+    virtual Transliterator* clone() const;
 
     /**
      * Transliterates a segment of a string, with optional filtering.
@@ -465,13 +474,10 @@ public:
      * Transliterates the portion of the text buffer that can be
      * transliterated unambiguosly after a new character has been
      * inserted, typically as a result of a keyboard event.  This is a
-     * convenience method; see {@link
-     * #transliterate(Replaceable&, UTransPosition&, const UnicodeString&, UErrorCode&) const}
-     * for details.
+     * convenience method.
      * @param text the buffer holding transliterated and
      * untransliterated text
-     * @param index an array of three integers.  See {@link
-     * #transliterate(Replaceable&, UTransPosition&, const UnicodeString&, UErrorCode&) const }.
+     * @param index an array of three integers.
      * @param insertion text to be inserted and possibly
      * transliterated into the translation buffer at
      * <code>index.limit</code>.
@@ -599,8 +605,8 @@ protected:
      * [<code>pos.start</code>, <code>pos.limit</code>) without
      * applying the filter. End user code should call <code>
      * transliterate()</code> instead of this method. Subclass code
-     * should call <code>filteredTransliterate()</code> instead of
-     * this method.<p>
+     * and wrapping transliterators should call
+     * <code>filteredTransliterate()</code> instead of this method.<p>
      *
      * @param text the buffer holding transliterated and
      * untransliterated text
@@ -621,6 +627,7 @@ protected:
                                      UTransPosition& pos,
                                      UBool incremental) const = 0;
 
+public:
     /**
      * Transliterate a substring of text, as specified by index, taking filters
      * into account.  This method is for subclasses that need to delegate to
@@ -636,9 +643,6 @@ protected:
                                        UTransPosition& index,
                                        UBool incremental) const;
 
-    friend class CompoundTransliterator; // for filteredTransliterate()
-    friend class AnyTransliterator; // for filteredTransliterate()
-
 private:
 
     /**
@@ -650,7 +654,7 @@ private:
      *
      * <p>If this transliterator has a filter, break up the input text into runs
      * of unfiltered characters.  Pass each run to
-     * <subclass>.handleTransliterate().
+     * subclass.handleTransliterate().
      *
      * <p>In incremental mode, if rollback is TRUE, perform a special
      * incremental procedure in which several passes are made over the input
@@ -884,7 +888,7 @@ public:
      * @return the number of transliterators that compose this
      * transliterator, or 1 if this transliterator is not composed of
      * multiple transliterators
-     * @draft ICU 3.0
+     * @stable ICU 3.0
      */
     int32_t countElements() const;
 
@@ -905,7 +909,7 @@ public:
      * transliterator, if this transliterator is made up of multiple
      * transliterators, otherwise a reference to this object if given
      * an index of 0
-     * @draft ICU 3.0
+     * @stable ICU 3.0
      */
     const Transliterator& getElement(int32_t index, UErrorCode& ec) const;
 
@@ -975,7 +979,7 @@ public:
                                 Token context);
 
     /**
-     * Registers a instance <tt>obj</tt> of a subclass of
+     * Registers an instance <tt>obj</tt> of a subclass of
      * <code>Transliterator</code> with the system.  When
      * <tt>createInstance()</tt> is called with an ID string that is
      * equal to <tt>obj->getID()</tt>, then <tt>obj->clone()</tt> is
@@ -993,8 +997,26 @@ public:
      */
     static void U_EXPORT2 registerInstance(Transliterator* adoptedObj);
 
+    /**
+     * Registers an ID string as an alias of another ID string.
+     * That is, after calling this function, <tt>createInstance(aliasID)</tt>
+     * will return the same thing as <tt>createInstance(realID)</tt>.
+     * This is generally used to create shorter, more mnemonic aliases
+     * for long compound IDs.
+     *
+     * @param aliasID The new ID being registered.
+     * @param realID The ID that the new ID is to be an alias for.
+     * This can be a compound ID and can include filters and should
+     * refer to transliterators that have already been registered with
+     * the framework, although this isn't checked.
+     * @stable ICU 3.6
+     */
+     static void U_EXPORT2 registerAlias(const UnicodeString& aliasID,
+                                         const UnicodeString& realID);
+
 protected:
 
+#ifndef U_HIDE_INTERNAL_API
     /**
      * @internal
      * @param id the ID being registered
@@ -1013,6 +1035,11 @@ protected:
      */
     static void _registerInstance(Transliterator* adoptedObj);
 
+    /**
+     * @internal
+     */
+    static void _registerAlias(const UnicodeString& aliasID, const UnicodeString& realID);
+
     /**
      * Register two targets as being inverses of one another.  For
      * example, calling registerSpecialInverse("NFC", "NFD", true) causes
@@ -1049,6 +1076,7 @@ protected:
     static void _registerSpecialInverse(const UnicodeString& target,
                                         const UnicodeString& inverseTarget,
                                         UBool bidirectional);
+#endif  /* U_HIDE_INTERNAL_API */
 
 public:
 
@@ -1076,7 +1104,7 @@ public:
      * @return a newly-created StringEnumeration over the transliterators
      * available at the time of the call. The caller should delete this object
      * when done using it.
-     * @draft ICU 3.0
+     * @stable ICU 3.0
      */
     static StringEnumeration* U_EXPORT2 getAvailableIDs(UErrorCode& ec);
 
@@ -1154,6 +1182,7 @@ public:
 
 protected:
 
+#ifndef U_HIDE_INTERNAL_API
     /**
      * Non-mutexed internal method
      * @internal
@@ -1196,6 +1225,7 @@ protected:
                                                const UnicodeString& source,
                                                const UnicodeString& target,
                                                UnicodeString& result);
+#endif  /* U_HIDE_INTERNAL_API */
 
 protected:
 
@@ -1239,9 +1269,10 @@ public:
     virtual UClassID getDynamicClassID(void) const = 0;
 
 private:
-    static UBool initializeRegistry(void);
+    static UBool initializeRegistry(UErrorCode &status);
 
 public:
+#ifndef U_HIDE_OBSOLETE_API
     /**
      * Return the number of IDs currently registered with the system.
      * To retrieve the actual IDs, call getAvailableID(i) with
@@ -1264,6 +1295,7 @@ public:
      * may become invalid if another thread calls unregister
      */
     static const UnicodeString& U_EXPORT2 getAvailableID(int32_t index);
+#endif  /* U_HIDE_OBSOLETE_API */
 };
 
 inline int32_t Transliterator::getMaximumContextLength(void) const {
@@ -1272,10 +1304,12 @@ inline int32_t Transliterator::getMaximumContextLength(void) const {
 
 inline void Transliterator::setID(const UnicodeString& id) {
     ID = id;
-    // NUL-terminate the ID string
-    ID.getTerminatedBuffer();
+    // NUL-terminate the ID string, which is a non-aliased copy.
+    ID.append((UChar)0);
+    ID.truncate(ID.length()-1);
 }
 
+#ifndef U_HIDE_INTERNAL_API
 inline Transliterator::Token Transliterator::integerToken(int32_t i) {
     Token t;
     t.integer = i;
@@ -1287,6 +1321,7 @@ inline Transliterator::Token Transliterator::pointerToken(void* p) {
     t.pointer = p;
     return t;
 }
+#endif
 
 U_NAMESPACE_END