ACE/ace/Compression/rle/RLECompressor.h

   1 // -*- C++ -*-
   2 //=============================================================================
   3 /**
   4  *  @file   RLECompressor.h
   5  *
   6  *  @author TAO version by
   7  *  @author Derek Dominish <derek.dominish@dsto.defence.gov.au>
   8  *  @author ACE version by
   9  *  @author Derek Dominish <derek.dominish@dsto.defence.gov.au>
  10  *
  11  *  Run-length encoding (RLE) is a very simple form of data compression
  12  *  in which runs of data (that is, sequences in which the same data value
  13  *  occurs in many consecutive data elements) are stored as a single data
  14  *  value and count, rather than as the original run. This is most useful
  15  *  on data that contains many such runs: for example, simple graphic
  16  *  images such as icons, line drawings, and animations. It is not useful
  17  *  with files that don't have many runs as it could slightly increase the
  18  *  output size.
  19  *  ALGORITHM: This algorithm is an optimized version of the traditional
  20  *  RLE algorithm in that it behaves better with very few runs.
  21  *
  22  *  With a run of a character where that run is >= 3 this is
  23  *  replaced with the repeat indicator 0X80 and then the repeat count OR'd
  24  *  over this ident.  This repeat count is therefore has a maximum value
  25  *  of 127 (0x7F) which is to be interpreted as the next character repeated
  26  *  another 'repeat count' times (i.e. a maximum of 128 characters can be
  27  *  represented in any single dupal). if the repeat ident is not present
  28  *  then the count is to be interpreted as a copy of the next repeat count
  29  *  characters + 1.
  30  *
  31  *  EXAMPLE: the following arbitary string of 67 bytes:-
  32  *  WWWWWWWWWWWWBWWWWWWWWWWWWBBBWWWWWWWWWWWWWWWWWWWWWWWWBWWWWWWWWWWWWWW
  33  *  will produce (as a HEXDUMP) of 14 bytes
  34  *  8B 57 00 42 8B 57 82 42  97 57 00 42 8D 57        .W.B.W.B.W.B.W
  35  */
  36 //=============================================================================
  37
  38 #ifndef ACE_RLECOMPRESSOR_H
  39 #define ACE_RLECOMPRESSOR_H
  40
  41 #include /**/ "ace/pre.h"
  42
  43 #include "ACE_RLECompression_export.h"
  44
  45 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  46 # pragma once
  47 #endif /* ACE_LACKS_PRAGMA_ONCE */
  48
  49 #include "ace/Compression/Compressor.h"
  50 #include "ace/Singleton.h"
  51
  52 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  53
  54 class ACE_RLECompression_Export ACE_RLECompressor : public ACE_Compressor
  55 {
  56 public:
  57   /**
  58   * Default constructor. Should use instance() to get global instance.
  59   */
  60   ACE_RLECompressor();
  61
  62   ~ACE_RLECompressor() override = default;
  63
  64   /**
  65   * Compress the @a in_ptr buffer for @a in_len into the
  66   * @a dest_ptr buffer with a maximum @a max_out_len using
  67   * the Run Length Ecoding (RLE) algorithm. If the
  68   * @a max_out_len is exhausted through the compress process
  69   * then a value of -1 will be returned from the function,
  70   * otherwise the return value will indicate the resultant
  71   * @a out_ptr compressed buffer length.
  72   *
  73   * @note It is advisable that the @max_out_len be slightly
  74   * larger of the input @a in_len (i.e. x 1.1F) to cater
  75   * for the possibility that a reduced compressed length
  76   * is not possible.
  77   */
  78   ACE_UINT64 compress(const void *in_ptr,
  79                       ACE_UINT64 in_len,
  80                       void *out_ptr,
  81                       ACE_UINT64 max_out_len) override;
  82
  83   /**
  84   * DeCompress the @a in_ptr buffer for @a in_len into the
  85   * @a out_ptr buffer with a maximum @a max_out_len using
  86   * the Run Length Ecoding (RLE) algorithm. If the
  87   * @a max_out_len is exhausted during decompression
  88   * then a value of -1 will be returned from the function,
  89   * otherwise the return value will indicate the resultant
  90   * @a out_ptr decompressed buffer length.
  91   */
  92   ACE_UINT64 decompress(const void *in_ptr,
  93                         ACE_UINT64 in_len,
  94                         void *out_ptr,
  95                         ACE_UINT64 max_out_len) override;
  96 };
  97
  98 ACE_RLECOMPRESSION_SINGLETON_DECLARE(ACE_Singleton, ACE_RLECompressor, ACE_SYNCH_MUTEX);
  99
 100 typedef class ACE_Singleton<ACE_RLECompressor, ACE_SYNCH_MUTEX> ACE_RLECompression;
 101
 102 ACE_END_VERSIONED_NAMESPACE_DECL
 103
 104 #include /**/ "ace/post.h"
 105
 106 #endif // ACE_RLECOMPRESSOR_H