What the Class Is Used For

Use Chilkat.BinData when an application needs to accumulate or manipulate bytes without immediately converting them to a string or file. It can append raw bytes, encoded data, strings in specific character sets, integers in chosen byte order, BOMs, padded fields, and other BinData objects. It can also return the bytes as raw data, encoded text, decoded text, hash values, chunks, integers, or file output.

Binary Buffer Store, append, clear, compare, remove, and securely clear byte data.

Encoding Bridge Decode Base64, hex, Base32, Base58, URL encoding, quoted-printable, and other encodings into bytes, or export bytes in encoded form.

Text and Charset Support Append strings using a charset, convert between character encodings, validate UTF-8, and interpret bytes as text.

Binary Structure Helpers Append and read 16-bit and 32-bit integers, byte-swap data, append counted strings, and build padded fields.

Typical Workflow

Create a BinData object.
Load or append data using LoadFile, LoadBinary, LoadEncoded, AppendBinary, AppendEncoded, or AppendString.
Optionally transform or inspect the data with CharsetConvert, ByteSwap, FindString, GetHash, or integer-reading methods.
Retrieve the data as bytes, encoded text, decoded text, chunks, hash values, or integers.
Write the contents to a file with WriteFile or append them to a file with WriteAppendFile.
Use SecureClear when the object contained sensitive data that should be overwritten before internal memory is released.
Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept	Meaning	Important Members
Mutable Byte Container	The object holds a sequence of bytes that can be replaced, appended to, removed from, transformed, or written to a file.	NumBytes, AppendBinary, RemoveChunk, Clear
Encoded Binary Data	Binary bytes can be represented as text using encodings such as Base64, hex, Base32, Base58, quoted-printable, or URL encoding.	LoadEncoded, AppendEncoded, GetEncoded
Character Encoding	Text can be converted to bytes using a charset, and bytes can be interpreted back into text using a charset.	AppendString, GetString, CharsetConvert
Byte Order	Integers can be appended or read using little-endian or big-endian byte ordering.	AppendInt2, AppendInt4, GetInt2, GetUInt4
Chunk Access	A portion of the buffer can be retrieved, encoded, decoded as text, or removed.	GetBinaryChunk, GetEncodedChunk, GetTextChunk, RemoveChunk
Secure Clearing	Sensitive data can be overwritten with zero bytes before the internal memory is released.	SecureClear

Core Properties

Property	Purpose	Guidance
NumBytes	Returns the number of bytes currently contained in the object.	Use to check buffer length after loading, appending, converting, or removing data.
LastErrorText	Diagnostic text for the last method or property access.	Check after failures or unexpected results. Diagnostic information may be available regardless of success or failure.

Loading and Replacing Contents

Input Source	Method	Behavior
Raw byte array	LoadBinary	Loads binary data and replaces the current contents.
Encoded text	LoadEncoded	Decodes the supplied encoded string and replaces the current contents.
File	LoadFile	Loads data from a file into the object.
Clear current contents	Clear	Removes all bytes from the object.
Securely clear current contents	SecureClear	Writes zero bytes to the internal memory before deallocating it.

Replace vs append: Methods beginning with Load replace the current contents. Methods beginning with Append add to the existing contents.

Appending Data

Data to Append	Method	Notes
Another BinData	AppendBd	Appends the contents of another BinData object.
Byte array	AppendBinary, AppendData	Appends binary bytes. AppendData appends the requested number of bytes from the supplied data.
Single byte	AppendByte	Appends one byte. The value should be from 0 to 255.
Encoded binary data	AppendEncoded, AppendEncodedSb	Decodes encoded data and appends the resulting bytes.
String	AppendString, AppendSb	Converts text to bytes using the specified charset and appends the bytes.
BOM / preamble	AppendBom	Appends the appropriate byte order mark for a charset such as UTF-8, UTF-16, or UTF-32 when one is defined.
16-bit or 32-bit integer	AppendInt2, AppendInt4	Appends integers using little-endian or big-endian byte order.
Counted string	AppendCountedString	Appends a byte count followed by the string encoded with the requested charset.
Padded string field	AppendPadded	Appends a fixed-length string field padded with spaces or null bytes.

Encoded Binary Data

Task	Method	Supported Encodings
Load encoded data	LoadEncoded	Decodes encoded text and replaces the object contents.
Append encoded data	AppendEncoded, AppendEncodedSb	Decodes encoded text and appends the resulting bytes.
Get all data encoded	GetEncoded	Returns the complete contents as encoded text.
Get encoded chunk	GetEncodedChunk	Encodes a byte range and returns it as text.
Write encoded data to StringBuilder	GetEncodedSb	Writes the encoded data to a supplied StringBuilder.

