Cairo

https://github.com/starkware-libs/cairo
Admin
Cairo is a Turing-complete language and blazing fast compiler written in Rust for creating provable...
Tokens:78,540
Snippets:1,182
Trust Score:8.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Minimal Cairo Program Example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/appendices/pages/full-grammar.adoc

A basic example demonstrating function, struct, and implementation definitions.

```cairo
// Function definition
fn main() -> felt252 {
    let x: felt252 = 42;
    x + 1
}

// Struct definition
struct Point {
    x: felt252,
    y: felt252,
}

// Implementation
impl PointImpl of PointTrait {
    fn new(x: felt252, y: felt252) -> Point {
        Point { x, y }
    }
}
```

--------------------------------

### Verify Cairo installation

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/getting_started/pages/prerequisites.adoc

Navigates to the project root and runs the test suite to ensure correct installation.

```bash
cd cairo && cargo test
```

--------------------------------

### Struct Documentation with Example Usage

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Documents a struct with fields and provides an example usage in a code block.

```rust
/// Point struct representing a point in a 2D space.
/// Example usage:
/// ```
///   fn new_Point() {
///     Point {x: 12, y: 14}
///   }
/// ```
/// [Point::bang]
#[derive(Drop)]
#[derive(Copy)]
struct Point {
    /// X coordinate.
    pub x: u32,
    /// Y coordinate.
    y: u32,
}
```

--------------------------------

### Install asciidoctor on Ubuntu

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/readme.md

Installs the `asciidoctor` tool on Ubuntu using apt-get. This is required for converting AsciiDoc files to HTML.

```bash
sudo apt-get install asciidoctor
```

--------------------------------

### Map Function Documentation Example

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/comment_markers.txt

Example usage of the map function.

```cairo
let maybe_some_string: Option<ByteArray> = Some("Hello, World!");
// `Option::map` takes self *by value*, consuming `maybe_some_string`
let maybe_some_len = maybe_some_string.map(|s: ByteArray| s.len());
assert!(maybe_some_len == Some(13));

let x: Option<ByteArray> = None;
assert!(x.map(|s: ByteArray| s.len()) == None);
```

--------------------------------

### Fibonacci Function Example in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-runner/README.md

This example demonstrates a recursive Fibonacci calculation in Cairo. It assumes the `main` function is the entry point for execution.

```cairo
// Calculates fib...
fn main() -> u128 {
    fib(1_u128, 1_u128, 100_u128)
}

fn fib(a: u128, b: u128, n: u128) -> u128 {
    if n == 0 {
        a
    } else {
        fib(b, a + b, n - 1_u128)
    }
}
```

--------------------------------

### Install Rust nightly version

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/getting_started/pages/prerequisites.adoc

Installs the specific nightly Rust version required for the Cairo rustfmt configuration.

```bash
rustup install nightly-2026-07-27
```

--------------------------------

### Set up Rust Toolchain

Source: https://github.com/starkware-libs/cairo/blob/main/README.md

Ensure you have the stable Rust toolchain installed and updated. This is a prerequisite for compiling and running Cairo.

```bash
rustup override set stable && rustup update
```

--------------------------------

### Rust String Initialization Example

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/submodule.txt

An example of initializing a String in Rust, often used in testing contexts. This snippet is for testing purposes only.

```rust
  let a = String::from("This also works fine");

```

--------------------------------

### Install asciidoctor-pdf on Ubuntu

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/readme.md

Installs `asciidoctor-pdf` on Ubuntu using RubyGems, as it may not be available via apt-get. This is required for converting AsciiDoc files to PDF.

```bash
sudo apt-get install ruby ruby-dev
sudo gem install asciidoctor-pdf
```

--------------------------------

### Struct Definition with Code Example

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Shows a struct definition and an example of its usage within a code block in the documentation. Links within code blocks are not tokenized.

```cairo
struct Circle {}

fn new_circle() {
    // [Circle] <- this should not tokenize as a link (neither be resolved), we're inside code
    block.
  }
```

--------------------------------

### Examples of Cairo Paths

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/path.adoc

Demonstrates basic path structures in Cairo, including single and multi-segment paths.

```cairo
x;
x::y::z;
```

--------------------------------

### Basic Destructuring

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/patterns.adoc

Examples of tuple, struct, and nested destructuring.

```cairo
// Tuple destructuring
let (x, y, z) = (1, 2, 3);

// Struct destructuring
struct Rectangle {
    width: u32,
    height: u32,
}
let Rectangle { width, height } = rect;

// Nested destructuring
let ((a, b), c) = ((1, 2), 3);
```

--------------------------------

### Examples of Function Calls

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/function-calls.adoc

Demonstrates various ways to call functions, including calls with named arguments, positional arguments, and no arguments.

```cairo
cmp::max(a: 5, b: 1)
```

```cairo
get_info()
```

```cairo
increment(ref a.b)
```

--------------------------------

### Define a Struct with Attributes and Example Usage

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Defines a `Point` struct with `Drop` and `Copy` attributes, including public and private fields. An example usage block demonstrates how to instantiate the struct.

```cairo
struct Point {
    pub x: u32,
    y: u32,
}
```

```cairo
  fn new_Point() {
    Point {x: 12, y: 14}
  }
```

--------------------------------

### Module-level constants

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/constant-items.adoc

Basic examples of defining constants at the module scope.

```cairo
const TEN: felt252 = 10;
const FLAG: bool = true;
const PAIR: (u8, u8) = (1_u8, 2_u8);
```

--------------------------------

### Variable and Array Assignment Examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/assignment-statement.adoc

Illustrates how to assign new values to mutable variables and arrays in Cairo.

```cairo
let mut x = 5;
x = 10;  // Assigns 10 to x

