core: fixed more comments and slight bug.

The bug involves the incorrect logic for `core::num::flt2dec::decoder`.
This makes some numbers in the form of 2^n inaccurate by one digit;
the regression tests have been added.

src/libcore/num/flt2dec/bignum.rs

@@ -216,7 +216,7 @@ macro_rules! define_bignum {
                     self.base[i] = 0;
                 }
 
-                // shift by `nbits` bits
+                // shift by `bits` bits
                 let mut sz = self.size + digits;
                 if bits > 0 {
                     let last = sz;

src/libcore/num/flt2dec/decoder.rs

@@ -73,21 +73,21 @@ pub fn decode<T: DecodableFloat>(v: T) -> (/*negative?*/ bool, FullDecoded) {
         FpCategory::Infinite => FullDecoded::Infinite,
         FpCategory::Zero => FullDecoded::Zero,
         FpCategory::Subnormal => {
-            // (mant - 2, exp) -- (mant, exp) -- (mant + 2, exp)
+            // neighbors: (mant - 2, exp) -- (mant, exp) -- (mant + 2, exp)
             // Float::integer_decode always preserves the exponent,
             // so the mantissa is scaled for subnormals.
             FullDecoded::Finite(Decoded { mant: mant, minus: 1, plus: 1,
                                           exp: exp, inclusive: even })
         }
         FpCategory::Normal => {
             let minnorm = <T as DecodableFloat>::min_pos_norm_value().integer_decode();
-            if mant == minnorm.0 && exp == minnorm.1 {
-                // (maxmant, exp - 1) -- (minnormmant, exp) -- (minnormmant + 1, exp)
+            if mant == minnorm.0 {
+                // neighbors: (maxmant, exp - 1) -- (minnormmant, exp) -- (minnormmant + 1, exp)
                 // where maxmant = minnormmant * 2 - 1
-                FullDecoded::Finite(Decoded { mant: mant << 1, minus: 1, plus: 2,
-                                              exp: exp - 1, inclusive: even })
+                FullDecoded::Finite(Decoded { mant: mant << 2, minus: 1, plus: 2,
+                                              exp: exp - 2, inclusive: even })
             } else {
-                // (mant - 1, exp) -- (mant, exp) -- (mant + 1, exp)
+                // neighbors: (mant - 1, exp) -- (mant, exp) -- (mant + 1, exp)
                 FullDecoded::Finite(Decoded { mant: mant << 1, minus: 1, plus: 1,
                                               exp: exp - 1, inclusive: even })
             }

src/libcore/num/flt2dec/estimator.rs

@@ -18,6 +18,8 @@
 pub fn estimate_scaling_factor(mant: u64, exp: i16) -> i16 {
     // 2^(nbits-1) < mant <= 2^nbits if mant > 0
     let nbits = 64 - (mant - 1).leading_zeros() as i64;
+    // 1292913986 = floor(2^32 * log_10 2)
+    // therefore this always underestimates (or is exact), but not much.
     (((nbits + exp as i64) * 1292913986) >> 32) as i16
 }
 

src/libcoretest/num/flt2dec/mod.rs

@@ -216,6 +216,13 @@ pub fn f32_shortest_sanity_test<F>(mut f: F) where F: FnMut(&Decoded, &mut [u8])
     // 10^18 * 0.314159231156617216
     check_shortest!(f(3.141592e17f32) => b"3141592", 18);
 
+    // regression test for decoders
+    // 33554430
+    // 33554432
+    // 33554436
+    let twoto25: f32 = StdFloat::ldexp(1.0, 25);
+    check_shortest!(f(twoto25) => b"33554432", 8);
+
     // 10^39 * 0.340282326356119256160033759537265639424
     // 10^39 * 0.34028234663852885981170418348451692544
     // 10^39 * 0.340282366920938463463374607431768211456
@@ -308,6 +315,13 @@ pub fn f64_shortest_sanity_test<F>(mut f: F) where F: FnMut(&Decoded, &mut [u8])
     // 10^18 * 0.314159200000000064
     check_shortest!(f(3.141592e17f64) => b"3141592", 18);
 
+    // regression test for decoders
+    // 18446744073709549568
+    // 18446744073709551616
+    // 18446744073709555712
+    let twoto64: f64 = StdFloat::ldexp(1.0, 64);
+    check_shortest!(f(twoto64) => b"18446744073709552", 20);
+
     // pathological case: high = 10^23 (exact). tie breaking should always prefer that.
     // 10^24 * 0.099999999999999974834176
     // 10^24 * 0.099999999999999991611392