Chapter on Date

Author: bowbahdoe

src/SUMMARY.md

@@ -529,6 +529,7 @@ Make them do one. -->
   - [Time Zones](./time/time_zones.md)
   - [ZonedDateTime](./time/zoned_date_time.md)
   - [OffsetDateTime](./time/offset_date_time.md)
+  - [Date](./time/date.md)
 - [ArrayList](./array_list.md)
   - [Ubiquity](./array_list/ubiquity.md)
   - [Add an item](./array_list/add_an_item.md)

src/time/date.md

@@ -1 +1,59 @@
 # Date
+
+There is one class related to time that isn't much like the others: `java.util.Date`.
+
+Java did not originally come with the `java.time` classes. At first it just had `Date`.
+
+```java
+import java.util.Date;
+
+class Main {
+    void main() {
+        Date date = new Date();
+        System.out.println(date);
+    }
+}
+```
+
+`Date` is somewhat of a chimera between `Instant` and `ZonedDateTime`. It represents an instant in time but specifically in the UTC timezone.[^gmt]
+
+It is important to know about because a lot of code, including code that comes with Java, makes use of it.
+
+Whenever you see `Date` in the wild you should usually turn it into an `Instant` by
+calling `.toInstant()`.
+
+```java
+import java.time.Instant;
+import java.util.Date;
+
+class Main {
+    void main() {
+        Date date = new Date();
+        System.out.println(date);
+
+        Instant instant = date.toInstant();
+        System.out.println(instant);
+    }
+}
+```
+
+You can also construct a `Date` from an `Instant` using `Date.from`. This is useful if there is some code that wants a `Date` as an argument.
+
+```java
+import java.time.Instant;
+import java.util.Date;
+
+class Main {
+    void main() {
+        var instant = Instant.now();
+        System.out.println(instant);
+        
+        Date date = Date.from(instant);
+        System.out.println(date);
+    }
+}
+```
+
+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.

src/time/local_date.md

@@ -12,7 +12,7 @@ You can make a `LocalDate` with `LocalDate.of`.
 import java.time.LocalDate;
 
 void main() {
-    var jan10 = LocalDate.of(2024, 10, 1);
+    var jan10 = LocalDate.of(2024, 1, 10);
     System.out.println(jan10);
 }
 ```

src/time/local_date_time.md

@@ -14,7 +14,7 @@ import java.time.LocalDateTime;
 
 class Main {
     void main() {
-        var jan10 = LocalDate.of(2024, 10, 1);
+        var jan10 = LocalDate.of(2024, 1, 10);
         var tenTwentyFour = LocalTime.of(10, 24, 0);
         System.out.println(LocalDateTime.of(jan10, tenTwentyFour));
     }

src/time/zoned_date_time.md

@@ -15,7 +15,7 @@ import java.time.ZoneId;
 
 class Main {
     void main() {
-        var jan10 = LocalDate.of(2024, 10, 1);
+        var jan10 = LocalDate.of(2024, 1, 10);
         var tenTwentyFour = LocalTime.of(10, 24, 0);
         var est = ZoneId.of("US/Eastern");