به Comprehensive Rust خوش آمدید 🦀

این یک دوره رایگان Rust است که توسط تیم اندروید در گوگل توسعه یافته است. این این دوره طیف کامل‌ای از Rust را پوشش میدهد, از مباحث پایه تا مباحث پیشرفته مانند جنریک و مدیریت خطاها.

آخرین نسخه از دوره را میتوان در https://google.github.io/comprehensive-rust/ پیدا کنید. اگر از جای دیگری میخوانید, لطفا برای بروز رسانی‌ها منبع اصلی را نیز بررسی کنید.

این دوره به زبان های دیگر موجود است. زبان مورد نظر خود را در گوشه سمت راست بالای صفحه انتخاب کنید یا صفحه ترجمه‌ها را برای فهرستی از تمام ترجمه‌های موجود را بررسی کنید.

این دوره نیز به عنوان یک PDF در دسترس است.

هدف از این دوره آموزش Rust به شماست. ما فرض می کنیم شما چیزی از درباره Rust نمی دانید :

• درک جامعی از syntax و زبان Rust به شما می دهد.
• شما را قادر می سازد تا برنامه های موجود را تغییر دهید و برنامه های جدید را در Rust بنویسید.
• اصطلاحات رایج Rust را به شما یاد می دهد.

ما چهار روز اول دوره را اصول Rust می نامیم.

با تکیه بر این، از شما دعوت می شود تا به یک یا چند موضوع تخصصی بپردازید:

• Android: یک دوره نیم روزه استفاده از Rust برای توسعه پلت فرم اندروید (AOSP). این شامل قابلیت همکاری با C، C ++و Java است.
• Chromium: یک دوره نیم روزه در مورد استفاده از Rust در مرورگرهای مبتنی بر Chromium. این شامل قابلیت همکاری با C ++ و نحوه قرار دادن جعبه های(crates) شخص ثالث در کروم است.
• Bare-metal: یک کلاس تمام روز در مورد استفاده از Rust برای توسعهbare-metal (تعریف شده). هم میکروکنترلرها و هم پردازنده های برنامه پوشش داده شده اند.
• همروندی: یک کلاس یک روزه در مورد concurrency در زبان Rust است. ما هر دو مورد concurrency کلاسیک (زمانبندی preemptively با استفاده از threadها و mutexها ) و async/await concurrency (multitasking مشارکتی) با استفاده از futures را پوشش خواهیم داد.

اهداف خارج از این دوره

زبان Rust, یک زبان بزرگ است و ما نمی‌توانیم طی چند روز همه موارد را پوشش دهیم.چندتا از اهداف خارج از این دوره عبارتند از:

• برای آموزش چگونه‌گی توسعه Macro ها: لطفا Chapter 19.5 in the Rust Book و Rust by Example را برسی کنید.

فرض می‌شود

این دوره فرض می‌کند که شما دانش برنامه‌نویسی دارید. Rust یک زبان استاتیک تایپ است و ما گاهی اوقات زبان Rust را با C و C++ مقایسه می کنیم تا رویکرد‌های Rust را بهتر توضیح دهیم.

اگر می‌دانید چگونه به زبانی با دینامیک تایپ مانند پایتون یا جاوا اسکریپت برنامه‌نویسی کنید می‌توانید به خوبی این روش را دنبال کنید.

اجرای دوره

این صفحه برای مدرس دوره است.

اینجا بخشی از پیشینه نحوه برگزاری دوره توسط گوگل به صورت درون سازمانی است.

ما معمولا کلاس‌ها را از ساعت ۱۰:۰۰ تا ۱۶:۰۰ برگزار می کنیم، با یک ساعت استراحت ناهار در میانه روز با این رویه ۲.۵ ساعت برای کلاس صبح و ۲.۵ ساعت برای کلاس بعدازظهر باقی می‌گذارد. توجه داشته باشید که این فقط یک توصیه است: شما می‌توانید ۳ ساعت از جلسه صبح را صرف تمرین بیشتر برای افراد کنید. نکته منفی این کار این است که با جلسه طولانی تر افراد بعد از ۶ ساعت کلاس در بعد از ظهر خیلی خسته میشوند.

قبل از اجرای دوره، شما می‌خواهید:

1. با مطالب دوره آشنا شوید. ما یادداشت های سخنرانی را برای کمک به برجسته کردن نکات کلیدی گنجانده‌ایم (لطفا با مشارکت بیشتر در یادداشت‌های سخنران به ما کمک کنید!). هنگام ارائه، باید مطمئن شوید که یادداشت‌های سخنران را در یک پنجره پاپ‌آپ باز کنید (روی پیوند با یک فلش کوچک در کنار «یادداشت‌های سخنران» کلیک کنید). به این ترتیب یک صفحه نمایش تمیز برای ارائه به کلاس خواهید داشت.

2. در مورد زمان‌بندی دوره تصمیم بگیرید. از آنجایی که دوره حداقل سه روز کامل طول می‌کشد، توصیه می‌کنیم که دوره را در دو هفته برنامه‌ریزی کنید. شرکت کنندگان در دوره گفته‌اند که داشتن فاصله‌ای در دوره مفید است، زیرا به آنها کمک می‌کند تا تمام اطلاعاتی را که به آنها می‌دهیم پردازش کنند.

3. یک اتاق بزرگ برای حضور شرکت کنندگان پیدا کنید. ما کلاسی با گنجایش ۱۵ الی ۲۵ نفر را پیشنهاد می‌کنیم. افراد در این تعداد می‌توانند به راحتی سوال بپرسند --- همچنین مدرس وقت کافی برای پاسخ‌ دادن به سوالات را نیز دارد. مطمئن شوید که اتاق مورد نظر میز برای شما و دانشجویان دارد: شما همگی نیاز دارید که بتونید بشنید و با لپتاپ های خود کار کنید. به خصوص شما به عنوان مدرس کلی live-coding انجام خواهید داد پس صرفا یک میز بدون جا برای لپتاپ برای شما مناسب نخواهد بود.

4. در روز برگزاری دوره، کمی زودتر به کلاس بیایید تا همه چیز را آماده کنید. ما توصیه می کنیم مستقیماً با استفاده از mdbook serveرا در لپتاپ خود اجرا کنید. (راهنمای نصب را ببنیید). با این کار عملکرد بدون تاخیر در هنگام تغییر صفحات تضمین می شود. استفاده از لپ تاپ همچنین به شما امکان می دهد اشتباهات تایپی ا در صورت مشاهده شما یا شرکت کنندگان در دوره اصلاح کنید.

5. بگذارید افراد خودشان یا در گروه های کوچک تمرینات را حل کنند. مابه طور معمول ۳۰ الی ۴۵ دقیقه را برای تمرینات در صبح و بعد‌از‌ظهر (از جمله زمان بررسی راه حل ها ) صرف می‌کنیم. حتما از افراد بخواهید که اگر گیر کرده‌اند یا چیزی وجود دارد که می‌توانید به آنها کمک کنید. وقتی که می‌بینید چندین نفر مشکل یکسانی دارند, خطاب به کلاس راه‌حل را پیشنهاد دهید؛ به عنوان مثال، با نشان دادن جایی که می‌توانند اطلاعات مربوطه را در کتابخانه استاندارد (standard library) پیدا کنند.

همش همین بود! در تدریس دوره موفق باشید! امیدواریم که برای شما هم به همان اندازه که برای ما لذت‌بخش بوده، لذت‌بخش باشد!

لطفاً بازخورد خود را ارائه دهید تا در آینده بتوانیم به بهبود دوره ادامه دهیم. ما دوست داریم بشنویم چه چیزی برای شما خوب بوده و چه چیزی می تواند بهتر شود. همینطور شما دانش‌آموزان نیز بسیار خوش آمدید برای ما بازخورد ارسال کنید !

مباحث دوره

این صفحه برای مدرس دوره است.

مبانی Rust

سه روز اول دوره را مبانی Rust تشکیل میدهند. این این سه روز با سرعت بالایی پیش می‌روند و ما موارد زیادی را پوشش می‌دهیم!

مباحث دوره:

• روز ۱ صبح (۲ ساعت و ۵ دقیقه با احتساب استراحت)

• روز ۱ بعد از ظهر (۲ ساعت و ۳۵ دقیقه،شامل وقت استراحت)

• روز ۲ صبح (۲ ساعت و ۱۰ دقیقه، شامل وقت استراحت)

• روز ۲ بعد از ظهر (۴ ساعت و ۵ دقیقه، شامل وقت استراحت)

• روز ۳ صبح (۲ ساعت و ۲۰ دقیقه، شامل وقت استراحت)

• روز ۳ بعدازظهر(۱ ساعت و ۵۵ دقیقه، شامل وقت اسراحت)

• روز ۴ صبح (۲ ساعت و ۴۰ دقیقه، شامل وقت استراحت)

• روز ۴ بعدازظهر (۲ ساعت و ۱۰ دقیقه، شامل وقت استراحت)

عمیق تر شدن

علاوه بر کلاس 4 روزه Rust Fundamentals، موضوعات تخصصی تری را نیز پوشش می دهیم:

Rust در اندروید

در Rust در اندروید توی دوره یک دوره نیم روزه در مورد استفاده از Rust برای توسعه پلتفرم اندروید عمیق می‌شیم. این شامل قابلیت تعامل با C، C++ و جاوا می‌شود.

شما نیاز دارید که یک نسخه از مخزن ASOP بگیرید, همچنین یک نسخه از مخزن دوره بگیرید و روی همون ماشین در مسیر src/android/مخزن ASOP قرار دهید. با این کار طمینان حاصل می‌کنید که سیستم build اندروید فایل های Android.bp را در src/android/ می‌بینید.

اطمینان حاصل کنید که adb sync با شبیه‌ساز یا دستگاه واقعی شما کار می‌کند و همه نمونه‌های Android را با استفاده از src/android/build_all.sh از قبل بسازید. اسکریپت را بخوانید تا دستوراتی را که اجرا می‌کند ببینید و مطمئن شوید که وقتی آنها را اجرا می‌کنید به درستی کار می‌کنند.

Rust در اندروید

عمیق Rust in Chromium یک دوره نیم روزه برای استفاده از Rust به عنوان بخشی از مرورگر Chromium است. این شامل استفاده از Rust در سیستم ساخت gn‍ Chromium، آوردن کتابخانه‌های شخص ثالث ("crates") و قابلیت همکاری ++C است.

شما باید بتوانید Chromium را بسازید --- یک اشکال زدایی، ساخت کامپوننت برای سرعت [توصیه می شود] (../chromium/setup.md) است، اما هر ساختی کار می کند. مطمئن شوید که می‌توانید مرورگر Chromium را که ساخته‌اید اجرا کنید.

Rust بر روی سخت افزار بدون سیستم عامل

دوره آموزشی Rust بر روی سخت افزار بدون سیستم عامل یک دوره یک روزه با تمرکز بر استفاده ازRust برای توسعه بر روی سخت افزار بدون سیستم عامل (embedded) است. این دوره هم میکروکنترلرها و هم پردازشگر هایی با کارایی خاص را پوشش می دهد.

برای قسمت میکروکنترلر، باید برد توسعه BBCmicro:bit v2 را خریداری کنید. همه باید تعدادی بسته را همانطور که در welcome page توضیح داده شده نصب کنند.

همزمانی در Rust

The Concurrency in Rust deep dive is a full day class on classical as well as async/await concurrency.

شما به یک crate جدید نیاز خواهید داشت و وابستگی ها دانلود و آماده استفاده باشند. سپس می‌توانید نمونه‌ها را در src/main.rs‍ کپی/پیست کنید تا با آنها آزمایش کنید:

cargo init concurrency
cd concurrency
cargo add tokio --features full
cargo run

مباحث دوره:

• صبح (۳ ساعت و ۲۰ دقیقه، شامل وقت اسراحت)

• بعدازظهر (۳ ساعت و ۲۰ دقیقه، شامل وقت استراحت)

فرمت

این دوره قرار است بسیار تعاملی باشد و توصیه می کنیم اجازه دهید حس کنجکاوی Rust را هدایت کنند!

میان‌برهای صفحه کلید

چندین میانبر صفحه کلید مفید در mdBook وجود دارد:

• Arrow-Left: به صفحه قبلی هدایت می‌کند.
• Arrow-Right: به صفحه بعدی هدایت می‌کند.
• Ctrl + Enter: Execute the code sample that has focus.
• s: نوار جستجو را فعال می‌کند.

ترجمه

این دوره توسط مجموعه ای از داوطلبان فوق العاده به زبان های دیگر ترجمه شده است:

• پرتغالی برزیلی توسط @rastringer, @hugojacob, @joaovicmendes و @henrif75.
• Chinese (Simplified) by @suetfei, @wnghl, @anlunx, @kongy, @noahdragon, @superwhd, @SketchK, and @nodmp.
• چینی (سنتی) توسط @hueich, @victorhsieh, @mingyc, @kuanhungchen و @johnathan79717.
• Japanese by @CoinEZ-JPN, @momotaro1105, @HidenoriKobayashi and @kantasv.
• کره ای توسط @keispace, @jiyongp و @jooyunghan.
• اسپانیایی توسط @deavid.
• Ukrainian by @git-user-cpp, @yaremam and @reta.

از انتخابگر زبان در گوشه بالا سمت راست برای جابه‌جایی بین زبان‌ها استفاده کنید.

ترجمه‌های ناقص

تعداد زیادی ترجمه در حال انجام وجود دارد. ما به آخرین ترجمه های به روز شده پیوند می دهیم:

• Arabic by @younies
• بنگالی توسط @raselmandol.
• Farsi by @Alix1383, @DannyRavi, @hamidrezakp, @javad-jafari and @moaminsharifi.
• فرانسویی توسط @KookaS و @vcaen.
• آلمانی توسط @Throvn و @ronaldfw.
• ایتالیایی توسط @Throvn و @ronaldfw.

فهرست کامل ترجمه‌ها با وضعیت فعلی‌شان نیز در آخرین به‌روزرسانی یا همگام‌سازی شده با آخرین نسخه دوره.

اگر می‌خواهید به این کار کمک کنید، لطفاً دستورالعمل‌های ما را برای چگونگی ادامه کار ببینید. ترجمه ها در issue tracker هماهنگ و کنترل می شوند.

استفاده از cargo

وقتی شروع به خواندن درباره Rust می کنید، خیلی سریع با Cargo ، ابزار استانداردی که در اکوسیستم Rust برای ساخت و اجرای برنامه های Rust استفاده می شود، آشنا خواهید شد. در اینجا می‌خواهیم یک مرور مختصر از در مورد کارگو و نحوه انطباق آن با اکوسیستم Rust و برنامه‌های آن را در این آموزش ارائه دهیم.

راهنمای نصب

لطفا دستورالعمل را دنبال کنید https://rustup.rs.

این کار به شما امکان استفاده از ابزار ساخت Cargo (cargo) و کامپایلر Rust (rustc) را می دهد. شما همچنین rustup را دریافت خواهید کرد، یک ابزار خط فرمان(CLI) که می توانید از آن برای نصب نسخه های مختلف کامپایلر استفاده کنید.

پس از نصب Rust، باید ویرایشگر یا IDE خود را برای کار با Rust پیکربندی کنید. اکثر ویرایشگرها این کار را با ارتباط گرفتن با rust-analyzer انجام می‌دهند، که قابلیت تکمیل خودکار و پرش به تعریف را برای VS Code، Emacs، Vim/Neovim و بسیاری دیگر فراهم می کند. همچنین یک IDE متفاوت به نام RustRover در دسترس است.

اکوسیستم Rust

اکوسیستم Rust از تعدادی ابزار تشکیل شده است که مهمترین آنها عبارتند از:

• rustc: کامپایلر Rust که فایل‌های .rs را به باینری و سایر فرمت‌های میانی تبدیل می‌کند.

• cargo: مدیر وابستگی Rust و build tool آن است. Cargo می داند که چگونه وابستگی ها را که معمولاً در https://crates.io میزبانی می شوند دانلود کند و هنگام ساخت پروژه آنها را به rustc منتقل می‌کند. Cargo همچنین دارای یک دستگاه تست داخلی است که برای اجرای unit test استفاده می شود.

• 'rustup': نصب کننده و به روز رسانی rustchain ابزار. این ابزار برای نصب و به روز رسانی "rustc" و "cargo" در هنگام انتشار نسخه های جدید Rust استفاده می شود. علاوه بر این، "rustup" همچنین می تواند اسناد را برای کتابخانه استاندارد دانلود کند. شما می توانید چندین نسخه از Rust را در یک زمان نصب کنید و "rustup" به شما اجازه می دهد تا در صورت نیاز بین انها تغییر دهید.

نمونه کد در این آموزش

برای این آموزش، بیشتر زبان Rust را از طریق مثال هایی که می توان از طریق مرورگر شما اجرا کرد، بررسی می کنیم. این کار راه اندازی را بسیار ساده تر می کند و تجربه ای ثابت را برای همه تضمین می کند.

نصب Cargo همچنان پیشنهاد می شود: چونکه انجام تمرینات را برای شما آسان تر می کند. در روز آخر، تمرین بزرگتری را انجام خواهیم داد که به شما نشان می دهد چگونه با وابستگی ها کار کنید و برای این کار شما به Cargo نیاز دارید.

بلوک های کد در این دوره کاملاً تعاملی(interactive) هستند:

fn main() {
    println!("Edit me!");
}

You can use Ctrl + Enter to execute the code when focus is in the text box.

اجرای کد به صورت لوکال با Cargo

اگر می خواهید کد را روی سیستم خود آزمایش کنید، ابتدا باید Rust را نصب کنید. این کار را با دنبال کردن instructions in the Rust Book انجام دهید. این باید به شما یک rustc و cargo کاربردی بدهد. در زمان نگارش، آخرین نسخه پایدار Rust دارای این version numberها است:

% rustc --version
rustc 1.69.0 (84c898d65 2023-04-16)
% cargo --version
cargo 1.69.0 (6e9a83356 2023-04-12)

شما همچنین می توانید از هر نسخه بعدی استفاده کنید، زیرا Rust سازگاری با نسخه های قبلی را حفظ می‌کند.

با این کار، این مراحل را دنبال کنید تا از یکی از مثال‌های این آموزش، یک باینری Rust بسازید:

1. روی دکمه "کپی در کلیپ بورد" در نمونه ای که می خواهید کپی کنید؛ کلیک کنید.

2. از cargo new exercise برای ایجاد دایرکتوری excerise/ جدید برای کد خود استفاده کنید:

   $ cargo new exercise
        Created binary (application) `exercise` package
   

3. به exercise/ بروید و از cargo run برای ساخت و اجرای باینری خود استفاده کنید:

   $ cd exercise
   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.75s
        Running `target/debug/exercise`
   Hello, world!
   

4. کد صفحه دیگر را در src/main.rs با کد خود جایگزین کنید. برای مثال، با استفاده از مثال در صفحه قبل، src/main.rs را شبیه به آن کنید.

   fn main() {
       println!("Edit me!");
   }

5. برای ساختن و اجرای باینری به روز شده خود از cargo run استفاده کنید:

   $ cargo run
      Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
       Finished dev [unoptimized + debuginfo] target(s) in 0.24s
        Running `target/debug/exercise`
   Edit me!
   

6. از cargo check برای بررسی سریع پروژه خود برای خطاها استفاده کنید، از cargo build برای کامپایل، بدون اجرای آن استفاده کنید. خروجی را در target/debug/ برای ساخت اشکال زدایی معمولی خواهید یافت. برای تولید نسخه بهینه سازی شده در target/release/ از cargo build --release استفاده کنید.

7. با ویرایش Cargo.toml می‌توانید وابستگی‌هایی برای پروژه خود اضافه کنید. هنگامی که دستورات cargo را اجرا می کنید، به طور خودکار وابستگی های مورد نیاز را برای شما دانلود و کامپایل می‌کند.

به روز اول خوش آمدید

این اولین روز از مبانی Rust است. ما امروز بخش‌های فابل توجه‌ای را پوشش خواهیم داد:

• سینتکس‌های مقدماتی: متغیرها, تایپ‌های عددی و تایپ‌های مرکب, enums, structs, مراجع, توابع, و متدها.
• Types and type inference.
• ساختارهای جریان کنترل: حلقه ها، شرط ها و غیره.
• تایپ های تعریف شده توسط کاربر: ساختارها و enums.
• تطابق الگو: تجزیه و تحلیل enums, structs و آرایه‌ها.

برنامه زمانی

با احتساب 10 دقیقه استراحت، این جلسه باید حدود 2 ساعت و 5 دقیقه طول بکشد. آن شامل:

سلام, دنیا

این بخش ۱۵ دقیقه زمان می برد. این بخش شامل:

زبان Rust چیست؟

‏Rust یک زبان برنامه‌نویسی جدید است که نسخه 1.0 آن در سال 2015 منتشر شد:

• زبان Rust, یک زبان کامپایل شده ایستا است که نقشی مشابه C++ دارد
  • rustc از LLVM به عنوان بک‌اند خود استفاده می‌کند.
• راست از بسیاری از بسترها و معماری‌ها پشتیبانی می کند :
  • x86, ARM, WebAssembly, ...
  • Linux, Mac, Windows, ...
• زبان Rust برای طیف گسترده‌ای از دستگاه‌ها استفاده می‌شود:
  • میان‌افزار (firmware) و بوت‌لودرها (boot loaders)
  • نمایشگر‌های هوشمند,
  • تلفن‌های همراه,
  • رایانه‌های رومیزی,
  • سرورها.

مزیت‌های زبان Rust

برخی از نقاط قوت منحصر به فرد زبان Rust:

• ایمنی حافظه زمان کامپایل - کل کلاس های باگ حافظه در زمان کامپایل جلوگیری می شود

  • هیچ متغیر مقدار‌دهی نشده‌ای (uninitialized) وجود ندارد.
  • هیچ آزادسازی دوباره‌ای وجود ندارد.
  • هیچ استفاده‌ای پس از آزادسازی وجود ندارد.
  • هیچ اشاره‌گر NULL وجود ندارد.
  • هیچ موتکس قفل شدهِ فراموش شده‌ای وجود ندارد.
  • هیچ وضعیت رقابتی (data races) بین رشته‌ها وجود ندارد.
  • تکرارکننده‌ها (iterators) هیچگاه نامعتبر نمی‌شوند..

• بدون رفتار زمان اجرا تعریف نشده - کاری که دستور Rust انجام می دهد هرگز نامشخص باقی نمی ماند

  • دسترسی به آرایه با بررسی محدوده چک می‌شود.
  • سرریز عدد صحیح تعریف شده است (پانیک یا wrap-around).

• ویژگی های زبان مدرن - به اندازه زبان های سطح بالاتر گویا و ارگونومیک است

  • Enumها و تطابق الگوها.
  • جنریک‌ها.
  • FFI بدون سربار.
  • انتزاع‌هایی بدون هزینه.
  • خطاهای کامپایل عالیست.
  • مدیر وابستگی درون-ساختی.
  • پشتیبانی درون-ساختی از تست نویسی.
  • پشتیبانی عالی از LSP‌.

Playground

Rust Playground یک راه آسان برای اجرای برنامه های Rust کوتاه ارائه می دهد و پایه ای برای مثال ها و تمرین های این دوره است. برنامه "Hello-world" را که با آن شروع می شود اجرا کنید. دارای چند ویژگی مفید است:

• در زیر "ابزارها"، از گزینه "rustfmt" برای قالب بندی کد خود به روش "استاندارد" استفاده کنید.

• Rust دارای دو "نمایه" اصلی برای تولید کد است: Debug (بررسی های زمان اجرا اضافی، بهینه سازی کمتر) و Release (بررسی های زمان اجرا کمتر، بهینه سازی زیاد). اینها در قسمت «اشکال‌زدایی» در بالا قابل دسترسی هستند.

• اگر علاقه مند هستید، از "ASM" در زیر "..." برای دیدن کد اسمبلی تولید شده استفاده کنید.

تایپ‌ها و مقادیر

این بخش باید حدود ۴۰ دقیقه طول بکشد. آن شامل:

سلام, دنیا

بیایید به ساده ترین برنامه Rust ممکن یعنی یک برنامه Hello World کلاسیک بپردازیم:

fn main() {
    println!("سلام 🌍!");
}

آنچه شما می‌بینید:

• توابع با fn معرفی می‌شوند.
• بلوک‌ها با پرانتزهای باز و بسته مانند C و C++ محدود می‌شوند.
• تابع main نقطه ورود برنامه است.
• زبان Rust دارای ماکروهای hygienic است، println! یک نمونه از این است.
• رشته‌های Rust دارای انکودینگ UTF-8 هستند و می‌توانند شامل هر کاراکتر یونیکد باشند.

متغیرها

زبان Rust از طریق سیستم تایپ استاتیک, ایمینی نوع را فراهم می‌کند. به صورت پیشفرض تعریف متغییر ها از نوع «غیر قابل تغییر» (immutable) است:

fn main() {
    let x: i32 = 10;
    println!("x: {x}");
    // x = 20;
    // println!("x: {x}");
}

مقادیر

در اینجا چند نوع پایه داخلی و نحو برای مقادیر تحت اللفظی هر نوع آورده شده است.

اندازه تایپ‌ها به شرح زیر است:

• iN, uNو fN به اندازه N حافظه اشغال می‌کنند.,
• isize و usize به اندازه یک اشاره‌گر حافظه اشغال می‌کنند,
• char به اندازه 32 بیت حافظه اشغال می‌کنند.,
• bool به اندازه 8 بیت حافظه اشغال می‌کنند.

عملگرهای ریاضی

fn interproduct(a: i32, b: i32, c: i32) -> i32 {
    return a * b + b * c + c * a;
}

fn main() {
    println!("result: {}", interproduct(120, 100, 248));
}

تعیین تایپ ضمنی

زبان Rust برای تعیین نوع متغیر به نحوه استفاده از آن نگاه می‌کند:

fn takes_u32(x: u32) {
    println!("u32: {x}");
}

fn takes_i8(y: i8) {
    println!("i8: {y}");
}

fn main() {
    let x = 10;
    let y = 20;

    takes_u32(x);
    takes_i8(y);
    // takes_u32(y);
}

fn main() {
    let x = 3.14;
    let y = 20;
    assert_eq!(x, y);
    // ERROR: no implementation for `{float} == {integer}`
}

تمرین: دنباله فیبوناچی

دنباله فیبوناچی با «[0،1]» شروع می شود. برای n>1، عدد فیبوناچی n به صورت بازگشتی به عنوان مجموع اعداد فیبوناچی n-1 و n-2 محاسبه می شود.

یک تابع fib(n) بنویسید که عدد فیبوناچی n را محاسبه کند. چه زمانی این عملکرد panic می شود؟

fn fib(n: u32) -> u32 {
    if n < 2 {
        //حالت پایه
        todo!("این را پیاده‌سازی کن")
    } else {
        // حالت بازگشتی
        todo!("این را پیاده‌سازی کن")
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

راه‌حل

fn fib(n: u32) -> u32 {
    if n < 2 {
        return n;
    } else {
        return fib(n - 1) + fib(n - 2);
    }
}

fn main() {
    let n = 20;
    println!("fib({n}) = {}", fib(n));
}

مبانی پایه کنترل جریان

این بخش باید حدود ۴۰ دقیقه طول بکشد. آن شامل:

عبارات if

شما عبارت if رو به مانند دیگر زبان‌ها استفاده می‌کنید:

fn main() {
    let x = 10;
    if x == 0 {
        println!("صفر!");
    } else if x < 100 {
        println!("biggish");
    } else {
        println!("huge");
    }
}

در کنار این موضوع, می‌توانید از if به عنوان یک عبارت با قابلیت بازگشت مقدار هم استفاده کنید. آخرین عبارت توی هر بلاک if اون مقدار و نوع بازگشتی است:

fn main() {
    let x = 10;
    let size = if x < 20 { "کوچک" } else { "بزرگ" };
    println!("اندازه عدد: {}", size);
}

حلقه‌ها

سه کلمه کلیدی حلقه ای در Rust وجود دارد: "while"، "loop" و "for":

حلقه‌های while

کلمه‌کلیدیwhile بسیار شبیه به سایر زبان‌ها عمل می‌کند.

fn main() {
    let mut x = 200;
    while x >= 10 {
        x = x / 2;
    }
    println!("خروجی x: {x}");
}

for

حلقه for در محدوده‌ای از مقادیر یا موارد موجود در یک مجموعه تکرار می‌شود:

fn main() {
    for x in 1..5 {
        println!("x: {x}");
    }

    for elem in [1, 2, 3, 4, 5] {
        println!("elem: {elem}");
    }
}

loop

loop برای همیشه، تا زمانی که یک «break» ایجاد شود، حلقه می‌شود.

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        println!("{i}");
        if i > 100 {
            break;
        }
    }
}

break و continue

اگر می‌خواهید بلافاصله تکرار بعدی را شروع کنید، از continue استفاده کنید.

If you want to exit any kind of loop early, use break. With loop, this can take an optional expression that becomes the value of the loop expression.

fn main() {
    let mut i = 0;
    loop {
        i += 1;
        if i > 5 {
            break;
        }
        if i % 2 == 0 {
            continue;
        }
        println!("{}", i);
    }
}

برچسب‌ها

کلیدواژه‌های continue و break هر دو می‌توانند به صورت اختیاری یک آرگومان برچسب (label) بگیرند که میتوان برای خروج از حلقه‌های تو در تو استفاده می‌کرد:

fn main() {
    let s = [[5, 6, 7], [8, 9, 10], [21, 15, 32]];
    let mut elements_searched = 0;
    let target_value = 10;
    'outer: for i in 0..=2 {
        for j in 0..=2 {
            elements_searched += 1;
            if s[i][j] == target_value {
                break 'outer;
            }
        }
    }
    print!("elements searched: {elements_searched}");
}

