2021-03-17

[Rust] Crate std(標準ライブラリ:日本語)

【Rust】
※当記事はCrate std(rust-lang / rust)を翻訳したものです(→翻訳に関して)
※Version 1.50.0 (cb75ad5db 2021-02-10)

Rust標準ライブラリ

 Rust標準ライブラリは、手軽なRustソフトウェアの土台であり、ミニマルなプログラムの一式であり、選びぬかれた(より広範囲をカバーする)Rustエコシステムのための抽象的なプログラム群です。また、Vec<T>Option<T>、ライブラリが定義した言語のプリミティブな部分を操作するコードのようなコアの型、標準マクロインプット/アウトプットマルチスレッドその他諸々などを提供します。

 標準ライブラリは初期状態から全てのRustクレートで使用できます。そしてそれは、useを「use std::env」のようにパスを指定することでアクセスできるようになります。

この文書の読み方

 もし探している項目の名が分かるなら、ページトップの検索枠を使うのが手っ取り早いでしょう。

 そうでないなら、以下の有益な方法もあります

std::* modules:モジュール一覧から探す
Primitive types:プリミティブ型の一覧から探す
Standard macros:標準マクロの一覧から探す
The Rust Prelude:Rustが自動で予め読み込むモジュール群の一覧から探す

 もし今回が初めてなら、この文書を気楽に熟読してみるのがよいでしょう。興味のあるリンクをクリックすれば、自然と興味のあるページへ向かえます。ただし、知っておかなければならない幾つかの重要なポイントがあります。それを以下で記します。

 一度標準ライブラリの内容に慣れれば、説明文が少し煩わしくなるかも知れません。その段階まで来たら、ページトップ付近にある[-]ボタンを押し、文章を折りたたんでみましょう。

 その際、[src]ボタンの存在にも気づくでしょう。RustのAPI文書はソースコードも含んでいるので、読むことをおすすめします。標準ライブラリのコードは一般的に高品質で、啓発されることも少なくないでしょう。

標準ライブラリの文書には何が書かれている?

 まず最初に、Rustの標準ライブラリは多くの焦点を持ったモジュールに分かれています(全てのリストはこちら)。これらのモジュールは全てのRustの土台であり、std::slicestd::cmpなどの確固たる名前が与えられています。モジュールの文書は一般的にコード例付きの概要を含むため、ライブラリに慣れる上での賢い選択になります。

 次に、ここにはプリミティブ型の暗黙のメソッドについての説明もあります。しかし以下の2つの理由で、混乱を招くこともあるため注意が必要です。

1.プリミティブ型はコンパイラによって実装されているのに対し、標準ライブラリはメソッドを直接プリミティブ型(文書の一覧はこちら)に実装しています(このような方法をとる唯一のライブラリでもあります)。
2.標準ライブラリには、多くのプリミティブ型と同名のモジュールがあります。これらはプリミティブ型に関係する追加機能を定義しますが、どれも重要なメソッドとは言えません。

 例えばi32型のページには32bit整数型に対して呼べる全てのメソッドの一覧があり、とても有用ですが、std::i32のページにあるMINMAXの値はあまり使うことがありません。

 プリミティブ型のstr[T](スライスとも)の資料に関して、StringVec<T>で呼ばれる多くのメソッドは実際deref強制により、それぞれstr[T]のものが呼ばれます。

 第3に標準ライブラリでは、全てのクレートの全てのモジュールにインポートされているRustプレリュード(小さなコード群、ほとんどがトレイトです)が定義されています。

 そして最後に、標準ライブラリは多くの標準マクロ(リストはこちら)をエクスポートしています(技術的に、全ての標準マクロが標準ライブラリで定義されているわけではありません-コンパイラによって定義されているものもあります-が同様に資料はここにあります)。プレリュードのように、標準マクロは初期状態で全てのクレートにインポートされています。

資料の更新に貢献する

 Rustへの貢献に関するガイドラインはこちらです。資料の情報源はGitHubにあります。更新への貢献の際は、まずガイダンスをお読み下さい。そして更新の提案では、プルリクエストを投げて下さい。

 貢献に感謝します! もし問題箇所を見つけたら、プルリクエストを投げるかDiscordの#docsで我々にまず知らせて下さい。

