لغة برمجة Rust

بقلم ستيف كلابنيك، كارول نيكولز، وكريس كرايشو، بمساهمات من مجتمع Rust

تفترض هذه النسخة من النص أنك تستخدم Rust 1.90.0 (الإصدار 1.90.0) الصادر في 2025-09-18 أو إصدارًا أحدث مع تعيين edition = "2024" في ملف Cargo.toml الخاص بجميع المشاريع لتكوينها لاستخدام أساليب برمجية (Idioms) إصدار Rust 2024. راجع قسم التثبيت (Installation) في الفصل 1 للحصول على تعليمات حول تثبيت Rust أو تحديثه، وراجع الملحق هـ (Appendix E) لمعلومات عن الإصدارات.

يتوفر التنسيق HTML عبر الإنترنت على https://doc.rust-lang.org/stable/book/ وبشكل غير متصل مع تثبيتات Rust التي تمت باستخدام rustup؛ شغّل الأمر rustup doc --book لفتحه.

تتوفر أيضًا عدة [ترجمات] من المجتمع.

يتوفر هذا النص في صيغة كتاب ورقي وكتاب إلكتروني من دار No Starch Press.

🚨 هل تريد تجربة تعلم أكثر تفاعلية؟ جرّب إصدارًا مختلفًا من كتاب Rust، يتضمن: اختبارات، تمييز، تصورات، والمزيد: https://rust-book.cs.brown.edu

مقدمة

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

في هذه المرحلة، من السهل الإشارة إلى الميزات الرائعة التي تقدمها Rust لشرح هذا الانفجار في الاهتمام والتبني. من لا يريد سلامة الذاكرة (Memory Safety)، وأداء (Performance) سريع، ومترجم (compiler) ودود، وأدوات (Tooling) رائعة، إلى جانب مجموعة أخرى من الميزات المذهلة؟ لغة Rust التي تراها اليوم تجمع بين سنوات من البحث في برمجة الأنظمة مع الحكمة العملية لمجتمع حيوي وشغوف. تم تصميم هذه اللغة بهدف واضح وصُنعت بعناية، مقدمة للمطورين أداة تسهل كتابة كود آمن، سريع وموثوق.

لكن ما يجعل Rust مميزة حقًا هو جذورها في تمكينك، المستخدم، من تحقيق أهدافك. هذه لغة تريد لك النجاح، ومبدأ التمكين يتغلغل في جوهر المجتمع الذي يبني ويحافظ ويدافع عن هذه اللغة. منذ الإصدار السابق لهذا النص الحاسم، تطورت Rust بشكل أكبر لتصبح لغة عالمية وموثوقة بحق. مشروع Rust مدعوم الآن بقوة من قبل مؤسسة Rust Foundation، التي تستثمر أيضًا في مبادرات رئيسية لضمان أن تكون Rust آمنة، مستقرة، ومستدامة.

يعد هذا الإصدار من The Rust Programming Language تحديثًا شاملًا، يعكس تطور اللغة على مر السنين ويوفر معلومات جديدة قيّمة. لكنه ليس مجرد دليل للنحو والمكتبات—بل دعوة للانضمام إلى مجتمع يُقدّر الجودة، الأداء، والتصميم المدروس. سواء كنت مطورًا متمرسًا يتطلع لاستكشاف Rust لأول مرة أو Rustacean ذو خبرة يريد صقل مهاراته، يقدم هذا الإصدار شيئًا للجميع.

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

مرحبًا بك في مجتمع Rust!

• بيك رامبول، المدير التنفيذي لمؤسسة Rust Foundation

مقدمة (Introduction)

ملاحظة: هذه الطبعة من الكتاب هي نفسها طبعة لغة البرمجة رست (The Rust Programming Language) المتوفرة في شكل مطبوع وكتاب إلكتروني من No Starch Press.

مرحباً بكم في كتاب لغة البرمجة رست، وهو كتاب تمهيدي حول Rust. تساعدك لغة البرمجة Rust على كتابة برمجيات أسرع وأكثر موثوقية. غالباً ما تتعارض بيئة العمل عالية المستوى (High-level ergonomics) والتحكم منخفض المستوى (low-level control) في تصميم لغات البرمجة؛ وتتحدى Rust هذا الصراع. من خلال الموازنة بين القدرة التقنية القوية وتجربة المطور الرائعة، تمنحك Rust خيار التحكم في التفاصيل منخفضة المستوى (مثل استخدام الذاكرة (memory usage)) دون كل العناء المرتبط تقليدياً بهذا التحكم.

لمن صُممت Rust

تعد Rust مثالية للعديد من الأشخاص لمجموعة متنوعة من الأسباب. دعونا نلقي نظرة على عدد قليل من أهم المجموعات.

فرق المطورين (Teams of Developers)

تثبت Rust أنها أداة إنتاجية للتعاون بين فرق كبيرة من المطورين الذين لديهم مستويات متفاوتة من المعرفة ببرمجة الأنظمة (systems programming). الكود منخفض المستوى عرضة للعديد من الأخطاء البرمجية (bugs) الدقيقة، والتي لا يمكن اكتشافها في معظم اللغات الأخرى إلا من خلال الاختبار المكثف ومراجعة الكود (code review) الدقيقة من قبل مطورين ذوي خبرة. في Rust، يلعب المصرف (compiler) دور الحارس من خلال رفض تصريف (compile) الكود الذي يحتوي على هذه الأخطاء المراوغة، بما في ذلك أخطاء التزامن (concurrency bugs). من خلال العمل جنباً إلى جنب مع compiler، يمكن للفريق قضاء وقته في التركيز على منطق البرنامج بدلاً من مطاردة bugs.

تجلب Rust أيضاً أدوات مطورين معاصرة إلى عالم برمجة الأنظمة:

• Cargo، وهو مدير الاعتمادات (dependency manager) وأداة البناء (build tool) المضمنة، يجعل إضافة الاعتمادات (dependencies) وتصريفها وإدارتها أمراً سهلاً ومتسقاً عبر نظام Rust البيئي (ecosystem).
• أداة التنسيق rustfmt تضمن أسلوب ترميز (coding style) متسقاً بين المطورين.
• خادم لغة رست (Rust Language Server) يدعم تكامل بيئة التطوير المتكاملة (IDE) لإكمال الكود ورسائل الخطأ المضمنة.

باستخدام هذه الأدوات وغيرها في نظام Rust البيئي، يمكن للمطورين أن يكونوا منتجين أثناء كتابة كود على مستوى الأنظمة.

الطلاب (Students)

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

الشركات (Companies)

تستخدم مئات الشركات، الكبيرة والصغيرة، Rust في الإنتاج لمجموعة متنوعة من المهام، بما في ذلك أدوات سطر الأوامر (command line tools)، وخدمات الويب، وأدوات العمليات البرمجية (DevOps tooling)، والأجهزة المدمجة (embedded devices)، وتحليل وترميز الصوت والفيديو، والعملات المشفرة، والمعلوماتية الحيوية، ومحركات البحث، وتطبيقات إنترنت الأشياء (Internet of Things)، والتعلم الآلي (machine learning)، وحتى أجزاء رئيسية من متصفح الويب Firefox.

مطورو البرمجيات مفتوحة المصدر (Open Source Developers)

Rust مخصصة للأشخاص الذين يرغبون في بناء لغة البرمجة Rust، والمجتمع، وأدوات المطورين، والمكتبات (libraries). يسعدنا أن تساهم في لغة Rust.

الأشخاص الذين يقدرون السرعة والاستقرار

Rust مخصصة للأشخاص الذين يتوقون إلى السرعة والاستقرار في اللغة. بالسرعة، نعني كلاً من مدى سرعة تشغيل كود Rust والسرعة التي تتيح لك بها Rust كتابة البرامج. تضمن فحوصات compiler في Rust الاستقرار من خلال إضافات الميزات وإعادة هيكلة الكود (refactoring). هذا على عكس الكود القديم الهش في اللغات التي لا تحتوي على هذه الفحوصات، والتي غالباً ما يخشى المطورون تعديلها. من خلال السعي وراء التجريدات صفرية التكلفة (zero-cost abstractions) — وهي ميزات عالية المستوى يتم تصريفها إلى كود منخفض المستوى بنفس سرعة الكود المكتوب يدوياً — تسعى Rust لجعل الكود الآمن كوداً سريعاً أيضاً.

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

لمن صُمم هذا الكتاب

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

كيفية استخدام هذا الكتاب

بشكل عام، يفترض هذا الكتاب أنك تقرأه بالتسلسل من البداية إلى النهاية. تبني الفصول اللاحقة على المفاهيم الواردة في الفصول السابقة، وقد لا تتعمق الفصول السابقة في تفاصيل موضوع معين ولكنها ستعيد زيارة الموضوع في فصل لاحق.

ستجد نوعين من الفصول في هذا الكتاب: فصول المفاهيم وفصول المشاريع. في فصول المفاهيم، ستتعلم عن جانب من جوانب Rust. في فصول المشاريع، سنبني برامج صغيرة معاً، ونطبق ما تعلمته حتى الآن. الفصل 2 والفصل 12 والفصل 21 هي فصول مشاريع؛ والباقي فصول مفاهيم.

يشرح الفصل 1 كيفية تثبيت Rust، وكيفية كتابة برنامج “Hello, world!”، وكيفية استخدام Cargo، وهو مدير الحزم (package manager) وأداة البناء في Rust. الفصل 2 هو مقدمة عملية لكتابة برنامج في Rust، حيث يجعلك تبني لعبة تخمين الأرقام. هنا، نغطي المفاهيم على مستوى عالٍ، وستوفر الفصول اللاحقة تفاصيل إضافية. إذا كنت ترغب في البدء بالتطبيق العملي على الفور، فإن الفصل 2 هو المكان المناسب لذلك. إذا كنت متعلماً دقيقاً بشكل خاص وتفضل تعلم كل التفاصيل قبل الانتقال إلى الخطوة التالية، فقد ترغب في تخطي الفصل 2 والانتقال مباشرة إلى الفصل 3، الذي يغطي ميزات Rust المشابهة لميزات لغات البرمجة الأخرى؛ ثم يمكنك العودة إلى الفصل 2 عندما ترغب في العمل على مشروع يطبق التفاصيل التي تعلمتها.

في الفصل 4، ستتعلم عن نظام الملكية (ownership system) في Rust. يناقش الفصل 5 الهياكل (structs) والدوال (methods). يغطي الفصل 6 التعدادات (enums)، وتعبيرات match ، وبنيات تدفق التحكم if let و let...else. ستستخدم structs و enums لإنشاء أنواع مخصصة.

في الفصل 7، ستتعلم عن نظام الوحدات (module system) في Rust وعن قواعد الخصوصية لتنظيم الكود الخاص بك وواجهة برمجة التطبيقات (API) العامة الخاصة به. يناقش الفصل 8 بعض هياكل بيانات المجموعات (collection data structures) الشائعة التي توفرها المكتبة القياسية (standard library): المتجهات (vectors)، والسلاسل النصية (strings)، وخرائط التجزئة (hash maps). يستكشف الفصل 9 فلسفة وتقنيات معالجة الأخطاء (error-handling) في Rust.

يتعمق الفصل 10 في الأنواع العامة (generics)، والسمات (traits)، وفترات الحياة (lifetimes)، والتي تمنحك القدرة على تعريف كود ينطبق على أنواع متعددة. الفصل 11 يدور حول الاختبار (testing)، والذي حتى مع ضمانات الأمان في Rust يعد ضرورياً لضمان صحة منطق برنامجك. في الفصل 12، سنبني تنفيذنا الخاص لمجموعة فرعية من الوظائف من أداة سطر الأوامر grep التي تبحث عن نص داخل الملفات. لهذا، سنستخدم العديد من المفاهيم التي ناقشناها في الفصول السابقة.

يستكشف الفصل 13 الإغلاقات (closures) والمكررات (iterators): ميزات Rust التي تأتي من لغات البرمجة الوظيفية (functional programming languages). في الفصل 14، سنفحص Cargo بمزيد من العمق ونتحدث عن أفضل الممارسات لمشاركة مكتباتك مع الآخرين. يناقش الفصل 15 المؤشرات الذكية (smart pointers) التي توفرها standard library والسمات التي تمكن وظائفها.

في الفصل 16، سنستعرض نماذج مختلفة من البرمجة المتزامنة (concurrent programming) ونتحدث عن كيفية مساعدة Rust لك في البرمجة في خيوط معالجة (threads) متعددة دون خوف. في الفصل 17، نبني على ذلك من خلال استكشاف بناء جملة async و await في Rust، جنباً إلى جنب مع المهام (tasks)، والمستقبليات (futures)، والمجاري (streams)، ونموذج التزامن خفيف الوزن الذي تمكنه.

ينظر الفصل 18 في كيفية مقارنة اصطلاحات (idioms) Rust بمبادئ البرمجة كائنية التوجه التي قد تكون مألوفاً بها. الفصل 19 هو مرجع حول الأنماط (patterns) ومطابقة الأنماط (pattern matching)، وهي طرق قوية للتعبير عن الأفكار عبر برامج Rust. يحتوي الفصل 20 على مجموعة متنوعة من المواضيع المتقدمة ذات الأهمية، بما في ذلك Rust غير الآمنة (unsafe Rust)، والماكرو (macros)، والمزيد حول lifetimes و traits والأنواع والدوال و closures.

في الفصل 21، سنكمل مشروعاً سنقوم فيه بتنفيذ خادم ويب متعدد الخيوط منخفض المستوى!

أخيراً، تحتوي بعض الملاحق على معلومات مفيدة حول اللغة في شكل مرجعي أكثر. يغطي الملحق أ الكلمات المفتاحية (keywords) في Rust، ويغطي الملحق ب العمليات والرموز، ويغطي الملحق ج السمات القابلة للاشتقاق (derivable traits) التي توفرها standard library، ويغطي الملحق د بعض أدوات التطوير المفيدة، ويشرح الملحق هـ إصدارات (editions) Rust. في الملحق و، يمكنك العثور على ترجمات للكتاب، وفي الملحق ز سنغطي كيفية صنع Rust وما هي نسخة nightly من Rust.

لا توجد طريقة خاطئة لقراءة هذا الكتاب: إذا كنت تريد التخطي للأمام، فافعل ذلك! قد تضطر إلى العودة إلى الفصول السابقة إذا واجهت أي ارتباك. لكن افعل ما يناسبك.

جزء مهم من عملية تعلم Rust هو تعلم كيفية قراءة رسائل الخطأ التي يعرضها compiler: ستوجهك هذه الرسائل نحو الكود الذي يعمل. على هذا النحو، سنقدم العديد من الأمثلة التي لا يتم تصريفها جنباً إلى جنب مع رسالة الخطأ التي سيظهرها لك compiler في كل موقف. اعلم أنك إذا أدخلت وشغلت مثالاً عشوائياً، فقد لا يتم تصريفه! تأكد من قراءة النص المحيط لمعرفة ما إذا كان المثال الذي تحاول تشغيله يهدف إلى إظهار خطأ. في معظم الحالات، سنقودك إلى النسخة الصحيحة من أي كود لا يتم تصريفه. سيساعدك Ferris أيضاً في تمييز الكود الذي لا يُقصد منه العمل:

Ferris	المعنى
	هذا الكود لا يتم تصريفه!
	هذا الكود يسبب هلعاً (panics)!
	هذا الكود لا ينتج السلوك المطلوب.

في معظم الحالات، سنقودك إلى النسخة الصحيحة من أي كود لا يتم تصريفه.

الكود المصدري (Source Code)

يمكن العثور على الملفات المصدرية التي تم إنشاء هذا الكتاب منها على GitHub.

Getting Started

لنبدأ رحلتك في عالم Rust! هناك الكثير لتتعلمه، لكن كل رحلة تبدأ من مكان ما.

في هذا الفصل، سنتناول ما يلي:

• تثبيت Rust على أنظمة Linux و macOS و Windows

• كتابة برنامج يطبع عبارة Hello, world!

• استخدام Cargo، مدير الحزم ونظام البناء الخاص بـ Rust

التثبيت (Installation)

التثبيت (Installation)

الخطوة الأولى هي تثبيت Rust. سنقوم بتنزيل Rust من خلال rustup، وهي أداة سطر أوامر (command line tool) لإدارة إصدارات Rust والأدوات المرتبطة بها. ستحتاج إلى اتصال بالإنترنت لعملية التنزيل.

ملاحظة: إذا كنت تفضل عدم استخدام rustup لسبب ما، فيرجى الاطلاع على صفحة طرق تثبيت Rust الأخرى للحصول على المزيد من الخيارات.

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

ترميز سطر الأوامر (Command Line Notation)

في هذا الفصل وطوال الكتاب، سنعرض بعض الأوامر المستخدمة في الطرفية (terminal). تبدأ جميع الأسطر التي يجب عليك إدخالها في terminal بالرمز $. لا تحتاج إلى كتابة الحرف $. إنه موجه سطر الأوامر (command line prompt) الذي يظهر للإشارة إلى بداية كل أمر. الأسطر التي لا تبدأ بـ $ $ عادةً ما تعرض إخراج الأمر السابق. بالإضافة إلى ذلك، ستستخدم الأمثلة الخاصة بـ PowerShell الرمز > بدلاً من $.

تثبيت rustup على Linux أو macOS

إذا كنت تستخدم Linux أو macOS، فافتح terminal وأدخل الأمر التالي:

$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

يقوم الأمر بتنزيل سكريبت (script) وبدء تثبيت أداة rustup، والتي تثبت أحدث إصدار مستقر من Rust. قد يُطلب منك إدخال كلمة المرور الخاصة بك. إذا نجح التثبيت، فسيظهر السطر التالي:

Rust is installed now. Great!

ستحتاج أيضًا إلى رابط (linker)، وهو برنامج تستخدمه Rust لضم مخرجاتها المجمعة في ملف واحد. من المحتمل أن يكون لديك واحد بالفعل. إذا تلقيت أخطاء linker، فيجب عليك تثبيت مترجم لغة C (C compiler)، والذي سيتضمن عادةً linker. يعد C compiler مفيدًا أيضًا لأن بعض حزم Rust الشائعة تعتمد على كود C وستحتاج إلى C compiler.

على macOS، يمكنك الحصول على C compiler عن طريق تشغيل:

$ xcode-select --install

يجب على مستخدمي Linux عمومًا تثبيت GCC أو Clang، وفقًا لوثائق التوزيعة (distribution) الخاصة بهم. على سبيل المثال، إذا كنت تستخدم Ubuntu، يمكنك تثبيت حزمة build-essential.

تثبيت rustup على Windows

على Windows، انتقل إلى https://www.rust-lang.org/tools/install واتبع التعليمات لتثبيت Rust. في مرحلة ما من التثبيت، سيُطلب منك تثبيت Visual Studio. يوفر هذا linker والمكتبات الأصلية (native libraries) اللازمة لتجميع البرامج. إذا كنت بحاجة إلى مزيد من المساعدة في هذه الخطوة، فراجع https://rust-lang.github.io/rustup/installation/windows-msvc.html.

يستخدم باقي هذا الكتاب أوامر تعمل في كل من cmd.exe و PowerShell. إذا كانت هناك اختلافات محددة، فسنشرح أيها يجب استخدامه.

استكشاف الأخطاء وإصلاحها (Troubleshooting)

للتحقق مما إذا كنت قد قمت بتثبيت Rust بشكل صحيح، افتح shell وأدخل هذا السطر:

$ rustc --version

يجب أن ترى رقم الإصدار (version number)، ورمز التثبيت (commit hash)، وتاريخ التثبيت (commit date) لأحدث إصدار مستقر تم إصداره، بالتنسيق التالي:

rustc x.y.z (abcabcabc yyyy-mm-dd)

إذا رأيت هذه المعلومات، فقد قمت بتثبيت Rust بنجاح! إذا لم تر هذه المعلومات، فتحقق من أن Rust موجود في متغير النظام %PATH% الخاص بك على النحو التالي.

في Windows CMD، استخدم:

> echo %PATH%

في PowerShell، استخدم:

> echo $env:Path

في Linux و macOS، استخدم:

$ echo $PATH

إذا كان كل هذا صحيحًا ولا تزال Rust لا تعمل، فهناك عدد من الأماكن التي يمكنك الحصول على المساعدة منها. اكتشف كيفية التواصل مع Rustaceans الآخرين (لقب سخيف نطلق به على أنفسنا) على صفحة المجتمع.

التحديث وإلغاء التثبيت (Updating and Uninstalling)

بمجرد تثبيت Rust عبر rustup، يصبح التحديث إلى إصدار تم إصداره حديثًا أمرًا سهلاً. من shell الخاص بك، قم بتشغيل سكريبت التحديث التالي:

$ rustup update

لإلغاء تثبيت Rust و rustup، قم بتشغيل سكريبت إلغاء التثبيت التالي من shell الخاص بك:

$ rustup self uninstall

قراءة الوثائق المحلية (Reading the Local Documentation)

يتضمن تثبيت Rust أيضًا نسخة محلية من الوثائق حتى تتمكن من قراءتها دون اتصال بالإنترنت. قم بتشغيل rustup doc لفتح الوثائق المحلية في متصفحك.

في أي وقت يتم فيه توفير نوع (type) أو دالة (function) بواسطة المكتبة القياسية (standard library) ولست متأكدًا مما تفعله أو كيفية استخدامها، استخدم وثائق واجهة برمجة التطبيقات (API) لمعرفة ذلك!

استخدام محررات النصوص وبيئات التطوير المتكاملة (Using Text Editors and IDEs)

لا يفترض هذا الكتاب أي شيء حول الأدوات التي تستخدمها لكتابة كود Rust. أي محرر نصوص تقريبًا سيقوم بالمهمة! ومع ذلك، فإن العديد من محررات النصوص و IDEs لديها دعم مدمج لـ Rust. يمكنك دائمًا العثور على قائمة حديثة إلى حد ما للعديد من المحررات و IDEs على صفحة الأدوات على موقع Rust على الويب.

العمل دون اتصال بالإنترنت مع هذا الكتاب (Working Offline with This Book)

في العديد من الأمثلة، سنستخدم حزم Rust تتجاوز standard library. للعمل من خلال تلك الأمثلة، ستحتاج إما إلى اتصال بالإنترنت أو إلى تنزيل تلك التبعيات (dependencies) مسبقًا. لتنزيل dependencies مسبقًا، يمكنك تشغيل الأوامر التالية. (سنشرح ما هو cargo وما يفعله كل من هذه الأوامر بالتفصيل لاحقًا.)

$ cargo new get-dependencies
$ cd get-dependencies
$ cargo add rand@0.8.5 trpl@0.2.0

سيؤدي هذا إلى تخزين التنزيلات لهذه الحزم مؤقتًا (cache) بحيث لن تحتاج إلى تنزيلها لاحقًا. بمجرد تشغيل هذا الأمر، لا تحتاج إلى الاحتفاظ بمجلد get-dependencies. إذا قمت بتشغيل هذا الأمر، يمكنك استخدام العلامة --offline مع جميع أوامر cargo في بقية الكتاب لاستخدام هذه الإصدارات المخزنة مؤقتًا بدلاً من محاولة استخدام الشبكة.

أهلاً بالعالم! (Hello, World!)

مرحباً أيها العالم! (Hello, World!)

الآن بعد أن قمت بتثبيت Rust، حان الوقت لكتابة أول برنامج Rust لك. من التقليدي عند تعلم لغة جديدة كتابة برنامج صغير يطبع النص Hello, world! على الشاشة، لذلك سنفعل الشيء نفسه هنا!

ملاحظة: يفترض هذا الكتاب إلمامًا أساسيًا بسطر الأوامر (command line). لا تفرض Rust متطلبات محددة حول التحرير أو الأدوات الخاصة بك أو مكان وجود الكود الخاص بك، لذلك إذا كنت تفضل استخدام بيئة التطوير المتكاملة (IDE) بدلاً من command line، فلا تتردد في استخدام IDE المفضل لديك. تحتوي العديد من IDEs الآن على درجة معينة من دعم Rust؛ تحقق من وثائق IDE للحصول على التفاصيل. يركز فريق Rust على تمكين دعم رائع لـ IDE عبر محلل لغة Rust (rust-analyzer). راجع الملحق د لمزيد من التفاصيل.

إعداد دليل المشروع (Project Directory Setup)

ستبدأ بإنشاء دليل (directory) لتخزين كود Rust الخاص بك. لا يهم Rust مكان وجود الكود الخاص بك، ولكن بالنسبة للتمارين والمشاريع في هذا الكتاب، نقترح إنشاء دليل المشاريع (projects directory) في دليلك الرئيسي والاحتفاظ بجميع مشاريعك هناك.

افتح الطرفية (terminal) وأدخل الأوامر التالية لإنشاء projects directory ودليل لمشروع “Hello, world!” داخل projects directory.

بالنسبة لنظامي Linux و macOS و PowerShell على Windows، أدخل ما يلي:

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

بالنسبة لـ Windows CMD، أدخل ما يلي:

> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world

أساسيات برنامج Rust (Rust Program Basics)

بعد ذلك، قم بإنشاء ملف مصدر (source file) جديد وسمه main.rs. تنتهي ملفات Rust دائمًا بامتداد .rs (extension). إذا كنت تستخدم أكثر من كلمة في اسم ملفك، فإن الاصطلاح (convention) هو استخدام شرطة سفلية (underscore) للفصل بينها. على سبيل المثال، استخدم hello_world.rs بدلاً من helloworld.rs.

الآن افتح ملف main.rs الذي أنشأته للتو وأدخل الكود في القائمة 1-1.

fn main() {
    println!("Hello, world!");
}

احفظ الملف وعد إلى نافذة terminal الخاصة بك في دليل ~/projects/hello_world. على Linux أو macOS، أدخل الأوامر التالية لتجميع (compile) وتشغيل (run) الملف:

$ rustc main.rs
$ ./main
Hello, world!

على Windows، أدخل الأمر .\main بدلاً من ./main:

> rustc main.rs
> .\main
Hello, world!

بغض النظر عن نظام التشغيل (operating system) الخاص بك، يجب أن تتم طباعة السلسلة النصية (string) Hello, world! على terminal. إذا لم تر هذا الإخراج، فارجع إلى جزء “استكشاف الأخطاء وإصلاحها” من قسم التثبيت للحصول على طرق للمساعدة.

إذا تمت طباعة Hello, world!، فتهانينا! لقد كتبت رسميًا برنامج Rust. هذا يجعلك مبرمج Rust - مرحبًا بك!

تشريح برنامج Rust (The Anatomy of a Rust Program)

دعنا نراجع برنامج “Hello, world!” هذا بالتفصيل. إليك الجزء الأول من اللغز:

fn main() {

}

تحدد هذه الأسطر دالة (function) تسمى main. الدالة الرئيسية (main function) خاصة: إنها دائمًا أول كود يتم تشغيله في كل برنامج Rust قابل للتنفيذ (executable). هنا، يعلن السطر الأول عن function تسمى main ليس لها معاملات (parameters) ولا تُرجع شيئًا. إذا كانت هناك parameters، فستكون داخل الأقواس (()).

جسم الدالة (function body) مغلف بأقواس معقوفة (curly brackets) {}. تتطلب Rust curly brackets حول جميع أجسام الدوال. من الأسلوب الجيد وضع القوس المعقوف الافتتاحي في نفس السطر مثل إعلان function، مع إضافة مسافة واحدة بينهما.

ملاحظة: إذا كنت ترغب في الالتزام بأسلوب قياسي عبر مشاريع Rust، يمكنك استخدام أداة منسق الكود (rustfmt) التلقائية لتنسيق الكود الخاص بك بأسلوب معين (المزيد حول rustfmt في الملحق د). قام فريق Rust بتضمين هذه الأداة مع توزيع Rust القياسي، مثل rustc، لذلك يجب أن تكون مثبتة بالفعل على جهاز الكمبيوتر الخاص بك!

يحتوي function body لـ main على الكود التالي:

#![allow(unused)]
fn main() {
println!("Hello, world!");
}

يقوم هذا السطر بكل العمل في هذا البرنامج الصغير: إنه يطبع نصًا على الشاشة. هناك ثلاث تفاصيل مهمة يجب ملاحظتها هنا.

أولاً، println! يستدعي ماكرو (macro) Rust. إذا كان قد استدعى function بدلاً من ذلك، فسيتم إدخاله كـ println (بدون !). macros Rust هي طريقة لكتابة كود يولد كودًا لتوسيع بناء جملة Rust، وسنناقشها بمزيد من التفصيل في الفصل 20. في الوقت الحالي، تحتاج فقط إلى معرفة أن استخدام ! يعني أنك تستدعي macro بدلاً من function عادية وأن macros لا تتبع دائمًا نفس قواعد functions.

ثانيًا، ترى string "Hello, world!". نمرر هذه string كوسيط (argument) إلى println!، ويتم طباعة string على الشاشة.

ثالثًا، ننهي السطر بفاصلة منقوطة (semicolon) (;)، مما يشير إلى أن هذا التعبير (expression) قد انتهى، والتعبير التالي جاهز للبدء. تنتهي معظم أسطر كود Rust بـ semicolon.

التجميع والتنفيذ (Compilation and Execution)

لقد قمت للتو بتشغيل برنامج تم إنشاؤه حديثًا، لذا دعنا نفحص كل خطوة في العملية.

قبل تشغيل برنامج Rust، يجب عليك تجميعه باستخدام مترجم Rust (Rust compiler) عن طريق إدخال الأمر rustc وتمرير اسم ملف المصدر (source file) الخاص بك إليه، مثل هذا:

$ rustc main.rs

إذا كانت لديك خلفية في C أو C++، فستلاحظ أن هذا مشابه لـ gcc أو clang. بعد التجميع بنجاح، يخرج Rust ملف ثنائي قابل للتنفيذ (binary executable).

على Linux و macOS و PowerShell على Windows، يمكنك رؤية executable عن طريق إدخال الأمر ls في shell الخاص بك:

$ ls
main  main.rs

على Linux و macOS، سترى ملفين. باستخدام PowerShell على Windows، سترى نفس الملفات الثلاثة التي تراها باستخدام CMD. باستخدام CMD على Windows، ستدخل ما يلي:

> dir /B %= the /B option says to only show the file names =%
main.exe
main.pdb
main.rs

يعرض هذا source file بامتداد .rs، و executable (main.exe على Windows، ولكن main على جميع operating systems الأخرى)، وعند استخدام Windows، ملف يحتوي على معلومات تصحيح الأخطاء (debugging information) بامتداد .pdb. من هنا، تقوم بتشغيل ملف main أو main.exe، مثل هذا:

$ ./main # or .\main on Windows

إذا كان main.rs هو برنامج “Hello, world!” الخاص بك، فإن هذا السطر يطبع Hello, world! على terminal الخاص بك.

إذا كنت أكثر دراية بلغة ديناميكية (dynamic language)، مثل Ruby أو Python أو JavaScript، فقد لا تكون معتادًا على تجميع وتشغيل برنامج كخطوات منفصلة. Rust هي لغة مجمعة مسبقاً (ahead-of-time compiled language)، مما يعني أنه يمكنك تجميع برنامج وإعطاء executable لشخص آخر، ويمكنه تشغيله حتى بدون تثبيت Rust. إذا أعطيت شخصًا ملف .rb أو .py أو .js، فإنه يحتاج إلى تثبيت تطبيق Ruby أو Python أو JavaScript (على التوالي). ولكن في تلك اللغات، تحتاج فقط إلى أمر واحد لتجميع وتشغيل برنامجك. كل شيء هو مقايضة في تصميم اللغة.

التجميع باستخدام rustc فقط جيد للبرامج البسيطة، ولكن مع نمو مشروعك، سترغب في إدارة جميع الخيارات وتسهيل مشاركة الكود الخاص بك. بعد ذلك، سنقدم لك أداة كارغو (Cargo)، والتي ستساعدك في كتابة برامج Rust واقعية.

أهلاً كارغو! (Hello, Cargo!)

مرحبًا، Cargo!

إن Cargo هو نظام البناء (build system) ومدير الحزم (package manager) الخاص بلغة Rust. يستخدم معظم مبرمجي Rust (Rustaceans) هذه الأداة لإدارة مشاريعهم لأن Cargo يتولى الكثير من المهام نيابة عنك، مثل بناء الكود الخاص بك، وتنزيل المكتبات التي يعتمد عليها الكود، وبناء تلك المكتبات. (نسمي المكتبات التي يحتاجها الكود الخاص بك بالتبعيات (dependencies)).

أبسط برامج Rust، مثل البرنامج الذي كتبناه حتى الآن، لا تحتوي على أي dependencies. إذا قمنا ببناء مشروع “Hello, world!” باستخدام Cargo، فسيستخدم فقط الجزء من Cargo الذي يتعامل مع بناء الكود الخاص بك. بينما تكتب برامج Rust أكثر تعقيدًا، ستضيف dependencies، وإذا بدأت مشروعًا باستخدام Cargo، فستكون إضافة dependencies أسهل بكثير.

نظرًا لأن الغالبية العظمى من مشاريع Rust تستخدم Cargo، فإن بقية هذا الكتاب تفترض أنك تستخدم Cargo أيضًا. يأتي Cargo مثبتًا مع Rust إذا استخدمت المثبتات الرسمية التي تمت مناقشتها في قسم “Installation”. إذا قمت بتثبيت Rust بوسائل أخرى، فتحقق مما إذا كان Cargo مثبتًا عن طريق إدخال ما يلي في الطرفية (terminal):

$ cargo --version

إذا رأيت رقم إصدار، فأنت تمتلكه! إذا رأيت خطأ، مثل command not found (الأمر غير موجود)، فراجع وثائق طريقة التثبيت الخاصة بك لتحديد كيفية تثبيت Cargo بشكل منفصل.

إنشاء مشروع باستخدام Cargo

دعنا ننشئ مشروعًا جديدًا باستخدام Cargo ونرى كيف يختلف عن مشروع “Hello, world!” الأصلي الخاص بنا. انتقل مرة أخرى إلى دليل المشاريع (projects directory) الخاص بك (أو أي مكان قررت تخزين الكود فيه). ثم، على أي نظام تشغيل، قم بتشغيل ما يلي:

$ cargo new hello_cargo
$ cd hello_cargo

يؤدي الأمر الأول إلى إنشاء دليل ومشروع جديد يسمى hello_cargo. لقد أطلقنا على مشروعنا اسم hello_cargo، ويقوم Cargo بإنشاء ملفاته في دليل يحمل نفس الاسم.

ادخل إلى دليل hello_cargo واعرض قائمة الملفات. سترى أن Cargo قد أنشأ ملفين ودليلاً واحدًا لنا: ملف Cargo.toml ودليل src وبداخله ملف main.rs.

لقد قام أيضًا بتهيئة مستودع Git جديد مع ملف .gitignore. لن يتم إنشاء ملفات Git إذا قمت بتشغيل cargo new داخل مستودع Git موجود؛ يمكنك تجاوز هذا السلوك باستخدام cargo new --vcs=git.

ملاحظة: Git هو نظام شائع للتحكم في الإصدارات (version control system). يمكنك تغيير cargo new لاستخدام نظام تحكم في الإصدارات مختلف أو عدم استخدام نظام تحكم في الإصدارات على الإطلاق باستخدام علم (flag) --vcs. قم بتشغيل cargo new --help لرؤية الخيارات المتاحة.

افتح Cargo.toml في محرر النصوص الذي تختاره. يجب أن يبدو مشابهًا للكود الموجود في القائمة 1-2.

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2024"

[dependencies]

هذا الملف بتنسيق TOML (Tom’s Obvious, Minimal Language)، وهو تنسيق التكوين (configuration format) الخاص بـ Cargo.

السطر الأول، [package]، هو عنوان قسم يشير إلى أن العبارات التالية تقوم بتكوين حزمة (package). بينما نضيف المزيد من المعلومات إلى هذا الملف، سنضيف أقسامًا أخرى.

تحدد الأسطر الثلاثة التالية معلومات التكوين التي يحتاجها Cargo لتجميع (compile) برنامجك: الاسم، والإصدار، وإصدار Rust (edition) المراد استخدامه. سنتحدث عن مفتاح edition في Appendix E.

السطر الأخير، [dependencies]، هو بداية قسم لتدرج فيه أيًا من dependencies الخاصة بمشروعك. في Rust، يشار إلى حزم الكود باسم الصناديق (crates). لن نحتاج إلى أي crates أخرى لهذا المشروع، لكننا سنحتاج إليها في المشروع الأول في الفصل 2، لذا سنستخدم قسم dependencies هذا حينها.

الآن افتح src/main.rs وألقِ نظرة:

Filename: src/main.rs

fn main() {
    println!("Hello, world!");
}

لقد أنشأ Cargo برنامج “Hello, world!” لك، تمامًا مثل البرنامج الذي كتبناه في القائمة 1-1! حتى الآن، الاختلافات بين مشروعنا والمشروع الذي أنشأه Cargo هي أن Cargo وضع الكود في دليل src، ولدينا ملف تكوين Cargo.toml في الدليل العلوي.

يتوقع Cargo أن تعيش ملفات المصدر (source files) الخاصة بك داخل دليل src. دليل المشروع ذو المستوى الأعلى مخصص فقط لملفات README، ومعلومات الترخيص، وملفات التكوين، وأي شيء آخر غير متعلق بالكود الخاص بك. يساعدك استخدام Cargo في تنظيم مشاريعك. هناك مكان لكل شيء، وكل شيء في مكانه.

إذا بدأت مشروعًا لا يستخدم Cargo، كما فعلنا مع مشروع “Hello, world!”، يمكنك تحويله إلى مشروع يستخدم Cargo. انقل كود المشروع إلى دليل src وأنشئ ملف Cargo.toml مناسبًا. إحدى الطرق السهلة للحصول على ملف Cargo.toml هذا هي تشغيل cargo init الذي سيقوم بإنشائه لك تلقائيًا.

بناء وتشغيل مشروع Cargo

الآن دعنا نرى ما هو المختلف عندما نقوم ببناء وتشغيل برنامج “Hello, world!” باستخدام Cargo! من دليل hello_cargo الخاص بك، قم ببناء مشروعك عن طريق إدخال الأمر التالي:

$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

يؤدي هذا الأمر إلى إنشاء ملف قابل للتنفيذ (executable file) في target/debug/hello_cargo (أو target\debug\hello_cargo.exe على Windows) بدلاً من دليلك الحالي. نظرًا لأن البناء الافتراضي هو بناء تصحيح أخطاء (debug build)، يضع Cargo الملف الثنائي (binary) في دليل يسمى debug. يمكنك تشغيل الملف القابل للتنفيذ بهذا الأمر:

$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows
Hello, world!

إذا سارت الأمور على ما يرام، يجب طباعة Hello, world! في terminal. يؤدي تشغيل cargo build لأول مرة أيضًا إلى قيام Cargo بإنشاء ملف جديد في المستوى الأعلى: Cargo.lock. يتتبع هذا الملف الإصدارات الدقيقة لـ dependencies في مشروعك. لا يحتوي هذا المشروع على dependencies، لذا فإن الملف فارغ قليلاً. لن تحتاج أبدًا إلى تغيير هذا الملف يدويًا؛ يتولى Cargo إدارة محتوياته نيابة عنك.

لقد قمنا للتو ببناء مشروع باستخدام cargo build وتشغيله باستخدام ./target/debug/hello_cargo ولكن يمكننا أيضًا استخدام cargo run لتجميع الكود ثم تشغيل الملف القابل للتنفيذ الناتج في أمر واحد:

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

يعد استخدام cargo run أكثر ملاءمة من الاضطرار إلى تذكر تشغيل cargo build ثم استخدام المسار الكامل للملف الثنائي، لذا يستخدم معظم المطورين cargo run.

لاحظ أننا هذه المرة لم نرَ مخرجات تشير إلى أن Cargo كان يقوم بتجميع hello_cargo. أدرك Cargo أن الملفات لم تتغير، لذا لم يقم بإعادة البناء بل قام فقط بتشغيل binary. إذا قمت بتعديل كود المصدر الخاص بك، فسيقوم Cargo بإعادة بناء المشروع قبل تشغيله، وسترى هذا المخرج:

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

يوفر Cargo أيضًا أمرًا يسمى cargo check. يقوم هذا الأمر بفحص الكود الخاص بك بسرعة للتأكد من أنه يتم تجميعه ولكنه لا ينتج ملفًا قابلاً للتنفيذ:

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

لماذا قد لا ترغب في ملف قابل للتنفيذ؟ غالبًا ما يكون cargo check أسرع بكثير من cargo build لأنه يتخطى خطوة إنتاج ملف قابل للتنفيذ. إذا كنت تتحقق باستمرار من عملك أثناء كتابة الكود، فإن استخدام cargo check سيسرع عملية إخبارك إذا كان مشروعك لا يزال يتم تجميعه! على هذا النحو، يقوم العديد من مبرمجي Rust بتشغيل cargo check بشكل دوري أثناء كتابة برنامجهم للتأكد من أنه يتم تجميعه. ثم يقومون بتشغيل cargo build عندما يكونون مستعدين لاستخدام الملف القابل للتنفيذ.

دعنا نلخص ما تعلمناه حتى الآن عن Cargo:

• يمكننا إنشاء مشروع باستخدام cargo new.
• يمكننا بناء مشروع باستخدام cargo build.
• يمكننا بناء وتشغيل مشروع في خطوة واحدة باستخدام cargo run.
• يمكننا بناء مشروع دون إنتاج binary للتحقق من الأخطاء باستخدام cargo check.
• بدلاً من حفظ نتيجة البناء في نفس دليل الكود الخاص بنا، يقوم Cargo بتخزينها في دليل target/debug.

ميزة إضافية لاستخدام Cargo هي أن الأوامر هي نفسها بغض النظر عن نظام التشغيل الذي تعمل عليه. لذا، في هذه المرحلة، لن نقدم تعليمات محددة لنظامي التشغيل Linux و macOS مقابل Windows.

البناء للإصدار (Building for Release)

عندما يكون مشروعك جاهزًا أخيرًا للإصدار، يمكنك استخدام cargo build --release لتجميعه مع التحسينات (optimizations). سيؤدي هذا الأمر إلى إنشاء ملف قابل للتنفيذ في target/release بدلاً من target/debug. تجعل optimizations كود Rust الخاص بك يعمل بشكل أسرع، ولكن تشغيلها يطيل الوقت الذي يستغرقه برنامجك للتجميع. هذا هو السبب في وجود ملفي تعريف (profiles) مختلفين: أحدهما للتطوير، عندما تريد إعادة البناء بسرعة وبشكل متكرر، والآخر لبناء البرنامج النهائي الذي ستعطيه للمستخدم والذي لن يتم إعادة بنائه بشكل متكرر وسيعمل بأسرع ما يمكن. إذا كنت تقوم بقياس أداء (benchmarking) وقت تشغيل الكود الخاص بك، فتأكد من تشغيل cargo build --release والقياس باستخدام الملف القابل للتنفيذ في target/release.

الاستفادة من اتفاقيات Cargo

مع المشاريع البسيطة، لا يوفر Cargo الكثير من القيمة مقارنة بمجرد استخدام rustc ولكنه سيثبت جدارته عندما تصبح برامجك أكثر تعقيدًا. بمجرد أن تنمو البرامج لتشمل ملفات متعددة أو تحتاج إلى dependency، يكون من الأسهل بكثير ترك Cargo ينسق عملية البناء.

على الرغم من أن مشروع hello_cargo بسيط، إلا أنه يستخدم الآن الكثير من الأدوات الحقيقية التي ستستخدمها في بقية حياتك المهنية مع Rust. في الواقع، للعمل في أي مشاريع موجودة، يمكنك استخدام الأوامر التالية لسحب الكود باستخدام Git، والانتقال إلى دليل ذلك المشروع، والبناء:

$ git clone example.org/someproject
$ cd someproject
$ cargo build

لمزيد من المعلومات حول Cargo، راجع وثائقه.

ملخص

لقد بدأت بالفعل بداية رائعة في رحلتك مع Rust! في هذا الفصل، تعلمت كيفية:

• تثبيت أحدث إصدار مستقر من Rust باستخدام rustup.
• التحديث إلى إصدار Rust أحدث.
• فتح الوثائق المثبتة محليًا.
• كتابة وتشغيل برنامج “Hello, world!” باستخدام rustc مباشرة.
• إنشاء وتشغيل مشروع جديد باستخدام اتفاقيات Cargo.

هذا وقت رائع لبناء برنامج أكثر جوهرية للتعود على قراءة وكتابة كود Rust. لذا، في الفصل 2، سنبني برنامج لعبة التخمين. إذا كنت تفضل البدء بتعلم كيفية عمل مفاهيم البرمجة الشائعة في Rust، فراجع الفصل 3 ثم عد إلى الفصل 2.

برمجة لعبة التخمين

دعونا نبدأ رحلتنا مع لغة Rust من خلال العمل على مشروع عملي معاً! يقدم لك هذا الفصل بعض مفاهيم Rust الشائعة من خلال توضيح كيفية استخدامها في برنامج حقيقي. ستتعلم عن let و match والدوال (methods) والدوال المرتبطة (associated functions) والصناديق الخارجية (external crates) والمزيد! في الفصول التالية، سنستكشف هذه الأفكار بمزيد من التفصيل. في هذا الفصل، ستتدرب فقط على الأساسيات.

سنقوم بتنفيذ مشكلة برمجية كلاسيكية للمبتدئين: لعبة التخمين. وإليك آلية عملها: سيقوم البرنامج بتوليد رقم صحيح عشوائي بين 1 و 100، ثم يطلب من اللاعب إدخال تخمين. بعد إدخال التخمين، سيوضح البرنامج ما إذا كان التخمين منخفضاً جداً أم مرتفعاً جداً. إذا كان التخمين صحيحاً، فسيقوم البرنامج بطباعة رسالة تهنئة ويخرج من اللعبة.

إعداد مشروع جديد

لإعداد مشروع جديد، انتقل إلى دليل projects الذي أنشأته في الفصل الأول وأنشئ مشروعاً جديداً باستخدام Cargo، كما يلي:

$ cargo new guessing_game
$ cd guessing_game

الأمر الأول، cargo new يأخذ اسم المشروع (guessing_game) كمعامل أول. الأمر الثاني يغير المسار إلى دليل المشروع الجديد.

ألقِ نظرة على ملف Cargo.toml الذي تم إنشاؤه:

اسم الملف: Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"

[dependencies]

كما رأيت في الفصل الأول، يقوم cargo new بإنشاء برنامج “Hello, world!” لك. تحقق من ملف src/main.rs:

اسم الملف: src/main.rs

fn main() {
    println!("Hello, world!");
}

الآن دعونا نقوم بتجميع برنامج “Hello, world!” هذا وتشغيله في نفس الخطوة باستخدام أمر cargo run:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/guessing_game`
Hello, world!

يعد أمر run مفيداً عندما تحتاج إلى تكرار العمل على مشروع بسرعة، كما سنفعل في هذه اللعبة، حيث نختبر كل تكرار بسرعة قبل الانتقال إلى التكرار التالي.

أعد فتح ملف src/main.rs. ستكتب كل الكود في هذا الملف.

معالجة التخمين

الجزء الأول من برنامج لعبة التخمين سيطلب مدخلات من المستخدم، ويعالج تلك المدخلات، ويتحقق من أن المدخلات في الشكل المتوقع. للبدء، سنسمح للاعب بإدخال تخمين. أدخل الكود الموجود في القائمة 2-1 في ملف src/main.rs.

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

يحتوي هذا الكود على الكثير من المعلومات، لذا دعونا نمر عليه سطراً بسطر. للحصول على مدخلات المستخدم ثم طباعة النتيجة كمخرجات، نحتاج إلى جلب مكتبة الإدخال/الإخراج io إلى النطاق (scope). تأتي مكتبة io من المكتبة القياسية، المعروفة باسم std:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

بشكل افتراضي، تمتلك Rust مجموعة من العناصر المحددة في المكتبة القياسية والتي تجلبها إلى نطاق كل برنامج. تسمى هذه المجموعة بـ prelude، ويمكنك رؤية كل شيء فيها في توثيق المكتبة القياسية.

إذا كان النوع الذي تريد استخدامه ليس في الـ prelude، فيجب عليك جلب ذلك النوع إلى النطاق صراحةً باستخدام عبارة use. يوفر لك استخدام مكتبة std::io عدداً من الميزات المفيدة، بما في ذلك القدرة على قبول مدخلات المستخدم.

كما رأيت في الفصل الأول، فإن دالة main هي نقطة الدخول إلى البرنامج:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

تعلن صيغة fn عن دالة جديدة؛ وتشير الأقواس () إلى عدم وجود معاملات؛ ويبدأ القوس المتعرج { جسم الدالة.

كما تعلمت أيضاً في الفصل الأول، فإن println! هو ماكرو (macro) يطبع سلسلة نصية على الشاشة:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

يقوم هذا الكود بطباعة مطالبة توضح ماهية اللعبة وتطلب مدخلات من المستخدم.

تخزين القيم باستخدام المتغيرات

بعد ذلك، سننشئ متغيراً لتخزين مدخلات المستخدم، كما يلي:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

الآن أصبح البرنامج مثيراً للاهتمام! هناك الكثير مما يحدث في هذا السطر الصغير. نستخدم عبارة let لإنشاء المتغير. إليك مثالاً آخر:

let apples = 5;

ينشئ هذا السطر متغيراً جديداً باسم apples ويربطه بالقيمة 5. في Rust، تكون المتغيرات غير قابلة للتغيير (immutable) افتراضياً، مما يعني أنه بمجرد إعطاء المتغير قيمة، فلن تتغير القيمة. سنناقش هذا المفهوم بالتفصيل في قسم “المتغيرات وقابلية التغيير” في الفصل الثالث. لجعل المتغير قابلاً للتغيير، نضيف mut قبل اسم المتغير:

let apples = 5; // غير قابل للتغيير
let mut bananas = 5; // قابل للتغيير

ملاحظة: تبدأ صيغة // تعليقاً يستمر حتى نهاية السطر. تتجاهل Rust كل شيء في التعليقات. سنناقش التعليقات بمزيد من التفصيل في الفصل الثالث.

بالعودة إلى برنامج لعبة التخمين، تعلم الآن أن let mut guess ستقدم متغيراً قابلاً للتغيير باسم guess. تخبر علامة التساوي (=) لغة Rust أننا نريد ربط شيء ما بالمتغير الآن. على يمين علامة التساوي توجد القيمة التي يرتبط بها guess وهي نتيجة استدعاء String::new وهي دالة تعيد نسخة جديدة من String. النوع String هو نوع سلسلة نصية توفره المكتبة القياسية وهو عبارة عن نص بتنسيق UTF-8 وقابل للنمو.

تشير صيغة :: في سطر ::new إلى أن new هي دالة مرتبطة (associated function) بنوع String. الدالة المرتبطة هي دالة يتم تنفيذها على نوع معين، في هذه الحالة String. تنشئ دالة new هذه سلسلة نصية جديدة وفارغة. ستجد دالة new في العديد من الأنواع لأنها اسم شائع لدالة تنشئ قيمة جديدة من نوع ما.

بشكل كامل، قام سطر let mut guess = String::new(); بإنشاء متغير قابل للتغيير مرتبط حالياً بنسخة جديدة وفارغة من String. يا للهول!

استقبال مدخلات المستخدم

تذكر أننا قمنا بتضمين وظائف الإدخال/الإخراج من المكتبة القياسية باستخدام use std::io; في السطر الأول من البرنامج. الآن سنستدعي دالة stdin من وحدة io والتي ستسمح لنا بالتعامل مع مدخلات المستخدم:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

إذا لم نكن قد استوردنا وحدة io باستخدام use std::io; في بداية البرنامج، كان بإمكاننا استدعاء الدالة بكتابتها كـ std::io::stdin. تعيد دالة stdin نسخة من std::io::Stdin وهو نوع يمثل مقبضاً (handle) للإدخال القياسي لمحطتك الطرفية (terminal).

بعد ذلك، يستدعي السطر .read_line(&mut guess) دالة read_line على مقبض الإدخال القياسي للحصول على مدخلات من المستخدم. نقوم أيضاً بتمرير &mut guess كمعامل لـ read_line لإخبارها بالسلسلة النصية التي يجب تخزين مدخلات المستخدم فيها. الوظيفة الكاملة لـ read_line هي أخذ كل ما يكتبه المستخدم في الإدخال القياسي وإلحاقه بسلسلة نصية (دون الكتابة فوق محتوياتها)، لذا نقوم بتمرير تلك السلسلة كمعامل. يجب أن يكون معامل السلسلة النصية قابلاً للتغيير حتى تتمكن الدالة من تغيير محتوى السلسلة.

تشير علامة & إلى أن هذا المعامل هو مرجع (reference)، مما يوفر لك طريقة للسماح لأجزاء متعددة من الكود بالوصول إلى قطعة واحدة من البيانات دون الحاجة إلى نسخ تلك البيانات في الذاكرة عدة مرات. المراجع ميزة معقدة، وإحدى المزايا الرئيسية لـ Rust هي مدى أمان وسهولة استخدام المراجع. لا تحتاج إلى معرفة الكثير من تلك التفاصيل لإنهاء هذا البرنامج. في الوقت الحالي، كل ما تحتاج إلى معرفته هو أن المراجع، مثل المتغيرات، غير قابلة للتغيير افتراضياً. ومن ثم، تحتاج إلى كتابة &mut guess بدلاً من &guess لجعلها قابلة للتغيير. (سيشرح الفصل الرابع المراجع بشكل أكثر تعمقاً).

التعامل مع الفشل المحتمل باستخدام Result

ما زلنا نعمل على هذا السطر من الكود. نحن نناقش الآن السطر الثالث من النص، ولكن لاحظ أنه لا يزال جزءاً من سطر منطقي واحد من الكود. الجزء التالي هو هذه الدالة:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

كان بإمكاننا كتابة هذا الكود كـ:

io::stdin().read_line(&mut guess).expect("فشل في قراءة السطر");

ومع ذلك، يصعب قراءة سطر واحد طويل، لذا فمن الأفضل تقسيمه. غالباً ما يكون من الحكمة إدخال سطر جديد ومسافات بيضاء أخرى للمساعدة في تقسيم السطور الطويلة عند استدعاء دالة باستخدام صيغة .method_name(). الآن دعونا نناقش ما يفعله هذا السطر.

كما ذكرنا سابقاً، تضع read_line كل ما يدخله المستخدم في السلسلة النصية التي نمررها إليها، ولكنها تعيد أيضاً قيمة من نوع Result. النوع Result هو تعداد (enumeration)، وغالباً ما يسمى enum، وهو نوع يمكن أن يكون في حالة واحدة من عدة حالات ممكنة. نسمي كل حالة ممكنة بـ variant.

سيغطي الفصل السادس التعدادات بمزيد من التفصيل. الغرض من أنواع Result هذه هو تشفير معلومات معالجة الأخطاء.

حالات Result هي Ok و Err. تشير حالة Ok إلى أن العملية كانت ناجحة، وتحتوي على القيمة التي تم إنشاؤها بنجاح. تعني حالة Err أن العملية فشلت، وتحتوي على معلومات حول كيفية أو سبب فشل العملية.

القيم من نوع Result مثل القيم من أي نوع، لها دوال محددة عليها. نسخة Result لها دالة expect يمكنك استدعاؤها. إذا كانت نسخة Result هذه هي قيمة Err فستتسبب expect في تعطل البرنامج وعرض الرسالة التي مررتها كمعامل لـ expect. إذا أعادت دالة read_line قيمة Err فمن المحتمل أن يكون ذلك نتيجة لخطأ قادم من نظام التشغيل الأساسي. إذا كانت نسخة Result هذه هي قيمة Ok فستأخذ expect القيمة المرتجعة التي يحملها Ok وتعيد تلك القيمة إليك لتتمكن من استخدامها. في هذه الحالة، تلك القيمة هي عدد البايتات في مدخلات المستخدم.

إذا لم تستدعِ expect فسيتم تجميع البرنامج ولكنك ستحصل على تحذير:

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
warning: unused `Result` that must be used
  --> src/main.rs:10:5
   |
10 |     io::stdin().read_line(&mut guess);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this `Result` may be an `Err` variant, which should be handled
   = note: `#[warn(unused_must_use)]` on by default
help: use `let _ = ...` to ignore the resulting value
   |
10 |     let _ = io::stdin().read_line(&mut guess);
   |     +++++++

warning: `guessing_game` (bin "guessing_game") generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.59s

تحذر Rust من أنك لم تستخدم قيمة Result المرتجعة من read_line مما يشير إلى أن البرنامج لم يعالج خطأً محتملاً.

الطريقة الصحيحة لقمع التحذير هي كتابة معالجة الأخطاء فعلياً، ولكن في حالتنا نريد فقط تعطل البرنامج عند حدوث مشكلة، لذا يمكننا استخدام expect. ستتعلم عن التعافي من الأخطاء في الفصل التاسع.

طباعة القيم باستخدام نائبات println!

بصرف النظر عن القوس المتعرج الختامي، هناك سطر واحد فقط متبقٍ في الكود الذي أضفناه حتى الآن:

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

يطبع هذا السطر السلسلة النصية التي تحتوي الآن على مدخلات المستخدم. مجموعة الأقواس المتعرجة {} هي نائبة (placeholder): فكر في {} كأطراف كماشة صغيرة تثبت القيمة في مكانها. عند طباعة قيمة متغير، يمكن أن يوضع اسم المتغير داخل الأقواس المتعرجة. عند طباعة نتيجة تعبير، ضع أقواس متعرجة فارغة في سلسلة التنسيق، ثم اتبع سلسلة التنسيق بقائمة من التعبيرات مفصولة بفاصلة لطباعتها في كل نائبة من الأقواس المتعرجة الفارغة بالترتيب. طباعة متغير ونتيجة تعبير في استدعاء واحد لـ println! ستبدو كما يلي:

#![allow(unused)]
fn main() {
let x = 5;
let y = 10;

println!("x = {x} and y + 2 = {}", y + 2);
}

سيطبع هذا الكود x = 5 and y + 2 = 12.

اختبار الجزء الأول

دعونا نختبر الجزء الأول من لعبة التخمين. قم بتشغيله باستخدام cargo run:

{{#include ../listings/ch02-guessing-game-tutorial/listing-02-01/output.txt}}

في هذه المرحلة، الجزء الأول من اللعبة قد انتهى: نحن نحصل على مدخلات من لوحة المفاتيح ثم نطبعها.

توليد رقم سري

بعد ذلك، نحتاج إلى توليد رقم سري سيحاول المستخدم تخمينه. يجب أن يكون الرقم السري مختلفاً في كل مرة حتى تكون اللعبة ممتعة لإعادة اللعب؛ سنستخدم رقماً عشوائياً بين 1 و 100 حتى لا تكون اللعبة صعبة للغاية. لا تتضمن Rust وظائف أرقام عشوائية في مكتبتها القياسية بعد. ومع ذلك، يوفر فريق Rust صندوق rand (rand crate) بهذه الوظيفة.

استخدام صندوق للحصول على المزيد من الوظائف

تذكر أن الصندوق (crate) هو مجموعة من ملفات كود Rust. المشروع الذي نقوم ببنائه هو صندوق ثنائي (binary crate)، وهو ملف قابل للتنفيذ. صندوق rand هو صندوق مكتبة (library crate)، والذي يحتوي على كود مخصص لاستخدامه في برامج أخرى ولا يمكن تشغيله بمفرده.

استخدام Cargo للصناديق الخارجية هو المكان الذي يتألق فيه Cargo حقاً. قبل أن نتمكن من كتابة كود يستخدم rand نحتاج إلى تعديل ملف Cargo.toml لتضمين صندوق rand كاعتمادية (dependency). افتح ذلك الملف الآن وأضف السطر التالي في الأسفل، تحت عنوان القسم [dependencies] الذي أنشأه Cargo لك. تأكد من تحديد rand تماماً كما فعلنا هنا، مع رقم الإصدار هذا، وإلا فقد لا تعمل أمثلة الكود في هذا البرنامج التعليمي (في وقت كتابة هذا، كان rand بالإصدار 0.8.5):

اسم الملف: Cargo.toml

[dependencies]
rand = "0.8.5"

في ملف Cargo.toml كل ما يأتي بعد العنوان هو جزء من ذلك القسم الذي يستمر حتى يبدأ قسم آخر. في [dependencies] تخبر Cargo بالصناديق الخارجية التي يعتمد عليها مشروعك وأي إصدارات من تلك الصناديق تحتاجها. في هذه الحالة، نحدد صندوق rand مع محدد الإصدار الدلالي (Semantic Versioning) 0.8.5. يفهم Cargo الإصدار الدلالي (يسمى أحياناً SemVer)، وهو معيار لكتابة أرقام الإصدارات. الرقم 0.8.5 هو في الواقع اختصار لـ ^0.8.5 مما يعني أي إصدار يتوافق مع الإصدار 0.8.5 على الأقل ولكن أقل من 0.9.0.

يعتبر Cargo أن هذه الإصدارات لها واجهات برمجية (APIs) متوافقة مع الإصدار 0.8.5 ويضمن هذا التحديد أنك ستحصل على أحدث إصدار تصحيحي (patch release) سيظل يجمع مع الكود في هذا الفصل. لا يمكن ضمان توافق أي إصدار 0.9.0 أو أعلى مع الواجهة البرمجية التي تستخدمها الأمثلة التالية.

الآن، دون تغيير أي كود، دعونا نبني المشروع، كما هو موضح في القائمة 2-2.

$ cargo build
    Updating crates.io index
  Downloaded rand v0.8.5
  Downloaded libc v0.2.143
  Downloaded rand_chacha v0.3.1
  Downloaded rand_core v0.6.4
   Compiling libc v0.2.143
   Compiling rand_core v0.6.4
   Compiling rand_chacha v0.3.1
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53s

القائمة 2-2: المخرجات بعد إضافة صندوق rand كاعتمادية وتشغيل cargo build

قد ترى أرقام إصدارات مختلفة (ولكنها ستكون جميعاً متوافقة مع الكود، بفضل SemVer!) وخطوطاً مختلفة (اعتماداً على نظام التشغيل) وقد تكون السطور بترتيب مختلف.

عندما نقوم بتضمين اعتمادية خارجية، يجلب Cargo أحدث الإصدارات من كل ما تحتاجه تلك الاعتمادية من Crates.io وهو المكان الذي ينشر فيه الأشخاص في نظام Rust البيئي مشاريع Rust مفتوحة المصدر الخاصة بهم ليستخدمها الآخرون.

بعد تحديث الفهرس، يتحقق Cargo من قسم [dependencies] وينزل أي صناديق مدرجة لم يتم تنزيلها بعد. في هذه الحالة، على الرغم من أننا أدرجنا rand فقط كاعتمادية، فقد جلب Cargo أيضاً صناديق أخرى يعتمد عليها rand ليعمل. بعد تنزيل الصناديق، تقوم Rust بتجميعها ثم تجميع المشروع بالاعتماديات المتاحة.

إذا قمت بتشغيل cargo build مرة أخرى فوراً دون إجراء أي تغييرات، فلن تحصل على أي مخرجات سوى سطر Finished. يعرف Cargo أنه قد قام بالفعل بتنزيل وتجميع الاعتماديات، ولم تقم بتغيير أي شيء عنها في ملف Cargo.toml. يعرف Cargo أيضاً أنك لم تغير أي شيء في الكود الخاص بك، لذا فهو لا يعيد تجميعه أيضاً. مع عدم وجود شيء للقيام به، فإنه يخرج ببساطة.

إذا فتحت ملف src/main.rs وأجريت تغييراً تافهاً، ثم حفظته، وقمت بالبناء مرة أخرى، فسترى مخرجات سطرين فقط:

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 2.53s

توضح هذه السطور أن Cargo يقوم فقط بتحديث البناء بتغييرك الصغير في ملف src/main.rs. لم تتغير اعتمادياتك، لذا يعرف Cargo أنه يمكنه إعادة استخدام ما قام بتنزيله وتجميعه بالفعل.

ضمان عمليات بناء قابلة للتكرار باستخدام ملف Cargo.lock

يحتوي Cargo على آلية تضمن إمكانية إعادة بناء نفس الملف الثنائي في كل مرة تقوم فيها أنت أو أي شخص آخر ببناء الكود الخاص بك: سيستخدم Cargo فقط إصدارات الاعتماديات التي حددتها حتى تشير إلى خلاف ذلك. على سبيل المثال، لنفترض أن الأسبوع القادم سيصدر الإصدار 0.8.6 من صندوق rand ويحتوي هذا الإصدار على إصلاح لخلل مهم، ولكنه يحتوي أيضاً على تراجع (regression) سيؤدي إلى كسر الكود الخاص بك. للتعامل مع هذا، تنشئ Rust ملف Cargo.lock في المرة الأولى التي تقوم فيها بتشغيل cargo build لذا لدينا الآن هذا الملف في دليل guessing_game.

عندما تبني مشروعاً لأول مرة، يكتشف Cargo جميع إصدارات الاعتماديات التي تناسب المعايير ثم يكتبها في ملف Cargo.lock. عندما تبني مشروعك في المستقبل، سيرى Cargo وجود ملف Cargo.lock وسيستخدم الإصدارات المحددة هناك بدلاً من القيام بكل العمل لمعرفة الإصدارات مرة أخرى. يتيح لك هذا الحصول على بناء قابل للتكرار تلقائياً. بمعنى آخر، سيظل مشروعك يستخدم الإصدار 0.8.5 حتى تقوم بالترقية صراحةً، بفضل ملف Cargo.lock. نظرًا لأن ملف Cargo.lock مهم لاستقرار عمليات البناء، فغالباً ما يتم تضمينه في نظام التحكم في الإصدارات (مثل Git) مع بقية الكود في مشروعك.

تحديث صندوق للحصول على إصدار جديد

عندما تريد تحديث صندوق، يوفر Cargo أمر update والذي سيتجاهل ملف Cargo.lock ويكتشف جميع أحدث الإصدارات التي تناسب مواصفاتك في Cargo.toml. سيقوم Cargo بعد ذلك بكتابة تلك الإصدارات في ملف Cargo.lock. وبخلاف ذلك، سيبحث Cargo افتراضياً فقط عن الإصدارات الأكبر من 0.8.5 وأقل من 0.9.0. إذا أصدر صندوق rand إصدارين جديدين 0.8.6 و 0.9.0 فسترى ما يلي إذا قمت بتشغيل cargo update:

$ cargo update
    Updating crates.io index
    Updating rand v0.8.5 -> v0.8.6

يتجاهل Cargo الإصدار 0.9.0. في هذه المرحلة، ستلاحظ أيضاً تغييراً في ملف Cargo.lock يشير إلى أن إصدار صندوق rand الذي تستخدمه الآن هو 0.8.6. لاستخدام الإصدار 0.9.0 من rand أو أي إصدار في سلسلة 0.9.x يجب عليك تحديث ملف Cargo.toml ليبدو كما يلي بدلاً من ذلك (أو الإصدار المناسب إذا كنت تستخدم rand 0.8):

[dependencies]
rand = "0.999.0"

في المرة القادمة التي تقوم فيها بتشغيل cargo build سيقوم Cargo بتحديث سجل الصناديق المتاحة ويعيد تقييم متطلبات rand الخاصة بك وفقاً للإصدار الجديد الذي حددته.

هناك الكثير مما يمكن قوله عن Cargo و نظامه البيئي والذي سنناقشه في الفصل 14، ولكن في الوقت الحالي، هذا كل ما تحتاج إلى معرفته. يجعل Cargo من السهل جداً إعادة استخدام المكتبات، لذا يستطيع مطورو Rust كتابة مشاريع أصغر يتم تجميعها من عدد من الحزم.

توليد رقم عشوائي

دعونا نبدأ في استخدام rand لتوليد رقم للتخمين. الخطوة التالية هي تحديث ملف src/main.rs كما هو موضح في القائمة 2-3.

use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

أولاً، نضيف السطر use rand::Rng;. تحدد سمة (trait) Rng الدوال التي تنفذها مولدات الأرقام العشوائية، ويجب أن تكون هذه السمة في النطاق لنتمكن من استخدام تلك الدوال. سيغطي الفصل العاشر السمات بالتفصيل.

بعد ذلك، نضيف سطرين في المنتصف. في السطر الأول، نستدعي دالة rand::thread_rng التي تعطينا مولد الأرقام العشوائية المحدد الذي سنستخدمه: وهو مولد محلي لخيط التنفيذ الحالي (thread) ويتم تزويده ببذرة (seed) من قبل نظام التشغيل. ثم نستدعي دالة gen_range على مولد الأرقام العشوائية. تم تحديد هذه الدالة بواسطة سمة Rng التي جلبناها إلى النطاق باستخدام عبارة use rand::Rng;. تأخذ دالة gen_range تعبيراً للنطاق كمعامل وتولد رقماً عشوائياً في ذلك النطاق. نوع تعبير النطاق الذي نستخدمه هنا يأخذ الشكل start..=end وهو شامل للحدود الدنيا والعليا، لذا نحتاج إلى تحديد 1..=100 لطلب رقم بين 1 و 100.

ملاحظة: لن تعرف ببساطة أي السمات يجب استخدامها وأي الدوال يجب استدعاؤها من صندوق ما، لذا فإن كل صندوق له توثيق مع تعليمات لاستخدامه. ميزة أخرى رائعة في Cargo هي أن تشغيل أمر cargo doc --open سيبني التوثيق المقدم من جميع اعتمادياتك محلياً ويفتحه في متصفحك. إذا كنت مهتماً بوظائف أخرى في صندوق rand على سبيل المثال، فقم بتشغيل cargo doc --open وانقر على rand في الشريط الجانبي على اليسار.

السطر الجديد الثاني يطبع الرقم السري. هذا مفيد أثناء تطوير البرنامج لنتمكن من اختباره، لكننا سنحذفه من النسخة النهائية. لن تكون اللعبة ممتعة إذا قام البرنامج بطباعة الإجابة بمجرد بدئه!

حاول تشغيل البرنامج عدة مرات:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5

يجب أن تحصل على أرقام عشوائية مختلفة، ويجب أن تكون جميعها أرقاماً بين 1 و 100. عمل رائع!

مقارنة التخمين بالرقم السري

الآن بعد أن أصبح لدينا مدخلات المستخدم ورقم عشوائي، يمكننا مقارنتهما. تظهر هذه الخطوة في القائمة 2-4. لاحظ أن هذا الكود لن يتم تجميعه بعد، كما سنوضح.

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    // --snip--
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

أولاً، نضيف عبارة use أخرى، لجلب نوع يسمى std::cmp::Ordering إلى النطاق من المكتبة القياسية. النوع Ordering هو تعداد آخر وله الحالات Less و Greater و Equal. هذه هي النتائج الثلاث الممكنة عند مقارنة قيمتين.

ثم نضيف خمسة أسطر جديدة في الأسفل تستخدم نوع Ordering. تقارن دالة cmp قيمتين ويمكن استدعاؤها على أي شيء يمكن مقارنته. تأخذ مرجعاً لأي شيء تريد مقارنته به: هنا، تقارن guess بـ secret_number. ثم تعيد حالة من تعداد Ordering الذي جلبناه إلى النطاق باستخدام عبارة use. نستخدم تعبير match لتقرير ما يجب فعله بعد ذلك بناءً على الحالة التي تم إرجاعها من استدعاء cmp بالقيم الموجودة في guess و secret_number.

يتكون تعبير match من أذرع (arms). يتكون الذراع من نمط (pattern) للمطابقة معه، والكود الذي يجب تشغيله إذا كانت القيمة المعطاة لـ match تناسب نمط ذلك الذراع. تأخذ Rust القيمة المعطاة لـ match وتبحث في نمط كل ذراع بالترتيب. الأنماط وبنية match هي ميزات قوية في Rust: فهي تتيح لك التعبير عن مجموعة متنوعة من المواقف التي قد يواجهها الكود الخاص بك، وتتأكد من معالجتها جميعاً. سيتم تغطية هذه الميزات بالتفصيل في الفصل السادس والفصل التاسع عشر على التوالي.

دعونا نمر بمثال مع تعبير match الذي نستخدمه هنا. لنفترض أن المستخدم قد خمن 50 والرقم السري الذي تم توليده عشوائياً هذه المرة هو 38.

عندما يقارن الكود 50 بـ 38، ستعيد دالة cmp القيمة Ordering::Greater لأن 50 أكبر من 38. يحصل تعبير match على القيمة Ordering::Greater ويبدأ في التحقق من نمط كل ذراع. ينظر إلى نمط الذراع الأول Ordering::Less ويرى أن القيمة Ordering::Greater لا تطابق Ordering::Less لذا يتجاهل الكود الموجود في ذلك الذراع وينتقل إلى الذراع التالي. نمط الذراع التالي هو Ordering::Greater والذي يطابق فعلاً Ordering::Greater! سيتم تنفيذ الكود المرتبط في ذلك الذراع وطباعة Too big! على الشاشة. ينتهي تعبير match بعد أول مطابقة ناجحة، لذا لن ينظر إلى الذراع الأخير في هذا السيناريو.

ومع ذلك، لن يتم تجميع الكود الموجود في القائمة 2-4 بعد. دعونا نجرب ذلك:

$ cargo build
   Compiling libc v0.2.86
   Compiling getrandom v0.2.2
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.10
   Compiling rand_core v0.6.2
   Compiling rand_chacha v0.3.0
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
  --> src/main.rs:23:21
   |
23 |     match guess.cmp(&secret_number) {
   |                 --- ^^^^^^^^^^^^^^ expected `&String`, found `&{integer}`
   |                 |
   |                 arguments to this method are incorrect
   |
   = note: expected reference `&String`
              found reference `&{integer}`
note: method defined here
  --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/cmp.rs:979:8

For more information about this error, try `rustc --explain E0308`.
error: could not compile `guessing_game` (bin "guessing_game") due to 1 previous error

جوهر الخطأ ينص على وجود أنواع غير متطابقة (mismatched types). تمتلك Rust نظام أنواع قوي وثابت. ومع ذلك، لديها أيضاً استنتاج الأنواع (type inference). عندما كتبنا let mut guess = String::new() تمكنت Rust من استنتاج أن guess يجب أن تكون من نوع String ولم تجبرنا على كتابة النوع. من ناحية أخرى، فإن secret_number هو نوع رقمي. يمكن لعدد قليل من أنواع الأرقام في Rust أن يكون لها قيمة بين 1 و 100: i32 وهو رقم 32 بت؛ u32 وهو رقم 32 بت غير موقع (unsigned)؛ i64 وهو رقم 64 بت؛ بالإضافة إلى أنواع أخرى. ما لم يتم تحديد خلاف ذلك، تفترض Rust افتراضياً النوع i32 وهو نوع secret_number ما لم تضف معلومات النوع في مكان آخر من شأنها أن تجعل Rust تستنتج نوعاً رقمياً مختلفاً. سبب الخطأ هو أن Rust لا يمكنها مقارنة سلسلة نصية ونوع رقمي.

في النهاية، نريد تحويل String الذي يقرأه البرنامج كمدخلات إلى نوع رقمي حتى نتمكن من مقارنته عددياً بالرقم السري. نقوم بذلك عن طريق إضافة هذا السطر إلى جسم دالة main:

اسم الملف: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    // --snip--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

السطر هو:

let guess: u32 = guess.trim().parse().expect("يرجى كتابة رقم!");

ننشئ متغيراً باسم guess. ولكن انتظر، أليس لدى البرنامج بالفعل متغير باسم guess؟ بلى، ولكن لحسن الحظ تسمح لنا Rust بـ “تظليل” (shadow) القيمة السابقة لـ guess بقيمة جديدة. يتيح لنا التظليل (Shadowing) إعادة استخدام اسم المتغير guess بدلاً من إجبارنا على إنشاء متغيرين فريدين، مثل guess_str و guess على سبيل المثال. سنغطي هذا بمزيد من التفصيل في الفصل الثالث ولكن في الوقت الحالي، اعلم أن هذه الميزة غالباً ما تستخدم عندما تريد تحويل قيمة من نوع إلى نوع آخر.

نربط هذا المتغير الجديد بالتعبير guess.trim().parse(). تشير guess في التعبير إلى متغير guess الأصلي الذي يحتوي على المدخلات كسلسلة نصية. ستقوم دالة trim على نسخة String بإزالة أي مسافات بيضاء في البداية والنهاية، وهو ما يجب علينا فعله قبل أن نتمكن من تحويل السلسلة النصية إلى u32 والذي يمكن أن يحتوي فقط على بيانات رقمية. يجب على المستخدم الضغط على مفتاح enter لإرضاء read_line وإدخال تخمينه، مما يضيف حرف سطر جديد إلى السلسلة النصية. على سبيل المثال، إذا كتب المستخدم 5 وضغط على enter فستبدو guess كما يلي: 5\n. يمثل \n “سطر جديد”. (في ويندوز، يؤدي الضغط على enter إلى رجوع العربة وسطر جديد \r\n). تزيل دالة trim حرف \n أو \r\n مما ينتج عنه 5 فقط.

تقوم دالة parse على السلاسل النصية بتحويل السلسلة النصية إلى نوع آخر. هنا، نستخدمها للتحويل من سلسلة نصية إلى رقم. نحتاج إلى إخبار Rust بنوع الرقم الدقيق الذي نريده باستخدام let guess: u32. تخبر النقطتان الرأسيتان (:) بعد guess لغة Rust أننا سنقوم بتوضيح نوع المتغير. تمتلك Rust بعض أنواع الأرقام المدمجة؛ u32 الموضح هنا هو عدد صحيح غير موقع بـ 32 بت. إنه خيار افتراضي جيد لرقم موجب صغير. ستتعلم عن أنواع الأرقام الأخرى في الفصل الثالث.

بالإضافة إلى ذلك، فإن توضيح u32 في هذا البرنامج التجريبي والمقارنة مع secret_number يعني أن Rust ستستنتج أن secret_number يجب أن يكون من نوع u32 أيضاً. لذا، ستكون المقارنة الآن بين قيمتين من نفس النوع!

ستعمل دالة parse فقط على الأحرف التي يمكن تحويلها منطقياً إلى أرقام، وبالتالي يمكن أن تتسبب بسهولة في حدوث أخطاء. إذا كانت السلسلة النصية تحتوي على A👍% على سبيل المثال، فلن تكون هناك طريقة لتحويل ذلك إلى رقم. ولأنها قد تفشل، تعيد دالة parse نوع Result تماماً كما تفعل دالة read_line (التي نوقشت سابقاً في “التعامل مع الفشل المحتمل باستخدام Result”). سنعامل هذا الـ Result بنفس الطريقة باستخدام دالة expect مرة أخرى. إذا أعادت parse حالة Err من نوع Result لأنها لم تستطع إنشاء رقم من السلسلة النصية، فسيؤدي استدعاء expect إلى تعطل اللعبة وطباعة الرسالة التي نعطيها إياها. إذا تمكنت parse من تحويل السلسلة النصية إلى رقم بنجاح، فستعيد حالة Ok من نوع Result وستعيد expect الرقم الذي نريده من قيمة Ok.

دعونا نشغل البرنامج الآن:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.26s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
  76
You guessed: 76
Too big!

رائع! على الرغم من إضافة مسافات قبل التخمين، إلا أن البرنامج لا يزال يدرك أن المستخدم خمن 76. قم بتشغيل البرنامج عدة مرات للتحقق من السلوك المختلف مع أنواع مختلفة من المدخلات: خمن الرقم بشكل صحيح، خمن رقماً مرتفعاً جداً، وخمن رقماً منخفضاً جداً.

لدينا معظم اللعبة تعمل الآن، ولكن يمكن للمستخدم القيام بتخمين واحد فقط. دعونا نغير ذلك بإضافة حلقة تكرار!

السماح بتخمينات متعددة باستخدام الحلقات

تنشئ الكلمة المفتاحية loop حلقة تكرار لانهائية. سنضيف حلقة لمنح المستخدمين المزيد من الفرص لتخمين الرقم:

اسم الملف: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    // --snip--

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        // --snip--


        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => println!("You win!"),
        }
    }
}

كما ترى، قمنا بنقل كل شيء من مطالبة إدخال التخمين فصاعداً إلى داخل حلقة تكرار. تأكد من إزاحة الأسطر داخل الحلقة بمقدار أربع مسافات إضافية لكل منها وقم بتشغيل البرنامج مرة أخرى. سيطلب البرنامج الآن تخميناً آخر إلى الأبد، مما يسبب مشكلة جديدة في الواقع. يبدو أن المستخدم لا يستطيع الخروج!

يمكن للمستخدم دائماً مقاطعة البرنامج باستخدام اختصار لوحة المفاتيح ctrl-C. ولكن هناك طريقة أخرى للهروب من هذا الوحش النهم، كما ذكرنا في مناقشة parse في “مقارنة التخمين بالرقم السري”: إذا أدخل المستخدم إجابة ليست رقماً، فسيتحطم البرنامج. يمكننا الاستفادة من ذلك للسماح للمستخدم بالخروج، كما هو موضح هنا:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60
Too big!
Please input your guess.
59
You guessed: 59
You win!
Please input your guess.
quit

thread 'main' panicked at src/main.rs:28:47:
يرجى كتابة رقم!: ParseIntError { kind: InvalidDigit }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

كتابة quit ستؤدي إلى الخروج من اللعبة، ولكن كما ستلاحظ، فإن إدخال أي مدخلات أخرى ليست رقماً سيفعل الشيء نفسه. هذا ليس مثالياً على أقل تقدير؛ نريد أن تتوقف اللعبة أيضاً عند تخمين الرقم الصحيح.

الخروج بعد التخمين الصحيح

دعونا نبرمج اللعبة لتخرج عندما يفوز المستخدم عن طريق إضافة عبارة break:

اسم الملف: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

إضافة سطر break بعد You win! تجعل البرنامج يخرج من الحلقة عندما يخمن المستخدم الرقم السري بشكل صحيح. الخروج من الحلقة يعني أيضاً الخروج من البرنامج، لأن الحلقة هي الجزء الأخير من دالة main.

معالجة المدخلات غير الصالحة

لمزيد من تحسين سلوك اللعبة، بدلاً من تحطيم البرنامج عندما يدخل المستخدم شيئاً ليس رقماً، دعونا نجعل اللعبة تتجاهل المدخلات غير الرقمية حتى يتمكن المستخدم من الاستمرار في التخمين. يمكننا القيام بذلك عن طريق تغيير السطر الذي يتم فيه تحويل guess من String إلى u32 كما هو موضح في القائمة 2-5.

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        // --snip--

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

ننتقل من استدعاء expect إلى تعبير match للانتقال من التحطم عند حدوث خطأ إلى معالجة الخطأ. تذكر أن parse تعيد نوع Result و Result هو تعداد له الحالات Ok و Err. نحن نستخدم تعبير match هنا، كما فعلنا مع نتيجة Ordering لدالة cmp.

إذا تمكنت parse من تحويل السلسلة النصية إلى رقم بنجاح، فستعيد قيمة Ok تحتوي على الرقم الناتج. ستطابق قيمة Ok تلك نمط الذراع الأول، وسيعيد تعبير match ببساطة قيمة num التي أنتجتها parse ووضعتها داخل قيمة Ok. سينتهي هذا الرقم تماماً حيث نريده في متغير guess الجديد الذي ننشئه.

إذا لم تتمكن parse من تحويل السلسلة النصية إلى رقم، فستعيد قيمة Err تحتوي على مزيد من المعلومات حول الخطأ. لا تطابق قيمة Err نمط Ok(num) في ذراع match الأول، ولكنها تطابق نمط Err(_) في الذراع الثاني. الشرطة السفلية _ هي قيمة شاملة (catch-all)؛ في هذا المثال، نقول إننا نريد مطابقة جميع قيم Err بغض النظر عن المعلومات الموجودة بداخلها. لذا، سيقوم البرنامج بتنفيذ كود الذراع الثاني continue والذي يخبر البرنامج بالانتقال إلى التكرار التالي من الحلقة loop وطلب تخمين آخر. وبذلك، يتجاهل البرنامج فعلياً جميع الأخطاء التي قد تواجهها parse!

الآن يجب أن يعمل كل شيء في البرنامج كما هو متوقع. دعونا نجربه:

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 61
Please input your guess.
10
You guessed: 10
Too small!
Please input your guess.
99
You guessed: 99
Too big!
Please input your guess.
foo
Please input your guess.
61
You guessed: 61
You win!

رائع! مع تعديل نهائي صغير واحد، سننهي لعبة التخمين. تذكر أن البرنامج لا يزال يطبع الرقم السري. كان ذلك مفيداً للاختبار، لكنه يفسد اللعبة. دعونا نحذف سطر println! الذي يطبع الرقم السري. تظهر القائمة 2-6 الكود النهائي.

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

في هذه المرحلة، تكون قد نجحت في بناء لعبة التخمين. تهانينا!

ملخص

كان هذا المشروع طريقة عملية لتعريفك بالعديد من مفاهيم Rust الجديدة: let و match والدوال واستخدام الصناديق الخارجية والمزيد. في الفصول القليلة القادمة، ستتعلم عن هذه المفاهيم بمزيد من التفصيل. يغطي الفصل الثالث المفاهيم التي تمتلكها معظم لغات البرمجة، مثل المتغيرات وأنواع البيانات والدوال، ويوضح كيفية استخدامها في Rust. يستكشف الفصل الرابع الملكية (ownership)، وهي ميزة تجعل Rust مختلفة عن اللغات الأخرى. يناقش الفصل الخامس الهياكل (structs) وصيغة الدوال، ويشرح الفصل السادس كيفية عمل التعدادات (enums).

مفاهيم البرمجة الشائعة (Common Programming Concepts)

يغطي هذا الفصل المفاهيم التي تظهر في كل لغة برمجة تقريبًا وكيف تعمل في Rust. تشترك العديد من لغات البرمجة في الكثير من الأمور الأساسية. لا يوجد أي من المفاهيم المقدمة في هذا الفصل فريد من نوعه لـ Rust، ولكننا سنناقشها في سياق Rust ونشرح الاتفاقيات (conventions) حول استخدامها.

على وجه التحديد، ستتعلم عن المتغيرات (variables)، الأنواع الأساسية (basic types)، الدوال (functions)، التعليقات (comments)، والتحكم في التدفق (control flow). ستكون هذه الأساسيات موجودة في كل برنامج Rust، وتعلمها مبكرًا سيعطيك أساسًا قويًا للانطلاق منه.

الكلمات المفتاحية (Keywords)

تحتوي لغة Rust على مجموعة من الكلمات المفتاحية (keywords) المحجوزة للاستخدام من قبل اللغة فقط، تمامًا كما هو الحال في اللغات الأخرى. تذكر أنه لا يمكنك استخدام هذه الكلمات كأسماء لـ variables أو functions. لمعظم keywords معانٍ خاصة، وستستخدمها للقيام بمهام مختلفة في برامج Rust الخاصة بك؛ القليل منها ليس له وظيفة حالية مرتبطة به ولكنه محجوز لوظائف قد تضاف إلى Rust في المستقبل. يمكنك العثور على قائمة keywords في الملحق أ.

المتغيرات والقابلية للتغيير (Variables and Mutability)

المتغيرات والقابلية للتغير (Variables and Mutability)

كما ذُكر في قسم “تخزين القيم باستخدام المتغيرات”، تكون المتغيرات (Variables) غير قابلة للتغير (Immutable) بشكل افتراضي. هذه واحدة من العديد من التوجيهات التي تقدمها لك لغة Rust لكتابة الكود (Code) الخاص بك بطريقة تستفيد من الأمان والتزامن (Concurrency) السهل الذي توفره Rust. ومع ذلك، لا يزال لديك الخيار لجعل Variables الخاصة بك قابلة للتغير (Mutable). دعنا نستكشف كيف ولماذا تشجعك Rust على تفضيل عدم القابلية للتغير (Immutability) ولماذا قد ترغب أحياناً في إلغاء هذا الاختيار.

عندما يكون Variable غير قابل للتغير، فبمجرد ربط قيمة باسم ما، لا يمكنك تغيير تلك القيمة. لتوضيح ذلك، قم بإنشاء مشروع جديد يسمى variables في دليل المشاريع الخاص بك باستخدام الأمر cargo new variables.

بعد ذلك، في دليل variables الجديد، افتح ملف src/main.rs واستبدل الكود الموجود فيه بالكود التالي، والذي لن يتم تحويله برمجياً (Compile) بعد:

اسم الملف: src/main.rs

fn main() {
    let x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

احفظ البرنامج وشغله باستخدام cargo run. يجب أن تتلقى رسالة خطأ تتعلق بخطأ في Immutability، كما هو موضح في هذا المخرج:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0384]: cannot assign twice to immutable variable `x`
 --> src/main.rs:4:5
  |
2 |     let x = 5;
  |         - first assignment to `x`
3 |     println!("The value of x is: {x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable
  |
help: consider making this binding mutable
  |
2 |     let mut x = 5;
  |         +++

For more information about this error, try `rustc --explain E0384`.
error: could not compile `variables` (bin "variables") due to 1 previous error

يوضح هذا المثال كيف يساعدك المترجم (Compiler) في العثور على الأخطاء في برامجك. قد تكون أخطاء Compiler محبطة، لكنها في الحقيقة تعني فقط أن برنامجك لا يفعل ما تريده بأمان بعد؛ وهي لا تعني أنك لست مبرمجاً جيداً! حتى مبرمجي Rust المتمرسين لا يزالون يتلقون أخطاء Compiler.

لقد تلقيت رسالة الخطأ cannot assign twice to immutable variable `x` لأنك حاولت تعيين قيمة ثانية لـ Variable x غير القابل للتغير.

من المهم أن نحصل على أخطاء في وقت التحويل البرمجي (Compile-time Errors) عندما نحاول تغيير قيمة تم تحديدها على أنها Immutable، لأن هذا الموقف بحد ذاته يمكن أن يؤدي إلى أخطاء برمجية (Bugs). إذا كان جزء من Code الخاص بنا يعمل بناءً على افتراض أن القيمة لن تتغير أبداً وقام جزء آخر من Code بتغيير تلك القيمة، فمن المحتمل ألا يقوم الجزء الأول من Code بما صُمم للقيام به. قد يكون من الصعب تتبع سبب هذا النوع من Bug بعد وقوعه، خاصة عندما يغير الجزء الثاني من Code القيمة أحياناً فقط. يضمن Compiler الخاص بـ Rust أنه عندما تصرح بأن القيمة لن تتغير، فإنها لن تتغير حقاً، لذا لا يتعين عليك تتبع ذلك بنفسك. وبالتالي يصبح من الأسهل فهم منطق Code الخاص بك.

لكن القابلية للتغير (Mutability) يمكن أن تكون مفيدة جداً ويمكن أن تجعل كتابة Code أكثر ملاءمة. على الرغم من أن Variables تكون Immutable افتراضياً، يمكنك جعلها Mutable عن طريق إضافة الكلمة المفتاحية mut أمام اسم Variable كما فعلت في الفصل 2. إضافة mut تنقل أيضاً النية للقراء المستقبليين لـ Code من خلال الإشارة إلى أن أجزاء أخرى من Code ستغير قيمة Variable هذا.

على سبيل المثال، لنقم بتغيير src/main.rs إلى ما يلي:

اسم الملف: src/main.rs

fn main() {
    let mut x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

عندما نشغل البرنامج الآن، نحصل على هذا:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/variables`
The value of x is: 5
The value of x is: 6

يُسمح لنا بتغيير القيمة المرتبطة بـ x من 5 إلى 6 عند استخدام mut. في النهاية، قرار استخدام Mutability من عدمه يعود إليك ويعتمد على ما تعتقد أنه الأكثر وضوحاً في ذلك الموقف المعين.

التصريح عن الثوابت (Declaring Constants)

مثل Variables غير القابلة للتغير، فإن الثوابت (Constants) هي قيم مرتبطة باسم ولا يُسمح بتغييرها، ولكن هناك بعض الاختلافات بين Constants و Variables.

أولاً، لا يُسمح لك باستخدام mut مع Constants. الثوابت ليست فقط Immutable افتراضياً - بل هي دائماً Immutable. تقوم بالتصريح عن Constants باستخدام الكلمة المفتاحية const بدلاً من الكلمة المفتاحية let ، و يجب تحديد نوع (Type) القيمة. سنغطي الأنواع وتوصيفات الأنواع (Type Annotations) في القسم التالي، “أنواع البيانات”، لذا لا تقلق بشأن التفاصيل الآن. فقط اعلم أنه يجب عليك دائماً توصيف Type.

يمكن التصريح عن Constants في أي نطاق (Scope)، بما في ذلك Scope العالمي، مما يجعلها مفيدة للقيم التي تحتاج أجزاء كثيرة من Code إلى معرفتها.

الاختلاف الأخير هو أنه لا يجوز تعيين Constants إلا لتعبير ثابت (Constant Expression)، وليس لنتيجة قيمة لا يمكن حسابها إلا في وقت التشغيل (Runtime).

إليك مثال على التصريح عن ثابت:

#![allow(unused)]
fn main() {
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
}

اسم الثابت هو THREE_HOURS_IN_SECONDS ، وقيمته محددة بنتيجة ضرب 60 (عدد الثواني في الدقيقة) في 60 (عدد الدقائق في الساعة) في 3 (عدد الساعات التي نريد عدها في هذا البرنامج). اصطلاح التسمية في Rust لـ Constants هو استخدام جميع الأحرف الكبيرة مع وجود شرطات سفلية بين الكلمات. يستطيع Compiler تقييم مجموعة محدودة من العمليات في وقت التحويل البرمجي، مما يتيح لنا اختيار كتابة هذه القيمة بطريقة يسهل فهمها والتحقق منها، بدلاً من تعيين هذا الثابت للقيمة 10,800. راجع قسم مرجع Rust حول تقييم الثوابت لمزيد من المعلومات حول العمليات التي يمكن استخدامها عند التصريح عن Constants.

تكون Constants صالحة طوال وقت تشغيل البرنامج، ضمن Scope الذي تم التصريح عنها فيه. تجعل هذه الخاصية Constants مفيدة للقيم في مجال تطبيقك التي قد تحتاج أجزاء متعددة من البرنامج إلى معرفتها، مثل الحد الأقصى لعدد النقاط التي يُسمح لأي لاعب في اللعبة بالحصول عليها، أو سرعة الضوء.

يعد تسمية القيم المكتوبة مباشرة (Hardcoded Values) المستخدمة في جميع أنحاء برنامجك كـ Constants أمراً مفيداً في نقل معنى تلك القيمة للمسؤولين عن صيانة Code في المستقبل. يساعد أيضاً وجود مكان واحد فقط في Code الخاص بك تحتاج إلى تغييره إذا احتاجت Hardcoded Value إلى التحديث في المستقبل.

الحجب (Shadowing)

كما رأيت في برنامج لعبة التخمين في الفصل 2، يمكنك التصريح عن Variable جديد بنفس اسم Variable سابق. يقول مبرمجو Rust إن Variable الأول قد تم حجبه (Shadowed) بواسطة الثاني، مما يعني أن Variable الثاني هو ما سيراه Compiler عند استخدام اسم Variable. في الواقع، يحجب Variable الثاني الأول، ويأخذ أي استخدامات لاسم Variable لنفسه حتى يتم حجبه هو نفسه أو ينتهي Scope. يمكننا حجب Variable باستخدام نفس اسم Variable وتكرار استخدام الكلمة المفتاحية let كما يلي:

اسم الملف: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }

    println!("The value of x is: {x}");
}

يربط هذا البرنامج أولاً x بقيمة 5. ثم ينشئ Variable جديد x بتكرار let x = ، آخذاً القيمة الأصلية ومضيفاً 1 بحيث تصبح قيمة x هي 6. ثم، داخل Scope داخلي تم إنشاؤه باستخدام الأقواس المتعرجة، تحجب جملة let الثالثة أيضاً x وتنشئ Variable جديداً، وتضرب القيمة السابقة في 2 لتعطي x قيمة 12. عندما ينتهي هذا Scope، ينتهي الحجب الداخلي ويعود x ليكون 6. عندما نشغل هذا البرنامج، سيخرج ما يلي:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
The value of x in the inner scope is: 12
The value of x is: 6

يختلف Shadowing عن تمييز Variable كـ mut لأننا سنحصل على Compile-time Error إذا حاولنا بالخطأ إعادة التعيين لهذا Variable دون استخدام الكلمة المفتاحية let. باستخدام let ، يمكننا إجراء بعض التحويلات على قيمة ولكن يظل Variable غير قابل للتغير بعد اكتمال تلك التحويلات.

الفرق الآخر بين mut و Shadowing هو أننا نظراً لأننا نقوم فعلياً بإنشاء Variable جديد عندما نستخدم الكلمة المفتاحية let مرة أخرى، يمكننا تغيير Type القيمة ولكن مع إعادة استخدام نفس الاسم. على سبيل المثال، لنفترض أن برنامجنا يطلب من المستخدم إظهار عدد المسافات التي يريدها بين بعض النصوص عن طريق إدخال أحرف مسافة، ثم نريد تخزين هذا الإدخال كرقم:

fn main() {
    let spaces = "   ";
    let spaces = spaces.len();
}

أول Variable باسم spaces هو من نوع سلسلة نصية (String Type)، وثاني Variable باسم spaces هو من نوع رقمي (Number Type). وبالتالي يجنبنا Shadowing الاضطرار إلى ابتكار أسماء مختلفة، مثل spaces_str و spaces_num؛ بدلاً من ذلك، يمكننا إعادة استخدام اسم spaces الأبسط. ومع ذلك، إذا حاولنا استخدام mut لهذا، كما هو موضح هنا، فسنحصل على Compile-time Error:

fn main() {
    let mut spaces = "   ";
    spaces = spaces.len();
}

يقول الخطأ إنه لا يُسمح لنا بتغيير نوع (Mutate a variable’s type) المتغير:

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0308]: mismatched types
 --> src/main.rs:3:14
  |
2 |     let mut spaces = "   ";
  |                      ----- expected due to this value
3 |     spaces = spaces.len();
  |              ^^^^^^^^^^^^ expected `&str`, found `usize`

For more information about this error, try `rustc --explain E0308`.
error: could not compile `variables` (bin "variables") due to 1 previous error

الآن بعد أن استكشفنا كيفية عمل Variables، دعنا نلقي نظرة على المزيد من أنواع البيانات (Data Types) التي يمكن أن تمتلكها.

أنواع البيانات (Data Types)

أنواع البيانات (Data Types)

كل قيمة في Rust تنتمي إلى “نوع بيانات” (Data Type) معين، والذي يخبر Rust بنوع البيانات التي يتم تحديدها حتى تعرف كيفية التعامل مع تلك البيانات. سنلقي نظرة على مجموعتين فرعيتين من أنواع البيانات: السلمية (Scalar) والمركبة (Compound).

ضع في اعتبارك أن Rust هي لغة “ذات أنواع ثابتة” (Statically Typed)، مما يعني أنها يجب أن تعرف أنواع جميع المتغيرات في وقت التجميع (Compile Time). يمكن للمترجم (Compiler) عادةً استنتاج النوع الذي نريد استخدامه بناءً على القيمة وكيفية استخدامنا لها. في الحالات التي تكون فيها أنواع عديدة ممكنة، مثل عندما قمنا بتحويل String إلى نوع رقمي باستخدام parse في قسم “مقارنة التخمين بالرقم السري” في الفصل 2، يجب علينا إضافة توضيح للنوع (Type Annotation)، مثل هذا:

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("Not a number!");
}

إذا لم نضف Type Annotation الموضح في الكود السابق (: u32)، فستعرض Rust الخطأ التالي، مما يعني أن الـ Compiler يحتاج إلى مزيد من المعلومات منا لمعرفة النوع الذي نريد استخدامه:

$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0284]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("Not a number!");
  |         ^^^^^        ----- type must be known at this point
  |
  = note: cannot satisfy `<_ as FromStr>::Err == _`
help: consider giving `guess` an explicit type
  |
2 |     let guess: /* Type */ = "42".parse().expect("Not a number!");
  |              ++++++++++++

For more information about this error, try `rustc --explain E0284`.
error: could not compile `no_type_annotations` (bin "no_type_annotations") due to 1 previous error

سترى Type Annotations مختلفة لأنواع البيانات الأخرى.

الأنواع السلمية (Scalar Types)

يمثل النوع “السلمي” (Scalar) قيمة واحدة. تمتلك Rust أربعة أنواع سلمية أساسية: الأعداد الصحيحة (Integers)، وأرقام الفاصلة العائمة (Floating-point numbers)، والقيم المنطقية (Booleans)، والأحرف (Characters). قد تتعرف على هذه الأنواع من لغات البرمجة الأخرى. دعنا ننتقل إلى كيفية عملها في Rust.

أنواع الأعداد الصحيحة (Integer Types)

“العدد الصحيح” (Integer) هو رقم بدون مكون كسري. استخدمنا نوعاً واحداً من الـ Integers في الفصل 2، وهو نوع u32. يشير إعلان النوع هذا إلى أن القيمة المرتبطة به يجب أن تكون عدداً صحيحاً غير موقع (Unsigned Integer) - تبدأ أنواع الأعداد الصحيحة الموقعة (Signed Integer) بـ i بدلاً من u - يشغل مساحة 32 بت. يوضح الجدول 3-1 أنواع الأعداد الصحيحة المدمجة في Rust. يمكننا استخدام أي من هذه التنويعات للإعلان عن نوع قيمة عدد صحيح.

الجدول 3-1: أنواع الأعداد الصحيحة في Rust

يمكن أن تكون كل تنويعة إما Signed أو Unsigned ولها حجم صريح. تشير كلمتا “موقع” (Signed) و “غير موقع” (Unsigned) إلى ما إذا كان من الممكن أن يكون الرقم سالباً - بعبارة أخرى، ما إذا كان الرقم يحتاج إلى علامة معه (Signed) أو ما إذا كان سيكون موجباً دائماً وبالتالي يمكن تمثيله بدون علامة (Unsigned). الأمر يشبه كتابة الأرقام على الورق: عندما تهم العلامة، يظهر الرقم بعلامة زائد أو علامة ناقص؛ ومع ذلك، عندما يكون من الآمن افتراض أن الرقم موجب، فإنه يظهر بدون علامة. يتم تخزين الأرقام الـ Signed باستخدام تمثيل المكمل لـ 2.

يمكن لكل تنويعة Signed تخزين أرقام من −(2^{n − 1}) إلى 2^{n − 1} − 1 ضمناً، حيث n هو عدد البتات التي تستخدمها تلك التنويعة. لذا، يمكن لـ i8 تخزين أرقام من −(2⁷) إلى 2⁷ − 1، وهو ما يعادل −128 إلى 127. يمكن للتنويعات الـ Unsigned تخزين أرقام من 0 إلى 2ⁿ − 1، لذا يمكن لـ u8 تخزين أرقام من 0 إلى 2⁸ − 1، وهو ما يعادل 0 إلى 255.

بالإضافة إلى ذلك، يعتمد نوعا isize و usize على معمارية الحاسوب الذي يعمل عليه برنامجك: 64 بت إذا كنت على معمارية 64 بت و 32 بت إذا كنت على معمارية 32 بت.

يمكنك كتابة الثوابت العددية الصحيحة (Integer Literals) بأي من الأشكال الموضحة في الجدول 3-2. لاحظ أن الثوابت الرقمية التي يمكن أن تكون أنواعاً رقمية متعددة تسمح بلاحقة نوع (Type Suffix)، مثل 57u8 لتحديد النوع. يمكن للثوابت الرقمية أيضاً استخدام _ كفاصل مرئي لجعل الرقم أسهل في القراءة، مثل 1_000 والتي سيكون لها نفس القيمة كما لو كنت قد حددت 1000.

الجدول 3-2: الثوابت العددية الصحيحة في Rust

إذاً كيف تعرف أي نوع من الـ Integers تستخدم؟ إذا كنت غير متأكد، فإن الخيارات الافتراضية في Rust هي أماكن جيدة للبدء بشكل عام: أنواع الـ Integers الافتراضية هي i32. الحالة الأساسية التي تستخدم فيها isize أو usize هي عند فهرسة (Indexing) نوع من المجموعات (Collections).

طفحان الأعداد الصحيحة (Integer Overflow)

لنفترض أن لديك متغيراً من نوع u8 يمكنه حمل قيم بين 0 و 255. إذا حاولت تغيير المتغير إلى قيمة خارج هذا النطاق، مثل 256، فسيحدث “طفحان الأعداد الصحيحة” (Integer Overflow)، مما قد يؤدي إلى أحد سلوكين. عندما تقوم بالتجميع في وضع التصحيح (Debug Mode)، تتضمن Rust فحوصات لـ Integer Overflow تتسبب في “هلع” (Panic) برنامجك في الـ Runtime إذا حدث هذا السلوك. تستخدم Rust مصطلح “الهلع” (Panicking) عندما يخرج البرنامج مع وجود خطأ؛ سنناقش الـ Panics بمزيد من العمق في قسم “أخطاء غير قابلة للاسترداد مع panic!” في الفصل 9.

عندما تقوم بالتجميع في وضع الإصدار (Release Mode) باستخدام علم --release لا تتضمن Rust فحوصات لـ Integer Overflow التي تسبب Panics. بدلاً من ذلك، إذا حدث Overflow، تقوم Rust بإجراء “التفاف المكمل لـ 2” (Two’s Complement Wrapping). باختصار، القيم الأكبر من القيمة القصوى التي يمكن أن يحملها النوع “تلتف” إلى الحد الأدنى من القيم التي يمكن أن يحملها النوع. في حالة u8 تصبح القيمة 256 هي 0، والقيمة 257 تصبح 1، وهكذا. لن يهلع البرنامج، ولكن المتغير سيكون له قيمة ربما ليست هي ما كنت تتوقع أن تكون عليه. الاعتماد على سلوك الالتفاف الخاص بـ Integer Overflow يعتبر خطأ.

للتعامل صراحة مع احتمالية حدوث Overflow، يمكنك استخدام هذه المجموعات من الـ Methods التي توفرها الـ Standard Library للأنواع الرقمية الأولية:

• الالتفاف في جميع الأوضاع باستخدام Methods الـ wrapping_* مثل wrapping_add.
• إرجاع قيمة None إذا كان هناك Overflow باستخدام Methods الـ checked_*.
• إرجاع القيمة وقيمة منطقية تشير إلى ما إذا كان هناك Overflow باستخدام Methods الـ overflowing_*.
• التشبع عند القيم الدنيا أو القصوى للقيمة باستخدام Methods الـ saturating_*.

أنواع الفاصلة العائمة (Floating-Point Types)

تمتلك Rust أيضاً نوعين أوليين لـ “أرقام الفاصلة العائمة” (Floating-point numbers)، وهي الأرقام التي تحتوي على فواصل عشرية. أنواع الـ Floating-point في Rust هي f32 و f64 وحجمهما 32 بت و 64 بت على التوالي. النوع الافتراضي هو f64 لأنه في وحدات المعالجة المركزية (CPUs) الحديثة، يكون بنفس سرعة f32 تقريباً ولكنه قادر على توفير دقة أكبر. جميع أنواع الـ Floating-point هي Signed.

إليك مثال يوضح أرقام الفاصلة العائمة أثناء العمل:

اسم الملف: src/main.rs

fn main() {
    let x = 2.0; // f64

    let y: f32 = 3.0; // f32
}

يتم تمثيل الـ Floating-point numbers وفقاً لمعيار IEEE-754.

العمليات الرقمية (Numeric Operations)

تدعم Rust العمليات الحسابية الأساسية التي تتوقعها لجميع أنواع الأرقام: الجمع، والطرح، والضرب، والقسمة، والباقي. تقوم قسمة الأعداد الصحيحة بالتقريب نحو الصفر إلى أقرب عدد صحيح. يوضح الكود التالي كيفية استخدام كل عملية رقمية في عبارة let:

اسم الملف: src/main.rs

fn main() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

    // division
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Results in -1

    // remainder
    let remainder = 43 % 5;
}

تستخدم كل تعبير (Expression) في هذه العبارات عاملاً حسابياً ويتم تقييمه إلى قيمة واحدة، والتي يتم ربطها بعد ذلك بمتغير. يحتوي الملحق ب على قائمة بجميع العوامل (Operators) التي توفرها Rust.

النوع المنطقي (The Boolean Type)

كما هو الحال في معظم لغات البرمجة الأخرى، فإن النوع المنطقي (Boolean) في Rust له قيمتان ممكنتان: true و false. حجم الـ Booleans هو بايت واحد. يتم تحديد النوع الـ Boolean في Rust باستخدام bool. على سبيل المثال:

اسم الملف: src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // with explicit type annotation
}

الطريقة الرئيسية لاستخدام قيم الـ Boolean هي من خلال الشروط، مثل تعبير if. سنغطي كيفية عمل تعبيرات if في Rust في قسم “تدفق التحكم”.

نوع الحرف (The Character Type)

نوع char في Rust هو النوع الأبجدي الأكثر أولية في اللغة. إليك بعض الأمثلة على الإعلان عن قيم char:

اسم الملف: src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // with explicit type annotation
    let heart_eyed_cat = '😻';
}

لاحظ أننا نحدد ثوابت الـ char (Character Literals) بعلامات اقتباس مفردة، على عكس الـ String Literals التي تستخدم علامات اقتباس مزدوجة. حجم نوع char في Rust هو 4 بايت ويمثل قيمة سلمية لليونيكود (Unicode Scalar Value)، مما يعني أنه يمكنه تمثيل أكثر بكثير من مجرد ASCII. الأحرف المشكلة؛ والأحرف الصينية واليابانية والكورية؛ والرموز التعبيرية (Emojis)؛ والمساحات ذات العرض الصفري كلها قيم char صالحة في Rust. تتراوح الـ Unicode Scalar Values من U+0000 إلى U+D7FF ومن U+E000 إلى U+10FFFF ضمناً. ومع ذلك، فإن “الحرف” ليس حقاً مفهوماً في Unicode، لذا فإن حدسك البشري لما هو “الحرف” قد لا يتطابق مع ما هو الـ char في Rust. سنناقش هذا الموضوع بالتفصيل في “تخزين النصوص المشفرة بـ UTF-8 باستخدام السلاسل النصية” في الفصل 8.

الأنواع المركبة (Compound Types)

يمكن لـ “الأنواع المركبة” (Compound Types) تجميع قيم متعددة في نوع واحد. تمتلك Rust نوعين مركبين أوليين: الصفوف (Tuples) والمصفوفات (Arrays).

نوع الصف (The Tuple Type)

“الصف” (Tuple) هو طريقة عامة لتجميع عدد من القيم بأنواع متنوعة في نوع مركب واحد. الـ Tuples لها طول ثابت: بمجرد الإعلان عنها، لا يمكن أن تنمو أو تتقلص في الحجم.

ننشئ Tuple عن طريق كتابة قائمة قيم مفصولة بفاصلة داخل أقواس. كل موضع في الـ Tuple له نوع، ولا يجب أن تكون أنواع القيم المختلفة في الـ Tuple هي نفسها. لقد أضفنا Type Annotations اختيارية في هذا المثال:

اسم الملف: src/main.rs

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

يرتبط المتغير tup بالـ Tuple بأكملها لأن الـ Tuple تعتبر عنصراً مركباً واحداً. للحصول على القيم الفردية من الـ Tuple، يمكننا استخدام مطابقة الأنماط (Pattern Matching) لـ “تفكيك” (Destructure) قيمة الـ Tuple، مثل هذا:

اسم الملف: src/main.rs

fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

    println!("The value of y is: {y}");
}

ينشئ هذا البرنامج أولاً Tuple ويربطها بالمتغير tup. ثم يستخدم نمطاً مع let لأخذ tup وتحويلها إلى ثلاثة متغيرات منفصلة، x و y و z. يسمى هذا “التفكيك” (Destructuring) لأنه يكسر الـ Tuple الواحدة إلى ثلاثة أجزاء. أخيراً، يطبع البرنامج قيمة y وهي 6.4.

يمكننا أيضاً الوصول إلى عنصر في الـ Tuple مباشرة باستخدام نقطة (.) متبوعة بفهرس (Index) القيمة التي نريد الوصول إليها. على سبيل المثال:

اسم الملف: src/main.rs

fn main() {
    let x: (i32, f64, u8) = (500, 6.4, 1);

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

ينشئ هذا البرنامج الـ Tuple المسمى x ثم يصل إلى كل عنصر فيها باستخدام فهارسها الخاصة. كما هو الحال في معظم لغات البرمجة، الفهرس الأول في الـ Tuple هو 0.

الـ Tuple التي لا تحتوي على أي قيم لها اسم خاص، وهو “الوحدة” (Unit). هذه القيمة ونوعها المماثل يكتبان () ويمثلان قيمة فارغة أو نوع إرجاع فارغ. تعيد التعبيرات (Expressions) قيمة الـ Unit ضمنياً إذا لم تعيد أي قيمة أخرى.

نوع المصفوفة (The Array Type)

طريقة أخرى لامتلاك مجموعة من قيم متعددة هي باستخدام “المصفوفة” (Array). على عكس الـ Tuple، يجب أن يكون لكل عنصر في الـ Array نفس النوع. وعلى عكس الـ Arrays في بعض اللغات الأخرى، فإن الـ Arrays في Rust لها طول ثابت.

نكتب القيم في الـ Array كقائمة مفصولة بفاصلة داخل أقواس مربعة:

اسم الملف: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];
}

تكون الـ Arrays مفيدة عندما تريد تخصيص بياناتك على “المكدس” (Stack)، تماماً مثل الأنواع الأخرى التي رأيناها حتى الآن، بدلاً من “الكومة” (Heap) (سنناقش الـ Stack والـ Heap أكثر في الفصل 4) أو عندما تريد التأكد من أن لديك دائماً عدداً ثابتاً من العناصر. ومع ذلك، فإن الـ Array ليست مرنة مثل نوع المتجه (Vector). الـ Vector هو نوع مجموعة مماثل توفره الـ Standard Library ويُسمح له بالنمو أو التقلص في الحجم لأن محتوياته تعيش على الـ Heap. إذا كنت غير متأكد مما إذا كنت ستستخدم Array أو Vector، فمن المحتمل أنك يجب أن تستخدم Vector. يناقش الفصل 8 الـ Vectors بمزيد من التفصيل.

ومع ذلك، تكون الـ Arrays أكثر فائدة عندما تعرف أن عدد العناصر لن يحتاج إلى التغيير. على سبيل المثال، إذا كنت تستخدم أسماء الأشهر في برنامج ما، فمن المحتمل أن تستخدم Array بدلاً من Vector لأنك تعلم أنها ستحتوي دائماً على 12 عنصراً:

#![allow(unused)]
fn main() {
let months = ["January", "February", "March", "April", "May", "June", "July",
              "August", "September", "October", "November", "December"];
}

تكتب نوع الـ Array باستخدام أقواس مربعة مع نوع كل عنصر، وفاصلة منقوطة، ثم عدد العناصر في الـ Array، هكذا:

#![allow(unused)]
fn main() {
let a: [i32; 5] = [1, 2, 3, 4, 5];
}

هنا، i32 هو نوع كل عنصر. بعد الفاصلة المنقوطة، يشير الرقم 5 إلى أن الـ Array تحتوي على خمسة عناصر.

يمكنك أيضاً تهيئة Array لتبدأ بنفس القيمة لكل عنصر عن طريق تحديد القيمة الأولية، متبوعة بفاصلة منقوطة، ثم طول الـ Array داخل أقواس مربعة، كما هو موضح هنا:

#![allow(unused)]
fn main() {
let a = [3; 5];
}

ستحتوي الـ Array المسماة a على 5 عناصر سيتم ضبطها جميعاً على القيمة 3 في البداية. هذا هو نفسه كتابة let a = [3, 3, 3, 3, 3]; ولكن بطريقة أكثر إيجازاً.

الوصول إلى عناصر المصفوفة (Array Element Access)

الـ Array هي قطعة واحدة من الذاكرة ذات حجم معروف وثابت يمكن تخصيصها على الـ Stack. يمكنك الوصول إلى عناصر الـ Array باستخدام الـ Indexing، مثل هذا:

اسم الملف: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];

    let first = a[0];
    let second = a[1];
}

في هذا المثال، سيحصل المتغير المسمى first على القيمة 1 لأن هذه هي القيمة عند الفهرس [0] في الـ Array. سيحصل المتغير المسمى second على القيمة 2 من الفهرس [1] في الـ Array.

الوصول غير الصالح لعناصر المصفوفة (Invalid Array Element Access)

دعنا نرى ما يحدث إذا حاولت الوصول إلى عنصر في Array يتجاوز نهاية الـ Array. لنفترض أنك قمت بتشغيل هذا الكود، المشابه للعبة التخمين في الفصل 2، للحصول على فهرس مصفوفة من المستخدم:

اسم الملف: src/main.rs

use std::io;

fn main() {
    let a = [1, 2, 3, 4, 5];

    println!("Please enter an array index.");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("Failed to read line");

    let index: usize = index
        .trim()
        .parse()
        .expect("Index entered was not a number");

    let element = a[index];

    println!("The value of the element at index {index} is: {element}");
}

يتم تجميع هذا الكود بنجاح. إذا قمت بتشغيل هذا الكود باستخدام cargo run وأدخلت 0 أو 1 أو 2 أو 3 أو 4 فسيقوم البرنامج بطباعة القيمة المقابلة عند ذلك الفهرس في الـ Array. إذا أدخلت بدلاً من ذلك رقماً يتجاوز نهاية الـ Array، مثل 10 فسترى مخرجات مثل هذه:

thread 'main' panicked at src/main.rs:19:19:
index out of bounds: the len is 5 but the index is 10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

أدى البرنامج إلى خطأ في الـ Runtime عند نقطة استخدام قيمة غير صالحة في عملية الـ Indexing. خرج البرنامج برسالة خطأ ولم ينفذ عبارة println! النهائية. عندما تحاول الوصول إلى عنصر باستخدام الـ Indexing، ستتحقق Rust من أن الفهرس الذي حددته أقل من طول الـ Array. إذا كان الفهرس أكبر من أو يساوي الطول، فستقوم Rust بالـ Panic. يجب أن يحدث هذا الفحص في الـ Runtime، خاصة في هذه الحالة، لأن الـ Compiler لا يمكنه معرفة القيمة التي سيدخلها المستخدم عندما يقوم بتشغيل الكود لاحقاً.

هذا مثال على مبادئ أمان الذاكرة (Memory Safety) في Rust أثناء العمل. في العديد من اللغات منخفضة المستوى، لا يتم إجراء هذا النوع من الفحص، وعندما تقدم فهرساً غير صحيح، يمكن الوصول إلى ذاكرة غير صالحة. تحميك Rust من هذا النوع من الأخطاء عن طريق الخروج فوراً بدلاً من السماح بالوصول إلى الذاكرة والاستمرار. يناقش الفصل 9 المزيد من معالجة الأخطاء في Rust وكيف يمكنك كتابة كود مقروء وآمن لا يهلع ولا يسمح بالوصول غير الصالح للذاكرة.

الدوال (Functions)

الدوال (Functions)

تنتشر الدوال في كود Rust. لقد رأيت بالفعل واحدة من أهم الدوال في اللغة: دالة main ، وهي نقطة الدخول (entry point) للعديد من البرامج. لقد رأيت أيضاً الكلمة المفتاحية fn ، والتي تسمح لك بالتصريح عن دوال جديدة.

يستخدم كود Rust أسلوب snake case كنمط تقليدي لأسماء الدوال والمتغيرات، حيث تكون جميع الحروف صغيرة وتفصل الشرطة السفلية (underscores) بين الكلمات. إليك برنامج يحتوي على مثال لتعريف دالة:

اسم الملف: src/main.rs

fn main() {
    println!("Hello, world!");

    another_function();
}

fn another_function() {
    println!("Another function.");
}

نقوم بتعريف دالة في Rust عن طريق إدخال fn متبوعة باسم الدالة ومجموعة من الأقواس. تخبر الأقواس المتعرجة (curly brackets) المصرف (compiler) بمكان بداية ونهاية جسم الدالة (function body).

يمكننا استدعاء أي دالة قمنا بتعريفها عن طريق إدخال اسمها متبوعاً بمجموعة من الأقواس. نظراً لأن another_function معرفة في البرنامج، يمكن استدعاؤها من داخل دالة main. لاحظ أننا قمنا بتعريف another_function بعد دالة main في الكود المصدري؛ كان بإمكاننا تعريفها قبل ذلك أيضاً. لا يهتم Rust بمكان تعريف دوالك، طالما أنها معرفة في مكان ما في نطاق (scope) يمكن رؤيته من قبل المستدعي (caller).

دعونا نبدأ مشروعاً ثنائياً (binary project) جديداً باسم functions لاستكشاف الدوال بشكل أكبر. ضع مثال another_function في ملف src/main.rs وقم بتشغيله. يجب أن ترى المخرجات التالية:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.28s
     Running `target/debug/functions`
Hello, world!
Another function.

يتم تنفيذ الأسطر بالترتيب الذي تظهر به في دالة main. أولاً يتم طباعة رسالة “Hello, world!” ، ثم يتم استدعاء another_function وطباعة رسالتها.

المعلمات (Parameters)

يمكننا تعريف الدوال بحيث تحتوي على معلمات (parameters)، وهي متغيرات خاصة تشكل جزءاً من توقيع الدالة (function’s signature). عندما تحتوي الدالة على parameters، يمكنك تزويدها بقيم ملموسة (concrete values) لتلك المعلمات. تقنياً، تسمى القيم الملموسة وسائط (arguments)، ولكن في المحادثات العادية، يميل الناس إلى استخدام الكلمتين parameter و argument بالتبادل سواء للمتغيرات في تعريف الدالة أو للقيم الملموسة التي يتم تمريرها عند استدعاء الدالة.

في هذا الإصدار من another_function نضيف parameter:

اسم الملف: src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("The value of x is: {x}");
}

جرب تشغيل هذا البرنامج؛ يجب أن تحصل على المخرجات التالية:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.21s
     Running `target/debug/functions`
The value of x is: 5

يحتوي التصريح عن another_function على parameter واحد باسم x. تم تحديد نوع x على أنه i32. عندما نمرر 5 إلى another_function ، يضع ماكرو println! القيمة 5 مكان زوج الأقواس المتعرجة الذي يحتوي على x في سلسلة التنسيق (format string).

في توقيعات الدوال، يجب عليك التصريح عن نوع كل parameter. هذا قرار متعمد في تصميم Rust: إن اشتراط توضيحات النوع (type annotations) في تعريفات الدوال يعني أن compiler لا يحتاج منك تقريباً لاستخدامها في أي مكان آخر في الكود لمعرفة النوع الذي تقصده. كما يستطيع compiler تقديم رسائل خطأ أكثر فائدة إذا كان يعرف الأنواع التي تتوقعها الدالة.

عند تعريف عدة parameters، افصل بين التصريحات عن المعلمات بفاصلة، هكذا:

اسم الملف: src/main.rs

fn main() {
    print_labeled_measurement(5, 'h');
}

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("The measurement is: {value}{unit_label}");
}

ينشئ هذا المثال دالة باسم print_labeled_measurement مع اثنين من parameters. المعلمة الأولى تسمى value وهي من نوع i32. والثانية تسمى unit_label وهي من نوع char. تقوم الدالة بعد ذلك بطباعة نص يحتوي على كل من value و unit_label.

دعونا نجرب تشغيل هذا الكود. استبدل البرنامج الموجود حالياً في ملف src/main.rs بمشروع functions الخاص بك بالمثال السابق وقم بتشغيله باستخدام cargo run:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/functions`
The measurement is: 5h

لأننا استدعينا الدالة بالقيمة 5 كقيمة لـ value و 'h' كقيمة لـ unit_label ، فإن مخرجات البرنامج تحتوي على تلك القيم.

الجمل والتعبيرات (Statements and Expressions)

تتكون أجسام الدوال من سلسلة من الجمل (statements) التي تنتهي اختيارياً بتعبير (expression). حتى الآن، لم تتضمن الدوال التي غطيناها تعبيراً ختامياً، لكنك رأيت تعبيراً كجزء من statement. نظراً لأن Rust لغة قائمة على التعبيرات (expression-based language)، فهذا تمييز مهم يجب فهمه. اللغات الأخرى ليس لديها نفس التمييزات، لذا دعونا نلقي نظرة على ماهية statements و expressions وكيف تؤثر اختلافاتهم على أجسام الدوال.

• الجمل (Statements) هي تعليمات تؤدي بعض الإجراءات ولا تعيد قيمة.
• التعبيرات (Expressions) تؤول إلى قيمة ناتجة.

دعونا نلقي نظرة على بعض الأمثلة.

لقد استخدمنا بالفعل statements و expressions. إن إنشاء متغير وتعيين قيمة له باستخدام الكلمة المفتاحية let هو statement. في القائمة 3-1، let y = 6; هي statement.

fn main() {
    let y = 6;
}

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

لا تعيد Statements قيماً. لذلك، لا يمكنك تعيين let statement لمتغير آخر، كما يحاول الكود التالي القيام به؛ ستحصل على خطأ:

اسم الملف: src/main.rs

fn main() {
    let x = (let y = 6);
}

عند تشغيل هذا البرنامج، فإن الخطأ الذي ستحصل عليه سيبدو كالتالي:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error: expected expression, found `let` statement
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^
  |
  = note: only supported directly in conditions of `if` and `while` expressions

warning: unnecessary parentheses around assigned value
 --> src/main.rs:2:13
  |
2 |     let x = (let y = 6);
  |             ^         ^
  |
  = note: `#[warn(unused_parens)]` on by default
help: remove these parentheses
  |
2 -     let x = (let y = 6);
2 +     let x = let y = 6;
  |

warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` (bin "functions") due to 1 previous error; 1 warning emitted

جملة let y = 6 لا تعيد قيمة، لذا لا يوجد شيء ليرتبط به x. هذا يختلف عما يحدث في لغات أخرى، مثل C و Ruby، حيث تعيد عملية التعيين (assignment) قيمة التعيين. في تلك اللغات، يمكنك كتابة x = y = 6 ويكون لكل من x و y القيمة 6 ؛ ليس هذا هو الحال في Rust.

تؤول Expressions إلى قيمة وتشكل معظم بقية الكود الذي ستكتبه في Rust. فكر في عملية حسابية، مثل 5 + 6 ، وهي expression يؤول إلى القيمة 11. يمكن أن تكون Expressions جزءاً من statements: في القائمة 3-1، القيمة 6 في الجملة let y = 6; هي expression يؤول إلى القيمة 6. استدعاء الدالة هو expression. استدعاء الماكرو هو expression. كتلة النطاق (scope block) الجديدة التي يتم إنشاؤها باستخدام الأقواس المتعرجة هي expression، على سبيل المثال:

اسم الملف: src/main.rs

fn main() {
    let y = {
        let x = 3;
        x + 1
    };

    println!("The value of y is: {y}");
}

هذا التعبير:

{
    let x = 3;
    x + 1
}

هو كتلة (block) تؤول في هذه الحالة إلى 4. ترتبط هذه القيمة بـ y كجزء من let statement. لاحظ سطر x + 1 بدون فاصلة منقوطة (semicolon) في نهايته، وهو ما يختلف عن معظم الأسطر التي رأيتها حتى الآن. لا تتضمن Expressions فواصل منقوطة ختامية. إذا أضفت فاصلة منقوطة إلى نهاية expression، فإنك تحوله إلى statement، وعندها لن يعيد قيمة. ضع ذلك في الاعتبار بينما تستكشف قيم إرجاع الدوال والتعبيرات تالياً.

دوال ذات قيم إرجاع (Functions with Return Values)

يمكن للدوال إعادة قيم إلى الكود الذي يستدعيها. نحن لا نسمي قيم الإرجاع (return values)، ولكن يجب علينا التصريح عن نوعها بعد سهم (->). في Rust، قيمة إرجاع الدالة مرادفة لقيمة التعبير الأخير في كتلة جسم الدالة. يمكنك الإرجاع مبكراً من دالة باستخدام الكلمة المفتاحية return وتحديد قيمة، ولكن معظم الدوال تعيد التعبير الأخير بشكل ضمني (implicitly). إليك مثال لدالة تعيد قيمة:

اسم الملف: src/main.rs

fn five() -> i32 {
    5
}

fn main() {
    let x = five();

    println!("The value of x is: {x}");
}

لا توجد استدعاءات دوال، أو ماكرو، أو حتى let statements في دالة five — فقط الرقم 5 بمفرده. هذه دالة صالحة تماماً في Rust. لاحظ أن نوع إرجاع الدالة محدد أيضاً كـ -> i32. جرب تشغيل هذا الكود؛ يجب أن تبدو المخرجات كالتالي:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/functions`
The value of x is: 5

الرقم 5 في five هو قيمة إرجاع الدالة، ولهذا السبب نوع الإرجاع هو i32. دعونا نفحص هذا بمزيد من التفصيل. هناك جزئيتان مهمتان: أولاً، يظهر السطر let x = five(); أننا نستخدم قيمة إرجاع الدالة لتهيئة متغير. نظراً لأن الدالة five تعيد 5 ، فإن هذا السطر هو نفسه السطر التالي:

#![allow(unused)]
fn main() {
let x = 5;
}

ثانياً، دالة five ليس لها parameters وتحدد نوع قيمة الإرجاع، لكن جسم الدالة هو 5 وحيد بدون فاصلة منقوطة لأنه expression نريد إعادة قيمته.

دعونا نلقي نظرة على مثال آخر:

اسم الملف: src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1
}

سيؤدي تشغيل هذا الكود إلى طباعة The value of x is: 6. ولكن ماذا يحدث إذا وضعنا فاصلة منقوطة في نهاية السطر الذي يحتوي على x + 1 ، محولين إياه من expression إلى statement؟

اسم الملف: src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1;
}

سيؤدي تصريف هذا الكود إلى حدوث خطأ، كالتالي:

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error[E0308]: mismatched types
 --> src/main.rs:7:24
  |
7 | fn plus_one(x: i32) -> i32 {
  |    --------            ^^^ expected `i32`, found `()`
  |    |
  |    implicitly returns `()` as its body has no tail or `return` expression
8 |     x + 1;
  |          - help: remove this semicolon to return this value

For more information about this error, try `rustc --explain E0308`.
error: could not compile `functions` (bin "functions") due to 1 previous error

رسالة الخطأ الرئيسية، mismatched types ، تكشف عن المشكلة الجوهرية في هذا الكود. يقول تعريف الدالة plus_one أنها ستعيد i32 ، لكن statements لا تؤول إلى قيمة، وهو ما يتم التعبير عنه بـ () ، النوع الوحدوي (unit type). لذلك، لا يتم إرجاع أي شيء، مما يتعارض مع تعريف الدالة ويؤدي إلى حدوث خطأ. في هذه المخرجات، يقدم Rust رسالة للمساعدة في تصحيح هذه المشكلة: يقترح إزالة الفاصلة المنقوطة، مما سيصلح الخطأ.

التعليقات (Comments)

التعليقات (Comments)

يسعى جميع المبرمجين لجعل code الخاص بهم سهل الفهم، ولكن في بعض الأحيان يكون هناك ما يبرر وجود شرح إضافي. في هذه الحالات، يترك المبرمجون تعليقات (comments) في شفرة المصدر (source code) الخاصة بهم والتي سيتجاهلها المُصرِّف (compiler) ولكن قد يجدها الأشخاص الذين يقرؤون source code مفيدة.

إليك comment بسيط:

#![allow(unused)]
fn main() {
// hello, world
}

في Rust، يبدأ أسلوب comment الاصطلاحي بشرطتين مائلتين، ويستمر comment حتى نهاية السطر. بالنسبة لـ comments التي تمتد إلى ما بعد سطر واحد، ستحتاج إلى تضمين // في كل سطر، مثل هذا:

#![allow(unused)]
fn main() {
// So we're doing something complicated here, long enough that we need
// multiple lines of comments to do it! Whew! Hopefully, this comment will
// explain what's going on.
}

يمكن أيضًا وضع comments في نهاية الأسطر التي تحتوي على code:

Filename: src/main.rs

fn main() {
    let lucky_number = 7; // I'm feeling lucky today
}

ولكن غالبًا ما ستراها مستخدمة بهذا التنسيق، مع comment على سطر منفصل فوق code الذي تشرحه:

Filename: src/main.rs

fn main() {
    // I'm feeling lucky today
    let lucky_number = 7;
}

لدى Rust أيضًا نوع آخر من comments، وهو تعليقات التوثيق (documentation comments)، والتي سنناقشها في قسم “نشر حزمة (Crate) إلى Crates.io” من الفصل 14.

تدفق التحكم (Control Flow)

تدفق التحكم (Control Flow)

تعد القدرة على تشغيل بعض الأكواد بناءً على ما إذا كان الشرط true والقدرة على تشغيل بعض الأكواد بشكل متكرر بينما يكون الشرط true من اللبنات الأساسية في معظم لغات البرمجة. أكثر البنيات شيوعاً التي تتيح لك التحكم في تدفق تنفيذ كود Rust هي تعبيرات if والحلقات (loops).

تعبيرات if (if Expressions)

يسمح لك تعبير if بتفريع الكود الخاص بك بناءً على الشروط. أنت تقدم شرطاً ثم تنص على: “إذا تم استيفاء هذا الشرط، فقم بتشغيل كتلة الكود هذه. وإذا لم يتم استيفاء الشرط، فلا تقم بتشغيل كتلة الكود هذه”.

أنشئ مشروعاً جديداً يسمى branches في دليل projects الخاص بك لاستكشاف تعبير if. في ملف src/main.rs ، أدخل ما يلي:

اسم الملف: src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

تبدأ جميع تعبيرات if بالكلمة المفتاحية if ، متبوعة بشرط. في هذه الحالة، يتحقق الشرط مما إذا كان المتغير number يحتوي على قيمة أقل من 5 أم لا. نضع كتلة الكود المراد تنفيذها إذا كان الشرط true مباشرة بعد الشرط داخل أقواس متعرجة. تسمى كتل الكود المرتبطة بالشروط في تعبيرات if أحياناً بالأذرع (arms)، تماماً مثل arms في تعبيرات match التي ناقشناها في قسم “مقارنة التخمين بالرقم السري” من الفصل الثاني.

اختيارياً، يمكننا أيضاً تضمين تعبير else ، وهو ما اخترنا القيام به هنا، لمنح البرنامج كتلة كود بديلة لتنفيذها في حالة تقييم الشرط إلى false. إذا لم تقدم تعبير else وكان الشرط false ، فسيقوم البرنامج ببساطة بتخطي كتلة if والانتقال إلى الجزء التالي من الكود.

حاول تشغيل هذا الكود؛ يجب أن ترى المخرجات التالية:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was true

دعونا نحاول تغيير قيمة number إلى قيمة تجعل الشرط false لنرى ما سيحدث:

fn main() {
    let number = 7;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

قم بتشغيل البرنامج مرة أخرى، وانظر إلى المخرجات:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was false

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

اسم الملف: src/main.rs

fn main() {
    let number = 3;

    if number {
        println!("number was three");
    }
}

يتم تقييم شرط if إلى قيمة 3 هذه المرة، ويقوم Rust بإصدار خطأ:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: mismatched types
 --> src/main.rs:4:8
  |
4 |     if number {
  |        ^^^^^^ expected `bool`, found integer

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

يشير الخطأ إلى أن Rust توقع bool ولكنه حصل على عدد صحيح (integer). على عكس لغات مثل Ruby و JavaScript، لن يحاول Rust تلقائياً تحويل الأنواع غير المنطقية إلى Boolean. يجب أن تكون صريحاً وتزود if دائماً بقيمة Boolean كشرط لها. إذا أردنا تشغيل كتلة كود if فقط عندما لا يساوي الرقم 0 ، على سبيل المثال، يمكننا تغيير تعبير if إلى ما يلي:

اسم الملف: src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("number was something other than zero");
    }
}

سيؤدي تشغيل هذا الكود إلى طباعة number was something other than zero.

التعامل مع شروط متعددة باستخدام else if

يمكنك استخدام شروط متعددة من خلال الجمع بين if و else في تعبير else if. على سبيل المثال:

اسم الملف: src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("number is divisible by 4");
    } else if number % 3 == 0 {
        println!("number is divisible by 3");
    } else if number % 2 == 0 {
        println!("number is divisible by 2");
    } else {
        println!("number is not divisible by 4, 3, or 2");
    }
}

يحتوي هذا البرنامج على أربعة مسارات محتملة يمكنه اتخاذها. بعد تشغيله، يجب أن ترى المخرجات التالية:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
number is divisible by 3

عندما يتم تنفيذ هذا البرنامج، فإنه يتحقق من كل تعبير if بالترتيب وينفذ أول جسم يتم تقييم شرطه إلى true. لاحظ أنه على الرغم من أن 6 يقبل القسمة على 2، إلا أننا لا نرى المخرجات number is divisible by 2 ، ولا نرى نص number is not divisible by 4, 3, or 2 من كتلة else. وذلك لأن Rust ينفذ فقط الكتلة الخاصة بأول شرط true ، وبمجرد العثور على واحد، فإنه لا يتحقق حتى من الباقي.

يمكن أن يؤدي استخدام الكثير من تعبيرات else if إلى جعل الكود الخاص بك مزدحماً، لذا إذا كان لديك أكثر من واحد، فقد ترغب في إعادة هيكلة (refactor) الكود الخاص بك. يصف الفصل السادس بنية تفريع قوية في Rust تسمى match لهذه الحالات.

استخدام if في عبارة let

نظراً لأن if هو تعبير (expression)، يمكننا استخدامه على الجانب الأيمن من عبارة let لتعيين النتيجة لمتغير، كما في القائمة 3-2.

fn main() {
    let condition = true;
    let number = if condition { 5 } else { 6 };

    println!("The value of number is: {number}");
}

سيتم ربط المتغير number بقيمة بناءً على نتيجة تعبير if. قم بتشغيل هذا الكود لترى ما سيحدث:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/branches`
The value of number is: 5

تذكر أن كتل الكود يتم تقييمها إلى آخر تعبير فيها، والأرقام بحد ذاتها هي أيضاً تعبيرات. في هذه الحالة، تعتمد قيمة تعبير if بالكامل على كتلة الكود التي يتم تنفيذها. هذا يعني أن القيم التي لديها القدرة على أن تكون نتائج من كل ذراع من أذرع if يجب أن تكون من نفس النوع؛ في القائمة 3-2، كانت نتائج كل من ذراع if وذراع else أعداداً صحيحة من نوع i32. إذا كانت الأنواع غير متطابقة، كما في المثال التالي، فسنحصل على خطأ:

اسم الملف: src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "six" };

    println!("The value of number is: {number}");
}

عندما نحاول تصريف (compile) هذا الكود، سنحصل على خطأ. أذرع if و else لها أنواع قيم غير متوافقة، ويشير Rust بالضبط إلى مكان العثور على المشكلة في البرنامج:

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: `if` and `else` have incompatible types
 --> src/main.rs:4:44
  |
4 |     let number = if condition { 5 } else { "six" };
  |                                 -          ^^^^^ expected integer, found `&str`
  |                                 |
  |                                 expected because of this

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

يتم تقييم التعبير في كتلة if إلى عدد صحيح، ويتم تقييم التعبير في كتلة else إلى سلسلة نصية (string). لن يعمل هذا، لأن المتغيرات يجب أن يكون لها نوع واحد، ويحتاج Rust إلى معرفة نوع المتغير number بشكل قاطع في وقت التصريف (compile time). تتيح معرفة نوع number للمصرف (compiler) التحقق من أن النوع صالح في كل مكان نستخدم فيه number. لن يتمكن Rust من القيام بذلك إذا تم تحديد نوع number فقط في وقت التشغيل (runtime)؛ سيكون المصرف أكثر تعقيداً وسيقدم ضمانات أقل حول الكود إذا كان عليه تتبع أنواع افتراضية متعددة لأي متغير.

التكرار باستخدام الحلقات (Repetition with Loops)

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

يحتوي Rust على ثلاثة أنواع من الحلقات: loop و while و for. دعونا نجرب كل واحدة منها.

تكرار الكود باستخدام loop

تخبر الكلمة المفتاحية loop لغة Rust بتنفيذ كتلة من الكود مراراً وتكراراً إما إلى الأبد أو حتى تخبرها صراحة بالتوقف.

كمثال، قم بتغيير ملف src/main.rs في دليل loops الخاص بك ليبدو كالتالي:

اسم الملف: src/main.rs

fn main() {
    loop {
        println!("again!");
    }
}

عندما نشغل هذا البرنامج، سنرى كلمة again! تُطبع مراراً وتكراراً بشكل مستمر حتى نوقف البرنامج يدوياً. تدعم معظم واجهات الأوامر (terminals) اختصار لوحة المفاتيح ctrl-C لمقاطعة برنامج عالق في حلقة مستمرة. جرب ذلك:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/loops`
again!
again!
again!
again!
^Cagain!

يمثل الرمز ^C المكان الذي ضغطت فيه على ctrl-C.

قد ترى أو لا ترى كلمة again! مطبوعة بعد ^C ، اعتماداً على مكان الكود في الحلقة عندما تلقى إشارة المقاطعة.

لحسن الحظ، يوفر Rust أيضاً طريقة للخروج من الحلقة باستخدام الكود. يمكنك وضع الكلمة المفتاحية break داخل الحلقة لإخبار البرنامج متى يتوقف عن تنفيذ الحلقة. تذكر أننا فعلنا ذلك في لعبة التخمين في قسم “الخروج بعد التخمين الصحيح” من الفصل الثاني للخروج من البرنامج عندما فاز المستخدم باللعبة من خلال تخمين الرقم الصحيح.

استخدمنا أيضاً continue في لعبة التخمين، والتي تخبر البرنامج في الحلقة بتخطي أي كود متبقٍ في هذه الدورة (iteration) من الحلقة والانتقال إلى الدورة التالية.

إرجاع القيم من الحلقات

أحد استخدامات loop هو إعادة محاولة عملية تعرف أنها قد تفشل، مثل التحقق مما إذا كان الخيط (thread) قد أكمل مهمته. قد تحتاج أيضاً إلى تمرير نتيجة تلك العملية خارج الحلقة إلى بقية الكود الخاص بك. للقيام بذلك، يمكنك إضافة القيمة التي تريد إرجاعها بعد تعبير break الذي تستخدمه لإيقاف الحلقة؛ سيتم إرجاع تلك القيمة خارج الحلقة حتى تتمكن من استخدامها، كما هو موضح هنا:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
        }
    };

    println!("The result is {result}");
}

قبل الحلقة، نعلن عن متغير باسم counter ونقوم بتهيئته بالقيمة 0. ثم نعلن عن متغير باسم result للاحتفاظ بالقيمة المرجعة من الحلقة. في كل دورة من دورات الحلقة، نضيف 1 إلى المتغير counter ، ثم نتحقق مما إذا كان counter يساوي 10. عندما يكون كذلك، نستخدم الكلمة المفتاحية break مع القيمة counter * 2. بعد الحلقة، نستخدم فاصلة منقوطة لإنهاء العبارة التي تعين القيمة لـ result. أخيراً، نطبع القيمة في result ، وهي في هذه الحالة 20.

يمكنك أيضاً استخدام return من داخل الحلقة. بينما يخرج break فقط من الحلقة الحالية، فإن return يخرج دائماً من الدالة الحالية.

إزالة الغموض باستخدام تسميات الحلقات (Loop Labels)

إذا كان لديك حلقات داخل حلقات، فإن break و continue ينطبقان على الحلقة الداخلية في تلك النقطة. يمكنك اختيارياً تحديد تسمية للحلقة (loop label) على حلقة يمكنك استخدامها بعد ذلك مع break أو continue لتحديد أن تلك الكلمات المفتاحية تنطبق على الحلقة المسماة بدلاً من الحلقة الداخلية. يجب أن تبدأ تسميات الحلقات بفاصلة علوية واحدة. إليك مثال مع حلقتين متداخلتين:

fn main() {
    let mut count = 0;
    'counting_up: loop {
        println!("count = {count}");
        let mut remaining = 10;

        loop {
            println!("remaining = {remaining}");
            if remaining == 9 {
                break;
            }
            if count == 2 {
                break 'counting_up;
            }
            remaining -= 1;
        }

        count += 1;
    }
    println!("End count = {count}");
}

تقوم الحلقة الداخلية بدون تسمية بالعد التنازلي من 10 إلى 9. أول break لا يحدد تسمية سيخرج من الحلقة الداخلية فقط. أما عبارة break 'counting_up; فستخرج من الحلقة الخارجية. يطبع هذا الكود:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/loops`
count = 0
remaining = 10
remaining = 9
count = 1
remaining = 10
remaining = 9
count = 2
remaining = 10
End count = 2

تبسيط الحلقات الشرطية باستخدام while

غالباً ما يحتاج البرنامج إلى تقييم شرط داخل حلقة. طالما أن الشرط true ، تعمل الحلقة. عندما يتوقف الشرط عن كونه true ، يستدعي البرنامج break ، مما يوقف الحلقة. من الممكن تنفيذ سلوك مثل هذا باستخدام مزيج من loop و if و else و break ؛ يمكنك تجربة ذلك الآن في برنامج، إذا أردت. ومع ذلك، فإن هذا النمط شائع جداً لدرجة أن Rust لديها بنية لغة مدمجة له، تسمى حلقة while. في القائمة 3-3، نستخدم while لتدوير البرنامج ثلاث مرات، والعد التنازلي في كل مرة، ثم بعد الحلقة، لطباعة رسالة والخروج.

fn main() {
    let mut number = 3;

    while number != 0 {
        println!("{number}!");

        number -= 1;
    }

    println!("LIFTOFF!!!");
}

تزيل هذه البنية الكثير من التداخل (nesting) الذي سيكون ضرورياً إذا استخدمت loop و if و else و break ، وهي أكثر وضوحاً. طالما يتم تقييم الشرط إلى true ، يتم تشغيل الكود؛ وإلا، فإنه يخرج من الحلقة.

التكرار عبر مجموعة باستخدام for

يمكنك اختيار استخدام بنية while للتكرار عبر عناصر مجموعة (collection)، مثل المصفوفة (array). على سبيل المثال، تقوم الحلقة في القائمة 3-4 بطباعة كل عنصر في المصفوفة a.

fn main() {
    let a = [10, 20, 30, 40, 50];
    let mut index = 0;

    while index < 5 {
        println!("the value is: {}", a[index]);

        index += 1;
    }
}

هنا، يقوم الكود بالعد التصاعدي عبر العناصر في المصفوفة. يبدأ من الفهرس (index) 0 ثم يدور حتى يصل إلى الفهرس النهائي في المصفوفة (أي عندما لا يعود index < 5 صحيحاً). سيؤدي تشغيل هذا الكود إلى طباعة كل عنصر في المصفوفة:

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/loops`
the value is: 10
the value is: 20
the value is: 30
the value is: 40
the value is: 50

تظهر جميع قيم المصفوفة الخمس في واجهة الأوامر، كما هو متوقع. على الرغم من أن index سيصل إلى قيمة 5 في مرحلة ما، إلا أن الحلقة تتوقف عن التنفيذ قبل محاولة جلب قيمة سادسة من المصفوفة.

ومع ذلك، فإن هذا النهج عرضة للأخطاء؛ فقد نتسبب في توقف البرنامج بشكل مفاجئ (panic) إذا كانت قيمة الفهرس أو شرط الاختبار غير صحيحين. على سبيل المثال، إذا قمت بتغيير تعريف المصفوفة a لتتكون من أربعة عناصر ولكنك نسيت تحديث الشرط إلى while index < 4 ، فسيحدث panic للكود. كما أنه بطيء، لأن المصرف يضيف كوداً في وقت التشغيل لإجراء الفحص الشرطي لما إذا كان الفهرس ضمن حدود المصفوفة في كل دورة عبر الحلقة.

كبديل أكثر إيجازاً، يمكنك استخدام حلقة for وتنفيذ بعض الأكواد لكل عنصر في المجموعة. تبدو حلقة for مثل الكود الموجود في القائمة 3-5.

fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("the value is: {element}");
    }
}

عندما نشغل هذا الكود، سنرى نفس المخرجات كما في القائمة 3-4. والأهم من ذلك، أننا زدنا الآن من سلامة الكود وقضينا على فرصة حدوث أخطاء برمجية قد تنتج عن تجاوز نهاية المصفوفة أو عدم الذهاب بعيداً بما يكفي وفقدان بعض العناصر. يمكن أن يكون كود الآلة (machine code) الناتج عن حلقات for أكثر كفاءة أيضاً لأن الفهرس لا يحتاج إلى مقارنته بطول المصفوفة في كل دورة.

باستخدام حلقة for ، لن تحتاج إلى تذكر تغيير أي كود آخر إذا قمت بتغيير عدد القيم في المصفوفة، كما تفعل مع الطريقة المستخدمة في القائمة 3-4.

إن سلامة وإيجاز حلقات for تجعلها بنية الحلقات الأكثر استخداماً في Rust. حتى في المواقف التي تريد فيها تشغيل بعض الأكواد عدداً معيناً من المرات، كما في مثال العد التنازلي الذي استخدم حلقة while في القائمة 3-3، فإن معظم مبرمجي رست (Rustaceans) سيستخدمون حلقة for. الطريقة للقيام بذلك هي استخدام النطاق (Range)، الذي توفره المكتبة القياسية، والذي يولد جميع الأرقام بالتسلسل بدءاً من رقم واحد وانتهاءً قبل رقم آخر.

إليك كيف سيبدو العد التنازلي باستخدام حلقة for وطريقة أخرى لم نتحدث عنها بعد، وهي rev ، لعكس النطاق:

اسم الملف: src/main.rs

fn main() {
    for number in (1..4).rev() {
        println!("{number}!");
    }
    println!("LIFTOFF!!!");
}

هذا الكود أجمل قليلاً، أليس كذلك؟

ملخص (Summary)

لقد فعلتها! كان هذا فصلاً كبيراً: لقد تعلمت عن المتغيرات، وأنواع البيانات البسيطة والمركبة، والدوال، والتعليقات، وتعبيرات if ، والحلقات! للتدرب على المفاهيم التي تمت مناقشتها في هذا الفصل، حاول بناء برامج للقيام بما يلي:

• تحويل درجات الحرارة بين فهرنهايت وسيلسيوس.
• توليد رقم فيبوناتشي ذو الترتيب n.
• طباعة كلمات أغنية عيد الميلاد “The Twelve Days of Christmas” ، مع الاستفادة من التكرار في الأغنية.

عندما تكون مستعداً للمضي قدماً، سنتحدث عن مفهوم في Rust لا يوجد عادةً في لغات البرمجة الأخرى: الملكية (ownership).

فهم Ownership

تُعدّ Ownership (الملكية) الميزة الأبرز في لغة Rust، ولها آثار عميقة على بقية مكونات اللغة.

فهي تُمكّن Rust من ضمان سلامة الذاكرة دون الحاجة إلى جامع قمامة، لذا من المهم فهم كيفية عمل Ownership .

في هذا الفصل، سنتناول Ownership بالإضافة إلى العديد من الميزات ذات الصلة:

borrowing (الاستعارة) ، slices (الشرائح) ، وكيفية تنظيم Rust للبيانات في الذاكرة.

ما هي الملكية؟ (What is Ownership?)

ما هي الملكية (Ownership)؟

الملكية (Ownership) هي مجموعة من القواعد التي تحكم كيفية إدارة برنامج Rust للذاكرة. يجب على جميع البرامج إدارة الطريقة التي تستخدم بها ذاكرة الكمبيوتر أثناء التشغيل. تحتوي بعض اللغات على تجميع البيانات المهملة (Garbage Collection - GC) الذي يبحث بانتظام عن الذاكرة التي لم تعد مستخدمة أثناء تشغيل البرنامج؛ وفي لغات أخرى، يجب على المبرمج تخصيص الذاكرة وتحريرها (allocate and free) بشكل صريح. تستخدم Rust نهجًا ثالثًا: تتم إدارة الذاكرة من خلال نظام Ownership مع مجموعة من القواعد التي يتحقق منها المترجم (compiler). إذا تم انتهاك أي من القواعد، فلن يتم تجميع البرنامج. لا توجد أي من ميزات Ownership تبطئ برنامجك أثناء تشغيله.

نظرًا لأن Ownership مفهوم جديد للعديد من المبرمجين، فإنه يستغرق بعض الوقت للاعتياد عليه. الخبر السار هو أنه كلما أصبحت أكثر خبرة في Rust وقواعد نظام Ownership، كلما وجدت أنه من الأسهل تطوير كود آمن وفعال بشكل طبيعي. استمر في المحاولة!

عندما تفهم Ownership، سيكون لديك أساس متين لفهم الميزات التي تجعل Rust فريدة من نوعها. في هذا الفصل، ستتعلم Ownership من خلال العمل على بعض الأمثلة التي تركز على بنية بيانات شائعة جدًا: السلاسل النصية (strings).

المكدس (Stack) والكومة (Heap)

لا تتطلب منك العديد من لغات البرمجة التفكير في الـ Stack والـ Heap في كثير من الأحيان. ولكن في لغة برمجة أنظمة مثل Rust، يؤثر ما إذا كانت القيمة موجودة على الـ Stack أو الـ Heap على كيفية تصرف اللغة ولماذا يجب عليك اتخاذ قرارات معينة. سيتم وصف أجزاء من Ownership فيما يتعلق بالـ Stack والـ Heap لاحقًا في هذا الفصل، لذا إليك شرح موجز كتحضير.

كل من الـ Stack والـ Heap هما جزءان من الذاكرة المتاحة للكود الخاص بك لاستخدامها في وقت التشغيل (runtime)، ولكنهما منظمان بطرق مختلفة. يخزن الـ Stack القيم بالترتيب الذي يحصل عليها به ويزيل القيم بالترتيب المعاكس. يشار إلى هذا باسم آخر ما يدخل، أول ما يخرج (Last In, First Out - LIFO). فكر في كومة من الأطباق: عندما تضيف المزيد من الأطباق، تضعها فوق الكومة، وعندما تحتاج إلى طبق، تأخذ واحدًا من الأعلى. لن ينجح إضافة أو إزالة الأطباق من المنتصف أو الأسفل! تسمى إضافة البيانات الدفع إلى الـ Stack (pushing onto the Stack)، وتسمى إزالة البيانات السحب من الـ Stack (popping off the Stack). يجب أن يكون لجميع البيانات المخزنة على الـ Stack حجم معروف وثابت. يجب تخزين البيانات ذات الحجم غير المعروف في وقت التجميع (compile time) أو الحجم الذي قد يتغير على الـ Heap بدلاً من ذلك.

الـ Heap أقل تنظيمًا: عندما تضع بيانات على الـ Heap، فإنك تطلب قدرًا معينًا من المساحة. يجد مخصص الذاكرة (memory allocator) بقعة فارغة في الـ Heap تكون كبيرة بما يكفي، ويضع علامة عليها بأنها قيد الاستخدام، ويعيد مؤشر (pointer)، وهو عنوان ذلك الموقع. تسمى هذه العملية التخصيص على الـ Heap (allocating on the Heap) ويتم اختصارها أحيانًا على أنها مجرد تخصيص (allocating) (لا يعتبر دفع القيم إلى الـ Stack تخصيصًا). نظرًا لأن الـ pointer إلى الـ Heap له حجم معروف وثابت، يمكنك تخزين الـ pointer على الـ Stack، ولكن عندما تريد البيانات الفعلية، يجب عليك اتباع الـ pointer. فكر في الجلوس في مطعم. عندما تدخل، تذكر عدد الأشخاص في مجموعتك، ويجد المضيف طاولة فارغة تناسب الجميع ويقودك إليها. إذا تأخر شخص ما في مجموعتك، يمكنه أن يسأل عن مكان جلوسك للعثور عليك.

الدفع إلى الـ Stack أسرع من الـ allocating على الـ Heap لأن الـ allocator لا يضطر أبدًا إلى البحث عن مكان لتخزين البيانات الجديدة؛ هذا الموقع دائمًا في الجزء العلوي من الـ Stack. بالمقارنة، يتطلب تخصيص مساحة على الـ Heap مزيدًا من العمل لأن الـ allocator يجب أن يجد أولاً مساحة كبيرة بما يكفي لاحتواء البيانات ثم يقوم بحفظ السجلات للتحضير للتخصيص التالي.

يعد الوصول إلى البيانات في الـ Heap أبطأ بشكل عام من الوصول إلى البيانات على الـ Stack لأنه يجب عليك اتباع pointer للوصول إليها. تكون المعالجات (processors) المعاصرة أسرع إذا قفزت حول الذاكرة بشكل أقل. استمرارًا للتشبيه، فكر في خادم في مطعم يأخذ طلبات من العديد من الطاولات. الأكثر كفاءة هو الحصول على جميع الطلبات على طاولة واحدة قبل الانتقال إلى الطاولة التالية. إن أخذ طلب من الطاولة A، ثم طلب من الطاولة B، ثم واحد من A مرة أخرى، ثم واحد من B مرة أخرى سيكون عملية أبطأ بكثير. بنفس الطريقة، يمكن للمعالج عادةً القيام بعمله بشكل أفضل إذا كان يعمل على بيانات قريبة من البيانات الأخرى (كما هو الحال في الـ Stack) بدلاً من أن تكون بعيدة (كما يمكن أن تكون في الـ Heap).

عندما يستدعي الكود الخاص بك دالة، يتم دفع القيم التي تم تمريرها إلى الدالة (بما في ذلك، من المحتمل، pointers إلى البيانات على الـ Heap) والمتغيرات المحلية للدالة إلى الـ Stack. عندما تنتهي الدالة، يتم سحب تلك القيم من الـ Stack.

تتبع الأجزاء التي تستخدم أي بيانات على الـ Heap، وتقليل كمية البيانات المكررة على الـ Heap، وتنظيف البيانات غير المستخدمة على الـ Heap حتى لا تنفد المساحة، كلها مشاكل يعالجها Ownership. بمجرد أن تفهم Ownership، لن تحتاج إلى التفكير في الـ Stack والـ Heap في كثير من الأحيان. ولكن معرفة أن الغرض الرئيسي من Ownership هو إدارة بيانات الـ Heap يمكن أن يساعد في تفسير سبب عمله بالطريقة التي يعمل بها.

قواعد الملكية (Ownership Rules)

أولاً، دعونا نلقي نظرة على قواعد Ownership. ضع هذه القواعد في الاعتبار بينما نعمل على الأمثلة التي توضحها:

• كل قيمة في Rust لها مالك (owner).
• يمكن أن يكون هناك owner واحد فقط في كل مرة.
• عندما يخرج الـ owner من النطاق (scope)، سيتم إسقاط (dropped) القيمة.

نطاق المتغير (Variable Scope)

الآن بعد أن تجاوزنا بناء جملة Rust الأساسي، لن ندرج كل كود fn main() { في الأمثلة، لذا إذا كنت تتابع، فتأكد من وضع الأمثلة التالية داخل دالة main يدويًا. ونتيجة لذلك، ستكون أمثلتنا أكثر إيجازًا، مما يسمح لنا بالتركيز على التفاصيل الفعلية بدلاً من الكود النمطي (boilerplate code).

كمثال أول على Ownership، سننظر إلى الـ scope لبعض المتغيرات. الـ scope هو النطاق داخل برنامج يكون فيه العنصر صالحًا. خذ المتغير التالي:

#![allow(unused)]
fn main() {
let s = "hello";
}

يشير المتغير s إلى حرفي السلسلة النصية (string literal)، حيث يتم ترميز قيمة الـ string مباشرة في نص برنامجنا. يكون المتغير صالحًا من النقطة التي يتم فيها الإعلان عنه حتى نهاية الـ scope الحالي. تُظهر القائمة 4-1 برنامجًا يحتوي على تعليقات توضيحية تشير إلى المكان الذي سيكون فيه المتغير s صالحًا.

fn main() {
    {                      // s is not valid here, since it's not yet declared
        let s = "hello";   // s is valid from this point forward

        // do stuff with s
    }                      // this scope is now over, and s is no longer valid
}

بمعنى آخر، هناك نقطتان زمنيتان مهمتان هنا:

• عندما يدخل s إلى الـ scope، يكون صالحًا.
• يظل صالحًا حتى يخرج من الـ scope.

في هذه المرحلة، العلاقة بين الـ scopes ومتى تكون المتغيرات صالحة تشبه تلك الموجودة في لغات البرمجة الأخرى. الآن سنبني على هذا الفهم من خلال تقديم النوع String.

النوع String

لتوضيح قواعد Ownership، نحتاج إلى نوع بيانات أكثر تعقيدًا من تلك التي تناولناها في قسم “أنواع البيانات” من الفصل 3. الأنواع التي تم تناولها سابقًا ذات حجم معروف، ويمكن تخزينها على الـ Stack وسحبها من الـ Stack عند انتهاء الـ scope الخاص بها، ويمكن نسخها بسرعة وبشكل بسيط لإنشاء مثيل (instance) جديد ومستقل إذا احتاج جزء آخر من الكود إلى استخدام نفس القيمة في scope مختلف. لكننا نريد أن ننظر إلى البيانات المخزنة على الـ Heap ونستكشف كيف تعرف Rust متى يجب تنظيف تلك البيانات، ويعد النوع String مثالًا رائعًا.

سنركز على أجزاء String المتعلقة بـ Ownership. تنطبق هذه الجوانب أيضًا على أنواع البيانات المعقدة الأخرى، سواء تم توفيرها بواسطة المكتبة القياسية (standard library) أو تم إنشاؤها بواسطتك. سنناقش جوانب String غير المتعلقة بـ Ownership في الفصل 8.

لقد رأينا بالفعل string literals، حيث يتم ترميز قيمة string مباشرة في برنامجنا. تعد string literals مريحة، لكنها ليست مناسبة لكل موقف قد نرغب في استخدام نص فيه. أحد الأسباب هو أنها غير قابلة للتغيير (immutable). سبب آخر هو أنه لا يمكن معرفة كل قيمة string عندما نكتب الكود الخاص بنا: على سبيل المثال، ماذا لو أردنا أخذ مدخلات المستخدم (user input) وتخزينها؟ لهذه المواقف، لدى Rust النوع String. يدير هذا النوع البيانات المخصصة على الـ Heap وعلى هذا النحو يمكنه تخزين كمية من النص غير معروفة لنا في compile time. يمكنك إنشاء String من string literal باستخدام الدالة from، على النحو التالي:

#![allow(unused)]
fn main() {
let s = String::from("hello");
}

يسمح لنا عامل التشغيل النقطتين المزدوجتين :: بتسمية هذه الدالة from المعينة تحت النوع String بدلاً من استخدام نوع من الأسماء مثل string_from. سنناقش بناء الجملة هذا أكثر في قسم “الدوال” من الفصل 5، وعندما نتحدث عن التسمية باستخدام الوحدات (modules) في “المسارات للإشارة إلى عنصر في شجرة الوحدة” في الفصل 7.

هذا النوع من الـ string يمكن أن يكون قابلاً للتغيير (mutable):

fn main() {
    let mut s = String::from("hello");

    s.push_str(", world!"); // push_str() appends a literal to a String

    println!("{s}"); // this will print `hello, world!`
}

إذن، ما هو الفرق هنا؟ لماذا يمكن تغيير String ولكن string literals لا يمكن تغييرها؟ يكمن الاختلاف في كيفية تعامل هذين النوعين مع الذاكرة.

الذاكرة والتخصيص (Memory and Allocation)

في حالة string literal، نعرف المحتويات في compile time، لذلك يتم ترميز النص مباشرة في الملف التنفيذي النهائي. هذا هو السبب في أن string literals سريعة وفعالة. لكن هذه الخصائص تأتي فقط من عدم قابلية تغيير string literal. لسوء الحظ، لا يمكننا وضع كتلة من الذاكرة في الملف الثنائي (binary) لكل جزء من النص يكون حجمه غير معروف في compile time وقد يتغير حجمه أثناء تشغيل البرنامج.

باستخدام النوع String، لدعم جزء نصي قابل للتغيير والنمو، نحتاج إلى تخصيص (allocate) قدر من الذاكرة على الـ Heap، غير معروف في compile time، لاحتواء المحتويات. هذا يعني:

• يجب طلب الذاكرة من memory allocator في وقت التشغيل (runtime).
• نحتاج إلى طريقة لإعادة هذه الذاكرة إلى الـ allocator عندما ننتهي من String الخاص بنا.

يتم تنفيذ الجزء الأول بواسطتنا: عندما نستدعي String::from، يطلب تطبيقه الذاكرة التي يحتاجها. هذا عالمي إلى حد كبير في لغات البرمجة.

ومع ذلك، فإن الجزء الثاني مختلف. في اللغات التي تحتوي على GC (Garbage Collector)، يتتبع الـ GC وينظف الذاكرة التي لم تعد مستخدمة، ولا نحتاج إلى التفكير في الأمر. في معظم اللغات التي لا تحتوي على GC، تقع على عاتقنا مسؤولية تحديد متى لم تعد الذاكرة مستخدمة واستدعاء الكود لتحريرها (free) بشكل صريح، تمامًا كما فعلنا لطلبها. لطالما كانت القيام بذلك بشكل صحيح مشكلة برمجة صعبة تاريخيًا. إذا نسينا، فسنهدر الذاكرة. إذا فعلنا ذلك في وقت مبكر جدًا، فسيكون لدينا متغير غير صالح. إذا فعلنا ذلك مرتين، فهذا bug أيضًا. نحتاج إلى إقران allocate واحد بالضبط مع free واحد بالضبط.

تأخذ Rust نهجًا مختلفًا: الـ owner. دعونا نعود إلى مثال string من القائمة 4-1 باستخدام String بدلاً من string literal:

fn main() {
    {
        let s = String::from("hello"); // s is valid from this point forward

        // do stuff with s
    }                                  // this scope is now over, and s is no
                                       // longer valid
}

هناك نقطة طبيعية يمكننا عندها إعادة الذاكرة التي يحتاجها String الخاص بنا إلى الـ allocator: عندما يخرج s من الـ scope. عندما يخرج متغير من الـ scope، تستدعي Rust دالة خاصة لنا. تسمى هذه الدالة drop، وهي المكان الذي يمكن لمؤلف String أن يضع فيه الكود لإعادة الذاكرة. تستدعي Rust الدالة drop تلقائيًا عند القوس المتعرج الختامي.

ملاحظة: في C++، يسمى هذا النمط من إلغاء تخصيص الموارد في نهاية عمر العنصر أحيانًا اكتساب الموارد هو تهيئة (Resource Acquisition Is Initialization - RAII). ستكون الدالة drop في Rust مألوفة لك إذا كنت قد استخدمت أنماط RAII.

لهذا النمط تأثير عميق على طريقة كتابة كود Rust. قد يبدو بسيطًا الآن، ولكن سلوك الكود يمكن أن يكون غير متوقع في مواقف أكثر تعقيدًا عندما نريد أن تستخدم متغيرات متعددة البيانات التي خصصناها على الـ Heap. دعونا نستكشف بعضًا من هذه المواقف الآن.

تفاعل المتغيرات والبيانات مع النقل (Move)

يمكن أن تتفاعل المتغيرات المتعددة مع نفس البيانات بطرق مختلفة في Rust. تُظهر القائمة 4-2 مثالًا باستخدام عدد صحيح (integer).

fn main() {
    let x = 5;
    let y = x;
}

يمكننا على الأرجح تخمين ما يفعله هذا: “ربط القيمة 5 بـ x؛ ثم، عمل نسخة من القيمة في x وربطها بـ y.” لدينا الآن متغيران، x و y، وكلاهما يساوي 5. هذا هو بالفعل ما يحدث، لأن integers هي قيم بسيطة ذات حجم معروف وثابت، ويتم دفع هاتين القيمتين 5 إلى الـ Stack.

الآن دعونا نلقي نظرة على نسخة String:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;
}

يبدو هذا مشابهًا جدًا، لذلك قد نفترض أن طريقة عمله ستكون هي نفسها: أي أن السطر الثاني سيقوم بعمل نسخة من القيمة في s1 وربطها بـ s2. لكن هذا ليس ما يحدث تمامًا.

ألق نظرة على الشكل 4-1 لترى ما يحدث لـ String تحت الغطاء. يتكون String من ثلاثة أجزاء، موضحة على اليسار: pointer إلى الذاكرة التي تحتوي على محتويات الـ string، وطول (length)، وسعة (capacity). يتم تخزين هذه المجموعة من البيانات على الـ Stack. على اليمين توجد الذاكرة على الـ Heap التي تحتوي على المحتويات.

الشكل 4-1: تمثيل String في الذاكرة الذي يحمل القيمة "hello" المرتبطة بـ s1

الـ length هو مقدار الذاكرة، بالبايت، التي تستخدمها محتويات String حاليًا. الـ capacity هي إجمالي كمية الذاكرة، بالبايت، التي تلقاها String من الـ allocator. الفرق بين الـ length والـ capacity مهم، ولكن ليس في هذا السياق، لذلك في الوقت الحالي، لا بأس بتجاهل الـ capacity.

عندما نخصص s1 لـ s2، يتم نسخ بيانات String، مما يعني أننا ننسخ الـ pointer والـ length والـ capacity الموجودة على الـ Stack. نحن لا ننسخ البيانات الموجودة على الـ Heap التي يشير إليها الـ pointer. بمعنى آخر، يبدو تمثيل البيانات في الذاكرة كما في الشكل 4-2.

الشكل 4-2: تمثيل المتغير s2 في الذاكرة الذي يحتوي على نسخة من الـ pointer والـ length والـ capacity لـ s1

التمثيل لا يبدو مثل الشكل 4-3، وهو ما ستبدو عليه الذاكرة إذا نسخت Rust بيانات الـ Heap أيضًا. إذا فعلت Rust ذلك، فقد تكون عملية s2 = s1 مكلفة للغاية من حيث أداء وقت التشغيل إذا كانت البيانات الموجودة على الـ Heap كبيرة.

الشكل 4-3: احتمال آخر لما قد تفعله s2 = s1 إذا نسخت Rust بيانات الـ Heap أيضًا

في وقت سابق، قلنا أنه عندما يخرج متغير من الـ scope، تستدعي Rust تلقائيًا الدالة drop وتنظف ذاكرة الـ Heap لذلك المتغير. لكن الشكل 4-2 يظهر أن كلا الـ pointers يشيران إلى نفس الموقع. هذه مشكلة: عندما يخرج s2 و s1 من الـ scope، سيحاول كلاهما تحرير نفس الذاكرة. يُعرف هذا باسم خطأ التحرير المزدوج (double free) وهو أحد أخطاء سلامة الذاكرة (memory safety bugs) التي ذكرناها سابقًا. يمكن أن يؤدي تحرير الذاكرة مرتين إلى تلف الذاكرة (memory corruption)، مما قد يؤدي إلى ثغرات أمنية (security vulnerabilities).

لضمان memory safety، بعد السطر let s2 = s1;، تعتبر Rust أن s1 لم يعد صالحًا. لذلك، لا تحتاج Rust إلى تحرير أي شيء عندما يخرج s1 من الـ scope. تحقق مما يحدث عندما تحاول استخدام s1 بعد إنشاء s2؛ لن ينجح:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;

    println!("{s1}, world!");
}

ستحصل على خطأ مثل هذا لأن Rust تمنعك من استخدام المرجع (reference) الذي تم إبطاله:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:16
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{s1}, world!");
  |                ^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                ++++++++

For more information about this error, try `rustc --explain E0382`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

إذا كنت قد سمعت مصطلحي النسخ السطحي (shallow copy) و النسخ العميق (deep copy) أثناء العمل مع لغات أخرى، فمن المحتمل أن يبدو مفهوم نسخ الـ pointer والـ length والـ capacity دون نسخ البيانات وكأنه عمل shallow copy. ولكن نظرًا لأن Rust تبطل أيضًا المتغير الأول، فبدلاً من تسميته shallow copy، فإنه يُعرف باسم النقل (move). في هذا المثال، نقول إن s1 تم نقله إلى s2. لذا، فإن ما يحدث بالفعل موضح في الشكل 4-4.

الشكل 4-4: تمثيل الذاكرة بعد إبطال s1

هذا يحل مشكلتنا! مع صلاحية s2 فقط، عندما يخرج من الـ scope، سيقوم وحده بتحرير الذاكرة، ونكون قد انتهينا.

بالإضافة إلى ذلك، هناك خيار تصميم ضمني بهذا: لن تقوم Rust أبدًا بإنشاء نسخ “deep” لبياناتك تلقائيًا. لذلك، يمكن افتراض أن أي نسخ تلقائي غير مكلف من حيث أداء وقت التشغيل.

النطاق والتعيين (Scope and Assignment)

العكس صحيح بالنسبة للعلاقة بين الـ scoping و Ownership والذاكرة التي يتم تحريرها عبر الدالة drop أيضًا. عندما تقوم بتعيين قيمة جديدة تمامًا لمتغير موجود، ستستدعي Rust الدالة drop وتحرر ذاكرة القيمة الأصلية على الفور. ضع في اعتبارك هذا الكود، على سبيل المثال:

fn main() {
    let mut s = String::from("hello");
    s = String::from("ahoy");

    println!("{s}, world!");
}

نعلن في البداية عن متغير s ونربطه بـ String بالقيمة "hello". ثم، نقوم على الفور بإنشاء String جديد بالقيمة "ahoy" ونعينه لـ s. في هذه المرحلة، لا يوجد شيء يشير إلى القيمة الأصلية على الـ Heap على الإطلاق. يوضح الشكل 4-5 بيانات الـ Stack والـ Heap الآن:

الشكل 4-5: تمثيل الذاكرة بعد استبدال القيمة الأولية بالكامل

وبالتالي، تخرج الـ string الأصلية من الـ scope على الفور. ستقوم Rust بتشغيل الدالة drop عليها وسيتم تحرير ذاكرتها على الفور. عندما نطبع القيمة في النهاية، ستكون "ahoy, world!".

تفاعل المتغيرات والبيانات مع الاستنساخ (Clone)

إذا أردنا عمل deep copy لبيانات الـ Heap لـ String، وليس فقط بيانات الـ Stack، فيمكننا استخدام دالة شائعة تسمى clone. سنناقش بناء جملة الـ methods في الفصل 5، ولكن نظرًا لأن الـ methods هي ميزة شائعة في العديد من لغات البرمجة، فمن المحتمل أنك رأيتها من قبل.

إليك مثال على دالة clone قيد التنفيذ:

fn main() {
    let s1 = String::from("hello");
    let s2 = s1.clone();

    println!("s1 = {s1}, s2 = {s2}");
}

يعمل هذا بشكل جيد وينتج صراحة السلوك الموضح في الشكل 4-3، حيث يتم نسخ بيانات الـ Heap.

عندما ترى استدعاء لـ clone، فأنت تعلم أنه يتم تنفيذ بعض الكود التعسفي وأن هذا الكود قد يكون مكلفًا. إنه مؤشر مرئي على أن شيئًا مختلفًا يحدث.

بيانات الـ Stack فقط: النسخ (Copy)

هناك تجعيدة أخرى لم نتحدث عنها بعد. هذا الكود الذي يستخدم integers - والذي تم عرض جزء منه في القائمة 4-2 - يعمل وصالح:

fn main() {
    let x = 5;
    let y = x;

    println!("x = {x}, y = {y}");
}

لكن هذا الكود يبدو وكأنه يتناقض مع ما تعلمناه للتو: ليس لدينا استدعاء لـ clone، لكن x لا يزال صالحًا ولم يتم نقله إلى y.

السبب هو أن الأنواع مثل integers التي لها حجم معروف في compile time يتم تخزينها بالكامل على الـ Stack، لذا فإن نسخ القيم الفعلية سريعة التنفيذ. هذا يعني أنه لا يوجد سبب يدعونا إلى منع x من أن يكون صالحًا بعد إنشاء المتغير y. بمعنى آخر، لا يوجد فرق بين deep copy و shallow copy هنا، لذا فإن استدعاء clone لن يفعل أي شيء مختلف عن الـ shallow copy المعتاد، ويمكننا حذفه.

لدى Rust تعليق توضيحي خاص يسمى سمة النسخ (Copy trait) يمكننا وضعه على الأنواع المخزنة على الـ Stack، كما هو الحال مع integers (سنتحدث أكثر عن الـ traits في الفصل 10). إذا طبق نوع ما الـ Copy trait، فإن المتغيرات التي تستخدمه لا يتم نقلها (move)، بل يتم نسخها بشكل بسيط، مما يجعلها لا تزال صالحة بعد التعيين لمتغير آخر.

لن تسمح لنا Rust بتعليق نوع بـ Copy إذا كان النوع، أو أي من أجزائه، قد طبق الـ Drop trait. إذا كان النوع يحتاج إلى حدوث شيء خاص عندما تخرج القيمة من الـ scope وأضفنا التعليق التوضيحي Copy إلى هذا النوع، فسنحصل على خطأ في compile time. لمعرفة كيفية إضافة التعليق التوضيحي Copy إلى نوعك لتطبيق الـ trait، راجع “السمات القابلة للاشتقاق” في الملحق ج.

إذن، ما هي الأنواع التي تطبق الـ Copy trait؟ يمكنك التحقق من توثيق النوع المحدد للتأكد، ولكن كقاعدة عامة، يمكن لأي مجموعة من القيم العددية (scalar values) البسيطة تطبيق Copy، ولا يمكن لأي شيء يتطلب تخصيصًا (allocation) أو هو شكل من أشكال المورد (resource) تطبيق Copy. فيما يلي بعض الأنواع التي تطبق Copy:

• جميع أنواع integers، مثل u32.
• النوع المنطقي (Boolean)، bool، بالقيمتين true و false.
• جميع أنواع الفاصلة العائمة (floating-point)، مثل f64.
• نوع الحرف (character)، char.
• الصفوف (Tuples)، إذا كانت تحتوي فقط على أنواع تطبق Copy أيضًا. على سبيل المثال، يطبق (i32, i32) الـ Copy، لكن (i32, String) لا يطبقه.

الملكية والدوال (Ownership and Functions)

آلية تمرير قيمة إلى دالة تشبه تلك الخاصة بتعيين قيمة لمتغير. سيؤدي تمرير متغير إلى دالة إلى move أو copy، تمامًا كما يفعل التعيين. تحتوي القائمة 4-3 على مثال مع بعض التعليقات التوضيحية التي توضح أين تدخل المتغيرات وتخرج من الـ scope.

fn main() {
    let s = String::from("hello");  // s comes into scope

    takes_ownership(s);             // s's value moves into the function...
                                    // ... and so is no longer valid here

    let x = 5;                      // x comes into scope

    makes_copy(x);                  // Because i32 implements the Copy trait,
                                    // x does NOT move into the function,
                                    // so it's okay to use x afterward.

} // Here, x goes out of scope, then s. However, because s's value was moved,
  // nothing special happens.

fn takes_ownership(some_string: String) { // some_string comes into scope
    println!("{some_string}");
} // Here, some_string goes out of scope and `drop` is called. The backing
  // memory is freed.

fn makes_copy(some_integer: i32) { // some_integer comes into scope
    println!("{some_integer}");
} // Here, some_integer goes out of scope. Nothing special happens.

إذا حاولنا استخدام s بعد الاستدعاء لـ takes_ownership، فستقوم Rust بإلقاء خطأ في compile time. تحمينا هذه الفحوصات الثابتة (static checks) من الأخطاء. حاول إضافة كود إلى main يستخدم s و x لترى أين يمكنك استخدامهما وأين تمنعك قواعد Ownership من القيام بذلك.

قيم الإرجاع والنطاق (Return Values and Scope)

يمكن أن تؤدي قيم الإرجاع أيضًا إلى نقل Ownership. تُظهر القائمة 4-4 مثالًا لدالة تُرجع بعض القيم، مع تعليقات توضيحية مماثلة لتلك الموجودة في القائمة 4-3.

fn main() {
    let s1 = gives_ownership();        // gives_ownership moves its return
                                       // value into s1

    let s2 = String::from("hello");    // s2 comes into scope

    let s3 = takes_and_gives_back(s2); // s2 is moved into
                                       // takes_and_gives_back, which also
                                       // moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing
  // happens. s1 goes out of scope and is dropped.

fn gives_ownership() -> String {       // gives_ownership will move its
                                       // return value into the function
                                       // that calls it

    let some_string = String::from("yours"); // some_string comes into scope

    some_string                        // some_string is returned and
                                       // moves out to the calling
                                       // function
}

// This function takes a String and returns a String.
fn takes_and_gives_back(a_string: String) -> String {
    // a_string comes into
    // scope

    a_string  // a_string is returned and moves out to the calling function
}

يتبع Ownership لمتغير نفس النمط في كل مرة: تعيين قيمة لمتغير آخر ينقلها (moves it). عندما يخرج متغير يتضمن بيانات على الـ Heap من الـ scope، سيتم تنظيف القيمة بواسطة drop ما لم يتم نقل Ownership للبيانات إلى متغير آخر.

بينما يعمل هذا، فإن أخذ Ownership ثم إرجاع Ownership مع كل دالة أمر ممل بعض الشيء. ماذا لو أردنا السماح لدالة باستخدام قيمة ولكن لا تأخذ Ownership؟ إنه أمر مزعج للغاية أن أي شيء نمرره يحتاج أيضًا إلى إعادته إذا أردنا استخدامه مرة أخرى، بالإضافة إلى أي بيانات ناتجة عن نص الدالة قد نرغب في إرجاعها أيضًا.

تسمح لنا Rust بإرجاع قيم متعددة باستخدام tuple، كما هو موضح في القائمة 4-5.

fn main() {
    let s1 = String::from("hello");

    let (s2, len) = calculate_length(s1);

    println!("The length of '{s2}' is {len}.");
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() returns the length of a String

    (s, length)
}

لكن هذا كثير جدًا من الإجراءات والكثير من العمل لمفهوم يجب أن يكون شائعًا. لحسن حظنا، لدى Rust ميزة لاستخدام قيمة دون نقل Ownership: الـ references.

المراجع والاستعارة (References and Borrowing)

المراجع والاستعارة (References and Borrowing)

المشكلة في كود الصفوف (tuple) في القائمة 4-5 هي أننا نضطر إلى إعادة String إلى الدالة المستدعية حتى نتمكن من الاستمرار في استخدام String بعد استدعاء calculate_length ، لأن String تم نقله (moved) إلى calculate_length. بدلاً من ذلك، يمكننا تقديم مرجع (reference) لقيمة String. المرجع يشبه المؤشر (pointer) في أنه عنوان يمكننا اتباعه للوصول إلى البيانات المخزنة في ذلك العنوان؛ تلك البيانات مملوكة لمتغير آخر. على عكس pointer، يضمن المرجع أن يشير إلى قيمة صالحة من نوع معين طوال فترة حياة ذلك المرجع.

إليك كيف يمكنك تعريف واستخدام دالة calculate_length التي تحتوي على مرجع لكائن كمعلمة (parameter) بدلاً من أخذ ملكية القيمة:

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

أولاً، لاحظ أن كل كود tuple في تصريح المتغير وقيمة إرجاع الدالة قد اختفى. ثانياً، لاحظ أننا نمرر &s1 إلى calculate_length وفي تعريفها، نأخذ &String بدلاً من String. تمثل علامات الاند (ampersands) هذه المراجع، وهي تسمح لك بالإشارة إلى قيمة ما دون أخذ ملكيتها. يوضح الشكل 4-6 هذا المفهوم.

الشكل 4-6: مخطط لـ &String s يشير إلى String s1

ملاحظة: عكس عملية الإسناد المرجعي (referencing) باستخدام & هو إلغاء المرجعية (dereferencing)، والذي يتم تحقيقه باستخدام عامل إلغاء المرجعية (dereference operator) *. سنرى بعض استخدامات dereference operator في الفصل 8 ونناقش تفاصيل dereferencing في الفصل 15.

دعونا نلقي نظرة فاحصة على استدعاء الدالة هنا:

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

يسمح لنا بناء جملة &s1 بإنشاء مرجع يشير إلى قيمة s1 ولكنه لا يملكها. ولأن المرجع لا يملكها، فإن القيمة التي يشير إليها لن يتم حذفها (dropped) عندما يتوقف استخدام المرجع.

وبالمثل، يستخدم توقيع الدالة & للإشارة إلى أن نوع parameter s هو مرجع. دعونا نضيف بعض التوضيحات الشارحة:

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize { // s is a reference to a String
    s.len()
} // Here, s goes out of scope. But because s does not have ownership of what
  // it refers to, the String is not dropped.

النطاق (scope) الذي يكون فيه المتغير s صالحاً هو نفس نطاق أي parameter للدالة، ولكن القيمة التي يشير إليها المرجع لا يتم حذفها عندما يتوقف استخدام s ، لأن s لا يملك الملكية. عندما تحتوي الدوال على مراجع كمعلمات بدلاً من القيم الفعلية، فلن نحتاج إلى إعادة القيم من أجل إعادة الملكية، لأننا لم نمتلك الملكية أبداً.

نسمي عملية إنشاء مرجع استعارة (borrowing). كما هو الحال في الحياة الواقعية، إذا كان شخص ما يملك شيئاً ما، يمكنك استعارته منه. عندما تنتهي، عليك إعادته. أنت لا تملكه.

لذا، ماذا يحدث إذا حاولنا تعديل شيء نستعيره؟ جرب الكود في القائمة 4-6. تنبيه: إنه لا يعمل!

fn main() {
    let s = String::from("hello");

    change(&s);
}

fn change(some_string: &String) {
    some_string.push_str(", world");
}

إليك الخطأ:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference
 --> src/main.rs:8:5
  |
8 |     some_string.push_str(", world");
  |     ^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
7 | fn change(some_string: &mut String) {
  |                         +++

For more information about this error, try `rustc --explain E0596`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

تماماً كما أن المتغيرات غير قابلة للتغيير (immutable) بشكل افتراضي، كذلك المراجع. لا يُسمح لنا بتعديل شيء لدينا مرجع له.

المراجع القابلة للتغيير (Mutable References)

يمكننا إصلاح الكود من القائمة 4-6 للسماح لنا بتعديل قيمة مستعارة ببعض التعديلات الصغيرة التي تستخدم، بدلاً من ذلك، مرجعاً قابلاً للتغيير (mutable reference):

fn main() {
    let mut s = String::from("hello");

    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

أولاً، نقوم بتغيير s ليكون mut. بعد ذلك، ننشئ mutable reference باستخدام &mut s حيث نستدعي دالة change ونقوم بتحديث توقيع الدالة لقبول mutable reference باستخدام some_string: &mut String. هذا يجعل من الواضح جداً أن دالة change ستقوم بتغيير (mutate) القيمة التي تستعيرها.

المراجع القابلة للتغيير لها قيد واحد كبير: إذا كان لديك mutable reference لقيمة ما، فلا يمكن أن يكون لديك مراجع أخرى لتلك القيمة. هذا الكود الذي يحاول إنشاء اثنين من mutable references لـ s سيفشل:

fn main() {
    let mut s = String::from("hello");

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{r1}, {r2}");
}

إليك الخطأ:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0499]: cannot borrow `s` as mutable more than once at a time
 --> src/main.rs:5:14
  |
4 |     let r1 = &mut s;
  |              ------ first mutable borrow occurs here
5 |     let r2 = &mut s;
  |              ^^^^^^ second mutable borrow occurs here
6 |
7 |     println!("{r1}, {r2}");
  |                -- first borrow later used here

For more information about this error, try `rustc --explain E0499`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

يقول هذا الخطأ أن هذا الكود غير صالح لأننا لا نستطيع استعارة s كـ mutable أكثر من مرة في كل مرة. الاستعارة القابلة للتغيير الأولى موجودة في r1 ويجب أن تستمر حتى يتم استخدامها في println! ، ولكن بين إنشاء ذلك المرجع القابل للتغيير واستخدامه، حاولنا إنشاء mutable reference آخر في r2 يستعير نفس البيانات مثل r1.

القيد الذي يمنع وجود مراجع متعددة قابلة للتغيير لنفس البيانات في نفس الوقت يسمح بالتغيير ولكن بطريقة محكومة للغاية. إنه شيء يعاني منه الـ Rustaceans الجدد لأن معظم اللغات تسمح لك بالتغيير وقتما تشاء. الفائدة من وجود هذا القيد هي أن Rust يمكنها منع سباقات البيانات (data races) في وقت التصريف (compile time). سباق البيانات يشبه حالة السباق (race condition) ويحدث عند وقوع هذه السلوكيات الثلاثة:

• وصول اثنين أو أكثر من pointers إلى نفس البيانات في نفس الوقت.
• استخدام واحد على الأقل من pointers للكتابة في البيانات.
• عدم وجود آلية مستخدمة لمزامنة الوصول إلى البيانات.

تسبب سباقات البيانات سلوكاً غير محدد (undefined behavior) ويمكن أن يكون من الصعب تشخيصها وإصلاحها عندما تحاول تعقبها في وقت التشغيل (runtime)؛ تمنع Rust هذه المشكلة برفض تصريف الكود الذي يحتوي على data races!

كما هو الحال دائماً، يمكننا استخدام الأقواس المتعرجة لإنشاء scope جديد، مما يسمح بوجود مراجع متعددة قابلة للتغيير، ولكن ليس مراجع متزامنة (simultaneous):

fn main() {
    let mut s = String::from("hello");

    {
        let r1 = &mut s;
    } // r1 goes out of scope here, so we can make a new reference with no problems.

    let r2 = &mut s;
}

تفرض Rust قاعدة مماثلة للجمع بين المراجع القابلة للتغيير وغير القابلة للتغيير. يؤدي هذا الكود إلى حدوث خطأ:

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    let r3 = &mut s; // BIG PROBLEM

    println!("{r1}, {r2}, and {r3}");
}

إليك الخطأ:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:14
  |
4 |     let r1 = &s; // no problem
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // no problem
6 |     let r3 = &mut s; // BIG PROBLEM
  |              ^^^^^^ mutable borrow occurs here
7 |
8 |     println!("{r1}, {r2}, and {r3}");
  |                -- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

يا للهول! لا يمكننا أيضاً الحصول على mutable reference بينما لدينا مرجع غير قابل للتغيير لنفس القيمة.

لا يتوقع مستخدمو المرجع غير القابل للتغيير أن تتغير القيمة فجأة من تحتهم! ومع ذلك، يُسمح بوجود مراجع متعددة غير قابلة للتغيير لأن لا أحد يقرأ البيانات فقط لديه القدرة على التأثير على قراءة أي شخص آخر للبيانات.

لاحظ أن scope المرجع يبدأ من حيث يتم تقديمه ويستمر حتى آخر مرة يتم فيها استخدام ذلك المرجع. على سبيل المثال، سيتم تصريف هذا الكود لأن آخر استخدام للمراجع غير القابلة للتغيير هو في println! ، قبل تقديم mutable reference:

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    println!("{r1} and {r2}");
    // Variables r1 and r2 will not be used after this point.

    let r3 = &mut s; // no problem
    println!("{r3}");
}

تنتهي نطاقات المراجع غير القابلة للتغيير r1 و r2 بعد println! حيث تم استخدامهما لآخر مرة، وهو ما يحدث قبل إنشاء mutable reference r3. هذه النطاقات لا تتداخل، لذا فإن هذا الكود مسموح به: يمكن لـ compiler معرفة أن المرجع لم يعد مستخدماً عند نقطة قبل نهاية scope.

على الرغم من أن أخطاء borrowing قد تكون محبطة في بعض الأحيان، تذكر أن compiler في Rust هو من يشير إلى خطأ محتمل في وقت مبكر (في compile time بدلاً من runtime) ويوضح لك بالضبط مكان المشكلة. عندها، لن تضطر إلى تعقب سبب عدم كون بياناتك كما كنت تعتقد.

المراجع المعلقة (Dangling References)

في اللغات التي تحتوي على pointers، من السهل إنشاء مؤشر معلق (dangling pointer) عن طريق الخطأ — وهو مؤشر يشير إلى موقع في الذاكرة ربما تم إعطاؤه لشخص آخر — عن طريق تحرير بعض الذاكرة مع الاحتفاظ بمؤشر لتلك الذاكرة. في Rust، على النقيض من ذلك، يضمن compiler أن المراجع لن تكون أبداً مراجع معلقة (dangling references): إذا كان لديك مرجع لبعض البيانات، فسيضمن compiler أن البيانات لن تخرج عن النطاق قبل أن يخرج المرجع للبيانات عن النطاق.

دعونا نحاول إنشاء dangling reference لنرى كيف تمنعها Rust بخطأ في وقت التصريف:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String {
    let s = String::from("hello");

    &s
}

إليك الخطأ:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn dangle() -> &String {
  |                ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static`
  |
5 | fn dangle() -> &'static String {
  |                 +++++++
help: instead, you are more likely to want to return an owned value
  |
5 - fn dangle() -> &String {
5 + fn dangle() -> String {
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

تشير رسالة الخطأ هذه إلى ميزة لم نغطها بعد: فترات الحياة (lifetimes). سنناقش lifetimes بالتفصيل في الفصل 10. ولكن، إذا تجاهلت الأجزاء المتعلقة بـ lifetimes، فإن الرسالة تحتوي بالفعل على المفتاح لسبب كون هذا الكود مشكلة:

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

دعونا نلقي نظرة فاحصة على ما يحدث بالضبط في كل مرحلة من مراحل كود dangle الخاص بنا:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope and is dropped, so its memory goes away.
  // Danger!

لأن s تم إنشاؤه داخل dangle ، فعند انتهاء كود dangle ، سيتم إلغاء تخصيص (deallocated) s. لكننا حاولنا إعادة مرجع له. هذا يعني أن هذا المرجع سيشير إلى String غير صالح. هذا ليس جيداً! لن تسمح لنا Rust بالقيام بذلك.

الحل هنا هو إعادة String مباشرة:

fn main() {
    let string = no_dangle();
}

fn no_dangle() -> String {
    let s = String::from("hello");

    s
}

هذا يعمل دون أي مشاكل. يتم نقل الملكية للخارج، ولا يتم إلغاء تخصيص أي شيء.

قواعد المراجع (The Rules of References)

دعونا نلخص ما ناقشناه حول المراجع:

• في أي وقت معين، يمكنك الحصول على إما مرجع واحد قابل للتغيير أو أي عدد من المراجع غير القابلة للتغيير.
• يجب أن تكون المراجع صالحة دائماً.

بعد ذلك، سننظر في نوع مختلف من المراجع: الشرائح (slices).

نوع الشريحة (The Slice Type)

نوع الشريحة (The Slice Type)

تتيح لك الـ شرائح (slices) الإشارة إلى تسلسل متصل من العناصر في مجموعة. الشريحة هي نوع من المراجع (references)، لذا فهي لا تمتلك ملكية (ownership).

إليك مشكلة برمجية صغيرة: اكتب دالة تأخذ سلسلة نصية (string) من الكلمات المفصولة بمسافات وتعيد الكلمة الأولى التي تجدها في تلك السلسلة. إذا لم تجد الدالة مسافة في السلسلة، فيجب اعتبار السلسلة بأكملها كلمة واحدة، وبالتالي يجب إعادة السلسلة كاملة.

ملاحظة: لأغراض تقديم الـ slices، نفترض استخدام ASCII فقط في هذا القسم؛ يوجد نقاش أكثر تفصيلاً حول التعامل مع UTF-8 في قسم “تخزين النصوص المشفرة بـ UTF-8 باستخدام السلاسل النصية” في الفصل 8.

دعنا نستعرض كيف سنكتب توقيع (signature) هذه الدالة دون استخدام الـ slices، لفهم المشكلة التي ستحلها الـ slices:

fn first_word(s: &String) -> ?

تمتلك دالة first_word معاملًا (parameter) من نوع &String. نحن لا نحتاج إلى الـ ownership، لذا هذا جيد. (في لغة Rust الاصطلاحية، لا تأخذ الدوال ملكية وسائطها (arguments) إلا إذا كانت بحاجة لذلك، وستتضح أسباب ذلك مع تقدمنا). ولكن ماذا يجب أن نعيد؟ ليس لدينا حقًا طريقة للتحدث عن جزء من السلسلة النصية. ومع ذلك، يمكننا إعادة فهرس (index) نهاية الكلمة، والذي تشير إليه المسافة. لنحاول ذلك، كما هو موضح في القائمة 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

لأننا بحاجة إلى المرور عبر الـ String عنصرًا تلو الآخر والتحقق مما إذا كانت القيمة مسافة، سنقوم بتحويل الـ String الخاص بنا إلى مصفوفة من البايتات (array of bytes) باستخدام دالة as_bytes.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

بعد ذلك، ننشئ مكررًا (iterator) فوق مصفوفة البايتات باستخدام دالة iter:

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

سنناقش الـ iterators بمزيد من التفصيل في الفصل 13. في الوقت الحالي، اعلم أن iter هي دالة تعيد كل عنصر في المجموعة، وأن enumerate تغلف نتيجة iter وتعيد كل عنصر كجزء من صف (tuple) بدلاً من ذلك. العنصر الأول في الـ tuple المعاد من enumerate هو الـ index، والعنصر الثاني هو مرجع للعنصر. هذا أكثر ملاءمة قليلاً من حساب الـ index بأنفسنا.

لأن دالة enumerate تعيد tuple، يمكننا استخدام الأنماط (patterns) لتفكيك ذلك الـ tuple. سنناقش الـ patterns أكثر في الفصل 6. في حلقة for نحدد نمطًا يحتوي على i للـ index في الـ tuple و &item للبايت الواحد في الـ tuple. ولأننا نحصل على مرجع للعنصر من .iter().enumerate() نستخدم & في النمط.

داخل حلقة for نبحث عن البايت الذي يمثل المسافة باستخدام بناء جملة البايت الحرفي (byte literal syntax). إذا وجدنا مسافة، نعيد الموضع. خلاف ذلك، نعيد طول السلسلة باستخدام s.len().

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

لدينا الآن طريقة لمعرفة فهرس نهاية الكلمة الأولى في السلسلة، ولكن هناك مشكلة. نحن نعيد نوع usize بمفرده، لكنه لا يكون ذا معنى إلا في سياق الـ &String. بعبارة أخرى، لأنه قيمة منفصلة عن الـ String فلا يوجد ضمان بأنه سيظل صالحًا في المستقبل. فكر في البرنامج في القائمة 4-8 الذي يستخدم دالة first_word من القائمة 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s); // word will get the value 5

    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but s no longer has any content that we
    // could meaningfully use with the value 5, so word is now totally invalid!
}

يترجم هذا البرنامج دون أي أخطاء، وسيفعل ذلك أيضًا إذا استخدمنا word بعد استدعاء s.clear(). ولأن word غير متصل بحالة s على الإطلاق، فإن word لا يزال يحتوي على القيمة 5. يمكننا استخدام تلك القيمة 5 مع المتغير s لمحاولة استخراج الكلمة الأولى، ولكن هذا سيكون خطأً برمجياً (bug) لأن محتويات s قد تغيرت منذ أن حفظنا 5 في word.

الاضطرار للقلق بشأن خروج الـ index في word عن المزامنة مع البيانات في s هو أمر ممل وعرضة للخطأ! إدارة هذه الفهارس تكون أكثر هشاشة إذا كتبنا دالة second_word. سيضطر توقيعها ليكون هكذا:

fn second_word(s: &String) -> (usize, usize) {

الآن نحن نتتبع فهرس بداية ونهاية، ولدينا المزيد من القيم التي تم حسابها من بيانات في حالة معينة ولكنها ليست مرتبطة بتلك الحالة على الإطلاق. لدينا ثلاثة متغيرات غير مرتبطة تطفو حولنا وتحتاج إلى الحفاظ على مزامنتها.

لحسن الحظ، لدى Rust حل لهذه المشكلة: شرائح السلاسل النصية (string slices).

شرائح السلاسل النصية (String Slices)

الـ string slice هي مرجع لتسلسل متصل من عناصر الـ String وتبدو هكذا:

fn main() {
    let s = String::from("hello world");

    let hello = &s[0..5];
    let world = &s[6..11];
}

بدلاً من مرجع للـ String بالكامل، فإن hello هو مرجع لجزء من الـ String محدد في الجزء الإضافي [0..5]. ننشئ الـ slices باستخدام نطاق (range) داخل أقواس مربعة عن طريق تحديد [starting_index..ending_index] حيث يكون starting_index هو الموضع الأول في الشريحة و ending_index هو أكثر بواحد من الموضع الأخير في الشريحة. داخليًا، يخزن هيكل بيانات الشريحة موضع البداية وطول الشريحة، والذي يتوافق مع ending_index ناقص starting_index. لذا، في حالة let world = &s[6..11]; سيكون world عبارة عن شريحة تحتوي على مؤشر (pointer) للبايت عند الفهرس 6 من s مع قيمة طول قدرها 5.

يوضح الشكل 4-7 هذا في رسم تخطيطي.

الشكل 4-7: شريحة سلسلة نصية تشير إلى جزء من String

مع بناء جملة النطاق .. في Rust، إذا كنت تريد البدء من الفهرس 0، يمكنك حذف القيمة قبل النقطتين. بعبارة أخرى، هذه متساوية:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let slice = &s[0..2];
let slice = &s[..2];
}

وبنفس المنطق، إذا كانت شريحتك تتضمن البايت الأخير من الـ String يمكنك حذف الرقم اللاحق. وهذا يعني أن هذه متساوية:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

يمكنك أيضًا حذف كلتا القيمتين لأخذ شريحة من السلسلة بأكملها. لذا، هذه متساوية:

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

ملاحظة: يجب أن تقع فهارس نطاق الـ string slice عند حدود أحرف UTF-8 صالحة. إذا حاولت إنشاء شريحة سلسلة نصية في منتصف حرف متعدد البايتات، فسيخرج برنامجك بخطأ.

مع وضع كل هذه المعلومات في الاعتبار، دعنا نعيد كتابة first_word لتعيد شريحة. النوع الذي يشير إلى “شريحة سلسلة نصية” يكتب كـ &str:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

نحصل على الفهرس لنهاية الكلمة بنفس الطريقة التي فعلناها في القائمة 4-7، من خلال البحث عن أول ظهور للمسافة. عندما نجد مسافة، نعيد شريحة سلسلة نصية باستخدام بداية السلسلة وفهرس المسافة كفهارس البداية والنهاية.

الآن عندما نستدعي first_word نحصل على قيمة واحدة مرتبطة بالبيانات الأساسية. تتكون القيمة من مرجع لنقطة بداية الشريحة وعدد العناصر في الشريحة.

إعادة شريحة سيعمل أيضًا مع دالة second_word:

fn second_word(s: &String) -> &str {

لدينا الآن واجهة برمجة تطبيقات (API) مباشرة يصعب العبث بها لأن المترجم سيضمن بقاء المراجع داخل الـ String صالحة. تذكر الـ bug في البرنامج في القائمة 4-8، عندما حصلنا على الفهرس لنهاية الكلمة الأولى ثم مسحنا السلسلة فصار الفهرس غير صالح؟ كان ذلك الكود غير صحيح منطقيًا ولكنه لم يظهر أي أخطاء فورية. كانت المشاكل ستظهر لاحقًا إذا واصلنا محاولة استخدام فهرس الكلمة الأولى مع سلسلة فارغة. تجعل الـ slices هذا الـ bug مستحيلاً وتخبرنا في وقت أبكر بكثير أن لدينا مشكلة في كودنا. استخدام نسخة الـ slice من first_word سيؤدي إلى خطأ في وقت الترجمة (compile-time error):

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {word}");
}

إليك خطأ المترجم:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                   ---- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

تذكر من قواعد الاستعارة (borrowing rules) أنه إذا كان لدينا مرجع غير قابل للتغيير (immutable reference) لشيء ما، فلا يمكننا أيضًا أخذ مرجع قابل للتغيير (mutable reference). ولأن clear تحتاج إلى تقليص الـ String فهي بحاجة للحصول على mutable reference. الـ println! بعد استدعاء clear تستخدم المرجع في word لذا يجب أن يظل الـ immutable reference نشطًا عند تلك النقطة. يمنع Rust وجود الـ mutable reference في clear والـ immutable reference في word في نفس الوقت، ويفشل الترجمة. لم يجعل Rust الـ API الخاص بنا أسهل في الاستخدام فحسب، بل قضى أيضًا على فئة كاملة من الأخطاء في وقت الترجمة!

السلاسل النصية الحرفية كشرائح (String Literals as Slices)

تذكر أننا تحدثنا عن تخزين السلاسل النصية الحرفية (string literals) داخل الملف الثنائي (binary). الآن بعد أن عرفنا عن الـ slices، يمكننا فهم السلاسل النصية الحرفية بشكل صحيح:

#![allow(unused)]
fn main() {
let s = "Hello, world!";
}

نوع s هنا هو &str: إنه شريحة تشير إلى تلك النقطة المحددة من الـ binary. وهذا أيضًا هو السبب في أن السلاسل النصية الحرفية غير قابلة للتغيير؛ &str هو immutable reference.

شرائح السلاسل النصية كمعاملات (String Slices as Parameters)

معرفة أنه يمكنك أخذ شرائح من الحرفيات وقيم الـ String يقودنا إلى تحسين آخر على first_word وهو توقيعها:

fn first_word(s: &String) -> &str {

سيكتب مبرمج Rust الأكثر خبرة (Rustacean) التوقيع الموضح في القائمة 4-9 بدلاً من ذلك لأنه يسمح لنا باستخدام نفس الدالة على كل من قيم &String وقيم &str.

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

إذا كان لدينا string slice، يمكننا تمريرها مباشرة. إذا كان لدينا String يمكننا تمرير شريحة من الـ String أو مرجع للـ String. تستفيد هذه المرونة من تحويلات فك المراجع (deref coercions)، وهي ميزة سنغطيها في قسم “استخدام تحويلات فك المراجع في الدوال والـ methods” في الفصل 15.

تعريف دالة لتأخذ string slice بدلاً من مرجع لـ String يجعل الـ API الخاص بنا أكثر عمومية وفائدة دون فقدان أي وظائف:

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

شرائح أخرى (Other Slices)

شرائح السلاسل النصية، كما قد تتخيل، خاصة بالسلاسل النصية. ولكن هناك نوع شريحة أكثر عمومية أيضًا. فكر في هذه المصفوفة:

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];
}

تمامًا كما قد نرغب في الإشارة إلى جزء من سلسلة نصية، قد نرغب في الإشارة إلى جزء من مصفوفة. سنفعل ذلك هكذا:

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

هذه الشريحة لها النوع &[i32]. وهي تعمل بنفس الطريقة التي تعمل بها شرائح السلاسل النصية، من خلال تخزين مرجع للعنصر الأول وطول. ستستخدم هذا النوع من الشرائح لجميع أنواع المجموعات الأخرى. سنناقش هذه المجموعات بالتفصيل عندما نتحدث عن المتجهات (vectors) في الفصل 8.

ملخص (Summary)

تضمن مفاهيم الملكية (ownership)، والاستعارة (borrowing)، والشرائح (slices) سلامة الذاكرة (memory safety) في برامج Rust في وقت الترجمة. تمنحك لغة Rust التحكم في استخدام الذاكرة بنفس الطريقة التي تمنحك إياها لغات برمجة الأنظمة الأخرى. ولكن وجود مالك للبيانات يقوم تلقائيًا بتنظيف تلك البيانات عندما يخرج المالك عن النطاق يعني أنك لست مضطرًا لكتابة وتصحيح كود إضافي للحصول على هذا التحكم.

تؤثر الـ Ownership على كيفية عمل الكثير من الأجزاء الأخرى في Rust، لذا سنتحدث عن هذه المفاهيم بشكل أكبر في بقية الكتاب. دعنا ننتقل إلى الفصل 5 وننظر في تجميع قطع البيانات معًا في هيكل struct.

استخدام الهياكل لتنظيم البيانات ذات الصلة (Using Structs to Structure Related Data)

الـ هيكل (struct)، أو البنية (structure)، هو نوع بيانات مخصص يتيح لك تجميع وتسمية قيم متعددة ذات صلة تشكل مجموعة ذات معنى. إذا كنت معتاداً على لغة كائنية التوجه (object-oriented language)، فإن struct يشبه سمات البيانات (data attributes) الخاصة بالكائن. في هذا الفصل، سنقوم بمقارنة وتباين الصفوف (tuples) مع structs للبناء على ما تعرفه بالفعل وتوضيح متى تكون structs طريقة أفضل لتجميع البيانات.

سنوضح كيفية تعريف وإنشاء مثيلات (instantiate) من structs. سنناقش كيفية تعريف الدوال المرتبطة (associated functions)، وخاصة نوع associated functions الذي يسمى الدوال (methods)، لتحديد السلوك المرتبط بنوع struct. تعد structs والتعدادات (enums) (التي تمت مناقشتها في الفصل السادس) هي اللبنات الأساسية لإنشاء أنواع جديدة في مجال برنامجك للاستفادة الكاملة من فحص النوع في وقت التصريف (compile-time type checking) في Rust.

تعريف وإنشاء الهياكل (Defining and Instantiating Structs)

تعريف الهياكل وإنشاؤها (Defining and Instantiating Structs)

تتشابه الهياكل (structs) مع الصفوف (tuples)، التي نوقشت في قسم “نوع الصف (Tuple)” ، في أن كليهما يحمل عدة قيم مرتبطة. ومثل tuples، يمكن أن تكون أجزاء الـ struct من أنواع مختلفة. وبخلاف tuples، ستقوم في الـ struct بتسمية كل قطعة من البيانات بحيث يكون واضحاً ما تعنيه القيم. إضافة هذه الأسماء تعني أن structs أكثر مرونة من tuples: لست مضطراً للاعتماد على ترتيب البيانات لتحديد قيم مثيل (instance) أو الوصول إليها.

لتعريف struct، ندخل الكلمة المفتاحية struct ونسمي الـ struct بالكامل. يجب أن يصف اسم الـ struct أهمية قطع البيانات التي يتم تجميعها معاً. ثم، داخل أقواس متعرجة، نعرف أسماء وأنواع قطع البيانات، والتي نسميها حقولاً (fields). على سبيل المثال، توضح القائمة 5-1 struct يخزن معلومات حول حساب مستخدم.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

لاستخدام struct بعد تعريفه، ننشئ مثيلاً (instance) من ذلك الـ struct عن طريق تحديد قيم ملموسة لكل من الـ fields. ننشئ instance بذكر اسم الـ struct ثم نضيف أقواس متعرجة تحتوي على أزواج key: value ، حيث المفاتيح هي أسماء الـ fields والقيم هي البيانات التي نريد تخزينها في تلك الـ fields. ليس علينا تحديد الـ fields بنفس الترتيب الذي صرحنا به عنها في الـ struct. بمعنى آخر، تعريف الـ struct يشبه قالباً عاماً للنوع، وتقوم الـ instances بملء ذلك القالب ببيانات محددة لإنشاء قيم من ذلك النوع. على سبيل المثال، يمكننا التصريح عن مستخدم معين كما هو موضح في القائمة 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
}

للحصول على قيمة محددة من struct، نستخدم ترميز النقطة (dot notation). على سبيل المثال، للوصول إلى عنوان البريد الإلكتروني لهذا المستخدم، نستخدم user1.email. إذا كان الـ instance قابلاً للتغيير (mutable)، فيمكننا تغيير قيمة باستخدام dot notation والتعيين في field معين. توضح القائمة 5-3 كيفية تغيير القيمة في حقل email لمثيل User قابل للتغيير.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let mut user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

    user1.email = String::from("anotheremail@example.com");
}

لاحظ أن الـ instance بالكامل يجب أن يكون mutable؛ لا تسمح لنا Rust بتمييز حقول معينة فقط كـ mutable. وكما هو الحال مع أي تعبير، يمكننا بناء instance جديد من الـ struct كآخر تعبير في جسم الدالة (function body) لإرجاع ذلك الـ instance الجديد ضمناً.

توضح القائمة 5-4 دالة build_user تعيد instance من User بالبريد الإلكتروني واسم المستخدم المعطيين. يحصل حقل active على القيمة true ، ويحصل sign_in_count على قيمة 1.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username: username,
        email: email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

من المنطقي تسمية معاملات الدالة (function parameters) بنفس اسم struct fields ، ولكن الاضطرار إلى تكرار أسماء الحقول والمتغيرات email و username أمر ممل بعض الشيء. إذا كان للـ struct حقول أكثر، فإن تكرار كل اسم سيصبح أكثر إزعاجاً. لحسن الحظ، هناك اختصار مريح!

استخدام اختصار تهيئة الحقول (Using the Field Init Shorthand)

لأن أسماء الـ parameters وأسماء struct fields متطابقة تماماً في القائمة 5-4، يمكننا استخدام صيغة (syntax) اختصار تهيئة الحقول (field init shorthand) لإعادة كتابة build_user بحيث تتصرف تماماً بنفس الطريقة ولكن بدون تكرار username و email ، كما هو موضح في القائمة 5-5.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username,
        email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

هنا، نقوم بإنشاء instance جديد من الـ User struct، والذي يحتوي على field باسم email. نريد تعيين قيمة حقل email إلى القيمة الموجودة في parameter الـ email لدالة build_user. ولأن حقل email و parameter الـ email لهما نفس الاسم، نحتاج فقط إلى كتابة email بدلاً من email: email.

إنشاء مثيلات باستخدام صيغة تحديث الهيكل (Creating Instances with Struct Update Syntax)

غالباً ما يكون من المفيد إنشاء instance جديد من struct يتضمن معظم القيم من instance آخر من نفس النوع، ولكن يغير بعضها. يمكنك القيام بذلك باستخدام صيغة تحديث الهيكل (struct update syntax).

أولاً، في القائمة 5-6 نوضح كيفية إنشاء instance جديد من User في user2 بالطريقة العادية، بدون update syntax. نقوم بتعيين قيمة جديدة لـ email ولكن بخلاف ذلك نستخدم نفس القيم من user1 الذي أنشأناه في القائمة 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("another@example.com"),
        sign_in_count: user1.sign_in_count,
    };
}

باستخدام struct update syntax، يمكننا تحقيق نفس التأثير بكود أقل، كما هو موضح في القائمة 5-7. تحدد الصيغة .. أن الـ fields المتبقية التي لم يتم تعيينها صراحة يجب أن يكون لها نفس قيمة الـ fields في الـ instance المعطى.

يُنشئ الكود في القائمة 5-7 أيضاً instance في `user2` له قيمة مختلفة لـ `email` ولكن له نفس القيم لحقول `username` و `active` و `sign_in_count` من `user1`. يجب أن تأتي `..user1` في النهاية لتحديد أن أي حقول متبقية يجب أن تحصل على قيمها من الحقول المقابلة في `user1` ، ولكن يمكننا اختيار تحديد قيم لعدد الحقول الذي نريده وبأي ترتيب، بغض النظر عن ترتيب الحقول في تعريف الـ struct.

لاحظ أن struct update syntax يستخدم `=` مثل التعيين؛ هذا لأنه ينقل البيانات، تماماً كما رأينا في قسم ["تفاعل المتغيرات والبيانات مع النقل (Move)"][move]. في هذا المثال، لم يعد بإمكاننا استخدام `user1` بعد إنشاء `user2` لأن الـ `String` في حقل `username` لـ `user1` قد نُقل إلى `user2`. إذا أعطينا `user2` قيم `String` جديدة لكل من `email` و `username` ، وبالتالي استخدمنا فقط قيم `active` و `sign_in_count` من `user1` ، فسيظل `user1` صالحاً بعد إنشاء `user2`. كل من `active` و `sign_in_count` هما أنواع تنفذ سمة (trait) الـ `Copy` ، لذا فإن السلوك الذي ناقشناه في قسم ["بيانات المكدس فقط: النسخ (Copy)"][copy] سينطبق. يمكننا أيضاً الاستمرار في استخدام `user1.email` في هذا المثال، لأن قيمته لم تُنقل خارج `user1`.

<!-- Old headings. Do not remove or links may break. -->

<a id="using-tuple-structs-without-named-fields-to-create-different-types"></a>

### إنشاء أنواع مختلفة باستخدام هياكل الصفوف (Creating Different Types with Tuple Structs)

تدعم Rust أيضاً structs تشبه tuples، وتسمى _هياكل الصفوف_ (tuple structs). تمتلك tuple structs المعنى الإضافي الذي يوفره اسم الـ struct ولكن ليس لها أسماء مرتبطة بحقولها؛ بدلاً من ذلك، لديها فقط أنواع الحقول. تكون tuple structs مفيدة عندما تريد إعطاء الـ tuple بالكامل اسماً وجعل الـ tuple نوعاً مختلفاً عن tuples الأخرى، وعندما يكون تسمية كل حقل كما هو الحال في الـ struct العادي أمراً مطولاً أو زائداً عن الحاجة.

لتعريف tuple struct، ابدأ بالكلمة المفتاحية `struct` واسم الـ struct متبوعاً بالأنواع الموجودة في الـ tuple. على سبيل المثال، هنا نعرف ونستخدم اثنين من tuple structs باسم `Color` و `Point`:

<Listing file-name="src/main.rs">

```rust
struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

لاحظ أن قيم black و origin هي أنواع مختلفة لأنها instances من tuple structs مختلفة. كل struct تعرفه هو نوع خاص به، على الرغم من أن الحقول داخل الـ struct قد يكون لها نفس الأنواع. على سبيل المثال، الدالة التي تأخذ parameter من نوع Color لا يمكنها أخذ Point كـ argument، على الرغم من أن كلا النوعين يتكونان من ثلاث قيم i32. بخلاف ذلك، تتشابه instances الـ tuple struct مع tuples في أنه يمكنك تفكيكها (destructure) إلى قطعها الفردية، ويمكنك استخدام . متبوعة بالفهرس (index) للوصول إلى قيمة فردية. وبخلاف tuples، تتطلب منك tuple structs تسمية نوع الـ struct عند القيام بـ destructure لها. على سبيل المثال، سنكتب let Point(x, y, z) = origin; لتفكيك القيم في نقطة الـ origin إلى متغيرات تسمى x و y و z.

تعريف الهياكل الشبيهة بالوحدة (Defining Unit-Like Structs)

يمكنك أيضاً تعريف structs لا تحتوي على أي حقول! تسمى هذه الهياكل الشبيهة بالوحدة (unit-like structs) لأنها تتصرف بشكل مشابه لـ () ، وهو نوع الوحدة (unit type) الذي ذكرناه في قسم “نوع الصف (Tuple)”. يمكن أن تكون unit-like structs مفيدة عندما تحتاج إلى تنفيذ trait على نوع ما ولكن ليس لديك أي بيانات تريد تخزينها في النوع نفسه. سنناقش الـ traits في الفصل العاشر. إليك مثال على التصريح عن struct وحدة باسم AlwaysEqual وإنشائه:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

لتعريف AlwaysEqual ، نستخدم الكلمة المفتاحية struct ، والاسم الذي نريده، ثم فاصلة منقوطة. لا حاجة لأقواس متعرجة أو أقواس عادية! بعد ذلك، يمكننا الحصول على instance من AlwaysEqual في متغير subject بطريقة مماثلة: باستخدام الاسم الذي عرفناه، بدون أي أقواس متعرجة أو عادية. تخيل أننا سنقوم لاحقاً بتنفيذ سلوك لهذا النوع بحيث يكون كل instance من AlwaysEqual مساوياً دائماً لكل instance من أي نوع آخر، ربما للحصول على نتيجة معروفة لأغراض الاختبار. لن نحتاج إلى أي بيانات لتنفيذ هذا السلوك! سترى في الفصل العاشر كيفية تعريف traits وتنفيذها على أي نوع، بما في ذلك unit-like structs.

ملكية بيانات الهيكل (Ownership of Struct Data)

في تعريف User struct في القائمة 5-1، استخدمنا نوع الـ String المملوك بدلاً من نوع شريحة السلسلة (string slice) &str. هذا اختيار متعمد لأننا نريد أن يمتلك كل instance من هذا الـ struct جميع بياناته وأن تكون تلك البيانات صالحة طالما أن الـ struct بالكامل صالح.

من الممكن أيضاً للـ structs تخزين مراجع (references) لبيانات مملوكة لشيء آخر، ولكن القيام بذلك يتطلب استخدام فترات الحياة (lifetimes)، وهي ميزة في Rust سنناقشها في الفصل العاشر. تضمن lifetimes أن البيانات المشار إليها بواسطة struct صالحة طالما أن الـ struct صالح. لنفترض أنك حاولت تخزين reference في struct دون تحديد lifetimes، مثل ما يلي في src/main.rs؛ هذا لن يعمل:

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

سيشتكي المترجم (compiler) من أنه يحتاج إلى محددات فترات الحياة (lifetime specifiers):

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

في الفصل العاشر، سنناقش كيفية إصلاح هذه الأخطاء بحيث يمكنك تخزين references في structs، ولكن في الوقت الحالي، سنصلح أخطاء مثل هذه باستخدام الأنواع المملوكة مثل String بدلاً من references مثل &str.

برنامج مثال باستخدام Structs

برنامج مثال يستخدم التركيبات (Structs)

لفهم متى قد نرغب في استخدام Structs، دعنا نكتب برنامجًا يحسب مساحة مستطيل. سنبدأ باستخدام متغيرات مفردة ثم نقوم بـ إعادة الهيكلة (Refactoring) للبرنامج حتى نستخدم Structs بدلاً من ذلك.

دعنا ننشئ مشروعًا ثنائيًا جديدًا باستخدام Cargo يسمى rectangles والذي سيأخذ العرض والارتفاع لمستطيل محدد بالبكسل ويحسب مساحة المستطيل. توضح القائمة 5-8 برنامجًا قصيرًا بإحدى طرق القيام بذلك بالضبط في ملف src/main.rs الخاص بمشروعنا.

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

الآن، قم بتشغيل هذا البرنامج باستخدام cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

ينجح هذا الكود في معرفة مساحة المستطيل عن طريق استدعاء الدالة area بكل بُعد، ولكن يمكننا فعل المزيد لجعل هذا الكود واضحًا وقابلًا للقراءة.

تظهر المشكلة في هذا الكود واضحة في توقيع area:

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

من المفترض أن تحسب الدالة area مساحة مستطيل واحد، لكن الدالة التي كتبناها تحتوي على معاملين، وليس من الواضح في أي مكان في برنامجنا أن المعاملين مرتبطان. سيكون تجميع width و height معًا أكثر قابلية للقراءة وأسهل في الإدارة. لقد ناقشنا بالفعل إحدى الطرق التي قد نفعل بها ذلك في قسم “The Tuple Type” من الفصل 3: باستخدام الصفوف (Tuples).

Refactoring باستخدام Tuples

توضح القائمة 5-9 إصدارًا آخر من برنامجنا يستخدم Tuples.

fn main() {
    let rect1 = (30, 50);

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

بطريقة ما، هذا البرنامج أفضل. تسمح لنا Tuples بإضافة القليل من الهيكلة، ونحن الآن نمرر وسيطًا واحدًا فقط. ولكن بطريقة أخرى، هذا الإصدار أقل وضوحًا: لا تسمي Tuples عناصرها، لذلك يجب علينا الفهرسة في أجزاء Tuple، مما يجعل حسابنا أقل وضوحًا.

لن يهم خلط width و height في حساب المساحة، ولكن إذا أردنا رسم المستطيل على الشاشة، فسيكون الأمر مهمًا! سيتعين علينا أن نضع في اعتبارنا أن width هو فهرس Tuple رقم 0 وأن height هو فهرس Tuple رقم 1. سيكون هذا أصعب على شخص آخر اكتشافه ووضعه في الاعتبار إذا كان سيستخدم الكود الخاص بنا. نظرًا لأننا لم ننقل معنى بياناتنا في الكود الخاص بنا، فقد أصبح من الأسهل الآن إدخال أخطاء.

Refactoring باستخدام Structs

نستخدم Structs لإضافة معنى عن طريق تسمية البيانات. يمكننا تحويل Tuple الذي نستخدمه إلى Struct باسم للكل بالإضافة إلى أسماء للأجزاء، كما هو موضح في القائمة 5-10.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

هنا، قمنا بتعريف Struct وسميناها Rectangle. داخل الأقواس المعقوفة، قمنا بتعريف الحقول (Fields) كـ width و height، وكلاهما من النوع u32. بعد ذلك، في main، أنشأنا مثيلًا (instance) معينًا من Rectangle بعرض 30 وارتفاع 50.

تم تعريف الدالة area الآن بمعامل واحد، سميناه rectangle، ونوعه هو استعارة غير قابلة للتغيير (immutable borrow) لمثيل Struct Rectangle. كما ذكرنا في الفصل 4، نريد استعارة (Borrow) Struct بدلاً من أخذ الملكية (Ownership) لها. بهذه الطريقة، تحتفظ main بـ Ownership الخاصة بها ويمكنها الاستمرار في استخدام rect1، وهذا هو السبب في أننا نستخدم & في توقيع الدالة وعندما نستدعي الدالة.

تصل الدالة area إلى Fields width و height لمثيل Rectangle (لاحظ أن الوصول إلى Fields لمثيل Struct مستعار لا ينقل قيم Field، ولهذا السبب ترى غالبًا عمليات Borrow لـ Structs). يقول توقيع الدالة area الآن بالضبط ما نعنيه: احسب مساحة Rectangle، باستخدام Fields width و height الخاصة بها. هذا ينقل أن width و height مرتبطان ببعضهما البعض، ويعطي أسماء وصفية للقيم بدلاً من استخدام قيم فهرس Tuple 0 و 1. هذا مكسب للوضوح.

إضافة وظائف باستخدام السمات المشتقة (Derived Traits)

سيكون من المفيد أن نتمكن من طباعة مثيل Rectangle أثناء تصحيح الأخطاء (Debug) في برنامجنا ورؤية القيم لجميع Fields الخاصة به. تحاول القائمة 5-11 استخدام الماكرو println! كما استخدمناه في الفصول السابقة. ومع ذلك، لن ينجح هذا.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1}");
}

عندما نقوم بتجميع هذا الكود، نحصل على خطأ بهذه الرسالة الأساسية:

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

يمكن لـ ماكرو println! القيام بالعديد من أنواع التنسيق، وبشكل افتراضي، تخبر الأقواس المعقوفة println! باستخدام تنسيق يُعرف باسم Display: إخراج مخصص للاستهلاك المباشر للمستخدم النهائي. تطبق الأنواع البدائية (primitive types) التي رأيناها حتى الآن Display افتراضيًا لأنه لا توجد سوى طريقة واحدة تريد بها إظهار 1 أو أي نوع بدائي آخر للمستخدم. ولكن مع Structs، فإن الطريقة التي يجب أن يقوم بها println! بتنسيق الإخراج أقل وضوحًا لأن هناك المزيد من إمكانيات العرض: هل تريد فواصل أم لا؟ هل تريد طباعة الأقواس المعقوفة؟ هل يجب عرض جميع Fields؟ بسبب هذا الغموض، لا يحاول Rust تخمين ما نريده، ولا تحتوي Structs على تطبيق متوفر لـ Display لاستخدامه مع println! والعنصر النائب {}.

إذا واصلنا قراءة الأخطاء، فسنجد هذه الملاحظة المفيدة:

   |                        |`Rectangle` cannot be formatted with the default formatter
   |                        required by this formatting parameter

دعنا نجربها! سيبدو استدعاء ماكرو println! الآن كما يلي: println!("rect1 is {rect1:?}");. وضع المحدد :? داخل الأقواس المعقوفة يخبر println! أننا نريد استخدام تنسيق إخراج يسمى Debug. تُمكّننا السمة (Trait) Debug من طباعة Struct الخاص بنا بطريقة مفيدة للمطورين حتى نتمكن من رؤية قيمتها أثناء قيامنا بـ Debug الكود الخاص بنا.

قم بتجميع الكود بهذا التغيير. يا للأسف! ما زلنا نحصل على خطأ:

error[E0277]: `Rectangle` doesn't implement `Debug`

ولكن مرة أخرى، يعطينا المترجم ملاحظة مفيدة:

   |                        required by this formatting parameter
   |

يتضمن Rust وظيفة لطباعة معلومات Debug، ولكن يجب علينا الاشتراك صراحةً لجعل هذه الوظيفة متاحة لـ Struct الخاص بنا. للقيام بذلك، نضيف السمة الخارجية (Attribute) #[derive(Debug)] قبل تعريف Struct مباشرةً، كما هو موضح في القائمة 5-12.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1:?}");
}

الآن عندما نقوم بتشغيل البرنامج، لن نحصل على أي أخطاء، وسنرى الإخراج التالي:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

جيد! إنه ليس أجمل إخراج، ولكنه يظهر قيم جميع Fields لهذا المثيل، مما سيساعد بالتأكيد أثناء Debug. عندما يكون لدينا Structs أكبر، من المفيد أن يكون لدينا إخراج أسهل قليلاً في القراءة؛ في هذه الحالات، يمكننا استخدام {:#?} بدلاً من {:?} في سلسلة println!. في هذا المثال، سيؤدي استخدام نمط {:#?} إلى إخراج ما يلي:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

هناك طريقة أخرى لطباعة قيمة باستخدام تنسيق Debug وهي استخدام الماكرو dbg!، الذي يأخذ Ownership لتعبير (على عكس println!، الذي يأخذ reference)، ويطبع الملف ورقم السطر الذي يحدث فيه استدعاء ماكرو dbg! في الكود الخاص بك جنبًا إلى جنب مع القيمة الناتجة لهذا التعبير، ويعيد Ownership للقيمة.

ملاحظة: يطبع استدعاء ماكرو dbg! إلى مجرى وحدة التحكم للخطأ القياسي (stderr)، على عكس println!، الذي يطبع إلى مجرى وحدة التحكم للإخراج القياسي (stdout). سنتحدث أكثر عن stderr و stdout في قسم “Redirecting Errors to Standard Error” section in Chapter 12.

إليك مثال حيث نهتم بالقيمة التي يتم تعيينها لـ Field width، بالإضافة إلى قيمة Struct بأكمله في rect1:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

يمكننا وضع dbg! حول التعبير 30 * scale، ولأن dbg! يعيد Ownership لقيمة التعبير، سيحصل Field width على نفس القيمة كما لو لم يكن لدينا استدعاء dbg! هناك. لا نريد أن يأخذ dbg! Ownership لـ rect1، لذلك نستخدم reference لـ rect1 في الاستدعاء التالي. إليك كيف يبدو إخراج هذا المثال:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10:16] 30 * scale = 60
[src/main.rs:14:5] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

يمكننا أن نرى أن الجزء الأول من الإخراج جاء من السطر 10 في src/main.rs حيث نقوم بـ Debug التعبير 30 * scale، وقيمته الناتجة هي 60 (تنسيق Debug المطبق للأعداد الصحيحة هو طباعة قيمتها فقط). يخرج استدعاء dbg! في السطر 14 من src/main.rs قيمة &rect1، وهي Struct Rectangle. يستخدم هذا الإخراج تنسيق Debug الجميل لنوع Rectangle. يمكن أن يكون ماكرو dbg! مفيدًا حقًا عندما تحاول معرفة ما يفعله الكود الخاص بك!

بالإضافة إلى Trait Debug، وفر Rust عددًا من Traits لنا لاستخدامها مع Attribute derive والتي يمكن أن تضيف سلوكًا مفيدًا لأنواعنا المخصصة. يتم سرد هذه Traits وسلوكياتها في Appendix C. سنغطي كيفية تطبيق هذه Traits بسلوك مخصص بالإضافة إلى كيفية إنشاء Traits الخاصة بك في الفصل 10. هناك أيضًا العديد من Attributes بخلاف derive؛ لمزيد من المعلومات، راجع the “Attributes” section of the Rust Reference.

الدالة area الخاصة بنا محددة للغاية: إنها تحسب مساحة المستطيلات فقط. سيكون من المفيد ربط هذا السلوك بشكل أوثق بـ Struct Rectangle الخاص بنا لأنه لن يعمل مع أي نوع آخر. دعنا نلقي نظرة على كيف يمكننا الاستمرار في Refactoring هذا الكود عن طريق تحويل الدالة area إلى دالة عضو (Method) area معرفة على نوع Rectangle الخاص بنا.

دوال الكائنات (Methods)

الـ Methods

الـ Methods تشبه الـ functions: نعلن عنها باستخدام الكلمة المفتاحية fn واسم، يمكن أن تحتوي على parameters وقيمة إرجاع (return value)، وتحتوي على بعض الكود الذي يتم تشغيله عند استدعاء الـ method من مكان آخر. على عكس الـ functions، يتم تعريف الـ methods ضمن سياق struct (أو enum أو trait object، والتي نغطيها في الفصل 6 و الفصل 18، على التوالي)، ويكون الـ parameter الأول لها دائمًا self، والذي يمثل مثيل الـ struct الذي يتم استدعاء الـ method عليه.

بناء جملة الـ Method (Method Syntax)

دعنا نغير دالة area التي تحتوي على مثيل Rectangle كـ parameter ونجعلها بدلاً من ذلك method area معرفًا على struct Rectangle، كما هو موضح في القائمة 5-13.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

لتعريف الـ function ضمن سياق Rectangle، نبدأ كتلة impl (تنفيذ (implementation)) لـ Rectangle. كل شيء داخل كتلة impl هذه سيتم ربطه بنوع Rectangle. بعد ذلك، ننقل دالة area داخل الأقواس المعقوفة لـ impl ونغير الـ parameter الأول (والوحيد في هذه الحالة) ليكون self في الـ signature وفي كل مكان داخل الـ body. في main، حيث استدعينا دالة area ومررنا rect1 كوسيط (argument)، يمكننا بدلاً من ذلك استخدام بناء جملة الـ method (method syntax) لاستدعاء method area على مثيل Rectangle الخاص بنا. يأتي الـ method syntax بعد مثيل: نضيف نقطة متبوعة باسم الـ method، والأقواس، وأي arguments.

في الـ signature لـ area، نستخدم &self بدلاً من rectangle: &Rectangle. الـ &self هو في الواقع اختصار لـ self: &Self. ضمن كتلة impl، النوع Self هو اسم مستعار (alias) للنوع الذي تنطبق عليه كتلة impl. يجب أن تحتوي الـ methods على parameter يسمى self من النوع Self لـ parameter الأول، لذا تسمح لك Rust باختصار ذلك باستخدام الاسم self فقط في موضع الـ parameter الأول. لاحظ أننا ما زلنا بحاجة إلى استخدام & أمام اختصار self للإشارة إلى أن هذا الـ method يقترض (borrows) مثيل Self، تمامًا كما فعلنا في rectangle: &Rectangle. يمكن أن تأخذ الـ methods ملكية (ownership) الـ self، أو تقترض الـ self بشكل غير قابل للتغيير (immutably)، كما فعلنا هنا، أو تقترض الـ self بشكل قابل للتغيير (mutably)، تمامًا كما يمكنها أي parameter آخر.

اخترنا &self هنا لنفس السبب الذي استخدمنا به &Rectangle في إصدار الـ function: لا نريد أن نأخذ الـ ownership، ونريد فقط قراءة الـ data في الـ struct، وليس الكتابة عليها. إذا أردنا تغيير المثيل الذي استدعينا الـ method عليه كجزء مما يفعله الـ method، فسنستخدم &mut self كـ parameter الأول. من النادر أن يكون هناك method يأخذ الـ ownership للمثيل باستخدام self فقط كـ parameter الأول؛ تُستخدم هذه التقنية عادةً عندما يحول الـ method الـ self إلى شيء آخر وتريد منع الـ caller من استخدام المثيل الأصلي بعد التحويل.

السبب الرئيسي لاستخدام الـ methods بدلاً من الـ functions، بالإضافة إلى توفير method syntax وعدم الاضطرار إلى تكرار نوع self في الـ signature لكل method، هو التنظيم. لقد وضعنا كل الأشياء التي يمكننا القيام بها باستخدام مثيل نوع ما في كتلة impl واحدة بدلاً من جعل المستخدمين المستقبليين للكود الخاص بنا يبحثون عن إمكانيات Rectangle في أماكن مختلفة في الـ library التي نقدمها.

لاحظ أنه يمكننا اختيار إعطاء الـ method نفس اسم أحد حقول الـ struct. على سبيل المثال، يمكننا تعريف method على Rectangle يسمى أيضًا width:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

هنا، نختار جعل method width يُرجع true إذا كانت القيمة في حقل width للمثيل أكبر من 0 و false إذا كانت القيمة 0: يمكننا استخدام حقل داخل method يحمل نفس الاسم لأي غرض. في main، عندما نتبع rect1.width بأقواس، تعرف Rust أننا نعني method width. عندما لا نستخدم الأقواس، تعرف Rust أننا نعني حقل width.

في كثير من الأحيان، ولكن ليس دائمًا، عندما نعطي الـ method نفس اسم الحقل، فإننا نريده فقط أن يُرجع القيمة في الحقل ولا يفعل أي شيء آخر. تسمى الـ methods مثل هذه الـ Getters، ولا تطبقها Rust تلقائيًا لحقول الـ struct كما تفعل بعض اللغات الأخرى. الـ Getters مفيدة لأنه يمكنك جعل الحقل خاصًا (private) ولكن الـ method عامًا (public)، وبالتالي تمكين الوصول للقراءة فقط إلى هذا الحقل كجزء من واجهة برمجة التطبيقات العامة (public API) للنوع. سنناقش ما هو public و private وكيفية تعيين حقل أو method كـ public أو private في الفصل 7.

أين عامل التشغيل ->؟

في C و C++، يتم استخدام عاملي تشغيل مختلفين لاستدعاء الـ methods: تستخدم . إذا كنت تستدعي method على الـ object مباشرة وتستخدم -> إذا كنت تستدعي الـ method على مؤشر (pointer) إلى الـ object وتحتاج إلى dereference الـ pointer أولاً. بعبارة أخرى، إذا كان object مؤشرًا، فإن object->something() يشبه (*object).something().

لا تحتوي Rust على ما يعادل عامل التشغيل ->؛ بدلاً من ذلك، تحتوي Rust على ميزة تسمى الإشارة وإلغاء الإشارة التلقائي (automatic referencing and dereferencing). يعد استدعاء الـ methods أحد الأماكن القليلة في Rust التي تتمتع بهذا السلوك.

إليك كيفية عملها: عندما تستدعي method باستخدام object.something()، تضيف Rust تلقائيًا & أو &mut أو * بحيث يتطابق object مع الـ signature للـ method. بعبارة أخرى، ما يلي متماثل:

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

يبدو الأول أكثر نظافة. يعمل سلوك الـ referencing التلقائي هذا لأن الـ methods لها مستقبل واضح - نوع self. بالنظر إلى مستقبل واسم الـ method، يمكن لـ Rust أن تحدد بشكل قاطع ما إذا كان الـ method يقرأ (&self)، أو يغير (&mut self)، أو يستهلك (self). حقيقة أن Rust تجعل الـ borrowing ضمنيًا لمستقبلات الـ method هي جزء كبير من جعل الـ ownership مريحًا (ergonomic) في الممارسة العملية.

الـ Methods ذات الـ Parameters الإضافية

دعنا نتدرب على استخدام الـ methods من خلال تطبيق method ثانٍ على struct Rectangle. هذه المرة نريد أن يأخذ مثيل Rectangle مثيلًا آخر من Rectangle ويُرجع true إذا كان Rectangle الثاني يمكن أن يتناسب تمامًا داخل self (الـ Rectangle الأول)؛ وإلا، يجب أن يُرجع false. أي، بمجرد أن نحدد method can_hold، نريد أن نكون قادرين على كتابة البرنامج الموضح في القائمة 5-14.

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

سيبدو الإخراج المتوقع كما يلي لأن كلا بعدي rect2 أصغر من أبعاد rect1، لكن rect3 أوسع من rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

نعلم أننا نريد تعريف method، لذلك سيكون ضمن كتلة impl Rectangle. سيكون اسم الـ method هو can_hold، وسيأخذ اقتراضًا غير قابل للتغيير (immutable borrow) لـ Rectangle آخر كـ parameter. يمكننا معرفة نوع الـ parameter من خلال النظر إلى الكود الذي يستدعي الـ method: rect1.can_hold(&rect2) يمرر &rect2، وهو immutable borrow لـ rect2، وهو مثيل لـ Rectangle. هذا منطقي لأننا نحتاج فقط إلى قراءة rect2 (بدلاً من الكتابة، مما يعني أننا سنحتاج إلى mutable borrow)، ونريد أن يحتفظ main بـ ownership لـ rect2 حتى نتمكن من استخدامه مرة أخرى بعد استدعاء method can_hold. ستكون القيمة المرجعة لـ can_hold عبارة عن Boolean، وسيقوم الـ implementation بالتحقق مما إذا كان عرض وارتفاع self أكبر من عرض وارتفاع الـ Rectangle الآخر، على التوالي. دعنا نضيف method can_hold الجديد إلى كتلة impl من القائمة 5-13، الموضحة في القائمة 5-15.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

عندما نقوم بتشغيل هذا الكود باستخدام دالة main في القائمة 5-14، سنحصل على الإخراج المطلوب. يمكن أن تأخذ الـ methods parameters متعددة نضيفها إلى الـ signature بعد parameter self، وتعمل هذه الـ parameters تمامًا مثل الـ parameters في الـ functions.

الـ Functions المرتبطة (Associated Functions)

تسمى جميع الـ functions المعرفة داخل كتلة impl الـ functions المرتبطة (associated functions) لأنها مرتبطة بالنوع المسمى بعد impl. يمكننا تعريف associated functions لا تحتوي على self كـ parameter الأول لها (وبالتالي فهي ليست methods) لأنها لا تحتاج إلى مثيل من النوع للعمل معه. لقد استخدمنا بالفعل function واحدًا من هذا القبيل: دالة String::from المعرفة على نوع String.

غالبًا ما تُستخدم الـ associated functions التي ليست methods لـ الـ constructors التي ستُرجع مثيلًا جديدًا من الـ struct. غالبًا ما تسمى هذه new، ولكن new ليس اسمًا خاصًا ولم يتم بناؤه في اللغة. على سبيل المثال، يمكننا اختيار توفير associated function يسمى square والذي سيكون له parameter بعد واحد ويستخدم ذلك كـ عرض وارتفاع، مما يسهل إنشاء Rectangle مربع بدلاً من الاضطرار إلى تحديد نفس القيمة مرتين:

Filename: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

الكلمات المفتاحية Self في نوع الإرجاع وفي نص الـ function هي aliases للنوع الذي يظهر بعد الكلمة المفتاحية impl، وهو في هذه الحالة Rectangle.

لاستدعاء هذا الـ associated function، نستخدم بناء جملة :: مع اسم الـ struct؛ let sq = Rectangle::square(3); هو مثال. هذا الـ function يتم تسميته بواسطة الـ struct: يتم استخدام بناء جملة :: لكل من الـ associated functions والـ namespaces التي تم إنشاؤها بواسطة الـ modules. سنناقش الـ modules في الفصل 7.

كتل impl المتعددة

يُسمح لكل struct أن يكون له كتل impl متعددة. على سبيل المثال، القائمة 5-15 مكافئة للكود الموضح في القائمة 5-16، والذي يحتوي على كل method في كتلة impl خاصة به.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

لا يوجد سبب لفصل هذه الـ methods إلى كتل impl متعددة هنا، ولكن هذا بناء جملة صالح. سنرى حالة تكون فيها كتل impl المتعددة مفيدة في الفصل 10، حيث نناقش الـ generic types والـ traits.

ملخص

تتيح لك الـ Structs إنشاء أنواع مخصصة (custom types) ذات مغزى لـ domain الخاص بك. باستخدام الـ structs، يمكنك الاحتفاظ بأجزاء الـ data المرتبطة متصلة ببعضها البعض وتسمية كل جزء لجعل الكود الخاص بك واضحًا. في كتل impl، يمكنك تعريف الـ functions المرتبطة بنوعك، والـ methods هي نوع من الـ associated function التي تتيح لك تحديد السلوك الذي تتمتع به مثيلات الـ structs الخاصة بك.

لكن الـ structs ليست الطريقة الوحيدة التي يمكنك من خلالها إنشاء custom types: دعنا ننتقل إلى ميزة enum في Rust لإضافة أداة أخرى إلى صندوق أدواتك.

التعدادات ومطابقة الأنماط (Enums and Pattern Matching)

في هذا الفصل، سننظر في التعدادات (Enums)، والتي يشار إليها أيضاً باسم enums. تسمح لك الـ Enums بتعريف نوع من خلال تعداد المتغيرات (variants) الممكنة له. أولاً، سنقوم بتعريف واستخدام enum لإظهار كيف يمكن لـ enum أن يشفر المعنى جنباً إلى جنب مع البيانات. بعد ذلك، سنستكشف enum مفيداً بشكل خاص، يسمى الخيار (Option)، والذي يعبر عن أن القيمة يمكن أن تكون إما شيئاً أو لا شيء. ثم، سننظر في كيفية جعل مطابقة الأنماط (pattern matching) في تعبير match من السهل تشغيل كود مختلف لقيم مختلفة من enum. أخيراً، سنغطي كيف أن بنية if let هي أسلوب برمجي (idiom) آخر مريح وموجز متاح للتعامل مع enums في الكود الخاص بك.

تعريف التعداد (Defining an Enum)

تعريف التعداد (Defining an Enum)

بينما تمنحك الهياكل (structs) طريقة لتجميع الحقول والبيانات ذات الصلة معاً، مثل Rectangle مع width و height الخاصين به، تمنحك التعدادات (enums) طريقة لقول أن القيمة هي واحدة من مجموعة محتملة من القيم. على سبيل المثال، قد نرغب في القول أن Rectangle هو واحد من مجموعة من الأشكال الممكنة التي تتضمن أيضاً Circle و Triangle. للقيام بذلك، يسمح لنا Rust بترميز هذه الاحتمالات كـ enum.

دعونا نلقي نظرة على موقف قد نرغب في التعبير عنه في الكود ونرى لماذا تعد enums مفيدة وأكثر ملاءمة من structs في هذه الحالة. لنفترض أننا بحاجة إلى العمل مع عناوين IP. حالياً، يتم استخدام معيارين رئيسيين لعناوين IP: الإصدار الرابع والإصدار السادس. نظراً لأن هذه هي الاحتمالات الوحيدة لعنوان IP التي سيواجهها برنامجنا، يمكننا تعداد (enumerate) جميع المتغيرات (variants) الممكنة، ومن هنا حصل التعداد على اسمه.

يمكن أن يكون أي عنوان IP إما عنواناً من الإصدار الرابع أو الإصدار السادس، ولكن ليس كلاهما في نفس الوقت. تجعل هذه الخاصية لعناوين IP هيكل بيانات enum مناسباً لأن قيمة enum لا يمكن أن تكون إلا واحدة من variants الخاصة بها. لا تزال عناوين الإصدار الرابع والإصدار السادس في الأساس عناوين IP، لذا يجب معاملتها على أنها من نفس النوع عندما يتعامل الكود مع المواقف التي تنطبق على أي نوع من عناوين IP.

يمكننا التعبير عن هذا المفهوم في الكود من خلال تعريف تعداد IpAddrKind وإدراج الأنواع الممكنة التي يمكن أن يكون عليها عنوان IP، وهي V4 و V6. هذه هي variants الخاصة بالتعداد:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

أصبح IpAddrKind الآن نوع بيانات مخصصاً يمكننا استخدامه في مكان آخر في الكود الخاص بنا.

قيم التعداد (Enum Values)

يمكننا إنشاء مثيلات (instances) لكل من المتغيرين في IpAddrKind كالتالي:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

لاحظ أن variants الخاصة بالتعداد تقع تحت مساحة الاسم (namespaced) الخاصة بمعرفه، ونستخدم نقطتين مزدوجتين للفصل بينهما. هذا مفيد لأن كلا القيمتين IpAddrKind::V4 و IpAddrKind::V6 هما الآن من نفس النوع: IpAddrKind. يمكننا بعد ذلك، على سبيل المثال، تعريف دالة تأخذ أي IpAddrKind:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

ويمكننا استدعاء هذه الدالة بأي من المتغيرين:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

استخدام enums له مزايا أكثر. بالتفكير أكثر في نوع عنوان IP الخاص بنا، في الوقت الحالي ليس لدينا طريقة لتخزين بيانات (data) عنوان IP الفعلية؛ نحن نعرف فقط نوعه. بالنظر إلى أنك تعلمت للتو عن structs في الفصل الخامس، فقد تميل إلى معالجة هذه المشكلة باستخدام structs كما هو موضح في القائمة 6-1.

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

هنا، قمنا بتعريف struct باسم IpAddr يحتوي على حقلين: حقل kind من نوع IpAddrKind (التعداد الذي عرفناه سابقاً) وحقل address من نوع String. لدينا مثيلان من هذا struct. الأول هو home ، وله القيمة IpAddrKind::V4 كـ kind مع بيانات العنوان المرتبطة 127.0.0.1. المثيل الثاني هو loopback. وله المتغير الآخر من IpAddrKind كقيمة لـ kind ، وهو V6 ، وله العنوان ::1 مرتبطاً به. لقد استخدمنا struct لربط قيم kind و address معاً، لذا أصبح المتغير الآن مرتبطاً بالقيمة.

ومع ذلك، فإن تمثيل نفس المفهوم باستخدام enum فقط هو أكثر إيجازاً: بدلاً من enum داخل struct، يمكننا وضع البيانات مباشرة في كل enum variant. يقول هذا التعريف الجديد لتعداد IpAddr أن كلا المتغيرين V4 و V6 سيكون لهما قيم String مرتبطة:

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

نحن نرفق البيانات بكل variant من التعداد مباشرة، لذا لا داعي لـ struct إضافي. هنا، من الأسهل أيضاً رؤية تفصيل آخر لكيفية عمل enums: يصبح اسم كل enum variant نقوم بتعريفه أيضاً دالة تنشئ instance من التعداد. أي أن IpAddr::V4() هو استدعاء دالة يأخذ وسيطاً (argument) من نوع String ويعيد instance من نوع IpAddr. نحصل تلقائياً على دالة البناء (constructor function) هذه نتيجة لتعريف التعداد.

هناك ميزة أخرى لاستخدام enum بدلاً من struct: يمكن أن يكون لكل variant أنواع وكميات مختلفة من البيانات المرتبطة. ستتكون عناوين IP من الإصدار الرابع دائماً من أربعة مكونات رقمية ستكون قيمها بين 0 و 255. إذا أردنا تخزين عناوين V4 كأربع قيم u8 ولكننا لا نزال نريد التعبير عن عناوين V6 كقيمة String واحدة، فلن نتمكن من ذلك باستخدام struct. تتعامل التعدادات مع هذه الحالة بسهولة:

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

لقد عرضنا عدة طرق مختلفة لتعريف هياكل البيانات لتخزين عناوين IP من الإصدار الرابع والسادس. ومع ذلك، كما اتضح، فإن الرغبة في تخزين عناوين IP وترميز نوعها أمر شائع جداً لدرجة أن المكتبة القياسية لديها تعريف يمكننا استخدامه! دعونا نلقي نظرة على كيفية تعريف المكتبة القياسية لـ IpAddr. لديها نفس التعداد والمتغيرات التي عرفناها واستخدمناها، ولكنها تدمج بيانات العنوان داخل variants في شكل اثنين من structs المختلفين، واللذين يتم تعريفهما بشكل مختلف لكل variant:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

يوضح هذا الكود أنه يمكنك وضع أي نوع من البيانات داخل enum variant: سلاسل نصية، أو أنواع رقمية، أو structs، على سبيل المثال. يمكنك حتى تضمين enum آخر! أيضاً، غالباً ما لا تكون أنواع المكتبة القياسية أكثر تعقيداً بكثير مما قد تبتكره أنت.

لاحظ أنه على الرغم من أن المكتبة القياسية تحتوي على تعريف لـ IpAddr ، إلا أنه لا يزال بإمكاننا إنشاء واستخدام تعريفنا الخاص دون تعارض لأننا لم نجلب تعريف المكتبة القياسية إلى نطاقنا (scope). سنتحدث أكثر عن جلب الأنواع إلى النطاق في الفصل السابع.

دعونا نلقي نظرة على مثال آخر لـ enum في القائمة 6-2: هذا المثال يحتوي على مجموعة واسعة من الأنواع المدمجة في variants الخاصة به.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

يحتوي هذا التعداد على أربعة variants بأنواع مختلفة:

• Quit: ليس لديه أي بيانات مرتبطة به على الإطلاق
• Move: يحتوي على حقول مسمى، تماماً كما يفعل struct
• Write: يتضمن String واحدة
• ChangeColor: يتضمن ثلاث قيم i32

تعريف enum مع variants مثل تلك الموجودة في القائمة 6-2 يشبه تعريف أنواع مختلفة من تعريفات struct، باستثناء أن التعداد لا يستخدم الكلمة المفتاحية struct ويتم تجميع جميع variants معاً تحت نوع Message. يمكن لـ structs التالية الاحتفاظ بنفس البيانات التي تحتفظ بها enum variants السابقة:

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

fn main() {}

ولكن إذا استخدمنا structs المختلفة، والتي لكل منها نوعها الخاص، فلن نتمكن بسهولة من تعريف دالة لتأخذ أي نوع من هذه الرسائل كما فعلنا مع تعداد Message المعرف في القائمة 6-2، والذي هو نوع واحد.

هناك تشابه آخر بين enums و structs: تماماً كما يمكننا تعريف دوال (methods) على structs باستخدام impl ، يمكننا أيضاً تعريف methods على enums. إليك method يسمى call يمكننا تعريفه على تعداد Message الخاص بنا:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // method body would be defined here
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

سيستخدم جسم الـ method الكلمة self للحصول على القيمة التي استدعينا الـ method عليها. في هذا المثال، أنشأنا متغيراً m له القيمة Message::Write(String::from("hello")) ، وهذا ما ستكون عليه self في جسم الـ method call عندما يتم تشغيل m.call().

دعونا نلقي نظرة على enum آخر في المكتبة القياسية شائع جداً ومفيد: Option.

تعداد Option (The Option Enum)

يستكشف هذا القسم دراسة حالة لـ Option ، وهو enum آخر معرف بواسطة المكتبة القياسية. يرمز النوع Option للسيناريو الشائع جداً الذي يمكن أن تكون فيه القيمة شيئاً ما، أو قد لا تكون شيئاً (nothing).

على سبيل المثال، إذا طلبت العنصر الأول في قائمة غير فارغة، فستحصل على قيمة. إذا طلبت العنصر الأول في قائمة فارغة، فلن تحصل على شيء. التعبير عن هذا المفهوم من حيث نظام الأنواع (type system) يعني أن المصرف (compiler) يمكنه التحقق مما إذا كنت قد تعاملت مع جميع الحالات التي يجب عليك التعامل معها؛ يمكن لهذه الوظيفة منع الأخطاء البرمجية الشائعة للغاية في لغات البرمجة الأخرى.

غالباً ما يتم التفكير في تصميم لغة البرمجة من حيث الميزات التي تضمنها، ولكن الميزات التي تستبعدها مهمة أيضاً. لا يحتوي Rust على ميزة القيمة الفارغة (null) الموجودة في العديد من اللغات الأخرى. Null هي قيمة تعني عدم وجود قيمة هناك. في اللغات التي تحتوي على null، يمكن أن تكون المتغيرات دائماً في واحدة من حالتين: null أو ليست null.

في عرضه التقديمي لعام 2009 بعنوان “مراجع Null: خطأ المليار دولار” ، قال توني هور، مخترع null، ما يلي:

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

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

ومع ذلك، فإن المفهوم الذي تحاول null التعبير عنه لا يزال مفهوماً مفيداً: null هي قيمة غير صالحة حالياً أو غائبة لسبب ما.

المشكلة ليست حقاً في المفهوم ولكن في التنفيذ المحدد. على هذا النحو، لا يحتوي Rust على nulls، ولكنه يحتوي على enum يمكنه ترميز مفهوم وجود القيمة أو غيابها. هذا التعداد هو Option<T> ، وهو معرف بواسطة المكتبة القياسية كما يلي:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

تعداد Option<T> مفيد جداً لدرجة أنه مضمن في التمهيد (prelude)؛ لست بحاجة إلى جلبه إلى النطاق صراحة. كما أن variants الخاصة به مضمنة في prelude: يمكنك استخدام Some و None مباشرة بدون بادئة Option::. لا يزال تعداد Option<T> مجرد enum عادي، ولا تزال Some(T) و None عبارة عن variants من نوع Option<T>.

بناء الجملة <T> هو ميزة في Rust لم نتحدث عنها بعد. إنه معلمة نوع عام (generic type parameter)، وسنغطي الأنواع العامة (generics) بمزيد من التفصيل في الفصل العاشر. في الوقت الحالي، كل ما تحتاج إلى معرفته هو أن <T> تعني أن المتغير Some من تعداد Option يمكنه الاحتفاظ بقطعة واحدة من البيانات من أي نوع، وأن كل نوع ملموس يتم استخدامه بدلاً من T يجعل نوع Option<T> الإجمالي نوعاً مختلفاً. إليك بعض الأمثلة على استخدام قيم Option للاحتفاظ بأنواع الأرقام وأنواع الأحرف:

#![allow(unused)]
fn main() {
(Content truncated due to size limit. Use line ranges to read remaining content)
}

نوع some_number هو Option<i32>. ونوع some_char هو Option<char> ، وهو نوع مختلف. يمكن لـ Rust استنتاج (infer) هذه الأنواع لأننا حددنا قيمة داخل المتغير Some. بالنسبة لـ absent_number ، يتطلب Rust منا توضيح نوع Option الإجمالي: لا يمكن للمصرف استنتاج النوع الذي سيحتفظ به المتغير Some المقابل من خلال النظر فقط إلى قيمة None. هنا، نخبر Rust أننا نقصد أن يكون absent_number من نوع Option<i32>.

عندما يكون لدينا قيمة Some ، فإننا نعلم أن القيمة موجودة، وأن القيمة محتفظ بها داخل Some. عندما يكون لدينا قيمة None ، فإنها تعني بمعنى ما نفس الشيء مثل null: ليس لدينا قيمة صالحة. إذاً، لماذا يعد وجود Option<T> أفضل من وجود null؟

باختصار، لأن Option<T> و T (حيث يمكن أن يكون T أي نوع) هما نوعان مختلفان، فلن يسمح لنا المصرف باستخدام قيمة Option<T> كما لو كانت بالتأكيد قيمة صالحة. على سبيل المثال، لن يتم تصريف هذا الكود، لأنه يحاول إضافة i8 إلى Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

إذا قمنا بتشغيل هذا الكود، فسنحصل على رسالة خطأ مثل هذه:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            `&i8` implements `Add<i8>`
            `&i8` implements `Add`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `enums` (bin "enums") due to 1 previous error

مثير للاهتمام! في الواقع، تعني رسالة الخطأ هذه أن Rust لا يفهم كيفية إضافة i8 و Option<i8> ، لأنهما نوعان مختلفان. عندما يكون لدينا قيمة من نوع مثل i8 في Rust، سيضمن المصرف أن لدينا دائماً قيمة صالحة. يمكننا المضي قدماً بثقة دون الحاجة إلى التحقق من null قبل استخدام تلك القيمة. فقط عندما يكون لدينا Option<i8> (أو أي نوع من القيم التي نعمل معها) يتعين علينا القلق بشأن احتمال عدم وجود قيمة، وسيضمن المصرف أننا نتعامل مع هذه الحالة قبل استخدام القيمة.

بمعنى آخر، يجب عليك تحويل Option<T> إلى T قبل أن تتمكن من إجراء عمليات T عليها. بشكل عام، يساعد هذا في اكتشاف واحدة من أكثر المشكلات شيوعاً مع null: افتراض أن شيئاً ما ليس null بينما هو كذلك في الواقع.

يساعدك القضاء على خطر الافتراض الخاطئ لقيمة ليست null على أن تكون أكثر ثقة في الكود الخاص بك. لكي يكون لديك قيمة يمكن أن تكون null، يجب عليك اختيار ذلك صراحة بجعل نوع تلك القيمة Option<T>. بعد ذلك، عندما تستخدم تلك القيمة، يطلب منك صراحة التعامل مع الحالة التي تكون فيها القيمة null. في كل مكان يكون فيه للقيمة نوع ليس Option<T> ، يمكنك بأمان افتراض أن القيمة ليست null. كان هذا قراراً تصميمياً متعمداً لـ Rust للحد من انتشار null وزيادة سلامة كود Rust.

إذاً، كيف تحصل على قيمة T من متغير Some عندما يكون لديك قيمة من نوع Option<T> حتى تتمكن من استخدام تلك القيمة؟ يحتوي تعداد Option<T> على عدد كبير من الدوال (methods) المفيدة في مجموعة متنوعة من المواقف؛ يمكنك الاطلاع عليها في توثيقها. سيصبح التعرف على methods الموجودة في Option<T> مفيداً للغاية في رحلتك مع Rust.

بشكل عام، من أجل استخدام قيمة Option<T> ، فأنت تريد كوداً يتعامل مع كل variant. تريد بعض الكود الذي سيتم تشغيله فقط عندما يكون لديك قيمة Some(T) ، ويسمح لهذا الكود باستخدام T الداخلية. وتريد تشغيل كود آخر فقط إذا كان لديك قيمة None ، وهذا الكود ليس لديه قيمة T متاحة. تعبير match هو بنية تدفق تحكم تقوم بذلك بالضبط عند استخدامها مع enums: سيقوم بتشغيل كود مختلف اعتماداً على variant التعداد الذي لديه، ويمكن لهذا الكود استخدام البيانات الموجودة داخل القيمة المطابقة.

بنية تدفق التحكم match

بنية التحكم في التدفق match (The match Control Flow Construct)

تمتلك Rust بنية تحكم في التدفق (control flow construct) قوية للغاية تسمى match تسمح لك بمقارنة قيمة مقابل سلسلة من الأنماط (patterns) ثم تنفيذ الكود بناءً على النمط الذي يتطابق. يمكن أن تتكون الأنماط من قيم حرفية (literal values)، وأسماء متغيرات، وعلامات بديلة (wildcards)، وأشياء أخرى كثيرة؛ يغطي الفصل 19 جميع الأنواع المختلفة من الأنماط وما تفعله. تأتي قوة match من التعبيرية في الأنماط وحقيقة أن المترجم (compiler) يؤكد أن جميع الحالات الممكنة قد تمت معالجتها.

فكر في تعبير match كما لو كان آلة لفرز العملات المعدنية: تنزلق العملات المعدنية على مسار به ثقوب ذات أحجام مختلفة، وتسقط كل عملة في أول ثقب تصادفه وتناسب حجمه. وبنفس الطريقة، تمر القيم عبر كل نمط في match وعند أول نمط “تناسبه” القيمة، تسقط القيمة في كتلة الكود المرتبطة بها لاستخدامها أثناء التنفيذ.

وبالحديث عن العملات المعدنية، دعنا نستخدمها كمثال باستخدام match! يمكننا كتابة دالة تأخذ عملة أمريكية غير معروفة، وبطريقة مماثلة لآلة العد، تحدد نوع العملة وترجع قيمتها بالسنتات، كما هو موضح في القائمة 6-3.

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

دعنا نحلل match في دالة value_in_cents. أولاً، ندرج الكلمة المفتاحية match متبوعة بتعبير، وهو في هذه الحالة القيمة coin. يبدو هذا مشابهًا جدًا للتعبير الشرطي المستخدم مع if ولكن هناك فرق كبير: مع if يجب أن يتم تقييم الشرط إلى قيمة منطقية (Boolean)، ولكن هنا يمكن أن يكون من أي نوع. نوع coin في هذا المثال هو التعداد Coin (enum) الذي عرفناه في السطر الأول.

بعد ذلك تأتي أذرع الـ match (match arms). يتكون الذراع (arm) من جزأين: نمط وكود. الذراع الأول هنا يحتوي على نمط هو القيمة Coin::Penny ثم عامل التشغيل => الذي يفصل بين النمط والكود المراد تشغيله. الكود في هذه الحالة هو مجرد القيمة 1. يتم فصل كل ذراع عن التالي بفاصلة.

عندما يتم تنفيذ تعبير match فإنه يقارن القيمة الناتجة مقابل نمط كل ذراع، بالترتيب. إذا تطابق النمط مع القيمة، يتم تنفيذ الكود المرتبط بهذا النمط. إذا لم يتطابق هذا النمط مع القيمة، يستمر التنفيذ إلى الذراع التالي، تمامًا كما هو الحال في آلة فرز العملات. يمكننا الحصول على عدد الأذرع الذي نحتاجه: في القائمة 6-3، يحتوي الـ match الخاص بنا على أربعة أذرع.

الكود المرتبط بكل ذراع هو تعبير (expression)، والقيمة الناتجة عن التعبير في الذراع المطابق هي القيمة التي يتم إرجاعها لتعبير match بالكامل.

عادة لا نستخدم الأقواس المتعرجة (curly brackets) إذا كان كود ذراع المطابقة قصيرًا، كما هو الحال في القائمة 6-3 حيث يرجع كل ذراع قيمة فقط. إذا كنت تريد تشغيل عدة أسطر من الكود في ذراع مطابقة، فيجب عليك استخدام الأقواس المتعرجة، وتكون الفاصلة التي تلي الذراع اختيارية حينها. على سبيل المثال، يقوم الكود التالي بطباعة “Lucky penny!” في كل مرة يتم فيها استدعاء الدالة بـ Coin::Penny ولكنه لا يزال يرجع القيمة الأخيرة في الكتلة، وهي 1:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

الأنماط التي ترتبط بالقيم (Patterns That Bind to Values)

ميزة أخرى مفيدة لأذرع المطابقة هي أنها يمكن أن ترتبط بأجزاء القيم التي تطابق النمط. هذه هي الطريقة التي يمكننا بها استخراج القيم من متغيرات التعداد (enum variants).

كمثال، دعنا نغير أحد متغيرات التعداد لدينا ليحمل بيانات بداخله. من عام 1999 إلى عام 2008، سكّت الولايات المتحدة أرباع دولارات (quarters) بتصميمات مختلفة لكل ولاية من الولايات الخمسين على أحد الجانبين. لم تحصل أي عملات معدنية أخرى على تصميمات الولايات، لذا فإن أرباع الدولارات فقط هي التي تمتلك هذه القيمة الإضافية. يمكننا إضافة هذه المعلومات إلى الـ enum الخاص بنا عن طريق تغيير متغير Quarter ليشمل قيمة UsState مخزنة بداخله، وهو ما فعلناه في القائمة 6-4.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

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

في تعبير المطابقة لهذا الكود، نضيف متغيرًا يسمى state إلى النمط الذي يطابق قيم المتغير Coin::Quarter. عندما يتطابق Coin::Quarter سيرتبط متغير state بقيمة ولاية ذلك الربع. بعد ذلك، يمكننا استخدام state في الكود الخاص بهذا الذراع، هكذا:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

إذا استدعينا value_in_cents(Coin::Quarter(UsState::Alaska)) فستكون coin هي Coin::Quarter(UsState::Alaska). عندما نقارن تلك القيمة مع كل من أذرع المطابقة، لا يتطابق أي منها حتى نصل إلى Coin::Quarter(state). عند تلك النقطة، سيكون الارتباط لـ state هو القيمة UsState::Alaska. يمكننا بعد ذلك استخدام ذلك الارتباط في تعبير println! وبالتالي استخراج قيمة الولاية الداخلية من متغير تعداد Coin لـ Quarter.

نمط match مع Option<T> (The Option<T> match Pattern)

في القسم السابق، أردنا الحصول على قيمة T الداخلية من حالة Some عند استخدام Option<T>؛ يمكننا أيضًا التعامل مع Option<T> باستخدام match كما فعلنا مع تعداد Coin! بدلاً من مقارنة العملات، سنقارن متغيرات Option<T> ولكن تظل الطريقة التي يعمل بها تعبير match كما هي.

لنفترض أننا نريد كتابة دالة تأخذ Option<i32> وإذا كانت هناك قيمة بداخلها، تضيف 1 إلى تلك القيمة. إذا لم تكن هناك قيمة بداخلها، يجب أن ترجع الدالة القيمة None ولا تحاول إجراء أي عمليات.

هذه الدالة سهلة الكتابة للغاية بفضل match وستبدو مثل القائمة 6-5.

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

دعنا نفحص التنفيذ الأول لـ plus_one بمزيد من التفصيل. عندما نستدعي plus_one(five) سيكون للمتغير x في جسم plus_one القيمة Some(5). ثم نقارن ذلك مقابل كل ذراع مطابقة:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

القيمة Some(5) لا تطابق النمط None لذا نستمر إلى الذراع التالي:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

هل تطابق Some(5) النمط Some(i)؟ نعم! لدينا نفس المتغير. يرتبط i بالقيمة الموجودة في Some لذا يأخذ i القيمة 5. يتم بعد ذلك تنفيذ الكود في ذراع المطابقة، لذا نضيف 1 إلى قيمة i وننشئ قيمة Some جديدة مع مجموعنا 6 بداخلها.

الآن دعنا نفكر في الاستدعاء الثاني لـ plus_one في القائمة 6-5، حيث تكون x هي None. ندخل الـ match ونقارن بالذراع الأول:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

إنه يتطابق! لا توجد قيمة للإضافة إليها، لذا يتوقف البرنامج ويرجع القيمة None على الجانب الأيمن من =>. ولأن الذراع الأول تطابق، لا يتم مقارنة أي أذرع أخرى.

يعد الجمع بين match والتعدادات مفيدًا في العديد من المواقف. سترى هذا النمط كثيرًا في كود Rust: match مقابل تعداد، وربط متغير بالبيانات الموجودة بداخله، ثم تنفيذ الكود بناءً عليه. إنه أمر صعب قليلاً في البداية، ولكن بمجرد أن تعتاد عليه، ستتمنى لو كان لديك في جميع اللغات. إنه المفضل لدى المستخدمين باستمرار.

المطابقات شاملة (Matches Are Exhaustive)

هناك جانب آخر لـ match نحتاج إلى مناقشته: يجب أن تغطي أنماط الأذرع جميع الاحتمالات. فكر في هذا الإصدار من دالة plus_one الذي يحتوي على خطأ (bug) ولن يترجم:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

لم نعالج حالة None لذا سيتسبب هذا الكود في حدوث خطأ. لحسن الحظ، إنه خطأ تعرف Rust كيفية اكتشافه. إذا حاولنا ترجمة هذا الكود، فسنحصل على هذا الخطأ:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:593:1
 ::: /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:597:5
  |
  = note: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `enums` (bin "enums") due to 1 previous error

تعرف Rust أننا لم نغطِ كل حالة ممكنة بل وتعرف النمط الذي نسيناه! المطابقات في Rust شاملة (exhaustive): يجب أن نستنفد كل الاحتمالات الأخيرة لكي يكون الكود صالحًا. خاصة في حالة Option<T> عندما تمنعنا Rust من نسيان التعامل صراحة مع حالة None فإنها تحمينا من افتراض أن لدينا قيمة بينما قد يكون لدينا null، مما يجعل “خطأ المليار دولار” الذي نوقش سابقًا مستحيلاً.

أنماط الالتقاط الشامل والعلامة البديلة _ (Catch-All Patterns and the _ Placeholder)

باستخدام التعدادات، يمكننا أيضًا اتخاذ إجراءات خاصة لعدد قليل من القيم المعينة، ولكن لجميع القيم الأخرى نتخذ إجراءً افتراضيًا واحدًا. تخيل أننا ننفذ لعبة حيث إذا حصلت على 3 في رمية نرد، فلا يتحرك لاعبك ولكنه يحصل بدلاً من ذلك على قبعة جديدة فاخرة. إذا حصلت على 7، يفقد لاعبك قبعة فاخرة. لجميع القيم الأخرى، يتحرك لاعبك بهذا العدد من المساحات على لوحة اللعبة. إليك match ينفذ هذا المنطق، مع كتابة نتيجة رمية النرد بشكل ثابت بدلاً من قيمة عشوائية، وتمثيل كل المنطق الآخر بدوال بدون أجسام لأن تنفيذها الفعلي خارج نطاق هذا المثال:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

بالنسبة لأول ذراعين، الأنماط هي القيم الحرفية 3 و 7. بالنسبة للذراع الأخير الذي يغطي كل قيمة ممكنة أخرى، النمط هو المتغير الذي اخترنا تسميته other. الكود الذي يعمل لذراع other يستخدم المتغير عن طريق تمريره إلى دالة move_player.

يترجم هذا الكود، على الرغم من أننا لم ندرج جميع القيم الممكنة التي يمكن أن يمتلكها u8 لأن النمط الأخير سيطابق جميع القيم غير المدرجة بشكل محدد. يلبي نمط الالتقاط الشامل (catch-all pattern) هذا متطلب أن يكون match شاملاً. لاحظ أنه يجب علينا وضع ذراع الالتقاط الشامل في النهاية لأن الأنماط يتم تقييمها بالترتيب. إذا وضعنا ذراع الالتقاط الشامل في وقت سابق، فلن تعمل الأذرع الأخرى أبدًا، لذا ستحذرنا Rust إذا أضفنا أذرعًا بعد الالتقاط الشامل!

تمتلك Rust أيضًا نمطًا يمكننا استخدامه عندما نريد التقاطًا شاملاً ولكن لا نريد استخدام القيمة في نمط الالتقاط الشامل: _ هو نمط خاص يطابق أي قيمة ولا يرتبط بتلك القيمة. هذا يخبر Rust أننا لن نستخدم القيمة، لذا لن تحذرنا Rust بشأن متغير غير مستخدم.

دعنا نغير قواعد اللعبة: الآن، إذا حصلت على أي شيء آخر غير 3 أو 7، يجب عليك الرمي مرة أخرى. لم نعد بحاجة إلى استخدام قيمة الالتقاط الشامل، لذا يمكننا تغيير كودنا لاستخدام _ بدلاً من المتغير المسمى other:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

يلبي هذا المثال أيضًا متطلب الشمولية لأننا نتجاهل صراحة جميع القيم الأخرى في الذراع الأخير؛ لم ننسَ أي شيء.

أخيرًا، سنغير قواعد اللعبة مرة أخرى بحيث لا يحدث أي شيء آخر في دورك إذا حصلت على أي شيء آخر غير 3 أو 7. يمكننا التعبير عن ذلك باستخدام قيمة الوحدة (unit value) (نوع المجموعة الفارغة الذي ذكرناه في قسم “نوع المجموعة”) ككود يتماشى مع ذراع _:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

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

هناك المزيد حول الأنماط والمطابقة سنغطيه في الفصل 19. في الوقت الحالي، سننتقل إلى بناء جملة if let والذي يمكن أن يكون مفيدًا في المواقف التي يكون فيها تعبير match مطولاً قليلاً.

تدفق التحكم الموجز باستخدام if let و let...else

التحكم في التدفق المختصر باستخدام if let و let...else

تتيح لك صياغة if let دمج if و let في طريقة أقل إسهابًا للتعامل مع القيم التي تطابق نمطًا واحدًا (pattern) مع تجاهل الباقي. لننظر إلى البرنامج في القائمة 6-6 الذي يطابق قيمة Option<u8> في المتغير config_max ولكنه يريد فقط تنفيذ الكود إذا كانت القيمة هي البديل (variant) Some.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

إذا كانت القيمة هي Some، فإننا نطبع القيمة في variant Some عن طريق ربط (binding) القيمة بالمتغير max في pattern. لا نريد أن نفعل أي شيء بقيمة None. لإرضاء تعبير المطابقة (match expression)، يجب علينا إضافة _ => () بعد معالجة variant واحد فقط، وهو كود نمطي مزعج (annoying boilerplate code) للإضافة.

بدلاً من ذلك، يمكننا كتابة هذا بطريقة أقصر باستخدام if let. يتصرف الكود التالي بنفس طريقة match في القائمة 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

تأخذ صياغة if let نمطًا (pattern) وتعبيرًا (expression) مفصولين بعلامة يساوي. يعمل بنفس طريقة match، حيث يتم إعطاء expression إلى match و pattern هو ذراعه الأول (first arm). في هذه الحالة، pattern هو Some(max)، ويرتبط max بالقيمة داخل Some. يمكننا بعد ذلك استخدام max في جسم كتلة if let (if let block) بنفس الطريقة التي استخدمنا بها max في ذراع match المقابل. يتم تشغيل الكود في if let block فقط إذا كانت القيمة تطابق pattern.

استخدام if let يعني كتابة أقل، مسافة بادئة (indentation) أقل، و boilerplate code أقل. ومع ذلك، فإنك تفقد التحقق الشامل (exhaustive checking) الذي يفرضه match والذي يضمن أنك لا تنسى التعامل مع أي حالات. يعتمد الاختيار بين match و if let على ما تفعله في حالتك الخاصة وما إذا كانت اكتساب الإيجاز (conciseness) مقايضة مناسبة لفقدان exhaustive checking.

بمعنى آخر، يمكنك التفكير في if let على أنه سكر صياغي (syntax sugar) لـ match يقوم بتشغيل الكود عندما تطابق القيمة pattern واحدًا ثم تتجاهل جميع القيم الأخرى.

يمكننا تضمين else مع if let. كتلة الكود التي تأتي مع else هي نفسها كتلة الكود التي ستأتي مع حالة _ في match expression المكافئ لـ if let و else. تذكر تعريف التعداد (enum) Coin في القائمة 6-4، حيث احتوى البديل Quarter أيضًا على قيمة UsState. إذا أردنا عد جميع العملات غير الربعية التي نراها مع الإعلان أيضًا عن حالة الأرباع، يمكننا القيام بذلك باستخدام match expression، مثل هذا:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

أو يمكننا استخدام تعبير if let و else، مثل هذا:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

البقاء على “المسار السعيد” (Happy Path) باستخدام let...else

النمط الشائع هو إجراء بعض العمليات الحسابية عندما تكون القيمة موجودة وإرجاع قيمة افتراضية (default value) بخلاف ذلك. استمرارًا في مثالنا للعملات المعدنية بقيمة UsState، إذا أردنا أن نقول شيئًا مضحكًا اعتمادًا على عمر الولاية على الربع، فقد نقدم طريقة (method) على UsState للتحقق من عمر الولاية، مثل هذا:

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

بعد ذلك، قد نستخدم if let للمطابقة على نوع العملة، مع تقديم متغير state داخل جسم الشرط (condition)، كما في القائمة 6-7.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

هذا ينجز المهمة، ولكنه دفع العمل إلى جسم عبارة if let، وإذا كان العمل الذي يتعين القيام به أكثر تعقيدًا، فقد يكون من الصعب متابعة كيفية ارتباط الفروع (branches) ذات المستوى الأعلى بالضبط. يمكننا أيضًا الاستفادة من حقيقة أن التعبيرات (expressions) تنتج قيمة إما لإنتاج state من if let أو للعودة مبكرًا (return early)، كما في القائمة 6-8. (يمكنك القيام بشيء مشابه باستخدام match أيضًا.)

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let state = if let Coin::Quarter(state) = coin {
        state
    } else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

هذا مزعج بعض الشيء للمتابعة بطريقته الخاصة، على الرغم من ذلك! ينتج أحد فروع if let قيمة، والآخر يعود من الدالة (function) بالكامل.

لجعل هذا النمط الشائع أسهل في التعبير، تحتوي Rust على let...else. تأخذ صياغة let...else نمطًا (pattern) على الجانب الأيسر وتعبيرًا (expression) على الجانب الأيمن، مشابهًا جدًا لـ if let، ولكن ليس لديها فرع if، بل فرع else فقط. إذا طابق pattern، فسيربط القيمة من pattern في النطاق الخارجي (outer scope). إذا لم يطابق pattern، فسيتدفق البرنامج إلى ذراع else، والذي يجب أن يعود من function.

في القائمة 6-9، يمكنك أن ترى كيف تبدو القائمة 6-8 عند استخدام let...else بدلاً من if let.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let Coin::Quarter(state) = coin else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

لاحظ أنه يبقى على “المسار السعيد” (happy path) في الجسم الرئيسي لـ function بهذه الطريقة، دون أن يكون لديه تدفق تحكم (control flow) مختلف بشكل كبير لفرعين بالطريقة التي فعلها if let.

إذا كان لديك موقف يحتوي فيه برنامجك على منطق (logic) مطول جدًا للتعبير عنه باستخدام match، فتذكر أن if let و let...else موجودان في صندوق أدوات Rust الخاص بك أيضًا.

ملخص (Summary)

لقد غطينا الآن كيفية استخدام التعدادات (enums) لإنشاء أنواع مخصصة (custom types) يمكن أن تكون واحدة من مجموعة من القيم المعددة. لقد أوضحنا كيف يساعدك نوع Option<T> في المكتبة القياسية (standard library) على استخدام نظام الأنواع (type system) لمنع الأخطاء. عندما تحتوي قيم enum على بيانات بداخلها، يمكنك استخدام match أو if let لاستخراج واستخدام تلك القيم، اعتمادًا على عدد الحالات التي تحتاج إلى التعامل معها.

يمكن لبرامج Rust الخاصة بك الآن التعبير عن المفاهيم في مجالك باستخدام الهياكل (structs) و enums. يضمن إنشاء custom types لاستخدامها في واجهة برمجة التطبيقات (API) الخاصة بك سلامة الأنواع (type safety): سيضمن المترجم (compiler) أن الدوال (functions) الخاصة بك تحصل فقط على قيم من النوع الذي تتوقعه كل دالة.

من أجل توفير API جيد التنظيم لمستخدميك يكون سهل الاستخدام ولا يكشف إلا عما سيحتاجه المستخدمون بالضبط، دعنا ننتقل الآن إلى وحدات Rust (Rust’s modules).

الحزم، والـ Crates، والوحدات (Packages, Crates, and Modules)

بينما تكتب برامج كبيرة، سيصبح تنظيم الكود الخاص بك مهماً بشكل متزايد. من خلال تجميع الوظائف ذات الصلة وفصل الكود ذو الميزات المتميزة، ستوضح مكان العثور على الكود الذي ينفذ ميزة معينة ومكان الذهاب لتغيير كيفية عمل الميزة.

البرامج التي كتبناها حتى الآن كانت في “وحدة” (Module) واحدة في ملف واحد. مع نمو المشروع، يجب عليك تنظيم الكود عن طريق تقسيمه إلى عدة Modules ثم إلى عدة ملفات. يمكن أن تحتوي “الحزمة” (Package) على عدة “صناديق ثنائية” (Binary Crates) واختيارياً “صندوق مكتبة” (Library Crate) واحد. مع نمو الـ Package، يمكنك استخراج أجزاء في Crates منفصلة تصبح تبعيات خارجية. يغطي هذا الفصل كل هذه التقنيات. بالنسبة للمشاريع الكبيرة جداً التي تتكون من مجموعة من الـ Packages المترابطة التي تتطور معاً، يوفر Cargo “مساحات عمل” (Workspaces)، والتي سنغطيها في قسم “مساحات عمل Cargo” في الفصل 14.

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

المفهوم ذو الصلة هو “النطاق” (Scope): السياق المتداخل الذي يتم فيه كتابة الكود يحتوي على مجموعة من الأسماء المعرفة على أنها “داخل النطاق” (In Scope). عند قراءة الكود وكتابته وتجميعه، يحتاج المبرمجون والمترجمون (Compilers) إلى معرفة ما إذا كان اسم معين في بقعة معينة يشير إلى متغير، أو دالة، أو هيكل (Struct)، أو تعداد (Enum)، أو Module، أو ثابت، أو عنصر آخر وماذا يعني ذلك العنصر. يمكنك إنشاء Scopes وتغيير الأسماء الموجودة داخل الـ Scope أو خارجه. لا يمكنك الحصول على عنصرين بنفس الاسم في نفس الـ Scope؛ تتوفر أدوات لحل تعارض الأسماء.

تمتلك Rust عدداً من الميزات التي تتيح لك إدارة تنظيم الكود الخاص بك، بما في ذلك التفاصيل التي يتم كشفها، والتفاصيل الخاصة، والأسماء الموجودة في كل Scope في برامجك. هذه الميزات، التي يشار إليها أحياناً مجتمعة باسم “نظام الوحدات” (Module System)، تشمل:

• الحزم (Packages): ميزة في Cargo تتيح لك بناء واختبار ومشاركة الـ Crates.
• الصناديق (Crates): شجرة من الـ Modules تنتج مكتبة أو ملفاً قابلاً للتنفيذ.
• الوحدات و use (Modules and use): تتيح لك التحكم في التنظيم، والـ Scope، وخصوصية المسارات.
• المسارات (Paths): طريقة لتسمية عنصر، مثل Struct، أو دالة، أو Module.

في هذا الفصل، سنغطي كل هذه الميزات، ونناقش كيفية تفاعلها، ونشرح كيفية استخدامها لإدارة الـ Scope. بنهاية الفصل، يجب أن يكون لديك فهم قوي للـ Module System وأن تكون قادراً على التعامل مع الـ Scopes كالمحترفين!

الحزم والكرات (Packages and Crates)

الحزم والصناديق (Packages and Crates)

الأجزاء الأولى من نظام الوحدات (Module System) التي سنغطيها هي الحزم (Packages) والصناديق (Crates).

الـ “صندوق” (Crate) هو أصغر كمية من الكود يأخذها مترجم Rust (Compiler) في الاعتبار في المرة الواحدة. حتى لو قمت بتشغيل rustc بدلاً من cargo ومررت ملف كود مصدري واحد (كما فعلنا سابقاً في قسم “أساسيات برنامج Rust” في الفصل 1)، فإن الـ Compiler يعتبر ذلك الملف بمثابة Crate. يمكن أن تحتوي الـ Crates على وحدات (Modules)، وقد يتم تعريف الـ Modules في ملفات أخرى يتم تجميعها مع الـ Crate، كما سنرى في الأقسام القادمة.

يمكن أن يأتي الـ Crate في أحد شكلين: “صندوق ثنائي” (Binary Crate) أو “صندوق مكتبة” (Library Crate). الـ “Binary Crates” هي برامج يمكنك تجميعها إلى ملف قابل للتنفيذ يمكنك تشغيله، مثل برنامج سطر أوامر أو خادم. يجب أن يحتوي كل منها على دالة تسمى main تحدد ما يحدث عند تشغيل الملف القابل للتنفيذ. جميع الـ Crates التي أنشأناها حتى الآن كانت Binary Crates.

الـ “Library Crates” لا تحتوي على دالة main ولا يتم تجميعها إلى ملف قابل للتنفيذ. بدلاً من ذلك، فهي تحدد وظائف مخصصة للمشاركة مع مشاريع متعددة. على سبيل المثال، يوفر Crate الـ rand الذي استخدمناه في الفصل 2 وظائف تولد أرقاماً عشوائية. في معظم الأوقات عندما يقول مبرمجو Rust (Rustaceans) كلمة “Crate”، فإنهم يقصدون Library Crate، ويستخدمون كلمة “Crate” بالتبادل مع المفهوم البرمجي العام لـ “المكتبة” (Library).

“جذر الصندوق” (Crate Root) هو ملف مصدري يبدأ منه الـ Compiler ويشكل الـ Module الجذر للـ Crate الخاصة بك (سنشرح الـ Modules بعمق في قسم “التحكم في النطاق والخصوصية باستخدام الوحدات”).

الـ “حزمة” (Package) هي حزمة من Crate واحد أو أكثر توفر مجموعة من الوظائف. تحتوي الـ Package على ملف Cargo.toml يصف كيفية بناء تلك الـ Crates. في الواقع، Cargo هو Package يحتوي على Binary Crate لأداة سطر الأوامر التي كنت تستخدمها لبناء الكود الخاص بك. تحتوي Package الـ Cargo أيضاً على Library Crate يعتمد عليه الـ Binary Crate. يمكن للمشاريع الأخرى الاعتماد على Library Crate الخاص بـ Cargo لاستخدام نفس المنطق الذي تستخدمه أداة سطر أوامر Cargo.

يمكن أن تحتوي الـ Package على أي عدد تريده من الـ Binary Crates، ولكن على الأكثر Library Crate واحد فقط. يجب أن تحتوي الـ Package على Crate واحد على الأقل، سواء كان ذلك Library Crate أو Binary Crate.

دعنا نستعرض ما يحدث عندما ننشئ Package. أولاً، ندخل الأمر cargo new my-project:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

بعد تشغيل cargo new my-project نستخدم ls لنرى ما ينشئه Cargo. في دليل my-project يوجد ملف Cargo.toml مما يمنحنا Package. يوجد أيضاً دليل src يحتوي على main.rs. افتح Cargo.toml في محرر النصوص الخاص بك ولاحظ أنه لا يوجد ذكر لـ src/main.rs. يتبع Cargo اتفاقاً (Convention) مفاده أن src/main.rs هو الـ Crate Root لـ Binary Crate يحمل نفس اسم الـ Package. وبالمثل، يعرف Cargo أنه إذا كان دليل الـ Package يحتوي على src/lib.rs فإن الـ Package تحتوي على Library Crate بنفس اسم الـ Package، ويكون src/lib.rs هو الـ Crate Root الخاص به. يمرر Cargo ملفات الـ Crate Root إلى rustc لبناء المكتبة أو الملف الثنائي.

هنا، لدينا Package تحتوي فقط على src/main.rs مما يعني أنها تحتوي فقط على Binary Crate يسمى my-project. إذا كانت الـ Package تحتوي على src/main.rs و src/lib.rs فإنها تحتوي على صندوقين: Binary و Library، وكلاهما بنفس اسم الـ Package. يمكن أن تحتوي الـ Package على عدة Binary Crates عن طريق وضع الملفات في دليل src/bin: سيكون كل ملف عبارة عن Binary Crate منفصل.

التحكم في النطاق والخصوصية باستخدام الوحدات (Modules)

التحكم في النطاق والخصوصية باستخدام الوحدات البرمجية

في هذا القسم، سنتحدث عن الوحدات البرمجية (modules) وأجزاء أخرى من نظام الوحدات البرمجية (module system)، وتحديداً المسارات (paths)، التي تسمح لك بتسمية العناصر؛ والكلمة المفتاحية use التي تجلب المسار (path) إلى النطاق (scope)؛ والكلمة المفتاحية pub لجعل العناصر عامة (public). سنناقش أيضاً الكلمة المفتاحية as والطرود الخارجية (external packages) وعامل الشمول (glob operator).

ورقة غش الوحدات البرمجية

قبل أن ننتقل إلى تفاصيل modules و paths، نقدم هنا مرجعاً سريعاً حول كيفية عمل modules و paths والكلمة المفتاحية use والكلمة المفتاحية pub في المترجم (compiler)، وكيف ينظم معظم المطورين كودهم. سنمر بأمثلة على كل من هذه القواعد طوال هذا الفصل، ولكن هذا مكان رائع للرجوع إليه كتذكير بكيفية عمل modules.

• البدء من جذر الكريت (crate root): عند تصريف (compiling) كريت (crate)، يبحث compiler أولاً في ملف crate root (عادةً ما يكون src/lib.rs لكريت المكتبة و src/main.rs لكريت ثنائي) عن كود لتصريفه.
• التصريح عن الوحدات البرمجية (Declaring modules): في ملف crate root، يمكنك التصريح عن modules جديدة؛ لنفترض أنك صرحت عن وحدة “garden” باستخدام mod garden;. سيبحث compiler عن كود الوحدة في هذه الأماكن:
  • مضمناً (Inline)، داخل أقواس متعرجة تحل محل الفاصلة المنقوطة التي تلي mod garden
  • في الملف src/garden.rs
  • في الملف src/garden/mod.rs
• التصريح عن الوحدات الفرعية (Declaring submodules): في أي ملف آخر غير crate root، يمكنك التصريح عن وحدات فرعية (submodules). على سبيل المثال، قد تصرح عن mod vegetables; في src/garden.rs. سيبحث compiler عن كود submodule داخل المجلد المسمى باسم الوحدة الأب (parent module) في هذه الأماكن:
  • مضمناً، مباشرة بعد mod vegetables داخل أقواس متعرجة بدلاً من الفاصلة المنقوطة
  • في الملف src/garden/vegetables.rs
  • في الملف src/garden/vegetables/mod.rs
• المسارات إلى الكود في الوحدات البرمجية: بمجرد أن تصبح module جزءاً من crate الخاص بك، يمكنك الرجوع إلى الكود في تلك module من أي مكان آخر في نفس crate، طالما تسمح قواعد الخصوصية (privacy rules) بذلك، باستخدام path المؤدي إلى الكود. على سبيل المثال، سيتم العثور على النوع Asparagus في وحدة vegetables الخاصة بـ garden في crate::garden::vegetables::Asparagus.
• خاص مقابل عام (Private vs. public): الكود داخل module يكون خاصاً (private) عن وحداته الأب بشكل افتراضي. لجعل module عامة (public)، صرح عنها باستخدام pub mod بدلاً من mod. لجعل العناصر داخل public module عامة أيضاً، استخدم pub قبل التصريح عنها.
• الكلمة المفتاحية use: داخل scope، تنشئ الكلمة المفتاحية use اختصارات للعناصر لتقليل تكرار paths الطويلة. في أي scope يمكنه الرجوع إلى crate::garden::vegetables::Asparagus يمكنك إنشاء اختصار باستخدام use crate::garden::vegetables::Asparagus; ومنذ ذلك الحين فصاعداً ستحتاج فقط إلى كتابة Asparagus لاستخدام ذلك النوع في scope.

هنا، ننشئ binary crate باسم backyard يوضح هذه القواعد. يحتوي مجلد crate، المسمى أيضاً backyard، على هذه الملفات والمجلدات:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

ملف crate root في هذه الحالة هو src/main.rs، ويحتوي على:

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

يخبر سطر pub mod garden; المترجم بتضمين الكود الذي يجده في src/garden.rs، وهو:

pub mod vegetables;

هنا، تعني pub mod vegetables; أن الكود في src/garden/vegetables.rs مضمن أيضاً. هذا الكود هو:

#[derive(Debug)]
pub struct Asparagus {}

الآن دعونا ندخل في تفاصيل هذه القواعد ونستعرضها عملياً!

تجميع الكود ذو الصلة في وحدات برمجية

تسمح لنا Modules بتنظيم الكود داخل crate لسهولة القراءة وإعادة الاستخدام. تسمح لنا modules أيضاً بالتحكم في خصوصية العناصر لأن الكود داخل module يكون private بشكل افتراضي. العناصر الخاصة هي تفاصيل تنفيذ داخلية (internal implementation details) غير متاحة للاستخدام الخارجي. يمكننا اختيار جعل modules والعناصر داخلها public، مما يكشفها للسماح للكود الخارجي باستخدامها والاعتماد عليها.

كمثال، لنكتب library crate يوفر وظائف مطعم. سنحدد تواقيع الدوال (function signatures) ولكن سنترك أجسامها فارغة للتركيز على تنظيم الكود بدلاً من تنفيذ (implementation) المطعم.

في صناعة المطاعم، يشار إلى بعض أجزاء المطعم باسم “واجهة المطعم” (front of house) وأجزاء أخرى باسم “خلفية المطعم” (back of house). Front of house هو المكان الذي يتواجد فيه الزبائن؛ وهذا يشمل المكان الذي يجلس فيه المضيفون الزبائن، ويأخذ فيه النادلون الطلبات والمدفوعات، ويقوم فيه السقاة بإعداد المشروبات. Back of house هو المكان الذي يعمل فيه الطهاة في المطبخ، ويقوم فيه غاسلو الأطباق بالتنظيف، ويقوم فيه المديرون بالعمل الإداري.

لهيكلة crate الخاص بنا بهذه الطريقة، يمكننا تنظيم دواله في modules متداخلة. أنشئ مكتبة جديدة باسم restaurant عن طريق تشغيل cargo new restaurant --lib. ثم أدخل الكود الموجود في القائمة 7-1 في src/lib.rs لتعريف بعض modules وتواقيع الدوال؛ هذا الكود هو قسم front of house.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

نحدد module باستخدام الكلمة المفتاحية mod متبوعة باسم module (في هذه الحالة، front_of_house). ثم يوضع جسم module داخل أقواس متعرجة. داخل modules، يمكننا وضع modules أخرى، كما في هذه الحالة مع الوحدتين hosting و serving. يمكن أن تحتوي modules أيضاً على تعريفات لعناصر أخرى، مثل الهياكل (structs) والتعدادات (enums) والثوابت (constants) والسمات (traits) وكما في القائمة 7-1، الدوال (functions).

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

ذكرنا سابقاً أن src/main.rs و src/lib.rs يسمى كل منهما crate roots. والسبب في تسميتهما هو أن محتويات أي من هذين الملفين تشكل module تسمى crate في جذر هيكل الوحدات البرمجية للكريت، والمعروف باسم شجرة الوحدات البرمجية (module tree).

توضح القائمة 7-2 module tree للهيكل الموجود في القائمة 7-1.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

توضح هذه الشجرة كيف تتداخل بعض modules داخل modules أخرى؛ على سبيل المثال، hosting يتداخل داخل front_of_house. توضح الشجرة أيضاً أن بعض modules هي أشقاء (siblings)، مما يعني أنها معرفة في نفس module؛ hosting و serving هما siblings معرفان داخل front_of_house. إذا كانت الوحدة A محتواة داخل الوحدة B، فإننا نقول إن الوحدة A هي الابن (child) للوحدة B وأن الوحدة B هي الأب (parent) للوحدة A. لاحظ أن module tree بالكامل متجذرة تحت module الضمنية المسماة crate.

قد تذكرك module tree بشجرة مجلدات نظام الملفات على جهاز الكمبيوتر الخاص بك؛ هذا تشبيه دقيق للغاية! تماماً مثل المجلدات في نظام الملفات، تستخدم modules لتنظيم كودك. وتماماً مثل الملفات في المجلد، نحتاج إلى طريقة للعثور على modules الخاصة بنا.

المسارات للإشارة إلى عنصر في شجرة الوحدات (Module Tree)

المسارات (Paths) للإشارة إلى عنصر في شجرة الوحدات (Module Tree)

لإظهار لغة Rust أين تجد عنصرًا في شجرة الوحدات (module tree)، نستخدم مسارًا (path) بنفس الطريقة التي نستخدم بها مسارًا عند التنقل في نظام الملفات (filesystem). لاستدعاء دالة (function)، نحتاج إلى معرفة مسارها.

يمكن أن يتخذ المسار شكلين:

• المسار المطلق (Absolute path) هو المسار الكامل الذي يبدأ من جذر الصندوق (crate root)؛ بالنسبة للكود من صندوق خارجي (external crate)، يبدأ المسار المطلق باسم الـ crate، وبالنسبة للكود من الـ crate الحالي، يبدأ بالحرف crate.
• المسار النسبي (Relative path) يبدأ من الوحدة (module) الحالية ويستخدم self أو super أو معرفًا (identifier) في الـ module الحالي.

يتبع كل من الـ absolute paths والـ relative paths بمعرف واحد أو أكثر مفصول بعلامتي نقطتين مزدوجتين (::).

بالعودة إلى القائمة 7-1، لنفترض أننا نريد استدعاء الدالة add_to_waitlist. هذا هو نفس السؤال: ما هو مسار الدالة add_to_waitlist؟ تحتوي القائمة 7-3 على القائمة 7-1 مع إزالة بعض الـ modules والدوال.

سنعرض طريقتين لاستدعاء الدالة add_to_waitlist من دالة جديدة، eat_at_restaurant، محددة في الـ crate root. هذه المسارات صحيحة، ولكن هناك مشكلة أخرى متبقية ستمنع هذا المثال من الـ compile كما هو. سنشرح السبب بعد قليل.

تعد الدالة eat_at_restaurant جزءًا من واجهة برمجة التطبيقات العامة (public API) لـ library crate الخاص بنا، لذلك نضع علامة عليها بالكلمة المفتاحية pub. في قسم “كشف المسارات باستخدام الكلمة المفتاحية pub”، سنتعمق في تفاصيل أكثر حول pub.

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

في المرة الأولى التي نستدعي فيها الدالة add_to_waitlist في eat_at_restaurant، نستخدم absolute path. تم تعريف الدالة add_to_waitlist في نفس الـ crate مثل eat_at_restaurant، مما يعني أنه يمكننا استخدام الكلمة المفتاحية crate لبدء absolute path. ثم نقوم بتضمين كل من الـ modules المتتالية حتى نصل إلى add_to_waitlist. يمكنك تخيل filesystem بنفس الهيكل: سنحدد المسار /front_of_house/hosting/add_to_waitlist لتشغيل برنامج add_to_waitlist؛ استخدام اسم الـ crate للبدء من الـ crate root يشبه استخدام / للبدء من جذر نظام الملفات في الـ shell الخاص بك.

في المرة الثانية التي نستدعي فيها add_to_waitlist في eat_at_restaurant، نستخدم relative path. يبدأ المسار بـ front_of_house، وهو اسم الـ module المحدد في نفس مستوى الـ module tree مثل eat_at_restaurant. هنا، سيكون مكافئ نظام الملفات هو استخدام المسار front_of_house/hosting/add_to_waitlist. البدء باسم module يعني أن المسار نسبي.

إن اختيار ما إذا كنت ستستخدم relative path أو absolute path هو قرار ستتخذه بناءً على مشروعك، ويعتمد على ما إذا كنت أكثر عرضة لنقل كود تعريف العنصر بشكل منفصل عن الكود الذي يستخدم العنصر أو معه. على سبيل المثال، إذا نقلنا الـ module front_of_house والدالة eat_at_restaurant إلى module يسمى customer_experience، فسنحتاج إلى تحديث الـ absolute path إلى add_to_waitlist، لكن الـ relative path سيظل صالحًا. ومع ذلك، إذا نقلنا الدالة eat_at_restaurant بشكل منفصل إلى module يسمى dining، فسيظل الـ absolute path إلى استدعاء add_to_waitlist كما هو، ولكن سيحتاج الـ relative path إلى التحديث. تفضيلنا بشكل عام هو تحديد absolute paths لأنه من المرجح أننا سنرغب في نقل تعريفات الكود واستدعاءات العناصر بشكل مستقل عن بعضها البعض.

دعنا نحاول compile القائمة 7-3 ونكتشف سبب عدم الـ compile بعد! تظهر الأخطاء التي نحصل عليها في القائمة 7-4.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
  |                            |
  |                            private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
   |                     |
   |                     private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
 2 |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

تقول رسائل الخطأ أن الـ module hosting خاص (private). بعبارة أخرى، لدينا المسارات الصحيحة لـ module hosting والدالة add_to_waitlist، لكن Rust لن تسمح لنا باستخدامها لأنه ليس لديها وصول إلى الأقسام الـ private. في Rust، تكون جميع العناصر (الدوال، الـ methods، الـ structs، الـ enums، الـ modules، والثوابت) خاصة بـ parent modules افتراضيًا. إذا كنت تريد جعل عنصر مثل function أو struct خاصًا، فستضعه في module.

لا يمكن للعناصر الموجودة في parent module استخدام العناصر الـ private داخل child modules، ولكن يمكن للعناصر الموجودة في child modules استخدام العناصر الموجودة في ancestor modules الخاصة بها. هذا لأن الـ child modules تغلف وتخفي تفاصيل التطبيق الخاصة بها، ولكن يمكن لـ child modules رؤية السياق الذي تم تعريفها فيه. لمواصلة استعارتنا، فكر في قواعد الخصوصية على أنها مثل المكتب الخلفي للمطعم: ما يحدث هناك خاص لعملاء المطعم، ولكن يمكن لمديري المكاتب رؤية والقيام بكل شيء في المطعم الذي يديرونه.

اختارت Rust أن يعمل نظام الـ module بهذه الطريقة بحيث يكون إخفاء تفاصيل التطبيق الداخلية هو الافتراضي. بهذه الطريقة، تعرف أي أجزاء من الكود الداخلي يمكنك تغييرها دون كسر الكود الخارجي. ومع ذلك، تمنحك Rust خيار كشف الأجزاء الداخلية من كود الـ child modules لـ ancestor modules الخارجية باستخدام الكلمة المفتاحية pub لجعل العنصر عامًا (public).

كشف المسارات باستخدام الكلمة المفتاحية pub

دعنا نعود إلى الخطأ في القائمة 7-4 الذي أخبرنا أن الـ module hosting خاص. نريد أن يكون للدالة eat_at_restaurant في الـ parent module وصول إلى الدالة add_to_waitlist في الـ child module، لذلك نضع علامة على الـ module hosting بالكلمة المفتاحية pub، كما هو موضح في القائمة 7-5.

mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

لسوء الحظ، لا يزال الكود في القائمة 7-5 يؤدي إلى أخطاء في الـ compiler، كما هو موضح في القائمة 7-6.

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:10:37
   |
10 |     crate::front_of_house::hosting::add_to_waitlist();
   |                                     ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:13:30
   |
13 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

ماذا حدث؟ إضافة الكلمة المفتاحية pub أمام mod hosting تجعل الـ module عامًا. مع هذا التغيير، إذا تمكنا من الوصول إلى front_of_house، فيمكننا الوصول إلى hosting. لكن محتويات hosting لا تزال خاصة؛ جعل الـ module عامًا لا يجعل محتوياته عامة. تسمح الكلمة المفتاحية pub على module فقط للكود الموجود في ancestor modules بالإشارة إليه، وليس الوصول إلى الكود الداخلي الخاص به. نظرًا لأن الـ modules هي حاويات، فلا يمكننا فعل الكثير بمجرد جعل الـ module عامًا؛ نحتاج إلى المضي قدمًا واختيار جعل عنصر واحد أو أكثر داخل الـ module عامًا أيضًا.

تقول الأخطاء في القائمة 7-6 أن الدالة add_to_waitlist خاصة. تنطبق قواعد الخصوصية على الـ structs، الـ enums، الـ functions، والـ methods بالإضافة إلى الـ modules.

دعنا نجعل الدالة add_to_waitlist عامة أيضًا عن طريق إضافة الكلمة المفتاحية pub قبل تعريفها، كما في القائمة 7-7.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

الآن سيتم الـ compile للكود! لمعرفة سبب سماح إضافة الكلمة المفتاحية pub لنا باستخدام هذه المسارات في eat_at_restaurant فيما يتعلق بقواعد الخصوصية، دعنا ننظر إلى الـ absolute paths والـ relative paths.

في الـ absolute path، نبدأ بـ crate، وهو جذر الـ module tree لـ crate الخاص بنا. تم تعريف الـ module front_of_house في الـ crate root. على الرغم من أن front_of_house ليس عامًا، نظرًا لأن الدالة eat_at_restaurant محددة في نفس الـ module مثل front_of_house (أي أن eat_at_restaurant و front_of_house هما شقيقان)، يمكننا الإشارة إلى front_of_house من eat_at_restaurant. التالي هو الـ module hosting الذي تم وضع علامة عليه بـ pub. يمكننا الوصول إلى الـ parent module لـ hosting، لذلك يمكننا الوصول إلى hosting. أخيرًا، تم وضع علامة على الدالة add_to_waitlist بـ pub، ويمكننا الوصول إلى الـ parent module الخاص بها، لذا فإن استدعاء الدالة هذا يعمل!

في الـ relative path، يكون المنطق هو نفسه الـ absolute path باستثناء الخطوة الأولى: بدلاً من البدء من الـ crate root، يبدأ المسار من front_of_house. تم تعريف الـ module front_of_house داخل نفس الـ module مثل eat_at_restaurant، لذا فإن الـ relative path الذي يبدأ من الـ module الذي تم تعريف eat_at_restaurant فيه يعمل. بعد ذلك، نظرًا لأن hosting و add_to_waitlist تم وضع علامة عليهما بـ pub، فإن بقية المسار يعمل، واستدعاء الدالة هذا صالح!

إذا كنت تخطط لمشاركة library crate الخاص بك بحيث يمكن للمشاريع الأخرى استخدام الكود الخاص بك، فإن الـ public API الخاص بك هو عقدك مع مستخدمي الـ crate الخاص بك الذي يحدد كيفية تفاعلهم مع الكود الخاص بك. هناك العديد من الاعتبارات حول إدارة التغييرات على الـ public API الخاص بك لتسهيل اعتماد الأشخاص على الـ crate الخاص بك. هذه الاعتبارات تتجاوز نطاق هذا الكتاب؛ إذا كنت مهتمًا بهذا الموضوع، فراجع إرشادات Rust API.

أفضل الممارسات للحزم التي تحتوي على ثنائي ومكتبة (Binary and a Library)

ذكرنا أن الحزمة يمكن أن تحتوي على كل من جذر الـ binary crate src/main.rs بالإضافة إلى جذر الـ library crate src/lib.rs، وسيكون لكلا الـ crates اسم الحزمة افتراضيًا. عادةً، تحتوي الحزم التي تحتوي على هذا النمط من احتواء كل من library crate و binary crate على كود كافٍ فقط في الـ binary crate لبدء ملف تنفيذي يستدعي الكود المحدد في الـ library crate. يتيح ذلك للمشاريع الأخرى الاستفادة من معظم الوظائف التي توفرها الحزمة لأنه يمكن مشاركة كود الـ library crate.

يجب تعريف الـ module tree في src/lib.rs. بعد ذلك، يمكن استخدام أي عناصر عامة في الـ binary crate عن طريق بدء المسارات باسم الحزمة. يصبح الـ binary crate مستخدمًا لـ library crate تمامًا مثلما يستخدم الـ external crate بالكامل الـ library crate: يمكنه فقط استخدام الـ public API. يساعدك هذا في تصميم API جيد؛ لست أنت المؤلف فحسب، بل أنت أيضًا عميل!

في الفصل 12، سنوضح هذه الممارسة التنظيمية باستخدام برنامج سطر أوامر سيحتوي على كل من binary crate و library crate.

بدء الـ Relative Paths بـ super

يمكننا إنشاء relative paths تبدأ في الـ parent module، بدلاً من الـ module الحالي أو الـ crate root، باستخدام super في بداية المسار. هذا يشبه بدء مسار filesystem ببناء جملة .. الذي يعني الانتقال إلى الدليل الأصل (parent directory). يسمح لنا استخدام super بالإشارة إلى عنصر نعرف أنه موجود في الـ parent module، مما قد يجعل إعادة ترتيب الـ module tree أسهل عندما يكون الـ module مرتبطًا ارتباطًا وثيقًا بالـ parent ولكن قد يتم نقل الـ parent إلى مكان آخر في الـ module tree في يوم من الأيام.

ضع في اعتبارك الكود في القائمة 7-8 الذي يصمم الموقف الذي يقوم فيه طاهٍ بإصلاح طلب غير صحيح ويحضره شخصيًا إلى العميل. تستدعي الدالة fix_incorrect_order المحددة في الـ module back_of_house الدالة deliver_order المحددة في الـ parent module عن طريق تحديد المسار إلى deliver_order، بدءًا من super.

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

توجد الدالة fix_incorrect_order في الـ module back_of_house، لذلك يمكننا استخدام super للانتقال إلى الـ parent module لـ back_of_house، وهو في هذه الحالة crate، الجذر. من هناك، نبحث عن deliver_order ونجده. نجاح! نعتقد أن الـ module back_of_house والدالة deliver_order من المرجح أن يظلا في نفس العلاقة مع بعضهما البعض ويتم نقلهما معًا إذا قررنا إعادة تنظيم الـ module tree لـ crate. لذلك، استخدمنا super حتى يكون لدينا عدد أقل من الأماكن لتحديث الكود فيها في المستقبل إذا تم نقل هذا الكود إلى module مختلف.

جعل الـ Structs والـ Enums عامة

يمكننا أيضًا استخدام pub لتعيين الـ structs والـ enums كـ public، ولكن هناك بعض الاختلافات. إذا وضعنا pub قبل تعريف struct، فإننا نجعل الـ struct عامًا، لكن الـ fields الخاصة بالـ struct ستظل خاصة. يمكننا جعل كل field عامًا أو لا على أساس كل حالة على حدة. في القائمة 7-9، قمنا بتعريف struct عام back_of_house::Breakfast مع field عام toast ولكن field خاص seasonal_fruit. يصمم هذا الحالة في مطعم حيث يمكن للعميل اختيار نوع الخبز الذي يأتي مع الوجبة، لكن الطاهي يقرر الفاكهة التي تصاحب الوجبة بناءً على ما هو موسمي ومتوفر. تتغير الفاكهة المتاحة بسرعة، لذلك لا يمكن للعملاء اختيار الفاكهة أو حتى رؤية الفاكهة التي سيحصلون عليها.

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal.
    // meal.seasonal_fruit = String::from("blueberries");
}

نظرًا لأن الـ field toast في struct back_of_house::Breakfast عام، في eat_at_restaurant يمكننا الكتابة والقراءة إلى الـ field toast باستخدام تدوين النقطة (dot notation). لاحظ أنه لا يمكننا استخدام الـ field seasonal_fruit في eat_at_restaurant، لأن seasonal_fruit خاص. حاول إلغاء التعليق على السطر الذي يعدل قيمة الـ field seasonal_fruit لترى الخطأ الذي تحصل عليه!

لاحظ أيضًا أنه نظرًا لأن back_of_house::Breakfast يحتوي على field خاص، يحتاج الـ struct إلى توفير دالة مرتبطة عامة تنشئ مثيلًا لـ Breakfast (لقد أطلقنا عليها اسم summer هنا). إذا لم يكن لدى Breakfast مثل هذه الدالة، فلن نتمكن من إنشاء مثيل لـ Breakfast في eat_at_restaurant، لأننا لا يمكننا تعيين قيمة الـ field الخاص seasonal_fruit في eat_at_restaurant.

في المقابل، إذا جعلنا enum عامًا، فإن جميع متغيراته (variants) تكون عامة. نحتاج فقط إلى pub قبل الكلمة المفتاحية enum، كما هو موضح في القائمة 7-10.

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

نظرًا لأننا جعلنا الـ enum Appetizer عامًا، يمكننا استخدام الـ variants Soup و Salad في eat_at_restaurant.

الـ Enums ليست مفيدة جدًا ما لم تكن متغيراتها عامة؛ سيكون من المزعج الاضطرار إلى إضافة تعليق توضيحي لجميع enum variants بـ pub في كل حالة، لذا فإن الإعداد الافتراضي لـ enum variants هو أن تكون عامة. غالبًا ما تكون الـ Structs مفيدة دون أن تكون الـ fields الخاصة بها عامة، لذا تتبع الـ struct fields القاعدة العامة المتمثلة في أن كل شيء خاص افتراضيًا ما لم يتم وضع علامة عليه بـ pub.

هناك موقف آخر يتعلق بـ pub لم نقم بتغطيته، وهو آخر ميزة لنظام الـ module: الكلمة المفتاحية use. سنغطي use بمفردها أولاً، ثم سنوضح كيفية دمج pub و use.

جلب المسارات إلى النطاق باستخدام الكلمة المفتاحية use

جلب المسارات إلى النطاق باستخدام الكلمة المفتاحية use (Bringing Paths into Scope with the use Keyword)

قد يكون الاضطرار إلى كتابة (المسارات) paths بالكامل لاستدعاء الدوال أمراً غير مريح ومتكرراً. في القائمة 7-7، سواء اخترنا المسار المطلق أو النسبي لدالة add_to_waitlist ، كان علينا في كل مرة نريد فيها استدعاء add_to_waitlist تحديد front_of_house و hosting أيضاً. لحسن الحظ، هناك طريقة لتبسيط هذه العملية: يمكننا إنشاء اختصار لمسار باستخدام الكلمة المفتاحية use مرة واحدة، ثم استخدام الاسم الأقصر في أي مكان آخر في (النطاق) scope.

في القائمة 7-11، نقوم بجلب (الوحدة) module المسماة crate::front_of_house::hosting إلى نطاق دالة eat_at_restaurant بحيث نضطر فقط إلى تحديد hosting::add_to_waitlist لاستدعاء دالة add_to_waitlist في eat_at_restaurant.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

إضافة use ومسار في نطاق ما يشبه إنشاء (رابط رمزي) symbolic link في نظام الملفات. من خلال إضافة use crate::front_of_house::hosting في جذر الصندوق، أصبح hosting الآن اسماً صالحاً في ذلك النطاق، تماماً كما لو تم تعريف وحدة hosting في جذر الصندوق. المسارات التي يتم جلبها إلى النطاق باستخدام use تخضع أيضاً لفحص (الخصوصية) privacy ، مثل أي مسارات أخرى.

لاحظ أن use تنشئ الاختصار فقط للنطاق المحدد الذي تظهر فيه use. تقوم القائمة 7-12 بنقل دالة eat_at_restaurant إلى وحدة فرعية جديدة تسمى customer ، والتي تعد نطاقاً مختلفاً عن عبارة use ، لذا لن يتم تجميع جسم الدالة.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}

يظهر خطأ المترجم أن الاختصار لم يعد ينطبق داخل وحدة customer:

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: failed to resolve: use of unresolved module or unlinked crate `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of unresolved module or unlinked crate `hosting`
   |
   = help: if you wanted to use a crate named `hosting`, use `cargo add hosting` to add it to your `Cargo.toml`
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

لاحظ أن هناك أيضاً تحذيراً بأن use لم تعد مستخدمة في نطاقها! لإصلاح هذه المشكلة، انقل use داخل وحدة customer أيضاً، أو أشر إلى الاختصار في الوحدة الأب باستخدام super::hosting داخل الوحدة الفرعية customer.

إنشاء مسارات use اصطلاحية (Creating Idiomatic use Paths)

في القائمة 7-11، ربما تساءلت لماذا حددنا use crate::front_of_house::hosting ثم استدعينا hosting::add_to_waitlist في eat_at_restaurant ، بدلاً من تحديد مسار use بالكامل وصولاً إلى دالة add_to_waitlist لتحقيق نفس النتيجة، كما في القائمة 7-13.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}

على الرغم من أن كلاً من القائمة 7-11 والقائمة 7-13 تنجزان نفس المهمة، إلا أن القائمة 7-11 هي الطريقة (الاصطلاحية) idiomatic لجلب دالة إلى النطاق باستخدام use. جلب الوحدة الأب للدالة إلى النطاق باستخدام use يعني أنه يجب علينا تحديد الوحدة الأب عند استدعاء الدالة. تحديد الوحدة الأب عند استدعاء الدالة يجعل من الواضح أن الدالة ليست معرفة محلياً مع تقليل تكرار المسار الكامل. الكود في القائمة 7-13 غير واضح فيما يتعلق بمكان تعريف add_to_waitlist.

من ناحية أخرى، عند جلب (الهياكل) structs و (التعدادات) enums والعناصر الأخرى باستخدام use ، فمن الاصطلاحي تحديد المسار الكامل. تعرض القائمة 7-14 الطريقة الاصطلاحية لجلب هيكل HashMap من المكتبة القياسية إلى نطاق صندوق ثنائي.

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

لا يوجد سبب قوي وراء هذا الاصطلاح: إنه مجرد العرف الذي ظهر، واعتاد الناس على قراءة وكتابة كود Rust بهذه الطريقة.

الاستثناء من هذا الاصطلاح هو إذا كنا نجلب عنصرين بنفس الاسم إلى النطاق باستخدام عبارات use ، لأن Rust لا تسمح بذلك. تعرض القائمة 7-15 كيفية جلب نوعين من Result إلى النطاق لهما نفس الاسم ولكن وحدات أب مختلفة، وكيفية الإشارة إليهما.

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

كما ترى، فإن استخدام الوحدات الأب يميز بين نوعي Result. إذا حددنا بدلاً من ذلك use std::fmt::Result و use std::io::Result ، فسيكون لدينا نوعان من Result في نفس النطاق، ولن تعرف Rust أيهما نقصد عندما نستخدم Result.

توفير أسماء جديدة باستخدام الكلمة المفتاحية as (Providing New Names with the as Keyword)

هناك حل آخر لمشكلة جلب نوعين من نفس الاسم إلى نفس النطاق باستخدام use: بعد المسار، يمكننا تحديد as واسم محلي جديد، أو (اسم مستعار) alias ، للنوع. تعرض القائمة 7-16 طريقة أخرى لكتابة الكود في القائمة 7-15 عن طريق إعادة تسمية أحد نوعي Result باستخدام as.

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

في عبارة use الثانية، اخترنا الاسم الجديد IoResult لنوع std::io::Result ، والذي لن يتعارض مع Result من std::fmt الذي جلبناه أيضاً إلى النطاق. تعتبر كل من القائمة 7-15 والقائمة 7-16 اصطلاحية، لذا فالخيار متروك لك!

إعادة تصدير الأسماء باستخدام pub use (Re-exporting Names with pub use)

عندما نجلب اسماً إلى النطاق باستخدام الكلمة المفتاحية use ، يكون الاسم خاصاً بالنطاق الذي استوردناه إليه. لتمكين الكود خارج ذلك النطاق من الإشارة إلى ذلك الاسم كما لو كان قد تم تعريفه في ذلك النطاق، يمكننا الجمع بين pub و use. تسمى هذه التقنية (إعادة التصدير) re-exporting لأننا نجلب عنصراً إلى النطاق ولكننا نجعله متاحاً أيضاً للآخرين لجلبه إلى نطاقهم.

تعرض القائمة 7-17 الكود في القائمة 7-11 مع تغيير use في الوحدة الجذرية إلى pub use.

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

قبل هذا التغيير، كان على الكود الخارجي استدعاء دالة add_to_waitlist باستخدام المسار restaurant::front_of_house::hosting::add_to_waitlist() ، والذي كان سيتطلب أيضاً وضع علامة pub على وحدة front_of_house. الآن بعد أن قامت pub use بإعادة تصدير وحدة hosting من الوحدة الجذرية، يمكن للكود الخارجي استخدام المسار restaurant::hosting::add_to_waitlist() بدلاً من ذلك.

تعد إعادة التصدير مفيدة عندما يكون الهيكل الداخلي لكودك مختلفاً عن الطريقة التي يفكر بها المبرمجون الذين يستدعون كودك حول المجال. على سبيل المثال، في استعارة المطعم هذه، يفكر الأشخاص الذين يديرون المطعم في “واجهة المطعم” و “خلفية المطعم”. لكن الزبائن الذين يزورون المطعم ربما لن يفكروا في أجزاء المطعم بهذه المصطلحات. باستخدام pub use ، يمكننا كتابة كودنا بهيكل واحد ولكن كشف هيكل مختلف. القيام بذلك يجعل مكتبتنا منظمة بشكل جيد للمبرمجين الذين يعملون على المكتبة والمبرمجين الذين يستدعون المكتبة. سنلقي نظرة على مثال آخر لـ pub use وكيف تؤثر على توثيق صندوقك في “تصدير واجهة برمجة تطبيقات عامة مريحة” في الفصل 14.

استخدام الحزم الخارجية (Using External Packages)

في الفصل الثاني، قمنا ببرمجة مشروع لعبة تخمين استخدم حزمة خارجية تسمى rand للحصول على أرقام عشوائية. لاستخدام rand في مشروعنا، أضفنا هذا السطر إلى Cargo.toml:

rand = "0.8.5"

إضافة rand كـ dependency في Cargo.toml يخبر Cargo بتنزيل حزمة rand وأي تبعيات من crates.io وجعل rand متاحاً لمشروعنا.

بعد ذلك، لجلب تعريفات rand إلى نطاق حزمتنا، أضفنا سطر use يبدأ باسم الصندوق، rand ، ودرجنا العناصر التي أردنا جلبها إلى النطاق. تذكر أنه في “توليد رقم عشوائي” في الفصل الثاني، جلبنا (سمة) trait المسماة Rng إلى النطاق واستدعينا دالة rand::thread_rng:

use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

قام أعضاء مجتمع Rust بتوفير العديد من الحزم في crates.io ، ويتضمن سحب أي منها إلى حزمتك نفس هذه الخطوات: إدراجها في ملف Cargo.toml الخاص بحزمتك واستخدام use لجلب العناصر من صناديقها إلى النطاق.

لاحظ أن المكتبة القياسية std هي أيضاً صندوق خارجي لحزمتنا. نظراً لأن المكتبة القياسية يتم شحنها مع لغة Rust، فلا نحتاج إلى تغيير Cargo.toml لتضمين std. لكننا نحتاج إلى الإشارة إليها باستخدام use لجلب العناصر من هناك إلى نطاق حزمتنا. على سبيل المثال، مع HashMap سنستخدم هذا السطر:

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

هذا مسار مطلق يبدأ بـ std ، وهو اسم صندوق المكتبة القياسية.

استخدام المسارات المتداخلة لتنظيف قوائم use الكبيرة (Using Nested Paths to Clean Up use Lists)

إذا كنا نستخدم عناصر متعددة معرفة في نفس الصندوق أو نفس الوحدة، فإن إدراج كل عنصر في سطر خاص به يمكن أن يشغل مساحة رأسية كبيرة في ملفاتنا. على سبيل المثال، هاتان العبارتان use اللتان كانتا لدينا في لعبة التخمين في القائمة 2-4 تجلبان عناصر من std إلى النطاق:

use rand::Rng;
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

بدلاً من ذلك، يمكننا استخدام (المسارات المتداخلة) nested paths لجلب نفس العناصر إلى النطاق في سطر واحد. نقوم بذلك عن طريق تحديد الجزء المشترك من المسار، متبوعاً بنقطتين مزدوجتين، ثم أقواس معقوفة حول قائمة أجزاء المسارات التي تختلف، كما هو موضح في القائمة 7-18.

use rand::Rng;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

في البرامج الأكبر، يمكن أن يؤدي جلب العديد من العناصر إلى النطاق من نفس الصندوق أو الوحدة باستخدام المسارات المتداخلة إلى تقليل عدد عبارات use المنفصلة المطلوبة بشكل كبير!

يمكننا استخدام مسار متداخل في أي مستوى في المسار، وهو أمر مفيد عند دمج عبارني use تشتركان في مسار فرعي. على سبيل المثال، تعرض القائمة 7-19 عبارني use: واحدة تجلب std::io إلى النطاق وأخرى تجلب std::io::Write إلى النطاق.

use std::io;
use std::io::Write;

الجزء المشترك من هذين المسارين هو std::io ، وهذا هو المسار الأول الكامل. لدمج هذين المسارين في عبارة use واحدة، يمكننا استخدام self في المسار المتداخل، كما هو موضح في القائمة 7-20.

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

يجلب هذا السطر std::io و std::io::Write إلى النطاق.

استيراد العناصر باستخدام عامل النجمة (Importing Items with the Glob Operator)

إذا أردنا جلب جميع العناصر العامة المعرفة في مسار ما إلى النطاق، فيمكننا تحديد ذلك المسار متبوعاً بـ (عامل النجمة) glob operator وهو *:

#![allow(unused)]
fn main() {
use std::collections::*;
}

تجلب عبارة use هذه جميع العناصر العامة المعرفة في std::collections إلى النطاق الحالي. كن حذراً عند استخدام عامل النجمة! يمكن أن يجعل glob من الصعب معرفة الأسماء الموجودة في النطاق ومكان تعريف الاسم المستخدم في برنامجك. بالإضافة إلى ذلك، إذا قامت التبعية بتغيير تعريفاتها، فإن ما استوردته يتغير أيضاً، مما قد يؤدي إلى أخطاء في المترجم عند ترقية التبعية إذا أضافت التبعية تعريفاً بنفس اسم تعريف خاص بك في نفس النطاق، على سبيل المثال.

غالباً ما يُستخدم عامل النجمة عند الاختبار لجلب كل شيء تحت الاختبار إلى وحدة tests ؛ سنتحدث عن ذلك في “كيفية كتابة الاختبارات” في الفصل 11. يُستخدم عامل النجمة أيضاً أحياناً كجزء من نمط (التمهيد) prelude : راجع توثيق المكتبة القياسية لمزيد من المعلومات حول هذا النمط.

فصل الوحدات في ملفات مختلفة

فصل الوحدات البرمجية في ملفات مختلفة

حتى الآن، كانت جميع الأمثلة في هذا الفصل تعرف وحدات برمجية (modules) متعددة في ملف واحد. عندما تصبح modules كبيرة، قد ترغب في نقل تعريفاتها إلى ملف منفصل لتسهيل تصفح الكود.

على سبيل المثال، لنبدأ من الكود الموجود في القائمة 7-17 الذي كان يحتوي على عدة modules للمطعم. سنقوم باستخراج modules إلى ملفات بدلاً من وجود جميع modules معرفة في ملف جذر الكريت (crate root). في هذه الحالة، ملف crate root هو src/lib.rs، ولكن هذا الإجراء يعمل أيضاً مع الكريتات الثنائية (binary crates) التي يكون ملف crate root الخاص بها هو src/main.rs.

أولاً، سنقوم باستخراج وحدة front_of_house إلى ملفها الخاص. قم بإزالة الكود الموجود داخل الأقواس المتعرجة لوحدة front_of_house مع ترك التصريح mod front_of_house; فقط، بحيث يحتوي src/lib.rs على الكود الموضح في القائمة 7-21. لاحظ أن هذا لن يتم تصريفه (compile) حتى ننشئ ملف src/front_of_house.rs في القائمة 7-22.

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

بعد ذلك، ضع الكود الذي كان داخل الأقواس المتعرجة في ملف جديد باسم src/front_of_house.rs، كما هو موضح في القائمة 7-22. يعرف المترجم (compiler) أنه يجب البحث في هذا الملف لأنه صادف تصريح الوحدة في crate root باسم front_of_house.

pub mod hosting {
    pub fn add_to_waitlist() {}
}

لاحظ أنك تحتاج فقط إلى تحميل ملف باستخدام تصريح mod مرة واحدة في شجرة الوحدات البرمجية (module tree). بمجرد أن يعرف compiler أن الملف جزء من المشروع (ويعرف مكان وجود الكود في module tree بسبب المكان الذي وضعت فيه عبارة mod)، يجب أن تشير الملفات الأخرى في مشروعك إلى كود الملف المحمل باستخدام مسار (path) إلى مكان التصريح عنه، كما هو مغطى في قسم “مسارات الإشارة إلى عنصر في شجرة الوحدات البرمجية”. بعبارة أخرى، mod ليست عملية “تضمين” (include) كما قد تكون رأيتها في لغات برمجة أخرى.

بعد ذلك، سنقوم باستخراج وحدة hosting إلى ملفها الخاص. العملية مختلفة قليلاً لأن hosting هي وحدة فرعية (child module) لـ front_of_house وليست للوحدة الجذرية. سنضع ملف hosting في مجلد جديد سيتم تسميته باسم أسلافه في module tree، وفي هذه الحالة هو src/front_of_house.

لبدء نقل hosting نقوم بتغيير src/front_of_house.rs ليحتوي فقط على تصريح وحدة hosting:

pub mod hosting;

ثم ننشئ مجلد src/front_of_house وملف hosting.rs ليحتويا على التعريفات الموجودة في وحدة hosting:

pub fn add_to_waitlist() {}

إذا وضعنا hosting.rs في مجلد src بدلاً من ذلك، فسيوقع compiler أن يكون كود hosting.rs في وحدة hosting مصرح عنها في crate root وليس مصرحاً عنها كابن لوحدة front_of_house. تعني قواعد compiler الخاصة بالملفات التي يجب فحصها بحثاً عن كود modules أن المجلدات والملفات تتطابق بشكل أوثق مع module tree.

مسارات ملفات بديلة (Alternate File Paths)

حتى الآن قمنا بتغطية مسارات الملفات الأكثر شيوعاً (idiomatic) التي يستخدمها مترجم Rust، ولكن Rust يدعم أيضاً أسلوباً قديماً لمسارات الملفات. بالنسبة لوحدة تسمى front_of_house مصرح عنها في crate root، سيبحث compiler عن كود الوحدة في:

• src/front_of_house.rs (ما قمنا بتغطيته)
• src/front_of_house/mod.rs (أسلوب قديم، مسار لا يزال مدعوماً)

بالنسبة لوحدة تسمى hosting وهي وحدة فرعية (submodule) لـ front_of_house سيبحث compiler عن كود الوحدة في:

• src/front_of_house/hosting.rs (ما قمنا بتغطيته)
• src/front_of_house/hosting/mod.rs (أسلوب قديم، مسار لا يزال مدعوماً)

إذا استخدمت كلا الأسلوبين لنفس الوحدة، فستحصل على خطأ من المترجم (compiler error). يسمح باستخدام مزيج من كلا الأسلوبين لوحدات مختلفة في نفس المشروع ولكن قد يكون ذلك مربكاً للأشخاص الذين يتصفحون مشروعك.

العيب الرئيسي للأسلوب الذي يستخدم ملفات تسمى mod.rs هو أن مشروعك قد ينتهي به الأمر بالعديد من الملفات المسماة mod.rs، مما قد يصبح مربكاً عندما تكون مفتوحة في المحرر الخاص بك في نفس الوقت.

لقد نقلنا كود كل وحدة إلى ملف منفصل، وظلت module tree كما هي. ستعمل استدعاءات الدوال في eat_at_restaurant دون أي تعديل، على الرغم من أن التعريفات تعيش في ملفات مختلفة. تتيح لك هذه التقنية نقل modules إلى ملفات جديدة مع زيادة حجمها.

لاحظ أن عبارة pub use crate::front_of_house::hosting في src/lib.rs لم تتغير أيضاً، كما أن use ليس لها أي تأثير على الملفات التي يتم تصريفها كجزء من crate. تقوم الكلمة المفتاحية mod بالتصريح عن modules، ويبحث Rust في ملف له نفس اسم الوحدة عن الكود الذي يوضع في تلك الوحدة.

ملخص

تسمح لك Rust بتقسيم طرد (package) إلى عدة كريتات (crates) والكريت إلى وحدات برمجية (modules) بحيث يمكنك الرجوع إلى العناصر المعرفة في وحدة من وحدة أخرى. يمكنك القيام بذلك عن طريق تحديد مسارات (paths) مطلقة أو نسبية. يمكن جلب هذه paths إلى النطاق (scope) باستخدام عبارة use بحيث يمكنك استخدام مسار أقصر لاستخدامات متعددة للعنصر في ذلك scope. كود الوحدة يكون خاصاً (private) بشكل افتراضي، ولكن يمكنك جعل التعريفات عامة (public) بإضافة الكلمة المفتاحية pub.

في الفصل القادم، سنلقي نظرة على بعض هياكل بيانات المجموعات (collection data structures) في المكتبة القياسية (standard library) التي يمكنك استخدامها في كودك المنظم بدقة.

المجموعات الشائعة (Common Collections)

تتضمن مكتبة Rust القياسية (Standard Library) عدداً من هياكل البيانات المفيدة جداً والتي تسمى “المجموعات” (Collections). تمثل معظم أنواع البيانات الأخرى قيمة واحدة محددة، ولكن يمكن للـ Collections أن تحتوي على قيم متعددة. على عكس أنواع المصفوفات (Arrays) والصفوف (Tuples) المدمجة، يتم تخزين البيانات التي تشير إليها هذه الـ Collections على “الكومة” (Heap)، مما يعني أن كمية البيانات لا يلزم معرفتها في “وقت التجميع” (Compile Time) ويمكن أن تنمو أو تتقلص أثناء تشغيل البرنامج. تمتلك كل نوع من الـ Collections قدرات وتكاليف مختلفة، واختيار النوع المناسب لموقفك الحالي هو مهارة ستطورها بمرور الوقت. في هذا الفصل، سنناقش ثلاث مجموعات تُستخدم بكثرة في برامج Rust:

• “المتجه” (Vector) يتيح لك تخزين عدد متغير من القيم بجانب بعضها البعض.
• “السلسلة النصية” (String) هي مجموعة من الأحرف. لقد ذكرنا نوع String سابقاً، ولكن في هذا الفصل، سنتحدث عنه بعمق.
• “جدول التجزئة” (Hash Map) يتيح لك ربط قيمة بمفتاح (Key) معين. إنه تنفيذ محدد لهيكل البيانات الأكثر عمومية والذي يسمى “الخريطة” (Map).

للتعرف على الأنواع الأخرى من الـ Collections التي توفرها الـ Standard Library، راجع التوثيق.

سنناقش كيفية إنشاء وتحديث الـ Vectors، والـ Strings، والـ Hash Maps، بالإضافة إلى ما يجعل كل منها مميزاً.

تخزين قوائم القيم باستخدام المتجهات (Vectors)

تخزين قوائم من القيم باستخدام الـ Vectors

أول نوع تجميع (collection type) سننظر إليه هو Vec<T>، المعروف أيضًا باسم الـ vector. تسمح لك الـ Vectors بتخزين أكثر من قيمة في بنية بيانات واحدة تضع جميع القيم بجوار بعضها البعض في الذاكرة. يمكن للـ Vectors تخزين قيم من نفس النوع فقط. وهي مفيدة عندما يكون لديك قائمة من العناصر، مثل أسطر النص في ملف أو أسعار العناصر في عربة تسوق.

إنشاء Vector جديد

لإنشاء vector جديد وفارغ، نستدعي دالة Vec::new، كما هو موضح في القائمة 8-1.

fn main() {
    let v: Vec<i32> = Vec::new();
}

لاحظ أننا أضفنا تذييل نوع (type annotation) هنا. نظرًا لأننا لا ندخل أي قيم في هذا الـ vector، فإن Rust لا تعرف نوع العناصر التي ننوي تخزينها. هذه نقطة مهمة. يتم تطبيق الـ Vectors باستخدام الأنواع العامة (generics)؛ سنغطي كيفية استخدام الـ generics مع أنواعك الخاصة في الفصل 10. في الوقت الحالي، اعلم أن نوع Vec<T> الذي توفره الـ standard library يمكن أن يحتوي على أي نوع. عندما ننشئ vector لاحتواء نوع معين، يمكننا تحديد النوع داخل الأقواس الزاوية (angle brackets). في القائمة 8-1، أخبرنا Rust أن Vec<T> في v سيحتوي على عناصر من نوع i32.

في كثير من الأحيان، ستقوم بإنشاء Vec<T> بقيم أولية، وستستنتج Rust نوع القيمة التي تريد تخزينها، لذلك نادرًا ما تحتاج إلى إجراء type annotation هذا. توفر Rust بشكل ملائم الماكرو (macro) vec!، والذي سيقوم بإنشاء vector جديد يحتوي على القيم التي تقدمها له. تنشئ القائمة 8-2 Vec<i32> جديدًا يحتوي على القيم 1 و 2 و 3. نوع الـ integer هو i32 لأنه نوع الـ integer الافتراضي، كما ناقشنا في قسم “أنواع البيانات” (Data Types) في الفصل 3.

fn main() {
    let v = vec![1, 2, 3];
}

نظرًا لأننا قدمنا قيم i32 أولية، يمكن لـ Rust استنتاج أن نوع v هو Vec<i32>، و type annotation ليس ضروريًا. بعد ذلك، سننظر في كيفية تعديل الـ vector.

تحديث Vector

لإنشاء vector ثم إضافة عناصر إليه، يمكننا استخدام الـ method push، كما هو موضح في القائمة 8-3.

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

كما هو الحال مع أي متغير، إذا أردنا أن نكون قادرين على تغيير قيمته، فنحن بحاجة إلى جعله قابلاً للتغيير (mutable) باستخدام الكلمة المفتاحية mut، كما نوقش في الفصل 3. الأرقام التي نضعها بالداخل كلها من نوع i32، وتستنتج Rust ذلك من الـ data، لذلك لا نحتاج إلى type annotation Vec<i32>.

قراءة عناصر الـ Vectors

هناك طريقتان للإشارة إلى قيمة مخزنة في vector: عبر الفهرسة (indexing) أو باستخدام الـ method get. في الأمثلة التالية، قمنا بتذييل أنواع القيم التي يتم إرجاعها من هذه الـ functions لمزيد من الوضوح.

توضح القائمة 8-4 كلتا طريقتي الوصول إلى قيمة في vector، باستخدام بناء جملة الـ indexing و method get.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

لاحظ بعض التفاصيل هنا. نستخدم قيمة الـ index 2 للحصول على العنصر الثالث لأن الـ vectors مفهرسة بالرقم، بدءًا من الصفر. يمنحنا استخدام & و [] مرجعًا (reference) إلى العنصر الموجود في قيمة الـ index. عندما نستخدم method get مع تمرير الـ index كوسيط، نحصل على Option<&T> يمكننا استخدامه مع match.

توفر Rust هاتين الطريقتين للإشارة إلى عنصر حتى تتمكن من اختيار كيفية تصرف البرنامج عندما تحاول استخدام قيمة index خارج نطاق العناصر الموجودة. كمثال، دعنا نرى ما يحدث عندما يكون لدينا vector من خمسة عناصر ثم نحاول الوصول إلى عنصر في الـ index 100 بكل تقنية، كما هو موضح في القائمة 8-5.

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

عندما نقوم بتشغيل هذا الكود، ستتسبب طريقة [] الأولى في ذعر (panic) البرنامج لأنها تشير إلى عنصر غير موجود. من الأفضل استخدام هذه الطريقة عندما تريد أن يتعطل برنامجك إذا كانت هناك محاولة للوصول إلى عنصر يتجاوز نهاية الـ vector.

عندما يتم تمرير index إلى method get يكون خارج نطاق الـ vector، فإنه يُرجع None دون panic. ستستخدم هذا الـ method إذا كان الوصول إلى عنصر يتجاوز نطاق الـ vector قد يحدث أحيانًا في ظل الظروف العادية. سيحتوي الكود الخاص بك بعد ذلك على منطق للتعامل مع وجود إما Some(&element) أو None، كما نوقش في الفصل 6. على سبيل المثال، يمكن أن يأتي الـ index من شخص يدخل رقمًا. إذا أدخلوا عن طريق الخطأ رقمًا كبيرًا جدًا وحصل البرنامج على قيمة None، فيمكنك إخبار المستخدم بعدد العناصر الموجودة في الـ vector الحالي ومنحهم فرصة أخرى لإدخال قيمة صالحة. سيكون هذا أكثر سهولة في الاستخدام من تعطل البرنامج بسبب خطأ مطبعي!

عندما يكون للبرنامج reference صالح، يفرض مدقق الاقتراض (borrow checker) قواعد الـ ownership والـ borrowing (المغطاة في الفصل 4) لضمان أن هذا الـ reference وأي references أخرى لمحتويات الـ vector تظل صالحة. تذكر القاعدة التي تنص على أنه لا يمكنك الحصول على references قابلة للتغيير وغير قابلة للتغيير في نفس النطاق (scope). تنطبق هذه القاعدة في القائمة 8-6، حيث نحتفظ بـ immutable reference للعنصر الأول في vector ونحاول إضافة عنصر إلى النهاية. لن يعمل هذا البرنامج إذا حاولنا أيضًا الإشارة إلى هذا العنصر لاحقًا في الـ function.

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

سيؤدي تجميع هذا الكود إلى هذا الخطأ:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("The first element is: {first}");
  |                                      ----- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `collections` (bin "collections") due to 1 previous error

قد يبدو الكود في القائمة 8-6 وكأنه يجب أن يعمل: لماذا يجب أن يهتم الـ reference إلى العنصر الأول بالتغييرات في نهاية الـ vector؟ يرجع هذا الخطأ إلى طريقة عمل الـ vectors: نظرًا لأن الـ vectors تضع القيم بجوار بعضها البعض في الذاكرة، فإن إضافة عنصر جديد إلى نهاية الـ vector قد يتطلب تخصيص (allocating) ذاكرة جديدة ونسخ العناصر القديمة إلى المساحة الجديدة، إذا لم تكن هناك مساحة كافية لوضع جميع العناصر بجوار بعضها البعض حيث يتم تخزين الـ vector حاليًا. في هذه الحالة، سيشير الـ reference إلى العنصر الأول إلى ذاكرة تم إلغاء تخصيصها (deallocated memory). تمنع قواعد الـ borrowing البرامج من الانتهاء في هذا الموقف.

ملاحظة: لمزيد من التفاصيل حول تفاصيل تطبيق نوع Vec<T>، راجع “The Rustonomicon”.

التكرار (Iterating) على القيم في Vector

للوصول إلى كل عنصر في vector بدوره، سنقوم بـ التكرار (iterate) عبر جميع العناصر بدلاً من استخدام الـ indices للوصول إلى عنصر واحد في كل مرة. توضح القائمة 8-7 كيفية استخدام حلقة for للحصول على immutable references لكل عنصر في vector من قيم i32 وطباعتها.

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

يمكننا أيضًا iterate على mutable references لكل عنصر في mutable vector من أجل إجراء تغييرات على جميع العناصر. ستضيف حلقة for في القائمة 8-8 50 إلى كل عنصر.

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

لتغيير القيمة التي يشير إليها الـ mutable reference، يجب علينا استخدام عامل إلغاء الإشارة (dereference operator) * للوصول إلى القيمة في i قبل أن نتمكن من استخدام عامل التشغيل +=. سنتحدث أكثر عن dereference operator في قسم “متابعة الـ Reference إلى القيمة” (Following the Reference to the Value) في الفصل 15.

يعد الـ Iterating على vector، سواء كان immutably أو mutably، آمنًا بسبب قواعد borrow checker. إذا حاولنا إدراج أو إزالة عناصر في نصوص حلقات for في القائمة 8-7 والقائمة 8-8، فسنحصل على خطأ compiler مشابه للخطأ الذي حصلنا عليه مع الكود في القائمة 8-6. يمنع الـ reference إلى الـ vector الذي تحتفظ به حلقة for التعديل المتزامن للـ vector بأكمله.

استخدام Enum لتخزين أنواع متعددة

يمكن للـ Vectors تخزين قيم من نفس النوع فقط. قد يكون هذا غير مريح؛ هناك بالتأكيد حالات استخدام تتطلب تخزين قائمة من العناصر من أنواع مختلفة. لحسن الحظ، يتم تعريف متغيرات (variants) الـ enum ضمن نفس نوع الـ enum، لذلك عندما نحتاج إلى نوع واحد لتمثيل عناصر من أنواع مختلفة، يمكننا تعريف واستخدام enum!

على سبيل المثال، لنفترض أننا نريد الحصول على قيم من صف في جدول بيانات يحتوي فيه بعض الأعمدة في الصف على integers، وبعضها على أرقام فاصلة عائمة (floating-point numbers)، وبعضها على strings. يمكننا تعريف enum تحتوي متغيراته على أنواع القيم المختلفة، وستعتبر جميع متغيرات الـ enum من نفس النوع: نوع الـ enum. بعد ذلك، يمكننا إنشاء vector لاحتواء هذا الـ enum، وبالتالي، في النهاية، الاحتفاظ بأنواع مختلفة. لقد أوضحنا ذلك في القائمة 8-9.

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

تحتاج Rust إلى معرفة الأنواع التي ستكون في الـ vector في وقت التجميع (compile time) حتى تعرف بالضبط مقدار الذاكرة على الكومة (heap) التي ستكون مطلوبة لتخزين كل عنصر. يجب أن نكون صريحين أيضًا بشأن الأنواع المسموح بها في هذا الـ vector. إذا سمحت Rust لـ vector بالاحتفاظ بأي نوع، فستكون هناك فرصة لأن يتسبب نوع واحد أو أكثر من الأنواع في حدوث أخطاء في العمليات التي يتم إجراؤها على عناصر الـ vector. يعني استخدام enum بالإضافة إلى تعبير match أن Rust ستضمن في compile time التعامل مع كل حالة ممكنة، كما نوقش في الفصل 6.

إذا كنت لا تعرف المجموعة الشاملة من الأنواع التي سيحصل عليها البرنامج في وقت التشغيل (runtime) لتخزينها في vector، فلن تنجح تقنية الـ enum. بدلاً من ذلك، يمكنك استخدام كائن سمة (trait object)، والذي سنغطيه في الفصل 18.

الآن بعد أن ناقشنا بعضًا من أكثر الطرق شيوعًا لاستخدام الـ vectors، تأكد من مراجعة وثائق API لجميع الـ methods المفيدة العديدة المعرفة على Vec<T> بواسطة الـ standard library. على سبيل المثال، بالإضافة إلى push، يزيل method pop العنصر الأخير ويُرجعه.

إسقاط Vector يسقط عناصره

مثل أي struct آخر، يتم تحرير (freed) الـ vector عندما يخرج من النطاق (scope)، كما هو موضح في القائمة 8-10.

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

عندما يتم إسقاط الـ vector، يتم أيضًا إسقاط جميع محتوياته، مما يعني أنه سيتم تنظيف الـ integers التي يحتوي عليها. يضمن borrow checker أن أي references لمحتويات vector تُستخدم فقط بينما يكون الـ vector نفسه صالحًا.

دعنا ننتقل إلى نوع التجميع التالي: String!

تخزين النصوص المشفرة بـ UTF-8 باستخدام السلاسل النصية (Strings)

تخزين النصوص المشفرة بـ UTF-8 باستخدام السلاسل النصية (Strings)

تحدثنا عن السلاسل النصية (Strings) في الفصل 4، لكننا سنلقي نظرة عليها بعمق أكبر الآن. عادةً ما يواجه المبرمجون الجدد في Rust (Rustaceans) صعوبة في التعامل مع الـ Strings لثلاثة أسباب مجتمعة: ميل Rust لإظهار الأخطاء المحتملة، وكون الـ Strings هيكل بيانات أكثر تعقيداً مما يعتقده الكثير من المبرمجين، و UTF-8. تجتمع هذه العوامل بطريقة قد تبدو صعبة عندما تأتي من لغات برمجة أخرى.

نناقش الـ Strings في سياق المجموعات (Collections) لأن الـ Strings يتم تنفيذها كمجموعة من البايتات (Bytes)، بالإضافة إلى بعض الدوال المرتبطة (Methods) لتوفير وظائف مفيدة عندما يتم تفسير تلك الـ Bytes كنص. في هذا القسم، سنتحدث عن العمليات على String التي تمتلكها كل أنواع الـ Collections، مثل الإنشاء والتحديث والقراءة. سنناقش أيضاً الطرق التي تختلف بها String عن الـ Collections الأخرى، وتحديداً كيف أن الفهرسة (Indexing) في String معقدة بسبب الاختلافات بين كيفية تفسير البشر والحواسيب لبيانات الـ String.

تعريف السلاسل النصية (Defining Strings)

سنعرف أولاً ما نعنيه بمصطلح String. تمتلك Rust نوعاً واحداً فقط من السلاسل النصية في لغتها الأساسية (Core Language)، وهو شريحة السلسلة النصية (String Slice) str والتي تُرى عادةً في شكلها المستعار &str. في الفصل 4، تحدثنا عن الـ String Slices، وهي مراجع (References) لبعض بيانات النصوص المشفرة بـ UTF-8 والمخزنة في مكان آخر. السلاسل النصية الثابتة (String Literals)، على سبيل المثال، يتم تخزينها في الملف الثنائي (Binary) للبرنامج وبالتالي فهي String Slices.

نوع String الذي توفره مكتبة Rust القياسية (Standard Library) بدلاً من كونه مدمجاً في الـ Core Language، هو نوع سلسلة نصية قابل للنمو، وقابل للتغيير (Mutable)، ومملوك (Owned)، ومشفر بـ UTF-8. عندما يشير الـ Rustaceans إلى “Strings” في Rust، فقد يقصدون إما نوع String أو نوع الـ String Slice &str وليس أحدهما فقط. على الرغم من أن هذا القسم يدور بشكل كبير حول String إلا أن كلا النوعين يستخدمان بكثافة في الـ Standard Library، وكلاهما مشفر بـ UTF-8.

إنشاء سلسلة نصية جديدة (Creating a New String)

تتوفر العديد من العمليات المتاحة مع Vec<T> لـ String أيضاً لأن String يتم تنفيذها فعلياً كغلاف حول متجه من البايتات (Vector of Bytes) مع بعض الضمانات والقيود والقدرات الإضافية. مثال على دالة تعمل بنفس الطريقة مع Vec<T> و String هي دالة new لإنشاء نسخة (Instance)، كما هو موضح في القائمة 8-11.

fn main() {
    let mut s = String::new();
}

يُنشئ هذا السطر سلسلة نصية جديدة فارغة تسمى s والتي يمكننا لاحقاً تحميل البيانات فيها. غالباً ما يكون لدينا بعض البيانات الأولية التي نريد بدء السلسلة النصية بها. لذلك، نستخدم Method تسمى to_string والمتاحة لأي نوع ينفذ سمة Display (Trait) كما تفعل الـ String Literals. توضح القائمة 8-12 مثالين.

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // The method also works on a literal directly:
    let s = "initial contents".to_string();
}

ينشئ هذا الكود سلسلة نصية تحتوي على initial contents.

يمكننا أيضاً استخدام الدالة String::from لإنشاء String من String Literal. الكود في القائمة 8-13 يعادل الكود في القائمة 8-12 الذي يستخدم to_string.

fn main() {
    let s = String::from("initial contents");
}

لأن الـ Strings تستخدم لأشياء كثيرة، يمكننا استخدام العديد من الواجهات البرمجية العامة (Generic APIs) المختلفة لها، مما يوفر لنا الكثير من الخيارات. قد يبدو بعضها زائداً عن الحاجة، لكن لكل منها مكانه! في هذه الحالة، تقوم String::from و to_string بنفس الشيء، لذا فإن اختيار أحدهما هو مسألة أسلوب ووضوح للقراءة.

تذكر أن الـ Strings مشفرة بـ UTF-8، لذا يمكننا تضمين أي بيانات مشفرة بشكل صحيح فيها، كما هو موضح في القائمة 8-14.

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

كل هذه قيم String صالحة.

تحديث سلسلة نصية (Updating a String)

يمكن لـ String أن تنمو في الحجم ويمكن أن تتغير محتوياتها، تماماً مثل محتويات Vec<T> إذا قمت بدفع (Push) المزيد من البيانات إليها. بالإضافة إلى ذلك، يمكنك استخدام عامل + أو ماكرو format! لدمج (Concatenate) قيم String بسهولة.

الإلحاق باستخدام push_str أو push

يمكننا زيادة حجم String باستخدام push_str لإلحاق String Slice، كما هو موضح في القائمة 8-15.

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

بعد هذين السطرين، ستحتوي s على foobar. تأخذ push_str شريحة نصية لأننا لا نريد بالضرورة أخذ ملكية (Ownership) المعامل. على سبيل المثال، في الكود في القائمة 8-16، نريد أن نكون قادرين على استخدام s2 بعد إلحاق محتوياتها بـ s1.

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

إذا كانت push_str تأخذ Ownership لـ s2 فلن نتمكن من طباعة قيمتها في السطر الأخير. ومع ذلك، يعمل هذا الكود كما نتوقع!

تأخذ Method الـ push حرفاً واحداً كمعامل وتضيفه إلى الـ String. تضيف القائمة 8-17 الحرف l إلى String باستخدام push.

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

نتيجة لذلك، ستحتوي s على lol.

الدمج باستخدام + أو format!

غالباً ما ستحتاج إلى دمج سلسلتين نصيتين موجودتين. إحدى الطرق للقيام بذلك هي استخدام عامل + كما هو موضح في القائمة 8-18.

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

ستحتوي السلسلة s3 على Hello, world!. السبب في أن s1 لم تعد صالحة بعد الإضافة، والسبب في استخدامنا لمرجع لـ s2 يتعلق بتوقيع (Signature) الـ Method التي يتم استدعاؤها عند استخدام عامل +. يستخدم عامل + دالة add التي يبدو توقيعها كالتالي:

fn add(self, s: &str) -> String {

في الـ Standard Library، سترى add معرفة باستخدام الأنواع العامة (Generics) والأنواع المرتبطة (Associated Types). هنا، قمنا باستبدالها بأنواع ملموسة (Concrete Types)، وهو ما يحدث عندما نستدعي هذه الـ Method بقيم String. سنناقش الـ Generics في الفصل 10. يعطينا هذا الـ Signature الأدلة التي نحتاجها لفهم الأجزاء المعقدة في عامل +.

أولاً، تمتلك s2 علامة & مما يعني أننا نضيف Reference للسلسلة الثانية إلى السلسلة الأولى. هذا بسبب معامل s في دالة add: يمكننا فقط إضافة String Slice إلى String؛ لا يمكننا إضافة قيمتي String معاً. ولكن انتظر—نوع &s2 هو &String وليس &str كما هو محدد في المعامل الثاني لـ add. إذاً، لماذا يتم تجميع القائمة 8-18؟

السبب في قدرتنا على استخدام &s2 في استدعاء add هو أن المترجم (Compiler) يمكنه إجبار (Coerce) معامل الـ &String ليصبح &str. عندما نستدعي add تستخدم Rust “إجبار إلغاء الإسناد” (Deref Coercion)، والذي يحول هنا &s2 إلى &s2[..]. سنناقش الـ Deref Coercion بعمق أكبر في الفصل 15. ولأن add لا تأخذ Ownership لمعامل s ستظل s2 قيمة String صالحة بعد هذه العملية.

ثانياً، يمكننا أن نرى في الـ Signature أن add تأخذ Ownership لـ self لأن self لا تمتلك علامة &. هذا يعني أن s1 في القائمة 8-18 سيتم نقلها (Moved) إلى استدعاء add ولن تعد صالحة بعد ذلك. لذا، على الرغم من أن let s3 = s1 + &s2; تبدو وكأنها ستنسخ كلتا السلسلتين وتنشئ واحدة جديدة، إلا أن هذه العبارة تأخذ في الواقع Ownership لـ s1 وتلحق بها نسخة من محتويات s2 ثم تعيد Ownership للنتيجة. بعبارة أخرى، يبدو الأمر وكأنه يتم إجراء الكثير من النسخ، لكنه ليس كذلك؛ التنفيذ أكثر كفاءة من النسخ.

إذا احتجنا لدمج سلاسل نصية متعددة، يصبح سلوك عامل + غير مريح:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

عند هذه النقطة، ستكون s هي tic-tac-toe. مع كل علامات + و " يصبح من الصعب رؤية ما يحدث. لدمج السلاسل النصية بطرق أكثر تعقيداً، يمكننا بدلاً من ذلك استخدام ماكرو format!:

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

يضبط هذا الكود أيضاً s لتكون tic-tac-toe. يعمل ماكرو format! مثل println! ولكن بدلاً من طباعة المخرجات على الشاشة، فإنه يعيد String بالمحتويات. نسخة الكود التي تستخدم format! أسهل بكثير في القراءة، والكود الناتج عن ماكرو format! يستخدم مراجع (References) بحيث لا يأخذ هذا الاستدعاء Ownership لأي من معاملاته.

الفهرسة في السلاسل النصية (Indexing into Strings)

في العديد من لغات البرمجة الأخرى، يعد الوصول إلى أحرف فردية في سلسلة نصية عن طريق الإشارة إليها بالفهرس (Index) عملية صالحة وشائعة. ومع ذلك، إذا حاولت الوصول إلى أجزاء من String باستخدام صيغة الفهرسة في Rust، فستحصل على خطأ. فكر في الكود غير الصالح في القائمة 8-19.

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

سيؤدي هذا الكود إلى الخطأ التالي:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `str` cannot be indexed by `{integer}`
 --> src/main.rs:3:16
  |
3 |     let h = s1[0];
  |                ^ string indices are ranges of `usize`
  |
  = help: the trait `SliceIndex<str>` is not implemented for `{integer}`
  = note: you can use `.chars().nth()` or `.bytes().nth()`
          for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
  = help: the following other types implement trait `SliceIndex<T>`:
            `usize` implements `SliceIndex<ByteStr>`
            `usize` implements `SliceIndex<[T]>`
  = note: required for `String` to implement `Index<{integer}>`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `collections` (bin "collections") due to 1 previous error

الخطأ يوضح القصة: الـ Strings في Rust لا تدعم الـ Indexing. ولكن لماذا لا؟ للإجابة على هذا السؤال، نحتاج إلى مناقشة كيفية تخزين Rust للـ Strings في الذاكرة.

التمثيل الداخلي (Internal Representation)

الـ String هي غلاف فوق Vec<u8>. دعنا ننظر في بعض أمثلة السلاسل النصية المشفرة بـ UTF-8 من القائمة 8-14. أولاً، هذه:

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

في هذه الحالة، سيكون len هو 4 مما يعني أن الـ Vector الذي يخزن السلسلة "Hola" طوله 4 بايتات. كل حرف من هذه الأحرف يأخذ 1 بايت عند تشفيره بـ UTF-8. ماذا عن السطر التالي؟

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

إذا سُئلت عن طول السلسلة، فقد تقول 12. في الواقع، إجابة Rust هي 24: هذا هو عدد البايتات التي يتطلبها تشفير “Здравствуйте” بـ UTF-8، لأن كل قيمة سلمية لليونيكود (Unicode Scalar Value) في تلك السلسلة تأخذ 2 بايت من التخزين. لذلك، فإن الفهرس في بايتات السلسلة لن يرتبط دائماً بـ Unicode Scalar Value صالحة. للتوضيح، فكر في كود Rust غير الصالح هذا:

let hello = "Здравствуйте";
let answer = &hello[0];

أنت تعلم بالفعل أن answer لن تكون З (الحرف الأول). عند التشفير بـ UTF-8، يكون البايت الأول من З هو 208 والثاني هو 151 لذا يبدو أن answer يجب أن تكون في الواقع 208 لكن 208 ليس حرفاً صالحاً بمفرده. من المحتمل ألا يكون إرجاع 208 هو ما يريده المستخدم إذا طلب الحرف الأول من هذه السلسلة؛ ومع ذلك، فهذه هي البيانات الوحيدة التي تمتلكها Rust عند فهرس البايت 0. لا يريد المستخدمون عموماً إرجاع قيمة البايت، حتى لو كانت السلسلة تحتوي فقط على أحرف لاتينية: إذا كان &"hi"[0] كوداً صالحاً يعيد قيمة البايت، فإنه سيعيد 104 وليس h.

الإجابة إذاً هي أنه لتجنب إرجاع قيمة غير متوقعة والتسبب في أخطاء قد لا يتم اكتشافها على الفور، لا تقوم Rust بتجميع هذا الكود على الإطلاق وتمنع سوء الفهم في وقت مبكر من عملية التطوير.

البايتات، والقيم السلمية، وعناقيد الرموز (Bytes, Scalar Values, and Grapheme Clusters)

نقطة أخرى حول UTF-8 هي أن هناك في الواقع ثلاث طرق ذات صلة للنظر في الـ Strings من منظور Rust: كبايتات (Bytes)، وقيم سلمية (Scalar Values)، وعناقيد رموز (Grapheme Clusters) - وهي أقرب شيء لما نسميه أحرفاً.

إذا نظرنا إلى الكلمة الهندية “नमस्ते” المكتوبة بخط الديفاناغاري، فسيتم تخزينها كمتجه من قيم u8 يبدو كالتالي:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

هذا يمثل 18 بايت وهو الكيفية التي تخزن بها الحواسيب هذه البيانات في النهاية. إذا نظرنا إليها كـ Unicode Scalar Values، وهي ما يمثله نوع char في Rust، فستبدو تلك البايتات كالتالي:

['न', 'م', 'س', '्', 'ت', 'े']

هناك ست قيم char هنا، لكن الرابعة والسادسة ليست أحرفاً: إنها علامات تشكيل لا معنى لها بمفردها. أخيراً، إذا نظرنا إليها كـ Grapheme Clusters، فسنحصل على ما يسميه الشخص الأحرف الأربعة التي تشكل الكلمة الهندية:

["न", "م", "स्", "ته"]

توفر Rust طرقاً مختلفة لتفسير بيانات السلسلة الخام التي تخزنها الحواسيب بحيث يمكن لكل برنامج اختيار التفسير الذي يحتاجه، بغض النظر عن اللغة البشرية التي كتبت بها البيانات.

السبب الأخير الذي يجعل Rust لا تسمح لنا بالفهرسة في String للحصول على حرف هو أن عمليات الفهرسة يُتوقع منها دائماً أن تأخذ وقتاً ثابتاً (O(1)). ولكن ليس من الممكن ضمان هذا الأداء مع String لأن Rust ستضطر إلى المرور عبر المحتويات من البداية إلى الفهرس لتحديد عدد الأحرف الصالحة الموجودة.

تشريح السلاسل النصية (Slicing Strings)

غالباً ما تكون الفهرسة في سلسلة نصية فكرة سيئة لأنه ليس من الواضح ما يجب أن يكون عليه النوع المرتجع لعملية فهرسة السلسلة: قيمة بايت، أو حرف، أو عنقود رموز، أو شريحة سلسلة نصية. إذا كنت بحاجة حقاً لاستخدام الفهارس لإنشاء String Slices، فإن Rust تطلب منك أن تكون أكثر تحديداً.

بدلاً من الفهرسة باستخدام [] مع رقم واحد، يمكنك استخدام [] مع نطاق (Range) لإنشاء String Slice يحتوي على بايتات معينة:

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

هنا، ستكون s عبارة عن &str تحتوي على أول 4 بايتات من السلسلة. ذكرنا سابقاً أن كل حرف من هذه الأحرف كان 2 بايت، مما يعني أن s ستكون Зд.

إذا حاولنا تشريح جزء فقط من بايتات حرف ما باستخدام شيء مثل &hello[0..1] فستقوم Rust بالهلع (Panic) في وقت التشغيل بنفس الطريقة التي يحدث بها الوصول إلى فهرس غير صالح في متجه:

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`

thread 'main' panicked at src/main.rs:4:19:
byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

يجب عليك توخي الحذر عند إنشاء String Slices باستخدام النطاقات، لأن القيام بذلك قد يؤدي إلى تعطل برنامجك.

التكرار عبر السلاسل النصية (Iterating Over Strings)

أفضل طريقة للتعامل مع أجزاء من السلاسل النصية هي أن تكون صريحاً بشأن ما إذا كنت تريد أحرفاً أم بايتات. بالنسبة لـ Unicode Scalar Values الفردية، استخدم Method الـ chars. استدعاء chars على “Зд” يفصل ويعيد قيمتين من نوع char ويمكنك التكرار (Iterate) عبر النتيجة للوصول إلى كل عنصر:

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

سيطبع هذا الكود ما يلي:

З
д

بدلاً من ذلك، تعيد Method الـ bytes كل بايت خام، وهو ما قد يكون مناسباً لمجالك:

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

سيطبع هذا الكود الـ 4 بايتات التي تشكل هذه السلسلة:

208
151
208
180

لكن تأكد من تذكر أن Unicode Scalar Values الصالحة قد تتكون من أكثر من 1 بايت.

الحصول على Grapheme Clusters من السلاسل النصية، كما هو الحال مع خط الديفاناغاري، أمر معقد، لذا لا توفر المكتبة القياسية هذه الوظيفة. تتوفر حزم (Crates) على crates.io إذا كانت هذه هي الوظيفة التي تحتاجها.

التعامل مع تعقيدات السلاسل النصية (Handling the Complexities of Strings)

باختصار، السلاسل النصية معقدة. تتخذ لغات البرمجة المختلفة خيارات مختلفة حول كيفية تقديم هذا التعقيد للمبرمج. اختارت Rust جعل التعامل الصحيح مع بيانات String هو السلوك الافتراضي لجميع برامج Rust، مما يعني أن المبرمجين يضطرون إلى التفكير أكثر في التعامل مع بيانات UTF-8 مسبقاً. تكشف هذه المقايضة عن المزيد من تعقيد السلاسل النصية عما هو ظاهر في لغات البرمجة الأخرى، ولكنها تمنعك من الاضطرار إلى التعامل مع الأخطاء التي تتضمن أحرفاً غير تابعة لـ ASCII لاحقاً في دورة حياة التطوير الخاصة بك.

الخبر السار هو أن الـ Standard Library تقدم الكثير من الوظائف المبنية على نوعي String و &str للمساعدة في التعامل مع هذه المواقف المعقدة بشكل صحيح. تأكد من مراجعة التوثيق للتعرف على Methods مفيدة مثل contains للبحث في سلسلة نصية و replace لاستبدال أجزاء من سلسلة نصية بسلسلة أخرى.

دعنا ننتقل إلى شيء أقل تعقيداً قليلاً: جداول التجزئة (Hash Maps)!

تخزين المفاتيح مع القيم المرتبطة في خرائط التجزئة (Hash Maps)

تخزين المفاتيح مع القيم المرتبطة في الخرائط الهاشية (Hash Maps)

الخريطة الهاشية (Hash Map) هي آخر مجموعة شائعة لدينا. يخزن النوع HashMap<K, V> تعيينًا للمفاتيح (keys) من النوع K إلى القيم (values) من النوع V باستخدام دالة تجزئة (hashing function)، والتي تحدد كيفية وضع هذه keys و values في الذاكرة. تدعم العديد من لغات البرمجة هذا النوع من هياكل البيانات، ولكنها غالبًا ما تستخدم اسمًا مختلفًا، مثل hash، map، object، hash table، dictionary، أو associative array، على سبيل المثال لا الحصر.

تعد Hash Maps مفيدة عندما تريد البحث عن البيانات ليس باستخدام فهرس، كما يمكنك أن تفعل مع المتجهات (vectors)، ولكن باستخدام key يمكن أن يكون من أي نوع. على سبيل المثال، في لعبة ما، يمكنك تتبع نتيجة كل فريق في Hash Map يكون فيها كل key هو اسم الفريق و values هي نتيجة كل فريق. بالنظر إلى اسم الفريق، يمكنك استرداد نتيجته.

سنتناول واجهة برمجة التطبيقات (API) الأساسية لـ Hash Maps في هذا القسم، ولكن هناك المزيد من الميزات مخبأة في الدوال المعرفة على HashMap<K, V> بواسطة المكتبة القياسية (standard library). كما هو الحال دائمًا، تحقق من وثائق standard library لمزيد من المعلومات.

إنشاء Hash Map جديدة

إحدى طرق إنشاء Hash Map فارغة هي استخدام new وإضافة العناصر باستخدام insert. في القائمة 8-20، نتتبع نتائج فريقين هما الأزرق و_الأصفر_. يبدأ الفريق الأزرق بـ 10 نقاط، والفريق الأصفر بـ 50.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

لاحظ أننا نحتاج أولاً إلى use لـ HashMap من جزء المجموعات في standard library. من بين مجموعاتنا الشائعة الثلاث، هذه هي الأقل استخدامًا، لذا فهي غير مدرجة في الميزات التي يتم جلبها تلقائيًا إلى النطاق (scope) في المقدمة (prelude). تحظى Hash Maps أيضًا بدعم أقل من standard library؛ لا يوجد ماكرو (macro) مدمج لإنشائها، على سبيل المثال.

تمامًا مثل vectors، تخزن Hash Maps بياناتها على الكومة (heap). تحتوي HashMap هذه على keys من النوع سلسلة نصية (String) و values من النوع عدد صحيح 32 بت (i32). مثل vectors، فإن Hash Maps متجانسة (homogeneous): يجب أن تكون جميع keys من نفس النوع، ويجب أن تكون جميع values من نفس النوع.

الوصول إلى القيم في Hash Map

يمكننا الحصول على value من Hash Map عن طريق توفير key الخاص بها لدالة get، كما هو موضح في القائمة 8-21.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

هنا، سيكون لـ score القيمة المرتبطة بالفريق الأزرق، وستكون النتيجة 10. تُرجع دالة get خيارًا (Option<&V>)؛ إذا لم تكن هناك value لهذا key في Hash Map، فستُرجع get لا شيء (None). يتعامل هذا البرنامج مع Option عن طريق استدعاء copied للحصول على Option<i32> بدلاً من Option<&i32>، ثم unwrap_or لتعيين score إلى صفر إذا لم يكن لدى scores إدخال (entry) لـ key.

يمكننا التكرار (iterate) على كل زوج key-value في Hash Map بطريقة مماثلة لما نفعله مع vectors، باستخدام حلقة for:

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

سيقوم هذا الكود بطباعة كل زوج بترتيب عشوائي:

Yellow: 50
Blue: 10

إدارة الملكية (Ownership) في Hash Maps

بالنسبة للأنواع التي تطبق سمة النسخ (Copy trait)، مثل i32، يتم نسخ values إلى Hash Map. بالنسبة للقيم المملوكة (owned values) مثل String، سيتم نقل values وستكون Hash Map هي مالك (owner) تلك values، كما هو موضح في القائمة 8-22.

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

لا يمكننا استخدام المتغيرين field_name و field_value بعد نقلهما إلى Hash Map باستدعاء insert.

إذا قمنا بإدراج مراجع (references) إلى values في Hash Map، فلن يتم نقل values إلى Hash Map. يجب أن تكون values التي تشير إليها references صالحة على الأقل طالما أن Hash Map صالحة. سنتحدث أكثر عن هذه المشكلات في “Validating References with Lifetimes” في الفصل 10.

تحديث Hash Map

على الرغم من أن عدد أزواج key و value قابل للنمو، إلا أن كل key فريد يمكن أن يكون له value واحدة فقط مرتبطة به في كل مرة (ولكن ليس العكس: على سبيل المثال، يمكن أن يكون لكل من الفريق الأزرق والفريق الأصفر القيمة 10 مخزنة في Hash Map scores).

عندما تريد تغيير البيانات في Hash Map، عليك أن تقرر كيفية التعامل مع الحالة التي يكون فيها لـ key قيمة معينة بالفعل. يمكنك استبدال value القديمة بـ value الجديدة، متجاهلاً value القديمة تمامًا. يمكنك الاحتفاظ بـ value القديمة وتجاهل value الجديدة، وإضافة value الجديدة فقط إذا لم يكن لـ key قيمة بالفعل. أو يمكنك دمج value القديمة و value الجديدة. دعونا نرى كيف نفعل كل واحدة من هذه!

الكتابة فوق قيمة (Overwriting a Value)

إذا قمنا بإدراج key و value في Hash Map ثم قمنا بإدراج نفس key بـ value مختلفة، فسيتم استبدال value المرتبطة بهذا key. على الرغم من أن الكود في القائمة 8-23 يستدعي insert مرتين، إلا أن Hash Map ستحتوي على زوج key-value واحد فقط لأننا نقوم بإدراج value لـ key الفريق الأزرق في كلتا المرتين.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

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

سيقوم هذا الكود بطباعة {"Blue": 25}. تم الكتابة فوق (overwritten) القيمة الأصلية 10.

إضافة Key و Value فقط إذا لم يكن Key موجودًا

من الشائع التحقق مما إذا كان key معين موجودًا بالفعل في Hash Map بقيمة، ثم اتخاذ الإجراءات التالية: إذا كان key موجودًا في Hash Map، فيجب أن تظل value الحالية كما هي؛ إذا لم يكن key موجودًا، فقم بإدراجه و value له.

تحتوي Hash Maps على واجهة API خاصة لذلك تسمى entry والتي تأخذ key الذي تريد التحقق منه كمعامل. القيمة المرجعة لدالة entry هي تعداد (enum) يسمى Entry يمثل value قد تكون موجودة أو لا تكون موجودة. لنفترض أننا نريد التحقق مما إذا كان key للفريق الأصفر له value مرتبطة به. إذا لم يكن كذلك، فنريد إدراج value 50، ونفس الشيء للفريق الأزرق. باستخدام واجهة API لـ entry، يبدو الكود كما في القائمة 8-24.

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

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

تم تعريف دالة or_insert على Entry لإرجاع مرجع قابل للتغيير (mutable reference) إلى value لـ key الخاص بـ Entry المقابل إذا كان هذا key موجودًا، وإذا لم يكن كذلك، فإنه يدرج المعامل كـ value الجديدة لهذا key ويعيد mutable reference إلى value الجديدة. هذه التقنية أنظف بكثير من كتابة المنطق بأنفسنا، وبالإضافة إلى ذلك، تتوافق بشكل أفضل مع مدقق الاستعارة (borrow checker).

سيؤدي تشغيل الكود في القائمة 8-24 إلى طباعة {"Yellow": 50, "Blue": 10}. سيقوم الاستدعاء الأول لـ entry بإدراج key للفريق الأصفر بـ value 50 لأن الفريق الأصفر ليس لديه value بالفعل. لن يغير الاستدعاء الثاني لـ entry Hash Map، لأن الفريق الأزرق لديه value 10 بالفعل.

تحديث قيمة بناءً على القيمة القديمة

حالة استخدام شائعة أخرى لـ Hash Maps هي البحث عن value لـ key ثم تحديثها بناءً على value القديمة. على سبيل المثال، تعرض القائمة 8-25 كودًا يحسب عدد مرات ظهور كل كلمة في نص ما. نستخدم Hash Map مع الكلمات كـ keys ونزيد value لتتبع عدد المرات التي رأينا فيها تلك الكلمة. إذا كانت هذه هي المرة الأولى التي نرى فيها كلمة، فسنقوم أولاً بإدراج value 0.

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

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

سيقوم هذا الكود بطباعة {"world": 2, "hello": 1, "wonderful": 1}. قد ترى أزواج key-value نفسها مطبوعة بترتيب مختلف: تذكر من “Accessing Values in a Hash Map” أن التكرار على Hash Map يحدث بترتيب عشوائي.

تُرجع دالة split_whitespace مكررًا (iterator) على الشرائح الفرعية (subslices)، مفصولة بمسافات بيضاء، لـ value في text. تُرجع دالة or_insert مرجعًا قابلًا للتغيير (&mut V) إلى value لـ key المحدد. هنا، نقوم بتخزين هذا mutable reference في المتغير count، لذلك من أجل التعيين لتلك value، يجب علينا أولاً فك الإشارة (dereference) لـ count باستخدام النجمة (*). يخرج mutable reference من النطاق في نهاية حلقة for، لذا فإن كل هذه التغييرات آمنة ومسموح بها بواسطة قواعد الاستعارة (borrowing rules).

دوال التجزئة (Hashing Functions)

بشكل افتراضي، تستخدم HashMap دالة تجزئة تسمى سيبهاش (SipHash) يمكن أن توفر مقاومة لهجمات حجب الخدمة (denial-of-service (DoS) attacks) التي تتضمن جداول التجزئة (hash tables)¹. هذه ليست أسرع خوارزمية تجزئة متاحة، ولكن المقايضة بين الأمان الأفضل الذي يأتي مع انخفاض الأداء تستحق العناء. إذا قمت بتحليل الكود الخاص بك ووجدت أن دالة hash الافتراضية بطيئة جدًا لأغراضك، فيمكنك التبديل إلى دالة أخرى عن طريق تحديد مجزئ (hasher) مختلف. الـ hasher هو نوع يطبق سمة BuildHasher (BuildHasher trait). سنتحدث عن traits وكيفية تطبيقها في Chapter 10. ليس عليك بالضرورة تطبيق hasher الخاص بك من البداية؛ يحتوي crates.io على مكتبات يشاركها مستخدمو Rust الآخرون توفر hashers تطبق العديد من خوارزميات hash الشائعة.

ملخص

ستوفر vectors و strings و Hash Maps قدرًا كبيرًا من الوظائف الضرورية في البرامج عندما تحتاج إلى تخزين البيانات والوصول إليها وتعديلها. فيما يلي بعض التمارين التي يجب أن تكون الآن مجهزًا لحلها:

1. بالنظر إلى قائمة من الأعداد الصحيحة، استخدم vector وأرجع الوسيط (median) (عندما يتم فرزها، القيمة في الموضع الأوسط) والمنوال (mode) (القيمة التي تحدث في أغلب الأحيان؛ ستكون Hash Map مفيدة هنا) للقائمة.
2. قم بتحويل strings إلى اللاتينية الخنزيرية (Pig Latin). يتم نقل الحرف الساكن الأول من كل كلمة إلى نهاية الكلمة ويتم إضافة ay، لذا تصبح first هي irst-fay. الكلمات التي تبدأ بحرف متحرك يتم إضافة hay إلى نهايتها بدلاً من ذلك (apple تصبح apple-hay). ضع في اعتبارك التفاصيل المتعلقة بترميز UTF-8 (UTF-8 encoding)!
3. باستخدام Hash Map و vectors، قم بإنشاء واجهة نصية للسماح للمستخدم بإضافة أسماء الموظفين إلى قسم في شركة؛ على سبيل المثال، “Add Sally to Engineering” أو “Add Amir to Sales”. بعد ذلك، اسمح للمستخدم باسترداد قائمة بجميع الأشخاص في قسم أو جميع الأشخاص في الشركة حسب القسم، مرتبة أبجديًا.

تصف وثائق API لـ standard library الدوال التي تحتوي عليها vectors و strings و Hash Maps والتي ستكون مفيدة لهذه التمارين!

نحن ندخل في برامج أكثر تعقيدًا حيث يمكن أن تفشل العمليات، لذا فقد حان الوقت المثالي لمناقشة معالجة الأخطاء. سنفعل ذلك لاحقًا!

1. https://en.wikipedia.org/wiki/SipHash ↩

معالجة الأخطاء (Error Handling)

الأخطاء هي حقيقة واقعة في البرمجيات، لذا تمتلك Rust عدداً من الميزات للتعامل مع المواقف التي يحدث فيها خطأ ما. في كثير من الحالات، تطلب منك Rust الإقرار باحتمالية حدوث خطأ واتخاذ إجراء ما قبل أن يتم تجميع الكود الخاص بك. هذا المتطلب يجعل برنامجك أكثر قوة من خلال ضمان اكتشافك للأخطاء ومعالجتها بشكل مناسب قبل نشر الكود الخاص بك في بيئة الإنتاج!

تقسم Rust الأخطاء إلى فئتين رئيسيتين: أخطاء قابلة للاسترداد (Recoverable) وأخطاء غير قابلة للاسترداد (Unrecoverable). بالنسبة لـ “الخطأ القابل للاسترداد” (Recoverable Error)، مثل خطأ “الملف غير موجود”، فمن المرجح أننا نريد فقط إبلاغ المستخدم بالمشكلة وإعادة محاولة العملية. أما “الأخطاء غير القابلة للاسترداد” (Unrecoverable Errors) فهي دائماً أعراض لوجود أخطاء برمجية (Bugs)، مثل محاولة الوصول إلى موقع يتجاوز نهاية المصفوفة، ولذا نريد إيقاف البرنامج على الفور.

لا تفرق معظم اللغات بين هذين النوعين من الأخطاء وتتعامل مع كليهما بنفس الطريقة، باستخدام آليات مثل “الاستثناءات” (Exceptions). لا تمتلك Rust استثناءات؛ بدلاً من ذلك، لديها النوع Result<T, E> للأخطاء الـ Recoverable، وماكرو panic! الذي يوقف التنفيذ عندما يواجه البرنامج خطأ Unrecoverable. يغطي هذا الفصل استدعاء panic! أولاً ثم يتحدث عن إرجاع قيم Result<T, E>. بالإضافة إلى ذلك، سنستكشف الاعتبارات عند تحديد ما إذا كنت ستحاول الاسترداد من خطأ ما أو إيقاف التنفيذ.

الأخطاء غير القابلة للاسترداد باستخدام panic!

الأخطاء غير القابلة للاسترداد باستخدام panic! (Unrecoverable Errors with panic!)

أحيانًا تحدث أشياء سيئة في الكود الخاص بك، ولا يوجد شيء يمكنك القيام به حيال ذلك. في هذه الحالات، تمتلك Rust ماكرو (macro) panic!. هناك طريقتان للتسبب في حدوث ذعر (panic) في الممارسة العملية: عن طريق اتخاذ إجراء يتسبب في ذعر الكود الخاص بنا (مثل الوصول إلى مصفوفة بعد نهايتها) أو عن طريق استدعاء ماكرو panic! صراحةً. في كلتا الحالتين، نتسبب في حدوث ذعر في برنامجنا. بشكل افتراضي، ستقوم حالات الذعر هذه بطباعة رسالة فشل، وفك المكدس (unwind)، وتنظيف المكدس (stack)، ثم الخروج. عبر متغير بيئة (environment variable)، يمكنك أيضًا جعل Rust تعرض مكدس الاستدعاءات (call stack) عند حدوث ذعر لتسهيل تتبع مصدر الذعر.

فك المكدس أو الإجهاض استجابةً للذعر (Unwinding the Stack or Aborting in Response to a Panic)

بشكل افتراضي، عندما يحدث ذعر، يبدأ البرنامج في فك المكدس (unwinding)، مما يعني أن Rust تعود إلى الوراء في المكدس وتنظف البيانات من كل دالة تصادفها. ومع ذلك، فإن العودة للخلف والتنظيف يتطلب الكثير من العمل. لذلك تسمح لك Rust باختيار البديل وهو الإجهاض (aborting) الفوري، والذي ينهي البرنامج دون تنظيف.

ستحتاج الذاكرة التي كان البرنامج يستخدمها بعد ذلك إلى التنظيف بواسطة نظام التشغيل. إذا كنت بحاجة في مشروعك إلى جعل الملف الثنائي الناتج أصغر ما يمكن، فيمكنك التبديل من فك المكدس إلى الإجهاض عند حدوث ذعر عن طريق إضافة panic = 'abort' إلى أقسام [profile] المناسبة في ملف Cargo.toml الخاص بك. على سبيل المثال، إذا كنت تريد الإجهاض عند حدوث ذعر في وضع الإصدار (release mode)، فأضف هذا:

[profile.release]
panic = 'abort'

دعنا نحاول استدعاء panic! في برنامج بسيط:

fn main() {
    panic!("crash and burn");
}

عند تشغيل البرنامج، سترى شيئًا كهذا:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

يتسبب استدعاء panic! في رسالة الخطأ الواردة في السطرين الأخيرين. يوضح السطر الأول رسالة الذعر الخاصة بنا والمكان في كود المصدر الخاص بنا حيث حدث الذعر: يشير src/main.rs:2:5 إلى أنه السطر الثاني، الحرف الخامس من ملف src/main.rs الخاص بنا.

في هذه الحالة، السطر المشار إليه هو جزء من الكود الخاص بنا، وإذا ذهبنا إلى ذلك السطر، فسنرى استدعاء ماكرو panic!. في حالات أخرى، قد يكون استدعاء panic! في كود يستدعيه الكود الخاص بنا، وسيكون اسم الملف ورقم السطر الوارد في رسالة الخطأ هما كود شخص آخر حيث يتم استدعاء ماكرو panic! وليس سطر الكود الخاص بنا الذي أدى في النهاية إلى استدعاء panic!.

يمكننا استخدام تتبع الخلفية (backtrace) للدوال التي جاء منها استدعاء panic! لمعرفة جزء الكود الخاص بنا الذي يسبب المشكلة. لفهم كيفية استخدام تتبع الخلفية لـ panic! دعنا ننظر إلى مثال آخر ونرى كيف يبدو الأمر عندما يأتي استدعاء panic! من مكتبة بسبب خطأ في الكود الخاص بنا بدلاً من استدعاء الكود الخاص بنا للماكرو مباشرةً. تحتوي القائمة 9-1 على بعض الكود الذي يحاول الوصول إلى فهرس (index) في متجه (vector) يتجاوز نطاق الفهارس الصالحة.

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

هنا، نحاول الوصول إلى العنصر رقم 100 في المتجه الخاص بنا (الموجود في الفهرس 99 لأن الفهرسة تبدأ من الصفر)، لكن المتجه يحتوي على ثلاثة عناصر فقط. في هذه الحالة، ستصاب Rust بالذعر. من المفترض أن يؤدي استخدام [] إلى إرجاع عنصر، ولكن إذا مررت فهرسًا غير صالح، فلا يوجد عنصر يمكن لـ Rust إرجاعه هنا ويكون صحيحًا.

في لغة C، تعد محاولة القراءة بعد نهاية هيكل البيانات سلوكًا غير محدد (undefined behavior). قد تحصل على أي شيء موجود في موقع الذاكرة الذي يتوافق مع ذلك العنصر في هيكل البيانات، على الرغم من أن الذاكرة لا تنتمي إلى ذلك الهيكل. يسمى هذا قراءة زائدة للمخزن المؤقت (buffer overread) ويمكن أن يؤدي إلى ثغرات أمنية إذا تمكن المهاجم من التلاعب بالفهرس بطريقة تمكنه من قراءة بيانات لا ينبغي السماح له بها والمخزنة بعد هيكل البيانات.

لحماية برنامجك من هذا النوع من الثغرات، إذا حاولت قراءة عنصر في فهرس غير موجود، فستوقف Rust التنفيذ وترفض الاستمرار. دعنا نجرب ذلك ونرى:

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

يشير هذا الخطأ إلى السطر 4 من ملف main.rs الخاص بنا حيث نحاول الوصول إلى الفهرس 99 للمتجه في v.

يخبرنا سطر note: أنه يمكننا تعيين متغير البيئة RUST_BACKTRACE للحصول على تتبع خلفية (backtrace) لما حدث بالضبط وتسبب في الخطأ. تتبع الخلفية هو قائمة بجميع الدوال التي تم استدعاؤها للوصول إلى هذه النقطة. تعمل تتبعات الخلفية في Rust كما تفعل في اللغات الأخرى: المفتاح لقراءة تتبع الخلفية هو البدء من الأعلى والقراءة حتى ترى الملفات التي كتبتها. هذه هي النقطة التي نشأت منها المشكلة. الأسطر الموجودة فوق تلك النقطة هي كود استدعاه الكود الخاص بك؛ الأسطر الموجودة أسفلها هي كود استدعى الكود الخاص بك. قد تتضمن هذه الأسطر السابقة واللاحقة كود Rust الأساسي (core)، أو كود المكتبة القياسية (standard library)، أو الصناديق (crates) التي تستخدمها. دعنا نحاول الحصول على تتبع خلفية عن طريق تعيين متغير البيئة RUST_BACKTRACE إلى أي قيمة باستثناء 0. تعرض القائمة 9-2 مخرجات مشابهة لما ستراه.

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
stack backtrace:
   0: rust_begin_unwind
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/std/src/panicking.rs:692:5
   1: core::panicking::panic_fmt
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:75:14
   2: core::panicking::panic_bounds_check
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:273:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:274:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/alloc/src/vec/mod.rs:3361:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

هذا الكثير من المخرجات! قد تختلف المخرجات الدقيقة التي تراها اعتمادًا على نظام التشغيل وإصدار Rust الخاص بك. من أجل الحصول على تتبعات خلفية بهذه المعلومات، يجب تمكين رموز التصحيح (debug symbols). يتم تمكين رموز التصحيح افتراضيًا عند استخدام cargo build أو cargo run بدون علم --release كما فعلنا هنا.

في المخرجات في القائمة 9-2، يشير السطر 6 من تتبع الخلفية إلى السطر في مشروعنا الذي يسبب المشكلة: السطر 4 من src/main.rs. إذا كنا لا نريد أن يصاب برنامجنا بالذعر، فيجب أن نبدأ تحقيقنا في الموقع الذي يشير إليه السطر الأول الذي يذكر ملفًا كتبناه. في القائمة 9-1، حيث كتبنا عمدًا كودًا من شأنه أن يسبب ذعرًا، فإن طريقة إصلاح الذعر هي عدم طلب عنصر يتجاوز نطاق فهارس المتجه. عندما يصاب الكود الخاص بك بالذعر في المستقبل، ستحتاج إلى معرفة الإجراء الذي يتخذه الكود مع أي قيم للتسبب في الذعر وما يجب أن يفعله الكود بدلاً من ذلك.

سنعود إلى panic! ومتى يجب ولا يجب استخدام panic! للتعامل مع ظروف الخطأ في قسم “استخدام panic! أو عدم استخدامه” لاحقًا في هذا الفصل. بعد ذلك، سننظر في كيفية الاسترداد من خطأ باستخدام Result.

الأخطاء القابلة للاسترداد باستخدام Result

الأخطاء القابلة للاسترداد باستخدام Result (Recoverable Errors with Result)

معظم الأخطاء ليست خطيرة بما يكفي لتتطلب إيقاف البرنامج بالكامل. أحياناً عندما تفشل دالة (function)، يكون ذلك لسبب يمكنك تفسيره والاستجابة له بسهولة. على سبيل المثال، إذا حاولت فتح ملف وفشلت تلك العملية لأن الملف غير موجود، فقد ترغب في إنشاء الملف بدلاً من إنهاء العملية (process).

تذكر من قسم “معالجة الفشل المحتمل باستخدام Result” في الفصل الثاني أن تعداد (enum) الـ Result مُعرف بأنه يحتوي على متغيرين (variants)، هما Ok و Err ، كما يلي:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

الـ T والـ E هما معاملات أنواع عامة (generic type parameters): سنناقش الأنواع العامة (generics) بمزيد من التفصيل في الفصل العاشر. ما تحتاج لمعرفته الآن هو أن T يمثل نوع القيمة التي سيتم إرجاعها في حالة النجاح داخل variant الـ Ok ، و E يمثل نوع الخطأ الذي سيتم إرجاعه في حالة الفشل داخل variant الـ Err. ولأن Result يحتوي على معاملات الأنواع العامة هذه، يمكننا استخدام نوع Result والدوال المعرفة عليه في العديد من المواقف المختلفة حيث قد تختلف قيمة النجاح وقيمة الخطأ التي نريد إرجاعها.

دعونا نستدعي function تعيد قيمة Result لأن الـ function قد تفشل. في القائمة 9-3، نحاول فتح ملف.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

نوع الإرجاع لـ File::open هو Result<T, E>. تم ملء المعامل العام T بواسطة تطبيق File::open بنوع قيمة النجاح، std::fs::File ، وهو مقبض ملف (file handle). نوع E المستخدم في قيمة الخطأ هو std::io::Error. نوع الإرجاع هذا يعني أن استدعاء File::open قد ينجح ويعيد file handle يمكننا القراءة منه أو الكتابة إليه. قد يفشل استدعاء الـ function أيضاً: على سبيل المثال، قد لا يكون الملف موجوداً، أو قد لا نمتلك الإذن للوصول إلى الملف. تحتاج function الـ File::open إلى طريقة لإخبارنا ما إذا كانت قد نجحت أو فشلت وفي نفس الوقت تعطينا إما الـ file handle أو معلومات الخطأ. هذه المعلومات هي بالضبط ما ينقله enum الـ Result.

في الحالة التي ينجح فيها File::open ، ستكون القيمة في المتغير greeting_file_result مثيلاً (instance) من Ok يحتوي على file handle. وفي الحالة التي يفشل فيها، ستكون القيمة في greeting_file_result instance من Err يحتوي على مزيد من المعلومات حول نوع الخطأ الذي حدث.

نحتاج إلى الإضافة على الكود في القائمة 9-3 لاتخاذ إجراءات مختلفة اعتماداً على القيمة التي يعيدها File::open. توضح القائمة 9-4 إحدى طرق معالجة Result باستخدام أداة أساسية، وهي تعبير المطابقة (match expression) الذي ناقشناه في الفصل السادس.

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("Problem opening the file: {error:?}"),
    };
}

لاحظ أنه، مثل enum الـ Option ، تم جلب enum الـ Result ومتغيراته إلى النطاق (scope) بواسطة التمهيد (prelude)، لذا لا نحتاج إلى تحديد Result:: قبل متغيرات Ok و Err في أذرع (arms) الـ match.

عندما تكون النتيجة Ok ، سيعيد هذا الكود قيمة file الداخلية من variant الـ Ok ، ثم نقوم بتعيين قيمة file handle تلك للمتغير greeting_file. بعد الـ match ، يمكننا استخدام الـ file handle للقراءة أو الكتابة.

الذراع الآخر للـ match يعالج الحالة التي نحصل فيها على قيمة Err من File::open. في هذا المثال، اخترنا استدعاء ماكرو (macro) panic!. إذا لم يكن هناك ملف باسم hello.txt في دليلنا الحالي وقمنا بتشغيل هذا الكود، فسنرى المخرجات التالية من macro الـ panic!:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`

thread 'main' panicked at src/main.rs:8:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

كالعادة، تخبرنا هذه المخرجات بالضبط بما حدث من خطأ.

المطابقة على أخطاء مختلفة (Matching on Different Errors)

الكود في القائمة 9-4 سيقوم بـ panic! بغض النظر عن سبب فشل File::open. ومع ذلك، نريد اتخاذ إجراءات مختلفة لأسباب فشل مختلفة. إذا فشل File::open لأن الملف غير موجود، نريد إنشاء الملف وإرجاع الـ handle للملف الجديد. إذا فشل File::open لأي سبب آخر - على سبيل المثال، لأننا لم نمتلك الإذن لفتح الملف - فلا نزال نريد أن يقوم الكود بـ panic! بنفس الطريقة التي فعلها في القائمة 9-4. لهذا، نضيف match expression داخلياً، كما هو موضح في القائمة 9-5.

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {e:?}"),
            },
            _ => {
                panic!("Problem opening the file: {error:?}");
            }
        },
    };
}

نوع القيمة التي يعيدها File::open داخل variant الـ Err هو io::Error ، وهو هيكل (struct) توفره المكتبة القياسية (standard library). هذا الـ struct لديه method تسمى kind ، يمكننا استدعاؤها للحصول على قيمة io::ErrorKind. يتم توفير enum الـ io::ErrorKind بواسطة الـ standard library ويحتوي على variants تمثل الأنواع المختلفة من الأخطاء التي قد تنتج عن عملية io. الـ variant الذي نريد استخدامه هو ErrorKind::NotFound ، والذي يشير إلى أن الملف الذي نحاول فتحه غير موجود بعد. لذا، نقوم بالمطابقة على greeting_file_result ، ولكن لدينا أيضاً مطابقة داخلية على error.kind().

الشرط الذي نريد التحقق منه في الـ match الداخلي هو ما إذا كانت القيمة التي تعيدها error.kind() هي variant الـ NotFound من enum الـ ErrorKind. إذا كانت كذلك، نحاول إنشاء الملف باستخدام File::create. ومع ذلك، ولأن File::create قد يفشل أيضاً، نحتاج إلى ذراع ثانٍ في الـ match expression الداخلي. عندما لا يمكن إنشاء الملف، يتم طباعة رسالة خطأ مختلفة. يبقى الذراع الثاني للـ match الخارجي كما هو، بحيث يصاب البرنامج بالذعر عند حدوث أي خطأ بخلاف خطأ فقدان الملف.

بدائل لاستخدام match مع Result<T, E>

هذا الكثير من الـ match! تعبير match مفيد جداً ولكنه أيضاً بدائي (primitive) للغاية. في الفصل الثالث عشر، ستتعلم عن الإغلاقات (closures)، والتي تُستخدم مع العديد من الـ methods المعرفة على Result<T, E>. يمكن أن تكون هذه الـ methods أكثر إيجازاً من استخدام match عند التعامل مع قيم Result<T, E> في الكود الخاص بك.

على سبيل المثال، إليك طريقة أخرى لكتابة نفس المنطق الموضح في القائمة 9-5، هذه المرة باستخدام closures و method الـ unwrap_or_else:

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

على الرغم من أن هذا الكود له نفس سلوك القائمة 9-5، إلا أنه لا يحتوي على أي match expressions وهو أكثر نظافة في القراءة. عد إلى هذا المثال بعد قراءة الفصل الثالث عشر وابحث عن method الـ unwrap_or_else في توثيق الـ standard library. العديد من هذه الـ methods يمكنها تنظيف match expressions الضخمة والمتداخلة عند التعامل مع الأخطاء.

اختصارات للذعر عند حدوث خطأ (Shortcuts for Panic on Error)

استخدام match يعمل بشكل جيد بما فيه الكفاية، ولكنه قد يكون مطولاً بعض الشيء ولا يوصل النية (intent) دائماً بشكل جيد. نوع Result<T, E> لديه العديد من الدوال المساعدة (helper methods) المعرفة عليه للقيام بمهام متنوعة وأكثر تحديداً. الـ method المسمى unwrap هو طريقة اختصار مطبقة تماماً مثل match expression الذي كتبناه في القائمة 9-4. إذا كانت قيمة Result هي variant الـ Ok ، سيعيد unwrap القيمة الموجودة داخل Ok. وإذا كان Result هو variant الـ Err ، سيقوم unwrap باستدعاء macro الـ panic! نيابة عنا. إليك مثال على unwrap قيد العمل:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

إذا قمنا بتشغيل هذا الكود بدون ملف hello.txt ، فسنرى رسالة خطأ من استدعاء panic! الذي تقوم به method الـ unwrap:

thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

وبالمثل، تتيح لنا method الـ expect اختيار رسالة خطأ الـ panic!. استخدام expect بدلاً من unwrap وتقديم رسائل خطأ جيدة يمكن أن يوصل intent الخاص بك ويجعل تتبع مصدر الـ panic أسهل. صيغة (syntax) الـ expect تبدو هكذا:

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

نستخدم expect بنفس طريقة unwrap: لإرجاع file handle أو استدعاء macro الـ panic!. رسالة الخطأ المستخدمة بواسطة expect في استدعائها لـ panic! ستكون المعامل (parameter) الذي نمرره لـ expect ، بدلاً من رسالة panic! الافتراضية التي يستخدمها unwrap. إليك كيف يبدو الأمر:

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

في الكود ذو جودة الإنتاج، يختار معظم مبرمجي Rust (Rustaceans) استخدام expect بدلاً من unwrap ويعطون سياقاً أكبر حول سبب توقع نجاح العملية دائماً. بهذه الطريقة، إذا ثبت خطأ افتراضاتك يوماً ما، فستمتلك المزيد من المعلومات لاستخدامها في تصحيح الأخطاء (debugging).

نشر الأخطاء (Propagating Errors)

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

على سبيل المثال، توضح القائمة 9-6 function تقرأ اسم مستخدم من ملف. إذا لم يكن الملف موجوداً أو لم يمكن قراءته، فستعيد هذه الـ function تلك الأخطاء إلى الكود الذي استدعى الـ function.

<Listing number="9-6" file-name="src/main.rs" caption="A function that returns errors to the calling code using `match` ">

```rust
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let username_file_result = File::open("hello.txt");

    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut username = String::new();

    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(e) => Err(e),
    }
}

يمكن كتابة هذه الـ function بطريقة أقصر بكثير، لكننا سنبدأ بالقيام بالكثير منها يدوياً لاستكشاف معالجة الأخطاء؛ وفي النهاية، سنعرض الطريقة الأقصر. دعونا ننظر إلى نوع الإرجاع للـ function أولاً: Result<String, io::Error>. هذا يعني أن الـ function تعيد قيمة من النوع Result<T, E> ، حيث تم ملء المعامل العام T بالنوع الملموس String وتم ملء المعامل العام E بالنوع الملموس io::Error.

إذا نجحت هذه الـ function دون أي مشاكل، فسيستلم الكود الذي يستدعي هذه الـ function قيمة Ok تحمل String - وهو username الذي قرأته هذه الـ function من الملف. وإذا واجهت هذه الـ function أي مشاكل، فسيستلم الكود المستدعي قيمة Err تحمل instance من io::Error يحتوي على مزيد من المعلومات حول ماهية المشاكل. لقد اخترنا io::Error كنوع إرجاع لهذه الـ function لأن هذا هو نوع قيمة الخطأ التي تعيدها كلتا العمليتين اللتين نستدعيهما في جسم (body) هذه الـ function واللتين قد تفشلان: function الـ File::open و method الـ read_to_string.

يبدأ body الـ function باستدعاء function الـ File::open. ثم نعالج قيمة Result باستخدام match مشابه للـ match في القائمة 9-4. إذا نجح File::open ، يصبح file handle الموجود في متغير النمط (pattern variable) المسمى file هو القيمة في المتغير القابل للتغيير username_file وتستمر الـ function. وفي حالة الـ Err ، بدلاً من استدعاء panic! ، نستخدم الكلمة المفتاحية return للخروج مبكراً من الـ function بالكامل وتمرير قيمة الخطأ من File::open ، الموجودة الآن في pattern variable المسمى e ، مرة أخرى إلى الكود المستدعي كقيمة خطأ لهذه الـ function.

لذا، إذا كان لدينا file handle في username_file ، تقوم الـ function بعد ذلك بإنشاء String جديد في المتغير username وتستدعي method الـ read_to_string على file handle الموجود في username_file لقراءة محتويات الملف إلى username. يعيد method الـ read_to_string أيضاً Result لأنه قد يفشل، حتى لو نجح File::open. لذا، نحتاج إلى match آخر لمعالجة ذلك الـ Result: إذا نجح read_to_string ، فقد نجحت الـ function الخاصة بنا، ونعيد اسم المستخدم من الملف الموجود الآن في username مغلفاً بـ Ok. وإذا فشل read_to_string ، فإننا نعيد قيمة الخطأ بنفس الطريقة التي أعدنا بها قيمة الخطأ في الـ match الذي عالج قيمة إرجاع File::open. ومع ذلك، لا نحتاج إلى قول return صراحة، لأن هذا هو التعبير الأخير في الـ function.

سيتعامل الكود الذي يستدعي هذا الكود بعد ذلك مع الحصول على إما قيمة Ok تحتوي على اسم مستخدم أو قيمة Err تحتوي على io::Error. الأمر متروك للكود المستدعي ليقرر ما سيفعله بتلك القيم. إذا حصل الكود المستدعي على قيمة Err ، فيمكنه استدعاء panic! وإيقاف البرنامج، أو استخدام اسم مستخدم افتراضي، أو البحث عن اسم المستخدم من مكان آخر غير الملف، على سبيل المثال. ليس لدينا معلومات كافية عما يحاول الكود المستدعي فعله حقاً، لذا فنحن ننشر جميع معلومات النجاح أو الخطأ للأعلى ليتعامل معها بشكل مناسب.

هذا النمط من نشر الأخطاء شائع جداً في Rust لدرجة أن Rust توفر عامل علامة الاستفهام (question mark operator) ? لجعل ذلك أسهل.

اختصار عامل الـ ? (The ? Operator Shortcut)

توضح القائمة 9-7 تطبيقاً لـ read_username_from_file له نفس وظيفة القائمة 9-6، ولكن هذا التطبيق يستخدم عامل الـ ?.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username_file = File::open("hello.txt")?;
    let mut username = String::new();
    username_file.read_to_string(&mut username)?;
    Ok(username)
}
}

عامل الـ ? الموضوع بعد قيمة Result مُعرف ليعمل بنفس الطريقة تقريباً مثل match expressions التي عرفناها لمعالجة قيم Result في القائمة 9-6. إذا كانت قيمة الـ Result هي Ok ، فسيتم إرجاع القيمة الموجودة داخل الـ Ok من هذا التعبير، وسيستمر البرنامج. وإذا كانت القيمة هي Err ، فسيتم إرجاع الـ Err من الـ function بالكامل كما لو كنا قد استخدمنا الكلمة المفتاحية return بحيث يتم نشر قيمة الخطأ إلى الكود المستدعي.

هناك فرق بين ما يفعله match expression من القائمة 9-6 وما يفعله عامل الـ ?: قيم الخطأ التي يتم استدعاء عامل الـ ? عليها تمر عبر function الـ from ، المعرفة في سمة (trait) الـ From في الـ standard library، والتي تُستخدم لتحويل القيم من نوع إلى آخر. عندما يستدعي عامل الـ ? الـ function المسمى from ، يتم تحويل نوع الخطأ المستلم إلى نوع الخطأ المعرف في نوع إرجاع الـ function الحالية. هذا مفيد عندما تعيد function نوع خطأ واحداً لتمثيل جميع الطرق التي قد تفشل بها الـ function، حتى لو كانت الأجزاء قد تفشل لأسباب عديدة ومختلفة.

على سبيل المثال، يمكننا تغيير function الـ read_username_from_file في القائمة 9-7 لتعيد نوع خطأ مخصصاً باسم OurError نقوم بتعريفه. إذا قمنا أيضاً بتعريف impl From<io::Error> for OurError لإنشاء instance من OurError من io::Error ، فإن استدعاءات عامل الـ ? في body الـ read_username_from_file ستستدعي from وتحول أنواع الأخطاء دون الحاجة إلى إضافة أي كود آخر إلى الـ function.

في سياق القائمة 9-7، فإن الـ ? في نهاية استدعاء File::open سيعيد القيمة الموجودة داخل Ok إلى المتغير username_file. وإذا حدث خطأ، فسيقوم عامل الـ ? بالعودة مبكراً من الـ function بالكامل ويعطي أي قيمة Err للكود المستدعي. وينطبق الشيء نفسه على الـ ? في نهاية استدعاء read_to_string.

يزيل عامل الـ ? الكثير من الكود المتكرر (boilerplate) ويجعل تطبيق هذه الـ function أبسط. يمكننا حتى تقصير هذا الكود أكثر عن طريق ربط (chaining) استدعاءات الـ methods مباشرة بعد الـ ? ، كما هو موضح في القائمة 9-8.

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();

    File::open("hello.txt")?.read_to_string(&mut username)?;

    Ok(username)
}
}

لقد نقلنا إنشاء الـ String الجديد في username إلى بداية الـ function؛ هذا الجزء لم يتغير. وبدلاً من إنشاء متغير username_file ، قمنا بربط استدعاء read_to_string مباشرة بنتيجة File::open("hello.txt")?. لا يزال لدينا ? في نهاية استدعاء read_to_string ، ولا نزال نعيد قيمة Ok تحتوي على username عندما ينجح كل من File::open و read_to_string بدلاً من إرجاع الأخطاء. الوظيفة هي نفسها مرة أخرى كما في القائمة 9-6 والقائمة 9-7؛ هذه مجرد طريقة مختلفة وأكثر راحة (ergonomic) لكتابتها.

توضح القائمة 9-9 طريقة لجعل هذا أقصر باستخدام fs::read_to_string.

#![allow(unused)]
fn main() {
use std::fs;
use std::io;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}
}

قراءة ملف إلى سلسلة نصية هي عملية شائعة إلى حد ما، لذا توفر الـ standard library الـ function المريح fs::read_to_string الذي يفتح الملف، وينشئ String جديداً، ويقرأ محتويات الملف، ويضع المحتويات في ذلك الـ String ، ويعيده. بالطبع، استخدام fs::read_to_string لا يعطينا الفرصة لشرح كل معالجة الأخطاء، لذا قمنا بذلك بالطريقة الأطول أولاً.

أين يمكن استخدام عامل الـ ? (Where to Use the ? Operator)

لا يمكن استخدام عامل الـ ? إلا في الـ functions التي يكون نوع إرجاعها متوافقاً مع القيمة التي يُستخدم عليها الـ ?. وذلك لأن عامل الـ ? مُعرف للقيام بعودة مبكرة لقيمة خارج الـ function، بنفس الطريقة التي يعمل بها match expression الذي عرفناه في القائمة 9-6. في القائمة 9-6، كان الـ match يستخدم قيمة Result ، وكان ذراع العودة المبكرة يعيد قيمة Err(e). يجب أن يكون نوع إرجاع الـ function هو Result بحيث يكون متوافقاً مع هذا الـ return.

في القائمة 9-10، دعونا ننظر إلى الخطأ الذي سنحصل عليه إذا استخدمنا عامل الـ ? في function الـ main بنوع إرجاع غير متوافق مع نوع القيمة التي نستخدم الـ ? عليها.

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

يفتح هذا الكود ملفاً، وهو ما قد يفشل. يتبع عامل الـ ? قيمة الـ Result التي تعيدها File::open ، ولكن function الـ main هذه لها نوع إرجاع () ، وليس Result. عندما نقوم بتجميع هذا الكود، نحصل على رسالة الخطأ التالية:

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
 --> src/main.rs:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greeting_file = File::open("hello.txt")?;
  |                                                ^ cannot use the `?` operator in a function that returns `()`
  |
help: consider adding return type
  |
3 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
4 |     let greeting_file = File::open("hello.txt")?;
5 +     Ok(())
  |

For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` (bin "error-handling") due to 1 previous error

يشير هذا الخطأ إلى أنه مسموح لنا فقط باستخدام عامل الـ ? في function تعيد Result أو Option أو نوعاً آخر يطبق FromResidual.

لإصلاح الخطأ، لديك خياران. أحد الخيارات هو تغيير نوع إرجاع الـ function الخاصة بك ليكون متوافقاً مع القيمة التي تستخدم عامل الـ ? عليها طالما لم يكن لديك قيود تمنع ذلك. الخيار الآخر هو استخدام match أو إحدى methods الـ Result<T, E> لمعالجة الـ Result<T, E> بأي طريقة مناسبة.

ذكرت رسالة الخطأ أيضاً أنه يمكن استخدام الـ ? مع قيم Option<T> أيضاً. كما هو الحال مع استخدام ? على Result ، يمكنك فقط استخدام ? على Option في function تعيد Option. سلوك عامل الـ ? عند استدعائه على Option<T> مشابه لسلوكه عند استدعائه على Result<T, E>: إذا كانت القيمة هي None ، فسيتم إرجاع الـ None مبكراً من الـ function عند تلك النقطة. وإذا كانت القيمة هي Some ، فإن القيمة الموجودة داخل الـ Some هي القيمة الناتجة عن التعبير، وتستمر الـ function. تحتوي القائمة 9-11 على مثال لـ function تجد الحرف الأخير من السطر الأول في النص المعطى.

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

تعيد هذه الـ function القيمة Option<char> لأنه من المحتمل وجود حرف هناك، ولكن من المحتمل أيضاً عدم وجوده. يأخذ هذا الكود وسيط (argument) شريحة السلسلة النصية (string slice) المسمى text ويستدعي method الـ lines عليه، والذي يعيد مكرراً (iterator) على الأسطر في السلسلة النصية. ولأن هذه الـ function تريد فحص السطر الأول، فإنها تستدعي next على الـ iterator للحصول على القيمة الأولى منه. إذا كان text سلسلة نصية فارغة، فسيؤدي استدعاء next هذا إلى إرجاع None ، وفي هذه الحالة نستخدم ? للتوقف وإرجاع None من last_char_of_first_line. وإذا لم يكن text سلسلة نصية فارغة، فسيقوم next بإرجاع قيمة Some تحتوي على string slice للسطر الأول في text.

يقوم الـ ? باستخراج الـ string slice، ويمكننا استدعاء chars على ذلك الـ string slice للحصول على iterator لحروفه. نحن مهتمون بالحرف الأخير في هذا السطر الأول، لذا نستدعي last لإرجاع العنصر الأخير في الـ iterator. هذا هو Option لأنه من المحتمل أن يكون السطر الأول سلسلة نصية فارغة؛ على سبيل المثال، إذا بدأ text بسطر فارغ ولكن لديه حروف في أسطر أخرى، كما في "\nhi". ومع ذلك، إذا كان هناك حرف أخير في السطر الأول، فسيتم إرجاعه في variant الـ Some. يعطينا عامل الـ ? في المنتصف طريقة موجزة للتعبير عن هذا المنطق، مما يسمح لنا بتطبيق الـ function في سطر واحد. إذا لم نتمكن من استخدام عامل الـ ? على Option ، فسنضطر إلى تطبيق هذا المنطق باستخدام المزيد من استدعاءات الـ methods أو match expression.

لاحظ أنه يمكنك استخدام عامل الـ ? على Result في function تعيد Result ، ويمكنك استخدام عامل الـ ? على Option في function تعيد Option ، ولكن لا يمكنك الخلط والمطابقة. لن يقوم عامل الـ ? تلقائياً بتحويل Result إلى Option أو العكس؛ في تلك الحالات، يمكنك استخدام methods مثل method الـ ok على Result أو method الـ ok_or على Option للقيام بالتحويل صراحة.

حتى الآن، جميع الـ functions المسمى main التي استخدمناها تعيد (). الـ function المسمى main خاص لأنه نقطة الدخول ونقطة الخروج لبرنامج قابل للتنفيذ،

وهناك قيود على ما يمكن أن يكون عليه نوع إرجاعها لكي يتصرف البرنامج كما هو متوقع.

لحسن الحظ، يمكن لـ `main` أيضاً إرجاع `Result<(), E>`. تحتوي القائمة 9-12 على الكود من القائمة 9-10، لكننا قمنا بتغيير نوع إرجاع `main` ليكون `Result<(), Box<dyn Error>>` وأضفنا قيمة إرجاع `Ok(())` إلى النهاية. سيتم تجميع هذا الكود الآن.

<Listing number="9-12" file-name="src/main.rs" caption="Changing `main` to return `Result<(), E>` allows the use of the `?` operator on `Result` values.">

```rust,ignore
use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

النوع Box<dyn Error> هو كائن سمة (trait object)، والذي سنتحدث عنه في قسم “استخدام كائنات السمات للتجريد فوق السلوك المشترك” في الفصل الثامن عشر. في الوقت الحالي، يمكنك قراءة Box<dyn Error> لتعني “أي نوع من الأخطاء”. يُسمح باستخدام ? على قيمة Result في function الـ main مع نوع الخطأ Box<dyn Error> لأنه يسمح بإرجاع أي قيمة Err مبكراً. على الرغم من أن body الـ main هذا سيعيد فقط أخطاء من النوع std::io::Error ، إلا أنه من خلال تحديد Box<dyn Error> ، سيبقى هذا التوقيع (signature) صحيحاً حتى لو تمت إضافة المزيد من الكود الذي يعيد أخطاء أخرى إلى body الـ main.

عندما تعيد function الـ main القيمة Result<(), E> ، سيخرج الملف القابل للتنفيذ بقيمة 0 إذا أعادت main القيمة Ok(()) وسيخرج بقيمة غير صفرية إذا أعادت main قيمة Err. تعيد الملفات القابلة للتنفيذ المكتوبة بلغة C أعداداً صحيحة (integers) عند خروجها: البرامج التي تخرج بنجاح تعيد الـ integer 0 ، والبرامج التي تخطئ تعيد عدداً صحيحاً آخر غير 0. تعيد Rust أيضاً integers من الملفات القابلة للتنفيذ لتكون متوافقة مع هذا العرف.

قد تعيد function الـ main أي أنواع تطبق سمة std::process::Termination ، والتي تحتوي على function تسمى report تعيد ExitCode. راجع توثيق الـ standard library لمزيد من المعلومات حول تطبيق سمة Termination لأنواعك الخاصة.

الآن بعد أن ناقشنا تفاصيل استدعاء panic! أو إرجاع Result ، دعونا نعود إلى موضوع كيفية تحديد أيهما مناسب للاستخدام في أي حالات.

استخدام panic! أو عدم استخدامه

استخدام panic! أو عدم استخدامه (To panic! or Not to panic!)

إذاً، كيف تقرر متى يجب عليك استدعاء panic! ومتى يجب عليك إعادة Result؟ عندما يصاب الكود بـ (الذعر) panic ، لا توجد طريقة للاسترداد. يمكنك استدعاء panic! في أي حالة خطأ، سواء كانت هناك طريقة ممكنة للاسترداد أم لا، ولكنك بذلك تتخذ القرار نيابة عن الكود المستدعي بأن الموقف غير قابل للاسترداد. عندما تختار إعادة قيمة Result ، فإنك تمنح الكود المستدعي خيارات؛ حيث يمكن للكود المستدعي اختيار محاولة الاسترداد بطريقة مناسبة لموقفه، أو يمكنه تقرير أن قيمة Err في هذه الحالة غير قابلة للاسترداد، وبالتالي يمكنه استدعاء panic! وتحويل خطئك القابل للاسترداد إلى خطأ غير قابل للاسترداد. لذلك، تعد إعادة Result خياراً افتراضياً جيداً عند تعريف دالة قد تفشل.

في حالات مثل الأمثلة، وكود النماذج الأولية، والاختبارات، يكون من الأنسب كتابة كود يصاب بالذعر بدلاً من إعادة Result. دعنا نستكشف السبب، ثم نناقش الحالات التي لا يستطيع فيها المترجم معرفة أن الفشل مستحيل، ولكن يمكنك أنت كبشر معرفة ذلك. سينتهي الفصل ببعض الإرشادات العامة حول كيفية تقرير ما إذا كان يجب استخدام panic! في كود المكتبة.

الأمثلة، وكود النماذج الأولية، والاختبارات (Examples, Prototype Code, and Tests)

عندما تكتب مثالاً لتوضيح مفهوم ما، فإن تضمين كود قوي للتعامل مع الأخطاء يمكن أن يجعل المثال أقل وضوحاً. في الأمثلة، من المفهوم أن استدعاء (منهج) method مثل unwrap الذي قد يؤدي إلى panic هو بمثابة مكان محجوز للطريقة التي تريد أن يتعامل بها تطبيقك مع الأخطاء، والتي يمكن أن تختلف بناءً على ما يفعله باقي الكود الخاص بك.

وبالمثل، فإن منهجي unwrap و expect مفيدان جداً عندما تقوم ببناء (نموذج أولي) prototyping ولم تكن مستعداً بعد لتقرير كيفية التعامل مع الأخطاء؛ فهما يتركان علامات واضحة في كودك للموعد الذي ستكون فيه مستعداً لجعل برنامجك أكثر قوة.

إذا فشل استدعاء منهج في اختبار ما، فستحتاج إلى فشل الاختبار بأكمله، حتى لو لم يكن هذا المنهج هو الوظيفة قيد الاختبار. ولأن panic! هي الطريقة التي يتم بها وضع علامة على الاختبار كفاشل، فإن استدعاء unwrap أو expect هو بالضبط ما يجب أن يحدث.

عندما تمتلك معلومات أكثر من المترجم (When You Have More Information Than the Compiler)

سيكون من المناسب أيضاً استدعاء expect عندما يكون لديك منطق آخر يضمن أن Result ستحتوي على قيمة Ok ، ولكن هذا المنطق ليس شيئاً يفهمه المترجم. ستظل لديك قيمة Result تحتاج إلى التعامل معها: فأي عملية تستدعيها لا تزال لديها إمكانية الفشل بشكل عام، على الرغم من أنها مستحيلة منطقياً في حالتك الخاصة. إذا كان بإمكانك التأكد من خلال فحص الكود يدوياً أنك لن تحصل أبداً على (متغير) variant من نوع Err ، فمن المقبول تماماً استدعاء expect وتوثيق السبب الذي يجعلك تعتقد أنك لن تحصل أبداً على Err في نص الوسيطة. إليك مثالاً:

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

نحن نقوم بإنشاء (نموذج) instance من IpAddr عن طريق تحليل سلسلة نصية مكتوبة برمجياً (Hardcoded). يمكننا أن نرى أن 127.0.0.1 هو عنوان IP صالح، لذا فمن المقبول استخدام expect هنا. ومع ذلك، فإن وجود سلسلة نصية صالحة ومكتوبة برمجياً لا يغير نوع الإرجاع لمنهج parse: فنحن لا نزال نحصل على قيمة Result ، وسيظل المترجم يجبرنا على التعامل مع Result كما لو كان متغير Err ممكناً لأن المترجم ليس ذكياً بما يكفي ليرى أن هذه السلسلة هي دائماً عنوان IP صالح. إذا جاءت سلسلة عنوان IP من مستخدم بدلاً من كونها مكتوبة برمجياً في البرنامج وبالتالي كانت لديها إمكانية الفشل، فسنرغب بالتأكيد في التعامل مع Result بطريقة أكثر قوة بدلاً من ذلك. إن ذكر الافتراض بأن عنوان IP هذا مكتوب برمجياً سيحثنا على تغيير expect إلى كود أفضل للتعامل مع الأخطاء إذا احتجنا في المستقبل إلى الحصول على عنوان IP من مصدر آخر بدلاً من ذلك.

إرشادات للتعامل مع الأخطاء (Guidelines for Error Handling)

يُنصح بجعل كودك يصاب بالذعر عندما يكون من الممكن أن ينتهي به المطاف في (حالة سيئة) bad state. في هذا السياق، تكون الحالة السيئة عندما يتم كسر بعض الافتراضات أو الضمانات أو العقود أو (الثوابت) invariants ، مثل تمرير قيم غير صالحة أو قيم متناقضة أو قيم مفقودة إلى كودك - بالإضافة إلى واحد أو أكثر مما يلي:

• الحالة السيئة هي شيء غير متوقع، على عكس شيء من المحتمل أن يحدث أحياناً، مثل إدخال المستخدم لبيانات بتنسيق خاطئ.
• يحتاج كودك بعد هذه النقطة إلى الاعتماد على عدم وجوده في هذه الحالة السيئة، بدلاً من التحقق من المشكلة في كل خطوة.
• لا توجد طريقة جيدة لترميز هذه المعلومات في الأنواع التي تستخدمها. سنعمل من خلال مثال لما نعنيه في “ترميز الحالات والسلوك كأنواع” في الفصل 18.

إذا قام شخص ما باستدعاء كودك ومرر قيماً غير منطقية، فمن الأفضل إعادة خطأ إذا استطعت حتى يتمكن مستخدم المكتبة من تقرير ما يريد فعله في هذه الحالة. ومع ذلك، في الحالات التي قد يكون فيها الاستمرار غير آمن أو ضاراً، قد يكون الخيار الأفضل هو استدعاء panic! وتنبيه الشخص الذي يستخدم مكتبتك إلى وجود (خطأ برمجى) bug في كوده حتى يتمكن من إصلاحه أثناء التطوير. وبالمثل، غالباً ما يكون panic! مناسباً إذا كنت تستدعي كوداً خارجياً خارجاً عن سيطرتك ويعيد حالة غير صالحة ليس لديك طريقة لإصلاحها.

ومع ذلك، عندما يكون الفشل متوقعاً، فمن الأنسب إعادة Result بدلاً من إجراء استدعاء panic!. تشمل الأمثلة إعطاء (محلل) parser بيانات مشوهة أو إعادة طلب HTTP لحالة تشير إلى أنك وصلت إلى حد المعدل (Rate limit). في هذه الحالات، تشير إعادة Result إلى أن الفشل هو احتمال متوقع يجب على الكود المستدعي تقرير كيفية التعامل معه.

عندما يؤدي كودك عملية قد تعرض المستخدم للخطر إذا تم استدعاؤها باستخدام قيم غير صالحة، يجب أن يتحقق كودك من صحة القيم أولاً ويصاب بالذعر إذا لم تكن القيم صالحة. هذا في الغالب لأسباب تتعلق بالسلامة: فمحاولة العمل على بيانات غير صالحة يمكن أن تعرض كودك لثغرات أمنية. هذا هو السبب الرئيسي الذي يجعل المكتبة القياسية تستدعي panic! إذا حاولت الوصول إلى ذاكرة خارج الحدود: فمحاولة الوصول إلى ذاكرة لا تنتمي إلى هيكل البيانات الحالي هي مشكلة أمنية شائعة. غالباً ما يكون للدوال (عقود) contracts: حيث يكون سلوكها مضموناً فقط إذا كانت المدخلات تلبي متطلبات معينة. إن الإصابة بالذعر عند انتهاك العقد أمر منطقي لأن انتهاك العقد يشير دائماً إلى خطأ من جانب المستدعي، وليس نوعاً من الأخطاء التي تريد أن يضطر الكود المستدعي للتعامل معها صراحة. في الواقع، لا توجد طريقة معقولة للكود المستدعي للاسترداد؛ بل يحتاج المبرمجون المستدعون إلى إصلاح الكود. يجب شرح عقود الدالة، خاصة عندما يتسبب الانتهاك في حدوث ذعر، في توثيق API للدالة.

ومع ذلك، فإن وجود الكثير من عمليات التحقق من الأخطاء في جميع دوالك سيكون مطولاً ومزعجاً. لحسن الحظ، يمكنك استخدام (نظام الأنواع) type system في Rust (وبالتالي فحص الأنواع الذي يقوم به المترجم) للقيام بالعديد من عمليات التحقق نيابة عنك. إذا كانت دالتك تحتوي على نوع معين كمعلمة، فيمكنك المضي قدماً في منطق كودك مع العلم أن المترجم قد تأكد بالفعل من أن لديك قيمة صالحة. على سبيل المثال، إذا كان لديك نوع بدلاً من Option ، فإن برنامجك يتوقع الحصول على شيء ما بدلاً من لا شيء. لا يتعين على كودك بعد ذلك التعامل مع حالتين لمتغيري Some و None: سيكون لديه حالة واحدة فقط للحصول على قيمة بالتأكيد. الكود الذي يحاول تمرير “لا شيء” إلى دالتك لن يتم تجميعه حتى، لذا لا يتعين على دالتك التحقق من هذه الحالة في وقت التشغيل. مثال آخر هو استخدام نوع صحيح غير موقع مثل u32 ، والذي يضمن أن المعلمة ليست سالبة أبداً.

أنواع مخصصة للتحقق من الصحة (Custom Types for Validation)

دعنا نأخذ فكرة استخدام نظام الأنواع في Rust لضمان حصولنا على قيمة صالحة خطوة إلى الأمام وننظر في إنشاء نوع مخصص للتحقق من الصحة. تذكر لعبة التخمين في الفصل الثاني التي طلب فيها كودنا من المستخدم تخمين رقم بين 1 و 100. لم نقم أبداً بالتحقق من أن تخمين المستخدم كان بين تلك الأرقام قبل التحقق منه مقابل رقمنا السري؛ لقد تحققنا فقط من أن التخمين كان موجباً. في هذه الحالة، لم تكن العواقب وخيمة للغاية: فمخرجاتنا “عالية جداً” أو “منخفضة جداً” ستظل صحيحة. ولكن سيكون من التحسينات المفيدة توجيه المستخدم نحو التخمينات الصالحة ويكون له سلوك مختلف عندما يخمن المستخدم رقماً خارج النطاق مقابل عندما يكتب المستخدم، على سبيل المثال، حروفاً بدلاً من ذلك.

إحدى الطرق للقيام بذلك هي تحليل التخمين كـ i32 بدلاً من u32 فقط للسماح بالأرقام السالبة المحتملة، ثم إضافة فحص لكون الرقم في النطاق، هكذا:

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        // --snip--

        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: i32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        if guess < 1 || guess > 100 {
            println!("The secret number will be between 1 and 100.");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --snip--
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

يتحقق تعبير if مما إذا كانت قيمتنا خارج النطاق، ويخبر المستخدم بالمشكلة، ويستدعي continue لبدء التكرار التالي للحلقة وطلب تخمين آخر. بعد تعبير if ، يمكننا المضي قدماً في المقارنات بين guess والرقم السري مع العلم أن guess بين 1 و 100.

ومع ذلك، هذا ليس حلاً مثالياً: فإذا كان من الضروري تماماً أن يعمل البرنامج فقط على القيم بين 1 و 100، وكان لديه العديد من الدوال بهذا المتطلب، فإن وجود فحص مثل هذا في كل دالة سيكون مملاً (وقد يؤثر على الأداء).

بدلاً من ذلك، يمكننا إنشاء نوع جديد في وحدة مخصصة ووضع عمليات التحقق من الصحة في دالة لإنشاء نموذج من النوع بدلاً من تكرار عمليات التحقق في كل مكان. بهذه الطريقة، يكون من الآمن للدوال استخدام النوع الجديد في (توقيعاتها) signatures واستخدام القيم التي تتلقاها بثقة. تعرض القائمة 9-13 إحدى الطرق لتعريف نوع Guess الذي سيقوم فقط بإنشاء نموذج من Guess إذا تلقت دالة new قيمة بين 1 و 100.

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

لاحظ أن هذا الكود في src/guessing_game.rs يعتمد على إضافة إعلان وحدة mod guessing_game; في src/lib.rs لم نعرضه هنا. داخل ملف هذه الوحدة الجديدة، نعرف هيكلاً يسمى Guess يحتوي على حقل يسمى value يحمل i32. هذا هو المكان الذي سيتم فيه تخزين الرقم.

بعد ذلك، نقوم بتنفيذ دالة مرتبطة تسمى new على Guess تقوم بإنشاء نماذج من قيم Guess. تم تعريف دالة new لتكون لها معلمة واحدة تسمى value من نوع i32 وتعيد Guess. يختبر الكود الموجود في جسم دالة new القيمة value للتأكد من أنها بين 1 و 100. إذا لم تجتز value هذا الاختبار، فإننا نجري استدعاء panic! ، والذي سينبه المبرمج الذي يكتب الكود المستدعي بأن لديه خطأ برمجياً يحتاج إلى إصلاحه، لأن إنشاء Guess بقيمة value خارج هذا النطاق سينتهك العقد الذي تعتمد عليه Guess::new. يجب مناقشة الظروف التي قد تؤدي فيها Guess::new إلى حدوث ذعر في توثيق API العام الخاص بها؛ سنغطي اصطلاحات التوثيق التي تشير إلى إمكانية حدوث panic! في توثيق API الذي تنشئه في الفصل 14. إذا اجتازت value الاختبار، فإننا ننشئ Guess جديداً مع ضبط حقل value الخاص به على معلمة value ونعيد Guess.

بعد ذلك، نقوم بتنفيذ منهج يسمى value يستعير self ، وليس له أي معلمات أخرى، ويعيد i32. يسمى هذا النوع من المناهج أحياناً (جالب) getter لأن الغرض منه هو الحصول على بعض البيانات من حقوله وإعادتها. هذا المنهج العام ضروري لأن حقل value في هيكل Guess خاص. من المهم أن يكون حقل value خاصاً حتى لا يُسمح للكود الذي يستخدم هيكل Guess بضبط value مباشرة: يجب على الكود خارج وحدة guessing_game استخدام دالة Guess::new لإنشاء نموذج من Guess ، مما يضمن عدم وجود طريقة لـ Guess للحصول على value لم يتم فحصها بواسطة الشروط الموجودة في دالة Guess::new.

يمكن للدالة التي تحتوي على معلمة أو تعيد فقط أرقاماً بين 1 و 100 أن تعلن في توقيعها أنها تأخذ أو تعيد Guess بدلاً من i32 ولن تحتاج إلى إجراء أي فحوصات إضافية في جسمها.

ملخص (Summary)

تم تصميم ميزات التعامل مع الأخطاء في Rust لمساعدتك على كتابة كود أكثر قوة. يشير (ماكرو) macro المسمى panic! إلى أن برنامجك في حالة لا يمكنه التعامل معها ويسمح لك بإخبار العملية بالتوقف بدلاً من محاولة المضي قدماً بقيم غير صالحة أو غير صحيحة. يستخدم (تعداد) enum المسمى Result نظام الأنواع في Rust للإشارة إلى أن العمليات قد تفشل بطريقة يمكن لكودك الاسترداد منها. يمكنك استخدام Result لإخبار الكود الذي يستدعي كودك بأنه يحتاج إلى التعامل مع النجاح أو الفشل المحتمل أيضاً. إن استخدام panic! و Result في المواقف المناسبة سيجعل كودك أكثر موثوقية في مواجهة المشكلات الحتمية.

الآن بعد أن رأيت طرقاً مفيدة تستخدم بها المكتبة القياسية (الأنواع العامة) generics مع تعدادي Option و Result ، سنتحدث عن كيفية عمل الأنواع العامة وكيف يمكنك استخدامها في كودك.

الأنواع العامة والسمات وفترات الحياة

تمتلك كل لغة برمجة أدوات للتعامل بفعالية مع تكرار المفاهيم. في لغة Rust، إحدى هذه الأدوات هي الأنواع العامة (generics): وهي بدائل مجردة للأنواع الملموسة (concrete types) أو الخصائص الأخرى. يمكننا التعبير عن سلوك generics أو كيفية ارتباطها بـ generics أخرى دون معرفة ما سيحل محلها عند تصريف (compiling) وتشغيل الكود.

يمكن للدوال أن تأخذ معاملات من نوع عام (generic type)، بدلاً من نوع ملموس (concrete type) مثل i32 أو String بنفس الطريقة التي تأخذ بها معاملات بقيم غير معروفة لتشغيل نفس الكود على قيم ملموسة متعددة. في الواقع، لقد استخدمنا بالفعل generics في الفصل السادس مع Option<T>، وفي الفصل الثامن مع Vec<T> و HashMap<K, V>، وفي الفصل التاسع مع Result<T, E>. في هذا الفصل، ستستكشف كيفية تعريف الأنواع والدوال والطرق (methods) الخاصة بك باستخدام generics!

أولاً، سنراجع كيفية استخراج دالة لتقليل تكرار الكود. سنستخدم بعد ذلك نفس التقنية لإنشاء دالة عامة (generic function) من دالتين تختلفان فقط في أنواع معاملاتهما. سنشرح أيضاً كيفية استخدام generic types في تعريفات الهياكل (structs) والتعدادات (enums).

بعد ذلك، ستتعلم كيفية استخدام السمات (traits) لتعريف السلوك بطريقة عامة. يمكنك دمج traits مع generic types لتقييد generic type لقبول تلك الأنواع التي تمتلك سلوكاً معيناً فقط، بدلاً من قبول أي نوع فحسب.

أخيراً، سنناقش فترات الحياة (lifetimes): وهي نوع من generics تزود المترجم (compiler) بمعلومات حول كيفية ارتباط المراجع (references) ببعضها البعض. تسمح لنا lifetimes بإعطاء compiler معلومات كافية حول القيم المستعارة (borrowed values) حتى يتمكن من ضمان أن references ستكون صالحة في مواقف أكثر مما يمكنه فعله بدون مساعدتنا.

إزالة التكرار عن طريق استخراج دالة

تسمح لنا generics باستبدال أنواع محددة بعنصر نائب (placeholder) يمثل أنواعاً متعددة لإزالة تكرار الكود. قبل الغوص في بناء جملة (syntax) الـ generics، دعونا ننظر أولاً في كيفية إزالة التكرار بطريقة لا تتضمن generic types عن طريق استخراج دالة تستبدل قيمًا محددة بـ placeholder يمثل قيمًا متعددة. بعد ذلك، سنطبق نفس التقنية لاستخراج generic function! من خلال النظر في كيفية التعرف على الكود المكرر الذي يمكنك استخراجه إلى دالة، ستبدأ في التعرف على الكود المكرر الذي يمكنه استخدام generics.

سنبدأ بالبرنامج القصير في القائمة 10-1 الذي يجد أكبر رقم في قائمة.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
    assert_eq!(*largest, 100);
}

نقوم بتخزين قائمة من الأعداد الصحيحة في المتغير number_list ونضع مرجعاً (reference) لأول رقم في القائمة في متغير يسمى largest. ثم نقوم بالتكرار (iterate) عبر جميع الأرقام في القائمة، وإذا كان الرقم الحالي أكبر من الرقم المخزن في largest نقوم باستبدال reference في ذلك المتغير. ومع ذلك، إذا كان الرقم الحالي أقل من أو يساوي أكبر رقم شوهد حتى الآن، فلا يتغير المتغير، وينتقل الكود إلى الرقم التالي في القائمة. بعد النظر في جميع الأرقام في القائمة، يجب أن يشير largest إلى أكبر رقم، وهو في هذه الحالة 100.

لقد كُلفنا الآن بالعثور على أكبر رقم في قائمتين مختلفتين من الأرقام. للقيام بذلك، يمكننا اختيار تكرار الكود الموجود في القائمة 10-1 واستخدام نفس المنطق في مكانين مختلفين في البرنامج، كما هو موضح في القائمة 10-2.

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
}

على الرغم من أن هذا الكود يعمل، إلا أن تكرار الكود أمر ممل وعرضة للخطأ. كما يتعين علينا تذكر تحديث الكود في أماكن متعددة عندما نريد تغييره.

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

في القائمة 10-3، نستخرج الكود الذي يجد أكبر رقم في دالة تسمى largest. ثم نستدعي الدالة للعثور على أكبر رقم في القائمتين من القائمة 10-2. يمكننا أيضاً استخدام الدالة على أي قائمة أخرى من قيم i32 قد تكون لدينا في المستقبل.

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 6000);
}

تمتلك الدالة largest معاملًا يسمى list يمثل أي شريحة (slice) ملموسة من قيم i32 قد نمررها إلى الدالة. ونتيجة لذلك، عندما نستدعي الدالة، يتم تشغيل الكود على القيم المحددة التي نمررها.

باختصار، إليك الخطوات التي اتخذناها لتغيير الكود من القائمة 10-2 إلى القائمة 10-3:

1. تحديد الكود المكرر.
2. استخراج الكود المكرر في جسم الدالة، وتحديد المدخلات وقيم الإرجاع (return values) لهذا الكود في توقيع الدالة (function signature).
3. تحديث مثيلي الكود المكرر لاستدعاء الدالة بدلاً من ذلك.

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

على سبيل المثال، لنفترض أن لدينا دالتين: واحدة تجد أكبر عنصر في slice من قيم i32 وأخرى تجد أكبر عنصر في slice من قيم char. كيف سنزيل هذا التكرار؟ لنكتشف ذلك!

أنواع البيانات العامة (Generic Data Types)

أنواع البيانات العامة (Generic Data Types)

نستخدم الـ generics لإنشاء تعريفات لعناصر مثل توقيعات الدوال (function signatures) أو الـ structs، والتي يمكننا بعد ذلك استخدامها مع العديد من أنواع البيانات الملموسة (concrete data types) المختلفة. دعنا ننظر أولاً إلى كيفية تعريف الـ functions، الـ structs، الـ enums، والـ methods باستخدام الـ generics. بعد ذلك، سنناقش كيف تؤثر الـ generics على أداء الكود.

في تعريفات الدوال

عند تعريف function تستخدم الـ generics، نضع الـ generics في توقيع الـ function حيث نحدد عادةً أنواع البيانات (data types) للمعلمات (parameters) وقيمة الإرجاع (return value). يؤدي القيام بذلك إلى جعل الكود الخاص بنا أكثر مرونة ويوفر وظائف أكثر لمستدعي الـ function مع منع تكرار الكود.

بالاستمرار مع الـ function largest، تُظهر القائمة 10-4 دالتين تجدان أكبر قيمة في شريحة (slice). سنقوم بعد ذلك بدمج هاتين الدالتين في function واحدة تستخدم الـ generics.

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {result}");
    assert_eq!(*result, 'y');
}

الدالة largest_i32 هي الدالة التي استخرجناها في القائمة 10-3 والتي تجد أكبر i32 في slice. تجد الدالة largest_char أكبر char في slice. تحتوي نصوص الدوال على نفس الكود، لذا دعنا نتخلص من التكرار عن طريق إدخال معلمة نوع عام (generic type parameter) في function واحدة.

لتعيين الـ types كـ parameters في function واحدة جديدة، نحتاج إلى تسمية الـ type parameter، تمامًا كما نفعل لـ value parameters لـ function. يمكنك استخدام أي معرف (identifier) كاسم لـ type parameter. لكننا سنستخدم T لأنه، حسب الاصطلاح، تكون أسماء الـ type parameter في Rust قصيرة، وغالبًا ما تكون حرفًا واحدًا فقط، واصطلاح تسمية الـ type في Rust هو UpperCamelCase. T، اختصار لـ type، هو الخيار الافتراضي لمعظم مبرمجي Rust.

عندما نستخدم parameter في نص الـ function، يجب علينا الإعلان عن اسم الـ parameter في التوقيع حتى يعرف المترجم (compiler) ما يعنيه هذا الاسم. وبالمثل، عندما نستخدم اسم type parameter في توقيع function، يجب علينا الإعلان عن اسم الـ type parameter قبل استخدامه. لتعريف الـ generic function largest، نضع إعلانات اسم الـ type داخل أقواس زاوية، <>، بين اسم الـ function وقائمة الـ parameters، مثل هذا:

fn largest<T>(list: &[T]) -> &T {

نقرأ هذا التعريف على أنه “الدالة largest عامة (generic) على نوع ما T.” تحتوي هذه الـ function على parameter واحد يسمى list، وهو slice من القيم من النوع T. ستُرجع الدالة largest مرجعًا (reference) إلى قيمة من نفس النوع T.

تُظهر القائمة 10-5 تعريف الـ function largest المدمج باستخدام نوع البيانات العام (generic data type) في توقيعها. تُظهر القائمة أيضًا كيف يمكننا استدعاء الـ function إما بـ slice من قيم i32 أو قيم char. لاحظ أن هذا الكود لن يتم تجميعه بعد.

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {result}");
}

إذا قمنا بـ compile هذا الكود الآن، فسنحصل على هذا الخطأ:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T` with trait `PartialOrd`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

For more information about this error, try `rustc --explain E0369`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

يذكر نص المساعدة std::cmp::PartialOrd، وهو سمة (trait)، وسنتحدث عن الـ traits في القسم التالي. في الوقت الحالي، اعلم أن هذا الخطأ ينص على أن نص largest لن يعمل لجميع الـ types الممكنة التي يمكن أن يكونها T. نظرًا لأننا نريد مقارنة قيم من النوع T في النص، يمكننا فقط استخدام الـ types التي يمكن ترتيب قيمها. لتمكين المقارنات، تحتوي المكتبة القياسية (standard library) على الـ trait std::cmp::PartialOrd الذي يمكنك تطبيقه على الـ types (راجع الملحق ج لمزيد من المعلومات حول هذا الـ trait). لإصلاح القائمة 10-5، يمكننا اتباع اقتراح نص المساعدة وتقييد الـ types الصالحة لـ T على تلك التي تطبق PartialOrd فقط. سيتم بعد ذلك تجميع القائمة، لأن الـ standard library تطبق PartialOrd على كل من i32 و char.

في تعريفات الـ Struct

يمكننا أيضًا تعريف الـ structs لاستخدام generic type parameter في حقل واحد أو أكثر باستخدام بناء جملة <>. تحدد القائمة 10-6 struct Point<T> للاحتفاظ بقيم إحداثيات x و y من أي نوع.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

بناء الجملة لاستخدام الـ generics في تعريفات الـ struct مشابه لذلك المستخدم في تعريفات الـ function. أولاً، نعلن عن اسم الـ type parameter داخل أقواس زاوية مباشرة بعد اسم الـ struct. بعد ذلك، نستخدم الـ generic type في تعريف الـ struct حيث كنا سنحدد أنواع البيانات الملموسة.

لاحظ أنه نظرًا لأننا استخدمنا generic type واحدًا فقط لتعريف Point<T>، فإن هذا التعريف يقول إن struct Point<T> عام على نوع ما T، وأن الـ fields x و y هما كلاهما من نفس النوع، مهما كان هذا النوع. إذا أنشأنا مثيلًا لـ Point<T> يحتوي على قيم من أنواع مختلفة، كما في القائمة 10-7، فلن يتم تجميع الكود الخاص بنا.

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

في هذا المثال، عندما نخصص القيمة الصحيحة 5 لـ x، فإننا نُعلم الـ compiler أن الـ generic type T سيكون عددًا صحيحًا لهذا المثيل من Point<T>. بعد ذلك، عندما نحدد 4.0 لـ y، والذي حددناه ليكون من نفس نوع x، سنحصل على خطأ عدم تطابق النوع (type mismatch) مثل هذا:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wont_work = Point { x: 5, y: 4.0 };
  |                                      ^^^ expected integer, found floating-point number

For more information about this error, try `rustc --explain E0308`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

لتعريف struct Point حيث يكون x و y كلاهما generics ولكنهما يمكن أن يكونا من أنواع مختلفة، يمكننا استخدام multiple generic type parameters. على سبيل المثال، في القائمة 10-8، نغير تعريف Point ليكون عامًا على الـ types T و U حيث يكون x من النوع T و y من النوع U.

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let both_integer = Point { x: 5, y: 10 };
    let both_float = Point { x: 1.0, y: 4.0 };
    let integer_and_float = Point { x: 5, y: 4.0 };
}

الآن جميع مثيلات Point الموضحة مسموح بها! يمكنك استخدام أي عدد تريده من generic type parameters في تعريف، ولكن استخدام أكثر من عدد قليل يجعل الكود الخاص بك صعب القراءة. إذا وجدت أنك بحاجة إلى الكثير من الـ generic types في الكود الخاص بك، فقد يشير ذلك إلى أن الكود الخاص بك يحتاج إلى إعادة هيكلة (restructuring) إلى أجزاء أصغر.

في تعريفات الـ Enum

كما فعلنا مع الـ structs، يمكننا تعريف الـ enums للاحتفاظ بـ generic data types في متغيراتها (variants). دعنا نلقي نظرة أخرى على الـ enum Option<T> الذي توفره الـ standard library، والذي استخدمناه في الفصل 6:

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

يجب أن يكون هذا التعريف أكثر منطقية بالنسبة لك الآن. كما ترى، فإن الـ enum Option<T> عام على النوع T وله متغيران: Some، الذي يحتوي على قيمة واحدة من النوع T، ومتغير None الذي لا يحتوي على أي قيمة. باستخدام الـ enum Option<T>، يمكننا التعبير عن المفهوم المجرد للقيمة الاختيارية (optional value)، ولأن Option<T> عام، يمكننا استخدام هذا التجريد بغض النظر عن نوع القيمة الاختيارية.

يمكن أن تستخدم الـ Enums أنواعًا عامة متعددة أيضًا. تعريف الـ enum Result الذي استخدمناه في الفصل 9 هو أحد الأمثلة:

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

الـ enum Result عام على نوعين، T و E، وله متغيران: Ok، الذي يحتوي على قيمة من النوع T، و Err، الذي يحتوي على قيمة من النوع E. يجعل هذا التعريف من الملائم استخدام الـ enum Result في أي مكان لدينا عملية قد تنجح (تُرجع قيمة من نوع ما T) أو تفشل (تُرجع خطأ من نوع ما E). في الواقع، هذا ما استخدمناه لفتح ملف في القائمة 9-3، حيث تم ملء T بالنوع std::fs::File عندما تم فتح الملف بنجاح وتم ملء E بالنوع std::io::Error عندما كانت هناك مشاكل في فتح الملف.

عندما تدرك مواقف في الكود الخاص بك مع تعريفات struct أو enum متعددة تختلف فقط في أنواع القيم التي تحتفظ بها، يمكنك تجنب التكرار باستخدام generic types بدلاً من ذلك.

في تعريفات الـ Method

يمكننا تطبيق الـ methods على الـ structs والـ enums (كما فعلنا في الفصل 5) واستخدام generic types في تعريفاتها أيضًا. تُظهر القائمة 10-9 struct Point<T> الذي عرفناه في القائمة 10-6 مع method يسمى x مطبق عليه.

struct Point<T> {
    x: T,
    y: T,
}

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

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

هنا، قمنا بتعريف method يسمى x على Point<T> يُرجع reference إلى البيانات الموجودة في الـ field x.

لاحظ أنه يجب علينا الإعلان عن T مباشرة بعد impl حتى نتمكن من استخدام T لتحديد أننا نطبق الـ methods على النوع Point<T>. من خلال الإعلان عن T كـ generic type بعد impl، يمكن لـ Rust تحديد أن النوع الموجود في الأقواس الزاوية في Point هو generic type بدلاً من concrete type. كان بإمكاننا اختيار اسم مختلف لـ generic parameter هذا عن الـ generic parameter المعلن في تعريف الـ struct، ولكن استخدام نفس الاسم هو اصطلاح. إذا كتبت method داخل impl يعلن عن generic type، فسيتم تعريف هذا الـ method على أي مثيل من النوع، بغض النظر عن الـ concrete type الذي ينتهي به الأمر ليحل محل الـ generic type.

يمكننا أيضًا تحديد قيود (constraints) على الـ generic types عند تعريف الـ methods على النوع. يمكننا، على سبيل المثال، تطبيق الـ methods فقط على مثيلات Point<f32> بدلاً من مثيلات Point<T> بأي generic type. في القائمة 10-10، نستخدم الـ concrete type f32، مما يعني أننا لا نعلن عن أي types بعد impl.

struct Point<T> {
    x: T,
    y: T,
}

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

impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

يعني هذا الكود أن النوع Point<f32> سيكون له method distance_from_origin؛ لن يكون لدى المثيلات الأخرى من Point<T> حيث T ليس من النوع f32 هذا الـ method المعرف. يقيس الـ method مدى بعد نقطتنا عن النقطة عند الإحداثيات (0.0، 0.0) ويستخدم العمليات الرياضية المتاحة فقط لـ floating-point types.

لا تكون generic type parameters في تعريف struct دائمًا هي نفسها التي تستخدمها في توقيعات الـ method لنفس الـ struct. تستخدم القائمة 10-11 الـ generic types X1 و Y1 لـ struct Point و X2 و Y2 لـ method signature mixup لجعل المثال أكثر وضوحًا. ينشئ الـ method مثيل Point جديدًا بقيمة x من self Point (من النوع X1) وقيمة y من Point الذي تم تمريره (من النوع Y2).

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

في main، قمنا بتعريف Point يحتوي على i32 لـ x (بقيمة 5) و f64 لـ y (بقيمة 10.4). المتغير p2 هو struct Point يحتوي على string slice لـ x (بقيمة "Hello") و char لـ y (بقيمة c). استدعاء mixup على p1 بالوسيطة p2 يعطينا p3، وستطبع نتيجة الاستدعاء p3.x = 5, p3.y = c.

الغرض من هذا المثال هو إظهار موقف يتم فيه الإعلان عن بعض الـ generic parameters باستخدام impl ويتم الإعلان عن البعض الآخر باستخدام تعريف الـ method. هنا، يتم الإعلان عن الـ generic parameters X1 و Y1 بعد impl لأنهما يذهبان مع تعريف الـ struct. يتم الإعلان عن الـ generic parameters X2 و Y2 بعد fn mixup لأنهما لا يتعلقان إلا بالـ method.

أداء الكود الذي يستخدم الـ Generics

قد تتساءل عما إذا كانت هناك تكلفة في وقت التشغيل (runtime cost) عند استخدام generic type parameters. الخبر السار هو أن استخدام generic types لن يجعل برنامجك يعمل أبطأ مما لو كان بأنواع ملموسة (concrete types).

تحقق Rust ذلك عن طريق إجراء تنميط أحادي (monomorphization) للكود باستخدام الـ generics في الـ compile time. الـ Monomorphization هي عملية تحويل الـ generic code إلى كود محدد عن طريق ملء الـ concrete types التي يتم استخدامها عند الـ compile. في هذه العملية، يقوم الـ compiler بعكس الخطوات التي استخدمناها لإنشاء الـ generic function في القائمة 10-5: ينظر الـ compiler إلى جميع الأماكن التي يتم فيها استدعاء الـ generic code ويولد كودًا لـ concrete types التي يتم استدعاء الـ generic code بها.

دعنا ننظر إلى كيفية عمل ذلك باستخدام الـ generic enum Option<T> الخاص بالـ standard library:

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

عندما تقوم Rust بـ compile هذا الكود، فإنها تجري monomorphization. خلال هذه العملية، يقرأ الـ compiler القيم التي تم استخدامها في مثيلات Option<T> ويحدد نوعين من Option<T>: أحدهما i32 والآخر f64. على هذا النحو، فإنه يوسع التعريف العام لـ Option<T> إلى تعريفين متخصصين لـ i32 و f64، وبالتالي يحل محل التعريف العام بالتعريفات المحددة.

يبدو الإصدار الذي تم عمل monomorphization له من الكود مشابهًا لما يلي (يستخدم الـ compiler أسماء مختلفة عما نستخدمه هنا للتوضيح):

enum Option_i32 {
    Some(i32),
    None,
}

enum Option_f64 {
    Some(f64),
    None,
}

fn main() {
    let integer = Option_i32::Some(5);
    let float = Option_f64::Some(5.0);
}

يتم استبدال الـ generic Option<T> بالتعريفات المحددة التي أنشأها الـ compiler. نظرًا لأن Rust تقوم بـ compile الـ generic code إلى كود يحدد النوع في كل مثيل، فإننا لا ندفع أي runtime cost لاستخدام الـ generics. عندما يتم تشغيل الكود، فإنه يعمل تمامًا كما لو كنا قد كررنا كل تعريف يدويًا. عملية الـ monomorphization تجعل الـ generics في Rust فعالة للغاية في الـ runtime.

تعريف السلوك المشترك باستخدام السمات (Traits)

تعريف السلوك المشترك باستخدام السمات (Defining Shared Behavior with Traits)

تحدد الـ سمة (trait) الوظائف التي يمتلكها نوع معين ويمكنه مشاركتها مع أنواع أخرى. يمكننا استخدام الـ traits لتعريف السلوك المشترك بطريقة مجردة (abstract). كما يمكننا استخدام قيود السمات (trait bounds) لتحديد أن النوع العام (generic type) يمكن أن يكون أي نوع يمتلك سلوكًا معينًا.

ملاحظة: الـ traits تشبه ميزة تسمى غالبًا الواجهات (interfaces) في لغات أخرى، وإن كان مع بعض الاختلافات.

تعريف سمة (Defining a Trait)

يتكون سلوك النوع من الدوال (methods) التي يمكننا استدعاؤها على ذلك النوع. تتشارك الأنواع المختلفة في نفس السلوك إذا كان بإمكاننا استدعاء نفس الـ methods على كل تلك الأنواع. تعريفات الـ Trait هي وسيلة لتجميع تواقيع الدوال (method signatures) معًا لتعريف مجموعة من السلوكيات الضرورية لتحقيق غرض ما.

على سبيل المثال، لنفترض أن لدينا عدة هياكل (structs) تحمل أنواعًا وكميات مختلفة من النصوص: هيكل NewsArticle يحمل قصة إخبارية مسجلة في موقع معين، وهيكل SocialPost يمكن أن يحتوي على 280 حرفًا كحد أقصى مع بيانات وصفية (metadata) تشير إلى ما إذا كان منشورًا جديدًا، أو إعادة نشر، أو ردًا على منشور آخر.

نريد إنشاء حزمة مكتبة (library crate) لمجمع وسائط تسمى aggregator يمكنها عرض ملخصات للبيانات التي قد تكون مخزنة في مثيل (instance) من NewsArticle أو SocialPost. للقيام بذلك، نحتاج إلى ملخص من كل نوع، وسنطلب ذلك الملخص عن طريق استدعاء دالة summarize على الـ instance. توضح القائمة 10-12 تعريف سمة Summary عامة (public) تعبر عن هذا السلوك.

pub trait Summary {
    fn summarize(&self) -> String;
}

هنا، نعلن عن trait باستخدام الكلمة المفتاحية trait ثم اسم الـ trait، وهو Summary في هذه الحالة. نعلن أيضًا عن الـ trait كـ pub بحيث يمكن للـ crates التي تعتمد على هذه الـ crate استخدام هذه الـ trait أيضًا، كما سنرى في بضعة أمثلة. داخل الأقواس المتعرجة، نعلن عن الـ method signatures التي تصف سلوكيات الأنواع التي تنفذ (implement) هذه الـ trait، وهي في هذه الحالة fn summarize(&self) -> String.

بعد الـ method signature، وبدلاً من توفير تنفيذ (implementation) داخل أقواس متعرجة، نستخدم فاصلة منقوطة. يجب على كل نوع ينفذ هذه الـ trait توفير سلوكه المخصص لجسم الـ method. سيفرض المترجم (compiler) أن أي نوع يمتلك الـ Summary trait سيكون لديه الـ method المسمى summarize معرفًا بهذا التوقيع (signature) تمامًا.

يمكن أن يحتوي الـ trait على عدة methods في جسمه: يتم إدراج الـ method signatures واحدًا تلو الآخر في كل سطر، وينتهي كل سطر بفاصلة منقوطة.

تنفيذ سمة على نوع (Implementing a Trait on a Type)

الآن بعد أن حددنا التواقيع المطلوبة لـ methods سمة Summary يمكننا تنفيذها على الأنواع في مجمع الوسائط الخاص بنا. توضح القائمة 10-13 تنفيذًا لـ Summary trait على هيكل NewsArticle يستخدم العنوان الرئيسي، والمؤلف، والموقع لإنشاء القيمة المعادة من summarize. بالنسبة لهيكل SocialPost نحدد summarize كاسم المستخدم متبوعًا بالنص الكامل للمنشور، بافتراض أن محتوى المنشور محدود بالفعل بـ 280 حرفًا.

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

تنفيذ trait على نوع يشبه تنفيذ الـ methods العادية. الفرق هو أنه بعد impl نضع اسم الـ trait الذي نريد تنفيذه، ثم نستخدم الكلمة المفتاحية for ثم نحدد اسم النوع الذي نريد تنفيذ الـ trait له. داخل كتلة impl نضع الـ method signatures التي حددها تعريف الـ trait. وبدلاً من إضافة فاصلة منقوطة بعد كل signature، نستخدم الأقواس المتعرجة ونملأ جسم الـ method بالسلوك المحدد الذي نريده لـ methods الـ trait لهذا النوع المعين.

الآن بعد أن نفذت المكتبة الـ Summary trait على NewsArticle و SocialPost يمكن لمستخدمي الـ crate استدعاء الـ trait methods على instances من NewsArticle و SocialPost بنفس الطريقة التي نستدعي بها الـ methods العادية. الفرق الوحيد هو أنه يجب على المستخدم إحضار الـ trait إلى النطاق (scope) بالإضافة إلى الأنواع. إليك مثال على كيفية استخدام binary crate لمكتبة aggregator الخاصة بنا:

use aggregator::{SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

يطبع هذا الكود 1 new post: horse_ebooks: of course, as you probably already know, people.

يمكن للـ crates الأخرى التي تعتمد على aggregator crate أيضًا إحضار الـ Summary trait إلى الـ scope لتنفيذ Summary على أنواعها الخاصة. أحد القيود التي يجب ملاحظتها هو أنه يمكننا تنفيذ trait على نوع فقط إذا كان الـ trait أو النوع، أو كلاهما، محليًا (local) للـ crate الخاصة بنا. على سبيل المثال، يمكننا تنفيذ traits المكتبة القياسية (standard library) مثل Display على نوع مخصص مثل SocialPost كجزء من وظائف aggregator crate لأن النوع SocialPost محلي لـ aggregator crate الخاصة بنا. يمكننا أيضًا تنفيذ Summary على Vec<T> في aggregator crate لأن الـ trait المسمى Summary محلي لـ aggregator crate الخاصة بنا.

لكن لا يمكننا تنفيذ traits خارجية على أنواع خارجية. على سبيل المثال، لا يمكننا تنفيذ الـ Display trait على Vec<T> داخل aggregator crate الخاصة بنا، لأن Display و Vec<T> كلاهما معرفان في المكتبة القياسية وليسا محليين لـ aggregator crate الخاصة بنا. هذا القيد هو جزء من خاصية تسمى التماسك (coherence)، وبشكل أكثر تحديدًا قاعدة اليتيم (orphan rule)، وسميت بهذا الاسم لأن النوع الأب غير موجود. تضمن هذه القاعدة أن كود الأشخاص الآخرين لا يمكنه كسر كودك والعكس صحيح. بدون هذه القاعدة، يمكن لـ crates اثنتين تنفيذ نفس الـ trait لنفس النوع، ولن يعرف Rust أي تنفيذ يستخدم.

استخدام التنفيذات الافتراضية (Using Default Implementations)

أحيانًا يكون من المفيد الحصول على سلوك افتراضي (default behavior) لبعض أو كل الـ methods في trait بدلاً من طلب تنفيذات لجميع الـ methods على كل نوع. بعد ذلك، عندما ننفذ الـ trait على نوع معين، يمكننا الاحتفاظ بالسلوك الافتراضي لكل method أو تجاوزه (override).

في القائمة 10-14، نحدد سلسلة نصية افتراضية لدالة summarize في سمة Summary بدلاً من الاكتفاء بتعريف الـ method signature، كما فعلنا في القائمة 10-12.

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

لاستخدام تنفيذ افتراضي لتلخيص instances من NewsArticle نحدد كتلة impl فارغة باستخدام impl Summary for NewsArticle {}.

على الرغم من أننا لم نعد نعرف دالة summarize على NewsArticle مباشرة، فقد قدمنا تنفيذًا افتراضيًا وحددنا أن NewsArticle ينفذ الـ Summary trait. ونتيجة لذلك، لا يزال بإمكاننا استدعاء دالة summarize على instance من NewsArticle بهذا الشكل:

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("New article available! {}", article.summarize());
}

يطبع هذا الكود New article available! (Read more...).

إنشاء تنفيذ افتراضي لا يتطلب منا تغيير أي شيء في تنفيذ Summary على SocialPost في القائمة 10-13. والسبب هو أن بناء الجملة (syntax) لتجاوز تنفيذ افتراضي هو نفسه الـ syntax لتنفيذ trait method ليس له تنفيذ افتراضي.

يمكن للتنفيذات الافتراضية استدعاء methods أخرى في نفس الـ trait، حتى لو لم يكن لتلك الـ methods الأخرى تنفيذ افتراضي. بهذه الطريقة، يمكن لـ trait توفير الكثير من الوظائف المفيدة وتتطلب فقط من المنفذين تحديد جزء صغير منها. على سبيل المثال، يمكننا تعريف الـ Summary trait ليكون له دالة summarize_author التي يكون تنفيذها مطلوبًا، ثم تعريف دالة summarize لها تنفيذ افتراضي يستدعي دالة summarize_author:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

لاستخدام هذه النسخة من Summary نحتاج فقط إلى تعريف summarize_author عندما ننفذ الـ trait على نوع ما:

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

بعد تعريف summarize_author يمكننا استدعاء summarize على instances من هيكل SocialPost وسيقوم التنفيذ الافتراضي لـ summarize باستدعاء تعريف summarize_author الذي قدمناه. نظرًا لأننا نفذنا summarize_author فقد منحتنا الـ Summary trait سلوك دالة summarize دون مطالبتنا بكتابة أي كود إضافي. إليك كيف يبدو ذلك:

use aggregator::{self, SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

يطبع هذا الكود 1 new post: (Read more from @horse_ebooks...).

لاحظ أنه ليس من الممكن استدعاء التنفيذ الافتراضي من تنفيذ متجاوز (overriding implementation) لنفس الـ method.

استخدام السمات كمعاملات (Using Traits as Parameters)

الآن بعد أن عرفت كيفية تعريف وتنفيذ الـ traits، يمكننا استكشاف كيفية استخدام الـ traits لتعريف دوال تقبل العديد من الأنواع المختلفة. سنستخدم الـ Summary trait الذي نفذناه على نوعي NewsArticle و SocialPost في القائمة 10-13 لتعريف دالة notify تستدعي دالة summarize على معاملها (parameter) المسمى item وهو من نوع ما ينفذ الـ Summary trait. للقيام بذلك، نستخدم الـ impl Trait syntax بهذا الشكل:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

بدلاً من نوع ملموس (concrete type) للمعامل item نحدد الكلمة المفتاحية impl واسم الـ trait. يقبل هذا الـ parameter أي نوع ينفذ الـ trait المحدد. في جسم notify يمكننا استدعاء أي methods على item تأتي من الـ Summary trait، مثل summarize. يمكننا استدعاء notify وتمرير أي instance من NewsArticle أو SocialPost. الكود الذي يستدعي الدالة مع أي نوع آخر، مثل String أو i32 لن يترجم، لأن تلك الأنواع لا تنفذ Summary.

بناء جملة قيد السمة (Trait Bound Syntax)

يعمل الـ impl Trait syntax في الحالات المباشرة ولكنه في الواقع عبارة عن اختصار برمجي (syntax sugar) لشكل أطول يعرف باسم قيد السمة (trait bound)؛ ويبدو هكذا:

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

هذا الشكل الأطول مكافئ للمثال في القسم السابق ولكنه أكثر تفصيلاً. نضع الـ trait bounds مع الإعلان عن معامل النوع العام (generic type parameter) بعد نقطتين وداخل أقواس زاوية.

يعتبر الـ trait bound syntax مناسبًا للحالات الأكثر تعقيدًا. على سبيل المثال، يمكن أن يكون لدينا معاملان ينفذان Summary. القيام بذلك باستخدام الـ impl Trait syntax يبدو هكذا:

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

استخدام impl Trait مناسب إذا أردنا أن تسمح هذه الدالة لـ item1 و item2 بأن يكون لهما نوعان مختلفان (طالما أن كلا النوعين ينفذان Summary). أما إذا أردنا إجبار كلا المعاملين على أن يكون لهما نفس النوع، فيجب علينا استخدام trait bound بهذا الشكل:

pub fn notify<T: Summary>(item1: &T, item2: &T) {

النوع العام T المحدد كنوع للمعاملين item1 و item2 يقيد الدالة بحيث يجب أن يكون النوع الملموس للقيمة الممررة كوسيط (argument) لـ item1 و item2 هو نفسه.

قيود سمات متعددة باستخدام الـ + Syntax (Multiple Trait Bounds with the + Syntax)

يمكننا أيضًا تحديد أكثر من trait bound واحد. لنفترض أننا أردنا أن تستخدم notify تنسيق العرض (display formatting) بالإضافة إلى summarize على item: نحدد في تعريف notify أن item يجب أن ينفذ كلاً من Display و Summary. يمكننا القيام بذلك باستخدام الـ + syntax:

pub fn notify(item: &(impl Summary + Display)) {

الـ + syntax صالح أيضًا مع الـ trait bounds على الأنواع العامة:

pub fn notify<T: Summary + Display>(item: &T) {

مع تحديد قيدي السمة، يمكن لجسم notify استدعاء summarize واستخدام {} لتنسيق item.

قيود سمات أكثر وضوحًا باستخدام بنود where (Clearer Trait Bounds with where Clauses)

استخدام الكثير من الـ trait bounds له سلبياته. فكل نوع عام له الـ trait bounds الخاصة به، لذا فإن الدوال التي تحتوي على عدة معاملات أنواع عامة يمكن أن تحتوي على الكثير من معلومات الـ trait bound بين اسم الدالة وقائمة معاملاتها، مما يجعل توقيع الدالة (function signature) صعب القراءة. لهذا السبب، يمتلك Rust بناء جملة بديلاً لتحديد الـ trait bounds داخل بند where بعد function signature. لذا، بدلاً من كتابة هذا:

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

يمكننا استخدام بند where بهذا الشكل:

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

توقيع هذه الدالة أقل فوضى: اسم الدالة، وقائمة المعاملات، ونوع الإرجاع قريبة من بعضها البعض، بشكل مشابه لدالة لا تحتوي على الكثير من الـ trait bounds.

إرجاع الأنواع التي تنفذ السمات (Returning Types That Implement Traits)

يمكننا أيضًا استخدام الـ impl Trait syntax في موضع الإرجاع لإعادة قيمة من نوع ما ينفذ trait، كما هو موضح هنا:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    }
}

باستخدام impl Summary لنوع الإرجاع، نحدد أن دالة returns_summarizable تعيد نوعًا ما ينفذ الـ Summary trait دون تسمية النوع الملموس. في هذه الحالة، تعيد returns_summarizable هيكل SocialPost ولكن الكود الذي يستدعي هذه الدالة لا يحتاج إلى معرفة ذلك.

القدرة على تحديد نوع الإرجاع فقط من خلال الـ trait الذي ينفذه مفيدة بشكل خاص في سياق الـ closures والـ iterators، والتي نغطيها في الفصل 13. تنشئ الـ closures والـ iterators أنواعًا لا يعرفها إلا المترجم أو أنواعًا طويلة جدًا في تحديدها. يتيح لك الـ impl Trait syntax تحديد أن الدالة تعيد نوعًا ما ينفذ الـ Iterator trait بإيجاز دون الحاجة إلى كتابة نوع طويل جدًا.

ومع ذلك، يمكنك فقط استخدام impl Trait إذا كنت تعيد نوعًا واحدًا فقط. على سبيل المثال، هذا الكود الذي يعيد إما NewsArticle أو SocialPost مع تحديد نوع الإرجاع كـ impl Summary لن يعمل:

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "Penguins win the Stanley Cup Championship!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "The Pittsburgh Penguins once again are the best \
                 hockey team in the NHL.",
            ),
        }
    } else {
        SocialPost {
            username: String::from("horse_ebooks"),
            content: String::from(
                "of course, as you probably already know, people",
            ),
            reply: false,
            repost: false,
        }
    }
}

إرجاع إما NewsArticle أو SocialPost غير مسموح به بسبب قيود حول كيفية تنفيذ الـ impl Trait syntax في المترجم. سنغطي كيفية كتابة دالة بهذا السلوك في قسم “استخدام كائنات السمات للتجريد فوق السلوك المشترك” من الفصل 18.

استخدام قيود السمات لتنفيذ الدوال بشكل مشروط (Using Trait Bounds to Conditionally Implement Methods)

باستخدام trait bound مع كتلة impl تستخدم معاملات أنواع عامة، يمكننا تنفيذ الـ methods بشكل مشروط للأنواع التي تنفذ الـ traits المحددة. على سبيل المثال، النوع Pair<T> في القائمة 10-15 ينفذ دائمًا دالة new لإعادة instance جديد من Pair<T> (تذكر من قسم “بناء جملة الدالة” في الفصل 5 أن Self هو اسم مستعار لنوع كتلة impl وهو في هذه الحالة Pair<T>). ولكن في كتلة impl التالية، ينفذ Pair<T> دالة cmp_display فقط إذا كان نوعه الداخلي T ينفذ الـ PartialOrd trait الذي يتيح المقارنة و الـ Display trait الذي يتيح الطباعة.

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

يمكننا أيضًا تنفيذ trait بشكل مشروط لأي نوع ينفذ trait آخر. تسمى تنفيذات trait على أي نوع يستوفي الـ trait bounds بـ التنفيذات الشاملة (blanket implementations) وتستخدم على نطاق واسع في مكتبة Rust القياسية. على سبيل المثال، تنفذ المكتبة القياسية الـ ToString trait على أي نوع ينفذ الـ Display trait. تبدو كتلة impl في المكتبة القياسية مشابهة لهذا الكود:

impl<T: Display> ToString for T {
    // --snip--
}

نظرًا لأن المكتبة القياسية تمتلك هذا الـ blanket implementation، يمكننا استدعاء دالة to_string المعرفة بواسطة الـ ToString trait على أي نوع ينفذ الـ Display trait. على سبيل المثال، يمكننا تحويل الأعداد الصحيحة (integers) إلى قيم String المقابلة لها بهذا الشكل لأن الأعداد الصحيحة تنفذ Display:

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

تظهر الـ blanket implementations في التوثيق الخاص بالـ trait في قسم “المنفذون” (Implementors).

تتيح لنا الـ traits والـ trait bounds كتابة كود يستخدم معاملات أنواع عامة لتقليل التكرار ولكنها تحدد أيضًا للمترجم أننا نريد أن يمتلك النوع العام سلوكًا معينًا. يمكن للمترجم بعد ذلك استخدام معلومات الـ trait bound للتحقق من أن جميع الأنواع الملموسة المستخدمة مع كودنا توفر السلوك الصحيح. في اللغات ذات الأنواع الديناميكية (dynamically typed languages)، سنحصل على خطأ في وقت التشغيل (runtime) إذا استدعينا دالة على نوع لم يحدد تلك الدالة. لكن Rust ينقل هذه الأخطاء إلى وقت الترجمة (compile time) بحيث نضطر إلى إصلاح المشكلات قبل أن يتمكن كودنا من العمل. بالإضافة إلى ذلك، لا يتعين علينا كتابة كود يتحقق من السلوك في وقت التشغيل، لأننا تحققنا بالفعل في وقت الترجمة. القيام بذلك يحسن الأداء دون الحاجة إلى التخلي عن مرونة الأنواع العامة (generics).

التحقق من المراجع باستخدام الأعمار (Lifetimes)

التحقق من صحة المراجع باستخدام فترات الحياة (Lifetimes)

تعد فترات الحياة (Lifetimes) نوعاً آخر من الأنواع العامة (Generics) التي كنا نستخدمها بالفعل. بدلاً من التأكد من أن النوع يمتلك السلوك الذي نريده، تضمن الـ Lifetimes أن المراجع (References) تظل صالحة طالما احتجنا إليها.

أحد التفاصيل التي لم نناقشها في قسم “المراجع والاستعارة” في الفصل الرابع هو أن كل Reference في Rust له Lifetime، وهو النطاق (Scope) الذي يكون فيه هذا المرجع صالحاً. في معظم الأوقات، تكون الـ Lifetimes ضمنية ومستنتجة، تماماً كما يتم استنتاج الأنواع في معظم الأوقات. نحن مطالبون فقط بتوضيح (Annotate) الأنواع عندما يكون هناك عدة أنواع ممكنة. وبطريقة مماثلة، يجب علينا توضيح الـ Lifetimes عندما يمكن أن ترتبط فترات حياة المراجع ببعضها البعض بعدة طرق مختلفة. تتطلب Rust منا توضيح هذه العلاقات باستخدام معاملات فترات الحياة العامة (Generic Lifetime Parameters) لضمان أن المراجع الفعلية المستخدمة في وقت التشغيل ستكون صالحة بالتأكيد.

إن توضيح الـ Lifetimes ليس مفهوماً موجوداً في معظم لغات البرمجة الأخرى، لذا سيبدو هذا الأمر غير مألوف. على الرغم من أننا لن نغطي فترات الحياة بالكامل في هذا الفصل، إلا أننا سنناقش الطرق الشائعة التي قد تواجه فيها صيغة فترات الحياة (Lifetime Syntax) حتى تتمكن من التعود على هذا المفهوم.

المراجع المعلقة (Dangling References)

الهدف الرئيسي من الـ Lifetimes هو منع المراجع المعلقة (Dangling References)، والتي إذا سُمح بوجودها، فستتسبب في إشارة البرنامج إلى بيانات غير البيانات المقصود الإشارة إليها. فكر في البرنامج الموجود في القائمة 10-16، والذي يحتوي على نطاق خارجي (Outer Scope) ونطاق داخلي (Inner Scope).

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {r}");
}

ملاحظة: تعلن الأمثلة في القوائم 10-16 و10-17 و10-23 عن متغيرات دون إعطائها قيمة أولية، لذا فإن اسم المتغير موجود في الـ Outer Scope. للوهلة الأولى، قد يبدو هذا متعارضاً مع عدم وجود قيم فارغة (Null) في Rust. ومع ذلك، إذا حاولنا استخدام متغير قبل إعطائه قيمة، فسنحصل على خطأ في وقت التجميع (Compile-time Error)، مما يوضح أن Rust بالفعل لا تسمح بالقيم الـ Null.

يعلن الـ Outer Scope عن متغير باسم r بدون قيمة أولية، ويعلن الـ Inner Scope عن متغير باسم x بقيمة أولية قدرها 5. داخل الـ Inner Scope، نحاول تعيين قيمة r كمرجع لـ x. ثم ينتهي الـ Inner Scope، ونحاول طباعة القيمة الموجودة في r. لن يتم تجميع هذا الكود، لأن القيمة التي يشير إليها r قد خرجت عن الـ Scope قبل أن نحاول استخدامها. إليك رسالة الخطأ:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
5 |         let x = 5;
  |             - binding `x` declared here
6 |         r = &x;
  |             ^^ borrowed value does not live long enough
7 |     }
  |     - `x` dropped here while still borrowed
8 |
9 |     println!("r: {r}");
  |                   - borrow later used here

For more information about this error, try `rustc --explain E0597`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

تقول رسالة الخطأ أن المتغير x “لا يعيش لفترة كافية”. والسبب هو أن x سيخرج عن الـ Scope عندما ينتهي الـ Inner Scope في السطر 7. لكن r لا يزال صالحاً للـ Outer Scope؛ ولأن نطاقه أكبر، نقول إنه “يعيش لفترة أطول”. إذا سمحت Rust لهذا الكود بالعمل، فسيشير r إلى ذاكرة تم إلغاء تخصيصها عندما خرج x عن الـ Scope، وأي شيء نحاول القيام به باستخدام r لن يعمل بشكل صحيح. إذاً، كيف تحدد Rust أن هذا الكود غير صالح؟ إنها تستخدم مدقق الاستعارة (Borrow Checker).

مدقق الاستعارة (Borrow Checker)

يحتوي مترجم Rust على مدقق استعارة (Borrow Checker) يقارن النطاقات لتحديد ما إذا كانت جميع الاستعارات (Borrows) صالحة. توضح القائمة 10-17 نفس الكود الموجود في القائمة 10-16 ولكن مع توضيحات تظهر الـ Lifetimes للمتغيرات.

fn main() {
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {r}");   //          |
}                         // ---------+

هنا، قمنا بتوضيح الـ Lifetime لـ r بـ 'a والـ Lifetime لـ x بـ 'b. كما ترون، فإن كتلة 'b الداخلية أصغر بكثير من كتلة الـ Lifetime 'a الخارجية. في وقت التجميع، تقارن Rust حجم فترتي الحياة وترى أن r له Lifetime قدره 'a ولكنه يشير إلى ذاكرة بـ Lifetime قدره 'b. يتم رفض البرنامج لأن 'b أقصر من 'a: فصاحب المرجع لا يعيش طويلاً مثل المرجع نفسه.

تقوم القائمة 10-18 بإصلاح الكود بحيث لا يحتوي على Dangling Reference ويتم تجميعه دون أي أخطاء.

fn main() {
    let x = 5;            // ----------+-- 'b
                          //           |
    let r = &x;           // --+-- 'a  |
                          //   |       |
    println!("r: {r}");   //   |       |
                          // --+       |
}                         // ----------+

هنا، يمتلك x الـ Lifetime 'b والتي في هذه الحالة أكبر من 'a. هذا يعني أن r يمكنه الإشارة إلى x لأن Rust تعلم أن المرجع في r سيكون دائماً صالحاً طالما أن x صالح.

الآن بعد أن عرفت أين توجد الـ Lifetimes للمراجع وكيف تحلل Rust فترات الحياة لضمان أن المراجع ستكون دائماً صالحة، دعنا نستكشف الـ Generic Lifetimes في معاملات الدوال والقيم المرتجعة.

فترات الحياة العامة في الدوال (Generic Lifetimes in Functions)

سنكتب دالة تعيد السلسلة الأطول من بين شريحتين نصيتين (String Slices). ستأخذ هذه الدالة شريحتين نصيتين وتعيد شريحة نصية واحدة. بعد تنفيذ دالة longest يجب أن يطبع الكود في القائمة 10-19 عبارة The longest string is abcd.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

لاحظ أننا نريد أن تأخذ الدالة String Slices، وهي مراجع، بدلاً من سلاسل نصية (Strings)، لأننا لا نريد لدالة longest أن تأخذ ملكية (Ownership) معاملاتها. ارجع إلى قسم “شرائح النصوص كمعاملات” في الفصل الرابع لمزيد من النقاش حول سبب كون المعاملات التي نستخدمها في القائمة 10-19 هي التي نريدها.

إذا حاولنا تنفيذ دالة longest كما هو موضح في القائمة 10-20، فلن يتم تجميعها.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() { x } else { y }
}

بدلاً من ذلك، نحصل على خطأ يتحدث عن الـ Lifetimes:

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0106]: missing lifetime specifier
 --> src/main.rs:9:33
  |
9 | fn longest(x: &str, y: &str) -> &str {
  |               ----     ----     ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y`
help: consider introducing a named lifetime parameter
  |
9 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
  |           ++++     ++          ++          ++

For more information about this error, try `rustc --explain E0106`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

يكشف نص المساعدة أن النوع المرتجع يحتاج إلى Generic Lifetime Parameter عليه لأن Rust لا تستطيع تحديد ما إذا كان المرجع الذي يتم إرجاعه يشير إلى x أو y. في الواقع، نحن لا نعرف ذلك أيضاً، لأن كتلة if في جسم هذه الدالة تعيد مرجعاً لـ x وكتلة else تعيد مرجعاً لـ y!

عندما نقوم بتعريف هذه الدالة، فإننا لا نعرف القيم الملموسة (Concrete Values) التي سيتم تمريرها إليها، لذا لا نعرف ما إذا كانت حالة if أو حالة else هي التي ستنفذ. كما أننا لا نعرف الـ Concrete Lifetimes للمراجع التي سيتم تمريرها، لذا لا يمكننا النظر في النطاقات كما فعلنا في القوائم 10-17 و10-18 لتحديد ما إذا كان المرجع الذي نعيده سيكون دائماً صالحاً. لا يمكن للـ Borrow Checker تحديد ذلك أيضاً، لأنه لا يعرف كيف ترتبط فترات حياة x و y بـ Lifetime القيمة المرتجعة. لإصلاح هذا الخطأ، سنضيف Generic Lifetime Parameters تحدد العلاقة بين المراجع حتى يتمكن الـ Borrow Checker من إجراء تحليله.

صيغة توضيح فترة الحياة (Lifetime Annotation Syntax)

لا تغير توضيحات فترة الحياة (Lifetime Annotations) مدة بقاء أي من المراجع. بدلاً من ذلك، فهي تصف علاقات فترات حياة مراجع متعددة ببعضها البعض دون التأثير على فترات الحياة. تماماً كما يمكن للدوال قبول أي نوع عندما يحدد التوقيع (Signature) معامل نوع عام، يمكن للدوال قبول مراجع بأي Lifetime من خلال تحديد Generic Lifetime Parameter.

تمتلك الـ Lifetime Annotations صيغة غير معتادة قليلاً: يجب أن تبدأ أسماء معاملات فترة الحياة بفاصلة عليا (') وعادة ما تكون كلها أحرفاً صغيرة وقصيرة جداً، مثل الأنواع العامة. يستخدم معظم الناس الاسم 'a لأول Lifetime Annotation. نضع توضيحات معاملات فترة الحياة بعد علامة & للمرجع، مع استخدام مسافة لفصل التوضيح عن نوع المرجع.

إليك بعض الأمثلة: مرجع لـ i32 بدون معامل فترة حياة، ومرجع لـ i32 له معامل فترة حياة باسم 'a ومرجع قابل للتغيير (Mutable Reference) لـ i32 له أيضاً فترة الحياة 'a:

&i32        // مرجع
&'a i32     // مرجع مع فترة حياة صريحة
&'a mut i32 // مرجع قابل للتغيير مع فترة حياة صريحة

توضيح فترة حياة واحد بمفرده ليس له معنى كبير، لأن التوضيحات تهدف إلى إخبار Rust بكيفية ارتباط الـ Generic Lifetime Parameters لمراجع متعددة ببعضها البعض. دعنا نفحص كيف ترتبط الـ Lifetime Annotations ببعضها البعض في سياق دالة longest.

في تواقيع الدوال (Function Signatures)

لاستخدام الـ Lifetime Annotations في تواقيع الدوال، نحتاج إلى الإعلان عن الـ Generic Lifetime Parameters داخل أقواس زاوية بين اسم الدالة وقائمة المعاملات، تماماً كما فعلنا مع معاملات الأنواع العامة.

نريد أن يعبر الـ Signature عن القيد التالي: المرجع المرتجع سيكون صالحاً طالما أن كلا المعاملين صالحان. هذه هي العلاقة بين فترات حياة المعاملات والقيمة المرتجعة. سنسمي فترة الحياة 'a ثم نضيفها إلى كل مرجع، كما هو موضح في القائمة 10-21.

fn main() {
    let string1 = String::from("abcd");
    let string2 = "xyz";

    let result = longest(string1.as_str(), string2);
    println!("The longest string is {result}");
}

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

يجب أن يتم تجميع هذا الكود وينتج النتيجة التي نريدها عندما نستخدمه مع دالة main في القائمة 10-19.

يخبر الـ Signature الآن Rust أنه لـ Lifetime ما 'a تأخذ الدالة معاملين، كلاهما String Slices يعيشان على الأقل طالما تعيش فترة الحياة 'a. يخبر الـ Signature أيضاً Rust أن الـ String Slice المرتجع من الدالة سيعيش على الأقل طالما تعيش فترة الحياة 'a. من الناحية العملية، هذا يعني أن فترة حياة المرجع الذي تعيده الدالة… (تم اختصار المحتوى بسبب حدود الحجم)

…

fn first_word<'a>(s: &'a str) -> &'a str {

الآن تمتلك جميع المراجع في الـ Signature فترات حياة، ويمكن للمترجم مواصلة تحليله دون حاجة المبرمج لتوضيح فترات الحياة في هذا الـ Signature.

دعنا ننظر في مثال آخر، هذه المرة باستخدام دالة longest التي لم تكن تحتوي على معاملات فترة حياة عندما بدأنا العمل عليها في القائمة 10-20:

fn longest(x: &str, y: &str) -> &str {

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

fn longest<'a, 'b>(x: &'a str, y: &'b str) -> &str {

يمكنك أن ترى أن القاعدة الثانية لا تنطبق، لأن هناك أكثر من فترة حياة مدخلة واحدة. القاعدة الثالثة لا تنطبق أيضاً، لأن longest هي دالة وليست دالة مرتبطة (Method)، لذا لا يوجد أي من المعاملات هو self. بعد المرور بجميع القواعد الثلاث، ما زلنا لم نكتشف ما هي فترة حياة النوع المرتجع. لهذا السبب حصلنا على خطأ عند محاولة تجميع الكود في القائمة 10-20: لقد مر المترجم عبر قواعد حذف فترة الحياة (Lifetime Elision Rules) ولكنه لم يتمكن بعد من اكتشاف جميع فترات حياة المراجع في الـ Signature.

ولأن القاعدة الثالثة تنطبق حقاً فقط في تواقيع الدوال المرتبطة (Method Signatures)، فسننظر في فترات الحياة في ذلك السياق تالياً لنرى لماذا تعني القاعدة الثالثة أننا لا نضطر لتوضيح فترات الحياة في الـ Method Signatures في كثير من الأحيان.

في تعريفات الدوال المرتبطة (Method Definitions)

عندما نقوم بتنفيذ Methods على هيكل (Struct) يحتوي على فترات حياة، نستخدم نفس الصيغة المستخدمة لمعاملات الأنواع العامة، كما هو موضح في القائمة 10-11. يعتمد مكان الإعلان عن معاملات فترات الحياة واستخدامها على ما إذا كانت مرتبطة بحقول الهيكل أو بمعاملات الـ Method والقيم المرتجعة.

يجب دائماً الإعلان عن أسماء فترات الحياة لحقول الهيكل بعد الكلمة المفتاحية impl ثم استخدامها بعد اسم الهيكل لأن فترات الحياة هذه جزء من نوع الهيكل.

في الـ Method Signatures داخل كتلة impl قد تكون المراجع مرتبطة بفترة حياة المراجع في حقول الهيكل، أو قد تكون مستقلة. بالإضافة إلى ذلك، غالباً ما تجعل الـ Lifetime Elision Rules توضيحات فترة الحياة غير ضرورية في الـ Method Signatures. دعنا ننظر في بعض الأمثلة باستخدام الهيكل المسمى ImportantExcerpt الذي عرفناه في القائمة 10-24.

أولاً، سنستخدم Method تسمى level معاملها الوحيد هو مرجع لـ self وقيمتها المرتجعة هي i32 وهو ليس مرجعاً لأي شيء:

struct ImportantExcerpt<'a> {
    part: &'a str,
}

impl<'a> ImportantExcerpt<'a> {
    fn level(&self) -> i32 {
        3
    }
}

impl<'a> ImportantExcerpt<'a> {
    fn announce_and_return_part(&self, announcement: &str) -> &str {
        println!("Attention please: {announcement}");
        self.part
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let first_sentence = novel.split('.').next().unwrap();
    let i = ImportantExcerpt {
        part: first_sentence,
    };
}

الإعلان عن معامل فترة الحياة بعد impl واستخدامه بعد اسم النوع مطلوبان، ولكن بسبب قاعدة الحذف الأولى، لسنا مطالبين بتوضيح فترة حياة المرجع لـ self.

إليك مثال تنطبق فيه الـ Lifetime Elision Rule الثالثة:

struct ImportantExcerpt<'a> {
    part: &'a str,
}

impl<'a> ImportantExcerpt<'a> {
    fn level(&self) -> i32 {
        3
    }
}

impl<'a> ImportantExcerpt<'a> {
    fn announce_and_return_part(&self, announcement: &str) -> &str {
        println!("Attention please: {announcement}");
        self.part
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let first_sentence = novel.split('.').next().unwrap();
    let i = ImportantExcerpt {
        part: first_sentence,
    };
}