Esoteric bit operations.

sdk/lib/core/int.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * Representation of Dart integers containing integer specific
  * operations and specialization of operations inherited from [num].
  *
@@ skipping 81 matching lines @@
    */
   int operator >>(int shiftAmount);
 
   /** Returns true if and only if this integer is even. */
   bool get isEven;
 
   /** Returns true if and only if this integer is odd. */
   bool get isOdd;
 
   /**
+   * Returns the minimum number of bits required to store this integer.
+   *
+   * The number of bits excludes the sign bit, which gives the natural length
+   * for non-negative (unsigned) values.  Negative values are complemented to
+   * return the bit position of the first bit that differs from the sign bit.
+   *
+   * To find the the number of bits needed to store the value as a signed value,
+   * add one, i.e. use `x.bitLength + 1`.
+   *
+   *      x.bitLength == (-x-1).bitLength
+   *
+   *      3.bitLength == 2;     // 00000011
+   *      2.bitLength == 2;     // 00000010
+   *      1.bitLength == 1;     // 00000001
+   *      0.bitLength == 0;     // 00000000
+   *      (-1).bitLength == 0;  // 11111111
+   *      (-2).bitLength == 1;  // 11111110
+   *      (-3).bitLength == 2;  // 11111101
+   *      (-4).bitLength == 2;  // 11111100
+   */
+  int get bitLength;
+
+  /**
+   * Returns the least significant [width] bits of this integer as a
+   * non-negative number (i.e. unsigned representation).  The returned value has
+   * zeros in all bit positions higher than [width].
+   *
+   *     (-1).toUnsigned(5) == 32   // 11111111  ->  00011111
+   *
+   * This operation can be used to simulate arithmetic from low level languages.
+   * For example, to increment an 8 bit quantity:
+   *
+   *     q = (q + 1).toUnsigned(8);
+   */
+  int toUnsigned(int width);
+
+  /**
+   * Returns the least significant [width] bits of this integer, extending the
+   * highest retained bit to the sign.  This is the same as truncating the value
+   * to fit in [width] bits using an signed 2-s complement representation.  The
+   * returned value has the same bit value in all positions higher than [width].
+   *
+   *                                    V--sign bit-V
+   *     16.toSigned(5) == -16   //  00010000 -> 11110000
+   *     239.toSigned(5) == 15   //  11101111 -> 00001111
+   *                                    ^           ^

[Lasse Reichstein Nielsen, 2013/09/06 12:40:11]

If I'm correct then 
  x == x.toSigned(x.bitLength + 1)
always holds.
Is it worth mentioning? I gave me an appreciation of the behavior that wasn't
easy to get just looking at the individual operations.

Is there a relation with toUnsigned as well?

[sra1, 2013/09/06 22:11:57]

I added this relation to the documentation.

+   */
+  int toSigned(int width);
+
+  /**
    * Return the negative value of this integer.
    *
    * The result of negating an integer always has the opposite sign, except
    * for zero, which is its own negation.
    */
   int operator -();
 
   /**
    * Returns the absolute value of this integer.
    *
@@ skipping 65 matching lines @@
    * value is used instead. If no [onError] is provided, a [FormatException]
    * is thrown.
    *
    * The [onError] function is only invoked if [source] is a [String]. It is
    * not invoked if the [source] is, for example, `null`.
    */
   external static int parse(String source,
                             { int radix,
                               int onError(String source) });
 }