/*
 *    GeoTools - The Open Source Java GIS Toolkit
 *    http://geotools.org
 * 
 *    (C) 2007-2008, Open Source Geospatial Foundation (OSGeo)
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotools.referencing.cs;

import java.io.Serializable;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import org.opengis.referencing.cs.AxisDirection;


/**
 * Parses {@linkplain AxisDirection axis direction} of the kind
 * "<cite>South along 90 deg East</cite>". Those directions are
 * used in the EPSG database for polar stereographic projections.
 *
 * @version $Id: DirectionAlongMeridian.java 37409 2011-06-11 10:01:00Z aaime $
 * @source $URL: http://svn.osgeo.org/geotools/branches/2.7.x/modules/library/referencing/src/main/java/org/geotools/referencing/cs/DirectionAlongMeridian.java $
 * @author Martin Desruisseaux
 * @since 2.7.2
 */
public final class DirectionAlongMeridian implements Comparable, Serializable {
    /**
     * For cross-version compatibility.
     */
    private static final long serialVersionUID = 1602711631943838328L;

    /**
     * For floating point comparaisons.
     */
    static final double EPS = 1E-10;

    /**
     * A parser for EPSG axis names. Examples:
     *
     * "<cite>South along 180 deg</cite>",
     * "<cite>South along 90 deg East</cite>"
     */
    private static final Pattern EPSG = Pattern.compile(
            "(\\p{Graph}+)\\s+along\\s+([\\-\\p{Digit}\\.]+)\\s*(deg|°)\\s*(\\p{Graph}+)?",
            Pattern.CASE_INSENSITIVE);

    /**
     * The base directions we are interested in. Any direction not in
     * this group will be rejected by our parser.
     */
    private static final AxisDirection[] BASE_DIRECTIONS = new AxisDirection[] {
        AxisDirection.NORTH,
        AxisDirection.SOUTH,
        AxisDirection.EAST,
        AxisDirection.WEST
    };

    /**
     * The direction. Will be created only when first needed.
     *
     * @see #getDirection
     */
    private transient AxisDirection direction;

    /**
     * The base direction, which must be {@link AxisDirection#NORTH} or
     * {@link AxisDirection#SOUTH}.
     */
    public final AxisDirection baseDirection;

    /**
     * The meridian, in degrees.
     */
    public final double meridian;

    /**
     * Creates a direction.
     */
    private DirectionAlongMeridian(final AxisDirection baseDirection, final double meridian) {
        this.baseDirection = baseDirection;
        this.meridian      = meridian;
    }

    /**
     * Returns the dimension along meridian for the specified axis direction, or {@code null} if
     * none.
     */
    public static DirectionAlongMeridian parse(final AxisDirection direction) {
        final DirectionAlongMeridian candidate = parse(direction.name());
        if (candidate != null) {
            candidate.direction = direction;
        }
        return candidate;
    }

    /**
     * If the specified name is a direction along some specific meridian,
     * returns information about that. Otherwise returns {@code null}.
     */
    public static DirectionAlongMeridian parse(final String name) {
        final Matcher m = EPSG.matcher(name);
        if (!m.matches()) {
            // Not the expected pattern.
            return null;
        }
        String group = m.group(1);
        final AxisDirection baseDirection = findDirection(BASE_DIRECTIONS, group);
        if (baseDirection == null || !AxisDirection.NORTH.equals(baseDirection.absolute())) {
            // We expected "North" or "South" direction.
            return null;
        }
        group = m.group(2);
        double meridian;
        try {
            meridian = Double.parseDouble(group);
        } catch (NumberFormatException exception) {
            // Not a legal axis direction. Just ignore the exception,
            // since we are supposed to return 'null' in this situation.
            return null;
        }
        if (!(meridian >= -180 && meridian <= 180)) {
            // Meridian is NaN or is not in the valid range.
            return null;
        }
        group = m.group(4);
        if (group != null) {
            final AxisDirection sign = findDirection(BASE_DIRECTIONS, group);
            final AxisDirection abs = sign.absolute();
            if (!AxisDirection.EAST.equals(abs)) {
                // We expected "East" or "West" direction.
                return null;
            }
            if (sign != abs) {
                meridian = -meridian;
            }
        }
        return new DirectionAlongMeridian(baseDirection, meridian);
    }

    /**
     * Searchs for the specified name in the specified set of directions.
     */
    private static AxisDirection findDirection(final AxisDirection[] values, final String direction) {
        for (int i=0; i<values.length; i++) {
            final AxisDirection candidate = values[i];
            final String name = candidate.name();
            if (direction.equalsIgnoreCase(name)) {
                return candidate;
            } 
            
            // check for common abbreviations
            if(direction.length() == 1) {
                if(candidate == AxisDirection.NORTH && direction.equals("N"))
                    return candidate;
                if(candidate == AxisDirection.SOUTH && direction.equals("S"))
                    return candidate;
                if(candidate == AxisDirection.WEST && direction.equals("W"))
                    return candidate;
                if(candidate == AxisDirection.EAST && direction.equals("E"))
                    return candidate;
            }
        }
        return null;
    }

    /**
     * Searchs for the specified name.
     */
    static AxisDirection findDirection(String direction) {
        final AxisDirection[] values = AxisDirection.values();
        AxisDirection candidate = findDirection(values, direction);
        if (candidate == null) {
            String modified = direction.replace('-', '_');
            if (modified != direction) {
                direction = modified;
                candidate = findDirection(values, modified);
            }
            if (candidate == null) {
                modified = direction.replace(' ', '_');
                if (modified != direction) {
                    candidate = findDirection(values, modified);
                }
            }
        }
        return candidate;
    }

