Function Reference
This page lists all the built-in functions available for templates.
I/O Functions
void BigEndian() void LittleEndian()
Select big-endian or little-endian mode. You can switch back and forth within the same template to declare fields with different byte orders.
Little-endian mode is selected by default.
bool IsBigEndian() bool IsLittleEndian()
Check whether big-endian or little-endian mode is selected.
bool FEof()
Returns true if the read position is at the end of the file.
int64_t FileSize()
Returns the length of the file in bytes.
void FSeek(int64_t offset)
Moves the read position relative to the start of the file.
The read position is used for reading data and defining new variables.
void FSkip(int64_t offset)
Moves the read position relative to its current offset.
int64_t FTell()
Returns the current read position in the file.
int8_t ReadI8(int64_t offset = FTell()) uint8_t ReadU8(int64_t offset = FTell()) int16_t ReadI16(int64_t offset = FTell()) uint16_t ReadU16(int64_t offset = FTell()) int32_t ReadI32(int64_t offset = FTell()) uint32_t ReadU32(int64_t offset = FTell()) int64_t ReadI64(int64_t offset = FTell()) uint64_t ReadU64(int64_t offset = FTell()) float ReadFloat(float offset = FTell()) double ReadDouble(double offset = FTell())
The ReadXXX() functions read a value from the document and return it. The offset parameter is optional and defaults to the current read position.
Calling any of these functions with an invalid offset will result in a template error.
string ReadString(int64_t offset = FTell(), uint8_t term_char = '\0', int64_t max_length = -1)
The ReadString() function reads a variable-length string from the document and returns it.
The function will read from the given offset until it reaches a terminator (defined by term_char) or has read max_length bytes. If max_length is negative, only a string terminator will end the string. If the end of the file is reached before either of these conditions is met, a template error will be raised.
int64_t OffsetOf(any_variable_type variable)
The OffsetOf() function returns the offset of the given variable in the file. Attempting to use this function with a local (non-file) variable will raise a template error.
void Printf(string format, ...)
Writes a message to the application console. The message will also be shown in the output window if the template encounters an error.
string SPrintf(string format, ...)
Creates a string from a printf-style format and parameters.
void Error(string format, ...)
Aborts template execution with the given error message, for example because of an error or inconsistency detected in the file.
Array Functions
int64_t ArrayLength(any array type array)
Returns the number of elements in the given array.
void ArrayResize(any_array_type array, int64_t num_elements, <struct arguments>)
The ArrayResize() function changes the size of the given array. Any new elements will be initialised to their default values and any removed elements will be erased. If the array elements are a struct type, <struct arguments> are passed through as the arguments to the new struct elements.
This function can be called to incrementally increase the size of an array being read from the document, but not if any variables have been defined after the array.
void ArrayExtend(any_array_type array, int64_t num_elements = 1, <struct arguments>)
Equivalent to ArrayResize(array, ArrayLength(array) + num_elements).
void ArrayPush(any_array_type array, array_value_type value)
Adds an element to the end of an array. The value type must be correct for the array and this function can only be used on local variables.
array_value_type ArrayPop(any_array_type array)
Removes and returns the last element from the array. This function can only be used on local variables, calling it on an empty array will raise a template error.
const int64_t ArrayIndex
Global variable that returns the current array index when expanding arrays of structs. For example, the following template would process a file containing a number of records, then the sizes of all those records, then the records themselves:
uint32_t num_records;
uint32_t record_sizes[num_records];
struct Record
{
unsigned char data[ record_sizes[ArrayIndex] ];
};
struct Record records[num_records];
Attempting to access the ArrayIndex variable when not in a struct that is being used as an array element will abort the template execution with an error.
String Functions
int64_t StringLengthBytes(string s)
Returns the number of bytes in the string.
Metadata Functions
void SetComment(int64_t offset, int64_t length, string text)
Sets a comment on a range of bytes in the document.