/*
 * 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 freemarker.template.utility;

import java.text.ParseException;
import java.util.Calendar;
import java.util.Date;
import java.util.GregorianCalendar;
import java.util.Locale;
import java.util.TimeZone;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Date and time related utilities.
 */
public class DateUtil {

    /**
     * Show hours (24h); always 2 digits, like {@code 00}, {@code 05}, etc.
     */
    public static final int ACCURACY_HOURS = 4;
    
    /**
     * Show hours and minutes (even if minutes is 00).
     */
    public static final int ACCURACY_MINUTES = 5;
    
    /**
     * Show hours, minutes and seconds (even if seconds is 00).
     */
    public static final int ACCURACY_SECONDS = 6;
    
    /**
     * Show hours, minutes and seconds and up to 3 fraction second digits, without trailing 0-s in the fraction part. 
     */
    public static final int ACCURACY_MILLISECONDS = 7;
    
    /**
     * Show hours, minutes and seconds and exactly 3 fraction second digits (even if it's 000)
     */
    public static final int ACCURACY_MILLISECONDS_FORCED = 8;
    
    public static final TimeZone UTC = TimeZone.getTimeZone("UTC");
    
    private static final String REGEX_XS_TIME_ZONE
            = "Z|(?:[-+][0-9]{2}:[0-9]{2})";
    private static final String REGEX_ISO8601_BASIC_TIME_ZONE
            = "Z|(?:[-+][0-9]{2}(?:[0-9]{2})?)";
    private static final String REGEX_ISO8601_EXTENDED_TIME_ZONE
            = "Z|(?:[-+][0-9]{2}(?::[0-9]{2})?)";
    
    private static final String REGEX_XS_OPTIONAL_TIME_ZONE
            = "(" + REGEX_XS_TIME_ZONE + ")?";
    private static final String REGEX_ISO8601_BASIC_OPTIONAL_TIME_ZONE
            = "(" + REGEX_ISO8601_BASIC_TIME_ZONE + ")?";
    private static final String REGEX_ISO8601_EXTENDED_OPTIONAL_TIME_ZONE
            = "(" + REGEX_ISO8601_EXTENDED_TIME_ZONE + ")?";
    
    private static final String REGEX_XS_DATE_BASE
            = "(-?[0-9]+)-([0-9]{2})-([0-9]{2})";
    private static final String REGEX_ISO8601_BASIC_DATE_BASE
            = "(-?[0-9]{4,}?)([0-9]{2})([0-9]{2})";
    private static final String REGEX_ISO8601_EXTENDED_DATE_BASE
            = "(-?[0-9]{4,})-([0-9]{2})-([0-9]{2})";
    
    private static final String REGEX_XS_TIME_BASE
            = "([0-9]{2}):([0-9]{2}):([0-9]{2})(?:\\.([0-9]+))?";
    private static final String REGEX_ISO8601_BASIC_TIME_BASE
            = "([0-9]{2})(?:([0-9]{2})(?:([0-9]{2})(?:[\\.,]([0-9]+))?)?)?";
    private static final String REGEX_ISO8601_EXTENDED_TIME_BASE
            = "([0-9]{2})(?::([0-9]{2})(?::([0-9]{2})(?:[\\.,]([0-9]+))?)?)?";
        
    private static final Pattern PATTERN_XS_DATE = Pattern.compile(
            REGEX_XS_DATE_BASE + REGEX_XS_OPTIONAL_TIME_ZONE);
    private static final Pattern PATTERN_ISO8601_BASIC_DATE = Pattern.compile(
            REGEX_ISO8601_BASIC_DATE_BASE); // No time zone allowed here
    private static final Pattern PATTERN_ISO8601_EXTENDED_DATE = Pattern.compile(
            REGEX_ISO8601_EXTENDED_DATE_BASE); // No time zone allowed here

    private static final Pattern PATTERN_XS_TIME = Pattern.compile(
            REGEX_XS_TIME_BASE + REGEX_XS_OPTIONAL_TIME_ZONE);
    private static final Pattern PATTERN_ISO8601_BASIC_TIME = Pattern.compile(
            REGEX_ISO8601_BASIC_TIME_BASE + REGEX_ISO8601_BASIC_OPTIONAL_TIME_ZONE);
    private static final Pattern PATTERN_ISO8601_EXTENDED_TIME = Pattern.compile(
            REGEX_ISO8601_EXTENDED_TIME_BASE + REGEX_ISO8601_EXTENDED_OPTIONAL_TIME_ZONE);
    
