Add augmented assignment (rust-lang#5992), sans wiring.

This is the first part of rust-lang#5992, covering the traits and their
implementations and documentation of it all, but not including the
wiring to make the actual operators (such as `+=`) desugar to the
appropriate method call.

This comes from my old augmented-assignment branch which had the wiring
also but wasn't quite right. Things have changed enough that that wiring
is utterly defunct and unworthy of any attempt at resurrection. The
traits, however, were not, so I have restored that part of the work.

All places in the present code base where any of the arithmetic traits
(`Add`, `Sub`, `Mul`, `Div`, `Rem`, `BitAnd`, `BitOr`, `BitXor`, `Shl`
and `Shr`) were implemented has an `*Assign` trait implementation added,
with the exception (as before and as noted in the code) of `&str` and
`&[T]` where the assignment operators cannot be implemented.

Note that there is necessarily no default implementation of the
`*Assign` traits, as that would preclude more efficient implementations
of the augmented assignment operators and render the whole thing utterly
pointless (c.f. rust-lang#7059 on function specialisation).

src/doc/rust.md

@@ -2044,28 +2044,48 @@ These language items are traits:
 
 * `add`
   : Elements can be added (for example, integers and floats).
+* `add_assign`
+  : Elements can be added with augmented assignment.
 * `sub`
   : Elements can be subtracted.
+* `sub_assign`
+  : Elements can be subtracted with augmented assignment.
 * `mul`
   : Elements can be multiplied.
+* `mul_assign`
+  : Elements can be multiplied with augmented assignment.
 * `div`
   : Elements have a division operation.
+* `div_assign`
+  : Elements have a division operation with augmented assignment.
 * `rem`
   : Elements have a remainder operation.
+* `rem_assign`
+  : Elements have a remainder operation with augmented assignment.
 * `neg`
   : Elements can be negated arithmetically.
 * `not`
   : Elements can be negated logically.
 * `bitxor`
   : Elements have an exclusive-or operation.
+* `bitxor_assign`
+  : Elements have an exclusive-or operation with augmented assignment.
 * `bitand`
   : Elements have a bitwise `and` operation.
+* `bitand_assign`
+  : Elements have a bitwise `and` operation with augmented assignment.
 * `bitor`
   : Elements have a bitwise `or` operation.
+* `bitor_assign`
+  : Elements have a bitwise `or` operation with augmented assignment.
 * `shl`
   : Elements have a left shift operation.
+* `shl_assign`
+  : Elements have a left shift operation with augmented assignment.
 * `shr`
   : Elements have a right shift operation.
+* `shr_assign`
+  : Elements have a right shift operation with augmented assignment.
 * `index`
   : Elements can be indexed.
 * `eq`

src/etc/kate/rust.xml

@@ -58,16 +58,26 @@
 		<item> Ptr </item>
 		<item> Drop </item>
 		<item> Add </item>
+		<item> AddAssign </item>
 		<item> Sub </item>
+		<item> SubAssign </item>
 		<item> Mul </item>
-		<item> Quot </item>
+		<item> MulAssign </item>
+		<item> Div </item>
+		<item> DivAssign </item>
 		<item> Rem </item>
+		<item> RemAssign </item>
 		<item> Neg </item>
 		<item> BitAnd </item>
+		<item> BitAndAssign </item>
 		<item> BitOr </item>
+		<item> BitOrAssign </item>
 		<item> BitXor </item>
+		<item> BitXorAssign </item>
 		<item> Shl </item>
+		<item> ShlAssign </item>
 		<item> Shr </item>
+		<item> ShrAssign </item>
 		<item> Index </item>
 		<item> Not </item>
 	</list>

src/etc/vim/syntax/rust.vim

@@ -64,9 +64,12 @@ syn keyword   rustType        f64 i8 i16 i32 i64 str Self
 " Core operators {{{3
 syn keyword   rustTrait       Copy Send Sized Share
 syn keyword   rustTrait       Add Sub Mul Div Rem Neg Not
+syn keyword   rustTrait       AddAssign SubAssign MulAssign DivAssign RemAssign
 syn keyword   rustTrait       BitAnd BitOr BitXor
+syn keyword   rustTrait       BitAndAssign BitOrAssign BitXorAssign
 syn keyword   rustTrait       Drop Deref DerefMut
 syn keyword   rustTrait       Shl Shr Index
+syn keyword   rustTrait       ShlAssign ShrAssign
 syn keyword   rustEnum        Option
 syn keyword   rustEnumVariant Some None
 syn keyword   rustEnum        Result

src/libcollections/enum_set.rs

@@ -88,18 +88,36 @@ impl<E:CLike> Sub<EnumSet<E>, EnumSet<E>> for EnumSet<E> {
     }
 }
 
+impl<E:CLike> SubAssign<EnumSet<E>> for EnumSet<E> {
+    fn sub_assign(&mut self, e: &EnumSet<E>) {
+        self.bits &= !e.bits;
+    }
+}
+
 impl<E:CLike> BitOr<EnumSet<E>, EnumSet<E>> for EnumSet<E> {
     fn bitor(&self, e: &EnumSet<E>) -> EnumSet<E> {
         EnumSet {bits: self.bits | e.bits}
     }
 }
 
+impl<E:CLike> BitOrAssign<EnumSet<E>> for EnumSet<E> {
+    fn bitor_assign(&mut self, e: &EnumSet<E>) {
+        self.bits |= e.bits;
+    }
+}
+
 impl<E:CLike> BitAnd<EnumSet<E>, EnumSet<E>> for EnumSet<E> {
     fn bitand(&self, e: &EnumSet<E>) -> EnumSet<E> {
         EnumSet {bits: self.bits & e.bits}
     }
 }
 
+impl<E:CLike> BitAndAssign<EnumSet<E>> for EnumSet<E> {
+    fn bitand_assign(&mut self, e: &EnumSet<E>) {
+        self.bits &= e.bits;
+    }
+}
+
 /// An iterator over an EnumSet
 pub struct Items<E> {
     index: uint,