let mut arr = array![1, 2, 3];
arr = array![4, 5, 6];  // Assigns a new array to arr
```

--------------------------------

### All Struct Expression Examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/struct-expressions.adoc

Demonstrates various ways to create struct instances, including basic instantiation, field init shorthand, functional updates, and fields in different orders.

```cairo
#[derive(Drop, Copy)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn examples() {
    // Basic instantiation
    let rect1 = Rectangle { width: 30, height: 50 };

    // Field init shorthand
    let width = 40;
    let height = 60;
    let rect2 = Rectangle { width, height };

    // Functional update
    let rect3 = Rectangle { width: 100, ..rect1 };  // height copied from rect1

    // Fields in different order
    let rect4 = Rectangle { height: 20, width: 10 };
}
```

--------------------------------

### Option Chaining Example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/error-propagation-operator.adoc

Shows how the `?` operator can be used to chain operations that return `Option`. If any operation returns `None`, the function exits early.

```cairo
fn get_first_char(s: @ByteArray) -> Option<u8> {
    s.at(0)
}

fn process() -> Option<u8> {
    let s: ByteArray = "hello";
    let first = get_first_char(@s)?;
    Option::Some(first)
}

fn process_empty() -> Option<u8> {
    let s: ByteArray = "";
    let first = get_first_char(@s)?;
    Option::Some(first)
}
```

--------------------------------

### Member access usage examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/member-access-expressions.adoc

Demonstrates accessing struct fields, nested struct fields, and tuple elements.

```cairo
struct Point {
    x: felt252,
    y: felt252,
}

struct Line {
    start: Point,
    end: Point,
}

fn example() -> felt252 {
    let p = Point { x: 10, y: 20 };
    let sum = p.x + p.y;

    let line = Line {
        start: Point { x: 0, y: 0 },
        end: Point { x: 10, y: 10 },
    };
    let end_x: felt252 = line.end.x;

    let t: (felt252, u8) = (1, 2_u8);
    let first: felt252 = t.0;
    let second: u8 = t.1;

    sum
}
```

--------------------------------

### Boolean Operations Example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/boolean-types.adoc

Demonstrates logical, bitwise, and comparison operations on boolean variables. Use `assert` to verify conditions.

```cairo
fn main() {
    let x: bool = true;
    let y = false;

    // Logical operations
    let z1 = x && y;  // false
    let z2 = x || y;  // true
    let z3 = !x;      // false

    // Bitwise operations
    let z4 = x & y;   // false
    let z5 = x | y;   // true

    // Comparisons
    assert(x == true, 'x is true');
    assert(x != y, 'x and y differ');
}
```

--------------------------------

### Install asciidoctor-pdf on macOS

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/readme.md

Installs the `asciidoctor-pdf` converter on macOS using Homebrew. This is needed for generating PDF documents from AsciiDoc files.

```bash
brew install asciidoctor-pdf
```

--------------------------------

### Import Cycle Example in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/use.adoc

Demonstrates a potential import cycle scenario where modules try to import items from each other, which the Cairo compiler will flag as an error.

```cairo
mod foo {
    use super::bar;
}
use foo::bar;
```

--------------------------------

### Pattern Matching

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/patterns.adoc

Example of using match to unwrap an Option enum.

```cairo
enum Option<T> {
    Some: T,
    None,
}

fn unwrap_or<T>(option: Option<T>, default: T) -> T {
    match option {
        Option::Some(value) => value,
        Option::None => default,
    }
}
```

--------------------------------

### Method Call Examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/functions.adoc

Illustrates how to call methods on a struct instance using dot notation. Shows calls to `increment` (using a mutable reference) and `get_value` (using a snapshot).

```cairo
let mut counter = Counter { value: 0 };
counter.increment();  // Calls increment with ref self
let value = counter.get_value();  // Calls get_value with snapshot
```

--------------------------------

### Install asciidoctor on macOS

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/readme.md

Installs the `asciidoctor` tool on macOS using Homebrew. This is required for converting AsciiDoc files to HTML.

```bash
brew install asciidoctor
```

--------------------------------

### Arithmetic Negation Panic Example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/negation-operators.adoc

Shows how negating the minimum value of a signed integer type results in a panic due to underflow.

```cairo
fn will_panic() {
    let min: i8 = Bounded::<i8>::MIN;
    let result = -min;  // Panics: i8_neg Underflow
}
```

--------------------------------

### Implement conditional panics

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/panic.adoc

Examples of triggering a panic manually or conditionally within a function.

```cairo
fn will_panic() {
    panic(array!['error message']);
}

fn conditional_panic(x: u32) {
    if x == 0 {
        panic(array!['x cannot be zero']);
    }
}
```

--------------------------------

### Function Signature and Body Example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/functions.adoc

Illustrates a function signature with generic parameters and a function body. The signature defines the function's interface, while the body contains the executable code.

```cairo
fn inc_n<T, const N>(x: T) -> T {
    x + N
}
```

--------------------------------

### Cairo Documentation Comments

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/documentation_comment_parser_links.txt

Example documentation comments containing various link syntax patterns.

```cairo
/// See [one](path) and [two](path2).
/// See [**bold** `code`](path).
/// See [*em* `code`](path).
/// See [![alt](img) label](path).
/// See [super::ids].
/// See [`super::ids`].
/// See [` super::ids `].
/// See [label](`super::ids`).
/// See [**some_label** anything else i want](super::ids).
/// Just a comment without links.
/// See [broken(link.
/// See [`  crate::Structure`]

