Module System

BAB 25: Method

Method adalah fungsi di blok impl yang menerima self, dan bab ini mengukur cara meminjam, mengubah, serta memindahkan nilai lewat receiver yang dipilih.

kopi.total() dan Barang::total(&kopi) menjalankan fungsi yang sama persis. Yang membedakan hanya penulisan pemanggilannya, karena tanda & pada argumen pertama ditambahkan sendiri oleh kompilator. Kemampuan menyingkat itulah yang membuat method terasa berbeda dari fungsi biasa walaupun keduanya sama sama dideklarasikan dengan fn.

Method adalah fungsi di dalam blok impl yang parameter pertamanya berupa self, &self, atau &mut self. Pilihan receiver menentukan 3 hal sekaligus: apakah method boleh mengubah isi struct, apakah nilai aslinya dipindah, dan apakah pemanggil masih boleh memakai variabel itu setelah pemanggilan selesai. Kesalahan pemilihan receiver muncul sebagai pesan kompilator yang berbeda beda, dan 3 di antaranya dibahas di bab ini.

Setelah bab ini selesai, kamu dapat menulis method untuk tipe buatan sendiri, memilih receiver yang sesuai kebutuhan, membaca E0596, E0382, dan E0502 sebagai kesalahan receiver serta pinjaman, dan menyusun rantai method yang mengembalikan Self. Semua contoh dijalankan dengan rustc 1.100.0 pada folder /tmp/latihan-rust/bab25.

Method menerima self sebagai parameter pertama

Method ditulis di dalam impl, dan parameter pertamanya adalah receiver. Bentuk &self dipakai kalau method hanya membaca isi struct, sehingga nilai aslinya tetap utuh setelah pemanggilan.

RSRUST
struct Barang {
    nama: String,
    harga: u32,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, harga: u32, jumlah: u32) -> Self {
        Self {
            nama: String::from(nama),
            harga,
            jumlah,
        }
    }

    fn total(&self) -> u32 {
        self.harga * self.jumlah
    }

    fn label(&self) -> String {
        format!("{} x {} = {}", self.nama, self.jumlah, self.total())
    }
}

fn main() {
    let kopi = Barang::baru("kopi", 2500, 4);

    println!("{}", kopi.label());
    println!("total: {}", kopi.total());
}
CodeTEXT
kopi x 4 = 10000
total: 10000

Isi total membaca self.harga dan self.jumlah, lalu mengalikannya. Karena receiver-nya &self, kopi masih bisa dipakai pada baris berikutnya tanpa pemindahan. Method label memanggil self.total() di dalam format!, dan pemanggilan itu sah karena &self bisa dipinjam berkali kali secara bersamaan.

Tanda -> tidak dipakai untuk memanggil method. Buku resmi Rust menjelaskan bahwa pada pemanggilan object.something() kompilator otomatis menambahkan &, &mut, atau * agar objek cocok dengan tanda tangan method. Karena itu kopi.total() dan Barang::total(&kopi) sama, dan penulisan pertama yang dipakai sehari hari.

Method juga boleh punya parameter lain setelah receiver. Contohnya fn tambah(&mut self, n: u32) pada bagian berikut, yang menerima self lebih dulu lalu n. Urutan itu wajib: receiver selalu berada di posisi pertama, dan self tidak bisa ditulis sebagai parameter kedua. Nama parameter lain bebas, dan yang perlu diingat hanya bahwa self sudah menunjuk instance sehingga field bisa dibaca langsung tanpa menyebut nama variabel.

Mengubah isi dengan &mut self

Method yang mengubah field memakai receiver &mut self. Pemanggilnya wajib punya binding mutable, sebab pinjaman mutable hanya boleh diberikan pada variabel yang boleh diubah.

RSRUST
struct Barang {
    nama: String,
    harga: u32,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, harga: u32, jumlah: u32) -> Self {
        Self {
            nama: String::from(nama),
            harga,
            jumlah,
        }
    }

    fn tambah(&mut self, n: u32) {
        self.jumlah += n;
    }

    fn total(&self) -> u32 {
        self.harga * self.jumlah
    }
}

fn main() {
    let mut kopi = Barang::baru("kopi", 2500, 4);
    println!("awal: {}", kopi.total());

    kopi.tambah(2);
    println!("setelah tambah: {}", kopi.total());
}
CodeTEXT
awal: 10000
setelah tambah: 15000