Rust標準ライブラリの旅

 この資料の残りは、Rustの標準ライブラリの注目に値する特徴の指摘に捧げます。

コンテナとコレクション

 optionresultモジュールは、オプションとエラー処理型(Option<T>Result<T, E>)を定義します。iterモジュールはRustのイテレータトレイト(Iterator)を定義します(これはコレクションにアクセスする際、forループと共に使います)。

 標準ライブラリは連続したメモリ領域を扱う3つの共通の方法を用意しています。

Vec<T>:プログラム実行時にサイズを変えられるヒープ割当のベクター型
[T; n]:コンパイル時にサイズが固定な埋め込み配列
[T]:ヒープ割当に限らない、連続したストレージへのサイズ可変な配列

 スライスはいくつかの種類のポインタを介してのみ処理できます。それには次のようなものがあります。

・&[T]:共有(参照)スライス
・&mut [T]:可変参照スライス
Box<T>:ヒープ割当のスライス(配列)

 str(UTF-8の文字列)はプリミティブ型で、標準ライブラリで多くのメソッドが定義されています。Rustのstrには一般的に不変参照(&str)としてアクセスします。文字列の組み立てと変更には所有権のあるString型を使って下さい。

 文字列への変換はformat!マクロを使います。そして文字列からの変換はFromStrトレイトを使います。

 データは参照カウントボックスか、Rc型に配置することで共有できます。さらにCellRefCellに含まれている場合、可変データのシェアもできます。並列処理において同様の効果を得るには、原始的な参照カウントボックスのArcMutexのペアを用いるのが一般的です。

 collectionsは、Maps,Sets,LinkedList他、一般的なHashMap<K, V>を含む典型的なコレクション型を定義します。

プラットフォーム抽象化とI/O

 基本的なデータ型に加え、標準ライブラリは一般的なプラットフォームの違い(最も顕著なのはWindowsとUnixの派生物)を抽象化することに大きく関係しています。

 files,TCP,UDPを含むI/Oの一般的な型は、io,fs,netで定義されています。

 threadはRustのスレッド抽象化を含みます。syncはさらにプリミティブなatomicmpscと言ったメモリ共有型を含みます。これらにはメッセージ通信のためのチャネル型があります。

再エクスポート

pub use core::arch;

プリミティブ型

never       【実験的】!型 またneverとも呼ばれる
array        [T; N](T=要素の型/N=コンパイル時不変の自然数)で示される固定サイズの配列
bool         ブール型
char         文字型
f32         32bit浮動小数点型(特にbinary32型はIEEE 754-2008で定義されている)
f64         64bit浮動小数点型(特にbinary64型はIEEE 754-2008で定義されている)
fn          関数ポインタ 例:fn(usize) -> bool
i8          8bit整数型
i16         16bit整数型
i32         32bit整数型
i64         64bit整数型
i128        128bit整数型
isize       ポインタサイズの整数型
pointer     生で安全でないポインタ(*const T と *mut T)
reference   共有と可変の参照
slice       [T](可変サイズの連続した値のビュー) ここでの隣接は等間隔に要素が並んでいることを意味する
str         文字列のスライス
tuple       定形の、異なる型を内包できるデータの並び (T, U, ..)
u8          8bit自然数型
u16         16bit自然数型
u32         32bit自然数型
u64         64bit自然数型
u128        128bit自然数型
unit        ()型 ユニットとも呼ばれる
usize       ポインタサイズの自然数型

モジュール

