Class GZipStream¶

Namespace: OfficeOpenXml.Packaging.Ionic.Zlib
Assembly: EPPlus.dll

A class for compressing and decompressing GZIP streams.

public class GZipStream : Stream, IDisposable, IAsyncDisposable

Inheritance¶

object ← MarshalByRefObject ← Stream ← GZipStream

Implements¶

IAsyncDisposable
IDisposable

Inherited Members¶

Remarks¶

The GZipStream is a Decorator on a [Stream](https://learn.microsoft.com/dotnet/api/system.io.stream). It adds GZIP compression or decompression to any stream.

Like the System.IO.Compression.GZipStream in the .NET Base Class Library, the Ionic.Zlib.GZipStream can compress while writing, or decompress while reading, but not vice versa. The compression method used is GZIP, which is documented in IETF RFC 1952, "GZIP file format specification version 4.3".

A GZipStream can be used to decompress data (through Read()) or to compress data (through Write()), but not both.

If you wish to use the GZipStream to compress data, you must wrap it around a write-able stream. As you call Write() on the GZipStream, the data will be compressed into the GZIP format. If you want to decompress data, you must wrap the GZipStream around a readable stream that contains an IETF RFC 1952-compliant stream. The data will be decompressed as you call Read() on the GZipStream.

Though the GZIP format allows data from multiple files to be concatenated together, this stream handles only a single segment of GZIP format, typically representing a single file.

This class is similar to [ZlibStream](OfficeOpenXml.Packaging.Ionic.Zlib.ZlibStream.md) and [DeflateStream](OfficeOpenXml.Packaging.Ionic.Zlib.DeflateStream.md). ZlibStream handles RFC1950-compliant streams. [DeflateStream](OfficeOpenXml.Packaging.Ionic.Zlib.DeflateStream.md) handles RFC1951-compliant streams. This class handles RFC1952-compliant streams.

Constructors¶

GZipStream(Stream, CompressionMode)¶

Create a GZipStream using the specified CompressionMode.

public GZipStream(Stream stream, CompressionMode mode)

Parameters¶

stream Stream

The stream which will be read or written.

mode CompressionMode

Indicates whether the GZipStream will compress or decompress.

Examples¶

This example shows how to use a GZipStream to compress data.

using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
{
    using (var raw = System.IO.File.Create(outputFile))
    {
        using (Stream compressor = new GZipStream(raw, CompressionMode.Compress))
        {
            byte[] buffer = new byte[WORKING_BUFFER_SIZE];
            int n;
            while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
            {
                compressor.Write(buffer, 0, n);
            }
        }
    }
}

Dim outputFile As String = (fileToCompress & ".compressed")
Using input As Stream = File.OpenRead(fileToCompress)
    Using raw As FileStream = File.Create(outputFile)
    Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress)
        Dim buffer As Byte() = New Byte(4096) {}
        Dim n As Integer = -1
        Do While (n <> 0)
            If (n > 0) Then
                compressor.Write(buffer, 0, n)
            End If
            n = input.Read(buffer, 0, buffer.Length)
        Loop
    End Using
    End Using
End Using

This example shows how to use a GZipStream to uncompress a file.

