Crate std 

Rust 標準函式庫

Rust 標準函式庫是可攜式 Rust 軟體的基礎， 一組為更廣泛的 Rust 生態系提供的精簡且經過實戰考驗的共用抽象。 它提供核心型別，如 Vec<T> 和 Option<T>、 函式庫定義的語言原始型別操作、標準巨集、I/O 和 多執行緒，以及許多其他功能。

std 預設對所有 Rust crate 都可用。因此，可以在 use 陳述句中透過 路徑 std 來存取標準函式庫，例如 use std::env。

如何閱讀本文件

如果你已經知道要找什麼，最快的方式是使用頁面頂部的 搜尋按鈕。

否則，你可能會想跳到以下實用的章節：

• std::* 模組
• 原始型別
• 標準巨集
• Rust Prelude

如果這是你第一次閱讀，標準函式庫的文件是以輕鬆瀏覽的方式撰寫的。 點選有趣的項目通常會帶你到有趣的地方。不過，有些重要的內容你不會想錯過， 所以請繼續閱讀，來一趟標準函式庫及其文件的導覽之旅！

當你熟悉標準函式庫的內容後，你可能會覺得冗長的說明文字令人分心。 在這個階段，你可能會想按下頁面頂部附近的 “ Summary” 按鈕，將其摺疊成更容易快速瀏覽的檢視。

在查看頁面頂部時，也請注意「Source」連結。Rust 的 API 文件附帶原始碼， 我們鼓勵你閱讀它。標準函式庫的原始碼通常品質很高， 一窺幕後往往能帶來啟發。

標準函式庫文件中有什麼？

首先，Rust 標準函式庫被劃分為許多專注的模組， 全部列在本頁下方。這些模組是所有 Rust 構建的基石， 它們有著響亮的名字，如 std::slice 和 std::cmp。 模組的文件通常包含模組的概觀和範例，是開始熟悉函式庫的好地方。

其次，原始型別上的隱含方法也記錄在此。 這可能會造成困惑，原因有二：

1. 雖然原始型別由編譯器實作，但標準函式庫直接在原始型別上實作方法 （而且它是唯一這樣做的函式庫），這些方法記錄在原始型別章節中。
2. 標準函式庫匯出許多與原始型別同名的模組。這些模組定義了與原始型別相關的 額外項目，但不包含那些最重要的方法。

舉例來說，有一個原始型別 char 的頁面列出了所有可以在 字元上呼叫的方法（非常實用），也有一個模組 std::char 的頁面 記錄了這些方法所建立的疊代器和錯誤型別（較少使用）。

請注意原始型別 str 和 [T]（也稱為「切片」）的文件。 許多在 String 和 Vec<T> 上的方法呼叫，實際上是透過 deref 強制轉換分別呼叫 str 和 [T] 上的方法。

第三，標準函式庫定義了 Rust Prelude， 一小組項目——主要是 trait——會被匯入每個 crate 的每個模組中。 Prelude 中的 trait 無處不在，因此 prelude 文件是學習函式庫的好起點。

最後，標準函式庫匯出了許多標準巨集，並列在本頁中 （技術上來說，並非所有標準巨集都由標準函式庫定義——有些由編譯器定義—— 但它們同樣記錄在此）。如同 prelude，標準巨集預設會匯入所有 crate。

貢獻文件修改

請查看 Rust 貢獻指南在此。 本文件的原始碼可以在 GitHub 的 ‘library/std/’ 目錄中找到。要貢獻修改，請確保你先閱讀指南， 然後提交 pull request。

我們感謝你的貢獻！如果你看到文件中可以改進的部分， 請提交 PR，或先在 Zulip #docs 上與我們聊聊。

Rust 標準函式庫導覽

本 crate 文件的其餘部分致力於指出 Rust 標準函式庫的顯著特色。

容器與集合

option 和 result 模組定義了可選值和錯誤處理型別， Option<T> 和 Result<T, E>。iter 模組定義了 Rust 的疊代器 trait Iterator，它與 for 迴圈搭配使用來存取集合。

標準函式庫提供三種常見的方式來處理連續的記憶體區域：

• Vec<T> - 在堆積上配置的向量，可在執行期調整大小。
• [T; N] - 行內的陣列，在編譯期具有固定大小。
• [T] - 動態大小的切片，可以指向任何種類的連續儲存空間， 無論是否在堆積上配置。