backtrace  【実験的】OSスレッドのスタックバックトレースのキャプチャのサポート
intrinsics 【実験的】コンパイラの組み込み関数
lazy       【実験的】遅延値と、静的データの一度きりの初期化
raw        【実験的】コンパイラ組み込み型のレイアウトの構造体定義を含む
alloc       メモリ割当API
any         Anyトレイトを実装(ランタイムリフレクションを通して任意の'static型の動的型付けが可能になる)
array       特定の長さまでの固定長配列の実装 最終的にはあらゆる長さに対し一般化できるはずです
ascii       ASCII文字と文字の操作
borrow      借用したデータを処理
boxed       ヒープ割当のポインタ型
cell        共有可能な可変コンテナ
char        文字型
clone       暗黙的にコピーできない型のトレイト
cmp         並び替えと比較のための機能
collections コレクション型
convert     型間の変換のためのトレイト
default     意味あるデフォルト値を持つ型のためのトレイト
env         プロセスの環境の検査と操作
error       エラー処理用のトレイト
f32         32bit浮動小数点型の実装に固有の定数を提供
f64         64bit浮動小数点型の実装に固有の定数を提供
ffi         FFIバインド関連のユーティリティ
fmt         文字列のフォーマットと出力のためのユーティリティ
fs          ファイルシステムの処理を行う
future      非同期値
hash        一般的なハッシュをサポート
hint        コンパイラへの、コードの発行や最適化に影響するヒント(コンパイル時か実行時)
i8          8bitの整数型
i16         16bitの整数型
i32         32bitの整数型
i64         64bitの整数型
i128        128bitの整数型
io          コアI/O機能のためのトレイト、ヘルパー、型定義
isize       ポインタサイズの整数型
iter        構成可能な外部反復
marker      型の基本プロパティ表すプリミティブなトレイトと型
mem         メモリを扱うための基本機能
net         TCP/UDP通信用のネットワークプリミティブ
num         数値のための追加機能
ops         オーバーロード可能な演算子
option      オプション値
os          OS固有の機能
panic       標準ライブラリでのpanicのサポート
path        クロスプラットフォームなパスの操作
pin         メモリ内の特定の場所にデータをピン留めする型
prelude     Rustプレリュード
primitive   プリミティブ型を再読み込みし、他の型宣言でシャドーイングされる可能性を回避
process     プロセスを操作
ptr         生ポインタを介してメモリを手動操作
rc          シングルスレッドの参照カウント(Reference Counted)ポインタ
result      Result型によるエラー処理
slice       連続した値への動的サイズのビュー [T]
str         Unicode文字列型
string      UTF-8でエンコードされた拡張可能な文字列
sync        有益な同期プリミティブ
task        非同期タスクを処理する型とトレイト
thread      ネイティブスレッド
time        時間の定量化
u8          8bitの自然数型
u16         16bitの自然数型
u32         32bitの自然数型
u64         64bitの自然数型
u128        128bitの自然数型
usize       ポインタサイズの自然数型
vec         ヒープ割当の、連続した拡張可能な配列 Vec<T>と表記

マクロ

asm            【実験的】インラインアセンブリ
concat_idents  【実験的】識別子を1つに連結する
format_args_nl 【実験的】format_argsと同じだが最後に改行を追加
global_asm     【実験的】モジュールレベルのインラインアセンブリ
is_aarch64_feature_detected【実験的】aarch64ターゲット以外でis_aarch64_feature_detectedが使われていた場合にコンパイルを停止
is_arm_feature_detected【実験的】ARMターゲット以外でis_arm_feature_detectedが使われていた場合にコンパイルを停止
is_mips64_feature_detected【実験的】MIPS64ターゲット以外でis_mips64_feature_detectedが使われていた場合にコンパイルを停止
is_mips_feature_detected【実験的】MIPSターゲット以外でis_mips_feature_detectedが使われていた場合にコンパイルを停止
is_powerpc64_feature_detected【実験的】PowerPC64ターゲット以外でis_powerpc64_feature_detectedが使われていた場合にコンパイルを停止
is_powerpc_feature_detected【実験的】PowerPCターゲット以外でis_powerpc_feature_detectedが使われていた場合にコンパイルを停止
llvm_asm       【実験的】LLVMスタイルのインラインアセンブリ
log_syntax     【実験的】渡されたトークンを標準出力に出力
trace_macros   【実験的】他のマクロのデバッグに使用されるトレース機能のon/off
assert          実行時にブール値が真であるこを表明する
assert_eq       2つの式が互いに等しいことを表明する(PartialEqを使用)
assert_ne       2つの式が互いに等しくないことを表明する(PartialEqを使用)
cfg             コンパイル時に設定フラグのブール値の組み合わせを評価する
column          呼び出された列番号に展開する
compile_error   発生すると、与えられたエラーメッセージと共にコンパイルが失敗する
concat          リテラルを静的な文字列スライスに連結する
dbg             迅速でダーティーなデバッグのため、与えられた式の値を出力し返す
debug_assert    実行時にブール式が真であることを表明する
debug_assert_eq 2つの式が互いに等しいことを表明する
debug_assert_ne 2つの式が互いに等しくないことを表明する
env             コンパイル時に環境変数を検査する
eprint          標準エラーに出力する
eprintln        標準エラーに出力する(最後に改行を加える)
file            呼び出されたファイル名に展開する
format          fmtに応じて文字列を生成する
format_args     他の文字列フォーマットマクロのパラメータを作成
include         コンテキストに従い、ファイルを式または項目として解析する
include_bytes   バイト配列への参照としてファイルを含める
include_str     UTF-8でエンコードされたファイルを文字列として含める
is_x86_feature_detected CPU機能がx86/x86-64上で使えるか実行時にテストする
line            呼び出された行番号に展開される
matches         与えられた式が与えられたいずれかのパターンに一致するかを返す
module_path     現在のモジュールパスを表す文字列に展開する
option_env      オプションで、コンパイル時に環境変数を検査する
panic           現在のスレッドをpanicさせる
print           標準出力に出力する
println         標準出力に出力する(最後に改行を加える)
stringify       引数を文字列化する
thread_local    LocalKey型の新しいローカルスレッドストレージキーを宣言する
todo            未完成のコードを示す
try            【非推奨】結果をアンラップするか、エラーを伝播させる
unimplemented   "not implemented"(メッセージ)と共にpanicさせ、未実装を示す
unreachable   到達できないコードを示す
vec             引数を含むVecを生成する
write           フォーマットされたデータをバッファに書き込む
writeln         フォーマットされたデータをバッファに書き込む(最後に改行を追加する)

キーワード

Self     traitimplブロック内の実装型、または型定義内の現在の型
as       型間でキャストするか、インポート名を変更する
async    現在のスレッドをブロックする代わりにFutureを返す
await    Futureの結果を準備できるまで、実行を一時停止する
break    ループを早期に終了する
const    コンパイル時の定数と、コンパイル時に評価可能な関数
continue ループの次の反復へスキップする
crate    Rustバイナリ、あるいはライブラリ
dyn      トレイトオブジェクトの型のプレフィックス
else     ifの条件式がfalseに評価された際に評価する式
enum     いくつかのバリアントのいずれかになる型
extern   外部コードにリンクするか、インポートする
false    偽を表すbool型の値
fn       関数または関数ポインタ
for      inを使ったイテレーション、implを使ったトレイト実装、または上位のトレイト境界(for<'a>)
if       条件が成立した際にブロックを評価する
impl     型にいくつかの機能を実装
in       forを使い、一連の値を繰り返し処理する
let      値を変数に束縛する
loop     無限ループ
match    パターンマッチングに基づき、フローを制御する
mod      コードをモジュールにまとめる
move     クロージャの環境を値でキャプチャする
mut      可変の変数、参照、またはポインタ
pub      項目を他から見えるようにする
ref      パターンマッチングの際、参照により束縛する
return   関数から値を返す
self     メソッドのレシーバー、または現在のモジュール
static   静的な項目は、プログラムの全期間('static)において有効な値
struct   他の型から構成する型
super    現在のモジュールの親
trait    型のグループに共通のインターフェース
true     真を表すbool型の値
type     既存の型のエイリアスを定義
unsafe   型システムで、メモリの安全性を検証できないコードまたはインターフェース
use      他のクレートやモジュールから、項目をインポートまたは名前変更する
where    項目を使用するために維持する必要のある制約を追加
while    条件が満たされている間、ループ処理を続ける