Receiver &mut self membuat method ini bisa dipanggil berkali kali tanpa memindahkan nilai, asalkan tidak ada pinjaman lain yang masih hidup. Mengubah jumlah lewat self.jumlah += n sama dengan mengubah field dari luar, hanya saja aturan validasinya bisa ditaruh di dalam method itu.

Kalau mut pada binding dihapus, program ditolak sebelum dijalankan. Pesannya menyebut variabel yang dimaksud dan menawarkan 1 kata tambahan sebagai perbaikan.

RSRUST
struct Barang {
    nama: String,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, jumlah: u32) -> Self {
        Self {
            nama: String::from(nama),
            jumlah,
        }
    }

    fn tambah(&mut self, n: u32) {
        self.jumlah += n;
    }
}

fn main() {
    let kopi = Barang::baru("kopi", 4);
    kopi.tambah(2);
    println!("{} {}", kopi.nama, kopi.jumlah);
}
CodeTEXT
error[E0596]: cannot borrow `kopi` as mutable, as it is not declared as mutable
  --> uji/salah_mut.rs:21:5
   |
21 |     kopi.tambah(2);
   |     ^^^^ cannot borrow as mutable
   |
help: consider changing this to be mutable
   |
20 |     let mut kopi = Barang::baru("kopi", 4);
   |         +++

error: aborting due to 1 previous error

For more information about this error, try `rustc --explain E0596`.

E0596 menunjuk baris pemanggilan, bukan baris deklarasi, karena di situlah pinjaman mutable diminta. Saran +++ di bawah baris 20 menunjukkan posisi mut yang harus disisipkan. Perlu diingat bahwa mut pada binding berbeda dari mut pada parameter method: mut di binding memberi izin meminjam secara mutable, sedangkan &mut self menyatakan bahwa method memang meminta pinjaman itu.

Memakai nilai dengan self

Receiver self tanpa tanda baca memindahkan nilai ke dalam method. Setelah pemanggilan seperti itu, variabel aslinya tidak boleh dipakai lagi, kecuali tipenya implements Copy.

RSRUST
struct Barang {
    nama: String,
    harga: u32,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, harga: u32, jumlah: u32) -> Self {
        Self {
            nama: String::from(nama),
            harga,
            jumlah,
        }
    }

    fn total(&self) -> u32 {
        self.harga * self.jumlah
    }

    fn serahkan(self) -> String {
        self.nama
    }
}

fn main() {
    let kopi = Barang::baru("kopi", 2500, 4);
    let nama = kopi.serahkan();

    println!("{}", nama);
    println!("total: {}", kopi.total());
}
CodeTEXT
error[E0382]: borrow of moved value: `kopi`
  --> uji/salah_pindah.rs:30:27
   |
26 |     let kopi = Barang::baru("kopi", 2500, 4);
   |         ---- move occurs because `kopi` has type `Barang`, which does not implement the `Copy` trait
27 |     let nama = kopi.serahkan();
   |                     ---------- `kopi` moved due to this method call
...
30 |     println!("total: {}", kopi.total());
   |                           ^^^^ value borrowed here after move
   |
note: `Barang::serahkan` takes ownership of the receiver `self`, which moves `kopi`
  --> uji/salah_pindah.rs:20:17
   |
20 |     fn serahkan(self) -> String {
   |                 ^^^^

error: aborting due to 1 previous error

Pesan itu menyebut 2 baris sekaligus: baris 27 sebagai tempat nilai dipindah, dan baris 20 sebagai penyebabnya. Catatan terakhir menjelaskan bahwa serahkan mengambil alih kepemilikan receiver. Perbaikannya ada 2: ubah receiver menjadi &self lalu kembalikan self.nama.clone(), atau biarkan self dan jangan memakai kopi setelah pemanggilan.

Receiver self berguna saat method memang mengubah nilai menjadi tipe lain, misalnya mengubah struct menjadi String atau menutup koneksi. Kalau niatnya hanya membaca, &self lebih murah karena tidak ada pemindahan dan tidak ada salinan.

Bentrokan pinjaman: E0502

Pinjaman immutable dan mutable tidak boleh hidup bersamaan pada nilai yang sama. Program berikut menyimpan referensi ke 1 field, lalu memanggil method yang butuh pinjaman mutable.

RSRUST
struct Barang {
    nama: String,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, jumlah: u32) -> Self {
        Self {
            nama: String::from(nama),
            jumlah,
        }
    }

    fn tambah(&mut self, n: u32) {
        self.jumlah += n;
    }
}

