digest: update package methods to reflect changes

We made a change to call the _hex_ portion the _encoded_ portion and
this makes a few updates to make that clearer for prospective users of
this package.

Signed-off-by: Stephen J Day <stephen.day@docker.com>

algorithm.go

@@ -125,6 +125,14 @@ func (a Algorithm) Hash() hash.Hash {
 	return algorithms[a].New()
 }
 
+// Encode encodes the raw bytes of a digest, typically from a hash.Hash, into
+// the encoded portion of the digest.
+func (a Algorithm) Encode(d []byte) string {
+	// TODO(stevvooe): Currently, all algorithms use a hex encoding. When we
+	// add support for back registration, we can modify this accordingly.
+	return fmt.Sprintf("%x", d)
+}
+
 // FromReader returns the digest of the reader using the algorithm.
 func (a Algorithm) FromReader(rd io.Reader) (Digest, error) {
 	digester := a.Digester()

digest.go

@@ -45,12 +45,17 @@ func NewDigest(alg Algorithm, h hash.Hash) Digest {
 // functions. This is also useful for rebuilding digests from binary
 // serializations.
 func NewDigestFromBytes(alg Algorithm, p []byte) Digest {
-	return Digest(fmt.Sprintf("%s:%x", alg, p))
+	return NewDigestFromEncoded(alg, alg.Encode(p))
 }
 
-// NewDigestFromHex returns a Digest from alg and a the hex encoded digest.
+// NewDigestFromHex is deprecated. Please use NewDigestFromEncoded.
 func NewDigestFromHex(alg, hex string) Digest {
-	return Digest(fmt.Sprintf("%s:%s", alg, hex))
+	return NewDigestFromEncoded(Algorithm(alg), hex)
+}
+
+// NewDigestFromEncoded returns a Digest from alg and the encoded digest.
+func NewDigestFromEncoded(alg Algorithm, encoded string) Digest {
+	return Digest(fmt.Sprintf("%s:%s", alg, encoded))
 }
 
 // DigestRegexp matches valid digest types.
@@ -133,12 +138,17 @@ func (d Digest) Verifier() Verifier {
 	}
 }
 
-// Hex returns the hex digest portion of the digest. This will panic if the
+// Encoded returns the encoded portion of the digest. This will panic if the
 // underlying digest is not in a valid format.
-func (d Digest) Hex() string {
+func (d Digest) Encoded() string {
 	return string(d[d.sepIndex()+1:])
 }
 
+// Hex is deprecated. Please use Digest.Encoded.
+func (d Digest) Hex() string {
+	return d.Encoded()
+}
+
 func (d Digest) String() string {
 	return string(d)
 }

digest_test.go

@@ -23,17 +23,17 @@ func TestParseDigest(t *testing.T) {
 		input     string
 		err       error
 		algorithm Algorithm
-		hex       string
+		encoded   string
 	}{
 		{
 			input:     "sha256:e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b",
 			algorithm: "sha256",
-			hex:       "e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b",
+			encoded:   "e58fcf7418d4390dec8e8fb69d88c06ec07039d651fedd3aa72af9972e7d046b",
 		},
 		{
 			input:     "sha384:d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 			algorithm: "sha384",
-			hex:       "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
+			encoded:   "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 		},
 		{
 			// empty hex
@@ -78,13 +78,13 @@ func TestParseDigest(t *testing.T) {
 			// ensure that we parse, but we don't have support for the algorithm
 			input:     "sha384.foo+bar:d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 			algorithm: "sha384.foo+bar",
-			hex:       "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
+			encoded:   "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 			err:       ErrDigestUnsupported,
 		},
 		{
 			input:     "sha384_foo+bar:d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 			algorithm: "sha384_foo+bar",
-			hex:       "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
+			encoded:   "d3fc7881460b7e22e3d172954463dddd7866d17597e7248453c48b3e9d26d9596bf9c4a9cf8072c9d5bad76e19af801d",
 			err:       ErrDigestUnsupported,
 		},
 	} {
@@ -101,8 +101,8 @@ func TestParseDigest(t *testing.T) {
 			t.Fatalf("incorrect algorithm for parsed digest: %q != %q", digest.Algorithm(), testcase.algorithm)
 		}
 
-		if digest.Hex() != testcase.hex {
+		if digest.Encoded() != testcase.encoded {
-			t.Fatalf("incorrect hex for parsed digest: %q != %q", digest.Hex(), testcase.hex)
+			t.Fatalf("incorrect hex for parsed digest: %q != %q", digest.Encoded(), testcase.encoded)
 		}
 
 		// Parse string return value and check equality
@@ -116,7 +116,7 @@ func TestParseDigest(t *testing.T) {
 			t.Fatalf("expected equal: %q != %q", newParsed, digest)
 		}
 
-		newFromHex := NewDigestFromHex(newParsed.Algorithm().String(), newParsed.Hex())
+		newFromHex := NewDigestFromEncoded(newParsed.Algorithm(), newParsed.Encoded())
 		if newFromHex != digest {
 			t.Fatalf("%v != %v", newFromHex, digest)
 		}