Add a hexadecimal codec.

lib/src/hex/encoder.dart

+// 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.
+
+library convert.hex.encoder;
+
+import 'dart:convert';
+
+import 'package:charcode/ascii.dart';
+
+/// The canonical instance of [HexEncoder].
+const hexEncoder = const HexEncoder._();
+
+/// A converter that encodes byte arrays into hexadecimal strings.
+///
+/// This will throw a [RangeError] if the byte array has any digits that don't
+/// fit in the gamut of a byte.
+class HexEncoder extends Converter<List<int>, String> {
+  const HexEncoder._();
+
+  String convert(List<int> bytes) {
+    var buffer = new StringBuffer();

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

Use an Uint8List instead of a StringBuffer. StringBuffer isn't as efficient as
you would want when you know that you are only dealing with code units.

Maybe:

   var buffer = new Uint8List(bytes.length * 2);
   var index = 0;
   var byteBits = 0;  // bitwise or of all bytes in `bytes`.
   for (var byte in bytes) {
     byteBits |= byte;
     buffer[index++] = _codeUnitForDigit(byte ~/ 16);
     buffer[index++] = _codeUnitForDigit(byte % 16);
  }
  if (byteBits >= 0 && byteBits <= 255) {
    return new String.fromCharCodes(buffer);
  }
  // there is an invalid byte in bytes, find it and report the error.
  // This moves the range-check branch outside of the inner loop.
  for (int i = 0; i < bytes.length; i++) {
    var byte = bytes[i];
    if (byte != byte.toUnsigned(8)) {
      throw new FormatException("Not a byte value (0..255)", input, i);
    }
  }

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

Done.

+    for (var byte in bytes) {
+      RangeError.checkValueInInterval(byte, 0, 255);
+      buffer.writeCharCode(_codeUnitForDigit(byte ~/ 16));
+      buffer.writeCharCode(_codeUnitForDigit(byte % 16));
+    }
+    return buffer.toString();
+  }
+
+  /// Returns the ASCII/Unicode code unit corresponding to the hexadecimal digit
+  /// [digit].
+  int _codeUnitForDigit(int digit) => digit < 10 ? digit + $0 : digit + $a - 10;

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

Maybe just use "0123456789abcdef".codeUnitAt(digit);
It's only used in two places, so you can even inline it (and maybe make the
string a named constant _hexDigits).

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

Will a memory read really be better than simple arithmetic?
I think it's nice to leave it as a named function. It parallels
_digitForCodeUnit in the decoder, and it makes it easy to read and swap out the
implementation (like we might do in this code review).

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

It's not simple arithmetic - there is an unpredictable branch in it.
It's only one branch, so I *guess* it'll be around the same time as a memory
fetch from a small constant piece of memory.

However, if the compiler can't determine that the argument is always in range of
the string, the string lookup will add a range check too.
I'd probably write it as: "0123456789ABCDEF".codeUnitAt(digit & 0xF) to help
with that.

And then benchmark! It's the only way to be sure.
It's probably fine as-is.

[nweiz, 2015/09/24 23:23:42]

I'm going to leave this as-is for now. We can come back and do benchmark-driven
changes if it becomes necessary in the future.

+
+  ByteConversionSink startChunkedConversion(Sink<String> sink) =>
+      new _HexEncoderSink(sink);
+}
+
+/// A sink for chunked hexadecimal encoding.
+class _HexEncoderSink extends ByteConversionSinkBase {
+  /// The underlying sink to which decoded byte arrays will be passed.
+  final Sink<String> _sink;
+
+  _HexEncoderSink(this._sink);
+
+  void add(List<int> chunk) {
+    _sink.add(hexEncoder.convert(chunk));
+  }

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

Consider implementing the addSlice function (and have a _convert(List<int>
bytes, int start, int end) helper function that the public `convert` method uses
as well.

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

Done.

+
+  void close() {
+    _sink.close();
+  }
+}