001/*
002 *  Copyright 2001-2005 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.time.format;
017
018import java.io.IOException;
019import java.io.Writer;
020import java.util.Locale;
021
022import org.joda.time.ReadablePeriod;
023
024/**
025 * Internal interface for printing textual representations of time periods.
026 * <p>
027 * Application users will rarely use this class directly. Instead, you
028 * will use one of the factory classes to create a {@link PeriodFormatter}.
029 * <p>
030 * The factory classes are:<br />
031 * - {@link PeriodFormatterBuilder}<br />
032 * - {@link PeriodFormat}<br />
033 * - {@link ISOPeriodFormat}<br />
034 *
035 * @author Brian S O'Neill
036 * @author Stephen Colebourne
037 * @since 1.0
038 * @see PeriodFormatter
039 * @see PeriodFormatterBuilder
040 * @see PeriodFormat
041 */
042public interface PeriodPrinter {
043
044    /**
045     * Returns the exact number of characters produced for the given period.
046     * 
047     * @param period  the period to use
048     * @param locale  the locale to use
049     * @return the estimated length
050     */
051    int calculatePrintedLength(ReadablePeriod period, Locale locale);
052
053    /**
054     * Returns the amount of fields from the given period that this printer
055     * will print.
056     * 
057     * @param period  the period to use
058     * @param stopAt stop counting at this value, enter a number &ge; 256 to count all
059     * @param locale  the locale to use
060     * @return amount of fields printed
061     */
062    int countFieldsToPrint(ReadablePeriod period, int stopAt, Locale locale);
063
064    //-----------------------------------------------------------------------
065    /**
066     * Prints a ReadablePeriod to a StringBuffer.
067     *
068     * @param buf  the formatted period is appended to this buffer
069     * @param period  the period to format
070     * @param locale  the locale to use
071     */
072    void printTo(StringBuffer buf, ReadablePeriod period, Locale locale);
073
074    /**
075     * Prints a ReadablePeriod to a Writer.
076     *
077     * @param out  the formatted period is written out
078     * @param period  the period to format
079     * @param locale  the locale to use
080     */
081    void printTo(Writer out, ReadablePeriod period, Locale locale) throws IOException;
082
083}