Rust工具鏈使用：穩定版與夜間版

# 安裝rustup（如果尚未安裝）
# 這個指令會下載並執行rustup安裝腳本
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 檢視目前安裝的工具鏈
# 列出所有已安裝的Rust版本以及目前使用的版本
rustup show

# 安裝穩定版工具鏈
# 穩定版適合生產環境使用，經過完整測試
rustup install stable

# 安裝夜間版工具鏈
# 夜間版包含最新的實驗性功能
rustup install nightly

# 安裝特定日期的夜間版
# 當需要特定版本的功能時非常有用
rustup install nightly-2025-11-01

# 設定預設工具鏈
# 後續所有Rust指令都會使用這個版本
rustup default stable

# 為當前目錄設定特定工具鏈
# 在專案根目錄執行，會建立rust-toolchain檔案
rustup override set nightly

# 查詢特定工具鏈的路徑
# 可用於診斷或整合其他工具
rustup which rustc

# 更新所有已安裝的工具鏈
# 定期執行以取得最新的bug修復與改進
rustup update

# 移除不再需要的工具鏈
# 釋放磁碟空間
rustup uninstall nightly-2025-10-01

# 安裝額外的元件
# 例如rust-src用於IDE的程式碼分析
rustup component add rust-src

# 安裝特定工具鏈的元件
rustup component add rust-src --toolchain nightly

# 查看可用的元件
rustup component list

# 安裝交叉編譯目標
# 例如編譯為WebAssembly
rustup target add wasm32-unknown-unknown

# 查看已安裝的目標平台
rustup target list --installed

// lib.rs
// 這個檔案展示如何條件性地啟用夜間版功能

// 使用cfg_attr根據功能標誌啟用夜間版功能
// 當啟用nightly功能時，才會啟用allocator_api功能
#![cfg_attr(feature = "nightly", feature(allocator_api))]
// 啟用doc_cfg功能以在文件中標示需要特定功能的項目
#![cfg_attr(all(feature = "nightly", doc), feature(doc_cfg))]

// 標準函式庫引入
use std::alloc::{Layout, LayoutError};

// 條件編譯模組
// 只有在啟用nightly功能時才編譯這個模組
#[cfg(feature = "nightly")]
// 在文件中標示這個模組需要nightly功能
#[cfg_attr(all(feature = "nightly", doc), doc(cfg(feature = "nightly")))]
pub mod protected_memory {
    //! 受保護的記憶體模組
    //!
    //! 此模組提供記憶體保護功能，包括記憶體鎖定與存取保護。
    //! 需要啟用nightly功能才能使用。

    use std::alloc::{AllocError, Allocator, Global, Layout};
    use std::ptr::NonNull;

    /// 受保護的記憶體區塊
    ///
    /// 這個結構封裝了一塊受保護的記憶體，提供安全的存取介面。
    pub struct ProtectedMemory {
        /// 記憶體指標
        ptr: NonNull<u8>,
        /// 記憶體佈局
        layout: Layout,
    }

    impl ProtectedMemory {
        /// 建立新的受保護記憶體區塊
        ///
        /// # Arguments
        ///
        /// * `size` - 要分配的記憶體大小（位元組）
        ///
        /// # Returns
        ///
        /// 成功時回傳ProtectedMemory實例，失敗時回傳AllocError
        ///
        /// # Example
        ///
        /// ```rust,ignore
        /// let protected = ProtectedMemory::new(1024)?;
        /// ```
        pub fn new(size: usize) -> Result<Self, AllocError> {
            // 建立記憶體佈局，對齊到頁面邊界
            let layout = Layout::from_size_align(size, 4096)
                .map_err(|_| AllocError)?;

            // 使用Global分配器分配記憶體
            // 這裡使用allocator_api的功能
            let ptr = Global.allocate(layout)?;

            Ok(Self {
                ptr: ptr.cast(),
                layout,
            })
        }

        /// 取得記憶體指標
        ///
        /// # Safety
        ///
        /// 呼叫者必須確保在ProtectedMemory生命週期內不會解除分配
        pub fn as_ptr(&self) -> *const u8 {
            self.ptr.as_ptr()
        }

        /// 取得可變記憶體指標
        pub fn as_mut_ptr(&mut self) -> *mut u8 {
            self.ptr.as_ptr()
        }

        /// 取得記憶體大小
        pub fn len(&self) -> usize {
            self.layout.size()
        }

        /// 檢查記憶體是否為空
        pub fn is_empty(&self) -> bool {
            self.layout.size() == 0
        }
    }

