Transformer SDK For C  7.1.19.190859-2c068f14
Formatting API

Data Structures

struct  _formathandler
 Structure used to generate chains of format handlers. More...
 
struct  format_interface_t
 Interface returned to other modules which require integration with the pipeline. More...
 

Typedefs

typedef struct _formathandler formathandler_t
 Opaque handle to the format handler. More...
 

Detailed Description

The format module exposes formatting capability to modules. This permits the centralisation of all formatting functionality.

The format module permits chains of formatters to built with the output of one formatter being the input to the next in the chain.

It should be loaded into the transformer using the following configuration option in transformer.conf:

add-module format
Examples
format_interface_t *format_interface;
...
formathandler_t *format = format_interface->format_parse("strip:where=start,where=end;align:width=10,align=centre;");
char *ret = format_interface->format_apply(format," HELLO ");
assert(strcmp(ret," HELLO ") == 0);
...
free(ret);

This example shows a sample usage of the format API and demonstrates chaining of format handlers together to perform a complex formatting action, in this case removing white space from the start and end of the string, and then placing the stripped text in the centre of a window 10 characters wide.

Alignment

The align:; formatter performs alignment within a given window size

NameDefaultDesc
width-Width of the window in which to perform the alignment</tr
align-Alignment: "centre","left", "right"
Timestamp formatter

The date:; formatter permits the transformation of timestamps between various formats as well as being able to format the current time into any timestamp format

No timezone conversions take place however.

NameDefaultDesc
from-The format of the incoming timestamp. If none is given then the current time is taken.
to-The format for the outgoing timestamp

Example

The format below will transform: "27.06.2005 13:18:01" into "13:18"

date:from=%d.%m.%Y %H:%M:%S,to=%H:%M;

The following conversion formats should be supported:

Format stringExplanation
%a

is replaced by the locale's abbreviated weekday name.

%Ais replaced by the locale's full weekday name.
%bis replaced by the locale's abbreviated month name.
%Bis replaced by the locale's full month name.
%cis replaced by the locale's appropriate date and time representation.
%Cis replaced by the century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99].
%dis replaced by the day of the month as a decimal number [01,31].
%Dsame as m/d/y.
%eis replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space.
%hsame as b.
%His replaced by the hour (24-hour clock) as a decimal number [00,23].
%Iis replaced by the hour (12-hour clock) as a decimal number [01,12].
%jis replaced by the day of the year as a decimal number [001,366].
%mis replaced by the month as a decimal number [01,12].
%Mis replaced by the minute as a decimal number [00,59].
%pis replaced by the locale's equivalent of either a.m. or p.m.
%ris replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to I:M:S p.
%Ris replaced by the time in 24 hour notation (H:M).
%scan be used to parse the time in seconds since the epoch.
%Sis replaced by the second as a decimal number [00,61].
%tis replaced by a tab character.
%Tis replaced by the time (H:M:S).
%Uis replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
%Vis replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1.
%wis replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.
%Wis replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
%xis replaced by the locale's appropriate date representation.
%Xis replaced by the locale's appropriate time representation.
%yis replaced by the year without century as a decimal number [00,99].
%Yis replaced by the year with century as a decimal number.
%Zis replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.
%fis replaced by the milliseconds (up to 3 digits) in the second with leading 0s.
%qis replaced by the microseconds (up to 6 digits) in the second with leading 0s.
%nis replaced by the nanoseconds (up to 9 digits) in the second with leading 0s.
%Nis replaced with the Refinitiv High precision fractional seconds (000:000:000).
%Jis replaced with a timestamp representing milliseconds since epoch.
%%is replaced by %.

If a conversion specification does not correspond to any of the above, the behaviour is undefined.

Decimal place formatter

The dp:; formatter formats numbers to a defined number of decimal places

Arguments

NameDefaultDesc
precision-Number of decimal places to convert the result to (must be defined)
places-An alias for precision
modetruncationMode of operation: "round" or "truncation"

Example

The following format will format a numerical value to 5 decimal places, performing rounding to calculate the last decimal place:

dp:places=5,mode=round;

It's recommended that the dp: formatter is combined with the frac: formatter to ensure that the number is decimal before calculating the decimal places, for example:

frac:;dp:places=5,mode=round;
Fraction formatter

The frac:; formatter resolves fractions into decimals.

Arguments

NameDefaultDesc
precision10Number of decimal places to convert the result to
Significant figures formatter

The sigfig:; formatter formats numbers to a defined number of figures

Arguments

NameDefaultDesc
places-Number of significant figures to convert the result to (must be defined)

Example

The following format will format a numerical value to 4 signficant figures

sigfig:places=4;

It's recommended that the dp: formatter is combined with the frac: formatter to ensure that the number is decimal before calculating the decimal places, for example:

frac:;sigfig:places=4;

will format an input of "1" to an output value of "1.000"

The noop formatter

The str:; formatter leaves the string unchanged.

Arguments

None

The space stripping format

The stripspace:; formatter can remove space from the start or the end of a string

NameDefaultDesc
where-Where to strip the space from: "start" or "end". Multiple where parameters can be specified in a format string.
at-Synonym for "where"
minlen-The minimum length of the string after white space has been removed. If it's less than this then the formatter fails.
Uppercase formatter

The strupper:; formatter permits the transformation of string to uppercase. Characters which aren't lower case will be ignored.

Arguments

None

Lowercase formatter

The strlower:; formatter permits the transformation of string to lowercase. Characters which aren't upper case will be ignored.

Arguments

None

The zero replacement formatter

The zero:; formatter can replace non-numeric values or empty strings with a 0.

NameDefaultDesc
when-When to replace the value with a "0", can be either "empty" or "nonnumeric". Multiple when parameters may be specified within a format string.
if-Synomym for "when"

Care should be taken when using the zero:; formatter, fractions will not be recognised as a number and as such will be replaced with a zero. Thus when constructing formatter chains, it's recommended that the frac: formatter is earlier in the chain than zero:

Typedef Documentation

Opaque handle to the format handler.


Generated on Fri Jan 12 2024 14:49:12 for Transformer SDK For C