    /**
     * Returns the axis direction for this object. If a suitable axis direction already exists,
     * it will be returned. Otherwise a new one is created and returned.
     */
    public AxisDirection getDirection() {
        if (direction != null) {
            return direction;
        }
        final String name = toString();
        synchronized (AxisDirection.class) {
            /*
             * The calls to  'AxisDirection.values()' and 'findDirection(...)'  should be performed
             * inside the synchronized block, since we try to avoid the creation of many directions
             * for the same name.   Strictly speaking, this synchronization is not suffisient since
             * it doesn't apply to the creation of axis directions from outside this class.  But it
             * okay if this code is the only place where we create axis directions with name of the
             * kind "South among 90°E". This assumption holds for Geotools implementation.
             */
            direction = findDirection(name);
            if (direction == null) {
                direction = AxisDirection.valueOf(name);
            }
        }
        return direction;
    }

    /**
     * Returns the arithmetic (counterclockwise) angle from this direction to the specified
     * direction, in decimal degrees. This method returns a value between -180° and +180°, or
     * {@link Double#NaN NaN} if the {@linkplain #baseDirection base directions} don't match.
     * A positive angle denote a right-handed system.
     * <p>
     * Example: the angle from "<cite>North along 90 deg East</cite>" to
     * "<cite>North along 0 deg</cite> is 90°.
     */
    public double getAngle(final DirectionAlongMeridian other) {
        if (!baseDirection.equals(other.baseDirection)) {
            return Double.NaN;
        }
        /*
         * We want the following pair of axis:
         * (NORTH along 90°E, NORTH along 0°)
         * to give a positive angle of 90°
         */
        double angle = meridian - other.meridian;
        /*
         * Forces to the [-180° .. +180°] range.
         */
        if (angle < -180) {
            angle += 360;
        } else if (angle > 180) {
            angle -= 360;
        }
        /*
         * Reverses the sign for axis oriented toward SOUTH,
         * so a positive angle is a right-handed system.
         */
        if (!baseDirection.equals(baseDirection.absolute())) {
            angle = -angle;
        }
        return angle;
    }

    /**
     * Compares this direction with the specified one for order. This method tries to reproduce
     * the ordering used for the majority of coordinate systems in the EPSG database, i.e. the
     * ordering of a right-handed coordinate system. Examples of ordered pairs that we should
     * get (extracted from the EPSG database):
     *
     * <table>
     *   <tr><td>North along 90 deg East,</td>  <td>North along 0 deg</td></tr>
     *   <tr><td>North along 75 deg West,</td>  <td>North along 165 deg West</td></tr>
     *   <tr><td>South along 90 deg West,</td>  <td>South along 0 deg</td></tr>
     *   <tr><td>South along 180 deg,</td>      <td>South along 90 deg West</td></tr>
     *   <tr><td>North along 130 deg West</td>  <td>North along 140 deg East</td></tr>
     * </table>
     */
    public int compareTo(final Object object) {
        final DirectionAlongMeridian that = (DirectionAlongMeridian) object;
        final int c = baseDirection.compareTo(that.baseDirection);
        if (c != 0) {
            return c;
        }
        final double angle = getAngle(that);
        if (angle < 0) return +1;  // Really the opposite sign.
        if (angle > 0) return -1;  // Really the opposite sign.
        return 0;
    }

    /**
     * Tests this object for equality with the specified one.
     * This method is used mostly for assertions.
     */
    @Override
    public boolean equals(final Object object) {
        if (object instanceof DirectionAlongMeridian) {
            final DirectionAlongMeridian that = (DirectionAlongMeridian) object;
            return baseDirection.equals(that.baseDirection) &&
                   Double.doubleToLongBits(meridian) == Double.doubleToLongBits(that.meridian);
        }
        return false;
    }

    /**
     * Returns a hash code value, for consistency with {@link #equals}.
     */
    @Override
    public int hashCode() {
        final long code = Double.doubleToLongBits(meridian);
        return (int)serialVersionUID ^ (int)code ^ (int)(code >> 32) + 37*baseDirection.hashCode();
    }

    /**
     * Returns a string representation of this direction, using a syntax matching the one used
     * by EPSG. This string representation will be used for creating a new {@link AxisDirection}.
     * The generated name should be identical to EPSG name, but we use the generated one anyway
     * (rather than the one provided by EPSG) in order to make sure that we create a single
     * {@link AxisDirection} for a given direction; we avoid potential differences like lower
     * versus upper cases, amount of white space, <cite>etc</cite>.
     */
    @Override
    public String toString() {
        final StringBuilder buffer = new StringBuilder(baseDirection.name());
        toLowerCase(buffer, 0);
        buffer.append(" along ");
        final double md = Math.abs(meridian);
        final int    mi = (int) md;
        if (md == mi) {
            buffer.append(mi);
        } else {
            buffer.append(md);
        }
        buffer.append(" deg");
        if (md != 0 && mi != 180) {
            buffer.append(' ');
            final int base = buffer.length();
            final AxisDirection sign = meridian < 0 ? AxisDirection.WEST : AxisDirection.EAST;
            buffer.append(sign.name());
            toLowerCase(buffer, base);
        }
        final String name = buffer.toString();
        assert EPSG.matcher(name).matches() : name;
        return name;
    }

    /**
     * Changes the buffer content to lower case from {@code base+1} to
     * the end of the buffer. For {@link #toString} internal use only.
     */
    private static void toLowerCase(final StringBuilder buffer, final int base) {
        for (int i=buffer.length(); --i>base;) {
            buffer.setCharAt(i, Character.toLowerCase(buffer.charAt(i)));
        }
    }
}
