Rust datatypes: Difference between revisions

From wikinotes
 
(46 intermediate revisions by the same user not shown)
Line 1: Line 1:
Rust does not use null, instead is uses <code>Option</code> and <code>Result</code>.
= Documentation =
= Documentation =
<blockquote>
<blockquote>
Line 4: Line 6:
|-
|-
| primitives || https://doc.rust-lang.org/std/#primitives
| primitives || https://doc.rust-lang.org/std/#primitives
|-
| custom smart pointers || https://doc.rust-lang.org/stable/book/ch15-02-deref.html
|-
|-
|}
|}
Line 52: Line 56:
let mut user = String::new();  // utf8 string
let mut user = String::new();  // utf8 string


// type casting 'string' to 'i8'
// type casting '&str' to 'i8'
let num: i8 = "123"
let num: i8 = "123"
   .parse()
   .parse()
   .unwrap();
   .unwrap();
"foo".to_string() // type cast '&str' to 'String' (heap)
</syntaxhighlight>
</syntaxhighlight>


Line 62: Line 68:
"abc".len()            // 3  number of bytes used
"abc".len()            // 3  number of bytes used
"abc".ends_with("bc")  // true if ends with
"abc".ends_with("bc")  // true if ends with
// bytes-array to &str
let hello_bytes: [u8; 5] = [72, 69, 76, 76, 79];
let hello = std::str::from_utf8(&hello_bytes[..]).unwrap(); // 'HELLO'
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- str -->
</blockquote><!-- str -->
Line 81: Line 91:


<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">
let mut mystr = String::from("foo")
let mut my_str = String::from("foo")
mystr.push("bar!");  // foobar!
let mut my_str = "foo".to_string()
 
my_str.as_str(); // get string-slice from string (reference)
 
// string concatenation
my_str.push_str("bar");  // foobar   (push &str)
my_str.push('!')        // foobar!  (push char)
 
let s1 = String::from("foo")
let s2 = String::from("bar")
let s3 = s1 + &s2            // 's1' dropped, b/c ownership changes
let s3 = format!("{s1}{s2}") // 's1' not dropped, b/c params are references
 
 
</syntaxhighlight>
 
