/**
*******************************************************************************
* Copyright (C) 1996-2005, International Business Machines Corporation and    *
* others. All Rights Reserved.                                                *
*******************************************************************************
*
*
*******************************************************************************
*/

package com.ibm.icu4jni.text;

import java.text.CharacterIterator;
import java.text.ParseException;
import java.util.Locale;

/**
* Concrete implementation class for Collation.
* <p>
* The collation table is composed of a list of collation rules, where each
* rule is of three forms:
* <pre>
*    < modifier >
*    < relation > < text-argument >
*    < reset > < text-argument >
* </pre>
* <p>
* <code>RuleBasedCollator</code> has the following restrictions for efficiency
* (other subclasses may be used for more complex languages) :
* <ol>
* <li> If a French secondary ordering is specified it applies to the whole
*      collator object.
* <li> All non-mentioned Unicode characters are at the end of the collation
*      order.
* <li> If a character is not located in the RuleBasedCollator, the default
*      Unicode Collation Algorithm (UCA) rule-based table is automatically
*      searched as a backup.
* </ol>
*
* The following demonstrates how to create your own collation rules:
* <UL Type=disc>
*    <LI><strong>Text-Argument</strong>: A text-argument is any sequence of
*        characters, excluding special characters (that is, common whitespace
*        characters [0009-000D, 0020] and rule syntax characters [0021-002F,
*        003A-0040, 005B-0060, 007B-007E]). If those characters are desired,
*        you can put them in single quotes (e.g. ampersand => '&'). Note that
*        unquoted white space characters are ignored; e.g. <code>b c</code> is
*        treated as <code>bc</code>.
*    <LI><strong>Modifier</strong>: There is a single modifier which is used
*        to specify that all accents (secondary differences) are backwards.
*        <p>'@' : Indicates that accents are sorted backwards, as in French.
*    <LI><strong>Relation</strong>: The relations are the following:
*        <UL Type=square>
*            <LI>'<' : Greater, as a letter difference (primary)
*            <LI>';' : Greater, as an accent difference (secondary)
*            <LI>',' : Greater, as a case difference (tertiary)
*            <LI>'=' : Equal
*        </UL>
*    <LI><strong>Reset</strong>: There is a single reset which is used
*        primarily for contractions and expansions, but which can also be used
*        to add a modification at the end of a set of rules.
*        <p>'&' : Indicates that the next rule follows the position to where
*            the reset text-argument would be sorted.
* </UL>
*
* <p>
* This sounds more complicated than it is in practice. For example, the
* following are equivalent ways of expressing the same thing:
* <blockquote>
* <pre>
* a < b < c
* a < b & b < c
* a < c & a < b
* </pre>
* </blockquote>
* Notice that the order is important, as the subsequent item goes immediately
* after the text-argument. The following are not equivalent:
* <blockquote>
* <pre>
* a < b & a < c
* a < c & a < b
* </pre>
* </blockquote>
* Either the text-argument must already be present in the sequence, or some
* initial substring of the text-argument must be present. (e.g. "a < b & ae <
* e" is valid since "a" is present in the sequence before "ae" is reset). In
* this latter case, "ae" is not entered and treated as a single character;
* instead, "e" is sorted as if it were expanded to two characters: "a"
* followed by an "e". This difference appears in natural languages: in
* traditional Spanish "ch" is treated as though it contracts to a single
* character (expressed as "c < ch < d"), while in traditional German a-umlaut
* is treated as though it expanded to two characters (expressed as "a,A < b,B
* ... & ae;? & AE;?"). [? and ? are, of course, the escape sequences for
* a-umlaut.]
* <p>
* <strong>Ignorable Characters</strong>
* <p>
* For ignorable characters, the first rule must start with a relation (the
* examples we have used above are really fragments; "a < b" really should be
* "< a < b"). If, however, the first relation is not "<", then all the all
* text-arguments up to the first "<" are ignorable. For example, ", - < a < b"
* makes "-" an ignorable character, as we saw earlier in the word
* "black-birds". In the samples for different languages, you see that most
* accents are ignorable.
*
* <p><strong>Normalization and Accents</strong>
* <p>
* <code>RuleBasedCollator</code> automatically processes its rule table to
* include both pre-composed and combining-character versions of accented
* characters. Even if the provided rule string contains only base characters
* and separate combining accent characters, the pre-composed accented
* characters matching all canonical combinations of characters from the rule
* string will be entered in the table.
* <p>
* This allows you to use a RuleBasedCollator to compare accented strings even
* when the collator is set to NO_DECOMPOSITION. However, if the strings to be
* collated contain combining sequences that may not be in canonical order, you
* should set the collator to CANONICAL_DECOMPOSITION to enable sorting of
* combining sequences.
* For more information, see
* <A HREF="http://www.aw.com/devpress">The Unicode Standard, Version 3.0</A>.)
*
* <p><strong>Errors</strong>
* <p>
* The following are errors:
* <UL Type=disc>
*     <LI>A text-argument contains unquoted punctuation symbols
*        (e.g. "a < b-c < d").
*     <LI>A relation or reset character not followed by a text-argument
*        (e.g. "a < , b").
*     <LI>A reset where the text-argument (or an initial substring of the
*         text-argument) is not already in the sequence or allocated in the
*         default UCA table.
*         (e.g. "a < b & e < f")
* </UL>
* If you produce one of these errors, a <code>RuleBasedCollator</code> throws
* a <code>ParseException</code>.
*
* <p><strong>Examples</strong>
* <p>Simple:     "< a < b < c < d"
* <p>Norwegian:  "< a,A< b,B< c,C< d,D< e,E< f,F< g,G< h,H< i,I< j,J
*                 < k,K< l,L< m,M< n,N< o,O< p,P< q,Q< r,R< s,S< t,T
*                < u,U< v,V< w,W< x,X< y,Y< z,Z
*                 < ?=a?,?=A?
*                 ;aa,AA< ?,?< ?,?"
*
* <p>
* Normally, to create a rule-based Collator object, you will use
* <code>Collator</code>'s factory method <code>getInstance</code>.
* However, to create a rule-based Collator object with specialized rules
* tailored to your needs, you construct the <code>RuleBasedCollator</code>
* with the rules contained in a <code>String</code> object. For example:
* <blockquote>
* <pre>
* String Simple = "< a < b < c < d";
* RuleBasedCollator mySimple = new RuleBasedCollator(Simple);
* </pre>
* </blockquote>
* Or:
* <blockquote>
* <pre>
* String Norwegian = "< a,A< b,B< c,C< d,D< e,E< f,F< g,G< h,H< i,I< j,J" +
*                 "< k,K< l,L< m,M< n,N< o,O< p,P< q,Q< r,R< s,S< t,T" +
*                 "< u,U< v,V< w,W< x,X< y,Y< z,Z" +
*                 "< ?=a?,?=A?" +
*                 ";aa,AA< ?,?< ?,?";
* RuleBasedCollator myNorwegian = new RuleBasedCollator(Norwegian);
* </pre>
* </blockquote>
*
* <p>
* Combining <code>Collator</code>s is as simple as concatenating strings.
* Here's an example that combines two <code>Collator</code>s from two
* different locales:
* <blockquote>
* <pre>
* // Create an en_US Collator object
* RuleBasedCollator en_USCollator = (RuleBasedCollator)
*     Collator.getInstance(new Locale("en", "US", ""));
* // Create a da_DK Collator object
* RuleBasedCollator da_DKCollator = (RuleBasedCollator)
*     Collator.getInstance(new Locale("da", "DK", ""));
* // Combine the two
* // First, get the collation rules from en_USCollator
* String en_USRules = en_USCollator.getRules();
* // Second, get the collation rules from da_DKCollator
* String da_DKRules = da_DKCollator.getRules();
* RuleBasedCollator newCollator =
*     new RuleBasedCollator(en_USRules + da_DKRules);
* // newCollator has the combined rules
* </pre>
* </blockquote>
*
* <p>
* Another more interesting example would be to make changes on an existing
* table to create a new <code>Collator</code> object.  For example, add
* "& C < ch, cH, Ch, CH" to the <code>en_USCollator</code> object to create
* your own:
* <blockquote>
* <pre>
* // Create a new Collator object with additional rules
* String addRules = "& C < ch, cH, Ch, CH";
* RuleBasedCollator myCollator =
*     new RuleBasedCollator(en_USCollator + addRules);
* // myCollator contains the new rules
* </pre>
* </blockquote>
*
* <p>
* The following example demonstrates how to change the order of
* non-spacing accents,
* <blockquote>
* <pre>
* // old rule
* String oldRules = "=?;?;?"    // main accents Diaeresis 00A8, Macron 00AF
*                               // Acute 00BF
*                 + "< a , A ; ae, AE ; ? , ?"
*                 + "< b , B < c, C < e, E & C < d, D";
* // change the order of accent characters
* String addOn = "& ?;?;?;"; // Acute 00BF, Macron 00AF, Diaeresis 00A8
* RuleBasedCollator myCollator = new RuleBasedCollator(oldRules + addOn);
* </pre>
* </blockquote>
*
* <p>
* The last example shows how to put new primary ordering in before the
* default setting. For example, in Japanese <code>Collator</code>, you
* can either sort English characters before or after Japanese characters,
* <blockquote>
* <pre>
* // get en_US Collator rules
* RuleBasedCollator en_USCollator =
*                      (RuleBasedCollator)Collator.getInstance(Locale.US);
* // add a few Japanese character to sort before English characters
* // suppose the last character before the first base letter 'a' in
* // the English collation rule is ?
* String jaString = "& \\u30A2 , \\u30FC < \\u30C8";
* RuleBasedCollator myJapaneseCollator = new
*     RuleBasedCollator(en_USCollator.getRules() + jaString);
* </pre>
* </blockquote>
* <P>
* @author syn wee quek
* @stable ICU 2.4
*/
public final class RuleBasedCollator extends Collator {
    private int m_collator_;
    private int m_hashcode_ = 0;

