1 /*

     2 **********************************************************************

     3 *   Copyright (c) 2000-2005, International Business Machines

     4 *   Corporation and others.  All Rights Reserved.

     5 **********************************************************************

     6 *   Date        Name        Description

     7 *   02/04/00    aliu        Creation.

     8 **********************************************************************

     9 */

    10 #ifndef SYMTABLE_H

    11 #define SYMTABLE_H

    12 

    13 #include "unicode/utypes.h"

    14 #include "unicode/uobject.h"

    15 

    16 /**

    17  * \file 

    18  * \brief C++ API: An interface that defines both lookup protocol and parsing of

    19  * symbolic names.

    20  */

    21  

    22 U_NAMESPACE_BEGIN

    23 

    24 class ParsePosition;

    25 class UnicodeFunctor;

    26 class UnicodeSet;

    27 class UnicodeString;

    28 

    29 /**

    30  * An interface that defines both lookup protocol and parsing of

    31  * symbolic names.

    32  *

    33  * <p>A symbol table maintains two kinds of mappings.  The first is

    34  * between symbolic names and their values.  For example, if the

    35  * variable with the name "start" is set to the value "alpha"

    36  * (perhaps, though not necessarily, through an expression such as

    37  * "$start=alpha"), then the call lookup("start") will return the

    38  * char[] array ['a', 'l', 'p', 'h', 'a'].

    39  *

    40  * <p>The second kind of mapping is between character values and

    41  * UnicodeMatcher objects.  This is used by RuleBasedTransliterator,

    42  * which uses characters in the private use area to represent objects

    43  * such as UnicodeSets.  If U+E015 is mapped to the UnicodeSet [a-z],

    44  * then lookupMatcher(0xE015) will return the UnicodeSet [a-z].

    45  *

    46  * <p>Finally, a symbol table defines parsing behavior for symbolic

    47  * names.  All symbolic names start with the SYMBOL_REF character.

    48  * When a parser encounters this character, it calls parseReference()

    49  * with the position immediately following the SYMBOL_REF.  The symbol

    50  * table parses the name, if there is one, and returns it.

    51  *

    52  * @stable ICU 2.8

    53  */

    54 class U_COMMON_API SymbolTable /* not : public UObject because this is an interface/mixin class */ {

    55 public:

    56 

    57     /**

    58      * The character preceding a symbol reference name.

    59      * @stable ICU 2.8

    60      */

    61     enum { SYMBOL_REF = 0x0024 /*$*/ };

    62 

    63     /**

    64      * Destructor.

    65      * @stable ICU 2.8

    66      */

    67     virtual ~SymbolTable();

    68 

    69     /**

    70      * Lookup the characters associated with this string and return it.

    71      * Return <tt>NULL</tt> if no such name exists.  The resultant

    72      * string may have length zero.

    73      * @param s the symbolic name to lookup

    74      * @return a string containing the name's value, or <tt>NULL</tt> if

    75      * there is no mapping for s.

    76      * @stable ICU 2.8

    77      */

    78     virtual const UnicodeString* lookup(const UnicodeString& s) const = 0;

    79 

    80     /**

    81      * Lookup the UnicodeMatcher associated with the given character, and

    82      * return it.  Return <tt>NULL</tt> if not found.

    83      * @param ch a 32-bit code point from 0 to 0x10FFFF inclusive.

    84      * @return the UnicodeMatcher object represented by the given

    85      * character, or NULL if there is no mapping for ch.

    86      * @stable ICU 2.8

    87      */

    88     virtual const UnicodeFunctor* lookupMatcher(UChar32 ch) const = 0;

    89 

    90     /**

    91      * Parse a symbol reference name from the given string, starting

    92      * at the given position.  If no valid symbol reference name is

    93      * found, return the empty string and leave pos unchanged.  That is, if the

    94      * character at pos cannot start a name, or if pos is at or after

    95      * text.length(), then return an empty string.  This indicates an

    96      * isolated SYMBOL_REF character.

    97      * @param text the text to parse for the name

    98      * @param pos on entry, the index of the first character to parse.

    99      * This is the character following the SYMBOL_REF character.  On

   100      * exit, the index after the last parsed character.  If the parse

   101      * failed, pos is unchanged on exit.

   102      * @param limit the index after the last character to be parsed.

   103      * @return the parsed name, or an empty string if there is no

   104      * valid symbolic name at the given position.

   105      * @stable ICU 2.8

   106      */

   107     virtual UnicodeString parseReference(const UnicodeString& text,

   108                                          ParsePosition& pos, int32_t limit) const = 0;

   109 };

   110 U_NAMESPACE_END

   111 

   112 #endif