DEV Community: Rodrigo Santiago

Implementing the Display Trait on a Generic Array using Newtype Pattern

Rodrigo Santiago — Sun, 25 Sep 2022 19:01:13 +0000

Edit: In the original post I said that the PartialEq trait bound was required in the generic Display function implementation; however, if the last element of the array is the same as its predecessor then the function will not print properly. Thanks to korrat for letting me know and for the recommendation to use std::ptr::eq instead.

Probably one of the first things that someone does when learning a new programming language is to implement the famous "Hello, world!" message, which in the case of Rust comes with the boilerplate code via the cargo new command:

fn main() {
    println!("Hello, world!");
}

And then, start experimenting on how to display different types in the terminal, like strings, integers, floats, etc.:

fn main() {
    let planet = "Earth";
    let surface_area = 510072000;
    let polar_radius = 6356.752;
    println!(
        "Hello, {}!\nSurface area: {}\nPolar radius: {}",
        planet, surface_area, polar_radius
    );
}

λ cargo run -q
Hello, Earth!
Surface area: 510072000
Polar radius: 6356.752

In Rust it's pretty straightforward until we try to print a struct or other user-defined types:

struct Planet {
    name: String,
    surface_area: i64,
    polar_radius: f64,
}

fn main() {
    let planet = Planet {
        name: "Earth".to_string(),
        surface_area: 510072000,
        polar_radius: 6356.752,
    };
    println!("{}", planet);
}

The compiler yields an error and advice:

 λ cargo run -q
error[E0277]: `Planet` doesn't implement `std::fmt::Display`
  --> src/main.rs:20:20
   |
20 |     println!("{}", planet);
   |                    ^^^^^^ `Planet` cannot be formatted with the default formatter
   |
   = help: the trait `std::fmt::Display` is not implemented for `Planet`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead
   = note: this error originates in the macro `$crate::format_args_nl` (in Nightly builds, run with -Z macro-backtrace for more info)

For more information about this error, try `rustc --explain E0277`.
error: could not compile `temp` due to previous error

What's happening here?

The Debug and Display traits

The compiler is basically saying that it doesn't know how to print the struct Planet type.

However, it's providing two alternatives:

Use the built-in formatters with {:?} or {:#?} in the println! macro, which requires implementing the Debug trait on the struct Planet type, or
Implement the std::fmt::Display trait and define the formatter for the type.

Let's review both alternatives in more detail.

First, the Debug trait can be implemented using the #[derive(Debug)] attribute:

#[derive(Debug)]
struct Planet {
    name: String,
    surface_area: i64,
    polar_radius: f64,
}

fn main() {
    let planet = Planet {
        name: "Earth".to_string(),
        surface_area: 510072000,
        polar_radius: 6356.752,
    };
    println!("{:?}", planet);
    println!("{:#?}", planet);
}

And when running the program, the struct Planet type is printed using the built-in formatters provided by the Debug trait:

λ cargo run -q
Planet { name: "Earth", surface_area: 510072000, polar_radius: 6356.752 }
Planet {
    name: "Earth",
    surface_area: 510072000,
    polar_radius: 6356.752,
}

On the other hand, implementing the Display trait isn't as straightforward as Debug, but can be accomplished by bringing std::fmt::Display into scope and writing an impl block for the struct Planet type, which defines the custom formatter in the fn fmt(...) function:

use std::fmt::Display;

struct Planet {
    name: String,
    surface_area: i64,
    polar_radius: f64,
}

impl Display for Planet {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "-> {}:\n\tSurface: {} km2\n\tPolar radius: {} km",
            self.name, self.surface_area, self.polar_radius
        )
    }
}

fn main() {
    let planet = Planet {
        name: "Earth".to_string(),
        surface_area: 510072000,
        polar_radius: 6356.752,
    };
    println!("{}", planet);
}

Implementing Display allows the definition of a custom printing format for the type:

λ cargo run -q
-> Earth:
    Surface: 510072000 km2
    Polar radius: 6356.752 km

Arrays and the 'Orphan Rule'

Now, let's try to follow the same steps but with an Array…

First, by defining an array of four f64 elements and trying to print it with println!:

type MyArray = [f64; 4];

fn main() {
    let my_array: MyArray = [1.5, 2.5, 3.5, 4.5];
    println!("{}", my_array);
}

The compiler yields the same error code and advice for the Array type, just as it did for the struct type:

 λ cargo run -q
error[E0277]: `[f64; 4]` doesn't implement `std::fmt::Display`
  --> src/main.rs:25:20
   |
25 |     println!("{}", my_array);
   |                    ^^^^^^^^ `[f64; 4]` cannot be formatted with the default formatter
   |
   = help: the trait `std::fmt::Display` is not implemented for `[f64; 4]`
   = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead
   = note: this error originates in the macro `$crate::format_args_nl` (in Nightly builds, run with -Z macro-backtrace for more info)

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

Following the compiler's guidance and using the built-in "{:?}" and "{:#?}" formatters works, just like with the struct type, and the array is printed:

 λ cargo run -q
[1.5, 2.5, 3.5, 4.5]
[
    1.5,
    2.5,
    3.5,
    4.5,
]

Great!

Now, let's try to define a custom formatter via the Display trait for the Array type, just as we did with the struct:

type MyArray = [f64; 4];

impl Display for MyArray {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}, {}, {}, {}", self[0], self[1], self[2], self[3])
    }
}

fn main() {
    let my_array: MyArray = [1.5, 2.5, 3.5, 4.5];
    println!("{}", my_array);
}

 λ cargo run -q
error[E0117]: only traits defined in the current crate can be implemented for arbitrary types
  --> src/main.rs:25:1
   |
25 | impl Display for MyArray {
   | ^^^^^^^^^^^^^^^^^-------
   | |                |
   | |                this is not defined in the current crate because arrays are always foreign
   | impl doesn't use only types from inside the current crate
   |
   = note: define and implement a trait or new type instead

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

Ups! Unfortunately, this doesn't work like it did with the struct type.

Looking closely at the compiler feedback, it's complaining that arrays are always foreign types.

If we run rustc --explain E0117 the compiler provides additional details about what is happening here:

This error indicates a violation of one of Rust's orphan rules for trait
implementations. The rule prohibits any implementation of a foreign trait (a
trait defined in another crate) where

 - the type that is implementing the trait is foreign
 - all of the parameters being passed to the trait (if there are any) are also
   foreign.

To avoid this kind of error, ensure that at least one local type is referenced
by the `impl`...

It turns out that by implementing Display on any Array we're violating Rust's Orphan Rule which essentially forbid implementing a foreign trait on a foreign type.

A foreign type or trait is that which isn't local to our crate.

A local type or trait is that which is defined in our crate.

So, to overcome the Orphan Rule we must either:

Implement a local trait on a foreign type: impl MyCustomTrait for Vec<T>, or
Implement a foreign trait on a local type: impl Display for MyStruct.

Because the struct Planet was a type defined in our crate we were able to implement Display, a foreign trait, for it.

However, even if we define an Array in our crate, like we did with MyArray above, Rust will always treat arrays as a foreign type.

Display will always be a foreign trait and any Array that we define locally in our crate will always be a foreign type…

What can be done?

The Newtype Pattern to the rescue

According to the Rust Programming Language book, the Newtype pattern comes from the Haskell Programming Language Newtype, and the idea is to essentially define a local wrapper type that encloses the foreign type in order to implement the foreign trait for the wrapper.

So, in a summary:

Define a new Wrapper type local to the crate.
Include the foreign type as an element of the Wrapper type.
Implement the foreign trait for the Wrapper type.

One convenient approach is to use a thin wrapper, that's a Wrapper type that provides a straightforward way to get to the enclosed or wrapped type with minimum friction.

A Tuple Struct is a suitable thin wrapper type:

type MyArray = [f64; 4];

struct Wrap(MyArray);

It's not verbose, not redundant and allows a straightforward access to the underlying type with wrap.0:

fn main() {
    let my_array: MyArray = [1.5, 2.5, 3.5, 4.5];
    let my_wrap = Wrap(my_array);
    println!("{:?}", my_wrap.0)
}

λ cargo run -q
[1.5, 2.5, 3.5, 4.5]

Now it's possible to implement the foreign Display trait for the local Wrap type that encloses the foreign Array type:

type MyArray = [f64; 4];

struct Wrap(MyArray);

impl Display for Wrap {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "-> Array:\n{}, {}, {}, {}",
            self.0[0], self.0[1], self.0[2], self.0[3]
        )
    }
}

fn main() {
    let my_array: MyArray = [1.5, 2.5, 3.5, 4.5];
    let my_wrap = Wrap(my_array);
    println!("{}", my_wrap)
}

When the program is executed, the custom format for the Array type is used via the Display trait:

λ cargo run -q
-> Array:
1.5, 2.5, 3.5, 4.5

This code works well but is rather limited to:

A single data type: f64.
An array of size 4.
One Array type.

It's possible to leverage Rust's generics to make it more extendable and idiomatic.

Extensibility with Generics

The first thing to do is make Array a generic type:

type MyArray<T, N> = [T; N];

However, the code above will fail to compile because 'N', which represents the size of the array, isn't a value:

error[E0423]: expected value, found type parameter `N`
  --> src/main.rs:22:26
   |
22 | type MyArray<T, N> = [T; N];
   |                          ^ not a value

It's necessary to use Rust's Const Generics in order to make the array completely generic, as per the RFC definition:

