Utilities.Format Method

Applies to TestComplete 15.10, last modified on December 01, 2021
This method is obsolete. See the Remarks section below.

Description

The Utilities.Format method converts the items of the Args array to a string using the format specified by the Format parameter.

Declaration

Utilities.Format(Format, Args)

Format [in]    Required    String    
Args [in]    Required    Array    
Result String

Applies To

The method is applied to the following object:

Parameters

The method has the following parameters:

Format

The Format string includes the format specifiers, each of which has the following format:

% [index:] [-] [width] [. precision] type

  • % - Required. Indicates the beginning of the format specifier.
  • index - Optional. Specifies the array item to which the specifier will be applied (more below).
  • dash ( - ) - Optional. If you specify a dash, the resulting string will be aligned to the left. By default, the resulting string is aligned to the right.
  • width - Optional. Specifies the minimum length of the resulting string in characters. If the resulting string is shorter than width, the function adds spaces to it.
  • precision - Optional. Specifies the number of digits after the decimal point in floating-point values.
  • type - Required. Specifies the formatting type. You can use one of the following type characters:
Type Character Description
d Decimal format. Applied to integer values only. If the precision parameter is used, it indicates the total number of digits the resulting string must have. If the converted value has less string than precision, the function adds leading spaces to the resulting string.
u Unsigned format. Applied to signed and unsigned integer values. Similar to d, but the resulting string does not contain the sign.
x Hexadecimal format. The argument must be an integer value. The function converts it to a string of hexadecimal digits. No hexadecimal prefixes, such as 0x, &H or $, are added. The precision parameter, if it is used, specifies the total number of digits in the resulting string. If the value has fewer digits, the function adds leading zeros to the string.
s String. The argument must be a string. The precision parameter, if it is used, specifies the total number of character in the resulting string. If the string length exceeds precision, the string is truncated.
e Scientific format. The argument must be a floating-point value. It is converted to a string of the form -d.ddE+ddd. One digit is always before the decimal point. The exponent character (“E”) is always followed by the sign and three digits. The total number of digits in the output string is specified by the precision parameter. If it is not used, the default value of 15 is used.
f Floating point format. The argument must be a floating-point value. The function converts this value to a string of the form -ddd.dddd. The number of digits after the decimal point is specified by the precision parameter. If it is absent, the default value of 2 is used.
g General number format. The argument must be a floating-point value. The function converts this value to a shortest possible string. Trailing zeros are removed and the decimal point is output only of it is necessary. The resulting string has the scientific format unless the number of digits to the left of the decimal point in the value is less than or equal to the specified precision, or unless the value is greater than or equal to 0.00001. In these cases, the resultant string has the fixed point format.
n Number format. Applied to floating-point values only. The argument is converted to a string of the form -d,ddd.ddd. The n format is similar to f except that the resultant string includes thousand separators. The character that is used for as the thousand separator is specified by the ThousandSeparator property.
m Currency format. Applied to floating-point values only. The function converts the value to a string representing a currency value. For conversion, the Format method uses the CurrencyString, CurrencyFormat, NegCurrFormat, ThousandSeparator and DecimalSeparator properties provided by the Utilities plugin. The values of these variables depend on the Regional Settings in the Control Panel on your computer. The precision parameter, if it is present, specifies the number of digits after the decimal point.

Format specifiers are case-insensitive. They will produce the same result both in uppercase and in lowercase.

Regardless of the selected format, the characters used as the decimal and thousand separators are specified by the DecimalSeparator and ThousandSeparator properties.

Args

Specifies the array of items to be converted to a string using the specified format.

Result Value

The formatted string.

Remarks

This method is obsolete. It is supported for backward compatibility only. To create a formatted string, use the aqString.Format method.

For JavaScript and Python users: The Format method does not support native arrays. You must convert them to TestComplete-compatible arrays.

Example

The index, width and precision parameters should be decimal digits (for example, “%8.4f”). The following code demonstrates a call to the Format function:

JavaScript

function Test()
{
  Arr = new Array()
  Arr[0] = "i";
  Arr[1]= 12.345;
  
  Arr = ConvertArray(Arr)
  
  s = Format("%s = %.2f", Arr)
  Log.Message(s)
}

