Fix some doc formatting problems, stop using "set" methods for NumberFormat

pkg/intl/lib/number_format.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 intl;
 /**
  * Provides the ability to format a number in a locale-specific way. The
  * format is specified as a pattern using a subset of the ICU formatting
  * patterns.
  *
- * 0 - A single digit
- * # - A single digit, omitted if the value is zero
- * . - Decimal separator
- * - - Minus sign
- * , - Grouping separator
- * E - Separates mantissa and expontent
- * + - Before an exponent, indicates it should be prefixed with a plus sign.
- * % - In prefix or suffix, multiply by 100 and show as percentage
- * \u2030 - In prefix or suffix, multiply by 1000 and show as per mille
- * \u00A4 - Currency sign, replaced by currency name
- * ' - Used to quote special characters
- * ; - Used to separate the positive and negative patterns if both are present
+ * - `0` A single digit
+ * - `#` A single digit, omitted if the value is zero
+ * - `.` Decimal separator
+ * - `-` Minus sign
+ * - `,` Grouping separator
+ * - `E` Separates mantissa and expontent
+ * - `+` - Before an exponent, indicates it should be prefixed with a plus sign.
+ * - `%` - In prefix or suffix, multiply by 100 and show as percentage
+ * - `‰ (\u2030)` In prefix or suffix, multiply by 1000 and show as per mille
+ * - `¤ (\u00A4)` Currency sign, replaced by currency name
+ * - `'` Used to quote special characters
+ * - `;` Used to separate the positive and negative patterns if both are present
  *
  * For example,
  *       var f = new NumberFormat("###.0#", "en_US");
  *       print(f.format(12.345));
  *       ==> 12.34
  * If the locale is not specified, it will default to the current locale. If
  * the format is not specified it will print in a basic format with at least
  * one integer digit and three fraction digits.
  *
  * There are also standard patterns available via the special constructors. e.g.
  *       var symbols = new NumberFormat.percentFormat("ar");
  * There are four such constructors: decimalFormat, percentFormat,
- * scientificFormat and currencyForamt. However, at the moment,
+ * scientificFormat and currencyFormat. However, at the moment,
  * scientificFormat prints only as equivalent to "#E0" and does not take
  * into account significant digits. currencyFormat will always use the name
  * of the currency rather than the symbol.
  */
 class NumberFormat {
   /** Variables to determine how number printing behaves. */
   // TODO(alanknight): If these remain as variables and are set based on the
   // pattern, can we make them final?
   String _negativePrefix = '-';
   String _positivePrefix = '';
   String _negativeSuffix = '';
   String _positiveSuffix = '';
   /**
    * How many numbers in a group when using punctuation to group digits in
    * large numbers. e.g. in en_US: "1,000,000" has a grouping size of 3 digits
    * between commas.
    */
   int _groupingSize = 3;
   bool _decimalSeparatorAlwaysShown = false;
   bool _useSignForPositiveExponent = false;
   bool _useExponentialNotation = false;
 
-  int _maximumIntegerDigits = 40;
-  int _minimumIntegerDigits = 1;
-  int _maximumFractionDigits = 3;
-  int _minimumFractionDigits = 0;
-  int _minimumExponentDigits = 0;
+  int maximumIntegerDigits = 40;
+  int minimumIntegerDigits = 1;
+  int maximumFractionDigits = 3;
+  int minimumFractionDigits = 0;
+  int minimumExponentDigits = 0;
 
   int _multiplier = 1;
 
   /**
    * Stores the pattern used to create this format. This isn't used, but
    * is helpful in debugging.
    */
   String _pattern;
-  /**
-   * Set the maximum digits printed to the left of the decimal point.
-   * Normally this is computed from the pattern, but it's exposed here for
-   * testing purposes and for rare cases where you want to force it explicitly.
-   */
-  void setMaximumIntegerDigits(int max) {
-    _maximumIntegerDigits = max;
-  }
-
-  /**
-   * Set the minimum number of digits printed to the left of the decimal point.
-   * Normally this is computed from the pattern, but it's exposed here for
-   * testing purposes and for rare cases where you want to force it explicitly.
-   */
-  void setMinimumIntegerDigits(int min) {
-    _minimumIntegerDigits = min;
-  }
-
-  /**
-   * Set the maximum number of digits printed to the right of the decimal point.
-   * Normally this is computed from the pattern, but it's exposed here for
-   * testing purposes and for rare cases where you want to force it explicitly.
-   */
-  void setMaximumFractionDigits(int max) {
-    _maximumFractionDigits = max;
-  }
-
-  /**
-   * Set the minimum digits printed to the left of the decimal point.
-   * Normally this is computed from the pattern, but it's exposed here for
-   * testing purposes and for rare cases where you want to force it explicitly.
-   */
-  void setMinimumFractionDigits(int max) {
-    _minimumFractionDigits = max;
-  }
 
   /** The locale in which we print numbers. */
   final String _locale;
 
   /** Caches the symbols used for our locale. */
   NumberSymbols _symbols;
 
   /**
    * Transient internal state in which to build up the result of the format
    * operation. We can have this be just an instance variable because Dart is
@@ skipping 93 matching lines @@
   void _formatExponential(num number) {
     if (number == 0.0) {
       _formatFixed(number);
       _formatExponent(0);
       return;
     }
 
     var exponent = (log(number) / log(10)).floor();
     var mantissa = number / pow(10.0, exponent);
 
-    var minIntDigits = _minimumIntegerDigits;
-    if (_maximumIntegerDigits > 1 &&
-        _maximumIntegerDigits > _minimumIntegerDigits) {
+    var minIntDigits = minimumIntegerDigits;
+    if (maximumIntegerDigits > 1 &&
+        maximumIntegerDigits > minimumIntegerDigits) {
       // A repeating range is defined; adjust to it as follows.
       // If repeat == 3, we have 6,5,4=>3; 3,2,1=>0; 0,-1,-2=>-3;
       // -3,-4,-5=>-6, etc. This takes into account that the
       // exponent we have here is off by one from what we expect;
       // it is for the format 0.MMMMMx10^n.
-      while ((exponent % _maximumIntegerDigits) != 0) {
+      while ((exponent % maximumIntegerDigits) != 0) {
         mantissa *= 10;
         exponent--;
       }
       minIntDigits = 1;
     } else {
       // No repeating range is defined, use minimum integer digits.
-      if (_minimumIntegerDigits < 1) {
+      if (minimumIntegerDigits < 1) {
         exponent++;
         mantissa /= 10;
       } else {
-        exponent -= _minimumIntegerDigits - 1;
-        mantissa *= pow(10, _minimumIntegerDigits - 1);
+        exponent -= minimumIntegerDigits - 1;
+        mantissa *= pow(10, minimumIntegerDigits - 1);
       }
     }
     _formatFixed(mantissa);
     _formatExponent(exponent);
   }
 
   /**
    * Format the exponent portion, e.g. in "1.3e-5" the "e-5".
    */
   void _formatExponent(num exponent) {
     _add(symbols.EXP_SYMBOL);
     if (exponent < 0) {
       exponent = -exponent;
       _add(symbols.MINUS_SIGN);
     } else if (_useSignForPositiveExponent) {
       _add(symbols.PLUS_SIGN);
     }
-    _pad(_minimumExponentDigits, exponent.toString());
+    _pad(minimumExponentDigits, exponent.toString());
   }
 
   /** Used to test if we have exceeded Javascript integer limits. */
   final _maxInt = pow(2, 52);
 
   /**
    * Format the basic number portion, inluding the fractional digits.
    */
   void _formatFixed(num number) {
     // Very fussy math to get integer and fractional parts.
-    var power = pow(10, _maximumFractionDigits);
+    var power = pow(10, maximumFractionDigits);
     var shiftedNumber = (number * power);
     // We must not roundToDouble() an int or it will lose precision. We must not
     // round() a large double or it will take its loss of precision and
     // preserve it in an int, which we will then print to the right
     // of the decimal place. Therefore, only roundToDouble if we are already
     // a double.
     if (shiftedNumber is double) {
       shiftedNumber = shiftedNumber.roundToDouble();
     }
     var intValue, fracValue;
     if (shiftedNumber.isInfinite) {
       intValue = number.toInt();
       fracValue = 0;
     } else {
       intValue = shiftedNumber.round() ~/ power;
       fracValue = (shiftedNumber - intValue * power).floor();
     }
-    var fractionPresent = _minimumFractionDigits > 0 || fracValue > 0;
+    var fractionPresent = minimumFractionDigits > 0 || fracValue > 0;
 
     // If the int part is larger than 2^52 and we're on Javascript (so it's
     // really a float) it will lose precision, so pad out the rest of it
     // with zeros. Check for Javascript by seeing if an integer is double.
     var paddingDigits = new StringBuffer();
     if (1 is double && intValue > _maxInt) {
         var howManyDigitsTooBig = (log(intValue) / LN10).ceil() - 16;
         var divisor = pow(10, howManyDigitsTooBig).round();
         for (var each in new List(howManyDigitsTooBig.toInt())) {
           paddingDigits.write(symbols.ZERO_DIGIT);
         }
         intValue = (intValue / divisor).truncate();
     }
     var integerDigits = "${intValue}${paddingDigits}".codeUnits;
     var digitLength = integerDigits.length;
 
     if (_hasPrintableIntegerPart(intValue)) {
-      _pad(_minimumIntegerDigits - digitLength);
+      _pad(minimumIntegerDigits - digitLength);
       for (var i = 0; i < digitLength; i++) {
         _addDigit(integerDigits[i]);
         _group(digitLength, i);
       }
     } else if (!fractionPresent) {
       // If neither fraction nor integer part exists, just print zero.
       _addZero();
     }
 
     _decimalSeparator(fractionPresent);
     _formatFractionPart((fracValue + power).toString());
   }
 
   /**
    * Format the part after the decimal place in a fixed point number.
    */
   void _formatFractionPart(String fractionPart) {
     var fractionCodes = fractionPart.codeUnits;
     var fractionLength = fractionPart.length;
     while(fractionCodes[fractionLength - 1] == _zero &&
-           fractionLength > _minimumFractionDigits + 1) {
+           fractionLength > minimumFractionDigits + 1) {
       fractionLength--;
     }
     for (var i = 1; i < fractionLength; i++) {
       _addDigit(fractionCodes[i]);
     }
   }
 
   /** Print the decimal separator if appropriate. */
   void _decimalSeparator(bool fractionPresent) {
     if (_decimalSeparatorAlwaysShown || fractionPresent) {
       _add(symbols.DECIMAL_SEP);
     }
   }
 
   /**
    * Return true if we have a main integer part which is printable, either
    * because we have digits left of the decimal point, or because there are
    * a minimum number of printable digits greater than 1.
    */
   bool _hasPrintableIntegerPart(int intValue) {
-    return intValue > 0 || _minimumIntegerDigits > 0;
+    return intValue > 0 || minimumIntegerDigits > 0;
   }
 
   /**
    * Create a new empty buffer. See comment on [_buffer] variable for why
    * we have it as an instance variable rather than passing it on the stack.
    */
   void _newBuffer() { _buffer = new StringBuffer(); }
 
   /** A group of methods that provide support for writing digits and other
    * required characters into [_buffer] easily.
@@ skipping 243 matching lines @@
 
     // Do syntax checking on the digits.
     if (decimalPos < 0 && digitRightCount > 0 ||
         decimalPos >= 0 && (decimalPos < digitLeftCount ||
             decimalPos > digitLeftCount + zeroDigitCount) ||
             groupingCount == 0) {
       throw new FormatException('Malformed pattern "${pattern.input}"');
     }
     var totalDigits = digitLeftCount + zeroDigitCount + digitRightCount;
 
-    format._maximumFractionDigits =
+    format.maximumFractionDigits =
         decimalPos >= 0 ? totalDigits - decimalPos : 0;
     if (decimalPos >= 0) {
-      format._minimumFractionDigits =
+      format.minimumFractionDigits =
           digitLeftCount + zeroDigitCount - decimalPos;
-      if (format._minimumFractionDigits < 0) {
-        format._minimumFractionDigits = 0;
+      if (format.minimumFractionDigits < 0) {
+        format.minimumFractionDigits = 0;
       }
     }
 
     // The effectiveDecimalPos is the position the decimal is at or would be at
     // if there is no decimal. Note that if decimalPos<0, then digitTotalCount
     // == digitLeftCount + zeroDigitCount.
     var effectiveDecimalPos = decimalPos >= 0 ? decimalPos : totalDigits;
-    format._minimumIntegerDigits = effectiveDecimalPos - digitLeftCount;
+    format.minimumIntegerDigits = effectiveDecimalPos - digitLeftCount;
     if (format._useExponentialNotation) {
-      format._maximumIntegerDigits =
-          digitLeftCount + format._minimumIntegerDigits;
+      format.maximumIntegerDigits =
+          digitLeftCount + format.minimumIntegerDigits;
 
       // In exponential display, we need to at least show something.
-      if (format._maximumFractionDigits == 0 &&
-          format._minimumIntegerDigits == 0) {
-        format._minimumIntegerDigits = 1;
+      if (format.maximumFractionDigits == 0 &&
+          format.minimumIntegerDigits == 0) {
+        format.minimumIntegerDigits = 1;
       }
     }
 
     format._groupingSize = max(0, groupingCount);
     format._decimalSeparatorAlwaysShown = decimalPos == 0 ||
         decimalPos == totalDigits;
 
     return trunk.toString();
   }
 
@@ skipping 35 matching lines @@
         }
         decimalPos = digitLeftCount + zeroDigitCount + digitRightCount;
         break;
       case _PATTERN_EXPONENT:
         trunk.write(ch);
         if (format._useExponentialNotation) {
           throw new FormatException(
               'Multiple exponential symbols in pattern "$pattern"');
         }
         format._useExponentialNotation = true;
-        format._minimumExponentDigits = 0;
+        format.minimumExponentDigits = 0;
 
         // exponent pattern can have a optional '+'.
         pattern.moveNext();
         var nextChar = pattern.current;
         if (nextChar == _PATTERN_PLUS) {
           trunk.write(pattern.current);
           pattern.moveNext();
           format._useSignForPositiveExponent = true;
         }
 
         // Use lookahead to parse out the exponential part
         // of the pattern, then jump into phase 2.
         while (pattern.current == _PATTERN_ZERO_DIGIT) {
           trunk.write(pattern.current);
           pattern.moveNext();
-          format._minimumExponentDigits++;
+          format.minimumExponentDigits++;
         }
 
         if ((digitLeftCount + zeroDigitCount) < 1 ||
-            format._minimumExponentDigits < 1) {
+            format.minimumExponentDigits < 1) {
           throw new FormatException(
               'Malformed exponential pattern "$pattern"');
         }
         return false;
       default:
         return false;
     }
     trunk.write(ch);
     pattern.moveNext();
     return true;
@@ skipping 30 matching lines @@
   String input;
   var index = -1;
   inBounds(i) => i >= 0 && i < input.length;
   _StringIterator(this.input);
   String get current => inBounds(index) ? input[index] : null;
 
   bool moveNext() => inBounds(++index);
   String get peek => inBounds(index + 1) ? input[index + 1] : null;
   Iterator<String> get iterator => this;
 }