Const Generics allow types to be generic over constant values; among other things this will allow users to write impls which are abstract over all array types.

type MyArray<T, const N: usize> = [T; N];

And now, it's possible to make the Wrap type generic as well:

struct Wrap<T, const N: usize>(MyArray<T, N>);

Next, we need to make the impl of Display generic for arrays of any type and of any size, by declaring the impl with the same generics as those of the Wrap:

impl<T, const N: usize> Display for Wrap<T, N>

Then it's necessary to bound the Array type to those types that implement the Display trait, plus any other trait that's required for our particular implementation:

impl<T, const N: usize> Display for Wrap<T, N>
where
    T: Display,

In this particular case, ~~the bound with the PartialEq trait is required because I'm making an equality comparison between elements of the array.~~ (As pointed by korrat, it's better to use std::ptr::eq as the comparison function between the references in order to avoid the incorrect printing if the last element of the array is the same as its predecessor.)

Last thing to do is to implement the required Display trait function: fn fmt(...) -> std::fmt::Result, with the desired custom formatter:

use core::fmt::Display;
use std::ptr::eq;

struct Wrap<T, const N: usize>([T; N]);

impl<T, const N: usize> Display for Wrap<T, N>
where
    T: Display,
{
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let separator = ", ";
        let mut s = "Array -> ".to_string();

        for element in &self.0 {
            s.push_str(&element.to_string());
            if !eq(element, self.0.last().unwrap()) {
                s.push_str(&separator);
            }
        }
        write!(f, "{}", s)
    }
}

fn main() {
    let my_array = [1, 3, 1];

    let my_wrap = Wrap(my_array);
    println!("{}", my_wrap);
}

Finally!

It's now possible to define an Array of any size and of any type, so long as that type implements Display, and print it using the println! macro with a custom formatter:

fn main() {
    let my_array_f = [1.5, 2.5, 3.5, 4.5, 5.2, 6.75, 8.90, 8.90, 8.90];
    let my_array_c = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'j', 'j'];
    let my_array_s = [
        "Hello".to_string(),
        "World!".to_string(),
        "from Rust!".to_string(),
    ];

    let my_wrap = Wrap(my_array_f);
    println!("{}", my_wrap);

    let my_wrap = Wrap(my_array_c);
    println!("{}", my_wrap);

    let my_wrap = Wrap(my_array_s);
    println!("{}", my_wrap);
}

Rust's powerful type inference detects the type of the Array and it's size, thanks to const generics!

And the result in the terminal is the following:

λ cargo run -q
Array -> 1.5, 2.5, 3.5, 4.5, 5.2, 6.75, 8.9, 8.9, 8.9
Array -> a, b, c, d, e, f, g, h, i, j, j, j
Array -> Hello, World!, from Rust!

Links, references and disclaimers:

Header Photo by Faris Mohammed on Unsplash.
The Rust Programming Language.
The Rust Programming Language book.
Rust's Const Generics RFC: 2000-const-generics.
The Haskell Programming Language.
The Haskell Programming Language Newtype.

How to Use Rust Traits, Generics and Bounds

Rodrigo Santiago — Wed, 14 Sep 2022 17:03:31 +0000

Every time I am developing the question I am always asking myself is "is this code idiomatic, ergonomic and extendable enough?"

I ask myself that question much more at the beginning, when all the scaffolding and critical building blocks are being created, and particularly when defining types that will be the workhorses of the entire project.

Because I know that if I don't do it correctly there will be significant pain in the form of refactoring later on.

And usually the answer to that question is "yes" up until I make some progress and then I realize that my code was in fact "not extendable enough" or that "there was a better way to do it."

And then comes the decision to either refactor or continue building on top of the code that I know is just not good enough.

And this is precisely what just happened with my project Ruxel…

After I finished developing and testing all the vector and matrix logic for the ray tracer, I came back this weekend to review the code again, including my Ruxel Part 1 post, and I noticed that my implementation could have leveraged generics and traits in a much better way by using trait bounds.

Hence, I have decided to refactor part of my initial implementation and also share in this post how I plan to leverage Rust's Traits, Generics and Bounds in a way that makes the code more idiomatic, extendable and ergonomic.

Main Problem

At the heart of a ray tracer exist two types: Vector3 and Point3 that are very similar but with key differences, particularly because of its weight w: component, when expressed in their homogeneous form:

It's convenient that both types can be declared with either floating point or integer values.

Both types share common behavior, but also each one has its own specific functionality.

And both types are the workhorses of the entire project so they need to be implemented in the most extendable, ergonomic and idiomatic way.

In summary, this is the scenario to implement:

Point3 vs Vector3

What's the best approach?

Possible Alternatives

There are countless ways to approach the implementation of these types in Rust. However,I think the most common a programmer would try are:

No generics, no traits
Generic structs and traits

Let's review the implications of each in more detail…

1. No generics, no traits

To implement this approach, the following types would be required:

struct Point3F64 {
    x: f64,
    y: f64,
    z: f64,
    w: f64,
}

struct Point3I64 {
    x: i64,
    y: i64,
    z: i64,
    w: i64,
}

struct Vector3F64 {
    x: f64,
    y: f64,
    z: f64,
    w: f64,
}

struct Vector3I64 {
    x: i64,
    y: i64,
    z: i64,
    w: i64,
}

From the get-go it's clear that this will become a nightmare, as each struct will need its own impl block like this:

impl Vector3F64 {
    fn new(x: f64, y: f64, z: f64) -> Self {
        Self { x, y, z, w: 0f64 }
    }

    fn zero() -> Self {
        Self {
            x: 0f64,
            y: 0f64,
            z: 0f64,
            w: 0f64,
        }
    }

    // Other Associated Functions

    fn dot(self, rhs: Vector3F64) -> f64 {
        self.x * rhs.x + self.y * rhs.y + self.z * rhs.z + self.w * rhs.w
    }

    // Other Methods
}

And things will get ever more convoluted when implementing Operator Overloading for each type:

impl Add for Vector3F64 {
    type Output = Vector3F64;

    fn add(self, rhs: Self) -> Self::Output {
        Self {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
            z: self.z + rhs.z,
            w: self.z + rhs.w,
        }
    }
}

impl Add for Vector3I64 {
    type Output = Vector3I64;

    fn add(self, rhs: Self) -> Self::Output {
        Self {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
            z: self.z + rhs.z,
            w: self.z + rhs.w,
        }
    }
}

Following this approach would require implementing:

	non-generic implementation
Associated functions	36
Methods	14
Operator overload functions	24
Copy attributes	4
Default attributes	4
Display, Debug and PartialEq functions	1

This approach is:

Not extendable, because supporting another primitive type like i32 has the effect of requiring an additional:

	new primitive
Associated functions	13
Methods	7
Operator overload functions	11
Copy attributes	1
Default attributes	1
Display, Debug and PartialEq functions	4

Not idiomatic, because it is not:
- Leveraging the capabilities provided by Rust to solve this particular situation
- Following the best practices of the Rust community
- Succint in its approach
- Using the expressing power of Rust effectively
Not ergonomic, because it:
- Is full of development friction
- Doesn't seek simplicity
- Is inefficient
- Makes testing exponentially more complicated

Hence, unless the intention is to support only one primitive per struct type, this approach should be discarded.

2. Generic structs and traits

The next approach involves the use of generics in the struct declarations as follows:

struct Vector3<T> {
    x: T,
    y: T,
    z: T,
    w: T,
}

struct Point3<T> {
    x: T,
    y: T,
    z: T,
    w: T,
}

From the start, the required struct declarations are reduced to only 2. Even if in the future the project supports another primitive, like i32 these struct declarations would not change and no additional declarations would be required.

It's a big step in the right direction.

Implementing the associated functions and methods is also more ergonomic and idiomatic with this approach by leveraging Rust's trait bounds using the where keyword:

impl<T> Vector3<T>{
    fn dot(self, rhs: Vector3<T>) -> T
    where T: Copy + Add<Output = T> + Mul<Output = T>
    {
        self.x * rhs.x + self.y * rhs.y + self.z * rhs.z + self.w * rhs.w
    }
}

The example above will work for any type that implements the Copy, Add and Mul traits, like: f64, f32, i64, i32, etc.

There is no more code to write to extend the dot product functionality for more primitives.

However, in those associated functions where a value, other than Default::default(), needs to be specified there is still the need to implement them separately:

impl Point3<f64>{
    fn new(x: f64, y: f64, z: f64)  -> Self{
        Self{x, y, z, w: 1f64}
    }
}

impl Point3<i64>{
    fn new(x: i64, y: i64, z: i64)  -> Self{
        Self{x, y, z, w: 1i64}
    }
}

Yet for the cases where Default::default() applies there is only one function to specify:

impl<T> Vector3<T>{

    // Other generic associated functions

    fn new(x: T, y: T, z: T) -> Self
    where T: Copy + Add + Mul + Default
    {
        Self{x, y, z, w: Default::default()}
    }
}

This generic new(...) function of Vector3<T> will work with any type that implements the Copy and Default traits, again like f64, f32, etc.

By my estimations, with this approach the following implementations would be required:

	generic implementation
Associated functions	26
Methods	6
Operator overload functions	7
Copy attributes	2
Default attributes	2
Display, Debug and PartialEq functions	3

When compared versus the non-generic approach the improvement is significant:

	non-generic	generic	difference
