Add Java assignments to the repository

.gitignore: The build files, files left by editors like *~ and the PDF
documents for the assignments are to be ignored for the purposes of
version control.

README.rst: Rewrite, with one line description in Chinese.

java/alist.txt: List of assignments, sorted in the order of the list of
assignments, with the ones with completed documentation marked with `#`.

java/buildall: Script that will build all of the assignments into one
PDF file; to be rehauled for the final document.

code/*.java: The Java source code for the assignments.

dbld: Script that builds a PDF document for a single assignment.

index.typ: The list of assignments, subject to update for further
refinement and inclusion of yet more assignments.

jbld: Script that compiles code for a single Java assignment.

output/*.typ: Typst file containing the output (sessions) obtained from
running the individual Java assignments.

state.sql: Future alternative to `alist.txt`, under development.

template.typ: The Typst template used across all of assignment,
containing common code for the uniform styling, such as page border.

text/*.typ: Typst file documenting each Java assignment.

vendor/Java.sublime-syntax: Updated Sublime Text syntax file for Java,
used for newer syntax features, such as `var`, not yet available in
syntaxes shipped with Typst.

vendor/gr.tmTheme: A grayscale TextMate theme to be used for code in the
documents generated by Typst suitable for black and white printing.

wltd: Difference between the files in `code/` and `text/`, and `code/`
and `output`; need to be rewritten along with `state.sql`.

8 files changed, 304 insertions, 0 deletions

diff --git a/java/text/AddTwoNumbers.typ b/java/text/AddTwoNumbers.typ
new file mode 100644
index 0000000..0ef86fa
--- /dev/null
+++ b/java/text/AddTwoNumbers.typ
@@ -0,0 +1,44 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.575em)
+
+#assignment(5)[
+  Write a program to add two numbers by taking input from command line arguments, the `Scanner` class and the `BufferedReader` class.
+]
+
+#scos("AddTwoNumbers")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `java.lang.Double` class:
+  - `static double parseDouble(String)`: Try to parse the provided string as a `double` value.
+- `java.util.Scanner` class:
+  - `double nextDouble()`: Scan a `double` value from the the input stream.
+- `java.io.IOException` class represents the exception to be thrown when an error occurs while performing an I/O operation.
+- `java.io.BufferedReader` class provides for he efficient reading of characters, arrays, and lines from a character-input stream, buffering characters.
+  - Constructor `BufferedReader(Reader)`: Creates a buffering character-input stream for the provided reader stream.
+  - `String readLine()`: Returns a line of text from the input stream.
+- `java.io.InputStreamReader` class adapts a byte stream into character stream using a specific character set encoding.
+  - Constructor `InputStreamReader(InputStream)`: Creates a reader stream for characters from the provided input stream with the default character set encoding.
+- `java.util.InputMismatchException` is thrown by the methods of `Scanner` class when encountering invalid input.
+- `java.lang.NumberFormatExeption` is thrown by `parseDouble` method when the provided string does not constitute a valid `double` value.
+  
+#skind[Classes and methods implemented in the program]
+
+- The `Number` class objects represents a `double` value.
+  - Constructor `Number(double)`: Create a number object for the provided value.
+  - `double valueOf()`: Returns the underlying number.
+- The `ArithmeticOperations` class has methods implementing operations on `Number`s.
+  - `static Number add(Number, Number)`: Adds two `Number`s provided and returns the sum as a `Number`.
+- `AddTwoNumbers` class contains the operation of adding when the two numbers have been provided.
+  - `static void process(double, double)`: Performs addition by creating `Number` objects from the two provided `double` values.
+- The `AddTwoNumbersCLI` orchestrates a main program with:
+  - `public static void main(String[])`: Implements addition of two numbers by taking input from command line arguments.
+- The `AddTwoNumbersScan` orchestrates a main program with:
+  - `public static void main(String[])`: Implements addition of two numbers by taking input utilising `java.util.Scanner`.
+- The `AddTwoNumbersBuf` orchestrates a main program with:
+  - `public static void main(String[])`: Implements addition of two numbers by taking input using `java.io.BufferedReader`.
+#signature()
diff --git a/java/text/ArraySearch.typ b/java/text/ArraySearch.typ
new file mode 100644
index 0000000..19e4d7f
--- /dev/null
+++ b/java/text/ArraySearch.typ
@@ -0,0 +1,44 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.475em)
+
+#assignment(1)[
+  Write a menu-driven program to implement linear and binary search on an object of a custom array class.
+]
+
+#scos("ArraySearch")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `void java.util.Arrays.sort(double[])`: A static method facilitating in-place sorting of the provided array.
+- `java.util.Scanner` Class:
+  - Constructor `Scanner(java.io.InputStream)`: Creates a scanner object for scanning values from given input stream.
+  - Methods `int nextInt()`, `double nextDouble()`: Scan an integer or `double` value from the the input stream.
+- `java.util.function.BiFunction<T, U, V>` Interface:
+  - Objects implementing this interface represent functions taking two arguments of types `T` and `U`, returning a value of type `V`.
+  - Member method `V apply(T, U)` is used to invoke the underlying function.
+- `public static java.io.PrintStream System.out, System.err`: Represents the standard output and error streams.
+- `public void java.io.PrintStream.println(String)` and `public void java.io.PrintStream.print(String)`: Print text to the print stream, with or without newline at the end, respectively.
+
+#skind[Classes and methods implemented in the program]
+
+- The `Array` class acts as an array with essential methods:
+  - Constructor `Array()`: Invokes the `takeInput()` method.
+  - `void takeInput()`: Takes the array length and elements of the array from the user.
+  - `void display()`: Displays the array elements.
+  - `double get(int)`: Returns the value at the specified position.
+  - `void set(int, double)`: Sets the value at the specified position.
+  - `void sort()` Utilizes `Arrays.sort` for in-place sorting.
+  - `int size()`: Returns the size of the array.
+- The `ArrayOperations` class includes methods for performing searching operations, which takes the array and the value to search in it and returns the position of the element if it found in the array or `-1` instead.
+  - `static int linearSearch(Array, double)`: Performs linear search on the given `Array`.
+  - `static int binarySearch(Array, double)`: Conducts binary search; the array must be sorted before calling.
+- The `ArraySearch` orchestrates the main program with:
+  - `static void menu()`: Displays the menu.
+  - `static void performSearch(Scanner, Array, BiFunction<Array, Double, Integer>)`: Takes user input, performs the specified search, and displays the result.
+  - `public static void main(String[])`: Implements a menu-driven program for array searching.
+
+#signature()
diff --git a/java/text/ArraySort.typ b/java/text/ArraySort.typ
new file mode 100644
index 0000000..bc87735
--- /dev/null
+++ b/java/text/ArraySort.typ
@@ -0,0 +1,30 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+
+#assignment(2)[
+  Write a menu-driven program to implement bubble sort and selection sort on an object of a custom array class.
+]
+
+#scos("ArraySort")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `java.util.function.Consumer<T>` Interface:
+  - Objects implementing this interface represent functions taking an argument of type `T`, returning nothing, effectively consuming the provided value.
+  - Member method `void accept(T)` is used to invoke the underlying function.
+
+#skind[Classes and methods implemented in the program]
+
+- The `ArrayOperations` class includes methods for performing sorting operations in-place.
+  - `static void bubbleSort(Array)`: Performs bubble sort on the given `Array`.
+  - `static void selectionSort(Array)`: Performs selection sort on the given `Array`.
+- The `ArraySort` orchestrates the main program with:
+  - `static void menu()`: Displays the menu.
+  - `static void performSort(Scanner, Array, Consumer<Array>)`: Performs the specified sort, and displays the array before and after the sorting operation.
+  - `public static void main(String[])`: Implements a menu-driven program for array sorting.
+
+
+#signature()
diff --git a/java/text/ComplexCalculations.typ b/java/text/ComplexCalculations.typ
new file mode 100644
index 0000000..b8df211
--- /dev/null
+++ b/java/text/ComplexCalculations.typ
@@ -0,0 +1,31 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.5em)
+
+#assignment(6)[
+  Write a program to add two complex numbers using concept of methods returning objects and methods taking objects as parameters.
+]
+
+#scos("ComplexCalculations")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- The `double Math.abs(double)` method returns the absolute value of the given `double` value. 
+- `java.util.Scanner` class:
+  - `double nextDouble()`: Scan a `double` value from the the input stream.
+- `java.util.InputMismatchException` is thrown by the methods of `Scanner` class when encountering invalid input.
+
+#skind[Classes and methods implemented in the program]
+
+- The `Complex` class objects represents a a complex number.
+  - Constructor `Complex(double, double)`: Create a complex number object from the provided real and imaginary parts.
+  - `public String toString()` method returns the string representation of the complex number.
+- The `ComplexOperations` class 
+- The `CylinderCalculationsCLI` orchestrates a main program with:
+  - `public static void main(String[])`: Creates a cylinder object with its radius and height given as command-line arguments.
+- The `CylinderCalculationsScan` orchestrates a main program with:
+  - `public static void main(String[])`: Creates a cylinder object with its radius and height taken from user using `java.util.Scanner`.
+#signature()
diff --git a/java/text/CylinderCalculations.typ b/java/text/CylinderCalculations.typ
new file mode 100644
index 0000000..1ee8519
--- /dev/null
+++ b/java/text/CylinderCalculations.typ
@@ -0,0 +1,34 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.5em)
+
+#assignment(6)[
+  Write a program to find the surface area and volume of a cylinder using constructor by taking keyboard input or command-line input.
+]
+
+#scos("CylinderCalculations")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `java.lang.Double` class:
+  - `static double parseDouble(String)`: Try to parse the provided string as a `double` value.
+- `java.util.Scanner` class:
+  - `double nextDouble()`: Scan a `double` value from the the input stream.
+- `java.util.InputMismatchException` is thrown by the methods of `Scanner` class when encountering invalid input.
+- `java.lang.NumberFormatExeption` is thrown by `parseDouble` method when the provided string does not constitute a valid `double` value.
+  
+#skind[Classes and methods implemented in the program]
+
+- The `Cylinder` class objects represents a cylinder, a 3D geometric shape.
+  - Constructor `Cylinder(double, double)`: Create a cylinder object of the provided radius and height.
+  - `double volume()`: Returns the volume of the cylinder.
+  - `double surfaceArea()`: Returns the surface area of the cylinder.
+  - `void display()`: Display information about the cylinder.
+- The `CylinderCalculationsCLI` orchestrates a main program with:
+  - `public static void main(String[])`: Creates a cylinder object with its radius and height given as command-line arguments.
+- The `CylinderCalculationsScan` orchestrates a main program with:
+  - `public static void main(String[])`: Creates a cylinder object with its radius and height taken from user using `java.util.Scanner`.
+#signature()
diff --git a/java/text/MatrixOperations.typ b/java/text/MatrixOperations.typ
new file mode 100644
index 0000000..bcb6ce8
--- /dev/null
+++ b/java/text/MatrixOperations.typ
@@ -0,0 +1,47 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.6em)
+
+#assignment(4)[
+  Write a menu-driven program to perform addition, subtraction and multiplication operations on matrix objects.
+]
+
+#scos("MatrixOperations")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `java.util.Scanner` class:
+  - `float nextFloat()`: Scan a `float` value from the the input stream.
+- `java.util.function.BinaryOperator<T>` Interface:
+  - Objects of this interface represent operations upon two operands of the same type, producing a result of the same type as the operands.
+  - This is a subinterface of `BiFunction<T, T, T>` whose functional method is `T apply(T, T)`.
+- `java.lang.IllegalArgumentException` class represents the exception to be thrown when an illegal argument is provided to a function.
+- `java.util.ArrayList<T>` class provides a resizeable array from the Java Collections framework.
+  - `T get(int)`: Returns the value at the specified position in the list.
+  - `void add(T)`: Appends the specified element to the end of the list.
+- `java.util.InputMismatchException` is thrown by the methods of `Scanner` class when encountering invalid input.
+  
+#skind[Classes and methods implemented in the program]
+
+- The `Matrix` class provides sufficient interface to operate on a matrix of `float` values.
+  - Constructor `Matrix(int, int)`: Creates the underlying two dimensional array with the given matrix dimensions.
+  - `int rows(), int cols()`: Returns the number of rows and columns of the matrix, respectively.
+  - `float get(int, int)`: Returns the value at the specified position.
+  - `void set(int, int, float)`: Sets the value at the specified position.
+  - `void input(Scanner)`: Take the elements of the matrix from the user using the provided `Scanner` instance.
+  - `void display()`: Displays the matrix elements in a tabular format.
+- The `MatrixOperations` class implements the matrix operations as static methods.
+  - `static Matrix add(Matrix, Matrix) throws IllegalArgumentException`,
+  - `static Matrix subtract(Matrix, Matrix) throws IllegalArgumentException`,
+  - `static Matrix multiply(Matrix, Matrix) throws IllegalArgumentException`:
+    Perform the respective operations on the provided two matrices, taking care of the compatibility to the operations.
+- The `MatrixOperationsCLI` orchestrates the main program with:
+  - `static void menu()`: Displays the menu.
+  - `static Matrix takeMatrix(Scanner)`: Takes requisite user input to create a new matrix object.
+  - `static void displayMatrix(Scanner, ArrayList<Matrix>)`: Asks the user to choose the matrix to display among the available matrices and displays it.
+  - `static void operate(Scanner, ArrayList<Matrix>, String, BinaryOperator<Matrix>)`: Performs the specified operation on the matrices chosen by the user.
+  - `public static void main(String[])`: Implements a menu-driven program for the matrix operations.
+#signature()
diff --git a/java/text/StaticExecution.typ b/java/text/StaticExecution.typ
new file mode 100644
index 0000000..00b4ed0
--- /dev/null
+++ b/java/text/StaticExecution.typ
@@ -0,0 +1,29 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.75em)
+
+#assignment(10)[
+  Write a program to show that `static` blocks get executed before any object creation and implement the use of static variable to count the number of objects.
+]
+
+#scos("StaticExecution")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `java.util.Random` class:
+  Provides methods for generating pseudorandom numbers.
+  - `int nextInt(int)`: Returns a pseudorandom, uniformly-distributed, random number between 0 (inclusive) and provided value (exclusive).
+
+#skind[Classes and methods implemented in the program]
+
+- `StaticExample` class:
+  The class being used to demonstrate the order of execution of static block.
+  - `static int getObjectCount()`: Returns the object count of this class.
+  - Constructor `StaticExample()`: Shows a message first time it is called, i.e. when the first object is created. Increments the object count static variable.
+- `StaticExecution` class contains the main method of the program.
+  - `public static void main(String[])`: Creates a random number of objects of the `StaticExample` class and shows the number of objects created.
+
+#signature()
diff --git a/java/text/StringOperations.typ b/java/text/StringOperations.typ
new file mode 100644
index 0000000..210e4a9
--- /dev/null
+++ b/java/text/StringOperations.typ
@@ -0,0 +1,45 @@
+#import "/template.typ": *
+#show: A => apply(A)
+#set raw(lang: "java-new")
+#set par(leading: 0.55em)
+
+#assignment(3)[
+  Write a menu-driven program to create a class with a String member variable and perform basic string operations:
+  #box(align(left, [
+  - count the number of words,
+  - case-insensitively check whether the string is palindrome, and
+  - reverse the string.]))
+]
+
+#scos("StringOperations")
+
+=== Discussion
+
+#skind[Classes, interfaces and methods used from Java standard library]
+
+- `java.util.Scanner` Class:
+  - Method `String nextLine()`: Scan a line of text as a string from the the input stream.
+- `java.lang.String` Class:
+  - `int length()` method: Returns the length of the string.
+  - `char charAt(int)`: Returns the character in the string at the provided position.
+  - `char[] toCharArray()`: Returns an array of characters corresponding to the string.
+  - `static String copyValueOf(char[])`: Creates a new string from the provided character array.
+  
+#skind[Classes and methods implemented in the program]
+
+- `MyString` Class:
+  Provides the methods implementing the specified operations.
+  - `String str` is the underlying string object upon which the operations are to be performed.
+  - Constructor `MyString(String)`: Create an object of this class for the provided string.
+  - `String valueOf()`: Returns the underlying string object.
+  - `int countWords()`: Counts the words in the underlying string manually by  iterating over the characters in the string.
+  - `MyString reverse()`: Returns a new object of MyString with the underlying string reversed manually by iterating over characters.
+  - `MyString toLowerCase()`: Returns a new object of MyString with its characters manually converted to lower-case.
+  - `boolean equals(MyString)`: Check whether the underlying strings are equal by comparing the arrays of characters.
+  - `boolean isCaseInsensitivePalindrome()`: Checks whether the underlying string is a palindrome case-insensitively using the `reverse()`, `toLowerCase()` and `equals()` method.
+- The `StringOperations` orchestrates the main program with:
+  - `static void menu()`: Displays the menu.
+  - `public static void main(String[])`: Implements a menu-driven program for the specified string operations.
+
+
+#signature()