Allergies in Cairo: Complete Solution & Deep Dive Guide

Pyramids visible over buildings and street traffic

Mastering Bitwise Operations in Cairo: The Complete Allergies Problem Guide

This guide provides a comprehensive solution to the Allergies problem using Cairo, focusing on bitwise operations and enums. We'll break down how a single number can efficiently represent multiple boolean states, a core concept in systems programming and smart contract development, by implementing functions to check for specific allergies and list all of them from a given score.

Have you ever looked at a system's configuration or a user's permissions and seen them represented by a single, cryptic number? It feels unintuitive. You might think, "Why not just use a list of settings or a series of true/false flags?" This is a common pain point for developers encountering low-level data representation for the first time—it seems complex and hard to manage.

But what if that single number was actually a hyper-efficient, compact, and lightning-fast way to store and check multiple states at once? This is the power of bitmasking. In this deep dive, part of the exclusive kodikra.com curriculum, we will demystify this powerful technique. We'll solve the "Allergies" challenge in Cairo, transforming you from someone who is intimidated by bitwise logic to someone who wields it to write cleaner, more optimized code for Starknet and beyond.

What Is the Allergies Problem in Cairo?

The core of the challenge is to build a system that can interpret a person's "allergy score." This score is a single integer (e.g., 34) that encodes all of a person's allergies from a predefined list. Each potential allergen is assigned a unique value that is a power of two.

Here’s the list of allergens and their associated values from the kodikra module:

Eggs: 1 (which is 2⁰)
Peanuts: 2 (which is 2¹)
Shellfish: 4 (which is 2²)
Strawberries: 8 (which is 2³)
Tomatoes: 16 (which is 2⁴)
Chocolate: 32 (which is 2⁵)
Pollen: 64 (which is 2⁶)
Cats: 128 (which is 2⁷)

The allergy score is simply the sum of the values for each item the person is allergic to. For example, a score of 34 means the person is allergic to Chocolate (32) and Peanuts (2). Our task is to write two primary functions in Cairo:

A function that checks if a person is allergic to a specific item given their score.
A function that returns a complete list of all allergies for a given score.

This problem is a classic introduction to bitmasking, a technique that uses bitwise operations to store and manipulate a set of boolean flags within a single integer variable.

Why Use Bitwise Operations? The Core Logic Explained

At first glance, you might consider solving this with loops and subtraction. For a score of 34, you could check: "Is 34 greater than or equal to 128? No. Is it greater than 64? No. Is it greater than 32? Yes. Okay, so they're allergic to Chocolate. Now subtract 32, leaving 2." You'd continue this until the score is zero. This works, but it's computationally inefficient.

A far more elegant and performant solution lies in the binary representation of numbers and the bitwise AND operator (&).

Understanding the Binary Magic

Because each allergen's value is a power of two, it corresponds to a single, unique "on" bit in its binary representation:

Eggs (1) = 00000001
Peanuts (2) = 00000010
Shellfish (4) = 00000100
Chocolate (32) = 00100000
...and so on.

When we sum these values to get a score, we are effectively "flipping on" the corresponding bits in a single number. A score of 34 is 32 + 2, which in binary is 00100010. You can see the bits for Chocolate (the 6th bit) and Peanuts (the 2nd bit) are both set to 1.

This is where the bitwise AND (&) operator comes in. It compares two numbers bit by bit. If both corresponding bits are 1, the resulting bit is 1; otherwise, it's 0.

To check for an allergy, we perform a bitwise AND between the person's score and the allergen's value. If the result is not zero, it means the specific bit for that allergen was "on" in the score, and thus, they are allergic.

For example, to check if a person with a score of 34 is allergic to Chocolate (32):


  00100010  (Score: 34)
& 00100000  (Allergen: Chocolate, 32)
-----------------
  00100000  (Result: 32)

Since the result (32) is not zero, the person is allergic to chocolate. Now let's check for an allergy they don't have, like Shellfish (4):


  00100010  (Score: 34)
& 00000100  (Allergen: Shellfish, 4)
-----------------
  00000000  (Result: 0)

The result is zero, confirming they are not allergic to shellfish. This simple, powerful operation is the foundation of our Cairo solution.

How to Implement the Allergies Solution in Cairo

