Automated docs update

Author: Document updater

docs/exception-safety.html

@@ -155,45 +155,89 @@ <h1 class="menu-title"></h1>
 
                 <div id="content" class="content">
                     <main>
-                        <h1><a class="header" href="#exception-safety" id="exception-safety">Exception Safety</a></h1>
-<p>Although programs should use unwinding sparingly, there's a lot of code that
-<em>can</em> panic. If you unwrap a None, index out of bounds, or divide by 0, your
+                        <!--
+# Exception Safety
+-->
+<h1><a class="header" href="#例外安全性" id="例外安全性">例外安全性</a></h1>
+<!--
+Although programs should use unwinding sparingly, there's a lot of code that
+*can* panic. If you unwrap a None, index out of bounds, or divide by 0, your
 program will panic. On debug builds, every arithmetic operation can panic
 if it overflows. Unless you are very careful and tightly control what code runs,
-pretty much everything can unwind, and you need to be ready for it.</p>
-<p>Being ready for unwinding is often referred to as <em>exception safety</em>
+pretty much everything can unwind, and you need to be ready for it.
+-->
+<p>プログラム内では巻き戻しを注意深く使用するべきですが、パニック<em>し得る</em>コードが
+たくさんあります。もし None をアンラップしたり、境界外のインデックスを指定したり、
+0 で除算したりしたら、プログラムはパニックするでしょう。デバッグビルドでは、
+全ての算術演算は、オーバーフロー時にパニックします。非常に注意深く、
+そしてどのコードを実行するかを厳しくコントロールしない限り、ほとんどすべての
+コードが巻き戻しをする可能性があり、これに対して準備をする必要があります。</p>
+<!--
+Being ready for unwinding is often referred to as *exception safety*
 in the broader programming world. In Rust, there are two levels of exception
-safety that one may concern themselves with:</p>
+safety that one may concern themselves with:
+-->
+<p>巻き戻しに対して準備が出来ていることは、もっと広いプログラミングの世界において、
+しばしば<em>例外安全</em>と呼ばれています。 Rust では、プログラムが関わる可能性のある、
+2 つの例外安全のレベルがあります。</p>
+<!--
+* In unsafe code, we *must* be exception safe to the point of not violating
+  memory safety. We'll call this *minimal* exception safety.
+
+* In safe code, it is *good* to be exception safe to the point of your program
+  doing the right thing. We'll call this *maximal* exception safety.
+-->
 <ul>
 <li>
-<p>In unsafe code, we <em>must</em> be exception safe to the point of not violating
-memory safety. We'll call this <em>minimal</em> exception safety.</p>
+<p>アンセーフなコードでは、メモリ安全性を侵害しないという点において、
+例外安全で<em>なければなりません</em>。これを、<em>最小限</em>の例外安全と呼びます。</p>
 </li>
 <li>
-<p>In safe code, it is <em>good</em> to be exception safe to the point of your program
-doing the right thing. We'll call this <em>maximal</em> exception safety.</p>
+<p>安全なコードでは、プログラムが正しいことを行なうという点において、
+例外安全であると<em>良い</em>です。これを<em>最大限</em>の例外安全と呼びます。</p>
 </li>
 </ul>
-<p>As is the case in many places in Rust, Unsafe code must be ready to deal with
+<!--
+As is the case in many places in Rust, Unsafe code must be ready to deal with
 bad Safe code when it comes to unwinding. Code that transiently creates
 unsound states must be careful that a panic does not cause that state to be
 used. Generally this means ensuring that only non-panicking code is run while
 these states exist, or making a guard that cleans up the state in the case of
 a panic. This does not necessarily mean that the state a panic witnesses is a
-fully coherent state. We need only guarantee that it's a <em>safe</em> state.</p>
-<p>Most Unsafe code is leaf-like, and therefore fairly easy to make exception-safe.
+fully coherent state. We need only guarantee that it's a *safe* state.
+-->
+<p>Rust の多くの場において事実なのですが、巻き戻しとなると、アンセーフなコードは、
+悪い安全なコードに対処する準備をしなければなりません。一時的に健全ではない
+状態を生むコードは、パニックによってその状態が使用されないよう、注意深く
+扱わなければなりません。通常これは、このような健全でない状態が存在する間、
+パニックを起こさないコードのみを確実に実行させることを意味するか、あるいは
+パニックの際、その状態を片付けるガードを生成することを意味します。
+これは必ずしも、パニックが起きているときの状態が、完全に一貫した状態であるということを
+意味しません。<em>安全な</em>状態であると保証されていることだけが必要なのです。</p>
+<!--
+Most Unsafe code is leaf-like, and therefore fairly easy to make exception-safe.
 It controls all the code that runs, and most of that code can't panic. However
 it is not uncommon for Unsafe code to work with arrays of temporarily
 uninitialized data while repeatedly invoking caller-provided code. Such code