    impl Drop for ProtectedMemory {
        fn drop(&mut self) {
            // 釋放分配的記憶體
            unsafe {
                Global.deallocate(self.ptr, self.layout);
            }
        }
    }
}

// 在穩定版也可以使用的功能
// 不需要任何feature gate

/// 計算字串的雜湊值
///
/// 使用簡單的雜湊演算法計算字串的雜湊值。
/// 此功能在穩定版與夜間版都可以使用。
///
/// # Arguments
///
/// * `input` - 要計算雜湊的字串
///
/// # Returns
///
/// 64位元無符號整數的雜湊值
///
/// # Example
///
/// ```rust
/// let hash = calculate_hash("hello");
/// println!("Hash: {}", hash);
/// ```
pub fn calculate_hash(input: &str) -> u64 {
    // 使用FNV-1a雜湊演算法
    let mut hash: u64 = 0xcbf29ce484222325;
    for byte in input.bytes() {
        hash ^= byte as u64;
        hash = hash.wrapping_mul(0x100000001b3);
    }
    hash
}

// 條件編譯的測試
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_calculate_hash() {
        // 測試雜湊函式的基本功能
        let hash1 = calculate_hash("hello");
        let hash2 = calculate_hash("hello");
        let hash3 = calculate_hash("world");

        // 相同輸入應產生相同雜湊
        assert_eq!(hash1, hash2);
        // 不同輸入應產生不同雜湊
        assert_ne!(hash1, hash3);
    }

    // 只在啟用nightly功能時執行的測試
    #[cfg(feature = "nightly")]
    #[test]
    fn test_protected_memory() {
        use protected_memory::ProtectedMemory;

        // 測試受保護記憶體的分配
        let result = ProtectedMemory::new(4096);
        assert!(result.is_ok());

        let protected = result.unwrap();
        assert_eq!(protected.len(), 4096);
        assert!(!protected.is_empty());
    }
}

[package]
name = "my-rust-project"
version = "0.1.0"
edition = "2021"

[features]
# 預設不啟用nightly功能
default = []
# nightly功能用於啟用夜間版特有的功能
nightly = []

[dependencies]
# 依賴項設定

# 使用穩定版編譯（不啟用nightly功能）
cargo build

# 使用夜間版編譯並啟用nightly功能
cargo +nightly build --features nightly

# 執行測試（穩定版）
cargo test

# 執行測試（夜間版，包含nightly專用測試）
cargo +nightly test --features nightly

# 安裝cargo-expand
# 需要夜間版工具鏈才能使用
cargo install cargo-expand

# 展開整個crate的巨集
cargo +nightly expand

# 展開特定模組的巨集
cargo +nightly expand my_module

# 展開特定函式的巨集
cargo +nightly expand my_module::my_function

# 將輸出儲存到檔案
cargo +nightly expand > expanded.rs

// src/main.rs
// 原始程式碼

fn main() {
    // 使用println!巨集
    let name = "Rust";
    println!("Hello, {}!", name);

    // 使用vec!巨集
    let numbers = vec![1, 2, 3, 4, 5];
    println!("Numbers: {:?}", numbers);

    // 使用derive巨集
    #[derive(Debug, Clone)]
    struct Point {
        x: i32,
        y: i32,
    }

    let point = Point { x: 10, y: 20 };
    println!("Point: {:?}", point);
}

// 展開後的程式碼（簡化版）
#![feature(prelude_import)]
#[prelude_import]
use std::prelude::rust_2021::*;
#[macro_use]
extern crate std;

fn main() {
    let name = "Rust";
    // println!巨集展開結果
    {
        ::std::io::_print(
            ::core::fmt::Arguments::new_v1(
                &["Hello, ", "!\n"],
                &[::core::fmt::ArgumentV1::new_display(&name)],
            ),
        );
    };

    // vec!巨集展開結果
    let numbers = <[_]>::into_vec(
        #[rustc_box]
        ::alloc::boxed::Box::new([1, 2, 3, 4, 5])
    );

    {
        ::std::io::_print(
            ::core::fmt::Arguments::new_v1(
                &["Numbers: ", "\n"],
                &[::core::fmt::ArgumentV1::new_debug(&numbers)],
            ),
        );
    };

    // derive巨集展開結果
    struct Point {
        x: i32,
        y: i32,
    }

    // 自動生成的Debug實作
    impl ::core::fmt::Debug for Point {
        fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
            ::core::fmt::Formatter::debug_struct_field2_finish(
                f,
                "Point",
                "x",
                &self.x,
                "y",
                &&self.y,
            )
        }
    }

    // 自動生成的Clone實作
    impl ::core::clone::Clone for Point {
        fn clone(&self) -> Point {
            Point {
                x: ::core::clone::Clone::clone(&self.x),
                y: ::core::clone::Clone::clone(&self.y),
            }
        }
    }

    let point = Point { x: 10, y: 20 };
    {
        ::std::io::_print(
            ::core::fmt::Arguments::new_v1(
                &["Point: ", "\n"],
                &[::core::fmt::ArgumentV1::new_debug(&point)],
            ),
        );
    };
}