Now, let's translate this logic into clean, modern Cairo code. We will structure our solution inside a Cairo library, which is perfect for utility functions that don't manage their own state. We'll start by defining our allergens using a Cairo enum for type safety and readability.

Step 1: Defining the `Allergen` Enum

An enum is the perfect tool to represent a fixed set of options. We can define each allergen and explicitly assign its integer value. This makes the code self-documenting and prevents magic numbers.

// Define the list of allergens and their corresponding bitmask values.
// We use u32 as the underlying type for the enum.
#[derive(Copy, Drop, PartialEq)]
enum Allergen {
    Eggs: u32,
    Peanuts: u32,
    Shellfish: u32,
    Strawberries: u32,
    Tomatoes: u32,
    Chocolate: u32,
    Pollen: u32,
    Cats: u32,
}

// Implementation block to provide helper functions for the enum.
impl AllergenImpl of Allergen {
    // A helper function to get the bitmask value for each allergen.
    fn value(self: Allergen) -> u32 {
        match self {
            Allergen::Eggs => 1,
            Allergen::Peanuts => 2,
            Allergen::Shellfish => 4,
            Allergen::Strawberries => 8,
            Allergen::Tomatoes => 16,
            Allergen::Chocolate => 32,
            Allergen::Pollen => 64,
            Allergen::Cats => 128,
        }
    }

    // A helper function to get an array of all possible allergens.
    // This is useful for iterating over all allergens to build the full list.
    fn all() -> Array<Allergen> {
        let mut all_allergens = ArrayTrait::new();
        all_allergens.append(Allergen::Eggs);
        all_allergens.append(Allergen::Peanuts);
        all_allergens.append(Allergen::Shellfish);
        all_allergens.append(Allergen::Strawberries);
        all_allergens.append(Allergen::Tomatoes);
        all_allergens.append(Allergen::Chocolate);
        all_allergens.append(Allergen::Pollen);
        all_allergens.append(Allergen::Cats);
        all_allergens
    }
}

In this snippet, we derive Copy, Drop, and PartialEq to make the enum easy to work with. We also create two helper functions: value() to get the integer representation and all() to provide an iterable list of all variants.

Step 2: Creating the `Allergies` Library

Next, we define our main library and the two required functions: is_allergic_to and list.

use core::array::ArrayTrait;

// (Paste the Allergen enum and impl from Step 1 here)

#[generate_trait]
impl Allergies of IAllergies {
    /// Checks if the allergy score indicates an allergy to a specific allergen.
    ///
    /// # Arguments
    /// * `score` - The person's total allergy score.
    /// * `allergen` - The specific Allergen enum variant to check for.
    ///
    /// # Returns
    /// * `bool` - `true` if allergic, `false` otherwise.
    fn is_allergic_to(score: u32, allergen: Allergen) -> bool {
        // Perform a bitwise AND operation.
        // If the result is non-zero, the specific bit for the allergen was set in the score.
        (score & allergen.value()) != 0
    }

    /// Generates a list of all allergens corresponding to a given allergy score.
    ///
    /// # Arguments
    /// * `score` - The person's total allergy score.
    ///
    /// # Returns
    /// * `Array<Allergen>` - An array containing all allergens identified from the score.
    fn list(score: u32) -> Array<Allergen> {
        let mut detected_allergies = ArrayTrait::new();
        let all_allergens = AllergenImpl::all();

        // Iterate through all possible allergens.
        let mut i = 0;
        loop {
            if i >= all_allergens.len() {
                break;
            }
            
            let allergen = *all_allergens.at(i);
            
            // Use our is_allergic_to function to check each one.
            if Self::is_allergic_to(score, allergen) {
                detected_allergies.append(allergen);
            }
            
            i += 1;
        };

        detected_allergies
    }
}

Code Walkthrough and Explanation

Let's break down the logic of our two main functions.

The `is_allergic_to` Function

This function is the heart of the bitmasking logic. It's remarkably concise:

(score & allergen.value()) != 0

allergen.value(): We retrieve the integer value for the given allergen (e.g., Allergen::Peanuts becomes 2).
score & ...: We perform the bitwise AND operation between the total score and the allergen's value.
... != 0: The result of the AND operation will either be the allergen's value itself (if the bit was set) or 0 (if it wasn't). We simply check if the result is non-zero to return true or false.

