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:
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:
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:
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
See Also
FILE_GZIP, FILE_TAR, FILE_UNTAR, FILE_ZIP, FILE_UNZIP, ZLIB_COMPRESS, ZLIB_UNCOMPRESS