切片只能透過某種指標來處理，因此有多種形式：

• &[T] - 共享切片
• &mut [T] - 可變切片
• Box<[T]> - 擁有所有權的切片

str，一個 UTF-8 字串切片，是一種原始型別，標準函式庫為它定義了許多方法。 Rust 的 str 通常以不可變參照的形式存取：&str。 使用擁有所有權的 String 來建構和修改字串。

要轉換為字串，使用 format! 巨集；要從字串轉換，使用 FromStr trait。

資料可以透過放入參照計數的 box 或 Rc 型別來共享， 如果進一步包含在 Cell 或 RefCell 中，則可以同時共享和修改。 同樣地，在並行環境中，常見的做法是將不可分割參照計數的 box Arc 與 Mutex 搭配使用來達到相同的效果。

collections 模組定義了映射、集合、連結串列和其他典型的集合型別， 包括常用的 HashMap<K, V>。

平台抽象與 I/O

除了基本資料型別之外，標準函式庫主要關注於抽象化常見平台之間的差異， 最顯著的是 Windows 和 Unix 衍生系統。

常見的 I/O 型別，包括檔案、TCP 和 UDP，定義在 io、fs 和 net 模組中。

thread 模組包含 Rust 的執行緒抽象。sync 包含更多原始的 共享記憶體型別，包括 atomic、mpmc 和 mpsc， 後者包含用於訊息傳遞的通道型別。

在 main() 之前和之後使用

標準函式庫的許多部分預期在 main() 之前和之後都能運作； 但這並未被保證或經過測試確認。建議你撰寫自己的測試， 並在你希望支援的每個平台上執行。 這意味著在 main 之前/之後使用 std，特別是與作業系統或全域狀態互動的功能， 不受穩定性和可攜性保證的約束，而僅以盡力而為的方式提供。 儘管如此，我們仍然歡迎錯誤回報。

另一方面，core 和 alloc 最有可能在這些環境中運作， 但需注意任何可掛鉤的行為（如 panic、記憶體不足處理或配置器） 也取決於掛鉤的相容性。

某些功能在 main 之外也可能有不同的行為，例如 stdio 可能變為無緩衝， 某些 panic 可能變為中止，回溯可能無法符號化等。

已知限制的非完整清單：

• 在 main 之後使用執行緒區域變數，這也會影響額外的功能：
  • thread::current()
• 在 UNIX 下，main 之前，檔案描述子 0、1 和 2 可能未被變更 （在 main 期間保證它們是開啟的， 如果在程式啟動時未開啟，則會以 O_RDWR 模式開啟到 /dev/null）

Primitive Types

array

固定大小的陣列，以 [T; N] 表示，其中 T 為元素型別，N 為非負的編譯期常數大小。

bool

布林型別。

char

字元型別。

f32

32 位元浮點數型別（具體而言，是 IEEE 754-2008 中定義的「binary32」型別）。

f64

64 位元浮點數型別（具體而言，是 IEEE 754-2008 中定義的「binary64」型別）。

fn

函式指標，例如 fn(usize) -> bool。

i8

8 位元有號整數型別。

i16

16 位元有號整數型別。

i32

32 位元有號整數型別。

i64

64 位元有號整數型別。

i128

128 位元有號整數型別。

isize

指標大小的有號整數型別。

pointer

原始不安全指標，*const T 和 *mut T。

reference

參考，&T 和 &mut T。

slice

連續序列的動態大小視圖，[T]。

str

字串切片。

tuple

有限的異質序列，(T, U, ..)。

u8

8 位元無號整數型別。

u16

16 位元無號整數型別。

u32

32 位元無號整數型別。

u64

64 位元無號整數型別。

u128

128 位元無號整數型別。

unit

() 型別，也稱為「unit」。

usize

指標大小的無號整數型別。

f16Experimental

16 位元浮點數型別（具體而言，是 IEEE 754-2008 中定義的「binary16」型別）。

f128Experimental

128 位元浮點數型別（具體而言，是 IEEE 754-2008 中定義的「binary128」型別）。

neverExperimental

! 型別，也稱為「never」。

Modules

alloc

記憶體配置 API。

any

動態型別或型別反射的工具。

arch

SIMD 與供應商內建函式模組。

array

陣列原始型別的工具函式。

ascii

