Add String Support to Compression Codec

[folly.git] / folly / io / Compression.h

diff --git a/folly/io/Compression.h b/folly/io/Compression.h
index 569356b13fa291ad86f97537c514def00f6a236b..05ce06d1f66662e102945914ab9351f6f255aa9a 100644 (file)
--- a/folly/io/Compression.h
+++ b/folly/io/Compression.h
@@ -1,5 +1,5 @@
 /*
- * Copyright 2014 Facebook, Inc.
+ * Copyright 2017 Facebook, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,13 +14,13 @@
  * limitations under the License.
  */
 
-#ifndef FOLLY_IO_COMPRESSION_H_
-#define FOLLY_IO_COMPRESSION_H_
+#pragma once
 
 #include <cstdint>
 #include <limits>
 #include <memory>
 
+#include <folly/Range.h>
 #include <folly/io/IOBuf.h>
 
 /**
@@ -73,7 +73,19 @@ enum class CodecType {
   LZMA2 = 6,
   LZMA2_VARINT_SIZE = 7,
 
-  NUM_CODEC_TYPES = 8,
+  /**
+   * Use ZSTD compression.
+   */
+  ZSTD = 8,
+
+  /**
+   * Use gzip compression.  This is the same compression algorithm as ZLIB but
+   * gzip-compressed files tend to be easier to work with from the command line.
+   * Levels supported: 0 = no compression, 1 = fast, ..., 9 = best; default = 6
+   */
+  GZIP = 9,
+
+  NUM_CODEC_TYPES = 10,
 };
 
 class Codec {
@@ -84,6 +96,7 @@ class Codec {
    * Return the maximum length of data that may be compressed with this codec.
    * NO_COMPRESSION and ZLIB support arbitrary lengths;
    * LZ4 supports up to 1.9GiB; SNAPPY supports up to 4GiB.
+   * May return UNLIMITED_UNCOMPRESSED_LENGTH if unlimited.
    */
   uint64_t maxUncompressedLength() const;
 
@@ -107,6 +120,13 @@ class Codec {
    */
   std::unique_ptr<IOBuf> compress(const folly::IOBuf* data);
 
+  /**
+   * Compresses data. May involve additional copies compared to the overload
+   * that takes and returns IOBufs. Has the same error semantics as the IOBuf
+   * version.
+   */
+  std::string compress(StringPiece data);
+
   /**
    * Uncompress data. Throws std::runtime_error on decompression error.
    *
@@ -120,11 +140,21 @@ class Codec {
    * an empty IOBuf chain will return an empty IOBuf chain.
    */
   static constexpr uint64_t UNKNOWN_UNCOMPRESSED_LENGTH = uint64_t(-1);
+  static constexpr uint64_t UNLIMITED_UNCOMPRESSED_LENGTH = uint64_t(-2);
 
   std::unique_ptr<IOBuf> uncompress(
       const IOBuf* data,
       uint64_t uncompressedLength = UNKNOWN_UNCOMPRESSED_LENGTH);
 
+  /**
+   * Uncompresses data. May involve additional copies compared to the overload
+   * that takes and returns IOBufs. Has the same error semantics as the IOBuf
+   * version.
+   */
+  std::string uncompress(
+      StringPiece data,
+      uint64_t uncompressedLength = UNKNOWN_UNCOMPRESSED_LENGTH);
+
  protected:
   explicit Codec(CodecType type);
 
@@ -136,6 +166,14 @@ class Codec {
   virtual std::unique_ptr<IOBuf> doCompress(const folly::IOBuf* data) = 0;
   virtual std::unique_ptr<IOBuf> doUncompress(const folly::IOBuf* data,
                                               uint64_t uncompressedLength) = 0;
+  // default: an implementation is provided by default to wrap the strings into
+  // IOBufs and delegate to the IOBuf methods. This incurs a copy of the output
+  // from IOBuf to string. Implementers, at their discretion, can override
+  // these methods to avoid the copy.
+  virtual std::string doCompressString(StringPiece data);
+  virtual std::string doUncompressString(
+      StringPiece data,
+      uint64_t uncompressedLength);
 
   CodecType type_;
 };
@@ -163,7 +201,9 @@ constexpr int COMPRESSION_LEVEL_BEST = -3;
 std::unique_ptr<Codec> getCodec(CodecType type,
                                 int level = COMPRESSION_LEVEL_DEFAULT);
 
-}}  // namespaces
-
-#endif /* FOLLY_IO_COMPRESSION_H_ */
+/**
+ * Check if a specified codec is supported.
+ */
+bool hasCodec(CodecType type);
 
+}}  // namespaces