Merge pull request #143 from bowbahdoe/develop

bowbahdoe · web-flow · commit 07a04785e196 · 2025-09-19T16:38:36.000-04:00
Update
diff --git a/src/annotations/elements.md b/src/annotations/elements.md
@@ -63,4 +63,4 @@ class PersonInCharge {}
 }
 ```
 
-[^fulllist]: You can find the full list [here](https://docs.oracle.com/javase/specs/jls/se23/html/jls-9.html#jls-9.6). It is a short list.
+[^fulllist]: You can find the full list [here](https://docs.oracle.com/javase/specs/jls/se25/html/jls-9.html#jls-9.6). It is a short list.
diff --git a/src/annotations/override.md b/src/annotations/override.md
@@ -6,7 +6,7 @@ is an annotation.
 There's not much else to say besides "hey, thats what that was!" but I think its
 worth noting.
 
-```java
+```java,no_run
 interface Num {
     boolean odd();
 
diff --git a/src/annotations/target.md b/src/annotations/target.md
@@ -7,7 +7,7 @@ The first of these "meta-annotations" you are likely to use is `@Target`.
 By default an annotation can mark anything, but you can use `@Target` to
 restrict what can be marked.[^typeuse]
 
-```java
+```java,no_run
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
 
diff --git a/src/branching_logic/nested_ifs.md b/src/branching_logic/nested_ifs.md
@@ -17,7 +17,7 @@ if (age < 25) {
 When an `if` is inside another `if` we say that it is "nested".
 
 If you find yourself nesting more than a few `if`s that might be a sign that
-you should reach out for help.
+you should reach out for help[^or].
 
 ```java,no_run
 if (...) {
@@ -30,3 +30,5 @@ if (...) {
     }
 }
 ```
+
+[^or]: Or a sign that you should keep reading. There are things I will show you that can help you avoid this - like "methods."
diff --git a/src/characters/conversion_to_integers.md b/src/characters/conversion_to_integers.md
@@ -1,6 +1,6 @@
 # Conversion to Integers
 
-All `char`s have a matching numeric value. `'a'` is `97`, `'b'` is `98`,
+All `char`s have a matching numeric value[^ascii]. `'a'` is `97`, `'b'` is `98`,
 `'&'` is `38`, and so on.
 
 Same as assigning an `int` to a `double`, you can perform a widening conversion
@@ -30,4 +30,6 @@ IO.println(isLetter);
 This can be useful if you are stranded on Mars[^onmars] or
 if you want to see if a character is in some range.
 
-[^onmars]: https://www.youtube.com/watch?v=0xkP_FQUsuM
+[^ascii]: You can find some of these values in an "[ASCII Table](https://www.ascii-code.com/)."
+
+[^onmars]: [https://www.youtube.com/watch?v=0xkP_FQUsuM](https://www.youtube.com/watch?v=0xkP_FQUsuM)
diff --git a/src/class_extension/challenges.md b/src/class_extension/challenges.md
@@ -39,7 +39,7 @@ class Main {
 ## Challenge 2.
 
 Rewrite your `Tree` class from above to instead extend `AbstractList<Apple>`.
-You can find the documentation for `AbstractList` [here](https://docs.oracle.com/javase/8/docs/api/java/util/AbstractList.html).
+You can find the documentation for `AbstractList` [here](https://docs.oracle.com/javase/25/docs/api/java/util/AbstractList.html).
 
 ## Challenge 3.
 
diff --git a/src/conclusion/what_now.md b/src/conclusion/what_now.md
@@ -117,7 +117,7 @@ to in order to render websites.
 There are a lot of tools for this in Java. A lot a lot. I would recommend
 starting with the one that comes built-in: the `jdk.httpserver` module.
 
-[Docs for `jdk.httpserver` here](https://docs.oracle.com/en/java/javase/24/docs/api/jdk.httpserver/module-summary.html)
+[Docs for `jdk.httpserver` here](https://docs.oracle.com/en/java/javase/25/docs/api/jdk.httpserver/module-summary.html)
 
 Then you will need to learn about SQL databases and how to query from/insert into them from Java.
 
@@ -147,7 +147,7 @@ two paths.
 Path #1 is to learn Java Swing. This is an old crusty GUI framework that is kinda difficult to use
 but has the pro of coming with Java and being able to run on every potato in existence.
 
-[Docs for `java.desktop` (Swing) here](https://docs.oracle.com/en/java/javase/24/docs/api/java.desktop/module-summary.html)
+[Docs for `java.desktop` (Swing) here](https://docs.oracle.com/en/java/javase/25/docs/api/java.desktop/module-summary.html)
 
 Path #2 is the learn JavaFX. By all accounts JavaFX is better software than Swing, but it was cursed
 by coming out at a point in history where desktop apps were no longer big business to develop. It
diff --git a/src/documentation/challenges.md b/src/documentation/challenges.md
@@ -19,6 +19,6 @@ Fix these by documenting that code enough that `javadoc` no longer gives you war
 
 ## Challenge 3.
 
-Read the [documentation for java.util.StringJoiner](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/StringJoiner.html).
+Read the [documentation for java.util.StringJoiner](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/StringJoiner.html).
 
 If you can, alter one of your projects to use it.
diff --git a/src/documentation/javadoc.md b/src/documentation/javadoc.md
@@ -17,6 +17,6 @@ javadoc \
 This will produce a directory full of HTML files that contain all
 the documentation from the specified modules.
 
-This is what is used to make [the official Java documenation](https://docs.oracle.com/en/java/javase/24/docs/api/index.html) as well as at least part of the documentation for most Java libraries.
+This is what is used to make [the official Java documenation](https://docs.oracle.com/en/java/javase/25/docs/api/index.html) as well as at least part of the documentation for most Java libraries.
 
 [^theme]: As is a theme with command-line tools
diff --git a/src/floating_point_numbers/conversion_to_integers.md b/src/floating_point_numbers/conversion_to_integers.md
@@ -48,6 +48,21 @@ IO.println(z);
 ~}
 ```
 
