richardanaya/tour_of_rust

A tour of rust's language features

Tour of Rust

Welcome to the source repo of Tour of Rust.

Goals

This project is meant to give an experienced programmer a swift introduction to Rust as an alternative to reading lengthy book style documentation.

• Chapter 1 - The Basics
• Chapter 2 - Basic Control Flow
• Chapter 3 - Basic Data Structure Types
• Chapter 4 - Generic Types
• Chapter 5 - Ownership & Borrowing Data
• Chapter 6 - Text
• Chapter 7 - Object Oriented Programming
• Chapter 8 - Smart Pointers
• Chapter 9 - Project Organization and Structure

Content goals:

• Chapter 1-4 should give you a strong taste of Rust's aesthetic
• Chapter 1-6 should give a person from C a good idea how their ideas translate
• Chapter 1-8 should give a person from C++ a good idea how their ideas translate
• Chapter 9+ should talk about Rust specific concepts that doesn't fit well into the above

This project also aims to provide this book in as many languages as possible.

Contributors

• Deutsch - Felix, Ramin Azhdari, Patrick Hintermayer
• English - Richard Anaya
• Español - Alba Martínez Martínez, (Tech review by Alberto Moreta and Fran Torres)
• Français - Mathieu Gemard, Vincent Foulon
• Interlingue - David MacLeod
• Magyar - Nemin32, Dániel Buga
• Polski - adamsky
• Português Brasileiro - Denstone
• Русский - Danil Kondratiev, Yuriy Larin
• 简体中文 - Tengfei Niu, Haizhi Geng, Zixing Liu
• 繁體中文 - kkpoon, Kai
• 日本語 - 7shi, Rossy, Yuji Sugiura, TaKO8Ki
• 한국어 - fermat39, Sungjin Han
• ภาษาไทย - pallat
• Türkçe - Rust Dili, mertataol, doganid, mhmmdd
• Ελληνικά - DoubleHyphen
• Italian - Andrea Manzini
• العربية - Fethienv

Looking for translators!

If you would like to contribute translations in a language that doesn't exist yet. Feel free to make a PR!

Look for your appropriate language under the lessons folder. Each chapter has its own file. You can modify an existing chapter's content or if there is one you'd like to translate from the english lessons, copy that chapter file over and modify it's content to your own language. Each page has various properties.

• title - this would be your localized page's title
• content_markdown - this would be your localized page's content as markdown using shodown markdown
• code (optional) - this would be your localized page's code. This is the "embedded link" generated from https://play.rust-lang.org/ when you hit the "Share" button. Be sure your run the "rustfmt" tool! If you don't provide code, a page will fallback onto an english version of code (if it exists).

- title: Capítulo 3 - Conclusión
  content_markdown: |
    ¡Rust tiene algunos increíbles ** punteros **!

    * A
    * `let`
    * C
  code: https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=fn%20main()%20%7B%7D%0A

Lastly, there is a file for common words you should fill out your localized translations of for deeper experience of the site.

How to run the project locally

To run the site locally you need to install yq. There are several projects with the name yq, this project uses this one.

Run yarn to install javascript dependencies.

After installing the dependencies use make to launch the site. You will need to restart the server every time to see the changes you've made. Windows users should use make.bat instead.

Releases

Release 5 - May 30, 2020

• Chapter 6 released on text in English, Occidental
• Chapter 5 released in French and Brazillian Portuguese
• Chapter 4 released in Chinese and Spanish
• Chapter 3 released in French
• Minor fixes
• Chapter 2 of Tour of WebAssembly released

Release 4 - May 30, 2020

• Chapter 5 released on ownership and sharing
• Chinese transalations chapter 1-3
• French translations for chapter 1-3
• Brazillian portuguese translations for chapter 2-4
• Spanish translations for chapter 3
• Starting new section for WebAssembly

Release 3 - May 23, 2020

• Chapter 4 released on generic data structures
• Spanish for Chapter 2
• Chapter 1 in brazillian portuguese
• Updates for german and russian
• New pages and rewrites and reordering

Release 2 - May 16, 2020

• Deutsch, English, Interlingue, Русский translations for chapter 2
• Spanish for chapter 1
• New markdown formatting for pages

Release 1 - May 10 2020

• Deutsch, English, Interlingue, Русский translations for chapter 2
• Deutsch, Interlingue, Русский translations for chapter 1
• Domain name setup
• Mobile improvements
• Deeper localization capabilites of generator

