From f6095119fe95ae83c8bd2385537e30519105bd61 Mon Sep 17 00:00:00 2001
From: KirkMcDonald <KirkMcDonald@1df65b71-e716-0410-9316-ac55df2b1602>
Date: Mon, 14 Aug 2006 20:33:21 +0000
Subject: [PATCH] html_doc: Automatic operator overloading documented

git-svn-id: http://svn.dsource.org/projects/pyd/trunk@36 1df65b71-e716-0410-9316-ac55df2b1602
---
 html_doc/class_wrapping.html | 32 +++++++++++++++++++++++++++-----
 html_doc/pyd.css             | 14 ++++++++++++++
 2 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/html_doc/class_wrapping.html b/html_doc/class_wrapping.html
index 3796ef3..c106d90 100644
--- a/html_doc/class_wrapping.html
+++ b/html_doc/class_wrapping.html
@@ -62,11 +62,22 @@ <h1>Class wrapping</h1>
 
 <p>If you have a class <code>Foo</code>, you can check whether it is wrapped by simply checking whether <code>is_wrapped!(Foo)</code> is true. It is important to note that this is <em>not</em> a <code>const bool</code>, it is a <em>runtime</em> check.</p>
 
-<h3>Automatic operator overloading</h3>
+<h3><a class="anchor" name="opwrap">Automatic operator overloading</a></h3>
 
-<p><i>Docs coming soon...</i></p>
+<p>Pyd will automatically wrap most of D's operator overload functions with appropriate Python operator overloads. There are some caveats:</p>
 
-<h3>Examples</h3>
+<ul>
+<li>Pyd will only automatically wrap the lexically first <i>opFunc</i> defined for a given <i>opFunc</i>. <i>(In the future, I may add a mechanism allowing a user to specifiy a specific overload of an opFunc.)</i></li>
+<li>The usual rules for function wrapping apply: Only an <i>opFunc</i> whose return type and arguments are <a href="conversion.html">convertable</a> may be wrapped. <i>(The current implementation is pretty dumb: If the lexically first opFunc has an unconvertable return type or argument, the operator overload will still be wrapped, but won't work.)</i></li>
+</ul>
+
+<p>At the moment, only the following operator overloads are supported:</p>
+
+<p><code>opAdd, opSub, opMul, opDiv, opMod, opAnd, opOr, opXor, opShl, opShr, opCat, opAddAssign, opSubAssign, opMulAssign, opDivAssign, opModAssign, opAndAssign, opOrAssign, opXorAssign, opShlAssign, opShrAssign, opCatAssign, opIn_r</code></p>
+
+<p>Most notably missing from this list are <code>opIndex, opIndexAssign, opSlice, opSliceAssign, opCall</code>, and <code>opApply</code>. Support for these operators is forthcoming. Also missing from the list are <code>opUShr</code> and <code>opUShrAssign</code>. Python does not have an unsigned right-shift operator, so these operator overloads are not supported. (You may still wrap them with a normal method using <code>wrapped_class.def</code>, of course.)</p>
+
+<h3><a class="anchor" name="examples">Examples</a></h3>
 
 <p>Suppose we have the following simple class:</p>
 
@@ -77,6 +88,7 @@ <h3>Examples</h3>
 
     <span class="keyword">this</span>() { m_i = <span class="number">0</span>; }
     <span class="keyword">this</span>(<span class="keyword">int</span> j) { m_i = j; }
+    <span class="keyword">this</span>(<span class="keyword">int</span> j, <span class="keyword">int</span> k) { m_i = j + k; }
 
     <span class="keyword">int</span> i() { <span class="keyword">return</span> m_i; }
     <span class="keyword">void</span> i(<span class="keyword">int</span> j) { m_i = j; }
@@ -84,6 +96,10 @@ <h3>Examples</h3>
     <span class="keyword">void</span> foo(<span class="keyword">char</span>[] s) {
         writefln(s, m_i);
     }
+
+    Foo opAdd(Foo rhs) {
+        <span class="keyword">return new</span> Foo(m_i + rhs.m_i);
+    }
 }</pre>
 
 <p>We would expose this class to Python by putting this code in our init function after the call to <code>module_init</code>:</p>
@@ -94,8 +110,8 @@ <h3>Examples</h3>
 f.def!(Foo.foo, <span class="string">"foo"</span>);
 <span class="comment">// Wrap the "i" property</span>
 f.prop!(Foo.i, <span class="string">"i"</span>);
-<span class="comment">// Wrap the constructor.</span>
-f.init!(tuple!(<span class="keyword">int</span>));
+<span class="comment">// Wrap the constructors.</span>
+f.init!(tuple!(<span class="keyword">int</span>), tuple!(<span class="keyword">int</span>, <span class="keyword">int</span>));
 finalize_class(f);</pre>
 
 <p>Now we can use this type from within Python like any other type.</p>
@@ -107,9 +123,15 @@ <h3>Examples</h3>
 &gt;&gt;&gt; f.i = 20
 &gt;&gt;&gt; f.foo("Hello! i is ")
 Hello! i is 20
+&gt;&gt;&gt; f = Foo(10, 10)
+&gt;&gt;&gt; f.i
+20
 &gt;&gt;&gt; g = Foo(30)
 &gt;&gt;&gt; g.i
 30
+&gt;&gt;&gt; e = f + g
+&gt;&gt;&gt; e.i
+50
 &gt;&gt;&gt; # We can even subclass our D type
 &gt;&gt;&gt; class MyFoo(Foo):
 ... 	def bar(self):
diff --git a/html_doc/pyd.css b/html_doc/pyd.css
index 401db95..3c9d7f7 100644
--- a/html_doc/pyd.css
+++ b/html_doc/pyd.css
@@ -25,6 +25,7 @@ div#nav {
     line-height: 140%;
     width: 150px;
 }
+/* navbar links */
 a.nav {
     text-decoration: none;
     font-weight: bold;
@@ -40,6 +41,7 @@ a.nav:hover {
     color: black;
     background-color: #d8d8d8;
 }
+/* the current navbar link */
 a.navcur {
     text-decoration: none;
     font-weight: bold;
@@ -56,6 +58,18 @@ a.navcur:hover {
     color: #f0f0f0;
     background-color: #305880;
 }
+/* section header anchors */
+a.anchor {
+    color: black;
+}
+a.anchor:active {
+    color: black;
+}
+a.anchor:hover {
+    text-decoration: none;
+    background-color: #d8d8d8;
+}
+/* normal links */
 a {
     color: #103860;
 }