Associated functions	36	26	-10
Methods	14	6	-8
Operator overload functions	24	7	-17
Copy attributes	4	2	-2
Default attributes	4	2	-2
Display, Debug and PartialEq functions	12	3	-9

Hence, this approach is:

Much more extendable, because supporting other primitive like i32 would only require an additional:

	new primitive
Associated functions	9
Methods	0
Operator overload functions	0
Copy attributes	0
Default attributes	0
Display, Debug and PartialEq functions	0

More idiomatic, because it:
- Leverages the generics capabilities provided by Rust that solve this particular problem
- Follow the best practices of the Rust community by using 'trait bounds' and generics
- Significantly more succint in the approach, as the comparison table above proved
- Uses the expressing power of Rust effectively
More ergonomic, because it:
- Has less developer friction: declaring a new Vector is let v = Vector3::new(...) instead of let v = Vector3F64::new(...) or let v = Vector3I32::new(...)
- Seeks simplicity with far less code
- Is efficient as it enables the same capabilities with less
- Testing is less burdensome as there are far fewer functions and scenarios to validate

It has been a big improvement by utilizing generics with trait bounds.

And most important: there is no impact on the speed and performance because this implementation is using static dispatch.

Supertraits and Subtraits

One additional Rust feature to further provide extensibility to the project is to define three traits in order to group the common behavior in a logical way via supertraits and subtraits:

The important part here is that the subraits don't inherit the functions or methods from the supertrait. Every type that implements the subtrait must implement the functions of the supertrait.

What this means in Rust code is the following:

// -- Trait declarations
trait Tuple<P> {
    fn new(x: P, y: P, z: P) -> Self
    where
        P: Copy + Default;
}

trait Vector<P>: Tuple<P> {
    fn dot(lhs: Vector3<P>, rhs: Vector3<P>) -> P 
    where
        P: Copy + Add<Output = P> + Mul<Output = P>;
}
trait Point<P>: Tuple<P> {
    fn origin(x: P) -> Self
    where
        P: Copy + Default;
}


// -- Supertrait implementations
impl<P> Tuple<P> for Vector3<P> {
    fn new(x: P, y: P, z: P) -> Vector3<P> where P: Copy + Default{
        Vector3 { x, y, z, w: Default::default() }
    }
}

impl Tuple<f64> for Point3<f64> {
    fn new(x: f64, y: f64, z: f64) -> Self {
        Point3 { x, y, z, w:1f64 }
    }
}

impl Tuple<i64> for Point3<i64> {
    fn new(x: i64, y: i64, z: i64) -> Self {
        Point3 { x, y, z, w:1i64 }
    }
}

// -- Subtrait implementations
impl<P> Vector<P> for Vector3<P> {
    fn dot(lhs: Vector3<P>, rhs: Vector3<P>) -> P 
    where
        P: Copy + Add<Output = P> + Mul<Output = P>,
        {
       lhs.x * rhs.x + lhs.w * rhs.w
    }

}

Vector3 and Point3 are implementing the new(x:...) -> Self function from the Tuple trait and not from one of its subtraits.

Because the type must implement the supertrait functions of those subtraits that it implements, it's critical to define under which scope a capability will be defined in order to balance logical grouping and efficiency:

Supertrait
Subtrait
Type implementation

For example, defining the ones() function -which returns a Vector or Point with '1' value in all its coordinates- in the Tuple supertrait scope forces the implementation of that function in both Point and Vector and all of their non-generic implementations like impl Tuple<i64> for Point3<i64>:

// -- Trait declarations
trait Tuple<P> {
    fn new(x: P, y: P, z: P) -> Self
    where
        P: Copy + Default;

    fn ones() ->Self
        where P: Copy + Default;
}

The compiler will be happy to let us know where an implementation is missing:

Rust/playground on  master [!] > v0.1.0 | v1.63.0
 λ cargo test it_works -- --nocapture
   Compiling playground v0.1.0 (/home/rsdlt/Documents/Rust/playground)
error[E0046]: not all trait items implemented, missing: `ones`
  --> src/lib.rs:46:1
   |
29 | /     fn ones() ->Self
30 | |         where P: Copy + Default;
   | |________________________________- `ones` from trait