fn foo() {}
```

--------------------------------

### Enum Variant Documentation

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Demonstrates how enum variants are documented. The 'Yes' and 'No' variants are simple examples.

```cairo
Yes
```

```cairo
No
```

--------------------------------

### Enum Type Compatibility Example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/enum-types.adoc

Illustrates that different generic instantiations of the same enum type are incompatible.

```cairo
enum Container<T> {
    Value: T,
    Empty,
}

let x: Container<u32> = Container::Value(1_u32);
let y: Container<felt252> = Container::Value(2);
// x and y have different types: Container<u32> vs Container<felt252>
```

--------------------------------

### Move Semantics Example (Non-Compiling)

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_semantics/pages/linear-types.adoc

Demonstrates how passing a value to a function moves it, making it unusable afterward. This code will not compile because `a` is used twice.

```cairo
struct A {}

fn main() {
    let a = A {};
    foo(a); // value is passed by value once here.
    foo(a); // error: Value was previously moved.
}
```

--------------------------------

### Associativity Examples in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/operator-precedence.adoc

Demonstrates left-to-right associativity for operators of the same precedence group, such as subtraction and division.

```cairo
let x = 20 - 5 - 3; // Parsed as (20 - 5) - 3
let y = 8 / 2 / 2;  // Parsed as (8 / 2) / 2
```

--------------------------------

### Run Cargo Tests

Source: https://github.com/starkware-libs/cairo/blob/main/README.md

Verify that your Rust installation is correct by running the project's tests from the root directory.

```bash
cargo test
```

--------------------------------

### Basic Cairo Variable Declaration

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/submodule.txt

A simple example demonstrating variable declaration in Cairo. This snippet is for testing purposes only.

```cairo
  let a = 5;
```

--------------------------------

### Concrete Paths in Expressions

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/path.adoc

Shows examples of concrete paths used in function calls and enum variant expressions.

```cairo
foo::bar::<bool>() // Function call expression
Option::<bool>::Some(true) // Enum variant expression
```

--------------------------------

### Operator Precedence Examples in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/operator-precedence.adoc

Illustrates how arithmetic, unary, and postfix operators are evaluated based on their precedence. Use parentheses to override default precedence.

```cairo
// Arithmetic binds tighter than comparison and logical operators.
let a = 2 + 3 * 4 == 14 && true; // ((2 + (3 * 4)) == 14) && true

// Prefix unary operators bind tighter than arithmetic operators.
let b = -x * 2; // (-x) * 2

// Postfix operators bind tighter than arithmetic operators.
let c = arr[0] + 1; // (arr[0]) + 1

// Use parentheses to override default precedence.
let d = (2 + 3) * 4;
```

--------------------------------

### Use Option for Failure

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/error-type.adoc

Example of using Option<T> to represent the absence of a value as a failure mode.

```cairo
use core::option::Option::{self, Some, None};

fn first_even(values: Span<u32>) -> Option<u32> {
    for value in values {
        if *value % 2 == 0 {
            return Some(*value);
        }
    }
    None
}
```

--------------------------------

### Define Documentation Comments with Links

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/documentation_comment_parser_links.txt

Examples of various markdown link formats within Cairo documentation comments.

```cairo
/// See [` super::ids `].
```

```cairo
/// See [label](`super::ids`).
```

```cairo
/// See [**some_label** anything else i want](super::ids).
```

```cairo
/// Just a comment without links.
```

```cairo
/// See [broken(link.
```

```cairo
/// See [`  crate::Structure`]
```

```cairo
/// See [**bold**](path) and [*em*](path2).

fn foo() {}
```

--------------------------------

### Basic Cairo Variable Declaration

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/submodule.txt

Demonstrates a simple variable declaration in Cairo. This is a basic example for testing purposes.

```cairo
  let a = 5;

```

--------------------------------

### Cairo Type and Impl Inference Examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/inference.adoc

Demonstrates type inference for variables and generic arguments, as well as impl inference for trait method calls.

```cairo
let x = 1_u8;
let y = Option<_>::Some(x);
let u: u32 = Into::<u8, u32>::into(x);
let u: u32 = x.into();
```

--------------------------------

### Concrete Paths in Trait Expressions

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/path.adoc

Provides examples of concrete paths used within trait implementations and generic trait bounds.

```cairo
impl MyImpl of MyTrait<usize> { // trait expression after `of` keyword
    ...
}
fn foo<impl Imp: MyTrait<usize>>() { ... } // trait expression after `:` in an impl generic argument
```

--------------------------------

### Iterating over a Span in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/slice-types.adoc

Provides examples of iterating over a Span<T> using for loops, manual `pop_front()` in a while loop, and the `into_iter()` method.

```cairo
// For loop iteration
for x in array![1, 2, 3].span() {
    // x is @T (snapshot of element)
    // Dereference with * to use the value
    let value = *x;
}

// Manual iteration
let mut span = array![10, 20, 30].span();
while let Option::Some(value) = span.pop_front() {
    // value is @T, dereference with *value to use it
}

