<p dir="auto">Was: <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="54745980" data-permission-text="Title is private" data-url="https://github.com/rust-lang/prev.rust-lang.org/issues/89" data-hovercard-type="issue" data-hovercard-url="/rust-lang/prev.rust-lang.org/issues/89/hovercard" href="https://github.com/rust-lang/prev.rust-lang.org/issues/89">rust-lang/prev.rust-lang.org#89</a>, from <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/gnzlbg/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/gnzlbg">@gnzlbg</a>, submitted January 19th 2015.</p>
<hr>
<p dir="auto">Hi,</p>
<p dir="auto">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 <code class="notranslate">Vec&lt;T&gt;</code> (is this the right data-structure in rust for an array of dynamic size?). My first step was to create a vector of <code class="notranslate">size</code> elements initialized to a default value of <code class="notranslate">0</code>. So:</p>
<ul dir="auto">
<li>I went to the <a href="http://doc.rust-lang.org/book/arrays-vectors-and-slices.html" rel="nofollow">Arrays, Vectors, and Slices</a> part of the book, where:
<ul dir="auto">
<li>I see how I can use the <code class="notranslate">vec!</code> macro,</li>
<li>I see how I can use <code class="notranslate">push</code>.</li>
<li>I see a link to the <code class="notranslate">Vec&lt;T&gt;</code> documentation, so...</li>
</ul>
</li>
<li>I went to the <a href="http://doc.rust-lang.org/std/vec/" rel="nofollow"><code class="notranslate">Vec&lt;T&gt;</code> documentation</a>:
<ul dir="auto">
<li>this looks... empty,</li>
<li>I see how I can use <code class="notranslate">new</code> to create an empty vector,</li>
<li>I guess <code class="notranslate">new(size)</code> and <code class="notranslate">new(size, default_value)</code> might work (I have a C++ background), but the compiler is helpful here and tells me that there is only <code class="notranslate">new()</code>. Ok, keep looking!</li>
<li>I search in the docs for <code class="notranslate">Vec</code> and arrive at:</li>
</ul>
</li>
<li><a href="http://doc.rust-lang.org/std/vec/struct.Vec.html" rel="nofollow"><code class="notranslate">std::vec::Vec</code></a>. I wonder why I didn't land here in the first place. Here:
<ul dir="auto">
<li>
<p dir="auto">I see more examples using: <code class="notranslate">len</code>, <code class="notranslate">iter</code>, this page looks good, I feel I'm getting close :)</p>
</li>
<li>
<p dir="auto">There is a section about initializing a vector with a capacity using <code class="notranslate">Vec::with_capacity</code> and why this should be preferred, this is almost what I want!</p>
</li>
<li>
<p dir="auto">I guess <code class="notranslate">Vec::with_size</code> without success, it seems I'm not there yet, so...</p>
</li>
<li>
<p dir="auto">I read the rest of the doc there, but it seems I'm out of luck.</p>
</li>
<li>
<p dir="auto">I go back to <code class="notranslate">Vec::resize(new_len, value)</code>, it seems that <code class="notranslate">value</code> is not documented, but I guess that it would be the default value, so...</p>
</li>
<li>
<p dir="auto">I try:</p>
<div class="highlight highlight-source-rust notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="    let mut v : Vec&lt;f64&gt; = Vec::with_capacity(size);
    v.resize(size, 0.0);"><pre class="notranslate">    <span class="pl-k">let</span> <span class="pl-k">mut</span> v <span class="pl-kos">:</span> <span class="pl-smi">Vec</span><span class="pl-kos">&lt;</span><span class="pl-smi">f64</span><span class="pl-kos">&gt;</span> = <span class="pl-smi">Vec</span><span class="pl-kos">::</span><span class="pl-en">with_capacity</span><span class="pl-kos">(</span>size<span class="pl-kos">)</span><span class="pl-kos">;</span>
    v<span class="pl-kos">.</span><span class="pl-en">resize</span><span class="pl-kos">(</span>size<span class="pl-kos">,</span> <span class="pl-c1">0.0</span><span class="pl-kos">)</span><span class="pl-kos">;</span></pre></div>
</li>
</ul>
</li>
</ul>
<p dir="auto">which gives a warning but works as expected.</p>
<p dir="auto">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 <code class="notranslate">with_capacity</code> 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: <code class="notranslate">erase_remove_if</code> 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, <code class="notranslate">flat_set</code>).</p>
<ul dir="auto">
<li>I decide to fill an issue in the rust documentation and to give rust another try in a couple of months:
<ul dir="auto">
<li>nowhere in the book could I find where to fill issues,</li>
<li>went to the rust language on github where I read somewhere that the documentation belongs to the website</li>
<li>supposed that rust-www host the website and also the documentation...</li>
</ul>
</li>
</ul>
<p dir="auto">Another <em>small</em> 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 <code class="notranslate">i32</code>. I guessed <code class="notranslate">double</code> and failed, but then guessed <code class="notranslate">f64</code> and it worked. I then googled <code class="notranslate">rust primitive types</code> and got a link to the reference where all primitive types where shown. A table explaining <code class="notranslate">iX</code> for integers, <code class="notranslate">fX</code> for doubles, <code class="notranslate">str</code> for chars where <code class="notranslate">X</code> is the width of the data type would have saved me jumping around through tabs and googling.</p>
<p dir="auto">Recent changes landed that broke Rust on Mac OS 10.9 (Mavericks) and above, see <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="42678136" data-permission-text="Title is private" data-url="https://github.com/rust-lang/rust/issues/17214" data-hovercard-type="issue" data-hovercard-url="/rust-lang/rust/issues/17214/hovercard" href="https://github.com/rust-lang/rust/issues/17214">#17214</a></p>
<p dir="auto">The problem is that the linker is being passed an argument that works for <code class="notranslate">gcc</code>, but that <code class="notranslate">clang</code> rejects. (Mac OS moved wholesale to <code class="notranslate">clang</code> in 10.9, it appears.)</p>
<p dir="auto">Unfortunately, this breakage wasn't caught by bors. Apparently the testing infrastructure is running an older version of Mac OS and therefor using <code class="notranslate">gcc</code> rather than <code class="notranslate">clang</code>.</p>
<p dir="auto">To avoid surprise Mac OS breakage in the future, we should make sure to test against <code class="notranslate">clang</code> before landing PRs.</p>
<p dir="auto">cc <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/brson/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/brson">@brson</a> <a class="user-mention notranslate" data-hovercard-type="organization" data-hovercard-url="/orgs/kballard/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/kballard">@kballard</a> <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/pnkfelix/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/pnkfelix">@pnkfelix</a></p>