/* ====================================================================
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 2002-2003 The Apache Software Foundation.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution, if
 *    any, must include the following acknowledgement:
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgement may appear in the software itself,
 *    if and wherever such third-party acknowledgements normally appear.
 *
 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
 *    Foundation" must not be used to endorse or promote products derived
 *    from this software without prior written permission. For written
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 */
package org.apache.commons.lang;

import java.io.Serializable;

/**
 * <p>隣接する文字の範囲(オプションとして範囲の除外)を表します。
 * {@primary A contiguous range of characters, optionally negated.}</p>
 * 
 * <p>このクラスのインスタンスは不変(immutable)です。
 * {@primary Instances are immutable.}</p>
 *
 * @author Henri Yandell
 * @author Stephen Colebourne
 * @author Chris Feldhacker
 * @author Gary Gregory
 * @translator 日置 聡
 * @status firstdraft
 * @update 2003/09/04
 * @since 1.0
 * @version $Id: CharRange.java,v 1.1.1.1 2004/02/13 10:02:05 hioki Exp $
 */
public final class CharRange implements Serializable {

    /** Serialization lock, Lang version 2.0. */
    private static final long serialVersionUID = 8270183163158333422L;
    
    /** The first character, inclusive, in the range. */
    private final char start;
    /** The last character, inclusive, in the range. */
    private final char end;
    /** True if the range is everything except the characters specified. */
    private final boolean negated;
    
    /** Cached toString. */
    private transient String iToString;

    //-----------------------------------------------------------------------
    /**
     * <p>単一の文字を意味する <code>CharRange</code> を生成します。
     * {@primary Constructs a <code>CharRange</code> over a single character.}</p>
     *
     * @param ch  この文字範囲の示す唯一の文字
     *{@primary only character in this range}
     */
    public CharRange(char ch) {
        this(ch, ch, false);
    }

    /**
     * <p>単一の文字(または単一文字の除外)を意味する CharRange を生成します。
     * {@primary Constructs a <code>CharRange</code> over a single character,
     * optionally negating the range.}</p>
     *
     * <p>除外が指定された文字範囲は指定された文字以外の全ての文字を表します。
     * {@primary A negated range includes everything except the specified char.}</p>
     *
     * @param ch  この文字範囲の示す唯一の文字
     * {@primary only character in this range}
     * @param negated  true の場合指定された文字以外の全てを表す
     * {@primary true to express everything except the range}
     */
    public CharRange(char ch, boolean negated) {
        this(ch, ch, negated);
    }

    /**
     * <p>文字のセットを意味する CharRange を生成します。
     * {@primary Constructs a <code>CharRange</code> over a set of characters.}</p>
     *
     * @param start   この文字範囲の最初の文字(この文字も含む)
     * {@primary first character, inclusive, in this range}
     * @param end  この文字範囲の最後の文字(この文字も含む)
     * {@primary last character, inclusive, in this range}
     */
    public CharRange(char start, char end) {
        this(start, end, false);
    }

    /**
     * <p>文字のセット(または文字のセットの除外)を意味する CharRange を生成します。
     * {@primary Constructs a <code>CharRange</code> over a set of characters,
     * optionally negating the range.}</p>
     *
     * <p>除外が指定された文字範囲は開始と終了の文字で定義された文字の範囲以外の全ての文字を表します。
     * {@primary A negated range includes everything except that defined by the
     * start and end characters.}</p>
     * 
     * <p>開始と終了の文字の順番が正しくない場合、逆に置き換えられます。
     * 従って <code>a-e</code> の指定は <code>e-a</code> と等しくなります。
     * {@primary If start and end are in the wrong order, they are reversed.
     * Thus <code>a-e</code> is the same as <code>e-a</code>.}</p>
     *
     * @param start   この文字範囲の最初の文字(この文字も含む)
     * {@primary first character, inclusive, in this range}
     * @param end  この文字範囲の最後の文字(この文字も含む)
     * {@primary last character, inclusive, in this range}
     * @param negated  true の場合指定された文字以外の全てを表す
     * {@primary true to express everything except the range}
     */
    public CharRange(char start, char end, boolean negated) {
        super();
        if (start > end) {
            char temp = start;
            start = end;
            end = temp;
        }
        
        this.start = start;
        this.end = end;
        this.negated = negated;
    }