...
46 |   impl<P> Tuple<P> for Vector3<P> {
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ missing `ones` in implementation

error[E0046]: not all trait items implemented, missing: `ones`
  --> src/lib.rs:52:1
   |
29 | /     fn ones() ->Self
30 | |         where P: Copy + Default;
   | |________________________________- `ones` from trait
...
52 |   impl Tuple<f64> for Point3<f64> {
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ missing `ones` in implementation

error[E0046]: not all trait items implemented, missing: `ones`
  --> src/lib.rs:58:1
   |
29 | /     fn ones() ->Self
30 | |         where P: Copy + Default;
   | |________________________________- `ones` from trait
...
58 |   impl Tuple<i64> for Point3<i64> {
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ missing `ones` in implementation

For more information about this error, try `rustc --explain E0046`.
error: could not compile `playground` due to 3 previous errors

It could appear that adding the supertrait and subtrait capabilities is generating more headaches than benefits… However, the benefits of structuring the common behavior this way are in my humble view, the following:

It forces thinking twice and hard under which scope it makes logical sense to add a new capability.
Once defined, the compiler will make sure that the capability is implemented everywhere it needs to be implemented.
Having a type defined within the bounds of the supertrait for cases that could be of benefit like ... where T: Tuple + Copy.

How could I have done better?

Going back to Ruxel Part 1 I am basically using two generic traits called CoordInit<T, U> and VecOps<T> which provide coordinate initialization and vector operations' capabilities, respectively.

Because they are generic traits, what followed was the implementation of each of those traits over the Vector3<f64> and Point3<f64> types:

impl VecOps<Vector3<f64>> for Vector3<f64> {
    fn magnitude(&self) -> f64 {
        (self.x.powf(2.0) + self.y.powf(2.0) + self.z.powf(2.0)).sqrt()
    }

    // Rest of Vector3<f64> operation methods and functions

impl CoordInit<Vector3<f64>, f64> for Vector3<f64> {
    fn back() -> Self {
        Vector3 {
            x: 0.0,
            y: 0.0,
            z: -1.0,
            w: 0.0,
        }
    }

    // Rest of Vector3<f64> initialization functions

impl CoordInit<Vector3<f64>, f64> for Point3<f64> {
    fn back() -> Self {
        Vector3 {
            x: 0.0,
            y: 0.0,
            z: -1.0,
            w: 0.0,
        }
    }

    // Rest of Point3<f64> initialization functions

Now, how would this approach support the addition of an i64 primitive type?

Not in a very ergonomic or idiomatic or extendable way.

Essentially, the following implementation blocks would need to be created and all the existing functions and methods defined for the f64 primitive be repeated (almost carbon copy) for each:

impl VecOps<Vector3<i64>> for Vector<i64>.
impl CoordInit<Vector3<i64>, <i64>> for Vector3<i64>.
impl CoordInit<Vector3<i64>, <i64>> for Point3<i64>.
impl operator overloading functions for Add, AddAssign, Sub, SubAssign, Mul, Div and Neg for i64.

So that's:

	new primitive
Associated functions	36
Methods	15
Operator overload func.	14
Copy attributes	0
Default attributes	0
Display, Debug and PartialEq func.	0

For a grand total of 55 methods & functions. And this is not counting the additional effort to properly test.

The approach I took was convenient enough to implement all the functionality quickly, but the solution could be better implemented by properly leveraging Rust's generics, traits and trait bounds.

Considering one of my primary Goals is to deliver idiomatic and ergonomic code, a refactoring over the implementation of the Vector3 and Point3 types is due.

Fortunately, it's going to be a minor refactor because the project is in its initial stage.

Links, references and disclaimers:

Header Photo by Brecht Corbeel on Unsplash

A version of this post was orginally published on https://rsdlt.github.io

Ruxel - Building a Ray Tracer with Rust Part 1

Rodrigo Santiago — Thu, 25 Aug 2022 13:33:00 +0000

This post is Part 1 in a series to share my journey in developing Ruxel, a simple Ray Tracer and 3D Renderer written in Rust, from scratch.

Please see the Series Prelude for more information regarding my Goals for v.0.1.0 of this project.

Ideally by the end of the series, Ruxel will be able to render an image like the one in the header, or better…

Note: Explaining 3D math in depth isn't the aim of these posts. To learn more about the underlying mathematics and theory please check the books I reference in the Series Prelude.

High-Level Architecture

The long-term objective is that Ruxel will become a big project, and surely it will go through several refactoring phases; however, it's critical to leverage Rust's modules' system from the beginning to keep the project well organized and easier to maintain as it grows larger…

The following diagram presents a high-level view of the architecture of the application, at least for v.0.1.0:

Ruxel high-level architecture diagram - made with https://mermaid.live

In Part 1 and Part 2 of this series, the focus is to create the following:

Part 1:

Initial project structure:
- Cargo.toml
- Modules tree
- Unit testing
Geometry module:
- Vectors
- Struct
- Traits
- Implementations
- Points
- Struct
- Traits
- Implementations

Part 2:

Picture module:
- Canvas
- Struct
- Traits
- Implementations
- Pixel
- Struct
- Traits
- Implementations
- Colors
- Struct
- Traits
- Implementations
- Image
- File

Implementing these modules first, will allow the testing of the basic geometric types and present a first image in a straightforward format.

Project scaffolding

To begin, open the terminal -in my case it's the Alacritty + Tmux + Fish + Neovim combo- and start a new Cargo project followed by several mkdir and touch commands to get the proper directory structure…

cargo new ruxel
mkdir src/geometry
mkdir src/picture

-- other commands

If you use Neovim, you can execute shell commands in Neovim's command line by prepending a ! before the shell commands, for example: :!mkdir geometry or :!touch vector.rs.
{: .prompt-tip }

The initial project structure is the following:

Rust/ruxel on  main [✘] > v0.0.0 | v1.63.0
 λ tree -L 4
.
├── Cargo.lock
├── Cargo.toml
├── images
├── LICENSE-APACHE
├── LICENSE-MIT
├── README.md
└── src
    ├── geometry
    │   ├── vector
    │   │   └── tests.rs
    │   └── vector.rs
    ├── geometry.rs
    ├── main.rs
    ├── picture
    │   ├── canvas
    │   │   └── tests.rs
    │   ├── canvas.rs
    │   ├── colors
    │   │   └── tests.rs
    │   └── colors.rs
    └── picture.rs

8 directories, 16 files

This initial scaffolding allows to continue adding modules, and their respective unit tests, in an structured way.

For example, adding a Matrix module would imply creating a new matrix directory, its rust source file and respective tests:

/src/geometry/matrix/
/src/geometry/matrix.rs
/src/geometry/matrix/tests.rs

This would yield the following tree:

Rust/ruxel on  main [✘] > v0.0.0 | v1.63.0
 λ tree -L 4
.
├── Cargo.lock
├── Cargo.toml
├── images
├── LICENSE-APACHE
├── LICENSE-MIT
├── README.md
└── src
    ├── geometry
**  │   ├── matrix 
**  │   │   └── tests.rs
**  │   ├── matrix.rs
    │   ├── vector
    │   │   └── tests.rs
    │   └── vector.rs
    ├── geometry.rs
    ├── main.rs
    ├── picture
    │   ├── canvas
    │   │   └── tests.rs
    │   ├── canvas.rs
    │   ├── colors
    │   │   └── tests.rs
    │   └── colors.rs
    └── picture.rs

8 directories, 16 files

Rust offers other alternatives to structure projects, like using mod.rs; however, I find the option of using a file and directory name to be the clearer.

Important diagnostic attributes to set up from the beginning:

/src/main.rs

#![warn(missing_docs, missing_debug_implementations)]

This will provide linter warnings for missing doc comments used by Rust to generate automatic documentation, and for detecting types missing the Debug trait that provides convenient ways to display type values during development.

And finally, lets make sure all of our files are part of Rust's module tree:

/src/main.r

/**
The geometry module implements the functionality for Points, Vectors, Matrices, and their transformations
*/
pub mod geometry;

/**
The picture module implements the functionality for Canvas and Colors in order to create an image file.
*/
pub mod picture;

/src/geometry.rs

/// Provides data structures, methods and traits for Matrix4 computations.
pub mod matrix;
/// Data structures and methods for Vector3 and Point3 computations.
pub mod vector;

/src/picture.rs

/// Provides the data structure and implementation of the Color type
pub mod colors;

/// Provides the data structure and implementation of the Canvas type
pub mod canvas;

/src/geometry/vector.rs

// Unit tests for Vector3 and Point3
#[cfg(test)]
mod tests;

/src/picture/canvas.rs

// Canvas Unit Tests
#[cfg(test)]
mod tests;

/src/picture/colors.rs

// Colors Unit Tests
#[cfg(test)]
mod tests;

If everything is properly set up rust-analyzer shouldn't emit a warning regarding that a file isn't part of the module tree.

It's now possible to write some types with their associated functions and bring them into the main.rs scope with full rust-analyzer completion assistance:

/src/main.rs

fn main() {
    let v = Vector3::one();
    let p = Point3::one();

    println!("Vector: {:?} \n Point: {:?}", v, p);

    let c = ColorRgb::red();
    println!("Color: {}", c);
}

Now that the initial scaffolding is done, lets start coding.

Vectors and Points

The module vector contains the types Vector3 and Point3 which are mathematically defined as:

Type definitions

The mathematics definition can be translated into Rust code as follows:
/src/geometry/vector.rs

/// Type representing a geometric 3D Vector with x, y, z components.
#[derive(Debug, Clone, Copy)]
pub struct Vector3<T> {
    /// Component on x axis
    pub x: T,
    /// Component on y axis
    pub y: T,
    /// Component on z axis
    pub z: T,
}

/// Type representing a geometric 3D Point with x, y, z components.  
#[derive(Debug, Clone, Copy)]
pub struct Point3<T> {
    /// Component on x axis
    pub x: T,
    /// Component on y axis
    pub y: T,
    /// Component on z axis
    pub z: T,
    /// Component representing the 'weight' 
    pub w: T,
}

Both types:

Are named-field structures to have access to their components by name (for example: vector.x, point.z).
Have generic type parameters in their components so to have the flexibility to implement them as f64 or i64, etc.
Implement the common traits of Debug, Copy and Clone.
Are, for the moment, public via pub.

The most consequential decision here is that both types implement the Copy and Clone common traits.

And the main reason is that all their components are expected to be common numeric types like i64, f64, etc., that don't own heap resources.

Traits and implementation

Out of the countless ways to implement the desired functionality for these types, the preferred way for this project is to do the following for v.0.1.0

Focus on implementing Vector and Point for common numeric types f64 and for a 3D coordinate system. So no Vector2<f64> or Point3<i64>.
Leverage generics and traits as much as possible, keeping in mind future extensibility with little to no refactoring. For example, including Vector2 should be about adding functionality without having to refactor the existing code.
Create a public Enum named Axis that specifies the axis of a 2D,3D or 4D coordinate system.
Create a public trait named CoordInit that specifies the methods for initializing the coordinate system for any type that implements it:
- This provides extensibility for other types of vectors and points, like Vector2 or Point2, or basically any type that requires a coordinate initialization: up, down, back, forward, etc.
Implement CoordInit trait for Vector3 and Point3
Create a public trait named VecOps that defines common capabilities exclusive for Vectors, like magnitude, cross product, dot product, etc.
Implement the associated function new(...) on each type.
Implement operator overloading capabilities to conveniently write common binary operations over Vector3 and Point3 (to learn more about this topic you can check this post Basic Operator Overloading with Traits):
- Add, AddAssign
- Sub, SubAssign
- Mul and Div
- Neg
Implement the following common traits:
- Display, Debug, Default, Eq and PartialEq

Axis enumerator

A critical, yet opinionated decision, is how to best handle the initialization of new coordinate-related types, like vectors and points, using a trait with type-associated functions with different signatures.
In essence, how to handle this case:

/src/geometry/vector.rs

trait Init{
        fn new(...);
    }

impl Init for Vector2<T>{
        fn new(x: T, y: T) -> Self{...}
    }
impl Init for Vector3<T>{
        fn new(x: T, y: T, z: T) -> Self{...}
    }
impl Init for Point4<T>{
        fn new(x: T, y: T, z: T, w: T) -> Self{...}
    }

There are various alternatives like using associated functions with the turbofish syntax, however for this project I favor utilizing an enumerator to encapsulate the method parameters:

/src/geometry/vector.rs

/**
Enumerator that encapsulates the different coordinate systems used to initialize a Vector or
Point
*/
#[derive(Debug)]
pub enum Axis<U> {
    /// Coordinate system with X and Y axis.
    XY(U, U),
    /// Coordinate system with X, Y and Z axis.
    XYZ(U, U, U),
    /// Coordinate system with X, Y, Z and W axis.
    XYZW(U, U, U, U),
}

And then bring it into scope using a simplified alias:

/src/geometry/vector.rs

use geometry::vector::{
    Axis,
    Axis::{XY as xy, XYZ as xyz, XYZW as xyzw},
};

With the end result in being able to initialize a new coordinate-related type in a consistent, clear and condensed manner using the new(...) method name:

/src/main.rs

    let vec3 = Vector3::new(xyz(1.0, 2.0, 3.0));
    let point3 = Point3::new(xyzw(1.0, 2.0, 3.0, 4.0));

It provides the added benefit of extensibility to new types while maintaining a consistent initialization syntax.

So for example, if in the future the Vector2, Vector4, Point2 or any other coordinate-related type requires a new method we would use the same syntax:

/src/main.rs

    let vec2 = Vector2::new(xy(1.0, 2.0));
    let vec3 = Vector3::new(xyz(1.0, 2.0, 3.0));
    let vec4 = Vector4::new(xyzw(1.0, 2.0, 3.0, 4.0));
    let point2 = Point2::new(xy(1.0, 2.0));
    let point3 = Point3::new(xyz(1.0, 2.0, 3.0));
    let point4 = Point4::new(xyzw(1.0, 2.0, 3.0, 4.0));

In the following section, where the CoordInit trait is defined, it's shown how to utilize the Axis enumerator in the trait function.

CoordInit trait

The main goal of the CoordInit trait is to define the functionality to initialize any coordinate-related type, in its most common ways, but also by in a user-defined way.

In the case of coordinate-related types the most common initializations are: up, down, left, right, forward, back, one and zero.

Also, having a self.equal() method to compare one type against another can be handy.

In Rust, this trait can be defined as follows:

/src/geometry/vector.rs

/// Trait allows Types with coordinates (x, y, etc.) to be efficiently initialized with common shorthand.
pub trait CoordInit<T, U> {
    /// Return a type with shorthand, for example [0, 0, -1].
    fn back() -> T;
    /// Return a type with shorthand, for example  [0, -1, 0].
    fn down() -> T;
    /// Return true if a type is identical to another, else return false.
    fn equal(self, rhs: Self) -> bool;
    /// Return a type with shorthand, for example  [0, 0, 1].
    fn forward() -> T;
    /// Return a type with shorthand, for example  [-1, 0, 0].
    fn left() -> T;
    /// Return a type with user-defined Axis components.
    fn new(axis: Axis<U>) -> T;
    /// Return a type with shorthand, for example  [1, 1, 1].
    fn one() -> T;
    /// Return a type with shorthand [1, 0, 0].
    fn right() -> T;
    /// Return a type with shorthand [0, 1, 0].
    fn up() -> T;
    /// Return a type with shorthand [0, 0, 0].
    fn zero() -> T;
}

The trait is defined with two generic components <T, U>.

T represents the coordinate-related types (Vector, Points, etc.) that will be initialized, and that will be returned from almost all the functions.

U represents the common type (f64) that will use the Axis enum to initialize the coordinate-related type.

The next step is to implement each of these functions for the specific types that are needed.

As defined above, for v.0.1.0 the focus is only to support types in 3 dimensions and with floating points (f64). However, the framework to make it extensible to other dimensions and primitive data types is already established.

For the full implementation details you can visit Ruxel's GitHub repository.

Here, I will explain just a couple in its implementation for Vector3<f64>:

fn new(axis: Axis) -> T
fn zero()

The Rust code is the following:

/src/geometry/vector.rs

impl CoordInit<Vector3<f64>, f64> for Vector3<f64> {

    // other type-associated functions

    // new()
    fn new(axis: Axis<f64>) -> Vector3<f64> {
        match axis {
            Axis::XY(x, y) => Vector3 { x, y, z: 0.0 },
            Axis::XYZ(x, y, z) => Vector3 { x, y, z },
            Axis::XYZW(x, y, z, _w) => Vector3 { x, y, z },
        }
    }

    fn zero() -> Self {
        Vector3 {
            x: 0.0,
            y: 0.0,
            z: 0.0,
        }
    }
}

The first line specifies the implementation of the CoordInit trait for the Vector3 type utilizing f64 in its components.

The function fn new(...) receives the Axis<f64> enumerator, performs a match against the supported coordinate systems (XYZ, etc.) and returns the Vector initialized with user-defined or sane values.

In this case, the sane value is to return a Vector3 even if the user inputs a 2D coordinate system.

The function fn zero() returns a Vector3 with all its components with value 0.0.

Operator overloading

To implement operator overloading capabilities it's necessary to bring the std::ops module into scope and implement the desired traits in each of the types.

/src/geometry/vector.rs

// Bring overflow operator's traits into scope
use std::ops::{Add, AddAssign, Div, Mul, Neg, Sub, SubAssign}

Binary operations between Vectors and Points need to follow some mathematical logic, summarized in this table:

Operation	LHS	RHS	Result
Add	V	P	P
Add	P	V	P
Add	V	V	V
Add	P	P	N/A
Sub	V	P	N/A
Sub	P	V	P
Sub	V	V	V
Sub	P	P	V
Mul	P	Scalar	N/A
Mul	V	Scalar	V
Mul	V	P	N/A
Div	P	Scalar	N/A
Div	V	Scalar	V
Div	V	P	N/A
Neg	V	N/A	-V
Neg	P	N/A	N/A

And hence, it's only necessary to implement the combinations that yield a logic result. Not implementing the others carries the additional benefit of being stopped by the Rust compiler.

For example, to support the Add operation between Vector3 and Point3 three implementation functions are needed:

impl Add<Point3<f64>> for Vector3<f64> {
    type Output = Point3<f64>;

    fn add(self, rhs: Point3<f64>) -> Point3<f64> {
        Point3 {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
            z: self.z + rhs.z,
            w: rhs.w,
        }
    }
}

impl Add<Vector3<f64>> for Point3<f64> {
    type Output = Point3<f64>;

    fn add(self, rhs: Vector3<f64>) -> Point3<f64> {
        Point3 {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
            z: self.z + rhs.z,
            w: self.w,
        }
    }
}

impl Add for Vector3<f64> {
    type Output = Vector3<f64>;

    fn add(self, rhs: Self) -> Vector3<f64> {
        Vector3 {
            x: self.x + rhs.x,
            y: self.y + rhs.y,
            z: self.z + rhs.z,
        }
    }
}

Check the GitHub repository for the full implementation of all the operators.

Once all the binary operators are overloaded, it's possible to 'chain' Vector and Point operations like with any common primitive, which is extremely useful and convenient:

src/main.rs

    let v1 = Vector3::new(xyz(2.0, 3.5, 4.0));
    let v2 = Vector3::new(xyz(3.0, 7.5, 8.0));
    let v3 = Vector3::new(xyz(2.55555, 7.88888, 9.34343));
    let v4 = Vector3::new(xyz(2.55553, 7.88887, 9.34342));
    let p1 = Point3::new(xyz(2.5, 3.5, 4.5));
    let p2 = Point3::new(xyz(3.0, 7.0, 8.0));
    let p3 = Point3::new(xyz(2.55555, 7.88888, 9.34343));
    let p4 = Point3::new(xyz(2.55553, 7.88887, 9.34342));


    println!("{:?}", v1 + v4 - v1 - v3 + (v2 - v4) / 1.522445523);
    println!("{:?}", v3 + p4 + v1);
    println!("{:?}", p1 - p2 / 3.7626374);
    println!("{:?}", p2 - v1);
    println!("{:?}", v2 + v1);

Common traits

The Rust API Guidelines offer an extensive explanation of the recommendations on how to develop APIs for the language in order to produce idiomatic code.

One of the key objectives of this project is to abide to the standards as much as possible.

As the project evolves, more common traits will likely be implemented as needed, and only if it makes sense to do so.
{: .prompt-info }

For starters, these are the common traits that are implemented at this stage for the Vector3 and Point3 types:

Type	Common Trait
Vector3	Eq, PartialEq, Display, Debug, Clone, Copy, Default
Point3	Eq, PartialEq, Display, Debug, Clone, Copy, Default

The default implementations can be derived by decorating the struct definitions with the #[derive(Debug, Copy,...)] attributes.

However, only in the particular cases of Display and Default a manual implementation will be written to modify the default behavior:

Default implementations via derive:

src/geometry/vector.rs

#[derive(Debug)]
pub enum Axis<U>

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub struct Vector3<T> 

#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub struct Point3<T>

And now the manual implementations:

src/geometry/vector.rs

impl Display for Vector3<f64> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let s = format!("v: [{:^5.2},{:^5.2},{:^5.2}]", self.x, self.y, self.z);
        f.write_str(&s)
    }
}

impl Display for Point3<f64> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let s = format!(
            "p: [{:^5.2},{:^5.2},{:^5.2},{:^5.2}]",
            self.x, self.y, self.z, self.w
        );
        f.write_str(&s)
    }
}

impl Default for Point3<f64> {
    fn default() -> Self {
        Self {
            x: 0.0,
            y: 0.0,
            z: 0.0,
            w: 1.0,
        }
    }
}

impl Default for Vector3<f64> {
    fn default() -> Self {
        Self {
            x: 0.0,
            y: 0.0,
            z: 0.0,
        }
    }
}

Even when Default for Vector3 implements Rust's defaults of filling the value with 0.0's for f64, it's convenient to have the manual implementation at hand for testing purposes.

Common vector operations

The last important implementations that are needed for the Vector type are those regarding their common mathematical operations:

Calculate magnitude
Normalize the vector
Calculate dot product
Calculate cross product
Obtain the minimum component in the vector
Obtain the maximum component in the vector
Return components of the vector by name and index

These capabilities can be defined using a public trait named VecOps<T>, with a generic parameter in order to extend its implementation for types other than Vector3<f64>:

src/geometry/vector.rs

/// A trait that encapsulates common Vector Operations.
pub trait VecOps<T> {
    /// Computes the magnitude of a Vector.
    fn magnitude(&self) -> f64;
    /// Returns the vector normalized (with magnitude of 1.0)
    fn normalized(&mut self) -> Self;
    /// Returns the Dot Product of two Vectors.
    fn dot(lhs: T, rhs: T) -> f64;
    /// Returns the Cross Product of two Vectors.
    fn cross(lhs: T, rhs: T) -> T;
    /// Returns the Smallest component in the Vector.
    fn min_component(&self) -> (i8, char, f64);
    /// Returns the Largest component in the Vector.
    fn max_component(&self) -> (i8, char, f64);
    /// Returns the component of the Vector by index. this(1)
    fn this(&self, index: i8) -> Option<(i8, char, f64)>;
    /// Returns the component of the Vector by name. this_n('x')
    fn this_name(&self, index: char) -> Option<(i8, char, f64)>;
}

As with the CoordInit trait, the implementation needs to be defined for each function within an impl block for Vector3<f64>:

impl VecOps<Vector3<f64>> for Vector3<f64> {
    fn magnitude(&self) -> f64 {
        (self.x.powf(2.0) + self.y.powf(2.0) + self.z.powf(2.0)).sqrt()
    }

    fn normalized(&mut self) -> Self {
        let magnitude = self.magnitude();
        Self {
            x: self.x / magnitude,
            y: self.y / magnitude,
            z: self.z / magnitude,
        }
    }

    // other functions in the VecOps<T> trait

Unit tests

Now that the basic implementations and capabilities for Vector3 and Point3 are created it's time to perform unit tests to ensure that there are no issues or bugs in the code.

As described at the beginning, the tests for each of the modules are implemented in the test.rs under the module's directory.

In the case of Vector3 and Point3, the file is located in src/geometry/vector/tests.rs.

There are 5 tests that will be executed to validate our types:

Vector and Point construction integrity
Vector and Point operator overloading integrity
Vector common operations integrity
Rocket launch simulator, based on The Ray Tracer Challenge book¹

First step is to bring into scope the vector module and use the alias for the Axis enumerator:

src/geometry/vector/tests.rs

/// Unit testing for Vector3 and Point3 types
use super::*;

use super::Axis::XYZ as xyz;

Second we define the tests functions:


#[test]
// This test validates the construction of the Vector3 and Point3 types
fn vector_and_point_construction_integrity() {}

#[test]
// This test validates the operation overloading Add, Sub, Div, Equality, Mul, Neg, AddAssign, SubAssign  for the Vector3 and Point3
fn vector_and_point_operator_overloading_integrity() {}

#[test]
// This test validates the implementation of the fuctions in the VecOps trait
fn vector_common_operations_integrity() {} 

#[test]
// This test validates integrity by simulating a rocket launch
fn simulate_rocket_lauch() {}

Each test is basically a set of assert!() and assert_eq!() macros, as well as println!() statements.

The testing file is pretty extensive, so in this post I will only show the code for vector_common_operations_integrity() and the 'simulate_rocket_lauch()' tests:

src/geometry/vector/tests.rs

#[test]
// This test validates the implementation of the fuctions in the VecOps trait
fn vector_common_operations_integrity() {
    // Magnitude
    let v1 = Vector3::new(xyz(1.0, 2.0, 3.0));
    assert_eq!(v1.magnitude(), 14f64.sqrt());
    // Normalization
    let mut v2 = v1;
    assert_eq!(v2.normalized().magnitude(), 1f64);
    // Dot product
    let a = Vector3::new(xyz(1.0, 2.0, 3.0));
    let b = Vector3::new(xyz(2.0, 3.0, 4.0));
    assert_eq!(Vector3::dot(a, b), 20f64);
    // Cross product
    assert_eq!(Vector3::cross(a, b), Vector3::new(xyz(-1.0, 2.0, -1.0)));
    assert_eq!(Vector3::cross(b, a), Vector3::new(xyz(1.0, -2.0, 1.0)));
    // Min, Max and Get Components
    assert_eq!(a.min_component(), (0, 'x', 1.0));
    assert_eq!(a.max_component(), (2, 'z', 3.0));
    assert_eq!(a.this(0).unwrap(), (0, 'x', 1.0));
    assert_eq!(a.this(9), None);
    assert_eq!(b.this(b.min_component().0).unwrap(), (0, 'x', 2.0));
    assert_eq!(a.this_name('z').unwrap(), (2, 'z', 3.0));
}

Running the test using cargo test vector_common_operations_integrity yields a positive result:

 λ cargo test vector_common_operations_integrity
running 1 test
test geometry::vector::tests::vector_common_operations_integrity ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 8 filtered out; finished in 0.00s

And now, the rocket launch simulation that brings everything together in a single test. To validate, the test will print the coordinates of the rocket based on initial launching conditions and the environment (gravity and wind).

The expectation is to see the data of a parabolic launch:

x axis getting larger.
y axis getting larger and then going down to 0.0.

#[test]
// This test validates integrity by simulating a rocket launch
fn simulate_rocket_lauch() {
    #[derive(Debug)]
    struct Projectile {
        position: Point3<f64>,
        velocity: Vector3<f64>,
    }

    struct Environment {
        gravity: Vector3<f64>,
        wind: Vector3<f64>,
    }

    let mut proj = Projectile {
        position: Point3::up(),
        velocity: Vector3::new(xyz(1.0, 1.0, 0.0)).normalized(),
    };

    let env = Environment {
        gravity: Vector3::down() / 10f64,
        wind: Vector3::left() / 100f64,
    };

    fn tick<'a, 'b>(env: &'a Environment, proj: &'b mut Projectile) -> &'b mut Projectile {
        proj.position = proj.position + proj.velocity;
        proj.velocity = proj.velocity + env.gravity + env.wind;
        proj
    }

    println!(
        "Launch position: - x: {:^5.2}, y: {:^5.2}, z: {:^5.2}",
        proj.position.x, proj.position.y, proj.position.z
    );
    while proj.position.y > 0.0 {
        tick(&env, &mut proj);
        if proj.position.y <= 0.0 {
            break;
        }
        println!(
            "Projectile position - x: {:^5.2}, y: {:^5.2}, z: {:^5.2}",
            proj.position.x, proj.position.y, proj.position.z
        );
    }
    println!("========================== End");
}

To view the println!() results it's necessary to run cargo test with the -- --nocapture argument:

Rust/ruxel on  main [!] > v0.0.0 | v1.63.0
 λ cargo test simulate_rocket_lauch  -- --nocapture

     Finished test [unoptimized + debuginfo] target(s) in 0.00s
     Running unittests src/main.rs (target/debug/deps/ruxel-6b30efdff903fb79)

running 1 test
Launch position: - x: 0.00 , y: 1.00 , z: 0.00
Projectile position - x: 0.71 , y: 1.71 , z: 0.00
Projectile position - x: 1.40 , y: 2.31 , z: 0.00
Projectile position - x: 2.09 , y: 2.82 , z: 0.00
Projectile position - x: 2.77 , y: 3.23 , z: 0.00
Projectile position - x: 3.44 , y: 3.54 , z: 0.00
Projectile position - x: 4.09 , y: 3.74 , z: 0.00
Projectile position - x: 4.74 , y: 3.85 , z: 0.00
Projectile position - x: 5.38 , y: 3.86 , z: 0.00
Projectile position - x: 6.00 , y: 3.76 , z: 0.00
Projectile position - x: 6.62 , y: 3.57 , z: 0.00
Projectile position - x: 7.23 , y: 3.28 , z: 0.00
Projectile position - x: 7.83 , y: 2.89 , z: 0.00
Projectile position - x: 8.41 , y: 2.39 , z: 0.00
Projectile position - x: 8.99 , y: 1.80 , z: 0.00
Projectile position - x: 9.56 , y: 1.11 , z: 0.00
Projectile position - x: 10.11, y: 0.31 , z: 0.00
========================== End
test geometry::vector::tests::simulate_rocket_lauch ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 8 filtered out; finished in 0.00s

As expected, the test passed. This means that our Vector3 and Point3 implementations have been successful.

And with that we conclude Part 1 of this series!

Next steps

In Part 2 we will focus on:

Creating the Color, Pixel and Canvas types.
Defining and implementing their traits.
Writing and executing their unit tests.
And finally, producing the first image.

This post was originally published on:
https://rsdlt.github.io/posts/ruxel-part-1-rust-ray-tracer-renderer-3d-development/

Links, references and disclaimers:

Header Photo by Rohit Choudhari on Unsplash

Books:

Buck, Jamis. (2019). The ray tracer challenge: A test-driven guide to your first 3D renderer. The Pragmatic Programmers. ↩

Rust and Neovim - A Thorough Guide and Walkthrough

Rodrigo Santiago — Tue, 16 Aug 2022 00:55:00 +0000

This post is a detailed explanation and walkthrough of how I set up my Rust development environment and workflow with Neovim.

Prerquisites

Have the following installed:
- Rust.
- Neovim v0.7.0+.
- A Neovim package manager, like wbthomason/packer.nvim.
Have basic knowledge about Neovim and Lua:
- How to navigate with the keyboard.
- How to install / remove plugins.
- How to create and edit Lua config files.
- Here is a great tutorial that helped me with these basics.

Why Neovim

Like many developers, I went through a phase of looking for the ideal development set of tools that would be convenient and enjoyable, but most of all, that would boost my productivity.

After extensively trying many text editors and IDEs, I have decided to give Neovim a serious shot and invest time and effort in learning and customizing it heavily.

I have to say, it was no easy feat... But it is also a great experience!

Neovim is a very sophisticated tool that is extremely customizable but carries a steep learning curve. However, once you're past the basics and force yourself some muscle memory it is unbelievably fast. All the effort pays off massively.

I am, by no means, an expert user of Neovim, but with every keystroke I get faster and more productive.

And I think that is the key thing that makes Neovim a different beast: it forces you to change and adapt, and you actually see and feel yourself getting better and better!

Anyways, here are my Pros and Cons about Neovim...

Pros:

Lighting fast.
Extremely configurable and customizable.
Massive ecosystem of plugins.
Cross-platform support.
Support for almost any programming language out there.
Forces productive habits upon you.
Abundant documentation and community support.
It is free and open source.

Cons:

Significant up-front time investment in learning.
Abundance of choice in customization options can be distracting.
Steep learning curve.
Demands commitment and patience in creating new muscle memory.

Why Neovim for Rust Development

Okay, the above points are all valid from a general point of view, but why is Neovim great specifically for a Rust development workflow? Here are my reasons:

Neovim natively supports LSP in versions 0.5+
rust-analyzer is supported through Neovim's LSP, which essentially give us:
- Code completion.
- Some refactoring.
- Code analysis and linting.
- Go to definition.
- Code actions.
- Access to documentation.
- Show and go to references.
- Snippets support.
- Better syntax highlighting.
- Code formatting.
rust-tools is a fantastic plugin to setup rust-analyzer with Neovim's LSP .
Integrated terminal.
Access to Cargo commands.
Rustfmt On Save.
Rust debugging via:
- CodeLLDB debugger with
- Vimspector plugin, or
- nvim-DAP plugin .
TOML language support.

In essence, we have all the functionality that is needed from an IDE to develop Rust with productivity.

Here are a couple screenshots using my current setup:

openSUSE Tumbleweed operating system.
XFCE desktop environment.
Alacritty terminal.

Rust development with Neovim and Vimspector

Rust development with Neovim and voldikss/vim-floaterm float terminal plugin

Set Up Rust with Neovim

To make things more digestible, here the major activities that what we are going to do:

Rust and Neovim Set Up Diagram - made with https://mermaid.live

Download and setup rust-analyzer and codelldb using Neovim's plugins.
Attach Neovim to rust-analyzer.
Install Neovim's complete and snippets plugins.
Install Neovim's tree-sitter and set it up with tree-sitter-rust parser.
Set up vimspector to work with codelldb to debug Rust and Rust Tests.

But before we go into the details, here is my Neovim .config/nvim folder so that the filenames below make sense:

.config/nvim on  main [!] via 🌙 v5.4.4
 λ tree -L 2
.
├── init.lua
├── lua
│   ├── keys.lua
│   ├── opts.lua
│   ├── plug.lua
│   └── vars.lua
└── plugin
    └── packer_compiled.lua

1. Download rust-analyzer and CodeLLDB with Neovim's plugins

The first Neovim plugin, other than Packer (the package manager), we need is Mason:

williamboman/mason.nvim a plugin to install and manage LSP servers, debuggers and linters.
williamboman/mason-lspconfig.nvim to complement Manson with other goodies.

Here is the Lua code to install these -and other- plugins using Packer:

.config/nvim/lua/plug.lua:

return require('packer').startup(function()
    -- other plugins...

    use 'williamboman/mason.nvim'    
    use 'williamboman/mason-lspconfig.nvim'

   -- other plugins...
end)

Then we just save :w, reload :luafile % and install with :PackerInstall.

I could use other package managers to install plugins or LSPs, however, I prefer Packer and Mason because they are written entirely in Lua, are getting traction within the Neovim developer community, and they work great.

Once Mason is installed, we use it to install and manage rust-analyzer and CodeLLDB:

On Neovim command mode we input :MasonInstall rust-analyzer codelldb.

When Manson finishes, we we can check with :Mason that we have rust-analyzer and CodeLLDB installed.

Mason installing rust-analyzer and CodeLLDB for Neovim

2. Attaching Neovim to rust-analyzer

Next, we continue by installing two essential plugins to attach rust-analyzer to Neovim's LSP:

neovim/nvim-lspconfig a collection of LSP configs.
simrat39/rust-tools.nvim tools to automatically set up lspconfig for rust-analyzer.

Here is the Lua code to install these packages using Packer:

.config/nvim/lua/plug.lua:

return require('packer').startup(function()
    -- other plugins...

    use 'neovim/nvim-lspconfig' 
    use 'simrat39/rust-tools.nvim'

    -- other plugins...
end)

Now, we need to setup Neovim so that it can interact with rust-analyzer:

.config/nvim/init.lua

local rt = {
    server = {
        settings = {
            on_attach = function(_, bufnr)
                -- Hover actions
                vim.keymap.set("n", "<C-space>", rt.hover_actions.hover_actions, { buffer = bufnr })
                -- Code action groups
                vim.keymap.set("n", "<Leader>a", rt.code_action_group.code_action_group, { buffer = bufnr })
                require 'illuminate'.on_attach(client)
            end,
            ["rust-analyzer"] = {
                checkOnSave = {
                    command = "clippy"
                }, 
            },
        }
    },
}
require('rust-tools').setup(rt)

Further customization options are available via rust-tools configuration.

However, I prefer to leave the defaults in rust-tools, and configure instead through Neovim's Diagnostics API:

.config/nvim/init.lua

-- LSP Diagnostics Options Setup 
local sign = function(opts)
  vim.fn.sign_define(opts.name, {
    texthl = opts.name,
    text = opts.text,
    numhl = ''
  })
end

sign({name = 'DiagnosticSignError', text = ''})
sign({name = 'DiagnosticSignWarn', text = ''})
sign({name = 'DiagnosticSignHint', text = ''})
sign({name = 'DiagnosticSignInfo', text = ''})

vim.diagnostic.config({
    virtual_text = false,
    signs = true,
    update_in_insert = true,
    underline = true,
    severity_sort = false,
    float = {
        border = 'rounded',
        source = 'always',
        header = '',
        prefix = '',
    },
})

vim.cmd([[
set signcolumn=yes
autocmd CursorHold * lua vim.diagnostic.open_float(nil, { focusable = false })
]])

3. Install the Complete and Snippets plugins' suite:

The following set of plugins allow us to query Neovim's LSPs, and other sources, to present the auto-complete drop-down menu while typing code.

Thanks to these plugins, and because we have already attached rust-analyzer to Neovim's LSP, we will be able to get nice IDE-like auto-completion when we work on a Cargo project:

.config/nvim/lua/plug.lua:

return require('packer').startup(function()
    -- other plugins...

    -- Completion framework:
    use 'hrsh7th/nvim-cmp' 

    -- LSP completion source:
    use 'hrsh7th/cmp-nvim-lsp'

    -- Useful completion sources:
    use 'hrsh7th/cmp-nvim-lua'
    use 'hrsh7th/cmp-nvim-lsp-signature-help'
    use 'hrsh7th/cmp-vsnip'                             
    use 'hrsh7th/cmp-path'                              
    use 'hrsh7th/cmp-buffer'                            
    use 'hrsh7th/vim-vsnip'                             

    -- other plugins...
end)

And now, we need to set them up in our configuration files:

First in our Neovim APIs:

.config/nvim/lua/opts.lua


--Set completeopt to have a better completion experience
-- :help completeopt
-- menuone: popup even when there's only one match
-- noinsert: Do not insert text until a selection is made
-- noselect: Do not select, force to select one from the menu
-- shortness: avoid showing extra messages when using completion
-- updatetime: set updatetime for CursorHold
vim.opt.completeopt = {'menuone', 'noselect', 'noinsert'}
vim.opt.shortmess = vim.opt.shortmess + { c = true}
vim.api.nvim_set_option('updatetime', 300) 

-- Fixed column for diagnostics to appear
-- Show autodiagnostic popup on cursor hover_range
-- Goto previous / next diagnostic warning / error 
-- Show inlay_hints more frequently 
vim.cmd([[
set signcolumn=yes
autocmd CursorHold * lua vim.diagnostic.open_float(nil, { focusable = false })
]])

And then in our completion plugins:

.config/nvim/init.lua

-- Completion Plugin Setup
local cmp = require'cmp'
cmp.setup({
  -- Enable LSP snippets
  snippet = {
    expand = function(args)
        vim.fn["vsnip#anonymous"](args.body)
    end,
  },
  mapping = {
    ['<C-p>'] = cmp.mapping.select_prev_item(),
    ['<C-n>'] = cmp.mapping.select_next_item(),
    -- Add tab support
    ['<S-Tab>'] = cmp.mapping.select_prev_item(),
    ['<Tab>'] = cmp.mapping.select_next_item(),
    ['<C-S-f>'] = cmp.mapping.scroll_docs(-4),
    ['<C-f>'] = cmp.mapping.scroll_docs(4),
    ['<C-Space>'] = cmp.mapping.complete(),
    ['<C-e>'] = cmp.mapping.close(),
    ['<CR>'] = cmp.mapping.confirm({
      behavior = cmp.ConfirmBehavior.Insert,
      select = true,
    })
  },
  -- Installed sources:
  sources = {
    { name = 'path' },                              -- file paths
    { name = 'nvim_lsp', keyword_length = 3 },      -- from language server
    { name = 'nvim_lsp_signature_help'},            -- display function signatures with current parameter emphasized
    { name = 'nvim_lua', keyword_length = 2},       -- complete neovim's Lua runtime API such vim.lsp.*
    { name = 'buffer', keyword_length = 2 },        -- source current buffer
    { name = 'vsnip', keyword_length = 2 },         -- nvim-cmp source for vim-vsnip 
    { name = 'calc'},                               -- source for math calculation
  },
  window = {
      completion = cmp.config.window.bordered(),
      documentation = cmp.config.window.bordered(),
  },
  formatting = {
      fields = {'menu', 'abbr', 'kind'},
      format = function(entry, item)
          local menu_icon ={
              nvim_lsp = 'λ',
              vsnip = '⋗',
              buffer = 'Ω',
              path = '🖫',
          }
          item.menu = menu_icon[entry.source.name]
          return item
      end,
  },
})

With this setup we are now able to have real-time completion capabilities sourcing from rust-analyzer and we can review the associated documentation that pops up:

Rust real-time completion in Neovim

4. Install Tree-sitter and set it up with the tree-sitter-rust parser

Tree-sitter is a fantastic parser generation and incremental parsing library, that supports Rust language bindings and has an available parser Rust tree-sitter-rust.

Neovim's support of Tree-sitter is, at the time of this post, experimental and should be treated as such; however, I have found no issues so far with my setup.

First we need to insall the nvim-treesitter/nvim-treesitter plugin:

.config/nvim/lua/plug.lua:

return require('packer').startup(function()
    -- other plugins...

    use 'nvim-treesitter/nvim-treesitter'

    -- other plugins...
end)

And then configure it... .config/nvim/init.lua

-- Treesitter Plugin Setup 
require('nvim-treesitter.configs').setup {
  ensure_installed = { "lua", "rust", "toml" },
  auto_install = true,
  highlight = {
    enable = true,
    additional_vim_regex_highlighting=false,
  },
  ident = { enable = true }, 
  rainbow = {
    enable = true,
    extended_mode = true,
    max_file_lines = nil,
  }
}

We need to be sure that the ensure_installed = {... "rust", "toml" ...} variable is part of the setup function and that "rust" and "toml" languages are included...

nvim-treesitter allows us to install the tree-sitter-rust parser, effectively enabling all the benefits of Tree-sitter for Rust in Neovim!

We can also check the status of our parsers with :TSInstallInfo and update them with :TSUpdate on the command prompt.

nvim-treesitter also provides a nice view of our parsers with the :checkhealth command and the specific support (e.g. Highlights, Folds, etc.) for each language:

nvim-treesitter: require("nvim-treesitter.health").check()
========================================================================
## Installation
  - WARNING: `tree-sitter` executable not found (parser generator, only needed for :TSInstallFromGrammar, not required for :TSInstall)
  - OK: `node` found v17.7.1 (only needed for :TSInstallFromGrammar)
  - OK: `git` executable found.
  - OK: `cc` executable found. Selected from { vim.NIL, "cc", "gcc", "clang", "cl", "zig" }
    Version: cc (SUSE Linux) 12.1.1 20220721 [revision 4f15d2234608e82159d030dadb17af678cfad626]
  - OK: Neovim was compiled with tree-sitter runtime ABI version 14 (required >=13). Parsers must be compatible with runtime ABI.

## Parser/Features H L F I J
  - toml           ✓ ✓ ✓ ✓ ✓
  - lua            ✓ ✓ ✓ ✓ ✓
  - rust           ✓ ✓ ✓ ✓ ✓

  Legend: H[ighlight], L[ocals], F[olds], I[ndents], In[j]ections
         +) multiple parsers found, only one will be used
         x) errors found in the query, try to run :TSUpdate {lang}

