Package com.chilkatsoft.chilkat2

Class BinData

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.BinData
All Implemented Interfaces:
AutoCloseable
public class BinData extends ChilkatObject
<section class="bindata-summary">

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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Summary

    Constructors
    Constructor
    Description
    BinData()
    Creates a new BinData object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    appendBd​(BinData binData)
    Appends the contents of another BinData to this object.
    void
    appendBom​(String charset)
    Appends the appropriate BOM (byte order mark), also known as a preamble, for the given charset.
    void
    appendByte​(int byteValue)
    Appends a single byte.
    void
    appendCountedString​(int numCountBytes, boolean bigEndian, String str, String charset)
    Appends a byte count followed by the string in the desired character encoding, such as utf-8.
    void
    appendData​(byte[] data)
    Appends binary data to the current contents.
    void
    appendEncoded​(String encData, String encoding)
    Appends encoded binary data to the current data.
    void
    appendEncodedSb​(StringBuilder sb, String encoding)
    Decodes the contents of sb and appends the decoded bytes to this object.
    void
    appendInt2​(int value, boolean littleEndian)
    Appends a 16-bit integer (2 bytes).
    void
    appendInt4​(int value, boolean littleEndian)
    Appends a 32-bit integer (4 bytes).
    void
    appendPadded​(String str, String charset, boolean padWithSpace, int fieldLen)
    Appends a string to this object, padded to the fieldLen with NULL or SPACE chars.
    void
    appendSb​(StringBuilder sb, String charset)
    Appends the contents of a StringBuilder to this object.
    void
    appendString​(String str, String charset)
    Appends a string to this object.
    void
    byteSwap​(int size)
    Does either 16-bit or 32-bit byte swapping of the entire contents.
    void
    charsetConvert​(String fromCharset, String toCharset, boolean allOrNone)
    This method converts the character encoding of an object's contents from one format to another, such as from Windows-1252 to UTF-8.
    void
    clear()
    Clears the contents.
    boolean
    contentsEqual​(BinData binData)
    Return true if the contents of this object equals the contents of binData.
    int
    findString​(String str, int startIdx, String charset)
    Return the index where the first occurrence of str is found.
    int
    getByte​(int index)
    Returns the value of the byte at the given index.
    byte[]
    getData()
    Retrieves the binary data contained within the object.
    byte[]
    getDataChunk​(int offset, int numBytes)
    Retrieves a chunk of the binary data contained within the object.
    String
    getEncoded​(String encoding)
    Retrieves the binary data as an encoded string.
    String
    getEncodedChunk​(int offset, int numBytes, String encoding)
    Retrieves a chunk of the binary data and returns it in encoded form.
    void
    getEncodedSb​(String encoding, StringBuilder sb)
    Writes the encoded data to a StringBuilder.
    String
    getHash​(String algorithm, String encoding)
    Returns the hash of the contents of this object.
    int
    getInt2​(int index, boolean littleEndian)
    Returns the value of the 16-bit signed integer stored in big-endian or little-endian byte ordering at the given index.
    int
    getInt4​(int index, boolean littleEndian)
    Returns the value of the 32-bit signed integer stored in big-endian or little-endian byte ordering at the given index.
    int
    getNumBytes()
    The number of bytes contained within the object.
    String
    getString​(String charset)
    Interprets the bytes according to charset and returns the string.
    String
    getTextChunk​(int startIdx, int numBytes, String charset)
    Returns numBytes bytes starting at startIdx.
    long
    getUInt2​(int index, boolean littleEndian)
    Returns the value of the 16-bit unsigned integer stored in big-endian or little-endian byte ordering at the given index.
    long
    getUInt4​(int index, boolean littleEndian)
    Returns the value of the 32-bit unsigned integer stored in big-endian or little-endian byte ordering at the given index.
    boolean
    isValidUtf8()
    Returns true if this object contains valid utf-8 byte sequences.
    void
    loadEncoded​(String encData, String encoding)
    Loads binary data from an encoded string, replacing the current contents, if any.
    void
    loadFile​(String path)
    Loads data from a file.
    void
    removeByteVal​(int value)
    Removes bytes having a specified value (0-255).
    void
    removeChunk​(int offset, int numBytes)
    Removes a chunk of bytes from the binary data.
    void
    secureClear()
    Securely clears the contents by writing 0 bytes to the memory prior to deallocating the internal memory.
    void
    writeAppendFile​(String path)
    Appends the contents of this object to a file.
    void
    writeFile​(String path)
    Writes the contents to a file.

    Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

    close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • BinData

      public BinData()
      Creates a new BinData object.

  • Method Details

    • getNumBytes

      public int getNumBytes()
      The number of bytes contained within the object.
      Returns:
      the value of the NumBytes property (read-only)

    • appendBd

      public void appendBd​(BinData binData)
      Appends the contents of another BinData to this object.
      Parameters:
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendBom

      public void appendBom​(String charset)
      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.
      Parameters:
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendByte

      public void appendByte​(int byteValue)
      Appends a single byte. The byteValue should be a value from 0 to 255.
      Parameters:
      byteValue - the byteValue argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendCountedString

      public void appendCountedString​(int numCountBytes, boolean bigEndian, String str, String charset)
      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.
      Parameters:
      numCountBytes - the numCountBytes argument
      bigEndian - the bigEndian argument
      str - the str argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendData

      public void appendData​(byte[] data)
      Appends binary data to the current contents.
      Parameters:
      data - the data argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendEncoded

      public void appendEncoded​(String encData, String encoding)
      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.
      Parameters:
      encData - the encData argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendEncodedSb

      public void appendEncodedSb​(StringBuilder sb, String encoding)
      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.
      Parameters:
      sb - the sb argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendInt2

      public void appendInt2​(int value, boolean littleEndian)
      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.
      Parameters:
      value - the value argument
      littleEndian - the littleEndian argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendInt4

      public void appendInt4​(int value, boolean littleEndian)
      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.
      Parameters:
      value - the value argument
      littleEndian - the littleEndian argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendPadded

      public void appendPadded​(String str, String charset, boolean padWithSpace, int fieldLen)
      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.

      Parameters:
      str - the str argument (not null)
      charset - the charset argument (not null)
      padWithSpace - the padWithSpace argument
      fieldLen - the fieldLen argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendSb

      public void appendSb​(StringBuilder sb, String charset)
      Appends the contents of a StringBuilder to this object.
      Parameters:
      sb - the sb argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendString

      public void appendString​(String str, String charset)
      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.)
      Parameters:
      str - the str argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • byteSwap

      public void byteSwap​(int size)
      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)
      Parameters:
      size - the size argument

    • charsetConvert

      public void charsetConvert​(String fromCharset, String toCharset, boolean allOrNone)
      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.
      Parameters:
      fromCharset - the fromCharset argument (not null)
      toCharset - the toCharset argument (not null)
      allOrNone - the allOrNone argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clear

      public void clear()
      Clears the contents.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • contentsEqual

      public boolean contentsEqual​(BinData binData)
      Return true if the contents of this object equals the contents of binData.
      Parameters:
      binData - the binData argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • findString

      public int findString​(String str, int startIdx, String charset)
      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.
      Parameters:
      str - the str argument (not null)
      startIdx - the startIdx argument
      charset - the charset argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getByte

      public int getByte​(int index)
      Returns the value of the byte at the given index. The returned value is an integer from 0 to 255.
      Parameters:
      index - the index argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getData

      public byte[] getData()
      Retrieves the binary data contained within the object.
      Returns:
      the bytes (an empty array when there are none)

    • getDataChunk

      public byte[] getDataChunk​(int offset, int numBytes)
      Retrieves a chunk of the binary data contained within the object.
      Parameters:
      offset - the offset argument
      numBytes - the numBytes argument
      Returns:
      the bytes (an empty array when there are none)

    • getEncoded

      public String getEncoded​(String encoding)
      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.
      Parameters:
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getEncodedChunk

      public String getEncodedChunk​(int offset, int numBytes, String encoding)
      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.
      Parameters:
      offset - the offset argument
      numBytes - the numBytes argument
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getEncodedSb

      public void getEncodedSb​(String encoding, StringBuilder sb)
      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.
      Parameters:
      encoding - the encoding argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getHash

      public String getHash​(String algorithm, String encoding)
      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.
      Parameters:
      algorithm - the algorithm argument (not null)
      encoding - the encoding argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getInt2

      public int getInt2​(int index, boolean littleEndian)
      Returns the value of the 16-bit signed integer stored in big-endian or little-endian byte ordering at the given index.
      Parameters:
      index - the index argument
      littleEndian - the littleEndian argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getInt4

      public int getInt4​(int index, boolean littleEndian)
      Returns the value of the 32-bit signed integer stored in big-endian or little-endian byte ordering at the given index.
      Parameters:
      index - the index argument
      littleEndian - the littleEndian argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getString

      public String getString​(String charset)
      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.
      Parameters:
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getTextChunk

      public String getTextChunk​(int startIdx, int numBytes, String charset)
      Returns numBytes bytes starting at startIdx. The bytes are interpreted according to charset (for example, utf-8, ansi, utf-16, windows-1252, etc.)
      Parameters:
      startIdx - the startIdx argument
      numBytes - the numBytes argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getUInt2

      public long getUInt2​(int index, boolean littleEndian)
      Returns the value of the 16-bit unsigned integer stored in big-endian or little-endian byte ordering at the given index.
      Parameters:
      index - the index argument
      littleEndian - the littleEndian argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getUInt4

      public long getUInt4​(int index, boolean littleEndian)
      Returns the value of the 32-bit unsigned integer stored in big-endian or little-endian byte ordering at the given index.
      Parameters:
      index - the index argument
      littleEndian - the littleEndian argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • isValidUtf8

      public boolean isValidUtf8()
      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:
      the result; this method never throws ChilkatException

    • loadEncoded

      public void loadEncoded​(String encData, String encoding)
      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.
      Parameters:
      encData - the encData argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadFile

      public void loadFile​(String path)
      Loads data from a file.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeByteVal

      public void removeByteVal​(int value)
      Removes bytes having a specified value (0-255). For example, to remove all null bytes, pass 0 in value.
      Parameters:
      value - the value argument

    • removeChunk

      public void removeChunk​(int offset, int numBytes)
      Removes a chunk of bytes from the binary data.
      Parameters:
      offset - the offset argument
      numBytes - the numBytes argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • secureClear

      public void secureClear()
      Securely clears the contents by writing 0 bytes to the memory prior to deallocating the internal memory.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeAppendFile

      public void writeAppendFile​(String path)
      Appends the contents of this object to a file.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • writeFile

      public void writeFile​(String path)
      Writes the contents to a file.
      Parameters:
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why