// Using iterator
let mut iter = array![1, 2, 3].span().into_iter();
while let Option::Some(value) = iter.next() {
    // value is @T
}
```

--------------------------------

### Arithmetic Negation Examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/negation-operators.adoc

Demonstrates arithmetic negation for signed integers and `felt252`. Negation of `felt252` is performed modulo the field prime.

```cairo
fn main() {
    let value: i32 = -42;
    let negated: i32 = -value;  // negated = 42

    let x: felt252 = 5;
    let neg_x: felt252 = -x;  // Negation modulo the field prime
}
```

--------------------------------

### Basic Function Call Syntax

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/function-calls.adoc

Illustrates the general syntax for calling a function with its concrete path and arguments. Use this for standard function invocations.

```cairo
<concrete_path>(<arg0>,<arg1>,...)
```

--------------------------------

### Basic impl alias example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/impl-aliases.adoc

Defines a trait and an impl, then creates an impl alias for a shorter name. `FeltPow` is an alias for `AnyAlgebraPow<felt252, FeltAlgebra>`.

```cairo
trait Pow<T> {
    fn pow(base: T, exp: u32) -> T;
}

impl AnyAlgebraPow<T, impl AlgImpl: Algebra<T>> of Pow<T> {
    fn pow(base: T, exp: u32) -> T {
        // Implementation details.
        base
    }
}

// Impl alias for Pow of felt252.
impl FeltPow = AnyAlgebraPow<felt252, FeltAlgebra>;

fn main() {
    // Call through the trait name.
    let x = Pow::pow(5, 3);

    // Call through the impl alias name.
    let y = FeltPow::pow(5, 3);
}
```

--------------------------------

### Generate Impl from Another Impl

Source: https://github.com/starkware-libs/cairo/blob/main/adrs/003_simple_trait_system.md

This example shows how to generate an implementation for one trait based on an existing implementation of another trait, similar to Rust's generic trait bounds.

```cairo
impl CloneFromCopy<T, CopyImpl: impl Copy<T>> of Clone<T> {}
```

--------------------------------

### Cairo Code Block Example

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/font_formatting.txt

Illustrates how to include a Cairo code block within documentation. Ensure the code block is correctly indented and formatted.

```cairo
  fn new_Point() {
    Point {x: 12, y: 14}
  }

```

--------------------------------

### Basic Cairo Test Functions

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-test-runner/README.md

These are example Cairo test functions demonstrating the use of `assert`. The `#[should_panic]` attribute is used to test failing assertions.

```cairo
#[test]
fn test_assert_true() {
    // Asserts that true is true.
    assert(true, 'assert(true)');
}

#[test]
#[should_panic]
fn test_assert_false() {
    assert(false, 'assert(false)');
}
```

--------------------------------

### Valid Tuple Expression Examples

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/tuple-expressions.adoc

Illustrates various valid tuple expressions, including the unit tuple, a 1-ary tuple, mixed-type tuples, and nested tuples.

```cairo
()
```

```cairo
(1_u32,)
```

```cairo
(1_u32, Some(3_u8))
```

```cairo
(true, false, 'abc')
```

```cairo
((1, 2), (3, 4))
```

--------------------------------

### Chaining impl aliases example

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/impl-aliases.adoc

Demonstrates chaining impl aliases, where one alias refers to another. `ImplAlias1` and `Impl2Alias` are names for existing impls and can be used in generic parameters or trait method calls.

```cairo
trait Trait1<T> {
    fn func1(value: T);
}

trait Trait2<T> {
    fn func2(value: T);
}

mod impls {
    impl Impl1<T, +Drop<T>> of super::Trait1<T> {
        fn func1(value: T) {}
    }

    // Public alias for a concrete impl of Trait1<felt252>.
    pub impl ImplAlias1 = Impl1<felt252>;

    impl Impl2<T, +Drop<T>> of super::Trait2<T> {
        fn func2(value: T) {}
    }

    // Public alias for a concrete impl of Trait2<felt252>.
    pub impl ImplAlias2 = Impl2<felt252>;
}

use impls::ImplAlias1;

// A second-level alias that refers to an impl alias from another module.
impl Impl2Alias = impls::ImplAlias2;
```

--------------------------------

### Using System Calls

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/contracts.adoc

Details how to use the `starknet::syscalls::call_contract_syscall` system call for direct contract interaction.

```APIDOC
## Using System Calls

Another way to call another contract is to use the `starknet::syscalls::call_contract_syscall` system call.

To directly call another contract using `starknet::syscalls::call_contract_syscall` you can do the following, but the result is the serialized return value of the function which you need to deserialize yourself.

```cairo
#[starknet::interface]
trait IMySecondContract<TContractState> {
    fn syscall_call_another_contract(
        ref self: TContractState,
        address: starknet::ContractAddress,
        selector: felt252,
        calldata: Array<felt252>,
    ) -> Span<felt252>;
}

#[starknet::contract]
mod my_second_contract {
    use starknet::SyscallResultTrait;

    #[storage]
    struct Storage {}

