CkByteData Tcl Reference Documentation

CkByteData

Current Version: 9.5.0.97

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

Object Creation

set myCkByteData [new CkByteData]

Properties

SecureClear
boolean 1/0
set boolVal [CkByteData_get_SecureClear $myCkByteData]
CkByteData_put_SecureClear $myCkByteData $boolVal
Introduced in version 9.5.0.73

If set to 1, then memory is always first overwritten with zero bytes prior to deallocation. The default value of this property is 0.

top

Methods

append
# db is a CkByteData
CkByteData_append $db

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

top
append2
# pByteData is binary data
# szByteData is an integer
CkByteData_append2 $pByteData $szByteData

Appends bytes to the data already contained in the object.

top
appendChar
# ch is a char
CkByteData_appendChar $ch

Appends a single byte.

top
appendCharN
# 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.

top
appendEncoded
# 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.

top
appendEncodedW
# str is a utf-16 string
# encoding is a utf-16 string
CkByteData_appendEncodedW $str $encoding

To be documented soon...

top
appendFile
# path is a string
set retBool [CkByteData_appendFile $path]

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

top
appendFileW
# path is a utf-16 string
set retBool [CkByteData_appendFileW $path]

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

top
appendInt
# 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.

top
appendRandom
# numBytes is an integer
CkByteData_appendRandom $numBytes

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

top
appendRange
# 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.

top
appendShort
# 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.

top
appendStr
# str is a string
CkByteData_appendStr $str

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

top
appendStrW
# str is a utf-16 string
# charset is a utf-16 string
CkByteData_appendStrW $str $charset

To be documented soon...

top
beginsWith
# byteDataObj is a CkByteData
set retBool [CkByteData_beginsWith $byteDataObj]

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

top
beginsWith2
# pByteData is binary data
# szByteData is an integer
set retBool [CkByteData_beginsWith2 $pByteData $szByteData]

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

top
byteSwap4321
CkByteData_byteSwap4321

4321 byte swaps the data contained within the object.

top
clear
CkByteData_clear

Clears the CkByteData object of all data. The internal memory is deallocated. To clear without deallocating, call dropData instead.

top
dropData
CkByteData_dropData
Introduced in version 9.5.0.91

Sets the size of the data to 0. Does not deallocate the existing internal buffer. (This is a fast way of "clearing" the CkByteData object, such that the existing data remains in memory and is overwritten on the next append.)

If the SecureClear property is set to 1, then the internal memory buffer is zeroed out before resetting the size to 0.

top
encode
# 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".

top
encodeW
# encoding is a utf-16 string
# str is a CkString
CkByteData_encodeW $encoding $str

To be documented soon...

top
ensureBuffer
# expectedNumBytes is an integer
set 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.

If the internal buffer is already larger than the expectedNumBytes then nothing happens. The existing internal buffer is kept.

Returns 1 for success, 0 for failure.

top
equals
# compareBytes is a CkByteData
set retBool [CkByteData_equals $compareBytes]

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

top
equals2
# pCompareBytes is binary data
# numBytes is an integer
set 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.

top
findBytes
# byteDataObj is a CkByteData
set retInt [CkByteData_findBytes $byteDataObj]

Locates the first occurrence 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.

top
findBytes2
# findBytes is binary data
# findBytesLen is an integer
set retInt [CkByteData_findBytes2 $findBytes $findBytesLen]

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

top
getByte
# byteIndex is an integer
set retByte [CkByteData_getByte $byteIndex]

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

top
getChar
# byteIndex is an integer
set retChar [CkByteData_getChar $byteIndex]

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

top
getData
set 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.

top
getDataAt
# byteIndex is an integer
set 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)

top
getEncoded
# encoding is a string
set 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".

top
getEncodedW
# encoding is a utf-16 string
set utf16_text [CkByteData_getEncodedW $encoding]

The utf-16 version of getEncoded.

top
getInt
# byteIndex is an integer
set retInt [CkByteData_getInt $byteIndex]

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

top
getRange
# byteIndex is an integer
# numBytes is an integer
set 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.

top
getSize
set retInt [CkByteData_getSize]

Returns the number of bytes in the data buffer.

top
is7bit
set retBool [CkByteData_is7bit]

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

top
loadFile
# path is a string
set retBool [CkByteData_loadFile $path]

Equivalent to clear() followed by appendFile().

top
loadFileW
# path is a utf-16 string
set retBool [CkByteData_loadFileW $path]

To be documented soon...

top
pad
# 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.

top
removeChunk
# startIndex is an integer
# numBytes is an integer
CkByteData_removeChunk $startIndex $numBytes

Removes (discards) a range from the data.

top
replaceChar
# existingByteValue is a byte
# replacementByteValue is a byte
CkByteData_replaceChar $existingByteValue $replacementByteValue

Replaces all occurrences of existingByteValue with replacementByteValue.

top
saveFile
# path is a string
set retBool [CkByteData_saveFile $path]

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

top
saveFileW
# path is a utf-16 string
set retBool [CkByteData_saveFileW $path]

To be documented soon...

top
shorten
# numBytes is an integer
CkByteData_shorten $numBytes

Discards N bytes from the end of the data.

top
to_ws
# charset is a string
set utf16_text [CkByteData_to_ws $charset]

To be documented soon...

top
unpad
# 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.

top