# 安裝cargo-fuzz
# 需要夜間版工具鏈
cargo install cargo-fuzz

# 初始化模糊測試專案
# 這會在專案中建立fuzz目錄
cargo fuzz init

# 建立新的模糊測試目標
cargo fuzz add my_fuzz_target

# 執行模糊測試
cargo +nightly fuzz run my_fuzz_target

# 執行模糊測試並設定最大執行時間
cargo +nightly fuzz run my_fuzz_target -- -max_total_time=60

# 列出所有模糊測試目標
cargo fuzz list

# 檢視模糊測試的覆蓋率
cargo +nightly fuzz coverage my_fuzz_target

// fuzz/fuzz_targets/my_fuzz_target.rs

#![no_main]
use libfuzzer_sys::fuzz_target;

// 假設這是要測試的函式
fn parse_config(data: &[u8]) -> Result<Config, ParseError> {
    // 解析設定檔的邏輯
    // ...
    unimplemented!()
}

struct Config {
    // 設定結構
}

struct ParseError;

// 定義模糊測試目標
// libfuzzer會自動產生隨機的位元組序列作為輸入
fuzz_target!(|data: &[u8]| {
    // 嘗試解析隨機輸入
    // 模糊測試器會記錄導致崩潰或panic的輸入
    let _ = parse_config(data);
});

# 安裝cargo-watch
cargo install cargo-watch

# 監控變更並自動執行測試
# 每當原始碼變更時就會重新執行測試
cargo watch -x test

# 監控變更並自動編譯
cargo watch -x build

# 監控變更並自動執行程式
cargo watch -x run

# 監控變更並自動生成文件
cargo watch -x doc

# 組合多個命令
# 先檢查、再測試、最後執行
cargo watch -x check -x test -x run

# 只監控特定檔案類型
cargo watch -w src -x test

# 忽略特定目錄
cargo watch -i target -x test

# 在執行前清除終端機
cargo watch -c -x test

# 延遲執行以避免過於頻繁的重新編譯
cargo watch --delay 2 -x test

# cargo-tree現在已內建於Cargo中
# 不需要額外安裝

# 顯示完整的依賴樹
cargo tree

# 顯示特定套件的依賴
cargo tree -p my_package

# 顯示反向依賴（誰依賴這個套件）
cargo tree -i regex

# 只顯示直接依賴
cargo tree --depth 1

# 顯示重複的依賴
cargo tree --duplicates

# 以不同格式輸出
cargo tree --format "{p} {l}"

# 只顯示開發依賴
cargo tree --edges dev

# 排除開發依賴
cargo tree --edges normal,build

# cargo-update：更新所有已安裝的Cargo套件
cargo install cargo-update
cargo install-update -a

# cargo-audit：檢查依賴的安全漏洞
cargo install cargo-audit
cargo audit

# cargo-outdated：檢查過時的依賴
cargo install cargo-outdated
cargo outdated

# cargo-bloat：分析二進位檔案大小
cargo install cargo-bloat
cargo bloat --release

# cargo-flamegraph：產生效能火焰圖
cargo install flamegraph
cargo flamegraph

# cargo-deny：檢查授權與安全問題
cargo install cargo-deny
cargo deny check

# cargo-make：任務執行器
cargo install cargo-make
cargo make build

// 字串型別的完整範例