    #[abi(embed_v0)]

```

--------------------------------

### Getting ByteArray Length

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/string-types.adoc

The .len() method returns the number of bytes in a ByteArray.

```cairo
let s: ByteArray = "byte array";
let len = s.len();  // Returns 10

```

--------------------------------

### Concrete Path with Generic Arguments

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/path.adoc

Illustrates how to use concrete paths with explicit generic arguments and how the compiler infers them.

```cairo
fn foo<A, B>(a: A, b: B) { ... }

fn main() {
    foo::<bool, bool>(false, 3_u32); // OK
    foo::<bool, _>(false, 3_u32);    // OK, B is inferred to be u32
    foo::<bool>(false, 3_u32);       // OK, B is inferred to be u32
    foo(false, 3_u32);               // OK, A, B are inferred as bool and u32 respectively
}
```

--------------------------------

### If-else if chain for number classification

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/if-expressions.adoc

A practical example of an `if-else if` chain to classify a number.

```cairo
fn classify_number(x: i32) -> ByteArray {
    if x < 0 {
        "negative"
    } else if x == 0 {
        "zero"
    } else if x < 10 {
        "single digit"
    } else {
        "multi digit"
    }
}
```

--------------------------------

### Using Comparison and Logical Operators in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/operator-expressions.adoc

Demonstrates the use of comparison operators like > and >=, and logical operators like && to evaluate conditions.

```cairo
fn is_valid_age(age: u32) -> bool {
    age >= 18 && age <= 120
}

fn main() {
    let age = 25;
    let height = 180;

    // Comparison operators
    let is_adult = age > 18;

    // Logical operators combine conditions
    let is_eligible = age >= 18 && height >= 150;

    let is_valid = is_valid_age(age);
}
```

--------------------------------

### Implement Result in Functions

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/error-type.adoc

Example of a function returning a Result type with a custom error enum.

```cairo
use core::result::Result;

enum ParseError {
    InvalidVersion: felt252,
}

fn parse_version(header: felt252) -> Result<felt252, ParseError> {
    match header {
        0 => Result::Ok(0),
        1 => Result::Ok(1),
        other => Result::Err(ParseError::InvalidVersion(other)),
    }
}
```

--------------------------------

### Common Use Case: Creating Multiple References

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/snapshot-type.adoc

Shows how to create multiple references to a large data structure using snapshots, enabling different parts of the program to access the same data immutably.

```cairo
let data = create_large_structure();
worker1(@data);
worker2(@data);
```

--------------------------------

### Define Mapper Trait

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/comment_markers.txt

Defines a generic trait for mapping values with an embedded usage example.

```cairo
trait Mapper<T> {
    /////////////////////////////////////////////////////////////////////////
    // Transforming contained values
    /////////////////////////////////////////////////////////////////////////

