1 package com.sharkysoft.printf;
2
3 /***
4 * Signals malformed printf format.
5 *
6 * <p><b>Details:</b> Printf for Java throws a
7 * <code>PrintfTemplateException</code> whenever an attempt is made to parse an
8 * invalid format string or apply illegal arguments to a valid format string.
9 * This exception almost always indicates a bug in the
10 * client code.</p>
11 *
12 * <blockquote class="example">
13 *
14 * <p><b>Example 1:</b> Invalid format string:</p>
15 *
16 *<blockquote><pre>
17 *float tax_increase = SOME_VALUE;
18 *Printf.out
19 *( "taxes raised by %f% this year",
20 * new Object[] {new Float(tax_increase)}
21 *);
22 *</pre></blockquote>
23 *
24 * <p>When this code is executed, the format string parser interprets the
25 * second percent character as the beginning of a second format specifier.
26 * But since the following character, '<tt>t</tt>', does not correspond to a
27 * legal printf conversion type, a <code>PrintfTemplateException</code> will be
28 * thrown. (The correct format string should read "<tt>taxes raised by %f%%
29 * this year</tt>".)</p>
30 *
31 * </blockquote>
32 *
33 * <p>Even if a format string is syntactically correct, a
34 * <code>PrintfTemplateException</code> can still be thrown if variable widths and
35 * precisions are used and the supplied arguments are invalid.</p>
36 *
37 * <blockquote class="example">
38 *
39 * <p><b>Example 2:</b> Valid format string with invalid arguments:</p>
40 *
41 *<blockquote><pre>
42 *int dec_places = -3;
43 *Printf.out
44 *( "pi rounded to %d decimal places is %.*f",
45 * new PrintfData(3)
46 * .add(dec_places) // intended for "%d"
47 * .add(dec_places) // intended for "%.*f"
48 * .add(Math.PI)
49 *);
50 *</pre></blockquote>
51 *
52 * <p>This code throws a <code>PrintfTemplateException</code> because the variable precision
53 * specified by "%.*f" cannot be set to -3.</p>
54 *
55 * </blockquote>
56 *
57 * <p>For more information on printf formatting, see <code>Printf</code>.</p>
58 *
59 * @see Printf
60 *
61 * @author Sharky
62 */
63 public class PrintfTemplateException extends IllegalArgumentException
64 {
65
66 /***
67 * Initializes with detail message.
68 *
69 * <p><b>Details:</b> This constructor initializes the new exception with the
70 * supplied detail message.</p>
71 *
72 * @param isDetail the detail message
73 */
74 PrintfTemplateException(final String isDetail)
75 {
76 super(isDetail);
77 }
78
79 }
80