function ConvertArray(Array)
{
  let i;
  objDict = getActiveXObject("Scripting.Dictionary");
  objDict.RemoveAll()
  for (i in Array)
  {
    objDict.Add(i, Array[i])
  }
  return objDict.Items()
}

JScript

function Test()
{
  var Arr, s;
  
  Arr = new Array(2);
  Arr[0] = "i";
  Arr[1] = 12.345;
  s = Format("%s = %.2f", Arr);
  Log.Message(s);
}

Python

def Test():
  Arr = []
  Arr.append("i")
  Arr.append(12.345)
  
  Arr = ConvertArray(Arr)
  
  s = Format("%s = %.2f", Arr)
  Log.Message(s)
  
def ConvertArray(Array):
  objDict = Sys.OleObject["Scripting.Dictionary"]
  objDict.RemoveAll()
  for i in range (0, len(Array)):
    objDict.Add(i, Array[i])
  return objDict.Items()

VBScript

Sub Test
  Arr = CreateVariantArray(0, 1)
  Arr(0) = "i"
  Arr(1) = 12.345
  s = Format("%s = %.2f", Arr)
  Log.Message s
End Sub

DelphiScript

procedure Test;
var
Arr, s;
begin
  Arr := CreateVariantArray(0, 1);
  Arr[0] := 'i';
  Arr[1] := 12.345;
  s := Format('%s = %.2f', Arr);
  Log.Message(s);
end;

C++Script, C#Script

function Test()
{
  var Arr, s;
  
  Arr = new Array(2);
  Arr[0] = "i";
  Arr[1] = 12.345;
  s = Format("%s = %.2f", Arr);
  Log["Message"](s);
}

The index parameter specifies which array item should be displayed in place of the specifier. Using this parameter, you can output the same argument multiple times. For example, the following code will produce the string '1024 = &H400':

JavaScript

function Test()
{
  var Arr, s;

  Arr = new Array(2);
  Arr[0] = 1024;
  Arr[1] = "&H";

  Arr = ConvertArray(Arr);
  s = Format("%d = %s%0:x", Arr);
  Log.Message(s);
}

function ConvertArray(Array)
{
  let i;
  objDict = Sys.OleObject("Scripting.Dictionary");
  objDict.RemoveAll()
  for (i in Array)
  {
    objDict.Add(i, Array[i])
  }
  return objDict.Items()
}

JScript

function Test()
{
  var Arr, s;

  Arr = new Array(2);
  Arr[0] = 1024;
  Arr[1] = "&H";
  s = Format("%d = %s%0:x", Arr);
  Log.Message(s);
}

Python

def Test():
  Arr = []
  Arr.append(1024)
  Arr.append("&H")
  
  Arr = ConvertArray(Arr)
  
  s = Format("%d = %s%0:x", Arr);
  Log.Message(s)
  
def ConvertArray(Array):
  objDict = Sys.OleObject["Scripting.Dictionary"]
  objDict.RemoveAll()
  for i in range (0, len(Array)):
    objDict.Add(i, Array[i])
  return objDict.Items()

VBScript

Sub Test
  Arr = CreateVariantArray(0, 1)
  Arr(0) = 1024
  Arr(1) = "&H"
  s = Format("%d = %s%0:x", Arr)
  Log.Message s
End Sub

DelphiScript

procedure Test;
var
  Arr, s;
begin
  Arr := CreateVariantArray(0, 1);
  Arr[0] := 1024;
  Arr[1] := '&H';
  s := Format('%d = %s%0:x', Arr);
  Log.Message(s);
end;

C++Script, C#Script

function Test()
{
  var Arr, s;

  Arr = new Array(2);
  Arr[0] = 1024;
  Arr[1] = "&H";
  s = Format("%d = %s%0:x", Arr);
  Log["Message"](s);
}

See Also

Format Method
CurrencyToFormatStr Method
CurrencyToStr Method
DateTimeToFormatStr Method
DateTimeToStr Method
FloatToStr Method
IntToStr Method

Highlight search results