Release 0 - May 3rd 2020

• Chapter 1

Credit

This tutorial format and many of the examples were inspired by the wonderful Tour of Go

tour_of_rust's Issues

Is there a example of a native librairy to help creating bindings with JavaScript?

In [Why Dynamic Invocation?](https://tourofrust.com/webassembly/19_en.html)

It is said:

Most people come to WebAssembly to escape JavaScript. Dynamic creation of JavaScript functions allow us to use
libraries in our native language that do the hard part of dynamically creating their bindings without everyone having
to recreate the wheel.

I think we should give an example of such a library (for both Rust and C). Anyone know one of them?

Chapter 8 - Smart Pointers

New chapter on smart pointers

https://tourofrust.com/beta_chapter_8_en.html

@jassler @Dhghomon @knightpp @albatraduce @Denstone @mgemard @spartucus @simeg

[FEATURE] Faster page loads

Currently when swapping between pages the page takes a second before any words appear on an old system at work here, it seems to be because of javascript loading (the rust iframe isn't even loaded yet so it's not the issue). Preventing the javascript from loading each and ever page load would allow swapping between pages a lot faster on slower systems and use less battery on mobile. There are a multitude of ways to do this but generally I opt for unpoly as it can be loaded on the page, then you decorate (just add some attributes to) some links that you want to it do a swap with and instead of the browser downloading the next page, reparsing the javascript, reloading the CSS, etc... it instead does a quick swap of the DOM elements, no reloading of anything else (unless you specify). You can control what is swapped as well though that's less interesting for pages like these. If you need to do something like run some javascript on elements when they get loaded it has a registry for that (think jquery-like matching but significantly faster, it doesn't use jquery). However there are other options, turbolinks is popular but it's less drop-in-and-work while being a lot slower.

Overall this would be a fairly minimal change and would decrease loading times substantially on lower-end hardware (especially as it can optionally prefetch the next page as well for instant swaps). And as it is decorative and enhancement only, the site still falls back to working as it does now when JS is disabled or the site is loaded in a browser without JS (like most CLI browsers).

Chapter 3

Good news! I was able to get Chapter 3 done this weekend. This was by far one of the most challenging chapters i've had to research and write thus far.

Also we have lots of new abilities of our generator!

We can now write our lessons in markdown and use multi-line strings in yaml 🎉 🎉 🎉

This is now way easier to write pages in.

Also, i've been working on a new way I can publish beta content to the website that users can't find, but you all will be able to see in preview.

With that said, I can present to you all chapter 3 content now via link!

https://tourofrust.com/beta_22_en.html

Happy translating!

@jassler @Dhghomon @knightpp @albatraduce

Hi! translate to Korean

Hi!

I want to translate to Korean

Chapter 9 Final Chapter!

Well, it's finally here! I'm not going to announce this final chapter this weekend. I want to give our awesome french translators time to make it into the big announcement. In the meantime, I will be spending time looking over the full content for minor corrections. The end is in sight!

https://tourofrust.com/beta_chapter_9_en.html

French translation

I can do the french translation. Do you already have someone for it?

On Project Goals

I apologize of things have seemed a bit chaotic lately. I've been reflecting a lot on the content ordering. Overall I think we have done a great job. The modularity of our content has made re-ordering easy to do, and only a few missing pages have really been identified.

I wanted to give you all some insight into what I've been thinking about. I recently wrote down in our README where this all is going :)

https://github.com/richardanaya/tour_of_rust#goals

@jassler @Dhghomon @knightpp @albatraduce

Thanks again everyone.

Do page generation in another branch

Currently, all commits go in the master branch, but there is too much 'generating new html' commits.

I think it would be better if page generation would be split into another branch.
Perhaps Makefile would be like this

publish:
    git checkout pages
    // git rebase master // ?
    generate
    lint
    git add .
    git commit -m 'generating new html'
    git push
    git checkout master

Translation to Hungarian

Apologies, I only saw that you also need to make an issue after I opened #214 . Well anyway, most details are in the pull request, but the gist of it is that I wish to start translating this project in my language.

Explaining Rustacean

In Chapter 4, where the usage of unwrap is discussed, the reader is called rustacean. To a newcomer the name might look a bit weird, even if they can make out that it's a portmanteau. I recommend either briefly talking about Rust's "culture" and community in the beginning or including a footnote under the aforementioned section explaining the word.

