exercises/exercises/051_values.zig

//
// If you thought the last exercise was a deep dive, hold onto your
// hat because we are about to descend into the computer's molten
// core.
//
// (Shouting) DOWN HERE, THE BITS AND BYTES FLOW FROM RAM TO THE CPU
// LIKE A HOT, DENSE FLUID. THE FORCES ARE INCREDIBLE. BUT HOW DOES
// ALL OF THIS RELATE TO THE DATA IN OUR ZIG PROGRAMS? LET'S HEAD
// BACK UP TO THE TEXT EDITOR AND FIND OUT.
//
// Ah, that's better. Now we can look at some familiar Zig code.
//
// @import() adds the imported code to your own. In this case, code
// from the standard library is added to your program and compiled
// with it. All of this will be loaded into RAM when it runs. Oh, and
// that thing we name "const std"? That's a struct!
//
const std = @import("std");

// Remember our old RPG Character struct? A struct is really just a
// very convenient way to deal with memory. These fields (gold,
// health, experience) are all values of a particular size. Add them
// together and you have the size of the struct as a whole.

const Character = struct {
    gold: u32 = 0,
    health: u8 = 100,
    experience: u32 = 0,
};

// Here we create a character called "the_narrator" that is a constant
// (immutable) instance of a Character struct. It is stored in your
// program as data, and like the instruction code, it is loaded into
// RAM when your program runs. The relative location of this data in
// memory is hard-coded and neither the address nor the value changes.

const the_narrator = Character{
    .gold = 12,
    .health = 99,
    .experience = 9000,
};

// This "global_wizard" character is very similar. The address for
// this data won't change, but the data itself can since this is a var
// and not a const.

var global_wizard = Character{};

// A function is instruction code at a particular address. Function
// parameters in Zig are always immutable. They are stored in "the
// stack". A stack is a type of data structure and "the stack" is a
// specific bit of RAM reserved for your program. The CPU has special
// support for adding and removing things from "the stack", so it is
// an extremely efficient place for memory storage.
//
// Also, when a function executes, the input arguments are often
// loaded into the beating heart of the CPU itself in registers.
//
// Our main() function here has no input parameters, but it will have
// a stack entry (called a "frame").

pub fn main() void {

    // Here, the "glorp" character will be allocated on the stack
    // because each instance of glorp is mutable and therefore unique
    // to the invocation of this function.

    var glorp = Character{
        .gold = 30,
    };

    // The "reward_xp" value is interesting. It's an immutable
    // value, so even though it is local, it can be put in global
    // data and shared between all invocations. But being such a
    // small value, it may also simply be inlined as a literal
    // value in your instruction code where it is used.  It's up
    // to the compiler.

    const reward_xp: u32 = 200;

    // Now let's circle back around to that "std" struct we imported
    // at the top. Since it's just a regular Zig value once it's
    // imported, we can also assign new names for its fields and
    // declarations. "debug" refers to another struct and "print" is a
    // public function namespaced within THAT struct.
    //
    // Let's assign the std.debug.print function to a const named
    // "print" so that we can use this new name later!

    const print = ???;

    // Now let's look at assigning and pointing to values in Zig.
    //
    // We'll try three different ways of making a new name to access
    // our glorp Character and change one of its values.
    //
    // "glorp_access1" is incorrectly named! We asked Zig to set aside
    // memory for another Character struct. So when we assign glorp to
    // glorp_access1 here, we're actually assigning all of the fields
    // to make a copy! Now we have two separate characters.
    //
    // You don't need to fix this. But notice what gets printed in
    // your program's output for this one compared to the other two
    // assignments below!

    var glorp_access1: Character = glorp;
    glorp_access1.gold = 111;
    print("1:{}!. ", .{glorp.gold == glorp_access1.gold});

    // NOTE:
    //
    //     If we tried to do this with a const Character instead of a
    //     var, changing the gold field would give us a compiler error
    //     because const values are immutable!
    //
    // "glorp_access2" will do what we want. It points to the original
    // glorp's address. Also remember that we get one implicit
    // dereference with struct fields, so accessing the "gold" field
    // from glorp_access2 looks just like accessing it from glorp
    // itself.

    var glorp_access2: *Character = &glorp;
    glorp_access2.gold = 222;
    print("2:{}!. ", .{glorp.gold == glorp_access2.gold});

    // "glorp_access3" is interesting. It's also a pointer, but it's a
    // const. Won't that disallow changing the gold value? No! As you
    // may recall from our earlier pointer experiments, a constant
    // pointer can't change what it's POINTING AT, but the value at
    // the address it points to is still mutable! So we CAN change it.

    const glorp_access3: *Character = &glorp;
    glorp_access3.gold = 333;
    print("3:{}!. ", .{glorp.gold == glorp_access3.gold});

    // NOTE:
    //
    //     If we tried to do this with a *const Character pointer,
    //     that would NOT work and we would get a compiler error
    //     because the VALUE becomes immutable!
    //
    // Moving along...
    //
    // When arguments are passed to a function,
    // they are ALWAYS passed as constants within the function,
    // regardless of how they were declared in the calling function.
    //
    // Example:
    // fn foo(arg: u8) void {
    //    arg = 42; // Error, 'arg' is const!
    // }
    //
    // fn bar() void {
    //    var arg: u8 = 12;
    //    foo(arg);
    //    ...
    // }
    //
    // Knowing this, see if you can make levelUp() work as expected -
    // it should add the specified amount to the supplied character's
    // experience points.
    //
    print("XP before:{}, ", .{glorp.experience});

    // Fix 1 of 2 goes here:
    levelUp(glorp, reward_xp);

    print("after:{}.\n", .{glorp.experience});
}

// Fix 2 of 2 goes here:
fn levelUp(character_access: Character, xp: u32) void {
    character_access.experience += xp;
}

// And there's more!
//
// Data segments (allocated at compile time) and "the stack"
// (allocated at run time) aren't the only places where program data
// can be stored in memory. They're just the most efficient. Sometimes
// we don't know how much memory our program will need until the
// program is running. Also, there is a limit to the size of stack
// memory allotted to programs (often set by your operating system).
// For these occasions, we have "the heap".
//
// You can use as much heap memory as you like (within physical
// limitations, of course), but it's much less efficient to manage
// because there is no built-in CPU support for adding and removing
// items as we have with the stack. Also, depending on the type of
// allocation, your program MAY have to do expensive work to manage
// the use of heap memory. We'll learn about heap allocators later.
//
// Whew! This has been a lot of information. You'll be pleased to know
// that the next exercise gets us back to learning Zig language
// features we can use right away to do more things!