xHarbour Reference Documentation > Function Reference

HB_Compress()

Compresses a character string (ZIP).

Syntax

HB_Compress( <cString> ) --> cCompressed

or

HB_Compress( <nComprFactor>, ;
             <cString>     , ;
             <nStringLen>  , ;
            @<cBuffer>     , ;
            @<nBytes>        ) --> nErrorCode

Arguments

<cString>

This is a character string to be ZIP compressed.

<nComprFactor>

When a numeric value is passed as first parameter, it indicates the compression factor. This factor influences the compression speed and result. A higher compression takes more time. #define constants are available in the file HbCompress.ch that can be used for <nComprFactor>.

ZIP compression factors

Constant	Value	Description
HB_Z_NO_COMPRESSION	0	No compression
HB_Z_BEST_SPEED	1	Fastest compression
HB_Z_BEST_COMPRESSION	9	Highest compression
HB_Z_DEFAULT_COMPRESSION *)	(-1)	Default compression
*) default

<nStringLen>

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

@<cBuffer>

This is a pre-allocated character string. It must be passed by reference and receives the compressed data. Use function HB_CompressBufLen() to calculate the number of bytes required for <cBuffer>.

@<nBytes>

This parameter must be passed by reference. It receives the actual number of compressed bytes when the compression is complete.

Return

The function returns either the compressed character string, or a numeric error code indicating success of the compression operation. See the description for Simple and Advanced usage below.

Description

HB_Compress() is a ZIP compression function for character strings. It is implemented in two "flavours" allowing for simple and advanced data compression.

Simple usage

The easiest way of compressing a character string is by passing it as a single parameter to HB_Compress(). The function returns the compressed data as a character string.

Advanced usage

The function allows for optimizing the compression between speed and compression result. This requires five parameters be passed, the first of which determines the compression factor. The result of the compression is received in two reference parameters. <cBuffer> must be a string large enough to hold the compression result. The function HB_CompressBufLen() can be used to calculate the size of <cBuffer>.

When the compression is complete, the return value is numeric. 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_CompressBufLen(), HB_CompressErrorDesc(), HB_Uncompress()
Category:	ZIP compression , xHarbour extensions
Header:	HbCompress.ch
Source:	rtl\hbcomprs.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates simple and advanced compression

   #include "HbCompress.ch"

   PROCEDURE Main
      LOCAL cText := MemoRead( "CompressTest.prg" )
      LOCAL cSimple
      LOCAL cAdvanced, nRequiredBytes, nError

      t1 := Seconds()
      cSimple := HB_Compress( cText )
      t2 := Seconds()

      nRequiredBytes := HB_CompressBufLen( Len(cText) )
      cAdvanced      := Space( nRequiredBytes )
      t3 := Seconds()
      nError := HB_Compress( HB_Z_BEST_COMPRESSION, ;
                             cText, ;
                             Len( cText ), ;
                             @cAdvanced, ;
                             @nRequiredBytes )
      t4 := Seconds()

      ? "Simple  :", t2-t1, Len(Trim(cSimple))
      ? "Advanced:", t4-t3, Len(Trim(cAdvanced))
   RETURN