    private static final Pattern PATTERN_XS_DATE_TIME = Pattern.compile(
            REGEX_XS_DATE_BASE
            + "T" + REGEX_XS_TIME_BASE
            + REGEX_XS_OPTIONAL_TIME_ZONE);
    private static final Pattern PATTERN_ISO8601_BASIC_DATE_TIME = Pattern.compile(
            REGEX_ISO8601_BASIC_DATE_BASE
            + "T" + REGEX_ISO8601_BASIC_TIME_BASE
            + REGEX_ISO8601_BASIC_OPTIONAL_TIME_ZONE);
    private static final Pattern PATTERN_ISO8601_EXTENDED_DATE_TIME = Pattern.compile(
            REGEX_ISO8601_EXTENDED_DATE_BASE
            + "T" + REGEX_ISO8601_EXTENDED_TIME_BASE
            + REGEX_ISO8601_EXTENDED_OPTIONAL_TIME_ZONE);
    
    private static final Pattern PATTERN_XS_TIME_ZONE = Pattern.compile(
            REGEX_XS_TIME_ZONE);
    
    private static final String MSG_YEAR_0_NOT_ALLOWED
            = "Year 0 is not allowed in XML schema dates. BC 1 is -1, AD 1 is 1.";
    
    private DateUtil() {
        // can't be instantiated
    }
    
    /**
     * Returns the time zone object for the name (or ID). This differs from
     * {@link TimeZone#getTimeZone(String)} in that the latest returns GMT
     * if it doesn't recognize the name, while this throws an
     * {@link UnrecognizedTimeZoneException}.
     * 
     * @throws UnrecognizedTimeZoneException If the time zone name wasn't understood
     */
    public static TimeZone getTimeZone(String name)
    throws UnrecognizedTimeZoneException {
        if (isGMTish(name)) {
            if (name.equalsIgnoreCase("UTC")) {
                return UTC;
            }
            return TimeZone.getTimeZone(name);
        }
        TimeZone tz = TimeZone.getTimeZone(name);
        if (isGMTish(tz.getID())) {
            throw new UnrecognizedTimeZoneException(name);
        }
        return tz;
    }

    /**
     * Tells if a offset or time zone is GMT. GMT is a fuzzy term, it used to
     * referred both to UTC and UT1.
     */
    private static boolean isGMTish(String name) {
        if (name.length() < 3) {
            return false;
        }
        char c1 = name.charAt(0);
        char c2 = name.charAt(1);
        char c3 = name.charAt(2);
        if (
                !(
                       (c1 == 'G' || c1 == 'g')
                    && (c2 == 'M' || c2 == 'm')
                    && (c3 == 'T' || c3 == 't')
                )
                &&
                !(
                       (c1 == 'U' || c1 == 'u')
                    && (c2 == 'T' || c2 == 't')
                    && (c3 == 'C' || c3 == 'c')
                )
                &&
                !(
                       (c1 == 'U' || c1 == 'u')
                    && (c2 == 'T' || c2 == 't')
                    && (c3 == '1')
                )
                ) {
            return false;
        }
        
        if (name.length() == 3) {
            return true;
        }
        
        String offset = name.substring(3);
        if (offset.startsWith("+")) {
            return offset.equals("+0") || offset.equals("+00")
                    || offset.equals("+00:00");
        } else {
            return offset.equals("-0") || offset.equals("-00")
            || offset.equals("-00:00");
        }
    }

