/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.lang3;

import java.io.Serializable;
import java.util.Iterator;
import java.util.NoSuchElementException;

A contiguous range of characters, optionally negated.
Instances are immutable.
#ThreadSafe#
Since:
1.0/**
 * <p>A contiguous range of characters, optionally negated.</p>
 *
 * <p>Instances are immutable.</p>
 *
 * <p>#ThreadSafe#</p>
 * @since 1.0
 */
// TODO: This is no longer public and will be removed later as CharSet is moved
// to depend on Range.
final class CharRange implements Iterable<Character>, Serializable {

    
Required for serialization support. Lang version 2.0.
See Also:
Serializable/**
     * Required for serialization support. Lang version 2.0.
     *
     * @see java.io.Serializable
     */
    private static final long serialVersionUID = 8270183163158333422L;

    
The first character, inclusive, in the range. /** The first character, inclusive, in the range. */
    private final char start;
    
The last character, inclusive, in the range. /** The last character, inclusive, in the range. */
    private final char end;
    
True if the range is everything except the characters specified. /** True if the range is everything except the characters specified. */
    private final boolean negated;

    
Cached toString. /** Cached toString. */
    private transient String iToString;

    
Constructs a CharRange over a set of characters, optionally negating the range.
A negated range includes everything except that defined by the
start and end characters.
If start and end are in the wrong order, they are reversed. Thus a-e is the same as e-a.
Params:
start –  first character, inclusive, in this range
end –  last character, inclusive, in this range
negated –  true to express everything except the range/**
     * <p>Constructs a {@code CharRange} over a set of characters,
     * optionally negating the range.</p>
     *
     * <p>A negated range includes everything except that defined by the
     * start and end characters.</p>
     *
     * <p>If start and end are in the wrong order, they are reversed.
     * Thus {@code a-e} is the same as {@code e-a}.</p>
     *
     * @param start  first character, inclusive, in this range
     * @param end  last character, inclusive, in this range
     * @param negated  true to express everything except the range
     */
    private CharRange(char start, char end, final boolean negated) {
        super();
        if (start > end) {
            final char temp = start;
            start = end;
            end = temp;
        }

        this.start = start;
        this.end = end;
        this.negated = negated;
    }

    
Constructs a CharRange over a single character.
Params:
ch –  only character in this range
See Also:
CharRange(char, char, boolean)
Returns:
the new CharRange object
Since:
2.5/**
     * <p>Constructs a {@code CharRange} over a single character.</p>
     *
     * @param ch  only character in this range
     * @return the new CharRange object
     * @see CharRange#CharRange(char, char, boolean)
     * @since 2.5
     */
    public static CharRange is(final char ch) {
        return new CharRange(ch, ch, false);
    }

    
Constructs a negated CharRange over a single character.
Params:
ch –  only character in this range
See Also:
CharRange(char, char, boolean)
Returns:
the new CharRange object
Since:
2.5/**
     * <p>Constructs a negated {@code CharRange} over a single character.</p>
     *
     * @param ch  only character in this range
     * @return the new CharRange object
     * @see CharRange#CharRange(char, char, boolean)
     * @since 2.5
     */
    public static CharRange isNot(final char ch) {
        return new CharRange(ch, ch, true);
    }

    
Constructs a CharRange over a set of characters.
Params:
start –  first character, inclusive, in this range
end –  last character, inclusive, in this range
See Also:
CharRange(char, char, boolean)
Returns:
the new CharRange object
Since:
2.5/**
     * <p>Constructs a {@code CharRange} over a set of characters.</p>
     *
     * @param start  first character, inclusive, in this range
     * @param end  last character, inclusive, in this range
     * @return the new CharRange object
     * @see CharRange#CharRange(char, char, boolean)
     * @since 2.5
     */
    public static CharRange isIn(final char start, final char end) {
        return new CharRange(start, end, false);
    }

    
Constructs a negated CharRange over a set of characters.
Params:
start –  first character, inclusive, in this range
end –  last character, inclusive, in this range
See Also:
CharRange(char, char, boolean)
Returns:
the new CharRange object
Since:
2.5/**
     * <p>Constructs a negated {@code CharRange} over a set of characters.</p>
     *
     * @param start  first character, inclusive, in this range
     * @param end  last character, inclusive, in this range
     * @return the new CharRange object
     * @see CharRange#CharRange(char, char, boolean)
     * @since 2.5
     */
    public static CharRange isNotIn(final char start, final char end) {
        return new CharRange(start, end, true);
    }

    // Accessors
    //-----------------------------------------------------------------------
    
Gets the start character for this character range.
Returns:
the start char (inclusive)/**
     * <p>Gets the start character for this character range.</p>
     *
     * @return the start char (inclusive)
     */
    public char getStart() {
        return this.start;
    }

    
Gets the end character for this character range.
Returns:
the end char (inclusive)/**
     * <p>Gets the end character for this character range.</p>
     *
     * @return the end char (inclusive)
     */
    public char getEnd() {
        return this.end;
    }

    
Is this CharRange negated.
A negated range includes everything except that defined by the
start and end characters.
Returns:
true if negated/**
     * <p>Is this {@code CharRange} negated.</p>
     *
     * <p>A negated range includes everything except that defined by the
     * start and end characters.</p>
     *
     * @return {@code true} if negated
     */
    public boolean isNegated() {
        return negated;
    }