Encoding examples: Supported binary encodings include base64, modBase64, base64Url, base32, base58, qp for quoted-printable, url for URL encoding, and hex.

Text, Charset, and BOM Operations

Task	Method	Behavior
Append string as bytes	AppendString	Converts the string to bytes using the specified charset and appends the bytes. It does not append a BOM.
Append StringBuilder text	AppendSb	Appends StringBuilder contents using the specified charset.
Append BOM	AppendBom	Appends the byte order mark for the requested charset when that charset has a defined BOM.
Convert character encoding	CharsetConvert	Converts the object contents from one charset to another, such as Windows-1252 to UTF-8.
Interpret bytes as text	GetString	Interprets the entire byte buffer using the specified charset and returns a string.
Interpret a byte range as text	GetTextChunk	Interprets a byte range using the specified charset and returns a string.
Find text in byte data	FindString	Converts the search string to bytes using the specified charset and searches from a byte index.
Validate UTF-8	IsValidUtf8	Returns true if the object contains valid UTF-8 byte sequences.

Charset conversion behavior: CharsetConvert uses allOrNone to control failure handling. If true, the contents remain unchanged when errors occur. If false, error bytes are discarded.

Retrieving Binary Data

Output	Method	Notes
All bytes	GetBinary, GetData	Retrieves the binary data contained in the object.
Byte chunk	GetBinaryChunk, GetDataChunk	Retrieves a byte range starting at an offset for a specified number of bytes.
Single byte	GetByte	Returns the byte at the specified index as an integer from 0 to 255.
Encoded text	GetEncoded, GetEncodedChunk, GetEncodedSb	Returns all or part of the bytes in encoded text form.
Decoded text	GetString, GetTextChunk	Interprets all or part of the byte buffer as text using a charset.

Integer and Endianness Helpers

Task	Method	Details
Append signed 16-bit integer	AppendInt2	Appends 2 bytes in little-endian or big-endian order.
Append signed 32-bit integer	AppendInt4	Appends 4 bytes in little-endian or big-endian order.
Read signed 16-bit integer	GetInt2	Reads a 16-bit signed integer at a byte index using the selected byte order.
Read signed 32-bit integer	GetInt4	Reads a 32-bit signed integer at a byte index using the selected byte order.
Read unsigned 16-bit integer	GetUInt2	Reads a 16-bit unsigned integer at a byte index using the selected byte order.
Read unsigned 32-bit integer	GetUInt4	Reads a 32-bit unsigned integer at a byte index using the selected byte order.
Byte-swap entire buffer	ByteSwap	Swaps 16-bit groups when size is 16, or 32-bit groups when size is 32.

ByteSwap examples: 16-bit swapping changes 0x1234 to 0x3412. 32-bit swapping changes 0x12345678 to 0x78563412.

Counted and Padded Strings

Method	Purpose	Key Options
AppendCountedString	Appends a byte count followed by a string encoded with a specified charset.	numCountBytes controls the byte count field size. bigEndian controls byte order. A value of 0 uses a minimal number of bytes for the count.
AppendPadded	Appends a fixed-length string field padded with spaces or null bytes.	padWithSpace chooses space padding or null-byte padding. The method always appends exactly fieldLen bytes if successful.

Fixed-length field rule: AppendPadded returns false and appends nothing if the string is longer than fieldLen.

Searching, Comparing, Hashing, and Validation

Task	Method	Behavior
Compare contents	ContentsEqual	Returns true if this object’s bytes equal the bytes in another BinData object.
Find text	FindString	Searches for the byte representation of a string starting at a specified byte index.
Hash contents	GetHash	Computes a hash of the object’s contents and returns it in the requested encoding.
Validate UTF-8	IsValidUtf8	Returns false if any byte sequence is invalid UTF-8.

Hash algorithms: GetHash supports algorithms including sha1, sha256, sha384, sha512, sha3-224, sha3-256, sha3-384, sha3-512, md2, md5, ripemd128, ripemd160, ripemd256, and ripemd320.

Removing and Clearing Data

Task	Method	Behavior
Clear all contents	Clear	Removes all bytes from the object.
Securely clear all contents	SecureClear	Writes zero bytes to memory before deallocating the internal memory.
Remove a byte range	RemoveChunk	Removes numBytes bytes starting at offset.
Remove all bytes with a specific value	RemoveByteVal	Removes bytes having the specified value from 0 to 255. For example, pass 0 to remove all null bytes.

Sensitive data: Use SecureClear instead of Clear when the buffer contains secrets, private keys, passwords, or other sensitive bytes.

File Input and Output