    /**
     * RuleBasedCollator constructor. This takes the table rules and builds a
     * collation table out of them. Please see RuleBasedCollator class
     * description for more details on the collation rule syntax.
     * @param rules the collation rules to build the collation table from.
     * @exception ParseException thrown if rules are empty or a Runtime error
     *            if collator can not be created.
     * @stable ICU 2.4
     */
    public RuleBasedCollator(String rules) throws ParseException {
        if (rules == null) {
            throw new NullPointerException();
        }
        m_collator_ = NativeCollation.openCollatorFromRules(rules,
                CollationAttribute.VALUE_OFF, CollationAttribute.VALUE_DEFAULT_STRENGTH);
    }

    /**
     * RuleBasedCollator constructor. This takes the table rules and builds a
     * collation table out of them. Please see RuleBasedCollator class
     * description for more details on the collation rule syntax.
     * @param rules the collation rules to build the collation table from.
     * @param strength collation strength
     * @exception ParseException thrown if rules are empty or a Runtime error
     *            if collator can not be created.
     * @see #PRIMARY
     * @see #SECONDARY
     * @see #TERTIARY
     * @see #QUATERNARY
     * @see #IDENTICAL
     * @stable ICU 2.4
     */
    public RuleBasedCollator(String rules, int strength) throws ParseException {
        if (rules == null) {
            throw new NullPointerException();
        }
        m_collator_ = NativeCollation.openCollatorFromRules(rules, CollationAttribute.VALUE_OFF, strength);
    }

