Crate giftbox[−][src]

Expand description

A fun Rust crate called giftbox to help Rustlings learn and explore generics. Let’s wrap our heads around Rust Generics!

              .__.      .==========.
            .(\\//).  .-[  GiftBox ]
           .(\\()//)./  '=========='
       .----(\)\/(/)----.
       |     ///\\\     |
       |    ///||\\\    |
       |   //`||||`\\   |
       |      ||||      |
       |      ||||      |
       '------====------'

Purpose

The purpose of this crate is to:

  • Help Rustlings understand Rust generics and how to use them.
  • Expand upon related beginner topics to support a Rustling’s understanding of generics.
  • Provide a fun crate to be used in hands-on self-directed Rustling projects to assist the learning process.
  • Be approachable, supportive, and encourage participation in a GiftBox community.

Concept

This crate uses the concept of a gift box to help explain Rust generics.

Imagine a real-life gift box. You can put any gift inside this gift box, wrap this gift box with wrapping paper, add a bow, and add a gift tag to show who it is for, who it is from and a short message. The gift box is generic, so you can reasonably assume that you can use this gift box to put any gift inside.

Imagine more, if you will, that Rust’s compiler is like the gift wrapping station at your local shopping mall. This imaginary gift wrapping station already has gift boxes for every type of gift available in the shopping mall. It can also build a new gift box on demand to put inside other gifts that you bring to them, which may not be already in the shopping mall. This gift wrapping station is so exceptional that they can pretty much put any gift you bring to them in a gift box.

Once your gift box is filled with a gift, it can then be gift wrapped or not. If it is wrapped it can have different patterns available at the gift wrapping station. You can also decide to add a gift tag or not.

In this way, the gift box is a generic. It is generic enough so that you can use it to wrap a huge–almost limitless–number of different things inside it. We will use this concept of the gift box to help describe what generics are in Rust.

Associating the Concept with Rust Concepts

Sometimes a metaphor can assist in the learning process. Metaphors help abstract difficult concepts so that the learner can relate these difficult concepts to other concepts that they may already be accustomed to. It is in this way that this crate uses the gift box metaphor to describe what a Rust generic is.

In order for the use of metaphors to work best, and to help reduce confusion, let’s relate the metaphors to the Rust concepts we are trying to learn:

  • rustc The Rust Compiler

    The Rust compiler, in this example, can be thought of as the gift wrapping station. When compiling a program that has generics, the compiler needs to know what the generics are being used for in order to allocate the appropriate amount of memory. In this same way, the gift wrapping station needs to know what gift (or at least what type of gift) is being wrapped so that they know which sized box they should use. If the gift wrapping station uses a box that is too big, the box will be inefficient and more difficult to carry than it needs to be. If the box is too small, the gift might not even fit in the box at all!

  • Generics Rust Generic Data Types

    In Rust, a generic is a generalized type or functionality that can be used for different types. “Wait, what?!”, you might ask. Think of generics as the gift box. A gift box is normally generic enough that it can be used for a large variety of gifts, as long as the gift box is sized correctly. The versatility of the gift box allows it to be useful in a large number of contexts. For example, a gift box can be used for many different occasions such as a birthday, Christmas, or an anniversary and hold many different types of gifts like a book, or toys, or candy, or many different things all at once! Therefore, similar to Rust generics, the gift box is a real-life “generic”.

How to Use this Crate and Documentation

Though this crate is made for new Rustlings, this crate assumes the following:

  • You have some prior programming experience.
  • You have read The Rust Book at least once.
  • You already have a preferred IDE set-up and you are ready to code in Rust.
  • You are willing to have fun learning generics!

This crate is meant to be used in any Rust project and the documentation is written in a tutorial style to aid new Rustlings in how to make use of generics. It is recommended that, if you are very new to Rust, that you follow along with the tutorial articles (links forthcoming).

If you are already comfortable using Rust crates and just want to play with these generics, you can import this crate by adding giftbox to your Cargo.toml dependencies. Examples are provided below to assist in using the crate.

The documentation is verbose to help Rustlings in understanding how to use the crate. Concepts are visited and described when required. Throughout the documentation examples are provided on how to make use of the various modules.

Structure of Crate

The giftbox crate is composed of four modules:

  1. giftbox

    Contains the giftbox::GiftBox enum which is the base instructional type for this crate.

  2. giftwrap

    Contains the giftwrap::GiftWrap struct meant to illustrate another use of generics and how generics can be used together.

  3. patterns

    Contains the patterns::Patterns enum meant to be used within the giftwrap::GiftWrap struct.

  4. gifttag

    Contains the gifttag::GiftTag struct also meant to be used within the giftwrap::GiftWrap struct.

Examples

The following are some examples to help new Rustlings make use of this crate. Examples can be copy-pasted and used. Be sure to add giftbox to your dependencies in Cargo.toml!

Import the crate and fill a gift box

use giftbox::giftbox::GiftBox;
use giftbox::gifttag::GiftTag;
use giftbox::giftwrap::GiftWrap;
use giftbox::patterns::Patterns;
let filled_box = GiftBox::fill(Some(["Toys", "Candy", "Money"]));
let tag = GiftTag::write(
    "Bob".to_string(),
    "Sally".to_string(),
    "Happy Cake Day!".to_string()
);
let wrapped_box = filled_box.wrap(
    Patterns::Polkadots,
    true,
    Some(tag)
);
assert_eq!(
     wrapped_box,
     {
         GiftWrap {
             contents:{
                 GiftBox::Gifts(["Toys", "Candy", "Money"])
             },
             pattern: Patterns::Polkadots,
             has_bow: true,
             tag: Some(
                 GiftTag {
                     recipient: "Bob".to_string(),
                     sender: "Sally".to_string(),
                     message: "Happy Cake Day!".to_string()
                 }
             )
         }
     }
)

Modules

giftbox

This module defines the GiftWrap enum which is the base generic type used in this crate. It represents a real-life gift box which can hold any gift that can fit within the box. The enum has two variants:

gifttag

This module defines the GiftTag. It is meant to be used by the crate::giftwrap::GiftWrap module but can be used anywhere in Rust. The GiftTag can be imagined as a tag that is tied to a wrapped gift box. It contains the following information in Strings:

giftwrap

This module defines the GiftWrap struct. This can be used by crate::giftbox::GiftBox to wrap itself. It is meant to represent wrapping paper used to wrap a gift box. The struct has four fields:

patterns

The module defines the Patterns enum. It is used by crate::giftwrap::GiftWrap.