بلوک‌ها و محدوده‌ها

بلوک‌ها

یک بلوک در Rust حاوی دنباله ای از عبارات است که با پرانتزهای «{}» محصور شده است. هر بلوک دارای یک مقدار و یک نوع است که آخرین عبارت بلوک است:

fn main() {
    let z = 13;
    let x = {
        let y = 10;
        println!("y: {y}");
        z - y
    };
    println!("x: {x}");
}

اگر آخرین عبارت با ; پایان یابد، مقدار و نوع بازگشتی () است.

محدوده‌ها و سایه‌گذاری

‏محدوده (scope) یک متغیر محدود به بلاک محاصره‌کننده آن است.

شما می توانید متغیرها را سایه بزنید، هم آنهایی که از اسکوپ‌های بیرونی هستند و هم متغیرهایی که از اسکوپ یکسان هستند:

fn main() {
    let a = 10;
    println!("before: {a}");
    {
        let a = "hello";
        println!("inner scope: {a}");

        let a = true;
        println!("shadowed in inner scope: {a}");
    }

    println!("after: {a}");
}

توابع

fn gcd(a: u32, b: u32) -> u32 {
    if b > 0 {
        gcd(b, a % b)
    } else {
        a
    }
}

fn main() {
    println!("gcd: {}", gcd(143, 52));
}

ماکروها

ماکروها در طول کامپایل به کد Rust گسترش می‌یابند و می‌توانند تعداد متغیری از آرگومان‌ها را بگیرند. آنها در پایان با یک «!» متمایز می شوند. کتابخانه استاندارد Rust شامل مجموعه ای از ماکروهای مفید است.

• println!(format, ..) یک خط را در خروجی استاندارد چاپ می کند و قالب بندی شرح داده شده در [std::fmt] (https://doc.rust-lang.org/std/fmt/index.html) را اعمال می کند. .
• format!(format, ..) درست مانند println! کار می کند، اما نتیجه را به صورت یک رشته برمی گرداند.
• dbg!(expression) مقدار عبارت را ثبت کرده و آن را برمی گرداند.
• todo!() مقداری از کد را به عنوان هنوز پیاده‌سازی نشده علامت‌گذاری می‌کند. panic می کند.
• unreachable!() مقداری از کد را غیرقابل دسترسی علامت گذاری می کند. اگر اعدام شود وحشت می کند.

fn factorial(n: u32) -> u32 {
    let mut product = 1;
    for i in 1..=n {
        product *= dbg!(i);
    }
    product
}

fn fizzbuzz(n: u32) -> u32 {
    todo!()
}

fn main() {
    let n = 4;
    println!("{n}! = {}", factorial(n));
}

تمرین: دنباله Collatz

The Collatz Sequence is defined as follows, for an arbitrary n₁ greater than zero:

• اگر n_i = ۱ باشد، دنباله (sequence) در n_i پایان می‌یابد.
• اگر n_i زوج باشد، آنگاه n_i+۱ = n_i/۲.
• اگر n_i فرد باشد، آنگاه n_i+۱ = ۳ * n_i + ۱.

به عنوان مثال، با شروع از n_i = ۳:

• ۳ فرد است، پس n₂ = ۳ * ۳ + ۱ = 10;
• ۱۰ زوج است، پس n₃ = ۱۰ / ۲ = ۵;
• ۵ فرد است، پس n₄ = ۳ * ۵ + ۱ = 16;
• ۱۶ زوج است، پس n₅ = ۱۶ / ۲ = 8;
• ۸ زوج است، پس n₆ = ۸ / ۲ = 4;
• ۴ زوج است، پس n₇ = ۴ / ۲ = ۲;
• ۲ زوج است، پس n_۸ = ۱; و
• دنباله به پایان می‌رسد.

یک تابع بنویسید تا طول دنباله Collatz برای یک n اولیه داده شده را محاسبه کند.

/// Determine the length of the collatz sequence beginning at `n`.
fn collatz_length(mut n: i32) -> u32 {
  todo!("این را پیاده‌سازی کن")
}

fn main() {
  todo!("این را پیاده‌سازی کن")
}

راه‌حل

/// Determine the length of the collatz sequence beginning at `n`.
fn collatz_length(mut n: i32) -> u32 {
    let mut len = 1;
    while n > 1 {
        n = if n % 2 == 0 { n / 2 } else { 3 * n + 1 };
        len += 1;
    }
    len
}

#[test]
fn test_collatz_length() {
    assert_eq!(collatz_length(11), 15);
}

fn main() {
    println!("Length: {}", collatz_length(11));
}

خوش آمد

با احتساب 10 دقیقه استراحت، این جلسه باید حدود 2 ساعت و 35 دقیقه طول بکشد. آن شامل:

تاپل ها و آرایه ها

این بخش باید حدود 35 دقیقه طول بکشد. این شامل:

آرایه‌ها

fn main() {
    let mut a: [i8; 10] = [42; 10];
    a[5] = 0;
    println!("a: {a:?}");
}

تاپل‌ها

fn main() {
    let t: (i8, bool) = (7, true);
    println!("t.0: {}", t.0);
    println!("t.1: {}", t.1);
}

تکرار ارایه

عبارت for از تکرار روی آرایه ها (اما نه تاپل ها) پشتیبانی می کند.

fn main() {
    let primes = [2, 3, 5, 7, 11, 13, 17, 19];
    for prime in primes {
        for i in 2..prime {
            assert_ne!(prime % i, 0);
        }
    }
}

الگو‌ها و ضدِ ساختارها

هنگام کار با تاپل ها و سایر مقادیر ساختاریافته، معمول است که بخواهید مقادیر داخلی را در متغیرهای محلی استخراج کنید. این را می توان به صورت دستی با دسترسی مستقیم به مقادیر داخلی انجام داد:

fn print_tuple(tuple: (i32, i32)) {
    let left = tuple.0;
    let right = tuple.1;
    println!("left: {left}, right: {right}");
}

با این حال، Rust همچنین از استفاده از تطبیق الگو برای تخریب یک مقدار بزرگتر در بخش های تشکیل دهنده آن پشتیبانی می کند:

fn print_tuple(tuple: (i32, i32)) {
    let (left, right) = tuple;
    println!("left: {left}, right: {right}");
}

تمرین: آرایه‌های تو در تو

آرایه ها می توانند آرایه های دیگری نیز داشته باشند:

#![allow(unused)]
fn main() {
let array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
}

نوع این متغیر چیست؟

از آرایه‌ای مشابه مثال بالا برای نوشتن تابع transpose استفاده کنید که یک ماتریس را جابجا می‌کند (ردیف‌ها را به ستون‌ها تبدیل می‌کند):

کد زیر را در https://play.rust-lang.org/ کپی کرده و توابع را پیاده‌سازی کنید:

// TODO: این را زمانی که پیاده‌سازی‌تان تمام شد حذف کنید.
#![allow(unused_variables, dead_code)]

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    unimplemented!()
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], ‏// <-- این کامنت باعث می‌شود rustfmt یک خط جدید اضافه کند.
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("matrix: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("جابجا شده است: {:#?}", transposed);
}

راه‌حل

fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {
    let mut result = [[0; 3]; 3];
    for i in 0..3 {
        for j in 0..3 {
            result[j][i] = matrix[i][j];
        }
    }
    result
}

#[test]
fn test_transpose() {
    let matrix = [
        [101, 102, 103], //
        [201, 202, 203],
        [301, 302, 303],
    ];
    let transposed = transpose(matrix);
    assert_eq!(
        transposed,
        [
            [101, 201, 301], //
            [102, 202, 302],
            [103, 203, 303],
        ]
    );
}

fn main() {
    let matrix = [
        [101, 102, 103], ‏// <-- این کامنت باعث می‌شود rustfmt یک خط جدید اضافه کند.
        [201, 202, 203],
        [301, 302, 303],
    ];

    println!("matrix: {:#?}", matrix);
    let transposed = transpose(matrix);
    println!("جابجا شده است: {:#?}", transposed);
}

مراجع

این بخش باید حدود ۵۵ دقیقه طول بکشد. آن شامل:

مراجع اشتراکی

A reference provides a way to access another value without taking ownership of the value, and is also called "borrowing". Shared references are read-only, and the referenced data cannot change.

fn main() {
    let a = 'A';
    let b = 'B';
    let mut r: &char = &a;
    println!("r: {}", *r);
    r = &b;
    println!("r: {}", *r);
}

یک مرجع مشترک به یک نوع T دارای نوع &T است. یک مقدار مرجع با عملگر & ساخته می شود. عملگر * یک مرجع را "ارجاع مجدد" می کند و مقدار آن را به دست می دهد.

راست بطور استاتیک مراجع تعلیق شده (dangling) را ممنوع می‌کند:

fn x_axis(x: &i32) -> &(i32, i32) {
    let point = (*x, 0);
    return &point;
}

مراجع انحصاری

مراجع انحصاری، همچنین به عنوان مراجع قابل تغییر شناخته می شوند، اجازه می دهند مقداری را که به آن ارجاع می دهند تغییر دهند. آنها نوع mut &T دارند.

fn main() {
    let mut point = (1, 2);
    let x_coord = &mut point.0;
    *x_coord = 20;
    println!("point: {point:?}");
}

برش‌ها

یک برش به شما امکان می‌دهد نما (view) از یک مجموعه بزرگتر داشته باشید:

fn main() {
    let mut a: [i32; 6] = [10, 20, 30, 40, 50, 60];
    println!("a: {a:?}");

    let s: &[i32] = &a[2..4];

    println!("s: {s:?}");
}

• برش‌ها داده‌ها را از نوع برش‌شده قرض می‌گیرند.
• پرسش: اگر a[3] را درست قبل از چاپ s تغییر دهید چه اتفاقی می‌افتد؟

رشته‌ها

حالا می‌توانیم دو نوع رشته‌ای را در راست درک کنیم:

• str& تکه‌ای از بایت‌های رمزگذاری‌شده UTF-8، شبیه به [u8]& است.
• String is an owned buffer of UTF-8 encoded bytes, similar to Vec<T>.

fn main() {
    let s1: &str = "دنیا";
    println!("s1: {s1}");

    let mut s2: String = String::from("سلام");
    println!("s2: {s2}");
    s2.push_str(s1);
    println!("s2: {s2}");

    let s3: &str = &s2[s2.len() - s1.len()..];
    println!("s3: {s3}");
}

تمرین: هندسه

ما چند توابع کاربردی برای هندسه سه بعدی ایجاد خواهیم کرد که نقطه ای را به عنوان [f64;3] نشان می دهد. تعیین امضاهای عملکرد به عهده شماست.

// اندازه یک بردار را با جمع مربعات مختصات آن محاسبه کنید
// و سپس جذر آن را بگیرید. از متد `sqrt()` برای محاسبه جذر استفاده کنید، مثل `v.sqrt()`.


fn magnitude(...) -> f64 {
    todo!()
}

// یک بردار را با محاسبه اندازه‌ی آن و تقسیم تمام مختصات آن
// بر آن اندازه، نرمال‌سازی کنید.


fn normalize(...) {
    todo!()
}

// از `main` زیر برای تست کار خود استفاده کنید.

fn main() {
    println!("اندازه‌ی یک بردار واحد: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("اندازه‌ی {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("اندازه‌ی {v:?} پس از نرمال‌سازی: {}", magnitude(&v));
}

راه‌حل

/// اندازه‌ی بردار داده شده را محاسبه کنید.
fn magnitude(vector: &[f64; 3]) -> f64 {
    let mut mag_squared = 0.0;
    for coord in vector {
        mag_squared += coord * coord;
    }
    mag_squared.sqrt()
}

/// اندازه‌ی بردار را به 1.0 تغییر دهید بدون اینکه جهت آن تغییر کند.
fn normalize(vector: &mut [f64; 3]) {
    let mag = magnitude(vector);
    for item in vector {
        *item /= mag;
    }
}

fn main() {
    println!("اندازه‌ی یک بردار واحد: {}", magnitude(&[0.0, 1.0, 0.0]));

    let mut v = [1.0, 2.0, 9.0];
    println!("اندازه‌ی {v:?}: {}", magnitude(&v));
    normalize(&mut v);
    println!("اندازه‌ی {v:?} پس از نرمال‌سازی: {}", magnitude(&v));
}

تایپ‌های تعریف شده توسط کاربر

این بخش حدود ۵۰ دقیقه طول خواهد کشید. شامل موارد زیر است:

ساختارهای نام‌دار

‏مانند C و C++، زبان Rust از ساختارهای سفارشی پشتیبانی می‌کند:

struct Person {
    name: String,
    age: u8,
}

fn describe(person: &Person) {
    println!(‏"{} {} ساله است", person.name, person.age);
}

fn main() {
    let mut peter = Person { name: String::from("پیتر"), age: 27 };
    describe(&peter);

    peter.age = 28;
    describe(&peter);

    let name = String::from("ایوری");
    let age = 39;
    let avery = Person { name, age };
    describe(&avery);

    let jackie = Person { name: String::from("جکی"), ..avery };
    describe(&jackie);
}

ساختار‌ تاپل‌ها

اگر نام فیلدها بی‌اهمیت هستند، می‌توانید از ساختار tuple استفاده کنید:

struct Point(i32, i32);

fn main() {
    let p = Point(17, 23);
    println!("({}, {})", p.0, p.1);
}

این اغلب برایsingle-field wrapper (که newtypes نامیده می‌شوند) استفاده می‌شود:

struct PoundsOfForce(f64);
struct Newtons(f64);

fn compute_thruster_force() -> PoundsOfForce {
    todo!("از یک دانشمند حوزه موشک در ناسا بپرس")
}

fn set_thruster_force(force: Newtons) {
    // ...
}

fn main() {
    let force = compute_thruster_force();
    set_thruster_force(force);
}

Enums

کلمه کلیدی enum اجازه ایجاد نوع داده‌ای را می دهد که دارای چندین گونه مختلف است:

#[derive(Debug)]
enum Direction {
    Left,
    Right,
}

#[derive(Debug)]
enum PlayerMove {
    Pass,                        // Simple variant
    Run(Direction),              // Tuple variant
    Teleport { x: u32, y: u32 }, // Struct variant
}

fn main() {
    let m: PlayerMove = PlayerMove::Run(Direction::Left);
    println!("در این پیچ: {:?}", m);
}

const

Constants are evaluated at compile time and their values are inlined wherever they are used:

const DIGEST_SIZE: usize = 3;
const ZERO: Option<u8> = Some(42);

fn compute_digest(text: &str) -> [u8; DIGEST_SIZE] {
    let mut digest = [ZERO.unwrap_or(0); DIGEST_SIZE];
    for (idx, &b) in text.as_bytes().iter().enumerate() {
        digest[idx % DIGEST_SIZE] = digest[idx % DIGEST_SIZE].wrapping_add(b);
    }
    digest
}

fn main() {
    let digest = compute_digest("Hello");
    println!("digest: {digest:?}");
}

طبق کتاب Rust RFC، این موارد هنگام استفاده درج می شوند.

فقط توابعی که با const علامت گذاری شده اند می توانند در زمان کامپایل برای تولید مقادیر const فراخوانی شوند. با این حال، توابع const را می توان در زمان اجرا فراخوانی کرد (بر خلاف تعریف متغییری ثابت)

static

متغیرهای ایستا در طول عمر کل اجرای برنامه خواهند ماند و بنابراین منتقل نمی‌شوند:

static BANNER: &str = "به RustOS 3.14 خوش آمدید";

fn main() {
    println!("{BANNER}");
}

As noted in the Rust RFC Book, these are not inlined upon use and have an actual associated memory location. This is useful for unsafe and embedded code, and the variable lives through the entirety of the program execution. When a globally-scoped value does not have a reason to need object identity, const is generally preferred.

نام‌های مستعار تایپ

تایپ alias، نامی برای نوع دیگر ایجاد می کند. این دو نوع را می توان به جای هم استفاده کرد.

enum CarryableConcreteItem {
    Left,
    Right,
}

type Item = CarryableConcreteItem;

// Aliases are more useful with long, complex types:
use std::cell::RefCell;
use std::sync::{Arc, RwLock};
type PlayerInventory = RwLock<Vec<Arc<RefCell<Item>>>>;

تمرین: رویدادهای آسانسور

ما یک ساختار داده برای نمایش یک رویداد در یک سیستم کنترل آسانسور ایجاد خواهیم کرد. این به شما بستگی دارد که انواع و عملکردها را برای ساخت رویدادهای مختلف تعریف کنید. از #[derive(Debug)] استفاده کنید تا اجازه دهید انواع با {:?} قالببندی شوند.

این تمرین فقط به ایجاد و پر کردن ساختارهای داده نیاز دارد تا main بدون خطا اجرا شود. بخش بعدی این دوره دریافت داده‌ها از این ساختارها را پوشش می‌دهد.

#[derive(Debug)]
/// An event in the elevator system that the controller must react to.
enum Event {
    // TODO: add required variants
}

/// A direction of travel.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// The car has arrived on the given floor.
fn car_arrived(floor: i32) -> Event {
    todo!()
}

/// The car doors have opened.
fn car_door_opened() -> Event {
    todo!()
}

/// The car doors have closed.
fn car_door_closed() -> Event {
    todo!()
}

/// A directional button was pressed in an elevator lobby on the given floor.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    todo!()
}

/// A floor button was pressed in the elevator car.
fn car_floor_button_pressed(floor: i32) -> Event {
    todo!()
}

fn main() {
    println!(
        "A ground floor passenger has pressed the up button: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("ماشین به طبقه همکف رسیده است: {:?}", car_arrived(0));
    println!("در ماشین باز شد: {:?}", car_door_opened());
    println!(
        "یک مسافر دکمه طبقه 3 را فشار داده است: {:?}",
        car_floor_button_pressed(3)
    );
    println!("در ماشین بسته شد: {:?}", car_door_closed());
    println!("ماشین به طبقه ۳ رسیده است: {:?}", car_arrived(3));
}

راه‌حل

#[derive(Debug)]
/// An event in the elevator system that the controller must react to.
enum Event {
    /// A button was pressed.
    ButtonPressed(Button),

    /// The car has arrived at the given floor.
    CarArrived(Floor),

    /// The car's doors have opened.
    CarDoorOpened,

    /// The car's doors have closed.
    CarDoorClosed,
}

/// A floor is represented as an integer.
type Floor = i32;

/// A direction of travel.
#[derive(Debug)]
enum Direction {
    Up,
    Down,
}

/// A user-accessible button.
#[derive(Debug)]
enum Button {
    /// A button in the elevator lobby on the given floor.
    LobbyCall(Direction, Floor),

    /// A floor button within the car.
    CarFloor(Floor),
}

/// The car has arrived on the given floor.
fn car_arrived(floor: i32) -> Event {
    Event::CarArrived(floor)
}

/// The car doors have opened.
fn car_door_opened() -> Event {
    Event::CarDoorOpened
}

/// The car doors have closed.
fn car_door_closed() -> Event {
    Event::CarDoorClosed
}

/// A directional button was pressed in an elevator lobby on the given floor.
fn lobby_call_button_pressed(floor: i32, dir: Direction) -> Event {
    Event::ButtonPressed(Button::LobbyCall(dir, floor))
}

/// A floor button was pressed in the elevator car.
fn car_floor_button_pressed(floor: i32) -> Event {
    Event::ButtonPressed(Button::CarFloor(floor))
}

fn main() {
    println!(
        "A ground floor passenger has pressed the up button: {:?}",
        lobby_call_button_pressed(0, Direction::Up)
    );
    println!("ماشین به طبقه همکف رسیده است: {:?}", car_arrived(0));
    println!("در ماشین باز شد: {:?}", car_door_opened());
    println!(
        "یک مسافر دکمه طبقه 3 را فشار داده است: {:?}",
        car_floor_button_pressed(3)
    );
    println!("در ماشین بسته شد: {:?}", car_door_closed());
    println!("ماشین به طبقه ۳ رسیده است: {:?}", car_arrived(3));
}

به روز ۲ خوش آمدید

اکنون که مقدار زیادی از Rust را دیده ایم، امروز بر روی سیستم تایپ Rust تمرکز خواهیم کرد:

• تطبیق الگو: استخراج داده از ساختارها.
• متد‌ها: ارتباط توابع با تایپ ها.
• Traits: رفتارهایی که توسط چندین تایپ مشترک هستند.
• Generics: پارامتری‌سازی تایپ‌ها بر اساس تایپ‌های دیگر.
• کتابخانه‌استاندارد تایپ‌ها و traits: یک گردش در کتابخانه‌ استاندارد و ارزشمند Rust.

برنامه زمانی

با احتساب ۱۰ دقیقه استراحت، این جلسه باید حدود ۲ ساعت و ۱۰ دقیقه طول بکشد. این شامل:

تطبیق

این بخش باید حدود ۱ ساعت طول بکشد. این شامل:

تطابق مقادیر

کلمه کلیدی match به شما اجازه می‌دهد یک مقدار را با یک یا چند الگو مطابقت دهید. مقایسه‌ها از بالا به پایین انجام می‌شوند و اولین تطابق انتخاب می‌شود.

الگوها می توانند مقادیر ساده ای باشند، شبیه به switch در C و ++C:

#[rustfmt::skip]
fn main() {
    let input = 'x';
    match input {
        'q'                       => println!("ترک کردن"),
        'a' | 's' | 'w' | 'd'     => println!("حرکت در اطراف"),
        '0'..='9'                 => println!("ورودی شماره"),
        key if key.is_lowercase() => println!("حروف کوچک: {key}"),
        _                         => println!("یک چیز دیگر"),
    }
}

الگوی _ یک الگوی عام (Wildcard) است که با هر مقداری مطابقت دارد. عبارت‌ها باید جامع باشند، به این معنی که همه احتمالات را پوشش دهند، بنابراین _ اغلب به عنوان آخرین حالت برای پوشش تمامی موارد استفاده می‌شود.

match می‌تواند به عنوان یک عبارت استفاده شود. دقیقاً مانند if، هر شاخه match باید از یک تایپ باشد. تایپ بازگشتی، تایپ آخرین عبارت در بلاک است، اگر وجود داشته باشد. در مثال بالا، تایپ بازگشتی () است.

یک متغیر در الگو (key در این مثال) یک اتصال ایجاد می‌کند که می‌توان از آن در بخش مطابقت استفاده کرد.

یک guard در عبارت match باعث می‌شود که آن شاخه تنها در صورتی مطابقت داشته باشد که شرط برقرار باشد.

ساختارها

مانند tuple ها، ساختار را نیز می توان با تطبیق تخریب کرد:

struct Foo {
    x: (u32, u32),
    y: u32,
}

#[rustfmt::skip]
fn main() {
    let foo = Foo { x: (1, 2), y: 3 };
    match foo {
        Foo { x: (1, b), y } => println!("x.0 = 1, b = {b}, y = {y}"),
        Foo { y: 2, x: i }   => println!("y = 2, x = {i:?}"),
        Foo { y, .. }        => println!("در y = {y} ، سایر فیلدها نادیده گرفته شدند"),
    }
}

Enums

مانند tuple ها، enum ها را نیز می توان با تطبیق تخریب کرد:

الگوها همچنین می‌توانند برای متصل کردن متغیرها به بخش‌هایی از مقادیر شما استفاده شوند. این روش به شما اجازه می‌دهد ساختار انواع خود را بررسی کنید. بیایید با یک نوع ساده enum شروع کنیم:

enum Result {
    Ok(i32),
    Err(String),
}

fn divide_in_two(n: i32) -> Result {
    if n % 2 == 0 {
        Result::Ok(n / 2)
    } else {
        Result::Err(format!("نمی توان  {n}  را به دو قسمت مساوی تقسیم کرد"))
    }
}

fn main() {
    let n = 100;
    match divide_in_two(n) {
        Result::Ok(half) => println!("{n} تقسیم به دو است {half}"),
        Result::Err(msg) => println!("با عرض‌پوزش، خطایی رخ داده است: {msg}"),
    }
}

اینجا از شاخه‌ها برای تجزیه مقدار Result استفاده کرده‌ایم. در شاخه‌ی اول، half به مقداری که درون حالت Ok قرار دارد متصل شده است. در شاخه‌ی دوم، msg به پیام خطا متصل شده است.

کنترل جریان Let

زبان Rust چند ساختار کنترل جریان دارد که با سایر زبان‌ها متفاوت است. این ساختارها برای مطابقت الگو استفاده می‌شوند:

• عبارت if let
• عبارت let else
• عبارت while let

عبارت if let

عبارت if let به شما امکان می‌دهد بسته به اینکه آیا یک مقدار با یک الگو مطابقت دارد، کدهای مختلفی را اجرا کنید:

use std::time::Duration;

fn sleep_for(secs: f32) {
    if let Ok(dur) = Duration::try_from_secs_f32(secs) {
        std::thread::sleep(dur);
        println!("slept for {:?}", dur);
    }
}

fn main() {
    sleep_for(-10.0);
    sleep_for(0.8);
}

عبارت let else

برای حالت رایج مطابقت با یک الگو و بازگشت از تابع، از let else استفاده کنید. در اینجا، حالت "else" باید منحرف شود (مانند return، break، یا panic - به غیر از اینکه از انتهای بلوک خارج شود).

fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    if let Some(s) = maybe_string {
        if let Some(first_byte_char) = s.chars().next() {
            if let Some(digit) = first_byte_char.to_digit(16) {
                Ok(digit)
            } else {
                return Err(String::from("نه یک hex digit"));
            }
        } else {
            return Err(String::from("یک string خالی دریافت کردم"));
        }
    } else {
        return Err(String::from("هیچ‌کدام"));
    }
}

fn main() {
    println!("نتیجه: {:?}", hex_or_die_trying(Some(String::from("foo"))));
}

مانند if let، یک دستور while let وجود دارد که مقادیر مقابل الگو به طور مکرر (تکرار شونده‌ای) بررسی می‌کند:

fn main() {
    let mut name = String::from("Comprehensive Rust 🦀");
    while let Some(c) = name.pop() {
        println!("character: {c}");
    }
    // (There are more efficient ways to reverse a string!)
}

در اینجا String::pop تا زمانی که رشته خالی نشده است، Some(c) را برمی‌گرداند و پس از آن None را باز می‌گرداند. استفاده از while let به ما این امکان را می‌دهد که به طور مداوم از میان همه موارد عبور کنیم.

#![allow(unused)]
fn main() {
fn hex_or_die_trying(maybe_string: Option<String>) -> Result<u32, String> {
    let Some(s) = maybe_string else {
        return Err(String::from("هیچ‌کدام"));
    };

    let Some(first_byte_char) = s.chars().next() else {
        return Err(String::from("یک string خالی دریافت کردم"));
    };

    let Some(digit) = first_byte_char.to_digit(16) else {
        return Err(String::from("نه یک hex digit"));
    };

    return Ok(digit);
}
}

تمرین: ارزیابی عبارت

بیایید یک ارزیاب ساده بازگشتی برای عبارات حسابی بنویسیم.

نوع Box در اینجا یک اشاره‌گر هوشمند است و در ادامه دوره به طور مفصل مورد بررسی قرار خواهد گرفت. یک عبارت می‌تواند با استفاده از Box::new "باکس" شود، همان‌طور که در تست‌ها مشاهده می‌شود. برای ارزیابی یک عبارت باکس‌شده، از عملگر deref (*) برای "باز کردن باکس" استفاده کنید: eval(*boxed_expr).

برخی از عبارات نمی‌توانند ارزیابی شوند و خطا برمی‌گردانند. نوع استاندارد Result<Value, String> یک enum است که یا نمایانگر یک مقدار موفقیت‌آمیز (Ok(Value)) یا یک خطا (Err(String)) است. ما این نوع را به‌طور مفصل‌تر در آینده پوشش خواهیم داد.

کد را کپی و در Rust Playground پیست کنید و پیاده‌سازی تابع eval را آغاز کنید. محصول نهایی باید تست‌ها را پاس کند. ممکن است استفاده از ()!todo و گذراندن تست‌ها به صورت تک به تک مفید باشد. همچنین می‌توانید به طور موقت یک تست را با استفاده از [ignore]# نادیده بگیرید:

#[test]
#[ignore]
fn test_value() { .. }

اگر زودتر تمام کردید، سعی کنید یک تست بنویسید که منجر به تقسیم بر صفر یا سرریز عدد صحیح شود. چگونه می‌توانید این را با استفاده از Result به جای panic مدیریت کنید؟

#![allow(unused)]
fn main() {
/// An operation to perform on two subexpressions.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// An expression, in tree form.
#[derive(Debug)]
enum Expression {
    /// An operation on two subexpressions.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// A literal value
    Value(i64),
}

fn eval(e: Expression) -> Result<i64, String> {
    todo!()
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(19));
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        Ok(30)
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        Ok(85)
    );
}

#[test]
fn test_error() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(99)),
            right: Box::new(Expression::Value(0)),
        }),
        Err(String::from("تقسیم بر صفر"))
    );
}
}

راه‌حل

/// An operation to perform on two subexpressions.
#[derive(Debug)]
enum Operation {
    Add,
    Sub,
    Mul,
    Div,
}

/// An expression, in tree form.
#[derive(Debug)]
enum Expression {
    /// An operation on two subexpressions.
    Op { op: Operation, left: Box<Expression>, right: Box<Expression> },

    /// A literal value
    Value(i64),
}