    // Accessors
    //-----------------------------------------------------------------------
    /**
     * <p>文字範囲の開始文字を返します。
     * {@primary Gets the start character for this character range.}</p>
     * 
     * @return 開始文字(この文字も含む)
     * {@primary the start char (inclusive)}
     */
    public char getStart() {
        return this.start;
    }

    /**
     * <p>文字範囲の終了文字を返します。
     * {@primary Gets the end character for this character range.}</p>
     * 
     * @return 終了文字(この文字も含む)
     * {@primary the end char (inclusive)}
     */
    public char getEnd() {
        return this.end;
    }

    /**
     * <p>この <code>CharRange</code> が除外条件かどうかを返します。
     * {@primary Is this <code>CharRange</code> negated.}</p>
     * 
     * <p>除外が指定された文字範囲は開始と終了の文字で定義された文字の範囲以外の全ての文字を表します。
     * {@primary A negated range includes everything except that defined by the
     * start and end characters.}</p>
     *
     * @return <code>true</code> の場合、除外条件
     * {@primary <code>true</code> is negated}
     */
    public boolean isNegated() {
        return negated;
    }

    // Contains
    //-----------------------------------------------------------------------
    /**
     * <p>指定された文字がこの文字範囲に含まれるかどうかを返します。
     * {@primary Is the character specified contained in this range.}</p>
     *
     * @param ch  チェック対象となる文字
     * {@primary the character to check}
     * @return 指定された文字が文字範囲内の場合、<code>true</code>
     * {@primary <code>true</code> if this range contains the input character}
     */
    public boolean contains(char ch) {
        return ((ch >= start && ch <= end) != negated);
    }

    /**
     * <p>指定された文字範囲が、全てこの文字範囲に含まれるかどうかを評価します。
     * {@primary Are all the characters of the passed in range contained in
     * this range.}</p>
     *
     * @param range  チェック対象となる文字範囲
     * {@primary the range to check against}
     * @return 指定された文字範囲が全て文字範囲内におさまる場合、<code>true</code>
     * {@primary <code>true</code> if this range entirely contains the input range}
     * @throws IllegalArgumentException <code>null</code> が入力された場合
     * {@primary if <code>null</code> input}
     */
    public boolean contains(CharRange range) {
        if (range == null) {
            throw new IllegalArgumentException("The Range must not be null");
        }
        if (negated) {
            if (range.negated) {
                return (start >= range.start && end <= range.end);
            } else {
                return (range.end < start || range.start > end);
            }
        } else {
            if (range.negated) {
                return (start == 0 && end == Character.MAX_VALUE);
            } else {
                return (start <= range.start && end >= range.end);
            }
        }
    }

    // Basics
    //-----------------------------------------------------------------------
    /**
     * <p>2つの CharRange オブジェクトを比較し、同じ方法で同じ文字範囲を示している場合に
     * true を返します。
     * {@primary Compares two CharRange objects, returning true if they represent
     * exactly the same range of characters defined in the same way.}</p>
     * 
     * @param obj  比較対照となるオブジェクト
     * {@primary the object to compare to}
     * @return true 等しい場合、true
     * {@primary true if equal}
     */
    public boolean equals(Object obj) {
        if (obj == this) {
            return true;
        }
        if (obj instanceof CharRange == false) {
            return false;
        }
        CharRange other = (CharRange) obj;
        return (start == other.start && end == other.end && negated == other.negated);
    }

    /**
     * <p>equals メソッドと互換性のあるハッシュコードを取得します。
     * {@primary Gets a hashCode compatable with the equals method.}</p>
     * 
     * @return 適切なハッシュコード
     * {@primary a suitable hashCode}
     */
    public int hashCode() {
        return 83 + start + 7 * end + (negated ? 1 : 0);
    }
    
    /**
     * <p>この文字範囲の文字列表現を返します。
     * {@primary Gets a string representation of the character range.}</p>
     * 
     * @return この文字範囲の文字列表現
     * {@primary string representation of this range}
     */
    public String toString() {
        if (iToString == null) {
            StringBuffer buf = new StringBuffer(4);
            if (isNegated()) {
                buf.append('^');
            }
            buf.append(start);
            if (start != end) {
                buf.append('-');
                buf.append(end);
            }
            iToString = buf.toString();
        }
        return iToString;
    }
    
}