Reading Rust documentation

Adalah hal yang penting untuk mengetahui bagaimana cara membaca dokumentasi di Rust, sehingga Anda bisa memahami apa yang orang lain tuliskan. Berikut adalah beberapa hal yang penting untuk diketahui pada dokumantasi Rust:

assert_eq!

Anda bisa melihat bahwa assert_eq! digunakan di saat melakukan testing. Anda masukkan dua buah item ke dalam function tersebut dan programnya akan panic jika keduanya tidak sama. Berikut adalah contoh sederhana di mana kita memerlukan bilangan genap agar programnya tidak panic.

fn main() {
    prints_number(56);
}

fn prints_number(input: i32) {
    assert_eq!(input % 2, 0); // angkanya harus sama.
                              // jika angka % 2 hasilnya bukan 0, ia akan panic
    println!("The number is not odd. It is {}", input);
}

Mungkin Anda tidak berencana untuk menggunakan assert_eq! pada code Anda, namun ia digunakan dimana pun di dokumentasi Rust. Ini dikarenakan dalam sebuah dokumen Anda akan membutuhkan banyak ruang untuk mem-println! semuanya. Juga, Anda akan membutuhkan Display atau Debug untuk sesuatu yang ingin Anda cetak. Itulah mengapa dokumentasi memiliki assert_eq! dimana-mana. Berikut adalah contoh https://doc.rust-lang.org/std/vec/struct.Vec.html yang menunjukkan bagaimana cara menggunakan Vec:

fn main() {
    let mut vec = Vec::new();
    vec.push(1);
    vec.push(2);

    assert_eq!(vec.len(), 2);
    assert_eq!(vec[0], 1);

    assert_eq!(vec.pop(), Some(2));
    assert_eq!(vec.len(), 1);

    vec[0] = 7;
    assert_eq!(vec[0], 7);

    vec.extend([1, 2, 3].iter().copied());

    for x in &vec {
        println!("{}", x);
    }
    assert_eq!(vec, [7, 1, 2, 3]);
}

Pada contoh ini, Anda bisa menganggap assert_eq!(a, b) mengatakan "a sama dengan b". Sekarang lihat contoh yang telah disertai dengan komentar di sebelah kanannya. Komentar tersebut menunjukkan apa yang sebenarnya dimaksud oleh assert_eq!().

fn main() {
    let mut vec = Vec::new();
    vec.push(1);
    vec.push(2);

    assert_eq!(vec.len(), 2); // "Panjang dari vec sama dengan 2"
    assert_eq!(vec[0], 1); // "vec[0] sama dengan 1"

    assert_eq!(vec.pop(), Some(2)); // "Di saat Anda menggunakan .pop(), itu sama dengan Some(2)"
    assert_eq!(vec.len(), 1); // "sekarang panjang vec sama dengan 1"

    vec[0] = 7;
    assert_eq!(vec[0], 7); // "Vec[0] sama dengan 7"

    vec.extend([1, 2, 3].iter().copied());

    for x in &vec {
        println!("{}", x);
    }
    assert_eq!(vec, [7, 1, 2, 3]); // "isi vec sama dengan [7, 1, 2, 3]"
}

Searching

Top bar dari dokumentasi Rust adalah search bar. Ia akan mencarikan apapun yang Anda ketik. Di saat Anda men-scroll pagenya ke bawah, Anda tidak bisa melihat search barnya lagi, namun jika Anda menekan s pada keyboard, Anda akan kembali ke search bar tersebut. Sehingga menekan s di manapun memungkinkan Anda untuk langsung melakukan pencarian.

[src] button

Biasanya code untuk method, struct, dll. tidak ditampilkan secara lengkap. Ini karena Anda biasanya tidak perlu untuk melihat source code lengkapnya untuk mengetahui cara kerjanya, dan code lengkapnya bisa saja membingungkan. Tapi, jika Anda ingin mempelajarinya lebih lanjut, Anda bisa klik pada [src] dan melihat semuanya. Misalnya, pada halaman tentang String, Anda bisa melihat signature untuk .with_capacity():


#![allow(unused)]
fn main() {
// 🚧
pub fn with_capacity(capacity: usize) -> String
}

Okay, jadi Anda memasukkan angka ke dalamnya dan ia akan mengembalikan String. Ini mudah untuk dipahami, tapi mungkin saja kita penasaran dan ingin mempelajarinya lebih lanjut. Jika Anda klik pada [src], Anda bisa melihat ini:


#![allow(unused)]
fn main() {
// 🚧
pub fn with_capacity(capacity: usize) -> String {
    String { vec: Vec::with_capacity(capacity) }
}
}

Menarik! Kita bisa melihat bahwa String ternyata adalah semacam Vec. Dan sebenarnya String memanglah vector dari type u8, yang mana ini sangat menarik untuk diketahui. Anda tidak perlu mengetahui hal itu hanya untuk menggunakan method with_capacity, sehingga Anda hanya bisa melihatnya apabila Anda meng-klik [src]. Jadi, meng-klik [src] adalah ide yang bagus apabila dokumen tidak memiliki cukup detail atau Anda ingin mempelajarinya lebih lanjut.

Information on traits

Bagian terpenting dari dokumentasi mengenai trait adalah "Required Methods" pada bagian sebelah kiri. Jika Anda melihat Required Methods, itu mungkin artinya bahwa Anda harus menuliskan methodnya sendiri. Contohnya, untuk Iterator Anda perlu menuliskan method .next(). Dan untuk From, Anda perlu menuliskan method .from(). Tapi beberapa trait bisa diimplementasikan cukup dengan sebuah attribute, seperti yang kita lihat pada #[derive(Debug)]. Debug memerlukan method .fmt(), tapi biasanya Anda hanya memerlukan #[derive(Debug)], kecuali jika Anda ingin menuliskannya sendiri. Inilah mengapa pada laman std::fmt::Debug mengatakan bahwa "Generally speaking, you should just derive a Debug implementation." (Secara umum, Anda sebaiknya men-derive (menurunkan) implementasi Debug)

Easy Rust