--- product: Chilkat product_version: 11.7.0 language: pascal language_label: Lazarus Pascal class: BinData license: free deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/pascal_BinDataRef.html --- # Chilkat BinData — Lazarus Pascal — v11.7.0 > Chilkat 11.7.0 · language=pascal · class=BinData > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/BinData.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/guide.md`. ## Purpose **Build, transform, encode, decode, inspect, and save binary data.** `Chilkat.BinData` is a general-purpose mutable byte container used throughout Chilkat for working with binary content in memory. It can load bytes from files, byte arrays, strings, and encoded text; append additional data in many forms; retrieve content as raw bytes, chunks, text, or encoded strings; compute hashes; convert character encodings; validate UTF-8; remove byte ranges; and write the final result to files. **Load binary content** Load data from files, byte arrays, strings, encoded strings, or other Chilkat objects that produce binary output. **Append and build data** Append bytes, strings, integers, BOMs, counted strings, padded fields, encoded data, and other `BinData` objects. **Encode and decode** Convert binary data to and from text encodings such as Base64, hex, URL encoding, and other supported binary encodings. **Text and charset handling** Interpret bytes as text, append strings using a specified charset, convert character encodings, and validate UTF-8 content. **Inspect and modify bytes** Get byte counts, extract chunks, remove ranges, compare data, and work with specific portions of a binary buffer. **Hash and save output** Compute hashes for the contained data and write the resulting bytes to files or pass them to other Chilkat classes. **Common pattern:** Load or append binary data, perform any needed encoding, decoding, hashing, charset conversion, or byte-level edits, then retrieve the result as bytes, text, an encoded string, or a file. Use `BinData` whenever a Chilkat method needs a mutable in-memory binary buffer. For an extended overview, see [BinData Class Overview](https://www.chilkatsoft.com/bindata_class_overview.asp). ## Object creation, unlocking and error handling **Create / Free** ```pascal uses Chilkat.BinData; var obj: TBinData; begin obj := TBinData.Create; try if not obj.IsValid then raise Exception.Create('Failed to create a TBinData instance.'); // ... use obj ... finally obj.Free; end; end; ``` `constructor Create;` Allocates the underlying CkBinData object and returns a new TBinData instance. Simply adding **Chilkat.BinData** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed). `destructor Destroy; override;` Every TBinData created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkBinData handle. A native (unmanaged) memory leak occurs if the object is never freed. Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Lazarus Pascal. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `NumBytes` | property, read-only | `property NumBytes: Integer read GetNumBytes;` | | `AppendBd` | method | `// binData is a TBinData object. function AppendBd(binData: TChilkatBase): Boolean;` | | `AppendBom` | method | `function AppendBom(const charset: string): Boolean;` | | `AppendByte` | method | `function AppendByte(byteValue: Integer): Boolean;` | | `AppendCountedString` | method | `function AppendCountedString(numCountBytes: Integer;     bigEndian: Boolean;     const str: string;     const charset: string): Boolean;` | | `AppendData` | method | `function AppendData(data: TBytes;     numBytes: Integer): Boolean;` | | `AppendEncoded` | method | `function AppendEncoded(const encData: string;     const encoding: string): Boolean;` | | `AppendEncodedSb` | method | `// sb is a TStringBuilder object. function AppendEncodedSb(sb: TChilkatBase;     const encoding: string): Boolean;` | | `AppendInt2` | method | `function AppendInt2(value: Integer;     littleEndian: Boolean): Boolean;` | | `AppendInt4` | method | `function AppendInt4(value: Integer;     littleEndian: Boolean): Boolean;` | | `AppendPadded` | method | `function AppendPadded(const str: string;     const charset: string;     padWithSpace: Boolean;     fieldLen: Integer): Boolean;` | | `AppendSb` | method | `// sb is a TStringBuilder object. function AppendSb(sb: TChilkatBase;     const charset: string): Boolean;` | | `AppendString` | method | `function AppendString(const str: string;     const charset: string): Boolean;` | | `ByteSwap` | method | `procedure ByteSwap(size: Integer);` | | `CharsetConvert` | method | `function CharsetConvert(const fromCharset: string;     const toCharset: string;     allOrNone: Boolean): Boolean;` | | `Clear` | method | `function Clear: Boolean;` | | `ContentsEqual` | method | `// binData is a TBinData object. function ContentsEqual(binData: TChilkatBase): Boolean;` | | `FindString` | method | `function FindString(const str: string;     startIdx: Integer;     const charset: string): Integer;` | | `GetByte` | method | `function GetByte(index: Integer): Integer;` | | `GetData` | method | `function GetData: TBytes;` | | `GetDataChunk` | method | `function GetDataChunk(offset: Integer;     numBytes: Integer): TBytes;` | | `GetEncoded` | method | `function GetEncoded(const encoding: string): string;` | | `GetEncodedChunk` | method | `function GetEncodedChunk(offset: Integer;     numBytes: Integer;     const encoding: string): string;` | | `GetEncodedSb` | method | `// sb is a TStringBuilder object. function GetEncodedSb(const encoding: string;     sb: TChilkatBase): Boolean;` | | `GetHash` | method | `function GetHash(const algorithm: string;     const encoding: string): string;` | | `GetInt2` | method | `function GetInt2(index: Integer;     littleEndian: Boolean): Integer;` | | `GetInt4` | method | `function GetInt4(index: Integer;     littleEndian: Boolean): Integer;` | | `GetString` | method | `function GetString(const charset: string): string;` | | `GetTextChunk` | method | `function GetTextChunk(startIdx: Integer;     numBytes: Integer;     const charset: string): string;` | | `GetUInt2` | method | `function GetUInt2(index: Integer;     littleEndian: Boolean): LongWord;` | | `GetUInt4` | method | `function GetUInt4(index: Integer;     littleEndian: Boolean): LongWord;` | | `IsValidUtf8` | method | `function IsValidUtf8: Boolean;` | | `LoadEncoded` | method | `function LoadEncoded(const encData: string;     const encoding: string): Boolean;` | | `LoadFile` | method | `function LoadFile(const path: string): Boolean;` | | `RemoveByteVal` | method | `procedure RemoveByteVal(value: Integer);` | | `RemoveChunk` | method | `function RemoveChunk(offset: Integer;     numBytes: Integer): Boolean;` | | `SecureClear` | method | `function SecureClear: Boolean;` | | `WriteAppendFile` | method | `function WriteAppendFile(const path: string): Boolean;` | | `WriteFile` | method | `function WriteFile(const path: string): Boolean;` | ## Properties ### BinData.NumBytes `Chilkat 11.7.0 · pascal · BinData · NumBytes · property · read-only · since 9.5.0.51` ```pascal property NumBytes: Integer read GetNumBytes; ``` The number of bytes contained within the object. ## Methods ### BinData.AppendBd `Chilkat 11.7.0 · pascal · BinData · AppendBd · method · since 9.5.0.62` ```pascal // binData is a TBinData object. function AppendBd(binData: TChilkatBase): Boolean; ``` Appends the contents of another BinData to this object. Returns True for success, False for failure. ### BinData.AppendBom `Chilkat 11.7.0 · pascal · BinData · AppendBom · method · since 9.5.0.62` ```pascal function AppendBom(const charset: string): Boolean; ``` Appends the appropriate BOM (byte order mark), also known as a `preamble`, for the given charset. If the `charset` has no defined BOM, then nothing is appended. An application would typically call this to append the utf-8, utf-16, or utf-32 BOM. Returns True for success, False for failure. ### BinData.AppendByte `Chilkat 11.7.0 · pascal · BinData · AppendByte · method · since 9.5.0.77` ```pascal function AppendByte(byteValue: Integer): Boolean; ``` Appends a single byte. The `byteValue` should be a value from 0 to 255. Returns True for success, False for failure. ### BinData.AppendCountedString `Chilkat 11.7.0 · pascal · BinData · AppendCountedString · method · since 9.5.0.91` ```pascal function AppendCountedString(numCountBytes: Integer;     bigEndian: Boolean;     const str: string;     const charset: string): Boolean; ``` Appends a byte count followed by the string in the desired character encoding, such as `utf-8`. The `numCountBytes` is the size in bytes of the integer to represent the byte count. If 0, then a minimal number of bytes is used. If `bigEndian` is `True`, the byte count is appended in big endian byte ordering, otherwise little-ending byte ordering. The `str` is the string to be appended. The `charset` is the character encoding, such as `utf-8`, `utf-16`, `windows-1252`, etc. Returns True for success, False for failure. ### BinData.AppendData `Chilkat 11.7.0 · pascal · BinData · AppendData · method · since 11.0.0` ```pascal function AppendData(data: TBytes;     numBytes: Integer): Boolean; ``` Appends binary data to the current contents. Returns True for success, False for failure. ### BinData.AppendEncoded `Chilkat 11.7.0 · pascal · BinData · AppendEncoded · method · since 9.5.0.51` ```pascal function AppendEncoded(const encData: string;     const encoding: string): Boolean; ``` Appends encoded binary data to the current data. The `encoding` may be `Base64`, `modBase64`, `base64Url`, `Base32`, `Base58`, `QP` (for quoted-printable), `URL` (for url-encoding), `Hex`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.AppendEncodedSb `Chilkat 11.7.0 · pascal · BinData · AppendEncodedSb · method · since 9.5.0.62` ```pascal // sb is a TStringBuilder object. function AppendEncodedSb(sb: TChilkatBase;     const encoding: string): Boolean; ``` Decodes the contents of `sb` and appends the decoded bytes to this object. The `encoding` may be `Base64`, `modBase64`, `base64Url`, `Base32`, `Base58`, `QP` (for quoted-printable), `URL` (for url-encoding), `Hex`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.AppendInt2 `Chilkat 11.7.0 · pascal · BinData · AppendInt2 · method · since 9.5.0.77` ```pascal function AppendInt2(value: Integer;     littleEndian: Boolean): Boolean; ``` Appends a 16-bit integer (2 bytes). If `littleEndian` is `True`, then the integer bytes are appended in little-endian byte order, otherwise big-endian byte order is used. Returns True for success, False for failure. ### BinData.AppendInt4 `Chilkat 11.7.0 · pascal · BinData · AppendInt4 · method · since 9.5.0.77` ```pascal function AppendInt4(value: Integer;     littleEndian: Boolean): Boolean; ``` Appends a 32-bit integer (4 bytes). If `littleEndian` is `True`, then the integer bytes are appended in little-endian byte order, otherwise big-endian byte order is used. Returns True for success, False for failure. ### BinData.AppendPadded `Chilkat 11.7.0 · pascal · BinData · AppendPadded · method · since 9.5.0.80` ```pascal function AppendPadded(const str: string;     const charset: string;     padWithSpace: Boolean;     fieldLen: Integer): Boolean; ``` Appends a string to this object, padded to the `fieldLen` with NULL or SPACE chars. If `padWithSpace` is `True`, then SPACE chars are used and the string is not null-terminated. If `fieldLen` is `False`, then null bytes are used. The `charset` controls the byte representation to use, such as `utf-8`. Note: This call will always append a total number of bytes equal to `fieldLen`. If the `str` is longer than `fieldLen`, the method returns `False` to indicate failure and nothing is appended. Returns True for success, False for failure. ### BinData.AppendSb `Chilkat 11.7.0 · pascal · BinData · AppendSb · method · since 9.5.0.62` ```pascal // sb is a TStringBuilder object. function AppendSb(sb: TChilkatBase;     const charset: string): Boolean; ``` Appends the contents of a StringBuilder to this object. Returns True for success, False for failure. ### BinData.AppendString `Chilkat 11.7.0 · pascal · BinData · AppendString · method · since 9.5.0.62` ```pascal function AppendString(const str: string;     const charset: string): Boolean; ``` Appends a string to this object. (This does not append the BOM. If a BOM is required, the AppendBom method can be called to append the appropriate BOM.) Returns True for success, False for failure. ### BinData.ByteSwap `Chilkat 11.7.0 · pascal · BinData · ByteSwap · method · since 11.0.0` ```pascal procedure ByteSwap(size: Integer); ``` Does either 16-bit or 32-bit byte swapping of the entire contents. If `size` equals 16, then swaps in 2 bytes (e.g., 0x1234 → 0x3412). If `size` equals 32, then swaps 4 bytes (e.g., 0x12345678 → 0x78563412) ### BinData.CharsetConvert `Chilkat 11.7.0 · pascal · BinData · CharsetConvert · method · since 11.0.0` ```pascal function CharsetConvert(const fromCharset: string;     const toCharset: string;     allOrNone: Boolean): Boolean; ``` This method converts the character encoding of an object's contents from one format to another, such as from Windows-1252 to UTF-8. The `allOrNone` parameter determines error handling for unrepresentable bytes. If `allOrNone` is `True`, the object's contents remain unchanged when errors occur. If `False`, error bytes are discarded. The method returns `True` if successful and `False` if errors occur. Returns True for success, False for failure. ### BinData.Clear `Chilkat 11.7.0 · pascal · BinData · Clear · method · since 9.5.0.51` ```pascal function Clear: Boolean; ``` Clears the contents. Returns True for success, False for failure. ### BinData.ContentsEqual `Chilkat 11.7.0 · pascal · BinData · ContentsEqual · method · since 9.5.0.62` ```pascal // binData is a TBinData object. function ContentsEqual(binData: TChilkatBase): Boolean; ``` Return `True` if the contents of this object equals the contents of `binData`. ### BinData.FindString `Chilkat 11.7.0 · pascal · BinData · FindString · method · since 9.5.0.85` ```pascal function FindString(const str: string;     startIdx: Integer;     const charset: string): Integer; ``` Return the index where the first occurrence of `str` is found. Return -1 if not found. The `startIdx` indicates the byte index where the search begins. The `charset` specifies the byte representation of `str` that is to be searched. For example, it can be `utf-8`, `windows-1252`, `ansi`, `utf-16`, etc. ### BinData.GetByte `Chilkat 11.7.0 · pascal · BinData · GetByte · method · since 9.5.0.92` ```pascal function GetByte(index: Integer): Integer; ``` Returns the value of the byte at the given `index`. The returned value is an integer from 0 to 255. ### BinData.GetData `Chilkat 11.7.0 · pascal · BinData · GetData · method · since 11.0.0` ```pascal function GetData: TBytes; ``` Retrieves the binary data contained within the object. Returns `nil` on failure ### BinData.GetDataChunk `Chilkat 11.7.0 · pascal · BinData · GetDataChunk · method · since 11.0.0` ```pascal function GetDataChunk(offset: Integer;     numBytes: Integer): TBytes; ``` Retrieves a chunk of the binary data contained within the object. Returns `nil` on failure ### BinData.GetEncoded `Chilkat 11.7.0 · pascal · BinData · GetEncoded · method · since 9.5.0.51` ```pascal function GetEncoded(const encoding: string): string; ``` Retrieves the binary data as an encoded string. The `encoding` may be `Base64`, `modBase64`, `base64Url`, `Base32`, `Base58`, `QP` (for quoted-printable), `URL` (for url-encoding), `Hex`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.GetEncodedChunk `Chilkat 11.7.0 · pascal · BinData · GetEncodedChunk · method · since 9.5.0.51` ```pascal function GetEncodedChunk(offset: Integer;     numBytes: Integer;     const encoding: string): string; ``` Retrieves a chunk of the binary data and returns it in encoded form. The `encoding` may be `Base64`, `modBase64`, `base64Url`, `Base32`, `Base58`, `QP` (for quoted-printable), `URL` (for url-encoding), `Hex`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.GetEncodedSb `Chilkat 11.7.0 · pascal · BinData · GetEncodedSb · method · since 9.5.0.64` ```pascal // sb is a TStringBuilder object. function GetEncodedSb(const encoding: string;     sb: TChilkatBase): Boolean; ``` Writes the encoded data to a StringBuilder. The `encoding` may be `Base64`, `modBase64`, `base64Url`, `Base32`, `Base58`, `QP` (for quoted-printable), `URL` (for url-encoding), `Hex`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.GetHash `Chilkat 11.7.0 · pascal · BinData · GetHash · method · since 9.5.0.91` ```pascal function GetHash(const algorithm: string;     const encoding: string): string; ``` Returns the hash of the contents of this object. The `algorithm` is the hash algorithm, and can be `sha1`, `sha256`, `sha384`, `sha512`, `sha3-224`, `sha3-256`, `sha3-384`, `sha3-512`, `md2`, `md5`, `ripemd128`, `ripemd160`,`ripemd256`, or `ripemd320`. The `encoding` can be `base64`, `modBase64`, `base64Url`, `base32`, `base58`, `qp` (for quoted-printable), `url` (for url-encoding), `hex`, `hexLower`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.GetInt2 `Chilkat 11.7.0 · pascal · BinData · GetInt2 · method · since 9.5.0.88` ```pascal function GetInt2(index: Integer;     littleEndian: Boolean): Integer; ``` Returns the value of the 16-bit signed integer stored in big-endian or little-endian byte ordering at the given index. ### BinData.GetInt4 `Chilkat 11.7.0 · pascal · BinData · GetInt4 · method · since 9.5.0.88` ```pascal function GetInt4(index: Integer;     littleEndian: Boolean): Integer; ``` Returns the value of the 32-bit signed integer stored in big-endian or little-endian byte ordering at the given index. ### BinData.GetString `Chilkat 11.7.0 · pascal · BinData · GetString · method · since 9.5.0.67` ```pascal function GetString(const charset: string): string; ``` Interprets the bytes according to `charset` and returns the string. The `charset` can be `utf-8`, `utf-16`, `ansi`, `iso-8859-*`, `windows-125*`, or any of the supported character encodings listed in the link below. Returns True for success, False for failure. See also: - [Chilkat Supported Character Encodings](http://cknotes.com/chilkat-charsets-character-encodings-supported/) ### BinData.GetTextChunk `Chilkat 11.7.0 · pascal · BinData · GetTextChunk · method · since 9.5.0.85` ```pascal function GetTextChunk(startIdx: Integer;     numBytes: Integer;     const charset: string): string; ``` Returns `numBytes` bytes starting at `startIdx`. The bytes are interpreted according to `charset` (for example, `utf-8`, `ansi`, `utf-16`, `windows-1252`, etc.) Returns True for success, False for failure. ### BinData.GetUInt2 `Chilkat 11.7.0 · pascal · BinData · GetUInt2 · method · since 9.5.0.88` ```pascal function GetUInt2(index: Integer;     littleEndian: Boolean): LongWord; ``` Returns the value of the 16-bit unsigned integer stored in big-endian or little-endian byte ordering at the given index. ### BinData.GetUInt4 `Chilkat 11.7.0 · pascal · BinData · GetUInt4 · method · since 9.5.0.88` ```pascal function GetUInt4(index: Integer;     littleEndian: Boolean): LongWord; ``` Returns the value of the 32-bit unsigned integer stored in big-endian or little-endian byte ordering at the given index. ### BinData.IsValidUtf8 `Chilkat 11.7.0 · pascal · BinData · IsValidUtf8 · method · since 10.1.0` ```pascal function IsValidUtf8: Boolean; ``` Returns `True` if this object contains valid utf-8 byte sequences. Any invalid byte sequence that is not valid utf-8 will cause this function to return `False`. Returns True for success, False for failure. ### BinData.LoadEncoded `Chilkat 11.7.0 · pascal · BinData · LoadEncoded · method · since 9.5.0.51` ```pascal function LoadEncoded(const encData: string;     const encoding: string): Boolean; ``` Loads binary data from an encoded string, replacing the current contents, if any. The `encoding` may be `Base64`, `modBase64`, `base64Url`, `Base32`, `Base58`, `QP` (for quoted-printable), `URL` (for url-encoding), `Hex`, or any of the encodings found at [Chilkat Binary Encodings List](https://www.chilkatsoft.com/binary_encodings.asp). Returns True for success, False for failure. ### BinData.LoadFile `Chilkat 11.7.0 · pascal · BinData · LoadFile · method · since 9.5.0.51` ```pascal function LoadFile(const path: string): Boolean; ``` Loads data from a file. Returns True for success, False for failure. ### BinData.RemoveByteVal `Chilkat 11.7.0 · pascal · BinData · RemoveByteVal · method · since 9.5.0.90` ```pascal procedure RemoveByteVal(value: Integer); ``` Removes bytes having a specified value (0-255). For example, to remove all null bytes, pass 0 in `value`. ### BinData.RemoveChunk `Chilkat 11.7.0 · pascal · BinData · RemoveChunk · method · since 9.5.0.51` ```pascal function RemoveChunk(offset: Integer;     numBytes: Integer): Boolean; ``` Removes a chunk of bytes from the binary data. Returns True for success, False for failure. ### BinData.SecureClear `Chilkat 11.7.0 · pascal · BinData · SecureClear · method · since 9.5.0.67` ```pascal function SecureClear: Boolean; ``` Securely clears the contents by writing 0 bytes to the memory prior to deallocating the internal memory. Returns True for success, False for failure. ### BinData.WriteAppendFile `Chilkat 11.7.0 · pascal · BinData · WriteAppendFile · method · since 9.5.0.91` ```pascal function WriteAppendFile(const path: string): Boolean; ``` Appends the contents of this object to a file. Returns True for success, False for failure. ### BinData.WriteFile `Chilkat 11.7.0 · pascal · BinData · WriteFile · method · since 9.5.0.62` ```pascal function WriteFile(const path: string): Boolean; ``` Writes the contents to a file. Returns True for success, False for failure. ## Related classes [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/StringBuilder.md)