    /**
     * Format a date, time or dateTime with one of the ISO 8601 extended
     * formats that is also compatible with the XML Schema format (as far as you
     * don't have dates in the BC era). Examples of possible outputs:
     * {@code "2005-11-27T15:30:00+02:00"}, {@code "2005-11-27"},
     * {@code "15:30:00Z"}. Note the {@code ":00"} in the time zone offset;
     * this is not required by ISO 8601, but included for compatibility with
     * the XML Schema format. Regarding the B.C. issue, those dates will be
     * one year off when read back according the XML Schema format, because of a
     * mismatch between that format and ISO 8601:2000 Second Edition.  
     * 
     * <p>This method is thread-safe.
     * 
     * @param date the date to convert to ISO 8601 string
     * @param datePart whether the date part (year, month, day) will be included
     *        or not
     * @param timePart whether the time part (hours, minutes, seconds,
     *        milliseconds) will be included or not
     * @param offsetPart whether the time zone offset part will be included or
     *        not. This will be shown as an offset to UTC (examples:
     *        {@code "+01"}, {@code "-02"}, {@code "+04:30"}) or as {@code "Z"}
     *        for UTC (and for UT1 and for GMT+00, since the Java platform
     *        doesn't really care about the difference).
     *        Note that this can't be {@code true} when {@code timePart} is
     *        {@code false}, because ISO 8601 (2004) doesn't mention such
     *        patterns.
     * @param accuracy tells which parts of the date/time to drop. The
     *        {@code datePart} and {@code timePart} parameters are stronger than
     *        this. Note that when {@link #ACCURACY_MILLISECONDS} is specified,
     *        the milliseconds part will be displayed as fraction seconds
     *        (like {@code "15:30.00.25"}) with the minimum number of
     *        digits needed to show the milliseconds without precision lose.
     *        Thus, if the milliseconds happen to be exactly 0, no fraction
     *        seconds will be shown at all.
     * @param timeZone the time zone in which the date/time will be shown. (You
     *        may find {@link DateUtil#UTC} handy here.) Note
     *        that although date-only formats has no time zone offset part,
     *        the result still depends on the time zone, as days start and end
     *        at different points on the time line in different zones.      
     * @param calendarFactory the factory that will create the calendar used
     *        internally for calculations. The point of this parameter is that
     *        creating a new calendar is relatively expensive, so it's desirable
     *        to reuse calendars and only set their time and zone. (This was
     *        tested on Sun JDK 1.6 x86 Win, where it gave 2x-3x speedup.) 
     */
    public static String dateToISO8601String(
            Date date,
            boolean datePart, boolean timePart, boolean offsetPart,
            int accuracy,
            TimeZone timeZone,
            DateToISO8601CalendarFactory calendarFactory) {
        return dateToString(date, datePart, timePart, offsetPart, accuracy, timeZone, false, calendarFactory);
    }

    /**
     * Same as {@link #dateToISO8601String}, but gives XML Schema compliant format.
     */
    public static String dateToXSString(
            Date date,
            boolean datePart, boolean timePart, boolean offsetPart,
            int accuracy,
            TimeZone timeZone,
            DateToISO8601CalendarFactory calendarFactory) {
        return dateToString(date, datePart, timePart, offsetPart, accuracy, timeZone, true, calendarFactory);
    }
    