partial strings, and representation. See [https://doc.rust-lang.org/book/ch08-02-strings.html#bytes-and-scalar-values-and-grapheme-clusters-oh-my representation types]<br>
to final representation applying diacritics is not in standard library.
<syntaxhighlight lang="rust">
// utf-8 has multibyte `scalar` characters
// `scalar` characters may be `diacritics`,
// intended as modifiers for characters that follow.
let s: &str = &name[0..4]    // str from first 4x bytes (panic if not full unicode glyph)
"123".chars()                // enumerable of `scalar` chars (incl. diacritics)
"123".bytes()                // enumerable of `bytes` for chars
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- String -->
</blockquote><!-- String -->
Line 117: Line 152:
u36  // 0..4294967295
u36  // 0..4294967295
u64  // ...
u64  // ...
u128  
u128
usize // your CPU wordsize (ex. u32 or u64)
usize // your CPU wordsize (ex. u32 or u64)
</syntaxhighlight>
</syntaxhighlight>
Line 211: Line 246:
let v: Vec<i32> = Vec::new();
let v: Vec<i32> = Vec::new();
let v = vec![1, 2, 3, 4, 5];
let v = vec![1, 2, 3, 4, 5];
v[0]      // get value at index 0 (and panic if index is invalid)
v.get(0)  // return an Option (don't panic if index is invalid)
v.push(34) // append to vector
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- vectors -->
</blockquote><!-- vectors -->
Line 216: Line 255:
== structs ==
== structs ==
<blockquote>
<blockquote>
Struct is either entirely mutable, or entirely immutable.<br>
Structs, along with each of their fields, are private by default.<br>
You cannot make some fields mutable and others not.
To access outside of their module structs/fields must be defined with the <code>pub</code> keyword.
 
Structs can contain references to objects owned by others.


=== Regular Structs ===
=== Regular Structs ===
Line 284: Line 321:
println!("{:#?}", p); // pretty-print struct
println!("{:#?}", p); // pretty-print struct
dbg!(p)              // prints the file, lineno, expression, and result
dbg!(p)              // prints the file, lineno, expression, and result
</syntaxhighlight>
Access Control
<syntaxhighlight lang="rust">
# users.rs
pub struct User {  // `struct` is public, so type can be returned outside of module
    pub id u8,      // `id` is public, outside of module can access
    name String,    // `name` is private, outside of module cannot assign or access
}
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- General -->
</blockquote><!-- General -->
</blockquote><!-- structs -->
</blockquote><!-- structs -->
</blockquote><!-- Collections -->


= Pointers =
== enums ==
<blockquote>
== Pointers ==
<blockquote>
<blockquote>
{{ TODO |
* are enums ordered? can you compare using < ?
* how to retrieve tuple/struct from enum outside of a match ?
}}


</blockquote><!-- Pointers -->
=== Enum Basics ===
 
== Function Pointers ==
<blockquote>
 
</blockquote><!-- Function Pointers -->
 
== References ==
<blockquote>
<blockquote>
Enums in rust are used to enumerate all possible values,<br>
but unlike many other languages, they can be parametrized and bind an arbitrary value.<br>
memory for enums will be allocated in chunks of the largest possible enum value.


</blockquote><!-- References -->
</blockquote><!-- Pointers -->
= Other =
<blockquote>
== Enums ==
<blockquote>
<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">
enum TaskStatus {
enum TaskStatus {
Line 322: Line 358:
</syntaxhighlight>
</syntaxhighlight>


You can add enum-values to current scope (without namespace) with <code>use</code> keyword.
<syntaxhighlight lang="rust">
use TaskStatus::*;
let foo = Blocked;
use TaskStatus::{Blocked, Ready};
let foo = Blocked;
let bar = Started;  // raises error, since not in scope
</syntaxhighlight>
You can cast enums to integers
<syntaxhighlight lang="rust">
let index = TaskStatus::Ready as u32;  // 1
</syntaxhighlight>
</blockquote><!-- Basics -->
=== Enum Params ===
<blockquote>
You can also store complex information in an enum,<br>
You can also store complex information in an enum,<br>
enumerating possible objects.
encoding additional information with each possible enum value.
<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">
enum Event {
enum Event {
   KeyPress(char),            // like tuple-struct
   KeyPress(char),            // wrapped type is tuple
   Click { x: i32, y: i32 },  // like c-structs
   Click { x: i32, y: i32 },  // wrapped type is struct
   Blue = 0x0000ff,          // assign value
   Blue = 0x0000ff,          // wrapped type is primitive
}
}


Event::KeyPress('j')
Event::KeyPress('j')
Event::Click{x: 100, y: 900}
</syntaxhighlight>
You can use the <code>match</code> keyword to extract information from these parametrized enum values.
<syntaxhighlight lang="rust">
#[derive(Debug)]
enum Pets {
    Cat(String, u8),
    Dog(String, u8, String),
}
let pet = Pets::Cat("maize", 1)
let result = match pet {
    Pets::Cat(name, age)        => { format!("A cat w/ name={name} age={age}", name=name, age=age) },
    Pets::Dog(name, age, breed) => { format!("A {breed} dog, name={name}, age={age}", name=name, age=age, breed=breed) }
}
// "A cat w/ name=maize age=1"
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Enum Params -->
=== Methods ===
<blockquote>
Like with structs, you can bind [[rust methods]] to enums.


Scoping with <code>use</code>
<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">
use TaskStatus::*;
enum Status {
let foo = Blocked;
    Ready,
    Started,
    Skipped,
    Completed,
}
 
impl Status {
    fn finished(&self) -> bool {
        match *self {
            Status::Completed | Status::Skipped => true;
            _ => false;
        }
    }
}


use TaskStatus::{Blocked, Ready};
let s = Status::Skipped;
let foo = Blocked;
println!("{}", s.finished)
let bar = Started;  // raises error, since not in scope
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Methods -->
</blockquote><!-- Enums -->
</blockquote><!-- Enums -->
== hashmaps ==
<blockquote>
* homogenous
* heap allocated
* un-ordered
* objects implementing <code>Copy</code> trait will be copied, otherwise ownership given to map
https://doc.rust-lang.org/std/collections/struct.HashMap.html
<syntaxhighlight lang="rust">
use std::collections::HashMap;
let mut users = HashMap::new();
users.insert(0, "will");            // add/override entry to hash
users.entry(1).or_insert("alex");  // add entry to hash if not exist
let v: Option<&i32> = users.get(&0) // get entry from hash
for (key, val) in &users { ... }    // iterate over entries
</syntaxhighlight>
</blockquote><!-- hashmaps -->
</blockquote><!-- Collections -->
= Pointers =
<blockquote>
The basics are similar to most other languages:
<syntaxhighlight lang="rust">
let foo = String::new("hi");  // allocated on the heap
&foo                          // `&` get reference to foo
let myref = &foo;
*myref                        // `*` de-reference to get foo instance
</syntaxhighlight>
However, mostly due to rust's ownership concepts there are some other semantics to handle edge cases.<br>
See [[rust pointers]] for more details.
</blockquote><!-- Pointers -->
= Other =
<blockquote>
== Option ==
<blockquote>
The Option type (enum) stands in for <code>null</code> in rust.<br>
It is commonly used with <code>match</code> to extract the values.<br>
It's methods are added to the prelude scope, so they are accessible without the namespace.
https://doc.rust-lang.org/std/option/enum.Option.html
<syntaxhighlight lang="rust">
let val = Some("foo");  // `Option` instance, with value present
let val = None;          // `Option` instance, standin for null
match val {
    Some(x) => println!("value was assigned"),    // `x` here refers to whatever value is held by `Some`
    None    => println!("value was not assigned"),
}
</syntaxhighlight>
</blockquote><!-- Option -->


== Result ==
== Result ==
<blockquote>
<blockquote>
Results are chainable enums with success/failure values.
Results are chainable enums with success/failure values.<br>
For more details see [[rust errors]].


<syntaxhighlight lang="rust">
<syntaxhighlight lang="rust">

Latest revision as of 00:21, 10 February 2023

Rust does not use null, instead is uses Option and Result.

Documentation

primitives https://doc.rust-lang.org/std/#primitives
custom smart pointers https://doc.rust-lang.org/stable/book/ch15-02-deref.html

Literals

General

'a'        // char
"abc"      // string (immutable)
1234       // i32
3.14       // f32
true/false // bool

Numeric Representations

1_000      // == 1000
1.000_000  // == 1.000000

0xff          // hex
Oo644         // octal
0b1111_0000   // binary
b'A'          // byte (u8)

Type Suffixes

1u8          // '1' as a u8
1i64         // '1' as a i64

Primitives

Text

str

  • immutable
  • size-known at compile-time

https://doc.rust-lang.org/std/primitive.str.html

let name: &str = "vaderd";     // assign string
let mut user = String::new();  // utf8 string

// type casting '&str' to 'i8'
let num: i8 = "123"
  .parse()
  .unwrap();

"foo".to_string() // type cast '&str' to 'String' (heap)

Some Useful Methods

"abc".len()            // 3  number of bytes used
"abc".ends_with("bc")  // true if ends with

// bytes-array to &str
let hello_bytes: [u8; 5] = [72, 69, 76, 76, 79];
let hello = std::str::from_utf8(&hello_bytes[..]).unwrap(); // 'HELLO'

char

chars refer to a single character, and it's literals use single-quotes.
chars use 4-bytes in memory; they can store multibyte characters.

https://doc.rust-lang.org/std/primitive.char.html

let foo: char = 'a';

String

String types are strings with a string-size that is unknown at compile-time.

let mut my_str = String::from("foo")
let mut my_str = "foo".to_string()

my_str.as_str(); // get string-slice from string (reference)

// string concatenation
my_str.push_str("bar");  // foobar   (push &str)
my_str.push('!')         // foobar!  (push char)

let s1 = String::from("foo")
let s2 = String::from("bar")
let s3 = s1 + &s2            // 's1' dropped, b/c ownership changes
let s3 = format!("{s1}{s2}") // 's1' not dropped, b/c params are references

partial strings, and representation. See representation types
to final representation applying diacritics is not in standard library.

// utf-8 has multibyte `scalar` characters
// `scalar` characters may be `diacritics`, 
// intended as modifiers for characters that follow.
 
let s: &str = &name[0..4]    // str from first 4x bytes (panic if not full unicode glyph)
"123".chars()                // enumerable of `scalar` chars (incl. diacritics)
"123".bytes()                // enumerable of `bytes` for chars

Numbers

implied type let var = 12;
assigned type let var: i8 = 12;
type suffix let var = 12i8;

int

  • signed integers range is split in two, can be positive/negative
  • unsigned integers are positive, and use all available bits
  • use radix to calculate max size that can be accomodated with b bits
// signed integers, by bit-size
i8     //        -128..127
i16    //      -32768..32767
i32    // -2147483648..2147483647
i64    // ...
i128
isize  // your CPU wordsize (ex. i32 or i64)

// unsigned integers, by bit-size
u8    // 0..255
u16   // 0..65535
u36   // 0..4294967295
u64   // ...
u128
usize // your CPU wordsize (ex. u32 or u64)

float

f32
f64

bool

true
false

fn foo(b: bool) { ... }

Collections

tuples

  • heterogenous
  • non-resizable
  • not stored in contiguous memory
  • support nesting

https://doc.rust-lang.org/std/primitive.tuple.html#

let var: (i8, char, u32) = (5, 'a', 300);
var = (1, "two", 3.14)
var.0  // item at index 1

arrays

  • homogenous
  • non-resizable
  • stored in contiguous memory

https://doc.rust-lang.org/std/primitive.array.html

// initialization
let var: [i32; 4] = [1, 2, 3, 4];  // declare an array of 4x 32-bit integers
let var: [i32; 4] = [100; 4];      // initialize all 4x ints as 100

// methods
var[0]     // 1
var.len()  // 4

// slices
let foo = &var[1..2];   // [2, 3]
println!("{}", foo[0]); // 2

slices

slices are a subsection of an array

let var: [i8; 4] = [1, 2, 3, 4];

let first_two = &var[0..1];   // [1, 2]
let first_two = &var[..1];    // [1, 2]
println!("{}", foo[0]); // 2

fn foo(s: &[i32]) { ... }               // borrows slice of an i32 array
fn foo(s: String) -> &str { ... }       // returns slice of String
fn foo(nums: &[usize; 10]) -> &[usize]  // returns slice of array (slice indexes always usize)

vectors

vectors are essentially resizable arrays.

  • homogenous
  • resizable
  • stored in contiguous memory

https://doc.rust-lang.org/std/vec/index.html

let v: Vec<i32> = Vec::new();
let v = vec![1, 2, 3, 4, 5];

v[0]       // get value at index 0 (and panic if index is invalid)
v.get(0)   // return an Option (don't panic if index is invalid)
v.push(34) // append to vector

structs

Structs, along with each of their fields, are private by default.
To access outside of their module structs/fields must be defined with the pub keyword.

Regular Structs

struct Point { x: u8, y: u8 }
let p: Point = Point { x: 5, y: 10 };  // assignment
println!("point({}, {})", p.x, p.y);   // access fields with '.'

Structs have syntactic sugar so that you can reuse parameters for assignment.

struct Coord { x: u8, y: u8, z: u8 };
fn build_coord_at_x0(x: u8, y: u8) {
    Coord{
        x: 0,
        y,
        z
    }  // bind `y`, `z` values from matching params
}

There is also syntactic sugar for creating a struct from another of the same type,
only replacing select values.

struct Coord { x: u8, y: u8, z: u8 };

let p1 = Coord{x: 1, y: 2, z: 3};
let p2 = Coord{x: 5, ..p1};         // reuse fields from `p1` for all values except `x`

Tuple Structs

struct Color(i8, i8, i8);             // declaration
let c: Color = Color(100, 150, 200);  // instantiation
c.1 = 200;                            // assignment (uses `.` index)

Unit Structs

Unit structs have no value, they're just a type.

struct Centimeters;
let cm = Centimeters;

General

TODO:

not sure this really belongs here..

Debug trait

#[derive(Debug)]
struct Point{x: i8, y: i8}
let p = Point{x: 1, y: 2};

println!("{:?}", p);  // print all fields on struct
println!("{:#?}", p); // pretty-print struct
dbg!(p)               // prints the file, lineno, expression, and result

Access Control

# users.rs
pub struct User {   // `struct` is public, so type can be returned outside of module
    pub id u8,      // `id` is public, outside of module can access
    name String,    // `name` is private, outside of module cannot assign or access
}

enums

TODO:

  • are enums ordered? can you compare using < ?
  • how to retrieve tuple/struct from enum outside of a match ?

Enum Basics

Enums in rust are used to enumerate all possible values,
but unlike many other languages, they can be parametrized and bind an arbitrary value.
memory for enums will be allocated in chunks of the largest possible enum value.

enum TaskStatus {
  Blocked,
  Ready,
  Started,
  Finished,
}

TaskStatus::Ready

You can add enum-values to current scope (without namespace) with use keyword.

use TaskStatus::*;
let foo = Blocked;

use TaskStatus::{Blocked, Ready};
let foo = Blocked;
let bar = Started;  // raises error, since not in scope

You can cast enums to integers

let index = TaskStatus::Ready as u32;  // 1

Enum Params

You can also store complex information in an enum,
encoding additional information with each possible enum value.

enum Event {
  KeyPress(char),            // wrapped type is tuple
  Click { x: i32, y: i32 },  // wrapped type is struct
  Blue = 0x0000ff,           // wrapped type is primitive
}

Event::KeyPress('j')
Event::Click{x: 100, y: 900}

You can use the match keyword to extract information from these parametrized enum values.

#[derive(Debug)]
enum Pets {
    Cat(String, u8),
    Dog(String, u8, String),
}
let pet = Pets::Cat("maize", 1)

let result = match pet {
    Pets::Cat(name, age)        => { format!("A cat w/ name={name} age={age}", name=name, age=age) },
    Pets::Dog(name, age, breed) => { format!("A {breed} dog, name={name}, age={age}", name=name, age=age, breed=breed) }
}
// "A cat w/ name=maize age=1"

Methods

Like with structs, you can bind rust methods to enums.

enum Status {
    Ready,
    Started,
    Skipped,
    Completed,
}

impl Status {
    fn finished(&self) -> bool {
        match *self {
            Status::Completed | Status::Skipped => true;
            _ => false;
        }
    }
}

let s = Status::Skipped;
println!("{}", s.finished)

hashmaps

  • homogenous
  • heap allocated
  • un-ordered
  • objects implementing Copy trait will be copied, otherwise ownership given to map

https://doc.rust-lang.org/std/collections/struct.HashMap.html

use std::collections::HashMap;

let mut users = HashMap::new();

users.insert(0, "will");            // add/override entry to hash
users.entry(1).or_insert("alex");   // add entry to hash if not exist
let v: Option<&i32> = users.get(&0) // get entry from hash
for (key, val) in &users { ... }    // iterate over entries

Pointers

The basics are similar to most other languages:

let foo = String::new("hi");  // allocated on the heap
&foo                          // `&` get reference to foo

let myref = &foo;
*myref                        // `*` de-reference to get foo instance

However, mostly due to rust's ownership concepts there are some other semantics to handle edge cases.
See rust pointers for more details.

Other

Option

The Option type (enum) stands in for null in rust.
It is commonly used with match to extract the values.
It's methods are added to the prelude scope, so they are accessible without the namespace.

https://doc.rust-lang.org/std/option/enum.Option.html

let val = Some("foo");   // `Option` instance, with value present
let val = None;          // `Option` instance, standin for null

match val {
    Some(x) => println!("value was assigned"),     // `x` here refers to whatever value is held by `Some`
    None    => println!("value was not assigned"),
}

Result

Results are chainable enums with success/failure values.
For more details see rust errors.