Tour of Web Assembly Chapter 2

Functions Page - incorrect terminology

https://tourofrust.com/05_en.html

5ab68cf

Suggestion: use page down/page up to change to the next/previous page

ToG always uses page down/page up to change to the next/previous pages, and immediately focuses in the editor. ToR's use of left/right arrows means one needs to click to focus the editor/content depending on what one wants to navigate

from reddit feedback

That way we could keep the focus on the editor and still use page up/down keys to navigate. We will probably need to revert this commit.

Clarification in C4 Graceful Error Handling

Graceful Error Handling
This block of code

match do_something_that_might_fail() {
   Ok(v) => v,
   Err(e) => e,
}

should be

match do_something_that_might_fail() {
   Ok(v) => v,
   Err(e) => return Err(e),
}

because the page tells that it equivalent to do_something_that_might_fail()?

? operator ... If the Option type has None value or the Result type has Err value, return them immediately to the caller of the function.

Lesson 33 is in Chinese

Starting with Chapter 4 (https://tourofrust.com/beta_chapter_4_en.html), clicking on Next links to the Chinese page (https://tourofrust.com/beta_33_en.html)

This is probably because the Key "en" wasn't changed to "zh-cn" (https://github.com/richardanaya/tour_of_rust/blob/master/lessons.yaml#L2739)

Ch. 5 code example is wrong on drop order

The current code example on page 44 reads

struct Foo {
    x: i32,
}

fn main() {
    let foo_a = Foo { x: 42 };
    let foo_b = Foo { x: 13 };

    println!("{}", foo_a.x);
    // foo_a is dropped here because it's no longer
    // used to after this location

    println!("{}", foo_b.x);
    // foo_b is dropped here because of the end
    // of the function scope
}

and suggests that the variables foo_a and foo_b are dropped in the order in which they were defined (at least in this case). However, an explicit Drop implementation à la

impl Drop for Foo {
    fn drop(&mut self) {
        println!("Dropping {}", self.x);
    }
}

makes clear that this is not te case: variables are in fact dropped in reverse declaration order (as is documented in the reference).

---

I'm not yet entirely sure how to fix this. Simply replacing the mistaken commentary with correct commentary, alongside the observation that dropping by reverse declaration order makes intuitive sense because later variables may depend on earlier ones, will go a long way, but there are some hairy cases:

• the presence of function calls that consume variables;
• the difference between declaration order and initialization order.

I may follow up on this when I have finished the book and investigated some more.

Adding to contributors

Hey all, I just wanted to let you know I created a contributors section for your awesome translation work! Feel free to add yourname and a link to your github in a PR :)

https://github.com/richardanaya/tour_of_rust/blob/master/README.md#contributors

@Dhghomon @jassler @knightpp

Missing image in tour of webassembly

On this page (but not only this one): https://tourofrust.com/webassembly/00_en.html

The image of Ferris is missing. I get in the console:

Failed to load resource: net::ERR_BLOCKED_BY_CLIENT ferris_lofi.png:1
Failed to load resource: the server responded with a status of 404 ()

Clarification in C.5 Dereferencing

Currently, the page states as follows

Using references, you can set the owner's value using the * operator.

I think it needs some clarity

Using &mut references, you can set the owner's value using the * operator.

Suggestion: preserves the content of the edits made to the editors even when the page

ToG preserves the content of the edits made to the editors even when the page we're on changes (and has an explicit reset button). ToR reloads the editor with the original content if you switch from one page to another.

from reddit feedback

Would it be possible to do something like this?

Suggestion for new chapters: async, closures, multithread

from reddit feedback

What do you think?

Displaying error messages if Rust Playground is blocked?

First, thanks for your efforts on Tour of Rust: I'm glad to see such a project as it will certainly help people get started with Rust. 👍

When I visited the site when the first chapter was announced, only the left side rendered and the playground didn't show up. It gave the appearance of being broken and hid all the hard work done for the project.

I'm using Firefox with the Privacy Badger extension and it blocked the playground. Is it possible to show a placeholder to help make it clear the playground should load on the right side of the screen?

Screenshot example from today:

Thanks again for your work on this!

Adding common words

I'd like to go for an even deeper experience for a language, I started a common words section so that people can see many words on the website navigation and table of contents in their native language.

https://github.com/richardanaya/tour_of_rust/blob/master/lessons.json#L2

