Merge branch 'ratfactor:main' into testing

exercises/001_hello.zig

@@ -1,18 +1,18 @@
 //
-// Oh no! This program is supposed to print "Hello world!" but it needs
-// your help!
+// Oh no, this is supposed to print "Hello world!" but it needs
+// your help.
 //
+// Zig functions are private by default but the main() function
+// should be public.
 //
-// Zig functions are private by default but the main() function should
-// be public.
-//
-// A function is declared public with the "pub" statement like so:
+// A function is made public with the "pub" statement like so:
 //
 //     pub fn foo() void {
 //         ...
 //     }
 //
-// Try to fix the program and run `ziglings` to see if it works!
+// Perhaps knowing this well help solve the errors we're getting
+// with this little program?
 //
 const std = @import("std");
 

exercises/047_methods.zig

@@ -2,9 +2,9 @@
 // Help! Evil alien creatures have hidden eggs all over the Earth
 // and they're starting to hatch!
 //
-// Before you jump into battle, you'll need to know four things:
+// Before you jump into battle, you'll need to know three things:
 //
-// 1. You can attach functions to structs:
+// 1. You can attach functions to structs (and other "type definitions"):
 //
 //     const Foo = struct{
 //         pub fn hello() void {
@@ -12,31 +12,30 @@
 //         }
 //     };
 //
-// 2. A function that is a member of a struct is a "method" and is
-//    called with the "dot syntax" like so:
+// 2. A function that is a member of a struct is "namespaced" within
+//    that struct and is called by specifying the "namespace" and then
+//    using the "dot syntax":
 //
 //     Foo.hello();
 //
-// 3. The NEAT feature of methods is the special parameter named
-//    "self" that takes an instance of that type of struct:
+// 3. The NEAT feature of these functions is that if their first argument
+//    is an instance of the struct (or a pointer to one) then we can use
+//    the instance as the namespace instead of the type:
 //
 //     const Bar = struct{
-//         number: u32,
-//
-//         pub fn printMe(self: Bar) void {
-//             std.debug.print("{}\n", .{self.number});
-//         }
+//         pub fn a(self: Bar) void {}
+//         pub fn b(this: *Bar, other: u8) void {}
+//         pub fn c(bar: *const Bar) void {}
 //     };
 //
-//    (Actually, you can name the first parameter anything, but
-//    please follow convention and use "self".)
+//    var bar = Bar{};
+//    bar.a() // is equivalent to Bar.a(bar)
+//    bar.b(3) // is equivalent to Bar.b(&bar, 3)
+//    bar.c() // is equivalent to Bar.c(&bar)
 //
-// 4. Now when you call the method on an INSTANCE of that struct
-//    with the "dot syntax", the instance will be automatically
-//    passed as the "self" parameter:
-//
-//     var my_bar = Bar{ .number = 2000 };
-//     my_bar.printMe(); // prints "2000"
+//    Notice that the name of the parameter doesn't matter. Some use
+//    self, others use a lowercase version of the type name, but feel
+//    free to use whatever is most appropriate.
 //
 // Okay, you're armed.
 //

exercises/060_floats.zig

@@ -1,10 +1,11 @@
 //
 // Zig has support for IEEE-754 floating-point numbers in these
 // specific sizes: f16, f32, f64, f80, and f128. Floating point
-// literals may be written in scientific notation:
+// literals may be written in the same ways as integers but also
+// in scientific notation:
 //
-//     const a1: f32 = 1200.0;     // 1,200
-//     const a2: f32 = 1.2e+3;     // 1,200
+//     const a1: f32 = 1200;       //    1,200
+//     const a2: f32 = 1.2e+3;     //    1,200
 //     const b1: f32 = -500_000.0; // -500,000
 //     const b2: f32 = -5.0e+5;    // -500,000
 //
@@ -22,12 +23,14 @@
 //     const pi: f16 = 3.1415926535;   // rounds to 3.140625
 //     const av: f16 = 6.02214076e+23; // Avogadro's inf(inity)!
 //
-// A float literal has a decimal point. When performing math
-// operations with numeric literals, ensure the types match. Zig
-// does not perform unsafe type coercions behind your back:
+// When performing math operations with numeric literals, ensure
+// the types match. Zig does not perform unsafe type coercions
+// behind your back:
 //
-//     var foo: f16 = 13.5 * 5;   // ERROR!
-//     var foo: f16 = 13.5 * 5.0; // No problem, both are floats
+//    var foo: f16 = 5; // NO ERROR
+//
+//    var foo: u16 = 5; // A literal of a different type
+//    var bar: f16 = foo; // ERROR
 //
 // Please fix the two float problems with this program and
 // display the result as a whole number.

exercises/092_interfaces.zig

@@ -40,7 +40,7 @@
 //
 //   switch (thing) {
 //       .a => |a| special(a),
-//       inline else |t| => normal(t),
+//       inline else => |t| normal(t),
 //   }
 //
 // We can have special handling of some cases and then Zig

exercises/101_for5.zig

@@ -79,19 +79,19 @@ pub fn main() void {
 // all about:
 //
 // Let's say you've been tasked with grabbing three glass
-// marbles, three spoons, and three feathers from a bucket. But
-// you can't use your hands to grab them. Instead, you have a
-// special marble scoop, spoon magnet, and feather tongs to grab
+// marbles, three spoons, and three feathers from a magic bag.
+// But you can't use your hands to grab them. Instead, you must
+// use a marble scoop, spoon magnet, and feather tongs to grab
 // each type of object.
 //
-// Now, would you rather have:
+// Now, would you rather the magic bag:
 //
-// A. The items layered so you have to pick up one marble, then
-//    one spoon, then one feather?
+// A. Grouped the items in clusters so you have to pick up one
+//    marble, then one spoon, then one feather?
 //
 //    OR
 //
-// B. The items separated by type so you can pick up all of the
+// B. Grouped the items by type so you can pick up all of the
 //    marbles at once, then all the spoons, then all of the
 //    feathers?
 //
@@ -103,14 +103,16 @@ pub fn main() void {
 // efficient for modern CPUs.
 //
 // Decades of OOP practices have steered people towards grouping
-// different data types together into "objects" with the hope
-// that it would be friendlier to the human mind. But
-// data-oriented design groups data in a way that is more
-// efficient for the computer.
+// different data types together into mixed-type "objects" with
+// the intent that these are easier on the human mind.
+// Data-oriented design groups data by type in a way that is
+// easier on the computer.
 //
-// In Zig terminology, the difference in groupings is sometimes
-// known as "Array of Structs" (AoS) versus "Struct of Arrays"
-// (SoA).
+// With clever language design, maybe we can have both.
+//
+// In the Zig community, you may see the difference in groupings
+// presented with the terms "Array of Structs" (AoS) versus
+// "Struct of Arrays" (SoA).
 //
 // To envision these two designs in action, imagine an array of
 // RPG character structs, each containing three different data