And we can customize as we please.

In my case, I am connecting the folding API in Neovim to the Tree-sitters folding functions:

.config/nvim/lua/opts.lua

-- Treesitter folding 
vim.wo.foldmethod = 'expr'
vim.wo.foldexpr = 'nvim_treesitter#foldexpr()'

And here is the result of my Rust code being folded in Neovim using Tree-sitter:

Rust code folding in Neovim using Tree-sitter

5. Set up Vimspector and CodeLLDB to debug Rust and Rust Tests

Okay, now comes one of the most impotart features of any IDE: having a debugger a couple of clicks away to troubleshoot your code.

As of today, my prefered method is to use the Vimspector plugin with CodeLLDB.

There is also the alternative to use nvim-DAP instead of Vimspector. It looks like a fantastic initiative that is getting traction, but I still have not enabled it in my workflow. Definitely worth a look!

Remember that we already installed CodeLLDB via Mason, so now we just need to install the Vimspector plugin:

.config/nvim/lua/plug.lua:

return require('packer').startup(function()
    -- other plugins...

    use 'puremourning/vimspector'

    -- other plugins...
end)

Second, we can configure Vimspector UI and keymap options to our liking:

.config/nvim/lua/opts.lua:

-- Vimspector options
vim.cmd([[
let g:vimspector_sidebar_width = 85
let g:vimspector_bottombar_height = 15
let g:vimspector_terminal_maxwidth = 70
]])

