Module System

BAB 23: Struct

Struct mengelompokkan beberapa field bernama menjadi 1 tipe, dan ukurannya di memori ditentukan jenis field serta penanda repr yang dipakai.

3 field u8, u32, dan u8 berjumlah 6 byte, tetapi struct yang memuatnya berukuran 8 byte. Selisih 2 byte itu adalah padding, dan bab ini menunjukkan cara mengukurnya sendiri lewat size_of serta offset_of.

Struct adalah tipe yang dibuat sendiri dengan field bernama. Setiap field punya nama dan tipe, dan seluruh field disimpan sebagai 1 nilai, sehingga bisa dipindah, dicetak, atau diserahkan ke fungsi sebagai satu kesatuan. Sebelum ada struct, data yang berkaitan harus dibawa sebagai beberapa variabel terpisah atau sebagai tuple yang anggotanya hanya bisa dibedakan lewat posisi.

Bab ini membahas cara mendefinisikan struct, 4 bentuk penulisan instance, 4 error yang muncul saat field salah, dan cara membaca ukuran struct di memori. Setelah bab ini selesai, kamu dapat membuat tipe sendiri untuk data yang berkelompok, memilih antara struct bernama field dan tuple struct, serta membaca E0063, E0560, E0277, E0616, dan E0382 sebagai kesalahan seputar field. Semua contoh dijalankan dengan rustc 1.100.0 pada package toko di /tmp/latihan-rust/bab23.

Mendefinisikan struct dan mengubah field

Definisi struct menuliskan nama tipe lalu daftar field di dalam kurung kurawal. Instance dibuat dengan menyebut setiap nama field beserta nilainya.

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

fn main() {
    let mut barang = Barang {
        nama: String::from("kopi"),
        harga: 2500,
        jumlah: 4,
    };

    println!("nama: {}", barang.nama);
    println!("total: {}", barang.harga * barang.jumlah);

    barang.jumlah = 6;
    println!("total setelah tambah: {}", barang.harga * barang.jumlah);
}
CodeTEXT
nama: kopi
total: 10000
total setelah tambah: 15000

Field dibaca dengan titik, misalnya barang.nama, dan penulisan field memerlukan binding yang mutable. Kata kunci mut pada let mut barang membuka izin mengubah seluruh field struct itu, karena Rust tidak punya penanda mut pada tingkat field. Kalau mut dihapus, baris barang.jumlah = 6 ditolak kompilator dengan E0594.

Nama tipe dan nama field memakai huruf kecil dengan garis bawah, sedangkan nama struct memakai CamelCase. Aturan itu punya akibat teknis: kompilator memberi peringatan non_snake_case untuk field yang ditulis dengan huruf besar.

Field init shorthand dan update syntax

Kalau nama variabel sama dengan nama field, penulisannya bisa disingkat. Kalau instance baru hampir sama dengan instance lama, field yang tidak berubah bisa diambil dengan ...

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

fn main() {
    let nama = String::from("kopi");
    let harga = 2500;
    let jumlah = 4;

    let kopi = Barang { nama, harga, jumlah };

    let tebu = Barang {
        nama: String::from("tebu"),
        harga: 3000,
        ..kopi
    };

    println!("kopi: {} x {} = {}", kopi.nama, kopi.jumlah, kopi.harga * kopi.jumlah);
    println!("tebu: {} x {} = {}", tebu.nama, tebu.jumlah, tebu.harga * tebu.jumlah);
}
CodeTEXT
kopi: kopi x 4 = 10000
tebu: tebu x 4 = 12000

Baris Barang { nama, harga, jumlah } adalah bentuk singkat dari Barang { nama: nama, harga: harga, jumlah: jumlah }. Pada tebu, field nama dan harga ditulis eksplisit, sedangkan jumlah diambil dari kopi lewat ..kopi.

