+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
/*
**********************************************************************
-* Copyright (C) 1999-2004, International Business Machines
+* Copyright (C) 1999-2014, 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"
#include "unicode/utrans.h" // UTransPosition, UTransDirection
#include "unicode/strenum.h"
+#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
class UnicodeFilter;
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.
* <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
void* pointer;
};
+#ifndef U_HIDE_INTERNAL_API
/**
* Return a token containing an integer.
* @return a token containing an integer.
* @internal
*/
inline static Token pointerToken(void*);
+#endif /* U_HIDE_INTERNAL_API */
/**
* A function that creates and returns a Transliterator. When
friend class TransliteratorParser; // for parseID()
friend class TransliteratorIDParser; // for createBasicInstance()
+ friend class TransliteratorAlias; // for setID()
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.
* 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>.
* for details.
* @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. See {@link #transliterate(Replaceable&, UTransPosition&, const UnicodeString*, UErrorCode&) const }.
* @param status Output param to filled in with a success or an error.
* @see #transliterate(Replaceable, int[], String)
* @stable ICU 2.0
* [<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
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
UTransPosition& index,
UBool incremental) const;
- friend class CompoundTransliterator; // for filteredTransliterate()
- friend class AnyTransliterator; // for filteredTransliterate()
-
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
* @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;
* 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;
/**
* Registers a factory function that creates transliterators of
* a given ID.
+ *
+ * Because ICU may choose to cache Transliterators internally, this must
+ * be called at application startup, prior to any calls to
+ * Transliterator::createXXX to avoid undefined behavior.
+ *
* @param id the ID being registered
* @param factory a function pointer that will be copied and
* called later when the given ID is passed to createInstance()
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
* After this call the Transliterator class owns the adoptedObj
* and will delete it.
*
+ * Because ICU may choose to cache Transliterators internally, this must
+ * be called at application startup, prior to any calls to
+ * Transliterator::createXXX to avoid undefined behavior.
+ *
* @param adoptedObj an instance of subclass of
* <code>Transliterator</code> that defines <tt>clone()</tt>
* @see #createInstance
*/
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
* @param factory a function pointer that will be copied and
* called later when the given ID is passed to createInstance()
* @param context a context pointer that will be stored and
* later passed to the factory function when an ID matching
* the registration ID is being instantiated with this factory.
+ * @internal
*/
static void _registerFactory(const UnicodeString& id,
Factory factory,
*/
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
static void _registerSpecialInverse(const UnicodeString& target,
const UnicodeString& inverseTarget,
UBool bidirectional);
+#endif /* U_HIDE_INTERNAL_API */
public:
* Any attempt to construct an unregistered transliterator based
* on its ID will fail.
*
+ * Because ICU may choose to cache Transliterators internally, this should
+ * be called during application shutdown, after all calls to
+ * Transliterator::createXXX to avoid undefined behavior.
+ *
* @param ID the ID of the transliterator or class
* @return the <code>Object</code> that was registered with
* <code>ID</code>, or <code>null</code> if none was
* @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);
protected:
+#ifndef U_HIDE_INTERNAL_API
/**
* Non-mutexed internal method
* @internal
const UnicodeString& source,
const UnicodeString& target,
UnicodeString& result);
+#endif /* U_HIDE_INTERNAL_API */
protected:
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
* 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 {
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((char16_t)0);
+ ID.truncate(ID.length()-1);
}
+#ifndef U_HIDE_INTERNAL_API
inline Transliterator::Token Transliterator::integerToken(int32_t i) {
Token t;
t.integer = i;
t.pointer = p;
return t;
}
+#endif /* U_HIDE_INTERNAL_API */
U_NAMESPACE_END
+#endif // U_SHOW_CPLUSPLUS_API
#endif /* #if !UCONFIG_NO_TRANSLITERATION */
projects / apple / icu.git / blobdiff