The `list` Function

This function builds upon the first one to generate a complete list.

let mut detected_allergies = ArrayTrait::new();: We initialize an empty, mutable array to store the results.
let all_allergens = AllergenImpl::all();: We get our predefined list of all possible allergens to iterate over.
loop { ... }: We loop through each allergen in the all_allergens array.
if Self::is_allergic_to(score, allergen) { ... }: Inside the loop, for each allergen, we call our own is_allergic_to function.
detected_allergies.append(allergen);: If the function returns true, we add the current allergen to our results array.
Finally, the function returns the detected_allergies array.

This approach is both clean and efficient. It reuses our core logic and is easy to read thanks to the helper functions and the enum.

Visualizing the Logic: ASCII Flow Diagrams

To better understand the flow of data and logic, here are two diagrams representing our core functions.

Diagram 1: The `is_allergic_to` Bitwise AND Check

This diagram illustrates how we check a score of 34 for a "Chocolate" (32) allergy.

    ● Start: is_allergic_to(score: 34, allergen: Chocolate)
    │
    ▼
  ┌──────────────────────────┐
  │ Get Allergen Value       │
  │ Chocolate ⟶ 32           │
  └────────────┬─────────────┘
               │
               ▼
  ┌──────────────────────────┐
  │ Convert to Binary        │
  │ Score: 34 ⟶ 00100010     │
  │ Value: 32 ⟶ 00100000     │
  └────────────┬─────────────┘
               │
               ▼
  ┌──────────────────────────┐
  │ Perform Bitwise AND (&)  │
  │   00100010               │
  │ & 00100000               │
  │ ──────────               │
  │   00100000 (Result: 32)  │
  └────────────┬─────────────┘
               │
               ▼
    ◆ Is Result != 0 ?
   ╱           ╲
  Yes           No
 (32 != 0)
  │
  ▼
┌───────────┐
│ Return true │
└───────────┘

Diagram 2: The `list` Function Logic Flow

This diagram shows the high-level process of iterating through all allergens to build the final list.

    ● Start: list(score)
    │
    ▼
  ┌──────────────────────────┐
  │ Initialize empty Array   │
  │ `detected_allergies`     │
  └────────────┬─────────────┘
               │
               ▼
  ┌──────────────────────────┐
  │ Loop through each        │
  │ `allergen` in `Allergen::all()` │
  └────────────┬─────────────┘
      ┌────────┤
      │        ▼
      │   ◆ is_allergic_to(score, allergen) ?
      │  ╱           ╲
      │ Yes           No
      │ │             │
      │ ▼             │
      │┌───────────┐  │
      ││ Add to    │  │
      ││ `detected_allergies` │  │
      │└───────────┘  │
      │  ╲           ╱
      └─────▶ Continue Loop
               │
               ▼
  ┌──────────────────────────┐
  │ Return `detected_allergies`│
  └──────────────────────────┘
    │
    ▼
    ● End

Where Else Are Bitwise Operations Used? Real-World Applications

The skills learned in this kodikra module are not just for solving puzzles. Bitwise operations are fundamental in high-performance and low-level programming, especially in the context of blockchain and smart contracts where efficiency is paramount.

State & Permission Management: In a DAO or a multi-sig wallet, a user's permissions (e.g., can vote, can propose, can execute) can be packed into a single u256 integer. Checking permissions becomes a quick bitwise AND operation, which is significantly cheaper in terms of gas fees than reading multiple storage slots.
Data Packing: To save on costly storage on-chain, developers often pack multiple smaller data types into a single 256-bit storage slot. For example, several boolean flags and small integers can be combined using bit shifting and masking.
Cryptography: Many cryptographic algorithms, which are the bedrock of blockchain security, rely heavily on bitwise operations like AND, OR, XOR, and bit shifts for their calculations.
Optimized Algorithms: In any performance-critical system, bitwise operations can be used to implement faster arithmetic, set manipulations, and data compression algorithms.

By mastering this concept in Cairo, you are building a foundational skill that directly translates to writing more optimized, secure, and gas-efficient smart contracts on Starknet. To continue building these crucial skills, explore our complete Cairo 4 learning path.

Pros & Cons of the Bitmasking Approach

