Promotic

PmFormat object formatting string

Format of conversion between value and string.

Parameters of a text string are in the KeyVal format, which is filled from the value of of the sFormat parameter of the SetFormat or CreatePmFormat method.

Keys common to all types:

Type:xx; - Value type. For example "Type:Float;".
Float (default) - real number
Int - integer
Bool - logical value (1/0)
String - text string
DateTime - Date and time
TimeSpan - Time span
Len:nn - The total number of characters excluding LTxt and RTxt
for numeric values including Sign, DSep, Group. For example "Len:6;".
See: Examples for Float type.
-1 (default) - unlimited, for Scan find end of a number
n - defined number of characters
IfShort:nn - What to do if the value is shorter than Len. For example "Len:4;IfShort:2;".
0 (default) - do nothing
1 - add space character from the left
2 - add space character from the right
7 - only for numeric values: add zeros from the left between the sign and the first digit (for non-numeric values like IfShort:1)
IfLong:nn - What to do if the value is longer than Len. For example "Len:4;IfLong:2;".
See: Examples for Float type.
0 (default) - do nothing, it means keep long
1 - crop from the left to length Len
2 - crop from the right to length Len
4 - fill with the character specified in IfLongPar to the length of Len
5 - replace with text defined in IfLongPar
7 - only for numeric values: scientific format max to IfLongPar (for non-numeric values like IfLong:2)
IfLongPar:ss - Specifies the character(s) to fill in for the IfLong parameter. For example "Len:4;IfLong:5;IfLongPar:MyErr;".
ss - Character(s)
for IfLong:4; - the character to fill with (default="", uses the asterisk "*" to fill)
for IfLong:5; - replacement text (default="")
LTxt:ss - Text to the left of the value For example "LTxt:Value ;".
See: The usage of Radix for formatting numbers into hexadecimal form.
RTxt:ss - Text to the right of the value (for Scan there must not be RTxt inside the value). For example "RTxt:°C;".
See: Examples for Float type.
Case:nn - Conversion to upper/lower case characters (characters in LTxt and RTxt are not converted). For example "Case:2;".
See: Examples for String type.
0 (default) - keep unchanged
1 - UpperCase - upper case characters
2 - LowerCase - lower case characters

Keys common to all numbers:

Radix:nn - Other numeric system (for Int type). For example "Type:Int;Radix:16;".
See: The usage of Radix for formatting numbers into hexadecimal form.
2 - binary
8 - octal
10 (default) - decimal
16 - in hexadecimal. Hex characters will be small but can be enlarged using Case:1;
Sign:nn - How to display the plus sign. For example "Sign:1;".
See: Examples for Float type.
0 (default) - do not display (display only "-")
1 - display "+" (if zero, then space)
2 - display " " (space)
Group:nn - Grouping groups of numbers into triples. For example "Group:1;".
See: Examples for Float type.
0 (default) - no grouping
1 - group to the left of the decimal separator (thousands)
2 - group to the right of the decimal separator (thousandths)
3 - group to the left and to the right of the decimal separator (thousands and thousandths)
GroupSep:nn - Separator between groups For example "Group:1;GroupSep:2;".
0 (default) - space
1 - dot
2 - comma
DLen:nn - Number of characters to the right of the decimal separator. For example "DLen:3;".
See: Examples for Float type.
-1 (default) - unlimited (filling up to the number specified in Len, but if Len=-1 then DLen:3)
n - integer including Group separator (3=default)
DSep:nn - Decimal dot type (relevant only if DLen!=0). For example "DSep:1;".
0 (default) - period "."
1 - comma ","
DZero:nn - Zeros to the right of the number (relevant only if DLen!=0). For example "DZero:1;".
0 (default) - keep the zeroes
1 - replace zeroes by spaces
2 - Optimize (delete zeros and eventually also the decimal separator)

Keys for DateTime:

Fmt:ss - Time format see: Formatting rule for date and time (DateTime). For example "Type:DateTime;Fmt:%Y.%m.%d %H:%M:%S.%T;".
See: Examples for DateTime type.

Keys for TimeSpan

