Merge pull request #44 from pedropark99/fix-c

Add section to describe type casting

Author: pedropark99

Chapters/03-structs.qmd

@@ -97,7 +97,7 @@ if (x > 10) {
 
 
 
-### Swith statements {#sec-switch}
+### Switch statements {#sec-switch}
 
 Switch statements are also available in Zig.
 A switch statement in Zig have a similar syntax to a switch statement in Rust.
@@ -1043,11 +1043,8 @@ is commonly used on switch statements in Zig.
 ## Modules
 
 We already talked about what modules are, and also, how to import other modules into
-you current module through *import statements*, so that you can use functionality from these other modules in
-your current module.
-But in this section, I just want to make it clear that modules are actually structs in Zig.
-
-In other words, every Zig module (i.e. a `.zig` file) that you write in your project
+you current module through *import statements*.
+Every Zig module (i.e. a `.zig` file) that you write in your project
 is internally stored as a struct object.
 Take the line exposed below as an example. In this line we are importing the
 Zig Standard Library into our current module.
@@ -1089,3 +1086,89 @@ const pool = ThreadPool.init(
     .{ .max_threads = num_threads }
 );
 ```
+
+
+
+## Type casting {#sec-type-cast}
+
+In this section, I want to discuss type casting (or, type conversion) with you.
+We use type casting when we have an object of type "x", and we want to convert
+it into an object of type "y", i.e. we want to change the data type of the object.
+
+Most languages have a formal way to perform type casting. In Rust for example, we normally
+use the keyword `as`, and in C, we normally use the type casting syntax, e.g. `(int) x`.
+In Zig, we use the `@as()` built-in function to cast an object of type "x", into
+an object of type "y".
+
+This `@as()` function is the preferred way to perform type conversion (or type casting)
+in Zig. Because it is explicit, and, it also performs the casting only if it
+is unambiguous and safe. To use this function, you just provide the target data type
+in the first argument, and, the object that you want cast at the second argument.
+
+```{zig}
+#| auto_main: false
+#| build_type: "test"
+const std = @import("std");
+const expect = std.testing.expect;
+test {
+    const x: usize = 500;
+    const y = @as(u32, x);
+    try expect(@TypeOf(y) == u32);
+}
+```
+
+This is the general way to perform type casting in Zig. But remember, `@as()` works only when casting
+is unambiguous and safe, and there are situations where these assumptions do not hold. For example,
+when casting an integer value into a float value, or vice-versa, it is not clear to the compiler
+how to perform this conversion safely.
+
+Therefore, we need to use specialized "casting functions" in such situations.
+For example, if you want to cast an integer value into a float value, then, you
+should use the `@floatFromInt()` function. In the inverse scenario, you should use
+the `@intFromFloat()` function.
+
+In these functions, you just provide the object that you want to
+cast as input. Then, the target data type of the "type casting operation" is determined by
+the type annotation of the object where you are saving the results.
+In the example below, we are casting the object `x` into a value of type `f32`,
+because the object `y`, which is where we are saving the results, is annotated
+as an object of type `f32`.
+
+```{zig}
+#| auto_main: false
+#| build_type: "test"
+const std = @import("std");
+const expect = std.testing.expect;
+test {
+    const x: usize = 565;
+    const y: f32 = @floatFromInt(x);
+    try expect(@TypeOf(y) == f32);
+}
+```
+
+Another built-in function that is very useful when performing type casting operations is `@ptrCast()`.
+In essence, we use the `@as()` built-in function when we want to explicit convert (or cast) a Zig value/object
+from a type "x" to a type "y", etc. However, pointers (we are going to discuss pointers
+in more depth at @sec-pointer) are a special type of object in Zig,
+i.e. they are treated differently from "normal objects".
+
+Everytime a pointer is involved in some "type casting operation" in Zig, the `@ptrCast()` function is used.
+This function works similarly to `@floatFromInt()`.
+You just provide the pointer object that you want to cast as input to this function, and the
+target data type is, once again, determined by the type annotation of the object where the results are being
+stored.
+
+```{zig}
+#| auto_main: false
+#| build_type: "test"
+const std = @import("std");
+const expect = std.testing.expect;
+test {
+    const bytes align(@alignOf(u32)) = [_]u8{
+        0x12, 0x12, 0x12, 0x12
+    };
+    const u32_ptr: *const u32 = @ptrCast(&bytes);
+    try expect(@TypeOf(u32_ptr) == *const u32);
+}
+```
+

Chapters/13-image-filter.qmd

@@ -285,8 +285,6 @@ object that reads the PNG file that we want to use.
 const c = @cImport({
     @cDefine("_NO_CRT_STDIO_INLINE", "1");
     @cInclude("stdio.h");
-});
-const png = @cImport({
     @cInclude("spng.h");
 });
 
@@ -295,8 +293,8 @@ const file_descriptor = c.fopen(path, "rb");
 if (file_descriptor == null) {
     @panic("Could not open file!");
 }
-const ctx = png.spng_ctx_new(0) orelse unreachable;
-_ = png.spng_set_png_file(
+const ctx = c.spng_ctx_new(0) orelse unreachable;
+_ = c.spng_set_png_file(
     ctx, @ptrCast(file_descriptor)
 );
 ```
@@ -334,13 +332,13 @@ Thus, an object of type `spng_ihdr` is a C struct that contains the data from th
 image header section of the PNG file.
 
 Since this Zig function is receiving a C object (the `libspng` context object) as input, I marked
-the function argument `ctx` as "a pointer to the context object" (`*png.spng_ctx`), following the recommendations
+the function argument `ctx` as "a pointer to the context object" (`*c.spng_ctx`), following the recommendations
 that we have discussed at @sec-pass-c-structs.
 
 ```zig
-fn get_image_header(ctx: *png.spng_ctx) !png.spng_ihdr {
-    var image_header: png.spng_ihdr = undefined;
-    if (png.spng_get_ihdr(ctx, &image_header) != 0) {
+fn get_image_header(ctx: *c.spng_ctx) !c.spng_ihdr {
+    var image_header: c.spng_ihdr = undefined;
+    if (c.spng_get_ihdr(ctx, &image_header) != 0) {
         return error.CouldNotGetImageHeader;
     }
 
@@ -375,10 +373,10 @@ the size of the space that we need to allocate.
 
 
 ```zig
-fn calc_output_size(ctx: *png.spng_ctx) !u64 {
+fn calc_output_size(ctx: *c.spng_ctx) !u64 {
     var output_size: u64 = 0;
-    const status = png.spng_decoded_image_size(
-        ctx, png.SPNG_FMT_RGBA8, &output_size
+    const status = c.spng_decoded_image_size(
+        ctx, c.SPNG_FMT_RGBA8, &output_size
     );
     if (status != 0) {
         return error.CouldNotCalcOutputSize;
@@ -419,12 +417,12 @@ Also, we are using the `SPNG_FMT_RGBA8` enum value once again to inform the corr
 that the PNG image being decoded, uses the RGBA color model and 8 bit depth.
 
 ```zig
-fn read_data_to_buffer(ctx: *png.spng_ctx, buffer: []u8) !void {
-    const status = png.spng_decode_image(
+fn read_data_to_buffer(ctx: *c.spng_ctx, buffer: []u8) !void {
+    const status = c.spng_decode_image(
         ctx,
         buffer.ptr,
         buffer.len,
-        png.SPNG_FMT_RGBA8,
+        c.SPNG_FMT_RGBA8,
         0
     );
 
@@ -579,26 +577,26 @@ in this new PNG file.
 
 
 ```zig
-fn save_png(image_header: *png.spng_ihdr, buffer: []u8) !void {
+fn save_png(image_header: *c.spng_ihdr, buffer: []u8) !void {
     const path = "pedro_pascal_filter.png";
     const file_descriptor = c.fopen(path.ptr, "wb");
     if (file_descriptor == null) {
         return error.CouldNotOpenFile;
     }
     const ctx = (
-        png.spng_ctx_new(png.SPNG_CTX_ENCODER)
+        c.spng_ctx_new(c.SPNG_CTX_ENCODER)
         orelse unreachable
     );
-    defer png.spng_ctx_free(ctx);
-    _ = png.spng_set_png_file(ctx, @ptrCast(file_descriptor));
-    _ = png.spng_set_ihdr(ctx, image_header);
+    defer c.spng_ctx_free(ctx);
+    _ = c.spng_set_png_file(ctx, @ptrCast(file_descriptor));
+    _ = c.spng_set_ihdr(ctx, image_header);
 
-    const encode_status = png.spng_encode_image(
+    const encode_status = c.spng_encode_image(
         ctx,
         buffer.ptr,
         buffer.len,
-        png.SPNG_FMT_PNG,
-        png.SPNG_ENCODE_FINALIZE
+        c.SPNG_FMT_PNG,
+        c.SPNG_ENCODE_FINALIZE
     );
     if (encode_status != 0) {
         return error.CouldNotEncodeImage;

Chapters/14-zig-c-interop.qmd

@@ -417,14 +417,12 @@ As I described at the previous section, the `[*c]` portion of the type
 means that it is a C pointer. This strategy is not-recommended. But it is
 useful to demonstrate the use of `@ptrCast()`.
 
-You may recall of the `@as()` built-in function, which is used to explicit convert (or cast) a Zig value from a type `x`
-to a type `y`, etc. That is, this `@as()` Zig function is equivalent to the
-`as` keyword in Rust, and the C type casting syntax (e.g. `(int) x`).
-But in our case here, we are not converting any type of object.
-More specifically, we are converting something into a pointer, or, a C pointer more specifically.
+You may recall of `@as()` and `@ptrCast()` from @sec-type-cast. Just as a recap,
+the `@as()` built-in function is used to explicit convert (or cast) a Zig value from a type "x"
+to a type "y".
+But in our case here, we are converting a pointer object, or, a C pointer more specifically.
 Everytime a pointer is involved in some "type casting operation" in Zig,
-the `@ptrCast()` function is involved. This `@ptrCast()` function is responsible
-for converting a pointer of one type to a pointer of another type.
+the `@ptrCast()` function is involved.
 
 In the example below, we are using this function to cast our `path` object
 into a C pointer to an array of bytes. Then, we pass this C pointer as input