Replace old utf8 decoder with new one.

sdk/lib/codec/encoding.dart

 // Copyright (c) 2013, 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.codec;
 
 /**
  * Open-ended Encoding enum.
  */
 // TODO(floitsch): dart:io already has an Encoding class. If we can't
 // consolitate them, we need to remove `Encoding` here.
 abstract class Encoding extends Codec<String, List<int>> {
   const Encoding();
 }
 
 // TODO(floitsch): add other encodings, like ASCII and ISO_8859_1.
 const UTF8 = const Utf8Codec();
 
 /**
  * A [Utf8Codec] encodes strings to utf-8 code units (bytes) and decodes
  * UTF-8 code units to strings.
  */
-// TODO(floitsch): Needs a way to specify if decoding should throw or use
-// the replacement character.
 class Utf8Codec extends Encoding {
-  const Utf8Codec();
+  final bool _allowMalformed;
+
+  /**
+   * Instantiates a new [Utf8Codec].
+   *
+   * The optional [allowMalformed] argument defines how [decode] and [decoder]
+   * deal with invalid or unterminated character sequences.
+   *
+   * If it is `true` (and not overriden at the method invocation) [decode] and
+   * the [decoder] replace invalid (or unterminated) character

[Lasse Reichstein Nielsen, 2013/07/16 12:23:03]

character sequences -> octet sequences

Actually, you can't generalize between the encoder and the decoder.
The encoder cannot fail since it takes a String as input, which always contains
"UTF-16 + unpaired surrogates". 
Is an unpaired surrogate an error for the encoder? (I see below that the encoder
doesn't use 'allowMalformed' at all, so just don't mention it here).

The decoder can see invalid octet sequences, and it can see non-canonical
encodings. I assume both are errors, and will either be replaced or throw.

What about the sequence [0x80, 0x80, 0x80]. Is that one error or three?

[floitsch, 2013/07/16 14:25:24]

As discussed: the sentence before says that it only applies to the decode part.

Will add tests for 0x80.

+   * sequences with the Unicode Replacement character `0xFFFD` (�). Otherwise

[Lasse Reichstein Nielsen, 2013/07/16 12:23:03]

'0xFFFD' -> U+FFFD

[floitsch, 2013/07/16 14:25:24]

Done.

+   * they throw a [FormatException].
+   */
+  const Utf8Codec({ bool allowMalformed: false })
+      : _allowMalformed = allowMalformed;
+
+  /**
+   * Decodes the UTF-8 [codeUnits] (a list of unsigned 8-bit integers) to the
+   * corresponding string.
+   *
+   * If [allowMalformed] is `true` replaces invalid (or unterminated) character

[Lasse Reichstein Nielsen, 2013/07/16 12:23:03]

... is `true`, the decoder replaces ...

[floitsch, 2013/07/16 14:25:24]

Done.

+   * sequences with the Unicode Replacement character `0xFFFD` (�). Otherwise

[Lasse Reichstein Nielsen, 2013/07/16 12:23:03]

U+FFFD

[floitsch, 2013/07/16 14:25:24]

Done.

+   * throws a [FormatException].

[Lasse Reichstein Nielsen, 2013/07/16 12:23:03]

Otherwise it throws ...

[floitsch, 2013/07/16 14:25:24]

Done.

+   *
+   * If [allowMalformed] is not given, defaults to the `allowMalformed` that

[Lasse Reichstein Nielsen, 2013/07/16 12:23:03]

'it' after comma.

[floitsch, 2013/07/16 14:25:24]

Done.

+   * was used to instantiate `this`.
+   */
+  String decode(List<int> codeUnits, { bool allowMalformed }) {
+    if (allowMalformed == null) allowMalformed = _allowMalformed;
+    return new Utf8Decoder(allowMalformed: allowMalformed).convert(codeUnits);
+  }
 
   Converter<String, List<int>> get encoder => new Utf8Encoder();
-  Converter<List<int>, String> get decoder => new Utf8Decoder();
+  Converter<List<int>, String> get decoder {
+    return new Utf8Decoder(allowMalformed: _allowMalformed);
+  }
 }