fn main() {
    let mut kopi = Barang::baru("kopi", 4);

    let nama = &kopi.nama;
    kopi.tambah(2);

    println!("{} {}", nama, kopi.jumlah);
}
CodeTEXT
error[E0502]: cannot borrow `kopi` as mutable because it is also borrowed as immutable
  --> uji/salah_borrow.rs:23:5
   |
22 |     let nama = &kopi.nama;
   |                ---------- immutable borrow occurs here
23 |     kopi.tambah(2);
   |     ^^^^^^^^^^^^^^ mutable borrow occurs here
24 |
25 |     println!("{} {}", nama, kopi.jumlah);
   |                       ---- immutable borrow later used here

Kompilator menunjuk 3 baris karena ketiganya membentuk satu rantai: pinjaman dibuat di baris 22, pinjaman mutable diminta di baris 23, dan pinjaman pertama masih dipakai di baris 25. Kalau baris 25 tidak memakai nama, programnya diterima, karena pinjaman immutable terakhir dipakai sebelum baris 23.

Perbaikannya adalah memperpendek umur pinjaman, misalnya dengan memanggil tambah sebelum mengambil &kopi.nama, atau dengan menyalin nilainya lebih dulu lewat kopi.nama.clone(). Aturan ini yang membuat Rust menolak banyak program yang di bahasa lain lolos, dan bab tentang borrowing membahasnya lebih rinci.

Rantai method yang mengembalikan Self

Method bisa mengembalikan Self, sehingga pemanggilan berikutnya disambung dengan titik. Pola ini dipakai untuk menyusun nilai bertahap, dan receiver-nya biasanya mut self karena nilai itu diubah lalu dikembalikan.

RSRUST
struct Barang {
    nama: String,
    harga: u32,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, harga: u32) -> Self {
        Self {
            nama: String::from(nama),
            harga,
            jumlah: 1,
        }
    }

    fn dengan_jumlah(mut self, jumlah: u32) -> Self {
        self.jumlah = jumlah;
        self
    }

    fn dengan_harga(mut self, harga: u32) -> Self {
        self.harga = harga;
        self
    }

    fn total(&self) -> u32 {
        self.harga * self.jumlah
    }
}

fn main() {
    let kopi = Barang::baru("kopi", 2500)
        .dengan_jumlah(4)
        .dengan_harga(2400);

    println!("{} x {} = {}", kopi.nama, kopi.jumlah, kopi.total());
}
CodeTEXT
kopi x 4 = 9600

Setiap method menerima mut self, mengubah 1 field, lalu mengembalikan self sehingga nilainya berpindah ke pemanggilan berikutnya. Karena receiver diambil dengan nilai, tidak ada pinjaman yang tertinggal di antara langkah, dan hasil akhirnya tetap 1 nilai utuh. Harga 2500 ditimpa menjadi 2400 sebelum total dipanggil, sehingga keluarannya 9600, bukan 10000.

Bentuk lain dari rantai memakai &mut self yang mengembalikan &mut Self. Bedanya, nilai aslinya tetap dipegang pemanggil dan hanya dipinjam selama rantai berjalan, sehingga variabel itu harus tetap hidup sampai baris terakhir. Bentuk mut self lebih mudah dibaca karena setiap langkah menghasilkan nilai baru, sedangkan bentuk &mut Self lebih murah karena tidak ada pemindahan di antara langkah.

Beberapa blok impl

Satu tipe boleh punya lebih dari 1 blok impl. Method dari semua blok itu tetap bisa dipanggil dengan cara yang sama, dan pemisahan blok sering dipakai untuk mengelompokkan method berdasarkan kebutuhan.

RSRUST
struct Barang {
    nama: String,
    harga: u32,
    jumlah: u32,
}

impl Barang {
    fn baru(nama: &str, harga: u32, jumlah: u32) -> Self {
        Self {
            nama: String::from(nama),
            harga,
            jumlah,
        }
    }
}

impl Barang {
    fn total(&self) -> u32 {
        self.harga * self.jumlah
    }

    fn mahal(&self) -> bool {
        self.total() > 12000
    }
}