Satu hal yang perlu diperhatikan: ..kopi memindahkan field yang belum diisi, dan untuk tipe yang tidak Copy seperti String pemindahan itu membuat instance lama tidak bisa dipakai utuh. Pada contoh di atas kopi masih bisa dibaca karena nama sudah diisi sendiri dan jumlah bertipe u32 yang disalin, bukan dipindah.

Tuple struct dan unit struct

Struct juga bisa ditulis tanpa nama field, dan bahkan tanpa field sama sekali. Bentuk pertama disebut tuple struct, bentuk kedua disebut unit struct.

RSRUST
struct Titik(i32, i32);

struct Meter;

fn main() {
    let awal = Titik(0, 0);
    let akhir = Titik(3, 4);

    println!("awal: ({}, {})", awal.0, awal.1);
    println!("akhir: ({}, {})", akhir.0, akhir.1);

    let satuan = Meter;
    let _ = satuan;
    println!("titik dan meter siap");
}
CodeTEXT
awal: (0, 0)
akhir: (3, 4)
titik dan meter siap

Field tuple struct diakses lewat nomor, yaitu .0 dan .1, bukan lewat nama. Bentuk ini berguna saat nama field tidak menambah informasi, misalnya koordinat atau pasangan nilai, tetapi tetap butuh tipe sendiri agar tidak tertukar dengan tuple biasa.

Unit struct tidak menyimpan data, sehingga ukurannya 0 byte. Gunanya bukan menyimpan nilai, melainkan menandai sesuatu pada tingkat tipe, misalnya satuan pengukuran atau penanda yang nanti dipakai bersama trait. Penulisan Meter tanpa kurung kurawal dan tanpa kurung biasa adalah bentuk yang benar untuk tipe seperti ini.

Field kurang atau berlebih: E0063 dan E0560

Kompilator memeriksa daftar field saat instance dibuat. 2 kesalahan yang paling sering muncul adalah field yang lupa diisi dan field yang tidak ada pada definisi.

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

fn main() {
    let kurang = Barang {
        nama: String::from("kopi"),
        harga: 2500,
    };

    let asing = Barang {
        nama: String::from("tebu"),
        harga: 3000,
        jumlah: 2,
        stok: 4,
    };

    println!("{} {}", kurang.nama, asing.nama);
}
CodeTEXT
error[E0063]: missing field `jumlah` in initializer of `Barang`
 --> uji/dua_salah.rs:8:18
  |
