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 ≥ 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 }