+Negative numbers will also have their decimal part dropped. So numbers like `-7.2`, `-7.6`, and `-7.9` will 
+all be converted into `-7`.
+
+```java
+~void main() {
+int x = (int) -7.2;
+int y = (int) -7.6;
+int z = (int) -7.9;
+
+IO.println(x);
+IO.println(y);
+IO.println(z);
+~}
+```
+
 Any number that is too big to store in an `int` will be converted to the biggest possible `int`, 2<sup>31</sup> - 1.
 
 ```java
diff --git a/src/hash_maps/challenges.md b/src/hash_maps/challenges.md
@@ -90,7 +90,7 @@ class Main {
 ```
 
 If you feel like this is hard to do with just `.put` and `.get`, you can 
-check for [other methods on HashMap that can help you](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/HashMap.html).
+check for [other methods on HashMap that can help you](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/HashMap.html).
 
 ## Challenge 3.
 
diff --git a/src/loops_ii/comparison_to_while.md b/src/loops_ii/comparison_to_while.md
@@ -57,7 +57,7 @@ while (index < numbers.length) {
 Us humans, with our tiny monkey brains, can get very lost when things that are related to each other are separated
 by long distances.
 
-In this dimension, for loops are superior. All the bits of code that "control the loop" can be right at the top.
+In this dimension, `for` loops are superior. All the bits of code that "control the loop" can be right at the top.
 
 ```java
 ~void main() {
diff --git a/src/loops_iii/for_each_loops.md b/src/loops_iii/for_each_loops.md
@@ -35,4 +35,4 @@ for (Bread bread : breads) {
 ```
 
 
-[^enhanced]: You might see this referred to as an "enhanced for statement." [That is its name in the language spec](https://docs.oracle.com/javase/specs/jls/se23/html/jls-14.html#jls-14.14.2) but not the name most people will use.
+[^enhanced]: You might see this referred to as an "enhanced for statement." [That is its name in the language spec](https://docs.oracle.com/javase/specs/jls/se25/html/jls-14.html#jls-14.14.2) but not the name most people will use.
diff --git a/src/loops_iii/iterable_and_iterator.md b/src/loops_iii/iterable_and_iterator.md
@@ -3,7 +3,7 @@
 For things that are not arrays, a for-each loops
 are built on top of two interfaces: `java.lang.Iterable` and `java.lang.Iterator`.
 
-The [`Iterator`](https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/Iterator.html) interface defines two methods: `hasNext` and `next`[^remove]. Iterators let you box up the logic of
+The [`Iterator`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Iterator.html) interface defines two methods: `hasNext` and `next`[^remove]. Iterators let you box up the logic of
 how to loop over something.
 
 ```java,no_run
@@ -17,7 +17,7 @@ public interface Iterator<T> {
 }
 ```
 
-[`Iterable`](https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/Iterable.html) then
+[`Iterable`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Iterable.html) then
 just has one method which gives you an `Iterator`. 
 
 ```java,no_run
diff --git a/src/niche_numerics/byte.md b/src/niche_numerics/byte.md
@@ -53,6 +53,12 @@ IO.println(b);
 
 You will most often use the `byte` type when working with data as sequences of bytes, such as reading from and writing to binary files. Representing binary data as arrays of `byte` values is more memory-efficient than representing each individual byte as, say, an `int`.
 
+
+<!--
+You will most often want a `byte` when you are trying to save space in memory.
+You will most often use the `byte` type when working with data as sequences of bytes, such as reading from and writing to binary files. Representing binary data as arrays of `byte` values is more memory-efficient than representing each individual byte as, say, an `int`.
+-->
+
 ```java,no_run
 // This array of 4 bytes
 byte[] bytes = { 1, 2, 3, 4 };
diff --git a/src/packages/challenges.md b/src/packages/challenges.md
@@ -28,7 +28,7 @@ This will require marking the classes and many of the methods within `public`.
 
 ## Challenge 3.
 
-Read through [the list of packages that come with Java](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/module-summary.html). You don't need to understand everything you are looking at; just
+Read through [the list of packages that come with Java](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/module-summary.html). You don't need to understand everything you are looking at; just
 browse and try to find at least one class that interests you.
 
 Import that class and try to use it.
diff --git a/src/reflection/challenges.md b/src/reflection/challenges.md
@@ -12,7 +12,7 @@ as input and returns if the name of the underlying
 class for that `Object` starts with a vowel.
 
 You might need to consult the documentation
-for [Class](https://docs.oracle.com/en/java/javase/24/docs/api/index.html).
+for [Class](https://docs.oracle.com/en/java/javase/25/docs/api/index.html).
 
 ```java,editable
 class Apple {}
diff --git a/src/reflection/invoke_a_method.md b/src/reflection/invoke_a_method.md
@@ -37,7 +37,7 @@ class Tea {
 ```
 
 For static methods you do not need an instance of the class to invoke them.
-Instead, the first argument is ignored. You can pass `null`.
+Instead, the first argument is ignored. You can pass `null`[^strange].
 
 ```java
 import java.lang.reflect.InvocationTargetException;
@@ -65,4 +65,6 @@ class Apple {
         IO.println("You took " + times + " bite" + (times < 1 ? "." : "s."));
     }
 }
-```
+```
+
+[^strange]: I find this strange. It hurts my brain.
diff --git a/src/static_methods/math.md b/src/static_methods/math.md
@@ -17,4 +17,4 @@ an instance of a class to call them would be silly.
 The `Math` class that comes with Java has methods that work in this way. `Math.max(a, b)`
 is `static` and therefore usable everywhere you want the maximum of two numbers.[^more]
 
-[^more]: There are way more on there. [Take a look](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Math.html).
+[^more]: There are way more on there. [Take a look](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/Math.html).
diff --git a/src/streams/challenges.md b/src/streams/challenges.md
@@ -46,7 +46,7 @@ class Main {
 
 ## Challenge 3.
 
-Read the documentation on [`Collector`](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/stream/Collector.html) and [`Collectors`](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/stream/Collector.html).
+Read the documentation on [`Collector`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Collector.html) and [`Collectors`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Collector.html).
 
 Make an implementation of `Collector` that can collect elements into `MySpecialList`.
 
diff --git a/src/strings/common_escape_sequences.md b/src/strings/common_escape_sequences.md
@@ -25,7 +25,7 @@ you need to escape the first backslash.[^forwardslash]
 
 ```java
 ~void main() {
-// The first backslash needs to be escaped. ¯\_(ツ)_/¯
+// The backslash needs to be escaped. ¯\_(ツ)_/¯
 String shruggie = "¯\\_(ツ)_/¯";
 ~}
 ```
diff --git a/src/strings_ii/UPPERCASE.md b/src/strings_ii/UPPERCASE.md
@@ -12,4 +12,17 @@ void main() {
 }
 ```
 
-This does not change the original `String` in place. It just makes a new `String` with all upper-case letters.
+This does not change the original `String` in place. It just makes a new `String` with all upper-case letters.
+
+Much like with `.toLowerCase()` you can optionally provide a `Locale` to get consistent behavior
+no matter what language the system is set to.
+
+```java
+void main() {
+    String message = "Happy Valentines Day";
+
+    // Same as above, no matter what.
+    String upperCased = message.toUpperCase(Locale.US);
+    IO.println(upperCased);
+}
+```
diff --git a/src/strings_ii/lowercase.md b/src/strings_ii/lowercase.md
@@ -16,7 +16,7 @@ void main() {
 
 This does not change the original `String` in place. It just makes a new `String` with all lower-case letters.
 
-What about other languages? Many of them also have a distinction between uppercase and lowercase, and usually, `.toLowerCase()` does the right thing for them too:
+Many other languages also have a distinction between upper-case and lower-case and, usually, `.toLowerCase()` does the "right thing" for them.
 
 ```java
 ~void main() {
@@ -25,4 +25,18 @@ IO.println("ПРИВЕТ".toLowerCase()); // prints "привет"
 ~}
 ```
 
-However, in different languages, the mapping between uppercase and lowercase characters can differ. For example, in Turkish, the lowercase form of the letter `I` is `ı` without a dot. By default, Java uses the rules for the language of the operating system, so `"I".toLowerCase()` will return `"i"` on an English system and `"ı"` on a Turkish one.
+In different languages the mapping between upper-case and lower-case letters can differ. 
+
+For example, in Turkish the lower-case form of the letter `I` is `ı` and not `i`. 
+By default, Java uses the rules for the language of the computer it is running on.
+So `"I".toLowerCase()` will return `"i"` on an English system and `"ı"` on a Turkish one.
+
+To get behavior that is consistent regardless of the machine it is being run on
+you can pass use an explicit `Locale`.
+
+```java
+~void main() {
+IO.println("I".toLowerCase(Locale.US)); // i - on every computer
+IO.println("I".toLowerCase(Locale.forLanguageTag("tr-TR"))); // ı - on every computer
+~}
+```
diff --git a/src/the_terminal/commands.md b/src/the_terminal/commands.md
@@ -2,12 +2,14 @@
 
 The primary way you interact with a terminal is by running commands.
 
-You start with a blank prompt and write something like the following.
+You start with a blank prompt and write something like the following[^nottyped].
 
 ```bash
 $ echo Hello
 Hello
 ```
 
 The first word is the name of the program to run. In this case `echo`. Everything after
-that is an "argument" to the program.
+that is an "argument" to the program.
+
+[^nottyped] You don't actually type the `$`. That is illustrative. Your terminal will give you something like a `$` or a `>` as a "prompt."
diff --git a/src/the_terminal/creating_files.md b/src/the_terminal/creating_files.md
@@ -1,6 +1,6 @@
 # Creating Files
 
-To create a blank file you can use the `touch`[^no_clue] command.
+To create a blank file you can use the `touch`[^why] command.
 
 ```bash
 $ touch hello.txt
@@ -12,8 +12,10 @@ using a program called a "text editor."
 There are some text editors, like [`vim`](https://www.vim.org/), which run entirely
 inside the terminal.[^diehard]
 
-One of the more popular ones at time of writing is [Visual Studio Code](https://code.visualstudio.com/). If you weren't otherwise shown a different option, that is a decent default. Install it and then you can use it to create and edit files.
+At the start of this book I showed you [VSCodium](https://vscodium.com/). If you weren't otherwise shown a different option, that is a decent default. You can use it to create and edit files.
+
+[^why]: This is called `touch` because it will "touch" a file and update its "last updated timestamp" but change nothing else.
 
-[^no_clue]: I have no clue why this is called `touch`.
 [^diehard]: These have their die hard supporters. The lunatics.
+
 [^thisbook]: This book has been written inside Visual Studio Code.
diff --git a/src/time/date.md b/src/time/date.md
@@ -56,4 +56,4 @@ class Main {
 
 To be clear though, `Date` has problems. We aren't ready to explain all of them yet. Just treat `Date` as haunted, as in by ghosts, and use the `java.time` alternatives when you can.
 
-[^gmt]: You will notice that when we print out the date we get GMT. GMT is basically the same as UTC, though [the documentation for `Date`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Date.html) explains the difference.
+[^gmt]: You will notice that when we print out the date we get GMT. GMT is basically the same as UTC, though [the documentation for `Date`](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/Date.html) explains the difference.

Original file line number	Diff line number	Diff line change
`@@ -63,4 +63,4 @@ class PersonInCharge {}`
`63`	`63`	`}`
`64`	`64`	```
`65`	`65`
`66`		`-[^fulllist]: You can find the full list [here](https://docs.oracle.com/javase/specs/jls/se23/html/jls-9.html#jls-9.6). It is a short list.`
	`66`	`+[^fulllist]: You can find the full list [here](https://docs.oracle.com/javase/specs/jls/se25/html/jls-9.html#jls-9.6). It is a short list.`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ if (age < 25) {`
`17`	`17`	When an `if` is inside another `if` we say that it is "nested".
`18`	`18`
`19`	`19`	If you find yourself nesting more than a few `if`s that might be a sign that
`20`		`-you should reach out for help.`
	`20`	`+you should reach out for help[^or].`
`21`	`21`
`22`	`22`	```java,no_run
`23`	`23`	`if (...) {`
`@@ -30,3 +30,5 @@ if (...) {`
`30`	`30`	`}`
`31`	`31`	`}`
`32`	`32`	```
	`33`	`+`
	`34`	`+[^or]: Or a sign that you should keep reading. There are things I will show you that can help you avoid this - like "methods."`