-needs to be careful and consider exception safety.</p>
+needs to be careful and consider exception safety.
+-->
+<p>ほとんどのアンセーフなコードは葉のようなもの (訳注: それ以上別の関数を呼ぶことが
+ない) で、それ故に割と簡単に例外安全に出来ます。実行するコードは完全に制御されていて、
+そしてほとんどのコードはパニックしません。しかし、アンセーフなコードが
+繰り返し呼び出し側のコードを実行している間に、部分的に初期化されていない配列を
+扱うことはよくあります。このようなコードは注意深く扱い、例外安全を考える必要があるのです。</p>
 <h2><a class="header" href="#vecpush_all" id="vecpush_all">Vec::push_all</a></h2>
-<p><code>Vec::push_all</code> is a temporary hack to get extending a Vec by a slice reliably
-efficient without specialization. Here's a simple implementation:</p>
+<!--
+`Vec::push_all` is a temporary hack to get extending a Vec by a slice reliably
+efficient without specialization. Here's a simple implementation:
+-->
+<p><code>Vec::push_all</code> は、特殊化なしに、スライスが確実に効率的であることを利用した、
+Vec を伸ばす一時的なハックです。これは単純な実装です。</p>
 <pre><code class="language-rust ignore">impl&lt;T: Clone&gt; Vec&lt;T&gt; {
     fn push_all(&amp;mut self, to_push: &amp;[T]) {
         self.reserve(to_push.len());
         unsafe {
-            // can't overflow because we just reserved this
+            // 今さっき reserve をしたので、オーバーフローするはずがありません
             self.set_len(self.len() + to_push.len());
 
             for (i, x) in to_push.iter().enumerate() {
@@ -203,44 +247,83 @@ <h2><a class="header" href="#vecpush_all" id="vecpush_all">Vec::push_all</a></h2
     }
 }
 </code></pre>
-<p>We bypass <code>push</code> in order to avoid redundant capacity and <code>len</code> checks on the
+<!--
+We bypass `push` in order to avoid redundant capacity and `len` checks on the
 Vec that we definitely know has capacity. The logic is totally correct, except
-there's a subtle problem with our code: it's not exception-safe! <code>set_len</code>,
-<code>offset</code>, and <code>write</code> are all fine; <code>clone</code> is the panic bomb we over-looked.</p>
-<p>Clone is completely out of our control, and is totally free to panic. If it
+there's a subtle problem with our code: it's not exception-safe! `set_len`,
+`offset`, and `write` are all fine; `clone` is the panic bomb we over-looked.
+-->
+<p>絶対にキャパシティがあると分かっている Vec の capacity と <code>len</code> の余分なチェックを
+回避するため、 <code>push</code> を使用していません。論理は完全に正しいです。但し、
+このコードに微妙な問題が含まれていることを除く。すなわち、このコードは例外安全
+ではないのです! <code>set_len</code> と <code>offset</code> と <code>write</code> は全部問題ありません。 <code>clone</code> は、
+我々が見落としていたパニックの起爆装置です。</p>
+<!--
+Clone is completely out of our control, and is totally free to panic. If it
 does, our function will exit early with the length of the Vec set too large. If
-the Vec is looked at or dropped, uninitialized memory will be read!</p>
-<p>The fix in this case is fairly simple. If we want to guarantee that the values
-we <em>did</em> clone are dropped, we can set the <code>len</code> every loop iteration. If we
+the Vec is looked at or dropped, uninitialized memory will be read!
+-->
+<p>Clone は全く制御不能で、全く自由にパニックしてしまいます。もしパニックしてしまえば、
+この関数は、 Vec の長さが大きすぎる値に設定されたまま、早期に終了してしまいます。
+もし Vec が読み出されたりドロップされたりすると、未初期化のメモリが読み出されて
+しまいます!</p>
+<!--
+The fix in this case is fairly simple. If we want to guarantee that the values
+we *did* clone are dropped, we can set the `len` every loop iteration. If we
 just want to guarantee that uninitialized memory can't be observed, we can set
-the <code>len</code> after the loop.</p>
+the `len` after the loop.
+-->
+<p>この場合、修正は割と簡単です。もし<em>本当に</em>、クローンした値がドロップされたと
+いうことを保証したいのなら、全てのループのイテレーションにおいて、 <code>len</code> を
+設定することが出来ます。もし単に、未初期化のメモリが読まれないようにしたいのなら、
+ループの後に <code>len</code> を設定することが出来ます。</p>
 <h2><a class="header" href="#binaryheapsift_up" id="binaryheapsift_up">BinaryHeap::sift_up</a></h2>
-<p>Bubbling an element up a heap is a bit more complicated than extending a Vec.
-The pseudocode is as follows:</p>
+<!--
+Bubbling an element up a heap is a bit more complicated than extending a Vec.
+The pseudocode is as follows:
+-->
+<p>ヒープにおけるアップヒープは Vec を伸ばすことよりちょっと複雑です。擬似コードはこんな感じです。</p>
 <pre><code class="language-text">bubble_up(heap, index):
     while index != 0 &amp;&amp; heap[index] &lt; heap[parent(index)]:
         heap.swap(index, parent(index))
         index = parent(index)
 
 </code></pre>
-<p>A literal transcription of this code to Rust is totally fine, but has an annoying
-performance characteristic: the <code>self</code> element is swapped over and over again
-uselessly. We would rather have the following:</p>
+<!--
+A literal transcription of this code to Rust is totally fine, but has an annoying
+performance characteristic: the `self` element is swapped over and over again
+uselessly. We would rather have the following:
+-->
+<p>このコードを Rust に直訳するのは全く問題ありません。ですが、嫌になるようなパフォーマンス
+です。すなわち、 <code>self</code> の要素が無駄に交換され続けます。それならむしろ、以下のコードの方が
+良いでしょう。</p>
 <pre><code class="language-text">bubble_up(heap, index):
     let elem = heap[index]
-    while index != 0 &amp;&amp; element &lt; heap[parent(index)]:
+    while index != 0 &amp;&amp; elem &lt; heap[parent(index)]:
         heap[index] = heap[parent(index)]
         index = parent(index)
     heap[index] = elem
 </code></pre>
-<p>This code ensures that each element is copied as little as possible (it is in
+<!--
+This code ensures that each element is copied as little as possible (it is in
 fact necessary that elem be copied twice in general). However it now exposes
 some exception safety trouble! At all times, there exists two copies of one
 value. If we panic in this function something will be double-dropped.
 Unfortunately, we also don't have full control of the code: that comparison is
-user-defined!</p>
-<p>Unlike Vec, the fix isn't as easy here. One option is to break the user-defined
-code and the unsafe code into two separate phases:</p>
+user-defined!
+-->
+<p>このコードでは確実に、それぞれの要素ができるだけ少ない回数でコピーされます
+(実は一般的に、要素を 2 回コピーすることが必要なのです) 。しかし、これによって、
+いくつか例外安全性の問題が露見しました! 毎回、ある値に対する 2 つのコピーが
+存在します。もしこの関数内でパニックしたら、何かが 2 回ドロップされてしまいます。
+残念ながら、このコードに関しても、完全にコントロールすることは出来ません。
+比較がユーザ定義されているのです!</p>
+<!--
+Unlike Vec, the fix isn't as easy here. One option is to break the user-defined
+code and the unsafe code into two separate phases:
+-->
+<p>Vec とは違い、これを直すのは簡単ではありません。一つの選択肢として、ユーザ定義の
+コードとアンセーフなコードを、 2 つの段階に分割することです。</p>
 <pre><code class="language-text">bubble_up(heap, index):
     let end_index = index;
     while end_index != 0 &amp;&amp; heap[end_index] &lt; heap[parent(end_index)]:
@@ -252,14 +335,29 @@ <h2><a class="header" href="#binaryheapsift_up" id="binaryheapsift_up">BinaryHea
         index = parent(index)
     heap[index] = elem
 </code></pre>
-<p>If the user-defined code blows up, that's no problem anymore, because we haven't
+<!--
+If the user-defined code blows up, that's no problem anymore, because we haven't
 actually touched the state of the heap yet. Once we do start messing with the
 heap, we're working with only data and functions that we trust, so there's no
-concern of panics.</p>
-<p>Perhaps you're not happy with this design. Surely it's cheating! And we have
-to do the complex heap traversal <em>twice</em>! Alright, let's bite the bullet. Let's
-intermix untrusted and unsafe code <em>for reals</em>.</p>
-<p>If Rust had <code>try</code> and <code>finally</code> like in Java, we could do the following:</p>
+concern of panics.
+-->
+<p>もしユーザ定義のコードでトラブっても、もう問題ありません。なぜなら、
+ヒープの状態にはまだ触れていないからです。ヒープを実際に弄るとき、
+信用しているデータや関数のみを扱っています。ですからもうパニックの心配は
+ありません。</p>
+<!--
+Perhaps you're not happy with this design. Surely it's cheating! And we have
+to do the complex heap traversal *twice*! Alright, let's bite the bullet. Let's
+intermix untrusted and unsafe code *for reals*.
+-->
+<p>多分、この設計を嬉しく思わないでしょう。明らかに騙している! そして複雑な
+ヒープのトラバーサルを <em>2 回</em> 行わなければならない! 分かった、我慢しよう。
+信用していないコードやアンセーフなコードを<em>本気で</em>混ぜてみよう。</p>
+<!--
+If Rust had `try` and `finally` like in Java, we could do the following:
+-->
+<p>もし Rust に Java のような <code>try</code> と <code>finally</code> があったら、コードは
+こんな感じだったでしょう。</p>
 <pre><code class="language-text">bubble_up(heap, index):
     let elem = heap[index]
     try:
@@ -269,18 +367,31 @@ <h2><a class="header" href="#binaryheapsift_up" id="binaryheapsift_up">BinaryHea
     finally:
         heap[index] = elem
 </code></pre>
-<p>The basic idea is simple: if the comparison panics, we just toss the loose
+<!--
+The basic idea is simple: if the comparison panics, we just toss the loose
 element in the logically uninitialized index and bail out. Anyone who observes
-the heap will see a potentially <em>inconsistent</em> heap, but at least it won't
+the heap will see a potentially *inconsistent* heap, but at least it won't
 cause any double-drops! If the algorithm terminates normally, then this
-operation happens to coincide precisely with the how we finish up regardless.</p>
-<p>Sadly, Rust has no such construct, so we're going to need to roll our own! The
+operation happens to coincide precisely with the how we finish up regardless.
+-->
+<p>基本的な考えは単純です。すなわち、もし比較においてパニックしたのなら、単に要素を
+論理的に未初期化のインデックスの位置に保存し、脱出します。このヒープを観察する誰もが、
+潜在的には<em>一貫性のない</em>ヒープを目にするでしょうが、少なくともこのコードは二重ドロップを
+起こしません! もしアルゴリズムが通常通り終了すれば、この操作はコードがどのように終了するかに
+関わらず、結果を正確に一致させるために実行されます。</p>
+<!--
+Sadly, Rust has no such construct, so we're going to need to roll our own! The
 way to do this is to store the algorithm's state in a separate struct with a
-destructor for the &quot;finally&quot; logic. Whether we panic or not, that destructor
-will run and clean up after us.</p>
+destructor for the "finally" logic. Whether we panic or not, that destructor
+will run and clean up after us.
+-->
+<p>悲しいことに、 Rust にはそのような構造が存在しません。ですので、自分たちで退避させなければ
+ならないようです! これを行なうには、 &quot;finally&quot; の論理を構成するため、デストラクタと共に
+アルゴリズムの状態を、別の構造体に保存します。パニックしようがしまいが、デストラクタは
+実行され、状態を綺麗にします。</p>
 <pre><code class="language-rust ignore">struct Hole&lt;'a, T: 'a&gt; {
     data: &amp;'a mut [T],
-    /// `elt` is always `Some` from new until drop.
+    /// `elt` は new で生成されたときからドロップまで、常に Some です
     elt: Option&lt;T&gt;,
     pos: usize,
 }
@@ -313,7 +424,7 @@ <h2><a class="header" href="#binaryheapsift_up" id="binaryheapsift_up">BinaryHea
 
 impl&lt;'a, T&gt; Drop for Hole&lt;'a, T&gt; {
     fn drop(&amp;mut self) {
-        // fill the hole again
+        // 穴を再び埋めます
         unsafe {
             let pos = self.pos;
             ptr::write(&amp;mut self.data[pos], self.elt.take().unwrap());
@@ -324,15 +435,15 @@ <h2><a class="header" href="#binaryheapsift_up" id="binaryheapsift_up">BinaryHea
 impl&lt;T: Ord&gt; BinaryHeap&lt;T&gt; {
     fn sift_up(&amp;mut self, pos: usize) {
         unsafe {
-            // Take out the value at `pos` and create a hole.
+            // `pos` にある値を受け取り、穴を作ります。
             let mut hole = Hole::new(&amp;mut self.data, pos);
 
             while hole.pos() != 0 {
                 let parent = parent(hole.pos());
                 if hole.removed() &lt;= hole.get(parent) { break }
                 hole.move_to(parent);
             }
-            // Hole will be unconditionally filled here; panic or not!
+            // 状況に関わらず、穴はここで埋まります。パニックしてもしなくても!
         }
     }
 }