Add a hexadecimal codec.

test/hex_test.dart

Index: test/hex_test.dart
diff --git a/test/hex_test.dart b/test/hex_test.dart
new file mode 100644
index 0000000000000000000000000000000000000000..b25dc8b9d2548af20a257d22a00669d5191dae48
--- /dev/null
+++ b/test/hex_test.dart
@@ -0,0 +1,108 @@
+// Copyright (c) 2015, 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.
+
+import 'dart:async';
+
+import 'package:convert/convert.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group("encoder", () {
+    test("converts byte arrays to hex", () {
+      expect(hex.encode([0x1a, 0xb2, 0x3c, 0xd4]), equals("1ab23cd4"));
+      expect(hex.encode([0x00, 0x01, 0xfe, 0xff]), equals("0001feff"));
+    });
+
+    test("does chunked conversion", () {
+      var results = [];
+      var controller = new StreamController(sync: true);
+      controller.stream.listen(results.add);
+      var sink = hex.encoder.startChunkedConversion(controller.sink);
+
+      sink.add([0x1a, 0xb2, 0x3c, 0xd4]);
+      expect(results, equals(["1ab23cd4"]));

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

Don't expect that the input is immediately output.

Another implementation would be to have a buffer in the converter, and
accumulate bytes until the buffer is full or the sink is closed. That would
break this test even if it's a perfectly valid implementation.

Only test the final result after calling close.

[nweiz, 2015/09/23 22:04:21]

That would be a valid implementation, but these aren't intended to be wholly
black-box tests. Even if it's not a guaranteed part of the external API, the
intended behavior of the current implementation is to pass through data as it
comes, and that can have performance implications. I'd rather have to
re-implement the test if the behavior changes than not test this behavior.

+
+      sink.add([0x00, 0x01, 0xfe, 0xff]);
+      expect(results, equals(["1ab23cd4", "0001feff"]));

[Lasse Reichstein Nielsen, 2015/09/23 08:32:05]

Test adding an empty list and a single-element list (possible edge cases).

Maybe even test the empty list first, between non-empty ones and last.

[nweiz, 2015/09/23 22:04:21]

Done.

+    });
+
+    test("rejects non-bytes", () {
+      expect(() => hex.encode([0x100]), throwsRangeError);
+
+      var sink = hex.encoder.startChunkedConversion(
+          new StreamController(sync: true));
+      expect(() => sink.add([0x100]), throwsRangeError);
+    });
+  });
+
+  group("decoder", () {
+    test("converts hex to byte arrays", () {
+      expect(hex.decode("1ab23cd4"), equals([0x1a, 0xb2, 0x3c, 0xd4]));
+      expect(hex.decode("0001feff"), equals([0x00, 0x01, 0xfe, 0xff]));
+    });
+
+    test("supports uppercase letters", () {
+      expect(hex.decode("1Ab23cD4"), equals([0x1a, 0xb2, 0x3c, 0xd4]));

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

Check all of them. No reason not to: "0123456789ABCDEFabcdef"

[nweiz, 2015/09/23 22:04:21]

Done.

+    });
+
+    group("with chunked conversion", () {
+      var results;
+      var sink;
+      setUp(() {
+        results = [];
+        var controller = new StreamController(sync: true);

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

Hmmm. Not really a proper use of a sync stream controller, but I can see that
it's an easy way to get a Sink.

+        controller.stream.listen(results.add);
+        sink = hex.decoder.startChunkedConversion(controller.sink);
+      });
+

[Lasse Reichstein Nielsen, 2015/09/23 08:32:05]

Again, don't compare intermediate results, only check the final result after
calling close, and don't expect a particular split for the output lists
(basically, flatten the list of result lists before comparing to it).

+      test("converts hex to byte arrays", () {
+        sink.add("1ab23cd4");
+        expect(results, equals([[0x1a, 0xb2, 0x3c, 0xd4]]));
+
+        sink.add("0001feff");
+        expect(results, equals([[0x1a, 0xb2, 0x3c, 0xd4], [0x00, 0x01, 0xfe, 0xff]]));

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

long line.

[nweiz, 2015/09/23 22:04:21]

Done.

+      });
+
+      test("supports trailing digits split across chunks", () {
+        sink.add("1ab23");
+        expect(results, equals([[0x1a, 0xb2]]));
+
+        sink.add("cd");
+        expect(results, equals([[0x1a, 0xb2], [0x3c]]));
+
+        sink.add("40001");
+        expect(results, equals([[0x1a, 0xb2], [0x3c], [0xd4, 0x00, 0x01]]));
+
+        sink.add("feff");
+        expect(results,
+            equals([[0x1a, 0xb2], [0x3c], [0xd4, 0x00, 0x01], [0xfe, 0xff]]));
+      });

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

Also check empty lists.

In similar cases I have made a parameterized test that tried all possible splits
of a list into 1-4 parts, and checks that the final result is the same in either
case. That also tests empty lists.

[nweiz, 2015/09/23 22:04:21]

Done.
I generally prefer to have a few explicit tests that we believe will cover all
relevant cases.

+
+      test("rejects odd characters detected in close()", () {

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

odd characters -> odd length
Ditto below.

[nweiz, 2015/09/23 22:04:21]

Done.

+        sink.add("1ab23");
+        expect(results, equals([[0x1a, 0xb2]]));
+        expect(() => sink.close(), throwsFormatException);
+      });
+
+      test("rejects odd characters detected in addSlice()", () {
+        sink.addSlice("1ab23cd", 0, 5, false);
+        expect(results, equals([[0x1a, 0xb2]]));
+
+        expect(() => sink.addSlice("1ab23cd", 5, 7, true), throwsFormatException);

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

Long line.

[nweiz, 2015/09/23 22:04:21]

Done.

+      });
+    });
+
+    test("rejects non-hex characters", () {
+      expect(() => hex.decode("az"), throwsFormatException);

[Lasse Reichstein Nielsen, 2015/09/23 08:32:04]

Also check the characters:
  "/"
  ":"
  "@"
  "["
  "`"
  "{"
  "\x00"
  "\u0141"
  "\u{10041}"
(characters right next to 0/9, A/Z, a/z, plus NUL and values that become valid
if masked incorrectly).

[nweiz, 2015/09/23 22:04:21]

Done, although I replaced "{" and "[" with "g" and "G" since those are the
limits of valid hex.

[Lasse Reichstein Nielsen, 2015/09/24 08:07:01]

Does it show that I'm working on BASE64 :)

+
+      var sink = hex.decoder.startChunkedConversion(
+          new StreamController(sync: true));
+      expect(() => sink.add("az"), throwsFormatException);
+    });
+
+    test("rejects odd characters detected in convert()", () {
+      expect(() => hex.decode("1ab23cd"), throwsFormatException);
+    });
+  });
+}