/*
    *  Copyright 2001-2005 Stephen Colebourne
    *
    *  Licensed 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.joda.time.format;
  
  import java.io.IOException;
  import java.io.Writer;
  import java.util.Locale;
  
  import org.joda.time.MutablePeriod;
  import org.joda.time.Period;
  import org.joda.time.PeriodType;
  import org.joda.time.ReadWritablePeriod;
  import org.joda.time.ReadablePeriod;
  
  /**
   * Controls the printing and parsing of a time period to and from a string.
   * <p>
   * This class is the main API for printing and parsing used by most applications.
   * Instances of this class are created via one of three factory classes:
   * <ul>
   * <li>{@link PeriodFormat} - formats by pattern and style</li>
   * <li>{@link ISOPeriodFormat} - ISO8601 formats</li>
   * <li>{@link PeriodFormatterBuilder} - complex formats created via method calls</li>
   * </ul>
   * <p>
   * An instance of this class holds a reference internally to one printer and
   * one parser. It is possible that one of these may be null, in which case the
   * formatter cannot print/parse. This can be checked via the {@link #isPrinter()}
   * and {@link #isParser()} methods.
   * <p>
   * The underlying printer/parser can be altered to behave exactly as required
   * by using a decorator modifier:
   * <ul>
   * <li>{@link #withLocale(Locale)} - returns a new formatter that uses the specified locale</li>
   * </ul>
   * This returns a new formatter (instances of this class are immutable).
   * <p>
   * The main methods of the class are the <code>printXxx</code> and
   * <code>parseXxx</code> methods. These are used as follows:
   * <pre>
   * // print using the default locale
   * String periodStr = formatter.print(period);
   * // print using the French locale
   * String periodStr = formatter.withLocale(Locale.FRENCH).print(period);
   * 
   * // parse using the French locale
   * Period date = formatter.withLocale(Locale.FRENCH).parsePeriod(str);
   * </pre>
   *
   * @author Brian S O'Neill
   * @author Stephen Colebourne
   * @since 1.0
   */
  public class PeriodFormatter {
  
      /** The internal printer used to output the datetime. */
      private final PeriodPrinter iPrinter;
      /** The internal parser used to output the datetime. */
      private final PeriodParser iParser;
      /** The locale to use for printing and parsing. */
      private final Locale iLocale;
      /** The period type used in parsing. */
      private final PeriodType iParseType;
  
      /**
       * Creates a new formatter, however you will normally use the factory
       * or the builder.
       * 
       * @param printer  the internal printer, null if cannot print
       * @param parser  the internal parser, null if cannot parse
       */
      public PeriodFormatter(
              PeriodPrinter printer, PeriodParser parser) {
          super();
          iPrinter = printer;
          iParser = parser;
          iLocale = null;
          iParseType = null;
      }
  
      /**
       * Constructor.
       * 
       * @param printer  the internal printer, null if cannot print
       * @param parser  the internal parser, null if cannot parse
       * @param locale  the locale to use
      * @param type  the parse period type
      */
     private PeriodFormatter(
             PeriodPrinter printer, PeriodParser parser,
             Locale locale, PeriodType type) {
         super();
         iPrinter = printer;
         iParser = parser;
         iLocale = locale;
         iParseType = type;
     }
 
     //-----------------------------------------------------------------------
     /**
      * Is this formatter capable of printing.
      * 
      * @return true if this is a printer
      */
     public boolean isPrinter() {
         return (iPrinter != null);
     }
 
     /**
      * Gets the internal printer object that performs the real printing work.
      * 
      * @return the internal printer
      */
     public PeriodPrinter getPrinter() {
         return iPrinter;
     }
 
     /**
      * Is this formatter capable of parsing.
      * 
      * @return true if this is a parser
      */
     public boolean isParser() {
         return (iParser != null);
     }
 
     /**
      * Gets the internal parser object that performs the real parsing work.
      * 
      * @return the internal parser
      */
     public PeriodParser getParser() {
         return iParser;
     }
 
     //-----------------------------------------------------------------------
     /**
      * Returns a new formatter with a different locale that will be used
      * for printing and parsing.
      * <p>
      * A PeriodFormatter is immutable, so a new instance is returned,
      * and the original is unaltered and still usable.
      * 
      * @param locale  the locale to use
      * @return the new formatter
      */
     public PeriodFormatter withLocale(Locale locale) {
         if (locale == getLocale() || (locale != null && locale.equals(getLocale()))) {
             return this;
         }
         return new PeriodFormatter(iPrinter, iParser, locale, iParseType);
     }
 
     /**
      * Gets the locale that will be used for printing and parsing.
      * 
      * @return the locale to use
      */
     public Locale getLocale() {
         return iLocale;
     }
 
     //-----------------------------------------------------------------------
     /**
      * Returns a new formatter with a different PeriodType for parsing.
      * <p>
      * A PeriodFormatter is immutable, so a new instance is returned,
      * and the original is unaltered and still usable.
      * 
      * @param type  the type to use in parsing
      * @return the new formatter
      */
     public PeriodFormatter withParseType(PeriodType type) {
         if (type == iParseType) {
             return this;
         }
         return new PeriodFormatter(iPrinter, iParser, iLocale, type);
     }
 
     /**
      * Gets the PeriodType that will be used for parsing.
      * 
      * @return the parse type to use
      */
     public PeriodType getParseType() {
         return iParseType;
     }
 
     //-----------------------------------------------------------------------
     /**
      * Prints a ReadablePeriod to a StringBuffer.
      *
      * @param buf  the formatted period is appended to this buffer
      * @param period  the period to format, not null
      */
     public void printTo(StringBuffer buf, ReadablePeriod period) {
         checkPrinter();
         checkPeriod(period);
         
         getPrinter().printTo(buf, period, iLocale);
     }
 
     /**
      * Prints a ReadablePeriod to a Writer.
      *
      * @param out  the formatted period is written out
      * @param period  the period to format, not null
      */
     public void printTo(Writer out, ReadablePeriod period) throws IOException {
         checkPrinter();
         checkPeriod(period);
         
         getPrinter().printTo(out, period, iLocale);
     }
 
     /**
      * Prints a ReadablePeriod to a new String.
      *
      * @param period  the period to format, not null
      * @return the printed result
      */
     public String print(ReadablePeriod period) {
         checkPrinter();
         checkPeriod(period);
         
         PeriodPrinter printer = getPrinter();
         StringBuffer buf = new StringBuffer(printer.calculatePrintedLength(period, iLocale));
         printer.printTo(buf, period, iLocale);
         return buf.toString();
     }
 
     /**
      * Checks whether printing is supported.
      * 
      * @throws UnsupportedOperationException if printing is not supported
      */
     private void checkPrinter() {
         if (iPrinter == null) {
             throw new UnsupportedOperationException("Printing not supported");
         }
     }
 
     /**
      * Checks whether the period is non-null.
      * 
      * @throws IllegalArgumentException if the period is null
      */
     private void checkPeriod(ReadablePeriod period) {
         if (period == null) {
             throw new IllegalArgumentException("Period must not be null");
         }
     }
 
     //-----------------------------------------------------------------------
     /**
      * Parses a period from the given text, at the given position, saving the
      * result into the fields of the given ReadWritablePeriod. If the parse
      * succeeds, the return value is the new text position. Note that the parse
      * may succeed without fully reading the text.
      * <p>
      * The parse type of the formatter is not used by this method.
      * <p>
      * If it fails, the return value is negative, but the period may still be
      * modified. To determine the position where the parse failed, apply the
      * one's complement operator (~) on the return value.
      *
      * @param period  a period that will be modified
      * @param text  text to parse
      * @param position position to start parsing from
      * @return new position, if negative, parse failed. Apply complement
      * operator (~) to get position of failure
      * @throws IllegalArgumentException if any field is out of range
      */
     public int parseInto(ReadWritablePeriod period, String text, int position) {
         checkParser();
         checkPeriod(period);
         
         return getParser().parseInto(period, text, position, iLocale);
     }
 
     /**
      * Parses a period from the given text, returning a new Period.
      *
      * @param text  text to parse
      * @return parsed value in a Period object
      * @throws IllegalArgumentException if any field is out of range
      */
     public Period parsePeriod(String text) {
         checkParser();
         
         return parseMutablePeriod(text).toPeriod();
     }
 
     /**
      * Parses a period from the given text, returning a new MutablePeriod.
      *
      * @param text  text to parse
      * @return parsed value in a MutablePeriod object
      * @throws IllegalArgumentException if any field is out of range
      */
     public MutablePeriod parseMutablePeriod(String text) {
         checkParser();
         
         MutablePeriod period = new MutablePeriod(0, iParseType);
         int newPos = getParser().parseInto(period, text, 0, iLocale);
         if (newPos >= 0) {
             if (newPos >= text.length()) {
                 return period;
             }
         } else {
             newPos = ~newPos;
         }
         throw new IllegalArgumentException(FormatUtils.createErrorMessage(text, newPos));
     }
 
     /**
      * Checks whether parsing is supported.
      * 
      * @throws UnsupportedOperationException if parsing is not supported
      */
     private void checkParser() {
         if (iParser == null) {
             throw new UnsupportedOperationException("Parsing not supported");
         }
     }
 
 }