يوم الانتخابات

البنى

البنى أنواع بيانات مخصصة تتيح لك تسمية عدة قيم مترابطة وتجميعها معًا في وحدة واحدة.

لتعريف بنية، استخدم الكلمة المفتاحية struct متبوعة باسم، ثم الأقواس المعقوفة التي تحتوي على الحقول بأسمائها وأنواعها:

#[derive(Drop)]
struct User {
    active: bool,
    username: ByteArray,
    email: ByteArray,
    sign_in_count: u64,
}

لإنشاء نسخة من struct، حدّد اسم struct واستخدم الأقواس المعقوفة مع أزواج المفتاح والقيمة للحقول.

let user = User {
   active: true, username: "someusername123", email: "someone@example.com", sign_in_count: 1
};

استخدم الترميز النقطي للوصول إلى حقول نسخة قابلة للتغيير من struct أو لتعديلها.

let mut user = User {
    active: true, username: "someusername123", email: "someone@example.com", sign_in_count: 1
};
user.email = "anotheremail@example.com";

الملكية

القيم في Cairo غير قابلة للتغيير، وهذا الثبات يضمن أنه حتى لو أشارت متغيرات كثيرة إلى القيمة نفسها، فإن القيمة ذاتها تبقى ثابتة دون تغيير. مالك المتغير هو الكود الذي يمكنه قراءة ذلك المتغير (وكتابته إن كان قابلًا للتغيير).

قواعد الملكية في Cairo:

1. لكل متغير في Cairo مالك.
2. لا يمكن أن يوجد أكثر من مالك واحد في الوقت نفسه.
3. عندما يخرج المالك من النطاق، يُدمَّر المتغير.

النطاق هو المدى داخل البرنامج الذي يكون فيه المتغير صالحًا.

fn main() {
                      // `x` is not valid here, it has not been declared yet
    let x: u32 = 3;   // `x` is declared, it is valid from this point forward
                      // do stuff with `x`

} // this scope ended here, `x` goes out of scope and is no longer valid

عندما يخرج المتغير من النطاق يُدمَّر، ما يضمن تحرير المورد المرتبط به تحريرًا صحيحًا. ويتحقق ذلك عبر تنفيذ سمة Drop أو اشتقاقها، وهي تُخبر المترجم بأنه يمكن تدمير النوع بأمان بمجرد انتهاء الحاجة إليه.

#[derive(Drop)]
struct A {}

fn main() {
    A {}; // this value can be destroyed after going out of scope
}

في الوقت الحالي، يمكن اشتقاق تنفيذ Drop لكل الأنواع، باستثناء القواميس (Felt252Dict) والأنواع التي تحتوي على قواميس.

يمكن أيضًا نقل القيمة، ويحدث ذلك عندما تُمرَّر قيمة إلى دالة أخرى، فيُدمَّر المتغير الأصلي الذي كان يشير إلى القيمة (فيصبح المتغير بلا فائدة)، ويُنشأ متغير جديد يحمل القيمة نفسها.

fn foo(num: u32) { 
    // do something with p
}

fn main() {
    let num: u32 = 10;
    foo(num);
    // ownership of `num` was moved into `foo` and is thus no longer valid in this scope
}

إرجاع القيم يعادل نقلها.

يوضح المثال التالي دالة تُرجع قيمة ما:

#[derive(Drop)]
struct A {}

fn main() {
    // main now owns a1
    let a1 = gives_ownership();

    // a2 comes into scope
    let a2 = A {};

    // a2 is moved into takes_and_gives_back, which also moves its return value into a3
    let a3 = takes_and_gives_back(a2);
} // Here, a3 and a1 go out of scope and are dropped. a2 was moved, so nothing happens.

// Moves its return value into the function that calls it
fn gives_ownership() -> A {
    let some_a = A {};
    some_a
}

// This function takes an instance some_a of A and returns it
fn takes_and_gives_back(some_a: A) -> A {
    some_a
}