    /**
     * RuleBasedCollator constructor. This takes the table rules and builds a
     * collation table out of them. Please see RuleBasedCollator class
     * description for more details on the collation rule syntax.
     * <p>Note API change starting from release 2.4. Prior to release 2.4, the
     * normalizationMode argument values are from the class
     * com.ibm.icu4jni.text.Normalization. In 2.4,
     * the valid normalizationMode arguments for this API are
     * CollationAttribute.VALUE_ON and CollationAttribute.VALUE_OFF.
     * </p>
     * @param rules the collation rules to build the collation table from.
     * @param strength collation strength
     * @param normalizationMode normalization mode
     * @exception IllegalArgumentException thrown when constructor error occurs
     * @see #PRIMARY
     * @see #SECONDARY
     * @see #TERTIARY
     * @see #QUATERNARY
     * @see #IDENTICAL
     * @see #CANONICAL_DECOMPOSITION
     * @see #NO_DECOMPOSITION
     * @stable ICU 2.4
     */
    public RuleBasedCollator(String rules, int normalizationMode, int strength) {
        if (rules == null) {
            throw new NullPointerException();
        }
        m_collator_ = NativeCollation.openCollatorFromRules(rules, normalizationMode, strength);
    }

    /**
     * Makes a complete copy of the current object.
     * @return a copy of this object if data clone is a success, otherwise null
     * @stable ICU 2.4
     */
    public Object clone() {
        RuleBasedCollator result = null;
        int collatoraddress = NativeCollation.safeClone(m_collator_);
        result = new RuleBasedCollator(collatoraddress);
        return (Collator)result;
    }