對 ASCII 字串和字元的操作。

backtrace

支援捕捉作業系統執行緒的堆疊回溯

borrow

用於處理借用資料的模組。

boxed

Box<T> 型別，用於堆積（heap）記憶體配置。

cell

可共享的可變容器。

char

char 原始型別的工具函式。

clone

無法「隱式複製」的型別所使用的 Clone 特徵。

cmp

比較與排序值的工具。

collections

集合型別。

convert

型別之間轉換的特徵。

default

具有預設值的型別所使用的 Default 特徵。

env

行程環境的檢查與操作。

error

處理錯誤的介面。

f32

f32 單精度浮點型別的常數。

f64

f64 雙精度浮點型別的常數。

ffi

與 FFI 繫結相關的工具程式。

fmt

格式化和列印 String 的工具函式。

fs

檔案系統操作。

future

非同步基礎功能。

hash

通用雜湊支援。

hint

向編譯器提供影響程式碼生成或最佳化方式的提示。

i8Deprecation planned

i8 原始型別的冗餘常數模組。

i16Deprecation planned

i16 原始型別的冗餘常數模組。

i32Deprecation planned

i32 原始型別的冗餘常數模組。

i64Deprecation planned

i64 原始型別的冗餘常數模組。

i128Deprecation planned

i128 原始型別的冗餘常數模組。

io

核心 I/O 功能的 trait、輔助工具與型別定義。

isizeDeprecation planned

isize 原始型別的冗餘常數模組。

iter

可組合的外部迭代。

marker

表示型別基本屬性的原始特徵與型別。

mem

處理記憶體的基本函式。

net

TCP/UDP 通訊的網路原語。

num

數值的額外功能。

ops

可重載的運算子。

option

可選值。

os

作業系統特定功能。

panic

標準函式庫中的 panic 支援。

path

跨平台路徑操作。

pin

將資料釘選到記憶體中特定位置的型別。

prelude

Rust Prelude

primitive

此模組重新匯出原始型別，以允許不會被其他宣告的型別遮蔽的使用方式。

process

用於操作行程的模組。

ptr

透過原始指標手動管理記憶體。

rc

單執行緒參考計數指標。‘Rc’ 代表 ‘Reference Counted’（參考計數）。

result

使用 Result 型別進行錯誤處理。

slice

切片基本型別的工具函式。

str

str 基本型別的工具函式。

string

UTF-8 編碼的可增長字串。

sync

實用的同步原語。

task

用於處理非同步任務的型別與特徵。

thread

原生執行緒。

time

時間量化。

u8Deprecation planned

u8 原始型別的冗餘常數模組。

u16Deprecation planned

u16 原始型別的冗餘常數模組。

u32Deprecation planned

u32 原始型別的冗餘常數模組。

u64Deprecation planned

u64 原始型別的冗餘常數模組。

u128Deprecation planned

u128 原始型別的冗餘常數模組。

usizeDeprecation planned

usize 原始型別的冗餘常數模組。

vec

一個具有堆積配置內容的連續可增長陣列型別，寫作 Vec<T>。

assert_matchesExperimental

包含不穩定 assert_matches 巨集的不穩定模組。

async_iterExperimental

可組合的非同步迭代。

autodiffExperimental

此模組提供自動微分的支援。

bstrExperimental

ByteStr 和 ByteString 型別及特徵實作。

f16Experimental

f16 半精度浮點型別的常數。

f128Experimental

f128 四精度浮點型別的常數。

fromExperimental

包含不穩定 From 衍生巨集的不穩定模組。

intrinsicsExperimental

編譯器內建函式（intrinsics）。

patExperimental

Helper module for exporting the pattern_type macro

randomExperimental

隨機值生成。

rangeExperimental

實驗性的替代範圍型別

simdExperimental

可攜式 SIMD 模組。

unsafe_binderExperimental

用於將型別轉換為 unsafe binder 及其逆向操作的運算子。

Macros

assert

在執行時斷言布林表達式為 true。

assert_eq

斷言兩個表達式彼此相等（使用 PartialEq）。

assert_ne

斷言兩個表達式彼此不相等（使用 PartialEq）。

cfg

在編譯時評估設定旗標的布林組合。

column

展開為呼叫它的欄號。

compile_error

在遇到時使編譯失敗，並顯示給定的錯誤訊息。