.config/nvim/lua/keys.lua

-- Vimspector
vim.cmd([[
nmap <F9> <cmd>call vimspector#Launch()<cr>
nmap <F5> <cmd>call vimspector#StepOver()<cr>
nmap <F8> <cmd>call vimspector#Reset()<cr>
nmap <F11> <cmd>call vimspector#StepOver()<cr>")
nmap <F12> <cmd>call vimspector#StepOut()<cr>")
nmap <F10> <cmd>call vimspector#StepInto()<cr>")
]])
map('n', "Db", ":call vimspector#ToggleBreakpoint()<cr>")
map('n', "Dw", ":call vimspector#AddWatch()<cr>")
map('n', "De", ":call vimspector#Evaluate()<cr>")

And finally, the tricky part:

Compile our Rust project with cargo build, cargo run, cargo test, so that we can produce a binary.
Create a .vimspector.json file at the root of your Cargo directory.
Attach CodeLLDB and your Rust application binary to Vimspector in the .vimspector.json file.
Create a debugger breakpoint in your code with :call vimspector#ToggleBreakpoint().
Launch Vimspector and start debugging with :call vimspector#Launch().

app/.vimspector.json

{
  "configurations": {
    "launch": {
      "adapter": "CodeLLDB",
      "filetypes": [ "rust" ],
      "configuration": {
        "request": "launch",
        "program": "${workspaceRoot}/target/debug/app"
      }
    }
  }
}