    /**
     * The comparison function compares the character data stored in two
     * different strings. Returns information about whether a string is less
     * than, greater than or equal to another string.
     * <p>Example of use:
     * <br>
     * <code>
     *   Collator myCollation = Collator.createInstance(Locale::US);
     *   myCollation.setStrength(CollationAttribute.VALUE_PRIMARY);
     *   // result would be 0 ("abc" == "ABC")
     *   // (no primary difference between "abc" and "ABC")
     *   int result = myCollation.compare("abc", "ABC",3);
     *   myCollation.setStrength(CollationAttribute.VALUE_TERTIARY);
     *   // result would be -1 (abc" &lt;&lt;&lt; "ABC")
     *   // (with tertiary difference between "abc" and "ABC")
     *   int result = myCollation.compare("abc", "ABC",3);
     * </code>
     */
    public int compare(String source, String target) {
        return NativeCollation.compare(m_collator_, source, target);
    }

    /**
     * Get the normalization mode for this object.
     * The normalization mode influences how strings are compared.
     * @see #CANONICAL_DECOMPOSITION
     * @see #NO_DECOMPOSITION
     * @stable ICU 2.4
     */
    public int getDecomposition() {
        return NativeCollation.getNormalization(m_collator_);
    }

    /**
     * <p>Sets the decomposition mode of the Collator object on or off.
     * If the decomposition mode is set to on, string would be decomposed into
     * NFD format where necessary before sorting.</p>
     * </p>
     * @param decompositionmode the new decomposition mode
     * @see #CANONICAL_DECOMPOSITION
     * @see #NO_DECOMPOSITION
     * @stable ICU 2.4
     */
    public void setDecomposition(int decompositionmode) {
        NativeCollation.setAttribute(m_collator_,
                CollationAttribute.NORMALIZATION_MODE, decompositionmode);
    }

    /**
     * Determines the minimum strength that will be use in comparison or
     * transformation.
     * <p>
     * E.g. with strength == CollationAttribute.VALUE_SECONDARY, the tertiary difference
     * is ignored
     * </p>
     * <p>
     * E.g. with strength == PRIMARY, the secondary and tertiary difference are
     * ignored.
     * </p>
     * @return the current comparison level.
     * @see #PRIMARY
     * @see #SECONDARY
     * @see #TERTIARY
     * @see #QUATERNARY
     * @see #IDENTICAL
     * @stable ICU 2.4
     */
    public int getStrength() {
        return NativeCollation.getAttribute(m_collator_, CollationAttribute.STRENGTH);
    }

