I put this under functional languages, since it is really an example of the concept of "type classes" in Rust. If this specific example is more of a design pattern, I would be happy to move it.

If no one beats me to it, I should be able to fix the two FIXMEs at the bottom sometime next week.

With more contributors, more differences in writing style will become apparent. This issue is a proposal to start a guideline to be able to refer back to for consistent writing.

Most words if not all, seem to use the British style (e.g. -ise endings such as 'finalise'; also used in Australia and New Zealand), to name just one example. One may out of habit (or stubbornness) use US-style. Using US-style could be discussed, but it's important to have agreement upon consistency.

A good example of inconsistent language usage is the usage of "we" and "you":

We can avoid this by using &str instead, and letting &String coerce to a &str whenever the function is invoked.

Source: idioms/coercion-arguments

This pattern is only of interest in Rust. In GC'd languages, you'd take the reference to the value by default (and the GC would keep track of refs), and in other low-level languages like C you'd simply alias the pointer and fix things later.

However, in Rust, we have to do a little more work to do this. An owned value may only have one owner, so to take it out, we need to put something back in

Source: idioms/mem-replace

One could argue that this is done on purpose in this specific instance, but it felt out of place when I read it. But there's also the usage of "me":

The etymology here is unclear to me. The terms 'fold' and 'folder' are used in the Rust compiler, although it appears to me to be more like a map than a fold in the usual sense. See the discussion below for more details.

Source: patterns/fold

Most of the text is also written informally (e.g. 'anyways' over 'anyway') and with abbreviations (in this instance of 'GC', even without explanation).

I am not necessarily suggesting a change and lots of things could be considered gray area (grey area?), but it would be good if there is some writing guideline to be able to refer to when in doubt.

As the intro says, this is a pure functional concept that Rust doesn't often use directly, but can be used to help understand some very "functional" looking APIs, such as Serde.

It is a rather difficult concept, even for me, so the wording might not be the best. I'm open to any feedback and improvements.

This doctests all code examples. There is some fallout to either ignore examples (if I deemed them too far from runnable) or change them to work, or at least compile.

~~I also added a .travis.yml so we can use CI to check PRs.~~

fixes #49

This is still in draft because it's early, but I wanted to open this PR to claim it and show where I'm going. Let me know if this is the right approach, or if I missed conversation occurring elsewhere and jumped the gun.

Looking through the PRs and the Issues, it looked like no one was tackling FFI. Well, I volunteer!

It's a big subject, of course, so I'm only offering one small part: exporting Rust type APIs to other languages, using object-based API design.

The example may seem rather obscure, but I think it's a good illustration. It is also one I am very familiar with. I learned Rust by trying to port the QDBM library from C (before finding something off-the-shelf). I got about half way done, and learned a lot about C bindings and memory safety! :smile: I figure this is the best way to capture a lot of that knowledge, and share it with the world.

Should we try preparing the book to be included as part of the rustup install or maybe we shouldn't do it? Rust API Guidelines isn't there as well but I wonder if it would be good to have both taken in at the same time? This allows people to read it offline and while having it bundled with the official docs, but of course the quality needs to be there first (maybe the team needs to review). Or maybe we could take the first them by creating a rustup component?

I claim that the builder pattern is more or less an anti-pattern and that you should use the Default trait instead. Here's why:

Let's say we have a struct:

pub struct Window {
    pub title: &'static str,
    pub width: usize,
    pub height: usize,
}

1. The builder pattern produces way too much code on the creators side while not having a significant amount of code reduction on the users side. This is especially visible if the struct has more fields:

Creator:

// Builder pattern
pub struct WindowBuilder {
    __title: &'static str,
    __width: usize,
    __height: usize,
}

impl WindowBuilder {
    pub fn new() -> Self {
        Self {
            __title: "Default title",
            __width: 800,
            __title: 600,
        }
    }

    pub fn with_title(self, title: &'static str) -> Self {
        Self {
            __title: title,
            __width: self.width,
            __title: self.height,
        }
    }
    
    pub fn with_dimensions(self, width: usize, height: usize) -> Self {
        Self {
            __title: self.title,
            __width: width,
            __title: height,
        }
    }

    pub fn build(self) -> Window {
        Window {
            title: self.title,
            width: self.width,
            height: self.height,
        }
    }
}

// Default pattern: much less code!
impl Default for Window {
    fn default() -> Self {
        Self {
           title: "Default title",
           width: 800,
           height: 600,
        }
    }
}

See how much code we need to construct a window in comparison to the Default trait?

User:

// Default pattern
let window = Window {
     title: "Original title",
    .. Default::default()
};

// Builder pattern: not a significant reduction of usage code!
let window = WindowBuilder::new()
                     .with_title("Original title")
                     .build();

2. The builder pattern doesn't protect against double-initialization:

let window = WindowBuilder::new()
                     .with_title("Original title")
                     .with_dimensions(800, 600)
                     .with_title("Oops, overwritten title!")
                     .build();

The Default trait protects against that, because you can't initialize the same field twice. The builder pattern simply overwrites the field and you don't get any warning.