fn main() {
    // String：堆積分配的可變字串
    // 擁有所有權，可以修改
    let mut owned_string = String::from("Hello");
    owned_string.push_str(", World!");
    println!("Owned String: {}", owned_string);

    // &str：字串切片，對字串資料的借用
    // 不擁有所有權，不可修改
    let borrowed_str: &str = "Hello, World!";
    println!("Borrowed str: {}", borrowed_str);

    // String可以借用為&str
    let borrowed_from_string: &str = &owned_string;
    println!("Borrowed from String: {}", borrowed_from_string);

    // 字串切片可以轉換為String
    let new_string: String = borrowed_str.to_string();
    let another_string: String = borrowed_str.into();

    // &'static str：靜態生命週期的字串切片
    // 在程式整個執行期間都有效
    let static_str: &'static str = "I live forever";
    println!("Static str: {}", static_str);

    // 字串操作示範
    demonstrate_string_operations();

    // 字串與記憶體佈局
    demonstrate_memory_layout();
}

/// 展示各種字串操作
fn demonstrate_string_operations() {
    // 建立String的多種方式
    let s1 = String::new();                    // 空字串
    let s2 = String::from("hello");            // 從&str建立
    let s3 = "hello".to_string();              // 使用to_string方法
    let s4 = "hello".to_owned();               // 使用to_owned方法
    let s5: String = "hello".into();           // 使用Into特徵

    // 字串連接
    let mut s = String::from("Hello");
    s.push(' ');                               // 添加單個字元
    s.push_str("World");                       // 添加字串切片
    println!("Concatenated: {}", s);

    // 使用format!巨集連接
    let s1 = String::from("Hello");
    let s2 = String::from("World");
    let s3 = format!("{}, {}!", s1, s2);       // s1和s2仍然可用
    println!("Formatted: {}", s3);

    // 字串切片
    let s = String::from("Hello, World!");
    let hello = &s[0..5];                      // "Hello"
    let world = &s[7..12];                     // "World"
    println!("Slices: {} {}", hello, world);

    // 遍歷字串
    let s = "你好世界";
    for c in s.chars() {
        println!("Char: {}", c);
    }
    for b in s.bytes() {
        println!("Byte: {}", b);
    }

    // 字串搜尋
    let s = "Hello, World!";
    if s.contains("World") {
        println!("Found 'World'");
    }
    if let Some(idx) = s.find("World") {
        println!("'World' starts at index {}", idx);
    }

    // 字串替換
    let s = "Hello, World!";
    let replaced = s.replace("World", "Rust");
    println!("Replaced: {}", replaced);

    // 字串分割
    let s = "one,two,three";
    for part in s.split(',') {
        println!("Part: {}", part);
    }

    // 去除空白
    let s = "  Hello, World!  ";
    println!("Trimmed: '{}'", s.trim());
}

/// 展示字串的記憶體佈局
fn demonstrate_memory_layout() {
    // String的記憶體佈局：
    // - ptr: 指向堆積上資料的指標（8 bytes）
    // - len: 當前長度（8 bytes）
    // - capacity: 已分配的容量（8 bytes）
    // 總共：24 bytes（在64位元系統上）

    let s = String::from("Hello");
    println!("String size on stack: {} bytes", std::mem::size_of_val(&s));
    println!("String length: {}", s.len());
    println!("String capacity: {}", s.capacity());
    println!("String pointer: {:p}", s.as_ptr());

    // &str的記憶體佈局：
    // - ptr: 指向資料的指標（8 bytes）
    // - len: 長度（8 bytes）
    // 總共：16 bytes（在64位元系統上）

    let slice: &str = "Hello";
    println!("&str size: {} bytes", std::mem::size_of_val(&slice));
}

// 函式參數中的字串型別選擇

/// 接受&str參數：最靈活的選擇
/// 可以傳入String（借用為&str）或直接傳入&str
fn print_greeting(name: &str) {
    println!("Hello, {}!", name);
}

/// 接受String參數：取得所有權
/// 函式結束後String會被釋放
fn take_ownership(s: String) {
    println!("I own: {}", s);
} // s在這裡被釋放

/// 接受&String參數：借用String的參照
/// 較少使用，因為&str更靈活
fn borrow_string(s: &String) {
    println!("Borrowed String: {}", s);
}

/// 回傳String：轉移所有權給呼叫者
fn create_greeting(name: &str) -> String {
    format!("Hello, {}!", name)
}

// 陣列與切片的完整範例

