]> Cypherpunks repositories - gostls13.git/commitdiff
document hash
authorRob Pike <r@golang.org>
Sun, 8 Mar 2009 00:56:21 +0000 (16:56 -0800)
committerRob Pike <r@golang.org>
Sun, 8 Mar 2009 00:56:21 +0000 (16:56 -0800)
R=rsc
DELTA=50  (33 added, 4 deleted, 13 changed)
OCL=25878
CL=25887

src/lib/hash/adler32.go
src/lib/hash/crc32.go
src/lib/hash/md5.go
src/lib/hash/sha1.go

index 07818992eab87902d5a899eb886ad106f581a470..e8876eba3350bd77dadfcf53c81c54fd9e7d221b 100644 (file)
@@ -2,41 +2,44 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Adler-32 checksum.
+// This package implements the Adler-32 checksum.
 // Defined in RFC 1950:
 //     Adler-32 is composed of two sums accumulated per byte: s1 is
 //     the sum of all bytes, s2 is the sum of all s1 values. Both sums
 //     are done modulo 65521. s1 is initialized to 1, s2 to zero.  The
 //     Adler-32 checksum is stored as s2*65536 + s1 in most-
 //     significant-byte first (network) order.
-
 package adler32
 
 import "os"
 
+// Digest represents the partial evaluation of a checksum.
 type Digest struct {
        a, b uint32;
        n int;
 }
 
 const (
-       _Mod = 65521;
-       _MaxIter = 5552;  // max mod-free iterations before would overflow uint32
+       mod = 65521;
+       maxIter = 5552;  // max mod-free iterations before would overflow uint32
 )
 
+// NewDigest creates a new Digest.
 func NewDigest() *Digest {
        return &Digest{1, 0, 0};
 }
 
