I was touching grass with the tip of my feet, jumping around the meadow, then I saw a herding of wild variables and I thought: Why are they all coming and going by a group if each of them all owns a value by themselves.

—  Cut it dude, looks like I’m crazy — 

Sometime we want to store a bunch of data, but nobody wants to write a bunch of variables just for the sake of it. Here comes collections, in this post we’ll be talking about arrays.

As we know a collection is an abstract data type that consist in a group of variables that holds a relation between them, e.g: You want to store the first 10 unsigned integers, the days of the week or even the months of the year, all and each them holds a shared significance and needs to be operated upon together to solve the given problem.

There are different type of collections out there, hashmaps, sets, maps and so on, but for now we’ll focus on static and dynamic arrays, how to represent it (visually) and while doing it and I’m sure we’ll spot some differences as well.

Introduction to static arrays

An static array is a fixed-size contiguous Data Structure, that means the values will be stored one next to other. First, let’s take a deeper look at how variables works to spot some differences:

A variable is like a box that will hold your value ready to be read or changed. The compiler & the linker will work together to assign you variable’s name to a memory address, it’s the compiler’s job to keep track of all the references (calls to that variable) and the linker to put the right location in it. So anytime you see an indentifier foo the compiler will see a 0xnnnnnnnn instead.

Something similar happens to static arrays, they let you keep multiple values under the same name but accessed through an unique identifier, and the array must have a known size at compile time, since they are stored in the stack memory — we’ll be digging into that topic soon. Another cool thing about arrays is they are homogeneous: That means that each element is of the same type, e.g. an array of integers or an array of chars.

Visually explained

A good way to get a better grasp of it is to explain it visually so I’m going make a horrible drawing and then we jump right into it.

In the center we find a box with a few cells in it, each cell contains a value and each value can be accessed through an index. I did create a small box below the array to show how indexing is being made. By the way you can notice that as the definition stated before every element is of the same type.

But an array with data unable to being read isn’t really handy, right? So let’s take a look at the next topic.

Indexing

In the vast majority of programming languages indexing uses zero-based numbering. This means that in order to get the data stored in the 3rd spot in our example array, we do have to get it through the index 2. In the picture below I did represent each index within its value.

📍Note: Array’s last index will always be (length - 1). In our example the length is 4, so the last element will be indexed by ( 4 - 1 ) index 3.

📍Note: It’s worth to remark that the squared brackets notation used here Array[Index] is convention among the most popular programming languages. By the way, if you’re interested in how it became standart you can read whether the discussion here or a summary here.

But now a question raises from the depths of our minds. What if we try to access to index -1 or index 4, What will we get?

Index out of bounds

Whether trying to access to negative index or a index greater or equal to the array’s length you’re accessing to an illegal index. In the modern programming languages this will result in an error labeled Index out of bounds. But in older languages such as C the compiler neither provide compile-time checks nor runtime checks for out of bounds access. So you’re likely to compile an error prone program and run into Undefined Behaviour.

Introduction to dynamic arrays

A big throwback when working with static sized array is that there’s no good way to add an element( n + 1) if the array is of size n. So instead of allocating a enormous capacity —  Which is a horrible decision when it comes to performance —  for the array, we can use dynamic arrays.

❔ Let’s take a slight look at what’s the logic behind it.

Dynamic arrays are, in fact, a static array with some magic tricks going underlying. In short, when the array runs out of space to store more values in it the compiler allocates another array with the double of size and copying the elements to the new array.

Look the at the picture bellow.

Imagine having an array of size 1, if we add a single value, it’ll have no longer space so the compiler allocates another array of size 2, copies the values to it and deallocates the old array. The same proccess will happen as long as we fulfill the available space.

Conclusion

Arrays are a very straightforward data structures and is one of the most popular ways to relate data. In further posts I’ll be talking about how are arrays implemented in C++ (and Rust), how to use them and some useful examples to get seasoned. Hope you enjoyed ❤️

⚠ Warning

This post requires basic understanding of some programming concepts as structs, functions, modules, and I/O handling. It is also recommended to have Rust knowledge, if you are new to programming I highly recommend you to check out this video and/or if you are new to Rust, you should read the official book.

Before getting into our hacker fashion, let’s create a cargo project and install the packages we’ll need:

cargo new ferris-say

Now, open your Cargo.toml, and add this below [dependencies]:

[dependencies]
ansi_term = "0.12.1"
clap = { version = "3.1.6", features = ["derive"] }

Or, if you have cargo edit (which I prefer using), write right in your terminal:

cargo add ansi_term 
cargo add clap --features derive

After it’s installed, we’re ready to go to the next step.

Getting input from arguments

The crate clap that we just installed and used in the snippet below, helps us not only to parse but to validate the input given by the user. Let’s see how to implement it in our application.

First thing is to create a function named input here we’ll handle and parse the arguments provided; Our Cli will request only two arguments to work with: quote and color but for color we need an enum as we’ll only allow to use a few types of colors (but a cool ones).

The function signature

The function signatures let us to know how many parameters will it receive and what will be the output generated, and let’s bring into scope both of the crate we’ll be using along this tutorial:

// Imports
use ansi_term::{self, Colour};
use clap::{ArgEnum, Parser};

fn input() -> (String, Colour)

Parsing the input

  #[derive(Parser, Debug)]
  #[clap(author, version, about = "cowsay rusty version")]
    struct Args {
        /// Quote that ferris will say
        #[clap(short, long)]
        quote: String,

        /// Colors to choose
        #[clap(arg_enum)]
        color: Colors,
    }