And, if everything went well we should be greeted by a new debugging session of our Rust code in Neovim.

Rust debugging in Neovim with Vimspector and CodeLLDB

If we want to debug Rust Tests we need to:

Compile the test with cargo test.
Locate the binary produced and printed by the cargo test command (target/debug/deps/app-0683da2c6affeec0 in the example below).
Update .vimspector.json to attach the test binary to the debugging session.
Set a breakpoint inside our test scope and launch Vimspector.

 λ cargo test
   Compiling app v0.1.0 (/home/rsdlt/Documents/RustProjects/app)
    Finished test [unoptimized + debuginfo] target(s) in 0.26s
     Running unittests src/main.rs (target/debug/deps/app-0683da2c6affeec0)

running 2 tests
test tests::first_test ... ok
test tests::test_persona ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

app/.vimspector.json

{
  "configurations": {
    "launch": {
      "adapter": "CodeLLDB",
      "filetypes": [ "rust" ],
      "configuration": {
        "request": "launch",
        "program": "${workspaceRoot}/target/debug/deps/app-0683da2c6affeec0"
      }
    }
  }
}

And again, if everything is properly configured we are greeted with a debugging session of a Rust Test:

Debugging a Rust Test in Neovim with Vimspector and CodeLLDB

Phew, the hard part is over...