FmtType:nn (optional) - Time span format type. For example "Type:TimeSpan;FmtType:10;".
See: Examples for TimeSpan type.
0 (default) - User-defined format of time span defined by formatting string. See Fmt key.
10 - System format of time span. The values of time span items used are listed along with a letter indicating the item type. Items with a null value are not shown.
Syntax: [-][Nd][Nh][Nm][Ns][Nt], where N is number and:
d - Number of days. For example 2d means 2 days or 1.5d means 36 hours.
h - Number of hours. For example 2h means 2 hours or 1.5h means 90 minutes.
m - Number of minutes. For example 2m means 2 minutes or 1.5m means 90 seconds.
s - Number of seconds. For example 2s means 2 seconds or 1.5s means 1500 miliseconds.
t - Number of miliseconds. For example 10t means 10 miliseconds or 500t means 500 miliseconds.
Fmt:ss - User-defined format of time span see: Formatting rule for time span (TimeSpan). Only for FmtType is 0. For example "Type:TimeSpan;FmtType:0;Fmt:%*N%*d-%H:%M:%S.%T;".
See: Examples for TimeSpan type.

Other keys:

FmtC:ss - C language conversion format (obsolete way kept to maintain compatibility). Description see: C language formatting rule. For example "FmtC:%5.2f;".
See: The usage of FmtC for C language formatting:.

Examples for Float type

Combination of keys RTxt and DLen:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Float;RTxt: %;DLen:2;");
var sVal = oFmt.Format(90.845);   // sVal = "90.84 %"
The usage of Group to split the number into digits triples:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Len:12;DLen:7;IfLong:2;Group:3;");
var sVal = oFmt.Format(-1234567.123456);   // sVal = "-1 234 567.1"
The usage of Sign to align plus and minus values:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Sign:2;");
var sVal;
sVal = oFmt.Format(1235.67);   // sVal = " 1235.670"
sVal = oFmt.Format(-1235.67);   // sVal = "-1235.670"

Examples for Int type

The usage of Radix for formatting numbers into hexadecimal form:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Int;Radix:16;LTxt:0x;Case:1;");
var sVal = oFmt.Format(10.58);   // sVal = "0xB"
var nVal = oFmt.Scan(sVal);   // nVal = 11
The usage of Radix for formatting numbers into octal form:
JavaScriptVBScriptSelect and copy to clipboard

oFmt = Pm.CreatePmFormat("Type:Int;Radix:8;LTxt:0o;");
sVal = oFmt.Format(10.58);   // sVal = "0o13"
nVal = oFmt.Scan(sVal);   // nVal = 11
The usage of Radix for formatting numbers into binary form:
JavaScriptVBScriptSelect and copy to clipboard

oFmt = Pm.CreatePmFormat("Type:Int;Radix:2;LTxt:0b;");
sVal = oFmt.Format(3.4);   // sVal = "0b11"
nVal = oFmt.Scan(sVal);   // nVal = 3

Examples for Bool type

Example1:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Bool;");
var sVal;
sVal = oFmt.Format(3.14);   // sVal = "1"
sVal = oFmt.Format(0);   // sVal = "0"
Example2:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:Bool;LTxt:Ln;RTxt:V;");
var sVal;
sVal = oFmt.Format(true);   // sVal = "Ln1V"
sVal = oFmt.Format(false);   // sVal = "Ln0V"

Examples for String type

Example1:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:String;LTxt:x;RTxt:q;Case:1;");
var sVal = oFmt.Format("aBcD");   // sVal = "xABCDq"
Example2:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("Type:String;LTxt:X_;RTxt:_Q;Len:6;IfLong:2;");
var sVal = oFmt.Format("abcdefgh");   // sVal = "X_abcdef_Q"

Examples for DateTime type

Example:
JavaScriptVBScriptSelect and copy to clipboard

var t = Pm.CreateDate(2023, 2, 13, 4, 15, 6, 789);

var oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%2d.%2m.%4Y %2H:%2M:%2S.%T");
var sVal = oFmt.Format(t);   // sVal = "13.02.2023 04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%2d.%2m.%4Y %2H:%2M:%2S");
sVal = oFmt.Format(t);   // sVal = "13.02.2023 04:15:06"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%4Y.%2d.%2m %2H:%2M:%2S");
sVal = oFmt.Format(t);   // sVal = "2023.13.02 04:15:06"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%*d.%*m.%*Y %*H:%*M:%*S.%T");
sVal = oFmt.Format(t);   // sVal = "13.2.2023 4:15:6.789"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%*Y.%*m.%*d");
sVal = oFmt.Format(t);   // sVal = "2023.13.2"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%*H:%*M:%*S");
sVal = oFmt.Format(t);   // sVal = "4:15:6"

oFmt = Pm.CreatePmFormat("Type:DateTime;Fmt:%Y%m%d%H%M%S");
sVal = oFmt.Format(t);   // sVal = "20231302041506"

Examples for TimeSpan type

Example:
JavaScriptVBScriptSelect and copy to clipboard

var t = Pm.CreateDate(0, 0, 53, 4, 15, 6, 789);

var oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%2d %2H:%2M:%2S.%T");
var sVal = oFmt.Format(t);   // sVal = "53 04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*d %*H:%*M:%*S");
sVal = oFmt.Format(t);   // sVal = "53 4:15:6"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%d%m%Y%H%M%S%T");
sVal = oFmt.Format(t);   // sVal = "13022023041506789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%N%2d %2H:%2M:%2S.%T");
sVal = oFmt.Format(-t);   // sVal = "-53 04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;FmtType:10");
sVal = oFmt.Format(-t);   // sVal = "-53d4h15m6s789t"

t = Pm.CreateDate(0, 0, 1053, 4, 15, 6, 789);

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%d-%H:%M:%S.%T");
sVal = oFmt.Format(t);   // sVal = "1053-04:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%H:%M:%S.%T");
sVal = oFmt.Format(t);   // sVal = "25276:15:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%M:%S.%T");
sVal = oFmt.Format(t);   // sVal = "1516575:06.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%S.%T");
sVal = oFmt.Format(t);   // sVal = "90994506.789"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;FmtType:10");
sVal = oFmt.Format(t);   // sVal = "1053d4h15m6s789t"

t = Pm.CreateDate(0, 0, 0, 1, 30, 0, 0);

oFmt = Pm.CreatePmFormat("Type:TimeSpan;Fmt:%*N%d-%H:%M:%S.%T");
sVal = oFmt.Format(t);   // sVal = "0-01:30:00.000"

oFmt = Pm.CreatePmFormat("Type:TimeSpan;FmtType:10");
sVal = oFmt.Format(t);   // sVal = "1h30m"

The usage of FmtC for C language formatting:

Example:
JavaScriptVBScriptSelect and copy to clipboard

var oFmt = Pm.CreatePmFormat("FmtC:%d\"");
var sVal = oFmt.Format(1);   // sVal = "1"

oFmt = Pm.CreatePmFormat("FmtC:x%dq");
sVal = oFmt.Format(1);   // sVal = "x1q"

oFmt = Pm.CreatePmFormat("FmtC:%f");
sVal = oFmt.Format(12.3456789);   // sVal = "12.3456789"

oFmt = Pm.CreatePmFormat("FmtC:%13.2f");
sVal = oFmt.Format(123456789.123456789);   // sVal = " 123456789.12"

oFmt = Pm.CreatePmFormat("FmtC:%x");
sVal = oFmt.Format(255);   // sVal = "ff"

oFmt = Pm.CreatePmFormat("FmtC:%03X");
sVal = oFmt.Format(10.58);   // sVal = "00B"

oFmt = Pm.CreatePmFormat("FmtC:n=%03X");
sVal = oFmt.Format(10.58);   // sVal = "n=00B"
See also:
- Pm.CreatePmFormat (method)
- SetFormat
- Formatting rule for date and time (DateTime)
- Formatting rule for time span (TimeSpan)
History:
Pm9.00.26: New option FmtType allows entering the system format for TimeSpan.
Pm9.00.17: Created
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r.o.