    private static String dateToString(
            Date date,
            boolean datePart, boolean timePart, boolean offsetPart,
            int accuracy,
            TimeZone timeZone, boolean xsMode,
            DateToISO8601CalendarFactory calendarFactory) {
        if (!xsMode && !timePart && offsetPart) {
            throw new IllegalArgumentException(
                    "ISO 8601:2004 doesn't specify any formats where the "
                    + "offset is shown but the time isn't.");
        }
        
        if (timeZone == null) {
            timeZone = UTC;
        }
        
        GregorianCalendar cal = calendarFactory.get(timeZone, date);

        int maxLength;
        if (!timePart) {
            maxLength = 10 + (xsMode ? 6 : 0);  // YYYY-MM-DD+00:00
        } else {
            if (!datePart) {
                maxLength = 12 + 6;  // HH:MM:SS.mmm+00:00
            } else {
                maxLength = 10 + 1 + 12 + 6;
            }
        }
        char[] res = new char[maxLength];
        int dstIdx = 0;
        
        if (datePart) {
            int x = cal.get(Calendar.YEAR);
            if (x > 0 && cal.get(Calendar.ERA) == GregorianCalendar.BC) {
                x = -x + (xsMode ? 0 : 1);
            }
            if (x >= 0 && x < 9999) {
                res[dstIdx++] = (char) ('0' + x / 1000);
                res[dstIdx++] = (char) ('0' + x % 1000 / 100);
                res[dstIdx++] = (char) ('0' + x % 100 / 10);
                res[dstIdx++] = (char) ('0' + x % 10);
            } else {
                String yearString = String.valueOf(x);
                
                // Re-allocate buffer:
                maxLength = maxLength - 4 + yearString.length();
                res = new char[maxLength];
                
                for (int i = 0; i < yearString.length(); i++) {
                    res[dstIdx++] = yearString.charAt(i);
                }
            }
    
            res[dstIdx++] = '-';
            
            x = cal.get(Calendar.MONTH) + 1;
            dstIdx = append00(res, dstIdx, x);
    
            res[dstIdx++] = '-';
            
            x = cal.get(Calendar.DAY_OF_MONTH);
            dstIdx = append00(res, dstIdx, x);

            if (timePart) {
                res[dstIdx++] = 'T';
            }
        }

        if (timePart) {
            int x = cal.get(Calendar.HOUR_OF_DAY);
            dstIdx = append00(res, dstIdx, x);
    
            if (accuracy >= ACCURACY_MINUTES) {
                res[dstIdx++] = ':';
        
                x = cal.get(Calendar.MINUTE);
                dstIdx = append00(res, dstIdx, x);
        
                if (accuracy >= ACCURACY_SECONDS) {
                    res[dstIdx++] = ':';
            
                    x = cal.get(Calendar.SECOND);
                    dstIdx = append00(res, dstIdx, x);
            
                    if (accuracy >= ACCURACY_MILLISECONDS) {
                        x = cal.get(Calendar.MILLISECOND);
                        int forcedDigits = accuracy == ACCURACY_MILLISECONDS_FORCED ? 3 : 0;
                        if (x != 0 || forcedDigits != 0) {
                            if (x > 999) {
                                // Shouldn't ever happen...
                                throw new RuntimeException(
                                        "Calendar.MILLISECOND > 999");
                            }
                            res[dstIdx++] = '.';
                            do {
                                res[dstIdx++] = (char) ('0' + (x / 100));
                                forcedDigits--;
                                x = x % 100 * 10;
                            } while (x != 0 || forcedDigits > 0);
                        }
                    }
                }
            }
        }

        if (offsetPart) {
            if (timeZone == UTC) {
                res[dstIdx++] = 'Z';
            } else {
                int dt = timeZone.getOffset(date.getTime());
                boolean positive;
                if (dt < 0) {
                    positive = false;
                    dt = -dt;
                } else {
                    positive = true;
                }
                
                dt /= 1000;
                int offS = dt % 60;
                dt /= 60;
                int offM = dt % 60;
                dt /= 60;
                int offH = dt;
                
                if (offS == 0 && offM == 0 && offH == 0) {
                    res[dstIdx++] = 'Z';
                } else {
                    res[dstIdx++] = positive ? '+' : '-';
                    dstIdx = append00(res, dstIdx, offH);
                    res[dstIdx++] = ':';
                    dstIdx = append00(res, dstIdx, offM);
                    if (offS != 0) {
                        res[dstIdx++] = ':';
                        dstIdx = append00(res, dstIdx, offS);
                    }
                }
            }
        }
        
        return new String(res, 0, dstIdx);
    }
    
    /** 
     * Appends a number between 0 and 99 padded to 2 digits.
     */
    private static int append00(char[] res, int dstIdx, int x) {
        res[dstIdx++] = (char) ('0' + x / 10);
        res[dstIdx++] = (char) ('0' + x % 10);
        return dstIdx;
    }
    
    /**
     * Parses an W3C XML Schema date string (not time or date-time).
     * Unlike in ISO 8601:2000 Second Edition, year -1 means B.C 1, and year 0 is invalid. 
     * 
     * @param dateStr the string to parse. 
     * @param defaultTimeZone used if the date doesn't specify the
     *     time zone offset explicitly. Can't be {@code null}.
     * @param calToDateConverter Used internally to calculate the result from the calendar field values.
     *     If you don't have a such object around, you can just use
     *     {@code new }{@link TrivialCalendarFieldsToDateConverter}{@code ()}. 
     * 
     * @throws DateParseException if the date is malformed, or if the time
     *     zone offset is unspecified and the {@code defaultTimeZone} is
     *     {@code null}.
     */
    public static Date parseXSDate(
            String dateStr, TimeZone defaultTimeZone,
            CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        Matcher m = PATTERN_XS_DATE.matcher(dateStr);
        if (!m.matches()) {
            throw new DateParseException("The value didn't match the expected pattern: " + PATTERN_XS_DATE); 
        }
        return parseDate_parseMatcher(
                m, defaultTimeZone, true, calToDateConverter);
    }

