1 /*
2 * Copyright 2001-2005 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
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, Locale locale);
63
64 //-----------------------------------------------------------------------
65 /**
66 * Prints a ReadablePeriod to a StringBuffer.
67 *
68 * @param buf the formatted period is appended to this buffer
69 * @param period the period to format
70 * @param locale the locale to use
71 */
72 void printTo(StringBuffer buf, ReadablePeriod period, Locale locale);
73
74 /**
75 * Prints a ReadablePeriod to a Writer.
76 *
77 * @param out the formatted period is written out
78 * @param period the period to format
79 * @param locale the locale to use
80 */
81 void printTo(Writer out, ReadablePeriod period, Locale locale) throws IOException;
82
83 }