Merge pull request #22 from pedropark99/self

Add section to explain the difference between `self: User` and `self: *User`

Author: pedropark99

Chapters/02-debugging.qmd

@@ -69,8 +69,7 @@ you provide this format specifier inside a pair of curly braces. So, if you want
 your object using the string specifier (`s`), then, you can insert the text `{s}` in your template string.
 Here is a quick list of the most used format specifiers:
 
-- `d`: for printing integers.
-- `f`: for printing floating-point numbers.
+- `d`: for printing integers and floating-point numbers.
 - `c`: for printing characters.
 - `s`: for printing strings.
 - `p`: for printing memory addresses.

Chapters/03-structs.qmd

@@ -522,8 +522,7 @@ not be authorized to call this method directly in my code.
 
 
 
-
-## Anonymous struct literals {#sec-anonymous-struct-literals}
+### Anonymous struct literals {#sec-anonymous-struct-literals}
 
 You can declare a struct object as a literal value. When we do that, we normally specify the
 data type of this struct literal by writing it's data type just before the opening curly braces.
@@ -578,6 +577,231 @@ pub fn main() !void {
 ```
 
 
+
+### Struct declarations must be constant
+
+Types in Zig must be `const` or `comptime` (we are going to talk more about comptime at @sec-comptime).
+What this means is that you cannot create a new data type, and mark it as variable with the `var` keyword.
+So struct declarations are always constant. You cannot declare a new struct using the `var` keyword.
+It must be `const`.
+
+In the `Vec3` example below, this declaration is allowed because I'm using the `const` keyword
+to declare this new data type.
+
+```{zig}
+#| build_type: "lib"
+#| auto_main: false
+const Vec3 = struct {
+    x: f64,
+    y: f64,
+    z: f64,
+};
+```
+
+
+### The `self` method argument
+
+In every language that have OOP, when we declare a method of some class or struct, we
+usually declare this method as a function that have a `self` argument.
+This `self` argument is the reference to the object itself from which the method
+is being called from.
+
+Is not mandatory to use this `self` argument. But why would you not use this `self` argument?
+There is no reason to not use it. Because the only way to get access to the data stored in the
+data members of your struct is to access them through this `self` argument.
+If you don't need to use the data in the data members of your struct inside your method, then, you very likely don't need
+a method, you can just simply declare this logic as a simple function, outside of your
+struct declaration.
+
+
+Take the `Vec3` struct below. Inside this `Vec3` struct we declared a method named `distance()`.
+This method calculates the distance between two `Vec3` objects, by following the distance
+formula in euclidean space. Notice that this `distance()` method takes two `Vec3` objects
+as input, `self` and `other`.
+
+
+```{zig}
+#| build_type: "lib"
+#| auto_main: false
+const std = @import("std");
+const m = std.math;
+const Vec3 = struct {
+    x: f64,
+    y: f64,
+    z: f64,
+
+    pub fn distance(self: Vec3, other: Vec3) f64 {
+        const xd = m.pow(f64, self.x - other.x, 2.0);
+        const yd = m.pow(f64, self.y - other.y, 2.0);
+        const zd = m.pow(f64, self.z - other.z, 2.0);
+        return m.sqrt(xd + yd + zd);
+    }
+};
+```
+
+
+The `self` argument corresponds to the `Vec3` object from which this `distance()` method
+is being called from. While the `other` is a separate `Vec3` object that is given as input
+to this method. In the example below, the `self` argument corresponds to the object
+`v1`, because the `distance()` method is being called from the `v1` object,
+while the `other` argument corresponds to the object `v2`.
+
+
+```{zig}
+#| eval: false
+const v1 = Vec3 {
+    .x = 4.2, .y = 2.4, .z = 0.9
+};
+const v2 = Vec3 {
+    .x = 5.1, .y = 5.6, .z = 1.6
+};
+
+std.debug.print(
+    "Distance: {d}\n",
+    .{v1.distance(v2)}
+);
+```
+
+```
+Distance: 3.3970575502926055
+```
+
+
+
+### About the struct state
+
+Sometimes you don't need to care about the state of your struct object. Sometimes, you just need
+to instantiate and use the objects, without altering their state. You can notice that when you have methods
+inside this struct object that might use the values that are present the data members, but they
+do not alter the values in the data members of structs in anyway.
+
+The `Vec3` struct that we presented in the previous section is an example of that.
+This struct have a single method named `distance()`, and this method do use the values
+present in all three data members of the struct (`x`, `y` and `z`). But at the same time,
+this method do not change the values of these data members in any point.
+
+As a result of that, when we create `Vec3` objects we usually create them as
+constant objects, like the `v1` and `v2` objects presented in the previous
+code example. We can create them as variable objects with the `var` keyword,
+if we want to. But because the methods of this `Vec3` struct do not change
+the state of the objects in any point, is unnecessary to mark them
+as variable objects.
+
+But why? Why am I talkin about this here? Is because the `self` argument
+in the methods is affected depending on whether the
+methods present in a struct change or not the state of the object itself.
+More specifically, when you have a method in a struct that changes the state
+of the object (i.e. change the value of a data member), the `self` argument
+in this method must be annotated in a different manner.
+
+As I described in the previous section, the `self` argument in methods of
+a struct is the argument that receives as input the object from which the method
+was called from. We usually annotate this argument in the methods by writing `self`,
+followed by the colon character (`:`), and the data type of the struct to which
+the method belongs to (e.g. `User`, `Vec3`, etc.).
+
+If we take the `Vec3` struct that we defined in the previous section as an example,
+we can see in the `distance()` method that this `self` argument is annotated as
+`self: Vec3`. Because the state of the `Vec3` object is never altered by this
+method.
+
+But what if we do have a method that alters the state of the object, by altering the
+values of it's data members. How should we annotate `self` in this instance? The answer is:
+"we should pass a pointer of `x` to `self`, and not simply a copy of `x` to `self`".
+In other words, you should annotate `self` as `self: *x`, instead of annotating it
+as `self: x`.
+
+If we create a new method inside the `Vec3` object that, for example, expands the
+vector by multiplying it's coordinates by a factor o two, then, we need to follow
+this rule specified in the previous paragraph. The code example below demonstrates
+this idea:
+
+```{zig}
+#| build_type: "lib"
+#| auto_main: false
+const std = @import("std");
+const m = std.math;
+const Vec3 = struct {
+    x: f64,
+    y: f64,
+    z: f64,
+
+    pub fn distance(self: Vec3, other: Vec3) f64 {
+        const xd = m.pow(f64, self.x - other.x, 2.0);
+        const yd = m.pow(f64, self.y - other.y, 2.0);
+        const zd = m.pow(f64, self.z - other.z, 2.0);
+        return m.sqrt(xd + yd + zd);
+    }
+
+    pub fn double(self: *Vec3) void {
+        self.x = self.x * 2.0;
+        self.y = self.y * 2.0;
+        self.z = self.z * 2.0;
+    }
+};
+```
+
+Notice in the code example above that we have added a new method
+to our `Vec3` struct named `double()`. This method essentially doubles the
+coordinate values of our vector object. Also notice that, in the
+case of the `double()` method, we annotated the `self` argument as `*Vec3`,
+indicating that this argument receives a pointer (or a reference, if you prefer to call it this way)
+to a `Vec3` object, instead of receiving a copy of the object directly, as input.
+
+```{zig}
+#| eval: false
+var v3 = Vec3 {
+    .x = 4.2, .y = 2.4, .z = 0.9
+};
+v3.double();
+std.debug.print("Doubled: {d}\n", .{v3.x});
+```
+
+```
+Doubled: 8.4
+```
+
+
+
+If you change the `self` argument in this `double()` method to `self: Vec3`, like in the
+`distance()` method, you will get the error exposed below as result. Notice that this
+error message is indicating a line from the `double()` method body,
+indicating that you cannot alter the value of the `x` data member.
+
+```zig
+// If we change the function signature of double to:
+    pub fn double(self: Vec3) void {
+```
+
+This error message indicates that the `x` data member belongs to a constant object,
+and, because of that, it cannot be changed. Even though we marked the `v3` object
+that we have created in the previous code example as a variable object.
+So even though this `x` data member belongs to a variable object in our code, this error
+message is pointing to the opposite direction.
+
+```
+t.zig:16:13: error: cannot assign to constant
+        self.x = self.x * 2.0;
+        ~~~~^~
+```
+
+But this error message is misleading, because the only thing that we have changed
+is the `self` argument signature from `*Vec3` to `Vec3` in the `double()` method. So, just remember this
+general rule below about your method declarations:
+
+::: {.callout-note}
+If a method of your `x` struct alters the state of the object, by
+changing the value of any data member, then, remember to use `self: *x`,
+instead of `self: x` in the function signature of this method.
+:::
+
+You could also interpret the content discussed in this section as:
+"if you need to alter the state of your `x` struct object in one of it's methods,
+you must pass the `x` struct object by reference to the `self` argument of this method,
+instead of passing it by value".
+
+
+
 ## Type inference {#sec-type-inference}
 
 Zig is kind of a strongly typed language. I say "kind of" because there are situations

ZigExamples/zig-basics/vec3_struct.zig

@@ -0,0 +1,37 @@
+const std = @import("std");
+const math = std.math;
+const Vec3 = struct {
+    x: f64,
+    y: f64,
+    z: f64,
+
+    pub fn distance(self: Vec3, other: Vec3) f64 {
+        const xd = math.pow(f64, self.x - other.x, 2.0);
+        const yd = math.pow(f64, self.y - other.y, 2.0);
+        const zd = math.pow(f64, self.z - other.z, 2.0);
+        return math.sqrt(xd + yd + zd);
+    }
+
+    pub fn double(self: *Vec3) void {
+        self.x = self.x * 2.0;
+        self.y = self.y * 2.0;
+        self.z = self.z * 2.0;
+    }
+};
+
+pub fn main() !void {
+    var v1 = Vec3{
+        .x = 4.2,
+        .y = 2.4,
+        .z = 0.9,
+    };
+    const v2 = Vec3{
+        .x = 5.1,
+        .y = 5.6,
+        .z = 1.6,
+    };
+
+    std.debug.print("Distance: {d}\n", .{v1.distance(v2)});
+    v1.double();
+    std.debug.print("Doubled: {d}\n", .{v1.x});
+}