    /**
     * Same as {@link #parseXSDate(String, TimeZone, CalendarFieldsToDateConverter)}, but for ISO 8601 dates.
     */
    public static Date parseISO8601Date(
            String dateStr, TimeZone defaultTimeZone,
            CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        Matcher m = PATTERN_ISO8601_EXTENDED_DATE.matcher(dateStr);
        if (!m.matches()) {
            m = PATTERN_ISO8601_BASIC_DATE.matcher(dateStr);
            if (!m.matches()) {
                throw new DateParseException("The value didn't match the expected pattern: "
                            + PATTERN_ISO8601_EXTENDED_DATE + " or "
                            + PATTERN_ISO8601_BASIC_DATE);
            }
        }
        return parseDate_parseMatcher(
                m, defaultTimeZone, false, calToDateConverter);
    }
    
    private static Date parseDate_parseMatcher(
            Matcher m, TimeZone defaultTZ,
            boolean xsMode,
            CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        NullArgumentException.check("defaultTZ", defaultTZ);
        try {
            int year = groupToInt(m.group(1), "year", Integer.MIN_VALUE, Integer.MAX_VALUE);
            
            int era;
            // Starting from ISO 8601:2000 Second Edition, 0001 is AD 1, 0000 is BC 1, -0001 is BC 2.
            // However, according to http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/, XML schemas are based
            // on the earlier version where 0000 didn't exist, and year -1 is BC 1.
            if (year <= 0) {
                era = GregorianCalendar.BC;
                year = -year + (xsMode ? 0 : 1);
                if (year == 0) {
                    throw new DateParseException(MSG_YEAR_0_NOT_ALLOWED);
                }
            } else {
                era = GregorianCalendar.AD;
            }
            
            int month = groupToInt(m.group(2), "month", 1, 12) - 1;
            int day = groupToInt(m.group(3), "day-of-month", 1, 31);

            TimeZone tz = xsMode ? parseMatchingTimeZone(m.group(4), defaultTZ) : defaultTZ;
            
            return calToDateConverter.calculate(era, year, month, day, 0, 0, 0, 0, false, tz);
        } catch (IllegalArgumentException e) {
            // Calendar methods used to throw this for illegal dates.
            throw new DateParseException(
                    "Date calculation faliure. "
                    + "Probably the date is formally correct, but refers "
                    + "to an unexistent date (like February 30)."); 
        }
    }
    
    /**
     * Parses an W3C XML Schema time string (not date or date-time).
     * If the time string doesn't specify the time zone offset explicitly,
     * the value of the {@code defaultTZ} paramter will be used. 
     */  
    public static Date parseXSTime(
            String timeStr, TimeZone defaultTZ, CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        Matcher m = PATTERN_XS_TIME.matcher(timeStr);
        if (!m.matches()) {
            throw new DateParseException("The value didn't match the expected pattern: " + PATTERN_XS_TIME);
        }
        return parseTime_parseMatcher(m, defaultTZ, calToDateConverter);
    }

    /**
     * Same as {@link #parseXSTime(String, TimeZone, CalendarFieldsToDateConverter)} but for ISO 8601 times.
     */
    public static Date parseISO8601Time(
            String timeStr, TimeZone defaultTZ, CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        Matcher m = PATTERN_ISO8601_EXTENDED_TIME.matcher(timeStr);
        if (!m.matches()) {
            m = PATTERN_ISO8601_BASIC_TIME.matcher(timeStr);
            if (!m.matches()) {
                throw new DateParseException("The value didn't match the expected pattern: "
                            + PATTERN_ISO8601_EXTENDED_TIME + " or "
                            + PATTERN_ISO8601_BASIC_TIME);
            }
        }
        return parseTime_parseMatcher(m, defaultTZ, calToDateConverter);
    }
    