fn eval(e: Expression) -> Result<i64, String> {
    match e {
        Expression::Op { op, left, right } => {
            let left = match eval(*left) {
                Ok(v) => v,
                e @ Err(_) => return e,
            };
            let right = match eval(*right) {
                Ok(v) => v,
                e @ Err(_) => return e,
            };
            Ok(match op {
                Operation::Add => left + right,
                Operation::Sub => left - right,
                Operation::Mul => left * right,
                Operation::Div => {
                    if right == 0 {
                        return Err(String::from("تقسیم بر صفر"));
                    } else {
                        left / right
                    }
                }
            })
        }
        Expression::Value(v) => Ok(v),
    }
}

#[test]
fn test_value() {
    assert_eq!(eval(Expression::Value(19)), Ok(19));
}

#[test]
fn test_sum() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(Expression::Value(10)),
            right: Box::new(Expression::Value(20)),
        }),
        Ok(30)
    );
}

#[test]
fn test_recursion() {
    let term1 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Value(10)),
        right: Box::new(Expression::Value(9)),
    };
    let term2 = Expression::Op {
        op: Operation::Mul,
        left: Box::new(Expression::Op {
            op: Operation::Sub,
            left: Box::new(Expression::Value(3)),
            right: Box::new(Expression::Value(4)),
        }),
        right: Box::new(Expression::Value(5)),
    };
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Add,
            left: Box::new(term1),
            right: Box::new(term2),
        }),
        Ok(85)
    );
}

#[test]
fn test_error() {
    assert_eq!(
        eval(Expression::Op {
            op: Operation::Div,
            left: Box::new(Expression::Value(99)),
            right: Box::new(Expression::Value(0)),
        }),
        Err(String::from("تقسیم بر صفر"))
    );
}

fn main() {
    let expr = Expression::Op {
        op: Operation::Sub,
        left: Box::new(Expression::Value(20)),
        right: Box::new(Expression::Value(10)),
    };
    println!("expr: {:?}", expr);
    println!("نتیجه: {:?}", eval(expr));
}

متدها و تریت‌ها

این بخش حدود ۵۰ دقیقه طول خواهد کشید. شامل موارد زیر است:

متدها

Rust به شما این امکان را می‌دهد که توابعی را با تایپ جدید خود مرتبط کنید. این کار را با استفاده از بلوک impl انجام می‌دهید:

#[derive(Debug)]
struct Race {
    name: String,
    laps: Vec<i32>,
}

impl Race {
    // No receiver, a static method
    fn new(name: &str) -> Self {
        Self { name: String::from(name), laps: Vec::new() }
    }

    // Exclusive borrowed read-write access to self
    fn add_lap(&mut self, lap: i32) {
        self.laps.push(lap);
    }

    // Shared and read-only borrowed access to self
    fn print_laps(&self) {
        println!("ضبط {} دور برای {}:", self.laps.len(), self.name);
        for (idx, lap) in self.laps.iter().enumerate() {
            println!("Lap {idx}: {lap} sec");
        }
    }

    // Exclusive ownership of self
    fn finish(self) {
        let total: i32 = self.laps.iter().sum();
        println!("مسابقه {} به پایان رسید، کل زمان دور: {}", self.name, total);
    }
}

fn main() {
    let mut race = Race::new("جایزه بزرگ موناکو");
    race.add_lap(70);
    race.add_lap(68);
    race.print_laps();
    race.add_lap(71);
    race.print_laps();
    race.finish();
    // race.add_lap(42);
}

آرگومان‌های self "گیرنده" را مشخص می‌کنند - شیئی که متد بر روی آن عمل می‌کند. چندین گیرنده رایج برای یک متد وجود دارد:

• self&: شیئی را از فراخواننده با استفاده از یک مرجع مشترک و غیرقابل تغییر قرض می‌گیرد. شیء می‌تواند بعداً دوباره استفاده شود.
• mut self&: شیء را از فراخواننده با استفاده از یک مرجع منحصر به فرد و قابل تغییر قرض می‌گیرد. شی پس از آن نمی‌تواند دوباره استفاده شود تا زمانی که مرجع به پایان برسد.
• self: مالکیت شیء را به عهده می‌گیرد و آن را از فراخواننده منتقل می‌کند. متد مالک شیء می‌شود. شیء هنگامی که متد باز می‌گردد حذف خواهد شد، مگر اینکه مالکیت آن به‌طور صریح منتقل شود. مالکیت کامل به‌طور خودکار به معنای قابلیت تغییر نیست.
• mut self: مشابه مورد بالا، اما متد می‌تواند شیء را تغییر دهد.
• بدون گیرنده: این تبدیل به یک متد استاتیک در ساختار می‌شود. معمولاً برای ایجاد سازنده‌ها استفاده می‌شود که به‌طور معمول new نامیده می‌شوند.

Traits

راست به شما این امکان را می‌دهد که با استفاده از traits بر روی تایپ‌ها انتزاع ایجاد کنید. آنها مشابه interface ها هستند:

trait Pet {
    /// Return a sentence from this pet.
    fn talk(&self) -> String;

    /// Print a string to the terminal greeting this pet.
    fn greet(&self);
}

پیاده سازی Traits

trait Pet {
    fn talk(&self) -> String;

    fn greet(&self) {
        println!("اوه تو چثدر زیبا هستی! اسمت چیه؟ {}", self.talk());
    }
}

struct Dog {
    name: String,
    age: i8,
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("  Woof، نام من {} است!", self.name)
    }
}

fn main() {
    let fido = Dog { name: String::from("Fido"), age: 5 };
    fido.greet();
}

Supertraits

یک trait می‌تواند نیاز داشته باشد که تایپ‌هایی که آن را پیاده‌سازی می‌کنند، همچنین traits دیگری به نام supertraits را نیز پیاده‌سازی کنند. در اینجا، هر نوعی که Pet را پیاده‌سازی کند، باید Animal را نیز پیاده‌سازی کند.

trait Animal {
    fn leg_count(&self) -> u32;
}

trait Pet: Animal {
    fn name(&self) -> String;
}

struct Dog(String);

impl Animal for Dog {
    fn leg_count(&self) -> u32 {
        4
    }
}

impl Pet for Dog {
    fn name(&self) -> String {
        self.0.clone()
    }
}

fn main() {
    let puppy = Dog(String::from("Rex"));
    println!("{} has {} legs", puppy.name(), puppy.leg_count());
}

تایپ‌های وابسته

تایپ‌های مرتبط تایپ‌هایی جایگزین هستند که توسط پیاده‌سازی trait تأمین می‌شوند.

#[derive(Debug)]
struct Meters(i32);
#[derive(Debug)]
struct MetersSquared(i32);

trait Multiply {
    type Output;
    fn multiply(&self, other: &Self) -> Self::Output;
}

impl Multiply for Meters {
    type Output = MetersSquared;
    fn multiply(&self, other: &Self) -> Self::Output {
        MetersSquared(self.0 * other.0)
    }
}

fn main() {
    println!("{:?}", Meters(10).multiply(&Meters(20)));
}

Deriving

Traitهای پشتیبانی‌شده می‌توانند به‌طور خودکار برای تایپ‌های سفارشی شما پیاده‌سازی شوند، به شرح زیر:

#[derive(Debug, Clone, Default)]
struct Player {
    name: String,
    strength: u8,
    hit_points: u8,
}

fn main() {
    let p1 = Player::default(); // Default trait adds `default` constructor.
    let mut p2 = p1.clone(); // Clone trait adds `clone` method.
    p2.name = String::from("dog");
    // Debug trait adds support for printing with `{:?}`.
    println!("{:?} vs. {:?}", p1, p2);
}

تمرین: Trait Logger

بیایید یک ابزار لاگ‌ ساده طراحی کنیم که از یک trait به نام Logger با متد log استفاده کند. کدی که ممکن است پیشرفت خود را لاگ کند می‌تواند یک impl Logger& دریافت کند. در زمان تست، این ممکن است پیام‌ها را در فایل‌ لاگ تست قرار دهد، در حالی که در نسخه تولید، پیام‌ها به یک سرور لاگ ارسال می‌شود.

با این حال، StderrLogger که در زیر داده شده است، تمامی پیام‌ها را بدون توجه به سطح جزئیات لاگ می‌کند. وظیفه شما این است که نوع VerbosityFilter را بنویسید که پیام‌هایی با سطح جزئیات بالاتر از حداکثر سطح تعیین‌شده را نادیده بگیرد.

این الگو الگوی رایجی است: یک ساختارکه یک پیاده‌سازی trait را در بر می‌گیرد و همان trait را پیاده‌سازی می‌کند و در این فرآیند به آن رفتار اضافی می‌دهد. چه نوع‌های دیگری از پوشش‌دهنده‌ها ممکن است در یک ابزار لاگ مفید باشند؟

use std::fmt::Display;

pub trait Logger {
    /// Log a message at the given verbosity level.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("اطلاعات بیشتر={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "اوهو");
}

// TODO: Define and implement `VerbosityFilter`.

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

راه‌حل

use std::fmt::Display;

pub trait Logger {
    /// Log a message at the given verbosity level.
    fn log(&self, verbosity: u8, message: impl Display);
}

struct StderrLogger;

impl Logger for StderrLogger {
    fn log(&self, verbosity: u8, message: impl Display) {
        eprintln!("اطلاعات بیشتر={verbosity}: {message}");
    }
}

fn do_things(logger: &impl Logger) {
    logger.log(5, "FYI");
    logger.log(2, "اوهو");
}

/// Only log messages up to the given verbosity level.
struct VerbosityFilter {
    max_verbosity: u8,
    inner: StderrLogger,
}

impl Logger for VerbosityFilter {
    fn log(&self, verbosity: u8, message: impl Display) {
        if verbosity <= self.max_verbosity {
            self.inner.log(verbosity, message);
        }
    }
}

fn main() {
    let l = VerbosityFilter { max_verbosity: 3, inner: StderrLogger };
    do_things(&l);
}

خوش آمد

با احتساب ۱۰ دقیقه استراحت، این جلسه باید حدود ۳ ساعت و ۱۵ دقیقه طول بکشد. آن شامل:

Generics

این بخش باید حدود ۴۵ دقیقه طول بکشد. آن شامل:

توابع Generic

Rust از generics پشتیبانی می‌کند که به شما امکان می‌دهد الگوریتم‌ها یا ساختارهای داده (مانند مرتب‌سازی یا درخت دودویی) را بر روی تایپ‌های استفاده‌شده یا ذخیره‌شده تخصیص دهید.

/// Pick `even` or `odd` depending on the value of `n`.
fn pick<T>(n: i32, even: T, odd: T) -> T {
    if n % 2 == 0 {
        even
    } else {
        odd
    }
}

fn main() {
    println!("شماره ای را انتخاب کرد: {:?}", pick(97, 222, 333));
    println!("یک تاپل انتخاب کرد: {:?}", pick(28, ("سگ", 1), ("گربه", 2)));
}

دیتا تایپ‌های Generic

می‌توانید از generic‌ ها برای انتزاع نوع فیلد مشخص استفاده کنید:

#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn coords(&self) -> (&T, &T) {
        (&self.x, &self.y)
    }

    fn set_x(&mut self, x: T) {
        self.x = x;
    }
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
    println!("{integer:?} و {float:?}");
    println!("coords: {:?}", integer.coords());
}

Generic Traits

Traits نیز می‌توانند generic باشند، درست مانند تایپ و توابع. پارامترهای یک trait زمانی که استفاده می‌شود، تایپ‌های مشخصی پیدا می‌کنند.

#[derive(Debug)]
struct Foo(String);

impl From<u32> for Foo {
    fn from(from: u32) -> Foo {
        Foo(format!("تبدیل شده از integer: {from}"))
    }
}

impl From<bool> for Foo {
    fn from(from: bool) -> Foo {
        Foo(format!("تبدیل‌شده از bool: {from}"))
    }
}

fn main() {
    let from_int = Foo::from(123);
    let from_bool = Foo::from(true);
    println!("{from_int:?}, {from_bool:?}");
}

Trait Bounds

هنگام کار با generic‌ها، معمولاً می‌خواهید نیاز داشته باشید که تایپ، trait ترید خاص را پیاده‌سازی کنند، تا بتوانید متدهای آن trait را فراخوانی کنید.

You can do this with T: Trait:

fn duplicate<T: Clone>(a: T) -> (T, T) {
    (a.clone(), a.clone())
}

// struct NotClonable;

fn main() {
    let foo = String::from("foo");
    let pair = duplicate(foo);
    println!("{pair:?}");
}

impl Trait

مشابه با محدودیت‌های trait، می‌توان از impl Trait syntax در آرگومان‌های تابع و مقادیر بازگشتی استفاده کرد:

// Syntactic sugar for:
//   fn add_42_millions<T: Into<i32>>(x: T) -> i32 {
fn add_42_millions(x: impl Into<i32>) -> i32 {
    x.into() + 42_000_000
}

fn pair_of(x: u32) -> impl std::fmt::Debug {
    (x + 1, x - 1)
}

fn main() {
    let many = add_42_millions(42_i8);
    println!("{many}");
    let many_more = add_42_millions(10_000_000);
    println!("{many_more}");
    let debuggable = pair_of(27);
    println!("قابل دیباگ: {debuggable:?}");
}

dyn Trait

علاوه بر استفاده از تریدها برای فراخوانی استاتیک از طریق generic‌ها، Rust همچنین از استفاده از آن‌ها برای فراخوانی داینامیک با تایپ‌های حذف‌شده از طریق اشیاء trait پشتیبانی می‌کند:

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("  Woof، نام من {} است!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

// Uses generics and static dispatch.
fn generic(pet: &impl Pet) {
    println!("سلام، شما کی هستید؟ {}", pet.talk());
}

// Uses type-erasure and dynamic dispatch.
fn dynamic(pet: &dyn Pet) {
    println!("سلام، شما کی هستید؟ {}", pet.talk());
}

fn main() {
    let cat = Cat { lives: 9 };
    let dog = Dog { name: String::from("Fido"), age: 5 };

    generic(&cat);
    generic(&dog);

    dynamic(&cat);
    dynamic(&dog);
}

تمرین: Generic min

در این تمرین کوتاه، شما یک تابع mingeneric را پیاده‌سازی خواهید کرد که حداقل از دو مقدار را تعیین می‌کند، با استفاده از trait Ord.

use std::cmp::Ordering;

// TODO: implement the `min` function used in `main`.

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("hello", "goodbye"), "goodbye");
    assert_eq!(min("bat", "armadillo"), "armadillo");
}

راه‌حل

use std::cmp::Ordering;

fn min<T: Ord>(l: T, r: T) -> T {
    match l.cmp(&r) {
        Ordering::Less | Ordering::Equal => l,
        Ordering::Greater => r,
    }
}

fn main() {
    assert_eq!(min(0, 10), 0);
    assert_eq!(min(500, 123), 123);

    assert_eq!(min('a', 'z'), 'a');
    assert_eq!(min('7', '1'), '1');

    assert_eq!(min("hello", "goodbye"), "goodbye");
    assert_eq!(min("bat", "armadillo"), "armadillo");
}

کتابخانه‌ استاندارد تایپ‌ها

این بخش باید حدود ۱ ساعت طول بکشد. این شامل:

کتابخانه‌ استاندارد

Rust دارای یک کتابخانه استاندارد است که به ایجاد مجموعه‌ای از تایپ‌های رایج استفاده‌شده توسط کتابخانه‌ها و برنامه‌های Rust کمک می‌کند. به این ترتیب، دو کتابخانه می‌توانند به‌راحتی با هم کار کنند زیرا هر دو از تایپ String یکسانی استفاده می‌کنند.

در واقع، Rust شامل چندین لایه از کتابخانه استاندارد است: core، alloc و std.

• core شامل ابتدایی‌ترین تایپ‌ها و توابع است که به libc، تخصیص‌دهنده حافظه یا حتی وجود یک سیستم‌عامل وابسته نیستند.
• alloc شامل تایپ‌هایی است که به یک تخصیص‌دهنده حافظه سراسری نیاز دارند، مانند Vec، Box و Arc.
• برنامه‌های Rust تعبیه‌شده اغلب تنها از core و گاهی اوقات از alloc استفاده می‌کنند.

مستندات

Rust دارای مستندات گسترده‌ای است. به عنوان مثال:

• تمام جزئیات مربوط به حلقه‌ها.
• تایپ‌های ابتدایی مانند u8.
• تایپ‌های کتابخانه استاندارد مانند Option یا BinaryHeap.

در واقع، شما می‌توانید کد خود را مستند کنید:

/// Determine whether the first argument is divisible by the second argument.
///
/// If the second argument is zero, the result is false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;
    }
    lhs % rhs == 0
}

محتویات به‌عنوان Markdown پردازش می‌شوند. تمام crate‌های کتابخانه‌ای منتشرشده Rust به‌طور خودکار در docs.rs با استفاده از ابزار rustdoc مستند می‌شوند. مستند کردن تمام آیتم‌های عمومی در یک API با استفاده از این الگو به‌طور رایج مرسوم است.

برای مستند کردن یک آیتم از درون خود آیتم (مانند درون یک ماژول)، از !// یا /* .. !*/ استفاده کنید که به آن "کامنت‌های مستندات داخلی" می‌گویند:

//! This module contains functionality relating to divisibility of integers.

Option

ما قبلاً برخی استفاده‌ها از <Option<T را مشاهده کرده‌ایم. این تایپ یا مقداری از تایپT را ذخیره می‌کند یا هیچ چیزی را ذخیره نمی‌کند. به عنوان مثال، String::find یک <Option<usize را برمی‌گرداند.

fn main() {
    let name = "Löwe 老虎 Léopard Gepardi";
    let mut position: Option<usize> = name.find('é');
    println!("پیدا کردن نوع بازگشتی{position:?}");
    assert_eq!(position.unwrap(), 14);
    position = name.find('Z');
    println!("پیدا کردن نوع بازگشتی{position:?}");
    assert_eq!(position.expect("Character not found"), 0);
}

Result

Result مشابه Option است، اما موفقیت یا شکست یک عملیات را نشان می‌دهد، هرکدام با یک نوع متغیر enum متفاوت. این نوع جنریک است: <Result<T, E که در آن T در متغیر Ok استفاده می‌شود و E در متغیر Err ظاهر می‌شود.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("دفتر خاطرات عزیز: {contents} ({bytes} bytes)");
            } else {
                println!("نمی‌توان محتوای فایل را خواند");
            }
        }
        Err(err) => {
            println!("دفتر خاطرات باز نشد: {err}");
        }
    }
}

String

String یک رشته قابل رشد با کدگذاری UTF-8 است:

fn main() {
    let mut s1 = String::new();
    s1.push_str("سلام");
    println!("s1: len = {}, capacity = {}", s1.len(), s1.capacity());

    let mut s2 = String::with_capacity(s1.len() + 1);
    s2.push_str(&s1);
    s2.push('!');
    println!("s2: len = {}, capacity = {}", s2.len(), s2.capacity());

    let s3 = String::from("🇨🇭");
    println!("s3: len = {}, number of chars = {}", s3.len(), s3.chars().count());
}

String پیاده‌سازی‌کننده Deref<Target = str> است، که به این معناست که می‌توانید تمام متدهای str را بر روی String فراخوانی کنید.

Vec

این Vec بافر قابل تغییر اندازه و heap-allocated است:

fn main() {
    let mut v1 = Vec::new();
    v1.push(42);
    println!("v1: len = {}, capacity = {}", v1.len(), v1.capacity());

    let mut v2 = Vec::with_capacity(v1.len() + 1);
    v2.extend(v1.iter());
    v2.push(9999);
    println!("v2: len = {}, capacity = {}", v2.len(), v2.capacity());

    // Canonical macro to initialize a vector with elements.
    let mut v3 = vec![0, 0, 1, 2, 3, 4];

    // Retain only the even elements.
    v3.retain(|x| x % 2 == 0);
    println!("{v3:?}");

    // Remove consecutive duplicates.
    v3.dedup();
    println!("{v3:?}");
}

Vec پیاده‌سازی‌کننده Deref<Target = [T]> است، به این معنی که می‌توانید متدهای برش را بر روی یک Vec فراخوانی کنید.

HashMap

نقشه hash استاندارد با حفاظت در برابر حملات HashDoS:

use std::collections::HashMap;

fn main() {
    let mut page_counts = HashMap::new();
    page_counts.insert("ماجراهای هاکلبری فین", 207);
    page_counts.insert("قصه‌های گریمز", 751);
    page_counts.insert("غرور و تعصب", 303);

    if !page_counts.contains_key("Les Misérables") {
        println!(
            "ما درباره {} کتاب می دانیم، اما Les Misérables نه.",
            page_counts.len()
        );
    }

    for book in ["غرور و تعصب", "ماجراجویی آلیس در سرزمین عجایب"] {
        match page_counts.get(book) {
            Some(count) => println!("{book}: {count} صفحه‌ها"),
            None => println!("{book} ناشناخته است."),
        }
    }

    // Use the .entry() method to insert a value if nothing is found.
    for book in ["غرور و تعصب", "ماجراجویی آلیس در سرزمین عجایب"] {
        let page_count: &mut i32 = page_counts.entry(book).or_insert(0);
        *page_count += 1;
    }

    println!("{page_counts:#?}");
}

تمرین: شمارنده

در این تمرین، شما یک ساختار داده بسیار ساده را به‌صورت generic خواهید کرد. این ساختار از std::collections::HashMap برای پیگیری اینکه چه مقادیری مشاهده شده‌اند و هرکدام چند بار ظاهر شده‌اند، استفاده می‌کند.

نسخه اولیه Counter به‌طور سخت‌افزاری برای مقادیر u32 کدگذاری شده است. ساختار و متدهای آن را به‌صورت generic بر اساس تایپ مقداری که در حال پیگیری است، تغییر دهید، به‌طوری که Counter بتواند هر تایپ مقداری را پیگیری کند.

اگر زود تمام کردید، سعی کنید از متد entry استفاده کنید تا تعداد جستجوهای هش مورد نیاز برای پیاده‌سازی متد count را به نصف کاهش دهید.

use std::collections::HashMap;

/// Counter counts the number of times each value of type T has been seen.
struct Counter {
    values: HashMap<u32, u64>,
}

impl Counter {
    /// Create a new Counter.
    fn new() -> Self {
        Counter {
            values: HashMap::new(),
        }
    }

    /// Count an occurrence of the given value.
    fn count(&mut self, value: u32) {
        if self.values.contains_key(&value) {
            *self.values.get_mut(&value).unwrap() += 1;
        } else {
            self.values.insert(value, 1);
        }
    }

    /// Return the number of times the given value has been seen.
    fn times_seen(&self, value: u32) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("مقادیر {} برابر با {} را دیده‌شده", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("سیب");
    strctr.count("orange");
    strctr.count("سیب");
    println!("داشتم {} سیب‌ها", strctr.times_seen("سیب"));
}

راه‌حل

use std::collections::HashMap;
use std::hash::Hash;

/// Counter counts the number of times each value of type T has been seen.
struct Counter<T> {
    values: HashMap<T, u64>,
}

impl<T: Eq + Hash> Counter<T> {
    /// Create a new Counter.
    fn new() -> Self {
        Counter { values: HashMap::new() }
    }

    /// Count an occurrence of the given value.
    fn count(&mut self, value: T) {
        *self.values.entry(value).or_default() += 1;
    }

    /// Return the number of times the given value has been seen.
    fn times_seen(&self, value: T) -> u64 {
        self.values.get(&value).copied().unwrap_or_default()
    }
}

fn main() {
    let mut ctr = Counter::new();
    ctr.count(13);
    ctr.count(14);
    ctr.count(16);
    ctr.count(14);
    ctr.count(14);
    ctr.count(11);

    for i in 10..20 {
        println!("مقادیر {} برابر با {} را دیده‌شده", ctr.times_seen(i), i);
    }

    let mut strctr = Counter::new();
    strctr.count("سیب");
    strctr.count("orange");
    strctr.count("سیب");
    println!("داشتم {} سیب‌ها", strctr.times_seen("سیب"));
}

کتابخانه استاندارد Traits

این بخش باید حدود ۱ ساعت و ۱۰ دقیقه طول بکشد. این بخش شامل موارد زیر است:

مقایسه

این trait‌ها از مقایسه بین مقادیر پشتیبانی می‌کنند. همه‌ی این trait‌ها را می‌توان برای تایپ‌هایی که شامل فیلدهایی هستند که این trait‌ها را پیاده‌سازی می‌کنند، به‌دست آورد.

PartialEq and Eq

PartialEq یک رابطه هم‌ارزی جزئی است که دارای متد الزامی eq و متد ارائه‌شده ne می‌باشد. عملگرهای == و =! این متدها را فراخوانی می‌کنند.

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq for Key {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}

Eq یک رابطه هم‌ارزی کامل است (بازتابی، متقارن، و transitive) و شامل PartialEq می‌شود. توابعی که به هم‌ارزی کامل نیاز دارند، از Eq به‌عنوان یک trait bound استفاده می‌کنند.

PartialOrd and Ord

PartialOrd یک ترتیب جزئی را تعریف می‌کند و دارای متد partial_cmp است. این ویژگی برای پیاده‌سازی عملگرهای <، <=، >= و > استفاده می‌شود.

use std::cmp::Ordering;
#[derive(Eq, PartialEq)]
struct Citation {
    author: String,
    year: u32,
}
impl PartialOrd for Citation {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        match self.author.partial_cmp(&other.author) {
            Some(Ordering::Equal) => self.year.partial_cmp(&other.year),
            author_ord => author_ord,
        }
    }
}

Ord یک ترتیب کامل است که در آن متد cmp مقدار Ordering را برمی‌گرداند.

struct Key {
    id: u32,
    metadata: Option<String>,
}
impl PartialEq<u32> for Key {
    fn eq(&self, other: &u32) -> bool {
        self.id == *other
    }
}

اپراتورها

بارگذاری مجدد عملگرها از طریق traits در std::ops پیاده‌سازی شده است:

#[derive(Debug, Copy, Clone)]
struct Point {
    x: i32,
    y: i32,
}

impl std::ops::Add for Point {
    type Output = Self;

    fn add(self, other: Self) -> Self {
        Self { x: self.x + other.x, y: self.y + other.y }
    }
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = Point { x: 100, y: 200 };
    println!("{:?} + {:?} = {:?}", p1, p2, p1 + p2);
}

From and Into

Types implement From and Into to facilitate type conversions. Unlike as, these traits correspond to lossless, infallible conversions.

fn main() {
    let s = String::from("hello");
    let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);
    let one = i16::from(true);
    let bigger = i32::from(123_i16);
    println!("{s}, {addr}, {one}, {bigger}");
}

Into به‌طور خودکار زمانی پیاده‌سازی می‌شود که From پیاده‌سازی شده باشد:

fn main() {
    let s: String = "hello".into();
    let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();
    let one: i16 = true.into();
    let bigger: i32 = 123_i16.into();
    println!("{s}, {addr}, {one}, {bigger}");
}

Casting

Rust هیچ implicit ندارد، اما از تبدیل‌های صریح با استفاده از as پشتیبانی می‌کند. این تبدیل‌ها معمولاً پیرو معنای C هستند که در آنجا تعریف شده‌اند.

fn main() {
    let value: i64 = 1000;
    println!("as u16: {}", value as u16);
    println!("as i16: {}", value as i16);
    println!("as u8: {}", value as u8);
}

نتایج استفاده از as همیشه در Rust تعریف شده و در تمامی پلتفرم‌ها ثابت هستند. این ممکن است با شهود شما برای تغییر علامت یا تبدیل به تایپ کوچکتر مطابقت نداشته باشد -- مستندات را بررسی کنید و برای وضوح بیشتر نظر دهید.

تبدیل تایپ با استفاده از as ابزاری نسبتاً حساس است که استفاده نادرست از آن آسان است و می‌تواند منبعی از اشکالات ظریف باشد، به خصوص زمانی که کار نگهداری آینده باعث تغییر تایپ‌های مورد استفاده یا دامنه مقادیر در تایپ‌ها شود. تبدیل‌ها بهتر است تنها زمانی استفاده شوند که قصد شما نشان دادن برش بدون قید و شرط باشد (مثلاً انتخاب 32 بیت پایین از یک u64 با as u32، بدون توجه به آنچه در بیت‌های بالا وجود دارد).

برای تبدیل‌های بدون خطا (مانند تبدیل u32 به u64)، استفاده از From یا Into بر as ارجح است تا تأیید شود که تبدیل در واقع بدون خطا است. برای تبدیل‌های با احتمال خطا، TryFrom و TryInto در دسترس هستند وقتی که می‌خواهید تبدیل‌هایی را که به شیوه‌ای متفاوت از آن‌هایی که مطابقت ندارند، مدیریت کنید.

Read and Write

با استفاده از Read و BufRead، می‌توانید بر روی منابع u8 انتزاع کنید:

use std::io::{BufRead, BufReader, Read, Result};

fn count_lines<R: Read>(reader: R) -> usize {
    let buf_reader = BufReader::new(reader);
    buf_reader.lines().count()
}

fn main() -> Result<()> {
    let slice: &[u8] = b"foo\nbar\nbaz\n";
    println!("lines in slice: {}", count_lines(slice));

    let file = std::fs::File::open(std::env::current_exe()?)?;
    println!("lines in file: {}", count_lines(file));
    Ok(())
}

به طور مشابه، Write به شما امکان می‌دهد که بر روی منابع u8 انتزاع کنید:

use std::io::{Result, Write};

fn log<W: Write>(writer: &mut W, msg: &str) -> Result<()> {
    writer.write_all(msg.as_bytes())?;
    writer.write_all("\n".as_bytes())
}

fn main() -> Result<()> {
    let mut buffer = Vec::new();
    log(&mut buffer, "سلام")?;
    log(&mut buffer, "دنیا")?;
    println!("Logged: {:?}", buffer);
    Ok(())
}

