From c8a9235c1d6cd83b44a6eb33a15ea7651c044eb6 Mon Sep 17 00:00:00 2001 From: Princetimix69 Date: Tue, 24 Feb 2026 22:54:18 +0800 Subject: [PATCH 1/2] docs: expand prelude documentation --- .../language_constructs/pages/prelude.adoc | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc b/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc index adc296ec6a4..e49a31a03e3 100644 --- a/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc +++ b/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc @@ -8,3 +8,116 @@ It is automatically used in every module. It is not possible to disable standard library prelude importing. This means that items from the prelude are always in scope without explicit imports, which is why you can use types like `Option`, `Result`, and common traits without importing them. + +== Items Included in the Prelude + +The prelude includes commonly used types, traits, and functions that are essential for Cairo programming. +The following categories of items are automatically imported: + +=== Basic Types + +* `bool` — Boolean type +* `felt252` — Field element type (252-bit) +* `usize` — Unsigned size type +* Integer types: `u8`, `u16`, `u32`, `u64`, `u128`, `u256`, `i8`, `i16`, `i32`, `i64`, `i128` + +=== Collection Types + +* `Array` and `ArrayTrait` — Dynamic array type and its methods +* `Span` and `SpanTrait` — Immutable view into arrays +* `ToSpanTrait` — Conversion to span +* `ByteArray` and `ByteArrayTrait` — Byte array type for string handling +* `Felt252DictTrait` — Dictionary with felt252 keys + +=== Option and Result Types + +* `Option`, `Some`, `None` — Optional value type and variants +* `OptionTrait` — Methods for working with options +* `Result`, `Ok`, `Err` — Result type for error handling and variants +* `ResultTrait` — Methods for working with results + +=== Common Traits + +* `Copy` — Types that can be copied by copying bits +* `Clone` — Types that can be explicitly cloned +* `Drop` — Types that can be safely dropped +* `Destruct` — Types that can be explicitly destructed +* `PanicDestruct` — Types that can be destructed during panic +* `Default` — Types with a default value +* `PartialEq` — Types that support equality comparison +* `PartialOrd` — Types that support ordering comparison +* `Into` and `TryInto` — Type conversion traits +* `Serde` — Serialization and deserialization + +=== Arithmetic Traits + +* `Add`, `Sub`, `Mul`, `Div`, `Rem` — Arithmetic operations +* `Neg` — Negation operation +* `Not` — Logical NOT operation +* `DivRem` — Combined division and remainder + +=== Other Types and Traits + +* `Box` and `BoxTrait` — Heap-allocated pointer type +* `Nullable` and `NullableTrait` — Nullable pointer type +* `NonZero` — Non-zero wrapper type +* `Iterator`, `IntoIterator`, `FromIterator` — Iterator traits +* `Deref` — Dereference trait +* `Felt252DictValue` — Values that can be stored in felt252 dictionaries + +=== Panic Functions + +* `panic` — Function to trigger a panic +* `Panic` and `PanicResult` — Panic-related types +* `assert` — Macro for assertions + +== Using Prelude Items + +Since prelude items are automatically imported, you can use them directly without explicit imports: + +[source,cairo] +---- +fn example() { + // Option and Result are from the prelude + let some_value: Option = Some(42); + let result: Result = Ok(100); + + // Array and common traits are available + let mut arr = array![1, 2, 3]; + + // Integer types are available + let x: u32 = 10; + let y: i64 = -5; + + // assert is available + assert(x > 0, 'x must be positive'); +} +---- + +== Explicit Imports + +While prelude items are automatically available, you can still import them explicitly if desired: + +[source,cairo] +---- +use core::option::Option::{Some, None}; +use core::array::ArrayTrait; + +fn explicit_example() { + let value = Some(42); + let arr = array![1, 2, 3]; +} +---- + +This is functionally identical to using them without explicit imports, but may improve code clarity in some cases. + +== Edition-Specific Preludes + +Cairo uses edition-based preludes (e.g., `v2023_01`, `v2023_10`, `v2024_07`). +Different editions may include different items in the prelude. +The compiler automatically selects the appropriate prelude based on your crate's edition. + +== Related + +- xref:use.adoc[Use declarations] — Importing items explicitly +- xref:module.adoc[Modules] — Module system and namespaces From 2eaece49f562a012391b4970767cab3106b2d9bb Mon Sep 17 00:00:00 2001 From: Princetimix69 Date: Wed, 3 Jun 2026 09:53:53 +0800 Subject: [PATCH 2/2] docs: update prelude source references --- .../language_constructs/pages/prelude.adoc | 121 +++--------------- 1 file changed, 15 insertions(+), 106 deletions(-) diff --git a/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc b/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc index e49a31a03e3..f84eb78a534 100644 --- a/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc +++ b/docs/reference/src/components/cairo/modules/language_constructs/pages/prelude.adoc @@ -9,115 +9,24 @@ It is not possible to disable standard library prelude importing. This means that items from the prelude are always in scope without explicit imports, which is why you can use types like `Option`, `Result`, and common traits without importing them. -== Items Included in the Prelude +== Edition-based Preludes -The prelude includes commonly used types, traits, and functions that are essential for Cairo programming. -The following categories of items are automatically imported: +Cairo has five compiler editions that map to three prelude definitions. +The edition is set per crate via the `edition` field — typically in `Scarb.toml` for Scarb +projects, or in `cairo_project.toml` for non-Scarb setups (and via `CrateSettings` when +driving the compiler programmatically). -=== Basic Types +- `core::prelude::v2024_07` — the modern prelude, used by editions `v2024_07` and `v2025_12`. +- `core::prelude::v2023_10` — intermediate edition, used by editions `v2023_10` and `v2023_11`. +- `core::prelude::v2023_01` — the legacy prelude. -* `bool` — Boolean type -* `felt252` — Field element type (252-bit) -* `usize` — Unsigned size type -* Integer types: `u8`, `u16`, `u32`, `u64`, `u128`, `u256`, `i8`, `i16`, `i32`, `i64`, `i128` +Each successive prelude is more conservative, exporting only the most commonly needed items. -=== Collection Types +== Prelude Source Files -* `Array` and `ArrayTrait` — Dynamic array type and its methods -* `Span` and `SpanTrait` — Immutable view into arrays -* `ToSpanTrait` — Conversion to span -* `ByteArray` and `ByteArrayTrait` — Byte array type for string handling -* `Felt252DictTrait` — Dictionary with felt252 keys +To inspect the exact items exported by each edition, see these source files: -=== Option and Result Types - -* `Option`, `Some`, `None` — Optional value type and variants -* `OptionTrait` — Methods for working with options -* `Result`, `Ok`, `Err` — Result type for error handling and variants -* `ResultTrait` — Methods for working with results - -=== Common Traits - -* `Copy` — Types that can be copied by copying bits -* `Clone` — Types that can be explicitly cloned -* `Drop` — Types that can be safely dropped -* `Destruct` — Types that can be explicitly destructed -* `PanicDestruct` — Types that can be destructed during panic -* `Default` — Types with a default value -* `PartialEq` — Types that support equality comparison -* `PartialOrd` — Types that support ordering comparison -* `Into` and `TryInto` — Type conversion traits -* `Serde` — Serialization and deserialization - -=== Arithmetic Traits - -* `Add`, `Sub`, `Mul`, `Div`, `Rem` — Arithmetic operations -* `Neg` — Negation operation -* `Not` — Logical NOT operation -* `DivRem` — Combined division and remainder - -=== Other Types and Traits - -* `Box` and `BoxTrait` — Heap-allocated pointer type -* `Nullable` and `NullableTrait` — Nullable pointer type -* `NonZero` — Non-zero wrapper type -* `Iterator`, `IntoIterator`, `FromIterator` — Iterator traits -* `Deref` — Dereference trait -* `Felt252DictValue` — Values that can be stored in felt252 dictionaries - -=== Panic Functions - -* `panic` — Function to trigger a panic -* `Panic` and `PanicResult` — Panic-related types -* `assert` — Macro for assertions - -== Using Prelude Items - -Since prelude items are automatically imported, you can use them directly without explicit imports: - -[source,cairo] ----- -fn example() { - // Option and Result are from the prelude - let some_value: Option = Some(42); - let result: Result = Ok(100); - - // Array and common traits are available - let mut arr = array![1, 2, 3]; - - // Integer types are available - let x: u32 = 10; - let y: i64 = -5; - - // assert is available - assert(x > 0, 'x must be positive'); -} ----- - -== Explicit Imports - -While prelude items are automatically available, you can still import them explicitly if desired: - -[source,cairo] ----- -use core::option::Option::{Some, None}; -use core::array::ArrayTrait; - -fn explicit_example() { - let value = Some(42); - let arr = array![1, 2, 3]; -} ----- - -This is functionally identical to using them without explicit imports, but may improve code clarity in some cases. - -== Edition-Specific Preludes - -Cairo uses edition-based preludes (e.g., `v2023_01`, `v2023_10`, `v2024_07`). -Different editions may include different items in the prelude. -The compiler automatically selects the appropriate prelude based on your crate's edition. - -== Related - -- xref:use.adoc[Use declarations] — Importing items explicitly -- xref:module.adoc[Modules] — Module system and namespaces +- `corelib/src/prelude.cairo`. +- `corelib/src/prelude/v2024_07.cairo`. +- `corelib/src/prelude/v2023_10.cairo`. +- `corelib/src/prelude/v2023_01.cairo`.