epubjs

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><title>Printf-Style Formatting</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="Printf-Style Formatting"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-10-SECT-5"/>Printf-Style Formatting</h1></div></div></div><p>A standard feature that Java adopted from the C language is <code class="literal">printf</code>-style string formatting. <code class="literal">printf</code>-style formatting utilizes special format strings embedded into text to tell the formatting engine where to place arguments and give detailed specification about conversions, layout, and alignment. The <code class="literal">printf</code> formatting methods also make use of variable-length argument lists, which makes working with them much easier. Here is a quick example of <code class="literal">printf</code>-formatted output:</p><a id="I_10_tt603"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code> <code class="s">"My name is %s and I am %d years old\n"</code><code class="o">,</code> <code class="n">name</code><code class="o">,</code> <code class="n">age</code> <code class="o">);</code></pre><p>The <code class="literal">printf</code> formatting draws its name from the C language <code class="literal">printf()</code> function, so if you’ve done any C programming, this will look familiar. Java has extended the concept, adding some additional type safety and convenience features. Although Java has had some text formatting capabilities in the past (we’ll discuss the <code class="literal">java.text</code> package and <code class="literal">MessageFormat</code> later), <code class="literal">printf</code> formatting was not really feasible until variable-length argument lists and autoboxing of primitive types were added in Java 5.0. (We mention this to explain why these similar APIs both exist in Java.)</p><div class="sect2" title="Formatter"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-10-SECT-5.1"/>Formatter</h2></div></div></div><p><a id="I_indexterm10_id728695" class="indexterm"/> <a id="I_indexterm10_id728704" class="indexterm"/>The primary new tool in our text formatting arsenal is the <a id="I_indexterm10_id728715" class="indexterm"/><code class="literal">java.util.Formatter</code> class and its <a id="I_indexterm10_id728726" class="indexterm"/><code class="literal">format()</code> method. Several convenience methods can hide the <code class="literal">Formatter</code> object from you and you may not need to create a <code class="literal">Formatter</code> directly. First, the static <code class="literal">String.format()</code> method can be used to format a <code class="literal">String</code> with arguments (like the C language <code class="literal">sprintf()</code> method):</p><a id="I_10_tt604"/><pre class="programlisting"> <code class="n">String</code> <code class="n">message</code> <code class="o">=</code> <code class="n">String</code><code class="o">.</code><code class="na">format</code><code class="o">(</code><code class="s">"My name is %s and I am %d years old."</code><code class="o">,</code> <code class="n">name</code><code class="o">,</code> <code class="n">age</code> <code class="o">);</code></pre><p>Next, the <a id="I_indexterm10_id728776" class="indexterm"/><code class="literal">java.io.PrintStream</code> and <a id="I_indexterm10_id728787" class="indexterm"/><code class="literal">java.io.PrintWriter</code> classes, which are used for writing text to streams, have their own <code class="literal">format()</code> method. We discuss streams in <a class="xref" href="ch12.html" title="Chapter 12. Input/Output Facilities">Chapter 12</a>, but this simply means that you can use this same <code class="literal">printf</code>-style formatting for writing strings to any kind of stream, whether it be to <code class="literal">System.out</code> standard console output, to a file, or to a network connection.</p><p>In addition to the <code class="literal">format()</code> method, <code class="literal">PrintStream</code> and <code class="literal">PrintWriter</code> also have a version of the format method that is actually called <code class="literal">printf().</code> The <code class="literal">printf()</code> method is identical to and, in fact, simply delegates to the <code class="literal">format()</code> method. It’s there solely as a shout-out to the C programmers and ex-C programmers in the audience.</p></div><div class="sect2" title="The Format String"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-10-SECT-5.2"/>The Format String</h2></div></div></div><p><a id="I_indexterm10_id728866" class="indexterm"/> <a id="idx10521" class="indexterm"/> <a id="I_indexterm10_id728883" class="indexterm"/> <a id="idx10541" class="indexterm"/> <a id="idx10583" class="indexterm"/>The syntax of the format string is compact and a bit cryptic at first, but not bad once you get used to it. The simplest format string is just a percent sign (%) followed by a conversion character. For example, the following text has two embedded format strings:</p><a id="I_10_tt605"/><pre class="programlisting"> <code class="s">"My name is %s and I am %d years old."</code></pre><p>The first conversion character is <code class="literal">s</code>, the most general format, which represents a string value; and the second is <code class="literal">d</code>, which represents an integer value. There are about a dozen basic conversion characters corresponding to different types and primitives and there are a couple of dozen more that are specifically used for formatting dates and times. We cover the basics here and return to date and time formatting in <a class="xref" href="ch11.html" title="Chapter 11. Core Utilities">Chapter 11</a>.</p><p>At first glance, some of the conversion characters may not seem to do much. For example, the <a id="I_indexterm10_id728952" class="indexterm"/><code class="literal">%s</code> general string conversion in our previous example would actually have handled the job of displaying the numeric age argument just as well as <a id="I_indexterm10_id728964" class="indexterm"/><code class="literal">%d</code>. However, these specialized conversion characters accomplish three things. First, they add a level of type safety. By specifying <code class="literal">%d</code>, we ensure that only an integer type is formatted at that location. If we make a mistake in the arguments, we get a runtime <a id="I_indexterm10_id728983" class="indexterm"/><code class="literal">IllegalFormatConversionException</code> instead of garbage in our string (and your IDE may flag it as well). Second, the format method is <code class="literal">Locale</code>-sensitive and capable of displaying numbers, percentages, dates, and times in many different languages just by specifying a <code class="literal">Locale</code> as an argument. By telling the <code class="literal">Formatter</code> the type of argument with type-specific conversion characters, <code class="literal">printf</code> can take into account language-specific localizations. Third, additional flags and fields can be used to govern layout with different meanings for different types of arguments. For example, with floating-point numbers, you can specify a precision in the format string.</p><p>The general layout of the embedded format string is as follows:</p><a id="I_10_tt606"/><pre class="programlisting"> <code class="o">%[</code><code class="n">argument_index$</code><code class="o">][</code><code class="n">flags</code><code class="o">][</code><code class="n">width</code><code class="o">][.</code><code class="na">precision</code><code class="o">]</code><code class="n">conversion_type</code></pre><p>Following the literal <code class="literal">%</code> are a number of optional items before the conversion type character. We’ll discuss these as they come up, but here’s the rundown. The <code class="literal">argument index</code> can be used to reorder or reuse individual arguments in the variable-length argument list by referring to them by number. The <a id="I_indexterm10_id729049" class="indexterm"/><code class="literal">flags</code> field holds one or more special flag characters governing the format. The <a id="I_indexterm10_id729060" class="indexterm"/><code class="literal">width</code> and <a id="I_indexterm10_id729071" class="indexterm"/><code class="literal">precision</code> fields control the size of the output for text and the number of digits displayed for floating-point numbers.<a id="I_indexterm10_id729082" class="indexterm"/><a id="I_indexterm10_id729089" class="indexterm"/><a id="I_indexterm10_id729096" class="indexterm"/></p></div><div class="sect2" title="String Conversions"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-10-SECT-5.3"/>String Conversions</h2></div></div></div><p><a id="idx10585" class="indexterm"/>The conversion characters <a id="I_indexterm10_id729126" class="indexterm"/><code class="literal">s</code> represents the general string conversion type. Ultimately, all of the conversion types produce a <code class="literal">String</code>. What we mean is that the general string conversion takes the easy route to turning its argument into a string. Normally, this simply means calling <code class="literal">toString()</code> on the object. Since all of the arguments in the variable argument list are autoboxed, they are all <code class="literal">Object</code>s. Any primitives are represented by the results of calling <code class="literal">toString()</code> on their wrapper classes, which generally return the value as you’d expect. If the argument is null, the result is the <code class="literal">String</code> “null.”</p><p>More interesting are objects that implement the <a id="I_indexterm10_id729172" class="indexterm"/><code class="literal">java.util.Formattable</code> interface. For these, the argument’s <a id="I_indexterm10_id729184" class="indexterm"/><code class="literal">formatTo()</code> method is invoked, passing it the flags, width, and precision information and allowing it to return the string to be used. In this way, objects can control their own <code class="literal">printf</code> string representation, just as an object can do so using <code class="literal">toString()</code>.</p><div class="sect3" title="Width, precision, and justification"><div class="titlepage"><div><div><h3 class="title"><a id="learnjava3-CHP-10-SECT-5.3.1"/>Width, precision, and justification</h3></div></div></div><p><a id="idx10544" class="indexterm"/> <a id="idx10568" class="indexterm"/>For simple text arguments, you can think of the width and precision as a minimum and maximum number of characters to be output. As we’ll see later, for floating-point numeric types, the precision changes meaning slightly and controls the number of digits displayed after the decimal point. We can see the effect on a simple string here:</p><a id="I_10_tt607"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code><code class="s">"String is '%5s'\n"</code><code class="o">,</code> <code class="s">"A"</code><code class="o">);</code> <code class="c1">// String is ' A'</code> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code><code class="s">"String is '%.5s'\n"</code><code class="o">,</code> <code class="s">"Happy Birthday!"</code><code class="o">);</code> <code class="c1">// String is 'Happy'</code></pre><p>In the first case, we specified a width of five characters, resulting in spaces being added to pad our argument. In the second example, we used the literal <a id="I_indexterm10_id729263" class="indexterm"/><a id="I_indexterm10_id729270" class="indexterm"/><code class="literal">.</code> followed by the precision value of <code class="literal">5</code> characters to limit the length of the string displayed, so our “Happy Birthday” string is truncated after the first five characters.</p><p>When our string was padded, it was right-justified (leading spaces added). You can control this with the flag character literal minus (<code class="literal">-</code>). Reversing our example:</p><a id="I_10_tt608"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code><code class="s">"String is '%-5s'\n"</code><code class="o">,</code> <code class="s">"A"</code><code class="o">);</code> <code class="c1">// String is 'A '</code></pre><p>And, of course, we can combine all three, specifying a justification flag and a minimum and maximum width. Here is an example that prints words of varying lengths in two columns:<a id="I_indexterm10_id729316" class="indexterm"/><a id="I_indexterm10_id729323" class="indexterm"/></p><a id="I_10_tt609"/><pre class="programlisting"> <code class="n">String</code> <code class="o">[]</code> <code class="n">words</code> <code class="o">=</code> <code class="k">new</code> <code class="n">String</code> <code class="o">[]</code> <code class="o">{</code> <code class="s">"abalone"</code><code class="o">,</code> <code class="s">"ape"</code><code class="o">,</code> <code class="s">"antidisestablishmentarianism"</code> <code class="o">};</code> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code> <code class="s">"%-10s %s\n"</code><code class="o">,</code> <code class="s">"Word"</code><code class="o">,</code> <code class="s">"Length"</code> <code class="o">);</code> <code class="k">for</code> <code class="o">(</code> <code class="n">String</code> <code class="n">word</code> <code class="o">:</code> <code class="n">words</code> <code class="o">)</code> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code> <code class="s">"%-10.10s %s\n"</code><code class="o">,</code> <code class="n">word</code><code class="o">,</code> <code class="n">word</code><code class="o">.</code><code class="na">length</code><code class="o">()</code> <code class="o">);</code> <code class="c1">// output</code> <code class="n">Word</code> <code class="n">Length</code> <code class="n">abalone</code> <code class="mi">7</code> <code class="n">ape</code> <code class="mi">3</code> <code class="n">antidisest</code> <code class="mi">28</code></pre></div><div class="sect3" title="Uppercase"><div class="titlepage"><div><div><h3 class="title"><a id="learnjava3-CHP-10-SECT-5.3.2"/>Uppercase</h3></div></div></div><p><a id="I_indexterm10_id729348" class="indexterm"/> <a id="I_indexterm10_id729359" class="indexterm"/>The <code class="literal">s</code> conversion’s big brother <a id="I_indexterm10_id729374" class="indexterm"/><code class="literal">S</code> indicates that the output of the conversion should be forced to uppercase. Several other primitive and numeric conversion characters follow this pattern, as we’ll see later. For example:</p><a id="I_10_tt610"/><pre class="programlisting"> <code class="n">String</code> <code class="n">word</code> <code class="o">=</code> <code class="s">"abalone"</code><code class="o">;</code> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">println</code><code class="o">(</code><code class="s">" The lucky word is: %S\n"</code><code class="o">,</code> <code class="n">word</code> <code class="o">);</code> <code class="c1">// The lucky word is: ABALONE</code></pre></div><div class="sect3" title="Numbered arguments"><div class="titlepage"><div><div><h3 class="title"><a id="learnjava3-CHP-10-SECT-5.3.3"/>Numbered arguments</h3></div></div></div><p><a id="idx10534" class="indexterm"/> <a id="idx10543" class="indexterm"/> <a id="idx10567" class="indexterm"/>You can refer to an arbitrary argument by number from a format string using the <a id="I_indexterm10_id729444" class="indexterm"/><code class="literal">%n$</code> notation. For example, the following code snippet uses the single argument three times:</p><a id="I_10_tt611"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">println</code><code class="o">(</code> <code class="s">"A %1$s is a %1$s is a %1$S..."</code><code class="o">,</code> <code class="s">"rose"</code> <code class="o">);</code> <code class="c1">// A rose is a rose is a ROSE...</code></pre><p>Numbered arguments are useful for two reasons. The first, shown here, is simply for reusing the same argument in different places and with different conversions. The usefulness of this becomes more apparent when we look at <code class="literal">Date</code> and <code class="literal">Time</code> formatting in <a class="xref" href="ch11.html" title="Chapter 11. Core Utilities">Chapter 11</a>, where we may refer to the same item half a dozen times to get individual fields. The second advantage is that numbered arguments give the message the flexibility to reorder the arguments. This is important when you’re using formatting strings to lay out a message for internationalization or customization purposes where convention may dictate a different ordering.<a id="I_indexterm10_id729491" class="indexterm"/><a id="I_indexterm10_id729498" class="indexterm"/><a id="I_indexterm10_id729505" class="indexterm"/><a id="I_indexterm10_id729512" class="indexterm"/></p><a id="I_10_tt612"/><pre class="programlisting"> <code class="n">log</code><code class="o">.</code><code class="na">format</code><code class="o">(</code><code class="s">"Error %d : %s\n"</code><code class="o">,</code> <code class="n">errNo</code><code class="o">,</code> <code class="n">errMsg</code> <code class="o">);</code> <code class="c1">// Error 42 : Low Power</code> <code class="n">log</code><code class="o">.</code><code class="na">format</code><code class="o">(</code><code class="s">"%2$s (Error %1$d)\n"</code><code class="o">,</code> <code class="n">errNo</code><code class="o">,</code> <code class="n">errMsg</code> <code class="o">);</code> <code class="c1">// Low Power (Error 42)</code></pre></div></div><div class="sect2" title="Primitive and Numeric Conversions"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-10-SECT-5.4"/>Primitive and Numeric Conversions</h2></div></div></div><p><a id="idx10538" class="indexterm"/> <a id="idx10542" class="indexterm"/> <a id="idx10584" class="indexterm"/> <a class="xref" href="ch10s05.html#learnjava3-CHP-10-TABLE-3" title="Table 10-3. Character and Boolean conversion characters">Table 10-3</a> shows character and Boolean conversion characters.</p><div class="table"><a id="learnjava3-CHP-10-TABLE-3"/><p class="title">Table 10-3. Character and Boolean conversion characters</p><div class="table-contents"><table summary="Character and Boolean conversion characters" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Conversion</p></th><th style="text-align: left"><p>Type</p></th><th style="text-align: left"><p>Description</p></th><th style="text-align: left"><p>Example output</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm10_id729646" class="indexterm"/> <code class="literal">c</code> </p></td><td style="text-align: left"><p>Character</p></td><td style="text-align: left"><p>Formats the result as a Unicode character</p></td><td style="text-align: left"><p> <code class="literal">a</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm10_id729685" class="indexterm"/> <code class="literal">b</code>, <a id="I_indexterm10_id729697" class="indexterm"/><code class="literal">B</code></p></td><td style="text-align: left"><p>Boolean</p></td><td style="text-align: left"><p>Formats result as Boolean</p></td><td style="text-align: left"><p> <code class="literal">true</code>, <code class="literal">FALSE</code></p></td></tr></tbody></table></div></div><p>The <code class="literal">c</code> conversion character produces a Unicode character:</p><a id="I_10_tt613"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code><code class="s">"The first letter is: %c\n"</code><code class="o">,</code> <code class="sc">'a'</code> <code class="o">);</code></pre><p>The <code class="literal">b</code> and <code class="literal">B</code> conversion characters output the Boolean value of their arguments. If the argument is null, the output is <code class="literal">false</code>. Strangely, if the argument is of a type other than Boolean, the output is <code class="literal">true</code>. <code class="literal">B</code> is identical to <code class="literal">b</code> except that it forces the output to uppercase.</p><a id="I_10_tt614"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code> <code class="s">"The door is open: %b\n"</code><code class="o">,</code> <code class="o">(</code> <code class="n">door</code><code class="o">.</code><code class="na">status</code><code class="o">()</code> <code class="o">==</code> <code class="n">OPEN</code> <code class="o">)</code> <code class="o">);</code></pre><p>As for <code class="literal">String</code> types, a width value can be specified on <code class="literal">c</code> and <code class="literal">b</code> conversions to pad the result to a minimum length. <a class="xref" href="ch10s05.html#learnjava3-CHP-10-TABLE-4" title="Table 10-4. Integer type conversion characters">Table 10-4</a> summarizes integer type conversion characters.</p><div class="table"><a id="learnjava3-CHP-10-TABLE-4"/><p class="title">Table 10-4. Integer type conversion characters</p><div class="table-contents"><table summary="Integer type conversion characters" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Conversion</p></th><th style="text-align: left"><p>Type</p></th><th style="text-align: left"><p>Description</p></th><th style="text-align: left"><p>Example output</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm10_id729888" class="indexterm"/> <code class="literal">d</code> </p></td><td style="text-align: left"><p>Integer</p></td><td style="text-align: left"><p>Formats the result as an integer.</p></td><td style="text-align: left"><p> <code class="literal">999</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm10_id729928" class="indexterm"/> <code class="literal">x</code>, <a id="I_indexterm10_id729939" class="indexterm"/><code class="literal">X</code></p></td><td style="text-align: left"><p>Integer</p></td><td style="text-align: left"><p>Formats result as hexadecimal.</p></td><td style="text-align: left"><p> <code class="literal">FF</code>, <code class="literal">0xCAFE</code></p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm10_id729981" class="indexterm"/> <code class="literal">o</code> </p></td><td style="text-align: left"><p>Integer</p></td><td style="text-align: left"><p>Formats result as octal integer.</p></td><td style="text-align: left"><p> <code class="literal">10</code>, <code class="literal">010</code></p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730026" class="indexterm"/> <code class="literal">h</code>, <a id="I_indexterm10_id730038" class="indexterm"/><code class="literal">H</code></p></td><td style="text-align: left" valign="top"><p>Integer or object</p></td><td style="text-align: left"><p>Formats object as hexadecimal number. If object is not an integer, format its <code class="literal">hashCode()</code> value or “null” for null value.</p></td><td style="text-align: left" valign="top"><p> <code class="literal">7a71e498</code> </p></td></tr></tbody></table></div></div><p>The <code class="literal">d</code>, <code class="literal">x</code>, and <code class="literal">o</code> conversion characters handle the integer type values <code class="literal">byte</code>, <code class="literal">short</code>, <code class="literal">int</code>, and <code class="literal">long</code>. (The <code class="literal">d</code> apparently stands for decimal, which makes little sense in this context.) The <code class="literal">h</code> conversion is an oddity probably intended for debugging. Several important flags give additional control over the formatting of these numeric types. See the section <a class="xref" href="ch10s05.html#learnjava3-CHP-10-SECT-5.5" title="Flags">Flags</a> for details.</p><p>A width value can be specified on these conversions to pad the result. Precision values are not allowed on integer conversions.</p><p><a class="xref" href="ch10s05.html#learnjava3-CHP-10-TABLE-5" title="Table 10-5. Floating-point type conversion characters">Table 10-5</a> lists floating-point type conversion characters.</p><div class="table"><a id="learnjava3-CHP-10-TABLE-5"/><p class="title">Table 10-5. Floating-point type conversion characters</p><div class="table-contents"><table summary="Floating-point type conversion characters" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Conversion</p></th><th style="text-align: left"><p>Type</p></th><th style="text-align: left"><p>Description</p></th><th style="text-align: left"><p>Example output</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm10_id730212" class="indexterm"/> <code class="literal">f</code> </p></td><td style="text-align: left"><p>Floating point</p></td><td style="text-align: left"><p>Formats result as decimal number.</p></td><td style="text-align: left"><p> <code class="literal">3.14</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm10_id730251" class="indexterm"/> <code class="literal">e</code>, <a id="I_indexterm10_id730263" class="indexterm"/><code class="literal">E</code></p></td><td style="text-align: left"><p>Floating point</p></td><td style="text-align: left"><p>Formats result in scientific notation.</p></td><td style="text-align: left"><p> <code class="literal">3.000000e+08</code> </p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730302" class="indexterm"/> <code class="literal">g</code>, <a id="I_indexterm10_id730314" class="indexterm"/><code class="literal">G</code></p></td><td style="text-align: left" valign="top"><p>Floating point</p></td><td style="text-align: left"><p>Formats result in either decimal or scientific notation depending on value and precision.</p></td><td style="text-align: left" valign="top"><p> <code class="literal">3.14</code>, <code class="literal">10.0e-15</code></p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730362" class="indexterm"/> <code class="literal">a</code>, <a id="I_indexterm10_id730374" class="indexterm"/><code class="literal">A</code></p></td><td style="text-align: left" valign="top"><p>Floating point</p></td><td style="text-align: left"><p>Formats result as hexadecimal floating-point number with significand and exponent.</p></td><td style="text-align: left" valign="top"><p> <code class="literal">0x1.fep7</code> </p></td></tr></tbody></table></div></div><p>The <code class="literal">f</code> conversion character is the primary floating-point conversion character. <code class="literal">e</code> and <code class="literal">g</code> conversions allow for values to be formatted in scientific notation. <code class="literal">a</code> complements the ability in Java to assign floating-point values using hexadecimal significand and exponent notation, allowing bit-for-bit floating-point values to be displayed without ambiguity.</p><p>As always, a width value may be used to pad results to a minimum length. The precision value of the conversion, as its name suggests, controls the number of digits displayed after the decimal point for floating-point values. The value is rounded as necessary. If no precision value is specified, it defaults to six digits:</p><a id="I_10_tt615"/><pre class="programlisting"> <code class="n">printf</code><code class="o">(</code><code class="s">"float is %f\n"</code><code class="o">,</code> <code class="mf">1.23456789</code><code class="o">);</code> <code class="c1">// float is 1.234568</code> <code class="n">printf</code><code class="o">(</code><code class="s">"float is %.3f\n"</code><code class="o">,</code> <code class="mf">1.23456789</code><code class="o">);</code> <code class="c1">// float is 1.235</code> <code class="n">printf</code><code class="o">(</code><code class="s">"float is %.1f\n"</code><code class="o">,</code> <code class="mf">1.23456789</code><code class="o">);</code> <code class="c1">// float is 1.2</code> <code class="n">printf</code><code class="o">(</code><code class="s">"float is %.0f\n"</code><code class="o">,</code> <code class="mf">1.23456789</code><code class="o">);</code> <code class="c1">// float is 1</code></pre><p>The <code class="literal">g</code> conversion character determines whether to use decimal or scientific notation. First, the value is rounded to the specified precision. If the result is less than 10<sup>−4</sup> (less than .0001) or if the result is greater than 10<sup>precision</sup> (10 to the power of the precision value), it is displayed in scientific notation. Otherwise, decimal notation is displayed.<a id="I_indexterm10_id730474" class="indexterm"/><a id="I_indexterm10_id730481" class="indexterm"/><a id="I_indexterm10_id730488" class="indexterm"/></p></div><div class="sect2" title="Flags"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-10-SECT-5.5"/>Flags</h2></div></div></div><p><a id="idx10520" class="indexterm"/> <a id="idx10540" class="indexterm"/> <a id="idx10582" class="indexterm"/> <a class="xref" href="ch10s05.html#learnjava3-CHP-10-TABLE-6" title="Table 10-6. Flags for format strings">Table 10-6</a> summarizes supported flags to use in format strings.</p><div class="table"><a id="learnjava3-CHP-10-TABLE-6"/><p class="title">Table 10-6. Flags for format strings</p><div class="table-contents"><table summary="Flags for format strings" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Flag</p></th><th style="text-align: left"><p>Arg types</p></th><th style="text-align: left"><p>Description</p></th><th style="text-align: left"><p>Example output</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm10_id730610" class="indexterm"/> <a id="I_indexterm10_id730617" class="indexterm"/> <code class="literal">-</code> </p></td><td style="text-align: left"><p>Any</p></td><td style="text-align: left"><p>Left-justifies result (pad space on the right)</p></td><td style="text-align: left"><p> <code class="literal">'foo '</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm10_id730656" class="indexterm"/> <a id="I_indexterm10_id730665" class="indexterm"/> <code class="literal">+</code> </p></td><td style="text-align: left"><p>Numeric</p></td><td style="text-align: left"><p>Prefixes a + sign on positive results</p></td><td style="text-align: left"><p> <code class="literal">+1</code> </p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730709" class="indexterm"/> <a id="I_indexterm10_id730715" class="indexterm"/> <code class="literal">' '</code> </p></td><td style="text-align: left" valign="top"><p>Numeric</p></td><td style="text-align: left"><p>Prefixes a space on positive results (aligning them with negative values)</p></td><td style="text-align: left" valign="top"><p> <code class="literal">' 1'</code> </p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730761" class="indexterm"/> <a id="I_indexterm10_id730768" class="indexterm"/> <code class="literal">0</code> </p></td><td style="text-align: left" valign="top"><p>Numeric</p></td><td style="text-align: left"><p>Pads number with leading zeros to accommodate width requirement</p></td><td style="text-align: left" valign="top"><p> <code class="literal">000001</code> </p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730813" class="indexterm"/> <a id="I_indexterm10_id730820" class="indexterm"/> <code class="literal">,</code> </p></td><td style="text-align: left" valign="top"><p>Numeric</p></td><td style="text-align: left"><p>Formats numbers with commas or other <code class="literal">Locale</code>-specific grouping characters</p></td><td style="text-align: left" valign="top"><p> <code class="literal">1,234,567</code> </p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730870" class="indexterm"/> <a id="I_indexterm10_id730877" class="indexterm"/> <code class="literal">(</code> </p></td><td style="text-align: left" valign="top"><p>Numeric</p></td><td style="text-align: left"><p>Encloses negative numbers in parentheses (a convention used to show credits)</p></td><td style="text-align: left" valign="top"><p> <code class="literal">(42.50)</code> </p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm10_id730922" class="indexterm"/> <code class="literal">#</code> </p></td><td style="text-align: left" valign="top"><p>x,X,o</p></td><td style="text-align: left"><p>Uses an alternate form for octal and hexadecimal output</p></td><td style="text-align: left" valign="top"><p> <code class="literal">0xCAFE</code>, <code class="literal">010</code></p></td></tr></tbody></table></div></div><p>As mentioned earlier, the <code class="literal">-</code> flag can be used to left-justify formatted output. The remaining flags affect the display of numeric types as described.</p><p>The <code class="literal">#</code> alternate form flag can be used to print octal and hexadecimal values with their standard prefixes—0x for hexadecimal or 0 for octal:<a id="I_indexterm10_id730982" class="indexterm"/><a id="I_indexterm10_id730989" class="indexterm"/><a id="I_indexterm10_id730996" class="indexterm"/></p><a id="I_10_tt616"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code><code class="s">"%1$X, %1$#X"</code><code class="o">,</code> <code class="mi">0</code><code class="n">xCAFE</code><code class="o">,</code> <code class="mi">0</code><code class="n">xCAFE</code> <code class="o">);</code> <code class="c1">// CAFE, 0xCAFE</code> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code><code class="s">"%1$o, %1$#o"</code><code class="o">,</code> <code class="mi">8</code><code class="o">,</code> <code class="mi">8</code> <code class="o">);</code> <code class="c1">// 10, 010</code></pre></div><div class="sect2" title="Miscellaneous"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-10-SECT-5.6"/>Miscellaneous</h2></div></div></div><p><a id="I_indexterm10_id731019" class="indexterm"/> <a class="xref" href="ch10s05.html#learnjava3-CHP-10-TABLE-7" title="Table 10-7. Miscellaneous formatting items">Table 10-7</a> lists the remaining formatting items.</p><div class="table"><a id="learnjava3-CHP-10-TABLE-7"/><p class="title">Table 10-7. Miscellaneous formatting items</p><div class="table-contents"><table summary="Miscellaneous formatting items" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Conversion</p></th><th style="text-align: left"><p>Description</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm10_id731078" class="indexterm"/> <a id="I_indexterm10_id731085" class="indexterm"/> <code class="literal">%</code> </p></td><td style="text-align: left"><p>Produces a literal % character (Unicode <code class="literal">\u0025</code>)</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm10_id731114" class="indexterm"/> <code class="literal">n</code> </p></td><td style="text-align: left"><p>Produces the platform-specific line separator (e.g., newline or carriage-return, newline)</p></td></tr></tbody></table></div></div></div></div></body></html>