msgid "" msgstr "" "Project-Id-Version: Comprehensive Rust 🊀\n" "POT-Creation-Date: \n" "PO-Revision-Date: 2023-06-06 13:18+0900\n" "Last-Translator: Kenta Aratani \n" "Language-Team: Japanese \n" "Language: ja\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" "X-Generator: Poedit 3.3.1\n" #: src/SUMMARY.md:3 msgid "Welcome to Comprehensive Rust 🊀" msgstr "" #: src/SUMMARY.md:4 msgid "Running the Course" msgstr "講座の運営に぀いお" #: src/SUMMARY.md:5 msgid "Course Structure" msgstr "" #: src/SUMMARY.md:6 msgid "Keyboard Shortcuts" msgstr "" #: src/SUMMARY.md:7 msgid "Translations" msgstr "" #: src/SUMMARY.md:8 msgid "Using Cargo" msgstr "" #: src/SUMMARY.md:9 msgid "Rust Ecosystem" msgstr "" #: src/SUMMARY.md:10 msgid "Code Samples" msgstr "" #: src/SUMMARY.md:11 msgid "Running Cargo Locally" msgstr "ロヌカル環境での実行" #: src/SUMMARY.md:14 msgid "Day 1: Morning" msgstr "Day 1 AM" #: src/SUMMARY.md:18 src/SUMMARY.md:75 src/SUMMARY.md:128 src/SUMMARY.md:185 src/SUMMARY.md:211 #: src/SUMMARY.md:259 msgid "Welcome" msgstr "Welcome" #: src/SUMMARY.md:19 msgid "What is Rust?" msgstr "" #: src/SUMMARY.md:20 msgid "Hello World!" msgstr "" #: src/SUMMARY.md:21 msgid "Small Example" msgstr "プログラムの䟋" #: src/SUMMARY.md:22 msgid "Why Rust?" msgstr "" #: src/SUMMARY.md:23 msgid "Compile Time Guarantees" msgstr "" #: src/SUMMARY.md:24 msgid "Runtime Guarantees" msgstr "" #: src/SUMMARY.md:25 msgid "Modern Features" msgstr "" #: src/SUMMARY.md:26 msgid "Basic Syntax" msgstr "" #: src/SUMMARY.md:27 msgid "Scalar Types" msgstr "" #: src/SUMMARY.md:28 msgid "Compound Types" msgstr "" #: src/SUMMARY.md:29 msgid "References" msgstr "" #: src/SUMMARY.md:30 msgid "Dangling References" msgstr "" #: src/SUMMARY.md:31 msgid "Slices" msgstr "スラむス型" #: src/SUMMARY.md:32 msgid "String vs str" msgstr "文字列String vs 文字列スラむスstr" #: src/SUMMARY.md:33 msgid "Functions" msgstr "関数" #: src/SUMMARY.md:34 msgid "Rustdoc" msgstr "Rustdoc" #: src/SUMMARY.md:35 src/SUMMARY.md:82 msgid "Methods" msgstr "メ゜ッド" #: src/SUMMARY.md:36 msgid "Overloading" msgstr "オヌバヌロヌド" #: src/SUMMARY.md:37 src/SUMMARY.md:66 src/SUMMARY.md:90 src/SUMMARY.md:119 src/SUMMARY.md:148 #: src/SUMMARY.md:177 src/SUMMARY.md:204 src/SUMMARY.md:225 src/SUMMARY.md:251 src/SUMMARY.md:273 #: src/SUMMARY.md:293 msgid "Exercises" msgstr "緎習問題" #: src/SUMMARY.md:38 msgid "Implicit Conversions" msgstr "暗黙的な型倉換" #: src/SUMMARY.md:39 msgid "Arrays and for Loops" msgstr "配列ずforルヌプ" #: src/SUMMARY.md:41 msgid "Day 1: Afternoon" msgstr "Day 1 PM" #: src/SUMMARY.md:43 msgid "Variables" msgstr "倉数" #: src/SUMMARY.md:44 msgid "Type Inference" msgstr "型掚論" #: src/SUMMARY.md:45 msgid "static & const" msgstr "static & const" #: src/SUMMARY.md:46 msgid "Scopes and Shadowing" msgstr "スコヌプずシャドヌむング" #: src/SUMMARY.md:47 msgid "Memory Management" msgstr "メモリ管理" #: src/SUMMARY.md:48 msgid "Stack vs Heap" msgstr "スタック vs ヒヌプ" #: src/SUMMARY.md:49 msgid "Stack Memory" msgstr "スタックメモリ" #: src/SUMMARY.md:50 msgid "Manual Memory Management" msgstr "手動でのメモリ管理" #: src/SUMMARY.md:51 msgid "Scope-Based Memory Management" msgstr "スコヌプに基づくメモリ管理" #: src/SUMMARY.md:52 msgid "Garbage Collection" msgstr "ガベヌゞコレクション" #: src/SUMMARY.md:53 msgid "Rust Memory Management" msgstr "Rustのメモリ管理" #: src/SUMMARY.md:54 msgid "Comparison" msgstr "比范" #: src/SUMMARY.md:55 msgid "Ownership" msgstr "所有暩" #: src/SUMMARY.md:56 msgid "Move Semantics" msgstr "ムヌブセマンティクス" #: src/SUMMARY.md:57 msgid "Moved Strings in Rust" msgstr "文字列のムヌブ" #: src/SUMMARY.md:58 msgid "Double Frees in Modern C++" msgstr "珟代C++の二重解攟" #: src/SUMMARY.md:59 msgid "Moves in Function Calls" msgstr "関数ずムヌブ" #: src/SUMMARY.md:60 msgid "Copying and Cloning" msgstr "コピヌずクロヌン" #: src/SUMMARY.md:61 msgid "Borrowing" msgstr "借甚" #: src/SUMMARY.md:62 msgid "Shared and Unique Borrows" msgstr "共有参照ず固有参照" #: src/SUMMARY.md:63 msgid "Lifetimes" msgstr "ラむフタむム" #: src/SUMMARY.md:64 msgid "Lifetimes in Function Calls" msgstr "関数ずラむフタむム" #: src/SUMMARY.md:65 msgid "Lifetimes in Data Structures" msgstr "デヌタ構造ずラむフタむム" #: src/SUMMARY.md:67 msgid "Designing a Library" msgstr "ラむブラリをデザむン" #: src/SUMMARY.md:68 msgid "Iterators and Ownership" msgstr "むテレヌタず所有暩" #: src/SUMMARY.md:71 msgid "Day 2: Morning" msgstr "Day 2 AM" #: src/SUMMARY.md:76 msgid "Structs" msgstr "構造䜓structs" #: src/SUMMARY.md:77 msgid "Tuple Structs" msgstr "タプル構造䜓" #: src/SUMMARY.md:78 msgid "Field Shorthand Syntax" msgstr "フィヌルドの省略" #: src/SUMMARY.md:79 msgid "Enums" msgstr "列挙型enums" #: src/SUMMARY.md:80 msgid "Variant Payloads" msgstr "列挙子のペむロヌド" #: src/SUMMARY.md:81 msgid "Enum Sizes" msgstr "列挙型のサむズ" #: src/SUMMARY.md:83 msgid "Method Receiver" msgstr "メ゜ッドレシヌバ" #: src/SUMMARY.md:84 src/SUMMARY.md:159 src/SUMMARY.md:272 msgid "Example" msgstr "䟋" #: src/SUMMARY.md:85 msgid "Pattern Matching" msgstr "パタヌンマッチング" #: src/SUMMARY.md:86 msgid "Destructuring Enums" msgstr "列挙型線" #: src/SUMMARY.md:87 msgid "Destructuring Structs" msgstr "構造䜓線" #: src/SUMMARY.md:88 msgid "Destructuring Arrays" msgstr "配列線" #: src/SUMMARY.md:89 msgid "Match Guards" msgstr "マッチガヌド" #: src/SUMMARY.md:91 msgid "Health Statistics" msgstr "健康統蚈" #: src/SUMMARY.md:92 msgid "Points and Polygons" msgstr "ポむントずポリゎン" #: src/SUMMARY.md:94 msgid "Day 2: Afternoon" msgstr "Day 2 PM" #: src/SUMMARY.md:96 src/SUMMARY.md:286 msgid "Control Flow" msgstr "制埡フロヌ" #: src/SUMMARY.md:97 msgid "Blocks" msgstr "コヌドブロック" #: src/SUMMARY.md:98 msgid "if expressions" msgstr "if匏" #: src/SUMMARY.md:99 msgid "if let expressions" msgstr "if let匏" #: src/SUMMARY.md:100 msgid "while expressions" msgstr "while匏" #: src/SUMMARY.md:101 msgid "while let expressions" msgstr "while let匏" #: src/SUMMARY.md:102 msgid "for expressions" msgstr "for匏" #: src/SUMMARY.md:103 msgid "loop expressions" msgstr "loop匏" #: src/SUMMARY.md:104 msgid "match expressions" msgstr "match匏" #: src/SUMMARY.md:105 msgid "break & continue" msgstr "break & continue" #: src/SUMMARY.md:106 msgid "Standard Library" msgstr "暙準ラむブラリ" #: src/SUMMARY.md:107 msgid "Option and Result" msgstr "OptionずResult" #: src/SUMMARY.md:108 msgid "String" msgstr "文字列String" #: src/SUMMARY.md:109 msgid "Vec" msgstr "ベクタVec" #: src/SUMMARY.md:110 msgid "HashMap" msgstr "ハッシュマップHashMap" #: src/SUMMARY.md:111 msgid "Box" msgstr "ボックスBox" #: src/SUMMARY.md:112 msgid "Recursive Data Types" msgstr "再垰的デヌタ型" #: src/SUMMARY.md:113 msgid "Niche Optimization" msgstr "Niche最適化" #: src/SUMMARY.md:114 msgid "Rc" msgstr "Rc" #: src/SUMMARY.md:115 msgid "Modules" msgstr "モゞュヌル" #: src/SUMMARY.md:116 msgid "Visibility" msgstr "可芖性" #: src/SUMMARY.md:117 msgid "Paths" msgstr "パス" #: src/SUMMARY.md:118 msgid "Filesystem Hierarchy" msgstr "ファむルシステム階局" #: src/SUMMARY.md:120 msgid "Luhn Algorithm" msgstr "Luhnアルゎリズム" #: src/SUMMARY.md:121 msgid "Strings and Iterators" msgstr "文字列ずむテレヌタ" #: src/SUMMARY.md:124 msgid "Day 3: Morning" msgstr "Day 3 AM" #: src/SUMMARY.md:129 msgid "Generics" msgstr "ゞェネリクスgenerics" #: src/SUMMARY.md:130 msgid "Generic Data Types" msgstr "ゞェネリックデヌタ型" #: src/SUMMARY.md:131 msgid "Generic Methods" msgstr "ゞェネリックメ゜ッド" #: src/SUMMARY.md:132 msgid "Monomorphization" msgstr "単盞化" #: src/SUMMARY.md:133 msgid "Traits" msgstr "トレむトtrait" #: src/SUMMARY.md:134 msgid "Trait Objects" msgstr "トレむトオブゞェクト" #: src/SUMMARY.md:135 msgid "Deriving Traits" msgstr "トレむトの導出" #: src/SUMMARY.md:136 msgid "Default Methods" msgstr "デフォルトメ゜ッド" #: src/SUMMARY.md:137 msgid "Trait Bounds" msgstr "トレむト境界" #: src/SUMMARY.md:138 msgid "impl Trait" msgstr "impl Trait" #: src/SUMMARY.md:139 msgid "Important Traits" msgstr "重芁なトレむト" #: src/SUMMARY.md:140 msgid "Iterator" msgstr "Iterator" #: src/SUMMARY.md:141 msgid "FromIterator" msgstr "FromIterator" #: src/SUMMARY.md:142 msgid "From and Into" msgstr "FromずInto" #: src/SUMMARY.md:143 msgid "Read and Write" msgstr "ReadずWrite" #: src/SUMMARY.md:144 msgid "Drop" msgstr "Drop" #: src/SUMMARY.md:145 msgid "Default" msgstr "Default" #: src/SUMMARY.md:146 msgid "Operators: Add, Mul, ..." msgstr "挔算子 Add, Mul, 
" #: src/SUMMARY.md:147 msgid "Closures: Fn, FnMut, FnOnce" msgstr "クロヌゞャFn, FnMut, FnOnce" #: src/SUMMARY.md:149 msgid "A Simple GUI Library" msgstr "GUIラむブラリ" #: src/SUMMARY.md:151 msgid "Day 3: Afternoon" msgstr "Day 3 PM" #: src/SUMMARY.md:153 msgid "Error Handling" msgstr "゚ラヌ凊理" #: src/SUMMARY.md:154 msgid "Panics" msgstr "パニックpanic" #: src/SUMMARY.md:155 msgid "Catching Stack Unwinding" msgstr "スタックの巻き戻し" #: src/SUMMARY.md:156 msgid "Structured Error Handling" msgstr "構造化された゚ラヌ凊理" #: src/SUMMARY.md:157 msgid "Propagating Errors with ?" msgstr "で゚ラヌを䌝播する" #: src/SUMMARY.md:158 msgid "Converting Error Types" msgstr "゚ラヌの型倉換" #: src/SUMMARY.md:160 msgid "Deriving Error Enums" msgstr "列挙型゚ラヌの導出" #: src/SUMMARY.md:161 msgid "Dynamic Error Types" msgstr "動的な゚ラヌ型" #: src/SUMMARY.md:162 msgid "Adding Context to Errors" msgstr "コンテキストを゚ラヌに远加" #: src/SUMMARY.md:163 msgid "Testing" msgstr "テスト" #: src/SUMMARY.md:164 msgid "Unit Tests" msgstr "ナニットテスト" #: src/SUMMARY.md:165 msgid "Test Modules" msgstr "テストモゞュヌル" #: src/SUMMARY.md:166 msgid "Documentation Tests" msgstr "ドキュメンテヌションテスト" #: src/SUMMARY.md:167 msgid "Integration Tests" msgstr "むンテグレヌションテスト" #: src/SUMMARY.md:168 msgid "Useful crates" msgstr "䟿利クレヌト" #: src/SUMMARY.md:169 msgid "Unsafe Rust" msgstr "Unsafe Rust" #: src/SUMMARY.md:170 msgid "Dereferencing Raw Pointers" msgstr "生ポむンタの参照倖し" #: src/SUMMARY.md:171 msgid "Mutable Static Variables" msgstr "可倉なstatic倉数" #: src/SUMMARY.md:172 msgid "Unions" msgstr "共甚䜓" #: src/SUMMARY.md:173 msgid "Calling Unsafe Functions" msgstr "Unsafe関数の呌び出し" #: src/SUMMARY.md:174 msgid "Writing Unsafe Functions" msgstr "Unsafe関数の曞き方" #: src/SUMMARY.md:175 msgid "Extern Functions" msgstr "Extern関数" #: src/SUMMARY.md:176 msgid "Implementing Unsafe Traits" msgstr "Unsafeなトレむトの実装" #: src/SUMMARY.md:178 msgid "Safe FFI Wrapper" msgstr "安党なFFIラッパ" #: src/SUMMARY.md:181 src/SUMMARY.md:249 msgid "Android" msgstr "Android" #: src/SUMMARY.md:186 msgid "Setup" msgstr "セットアップ" #: src/SUMMARY.md:187 msgid "Build Rules" msgstr "ビルドのルヌル" #: src/SUMMARY.md:188 msgid "Binary" msgstr "バむナリ" #: src/SUMMARY.md:189 msgid "Library" msgstr "ラむブラリ" #: src/SUMMARY.md:190 msgid "AIDL" msgstr "AIDLAndroidむンタヌフェむス定矩蚀語" #: src/SUMMARY.md:191 msgid "Interface" msgstr "むンタヌフェむス" #: src/SUMMARY.md:192 msgid "Implementation" msgstr "実装" #: src/SUMMARY.md:193 msgid "Server" msgstr "サヌバ" #: src/SUMMARY.md:194 msgid "Deploy" msgstr "デプロむ" #: src/SUMMARY.md:195 msgid "Client" msgstr "クラむアント" #: src/SUMMARY.md:196 msgid "Changing API" msgstr "APIの倉曎" #: src/SUMMARY.md:197 src/SUMMARY.md:240 msgid "Logging" msgstr "ログ出力" #: src/SUMMARY.md:198 msgid "Interoperability" msgstr "盞互運甚性" #: src/SUMMARY.md:199 msgid "With C" msgstr "C" #: src/SUMMARY.md:200 msgid "Calling C with Bindgen" msgstr "BindgenによるCの呌び出し" #: src/SUMMARY.md:201 msgid "Calling Rust from C" msgstr "CからRust呌び出し" #: src/SUMMARY.md:202 msgid "With C++" msgstr "C++" #: src/SUMMARY.md:203 msgid "With Java" msgstr "Java" #: src/SUMMARY.md:207 msgid "Bare Metal: Morning" msgstr "ベアメタル AM" #: src/SUMMARY.md:212 msgid "no_std" msgstr "no_std" #: src/SUMMARY.md:213 msgid "A Minimal Example" msgstr "䟋" #: src/SUMMARY.md:214 msgid "alloc" msgstr "alloc" #: src/SUMMARY.md:215 msgid "Microcontrollers" msgstr "マむクロコントロヌラ" #: src/SUMMARY.md:216 msgid "Raw MMIO" msgstr "生MMIOメモリマップトI/O" #: src/SUMMARY.md:217 msgid "PACs" msgstr "PACs" #: src/SUMMARY.md:218 msgid "HAL Crates" msgstr "HALクレヌト" #: src/SUMMARY.md:219 msgid "Board Support Crates" msgstr "ボヌドサポヌトクレヌト" #: src/SUMMARY.md:220 msgid "The Type State Pattern" msgstr "タむプステヌトパタヌン" #: src/SUMMARY.md:221 msgid "embedded-hal" msgstr "embedded-hal" #: src/SUMMARY.md:222 msgid "probe-rs, cargo-embed" msgstr "probe-rs, cargo-embed" #: src/SUMMARY.md:223 msgid "Debugging" msgstr "デバッグ" #: src/SUMMARY.md:224 src/SUMMARY.md:242 msgid "Other Projects" msgstr "他のプロゞェクト" #: src/SUMMARY.md:226 msgid "Compass" msgstr "コンパス" #: src/SUMMARY.md:228 msgid "Bare Metal: Afternoon" msgstr "ベアメタル PM" #: src/SUMMARY.md:230 msgid "Application Processors" msgstr "アプリケヌションプロセッサ" #: src/SUMMARY.md:231 msgid "Inline Assembly" msgstr "むンラむンアセンブリ" #: src/SUMMARY.md:232 msgid "MMIO" msgstr "MMIO" #: src/SUMMARY.md:233 msgid "Let's Write a UART Driver" msgstr "UARTドラむバを曞いおみよう" #: src/SUMMARY.md:234 msgid "More Traits" msgstr "他のトレむト" #: src/SUMMARY.md:235 msgid "A Better UART Driver" msgstr "UARTドラむバの改善" #: src/SUMMARY.md:236 msgid "Bitflags" msgstr "ビットフラッグ" #: src/SUMMARY.md:237 msgid "Multiple Registers" msgstr "耇数のレゞスタ" #: src/SUMMARY.md:238 msgid "Driver" msgstr "ドラむバ" #: src/SUMMARY.md:239 src/SUMMARY.md:241 msgid "Using It" msgstr "䜿甚䟋" #: src/SUMMARY.md:243 msgid "Useful Crates" msgstr "䟿利クレヌト" #: src/SUMMARY.md:244 msgid "zerocopy" msgstr "zerocopy" #: src/SUMMARY.md:245 msgid "aarch64-paging" msgstr "aarch64-paging" #: src/SUMMARY.md:246 msgid "buddy_system_allocator" msgstr "buddy_system_allocator" #: src/SUMMARY.md:247 msgid "tinyvec" msgstr "tinyvec" #: src/SUMMARY.md:248 msgid "spin" msgstr "spin" #: src/SUMMARY.md:250 msgid "vmbase" msgstr "vmbase" #: src/SUMMARY.md:252 msgid "RTC Driver" msgstr "RTCリアルタむムクロックドラむバ" #: src/SUMMARY.md:255 msgid "Concurrency: Morning" msgstr "䞊行性 AM" #: src/SUMMARY.md:260 msgid "Threads" msgstr "スレッド" #: src/SUMMARY.md:261 msgid "Scoped Threads" msgstr "スコヌプ付きスレッド" #: src/SUMMARY.md:262 msgid "Channels" msgstr "チャネル" #: src/SUMMARY.md:263 msgid "Unbounded Channels" msgstr "Unboundedチャネル" #: src/SUMMARY.md:264 msgid "Bounded Channels" msgstr "Boundedチャネル" #: src/SUMMARY.md:265 msgid "Send and Sync" msgstr "SendずSync" #: src/SUMMARY.md:265 msgid "Send" msgstr "Send" #: src/SUMMARY.md:265 msgid "Sync" msgstr "Sync" #: src/SUMMARY.md:268 msgid "Examples" msgstr "䟋" #: src/SUMMARY.md:269 msgid "Shared State" msgstr "状態共有" #: src/SUMMARY.md:270 msgid "Arc" msgstr "Arc" #: src/SUMMARY.md:271 msgid "Mutex" msgstr "Mutex" #: src/SUMMARY.md:274 src/SUMMARY.md:294 msgid "Dining Philosophers" msgstr "食事する哲孊者" #: src/SUMMARY.md:275 msgid "Multi-threaded Link Checker" msgstr "マルチスレッド・リンクチェッカヌ" #: src/SUMMARY.md:277 msgid "Concurrency: Afternoon" msgstr "䞊行性 PM" #: src/SUMMARY.md:279 msgid "Async Basics" msgstr "Asyncの基瀎" #: src/SUMMARY.md:280 msgid "async/await" msgstr "async/await" #: src/SUMMARY.md:281 msgid "Futures" msgstr "Future" #: src/SUMMARY.md:282 msgid "Runtimes" msgstr "ランタむム" #: src/SUMMARY.md:283 msgid "Tokio" msgstr "Tokio" #: src/SUMMARY.md:284 msgid "Tasks" msgstr "タスク" #: src/SUMMARY.md:285 msgid "Async Channels" msgstr "Asyncチャネル" #: src/SUMMARY.md:287 msgid "Join" msgstr "" #: src/SUMMARY.md:288 msgid "Select" msgstr "" #: src/SUMMARY.md:289 msgid "Pitfalls" msgstr "萜ずし穎" #: src/SUMMARY.md:290 msgid "Blocking the Executor" msgstr "゚グれキュヌタのブロッキング" #: src/SUMMARY.md:291 msgid "Pin" msgstr "Pin" #: src/SUMMARY.md:292 msgid "Async Traits" msgstr "Asyncトレむト" #: src/SUMMARY.md:295 msgid "Broadcast Chat Application" msgstr "ブロヌドキャスト・チャットアプリ" #: src/SUMMARY.md:298 msgid "Final Words" msgstr "最埌に" #: src/SUMMARY.md:302 msgid "Thanks!" msgstr "ありがずうございたした" #: src/SUMMARY.md:303 msgid "Other Resources" msgstr "参考資料" #: src/SUMMARY.md:304 msgid "Credits" msgstr "クレゞット" #: src/SUMMARY.md:307 msgid "Solutions" msgstr "解答" #: src/SUMMARY.md:312 msgid "Day 1 Morning" msgstr "Day 1 AM" #: src/SUMMARY.md:313 msgid "Day 1 Afternoon" msgstr "Day 1 PM" #: src/SUMMARY.md:314 msgid "Day 2 Morning" msgstr "Day 2 AM" #: src/SUMMARY.md:315 msgid "Day 2 Afternoon" msgstr "Day 2 PM" #: src/SUMMARY.md:316 msgid "Day 3 Morning" msgstr "Day 3 AM" #: src/SUMMARY.md:317 msgid "Day 3 Afternoon" msgstr "Day 3 PM" #: src/SUMMARY.md:318 msgid "Bare Metal Rust Morning" msgstr "ベアメタルRust AM" #: src/SUMMARY.md:319 msgid "Bare Metal Rust Afternoon" msgstr "ベアメタルRust PM" #: src/SUMMARY.md:320 msgid "Concurrency Morning" msgstr "䞊行性 AM" #: src/SUMMARY.md:321 msgid "Concurrency Afternoon" msgstr "䞊行性 PM" #: src/welcome.md:1 msgid "# Welcome to Comprehensive Rust 🊀" msgstr "" #: src/welcome.md:3 msgid "" "[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/comprehensive-rust/" "build.yml?style=flat-square)](https://github.com/google/comprehensive-rust/actions/workflows/build." "yml?query=branch%3Amain)" msgstr "" #: src/welcome.md:3 msgid "Build workflow" msgstr "" #: src/welcome.md:3 msgid "" "[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/comprehensive-rust/" "build.yml?style=flat-square)](https://github.com/google/comprehensive-rust/actions/workflows/build." "yml?query=branch%3Amain)\n" "[![GitHub contributors](https://img.shields.io/github/contributors/google/comprehensive-rust?" "style=flat-square)](https://github.com/google/comprehensive-rust/graphs/contributors)" msgstr "" "[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/comprehensive-rust/" "build.yml?style=flat-square)](https://github.com/google/comprehensive-rust/actions/workflows/build." "yml?query=branch%3Amain)\n" "[![GitHub contributors](https://img.shields.io/github/contributors/google/comprehensive-rust?" "style=flat-square)](https://github.com/google/comprehensive-rust/graphs/contributors)" #: src/welcome.md:4 msgid "GitHub contributors" msgstr "" #: src/welcome.md:4 msgid "" "[![GitHub contributors](https://img.shields.io/github/contributors/google/comprehensive-rust?" "style=flat-square)](https://github.com/google/comprehensive-rust/graphs/contributors)\n" "[![GitHub stars](https://img.shields.io/github/stars/google/comprehensive-rust?style=flat-square)]" "(https://github.com/google/comprehensive-rust/stargazers)" msgstr "" "[![GitHub contributors](https://img.shields.io/github/contributors/google/comprehensive-rust?" "style=flat-square)](https://github.com/google/comprehensive-rust/graphs/contributors)\n" "[![GitHub stars](https://img.shields.io/github/stars/google/comprehensive-rust?style=flat-square)]" "(https://github.com/google/comprehensive-rust/stargazers)" #: src/welcome.md:5 msgid "GitHub stars" msgstr "" #: src/welcome.md:5 msgid "" "[![GitHub stars](https://img.shields.io/github/stars/google/comprehensive-rust?style=flat-square)]" "(https://github.com/google/comprehensive-rust/stargazers)" msgstr "" "[![GitHub stars](https://img.shields.io/github/stars/google/comprehensive-rust?style=flat-square)]" "(https://github.com/google/comprehensive-rust/stargazers)" #: src/welcome.md:7 msgid "" "This is a three day Rust course developed by the Android team. The course covers\n" "the full spectrum of Rust, from basic syntax to advanced topics like generics\n" "and error handling. It also includes Android-specific content on the last day." msgstr "" "この資料は、GoogleのAndroidチヌムによっお開発された3日間のRust講座です。本講座では、基本構文から" "ゞェネリクスや゚ラヌ凊理など、幅広い内容をカバヌしたす。たた、最終日にはAndroid専甚の内容も含たれお" "いたす。" #: src/welcome.md:11 msgid "" "The goal of the course is to teach you Rust. We assume you don't know anything\n" "about Rust and hope to:" msgstr "" "本講座の目的は、Rustを教える事です。Rustに関する前提知識は䞍芁ずしおおり、次の目暙を蚭定しおいた" "す" #: src/welcome.md:14 msgid "" "* Give you a comprehensive understanding of the Rust syntax and language.\n" "* Enable you to modify existing programs and write new programs in Rust.\n" "* Show you common Rust idioms." msgstr "" "* Rustの基本構文ず蚀語に぀いおの理解を深める。\n" "* 既存のプログラムを修正したり、新芏プログラムをRustで曞けるようにする。\n" "* 䞀般的なRustのむディオムを玹介する。" #: src/welcome.md:18 msgid "" "The first three days show you the fundamentals of Rust. Following this, you're\n" "invited to dive into one or more spezialized topics:" msgstr "最初の3日間は、Rustの基瀎を孊びたす。その埌、より専門的なトピックに進む事ができたす" #: src/welcome.md:21 msgid "" "* [Android](android.md): a half-day course on using Rust for Android platform\n" " development (AOSP). This includes interoperability wtih C, C++, and Java.\n" "* [Bare-metal](bare-metal.md): a full day class on using Rust for bare-metal\n" " (embedded) development. Both microcontrollers and application processors are\n" " covered.\n" "* [Concurrency](concurrency.md): a full day class on concurrency in Rust. We\n" " cover both classical concurrency (preemptively scheduling using threads and\n" " mutextes) and async/await concurrency (cooperative multitasking using\n" " futures)." msgstr "" "* [Android](android.md) Androidオヌプン゜ヌスプラットフォヌムAOSPでRustを䜿甚するための半日講" "座。C、C++、およびJavaずの盞互運甚性も含たれたす。\n" "* [Bare-metal](bare-metal.md) ベアメタル組み蟌み開発でRustを䜿甚するための1日講座。マむクロコ" "ントロヌラずアプリケヌションプロセッサの䞡方が察象ずなりたす。\n" "* [Concurrency](concurrency.md) Rustの䞊行性に぀いおの1日講座。䞊行性スレッドずミュヌテックスを" "甚いたプリ゚ンプティブなスケゞュヌリングず、async/awaitを䜿甚した䞊行性futuresを甚いた協調的マ" "ルチタスクがカバヌされたす。" #: src/welcome.md:32 msgid "## Non-Goals" msgstr "## 本講座の察象倖" #: src/welcome.md:34 msgid "" "Rust is a large language and we won't be able to cover all of it in a few days.\n" "Some non-goals of this course are:" msgstr "" "Rustは非垞に汎甚性の高い蚀語であり、数日で党おを網矅する事はできたせん。本講座の目暙ずしお蚭定され" "おいないものには、以䞋のようなものがありたす" #: src/welcome.md:37 msgid "" "* Learn how to develop macros, please see [Chapter 19.5 in the Rust\n" " Book](https://doc.rust-lang.org/book/ch19-06-macros.html) and [Rust by\n" " Example](https://doc.rust-lang.org/rust-by-example/macros.html) instead." msgstr "" "* マクロmacroの開発。マクロの詳现に぀いおは、[Rust Book 日本語版 Ch. 19.5](https://doc.rust-jp." "rs/book-ja/ch19-06-macros.html)ず[Rust by Example 日本語版 Ch.17](http://doc.rust-jp.rs/rust-by-" "example-ja/macros.html)を参照しおください。" #: src/welcome.md:41 msgid "## Assumptions" msgstr "## 前提知識" #: src/welcome.md:43 msgid "" "The course assumes that you already know how to program. Rust is a statically\n" "typed language and we will sometimes make comparisons with C and C++ to better\n" "explain or contrast the Rust approach." msgstr "" "本講座では、既にプログラミングの知識がある事を前提ずしおいたす。Rustは静的型付け蚀語であり、Rustの" "アプロヌチをより分かりやすく説明するために、時折CやC++ずの比范を行いたす。" #: src/welcome.md:47 msgid "" "If you know how to program in a dynamically typed language such as Python or\n" "JavaScript, then you will be able to follow along just fine too." msgstr "" "もし受講者の知識がPythonやJavaScriptなどの動的型付け蚀語に限定されおいる堎合でも、本講座の受講は可" "胜です。" #: src/welcome.md:50 src/cargo/rust-ecosystem.md:19 src/cargo/code-samples.md:22 #: src/cargo/running-locally.md:68 src/welcome-day-1.md:14 src/welcome-day-1/what-is-rust.md:19 #: src/hello-world.md:20 src/hello-world/small-example.md:21 src/why-rust.md:9 #: src/why-rust/compile-time.md:14 src/why-rust/runtime.md:8 src/why-rust/modern.md:19 #: src/basic-syntax/scalar-types.md:19 src/basic-syntax/compound-types.md:28 #: src/basic-syntax/references.md:21 src/basic-syntax/slices.md:18 #: src/basic-syntax/string-slices.md:25 src/basic-syntax/functions.md:33 #: src/basic-syntax/rustdoc.md:22 src/basic-syntax/methods.md:32 #: src/basic-syntax/functions-interlude.md:25 src/exercises/day-1/morning.md:9 #: src/exercises/day-1/for-loops.md:90 src/basic-syntax/variables.md:15 #: src/basic-syntax/type-inference.md:24 src/basic-syntax/static-and-const.md:46 #: src/basic-syntax/scopes-shadowing.md:23 src/memory-management/stack.md:26 #: src/memory-management/rust.md:12 src/ownership/move-semantics.md:20 #: src/ownership/moves-function-calls.md:18 src/ownership/copy-clone.md:33 #: src/ownership/borrowing.md:25 src/ownership/shared-unique-borrows.md:23 #: src/ownership/lifetimes-function-calls.md:27 src/ownership/lifetimes-data-structures.md:23 #: src/exercises/day-1/afternoon.md:9 src/exercises/day-1/book-library.md:100 src/structs.md:29 #: src/structs/tuple-structs.md:35 src/structs/field-shorthand.md:25 src/enums.md:31 #: src/enums/variant-payloads.md:33 src/enums/sizes.md:27 src/methods.md:28 #: src/methods/receiver.md:23 src/methods/example.md:44 src/pattern-matching.md:23 #: src/pattern-matching/destructuring-enums.md:33 src/pattern-matching/destructuring-structs.md:21 #: src/pattern-matching/destructuring-arrays.md:19 src/pattern-matching/match-guards.md:20 #: src/exercises/day-2/morning.md:9 src/exercises/day-2/points-polygons.md:115 #: src/control-flow/blocks.md:40 src/control-flow/if-expressions.md:33 #: src/control-flow/if-let-expressions.md:21 src/control-flow/while-let-expressions.md:24 #: src/control-flow/for-expressions.md:23 src/control-flow/loop-expressions.md:25 #: src/control-flow/match-expressions.md:26 src/std.md:23 src/std/option-result.md:16 #: src/std/string.md:28 src/std/vec.md:35 src/std/hashmap.md:36 src/std/box.md:32 #: src/std/box-recursive.md:31 src/std/rc.md:29 src/modules.md:26 src/modules/visibility.md:37 #: src/modules/filesystem.md:42 src/exercises/day-2/afternoon.md:5 src/generics/data-types.md:19 #: src/generics/methods.md:23 src/traits/trait-objects.md:70 src/traits/default-methods.md:30 #: src/traits/trait-bounds.md:33 src/traits/impl-trait.md:21 src/traits/iterator.md:30 #: src/traits/from-iterator.md:15 src/traits/from-into.md:27 src/traits/drop.md:32 #: src/traits/default.md:38 src/traits/operators.md:24 src/traits/closures.md:23 #: src/exercises/day-3/morning.md:5 src/error-handling/result.md:25 #: src/error-handling/try-operator.md:46 src/error-handling/converting-error-types-example.md:48 #: src/error-handling/deriving-error-enums.md:37 src/error-handling/dynamic-errors.md:34 #: src/error-handling/error-contexts.md:33 src/unsafe.md:26 src/unsafe/raw-pointers.md:25 #: src/unsafe/mutable-static-variables.md:30 src/unsafe/unions.md:19 #: src/unsafe/writing-unsafe-functions.md:31 src/unsafe/extern-functions.md:19 #: src/unsafe/unsafe-traits.md:28 src/exercises/day-3/afternoon.md:5 #: src/android/interoperability/with-c/rust.md:81 src/exercises/android/morning.md:10 #: src/bare-metal/minimal.md:15 src/bare-metal/alloc.md:37 src/bare-metal/microcontrollers.md:23 #: src/bare-metal/microcontrollers/mmio.md:62 src/bare-metal/microcontrollers/pacs.md:47 #: src/bare-metal/microcontrollers/hals.md:37 src/bare-metal/microcontrollers/board-support.md:26 #: src/bare-metal/microcontrollers/type-state.md:30 #: src/bare-metal/microcontrollers/embedded-hal.md:17 src/bare-metal/microcontrollers/probe-rs.md:14 #: src/bare-metal/microcontrollers/debugging.md:25 #: src/bare-metal/microcontrollers/other-projects.md:16 src/exercises/bare-metal/morning.md:5 #: src/bare-metal/aps.md:7 src/bare-metal/aps/inline-assembly.md:41 src/bare-metal/aps/mmio.md:7 #: src/bare-metal/aps/uart.md:53 src/bare-metal/aps/uart/traits.md:22 #: src/bare-metal/aps/better-uart.md:24 src/bare-metal/aps/better-uart/bitflags.md:35 #: src/bare-metal/aps/better-uart/registers.md:39 src/bare-metal/aps/better-uart/driver.md:62 #: src/bare-metal/aps/better-uart/using.md:49 src/bare-metal/aps/logging.md:48 #: src/bare-metal/aps/logging/using.md:44 src/bare-metal/useful-crates/zerocopy.md:43 #: src/bare-metal/useful-crates/aarch64-paging.md:26 #: src/bare-metal/useful-crates/buddy_system_allocator.md:24 #: src/bare-metal/useful-crates/tinyvec.md:21 src/bare-metal/useful-crates/spin.md:21 #: src/bare-metal/android/vmbase.md:19 src/exercises/bare-metal/afternoon.md:5 #: src/concurrency/threads.md:28 src/concurrency/scoped-threads.md:35 src/concurrency/channels.md:25 #: src/concurrency/send-sync.md:18 src/concurrency/send-sync/send.md:11 #: src/concurrency/send-sync/sync.md:12 src/concurrency/shared_state/arc.md:27 #: src/concurrency/shared_state/mutex.md:29 src/concurrency/shared_state/example.md:21 #: src/exercises/concurrency/morning.md:10 src/async/async-await.md:23 src/async/futures.md:30 #: src/async/runtimes.md:18 src/async/runtimes/tokio.md:31 src/async/tasks.md:51 #: src/async/channels.md:33 src/async/control-flow/join.md:34 src/async/control-flow/select.md:59 #: src/async/pitfalls/blocking-executor.md:27 src/async/pitfalls/pin.md:66 #: src/exercises/concurrency/afternoon.md:11 #: src/exercises/concurrency/dining-philosophers-async.md:75 msgid "
" msgstr "" #: src/welcome.md:52 msgid "" "This is an example of a _speaker note_. We will use these to add additional\n" "information to the slides. This could be key points which the instructor should\n" "cover as well as answers to typical questions which come up in class." msgstr "" "これはスピヌカヌノヌトの䞀䟋です。これを䜿甚しおスラむドを捕捉したす。講垫がカバヌすべき芁点や、授" "業でよく出る質問ぞの回答などが含たれたす。" #: src/welcome.md:56 src/cargo/rust-ecosystem.md:67 src/cargo/code-samples.md:35 #: src/cargo/running-locally.md:74 src/welcome-day-1.md:42 src/welcome-day-1/what-is-rust.md:29 #: src/hello-world.md:40 src/hello-world/small-example.md:44 src/why-rust.md:24 #: src/why-rust/compile-time.md:35 src/why-rust/runtime.md:22 src/why-rust/modern.md:66 #: src/basic-syntax/scalar-types.md:43 src/basic-syntax/compound-types.md:62 #: src/basic-syntax/references.md:29 src/basic-syntax/slices.md:36 #: src/basic-syntax/string-slices.md:44 src/basic-syntax/functions.md:41 #: src/basic-syntax/rustdoc.md:33 src/basic-syntax/methods.md:45 #: src/basic-syntax/functions-interlude.md:30 src/exercises/day-1/morning.md:28 #: src/exercises/day-1/for-loops.md:95 src/basic-syntax/variables.md:20 #: src/basic-syntax/type-inference.md:48 src/basic-syntax/static-and-const.md:52 #: src/basic-syntax/scopes-shadowing.md:39 src/memory-management/stack.md:49 #: src/memory-management/rust.md:18 src/ownership/move-semantics.md:26 #: src/ownership/moves-function-calls.md:26 src/ownership/copy-clone.md:51 #: src/ownership/borrowing.md:51 src/ownership/shared-unique-borrows.md:29 #: src/ownership/lifetimes-function-calls.md:60 src/ownership/lifetimes-data-structures.md:30 #: src/exercises/day-1/afternoon.md:15 src/exercises/day-1/book-library.md:104 src/structs.md:42 #: src/structs/tuple-structs.md:43 src/structs/field-shorthand.md:72 src/enums.md:41 #: src/enums/variant-payloads.md:45 src/enums/sizes.md:155 src/methods.md:41 #: src/methods/receiver.md:29 src/methods/example.md:53 src/pattern-matching.md:35 #: src/pattern-matching/destructuring-enums.md:39 src/pattern-matching/destructuring-structs.md:29 #: src/pattern-matching/destructuring-arrays.md:46 src/pattern-matching/match-guards.md:28 #: src/exercises/day-2/morning.md:15 src/exercises/day-2/points-polygons.md:125 #: src/control-flow/blocks.md:46 src/control-flow/if-expressions.md:37 #: src/control-flow/if-let-expressions.md:41 src/control-flow/while-let-expressions.md:29 #: src/control-flow/for-expressions.md:30 src/control-flow/loop-expressions.md:32 #: src/control-flow/match-expressions.md:33 src/std.md:31 src/std/option-result.md:25 #: src/std/string.md:42 src/std/vec.md:49 src/std/hashmap.md:66 src/std/box.md:39 #: src/std/box-recursive.md:41 src/std/rc.md:69 src/modules.md:32 src/modules/visibility.md:48 #: src/modules/filesystem.md:71 src/exercises/day-2/afternoon.md:11 src/generics/data-types.md:25 #: src/generics/methods.md:31 src/traits/trait-objects.md:83 src/traits/default-methods.md:60 #: src/traits/trait-bounds.md:50 src/traits/impl-trait.md:44 src/traits/iterator.md:42 #: src/traits/from-iterator.md:26 src/traits/from-into.md:33 src/traits/drop.md:42 #: src/traits/default.md:47 src/traits/operators.md:38 src/traits/closures.md:38 #: src/exercises/day-3/morning.md:11 src/error-handling/result.md:33 #: src/error-handling/try-operator.md:53 src/error-handling/converting-error-types-example.md:60 #: src/error-handling/deriving-error-enums.md:45 src/error-handling/dynamic-errors.md:41 #: src/error-handling/error-contexts.md:42 src/unsafe.md:32 src/unsafe/raw-pointers.md:43 #: src/unsafe/mutable-static-variables.md:35 src/unsafe/unions.md:28 #: src/unsafe/writing-unsafe-functions.md:38 src/unsafe/extern-functions.md:28 #: src/unsafe/unsafe-traits.md:37 src/exercises/day-3/afternoon.md:11 #: src/android/interoperability/with-c/rust.md:86 src/exercises/android/morning.md:15 #: src/bare-metal/no_std.md:65 src/bare-metal/minimal.md:26 src/bare-metal/alloc.md:49 #: src/bare-metal/microcontrollers.md:29 src/bare-metal/microcontrollers/mmio.md:72 #: src/bare-metal/microcontrollers/pacs.md:65 src/bare-metal/microcontrollers/hals.md:49 #: src/bare-metal/microcontrollers/board-support.md:40 #: src/bare-metal/microcontrollers/type-state.md:43 #: src/bare-metal/microcontrollers/embedded-hal.md:23 src/bare-metal/microcontrollers/probe-rs.md:29 #: src/bare-metal/microcontrollers/debugging.md:38 #: src/bare-metal/microcontrollers/other-projects.md:26 src/exercises/bare-metal/morning.md:11 #: src/bare-metal/aps.md:15 src/bare-metal/aps/inline-assembly.md:58 src/bare-metal/aps/mmio.md:17 #: src/bare-metal/aps/uart/traits.md:27 src/bare-metal/aps/better-uart.md:28 #: src/bare-metal/aps/better-uart/bitflags.md:40 src/bare-metal/aps/better-uart/registers.md:46 #: src/bare-metal/aps/better-uart/driver.md:67 src/bare-metal/aps/better-uart/using.md:55 #: src/bare-metal/aps/logging.md:52 src/bare-metal/aps/logging/using.md:49 #: src/bare-metal/useful-crates/zerocopy.md:53 src/bare-metal/useful-crates/aarch64-paging.md:33 #: src/bare-metal/useful-crates/buddy_system_allocator.md:30 #: src/bare-metal/useful-crates/tinyvec.md:26 src/bare-metal/useful-crates/spin.md:30 #: src/bare-metal/android/vmbase.md:25 src/exercises/bare-metal/afternoon.md:11 #: src/concurrency/threads.md:45 src/concurrency/scoped-threads.md:40 src/concurrency/channels.md:32 #: src/concurrency/send-sync.md:23 src/concurrency/send-sync/send.md:16 #: src/concurrency/send-sync/sync.md:18 src/concurrency/shared_state/arc.md:38 #: src/concurrency/shared_state/mutex.md:45 src/concurrency/shared_state/example.md:56 #: src/exercises/concurrency/morning.md:16 src/async/async-await.md:48 src/async/futures.md:45 #: src/async/runtimes.md:29 src/async/runtimes/tokio.md:49 src/async/tasks.md:64 #: src/async/channels.md:49 src/async/control-flow/join.md:50 src/async/control-flow/select.md:77 #: src/async/pitfalls/blocking-executor.md:50 src/async/pitfalls/pin.md:112 #: src/async/pitfalls/async-traits.md:63 src/exercises/concurrency/afternoon.md:17 #: src/exercises/concurrency/dining-philosophers-async.md:79 msgid "
" msgstr "" #: src/running-the-course.md:1 msgid "# Running the Course" msgstr "# 講座の運営に぀いお" #: src/running-the-course.md:3 src/running-the-course/course-structure.md:3 msgid "> This page is for the course instructor." msgstr "> このペヌゞは講垫甚です。" #: src/running-the-course.md:5 msgid "" "Here is a bit of background information about how we've been running the course\n" "internally at Google." msgstr "以䞋は、Google内での講座の運営方法に関する情報です。" #: src/running-the-course.md:8 msgid "Before you run the course, you will want to:" msgstr "講座開始たでに、以䞋にあげる準備を枈たせおおくず良いでしょう" #: src/running-the-course.md:10 msgid "" "1. Make yourself familiar with the course material. We've included speaker notes\n" " to help highlight the key points (please help us by contributing more speaker\n" " notes!). When presenting, you should make sure to open the speaker notes in a\n" " popup (click the link with a little arrow next to \"Speaker Notes\"). This way\n" " you have a clean screen to present to the class.\n" "\n" "1. Decide on the dates. Since the course takes at least three full days, we recommend that you\n" " schedule the days over two weeks. Course participants have said that\n" " they find it helpful to have a gap in the course since it helps them process\n" " all the information we give them.\n" "\n" "1. Find a room large enough for your in-person participants. We recommend a\n" " class size of 15-25 people. That's small enough that people are comfortable\n" " asking questions --- it's also small enough that one instructor will have\n" " time to answer the questions. Make sure the room has _desks_ for yourself and for the\n" " students: you will all need to be able to sit and work with your laptops.\n" " In particular, you will be doing a lot of live-coding as an instructor, so a lectern won't\n" " be very helpful for you.\n" "\n" "1. On the day of your course, show up to the room a little early to set things\n" " up. We recommend presenting directly using `mdbook serve` running on your\n" " laptop (see the [installation instructions][3]). This ensures optimal performance with no lag " "as you change pages.\n" " Using your laptop will also allow you to fix typos as you or the course\n" " participants spot them.\n" "\n" "1. Let people solve the exercises by themselves or in small groups.\n" " We typically spend 30-45 minutes on exercises in the morning and in the afternoon (including " "time to review the solutions).\n" " Make sure to\n" " ask people if they're stuck or if there is anything you can help with. When\n" " you see that several people have the same problem, call it out to the class\n" " and offer a solution, e.g., by showing people where to find the relevant\n" " information in the standard library." msgstr "" "1. 資料に慣れおおいおください。芁点を匷調するためにスピヌカヌノヌトが甚意されおいたす内容の远加に" "ご協力ください。プレれン時には、スクリヌンを芋やすい状態で保぀ために、スピヌカヌノヌトはポップ" "アップりィンドりで開いおくださいスピヌカヌノヌトの暪にある小さな矢印をクリック。\n" "\n" "1. あらかじめ日皋を決めおおいおください。講座は最䜎でも3日かかるため、2週間にわたっお日皋を組む事を" "掚奚しおいたす。過去の受講者によるず、講座の間に数日ギャップを蚭ける事で内容が吞収しやすくなりた" "す。\n" "\n" "1. 十分な広さの郚屋を確保しおおいおください。15~25名皋床のクラスを掚奚しおいたす。受講者にずっお質" "問がしやすい人数であり、1人の講垫が質問に答える時間も確保できる芏暡だからです。たた、皆さんはPCで䜜" "業をする必芁があるため、講垫を含めた人数分の机を甚意しおおいおください。ラむブコヌディング圢匏での" "実斜を想定しおいるため、講壇は䞍芁です。\n" "\n" "1. 圓日は少し早めに到着しお準備をしおください。自分のPCで実行する`mdbook serve`から盎接プレれンを行" "う事を掚奚したす[むンストヌル手順][3]はこちら。これにより、ペヌゞ切り替え時に遅延なしで最適なパ" "フォヌマンスが埗られたす。たた、PCを䜿甚する事で、受講者や自分自身が芋぀けたタむプミスなども修正可" "胜になりたす。\n" "\n" "1. 緎習問題は個人か小さいグルヌプで解いおください。回答をレビュヌする時間も含め、各緎習問題に30~45" "分を費やしたす。受講者が行き詰たっおいるかどうか、䜕か質問があるかなど確認しおください。耇数の受講" "者が同じ問題で詰たっおいる堎合、クラス党䜓に察しおそれを共有し、解決策を提䟛しおください。䟋えば、" "探しおいる情報が暙準ラむブラリのどこにあるかを瀺す、など。" #: src/running-the-course.md:43 msgid "" "That is all, good luck running the course! We hope it will be as much fun for\n" "you as it has been for us!" msgstr "以䞊です。運営頑匵っおください皆さんにずっおも楜しい時間になりたすように" #: src/running-the-course.md:46 msgid "" "Please [provide feedback][1] afterwards so that we can keep improving the\n" "course. We would love to hear what worked well for you and what can be made\n" "better. Your students are also very welcome to [send us feedback][2]!" msgstr "" "本講座の改善に向けお[フィヌドバック][1]をお願いしたす。うたくいった点や改善点に぀いお幅広くご意芋お" "聞かせください。[受講者からのフィヌドバック][2]も歓迎しおおりたす" #: src/running-the-course/course-structure.md:1 msgid "# Course Structure" msgstr "" #: src/running-the-course/course-structure.md:5 msgid "The course is fast paced and covers a lot of ground:" msgstr "本講座はペヌスが早く、倚くの内容をカバヌしたす" #: src/running-the-course/course-structure.md:7 msgid "" "* Day 1: Basic Rust, ownership and the borrow checker.\n" "* Day 2: Compound data types, pattern matching, the standard library.\n" "* Day 3: Traits and generics, error handling, testing, unsafe Rust." msgstr "" "* Day 1 Rustの基本、所有暩ず借甚チェッカヌ\n" "* Day 2 耇合デヌタ型、パタヌンマッチング、暙準ラむブラリ\n" "* Day 3 トレむトずゞェネリクス、゚ラヌ凊理、テスト、unsafe Rust" #: src/running-the-course/course-structure.md:11 msgid "## Deep Dives" msgstr "## 専門的なトピック" #: src/running-the-course/course-structure.md:13 msgid "" "In addition to the 3-day class on Rust Fundamentals, we cover some more\n" "specialized topics:" msgstr "Rustの基瀎に関する3日間の講座に加え、いく぀かのより専門的なトピックも甚意されおいたす" #: src/running-the-course/course-structure.md:16 msgid "### Android" msgstr "" #: src/running-the-course/course-structure.md:18 msgid "" "The [Android Deep Dive](../android.md) is a half-day course on using Rust for\n" "Android platform development. This includes interoperability wtih C, C++, and\n" "Java." msgstr "" "[Androidç·š](../android.md)は、Androidオヌプン゜ヌスプラットフォヌムAOSPでRustを䜿甚するための半" "日皋床の講座です。C、C++、およびJavaずの盞互運甚性も含たれたす。" #: src/running-the-course/course-structure.md:22 msgid "" "You will need an [AOSP checkout][1]. Make a checkout of the [course\n" "repository][2] on the same machine and move the `src/android/` directory into\n" "the root of your AOSP checkout. This will ensure that the Android build system\n" "sees the `Android.bp` files in `src/android/`." msgstr "" "[AOSPのチェックアりト][1]が必芁です。同じ端末から[講座のリポゞトリ][2]をチェックアりトし、`src/" "android/`ディレクトリをAOSPチェックアりトのルヌトに移動しおください。これにより、Androidビルドシス" "テムが`src/android/`内の`Android.bp`を確認できるようになりたす。" #: src/running-the-course/course-structure.md:27 msgid "" "Ensure that `adb sync` works with your emulator or real device and pre-build all\n" "Android examples using `src/android/build_all.sh`. Read the script to see the\n" "commands it runs and make sure they work when you run them by hand." msgstr "" "゚ミュレヌタたたは実際のデバむスで`adb sync`が機胜する事を確認し、`src/android/build_all.sh`を䜿甚" "しお党おのAndroidの䟋を事前にビルドしおください。スクリプトを読んで実行コマンドを確認し、手動で実行" "した際に正垞に動䜜する事を確認しおください。" #: src/running-the-course/course-structure.md:34 msgid "### Bare-Metal" msgstr "### ベアメタル" #: src/running-the-course/course-structure.md:36 msgid "" "The [Bare-Metal Deep Dive](../bare-metal.md): a full day class on using Rust for\n" "bare-metal (embedded) development. Both microcontrollers and application\n" "processors are covered." msgstr "" "[ベアメタル線](../bare-metal.md)は、ベアメタル組み蟌み開発でRustを䜿甚するための1日講座です。マ" "むクロコントロヌラずアプリケヌションプロセッサの䞡方が察象ずなりたす。" #: src/running-the-course/course-structure.md:40 msgid "" "For the microcontroller part, you will need to buy the [BBC\n" "micro:bit](https://microbit.org/) v2 development board ahead of time. Everybody\n" "will need to install a number of packages as described on the [welcome\n" "page](../bare-metal.md)." msgstr "" "マむクロコントロヌラの章では、事前に[BBCmicro:bit](https://microbit.org/)v2開発ボヌドを賌入する必芁" "がありたす。たた、[welcomeペヌゞ](../bare-metal.md)で説明されおいるように、耇数のパッケヌゞをむンス" "トヌルする必芁がありたす。" #: src/running-the-course/course-structure.md:45 msgid "### Concurrency" msgstr "### 䞊行性" #: src/running-the-course/course-structure.md:47 msgid "" "The [Concurrency Deep Dive](../concurrency.md) is a full day class on classical\n" "as well as `async`/`await` concurrency." msgstr "[䞊行性線](../concurrency.md) は、䞊行性ずasync/awaitを䜿甚した䞊行性に぀いおの1日講座です。" #: src/running-the-course/course-structure.md:50 msgid "" "You will need a fresh crate set up and the dependencies downloaded and ready to\n" "go. You can then copy/paste the examples into `src/main.rs` to experiment with\n" "them:" msgstr "" "新芏クレヌトの䜜成ず、䟝存関係dependenciesのダりンロヌドが必芁です。その埌、䟋を`src/main.rs`に" "コピペしお実行する事ができたす" #: src/running-the-course/course-structure.md:54 msgid "" "```shell\n" "cargo init concurrency\n" "cd concurrency\n" "cargo add tokio --features full\n" "cargo run\n" "```" msgstr "" #: src/running-the-course/course-structure.md:61 msgid "## Format" msgstr "## フォヌマット" #: src/running-the-course/course-structure.md:63 msgid "" "The course is meant to be very interactive and we recommend letting the\n" "questions drive the exploration of Rust!" msgstr "本講座はむンタラクティブな圢匏で行いたす。積極的に質問しお、Rustぞの理解を深めおください" #: src/running-the-course/keyboard-shortcuts.md:1 msgid "# Keyboard Shortcuts" msgstr "" #: src/running-the-course/keyboard-shortcuts.md:3 msgid "There are several useful keyboard shortcuts in mdBook:" msgstr "mdBookには、䟿利なショヌトカットキヌがいく぀か存圚したす" #: src/running-the-course/keyboard-shortcuts.md:5 msgid "" "* Arrow-Left: Navigate to the previous page.\n" "* Arrow-Right: Navigate to the next page.\n" "* Ctrl + Enter: Execute the code sample that has focus.\n" "* s: Activate the search bar." msgstr "" "* Arrow-Left 前のペヌゞに移動\n" "* Arrow-Right 次のペヌゞに移動。\n" "* Ctrl + Enter フォヌカスを持぀コヌドサンプルを実行\n" "* s 怜玢バヌを起動" #: src/running-the-course/translations.md:1 msgid "# Translations" msgstr "# 翻蚳" #: src/running-the-course/translations.md:3 msgid "" "The course has been translated into other languages by a set of wonderful\n" "volunteers:" msgstr "本資料は、ボランティアによっお翻蚳されおいたす" #: src/running-the-course/translations.md:6 msgid "" "* [Brazilian Portuguese][pt-BR] by [@rastringer] and [@hugojacob].\n" "* [Korean][ko] by [@keispace], [@jiyongp] and [@jooyunghan]." msgstr "" #: src/running-the-course/translations.md:9 msgid "Use the language picker in the top-right corner to switch between languages." msgstr "画面右䞊の蚀語切り替えボタンから、切り替えを行なっおください。" #: src/running-the-course/translations.md:11 msgid "" "If you want to help with this effort, please see [our instructions] for how to\n" "get going. Translations are coordinated on the [issue tracker]." msgstr "" "この取り組みにご協力いただける堎合は、[our instructions]をご芧ください。翻蚳は[issue tracker]で管理" "されおいたす。" #: src/cargo.md:1 msgid "# Using Cargo" msgstr "" #: src/cargo.md:3 msgid "" "When you start reading about Rust, you will soon meet [Cargo](https://doc.rust-lang.org/cargo/), " "the standard tool\n" "used in the Rust ecosystem to build and run Rust applications. Here we want to\n" "give a brief overview of what Cargo is and how it fits into the wider ecosystem\n" "and how it fits into this training." msgstr "" "Rustを孊び始めるず、たもなくRust゚コシステムで広く䜿われおいるビルドシステム兌パッケヌゞマネヌゞャ" "である[Cargo](https://doc.rust-lang.org/cargo/)ずいう暙準ツヌルに出䌚いたす。ここでは、Cargoの抂芁" "や䜿甚方法、そしお本講座における重芁性に぀いお簡単に説明したす。" #: src/cargo.md:8 msgid "## Installation" msgstr "## むンストヌル" #: src/cargo.md:10 msgid "### Rustup (Recommended)" msgstr "### Rustup (掚奚)" #: src/cargo.md:12 msgid "" "You can follow the instructions to install cargo and rust compiler, among other standard ecosystem " "tools with the [rustup][3] tool, which is maintained by the Rust Foundation." msgstr "" "[rustup][3]ツヌルを䜿甚しお、cargoやrustコンパむラなどの暙準゚コシステムツヌルをむンストヌルした" "す。RustupはRust Foundationによっおメンテナンスされおいたす。" #: src/cargo.md:14 msgid "" "Along with cargo and rustc, Rustup will install itself as a command line utility that you can use " "to install/switch toolchains, setup cross compilation, etc." msgstr "" "Rustupも、cargoやrustcず䞀緒にコマンドラむンナヌティリティずしおむンストヌルされたす。Rustupを䜿甚" "するこずで、ツヌルチェヌンのむンストヌルや切り替え、クロスコンパむルの蚭定などが行えたす。" #: src/cargo.md:16 msgid "### Package Managers" msgstr "### パッケヌゞマネヌゞャ" #: src/cargo.md:18 msgid "#### Debian" msgstr "" #: src/cargo.md:20 msgid "On Debian/Ubuntu, you can install Cargo, the Rust source and the [Rust formatter][6] with" msgstr "" "Debian/Ubuntuを䜿甚しおいる堎合、以䞋のコマンドを䜿っおcargo、rustの゜ヌスコヌド、[Rust formatter]" "[6]をむンストヌルしたす" #: src/cargo.md:22 msgid "" "```shell\n" "$ sudo apt install cargo rust-src rustfmt\n" "```" msgstr "" #: src/cargo.md:26 msgid "" "This will allow [rust-analyzer][1] to jump to the definitions. We suggest using\n" "[VS Code][2] to edit the code (but any LSP compatible editor works)." msgstr "" "これで[rust-analyzer][1]を䜿っお定矩に飛べるようになりたす。コヌドの線集には、[VS Code][2]を掚奚し" "おいたすただし、LSP互換゚ディタならどれでも倧䞈倫です。" #: src/cargo.md:29 msgid "" "Some folks also like to use the [JetBrains][4] family of IDEs, which do their own analysis but " "have their own tradeoffs. If you prefer them, you can install the [Rust Plugin][5]. Please take " "note that as of January 2023 debugging only works on the CLion version of the JetBrains IDEA suite." msgstr "" "[JetBrains][4]ファミリのIDEを䜿いたい人もいるでしょう。これらは独自の分析を提䟛しおくれたすが、ト" "レヌドオフもありたす。もし䜿甚したい堎合、[Rust Plugin][5]のむンストヌルが可胜です。ただし、2023幎1" "月時点では、デバッグがJetBrains IDEA suiteのCLionバヌゞョンでしか動䜜しない点に泚意しおください。" #: src/cargo/rust-ecosystem.md:1 msgid "# The Rust Ecosystem" msgstr "" #: src/cargo/rust-ecosystem.md:3 msgid "The Rust ecosystem consists of a number of tools, of which the main ones are:" msgstr "Rust゚コシステムの䞻芁ツヌルは以䞋の通りです" #: src/cargo/rust-ecosystem.md:5 msgid "" "* `rustc`: the Rust compiler which turns `.rs` files into binaries and other\n" " intermediate formats.\n" "\n" "* `cargo`: the Rust dependency manager and build tool. Cargo knows how to\n" " download dependencies hosted on and it will pass them to\n" " `rustc` when building your project. Cargo also comes with a built-in test\n" " runner which is used to execute unit tests.\n" "\n" "* `rustup`: the Rust toolchain installer and updater. This tool is used to\n" " install and update `rustc` and `cargo` when new versions of Rust is released.\n" " In addition, `rustup` can also download documentation for the standard\n" " library. You can have multiple versions of Rust installed at once and `rustup`\n" " will let you switch between them as needed." msgstr "" "* `rustc` Rustのコンパむラです。`.rs`ファむルをバむナリや他の䞭間圢匏に倉換したす。\n" "\n" "* `cargo` Rustのビルドシステム兌パッケヌゞマネヌゞャです。でホストされおいる䟝" "存関係をダりンロヌドし、プロゞェクトビルド時に`rustc`に枡したす。Cargo に組み蟌たれたテストランナを" "䜿っお、ナニットテストを実行するこずもできたす。\n" "\n" "* `rustup` Rustのツヌルチェヌンを管理するためのツヌルです。`rustc`や`cargo`のむンストヌルやアップ" "デヌトに䜿甚されたす。暙準ラむブラリのドキュメントをダりンロヌドする事も可胜です。たた、耇数のRust" "のバヌゞョンがむンストヌルされおいる堎合、`rustup`で切り替えが行えたす。" #: src/cargo/rust-ecosystem.md:21 src/hello-world.md:25 src/hello-world/small-example.md:27 #: src/why-rust/runtime.md:10 src/why-rust/modern.md:21 src/basic-syntax/compound-types.md:30 #: src/basic-syntax/references.md:23 src/pattern-matching/destructuring-enums.md:35 #: src/error-handling/try-operator.md:48 src/error-handling/converting-error-types-example.md:50 #: src/concurrency/threads.md:30 src/async/async-await.md:25 msgid "Key points:" msgstr "芁点" #: src/cargo/rust-ecosystem.md:23 msgid "" "* Rust has a rapid release schedule with a new release coming out\n" " every six weeks. New releases maintain backwards compatibility with\n" " old releases --- plus they enable new functionality.\n" "\n" "* There are three release channels: \"stable\", \"beta\", and \"nightly\".\n" "\n" "* New features are being tested on \"nightly\", \"beta\" is what becomes\n" " \"stable\" every six weeks.\n" "\n" "* Rust also has [editions]: the current edition is Rust 2021. Previous\n" " editions were Rust 2015 and Rust 2018.\n" "\n" " * The editions are allowed to make backwards incompatible changes to\n" " the language.\n" "\n" " * To prevent breaking code, editions are opt-in: you select the\n" " edition for your crate via the `Cargo.toml` file.\n" "\n" " * To avoid splitting the ecosystem, Rust compilers can mix code\n" " written for different editions.\n" "\n" " * Mention that it is quite rare to ever use the compiler directly not through `cargo` (most " "users never do).\n" "\n" " * It might be worth alluding that Cargo itself is an extremely powerful and comprehensive tool. " "It is capable of many advanced features including but not limited to: \n" " * Project/package structure\n" " * [workspaces]\n" " * Dev Dependencies and Runtime Dependency management/caching\n" " * [build scripting]\n" " * [global installation]\n" " * It is also extensible with sub command plugins as well (such as [cargo clippy]).\n" " * Read more from the [official Cargo Book]" msgstr "" "* Rust蚀語ずコンパむラは、6週間のリリヌスサむクルを採甚しおいたす。新しいリリヌスは、叀いリリヌスず" "の埌方互換性を維持しながら、新機胜を提䟛したす。\n" "\n" "* リリヌスチャネルは3぀ありたす「stable」「beta」「nightly」。\n" "\n" "* 新機胜は「nightly」でテストされ、「beta」が6週間毎に「stable」ずなりたす。\n" "\n" "* Rustには[editions]゚ディションがありたす珟圚の゚ディションはRust2021です。以前はRust2015ず" "Rust2018でした。\n" "\n" " * ゚ディションでは、埌方非互換な倉曎を加える事ができたす。\n" "\n" " * コヌドの砎損を防ぐために、゚ディションはオプトむン方匏です`Cargo.toml`で、クレヌトに察しお適" "甚したい゚ディションを遞択したす。\n" "\n" " * ゚コシステムの分断を避けるために、コンパむラは異なる゚ディションのコヌドを混圚させる事ができた" "す。\n" "\n" " * コンパむラを盎接䜿甚する事は非垞に皀であり、基本的には`cargo`を介したす。\n" "\n" " * `Cargo`は非垞に包括的なツヌルであり、倚くの機胜を備えおいたす\n" " * プロゞェクト・パッケヌゞの構造管理\n" " * [workspaces]ワヌクスペヌス\n" " * 開発甚ずランタむム甚の䟝存関係管理・キャッシュ\n" " * [build scripting]ビルドスクリプト\n" " * [global installation]\n" " * [cargo clippy]などのサブコマンドプラグむンによる拡匵\n" " * 詳现は[official Cargo Book]を参照しおください。" #: src/cargo/code-samples.md:1 msgid "# Code Samples in This Training" msgstr "# 講座のサンプルコヌド" #: src/cargo/code-samples.md:3 msgid "" "For this training, we will mostly explore the Rust language through examples\n" "which can be executed through your browser. This makes the setup much easier and\n" "ensures a consistent experience for everyone." msgstr "" "本講座は、䞻にブラりザ内で実行可胜な䟋を䜿いたす。こうする事で、セットアップが容易になり、䞀貫した" "開発環境の提䟛が可胜ずなりたす。" #: src/cargo/code-samples.md:7 msgid "" "Installing Cargo is still encouraged: it will make it easier for you to do the\n" "exercises. On the last day, we will do a larger exercise which shows you how to\n" "work with dependencies and for that you need Cargo." msgstr "" "ただし、できればCargoをむンストヌルしおください 緎習問題で䜿えるず䟿利です。たた最終日に䟝存関係" "を扱う課題を扱いたすが、そこではCargoが必芁になりたす。" #: src/cargo/code-samples.md:11 msgid "The code blocks in this course are fully interactive:" msgstr "講座のコヌドブロックはむンタラクティブです" #: src/cargo/code-samples.md:13 msgid "" "```rust,editable\n" "fn main() {\n" " println!(\"Edit me!\");\n" "}\n" "```" msgstr "" #: src/cargo/code-samples.md:19 msgid "" "You can use Ctrl + Enter to execute the code when focus is in the\n" "text box." msgstr "ボックス内にフォヌカスがある状態でCtrl + Enterを抌すず、コヌドが実行されたす。" #: src/cargo/code-samples.md:24 msgid "" "Most code samples are editable like shown above. A few code samples\n" "are not editable for various reasons:" msgstr "" "ほずんどのサンプルコヌドは䞊蚘のように線集可胜ですが、䞀郚だけ以䞋のような理由から線集䞍可ずなっお" "いたす" #: src/cargo/code-samples.md:27 msgid "" "* The embedded playgrounds cannot execute unit tests. Copy-paste the\n" " code and open it in the real Playground to demonstrate unit tests.\n" "\n" "* The embedded playgrounds lose their state the moment you navigate\n" " away from the page! This is the reason that the students should\n" " solve the exercises using a local Rust installation or via the\n" " Playground." msgstr "" "* 講座のペヌゞ内に埋め蟌たれたプレむグラりンドでナニットテストは実行できたせん。コヌドを実際のプレ" "むグラりンドで開き、デモンストレヌションを行う必芁がありたす。\n" "\n" "* 講座のペヌゞ内に埋め蟌たれたプレむグラりンドでは、ペヌゞ移動するず状態が倱われたす故に、受講生" "はロヌカル環境や実際のプレむグラりンドを䜿甚しお問題を解く必芁がありたす。" #: src/cargo/running-locally.md:1 msgid "# Running Code Locally with Cargo" msgstr "# Cargoを䜿っおロヌカルで実行" #: src/cargo/running-locally.md:3 msgid "" "If you want to experiment with the code on your own system, then you will need\n" "to first install Rust. Do this by following the [instructions in the Rust\n" "Book][1]. This should give you a working `rustc` and `cargo`. At the time of\n" "writing, the latest stable Rust release has these version numbers:" msgstr "" "コヌドをロヌカルで詊したい堎合、[Rust Bookの手順][1]に埓っおRustをむンストヌルしおください。正垞に" "むンストヌルされたら、`rustc`ず`cargo`が䜿えるようになりたす。最新のstableリリヌスのバヌゞョンは以" "䞋の通りです" #: src/cargo/running-locally.md:8 msgid "" "```shell\n" "% rustc --version\n" "rustc 1.61.0 (fe5b13d68 2022-05-18)\n" "% cargo --version\n" "cargo 1.61.0 (a028ae4 2022-04-29)\n" "```" msgstr "" #: src/cargo/running-locally.md:15 msgid "" "With this is in place, then follow these steps to build a Rust binary from one\n" "of the examples in this training:" msgstr "次に、本講座の䟋を参考にしながら、以䞋の手順に埓っおRustのバむナリをビルドしおください" #: src/cargo/running-locally.md:18 msgid "" "1. Click the \"Copy to clipboard\" button on the example you want to copy.\n" "\n" "2. Use `cargo new exercise` to create a new `exercise/` directory for your code:\n" "\n" " ```shell\n" " $ cargo new exercise\n" " Created binary (application) `exercise` package\n" " ```\n" "\n" "3. Navigate into `exercise/` and use `cargo run` to build and run your binary:\n" "\n" " ```shell\n" " $ cd exercise\n" " $ cargo run\n" " Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)\n" " Finished dev [unoptimized + debuginfo] target(s) in 0.75s\n" " Running `target/debug/exercise`\n" " Hello, world!\n" " ```\n" "\n" "4. Replace the boiler-plate code in `src/main.rs` with your own code. For\n" " example, using the example on the previous page, make `src/main.rs` look like\n" "\n" " ```rust\n" " fn main() {\n" " println!(\"Edit me!\");\n" " }\n" " ```\n" "\n" "5. Use `cargo run` to build and run your updated binary:\n" "\n" " ```shell\n" " $ cargo run\n" " Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)\n" " Finished dev [unoptimized + debuginfo] target(s) in 0.24s\n" " Running `target/debug/exercise`\n" " Edit me!\n" " ```\n" "\n" "6. Use `cargo check` to quickly check your project for errors, use `cargo build`\n" " to compile it without running it. You will find the output in `target/debug/`\n" " for a normal debug build. Use `cargo build --release` to produce an optimized\n" " release build in `target/release/`.\n" "\n" "7. You can add dependencies for your project by editing `Cargo.toml`. When you\n" " run `cargo` commands, it will automatically download and compile missing\n" " dependencies for you." msgstr "" "1. 「Copy to clipboard」でコヌドをコピヌ。\n" "\n" "2. `cargo new exercise`で`exercise/`ディレクトリを䜜成\n" "\n" " ```shell\n" " $ cargo new exercise\n" " Created binary (application) `exercise` package\n" " ```\n" "\n" "3. `exercise/`ディレクトリに移動し、`cargo run`でバむナリをビルドしお実行\n" "\n" " ```shell\n" " $ cd exercise\n" " $ cargo run\n" " Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)\n" " Finished dev [unoptimized + debuginfo] target(s) in 0.75s\n" " Running `target/debug/exercise`\n" " Hello, world!\n" " ```\n" "\n" "4. `src/main.rs`のボむラヌプレヌトコヌドを、コピヌしたコヌドで眮き換えおください。䟋えば、前のペヌ" "ゞの䟋を䜿った堎合、`src/main.rs`は以䞋のようになりたす。\n" "\n" " ```rust\n" " fn main() {\n" " println!(\"Edit me!\");\n" " }\n" " ```\n" "\n" "5. `cargo run`で曎新されたバむナリをビルドしお実行\n" "\n" " ```shell\n" " $ cargo run\n" " Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)\n" " Finished dev [unoptimized + debuginfo] target(s) in 0.24s\n" " Running `target/debug/exercise`\n" " Edit me!\n" " ```\n" "\n" "6. `cargo check`でプロゞェクトの゚ラヌチェックを行い、`cargo build`でコンパむルだけ実行はせずを" "行いたす。通垞のデバッグビルドでは、生成されたファむルは`target/debug/`に栌玍されたす。最適化された" "リリヌスビルドには`cargo build —release`を䜿い、ファむルは`target/release/`に栌玍されたす。\n" "\n" "7. プロゞェクトに䟝存関係を远加するには、`Cargo.toml`を線集したす。その埌、`cargo`コマンドを実行す" "るず、自動的に䞍足しおいる䟝存関係がダりンロヌドされおコンパむルされたす。" #: src/cargo/running-locally.md:70 msgid "" "Try to encourage the class participants to install Cargo and use a\n" "local editor. It will make their life easier since they will have a\n" "normal development environment." msgstr "" "受講者にCargoのむンストヌルずロヌカル゚ディタの䜿甚を勧めおください。通垞の開発環境を持぀事で、䜜業" "がスムヌズになりたす。" #: src/welcome-day-1.md:1 msgid "# Welcome to Day 1" msgstr "# Day 1ぞようこそ" #: src/welcome-day-1.md:3 msgid "" "This is the first day of Comprehensive Rust. We will cover a lot of ground\n" "today:" msgstr "「Comprehensive Rust」の初日です。本日は倚岐にわたる内容をカバヌしたす" #: src/welcome-day-1.md:6 msgid "" "* Basic Rust syntax: variables, scalar and compound types, enums, structs,\n" " references, functions, and methods.\n" "\n" "* Memory management: stack vs heap, manual memory management, scope-based memory\n" " management, and garbage collection.\n" "\n" "* Ownership: move semantics, copying and cloning, borrowing, and lifetimes." msgstr "" "* Rustの基本的な構文 倉数、スカラヌ型ず耇合型、列挙型、構造䜓、参照、関数、メ゜ッド。\n" "\n" "* メモリ管理 スタック vs ヒヌプ、手動でのメモリ管理、スコヌプに基づくメモリ管理、ガベヌゞコレク" "ション。\n" "\n" "* 所有暩 ムヌブセマンティクス、コピヌずクロヌン、借甚、ラむフタむム。" #: src/welcome-day-1.md:16 msgid "Please remind the students that:" msgstr "受講生に䌝えおください" #: src/welcome-day-1.md:18 msgid "" "* They should ask questions when they get them, don't save them to the end.\n" "* The class is meant to be interactive and discussions are very much encouraged!\n" " * As an instructor, you should try to keep the discussions relevant, i.e.,\n" " keep the related to how Rust does things vs some other language. It can be\n" " hard to find the right balance, but err on the side of allowing discussions\n" " since they engage people much more than one-way communication.\n" "* The questions will likely mean that we talk about things ahead of the slides.\n" " * This is perfectly okay! Repetition is an important part of learning. Remember\n" " that the slides are just a support and you are free to skip them as you\n" " like." msgstr "" "* 分からない事があれば、最埌たで埅たずに質問をしおください。\n" "* 本講座はむンタラクティブな圢匏で行うため、積極的にディスカッションをしおください\n" " * 講垫の方ぞ ディスカッションはなるべく関連性を有する範囲に留めたしょう。䟋えば、他蚀語ずの比范" "を行う堎合には、あくたでもRustずどう違うのかたでを議論の範囲に蚭定しおください。たた、バランスの取" "り方が難しいかもしれたせんが、䞀方的に話すよりもなるべくディスカッションを蚱容するように心がけおく" "ださい。\n" "* 質問があった堎合、おそらく将来的に話す内容に觊れる事になりたす。\n" " * これは党く問題ありたせん埩習は孊びの重芁な芁玠です。スラむドはあくたでもサポヌトずしお甚意さ" "れおいるものであり、ご自身の刀断でスキップも可胜です。" #: src/welcome-day-1.md:29 msgid "" "The idea for the first day is to show _just enough_ of Rust to be able to speak\n" "about the famous borrow checker. The way Rust handles memory is a major feature\n" "and we should show students this right away." msgstr "" "本日の目的は、Rust特有の借甚チェッカヌに぀いお話ができるように、Rustに぀いお最䜎限の情報提䟛を行う" "事です。Rustがメモリをどのように扱うかは重芁な機胜であり、なるべく早く受講生に説明すべき内容です。" #: src/welcome-day-1.md:33 msgid "" "If you're teaching this in a classroom, this is a good place to go over the\n" "schedule. We suggest splitting the day into two parts (following the slides):" msgstr "" "この時点でスケゞュヌル確認を行なっおください。以䞋のように1日をパヌトに分けお実斜する事を掚奚しお" "いたす" #: src/welcome-day-1.md:36 msgid "" "* Morning: 9:00 to 12:00,\n" "* Afternoon: 13:00 to 16:00." msgstr "" "* AM 9:00 ~ 12:00\n" "* PM 13:00 ~ 16:00" #: src/welcome-day-1.md:39 msgid "" "You can of course adjust this as necessary. Please make sure to include breaks,\n" "we recommend a break every hour!" msgstr "必芁に応じお調敎しおください。たた、1時間ごずに䌑憩を取る事をおすすめしたす" #: src/welcome-day-1/what-is-rust.md:1 msgid "# What is Rust?" msgstr "# Rustずは" #: src/welcome-day-1/what-is-rust.md:3 msgid "Rust is a new programming language which had its [1.0 release in 2015][1]:" msgstr "Rustは[2015幎に1.0版がリリヌス][1]された新しいプログラミング蚀語です" #: src/welcome-day-1/what-is-rust.md:5 msgid "" "* Rust is a statically compiled language in a similar role as C++\n" " * `rustc` uses LLVM as its backend.\n" "* Rust supports many [platforms and\n" " architectures](https://doc.rust-lang.org/nightly/rustc/platform-support.html):\n" " * x86, ARM, WebAssembly, ...\n" " * Linux, Mac, Windows, ...\n" "* Rust is used for a wide range of devices:\n" " * firmware and boot loaders,\n" " * smart displays,\n" " * mobile phones,\n" " * desktops,\n" " * servers." msgstr "" "* RustはC++ず同様に、静的にコンパむルされる蚀語です\n" " * `rustc`はバック゚ンドにLLVMを䜿甚しおいたす。\n" "* Rustは倚くの[プラットフォヌムずアヌキテクチャ](https://doc.rust-lang.org/nightly/rustc/platform-" "support.html)をサポヌトしおいたす\n" " * x86, ARM, WebAssembly, 
\n" " * Linux, Mac, Windows, 
\n" "* Rustは様々なデバむスで䜿甚されおいたす\n" " * ファヌムりェアやブヌトロヌダ\n" " * スマヌトディスプレむ\n" " * 携垯電話\n" " * デスクトップ\n" " * サヌバ" #: src/welcome-day-1/what-is-rust.md:21 msgid "Rust fits in the same area as C++:" msgstr "RustずC++が䌌おいるずころ:" #: src/welcome-day-1/what-is-rust.md:23 msgid "" "* High flexibility.\n" "* High level of control.\n" "* Can be scaled down to very constrained devices like mobile phones.\n" "* Has no runtime or garbage collection.\n" "* Focuses on reliability and safety without sacrificing performance." msgstr "" "* 高い柔軟性\n" "* 高床な制埡性\n" "* 携垯電話のようなデバむスにたでスケヌルダりンが可胜\n" "* ランタむムやガベヌゞコレクションがない\n" "* パフォヌマンスを犠牲にせず、信頌性ず安党性に焊点を圓おおいる" #: src/hello-world.md:1 msgid "# Hello World!" msgstr "" #: src/hello-world.md:3 msgid "" "Let us jump into the simplest possible Rust program, a classic Hello World\n" "program:" msgstr "さっそく䞀番シンプルなプログラムである定番のHello Worldからみおみたしょう" #: src/hello-world.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " println!(\"Hello 🌍!\");\n" "}\n" "```" msgstr "" #: src/hello-world.md:12 msgid "What you see:" msgstr "プログラムの䞭身" #: src/hello-world.md:14 msgid "" "* Functions are introduced with `fn`.\n" "* Blocks are delimited by curly braces like in C and C++.\n" "* The `main` function is the entry point of the program.\n" "* Rust has hygienic macros, `println!` is an example of this.\n" "* Rust strings are UTF-8 encoded and can contain any Unicode character." msgstr "" "* 関数は`fn`で導入されたす。\n" "* CやC++ず同様に、ブロックは波括匧で囲みたす。\n" "* `main`関数はプログラムの゚ントリヌポむントになりたす。\n" "* Rustには衛生的なマクロがあり、`println!`はその䞀䟋です。\n" "* Rustの文字列はUTF-8で゚ンコヌドされ、どんなUnicode文字でも含む事ができたす。" #: src/hello-world.md:22 msgid "" "This slide tries to make the students comfortable with Rust code. They will see\n" "a ton of it over the next four days so we start small with something familiar." msgstr "" "このスラむドの目的は、Rustのコヌドに慣れおもらう事です。この4日間で倧量のRustコヌドを芋る事になるの" "で、銎染みのあるものから始めおみたしょう。" #: src/hello-world.md:27 msgid "" "* Rust is very much like other languages in the C/C++/Java tradition. It is\n" " imperative (not functional) and it doesn't try to reinvent things unless\n" " absolutely necessary.\n" "\n" "* Rust is modern with full support for things like Unicode.\n" "\n" "* Rust uses macros for situations where you want to have a variable number of\n" " arguments (no function [overloading](basic-syntax/functions-interlude.md)).\n" "\n" "* Macros being 'hygienic' means they don't accidentally capture identifiers from\n" " the scope they are used in. Rust macros are actually only\n" " [partially hygenic](https://veykril.github.io/tlborm/decl-macros/minutiae/hygiene.html)." msgstr "" "* Rustは、C/C++/Java系統の蚀語によく䌌おいたす。Rustは、呜什型関数型ではなくであり、必須でない" "限り機胜の再発明はしたせん。\n" "\n" "* RustはUnicodeなどにも完党に察応しおいる珟代的な蚀語です。\n" "\n" "* Rustで可倉長匕数を甚いたい堎合は、マクロを䜿甚したす(関数[オヌバヌロヌド](basic-syntax/functions-" "interlude.md)はありたせん)。\n" "\n" "* マクロが「衛生的 (hygienic)」であるずは、そのマクロが呌び出されるスコヌプにある識別子ず、そのマク" "ロ内郚の識別子が衝突しないこずが保蚌されおいるこずを蚀いたす。Rustのマクロは、実際には[郚分的にしか" "衛生的](https://veykril.github.io/tlborm/decl-macros/minutiae/hygiene.html)ではありたせん。" #: src/hello-world/small-example.md:1 msgid "# Small Example" msgstr "" #: src/hello-world/small-example.md:3 msgid "Here is a small example program in Rust:" msgstr "ここでは、Rustによる小さなサンプルプログラムを玹介したす" #: src/hello-world/small-example.md:5 msgid "" "```rust,editable\n" "fn main() { // Program entry point\n" " let mut x: i32 = 6; // Mutable variable binding\n" " print!(\"{x}\"); // Macro for printing, like printf\n" " while x != 1 { // No parenthesis around expression\n" " if x % 2 == 0 { // Math like in other languages\n" " x = x / 2;\n" " } else {\n" " x = 3 * x + 1;\n" " }\n" " print!(\" -> {x}\");\n" " }\n" " println!();\n" "}\n" "```" msgstr "" "```rust,editable\n" "fn main() { // プログラムの゚ントリヌポむント\n" " let mut x: i32 = 6; // 可倉倉数のバむンディング\n" " print!(\"{x}\"); // printfのような、出力甚マクロ\n" " while x != 1 { // 匏を囲む括匧は䞍芁\n" " if x % 2 == 0 { // 他の蚀語ず同様の挔算\n" " x = x / 2;\n" " } else {\n" " x = 3 * x + 1;\n" " }\n" " print!(\" -> {x}\");\n" " }\n" " println!();\n" "}\n" "```" #: src/hello-world/small-example.md:23 msgid "" "The code implements the Collatz conjecture: it is believed that the loop will\n" "always end, but this is not yet proved. Edit the code and play with different\n" "inputs." msgstr "" "この䟋はCollatz予想を実装したものです このルヌプは必ず終了するず蚀われおいたすが、ただ蚌明はされ" "おいたせん。コヌドを線集しお、異なる入力倀で詊しおみおください。" #: src/hello-world/small-example.md:29 msgid "" "* Explain that all variables are statically typed. Try removing `i32` to trigger\n" " type inference. Try with `i8` instead and trigger a runtime integer overflow.\n" "\n" "* Change `let mut x` to `let x`, discuss the compiler error.\n" "\n" "* Show how `print!` gives a compilation error if the arguments don't match the\n" " format string.\n" "\n" "* Show how you need to use `{}` as a placeholder if you want to print an\n" " expression which is more complex than just a single variable.\n" "\n" "* Show the students the standard library, show them how to search for `std::fmt`\n" " which has the rules of the formatting mini-language. It's important that the\n" " students become familiar with searching in the standard library." msgstr "" "* すべおの倉数が静的型付けされおいる事を説明しおください。`i32`を削陀しお型掚論を詊しおください。代" "わりに`i8`を䜿甚しお、実行時に敎数オヌバヌフロヌを匕き起こしおみおください。\n" "\n" "* `let mut x`を`let x`に倉曎し、コンパむル゚ラヌに぀いお説明しおください。\n" "\n" "* `print!`の匕数がフォヌマット文字列ず䞀臎しない堎合、コンパむル゚ラヌが発生する事を実挔しおくださ" "い。\n" "\n" "* 単䞀の倉数よりも耇雑な匏を衚瀺したい堎合は、`{}`をプレヌスホルダずしお䜿甚する必芁がある事を実挔" "しおください。\n" "\n" "* 受講生に暙準ラむブラリを玹介し、`std::fmt`の怜玢方法を説明しおください。`std::fmt`には、フォヌ" "マット機胜のルヌルや構文が説明されおいたす。受講者が暙準ラむブラリの怜玢に慣れおおく事は重芁です。" #: src/why-rust.md:1 msgid "# Why Rust?" msgstr "" #: src/why-rust.md:3 msgid "Some unique selling points of Rust:" msgstr "Rustのナニヌクなセヌルスポむントをいく぀か玹介したす" #: src/why-rust.md:5 msgid "" "* Compile time memory safety.\n" "* Lack of undefined runtime behavior.\n" "* Modern language features." msgstr "" "* コンパむル時のメモリ安党性。\n" "* 未定矩の実行時動䜜がない。\n" "* 珟代的な蚀語機胜。" #: src/why-rust.md:11 msgid "" "Make sure to ask the class which languages they have experience with. Depending\n" "on the answer you can highlight different features of Rust:" msgstr "" "受講者にどの蚀語の経隓があるかを尋ねおください。回答に応じお、Rustのさたざたな特城を匷調するこずが" "できたす" #: src/why-rust.md:14 msgid "" "* Experience with C or C++: Rust eliminates a whole class of _runtime errors_\n" " via the borrow checker. You get performance like in C and C++, but you don't\n" " have the memory unsafety issues. In addition, you get a modern language with\n" " constructs like pattern matching and built-in dependency management.\n" "\n" "* Experience with Java, Go, Python, JavaScript...: You get the same memory safety\n" " as in those languages, plus a similar high-level language feeling. In addition\n" " you get fast and predictable performance like C and C++ (no garbage collector)\n" " as well as access to low-level hardware (should you need it)" msgstr "" "* CたたはC++の経隓がある堎合 Rustは借甚チェッカヌを介しお実行時゚ラヌの䞀郚を排陀しおくれたす。そ" "れに加え、CやC++ず同等のパフォヌマンスを埗るこずができ、メモリ安党性の問題はありたせん。さらに、パ" "タヌンマッチングや組み蟌みの䟝存関係管理などの構造芁玠を含む珟代的な蚀語です。\n" "\n" "* Java、Go、Python、JavaScriptなどの経隓がある堎合 これらの蚀語ず同様のメモリ安党性ず、高氎準蚀語" "に近い感芚を埗るこずができたす。たた、CやC++のように高速か぀予枬可胜なパフォヌマンスガベヌゞコレ" "クタがないを埗るこずができ、必芁なら䜎氎準なハヌドりェアぞのアクセスも可胜です" #: src/why-rust/compile-time.md:1 msgid "# Compile Time Guarantees" msgstr "# コンパむル時の保蚌" #: src/why-rust/compile-time.md:3 msgid "Static memory management at compile time:" msgstr "コンパむル時の静的メモリの管理" #: src/why-rust/compile-time.md:5 msgid "" "* No uninitialized variables.\n" "* No memory leaks (_mostly_, see notes).\n" "* No double-frees.\n" "* No use-after-free.\n" "* No `NULL` pointers.\n" "* No forgotten locked mutexes.\n" "* No data races between threads.\n" "* No iterator invalidation." msgstr "" "* 未初期化の倉数がない。\n" "* メモリリヌクの心配がほずんどない (ノヌトを参照)。\n" "* 二重解攟が起きない。\n" "* 解攟枈みメモリ䜿甚use-after-freeがない。\n" "* `NULL`ヌルポむンタがない。\n" "* ミュヌテックスmutexのロックの解陀忘れがない。\n" "* スレッド間でデヌタ競合しない。\n" "* むテレヌタが無効化されない。" #: src/why-rust/compile-time.md:16 msgid "" "It is possible to produce memory leaks in (safe) Rust. Some examples\n" "are:" msgstr "" "SafeなRustの範囲内でメモリリヌクを匕き起こすこずは可胜です。䟋ずしお以䞋のような手段がありたす" #: src/why-rust/compile-time.md:19 msgid "" "* You can for use [`Box::leak`] to leak a pointer. A use of this could\n" " be to get runtime-initialized and runtime-sized static variables\n" "* You can use [`std::mem::forget`] to make the compiler \"forget\" about\n" " a value (meaning the destructor is never run).\n" "* You can also accidentally create a [reference cycle] with `Rc` or\n" " `Arc`.\n" "* In fact, some will consider infinitely populating a collection a memory\n" " leak and Rust does not protect from those." msgstr "" "* [`Box::leak`]を䜿っおポむンタをリヌクさせるこずができたす。この関数は実行時に初期化され、実行時に" "サむズが決たるstatic倉数の取埗などに䜿われたす。\n" "* [`std::mem::forget`]を䜿っお、コンパむラに倀を忘れさせるこずができたす (぀たり、デストラクタが実" "行されない)。\n" "* `Rc`や`Arc`を䜿っお[埪環参照reference cycle]を誀っお䜜成するこずがありたす。\n" "* コレクションを無限に拡匵し続けるこずをメモリリヌクず芋なす堎合があり、Rustにはこれを防ぐ機胜はあ" "りたせん。" #: src/why-rust/compile-time.md:28 msgid "" "For the purpose of this course, \"No memory leaks\" should be understood\n" "as \"Pretty much no *accidental* memory leaks\"." msgstr "" "本講座での「メモリリヌクが起きない」は「*意図しない*メモリリヌクはほずんど起きない」ず解釈すべきで" "す。" #: src/why-rust/runtime.md:1 msgid "# Runtime Guarantees" msgstr "# 実行時の保蚌" #: src/why-rust/runtime.md:3 msgid "No undefined behavior at runtime:" msgstr "実行時に未定矩の動䜜はありたせん" #: src/why-rust/runtime.md:5 msgid "" "* Array access is bounds checked.\n" "* Integer overflow is defined." msgstr "" "* 配列ぞのアクセスには境界チェックが行われる。\n" "* 敎数オヌバヌフロヌの挙動が定矩されおいる。" #: src/why-rust/runtime.md:12 msgid "" "* Integer overflow is defined via a compile-time flag. The options are\n" " either a panic (a controlled crash of the program) or wrap-around\n" " semantics. By default, you get panics in debug mode (`cargo build`)\n" " and wrap-around in release mode (`cargo build --release`).\n" "\n" "* Bounds checking cannot be disabled with a compiler flag. It can also\n" " not be disabled directly with the `unsafe` keyword. However,\n" " `unsafe` allows you to call functions such as `slice::get_unchecked`\n" " which does not do bounds checking." msgstr "" "* 敎数オヌバヌフロヌは、コンパむル時のフラグで定矩されたす。遞択肢ずしお、パニックプログラムの制" "埡されたクラッシュたたはラップアラりンドのセマンティクスがありたす。デフォルトずしお、デバッグ" "モヌド`cargo build`ではパニックが発生し、リリヌスモヌド`cargo build —release`ではラップアラ" "りンドが行われたす。\n" "\n" "* 境界チェックは、コンパむル時のフラグで無効にするこずはできたせん。たた、`unsafe`のキヌワヌドを" "䜿っお盎接無効にするこずもできたせん。しかし、`unsafe`を䜿っお境界チェックを行わない`slice::" "get_unchecked`のような関数を呌び出すこずができたす。" #: src/why-rust/modern.md:1 msgid "# Modern Features" msgstr "# 珟代的な機胜" #: src/why-rust/modern.md:3 msgid "Rust is built with all the experience gained in the last 40 years." msgstr "Rustは過去40幎間の経隓を基に構築されおいたす。" #: src/why-rust/modern.md:5 msgid "## Language Features" msgstr "## 蚀語の特城" #: src/why-rust/modern.md:7 msgid "" "* Enums and pattern matching.\n" "* Generics.\n" "* No overhead FFI.\n" "* Zero-cost abstractions." msgstr "" "* 列挙型ずパタヌンマッチング\n" "* ゞェネリクス\n" "* オヌバヌヘッドのないFFI\n" "* れロコスト抜象化" #: src/why-rust/modern.md:12 msgid "## Tooling" msgstr "" #: src/why-rust/modern.md:14 msgid "" "* Great compiler errors.\n" "* Built-in dependency manager.\n" "* Built-in support for testing.\n" "* Excellent Language Server Protocol support." msgstr "" "* 優秀なコンパむル゚ラヌ。\n" "* 組み蟌みの䟝存関係マネヌゞャ。\n" "* 組み蟌みのテストサポヌト。\n" "* Language Server ProtocolLSPのサポヌト。" #: src/why-rust/modern.md:23 msgid "" "* Zero-cost abstractions, similar to C++, means that you don't have to 'pay'\n" " for higher-level programming constructs with memory or CPU. For example,\n" " writing a loop using `for` should result in roughly the same low level\n" " instructions as using the `.iter().fold()` construct.\n" "\n" "* It may be worth mentioning that Rust enums are 'Algebraic Data Types', also\n" " known as 'sum types', which allow the type system to express things like\n" " `Option` and `Result`.\n" "\n" "* Remind people to read the errors --- many developers have gotten used to\n" " ignore lengthy compiler output. The Rust compiler is significantly more\n" " talkative than other compilers. It will often provide you with _actionable_\n" " feedback, ready to copy-paste into your code.\n" "\n" "* The Rust standard library is small compared to languages like Java, Python,\n" " and Go. Rust does not come with several things you might consider standard and\n" " essential:\n" "\n" " * a random number generator, but see [rand].\n" " * support for SSL or TLS, but see [rusttls].\n" " * support for JSON, but see [serde_json].\n" "\n" " The reasoning behind this is that functionality in the standard library cannot\n" " go away, so it has to be very stable. For the examples above, the Rust\n" " community is still working on finding the best solution --- and perhaps there\n" " isn't a single \"best solution\" for some of these things.\n" "\n" " Rust comes with a built-in package manager in the form of Cargo and this makes\n" " it trivial to download and compile third-party crates. A consequence of this\n" " is that the standard library can be smaller.\n" "\n" " Discovering good third-party crates can be a problem. Sites like\n" " help with this by letting you compare health metrics for\n" " crates to find a good and trusted one.\n" " \n" "* [rust-analyzer] is a well supported LSP implementation used in major\n" " IDEs and text editors." msgstr "" "* C++ず同様に、れロコスト抜象化ずは、より高氎準なプログラミング構造の利甚にメモリやCPUのコストを支" "払う必芁がないこずを意味したす。䟋えば、`for`を䜿ったルヌプの堎合、`iter().fold()`構文を䜿った堎合" "ずおおよそ同じ䜎氎準の凊理になりたす。\n" "\n" "* Rustの列挙型は「代数的デヌタ型」であり、「盎和型」ず呌ばれたす。`Option`や`Result`のよう" "な芁玠を衚珟するこずができたす。\n" "\n" "* ゚ラヌをちゃんず確認するよう泚意しおください。倚くの開発者は、長いコンパむラ出力を無芖するこずに" "慣れおしたっおいたす。Rustのコンパむラは他のコンパむラよりもわかりやすく実甚的なフィヌドバックを提" "䟛しおくれたす。そしお倚くの堎合、コヌドにそのたたコピペできるようなフィヌドバックが提䟛された" "す。\n" "\n" "* Rustの暙準ラむブラリは、Java、Python、Goなどのそれず比べるず小芏暡です。Rustには暙準的か぀必須ず" "思われるいく぀かの機胜が含たれおいたせん\n" "\n" " * 乱数生成噚。[rand]を確認しおください。\n" " * SSLやTLSのサポヌト。[rusttls]を確認しおください。\n" " * JSONのサポヌト。[serde_json]を確認しおください。 \n" "\n" " この理由は、暙準ラむブラリの機胜は消えるこずがなく、非垞に安定したものでなければならないからで" "す。䞊蚘の䟋に぀いおは、Rustコミュニティが未だに最適な解決策を探し続けおいたす。そもそも、これらに" "察する「最適解」は䞀぀であるずは限らないのです。\n" "\n" " Rustには、Cargoずいう倖郚クレヌトのダりンロヌドからコンパむルたでを簡単に行っおくれるパッケヌゞマ" "ネヌゞャが組み蟌たれおいたす。これにより、暙準ラむブラリを小芏暡に保぀こずができおいたす。\n" "\n" " 良い倖郚クレヌトを芋぀けるのは難しいずきがありたす。のようなサむトを䜿うこずで、" "クレヌトの評䟡基準を参考にしながら比范を行うこずができたす。\n" " \n" "* [rust-analyzer]は、䞻芁IDEやテキスト゚ディタで䜿甚できる、サポヌトが充実しおいるLSPの実装です。" #: src/basic-syntax.md:1 msgid "# Basic Syntax" msgstr "" #: src/basic-syntax.md:3 msgid "Much of the Rust syntax will be familiar to you from C, C++ or Java:" msgstr "" #: src/basic-syntax.md:5 msgid "" "* Blocks and scopes are delimited by curly braces.\n" "* Line comments are started with `//`, block comments are delimited by `/* ...\n" " */`.\n" "* Keywords like `if` and `while` work the same.\n" "* Variable assignment is done with `=`, comparison is done with `==`." msgstr "" #: src/basic-syntax/scalar-types.md:1 msgid "# Scalar Types" msgstr "" #: src/basic-syntax/scalar-types.md:3 msgid "" "| | Types | " "Literals |\n" "|------------------------|--------------------------------------------|-------------------------------|\n" "| Signed integers | `i8`, `i16`, `i32`, `i64`, `i128`, `isize` | `-10`, `0`, `1_000`, " "`123i64` |\n" "| Unsigned integers | `u8`, `u16`, `u32`, `u64`, `u128`, `usize` | `0`, `123`, " "`10u16` |\n" "| Floating point numbers | `f32`, `f64` | `3.14`, `-10.0e20`, " "`2f32` |\n" "| Strings | `&str` | `\"foo\"`, " "`\"two\\nlines\"` |\n" "| Unicode scalar values | `char` | `'a'`, `'α'`, " "`'∞'` |\n" "| Booleans | `bool` | `true`, " "`false` |" msgstr "" #: src/basic-syntax/scalar-types.md:12 msgid "The types have widths as follows:" msgstr "" #: src/basic-syntax/scalar-types.md:14 msgid "" "* `iN`, `uN`, and `fN` are _N_ bits wide,\n" "* `isize` and `usize` are the width of a pointer,\n" "* `char` is 32 bit wide,\n" "* `bool` is 8 bit wide." msgstr "" #: src/basic-syntax/scalar-types.md:21 msgid "There are a few syntaxes which are not shown above:" msgstr "" #: src/basic-syntax/scalar-types.md:23 msgid "" "- Raw strings allow you to create a `&str` value with escapes disabled: `r\"\\n\"\n" " == \"\\\\\\\\n\"`. You can embed double-quotes by using an equal amount of `#` on\n" " either side of the quotes:\n" "\n" " ```rust,editable\n" " fn main() {\n" " println!(r#\"link\"#);\n" " println!(\"link\");\n" " }\n" " ```\n" "\n" "- Byte strings allow you to create a `&[u8]` value directly:\n" "\n" " ```rust,editable\n" " fn main() {\n" " println!(\"{:?}\", b\"abc\");\n" " println!(\"{:?}\", &[97, 98, 99]);\n" " }\n" " ```" msgstr "" #: src/basic-syntax/compound-types.md:1 msgid "# Compound Types" msgstr "" #: src/basic-syntax/compound-types.md:3 msgid "" "| | Types | Literals |\n" "|--------|-------------------------------|-----------------------------------|\n" "| Arrays | `[T; N]` | `[20, 30, 40]`, `[0; 3]` |\n" "| Tuples | `()`, `(T,)`, `(T1, T2)`, ... | `()`, `('x',)`, `('x', 1.2)`, ... |" msgstr "" #: src/basic-syntax/compound-types.md:8 msgid "Array assignment and access:" msgstr "" #: src/basic-syntax/compound-types.md:10 msgid "" "```rust,editable\n" "fn main() {\n" " let mut a: [i8; 10] = [42; 10];\n" " a[5] = 0;\n" " println!(\"a: {:?}\", a);\n" "}\n" "```" msgstr "" #: src/basic-syntax/compound-types.md:18 msgid "Tuple assignment and access:" msgstr "" #: src/basic-syntax/compound-types.md:20 msgid "" "```rust,editable\n" "fn main() {\n" " let t: (i8, bool) = (7, true);\n" " println!(\"1st index: {}\", t.0);\n" " println!(\"2nd index: {}\", t.1);\n" "}\n" "```" msgstr "" #: src/basic-syntax/compound-types.md:32 msgid "Arrays:" msgstr "" #: src/basic-syntax/compound-types.md:34 msgid "" "* Arrays have elements of the same type, `T`, and length, `N`, which is a compile-time constant.\n" " Note that the length of the array is *part of its type*, which means that `[u8; 3]` and\n" " `[u8; 4]` are considered two different types.\n" "\n" "* We can use literals to assign values to arrays.\n" "\n" "* In the main function, the print statement asks for the debug implementation with the `?` format\n" " parameter: `{}` gives the default output, `{:?}` gives the debug output. We\n" " could also have used `{a}` and `{a:?}` without specifying the value after the\n" " format string.\n" "\n" "* Adding `#`, eg `{a:#?}`, invokes a \"pretty printing\" format, which can be easier to read." msgstr "" #: src/basic-syntax/compound-types.md:47 msgid "Tuples:" msgstr "" #: src/basic-syntax/compound-types.md:49 msgid "" "* Like arrays, tuples have a fixed length.\n" "\n" "* Tuples group together values of different types into a compound type.\n" "\n" "* Fields of a tuple can be accessed by the period and the index of the value, e.g. `t.0`, `t.1`.\n" "\n" "* The empty tuple `()` is also known as the \"unit type\". It is both a type, and\n" " the only valid value of that type - that is to say both the type and its value\n" " are expressed as `()`. It is used to indicate, for example, that a function or\n" " expression has no return value, as we'll see in a future slide. \n" " * You can think of it as `void` that can be familiar to you from other \n" " programming languages." msgstr "" #: src/basic-syntax/references.md:1 msgid "# References" msgstr "" #: src/basic-syntax/references.md:3 msgid "Like C++, Rust has references:" msgstr "" #: src/basic-syntax/references.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let mut x: i32 = 10;\n" " let ref_x: &mut i32 = &mut x;\n" " *ref_x = 20;\n" " println!(\"x: {x}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/references.md:14 msgid "Some notes:" msgstr "" #: src/basic-syntax/references.md:16 msgid "" "* We must dereference `ref_x` when assigning to it, similar to C and C++ pointers.\n" "* Rust will auto-dereference in some cases, in particular when invoking\n" " methods (try `ref_x.count_ones()`).\n" "* References that are declared as `mut` can be bound to different values over their lifetime." msgstr "" #: src/basic-syntax/references.md:25 msgid "" "* Be sure to note the difference between `let mut ref_x: &i32` and `let ref_x:\n" " &mut i32`. The first one represents a mutable reference which can be bound to\n" " different values, while the second represents a reference to a mutable value." msgstr "" #: src/basic-syntax/references-dangling.md:1 msgid "# Dangling References" msgstr "" #: src/basic-syntax/references-dangling.md:3 msgid "Rust will statically forbid dangling references:" msgstr "" #: src/basic-syntax/references-dangling.md:5 msgid "" "```rust,editable,compile_fail\n" "fn main() {\n" " let ref_x: &i32;\n" " {\n" " let x: i32 = 10;\n" " ref_x = &x;\n" " }\n" " println!(\"ref_x: {ref_x}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/references-dangling.md:16 msgid "" "* A reference is said to \"borrow\" the value it refers to.\n" "* Rust is tracking the lifetimes of all references to ensure they live long\n" " enough.\n" "* We will talk more about borrowing when we get to ownership." msgstr "" #: src/basic-syntax/slices.md:1 msgid "# Slices" msgstr "" #: src/basic-syntax/slices.md:3 msgid "A slice gives you a view into a larger collection:" msgstr "" #: src/basic-syntax/slices.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let a: [i32; 6] = [10, 20, 30, 40, 50, 60];\n" " println!(\"a: {a:?}\");\n" "\n" " let s: &[i32] = &a[2..4];\n" " println!(\"s: {s:?}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/slices.md:15 msgid "" "* Slices borrow data from the sliced type.\n" "* Question: What happens if you modify `a[3]`?" msgstr "" #: src/basic-syntax/slices.md:20 msgid "" "* We create a slice by borrowing `a` and specifying the starting and ending indexes in brackets.\n" "\n" "* If the slice starts at index 0, Rust’s range syntax allows us to drop the starting index, " "meaning that `&a[0..a.len()]` and `&a[..a.len()]` are identical.\n" " \n" "* The same is true for the last index, so `&a[2..a.len()]` and `&a[2..]` are identical.\n" "\n" "* To easily create a slice of the full array, we can therefore use `&a[..]`.\n" "\n" "* `s` is a reference to a slice of `i32`s. Notice that the type of `s` (`&[i32]`) no longer " "mentions the array length. This allows us to perform computation on slices of different sizes.\n" " \n" "* Slices always borrow from another object. In this example, `a` has to remain 'alive' (in scope) " "for at least as long as our slice. \n" " \n" "* The question about modifying `a[3]` can spark an interesting discussion, but the answer is that " "for memory safety reasons\n" " you cannot do it through `a` after you created a slice, but you can read the data from both `a` " "and `s` safely. \n" " More details will be explained in the borrow checker section." msgstr "" #: src/basic-syntax/string-slices.md:1 msgid "# `String` vs `str`" msgstr "" #: src/basic-syntax/string-slices.md:3 msgid "We can now understand the two string types in Rust:" msgstr "" #: src/basic-syntax/string-slices.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let s1: &str = \"World\";\n" " println!(\"s1: {s1}\");\n" "\n" " let mut s2: String = String::from(\"Hello \");\n" " println!(\"s2: {s2}\");\n" " s2.push_str(s1);\n" " println!(\"s2: {s2}\");\n" " \n" " let s3: &str = &s2[6..];\n" " println!(\"s3: {s3}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/string-slices.md:20 msgid "Rust terminology:" msgstr "" #: src/basic-syntax/string-slices.md:22 msgid "" "* `&str` an immutable reference to a string slice.\n" "* `String` a mutable string buffer." msgstr "" #: src/basic-syntax/string-slices.md:27 msgid "" "* `&str` introduces a string slice, which is an immutable reference to UTF-8 encoded string data \n" " stored in a block of memory. String literals (`”Hello”`), are stored in the program’s binary.\n" "\n" "* Rust’s `String` type is a wrapper around a vector of bytes. As with a `Vec`, it is owned.\n" " \n" "* As with many other types `String::from()` creates a string from a string literal; `String::" "new()` \n" " creates a new empty string, to which string data can be added using the `push()` and " "`push_str()` methods.\n" "\n" "* The `format!()` macro is a convenient way to generate an owned string from dynamic values. It \n" " accepts the same format specification as `println!()`.\n" " \n" "* You can borrow `&str` slices from `String` via `&` and optionally range selection.\n" " \n" "* For C++ programmers: think of `&str` as `const char*` from C++, but the one that always points \n" " to a valid string in memory. Rust `String` is a rough equivalent of `std::string` from C++ \n" " (main difference: it can only contain UTF-8 encoded bytes and will never use a small-string " "optimization).\n" " " msgstr "" #: src/basic-syntax/functions.md:1 msgid "# Functions" msgstr "" #: src/basic-syntax/functions.md:3 msgid "" "A Rust version of the famous [FizzBuzz](https://en.wikipedia.org/wiki/Fizz_buzz) interview " "question:" msgstr "" #: src/basic-syntax/functions.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " print_fizzbuzz_to(20);\n" "}\n" "\n" "fn is_divisible(n: u32, divisor: u32) -> bool {\n" " if divisor == 0 {\n" " return false;\n" " }\n" " n % divisor == 0\n" "}\n" "\n" "fn fizzbuzz(n: u32) -> String {\n" " let fizz = if is_divisible(n, 3) { \"fizz\" } else { \"\" };\n" " let buzz = if is_divisible(n, 5) { \"buzz\" } else { \"\" };\n" " if fizz.is_empty() && buzz.is_empty() {\n" " return format!(\"{n}\");\n" " }\n" " format!(\"{fizz}{buzz}\")\n" "}\n" "\n" "fn print_fizzbuzz_to(n: u32) {\n" " for i in 1..=n {\n" " println!(\"{}\", fizzbuzz(i));\n" " }\n" "}\n" "```" msgstr "" #: src/basic-syntax/functions.md:35 msgid "" "* We refer in `main` to a function written below. Neither forward declarations nor headers are " "necessary. \n" "* Declaration parameters are followed by a type (the reverse of some programming languages), then " "a return type.\n" "* The last expression in a function body (or any block) becomes the return value. Simply omit the " "`;` at the end of the expression.\n" "* Some functions have no return value, and return the 'unit type', `()`. The compiler will infer " "this if the `-> ()` return type is omitted.\n" "* The range expression in the `for` loop in `print_fizzbuzz_to()` contains `=n`, which causes it " "to include the upper bound." msgstr "" #: src/basic-syntax/rustdoc.md:1 msgid "# Rustdoc" msgstr "" #: src/basic-syntax/rustdoc.md:3 msgid "All language items in Rust can be documented using special `///` syntax." msgstr "" #: src/basic-syntax/rustdoc.md:5 msgid "" "```rust,editable\n" "/// Determine whether the first argument is divisible by the second argument.\n" "///\n" "/// If the second argument is zero, the result is false.\n" "fn is_divisible_by(lhs: u32, rhs: u32) -> bool {\n" " if rhs == 0 {\n" " return false; // Corner case, early return\n" " }\n" " lhs % rhs == 0 // The last expression in a block is the return value\n" "}\n" "```" msgstr "" #: src/basic-syntax/rustdoc.md:17 msgid "" "The contents are treated as Markdown. All published Rust library crates are\n" "automatically documented at [`docs.rs`](https://docs.rs) using the\n" "[rustdoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html) tool. It is\n" "idiomatic to document all public items in an API using this pattern." msgstr "" #: src/basic-syntax/rustdoc.md:24 msgid "" "* Show students the generated docs for the `rand` crate at\n" " [`docs.rs/rand`](https://docs.rs/rand).\n" "\n" "* This course does not include rustdoc on slides, just to save space, but in\n" " real code they should be present.\n" "\n" "* Inner doc comments are discussed later (in the page on modules) and need not\n" " be addressed here." msgstr "" #: src/basic-syntax/methods.md:1 src/methods.md:1 msgid "# Methods" msgstr "" #: src/basic-syntax/methods.md:3 msgid "" "Methods are functions associated with a type. The `self` argument of a method is\n" "an instance of the type it is associated with:" msgstr "" #: src/basic-syntax/methods.md:6 msgid "" "```rust,editable\n" "struct Rectangle {\n" " width: u32,\n" " height: u32,\n" "}\n" "\n" "impl Rectangle {\n" " fn area(&self) -> u32 {\n" " self.width * self.height\n" " }\n" "\n" " fn inc_width(&mut self, delta: u32) {\n" " self.width += delta;\n" " }\n" "}\n" "\n" "fn main() {\n" " let mut rect = Rectangle { width: 10, height: 5 };\n" " println!(\"old area: {}\", rect.area());\n" " rect.inc_width(5);\n" " println!(\"new area: {}\", rect.area());\n" "}\n" "```" msgstr "" #: src/basic-syntax/methods.md:30 msgid "* We will look much more at methods in today's exercise and in tomorrow's class." msgstr "" #: src/basic-syntax/methods.md:34 msgid "" "- Add a `Rectangle::new` constructor and call this from `main`:\n" "\n" " ```rust,editable,compile_fail\n" " fn new(width: u32, height: u32) -> Rectangle {\n" " Rectangle { width, height }\n" " }\n" " ```\n" "\n" "- Add a `Rectangle::new_square(width: u32)` constructor to illustrate that\n" " constructors can take arbitrary parameters." msgstr "" #: src/basic-syntax/functions-interlude.md:1 msgid "# Function Overloading" msgstr "" #: src/basic-syntax/functions-interlude.md:3 msgid "Overloading is not supported:" msgstr "" #: src/basic-syntax/functions-interlude.md:5 msgid "" "* Each function has a single implementation:\n" " * Always takes a fixed number of parameters.\n" " * Always takes a single set of parameter types.\n" "* Default values are not supported:\n" " * All call sites have the same number of arguments.\n" " * Macros are sometimes used as an alternative." msgstr "" #: src/basic-syntax/functions-interlude.md:12 msgid "However, function parameters can be generic:" msgstr "" #: src/basic-syntax/functions-interlude.md:14 msgid "" "```rust,editable\n" "fn pick_one(a: T, b: T) -> T {\n" " if std::process::id() % 2 == 0 { a } else { b }\n" "}\n" "\n" "fn main() {\n" " println!(\"coin toss: {}\", pick_one(\"heads\", \"tails\"));\n" " println!(\"cash prize: {}\", pick_one(500, 1000));\n" "}\n" "```" msgstr "" #: src/basic-syntax/functions-interlude.md:27 msgid "" "* When using generics, the standard library's `Into` can provide a kind of limited\n" " polymorphism on argument types. We will see more details in a later section." msgstr "" #: src/exercises/day-1/morning.md:1 msgid "# Day 1: Morning Exercises" msgstr "" #: src/exercises/day-1/morning.md:3 msgid "In these exercises, we will explore two parts of Rust:" msgstr "" #: src/exercises/day-1/morning.md:5 msgid "" "* Implicit conversions between types.\n" "\n" "* Arrays and `for` loops." msgstr "" #: src/exercises/day-1/morning.md:11 msgid "A few things to consider while solving the exercises:" msgstr "" #: src/exercises/day-1/morning.md:13 msgid "" "* Use a local Rust installation, if possible. This way you can get\n" " auto-completion in your editor. See the page about [Using Cargo] for details\n" " on installing Rust.\n" "\n" "* Alternatively, use the Rust Playground." msgstr "" #: src/exercises/day-1/morning.md:19 msgid "" "The code snippets are not editable on purpose: the inline code snippets lose\n" "their state if you navigate away from the page." msgstr "" #: src/exercises/day-1/morning.md:22 src/exercises/day-1/afternoon.md:11 #: src/exercises/day-2/morning.md:11 src/exercises/day-2/afternoon.md:7 #: src/exercises/day-3/morning.md:7 src/exercises/bare-metal/morning.md:7 #: src/exercises/bare-metal/afternoon.md:7 src/exercises/concurrency/morning.md:12 #: src/exercises/concurrency/afternoon.md:13 msgid "After looking at the exercises, you can look at the [solutions] provided." msgstr "" #: src/exercises/day-1/implicit-conversions.md:1 msgid "# Implicit Conversions" msgstr "" #: src/exercises/day-1/implicit-conversions.md:3 msgid "" "Rust will not automatically apply _implicit conversions_ between types ([unlike\n" "C++][3]). You can see this in a program like this:" msgstr "" #: src/exercises/day-1/implicit-conversions.md:6 msgid "" "```rust,editable,compile_fail\n" "fn multiply(x: i16, y: i16) -> i16 {\n" " x * y\n" "}\n" "\n" "fn main() {\n" " let x: i8 = 15;\n" " let y: i16 = 1000;\n" "\n" " println!(\"{x} * {y} = {}\", multiply(x, y));\n" "}\n" "```" msgstr "" #: src/exercises/day-1/implicit-conversions.md:19 msgid "" "The Rust integer types all implement the [`From`][1] and [`Into`][2]\n" "traits to let us convert between them. The `From` trait has a single `from()`\n" "method and similarly, the `Into` trait has a single `into()` method.\n" "Implementing these traits is how a type expresses that it can be converted into\n" "another type." msgstr "" #: src/exercises/day-1/implicit-conversions.md:25 msgid "" "The standard library has an implementation of `From for i16`, which means\n" "that we can convert a variable `x` of type `i8` to an `i16` by calling \n" "`i16::from(x)`. Or, simpler, with `x.into()`, because `From for i16`\n" "implementation automatically create an implementation of `Into for i8`." msgstr "" #: src/exercises/day-1/implicit-conversions.md:30 msgid "" "The same applies for your own `From` implementations for your own types, so it is\n" "sufficient to only implement `From` to get a respective `Into` implementation automatically." msgstr "" #: src/exercises/day-1/implicit-conversions.md:33 msgid "" "1. Execute the above program and look at the compiler error.\n" "\n" "2. Update the code above to use `into()` to do the conversion.\n" "\n" "3. Change the types of `x` and `y` to other things (such as `f32`, `bool`,\n" " `i128`) to see which types you can convert to which other types. Try\n" " converting small types to big types and the other way around. Check the\n" " [standard library documentation][1] to see if `From` is implemented for\n" " the pairs you check." msgstr "" #: src/exercises/day-1/for-loops.md:1 msgid "# Arrays and `for` Loops" msgstr "" #: src/exercises/day-1/for-loops.md:3 msgid "We saw that an array can be declared like this:" msgstr "" #: src/exercises/day-1/for-loops.md:5 msgid "" "```rust\n" "let array = [10, 20, 30];\n" "```" msgstr "" #: src/exercises/day-1/for-loops.md:9 msgid "You can print such an array by asking for its debug representation with `{:?}`:" msgstr "" #: src/exercises/day-1/for-loops.md:11 msgid "" "```rust,editable\n" "fn main() {\n" " let array = [10, 20, 30];\n" " println!(\"array: {array:?}\");\n" "}\n" "```" msgstr "" #: src/exercises/day-1/for-loops.md:18 msgid "" "Rust lets you iterate over things like arrays and ranges using the `for`\n" "keyword:" msgstr "" #: src/exercises/day-1/for-loops.md:21 msgid "" "```rust,editable\n" "fn main() {\n" " let array = [10, 20, 30];\n" " print!(\"Iterating over array:\");\n" " for n in array {\n" " print!(\" {n}\");\n" " }\n" " println!();\n" "\n" " print!(\"Iterating over range:\");\n" " for i in 0..3 {\n" " print!(\" {}\", array[i]);\n" " }\n" " println!();\n" "}\n" "```" msgstr "" #: src/exercises/day-1/for-loops.md:38 msgid "" "Use the above to write a function `pretty_print` which pretty-print a matrix and\n" "a function `transpose` which will transpose a matrix (turn rows into columns):" msgstr "" #: src/exercises/day-1/for-loops.md:41 msgid "" "```bob\n" " ⎛⎡1 2 3⎀⎞ ⎡1 4 7⎀\n" "\"transpose\"⎜⎢4 5 6⎥⎟ \"==\"⎢2 5 8⎥\n" " ⎝⎣7 8 9⎊⎠ ⎣3 6 9⎊\n" "```" msgstr "" #: src/exercises/day-1/for-loops.md:47 msgid "Hard-code both functions to operate on 3 × 3 matrices." msgstr "" #: src/exercises/day-1/for-loops.md:49 msgid "" "Copy the code below to and implement the\n" "functions:" msgstr "" #: src/exercises/day-1/for-loops.md:52 msgid "" "```rust,should_panic\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_variables, dead_code)]\n" "\n" "fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {\n" " unimplemented!()\n" "}\n" "\n" "fn pretty_print(matrix: &[[i32; 3]; 3]) {\n" " unimplemented!()\n" "}\n" "\n" "fn main() {\n" " let matrix = [\n" " [101, 102, 103], // <-- the comment makes rustfmt add a newline\n" " [201, 202, 203],\n" " [301, 302, 303],\n" " ];\n" "\n" " println!(\"matrix:\");\n" " pretty_print(&matrix);\n" "\n" " let transposed = transpose(matrix);\n" " println!(\"transposed:\");\n" " pretty_print(&transposed);\n" "}\n" "```" msgstr "" #: src/exercises/day-1/for-loops.md:80 msgid "## Bonus Question" msgstr "" #: src/exercises/day-1/for-loops.md:82 msgid "" "Could you use `&[i32]` slices instead of hard-coded 3 × 3 matrices for your\n" "argument and return types? Something like `&[&[i32]]` for a two-dimensional\n" "slice-of-slices. Why or why not?" msgstr "" #: src/exercises/day-1/for-loops.md:87 msgid "" "See the [`ndarray` crate](https://docs.rs/ndarray/) for a production quality\n" "implementation." msgstr "" #: src/exercises/day-1/for-loops.md:92 msgid "" "The solution and the answer to the bonus section are available in the \n" "[Solution](solutions-morning.md#arrays-and-for-loops) section." msgstr "" #: src/basic-syntax/variables.md:1 msgid "# Variables" msgstr "" #: src/basic-syntax/variables.md:3 msgid "" "Rust provides type safety via static typing. Variable bindings are immutable by\n" "default:" msgstr "" #: src/basic-syntax/variables.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let x: i32 = 10;\n" " println!(\"x: {x}\");\n" " // x = 20;\n" " // println!(\"x: {x}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/variables.md:17 msgid "" "* Due to type inference the `i32` is optional. We will gradually show the types less and less as " "the course progresses.\n" "* Note that since `println!` is a macro, `x` is not moved, even using the function like syntax of " "`println!(\"x: {}\", x)`" msgstr "" #: src/basic-syntax/type-inference.md:1 msgid "# Type Inference" msgstr "" #: src/basic-syntax/type-inference.md:3 msgid "Rust will look at how the variable is _used_ to determine the type:" msgstr "" #: src/basic-syntax/type-inference.md:5 msgid "" "```rust,editable\n" "fn takes_u32(x: u32) {\n" " println!(\"u32: {x}\");\n" "}\n" "\n" "fn takes_i8(y: i8) {\n" " println!(\"i8: {y}\");\n" "}\n" "\n" "fn main() {\n" " let x = 10;\n" " let y = 20;\n" "\n" " takes_u32(x);\n" " takes_i8(y);\n" " // takes_u32(y);\n" "}\n" "```" msgstr "" #: src/basic-syntax/type-inference.md:26 msgid "" "This slide demonstrates how the Rust compiler infers types based on constraints given by variable " "declarations and usages." msgstr "" #: src/basic-syntax/type-inference.md:28 msgid "" "It is very important to emphasize that variables declared like this are not of some sort of " "dynamic \"any type\" that can\n" "hold any data. The machine code generated by such declaration is identical to the explicit " "declaration of a type.\n" "The compiler does the job for us and helps us write more concise code." msgstr "" #: src/basic-syntax/type-inference.md:32 msgid "" "The following code tells the compiler to copy into a certain generic container without the code " "ever explicitly specifying the contained type, using `_` as a placeholder:" msgstr "" #: src/basic-syntax/type-inference.md:34 msgid "" "```rust,editable\n" "fn main() {\n" " let mut v = Vec::new();\n" " v.push((10, false));\n" " v.push((20, true));\n" " println!(\"v: {v:?}\");\n" "\n" " let vv = v.iter().collect::>();\n" " println!(\"vv: {vv:?}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/type-inference.md:46 msgid "" "[`collect`](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.collect) relies " "on `FromIterator`, which [`HashSet`](https://doc.rust-lang.org/std/iter/trait.FromIterator.html) " "implements." msgstr "" #: src/basic-syntax/static-and-const.md:1 msgid "# Static and Constant Variables" msgstr "" #: src/basic-syntax/static-and-const.md:3 msgid "Global state is managed with static and constant variables." msgstr "" #: src/basic-syntax/static-and-const.md:5 msgid "## `const`" msgstr "" #: src/basic-syntax/static-and-const.md:7 msgid "You can declare compile-time constants:" msgstr "" #: src/basic-syntax/static-and-const.md:9 msgid "" "```rust,editable\n" "const DIGEST_SIZE: usize = 3;\n" "const ZERO: Option = Some(42);\n" "\n" "fn compute_digest(text: &str) -> [u8; DIGEST_SIZE] {\n" " let mut digest = [ZERO.unwrap_or(0); DIGEST_SIZE];\n" " for (idx, &b) in text.as_bytes().iter().enumerate() {\n" " digest[idx % DIGEST_SIZE] = digest[idx % DIGEST_SIZE].wrapping_add(b);\n" " }\n" " digest\n" "}\n" "\n" "fn main() {\n" " let digest = compute_digest(\"Hello\");\n" " println!(\"Digest: {digest:?}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/static-and-const.md:27 msgid "According to the [Rust RFC Book][1] these are inlined upon use." msgstr "" #: src/basic-syntax/static-and-const.md:29 msgid "## `static`" msgstr "" #: src/basic-syntax/static-and-const.md:31 msgid "You can also declare static variables:" msgstr "" #: src/basic-syntax/static-and-const.md:33 msgid "" "```rust,editable\n" "static BANNER: &str = \"Welcome to RustOS 3.14\";\n" "\n" "fn main() {\n" " println!(\"{BANNER}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/static-and-const.md:41 msgid "" "As noted in the [Rust RFC Book][1], these are not inlined upon use and have an actual associated " "memory location. This is useful for unsafe and embedded code, and the variable lives through the " "entirety of the program execution." msgstr "" #: src/basic-syntax/static-and-const.md:44 msgid "We will look at mutating static data in the [chapter on Unsafe Rust](../unsafe.md)." msgstr "" #: src/basic-syntax/static-and-const.md:48 msgid "" "* Mention that `const` behaves semantically similar to C++'s `constexpr`.\n" "* `static`, on the other hand, is much more similar to a `const` or mutable global variable in C+" "+.\n" "* It isn't super common that one would need a runtime evaluated constant, but it is helpful and " "safer than using a static." msgstr "" #: src/basic-syntax/scopes-shadowing.md:1 msgid "# Scopes and Shadowing" msgstr "" #: src/basic-syntax/scopes-shadowing.md:3 msgid "" "You can shadow variables, both those from outer scopes and variables from the\n" "same scope:" msgstr "" #: src/basic-syntax/scopes-shadowing.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let a = 10;\n" " println!(\"before: {a}\");\n" "\n" " {\n" " let a = \"hello\";\n" " println!(\"inner scope: {a}\");\n" "\n" " let a = true;\n" " println!(\"shadowed in inner scope: {a}\");\n" " }\n" "\n" " println!(\"after: {a}\");\n" "}\n" "```" msgstr "" #: src/basic-syntax/scopes-shadowing.md:25 msgid "" "* Definition: Shadowing is different from mutation, because after shadowing both variable's memory " "locations exist at the same time. Both are available under the same name, depending where you use " "it in the code. \n" "* A shadowing variable can have a different type. \n" "* Shadowing looks obscure at first, but is convenient for holding on to values after `.unwrap()`.\n" "* The following code demonstrates why the compiler can't simply reuse memory locations when " "shadowing an immutable variable in a scope, even if the type does not change." msgstr "" #: src/basic-syntax/scopes-shadowing.md:30 msgid "" "```rust,editable\n" "fn main() {\n" " let a = 1;\n" " let b = &a;\n" " let a = a + 1;\n" " println!(\"{a} {b}\");\n" "}\n" "```" msgstr "" #: src/memory-management.md:1 msgid "# Memory Management" msgstr "" #: src/memory-management.md:3 msgid "Traditionally, languages have fallen into two broad categories:" msgstr "" #: src/memory-management.md:5 msgid "" "* Full control via manual memory management: C, C++, Pascal, ...\n" "* Full safety via automatic memory management at runtime: Java, Python, Go, Haskell, ..." msgstr "" #: src/memory-management.md:8 msgid "Rust offers a new mix:" msgstr "" #: src/memory-management.md:10 msgid "" "> Full control *and* safety via compile time enforcement of correct memory\n" "> management." msgstr "" #: src/memory-management.md:13 msgid "It does this with an explicit ownership concept." msgstr "" #: src/memory-management.md:15 msgid "First, let's refresh how memory management works." msgstr "" #: src/memory-management/stack-vs-heap.md:1 msgid "# The Stack vs The Heap" msgstr "" #: src/memory-management/stack-vs-heap.md:3 msgid "" "* Stack: Continuous area of memory for local variables.\n" " * Values have fixed sizes known at compile time.\n" " * Extremely fast: just move a stack pointer.\n" " * Easy to manage: follows function calls.\n" " * Great memory locality.\n" "\n" "* Heap: Storage of values outside of function calls.\n" " * Values have dynamic sizes determined at runtime.\n" " * Slightly slower than the stack: some book-keeping needed.\n" " * No guarantee of memory locality." msgstr "" #: src/memory-management/stack.md:1 msgid "# Stack Memory" msgstr "" #: src/memory-management/stack.md:3 msgid "" "Creating a `String` puts fixed-sized data on the stack and dynamically sized\n" "data on the heap:" msgstr "" #: src/memory-management/stack.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let s1 = String::from(\"Hello\");\n" "}\n" "```" msgstr "" #: src/memory-management/stack.md:12 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - - -. .- - - - - - - - - - - - - - - -.\n" ": : : :\n" ": s1 : : :\n" ": +-----------+-------+ : : +----+----+----+----+----+ :\n" ": | ptr | o---+---+-----+-->| H | e | l | l | o | :\n" ": | len | 5 | : : +----+----+----+----+----+ :\n" ": | capacity | 5 | : : :\n" ": +-----------+-------+ : : :\n" ": : `- - - - - - - - - - - - - - - -'\n" "`- - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/memory-management/stack.md:28 msgid "" "* Mention that a `String` is backed by a `Vec`, so it has a capacity and length and can grow if " "mutable via reallocation on the heap.\n" "\n" "* If students ask about it, you can mention that the underlying memory is heap allocated using the " "[System Allocator] and custom allocators can be implemented using the [Allocator API]\n" "\n" "* We can inspect the memory layout with `unsafe` code. However, you should point out that this is " "rightfully unsafe!\n" "\n" " ```rust,editable\n" " fn main() {\n" " let mut s1 = String::from(\"Hello\");\n" " s1.push(' ');\n" " s1.push_str(\"world\");\n" " // DON'T DO THIS AT HOME! For educational purposes only.\n" " // String provides no guarantees about its layout, so this could lead to\n" " // undefined behavior.\n" " unsafe {\n" " let (capacity, ptr, len): (usize, usize, usize) = std::mem::transmute(s1);\n" " println!(\"ptr = {ptr:#x}, len = {len}, capacity = {capacity}\");\n" " }\n" " }\n" " ```" msgstr "" #: src/memory-management/manual.md:1 msgid "# Manual Memory Management" msgstr "" #: src/memory-management/manual.md:3 msgid "You allocate and deallocate heap memory yourself." msgstr "" #: src/memory-management/manual.md:5 msgid "" "If not done with care, this can lead to crashes, bugs, security vulnerabilities, and memory leaks." msgstr "" #: src/memory-management/manual.md:7 msgid "## C Example" msgstr "" #: src/memory-management/manual.md:9 msgid "You must call `free` on every pointer you allocate with `malloc`:" msgstr "" #: src/memory-management/manual.md:11 msgid "" "```c\n" "void foo(size_t n) {\n" " int* int_array = (int*)malloc(n * sizeof(int));\n" " //\n" " // ... lots of code\n" " //\n" " free(int_array);\n" "}\n" "```" msgstr "" #: src/memory-management/manual.md:21 msgid "" "Memory is leaked if the function returns early between `malloc` and `free`: the\n" "pointer is lost and we cannot deallocate the memory." msgstr "" #: src/memory-management/scope-based.md:1 msgid "# Scope-Based Memory Management" msgstr "" #: src/memory-management/scope-based.md:3 msgid "Constructors and destructors let you hook into the lifetime of an object." msgstr "" #: src/memory-management/scope-based.md:5 msgid "" "By wrapping a pointer in an object, you can free memory when the object is\n" "destroyed. The compiler guarantees that this happens, even if an exception is\n" "raised." msgstr "" #: src/memory-management/scope-based.md:9 msgid "" "This is often called _resource acquisition is initialization_ (RAII) and gives\n" "you smart pointers." msgstr "" #: src/memory-management/scope-based.md:12 msgid "## C++ Example" msgstr "" #: src/memory-management/scope-based.md:14 msgid "" "```c++\n" "void say_hello(std::unique_ptr person) {\n" " std::cout << \"Hello \" << person->name << std::endl;\n" "}\n" "```" msgstr "" #: src/memory-management/scope-based.md:20 msgid "" "* The `std::unique_ptr` object is allocated on the stack, and points to\n" " memory allocated on the heap.\n" "* At the end of `say_hello`, the `std::unique_ptr` destructor will run.\n" "* The destructor frees the `Person` object it points to." msgstr "" #: src/memory-management/scope-based.md:25 msgid "Special move constructors are used when passing ownership to a function:" msgstr "" #: src/memory-management/scope-based.md:27 msgid "" "```c++\n" "std::unique_ptr person = find_person(\"Carla\");\n" "say_hello(std::move(person));\n" "```" msgstr "" #: src/memory-management/garbage-collection.md:1 msgid "# Automatic Memory Management" msgstr "" #: src/memory-management/garbage-collection.md:3 msgid "" "An alternative to manual and scope-based memory management is automatic memory\n" "management:" msgstr "" #: src/memory-management/garbage-collection.md:6 msgid "" "* The programmer never allocates or deallocates memory explicitly.\n" "* A garbage collector finds unused memory and deallocates it for the programmer." msgstr "" #: src/memory-management/garbage-collection.md:9 msgid "## Java Example" msgstr "" #: src/memory-management/garbage-collection.md:11 msgid "The `person` object is not deallocated after `sayHello` returns:" msgstr "" #: src/memory-management/garbage-collection.md:13 msgid "" "```java\n" "void sayHello(Person person) {\n" " System.out.println(\"Hello \" + person.getName());\n" "}\n" "```" msgstr "" #: src/memory-management/rust.md:1 msgid "# Memory Management in Rust" msgstr "" #: src/memory-management/rust.md:3 msgid "Memory management in Rust is a mix:" msgstr "" #: src/memory-management/rust.md:5 msgid "" "* Safe and correct like Java, but without a garbage collector.\n" "* Depending on which abstraction (or combination of abstractions) you choose, can be a single " "unique pointer, reference counted, or atomically reference counted.\n" "* Scope-based like C++, but the compiler enforces full adherence.\n" "* A Rust user can choose the right abstraction for the situation, some even have no cost at " "runtime like C." msgstr "" #: src/memory-management/rust.md:10 msgid "It achieves this by modeling _ownership_ explicitly." msgstr "" #: src/memory-management/rust.md:14 msgid "" "* If asked how at this point, you can mention that in Rust this is usually handled by RAII wrapper " "types such as [Box], [Vec], [Rc], or [Arc]. These encapsulate ownership and memory allocation via " "various means, and prevent the potential errors in C.\n" "\n" "* You may be asked about destructors here, the [Drop] trait is the Rust equivalent." msgstr "" #: src/memory-management/comparison.md:1 msgid "# Comparison" msgstr "" #: src/memory-management/comparison.md:3 msgid "Here is a rough comparison of the memory management techniques." msgstr "" #: src/memory-management/comparison.md:5 msgid "## Pros of Different Memory Management Techniques" msgstr "" #: src/memory-management/comparison.md:7 msgid "" "* Manual like C:\n" " * No runtime overhead.\n" "* Automatic like Java:\n" " * Fully automatic.\n" " * Safe and correct.\n" "* Scope-based like C++:\n" " * Partially automatic.\n" " * No runtime overhead.\n" "* Compiler-enforced scope-based like Rust:\n" " * Enforced by compiler.\n" " * No runtime overhead.\n" " * Safe and correct." msgstr "" #: src/memory-management/comparison.md:20 msgid "## Cons of Different Memory Management Techniques" msgstr "" #: src/memory-management/comparison.md:22 msgid "" "* Manual like C:\n" " * Use-after-free.\n" " * Double-frees.\n" " * Memory leaks.\n" "* Automatic like Java:\n" " * Garbage collection pauses.\n" " * Destructor delays.\n" "* Scope-based like C++:\n" " * Complex, opt-in by programmer.\n" " * Potential for use-after-free.\n" "* Compiler-enforced and scope-based like Rust:\n" " * Some upfront complexity.\n" " * Can reject valid programs." msgstr "" #: src/ownership.md:1 msgid "# Ownership" msgstr "" #: src/ownership.md:3 msgid "" "All variable bindings have a _scope_ where they are valid and it is an error to\n" "use a variable outside its scope:" msgstr "" #: src/ownership.md:6 msgid "" "```rust,editable,compile_fail\n" "struct Point(i32, i32);\n" "\n" "fn main() {\n" " {\n" " let p = Point(3, 4);\n" " println!(\"x: {}\", p.0);\n" " }\n" " println!(\"y: {}\", p.1);\n" "}\n" "```" msgstr "" #: src/ownership.md:18 msgid "" "* At the end of the scope, the variable is _dropped_ and the data is freed.\n" "* A destructor can run here to free up resources.\n" "* We say that the variable _owns_ the value." msgstr "" #: src/ownership/move-semantics.md:1 msgid "# Move Semantics" msgstr "" #: src/ownership/move-semantics.md:3 msgid "An assignment will transfer ownership between variables:" msgstr "" #: src/ownership/move-semantics.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let s1: String = String::from(\"Hello!\");\n" " let s2: String = s1;\n" " println!(\"s2: {s2}\");\n" " // println!(\"s1: {s1}\");\n" "}\n" "```" msgstr "" #: src/ownership/move-semantics.md:14 msgid "" "* The assignment of `s1` to `s2` transfers ownership.\n" "* The data was _moved_ from `s1` and `s1` is no longer accessible.\n" "* When `s1` goes out of scope, nothing happens: it has no ownership.\n" "* When `s2` goes out of scope, the string data is freed.\n" "* There is always _exactly_ one variable binding which owns a value." msgstr "" #: src/ownership/move-semantics.md:22 msgid "" "* Mention that this is the opposite of the defaults in C++, which copies by value unless you use " "`std::move` (and the move constructor is defined!).\n" "\n" "* In Rust, clones are explicit (by using `clone`)." msgstr "" #: src/ownership/moved-strings-rust.md:1 msgid "# Moved Strings in Rust" msgstr "" #: src/ownership/moved-strings-rust.md:3 msgid "" "```rust,editable\n" "fn main() {\n" " let s1: String = String::from(\"Rust\");\n" " let s2: String = s1;\n" "}\n" "```" msgstr "" #: src/ownership/moved-strings-rust.md:10 msgid "" "* The heap data from `s1` is reused for `s2`.\n" "* When `s1` goes out of scope, nothing happens (it has been moved from)." msgstr "" #: src/ownership/moved-strings-rust.md:13 msgid "Before move to `s2`:" msgstr "" #: src/ownership/moved-strings-rust.md:15 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - - -. .- - - - - - - - - - - - - -.\n" ": : : :\n" ": s1 : : :\n" ": +-----------+-------+ : : +----+----+----+----+ :\n" ": | ptr | o---+---+-----+-->| R | u | s | t | :\n" ": | len | 4 | : : +----+----+----+----+ :\n" ": | capacity | 4 | : : :\n" ": +-----------+-------+ : : :\n" ": : `- - - - - - - - - - - - - -'\n" ": :\n" "`- - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/ownership/moved-strings-rust.md:30 msgid "After move to `s2`:" msgstr "" #: src/ownership/moved-strings-rust.md:32 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - - -. .- - - - - - - - - - - - - -.\n" ": : : :\n" ": s1 \"(inaccessible)\" : : :\n" ": +-----------+-------+ : : +----+----+----+----+ :\n" ": | ptr | o---+---+--+--+-->| R | u | s | t | :\n" ": | len | 4 | : | : +----+----+----+----+ :\n" ": | capacity | 4 | : | : :\n" ": +-----------+-------+ : | : :\n" ": : | `- - - - - - - - - - - - - -'\n" ": s2 : |\n" ": +-----------+-------+ : |\n" ": | ptr | o---+---+--'\n" ": | len | 4 | :\n" ": | capacity | 4 | :\n" ": +-----------+-------+ :\n" ": :\n" "`- - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/ownership/double-free-modern-cpp.md:1 msgid "# Double Frees in Modern C++" msgstr "" #: src/ownership/double-free-modern-cpp.md:3 msgid "Modern C++ solves this differently:" msgstr "" #: src/ownership/double-free-modern-cpp.md:5 msgid "" "```c++\n" "std::string s1 = \"Cpp\";\n" "std::string s2 = s1; // Duplicate the data in s1.\n" "```" msgstr "" #: src/ownership/double-free-modern-cpp.md:10 msgid "" "* The heap data from `s1` is duplicated and `s2` gets its own independent copy.\n" "* When `s1` and `s2` go out of scope, they each free their own memory." msgstr "" #: src/ownership/double-free-modern-cpp.md:13 msgid "Before copy-assignment:" msgstr "" #: src/ownership/double-free-modern-cpp.md:16 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - - -. .- - - - - - - - - - - -.\n" ": : : :\n" ": s1 : : :\n" ": +-----------+-------+ : : +----+----+----+ :\n" ": | ptr | o---+---+--+--+-->| C | p | p | :\n" ": | len | 3 | : : +----+----+----+ :\n" ": | capacity | 3 | : : :\n" ": +-----------+-------+ : : :\n" ": : `- - - - - - - - - - - -'\n" "`- - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/ownership/double-free-modern-cpp.md:30 msgid "After copy-assignment:" msgstr "" #: src/ownership/double-free-modern-cpp.md:32 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - - -. .- - - - - - - - - - - -.\n" ": : : :\n" ": s1 : : :\n" ": +-----------+-------+ : : +----+----+----+ :\n" ": | ptr | o---+---+--+--+-->| C | p | p | :\n" ": | len | 3 | : : +----+----+----+ :\n" ": | capacity | 3 | : : :\n" ": +-----------+-------+ : : :\n" ": : : :\n" ": s2 : : :\n" ": +-----------+-------+ : : +----+----+----+ :\n" ": | ptr | o---+---+-----+-->| C | p | p | :\n" ": | len | 3 | : : +----+----+----+ :\n" ": | capacity | 3 | : : :\n" ": +-----------+-------+ : : :\n" ": : `- - - - - - - - - - - -'\n" "`- - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/ownership/moves-function-calls.md:1 msgid "# Moves in Function Calls" msgstr "" #: src/ownership/moves-function-calls.md:3 msgid "" "When you pass a value to a function, the value is assigned to the function\n" "parameter. This transfers ownership:" msgstr "" #: src/ownership/moves-function-calls.md:6 msgid "" "```rust,editable\n" "fn say_hello(name: String) {\n" " println!(\"Hello {name}\")\n" "}\n" "\n" "fn main() {\n" " let name = String::from(\"Alice\");\n" " say_hello(name);\n" " // say_hello(name);\n" "}\n" "```" msgstr "" #: src/ownership/moves-function-calls.md:20 msgid "" "* With the first call to `say_hello`, `main` gives up ownership of `name`. Afterwards, `name` " "cannot be used anymore within `main`.\n" "* The heap memory allocated for `name` will be freed at the end of the `say_hello` function.\n" "* `main` can retain ownership if it passes `name` as a reference (`&name`) and if `say_hello` " "accepts a reference as a parameter.\n" "* Alternatively, `main` can pass a clone of `name` in the first call (`name.clone()`).\n" "* Rust makes it harder than C++ to inadvertently create copies by making move semantics the " "default, and by forcing programmers to make clones explicit." msgstr "" #: src/ownership/copy-clone.md:1 msgid "# Copying and Cloning" msgstr "" #: src/ownership/copy-clone.md:3 msgid "While move semantics are the default, certain types are copied by default:" msgstr "" #: src/ownership/copy-clone.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let x = 42;\n" " let y = x;\n" " println!(\"x: {x}\");\n" " println!(\"y: {y}\");\n" "}\n" "```" msgstr "" #: src/ownership/copy-clone.md:14 msgid "These types implement the `Copy` trait." msgstr "" #: src/ownership/copy-clone.md:16 msgid "You can opt-in your own types to use copy semantics:" msgstr "" #: src/ownership/copy-clone.md:18 msgid "" "```rust,editable\n" "#[derive(Copy, Clone, Debug)]\n" "struct Point(i32, i32);\n" "\n" "fn main() {\n" " let p1 = Point(3, 4);\n" " let p2 = p1;\n" " println!(\"p1: {p1:?}\");\n" " println!(\"p2: {p2:?}\");\n" "}\n" "```" msgstr "" #: src/ownership/copy-clone.md:30 msgid "" "* After the assignment, both `p1` and `p2` own their own data.\n" "* We can also use `p1.clone()` to explicitly copy the data." msgstr "" #: src/ownership/copy-clone.md:35 msgid "Copying and cloning are not the same thing:" msgstr "" #: src/ownership/copy-clone.md:37 msgid "" "* Copying refers to bitwise copies of memory regions and does not work on arbitrary objects.\n" "* Copying does not allow for custom logic (unlike copy constructors in C++).\n" "* Cloning is a more general operation and also allows for custom behavior by implementing the " "`Clone` trait.\n" "* Copying does not work on types that implement the `Drop` trait." msgstr "" #: src/ownership/copy-clone.md:42 src/ownership/lifetimes-function-calls.md:29 msgid "In the above example, try the following:" msgstr "" #: src/ownership/copy-clone.md:44 msgid "" "* Add a `String` field to `struct Point`. It will not compile because `String` is not a `Copy` " "type.\n" "* Remove `Copy` from the `derive` attribute. The compiler error is now in the `println!` for " "`p1`.\n" "* Show that it works if you clone `p1` instead." msgstr "" #: src/ownership/copy-clone.md:48 msgid "" "If students ask about `derive`, it is sufficient to say that this is a way to generate code in " "Rust\n" "at compile time. In this case the default implementations of `Copy` and `Clone` traits are " "generated." msgstr "" #: src/ownership/borrowing.md:1 msgid "# Borrowing" msgstr "" #: src/ownership/borrowing.md:3 msgid "" "Instead of transferring ownership when calling a function, you can let a\n" "function _borrow_ the value:" msgstr "" #: src/ownership/borrowing.md:6 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Point(i32, i32);\n" "\n" "fn add(p1: &Point, p2: &Point) -> Point {\n" " Point(p1.0 + p2.0, p1.1 + p2.1)\n" "}\n" "\n" "fn main() {\n" " let p1 = Point(3, 4);\n" " let p2 = Point(10, 20);\n" " let p3 = add(&p1, &p2);\n" " println!(\"{p1:?} + {p2:?} = {p3:?}\");\n" "}\n" "```" msgstr "" #: src/ownership/borrowing.md:22 msgid "" "* The `add` function _borrows_ two points and returns a new point.\n" "* The caller retains ownership of the inputs." msgstr "" #: src/ownership/borrowing.md:27 msgid "Notes on stack returns:" msgstr "" #: src/ownership/borrowing.md:28 msgid "" "* Demonstrate that the return from `add` is cheap because the compiler can eliminate the copy " "operation. Change the above code to print stack addresses and run it on the [Playground]. In the " "\"DEBUG\" optimization level, the addresses should change, while they stay the same when changing " "to the \"RELEASE\" setting:\n" "\n" " ```rust,editable\n" " #[derive(Debug)]\n" " struct Point(i32, i32);\n" "\n" " fn add(p1: &Point, p2: &Point) -> Point {\n" " let p = Point(p1.0 + p2.0, p1.1 + p2.1);\n" " println!(\"&p.0: {:p}\", &p.0);\n" " p\n" " }\n" "\n" " fn main() {\n" " let p1 = Point(3, 4);\n" " let p2 = Point(10, 20);\n" " let p3 = add(&p1, &p2);\n" " println!(\"&p3.0: {:p}\", &p3.0);\n" " println!(\"{p1:?} + {p2:?} = {p3:?}\");\n" " }\n" " ```\n" "* The Rust compiler can do return value optimization (RVO).\n" "* In C++, copy elision has to be defined in the language specification because constructors can " "have side effects. In Rust, this is not an issue at all. If RVO did not happen, Rust will always " "performs a simple and efficient `memcpy` copy." msgstr "" #: src/ownership/shared-unique-borrows.md:1 msgid "# Shared and Unique Borrows" msgstr "" #: src/ownership/shared-unique-borrows.md:3 msgid "Rust puts constraints on the ways you can borrow values:" msgstr "" #: src/ownership/shared-unique-borrows.md:5 msgid "" "* You can have one or more `&T` values at any given time, _or_\n" "* You can have exactly one `&mut T` value." msgstr "" #: src/ownership/shared-unique-borrows.md:8 msgid "" "```rust,editable,compile_fail\n" "fn main() {\n" " let mut a: i32 = 10;\n" " let b: &i32 = &a;\n" "\n" " {\n" " let c: &mut i32 = &mut a;\n" " *c = 20;\n" " }\n" "\n" " println!(\"a: {a}\");\n" " println!(\"b: {b}\");\n" "}\n" "```" msgstr "" #: src/ownership/shared-unique-borrows.md:25 msgid "" "* The above code does not compile because `a` is borrowed as mutable (through `c`) and as " "immutable (through `b`) at the same time.\n" "* Move the `println!` statement for `b` before the scope that introduces `c` to make the code " "compile.\n" "* After that change, the compiler realizes that `b` is only ever used before the new mutable " "borrow of `a` through `c`. This is a feature of the borrow checker called \"non-lexical " "lifetimes\"." msgstr "" #: src/ownership/lifetimes.md:1 msgid "# Lifetimes" msgstr "" #: src/ownership/lifetimes.md:3 msgid "A borrowed value has a _lifetime_:" msgstr "" #: src/ownership/lifetimes.md:5 msgid "" "* The lifetime can be elided: `add(p1: &Point, p2: &Point) -> Point`.\n" "* Lifetimes can also be explicit: `&'a Point`, `&'document str`.\n" "* Read `&'a Point` as \"a borrowed `Point` which is valid for at least the\n" " lifetime `a`\".\n" "* Lifetimes are always inferred by the compiler: you cannot assign a lifetime\n" " yourself.\n" " * Lifetime annotations create constraints; the compiler verifies that there is\n" " a valid solution." msgstr "" #: src/ownership/lifetimes-function-calls.md:1 msgid "# Lifetimes in Function Calls" msgstr "" #: src/ownership/lifetimes-function-calls.md:3 msgid "In addition to borrowing its arguments, a function can return a borrowed value:" msgstr "" #: src/ownership/lifetimes-function-calls.md:5 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Point(i32, i32);\n" "\n" "fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {\n" " if p1.0 < p2.0 { p1 } else { p2 }\n" "}\n" "\n" "fn main() {\n" " let p1: Point = Point(10, 10);\n" " let p2: Point = Point(20, 20);\n" " let p3: &Point = left_most(&p1, &p2);\n" " println!(\"left-most point: {:?}\", p3);\n" "}\n" "```" msgstr "" #: src/ownership/lifetimes-function-calls.md:21 msgid "" "* `'a` is a generic parameter, it is inferred by the compiler.\n" "* Lifetimes start with `'` and `'a` is a typical default name.\n" "* Read `&'a Point` as \"a borrowed `Point` which is valid for at least the\n" " lifetime `a`\".\n" " * The _at least_ part is important when parameters are in different scopes." msgstr "" #: src/ownership/lifetimes-function-calls.md:31 msgid "" "* Move the declaration of `p2` and `p3` into a a new scope (`{ ... }`), resulting in the following " "code:\n" " ```rust,ignore\n" " #[derive(Debug)]\n" " struct Point(i32, i32);\n" "\n" " fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point {\n" " if p1.0 < p2.0 { p1 } else { p2 }\n" " }\n" "\n" " fn main() {\n" " let p1: Point = Point(10, 10);\n" " let p3: &Point;\n" " {\n" " let p2: Point = Point(20, 20);\n" " p3 = left_most(&p1, &p2);\n" " }\n" " println!(\"left-most point: {:?}\", p3);\n" " }\n" " ```\n" " Note how this does not compile since `p3` outlives `p2`.\n" "\n" "* Reset the workspace and change the function signature to `fn left_most<'a, 'b>(p1: &'a Point, " "p2: &'a Point) -> &'b Point`. This will not compile because the relationship between the lifetimes " "`'a` and `'b` is unclear.\n" "* Another way to explain it:\n" " * Two references to two values are borrowed by a function and the function returns\n" " another reference.\n" " * It must have come from one of those two inputs (or from a global variable).\n" " * Which one is it? The compiler needs to to know, so at the call site the returned reference is " "not used\n" " for longer than a variable from where the reference came from." msgstr "" #: src/ownership/lifetimes-data-structures.md:1 msgid "# Lifetimes in Data Structures" msgstr "" #: src/ownership/lifetimes-data-structures.md:3 msgid "If a data type stores borrowed data, it must be annotated with a lifetime:" msgstr "" #: src/ownership/lifetimes-data-structures.md:5 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Highlight<'doc>(&'doc str);\n" "\n" "fn erase(text: String) {\n" " println!(\"Bye {text}!\");\n" "}\n" "\n" "fn main() {\n" " let text = String::from(\"The quick brown fox jumps over the lazy dog.\");\n" " let fox = Highlight(&text[4..19]);\n" " let dog = Highlight(&text[35..43]);\n" " // erase(text);\n" " println!(\"{fox:?}\");\n" " println!(\"{dog:?}\");\n" "}\n" "```" msgstr "" #: src/ownership/lifetimes-data-structures.md:25 msgid "" "* In the above example, the annotation on `Highlight` enforces that the data underlying the " "contained `&str` lives at least as long as any instance of `Highlight` that uses that data.\n" "* If `text` is consumed before the end of the lifetime of `fox` (or `dog`), the borrow checker " "throws an error.\n" "* Types with borrowed data force users to hold on to the original data. This can be useful for " "creating lightweight views, but it generally makes them somewhat harder to use.\n" "* When possible, make data structures own their data directly.\n" "* Some structs with multiple references inside can have more than one lifetime annotation. This " "can be necessary if there is a need to describe lifetime relationships between the references " "themselves, in addition to the lifetime of the struct itself. Those are very advanced use cases." msgstr "" #: src/exercises/day-1/afternoon.md:1 msgid "# Day 1: Afternoon Exercises" msgstr "" #: src/exercises/day-1/afternoon.md:3 msgid "We will look at two things:" msgstr "" #: src/exercises/day-1/afternoon.md:5 msgid "" "* A small book library,\n" "\n" "* Iterators and ownership (hard)." msgstr "" #: src/exercises/day-1/book-library.md:1 msgid "# Designing a Library" msgstr "" #: src/exercises/day-1/book-library.md:3 msgid "" "We will learn much more about structs and the `Vec` type tomorrow. For now,\n" "you just need to know part of its API:" msgstr "" #: src/exercises/day-1/book-library.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let mut vec = vec![10, 20];\n" " vec.push(30);\n" " let midpoint = vec.len() / 2;\n" " println!(\"middle value: {}\", vec[midpoint]);\n" " for item in &vec {\n" " println!(\"item: {item}\");\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/day-1/book-library.md:18 msgid "" "Use this to create a library application. Copy the code below to\n" " and update the types to make it compile:" msgstr "" #: src/exercises/day-1/book-library.md:21 msgid "" "```rust,should_panic\n" "struct Library {\n" " books: Vec,\n" "}\n" "\n" "struct Book {\n" " title: String,\n" " year: u16,\n" "}\n" "\n" "impl Book {\n" " // This is a constructor, used below.\n" " fn new(title: &str, year: u16) -> Book {\n" " Book {\n" " title: String::from(title),\n" " year,\n" " }\n" " }\n" "}\n" "\n" "// Implement the methods below. Update the `self` parameter to\n" "// indicate the method's required level of ownership over the object:\n" "//\n" "// - `&self` for shared read-only access,\n" "// - `&mut self` for unique and mutable access,\n" "// - `self` for unique access by value.\n" "impl Library {\n" " fn new() -> Library {\n" " todo!(\"Initialize and return a `Library` value\")\n" " }\n" "\n" " //fn len(self) -> usize {\n" " // todo!(\"Return the length of `self.books`\")\n" " //}\n" "\n" " //fn is_empty(self) -> bool {\n" " // todo!(\"Return `true` if `self.books` is empty\")\n" " //}\n" "\n" " //fn add_book(self, book: Book) {\n" " // todo!(\"Add a new book to `self.books`\")\n" " //}\n" "\n" " //fn print_books(self) {\n" " // todo!(\"Iterate over `self.books` and each book's title and year\")\n" " //}\n" "\n" " //fn oldest_book(self) -> Option<&Book> {\n" " // todo!(\"Return a reference to the oldest book (if any)\")\n" " //}\n" "}\n" "\n" "// This shows the desired behavior. Uncomment the code below and\n" "// implement the missing methods. You will need to update the\n" "// method signatures, including the \"self\" parameter! You may\n" "// also need to update the variable bindings within main.\n" "fn main() {\n" " let library = Library::new();\n" "\n" " //println!(\"The library is empty: {}\", library.is_empty());\n" " //\n" " //library.add_book(Book::new(\"Lord of the Rings\", 1954));\n" " //library.add_book(Book::new(\"Alice's Adventures in Wonderland\", 1865));\n" " //\n" " //println!(\"The library is no longer empty: {}\", library.is_empty());\n" " //\n" " //\n" " //library.print_books();\n" " //\n" " //match library.oldest_book() {\n" " // Some(book) => println!(\"The oldest book is {}\", book.title),\n" " // None => println!(\"The library is empty!\"),\n" " //}\n" " //\n" " //println!(\"The library has {} books\", library.len());\n" " //library.print_books();\n" "}\n" "```" msgstr "" #: src/exercises/day-1/book-library.md:102 msgid "[Solution](solutions-afternoon.md#designing-a-library)" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:1 msgid "# Iterators and Ownership" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:3 msgid "" "The ownership model of Rust affects many APIs. An example of this is the\n" "[`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) and\n" "[`IntoIterator`](https://doc.rust-lang.org/std/iter/trait.IntoIterator.html)\n" "traits." msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:8 msgid "## `Iterator`" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:10 msgid "" "Traits are like interfaces: they describe behavior (methods) for a type. The\n" "`Iterator` trait simply says that you can call `next` until you get `None` back:" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:13 msgid "" "```rust\n" "pub trait Iterator {\n" " type Item;\n" " fn next(&mut self) -> Option;\n" "}\n" "```" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:20 msgid "You use this trait like this:" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:22 msgid "" "```rust,editable\n" "fn main() {\n" " let v: Vec = vec![10, 20, 30];\n" " let mut iter = v.iter();\n" "\n" " println!(\"v[0]: {:?}\", iter.next());\n" " println!(\"v[1]: {:?}\", iter.next());\n" " println!(\"v[2]: {:?}\", iter.next());\n" " println!(\"No more items: {:?}\", iter.next());\n" "}\n" "```" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:34 msgid "What is the type returned by the iterator? Test your answer here:" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:36 msgid "" "```rust,editable,compile_fail\n" "fn main() {\n" " let v: Vec = vec![10, 20, 30];\n" " let mut iter = v.iter();\n" "\n" " let v0: Option<..> = iter.next();\n" " println!(\"v0: {v0:?}\");\n" "}\n" "```" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:46 msgid "Why is this type used?" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:48 msgid "## `IntoIterator`" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:50 msgid "" "The `Iterator` trait tells you how to _iterate_ once you have created an\n" "iterator. The related trait `IntoIterator` tells you how to create the iterator:" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:53 msgid "" "```rust\n" "pub trait IntoIterator {\n" " type Item;\n" " type IntoIter: Iterator;\n" "\n" " fn into_iter(self) -> Self::IntoIter;\n" "}\n" "```" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:62 msgid "" "The syntax here means that every implementation of `IntoIterator` must\n" "declare two types:" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:65 msgid "" "* `Item`: the type we iterate over, such as `i8`,\n" "* `IntoIter`: the `Iterator` type returned by the `into_iter` method." msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:68 msgid "" "Note that `IntoIter` and `Item` are linked: the iterator must have the same\n" "`Item` type, which means that it returns `Option`" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:71 msgid "Like before, what is the type returned by the iterator?" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:73 msgid "" "```rust,editable,compile_fail\n" "fn main() {\n" " let v: Vec = vec![String::from(\"foo\"), String::from(\"bar\")];\n" " let mut iter = v.into_iter();\n" "\n" " let v0: Option<..> = iter.next();\n" " println!(\"v0: {v0:?}\");\n" "}\n" "```" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:83 msgid "## `for` Loops" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:85 msgid "" "Now that we know both `Iterator` and `IntoIterator`, we can build `for` loops.\n" "They call `into_iter()` on an expression and iterates over the resulting\n" "iterator:" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:89 msgid "" "```rust,editable\n" "fn main() {\n" " let v: Vec = vec![String::from(\"foo\"), String::from(\"bar\")];\n" "\n" " for word in &v {\n" " println!(\"word: {word}\");\n" " }\n" "\n" " for word in v {\n" " println!(\"word: {word}\");\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:103 msgid "What is the type of `word` in each loop?" msgstr "" #: src/exercises/day-1/iterators-and-ownership.md:105 msgid "" "Experiment with the code above and then consult the documentation for [`impl\n" "IntoIterator for\n" "&Vec`](https://doc.rust-lang.org/std/vec/struct.Vec.html#impl-IntoIterator-for-" "%26%27a%20Vec%3CT%2C%20A%3E)\n" "and [`impl IntoIterator for\n" "Vec`](https://doc.rust-lang.org/std/vec/struct.Vec.html#impl-IntoIterator-for-" "Vec%3CT%2C%20A%3E)\n" "to check your answers." msgstr "" #: src/welcome-day-2.md:1 msgid "# Welcome to Day 2" msgstr "" #: src/welcome-day-2.md:3 msgid "Now that we have seen a fair amount of Rust, we will continue with:" msgstr "" #: src/welcome-day-2.md:5 msgid "" "* Structs, enums, methods.\n" "\n" "* Pattern matching: destructuring enums, structs, and arrays.\n" "\n" "* Control flow constructs: `if`, `if let`, `while`, `while let`, `break`, and\n" " `continue`.\n" "\n" "* The Standard Library: `String`, `Option` and `Result`, `Vec`, `HashMap`, `Rc`\n" " and `Arc`.\n" "\n" "* Modules: visibility, paths, and filesystem hierarchy." msgstr "" #: src/structs.md:1 msgid "# Structs" msgstr "" #: src/structs.md:3 msgid "Like C and C++, Rust has support for custom structs:" msgstr "" #: src/structs.md:5 msgid "" "```rust,editable\n" "struct Person {\n" " name: String,\n" " age: u8,\n" "}\n" "\n" "fn main() {\n" " let mut peter = Person {\n" " name: String::from(\"Peter\"),\n" " age: 27,\n" " };\n" " println!(\"{} is {} years old\", peter.name, peter.age);\n" " \n" " peter.age = 28;\n" " println!(\"{} is {} years old\", peter.name, peter.age);\n" " \n" " let jackie = Person {\n" " name: String::from(\"Jackie\"),\n" " ..peter\n" " };\n" " println!(\"{} is {} years old\", jackie.name, jackie.age);\n" "}\n" "```" msgstr "" #: src/structs.md:31 src/enums.md:33 src/enums/sizes.md:29 src/methods.md:30 #: src/methods/example.md:46 src/pattern-matching.md:25 src/pattern-matching/match-guards.md:22 #: src/control-flow/blocks.md:42 msgid "Key Points:" msgstr "" #: src/structs.md:33 msgid "" "* Structs work like in C or C++.\n" " * Like in C++, and unlike in C, no typedef is needed to define a type.\n" " * Unlike in C++, there is no inheritance between structs.\n" "* Methods are defined in an `impl` block, which we will see in following slides.\n" "* This may be a good time to let people know there are different types of structs. \n" " * Zero-sized structs `e.g., struct Foo;` might be used when implementing a trait on some type " "but don’t have any data that you want to store in the value itself. \n" " * The next slide will introduce Tuple structs, used when the field names are not important.\n" "* The syntax `..peter` allows us to copy the majority of the fields from the old struct without " "having to explicitly type it all out. It must always be the last element." msgstr "" #: src/structs/tuple-structs.md:1 msgid "# Tuple Structs" msgstr "" #: src/structs/tuple-structs.md:3 msgid "If the field names are unimportant, you can use a tuple struct:" msgstr "" #: src/structs/tuple-structs.md:5 msgid "" "```rust,editable\n" "struct Point(i32, i32);\n" "\n" "fn main() {\n" " let p = Point(17, 23);\n" " println!(\"({}, {})\", p.0, p.1);\n" "}\n" "```" msgstr "" #: src/structs/tuple-structs.md:14 msgid "This is often used for single-field wrappers (called newtypes):" msgstr "" #: src/structs/tuple-structs.md:16 msgid "" "```rust,editable,compile_fail\n" "struct PoundsOfForce(f64);\n" "struct Newtons(f64);\n" "\n" "fn compute_thruster_force() -> PoundsOfForce {\n" " todo!(\"Ask a rocket scientist at NASA\")\n" "}\n" "\n" "fn set_thruster_force(force: Newtons) {\n" " // ...\n" "}\n" "\n" "fn main() {\n" " let force = compute_thruster_force();\n" " set_thruster_force(force);\n" "}\n" "\n" "```" msgstr "" #: src/structs/tuple-structs.md:37 msgid "" "* Newtypes are a great way to encode additional information about the value in a primitive type, " "for example:\n" " * The number is measured in some units: `Newtons` in the example above.\n" " * The value passed some validation when it was created, so you no longer have to validate it " "again at every use: 'PhoneNumber(String)` or `OddNumber(u32)`.\n" "* Demonstrate how to add a `f64` value to a `Newtons` type by accessing the single field in the " "newtype.\n" " * Rust generally doesn’t like inexplicit things, like automatic unwrapping or for instance " "using booleans as integers.\n" " * Operator overloading is discussed on Day 3 (generics). " msgstr "" #: src/structs/field-shorthand.md:1 msgid "# Field Shorthand Syntax" msgstr "" #: src/structs/field-shorthand.md:3 msgid "" "If you already have variables with the right names, then you can create the\n" "struct using a shorthand:" msgstr "" #: src/structs/field-shorthand.md:6 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Person {\n" " name: String,\n" " age: u8,\n" "}\n" "\n" "impl Person {\n" " fn new(name: String, age: u8) -> Person {\n" " Person { name, age }\n" " }\n" "}\n" "\n" "fn main() {\n" " let peter = Person::new(String::from(\"Peter\"), 27);\n" " println!(\"{peter:?}\");\n" "}\n" "```" msgstr "" #: src/structs/field-shorthand.md:27 msgid "" "* The `new` function could be written using `Self` as a type, as it is interchangeable with the " "struct type name\n" "\n" " ```rust,editable\n" " #[derive(Debug)]\n" " struct Person {\n" " name: String,\n" " age: u8,\n" " }\n" " impl Person {\n" " fn new(name: String, age: u8) -> Self {\n" " Self { name, age }\n" " }\n" " }\n" " ``` \n" "* Implement the `Default` trait for the struct. Define some fields and use the default values for " "the other fields.\n" "\n" " ```rust,editable\n" " #[derive(Debug)]\n" " struct Person {\n" " name: String,\n" " age: u8,\n" " }\n" " impl Default for Person {\n" " fn default() -> Person {\n" " Person {\n" " name: \"Bot\".to_string(),\n" " age: 0,\n" " }\n" " }\n" " }\n" " fn create_default() {\n" " let tmp = Person {\n" " ..Default::default()\n" " };\n" " let tmp = Person {\n" " name: \"Sam\".to_string(),\n" " ..Default::default()\n" " };\n" " }\n" " ```\n" "\n" "* Methods are defined in the `impl` block.\n" "* Use struct update syntax to define a new structure using `peter`. Note that the variable `peter` " "will no longer be accessible afterwards.\n" "* Use `{:#?}` when printing structs to request the `Debug` representation." msgstr "" #: src/enums.md:1 msgid "# Enums" msgstr "" #: src/enums.md:3 msgid "" "The `enum` keyword allows the creation of a type which has a few\n" "different variants:" msgstr "" #: src/enums.md:6 msgid "" "```rust,editable\n" "fn generate_random_number() -> i32 {\n" " 4 // Chosen by fair dice roll. Guaranteed to be random.\n" "}\n" "\n" "#[derive(Debug)]\n" "enum CoinFlip {\n" " Heads,\n" " Tails,\n" "}\n" "\n" "fn flip_coin() -> CoinFlip {\n" " let random_number = generate_random_number();\n" " if random_number % 2 == 0 {\n" " return CoinFlip::Heads;\n" " } else {\n" " return CoinFlip::Tails;\n" " }\n" "}\n" "\n" "fn main() {\n" " println!(\"You got: {:?}\", flip_coin());\n" "}\n" "```" msgstr "" #: src/enums.md:35 msgid "" "* Enumerations allow you to collect a set of values under one type\n" "* This page offers an enum type `CoinFlip` with two variants `Heads` and `Tail`. You might note " "the namespace when using variants.\n" "* This might be a good time to compare Structs and Enums:\n" " * In both, you can have a simple version without fields (unit struct) or one with different " "types of fields (variant payloads). \n" " * In both, associated functions are defined within an `impl` block.\n" " * You could even implement the different variants of an enum with separate structs but then they " "wouldn’t be the same type as they would if they were all defined in an enum. " msgstr "" #: src/enums/variant-payloads.md:1 msgid "# Variant Payloads" msgstr "" #: src/enums/variant-payloads.md:3 msgid "" "You can define richer enums where the variants carry data. You can then use the\n" "`match` statement to extract the data from each variant:" msgstr "" #: src/enums/variant-payloads.md:6 msgid "" "```rust,editable\n" "enum WebEvent {\n" " PageLoad, // Variant without payload\n" " KeyPress(char), // Tuple struct variant\n" " Click { x: i64, y: i64 }, // Full struct variant\n" "}\n" "\n" "#[rustfmt::skip]\n" "fn inspect(event: WebEvent) {\n" " match event {\n" " WebEvent::PageLoad => println!(\"page loaded\"),\n" " WebEvent::KeyPress(c) => println!(\"pressed '{c}'\"),\n" " WebEvent::Click { x, y } => println!(\"clicked at x={x}, y={y}\"),\n" " }\n" "}\n" "\n" "fn main() {\n" " let load = WebEvent::PageLoad;\n" " let press = WebEvent::KeyPress('x');\n" " let click = WebEvent::Click { x: 20, y: 80 };\n" "\n" " inspect(load);\n" " inspect(press);\n" " inspect(click);\n" "}\n" "```" msgstr "" #: src/enums/variant-payloads.md:35 msgid "" "* The values in the enum variants can only be accessed after being pattern matched. The pattern " "binds references to the fields in the \"match arm\" after the `=>`.\n" " * The expression is matched against the patterns from top to bottom. There is no fall-through " "like in C or C++.\n" " * The match expression has a value. The value is the last expression in the match arm which was " "executed.\n" " * Starting from the top we look for what pattern matches the value then run the code following " "the arrow. Once we find a match, we stop. \n" "* Demonstrate what happens when the search is inexhaustive. Note the advantage the Rust compiler " "provides by confirming when all cases are handled. \n" "* `match` inspects a hidden discriminant field in the `enum`.\n" "* It is possible to retrieve the discriminant by calling `std::mem::discriminant()`\n" " * This is useful, for example, if implementing `PartialEq` for structs where comparing field " "values doesn't affect equality.\n" "* `WebEvent::Click { ... }` is not exactly the same as `WebEvent::Click(Click)` with a top level " "`struct Click { ... }`. The inlined version cannot implement traits, for example. \n" " " msgstr "" #: src/enums/sizes.md:1 msgid "# Enum Sizes" msgstr "" #: src/enums/sizes.md:3 msgid "Rust enums are packed tightly, taking constraints due to alignment into account:" msgstr "" #: src/enums/sizes.md:5 msgid "" "```rust,editable\n" "use std::mem::{align_of, size_of};\n" "\n" "macro_rules! dbg_size {\n" " ($t:ty) => {\n" " println!(\"{}: size {} bytes, align: {} bytes\",\n" " stringify!($t), size_of::<$t>(), align_of::<$t>());\n" " };\n" "}\n" "\n" "enum Foo {\n" " A,\n" " B,\n" "}\n" "\n" "fn main() {\n" " dbg_size!(Foo);\n" "}\n" "```" msgstr "" #: src/enums/sizes.md:25 msgid "* See the [Rust Reference](https://doc.rust-lang.org/reference/type-layout.html)." msgstr "" #: src/enums/sizes.md:31 msgid "" " * Internally Rust is using a field (discriminant) to keep track of the enum variant.\n" "\n" " * You can control the discriminant if needed (e.g., for compatibility with C):\n" " \n" " ```rust,editable\n" " #[repr(u32)]\n" " enum Bar {\n" " A, // 0\n" " B = 10000,\n" " C, // 10001\n" " }\n" " \n" " fn main() {\n" " println!(\"A: {}\", Bar::A as u32);\n" " println!(\"B: {}\", Bar::B as u32);\n" " println!(\"C: {}\", Bar::C as u32);\n" " }\n" " ```\n" "\n" " Without `repr`, the discriminant type takes 2 bytes, because 10001 fits 2\n" " bytes.\n" "\n" "\n" " * Try out other types such as\n" " \n" " * `dbg_size!(bool)`: size 1 bytes, align: 1 bytes,\n" " * `dbg_size!(Option)`: size 1 bytes, align: 1 bytes (niche optimization, see below),\n" " * `dbg_size!(&i32)`: size 8 bytes, align: 8 bytes (on a 64-bit machine),\n" " * `dbg_size!(Option<&i32>)`: size 8 bytes, align: 8 bytes (null pointer optimization, see " "below).\n" "\n" " * Niche optimization: Rust will merge use unused bit patterns for the enum\n" " discriminant.\n" "\n" " * Null pointer optimization: For [some\n" " types](https://doc.rust-lang.org/std/option/#representation), Rust guarantees\n" " that `size_of::()` equals `size_of::>()`.\n" "\n" " Example code if you want to show how the bitwise representation *may* look like in practice.\n" " It's important to note that the compiler provides no guarantees regarding this " "representation, therefore this is totally unsafe.\n" "\n" " ```rust,editable\n" " use std::mem::transmute;\n" "\n" " macro_rules! dbg_bits {\n" " ($e:expr, $bit_type:ty) => {\n" " println!(\"- {}: {:#x}\", stringify!($e), transmute::<_, $bit_type>($e));\n" " };\n" " }\n" "\n" " fn main() {\n" " // TOTALLY UNSAFE. Rust provides no guarantees about the bitwise\n" " // representation of types.\n" " unsafe {\n" " println!(\"Bitwise representation of bool\");\n" " dbg_bits!(false, u8);\n" " dbg_bits!(true, u8);\n" "\n" " println!(\"Bitwise representation of Option\");\n" " dbg_bits!(None::, u8);\n" " dbg_bits!(Some(false), u8);\n" " dbg_bits!(Some(true), u8);\n" "\n" " println!(\"Bitwise representation of Option>\");\n" " dbg_bits!(Some(Some(false)), u8);\n" " dbg_bits!(Some(Some(true)), u8);\n" " dbg_bits!(Some(None::), u8);\n" " dbg_bits!(None::>, u8);\n" "\n" " println!(\"Bitwise representation of Option<&i32>\");\n" " dbg_bits!(None::<&i32>, usize);\n" " dbg_bits!(Some(&0i32), usize);\n" " }\n" " }\n" " ```\n" "\n" " More complex example if you want to discuss what happens when we chain more than 256 " "`Option`s together.\n" "\n" " ```rust,editable\n" " #![recursion_limit = \"1000\"]\n" "\n" " use std::mem::transmute;\n" " \n" " macro_rules! dbg_bits {\n" " ($e:expr, $bit_type:ty) => {\n" " println!(\"- {}: {:#x}\", stringify!($e), transmute::<_, $bit_type>($e));\n" " };\n" " }\n" "\n" " // Macro to wrap a value in 2^n Some() where n is the number of \"@\" signs.\n" " // Increasing the recursion limit is required to evaluate this macro.\n" " macro_rules! many_options {\n" " ($value:expr) => { Some($value) };\n" " ($value:expr, @) => {\n" " Some(Some($value))\n" " };\n" " ($value:expr, @ $($more:tt)+) => {\n" " many_options!(many_options!($value, $($more)+), $($more)+)\n" " };\n" " }\n" "\n" " fn main() {\n" " // TOTALLY UNSAFE. Rust provides no guarantees about the bitwise\n" " // representation of types.\n" " unsafe {\n" " assert_eq!(many_options!(false), Some(false));\n" " assert_eq!(many_options!(false, @), Some(Some(false)));\n" " assert_eq!(many_options!(false, @@), Some(Some(Some(Some(false)))));\n" "\n" " println!(\"Bitwise representation of a chain of 128 Option's.\");\n" " dbg_bits!(many_options!(false, @@@@@@@), u8);\n" " dbg_bits!(many_options!(true, @@@@@@@), u8);\n" "\n" " println!(\"Bitwise representation of a chain of 256 Option's.\");\n" " dbg_bits!(many_options!(false, @@@@@@@@), u16);\n" " dbg_bits!(many_options!(true, @@@@@@@@), u16);\n" "\n" " println!(\"Bitwise representation of a chain of 257 Option's.\");\n" " dbg_bits!(many_options!(Some(false), @@@@@@@@), u16);\n" " dbg_bits!(many_options!(Some(true), @@@@@@@@), u16);\n" " dbg_bits!(many_options!(None::, @@@@@@@@), u16);\n" " }\n" " }\n" " ```" msgstr "" #: src/methods.md:3 msgid "" "Rust allows you to associate functions with your new types. You do this with an\n" "`impl` block:" msgstr "" #: src/methods.md:6 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Person {\n" " name: String,\n" " age: u8,\n" "}\n" "\n" "impl Person {\n" " fn say_hello(&self) {\n" " println!(\"Hello, my name is {}\", self.name);\n" " }\n" "}\n" "\n" "fn main() {\n" " let peter = Person {\n" " name: String::from(\"Peter\"),\n" " age: 27,\n" " };\n" " peter.say_hello();\n" "}\n" "```" msgstr "" #: src/methods.md:31 msgid "" "* It can be helpful to introduce methods by comparing them to functions.\n" " * Methods are called on an instance of a type (such as a struct or enum), the first parameter " "represents the instance as `self`.\n" " * Developers may choose to use methods to take advantage of method receiver syntax and to help " "keep them more organized. By using methods we can keep all the implementation code in one " "predictable place.\n" "* Point out the use of the keyword `self`, a method receiver. \n" " * Show that it is an abbreviated term for `self:&Self` and perhaps show how the struct name " "could also be used. \n" " * Explain that `Self` is a type alias for the type the `impl` block is in and can be used " "elsewhere in the block.\n" " * Note how `self` is used like other structs and dot notation can be used to refer to individual " "fields.\n" " * This might be a good time to demonstrate how the `&self` differs from `self` by modifying the " "code and trying to run say_hello twice. \n" "* We describe the distinction between method receivers next.\n" " " msgstr "" #: src/methods/receiver.md:1 msgid "# Method Receiver" msgstr "" #: src/methods/receiver.md:3 msgid "" "The `&self` above indicates that the method borrows the object immutably. There\n" "are other possible receivers for a method:" msgstr "" #: src/methods/receiver.md:6 msgid "" "* `&self`: borrows the object from the caller using a shared and immutable\n" " reference. The object can be used again afterwards.\n" "* `&mut self`: borrows the object from the caller using a unique and mutable\n" " reference. The object can be used again afterwards.\n" "* `self`: takes ownership of the object and moves it away from the caller. The\n" " method becomes the owner of the object. The object will be dropped (deallocated)\n" " when the method returns, unless its ownership is explicitly\n" " transmitted.\n" "* `mut self`: same as above, but while the method owns the object, it can\n" " mutate it too. Complete ownership does not automatically mean mutability.\n" "* No receiver: this becomes a static method on the struct. Typically used to\n" " create constructors which are called `new` by convention." msgstr "" #: src/methods/receiver.md:19 msgid "" "Beyond variants on `self`, there are also\n" "[special wrapper types](https://doc.rust-lang.org/reference/special-types-and-traits.html)\n" "allowed to be receiver types, such as `Box`." msgstr "" #: src/methods/receiver.md:25 msgid "" "Consider emphasizing \"shared and immutable\" and \"unique and mutable\". These constraints always " "come\n" "together in Rust due to borrow checker rules, and `self` is no exception. It isn't possible to\n" "reference a struct from multiple locations and call a mutating (`&mut self`) method on it." msgstr "" #: src/methods/example.md:1 src/concurrency/shared_state/example.md:1 msgid "# Example" msgstr "" #: src/methods/example.md:3 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Race {\n" " name: String,\n" " laps: Vec,\n" "}\n" "\n" "impl Race {\n" " fn new(name: &str) -> Race { // No receiver, a static method\n" " Race { name: String::from(name), laps: Vec::new() }\n" " }\n" "\n" " fn add_lap(&mut self, lap: i32) { // Exclusive borrowed read-write access to self\n" " self.laps.push(lap);\n" " }\n" "\n" " fn print_laps(&self) { // Shared and read-only borrowed access to self\n" " println!(\"Recorded {} laps for {}:\", self.laps.len(), self.name);\n" " for (idx, lap) in self.laps.iter().enumerate() {\n" " println!(\"Lap {idx}: {lap} sec\");\n" " }\n" " }\n" "\n" " fn finish(self) { // Exclusive ownership of self\n" " let total = self.laps.iter().sum::();\n" " println!(\"Race {} is finished, total lap time: {}\", self.name, total);\n" " }\n" "}\n" "\n" "fn main() {\n" " let mut race = Race::new(\"Monaco Grand Prix\");\n" " race.add_lap(70);\n" " race.add_lap(68);\n" " race.print_laps();\n" " race.add_lap(71);\n" " race.print_laps();\n" " race.finish();\n" " // race.add_lap(42);\n" "}\n" "```" msgstr "" #: src/methods/example.md:47 msgid "" "* All four methods here use a different method receiver.\n" " * You can point out how that changes what the function can do with the variable values and if/" "how it can be used again in `main`.\n" " * You can showcase the error that appears when trying to call `finish` twice.\n" "* Note that although the method receivers are different, the non-static functions are called the " "same way in the main body. Rust enables automatic referencing and dereferencing when calling " "methods. Rust automatically adds in the `&`, `*`, `muts` so that that object matches the method " "signature.\n" "* You might point out that `print_laps` is using a vector that is iterated over. We describe " "vectors in more detail in the afternoon. " msgstr "" #: src/pattern-matching.md:1 msgid "# Pattern Matching" msgstr "" #: src/pattern-matching.md:3 msgid "" "The `match` keyword let you match a value against one or more _patterns_. The\n" "comparisons are done from top to bottom and the first match wins." msgstr "" #: src/pattern-matching.md:6 msgid "The patterns can be simple values, similarly to `switch` in C and C++:" msgstr "" #: src/pattern-matching.md:8 msgid "" "```rust,editable\n" "fn main() {\n" " let input = 'x';\n" "\n" " match input {\n" " 'q' => println!(\"Quitting\"),\n" " 'a' | 's' | 'w' | 'd' => println!(\"Moving around\"),\n" " '0'..='9' => println!(\"Number input\"),\n" " _ => println!(\"Something else\"),\n" " }\n" "}\n" "```" msgstr "" #: src/pattern-matching.md:21 msgid "The `_` pattern is a wildcard pattern which matches any value." msgstr "" #: src/pattern-matching.md:26 msgid "" "* You might point out how some specific characters are being used when in a pattern\n" " * `|` as an `or`\n" " * `..` can expand as much as it needs to be\n" " * `1..=5` represents an inclusive range\n" " * `_` is a wild card\n" "* It can be useful to show how binding works, by for instance replacing a wildcard character with " "a variable, or removing the quotes around `q`.\n" "* You can demonstrate matching on a reference.\n" "* This might be a good time to bring up the concept of irrefutable patterns, as the term can show " "up in error messages.\n" " " msgstr "" #: src/pattern-matching/destructuring-enums.md:1 msgid "# Destructuring Enums" msgstr "" #: src/pattern-matching/destructuring-enums.md:3 msgid "" "Patterns can also be used to bind variables to parts of your values. This is how\n" "you inspect the structure of your types. Let us start with a simple `enum` type:" msgstr "" #: src/pattern-matching/destructuring-enums.md:6 msgid "" "```rust,editable\n" "enum Result {\n" " Ok(i32),\n" " Err(String),\n" "}\n" "\n" "fn divide_in_two(n: i32) -> Result {\n" " if n % 2 == 0 {\n" " Result::Ok(n / 2)\n" " } else {\n" " Result::Err(format!(\"cannot divide {n} into two equal parts\"))\n" " }\n" "}\n" "\n" "fn main() {\n" " let n = 100;\n" " match divide_in_two(n) {\n" " Result::Ok(half) => println!(\"{n} divided in two is {half}\"),\n" " Result::Err(msg) => println!(\"sorry, an error happened: {msg}\"),\n" " }\n" "}\n" "```" msgstr "" #: src/pattern-matching/destructuring-enums.md:29 msgid "" "Here we have used the arms to _destructure_ the `Result` value. In the first\n" "arm, `half` is bound to the value inside the `Ok` variant. In the second arm,\n" "`msg` is bound to the error message." msgstr "" #: src/pattern-matching/destructuring-enums.md:36 msgid "" "* The `if`/`else` expression is returning an enum that is later unpacked with a `match`.\n" "* You can try adding a third variant to the enum definition and displaying the errors when running " "the code. Point out the places where your code is now inexhaustive and how the compiler tries to " "give you hints." msgstr "" #: src/pattern-matching/destructuring-structs.md:1 msgid "# Destructuring Structs" msgstr "" #: src/pattern-matching/destructuring-structs.md:3 msgid "You can also destructure `structs`:" msgstr "" #: src/pattern-matching/destructuring-structs.md:5 msgid "" "```rust,editable\n" "struct Foo {\n" " x: (u32, u32),\n" " y: u32,\n" "}\n" "\n" "#[rustfmt::skip]\n" "fn main() {\n" " let foo = Foo { x: (1, 2), y: 3 };\n" " match foo {\n" " Foo { x: (1, b), y } => println!(\"x.0 = 1, b = {b}, y = {y}\"),\n" " Foo { y: 2, x: i } => println!(\"y = 2, x = {i:?}\"),\n" " Foo { y, .. } => println!(\"y = {y}, other fields were ignored\"),\n" " }\n" "}\n" "```" msgstr "" #: src/pattern-matching/destructuring-structs.md:23 msgid "" "* Change the literal values in `foo` to match with the other patterns.\n" "* Add a new field to `Foo` and make changes to the pattern as needed.\n" "* The distinction between a capture and a constant expression can be hard to\n" " spot. Try changing the `2` in the second arm to a variable, and see that it subtly\n" " doesn't work. Change it to a `const` and see it working again." msgstr "" #: src/pattern-matching/destructuring-arrays.md:1 msgid "# Destructuring Arrays" msgstr "" #: src/pattern-matching/destructuring-arrays.md:3 msgid "You can destructure arrays, tuples, and slices by matching on their elements:" msgstr "" #: src/pattern-matching/destructuring-arrays.md:5 msgid "" "```rust,editable\n" "#[rustfmt::skip]\n" "fn main() {\n" " let triple = [0, -2, 3];\n" " println!(\"Tell me about {triple:?}\");\n" " match triple {\n" " [0, y, z] => println!(\"First is 0, y = {y}, and z = {z}\"),\n" " [1, ..] => println!(\"First is 1 and the rest were ignored\"),\n" " _ => println!(\"All elements were ignored\"),\n" " }\n" "}\n" "```" msgstr "" #: src/pattern-matching/destructuring-arrays.md:21 msgid "" "* Destructuring of slices of unknown length also works with patterns of fixed length.\n" "\n" "\n" " ```rust,editable\n" " fn main() {\n" " inspect(&[0, -2, 3]);\n" " inspect(&[0, -2, 3, 4]);\n" " }\n" "\n" " #[rustfmt::skip]\n" " fn inspect(slice: &[i32]) {\n" " println!(\"Tell me about {slice:?}\");\n" " match slice {\n" " &[0, y, z] => println!(\"First is 0, y = {y}, and z = {z}\"),\n" " &[1, ..] => println!(\"First is 1 and the rest were ignored\"),\n" " _ => println!(\"All elements were ignored\"),\n" " }\n" " }\n" " ```\n" " \n" "* Create a new pattern using `_` to represent an element. \n" "* Add more values to the array.\n" "* Point out that how `..` will expand to account for different number of elements.\n" "* Show matching against the tail with patterns `[.., b]` and `[a@..,b]`" msgstr "" #: src/pattern-matching/match-guards.md:1 msgid "# Match Guards" msgstr "" #: src/pattern-matching/match-guards.md:3 msgid "" "When matching, you can add a _guard_ to a pattern. This is an arbitrary Boolean\n" "expression which will be executed if the pattern matches:" msgstr "" #: src/pattern-matching/match-guards.md:6 msgid "" "```rust,editable\n" "#[rustfmt::skip]\n" "fn main() {\n" " let pair = (2, -2);\n" " println!(\"Tell me about {pair:?}\");\n" " match pair {\n" " (x, y) if x == y => println!(\"These are twins\"),\n" " (x, y) if x + y == 0 => println!(\"Antimatter, kaboom!\"),\n" " (x, _) if x % 2 == 1 => println!(\"The first one is odd\"),\n" " _ => println!(\"No correlation...\"),\n" " }\n" "}\n" "```" msgstr "" #: src/pattern-matching/match-guards.md:23 msgid "" "* Match guards as a separate syntax feature are important and necessary when we wish to concisely " "express more complex ideas than patterns alone would allow.\n" "* They are not the same as separate `if` expression inside of the match arm. An `if` expression " "inside of the branch block (after `=>`) happens after the match arm is selected. Failing the `if` " "condition inside of that block won't result in other arms\n" "of the original `match` expression being considered. \n" "* You can use the variables defined in the pattern in your if expression.\n" "* The condition defined in the guard applies to every expression in a pattern with an `|`." msgstr "" #: src/exercises/day-2/morning.md:1 msgid "# Day 2: Morning Exercises" msgstr "" #: src/exercises/day-2/morning.md:3 msgid "We will look at implementing methods in two contexts:" msgstr "" #: src/exercises/day-2/morning.md:5 msgid "" "* Simple struct which tracks health statistics.\n" "\n" "* Multiple structs and enums for a drawing library." msgstr "" #: src/exercises/day-2/health-statistics.md:1 msgid "# Health Statistics" msgstr "" #: src/exercises/day-2/health-statistics.md:3 msgid "" "You're working on implementing a health-monitoring system. As part of that, you\n" "need to keep track of users' health statistics." msgstr "" #: src/exercises/day-2/health-statistics.md:6 msgid "" "You'll start with some stubbed functions in an `impl` block as well as a `User`\n" "struct definition. Your goal is to implement the stubbed out methods on the\n" "`User` `struct` defined in the `impl` block." msgstr "" #: src/exercises/day-2/health-statistics.md:10 msgid "" "Copy the code below to and fill in the missing\n" "methods:" msgstr "" #: src/exercises/day-2/health-statistics.md:13 msgid "" "```rust,should_panic\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_variables, dead_code)]\n" "\n" "struct User {\n" " name: String,\n" " age: u32,\n" " weight: f32,\n" "}\n" "\n" "impl User {\n" " pub fn new(name: String, age: u32, weight: f32) -> Self {\n" " unimplemented!()\n" " }\n" "\n" " pub fn name(&self) -> &str {\n" " unimplemented!()\n" " }\n" "\n" " pub fn age(&self) -> u32 {\n" " unimplemented!()\n" " }\n" "\n" " pub fn weight(&self) -> f32 {\n" " unimplemented!()\n" " }\n" "\n" " pub fn set_age(&mut self, new_age: u32) {\n" " unimplemented!()\n" " }\n" "\n" " pub fn set_weight(&mut self, new_weight: f32) {\n" " unimplemented!()\n" " }\n" "}\n" "\n" "fn main() {\n" " let bob = User::new(String::from(\"Bob\"), 32, 155.2);\n" " println!(\"I'm {} and my age is {}\", bob.name(), bob.age());\n" "}\n" "\n" "#[test]\n" "fn test_weight() {\n" " let bob = User::new(String::from(\"Bob\"), 32, 155.2);\n" " assert_eq!(bob.weight(), 155.2);\n" "}\n" "\n" "#[test]\n" "fn test_set_age() {\n" " let mut bob = User::new(String::from(\"Bob\"), 32, 155.2);\n" " assert_eq!(bob.age(), 32);\n" " bob.set_age(33);\n" " assert_eq!(bob.age(), 33);\n" "}\n" "```" msgstr "" #: src/exercises/day-2/points-polygons.md:1 msgid "# Polygon Struct" msgstr "" #: src/exercises/day-2/points-polygons.md:3 msgid "" "We will create a `Polygon` struct which contain some points. Copy the code below\n" "to and fill in the missing methods to make the\n" "tests pass:" msgstr "" #: src/exercises/day-2/points-polygons.md:7 msgid "" "```rust\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_variables, dead_code)]\n" "\n" "pub struct Point {\n" " // add fields\n" "}\n" "\n" "impl Point {\n" " // add methods\n" "}\n" "\n" "pub struct Polygon {\n" " // add fields\n" "}\n" "\n" "impl Polygon {\n" " // add methods\n" "}\n" "\n" "pub struct Circle {\n" " // add fields\n" "}\n" "\n" "impl Circle {\n" " // add methods\n" "}\n" "\n" "pub enum Shape {\n" " Polygon(Polygon),\n" " Circle(Circle),\n" "}\n" "\n" "#[cfg(test)]\n" "mod tests {\n" " use super::*;\n" "\n" " fn round_two_digits(x: f64) -> f64 {\n" " (x * 100.0).round() / 100.0\n" " }\n" "\n" " #[test]\n" " fn test_point_magnitude() {\n" " let p1 = Point::new(12, 13);\n" " assert_eq!(round_two_digits(p1.magnitude()), 17.69);\n" " }\n" "\n" " #[test]\n" " fn test_point_dist() {\n" " let p1 = Point::new(10, 10);\n" " let p2 = Point::new(14, 13);\n" " assert_eq!(round_two_digits(p1.dist(p2)), 5.00);\n" " }\n" "\n" " #[test]\n" " fn test_point_add() {\n" " let p1 = Point::new(16, 16);\n" " let p2 = p1 + Point::new(-4, 3);\n" " assert_eq!(p2, Point::new(12, 19));\n" " }\n" "\n" " #[test]\n" " fn test_polygon_left_most_point() {\n" " let p1 = Point::new(12, 13);\n" " let p2 = Point::new(16, 16);\n" "\n" " let mut poly = Polygon::new();\n" " poly.add_point(p1);\n" " poly.add_point(p2);\n" " assert_eq!(poly.left_most_point(), Some(p1));\n" " }\n" "\n" " #[test]\n" " fn test_polygon_iter() {\n" " let p1 = Point::new(12, 13);\n" " let p2 = Point::new(16, 16);\n" "\n" " let mut poly = Polygon::new();\n" " poly.add_point(p1);\n" " poly.add_point(p2);\n" "\n" " let points = poly.iter().cloned().collect::>();\n" " assert_eq!(points, vec![Point::new(12, 13), Point::new(16, 16)]);\n" " }\n" "\n" " #[test]\n" " fn test_shape_perimeters() {\n" " let mut poly = Polygon::new();\n" " poly.add_point(Point::new(12, 13));\n" " poly.add_point(Point::new(17, 11));\n" " poly.add_point(Point::new(16, 16));\n" " let shapes = vec![\n" " Shape::from(poly),\n" " Shape::from(Circle::new(Point::new(10, 20), 5)),\n" " ];\n" " let perimeters = shapes\n" " .iter()\n" " .map(Shape::perimeter)\n" " .map(round_two_digits)\n" " .collect::>();\n" " assert_eq!(perimeters, vec![15.48, 31.42]);\n" " }\n" "}\n" "\n" "#[allow(dead_code)]\n" "fn main() {}\n" "```" msgstr "" #: src/exercises/day-2/points-polygons.md:117 msgid "" "Since the method signatures are missing from the problem statements, the key part\n" "of the exercise is to specify those correctly. You don't have to modify the tests." msgstr "" #: src/exercises/day-2/points-polygons.md:120 msgid "Other interesting parts of the exercise:" msgstr "" #: src/exercises/day-2/points-polygons.md:122 msgid "" "* Derive a `Copy` trait for some structs, as in tests the methods sometimes don't borrow their " "arguments.\n" "* Discover that `Add` trait must be implemented for two objects to be addable via \"+\". Note that " "we do not discuss generics until Day 3." msgstr "" #: src/control-flow.md:1 msgid "# Control Flow" msgstr "" #: src/control-flow.md:3 msgid "" "As we have seen, `if` is an expression in Rust. It is used to conditionally\n" "evaluate one of two blocks, but the blocks can have a value which then becomes\n" "the value of the `if` expression. Other control flow expressions work similarly\n" "in Rust." msgstr "" #: src/control-flow/blocks.md:1 msgid "# Blocks" msgstr "" #: src/control-flow/blocks.md:3 msgid "" "A block in Rust has a value and a type: the value is the last expression of the\n" "block:" msgstr "" #: src/control-flow/blocks.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let x = {\n" " let y = 10;\n" " println!(\"y: {y}\");\n" " let z = {\n" " let w = {\n" " 3 + 4\n" " };\n" " println!(\"w: {w}\");\n" " y * w\n" " };\n" " println!(\"z: {z}\");\n" " z - y\n" " };\n" " println!(\"x: {x}\");\n" "}\n" "```" msgstr "" #: src/control-flow/blocks.md:25 msgid "" "The same rule is used for functions: the value of the function body is the\n" "return value:" msgstr "" #: src/control-flow/blocks.md:28 msgid "" "```rust,editable\n" "fn double(x: i32) -> i32 {\n" " x + x\n" "}\n" "\n" "fn main() {\n" " println!(\"doubled: {}\", double(7));\n" "}\n" "```" msgstr "" #: src/control-flow/blocks.md:38 msgid "However if the last expression ends with `;`, then the resulting value and type is `()`." msgstr "" #: src/control-flow/blocks.md:43 msgid "" "* The point of this slide is to show that blocks have a type and value in Rust. \n" "* You can show how the value of the block changes by changing the last line in the block. For " "instance, adding/removing a semicolon or using a `return`.\n" " " msgstr "" #: src/control-flow/if-expressions.md:1 msgid "# `if` expressions" msgstr "" #: src/control-flow/if-expressions.md:3 msgid "" "You use [`if`\n" "expressions](https://doc.rust-lang.org/reference/expressions/if-expr.html#if-expressions)\n" "exactly like `if` statements in other languages:" msgstr "" #: src/control-flow/if-expressions.md:7 msgid "" "```rust,editable\n" "fn main() {\n" " let mut x = 10;\n" " if x % 2 == 0 {\n" " x = x / 2;\n" " } else {\n" " x = 3 * x + 1;\n" " }\n" "}\n" "```" msgstr "" #: src/control-flow/if-expressions.md:18 msgid "" "In addition, you can use `if` as an expression. The last expression of each\n" "block becomes the value of the `if` expression:" msgstr "" #: src/control-flow/if-expressions.md:22 msgid "" "```rust,editable\n" "fn main() {\n" " let mut x = 10;\n" " x = if x % 2 == 0 {\n" " x / 2\n" " } else {\n" " 3 * x + 1\n" " };\n" "}\n" "```" msgstr "" #: src/control-flow/if-expressions.md:35 msgid "" "Because `if` is an expression and must have a particular type, both of its branch blocks must have " "the same type. Consider showing what happens if you add `;` after `x / 2` in the second example." msgstr "" #: src/control-flow/if-let-expressions.md:1 msgid "# `if let` expressions" msgstr "" #: src/control-flow/if-let-expressions.md:3 msgid "" "The [`if let`\n" "expression](https://doc.rust-lang.org/reference/expressions/if-expr.html#if-let-expressions)\n" "lets you execute different code depending on whether a value matches a pattern:" msgstr "" #: src/control-flow/if-let-expressions.md:7 msgid "" "```rust,editable\n" "fn main() {\n" " let arg = std::env::args().next();\n" " if let Some(value) = arg {\n" " println!(\"Program name: {value}\");\n" " } else {\n" " println!(\"Missing name?\");\n" " }\n" "}\n" "```" msgstr "" #: src/control-flow/if-let-expressions.md:18 src/control-flow/while-let-expressions.md:21 #: src/control-flow/match-expressions.md:23 msgid "" "See [pattern matching](../pattern-matching.md) for more details on patterns in\n" "Rust." msgstr "" #: src/control-flow/if-let-expressions.md:23 msgid "" "* `if let` can be more concise than `match`, e.g., when only one case is interesting. In contrast, " "`match` requires all branches to be covered.\n" "* A common usage is handling `Some` values when working with `Option`.\n" "* Unlike `match`, `if let` does not support guard clauses for pattern matching.\n" "* Since 1.65, a similar [let-else](https://doc.rust-lang.org/rust-by-example/flow_control/let_else." "html) construct allows to do a destructuring assignment, or if it fails, have a non-returning " "block branch (panic/return/break/continue):\n" "\n" " ```rust,editable\n" " fn main() {\n" " println!(\"{:?}\", second_word_to_upper(\"foo bar\"));\n" " }\n" " \n" " fn second_word_to_upper(s: &str) -> Option {\n" " let mut it = s.split(' ');\n" " let (Some(_), Some(item)) = (it.next(), it.next()) else {\n" " return None;\n" " };\n" " Some(item.to_uppercase())\n" " }" msgstr "" #: src/control-flow/while-expressions.md:1 msgid "# `while` loops" msgstr "" #: src/control-flow/while-expressions.md:3 msgid "" "The [`while` keyword](https://doc.rust-lang.org/reference/expressions/loop-expr.html#predicate-" "loops)\n" "works very similar to other languages:" msgstr "" #: src/control-flow/while-expressions.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let mut x = 10;\n" " while x != 1 {\n" " x = if x % 2 == 0 {\n" " x / 2\n" " } else {\n" " 3 * x + 1\n" " };\n" " }\n" " println!(\"Final x: {x}\");\n" "}\n" "```" msgstr "" #: src/control-flow/while-let-expressions.md:1 msgid "# `while let` loops" msgstr "" #: src/control-flow/while-let-expressions.md:3 msgid "" "Like with `if let`, there is a [`while let`](https://doc.rust-lang.org/reference/expressions/loop-" "expr.html#predicate-pattern-loops)\n" "variant which repeatedly tests a value against a pattern:" msgstr "" #: src/control-flow/while-let-expressions.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let v = vec![10, 20, 30];\n" " let mut iter = v.into_iter();\n" "\n" " while let Some(x) = iter.next() {\n" " println!(\"x: {x}\");\n" " }\n" "}\n" "```" msgstr "" #: src/control-flow/while-let-expressions.md:17 msgid "" "Here the iterator returned by `v.iter()` will return a `Option` on every\n" "call to `next()`. It returns `Some(x)` until it is done, after which it will\n" "return `None`. The `while let` lets us keep iterating through all items." msgstr "" #: src/control-flow/while-let-expressions.md:26 msgid "" "* Point out that the `while let` loop will keep going as long as the value matches the pattern.\n" "* You could rewrite the `while let` loop as an infinite loop with an if statement that breaks when " "there is no value to unwrap for `iter.next()`. The `while let` provides syntactic sugar for the " "above scenario.\n" " " msgstr "" #: src/control-flow/for-expressions.md:1 msgid "# `for` loops" msgstr "" #: src/control-flow/for-expressions.md:3 msgid "" "The [`for` loop](https://doc.rust-lang.org/std/keyword.for.html) is closely\n" "related to the [`while let` loop](while-let-expression.md). It will\n" "automatically call `into_iter()` on the expression and then iterate over it:" msgstr "" #: src/control-flow/for-expressions.md:7 msgid "" "```rust,editable\n" "fn main() {\n" " let v = vec![10, 20, 30];\n" "\n" " for x in v {\n" " println!(\"x: {x}\");\n" " }\n" " \n" " for i in (0..10).step_by(2) {\n" " println!(\"i: {i}\");\n" " }\n" "}\n" "```" msgstr "" #: src/control-flow/for-expressions.md:21 msgid "You can use `break` and `continue` here as usual." msgstr "" #: src/control-flow/for-expressions.md:25 msgid "" "* Index iteration is not a special syntax in Rust for just that case.\n" "* `(0..10)` is a range that implements an `Iterator` trait. \n" "* `step_by` is a method that returns another `Iterator` that skips every other element. \n" "* Modify the elements in the vector and explain the compiler errors. Change vector `v` to be " "mutable and the for loop to `for x in v.iter_mut()`." msgstr "" #: src/control-flow/loop-expressions.md:1 msgid "# `loop` expressions" msgstr "" #: src/control-flow/loop-expressions.md:3 msgid "" "Finally, there is a [`loop` keyword](https://doc.rust-lang.org/reference/expressions/loop-expr." "html#infinite-loops)\n" "which creates an endless loop." msgstr "" #: src/control-flow/loop-expressions.md:6 msgid "Here you must either `break` or `return` to stop the loop:" msgstr "" #: src/control-flow/loop-expressions.md:8 msgid "" "```rust,editable\n" "fn main() {\n" " let mut x = 10;\n" " loop {\n" " x = if x % 2 == 0 {\n" " x / 2\n" " } else {\n" " 3 * x + 1\n" " };\n" " if x == 1 {\n" " break;\n" " }\n" " }\n" " println!(\"Final x: {x}\");\n" "}\n" "```" msgstr "" #: src/control-flow/loop-expressions.md:27 msgid "" "* Break the `loop` with a value (e.g. `break 8`) and print it out.\n" "* Note that `loop` is the only looping construct which returns a non-trivial\n" " value. This is because it's guaranteed to be entered at least once (unlike\n" " `while` and `for` loops)." msgstr "" #: src/control-flow/match-expressions.md:1 msgid "# `match` expressions" msgstr "" #: src/control-flow/match-expressions.md:3 msgid "" "The [`match` keyword](https://doc.rust-lang.org/reference/expressions/match-expr.html)\n" "is used to match a value against one or more patterns. In that sense, it works\n" "like a series of `if let` expressions:" msgstr "" #: src/control-flow/match-expressions.md:7 msgid "" "```rust,editable\n" "fn main() {\n" " match std::env::args().next().as_deref() {\n" " Some(\"cat\") => println!(\"Will do cat things\"),\n" " Some(\"ls\") => println!(\"Will ls some files\"),\n" " Some(\"mv\") => println!(\"Let's move some files\"),\n" " Some(\"rm\") => println!(\"Uh, dangerous!\"),\n" " None => println!(\"Hmm, no program name?\"),\n" " _ => println!(\"Unknown program name!\"),\n" " }\n" "}\n" "```" msgstr "" #: src/control-flow/match-expressions.md:20 msgid "" "Like `if let`, each match arm must have the same type. The type is the last\n" "expression of the block, if any. In the example above, the type is `()`." msgstr "" #: src/control-flow/match-expressions.md:28 msgid "" "* Save the match expression to a variable and print it out.\n" "* Remove `.as_deref()` and explain the error.\n" " * `std::env::args().next()` returns an `Option`, but we cannot match against " "`String`.\n" " * `as_deref()` transforms an `Option` to `Option<&T::Target>`. In our case, this turns " "`Option` into `Option<&str>`.\n" " * We can now use pattern matching to match against the `&str` inside `Option`." msgstr "" #: src/control-flow/break-continue.md:1 msgid "# `break` and `continue`" msgstr "" #: src/control-flow/break-continue.md:3 msgid "" "- If you want to exit a loop early, use [`break`](https://doc.rust-lang.org/reference/expressions/" "loop-expr.html#break-expressions),\n" "- If you want to immediately start\n" "the next iteration use [`continue`](https://doc.rust-lang.org/reference/expressions/loop-expr." "html#continue-expressions)." msgstr "" #: src/control-flow/break-continue.md:7 msgid "" "Both `continue` and `break` can optionally take a label argument which is used\n" "to break out of nested loops:" msgstr "" #: src/control-flow/break-continue.md:10 msgid "" "```rust,editable\n" "fn main() {\n" " let v = vec![10, 20, 30];\n" " let mut iter = v.into_iter();\n" " 'outer: while let Some(x) = iter.next() {\n" " println!(\"x: {x}\");\n" " let mut i = 0;\n" " while i < x {\n" " println!(\"x: {x}, i: {i}\");\n" " i += 1;\n" " if i == 3 {\n" " break 'outer;\n" " }\n" " }\n" " }\n" "}\n" "```" msgstr "" #: src/control-flow/break-continue.md:28 msgid "In this case we break the outer loop after 3 iterations of the inner loop." msgstr "" #: src/std.md:1 msgid "# Standard Library" msgstr "" #: src/std.md:3 msgid "" "Rust comes with a standard library which helps establish a set of common types\n" "used by Rust library and programs. This way, two libraries can work together\n" "smoothly because they both use the same `String` type." msgstr "" #: src/std.md:7 msgid "The common vocabulary types include:" msgstr "" #: src/std.md:9 msgid "" "* [`Option` and `Result`](std/option-result.md) types: used for optional values\n" " and [error handling](error-handling.md).\n" "\n" "* [`String`](std/string.md): the default string type used for owned data.\n" "\n" "* [`Vec`](std/vec.md): a standard extensible vector.\n" "\n" "* [`HashMap`](std/hashmap.md): a hash map type with a configurable hashing\n" " algorithm.\n" "\n" "* [`Box`](std/box.md): an owned pointer for heap-allocated data.\n" "\n" "* [`Rc`](std/rc.md): a shared reference-counted pointer for heap-allocated data." msgstr "" #: src/std.md:25 msgid "" " * In fact, Rust contains several layers of the Standard Library: `core`, `alloc` and `std`. \n" " * `core` includes the most basic types and functions that don't depend on `libc`, allocator or\n" " even the presence of an operating system. \n" " * `alloc` includes types which require a global heap allocator, such as `Vec`, `Box` and `Arc`.\n" " * Embedded Rust applications often only use `core`, and sometimes `alloc`." msgstr "" #: src/std/option-result.md:1 msgid "# `Option` and `Result`" msgstr "" #: src/std/option-result.md:3 msgid "The types represent optional data:" msgstr "" #: src/std/option-result.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let numbers = vec![10, 20, 30];\n" " let first: Option<&i8> = numbers.first();\n" " println!(\"first: {first:?}\");\n" "\n" " let idx: Result = numbers.binary_search(&10);\n" " println!(\"idx: {idx:?}\");\n" "}\n" "```" msgstr "" #: src/std/option-result.md:18 msgid "" "* `Option` and `Result` are widely used not just in the standard library.\n" "* `Option<&T>` has zero space overhead compared to `&T`.\n" "* `Result` is the standard type to implement error handling as we will see on Day 3.\n" "* `binary_search` returns `Result`.\n" " * If found, `Result::Ok` holds the index where the element is found.\n" " * Otherwise, `Result::Err` contains the index where such an element should be inserted." msgstr "" #: src/std/string.md:1 msgid "# String" msgstr "" #: src/std/string.md:3 msgid "[`String`][1] is the standard heap-allocated growable UTF-8 string buffer:" msgstr "" #: src/std/string.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let mut s1 = String::new();\n" " s1.push_str(\"Hello\");\n" " println!(\"s1: len = {}, capacity = {}\", s1.len(), s1.capacity());\n" "\n" " let mut s2 = String::with_capacity(s1.len() + 1);\n" " s2.push_str(&s1);\n" " s2.push('!');\n" " println!(\"s2: len = {}, capacity = {}\", s2.len(), s2.capacity());\n" "\n" " let s3 = String::from(\"🇚🇭\");\n" " println!(\"s3: len = {}, number of chars = {}\", s3.len(),\n" " s3.chars().count());\n" "}\n" "```" msgstr "" #: src/std/string.md:22 msgid "" "`String` implements [`Deref`][2], which means that you can call all\n" "`str` methods on a `String`." msgstr "" #: src/std/string.md:30 msgid "" "* `String::new` returns a new empty string, use `String::with_capacity` when you know how much " "data you want to push to the string.\n" "* `String::len` returns the size of the `String` in bytes (which can be different from its length " "in characters).\n" "* `String::chars` returns an iterator over the actual characters. Note that a `char` can be " "different from what a human will consider a \"character\" due to [grapheme clusters](https://docs." "rs/unicode-segmentation/latest/unicode_segmentation/struct.Graphemes.html).\n" "* When people refer to strings they could either be talking about `&str` or `String`. \n" "* When a type implements `Deref`, the compiler will let you transparently call methods " "from `T`.\n" " * `String` implements `Deref` which transparently gives it access to `str`'s " "methods.\n" " * Write and compare `let s3 = s1.deref();` and `let s3 = &*s1`;.\n" "* `String` is implemented as a wrapper around a vector of bytes, many of the operations you see " "supported on vectors are also supported on `String`, but with some extra guarantees.\n" "* Compare the different ways to index a `String`:\n" " * To a character by using `s3.chars().nth(i).unwrap()` where `i` is in-bound, out-of-bounds.\n" " * To a substring by using `s3[0..4]`, where that slice is on character boundaries or not." msgstr "" #: src/std/vec.md:1 msgid "# `Vec`" msgstr "" #: src/std/vec.md:3 msgid "[`Vec`][1] is the standard resizable heap-allocated buffer:" msgstr "" #: src/std/vec.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let mut v1 = Vec::new();\n" " v1.push(42);\n" " println!(\"v1: len = {}, capacity = {}\", v1.len(), v1.capacity());\n" "\n" " let mut v2 = Vec::with_capacity(v1.len() + 1);\n" " v2.extend(v1.iter());\n" " v2.push(9999);\n" " println!(\"v2: len = {}, capacity = {}\", v2.len(), v2.capacity());\n" "\n" " // Canonical macro to initialize a vector with elements.\n" " let mut v3 = vec![0, 0, 1, 2, 3, 4];\n" "\n" " // Retain only the even elements.\n" " v3.retain(|x| x % 2 == 0);\n" " println!(\"{v3:?}\");\n" "\n" " // Remove consecutive duplicates.\n" " v3.dedup();\n" " println!(\"{v3:?}\");\n" "}\n" "```" msgstr "" #: src/std/vec.md:29 msgid "" "`Vec` implements [`Deref`][2], which means that you can call slice\n" "methods on a `Vec`." msgstr "" #: src/std/vec.md:37 msgid "" "* `Vec` is a type of collection, along with `String` and `HashMap`. The data it contains is " "stored\n" " on the heap. This means the amount of data doesn't need to be known at compile time. It can " "grow\n" " or shrink at runtime.\n" "* Notice how `Vec` is a generic type too, but you don't have to specify `T` explicitly. As " "always\n" " with Rust type inference, the `T` was established during the first `push` call.\n" "* `vec![...]` is a canonical macro to use instead of `Vec::new()` and it supports adding initial\n" " elements to the vector.\n" "* To index the vector you use `[` `]`, but they will panic if out of bounds. Alternatively, using\n" " `get` will return an `Option`. The `pop` function will remove the last element.\n" "* Show iterating over a vector and mutating the value:\n" " `for e in &mut v { *e += 50; }`" msgstr "" #: src/std/hashmap.md:1 msgid "# `HashMap`" msgstr "" #: src/std/hashmap.md:3 msgid "Standard hash map with protection against HashDoS attacks:" msgstr "" #: src/std/hashmap.md:5 msgid "" "```rust,editable\n" "use std::collections::HashMap;\n" "\n" "fn main() {\n" " let mut page_counts = HashMap::new();\n" " page_counts.insert(\"Adventures of Huckleberry Finn\".to_string(), 207);\n" " page_counts.insert(\"Grimms' Fairy Tales\".to_string(), 751);\n" " page_counts.insert(\"Pride and Prejudice\".to_string(), 303);\n" "\n" " if !page_counts.contains_key(\"Les Misérables\") {\n" " println!(\"We know about {} books, but not Les Misérables.\",\n" " page_counts.len());\n" " }\n" "\n" " for book in [\"Pride and Prejudice\", \"Alice's Adventure in Wonderland\"] {\n" " match page_counts.get(book) {\n" " Some(count) => println!(\"{book}: {count} pages\"),\n" " None => println!(\"{book} is unknown.\")\n" " }\n" " }\n" "\n" " // Use the .entry() method to insert a value if nothing is found.\n" " for book in [\"Pride and Prejudice\", \"Alice's Adventure in Wonderland\"] {\n" " let page_count: &mut i32 = page_counts.entry(book.to_string()).or_insert(0);\n" " *page_count += 1;\n" " }\n" "\n" " println!(\"{page_counts:#?}\");\n" "}\n" "```" msgstr "" #: src/std/hashmap.md:38 msgid "" "* `HashMap` is not defined in the prelude and needs to be brought into scope.\n" "* Try the following lines of code. The first line will see if a book is in the hashmap and if not " "return an alternative value. The second line will insert the alternative value in the hashmap if " "the book is not found.\n" "\n" " ```rust,ignore\n" " let pc1 = page_counts\n" " .get(\"Harry Potter and the Sorcerer's Stone \")\n" " .unwrap_or(&336);\n" " let pc2 = page_counts\n" " .entry(\"The Hunger Games\".to_string())\n" " .or_insert(374);\n" " ```\n" "* Unlike `vec!`, there is unfortunately no standard `hashmap!` macro.\n" " * Although, since Rust 1.56, HashMap implements [`From<[(K, V); N]>`][1], which allows us to " "easily initialize a hash map from a literal array:\n" "\n" " ```rust,ignore\n" " let page_counts = HashMap::from([\n" " (\"Harry Potter and the Sorcerer's Stone\".to_string(), 336),\n" " (\"The Hunger Games\".to_string(), 374),\n" " ]);\n" " ```\n" "\n" " * Alternatively HashMap can be built from any `Iterator` which yields key-value tuples.\n" "* We are showing `HashMap`, and avoid using `&str` as key to make examples easier. " "Using references in collections can, of course, be done,\n" " but it can lead into complications with the borrow checker.\n" " * Try removing `to_string()` from the example above and see if it still compiles. Where do you " "think we might run into issues?" msgstr "" #: src/std/box.md:1 msgid "# `Box`" msgstr "" #: src/std/box.md:3 msgid "[`Box`][1] is an owned pointer to data on the heap:" msgstr "" #: src/std/box.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let five = Box::new(5);\n" " println!(\"five: {}\", *five);\n" "}\n" "```" msgstr "" #: src/std/box.md:13 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - -. .- - - - - - -.\n" ": : : :\n" ": five : : :\n" ": +-----+ : : +-----+ :\n" ": | o---|---+-----+-->| 5 | :\n" ": +-----+ : : +-----+ :\n" ": : : :\n" ": : : :\n" "`- - - - - - -' `- - - - - - -'\n" "```" msgstr "" #: src/std/box.md:26 msgid "" "`Box` implements `Deref`, which means that you can [call methods\n" "from `T` directly on a `Box`][2]." msgstr "" #: src/std/box.md:34 msgid "" "* `Box` is like `std::unique_ptr` in C++, except that it's guaranteed to be not null. \n" "* In the above example, you can even leave out the `*` in the `println!` statement thanks to " "`Deref`. \n" "* A `Box` can be useful when you:\n" " * have a type whose size that can't be known at compile time, but the Rust compiler wants to " "know an exact size.\n" " * want to transfer ownership of a large amount of data. To avoid copying large amounts of data " "on the stack, instead store the data on the heap in a `Box` so only the pointer is moved." msgstr "" #: src/std/box-recursive.md:1 msgid "# Box with Recursive Data Structures" msgstr "" #: src/std/box-recursive.md:3 msgid "Recursive data types or data types with dynamic sizes need to use a `Box`:" msgstr "" #: src/std/box-recursive.md:5 src/std/box-niche.md:3 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "enum List {\n" " Cons(T, Box>),\n" " Nil,\n" "}\n" "\n" "fn main() {\n" " let list: List = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil))));\n" " println!(\"{list:?}\");\n" "}\n" "```" msgstr "" #: src/std/box-recursive.md:18 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - -. .- - - - - - - - - - - - - - - - - - - - - - - -.\n" ": : : :\n" ": list : : :\n" ": +------+----+----+ : : +------+----+----+ +------+----+----+ :\n" ": | Cons | 1 | o--+----+-----+--->| Cons | 2 | o--+--->| Nil | // | // | :\n" ": +------+----+----+ : : +------+----+----+ +------+----+----+ :\n" ": : : :\n" ": : : :\n" "'- - - - - - - - - - - - -' '- - - - - - - - - - - - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/std/box-recursive.md:33 msgid "" "* If the `Box` was not used here and we attempted to embed a `List` directly into the `List`,\n" "the compiler would not compute a fixed size of the struct in memory, it would look infinite.\n" "\n" "* `Box` solves this problem as it has the same size as a regular pointer and just points at the " "next\n" "element of the `List` in the heap.\n" "\n" "* Remove the `Box` in the List definition and show the compiler error. \"Recursive with " "indirection\" is a hint you might want to use a Box or reference of some kind, instead of storing " "a value directly. \n" " " msgstr "" #: src/std/box-niche.md:1 msgid "# Niche Optimization" msgstr "" #: src/std/box-niche.md:16 msgid "" "A `Box` cannot be empty, so the pointer is always valid and non-`null`. This\n" "allows the compiler to optimize the memory layout:" msgstr "" #: src/std/box-niche.md:19 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - -. .- - - - - - - - - - - - - - - - - - - - - - -.\n" ": : : :\n" ": list : : :\n" ": +----+----+ : : +----+----+ +----+------+ :\n" ": | 1 | o--+-----------+-----+--->| 2 | o--+--->| // | null | :\n" ": +----+----+ : : +----+----+ +----+------+ :\n" ": : : :\n" ": : : :\n" "`- - - - - - - - - - - - -' '- - - - - - - - - - - - - - - - - - - - - - -'\n" "```" msgstr "" #: src/std/rc.md:1 msgid "# `Rc`" msgstr "" #: src/std/rc.md:3 msgid "" "[`Rc`][1] is a reference-counted shared pointer. Use this when you need to refer\n" "to the same data from multiple places:" msgstr "" #: src/std/rc.md:6 msgid "" "```rust,editable\n" "use std::rc::Rc;\n" "\n" "fn main() {\n" " let mut a = Rc::new(10);\n" " let mut b = Rc::clone(&a);\n" "\n" " println!(\"a: {a}\");\n" " println!(\"b: {b}\");\n" "}\n" "```" msgstr "" #: src/std/rc.md:18 msgid "" "* If you need to mutate the data inside an `Rc`, you will need to wrap the data in\n" " a type such as [`Cell` or `RefCell`][2].\n" "* See [`Arc`][3] if you are in a multi-threaded context.\n" "* You can *downgrade* a shared pointer into a [`Weak`][4] pointer to create cycles\n" " that will get dropped." msgstr "" #: src/std/rc.md:31 msgid "" "* `Rc`'s count ensures that its contained value is valid for as long as there are references.\n" "* Like C++'s `std::shared_ptr`.\n" "* `Rc::clone` is cheap: it creates a pointer to the same allocation and increases the reference " "count. Does not make a deep clone and can generally be ignored when looking for performance issues " "in code.\n" "* `make_mut` actually clones the inner value if necessary (\"clone-on-write\") and returns a " "mutable reference.\n" "* Use `Rc::strong_count` to check the reference count.\n" "* Compare the different datatypes mentioned. `Box` enables (im)mutable borrows that are enforced " "at compile time. `RefCell` enables (im)mutable borrows that are enforced at run time and will " "panic if it fails at runtime.\n" "* `Rc::downgrade` gives you a *weakly reference-counted* object to\n" " create cycles that will be dropped properly (likely in combination with\n" " `RefCell`)." msgstr "" #: src/std/rc.md:41 msgid "" "```rust,editable\n" "use std::rc::{Rc, Weak};\n" "use std::cell::RefCell;\n" "\n" "#[derive(Debug)]\n" "struct Node {\n" " value: i64,\n" " parent: Option>>,\n" " children: Vec>>,\n" "}\n" "\n" "fn main() {\n" " let mut root = Rc::new(RefCell::new(Node {\n" " value: 42,\n" " parent: None,\n" " children: vec![],\n" " }));\n" " let child = Rc::new(RefCell::new(Node {\n" " value: 43,\n" " children: vec![],\n" " parent: Some(Rc::downgrade(&root))\n" " }));\n" " root.borrow_mut().children.push(child);\n" "\n" " println!(\"graph: {root:#?}\");\n" "}\n" "```" msgstr "" #: src/modules.md:1 msgid "# Modules" msgstr "" #: src/modules.md:3 msgid "We have seen how `impl` blocks let us namespace functions to a type." msgstr "" #: src/modules.md:5 msgid "Similarly, `mod` lets us namespace types and functions:" msgstr "" #: src/modules.md:7 msgid "" "```rust,editable\n" "mod foo {\n" " pub fn do_something() {\n" " println!(\"In the foo module\");\n" " }\n" "}\n" "\n" "mod bar {\n" " pub fn do_something() {\n" " println!(\"In the bar module\");\n" " }\n" "}\n" "\n" "fn main() {\n" " foo::do_something();\n" " bar::do_something();\n" "}\n" "```" msgstr "" #: src/modules.md:28 msgid "" "* Packages provide functionality and include a `Cargo.toml` file that describes how to build a " "bundle of 1+ crates.\n" "* Crates are a tree of modules, where a binary crate creates an executable and a library crate " "compiles to a library.\n" "* Modules define organization, scope, and are the focus of this section." msgstr "" #: src/modules/visibility.md:1 msgid "# Visibility" msgstr "" #: src/modules/visibility.md:3 msgid "Modules are a privacy boundary:" msgstr "" #: src/modules/visibility.md:5 msgid "" "* Module items are private by default (hides implementation details).\n" "* Parent and sibling items are always visible.\n" "* In other words, if an item is visible in module `foo`, it's visible in all the\n" " descendants of `foo`." msgstr "" #: src/modules/visibility.md:10 msgid "" "```rust,editable\n" "mod outer {\n" " fn private() {\n" " println!(\"outer::private\");\n" " }\n" "\n" " pub fn public() {\n" " println!(\"outer::public\");\n" " }\n" "\n" " mod inner {\n" " fn private() {\n" " println!(\"outer::inner::private\");\n" " }\n" "\n" " pub fn public() {\n" " println!(\"outer::inner::public\");\n" " super::private();\n" " }\n" " }\n" "}\n" "\n" "fn main() {\n" " outer::public();\n" "}\n" "```" msgstr "" #: src/modules/visibility.md:39 msgid "* Use the `pub` keyword to make modules public." msgstr "" #: src/modules/visibility.md:41 msgid "" "Additionally, there are advanced `pub(...)` specifiers to restrict the scope of public visibility." msgstr "" #: src/modules/visibility.md:43 msgid "" "* See the [Rust Reference](https://doc.rust-lang.org/reference/visibility-and-privacy.html#pubin-" "path-pubcrate-pubsuper-and-pubself).\n" "* Configuring `pub(crate)` visibility is a common pattern.\n" "* Less commonly, you can give visibility to a specific path.\n" "* In any case, visibility must be granted to an ancestor module (and all of its descendants)." msgstr "" #: src/modules/paths.md:1 msgid "# Paths" msgstr "" #: src/modules/paths.md:3 msgid "Paths are resolved as follows:" msgstr "" #: src/modules/paths.md:5 msgid "" "1. As a relative path:\n" " * `foo` or `self::foo` refers to `foo` in the current module,\n" " * `super::foo` refers to `foo` in the parent module.\n" "\n" "2. As an absolute path:\n" " * `crate::foo` refers to `foo` in the root of the current crate,\n" " * `bar::foo` refers to `foo` in the `bar` crate." msgstr "" #: src/modules/paths.md:13 msgid "" "A module can bring symbols from another module into scope with `use`.\n" "You will typically see something like this at the top of each module:" msgstr "" #: src/modules/paths.md:16 msgid "" "```rust,editable\n" "use std::collections::HashSet;\n" "use std::mem::transmute;\n" "```" msgstr "" #: src/modules/filesystem.md:1 msgid "# Filesystem Hierarchy" msgstr "" #: src/modules/filesystem.md:3 msgid "The module content can be omitted:" msgstr "" #: src/modules/filesystem.md:5 msgid "" "```rust,editable,compile_fail\n" "mod garden;\n" "```" msgstr "" #: src/modules/filesystem.md:9 msgid "The `garden` module content is found at:" msgstr "" #: src/modules/filesystem.md:11 msgid "" "* `src/garden.rs` (modern Rust 2018 style)\n" "* `src/garden/mod.rs` (older Rust 2015 style)" msgstr "" #: src/modules/filesystem.md:14 msgid "Similarly, a `garden::vegetables` module can be found at:" msgstr "" #: src/modules/filesystem.md:16 msgid "" "* `src/garden/vegetables.rs` (modern Rust 2018 style)\n" "* `src/garden/vegetables/mod.rs` (older Rust 2015 style)" msgstr "" #: src/modules/filesystem.md:19 msgid "The `crate` root is in:" msgstr "" #: src/modules/filesystem.md:21 msgid "" "* `src/lib.rs` (for a library crate)\n" "* `src/main.rs` (for a binary crate)" msgstr "" #: src/modules/filesystem.md:24 msgid "" "Modules defined in files can be documented, too, using \"inner doc comments\".\n" "These document the item that contains them -- in this case, a module." msgstr "" #: src/modules/filesystem.md:27 msgid "" "```rust,editable,compile_fail\n" "//! This module implements the garden, including a highly performant germination\n" "//! implementation.\n" "\n" "// Re-export types from this module.\n" "pub use seeds::SeedPacket;\n" "pub use garden::Garden;\n" "\n" "/// Sow the given seed packets.\n" "pub fn sow(seeds: Vec) { todo!() }\n" "\n" "/// Harvest the produce in the garden that is ready.\n" "pub fn harvest(garden: &mut Garden) { todo!() }\n" "```" msgstr "" #: src/modules/filesystem.md:44 msgid "" "* The change from `module/mod.rs` to `module.rs` doesn't preclude the use of submodules in Rust " "2018.\n" " (It was mandatory in Rust 2015.)\n" "\n" " The following is valid:\n" "\n" " ```ignore\n" " src/\n" " ├── main.rs\n" " ├── top_module.rs\n" " └── top_module/\n" " └── sub_module.rs\n" " ```\n" "\n" "* The main reason for the change is to prevent many files named `mod.rs`, which can be hard\n" " to distinguish in IDEs.\n" "\n" "* Rust will look for modules in `modulename/mod.rs` and `modulename.rs`, but this can be changed\n" " with a compiler directive:\n" "\n" " ```rust,ignore\n" " #[path = \"some/path.rs\"]\n" " mod some_module { }\n" " ```\n" "\n" " This is useful, for example, if you would like to place tests for a module in a file named\n" " `some_module_test.rs`, similar to the convention in Go." msgstr "" #: src/exercises/day-2/afternoon.md:1 msgid "# Day 2: Afternoon Exercises" msgstr "" #: src/exercises/day-2/afternoon.md:3 msgid "The exercises for this afternoon will focus on strings and iterators." msgstr "" #: src/exercises/day-2/luhn.md:1 msgid "# Luhn Algorithm" msgstr "" #: src/exercises/day-2/luhn.md:3 msgid "" "The [Luhn algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm) is used to\n" "validate credit card numbers. The algorithm takes a string as input and does the\n" "following to validate the credit card number:" msgstr "" #: src/exercises/day-2/luhn.md:7 msgid "" "* Ignore all spaces. Reject number with less than two digits.\n" "\n" "* Moving from right to left, double every second digit: for the number `1234`,\n" " we double `3` and `1`.\n" "\n" "* After doubling a digit, sum the digits. So doubling `7` becomes `14` which\n" " becomes `5`.\n" "\n" "* Sum all the undoubled and doubled digits.\n" "\n" "* The credit card number is valid if the sum ends with `0`." msgstr "" #: src/exercises/day-2/luhn.md:19 msgid "" "Copy the following code to and implement the\n" "function:" msgstr "" #: src/exercises/day-2/luhn.md:23 msgid "" "```rust\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_variables, dead_code)]\n" "\n" "pub fn luhn(cc_number: &str) -> bool {\n" " unimplemented!()\n" "}\n" "\n" "#[test]\n" "fn test_non_digit_cc_number() {\n" " assert!(!luhn(\"foo\"));\n" "}\n" "\n" "#[test]\n" "fn test_empty_cc_number() {\n" " assert!(!luhn(\"\"));\n" " assert!(!luhn(\" \"));\n" " assert!(!luhn(\" \"));\n" " assert!(!luhn(\" \"));\n" "}\n" "\n" "#[test]\n" "fn test_single_digit_cc_number() {\n" " assert!(!luhn(\"0\"));\n" "}\n" "\n" "#[test]\n" "fn test_two_digit_cc_number() {\n" " assert!(luhn(\" 0 0 \"));\n" "}\n" "\n" "#[test]\n" "fn test_valid_cc_number() {\n" " assert!(luhn(\"4263 9826 4026 9299\"));\n" " assert!(luhn(\"4539 3195 0343 6467\"));\n" " assert!(luhn(\"7992 7398 713\"));\n" "}\n" "\n" "#[test]\n" "fn test_invalid_cc_number() {\n" " assert!(!luhn(\"4223 9826 4026 9299\"));\n" " assert!(!luhn(\"4539 3195 0343 6476\"));\n" " assert!(!luhn(\"8273 1232 7352 0569\"));\n" "}\n" "\n" "#[allow(dead_code)]\n" "fn main() {}\n" "```" msgstr "" #: src/exercises/day-2/strings-iterators.md:1 msgid "# Strings and Iterators" msgstr "" #: src/exercises/day-2/strings-iterators.md:3 msgid "" "In this exercise, you are implementing a routing component of a web server. The\n" "server is configured with a number of _path prefixes_ which are matched against\n" "_request paths_. The path prefixes can contain a wildcard character which\n" "matches a full segment. See the unit tests below." msgstr "" #: src/exercises/day-2/strings-iterators.md:8 msgid "" "Copy the following code to and make the tests\n" "pass. Try avoiding allocating a `Vec` for your intermediate results:" msgstr "" #: src/exercises/day-2/strings-iterators.md:12 msgid "" "```rust\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_variables, dead_code)]\n" "\n" "pub fn prefix_matches(prefix: &str, request_path: &str) -> bool {\n" " unimplemented!()\n" "}\n" "\n" "#[test]\n" "fn test_matches_without_wildcard() {\n" " assert!(prefix_matches(\"/v1/publishers\", \"/v1/publishers\"));\n" " assert!(prefix_matches(\"/v1/publishers\", \"/v1/publishers/abc-123\"));\n" " assert!(prefix_matches(\"/v1/publishers\", \"/v1/publishers/abc/books\"));\n" "\n" " assert!(!prefix_matches(\"/v1/publishers\", \"/v1\"));\n" " assert!(!prefix_matches(\"/v1/publishers\", \"/v1/publishersBooks\"));\n" " assert!(!prefix_matches(\"/v1/publishers\", \"/v1/parent/publishers\"));\n" "}\n" "\n" "#[test]\n" "fn test_matches_with_wildcard() {\n" " assert!(prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/foo/books\"\n" " ));\n" " assert!(prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/bar/books\"\n" " ));\n" " assert!(prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/foo/books/book1\"\n" " ));\n" "\n" " assert!(!prefix_matches(\"/v1/publishers/*/books\", \"/v1/publishers\"));\n" " assert!(!prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/foo/booksByAuthor\"\n" " ));\n" "}\n" "```" msgstr "" #: src/welcome-day-3.md:1 msgid "# Welcome to Day 3" msgstr "" #: src/welcome-day-3.md:3 msgid "Today, we will cover some more advanced topics of Rust:" msgstr "" #: src/welcome-day-3.md:5 msgid "" "* Traits: deriving traits, default methods, and important standard library\n" " traits.\n" "\n" "* Generics: generic data types, generic methods, monomorphization, and trait\n" " objects.\n" "\n" "* Error handling: panics, `Result`, and the try operator `?`.\n" "\n" "* Testing: unit tests, documentation tests, and integration tests.\n" "\n" "* Unsafe Rust: raw pointers, static variables, unsafe functions, and extern\n" " functions." msgstr "" #: src/generics.md:1 msgid "# Generics" msgstr "" #: src/generics.md:3 msgid "" "Rust support generics, which lets you abstract an algorithm (such as sorting)\n" "over the types used in the algorithm." msgstr "" #: src/generics/data-types.md:1 msgid "# Generic Data Types" msgstr "" #: src/generics/data-types.md:3 msgid "You can use generics to abstract over the concrete field type:" msgstr "" #: src/generics/data-types.md:5 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Point {\n" " x: T,\n" " y: T,\n" "}\n" "\n" "fn main() {\n" " let integer = Point { x: 5, y: 10 };\n" " let float = Point { x: 1.0, y: 4.0 };\n" " println!(\"{integer:?} and {float:?}\");\n" "}\n" "```" msgstr "" #: src/generics/data-types.md:21 msgid "" "* Try declaring a new variable `let p = Point { x: 5, y: 10.0 };`.\n" "\n" "* Fix the code to allow points that have elements of different types." msgstr "" #: src/generics/methods.md:1 msgid "# Generic Methods" msgstr "" #: src/generics/methods.md:3 msgid "You can declare a generic type on your `impl` block:" msgstr "" #: src/generics/methods.md:5 msgid "" "```rust,editable\n" "#[derive(Debug)]\n" "struct Point(T, T);\n" "\n" "impl Point {\n" " fn x(&self) -> &T {\n" " &self.0 // + 10\n" " }\n" "\n" " // fn set_x(&mut self, x: T)\n" "}\n" "\n" "fn main() {\n" " let p = Point(5, 10);\n" " println!(\"p.x = {}\", p.x());\n" "}\n" "```" msgstr "" #: src/generics/methods.md:25 msgid "" "* *Q:* Why `T` is specified twice in `impl Point {}`? Isn't that redundant?\n" " * This is because it is a generic implementation section for generic type. They are " "independently generic.\n" " * It means these methods are defined for any `T`.\n" " * It is possible to write `impl Point { .. }`. \n" " * `Point` is still generic and you can use `Point`, but methods in this block will only " "be available for `Point`." msgstr "" #: src/generics/monomorphization.md:1 msgid "# Monomorphization" msgstr "" #: src/generics/monomorphization.md:3 msgid "Generic code is turned into non-generic code based on the call sites:" msgstr "" #: src/generics/monomorphization.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let integer = Some(5);\n" " let float = Some(5.0);\n" "}\n" "```" msgstr "" #: src/generics/monomorphization.md:12 msgid "behaves as if you wrote" msgstr "" #: src/generics/monomorphization.md:14 msgid "" "```rust,editable\n" "enum Option_i32 {\n" " Some(i32),\n" " None,\n" "}\n" "\n" "enum Option_f64 {\n" " Some(f64),\n" " None,\n" "}\n" "\n" "fn main() {\n" " let integer = Option_i32::Some(5);\n" " let float = Option_f64::Some(5.0);\n" "}\n" "```" msgstr "" #: src/generics/monomorphization.md:31 msgid "" "This is a zero-cost abstraction: you get exactly the same result as if you had\n" "hand-coded the data structures without the abstraction." msgstr "" #: src/traits.md:1 msgid "# Traits" msgstr "" #: src/traits.md:3 msgid "Rust lets you abstract over types with traits. They're similar to interfaces:" msgstr "" #: src/traits.md:5 msgid "" "```rust,editable\n" "trait Pet {\n" " fn name(&self) -> String;\n" "}\n" "\n" "struct Dog {\n" " name: String,\n" "}\n" "\n" "struct Cat;\n" "\n" "impl Pet for Dog {\n" " fn name(&self) -> String {\n" " self.name.clone()\n" " }\n" "}\n" "\n" "impl Pet for Cat {\n" " fn name(&self) -> String {\n" " String::from(\"The cat\") // No name, cats won't respond to it anyway.\n" " }\n" "}\n" "\n" "fn greet(pet: &P) {\n" " println!(\"Who's a cutie? {} is!\", pet.name());\n" "}\n" "\n" "fn main() {\n" " let fido = Dog { name: \"Fido\".into() };\n" " greet(&fido);\n" "\n" " let captain_floof = Cat;\n" " greet(&captain_floof);\n" "}\n" "```" msgstr "" #: src/traits/trait-objects.md:1 msgid "# Trait Objects" msgstr "" #: src/traits/trait-objects.md:3 msgid "Trait objects allow for values of different types, for instance in a collection:" msgstr "" #: src/traits/trait-objects.md:5 msgid "" "```rust,editable\n" "trait Pet {\n" " fn name(&self) -> String;\n" "}\n" "\n" "struct Dog {\n" " name: String,\n" "}\n" "\n" "struct Cat;\n" "\n" "impl Pet for Dog {\n" " fn name(&self) -> String {\n" " self.name.clone()\n" " }\n" "}\n" "\n" "impl Pet for Cat {\n" " fn name(&self) -> String {\n" " String::from(\"The cat\") // No name, cats won't respond to it anyway.\n" " }\n" "}\n" "\n" "fn main() {\n" " let pets: Vec> = vec![\n" " Box::new(Cat),\n" " Box::new(Dog { name: String::from(\"Fido\") }),\n" " ];\n" " for pet in pets {\n" " println!(\"Hello {}!\", pet.name());\n" " }\n" "}\n" "```" msgstr "" #: src/traits/trait-objects.md:40 msgid "Memory layout after allocating `pets`:" msgstr "" #: src/traits/trait-objects.md:42 msgid "" "```bob\n" " Stack Heap\n" ".- - - - - - - - - - - - - -. .- - - - - - - - - - - - - - - - - - - - - - -.\n" ": : : :\n" ": pets : : :\n" ": +-----------+-------+ : : +-----+-----+ :\n" ": | ptr | o---+---+-----+-->| o o | o o | :\n" ": | len | 2 | : : +-|-|-+-|-|-+ :\n" ": | capacity | 2 | : : | | | | +---------------+ :\n" ": +-----------+-------+ : : | | | '-->| name: \"Fido\" | :\n" ": : : | | | +---------------+ :\n" "`- - - - - - - - - - - - - -' : | | | :\n" " : | | | +----------------------+ : \n" " : | | '---->| \"::name\" | :\n" " : | | +----------------------+ : \n" " : | | : \n" " : | | +-+ : \n" " : | '-->|\\| : \n" " : | +-+ : \n" " : | : \n" " : | +----------------------+ : \n" " : '---->| \"::name\" | : \n" " : +----------------------+ :\n" " : :\n" " '- - - - - - - - - - - - - - - - - - - - - - -'\n" "\n" "```" msgstr "" #: src/traits/trait-objects.md:72 msgid "" "* Types that implement a given trait may be of different sizes. This makes it impossible to have " "things like `Vec` in the example above.\n" "* `dyn Pet` is a way to tell the compiler about a dynamically sized type that implements `Pet`.\n" "* In the example, `pets` holds *fat pointers* to objects that implement `Pet`. The fat pointer " "consists of two components, a pointer to the actual object and a pointer to the virtual method " "table for the `Pet` implementation of that particular object.\n" "* Compare these outputs in the above example:\n" " ```rust,ignore\n" " println!(\"{} {}\", std::mem::size_of::(), std::mem::size_of::());\n" " println!(\"{} {}\", std::mem::size_of::<&Dog>(), std::mem::size_of::<&Cat>());\n" " println!(\"{}\", std::mem::size_of::<&dyn Pet>());\n" " println!(\"{}\", std::mem::size_of::>());\n" " ```" msgstr "" #: src/traits/deriving-traits.md:1 msgid "# Deriving Traits" msgstr "" #: src/traits/deriving-traits.md:3 msgid "You can let the compiler derive a number of traits:" msgstr "" #: src/traits/deriving-traits.md:5 msgid "" "```rust,editable\n" "#[derive(Debug, Clone, PartialEq, Eq, Default)]\n" "struct Player {\n" " name: String,\n" " strength: u8,\n" " hit_points: u8,\n" "}\n" "\n" "fn main() {\n" " let p1 = Player::default();\n" " let p2 = p1.clone();\n" " println!(\"Is {:?}\\nequal to {:?}?\\nThe answer is {}!\", &p1, &p2,\n" " if p1 == p2 { \"yes\" } else { \"no\" });\n" "}\n" "```" msgstr "" #: src/traits/default-methods.md:1 msgid "# Default Methods" msgstr "" #: src/traits/default-methods.md:3 msgid "Traits can implement behavior in terms of other trait methods:" msgstr "" #: src/traits/default-methods.md:5 msgid "" "```rust,editable\n" "trait Equals {\n" " fn equal(&self, other: &Self) -> bool;\n" " fn not_equal(&self, other: &Self) -> bool {\n" " !self.equal(other)\n" " }\n" "}\n" "\n" "#[derive(Debug)]\n" "struct Centimeter(i16);\n" "\n" "impl Equals for Centimeter {\n" " fn equal(&self, other: &Centimeter) -> bool {\n" " self.0 == other.0\n" " }\n" "}\n" "\n" "fn main() {\n" " let a = Centimeter(10);\n" " let b = Centimeter(20);\n" " println!(\"{a:?} equals {b:?}: {}\", a.equal(&b));\n" " println!(\"{a:?} not_equals {b:?}: {}\", a.not_equal(&b));\n" "}\n" "```" msgstr "" #: src/traits/default-methods.md:32 msgid "" "* Traits may specify pre-implemented (default) methods and methods that users are required to\n" " implement themselves. Methods with default implementations can rely on required methods.\n" "\n" "* Move method `not_equal` to a new trait `NotEqual`.\n" "\n" "* Make `NotEqual` a super trait for `Equal`.\n" " ```rust,editable,compile_fail\n" " trait NotEqual: Equals {\n" " fn not_equal(&self, other: &Self) -> bool {\n" " !self.equal(other)\n" " }\n" " }\n" " ```\n" "\n" "* Provide a blanket implementation of `NotEqual` for `Equal`.\n" " ```rust,editable,compile_fail\n" " trait NotEqual {\n" " fn not_equal(&self, other: &Self) -> bool;\n" " }\n" "\n" " impl NotEqual for T where T: Equals {\n" " fn not_equal(&self, other: &Self) -> bool {\n" " !self.equal(other)\n" " }\n" " }\n" " ```\n" " * With the blanket implementation, you no longer need `NotEqual` as a super trait for `Equal`.\n" " " msgstr "" #: src/traits/trait-bounds.md:1 msgid "# Trait Bounds" msgstr "" #: src/traits/trait-bounds.md:3 msgid "" "When working with generics, you often want to require the types to implement\n" "some trait, so that you can call this trait's methods." msgstr "" #: src/traits/trait-bounds.md:6 msgid "You can do this with `T: Trait` or `impl Trait`:" msgstr "" #: src/traits/trait-bounds.md:8 msgid "" "```rust,editable\n" "fn duplicate(a: T) -> (T, T) {\n" " (a.clone(), a.clone())\n" "}\n" "\n" "// Syntactic sugar for:\n" "// fn add_42_millions>(x: T) -> i32 {\n" "fn add_42_millions(x: impl Into) -> i32 {\n" " x.into() + 42_000_000\n" "}\n" "\n" "// struct NotClonable;\n" "\n" "fn main() {\n" " let foo = String::from(\"foo\");\n" " let pair = duplicate(foo);\n" " println!(\"{pair:?}\");\n" "\n" " let many = add_42_millions(42_i8);\n" " println!(\"{many}\");\n" " let many_more = add_42_millions(10_000_000);\n" " println!(\"{many_more}\");\n" "}\n" "```" msgstr "" #: src/traits/trait-bounds.md:35 msgid "Show a `where` clause, students will encounter it when reading code." msgstr "" #: src/traits/trait-bounds.md:37 msgid "" "```rust,ignore\n" "fn duplicate(a: T) -> (T, T)\n" "where\n" " T: Clone,\n" "{\n" " (a.clone(), a.clone())\n" "}\n" "```" msgstr "" #: src/traits/trait-bounds.md:46 msgid "" "* It declutters the function signature if you have many parameters.\n" "* It has additional features making it more powerful.\n" " * If someone asks, the extra feature is that the type on the left of \":\" can be arbitrary, " "like `Option`.\n" " " msgstr "" #: src/traits/impl-trait.md:1 msgid "# `impl Trait`" msgstr "" #: src/traits/impl-trait.md:3 msgid "" "Similar to trait bounds, an `impl Trait` syntax can be used in function\n" "arguments and return values:" msgstr "" #: src/traits/impl-trait.md:6 msgid "" "```rust,editable\n" "use std::fmt::Display;\n" "\n" "fn get_x(name: impl Display) -> impl Display {\n" " format!(\"Hello {name}\")\n" "}\n" "\n" "fn main() {\n" " let x = get_x(\"foo\");\n" " println!(\"{x}\");\n" "}\n" "```" msgstr "" #: src/traits/impl-trait.md:19 msgid "* `impl Trait` allows you to work with types which you cannot name." msgstr "" #: src/traits/impl-trait.md:23 msgid "The meaning of `impl Trait` is a bit different in the different positions." msgstr "" #: src/traits/impl-trait.md:25 msgid "" "* For a parameter, `impl Trait` is like an anonymous generic parameter with a trait bound.\n" "\n" "* For a return type, it means that the return type is some concrete type that implements the " "trait,\n" " without naming the type. This can be useful when you don't want to expose the concrete type in " "a\n" " public API.\n" "\n" " Inference is hard in return position. A function returning `impl Foo` picks\n" " the concrete type it returns, without writing it out in the source. A function\n" " returning a generic type like `collect() -> B` can return any type\n" " satisfying `B`, and the caller may need to choose one, such as with `let x:\n" " Vec<_> = foo.collect()` or with the turbofish, `foo.collect::>()`." msgstr "" #: src/traits/impl-trait.md:37 msgid "" "This example is great, because it uses `impl Display` twice. It helps to explain that\n" "nothing here enforces that it is _the same_ `impl Display` type. If we used a single \n" "`T: Display`, it would enforce the constraint that input `T` and return `T` type are the same " "type.\n" "It would not work for this particular function, as the type we expect as input is likely not\n" "what `format!` returns. If we wanted to do the same via `: Display` syntax, we'd need two\n" "independent generic parameters." msgstr "" #: src/traits/important-traits.md:1 msgid "# Important Traits" msgstr "" #: src/traits/important-traits.md:3 msgid "We will now look at some of the most common traits of the Rust standard library:" msgstr "" #: src/traits/important-traits.md:5 msgid "" "* [`Iterator`][1] and [`IntoIterator`][2] used in `for` loops,\n" "* [`From`][3] and [`Into`][4] used to convert values,\n" "* [`Read`][5] and [`Write`][6] used for IO,\n" "* [`Add`][7], [`Mul`][8], ... used for operator overloading, and\n" "* [`Drop`][9] used for defining destructors.\n" "* [`Default`][10] used to construct a default instance of a type." msgstr "" #: src/traits/iterator.md:1 msgid "# Iterators" msgstr "" #: src/traits/iterator.md:3 msgid "You can implement the [`Iterator`][1] trait on your own types:" msgstr "" #: src/traits/iterator.md:5 msgid "" "```rust,editable\n" "struct Fibonacci {\n" " curr: u32,\n" " next: u32,\n" "}\n" "\n" "impl Iterator for Fibonacci {\n" " type Item = u32;\n" "\n" " fn next(&mut self) -> Option {\n" " let new_next = self.curr + self.next;\n" " self.curr = self.next;\n" " self.next = new_next;\n" " Some(self.curr)\n" " }\n" "}\n" "\n" "fn main() {\n" " let fib = Fibonacci { curr: 0, next: 1 };\n" " for (i, n) in fib.enumerate().take(5) {\n" " println!(\"fib({i}): {n}\");\n" " }\n" "}\n" "```" msgstr "" #: src/traits/iterator.md:32 msgid "" "* The `Iterator` trait implements many common functional programming operations over collections \n" " (e.g. `map`, `filter`, `reduce`, etc). This is the trait where you can find all the " "documentation\n" " about them. In Rust these functions should produce the code as efficient as equivalent " "imperative\n" " implementations.\n" " \n" "* `IntoIterator` is the trait that makes for loops work. It is implemented by collection types " "such as\n" " `Vec` and references to them such as `&Vec` and `&[T]`. Ranges also implement it. This is " "why\n" " you can iterate over a vector with `for i in some_vec { .. }` but\n" " `some_vec.next()` doesn't exist." msgstr "" #: src/traits/from-iterator.md:1 msgid "# FromIterator" msgstr "" #: src/traits/from-iterator.md:3 msgid "[`FromIterator`][1] lets you build a collection from an [`Iterator`][2]." msgstr "" #: src/traits/from-iterator.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let primes = vec![2, 3, 5, 7];\n" " let prime_squares = primes\n" " .into_iter()\n" " .map(|prime| prime * prime)\n" " .collect::>();\n" "}\n" "```" msgstr "" #: src/traits/from-iterator.md:17 msgid "" "`Iterator` implements\n" "`fn collect(self) -> B\n" "where\n" " B: FromIterator,\n" " Self: Sized`" msgstr "" #: src/traits/from-iterator.md:23 msgid "" "There are also implementations which let you do cool things like convert an\n" "`Iterator>` into a `Result, E>`." msgstr "" #: src/traits/from-into.md:1 msgid "# `From` and `Into`" msgstr "" #: src/traits/from-into.md:3 msgid "Types implement [`From`][1] and [`Into`][2] to facilitate type conversions:" msgstr "" #: src/traits/from-into.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let s = String::from(\"hello\");\n" " let addr = std::net::Ipv4Addr::from([127, 0, 0, 1]);\n" " let one = i16::from(true);\n" " let bigger = i32::from(123i16);\n" " println!(\"{s}, {addr}, {one}, {bigger}\");\n" "}\n" "```" msgstr "" #: src/traits/from-into.md:15 msgid "[`Into`][2] is automatically implemented when [`From`][1] is implemented:" msgstr "" #: src/traits/from-into.md:17 msgid "" "```rust,editable\n" "fn main() {\n" " let s: String = \"hello\".into();\n" " let addr: std::net::Ipv4Addr = [127, 0, 0, 1].into();\n" " let one: i16 = true.into();\n" " let bigger: i32 = 123i16.into();\n" " println!(\"{s}, {addr}, {one}, {bigger}\");\n" "}\n" "```" msgstr "" #: src/traits/from-into.md:29 msgid "" "* That's why it is common to only implement `From`, as your type will get `Into` implementation " "too.\n" "* When declaring a function argument input type like \"anything that can be converted into a " "`String`\", the rule is opposite, you should use `Into`.\n" " Your function will accept types that implement `From` and those that _only_ implement `Into`.\n" " " msgstr "" #: src/traits/read-write.md:1 msgid "# `Read` and `Write`" msgstr "" #: src/traits/read-write.md:3 msgid "Using [`Read`][1] and [`BufRead`][2], you can abstract over `u8` sources:" msgstr "" #: src/traits/read-write.md:5 msgid "" "```rust,editable\n" "use std::io::{BufRead, BufReader, Read, Result};\n" "\n" "fn count_lines(reader: R) -> usize {\n" " let buf_reader = BufReader::new(reader);\n" " buf_reader.lines().count()\n" "}\n" "\n" "fn main() -> Result<()> {\n" " let slice: &[u8] = b\"foo\\nbar\\nbaz\\n\";\n" " println!(\"lines in slice: {}\", count_lines(slice));\n" "\n" " let file = std::fs::File::open(std::env::current_exe()?)?;\n" " println!(\"lines in file: {}\", count_lines(file));\n" " Ok(())\n" "}\n" "```" msgstr "" #: src/traits/read-write.md:23 msgid "Similarly, [`Write`][3] lets you abstract over `u8` sinks:" msgstr "" #: src/traits/read-write.md:25 msgid "" "```rust,editable\n" "use std::io::{Result, Write};\n" "\n" "fn log(writer: &mut W, msg: &str) -> Result<()> {\n" " writer.write_all(msg.as_bytes())?;\n" " writer.write_all(\"\\n\".as_bytes())\n" "}\n" "\n" "fn main() -> Result<()> {\n" " let mut buffer = Vec::new();\n" " log(&mut buffer, \"Hello\")?;\n" " log(&mut buffer, \"World\")?;\n" " println!(\"Logged: {:?}\", buffer);\n" " Ok(())\n" "}\n" "```" msgstr "" #: src/traits/drop.md:1 msgid "# The `Drop` Trait" msgstr "" #: src/traits/drop.md:3 msgid "Values which implement [`Drop`][1] can specify code to run when they go out of scope:" msgstr "" #: src/traits/drop.md:5 msgid "" "```rust,editable\n" "struct Droppable {\n" " name: &'static str,\n" "}\n" "\n" "impl Drop for Droppable {\n" " fn drop(&mut self) {\n" " println!(\"Dropping {}\", self.name);\n" " }\n" "}\n" "\n" "fn main() {\n" " let a = Droppable { name: \"a\" };\n" " {\n" " let b = Droppable { name: \"b\" };\n" " {\n" " let c = Droppable { name: \"c\" };\n" " let d = Droppable { name: \"d\" };\n" " println!(\"Exiting block B\");\n" " }\n" " println!(\"Exiting block A\");\n" " }\n" " drop(a);\n" " println!(\"Exiting main\");\n" "}\n" "```" msgstr "" #: src/traits/drop.md:34 src/traits/operators.md:26 msgid "Discussion points:" msgstr "" #: src/traits/drop.md:36 msgid "" "* Why doesn't `Drop::drop` take `self`?\n" " * Short-answer: If it did, `std::mem::drop` would be called at the end of\n" " the block, resulting in another call to `Drop::drop`, and a stack\n" " overflow!\n" "* Try replacing `drop(a)` with `a.drop()`." msgstr "" #: src/traits/default.md:1 msgid "# The `Default` Trait" msgstr "" #: src/traits/default.md:3 msgid "[`Default`][1] trait provides a default implementation of a trait." msgstr "" #: src/traits/default.md:5 msgid "" "```rust,editable\n" "#[derive(Debug, Default)]\n" "struct Derived {\n" " x: u32,\n" " y: String,\n" " z: Implemented,\n" "}\n" "\n" "#[derive(Debug)]\n" "struct Implemented(String);\n" "\n" "impl Default for Implemented {\n" " fn default() -> Self {\n" " Self(\"John Smith\".into())\n" " }\n" "}\n" "\n" "fn main() {\n" " let default_struct: Derived = Default::default();\n" " println!(\"{default_struct:#?}\");\n" "\n" " let almost_default_struct = Derived {\n" " y: \"Y is set!\".into(),\n" " ..Default::default()\n" " };\n" " println!(\"{almost_default_struct:#?}\");\n" "\n" " let nothing: Option = None;\n" " println!(\"{:#?}\", nothing.unwrap_or_default());\n" "}\n" "\n" "```" msgstr "" #: src/traits/default.md:40 msgid "" " * It can be implemented directly or it can be derived via `#[derive(Default)]`.\n" " * Derived implementation will produce an instance where all fields are set to their default " "values.\n" " * This means all types in the struct must implement `Default` too.\n" " * Standard Rust types often implement `Default` with reasonable values (e.g. `0`, `\"\"`, etc).\n" " * The partial struct copy works nicely with default.\n" " * Rust standard library is aware that types can implement `Default` and provides convenience " "methods that use it." msgstr "" #: src/traits/operators.md:1 msgid "# `Add`, `Mul`, ..." msgstr "" #: src/traits/operators.md:3 msgid "Operator overloading is implemented via traits in [`std::ops`][1]:" msgstr "" #: src/traits/operators.md:5 msgid "" "```rust,editable\n" "#[derive(Debug, Copy, Clone)]\n" "struct Point { x: i32, y: i32 }\n" "\n" "impl std::ops::Add for Point {\n" " type Output = Self;\n" "\n" " fn add(self, other: Self) -> Self {\n" " Self {x: self.x + other.x, y: self.y + other.y}\n" " }\n" "}\n" "\n" "fn main() {\n" " let p1 = Point { x: 10, y: 20 };\n" " let p2 = Point { x: 100, y: 200 };\n" " println!(\"{:?} + {:?} = {:?}\", p1, p2, p1 + p2);\n" "}\n" "```" msgstr "" #: src/traits/operators.md:28 msgid "" "* You could implement `Add` for `&Point`. In which situations is that useful? \n" " * Answer: `Add:add` consumes `self`. If type `T` for which you are\n" " overloading the operator is not `Copy`, you should consider overloading\n" " the operator for `&T` as well. This avoids unnecessary cloning on the\n" " call site.\n" "* Why is `Output` an associated type? Could it be made a type parameter?\n" " * Short answer: Type parameters are controlled by the caller, but\n" " associated types (like `Output`) are controlled by the implementor of a\n" " trait." msgstr "" #: src/traits/closures.md:1 msgid "# Closures" msgstr "" #: src/traits/closures.md:3 msgid "" "Closures or lambda expressions have types which cannot be named. However, they\n" "implement special [`Fn`](https://doc.rust-lang.org/std/ops/trait.Fn.html),\n" "[`FnMut`](https://doc.rust-lang.org/std/ops/trait.FnMut.html), and\n" "[`FnOnce`](https://doc.rust-lang.org/std/ops/trait.FnOnce.html) traits:" msgstr "" #: src/traits/closures.md:8 msgid "" "```rust,editable\n" "fn apply_with_log(func: impl FnOnce(i32) -> i32, input: i32) -> i32 {\n" " println!(\"Calling function on {input}\");\n" " func(input)\n" "}\n" "\n" "fn main() {\n" " let add_3 = |x| x + 3;\n" " let mul_5 = |x| x * 5;\n" "\n" " println!(\"add_3: {}\", apply_with_log(add_3, 10));\n" " println!(\"mul_5: {}\", apply_with_log(mul_5, 20));\n" "}\n" "```" msgstr "" #: src/traits/closures.md:25 msgid "If you have an `FnOnce`, you may only call it once. It might consume captured values." msgstr "" #: src/traits/closures.md:27 msgid "" "An `FnMut` might mutate captured values, so you can call it multiple times but not concurrently." msgstr "" #: src/traits/closures.md:29 msgid "" "An `Fn` neither consumes nor mutates captured values, or perhaps captures nothing at all, so it " "can\n" "be called multiple times concurrently." msgstr "" #: src/traits/closures.md:32 msgid "" "`FnMut` is a subtype of `FnOnce`. `Fn` is a subtype of `FnMut` and `FnOnce`. I.e. you can use an\n" "`FnMut` wherever an `FnOnce` is called for, and you can use an `Fn` wherever an `FnMut` or " "`FnOnce`\n" "is called for." msgstr "" #: src/traits/closures.md:36 msgid "`move` closures only implement `FnOnce`." msgstr "" #: src/exercises/day-3/morning.md:1 msgid "# Day 3: Morning Exercises" msgstr "" #: src/exercises/day-3/morning.md:3 msgid "We will design a classical GUI library traits and trait objects." msgstr "" #: src/exercises/day-3/simple-gui.md:1 msgid "# A Simple GUI Library" msgstr "" #: src/exercises/day-3/simple-gui.md:3 msgid "" "Let us design a classical GUI library using our new knowledge of traits and\n" "trait objects." msgstr "" #: src/exercises/day-3/simple-gui.md:6 msgid "We will have a number of widgets in our library:" msgstr "" #: src/exercises/day-3/simple-gui.md:8 msgid "" "* `Window`: has a `title` and contains other widgets.\n" "* `Button`: has a `label` and a callback function which is invoked when the\n" " button is pressed.\n" "* `Label`: has a `label`." msgstr "" #: src/exercises/day-3/simple-gui.md:13 msgid "The widgets will implement a `Widget` trait, see below." msgstr "" #: src/exercises/day-3/simple-gui.md:15 msgid "" "Copy the code below to , fill in the missing\n" "`draw_into` methods so that you implement the `Widget` trait:" msgstr "" #: src/exercises/day-3/simple-gui.md:18 msgid "" "```rust,should_panic\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_imports, unused_variables, dead_code)]\n" "\n" "pub trait Widget {\n" " /// Natural width of `self`.\n" " fn width(&self) -> usize;\n" "\n" " /// Draw the widget into a buffer.\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write);\n" "\n" " /// Draw the widget on standard output.\n" " fn draw(&self) {\n" " let mut buffer = String::new();\n" " self.draw_into(&mut buffer);\n" " println!(\"{buffer}\");\n" " }\n" "}\n" "\n" "pub struct Label {\n" " label: String,\n" "}\n" "\n" "impl Label {\n" " fn new(label: &str) -> Label {\n" " Label {\n" " label: label.to_owned(),\n" " }\n" " }\n" "}\n" "\n" "pub struct Button {\n" " label: Label,\n" " callback: Box,\n" "}\n" "\n" "impl Button {\n" " fn new(label: &str, callback: Box) -> Button {\n" " Button {\n" " label: Label::new(label),\n" " callback,\n" " }\n" " }\n" "}\n" "\n" "pub struct Window {\n" " title: String,\n" " widgets: Vec>,\n" "}\n" "\n" "impl Window {\n" " fn new(title: &str) -> Window {\n" " Window {\n" " title: title.to_owned(),\n" " widgets: Vec::new(),\n" " }\n" " }\n" "\n" " fn add_widget(&mut self, widget: Box) {\n" " self.widgets.push(widget);\n" " }\n" "\n" " fn inner_width(&self) -> usize {\n" " std::cmp::max(\n" " self.title.chars().count(),\n" " self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),\n" " )\n" " }\n" "}\n" "\n" "\n" "impl Widget for Label {\n" " fn width(&self) -> usize {\n" " unimplemented!()\n" " }\n" "\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {\n" " unimplemented!()\n" " }\n" "}\n" "\n" "impl Widget for Button {\n" " fn width(&self) -> usize {\n" " unimplemented!()\n" " }\n" "\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {\n" " unimplemented!()\n" " }\n" "}\n" "\n" "impl Widget for Window {\n" " fn width(&self) -> usize {\n" " unimplemented!()\n" " }\n" "\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {\n" " unimplemented!()\n" " }\n" "}\n" "\n" "fn main() {\n" " let mut window = Window::new(\"Rust GUI Demo 1.23\");\n" " window.add_widget(Box::new(Label::new(\"This is a small text GUI demo.\")));\n" " window.add_widget(Box::new(Button::new(\n" " \"Click me!\",\n" " Box::new(|| println!(\"You clicked the button!\")),\n" " )));\n" " window.draw();\n" "}\n" "```" msgstr "" #: src/exercises/day-3/simple-gui.md:130 msgid "The output of the above program can be something simple like this:" msgstr "" #: src/exercises/day-3/simple-gui.md:132 msgid "" "```text\n" "========\n" "Rust GUI Demo 1.23\n" "========\n" "\n" "This is a small text GUI demo.\n" "\n" "| Click me! |\n" "```" msgstr "" #: src/exercises/day-3/simple-gui.md:142 msgid "" "If you want to draw aligned text, you can use the\n" "[fill/alignment](https://doc.rust-lang.org/std/fmt/index.html#fillalignment)\n" "formatting operators. In particular, notice how you can pad with different\n" "characters (here a `'/'`) and how you can control alignment:" msgstr "" #: src/exercises/day-3/simple-gui.md:147 msgid "" "```rust,editable\n" "fn main() {\n" " let width = 10;\n" " println!(\"left aligned: |{:/width$}|\", \"foo\");\n" "}\n" "```" msgstr "" #: src/exercises/day-3/simple-gui.md:156 msgid "Using such alignment tricks, you can for example produce output like this:" msgstr "" #: src/exercises/day-3/simple-gui.md:158 msgid "" "```text\n" "+--------------------------------+\n" "| Rust GUI Demo 1.23 |\n" "+================================+\n" "| This is a small text GUI demo. |\n" "| +-----------+ |\n" "| | Click me! | |\n" "| +-----------+ |\n" "+--------------------------------+\n" "```" msgstr "" #: src/error-handling.md:1 msgid "# Error Handling" msgstr "" #: src/error-handling.md:3 msgid "Error handling in Rust is done using explicit control flow:" msgstr "" #: src/error-handling.md:5 msgid "" "* Functions that can have errors list this in their return type,\n" "* There are no exceptions." msgstr "" #: src/error-handling/panics.md:1 msgid "# Panics" msgstr "" #: src/error-handling/panics.md:3 msgid "Rust will trigger a panic if a fatal error happens at runtime:" msgstr "" #: src/error-handling/panics.md:5 msgid "" "```rust,editable,should_panic\n" "fn main() {\n" " let v = vec![10, 20, 30];\n" " println!(\"v[100]: {}\", v[100]);\n" "}\n" "```" msgstr "" #: src/error-handling/panics.md:12 msgid "" "* Panics are for unrecoverable and unexpected errors.\n" " * Panics are symptoms of bugs in the program.\n" "* Use non-panicking APIs (such as `Vec::get`) if crashing is not acceptable." msgstr "" #: src/error-handling/panic-unwind.md:1 msgid "# Catching the Stack Unwinding" msgstr "" #: src/error-handling/panic-unwind.md:3 msgid "By default, a panic will cause the stack to unwind. The unwinding can be caught:" msgstr "" #: src/error-handling/panic-unwind.md:5 msgid "" "```rust,editable\n" "use std::panic;\n" "\n" "let result = panic::catch_unwind(|| {\n" " println!(\"hello!\");\n" "});\n" "assert!(result.is_ok());\n" "\n" "let result = panic::catch_unwind(|| {\n" " panic!(\"oh no!\");\n" "});\n" "assert!(result.is_err());\n" "```" msgstr "" #: src/error-handling/panic-unwind.md:19 msgid "" "* This can be useful in servers which should keep running even if a single\n" " request crashes.\n" "* This does not work if `panic = 'abort'` is set in your `Cargo.toml`." msgstr "" #: src/error-handling/result.md:1 msgid "# Structured Error Handling with `Result`" msgstr "" #: src/error-handling/result.md:3 msgid "" "We have already seen the `Result` enum. This is used pervasively when errors are\n" "expected as part of normal operation:" msgstr "" #: src/error-handling/result.md:6 msgid "" "```rust,editable\n" "use std::fs::File;\n" "use std::io::Read;\n" "\n" "fn main() {\n" " let file = File::open(\"diary.txt\");\n" " match file {\n" " Ok(mut file) => {\n" " let mut contents = String::new();\n" " file.read_to_string(&mut contents);\n" " println!(\"Dear diary: {contents}\");\n" " },\n" " Err(err) => {\n" " println!(\"The diary could not be opened: {err}\");\n" " }\n" " }\n" "}\n" "```" msgstr "" #: src/error-handling/result.md:27 msgid "" " * As with `Option`, the successful value sits inside of `Result`, forcing the developer to\n" " explicitly extract it. This encourages error checking. In the case where an error should never " "happen,\n" " `unwrap()` or `expect()` can be called, and this is a signal of the developer intent too. \n" " * `Result` documentation is a recommended read. Not during the course, but it is worth " "mentioning. \n" " It contains a lot of convenience methods and functions that help functional-style " "programming. \n" " " msgstr "" #: src/error-handling/try-operator.md:1 msgid "# Propagating Errors with `?`" msgstr "" #: src/error-handling/try-operator.md:3 msgid "" "The try-operator `?` is used to return errors to the caller. It lets you turn\n" "the common" msgstr "" #: src/error-handling/try-operator.md:6 msgid "" "```rust,ignore\n" "match some_expression {\n" " Ok(value) => value,\n" " Err(err) => return Err(err),\n" "}\n" "```" msgstr "" #: src/error-handling/try-operator.md:13 msgid "into the much simpler" msgstr "" #: src/error-handling/try-operator.md:15 msgid "" "```rust,ignore\n" "some_expression?\n" "```" msgstr "" #: src/error-handling/try-operator.md:19 msgid "We can use this to simplify our error handing code:" msgstr "" #: src/error-handling/try-operator.md:21 msgid "" "```rust,editable\n" "use std::fs;\n" "use std::io::{self, Read};\n" "\n" "fn read_username(path: &str) -> Result {\n" " let username_file_result = fs::File::open(path);\n" " let mut username_file = match username_file_result {\n" " Ok(file) => file,\n" " Err(err) => return Err(err),\n" " };\n" "\n" " let mut username = String::new();\n" " match username_file.read_to_string(&mut username) {\n" " Ok(_) => Ok(username),\n" " Err(err) => Err(err),\n" " }\n" "}\n" "\n" "fn main() {\n" " //fs::write(\"config.dat\", \"alice\").unwrap();\n" " let username = read_username(\"config.dat\");\n" " println!(\"username or error: {username:?}\");\n" "}\n" "```" msgstr "" #: src/error-handling/try-operator.md:50 src/error-handling/converting-error-types-example.md:52 msgid "" "* The `username` variable can be either `Ok(string)` or `Err(error)`.\n" "* Use the `fs::write` call to test out the different scenarios: no file, empty file, file with " "username." msgstr "" #: src/error-handling/converting-error-types.md:1 #: src/error-handling/converting-error-types-example.md:1 msgid "# Converting Error Types" msgstr "" #: src/error-handling/converting-error-types.md:3 msgid "The effective expansion of `?` is a little more complicated than previously indicated:" msgstr "" #: src/error-handling/converting-error-types.md:5 msgid "" "```rust,ignore\n" "expression?\n" "```" msgstr "" #: src/error-handling/converting-error-types.md:9 msgid "works the same as" msgstr "" #: src/error-handling/converting-error-types.md:11 msgid "" "```rust,ignore\n" "match expression {\n" " Ok(value) => value,\n" " Err(err) => return Err(From::from(err)),\n" "}\n" "```" msgstr "" #: src/error-handling/converting-error-types.md:18 msgid "" "The `From::from` call here means we attempt to convert the error type to the\n" "type returned by the function:" msgstr "" #: src/error-handling/converting-error-types-example.md:3 msgid "" "```rust,editable\n" "use std::error::Error;\n" "use std::fmt::{self, Display, Formatter};\n" "use std::fs::{self, File};\n" "use std::io::{self, Read};\n" "\n" "#[derive(Debug)]\n" "enum ReadUsernameError {\n" " IoError(io::Error),\n" " EmptyUsername(String),\n" "}\n" "\n" "impl Error for ReadUsernameError {}\n" "\n" "impl Display for ReadUsernameError {\n" " fn fmt(&self, f: &mut Formatter) -> fmt::Result {\n" " match self {\n" " Self::IoError(e) => write!(f, \"IO error: {e}\"),\n" " Self::EmptyUsername(filename) => write!(f, \"Found no username in {filename}\"),\n" " }\n" " }\n" "}\n" "\n" "impl From for ReadUsernameError {\n" " fn from(err: io::Error) -> ReadUsernameError {\n" " ReadUsernameError::IoError(err)\n" " }\n" "}\n" "\n" "fn read_username(path: &str) -> Result {\n" " let mut username = String::with_capacity(100);\n" " File::open(path)?.read_to_string(&mut username)?;\n" " if username.is_empty() {\n" " return Err(ReadUsernameError::EmptyUsername(String::from(path)));\n" " }\n" " Ok(username)\n" "}\n" "\n" "fn main() {\n" " //fs::write(\"config.dat\", \"\").unwrap();\n" " let username = read_username(\"config.dat\");\n" " println!(\"username or error: {username:?}\");\n" "}\n" "```" msgstr "" #: src/error-handling/converting-error-types-example.md:55 msgid "" "It is good practice for all error types to implement `std::error::Error`, which requires `Debug` " "and\n" "`Display`. It's generally helpful for them to implement `Clone` and `Eq` too where possible, to " "make\n" "life easier for tests and consumers of your library. In this case we can't easily do so, because\n" "`io::Error` doesn't implement them." msgstr "" #: src/error-handling/deriving-error-enums.md:1 msgid "# Deriving Error Enums" msgstr "" #: src/error-handling/deriving-error-enums.md:3 msgid "" "The [thiserror](https://docs.rs/thiserror/) crate is a popular way to create an\n" "error enum like we did on the previous page:" msgstr "" #: src/error-handling/deriving-error-enums.md:6 msgid "" "```rust,editable,compile_fail\n" "use std::{fs, io};\n" "use std::io::Read;\n" "use thiserror::Error;\n" "\n" "#[derive(Debug, Error)]\n" "enum ReadUsernameError {\n" " #[error(\"Could not read: {0}\")]\n" " IoError(#[from] io::Error),\n" " #[error(\"Found no username in {0}\")]\n" " EmptyUsername(String),\n" "}\n" "\n" "fn read_username(path: &str) -> Result {\n" " let mut username = String::with_capacity(100);\n" " fs::File::open(path)?.read_to_string(&mut username)?;\n" " if username.is_empty() {\n" " return Err(ReadUsernameError::EmptyUsername(String::from(path)));\n" " }\n" " Ok(username)\n" "}\n" "\n" "fn main() {\n" " //fs::write(\"config.dat\", \"\").unwrap();\n" " match read_username(\"config.dat\") {\n" " Ok(username) => println!(\"Username: {username}\"),\n" " Err(err) => println!(\"Error: {err}\"),\n" " }\n" "}\n" "```" msgstr "" #: src/error-handling/deriving-error-enums.md:39 msgid "" "`thiserror`'s derive macro automatically implements `std::error::Error`, and optionally `Display`\n" "(if the `#[error(...)]` attributes are provided) and `From` (if the `#[from]` attribute is " "added).\n" "It also works for structs." msgstr "" #: src/error-handling/deriving-error-enums.md:43 msgid "It doesn't affect your public API, which makes it good for libraries." msgstr "" #: src/error-handling/dynamic-errors.md:1 msgid "# Dynamic Error Types" msgstr "" #: src/error-handling/dynamic-errors.md:3 msgid "" "Sometimes we want to allow any type of error to be returned without writing our own enum covering\n" "all the different possibilities. `std::error::Error` makes this easy." msgstr "" #: src/error-handling/dynamic-errors.md:6 msgid "" "```rust,editable,compile_fail\n" "use std::fs::{self, File};\n" "use std::io::Read;\n" "use thiserror::Error;\n" "use std::error::Error;\n" "\n" "#[derive(Clone, Debug, Eq, Error, PartialEq)]\n" "#[error(\"Found no username in {0}\")]\n" "struct EmptyUsernameError(String);\n" "\n" "fn read_username(path: &str) -> Result> {\n" " let mut username = String::with_capacity(100);\n" " File::open(path)?.read_to_string(&mut username)?;\n" " if username.is_empty() {\n" " return Err(EmptyUsernameError(String::from(path)).into());\n" " }\n" " Ok(username)\n" "}\n" "\n" "fn main() {\n" " //fs::write(\"config.dat\", \"\").unwrap();\n" " match read_username(\"config.dat\") {\n" " Ok(username) => println!(\"Username: {username}\"),\n" " Err(err) => println!(\"Error: {err}\"),\n" " }\n" "}\n" "```" msgstr "" #: src/error-handling/dynamic-errors.md:36 msgid "" "This saves on code, but gives up the ability to cleanly handle different error cases differently " "in\n" "the program. As such it's generally not a good idea to use `Box` in the public API of " "a\n" "library, but it can be a good option in a program where you just want to display the error " "message\n" "somewhere." msgstr "" #: src/error-handling/error-contexts.md:1 msgid "# Adding Context to Errors" msgstr "" #: src/error-handling/error-contexts.md:3 msgid "" "The widely used [anyhow](https://docs.rs/anyhow/) crate can help you add\n" "contextual information to your errors and allows you to have fewer\n" "custom error types:" msgstr "" #: src/error-handling/error-contexts.md:7 msgid "" "```rust,editable,compile_fail\n" "use std::{fs, io};\n" "use std::io::Read;\n" "use anyhow::{Context, Result, bail};\n" "\n" "fn read_username(path: &str) -> Result {\n" " let mut username = String::with_capacity(100);\n" " fs::File::open(path)\n" " .with_context(|| format!(\"Failed to open {path}\"))?\n" " .read_to_string(&mut username)\n" " .context(\"Failed to read\")?;\n" " if username.is_empty() {\n" " bail!(\"Found no username in {path}\");\n" " }\n" " Ok(username)\n" "}\n" "\n" "fn main() {\n" " //fs::write(\"config.dat\", \"\").unwrap();\n" " match read_username(\"config.dat\") {\n" " Ok(username) => println!(\"Username: {username}\"),\n" " Err(err) => println!(\"Error: {err:?}\"),\n" " }\n" "}\n" "```" msgstr "" #: src/error-handling/error-contexts.md:35 msgid "" "* `anyhow::Result` is a type alias for `Result`.\n" "* `anyhow::Error` is essentially a wrapper around `Box`. As such it's again generally " "not\n" " a good choice for the public API of a library, but is widely used in applications.\n" "* Actual error type inside of it can be extracted for examination if necessary.\n" "* Functionality provided by `anyhow::Result` may be familiar to Go developers, as it provides\n" " similar usage patterns and ergonomics to `(T, error)` from Go." msgstr "" #: src/testing.md:1 msgid "# Testing" msgstr "" #: src/testing.md:3 msgid "Rust and Cargo come with a simple unit test framework:" msgstr "" #: src/testing.md:5 msgid "" "* Unit tests are supported throughout your code.\n" "\n" "* Integration tests are supported via the `tests/` directory." msgstr "" #: src/testing/unit-tests.md:1 msgid "# Unit Tests" msgstr "" #: src/testing/unit-tests.md:3 msgid "Mark unit tests with `#[test]`:" msgstr "" #: src/testing/unit-tests.md:5 msgid "" "```rust,editable,ignore\n" "fn first_word(text: &str) -> &str {\n" " match text.find(' ') {\n" " Some(idx) => &text[..idx],\n" " None => &text,\n" " }\n" "}\n" "\n" "#[test]\n" "fn test_empty() {\n" " assert_eq!(first_word(\"\"), \"\");\n" "}\n" "\n" "#[test]\n" "fn test_single_word() {\n" " assert_eq!(first_word(\"Hello\"), \"Hello\");\n" "}\n" "\n" "#[test]\n" "fn test_multiple_words() {\n" " assert_eq!(first_word(\"Hello World\"), \"Hello\");\n" "}\n" "```" msgstr "" #: src/testing/unit-tests.md:29 msgid "Use `cargo test` to find and run the unit tests." msgstr "" #: src/testing/test-modules.md:1 msgid "# Test Modules" msgstr "" #: src/testing/test-modules.md:3 msgid "" "Unit tests are often put in a nested module (run tests on the\n" "[Playground](https://play.rust-lang.org/)):" msgstr "" #: src/testing/test-modules.md:6 msgid "" "```rust,editable\n" "fn helper(a: &str, b: &str) -> String {\n" " format!(\"{a} {b}\")\n" "}\n" "\n" "pub fn main() {\n" " println!(\"{}\", helper(\"Hello\", \"World\"));\n" "}\n" "\n" "#[cfg(test)]\n" "mod tests {\n" " use super::*;\n" "\n" " #[test]\n" " fn test_helper() {\n" " assert_eq!(helper(\"foo\", \"bar\"), \"foo bar\");\n" " }\n" "}\n" "```" msgstr "" #: src/testing/test-modules.md:26 msgid "" "* This lets you unit test private helpers.\n" "* The `#[cfg(test)]` attribute is only active when you run `cargo test`." msgstr "" #: src/testing/doc-tests.md:1 msgid "# Documentation Tests" msgstr "" #: src/testing/doc-tests.md:3 msgid "Rust has built-in support for documentation tests:" msgstr "" #: src/testing/doc-tests.md:5 msgid "" "```rust\n" "/// Shortens a string to the given length.\n" "///\n" "/// ```\n" "/// use playground::shorten_string;\n" "/// assert_eq!(shorten_string(\"Hello World\", 5), \"Hello\");\n" "/// assert_eq!(shorten_string(\"Hello World\", 20), \"Hello World\");\n" "/// ```\n" "pub fn shorten_string(s: &str, length: usize) -> &str {\n" " &s[..std::cmp::min(length, s.len())]\n" "}\n" "```" msgstr "" #: src/testing/doc-tests.md:18 msgid "" "* Code blocks in `///` comments are automatically seen as Rust code.\n" "* The code will be compiled and executed as part of `cargo test`.\n" "* Test the above code on the [Rust Playground](https://play.rust-lang.org/?" "version=stable&mode=debug&edition=2021&gist=3ce2ad13ea1302f6572cb15cd96becf0)." msgstr "" #: src/testing/integration-tests.md:1 msgid "# Integration Tests" msgstr "" #: src/testing/integration-tests.md:3 msgid "If you want to test your library as a client, use an integration test." msgstr "" #: src/testing/integration-tests.md:5 msgid "Create a `.rs` file under `tests/`:" msgstr "" #: src/testing/integration-tests.md:7 msgid "" "```rust,ignore\n" "use my_library::init;\n" "\n" "#[test]\n" "fn test_init() {\n" " assert!(init().is_ok());\n" "}\n" "```" msgstr "" #: src/testing/integration-tests.md:16 msgid "These tests only have access to the public API of your crate." msgstr "" #: src/testing/useful-crates.md:1 msgid "## Useful crates for writing tests" msgstr "" #: src/testing/useful-crates.md:3 msgid "Rust comes with only basic support for writing tests." msgstr "" #: src/testing/useful-crates.md:5 msgid "Here are some additional crates which we recommend for writing tests:" msgstr "" #: src/testing/useful-crates.md:7 msgid "" "* [googletest](https://docs.rs/googletest): Comprehensive test assertion library in the tradition " "of GoogleTest for C++.\n" "* [proptest](https://docs.rs/proptest): Property-based testing for Rust.\n" "* [rstest](https://docs.rs/rstest): Support for fixtures and parameterised tests." msgstr "" #: src/unsafe.md:1 msgid "# Unsafe Rust" msgstr "" #: src/unsafe.md:3 msgid "The Rust language has two parts:" msgstr "" #: src/unsafe.md:5 msgid "" "* **Safe Rust:** memory safe, no undefined behavior possible.\n" "* **Unsafe Rust:** can trigger undefined behavior if preconditions are violated." msgstr "" #: src/unsafe.md:8 msgid "" "We will be seeing mostly safe Rust in this course, but it's important to know\n" "what Unsafe Rust is." msgstr "" #: src/unsafe.md:11 msgid "" "Unsafe code is usually small and isolated, and its correctness should be carefully\n" "documented. It is usually wrapped in a safe abstraction layer." msgstr "" #: src/unsafe.md:14 msgid "Unsafe Rust gives you access to five new capabilities:" msgstr "" #: src/unsafe.md:16 msgid "" "* Dereference raw pointers.\n" "* Access or modify mutable static variables.\n" "* Access `union` fields.\n" "* Call `unsafe` functions, including `extern` functions.\n" "* Implement `unsafe` traits." msgstr "" #: src/unsafe.md:22 msgid "" "We will briefly cover unsafe capabilities next. For full details, please see\n" "[Chapter 19.1 in the Rust Book](https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html)\n" "and the [Rustonomicon](https://doc.rust-lang.org/nomicon/)." msgstr "" #: src/unsafe.md:28 msgid "" "Unsafe Rust does not mean the code is incorrect. It means that developers have\n" "turned off the compiler safety features and have to write correct code by\n" "themselves. It means the compiler no longer enforces Rust's memory-safety rules." msgstr "" #: src/unsafe/raw-pointers.md:1 msgid "# Dereferencing Raw Pointers" msgstr "" #: src/unsafe/raw-pointers.md:3 msgid "Creating pointers is safe, but dereferencing them requires `unsafe`:" msgstr "" #: src/unsafe/raw-pointers.md:5 msgid "" "```rust,editable\n" "fn main() {\n" " let mut num = 5;\n" "\n" " let r1 = &mut num as *mut i32;\n" " let r2 = r1 as *const i32;\n" "\n" " // Safe because r1 and r2 were obtained from references and so are\n" " // guaranteed to be non-null and properly aligned, the objects underlying\n" " // the references from which they were obtained are live throughout the\n" " // whole unsafe block, and they are not accessed either through the\n" " // references or concurrently through any other pointers.\n" " unsafe {\n" " println!(\"r1 is: {}\", *r1);\n" " *r1 = 10;\n" " println!(\"r2 is: {}\", *r2);\n" " }\n" "}\n" "```" msgstr "" #: src/unsafe/raw-pointers.md:27 msgid "" "It is good practice (and required by the Android Rust style guide) to write a comment for each\n" "`unsafe` block explaining how the code inside it satisfies the safety requirements of the unsafe\n" "operations it is doing." msgstr "" #: src/unsafe/raw-pointers.md:31 msgid "" "In the case of pointer dereferences, this means that the pointers must be\n" "[_valid_](https://doc.rust-lang.org/std/ptr/index.html#safety), i.e.:" msgstr "" #: src/unsafe/raw-pointers.md:34 msgid "" " * The pointer must be non-null.\n" " * The pointer must be _dereferenceable_ (within the bounds of a single allocated object).\n" " * The object must not have been deallocated.\n" " * There must not be concurrent accesses to the same location.\n" " * If the pointer was obtained by casting a reference, the underlying object must be live and no\n" " reference may be used to access the memory." msgstr "" #: src/unsafe/raw-pointers.md:41 msgid "In most cases the pointer must also be properly aligned." msgstr "" #: src/unsafe/mutable-static-variables.md:1 msgid "# Mutable Static Variables" msgstr "" #: src/unsafe/mutable-static-variables.md:3 msgid "It is safe to read an immutable static variable:" msgstr "" #: src/unsafe/mutable-static-variables.md:5 msgid "" "```rust,editable\n" "static HELLO_WORLD: &str = \"Hello, world!\";\n" "\n" "fn main() {\n" " println!(\"HELLO_WORLD: {HELLO_WORLD}\");\n" "}\n" "```" msgstr "" #: src/unsafe/mutable-static-variables.md:13 msgid "" "However, since data races can occur, it is unsafe to read and write mutable\n" "static variables:" msgstr "" #: src/unsafe/mutable-static-variables.md:16 msgid "" "```rust,editable\n" "static mut COUNTER: u32 = 0;\n" "\n" "fn add_to_counter(inc: u32) {\n" " unsafe { COUNTER += inc; } // Potential data race!\n" "}\n" "\n" "fn main() {\n" " add_to_counter(42);\n" "\n" " unsafe { println!(\"COUNTER: {COUNTER}\"); } // Potential data race!\n" "}\n" "```" msgstr "" #: src/unsafe/mutable-static-variables.md:32 msgid "" "Using a mutable static is generally a bad idea, but there are some cases where it might make " "sense\n" "in low-level `no_std` code, such as implementing a heap allocator or working with some C APIs." msgstr "" #: src/unsafe/unions.md:1 msgid "# Unions" msgstr "" #: src/unsafe/unions.md:3 msgid "Unions are like enums, but you need to track the active field yourself:" msgstr "" #: src/unsafe/unions.md:5 msgid "" "```rust,editable\n" "#[repr(C)]\n" "union MyUnion {\n" " i: u8,\n" " b: bool,\n" "}\n" "\n" "fn main() {\n" " let u = MyUnion { i: 42 };\n" " println!(\"int: {}\", unsafe { u.i });\n" " println!(\"bool: {}\", unsafe { u.b }); // Undefined behavior!\n" "}\n" "```" msgstr "" #: src/unsafe/unions.md:21 msgid "" "Unions are very rarely needed in Rust as you can usually use an enum. They are occasionally " "needed\n" "for interacting with C library APIs." msgstr "" #: src/unsafe/unions.md:24 msgid "" "If you just want to reinterpret bytes as a different type, you probably want\n" "[`std::mem::transmute`](https://doc.rust-lang.org/stable/std/mem/fn.transmute.html) or a safe\n" "wrapper such as the [`zerocopy`](https://crates.io/crates/zerocopy) crate." msgstr "" #: src/unsafe/calling-unsafe-functions.md:1 msgid "# Calling Unsafe Functions" msgstr "" #: src/unsafe/calling-unsafe-functions.md:3 msgid "" "A function or method can be marked `unsafe` if it has extra preconditions you\n" "must uphold to avoid undefined behaviour:" msgstr "" #: src/unsafe/calling-unsafe-functions.md:6 msgid "" "```rust,editable\n" "fn main() {\n" " let emojis = \"🗻∈🌏\";\n" "\n" " // Safe because the indices are in the correct order, within the bounds of\n" " // the string slice, and lie on UTF-8 sequence boundaries.\n" " unsafe {\n" " println!(\"emoji: {}\", emojis.get_unchecked(0..4));\n" " println!(\"emoji: {}\", emojis.get_unchecked(4..7));\n" " println!(\"emoji: {}\", emojis.get_unchecked(7..11));\n" " }\n" "\n" " println!(\"char count: {}\", count_chars(unsafe { emojis.get_unchecked(0..7) }));\n" "\n" " // Not upholding the UTF-8 encoding requirement breaks memory safety!\n" " // println!(\"emoji: {}\", unsafe { emojis.get_unchecked(0..3) });\n" " // println!(\"char count: {}\", count_chars(unsafe { emojis.get_unchecked(0..3) }));\n" "}\n" "\n" "fn count_chars(s: &str) -> usize {\n" " s.chars().map(|_| 1).sum()\n" "}\n" "```" msgstr "" #: src/unsafe/writing-unsafe-functions.md:1 msgid "# Writing Unsafe Functions" msgstr "" #: src/unsafe/writing-unsafe-functions.md:3 msgid "" "You can mark your own functions as `unsafe` if they require particular conditions to avoid " "undefined\n" "behaviour." msgstr "" #: src/unsafe/writing-unsafe-functions.md:6 msgid "" "```rust,editable\n" "/// Swaps the values pointed to by the given pointers.\n" "///\n" "/// # Safety\n" "///\n" "/// The pointers must be valid and properly aligned.\n" "unsafe fn swap(a: *mut u8, b: *mut u8) {\n" " let temp = *a;\n" " *a = *b;\n" " *b = temp;\n" "}\n" "\n" "fn main() {\n" " let mut a = 42;\n" " let mut b = 66;\n" "\n" " // Safe because ...\n" " unsafe {\n" " swap(&mut a, &mut b);\n" " }\n" "\n" " println!(\"a = {}, b = {}\", a, b);\n" "}\n" "```" msgstr "" #: src/unsafe/writing-unsafe-functions.md:33 msgid "We wouldn't actually use pointers for this because it can be done safely with references." msgstr "" #: src/unsafe/writing-unsafe-functions.md:35 msgid "" "Note that unsafe code is allowed within an unsafe function without an `unsafe` block. We can\n" "prohibit this with `#[deny(unsafe_op_in_unsafe_fn)]`. Try adding it and see what happens." msgstr "" #: src/unsafe/extern-functions.md:1 msgid "# Calling External Code" msgstr "" #: src/unsafe/extern-functions.md:3 msgid "" "Functions from other languages might violate the guarantees of Rust. Calling\n" "them is thus unsafe:" msgstr "" #: src/unsafe/extern-functions.md:6 msgid "" "```rust,editable\n" "extern \"C\" {\n" " fn abs(input: i32) -> i32;\n" "}\n" "\n" "fn main() {\n" " unsafe {\n" " // Undefined behavior if abs misbehaves.\n" " println!(\"Absolute value of -3 according to C: {}\", abs(-3));\n" " }\n" "}\n" "```" msgstr "" #: src/unsafe/extern-functions.md:21 msgid "" "This is usually only a problem for extern functions which do things with pointers which might\n" "violate Rust's memory model, but in general any C function might have undefined behaviour under " "any\n" "arbitrary circumstances." msgstr "" #: src/unsafe/extern-functions.md:25 msgid "" "The `\"C\"` in this example is the ABI;\n" "[other ABIs are available too](https://doc.rust-lang.org/reference/items/external-blocks.html)." msgstr "" #: src/unsafe/unsafe-traits.md:1 msgid "# Implementing Unsafe Traits" msgstr "" #: src/unsafe/unsafe-traits.md:3 msgid "" "Like with functions, you can mark a trait as `unsafe` if the implementation must guarantee\n" "particular conditions to avoid undefined behaviour." msgstr "" #: src/unsafe/unsafe-traits.md:6 msgid "" "For example, the `zerocopy` crate has an unsafe trait that looks\n" "[something like this](https://docs.rs/zerocopy/latest/zerocopy/trait.AsBytes.html):" msgstr "" #: src/unsafe/unsafe-traits.md:9 msgid "" "```rust,editable\n" "use std::mem::size_of_val;\n" "use std::slice;\n" "\n" "/// ...\n" "/// # Safety\n" "/// The type must have a defined representation and no padding.\n" "pub unsafe trait AsBytes {\n" " fn as_bytes(&self) -> &[u8] {\n" " unsafe {\n" " slice::from_raw_parts(self as *const Self as *const u8, size_of_val(self))\n" " }\n" " }\n" "}\n" "\n" "// Safe because u32 has a defined representation and no padding.\n" "unsafe impl AsBytes for u32 {}\n" "```" msgstr "" #: src/unsafe/unsafe-traits.md:30 msgid "" "There should be a `# Safety` section on the Rustdoc for the trait explaining the requirements for\n" "the trait to be safely implemented." msgstr "" #: src/unsafe/unsafe-traits.md:33 msgid "The actual safety section for `AsBytes` is rather longer and more complicated." msgstr "" #: src/unsafe/unsafe-traits.md:35 msgid "The built-in `Send` and `Sync` traits are unsafe." msgstr "" #: src/exercises/day-3/afternoon.md:1 msgid "# Day 3: Afternoon Exercises" msgstr "" #: src/exercises/day-3/afternoon.md:3 msgid "Let us build a safe wrapper for reading directory content!" msgstr "" #: src/exercises/day-3/afternoon.md:7 msgid "After looking at the exercise, you can look at the [solution] provided." msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:1 msgid "# Safe FFI Wrapper" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:3 msgid "" "Rust has great support for calling functions through a _foreign function\n" "interface_ (FFI). We will use this to build a safe wrapper for the `libc`\n" "functions you would use from C to read the filenames of a directory." msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:7 msgid "You will want to consult the manual pages:" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:9 msgid "" "* [`opendir(3)`](https://man7.org/linux/man-pages/man3/opendir.3.html)\n" "* [`readdir(3)`](https://man7.org/linux/man-pages/man3/readdir.3.html)\n" "* [`closedir(3)`](https://man7.org/linux/man-pages/man3/closedir.3.html)" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:13 msgid "" "You will also want to browse the [`std::ffi`] module. There you find a number of\n" "string types which you need for the exercise:" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:16 msgid "" "| Types | Encoding | Use |\n" "|----------------------------|----------------|--------------------------------|\n" "| [`str`] and [`String`] | UTF-8 | Text processing in Rust |\n" "| [`CStr`] and [`CString`] | NUL-terminated | Communicating with C functions |\n" "| [`OsStr`] and [`OsString`] | OS-specific | Communicating with the OS |" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:22 msgid "You will convert between all these types:" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:24 msgid "" "- `&str` to `CString`: you need to allocate space for a trailing `\\0` character,\n" "- `CString` to `*const i8`: you need a pointer to call C functions,\n" "- `*const i8` to `&CStr`: you need something which can find the trailing `\\0` character,\n" "- `&CStr` to `&[u8]`: a slice of bytes is the universal interface for \"some unknow data\",\n" "- `&[u8]` to `&OsStr`: `&OsStr` is a step towards `OsString`, use\n" " [`OsStrExt`](https://doc.rust-lang.org/std/os/unix/ffi/trait.OsStrExt.html)\n" " to create it,\n" "- `&OsStr` to `OsString`: you need to clone the data in `&OsStr` to be able to return it and call\n" " `readdir` again." msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:34 msgid "The [Nomicon] also has a very useful chapter about FFI." msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:45 msgid "" "Copy the code below to and fill in the missing\n" "functions and methods:" msgstr "" #: src/exercises/day-3/safe-ffi-wrapper.md:48 msgid "" "```rust,should_panic\n" "// TODO: remove this when you're done with your implementation.\n" "#![allow(unused_imports, unused_variables, dead_code)]\n" "\n" "mod ffi {\n" " use std::os::raw::{c_char, c_int};\n" " #[cfg(not(target_os = \"macos\"))]\n" " use std::os::raw::{c_long, c_ulong, c_ushort};\n" "\n" " // Opaque type. See https://doc.rust-lang.org/nomicon/ffi.html.\n" " #[repr(C)]\n" " pub struct DIR {\n" " _data: [u8; 0],\n" " _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,\n" " }\n" "\n" " // Layout as per readdir(3) and definitions in /usr/include/x86_64-linux-gnu.\n" " #[cfg(not(target_os = \"macos\"))]\n" " #[repr(C)]\n" " pub struct dirent {\n" " pub d_ino: c_long,\n" " pub d_off: c_ulong,\n" " pub d_reclen: c_ushort,\n" " pub d_type: c_char,\n" " pub d_name: [c_char; 256],\n" " }\n" "\n" " // Layout as per man entry for dirent\n" " #[cfg(target_os = \"macos\")]\n" " #[repr(C)]\n" " pub struct dirent {\n" " pub d_ino: u64,\n" " pub d_seekoff: u64,\n" " pub d_reclen: u16,\n" " pub d_namlen: u16,\n" " pub d_type: u8,\n" " pub d_name: [c_char; 1024],\n" " }\n" "\n" " extern \"C\" {\n" " pub fn opendir(s: *const c_char) -> *mut DIR;\n" " pub fn readdir(s: *mut DIR) -> *const dirent;\n" " pub fn closedir(s: *mut DIR) -> c_int;\n" " }\n" "}\n" "\n" "use std::ffi::{CStr, CString, OsStr, OsString};\n" "use std::os::unix::ffi::OsStrExt;\n" "\n" "#[derive(Debug)]\n" "struct DirectoryIterator {\n" " path: CString,\n" " dir: *mut ffi::DIR,\n" "}\n" "\n" "impl DirectoryIterator {\n" " fn new(path: &str) -> Result {\n" " // Call opendir and return a Ok value if that worked,\n" " // otherwise return Err with a message.\n" " unimplemented!()\n" " }\n" "}\n" "\n" "impl Iterator for DirectoryIterator {\n" " type Item = OsString;\n" " fn next(&mut self) -> Option {\n" " // Keep calling readdir until we get a NULL pointer back.\n" " unimplemented!()\n" " }\n" "}\n" "\n" "impl Drop for DirectoryIterator {\n" " fn drop(&mut self) {\n" " // Call closedir as needed.\n" " unimplemented!()\n" " }\n" "}\n" "\n" "fn main() -> Result<(), String> {\n" " let iter = DirectoryIterator::new(\".\")?;\n" " println!(\"files: {:#?}\", iter.collect::>());\n" " Ok(())\n" "}\n" "```" msgstr "" #: src/android.md:1 msgid "# Welcome to Rust in Android" msgstr "" #: src/android.md:3 msgid "" "Rust is supported for native platform development on Android. This means that\n" "you can write new operating system services in Rust, as well as extending\n" "existing services." msgstr "" #: src/android.md:7 msgid "" "> We will attempt to call Rust from one of your own projects today. So try to\n" "> find a little corner of your code base where we can move some lines of code to\n" "> Rust. The fewer dependencies and \"exotic\" types the better. Something that\n" "> parses some raw bytes would be ideal." msgstr "" #: src/android/setup.md:1 msgid "# Setup" msgstr "" #: src/android/setup.md:3 msgid "" "We will be using an Android Virtual Device to test our code. Make sure you have\n" "access to one or create a new one with:" msgstr "" #: src/android/setup.md:6 msgid "" "```shell\n" "$ source build/envsetup.sh\n" "$ lunch aosp_cf_x86_64_phone-userdebug\n" "$ acloud create\n" "```" msgstr "" #: src/android/setup.md:12 msgid "" "Please see the [Android Developer\n" "Codelab](https://source.android.com/docs/setup/start) for details." msgstr "" #: src/android/build-rules.md:1 msgid "# Build Rules" msgstr "" #: src/android/build-rules.md:3 msgid "The Android build system (Soong) supports Rust via a number of modules:" msgstr "" #: src/android/build-rules.md:5 msgid "" "| Module Type | " "Description " "|\n" "|-------------------|----------------------------------------------------------------------------------------------------|\n" "| `rust_binary` | Produces a Rust " "binary. |\n" "| `rust_library` | Produces a Rust library, and provides both `rlib` and `dylib` " "variants. |\n" "| `rust_ffi` | Produces a Rust C library usable by `cc` modules, and provides both static " "and shared variants. |\n" "| `rust_proc_macro` | Produces a `proc-macro` Rust library. These are analogous to compiler " "plugins. |\n" "| `rust_test` | Produces a Rust test binary that uses the standard Rust test " "harness. |\n" "| `rust_fuzz` | Produces a Rust fuzz binary leveraging " "`libfuzzer`. |\n" "| `rust_protobuf` | Generates source and produces a Rust library that provides an interface for " "a particular protobuf. |\n" "| `rust_bindgen` | Generates source and produces a Rust library containing Rust bindings to C " "libraries. |" msgstr "" #: src/android/build-rules.md:16 msgid "We will look at `rust_binary` and `rust_library` next." msgstr "" #: src/android/build-rules/binary.md:1 msgid "# Rust Binaries" msgstr "" #: src/android/build-rules/binary.md:3 msgid "" "Let us start with a simple application. At the root of an AOSP checkout, create\n" "the following files:" msgstr "" #: src/android/build-rules/binary.md:6 src/android/build-rules/library.md:13 msgid "_hello_rust/Android.bp_:" msgstr "" #: src/android/build-rules/binary.md:8 msgid "" "```javascript\n" "rust_binary {\n" " name: \"hello_rust\",\n" " crate_name: \"hello_rust\",\n" " srcs: [\"src/main.rs\"],\n" "}\n" "```" msgstr "" #: src/android/build-rules/binary.md:16 src/android/build-rules/library.md:34 msgid "_hello_rust/src/main.rs_:" msgstr "" #: src/android/build-rules/binary.md:18 msgid "" "```rust\n" "//! Rust demo.\n" "\n" "/// Prints a greeting to standard output.\n" "fn main() {\n" " println!(\"Hello from Rust!\");\n" "}\n" "```" msgstr "" #: src/android/build-rules/binary.md:27 msgid "You can now build, push, and run the binary:" msgstr "" #: src/android/build-rules/binary.md:29 msgid "" "```shell\n" "$ m hello_rust\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/hello_rust /data/local/tmp\n" "$ adb shell /data/local/tmp/hello_rust\n" "Hello from Rust!\n" "```" msgstr "" #: src/android/build-rules/library.md:1 msgid "# Rust Libraries" msgstr "" #: src/android/build-rules/library.md:3 msgid "You use `rust_library` to create a new Rust library for Android." msgstr "" #: src/android/build-rules/library.md:5 msgid "Here we declare a dependency on two libraries:" msgstr "" #: src/android/build-rules/library.md:7 msgid "" "* `libgreeting`, which we define below,\n" "* `libtextwrap`, which is a crate already vendored in\n" " [`external/rust/crates/`][crates]." msgstr "" #: src/android/build-rules/library.md:15 msgid "" "```javascript\n" "rust_binary {\n" " name: \"hello_rust_with_dep\",\n" " crate_name: \"hello_rust_with_dep\",\n" " srcs: [\"src/main.rs\"],\n" " rustlibs: [\n" " \"libgreetings\",\n" " \"libtextwrap\",\n" " ],\n" " prefer_rlib: true,\n" "}\n" "\n" "rust_library {\n" " name: \"libgreetings\",\n" " crate_name: \"greetings\",\n" " srcs: [\"src/lib.rs\"],\n" "}\n" "```" msgstr "" #: src/android/build-rules/library.md:36 msgid "" "```rust,ignore\n" "//! Rust demo.\n" "\n" "use greetings::greeting;\n" "use textwrap::fill;\n" "\n" "/// Prints a greeting to standard output.\n" "fn main() {\n" " println!(\"{}\", fill(&greeting(\"Bob\"), 24));\n" "}\n" "```" msgstr "" #: src/android/build-rules/library.md:48 msgid "_hello_rust/src/lib.rs_:" msgstr "" #: src/android/build-rules/library.md:50 msgid "" "```rust,ignore\n" "//! Greeting library.\n" "\n" "/// Greet `name`.\n" "pub fn greeting(name: &str) -> String {\n" " format!(\"Hello {name}, it is very nice to meet you!\")\n" "}\n" "```" msgstr "" #: src/android/build-rules/library.md:59 msgid "You build, push, and run the binary like before:" msgstr "" #: src/android/build-rules/library.md:61 msgid "" "```shell\n" "$ m hello_rust_with_dep\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/hello_rust_with_dep /data/local/tmp\n" "$ adb shell /data/local/tmp/hello_rust_with_dep\n" "Hello Bob, it is very\n" "nice to meet you!\n" "```" msgstr "" #: src/android/aidl.md:1 msgid "# AIDL" msgstr "" #: src/android/aidl.md:3 msgid "" "The [Android Interface Definition Language\n" "(AIDL)](https://developer.android.com/guide/components/aidl) is supported in Rust:" msgstr "" #: src/android/aidl.md:6 msgid "" "* Rust code can call existing AIDL servers,\n" "* You can create new AIDL servers in Rust." msgstr "" #: src/android/aidl/interface.md:1 msgid "# AIDL Interfaces" msgstr "" #: src/android/aidl/interface.md:3 msgid "You declare the API of your service using an AIDL interface:" msgstr "" #: src/android/aidl/interface.md:5 msgid "*birthday_service/aidl/com/example/birthdayservice/IBirthdayService.aidl*:" msgstr "" #: src/android/aidl/interface.md:7 msgid "" "```java\n" "package com.example.birthdayservice;\n" "\n" "/** Birthday service interface. */\n" "interface IBirthdayService {\n" " /** Generate a Happy Birthday message. */\n" " String wishHappyBirthday(String name, int years);\n" "}\n" "```" msgstr "" #: src/android/aidl/interface.md:17 msgid "*birthday_service/aidl/Android.bp*:" msgstr "" #: src/android/aidl/interface.md:19 msgid "" "```javascript\n" "aidl_interface {\n" " name: \"com.example.birthdayservice\",\n" " srcs: [\"com/example/birthdayservice/*.aidl\"],\n" " unstable: true,\n" " backend: {\n" " rust: { // Rust is not enabled by default\n" " enabled: true,\n" " },\n" " },\n" "}\n" "```" msgstr "" #: src/android/aidl/interface.md:32 msgid "" "Add `vendor_available: true` if your AIDL file is used by a binary in the vendor\n" "partition." msgstr "" #: src/android/aidl/implementation.md:1 msgid "# Service Implementation" msgstr "" #: src/android/aidl/implementation.md:3 msgid "We can now implement the AIDL service:" msgstr "" #: src/android/aidl/implementation.md:5 msgid "*birthday_service/src/lib.rs*:" msgstr "" #: src/android/aidl/implementation.md:7 msgid "" "```rust,ignore\n" "//! Implementation of the `IBirthdayService` AIDL interface.\n" "use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::" "IBirthdayService;\n" "use com_example_birthdayservice::binder;\n" "\n" "/// The `IBirthdayService` implementation.\n" "pub struct BirthdayService;\n" "\n" "impl binder::Interface for BirthdayService {}\n" "\n" "impl IBirthdayService for BirthdayService {\n" " fn wishHappyBirthday(&self, name: &str, years: i32) -> binder::Result {\n" " Ok(format!(\n" " \"Happy Birthday {name}, congratulations with the {years} years!\"\n" " ))\n" " }\n" "}\n" "```" msgstr "" #: src/android/aidl/implementation.md:26 src/android/aidl/server.md:28 src/android/aidl/client.md:37 msgid "*birthday_service/Android.bp*:" msgstr "" #: src/android/aidl/implementation.md:28 msgid "" "```javascript\n" "rust_library {\n" " name: \"libbirthdayservice\",\n" " srcs: [\"src/lib.rs\"],\n" " crate_name: \"birthdayservice\",\n" " rustlibs: [\n" " \"com.example.birthdayservice-rust\",\n" " \"libbinder_rs\",\n" " ],\n" "}\n" "```" msgstr "" #: src/android/aidl/server.md:1 msgid "# AIDL Server" msgstr "" #: src/android/aidl/server.md:3 msgid "Finally, we can create a server which exposes the service:" msgstr "" #: src/android/aidl/server.md:5 msgid "*birthday_service/src/server.rs*:" msgstr "" #: src/android/aidl/server.md:7 msgid "" "```rust,ignore\n" "//! Birthday service.\n" "use birthdayservice::BirthdayService;\n" "use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::" "BnBirthdayService;\n" "use com_example_birthdayservice::binder;\n" "\n" "const SERVICE_IDENTIFIER: &str = \"birthdayservice\";\n" "\n" "/// Entry point for birthday service.\n" "fn main() {\n" " let birthday_service = BirthdayService;\n" " let birthday_service_binder = BnBirthdayService::new_binder(\n" " birthday_service,\n" " binder::BinderFeatures::default(),\n" " );\n" " binder::add_service(SERVICE_IDENTIFIER, birthday_service_binder.as_binder())\n" " .expect(\"Failed to register service\");\n" " binder::ProcessState::join_thread_pool()\n" "}\n" "```" msgstr "" #: src/android/aidl/server.md:30 msgid "" "```javascript\n" "rust_binary {\n" " name: \"birthday_server\",\n" " crate_name: \"birthday_server\",\n" " srcs: [\"src/server.rs\"],\n" " rustlibs: [\n" " \"com.example.birthdayservice-rust\",\n" " \"libbinder_rs\",\n" " \"libbirthdayservice\",\n" " ],\n" " prefer_rlib: true,\n" "}\n" "```" msgstr "" #: src/android/aidl/deploy.md:1 msgid "# Deploy" msgstr "" #: src/android/aidl/deploy.md:3 msgid "We can now build, push, and start the service:" msgstr "" #: src/android/aidl/deploy.md:5 msgid "" "```shell\n" "$ m birthday_server\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/birthday_server /data/local/tmp\n" "$ adb shell /data/local/tmp/birthday_server\n" "```" msgstr "" #: src/android/aidl/deploy.md:11 msgid "In another terminal, check that the service runs:" msgstr "" #: src/android/aidl/deploy.md:13 msgid "" "```shell\n" "$ adb shell service check birthdayservice\n" "Service birthdayservice: found\n" "```" msgstr "" #: src/android/aidl/deploy.md:18 msgid "You can also call the service with `service call`:" msgstr "" #: src/android/aidl/deploy.md:20 msgid "" "```shell\n" "$ $ adb shell service call birthdayservice 1 s16 Bob i32 24\n" "Result: Parcel(\n" " 0x00000000: 00000000 00000036 00610048 00700070 '....6...H.a.p.p.'\n" " 0x00000010: 00200079 00690042 00740072 00640068 'y. .B.i.r.t.h.d.'\n" " 0x00000020: 00790061 00420020 0062006f 0020002c 'a.y. .B.o.b.,. .'\n" " 0x00000030: 006f0063 0067006e 00610072 00750074 'c.o.n.g.r.a.t.u.'\n" " 0x00000040: 0061006c 00690074 006e006f 00200073 'l.a.t.i.o.n.s. .'\n" " 0x00000050: 00690077 00680074 00740020 00650068 'w.i.t.h. .t.h.e.'\n" " 0x00000060: 00320020 00200034 00650079 00720061 ' .2.4. .y.e.a.r.'\n" " 0x00000070: 00210073 00000000 's.!..... ')\n" "```" msgstr "" #: src/android/aidl/client.md:1 msgid "# AIDL Client" msgstr "" #: src/android/aidl/client.md:3 msgid "Finally, we can create a Rust client for our new service." msgstr "" #: src/android/aidl/client.md:5 msgid "*birthday_service/src/client.rs*:" msgstr "" #: src/android/aidl/client.md:7 msgid "" "```rust,ignore\n" "//! Birthday service.\n" "use com_example_birthdayservice::aidl::com::example::birthdayservice::IBirthdayService::" "IBirthdayService;\n" "use com_example_birthdayservice::binder;\n" "\n" "const SERVICE_IDENTIFIER: &str = \"birthdayservice\";\n" "\n" "/// Connect to the BirthdayService.\n" "pub fn connect() -> Result, binder::StatusCode> {\n" " binder::get_interface(SERVICE_IDENTIFIER)\n" "}\n" "\n" "/// Call the birthday service.\n" "fn main() -> Result<(), binder::Status> {\n" " let name = std::env::args()\n" " .nth(1)\n" " .unwrap_or_else(|| String::from(\"Bob\"));\n" " let years = std::env::args()\n" " .nth(2)\n" " .and_then(|arg| arg.parse::().ok())\n" " .unwrap_or(42);\n" "\n" " binder::ProcessState::start_thread_pool();\n" " let service = connect().expect(\"Failed to connect to BirthdayService\");\n" " let msg = service.wishHappyBirthday(&name, years)?;\n" " println!(\"{msg}\");\n" " Ok(())\n" "}\n" "```" msgstr "" #: src/android/aidl/client.md:39 msgid "" "```javascript\n" "rust_binary {\n" " name: \"birthday_client\",\n" " crate_name: \"birthday_client\",\n" " srcs: [\"src/client.rs\"],\n" " rustlibs: [\n" " \"com.example.birthdayservice-rust\",\n" " \"libbinder_rs\",\n" " ],\n" " prefer_rlib: true,\n" "}\n" "```" msgstr "" #: src/android/aidl/client.md:52 msgid "Notice that the client does not depend on `libbirthdayservice`." msgstr "" #: src/android/aidl/client.md:54 msgid "Build, push, and run the client on your device:" msgstr "" #: src/android/aidl/client.md:56 msgid "" "```shell\n" "$ m birthday_client\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/birthday_client /data/local/tmp\n" "$ adb shell /data/local/tmp/birthday_client Charlie 60\n" "Happy Birthday Charlie, congratulations with the 60 years!\n" "```" msgstr "" #: src/android/aidl/changing.md:1 msgid "# Changing API" msgstr "" #: src/android/aidl/changing.md:3 msgid "" "Let us extend the API with more functionality: we want to let clients specify a\n" "list of lines for the birthday card:" msgstr "" #: src/android/aidl/changing.md:6 msgid "" "```java\n" "package com.example.birthdayservice;\n" "\n" "/** Birthday service interface. */\n" "interface IBirthdayService {\n" " /** Generate a Happy Birthday message. */\n" " String wishHappyBirthday(String name, int years, in String[] text);\n" "}\n" "```" msgstr "" #: src/android/logging.md:1 src/bare-metal/aps/logging.md:1 msgid "# Logging" msgstr "" #: src/android/logging.md:3 msgid "" "You should use the `log` crate to automatically log to `logcat` (on-device) or\n" "`stdout` (on-host):" msgstr "" #: src/android/logging.md:6 msgid "_hello_rust_logs/Android.bp_:" msgstr "" #: src/android/logging.md:8 msgid "" "```javascript\n" "rust_binary {\n" " name: \"hello_rust_logs\",\n" " crate_name: \"hello_rust_logs\",\n" " srcs: [\"src/main.rs\"],\n" " rustlibs: [\n" " \"liblog_rust\",\n" " \"liblogger\",\n" " ],\n" " prefer_rlib: true,\n" " host_supported: true,\n" "}\n" "```" msgstr "" #: src/android/logging.md:22 msgid "_hello_rust_logs/src/main.rs_:" msgstr "" #: src/android/logging.md:24 msgid "" "```rust,ignore\n" "//! Rust logging demo.\n" "\n" "use log::{debug, error, info};\n" "\n" "/// Logs a greeting.\n" "fn main() {\n" " logger::init(\n" " logger::Config::default()\n" " .with_tag_on_device(\"rust\")\n" " .with_min_level(log::Level::Trace),\n" " );\n" " debug!(\"Starting program.\");\n" " info!(\"Things are going fine.\");\n" " error!(\"Something went wrong!\");\n" "}\n" "```" msgstr "" #: src/android/logging.md:42 src/android/interoperability/with-c/bindgen.md:98 #: src/android/interoperability/with-c/rust.md:73 msgid "Build, push, and run the binary on your device:" msgstr "" #: src/android/logging.md:44 msgid "" "```shell\n" "$ m hello_rust_logs\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/hello_rust_logs /data/local/tmp\n" "$ adb shell /data/local/tmp/hello_rust_logs\n" "```" msgstr "" #: src/android/logging.md:50 msgid "The logs show up in `adb logcat`:" msgstr "" #: src/android/logging.md:52 msgid "" "```shell\n" "$ adb logcat -s rust\n" "09-08 08:38:32.454 2420 2420 D rust: hello_rust_logs: Starting program.\n" "09-08 08:38:32.454 2420 2420 I rust: hello_rust_logs: Things are going fine.\n" "09-08 08:38:32.454 2420 2420 E rust: hello_rust_logs: Something went wrong!\n" "```" msgstr "" #: src/android/interoperability.md:1 msgid "# Interoperability" msgstr "" #: src/android/interoperability.md:3 msgid "" "Rust has excellent support for interoperability with other languages. This means\n" "that you can:" msgstr "" #: src/android/interoperability.md:6 msgid "" "* Call Rust functions from other languages.\n" "* Call functions written in other languages from Rust." msgstr "" #: src/android/interoperability.md:9 msgid "" "When you call functions in a foreign language we say that you're using a\n" "_foreign function interface_, also known as FFI." msgstr "" #: src/android/interoperability/with-c.md:1 msgid "# Interoperability with C" msgstr "" #: src/android/interoperability/with-c.md:3 msgid "" "Rust has full support for linking object files with a C calling convention.\n" "Similarly, you can export Rust functions and call them from C." msgstr "" #: src/android/interoperability/with-c.md:6 msgid "You can do it by hand if you want:" msgstr "" #: src/android/interoperability/with-c.md:8 msgid "" "```rust\n" "extern \"C\" {\n" " fn abs(x: i32) -> i32;\n" "}\n" "\n" "fn main() {\n" " let x = -42;\n" " let abs_x = unsafe { abs(x) };\n" " println!(\"{x}, {abs_x}\");\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c.md:20 msgid "" "We already saw this in the [Safe FFI Wrapper\n" "exercise](../../exercises/day-3/safe-ffi-wrapper.md)." msgstr "" #: src/android/interoperability/with-c.md:23 msgid "" "> This assumes full knowledge of the target platform. Not recommended for\n" "> production." msgstr "" #: src/android/interoperability/with-c.md:26 msgid "We will look at better options next." msgstr "" #: src/android/interoperability/with-c/bindgen.md:1 msgid "# Using Bindgen" msgstr "" #: src/android/interoperability/with-c/bindgen.md:3 msgid "" "The [bindgen](https://rust-lang.github.io/rust-bindgen/introduction.html) tool\n" "can auto-generate bindings from a C header file." msgstr "" #: src/android/interoperability/with-c/bindgen.md:6 msgid "First create a small C library:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:8 msgid "_interoperability/bindgen/libbirthday.h_:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:10 msgid "" "```c\n" "typedef struct card {\n" " const char* name;\n" " int years;\n" "} card;\n" "\n" "void print_card(const card* card);\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:19 msgid "_interoperability/bindgen/libbirthday.c_:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:21 msgid "" "```c\n" "#include \n" "#include \"libbirthday.h\"\n" "\n" "void print_card(const card* card) {\n" " printf(\"+--------------\\n\");\n" " printf(\"| Happy Birthday %s!\\n\", card->name);\n" " printf(\"| Congratulations with the %i years!\\n\", card->years);\n" " printf(\"+--------------\\n\");\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:33 msgid "Add this to your `Android.bp` file:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:35 #: src/android/interoperability/with-c/bindgen.md:55 #: src/android/interoperability/with-c/bindgen.md:69 #: src/android/interoperability/with-c/bindgen.md:108 msgid "_interoperability/bindgen/Android.bp_:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:37 msgid "" "```javascript\n" "cc_library {\n" " name: \"libbirthday\",\n" " srcs: [\"libbirthday.c\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:44 msgid "" "Create a wrapper header file for the library (not strictly needed in this\n" "example):" msgstr "" #: src/android/interoperability/with-c/bindgen.md:47 msgid "_interoperability/bindgen/libbirthday_wrapper.h_:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:49 msgid "" "```c\n" "#include \"libbirthday.h\"\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:53 msgid "You can now auto-generate the bindings:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:57 msgid "" "```javascript\n" "rust_bindgen {\n" " name: \"libbirthday_bindgen\",\n" " crate_name: \"birthday_bindgen\",\n" " wrapper_src: \"libbirthday_wrapper.h\",\n" " source_stem: \"bindings\",\n" " static_libs: [\"libbirthday\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:67 msgid "Finally, we can use the bindings in our Rust program:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:71 msgid "" "```javascript\n" "rust_binary {\n" " name: \"print_birthday_card\",\n" " srcs: [\"main.rs\"],\n" " rustlibs: [\"libbirthday_bindgen\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:79 msgid "_interoperability/bindgen/main.rs_:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:81 msgid "" "```rust,compile_fail\n" "//! Bindgen demo.\n" "\n" "use birthday_bindgen::{card, print_card};\n" "\n" "fn main() {\n" " let name = std::ffi::CString::new(\"Peter\").unwrap();\n" " let card = card {\n" " name: name.as_ptr(),\n" " years: 42,\n" " };\n" " unsafe {\n" " print_card(&card as *const card);\n" " }\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:100 msgid "" "```shell\n" "$ m print_birthday_card\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/print_birthday_card /data/local/tmp\n" "$ adb shell /data/local/tmp/print_birthday_card\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:106 msgid "Finally, we can run auto-generated tests to ensure the bindings work:" msgstr "" #: src/android/interoperability/with-c/bindgen.md:110 msgid "" "```javascript\n" "rust_test {\n" " name: \"libbirthday_bindgen_test\",\n" " srcs: [\":libbirthday_bindgen\"],\n" " crate_name: \"libbirthday_bindgen_test\",\n" " test_suites: [\"general-tests\"],\n" " auto_gen_config: true,\n" " clippy_lints: \"none\", // Generated file, skip linting\n" " lints: \"none\",\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/bindgen.md:122 msgid "" "```shell\n" "$ atest libbirthday_bindgen_test\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:1 msgid "# Calling Rust" msgstr "" #: src/android/interoperability/with-c/rust.md:3 msgid "Exporting Rust functions and types to C is easy:" msgstr "" #: src/android/interoperability/with-c/rust.md:5 msgid "_interoperability/rust/libanalyze/analyze.rs_" msgstr "" #: src/android/interoperability/with-c/rust.md:7 msgid "" "```rust,editable\n" "//! Rust FFI demo.\n" "#![deny(improper_ctypes_definitions)]\n" "\n" "use std::os::raw::c_int;\n" "\n" "/// Analyze the numbers.\n" "#[no_mangle]\n" "pub extern \"C\" fn analyze_numbers(x: c_int, y: c_int) {\n" " if x < y {\n" " println!(\"x ({x}) is smallest!\");\n" " } else {\n" " println!(\"y ({y}) is probably larger than x ({x})\");\n" " }\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:24 msgid "_interoperability/rust/libanalyze/analyze.h_" msgstr "" #: src/android/interoperability/with-c/rust.md:26 msgid "" "```c\n" "#ifndef ANALYSE_H\n" "#define ANALYSE_H\n" "\n" "extern \"C\" {\n" "void analyze_numbers(int x, int y);\n" "}\n" "\n" "#endif\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:37 msgid "_interoperability/rust/libanalyze/Android.bp_" msgstr "" #: src/android/interoperability/with-c/rust.md:39 msgid "" "```javascript\n" "rust_ffi {\n" " name: \"libanalyze_ffi\",\n" " crate_name: \"analyze_ffi\",\n" " srcs: [\"analyze.rs\"],\n" " include_dirs: [\".\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:48 msgid "We can now call this from a C binary:" msgstr "" #: src/android/interoperability/with-c/rust.md:50 msgid "_interoperability/rust/analyze/main.c_" msgstr "" #: src/android/interoperability/with-c/rust.md:52 msgid "" "```c\n" "#include \"analyze.h\"\n" "\n" "int main() {\n" " analyze_numbers(10, 20);\n" " analyze_numbers(123, 123);\n" " return 0;\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:62 msgid "_interoperability/rust/analyze/Android.bp_" msgstr "" #: src/android/interoperability/with-c/rust.md:64 msgid "" "```javascript\n" "cc_binary {\n" " name: \"analyze_numbers\",\n" " srcs: [\"main.c\"],\n" " static_libs: [\"libanalyze_ffi\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:75 msgid "" "```shell\n" "$ m analyze_numbers\n" "$ adb push $ANDROID_PRODUCT_OUT/system/bin/analyze_numbers /data/local/tmp\n" "$ adb shell /data/local/tmp/analyze_numbers\n" "```" msgstr "" #: src/android/interoperability/with-c/rust.md:83 msgid "" "`#[no_mangle]` disables Rust's usual name mangling, so the exported symbol will just be the name " "of\n" "the function. You can also use `#[export_name = \"some_name\"]` to specify whatever name you want." msgstr "" #: src/android/interoperability/cpp.md:1 msgid "# With C++" msgstr "" #: src/android/interoperability/cpp.md:3 msgid "" "The [CXX crate][1] makes it possible to do safe interoperability between Rust\n" "and C++." msgstr "" #: src/android/interoperability/cpp.md:6 msgid "The overall approach looks like this:" msgstr "" #: src/android/interoperability/cpp.md:8 msgid "" msgstr "" #: src/android/interoperability/cpp.md:10 msgid "See the [CXX tutorial][2] for an full example of using this." msgstr "" #: src/android/interoperability/java.md:1 msgid "# Interoperability with Java" msgstr "" #: src/android/interoperability/java.md:3 msgid "" "Java can load shared objects via [Java Native Interface\n" "(JNI)](https://en.wikipedia.org/wiki/Java_Native_Interface). The [`jni`\n" "crate](https://docs.rs/jni/) allows you to create a compatible library." msgstr "" #: src/android/interoperability/java.md:7 msgid "First, we create a Rust function to export to Java:" msgstr "" #: src/android/interoperability/java.md:9 msgid "_interoperability/java/src/lib.rs_:" msgstr "" #: src/android/interoperability/java.md:11 msgid "" "```rust,compile_fail\n" "//! Rust <-> Java FFI demo.\n" "\n" "use jni::objects::{JClass, JString};\n" "use jni::sys::jstring;\n" "use jni::JNIEnv;\n" "\n" "/// HelloWorld::hello method implementation.\n" "#[no_mangle]\n" "pub extern \"system\" fn Java_HelloWorld_hello(\n" " env: JNIEnv,\n" " _class: JClass,\n" " name: JString,\n" ") -> jstring {\n" " let input: String = env.get_string(name).unwrap().into();\n" " let greeting = format!(\"Hello, {input}!\");\n" " let output = env.new_string(greeting).unwrap();\n" " output.into_inner()\n" "}\n" "```" msgstr "" #: src/android/interoperability/java.md:32 src/android/interoperability/java.md:62 msgid "_interoperability/java/Android.bp_:" msgstr "" #: src/android/interoperability/java.md:34 msgid "" "```javascript\n" "rust_ffi_shared {\n" " name: \"libhello_jni\",\n" " crate_name: \"hello_jni\",\n" " srcs: [\"src/lib.rs\"],\n" " rustlibs: [\"libjni\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/java.md:43 msgid "Finally, we can call this function from Java:" msgstr "" #: src/android/interoperability/java.md:45 msgid "_interoperability/java/HelloWorld.java_:" msgstr "" #: src/android/interoperability/java.md:47 msgid "" "```java\n" "class HelloWorld {\n" " private static native String hello(String name);\n" "\n" " static {\n" " System.loadLibrary(\"hello_jni\");\n" " }\n" "\n" " public static void main(String[] args) {\n" " String output = HelloWorld.hello(\"Alice\");\n" " System.out.println(output);\n" " }\n" "}\n" "```" msgstr "" #: src/android/interoperability/java.md:64 msgid "" "```javascript\n" "java_binary {\n" " name: \"helloworld_jni\",\n" " srcs: [\"HelloWorld.java\"],\n" " main_class: \"HelloWorld\",\n" " required: [\"libhello_jni\"],\n" "}\n" "```" msgstr "" #: src/android/interoperability/java.md:73 msgid "Finally, you can build, sync, and run the binary:" msgstr "" #: src/android/interoperability/java.md:75 msgid "" "```shell\n" "$ m helloworld_jni\n" "$ adb sync # requires adb root && adb remount\n" "$ adb shell /system/bin/helloworld_jni\n" "```" msgstr "" #: src/exercises/android/morning.md:1 src/exercises/bare-metal/morning.md:1 #: src/exercises/bare-metal/afternoon.md:1 src/exercises/concurrency/morning.md:1 #: src/exercises/concurrency/afternoon.md:1 msgid "# Exercises" msgstr "" #: src/exercises/android/morning.md:3 msgid "" "This is a group exercise: We will look at one of the projects you work with and\n" "try to integrate some Rust into it. Some suggestions:" msgstr "" #: src/exercises/android/morning.md:6 msgid "" "* Call your AIDL service with a client written in Rust.\n" "\n" "* Move a function from your project to Rust and call it." msgstr "" #: src/exercises/android/morning.md:12 msgid "" "No solution is provided here since this is open-ended: it relies on someone in\n" "the class having a piece of code which you can turn in to Rust on the fly." msgstr "" #: src/bare-metal.md:1 msgid "# Welcome to Bare Metal Rust" msgstr "" #: src/bare-metal.md:3 msgid "" "This is a standalone one-day course about bare-metal Rust, aimed at people who are familiar with " "the\n" "basics of Rust (perhaps from completing the Comprehensive Rust course), and ideally also have " "some\n" "experience with bare-metal programming in some other language such as C." msgstr "" #: src/bare-metal.md:7 msgid "" "Today we will talk about 'bare-metal' Rust: running Rust code without an OS underneath us. This " "will\n" "be divided into several parts:" msgstr "" #: src/bare-metal.md:10 msgid "" "- What is `no_std` Rust?\n" "- Writing firmware for microcontrollers.\n" "- Writing bootloader / kernel code for application processors.\n" "- Some useful crates for bare-metal Rust development." msgstr "" #: src/bare-metal.md:15 msgid "" "For the microcontroller part of the course we will use the [BBC micro:bit](https://microbit.org/) " "v2\n" "as an example. It's a [development board](https://tech.microbit.org/hardware/) based on the " "Nordic\n" "nRF51822 microcontroller with some LEDs and buttons, an I2C-connected accelerometer and compass, " "and\n" "an on-board SWD debugger." msgstr "" #: src/bare-metal.md:20 msgid "To get started, install some tools we'll need later. On gLinux or Debian:" msgstr "" #: src/bare-metal.md:22 msgid "" "```bash\n" "sudo apt install gcc-aarch64-linux-gnu gdb-multiarch libudev-dev picocom pkg-config qemu-system-" "arm\n" "rustup update\n" "rustup target add aarch64-unknown-none thumbv7em-none-eabihf\n" "rustup component add llvm-tools-preview\n" "cargo install cargo-binutils cargo-embed\n" "```" msgstr "" #: src/bare-metal.md:30 msgid "And give users in the `plugdev` group access to the micro:bit programmer:" msgstr "" #: src/bare-metal.md:32 msgid "" "```bash\n" "echo 'SUBSYSTEM==\"usb\", ATTR{idVendor}==\"0d28\", MODE=\"0664\", GROUP=\"plugdev\"' |\\\n" " sudo tee /etc/udev/rules.d/50-microbit.rules\n" "sudo udevadm control --reload-rules\n" "```" msgstr "" #: src/bare-metal.md:38 msgid "On MacOS:" msgstr "" #: src/bare-metal.md:40 msgid "" "```bash\n" "xcode-select --install\n" "brew install gdb picocom qemu\n" "brew install --cask gcc-aarch64-embedded\n" "rustup update\n" "rustup target add aarch64-unknown-none thumbv7em-none-eabihf\n" "rustup component add llvm-tools-preview\n" "cargo install cargo-binutils cargo-embed\n" "```" msgstr "" #: src/bare-metal/no_std.md:1 msgid "# `no_std`" msgstr "" #: src/bare-metal/no_std.md:3 msgid "" "\n" "\n" "\n" "\n" "\n" "\n" "\n" "\n" "\n" "
" msgstr "" #: src/bare-metal/no_std.md:7 msgid "`core`" msgstr "" #: src/bare-metal/no_std.md:9 src/bare-metal/no_std.md:14 msgid "" "" msgstr "" #: src/bare-metal/no_std.md:12 msgid "`alloc`" msgstr "" #: src/bare-metal/no_std.md:17 msgid "`std`" msgstr "" #: src/bare-metal/no_std.md:19 msgid "" "
" msgstr "" #: src/bare-metal/no_std.md:24 msgid "" "* Slices, `&str`, `CStr`\n" "* `NonZeroU8`...\n" "* `Option`, `Result`\n" "* `Display`, `Debug`, `write!`...\n" "* `Iterator`\n" "* `panic!`, `assert_eq!`...\n" "* `NonNull` and all the usual pointer-related functions\n" "* `Future` and `async`/`await`\n" "* `fence`, `AtomicBool`, `AtomicPtr`, `AtomicU32`...\n" "* `Duration`" msgstr "" #: src/bare-metal/no_std.md:35 src/bare-metal/no_std.md:42 msgid "" "" msgstr "" #: src/bare-metal/no_std.md:38 msgid "" "* `Box`, `Cow`, `Arc`, `Rc`\n" "* `Vec`, `BinaryHeap`, `BtreeMap`, `LinkedList`, `VecDeque`\n" "* `String`, `CString`, `format!`" msgstr "" #: src/bare-metal/no_std.md:45 msgid "" "* `Error`\n" "* `HashMap`\n" "* `Mutex`, `Condvar`, `Barrier`, `Once`, `RwLock`, `mpsc`\n" "* `File` and the rest of `fs`\n" "* `println!`, `Read`, `Write`, `Stdin`, `Stdout` and the rest of `io`\n" "* `Path`, `OsString`\n" "* `net`\n" "* `Command`, `Child`, `ExitCode`\n" "* `spawn`, `sleep` and the rest of `thread`\n" "* `SystemTime`, `Instant`" msgstr "" #: src/bare-metal/no_std.md:56 msgid "" "
\n" "\n" "
" msgstr "" #: src/bare-metal/no_std.md:62 msgid "" "* `HashMap` depends on RNG.\n" "* `std` re-exports the contents of both `core` and `alloc`." msgstr "" #: src/bare-metal/minimal.md:1 msgid "# A minimal `no_std` program" msgstr "" #: src/bare-metal/minimal.md:3 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "use core::panic::PanicInfo;\n" "\n" "#[panic_handler]\n" "fn panic(_panic: &PanicInfo) -> ! {\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/minimal.md:17 msgid "" "* This will compile to an empty binary.\n" "* `std` provides a panic handler; without it we must provide our own.\n" "* It can also be provided by another crate, such as `panic-halt`.\n" "* Depending on the target, you may need to compile with `panic = \"abort\"` to avoid an error " "about\n" " `eh_personality`.\n" "* Note that there is no `main` or any other entry point; it's up to you to define your own entry\n" " point. This will typically involve a linker script and some assembly code to set things up " "ready\n" " for Rust code to run." msgstr "" #: src/bare-metal/alloc.md:1 msgid "# `alloc`" msgstr "" #: src/bare-metal/alloc.md:3 msgid "" "To use `alloc` you must implement a\n" "[global (heap) allocator](https://doc.rust-lang.org/stable/std/alloc/trait.GlobalAlloc.html)." msgstr "" #: src/bare-metal/alloc.md:6 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate alloc;\n" "extern crate panic_halt as _;\n" "\n" "use alloc::string::ToString;\n" "use alloc::vec::Vec;\n" "use buddy_system_allocator::LockedHeap;\n" "\n" "#[global_allocator]\n" "static HEAP_ALLOCATOR: LockedHeap<32> = LockedHeap::<32>::new();\n" "\n" "static mut HEAP: [u8; 65536] = [0; 65536];\n" "\n" "pub fn entry() {\n" " // Safe because `HEAP` is only used here and `entry` is only called once.\n" " unsafe {\n" " // Give the allocator some memory to allocate.\n" " HEAP_ALLOCATOR\n" " .lock()\n" " .init(HEAP.as_mut_ptr() as usize, HEAP.len());\n" " }\n" "\n" " // Now we can do things that require heap allocation.\n" " let mut v = Vec::new();\n" " v.push(\"A string\".to_string());\n" "}\n" "```" msgstr "" #: src/bare-metal/alloc.md:39 msgid "" "* `buddy_system_allocator` is a third-party crate implementing a basic buddy system allocator. " "Other\n" " crates are available, or you can write your own or hook into your existing allocator.\n" "* The const parameter of `LockedHeap` is the max order of the allocator; i.e. in this case it can\n" " allocate regions of up to 2**32 bytes.\n" "* If any crate in your dependency tree depends on `alloc` then you must have exactly one global\n" " allocator defined in your binary. Usually this is done in the top-level binary crate.\n" "* `extern crate panic_halt as _` is necessary to ensure that the `panic_halt` crate is linked in " "so\n" " we get its panic handler.\n" "* This example will build but not run, as it doesn't have an entry point." msgstr "" #: src/bare-metal/microcontrollers.md:1 msgid "# Microcontrollers" msgstr "" #: src/bare-metal/microcontrollers.md:3 msgid "" "The `cortex_m_rt` crate provides (among other things) a reset handler for Cortex M " "microcontrollers." msgstr "" #: src/bare-metal/microcontrollers.md:5 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "mod interrupts;\n" "\n" "use cortex_m_rt::entry;\n" "\n" "#[entry]\n" "fn main() -> ! {\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/microcontrollers.md:21 msgid "Next we'll look at how to access peripherals, with increasing levels of abstraction." msgstr "" #: src/bare-metal/microcontrollers.md:25 msgid "" "* The `cortex_m_rt::entry` macro requires that the function have type `fn() -> !`, because " "returning\n" " to the reset handler doesn't make sense.\n" "* Run the example with `cargo embed --bin minimal`" msgstr "" #: src/bare-metal/microcontrollers/mmio.md:1 msgid "# Raw MMIO" msgstr "" #: src/bare-metal/microcontrollers/mmio.md:3 msgid "" "Most microcontrollers access peripherals via memory-mapped IO. Let's try turning on an LED on our\n" "micro:bit:" msgstr "" #: src/bare-metal/microcontrollers/mmio.md:6 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "mod interrupts;\n" "\n" "use core::mem::size_of;\n" "use cortex_m_rt::entry;\n" "\n" "/// GPIO port 0 peripheral address\n" "const GPIO_P0: usize = 0x5000_0000;\n" "\n" "// GPIO peripheral offsets\n" "const PIN_CNF: usize = 0x700;\n" "const OUTSET: usize = 0x508;\n" "const OUTCLR: usize = 0x50c;\n" "\n" "// PIN_CNF fields\n" "const DIR_OUTPUT: u32 = 0x1;\n" "const INPUT_DISCONNECT: u32 = 0x1 << 1;\n" "const PULL_DISABLED: u32 = 0x0 << 2;\n" "const DRIVE_S0S1: u32 = 0x0 << 8;\n" "const SENSE_DISABLED: u32 = 0x0 << 16;\n" "\n" "#[entry]\n" "fn main() -> ! {\n" " // Configure GPIO 0 pins 21 and 28 as push-pull outputs.\n" " let pin_cnf_21 = (GPIO_P0 + PIN_CNF + 21 * size_of::()) as *mut u32;\n" " let pin_cnf_28 = (GPIO_P0 + PIN_CNF + 28 * size_of::()) as *mut u32;\n" " // Safe because the pointers are to valid peripheral control registers, and\n" " // no aliases exist.\n" " unsafe {\n" " pin_cnf_21.write_volatile(\n" " DIR_OUTPUT | INPUT_DISCONNECT | PULL_DISABLED | DRIVE_S0S1 | SENSE_DISABLED,\n" " );\n" " pin_cnf_28.write_volatile(\n" " DIR_OUTPUT | INPUT_DISCONNECT | PULL_DISABLED | DRIVE_S0S1 | SENSE_DISABLED,\n" " );\n" " }\n" "\n" " // Set pin 28 low and pin 21 high to turn the LED on.\n" " let gpio0_outset = (GPIO_P0 + OUTSET) as *mut u32;\n" " let gpio0_outclr = (GPIO_P0 + OUTCLR) as *mut u32;\n" " // Safe because the pointers are to valid peripheral control registers, and\n" " // no aliases exist.\n" " unsafe {\n" " gpio0_outclr.write_volatile(1 << 28);\n" " gpio0_outset.write_volatile(1 << 21);\n" " }\n" "\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/microcontrollers/mmio.md:64 msgid "" "* GPIO 0 pin 21 is connected to the first column of the LED matrix, and pin 28 to the first row." msgstr "" #: src/bare-metal/microcontrollers/mmio.md:66 src/bare-metal/microcontrollers/pacs.md:59 #: src/bare-metal/microcontrollers/hals.md:43 src/bare-metal/microcontrollers/board-support.md:34 msgid "Run the example with:" msgstr "" #: src/bare-metal/microcontrollers/mmio.md:68 msgid "" "```sh\n" "cargo embed --bin mmio\n" "```" msgstr "" #: src/bare-metal/microcontrollers/pacs.md:1 msgid "# Peripheral Access Crates" msgstr "" #: src/bare-metal/microcontrollers/pacs.md:3 msgid "" "[`svd2rust`](https://crates.io/crates/svd2rust) generates mostly-safe Rust wrappers for\n" "memory-mapped peripherals from [CMSIS-SVD](https://www.keil.com/pack/doc/CMSIS/SVD/html/index." "html)\n" "files." msgstr "" #: src/bare-metal/microcontrollers/pacs.md:7 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "use cortex_m_rt::entry;\n" "use nrf52833_pac::Peripherals;\n" "\n" "#[entry]\n" "fn main() -> ! {\n" " let p = Peripherals::take().unwrap();\n" " let gpio0 = p.P0;\n" "\n" " // Configure GPIO 0 pins 21 and 28 as push-pull outputs.\n" " gpio0.pin_cnf[21].write(|w| {\n" " w.dir().output();\n" " w.input().disconnect();\n" " w.pull().disabled();\n" " w.drive().s0s1();\n" " w.sense().disabled();\n" " w\n" " });\n" " gpio0.pin_cnf[28].write(|w| {\n" " w.dir().output();\n" " w.input().disconnect();\n" " w.pull().disabled();\n" " w.drive().s0s1();\n" " w.sense().disabled();\n" " w\n" " });\n" "\n" " // Set pin 28 low and pin 21 high to turn the LED on.\n" " gpio0.outclr.write(|w| w.pin28().clear());\n" " gpio0.outset.write(|w| w.pin21().set());\n" "\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/microcontrollers/pacs.md:49 msgid "" "* SVD (System View Description) files are XML files typically provided by silicon vendors which\n" " describe the memory map of the device.\n" " * They are organised by peripheral, register, field and value, with names, descriptions, " "addresses\n" " and so on.\n" " * SVD files are often buggy and incomplete, so there are various projects which patch the\n" " mistakes, add missing details, and publish the generated crates.\n" "* `cortex-m-rt` provides the vector table, among other things.\n" "* If you `cargo install cargo-binutils` then you can run\n" " `cargo objdump --bin pac -- -d --no-show-raw-insn` to see the resulting binary." msgstr "" #: src/bare-metal/microcontrollers/pacs.md:61 msgid "" "```sh\n" "cargo embed --bin pac\n" "```" msgstr "" #: src/bare-metal/microcontrollers/hals.md:1 msgid "# HAL crates" msgstr "" #: src/bare-metal/microcontrollers/hals.md:3 msgid "" "[HAL crates](https://github.com/rust-embedded/awesome-embedded-rust#hal-implementation-crates) " "for\n" "many microcontrollers provide wrappers around various peripherals. These generally implement " "traits\n" "from [`embedded-hal`](https://crates.io/crates/embedded-hal)." msgstr "" #: src/bare-metal/microcontrollers/hals.md:7 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "use cortex_m_rt::entry;\n" "use nrf52833_hal::gpio::{p0, Level};\n" "use nrf52833_hal::pac::Peripherals;\n" "use nrf52833_hal::prelude::*;\n" "\n" "#[entry]\n" "fn main() -> ! {\n" " let p = Peripherals::take().unwrap();\n" "\n" " // Create HAL wrapper for GPIO port 0.\n" " let gpio0 = p0::Parts::new(p.P0);\n" "\n" " // Configure GPIO 0 pins 21 and 28 as push-pull outputs.\n" " let mut col1 = gpio0.p0_28.into_push_pull_output(Level::High);\n" " let mut row1 = gpio0.p0_21.into_push_pull_output(Level::Low);\n" "\n" " // Set pin 28 low and pin 21 high to turn the LED on.\n" " col1.set_low().unwrap();\n" " row1.set_high().unwrap();\n" "\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/microcontrollers/hals.md:39 msgid "" " * `set_low` and `set_high` are methods on the `embedded_hal` `OutputPin` trait.\n" " * HAL crates exist for many Cortex-M and RISC-V devices, including various STM32, GD32, nRF, " "NXP,\n" " MSP430, AVR and PIC microcontrollers." msgstr "" #: src/bare-metal/microcontrollers/hals.md:45 msgid "" "```sh\n" "cargo embed --bin hal\n" "```" msgstr "" #: src/bare-metal/microcontrollers/board-support.md:1 msgid "# Board support crates" msgstr "" #: src/bare-metal/microcontrollers/board-support.md:3 msgid "" "Board support crates provide a further level of wrapping for a specific board for convenience." msgstr "" #: src/bare-metal/microcontrollers/board-support.md:5 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "use cortex_m_rt::entry;\n" "use microbit::hal::prelude::*;\n" "use microbit::Board;\n" "\n" "#[entry]\n" "fn main() -> ! {\n" " let mut board = Board::take().unwrap();\n" "\n" " board.display_pins.col1.set_low().unwrap();\n" " board.display_pins.row1.set_high().unwrap();\n" "\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/microcontrollers/board-support.md:28 msgid "" " * In this case the board support crate is just providing more useful names, and a bit of\n" " initialisation.\n" " * The crate may also include drivers for some on-board devices outside of the microcontroller\n" " itself.\n" " * `microbit-v2` includes a simple driver for the LED matrix." msgstr "" #: src/bare-metal/microcontrollers/board-support.md:36 msgid "" "```sh\n" "cargo embed --bin board_support\n" "```" msgstr "" #: src/bare-metal/microcontrollers/type-state.md:1 msgid "# The type state pattern" msgstr "" #: src/bare-metal/microcontrollers/type-state.md:3 msgid "" "```rust,editable,compile_fail\n" "#[entry]\n" "fn main() -> ! {\n" " let p = Peripherals::take().unwrap();\n" " let gpio0 = p0::Parts::new(p.P0);\n" "\n" " let pin: P0_01 = gpio0.p0_01;\n" "\n" " // let gpio0_01_again = gpio0.p0_01; // Error, moved.\n" " let pin_input: P0_01> = pin.into_floating_input();\n" " if pin_input.is_high().unwrap() {\n" " // ...\n" " }\n" " let mut pin_output: P0_01> = pin_input\n" " .into_open_drain_output(OpenDrainConfig::Disconnect0Standard1, Level::Low);\n" " pin_output.set_high().unwrap();\n" " // pin_input.is_high(); // Error, moved.\n" "\n" " let _pin2: P0_02> = gpio0\n" " .p0_02\n" " .into_open_drain_output(OpenDrainConfig::Disconnect0Standard1, Level::Low);\n" " let _pin3: P0_03> = gpio0.p0_03.into_push_pull_output(Level::Low);\n" "\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/microcontrollers/type-state.md:32 msgid "" " * Pins don't implement `Copy` or `Clone`, so only one instance of each can exist. Once a pin is\n" " moved out of the port struct nobody else can take it.\n" " * Changing the configuration of a pin consumes the old pin instance, so you can’t keep use the " "old\n" " instance afterwards.\n" " * The type of a value indicates the state that it is in: e.g. in this case, the configuration " "state\n" " of a GPIO pin. This encodes the state machine into the type system, and ensures that you don't\n" " try to use a pin in a certain way without properly configuring it first. Illegal state\n" " transitions are caught at compile time.\n" " * You can call `is_high` on an input pin and `set_high` on an output pin, but not vice-versa.\n" " * Many HAL crates follow this pattern." msgstr "" #: src/bare-metal/microcontrollers/embedded-hal.md:1 msgid "# `embedded-hal`" msgstr "" #: src/bare-metal/microcontrollers/embedded-hal.md:3 msgid "" "The [`embedded-hal`](https://crates.io/crates/embedded-hal) crate provides a number of traits\n" "covering common microcontroller peripherals." msgstr "" #: src/bare-metal/microcontrollers/embedded-hal.md:6 msgid "" " * GPIO\n" " * ADC\n" " * I2C, SPI, UART, CAN\n" " * RNG\n" " * Timers\n" " * Watchdogs" msgstr "" #: src/bare-metal/microcontrollers/embedded-hal.md:13 msgid "" "Other crates then implement\n" "[drivers](https://github.com/rust-embedded/awesome-embedded-rust#driver-crates) in terms of these\n" "traits, e.g. an accelerometer driver might need an I2C or SPI bus implementation." msgstr "" #: src/bare-metal/microcontrollers/embedded-hal.md:19 msgid "" " * There are implementations for many microcontrollers, as well as other platforms such as Linux " "on\n" "Raspberry Pi.\n" " * There is work in progress on an `async` version of `embedded-hal`, but it isn't stable yet." msgstr "" #: src/bare-metal/microcontrollers/probe-rs.md:1 msgid "# `probe-rs`, `cargo-embed`" msgstr "" #: src/bare-metal/microcontrollers/probe-rs.md:3 msgid "" "[probe-rs](https://probe.rs/) is a handy toolset for embedded debugging, like OpenOCD but better\n" "integrated." msgstr "" #: src/bare-metal/microcontrollers/probe-rs.md:6 msgid "" "* SWD and JTAG via CMSIS-DAP, ST-Link and J-Link probes\n" "* GDB stub and Microsoft DAP server\n" "* Cargo integration" msgstr "" #: src/bare-metal/microcontrollers/probe-rs.md:10 msgid "" "`cargo-embed` is a cargo subcommand to build and flash binaries, log\n" "RTT output and connect GDB. It's configured by an\n" "`Embed.toml` file in your project directory." msgstr "" #: src/bare-metal/microcontrollers/probe-rs.md:16 msgid "" "* [CMSIS-DAP](https://arm-software.github.io/CMSIS_5/DAP/html/index.html) is an Arm standard\n" " protocol over USB for an in-circuit debugger to access the CoreSight Debug Access Port of " "various\n" " Arm Cortex processors. It's what the on-board debugger on the BBC micro:bit uses.\n" "* ST-Link is a range of in-circuit debuggers from ST Microelectronics, J-Link is a range from\n" " SEGGER.\n" "* The Debug Access Port is usually either a 5-pin JTAG interface or 2-pin Serial Wire Debug.\n" "* probe-rs is a library which you can integrate into your own tools if you want to.\n" "* The [Microsoft Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) " "lets\n" " VSCode and other IDEs debug code running on any supported microcontroller.\n" "* cargo-embed is a binary built using the probe-rs library.\n" "* RTT (Real Time Transfers) is a mechanism to transfer data between the debug host and the target\n" " through a number of ringbuffers." msgstr "" #: src/bare-metal/microcontrollers/debugging.md:1 msgid "# Debugging" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:3 msgid "Embed.toml:" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:5 msgid "" "```toml\n" "[default.general]\n" "chip = \"nrf52833_xxAA\"\n" "\n" "[debug.gdb]\n" "enabled = true\n" "```" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:13 msgid "In one terminal under `src/bare-metal/microcontrollers/examples/`:" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:15 msgid "" "```sh\n" "cargo embed --bin board_support debug\n" "```" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:19 msgid "In another terminal in the same directory:" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:21 msgid "" "```sh\n" "gdb-multiarch target/thumbv7em-none-eabihf/debug/board_support --eval-command=\"target " "remote :1337\"\n" "```" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:27 msgid "In GDB, try running:" msgstr "" #: src/bare-metal/microcontrollers/debugging.md:29 msgid "" "```gdb\n" "b src/bin/board_support.rs:29\n" "b src/bin/board_support.rs:30\n" "b src/bin/board_support.rs:32\n" "c\n" "c\n" "c\n" "```" msgstr "" #: src/bare-metal/microcontrollers/other-projects.md:1 src/bare-metal/aps/other-projects.md:1 msgid "# Other projects" msgstr "" #: src/bare-metal/microcontrollers/other-projects.md:3 msgid "" " * [RTIC](https://rtic.rs/)\n" " * \"Real-Time Interrupt-driven Concurrency\"\n" " * Shared resource management, message passing, task scheduling, timer queue\n" " * [Embassy](https://embassy.dev/)\n" " * `async` executors with priorities, timers, networking, USB\n" " * [TockOS](https://www.tockos.org/documentation/getting-started)\n" " * Security-focused RTOS with preemptive scheduling and Memory Protection Unit support\n" " * [Hubris](https://hubris.oxide.computer/)\n" " * Microkernel RTOS from Oxide Computer Company with memory protection, unprivileged drivers, " "IPC\n" " * [Bindings for FreeRTOS](https://github.com/lobaro/FreeRTOS-rust)\n" " * Some platforms have `std` implementations, e.g.\n" " [esp-idf](https://esp-rs.github.io/book/overview/using-the-standard-library.html)." msgstr "" #: src/bare-metal/microcontrollers/other-projects.md:18 msgid "" " * RTIC can be considered either an RTOS or a concurrency framework.\n" " * It doesn't include any HALs.\n" " * It uses the Cortex-M NVIC (Nested Virtual Interrupt Controller) for scheduling rather than a\n" " proper kernel.\n" " * Cortex-M only.\n" " * Google uses TockOS on the Haven microcontroller for Titan security keys.\n" " * FreeRTOS is mostly written in C, but there are Rust bindings for writing applications." msgstr "" #: src/exercises/bare-metal/morning.md:3 msgid "We will read the direction from an I2C compass, and log the readings to a serial port." msgstr "" #: src/exercises/bare-metal/compass.md:1 msgid "# Compass" msgstr "" #: src/exercises/bare-metal/compass.md:3 msgid "" "We will read the direction from an I2C compass, and log the readings to a serial port. If you " "have\n" "time, try displaying it on the LEDs somehow too, or use the buttons somehow." msgstr "" #: src/exercises/bare-metal/compass.md:6 msgid "Hints:" msgstr "" #: src/exercises/bare-metal/compass.md:8 msgid "" "- Check the documentation for the [`lsm303agr`](https://docs.rs/lsm303agr/latest/lsm303agr/) and\n" " [`microbit-v2`](https://docs.rs/microbit-v2/latest/microbit/) crates, as well as the\n" " [micro:bit hardware](https://tech.microbit.org/hardware/).\n" "- The LSM303AGR Inertial Measurement Unit is connected to the internal I2C bus.\n" "- TWI is another name for I2C, so the I2C master peripheral is called TWIM.\n" "- The LSM303AGR driver needs something implementing the `embedded_hal::blocking::i2c::WriteRead`\n" " trait. The\n" " [`microbit::hal::Twim`](https://docs.rs/microbit-v2/latest/microbit/hal/struct.Twim.html) " "struct\n" " implements this.\n" "- You have a [`microbit::Board`](https://docs.rs/microbit-v2/latest/microbit/struct.Board.html)\n" " struct with fields for the various pins and peripherals.\n" "- You can also look at the\n" " [nRF52833 datasheet](https://infocenter.nordicsemi.com/pdf/nRF52833_PS_v1.5.pdf) if you want, " "but\n" " it shouldn't be necessary for this exercise." msgstr "" #: src/exercises/bare-metal/compass.md:23 msgid "" "Download the [exercise template](../../comprehensive-rust-exercises.zip) and look in the " "`compass`\n" "directory for the following files." msgstr "" #: src/exercises/bare-metal/compass.md:26 src/exercises/bare-metal/rtc.md:19 msgid "`src/main.rs`:" msgstr "" #: src/exercises/bare-metal/compass.md:28 src/exercises/bare-metal/rtc.md:21 #: src/exercises/concurrency/dining-philosophers.md:17 src/exercises/concurrency/link-checker.md:55 #: src/exercises/concurrency/dining-philosophers-async.md:11 msgid "" msgstr "" #: src/exercises/bare-metal/compass.md:30 msgid "" "```rust,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "use core::fmt::Write;\n" "use cortex_m_rt::entry;\n" "use microbit::{hal::uarte::{Baudrate, Parity, Uarte}, Board};\n" "\n" "#[entry]\n" "fn main() -> ! {\n" " let board = Board::take().unwrap();\n" "\n" " // Configure serial port.\n" " let mut serial = Uarte::new(\n" " board.UARTE0,\n" " board.uart.into(),\n" " Parity::EXCLUDED,\n" " Baudrate::BAUD115200,\n" " );\n" "\n" " // Set up the I2C controller and Inertial Measurement Unit.\n" " // TODO\n" "\n" " writeln!(serial, \"Ready.\").unwrap();\n" "\n" " loop {\n" " // Read compass data and log it to the serial port.\n" " // TODO\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/compass.md:64 src/exercises/bare-metal/rtc.md:385 msgid "`Cargo.toml` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/compass.md:66 src/exercises/bare-metal/rtc.md:387 #: src/exercises/concurrency/dining-philosophers.md:63 src/exercises/concurrency/link-checker.md:35 #: src/exercises/concurrency/dining-philosophers-async.md:60 src/exercises/concurrency/chat-app.md:17 msgid "" msgstr "" #: src/exercises/bare-metal/compass.md:68 msgid "" "```toml\n" "[workspace]\n" "\n" "[package]\n" "name = \"compass\"\n" "version = \"0.1.0\"\n" "edition = \"2021\"\n" "publish = false\n" "\n" "[dependencies]\n" "cortex-m-rt = \"0.7.3\"\n" "embedded-hal = \"0.2.6\"\n" "lsm303agr = \"0.2.2\"\n" "microbit-v2 = \"0.13.0\"\n" "panic-halt = \"0.2.0\"\n" "```" msgstr "" #: src/exercises/bare-metal/compass.md:85 msgid "`Embed.toml` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/compass.md:87 msgid "" msgstr "" #: src/exercises/bare-metal/compass.md:89 msgid "" "```toml\n" "[default.general]\n" "chip = \"nrf52833_xxAA\"\n" "\n" "[debug.gdb]\n" "enabled = true\n" "\n" "[debug.reset]\n" "halt_afterwards = true\n" "```" msgstr "" #: src/exercises/bare-metal/compass.md:100 src/exercises/bare-metal/rtc.md:985 msgid "`.cargo/config.toml` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/compass.md:102 src/exercises/bare-metal/rtc.md:987 msgid "" msgstr "" #: src/exercises/bare-metal/compass.md:104 msgid "" "```toml\n" "[build]\n" "target = \"thumbv7em-none-eabihf\" # Cortex-M4F\n" "\n" "[target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))']\n" "rustflags = [\"-C\", \"link-arg=-Tlink.x\"]\n" "```" msgstr "" #: src/exercises/bare-metal/compass.md:112 msgid "See the serial output on Linux with:" msgstr "" #: src/exercises/bare-metal/compass.md:114 msgid "" "```sh\n" "picocom --baud 115200 --imap lfcrlf /dev/ttyACM0\n" "```" msgstr "" #: src/exercises/bare-metal/compass.md:118 msgid "Or on Mac OS something like (the device name may be slightly different):" msgstr "" #: src/exercises/bare-metal/compass.md:120 msgid "" "```sh\n" "picocom --baud 115200 --imap lfcrlf /dev/tty.usbmodem14502\n" "```" msgstr "" #: src/exercises/bare-metal/compass.md:124 msgid "Use Ctrl+A Ctrl+Q to quit picocom." msgstr "" #: src/bare-metal/aps.md:1 msgid "# Application processors" msgstr "" #: src/bare-metal/aps.md:3 msgid "" "So far we've talked about microcontrollers, such as the Arm Cortex-M series. Now let's try " "writing\n" "something for Cortex-A. For simplicity we'll just work with QEMU's aarch64\n" "['virt'](https://qemu-project.gitlab.io/qemu/system/arm/virt.html) board." msgstr "" #: src/bare-metal/aps.md:9 msgid "" "* Broadly speaking, microcontrollers don't have an MMU or multiple levels of privilege (exception\n" " levels on Arm CPUs, rings on x86), while application processors do.\n" "* QEMU supports emulating various different machines or board models for each architecture. The\n" " 'virt' board doesn't correspond to any particular real hardware, but is designed purely for\n" " virtual machines." msgstr "" #: src/bare-metal/aps/inline-assembly.md:1 msgid "# Inline assembly" msgstr "" #: src/bare-metal/aps/inline-assembly.md:3 msgid "" "Sometimes we need to use assembly to do things that aren't possible with Rust code. For example,\n" "to make an HVC to tell the firmware to power off the system:" msgstr "" #: src/bare-metal/aps/inline-assembly.md:6 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "use core::arch::asm;\n" "use core::panic::PanicInfo;\n" "\n" "mod exceptions;\n" "\n" "const PSCI_SYSTEM_OFF: u32 = 0x84000008;\n" "\n" "#[no_mangle]\n" "extern \"C\" fn main(_x0: u64, _x1: u64, _x2: u64, _x3: u64) {\n" " // Safe because this only uses the declared registers and doesn't do\n" " // anything with memory.\n" " unsafe {\n" " asm!(\"hvc #0\",\n" " inout(\"w0\") PSCI_SYSTEM_OFF => _,\n" " inout(\"w1\") 0 => _,\n" " inout(\"w2\") 0 => _,\n" " inout(\"w3\") 0 => _,\n" " inout(\"w4\") 0 => _,\n" " inout(\"w5\") 0 => _,\n" " inout(\"w6\") 0 => _,\n" " inout(\"w7\") 0 => _,\n" " options(nomem, nostack)\n" " );\n" " }\n" "\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/inline-assembly.md:39 msgid "" "(If you actually want to do this, use the [`smccc`][1] crate which has wrappers for all these " "functions.)" msgstr "" #: src/bare-metal/aps/inline-assembly.md:43 msgid "" "* PSCI is the Arm Power State Coordination Interface, a standard set of functions to manage " "system\n" " and CPU power states, among other things. It is implemented by EL3 firmware and hypervisors on\n" " many systems.\n" "* The `0 => _` syntax means initialise the register to 0 before running the inline assembly code,\n" " and ignore its contents afterwards. We need to use `inout` rather than `in` because the call " "could\n" " potentially clobber the contents of the registers.\n" "* This `main` function needs to be `#[no_mangle]` and `extern \"C\"` because it is called from " "our\n" " entry point in `entry.S`.\n" "* `_x0`–`_x3` are the values of registers `x0`–`x3`, which are conventionally used by the " "bootloader\n" " to pass things like a pointer to the device tree. According to the standard aarch64 calling\n" " convention (which is what `extern \"C\"` specifies to use), registers `x0`–`x7` are used for " "the\n" " first 8 arguments passed to a function, so `entry.S` doesn't need to do anything special except\n" " make sure it doesn't change these registers.\n" "* Run the example in QEMU with `make qemu_psci` under `src/bare-metal/aps/examples`." msgstr "" #: src/bare-metal/aps/mmio.md:1 msgid "# Volatile memory access for MMIO" msgstr "" #: src/bare-metal/aps/mmio.md:3 msgid "" " * Use `pointer::read_volatile` and `pointer::write_volatile`.\n" " * Never hold a reference.\n" " * `addr_of!` lets you get fields of structs without creating an intermediate reference." msgstr "" #: src/bare-metal/aps/mmio.md:9 msgid "" " * Volatile access: read or write operations may have side-effects, so prevent the compiler or\n" " hardware from reordering, duplicating or eliding them.\n" " * Usually if you write and then read, e.g. via a mutable reference, the compiler may assume " "that\n" " the value read is the same as the value just written, and not bother actually reading " "memory.\n" " * Some existing crates for volatile access to hardware do hold references, but this is unsound.\n" " Whenever a reference exist, the compiler may choose to dereference it.\n" " * Use the `addr_of!` macro to get struct field pointers from a pointer to the struct." msgstr "" #: src/bare-metal/aps/uart.md:1 msgid "# Let's write a UART driver" msgstr "" #: src/bare-metal/aps/uart.md:3 msgid "The QEMU 'virt' machine has a [PL011][1] UART, so let's write a driver for that." msgstr "" #: src/bare-metal/aps/uart.md:5 msgid "" "```rust,editable\n" "const FLAG_REGISTER_OFFSET: usize = 0x18;\n" "const FR_BUSY: u8 = 1 << 3;\n" "const FR_TXFF: u8 = 1 << 5;\n" "\n" "/// Minimal driver for a PL011 UART.\n" "#[derive(Debug)]\n" "pub struct Uart {\n" " base_address: *mut u8,\n" "}\n" "\n" "impl Uart {\n" " /// Constructs a new instance of the UART driver for a PL011 device at the\n" " /// given base address.\n" " ///\n" " /// # Safety\n" " ///\n" " /// The given base address must point to the 8 MMIO control registers of a\n" " /// PL011 device, which must be mapped into the address space of the process\n" " /// as device memory and not have any other aliases.\n" " pub unsafe fn new(base_address: *mut u8) -> Self {\n" " Self { base_address }\n" " }\n" "\n" " /// Writes a single byte to the UART.\n" " pub fn write_byte(&self, byte: u8) {\n" " // Wait until there is room in the TX buffer.\n" " while self.read_flag_register() & FR_TXFF != 0 {}\n" "\n" " // Safe because we know that the base address points to the control\n" " // registers of a PL011 device which is appropriately mapped.\n" " unsafe {\n" " // Write to the TX buffer.\n" " self.base_address.write_volatile(byte);\n" " }\n" "\n" " // Wait until the UART is no longer busy.\n" " while self.read_flag_register() & FR_BUSY != 0 {}\n" " }\n" "\n" " fn read_flag_register(&self) -> u8 {\n" " // Safe because we know that the base address points to the control\n" " // registers of a PL011 device which is appropriately mapped.\n" " unsafe { self.base_address.add(FLAG_REGISTER_OFFSET).read_volatile() }\n" " }\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/uart.md:55 msgid "" "* Note that `Uart::new` is unsafe while the other methods are safe. This is because as long as " "the\n" " caller of `Uart::new` guarantees that its safety requirements are met (i.e. that there is only\n" " ever one instance of the driver for a given UART, and nothing else aliasing its address space),\n" " then it is always safe to call `write_byte` later because we can assume the necessary\n" " preconditions.\n" "* We could have done it the other way around (making `new` safe but `write_byte` unsafe), but " "that\n" " would be much less convenient to use as every place that calls `write_byte` would need to " "reason\n" " about the safety\n" "* This is a common pattern for writing safe wrappers of unsafe code: moving the burden of proof " "for\n" " soundness from a large number of places to a smaller number of places." msgstr "" #: src/bare-metal/aps/uart.md:66 msgid "" msgstr "" #: src/bare-metal/aps/uart/traits.md:1 msgid "# More traits" msgstr "" #: src/bare-metal/aps/uart/traits.md:3 msgid "We derived the `Debug` trait. It would be useful to implement a few more traits too." msgstr "" #: src/bare-metal/aps/uart/traits.md:5 msgid "" "```rust,editable,compile_fail\n" "use core::fmt::{self, Write};\n" "\n" "impl Write for Uart {\n" " fn write_str(&mut self, s: &str) -> fmt::Result {\n" " for c in s.as_bytes() {\n" " self.write_byte(*c);\n" " }\n" " Ok(())\n" " }\n" "}\n" "\n" "// Safe because it just contains a pointer to device memory, which can be\n" "// accessed from any context.\n" "unsafe impl Send for Uart {}\n" "```" msgstr "" #: src/bare-metal/aps/uart/traits.md:24 msgid "" "* Implementing `Write` lets us use the `write!` and `writeln!` macros with our `Uart` type.\n" "* Run the example in QEMU with `make qemu_minimal` under `src/bare-metal/aps/examples`." msgstr "" #: src/bare-metal/aps/better-uart.md:1 msgid "# A better UART driver" msgstr "" #: src/bare-metal/aps/better-uart.md:3 msgid "" "The PL011 actually has [a bunch more registers][1], and adding offsets to construct pointers to " "access\n" "them is error-prone and hard to read. Plus, some of them are bit fields which would be nice to\n" "access in a structured way." msgstr "" #: src/bare-metal/aps/better-uart.md:7 msgid "" "| Offset | Register name | Width |\n" "| ------ | ------------- | ----- |\n" "| 0x00 | DR | 12 |\n" "| 0x04 | RSR | 4 |\n" "| 0x18 | FR | 9 |\n" "| 0x20 | ILPR | 8 |\n" "| 0x24 | IBRD | 16 |\n" "| 0x28 | FBRD | 6 |\n" "| 0x2c | LCR_H | 8 |\n" "| 0x30 | CR | 16 |\n" "| 0x34 | IFLS | 6 |\n" "| 0x38 | IMSC | 11 |\n" "| 0x3c | RIS | 11 |\n" "| 0x40 | MIS | 11 |\n" "| 0x44 | ICR | 11 |\n" "| 0x48 | DMACR | 3 |" msgstr "" #: src/bare-metal/aps/better-uart.md:26 msgid "- There are also some ID registers which have been omitted for brevity." msgstr "" #: src/bare-metal/aps/better-uart/bitflags.md:1 msgid "# Bitflags" msgstr "" #: src/bare-metal/aps/better-uart/bitflags.md:3 msgid "" "The [`bitflags`](https://crates.io/crates/bitflags) crate is useful for working with bitflags." msgstr "" #: src/bare-metal/aps/better-uart/bitflags.md:5 msgid "" "```rust,editable,compile_fail\n" "use bitflags::bitflags;\n" "\n" "bitflags! {\n" " /// Flags from the UART flag register.\n" " #[repr(transparent)]\n" " #[derive(Copy, Clone, Debug, Eq, PartialEq)]\n" " struct Flags: u16 {\n" " /// Clear to send.\n" " const CTS = 1 << 0;\n" " /// Data set ready.\n" " const DSR = 1 << 1;\n" " /// Data carrier detect.\n" " const DCD = 1 << 2;\n" " /// UART busy transmitting data.\n" " const BUSY = 1 << 3;\n" " /// Receive FIFO is empty.\n" " const RXFE = 1 << 4;\n" " /// Transmit FIFO is full.\n" " const TXFF = 1 << 5;\n" " /// Receive FIFO is full.\n" " const RXFF = 1 << 6;\n" " /// Transmit FIFO is empty.\n" " const TXFE = 1 << 7;\n" " /// Ring indicator.\n" " const RI = 1 << 8;\n" " }\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/better-uart/bitflags.md:37 msgid "" "* The `bitflags!` macro creates a newtype something like `Flags(u16)`, along with a bunch of " "method\n" " implementations to get and set flags." msgstr "" #: src/bare-metal/aps/better-uart/registers.md:1 msgid "# Multiple registers" msgstr "" #: src/bare-metal/aps/better-uart/registers.md:3 msgid "We can use a struct to represent the memory layout of the UART's registers." msgstr "" #: src/bare-metal/aps/better-uart/registers.md:5 msgid "" "```rust,editable,compile_fail\n" "#[repr(C, align(4))]\n" "struct Registers {\n" " dr: u16,\n" " _reserved0: [u8; 2],\n" " rsr: ReceiveStatus,\n" " _reserved1: [u8; 19],\n" " fr: Flags,\n" " _reserved2: [u8; 6],\n" " ilpr: u8,\n" " _reserved3: [u8; 3],\n" " ibrd: u16,\n" " _reserved4: [u8; 2],\n" " fbrd: u8,\n" " _reserved5: [u8; 3],\n" " lcr_h: u8,\n" " _reserved6: [u8; 3],\n" " cr: u16,\n" " _reserved7: [u8; 3],\n" " ifls: u8,\n" " _reserved8: [u8; 3],\n" " imsc: u16,\n" " _reserved9: [u8; 2],\n" " ris: u16,\n" " _reserved10: [u8; 2],\n" " mis: u16,\n" " _reserved11: [u8; 2],\n" " icr: u16,\n" " _reserved12: [u8; 2],\n" " dmacr: u8,\n" " _reserved13: [u8; 3],\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/better-uart/registers.md:41 msgid "" "* [`#[repr(C)]`](https://doc.rust-lang.org/reference/type-layout.html#the-c-representation) tells\n" " the compiler to lay the struct fields out in order, following the same rules as C. This is\n" " necessary for our struct to have a predictable layout, as default Rust representation allows " "the\n" " compiler to (among other things) reorder fields however it sees fit." msgstr "" #: src/bare-metal/aps/better-uart/driver.md:1 msgid "# Driver" msgstr "" #: src/bare-metal/aps/better-uart/driver.md:3 msgid "Now let's use the new `Registers` struct in our driver." msgstr "" #: src/bare-metal/aps/better-uart/driver.md:5 msgid "" "```rust,editable,compile_fail\n" "/// Driver for a PL011 UART.\n" "#[derive(Debug)]\n" "pub struct Uart {\n" " registers: *mut Registers,\n" "}\n" "\n" "impl Uart {\n" " /// Constructs a new instance of the UART driver for a PL011 device at the\n" " /// given base address.\n" " ///\n" " /// # Safety\n" " ///\n" " /// The given base address must point to the 8 MMIO control registers of a\n" " /// PL011 device, which must be mapped into the address space of the process\n" " /// as device memory and not have any other aliases.\n" " pub unsafe fn new(base_address: *mut u32) -> Self {\n" " Self {\n" " registers: base_address as *mut Registers,\n" " }\n" " }\n" "\n" " /// Writes a single byte to the UART.\n" " pub fn write_byte(&self, byte: u8) {\n" " // Wait until there is room in the TX buffer.\n" " while self.read_flag_register().contains(Flags::TXFF) {}\n" "\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL011 device which is appropriately mapped.\n" " unsafe {\n" " // Write to the TX buffer.\n" " addr_of_mut!((*self.registers).dr).write_volatile(byte.into());\n" " }\n" "\n" " // Wait until the UART is no longer busy.\n" " while self.read_flag_register().contains(Flags::BUSY) {}\n" " }\n" "\n" " /// Reads and returns a pending byte, or `None` if nothing has been received.\n" " pub fn read_byte(&self) -> Option {\n" " if self.read_flag_register().contains(Flags::RXFE) {\n" " None\n" " } else {\n" " let data = unsafe { addr_of!((*self.registers).dr).read_volatile() };\n" " // TODO: Check for error conditions in bits 8-11.\n" " Some(data as u8)\n" " }\n" " }\n" "\n" " fn read_flag_register(&self) -> Flags {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL011 device which is appropriately mapped.\n" " unsafe { addr_of!((*self.registers).fr).read_volatile() }\n" " }\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/better-uart/driver.md:64 msgid "" "* Note the use of `addr_of!` / `addr_of_mut!` to get pointers to individual fields without " "creating\n" " an intermediate reference, which would be unsound." msgstr "" #: src/bare-metal/aps/better-uart/using.md:1 src/bare-metal/aps/logging/using.md:1 msgid "# Using it" msgstr "" #: src/bare-metal/aps/better-uart/using.md:3 msgid "" "Let's write a small program using our driver to write to the serial console, and echo incoming\n" "bytes." msgstr "" #: src/bare-metal/aps/better-uart/using.md:6 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "mod exceptions;\n" "mod pl011;\n" "\n" "use crate::pl011::Uart;\n" "use core::fmt::Write;\n" "use core::panic::PanicInfo;\n" "use log::error;\n" "use smccc::psci::system_off;\n" "use smccc::Hvc;\n" "\n" "/// Base address of the primary PL011 UART.\n" "const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;\n" "\n" "#[no_mangle]\n" "extern \"C\" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {\n" " // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,\n" " // and nothing else accesses that address range.\n" " let mut uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };\n" "\n" " writeln!(uart, \"main({x0:#x}, {x1:#x}, {x2:#x}, {x3:#x})\").unwrap();\n" "\n" " loop {\n" " if let Some(b) = uart.read_byte() {\n" " uart.write_byte(b);\n" " match b {\n" " b'\\r' => {\n" " uart.write_byte(b'\\n');\n" " }\n" " b'q' => break,\n" " _ => {}\n" " }\n" " }\n" " }\n" "\n" " writeln!(uart, \"Bye!\").unwrap();\n" " system_off::().unwrap();\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/better-uart/using.md:51 msgid "" "* As in the [inline assembly](../inline-assembly.md) example, this `main` function is called from " "our\n" " entry point code in `entry.S`. See the speaker notes there for details.\n" "* Run the example in QEMU with `make qemu` under `src/bare-metal/aps/examples`." msgstr "" #: src/bare-metal/aps/logging.md:3 msgid "" "It would be nice to be able to use the logging macros from the [`log`][1] crate. We can do this " "by\n" "implementing the `Log` trait." msgstr "" #: src/bare-metal/aps/logging.md:6 msgid "" "```rust,editable,compile_fail\n" "use crate::pl011::Uart;\n" "use core::fmt::Write;\n" "use log::{LevelFilter, Log, Metadata, Record, SetLoggerError};\n" "use spin::mutex::SpinMutex;\n" "\n" "static LOGGER: Logger = Logger {\n" " uart: SpinMutex::new(None),\n" "};\n" "\n" "struct Logger {\n" " uart: SpinMutex>,\n" "}\n" "\n" "impl Log for Logger {\n" " fn enabled(&self, _metadata: &Metadata) -> bool {\n" " true\n" " }\n" "\n" " fn log(&self, record: &Record) {\n" " writeln!(\n" " self.uart.lock().as_mut().unwrap(),\n" " \"[{}] {}\",\n" " record.level(),\n" " record.args()\n" " )\n" " .unwrap();\n" " }\n" "\n" " fn flush(&self) {}\n" "}\n" "\n" "/// Initialises UART logger.\n" "pub fn init(uart: Uart, max_level: LevelFilter) -> Result<(), SetLoggerError> {\n" " LOGGER.uart.lock().replace(uart);\n" "\n" " log::set_logger(&LOGGER)?;\n" " log::set_max_level(max_level);\n" " Ok(())\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/logging.md:50 msgid "* The unwrap in `log` is safe because we initialise `LOGGER` before calling `set_logger`." msgstr "" #: src/bare-metal/aps/logging/using.md:3 msgid "We need to initialise the logger before we use it." msgstr "" #: src/bare-metal/aps/logging/using.md:5 msgid "" "```rust,editable,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "mod exceptions;\n" "mod logger;\n" "mod pl011;\n" "\n" "use crate::pl011::Uart;\n" "use core::panic::PanicInfo;\n" "use log::{error, info, LevelFilter};\n" "use smccc::psci::system_off;\n" "use smccc::Hvc;\n" "\n" "/// Base address of the primary PL011 UART.\n" "const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;\n" "\n" "#[no_mangle]\n" "extern \"C\" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {\n" " // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,\n" " // and nothing else accesses that address range.\n" " let uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };\n" " logger::init(uart, LevelFilter::Trace).unwrap();\n" "\n" " info!(\"main({x0:#x}, {x1:#x}, {x2:#x}, {x3:#x})\");\n" "\n" " assert_eq!(x1, 42);\n" "\n" " system_off::().unwrap();\n" "}\n" "\n" "#[panic_handler]\n" "fn panic(info: &PanicInfo) -> ! {\n" " error!(\"{info}\");\n" " system_off::().unwrap();\n" " loop {}\n" "}\n" "```" msgstr "" #: src/bare-metal/aps/logging/using.md:46 msgid "" "* Note that our panic handler can now log details of panics.\n" "* Run the example in QEMU with `make qemu_logger` under `src/bare-metal/aps/examples`." msgstr "" #: src/bare-metal/aps/other-projects.md:3 msgid "" " * [oreboot](https://github.com/oreboot/oreboot)\n" " * \"coreboot without the C\"\n" " * Supports x86, aarch64 and RISC-V.\n" " * Relies on LinuxBoot rather than having many drivers itself.\n" " * [Rust RaspberryPi OS tutorial](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)\n" " * Initialisation, UART driver, simple bootloader, JTAG, exception levels, exception handling, " "page tables\n" " * Not all very well written, so beware.\n" " * [`cargo-call-stack`](https://crates.io/crates/cargo-call-stack)\n" " * Static analysis to determine maximum stack usage." msgstr "" #: src/bare-metal/useful-crates.md:1 msgid "# Useful crates" msgstr "" #: src/bare-metal/useful-crates.md:3 msgid "We'll go over a few crates which solve some common problems in bare-metal programming." msgstr "" #: src/bare-metal/useful-crates/zerocopy.md:1 msgid "# `zerocopy`" msgstr "" #: src/bare-metal/useful-crates/zerocopy.md:3 msgid "" "The [`zerocopy`][1] crate (from Fuchsia) provides traits and macros for safely converting between\n" "byte sequences and other types." msgstr "" #: src/bare-metal/useful-crates/zerocopy.md:6 msgid "" "```rust,editable,compile_fail\n" "use zerocopy::AsBytes;\n" "\n" "#[repr(u32)]\n" "#[derive(AsBytes, Debug, Default)]\n" "enum RequestType {\n" " #[default]\n" " In = 0,\n" " Out = 1,\n" " Flush = 4,\n" "}\n" "\n" "#[repr(C)]\n" "#[derive(AsBytes, Debug, Default)]\n" "struct VirtioBlockRequest {\n" " request_type: RequestType,\n" " reserved: u32,\n" " sector: u64,\n" "}\n" "\n" "fn main() {\n" " let request = VirtioBlockRequest {\n" " request_type: RequestType::Flush,\n" " sector: 42,\n" " ..Default::default()\n" " };\n" "\n" " assert_eq!(\n" " request.as_bytes(),\n" " &[4, 0, 0, 0, 0, 0, 0, 0, 42, 0, 0, 0, 0, 0, 0, 0]\n" " );\n" "}\n" "```" msgstr "" #: src/bare-metal/useful-crates/zerocopy.md:40 msgid "" "This is not suitable for MMIO (as it doesn't use volatile reads and writes), but can be useful " "for\n" "working with structures shared with hardware e.g. by DMA, or sent over some external interface." msgstr "" #: src/bare-metal/useful-crates/zerocopy.md:45 msgid "" "* `FromBytes` can be implemented for types for which any byte pattern is valid, and so can safely " "be\n" " converted from an untrusted sequence of bytes.\n" "* Attempting to derive `FromBytes` for these types would fail, because `RequestType` doesn't use " "all\n" " possible u32 values as discriminants, so not all byte patterns are valid.\n" "* `zerocopy::byteorder` has types for byte-order aware numeric primitives.\n" "* Run the example with `cargo run` under `src/bare-metal/useful-crates/zerocopy-example/`. (It " "won't\n" " run in the Playground because of the crate dependency.)" msgstr "" #: src/bare-metal/useful-crates/aarch64-paging.md:1 msgid "# `aarch64-paging`" msgstr "" #: src/bare-metal/useful-crates/aarch64-paging.md:3 msgid "" "The [`aarch64-paging`][1] crate lets you create page tables according to the AArch64 Virtual " "Memory\n" "System Architecture." msgstr "" #: src/bare-metal/useful-crates/aarch64-paging.md:6 msgid "" "```rust,editable,compile_fail\n" "use aarch64_paging::{\n" " idmap::IdMap,\n" " paging::{Attributes, MemoryRegion},\n" "};\n" "\n" "const ASID: usize = 1;\n" "const ROOT_LEVEL: usize = 1;\n" "\n" "// Create a new page table with identity mapping.\n" "let mut idmap = IdMap::new(ASID, ROOT_LEVEL);\n" "// Map a 2 MiB region of memory as read-only.\n" "idmap.map_range(\n" " &MemoryRegion::new(0x80200000, 0x80400000),\n" " Attributes::NORMAL | Attributes::NON_GLOBAL | Attributes::READ_ONLY,\n" ").unwrap();\n" "// Set `TTBR0_EL1` to activate the page table.\n" "idmap.activate();\n" "```" msgstr "" #: src/bare-metal/useful-crates/aarch64-paging.md:28 msgid "" "* For now it only supports EL1, but support for other exception levels should be straightforward " "to\n" " add.\n" "* This is used in Android for the [Protected VM Firmware][2].\n" "* There's no easy way to run this example, as it needs to run on real hardware or under QEMU." msgstr "" #: src/bare-metal/useful-crates/buddy_system_allocator.md:1 msgid "# `buddy_system_allocator`" msgstr "" #: src/bare-metal/useful-crates/buddy_system_allocator.md:3 msgid "" "[`buddy_system_allocator`][1] is a third-party crate implementing a basic buddy system allocator.\n" "It can be used both for [`LockedHeap`][2] implementing [`GlobalAlloc`][3] so you can use the\n" "standard `alloc` crate (as we saw [before][4]), or for allocating other address space. For " "example,\n" "we might want to allocate MMIO space for PCI BARs:" msgstr "" #: src/bare-metal/useful-crates/buddy_system_allocator.md:8 msgid "" "```rust,editable,compile_fail\n" "use buddy_system_allocator::FrameAllocator;\n" "use core::alloc::Layout;\n" "\n" "fn main() {\n" " let mut allocator = FrameAllocator::<32>::new();\n" " allocator.add_frame(0x200_0000, 0x400_0000);\n" "\n" " let layout = Layout::from_size_align(0x100, 0x100).unwrap();\n" " let bar = allocator\n" " .alloc_aligned(layout)\n" " .expect(\"Failed to allocate 0x100 byte MMIO region\");\n" " println!(\"Allocated 0x100 byte MMIO region at {:#x}\", bar);\n" "}\n" "```" msgstr "" #: src/bare-metal/useful-crates/buddy_system_allocator.md:26 msgid "" "* PCI BARs always have alignment equal to their size.\n" "* Run the example with `cargo run` under `src/bare-metal/useful-crates/allocator-example/`. (It " "won't\n" " run in the Playground because of the crate dependency.)" msgstr "" #: src/bare-metal/useful-crates/tinyvec.md:1 msgid "# `tinyvec`" msgstr "" #: src/bare-metal/useful-crates/tinyvec.md:3 msgid "" "Sometimes you want something which can be resized like a `Vec`, but without heap allocation.\n" "[`tinyvec`][1] provides this: a vector backed by an array or slice, which could be statically\n" "allocated or on the stack, which keeps track of how many elements are used and panics if you try " "to\n" "use more than are allocated." msgstr "" #: src/bare-metal/useful-crates/tinyvec.md:8 msgid "" "```rust,editable,compile_fail\n" "use tinyvec::{array_vec, ArrayVec};\n" "\n" "fn main() {\n" " let mut numbers: ArrayVec<[u32; 5]> = array_vec!(42, 66);\n" " println!(\"{numbers:?}\");\n" " numbers.push(7);\n" " println!(\"{numbers:?}\");\n" " numbers.remove(1);\n" " println!(\"{numbers:?}\");\n" "}\n" "```" msgstr "" #: src/bare-metal/useful-crates/tinyvec.md:23 msgid "" "* `tinyvec` requires that the element type implement `Default` for initialisation.\n" "* The Rust Playground includes `tinyvec`, so this example will run fine inline." msgstr "" #: src/bare-metal/useful-crates/spin.md:1 msgid "# `spin`" msgstr "" #: src/bare-metal/useful-crates/spin.md:3 msgid "" "`std::sync::Mutex` and the other synchronisation primitives from `std::sync` are not available in\n" "`core` or `alloc`. How can we manage synchronisation or interior mutability, such as for sharing\n" "state between different CPUs?" msgstr "" #: src/bare-metal/useful-crates/spin.md:7 msgid "The [`spin`][1] crate provides spinlock-based equivalents of many of these primitives." msgstr "" #: src/bare-metal/useful-crates/spin.md:9 msgid "" "```rust,editable,compile_fail\n" "use spin::mutex::SpinMutex;\n" "\n" "static counter: SpinMutex = SpinMutex::new(0);\n" "\n" "fn main() {\n" " println!(\"count: {}\", counter.lock());\n" " *counter.lock() += 2;\n" " println!(\"count: {}\", counter.lock());\n" "}\n" "```" msgstr "" #: src/bare-metal/useful-crates/spin.md:23 msgid "" "* Be careful to avoid deadlock if you take locks in interrupt handlers.\n" "* `spin` also has a ticket lock mutex implementation; equivalents of `RwLock`, `Barrier` and " "`Once`\n" " from `std::sync`; and `Lazy` for lazy initialisation.\n" "* The [`once_cell`][2] crate also has some useful types for late initialisation with a slightly\n" " different approach to `spin::once::Once`.\n" "* The Rust Playground includes `spin`, so this example will run fine inline." msgstr "" #: src/bare-metal/android.md:1 msgid "# Android" msgstr "" #: src/bare-metal/android.md:3 msgid "" "To build a bare-metal Rust binary in AOSP, you need to use a `rust_ffi_static` Soong rule to " "build\n" "your Rust code, then a `cc_binary` with a linker script to produce the binary itself, and then a\n" "`raw_binary` to convert the ELF to a raw binary ready to be run." msgstr "" #: src/bare-metal/android.md:7 msgid "" "```soong\n" "rust_ffi_static {\n" " name: \"libvmbase_example\",\n" " defaults: [\"vmbase_ffi_defaults\"],\n" " crate_name: \"vmbase_example\",\n" " srcs: [\"src/main.rs\"],\n" " rustlibs: [\n" " \"libvmbase\",\n" " ],\n" "}\n" "\n" "cc_binary {\n" " name: \"vmbase_example\",\n" " defaults: [\"vmbase_elf_defaults\"],\n" " srcs: [\n" " \"idmap.S\",\n" " ],\n" " static_libs: [\n" " \"libvmbase_example\",\n" " ],\n" " linker_scripts: [\n" " \"image.ld\",\n" " \":vmbase_sections\",\n" " ],\n" "}\n" "\n" "raw_binary {\n" " name: \"vmbase_example_bin\",\n" " stem: \"vmbase_example.bin\",\n" " src: \":vmbase_example\",\n" " enabled: false,\n" " target: {\n" " android_arm64: {\n" " enabled: true,\n" " },\n" " },\n" "}\n" "```" msgstr "" #: src/bare-metal/android/vmbase.md:1 msgid "# vmbase" msgstr "" #: src/bare-metal/android/vmbase.md:3 msgid "" "For VMs running under crosvm on aarch64, the [vmbase][1] library provides a linker script and " "useful\n" "defaults for the build rules, along with an entry point, UART console logging and more." msgstr "" #: src/bare-metal/android/vmbase.md:6 msgid "" "```rust,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "use vmbase::{main, println};\n" "\n" "main!(main);\n" "\n" "pub fn main(arg0: u64, arg1: u64, arg2: u64, arg3: u64) {\n" " println!(\"Hello world\");\n" "}\n" "```" msgstr "" #: src/bare-metal/android/vmbase.md:21 msgid "" "* The `main!` macro marks your main function, to be called from the `vmbase` entry point.\n" "* The `vmbase` entry point handles console initialisation, and issues a PSCI_SYSTEM_OFF to " "shutdown\n" " the VM if your main function returns." msgstr "" #: src/exercises/bare-metal/afternoon.md:3 msgid "We will write a driver for the PL031 real-time clock device." msgstr "" #: src/exercises/bare-metal/rtc.md:1 msgid "# RTC driver" msgstr "" #: src/exercises/bare-metal/rtc.md:3 msgid "" "The QEMU aarch64 virt machine has a [PL031][1] real-time clock at 0x9010000. For this exercise, " "you\n" "should write a driver for it." msgstr "" #: src/exercises/bare-metal/rtc.md:6 msgid "" "1. Use it to print the current time to the serial console. You can use the [`chrono`][2] crate " "for\n" " date/time formatting.\n" "2. Use the match register and raw interrupt status to busy-wait until a given time, e.g. 3 " "seconds\n" " in the future. (Call [`core::hint::spin_loop`][3] inside the loop.)\n" "3. _Extension if you have time:_ Enable and handle the interrupt generated by the RTC match. You " "can\n" " use the driver provided in the [`arm-gic`][4] crate to configure the Arm Generic Interrupt " "Controller.\n" " - Use the RTC interrupt, which is wired to the GIC as `IntId::spi(2)`.\n" " - Once the interrupt is enabled, you can put the core to sleep via `arm_gic::wfi()`, which will " "cause the core to sleep until it receives an interrupt.\n" " " msgstr "" #: src/exercises/bare-metal/rtc.md:16 msgid "" "Download the [exercise template](../../comprehensive-rust-exercises.zip) and look in the `rtc`\n" "directory for the following files." msgstr "" #: src/exercises/bare-metal/rtc.md:23 msgid "" "```rust,compile_fail\n" "#![no_main]\n" "#![no_std]\n" "\n" "mod exceptions;\n" "mod logger;\n" "mod pl011;\n" "\n" "use crate::pl011::Uart;\n" "use arm_gic::gicv3::GicV3;\n" "use core::panic::PanicInfo;\n" "use log::{error, info, trace, LevelFilter};\n" "use smccc::psci::system_off;\n" "use smccc::Hvc;\n" "\n" "/// Base addresses of the GICv3.\n" "const GICD_BASE_ADDRESS: *mut u64 = 0x800_0000 as _;\n" "const GICR_BASE_ADDRESS: *mut u64 = 0x80A_0000 as _;\n" "\n" "/// Base address of the primary PL011 UART.\n" "const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;\n" "\n" "#[no_mangle]\n" "extern \"C\" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {\n" " // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,\n" " // and nothing else accesses that address range.\n" " let uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };\n" " logger::init(uart, LevelFilter::Trace).unwrap();\n" "\n" " info!(\"main({:#x}, {:#x}, {:#x}, {:#x})\", x0, x1, x2, x3);\n" "\n" " // Safe because `GICD_BASE_ADDRESS` and `GICR_BASE_ADDRESS` are the base\n" " // addresses of a GICv3 distributor and redistributor respectively, and\n" " // nothing else accesses those address ranges.\n" " let mut gic = unsafe { GicV3::new(GICD_BASE_ADDRESS, GICR_BASE_ADDRESS) };\n" " gic.setup();\n" "\n" " // TODO: Create instance of RTC driver and print current time.\n" "\n" " // TODO: Wait for 3 seconds.\n" "\n" " system_off::().unwrap();\n" "}\n" "\n" "#[panic_handler]\n" "fn panic(info: &PanicInfo) -> ! {\n" " error!(\"{info}\");\n" " system_off::().unwrap();\n" " loop {}\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:75 msgid "`src/exceptions.rs` (you should only need to change this for the 3rd part of the exercise):" msgstr "" #: src/exercises/bare-metal/rtc.md:77 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:79 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "use arm_gic::gicv3::GicV3;\n" "use log::{error, info, trace};\n" "use smccc::psci::system_off;\n" "use smccc::Hvc;\n" "\n" "#[no_mangle]\n" "extern \"C\" fn sync_exception_current(_elr: u64, _spsr: u64) {\n" " error!(\"sync_exception_current\");\n" " system_off::().unwrap();\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn irq_current(_elr: u64, _spsr: u64) {\n" " trace!(\"irq_current\");\n" " let intid = GicV3::get_and_acknowledge_interrupt().expect(\"No pending interrupt\");\n" " info!(\"IRQ {intid:?}\");\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn fiq_current(_elr: u64, _spsr: u64) {\n" " error!(\"fiq_current\");\n" " system_off::().unwrap();\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn serr_current(_elr: u64, _spsr: u64) {\n" " error!(\"serr_current\");\n" " system_off::().unwrap();\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn sync_lower(_elr: u64, _spsr: u64) {\n" " error!(\"sync_lower\");\n" " system_off::().unwrap();\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn irq_lower(_elr: u64, _spsr: u64) {\n" " error!(\"irq_lower\");\n" " system_off::().unwrap();\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn fiq_lower(_elr: u64, _spsr: u64) {\n" " error!(\"fiq_lower\");\n" " system_off::().unwrap();\n" "}\n" "\n" "#[no_mangle]\n" "extern \"C\" fn serr_lower(_elr: u64, _spsr: u64) {\n" " error!(\"serr_lower\");\n" " system_off::().unwrap();\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:149 msgid "`src/logger.rs` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:151 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:153 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: main\n" "use crate::pl011::Uart;\n" "use core::fmt::Write;\n" "use log::{LevelFilter, Log, Metadata, Record, SetLoggerError};\n" "use spin::mutex::SpinMutex;\n" "\n" "static LOGGER: Logger = Logger {\n" " uart: SpinMutex::new(None),\n" "};\n" "\n" "struct Logger {\n" " uart: SpinMutex>,\n" "}\n" "\n" "impl Log for Logger {\n" " fn enabled(&self, _metadata: &Metadata) -> bool {\n" " true\n" " }\n" "\n" " fn log(&self, record: &Record) {\n" " writeln!(\n" " self.uart.lock().as_mut().unwrap(),\n" " \"[{}] {}\",\n" " record.level(),\n" " record.args()\n" " )\n" " .unwrap();\n" " }\n" "\n" " fn flush(&self) {}\n" "}\n" "\n" "/// Initialises UART logger.\n" "pub fn init(uart: Uart, max_level: LevelFilter) -> Result<(), SetLoggerError> {\n" " LOGGER.uart.lock().replace(uart);\n" "\n" " log::set_logger(&LOGGER)?;\n" " log::set_max_level(max_level);\n" " Ok(())\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:210 msgid "`src/pl011.rs` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:212 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:214 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "#![allow(unused)]\n" "\n" "use core::fmt::{self, Write};\n" "use core::ptr::{addr_of, addr_of_mut};\n" "\n" "// ANCHOR: Flags\n" "use bitflags::bitflags;\n" "\n" "bitflags! {\n" " /// Flags from the UART flag register.\n" " #[repr(transparent)]\n" " #[derive(Copy, Clone, Debug, Eq, PartialEq)]\n" " struct Flags: u16 {\n" " /// Clear to send.\n" " const CTS = 1 << 0;\n" " /// Data set ready.\n" " const DSR = 1 << 1;\n" " /// Data carrier detect.\n" " const DCD = 1 << 2;\n" " /// UART busy transmitting data.\n" " const BUSY = 1 << 3;\n" " /// Receive FIFO is empty.\n" " const RXFE = 1 << 4;\n" " /// Transmit FIFO is full.\n" " const TXFF = 1 << 5;\n" " /// Receive FIFO is full.\n" " const RXFF = 1 << 6;\n" " /// Transmit FIFO is empty.\n" " const TXFE = 1 << 7;\n" " /// Ring indicator.\n" " const RI = 1 << 8;\n" " }\n" "}\n" "// ANCHOR_END: Flags\n" "\n" "bitflags! {\n" " /// Flags from the UART Receive Status Register / Error Clear Register.\n" " #[repr(transparent)]\n" " #[derive(Copy, Clone, Debug, Eq, PartialEq)]\n" " struct ReceiveStatus: u16 {\n" " /// Framing error.\n" " const FE = 1 << 0;\n" " /// Parity error.\n" " const PE = 1 << 1;\n" " /// Break error.\n" " const BE = 1 << 2;\n" " /// Overrun error.\n" " const OE = 1 << 3;\n" " }\n" "}\n" "\n" "// ANCHOR: Registers\n" "#[repr(C, align(4))]\n" "struct Registers {\n" " dr: u16,\n" " _reserved0: [u8; 2],\n" " rsr: ReceiveStatus,\n" " _reserved1: [u8; 19],\n" " fr: Flags,\n" " _reserved2: [u8; 6],\n" " ilpr: u8,\n" " _reserved3: [u8; 3],\n" " ibrd: u16,\n" " _reserved4: [u8; 2],\n" " fbrd: u8,\n" " _reserved5: [u8; 3],\n" " lcr_h: u8,\n" " _reserved6: [u8; 3],\n" " cr: u16,\n" " _reserved7: [u8; 3],\n" " ifls: u8,\n" " _reserved8: [u8; 3],\n" " imsc: u16,\n" " _reserved9: [u8; 2],\n" " ris: u16,\n" " _reserved10: [u8; 2],\n" " mis: u16,\n" " _reserved11: [u8; 2],\n" " icr: u16,\n" " _reserved12: [u8; 2],\n" " dmacr: u8,\n" " _reserved13: [u8; 3],\n" "}\n" "// ANCHOR_END: Registers\n" "\n" "// ANCHOR: Uart\n" "/// Driver for a PL011 UART.\n" "#[derive(Debug)]\n" "pub struct Uart {\n" " registers: *mut Registers,\n" "}\n" "\n" "impl Uart {\n" " /// Constructs a new instance of the UART driver for a PL011 device at the\n" " /// given base address.\n" " ///\n" " /// # Safety\n" " ///\n" " /// The given base address must point to the MMIO control registers of a\n" " /// PL011 device, which must be mapped into the address space of the process\n" " /// as device memory and not have any other aliases.\n" " pub unsafe fn new(base_address: *mut u32) -> Self {\n" " Self {\n" " registers: base_address as *mut Registers,\n" " }\n" " }\n" "\n" " /// Writes a single byte to the UART.\n" " pub fn write_byte(&self, byte: u8) {\n" " // Wait until there is room in the TX buffer.\n" " while self.read_flag_register().contains(Flags::TXFF) {}\n" "\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL011 device which is appropriately mapped.\n" " unsafe {\n" " // Write to the TX buffer.\n" " addr_of_mut!((*self.registers).dr).write_volatile(byte.into());\n" " }\n" "\n" " // Wait until the UART is no longer busy.\n" " while self.read_flag_register().contains(Flags::BUSY) {}\n" " }\n" "\n" " /// Reads and returns a pending byte, or `None` if nothing has been received.\n" " pub fn read_byte(&self) -> Option {\n" " if self.read_flag_register().contains(Flags::RXFE) {\n" " None\n" " } else {\n" " let data = unsafe { addr_of!((*self.registers).dr).read_volatile() };\n" " // TODO: Check for error conditions in bits 8-11.\n" " Some(data as u8)\n" " }\n" " }\n" "\n" " fn read_flag_register(&self) -> Flags {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL011 device which is appropriately mapped.\n" " unsafe { addr_of!((*self.registers).fr).read_volatile() }\n" " }\n" "}\n" "// ANCHOR_END: Uart\n" "\n" "impl Write for Uart {\n" " fn write_str(&mut self, s: &str) -> fmt::Result {\n" " for c in s.as_bytes() {\n" " self.write_byte(*c);\n" " }\n" " Ok(())\n" " }\n" "}\n" "\n" "// Safe because it just contains a pointer to device memory, which can be\n" "// accessed from any context.\n" "unsafe impl Send for Uart {}\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:389 msgid "" "```toml\n" "[workspace]\n" "\n" "[package]\n" "name = \"rtc\"\n" "version = \"0.1.0\"\n" "edition = \"2021\"\n" "publish = false\n" "\n" "[dependencies]\n" "arm-gic = \"0.1.0\"\n" "bitflags = \"2.0.0\"\n" "chrono = { version = \"0.4.24\", default-features = false }\n" "log = \"0.4.17\"\n" "smccc = \"0.1.1\"\n" "spin = \"0.9.8\"\n" "\n" "[build-dependencies]\n" "cc = \"1.0.73\"\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:410 msgid "`build.rs` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:412 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:414 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "use cc::Build;\n" "use std::env;\n" "\n" "fn main() {\n" " #[cfg(target_os = \"linux\")]\n" " env::set_var(\"CROSS_COMPILE\", \"aarch64-linux-gnu\");\n" " #[cfg(not(target_os = \"linux\"))]\n" " env::set_var(\"CROSS_COMPILE\", \"aarch64-none-elf\");\n" "\n" " Build::new()\n" " .file(\"entry.S\")\n" " .file(\"exceptions.S\")\n" " .file(\"idmap.S\")\n" " .compile(\"empty\")\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:446 msgid "`entry.S` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:448 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:450 msgid "" "```armasm\n" "/*\n" " * Copyright 2023 Google LLC\n" " *\n" " * Licensed under the Apache License, Version 2.0 (the \"License\");\n" " * you may not use this file except in compliance with the License.\n" " * You may obtain a copy of the License at\n" " *\n" " * https://www.apache.org/licenses/LICENSE-2.0\n" " *\n" " * Unless required by applicable law or agreed to in writing, software\n" " * distributed under the License is distributed on an \"AS IS\" BASIS,\n" " * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" " * See the License for the specific language governing permissions and\n" " * limitations under the License.\n" " */\n" "\n" ".macro adr_l, reg:req, sym:req\n" "\tadrp \\reg, \\sym\n" "\tadd \\reg, \\reg, :lo12:\\sym\n" ".endm\n" "\n" ".macro mov_i, reg:req, imm:req\n" "\tmovz \\reg, :abs_g3:\\imm\n" "\tmovk \\reg, :abs_g2_nc:\\imm\n" "\tmovk \\reg, :abs_g1_nc:\\imm\n" "\tmovk \\reg, :abs_g0_nc:\\imm\n" ".endm\n" "\n" ".set .L_MAIR_DEV_nGnRE,\t0x04\n" ".set .L_MAIR_MEM_WBWA,\t0xff\n" ".set .Lmairval, .L_MAIR_DEV_nGnRE | (.L_MAIR_MEM_WBWA << 8)\n" "\n" "/* 4 KiB granule size for TTBR0_EL1. */\n" ".set .L_TCR_TG0_4KB, 0x0 << 14\n" "/* 4 KiB granule size for TTBR1_EL1. */\n" ".set .L_TCR_TG1_4KB, 0x2 << 30\n" "/* Disable translation table walk for TTBR1_EL1, generating a translation fault instead. */\n" ".set .L_TCR_EPD1, 0x1 << 23\n" "/* Translation table walks for TTBR0_EL1 are inner sharable. */\n" ".set .L_TCR_SH_INNER, 0x3 << 12\n" "/*\n" " * Translation table walks for TTBR0_EL1 are outer write-back read-allocate write-allocate\n" " * cacheable.\n" " */\n" ".set .L_TCR_RGN_OWB, 0x1 << 10\n" "/*\n" " * Translation table walks for TTBR0_EL1 are inner write-back read-allocate write-allocate\n" " * cacheable.\n" " */\n" ".set .L_TCR_RGN_IWB, 0x1 << 8\n" "/* Size offset for TTBR0_EL1 is 2**39 bytes (512 GiB). */\n" ".set .L_TCR_T0SZ_512, 64 - 39\n" ".set .Ltcrval, .L_TCR_TG0_4KB | .L_TCR_TG1_4KB | .L_TCR_EPD1 | .L_TCR_RGN_OWB\n" ".set .Ltcrval, .Ltcrval | .L_TCR_RGN_IWB | .L_TCR_SH_INNER | .L_TCR_T0SZ_512\n" "\n" "/* Stage 1 instruction access cacheability is unaffected. */\n" ".set .L_SCTLR_ELx_I, 0x1 << 12\n" "/* SP alignment fault if SP is not aligned to a 16 byte boundary. */\n" ".set .L_SCTLR_ELx_SA, 0x1 << 3\n" "/* Stage 1 data access cacheability is unaffected. */\n" ".set .L_SCTLR_ELx_C, 0x1 << 2\n" "/* EL0 and EL1 stage 1 MMU enabled. */\n" ".set .L_SCTLR_ELx_M, 0x1 << 0\n" "/* Privileged Access Never is unchanged on taking an exception to EL1. */\n" ".set .L_SCTLR_EL1_SPAN, 0x1 << 23\n" "/* SETEND instruction disabled at EL0 in aarch32 mode. */\n" ".set .L_SCTLR_EL1_SED, 0x1 << 8\n" "/* Various IT instructions are disabled at EL0 in aarch32 mode. */\n" ".set .L_SCTLR_EL1_ITD, 0x1 << 7\n" ".set .L_SCTLR_EL1_RES1, (0x1 << 11) | (0x1 << 20) | (0x1 << 22) | (0x1 << 28) | (0x1 << 29)\n" ".set .Lsctlrval, .L_SCTLR_ELx_M | .L_SCTLR_ELx_C | .L_SCTLR_ELx_SA | .L_SCTLR_EL1_ITD | ." "L_SCTLR_EL1_SED\n" ".set .Lsctlrval, .Lsctlrval | .L_SCTLR_ELx_I | .L_SCTLR_EL1_SPAN | .L_SCTLR_EL1_RES1\n" "\n" "/**\n" " * This is a generic entry point for an image. It carries out the operations required to prepare " "the\n" " * loaded image to be run. Specifically, it zeroes the bss section using registers x25 and above,\n" " * prepares the stack, enables floating point, and sets up the exception vector. It preserves x0-" "x3\n" " * for the Rust entry point, as these may contain boot parameters.\n" " */\n" ".section .init.entry, \"ax\"\n" ".global entry\n" "entry:\n" "\t/* Load and apply the memory management configuration, ready to enable MMU and caches. */\n" "\tadrp x30, idmap\n" "\tmsr ttbr0_el1, x30\n" "\n" "\tmov_i x30, .Lmairval\n" "\tmsr mair_el1, x30\n" "\n" "\tmov_i x30, .Ltcrval\n" "\t/* Copy the supported PA range into TCR_EL1.IPS. */\n" "\tmrs x29, id_aa64mmfr0_el1\n" "\tbfi x30, x29, #32, #4\n" "\n" "\tmsr tcr_el1, x30\n" "\n" "\tmov_i x30, .Lsctlrval\n" "\n" "\t/*\n" "\t * Ensure everything before this point has completed, then invalidate any potentially stale\n" "\t * local TLB entries before they start being used.\n" "\t */\n" "\tisb\n" "\ttlbi vmalle1\n" "\tic iallu\n" "\tdsb nsh\n" "\tisb\n" "\n" "\t/*\n" "\t * Configure sctlr_el1 to enable MMU and cache and don't proceed until this has completed.\n" "\t */\n" "\tmsr sctlr_el1, x30\n" "\tisb\n" "\n" "\t/* Disable trapping floating point access in EL1. */\n" "\tmrs x30, cpacr_el1\n" "\torr x30, x30, #(0x3 << 20)\n" "\tmsr cpacr_el1, x30\n" "\tisb\n" "\n" "\t/* Zero out the bss section. */\n" "\tadr_l x29, bss_begin\n" "\tadr_l x30, bss_end\n" "0:\tcmp x29, x30\n" "\tb.hs 1f\n" "\tstp xzr, xzr, [x29], #16\n" "\tb 0b\n" "\n" "1:\t/* Prepare the stack. */\n" "\tadr_l x30, boot_stack_end\n" "\tmov sp, x30\n" "\n" "\t/* Set up exception vector. */\n" "\tadr x30, vector_table_el1\n" "\tmsr vbar_el1, x30\n" "\n" "\t/* Call into Rust code. */\n" "\tbl main\n" "\n" "\t/* Loop forever waiting for interrupts. */\n" "2:\twfi\n" "\tb 2b\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:595 msgid "`exceptions.S` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:597 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:599 msgid "" "```armasm\n" "/*\n" " * Copyright 2023 Google LLC\n" " *\n" " * Licensed under the Apache License, Version 2.0 (the \"License\");\n" " * you may not use this file except in compliance with the License.\n" " * You may obtain a copy of the License at\n" " *\n" " * https://www.apache.org/licenses/LICENSE-2.0\n" " *\n" " * Unless required by applicable law or agreed to in writing, software\n" " * distributed under the License is distributed on an \"AS IS\" BASIS,\n" " * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" " * See the License for the specific language governing permissions and\n" " * limitations under the License.\n" " */\n" "\n" "/**\n" " * Saves the volatile registers onto the stack. This currently takes 14\n" " * instructions, so it can be used in exception handlers with 18 instructions\n" " * left.\n" " *\n" " * On return, x0 and x1 are initialised to elr_el2 and spsr_el2 respectively,\n" " * which can be used as the first and second arguments of a subsequent call.\n" " */\n" ".macro save_volatile_to_stack\n" "\t/* Reserve stack space and save registers x0-x18, x29 & x30. */\n" "\tstp x0, x1, [sp, #-(8 * 24)]!\n" "\tstp x2, x3, [sp, #8 * 2]\n" "\tstp x4, x5, [sp, #8 * 4]\n" "\tstp x6, x7, [sp, #8 * 6]\n" "\tstp x8, x9, [sp, #8 * 8]\n" "\tstp x10, x11, [sp, #8 * 10]\n" "\tstp x12, x13, [sp, #8 * 12]\n" "\tstp x14, x15, [sp, #8 * 14]\n" "\tstp x16, x17, [sp, #8 * 16]\n" "\tstr x18, [sp, #8 * 18]\n" "\tstp x29, x30, [sp, #8 * 20]\n" "\n" "\t/*\n" "\t * Save elr_el1 & spsr_el1. This such that we can take nested exception\n" "\t * and still be able to unwind.\n" "\t */\n" "\tmrs x0, elr_el1\n" "\tmrs x1, spsr_el1\n" "\tstp x0, x1, [sp, #8 * 22]\n" ".endm\n" "\n" "/**\n" " * Restores the volatile registers from the stack. This currently takes 14\n" " * instructions, so it can be used in exception handlers while still leaving 18\n" " * instructions left; if paired with save_volatile_to_stack, there are 4\n" " * instructions to spare.\n" " */\n" ".macro restore_volatile_from_stack\n" "\t/* Restore registers x2-x18, x29 & x30. */\n" "\tldp x2, x3, [sp, #8 * 2]\n" "\tldp x4, x5, [sp, #8 * 4]\n" "\tldp x6, x7, [sp, #8 * 6]\n" "\tldp x8, x9, [sp, #8 * 8]\n" "\tldp x10, x11, [sp, #8 * 10]\n" "\tldp x12, x13, [sp, #8 * 12]\n" "\tldp x14, x15, [sp, #8 * 14]\n" "\tldp x16, x17, [sp, #8 * 16]\n" "\tldr x18, [sp, #8 * 18]\n" "\tldp x29, x30, [sp, #8 * 20]\n" "\n" "\t/* Restore registers elr_el1 & spsr_el1, using x0 & x1 as scratch. */\n" "\tldp x0, x1, [sp, #8 * 22]\n" "\tmsr elr_el1, x0\n" "\tmsr spsr_el1, x1\n" "\n" "\t/* Restore x0 & x1, and release stack space. */\n" "\tldp x0, x1, [sp], #8 * 24\n" ".endm\n" "\n" "/**\n" " * This is a generic handler for exceptions taken at the current EL while using\n" " * SP0. It behaves similarly to the SPx case by first switching to SPx, doing\n" " * the work, then switching back to SP0 before returning.\n" " *\n" " * Switching to SPx and calling the Rust handler takes 16 instructions. To\n" " * restore and return we need an additional 16 instructions, so we can implement\n" " * the whole handler within the allotted 32 instructions.\n" " */\n" ".macro current_exception_sp0 handler:req\n" "\tmsr spsel, #1\n" "\tsave_volatile_to_stack\n" "\tbl \\handler\n" "\trestore_volatile_from_stack\n" "\tmsr spsel, #0\n" "\teret\n" ".endm\n" "\n" "/**\n" " * This is a generic handler for exceptions taken at the current EL while using\n" " * SPx. It saves volatile registers, calls the Rust handler, restores volatile\n" " * registers, then returns.\n" " *\n" " * This also works for exceptions taken from EL0, if we don't care about\n" " * non-volatile registers.\n" " *\n" " * Saving state and jumping to the Rust handler takes 15 instructions, and\n" " * restoring and returning also takes 15 instructions, so we can fit the whole\n" " * handler in 30 instructions, under the limit of 32.\n" " */\n" ".macro current_exception_spx handler:req\n" "\tsave_volatile_to_stack\n" "\tbl \\handler\n" "\trestore_volatile_from_stack\n" "\teret\n" ".endm\n" "\n" ".section .text.vector_table_el1, \"ax\"\n" ".global vector_table_el1\n" ".balign 0x800\n" "vector_table_el1:\n" "sync_cur_sp0:\n" "\tcurrent_exception_sp0 sync_exception_current\n" "\n" ".balign 0x80\n" "irq_cur_sp0:\n" "\tcurrent_exception_sp0 irq_current\n" "\n" ".balign 0x80\n" "fiq_cur_sp0:\n" "\tcurrent_exception_sp0 fiq_current\n" "\n" ".balign 0x80\n" "serr_cur_sp0:\n" "\tcurrent_exception_sp0 serr_current\n" "\n" ".balign 0x80\n" "sync_cur_spx:\n" "\tcurrent_exception_spx sync_exception_current\n" "\n" ".balign 0x80\n" "irq_cur_spx:\n" "\tcurrent_exception_spx irq_current\n" "\n" ".balign 0x80\n" "fiq_cur_spx:\n" "\tcurrent_exception_spx fiq_current\n" "\n" ".balign 0x80\n" "serr_cur_spx:\n" "\tcurrent_exception_spx serr_current\n" "\n" ".balign 0x80\n" "sync_lower_64:\n" "\tcurrent_exception_spx sync_lower\n" "\n" ".balign 0x80\n" "irq_lower_64:\n" "\tcurrent_exception_spx irq_lower\n" "\n" ".balign 0x80\n" "fiq_lower_64:\n" "\tcurrent_exception_spx fiq_lower\n" "\n" ".balign 0x80\n" "serr_lower_64:\n" "\tcurrent_exception_spx serr_lower\n" "\n" ".balign 0x80\n" "sync_lower_32:\n" "\tcurrent_exception_spx sync_lower\n" "\n" ".balign 0x80\n" "irq_lower_32:\n" "\tcurrent_exception_spx irq_lower\n" "\n" ".balign 0x80\n" "fiq_lower_32:\n" "\tcurrent_exception_spx fiq_lower\n" "\n" ".balign 0x80\n" "serr_lower_32:\n" "\tcurrent_exception_spx serr_lower\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:780 msgid "`idmap.S` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:782 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:784 msgid "" "```armasm\n" "/*\n" " * Copyright 2023 Google LLC\n" " *\n" " * Licensed under the Apache License, Version 2.0 (the \"License\");\n" " * you may not use this file except in compliance with the License.\n" " * You may obtain a copy of the License at\n" " *\n" " * https://www.apache.org/licenses/LICENSE-2.0\n" " *\n" " * Unless required by applicable law or agreed to in writing, software\n" " * distributed under the License is distributed on an \"AS IS\" BASIS,\n" " * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" " * See the License for the specific language governing permissions and\n" " * limitations under the License.\n" " */\n" "\n" ".set .L_TT_TYPE_BLOCK, 0x1\n" ".set .L_TT_TYPE_PAGE, 0x3\n" ".set .L_TT_TYPE_TABLE, 0x3\n" "\n" "/* Access flag. */\n" ".set .L_TT_AF, 0x1 << 10\n" "/* Not global. */\n" ".set .L_TT_NG, 0x1 << 11\n" ".set .L_TT_XN, 0x3 << 53\n" "\n" ".set .L_TT_MT_DEV, 0x0 << 2\t\t\t// MAIR #0 (DEV_nGnRE)\n" ".set .L_TT_MT_MEM, (0x1 << 2) | (0x3 << 8)\t// MAIR #1 (MEM_WBWA), inner shareable\n" "\n" ".set .L_BLOCK_DEV, .L_TT_TYPE_BLOCK | .L_TT_MT_DEV | .L_TT_AF | .L_TT_XN\n" ".set .L_BLOCK_MEM, .L_TT_TYPE_BLOCK | .L_TT_MT_MEM | .L_TT_AF | .L_TT_NG\n" "\n" ".section \".rodata.idmap\", \"a\", %progbits\n" ".global idmap\n" ".align 12\n" "idmap:\n" "\t/* level 1 */\n" "\t.quad\t\t.L_BLOCK_DEV | 0x0\t\t // 1 GiB of device mappings\n" "\t.quad\t\t.L_BLOCK_MEM | 0x40000000\t// 1 GiB of DRAM\n" "\t.fill\t\t254, 8, 0x0\t\t\t// 254 GiB of unmapped VA space\n" "\t.quad\t\t.L_BLOCK_DEV | 0x4000000000 // 1 GiB of device mappings\n" "\t.fill\t\t255, 8, 0x0\t\t\t// 255 GiB of remaining VA space\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:829 msgid "`image.ld` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:831 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:833 msgid "" "```ld\n" "/*\n" " * Copyright 2023 Google LLC\n" " *\n" " * Licensed under the Apache License, Version 2.0 (the \"License\");\n" " * you may not use this file except in compliance with the License.\n" " * You may obtain a copy of the License at\n" " *\n" " * https://www.apache.org/licenses/LICENSE-2.0\n" " *\n" " * Unless required by applicable law or agreed to in writing, software\n" " * distributed under the License is distributed on an \"AS IS\" BASIS,\n" " * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" " * See the License for the specific language governing permissions and\n" " * limitations under the License.\n" " */\n" "\n" "/*\n" " * Code will start running at this symbol which is placed at the start of the\n" " * image.\n" " */\n" "ENTRY(entry)\n" "\n" "MEMORY\n" "{\n" "\timage : ORIGIN = 0x40080000, LENGTH = 2M\n" "}\n" "\n" "SECTIONS\n" "{\n" "\t/*\n" "\t * Collect together the code.\n" "\t */\n" "\t.init : ALIGN(4096) {\n" "\t\ttext_begin = .;\n" "\t\t*(.init.entry)\n" "\t\t*(.init.*)\n" "\t} >image\n" "\t.text : {\n" "\t\t*(.text.*)\n" "\t} >image\n" "\ttext_end = .;\n" "\n" "\t/*\n" "\t * Collect together read-only data.\n" "\t */\n" "\t.rodata : ALIGN(4096) {\n" "\t\trodata_begin = .;\n" "\t\t*(.rodata.*)\n" "\t} >image\n" "\t.got : {\n" "\t\t*(.got)\n" "\t} >image\n" "\trodata_end = .;\n" "\n" "\t/*\n" "\t * Collect together the read-write data including .bss at the end which\n" "\t * will be zero'd by the entry code.\n" "\t */\n" "\t.data : ALIGN(4096) {\n" "\t\tdata_begin = .;\n" "\t\t*(.data.*)\n" "\t\t/*\n" "\t\t * The entry point code assumes that .data is a multiple of 32\n" "\t\t * bytes long.\n" "\t\t */\n" "\t\t. = ALIGN(32);\n" "\t\tdata_end = .;\n" "\t} >image\n" "\n" "\t/* Everything beyond this point will not be included in the binary. */\n" "\tbin_end = .;\n" "\n" "\t/* The entry point code assumes that .bss is 16-byte aligned. */\n" "\t.bss : ALIGN(16) {\n" "\t\tbss_begin = .;\n" "\t\t*(.bss.*)\n" "\t\t*(COMMON)\n" "\t\t. = ALIGN(16);\n" "\t\tbss_end = .;\n" "\t} >image\n" "\n" "\t.stack (NOLOAD) : ALIGN(4096) {\n" "\t\tboot_stack_begin = .;\n" "\t\t. += 40 * 4096;\n" "\t\t. = ALIGN(4096);\n" "\t\tboot_stack_end = .;\n" "\t} >image\n" "\n" "\t. = ALIGN(4K);\n" "\tPROVIDE(dma_region = .);\n" "\n" "\t/*\n" "\t * Remove unused sections from the image.\n" "\t */\n" "\t/DISCARD/ : {\n" "\t\t/* The image loads itself so doesn't need these sections. */\n" "\t\t*(.gnu.hash)\n" "\t\t*(.hash)\n" "\t\t*(.interp)\n" "\t\t*(.eh_frame_hdr)\n" "\t\t*(.eh_frame)\n" "\t\t*(.note.gnu.build-id)\n" "\t}\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:940 msgid "`Makefile` (you shouldn't need to change this):" msgstr "" #: src/exercises/bare-metal/rtc.md:942 msgid "" msgstr "" #: src/exercises/bare-metal/rtc.md:944 msgid "" "```makefile\n" "# Copyright 2023 Google LLC\n" "#\n" "# Licensed under the Apache License, Version 2.0 (the \"License\");\n" "# you may not use this file except in compliance with the License.\n" "# You may obtain a copy of the License at\n" "#\n" "# http://www.apache.org/licenses/LICENSE-2.0\n" "#\n" "# Unless required by applicable law or agreed to in writing, software\n" "# distributed under the License is distributed on an \"AS IS\" BASIS,\n" "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "# See the License for the specific language governing permissions and\n" "# limitations under the License.\n" "\n" "UNAME := $(shell uname -s)\n" "ifeq ($(UNAME),Linux)\n" "\tTARGET = aarch64-linux-gnu\n" "else\n" "\tTARGET = aarch64-none-elf\n" "endif\n" "OBJCOPY = $(TARGET)-objcopy\n" "\n" ".PHONY: build qemu_minimal qemu qemu_logger\n" "\n" "all: rtc.bin\n" "\n" "build:\n" "\tcargo build\n" "\n" "rtc.bin: build\n" "\t$(OBJCOPY) -O binary target/aarch64-unknown-none/debug/rtc $@\n" "\n" "qemu: rtc.bin\n" "\tqemu-system-aarch64 -machine virt,gic-version=3 -cpu max -serial mon:stdio -display none -kernel " "$< -s\n" "\n" "clean:\n" "\tcargo clean\n" "\trm -f *.bin\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:989 msgid "" "```toml\n" "[build]\n" "target = \"aarch64-unknown-none\"\n" "rustflags = [\"-C\", \"link-arg=-Timage.ld\"]\n" "```" msgstr "" #: src/exercises/bare-metal/rtc.md:995 msgid "Run the code in QEMU with `make qemu`." msgstr "" #: src/concurrency.md:1 msgid "# Welcome to Concurrency in Rust" msgstr "" #: src/concurrency.md:3 msgid "" "Rust has full support for concurrency using OS threads with mutexes and\n" "channels." msgstr "" #: src/concurrency.md:6 msgid "" "The Rust type system plays an important role in making many concurrency bugs\n" "compile time bugs. This is often referred to as _fearless concurrency_ since you\n" "can rely on the compiler to ensure correctness at runtime." msgstr "" #: src/concurrency/threads.md:1 msgid "# Threads" msgstr "" #: src/concurrency/threads.md:3 msgid "Rust threads work similarly to threads in other languages:" msgstr "" #: src/concurrency/threads.md:5 msgid "" "```rust,editable\n" "use std::thread;\n" "use std::time::Duration;\n" "\n" "fn main() {\n" " thread::spawn(|| {\n" " for i in 1..10 {\n" " println!(\"Count in thread: {i}!\");\n" " thread::sleep(Duration::from_millis(5));\n" " }\n" " });\n" "\n" " for i in 1..5 {\n" " println!(\"Main thread: {i}\");\n" " thread::sleep(Duration::from_millis(5));\n" " }\n" "}\n" "```" msgstr "" #: src/concurrency/threads.md:24 msgid "" "* Threads are all daemon threads, the main thread does not wait for them.\n" "* Thread panics are independent of each other.\n" " * Panics can carry a payload, which can be unpacked with `downcast_ref`." msgstr "" #: src/concurrency/threads.md:32 msgid "" "* Notice that the thread is stopped before it reaches 10 — the main thread is\n" " not waiting.\n" "\n" "* Use `let handle = thread::spawn(...)` and later `handle.join()` to wait for\n" " the thread to finish.\n" "\n" "* Trigger a panic in the thread, notice how this doesn't affect `main`.\n" "\n" "* Use the `Result` return value from `handle.join()` to get access to the panic\n" " payload. This is a good time to talk about [`Any`]." msgstr "" #: src/concurrency/scoped-threads.md:1 msgid "# Scoped Threads" msgstr "" #: src/concurrency/scoped-threads.md:3 msgid "Normal threads cannot borrow from their environment:" msgstr "" #: src/concurrency/scoped-threads.md:5 msgid "" "```rust,editable,compile_fail\n" "use std::thread;\n" "\n" "fn main() {\n" " let s = String::from(\"Hello\");\n" "\n" " thread::spawn(|| {\n" " println!(\"Length: {}\", s.len());\n" " });\n" "}\n" "```" msgstr "" #: src/concurrency/scoped-threads.md:17 msgid "However, you can use a [scoped thread][1] for this:" msgstr "" #: src/concurrency/scoped-threads.md:19 msgid "" "```rust,editable\n" "use std::thread;\n" "\n" "fn main() {\n" " let s = String::from(\"Hello\");\n" "\n" " thread::scope(|scope| {\n" " scope.spawn(|| {\n" " println!(\"Length: {}\", s.len());\n" " });\n" " });\n" "}\n" "```" msgstr "" #: src/concurrency/scoped-threads.md:37 msgid "" "* The reason for that is that when the `thread::scope` function completes, all the threads are " "guaranteed to be joined, so they can return borrowed data.\n" "* Normal Rust borrowing rules apply: you can either borrow mutably by one thread, or immutably by " "any number of threads.\n" " " msgstr "" #: src/concurrency/channels.md:1 msgid "# Channels" msgstr "" #: src/concurrency/channels.md:3 msgid "" "Rust channels have two parts: a `Sender` and a `Receiver`. The two parts\n" "are connected via the channel, but you only see the end-points." msgstr "" #: src/concurrency/channels.md:6 msgid "" "```rust,editable\n" "use std::sync::mpsc;\n" "use std::thread;\n" "\n" "fn main() {\n" " let (tx, rx) = mpsc::channel();\n" "\n" " tx.send(10).unwrap();\n" " tx.send(20).unwrap();\n" "\n" " println!(\"Received: {:?}\", rx.recv());\n" " println!(\"Received: {:?}\", rx.recv());\n" "\n" " let tx2 = tx.clone();\n" " tx2.send(30).unwrap();\n" " println!(\"Received: {:?}\", rx.recv());\n" "}\n" "```" msgstr "" #: src/concurrency/channels.md:27 msgid "" "* `mpsc` stands for Multi-Producer, Single-Consumer. `Sender` and `SyncSender` implement `Clone` " "(so\n" " you can make multiple producers) but `Receiver` does not.\n" "* `send()` and `recv()` return `Result`. If they return `Err`, it means the counterpart `Sender` " "or\n" " `Receiver` is dropped and the channel is closed." msgstr "" #: src/concurrency/channels/unbounded.md:1 msgid "# Unbounded Channels" msgstr "" #: src/concurrency/channels/unbounded.md:3 msgid "You get an unbounded and asynchronous channel with `mpsc::channel()`:" msgstr "" #: src/concurrency/channels/unbounded.md:5 msgid "" "```rust,editable\n" "use std::sync::mpsc;\n" "use std::thread;\n" "use std::time::Duration;\n" "\n" "fn main() {\n" " let (tx, rx) = mpsc::channel();\n" "\n" " thread::spawn(move || {\n" " let thread_id = thread::current().id();\n" " for i in 1..10 {\n" " tx.send(format!(\"Message {i}\")).unwrap();\n" " println!(\"{thread_id:?}: sent Message {i}\");\n" " }\n" " println!(\"{thread_id:?}: done\");\n" " });\n" " thread::sleep(Duration::from_millis(100));\n" "\n" " for msg in rx.iter() {\n" " println!(\"Main: got {}\", msg);\n" " }\n" "}\n" "```" msgstr "" #: src/concurrency/channels/bounded.md:1 msgid "# Bounded Channels" msgstr "" #: src/concurrency/channels/bounded.md:3 msgid "Bounded and synchronous channels make `send` block the current thread:" msgstr "" #: src/concurrency/channels/bounded.md:5 msgid "" "```rust,editable\n" "use std::sync::mpsc;\n" "use std::thread;\n" "use std::time::Duration;\n" "\n" "fn main() {\n" " let (tx, rx) = mpsc::sync_channel(3);\n" "\n" " thread::spawn(move || {\n" " let thread_id = thread::current().id();\n" " for i in 1..10 {\n" " tx.send(format!(\"Message {i}\")).unwrap();\n" " println!(\"{thread_id:?}: sent Message {i}\");\n" " }\n" " println!(\"{thread_id:?}: done\");\n" " });\n" " thread::sleep(Duration::from_millis(100));\n" "\n" " for msg in rx.iter() {\n" " println!(\"Main: got {msg}\");\n" " }\n" "}\n" "```" msgstr "" #: src/concurrency/send-sync.md:1 msgid "# `Send` and `Sync`" msgstr "" #: src/concurrency/send-sync.md:3 msgid "How does Rust know to forbid shared access across thread? The answer is in two traits:" msgstr "" #: src/concurrency/send-sync.md:5 msgid "" "* [`Send`][1]: a type `T` is `Send` if it is safe to move a `T` across a thread\n" " boundary.\n" "* [`Sync`][2]: a type `T` is `Sync` if it is safe to move a `&T` across a thread\n" " boundary." msgstr "" #: src/concurrency/send-sync.md:10 msgid "" "`Send` and `Sync` are [unsafe traits][3]. The compiler will automatically derive them for your " "types\n" "as long as they only contain `Send` and `Sync` types. You can also implement them manually when " "you\n" "know it is valid." msgstr "" #: src/concurrency/send-sync.md:20 msgid "" "* One can think of these traits as markers that the type has certain thread-safety properties.\n" "* They can be used in the generic constraints as normal traits.\n" " " msgstr "" #: src/concurrency/send-sync/send.md:1 msgid "# `Send`" msgstr "" #: src/concurrency/send-sync/send.md:3 msgid "> A type `T` is [`Send`][1] if it is safe to move a `T` value to another thread." msgstr "" #: src/concurrency/send-sync/send.md:5 msgid "" "The effect of moving ownership to another thread is that _destructors_ will run\n" "in that thread. So the question is when you can allocate a value in one thread\n" "and deallocate it in another." msgstr "" #: src/concurrency/send-sync/send.md:13 msgid "" "As an example, a connection to the SQLite library must only be accessed from a\n" "single thread." msgstr "" #: src/concurrency/send-sync/sync.md:1 msgid "# `Sync`" msgstr "" #: src/concurrency/send-sync/sync.md:3 msgid "" "> A type `T` is [`Sync`][1] if it is safe to access a `T` value from multiple\n" "> threads at the same time." msgstr "" #: src/concurrency/send-sync/sync.md:6 msgid "More precisely, the definition is:" msgstr "" #: src/concurrency/send-sync/sync.md:8 msgid "> `T` is `Sync` if and only if `&T` is `Send`" msgstr "" #: src/concurrency/send-sync/sync.md:14 msgid "" "This statement is essentially a shorthand way of saying that if a type is thread-safe for shared " "use, it is also thread-safe to pass references of it across threads." msgstr "" #: src/concurrency/send-sync/sync.md:16 msgid "" "This is because if a type is Sync it means that it can be shared across multiple threads without " "the risk of data races or other synchronization issues, so it is safe to move it to another " "thread. A reference to the type is also safe to move to another thread, because the data it " "references can be accessed from any thread safely." msgstr "" #: src/concurrency/send-sync/examples.md:1 msgid "# Examples" msgstr "" #: src/concurrency/send-sync/examples.md:3 msgid "## `Send + Sync`" msgstr "" #: src/concurrency/send-sync/examples.md:5 msgid "Most types you come across are `Send + Sync`:" msgstr "" #: src/concurrency/send-sync/examples.md:7 msgid "" "* `i8`, `f32`, `bool`, `char`, `&str`, ...\n" "* `(T1, T2)`, `[T; N]`, `&[T]`, `struct { x: T }`, ...\n" "* `String`, `Option`, `Vec`, `Box`, ...\n" "* `Arc`: Explicitly thread-safe via atomic reference count.\n" "* `Mutex`: Explicitly thread-safe via internal locking.\n" "* `AtomicBool`, `AtomicU8`, ...: Uses special atomic instructions." msgstr "" #: src/concurrency/send-sync/examples.md:14 msgid "" "The generic types are typically `Send + Sync` when the type parameters are\n" "`Send + Sync`." msgstr "" #: src/concurrency/send-sync/examples.md:17 msgid "## `Send + !Sync`" msgstr "" #: src/concurrency/send-sync/examples.md:19 msgid "" "These types can be moved to other threads, but they're not thread-safe.\n" "Typically because of interior mutability:" msgstr "" #: src/concurrency/send-sync/examples.md:22 msgid "" "* `mpsc::Sender`\n" "* `mpsc::Receiver`\n" "* `Cell`\n" "* `RefCell`" msgstr "" #: src/concurrency/send-sync/examples.md:27 msgid "## `!Send + Sync`" msgstr "" #: src/concurrency/send-sync/examples.md:29 msgid "These types are thread-safe, but they cannot be moved to another thread:" msgstr "" #: src/concurrency/send-sync/examples.md:31 msgid "" "* `MutexGuard`: Uses OS level primitives which must be deallocated on the\n" " thread which created them." msgstr "" #: src/concurrency/send-sync/examples.md:34 msgid "## `!Send + !Sync`" msgstr "" #: src/concurrency/send-sync/examples.md:36 msgid "These types are not thread-safe and cannot be moved to other threads:" msgstr "" #: src/concurrency/send-sync/examples.md:38 msgid "" "* `Rc`: each `Rc` has a reference to an `RcBox`, which contains a\n" " non-atomic reference count.\n" "* `*const T`, `*mut T`: Rust assumes raw pointers may have special\n" " concurrency considerations." msgstr "" #: src/concurrency/shared_state.md:1 msgid "# Shared State" msgstr "" #: src/concurrency/shared_state.md:3 msgid "" "Rust uses the type system to enforce synchronization of shared data. This is\n" "primarily done via two types:" msgstr "" #: src/concurrency/shared_state.md:6 msgid "" "* [`Arc`][1], atomic reference counted `T`: handles sharing between threads and\n" " takes care to deallocate `T` when the last reference is dropped,\n" "* [`Mutex`][2]: ensures mutually exclusive access to the `T` value." msgstr "" #: src/concurrency/shared_state/arc.md:1 msgid "# `Arc`" msgstr "" #: src/concurrency/shared_state/arc.md:3 msgid "[`Arc`][1] allows shared read-only access via `Arc::clone`:" msgstr "" #: src/concurrency/shared_state/arc.md:5 msgid "" "```rust,editable\n" "use std::thread;\n" "use std::sync::Arc;\n" "\n" "fn main() {\n" " let v = Arc::new(vec![10, 20, 30]);\n" " let mut handles = Vec::new();\n" " for _ in 1..5 {\n" " let v = Arc::clone(&v);\n" " handles.push(thread::spawn(move || {\n" " let thread_id = thread::current().id();\n" " println!(\"{thread_id:?}: {v:?}\");\n" " }));\n" " }\n" "\n" " handles.into_iter().for_each(|h| h.join().unwrap());\n" " println!(\"v: {v:?}\");\n" "}\n" "```" msgstr "" #: src/concurrency/shared_state/arc.md:29 msgid "" "* `Arc` stands for \"Atomic Reference Counted\", a thread safe version of `Rc` that uses atomic\n" " operations.\n" "* `Arc` implements `Clone` whether or not `T` does. It implements `Send` and `Sync` iff `T`\n" " implements them both.\n" "* `Arc::clone()` has the cost of atomic operations that get executed, but after that the use of " "the\n" " `T` is free.\n" "* Beware of reference cycles, `Arc` does not use a garbage collector to detect them.\n" " * `std::sync::Weak` can help." msgstr "" #: src/concurrency/shared_state/mutex.md:1 msgid "# `Mutex`" msgstr "" #: src/concurrency/shared_state/mutex.md:3 msgid "" "[`Mutex`][1] ensures mutual exclusion _and_ allows mutable access to `T`\n" "behind a read-only interface:" msgstr "" #: src/concurrency/shared_state/mutex.md:6 msgid "" "```rust,editable\n" "use std::sync::Mutex;\n" "\n" "fn main() {\n" " let v = Mutex::new(vec![10, 20, 30]);\n" " println!(\"v: {:?}\", v.lock().unwrap());\n" "\n" " {\n" " let mut guard = v.lock().unwrap();\n" " guard.push(40);\n" " }\n" "\n" " println!(\"v: {:?}\", v.lock().unwrap());\n" "}\n" "```" msgstr "" #: src/concurrency/shared_state/mutex.md:22 msgid "" "Notice how we have a [`impl Sync for Mutex`][2] blanket\n" "implementation." msgstr "" #: src/concurrency/shared_state/mutex.md:31 msgid "" "* `Mutex` in Rust looks like a collection with just one element - the protected data.\n" " * It is not possible to forget to acquire the mutex before accessing the protected data.\n" "* You can get an `&mut T` from an `&Mutex` by taking the lock. The `MutexGuard` ensures that " "the\n" " `&mut T` doesn't outlive the lock being held.\n" "* `Mutex` implements both `Send` and `Sync` iff `T` implements `Send`.\n" "* A read-write lock counterpart - `RwLock`.\n" "* Why does `lock()` return a `Result`? \n" " * If the thread that held the `Mutex` panicked, the `Mutex` becomes \"poisoned\" to signal " "that\n" " the data it protected might be in an inconsistent state. Calling `lock()` on a poisoned " "mutex\n" " fails with a [`PoisonError`]. You can call `into_inner()` on the error to recover the data\n" " regardless." msgstr "" #: src/concurrency/shared_state/example.md:3 msgid "Let us see `Arc` and `Mutex` in action:" msgstr "" #: src/concurrency/shared_state/example.md:5 msgid "" "```rust,editable,compile_fail\n" "use std::thread;\n" "// use std::sync::{Arc, Mutex};\n" "\n" "fn main() {\n" " let v = vec![10, 20, 30];\n" " let handle = thread::spawn(|| {\n" " v.push(10);\n" " });\n" " v.push(1000);\n" "\n" " handle.join().unwrap();\n" " println!(\"v: {v:?}\");\n" "}\n" "```" msgstr "" #: src/concurrency/shared_state/example.md:23 msgid "Possible solution:" msgstr "" #: src/concurrency/shared_state/example.md:25 msgid "" "```rust,editable\n" "use std::sync::{Arc, Mutex};\n" "use std::thread;\n" "\n" "fn main() {\n" " let v = Arc::new(Mutex::new(vec![10, 20, 30]));\n" "\n" " let v2 = Arc::clone(&v);\n" " let handle = thread::spawn(move || {\n" " let mut v2 = v2.lock().unwrap();\n" " v2.push(10);\n" " });\n" "\n" " {\n" " let mut v = v.lock().unwrap();\n" " v.push(1000);\n" " }\n" "\n" " handle.join().unwrap();\n" "\n" " println!(\"v: {v:?}\");\n" "}\n" "```" msgstr "" #: src/concurrency/shared_state/example.md:49 msgid "Notable parts:" msgstr "" #: src/concurrency/shared_state/example.md:51 msgid "" "* `v` is wrapped in both `Arc` and `Mutex`, because their concerns are orthogonal.\n" " * Wrapping a `Mutex` in an `Arc` is a common pattern to share mutable state between threads.\n" "* `v: Arc<_>` needs to be cloned as `v2` before it can be moved into another thread. Note `move` " "was added to the lambda signature.\n" "* Blocks are introduced to narrow the scope of the `LockGuard` as much as possible." msgstr "" #: src/exercises/concurrency/morning.md:3 msgid "Let us practice our new concurrency skills with" msgstr "" #: src/exercises/concurrency/morning.md:5 msgid "" "* Dining philosophers: a classic problem in concurrency.\n" "\n" "* Multi-threaded link checker: a larger project where you'll use Cargo to\n" " download dependencies and then check links in parallel." msgstr "" #: src/exercises/concurrency/dining-philosophers.md:1 msgid "# Dining Philosophers" msgstr "" #: src/exercises/concurrency/dining-philosophers.md:3 msgid "The dining philosophers problem is a classic problem in concurrency:" msgstr "" #: src/exercises/concurrency/dining-philosophers.md:5 msgid "" "> Five philosophers dine together at the same table. Each philosopher has their\n" "> own place at the table. There is a fork between each plate. The dish served is\n" "> a kind of spaghetti which has to be eaten with two forks. Each philosopher can\n" "> only alternately think and eat. Moreover, a philosopher can only eat their\n" "> spaghetti when they have both a left and right fork. Thus two forks will only\n" "> be available when their two nearest neighbors are thinking, not eating. After\n" "> an individual philosopher finishes eating, they will put down both forks." msgstr "" #: src/exercises/concurrency/dining-philosophers.md:13 msgid "" "You will need a local [Cargo installation](../../cargo/running-locally.md) for\n" "this exercise. Copy the code below to a file called `src/main.rs`, fill out the\n" "blanks, and test that `cargo run` does not deadlock:" msgstr "" #: src/exercises/concurrency/dining-philosophers.md:19 msgid "" "```rust,compile_fail\n" "use std::sync::{mpsc, Arc, Mutex};\n" "use std::thread;\n" "use std::time::Duration;\n" "\n" "struct Fork;\n" "\n" "struct Philosopher {\n" " name: String,\n" " // left_fork: ...\n" " // right_fork: ...\n" " // thoughts: ...\n" "}\n" "\n" "impl Philosopher {\n" " fn think(&self) {\n" " self.thoughts\n" " .send(format!(\"Eureka! {} has a new idea!\", &self.name))\n" " .unwrap();\n" " }\n" "\n" " fn eat(&self) {\n" " // Pick up forks...\n" " println!(\"{} is eating...\", &self.name);\n" " thread::sleep(Duration::from_millis(10));\n" " }\n" "}\n" "\n" "static PHILOSOPHERS: &[&str] =\n" " &[\"Socrates\", \"Plato\", \"Aristotle\", \"Thales\", \"Pythagoras\"];\n" "\n" "fn main() {\n" " // Create forks\n" "\n" " // Create philosophers\n" "\n" " // Make them think and eat\n" "\n" " // Output their thoughts\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/dining-philosophers.md:61 msgid "You can use the following `Cargo.toml`:" msgstr "" #: src/exercises/concurrency/dining-philosophers.md:65 msgid "" "```toml\n" "[package]\n" "name = \"dining-philosophers\"\n" "version = \"0.1.0\"\n" "edition = \"2021\"\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:1 msgid "# Multi-threaded Link Checker" msgstr "" #: src/exercises/concurrency/link-checker.md:3 msgid "" "Let us use our new knowledge to create a multi-threaded link checker. It should\n" "start at a webpage and check that links on the page are valid. It should\n" "recursively check other pages on the same domain and keep doing this until all\n" "pages have been validated." msgstr "" #: src/exercises/concurrency/link-checker.md:8 msgid "" "For this, you will need an HTTP client such as [`reqwest`][1]. Create a new\n" "Cargo project and `reqwest` it as a dependency with:" msgstr "" #: src/exercises/concurrency/link-checker.md:11 msgid "" "```shell\n" "$ cargo new link-checker\n" "$ cd link-checker\n" "$ cargo add --features blocking,rustls-tls reqwest\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:17 msgid "" "> If `cargo add` fails with `error: no such subcommand`, then please edit the\n" "> `Cargo.toml` file by hand. Add the dependencies listed below." msgstr "" #: src/exercises/concurrency/link-checker.md:20 msgid "You will also need a way to find links. We can use [`scraper`][2] for that:" msgstr "" #: src/exercises/concurrency/link-checker.md:22 msgid "" "```shell\n" "$ cargo add scraper\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:26 msgid "" "Finally, we'll need some way of handling errors. We use [`thiserror`][3] for\n" "that:" msgstr "" #: src/exercises/concurrency/link-checker.md:29 msgid "" "```shell\n" "$ cargo add thiserror\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:33 msgid "The `cargo add` calls will update the `Cargo.toml` file to look like this:" msgstr "" #: src/exercises/concurrency/link-checker.md:37 msgid "" "```toml\n" "[package]\n" "name = \"link-checker\"\n" "version = \"0.1.0\"\n" "edition = \"2021\"\n" "publish = false\n" "\n" "[dependencies]\n" "reqwest = { version = \"0.11.12\", features = [\"blocking\", \"rustls-tls\"] }\n" "scraper = \"0.13.0\"\n" "thiserror = \"1.0.37\"\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:50 msgid "" "You can now download the start page. Try with a small site such as\n" "`https://www.google.org/`." msgstr "" #: src/exercises/concurrency/link-checker.md:53 msgid "Your `src/main.rs` file should look something like this:" msgstr "" #: src/exercises/concurrency/link-checker.md:57 msgid "" "```rust,compile_fail\n" "use reqwest::blocking::{get, Response};\n" "use reqwest::Url;\n" "use scraper::{Html, Selector};\n" "use thiserror::Error;\n" "\n" "#[derive(Error, Debug)]\n" "enum Error {\n" " #[error(\"request error: {0}\")]\n" " ReqwestError(#[from] reqwest::Error),\n" "}\n" "\n" "fn extract_links(response: Response) -> Result, Error> {\n" " let base_url = response.url().to_owned();\n" " let document = response.text()?;\n" " let html = Html::parse_document(&document);\n" " let selector = Selector::parse(\"a\").unwrap();\n" "\n" " let mut valid_urls = Vec::new();\n" " for element in html.select(&selector) {\n" " if let Some(href) = element.value().attr(\"href\") {\n" " match base_url.join(href) {\n" " Ok(url) => valid_urls.push(url),\n" " Err(err) => {\n" " println!(\"On {base_url}: could not parse {href:?}: {err} (ignored)\",);\n" " }\n" " }\n" " }\n" " }\n" "\n" " Ok(valid_urls)\n" "}\n" "\n" "fn main() {\n" " let start_url = Url::parse(\"https://www.google.org\").unwrap();\n" " let response = get(start_url).unwrap();\n" " match extract_links(response) {\n" " Ok(links) => println!(\"Links: {links:#?}\"),\n" " Err(err) => println!(\"Could not extract links: {err:#}\"),\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:100 msgid "Run the code in `src/main.rs` with" msgstr "" #: src/exercises/concurrency/link-checker.md:102 msgid "" "```shell\n" "$ cargo run\n" "```" msgstr "" #: src/exercises/concurrency/link-checker.md:106 src/exercises/concurrency/chat-app.md:140 msgid "## Tasks" msgstr "" #: src/exercises/concurrency/link-checker.md:108 msgid "" "* Use threads to check the links in parallel: send the URLs to be checked to a\n" " channel and let a few threads check the URLs in parallel.\n" "* Extend this to recursively extract links from all pages on the\n" " `www.google.org` domain. Put an upper limit of 100 pages or so so that you\n" " don't end up being blocked by the site." msgstr "" #: src/async.md:1 msgid "# Async Rust" msgstr "# Asyncの基瀎" #: src/async.md:3 msgid "" "\"Async\" is a concurrency model where multiple tasks are executed concurrently by\n" "executing each task until it would block, then switching to another task that is\n" "ready to make progress. The model allows running a larger number of tasks on a\n" "limited number of threads. This is because the per-task overhead is typically\n" "very low and operating systems provide primitives for efficiently identifying\n" "I/O that is able to proceed." msgstr "" "「Async」は耇数のタスクが䞊行凊理される䞊行性モデルです。それぞれのタスクはブロックされるたで実行さ" "れ、そしお次に進むこずのできる他のタスクに切り替えるこずにより実珟されたす。このモデルは限られた数" "のスレッド䞊でより倚くのタスクを実行するこずを可胜にしたす。なぜなら、タスクごずのオヌバヌヘッドは" "通垞はずおも䜎く、効率的に実行可胜なI/Oを特定するために必芁なプリミティブをOSが提䟛しおくれるからで" "す。" #: src/async.md:10 msgid "" "Rust's asynchronous operation is based on \"futures\", which represent work that\n" "may be completed in the future. Futures are \"polled\" until they signal that\n" "they are complete." msgstr "" "Rustの非同期的な操䜜は「future」に基づいおいお、これは将来に完了するかもしれない䜜業を衚しおいた" "す。Futureは、タスクが完了したこずを知らせるシグナルが埗られるたでポヌリングされたす。" #: src/async.md:14 msgid "" "Futures are polled by an async runtime, and several different runtimes are\n" "available." msgstr "" "Futureは非同期的なランタむムによりポヌリングされたす。ランタむムにはいく぀かの遞択肢がありたす。" #: src/async.md:17 msgid "## Comparisons" msgstr "## 他の蚀語ずの比范" #: src/async.md:19 msgid "" " * Python has a similar model in its `asyncio`. However, its `Future` type is\n" " callback-based, and not polled. Async Python programs require a \"loop\",\n" " similar to a runtime in Rust.\n" "\n" " * JavaScript's `Promise` is similar, but again callback-based. The language\n" " runtime implements the event loop, so many of the details of Promise\n" " resolution are hidden." msgstr "" " * Pythonには䌌たようなモデルが`asyncio`ずしお搭茉されおいたす。しかし、ここでの`Future`型はコヌル" "バックに基づくものであっお、ポヌリングによるものではありたせん。Pythonの非同期プログラムは「ルヌ" "プ」を必芁ずし、Rustのランタむムに䌌おいたす。\n" "\n" " * JavaScriptの`Promise`は䌌おいるものの、これもたたもやコヌルバックに基づきたす。\n" " この蚀語のランタむムはむベントルヌプにより実装されおいるため、倚くのPromise解決の詳现は隠されお" "いたす。" #: src/async/async-await.md:1 msgid "# `async`/`await`" msgstr "# `async`/`await`" #: src/async/async-await.md:3 msgid "At a high level, async Rust code looks very much like \"normal\" sequential code:" msgstr "おおたかには、Rustの非同期コヌドはほずんど「通垞の」逐次的なコヌドのように芋えたす:" #: src/async/async-await.md:5 msgid "" "```rust,editable,compile_fail\n" "use futures::executor::block_on;\n" "\n" "async fn count_to(count: i32) {\n" " for i in 1..=count {\n" " println!(\"Count is: {i}!\");\n" " }\n" "}\n" "\n" "async fn async_main(count: i32) {\n" " count_to(count).await;\n" "}\n" "\n" "fn main() {\n" " block_on(async_main(10));\n" "}\n" "```" msgstr "" #: src/async/async-await.md:27 msgid "" "* Note that this is a simplified example to show the syntax. There is no long\n" " running operation or any real concurrency in it!\n" "\n" "* What is the return type of an async call?\n" " * Use `let future: () = async_main(10);` in `main` to see the type.\n" "\n" "* The \"async\" keyword is syntactic sugar. The compiler replaces the return type\n" " with a future. \n" "\n" "* You cannot make `main` async, without additional instructions to the compiler\n" " on how to use the returned future.\n" "\n" "* You need an executor to run async code. `block_on` blocks the current thread\n" " until the provided future has run to completion. \n" "\n" "* `.await` asynchronously waits for the completion of another operation. Unlike\n" " `block_on`, `.await` doesn't block the current thread.\n" "\n" "* `.await` can only be used inside an `async` function (or block; these are\n" " introduced later). " msgstr "" "* これは構文を瀺すための単玔化された䟋であるこずに泚意しおください。長く実行されうる操䜜や本物の䞊" "行凊理はここには含たれたせん。\n" "* 非同期の呌び出しの返り倀の型は\n" " * 型を知るために`main`で`let future: () = async_main(10);`を䜿っおみおください。\n" "\n" "* 「async」キヌワヌドは糖衣構文です。コンパむラは返り倀をfutureに眮き換えたす。\n" "\n" "* コンパむラに察しお、返されたfutureの倀をその埌どう扱うべきかずいう、远加の指瀺を含めない限り、" "`main`をasyncにするこずはできたせん。\n" "\n" "* 非同期のコヌドを実行するためには、゚グれキュヌタが必芁です。`block_on`は、䞎えられたfutureが最埌たで" "実行されるたで、珟圚のスレッドをブロックしたす。\n" "\n" "* `.await`は非同期的に他の操䜜の完了を埅ちたす。`block_on`ずは異なり、`.await`は珟圚のスレッドをブ" "ロックしたせん。\n" "\n" "* `.await`はasync関数(たたはasync ブロック)の䞭でのみ利甚できたす。" "(async関数・ブロックに぀いおは埌ほど玹介したす。)" #: src/async/futures.md:1 msgid "# Futures" msgstr "" #: src/async/futures.md:3 msgid "" "[`Future`](https://doc.rust-lang.org/std/future/trait.Future.html)\n" "is a trait, implemented by objects that represent an operation that may not be\n" "complete yet. A future can be polled, and `poll` returns a\n" "[`Poll`](https://doc.rust-lang.org/std/task/enum.Poll.html)." msgstr "" "[`Future`](https://doc.rust-lang.org/std/future/trait.Future.html)はトレむトであり、ただ完了しおな" "いかもしれない操䜜を衚珟するオブゞェクトにより実装されたす。Futureはポヌリングされるこずがあり、" "`poll`は[`Poll`](https://doc.rust-lang.org/std/task/enum.Poll.html)を返したす。" #: src/async/futures.md:8 msgid "" "```rust\n" "use std::pin::Pin;\n" "use std::task::Context;\n" "\n" "pub trait Future {\n" " type Output;\n" " fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll;\n" "}\n" "\n" "pub enum Poll {\n" " Ready(T),\n" " Pending,\n" "}\n" "```" msgstr "" #: src/async/futures.md:23 msgid "" "An async function returns an `impl Future`. It's also possible (but uncommon) to\n" "implement `Future` for your own types. For example, the `JoinHandle` returned\n" "from `tokio::spawn` implements `Future` to allow joining to it." msgstr "" "非同期の関数は`impl Future`を返したす。自分で定矩した型に察しお`Future`を実装するこずもあたりない" "こずですが可胜です。䟋えば、`tokio::spawn`から返される`JoinHandle`は`Future`を実装する" "こずにより、joinするこずを可胜にしおいたす。" #: src/async/futures.md:27 msgid "" "The `.await` keyword, applied to a Future, causes the current async function to\n" "pause until that Future is ready, and then evaluates to its output." msgstr "" "Futureに適甚される`.await`キヌワヌドは、そのFutureの準備ができるたで、珟圚の非同期の関数の䞀時停止" "を起こし、そしおその出力を評䟡したす。" #: src/async/futures.md:32 msgid "" "* The `Future` and `Poll` types are implemented exactly as shown; click the\n" " links to show the implementations in the docs.\n" "\n" "* We will not get to `Pin` and `Context`, as we will focus on writing async\n" " code, rather than building new async primitives. Briefly:\n" "\n" " * `Context` allows a Future to schedule itself to be polled again when an\n" " event occurs.\n" "\n" " * `Pin` ensures that the Future isn't moved in memory, so that pointers into\n" " that future remain valid. This is required to allow references to remain\n" " valid after an `.await`." msgstr "" "* `Future`ず`Poll`の型はたさに瀺されたように実装されたす; ドキュメントの具䜓的な実装を芋るにはリン" "クをクリックしおください。\n" "* `Pin`ず`Context`に぀いおは詳しくは扱いたせん。なぜなら、新しく非同期のプリミティブを䜜るよりも、" "非同期のコヌドを曞くこずに我々は重点を眮く぀もりだからです。完結には以䞋で説明されたす\n" " * `Context`は、特定のむベントが発生した時に、Futureが自分自身を再びポヌリングされるようにスケ" "ゞュヌルするこずを可胜にしたす。\n" "\n" " * `Pin`はfutureぞのポむンタが有効であり続けるために、Futureがメモリの䞭で移動されないこずを確実に" "したす。これは、参照が`.await`の埌に有効であり続けるために必芁です。" #: src/async/runtimes.md:1 msgid "# Runtimes" msgstr "# ランタむム" #: src/async/runtimes.md:3 msgid "" "A *runtime* provides support for performing operations asynchronously (a\n" "*reactor*) and is responsible for executing futures (an *executor*). Rust does not have a\n" "\"built-in\" runtime, but several options are available:" msgstr "" "*runtime*は非同期な挔算*reactor*のサポヌトを提䟛し、たた、futureを実行するこず*executor*を" "担圓しおいたす。Rustには「ビルトむン」のランタむムはありたせんが、いく぀かのランタむムの遞択肢があ" "りたす: " #: src/async/runtimes.md:7 msgid "" " * [Tokio](https://tokio.rs/) - performant, with a well-developed ecosystem of\n" " functionality like [Hyper](https://hyper.rs/) for HTTP or\n" " [Tonic](https://github.com/hyperium/tonic) for gRPC.\n" " * [async-std](https://async.rs/) - aims to be a \"std for async\", and includes a\n" " basic runtime in `async::task`.\n" " * [smol](https://docs.rs/smol/latest/smol/) - simple and lightweight" msgstr "" " * [Tokio](https://tokio.rs/) - パフォヌマンスが高い。HTTP向けの[Hyper](https://hyper.rs/)やgRPC向けの[Tonic](https://" "github.com/hyperium/tonic)のような発達した゚コシステムも持っおいる\n" " * [async-std](https://async.rs/) - 「async」のための「std」であるこずを目指したもの。たた、" "`async::task`に基本的なランタむムを含む。\n" " * [smol](https://docs.rs/smol/latest/smol/) - シンプルで軜量" #: src/async/runtimes.md:14 msgid "" "Several larger applications have their own runtimes. For example,\n" "[Fuchsia](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/lib/fuchsia-async/src/lib." "rs)\n" "already has one." msgstr "" "いく぀かのより巚倧なアプリケヌションは、独自のランタむムを備えおいたす。䟋えば[Fuchsia](https://" "fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/lib/fuchsia-async/src/lib.rs)はそのようなも" "のをすでに備えおいたす。" #: src/async/runtimes.md:20 msgid "" "* Note that of the listed runtimes, only Tokio is supported in the Rust\n" " playground. The playground also does not permit any I/O, so most interesting\n" " async things can't run in the playground.\n" "\n" "* Futures are \"inert\" in that they do not do anything (not even start an I/O\n" " operation) unless there is an executor polling them. This differs from JS\n" " Promises, for example, which will run to completion even if they are never\n" " used." msgstr "" "* 䞊で挙げられたランタむムのうち、TokioのみがRustプレむグラりンドでサポヌトされおいたす。このプレむ" "グラりンドではいかなる入出力操䜜も蚱可されおいないため、倧抵の興味深い非同期のあれこれは、プレむグ" "ラりンドで実行するこずはできたせん。\n" "* Futureは、ポヌリングを行う゚グれキュヌタの存圚なしには䜕も行わない入出力操䜜さえ始めないずい" "う点で「怠惰」です。䟋えば、これは、゚グれキュヌタがなくずも最埌たで実行されるJavaScriptのPromiseず" "は異なりたす。" #: src/async/runtimes/tokio.md:1 msgid "# Tokio" msgstr "" #: src/async/runtimes/tokio.md:4 msgid "Tokio provides: " msgstr "Tokioは以䞋を提䟛したす: " #: src/async/runtimes/tokio.md:6 msgid "" "* A multi-threaded runtime for executing asynchronous code.\n" "* An asynchronous version of the standard library.\n" "* A large ecosystem of libraries." msgstr "" "* 非同期のコヌドを実行するためのマルチスレッドのランタむム。\n" "* 暙準ラむブラリの非同期バヌゞョン。\n" "* 倧きなラむブラリの゚コシステム。" #: src/async/runtimes/tokio.md:10 msgid "" "```rust,editable,compile_fail\n" "use tokio::time;\n" "\n" "async fn count_to(count: i32) {\n" " for i in 1..=count {\n" " println!(\"Count in task: {i}!\");\n" " time::sleep(time::Duration::from_millis(5)).await;\n" " }\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " tokio::spawn(count_to(10));\n" "\n" " for i in 1..5 {\n" " println!(\"Main task: {i}\");\n" " time::sleep(time::Duration::from_millis(5)).await;\n" " }\n" "}\n" "```" msgstr "" #: src/async/runtimes/tokio.md:33 msgid "" "* With the `tokio::main` macro we can now make `main` async.\n" "\n" "* The `spawn` function creates a new, concurrent \"task\".\n" "\n" "* Note: `spawn` takes a `Future`, you don't call `.await` on `count_to`." msgstr "" "* `tokio::main`のマクロにより、`main`の非同期凊理を䜜るこずができたす。\n" "\n" "* `spawn`関数は新しい䞊行の「タスク」を䜜成したす。\n" "* 泚意`spawn`は`Future`を匕数に取るため、`count_to`に察しお`.await`を呌ぶこずはありたせん。" #: src/async/runtimes/tokio.md:39 msgid "**Further exploration:**" msgstr "**さらなる探求:**" #: src/async/runtimes/tokio.md:41 msgid "" "* Why does `count_to` not (usually) get to 10? This is an example of async\n" " cancellation. `tokio::spawn` returns a handle which can be awaited to wait\n" " until it finishes.\n" "\n" "* Try `count_to(10).await` instead of spawning.\n" "\n" "* Try awaiting the task returned from `tokio::spawn`." msgstr "" "* どうしお`count_to`は通垞は10に蟿り着かないのでしょうかこれは非同期凊理のキャンセルの䟋で" "す。 `tokio::spawn`は完了たで埅機するためのハンドラを返したす。\n" "* プロセスを新しく䜜る代わりに、`count_to(10).await`を詊しおみおください。\n" "* `tokio::spawn`から返されたタスクを埅機しおみおください。" #: src/async/tasks.md:1 msgid "# Tasks" msgstr "" #: src/async/tasks.md:3 msgid "" "Runtimes have the concept of a \"task\", similar to a thread but much\n" "less resource-intensive." msgstr "" "ランタむムには「タスク」ずいう抂念があり、スレッドに䌌おいるものの、スレッドよりリ゜ヌスの消費はは" "るかに小さいです。" #: src/async/tasks.md:6 msgid "" "A task has a single top-level future which the executor polls to make progress.\n" "That future may have one or more nested futures that its `poll` method polls,\n" "corresponding loosely to a call stack. Concurrency within a task is possible by\n" "polling multiple child futures, such as racing a timer and an I/O operation." msgstr "" "タスクには、単䞀のトップレベルのfutureがあり、これぱグれキュヌタが先に進むためにポヌリングする察" "象ずなりたす。そのfutureには䞀぀たたは耇数のfutureがネストされおいるこずもあり、トップレベルの" "futureの`poll`メ゜ッドがポヌリングするこずになり、倧たかにはコヌルスタックに察応するず蚀えたす。タ" "スクにおける䞊行凊理は、䟋えば競合タむマヌや入出力操䜜など、耇数の子のfutureをポヌリングするこずに" "より可胜になりたす。" #: src/async/tasks.md:11 msgid "" "```rust,compile_fail\n" "use tokio::io::{self, AsyncReadExt, AsyncWriteExt};\n" "use tokio::net::TcpListener;\n" "\n" "#[tokio::main]\n" "async fn main() -> io::Result<()> {\n" " let listener = TcpListener::bind(\"127.0.0.1:6142\").await?;\n" "\tprintln!(\"listening on port 6142\");\n" "\n" " loop {\n" " let (mut socket, addr) = listener.accept().await?;\n" "\n" " println!(\"connection from {addr:?}\");\n" "\n" " tokio::spawn(async move {\n" " if let Err(e) = socket.write_all(b\"Who are you?\\n\").await {\n" " println!(\"socket error: {e:?}\");\n" " return;\n" " }\n" "\n" " let mut buf = vec![0; 1024];\n" " let reply = match socket.read(&mut buf).await {\n" " Ok(n) => {\n" " let name = std::str::from_utf8(&buf[..n]).unwrap().trim();\n" " format!(\"Thanks for dialing in, {name}!\\n\")\n" " }\n" " Err(e) => {\n" " println!(\"socket error: {e:?}\");\n" " return;\n" " }\n" " };\n" "\n" " if let Err(e) = socket.write_all(reply.as_bytes()).await {\n" " println!(\"socket error: {e:?}\");\n" " }\n" " });\n" " }\n" "}\n" "```" msgstr "" #: src/async/tasks.md:53 src/async/control-flow/join.md:36 msgid "Copy this example into your prepared `src/main.rs` and run it from there." msgstr "この䟋を準備した`src/main.rs`にコピヌしお、そこから実行しおみたしょう。" #: src/async/tasks.md:55 msgid "" "* Ask students to visualize what the state of the example server would be with a\n" " few connected clients. What tasks exist? What are their Futures?\n" "\n" "* This is the first time we've seen an `async` block. This is similar to a\n" " closure, but does not take any arguments. Its return value is a Future,\n" " similar to an `async fn`. \n" "\n" "* Refactor the async block into a function, and improve the error handling using `?`." msgstr "" "* 䟋のサヌバヌがどのような状態の時に、いく぀かのクラむアントず接続された状態にあるのかを、可芖化す" "るように受講者に指瀺しおください。どんなタスクが存圚しおいたすかそれらのfutureは䜕ですか\n" "\n" "* 私たちが`async`ブロックを芋かけるのは初めおですね。これはクロヌゞャず䌌おいたすが、䜕も匕数は取り" "たせん。この返り倀はFutureであり、`async fn`ず䌌おいたす。\n" "* mainのasyncブロックを関数にリファクタしお、`?`を䜿った゚ラヌハンドリングを改善しおみたしょう。" #: src/async/channels.md:1 msgid "# Async Channels" msgstr "# Asyncチャネル" #: src/async/channels.md:3 msgid "Several crates have support for `async`/`await`. For instance `tokio` channels:" msgstr "いく぀かのクレヌトは`async`/`await`をサポヌトしおいたす。䟋えば、`tokio`チャネルは:" #: src/async/channels.md:5 msgid "" "```rust,editable,compile_fail\n" "use tokio::sync::mpsc::{self, Receiver};\n" "\n" "async fn ping_handler(mut input: Receiver<()>) {\n" " let mut count: usize = 0;\n" "\n" " while let Some(_) = input.recv().await {\n" " count += 1;\n" " println!(\"Received {count} pings so far.\");\n" " }\n" "\n" " println!(\"ping_handler complete\");\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " let (sender, receiver) = mpsc::channel(32);\n" " let ping_handler_task = tokio::spawn(ping_handler(receiver));\n" " for i in 0..10 {\n" " sender.send(()).await.expect(\"Failed to send ping.\");\n" " println!(\"Sent {} pings so far.\", i + 1);\n" " }\n" "\n" " std::mem::drop(sender);\n" " ping_handler_task.await.expect(\"Something went wrong in ping handler task.\");\n" "}\n" "```" msgstr "" #: src/async/channels.md:35 msgid "" "* Change the channel size to `3` and see how it affects the execution.\n" "\n" "* Overall, the interface is similar to the `sync` channels as seen in the\n" " [morning class](concurrency/channels.md).\n" "\n" "* Try removing the `std::mem::drop` call. What happens? Why?\n" "\n" "* The [Flume](https://docs.rs/flume/latest/flume/) crate has channels that\n" " implement both `sync` and `async` `send` and `recv`. This can be convenient\n" " for complex applications with both IO and heavy CPU processing tasks.\n" "\n" "* What makes working with `async` channels preferable is the ability to combine\n" " them with other `future`s to combine them and create complex control flow." msgstr "" "* チャネルサむズを `3`に倉えおみお、これがどのように凊理に圱響するか確認しおみたしょう。\n" "\n" "* 䞀般的に、このむンタヌフェヌスは、[朝の講座](concurrency/channels.md)で芋られたような`sync`チャネ" "ルに䌌おいたす。\n" "* `std::mem::drop`の呌び出しを陀いおみたしょう。䜕か起こるでしょうかそれはなぜでしょうか\n" "\n" "* [Flume](https://docs.rs/flume/latest/flume/)クレヌトには`sync`ず`async`や`send`ず`recv`の䞡方を実" "装するチャネルがありたす。\n" "これは入出力ず重いCPUの凊理のタスクの䞡方を含む、耇雑なアプリケヌションで䟿利です。\n" "* `async`チャネルを扱うこずを奜たしくするのは、チャネルず繋げるためにや、耇雑なコントロヌルフロヌを" "䜜るために、チャネルを他の`future`ず繋げられるこずです。" #: src/async/control-flow.md:1 msgid "# Futures Control Flow" msgstr "" #: src/async/control-flow.md:3 msgid "" "Futures can be combined together to produce concurrent compute flow graphs. We\n" "have already seen tasks, that function as independent threads of execution." msgstr "" #: src/async/control-flow.md:6 msgid "" "- [Join](control-flow/join.md)\n" "- [Select](control-flow/select.md)" msgstr "" #: src/async/control-flow/join.md:1 msgid "# Join" msgstr "" #: src/async/control-flow/join.md:3 msgid "" "A join operation waits until all of a set of futures are ready, and\n" "returns a collection of their results. This is similar to `Promise.all` in\n" "JavaScript or `asyncio.gather` in Python." msgstr "" #: src/async/control-flow/join.md:7 msgid "" "```rust,editable,compile_fail\n" "use anyhow::Result;\n" "use futures::future;\n" "use reqwest;\n" "use std::collections::HashMap;\n" "\n" "async fn size_of_page(url: &str) -> Result {\n" " let resp = reqwest::get(url).await?;\n" " Ok(resp.text().await?.len())\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " let urls: [&str; 4] = [\n" " \"https://google.com\",\n" " \"https://httpbin.org/ip\",\n" " \"https://play.rust-lang.org/\",\n" " \"BAD_URL\",\n" " ];\n" " let futures_iter = urls.into_iter().map(size_of_page);\n" " let results = future::join_all(futures_iter).await;\n" " let page_sizes_dict: HashMap<&str, Result> =\n" " urls.into_iter().zip(results.into_iter()).collect();\n" " println!(\"{:?}\", page_sizes_dict);\n" "}\n" "```" msgstr "" #: src/async/control-flow/join.md:38 msgid "" "* For multiple futures of disjoint types, you can use `std::future::join!` but\n" " you must know how many futures you will have at compile time. This is\n" " currently in the `futures` crate, soon to be stabilised in `std::future`.\n" "\n" "* The risk of `join` is that one of the futures may never resolve, this would\n" " cause your program to stall. \n" "\n" "* You can also combine `join_all` with `join!` for instance to join all requests\n" " to an http service as well as a database query. Try adding a\n" " `tokio::time::sleep` to the future, using `futures::join!`. This is not a\n" " timeout (that requires `select!`, explained in the next chapter), but demonstrates `join!`." msgstr "" #: src/async/control-flow/select.md:1 msgid "# Select" msgstr "" #: src/async/control-flow/select.md:3 msgid "" "A select operation waits until any of a set of futures is ready, and responds to\n" "that future's result. In JavaScript, this is similar to `Promise.race`. In\n" "Python, it compares to `asyncio.wait(task_set,\n" "return_when=asyncio.FIRST_COMPLETED)`." msgstr "" #: src/async/control-flow/select.md:8 msgid "" "This is usually a macro, similar to match, with each arm of the form `pattern =\n" "future => statement`. When the future is ready, the statement is executed with the\n" "variable bound to the future's result." msgstr "" #: src/async/control-flow/select.md:12 msgid "" "```rust,editable,compile_fail\n" "use tokio::sync::mpsc::{self, Receiver};\n" "use tokio::time::{sleep, Duration};\n" "\n" "#[derive(Debug, PartialEq)]\n" "enum Animal {\n" " Cat { name: String },\n" " Dog { name: String },\n" "}\n" "\n" "async fn first_animal_to_finish_race(\n" " mut cat_rcv: Receiver,\n" " mut dog_rcv: Receiver,\n" ") -> Option {\n" " tokio::select! {\n" " cat_name = cat_rcv.recv() => Some(Animal::Cat { name: cat_name? }),\n" " dog_name = dog_rcv.recv() => Some(Animal::Dog { name: dog_name? })\n" " }\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " let (cat_sender, cat_receiver) = mpsc::channel(32);\n" " let (dog_sender, dog_receiver) = mpsc::channel(32);\n" " tokio::spawn(async move {\n" " sleep(Duration::from_millis(500)).await;\n" " cat_sender\n" " .send(String::from(\"Felix\"))\n" " .await\n" " .expect(\"Failed to send cat.\");\n" " });\n" " tokio::spawn(async move {\n" " sleep(Duration::from_millis(50)).await;\n" " dog_sender\n" " .send(String::from(\"Rex\"))\n" " .await\n" " .expect(\"Failed to send dog.\");\n" " });\n" "\n" " let winner = first_animal_to_finish_race(cat_receiver, dog_receiver)\n" " .await\n" " .expect(\"Failed to receive winner\");\n" "\n" " println!(\"Winner is {winner:?}\");\n" "}\n" "```" msgstr "" #: src/async/control-flow/select.md:61 msgid "" "* In this example, we have a race between a cat and a dog.\n" " `first_animal_to_finish_race` listens to both channels and will pick whichever\n" " arrives first. Since the dog takes 50ms, it wins against the cat that\n" " take 500ms seconds.\n" "\n" "* You can use `oneshot` channels in this example as the channels are supposed to\n" " receive only one `send`.\n" "\n" "* Try adding a deadline to the race, demonstrating selecting different sorts of\n" " futures.\n" "\n" "* Note that `select!` moves the values it is given. It is easiest to use\n" " when every execution of `select!` creates new futures. An alternative is to\n" " pass `&mut future` instead of the future itself, but this can lead to\n" " issues, further discussed in the pinning slide." msgstr "" #: src/async/pitfalls.md:1 msgid "# Pitfalls of async/await" msgstr "" #: src/async/pitfalls.md:3 msgid "" "Async / await provides convenient and efficient abstraction for concurrent asynchronous " "programming. However, the async/await model in Rust also comes with its share of pitfalls and " "footguns. We illustrate some of them in this chapter:" msgstr "" #: src/async/pitfalls.md:5 msgid "" "- [Blocking the Executor](pitfalls/blocking-executor.md)\n" "- [Pin](pitfalls/pin.md)\n" "- [Async Traits](pitfall/async-traits.md)" msgstr "" #: src/async/pitfalls/blocking-executor.md:1 msgid "# Blocking the executor" msgstr "" #: src/async/pitfalls/blocking-executor.md:3 msgid "" "Most async runtimes only allow IO tasks to run concurrently.\n" "This means that CPU blocking tasks will block the executor and prevent other tasks from being " "executed.\n" "An easy workaround is to use async equivalent methods where possible." msgstr "" #: src/async/pitfalls/blocking-executor.md:7 msgid "" "```rust,editable,compile_fail\n" "use futures::future::join_all;\n" "use std::time::Instant;\n" "\n" "async fn sleep_ms(start: &Instant, id: u64, duration_ms: u64) {\n" " std::thread::sleep(std::time::Duration::from_millis(duration_ms));\n" " println!(\n" " \"future {id} slept for {duration_ms}ms, finished after {}ms\",\n" " start.elapsed().as_millis()\n" " );\n" "}\n" "\n" "#[tokio::main(flavor = \"current_thread\")]\n" "async fn main() {\n" " let start = Instant::now();\n" " let sleep_futures = (1..=10).map(|t| sleep_ms(&start, t, t * 10));\n" " join_all(sleep_futures).await;\n" "}\n" "```" msgstr "" #: src/async/pitfalls/blocking-executor.md:29 msgid "" "* Run the code and see that the sleeps happen consecutively rather than\n" " concurrently.\n" "\n" "* The `\"current_thread\"` flavor puts all tasks on a single thread. This makes the\n" " effect more obvious, but the bug is still present in the multi-threaded\n" " flavor.\n" "\n" "* Switch the `std::thread::sleep` to `tokio::time::sleep` and await its result.\n" "\n" "* Another fix would be to `tokio::task::spawn_blocking` which spawns an actual\n" " thread and transforms its handle into a future without blocking the executor.\n" "\n" "* You should not think of tasks as OS threads. They do not map 1 to 1 and most\n" " executors will allow many tasks to run on a single OS thread. This is\n" " particularly problematic when interacting with other libraries via FFI, where\n" " that library might depend on thread-local storage or map to specific OS\n" " threads (e.g., CUDA). Prefer `tokio::task::spawn_blocking` in such situations.\n" "\n" "* Use sync mutexes with care. Holding a mutex over an `.await` may cause another\n" " task to block, and that task may be running on the same thread." msgstr "" #: src/async/pitfalls/pin.md:1 msgid "# Pin" msgstr "" #: src/async/pitfalls/pin.md:3 msgid "" "When you await a future, all local variables (that would ordinarily be stored on\n" "a stack frame) are instead stored in the Future for the current async block. If your\n" "future has pointers to data on the stack, those pointers might get invalidated.\n" "This is unsafe." msgstr "" #: src/async/pitfalls/pin.md:8 msgid "" "Therefore, you must guarantee that the addresses your future points to don't\n" "change. That is why we need to `pin` futures. Using the same future repeatedly\n" "in a `select!` often leads to issues with pinned values." msgstr "" #: src/async/pitfalls/pin.md:12 msgid "" "```rust,editable,compile_fail\n" "use tokio::sync::{mpsc, oneshot};\n" "use tokio::task::spawn;\n" "use tokio::time::{sleep, Duration};\n" "\n" "// A work item. In this case, just sleep for the given time and respond\n" "// with a message on the `respond_on` channel.\n" "#[derive(Debug)]\n" "struct Work {\n" " input: u32,\n" " respond_on: oneshot::Sender,\n" "}\n" "\n" "// A worker which listens for work on a queue and performs it.\n" "async fn worker(mut work_queue: mpsc::Receiver) {\n" " let mut iterations = 0;\n" " loop {\n" " tokio::select! {\n" " Some(work) = work_queue.recv() => {\n" " sleep(Duration::from_millis(10)).await; // Pretend to work.\n" " work.respond_on\n" " .send(work.input * 1000)\n" " .expect(\"failed to send response\");\n" " iterations += 1;\n" " }\n" " // TODO: report number of iterations every 100ms\n" " }\n" " }\n" "}\n" "\n" "// A requester which requests work and waits for it to complete.\n" "async fn do_work(work_queue: &mpsc::Sender, input: u32) -> u32 {\n" " let (tx, rx) = oneshot::channel();\n" " work_queue\n" " .send(Work {\n" " input,\n" " respond_on: tx,\n" " })\n" " .await\n" " .expect(\"failed to send on work queue\");\n" " rx.await.expect(\"failed waiting for response\")\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " let (tx, rx) = mpsc::channel(10);\n" " spawn(worker(rx));\n" " for i in 0..100 {\n" " let resp = do_work(&tx, i).await;\n" " println!(\"work result for iteration {i}: {resp}\");\n" " }\n" "}\n" "```" msgstr "" #: src/async/pitfalls/pin.md:68 msgid "" "* You may recognize this as an example of the actor pattern. Actors\n" " typically call `select!` in a loop.\n" "\n" "* This serves as a summation of a few of the previous lessons, so take your time\n" " with it.\n" "\n" " * Naively add a `_ = sleep(Duration::from_millis(100)) => { println!(..) }`\n" " to the `select!`. This will never execute. Why?\n" "\n" " * Instead, add a `timeout_fut` containing that future outside of the `loop`:\n" "\n" " ```rust,compile_fail\n" " let mut timeout_fut = sleep(Duration::from_millis(100));\n" " loop {\n" " select! {\n" " ..,\n" " _ = timeout_fut => { println!(..); },\n" " }\n" " }\n" " ```\n" " * This still doesn't work. Follow the compiler errors, adding `&mut` to the\n" " `timeout_fut` in the `select!` to work around the move, then using\n" " `Box::pin`:\n" "\n" " ```rust,compile_fail\n" " let mut timeout_fut = Box::pin(sleep(Duration::from_millis(100)));\n" " loop {\n" " select! {\n" " ..,\n" " _ = &mut timeout_fut => { println!(..); },\n" " }\n" " }\n" " ```\n" "\n" " * This compiles, but once the timeout expires it is `Poll::Ready` on every\n" " iteration (a fused future would help with this). Update to reset\n" " `timeout_fut` every time it expires.\n" "\n" "* Box allocates on the heap. In some cases, `std::pin::pin!` (only recently\n" " stabilized, with older code often using `tokio::pin!`) is also an option, but\n" " that is difficult to use for a future that is reassigned.\n" "\n" "* Another alternative is to not use `pin` at all but spawn another task that will send to a " "`oneshot` channel every 100ms." msgstr "" #: src/async/pitfalls/async-traits.md:1 msgid "# Async Traits" msgstr "" #: src/async/pitfalls/async-traits.md:3 msgid "" "Async methods in traits are not yet supported in the stable channel ([An experimental feature " "exists in nightly and should be stabilized in the mid term.](https://blog.rust-lang.org/inside-" "rust/2022/11/17/async-fn-in-trait-nightly.html))" msgstr "" #: src/async/pitfalls/async-traits.md:5 msgid "" "The crate [async_trait](https://docs.rs/async-trait/latest/async_trait/) provides a workaround " "through a macro:" msgstr "" #: src/async/pitfalls/async-traits.md:7 msgid "" "```rust,editable,compile_fail\n" "use async_trait::async_trait;\n" "use std::time::Instant;\n" "use tokio::time::{sleep, Duration};\n" "\n" "#[async_trait]\n" "trait Sleeper {\n" " async fn sleep(&self);\n" "}\n" "\n" "struct FixedSleeper {\n" " sleep_ms: u64,\n" "}\n" "\n" "#[async_trait]\n" "impl Sleeper for FixedSleeper {\n" " async fn sleep(&self) {\n" " sleep(Duration::from_millis(self.sleep_ms)).await;\n" " }\n" "}\n" "\n" "async fn run_all_sleepers_multiple_times(sleepers: Vec>, n_times: usize) {\n" " for _ in 0..n_times {\n" " println!(\"running all sleepers..\");\n" " for sleeper in &sleepers {\n" " let start = Instant::now();\n" " sleeper.sleep().await;\n" " println!(\"slept for {}ms\", start.elapsed().as_millis());\n" " }\n" " }\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " let sleepers: Vec> = vec![\n" " Box::new(FixedSleeper { sleep_ms: 50 }),\n" " Box::new(FixedSleeper { sleep_ms: 100 }),\n" " ];\n" " run_all_sleepers_multiple_times(sleepers, 5).await;\n" "}\n" "```" msgstr "" #: src/async/pitfalls/async-traits.md:49 msgid "
" msgstr "" #: src/async/pitfalls/async-traits.md:51 msgid "" "* `async_trait` is easy to use, but note that it's using heap allocations to\n" " achieve this. This heap allocation has performance overhead.\n" "\n" "* The challenges in language support for `async trait` are deep Rust and\n" " probably not worth describing in-depth. Niko Matsakis did a good job of\n" " explaining them in [this\n" " post](https://smallcultfollowing.com/babysteps/blog/2019/10/26/async-fn-in-traits-are-hard/)\n" " if you are interested in digging deeper.\n" "\n" "* Try creating a new sleeper struct that will sleep for a random amount of time\n" " and adding it to the Vec." msgstr "" #: src/exercises/concurrency/afternoon.md:3 msgid "To practice your Async Rust skills, we have again two exercises for you:" msgstr "" #: src/exercises/concurrency/afternoon.md:5 msgid "" "* Dining philosophers: we already saw this problem in the morning. This time\n" " you are going to implement it with Async Rust.\n" "\n" "* A Broadcast Chat Application: this is a larger project that allows you\n" " experiment with more advanced Async Rust features." msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:1 msgid "# Dining Philosophers - Async" msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:3 msgid "" "See [dining philosophers](dining-philosophers.md) for a description of the\n" "problem." msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:6 msgid "" "As before, you will need a local\n" "[Cargo installation](../../cargo/running-locally.md) for this exercise. Copy\n" "the code below to a file called `src/main.rs`, fill out the blanks, and test\n" "that `cargo run` does not deadlock:" msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:13 msgid "" "```rust,compile_fail\n" "use std::sync::Arc;\n" "use tokio::time;\n" "use tokio::sync::mpsc::{self, Sender};\n" "use tokio::sync::Mutex;\n" "\n" "struct Fork;\n" "\n" "struct Philosopher {\n" " name: String,\n" " // left_fork: ...\n" " // right_fork: ...\n" " // thoughts: ...\n" "}\n" "\n" "impl Philosopher {\n" " async fn think(&self) {\n" " self.thoughts\n" " .send(format!(\"Eureka! {} has a new idea!\", &self.name)).await\n" " .unwrap();\n" " }\n" "\n" " async fn eat(&self) {\n" " // Pick up forks...\n" " println!(\"{} is eating...\", &self.name);\n" " time::sleep(time::Duration::from_millis(5)).await;\n" " }\n" "}\n" "\n" "static PHILOSOPHERS: &[&str] =\n" " &[\"Socrates\", \"Plato\", \"Aristotle\", \"Thales\", \"Pythagoras\"];\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " // Create forks\n" "\n" " // Create philosophers\n" "\n" " // Make them think and eat\n" "\n" " // Output their thoughts\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:57 msgid "" "Since this time you are using Async Rust, you'll need a `tokio` dependency.\n" "You can use the following `Cargo.toml`:" msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:62 msgid "" "```toml\n" "[package]\n" "name = \"dining-philosophers-async-dine\"\n" "version = \"0.1.0\"\n" "edition = \"2021\"\n" "\n" "[dependencies]\n" "tokio = {version = \"1.26.0\", features = [\"sync\", \"time\", \"macros\", \"rt-multi-thread\"]}\n" "```" msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:72 msgid "" "Also note that this time you have to use the `Mutex` and the `mpsc` module\n" "from the `tokio` crate." msgstr "" #: src/exercises/concurrency/dining-philosophers-async.md:77 msgid "* Can you make your implementation single-threaded? " msgstr "" #: src/exercises/concurrency/chat-app.md:1 msgid "# Broadcast Chat Application" msgstr "" #: src/exercises/concurrency/chat-app.md:3 msgid "" "In this exercise, we want to use our new knowledge to implement a broadcast\n" "chat application. We have a chat server that the clients connect to and publish\n" "their messages. The client reads user messages from the standard input, and\n" "sends them to the server. The chat server broadcasts each message that it\n" "receives to all the clients." msgstr "" #: src/exercises/concurrency/chat-app.md:9 msgid "" "For this, we use [a broadcast channel][1] on the server, and\n" "[`tokio_websockets`][2] for the communication between the client and the\n" "server." msgstr "" #: src/exercises/concurrency/chat-app.md:13 msgid "Create a new Cargo project and add the following dependencies:" msgstr "" #: src/exercises/concurrency/chat-app.md:15 msgid "`Cargo.toml`:" msgstr "" #: src/exercises/concurrency/chat-app.md:19 msgid "" "```toml\n" "[package]\n" "name = \"chat-async\"\n" "version = \"0.1.0\"\n" "edition = \"2021\"\n" "\n" "[dependencies]\n" "futures-util = \"0.3.28\"\n" "http = \"0.2.9\"\n" "tokio = { version = \"1.28.1\", features = [\"full\"] }\n" "tokio-websockets = \"0.3.2\"\n" "```" msgstr "" #: src/exercises/concurrency/chat-app.md:32 msgid "## The required APIs" msgstr "" #: src/exercises/concurrency/chat-app.md:33 msgid "" "You are going to need the following functions from `tokio` and\n" "[`tokio_websockets`][2]. Spend a few minutes to familiarize yourself with the\n" "API. " msgstr "" #: src/exercises/concurrency/chat-app.md:37 msgid "" "- [WebsocketStream::next()][3]: for asynchronously reading messages from a\n" " Websocket Stream.\n" "- [SinkExt::send()][4] implemented by `WebsocketStream`: for asynchronously\n" " sending messages on a Websocket Stream.\n" "- [BufReader::read_line()][5]: for asynchronously reading user messages\n" " from the standard input.\n" "- [Sender::subscribe()][6]: for subscribing to a broadcast channel." msgstr "" #: src/exercises/concurrency/chat-app.md:46 msgid "## Two binaries" msgstr "" #: src/exercises/concurrency/chat-app.md:48 msgid "" "Normally in a Cargo project, you can have only one binary, and one\n" "`src/main.rs` file. In this project, we need two binaries. One for the client,\n" "and one for the server. You could potentially make them two separate Cargo\n" "projects, but we are going to put them in a single Cargo project with two\n" "binaries. For this to work, the client and the server code should go under\n" "`src/bin` (see the [documentation][7]). " msgstr "" #: src/exercises/concurrency/chat-app.md:55 msgid "" "Copy the following server and client code into `src/bin/server.rs` and\n" "`src/bin/client.rs`, respectively. Your task is to complete these files as\n" "described below. " msgstr "" #: src/exercises/concurrency/chat-app.md:59 src/exercises/concurrency/solutions-afternoon.md:117 msgid "`src/bin/server.rs`:" msgstr "" #: src/exercises/concurrency/chat-app.md:61 msgid "" msgstr "" #: src/exercises/concurrency/chat-app.md:63 msgid "" "```rust,compile_fail\n" "use futures_util::sink::SinkExt;\n" "use std::error::Error;\n" "use std::net::SocketAddr;\n" "use tokio::net::{TcpListener, TcpStream};\n" "use tokio::sync::broadcast::{channel, Sender};\n" "use tokio_websockets::{Message, ServerBuilder, WebsocketStream};\n" "\n" "async fn handle_connection(\n" " addr: SocketAddr,\n" " mut ws_stream: WebsocketStream,\n" " bcast_tx: Sender,\n" ") -> Result<(), Box> {\n" "\n" " // TODO: For a hint, see the description of the task below.\n" "\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() -> Result<(), Box> {\n" " let (bcast_tx, _) = channel(16);\n" "\n" " let listener = TcpListener::bind(\"127.0.0.1:2000\").await?;\n" " println!(\"listening on port 2000\");\n" "\n" " loop {\n" " let (socket, addr) = listener.accept().await?;\n" " println!(\"New connection from {addr:?}\");\n" " let bcast_tx = bcast_tx.clone();\n" " tokio::spawn(async move {\n" " // Wrap the raw TCP stream into a websocket.\n" " let ws_stream = ServerBuilder::new().accept(socket).await?;\n" "\n" " handle_connection(addr, ws_stream, bcast_tx).await\n" " });\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/chat-app.md:102 src/exercises/concurrency/solutions-afternoon.md:202 msgid "`src/bin/client.rs`:" msgstr "" #: src/exercises/concurrency/chat-app.md:104 msgid "" msgstr "" #: src/exercises/concurrency/chat-app.md:106 msgid "" "```rust,compile_fail\n" "use futures_util::SinkExt;\n" "use http::Uri;\n" "use tokio::io::{AsyncBufReadExt, BufReader};\n" "use tokio_websockets::{ClientBuilder, Message};\n" "\n" "#[tokio::main]\n" "async fn main() -> Result<(), tokio_websockets::Error> {\n" " let mut ws_stream = ClientBuilder::from_uri(Uri::from_static(\"ws://127.0.0.1:2000\"))\n" " .connect()\n" " .await?;\n" "\n" " let stdin = tokio::io::stdin();\n" " let mut stdin = BufReader::new(stdin);\n" "\n" "\n" " // TODO: For a hint, see the description of the task below.\n" "\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/chat-app.md:127 msgid "## Running the binaries" msgstr "" #: src/exercises/concurrency/chat-app.md:128 msgid "Run the server with:" msgstr "" #: src/exercises/concurrency/chat-app.md:130 msgid "" "```shell\n" "$ cargo run --bin server\n" "```" msgstr "" #: src/exercises/concurrency/chat-app.md:134 msgid "and the client with:" msgstr "" #: src/exercises/concurrency/chat-app.md:136 msgid "" "```shell\n" "$ cargo run --bin client\n" "```" msgstr "" #: src/exercises/concurrency/chat-app.md:142 msgid "" "* Implement the `handle_connection` function in `src/bin/server.rs`.\n" " * Hint: Use `tokio::select!` for concurrently performing two tasks in a\n" " continuous loop. One task receives messages from the client and broadcasts\n" " them. The other sends messages received by the server to the client.\n" "* Complete the main function in `src/bin/client.rs`.\n" " * Hint: As before, use `tokio::select!` in a continuous loop for concurrently\n" " performing two tasks: (1) reading user messages from standard input and\n" " sending them to the server, and (2) receiving messages from the server, and\n" " displaying them for the user.\n" "* Optional: Once you are done, change the code to broadcast messages to all\n" " clients, but the sender of the message." msgstr "" #: src/thanks.md:1 msgid "# Thanks!" msgstr "" #: src/thanks.md:3 msgid "" "_Thank you for taking Comprehensive Rust 🊀!_ We hope you enjoyed it and that it\n" "was useful." msgstr "" #: src/thanks.md:6 msgid "" "We've had a lot of fun putting the course together. The course is not perfect,\n" "so if you spotted any mistakes or have ideas for improvements, please get in\n" "[contact with us on\n" "GitHub](https://github.com/google/comprehensive-rust/discussions). We would love\n" "to hear from you." msgstr "" #: src/other-resources.md:1 msgid "# Other Rust Resources" msgstr "" #: src/other-resources.md:3 msgid "" "The Rust community has created a wealth of high-quality and free resources\n" "online." msgstr "" #: src/other-resources.md:6 msgid "## Official Documentation" msgstr "" #: src/other-resources.md:8 msgid "The Rust project hosts many resources. These cover Rust in general:" msgstr "" #: src/other-resources.md:10 msgid "" "* [The Rust Programming Language](https://doc.rust-lang.org/book/): the\n" " canonical free book about Rust. Covers the language in detail and includes a\n" " few projects for people to build.\n" "* [Rust By Example](https://doc.rust-lang.org/rust-by-example/): covers the Rust\n" " syntax via a series of examples which showcase different constructs. Sometimes\n" " includes small exercises where you are asked to expand on the code in the\n" " examples.\n" "* [Rust Standard Library](https://doc.rust-lang.org/std/): full documentation of\n" " the standard library for Rust.\n" "* [The Rust Reference](https://doc.rust-lang.org/reference/): an incomplete book\n" " which describes the Rust grammar and memory model." msgstr "" #: src/other-resources.md:22 msgid "More specialized guides hosted on the official Rust site:" msgstr "" #: src/other-resources.md:24 msgid "" "* [The Rustonomicon](https://doc.rust-lang.org/nomicon/): covers unsafe Rust,\n" " including working with raw pointers and interfacing with other languages\n" " (FFI).\n" "* [Asynchronous Programming in Rust](https://rust-lang.github.io/async-book/):\n" " covers the new asynchronous programming model which was introduced after the\n" " Rust Book was written.\n" "* [The Embedded Rust Book](https://doc.rust-lang.org/stable/embedded-book/): an\n" " introduction to using Rust on embedded devices without an operating system." msgstr "" #: src/other-resources.md:33 msgid "## Unofficial Learning Material" msgstr "" #: src/other-resources.md:35 msgid "A small selection of other guides and tutorial for Rust:" msgstr "" #: src/other-resources.md:37 msgid "" "* [Learn Rust the Dangerous Way](http://cliffle.com/p/dangerust/): covers Rust\n" " from the perspective of low-level C programmers.\n" "* [Rust for Embedded C\n" " Programmers](https://docs.opentitan.org/doc/ug/rust_for_c/): covers Rust from\n" " the perspective of developers who write firmware in C.\n" "* [Rust for professionals](https://overexact.com/rust-for-professionals/):\n" " covers the syntax of Rust using side-by-side comparisons with other languages\n" " such as C, C++, Java, JavaScript, and Python.\n" "* [Rust on Exercism](https://exercism.org/tracks/rust): 100+ exercises to help\n" " you learn Rust.\n" "* [Ferrous Teaching\n" " Material](https://ferrous-systems.github.io/teaching-material/index.html): a\n" " series of small presentations covering both basic and advanced part of the\n" " Rust language. Other topics such as WebAssembly, and async/await are also\n" " covered.\n" "* [Beginner's Series to\n" " Rust](https://docs.microsoft.com/en-us/shows/beginners-series-to-rust/) and\n" " [Take your first steps with\n" " Rust](https://docs.microsoft.com/en-us/learn/paths/rust-first-steps/): two\n" " Rust guides aimed at new developers. The first is a set of 35 videos and the\n" " second is a set of 11 modules which covers Rust syntax and basic constructs.\n" "* [Learn Rust With Entirely Too Many Linked\n" " Lists](https://rust-unofficial.github.io/too-many-lists/): in-depth\n" " exploration of Rust's memory management rules, through implementing a few\n" " different types of list structures." msgstr "" #: src/other-resources.md:63 msgid "" "Please see the [Little Book of Rust Books](https://lborb.github.io/book/) for\n" "even more Rust books." msgstr "" #: src/credits.md:1 msgid "# Credits" msgstr "" #: src/credits.md:3 msgid "" "The material here builds on top of the many great sources of Rust documentation.\n" "See the page on [other resources](other-resources.md) for a full list of useful\n" "resources." msgstr "" #: src/credits.md:7 msgid "" "The material of Comprehensive Rust is licensed under the terms of the Apache 2.0\n" "license, please see [`LICENSE`](../LICENSE) for details." msgstr "" #: src/credits.md:10 msgid "## Rust by Example" msgstr "" #: src/credits.md:12 msgid "" "Some examples and exercises have been copied and adapted from [Rust by\n" "Example](https://doc.rust-lang.org/rust-by-example/). Please see the\n" "`third_party/rust-by-example/` directory for details, including the license\n" "terms." msgstr "" #: src/credits.md:17 msgid "## Rust on Exercism" msgstr "" #: src/credits.md:19 msgid "" "Some exercises have been copied and adapted from [Rust on\n" "Exercism](https://exercism.org/tracks/rust). Please see the\n" "`third_party/rust-on-exercism/` directory for details, including the license\n" "terms." msgstr "" #: src/credits.md:24 msgid "## CXX" msgstr "" #: src/credits.md:26 msgid "" "The [Interoperability with C++](android/interoperability/cpp.md) section uses an\n" "image from [CXX](https://cxx.rs/). Please see the `third_party/cxx/` directory\n" "for details, including the license terms." msgstr "" #: src/exercises/solutions.md:1 msgid "# Solutions" msgstr "" #: src/exercises/solutions.md:3 msgid "You will find solutions to the exercises on the following pages." msgstr "" #: src/exercises/solutions.md:5 msgid "" "Feel free to ask questions about the solutions [on\n" "GitHub](https://github.com/google/comprehensive-rust/discussions). Let us know\n" "if you have a different or better solution than what is presented here." msgstr "" #: src/exercises/solutions.md:10 msgid "" "> **Note:** Please ignore the `// ANCHOR: label` and `// ANCHOR_END: label`\n" "> comments you see in the solutions. They are there to make it possible to\n" "> re-use parts of the solutions as the exercises." msgstr "" #: src/exercises/day-1/solutions-morning.md:1 msgid "# Day 1 Morning Exercises" msgstr "" #: src/exercises/day-1/solutions-morning.md:3 msgid "## Arrays and `for` Loops" msgstr "" #: src/exercises/day-1/solutions-morning.md:5 msgid "([back to exercise](for-loops.md))" msgstr "" #: src/exercises/day-1/solutions-morning.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: transpose\n" "fn transpose(matrix: [[i32; 3]; 3]) -> [[i32; 3]; 3] {\n" " // ANCHOR_END: transpose\n" " let mut result = [[0; 3]; 3];\n" " for i in 0..3 {\n" " for j in 0..3 {\n" " result[j][i] = matrix[i][j];\n" " }\n" " }\n" " return result;\n" "}\n" "\n" "// ANCHOR: pretty_print\n" "fn pretty_print(matrix: &[[i32; 3]; 3]) {\n" " // ANCHOR_END: pretty_print\n" " for row in matrix {\n" " println!(\"{row:?}\");\n" " }\n" "}\n" "\n" "// ANCHOR: tests\n" "#[test]\n" "fn test_transpose() {\n" " let matrix = [\n" " [101, 102, 103], //\n" " [201, 202, 203],\n" " [301, 302, 303],\n" " ];\n" " let transposed = transpose(matrix);\n" " assert_eq!(\n" " transposed,\n" " [\n" " [101, 201, 301], //\n" " [102, 202, 302],\n" " [103, 203, 303],\n" " ]\n" " );\n" "}\n" "// ANCHOR_END: tests\n" "\n" "// ANCHOR: main\n" "fn main() {\n" " let matrix = [\n" " [101, 102, 103], // <-- the comment makes rustfmt add a newline\n" " [201, 202, 203],\n" " [301, 302, 303],\n" " ];\n" "\n" " println!(\"matrix:\");\n" " pretty_print(&matrix);\n" "\n" " let transposed = transpose(matrix);\n" " println!(\"transposed:\");\n" " pretty_print(&transposed);\n" "}\n" "```" msgstr "" #: src/exercises/day-1/solutions-morning.md:78 msgid "### Bonus question" msgstr "" #: src/exercises/day-1/solutions-morning.md:80 msgid "" "It requires more advanced concepts. It might seem that we could use a slice-of-slices " "(`&[&[i32]]`) as the input type to transpose and thus make our function handle any size of matrix. " "However, this quickly breaks down: the return type cannot be `&[&[i32]]` since it needs to own the " "data you return." msgstr "" #: src/exercises/day-1/solutions-morning.md:82 msgid "" "You can attempt to use something like `Vec>`, but this doesn't work out-of-the-box " "either: it's hard to convert from `Vec>` to `&[&[i32]]` so now you cannot easily use " "`pretty_print` either." msgstr "" #: src/exercises/day-1/solutions-morning.md:84 msgid "" "Once we get to traits and generics, we'll be able to use the [`std::convert::AsRef`][1] trait to " "abstract over anything that can be referenced as a slice." msgstr "" #: src/exercises/day-1/solutions-morning.md:86 msgid "" "```rust\n" "use std::convert::AsRef;\n" "use std::fmt::Debug;\n" "\n" "fn pretty_print(matrix: Matrix)\n" "where\n" " T: Debug,\n" " // A line references a slice of items\n" " Line: AsRef<[T]>,\n" " // A matrix references a slice of lines\n" " Matrix: AsRef<[Line]>\n" "{\n" " for row in matrix.as_ref() {\n" " println!(\"{:?}\", row.as_ref());\n" " }\n" "}\n" "\n" "fn main() {\n" " // &[&[i32]]\n" " pretty_print(&[&[1, 2, 3], &[4, 5, 6], &[7, 8, 9]]);\n" " // [[&str; 2]; 2]\n" " pretty_print([[\"a\", \"b\"], [\"c\", \"d\"]]);\n" " // Vec>\n" " pretty_print(vec![vec![1, 2], vec![3, 4]]);\n" "}\n" "```" msgstr "" #: src/exercises/day-1/solutions-morning.md:113 msgid "" "In addition, the type itself would not enforce that the child slices are of the same length, so " "such variable could contain an invalid matrix." msgstr "" #: src/exercises/day-1/solutions-afternoon.md:1 msgid "# Day 1 Afternoon Exercises" msgstr "" #: src/exercises/day-1/solutions-afternoon.md:3 msgid "## Designing a Library" msgstr "" #: src/exercises/day-1/solutions-afternoon.md:5 msgid "([back to exercise](book-library.md))" msgstr "" #: src/exercises/day-1/solutions-afternoon.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: setup\n" "struct Library {\n" " books: Vec,\n" "}\n" "\n" "struct Book {\n" " title: String,\n" " year: u16,\n" "}\n" "\n" "impl Book {\n" " // This is a constructor, used below.\n" " fn new(title: &str, year: u16) -> Book {\n" " Book {\n" " title: String::from(title),\n" " year,\n" " }\n" " }\n" "}\n" "\n" "// Implement the methods below. Update the `self` parameter to\n" "// indicate the method's required level of ownership over the object:\n" "//\n" "// - `&self` for shared read-only access,\n" "// - `&mut self` for unique and mutable access,\n" "// - `self` for unique access by value.\n" "impl Library {\n" " // ANCHOR_END: setup\n" "\n" " // ANCHOR: Library_new\n" " fn new() -> Library {\n" " // ANCHOR_END: Library_new\n" " Library { books: Vec::new() }\n" " }\n" "\n" " // ANCHOR: Library_len\n" " //fn len(self) -> usize {\n" " // todo!(\"Return the length of `self.books`\")\n" " //}\n" " // ANCHOR_END: Library_len\n" " fn len(&self) -> usize {\n" " self.books.len()\n" " }\n" "\n" " // ANCHOR: Library_is_empty\n" " //fn is_empty(self) -> bool {\n" " // todo!(\"Return `true` if `self.books` is empty\")\n" " //}\n" " // ANCHOR_END: Library_is_empty\n" " fn is_empty(&self) -> bool {\n" " self.books.is_empty()\n" " }\n" "\n" " // ANCHOR: Library_add_book\n" " //fn add_book(self, book: Book) {\n" " // todo!(\"Add a new book to `self.books`\")\n" " //}\n" " // ANCHOR_END: Library_add_book\n" " fn add_book(&mut self, book: Book) {\n" " self.books.push(book)\n" " }\n" "\n" " // ANCHOR: Library_print_books\n" " //fn print_books(self) {\n" " // todo!(\"Iterate over `self.books` and each book's title and year\")\n" " //}\n" " // ANCHOR_END: Library_print_books\n" " fn print_books(&self) {\n" " for book in &self.books {\n" " println!(\"{}, published in {}\", book.title, book.year);\n" " }\n" " }\n" "\n" " // ANCHOR: Library_oldest_book\n" " //fn oldest_book(self) -> Option<&Book> {\n" " // todo!(\"Return a reference to the oldest book (if any)\")\n" " //}\n" " // ANCHOR_END: Library_oldest_book\n" " fn oldest_book(&self) -> Option<&Book> {\n" " // Using a closure and a built-in method:\n" " // self.books.iter().min_by_key(|book| book.year)\n" "\n" " // Longer hand-written solution:\n" " let mut oldest: Option<&Book> = None;\n" " for book in self.books.iter() {\n" " if oldest.is_none() || book.year < oldest.unwrap().year {\n" " oldest = Some(book);\n" " }\n" " }\n" "\n" " oldest\n" " }\n" "}\n" "\n" "// ANCHOR: main\n" "// This shows the desired behavior. Uncomment the code below and\n" "// implement the missing methods. You will need to update the\n" "// method signatures, including the \"self\" parameter! You may\n" "// also need to update the variable bindings within main.\n" "fn main() {\n" " let library = Library::new();\n" "\n" " //println!(\"The library is empty: {}\", library.is_empty());\n" " //\n" " //library.add_book(Book::new(\"Lord of the Rings\", 1954));\n" " //library.add_book(Book::new(\"Alice's Adventures in Wonderland\", 1865));\n" " //\n" " //println!(\"The library is no longer empty: {}\", library.is_empty());\n" " //\n" " //\n" " //library.print_books();\n" " //\n" " //match library.oldest_book() {\n" " // Some(book) => println!(\"The oldest book is {}\", book.title),\n" " // None => println!(\"The library is empty!\"),\n" " //}\n" " //\n" " //println!(\"The library has {} books\", library.len());\n" " //library.print_books();\n" "}\n" "// ANCHOR_END: main\n" "\n" "#[test]\n" "fn test_library_len() {\n" " let mut library = Library::new();\n" " assert_eq!(library.len(), 0);\n" " assert!(library.is_empty());\n" "\n" " library.add_book(Book::new(\"Lord of the Rings\", 1954));\n" " library.add_book(Book::new(\"Alice's Adventures in Wonderland\", 1865));\n" " assert_eq!(library.len(), 2);\n" " assert!(!library.is_empty());\n" "}\n" "\n" "#[test]\n" "fn test_library_is_empty() {\n" " let mut library = Library::new();\n" " assert!(library.is_empty());\n" "\n" " library.add_book(Book::new(\"Lord of the Rings\", 1954));\n" " assert!(!library.is_empty());\n" "}\n" "\n" "#[test]\n" "fn test_library_print_books() {\n" " let mut library = Library::new();\n" " library.add_book(Book::new(\"Lord of the Rings\", 1954));\n" " library.add_book(Book::new(\"Alice's Adventures in Wonderland\", 1865));\n" " // We could try and capture stdout, but let us just call the\n" " // method to start with.\n" " library.print_books();\n" "}\n" "\n" "#[test]\n" "fn test_library_oldest_book() {\n" " let mut library = Library::new();\n" " assert!(library.oldest_book().is_none());\n" "\n" " library.add_book(Book::new(\"Lord of the Rings\", 1954));\n" " assert_eq!(\n" " library.oldest_book().map(|b| b.title.as_str()),\n" " Some(\"Lord of the Rings\")\n" " );\n" "\n" " library.add_book(Book::new(\"Alice's Adventures in Wonderland\", 1865));\n" " assert_eq!(\n" " library.oldest_book().map(|b| b.title.as_str()),\n" " Some(\"Alice's Adventures in Wonderland\")\n" " );\n" "}\n" "```" msgstr "" #: src/exercises/day-2/solutions-morning.md:1 msgid "# Day 2 Morning Exercises" msgstr "" #: src/exercises/day-2/solutions-morning.md:3 msgid "## Points and Polygons" msgstr "" #: src/exercises/day-2/solutions-morning.md:5 msgid "([back to exercise](points-polygons.md))" msgstr "" #: src/exercises/day-2/solutions-morning.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "#[derive(Debug, Copy, Clone, PartialEq, Eq)]\n" "// ANCHOR: Point\n" "pub struct Point {\n" " // ANCHOR_END: Point\n" " x: i32,\n" " y: i32,\n" "}\n" "\n" "// ANCHOR: Point-impl\n" "impl Point {\n" " // ANCHOR_END: Point-impl\n" " pub fn new(x: i32, y: i32) -> Point {\n" " Point { x, y }\n" " }\n" "\n" " pub fn magnitude(self) -> f64 {\n" " f64::from(self.x.pow(2) + self.y.pow(2)).sqrt()\n" " }\n" "\n" " pub fn dist(self, other: Point) -> f64 {\n" " (self - other).magnitude()\n" " }\n" "}\n" "\n" "impl std::ops::Add for Point {\n" " type Output = Self;\n" "\n" " fn add(self, other: Self) -> Self::Output {\n" " Self {\n" " x: self.x + other.x,\n" " y: self.y + other.y,\n" " }\n" " }\n" "}\n" "\n" "impl std::ops::Sub for Point {\n" " type Output = Self;\n" "\n" " fn sub(self, other: Self) -> Self::Output {\n" " Self {\n" " x: self.x - other.x,\n" " y: self.y - other.y,\n" " }\n" " }\n" "}\n" "\n" "// ANCHOR: Polygon\n" "pub struct Polygon {\n" " // ANCHOR_END: Polygon\n" " points: Vec,\n" "}\n" "\n" "// ANCHOR: Polygon-impl\n" "impl Polygon {\n" " // ANCHOR_END: Polygon-impl\n" " pub fn new() -> Polygon {\n" " Polygon { points: Vec::new() }\n" " }\n" "\n" " pub fn add_point(&mut self, point: Point) {\n" " self.points.push(point);\n" " }\n" "\n" " pub fn left_most_point(&self) -> Option {\n" " self.points.iter().min_by_key(|p| p.x).copied()\n" " }\n" "\n" " pub fn iter(&self) -> impl Iterator {\n" " self.points.iter()\n" " }\n" "\n" " pub fn length(&self) -> f64 {\n" " if self.points.is_empty() {\n" " return 0.0;\n" " }\n" "\n" " let mut result = 0.0;\n" " let mut last_point = self.points[0];\n" " for point in &self.points[1..] {\n" " result += last_point.dist(*point);\n" " last_point = *point;\n" " }\n" " result += last_point.dist(self.points[0]);\n" " result\n" " }\n" "}\n" "\n" "// ANCHOR: Circle\n" "pub struct Circle {\n" " // ANCHOR_END: Circle\n" " center: Point,\n" " radius: i32,\n" "}\n" "\n" "// ANCHOR: Circle-impl\n" "impl Circle {\n" " // ANCHOR_END: Circle-impl\n" " pub fn new(center: Point, radius: i32) -> Circle {\n" " Circle { center, radius }\n" " }\n" "\n" " pub fn circumference(&self) -> f64 {\n" " 2.0 * std::f64::consts::PI * f64::from(self.radius)\n" " }\n" "\n" " pub fn dist(&self, other: &Self) -> f64 {\n" " self.center.dist(other.center)\n" " }\n" "}\n" "\n" "// ANCHOR: Shape\n" "pub enum Shape {\n" " Polygon(Polygon),\n" " Circle(Circle),\n" "}\n" "// ANCHOR_END: Shape\n" "\n" "impl From for Shape {\n" " fn from(poly: Polygon) -> Self {\n" " Shape::Polygon(poly)\n" " }\n" "}\n" "\n" "impl From for Shape {\n" " fn from(circle: Circle) -> Self {\n" " Shape::Circle(circle)\n" " }\n" "}\n" "\n" "impl Shape {\n" " pub fn perimeter(&self) -> f64 {\n" " match self {\n" " Shape::Polygon(poly) => poly.length(),\n" " Shape::Circle(circle) => circle.circumference(),\n" " }\n" " }\n" "}\n" "\n" "// ANCHOR: unit-tests\n" "#[cfg(test)]\n" "mod tests {\n" " use super::*;\n" "\n" " fn round_two_digits(x: f64) -> f64 {\n" " (x * 100.0).round() / 100.0\n" " }\n" "\n" " #[test]\n" " fn test_point_magnitude() {\n" " let p1 = Point::new(12, 13);\n" " assert_eq!(round_two_digits(p1.magnitude()), 17.69);\n" " }\n" "\n" " #[test]\n" " fn test_point_dist() {\n" " let p1 = Point::new(10, 10);\n" " let p2 = Point::new(14, 13);\n" " assert_eq!(round_two_digits(p1.dist(p2)), 5.00);\n" " }\n" "\n" " #[test]\n" " fn test_point_add() {\n" " let p1 = Point::new(16, 16);\n" " let p2 = p1 + Point::new(-4, 3);\n" " assert_eq!(p2, Point::new(12, 19));\n" " }\n" "\n" " #[test]\n" " fn test_polygon_left_most_point() {\n" " let p1 = Point::new(12, 13);\n" " let p2 = Point::new(16, 16);\n" "\n" " let mut poly = Polygon::new();\n" " poly.add_point(p1);\n" " poly.add_point(p2);\n" " assert_eq!(poly.left_most_point(), Some(p1));\n" " }\n" "\n" " #[test]\n" " fn test_polygon_iter() {\n" " let p1 = Point::new(12, 13);\n" " let p2 = Point::new(16, 16);\n" "\n" " let mut poly = Polygon::new();\n" " poly.add_point(p1);\n" " poly.add_point(p2);\n" "\n" " let points = poly.iter().cloned().collect::>();\n" " assert_eq!(points, vec![Point::new(12, 13), Point::new(16, 16)]);\n" " }\n" "\n" " #[test]\n" " fn test_shape_perimeters() {\n" " let mut poly = Polygon::new();\n" " poly.add_point(Point::new(12, 13));\n" " poly.add_point(Point::new(17, 11));\n" " poly.add_point(Point::new(16, 16));\n" " let shapes = vec![\n" " Shape::from(poly),\n" " Shape::from(Circle::new(Point::new(10, 20), 5)),\n" " ];\n" " let perimeters = shapes\n" " .iter()\n" " .map(Shape::perimeter)\n" " .map(round_two_digits)\n" " .collect::>();\n" " assert_eq!(perimeters, vec![15.48, 31.42]);\n" " }\n" "}\n" "// ANCHOR_END: unit-tests\n" "\n" "fn main() {}\n" "```" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:1 msgid "# Day 2 Afternoon Exercises" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:3 msgid "## Luhn Algorithm" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:5 msgid "([back to exercise](luhn.md))" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: luhn\n" "pub fn luhn(cc_number: &str) -> bool {\n" " // ANCHOR_END: luhn\n" " let mut digits_seen = 0;\n" " let mut sum = 0;\n" " for (i, ch) in cc_number.chars().rev().filter(|&ch| ch != ' ').enumerate() {\n" " match ch.to_digit(10) {\n" " Some(d) => {\n" " sum += if i % 2 == 1 {\n" " let dd = d * 2;\n" " dd / 10 + dd % 10\n" " } else {\n" " d\n" " };\n" " digits_seen += 1;\n" " }\n" " None => return false,\n" " }\n" " }\n" "\n" " if digits_seen < 2 {\n" " return false;\n" " }\n" "\n" " sum % 10 == 0\n" "}\n" "\n" "fn main() {\n" " let cc_number = \"1234 5678 1234 5670\";\n" " println!(\n" " \"Is {cc_number} a valid credit card number? {}\",\n" " if luhn(cc_number) { \"yes\" } else { \"no\" }\n" " );\n" "}\n" "\n" "// ANCHOR: unit-tests\n" "#[test]\n" "fn test_non_digit_cc_number() {\n" " assert!(!luhn(\"foo\"));\n" "}\n" "\n" "#[test]\n" "fn test_empty_cc_number() {\n" " assert!(!luhn(\"\"));\n" " assert!(!luhn(\" \"));\n" " assert!(!luhn(\" \"));\n" " assert!(!luhn(\" \"));\n" "}\n" "\n" "#[test]\n" "fn test_single_digit_cc_number() {\n" " assert!(!luhn(\"0\"));\n" "}\n" "\n" "#[test]\n" "fn test_two_digit_cc_number() {\n" " assert!(luhn(\" 0 0 \"));\n" "}\n" "\n" "#[test]\n" "fn test_valid_cc_number() {\n" " assert!(luhn(\"4263 9826 4026 9299\"));\n" " assert!(luhn(\"4539 3195 0343 6467\"));\n" " assert!(luhn(\"7992 7398 713\"));\n" "}\n" "\n" "#[test]\n" "fn test_invalid_cc_number() {\n" " assert!(!luhn(\"4223 9826 4026 9299\"));\n" " assert!(!luhn(\"4539 3195 0343 6476\"));\n" " assert!(!luhn(\"8273 1232 7352 0569\"));\n" "}\n" "// ANCHOR_END: unit-tests\n" "```" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:97 msgid "## Strings and Iterators" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:99 msgid "([back to exercise](strings-iterators.md))" msgstr "" #: src/exercises/day-2/solutions-afternoon.md:101 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: prefix_matches\n" "pub fn prefix_matches(prefix: &str, request_path: &str) -> bool {\n" " // ANCHOR_END: prefix_matches\n" " let prefixes = prefix.split('/');\n" " let request_paths = request_path\n" " .split('/')\n" " .map(|p| Some(p))\n" " .chain(std::iter::once(None));\n" "\n" " for (prefix, request_path) in prefixes.zip(request_paths) {\n" " match request_path {\n" " Some(request_path) => {\n" " if (prefix != \"*\") && (prefix != request_path) {\n" " return false;\n" " }\n" " }\n" " None => return false,\n" " }\n" " }\n" " true\n" "}\n" "\n" "// ANCHOR: unit-tests\n" "#[test]\n" "fn test_matches_without_wildcard() {\n" " assert!(prefix_matches(\"/v1/publishers\", \"/v1/publishers\"));\n" " assert!(prefix_matches(\"/v1/publishers\", \"/v1/publishers/abc-123\"));\n" " assert!(prefix_matches(\"/v1/publishers\", \"/v1/publishers/abc/books\"));\n" "\n" " assert!(!prefix_matches(\"/v1/publishers\", \"/v1\"));\n" " assert!(!prefix_matches(\"/v1/publishers\", \"/v1/publishersBooks\"));\n" " assert!(!prefix_matches(\"/v1/publishers\", \"/v1/parent/publishers\"));\n" "}\n" "\n" "#[test]\n" "fn test_matches_with_wildcard() {\n" " assert!(prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/foo/books\"\n" " ));\n" " assert!(prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/bar/books\"\n" " ));\n" " assert!(prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/foo/books/book1\"\n" " ));\n" "\n" " assert!(!prefix_matches(\"/v1/publishers/*/books\", \"/v1/publishers\"));\n" " assert!(!prefix_matches(\n" " \"/v1/publishers/*/books\",\n" " \"/v1/publishers/foo/booksByAuthor\"\n" " ));\n" "}\n" "// ANCHOR_END: unit-tests\n" "\n" "fn main() {}\n" "```" msgstr "" #: src/exercises/day-3/solutions-morning.md:1 msgid "# Day 3 Morning Exercise" msgstr "" #: src/exercises/day-3/solutions-morning.md:3 msgid "## A Simple GUI Library" msgstr "" #: src/exercises/day-3/solutions-morning.md:5 msgid "([back to exercise](simple-gui.md))" msgstr "" #: src/exercises/day-3/solutions-morning.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: setup\n" "pub trait Widget {\n" " /// Natural width of `self`.\n" " fn width(&self) -> usize;\n" "\n" " /// Draw the widget into a buffer.\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write);\n" "\n" " /// Draw the widget on standard output.\n" " fn draw(&self) {\n" " let mut buffer = String::new();\n" " self.draw_into(&mut buffer);\n" " println!(\"{buffer}\");\n" " }\n" "}\n" "\n" "pub struct Label {\n" " label: String,\n" "}\n" "\n" "impl Label {\n" " fn new(label: &str) -> Label {\n" " Label {\n" " label: label.to_owned(),\n" " }\n" " }\n" "}\n" "\n" "pub struct Button {\n" " label: Label,\n" " callback: Box,\n" "}\n" "\n" "impl Button {\n" " fn new(label: &str, callback: Box) -> Button {\n" " Button {\n" " label: Label::new(label),\n" " callback,\n" " }\n" " }\n" "}\n" "\n" "pub struct Window {\n" " title: String,\n" " widgets: Vec>,\n" "}\n" "\n" "impl Window {\n" " fn new(title: &str) -> Window {\n" " Window {\n" " title: title.to_owned(),\n" " widgets: Vec::new(),\n" " }\n" " }\n" "\n" " fn add_widget(&mut self, widget: Box) {\n" " self.widgets.push(widget);\n" " }\n" "\n" " fn inner_width(&self) -> usize {\n" " std::cmp::max(\n" " self.title.chars().count(),\n" " self.widgets.iter().map(|w| w.width()).max().unwrap_or(0),\n" " )\n" " }\n" "}\n" "\n" "// ANCHOR_END: setup\n" "\n" "// ANCHOR: Window-width\n" "impl Widget for Window {\n" " fn width(&self) -> usize {\n" " // ANCHOR_END: Window-width\n" " // Add 4 paddings for borders\n" " self.inner_width() + 4\n" " }\n" "\n" " // ANCHOR: Window-draw_into\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {\n" " // ANCHOR_END: Window-draw_into\n" " let mut inner = String::new();\n" " for widget in &self.widgets {\n" " widget.draw_into(&mut inner);\n" " }\n" "\n" " let inner_width = self.inner_width();\n" "\n" " // TODO: after learning about error handling, you can change\n" " // draw_into to return Result<(), std::fmt::Error>. Then use\n" " // the ?-operator here instead of .unwrap().\n" " writeln!(buffer, \"+-{:- usize {\n" " // ANCHOR_END: Button-width\n" " self.label.width() + 8 // add a bit of padding\n" " }\n" "\n" " // ANCHOR: Button-draw_into\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {\n" " // ANCHOR_END: Button-draw_into\n" " let width = self.width();\n" " let mut label = String::new();\n" " self.label.draw_into(&mut label);\n" "\n" " writeln!(buffer, \"+{:- usize {\n" " // ANCHOR_END: Label-width\n" " self.label\n" " .lines()\n" " .map(|line| line.chars().count())\n" " .max()\n" " .unwrap_or(0)\n" " }\n" "\n" " // ANCHOR: Label-draw_into\n" " fn draw_into(&self, buffer: &mut dyn std::fmt::Write) {\n" " // ANCHOR_END: Label-draw_into\n" " writeln!(buffer, \"{}\", &self.label).unwrap();\n" " }\n" "}\n" "\n" "// ANCHOR: main\n" "fn main() {\n" " let mut window = Window::new(\"Rust GUI Demo 1.23\");\n" " window.add_widget(Box::new(Label::new(\"This is a small text GUI demo.\")));\n" " window.add_widget(Box::new(Button::new(\n" " \"Click me!\",\n" " Box::new(|| println!(\"You clicked the button!\")),\n" " )));\n" " window.draw();\n" "}\n" "// ANCHOR_END: main\n" "```" msgstr "" #: src/exercises/day-3/solutions-afternoon.md:1 msgid "# Day 3 Afternoon Exercises" msgstr "" #: src/exercises/day-3/solutions-afternoon.md:3 msgid "## Safe FFI Wrapper" msgstr "" #: src/exercises/day-3/solutions-afternoon.md:5 msgid "([back to exercise](safe-ffi-wrapper.md))" msgstr "" #: src/exercises/day-3/solutions-afternoon.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: ffi\n" "mod ffi {\n" " use std::os::raw::{c_char, c_int};\n" " #[cfg(not(target_os = \"macos\"))]\n" " use std::os::raw::{c_long, c_ulong, c_ushort};\n" "\n" " // Opaque type. See https://doc.rust-lang.org/nomicon/ffi.html.\n" " #[repr(C)]\n" " pub struct DIR {\n" " _data: [u8; 0],\n" " _marker: core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,\n" " }\n" "\n" " // Layout as per readdir(3) and definitions in /usr/include/x86_64-linux-gnu.\n" " #[cfg(not(target_os = \"macos\"))]\n" " #[repr(C)]\n" " pub struct dirent {\n" " pub d_ino: c_long,\n" " pub d_off: c_ulong,\n" " pub d_reclen: c_ushort,\n" " pub d_type: c_char,\n" " pub d_name: [c_char; 256],\n" " }\n" "\n" " // Layout as per man entry for dirent\n" " #[cfg(target_os = \"macos\")]\n" " #[repr(C)]\n" " pub struct dirent {\n" " pub d_ino: u64,\n" " pub d_seekoff: u64,\n" " pub d_reclen: u16,\n" " pub d_namlen: u16,\n" " pub d_type: u8,\n" " pub d_name: [c_char; 1024],\n" " }\n" "\n" " extern \"C\" {\n" " pub fn opendir(s: *const c_char) -> *mut DIR;\n" " pub fn readdir(s: *mut DIR) -> *const dirent;\n" " pub fn closedir(s: *mut DIR) -> c_int;\n" " }\n" "}\n" "\n" "use std::ffi::{CStr, CString, OsStr, OsString};\n" "use std::os::unix::ffi::OsStrExt;\n" "\n" "#[derive(Debug)]\n" "struct DirectoryIterator {\n" " path: CString,\n" " dir: *mut ffi::DIR,\n" "}\n" "// ANCHOR_END: ffi\n" "\n" "// ANCHOR: DirectoryIterator\n" "impl DirectoryIterator {\n" " fn new(path: &str) -> Result {\n" " // Call opendir and return a Ok value if that worked,\n" " // otherwise return Err with a message.\n" " // ANCHOR_END: DirectoryIterator\n" " let path = CString::new(path).map_err(|err| format!(\"Invalid path: {err}\"))?;\n" " // SAFETY: path.as_ptr() cannot be NULL.\n" " let dir = unsafe { ffi::opendir(path.as_ptr()) };\n" " if dir.is_null() {\n" " Err(format!(\"Could not open {:?}\", path))\n" " } else {\n" " Ok(DirectoryIterator { path, dir })\n" " }\n" " }\n" "}\n" "\n" "// ANCHOR: Iterator\n" "impl Iterator for DirectoryIterator {\n" " type Item = OsString;\n" " fn next(&mut self) -> Option {\n" " // Keep calling readdir until we get a NULL pointer back.\n" " // ANCHOR_END: Iterator\n" " // SAFETY: self.dir is never NULL.\n" " let dirent = unsafe { ffi::readdir(self.dir) };\n" " if dirent.is_null() {\n" " // We have reached the end of the directory.\n" " return None;\n" " }\n" " // SAFETY: dirent is not NULL and dirent.d_name is NUL\n" " // terminated.\n" " let d_name = unsafe { CStr::from_ptr((*dirent).d_name.as_ptr()) };\n" " let os_str = OsStr::from_bytes(d_name.to_bytes());\n" " Some(os_str.to_owned())\n" " }\n" "}\n" "\n" "// ANCHOR: Drop\n" "impl Drop for DirectoryIterator {\n" " fn drop(&mut self) {\n" " // Call closedir as needed.\n" " // ANCHOR_END: Drop\n" " if !self.dir.is_null() {\n" " // SAFETY: self.dir is not NULL.\n" " if unsafe { ffi::closedir(self.dir) } != 0 {\n" " panic!(\"Could not close {:?}\", self.path);\n" " }\n" " }\n" " }\n" "}\n" "\n" "// ANCHOR: main\n" "fn main() -> Result<(), String> {\n" " let iter = DirectoryIterator::new(\".\")?;\n" " println!(\"files: {:#?}\", iter.collect::>());\n" " Ok(())\n" "}\n" "// ANCHOR_END: main\n" "\n" "#[cfg(test)]\n" "mod tests {\n" " use super::*;\n" " use std::error::Error;\n" "\n" " #[test]\n" " fn test_nonexisting_directory() {\n" " let iter = DirectoryIterator::new(\"no-such-directory\");\n" " assert!(iter.is_err());\n" " }\n" "\n" " #[test]\n" " fn test_empty_directory() -> Result<(), Box> {\n" " let tmp = tempfile::TempDir::new()?;\n" " let iter = DirectoryIterator::new(\n" " tmp.path().to_str().ok_or(\"Non UTF-8 character in path\")?,\n" " )?;\n" " let mut entries = iter.collect::>();\n" " entries.sort();\n" " assert_eq!(entries, &[\".\", \"..\"]);\n" " Ok(())\n" " }\n" "\n" " #[test]\n" " fn test_nonempty_directory() -> Result<(), Box> {\n" " let tmp = tempfile::TempDir::new()?;\n" " std::fs::write(tmp.path().join(\"foo.txt\"), \"The Foo Diaries\\n\")?;\n" " std::fs::write(tmp.path().join(\"bar.png\"), \"\\n\")?;\n" " std::fs::write(tmp.path().join(\"crab.rs\"), \"//! Crab\\n\")?;\n" " let iter = DirectoryIterator::new(\n" " tmp.path().to_str().ok_or(\"Non UTF-8 character in path\")?,\n" " )?;\n" " let mut entries = iter.collect::>();\n" " entries.sort();\n" " assert_eq!(entries, &[\".\", \"..\", \"bar.png\", \"crab.rs\", \"foo.txt\"]);\n" " Ok(())\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/solutions-morning.md:1 msgid "# Bare Metal Rust Morning Exercise" msgstr "" #: src/exercises/bare-metal/solutions-morning.md:3 msgid "## Compass" msgstr "" #: src/exercises/bare-metal/solutions-morning.md:5 msgid "([back to exercise](compass.md))" msgstr "" #: src/exercises/bare-metal/solutions-morning.md:7 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: top\n" "#![no_main]\n" "#![no_std]\n" "\n" "extern crate panic_halt as _;\n" "\n" "use core::fmt::Write;\n" "use cortex_m_rt::entry;\n" "// ANCHOR_END: top\n" "use core::cmp::{max, min};\n" "use lsm303agr::{AccelOutputDataRate, Lsm303agr, MagOutputDataRate};\n" "use microbit::display::blocking::Display;\n" "use microbit::hal::prelude::*;\n" "use microbit::hal::twim::Twim;\n" "use microbit::hal::uarte::{Baudrate, Parity, Uarte};\n" "use microbit::hal::Timer;\n" "use microbit::pac::twim0::frequency::FREQUENCY_A;\n" "use microbit::Board;\n" "\n" "const COMPASS_SCALE: i32 = 30000;\n" "const ACCELEROMETER_SCALE: i32 = 700;\n" "\n" "// ANCHOR: main\n" "#[entry]\n" "fn main() -> ! {\n" " let board = Board::take().unwrap();\n" "\n" " // Configure serial port.\n" " let mut serial = Uarte::new(\n" " board.UARTE0,\n" " board.uart.into(),\n" " Parity::EXCLUDED,\n" " Baudrate::BAUD115200,\n" " );\n" "\n" " // Set up the I2C controller and Inertial Measurement Unit.\n" " // ANCHOR_END: main\n" " writeln!(serial, \"Setting up IMU...\").unwrap();\n" " let i2c = Twim::new(board.TWIM0, board.i2c_internal.into(), FREQUENCY_A::K100);\n" " let mut imu = Lsm303agr::new_with_i2c(i2c);\n" " imu.init().unwrap();\n" " imu.set_mag_odr(MagOutputDataRate::Hz50).unwrap();\n" " imu.set_accel_odr(AccelOutputDataRate::Hz50).unwrap();\n" " let mut imu = imu.into_mag_continuous().ok().unwrap();\n" "\n" " // Set up display and timer.\n" " let mut timer = Timer::new(board.TIMER0);\n" " let mut display = Display::new(board.display_pins);\n" "\n" " let mut mode = Mode::Compass;\n" " let mut button_pressed = false;\n" "\n" " // ANCHOR: loop\n" " writeln!(serial, \"Ready.\").unwrap();\n" "\n" " loop {\n" " // Read compass data and log it to the serial port.\n" " // ANCHOR_END: loop\n" " while !(imu.mag_status().unwrap().xyz_new_data\n" " && imu.accel_status().unwrap().xyz_new_data)\n" " {}\n" " let compass_reading = imu.mag_data().unwrap();\n" " let accelerometer_reading = imu.accel_data().unwrap();\n" " writeln!(\n" " serial,\n" " \"{},{},{}\\t{},{},{}\",\n" " compass_reading.x,\n" " compass_reading.y,\n" " compass_reading.z,\n" " accelerometer_reading.x,\n" " accelerometer_reading.y,\n" " accelerometer_reading.z,\n" " )\n" " .unwrap();\n" "\n" " let mut image = [[0; 5]; 5];\n" " let (x, y) = match mode {\n" " Mode::Compass => (\n" " scale(-compass_reading.x, -COMPASS_SCALE, COMPASS_SCALE, 0, 4) as usize,\n" " scale(compass_reading.y, -COMPASS_SCALE, COMPASS_SCALE, 0, 4) as usize,\n" " ),\n" " Mode::Accelerometer => (\n" " scale(\n" " accelerometer_reading.x,\n" " -ACCELEROMETER_SCALE,\n" " ACCELEROMETER_SCALE,\n" " 0,\n" " 4,\n" " ) as usize,\n" " scale(\n" " -accelerometer_reading.y,\n" " -ACCELEROMETER_SCALE,\n" " ACCELEROMETER_SCALE,\n" " 0,\n" " 4,\n" " ) as usize,\n" " ),\n" " };\n" " image[y][x] = 255;\n" " display.show(&mut timer, image, 100);\n" "\n" " // If button A is pressed, switch to the next mode and briefly blink all LEDs on.\n" " if board.buttons.button_a.is_low().unwrap() {\n" " if !button_pressed {\n" " mode = mode.next();\n" " display.show(&mut timer, [[255; 5]; 5], 200);\n" " }\n" " button_pressed = true;\n" " } else {\n" " button_pressed = false;\n" " }\n" " }\n" "}\n" "\n" "#[derive(Copy, Clone, Debug, Eq, PartialEq)]\n" "enum Mode {\n" " Compass,\n" " Accelerometer,\n" "}\n" "\n" "impl Mode {\n" " fn next(self) -> Self {\n" " match self {\n" " Self::Compass => Self::Accelerometer,\n" " Self::Accelerometer => Self::Compass,\n" " }\n" " }\n" "}\n" "\n" "fn scale(value: i32, min_in: i32, max_in: i32, min_out: i32, max_out: i32) -> i32 {\n" " let range_in = max_in - min_in;\n" " let range_out = max_out - min_out;\n" " cap(\n" " min_out + range_out * (value - min_in) / range_in,\n" " min_out,\n" " max_out,\n" " )\n" "}\n" "\n" "fn cap(value: i32, min_value: i32, max_value: i32) -> i32 {\n" " max(min_value, min(value, max_value))\n" "}\n" "```" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:1 msgid "# Bare Metal Rust Afternoon" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:3 msgid "## RTC driver" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:5 msgid "([back to exercise](rtc.md))" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:7 msgid "`main.rs`:" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:9 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: top\n" "#![no_main]\n" "#![no_std]\n" "\n" "mod exceptions;\n" "mod logger;\n" "mod pl011;\n" "// ANCHOR_END: top\n" "mod pl031;\n" "\n" "use crate::pl031::Rtc;\n" "use arm_gic::gicv3::{IntId, Trigger};\n" "use arm_gic::{irq_enable, wfi};\n" "use chrono::{TimeZone, Utc};\n" "use core::hint::spin_loop;\n" "// ANCHOR: imports\n" "use crate::pl011::Uart;\n" "use arm_gic::gicv3::GicV3;\n" "use core::panic::PanicInfo;\n" "use log::{error, info, trace, LevelFilter};\n" "use smccc::psci::system_off;\n" "use smccc::Hvc;\n" "\n" "/// Base addresses of the GICv3.\n" "const GICD_BASE_ADDRESS: *mut u64 = 0x800_0000 as _;\n" "const GICR_BASE_ADDRESS: *mut u64 = 0x80A_0000 as _;\n" "\n" "/// Base address of the primary PL011 UART.\n" "const PL011_BASE_ADDRESS: *mut u32 = 0x900_0000 as _;\n" "// ANCHOR_END: imports\n" "\n" "/// Base address of the PL031 RTC.\n" "const PL031_BASE_ADDRESS: *mut u32 = 0x901_0000 as _;\n" "/// The IRQ used by the PL031 RTC.\n" "const PL031_IRQ: IntId = IntId::spi(2);\n" "\n" "// ANCHOR: main\n" "#[no_mangle]\n" "extern \"C\" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {\n" " // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,\n" " // and nothing else accesses that address range.\n" " let uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };\n" " logger::init(uart, LevelFilter::Trace).unwrap();\n" "\n" " info!(\"main({:#x}, {:#x}, {:#x}, {:#x})\", x0, x1, x2, x3);\n" "\n" " // Safe because `GICD_BASE_ADDRESS` and `GICR_BASE_ADDRESS` are the base\n" " // addresses of a GICv3 distributor and redistributor respectively, and\n" " // nothing else accesses those address ranges.\n" " let mut gic = unsafe { GicV3::new(GICD_BASE_ADDRESS, GICR_BASE_ADDRESS) };\n" " gic.setup();\n" " // ANCHOR_END: main\n" "\n" " // Safe because `PL031_BASE_ADDRESS` is the base address of a PL031 device,\n" " // and nothing else accesses that address range.\n" " let mut rtc = unsafe { Rtc::new(PL031_BASE_ADDRESS) };\n" " let timestamp = rtc.read();\n" " let time = Utc.timestamp_opt(timestamp.into(), 0).unwrap();\n" " info!(\"RTC: {time}\");\n" "\n" " GicV3::set_priority_mask(0xff);\n" " gic.set_interrupt_priority(PL031_IRQ, 0x80);\n" " gic.set_trigger(PL031_IRQ, Trigger::Level);\n" " irq_enable();\n" " gic.enable_interrupt(PL031_IRQ, true);\n" "\n" " // Wait for 3 seconds, without interrupts.\n" " let target = timestamp + 3;\n" " rtc.set_match(target);\n" " info!(\n" " \"Waiting for {}\",\n" " Utc.timestamp_opt(target.into(), 0).unwrap()\n" " );\n" " trace!(\n" " \"matched={}, interrupt_pending={}\",\n" " rtc.matched(),\n" " rtc.interrupt_pending()\n" " );\n" " while !rtc.matched() {\n" " spin_loop();\n" " }\n" " trace!(\n" " \"matched={}, interrupt_pending={}\",\n" " rtc.matched(),\n" " rtc.interrupt_pending()\n" " );\n" " info!(\"Finished waiting\");\n" "\n" " // Wait another 3 seconds for an interrupt.\n" " let target = timestamp + 6;\n" " info!(\n" " \"Waiting for {}\",\n" " Utc.timestamp_opt(target.into(), 0).unwrap()\n" " );\n" " rtc.set_match(target);\n" " rtc.clear_interrupt();\n" " rtc.enable_interrupt(true);\n" " trace!(\n" " \"matched={}, interrupt_pending={}\",\n" " rtc.matched(),\n" " rtc.interrupt_pending()\n" " );\n" " while !rtc.interrupt_pending() {\n" " wfi();\n" " }\n" " trace!(\n" " \"matched={}, interrupt_pending={}\",\n" " rtc.matched(),\n" " rtc.interrupt_pending()\n" " );\n" " info!(\"Finished waiting\");\n" "\n" " // ANCHOR: main_end\n" " system_off::().unwrap();\n" "}\n" "\n" "#[panic_handler]\n" "fn panic(info: &PanicInfo) -> ! {\n" " error!(\"{info}\");\n" " system_off::().unwrap();\n" " loop {}\n" "}\n" "// ANCHOR_END: main_end\n" "```" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:149 msgid "`pl031.rs`:" msgstr "" #: src/exercises/bare-metal/solutions-afternoon.md:151 msgid "" "```rust\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "use core::ptr::{addr_of, addr_of_mut};\n" "\n" "#[repr(C, align(4))]\n" "struct Registers {\n" " /// Data register\n" " dr: u32,\n" " /// Match register\n" " mr: u32,\n" " /// Load register\n" " lr: u32,\n" " /// Control register\n" " cr: u8,\n" " _reserved0: [u8; 3],\n" " /// Interrupt Mask Set or Clear register\n" " imsc: u8,\n" " _reserved1: [u8; 3],\n" " /// Raw Interrupt Status\n" " ris: u8,\n" " _reserved2: [u8; 3],\n" " /// Masked Interrupt Status\n" " mis: u8,\n" " _reserved3: [u8; 3],\n" " /// Interrupt Clear Register\n" " icr: u8,\n" " _reserved4: [u8; 3],\n" "}\n" "\n" "/// Driver for a PL031 real-time clock.\n" "#[derive(Debug)]\n" "pub struct Rtc {\n" " registers: *mut Registers,\n" "}\n" "\n" "impl Rtc {\n" " /// Constructs a new instance of the RTC driver for a PL031 device at the\n" " /// given base address.\n" " ///\n" " /// # Safety\n" " ///\n" " /// The given base address must point to the MMIO control registers of a\n" " /// PL031 device, which must be mapped into the address space of the process\n" " /// as device memory and not have any other aliases.\n" " pub unsafe fn new(base_address: *mut u32) -> Self {\n" " Self {\n" " registers: base_address as *mut Registers,\n" " }\n" " }\n" "\n" " /// Reads the current RTC value.\n" " pub fn read(&self) -> u32 {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL031 device which is appropriately mapped.\n" " unsafe { addr_of!((*self.registers).dr).read_volatile() }\n" " }\n" "\n" " /// Writes a match value. When the RTC value matches this then an interrupt\n" " /// will be generated (if it is enabled).\n" " pub fn set_match(&mut self, value: u32) {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL031 device which is appropriately mapped.\n" " unsafe { addr_of_mut!((*self.registers).mr).write_volatile(value) }\n" " }\n" "\n" " /// Returns whether the match register matches the RTC value, whether or not\n" " /// the interrupt is enabled.\n" " pub fn matched(&self) -> bool {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL031 device which is appropriately mapped.\n" " let ris = unsafe { addr_of!((*self.registers).ris).read_volatile() };\n" " (ris & 0x01) != 0\n" " }\n" "\n" " /// Returns whether there is currently an interrupt pending.\n" " ///\n" " /// This should be true iff `matched` returns true and the interrupt is\n" " /// masked.\n" " pub fn interrupt_pending(&self) -> bool {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL031 device which is appropriately mapped.\n" " let ris = unsafe { addr_of!((*self.registers).mis).read_volatile() };\n" " (ris & 0x01) != 0\n" " }\n" "\n" " /// Sets or clears the interrupt mask.\n" " ///\n" " /// When the mask is true the interrupt is enabled; when it is false the\n" " /// interrupt is disabled.\n" " pub fn enable_interrupt(&mut self, mask: bool) {\n" " let imsc = if mask { 0x01 } else { 0x00 };\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL031 device which is appropriately mapped.\n" " unsafe { addr_of_mut!((*self.registers).imsc).write_volatile(imsc) }\n" " }\n" "\n" " /// Clears a pending interrupt, if any.\n" " pub fn clear_interrupt(&mut self) {\n" " // Safe because we know that self.registers points to the control\n" " // registers of a PL031 device which is appropriately mapped.\n" " unsafe { addr_of_mut!((*self.registers).icr).write_volatile(0x01) }\n" " }\n" "}\n" "\n" "// Safe because it just contains a pointer to device memory, which can be\n" "// accessed from any context.\n" "unsafe impl Send for Rtc {}\n" "```" msgstr "" #: src/exercises/concurrency/solutions-morning.md:1 msgid "# Concurrency Morning Exercise" msgstr "" #: src/exercises/concurrency/solutions-morning.md:3 msgid "## Dining Philosophers" msgstr "" #: src/exercises/concurrency/solutions-morning.md:5 msgid "([back to exercise](dining-philosophers.md))" msgstr "" #: src/exercises/concurrency/solutions-morning.md:7 msgid "" "```rust\n" "// Copyright 2022 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: Philosopher\n" "use std::sync::{mpsc, Arc, Mutex};\n" "use std::thread;\n" "use std::time::Duration;\n" "\n" "struct Fork;\n" "\n" "struct Philosopher {\n" " name: String,\n" " // ANCHOR_END: Philosopher\n" " left_fork: Arc>,\n" " right_fork: Arc>,\n" " thoughts: mpsc::SyncSender,\n" "}\n" "\n" "// ANCHOR: Philosopher-think\n" "impl Philosopher {\n" " fn think(&self) {\n" " self.thoughts\n" " .send(format!(\"Eureka! {} has a new idea!\", &self.name))\n" " .unwrap();\n" " }\n" " // ANCHOR_END: Philosopher-think\n" "\n" " // ANCHOR: Philosopher-eat\n" " fn eat(&self) {\n" " // ANCHOR_END: Philosopher-eat\n" " println!(\"{} is trying to eat\", &self.name);\n" " let left = self.left_fork.lock().unwrap();\n" " let right = self.right_fork.lock().unwrap();\n" "\n" " // ANCHOR: Philosopher-eat-end\n" " println!(\"{} is eating...\", &self.name);\n" " thread::sleep(Duration::from_millis(10));\n" " }\n" "}\n" "\n" "static PHILOSOPHERS: &[&str] =\n" " &[\"Socrates\", \"Plato\", \"Aristotle\", \"Thales\", \"Pythagoras\"];\n" "\n" "fn main() {\n" " // ANCHOR_END: Philosopher-eat-end\n" " let (tx, rx) = mpsc::sync_channel(10);\n" "\n" " let forks = (0..PHILOSOPHERS.len())\n" " .map(|_| Arc::new(Mutex::new(Fork)))\n" " .collect::>();\n" "\n" " for i in 0..forks.len() {\n" " let tx = tx.clone();\n" " let mut left_fork = forks[i].clone();\n" " let mut right_fork = forks[(i + 1) % forks.len()].clone();\n" "\n" " // To avoid a deadlock, we have to break the symmetry\n" " // somewhere. This will swap the forks without deinitializing\n" " // either of them.\n" " if i == forks.len() - 1 {\n" " std::mem::swap(&mut left_fork, &mut right_fork);\n" " }\n" "\n" " let philosopher = Philosopher {\n" " name: PHILOSOPHERS[i].to_string(),\n" " thoughts: tx,\n" " left_fork,\n" " right_fork,\n" " };\n" "\n" " thread::spawn(move || {\n" " for _ in 0..100 {\n" " philosopher.eat();\n" " philosopher.think();\n" " }\n" " });\n" " }\n" "\n" " drop(tx);\n" " for thought in rx {\n" " println!(\"{thought}\");\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:1 msgid "# Concurrency Afternoon Exercise" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:3 msgid "## Dining Philosophers - Async" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:5 msgid "([back to exercise](dining-philosophers-async.md))" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:7 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: Philosopher\n" "use std::sync::Arc;\n" "use tokio::time;\n" "use tokio::sync::mpsc::{self, Sender};\n" "use tokio::sync::Mutex;\n" "\n" "struct Fork;\n" "\n" "struct Philosopher {\n" " name: String,\n" " // ANCHOR_END: Philosopher\n" " left_fork: Arc>,\n" " right_fork: Arc>,\n" " thoughts: Sender,\n" "}\n" "\n" "// ANCHOR: Philosopher-think\n" "impl Philosopher {\n" " async fn think(&self) {\n" " self.thoughts\n" " .send(format!(\"Eureka! {} has a new idea!\", &self.name)).await\n" " .unwrap();\n" " }\n" " // ANCHOR_END: Philosopher-think\n" "\n" " // ANCHOR: Philosopher-eat\n" " async fn eat(&self) {\n" " // Pick up forks...\n" " // ANCHOR_END: Philosopher-eat\n" " let _first_lock = self.left_fork.lock().await;\n" " // Add a delay before picking the second fork to allow the execution\n" " // to transfer to another task\n" " time::sleep(time::Duration::from_millis(1)).await;\n" " let _second_lock = self.right_fork.lock().await;\n" "\n" " // ANCHOR: Philosopher-eat-body\n" " println!(\"{} is eating...\", &self.name);\n" " time::sleep(time::Duration::from_millis(5)).await;\n" " // ANCHOR_END: Philosopher-eat-body\n" "\n" " // The locks are dropped here\n" " // ANCHOR: Philosopher-eat-end\n" " }\n" "}\n" "\n" "static PHILOSOPHERS: &[&str] =\n" " &[\"Socrates\", \"Plato\", \"Aristotle\", \"Thales\", \"Pythagoras\"];\n" "\n" "#[tokio::main]\n" "async fn main() {\n" " // ANCHOR_END: Philosopher-eat-end\n" " // Create forks\n" " let mut forks = vec![];\n" " (0..PHILOSOPHERS.len()).for_each(|_| forks.push(Arc::new(Mutex::new(Fork))));\n" "\n" " // Create philosophers\n" " let (philosophers, mut rx) = {\n" " let mut philosophers = vec![];\n" " let (tx, rx) = mpsc::channel(10);\n" " for (i, name) in PHILOSOPHERS.iter().enumerate() {\n" " let left_fork = forks[i].clone();\n" " let right_fork = forks[(i + 1) % PHILOSOPHERS.len()].clone();\n" " philosophers.push(Philosopher {\n" " name: name.to_string(),\n" " left_fork: if i % 2 == 0 { left_fork.clone() } else { right_fork.clone() },\n" " right_fork: if i % 2 == 0 { right_fork } else { left_fork },\n" " thoughts: tx.clone(),\n" " });\n" " }\n" " (philosophers, rx)\n" " // tx is dropped here, so we don't need to explicitly drop it later\n" " };\n" "\n" " // Make them think and eat\n" " for phil in philosophers {\n" " tokio::spawn(async move {\n" " for _ in 0..100 {\n" " phil.think().await;\n" " phil.eat().await;\n" " }\n" " });\n" "\n" " }\n" "\n" " // Output their thoughts\n" " while let Some(thought) = rx.recv().await {\n" " println!(\"Here is a thought: {thought}\");\n" " }\n" "}\n" "```" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:113 msgid "## Broadcast Chat Application" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:115 msgid "([back to exercise](chat-app.md))" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:119 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: setup\n" "use futures_util::sink::SinkExt;\n" "use std::error::Error;\n" "use std::net::SocketAddr;\n" "use tokio::net::{TcpListener, TcpStream};\n" "use tokio::sync::broadcast::{channel, Sender};\n" "use tokio_websockets::{Message, ServerBuilder, WebsocketStream};\n" "// ANCHOR_END: setup\n" "\n" "// ANCHOR: handle_connection\n" "async fn handle_connection(\n" " addr: SocketAddr,\n" " mut ws_stream: WebsocketStream,\n" " bcast_tx: Sender,\n" ") -> Result<(), Box> {\n" " // ANCHOR_END: handle_connection\n" "\n" " ws_stream\n" " .send(Message::text(\"Welcome to chat! Type a message\".into()))\n" " .await?;\n" " let mut bcast_rx = bcast_tx.subscribe();\n" "\n" " // A continuous loop for concurrently performing two tasks: (1) receiving\n" " // messages from `ws_stream` and broadcasting them, and (2) receiving\n" " // messages on `bcast_rx` and sending them to the client.\n" " loop {\n" " tokio::select! {\n" " incoming = ws_stream.next() => {\n" " match incoming {\n" " Some(Ok(msg)) => {\n" " let msg = msg.as_text()?;\n" " println!(\"From client {addr:?} {msg:?}\");\n" " bcast_tx.send(msg.into())?;\n" " }\n" " Some(Err(err)) => return Err(err.into()),\n" " None => return Ok(()),\n" " }\n" " }\n" " msg = bcast_rx.recv() => {\n" " ws_stream.send(Message::text(msg?)).await?;\n" " }\n" " }\n" " }\n" " // ANCHOR: main\n" "}\n" "\n" "#[tokio::main]\n" "async fn main() -> Result<(), Box> {\n" " let (bcast_tx, _) = channel(16);\n" "\n" " let listener = TcpListener::bind(\"127.0.0.1:2000\").await?;\n" " println!(\"listening on port 2000\");\n" "\n" " loop {\n" " let (socket, addr) = listener.accept().await?;\n" " println!(\"New connection from {addr:?}\");\n" " let bcast_tx = bcast_tx.clone();\n" " tokio::spawn(async move {\n" " // Wrap the raw TCP stream into a websocket.\n" " let ws_stream = ServerBuilder::new().accept(socket).await?;\n" "\n" " handle_connection(addr, ws_stream, bcast_tx).await\n" " });\n" " }\n" "}\n" "// ANCHOR_END: main\n" "```" msgstr "" #: src/exercises/concurrency/solutions-afternoon.md:204 msgid "" "```rust,compile_fail\n" "// Copyright 2023 Google LLC\n" "//\n" "// Licensed under the Apache License, Version 2.0 (the \"License\");\n" "// you may not use this file except in compliance with the License.\n" "// You may obtain a copy of the License at\n" "//\n" "// http://www.apache.org/licenses/LICENSE-2.0\n" "//\n" "// Unless required by applicable law or agreed to in writing, software\n" "// distributed under the License is distributed on an \"AS IS\" BASIS,\n" "// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" "// See the License for the specific language governing permissions and\n" "// limitations under the License.\n" "\n" "// ANCHOR: setup\n" "use futures_util::SinkExt;\n" "use http::Uri;\n" "use tokio::io::{AsyncBufReadExt, BufReader};\n" "use tokio_websockets::{ClientBuilder, Message};\n" "\n" "#[tokio::main]\n" "async fn main() -> Result<(), tokio_websockets::Error> {\n" " let mut ws_stream = ClientBuilder::from_uri(Uri::from_static(\"ws://127.0.0.1:2000\"))\n" " .connect()\n" " .await?;\n" "\n" " let stdin = tokio::io::stdin();\n" " let mut stdin = BufReader::new(stdin);\n" "\n" " // ANCHOR_END: setup\n" " // Continuous loop for concurrently sending and receiving messages.\n" " loop {\n" " let mut line = String::new();\n" " tokio::select! {\n" " incoming = ws_stream.next() => {\n" " match incoming {\n" " Some(Ok(msg)) => println!(\"From server: {}\", msg.as_text()?),\n" " Some(Err(err)) => return Err(err.into()),\n" " None => return Ok(()),\n" " }\n" " }\n" " res = stdin.read_line(&mut line) => {\n" " match res {\n" " Ok(0) => return Ok(()),\n" " Ok(_) => ws_stream.send(Message::text(line.trim_end().to_string())).await?,\n" " Err(err) => return Err(err.into()),\n" " }\n" " }\n" "\n" " }\n" " }\n" "}\n" "```" msgstr ""