The Default Trait

ویژگی Default یک مقدار پیش‌فرض برای یک تایپ تولید می‌کند.

#[derive(Debug, Default)]
struct Derived {
    x: u32,
    y: String,
    z: Implemented,
}

#[derive(Debug)]
struct Implemented(String);

impl Default for Implemented {
    fn default() -> Self {
        Self("John Smith".into())
    }
}

fn main() {
    let default_struct = Derived::default();
    println!("{default_struct:#?}");

    let almost_default_struct =
        Derived { y: "Y is set!".into(), ..Derived::default() };
    println!("{almost_default_struct:#?}");

    let nothing: Option<Derived> = None;
    println!("{:#?}", nothing.unwrap_or_default());
}

Closures

بسته‌ها یا عبارات لامبدا تایپ‌هایی دارند که نمی‌توان نام‌گذاری کرد. با این حال، آن‌ها پیاده‌سازی‌های ویژه از traits Fn، FnMut و FnOnce هستند:

fn apply_and_log(func: impl FnOnce(i32) -> i32, func_name: &str, input: i32) {
    println!("فراخوانی {func_name}({input}): {}", func(input))
}

fn main() {
    let n = 3;
    let add_3 = |x| x + n;
    apply_and_log(&add_3, "add_3", 10);
    apply_and_log(&add_3, "add_3", 20);

    let mut v = Vec::new();
    let mut accumulate = |x: i32| {
        v.push(x);
        v.iter().sum::<i32>()
    };
    apply_and_log(&mut accumulate, "تجمیع: {}", 4);
    apply_and_log(&mut accumulate, "تجمیع: {}", 5);

    let multiply_sum = |x| x * v.into_iter().sum::<i32>();
    apply_and_log(multiply_sum, "multiply_sum", 3);
}

fn make_greeter(prefix: String) -> impl Fn(&str) {
    return move |name| println!("{} {}", prefix, name);
}

fn main() {
    let hi = make_greeter("Hi".to_string());
    hi("Greg");
}

تمرین: ROT13

در این مثال، شما الگوریتم کلاسیک رمزگذاری "ROT13" را پیاده‌سازی خواهید کرد. این کد را به محیط Playground کپی کرده و بخش‌های ناقص آن را پیاده‌سازی کنید. تنها حروف الفبای ASCII را بچرخانید تا نتیجه همچنان UTF-8 معتبر باقی بماند.

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

// Implement the `Read` trait for `RotDecoder`.

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

چه اتفاقی می‌افتد اگر دو نمونه از RotDecoder را به‌هم متصل کنید که هر کدام ۱۳ کاراکتر را بچرخانند؟

راه‌حل

use std::io::Read;

struct RotDecoder<R: Read> {
    input: R,
    rot: u8,
}

impl<R: Read> Read for RotDecoder<R> {
    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
        let size = self.input.read(buf)?;
        for b in &mut buf[..size] {
            if b.is_ascii_alphabetic() {
                let base = if b.is_ascii_uppercase() { 'A' } else { 'a' } as u8;
                *b = (*b - base + self.rot) % 26 + base;
            }
        }
        Ok(size)
    }
}

fn main() {
    let mut rot =
        RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
    let mut result = String::new();
    rot.read_to_string(&mut result).unwrap();
    println!("{}", result);
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn joke() {
        let mut rot =
            RotDecoder { input: "Gb trg gb gur bgure fvqr!".as_bytes(), rot: 13 };
        let mut result = String::new();
        rot.read_to_string(&mut result).unwrap();
        assert_eq!(&result, "To get to the other side!");
    }

    #[test]
    fn binary() {
        let input: Vec<u8> = (0..=255u8).collect();
        let mut rot = RotDecoder::<&[u8]> { input: input.as_ref(), rot: 13 };
        let mut buf = [0u8; 256];
        assert_eq!(rot.read(&mut buf).unwrap(), 256);
        for i in 0..=255 {
            if input[i] != buf[i] {
                assert!(input[i].is_ascii_alphabetic());
                assert!(buf[i].is_ascii_alphabetic());
            }
        }
    }
}

به روز ۳ خوش آمدید

امروز، ما به بررسی خواهیم پرداخت:

• مدیریت حافظه، طول عمرها و بررسی‌کننده قرض‌گیری (borrow checker): چگونه زبان Rust از ایمنی حافظه اطمینان حاصل می‌کند.
• اشاره‌گر هوشمند: تایپ‌های اشاره‌گر در کتابخانه استاندارد.

برنامه زمانی

با احتساب استراحت‌های ۱۰ دقیقه‌ای، این جلسه باید حدود ۲ ساعت و ۲۰ دقیقه طول بکشد. این جلسه شامل:

مدیریت حافظه

این بخش باید حدود ۱ ساعت طول بکشد. این شامل:

بررسی حافظه برنامه

برنامه‌ها حافظه را به دو روش تخصیص می‌دهند:

• Stack: بلوک پیوسته‌ای از حافظه که برای متغیرهای محلی (داخل یک تابع) استفاده می‌شود.

  • مقادیر دارای اندازه‌های ثابتی هستند که در زمان کامپایل شناخته می‌شوند.
  • بسیار سریع: فقط یک اشاره‌گر stack را جابجا کنید.
  • مدیریت آسان: پیرو فراخوانی‌های تابع است.
  • بهره‌وری عالی از حافظه.

• Heap: ذخیره‌سازی مقادیر خارج از فراخوانی‌های تابع.

  • مقادیر دارای اندازه‌های پویا هستند که در زمان اجرا تعیین می‌شوند.
  • کمی کندتر از stack: نیاز به برخی از عملیات‌های مدیریتی دارد.
  • هیچ تضمینی برای بهره‌وری بالا از حافظه ندارد.

مثال

ساختن یک String metadata با اندازه ثابت را روی stack و داده با اندازه پویا، یعنی رشته واقعی، را روی heap قرار می‌دهد:

fn main() {
    let s1 = String::from("سلام");
}

fn main() {
    let mut s1 = String::from("سلام");
    s1.push(' ');
    s1.push_str("دنیا");
    // DON'T DO THIS AT HOME! For educational purposes only.
    // String provides no guarantees about its layout, so this could lead to
    // undefined behavior.
    unsafe {
        let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);
        println!("capacity = {capacity}, ptr = {ptr:#x}, len = {len}");
    }
}

رویکردهای مدیریت حافظه

به طور سنتی، زبان‌ها به دو دسته گسترده تقسیم شده‌اند:

• کنترل کامل از طریق مدیریت دستی حافظه: C++، C، پاسکال، ...
  • برنامه‌نویس تصمیم می‌گیرد که چه زمانی حافظه heap را تخصیص یا آزاد کند.
  • برنامه‌نویس باید تعیین کند که آیا یک اشاره‌گر هنوز به حافظه معتبر اشاره می‌کند یا نه.
  • مطالعات نشان می‌دهد که برنامه‌نویسان اشتباهاتی مرتکب می‌شوند.
• ایمنی کامل از طریق مدیریت خودکار حافظه در زمان اجرا: جاوا، پایتون، گو، هسکل، ...
  • یک سیستم زمان اجرا اطمینان می‌یابد که حافظه تا زمانی که دیگر نتواند به آن ارجاع داده شود، آزاد نمی‌شود.
  • Typically implemented with reference counting or garbage collection.

Rust یک ترکیب جدید ارائه می‌دهد:

کنترل کامل و ایمنی از طریق اجرای صحیح مدیریت حافظه در زمان کامپایل.

این کار را با استفاده از مفهوم مالکیت صریح انجام می‌دهد.

مالکیت

تمام پیوندهای متغیر دارای یک دامنه هستند که در آن معتبر هستند و استفاده از متغیر خارج از دامنه‌اش یک خطاست:

struct Point(i32, i32);

fn main() {
    {
        let p = Point(3, 4);
        println!("x: {}", p.0);
    }
    println!("y: {}", p.1);
}

می‌گوییم که متغیر مالک مقدار است. هر مقدار در Rust در هر لحظه دقیقاً یک مالک دارد.

در پایان دامنه، متغیر حذف می‌شود و داده‌ها آزاد می‌شوند. یک ویرایشگر (destructor) می‌تواند در اینجا اجرا شود تا منابع را آزاد کند.

مفاهیم جابه‌جایی

انتساب, مالکیت را بین متغیرها منتقل می‌کند:

fn main() {
    let s1: String = String::from("سلام!");
    let s2: String = s1;
    println!("s2: {s2}");
    // println!("s1: {s1}");
}

• انتساب s1به s2 مالکیت را منتقل می‌کند.
• زمانی که دیگر در اسکوپ s1 نیستیم, هیچ اتفاقی نمی‌افتد: چون s1 مالک چیزی نیست.
• زمانی که دیگر در اسکوپ s2 نیستیم, داده‌های رشته آزاد می‌شوند.

قبل از انتقال به s2 :

بعد از انتقال به s2 :

هنگامی که یک مقدار را به یک تابع منتقل می‌کنید، مقدار به آرگمان تابع اختصاص داده می‌شود. به این شکل مالکیت را منتقل می‌کند:

fn say_hello(name: String) {
    println!("سلام {name}")
}

fn main() {
    let name = String::from("الیس");
    say_hello(name);
    // say_hello(name);
}

std::string s1 = "Cpp";
std::string s2 = s1;  // Duplicate the data in s1.

Clone

گاهی اوقات شما می‌خواهید یک نسخه از مقدار بسازید. ویژگی Clone این کار را انجام می‌دهد.

fn say_hello(name: String) {
    println!("سلام {name}")
}

fn main() {
    let name = String::from("الیس");
    say_hello(name.clone());
    say_hello(name);
}

کپی کردن تایپ‌ها

در حالی که مفهوم انتقال به صورت پیش‌فرض است، در زبان راست چند نوع خاص به صورت پیش‌فرض کپی می‌شوند:

fn main() {
    let x = 42;
    let y = x;
    println!("x: {x}"); // would not be accessible if not Copy
    println!("y: {y}");
}

این انواع‌داده ویژگی Copy را پیاده‌سازی کرده‌اند.

البته که میتوان برای نوع‌هایی که میسازید هم مفهوم کپی را داشته باشید:

#[derive(Copy, Clone, Debug)]
struct Point(i32, i32);

fn main() {
    let p1 = Point(3, 4);
    let p2 = p1;
    println!("p1: {p1:?}");
    println!("p2: {p2:?}");
}

• پس از انتساب، هر دو p1 و p2 داده‌های خود مستقل خود را دارند.
• همچنین می‌توانیم از p1.clone() برای کپی صریح داده‌ها استفاده کنیم.

ویژگی Drop

مقادیر که ویژگی Drop را پیاده‌سازی می‌کنند می‌توانند کدی را مشخص کنند که هنگام خروج از دامنه اجرا شود:

struct Droppable {
    name: &'static str,
}

impl Drop for Droppable {
    fn drop(&mut self) {
        println!("Dropping {}", self.name);
    }
}

fn main() {
    let a = Droppable { name: "a" };
    {
        let b = Droppable { name: "a" };
        {
            let c = Droppable { name: "c" };
            let d = Droppable { name: "d" };
            println!("Exiting block B");
        }
        println!("Exiting block A");
    }
    drop(a);
    println!("Exiting main");
}

تمرین: تایپ‌های سازنده

در این مثال، ما یک نوع داده پیچیده را پیاده‌سازی خواهیم کرد که مالک تمام داده‌های خود است. ما از "الگوی سازنده" برای پشتیبانی از ساخت یک مقدار جدید به صورت قطعه‌قطعه، با استفاده از توابع کمکی، استفاده خواهیم کرد.

جا‌های خالی را پر کنید.

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// A representation of a software package.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Return a representation of this package as a dependency, for use in
    /// building other packages.
    fn as_dependency(&self) -> Dependency {
        todo!("1")
    }
}

/// A builder for a Package. Use `build()` to create the `Package` itself.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        todo!("2")
    }

    /// Set the package version.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Set the package authors.
    fn authors(mut self, authors: Vec<String>) -> Self {
        todo!("3")
    }

    /// Add an additional dependency.
    fn dependency(mut self, dependency: Dependency) -> Self {
        todo!("4")
    }

    /// Set the language. If not set, language defaults to None.
    fn language(mut self, language: Language) -> Self {
        todo!("5")
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64: {base64:?}").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

راه‌حل

#[derive(Debug)]
enum Language {
    Rust,
    Java,
    Perl,
}

#[derive(Clone, Debug)]
struct Dependency {
    name: String,
    version_expression: String,
}

/// A representation of a software package.
#[derive(Debug)]
struct Package {
    name: String,
    version: String,
    authors: Vec<String>,
    dependencies: Vec<Dependency>,
    language: Option<Language>,
}

impl Package {
    /// Return a representation of this package as a dependency, for use in
    /// building other packages.
    fn as_dependency(&self) -> Dependency {
        Dependency {
            name: self.name.clone(),
            version_expression: self.version.clone(),
        }
    }
}

/// A builder for a Package. Use `build()` to create the `Package` itself.
struct PackageBuilder(Package);

impl PackageBuilder {
    fn new(name: impl Into<String>) -> Self {
        Self(Package {
            name: name.into(),
            version: "0.1".into(),
            authors: vec![],
            dependencies: vec![],
            language: None,
        })
    }

    /// Set the package version.
    fn version(mut self, version: impl Into<String>) -> Self {
        self.0.version = version.into();
        self
    }

    /// Set the package authors.
    fn authors(mut self, authors: Vec<String>) -> Self {
        self.0.authors = authors;
        self
    }

    /// Add an additional dependency.
    fn dependency(mut self, dependency: Dependency) -> Self {
        self.0.dependencies.push(dependency);
        self
    }

    /// Set the language. If not set, language defaults to None.
    fn language(mut self, language: Language) -> Self {
        self.0.language = Some(language);
        self
    }

    fn build(self) -> Package {
        self.0
    }
}

fn main() {
    let base64 = PackageBuilder::new("base64: {base64:?}").version("0.13").build();
    println!("base64: {base64:?}");
    let log =
        PackageBuilder::new("log").version("0.4").language(Language::Rust).build();
    println!("log: {log:?}");
    let serde = PackageBuilder::new("serde")
        .authors(vec!["djmitche".into()])
        .version(String::from("4.0"))
        .dependency(base64.as_dependency())
        .dependency(log.as_dependency())
        .build();
    println!("serde: {serde:?}");
}

اشاره‌گرهای هوشمند

این بخش باید حدود ۵۵ دقیقه طول بکشد. آن شامل:

<Box<T

Box یک اشاره‌گر مالک به داده‌های روی heap است:

fn main() {
    let five = Box::new(5);
    println!("five: {}", *five);
}

<Box<T ویژگی <Deref<Target = T را پیاده‌سازی می‌کند، که به این معناست که می‌توانید مستقیم روش‌های T را روی <Box<T فراخوانی کنید.

تایپ‌های داده‌های بازگشتی یا انواع داده با اندازه‌های دینامیک را نمی‌توان به صورت inline بدون pointer indirection ذخیره کرد، که می‌توان با استفاده از Box آن کار را کرد:

#[derive(Debug)]
enum List<T> {
    /// A non-empty list: first element and the rest of the list.
    Element(T, Box<List<T>>),
    /// An empty list.
    Nil,
}

fn main() {
    let list: List<i32> =
        List::Element(1, Box::new(List::Element(2, Box::new(List::Nil))));
    println!("{list:?}");
}

use std::mem::size_of_val;

struct Item(String);

fn main() {
    let just_box: Box<Item> = Box::new(Item("Just box".into()));
    let optional_box: Option<Box<Item>> =
        Some(Box::new(Item("Optional box".into())));
    let none: Option<Box<Item>> = None;

    assert_eq!(size_of_val(&just_box), size_of_val(&optional_box));
    assert_eq!(size_of_val(&just_box), size_of_val(&none));

    println!("Size of just_box: {}", size_of_val(&just_box));
    println!("Size of optional_box: {}", size_of_val(&optional_box));
    println!("Size of none: {}", size_of_val(&none));
}

Rc

Rc یک اشاره‌گر مشترک با شمارش ارجاع است. از این هنگام استفاده کنید که نیاز دارید به داده‌های یکسان از مکان‌های متعدد اشاره کنید:

use std::rc::Rc;

fn main() {
    let a = Rc::new(10);
    let b = Rc::clone(&a);

    println!("a: {a}");
    println!("b: {b}");
}

• اگر در یک محیط چند-رشته‌ای (multi-threaded) هستید، به Arc و Mutex نگاه کنید.
• شما می‌توانید یک اشاره‌گر مشترک را به یک اشاره‌گر Weak تغییر دهید تا دوره‌هایی ایجاد کنید که در نهایت حذف خواهند شد.

Owned Trait Objects

پیش‌تر دیدیم که چگونه می‌توان ازویژگی اشیاء (trait objects) با ارجاعات استفاده کرد، مثلاً dyn Pet&. با این حال، می‌توانیم از اشیاء ویژگی با اشاره‌گرهای هوشمند مانند Box نیز استفاده کنیم تا یک شیء ویژگی مالک (owned trait object) ایجاد کنیم: <Box<dyn Pet.

struct Dog {
    name: String,
    age: i8,
}
struct Cat {
    lives: i8,
}

trait Pet {
    fn talk(&self) -> String;
}

impl Pet for Dog {
    fn talk(&self) -> String {
        format!("  Woof، نام من {} است!", self.name)
    }
}

impl Pet for Cat {
    fn talk(&self) -> String {
        String::from("Miau!")
    }
}

fn main() {
    let pets: Vec<Box<dyn Pet>> = vec![
        Box::new(Cat { lives: 9 }),
        Box::new(Dog { name: String::from("Fido"), age: 5 }),
    ];
    for pet in pets {
        println!("سلام، شما کی هستید؟ {}", pet.talk());
    }
}

چیدمان حافظه پس از تخصیص pets:

تمرین: درخت باینری

یک درخت باینری (binary tree) یک ساختار داده درختی است که در آن هر گره دو فرزند (چپ و راست) دارد. ما درختی خواهیم ساخت که در آن هر گره یک مقدار را ذخیره می‌کند. برای یک گره معین N، تمام گره‌های زیر درخت چپ N دارای مقادیر کوچکتر خواهند بود و تمام گره‌های زیر درخت راست N دارای مقادیر بزرگتر خواهند بود.

تایپ‌های زیر را پیاده‌سازی کنید تا آزمایش‌های داده شده موفقیت‌آمیز باشند.

اعتبار اضافی: یک تکرارگر (iterator) بر روی درخت باینری پیاده‌سازی کنید که مقادیر را به ترتیب (in-order) برگرداند.

/// A node in the binary tree.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// A possibly-empty subtree.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// A container storing a set of values, using a binary tree.
///
/// If the same value is added multiple times, it is only stored once.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

// Implement `new`, `insert`, `len`, and `has` for `Subtree`.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // not a unique item
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

راه‌حل

use std::cmp::Ordering;

/// A node in the binary tree.
#[derive(Debug)]
struct Node<T: Ord> {
    value: T,
    left: Subtree<T>,
    right: Subtree<T>,
}

/// A possibly-empty subtree.
#[derive(Debug)]
struct Subtree<T: Ord>(Option<Box<Node<T>>>);

/// A container storing a set of values, using a binary tree.
///
/// If the same value is added multiple times, it is only stored once.
#[derive(Debug)]
pub struct BinaryTree<T: Ord> {
    root: Subtree<T>,
}

impl<T: Ord> BinaryTree<T> {
    fn new() -> Self {
        Self { root: Subtree::new() }
    }

    fn insert(&mut self, value: T) {
        self.root.insert(value);
    }

    fn has(&self, value: &T) -> bool {
        self.root.has(value)
    }

    fn len(&self) -> usize {
        self.root.len()
    }
}

impl<T: Ord> Subtree<T> {
    fn new() -> Self {
        Self(None)
    }

    fn insert(&mut self, value: T) {
        match &mut self.0 {
            None => self.0 = Some(Box::new(Node::new(value))),
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.insert(value),
                Ordering::Equal => {}
                Ordering::Greater => n.right.insert(value),
            },
        }
    }

    fn has(&self, value: &T) -> bool {
        match &self.0 {
            None => false,
            Some(n) => match value.cmp(&n.value) {
                Ordering::Less => n.left.has(value),
                Ordering::Equal => true,
                Ordering::Greater => n.right.has(value),
            },
        }
    }

    fn len(&self) -> usize {
        match &self.0 {
            None => 0,
            Some(n) => 1 + n.left.len() + n.right.len(),
        }
    }
}

impl<T: Ord> Node<T> {
    fn new(value: T) -> Self {
        Self { value, left: Subtree::new(), right: Subtree::new() }
    }
}

fn main() {
    let mut tree = BinaryTree::new();
    tree.insert("foo");
    assert_eq!(tree.len(), 1);
    tree.insert("bar");
    assert!(tree.has(&"foo"));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn len() {
        let mut tree = BinaryTree::new();
        assert_eq!(tree.len(), 0);
        tree.insert(2);
        assert_eq!(tree.len(), 1);
        tree.insert(1);
        assert_eq!(tree.len(), 2);
        tree.insert(2); // not a unique item
        assert_eq!(tree.len(), 2);
    }

    #[test]
    fn has() {
        let mut tree = BinaryTree::new();
        fn check_has(tree: &BinaryTree<i32>, exp: &[bool]) {
            let got: Vec<bool> =
                (0..exp.len()).map(|i| tree.has(&(i as i32))).collect();
            assert_eq!(&got, exp);
        }

        check_has(&tree, &[false, false, false, false, false]);
        tree.insert(0);
        check_has(&tree, &[true, false, false, false, false]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(4);
        check_has(&tree, &[true, false, false, false, true]);
        tree.insert(3);
        check_has(&tree, &[true, false, false, true, true]);
    }

    #[test]
    fn unbalanced() {
        let mut tree = BinaryTree::new();
        for i in 0..100 {
            tree.insert(i);
        }
        assert_eq!(tree.len(), 100);
        assert!(tree.has(&50));
    }
}

خوش آمد

با احتساب استراحت‌های ۱۰ دقیقه‌ای، این جلسه باید حدود ۱ ساعت و ۵۵ دقیقه طول بکشد. این شامل:

قرض‌گیری (Borrowing)

این بخش باید حدود ۵۵ دقیقه طول بکشد. آن شامل:

قرض‌گیری یک مقدار

همان‌طور که پیش‌تر دیدیم، به جای انتقال مالکیت هنگام فراخوانی یک تابع، می‌توانید به تابع اجازه دهید که ارجاعی به مقدار داشته باشد:

#[derive(Debug)]
struct Point(i32, i32);

fn add(p1: &Point, p2: &Point) -> Point {
    Point(p1.0 + p2.0, p1.1 + p2.1)
}

fn main() {
    let p1 = Point(3, 4);
    let p2 = Point(10, 20);
    let p3 = add(&p1, &p2);
    println!("{p1:?} + {p2:?} = {p3:?}");
}

• تابع add ارجاع می‌گیرد به دو نقطه و یک نقطه جدید برمی‌گرداند.
• فراخوانی‌کننده مالکیت ورودی‌ها را حفظ می‌کند.

چک کردن قرض

بررسی‌کننده ارجاع (borrow checker) در Rust محدودیت‌هایی بر روی روش‌های ارجاع به مقادیر اعمال می‌کند. برای یک مقدار خاص، در هر زمان:

• شما می‌توانید یک یا چند ارجاع اشتراکی به مقدار داشته باشید، یا
• می‌توانید دقیقاً یک ارجاع انحصاری به مقدار داشته باشید.

fn main() {
    let mut a: i32 = 10;
    let b: &i32 = &a;

    {
        let c: &mut i32 = &mut a;
        *c = 20;
    }

    println!("a: {a}");
    println!("b: {b}");
}

خطاهای قرض‌گیری

به عنوان یک مثال ملموس از چگونگی جلوگیری از خطاهای حافظه توسط این قوانین ارجاع، به حالت تغییر یک مجموعه در حالی که ارجاعاتی به عناصر آن وجود دارد، توجه کنید:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    let elem = &vec[2];
    vec.push(6);
    println!("{elem}");
}

به طور مشابه، به وضعیت نامعتبر شدن تکرارگر (iterator) توجه کنید:

fn main() {
    let mut vec = vec![1, 2, 3, 4, 5];
    for elem in &vec {
        vec.push(elem * 2);
    }
}

تغییرپذیری داخلی

در برخی موقعیت‌ها، لازم است که داده‌های پشت یک ارجاع اشتراکی (فقط خواندنی) را تغییر دهید. به عنوان مثال، یک ساختار داده اشتراکی ممکن است دارای یک کش داخلی باشد و بخواهد این کش را از روش‌های خواندنی به‌روزرسانی کند.

الگوی "تغییرپذیری داخلی" (interior mutability) اجازه می‌دهد که دسترسی انحصاری (قابل تغییر) پشت یک ارجاع اشتراکی وجود داشته باشد. کتابخانه استاندارد روش‌های متعددی برای انجام این کار فراهم می‌کند، در حالی که همچنان ایمنی را تضمین می‌کند، معمولاً با انجام یک بررسی در زمان اجرا.

Cell

Cell wraps a value and allows getting or setting the value using only a shared reference to the Cell. However, it does not allow any references to the inner value. Since there are no references, borrowing rules cannot be broken.

use std::cell::Cell;

fn main() {
    // Note that `cell` is NOT declared as mutable.
    let cell = Cell::new(5);

    cell.set(123);
    println!("{}", cell.get());
}

RefCell

RefCell allows accessing and mutating a wrapped value by providing alternative types Ref and RefMut that emulate &T/&mut T without actually being Rust references.

این type با استفاده از یک شمارنده در RefCell بررسی‌های dynamic را انجام می‌دهند تا از وجود RefMut در کنار Ref/RefMut دیگر جلوگیری کنند.

با پیاده‌سازی Deref (و DerefMut برای RefMut)، این تایپ‌ها امکان فراخوانی متدها روی مقدار داخلی را بدون اجازه خروج ارجاع‌ها فراهم می‌کنند.

use std::cell::RefCell;

fn main() {
    // Note that `cell` is NOT declared as mutable.
    let cell = RefCell::new(5);

    {
        let mut cell_ref = cell.borrow_mut();
        *cell_ref = 123;

        // This triggers an error at runtime.
        // let other = cell.borrow();
        // println!("{}", *other);
    }

    println!("{cell:?}");
}

تمرین: آمار سلامتی

شما در حال پیاده‌سازی یک سیستم پایش سلامت هستید. به عنوان بخشی از این کار، نیاز دارید تا آمار سلامت کاربران را دنبال کنید.

شما با یک تابع ابتدایی در بلوک impl و همچنین یک تعریف struct به نام User شروع خواهید کرد. هدف شما پیاده‌سازی متد ابتدایی در struct User است که در بلوک impl تعریف شده است.

کد زیر را به https://play.rust-lang.org/ کپی کنید و متد‌های ناقص را تکمیل کنید:

// TODO: این را زمانی که پیاده‌سازی‌تان تمام شد حذف کنید.
#![allow(unused_variables, dead_code)]


#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        todo!("به‌روزرسانی آمار یک کاربر بر اساس اندازه‌گیری معبار بازدید از پزشک")
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("من {} هستم و سن من {} است", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);
    assert!((report.height_change - 0.9).abs() < 0.00001);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
    assert_eq!(report.height_change, 0.0);
}

راه‌حل

#![allow(dead_code)]
pub struct User {
    name: String,
    age: u32,
    height: f32,
    visit_count: usize,
    last_blood_pressure: Option<(u32, u32)>,
}

pub struct Measurements {
    height: f32,
    blood_pressure: (u32, u32),
}

pub struct HealthReport<'a> {
    patient_name: &'a str,
    visit_count: u32,
    height_change: f32,
    blood_pressure_change: Option<(i32, i32)>,
}

impl User {
    pub fn new(name: String, age: u32, height: f32) -> Self {
        Self { name, age, height, visit_count: 0, last_blood_pressure: None }
    }

    pub fn visit_doctor(&mut self, measurements: Measurements) -> HealthReport {
        self.visit_count += 1;
        let bp = measurements.blood_pressure;
        let report = HealthReport {
            patient_name: &self.name,
            visit_count: self.visit_count as u32,
            height_change: measurements.height - self.height,
            blood_pressure_change: match self.last_blood_pressure {
                Some(lbp) => {
                    Some((bp.0 as i32 - lbp.0 as i32, bp.1 as i32 - lbp.1 as i32))
                }
                None => None,
            },
        };
        self.height = measurements.height;
        self.last_blood_pressure = Some(bp);
        report
    }
}

fn main() {
    let bob = User::new(String::from("Bob"), 32, 155.2);
    println!("من {} هستم و سن من {} است", bob.name, bob.age);
}

#[test]
fn test_visit() {
    let mut bob = User::new(String::from("Bob"), 32, 155.2);
    assert_eq!(bob.visit_count, 0);
    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (120, 80) });
    assert_eq!(report.patient_name, "Bob");
    assert_eq!(report.visit_count, 1);
    assert_eq!(report.blood_pressure_change, None);
    assert!((report.height_change - 0.9).abs() < 0.00001);

    let report =
        bob.visit_doctor(Measurements { height: 156.1, blood_pressure: (115, 76) });

    assert_eq!(report.visit_count, 2);
    assert_eq!(report.blood_pressure_change, Some((-5, -4)));
    assert_eq!(report.height_change, 0.0);
}

طول‌عمر

این بخش حدود ۵۰ دقیقه طول خواهد کشید. شامل موارد زیر است:

تفسیر‌های طول عمر

