Methods + Classes (#23)

* Add start of if/else!

...

Co-Authored-By: Mitch Masia <[email protected]>

* loops

* ...

* Update SUMMARY.md

* loop challenges

* Update challenges.md

* ..

* Move iteration into loops

* More arrays

* Update access_individual_elements.md

* ...

* Close out arrays I sans challenges

* Rename features.py to features.java to placate folks

Update book.toml

Update book.toml

* Format

* Fix typo

* ..

* ...

* ...

* ...

* classes

* ...

* Update labeled_continue.md

* Update book.toml

* ...

---------

Co-authored-by: Mitch Masia <[email protected]>

book.toml

@@ -16,9 +16,10 @@ level = 0         # the depth to start folding
 
 [preprocessor.features]
 command = "python3 features.java"
+# Going to start writing the rest of the book
+# Assuming this is true
+toplevel_anonymous_class = true
 # Not ready
-toplevel_anonymous_class = false
-# Not ready
-simple_io = false
+simple_io = true
 # Turn on when Java 21 released
 java_21 = false

src/SUMMARY.md

@@ -132,44 +132,97 @@
     - [Printing the Contents of an Array](./arrays/printing_the_contents_of_an_array.md)
     - [Empty Array](./arrays/empty_array.md)
     - [Difference between Initializer and Literal](./arrays/difference_between_initializer_and_literal.md)
-    - [Challenges](./arrays/challenges)
+    - [Challenges](./arrays/challenges.md)
 
 # Control Flow II
 
-<!--
-- [For](./for.md)
-    - [Comparison to while]()
-    - [i](./for/i.md)
-    - [Relation to Arrays]()
-    - [var]()
-    - [final]()
-- [For Each]()
+- [Loops II](./loops_ii.md)
+    - [For](./loops_ii/for.md)
+    - [For Syntax](./loops_ii/for_syntax.md)
+    - [Counting Up and Down](./loops_ii/for_counting_up_and_down.md)
+    - [Iterate over a String](./loops_ii/iterate_over_a_string.md)
+    - [Iterate over an Array](./loops_ii/iterate_over_an_array.md)
+    - [Comparison to while](./loops_ii/comparison_to_while.md)
+    - [i](./loops_ii/i.md)
+    - [Break](./loops_ii/break.md)
+    - [Continue](./loops_ii/continue.md)
+    - [Delayed Assignment](./loops_ii/delayed_assignment.md)
+    - [Inferred Types](./loops_ii/inferred_types.md)
+    - [Empty Initializers](./loops_ii/empty_initializers.md)
+    - [Empty Expressions](./loops_ii/empty_expressions.md)
+    - [Empty Statements](./loops_ii/empty_statements.md)
+    - [Final Variables](./loops_ii/final_variables.md)
+    - [Labeled Break](./loops_ii/labeled_break.md)
+    - [Labeled Continue](./loops_ii/labeled_continue.md)
+    - [Drawing Right Triangles](./loops_ii/drawing_right_triangles.md)
+    - [Drawing Isosceles Triangles](./loops_ii/drawing_isosceles_triangles.md)
+    - [Challenges](./loops_ii/challenges.md)
+
+# Code Structure
+
+- [Methods](./methods.md)
+    - [Declaration](./methods/declaration.md)
+    - [Invocation](./methods/invocation.md)
+    - [Scope](./methods/scope.md)
+    - [Return](./methods/return.md)
+    - [Unreachable Statements](./methods/unreachable_statements.md)
+    - [main](./methods/main.md)
+- [Arguments](./arguments.md)
+    - [Declaration](./arguments/declaration.md)
+- [Return Values](./return_values.md)
+    - [void](./return_values/void.md)
+    - [Conversion](./return_values/conversion.md)
+    - [Pure Functions](./return_values/pure_functions.md)
+- [Classes](./classes.md)
+    - [Class Declaration](./classes/class_declaration.md)
+    - [Naming Classes](./classes/naming_classes.md)
+    - [Field Declaration](./classes/field_declaration.md)
+    - [Naming Fields](./classes/naming_fields.md)
+    - [new](./classes/new.md)
+    - [Zero Values](./classes/zero_values.md)
+    - [Aliasing](./classes/aliasing.md)
+    - [null](./classes/null.md)
+
+- [Constructors](./constructors.md)
+    - [this](./constructors/this.md)
+    - [The Default Constructor](./constructors/the_default_constructor.md)
+    - [Final Fields](./constructors/final_fields.md)
+    - [Multiple Constructors](./constructors/multiple_constructors.md)
 
-- [Iteration]()
-    - [Iterate over an array]()
+- [Instance Methods](./instance_methods.md)
+    - [Declaration](./instance_methods/declaration.md)
+    - [Invocation](./instance_methods/invocation.md)
+    - [this](./instance_methods/this.md)
+    - [Aliasing](./instance_methods/aliasing.md)
+    - [Derived Values](./instance_methods/derived_values.md)
+
+# Data Types III
 
 - [null](./null.md)
-- [Reference Types]()
-- [Primitive Types]()
-- [Populate array]()
+    - [Checking for null](./null/checking_for_null.md)
+    - [Field Access](./null/field_access.md)
+    - [Instance Methods](./null/instance_methods.md)
 
--->
+- [Arrays II]()
+    - [Default Values]()
+    - [Populate Array]()
+- [Boxed Primitives]()
+    - [Boolean]()
+    - [Character]()
+    - [Integer]()
+    - [Double]()
+
+- [Example: "Growable" Array]()
+
+# Code Structure II
+- [Documentation]()
+    - [Documentation Comments]()
+- [Testing]()
 
 # User Defined Types
 
-- [Classes](./classes.md)
-    - [Primitive Classes](./classes/primitive_classes.md)
-    - [Reference Classes](./classes/reference_classes.md)
-    - [null](./classes/null.md)
-    - [Class Declaration](./classes/class_declaration.md)
-    - [Naming](./classes/naming.md)
-- [Fields](./fields.md)
-    - [Default Values](./fields/default_values.md)
-- [Methods](./methods.md)
-    - [Arguments](./methods/arguments.md)
-    - [Return Values](./methods/return_values.md)
-    - [void](./methods/void.md)
-- [Constructors](./constructors.md)
+- [Primitive Classes](./classes/primitive_classes.md)
+- [Reference Classes](./classes/reference_classes.md)
 
 <!--
 Arrays

src/arguments.md

@@ -0,0 +1,21 @@
+# Arguments
+
+If methods always had to do the same thing each time they were run, they wouldn't be that useful.
+
+The way to customize what happens when a method is called is to have them take "arguments."
+Arguments let the caller of the method change what happens when a method runs.
+As part of a method declaration, you can include a comma separated list of "arguments"
+to that method. These arguments let the caller of the method change what happens when a method runs.
+
+```java
+void sayHello(String name) {
+    System.out.println("Hello " + name + "!");
+}
+
+void main() {
+    // Hello Joshua!
+    sayHello("Joshua");
+    // Hello Claire!
+    sayHello("Claire");
+}
+```

src/arguments/declaration.md

@@ -0,0 +1,13 @@
+# Declaration
+
+To declare a method take an argument, instead of putting `()` after the method name
+you need to put a comma separated list of argument declarations.
+
+Each argument declaration looks the same as a variable declaration and has both a type and a name.
+
+```java
+// This declares a single argument named "food" that
+// has a type of "String".
+void eat(String food) {
+    System.out.println("I ate " + food);
+}

src/arrays/challenges.md

@@ -0,0 +1 @@
+# Challenges

src/classes.md

@@ -1 +1,44 @@
 # Classes
+
+Methods can only have one return value. This means that if you wanted to make a method
+that returned two values, such as the location of buried treasure, you would have trouble.
+
+```java
+// Can only declare one "thing" that will be returned
+double getTreasureLocation() {
+    // Can't return two values.
+    return 43.8803, 103.4538
+}
+```
+
+This is the first[^many] use of classes. You can declare your own class which can hold multiple
+values and use that to smuggle them across a method return.
+
+```java
+class Location {
+    double latitude;
+    double longitude;
+}
+
+Location getTreasureLocation() {
+    Location treasure = new Location();
+    treasure.latitude = 43.8803;
+    treasure.longitude = 103.4538;
+    return treasure;
+}
+
+void main() {
+    Location treasure = getTreasureLocation();
+
+    System.out.println(
+        "The treasure is at " + 
+        treasure.latitude +
+        "N, " +
+        treasure.longitude +
+        "W."
+    );
+}
+```
+
+
+[^many]: of many

src/classes/aliasing.md

@@ -0,0 +1 @@
+# Aliasing

src/classes/declaration.md

@@ -0,0 +1,6 @@
+# Declaration
+
+To declare a class, you write the word `class` followed by a name for the class.
+
+You shoul
+

src/classes/field_declaration.md

@@ -0,0 +1 @@
+# Field Declaration

src/classes/naming_classes.md

@@ -0,0 +1 @@
+# Naming Classes

src/classes/naming_fields.md

@@ -0,0 +1,14 @@
+# Naming Fields
+
+Fields are generally named `camelCase`, the same as local variables.[^break]
+
+```java
+class Example {
+    int x;
+    String name;
+    int[] timesOfRacers;
+    String[] namesOfClowns;
+}
+```
+
+[^break]: If you break a social rule, something Bad happens.

src/classes/new.md

@@ -0,0 +1 @@
+# new

src/classes/zero_values.md

@@ -0,0 +1 @@
+# Zero Values

src/constructors/final_fields.md

@@ -0,0 +1 @@
+# Final Fields

src/constructors/multiple_constructors.md

@@ -0,0 +1 @@
+# Multiple Constructors

src/constructors/the_default_constructor.md

@@ -0,0 +1 @@
+# The Default Constructor

src/constructors/this.md

@@ -0,0 +1 @@
+# this

src/drawing_shapes/right_triangles.md

@@ -0,0 +1 @@
+# Right Triangles

src/instance

@@ -0,0 +1 @@
+# this

src/instance_methods.md

@@ -0,0 +1 @@
+# Instance Methods

src/instance_methods/aliasing.md

@@ -0,0 +1 @@
+# Aliasing

src/instance_methods/declaration.md

@@ -0,0 +1 @@
+# Declaration

src/instance_methods/derived_values.md

@@ -0,0 +1 @@
+# Derived Values

src/instance_methods/invocation.md

@@ -0,0 +1 @@
+# Invocation

src/instance_methods/this.md

@@ -0,0 +1 @@
+# this

src/integers/division.md

@@ -19,7 +19,7 @@ So `5 / 2` does not result in `2.5`, but instead just `2`.
 // 5 / 2 is not 2.5, but instead 2.
 int x = 5 / 2;
 // 13 / 3 is not 4.3333, but instead 4.
-int y = 13 / 2;
+int y = 13 / 3;
 
 System.out.println(x);
 System.out.println(y);

src/loops/do_while.md

@@ -1,6 +1,8 @@
 # Do
 
-One variation on a while loop is a "do-while loop."
+
+One variation on a `while` loop is a "do-while loop."
+
 
 ```java
 int x = 0;

src/loops_ii.md

@@ -0,0 +1,9 @@
+# Loops II
+
+`while` loops are enough to make any looping logic that you might want, but
+they aren't the only kind of loops you will see.
+
+There are tasks which would require a `while` loop, but are common enough that there are other kinds
+of loops that are shortcuts to writing them.
+
+

src/loops_ii/break.md

@@ -0,0 +1,21 @@
+# Break
+
+`break` works the same with `for` loops as it does with `while` loops.
+Any time you hit a line with `break` you will immediately exit the loop.
+
+```java
+for (int i = 0; i < 1000; i++) {
+    if (i == 5) {
+        break;
+    }
+    System.out.println(i);
+}
+System.out.println("Over");
+
+// 0
+// 1
+// 2
+// 3
+// 4
+// Over
+```