jars/icu4j-4_4_2-src/main/classes/core/src/com/ibm/icu/text/SymbolTable.java

   1 /*\r
   2  *******************************************************************************\r
   3  * Copyright (C) 1996-2005, International Business Machines Corporation and    *\r
   4  * others. All Rights Reserved.                                                *\r
   5  *******************************************************************************\r
   6  */\r
   7 package com.ibm.icu.text;\r
   8 import java.text.ParsePosition;\r
   9 \r
  10 /**\r
  11  * An interface that defines both lookup protocol and parsing of\r
  12  * symbolic names.\r
  13  * \r
  14  * <p>This interface is used by UnicodeSet to resolve $Variable style\r
  15  * references that appear in set patterns.  RBBI and Transliteration\r
  16  * both independently implement this interface.\r
  17  *\r
  18  * <p>A symbol table maintains two kinds of mappings.  The first is\r
  19  * between symbolic names and their values.  For example, if the\r
  20  * variable with the name "start" is set to the value "alpha"\r
  21  * (perhaps, though not necessarily, through an expression such as\r
  22  * "$start=alpha"), then the call lookup("start") will return the\r
  23  * char[] array ['a', 'l', 'p', 'h', 'a'].\r
  24  *\r
  25  * <p>The second kind of mapping is between character values and\r
  26  * UnicodeMatcher objects.  This is used by RuleBasedTransliterator,\r
  27  * which uses characters in the private use area to represent objects\r
  28  * such as UnicodeSets.  If U+E015 is mapped to the UnicodeSet [a-z],\r
  29  * then lookupMatcher(0xE015) will return the UnicodeSet [a-z].\r
  30  *\r
  31  * <p>Finally, a symbol table defines parsing behavior for symbolic\r
  32  * names.  All symbolic names start with the SYMBOL_REF character.\r
  33  * When a parser encounters this character, it calls parseReference()\r
  34  * with the position immediately following the SYMBOL_REF.  The symbol\r
  35  * table parses the name, if there is one, and returns it.\r
  36  *\r
  37  * @stable ICU 2.8\r
  38  */\r
  39 public interface SymbolTable {\r
  40 \r
  41     /**\r
  42      * The character preceding a symbol reference name.\r
  43      * @stable ICU 2.8\r
  44      */\r
  45     static final char SYMBOL_REF = '$';\r
  46 \r
  47     /**\r
  48      * Lookup the characters associated with this string and return it.\r
  49      * Return <tt>null</tt> if no such name exists.  The resultant\r
  50      * array may have length zero.\r
  51      * @param s the symbolic name to lookup\r
  52      * @return a char array containing the name's value, or null if\r
  53      * there is no mapping for s.\r
  54      * @stable ICU 2.8\r
  55      */\r
  56     char[] lookup(String s);\r
  57 \r
  58     /**\r
  59      * Lookup the UnicodeMatcher associated with the given character, and\r
  60      * return it.  Return <tt>null</tt> if not found.\r
  61      * @param ch a 32-bit code point from 0 to 0x10FFFF inclusive.\r
  62      * @return the UnicodeMatcher object represented by the given\r
  63      * character, or null if there is no mapping for ch.\r
  64      * @stable ICU 2.8\r
  65      */\r
  66     UnicodeMatcher lookupMatcher(int ch);\r
  67 \r
  68     /**\r
  69      * Parse a symbol reference name from the given string, starting\r
  70      * at the given position.  If no valid symbol reference name is\r
  71      * found, return null and leave pos unchanged.  That is, if the\r
  72      * character at pos cannot start a name, or if pos is at or after\r
  73      * text.length(), then return null.  This indicates an isolated\r
  74      * SYMBOL_REF character.\r
  75      * @param text the text to parse for the name\r
  76      * @param pos on entry, the index of the first character to parse.\r
  77      * This is the character following the SYMBOL_REF character.  On\r
  78      * exit, the index after the last parsed character.  If the parse\r
  79      * failed, pos is unchanged on exit.\r
  80      * @param limit the index after the last character to be parsed.\r
  81      * @return the parsed name, or null if there is no valid symbolic\r
  82      * name at the given position.\r
  83      * @stable ICU 2.8\r
  84      */\r
  85     String parseReference(String text, ParsePosition pos, int limit);\r
  86 }\r