concat

將字面量串接成靜態字串切片。

dbg

列印並回傳給定表達式的值，用於快速簡易的除錯。

debug_assert

在執行時斷言布林表達式為 true。

debug_assert_eq

斷言兩個表達式彼此相等。

debug_assert_ne

斷言兩個表達式彼此不相等。

env

在編譯時檢視環境變數。

eprint

列印到標準錯誤輸出。

eprintln

列印到標準錯誤輸出，並附加換行符。

file

展開為呼叫它的檔案名稱。

format

使用執行時期表達式的插值建立 String。

format_args

為其他字串格式化巨集建構參數。

include

根據上下文將檔案解析為表達式或項目。

include_bytes

以位元組陣列的參考形式包含檔案。

include_str

以字串形式包含 UTF-8 編碼的檔案。

is_x86_feature_detected

在執行時檢查 CPU 功能是否存在。

line

展開為呼叫它的行號。

matches

回傳給定表達式是否符合所提供的模式。

module_path

展開為代表當前模組路徑的字串。

option_env

在編譯時可選地檢視環境變數。

panic

使目前的執行緒 panic。

print

列印到標準輸出。

println

列印到標準輸出，並附加換行符。

stringify

將其參數字串化。

thread_local

宣告一個 std::thread::LocalKey 型別的新執行緒本地儲存鍵。

todo

表示未完成的程式碼。

tryDeprecated

解包一個結果，或傳播其錯誤。

unimplemented

以「not implemented」訊息 panic 來表示未實作的程式碼。

unreachable

表示不可到達的程式碼。

vec

建立包含引數的 Vec。

write

將格式化資料寫入緩衝區。

writeln

將格式化資料寫入緩衝區，並在末尾附加換行符。

cfg_selectExperimental

根據 cfg 謂詞在編譯時選取程式碼。

concat_bytesExperimental

將字面量串接成位元組切片。

const_format_argsExperimental

與 format_args 相同，但可在某些 const 上下文中使用。

log_syntaxExperimental

將傳入的記號印到標準輸出。

trace_macrosExperimental

啟用或停用用於偵錯其他巨集的追蹤功能。

Keywords

SelfTy

trait 或 impl 區塊中的實作型別，或型別定義中的目前型別。

as

在型別之間轉型、重新命名匯入，或限定關聯項目的路徑。

async

回傳一個 Future 而不是阻塞目前的執行緒。

await

暫停執行直到 Future 的結果準備就緒。

become

執行函式的尾呼叫。

break

從迴圈或有標籤的區塊提前退出。

const

編譯期常數、編譯期區塊、可在編譯期求值的函式，以及原始指標。

continue

跳至迴圈的下一次疊代。

crate

一個 Rust 二進位檔或函式庫。

dyn

dyn 是 trait 物件型別的前綴。

else

當 if 條件求值為 false 時要求值的表達式。

enum

一種可以是多個變體之一的型別。

extern

連結或匯入外部程式碼。

false

一個型別為 bool 的值，代表邏輯上的假。

fn

一個函式或函式指標。

for

使用 in 疊代、使用 impl 實作 trait，或使用高階 trait 約束（for<'a>）。

if

當條件成立時對一個區塊求值。

impl

為型別實作功能，或一個型別實作某些功能。

in

使用 for 疊代一系列值。

let

將值綁定到變數。

loop

無限迴圈。

match

基於模式配對的控制流程。

mod

將程式碼組織成模組。

move

以值捕獲閉包的環境。

mut

可變的變數、參照或指標。

pub

讓項目對外可見。

ref

在模式配對期間以參照方式綁定。

return

從函式回傳一個值。

self

方法的接收者，或目前的模組。

static

靜態項目是在程式整個執行期間有效的值（'static 生命週期）。

struct

一種由其他型別組成的型別。

super

目前模組的父模組。

trait

一組型別的共同介面。

true

一個型別為 bool 的值，代表邏輯上的真。

type

為現有型別定義別名。

union

C 風格聯合在 Rust 中的等價物。

unsafe

型別系統無法驗證其記憶體安全的程式碼或介面。

use

從其他 crate 或模組匯入或重新命名項目，在符合人體工程學的複製語義下使用值，或使用 use<..> 指定精確捕獲。

where

添加使用某個項目時必須遵守的約束。

while

在條件成立時持續迴圈。