Merge branch 'develop' into patch-1

.github/workflows/linter.yaml

@@ -3,21 +3,20 @@ name: Linter
 on: [pull_request]
 
 jobs:
-  markdown-linter:
-    name: "Markdown Linter"
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
+#  markdown-linter:
+#    name: "Markdown Linter"
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: actions/checkout@v2
+#      - name: markdownlint-cli
+#        uses: nosborn/[email protected]
+#        with:
+#          files: .
+#          config_file: .markdownlint.yaml
 
-      - name: markdownlint-cli
-        uses: nosborn/[email protected]
-        with:
-          files: .
-          config_file: .markdownlint.yaml
-
-  markdown-link-check:
-    name: "Markdown Link Checker"
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: gaurav-nelson/[email protected]
+#  markdown-link-check:
+#    name: "Markdown Link Checker"
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: actions/checkout@v2
+#      - uses: gaurav-nelson/[email protected]

README.md

@@ -3,10 +3,48 @@
 [![codefactor](https://img.shields.io/codefactor/grade/github/together-java/modernjava)](https://www.codefactor.io/repository/github/together-java/modernjava)
 [![license](https://img.shields.io/github/license/Together-Java/ModernJava)](https://github.com/Together-Java/ModernJava/blob/master/LICENSE)
 
-Book teaching how to write modern and effective Java. It is maintained by the community, anyone can contribute.
+Greetings.
+
+This is a book intended to teach someone the Java language, from scratch. 
+
+You will find that the content makes heavy use of recently released and, for the moment,
+preview features. This is intentional as much of the topic ordering doesn't work
+without at least Java 21.
+
+Right now I have several key areas where I could use some help:
+
+* Writing Challenges. Most of the early sections have challenges students can do to test
+their understanding of the topics covered and for practice. I've shifted my focus away from
+these to make more progress on the main content of the book. Any assistance would be appreciated.
+* Theming. A lot of the chapters are...bland. Purely technical. I find that when I have the imagination to "theme" the subjects they become higher quality and more engaging overall. See
+an anime you liked recently and think you can make the math chapters use the characters from it?
+Give it a shot!
+* Fixing Mechanical Issues. I don't have an editor and I don't often proofread. If you find mechanical errors
+in my grammar or find issues with the way topics are ordered I would welcome fixes.
+
+Notably I do not want to open the floodgates for contributions on the main chapter content
+just yet. This has the downside of slower progress but the upside of a more coherent result.
+
+My primary goals with this are
+
+* Get the ordering of topics right. By this I mean that every topic covered should have had its pre-requitsites covered in the topics previous. While "lesson 1: Inheritance" is clearly wrong
+in this regard, some things are more subtle.
+* Be a template for other people. This is a book. Not everyone likes books, some like youtube videos, some like over priced udemy courses, some attend College, etc. Everyone has different learning paths. I hope this to be of use to anyone looking to make a more up to date Java
+curriculum and hope that the vague order of things (which I consider superior to the content
+produced with the Java of years' past) as carried through.
+* Write as if the newest Java wasn't new. Its obvious when a book was written before Java 8
+because it always has newer additions with "addendum: brand new stuff in Java 8." But 
+the order language features were introduced is hardly a good order to teach them. You have
+to pretend that Java 21 has always been *the* Java. Does it really make sense to show terrible
+C-style switch statements way before switch expressions?
+* Write as if the words Object Oriented Programming, Functional Programming, etc. didn't exist.
+While I understand that these all have definitions and are useful concepts to know about, introducing them early seems to lead to either dogma, rejection of said dogma, or some
+mix thereof. None of them are actually needed to understand the mechanics of and motivation
+behind what we would call "object oriented" or "functional" techniques. They certainly don't
+work as justification for adding getters and setters to every class.
 
 Feel free to join our [discord server](https://discord.gg/together-java-272761734820003841)
-if you have any questions, or require assistance with the project. :relaxed:
+if you have any questions, or require assistance with the project.
 
 ## Getting started
 

ferris.js

@@ -54,7 +54,16 @@ function createFerris(type, size) {
   a.setAttribute('target', '_blank')
 
   var toFileName = function (t) {
-    return '../img/' + t.attr + '.svg';
+    // return '../img/' + t.attr + '.svg';
+    if (t.attr == 'panics') {
+      return '../img/duke_armcross.webp'
+    }
+    else if (t.attr == 'does_not_compile') {
+      return '../img/duke_computer.webp'
+    }
+    else if (t.attr == 'not_desired_behavior') {
+      return '../img/duke_finger.webp'
+    }
   }
 
   var img = document.createElement('img')

src/SUMMARY.md

@@ -447,6 +447,8 @@
   - [Integer to a Base 16 String](./integers_ii/integer_to_a_base_16_string.md)
   - [Underscores in Integer Literals](./integers_ii/underscores_in_integer_literals.md)
 
+- [🚧 Construction Zone 🚧]()
+
 # Interactive Programs III
 
 - [Files](./files.md)
@@ -456,76 +458,119 @@
   - [Write to a File](./files/write_to_a_file.md)
   - [Read from a File](./files/read_from_a_file.md)
   - [Create a Folder](./files/creating_a_folder.md)
-  - [Delete a Folder](./files/creating_a_folder.md)
-  - [Delete a File](./files/creating_a_folder.md)
+  - [Delete a Folder](./files/deleting_a_folder.md)
+  - [Delete a File](./files/deleting_a_file.md)
 
 # Data Structures & Algorithms II
 
-- [Hash Maps]()
-- [Hash Sets]()
+- [Hash Maps](./hash_maps.md)
+  - [Filing Cabinets](./hash_maps/filing_cabinets.md)
+  - [Hash Functions](./hash_maps/hash_functions.md)
+  - [Function Range](./hash_maps/function_range.md)
+  - [Buckets](./hash_maps/buckets.md)
+  - [Hash Collision](./hash_maps/hash_collision.md)
+  - [Hash Distribution](./hash_maps/hash_distribution.md)
+  - [Growable Buckets](./hash_maps/growable_buckets.md)
+  - [Keys and Values](./hash_maps/keys_and_values.md)
+  - [Put Items](./hash_maps/put_items.md)
+  - [Get Items](./hash_maps/get_items.md)
+
 
 # Code Structure IV
 
+- [Object](./objects.md)
+  - [Subtypes](./objects/subtypes.md)
+  - [instanceof](./objects/instanceof.md)
+  - [toString](./objects/toString.md)
+  - [Override toString](./objects/override_toString.md)
+  - [@Override](./objects/override.md)
+  - [equals and hashCode](./objects/equals_and_hashCode.md)
+  - [Override equals and hashCode](./objects/override_equals_and_hashCode.md)
+  - [Variance and Casting](./objects/variance_and_casting.md)
+  - [Subclasses](./objects/subclasses.md)
+- [Generics](./generics.md)
+- [Interfaces](./interfaces.md)
 
-- [Interfaces]()
-  - [@Override]()
-- [Generics]()
-  - [Casting]()
-- [Object]()
-  - [instanceof]()
-  - [toString]()
-  - [equals]()
-  - [hashCode]()
-
-
-<!--
-
-
-
-# Data Types IV
-
-- [StringBuilder](./string_builder.md)
-- [Pattern]()
-
-
-# Concepts
+# Data Types V
 
-- [The Idiot Game](./the_idiot_game.md)
+<!-- Note: Put a joke about the "A train leaves chicago at ..." problems.
+Make them do one. -->
+- [Time](./time.md)
+  - [Instant](./time/instant.md)
+  - [Duration](./time/duration.md)
+  - [LocalDate](./time/local_date.md)
+  - [LocalTime](./time/local_time.md)
+  - [LocalDateTime](./time/local_date_time.md)
+  - [ZonedDateTime](./time/zoned_date_time.md)
+  - [OffsetDateTime](./time/offset_date_time.md)
+- [ArrayList](./array_list.md)
+  - [Ubiquity](./array_list/ubiquity.md)
+  - [Add an item](./array_list/add_an_item.md)
+  - [Size](./array_list/size.md)
+  - [Get an item](./array_list/get_an_item.md)
+  - [Loop over items](./array_list/loop_over_items.md)
+  - [Set an item](./array_list/set_an_item.md)
+  - [Remove an item](./array_list/remove_an_item.md)
+- [HashMap](./hash_map.md)
+- [Multi-Dimensional Arrays](./multi_dimensional_arrays.md)
 
-# Interactive Programs
+# Control Flow IV
+- [Loops III](./loops_iii.md)
+  - [For-each loops]()
+  - [Arrays]()
+  - [Iterable]()
+  - [ArrayList]()
+  - [Reasons to go back]() <!-- -->
+- [Switch III](./switch_iii.md)
+  - [Fallthrough](./switch_iii/fallthrough.md)
+  - [break](./switch_iii/break.md)
+  - [default](./switch_iii/default.md)
+  - [return](./switch_iii/return.md)
+  - [yield](./switch_iii/yield.md)
+- [Recursion](./recursion.md)
+  - [Disclaimer](./recursion/disclaimer.md)
+  - [Base Case](./recursion/base_case.md)
+  - [Comparison to Delegation](./recursion/comparison_to_delegation.md)
+  - [Comparison to Loops](./recursion/comparison_to_loops.md)
 
+# Code Structure V
+- [Class Extension](./class_extension.md)
+- [Abstract Classes](./abstract_classes.md)
 
-# The Computing Environment
+# Concepts II
 
+- [Encapsulation](./encapsulation.md)
+  - [Methods]()
+  - [Classes]()
+  - [Information Hiding]()
 
+# Building
 
+- [Compilation]()
+- [Compile Java Code]()
+  - [Compile a List of Files]()
+  - [Specify Where to Find Sources]()
+  - [Enable Debug Info]()
 
+# Data Types VI
+- [StringBuilder]()
+- [Pattern]()
 
-# Interactive Programs
+<!--
 
 
-- [Command Line Arguments]()
 
-# Code Structure IV
 
+# Concepts
 
-- [Import]()
-- [Packages]()
-  - [Public]()
-  - [Package Private]()
-  
+- [The Idiot Game](./the_idiot_game.md)
 
 # Data Types V
 
 - [Strings III]()
 - [StringBuilder](./stringbuilder.md)
 - [Regular Expressions]()
 
-# Code Structure V
-
-- [toString]()
-- [Interfaces]()
-  - [@Override]()
 
 
 # Code Structure V
@@ -535,6 +580,8 @@
   - [Safety]()
   - [Unsafe Casts]()
 
+[Informal Diagrams]
+
 # Data Types VI
 
 - [Integers II]()
@@ -546,7 +593,6 @@
   - [Add an item]()
   - [Get an item]()
   - [Set an item]()
-  - [Loop over Contents]()
 
 # Control Flow IV
 
@@ -564,10 +610,6 @@
 - [Sets]()
   - [HashSet]()
 
-# Interactive Programs II
-
-- [Files]()
-
 # Metaprogramming
 
 - [Reflection]()

src/abstract_classes.md

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

src/array_list.md

@@ -0,0 +1,15 @@
+# ArrayList
+
+Java comes with a generic growable array. It is called
+an `ArrayList`.
+
+```java
+import java.util.ArrayList;
+
+void main() {
+    ArrayList<String> names = new ArrayList<>();
+    names.add("John Wick");
+
+    System.out.println(names);
+}
+```

src/array_list/add_an_item.md

@@ -0,0 +1,23 @@
+# Add an item
+
+To add an item to an `ArrayList` you use the `.add`
+method.
+
+```java
+import java.util.ArrayList;
+
+void main() {
+    ArrayList<String> names = new ArrayList<>();
+    names.add("The Bowery King");
+    names.add("Caine");
+
+    System.out.println(names);
+}
+```
+
+The way this works is conceptually the 
+same as the growable array that we went over earlier.
+
+All you need to know though is that you can add 
+as many items as you will and the container will grow
+dynamically.

src/array_list/get_an_item.md

@@ -0,0 +1,31 @@
+# Get an item
+
+To get an item at a given index in an `ArrayList`
+you should use `.get`
+
+```java
+import java.util.ArrayList;
+
+void main() {
+    ArrayList<String> names = new ArrayList<>();
+    names.add("Winston Scott");
+
+    String name = names.get(0);
+    System.out.println(name);
+}
+```
+
+If the index you picked is greater than the number of elements in the `ArrayList`
+it will throw an `IndexOutOfBoundsException`
+
+```java,panics
+import java.util.ArrayList;
+
+void main() {
+    ArrayList<String> names = new ArrayList<>();
+    names.add("Killa Harkan");
+
+    String name = names.get(10);
+    System.out.println(name);
+}
+```