Cargo Power with Terminal Access

One of my favorite plugins in Neovim is voldikss/vim-floaterm. I just love the capability to hit a keystroke and have a terminal prompt pop-up right in front of me to input a fast command and then return to my code just as quickly...

In Rust development I mainly use the terminal to execute Cargo commands like cargo run, cargo build, cargo check and cargo test, among others.

To install this plugin:

.config/nvim/lua/plug.lua:

return require('packer').startup(function()
    -- other plugins...

    use 'voldikss/vim-floaterm'

    -- other plugins...
end)

And I have it configured so that I can toggle the terminal pop-up by just pressing t after creating a session with <leader>ft:

-- FloaTerm configuration
map('n', "<leader>ft", ":FloatermNew --name=myfloat --height=0.8 --width=0.7 --autoclose=2 fish <CR> ")
map('n', "t", ":FloatermToggle myfloat<CR>")
map('t', "<Esc>", "<C-\\><C-n>:q<CR>")

Searching at the Speed of Rust

Rust is fast, and so should be getting anywhere in our code.

There are countless plugins and solutions to find and jump within a project. However, in my experience these two plugins are the most essential:

Telescope can leverage other plugins like BurntSushi/ripgrep and sharkdp/fd

Hop is unbelievably joyful, fun and effective to use.

Project status

I mainly use four plugins to keep my project nice and tidy:

kyazdani42/nvim-tree.lua for the typical file explorer - but with the added benefit of displaying Git file status.
preservim/tagbar for an overview of my project structure to quickly see my Structures, Traits, Functions, etc.
folke/todo-comments.nvim to neatly consolidate TODOs, FIXMEs, etc.
folke/trouble.nvim to show in a single panel my rust-analyzer errors and warnings.

And of course, with just one keystroke we can toggle on / off each of these features really fast...

Rust in Neovim with File Explorer, Tagbar, TODOs and Trouble

Better Coding Experience

Other plugins that I use that make my coding experience more enjoyable are:

lukas-reineke/indent-blankline.nvim to show and customize ident lines.
windwp/nvim-autopairs for smart pairing of brackets.
tpope/vim-surround to quickly add, remove or change brackets surrounding any text.
RRethy/vim-illuminate to highlight other uses of word under cursor.
numToStr/Comment.nvim to quickly comment / uncomment text.

Nice Look & Feel

And last, but not least, we can make Neovim look awesome with just a few plugins and tweaks:

m-demare/hlargs.nvim to leverage Tree-sitter and highlight argument definitions.
danilamihailov/beacon.nvim to highlight our prompt when we jump from one location to another.
tanvirtin/monokai.nvim an awesome color theme (used in the screenshots of this post).
navarasu/onedark.nvim another great and popular color theme.
kyazdani42/nvim-web-devicons for cool icons in the file explorer and other places.
lewis6991/impatient.nvim to make Neovim even faster.

Links, references and disclaimers:

Here is the full list of all the Neovim plugins I use as of the date of this post. The credit, and my gratitude, goes to all the hardworking developers that make these awesome open source tools:

Neovim Plugins:
(In alphabetical order)

A version of this post was orginally published on https://rsdlt.github.io