CkByteData Perl Reference Documentation

CkByteData

Represents a chunk of byte data and provides methods for accessing it, adding to it, or saving and loading from files.

Object Creation

$obj = new chilkat::CkByteData();

Properties

None

Methods

# $db is a CkByteData
$ckByteData->append($db);

Appends byte data to the data already contained in the object.

# $pByteData is binary data
# $szByteData is an integer
$ckByteData->append2($pByteData, $szByteData);

Appends bytes to the data already contained in the object.

# $ch is a char
$ckByteData->appendChar($ch);

Appends a single byte.

# $ch is a char
# $numTimes is an integer
$ckByteData->appendCharN($ch, $numTimes);

Appends a single char N times. The equivalent of calling appendChar N times.

# $str is a string
# $encoding is a string
$ckByteData->appendEncoded($str, $encoding);

Appends binary data from an encoded string. The encoding can be specified as "hex", "base64", "url", "quoted-printable", "modBase64", "base58", or "base32". The input string is decoded from the specified encoding and the binary data is appended to the calling object's content.

# $str is a utf-16 string
# $encoding is a utf-16 string
$ckByteData->appendEncodedW($str, $encoding);

To be documented soon...

# $path is a string
$retBool = $ckByteData->appendFile($path);

Opens a file for binary read, appends the file contents, and closes the file.

# $path is a utf-16 string
$retBool = $ckByteData->appendFileW($path);

To be documented soon...

# $intValue is an integer
# $littleEndian is a boolean
$ckByteData->appendInt($intValue, $littleEndian);

Appends a 32-bit signed integer (4 bytes) to the data already contained in the object. littleEndian determines whether the big endian or little endian byte ordering is used.

# $numBytes is an integer
$ckByteData->appendRandom($numBytes);

Appends numBytes random bytes to the data already contained within the object.

# $byteData is a CkByteData
# $index is an integer
# $numBytes is an integer
$ckByteData->appendRange($byteData, $index, $numBytes);

Appends a range of bytes from byteData to the data contained withing the caller. The first byte is at index 0.

# $shortValue is an integer
# $littleEndian is a boolean
$ckByteData->appendShort($shortValue, $littleEndian);

Appends a 16-bit signed integer (2 bytes) to the data already contained in the object. littleEndian determines whether the big endian or little endian byte ordering is used.

# $str is a string
$ckByteData->appendStr($str);

Appends a null-terminated string to the data, without including the terminating null.

# $str is a utf-16 string
# $charset is a utf-16 string
$ckByteData->appendStrW($str, $charset);

To be documented soon...

# $byteDataObj is a CkByteData
$retBool = $ckByteData->beginsWith($byteDataObj);

Returns 1 if the caller's data begins with the exact bytes contained within byteDataObj.

# $pByteData is binary data
# $szByteData is an integer
$retBool = $ckByteData->beginsWith2($pByteData, $szByteData);

Returns 1 if the caller's data begins with specified bytes.

$ckByteData->byteSwap4321();

4321 byte swaps the data contained within the object.

$ckByteData->clear();

Clears the CkByteData object of all data.

# $encoding is a string
# $str is a CkString
$ckByteData->encode($encoding, $str);

Encodes binary data according to the encoding requested. The encoding can be specified as "hex", "base64", "url", "quoted-printable", "modBase64", "base58", "base32", "qp-", "url_rfc1738", "url_rfc2396", or "url_rfc3986".

# $encoding is a utf-16 string
# $str is a CkString
$ckByteData->encodeW($encoding, $str);

To be documented soon...

# $expectedNumBytes is an integer
$status = $ckByteData->ensureBuffer($expectedNumBytes);

This method can be called to help optimize internal memory re-allocation. If, for example, many calls will be made to append data, and the total size is approximately known, then this method can be called to pre-allocate the internal buffer to the expected total size.

Returns 1 for success, 0 for failure.

# $compareBytes is a CkByteData
$retBool = $ckByteData->equals($compareBytes);

Returns 1 if compareBytes contains exactly the same content as the caller. Otherwise returns 0.

# $pCompareBytes is a CkByteData
# $numBytes is an integer
$retBool = $ckByteData->equals2($pCompareBytes, $numBytes);

Returns 1 if the bytes pointed to by pCompareBytes contains exactly the same content as the caller. Otherwise returns 0.

# $byteDataObj is a CkByteData
$retInt = $ckByteData->findBytes($byteDataObj);

Locates the first occurance of the bytes contained in byteDataObj and returns the index of where these bytes occur in the caller's data. Returns -1 if not found.