یک مرجع دارای طول عمر است که نباید از ارزش مورد اشاره بیشتر باشد. این موضوع توسط بررسی‌کننده قرض‌ها تایید می‌شود.

طول عمر می‌تواند ضمنی باشد - این همان چیزی است که تا کنون مشاهده کرده‌ایم. طول عمرها می‌توانند صریح نیز باشند: &'a Point، &'document str. طول عمرها با ' شروع می‌شوند و 'a نام پیش‌فرض معمولی است. &'a Point را به عنوان "یک Point قرضی که برای حداقل طول عمر a معتبر است" بخوانید.

طول عمرها همیشه توسط کامپایلر استنتاج می‌شوند: شما نمی‌توانید به طور دستی طول عمر را اختصاص دهید. انتساب‌های صریح طول عمر محدودیت‌هایی ایجاد می‌کنند که در صورت وجود ابهام است؛ کامپایلر تأیید می‌کند که یک راه‌حل معتبر وجود دارد.

طول عمرها وقتی که به عبور مقادیر به توابع و بازگشت مقادیر از توابع می‌پردازیم پیچیده‌تر می‌شوند.

#[derive(Debug)]
struct Point(i32, i32);

fn left_most(p1: &Point, p2: &Point) -> &Point {
    if p1.0 < p2.0 {
        p1
    } else {
        p2
    }
}

fn main() {
    let p1: Point = Point(10, 10);
    let p2: Point = Point(20, 20);
    let p3 = left_most(&p1, &p2); // What is the lifetime of p3?
    println!("p3: {p3:?}");
}

fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {

طول عمر در فراخوانی‌ توابع

عمرهای مربوط به آرگومان‌های تابع و مقادیر بازگشتی باید به طور کامل مشخص شوند، اما Rust اجازه می‌دهد عمرها در بیشتر موارد با چند قانون ساده نادیده گرفته شوند. این مسئله استنتاج نیست -- بلکه تنها یک اصطلاح نوشتاری کوتاه است.

• هر آرگومان که فاقد یک lifetime annotation است، یک عمر به آن اختصاص داده می‌شود.
• اگر تنها یک عمر برای آرگومان وجود داشته باشد، به تمام مقادیر بازگشتی که حاشیه‌نویسی نشده‌اند، اختصاص داده می‌شود.
• اگر چندین عمر آرگومان وجود داشته باشد و اولین آن برای self باشد، آن عمر به تمام مقادیر بازگشتی که حاشیه‌نویسی نشده‌اند، اختصاص داده می‌شود.

#[derive(Debug)]
struct Point(i32, i32);

fn cab_distance(p1: &Point, p2: &Point) -> i32 {
    (p1.0 - p2.0).abs() + (p1.1 - p2.1).abs()
}

fn nearest<'a>(points: &'a [Point], query: &Point) -> Option<&'a Point> {
    let mut nearest = None;
    for p in points {
        if let Some((_, nearest_dist)) = nearest {
            let dist = cab_distance(p, query);
            if dist < nearest_dist {
                nearest = Some((p, dist));
            }
        } else {
            nearest = Some((p, cab_distance(p, query)));
        };
    }
    nearest.map(|(p, _)| p)
}

fn main() {
    println!(
        "{:?}",
        nearest(
            &[Point(1, 0), Point(1, 0), Point(-1, 0), Point(0, -1),],
            &Point(0, 2)
        )
    );
}

fn nearest<'a, 'q>(points: &'a [Point], query: &'q Point) -> Option<&'q Point> {

Lifetimes in Data Structures

اگر یک تایپ داده داده‌های قرضی را ذخیره کند، باید با یک طول عمر مشخص شود:

#[derive(Debug)]
struct Highlight<'doc>(&'doc str);

fn erase(text: String) {
    println!("Bye {text}!");
}

fn main() {
    let text = String::from("The quick brown fox jumps over the lazy dog.");
    let fox = Highlight(&text[4..19]);
    let dog = Highlight(&text[35..43]);
    // erase(text);
    println!("{fox:?}");
    println!("{dog:?}");
}

تمرین: تجزیه Protobuf

در این تمرین، شما یک تجزیه‌کننده برای رمزگذاری باینری پروتوباف خواهید ساخت. نگران نباشید، این کار ساده‌تر از آن است که به نظر می‌رسد! این الگو نشان‌دهنده یک الگوی رایج در تجزیه داده‌ها است که شامل عبور برش‌های داده است. داده‌های اصلی هرگز کپی نمی‌شوند.

تجزیه کامل یک پیام پروتوباف نیاز به دانستن تایپ‌های این فیلدها دارد که بر اساس شماره‌های فیلد ایندکس شده‌اند. این اطلاعات معمولاً در یک فایل proto ارائه می‌شود. در این تمرین، ما این اطلاعات را به صورت عبارات match در توابعی که برای هر فیلد فراخوانی می‌شوند، کدگذاری خواهیم کرد.

ما از پروتوباف زیر استفاده خواهیم کرد:

message PhoneNumber {
  optional string number = 1;
  optional string type = 2;
}

message Person {
  optional string name = 1;
  optional int32 id = 2;
  repeated PhoneNumber phones = 3;
}

یک پیام پروتوباف به عنوان مجموعه‌ای از فیلدها، یکی پس از دیگری، کدگذاری می‌شود. هر فیلد به صورت یک "تگ" به همراه مقدار آن پیاده‌سازی شده است. تگ شامل شماره فیلد (مانند 2 برای فیلد id در پیام Person) و wire type است که نحوه تعیین بار را از جریان بایت مشخص می‌کند.

اعداد، از جمله تگ، با استفاده از کدگذاری با طول متغیر به نام VARINT نمایندگی می‌شوند. خوشبختانه، تابع parse_varint برای شما تعریف شده است. کد داده شده همچنین بازخوانی‌هایی برای مدیریت فیلدهای Person و PhoneNumber و تجزیه یک پیام به مجموعه‌ای از فراخوانی‌ها به آن بازخوانی‌ها را تعریف می‌کند.

برای شما باقی‌مانده است که تابع parse_field و ویژگی ProtoMessage را برای Person و PhoneNumber پیاده‌سازی کنید.

/// A wire type as seen on the wire.
enum WireType {
    /// The Varint WireType indicates the value is a single VARINT.
    Varint,
    /// The I64 WireType indicates that the value is precisely 8 bytes in
    /// little-endian order containing a 64-bit signed integer or double type.
    //I64,  -- not needed for this exercise
    /// The Len WireType indicates that the value is a length represented as a
    /// VARINT followed by exactly that number of bytes.
    Len,
    // The I32 WireType indicates that the value is precisely 4 bytes in
    // little-endian order containing a 32-bit signed integer or float type.
    //I32,  -- not needed for this exercise
}

#[derive(Debug)]
/// A field's value, typed based on the wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- not needed for this exercise
    Len(&'a [u8]),
    //I32(i32),  -- not needed for this exercise
}

#[derive(Debug)]
/// A field, containing the field number and its value.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- not needed for this exercise
            2 => WireType::Len,
            //5 => WireType::I32,  -- not needed for this exercise
            _ => panic!("نوع سیم نامعتبر: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("انتظار می‌رود که رشته یک فیلد Len باشد");
        };
        std::str::from_utf8(data).expect("نامعتبر string")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("بایت‌های مورد انتظار یک فیلد `Len` باشند");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("انتظار می‌رود `u64` یک فیلد `Varint` باشد");
        };
        *value
    }
}

/// Parse a VARINT, returning the parsed value and the remaining bytes.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("بایت کافی برای varint نیست");
        };
        if b & 0x80 == 0 {
            // This is the last byte of the VARINT, so convert it to
            // a u64 and return it.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // More than 7 bytes is invalid.
    panic!("تعداد بایت‌های زیادی برای varint");
}

/// Convert a tag into a field number and a WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}


/// Parse a field, returning the remaining bytes
fn parse_field(data: &[u8]) -> (Field, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        _ => todo!("بر اساس نوع سیم، یک فیلد بسازید، با مصرف هر تعداد بایت که لازم است.")
    };
    todo!("فیلد و هر بایت مصرف نشده را برگردانید.")
}

/// Parse a message in the given data, calling `T::add_field` for each field in
/// the message.
///
/// The entire input is consumed.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}



#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

// TODO: Implement ProtoMessage for Person and PhoneNumber.

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    println!("{:#?}", person);
}

راه‌حل

/// A wire type as seen on the wire.
enum WireType {
    /// The Varint WireType indicates the value is a single VARINT.
    Varint,
    /// The I64 WireType indicates that the value is precisely 8 bytes in
    /// little-endian order containing a 64-bit signed integer or double type.
    //I64,  -- not needed for this exercise
    /// The Len WireType indicates that the value is a length represented as a
    /// VARINT followed by exactly that number of bytes.
    Len,
    // The I32 WireType indicates that the value is precisely 4 bytes in
    // little-endian order containing a 32-bit signed integer or float type.
    //I32,  -- not needed for this exercise
}

#[derive(Debug)]
/// A field's value, typed based on the wire type.
enum FieldValue<'a> {
    Varint(u64),
    //I64(i64),  -- not needed for this exercise
    Len(&'a [u8]),
    //I32(i32),  -- not needed for this exercise
}

#[derive(Debug)]
/// A field, containing the field number and its value.
struct Field<'a> {
    field_num: u64,
    value: FieldValue<'a>,
}

trait ProtoMessage<'a>: Default {
    fn add_field(&mut self, field: Field<'a>);
}

impl From<u64> for WireType {
    fn from(value: u64) -> Self {
        match value {
            0 => WireType::Varint,
            //1 => WireType::I64,  -- not needed for this exercise
            2 => WireType::Len,
            //5 => WireType::I32,  -- not needed for this exercise
            _ => panic!("نوع سیم نامعتبر: {value}"),
        }
    }
}

impl<'a> FieldValue<'a> {
    fn as_str(&self) -> &'a str {
        let FieldValue::Len(data) = self else {
            panic!("انتظار می‌رود که رشته یک فیلد Len باشد");
        };
        std::str::from_utf8(data).expect("نامعتبر string")
    }

    fn as_bytes(&self) -> &'a [u8] {
        let FieldValue::Len(data) = self else {
            panic!("بایت‌های مورد انتظار یک فیلد `Len` باشند");
        };
        data
    }

    fn as_u64(&self) -> u64 {
        let FieldValue::Varint(value) = self else {
            panic!("انتظار می‌رود `u64` یک فیلد `Varint` باشد");
        };
        *value
    }
}

/// Parse a VARINT, returning the parsed value and the remaining bytes.
fn parse_varint(data: &[u8]) -> (u64, &[u8]) {
    for i in 0..7 {
        let Some(b) = data.get(i) else {
            panic!("بایت کافی برای varint نیست");
        };
        if b & 0x80 == 0 {
            // This is the last byte of the VARINT, so convert it to
            // a u64 and return it.
            let mut value = 0u64;
            for b in data[..=i].iter().rev() {
                value = (value << 7) | (b & 0x7f) as u64;
            }
            return (value, &data[i + 1..]);
        }
    }

    // More than 7 bytes is invalid.
    panic!("تعداد بایت‌های زیادی برای varint");
}

/// Convert a tag into a field number and a WireType.
fn unpack_tag(tag: u64) -> (u64, WireType) {
    let field_num = tag >> 3;
    let wire_type = WireType::from(tag & 0x7);
    (field_num, wire_type)
}

/// Parse a field, returning the remaining bytes
fn parse_field(data: &[u8]) -> (Field, &[u8]) {
    let (tag, remainder) = parse_varint(data);
    let (field_num, wire_type) = unpack_tag(tag);
    let (fieldvalue, remainder) = match wire_type {
        WireType::Varint => {
            let (value, remainder) = parse_varint(remainder);
            (FieldValue::Varint(value), remainder)
        }
        WireType::Len => {
            let (len, remainder) = parse_varint(remainder);
            let len: usize = len.try_into().expect("استفاده از len در `usize` معتبر نیست");
            if remainder.len() < len {
                panic!("EOF غیر منتظره");
            }
            let (value, remainder) = remainder.split_at(len);
            (FieldValue::Len(value), remainder)
        }
    };
    (Field { field_num, value: fieldvalue }, remainder)
}

/// Parse a message in the given data, calling `T::add_field` for each field in
/// the message.
///
/// The entire input is consumed.
fn parse_message<'a, T: ProtoMessage<'a>>(mut data: &'a [u8]) -> T {
    let mut result = T::default();
    while !data.is_empty() {
        let parsed = parse_field(data);
        result.add_field(parsed.0);
        data = parsed.1;
    }
    result
}

#[derive(PartialEq)]
#[derive(Debug, Default)]
struct PhoneNumber<'a> {
    number: &'a str,
    type_: &'a str,
}

#[derive(PartialEq)]
#[derive(Debug, Default)]
struct Person<'a> {
    name: &'a str,
    id: u64,
    phone: Vec<PhoneNumber<'a>>,
}

impl<'a> ProtoMessage<'a> for Person<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.name = field.value.as_str(),
            2 => self.id = field.value.as_u64(),
            3 => self.phone.push(parse_message(field.value.as_bytes())),
            _ => {} // skip everything else
        }
    }
}

impl<'a> ProtoMessage<'a> for PhoneNumber<'a> {
    fn add_field(&mut self, field: Field<'a>) {
        match field.field_num {
            1 => self.number = field.value.as_str(),
            2 => self.type_ = field.value.as_str(),
            _ => {} // skip everything else
        }
    }
}

fn main() {
    let person: Person = parse_message(&[
        0x0a, 0x07, 0x6d, 0x61, 0x78, 0x77, 0x65, 0x6c, 0x6c, 0x10, 0x2a, 0x1a,
        0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x30, 0x32, 0x2d, 0x35, 0x35, 0x35,
        0x2d, 0x31, 0x32, 0x31, 0x32, 0x12, 0x04, 0x68, 0x6f, 0x6d, 0x65, 0x1a,
        0x18, 0x0a, 0x0e, 0x2b, 0x31, 0x38, 0x30, 0x30, 0x2d, 0x38, 0x36, 0x37,
        0x2d, 0x35, 0x33, 0x30, 0x38, 0x12, 0x06, 0x6d, 0x6f, 0x62, 0x69, 0x6c,
        0x65,
    ]);
    println!("{:#?}", person);
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_id() {
        let person_id: Person = parse_message(&[0x10, 0x2a]);
        assert_eq!(person_id, Person { name: ".", id: 42, phone: vec![] });
    }

    #[test]
    fn test_name() {
        let person_name: Person = parse_message(&[
            0x0a, 0x0e, 0x62, 0x65, 0x61, 0x75, 0x74, 0x69, 0x66, 0x75, 0x6c, 0x20,
            0x6e, 0x61, 0x6d, 0x65,
        ]);
        assert_eq!(
            person_name,
            Person { name: "beautiful name", id: 0, phone: vec![] }
        );
    }

    #[test]
    fn test_just_person() {
        let person_name_id: Person =
            parse_message(&[0x0a, 0x04, 0x45, 0x76, 0x61, 0x6e, 0x10, 0x16]);
        assert_eq!(person_name_id, Person { name: "Evan", id: 22, phone: vec![] });
    }

    #[test]
    fn test_phone() {
        let phone: Person = parse_message(&[
            0x0a, 0x00, 0x10, 0x00, 0x1a, 0x16, 0x0a, 0x0e, 0x2b, 0x31, 0x32, 0x33,
            0x34, 0x2d, 0x37, 0x37, 0x37, 0x2d, 0x39, 0x30, 0x39, 0x30, 0x12, 0x04,
            0x68, 0x6f, 0x6d, 0x65,
        ]);
        assert_eq!(
            phone,
            Person {
                name: ".",
                id: 0,
                phone: vec![PhoneNumber { number: "+1234-777-9090", type_: "خانه" },],
            }
        );
    }
}

Welcome to Day 4

امروز ما موضوعات مربوط به ساخت نرم افزار در مقیاس بزرگ در Rust را پوشش خواهیم داد:

• Iterators: شیرجه عمیق در ویژگی Iterator.
• ماژول ها و قابلیت مشاهده.
• تست‌کردن.
• رسیدگی به خطا: panics در Result و اپراتور تلاش مجدد ?.
• با Unsafe Rust: پنجره فرار مبتنی بر زمان که نمی‌توانید خود را در safe Rust بیان کنید.

برنامه زمانی

با احتساب ۱۰ دقیقه استراحت، این جلسه باید حدود ۲ ساعت و ۴۰ دقیقه طول بکشد. شامل:

Iterators

این بخش باید حدود ۴۵ دقیقه طول بکشد. آن شامل:

Iterator

ویژگی 'Iterator' از تکرار بیش از مقادیر در یک مجموعه پشتیبانی می‌کند. این به یک متد next نیاز دارد و متدهای زیادی را ارائه می‌کند. بسیاری از انواع کتابخانه استاندارد Iterator را پیاده‌سازی می‌کنند و شما نیز می‌توانید آن را خودتان پیاده‌سازی کنید:

struct Fibonacci {
    curr: u32,
    next: u32,
}

impl Iterator for Fibonacci {
    type Item = u32;

    fn next(&mut self) -> Option<Self::Item> {
        let new_next = self.curr + self.next;
        self.curr = self.next;
        self.next = new_next;
        Some(self.curr)
    }
}

fn main() {
    let fib = Fibonacci { curr: 0, next: 1 };
    for (i, n) in fib.enumerate().take(5) {
        println!("fib({i}): {n}");
    }
}

IntoIterator

ویژگی Iterator به شما می‌گوید که چگونه پس از ایجاد یک تکرار کننده، iterate کنید. ویژگی مرتبط IntoIterator نحوه ایجاد یک تکرار کننده برای یک نوع را مشخص می‌کند. به طور خودکار توسط حلقه for استفاده می‌شود.

struct Grid {
    x_coords: Vec<u32>,
    y_coords: Vec<u32>,
}

impl IntoIterator for Grid {
    type Item = (u32, u32);
    type IntoIter = GridIter;
    fn into_iter(self) -> GridIter {
        GridIter { grid: self, i: 0, j: 0 }
    }
}

struct GridIter {
    grid: Grid,
    i: usize,
    j: usize,
}

impl Iterator for GridIter {
    type Item = (u32, u32);

    fn next(&mut self) -> Option<(u32, u32)> {
        if self.i >= self.grid.x_coords.len() {
            self.i = 0;
            self.j += 1;
            if self.j >= self.grid.y_coords.len() {
                return None;
            }
        }
        let res = Some((self.grid.x_coords[self.i], self.grid.y_coords[self.j]));
        self.i += 1;
        res
    }
}

fn main() {
    let grid = Grid { x_coords: vec![3, 5, 7, 9], y_coords: vec![10, 20, 30, 40] };
    for (x, y) in grid {
        println!("point = {x}, {y}");
    }
}

FromIterator

گزینه FromIterator به شما امکان می دهد از یک [Iterator](https://doc.rust-lang .org/std/iter/trait.Iterator.html) یک مجموعه یا collection بسازید.

fn main() {
    let primes = vec![2, 3, 5, 7];
    let prime_squares = primes.into_iter().map(|p| p * p).collect::<Vec<_>>();
    println!("prime_squares: {prime_squares:?}");
}

fn collect<B>(self) -> B
where
    B: FromIterator<Self::Item>,
    Self: Sized

تمرین: روش Iterator Chaining

در این تمرین، باید برخی از روش های ارائه شده در Iterator را برای پیاده‌سازی یک ویژگی پیدا کنید و از آنها برای محاسبه پیچیده استفاده کنید.

کد زیر را درhttps://play.rust-lang.org/ کپی کنید و تست ها را قبول کنید. از یک عبارت تکرارکننده (iterator) استفاده کنید و نتیجه را جمع‌آوری (collect) کنید تا مقدار بازگشتی را بسازید.

#![allow(unused)]
fn main() {
/// Calculate the differences between elements of `values` offset by `offset`,
/// wrapping around from the end of `values` to the beginning.
///
/// Element `n` of the result is `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    unimplemented!()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}
}

راه‌حل

/// Calculate the differences between elements of `values` offset by `offset`,
/// wrapping around from the end of `values` to the beginning.
///
/// Element `n` of the result is `values[(n+offset)%len] - values[n]`.
fn offset_differences<N>(offset: usize, values: Vec<N>) -> Vec<N>
where
    N: Copy + std::ops::Sub<Output = N>,
{
    let a = (&values).into_iter();
    let b = (&values).into_iter().cycle().skip(offset);
    a.zip(b).map(|(a, b)| *b - *a).collect()
}

#[test]
fn test_offset_one() {
    assert_eq!(offset_differences(1, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
    assert_eq!(offset_differences(1, vec![1, 3, 5]), vec![2, 2, -4]);
    assert_eq!(offset_differences(1, vec![1, 3]), vec![2, -2]);
}

#[test]
fn test_larger_offsets() {
    assert_eq!(offset_differences(2, vec![1, 3, 5, 7]), vec![4, 4, -4, -4]);
    assert_eq!(offset_differences(3, vec![1, 3, 5, 7]), vec![6, -2, -2, -2]);
    assert_eq!(offset_differences(4, vec![1, 3, 5, 7]), vec![0, 0, 0, 0]);
    assert_eq!(offset_differences(5, vec![1, 3, 5, 7]), vec![2, 2, 2, -6]);
}

#[test]
fn test_custom_type() {
    assert_eq!(
        offset_differences(1, vec![1.0, 11.0, 5.0, 0.0]),
        vec![10.0, -6.0, -5.0, 1.0]
    );
}

#[test]
fn test_degenerate_cases() {
    assert_eq!(offset_differences(1, vec![0]), vec![0]);
    assert_eq!(offset_differences(1, vec![1]), vec![0]);
    let empty: Vec<i32> = vec![];
    assert_eq!(offset_differences(1, empty), vec![]);
}

fn main() {}

ماژول‌ها

این بخش باید حدود ۴۰ دقیقه طول بکشد. آن شامل:

ماژول‌ها

دیده‌ایم که چگونه بلوک‌های impl به ما اجازه می‌دهند تا namespace functions را به یک type تبدیل کنیم.

به طور مشابه، mod به ما اجازه می‌دهد تا توابع و namespace type به این صورت داشته باشیم:

mod foo {
    pub fn do_something() {
        println!("در ماژول foo");
    }
}

mod bar {
    pub fn do_something() {
        println!("در ماژول نواری");
    }
}

fn main() {
    foo::do_something();
    bar::do_something();
}

سلسله‌ مراتب فایل‌سیستم

حذف محتوای ماژول به Rust می‌گوید که آن را در فایل دیگری جستجو کند:

mod garden;

این به rust می‌گوید که محتوای ماژول garden درsrc/garden.rsیافت می‌شود. به طور مشابه، ماژول garden::vegetables را می‌توان در src/garden/vegetables.rs یافت.

ریشهcrate در:

• src/lib.rs (for a library crate)
• src/main.rs (for a binary crate)

ماژول‌های تعریف‌شده در فایل‌ها را نیز می‌توان با استفاده از «کامنت‌های مستند داخلی» مستند کرد. اینها موردی را که حاوی آنها است - در این مورد، یک ماژول مستند می‌کنند.

//! This module implements the garden, including a highly performant germination
//! implementation.

// Re-export types from this module.
pub use garden::Garden;
pub use seeds::SeedPacket;

/// Sow the given seed packets.
pub fn sow(seeds: Vec<SeedPacket>) {
    todo!()
}

/// Harvest the produce in the garden that is ready.
pub fn harvest(garden: &mut Garden) {
    todo!()
}

قابلیت دید

ماژول‌ها یک مرز حریم خصوصی هستند:

• گزینه‌های ماژول به طور پیش‌فرض private هستند (جزئیات پیاده سازی را پنهان می‌کند).
• کزینه‌های sibling و sibling همیشه قابل مشاهده است.
• به عبارت دیگر، اگر یک مورد در ماژول foo قابل مشاهده باشد، در همه فرزندانfoo قابل مشاهده است.

mod outer {
    fn private() {
        println!("outer::private");
    }

    pub fn public() {
        println!("outer::public");
    }

    mod inner {
        fn private() {
            println!("outer::inner::private");
        }

        pub fn public() {
            println!("outer::inner::public");
            super::private();
        }
    }
}

fn main() {
    outer::public();
}

use, super, self

یک ماژول می‌تواند نمادها را از ماژول دیگری با use وارد محدوده کند. شما معمولاً چیزی شبیه به این را در بالای هر ماژول خواهید دید:

use std::collections::HashSet;
use std::process::abort;

مسیر

مسیرها (Paths) به شرح زیر حل می‌شوند:

1. به عنوان یک path نسبی:

   • در واقع foo یا self::foo به foo در ماژول فعلی اشاره دارد،
   • super::foo refers to foo in the parent module.

2. به عنوان یک path مطلق:

   • crate::foo به foo در ریشه جعبه فعلی اشاره دارد,
   • یک bar::foo به foo در bar crate اشاره دارد.

تمرین: ماژولهایی برای کتابخانه رابط کاربری گرافیکی

در این تمرین، یک پیاده‌سازی کتابخانه GUI کوچک را دوباره سازماندهی خواهید کرد. این کتابخانه یک ویژگیWidget و چند پیاده‌سازی از آن ویژگی و همچنین یک تابع main را تعریف می‌کند.

معمول است که هر نوع یا مجموعه‌ای از انواع مرتبط نزدیک را در ماژول خود قرار دهید، بنابراین هر نوع ویجت باید ماژول خاص خود را داشته باشد.

Cargo Setup

یک Rust playground فقط از یک فایل پشتیبانی می‌کند، بنابراین باید یک پروژه Cargo را در سیستم فایل محلی خود ایجاد کنید:

cargo init gui-modules
cd gui-modules
cargo run

این src/main.rs حاصل را ویرایش کنید تا عبارات mod را اضافه کنید و فایل‌های اضافی را در دایرکتوری src اضافه کنید.

منبع

در اینجا اجرای تک ماژول کتابخانه GUI آمده است:

pub trait Widget {
    /// Natural width of `self`.
    fn width(&self) -> usize;

    /// Draw the widget into a buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Draw the widget on standard output.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub struct Label {
    label: String,
}

impl Label {
    fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

pub struct Button {
    label: Label,
}

impl Button {
    fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // Add 4 paddings for borders
        self.inner_width() + 4
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: Change draw_into to return Result<(), std::fmt::Error>. Then use the
        // ?-operator here instead of .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", ".").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", ".").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", ".").unwrap();
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        self.label.width() + 8 // add a bit of padding
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", ".").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", ".").unwrap();
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

fn main() {
    let mut window = Window::new("Rust GUI Demo 1.23");
    window.add_widget(Box::new(Label::new("این یک نسخه نمایشی GUI برای متنی کوچک است.")));
    window.add_widget(Box::new(Button::new("Click me!")));
    window.draw();
}

راه‌حل

src
├── main.rs
├── widgets
│   ├── button.rs
│   ├── label.rs
│   └── window.rs
└── widgets.rs

// ---- src/widgets.rs ----
mod button;
mod label;
mod window;

pub trait Widget {
    /// Natural width of `self`.
    fn width(&self) -> usize;

    /// Draw the widget into a buffer.
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write);

    /// Draw the widget on standard output.
    fn draw(&self) {
        let mut buffer = String::new();
        self.draw_into(&mut buffer);
        println!("{buffer}");
    }
}

pub use button::Button;
pub use label::Label;
pub use window::Window;

// ---- src/widgets/label.rs ----
use super::Widget;

pub struct Label {
    label: String,
}

impl Label {
    pub fn new(label: &str) -> Label {
        Label { label: label.to_owned() }
    }
}

impl Widget for Label {
    fn width(&self) -> usize {
        // ANCHOR_END: Label-width
        self.label.lines().map(|line| line.chars().count()).max().unwrap_or(0)
    }

    // ANCHOR: Label-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Label-draw_into
        writeln!(buffer, "{}", &self.label).unwrap();
    }
}

// ---- src/widgets/button.rs ----
use super::{Label, Widget};

pub struct Button {
    label: Label,
}

impl Button {
    pub fn new(label: &str) -> Button {
        Button { label: Label::new(label) }
    }
}

impl Widget for Button {
    fn width(&self) -> usize {
        // ANCHOR_END: Button-width
        self.label.width() + 8 // add a bit of padding
    }

    // ANCHOR: Button-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Button-draw_into
        let width = self.width();
        let mut label = String::new();
        self.label.draw_into(&mut label);

        writeln!(buffer, "+{:-<width$}+", ".").unwrap();
        for line in label.lines() {
            writeln!(buffer, "|{:^width$}|", &line).unwrap();
        }
        writeln!(buffer, "+{:-<width$}+", ".").unwrap();
    }
}

// ---- src/widgets/window.rs ----
use super::Widget;

pub struct Window {
    title: String,
    widgets: Vec<Box<dyn Widget>>,
}

impl Window {
    pub fn new(title: &str) -> Window {
        Window { title: title.to_owned(), widgets: Vec::new() }
    }

    pub fn add_widget(&mut self, widget: Box<dyn Widget>) {
        self.widgets.push(widget);
    }

    fn inner_width(&self) -> usize {
        std::cmp::max(
            self.title.chars().count(),
            self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),
        )
    }
}

impl Widget for Window {
    fn width(&self) -> usize {
        // ANCHOR_END: Window-width
        // Add 4 paddings for borders
        self.inner_width() + 4
    }