    private static Date parseTime_parseMatcher(
            Matcher m, TimeZone defaultTZ,
            CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        NullArgumentException.check("defaultTZ", defaultTZ);
        try {
            // ISO 8601 allows both 00:00 and 24:00,
            // but Calendar.set(...) doesn't if the Calendar is not lenient.
            int hours = groupToInt(m.group(1), "hour-of-day", 0, 24);
            boolean hourWas24;
            if (hours == 24) {
                hours = 0;
                hourWas24 = true;
                // And a day will be added later...
            } else {
                hourWas24 = false;
            }
            
            final String minutesStr = m.group(2);
            int minutes = minutesStr != null ? groupToInt(minutesStr, "minute", 0, 59) : 0;
            
            final String secsStr = m.group(3);
            // Allow 60 because of leap seconds
            int secs = secsStr != null ? groupToInt(secsStr, "second", 0, 60) : 0;
            
            int millisecs = groupToMillisecond(m.group(4));
            
            // As a time is just the distance from the beginning of the day,
            // the time-zone offest should be 0 usually.
            TimeZone tz = parseMatchingTimeZone(m.group(5), defaultTZ);
            
            // Continue handling the 24:00 special case
            int day;
            if (hourWas24) {
                if (minutes == 0 && secs == 0 && millisecs == 0) {
                    day = 2;
                } else {
                    throw new DateParseException(
                            "Hour 24 is only allowed in the case of "
                            + "midnight."); 
                }
            } else {
                day = 1;
            }
            
            return calToDateConverter.calculate(
                    GregorianCalendar.AD, 1970, 0, day, hours, minutes, secs, millisecs, false, tz);
        } catch (IllegalArgumentException e) {
            // Calendar methods used to throw this for illegal dates.
            throw new DateParseException(
                    "Unexpected time calculation faliure."); 
        }
    }
    
    /**
     * Parses an W3C XML Schema date-time string (not date or time).
     * Unlike in ISO 8601:2000 Second Edition, year -1 means B.C 1, and year 0 is invalid. 
     * 
     * @param dateTimeStr the string to parse. 
     * @param defaultTZ used if the dateTime doesn't specify the
     *     time zone offset explicitly. Can't be {@code null}. 
     * 
     * @throws DateParseException if the dateTime is malformed.
     */
    public static Date parseXSDateTime(
            String dateTimeStr, TimeZone defaultTZ, CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        Matcher m = PATTERN_XS_DATE_TIME.matcher(dateTimeStr);
        if (!m.matches()) {
            throw new DateParseException(
                    "The value didn't match the expected pattern: " + PATTERN_XS_DATE_TIME);
        }
        return parseDateTime_parseMatcher(
                m, defaultTZ, true, calToDateConverter);
    }

    /**
     * Same as {@link #parseXSDateTime(String, TimeZone, CalendarFieldsToDateConverter)} but for ISO 8601 format. 
     */
    public static Date parseISO8601DateTime(
            String dateTimeStr, TimeZone defaultTZ, CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        Matcher m = PATTERN_ISO8601_EXTENDED_DATE_TIME.matcher(dateTimeStr);
        if (!m.matches()) {
            m = PATTERN_ISO8601_BASIC_DATE_TIME.matcher(dateTimeStr);
            if (!m.matches()) {
                throw new DateParseException("The value (" + dateTimeStr + ") didn't match the expected pattern: "
                            + PATTERN_ISO8601_EXTENDED_DATE_TIME + " or "
                            + PATTERN_ISO8601_BASIC_DATE_TIME);
            }
        }
        return parseDateTime_parseMatcher(
                m, defaultTZ, false, calToDateConverter);
    }
    
