Varargs format(...) exercise

Doc/Sd1/coreClasses.xml

@@ -9,6 +9,111 @@
          xmlns:db="http://docbook.org/ns/docbook">
   <title>Core Classes</title>
 
+  <section xml:id="sd1SectVarargsFormat">
+    <title>Reconsidering System.out.format().</title>
+
+    <qandaset defaultlabel="qanda" xml:id="sd1QandaVarargsFormat">
+      <qandadiv>
+        <qandaentry>
+          <question>
+            <para>This exercise aims at a better understanding of
+            <code>System.out.<link
+            xlink:href="https://docs.oracle.com/javase/8/docs/api/java/io/PrintStream.html#format-java.lang.String-java.lang.Object...-">format()</link></code>
+            already being used in <xref
+            linkend="sd1SectIntermediateMultiplication"/> and other exercises.
+            Consider the following snippet:</para>
+
+            <programlisting language="none">      int value = 33;
+      double secondValue = 114.317;
+      
+      System.out.format("Just a single integer %3d\n", value);
+      System.out.format("An integer %3d and a double value %6.2f\n", value, secondValue);</programlisting>
+
+            <para>Something seems to be odd here: The format() method is being
+            called with a different number of arguments. Actually we may call
+            it with an arbitrary number of one or more arguments. Answer the
+            following two questions:</para>
+
+            <orderedlist>
+              <listitem>
+                <para>How does this (syntactically) work (overloading)
+                ?</para>
+              </listitem>
+
+              <listitem>
+                <para>What is the role of the <quote>%...</quote> format
+                strings? </para>
+              </listitem>
+            </orderedlist>
+          </question>
+
+          <answer>
+            <orderedlist>
+              <listitem>
+                <para>The mechanism does not work not by overloading despite
+                the fact that a related <link
+                xlink:href="https://docs.oracle.com/javase/8/docs/api/java/io/PrintStream.html#format-java.util.Locale-java.lang.String-java.lang.Object...-">overloaded
+                method</link> providing a locale argument does indeed
+                exist.</para>
+
+                <para>According to <code>System.out.<methodname
+                xlink:href="https://docs.oracle.com/javase/8/docs/api/java/io/PrintStream.html#format-java.lang.String-java.lang.Object...-">format(...)</methodname></code>
+                the first argument must be of type <code
+                xlink:href="https://docs.oracle.com/javase/8/docs/api/java/lang/String.html">String</code>.
+                Additional arguments of arbitrary type may be added in
+                accordance with the <quote>%...</quote> <link
+                xlink:href="https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax">format
+                strings</link> inside the first argument. It uses the
+                <acronym>varargs</acronym> mechanism being described in the
+                <link
+                xlink:href="http://proquest.safaribooksonline.com/9780992133047/toc2_html_5#toc2">Java
+                classes section of chapter 4</link>.</para>
+              </listitem>
+
+              <listitem>
+                <para>There is a one to one correspondence between each %...
+                format string and a corresponding argument. Thus if the first
+                argument does contain n format strings we need another n
+                arguments of appropriate types to follow.</para>
+              </listitem>
+            </orderedlist>
+
+            <para>Consider the following snippet:</para>
+
+            <programlisting language="none">      final int v = 33;
+      final double d = 114.317;
+      final short color = 255;
+      
+      System.out.format("v=%d, d=%5.2f, color=%2x\n", v, d, color);</programlisting>
+
+            <para>This generates the following output:</para>
+
+            <programlisting language="none">v=33, d=114.32, color=ff</programlisting>
+
+            <para>We may modify our code to better reflect the one to one
+            correspondence between format strings and variables:</para>
+
+            <programlisting language="none">      System.out.format("v=%d, d=%5.2f, color=%2x\n", 
+                           v,    d,           color);</programlisting>
+
+            <caution>
+              <para>A failure in providing appropriate numbers of arguments
+              having appropriate types likely results in a runtime
+              exception:</para>
+
+              <programlisting language="none">      System.out.format("v=%d, d=%d, color=%2x\n", // Error: Using %s rather than %f
+                           v,    d,           color);</programlisting>
+
+              <programlisting language="none">v=33, d=Exception in thread "main" java.util.IllegalFormatConversionException: d != java.lang.Double
+	at java.util.Formatter$FormatSpecifier.failConversion(Formatter.java:4302)
+   ...</programlisting>
+            </caution>
+          </answer>
+        </qandaentry>
+      </qandadiv>
+    </qandaset>
+  </section>
+
   <section xml:id="sw1SectionCoreClassesUsingMath">
     <title>Using class <classname
     xlink:href="http://docs.oracle.com/javase/8/docs/api/java/lang/Math.html">Math</classname></title>
@@ -148,14 +253,6 @@ public class CircleAreaCalculator {
     </qandaset>
   </section>
 
-  <section xml:id="sd1VarargsFormat">
-    <title>Reconsidering System.out-format().</title>
-
-    <para>This exercise aims at a better understanding of ... already being
-    used in <xref linkend="sd1SectIntermediateMultiplication"/> and other
-    exercises.</para>
-  </section>
-
   <section xml:id="sw1StringDigitProduct">
     <title>Analyzing strings</title>