+// Write updates the Digest with the incremental checksum generated by p.
+// It returns the number of bytes written; err is always nil.
 func (d *Digest) Write(p []byte) (nn int, err *os.Error) {
        a, b, n := d.a, d.b, d.n;
        for i := 0; i < len(p); i++ {
                a += uint32(p[i]);
                b += a;
                n++;
-               if n == _MaxIter {
-                       a %= _Mod;
-                       b %= _Mod;
+               if n == maxIter {
+                       a %= mod;
+                       b %= mod;
                        n = 0;
                }
        }
@@ -44,15 +47,18 @@ func (d *Digest) Write(p []byte) (nn int, err *os.Error) {
        return len(p), nil
 }
 
+// Sum32 returns the 32-bit Adler-32 checksum of the data written to the Digest.
 func (d *Digest) Sum32() uint32 {
        a, b := d.a, d.b;
-       if a >= _Mod || b >= _Mod {
-               a %= _Mod;
-               b %= _Mod;
+       if a >= mod || b >= mod {
+               a %= mod;
+               b %= mod;
        }
        return b<<16 | a;
 }
 
+// Sum returns the 32-bit Adler-32 checksum of the data written to the Digest
+// in the form of an array of 4 bytes in big-endian order.
 func (d *Digest) Sum() []byte {
        p := make([]byte, 4);
        s := d.Sum32();
index 7bfca39d3fec95f4326a487c3975f7ea72fba79d..eb1dff3ba35faad52f5895f085fe2eaecd96d39b 100644 (file)
@@ -2,13 +2,13 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// CRC-32 checksum.
-// http://en.wikipedia.org/wiki/Cyclic_redundancy_check for links
-
+// This package implements the 32-bit cyclic redundancy check, or CRC-32, checksum.
+// See http://en.wikipedia.org/wiki/Cyclic_redundancy_check for information.
 package crc32
 
 import "os"
 
+// Predefined polynomials.
 const (
        // Far and away the most common CRC-32 polynomial.
        // Used by ethernet (IEEE 802.3), v.42, fddi, gzip, zip, png, mpeg-2, ...
@@ -25,9 +25,11 @@ const (
        Koopman = 0xeb31d82e;
 )
 
+// Table is a 256-word table representing the polynomial for efficient processing.
 // TODO(rsc): Change to [256]uint32 once 6g can handle it.
 type Table []uint32
 
+// MakeTable returns the Table constructed from the specified polynomial.
 func MakeTable(poly uint32) Table {
        t := make(Table, 256);
        for i := 0; i < 256; i++ {
@@ -44,21 +46,29 @@ func MakeTable(poly uint32) Table {
        return t;
 }
 
+// IEEETable is the table for the IEEE polynomial.
 var IEEETable = MakeTable(IEEE);
 
+// Digest represents the partial evaluation of a checksum.
 type Digest struct {
        crc uint32;
        tab Table;
 }
 
+// NewDigest creates a new Digest for the checksum based on
+// the polynomial represented by the Table.
 func NewDigest(tab Table) *Digest {
        return &Digest{0, tab};
 }
 
+// NewIEEEDigest creates a new Digest for the checksum based on
+// the IEEE polynomial.
 func NewIEEEDigest() *Digest {
        return NewDigest(IEEETable);
 }
 
+// Write updates the Digest with the incremental checksum generated by p.
+// It returns the number of bytes written; err is always nil.
 func (d *Digest) Write(p []byte) (n int, err *os.Error) {
        crc := d.crc ^ 0xFFFFFFFF;
        tab := d.tab;
@@ -69,10 +79,13 @@ func (d *Digest) Write(p []byte) (n int, err *os.Error) {
        return len(p), nil;
 }
 
+// Sum32 returns the CRC-32 checksum of the data written to the Digest.
 func (d *Digest) Sum32() uint32 {
        return d.crc
 }
 
+// Sum returns the CRC-32 checksum of the data written to the Digest
+// in the form of an array of 4 bytes in big-endian order.
 func (d *Digest) Sum() []byte {
        p := make([]byte, 4);
        s := d.Sum32();
index 98dae6f837942ef9791125d6f626737d956052c2..ab3201ffb8b562e897390b6279b5d7735bd3baf2 100644 (file)
@@ -2,8 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// MD5 hash algorithm.  See RFC 1321.
-
+// This package implements the MD5 hash algorithm as defined in RFC 1321.
 package md5
 
 import "os"
@@ -17,6 +16,7 @@ const (
        _Init3 = 0x10325476;
 )
 
+// Digest represents the partial evaluation of a checksum.
 type Digest struct {
        s [4]uint32;
        x [_Chunk]byte;
@@ -24,6 +24,7 @@ type Digest struct {
        len uint64;
 }
 
+// NewDigest creates a new Digest.
 func NewDigest() *Digest {
        d := new(Digest);
        d.s[0] = _Init0;
@@ -35,6 +36,8 @@ func NewDigest() *Digest {
 
 func _Block(dig *Digest, p []byte) int
 
+// Write updates the Digest with the incremental checksum generated by p.
+// It returns the number of bytes written; err is always nil.
 func (d *Digest) Write(p []byte) (nn int, err *os.Error) {
        nn = len(p);
        d.len += uint64(nn);
@@ -64,6 +67,8 @@ func (d *Digest) Write(p []byte) (nn int, err *os.Error) {
        return;
 }
 
+// Sum returns the MD5 checksum of the data written to the Digest
+// in the form of an array of 16 bytes in big-endian order.
 func (d *Digest) Sum() []byte {
        // Padding.  Add a 1 bit and 0 bits until 56 bytes mod 64.
        len := d.len;
index dab477cd48147fac2f25976ea04477cc27c5ffc0..0bf284ef1ac49f1ceb821f47a7e0d17da7d4644c 100644 (file)
@@ -2,8 +2,7 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// SHA1 hash algorithm.  See RFC 3174.
-
+// This package implements the SHA1 hash algorithm as defined in RFC 3174.
 package sha1
 
 import "os"
@@ -18,6 +17,7 @@ const (
        _Init4 = 0xC3D2E1F0;
 )
 
+// Digest represents the partial evaluation of a checksum.
 type Digest struct {
        h [5]uint32;
        x [_Chunk]byte;
@@ -25,6 +25,7 @@ type Digest struct {
        len uint64;
 }
 
+// NewDigest creates a new Digest.
 func NewDigest() *Digest {
        d := new(Digest);
        d.h[0] = _Init0;
@@ -37,6 +38,8 @@ func NewDigest() *Digest {
 
 func _Block(dig *Digest, p []byte) int
 
+// Write updates the Digest with the incremental checksum generated by p.
+// It returns the number of bytes written; err is always nil.
 func (d *Digest) Write(p []byte) (nn int, err *os.Error) {
        nn = len(p);
        d.len += uint64(nn);
@@ -66,6 +69,8 @@ func (d *Digest) Write(p []byte) (nn int, err *os.Error) {
        return;
 }
 
+// Sum returns the SHA-1 checksum of the data written to the Digest
+// in the form of an array of 20 bytes in big-endian order.
 func (d *Digest) Sum() []byte {
        // Padding.  Add a 1 bit and 0 bits until 56 bytes mod 64.
        len := d.len;