fn main() {
    // 陣列：固定大小的序列
    // 大小是型別的一部分
    let array: [i32; 5] = [1, 2, 3, 4, 5];
    println!("Array: {:?}", array);
    println!("Array length: {}", array.len());

    // 初始化所有元素為相同值
    let zeros: [u8; 100] = [0; 100];
    println!("First zero: {}", zeros[0]);

    // 切片：對陣列或向量的視圖
    // 切片不擁有資料
    let slice: &[i32] = &array[1..4]; // [2, 3, 4]
    println!("Slice: {:?}", slice);

    // 切片的各種建立方式
    let full_slice: &[i32] = &array;           // 完整切片
    let from_start: &[i32] = &array[..3];      // 從開頭到索引3
    let to_end: &[i32] = &array[2..];          // 從索引2到結尾
    let middle: &[i32] = &array[1..4];         // 中間部分

    // 可變切片
    let mut array = [1, 2, 3, 4, 5];
    let slice = &mut array[1..4];
    slice[0] = 10;                              // 修改第一個元素
    println!("Modified array: {:?}", array);    // [1, 10, 3, 4, 5]

    // 切片分割
    let array = [1, 2, 3, 4, 5, 6];
    let (first, second) = array.split_at(3);
    println!("First half: {:?}", first);        // [1, 2, 3]
    println!("Second half: {:?}", second);      // [4, 5, 6]

    // 切片方法
    demonstrate_slice_methods();
}

/// 展示切片的各種方法
fn demonstrate_slice_methods() {
    let array = [3, 1, 4, 1, 5, 9, 2, 6];
    let slice = &array[..];

    // 基本操作
    println!("Length: {}", slice.len());
    println!("Is empty: {}", slice.is_empty());
    println!("First: {:?}", slice.first());
    println!("Last: {:?}", slice.last());

    // 搜尋
    println!("Contains 5: {}", slice.contains(&5));
    println!("Position of 5: {:?}", slice.iter().position(|&x| x == 5));

    // 遍歷
    for (i, &value) in slice.iter().enumerate() {
        println!("Index {}: {}", i, value);
    }

    // 視窗遍歷
    for window in slice.windows(3) {
        println!("Window: {:?}", window);
    }

    // 塊遍歷
    for chunk in slice.chunks(3) {
        println!("Chunk: {:?}", chunk);
    }

    // 排序（需要可變切片）
    let mut array = [3, 1, 4, 1, 5, 9, 2, 6];
    array.sort();
    println!("Sorted: {:?}", array);

    // 二分搜尋（需要已排序）
    let result = array.binary_search(&5);
    println!("Binary search for 5: {:?}", result);

    // 反轉
    let mut array = [1, 2, 3, 4, 5];
    array.reverse();
    println!("Reversed: {:?}", array);

    // 旋轉
    let mut array = [1, 2, 3, 4, 5];
    array.rotate_left(2);
    println!("Rotated left by 2: {:?}", array);  // [3, 4, 5, 1, 2]
}

// 函式中使用切片

/// 接受切片參數：最靈活的選擇
/// 可以傳入陣列的切片或向量的切片
fn sum_slice(numbers: &[i32]) -> i32 {
    numbers.iter().sum()
}

/// 接受可變切片：可以修改內容
fn double_values(numbers: &mut [i32]) {
    for n in numbers.iter_mut() {
        *n *= 2;
    }
}

/// 接受固定大小的陣列參數
/// 只能傳入完全相同大小的陣列
fn process_fixed_array(array: [i32; 5]) {
    println!("Fixed array: {:?}", array);
}

/// 使用泛型接受任意大小的陣列
fn process_any_array<const N: usize>(array: [i32; N]) {
    println!("Array of size {}: {:?}", N, array);
}

// 效能最佳化範例

fn main() {
    // 1. 預先分配容量以避免重複分配
    let mut vec = Vec::with_capacity(1000);
    for i in 0..1000 {
        vec.push(i);
    }

    // 2. 使用&str而非String作為函式參數
    // 這允許零成本傳遞字串字面值
    fn process(s: &str) {
        // 處理字串
    }

    // 3. 使用切片而非Vec作為函式參數
    fn sum(numbers: &[i32]) -> i32 {
        numbers.iter().sum()
    }

    // 4. 使用into_iter取得所有權以避免複製
    let vec = vec![String::from("a"), String::from("b")];
    for s in vec.into_iter() {
        // s擁有String的所有權
    }

    // 5. 使用collect時指定型別以獲得更好的效能
    let doubled: Vec<i32> = (0..100).map(|x| x * 2).collect();

    // 6. 使用extend而非多次push
    let mut vec = Vec::new();
    vec.extend(0..1000);

    // 7. 使用join而非多次字串連接
    let parts = vec!["Hello", "World"];
    let joined = parts.join(", ");

    // 8. 使用entry API處理Map
    use std::collections::HashMap;
    let mut map = HashMap::new();
    map.entry("key").or_insert(0);
}