    // ANCHOR: Window-draw_into
    fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {
        // ANCHOR_END: Window-draw_into
        let mut inner = String::new();
        for widget in &self.widgets {
            widget.draw_into(&mut inner);
        }

        let inner_width = self.inner_width();

        // TODO: after learning about error handling, you can change
        // draw_into to return Result<(), std::fmt::Error>. Then use
        // the ?-operator here instead of .unwrap().
        writeln!(buffer, "+-{:-<inner_width$}-+", ".").unwrap();
        writeln!(buffer, "| {:^inner_width$} |", &self.title).unwrap();
        writeln!(buffer, "+={:=<inner_width$}=+", ".").unwrap();
        for line in inner.lines() {
            writeln!(buffer, "| {:inner_width$} |", line).unwrap();
        }
        writeln!(buffer, "+-{:-<inner_width$}-+", ".").unwrap();
    }
}

// ---- src/main.rs ----
mod widgets;

use widgets::Widget;

fn main() {
    let mut window = widgets::Window::new("Rust GUI Demo 1.23");
    window
        .add_widget(Box::new(widgets::Label::new("این یک نسخه نمایشی GUI برای متنی کوچک است.")));
    window.add_widget(Box::new(widgets::Button::new("Click me!")));
    window.draw();
}

تست‌کردن

این بخش باید حدود ۴۵ دقیقه طول بکشد. آن شامل:

تست‌های واحد (Unit Tests)

Rust and Cargo با یک چارچوب تست واحد ساده ارائه می شود:

• Unit tests are supported throughout your code.

• تست‌های یکپارچه‌سازی از طریق دایرکتوری tests/ پشتیبانی می‌شوند.

تست‌ها با #[test]علامت‌گذاری شده‌اند. تست‌های واحد اغلب در یک ماژول tests تودرتو قرار می‌گیرند و از #[cfg(test)] استفاده می‌کنند تا آنها را به صورت مشروط تنها در هنگام build تست‌ها کامپایل کنند.

fn first_word(text: &str) -> &str {
    match text.find(' ') {
        Some(idx) => &text[..idx],
        None => &text,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty() {
        assert_eq!(first_word("."), ".");
    }

    #[test]
    fn test_single_word() {
        assert_eq!(first_word("سلام"), "سلام");
    }

    #[test]
    fn test_multiple_words() {
        assert_eq!(first_word("سلام دنیا!"), "سلام");
    }
}

• این به شما امکان می‌دهد تا private helper را آزمایش کنید.
• ویژگی #[cfg(test)] تنها زمانی فعال است که cargo test را اجرا کنید.

انواع دیگر تست‌ها

Integration Tests

اگر می‌خواهید کتابخانه خود را به عنوان یک سرویس‌گیرنده آزمایش کنید، از تست یکپارچه‌سازی (integration test) استفاده کنید.

یک فایل .rs در زیر tests/ بسازید:

// tests/my_library.rs
use my_library::init;

#[test]
fn test_init() {
    assert!(init().is_ok());
}

این آزمایش‌ها فقط به public API مربوط به crate شما دسترسی دارند.

تست‌ سندها

زبان Rust دارای پشتیبانی داخلی برای تست‌های مستندسازی است:

#![allow(unused)]
fn main() {
/// Shortens a string to the given length.
///
/// ```
/// # use playground::shorten_string;
/// assert_eq!(shorten_string("Hello World", 5), "Hello");
/// assert_eq!(shorten_string("Hello World", 20), "Hello World");
/// ```
pub fn shorten_string(s: &str, length: usize) -> &str {
    &s[..std::cmp::min(length, s.len())]
}
}

• بلوک‌های کد در commentها /// به طور خودکار به عنوان کد Rust دیده می‌شوند.
• این کد به عنوان بخشی از cargo test کامپایل و اجرا می‌شود.
• افزودن # به کد، آن را از مستندات پنهان می‌کند، اما همچنان آن را کامپایل/اجرا می‌کند.
• کد بالا را در Rust Playground تست کنید.

کامپایلر Lints و Clippy

کامپایلر Rust پیام‌های خطای جالب و همچنین built-in lint مناسبی تولید می‌کند. Clippy که lintهای بیشتری را ارائه می‌دهد، که در گروه‌هایی سازماندهی شده‌اند که می‌توانند در هر پروژه فعال شوند.

#[deny(clippy::cast_possible_truncation)]
fn main() {
    let x = 3;
    while (x < 70000) {
        x *= 2;
    }
    println!(""X احتمالاً در یک u16 مناسب است، درست است؟ {}"X احتمالاً در یک u16 مناسب است، درست است؟ {}", x as u16);
}

تمرین: الگوریتم Luhn

الگوریتم Luhn

الگوریتم Luhn برای اعتبارسنجی شماره‌های کارت اعتباری استفاده می‌شود. این الگوریتم یک رشته را به عنوان ورودی دریافت می‌کند و برای اعتبارسنجی شماره کارت اعتباری مراحل زیر را انجام می‌دهد:

• Ignore all spaces. Reject numbers with fewer than two digits.

• با حرکت از سمت راست رشته به چپ، هر دومین رقم را دوبل کنید: برای شماره 1234، 3 و 1 را دوبل می‌کنیم. برای شماره 98765، 6 و 8 را دوبل می‌کنیم.

• پس از دوبل کردن یک عدد، اگر اون جفت خروجی بیش از 9 باشد، ارقام را جمع کنید. بنابراین، دوبل کردن 7 به 14 تبدیل می‌شود که به 1 + 4 = 5 تبدیل می‌شود.

• تمام ارقام دو برابر نشده و دو برابر شده را جمع کنید.

• اگر مجموع با ‍0 خاتمه یابد، شماره کارت اعتباری معتبر است.

کد ارائه شده یک پیاده‌سازی باگ از الگوریتم luhn را به همراه دو unit test پایه ارائه می‌کند که تأیید می‌کند بیشتر الگوریتم به درستی پیاده‌سازی شده است.

Copy the code below to https://play.rust-lang.org/ and write additional tests to uncover bugs in the provided implementation, fixing any bugs you find.

#![allow(unused)]
fn main() {
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }
}
}

راه‌حل

// This is the buggy version that appears in the problem.
#[cfg(never)]
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else {
            continue;
        }
    }

    sum % 10 == 0
}

// This is the solution and passes all of the tests below.
pub fn luhn(cc_number: &str) -> bool {
    let mut sum = 0;
    let mut double = false;
    let mut digits = 0;

    for c in cc_number.chars().rev() {
        if let Some(digit) = c.to_digit(10) {
            digits += 1;
            if double {
                let double_digit = digit * 2;
                sum +=
                    if double_digit > 9 { double_digit - 9 } else { double_digit };
            } else {
                sum += digit;
            }
            double = !double;
        } else if c.is_whitespace() {
            continue;
        } else {
            return false;
        }
    }

    digits >= 2 && sum % 10 == 0
}

fn main() {
    let cc_number = "1234 5678 1234 5670";
    println!(
        "آیا {cc_number} یک شماره کارت اعتباری معتبر است؟ {}",
        if luhn(cc_number) { "بله" } else { "نه" }
    );
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_valid_cc_number() {
        assert!(luhn("4263 9826 4026 9299"));
        assert!(luhn("4539 3195 0343 6467"));
        assert!(luhn("7992 7398 713"));
    }

    #[test]
    fn test_invalid_cc_number() {
        assert!(!luhn("4223 9826 4026 9299"));
        assert!(!luhn("4539 3195 0343 6476"));
        assert!(!luhn("8273 1232 7352 0569"));
    }

    #[test]
    fn test_non_digit_cc_number() {
        assert!(!luhn("foo"));
        assert!(!luhn("foo 0 0"));
    }

    #[test]
    fn test_empty_cc_number() {
        assert!(!luhn("."));
        assert!(!luhn(" "));
        assert!(!luhn("  "));
        assert!(!luhn("    "));
    }

    #[test]
    fn test_single_digit_cc_number() {
        assert!(!luhn("0"));
    }

    #[test]
    fn test_two_digit_cc_number() {
        assert!(luhn(" 0 0 "));
    }
}

خوش آمد

Including 10 minute breaks, this session should take about 2 hours and 15 minutes. It contains:

مدیریت خطا

این بخش باید حدود ۱ ساعت طول بکشد. این شامل:

در مورد Panicها

Rust خطاهای مهلک را با "panic" کنترل می‌کند.

اگر یک خطای مرگبار در زمان اجرا رخ دهد، Rust باعث panic می‌شود:

fn main() {
    let v = vec![10, 20, 30];
    println!("v[100]: {}", v[100]);
}

• استفاده از Panicها برای خطاهای غیر قابل جبران و غیرمنتظره است.
  • پانیک‌ها علائم باگ در برنامه هستند.
  • خرابی‌های زمان اجرا مانند failed bounds checkها می‌تواند باعث panic شود
  • Assertions (such as assert!) panic on failure
  • پنیک‌های خاص می‌توانند از ماکرو panic! استفاده کنند.
• یک panic را "باز" ​​می‌کند و مقادیر را حذف می‌کند درست مثل اینکه توابع برگشته باشند.
• اگر خرابی قابل قبول نیست، از APIهای بدون panic (مانند Vec::get) استفاده کنید.

use std::panic;

fn main() {
    let result = panic::catch_unwind(|| "اینجا مشکلی نیست!");
    println!("{result:?}");

    let result = panic::catch_unwind(|| {
        panic!("oh no!");
    });
    println!("{result:?}");
}

Result

مکانیسم اصلی ما برای مدیریت خطا در Rust، فهرست Result است، که به طور خلاصه هنگام بحث در مورد تایپ‌های کتابخانه استاندارد مشاهده کردیم.

use std::fs::File;
use std::io::Read;

fn main() {
    let file: Result<File, std::io::Error> = File::open("diary.txt");
    match file {
        Ok(mut file) => {
            let mut contents = String::new();
            if let Ok(bytes) = file.read_to_string(&mut contents) {
                println!("دفتر خاطرات عزیز: {contents} ({bytes} bytes)");
            } else {
                println!("نمی‌توان محتوای فایل را خواند");
            }
        }
        Err(err) => {
            println!("دفتر خاطرات باز نشد: {err}");
        }
    }
}

عملگرد Try

خطاهای زمان اجرا مانند connection-refused یا file-not-found با نوع «نتیجه» مدیریت می‌شوند، اما تطبیق این نوع در هر تماس می‌تواند دشوار باشد. اپراتور ? برای برگرداندن خطاها به تماس گیرنده استفاده می‌شود. این به شما امکان می‌دهد تا موارد مشترک را بازگردانید.

match some_expression {
    Ok(value) => value,
    Err(err) => return Err(err),
}

بسیار ساده‌تر

some_expression?

می‌توانیم از این برای ساده‌سازی کد رسیدگی به خطا استفاده کنیم:

use std::io::Read;
use std::{fs, io};

fn read_username(path: &str) -> Result<String, io::Error> {
    let username_file_result = fs::File::open(path);
    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(err) => return Err(err),
    };

    let mut username = String::new();
    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(err) => Err(err),
    }
}

fn main() {
    //fs::write("config.dat", "alice").unwrap();
    let username = read_username("config.dat");
    println!("نام‌کاربری یا خطا: {username:?}");
}

این تبدیل‌ها (Conversions) را امتحان کنید

گسترش مؤثر ? کمی پیچیده‌تر از آنچه قبلاً ذکر شد است:

expression?

به طو مشابه کار می‌کند

match expression {
    Ok(value) => value,
    Err(err)  => return Err(From::from(err)),
}

فراخوانی From::from در اینجا به این معنی است که ما سعی می کنیم نوع خطا را به نوع بازگشتی توسط تابع تبدیل کنیم. این باعث می‌شود که خطاها به خطاهای سطح بالاتر کپسوله شوند.

مثال

use std::error::Error;
use std::fmt::{self, Display, Formatter};
use std::fs::File;
use std::io::{self, Read};

#[derive(Debug)]
enum ReadUsernameError {
    IoError(io::Error),
    EmptyUsername(String),
}

impl Error for ReadUsernameError {}

impl Display for ReadUsernameError {
    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
        match self {
            Self::IoError(e) => write!(f, "IO error: {e}"),
            Self::EmptyUsername(path) => write!(f, "در این  {path} نام کاربری یافت نشد"),
        }
    }
}

impl From<io::Error> for ReadUsernameError {
    fn from(err: io::Error) -> Self {
        Self::IoError(err)
    }
}

fn read_username(path: &str) -> Result<String, ReadUsernameError> {
    let mut username = String::with_capacity(100);
    File::open(path)?.read_to_string(&mut username)?;
    if username.is_empty() {
        return Err(ReadUsernameError::EmptyUsername(String::from(path)));
    }
    Ok(username)
}

fn main() {
    //std::fs::write("config.dat", "").unwrap();
    let username = read_username("config.dat");
    println!("نام‌کاربری یا خطا: {username:?}");
}

انواع خطاهای Dynamic

گاهی اوقات می‌خواهیم اجازه دهیم هر نوع خطای بدون نوشتن enum خودمان که تمام احتمالات مختلف را پوشش می‌دهد، برگردانده شود. ویژگی std::error::Error ایجاد یک object مشخ استه که می‌تواند حاوی هر خطایی باشد را آسان می‌کند.

use std::error::Error;
use std::fs;
use std::io::Read;

fn read_count(path: &str) -> Result<i32, Box<dyn Error>> {
    let mut count_str = String::new();
    fs::File::open(path)?.read_to_string(&mut count_str)?;
    let count: i32 = count_str.parse()?;
    Ok(count)
}

fn main() {
    fs::write("count.dat", "1i3").unwrap();
    match read_count("count.dat") {
        Ok(count) => println!("تعداد: {count}"),
        Err(err) => println!("Error: {err}"),
    }
}

thiserror و anyhow

این thiserror و anyhow crateها به طور گسترده ای برای ساده کردن رسیدگی به خطا استفاده می‌شوند.

• thiserror is often used in libraries to create custom error types that implement From<T>.
• اغلب anyhow توسط برنامه‌ها برای کمک به مدیریت خطا در توابع، از جمله افزودن اطلاعات متنی به خطاهای شما، استفاده می‌شود.

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[error("هیچ نام‌کاربری در {0} یافت نشد")]
struct EmptyUsernameError(String);

fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("{path} باز نشد"))?
        .read_to_string(&mut username)
        .context("شکست در خواندن")?;
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("نام‌کاربری: {username}"),
        Err(err) => println!("Error: {err:?}"),
    }
}

تمرین: بازنویسی با Result

در زیر یک تجزیه‌کننده بسیار ساده برای یک زبان عبارت پیاده‌سازی می‌کند. با این حال، با panic خطاها را کنترل می‌کند. آن را بازنویسی کنید تا به جای آن از مدیریت خطای اصطلاحی استفاده کنید و خطاها را به بازگشت از main منتشر کنید. با خیال راحت از thiserror و anyhow استفاده کنید.

نکته: با رفع خطا در عملکرد parse شروع کنید. هنگامی که به درستی کار کرد، Tokenizer را برای پیاده‌سازی Iterator<Item=Result<Token, TokenizerError>> به‌روزرسانی کنید و آن را در parser کنترل کنید.

use std::iter::Peekable;
use std::str::Chars;

/// An arithmetic operator.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// A token in the expression language.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// An expression in the expression language.
#[derive(Debug, PartialEq)]
enum Expression {
    /// A reference to a variable.
    Var(String),
    /// A literal number.
    Number(u32),
    /// A binary operation.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Token;

    fn next(&mut self) -> Option<Token> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(self.collect_number(c)),
            'a'..='z' => Some(self.collect_identifier(c)),
            '+' => Some(Token::Operator(Op::Add)),
            '-' => Some(Token::Operator(Op::Sub)),
            _ => panic!("کاراکتر غیرمنتظره {c}"),
        }
    }
}

fn parse(input: &str) -> Expression {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(tokens: &mut Tokenizer<'a>) -> Expression {
        let Some(tok) = tokens.next() else {
            panic!("پایان غیرمنتظره در ورودی");
        };
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse().expect("عدد صحیح 32-bit  نامعتبر");
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => panic!("توکن غیرمنتظره {tok:?}"),
        };
        // Look ahead to parse a binary operation if present.
        match tokens.next() {
            None => expr,
            Some(Token::Operator(op)) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)),
            ),
            Some(tok) => panic!("توکن غیرمنتظره {tok:?}"),
        }
    }

    parse_expr(&mut tokens)
}

fn main() {
    let expr = parse("10+foo+20-30");
    println!("{expr:?}");
}

راه‌حل

use thiserror::Error;
use std::iter::Peekable;
use std::str::Chars;

/// An arithmetic operator.
#[derive(Debug, PartialEq, Clone, Copy)]
enum Op {
    Add,
    Sub,
}

/// A token in the expression language.
#[derive(Debug, PartialEq)]
enum Token {
    Number(String),
    Identifier(String),
    Operator(Op),
}

/// An expression in the expression language.
#[derive(Debug, PartialEq)]
enum Expression {
    /// A reference to a variable.
    Var(String),
    /// A literal number.
    Number(u32),
    /// A binary operation.
    Operation(Box<Expression>, Op, Box<Expression>),
}

fn tokenize(input: &str) -> Tokenizer {
    return Tokenizer(input.chars().peekable());
}

#[derive(Debug, Error)]
enum TokenizerError {
    #[error("کاراکتر غیرمنتظره "{0}" در ورودی")]
    UnexpectedCharacter(char),
}

struct Tokenizer<'a>(Peekable<Chars<'a>>);

impl<'a> Tokenizer<'a> {
    fn collect_number(&mut self, first_char: char) -> Token {
        let mut num = String::from(first_char);
        while let Some(&c @ '0'..='9') = self.0.peek() {
            num.push(c);
            self.0.next();
        }
        Token::Number(num)
    }

    fn collect_identifier(&mut self, first_char: char) -> Token {
        let mut ident = String::from(first_char);
        while let Some(&c @ ('a'..='z' | '_' | '0'..='9')) = self.0.peek() {
            ident.push(c);
            self.0.next();
        }
        Token::Identifier(ident)
    }
}

impl<'a> Iterator for Tokenizer<'a> {
    type Item = Result<Token, TokenizerError>;

    fn next(&mut self) -> Option<Result<Token, TokenizerError>> {
        let c = self.0.next()?;
        match c {
            '0'..='9' => Some(Ok(self.collect_number(c))),
            'a'..='z' | '_' => Some(Ok(self.collect_identifier(c))),
            '+' => Some(Ok(Token::Operator(Op::Add))),
            '-' => Some(Ok(Token::Operator(Op::Sub))),
            _ => Some(Err(TokenizerError::UnexpectedCharacter(c))),
        }
    }
}

#[derive(Debug, Error)]
enum ParserError {
    #[error("خطای توکن‌سازی: {0}")]
    TokenizerError(#[from] TokenizerError),
    #[error("پایان غیرمنتظره در ورودی")]
    UnexpectedEOF,
    #[error("توکن (token) غیرمنتظره {0:?}")]
    UnexpectedToken(Token),
    #[error("شماره نامعتبر")]
    InvalidNumber(#[from] std::num::ParseIntError),
}

fn parse(input: &str) -> Result<Expression, ParserError> {
    let mut tokens = tokenize(input);

    fn parse_expr<'a>(
        tokens: &mut Tokenizer<'a>,
    ) -> Result<Expression, ParserError> {
        let tok = tokens.next().ok_or(ParserError::UnexpectedEOF)??;
        let expr = match tok {
            Token::Number(num) => {
                let v = num.parse()?;
                Expression::Number(v)
            }
            Token::Identifier(ident) => Expression::Var(ident),
            Token::Operator(_) => return Err(ParserError::UnexpectedToken(tok)),
        };
        // Look ahead to parse a binary operation if present.
        Ok(match tokens.next() {
            None => expr,
            Some(Ok(Token::Operator(op))) => Expression::Operation(
                Box::new(expr),
                op,
                Box::new(parse_expr(tokens)?),
            ),
            Some(Err(e)) => return Err(e.into()),
            Some(Ok(tok)) => return Err(ParserError::UnexpectedToken(tok)),
        })
    }

    parse_expr(&mut tokens)
}

fn main() -> anyhow::Result<()> {
    let expr = parse("10+foo+20-30")?;
    println!("{expr:?}");
    Ok(())
}

Rust ناایمن

این بخش باید حدود ۱ ساعت و ۵ دقیقه طول بکشد.و شامل موارد زیر است:

Rust ناایمن

زبان Rust دو بخش دارد:

• در Safe Rust: حافظه ایمن یا memory safe، هیچ رفتار تعریف نشده‌ای امکان پذیر نیست.
• در Unsafe Rust: در صورت نقض پیش‌شرط‌ها، می‌تواند باعث رفتار نامشخص شود.

ما عمدتاً safe Rust را در این دوره دیدیم، اما مهم است که بدانیم Unsafe Rust چیست.

کد ناامن معمولا کوچک و ایزوله است و صحت آن باید به دقت مستند شود. معمولاً در یک لایه انتزاعی ایمن پیچیده می‌شود.

این Unsafe Rust به شما امکان دسترسی به پنج قابلیت جدید را می‌دهد:

• اشاره‌گرهای خام.
• به متغیرهای mutable static variable تغییر دسترسی دهید.
• به فیلدهای union دسترسی پیدا کنید.
• توابع unsafe، از جمله توابع extern را فراخوانی کنید.
• ویژگی‌های unsafe را اجرا کنید.

در ادامه به طور خلاصه به قابلیت‌های unsafe می‌پردازیم. برای جزئیات کامل، لطفاً به Chapter 19.1 in the Rust Book و Rustonomicon.

عدم ارجاع به اشاره‌گرهای خام

ایجاد اشاره‌گر ایمن است، اما عدم ارجاع به آنها «ناامن» یا unsafe است:

fn main() {
    let mut s = String::from("مراقب باش!");

    let r1 = &mut s as *mut String;
    let r2 = r1 as *const String;

    // SAFETY: r1 and r2 were obtained from references and so are guaranteed to
    // be non-null and properly aligned, the objects underlying the references
    // from which they were obtained are live throughout the whole unsafe
    // block, and they are not accessed either through the references or
    // concurrently through any other pointers.
    unsafe {
        println!("r1 برابر هست: {}", *r1);
        *r1 = String::from("اوهو");
        println!("r2 برابر هست: {}", *r2);
    }

    // NOT SAFE. DO NOT DO THIS.
    /*
    let r3: &String = unsafe { &*r1 };
    drop(s);
    println!("r3 is: {}", *r3);
    */
}

متغیرهای ثابت قابل تغییر

خواندن یک متغیر استاتیک تغییرناپذیر بی‌خطر است:

static HELLO_WORLD: &str = "سلام دنیا!";

fn main() {
    println!("HELLO_WORLD: {HELLO_WORLD}");
}

با‌این‌حال، از آنجایی که شرایط رقابتی داده‌ها ممکن است رخ دهد، خواندن و نوشتن متغیرهای mutable static ناامن است:

static mut COUNTER: u32 = 0;

fn add_to_counter(inc: u32) {
    // SAFETY: There are no other threads which could be accessing `COUNTER`.
    unsafe {
        COUNTER += inc;
    }
}

fn main() {
    add_to_counter(42);

    // SAFETY: There are no other threads which could be accessing `COUNTER`.
    unsafe {
        println!("COUNTER: {COUNTER}");
    }
}

نوع داده چندگانه

همینطور Unionها مانند enum‌ها هستند، اما شما باید خودتان active field را ردیابی کنید:

#[repr(C)]
union MyUnion {
    i: u8,
    b: bool,
}

fn main() {
    let u = MyUnion { i: 42 };
    println!("int: {}", unsafe { u.i });
    println!("bool: {}", unsafe { u.b }); // Undefined behavior!
}

توابع ناامن

فراخوانی متدهای ناامن

یک function یا method را می‌توان unsafe علامت‌گذاری کرد، اگر دارای پیش‌شرط‌های اضافی باشد که باید برای جلوگیری از رفتار نامشخص رعایت کنید:

extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let emojis = "🗻∈🌏";

    // SAFETY: The indices are in the correct order, within the bounds of the
    // string slice, and lie on UTF-8 sequence boundaries.
    unsafe {
        println!("emoji: {}", emojis.get_unchecked(0..4));
        println!("emoji: {}", emojis.get_unchecked(4..7));
        println!("emoji: {}", emojis.get_unchecked(7..11));
    }

    println!("char count: {}", count_chars(unsafe { emojis.get_unchecked(0..7) }));

    // SAFETY: `abs` doesn't deal with pointers and doesn't have any safety
    // requirements.
    unsafe {
        println!("مقدار مطلق ۳- طبق C: {}", abs(-3));
    }

    // Not upholding the UTF-8 encoding requirement breaks memory safety!
    // println!("emoji: {}", unsafe { emojis.get_unchecked(0..3) });
    // println!("char count: {}", count_chars(unsafe {
    // emojis.get_unchecked(0..3) }));
}

fn count_chars(s: &str) -> usize {
    s.chars().count()
}

نوشتن متدهای ناامن

اگر عملکردهای خود را برای جلوگیری از رفتار نامشخص به شرایط خاصی نیاز دارند، می‌توانید به‌عنوانunsafe علامت‌گذاری کنید.

/// Swaps the values pointed to by the given pointers.
///
/// # Safety
///
/// The pointers must be valid and properly aligned.
unsafe fn swap(a: *mut u8, b: *mut u8) {
    let temp = *a;
    *a = *b;
    *b = temp;
}

fn main() {
    let mut a = 42;
    let mut b = 66;

    // SAFETY: ...
    unsafe {
        swap(&mut a, &mut b);
    }

    println!("a = {}, b = {}", a, b);
}

پیاده سازی صفات (Traits) ناامن

مانند توابع، اگر پیاده‌سازی باید شرایط خاصی را تضمین کند تا از رفتار نامشخص جلوگیری شود، می‌توانید یک ویژگی را به‌عنوان unsafe علامت‌گذاری کنید.

برای مثال، zerocopy crate یک ویژگی ناامن دارد که چیزی شبیه به این است:

use std::mem::size_of_val;
use std::slice;

/// ...
/// # Safety
/// The type must have a defined representation and no padding.
pub unsafe trait AsBytes {
    fn as_bytes(&self) -> &[u8] {
        unsafe {
            slice::from_raw_parts(
                self as *const Self as *const u8,
                size_of_val(self),
            )
        }
    }
}

// SAFETY: `u32` has a defined representation and no padding.
unsafe impl AsBytes for u32 {}

امن بودن FFI Wrapper

زبان Rust پشتیبانی بسیار خوبی برای فراخوانی توابع از طریق رابط تابع خارجی foreign function interface (FFI) دارد. ما از آن برای ساختن یک پوشش امن برای توابع libc استفاده می‌کنیم که از C برای خواندن نام فایل ها در یک فهرست استفاده می کنید.

شما می‌خواهید به صفحات راهنما مراجعه کنید:

• opendir(3)
• readdir(3)
• closedir(3)

همچنین می‌خواهید std::ffi را مرور کنید

شما بین تمام این typeها تبدیل خواهید کرد:

• &str to CString: you need to allocate space for a trailing \0 character,
• CString به *const i8: برای فراخوانی توابع C به یک اشاره‌گر نیاز دارید,
• از *const i8 به &CStr: به چیزی نیاز دارید که بتواند کاراکتر \0 را پیدا کند,
• &CStr به &[u8]: یک slice بایت universal interface برای «برخی داده‌های ناشناخته» است،
• از &[u8] به &OsStr: &OsStr گامی به سوی OsString است، از OsStrExt برای ایجاد آن استفاده کنید،
• &OsStr to OsString: you need to clone the data in &OsStr to be able to return it and call readdir again.

مورد Nomicon همچنین یک فصل بسیار مفید در مورد FFI دارد.

کد زیر را در https://play.rust-lang.org/ کپی کنید و توابع و متدهای از مفقود شده را پر کنید:

// TODO: این را زمانی که پیاده‌سازی‌تان تمام شد حذف کنید.
#![allow(unused_imports, unused_variables, dead_code)]

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Opaque type. See https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Layout according to the Linux man page for readdir(3), where ino_t and
    // off_t are resolved according to the definitions in
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Layout according to the macOS man page for dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // See https://github.com/rust-lang/libc/issues/414 and the section on
        // _DARWIN_FEATURE_64_BIT_INODE in the macOS man page for stat(2).
        //
        // "Platforms that existed before these updates were available" refers
        // to macOS (as opposed to iOS / wearOS / etc.) on Intel and PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Call opendir and return a Ok value if that worked,
        // otherwise return Err with a message.
        unimplemented!()
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Keep calling readdir until we get a NULL pointer back.
        unimplemented!()
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Call closedir as needed.
        unimplemented!()
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

راه‌حل

mod ffi {
    use std::os::raw::{c_char, c_int};
    #[cfg(not(target_os = "macos"))]
    use std::os::raw::{c_long, c_uchar, c_ulong, c_ushort};

    // Opaque type. See https://doc.rust-lang.org/nomicon/ffi.html.
    #[repr(C)]
    pub struct DIR {
        _data: [u8; 0],
        _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
    }

    // Layout according to the Linux man page for readdir(3), where ino_t and
    // off_t are resolved according to the definitions in
    // /usr/include/x86_64-linux-gnu/{sys/types.h, bits/typesizes.h}.
    #[cfg(not(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_ino: c_ulong,
        pub d_off: c_long,
        pub d_reclen: c_ushort,
        pub d_type: c_uchar,
        pub d_name: [c_char; 256],
    }

    // Layout according to the macOS man page for dir(5).
    #[cfg(all(target_os = "macos"))]
    #[repr(C)]
    pub struct dirent {
        pub d_fileno: u64,
        pub d_seekoff: u64,
        pub d_reclen: u16,
        pub d_namlen: u16,
        pub d_type: u8,
        pub d_name: [c_char; 1024],
    }

    extern "C" {
        pub fn opendir(s: *const c_char) -> *mut DIR;

        #[cfg(not(all(target_os = "macos", target_arch = "x86_64")))]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        // See https://github.com/rust-lang/libc/issues/414 and the section on
        // _DARWIN_FEATURE_64_BIT_INODE in the macOS man page for stat(2).
        //
        // "Platforms that existed before these updates were available" refers
        // to macOS (as opposed to iOS / wearOS / etc.) on Intel and PowerPC.
        #[cfg(all(target_os = "macos", target_arch = "x86_64"))]
        #[link_name = "readdir$INODE64"]
        pub fn readdir(s: *mut DIR) -> *const dirent;

        pub fn closedir(s: *mut DIR) -> c_int;
    }
}