@Dhghomon @jassler @knightpp

Chapter 2

https://richardanaya.github.io/tour_of_rust/13_en.html

@Dhghomon @jassler @knightpp

discussion about immutability

You say here

• immutable - the location in memory can only be read

Infering that the location in memory can not be written.
Technicaly, this is not 100% correct:

Immutability does not imply that the object as stored in the computer's memory is unwriteable. Rather, immutability is a compile-time construct that indicates what a programmer can do through the normal interface of the object, not necessarily what they can absolutely do (for instance, by circumventing the type system or violating const correctness in C or C++).

Taken from Immutable object on wikipedia

I am not sure if this apply to rust though.

Just wanted to let you know.

New Page: Arrays

I felt like arrays really needed to be discussed in the first chapter.

Also a little rewrite on basic types

#46

Page Rewrite - Exporting

Rewrote export page to be more consistent, have more relevant code example.

WebAssembly spelling

I believe the right way to spell WebAssembly is as it is, not Web Assembly (two words).

I have a PR drafted to fix this and I'd submit if you dont mind.

Split out returning from loop to it's own page

I split out returning from a loop to it's own page.

@jassler I might not have retained the correctness of the german version https://tourofrust.com/19_de.html

Language specific index.html

I added a generator for language specific index.html (i.e. index.fr.htmlpages, could use some help with the common words!

146ac69#diff-db303626eda2923d0b99a33f03b3566eR11

@jassler @Dhghomon @knightpp @albatraduce @Denstone @mgemard @spartucus @simeg @VincentFoulon80

Left and right arrows to change page does not work if there is a playground on the page

I do not know if anyone has the same problem but I cannot go to previous/next page if there is a Rust playground on the page.

Once the playground is loaded, it get the focus and right/left arrows can only be used to navigate in the code.

Can't we just not focus on the playground when we load the page?

Split the giant Markdown file

Having every chapter, in every language, in one large Markdown file makes it awkward to submit pull requests.

Adding new word "Untranslated"

d45e796

@jassler @Dhghomon @knightpp @albatraduce @Denstone

Translate to chinese

Chapter 4 - Generic Types

New chapter is up! Let me know what you think :)

https://tourofrust.com/beta_33_en.html

[ie] problem in the Interlingue translation

There is a problem on this page.

Also in the lessons.yaml file, for this page, some part are missing. Compare the english version with the interlingue version:

  - en:
      title: Dynamic vs Static Dispatch
      code: https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&code=struct%20SeaCreature%20%7B%0A%20%20%20%20pub%20name%3A%20String%2C%0A%20%20%20%20noise%3A%20String%2C%0A%7D%0A%0Aimpl%20SeaCreature%20%7B%0A%20%20%20%20pub%20fn%20get_sound(%26self)%20-%3E%20%26str%20%7B%0A%20%20%20%20%20%20%20%20%26self.noise%0A%20%20%20%20%7D%0A%7D%0A%0Atrait%20NoiseMaker%20%7B%0A%20%20%20%20fn%20make_noise(%26self)%3B%0A%7D%0A%0Aimpl%20NoiseMaker%20for%20SeaCreature%20%7B%0A%20%20%20%20fn%20make_noise(%26self)%20%7B%0A%20%20%20%20%20%20%20%20println!(%22%7B%7D%22%2C%20%26self.get_sound())%3B%0A%20%20%20%20%7D%0A%7D%0A%0Afn%20static_make_noise(creature%3A%20%26SeaCreature)%20%7B%0A%20%20%20%20%2F%2F%20we%20know%20the%20real%20type%0A%20%20%20%20creature.make_noise()%3B%0A%7D%0A%0Afn%20dynamic_make_noise(noise_maker%3A%20%26dyn%20NoiseMaker)%20%7B%0A%20%20%20%20%2F%2F%20we%20don't%20know%20the%20real%20type%0A%20%20%20%20noise_maker.make_noise()%3B%0A%7D%0A%0Afn%20main()%20%7B%0A%20%20%20%20let%20creature%20%3D%20SeaCreature%20%7B%0A%20%20%20%20%20%20%20%20name%3A%20String%3A%3Afrom(%22Ferris%22)%2C%0A%20%20%20%20%20%20%20%20noise%3A%20String%3A%3Afrom(%22blub%22)%2C%0A%20%20%20%20%7D%3B%0A%20%20%20%20static_make_noise(%26creature)%3B%0A%20%20%20%20dynamic_make_noise(%26creature)%3B%0A%7D%0A
      content_markdown: |
        Methods are executed in two ways:
        * static dispatch - When the instance type is known, we have direct knowledge of what function to call.
        * dynamic dispatch - When an instance type is not known, we must find out some way of calling the correct function.

        Traits types `&dyn MyTrait` give us the ability to work with instances of objects indirectly using dynamic dispatch.

        When dynamic dispatch is used, Rust will encourage you to put `dyn` before your trait type so people are aware.

        Memory details:
        * Dynamic dispatch is slightly slower because of the pointer chasing to find the real function call.

