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     */
016    package org.joda.time.format;
017    
018    import java.io.IOException;
019    import java.io.Writer;
020    import java.util.Locale;
021    
022    import 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     */
042    public 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    }