use std::ffi::{CStr, CString, OsStr, OsString};
use std::os::unix::ffi::OsStrExt;

#[derive(Debug)]
struct DirectoryIterator {
    path: CString,
    dir: *mut ffi::DIR,
}

impl DirectoryIterator {
    fn new(path: &str) -> Result<DirectoryIterator, String> {
        // Call opendir and return a Ok value if that worked,
        // otherwise return Err with a message.
        let path =
            CString::new(path).map_err(|err| format!("مسیر نامعتبر: {err}"))?;
        // SAFETY: path.as_ptr() cannot be NULL.
        let dir = unsafe { ffi::opendir(path.as_ptr()) };
        if dir.is_null() {
            Err(format!("نمی‌توان {:?} را باز کرد", path))
        } else {
            Ok(DirectoryIterator { path, dir })
        }
    }
}

impl Iterator for DirectoryIterator {
    type Item = OsString;
    fn next(&mut self) -> Option<OsString> {
        // Keep calling readdir until we get a NULL pointer back.
        // SAFETY: self.dir is never NULL.
        let dirent = unsafe { ffi::readdir(self.dir) };
        if dirent.is_null() {
            // We have reached the end of the directory.
            return None;
        }
        // SAFETY: dirent is not NULL and dirent.d_name is NUL
        // terminated.
        let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };
        let os_str = OsStr::from_bytes(d_name.to_bytes());
        Some(os_str.to_owned())
    }
}

impl Drop for DirectoryIterator {
    fn drop(&mut self) {
        // Call closedir as needed.
        if !self.dir.is_null() {
            // SAFETY: self.dir is not NULL.
            if unsafe { ffi::closedir(self.dir) } != 0 {
                panic!("نمی‌توان {:?} را ببندد", self.path);
            }
        }
    }
}

fn main() -> Result<(), String> {
    let iter = DirectoryIterator::new(".")?;
    println!("files: {:#?}", iter.collect::<Vec<_>>());
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn test_nonexisting_directory() {
        let iter = DirectoryIterator::new("نه مشابه این دایرکتوری");
        assert!(iter.is_err());
    }

    #[test]
    fn test_empty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("نویسه غیر UTF-8 در مسیر")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", ".."]);
        Ok(())
    }

    #[test]
    fn test_nonempty_directory() -> Result<(), Box<dyn Error>> {
        let tmp = tempfile::TempDir::new()?;
        std::fs::write(tmp.path().join("foo.txt"), "این خاطرات Foo است \n")?;
        std::fs::write(tmp.path().join("bar.png"), "<PNG>\n")?;
        std::fs::write(tmp.path().join("crab.rs"), "//! Crab\n")?;
        let iter = DirectoryIterator::new(
            tmp.path().to_str().ok_or("نویسه غیر UTF-8 در مسیر")?,
        )?;
        let mut entries = iter.collect::<Vec<_>>();
        entries.sort();
        assert_eq!(entries, &[".", "..", "bar.png", "crab.rs", "foo.txt"]);
        Ok(())
    }
}

به Rust در Android خوش‌آمدید

‏ Rust برای system software در اندروید پشتیبانی می‌شود. این بدان معناست که می توانید سرویس‌ها، کتابخانه‌‌ها، درایورها یا حتی سیستم‌عامل جدید را در Rust بنویسید (یا در صورت نیاز کدهای موجود را بهبود ببخشید).

ما امروز سعی خواهیم کرد Rust را از یکی از پروژه‌های خودتان فراخوانی کنیم. بنابراین سعی کنید گوشه کوچکی از پایه کد خود را پیدا کنید تا بتوانیم برخی از خطوط کد را به Rust منتقل کنیم. هر چه وابستگی‌ها و انواع "exotic" کمتر باشد برای ما بهتر است. چیزی که برخی از بایت‌های خام را تجزیه کند ایده آل خواهد بود.

تنظیم

ما از یک دستگاه Cuttlefish Android Virtual برای آزمایش کد خود استفاده خواهیم کرد. مطمئن شوید که به یکی از آنها دسترسی دارید یا یک مورد جدید ایجاد کنید:

source build/envsetup.sh
lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create

لطفاً برای جزئیات به [Android Developer Codelab]‌(https://source.android.com/docs/setup/start) مراجعه کنید.

قوانین ساخت

‏ Android build system (Soong) از Rust از طریق تعدادی ماژول پشتیبانی می‌کند:

در ادامه به rust_binary و rust_binary نگاه خواهیم کرد.

Rust Binaries

اجازه دهید با یک برنامه ساده شروع کنیم. در ریشه یک AOSP، فایل های زیر را ایجاد کنید:

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/main.rs"],
}

hello_rust/src/main.rs:

//! Rust demo.

/// Prints a greeting to standard output.
fn main() {
    println!("سلام از Rust!");
}

اکنون می‌توانید باینری را بسازید، push و اجرا کنید:

m hello_rust
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust" /data/local/tmp
adb shell /data/local/tmp/hello_rust

Hello from Rust!

کتابخانه‌های Rust

شما از rust_library برای ایجاد یک کتابخانه Rust جدید برای Android استفاده می‌کنید.

در اینجا ما یک وابستگی به دو کتابخانه را اعلام می‌کنیم:

• ‏ libgreeting, چیزی که در زیر تعریف می‌کنیم,
• libtextwrap, which is a crate already vendored in external/rust/crates/.

hello_rust/Android.bp:

rust_binary {
    name: "hello_rust_with_dep",
    crate_name: "hello_rust_with_dep",
    srcs: ["src/main.rs"],
    rustlibs: [
        "libgreetings",
        "libtextwrap",
    ],
    prefer_rlib: true, // Need this to avoid dynamic link error.
}

rust_library {
    name: "libgreetings",
    crate_name: "greetings",
    srcs: ["src/lib.rs"],
}

hello_rust/src/main.rs:

//! Rust demo.

use greetings::greeting;
use textwrap::fill;

/// Prints a greeting to standard output.
fn main() {
    println!("{}", fill(&greeting("Bob"), 24));
}

hello_rust/src/lib.rs:

//! Greeting library.

/// Greet `name`.
pub fn greeting(name: &str) -> String {
    format!("سلام {name}، از آشنایی با شما بسیار خوشحالم!")
}

باینری را مانند قبل می سازید، push و اجرا می‌کنید:

m hello_rust_with_dep
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep" /data/local/tmp
adb shell /data/local/tmp/hello_rust_with_dep

Hello Bob, it is very
nice to meet you!

AIDL

‏Android Interface Definition Language (AIDL) در Rust پشتیبانی می‌شود:

• کد Rust می تواند سرورهای AIDL موجود را فراخوانی کند,
• می‌توانید سرورهای جدید AIDL را در Rust ایجاد کنید.

آموزش سرویس Birthday

برای نشان‌دادن نحوه استفاده از Rust با Binder، ما می‌خواهیم روند ایجاد رابط Binder را بررسی کنیم. سپس هم سرویس توصیف‌شده را پیاده‌سازی می‌کنیم و هم کد کلاینت را می‌نویسیم که با آن سرویس صحبت می‌کند.

AIDL Interfaces

شما API سرویس خود را با استفاده از یک AIDL interface اعلام می‌کنید:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years);
}

birthday_service/aidl/Android.bp:

aidl_interface {
    name: "com.example.birthdayservice",
    srcs: ["com/example/birthdayservice/*.aidl"],
    unstable: true,
    backend: {
        rust: { // Rust is not enabled by default
            enabled: true,
        },
    },
}

Generated Service API

Binder یک trait مطابق با تعریف interface تولید می‌کند. trait برای صحبت کردن با سرویس است.

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years);
}

Generated trait:

trait IBirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String>;
}

سرویس شما باید این trait را پیاده‌سازی کند و کلاینت شما از این ویژگی برای صحبت با سرویس‌ها استفاده خواهد کرد.

پیاده‌سازی سرویس‌ها

اکنون می‌توانیم سرویس AIDL را پیاده‌سازی کنیم:

birthday_service/src/lib.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

/// The `IBirthdayService` implementation.
pub struct BirthdayService;

impl binder::Interface for BirthdayService {}

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result<String> {
        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
    }
}

birthday_service/Android.bp:

rust_library {
    name: "libbirthdayservice",
    srcs: ["src/lib.rs"],
    crate_name: "birthdayservice",
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
}

AIDL Server

در نهایت، می توانیم سروری ایجاد کنیم که سرویس را expose می‌کند:

birthday_service/src/server.rs:

//! Birthday service.
use birthdayservice::BirthdayService;
use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::BnBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Entry point for birthday service.
fn main() {
    let birthday_service = BirthdayService;
    let birthday_service_binder = BnBirthdayService::new_binder(
        birthday_service,
        binder::BinderFeatures::default(),
    );
    binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())
        .expect("Failed to register service");
    binder::ProcessState::join_thread_pool()
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_server",
    crate_name: "birthday_server",
    srcs: ["src/server.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
        "libbirthdayservice",
    ],
    prefer_rlib: true, // To avoid dynamic link error.
}

استقرار

اکنون می‌توانیم سرویس را بسازیم، push کنیم و شروع کنیم:

m birthday_server
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_server" /data/local/tmp
adb root
adb shell /data/local/tmp/birthday_server

در ترمینال دیگر، بررسی کنید که آیا سرویسی اجرا شود:

adb shell service check birthdayservice

Service birthdayservice: found

همچنین می‌توانید با service call با سرویس تماس بگیرید:

adb shell service call birthdayservice 1 s16 Bob i32 24

Result: Parcel(
  0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'
  0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'
  0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'
  0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'
  0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'
  0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'
  0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'
  0x00000070: 00210073 00000000                   's.!.....        ')

AIDL Client

در‌نهایت، ما می‌توانیم یک Rust client برای سرویس جدید خود ایجاد کنیم.

birthday_service/src/client.rs:

use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::IBirthdayService;
use com_example_birthdayservice::binder;

const SERVICE_IDENTIFIER: &str = "birthdayservice";

/// Call the birthday service.
fn main() -> Result<(), Box<dyn Error>> {
    let name = std::env::args().nth(1).unwrap_or_else(|| String::from("Bob"));
    let years = std::env::args()
        .nth(2)
        .and_then(|arg| arg.parse::<i32>().ok())
        .unwrap_or(42);

    binder::ProcessState::start_thread_pool();
    let service = binder::get_interface::<dyn IBirthdayService>(SERVICE_IDENTIFIER)
        .map_err(|_| "Failed to connect to BirthdayService")?;

    // Call the service.
    let msg = service.wishHappyBirthday(&name, years)?;
    println!("{msg}");
}

birthday_service/Android.bp:

rust_binary {
    name: "birthday_client",
    crate_name: "birthday_client",
    srcs: ["src/client.rs"],
    rustlibs: [
        "com.example.birthdayservice-rust",
        "libbinder_rs",
    ],
    prefer_rlib: true, // To avoid dynamic link error.
}

توجه داشته باشید که client به libbirthdayservice وابسته نیست.

کلاینت را در دستگاه خود بسازید، push کرده و اجرا کنید:

m birthday_client
adb push "$ANDROID_PRODUCT_OUT/system/bin/birthday_client" /data/local/tmp
adb shell /data/local/tmp/birthday_client Charlie 60

Happy Birthday Charlie, congratulations with the 60 years!

تغییر دادن API

اجازه دهید API را با عملکرد بیشتری گسترش دهیم: می‌خواهیم به مشتریان اجازه دهیم لیستی از خطوط را برای کارت تولد مشخص کنند:

package com.example.birthdayservice;

/** Birthday service interface. */
interface IBirthdayService {
    /** Generate a Happy Birthday message. */
    String wishHappyBirthday(String name, int years, in String[] text);
}

این منجر به یک تعریف ویژگی به روز شده برای IBirthdayService می‌شود:

trait IBirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String>;
}

به‌روزرسانی کلاینت و سرویس‌ها

کد سرویس کلاینت و سرور را برای حساب کردن API جدید به‌روز کنید.

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishHappyBirthday(
        &self,
        name: &str,
        years: i32,
        text: &[String],
    ) -> binder::Result<String> {
        let mut msg = format!(
            "Happy Birthday {name}, congratulations with the {years} years!",
        );

        for line in text {
            msg.push('\n');
            msg.push_str(line);
        }

        Ok(msg)
    }
}

birthday_service/src/client.rs:

let msg = service.wishHappyBirthday(
    &name,
    years,
    &[
        String::from("Habby birfday to yuuuuu"),
        String::from("And also: many more"),
    ],
)?;

کار با انواع AIDL

انواع AIDL به نوع اصطلاحی Rust مناسب ترجمه می‌شوند:

• انواع اولیه یا Primitive types (بیشتر) به idiomatic Rust type نگاشت می‌شوند.
• انواع Collectionها مانند sliceها،Vec و string typeها پشتیبانی می‌شوند.
• ارجاع به AIDL objects و دسته فایل‌ها را می‌توان بین clientها و سرویس‌ها ارسال کرد.
• دسته‌های فایل و بسته‌بندی‌ها به طور کامل پشتیبانی می‌شوند.

انواع اولیه

انواع ابتدایی یا Primitive type (معمولاً) به صورت idiomatically نگاشت می‌شوند:

تایپ‌های اٰرایه‌ای

انواع آرایه (T[], byte[], و List<T>) بسته به نحوه استفاده از آنها در function signature، به Rust array type مناسب ترجمه می‌شوند:

Sending Objects

‏ AIDL objects را می‌توان به‌عنوان یک نوع AIDL مشخص یا به عنوان IBinder interface پاک‌شده ارسال کرد:

birthday_service/aidl/com/example/birthdayservice/IBirthdayInfoProvider.aidl:

package com.example.birthdayservice;

interface IBirthdayInfoProvider {
    String name();
    int years();
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.IBirthdayInfoProvider;

interface IBirthdayService {
    /** The same thing, but using a binder object. */
    String wishWithProvider(IBirthdayInfoProvider provider);

    /** The same thing, but using `IBinder`. */
    String wishWithErasedProvider(IBinder provider);
}

birthday_service/src/client.rs:

/// Rust struct implementing the `IBirthdayInfoProvider` interface.
struct InfoProvider {
    name: String,
    age: u8,
}

impl binder::Interface for InfoProvider {}

impl IBirthdayInfoProvider for InfoProvider {
    fn name(&self) -> binder::Result<String> {
        Ok(self.name.clone())
    }

    fn years(&self) -> binder::Result<i32> {
        Ok(self.age as i32)
    }
}

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    // Create a binder object for the `IBirthdayInfoProvider` interface.
    let provider = BnBirthdayInfoProvider::new_binder(
        InfoProvider { name: name.clone(), age: years as u8 },
        BinderFeatures::default(),
    );

    // Send the binder object to the service.
    service.wishWithProvider(&provider)?;

    // Perform the same operation but passing the provider as an `SpIBinder`.
    service.wishWithErasedProvider(&provider.as_binder())?;
}

بسته‌بندی‌ها

Binder for Rust supports sending parcelables directly:

birthday_service/aidl/com/example/birthdayservice/BirthdayInfo.aidl:

package com.example.birthdayservice;

parcelable BirthdayInfo {
    String name;
    int years;
}

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

import com.example.birthdayservice.BirthdayInfo;

interface IBirthdayService {
    /** The same thing, but with a parcelable. */
    String wishWithInfo(in BirthdayInfo info);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    service.wishWithInfo(&BirthdayInfo { name: name.clone(), years })?;
}

ارسال فایل‌ها

فایل‌ها را می‌توان با استفاده از نوع ParcelFileDescriptor بین کلاینت‌ها/سرورهای Binder ارسال کرد:

birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl:

interface IBirthdayService {
    /** The same thing, but loads info from a file. */
    String wishFromFile(in ParcelFileDescriptor infoFile);
}

birthday_service/src/client.rs:

fn main() {
    binder::ProcessState::start_thread_pool();
    let service = connect().expect("Failed to connect to BirthdayService");

    // Open a file and put the birthday info in it.
    let mut file = File::create("/data/local/tmp/birthday.info").unwrap();
    writeln!(file, "{name}")?;
    writeln!(file, "{years}")?;

    // Create a `ParcelFileDescriptor` from the file and send it.
    let file = ParcelFileDescriptor::new(file);
    service.wishFromFile(&file)?;
}

birthday_service/src/lib.rs:

impl IBirthdayService for BirthdayService {
    fn wishFromFile(
        &self,
        info_file: &ParcelFileDescriptor,
    ) -> binder::Result<String> {
        // Convert the file descriptor to a `File`. `ParcelFileDescriptor` wraps
        // an `OwnedFd`, which can be cloned and then used to create a `File`
        // object.
        let mut info_file = info_file
            .as_ref()
            .try_clone()
            .map(File::from)
            .expect("کنترل فایل نامعتبر");

        let mut contents = String::new();
        info_file.read_to_string(&mut contents).unwrap();

        let mut lines = contents.lines();
        let name = lines.next().unwrap();
        let years: i32 = lines.next().unwrap().parse().unwrap();

        Ok(format!("Happy Birthday {name}, congratulations with the {years} years!"))
    }
}

تست‌کردن در Android

بر اساس Testing، اکنون به نحوه عملکرد unit testها در AOSP خواهیم پرداخت. از ماژول rust_test برای تست های واحد خود استفاده کنید:

testing/Android.bp:

rust_library {
    name: "libleftpad",
    crate_name: leftpad",
    srcs: ["src/lib.rs"],
}

rust_test {
    name: "libleftpad_test",
    crate_name: "leftpad_test",
    srcs: ["src/lib.rs"],
    host_supported: true,
    test_suites: ["general-tests"],
}

testing/src/lib.rs:

#![allow(unused)]
fn main() {
//! Left-padding library.

/// Left-pad `s` to `width`.
pub fn leftpad(s: &str, width: usize) -> String {
    format!("{s:>width$}")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn short_string() {
        assert_eq!(leftpad("foo", 5), "  foo");
    }

    #[test]
    fn long_string() {
        assert_eq!(leftpad("foobar", 6), "foobar");
    }
}
}

اکنون می توانید تست را با

atest --host libleftpad_test

خروجی به شکل زیر است:

INFO: Elapsed time: 2.666s, Critical Path: 2.40s
INFO: 3 processes: 2 internal, 1 linux-sandbox.
INFO: Build completed successfully, 3 total actions
//comprehensive-rust-android/testing:libleftpad_test_host            PASSED in 2.3s
    PASSED  libleftpad_test.tests::long_string (0.0s)
    PASSED  libleftpad_test.tests::short_string (0.0s)
Test cases: finished with 2 passing and 0 failing out of 2 test cases

توجه کنید که چگونه فقط ریشه crate کتابخانه را ذکر می‌کنید. تست‌ها به صورت بازگشتی در ماژول‌های تودرتو یافت می‌شوند.

GoogleTest

جعبه GoogleTest با استفاده از matchers اجازه می‌دهد تا assertهای آزمایشی انعطاف‌پذیر را انجام دهید:

use googletest::prelude::*;

#[googletest::test]
fn test_elements_are() {
    let value = vec!["foo", "bar", "baz"];
    expect_that!(value, elements_are!(eq(&"foo"), lt(&"xyz"), starts_with("a")));
}

اگر آخرین عنصر را به"!"تغییر دهیم، آزمایش با یک پیغام خطای ساختار یافته که خطا را pin-pointing می‌کند، شکست می خورد:

---- test_elements_are stdout ----
Value of: value
Expected: has elements:
  0. is equal to "foo"
  1. is less than "xyz"
  2. starts with prefix "!"
Actual: ["foo", "bar", "baz"],
  where element #2 is "baz", which does not start with "!"
  at src/testing/googletest.rs:6:5
Error: See failure output above

#[test]
fn test_multiline_string_diff() {
    let haiku = "Memory safety found,\n\
                 Rust's strong typing guides the way,\n\
                 Secure code you'll write.";
    assert_that!(
        haiku,
        eq("Memory safety found,\n\
            Rust's silly humor guides the way,\n\
            Secure code you'll write.")
    );
}

    Value of: haiku
Expected: is equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Actual: "Memory safety found,\nRust's strong typing guides the way,\nSecure code you'll write.",
  which isn't equal to "Memory safety found,\nRust's silly humor guides the way,\nSecure code you'll write."
Difference(-actual / +expected):
 Memory safety found,
-Rust's strong typing guides the way,
+Rust's silly humor guides the way,
 Secure code you'll write.
  at src/testing/googletest.rs:17:5

Mocking

برای mocking از Mockall که یک کتابخانه محبوب بوده استفاده شده است. برای استفاده از traitها، باید کد خود را مجدداً تغییر دهید، سپس می‌توانید به سرعت آنها را mock کنید:

use std::time::Duration;

#[mockall::automock]
pub trait Pet {
    fn is_hungry(&self, since_last_meal: Duration) -> bool;
}

#[test]
fn test_robot_dog() {
    let mut mock_dog = MockPet::new();
    mock_dog.expect_is_hungry().return_const(true);
    assert_eq!(mock_dog.is_hungry(Duration::from_secs(10)), true);
}

#[test]
fn test_robot_cat() {
    let mut mock_cat = MockPet::new();
    mock_cat
        .expect_is_hungry()
        .with(mockall::predicate::gt(Duration::from_secs(3 * 3600)))
        .return_const(true);
    mock_cat.expect_is_hungry().return_const(false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(1 * 3600)), false);
    assert_eq!(mock_cat.is_hungry(Duration::from_secs(5 * 3600)), true);
}

لاگ

باید از log crate برای ورود خودکار بهlogcat (روی دستگاه) یا stdout (روی host) استفاده کنید:

hello_rust_logs/Android.bp:

rust_binary {
    name: "hello_rust_logs",
    crate_name: "hello_rust_logs",
    srcs: ["src/main.rs"],
    rustlibs: [
        "liblog_rust",
        "liblogger",
    ],
    host_supported: true,
}

hello_rust_logs/src/main.rs:

//! Rust logging demo.

use log::{debug, error, info};

/// Logs a greeting.
fn main() {
    logger::init(
        logger::Config::default()
            .with_tag_on_device("rust")
            .with_min_level(log::Level::Trace),
    );
    debug!("شروع برنامه.");
    info!("کارها خوب پیش می‌رود.");
    error!("Something went wrong!");
}

ساخت، push و اجرای باینری‌ها روی یک ماشین:

m hello_rust_logs
adb push "$ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs" /data/local/tmp
adb shell /data/local/tmp/hello_rust_logs

لاگ‌ها در adb logcat نشان‌داده می‌شوند:

adb logcat -s rust

09-08 08:38:32.454  2420  2420 D rust: hello_rust_logs: Starting program.
09-08 08:38:32.454  2420  2420 I rust: hello_rust_logs: Things are going fine.
09-08 08:38:32.454  2420  2420 E rust: hello_rust_logs: Something went wrong!

قابلیت همکاری

‏‌Rust از قابلیت همکاری با زبان‌های دیگر پشتیبانی می‌کند. این بدان معنی است که شما می‌توانید:

• توابع Rust را از زبان های دیگر فراخوانی کنید.
• فراخوانی توابع نوشته شده به زبان های دیگر از Rust.

وقتی توابعی را به‌ یک زبان خارجی فراخوانی می‌کنید، می‌گوییم که از یک رابط تابع خارج( foreign function interface) که به نام FFI نیز شناخته می‌شود، استفاده می‌کنید.

قابلیت همکاری با C

‏ Rust پشتیبانی کاملی برای link دادن object fileهایی با یک فراخوانی C دارد. به طور مشابه، می توانید توابع Rust را export کرده و آنها را از C فراخوانی کنید.

در صورت تمایل می‌توانید این کار را دستی انجام دهید:

extern "C" {
    fn abs(x: i32) -> i32;
}

fn main() {
    let x = -42;
    // SAFETY: `abs` doesn't have any safety requirements.
    let abs_x = unsafe { abs(x) };
    println!("{x}, {abs_x}");
}

ما قبلاً این را در تمرین Safe FFI Wrapper دیدیم.

این مستلزم آگاهی کامل از پلتفرم هدف است و برای production توصیه نمی‌شود.

در ادامه گزینه‌های بهتر را بررسی خواهیم کرد.

با استفاده از Bindgen

ابزار bindgen می‌تواند اتصالات را از یک فایل هدر C به طور خودکار ایجاد کند.

ابتدا یک کتابخانه کوچک C ایجاد کنید:

interoperability/bindgen/libbirthday.h:

typedef struct card {
  const char* name;
  int years;
} card;

void print_card(const card* card);

interoperability/bindgen/libbirthday.c:

#include <stdio.h>
#include "libbirthday.h"

void print_card(const card* card) {
  printf("+--------------\n");
  printf("| Happy Birthday %s!\n", card->name);
  printf("| Congratulations with the %i years!\n", card->years);
  printf("+--------------\n");
}

این را به فایل Android.bp خود اضافه کنید:

interoperability/bindgen/Android.bp:

cc_library {
    name: "libbirthday",
    srcs: ["libbirthday.c"],
}

یک فایل هدر wrapper برای کتابخانه ایجاد کنید (در این مثال به شدت مورد نیاز نیست):

interoperability/bindgen/libbirthday_wrapper.h:

#include "libbirthday.h"

اکنون می توانید اتصالات (bindings) را به طور خودکار ایجاد کنید:

interoperability/bindgen/Android.bp:

rust_bindgen {
    name: "libbirthday_bindgen",
    crate_name: "birthday_bindgen",
    wrapper_src: "libbirthday_wrapper.h",
    source_stem: "bindings",
    static_libs: ["libbirthday"],
}

در نهایت، می‌توانیم از bindingها در برنامه Rust خود استفاده کنیم:

interoperability/bindgen/Android.bp:

rust_binary {
    name: "چاپ_کارت_تولد",
    srcs: ["main.rs"],
    rustlibs: ["libbirthday_bindgen"],
}

interoperability/bindgen/main.rs:

//! Bindgen demo.

use birthday_bindgen::{card, print_card};

fn main() {
    let name = std::ffi::CString::new("پیتر").unwrap();
    let card = card { name: name.as_ptr(), years: 42 };
    // SAFETY: The pointer we pass is valid because it came from a Rust
    // reference, and the `name` it contains refers to `name` above which also
    // remains valid. `print_card` doesn't store either pointer to use later
    // after it returns.
    unsafe {
        print_card(&card as *const card);
    }
}

ساخت، push و اجرای باینری‌ها روی یک ماشین:

m print_birthday_card
adb push "$ANDROID_PRODUCT_OUT/system/bin/print_birthday_card" /data/local/tmp
adb shell /data/local/tmp/print_birthday_card

در نهایت، ما می‌توانیم تست‌های تولید شده خودکار را برای اطمینان از کارکرد اتصالات (bindings) اجرا کنیم:

interoperability/bindgen/Android.bp:

rust_test {
    name: "libbirthday_bindgen_test",
    srcs: [":libbirthday_bindgen"],
    crate_name: "libbirthday_bindgen_test",
    test_suites: ["general-tests"],
    auto_gen_config: true,
    clippy_lints: "none", // Generated file, skip linting
    lints: "none",
}

atest libbirthday_bindgen_test

فراخوانی Rust

صدور یا Exporting توابع و تایپ‌ها از Rust به C آسان است:

interoperability/rust/libanalyze/analyze.rs

//! Rust FFI demo.
#![deny(improper_ctypes_definitions)]

use std::os::raw::c_int;

/// Analyze the numbers.
#[no_mangle]
pub extern "C" fn analyze_numbers(x: c_int, y: c_int) {
    if x < y {
        println!("x ({x}) is smallest!");
    } else {
        println!(" مقدارy  ({y}) احتمالا بزرگتر از x ({x}) است");
    }
}

interoperability/rust/libanalyze/analyze.h

#ifndef ANALYSE_H
#define ANALYSE_H

extern "C" {
void analyze_numbers(int x, int y);
}

#endif

interoperability/rust/libanalyze/Android.bp

rust_ffi {
    name: "libanalyze_ffi",
    crate_name: "analyze_ffi",
    srcs: ["analyze.rs"],
    include_dirs: ["."],
}

اکنون می توانیم این را از یک باینری C فراخوانی کنیم:

interoperability/rust/analyze/Android.bp

#include "analyze.h"

int main() {
  analyze_numbers(10, 20);
  analyze_numbers(123, 123);
  return 0;
}

interoperability/rust/analyze/Android.bp

cc_binary {
    name: "analyze_numbers",
    srcs: ["main.c"],
    static_libs: ["libanalyze_ffi"],
}

ساخت، push و اجرای باینری‌ها روی یک ماشین:

m analyze_numbers
adb push "$ANDROID_PRODUCT_OUT/system/bin/analyze_numbers" /data/local/tmp
adb shell /data/local/tmp/analyze_numbers

با C++

این CXX crate امکان همکاری امن بین Rust و C++ را فراهم می‌کند.

رویکرد کلی به این صورت است:

ماژول پل

‏ CXX متکی به توصیفی از signatureهای تابع است که از هر زبان به زبان دیگر در معرض دید قرار می‌گیرد. شما این توضیحات را با استفاده از بلوک‌های خارجی در یک ماژول Rust ارائه می‌کنید که با attribute ماکروها #[cxx::bridge] شرح داده شده است.

