The FILE_GUNZIP routine uncompresses a given GZIP input file or files, and saves the uncompressed data into a new file or to memory. The uncompression is done using the ZLIB library, written by Jean-Loup Gailly and Mark Adler.

This routine is written in the IDL language. Its source code can be found in the file file_gunzip.pro in the lib subdirectory of the IDL distribution.

Examples


Use the following code to compress a single ASCII text file from the IDL examples directory into our current working directory, then GUNZIP the file, and delete the original .gz file:

file = FILEPATH('irreg_grid2.txt', SUBDIR=['examples','data'])
FILE_GZIP, file, 'irreg_grid2.txt.gz'
FILE_GUNZIP, 'irreg_grid2.txt.gz', /DELETE, /VERBOSE

IDL prints:

% Uncompress irreg_grid2.txt.gz  14213 bytes

As another example, we can uncompress the above file into a buffer.

file = FILEPATH('irreg_grid2.txt', SUBDIR=['examples','data'])
FILE_GZIP, file, 'irreg_grid2.txt.gz'
FILE_GUNZIP, 'irreg_grid2.txt.gz', BUFFER=data
HELP, data

IDL prints:

DATA            BYTE      = Array[14213]

Syntax


FILE_GUNZIP, File [, FileOut] [, BUFFER=variable] [, /CLOSE] [, COUNT=variable] [, /DELETE] [, NBYTES=value] [, OFFSET=value] [, /VERBOSE]

Arguments


File

Set this argument to a string or array of strings giving the file or files to uncompress.

FileOut

Set this optional argument to a string or array of strings giving the output filenames (including the full path). FileOut must have the same number of elements as File. If you do not provide FileOut, then IDL constructs the output filenames by removing the file suffix ".gz" from each filename. In addition, if you do not provide FileOut, then FILE_GUNZIP will uncompress each file into the same directory as the original file.

Keywords


BUFFER

Setting this keyword to a named variable causes IDL to store the uncompressed data in the variable rather than within a file. If this keyword is present, do not provide the FileOut argument. If there is no data to return then BUFFER will contain a scalar 0, otherwise BUFFER will be a byte array.

CLOSE

By default, the FILE_GUNZIP routine closes the input and output files when the routine finishes. However, if you use the NBYTES or OFFSET keywords, you can set CLOSE=0 to keep the files open. You can then call FILE_GUNZIP again with the same file names, and IDL will continue reading and writing at the current offset within the files. When you finish reading and writing, you must then call FILE_GUNZIP once more with /CLOSE.

COUNT

Set this keyword to a named variable to return the number of bytes that were uncompressed. If File is an array, then COUNT will be an array of integers.

Tip: If you have set the NBYTES keyword to read only a portion of the input file, then the returned COUNT value will be equal to NBYTES until the end of the file is reached. When the end is reached, the returned COUNT value will be less than NBYTES. You can use this behavior to determine if you have reached the end of the input file and should then call FILE_GUNZIP with /CLOSE.

DELETE

By default the FILE_GUNZIP routine preserves the original files. Set the DELETE keyword to delete the original files.

Note: When you are uncompressing multiple files, IDL deletes files as it uncompresses them. If an error occurs during this process, any original files that have been uncompressed will already have been deleted.

NBYTES

Set the NBYTES keyword to an integer giving the number of bytes to uncompress. By default, FILE_GUNZIP uncompresses all of the data within the file. If the file is already open (with CLOSE=0 in a previous call) then by default NBYTES is set to read all of the remaining data within the file.

Note: You can not use the NBYTES keyword with multiple files.

OFFSET

Set the OFFSET keyword to an integer giving the offset within File at which to start reading and uncompressing data. Note that you should specify this offset in terms of the uncompressed data size (as if the data were already uncompressed). By default, FILE_GUNZIP starts at the beginning of the file (or at the current file position if CLOSE=0 was used to keep the file open in a previous FILE_GUNZIP call).

Note: You can not use the OFFSET keyword with multiple files.

VERBOSE

Set this keyword to output additional information while the routine is executing.

Additional Examples


Uncompress a Huge File Using Chunks

You can use the CLOSE, COUNT, and NBYTES keywords to uncompress a potentially huge file using small-size chunks. For example:

; Create a gzip-compressed data file
data = BYTSCL(RANDOMU(1,20000), TOP=10)
OPENW, lun, 'test_data.dat.gz', /GET_LUN
WRITEU, lun, ZLIB_COMPRESS(data, /GZIP)
FREE_LUN, lun
 
nbuffer = 4096
count = nbuffer
while (count ne 0) do begin & $
  FILE_GUNZIP, 'test_data.dat.gz', 'test_data.dat', CLOSE=0, $
  COUNT=count, NBYTES=nbuffer & $
  print, ' count =',count & $
endwhile
FILE_GUNZIP, 'test_data.dat.gz', 'test_data.dat', /CLOSE

IDL prints:

count =        4096
count =        4096
count =        4096
count =        4096
count =        3616
count =           0

Uncompress a Huge File to a Memory Buffer

In this example we uncompress a file to a memory buffer, using chunks:

; Create a gzip-compressed data file
data = BYTSCL(RANDOMU(1,20000), TOP=10)
OPENW, lun, 'test_data.dat.gz', /GET_LUN
WRITEU, lun, ZLIB_COMPRESS(data, /GZIP)
FREE_LUN, lun
 
nbuffer = 4096
count = nbuffer
newdata = LIST()
while (count ne 0) do begin & $
  FILE_GUNZIP, 'test_data.dat.gz', BUFFER=buffer, CLOSE=0, $
  COUNT=count, NBYTES=nbuffer & $
    if (count gt 0) then newdata.Add, buffer & $
endwhile
FILE_GUNZIP, 'test_data.dat.gz', /CLOSE
newdata = newdata.ToArray(DIMENSION=1)
print, 'new data equals original: ', ARRAY_EQUAL(newdata, data)

IDL prints:

new data equals original:    1

Uncompress a Portion of a File

Here, we uncompress just a certain portion of a file to a memory buffer:

; Create a gzip-compressed data file
data = BYTSCL(RANDOMU(1,20000), TOP=10)
OPENW, lun, 'test_data.dat', /GET_LUN
WRITEU, lun, ZLIB_COMPRESS(data, /GZIP)
FREE_LUN, lun
 
FILE_GUNZIP, 'test_data.dat', BUFFER=buffer, $
  NBYTES=10, OFFSET=1000
PRINT, buffer
PRINT, data[1000:1009]

IDL prints:

0   4   2   3   3   1   1   9   6   1
0   4   2   3   3   1   1   9   6   1

Version History


8.2.3

Introduced

See Also


FILE_GZIP, FILE_TAR, FILE_UNTAR, FILE_ZIP, FILE_UNZIP, ZLIB_COMPRESS, ZLIB_UNCOMPRESS