    /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value (if `Some`)
    /// or returns `None` (if `None`).
    ///
    /// # Examples
    ///
    /// ```
    /// let maybe_some_string: Option<ByteArray> = Some("Hello, World!");
    /// // `Option::map` takes self *by value*, consuming `maybe_some_string`
    /// let maybe_some_len = maybe_some_string.map(|s: ByteArray| s.len());
    /// assert!(maybe_some_len == Some(13));
    ///
    /// let x: Option<ByteArray> = None;
    /// assert!(x.map(|s: ByteArray| s.len()) == None);
    /// ```
    fn map<U, F, +Destruct<F>, +core::ops::FnOnce<F, (T,)>[Output: U]>(
        self: Option<T>, f: F,
    ) -> Option<U>;
}
```

--------------------------------

### Configure cairo_project.toml

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/comment_markers.txt

Defines the crate root for the project.

```toml
[crate_roots]
hello = "src"
```

--------------------------------

### Struct with Derive Attribute

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Example of a struct with the `Drop` derive attribute, indicating it can be dropped and will shatter.

```cairo
#[derive(Drop)]
struct Glass {}

This glass is droppable.
When it's dropped, it shatters.
```

```cairo
#[derive(Drop)]
struct Cup {}

This cup is droppable.
When it's dropped, it shatters.
```

--------------------------------

### Get Length of Dynamic Array

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/array-types.adoc

Retrieves the number of elements in a dynamic array. Returns `usize`.

```cairo
let len = arr.len(); // usize
```

--------------------------------

### Defining and Calling a Method in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/method-calls.adoc

Demonstrates how to define a trait with a method and implement it for a type. The method can then be called using the convenient method call syntax.

```cairo
trait Display<T> {
    fn display(self: T) -> Array<u8>;
}

impl DisplayUsize of Display<usize> {
    fn display(self: usize) -> Array<u8> {
        // Implementation details omitted for brevity
        // ...
    }
}

fn bar<T: impl TDisplay: Display<T>>(value: T) {
    // ...
    // Can be called as a method.
    let c = value.display();
    // ...
}
```

--------------------------------

### Define a generic identity function

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/generics.adoc

A basic example of a function using a type generic parameter T.

```cairo
fn foo<T>(x: T) -> T { x }
```

--------------------------------

### Document a Function with Default Implementation

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Provides documentation for a function `abc` which has a default implementation. Includes inner comments for detailed explanations.

```cairo
Default impl of abc TraitTest function. Default impl of abc TraitTest function inner comment.
```

--------------------------------

### Instantiate a Struct

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/structs.adoc

Instantiate a struct by providing values for all its members using the struct expression syntax. All members must be specified, but their order does not matter.

```cairo
let mut tree = Tree {
    height: 6,
    number_of_leaves: 10000,
};
```

--------------------------------

### Basic Function Definitions

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/functions.adoc

Defines two simple functions: `main` for entry point and `inc` for incrementing a value. Functions are declared using the `fn` keyword.

```cairo
fn main() {
    let x = 3;
}

fn inc(x: u32) -> u32 {
    x + 1
}
```

--------------------------------

### Use named generic arguments

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/generics.adoc

Demonstrates that named generic arguments allow specifying them in any order.

```cairo
let x = foo::<T: u32, S: u64>(5);
let x = foo::<S: u64, T: u32>(5);
```

--------------------------------

### Implement Contract Entry Points

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/contracts.adoc

Implements the contract's external entry points by defining functions within an `impl` block marked with `#[abi(embed_v0)]`. This allows interaction with the contract's state.

```cairo
#[abi(embed_v0)]
    impl MyContractImpl of super::IMyContract<ContractState> {
        fn set_value(ref self: ContractState, value: felt252) {
            self.x.write(value);
        }

        fn get_value(self: @ContractState) -> felt252 {
            self.x.read()
        }
    }
```

--------------------------------

### Pattern Matching with Option Enum

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/enum-types.adoc

Demonstrates how to use pattern matching to access values within an Option enum.

```cairo
fn process_option(value: Option<u32>) -> u32 {
    match value {
        Option::Some(x) => x,
        Option::None => 0,
    }
}
```

--------------------------------

### Basic Felt252Dict Usage

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/felt252dict-type.adoc

Demonstrates initializing a dictionary, inserting values, and retrieving them. Non-existent keys return 0 by default.

```cairo
let mut dict: Felt252Dict<u128> = Default::default();
dict.insert(10, 110);
dict.insert(11, 111);
let val10 = dict[10]; // 110
let val11 = dict[11]; // 111
let val12 = dict[12]; // 0
dict.insert(10, 120);
let val10 = dict[10]; // 120
```

--------------------------------

### Define tuple types in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/tuple-types.adoc

Examples of various tuple type definitions, including the unit type and multi-element tuples.

```cairo
() // Unit type.
(bool,)
(u32, u256)
(felt252, u16, Option<u8>)
```

--------------------------------

### Early Function Exit with Return

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/return-expressions.adoc

Illustrates how `return` statements exit a function immediately, skipping any subsequent code. This is useful for handling error conditions or specific cases early.

```cairo
fn check_positive(x: i32) -> felt252 {
    if x < 0 {
        return 0;  // Exit early if negative
    }
    x.into()
}
```

--------------------------------

### Integer Overflow Behavior

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/integer-types.adoc

Illustrates that integer operations in Cairo panic on overflow. This example shows an overflow with `u8` addition.

```cairo
fn will_panic() {
    let x: u8 = 255;
    let y = x + 1;  // Panics: u8_add Overflow
}
```

--------------------------------

### Define and instantiate a generic struct

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/generics.adoc

Demonstrates creating a generic struct Box and instantiating it with different concrete types.

```cairo
fn main() {
    struct Box<T> {
        value: T,
    }

    let box_u32 = Box::<u32> { value: 5_u32 };
    let box_u128 = Box::<u128> { value: 1_u128 };
    let box_box_u32 = Box::<Box::<u32>> { value: 100_u32 };
}
```

--------------------------------

### Grade calculation using if-else if chain

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/if-expressions.adoc

An example of using an `if-else if` chain to determine a letter grade based on a score.

```cairo
fn grade(score: u32) -> ByteArray {
    if score >= 90 {
        "A"
    } else if score >= 80 {
        "B"
    } else if score >= 70 {
        "C"
    } else if score >= 60 {
        "D"
    } else {
        "F"
    }
}
```

--------------------------------

### Common Use Case: Working with Generic Functions

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/snapshot-type.adoc

Demonstrates using snapshots in generic functions. A snapshot allows the generic function to operate on a value and use it multiple times, as shown with `println!`.

```cairo
fn print_twice<T, impl TDisplay: Display<T>>(value: @T) {
    println!("{}", value);
    println!("{}", value);  // Can use snapshot twice
}
```

--------------------------------

### Valid if without else returning unit type

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/if-expressions.adoc

This example shows a valid use case where the `if` branch also returns `()`.

```cairo
let x = 5;
if x > 10 {
    do_something();  // Returns ()
}
```

--------------------------------

### Processing Sequences with Span in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/slice-types.adoc

An example function that calculates the sum of elements in a Span<u32> by repeatedly popping elements from the front.

```cairo
fn sum_span(mut span: Span<u32>) -> u32 {
    let mut total = 0;
    while let Option::Some(val) = span.pop_front() {
        total += *val;
    }
}
```

--------------------------------

### Function Call with Expression and Reference Arguments

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/function-calls.adoc

Shows how to pass both expression and reference arguments to a function. Note the use of `ref` for reference arguments.

```cairo
fn main() {
    let x = 3;
    let mut y = A { z: 5 };
    foo(x, ref y.z);
}
```

--------------------------------

### Compile Starknet Contract to Sierra ContractClass

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/getting_started/pages/compiling-starknet-contracts.adoc

Use this command to compile a Starknet crate into a Sierra ContractClass. Specify the input crate path and the output JSON file path.

```bash
cargo run --bin starknet-compile -- /path/to/crate /path/to/output.json
```

--------------------------------

### Compile Starknet Contract with Specific Contract Path

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/getting_started/pages/compiling-starknet-contracts.adoc

When multiple contracts are defined in a single crate, use the `--contract-path` flag to specify the exact contract to compile.

```bash
cargo run --bin starknet-compile -- /path/to/crate /path/to/output.json --contract-path path::to::contract
```

--------------------------------

### Import Items with `use`

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/namespaces.adoc

Import specific items from other modules using `use`. You can import multiple items, use aliases with `as`, or import all items using a glob (`*`), though glob imports should be used carefully.

```cairo
use crypto::hash::sha256;
use std::array::ArrayTrait as Arr;

use my_module::{item1, item2};
use my_module::*;  // Glob (use carefully)
```

--------------------------------

### Use impl generic parameters

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/generics.adoc

Shows how to use impl generic parameters to allow users to specify which trait implementation to use.

```cairo
trait MulTrait<T> {
    fn mul(x: T) -> T;
}
impl Double<u32> of MulTrait::<u32> {
    fn mul(x: u32) -> u32 {
        x * 2
    }
}
impl Triple<u32> of MulTrait::<u32> {
    fn mul(x: u32) -> u32 {
        x * 3
    }
}
fn foo<T, impl MyImpl: MulTrait::<T>>(x: T) -> T {
    MyImpl::mul(x)
}
fn main() {
    let x = foo::<u32, Double::<u32>>(5);
    assert(x == 10, 'Should be doubled');

    let y = foo::<u32, Triple::<u32>>(5);
    assert(y == 15, 'Should be tripled');
}
```

--------------------------------

### Variable Dropping Example (Non-Compiling)

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_semantics/pages/linear-types.adoc

Highlights the restriction that values may not go out of scope unless moved. This code will not compile because the `A` instance is not dropped.

```cairo
#[derive(Copy)]
struct A {}

fn main() {
    A {}; // error: Value not dropped.
}
```

--------------------------------

### Organize Related Functionality with Modules

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/module.adoc

Group related code, such as adapters and traits, into separate modules. Use `pub use` to expose specific items from these modules.

```cairo
mod adapters;
mod traits;
pub use adapters::PeekableTrait;
pub use adapters::zip::zip;
pub use traits::{Extend, FromIterator, IntoIterator, Iterator, Product, Sum};
```

--------------------------------

### Deserialization using Span in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/slice-types.adoc

A practical example showing how a Span<T> can be used to deserialize data, such as a Point struct, by consuming elements from the span.

```cairo
fn deserialize_point(ref data: Span<felt252>) -> Option<Point> {
    let x = (*data.pop_front()?).try_into()?;
    let y = (*data.pop_front()?).try_into()?;
    Option::Some(Point { x, y })
}
```

--------------------------------

### Bitwise NOT with Different Integer Types

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/negation-operators.adoc

Provides examples of the bitwise NOT operator `~` applied to various unsigned integer types (`u8`, `u32`, `u16`).

```cairo
fn bitwise_examples() {
    let a: u8 = 0xFF;
    let not_a = ~a;  // 0x00

    let b: u32 = 0x0000FFFF;
    let not_b = ~b;  // 0xFFFF0000

    let c: u16 = 0b1111000011110000;
    let not_c = ~c;  // 0b0000111100001111
}
```

--------------------------------

### Call Another Contract Syscall in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/contracts.adoc

Demonstrates how to use the `call_contract_syscall` to invoke another contract. Ensure the `starknet` module is imported.

```cairo
impl MySecondContractImpl of super::IMySecondContract<ContractState> {
        fn syscall_call_another_contract(
            ref self: ContractState,
            address: starknet::ContractAddress,
            selector: felt252,
            calldata: Array<felt252>
        ) -> Span<felt252> {
            starknet::syscalls::call_contract_syscall(
                :address, entry_point_selector: selector, calldata: calldata.span()
            ).unwrap_syscall()
        }
    }
}
```

--------------------------------

### Managing Operator Precedence in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/operator-expressions.adoc

Illustrates how arithmetic, comparison, and logical operators are evaluated based on precedence, and how to use parentheses to override default behavior.

```cairo
fn main() {
    // Multiplication has higher precedence than addition
    let result = 2 + 3 * 4;  // 14, not 20

    // Use parentheses to override
    let result2 = (2 + 3) * 4;  // 20

    // Comparison binds looser than arithmetic
    let check = 10 + 5 > 12;  // true (evaluates as (10 + 5) > 12)

    // Logical AND binds tighter than OR
    let logic = true || false && false;  // true (as true || (false && false))
}
```

--------------------------------

### Iterating Over a Range in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/for-loop-expressions.adoc

Example of using a for loop to iterate over a range of numbers. The loop variable `i` will take values from 0 up to (but not including) 5.

```cairo
for i in 0..5_usize {
    // i takes values 0, 1, 2, 3, 4
}
```

--------------------------------

### Run a Gas-Tested Cairo File

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-runner/README.md

Execute a Cairo file with a specified amount of available gas. This is useful for gas testing.

```bash
cargo run --bin cairo-run -- --single-file /path/to/file.cairo --available-gas 200
```

--------------------------------

### Struct Documentation with Code Block

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-doc/src/tests/test-data/basic.txt

Illustrates documentation for a struct that includes a multi-line code block. Comments and links within these blocks are ignored.

```cairo
struct Square {}

    First line of code
    // Comment inside the code block, that should be ignored. [Square] <- it will be ignored as
    well.
    Second line of code
```

--------------------------------

### Accessing Span Elements in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/slice-types.adoc

Shows how to access elements within a Span<T> using indexing and the safe `get()` method, which returns an Option.

```cairo
let span = array![10, 20, 30].span();

// Indexing (returns snapshot of element)
let second = span[1];           // Returns @20 (panics if out of bounds)
let second = span.at(1);        // Returns @20 (panics if out of bounds)

// Safe access with Option
let opt = span.get(1);          // Returns Option<Box<@u32>>
match opt {
    Option::Some(val) => {
        let v = val.unbox();    // @20
    },
    Option::None => {},
}
```

--------------------------------

### Slicing a Span in Cairo

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/slice-types.adoc

Demonstrates creating a sub-span from an existing Span<T> using the `slice(start, length)` method. Panics if the range is invalid.

```cairo
let span = array![10, 20, 30, 40, 50].span();
let sub = span.slice(1, 3);  // Returns Span containing [20, 30, 40]
```

--------------------------------

### Run code formatters

Source: https://github.com/starkware-libs/cairo/blob/main/docs/CONTRIBUTING.md

Execute the project-specific formatting scripts for Rust and Cairo codebases.

```bash
scripts/rust_fmt.sh && scripts/cairo_fmt.sh
```

--------------------------------

### Compile Starknet Contract to Sierra

Source: https://github.com/starkware-libs/cairo/blob/main/README.md

Compile a Starknet contract from a specified crate or project path into a Sierra ContractClass JSON format.

```bash
cargo run --bin starknet-compile -- /path/to/input/crate /path/to/output.json
```

--------------------------------

### Example of a function returning unit type implicitly

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/unit-type.adoc

This function performs an assertion and does not explicitly return a value, thus implicitly returning the unit type `()`.

```cairo
pub fn assert_eq<T, +PartialEq<T>>(a: @T, b: @T, err_code: felt252) {
    assert(a == b, err_code);
}
```

--------------------------------

### Define Starknet Contract Interface and Implementation

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/contracts.adoc

Defines a contract interface using `#[starknet::interface]` and implements it within a `#[starknet::contract]` module. This sets up the contract's ABI and logic.

```cairo
#[starknet::interface]
trait IMyContract<TContractState> {
    fn get_value(self: @TContractState) -> felt252;
    fn set_value(ref self: TContractState, value: felt252);
}

#[starknet::contract]
mod my_contract {
    use starknet::storage::{
        StoragePointerReadAccess, StoragePointerWriteAccess, StorageMapWriteAccess, Map,
    };

    #[storage]
    struct Storage {
        x: felt252,
        m: Map<felt252, u128>,
    }

    #[abi(embed_v0)]
    impl MyContractImpl of super::IMyContract<ContractState> {
        fn get_value(self: @ContractState) -> felt252 {
            self.x.read()
        }

        fn set_value(ref self: ContractState, value: felt252) {
            self.x.write(value);
            self.m.write(value, 3_u128);
        }
    }
}
```

--------------------------------

### Primitive Type Comparisons

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/comparison-operators.adoc

Demonstrates the basic usage of comparison operators (<, <=, >, >=) with primitive integer types.

```cairo
fn main() {
    assert!(1 < 2);
    assert!(2 <= 2);
    assert!(3 > 1);
    assert!(3 >= 3);
}
```

--------------------------------

### Access Element by Index Safely (get)

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/array-types.adoc

Safely access an element by its index using `.get(index)`. Returns `Option<Box<@T>>` and does not panic if out of bounds.

```cairo
match arr.get(2) {
    Option::Some(x) => { let value = *x.unbox(); },
    Option::None => { /* out of bounds */ }
}
```

--------------------------------

### Basic Struct Instantiation

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/struct-expressions.adoc

Use basic instantiation to create a struct value by explicitly providing values for all its fields. Fields can be in any order.

```cairo
struct Point {
    x: felt252,
    y: felt252,
}

fn example() -> Point {
    Point { x: 10, y: 20 }
}
```

```cairo
// Both are equivalent
let p1 = Point { x: 10, y: 20 };
let p2 = Point { y: 20, x: 10 };
```

--------------------------------

### Accessing Struct/Enum Fields via Snapshot

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/snapshot-type.adoc

Demonstrates creating a snapshot of a struct and accessing its fields. Fields are automatically desnapped starting from edition 2025_12.

```cairo
#[derive(Copy, Drop)]
struct Point {
    x: u32,
    y: u32,
}

let point = Point { x: 10, y: 20 };
let snap = @point;
let x_val = snap.x;  // Access field through snapshot
// Note: Starting from edition 2025_12, fields are automatically desnapped
```

--------------------------------

### Run a Single Cairo File

Source: https://github.com/starkware-libs/cairo/blob/main/crates/cairo-lang-runner/README.md

Use this command to execute a single Cairo file. Ensure the path to the file is correct.

```bash
cargo run --bin cairo-run -- --single-file /path/to/file.cairo
```

--------------------------------

### Nullable Deref with Panic on Null

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/never-type.adoc

This example shows how a `never` type (via panic) can be used in one arm of a match expression, while the other arm returns a value.

```cairo
fn deref(self: Nullable<T>) -> T {
    match match_nullable(self) {
        FromNullableResult::Null => crate::panic_with_felt252('Attempted to deref null value'),
        FromNullableResult::NotNull(value) => value.unbox(),
    }
}

```

--------------------------------

### Match on Enum Variants

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/match-expressions.adoc

Demonstrates how to match an enum instance against its declared variants. Each variant can bind variables from its data.

```cairo
match enum_var {
    variant_0(a, b, c) => { /* code */ }
    variant_1(_) => { /* code */ }
    ...
    variant_k(a, c) => { /* code */ }
}
```

--------------------------------

### Overloading Operators for Custom Types

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/language_constructs/pages/operator-expressions.adoc

Implement the corresponding trait to enable operator usage for custom structs. This example demonstrates overloading the addition operator for a Point struct.

```cairo
#[derive(Copy, Drop)]
struct Point {
    x: u32,
    y: u32,
}

impl PointAdd of Add<Point> {
    fn add(lhs: Point, rhs: Point) -> Point {
        Point { x: lhs.x + rhs.x, y: lhs.y + rhs.y }
    }
}

fn main() {
    let p1 = Point { x: 1, y: 2 };
    let p2 = Point { x: 3, y: 4 };
    let p3 = p1 + p2;  // Now works for Point
}
```

--------------------------------

### Configure Rust environment

Source: https://github.com/starkware-libs/cairo/blob/main/docs/reference/src/components/cairo/modules/getting_started/pages/prerequisites.adoc

Sets the Rust toolchain to stable and updates it to the latest version.

```bash
rustup override set stable && rustup update
```

--------------------------------

### Rust Equivalent for Trait Generation

Source: https://github.com/starkware-libs/cairo/blob/main/adrs/003_simple_trait_system.md

This Rust code demonstrates the concept of generating a `Clone` implementation for types that implement `Copy`, illustrating the pattern used in the Cairo example.

```rust
impl<T: Copy> Clone for T {}
```
Tokens:
Raw