crc/internal/crc.h

0001 // Copyright 2022 The Abseil Authors.
0002 //
0003 // Licensed under the Apache License, Version 2.0 (the "License");
0004 // you may not use this file except in compliance with the License.
0005 // You may obtain a copy of the License at
0006 //
0007 //      https://www.apache.org/licenses/LICENSE-2.0
0008 //
0009 // Unless required by applicable law or agreed to in writing, software
0010 // distributed under the License is distributed on an "AS IS" BASIS,
0011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0012 // See the License for the specific language governing permissions and
0013 // limitations under the License.
0014
0015 #ifndef ABSL_CRC_INTERNAL_CRC_H_
0016 #define ABSL_CRC_INTERNAL_CRC_H_
0017
0018 #include <cstdint>
0019
0020 #include "absl/base/config.h"
0021
0022 // This class implements CRCs (aka Rabin Fingerprints).
0023 // Treats the input as a polynomial with coefficients in Z(2),
0024 // and finds the remainder when divided by an primitive polynomial
0025 // of the appropriate length.
0026
0027 // A polynomial is represented by the bit pattern formed by its coefficients,
0028 // but with the highest order bit not stored.
0029 // The highest degree coefficient is stored in the lowest numbered bit
0030 // in the lowest addressed byte.   Thus, in what follows, the highest degree
0031 // coefficient that is stored is in the low order bit of "lo" or "*lo".
0032
0033 // Hardware acceleration is used when available.
0034
0035 namespace absl {
0036 ABSL_NAMESPACE_BEGIN
0037 namespace crc_internal {
0038
0039 class CRC {
0040  public:
0041   virtual ~CRC();
0042
0043   // If "*crc" is the CRC of bytestring A, place the CRC of
0044   // the bytestring formed from the concatenation of A and the "length"
0045   // bytes at "bytes" into "*crc".
0046   virtual void Extend(uint32_t* crc, const void* bytes,
0047                       size_t length) const = 0;
0048
0049   // Equivalent to Extend(crc, bytes, length) where "bytes"
0050   // points to an array of "length" zero bytes.
0051   virtual void ExtendByZeroes(uint32_t* crc, size_t length) const = 0;
0052
0053   // Inverse operation of ExtendByZeroes.  If `crc` is the CRC value of a string
0054   // ending in `length` zero bytes, this returns a CRC value of that string
0055   // with those zero bytes removed.
0056   virtual void UnextendByZeroes(uint32_t* crc, size_t length) const = 0;
0057
0058   // Apply a non-linear transformation to "*crc" so that
0059   // it is safe to CRC the result with the same polynomial without
0060   // any reduction of error-detection ability in the outer CRC.
0061   // Unscramble() performs the inverse transformation.
0062   // It is strongly recommended that CRCs be scrambled before storage or
0063   // transmission, and unscrambled at the other end before further manipulation.
0064   virtual void Scramble(uint32_t* crc) const = 0;
0065   virtual void Unscramble(uint32_t* crc) const = 0;
0066
0067   // Crc32c() returns the singleton implementation of CRC for the CRC32C
0068   // polynomial.  Returns a handle that MUST NOT be destroyed with delete.
0069   static CRC* Crc32c();
0070
0071  protected:
0072   CRC();  // Clients may not call constructor; use Crc32c() instead.
0073
0074  private:
0075   CRC(const CRC&) = delete;
0076   CRC& operator=(const CRC&) = delete;
0077 };
0078
0079 }  // namespace crc_internal
0080 ABSL_NAMESPACE_END
0081 }  // namespace absl
0082
0083 #endif  // ABSL_CRC_INTERNAL_CRC_H_