11.49 sprintf()

This function is used to format a string according to a given format string. It is similar to the functions available in the C library.

Definition

string sprintf
(
      string   Format     input,
      anyvalue Argument1  input
  { , anyvalue Argument2  input }
      ...
  { , anyvalue Argument15 input }
)

Parameters

string Format input

Format describes the formatting of the output string. The individual formats follow, to a large extent, the notation in ANSI-C. However, some restrictions are necessary. The IDM is not able to check whether the format string is correct. Incorrect specifications in the arguments for the function cause errors.

The data types of the ISA Dialog Managers will be output exclusively via %s (plus possible formats). The data types integer and pointer are exceptions; they are output via numerical format types. The possible values for the ISA Dialog Manager are described below in the section “Syntax of the Format String”.

anyvalue Argument1 input
anyvalue Argument2 input
…
anyvalue Argument15 input

These (optional) parameters have to be specified according to the format string.

They are used for the corresponding format characters in the output string.

Return value

The return value is a string corresponding to the input format Format. In case of errors an empty string will be returned.

Syntax of the Format String

The first character in a format is %. The following term describes the syntax for a format of the IDM sprintf():

%[argument$] [flags] [width] [.precision] type
%[argument$] [flags] [width] [.precision] ([singular],[plural])

The individual elements of the term are defined as follows:

argument

This parameter controls the order of the given parameters. The given arguments usually keep their order. However it is also possible to use any argument (i.e. not following the given order), provided that the relevant argument is accessed via its position (number). It is thus possible to use parameters several times.

Example 

text DateFormat "Date"
{
  0: "%02d.%02d.%04d";        // German
  1: "%2$02d/%1$02d/%3$04d";  // British
}
...
sprintf(DateFormat,7,9,1965);
// variant 0:"07.09.1965"
// variant 1:"09/07/1965"

flags

IDM supports the following flags: +, -, 0, #

The flags + and - define whether the string is to be formatted left-aligned (-) or right-aligned (+), i.e. whether necessary blanks are to be inserted at the beginning or at the end of the string.

It is also possible to specify 0 for the output of numbers. The strings will thus be filled with zeros. If # is specified, the hexadecimal number format will be 0x or 0X.

width

This parameter controls the minimal number of characters to be output. If less characters than specified are output, blanks will be inserted at the beginning or at the end of the string. This is controlled by the %s parameter. If the string is longer than the specified field length all characters will be output.

This parameter may also contain a star (*). This means that the following argument in the argument list will be used to define the output size.

Examples

sprintf("%0*x",4,255) is interpreted as sprintf("%04x",255)

sprintf("%s %*s","Hallo",40,"Welt") is interpreted as sprintf("%s %40s","Hallo","Welt")

.precision

This parameter controls the length of a string to be output. The first character is always a dot . and will lead, in contrast to the parameter width, to a clipping of the string.

Examples 

sprintf("%.5s", "123456789")  // Result "12345"
sprintf("%.*s", 2, "1234")    // Result "12"

type

This parameter defines the type of the relevant argument. The following types are possible in the IDM:

Type

Output Format

d

number with prefix

u

number without prefix

b

number in binary format

o

number in octal format

x

number in hexadecimal format, using abcdef

X

number in hexadecimal format, using ABCDEF

c

output of a character

s

output of a string

For the use in IDM the formats for strings (%s) and numbers (%d, %u, %x, %o) have been expanded. The behavior is described in the following table. [numeric] is used instead of d, x, X, b or u.

Data Type

Control via %

Result

void

%s

%[numeric]

empty string

ERROR

string

%s

otherwise

input string

ERROR

text

%s

%[numeric

relevant string

textid in number format

object

%s

%[numeric

name of object

DM_ID in number format

pointer

%s

%[numeric

ERROR

address of pointers in number format

event

%s

%[numeric

name of event

number of event in number format

enum

%s

%[numeric

name of enumeration

number of enumeration in number format

attribute

%s

%[numeric

%name of attribute

number of attribute in number format

method

%s

%[numeric

name of method

number of method in number format

integer

%s

%[numeric

ERROR

number in number format

index

%s

%[numeric

both values of index

ERROR

boolean

%s

%[numeric

output of true or false as string

output of 0 (false) or 1 in number format

class

%s

%[numeric

name of class

internal number of class in number format

datatype

%s

%[numeric

data type as string

data type in number format

Pluralism

This parameter is used to control an output that depends on the value of the argument. You can select the given singular value or plural value. The values must always be indicated in square brackets, separated by |. The given value for the relevant part of the string in the parameter range determines the value to be displayed.

The following is valid:

1
singular value
<> 1
plural value

Example 

sprintf("%d %[house|houses]", 1);  // "1 house"
sprintf("%d %[house|houses]", 2);  // "2 houses"
sprintf("%d %[house|houses]", 0);  // "0 houses"

Summary Examples

!! output of a hexadecimal number in a statictext.
dialog HexOut

window W
{
  child statictext HexOutput { }
}

on dialog start
{
  variable integer Answer := 42;
  variable string S;
  S := sprintf("This is a hex number: %X", Answer);
  W.HexOutput.text := S;
}
!! Output of a date in a statictext.
!!  Variants are used to support country-specific features
!! (order of day, month and year).
dialog VariantDate
text DateFormat "DateFormat"
{
  0: "%02d.%02d.%04d";
  1: "%2$02d/%1$02d/3$04d";
}

window W
{
  child statictext Date{ }
}

on dialog start
{
  variable integer Day := 7;
  variable integer Month := 9;
  variable integer Year := 1965;
  variable string S;
  S := sprintf(DateFormat,Day,Month,Year);
  !! language variant 0: S = "07.09.1965"
  !! language variant 1: S = "09/07/1965"
  W.Date.text := S;
}
!! Example for the use of singular and plural values.
dialog SingularPlural

on dialog start
{
  sprintf("%d %[house|houses]", 1);  // "1 house"
  sprintf("%d %[house|houses]", 2);  // "2 houses"
  sprintf("%d %[house|houses]", 0);  // "0 houses"

  print sprintf("%3d file%[|s] copied", 1);
  // Result:  1 file copied
  print sprintf("%3d file%[|s] copied", 34);
  // Result: 34 files copied
  print sprintf("%3d file%[|s] copied", 0);
  // Result:  0 files copied
}
!! This dialog shows specific features of sprintf() in the IDM.
dialog DMInterna

window W1 { }

on dialog start
{
  print sprintf("Attribute %s has number %1$d", W1.visible);
  // Result: Attribute .visible has number 1
 
  print sprintf("Window %s has DM_ID %d", W1, W1);
  // Result: Window W1 has DM_ID 5
 
  print sprintf("Index %s", [1,2]);
  // Result: Index [1,2]
}