    private static Date parseDateTime_parseMatcher(
            Matcher m, TimeZone defaultTZ,
            boolean xsMode,
            CalendarFieldsToDateConverter calToDateConverter) 
            throws DateParseException {
        NullArgumentException.check("defaultTZ", defaultTZ);
        try {
            int year = groupToInt(m.group(1), "year", Integer.MIN_VALUE, Integer.MAX_VALUE);
            
            int era;
            // Starting from ISO 8601:2000 Second Edition, 0001 is AD 1, 0000 is BC 1, -0001 is BC 2.
            // However, according to http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/, XML schemas are based
            // on the earlier version where 0000 didn't exist, and year -1 is BC 1.
            if (year <= 0) {
                era = GregorianCalendar.BC;
                year = -year + (xsMode ? 0 : 1);
                if (year == 0) {
                    throw new DateParseException(MSG_YEAR_0_NOT_ALLOWED);
                }
            } else {
                era = GregorianCalendar.AD;
            }
            
            int month = groupToInt(m.group(2), "month", 1, 12) - 1;
            int day = groupToInt(m.group(3), "day-of-month", 1, 31);
            
            // ISO 8601 allows both 00:00 and 24:00,
            // but cal.set(...) doesn't if the Calendar is not lenient.
            int hours = groupToInt(m.group(4), "hour-of-day", 0, 24);
            boolean hourWas24;
            if (hours == 24) {
                hours = 0;
                hourWas24 = true;
                // And a day will be added later...
            } else {
                hourWas24 = false;
            }
            
            final String minutesStr = m.group(5);
            int minutes = minutesStr != null ? groupToInt(minutesStr, "minute", 0, 59) : 0;
            
            final String secsStr = m.group(6);
            // Allow 60 because of leap seconds
            int secs = secsStr != null ? groupToInt(secsStr, "second", 0, 60) : 0;
            
            int millisecs = groupToMillisecond(m.group(7));
            
            // As a time is just the distance from the beginning of the day,
            // the time-zone offest should be 0 usually.
            TimeZone tz = parseMatchingTimeZone(m.group(8), defaultTZ);
            
            // Continue handling the 24:00 specail case
            if (hourWas24) {
                if (minutes != 0 || secs != 0 || millisecs != 0) {
                    throw new DateParseException(
                            "Hour 24 is only allowed in the case of "
                            + "midnight."); 
                }
            }
            
            return calToDateConverter.calculate(
                    era, year, month, day, hours, minutes, secs, millisecs, hourWas24, tz);
        } catch (IllegalArgumentException e) {
            // Calendar methods used to throw this for illegal dates.
            throw new DateParseException(
                    "Date-time calculation faliure. "
                    + "Probably the date-time is formally correct, but "
                    + "refers to an unexistent date-time "
                    + "(like February 30)."); 
        }
    }

    /**
     * Parses the time zone part from a W3C XML Schema date/time/dateTime. 
     * @throws DateParseException if the zone is malformed.
     */
    public static TimeZone parseXSTimeZone(String timeZoneStr)
            throws DateParseException {
        Matcher m = PATTERN_XS_TIME_ZONE.matcher(timeZoneStr);
        if (!m.matches()) {
            throw new DateParseException(
                    "The time zone offset didn't match the expected pattern: " + PATTERN_XS_TIME_ZONE);
        }
        return parseMatchingTimeZone(timeZoneStr, null);
    }

    private static int groupToInt(String g, String gName,
            int min, int max)
            throws DateParseException {
        if (g == null) {
            throw new DateParseException("The " + gName + " part "
                    + "is missing.");
        }

        int start;
        
        // Remove minus sign, so we can remove the 0-s later:
        boolean negative;
        if (g.startsWith("-")) {
            negative = true;
            start = 1;
        } else {
            negative = false;
            start = 0;
        }
        
        // Remove leading 0-s:
        while (start < g.length() - 1 && g.charAt(start) == '0') {
            start++;
        }
        if (start != 0) {
            g = g.substring(start);
        }
        
        try {
            int r = Integer.parseInt(g);
            if (negative) {
                r = -r;
            }
            if (r < min) {
                throw new DateParseException("The " + gName + " part "
                    + "must be at least " + min + ".");
            }
            if (r > max) {
                throw new DateParseException("The " + gName + " part "
                    + "can't be more than " + max + ".");
            }
            return r;
        } catch (NumberFormatException e) {
            throw new DateParseException("The " + gName + " part "
                    + "is a malformed integer.");
        }
    }

    private static TimeZone parseMatchingTimeZone(
            String s, TimeZone defaultZone)
            throws DateParseException {
        if (s == null) {
            return defaultZone;
        }
        if (s.equals("Z")) {
            return DateUtil.UTC;
        }
        
        StringBuilder sb = new StringBuilder(9);
        sb.append("GMT");
        sb.append(s.charAt(0));
        
        String h = s.substring(1, 3);
        groupToInt(h, "offset-hours", 0, 23);
        sb.append(h);
        
        String m;
        int ln = s.length();
        if (ln > 3) {
            int startIdx = s.charAt(3) == ':' ? 4 : 3;
            m = s.substring(startIdx, startIdx + 2);
            groupToInt(m, "offset-minutes", 0, 59);
            sb.append(':');
            sb.append(m);
        }
        
        return TimeZone.getTimeZone(sb.toString());
    }