    /**
     * Sets the minimum strength to be used in comparison or transformation.
     * <p>Example of use:
     * <br>
     * <code>
     * Collator myCollation = Collator.createInstance(Locale::US);
     * myCollation.setStrength(PRIMARY);
     * // result will be "abc" == "ABC"
     * // tertiary differences will be ignored
     * int result = myCollation->compare("abc", "ABC");
     * </code>
     * @param strength the new comparison level.
     * @exception IllegalArgumentException when argument does not belong to any collation strength
     *            mode or error occurs while setting data.
     * @see #PRIMARY
     * @see #SECONDARY
     * @see #TERTIARY
     * @see #QUATERNARY
     * @see #IDENTICAL
     * @stable ICU 2.4
     */
    public void setStrength(int strength) {
        NativeCollation.setAttribute(m_collator_, CollationAttribute.STRENGTH, strength);
    }

    /**
     * Sets the attribute to be used in comparison or transformation.
     * <p>Example of use:
     * <br>
     * <code>
     *  Collator myCollation = Collator.createInstance(Locale::US);
     *  myCollation.setAttribute(CollationAttribute.CASE_LEVEL,
     *                           CollationAttribute.VALUE_ON);
     *  int result = myCollation->compare("\\u30C3\\u30CF",
     *                                    "\\u30C4\\u30CF");
     * // result will be -1
     * </code>
     * @param type the attribute to be set from CollationAttribute
     * @param value attribute value from CollationAttribute
     * @stable ICU 2.4
     */
    public void setAttribute(int type, int value) {
        NativeCollation.setAttribute(m_collator_, type, value);
    }

    /**
     * Gets the attribute to be used in comparison or transformation.
     * @param type the attribute to be set from CollationAttribute
     * @return value attribute value from CollationAttribute
     * @stable ICU 2.4
     */
    public int getAttribute(int type) {
        return NativeCollation.getAttribute(m_collator_, type);
    }

    public CollationKey getCollationKey(String source) {
        if (source == null) {
            return null;
        }
        byte[] key = NativeCollation.getSortKey(m_collator_, source);
        if (key == null) {
            return null;
        }
        return new CollationKey(source, key);
    }

    /**
     * Get the collation rules of this Collation object
     * The rules will follow the rule syntax.
     * @return collation rules.
     * @stable ICU 2.4
     */
    public String getRules() {
        return NativeCollation.getRules(m_collator_);
    }

    /**
     * Create a CollationElementIterator object that will iterator over the
     * elements in a string, using the collation rules defined in this
     * RuleBasedCollator
     * @param source string to iterate over
     * @return address of C collationelement
     * @exception IllegalArgumentException thrown when error occurs
     * @stable ICU 2.4
     */
    public CollationElementIterator getCollationElementIterator(String source) {
        CollationElementIterator result = new CollationElementIterator(
                NativeCollation.getCollationElementIterator(m_collator_, source));
        // result.setOwnCollationElementIterator(true);
        return result;
    }

    public CollationElementIterator getCollationElementIterator(CharacterIterator it) {
        // We only implement the String-based API, so build a string from the iterator.
        return getCollationElementIterator(characterIteratorToString(it));
    }

    private String characterIteratorToString(CharacterIterator it) {
        StringBuilder result = new StringBuilder();
        for (char ch = it.current(); ch != CharacterIterator.DONE; ch = it.next()) {
            result.append(ch);
        }
        return result.toString();
    }

    @Override
    public int hashCode() {
        return 42; // No-one uses RuleBasedCollator as a hash key.
    }

    /**
     * Checks if argument object is equals to this object.
     * @param target object
     * @return true if source is equivalent to target, false otherwise
     * @stable ICU 2.4
     */
    public boolean equals(Object object) {
        if (object ==  this) {
            return true;
        }
        if (!(object instanceof RuleBasedCollator)) {
            return false;
        }
        RuleBasedCollator rhs = (RuleBasedCollator) object;
        return getRules().equals(rhs.getRules()) &&
                getStrength() == rhs.getStrength() &&
                getDecomposition() == rhs.getDecomposition();
    }

    RuleBasedCollator(Locale locale) {
        m_collator_ = NativeCollation.openCollator(locale.toString());
    }

    @Override protected void finalize() throws Throwable {
        try {
            NativeCollation.closeCollator(m_collator_);
        } finally {
            super.finalize();
        }
    }

    private RuleBasedCollator(int addr) {
        m_collator_ = addr;
    }
}