Task	Method	Behavior
Load file	LoadFile	Reads the file contents into the BinData object.
Write file	WriteFile	Writes the object’s contents to a file.
Append to file	WriteAppendFile	Appends the object’s contents to a file.

Method Summary by Category

Category	Methods	Purpose
Load / replace	LoadBinary, LoadEncoded, LoadFile, Clear, SecureClear	Replace or clear the object’s current contents.
Append bytes	AppendBd, AppendBinary, AppendData, AppendByte	Add raw bytes or another BinData object.
Append encoded/text data	AppendEncoded, AppendEncodedSb, AppendString, AppendSb, AppendBom	Decode encoded text or convert strings to bytes and append them.
Structured append	AppendInt2, AppendInt4, AppendCountedString, AppendPadded	Build binary structures with integers, counted strings, or fixed-length fields.
Retrieve bytes	GetBinary, GetData, GetBinaryChunk, GetDataChunk, GetByte	Retrieve all bytes, chunks, or a single byte.
Retrieve text / encoded data	GetEncoded, GetEncodedChunk, GetEncodedSb, GetString, GetTextChunk	Convert bytes to encoded text or decode bytes as text using a charset.
Integer reads	GetInt2, GetInt4, GetUInt2, GetUInt4	Read signed or unsigned integers from the byte buffer.
Transform / inspect	ByteSwap, CharsetConvert, FindString, ContentsEqual, GetHash, IsValidUtf8	Convert, search, compare, hash, validate, or byte-swap contents.
Remove / file output	RemoveChunk, RemoveByteVal, WriteFile, WriteAppendFile	Remove bytes or write the object’s contents to files.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
General method failure	LastErrorText	Check after failed load, append, conversion, remove, write, or encoding operations.
Unexpected buffer size	NumBytes	Confirm whether the operation replaced contents or appended to existing contents.
Encoded data cannot be decoded	LoadEncoded, AppendEncoded	Confirm the encoded text matches the specified encoding, such as Base64 or hex.
Text appears garbled	AppendString, GetString, CharsetConvert	Confirm the charset used to convert between strings and bytes.
Integer values are wrong	AppendInt2, AppendInt4, GetInt2, GetUInt4	Confirm the intended little-endian or big-endian byte order.
UTF-8 text fails validation	IsValidUtf8	The buffer contains at least one byte sequence that is not valid UTF-8.
Padded field append fails	AppendPadded	Confirm the encoded string length is not greater than fieldLen.

Common Pitfalls

Pitfall	Better Approach
Calling a Load* method when append behavior was intended.	Use Append* methods to preserve existing contents and add more bytes.
Forgetting that AppendString does not append a BOM.	Call AppendBom first when a BOM/preamble is required.
Using the wrong charset when appending or reading strings.	Be explicit with charsets such as utf-8, utf-16, windows-1252, or ansi.
Reading integers with the wrong byte order.	Match the littleEndian argument to the binary format being parsed.
Expecting AppendPadded to truncate long strings.	It fails and appends nothing if the string is longer than the requested field length.
Using Clear for sensitive data.	Use SecureClear when the buffer contains secrets that should be overwritten in memory.

Best Practices

Recommendation	Reason
Use BinData as the binary bridge between classes.	Many Chilkat classes accept or return BinData for binary data without unnecessary string conversion.
Use explicit encodings for encoded binary data.	Passing base64, hex, base64Url, or another encoding avoids ambiguity.
Use explicit charsets for text operations.	Correct charset selection prevents corrupted text and mismatched byte sequences.
Check NumBytes after important transformations.	It confirms whether bytes were added, removed, converted, or cleared as expected.
Use chunk methods for large or structured data.	GetBinaryChunk, GetEncodedChunk, GetTextChunk, and RemoveChunk allow byte-range operations.
Use GetHash directly on the buffer.	It avoids separately extracting bytes just to compute a digest.
Use SecureClear for secret material.	It overwrites internal memory with zero bytes before releasing it.
Check LastErrorText after failures.	It provides the most useful diagnostic detail for load, append, conversion, encoding, hashing, remove, and file-write operations.

Summary

Chilkat.BinData is a general-purpose mutable byte container. It can load bytes from files, byte arrays, or encoded strings; append bytes, strings, integers, BOMs, counted strings, padded fields, and other BinData objects; retrieve bytes as raw data, chunks, text, or encoded strings; compute hashes; convert character encodings; validate UTF-8; remove bytes; and write the result to files.

The most important practical distinction is between loading, which replaces the current contents, and appending, which preserves existing data and adds more bytes. For text and encoded data, always specify the charset or binary encoding explicitly.

Chilkat.BinData Class Overview