    private static int groupToMillisecond(String g)
            throws DateParseException {
        if (g == null) {
            return 0;
        }
        
        if (g.length() > 3) {
            g = g.substring(0, 3);
        }
        int i = groupToInt(g, "partial-seconds", 0, Integer.MAX_VALUE);
        return g.length() == 1 ? i * 100 : (g.length() == 2 ? i * 10 : i);
    }
    
    /**
     * Used internally by {@link DateUtil}; don't use its implementations for
     * anything else.
     */
    public interface DateToISO8601CalendarFactory {
        
        /**
         * Returns a {@link GregorianCalendar} with the desired time zone and
         * time and US locale. The returned calendar is used as read-only.
         * It must be guaranteed that within a thread the instance returned last time
         * is not in use anymore when this method is called again.
         */
        GregorianCalendar get(TimeZone tz, Date date);
        
    }

    /**
     * Used internally by {@link DateUtil}; don't use its implementations for anything else.
     */
    public interface CalendarFieldsToDateConverter {

        /**
         * Calculates the {@link Date} from the specified calendar fields.
         */
        Date calculate(int era, int year, int month, int day, int hours, int minutes, int secs, int millisecs,
                boolean addOneDay,
                TimeZone tz);

    }

    /**
     * Non-thread-safe factory that hard-references a calendar internally.
     */
    public static final class TrivialDateToISO8601CalendarFactory
            implements DateToISO8601CalendarFactory {
        
        private GregorianCalendar calendar;
        private TimeZone lastlySetTimeZone;
    
        public GregorianCalendar get(TimeZone tz, Date date) {
            if (calendar == null) {
                calendar = new GregorianCalendar(tz, Locale.US);
                calendar.setGregorianChange(new Date(Long.MIN_VALUE));  // never use Julian calendar
            } else {
                // At least on Java 6, calendar.getTimeZone is slow due to a bug, so we need lastlySetTimeZone.
                if (lastlySetTimeZone != tz) {  // Deliberately `!=` instead of `!<...>.equals()`  
                    calendar.setTimeZone(tz);
                    lastlySetTimeZone = tz;
                }
            }
            calendar.setTime(date);
            return calendar;
        }
        
    }

    /**
     * Non-thread-safe implementation that hard-references a calendar internally.
     */
    public static final class TrivialCalendarFieldsToDateConverter
            implements CalendarFieldsToDateConverter {

        private GregorianCalendar calendar;
        private TimeZone lastlySetTimeZone;

        public Date calculate(int era, int year, int month, int day, int hours, int minutes, int secs, int millisecs,
                boolean addOneDay, TimeZone tz) {
            if (calendar == null) {
                calendar = new GregorianCalendar(tz, Locale.US);
                calendar.setLenient(false);
                calendar.setGregorianChange(new Date(Long.MIN_VALUE));  // never use Julian calendar
            } else {
                // At least on Java 6, calendar.getTimeZone is slow due to a bug, so we need lastlySetTimeZone.
                if (lastlySetTimeZone != tz) {  // Deliberately `!=` instead of `!<...>.equals()`  
                    calendar.setTimeZone(tz);
                    lastlySetTimeZone = tz;
                }
            }

            calendar.set(Calendar.ERA, era);
            calendar.set(Calendar.YEAR, year);
            calendar.set(Calendar.MONTH, month);
            calendar.set(Calendar.DAY_OF_MONTH, day);
            calendar.set(Calendar.HOUR_OF_DAY, hours);
            calendar.set(Calendar.MINUTE, minutes);
            calendar.set(Calendar.SECOND, secs);
            calendar.set(Calendar.MILLISECOND, millisecs);
            if (addOneDay) {
                calendar.add(Calendar.DAY_OF_MONTH, 1);
            }
            
            return calendar.getTime();
        }

    }
    
    public static final class DateParseException extends ParseException {
        
        public DateParseException(String message) {
            super(message, 0);
        }
        
    }
        
}