Start » Filter Reference » System » Binary Data » WriteStringToBuffer

WriteStringToBuffer


Module: FoundationLite

Converts string value into specified binary representation and writes it to a byte buffer.

Name Type Range Description
Input value
inBuffer ByteBuffer Initial buffer to be expanded
Input value
inOffset Integer* 0 - Write destination position
Input value
inValue String Value to be written
Input value
inFormat StringBinaryFormat Binary serialization format responsible for handling string length
Input value
inTextEncoding StringEncodingFormat Binary character encoding format
Input value
inMaxLength Integer 0 - 536870911 Maximum length of resulting string in code units
Output value
outBuffer ByteBuffer Resulting data

Description

This filter is intended for generating a raw binary data in the ByteBuffer by writing a properly serialized text data into it.

Resulting ByteBuffer data on the outBuffer output is created by expanding data from buffer on the inBuffer input. Data is written starting at the position specified by the inOffset input (in bytes). When written data spans beyond the end of the input buffer the resulting buffer length is expanded (event when inOffset points beyond the end of the input buffer). When the inOffset input is set to Auto data is written at the end of the input buffer.

There are two main aspects of formatting the binary representation of a text data. First is a character encoding, that determines how characters from different alphabets and languages are substituted into numeric codes and how those numeric codes are stored. Second is marking a resulting string length. Length of a string is always considered in context of character-encoded text representation (in resulting binary data). Length can be also measured differently depending on the selected character encoding.

inTextEncoding input is selecting a required character encoding:

  • ASCII - basic ASCII encoding with single byte per character, only the range of characters in lower half (0...127) are allowed. Length in this encoding is measured in bytes.
  • UTF8 - Unicode UTF-8 encoding (without BOM), variable byte length of character. Length in this encoding is measured in bytes.
  • UTF16LE - Unicode UTF-16 Little-Endian encoding, two bytes (16bit) per character with possible surrogate pairs. Length in this encoding is measured in 16-bit code points (two bytes per unit).
  • UTF16BE - Unicode UTF-16 Big-Endian encoding, two bytes (16bit) per character with possible surrogate pairs. Length in this encoding is measured in 16-bit code points (two bytes per unit).
  • ANSI - default encoding (ANSI variant in Microsoft Windows) of local system is used. Actual encoding depends on local system regional settings. Length of a single character may be a single byte, but for some regions variable length of a character is possible (a multi-byte strings). Length in this encoding is measured in bytes.
  • OEM - default encoding of local system, similarly to ANSI, but OEM variant in Microsoft Windows is used.

It is strongly advised to not use ANSI and OEM encodings whenever possible and use one of the Unicode encodings instead. Those options are provided only for compatibility with older systems and data formats.

inFormat input is selecting a general string representation:

  • VariableLength_Raw - variable length of string field without any additional prefixes and suffixes (just raw text in its character encoding is stored in the buffer).
  • VariableLength_NullTerminated - variable length of string field with null termination character at its end (size of a null terminator is appropriate to the specified character encoding).
  • VariableLength_8BitPrefix - variable length of string field with 8-bit prefix specifying the length of the encoded string. Resulting string length must not be longer than 255.
  • VariableLength_16BitLEPrefix - variable length of string field with 16-bit little endian prefix specifying the length of the encoded string. Resulting string length must not be longer than 65535.
  • VariableLength_32BitLEPrefix - variable length of string field with 32-bit little endian prefix specifying the length of the encoded string.
  • VariableLength_16BitBEPrefix - variable length of string field with 16-bit big endian prefix specifying the length of the encoded string. Resulting string length must not be longer than 65535.
  • VariableLength_32BitBEPrefix - variable length of string field with 32-bit big endian prefix specifying the length of the encoded string.
  • VariableLength_LEB128Prefix - variable length of string field with variable length prefix stored using LEB128 coding (sometimes referred also as UTF-7 coding).
  • FixedLength_Raw - resulting data field is always of fixed length, specified by the inMaxLength input (in units determined by the character encoding), when the actual text is shorter than the specified length it is padded with null codes.
  • FixedLength_NullTerminated - resulting data field is always of fixed length, specified by the inMaxLength input (in units determined by the character encoding), when the actual text is shorter than the specified length it is padded with null codes, at least one null code must be always padded at the end of the text.

inMaxLength input specifies the maximum allowed length of the resulting string (after converting to the requested character encoding and including eventual null terminator). When the actual text length is greater a DomainError will be raised. This input also specifies the length of the data field when using fixed-length formats.

When the source string contains one or more characters that cannot be represented in the selected character encoding a DomainError is raised.

Errors

This filter can throw an exception to report error. Read how to deal with errors in Error Handling.

List of possible exceptions:

Error type Description
DomainError ANSI and OEM encodings are not supported on Linux.
DomainError Input string is too large for specified binary format.
Length of the string on the inValue input is too big to be stored using selected binary format of the length prefix.
DomainError Input string length exceeds inMaxLength value.
Length of the string to be stored in output buffer (after text encoding conversion and including null terminator) is larger that the value on the inMaxLength input.
DomainError Not supported string binary format.
DomainError Not supported text encoding format.
DomainError String contains characters not valid in the ASCII encoding.
ASCII string encoding is selected and the string on the inValue input contains character or characters from outside of the 7-bit ASCII range (0...127).
DomainError String contains characters not valid in the current encoding.
ANSI string encoding is selected and the string on the inValue input contains character or characters that cannot be represented in coding of current system regional settings.
DomainError String is too large to be written into the byte buffer.
IoError Resulting buffer size is too large.
RuntimeError Multi-byte string conversion error.
SystemError Requested text encoding is not available in local system.

Complexity Level

This filter is available on Basic Complexity Level.

Filter Group

This filter is member of WriteToBuffer filter group.

See Also

  • WriteStringToBuffer – Converts string value into specified binary representation and writes it to a byte buffer.