rust-std-docs

Rust 標準函式庫 (std 1.99.1)

概述

此技能收錄了官方 std 文件中容易出錯的部分：恐慌、令人驚訝的預設值、平台注意事項、不建議使用的 API 以及取代舊慣例的新穩定 API。每位 Rust 開發者都知道的基礎知識則不包含在內。references/ 中的每個說法結尾都附有來源文件的 URL，方便您重新開啟頁面。https://doc.rust-lang.org/std/index.html

涵蓋版本

Rust std 1.99.1，穩定版頻道。版本號（"Since"）來自各頁面。標記為 nightly 的 API 在穩定版 1.99.1 上無法使用，請勿建議。在使用於專案最低 Rust 版本之後才穩定的 API 之前，請先檢查該版本。

如何使用

1. 在下方表格中找出您撰寫或審查程式碼所屬的領域。
2. 只開啟對應的參考文件。每個文件都獨立成篇，開頭附有目錄。
3. 套用其預設規則。僅在所述條件成立時，才採取例外措施。
4. 在審查中，也請查看文件結尾的「舊模式」表格，並建議替代寫法。

最有價值的規則

• Command::output() 和 status() 在非零退出碼時會回傳 Ok。務必檢查 status.success()。https://doc.rust-lang.org/std/process/struct.Command.html
• Path::join 或 PathBuf::push 若傳入絕對路徑，會取代整個基底路徑。https://doc.rust-lang.org/std/path/struct.PathBuf.html#method.push
• env::set_var 是 unsafe 的，且在執行緒啟動後（Windows 除外）是不健全的。請改用 Command::env 來設定子行程的環境變數。https://doc.rust-lang.org/std/env/fn.set_var.html
• 在 BufWriter 被丟棄前呼叫 flush()，因為 drop 會忽略 flush 錯誤。https://doc.rust-lang.org/std/io/struct.BufWriter.html
• 僅使用 OpenOptions::write(true) 而未加上 truncate(true) 會保留舊的檔案尾端內容。請使用 File::create_new 進行原子創建。https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.write
• 優先使用 try_exists() 而非 exists()，因為 exists() 會將錯誤隱藏為 false。https://doc.rust-lang.org/std/path/struct.Path.html#method.try_exists
• 不會失敗的一次性初始化使用 LazyLock (1.80)。會恐慌的 LazyLock 初始化會永久毒化它。可能會失敗的初始化使用 OnceLock (1.70)：先載入，在外部處理錯誤，然後再使用 get_or_init 或 set，絕對不要使用 LazyLock<Result<..>>。https://doc.rust-lang.org/std/sync/struct.LazyLock.html#poisoning https://doc.rust-lang.org/std/sync/struct.OnceLock.html#method.get_or_init
• thread::scope (1.63) 允許在執行緒中借用區域變數，無需 Arc 或 'static。https://doc.rust-lang.org/std/thread/fn.scope.html
• recv() 迴圈只有在每個 Sender 都被丟棄時才會結束。請丟棄原始的 tx。https://doc.rust-lang.org/std/sync/mpsc/index.html
• 使用 Arc::into_inner，而非 Arc::try_unwrap(..).ok()，當錯誤的 Arc 被丟棄時。https://doc.rust-lang.org/std/sync/struct.Arc.html
• unwrap_or(f())、ok_or(..) 和 map_or(..) 會立即求值其引數。對於函式呼叫，請使用 _else 形式的版本。https://doc.rust-lang.org/std/option/enum.Option.html#method.unwrap_or
• 撰寫 expect 訊息時，描述「應該」成立的情況。https://doc.rust-lang.org/std/error/index.html#common-message-styles
• 對包含 Result 項目的迭代器使用 flatten() 會靜默地丟棄錯誤。請收集為 Result<Vec<_>, _>。https://doc.rust-lang.org/std/result/index.html#iterating-over-result
• 使用 extract_if (Vec 1.87, HashMap/HashSet 1.88, BTreeMap 1.91) 來移除並保留符合條件的項目。如果迭代器在被耗盡前就被丟棄或短路，未造訪的元素會留在集合中且永遠不會被提取。https://doc.rust-lang.org/std/vec/struct.Vec.html#method.extract_if
• 對浮點數排序使用 sort_unstable_by(|a, b| a.total_cmp(b))，或在需要穩定排序時使用 sort_by。total_cmp 的順序為：-NaN, -inf, 負數, -0.0, +0.0, 正數, +inf, +NaN，因此 NaN 會根據其符號移到某一端，而 -0.0 會排在 +0.0 之前。https://doc.rust-lang.org/std/primitive.f64.html#method.total_cmp
• 字串切片使用字節索引，若位於字符邊界上則會恐慌。請使用 get(..) 或 floor_char_boundary (1.91)。https://doc.rust-lang.org/std/string/struct.String.html
• 在單一表達式中執行 CString::new(..).unwrap().as_ptr() 會產生懸置指標。請先繫結 CString。https://doc.rust-lang.org/std/ffi/struct.CString.html
• 使用 Instant 測量時間。SystemTime::elapsed 回傳 Result，因為時鐘可能倒轉。https://doc.rust-lang.org/std/time/struct.SystemTime.html
• 實作 From，永不實作 Into。使用 TryFrom 來取代有損轉換的 as。https://doc.rust-lang.org/std/convert/trait.From.html
• 明確選擇溢位行為：checked_*、strict_* (1.91)、saturating_*、wrapping_*。https://doc.rust-lang.org/std/primitive.i32.html#method.strict_add
• 避免使用 transmute。請改用 from_le_bytes、as_bytes、addr()、型別轉換等。https://doc.rust-lang.org/std/mem/fn.transmute.html#alternatives

參考文件

檔案	涵蓋內容
references/collections.md	Vec, 切片, 陣列, VecDeque, BinaryHeap, HashMap/HashSet, entry API, BTreeMap, Hash
references/option-result-error.md	unwrap/expect, 急切求值 vs 延遲求值組合子, 較新的 Option/Result 方法, Error 實作, ExitCode, 恐慌
references/iterators.md	鏈式呼叫, 非終止與溢位, Peekable, from_fn, successors, 實作 Iterator
references/ownership-smart-pointers.md	Box, Rc, Weak, Cell, RefCell, OnceCell, LazyCell, Cow, mem::take, Pin
references/concurrency.md	Arc, Mutex, RwLock, 毒化, OnceLock, LazyLock, Condvar, mpsc, 執行緒, scope, 原子操作
references/strings-formatting.md	String/str 索引, 大小寫, format 語法, Display/Debug 實作, OsString, CString
references/io-fs-path.md	BufReader/BufWriter, OpenOptions, TOCTOU, Read/Write/BufRead, io::Error, Path/PathBuf
references/process-env-net-time.md	Command, Child, 管道, Windows 特殊行為, exit, env, TcpListener/TcpStream, Instant, SystemTime, Duration
references/traits-conversions.md	From/Into/TryFrom, AsRef/Borrow, Clone/Copy/Default, PartialEq/Ord, Drop, Deref, Fn, Any, PhantomData
references/unsafe-ptr-num.md	指標有效性, provenance, NonNull, from_raw_parts, MaybeUninit, transmute, 溢位, 浮點數, hints

所有已讀取的頁面皆列於 SOURCES.md 中。