1 package com.sharkysoft.printf;
2
3 import java.util.ArrayList;
4 import java.util.List;
5
6 /***
7 * Syntactic sugar for variable argument lists.
8 *
9 * <p><b>Details:</b> <code>PrintfData</code> offers an alternative method for
10 * defining the data vector in Printf For Java. If you don't like the idea of
11 * wrapping primitive types in their object counterparts and referencing them in
12 * an <code>Object</code> array, then perhaps you'll like the syntactic sugar
13 * afforded by this helper class. <em>Use of this class is entirely
14 * optional.</em></p>
15 *
16 * <p>To build a printf data vector using this class, first instantiate an
17 * instance, and then chain together calls to its overloaded <code>add</code>
18 * method, furnishing the printf input data one element at a time. (Each
19 * <code>add</code> call returns the same instance of this class, to facilitate
20 * chaining.) After the last element has been added, the result can then be
21 * supplied directly to most {@link Printf} methods.</p>
22 *
23 * <blockquote class="example">
24 *
25 * <p><b>Example:</b> The two {@link Printf} in this code are equivalent:</p>
26 *
27 *<blockquote><pre>
28 *String format = "My dog %s is %d years old.";
29 *String name = "Spot";
30 *int age = 3;
31 *<i>// With Object array:</i>
32 *Printf.out(format, <b>new Object[]{name, new Integer(age)}</b>);
33 *<i>// With PrintfData:</i>
34 *Printf.out(format, <b>new PrintfData().add(name).add(age)</b>);
35 *</pre></blockquote>
36
37 * </blockquote>
38 *
39 * <p>In the first {@link Printf} call above, an <code>Object</code> array is
40 * explicitely created, and the primitive type is explicitely wrapped. In the
41 * second call, no <code>Object</code> array is created, and no primitive type
42 * is wrapped. <code>Printf</code> accepts the data vector returned by the last
43 * <code>add</code> call.</p>
44 *
45 * <p>Behind the scenes, <code>Printf</code> simply converts the
46 * <code>PrintfData</code> to an <code>Object[]</code>. Therefore, straight
47 * <code>Object</code> arrays are always more efficient. The choice is
48 * yours.</p>
49 *
50 * @since before 1998.02.19
51 * @version 1998.12.23
52 *
53 * @author Sharky
54 */
55 public class PrintfData
56 {
57
58 private final List mpList;
59
60 /***
61 * Initializes empty vector with undetermined length.
62 *
63 * <p><b>Details:</b> This constructor initializes an empty data vector. Use
64 * this constructor when the final length of the data vector is unknown at
65 * compile time.</p>
66 */
67 public PrintfData()
68 {
69 mpList = new ArrayList();
70 }
71
72 /***
73 * Initializes empty vector with final length.
74 *
75 * <p><b>Details:</b> This constructor initializes an empty data vector whose
76 * final length has already been determined. Use this constructor whenever
77 * possible to create more efficient code. If the predicted final length of
78 * this data vector ultimately differs from the value passed into this
79 * constructor, no harm is done.</p>
80 *
81 * @param inLength the estimated length
82 */
83 public PrintfData(int inLength)
84 {
85 mpList = new ArrayList(inLength);
86 }
87
88 /***
89 * Appends Object data.
90 *
91 * <p><b>Details:</b> Use this method to append any type of object, including
92 * <code>String</code>s, to this data vector. The argument will not be
93 * wrapped.</p>
94 *
95 * @param ipO the object
96 * @return this instance
97 */
98 public PrintfData add(Object ipO)
99 {
100 mpList.add(ipO);
101 return this;
102 }
103
104 /***
105 * Appends char data.
106 *
107 * <p><b>Details:</b> Use this method to append a <code>char</code> to this
108 * data vector. The argument will be wrapped in a <code>Character</code>.</p>
109 *
110 * @param icC the char
111 * @return this instance
112 */
113 public PrintfData add(char icC)
114 {
115 return add(new Character(icC));
116 }
117
118 /***
119 * Appends short data.
120 *
121 * <p><b>Details:</b> Use this method to append a <code>short</code> to this
122 * data vector. The argument will be wrapped in a <code>Short</code>.</p>
123 *
124 * @param iwS the short
125 * @return this instance
126 */
127 public PrintfData add(short iwS)
128 {
129 return add(new Short(iwS));
130 }
131
132 /***
133 * Appends int data.
134 *
135 * <p><b>Details:</b> Use this method to append an <code>int</code> to this
136 * data vector. The argument will be wrapped in a <code>Integer</code>.</p>
137 *
138 * @param inI the int
139 * @return this instance
140 */
141 public PrintfData add(int inI)
142 {
143 return add(new Integer(inI));
144 }
145
146 /***
147 * Appends long data.
148 *
149 * <p><b>Details:</b> Use this method to append a <code>long</code> to this
150 * data vector. The argument will be wrapped in a <code>Long</code>.</p>
151 *
152 * @param ilL the long
153 * @return this instance
154 */
155 public PrintfData add(long ilL)
156 {
157 return add(new Long(ilL));
158 }
159
160 /***
161 * Appends float data.
162 *
163 * <p><b>Details:</b> Use this method to append a <code>float</code> to this
164 * data vector. The argument will be wrapped in a <code>Float</code>.</p>
165 *
166 * @param ifF the float
167 * @return this instance
168 */
169 public PrintfData add(float ifF)
170 {
171 return add(new Float(ifF));
172 }
173
174 /***
175 * Appends double data.
176 *
177 * <p><b>Details:</b> Use this method to append a <code>double</code> to this
178 * data vector. The argument will be wrapped in a <code>Double</code>.</p>
179 *
180 * @param idD the double
181 * @return this instance
182 */
183 public PrintfData add(double idD)
184 {
185 return add(new Double(idD));
186 }
187
188 /***
189 * Appends byte data.
190 *
191 * <p><b>Details:</b> Use this method to append a <code>byte</code> to this
192 * data vector. The argument will be wrapped in a <code>Byte</code>.</p>
193 *
194 * @param ibB the byte
195 * @return this instance
196 */
197 public PrintfData add(final byte ibB)
198 {
199 return add(new Byte(ibB));
200 }
201
202 /***
203 * Appends boolean data.
204 *
205 * <p><b>Details:</b> Use this method to append a <code>boolean</code> to this
206 * data vector. The argument will be wrapped in a <code>Boolean</code>.</p>
207 *
208 * @param izB the boolean
209 * @return this instance
210 */
211 public PrintfData add(final boolean izB)
212 {
213 return add(new Boolean(izB));
214 }
215
216 /***
217 * Converts to Object array.
218 *
219 * <p><b>Details:</b> Although it is not necessary in most cases, this method
220 * can be used to convert this data vector into an <code>Object</code>
221 * array.</p>
222 *
223 * @return the Object array
224 */
225 public Object[] done()
226 {
227 return mpList.toArray();
228 }
229
230 };
231