Update charted to 0.4.8 and roll

packages/intl/lib/src/intl/bidi_formatter.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;
 
-/**
- * Bidi stands for Bi-directional text.
- * According to [Wikipedia](http://en.wikipedia.org/wiki/Bi-directional_text):
- * Bi-directional text is text containing text in both text directionalities,
- * both right-to-left (RTL) and left-to-right (LTR). It generally involves text
- * containing different types of alphabets, but may also refer to boustrophedon,
- * which is changing text directionality in each row.
- *
- * Utility class for formatting display text in a potentially
- * opposite-directionality context without garbling layout issues.
- * Mostly a very "slimmed-down" and dart-ified port of the Closure Birectional
- * formatting libary. If there is a utility in the Closure library (or ICU, or
- * elsewhere) that you would like this formatter to make available, please
- * contact the Dart team.
- *
- * Provides the following functionality:
- *
- * 1. *BiDi Wrapping*
- * When text in one language is mixed into a document in another, opposite-
- * directionality language, e.g. when an English business name is embedded in a
- * Hebrew web page, both the inserted string and the text following it may be
- * displayed incorrectly unless the inserted string is explicitly separated
- * from the surrounding text in a "wrapper" that declares its directionality at
- * the start and then resets it back at the end. This wrapping can be done in
- * HTML mark-up (e.g. a 'span dir=rtl' tag) or - only in contexts where mark-up
- * can not be used - in Unicode BiDi formatting codes (LRE|RLE and PDF).
- * Providing such wrapping services is the basic purpose of the BiDi formatter.
- *
- * 2. *Directionality estimation*
- * How does one know whether a string about to be inserted into surrounding
- * text has the same directionality? Well, in many cases, one knows that this
- * must be the case when writing the code doing the insertion, e.g. when a
- * localized message is inserted into a localized page. In such cases there is
- * no need to involve the BiDi formatter at all. In the remaining cases, e.g.
- * when the string is user-entered or comes from a database, the language of
- * the string (and thus its directionality) is not known a priori, and must be
- * estimated at run-time. The BiDi formatter does this automatically.
- *
- * 3. *Escaping*
- * When wrapping plain text - i.e. text that is not already HTML or HTML-
- * escaped - in HTML mark-up, the text must first be HTML-escaped to prevent XSS
- * attacks and other nasty business. This of course is always true, but the
- * escaping cannot be done after the string has already been wrapped in
- * mark-up, so the BiDi formatter also serves as a last chance and includes
- * escaping services.
- *
- * Thus, in a single call, the formatter will escape the input string as
- * specified, determine its directionality, and wrap it as necessary. It is
- * then up to the caller to insert the return value in the output.
- */
+/// Bidi stands for Bi-directional text.  According to
+/// [Wikipedia](http://en.wikipedia.org/wiki/Bi-directional_text):
+/// Bi-directional text is text containing text in both text directionalities,
+/// both right-to-left (RTL) and left-to-right (LTR). It generally involves text
+/// containing different types of alphabets, but may also refer to
+/// boustrophedon, which is changing text directionality in each row.
+///
+/// Utility class for formatting display text in a potentially
+/// opposite-directionality context without garbling layout issues.  Mostly a
+/// very "slimmed-down" and dart-ified port of the Closure Birectional
+/// formatting libary. If there is a utility in the Closure library (or ICU, or
+/// elsewhere) that you would like this formatter to make available, please
+/// contact the Dart team.
+///
+/// Provides the following functionality:
+///
+/// 1. *BiDi Wrapping*
+/// When text in one language is mixed into a document in another, opposite-
+/// directionality language, e.g. when an English business name is embedded in a
+/// Hebrew web page, both the inserted string and the text following it may be
+/// displayed incorrectly unless the inserted string is explicitly separated
+/// from the surrounding text in a "wrapper" that declares its directionality at
+/// the start and then resets it back at the end. This wrapping can be done in
+/// HTML mark-up (e.g. a 'span dir=rtl' tag) or - only in contexts where mark-up
+/// can not be used - in Unicode BiDi formatting codes (LRE|RLE and PDF).
+/// Providing such wrapping services is the basic purpose of the BiDi formatter.
+///
+/// 2. *Directionality estimation*
+/// How does one know whether a string about to be inserted into surrounding
+/// text has the same directionality? Well, in many cases, one knows that this
+/// must be the case when writing the code doing the insertion, e.g. when a
+/// localized message is inserted into a localized page. In such cases there is
+/// no need to involve the BiDi formatter at all. In the remaining cases, e.g.
+/// when the string is user-entered or comes from a database, the language of
+/// the string (and thus its directionality) is not known a priori, and must be
+/// estimated at run-time. The BiDi formatter does this automatically.
+///
+/// 3. *Escaping*
+/// When wrapping plain text - i.e. text that is not already HTML or HTML-
+/// escaped - in HTML mark-up, the text must first be HTML-escaped to prevent
+/// XSS attacks and other nasty business. This of course is always true, but the
+/// escaping cannot be done after the string has already been wrapped in
+/// mark-up, so the BiDi formatter also serves as a last chance and includes
+/// escaping services.
+///
+/// Thus, in a single call, the formatter will escape the input string as
+/// specified, determine its directionality, and wrap it as necessary. It is
+/// then up to the caller to insert the return value in the output.
 
 class BidiFormatter {
 
-  /** The direction of the surrounding text (the context). */
+  /// The direction of the surrounding text (the context).
   TextDirection contextDirection;
 
-  /**
-   * Indicates if we should always wrap the formatted text in a <span<,.
-   */
+  /// Indicates if we should always wrap the formatted text in a <span<,.
   bool _alwaysSpan;
 
-  /**
-   * Create a formatting object with a direction. If [alwaysSpan] is true we
-   * should always use a `span` tag, even when the input directionality is
-   * neutral or matches the context, so that the DOM structure of the output
-   * does not depend on the combination of directionalities.
-   */
+  /// Create a formatting object with a direction. If [alwaysSpan] is true we
+  /// should always use a `span` tag, even when the input directionality is
+  /// neutral or matches the context, so that the DOM structure of the output
+  /// does not depend on the combination of directionalities.
   BidiFormatter.LTR([alwaysSpan = false])
       : contextDirection = TextDirection.LTR,
         _alwaysSpan = alwaysSpan;
   BidiFormatter.RTL([alwaysSpan = false])
       : contextDirection = TextDirection.RTL,
         _alwaysSpan = alwaysSpan;
   BidiFormatter.UNKNOWN([alwaysSpan = false])
       : contextDirection = TextDirection.UNKNOWN,
         _alwaysSpan = alwaysSpan;
 
-  /** Is true if the known context direction for this formatter is RTL. */
+  /// Is true if the known context direction for this formatter is RTL.
   bool get isRTL => contextDirection == TextDirection.RTL;
 
-  /**
-   * Formats a string of a given (or estimated, if not provided)
-   * [direction] for use in HTML output of the context directionality, so
-   * an opposite-directionality string is neither garbled nor garbles what
-   * follows it.
-   * If the input string's directionality doesn't match the context
-   * directionality, we wrap it with a `span` tag and add a `dir` attribute
-   * (either "dir=rtl" or "dir=ltr").
-   * If alwaysSpan was true when constructing the formatter, the input is always
-   * wrapped with `span` tag, skipping the dir attribute when it's not needed.
-   *
-   * If [resetDir] is true and the overall directionality or the exit
-   * directionality of [text] is opposite to the context directionality,
-   * a trailing unicode BiDi mark matching the context directionality is
-   * appended (LRM or RLM). If [isHtml] is false, we HTML-escape the [text].
-   */
+  /// Formats a string of a given (or estimated, if not provided) [direction]
+  /// for use in HTML output of the context directionality, so an
+  /// opposite-directionality string is neither garbled nor garbles what follows
+  /// it.
+  ///
+  ///If the input string's directionality doesn't match the context
+  /// directionality, we wrap it with a `span` tag and add a `dir` attribute
+  /// (either "dir=rtl" or "dir=ltr").  If alwaysSpan was true when constructing
+  /// the formatter, the input is always wrapped with `span` tag, skipping the
+  /// dir attribute when it's not needed.
+  ///
+  /// If [resetDir] is true and the overall directionality or the exit
+  /// directionality of [text] is opposite to the context directionality,
+  /// a trailing unicode BiDi mark matching the context directionality is
+  /// appended (LRM or RLM). If [isHtml] is false, we HTML-escape the [text].
   String wrapWithSpan(String text,
       {bool isHtml: false, bool resetDir: true, TextDirection direction}) {
     if (direction == null) direction = estimateDirection(text, isHtml: isHtml);
     var result;
     if (!isHtml) text = HTML_ESCAPE.convert(text);
     var directionChange = contextDirection.isDirectionChange(direction);
     if (_alwaysSpan || directionChange) {
       var spanDirection = '';
       if (directionChange) {
         spanDirection = ' dir=${direction.spanText}';
       }
       result = '<span$spanDirection>$text</span>';
     } else {
       result = text;
     }
     return result + (resetDir ? _resetDir(text, direction, isHtml) : '');
   }
 
-  /**
-   * Format [text] of a known (if specified) or estimated [direction] for use
-   * in *plain-text* output of the context directionality, so an
-   * opposite-directionality text is neither garbled nor garbles what follows
-   * it. Unlike wrapWithSpan, this makes use of unicode BiDi formatting
-   * characters instead of spans for wrapping. The returned string would be
-   * RLE+text+PDF for RTL text, or LRE+text+PDF for LTR text.
-   *
-   * If [resetDir] is true, and if the overall directionality or the exit
-   * directionality of text are opposite to the context directionality,
-   * a trailing unicode BiDi mark matching the context directionality is
-   * appended (LRM or RLM).
-   *
-   * In HTML, the *only* valid use of this function is inside of elements that
-   * do not allow markup, e.g. an 'option' tag.
-   * This function does *not* do HTML-escaping regardless of the value of
-   * [isHtml]. [isHtml] is used to designate if the text contains HTML (escaped
-   * or unescaped).
-   */
+  /// Format [text] of a known (if specified) or estimated [direction] for use
+  /// in *plain-text* output of the context directionality, so an
+  /// opposite-directionality text is neither garbled nor garbles what follows
+  /// it. Unlike wrapWithSpan, this makes use of unicode BiDi formatting
+  /// characters instead of spans for wrapping. The returned string would be
+  /// RLE+text+PDF for RTL text, or LRE+text+PDF for LTR text.
+  ///
+  /// If [resetDir] is true, and if the overall directionality or the exit
+  /// directionality of text are opposite to the context directionality,
+  /// a trailing unicode BiDi mark matching the context directionality is
+  /// appended (LRM or RLM).
+  ///
+  /// In HTML, the *only* valid use of this function is inside of elements that
+  /// do not allow markup, e.g. an 'option' tag.
+  /// This function does *not* do HTML-escaping regardless of the value of
+  /// [isHtml]. [isHtml] is used to designate if the text contains HTML (escaped
+  /// or unescaped).
   String wrapWithUnicode(String text,
       {bool isHtml: false, bool resetDir: true, TextDirection direction}) {
     if (direction == null) direction = estimateDirection(text, isHtml: isHtml);
     var result = text;
     if (contextDirection.isDirectionChange(direction)) {
       var marker = direction == TextDirection.RTL ? Bidi.RLE : Bidi.LRE;
       result = "${marker}$text${Bidi.PDF}";
     }
     return result + (resetDir ? _resetDir(text, direction, isHtml) : '');
   }
 
-  /**
-   * Estimates the directionality of [text] using the best known
-   * general-purpose method (using relative word counts). A
-   * TextDirection.UNKNOWN return value indicates completely neutral input.
-   * [isHtml] is true if [text] HTML or HTML-escaped.
-   */
+  /// Estimates the directionality of [text] using the best known
+  /// general-purpose method (using relative word counts). A
+  /// TextDirection.UNKNOWN return value indicates completely neutral input.
+  /// [isHtml] is true if [text] HTML or HTML-escaped.
   TextDirection estimateDirection(String text, {bool isHtml: false}) {
     return Bidi.estimateDirectionOfText(text, isHtml: isHtml); //TODO~!!!
   }
 
-  /**
-   * Returns a unicode BiDi mark matching the surrounding context's [direction]
-   * (not necessarily the direction of [text]). The function returns an LRM or
-   * RLM if the overall directionality or the exit directionality of [text] is
-   * opposite the context directionality. Otherwise
-   * return the empty string. [isHtml] is true if [text] is HTML or
-   * HTML-escaped.
-   */
+  /// Returns a unicode BiDi mark matching the surrounding context's [direction]
+  /// (not necessarily the direction of [text]). The function returns an LRM or
+  /// RLM if the overall directionality or the exit directionality of [text] is
+  /// opposite the context directionality. Otherwise
+  /// return the empty string. [isHtml] is true if [text] is HTML or
+  /// HTML-escaped.
   String _resetDir(String text, TextDirection direction, bool isHtml) {
     // endsWithRtl and endsWithLtr are called only if needed (short-circuit).
     if ((contextDirection == TextDirection.LTR &&
             (direction == TextDirection.RTL ||
                 Bidi.endsWithRtl(text, isHtml))) ||
         (contextDirection == TextDirection.RTL &&
             (direction == TextDirection.LTR ||
                 Bidi.endsWithLtr(text, isHtml)))) {
       return contextDirection == TextDirection.LTR ? Bidi.LRM : Bidi.RLM;
     } else {
       return '';
     }
   }
 }