01: /*
02: * Copyright 2001-2005 Stephen Colebourne
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS,
12: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13: * See the License for the specific language governing permissions and
14: * limitations under the License.
15: */
16: package org.joda.time.format;
17:
18: import java.io.IOException;
19: import java.io.Writer;
20: import java.util.Locale;
21:
22: import org.joda.time.ReadablePeriod;
23:
24: /**
25: * Internal interface for printing textual representations of time periods.
26: * <p>
27: * Application users will rarely use this class directly. Instead, you
28: * will use one of the factory classes to create a {@link PeriodFormatter}.
29: * <p>
30: * The factory classes are:<br />
31: * - {@link PeriodFormatterBuilder}<br />
32: * - {@link PeriodFormat}<br />
33: * - {@link ISOPeriodFormat}<br />
34: *
35: * @author Brian S O'Neill
36: * @author Stephen Colebourne
37: * @since 1.0
38: * @see PeriodFormatter
39: * @see PeriodFormatterBuilder
40: * @see PeriodFormat
41: */
42: public interface PeriodPrinter {
43:
44: /**
45: * Returns the exact number of characters produced for the given period.
46: *
47: * @param period the period to use
48: * @param locale the locale to use
49: * @return the estimated length
50: */
51: int calculatePrintedLength(ReadablePeriod period, Locale locale);
52:
53: /**
54: * Returns the amount of fields from the given period that this printer
55: * will print.
56: *
57: * @param period the period to use
58: * @param stopAt stop counting at this value, enter a number ≥ 256 to count all
59: * @param locale the locale to use
60: * @return amount of fields printed
61: */
62: int countFieldsToPrint(ReadablePeriod period, int stopAt,
63: Locale locale);
64:
65: //-----------------------------------------------------------------------
66: /**
67: * Prints a ReadablePeriod to a StringBuffer.
68: *
69: * @param buf the formatted period is appended to this buffer
70: * @param period the period to format
71: * @param locale the locale to use
72: */
73: void printTo(StringBuffer buf, ReadablePeriod period, Locale locale);
74:
75: /**
76: * Prints a ReadablePeriod to a Writer.
77: *
78: * @param out the formatted period is written out
79: * @param period the period to format
80: * @param locale the locale to use
81: */
82: void printTo(Writer out, ReadablePeriod period, Locale locale)
83: throws IOException;
84:
85: }
|