8 |     let kurang = Barang {
  |                  ^^^^^^ missing `jumlah`

error[E0560]: struct `Barang` has no field named `stok`
  --> uji/dua_salah.rs:17:9
   |
17 |         stok: 4,
   |         ^^^^ `Barang` does not have this field
   |
   = note: all struct fields are already assigned

error: aborting due to 2 previous errors

Kedua pesan menunjuk baris yang berbeda dan menyebut nama field yang bermasalah, sehingga perbaikannya langsung jelas. E0063 berarti ada field yang belum diberi nilai, dan di Rust tidak ada nilai default otomatis, jadi semua field wajib diisi atau diambil lewat ... E0560 berarti nama field tidak ada di definisi, biasanya karena salah ketik atau karena field itu milik struct lain.

Perhatikan catatan pada error kedua, "all struct fields are already assigned". Catatan itu muncul karena nama, harga, dan jumlah sudah lengkap, lalu ada 1 field tambahan yang tidak dikenal. Kalau struct punya field lain yang belum diisi, pesan yang muncul bisa berbeda.

Mencetak struct dengan Debug: E0277

Struct tidak bisa dicetak dengan {:?} sebelum diberi penanda #[derive(Debug)]. Program berikut mencoba mencetak instance tanpa penanda itu.

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

fn main() {
    let barang = Barang {
        nama: String::from("kopi"),
        harga: 2500,
    };

    println!("{:?}", barang);
}
CodeTEXT
error[E0277]: `Barang` doesn't implement `Debug`
  --> uji/tanpa_debug.rs:12:22
   |
12 |     println!("{:?}", barang);
   |               ----   ^^^^^^ `Barang` cannot be formatted using `{:?}` because it doesn't implement `Debug`
   |               |
   |               required by this formatting parameter
   |
   = help: the trait `Debug` is not implemented for `Barang`
help: consider annotating `Barang` with `#[derive(Debug)]`
   |
 1 + #[derive(Debug)]
 2 | struct Barang {
   |

error: aborting due to 1 previous error

Debug adalah trait yang menentukan cara nilai ditampilkan untuk keperluan debugging, dan #[derive(Debug)] membuat implementasinya secara otomatis. Tanpa trait itu, println! tidak tahu field mana yang harus dicetak dan dengan format apa, sehingga menolak seluruh perintah.

Setelah penanda ditambahkan di atas struct Barang, {:?} mencetak 1 baris padat dan {:#?} mencetak format bertingkat. Keduanya memakai nama field, jadi keluarannya jauh lebih mudah dibaca daripada tuple yang hanya menampilkan posisi.

Struct di dalam module: field juga perlu pub

Struct yang publik belum tentu field-nya publik. Kalau struct dipakai dari module lain, setiap field yang dibaca dari luar juga harus diberi pub, dan pesan errornya memakai kode tersendiri.

RSRUST
mod katalog {
    pub struct Barang {
        pub nama: String,
        harga: u32,
    }

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

fn main() {
    let barang = katalog::baru("kopi", 2500);
    println!("{}", barang.harga);
}
CodeTEXT
error[E0616]: field `harga` of struct `Barang` is private
  --> uji/privat.rs:17:27
   |
17 |     println!("{}", barang.harga);
   |                           ^^^^^ private field

error: aborting due to 1 previous error

Field nama bisa dibaca dari luar karena diberi pub, sedangkan harga tidak. Menariknya, fungsi baru di dalam module tetap boleh mengisi harga, karena kode di module yang sama tidak terkena batas privasi. Pola ini dipakai untuk menjaga nilai tetap valid: field ditutup, lalu perubahan hanya lewat fungsi yang memeriksa masukannya.

Perbaikannya 2 pilihan, yaitu menambahkan pub pada field harga, atau menambahkan fungsi publik yang mengembalikan nilai field itu. Pilihan kedua lebih aman untuk data yang punya aturan, misalnya harga yang tidak boleh negatif.

Memindahkan field String: E0382

Struct memiliki field-nya. Kalau 1 field bertipe String dipindah ke variabel lain, struct itu tidak lagi utuh, dan pemakaian seluruh struct setelahnya ditolak.

RSRUST
#[derive(Debug)]
struct Barang {
    nama: String,
    harga: u32,
}

fn main() {
    let barang = Barang {
        nama: String::from("kopi"),
        harga: 2500,
    };

    let nama = barang.nama;
    println!("{}", nama);
    println!("{:?}", barang);
}
CodeTEXT
error[E0382]: borrow of partially moved value: `barang`
  --> uji/pindah.rs:15:22
   |
13 |     let nama = barang.nama;
   |                ----------- value partially moved here
14 |     println!("{}", nama);
15 |     println!("{:?}", barang);
   |                      ^^^^^^ value borrowed here after partial move
   |
   = note: partial move occurs because `barang.nama` has type `String`, which does not implement the `Copy` trait

error: aborting due to 1 previous error

Pemindahan 1 field disebut partial move, dan akibatnya struct tidak bisa dipakai sebagai nilai utuh. Field lain seperti harga masih bisa dibaca, karena u32 disalin bukan dipindah, tetapi println!("{:?}", barang) membutuhkan seluruh struct dan itulah yang ditolak.

Perbaikannya memakai barang.nama.clone() kalau nama memang dibutuhkan di 2 tempat, atau meminjam dengan &barang.nama kalau hanya perlu dibaca. Aturan peminjaman dan pemindahan dibahas lebih dalam pada bab ownership, dan contoh di atas adalah bentuk paling sederhana dari masalah yang akan muncul lagi di sana.

Ukuran struct dan padding

Ukuran struct bukan jumlah ukuran field-nya. Untuk membuktikannya, program berikut mencetak ukuran 2 struct dengan field sama tetapi penanda berbeda, sekaligus offset setiap field.

RSRUST
use std::mem::{offset_of, size_of};

struct A {
    a: u8,
    b: u32,
    c: u8,
}

#[repr(C)]
struct C {
    a: u8,
    b: u32,
    c: u8,
}

fn main() {
    println!("A: ukuran {}", size_of::<A>());
    println!("  a di offset {}", offset_of!(A, a));
    println!("  b di offset {}", offset_of!(A, b));
    println!("  c di offset {}", offset_of!(A, c));

    println!("C: ukuran {}", size_of::<C>());
    println!("  a di offset {}", offset_of!(C, a));
    println!("  b di offset {}", offset_of!(C, b));
    println!("  c di offset {}", offset_of!(C, c));

    println!("jumlah ukuran field: {}", size_of::<u8>() + size_of::<u32>() + size_of::<u8>());
}
CodeTEXT
A: ukuran 8
  a di offset 4
  b di offset 0
  c di offset 5
C: ukuran 12
  a di offset 0
  b di offset 4
  c di offset 8
jumlah ukuran field: 6

Hasil itu menunjukkan 3 hal yang tidak terlihat dari definisi struct. Pertama, struct A menempatkan b di offset 0 dan a di offset 4, jadi urutan di memori tidak mengikuti urutan penulisan. Kedua, struct C dengan penanda #[repr(C)] mempertahankan urutan tulis, tetapi menyisipkan 3 byte padding setelah a agar b sejajar pada alamat kelipatan 4, sehingga ukurannya 12 byte. Ketiga, jumlah ukuran field hanya 6 byte, sedangkan struct terkecil yang memuatnya tetap 8 byte karena ukuran nilai selalu kelipatan alignment-nya.

Reference Rust menjelaskan bahwa ukuran nilai mencakup padding alignment, dan alignment menentukan alamat yang sah untuk menyimpan nilai. Untuk data yang hanya dipakai di dalam program Rust, urutan field tidak perlu dipikirkan. Kalau struct harus dibaca program lain lewat antarmuka C, penanda #[repr(C)] yang membuat susunannya bisa diprediksi, dan biaya padding-nya adalah harga yang dibayar untuk kepastian itu.

Latihan

  1. Buat struct Buku berisi judul: String, halaman: u32, dan tahun: u32. Buat 2 instance, lalu cetak judul dan jumlah halaman per tahun untuk keduanya.
  2. Buat instance ketiga dengan update syntax dari instance pertama, ubah judul dan tahun, lalu pastikan instance pertama masih bisa dipakai.
  3. Hapus #[derive(Debug)] dari salah satu struct, jalankan rustc, dan kutip baris bantuan yang ditawarkan kompilator.
  4. Cetak size_of untuk struct berisi u8, u64, dan u16 tanpa penanda, lalu dengan #[repr(C)]. Jelaskan selisihnya memakai angka offset dari offset_of!.

Ringkasan

Struct mengelompokkan field bernama menjadi 1 tipe, dan instance-nya dibuat dengan menyebut setiap field atau memakai singkatan serta .. untuk field yang diambil dari instance lain. Field hanya bisa diubah kalau binding-nya mut, dan struct yang dipakai dari module lain membutuhkan pub pada field yang dibaca dari luar. Ukuran struct di memori mengikuti alignment, bukan jumlah ukuran field, sehingga struct 3 field pada contoh di atas memakai 8 byte dan #[repr(C)] menaikkannya menjadi 12 byte.

Referensi

  1. The Rust Programming Language. Defining and Instantiating Structs.
  2. The Rust Reference. Structs.
  3. The Rust Reference. Type layout.
  4. The Rust Programming Language. Derivable Traits.