From dd17996b1179fe4dbd14594bdce17b50caf45d85 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Sun, 15 Jan 2012 18:57:04 +0100 Subject: [PATCH 01/20] Added introduction to the module At the moment this was just extracted from ZLib manual introduction. I've yet to polish and adapt it a bit to the ruby part. --- ext/zlib/zlib.c | 13 ++++++++++++- 1 files changed, 12 insertions(+), 1 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index a235cbb..d068260 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -224,7 +224,18 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * * == Overview * - * Access to the zlib library. + * This module provides access to the ZLib library + * + * The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data. This version of the library supports only one compression method (deflation) but other algorithms will be added later and will have the same stream interface. + * Compression can be done in a single step if the buffers are large enough (for example if an input file is mmap'ed), or can be done by repeated calls of the compression function. In the latter case, the application must provide more input and/or consume the output (providing more output space) before each call. + * + * The compressed data format used by default by the in-memory functions is the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped around a deflate stream, which is itself documented in RFC 1951. + * + * The library also supports reading and writing files in gzip (.gz) format with an interface similar to that of stdio using the functions that start with "gz". The gzip format is different from the zlib format. gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. + * + * This library can optionally read and write gzip streams in memory as well. + * + * The zlib format was designed to be compact and fast for use in memory and on communications channels. The gzip format was designed for single-file compression on file systems, has a larger header than zlib to maintain directory information, and uses a different, slower check method than zlib. * * == Class tree * -- 1.7.5.1 From c99717a93ae427d0c934e053324f4d29590fe5ed Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 00:04:32 +0100 Subject: [PATCH 02/20] Added trivial usage example --- ext/zlib/zlib.c | 20 ++++++++++++++++++++ 1 files changed, 20 insertions(+), 0 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index d068260..2525633 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -237,6 +237,26 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * * The zlib format was designed to be compact and fast for use in memory and on communications channels. The gzip format was designed for single-file compression on file systems, has a larger header than zlib to maintain directory information, and uses a different, slower check method than zlib. * + * + * == Sample usage + * + * Using the wrapper to compress strings with default parameters is quite simple: + * + * require "zlib" + * + * data_to_compress = File.read("file_to_compress.data") + * + * puts "Input size: #{data_to_compress.size}" + * + * data_compressed = Zlib::Deflate.deflate(data_to_compress) + * + * puts "Compressed data is:\n#{data_compressed}" + * puts "And its size is #{data_compressed.size}" + * + * uncompressed_data = Zlib::Inflate.inflate(data_compressed) + * + * puts "Uncompressed data is:\n#{uncompressed_data}" + * * == Class tree * * - Zlib::Deflate -- 1.7.5.1 From fb7812bca0c41e5de73f90c9dabcbacee0530f27 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 00:06:04 +0100 Subject: [PATCH 03/20] The first paragraph does not apply to ruby wrapper since that behavior is wrapped. --- ext/zlib/zlib.c | 3 +-- 1 files changed, 1 insertions(+), 2 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 2525633..66fec83 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -226,8 +226,7 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * * This module provides access to the ZLib library * - * The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data. This version of the library supports only one compression method (deflation) but other algorithms will be added later and will have the same stream interface. - * Compression can be done in a single step if the buffers are large enough (for example if an input file is mmap'ed), or can be done by repeated calls of the compression function. In the latter case, the application must provide more input and/or consume the output (providing more output space) before each call. + * The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data. * * The compressed data format used by default by the in-memory functions is the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped around a deflate stream, which is itself documented in RFC 1951. * -- 1.7.5.1 From 0c0d740e068f2f31349b196a7d002dcd5145cfef Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 00:32:26 +0100 Subject: [PATCH 04/20] Added some small intro to zlib purpose. --- ext/zlib/zlib.c | 4 +++- 1 files changed, 3 insertions(+), 1 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 66fec83..820979f 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -224,7 +224,9 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * * == Overview * - * This module provides access to the ZLib library + * This module provides access to the {zlib library}[http://zlib.net]. Zlib is designed to be a free, general-purpose, legally unencumbered -- that is, + * not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system. + * The zlib data format is itself portable across platforms. * * The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data. * -- 1.7.5.1 From 6fd5e6849302dd117f11adc5ad6f86245c4bf956 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 13:56:32 +0100 Subject: [PATCH 05/20] Removed deflate instance method usage since it was an example of class method usage and added an example of instance method instead --- ext/zlib/zlib.c | 13 +++++++++---- 1 files changed, 9 insertions(+), 4 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 820979f..71b50da 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1475,12 +1475,17 @@ do_deflate(struct zstream *z, VALUE src, int flush) * If +string+ is nil, this method finishes the * stream, just like Zlib::ZStream#finish. * - * == Usage + * == Sample Usage * - * comp = Zlib.deflate(File.read("big.file")) - * or - * comp = Zlib.deflate(File.read("big.file"), Zlib::FULL_FLUSH) + * === Compressing a string with best compression + * + * zlib = Zlib::Deflate.new(Zlib::BEST_COMPRESSION) + * compressed_string = zlib.deflate(string, Zlib::FINISH) + * zlib.close + * + * puts "Compressed string is: #{compressed_string}" * + * puts "Decompressed string is #{Zlib::Inflate.inflate(compressed_string)}" */ static VALUE rb_deflate_deflate(int argc, VALUE *argv, VALUE obj) -- 1.7.5.1 From 61de75bca6c6a66735c7d79b922a843dfd3b5e54 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 20:58:34 +0100 Subject: [PATCH 06/20] Corrected level parameter and detailed constants Compressiol level ranges from Z_NO_COMPRESSION and Z_BEST_COMPRESSION --- ext/zlib/zlib.c | 9 +++++++-- 1 files changed, 7 insertions(+), 2 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 71b50da..fed8eaf 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1280,8 +1280,13 @@ rb_deflate_s_allocate(VALUE klass) * == Arguments * * +level+:: - * An Integer compression level between - * BEST_SPEED and BEST_COMPRESSION + * An Integer compression level between 0 and 9. The following constants have + * been defined to make code more readable: + * + * [Z_NO_COMPRESSION = 0] + * [Z_BEST_SPEED = 1] + * [Z_BEST_COMPRESSION = 9] + * * +windowBits+:: * An Integer for the windowBits size. Should be * in the range 8..15, larger values of this parameter -- 1.7.5.1 From 657ca6e775ff23de6bde4865608f691419909eeb Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 21:01:57 +0100 Subject: [PATCH 07/20] Added Z_DEFAULT_COMPRESSION constant to constant list in Deflate.new --- ext/zlib/zlib.c | 1 + 1 files changed, 1 insertions(+), 0 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index fed8eaf..9f57edd 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1285,6 +1285,7 @@ rb_deflate_s_allocate(VALUE klass) * * [Z_NO_COMPRESSION = 0] * [Z_BEST_SPEED = 1] + * [Z_DEFAULT_COMPRESSION = 6] * [Z_BEST_COMPRESSION = 9] * * +windowBits+:: -- 1.7.5.1 From 9dcc12e527e41b8bd1d3a5e4f76578ee39f12088 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 21:37:44 +0100 Subject: [PATCH 08/20] Improved strategies documentation in Deflate.new --- ext/zlib/zlib.c | 12 ++++++++---- 1 files changed, 8 insertions(+), 4 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 9f57edd..bbccb17 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1297,10 +1297,14 @@ rb_deflate_s_allocate(VALUE klass) * the internal compression state. * Between DEF_MEM_LEVEL and MAX_MEM_LEVEL * +strategy+:: - * A parameter to tune the compression algorithm. Use the - * DEFAULT_STRATEGY for normal data, FILTERED for data produced by a - * filter (or predictor), HUFFMAN_ONLY to force Huffman encoding only (no - * string match). + * A parameter to tune the compression algorithm. + * [Z_DEFAULT_STRATEGY] For normal data + * [HUFFMAN_ONLY] To force Huffman encoding only (no string match). + * [FILTERED] For data produced by a filter (or predictor). The effect + * of FILTERED is to force more Huffman coding and less string + * matching; it is somewhat intermediate between + * DEFAULT_STRATEGY and HUFFMAN_ONLY. Filtered data consists + * mostly of small values with a somewhat random distribution. * * == Description * -- 1.7.5.1 From 9af96acbf87d97a5309b01b8cf6ed7966ec5a244 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 21:42:14 +0100 Subject: [PATCH 09/20] Changed format for compression levels in Deflate.new --- ext/zlib/zlib.c | 8 ++++---- 1 files changed, 4 insertions(+), 4 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index bbccb17..bf9f27b 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1283,10 +1283,10 @@ rb_deflate_s_allocate(VALUE klass) * An Integer compression level between 0 and 9. The following constants have * been defined to make code more readable: * - * [Z_NO_COMPRESSION = 0] - * [Z_BEST_SPEED = 1] - * [Z_DEFAULT_COMPRESSION = 6] - * [Z_BEST_COMPRESSION = 9] + * * Z_NO_COMPRESSION = 0 + * * Z_BEST_SPEED = 1 + * * Z_DEFAULT_COMPRESSION = 6 + * * Z_BEST_COMPRESSION = 9 * * +windowBits+:: * An Integer for the windowBits size. Should be -- 1.7.5.1 From 3409fd26b46b0f724b2f4b7b810140c48ab3d35c Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 21:53:15 +0100 Subject: [PATCH 10/20] Corrected documentation for Deflate.new's memLevel parameter. The range of values is not between DEF_MEM_LEVEL and MAX_MEM_LEVEL but 1 and 9. Also added constant's value. --- ext/zlib/zlib.c | 9 ++++++--- 1 files changed, 6 insertions(+), 3 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index bf9f27b..ae80cf4 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1293,9 +1293,12 @@ rb_deflate_s_allocate(VALUE klass) * in the range 8..15, larger values of this parameter * result in better at the expense of memory usage. * +memlevel+:: - * Specifies how much memory should be allocated for - * the internal compression state. - * Between DEF_MEM_LEVEL and MAX_MEM_LEVEL + * The memLevel parameter specifies how much memory should be allocated + * for the internal compression state. memLevel=1 uses minimum memory but is + * slow and reduces compression ratio; memLevel=9 uses maximum memory for + * optimal speed. The default value is 8. Two constants are defined: + * * DEF_MEM_LEVEL = 8 + * * MAX_MEM_LEVEL = 9 * +strategy+:: * A parameter to tune the compression algorithm. * [Z_DEFAULT_STRATEGY] For normal data -- 1.7.5.1 From ecb330eab693eaaa06734821ccf272761d63a231 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Tue, 17 Jan 2012 21:55:47 +0100 Subject: [PATCH 11/20] Improved explanation of windowBits parameter --- ext/zlib/zlib.c | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index ae80cf4..0db97f0 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1289,9 +1289,9 @@ rb_deflate_s_allocate(VALUE klass) * * Z_BEST_COMPRESSION = 9 * * +windowBits+:: - * An Integer for the windowBits size. Should be - * in the range 8..15, larger values of this parameter - * result in better at the expense of memory usage. + * An Integer for the windowBits size (the size of the history buffer). + * Should be in the range 8..15. Larger values of this parameter + * result in better compression at the expense of memory usage. * +memlevel+:: * The memLevel parameter specifies how much memory should be allocated * for the internal compression state. memLevel=1 uses minimum memory but is -- 1.7.5.1 From 211223802462e127b4a98a0371f54dc914d5ef48 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Wed, 18 Jan 2012 01:12:18 +0100 Subject: [PATCH 12/20] Documented flush modes --- ext/zlib/zlib.c | 25 ++++++++++++++++++++----- 1 files changed, 20 insertions(+), 5 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 0db97f0..8bf713b 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1473,11 +1473,26 @@ do_deflate(struct zstream *z, VALUE src, int flush) * String * * +flush+:: - * Integer representing a flush code. Either NO_FLUSH, - * SYNC_FLUSH, FULL_FLUSH, or FINISH. See zlib.h for details. - * Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to - * decide how much data to accumulate before producing output, in order to - * maximize compression. + * Integer representing a flush mode. + * [NO_FLUSH] Normally the parameter flush is set to NO_FLUSH, which + * allows deflate to decide how much data to accumulate before + * producing output, in order to maximize compression. + * [SYNC_FLUSH] All pending output is flushed to the output buffer + * and the output is aligned on a byte boundary, so that the + * decompressor can get all input data available so far. (In + * particular avail_in is zero after the call if enough output + * space has been provided before the call.) Flushing may + * degrade compression for some compression algorithms and so + * it should be used only when necessary. This completes the + * current deflate block and follows it with an empty stored + * block that is three bits plus filler bits to the next byte, + * followed by four bytes (00 00 ff ff) + * [FULL_FLUSH] All output is flushed as with SYNC_FLUSH, and the + * compression state is reset so that decompression can + * restart from this point if previous compressed data has been + * damaged or if random access is desired. Using FULL_FLUSH too + * often can seriously degrade compression. + * [FINISH] Pending input is processed, pending output is flushed. * * == Description * -- 1.7.5.1 From 5ceba48064e41420d3561ccc9eafa1f9a3541e50 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Wed, 18 Jan 2012 01:16:17 +0100 Subject: [PATCH 13/20] Given a better name to variable in sample --- ext/zlib/zlib.c | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 8bf713b..8d07f97 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1507,9 +1507,9 @@ do_deflate(struct zstream *z, VALUE src, int flush) * * === Compressing a string with best compression * - * zlib = Zlib::Deflate.new(Zlib::BEST_COMPRESSION) - * compressed_string = zlib.deflate(string, Zlib::FINISH) - * zlib.close + * zstream = Zlib::Deflate.new(Zlib::BEST_COMPRESSION) + * compressed_string = zstream.deflate(string, Zlib::FINISH) + * zstream.close * * puts "Compressed string is: #{compressed_string}" * -- 1.7.5.1 From bcabdc6f9357ecce27bd9e749be88bb759332235 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Wed, 18 Jan 2012 01:41:12 +0100 Subject: [PATCH 14/20] Completed documentation for inflate windowBits parameter --- ext/zlib/zlib.c | 24 ++++++++++++++++++------ 1 files changed, 18 insertions(+), 6 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 8d07f97..2b6eb5c 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1683,14 +1683,26 @@ rb_inflate_s_allocate(VALUE klass) * == Arguments * * +windowBits+:: - * An Integer for the windowBits size. Should be - * in the range 8..15, larger values of this parameter - * result in better at the expense of memory usage. - * + * An Integer whose meaning depends on the value + * [0] To request that inflate use the window size in the zlib header of the + * compressed stream. + * [Between 8 and 15] In this case, +windowBits+ determines the window size. + * +inflate+ will then process raw deflate data, not + * looking for a zlib or gzip header, not generating a + * check value, and not looking for any check values for + * comparison at the end of the stream. This is for use + * with other formats that use the deflate compressed data + * format such as zip. Those formats provide their own + * check values. + * [Greater than 15] windowBits can also be greater than 15 for optional + * gzip decoding. Add 32 to windowBits to enable zlib and + * gzip decoding with automatic header detection, or add + * 16 to decode only the gzip format (the zlib format will + * throw a Zlib::DataError). * == Description * - * Creates a new inflate stream for decompression. See zlib.h for details - * of the argument. If +window_bits+ is +nil+, the default value is used. + * Creates a new inflate stream for decompression. If +window_bits+ is +nil+, + * the default value Zlib::MAX_WBITS is used. * * == Example * -- 1.7.5.1 From e041d86d79c4710ef50b76275cd08ce2d5c88bf6 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Wed, 18 Jan 2012 01:45:27 +0100 Subject: [PATCH 15/20] No Z_ prefix is used in Ruby wrapper constants --- ext/zlib/zlib.c | 10 +++++----- 1 files changed, 5 insertions(+), 5 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 2b6eb5c..0741423 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1283,10 +1283,10 @@ rb_deflate_s_allocate(VALUE klass) * An Integer compression level between 0 and 9. The following constants have * been defined to make code more readable: * - * * Z_NO_COMPRESSION = 0 - * * Z_BEST_SPEED = 1 - * * Z_DEFAULT_COMPRESSION = 6 - * * Z_BEST_COMPRESSION = 9 + * * NO_COMPRESSION = 0 + * * BEST_SPEED = 1 + * * DEFAULT_COMPRESSION = 6 + * * BEST_COMPRESSION = 9 * * +windowBits+:: * An Integer for the windowBits size (the size of the history buffer). @@ -1301,7 +1301,7 @@ rb_deflate_s_allocate(VALUE klass) * * MAX_MEM_LEVEL = 9 * +strategy+:: * A parameter to tune the compression algorithm. - * [Z_DEFAULT_STRATEGY] For normal data + * [DEFAULT_STRATEGY] For normal data * [HUFFMAN_ONLY] To force Huffman encoding only (no string match). * [FILTERED] For data produced by a filter (or predictor). The effect * of FILTERED is to force more Huffman coding and less string -- 1.7.5.1 From 851a2f812465d147c886c68b31f8cd8ddb839ce9 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Wed, 18 Jan 2012 01:53:58 +0100 Subject: [PATCH 16/20] Adding carriage returns to avoid 80 line limit --- ext/zlib/zlib.c | 25 +++++++++++++++++++------ 1 files changed, 19 insertions(+), 6 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 0741423..831297c 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -224,19 +224,32 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * * == Overview * - * This module provides access to the {zlib library}[http://zlib.net]. Zlib is designed to be a free, general-purpose, legally unencumbered -- that is, - * not covered by any patents -- lossless data-compression library for use on virtually any computer hardware and operating system. + * This module provides access to the {zlib library}[http://zlib.net]. Zlib is + * designed to be a free, general-purpose, legally unencumbered -- that is, + * not covered by any patents -- lossless data-compression library for use on + * virtually any computer hardware and operating system. + * * The zlib data format is itself portable across platforms. * - * The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data. + * The zlib compression library provides in-memory compression and + * decompression functions, including integrity checks of the uncompressed + * data. * - * The compressed data format used by default by the in-memory functions is the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped around a deflate stream, which is itself documented in RFC 1951. + * The compressed data format used by default by the in-memory functions is the + * zlib format, which is a zlib wrapper documented in RFC 1950, wrapped around + * a deflate stream, which is itself documented in RFC 1951. * - * The library also supports reading and writing files in gzip (.gz) format with an interface similar to that of stdio using the functions that start with "gz". The gzip format is different from the zlib format. gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. + * The library also supports reading and writing files in gzip (.gz) format + * with an interface similar to that of stdio using the functions that start + * with "gz". The gzip format is different from the zlib format. gzip is a gzip + * wrapper, documented in RFC 1952, wrapped around a deflate stream. * * This library can optionally read and write gzip streams in memory as well. * - * The zlib format was designed to be compact and fast for use in memory and on communications channels. The gzip format was designed for single-file compression on file systems, has a larger header than zlib to maintain directory information, and uses a different, slower check method than zlib. + * The zlib format was designed to be compact and fast for use in memory and on + * communications channels. The gzip format was designed for single-file + * compression on file systems, has a larger header than zlib to maintain + * directory information, and uses a different, slower check method than zlib. * * * == Sample usage -- 1.7.5.1 From 56380bfb5af91f5d687c285364dc01f811e04716 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Wed, 18 Jan 2012 02:06:28 +0100 Subject: [PATCH 17/20] Added references when parameters are already described --- ext/zlib/zlib.c | 10 +++------- 1 files changed, 3 insertions(+), 7 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 831297c..2c53342 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1569,7 +1569,7 @@ rb_deflate_addstr(VALUE obj, VALUE src) * SYNC_FLUSH is used as flush. This method is just provided * to improve the readability of your Ruby program. * - * Please visit your zlib.h for a deeper detail on NO_FLUSH, SYNC_FLUSH, FULL_FLUSH, and FINISH + * Please visit Zlib::Deflate#deflate for a deeper detail on NO_FLUSH, SYNC_FLUSH, FULL_FLUSH, and FINISH * */ static VALUE @@ -1600,13 +1600,9 @@ rb_deflate_flush(int argc, VALUE *argv, VALUE obj) * buffer. * * +level+:: - * An Integer compression level between - * BEST_SPEED and BEST_COMPRESSION + * See Zlib::Deflate.new * +strategy+:: - * A parameter to tune the compression algorithm. Use the - * DEFAULT_STRATEGY for normal data, FILTERED for data produced by a - * filter (or predictor), HUFFMAN_ONLY to force Huffman encoding only (no - * string match). + * See Zlib::Deflate.new * */ static VALUE -- 1.7.5.1 From da35b5ec1140a8f6eeeb12a2ad9ac608c49f3a13 Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Sun, 22 Jan 2012 11:43:41 +0100 Subject: [PATCH 18/20] Added output of puts instructions --- ext/zlib/zlib.c | 17 +++++++++++++---- 1 files changed, 13 insertions(+), 4 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 2c53342..b36c8d5 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -257,19 +257,28 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * Using the wrapper to compress strings with default parameters is quite simple: * * require "zlib" - * - * data_to_compress = File.read("file_to_compress.data") * + * data_to_compress = File.read("file_to_compress.data") + * * puts "Input size: #{data_to_compress.size}" + * #=> Input lenght: 2347740 * * data_compressed = Zlib::Deflate.deflate(data_to_compress) * - * puts "Compressed data is:\n#{data_compressed}" + * puts "Compressed data is:\n#{data_compressed}" + * #=> Compressed data is: + * x????r?%?.3?C?Cuoe??K??(???M??$?????@?輐B}???=2?z???S[?%?ï˗?mb?] + * [...] + * * puts "And its size is #{data_compressed.size}" - * + * #=> And its size is 887238 + * * uncompressed_data = Zlib::Inflate.inflate(data_compressed) * * puts "Uncompressed data is:\n#{uncompressed_data}" + * #=> Uncompressed data is: + * The Project Gutenberg EBook of Don Quixote, by Miguel de Cervantes + * [...] * * == Class tree * -- 1.7.5.1 From 87b0d8175a57cc36f5086589bd99bdfcb1cd09ef Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Sun, 22 Jan 2012 11:56:53 +0100 Subject: [PATCH 19/20] Added output of puts to custom compression --- ext/zlib/zlib.c | 3 +++ 1 files changed, 3 insertions(+), 0 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index b36c8d5..5ba6a02 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -1534,8 +1534,11 @@ do_deflate(struct zstream *z, VALUE src, int flush) * zstream.close * * puts "Compressed string is: #{compressed_string}" + * #=> Compressed string is: ڜ??r?%?.3?C?Cu???Rwץ[?(???͋6I??f? Decompressed string is The Project Gutenberg EBook of Don Quixote, by Miguel de Cervantes */ static VALUE rb_deflate_deflate(int argc, VALUE *argv, VALUE obj) -- 1.7.5.1 From 1d17e3f744cb2aee35b1ab9d3b008f7af38a1e0c Mon Sep 17 00:00:00 2001 From: Rafa de Castro Date: Sun, 29 Jan 2012 15:19:38 +0100 Subject: [PATCH 20/20] Reformatted examples to avoid new lines in comments. Reformulated flush mode description. --- ext/zlib/zlib.c | 35 +++++++++++++++-------------------- 1 files changed, 15 insertions(+), 20 deletions(-) diff --git a/ext/zlib/zlib.c b/ext/zlib/zlib.c index 5ba6a02..a257eee 100644 --- a/ext/zlib/zlib.c +++ b/ext/zlib/zlib.c @@ -265,20 +265,16 @@ static VALUE rb_gzreader_readlines(int, VALUE*, VALUE); * * data_compressed = Zlib::Deflate.deflate(data_to_compress) * - * puts "Compressed data is:\n#{data_compressed}" - * #=> Compressed data is: - * x????r?%?.3?C?Cuoe??K??(???M??$?????@?輐B}???=2?z???S[?%?ï˗?mb?] - * [...] + * puts "Compressed data is:#{data_compressed}" + * #=> Compressed data is: x????r?%?.3?C?Cuoe??K??(???M??$?????@?輐B}???=2?z... * * puts "And its size is #{data_compressed.size}" * #=> And its size is 887238 * * uncompressed_data = Zlib::Inflate.inflate(data_compressed) * - * puts "Uncompressed data is:\n#{uncompressed_data}" - * #=> Uncompressed data is: - * The Project Gutenberg EBook of Don Quixote, by Miguel de Cervantes - * [...] + * puts "Uncompressed data is:#{uncompressed_data}" + * #=> Uncompressed data is:The Project Gutenberg EBook of Don Quixote... * * == Class tree * @@ -1492,10 +1488,10 @@ do_deflate(struct zstream *z, VALUE src, int flush) * == Arguments * * +string+:: - * String + * String to deflate * * +flush+:: - * Integer representing a flush mode. + * Flush mode. You can use four constants to specify flush mode. * [NO_FLUSH] Normally the parameter flush is set to NO_FLUSH, which * allows deflate to decide how much data to accumulate before * producing output, in order to maximize compression. @@ -1534,11 +1530,10 @@ do_deflate(struct zstream *z, VALUE src, int flush) * zstream.close * * puts "Compressed string is: #{compressed_string}" - * #=> Compressed string is: ڜ??r?%?.3?C?Cu???Rwץ[?(???͋6I??f? Compressed string is: ڜ??r?%?.3?C?Cu???Rwץ[?(???͋6I??... * * puts "Decompressed string is #{Zlib::Inflate.inflate(compressed_string)}" - * #=> Decompressed string is The Project Gutenberg EBook of Don Quixote, by Miguel de Cervantes + * #=> Decompressed string is The Project Gutenberg EBook of Don Quixote... */ static VALUE rb_deflate_deflate(int argc, VALUE *argv, VALUE obj) @@ -1727,15 +1722,15 @@ rb_inflate_s_allocate(VALUE klass) * * == Example * - * cf = File.open("compressed.file") - * ucf = File.open("uncompressed.file", "w+") - * zi = Zlib::Inflate.new(Zlib::MAX_WBITS) + * compressed_file = File.open("compressed.gz") + * uncompressed_file = File.open("uncompressed.file", "w+") + * zip = Zlib::Inflate.new(16) * - * ucf << zi.inflate(cf.read) + * uncompressed_file << zip.inflate(compressed_file.read) * - * ucf.close - * zi.close - * cf.close + * uncompressed_file.close + * zip.close + * compressed_file.close * * or * -- 1.7.5.1