Like any technique, bitmasking has its trade-offs. It's important to know when it's the right tool for the job.

Pros (Advantages)	Cons (Disadvantages)
Space Efficiency: Stores multiple boolean flags in a single integer, drastically reducing memory or storage usage. This is a huge win for gas optimization in smart contracts.	Limited Set of Flags: The number of flags is limited by the bits in the integer type (e.g., a `u32` can hold 32 flags, a `u64` can hold 64). It's not suitable for a dynamic or near-infinite set of options.
High Performance: Bitwise operations are executed directly by the CPU/VM at a very low level, making them incredibly fast compared to loops or complex conditional logic.	Readability: For developers unfamiliar with bitwise logic, code like `(flags & 0x04) != 0` can be less intuitive than `user.is_moderator`. Using enums and well-named functions, as we did, is crucial to mitigate this.
Atomic Operations: Updating multiple flags can often be done in a single atomic operation (e.g., using bitwise OR to set multiple flags at once), which can simplify state management.	Error-Prone: Manually working with bit values (magic numbers) can be error-prone. A typo in a bitmask value can lead to hard-to-debug logical errors. Again, enums are the solution here.

Frequently Asked Questions (FAQ)

1. What exactly is bitmasking?: Bitmasking is a technique that uses bitwise operations to manipulate specific bits within an integer. A "mask" is an integer value (like our allergen values) where certain bits are set to 1 to select or modify the corresponding bits in another integer (the score).
2. Why must the allergen values be powers of two?: Using powers of two (1, 2, 4, 8, ...) ensures that each value has exactly one bit set to '1' in its binary representation (001, 010, 100, etc.). This guarantees that each allergen occupies a unique bit position, preventing any overlap and allowing the bitwise AND operation to isolate each flag perfectly.
3. How would I add a new allergen to this system?: It's straightforward. First, you would add a new variant to the `Allergen` enum. Then, you'd assign it the next power of two as its value (e.g., 256 for the ninth allergen). Finally, you'd update the `AllergenImpl::all()` function to include the new allergen in the list. The core logic in `is_allergic_to` and `list` would work without any changes.
4. Is this bitmasking approach gas-efficient on Starknet?: Yes, extremely. Bitwise operations are among the cheapest computations you can perform in the Cairo VM. Reading a single `u32` or `u256` from storage and performing a bitwise check is far more gas-efficient than reading multiple boolean values from different storage slots.
5. What is the difference between the bitwise AND `&` and the logical AND `&&`?: The bitwise AND `&` operates on integers, comparing them bit by bit to produce a new integer. The logical AND `&&` operates on boolean values (`true`/`false`). It evaluates to `true` only if both of its operands are `true`. You use `&` for bitmasking and `&&` for standard conditional logic (e.g., `if (x > 5 && y < 10)`).
6. Can I check for multiple allergies at once?: Absolutely. You can create a mask for multiple allergies using the bitwise OR `|` operator. For example, to check for an allergy to both Peanuts (2) and Shellfish (4), you could create a mask: `let mask = Allergen::Peanuts.value() | Allergen::Shellfish.value();` which equals 6 (binary `110`). Then, you can check if `(score & mask) == mask`. This confirms that *all* bits in the mask are also set in the score.

Conclusion: From Bits to Mastery

We've successfully dissected the Allergies problem, transforming a seemingly simple challenge into a deep exploration of bitwise operations, enums, and clean code architecture in Cairo. You've learned not just how to solve the problem, but why this solution is powerful, efficient, and widely applicable in real-world scenarios, especially in the resource-constrained environment of blockchain development.

The key takeaways are clear: using powers of two for unique flags, leveraging the bitwise AND operator for efficient checks, and wrapping it all in readable enums and helper functions is a pattern for success. This knowledge is a significant step in your journey to becoming a proficient Cairo developer.

Disclaimer: The code in this article is written for Cairo v2.6.x. The core concepts of bitwise logic are timeless, but always consult the official Starknet and Cairo documentation for the latest syntax and best practices.

Ready to tackle the next challenge? Continue your progress on the kodikra learning path and explore more advanced topics. For a broader overview of the language, be sure to visit our complete Cairo language guide.

Published by Kodikra — Your trusted Cairo learning resource.

kodikra

Search this blog