xHarbour Reference Documentation > Function Reference

HB_Uncompress()

Uncompresses a compressed character string (ZIP).

Syntax

HB_Uncompress( <nBytes>, <cCompressed> ) --> cUncompressed

or

HB_Uncompress( <nBytes>     , ;
               <cCompressed>, ;
               <nComprLen>  , ;
              @<cString>      ) --> nError

Arguments

<nBytes>

This numeric value indicates the number of bytes the uncompressed string is going to have.

<cCompressed>

This is a character string holding the copressed data. It is obtained from function HB_Compress().

<nComprLen>

This numeric value indicates the number of bytes of the input string to uncompress. Use the expression Len(<cCompressed>) to uncompress the entire input string.

@<cString>

This is a pre-allocated character string. It must be passed by reference and receives the uncompressed data.

Return

The function returns either the uncompressed character string, or a numeric error code indicating success of the uncompression operation. See the description below.

Description

HB_Uncompress() is the reverse function of HB_Compress() and uncompressed character string holding ZIP compressed data. It is implemented in two "flavours" allowing for simple and advanced uncompression of data.

The easiest way of uncompressing a character string is by passing the number of bytes for the result string and the ZIP compressed string to HB_Uncompress(). In this case, the function returns the uncompressed data as a character string.

Alternatively, the number od bytes to use from <cCompressed> can be specified as <nComprLen>. This requires <cString> be passed by reference as fourth parameter, since the function returns a numeric error code in this case. The value zero indicates a successful operation. Values other than zero can be passed to HB_CompressErrorDesc() to obtain a descriptive error message.

Info

See also:	HB_Compress(), HB_CreateLen8(), HB_CompressError(), HB_GetLen8()
Category:	ZIP compression , xHarbour extensions
Header:	HbCompress.ch
Source:	rtl\hbcomprs.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example implements two functions for easiest (un)compression
// since the buffer size required for uncompression is stored in
// the compressed string using HB_CreateLen8().

   PROCEDURE Main
      LOCAL cText := MemoRead( "LargeFile.txt" )
      LOCAL cCompressed, cUncompressed

      cCompressed   := ZipCompress( cText )

      cUnCompressed := ZipUncompress( cCompressed )

      ? "Original    :", Len( cText )
      ? "Compressed  :", Len( cCompressed )
      ? "Uncompressed:", Len( cUncompressed )
      ? cUncompressed == cText
   RETURN


   // The function adds 8 bytes holding the length of the original
   // character string to the compressed string
   FUNCTION ZipCompress( cString )
      LOCAL cCompressed := HB_Compress( cString )

   RETURN HB_CreateLen8( Len( cString ) ) + cCompressed


   // The function extracts the first 8 bytes holding the length
   // of the uncompressed character string from the compressed string
   FUNCTION ZipUncompress( cCompressed )
      LOCAL nBytes := HB_GetLen8( cCompressed )

   RETURN HB_Uncompress( nBytes, SubStr( cCompressed, 9 ) )