The Parser trait that our struct derives, parses all the arguments provided by the user and turns it into that struct fields. As you can see, we only have two fields, so it means, we’ll only receive two arguments, as we state before.

Note that quote is the type of String and color is the type of Colors, but it doesn’t exist yet, so let’s create it.

  #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ArgEnum, Debug)]
    enum Colors {
        // Not black because it's the background color
        Red,
        Green,
        Yellow,
        Blue,
        Purple,
        Cyan,
        White,
    }

Focus on that ArgEnum derived trait, that means: “Hey, this enum’s variants are the only few valid types for a argument” and clap will ensure that the argument provided fits into it.

Once we have our Colors enum, let’s handle each variant using the classic match statement.

Handling the input

At this point we already brought into scope our ansi_term crate so it’s time to use it

// Imports
use clap::{ArgEnum, Parser};
use ansi_term::{self, Colour} // -> This one

// fn input(){...} 

So we can crate a match statement to filter through the Colors(our enum) variants, return a Colour(ansi_term’s enum) variant and bind it to a variale named color_matched.

First, create a new instance of Args. To access to its field (quote and color) we need to use the dot notation:

// ...
let args = Args::parse();
// to access to the quote:
args.quote
// to access to the color:
args.color // If you want to show through terminal remember using ":?"

Now we are up to handle:

// ...
    let color_matched = match args.color {
        Colors::Red => Colour::Red,
        Colors::Green => Colour::Green,
        Colors::Yellow => Colour::Yellow,
        Colors::Blue => Colour::Blue,
        Colors::Purple => Colour::Purple,
        Colors::Cyan => Colour::Cyan,
        Colors::White => Colour::White,
    };
    println!("The user picked the color {:?}", color_matched);

Last thing to do is return the tuple:

//...
(args.quote, color_matched)

Time to test it!

cargo build
target/debug/ferris_say.exe -h
ferris-say 0.1.0
cowsay rusty version

USAGE:
    ferris_say.exe --quote <QUOTE> <COLOR>

ARGS:
    <COLOR>    Colors to choose [possible values: red, green, yellow, blue, purple,
               cyan, white]

OPTIONS:
    -h, --help             Print help information
    -q, --quote <QUOTE>    Quote that ferris will say
    -V, --version          Print version information

passing the -h or --help shows the arguments we can use.

Once we know what are the arguments, we’re able to use it correctly.

target/debug/ferris_say.exe -q "Hello world!" red
The user picked the color Red

But…what if I pass a color that isn’t valid?

target/debug/ferris_say.exe -q "hello world!" black
error: "black" isn't a valid value for '<COLOR>'
        [possible values: red, green, yellow, blue, purple, cyan, white]

USAGE:
    ferris_say.exe --quote <QUOTE> <COLOR>

For more information try --help

We are ready to go to the next step: drawing the ferris.

Draw the ferris

Here, I highly recommend you just to copy and paste the drawing. But first, let’s create another function draw:

The function signature

fn draw(quote: &str, color: &Colour)

Inside the draw function:

// Ferris drawing
    const FERRIS: &'static str = r"
    .
     .
      .
       █ █           █ █
        ▀█  ▄█████▄  █▀
         ▀▄███▀█▀███▄▀ 
         ▄▀███▀▀▀███▀▄ 
         █ ▄▀▀▀▀▀▀▀▄ █
    ";
    println!("{}", format!("\"{}\"{}", quote, color.paint(FERRIS)));

A r"" String is called as “raw string”, in short, it tells the compiler to ignore every scape character, It’s easier for us to draw our ferris that way. On the other hand we have a format!macro, we use it as we’ll place the text right above the ferris. It will be better illustrated as we run the program.

Last but not least color is a Colour instance passed by reference, that means we can use the paint that receives a &str params. It “paints” the text to a given color.

Finally inside our main function:

fn main() {
    let (q, c) = input();
    draw(&q, &c)
}

Final code

We’ll split it into parts to understand how it works.

use ansi_term::{self, Colour}; // 0.12.1
use clap::{ArgEnum, Parser};

fn draw(quote: &str, color: &Colour) {
    // Ferris drawing
    const FERRIS: &'static str = r"
    .
     .
      .
       █ █           █ █
        ▀█  ▄█████▄  █▀
         ▀▄███▀█▀███▄▀ 
         ▄▀███▀▀▀███▀▄ 
         █ ▄▀▀▀▀▀▀▀▄ █
    ";
    println!("{}", format!("\"{}\"{}", quote, color.paint(FERRIS)));
}
fn input()-> (String, Colour) {
    #[derive(Parser, Debug)]
    #[clap(author, version, about = "cowsay rusty version")]
    struct Args {
        /// Quote that ferris will say
        #[clap(short, long)]
        quote: String,

        /// Colors to choose
        #[clap(arg_enum)]
        color: Colors,
    }

    #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ArgEnum, Debug)]
    enum Colors {
        // Not black because it's the our background color
        Red,
        Green,
        Yellow,
        Blue,
        Purple,
        Cyan,
        White,
    }

    let args = Args::parse();
    // validate colors argument:
    let color_matched = match args.color {
        Colors::Red => Colour::Red,
        Colors::Green => Colour::Green,
        Colors::Yellow => Colour::Yellow,
        Colors::Blue => Colour::Blue,
        Colors::Purple => Colour::Purple,
        Colors::Cyan => Colour::Cyan,
        Colors::White => Colour::White,
    };
    (args.quote, color_matched)
}

fn main() {
    let (q, c) = input();
    draw(&q, &c)
}

Result photos

I hope you guys enjoyed this tutorial, any comment or suggestion my email is opened!