402
CMP( ) Function
Compress Data
Format
CMP(string[,ERR=stmtref])
Where:
string
Original data to be compressed.
stmtref
Program line number or label to transfer control to.
Returns
Compressed data string.
Description
The CMP( ) function uses standard ZLib compression libraries to compress a data
string. To expand (uncompress) the data, use the UCP( ) Function, p.545. TCB(195)
will return 1 if ZLib support is available.
The data returned from the CMP( ) function includes a single header byte (value
between $01$ and $FF$) to facilitate ZLib uncompression routines. This represents a
multiplier value that can be used against the length of the compressed data to
estimate uncompressed data size (basically, original size/compressed size rounded
up and capped at 255). When expanding the compressed data using the UCP( )
function, the length of the compressed data will be multiplied by this header byte to
determine an estimated uncompressed buffer size.
Note: Since the CMP( ) and UCP( ) compression routines are not supported on all
platforms, systems using these functions may not be fully portable.
Typically, the compressed data will be smaller than the original data; however, in
rare instances or when dealing with short strings, the compressed data might be
longer. Also be aware that data returned from the compression logic may contain
any potential character; therefore, if writing to a data file, do not use field delimiters
since they may occur within the compressed data.
Interfacing with Other ZLib-compliant Utilities
The header byte should be removed from the compressed data if it is to be used
outside of ProvideX.
Example
0100
! ^100 - CMP and UCP functions
0110
Original$=dim(512,"String to compress ")
0120
Compressed$=cmp(Original$)
0130
print "Length of Original: ",'BR',str(len(Original$)),'ER'
0140
print "Original String:
",'BR',Original$,'ER'
0150
print "Length of Compressed:",'BR',str(len(Compressed$)),'ER'
0160
print "Compressed String:
",'BR',cvs(Compressed$,16:"~"),'ER'
0170
print
0180
!
0200
! ^100 - Due to Zlib overhead, not all strings yield smaller strings