# $findBytes is a CkByteData
# $findBytesLen is an integer
$retInt = $ckByteData->findBytes2($findBytes, $findBytesLen);

Locates the first occurance of the specified bytes and returns the index of where these bytes occur in the caller's data. Returns -1 if not found.

# $byteIndex is an integer
$retByte = $ckByteData->getByte($byteIndex);

Returns the Nth byte of the binary data. The 1st byte is at index 0.

$binary_data = $ckByteData->getBytes();

This method is deprecated. It will be removed in a future version.

Returns a pointer to the bytes contained within the object. Be very careful with the pointer that is returned. If more data is appended to the object, an internal reallocation may occur such that the previously returned pointer is no longer valid.

This method is identical to the getData method. Use getData instead.

# $byteIndex is an integer
$retChar = $ckByteData->getChar($byteIndex);

Returns the Nth byte of the binary content as a "char". The 1st byte is at index 0.

$binary_data = $ckByteData->getData();

Returns a pointer to the internal buffer. Be careful with this method because if additional data is appended, the data within the object may be relocated and the pointer may cease to be valid.

# $byteIndex is an integer
$binary_data = $ckByteData->getDataAt($byteIndex);

Same as getData, except it gets a pointer to the data at a byte offset. (0 = the start of buffer)

# $encoding is a string
# $outStr is a CkString (output)
$status = $ckByteData->getEncoded($encoding, $outStr);
$retStr = $ckByteData->getEncoded($encoding);

Introduced in version 9.5.0.47

Returns the binary data as an encoded string. The encoding may be "base64", "hex", "quoted-printable" (or "qp"), "url", "asc", "url_rfc1738", "url_rfc2396", "url_rfc3986", or "url_oauth".

Returns 1 for success, 0 for failure.

# $encoding is a utf-16 string
$utf16_text = $ckByteData->getEncodedW($encoding);

The utf-16 version of getEncoded.

# $byteIndex is an integer
$retInt = $ckByteData->getInt($byteIndex);

Returns the 4-byte integer located at a specific byte index.

# $byteIndex is an integer
# $numBytes is an integer
$binary_data = $ckByteData->getRange($byteIndex, $numBytes);

Copies a range of bytes to a separate internal memory buffer and returns the pointer to the bytes. The returned pointer is only valid while the object exists. Also, any subsequent calls to getRange, getRangeStr, or to_s will invalidate the buffer.

$retInt = $ckByteData->getSize();

Returns the number of bytes in the data buffer.

$retBool = $ckByteData->is7bit();

Returns 1 if all the bytes are in the range 0x00 to 0x7F.

# $path is a string
$retBool = $ckByteData->loadFile($path);

Equivalent to clear() followed by appendFile().

# $path is a utf-16 string
$retBool = $ckByteData->loadFileW($path);

To be documented soon...

# $blockSize is an integer
# $paddingScheme is an integer
$ckByteData->pad($blockSize, $paddingScheme);

Pads the data to a multiple of the blockSize using a cryptographic padding scheme specified by paddingScheme. The possible integer values for paddingScheme are the same as those listed for the PaddingScheme property of the CkCrypt2 class.

# $expectedNumBytes is an integer
$retBool = $ckByteData->preAllocate($expectedNumBytes);

This method is deprecated. It will be removed in a future version.

This method can be called to help optimize internal memory re-allocation. If, for example, many calls will be made to append data, and the total size is approximately known, then this method can be called to pre-allocate the internal buffer to the expected total size.

This method is identical to the ensureBuffer method. Use ensureBuffer instead.

# $startIndex is an integer
# $numBytes is an integer
$ckByteData->removeChunk($startIndex, $numBytes);

Removes (discards) a range from the data.

# $existingByteValue is a CkByteData
# $replacementByteValue is a CkByteData
$ckByteData->replaceChar($existingByteValue, $replacementByteValue);

Replaces all occurances of existingByteValue with replacementByteValue.

# $path is a string
$retBool = $ckByteData->saveFile($path);

Saves the byte data to a file. If the file already exists, it will be overwritten.

# $path is a utf-16 string
$retBool = $ckByteData->saveFileW($path);

To be documented soon...

# $numBytes is an integer
$ckByteData->shorten($numBytes);

Discards N bytes from the end of the data.

# $charset is a string
$utf16_text = $ckByteData->to_ws($charset);

To be documented soon...

# $blockSize is an integer
# $paddingScheme is an integer
$ckByteData->unpad($blockSize, $paddingScheme);

Unpads the data from a multiple of the blockSize to the original data size using a cryptographic padding scheme specified by paddingScheme. The possible integer values for paddingScheme are the same as those listed for the PaddingScheme property of the CkCrypt2 class.