private void GunZipFile(string filename)
{
    if (!filename.EndsWith(".gz))
        throw new ArgumentException("filename");
    var DecompressedFile = filename.Substring(0,filename.Length-3);
    byte[] working = new byte[WORKING_BUFFER_SIZE];
    int n= 1;
    using (System.IO.Stream input = System.IO.File.OpenRead(filename))
    {
        using (Stream decompressor= new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, true))
        {
            using (var output = System.IO.File.Create(DecompressedFile))
            {
                while (n !=0)
                {
                    n= decompressor.Read(working, 0, working.Length);
                    if (n > 0)
                    {
                        output.Write(working, 0, n);
                    }
                }
            }
        }
    }
}

Private Sub GunZipFile(ByVal filename as String)
    If Not (filename.EndsWith(".gz)) Then
        Throw New ArgumentException("filename")
    End If
    Dim DecompressedFile as String = filename.Substring(0,filename.Length-3)
    Dim working(WORKING_BUFFER_SIZE) as Byte
    Dim n As Integer = 1
    Using input As Stream = File.OpenRead(filename)
        Using decompressor As Stream = new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, True)
            Using output As Stream = File.Create(UncompressedFile)
                Do
                    n= decompressor.Read(working, 0, working.Length)
                    If n > 0 Then
                        output.Write(working, 0, n)
                    End IF
                Loop While (n  > 0)
            End Using
        End Using
    End Using
End Sub

Remarks¶

When mode is CompressionMode.Compress, the GZipStream will use the default compression level.

As noted in the class documentation, the CompressionMode (Compress or Decompress) also establishes the "direction" of the stream. A GZipStream with CompressionMode.Compress works only through Write(). A GZipStream with CompressionMode.Decompress works only through Read().

GZipStream(Stream, CompressionMode, CompressionLevel)¶

Create a GZipStream using the specified CompressionMode and the specified CompressionLevel.

public GZipStream(Stream stream, CompressionMode mode, CompressionLevel level)

Parameters¶

stream Stream

The stream to be read or written while deflating or inflating.

mode CompressionMode

Indicates whether the GZipStream will compress or decompress.

level CompressionLevel

A tuning knob to trade speed for effectiveness.

Examples¶

This example shows how to use a GZipStream to compress a file into a .gz file.

using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
{
    using (var raw = System.IO.File.Create(fileToCompress + ".gz"))
    {
        using (Stream compressor = new GZipStream(raw,
                                                  CompressionMode.Compress,
                                                  CompressionLevel.BestCompression))
        {
            byte[] buffer = new byte[WORKING_BUFFER_SIZE];
            int n;
            while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
            {
                compressor.Write(buffer, 0, n);
            }
        }
    }
}

Using input As Stream = File.OpenRead(fileToCompress)
    Using raw As FileStream = File.Create(fileToCompress & ".gz")
        Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression)
            Dim buffer As Byte() = New Byte(4096) {}
            Dim n As Integer = -1
            Do While (n <> 0)
                If (n > 0) Then
                    compressor.Write(buffer, 0, n)
                End If
                n = input.Read(buffer, 0, buffer.Length)
            Loop
        End Using
    End Using
End Using

Remarks¶

The CompressionMode (Compress or Decompress) also establishes the "direction" of the stream. A GZipStream with CompressionMode.Compress works only through Write(). A GZipStream with CompressionMode.Decompress works only through Read().

GZipStream(Stream, CompressionMode, bool)¶

Create a GZipStream using the specified CompressionMode, and explicitly specify whether the stream should be left open after Deflation or Inflation.

public GZipStream(Stream stream, CompressionMode mode, bool leaveOpen)

Parameters¶

stream Stream

The stream which will be read or written. This is called the "captive" stream in other places in this documentation.

mode CompressionMode

Indicates whether the GZipStream will compress or decompress.

leaveOpen bool

true if the application would like the base stream to remain open after inflation/deflation.

Remarks¶

This constructor allows the application to request that the captive stream remain open after the deflation or inflation occurs. By default, after Close() is called on the stream, the captive stream is also closed. In some cases this is not desired, for example if the stream is a memory stream that will be re-read after compressed data has been written to it. Specify true for the leaveOpen parameter to leave the stream open.

The [CompressionMode](OfficeOpenXml.Packaging.Ionic.Zlib.CompressionMode.md) (Compress or Decompress) also establishes the "direction" of the stream. A GZipStream with CompressionMode.Compress works only through Write(). A GZipStream with CompressionMode.Decompress works only through Read().

The GZipStream will use the default compression level. If you want to specify the compression level, see [GZipStream(Stream, CompressionMode, CompressionLevel, bool)](OfficeOpenXml.Packaging.Ionic.Zlib.GZipStream.md#OfficeOpenXml_Packaging_Ionic_Zlib_GZipStream__ctor_System_IO_Stream_OfficeOpenXml_Packaging_Ionic_Zlib_CompressionMode_OfficeOpenXml_Packaging_Ionic_Zlib_CompressionLevel_System_Boolean_).

See the other overloads of this constructor for example code.

GZipStream(Stream, CompressionMode, CompressionLevel, bool)¶

Create a GZipStream using the specified CompressionMode and the specified CompressionLevel, and explicitly specify whether the stream should be left open after Deflation or Inflation.

public GZipStream(Stream stream, CompressionMode mode, CompressionLevel level, bool leaveOpen)

Parameters¶

stream Stream

The stream which will be read or written.

mode CompressionMode

Indicates whether the GZipStream will compress or decompress.

level CompressionLevel

A tuning knob to trade speed for effectiveness.

leaveOpen bool

true if the application would like the stream to remain open after inflation/deflation.

Examples¶

This example shows how to use a GZipStream to compress data.

using (System.IO.Stream input = System.IO.File.OpenRead(fileToCompress))
{
    using (var raw = System.IO.File.Create(outputFile))
    {
        using (Stream compressor = new GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression, true))
        {
            byte[] buffer = new byte[WORKING_BUFFER_SIZE];
            int n;
            while ((n= input.Read(buffer, 0, buffer.Length)) != 0)
            {
                compressor.Write(buffer, 0, n);
            }
        }
    }
}

Dim outputFile As String = (fileToCompress & ".compressed")
Using input As Stream = File.OpenRead(fileToCompress)
    Using raw As FileStream = File.Create(outputFile)
    Using compressor As Stream = New GZipStream(raw, CompressionMode.Compress, CompressionLevel.BestCompression, True)
        Dim buffer As Byte() = New Byte(4096) {}
        Dim n As Integer = -1
        Do While (n <> 0)
            If (n > 0) Then
                compressor.Write(buffer, 0, n)
            End If
            n = input.Read(buffer, 0, buffer.Length)
        Loop
    End Using
    End Using
End Using

Remarks¶

This constructor allows the application to request that the captive stream remain open after the deflation or inflation occurs. By default, after Close() is called on the stream, the captive stream is also closed. In some cases this is not desired, for example if the stream is a memory stream that will be re-read after compressed data has been written to it. Specify true for the leaveOpen parameter to leave the stream open.

As noted in the class documentation, the CompressionMode (Compress or Decompress) also establishes the "direction" of the stream. A GZipStream with CompressionMode.Compress works only through Write(). A GZipStream with CompressionMode.Decompress works only through Read().

Fields¶

LastModified¶

The last modified time for the GZIP stream.

public DateTime? LastModified

Field Value¶

DateTime?

Remarks¶

GZIP allows the storage of a last modified time with each GZIP entry. When compressing data, you can set this before the first call to Write(). When decompressing, you can retrieve this value any time after the first call to Read().

Properties¶

BufferSize¶

The size of the working buffer for the compression codec.

public int BufferSize { get; set; }

Property Value¶

int

Remarks¶

The working buffer is used for all stream operations. The default size is 1024 bytes. The minimum size is 128 bytes. You may get better performance with a larger buffer. Then again, you might not. You would have to test it.

Set this before the first call to Read() or Write() on the stream. If you try to set it afterwards, it will throw.

CanRead¶

Indicates whether the stream can be read.

public override bool CanRead { get; }

Property Value¶

bool

Remarks¶

The return value depends on whether the captive stream supports reading.

CanSeek¶

Indicates whether the stream supports Seek operations.

public override bool CanSeek { get; }

Property Value¶

bool

Remarks¶

Always returns false.

CanWrite¶

Indicates whether the stream can be written.

public override bool CanWrite { get; }

Property Value¶

bool

Remarks¶

The return value depends on whether the captive stream supports writing.

Comment¶

The comment on the GZIP stream.

public string Comment { get; set; }

Property Value¶

string

Remarks¶

The GZIP format allows for each file to optionally have an associated comment stored with the file. The comment is encoded with the ISO-8859-1 code page. To include a comment in a GZIP stream you create, set this property before calling Write() for the first time on the GZipStream.

When using GZipStream to decompress, you can retrieve this property after the first call to Read(). If no comment has been set in the GZIP bytestream, the Comment property will return null (Nothing in VB).

Crc32¶

The CRC on the GZIP stream.

public int Crc32 { get; }

Property Value¶

int

Remarks¶

This is used for internal error checking. You probably don't need to look at this property.

FileName¶

The FileName for the GZIP stream.

public string FileName { get; set; }

Property Value¶

string

Remarks¶

The GZIP format optionally allows each file to have an associated filename. When compressing data (through Write()), set this FileName before calling Write() the first time on the GZipStream. The actual filename is encoded into the GZIP bytestream with the ISO-8859-1 code page, according to RFC 1952. It is the application's responsibility to insure that the FileName can be encoded and decoded correctly with this code page.

When decompressing (through Read()), you can retrieve this value any time after the first Read(). In the case where there was no filename encoded into the GZIP bytestream, the property will return null (Nothing in VB).

FlushMode¶

This property sets the flush behavior on the stream.

public virtual FlushType FlushMode { get; set; }

Property Value¶

FlushType

Length¶

Reading this property always throws a NotImplementedException.

public override long Length { get; }

Property Value¶

long

Position¶

The position of the stream pointer.

public override long Position { get; set; }

Property Value¶

long

Remarks¶

Setting this property always throws a NotImplementedException. Reading will return the total bytes written out, if used in writing, or the total bytes read in, if used in reading. The count may refer to compressed bytes or uncompressed bytes, depending on how you've used the stream.

TotalIn¶

Returns the total number of bytes input so far.

public virtual long TotalIn { get; }

Property Value¶

long

TotalOut¶

Returns the total number of bytes output so far.

public virtual long TotalOut { get; }

Property Value¶

long

Methods¶

CompressBuffer(byte[])¶

Compress a byte array into a new byte array using GZip.

public static byte[] CompressBuffer(byte[] b)

Parameters¶

b byte[]

A buffer to compress.

Returns¶

byte[]

The data in compressed form

Remarks¶

Uncompress it with UncompressBuffer(byte[]).

CompressString(string)¶

Compress a string into a byte array using GZip.

public static byte[] CompressString(string s)

Parameters¶

s string

A string to compress. The string will first be encoded using UTF8, then compressed.

Returns¶

byte[]

The string in compressed form

Remarks¶

Uncompress it with UncompressString(byte[]).

Dispose(bool)¶

Dispose the stream.

protected override void Dispose(bool disposing)

Parameters¶

disposing bool

indicates whether the Dispose method was invoked by user code.

Remarks¶

This may or may not result in a Close() call on the captive stream. See the constructors that have a leaveOpen parameter for more information.

This method may be invoked in two distinct scenarios. If disposing == true, the method has been called directly or indirectly by a user's code, for example via the public Dispose() method. In this case, both managed and unmanaged resources can be referenced and disposed. If disposing == false, the method has been called by the runtime from inside the object finalizer and this method should not reference other objects; in that case only unmanaged resources must be referenced or disposed.

Flush()¶

Flush the stream.

public override void Flush()

Read(byte[], int, int)¶

Read and decompress data from the source stream.

public override int Read(byte[] buffer, int offset, int count)

Parameters¶

buffer byte[]

The buffer into which the decompressed data should be placed.

offset int

the offset within that data array to put the first byte read.

count int

the number of bytes to read.

Returns¶

int

the number of bytes actually read

Examples¶

byte[] working = new byte[WORKING_BUFFER_SIZE];
using (System.IO.Stream input = System.IO.File.OpenRead(_CompressedFile))
{
    using (Stream decompressor= new Ionic.Zlib.GZipStream(input, CompressionMode.Decompress, true))
    {
        using (var output = System.IO.File.Create(_DecompressedFile))
        {
            int n;
            while ((n= decompressor.Read(working, 0, working.Length)) !=0)
            {
                output.Write(working, 0, n);
            }
        }
    }
}

Remarks¶

With a GZipStream, decompression is done through reading.

Seek(long, SeekOrigin)¶

Calling this method always throws a NotImplementedException.

public override long Seek(long offset, SeekOrigin origin)

Parameters¶

offset long

irrelevant; it will always throw!

origin SeekOrigin

irrelevant; it will always throw!

Returns¶

long

irrelevant!

SetLength(long)¶

Calling this method always throws a NotImplementedException.

public override void SetLength(long value)

Parameters¶

value long

irrelevant; this method will always throw!

UncompressBuffer(byte[])¶

Uncompress a GZip'ed byte array into a byte array.

public static byte[] UncompressBuffer(byte[] compressed)

Parameters¶

compressed byte[]

A buffer containing data that has been compressed with GZip.

Returns¶

byte[]

The data in uncompressed form

UncompressString(byte[])¶

Uncompress a GZip'ed byte array into a single string.

public static string UncompressString(byte[] compressed)

Parameters¶

compressed byte[]

A buffer containing GZIP-compressed data.

Returns¶

string

The uncompressed string

Write(byte[], int, int)¶

Write data to the stream.

public override void Write(byte[] buffer, int offset, int count)

Parameters¶

buffer byte[]

The buffer holding data to write to the stream.

offset int

the offset within that data array to find the first byte to write.

count int

the number of bytes to write.

Remarks¶

If you wish to use the GZipStream to compress data while writing, you can create a GZipStream with CompressionMode.Compress, and a writable output stream. Then call Write() on that GZipStream, providing uncompressed data as input. The data sent to the output stream will be the compressed form of the data written.

A GZipStream can be used for Read() or Write(), but not both. Writing implies compression. Reading implies decompression.

Class GZipStream¶

Inheritance¶

Implements¶

Inherited Members¶

Remarks¶

Constructors¶

GZipStream(Stream, CompressionMode)¶

Parameters¶

Examples¶

Remarks¶

GZipStream(Stream, CompressionMode, CompressionLevel)¶

Parameters¶

Examples¶

Remarks¶

GZipStream(Stream, CompressionMode, bool)¶

Parameters¶

Remarks¶

GZipStream(Stream, CompressionMode, CompressionLevel, bool)¶

Parameters¶

Examples¶

Remarks¶

Fields¶

LastModified¶

Field Value¶

Remarks¶

Properties¶

BufferSize¶

Property Value¶

Remarks¶

CanRead¶

Property Value¶

Remarks¶

CanSeek¶

Property Value¶

Remarks¶

CanWrite¶

Property Value¶

Remarks¶

Comment¶

Property Value¶

Remarks¶

Crc32¶

Property Value¶

Remarks¶

FileName¶

Property Value¶

Remarks¶

FlushMode¶

Property Value¶

Length¶

Property Value¶

Position¶

Property Value¶

Remarks¶

TotalIn¶

Property Value¶

TotalOut¶

Property Value¶

Methods¶

CompressBuffer(byte[])¶

Parameters¶

Returns¶

Remarks¶

See Also¶

CompressString(string)¶

Parameters¶

Returns¶

Remarks¶

See Also¶

Dispose(bool)¶

Parameters¶

Remarks¶

Flush()¶

Read(byte[], int, int)¶

Parameters¶

Returns¶

Examples¶

Remarks¶

Seek(long, SeekOrigin)¶

Parameters¶