ie:
   title: Dinamic contra Static Dispatch (Depeche)
   content: |
     On execute metodes secun du manieres quam seque:
     * dispatch static - Quande on save li tip del instantie, noi save directmen pri quel function a vocar.
     * dispatch dinamic - Quande on ne save li tip del instantie, noi deve trovar un maniere por vocar li function corect.

     Li tip de un trate `&dyn MyTrait` possibilisa li manipulation de objectes índirectmen con dispatch dinamic.

Chapter 6 - Text

https://tourofrust.com/beta_chapter_6_en.html

Question about generics

In What Are Generic Types?

You say in a comment:

// Note: by using generic types here, we create compile-time created types
// making our code-size bigger. Turbofish let's us be explicit.

Did you mean smaller instead of bigger?

question about LLVM

In this page https://tourofrust.com/59_en.html, you talk about the LLVM compiler.

Did you meant Rust compiler instead?

If not, this is the first time you talk about LLVM. Maybe you should explain what it is briefly. Is it used by the Rust compiler to make somes optimizations? Is there a reason you talked about it here?

Translate to Japanese

Hi! Seems there is no Japanese version after chapter 2.
Has the translation process already begun?
If don't, I want to do it.

format code according to rust style

Run rustfmt through the code, 4 spaces, 100 chars width, there should also be space in between parenthesis and curly braces. This allow more consistency with other rust code and easier to read.

https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md

New Page - Calling Methods

Realized we probably need this page :)

https://tourofrust.com/beta_25_en.html

Chapter 7 - Object Oriented Programming

https://tourofrust.com/chapter_7_en.html

@jassler @Dhghomon @knightpp @albatraduce @Denstone @mgemard @spartucus @simeg

Remove cosmetic whitespace from Markdown

The Markdown documents are split into short lines (perhaps an attempt at 80 character lines?).

This might be nice for people with editors that don't wrap, but not nice for people who want to contribute since it makes it hard to search for strings in the files (because the sentence you're looking for might have a linebreak in the middle of it, and indentation at the beginning of the next line as well).

I ran into this multiple times when I recently corrected a bunch of typos that I found while going through the ToR in my browser - when I went looking for those sentences in the source code, I often had to search by regex.

new home page error 404

When I am on this page and I click on "Français", I get a 404 error page.

The same thing happens for others languages except english.

Declaring project complete

Hey all, I think it's time we declare this project complete! I wanted to personally say thank you to you all. I had no idea when I started this I'd encounter so many amazing helpful people along the way. This experience really opened my eyes to the collaboration that can happen on the internet when people all just want to make something to help the technology community.

I don't know if it's an international thing, but if you want, feel free to connect with me at.

https://www.linkedin.com/in/richardanaya/

I work on robot related tech in my personal life and tend to share my other mad science and thoughts there. :)

@jassler @Dhghomon @knightpp @albatraduce @Denstone @mgemard @spartucus @simeg @VincentFoulon80 @7shi

[WASM] chapter 1: typo in css styles font-family

On main.html, the font-family displayed in the header is "san-serif" instead of "sans-serif"

Seen on FR and EN translations for "1+1", "Importing Functions", "Logging Text". Maybe beyond these.
I didn't verified for other translations but we need to check and fix them.

Chapter 5

The beta for chapter 5 up. This was the most difficult chapter to write.

https://tourofrust.com/beta_chapter_5_en.html

@jassler @Dhghomon @knightpp @albatraduce @Denstone

Tour of Web Assembly Chapter 1

Hey all, I started a new Tour of Web Assembly. I know you all might not be interested in web tech, but if you are, feel free to contribute to wasm.yaml!

https://tourofrust.com/webassembly

@jassler @Dhghomon @knightpp @albatraduce @Denstone @mgemard @spartucus