3. The Default trait eliminates the need for the SomethingBuilder struct. The SomethingBuilder struct is an intermediate struct that provides a certain kind of type safety so that you have to call SomethingBuilder.build() to construct a Something out of a SomethingBuilder. All of this is unnecessary if you use the Default trait - less code with essentially the same outcome. The SomethingBuilder has one appropriate use, in my opinion: When you need something to happen in the .build() function and it needs to happen once (although you can implement this in a default() function, too). For example, you need to tell the OS to create a window. This is where it's appropriate to use a builder. However, I've seen the builder pattern to be completely overused, which is why I'm writing this.

Often times when I'm having a struct with many fields that can have default values, it is easier to implement a default trait than to write ten or twenty builder functions. And that is why I claim that the builder pattern is actually an anti-pattern and that you should use the Default trait instead, wherever possible. It should at least be included somewhere in this repository.

I recently started collecting some API design patterns here. I'm not sure if these match what this repo is all about (or which ones you already cover), but I just wanted to say: Feel free to take anything you like from that post! :)

• Public type aliases
• Use conversion traits
• Laziness: Use Iterators
• Laziness: Take closures
• Custom traits for input parameters
• Extension traits
• Builder pattern
• Session types

(The markdown source of that post is here and I hereby relicense the content as MPL2 (in addition to CC-BY) and allow you to use it in this repo.)

Due to inactivity of the author and maintainers not being able to edit the PR I'll move #23 to a new branch in this repository.

Future fixes to the PR will be made on this branch.

Hi @lambda-fairy,

you stated here that this repo needs some help, how do you imagine helping with this repository? MarcoIeni & me would like to help. We could start reviewing all past issues and merging/closing or give some feedback to all pending PRs.

Long-term, we would also like to turn this repo into a rust book that can be served with GitHub pages to the community.

Cheers, Simonsan & MarcoIeni

Requesting a design pattern for functions that take lots of parameters. For example this way:

fn foo(parameter_0: type, parameter_1: type, parameter_2: type, parameter_3: type, parameter_4: type, parameter_5: type, parameter_6: type) -> type {
    // function body
}

is a way that I think should be an anti-pattern because it's too wide. I prefer things to be less than 80 chars wide.

The section 5.2. Generics as Type Classes contains the following paragraph:

In object-oriented languages, classes can inherit behavior from their parents. However, this allows the attachment of not only additional behavior to particular members of a type class, but extra behavior as well.

which I find fairly confusing. The second sentence contains repetitive words and does not clarify the first statement enough. It would help if this paragraph was rewritten and/or expanded to add meaning and additional information. Thanks!

Inspired by the talk Rust in 2024 by Niko Matsakis (at 37m20s) I was thinking we may be able to create some more learning resources about that here to help to reduce accidental complexity for people being new to Rust.

We have an article about interacting with the borrow checker (Anti-Pattern/Clone to satisfy the borrow checker), but I feel that more a don't than how to interact usually with the borrow checker.

We may also revisit https://github.com/rust-unofficial/patterns/pull/323 to make these things overall more visible, I even thought about a new category for "Borrow Checker Pattterns" because they are quite exclusive to Rust (and may change within each edition).

tmarsh1024 1 hr. ago

I love seeing more discussion and presentations of optics such as lenses and prisms. I do find their treatment in this document, however, more than a little confusing.

A lot of the discussion of lenses is focused on achieving structural typing (accessing a field by name if it exists on the struct without knowing the nominal type in advance). I've never witnessed optics in the context of structural or duck typing before and certainly isn't the usually touted benefit. The lenses section goes on to mention that the power in rust really comes from composition but stops there and doesn't show any examples.

The section on prisms is mistaken in its characterization that prisms represent families of optics. This is no more true than it is true for the lens - both prisms and lenses can be generated from the simpler iso optic. In some representations of optics prisms can be seen as dual to lenses, another way lenses and prisms are peer level.

I didn't understand the visitor example and the discussion of type erasure, which all seemed to me very far removed from anything to do with prisms.

Maybe I'm missing something here, and I admit to not reading too deeply when I got confused, but I would definitely recommend the audience and the explanation be reevaluated. Like I said, I would love for these topics to be more broadly presented!

CC: @jhwgh1968

I asked the person to leave some feedback here as well, so we can improve on the article. But we could start discussing given feedback on top.

I think it would be nice to mention that one should be careful when writing drop implementations on guards relatively to the double panic possibility when they find out about this pattern for the first time or are unaware of double panicking generally.

It might help someone inexperienced I suppose.

Floating point numbers are known to be an imperfect model of real numbers, causing rounding errors in calculations and difficulty for equality comparison.

For example, the Euclidean length example in the Interpreter chapter using sqrt has an average error of 2.9 bits for 4-dimension and 13.9 bits for 2-dimension, with more and bigger errors (over 56-bit errors) happening at points very close to the axes. This can be improved by using hypot ("hypotenus") instead. (Herbie page for 4D Euclid length) (Herbie page for 2D Euclid length)

Similarly, taking the angle between two 2-dimentional vectors has an average error of 34.3 bits, again with more and bigger errors (64-bit errors) closer to the axes, can be improved with hypot and mul_add (aka fma, "fused multiply add") to cut the average error down to 18.9 bits. (Herbie page for angle between vectors)

(The error figures above are taken from the results of Herbie project.)

A related problem is that nominally equal floating point expressions often do not compare equal due to rounding errors. This necessitates something like the crate float-cmp.

These are not Rust specific idioms per se, but I feel like this is a good place to raise awareness of these errors and list Rust specific solutions.