fn main() {
    let kopi = Barang::baru("kopi", 2500, 4);
    let gula = Barang::baru("gula", 15000, 1);

    println!("{} mahal: {}", kopi.nama, kopi.mahal());
    println!("{} mahal: {}", gula.nama, gula.mahal());
}
CodeTEXT
kopi mahal: false
gula mahal: true

Blok pertama memuat konstruktor, blok kedua memuat method pembacaan. mahal memanggil self.total() yang didefinisikan di blok yang sama, dan pemanggilan itu juga sah kalau total berada di blok lain. Yang tidak boleh adalah mendefinisikan 2 method dengan nama sama pada tipe yang sama, walaupun keduanya berada di blok berbeda.

Blok impl juga dipakai untuk implementasi trait, misalnya impl Default for Barang, dan blok semacam itu boleh berdampingan dengan blok impl Barang biasa. Bedanya, method dari impl Trait for Tipe hanya bisa dipanggil kalau trait-nya sudah diimpor di tempat pemanggilan. Pemisahan blok karena itu punya akibat teknis: ia menandai mana method milik tipe itu sendiri dan mana method yang datang dari kontrak trait.

Panjang byte dan jumlah karakter

Method len pada str mengembalikan panjang dalam byte, bukan jumlah karakter. Karena str menyimpan UTF-8, 2 teks yang terlihat sama panjang bisa menghasilkan angka berbeda.

RSRUST
fn main() {
    let a = "kopi";
    let b = "café";

    println!("{}: len {} chars {}", a, a.len(), a.chars().count());
    println!("{}: len {} chars {}", b, b.len(), b.chars().count());
}
CodeTEXT
kopi: len 4 chars 4
café: len 5 chars 4

Huruf é memakai 2 byte dalam UTF-8, sehingga len melaporkan 5 sementara chars().count() melaporkan 4. Dokumentasi str::len menuliskan hal itu secara eksplisit: "This length is in bytes, not chars or graphemes". Untuk memotong teks berdasarkan jumlah karakter, len tidak bisa dipakai sebagai indeks, dan pembahasan pemotongan aman ada di bab tentang string.

chars() mengembalikan iterator, bukan angka, sehingga jumlah karakter baru diketahui setelah count() dijalankan. Iterator itu juga yang dipakai untuk mengolah teks per karakter, misalnya membalik urutan huruf, sementara len hanya berguna untuk hal yang memang dihitung dalam byte seperti ukuran buffer atau alokasi.

Pemilihan receiver juga terlihat pada kedua method itu: len(&self) dan chars(&self) sama sama meminjam, sehingga variabel b masih bisa dipakai pada baris berikutnya. Kalau salah satunya memakai self, String akan berpindah dan baris kedua tidak lagi bisa dijalankan.

Latihan

  1. Tambahkan method diskon(&mut self, persen: u8) yang mengurangi harga sesuai persen, lalu panggil 2 kali dan cetak hasilnya.
  2. Ubah serahkan pada contoh E0382 menjadi fn nama(&self) -> &str, lalu jelaskan mengapa kopi masih bisa dipakai setelah pemanggilan.
  3. Tulis rantai method Barang::baru("teh", 5000).dengan_jumlah(3) tanpa method total, lalu tambahkan 1 method lagi yang mengembalikan Self untuk mengubah nama.
  4. Panggil method &mut self pada variabel tanpa mut, jalankan rustc, dan kutip baris bantuan yang muncul.

Ringkasan

Method adalah fungsi di dalam impl yang menerima self, &self, atau &mut self, dan pemanggilannya memakai titik karena kompilator menambahkan tanda baca pada receiver secara otomatis. Receiver &self hanya membaca sehingga nilai tetap utuh, &mut self mengubah isi dan menuntut binding mutable, sedangkan self memindahkan nilai sehingga pemakaian berikutnya ditolak dengan E0382. Binding tanpa mut menghasilkan E0596, dan pinjaman immutable yang masih hidup saat method mutable dipanggil menghasilkan E0502. Method yang mengembalikan Self bisa dirangkai, dan str::len pada teks café melaporkan 5 byte untuk 4 karakter.

Referensi

  1. The Rust Programming Language. Method Syntax.
  2. The Rust Reference. Associated items.
  3. Rust Standard Library. str, method len dan chars.