WriteStringToBuffer

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.

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

List of possible exceptions:

This filter is available on Basic Complexity Level.

This filter is member of WriteToBuffer filter group.

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