Replace old utf8 decoder with new one.

sdk/lib/codec/encoding.dart

Index: sdk/lib/codec/encoding.dart
diff --git a/sdk/lib/codec/encoding.dart b/sdk/lib/codec/encoding.dart
index 50b724be6d398d50ead3e91740080f43c604f47c..ae71af8ab476426de8efb1dc5d6f3e563acf2156 100644
--- a/sdk/lib/codec/encoding.dart
+++ b/sdk/lib/codec/encoding.dart
@@ -20,11 +20,41 @@ 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);
+  }
 }