From 2ea6bf36a6edc152818b7bf0fc337449393b497d Mon Sep 17 00:00:00 2001
From: Martin Goik <goik@hdm-stuttgart.de>
Date: Tue, 23 May 2023 18:48:32 +0200
Subject: [PATCH] Minor enhancements
---
Doc/Sd1/Arrays/arrays.xml | 146 ++++++++++++++++++++------------------
1 file changed, 77 insertions(+), 69 deletions(-)
diff --git a/Doc/Sd1/Arrays/arrays.xml b/Doc/Sd1/Arrays/arrays.xml
index b8bc74612..dea7baf82 100644
--- a/Doc/Sd1/Arrays/arrays.xml
+++ b/Doc/Sd1/Arrays/arrays.xml
@@ -911,7 +911,8 @@ Mark|frequency
</listitem>
<listitem>
- <para>Holding either primitive types or object references.</para>
+ <para>Holding either primitive types or object references (Class
+ instance or array).</para>
</listitem>
<listitem>
@@ -919,8 +920,8 @@ Mark|frequency
</listitem>
<listitem>
- <para>Arbitrary dimensions: One-dimensional, two-dimensional
- etc.</para>
+ <para>Arbitrary array dimensions by virtue of nesting:
+ One-dimensional, two-dimensional etc.</para>
</listitem>
</itemizedlist>
</figure>
@@ -942,19 +943,18 @@ Mark|frequency
<figure xml:id="sd1_array_fig_arrayTypeDefinition">
<title>Array instances are special!</title>
- <programlisting language="java">...println(" String: " + "".getClass().getName());
-...println(" int[]: " + new int[]{}.getClass().getName());
-...println(" double[]: " + new double[]{}.getClass().getName());
-...println(" boolean[]: " + new boolean[]{}.getClass().getName());
-...println(" String[]: " + new String[]{}.getClass().getName());
-...println("StringBuffer[]: " + new StringBuffer[]{}.getClass().getName());</programlisting>
+ <programlisting language="java">...println(" String: " + "".getClass().getTypeName());
+...println(" int[]: " + new int[]{}.getClass().getTypeName());
+...println(" double[]: " + new double[]{}.getClass().getTypeName());
+...println(" boolean[]: " + new boolean[]{}.getClass().getTypeName());
+...println("StringBuffer[]: " + new StringBuffer[]{}.getClass().getTypeName());</programlisting>
<screen> String: java.lang.String
- int[]: [I
- double[]: [D
- boolean[]: [Z
- String[]: [Ljava.lang.String;
-StringBuffer[]: [Ljava.lang.StringBuffer;</screen>
+ int[]: int[]
+ double[]: double[]
+ boolean[]: boolean[]
+ String[]: java.lang.String[]
+StringBuffer[]: java.lang.StringBuffer[]</screen>
</figure>
<figure xml:id="sd1_array_fig_arrayDefMemoryDetails">
@@ -980,7 +980,7 @@ StringBuffer[]: [Ljava.lang.StringBuffer;</screen>
* Initialize array with default value.
*
* @param values Array to be initialized.
- * @param common Common value for all array elements.
+ * @param common New value for all array elements.
*/
static void fill(final int[] values, final int common) {
for (int i = 0; i < values.length; i++) {
@@ -1231,14 +1231,36 @@ sort|find(Mandyer): -4</screen>
<qandadiv>
<qandaentry>
<question>
- <para>Read the <xref linkend="glo_Javadoc"/> of <classname
- xlink:href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Arrays.html">Arrays</classname>.<methodname
- xlink:href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Arrays.html#binarySearch(java.lang.Object%5B%5D,java.lang.Object)">binarySearch(...)</methodname>and
- explain the three integer search result values in <xref
- linkend="sd1_array_fig_arraysBinarySearch"/>.</para>
-
- <para>In particular give a detailed account explaining the two
- negative values -3 and -4.</para>
+ <para>In <xref linkend="sd1_array_fig_arraysBinarySearch"/> the
+ result reads:</para>
+
+ <screen>sort|find(Mand): -3
+sort|find(Mandy): 2
+sort|find(Mandyer): -4</screen>
+
+ <orderedlist>
+ <listitem>
+ <para>What does the positive value 2 in return to <code
+ language="java">"Mandy"</code> indicate?</para>
+ </listitem>
+
+ <listitem>
+ <para>Why do we get negative values -3 and -4 for <code
+ language="java">"Mand"</code> and <code
+ language="java">"Mandyer"</code> respectively?</para>
+ </listitem>
+
+ <listitem>
+ <para>What is the exact meaning of -3 and -4 besides being
+ just negative?</para>
+ </listitem>
+ </orderedlist>
+
+ <tip>
+ <para>Read <classname
+ xlink:href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Arrays.html">Arrays</classname>.<methodname
+ xlink:href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Arrays.html#binarySearch(java.lang.Object%5B%5D,java.lang.Object)">binarySearch(...).</methodname></para>
+ </tip>
</question>
<answer>
@@ -1277,64 +1299,50 @@ sort|find(Mandyer): -4</screen>
</tr>
</informaltable>
- <para>A positive return value conveys:</para>
-
<orderedlist>
<listitem>
- <para>The value is present within the array.</para>
+ <para>A positive value indicates an exact match: The string
+ <code language="java">"Mandy"</code> does exist within the
+ array at index position 2.</para>
</listitem>
<listitem>
- <para>The return value is equal to the array element's
- index.</para>
+ <para>A negative value indicates a value not being found: Both
+ <code language="java">"Mand"</code> and <code
+ language="java">"Mandyer"</code> do not exist in the
+ array</para>
</listitem>
- </orderedlist>
- <para>Searching for <code language="java">"Mandy"</code> thus
- returns the index value 2 corresponding to the third array
- element.</para>
+ <listitem>
+ <para>The exact value of a negative integer being returned
+ defines the hypothetical insertion position keeping the
+ resulting array sorted. Regarding <code
+ language="java">"Mandyer"</code> the insertion index would be
+ 3 squeezing <code language="java">"Paul"</code> one step to
+ the right:</para>
- <para>Negative return values actually also provide two types of
- information:</para>
+ <programlisting language="none"> {"Aaron", "Eva", "Mandy", <emphasis
+ role="red">"Mandyer"</emphasis>, "Paul"}
+/* Index 0 1 2 3 4 /*
- <orderedlist>
- <listitem>
- <para>The value is not present in the given array.</para>
- </listitem>
+</programlisting>
- <listitem>
- <para>The position where the element would be inserted to
- become part of an ordered list.</para>
+ <para>The observed return value of -4 when searching for
+ <emphasis role="red">"Mandyer"</emphasis> thus corresponds to
+ insertion index 3. Hence we have the following rule:</para>
+
+ <para>Negate the return value and subsequently subtract
+ 1.</para>
+
+ <remark>Ratio: Subtracting 1 is being required for conveying
+ the «not in list» information under all circumstances.
+ Otherwise not finding and hypothetically inserting e.g. <code
+ language="java">"A"</code> at the list's beginning would
+ result in 0. This could not be disambiguated from an array
+ featuring an existing value<code language="java">"A"</code> at
+ its leftmost start position.</remark>
</listitem>
</orderedlist>
-
- <para>In the given example hypothetically inserting the string
- <code language="java"><emphasis
- role="red">"Mand"</emphasis></code> retaining a sorted list
- results in:</para>
-
- <programlisting language="none">{"Aaron", "Eva", <emphasis
- role="red">"Mand"</emphasis>, "Mandy", "Paul"}</programlisting>
-
- <para>This insertion point's index is 2 corresponding to the third
- array element. According to the <methodname
- xlink:href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Arrays.html#binarySearch(java.lang.Object%5B%5D,java.lang.Object)">binarySearch(...)</methodname>
- method's documentation this corresponds to a return value of -2 -
- 1 == -3.</para>
-
- <para>The observed return value of -4 when searching for <emphasis
- role="red">"Mandyer"</emphasis> corresponds to insertion index
- 3:</para>
-
- <programlisting language="none">{"Aaron", "Eva", "Mandy", <emphasis
- role="red">"Mandyer"</emphasis>, "Paul"}</programlisting>
-
- <remark>Subtracting -1 is being required for conveying the «not in
- list» information under all circumstances. Otherwise not finding
- and hypothetically inserting e.g. <code language="java">"A"</code>
- at the list's beginning would result in 0. This could not be
- disambiguated from an array featuring <code
- language="java">"A"</code> at its front position.</remark>
</answer>
</qandaentry>
</qandadiv>
--
GitLab