#[allow(unsafe_op_in_unsafe_fn)]
#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    // Shared structs with fields visible to both languages.
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    // Rust types and signatures exposed to C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    // C++ types and signatures exposed to Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

تعریف پل در Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MyType; // Opaque type
        fn foo(&self); // Method on `MyType`
        fn bar() -> Box<MyType>; // Free function
    }
}

struct MyType(i32);

impl MyType {
    fn foo(&self) {
        println!("{}", self.0);
    }
}

fn bar() -> Box<MyType> {
    Box::new(MyType(123))
}

Generated C++

#[cxx::bridge]
mod ffi {
    // Rust types and signatures exposed to C++.
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }
}

نتیجه (تقریبی) ++C در زیر است:

struct MultiBuf final : public ::rust::Opaque {
  ~MultiBuf() = delete;

private:
  friend ::rust::layout;
  struct layout {
    static ::std::size_t size() noexcept;
    static ::std::size_t align() noexcept;
  };
};

::rust::Slice<::std::uint8_t const> next_chunk(::org::blobstore::MultiBuf &buf) noexcept;

C++ Bridge Declarations

#[cxx::bridge]
mod ffi {
    // C++ types and signatures exposed to Rust.
    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

نتیجه (تقریبی) Rust در زیر است:

#[repr(C)]
pub struct BlobstoreClient {
    _private: ::cxx::private::Opaque,
}

pub fn new_blobstore_client() -> ::cxx::UniquePtr<BlobstoreClient> {
    extern "C" {
        #[link_name = "org$blobstore$cxxbridge1$new_blobstore_client"]
        fn __new_blobstore_client() -> *mut BlobstoreClient;
    }
    unsafe { ::cxx::UniquePtr::from_raw(__new_blobstore_client()) }
}

impl BlobstoreClient {
    pub fn put(&self, parts: &mut MultiBuf) -> u64 {
        extern "C" {
            #[link_name = "org$blobstore$cxxbridge1$BlobstoreClient$put"]
            fn __put(
                _: &BlobstoreClient,
                parts: *mut ::cxx::core::ffi::c_void,
            ) -> u64;
        }
        unsafe {
            __put(self, parts as *mut MultiBuf as *mut ::cxx::core::ffi::c_void)
        }
    }
}

// ...

انواع مشترک

#[cxx::bridge]
mod ffi {
    #[derive(Clone, Debug, Hash)]
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1, J=11, Q=12, K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Shared Enums

#[cxx::bridge]
mod ffi {
    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }
}

Generated Rust:

#![allow(unused)]
fn main() {
#[derive(Copy, Clone, PartialEq, Eq)]
#[repr(transparent)]
pub struct Suit {
    pub repr: u8,
}

#[allow(non_upper_case_globals)]
impl Suit {
    pub const Clubs: Self = Suit { repr: 0 };
    pub const Diamonds: Self = Suit { repr: 1 };
    pub const Hearts: Self = Suit { repr: 2 };
    pub const Spades: Self = Suit { repr: 3 };
}
}

Generated C++:

enum class Suit : uint8_t {
  Clubs = 0,
  Diamonds = 1,
  Hearts = 2,
  Spades = 3,
};

مدیریت خطا Rust

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn fallible(depth: usize) -> anyhow::Result<String> {
    if depth == 0 {
        return Err(anyhow::Error::msg("fallible1 به عمق > 0 نیاز دارد"));
    }

    Ok("Success!".into())
}

مدیریت خطا ++C

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Error: {}", err);
        process::exit(1);
    }
}

تایپ‌های اضافی

ساخت در اندروید

یک cc_library_static برای ساخت کتابخانه ++C از جمله هدر و فایل منبع تولید شده CXX ایجاد کنید.

cc_library_static {
    name: "libcxx_test_cpp",
    srcs: ["cxx_test.cpp"],
    generated_headers: [
        "cxx-bridge-header",
        "libcxx_test_bridge_header"
    ],
    generated_sources: ["libcxx_test_bridge_code"],
}

ساخت در اندروید

دو نوع ژانر ایجاد کنید: یکی برای تولید هدر CXX و دیگری برای تولید فایل منبع CXX. سپس از اینها به عنوان ورودی cc_library_static استفاده می‌شود.

// Generate a C++ header containing the C++ bindings
// to the Rust exported functions in lib.rs.
genrule {
    name: "libcxx_test_bridge_header",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) --header > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.h"],
}

// Generate the C++ code that Rust calls into.
genrule {
    name: "libcxx_test_bridge_code",
    tools: ["cxxbridge"],
    cmd: "$(location cxxbridge) $(in) > $(out)",
    srcs: ["lib.rs"],
    out: ["lib.rs.cc"],
}

ساخت در اندروید

یکrust_binary ایجاد کنید که به libcxx و cc_library_static شما بستگی دارد.

rust_binary {
    name: "cxx_test",
    srcs: ["lib.rs"],
    rustlibs: ["libcxx"],
    static_libs: ["libcxx_test_cpp"],
}

قابلیت همکاری با جاوا

جاوا می‌تواند objectهای مشترک را از طریق [واسط بومی جاوا Java Native Interface (JNI) بارگیری کند. jni crate به شما امکان می دهد یک کتابخانه سازگار ایجاد کنید.

ابتدا یک تابع Rust برای export به Java ایجاد می‌کنیم:

interoperability/java/src/lib.rs:

#![allow(unused)]
fn main() {
//! Rust <-> Java FFI demo.

use jni::objects::{JClass, JString};
use jni::sys::jstring;
use jni::JNIEnv;

/// HelloWorld::hello method implementation.
#[no_mangle]
pub extern "system" fn Java_HelloWorld_hello(
    env: JNIEnv,
    _class: JClass,
    name: JString,
) -> jstring {
    let input: String = env.get_string(name).unwrap().into();
    let greeting = format!("سلام, {input}!");
    let output = env.new_string(greeting).unwrap();
    output.into_inner()
}
}

interoperability/java/Android.bp:

rust_ffi_shared {
    name: "libhello_jni",
    crate_name: "hello_jni",
    srcs: ["src/lib.rs"],
    rustlibs: ["libjni"],
}

سپس این تابع را از جاوا فراخوانی می کنیم:

interoperability/java/HelloWorld.java:

class HelloWorld {
    private static native String hello(String name);

    static {
        System.loadLibrary("hello_jni");
    }

    public static void main(String[] args) {
        String output = HelloWorld.hello("الیس");
        System.out.println(output);
    }
}

interoperability/java/Android.bp:

java_binary {
    name: "helloworld_jni",
    srcs: [سلام دنیا"HelloWorld.java"],
    main_class: "HelloWorld",
    required: ["libhello_jni"],
}

در نهایت، می‌توانید باینری را بسازید، همگام‌سازی کنید و اجرا کنید:

m helloworld_jni
adb sync  # requires adb root && adb remount
adb shell /system/bin/helloworld_jni

تمرین‌ها

این یک تمرین گروهی است: ما به یکی از پروژه‌هایی که با آن کار می‌کنید نگاه می‌کنیم و سعی می‌کنیم مقداری Rust را در آن ادغام کنیم. چند پیشنهاد:

• با سرویس AIDL خود با کلاینت که در Rust نوشته شده است تماس بگیرید.

• یک تابع را از پروژه خود به Rust منتقل کنید و آن را فراخوانی کنید.

به Rust در Chromium خوش‌آمدید

‏ Rust برای کتابخانه‌های شخص ثالث در Chromium پشتیبانی می‌شود، با glue code اول شخص برای اتصال بین Rust و کد موجود در ++Chromium C.

امروز ما با Rust ارتباط می‌گیریم تا کار احمقانه‌ای با stringها انجام دهد. اگر گوشه‌ای از کد را دارید که در آن رشته UTF8 را به کاربر نشان می دهید، به جای قسمت دقیقی که در مورد آن صحبت می‌کنیم، این دستور العمل را در قسمت خود از پایگاه کد دنبال کنید.

تنظیم

مطمئن شوید که می‌توانید Chromium را build و اجرا کنید. هر پلتفرم و مجموعه‌ای از build flag ها بدون مشکل هستند، تا زمانی که کد شما نسبتاً جدید باشد (موقعیت commit 1223636 به بعد، مربوط به نوامبر 2023):

gn gen out/Debug
autoninja -C out/Debug chrome
out/Debug/chrome # or on Mac, out/Debug/Chromium.app/Contents/MacOS/Chromium

(یک component به صورت debug build برای سریع‌ترین زمان تکرار توصیه می‌شود. این یک حالت پیش‌فرض است!)

اگر از قبل در آن مرحله نیستید، به چگونه Chromium بسازیم مراجعه کنید. هشدار: راه‌اندازی برای build Chromium زمان زیادی می‌برد.

همچنین توصیه می شود که Visual Studio code را نصب کرده باشید.

در مورد تمرین‌ها

این بخش از دوره دارای یک سری تمرینات است که بر روی یکدیگر ساخته می‌شوند. ما آنها را به جای اینکه فقط در انتها انجام دهیم، در طول دوره پخش خواهیم کرد. اگر برای تکمیل قسمت خاصی وقت ندارید، نگران نباشید: می توانید در اسلاید بعدی به عقب برگردید.

مقایسه Chromium و اکوسیستم Cargo

جامعه Rust معمولاً از cargo و کتابخانه‌های crates.io استفاده می‌کند. Chromium با استفاده از gn و ninja و مجموعه‌ای از وابستگی‌ها ساخته شده است.

هنگام نوشتن کد در Rust، انتخاب‌های شما عبارتند از:

• از gn و ninja با کمک الگوهای //build/rust/*.gni استفاده کنید (مثلاً rust_static_library که بعداً با آن آشنا خواهیم شد). این از toolchain و crateهای بررسی‌شده Chromium استفاده می‌کند.
• از cargo استفاده کنید، اما خود را به toolchain و crateهای بررسی‌شده Chromium محدود کنید
• از cargo استفاده کنید، به یک toolchain و/یا [crateهای دانلود شده از اینترنت]‌(https://crates.io/) اعتماد کنید.

از اینجا به بعد ما روی gn و ninja تمرکز خواهیم کرد، زیرا به این ترتیب می‌توان کد Rust را در مرورگر Chromium ایجاد کرد. در عین حال، Cargo بخش مهمی از اکوسیستم Rust است و شما باید آن را در جعبه ابزار خود نگه دارید.

خرده تمرین

به گروه‌های کوچک تقسیم شده و:

• سناریوهای طوفان فکری که در آن cargo ممکن است مزیتی را ارائه دهد و نمایه ریسک‌های این سناریوها را ارزیابی کند.
• در هنگام استفاده از gn و ninjaو cargo آفلاین و غیره در مورد ابزارها، کتابخانه‌ها و گروه‌هایی از افراد بحث کنید.

رویکرد Chromium Rust

‏ Chromium هنوز Rust شخص اول را مجاز نمی‌کند، مگر در موارد نادر که توسط Area Tech Leads تأیید شده است.

رویکردهای Chromium در مورد کتابخانه‌های شخص ثالث اینجا مشخص شده است. Rust برای کتابخانه‌های شخص ثالث تحت شرایط مختلف مجاز است، از جمله اینکه آیا آنها بهترین گزینه برای کارایی بالا یا موارد امنیتی هستند.

تعداد بسیار کمی از کتابخانه‌های Rust مستقیماً یک C/C++ API را در معرض دید (expose) قرار می‌دهند، به این معنی که تقریباً همه این کتابخانه‌ها به مقدار کمی glue code اول شخص نیاز دارند.

کد Rust glue اول شخص برای یک crate شخص ثالث خاص معمولاً باید در third_party/rust/<crate>/<version>/wrapper نگهداری شود.

به‌همین دلیل، دوره‌ی امروز به شدت بر روی موارد زیر متمرکز خواهد شد:

• آوردن کتابخانه های Rust شخص ثالث ("crates")
• نوشتن glue code برای اینکه بتوانید به کمک آن crateها از ++Chromium C استفاده کنید.

اگر این رویکرد در طول زمان تغییر کند، این دوره به گونه‌ای تکامل می‌یابد که در مسیر مناسب ادامه یابد.

قوانین Build

کد Rust معمولاً با استفاده از cargo ساخته می‌شود. Chromium با gn و ninja جهت کارایی بیشتر ساخته می‌شود --- قواعد استاتیک آن حداکثر موازی‌سازی را امکان‌پذیر می‌سازد. Rust نیز از این قاعده مستثنی نیست.

افزودن کد Rust به Chromium

در برخی از فایل‌های موجود BUILD.gn یک rust_static_library را اعلام کنید:

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

همچنین می‌توانید deps را روی سایر اهداف Rust اضافه کنید. بعداً از این برای وابستگی به کد شخص ثالث استفاده خواهیم کرد.

شامل کد unsafe Rust

کد ناامن Rust به طور پیش‌فرض در rust_static_library غیرمجاز است --- کامپایل نمی‌شود. اگر به کد unsafe Rust نیاز دارید، allow_unsafe = true را به هدف gn اضافه کنید. (بعداً در دوره ما شرایطی را خواهیم دید که در آن لازم است.)

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [
    "lib.rs",
    "hippopotamus.rs"
  ]
  allow_unsafe = true
}

بسته به Rust Code از ++Chromium C

به سادگی هدف بالا را به deps برخی از اهداف Chromium C++ اضافه کنید.

import("//build/rust/rust_static_library.gni")

rust_static_library("my_rust_lib") {
  crate_root = "lib.rs"
  sources = [ "lib.rs" ]
}

# or source_set, static_library etc.
component("preexisting_cpp") {
  deps = [ ":my_rust_lib" ]
}

Visual Studio Code

تایپ‌ها در کد Rust حذف شده اند که باعث می‌شود یک IDE خوب حتی مفیدتر از++C باشد. کد ویژوال استودیو برای Rust در Chromium به خوبی کار می کند و برای استفاده از آن،

• اطمینان حاصل کنید که VSCode شما دارای extension rust-analyzer است، نه فرم‌های قبلی پشتیبانی از Rust
• ‏ gn gen out/Debug --export-rust-project (یا معادل آن برای دایرکتوری خروجی شما)
• ln -s out/Debug/rust-project.json rust-project.json

تمرین قواعد ساخت

در ساخت Chromium خود، یک Rust target جدید به //ui/base/BUILD.gn اضافه کنید که حاوی:

#![allow(unused)]
fn main() {
#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("سلام از Rust!")
}
}

مهم: توجه داشته باشید که no_mangle در اینجا توسط کامپایلر Rust نوعی ناامنی (type of unsafety) در نظر گرفته می‌شود، بنابراین باید کد unsafe را در gn target خود مجاز کنید.

این هدف جدید Rust را به عنوان وابستگی به //ui/base:base اضافه کنید. این تابع را در بالای ui/base/resource/resource_bundle.cc اعلام کنید (بعداً خواهیم دید که چگونه می‌توان این کار را با ابزارهای تولید bindings خودکار کرد):

extern "C" void hello_from_rust();

این تابع را از جایی در ui/base/resource/resource_bundle.cc فراخوانی کنید - ما قسمت بالای ResourceBundle::MaybeMangleLocalizedString را پیشنهاد می‌کنیم. Chromium را Build و اجرا کنید و مطمئن شوید که "Hello from Rust!" بارها چاپ می‌شود.

اگر از VSCode استفاده می‌کنید، اکنون Rust را تنظیم کنید تا در VSCode به خوبی کار کند. این کار در تمرین‌های بعدی مفید خواهد بود. اگر موفق شده‌اید، می‌توانید از کلیک راست روی"Go to definition" درprintln! استفاده کنید.

کجا می‌توان help پیدا کرد

• گزینه‌های موجود برای rust_static_library gn template
• اطلاعات درباره #[no_mangle]
• اطلاعات درباره extern "C"
• اطلاعاتی درباره gnهای --export-rust-project switch
• How to install rust-analyzer in VSCode

تست‌کردن

جامعه Rust معمولاً unit testهای را در یک ماژول قرار می‌دهد که در همان فایل منبع کد مورد آزمایش قرار می‌گیرد. این مورد قبل‌تر در دوره پوشش داده شده بود و به این صورت است:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    #[test]
    fn my_test() {
        todo!()
    }
}
}

در Chromium باید unit testها را در یک فایل منبع جداگانه قرار دهیم و همچنان این روش را برای Rust دنبال می‌کنیم --- این باعث می‌شود تست‌ها به طور مداوم قابل کشف باشند و کمک می‌کند از بازسازی فایل‌های .rs برای بار دوم (در پیکربندی test) جلوگیری شود.

این منجر به گزینه‌های زیر برای تست کد Rust در Chromium می‌شود:

• تست‌های Native Rust (یعنی #[test]). خارج از //third_party/rust مناسب نیست.
• تست‌های gtest که در C++ نوشته شده‌اند و Rust را از طریق تماس‌های FFI انجام می‌دهند. زمانی که کد Rust فقط یک لایه نازکی از FFI است و unit testها موجود، پوشش کافی برای ویژگی‌هایی که ارائه می‌کنند کافی است.
• آزمایش‌های gtest که در Rust نوشته شده‌اند و از crate تحت آزمایش از طریق API عمومی آن استفاده می‌کنند (در صورت نیاز از pub mod for_testing { ... } » استفاده می‌کنند. این موضوع در چند اسلاید بعد معرفی شده است.

rust_gtest_interop Library

کتابخانه rust_gtest_interop راهی را ارائه می‌دهد:

• از یک تابع Rust به عنوان یک تست gtest استفاده کنید (با استفاده از #[gtest(...)] attribute)
• از expect_eq! و ماکروهای مشابه (شبیه به assert_eq! استفاده کنید، اما وقتی assertion ناموفق بود، panic نکنید و تست را خاتمه ندهید).

مثال:

use rust_gtest_interop::prelude::*;

#[gtest(MyRustTestSuite, MyAdditionTest)]
fn test_addition() {
    expect_eq!(2 + 2, 4);
}

قواعد GN برای تست‌های Rust

ساده‌ترین راه برای build Rust gtest اضافه‌کردن آن‌ها به یک باینری تست موجود است که از قبل حاوی تست‌هایی است که در ++C نوشته شده‌اند. به عنوان مثال:

test("ui_base_unittests") {
  ...
  sources += [ "my_rust_lib_unittest.rs" ]
  deps += [ ":my_rust_lib" ]
}

نگارش تست‌های Rust در یک static_library جداگانه نیز کار می‌کند، اما نیاز به اعلام دستی وابستگی به کتابخانه‌های پشتیبانی دارد:

rust_static_library("my_rust_lib_unittests") {
  testonly = true
  is_gtest_unittests = true
  crate_root = "my_rust_lib_unittest.rs"
  sources = [ "my_rust_lib_unittest.rs" ]
  deps = [
    ":my_rust_lib",
    "//testing/rust_gtest_interop",
  ]
}

test("ui_base_unittests") {
  ...
  deps += [ ":my_rust_lib_unittests" ]
}

chromium::import! Macro

پس از افزودن :my_rust_lib به GN deps، همچنان باید نحوه وارد کردن و استفاده از my_rust_lib را از my_rust_lib_unittest.rs یاد بگیریم. ما یک crate_name صریح برای my_rust_lib ارائه نکرده‌ایم، بنابراین نام crate آن بر اساس مسیر و نام کامل هدف محاسبه می‌شود. خوشبختانه ما می‌توانیم با استفاده از ماکرو chromium::import! از chromium crate که به‌طور خودکار وارد می‌شود، درنتیجه از کار با چنین نامی پرهیز کنیم:

chromium::import! {
    "//ui/base:my_rust_lib";
}

use my_rust_lib::my_function_under_test;

در زیر جلدها، ماکرو به چیزی شبیه به زیر گسترش می یابد:

extern crate ui_sbase_cmy_urust_ulib as my_rust_lib;

use my_rust_lib::my_function_under_test;

اطلاعات بیشتر را می‌توانید در doc comment پیدا کنید. ماکرو مربوطه chromium::import.

تمرین تستی

وقت یک تمرین دیگر است!

درChromium build شما باید:

• یک تابع قابل آزمایش در کنار hello_from_rust اضافه کنید. چند پیشنهاد: اضافه کردن دو عدد صحیح دریافت شده به عنوان آرگومان، محاسبه عدد فیبوناچی nام، جمع اعداد صحیح در یک برش و غیره.
• یک فایل..._unittest.rs جداگانه با یک تست برای تابع جدید اضافه کنید.
• تست‌های جدید را به BUILD.gn اضافه کنید.
• تست‌ها را بسازید، اجرا کنید و بررسی کنید که آيا تست جدید به درستی کار می‌کند.

قابلیت همکاری با ++C

جامعه Rust گزینه‌های متعددی را برای C++/Rust interop ارائه می‌دهد، با ابزارهای جدیدی که همیشه در حال توسعه هستند. در حال حاضر، Chromium از ابزاری به نام CXX استفاده می‌کند.

شما کل مرز زبان (language boundary) خود را در یک زبان تعریف interface (که بسیار شبیه Rust به نظر می رسد) توصیف می کنید و سپس ابزارهای CXX اعلان‌هایی را برای توابع و تایپ‌ها در Rust و ++C ایجاد می‌کنند.

برای مثال کامل استفاده از این آموزش CXX را ببینید.

نمونه اتصال‌ها (Bindingها)

‏ CXX مستلزم آن است که کل مرز C++/Rust در ماژول‌های cxx::bridge در کد منبع .rs اعلام شود.

#[cxx::bridge]
mod ffi {
    extern "Rust" {
        type MultiBuf;

        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("example/include/blobstore.h");

        type BlobstoreClient;

        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: &BlobstoreClient, buf: &mut MultiBuf) -> Result<u64>;
    }
}

// Definitions of Rust types and functions go here

محدودیت‌های CXX

تا حد زیادی مفیدترین صفحه هنگام استفاده از CXX برابر type reference است.

‏ CXX به‌طورکلی مناسب مواردی است که:

• اینترفیس ++Rust-C شما به اندازه کافی ساده است که می‌توانید همه آن را اعلام یا declare کنید.
• شما فقط از تایپ‌هایی استفاده می‌کنید که قبلاً توسط CXX ​​پشتیبانی می‌شوند، برای مثالstd::unique_ptr, std::string, &[u8] و غیره.

این مورد محدودیت‌های زیادی دارد --- برای مثال عدم پشتیبانی از تایپ 'Option' Rust.

این محدودیت‌ها ما را محدود می‌کنند تا از Rust در Chromium فقط برای "گره‌های برگ" به خوبی ایزوله شده استفاده کنیم نه برای تعامل دلخواه ++Rust-C. هنگام در نظر گرفتن یک مورد استفاده برای Rust در Chromium، یک نقطه شروع خوب این است که پیش نویس پیوندهای CXX برای مرز زبان (language boundary) را پیش‌نویس کنید تا ببینید آیا به اندازه کافی ساده به نظر می رسد یا خیر.

مدیریت خطا CXX

‏ CXX پشتیبانی از Result<T,E> به C++ exception متکی است، بنابراین نمی‌توانیم از آن در Chromium استفاده کنیم. جایگزین‌های آن عبارتند از:

• قسمت T از نتیجه<T، E> می تواند باشد:

  • از طریق پارامترهای خارجی (به عنوان مثال از طریق &mut T) برگردانده شده است. این مستلزم آن است که T بتواند از مرز FFI عبور کند - برای مثال T باید باشد:
    • یک type اولیه (مانند u32 یا usize)
    • تایپی که به طور native توسط cxx پشتیبانی می‌شود (مانند UniquePtr<T>) که دارای یک مقدار پیش‌فرض مناسب برای استفاده در موارد خرابی است (unlike Box<T>).
  • در سمت Rust حفظ شده و از طریق مرجع در معرض دید قرار گرفته است. این کار ممکن است زمانی مورد نیاز باشد که T یک تایپ Rust است که نمی‌تواند از مرز FFI عبور کند و نمی تواند در UniquePtr<T> ذخیره شود.

• قسمت E از Result<T, E> می‌تواند باشد:

  • به‌عنوان یک boolean برگردانده می‌شود (مثلاً true نشان‌دهنده موفقیت و false نشان‌دهنده یک شکست است)
  • حفظ جزئیات خطا در تئوری امکان پذیر است، اما تاکنون در عمل مورد نیاز نبوده است.

مدیریت خطا CXX: مثال QR

تولید کد QR نمونه‌ای است که در آن بولی برای ارتباط موفقیت در مق‌بل شکست و جایی که نتیجه موفقیت آمیز را می‌توان از مرز FFI عبور داد استفاده می شود:

#[cxx::bridge(namespace = "qr_code_generator")]
mod ffi {
    extern "Rust" {
        fn generate_qr_code_using_rust(
            data: &[u8],
            min_version: i16,
            out_pixels: Pin<&mut CxxVector<u8>>,
            out_qr_size: &mut usize,
        ) -> bool;
    }
}

مدیریت خطا CXX: مثال PNG

نمونه اولیه PNG decoder نشان می‌دهد که وقتی نتیجه موفقیت آمیز نمی‌تواند از مرز FFI عبور کند و چه کاری می توان انجام داد:

#[cxx::bridge(namespace = "gfx::rust_bindings")]
mod ffi {
    extern "Rust" {
        /// This returns an FFI-friendly equivalent of `Result<PngReader<'a>,
        /// ()>`.
        fn new_png_reader<'a>(input: &'a [u8]) -> Box<ResultOfPngReader<'a>>;

        /// C++ bindings for the `crate::png::ResultOfPngReader` type.
        type ResultOfPngReader<'a>;
        fn is_err(self: &ResultOfPngReader) -> bool;
        fn unwrap_as_mut<'a, 'b>(
            self: &'b mut ResultOfPngReader<'a>,
        ) -> &'b mut PngReader<'a>;

        /// C++ bindings for the `crate::png::PngReader` type.
        type PngReader<'a>;
        fn height(self: &PngReader) -> u32;
        fn width(self: &PngReader) -> u32;
        fn read_rgba8(self: &mut PngReader, output: &mut [u8]) -> bool;
    }
}

استفاده از cxx در Chromium

در Chromium، یک #[cxx::bridge] mod مستقل برای هر برگ گره‌ای که می‌خواهیم از Rust استفاده کنیم را تعریف می‌کنیم. شما معمولاً برای هر rust_static_library یکی دارید. پس فقط اضافه کنید.

cxx_bindings = [ "my_rust_file.rs" ]
   # list of files containing #[cxx::bridge], not all source files
allow_unsafe = true

به هدف rust_static_library موجود در کنار crate_root و sources.

headerهای ++C در یک مکان منطقی تولید می‌شوند، بنابراین شما می‌توانید

#include "ui/base/my_rust_file.rs.h"

برخی از توابع کاربردی را در //base برای تبدیل به/از تایپ‌های ++Chromium C به انواع CXX Rust پیدا خواهید کرد --- برای مثال [SpanToRustSlice](https://source.chromium.org/chromium/chromium/src /+/main:base/containers/span_rust.h;l=21).

تمرین: قابلیت همکاری با ++C

قسمت اول

• در فایل Rust که قبلاً ایجاد کرده‌اید، یک #[cxx::bridge] اضافه کنید که یک تابع را مشخص می‌کند که باید از++C فراخوانی شود که نام hello_from_rust دارد، بدون اینکه پارامتر و هیچ مقداری برگرداند.
• تابع hello_from_rust قبلی خود را برای حذف extern "C" و #[no_mangle] تغییر دهید. حالا این فقط یک تابع استاندارد Rust است.
• هدف gn خود را برای ایجاد این پیوندها (bindings) تغییر دهید.
• در کد ++C خود، forward-declaration برای hello_from_rust را حذف کنید. در عوض، فایل هِدِر تولید شده را اضافه کنید.
• Build و run!

قسمت دوم

ایده خوبی است که کمی با CXX بازی کنید. این به شما کمک می کند تا به این فکر کنید که Rust در Chromium واقعا چقدر انعطاف پذیر است.

برخی از چیزهایی که باید امتحان کنید:

• از Rust دوباره به ++C فراخوانی کنید. درنهایت شما نیاز خواهید داشت:
  • یک فایل هِدِر اضافی که می‌توانید از cxx::bridge خود include! را وارد کنید. شما باید تابع ++C خود را در آن فایل هِدِر جدید اعلام کنید.
  • یک بلوک unsafe برای فراخوانی چنین تابعی، یا به طور متناوب کلمه کلیدی unsafe را در #[cxx::bridge] خود همانطور که در اینجا توضیح داده شده است.
  • همچنین ممکن است لازم باشد#include "third_party/rust/cxx/v1/crate/include/cxx.h" را وارد کنید.
• یک رشته++C را از ++C به Rust منتقل کنید.
• ارسال یک reference از یک C++ object به Rust .
• عمداً امضاهای تابع Rust را که از #[cxx::bridge] مطابقت ندارند، دریافت کنید و به خطاهایی که می بینید عادت کنید.
• عمداً امضاهای تابع ++C را که از #[cxx::bridge] مطابقت ندارند، دریافت کنید و به خطاهایی که می بینید عادت کنید.
• یک std::unique_ptr از نوعی از ++C را به Rust ارسال کنید، به طوری که Rust بتواند دارای یک C++ object باشد.
• یک Rust object ایجاد کنید و آن را به ++C ارسال کنید تا ++C مالک آن باشد. (نکته: شما به یک Box نیاز دارید).
• چند متد را در نوع ++C اعلام کنید. آنها را از Rust فراخوانی کنید.
• چند متد را در Rust type اعلام کنید. از ++C آن‌ها را فراخوانی کنید.

قسمت سوم