ولأن المتغير يُدمَّر بعد نقله، يمنعنا المترجم من إعادة استخدامه بعد ذلك.

#[derive(Drop)]
struct Point {
    x: u128,
    y: u128,
}

fn foo(p: Point) { 
    // do something with p
}

fn main() {
    let p = Point { x: 5, y: 10 };
    foo(p);
    foo(p); // compiler error: Variable was previously moved.
}

في هذه الحالة، نحاول تمرير القيمة نفسها (بنية Point في المتغير p) إلى نداءي الدالة. بمجرد أن نمرّر المتغير إلى الدالة foo في المرة الأولى، يصبح المتغير غير قابل للاستخدام.

أحد الحلول هو اشتقاق سمة Copy على البنية، ما يغيّر ما يحدث عند تمرير متغير Copy إلى دالة: فلن ينقل القيمة بعد ذلك، بل ينشئ متغيرًا جديدًا يشير إلى القيمة نفسها. وهذه عملية بلا كلفة لأن المتغيرات تجريد من Cairo، والقيم دائمًا غير قابلة للتغيير.

لتنفيذ سمة Copy على نوعك، أضف التعليمة #[derive(Copy)] إلى تعريف النوع.

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

fn foo(p: Point) { 
    // do something with p
}

fn main() {
    let p = Point { x: 5, y: 10 };
    foo(p);
    foo(p); // this now works
}

المراجع واللقطات

يمتلك Cairo ميزتين لتمرير قيمة دون تدميرها أو نقلها، وهما references وsnapshots.

توفّر اللقطات "عرضًا" غير قابل للتغيير لقيمة في لحظة معينة، ما يتيح لك الاحتفاظ بملكية المتغير أثناء الوصول إلى حالته. أي تعديل على المتغير ينشئ خلية ذاكرة جديدة، فيبقى عرض اللقطة دون تغيير.

لإنشاء لقطة، ما عليك سوى وضع @ قبل المتغير.

// this function takes in a snapshot using `@` with the data-type
fn get_len(arr: @Array<u128>) -> u32 { // 
    arr.len()
}

fn foo(arr: Array<u128>) {
    arr.pop_front();
}

fn main() {
    let mut new_arr: Array<u128> = array![1, 2, 3, 4, 5, 6, 7, 8];
    let snapshot = @new_arr; // using `@` to create a snapshot of a variable
    let len = get_len(snapshot); // pass the snapshot as argument, retaining ownership
    foo(new_arr); // `new_arr` is still valid up until here and no further
}

لتحويل لقطة عائدة إلى متغير عادي، يمكنك استخدام عامل إلغاء اللقطة *، وهو عكس العامل @. ولا يمكن إلغاء لقطة إلا للأنواع التي تنفّذ سمة Copy.

fn square(n: @u32) -> u32 {
    let n = *n; // we desnap the value
    n * n
}

fn main() {
    let num: u32 = 10;
    let squared = square(@num); // we use `@` to create a snapshot
    println!("{} squared = {}", num, squared);
}

تتيح لك المراجع تمرير قيم قابلة للتغيير إلى الدوال وإرجاعها ضمنيًا، مع الحفاظ على الملكية في سياق الاستدعاء. ويمكن تحقيق ذلك باستخدام المُعدِّل ref، شرط أن يكون المتغير مصرَّحًا به كقابل للتغيير عبر الكلمة المفتاحية mut.

يمكننا تحديث مثال Point السابق لاستخدام مراجع قابلة للتغيير بدلًا من الاعتماد على سمة Copy، وسيظل يعمل.

#[derive(Drop)]
struct Point {
    x: u128,
    y: u128,
}

fn foo(ref p: Point) { 
    // we can now update the passed values and the changes
    // will be visible in the calling context
    p.x += 1;
}

fn main() {
    let mut p = Point { x: 5, y: 10 };
    foo(ref p);
    foo(ref p); // this now works even without the Copy trait
    println!("p.x = {}", p.x); // p.x = 7 
}