Hi,
I just tried rust for the first time. From the description of the language, I decided to try a dynamic array first, since in my head this is the most important data structure in a low level language (e.g., for cache performance). So I decided to write a small program using a Vec<T> (is this the right data-structure in rust for an array of dynamic size?). My first step was to create a vector of size elements initialized to a default value of 0. So:
- I went to the Arrays, Vectors, and Slices part of the book, where:
- I see how I can use the
vec! macro,
- I see how I can use
push.
- I see a link to the
Vec<T> documentation, so...
- I went to the
Vec<T> documentation:
- this looks... empty,
- I see how I can use
new to create an empty vector,
- I guess
new(size) and new(size, default_value) might work (I have a C++ background), but the compiler is helpful here and tells me that there is only new(). Ok, keep looking!
- I search in the docs for
Vec and arrive at:
std::vec::Vec. I wonder why I didn't land here in the first place. Here:
-
I see more examples using: len, iter, this page looks good, I feel I'm getting close :)
-
There is a section about initializing a vector with a capacity using Vec::with_capacity and why this should be preferred, this is almost what I want!
-
I guess Vec::with_size without success, it seems I'm not there yet, so...
-
I read the rest of the doc there, but it seems I'm out of luck.
-
I go back to Vec::resize(new_len, value), it seems that value is not documented, but I guess that it would be the default value, so...
-
I try:
let mut v : Vec<f64> = Vec::with_capacity(size);
v.resize(size, 0.0);
which gives a warning but works as expected.
I'm left with a very weird feeling. I'll try to explain it. What in my head should be the most used data structure in a low level language, and thus the most used data structure in rust, turned out to be barely and poorly documented. The best part of the documentation is, without doubt, the "Capacity and reallocation" where with_capacity is explained. Most of the other functions there are missing documentation. Almost none of the functions have the algorithmic/memory complexity documented. Even in those functions that are documented, some arguments aren't. I think that for vector even the growth factor (which is an implementation detail) should be included in the documentation since it can be interesting to know it in some applications (or while debugging/profiling performance). Besides improving the documentation of all these functions, the documentation of vector could be improved significantly by including different "sub sections" like "Capacity and reallocation". Those I would have found useful are: "Initialization" (how to initialize a vector: with a capacity/size, with/without default constructed elements, from slice, from pointer and length, from raw array, using the vec! macro...), "Insertion" (push, insert, resize.. and how are the elements initialized when they are created), "Deletion" (pop, selectively delete some elements based on predicate: erase_remove_if in C++, resize.. and what happens if I resize below the current size), "Memory layout" (capacity, extend capacity, shrink to fit, ...), "Iteration" (how to iterate over a vector), "Common patterns" (sort + remove duplicates, stack, queue, flat_set).
- I decide to fill an issue in the rust documentation and to give rust another try in a couple of months:
- nowhere in the book could I find where to fill issues,
- went to the rust language on github where I read somewhere that the documentation belongs to the website
- supposed that rust-www host the website and also the documentation...
Another small issue I had at the beginning was that nowhere in the introduction did I find a link or a table with the primitive data types. Most of the introduction uses i32. I guessed double and failed, but then guessed f64 and it worked. I then googled rust primitive types and got a link to the reference where all primitive types where shown. A table explaining iX for integers, fX for doubles, str for chars where X is the width of the data type would have saved me jumping around through tabs and googling.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent