github.com/klaytn/klaytn@v1.12.1/common/bitutil/doc.go (about)

     1  // Copyright 2018 The klaytn Authors
     2  // Copyright 2013 The Go Authors. All rights reserved.
     3  // Use of this source code is governed by a BSD-style
     4  // license that can be found in the LICENSE file.
     5  //
     6  // Adapted from: https://golang.org/src/crypto/cipher/xor.go
     7  //
     8  // This file is derived from common/bitutil/bitutil.go (2018/06/04).
     9  // Modified and improved for the klaytn development.
    10  //
    11  // TODO-Klaytn: put the original LICENSE file in the common/bitutil directory
    12  
    13  /*
    14  Package bitutil implements fast bitwise operations and compression/decompressions.
    15  
    16  Bitwise Operations
    17  
    18  Following operations are supported
    19    - AND, OR, XOR operations
    20    - Provides both safe version and fast version of above operations
    21      `Safe` means it can be performed on all architectures
    22      `Fast` means it only can be performed on architecture which supports unaligned read/write
    23  
    24  Compression and Decompression
    25  
    26  Following operations are supported
    27    - CompressBytes
    28    - DecompressBytes
    29  
    30  How compression works
    31  
    32  The compression algorithm implemented by CompressBytes and DecompressBytes is
    33  optimized for sparse input data which contains a lot of zero bytes. Decompression
    34  requires knowledge of the decompressed data length.
    35  
    36  	Compression works as follows:
    37  
    38  	  if data only contains zeroes,
    39  		  CompressBytes(data) == nil
    40  	  otherwise if len(data) <= 1,
    41  		  CompressBytes(data) == data
    42  	  otherwise:
    43  		  CompressBytes(data) == append(CompressBytes(nonZeroBitset(data)), nonZeroBytes(data)...)
    44  		  where
    45  			nonZeroBitset(data) is a bit vector with len(data) bits (MSB first):
    46  				nonZeroBitset(data)[i/8] && (1 << (7-i%8)) != 0  if data[i] != 0
    47  				len(nonZeroBitset(data)) == (len(data)+7)/8
    48  			nonZeroBytes(data) contains the non-zero bytes of data in the same order
    49  */
    50  package bitutil