    // Contains
    //-----------------------------------------------------------------------
    
Is the character specified contained in this range.
Params:
ch –  the character to check
Returns:
true if this range contains the input character/**
     * <p>Is the character specified contained in this range.</p>
     *
     * @param ch  the character to check
     * @return {@code true} if this range contains the input character
     */
    public boolean contains(final char ch) {
        return (ch >= start && ch <= end) != negated;
    }

    
Are all the characters of the passed in range contained in
this range.
Params:
range –  the range to check against
Throws:
IllegalArgumentException – if null input
Returns:
true if this range entirely contains the input range/**
     * <p>Are all the characters of the passed in range contained in
     * this range.</p>
     *
     * @param range  the range to check against
     * @return {@code true} if this range entirely contains the input range
     * @throws IllegalArgumentException if {@code null} input
     */
    public boolean contains(final CharRange range) {
        Validate.isTrue(range != null, "The Range must not be null");
        if (negated) {
            if (range.negated) {
                return start >= range.start && end <= range.end;
            }
            return range.end < start || range.start > end;
        }
        if (range.negated) {
            return start == 0 && end == Character.MAX_VALUE;
        }
        return start <= range.start && end >= range.end;
    }

    // Basics
    //-----------------------------------------------------------------------
    
Compares two CharRange objects, returning true if they represent
exactly the same range of characters defined in the same way.
Params:
obj –  the object to compare to
Returns:
true if equal/**
     * <p>Compares two CharRange objects, returning true if they represent
     * exactly the same range of characters defined in the same way.</p>
     *
     * @param obj  the object to compare to
     * @return true if equal
     */
    @Override
    public boolean equals(final Object obj) {
        if (obj == this) {
            return true;
        }
        if (!(obj instanceof CharRange)) {
            return false;
        }
        final CharRange other = (CharRange) obj;
        return start == other.start && end == other.end && negated == other.negated;
    }

    
Gets a hashCode compatible with the equals method.
Returns:
a suitable hashCode/**
     * <p>Gets a hashCode compatible with the equals method.</p>
     *
     * @return a suitable hashCode
     */
    @Override
    public int hashCode() {
        return 83 + start + 7 * end + (negated ? 1 : 0);
    }

    
Gets a string representation of the character range.
Returns:
string representation of this range/**
     * <p>Gets a string representation of the character range.</p>
     *
     * @return string representation of this range
     */
    @Override
    public String toString() {
        if (iToString == null) {
            final StringBuilder buf = new StringBuilder(4);
            if (isNegated()) {
                buf.append('^');
            }
            buf.append(start);
            if (start != end) {
                buf.append('-');
                buf.append(end);
            }
            iToString = buf.toString();
        }
        return iToString;
    }

    // Expansions
    //-----------------------------------------------------------------------
    
Returns an iterator which can be used to walk through the characters described by this range.
#NotThreadSafe# the iterator is not thread-safe
Returns:
an iterator to the chars represented by this range
Since:
2.5/**
     * <p>Returns an iterator which can be used to walk through the characters described by this range.</p>
     *
     * <p>#NotThreadSafe# the iterator is not thread-safe</p>
     * @return an iterator to the chars represented by this range
     * @since 2.5
     */
    @Override
    public Iterator<Character> iterator() {
        return new CharacterIterator(this);
    }

    
Character Iterator. 
#NotThreadSafe#
/**
     * Character {@link Iterator}.
     * <p>#NotThreadSafe#</p>
     */
    private static class CharacterIterator implements Iterator<Character> {
        
The current character /** The current character */
        private char current;

        private final CharRange range;
        private boolean hasNext;

        
Construct a new iterator for the character range.
Params:
r – The character range/**
         * Construct a new iterator for the character range.
         *
         * @param r The character range
         */
        private CharacterIterator(final CharRange r) {
            range = r;
            hasNext = true;

            if (range.negated) {
                if (range.start == 0) {
                    if (range.end == Character.MAX_VALUE) {
                        // This range is an empty set
                        hasNext = false;
                    } else {
                        current = (char) (range.end + 1);
                    }
                } else {
                    current = 0;
                }
            } else {
                current = range.start;
            }
        }

        
Prepare the next character in the range.
/**
         * Prepare the next character in the range.
         */
        private void prepareNext() {
            if (range.negated) {
                if (current == Character.MAX_VALUE) {
                    hasNext = false;
                } else if (current + 1 == range.start) {
                    if (range.end == Character.MAX_VALUE) {
                        hasNext = false;
                    } else {
                        current = (char) (range.end + 1);
                    }
                } else {
                    current = (char) (current + 1);
                }
            } else if (current < range.end) {
                current = (char) (current + 1);
            } else {
                hasNext = false;
            }
        }

        
Has the iterator not reached the end character yet?
Returns:
true if the iterator has yet to reach the character date/**
         * Has the iterator not reached the end character yet?
         *
         * @return {@code true} if the iterator has yet to reach the character date
         */
        @Override
        public boolean hasNext() {
            return hasNext;
        }

        
Return the next character in the iteration
Returns:
Character for the next character/**
         * Return the next character in the iteration
         *
         * @return {@code Character} for the next character
         */
        @Override
        public Character next() {
            if (!hasNext) {
                throw new NoSuchElementException();
            }
            final char cur = current;
            prepareNext();
            return Character.valueOf(cur);
        }

        
Always throws UnsupportedOperationException.
Throws:
UnsupportedOperationException – 
See Also:
Iterator.remove()/**
         * Always throws UnsupportedOperationException.
         *
         * @throws UnsupportedOperationException
         * @see java.util.Iterator#remove()
         */
        @Override
        public void remove() {
            throw new UnsupportedOperationException();
        }
    }
}