Instant constructors: string()

The instant constructor string() creates a string operand dynamically. String operands are intended to store text. The below described constructors focus mainly on formatting strings from numbers.

Declaration

Form 1:

string string( int32 aValue )

Form 2:

string string( int32 aValue, int32 aNoOfDigits )

Form 3:

string string( int32 aValue, int32 aNoOfDigits, int32 aRadix )

Form 4:

string string( uint32 aValue )

Form 5:

string string( uint32 aValue, int32 aNoOfDigits )

Form 6:

string string( uint32 aValue, int32 aNoOfDigits, int32 aRadix )

Form 7:

string string( float aValue )

Form 8:

string string( float aValue, int32 aNoOfDigits )

Form 9:

string string( float aValue, int32 aNoOfDigits, int32 aPrecision )

Form 10:

string string( char aChar, int32 aCount )

Form 11:

string string()

Parameters

aValue

The integer or the floating-point value to convert into a string.

aNoOfDigits

Minimum number of digits in the resulting string. If necessary, leading 0 (zero) signs are added automatically. The value is limited to 128.

aRadix

Controls the format of the resulting string. This parameter can assume values 2, 8, 10 or 16. Accordingly the number is converted in binary, octal, decimal or hexadecimal notation. When the passed value is other than 2, 8 or 16, the value 10 is assumed implicitly.

aPrecision

Number of digits after the decimal point. The value is limited to 32.

aChar

The character to fill the string with.

aCount

Number of aChar characters to fill the string with.

Discussion

The first version of the string() constructor converts the signed integer value aValue in a string in decimal notation and returns it. If the number is negative, an additional - (minus) sign is put in front of the formatted string. For example:

var int32 x1 = 320;
var int32 x2 = 200;

var string s = string( x1 - x2 ); // s = "120"
var string s = string( x2 - x1 ); // s = "-120"

The second version of the string() constructor converts the signed integer value aValue in a string in decimal notation and returns it. If the number is negative, an additional - (minus) sign is put in front of the formatted string. Additionally the constructor adds leading 0 (zero) signs until the resulting string has reached the length specified in the parameter aNoOfDigits. For example:

var int32 x1 = 320;
var int32 x2 = 200;

var string s = string( x1 - x2, 5 ); // s = "00120"
var string s = string( x2 - x1, 5 ); // s = "-0120"

The third version of the string() constructor converts the signed integer value aValue in a string in binary, octal, decimal or lowercase hexadecimal notation and returns it. The particular notation is specified in the parameter aRadix. According to the desired notation pass in this parameter the value 2 (binary), 8 (octal), 10 (decimal) or 16 (hexadecimal). Specifying the value 10 in the aRadix parameter results in the same functionality as described in the constructor version above.

If the number is negative, an additional - (minus) sign is put in front of the formatted string. Additionally the constructor adds leading 0 (zero) signs until the resulting string has reached the length specified in the parameter aNoOfDigits. For example:

var int32 x1 = 320;
var int32 x2 = 200;

// Binary notation: aRadix = 2
var string s = string( x1 - x2,  0, 2  ); // s = "1111000"
var string s = string( x1 - x2, 16, 2  ); // s = "0000000001111000"
var string s = string( x2 - x1,  0, 2  ); // s = "-1111000"
var string s = string( x2 - x1, 16, 2  ); // s = "-000000001111000"

// Octal notation: aRadix = 8
var string s = string( x1 - x2,  0, 8  ); // s = "170"
var string s = string( x1 - x2,  5, 8  ); // s = "00170"
var string s = string( x2 - x1,  0, 8  ); // s = "-170"
var string s = string( x2 - x1,  5, 8  ); // s = "-0170"

// Decimal notation: aRadix = 10
var string s = string( x1 - x2,  0, 10 ); // s = "120"
var string s = string( x1 - x2,  5, 10 ); // s = "00120"
var string s = string( x2 - x1,  0, 10 ); // s = "-120"
var string s = string( x2 - x1,  5, 10 ); // s = "-0120"

// Hexadecimal notation: aRadix = 16
var string s = string( x1 - x2,  0, 16 ); // s = "78"
var string s = string( x1 - x2,  5, 16 ); // s = "00078"
var string s = string( x2 - x1,  0, 16 ); // s = "-78"
var string s = string( x2 - x1,  5, 16 ); // s = "-0078"

The fourth version of the string() constructor converts the unsigned integer value aValue in a string in decimal notation and returns it. For example:

var int32 x1 = 320;
var int32 x2 = 200;

var string s = string((uint32)( x1 - x2 )); // s = "120"
var string s = string((uint32)( x2 - x1 )); // s = "4294967176"

The fifth version of the string() constructor converts the unsigned integer value aValue in a string in decimal notation and returns it. Additionally the constructor adds leading 0 (zero) signs until the resulting string has reached the length specified in the parameter aNoOfDigits. For example:

var int32 x1 = 320;
var int32 x2 = 200;

var string s = string((uint32)( x1 - x2 ), 5 ); // s = "00120"

The sixth version of the string() constructor converts the unsigned integer value aValue in a string in binary, octal, decimal or lowercase hexadecimal notation and returns it. The particular notation is specified in the parameter aRadix. According to the desired notation pass in this parameter the value 2 (binary), 8 (octal), 10 (decimal) or 16 (hexadecimal). Specifying the value 10 in the aRadix parameter results in the same functionality as described in the constructor version above.

Additionally the constructor adds leading 0 (zero) signs until the resulting string has reached the length specified in the parameter aNoOfDigits. For example:

var int32 x1 = 320;
var int32 x2 = 200;

// Binary notation: aRadix = 2
var string s = string((uint32)( x1 - x2 ),  0, 2  ); // s = "1111000"
var string s = string((uint32)( x1 - x2 ), 16, 2  ); // s = "0000000001111000"
var string s = string((uint32)( x2 - x1 ),  0, 2  ); // s = "11111111111111111111111110001000"
var string s = string((uint32)( x2 - x1 ), 35, 2  ); // s = "00011111111111111111111111110001000"

// Octal notation: aRadix = 8
var string s = string((uint32)( x1 - x2 ),  0, 8  ); // s = "170"
var string s = string((uint32)( x1 - x2 ),  5, 8  ); // s = "00170"
var string s = string((uint32)( x2 - x1 ),  0, 8  ); // s = "37777777610"
var string s = string((uint32)( x2 - x1 ), 15, 8  ); // s = "000037777777610"

// Decimal notation: aRadix = 10
var string s = string((uint32)( x1 - x2 ),  0, 10 ); // s = "120"
var string s = string((uint32)( x1 - x2 ),  5, 10 ); // s = "00120"
var string s = string((uint32)( x2 - x1 ),  0, 10 ); // s = "4294967176"
var string s = string((uint32)( x2 - x1 ), 15, 10 ); // s = "000004294967176"

// Hexadecimal notation: aRadix = 16
var string s = string((uint32)( x1 - x2 ),  0, 16 ); // s = "78"
var string s = string((uint32)( x1 - x2 ),  5, 16 ); // s = "00078"
var string s = string((uint32)( x2 - x1 ),  0, 16 ); // s = "ffffff88"
var string s = string((uint32)( x2 - x1 ), 15, 16 ); // s = "0000000ffffff88"

The seventh version of the string() constructor converts the floating-point value aValue in a string and returns it. If the number is negative, an additional - (minus) sign is put in front of the formatted string. The number of digits after the decimal point is limited to 6 whereby final 0 (zero) signs are not shown. For example:

var float f1 = 1.0;
var float f2 = 1.123456789;
var float f3 = 1.123000000;

var string s = string( f1 );  // s = "1.0"
var string s = string( f2 );  // s = "1.123457"
var string s = string( f3 );  // s = "1.123"
var string s = string( -f3 ); // s = "-1.123"

The eighth version of the string() constructor converts the floating-point value aValue in a string and returns it. If the number is negative, an additional - (minus) sign is put in front of the formatted string. This constructor doesn't format the decimal point and the following digits. Additionally the constructor adds leading 0 (zero) signs until the resulting string has reached the length specified in the parameter aNoOfDigits. For example:

var float f1 = 1.0;
var float f2 = 1123.456789;
var float f3 = 112.3000000;

var string s = string( f1,  5 ); // s = "00001"
var string s = string( f2,  5 ); // s = "01123"
var string s = string( f3,  5 ); // s = "00112"
var string s = string( -f3, 8 ); // s = "-0000112"

The ninth version of the string() constructor converts the floating-point value aValue in a string and returns it. If the number is negative, an additional - (minus) sign is put in front of the formatted string. The number of digits following the decimal point is specified in the parameter aPrecision. When aPrecision is <= 0 (zero), no decimal point and no digits after the decimal point are formatted. Additionally the constructor adds leading 0 (zero) signs until the resulting string has reached the length specified in the parameter aNoOfDigits. For example:

var float f1 = 1.0;
var float f2 = 1123.456789;

var string s = string( f1,  0, 3 ); // s = "1.000"
var string s = string( f2,  0, 3 ); // s = "1123.457"
var string s = string( f1,  0, 0 ); // s = "1"
var string s = string( f2,  0, 0 ); // s = "1123"

var string s = string( f1,  6, 3 ); // s = "01.000"
var string s = string( f2, 10, 3 ); // s = "001123.457"
var string s = string( f1,  3, 0 ); // s = "001"
var string s = string( f2,  6, 0 ); // s = "001123"

var string s = string( -f1,  6, 3 ); // s = "-1.000"
var string s = string( -f2, 10, 3 ); // s = "-01123.457"
var string s = string( -f1,  3, 0 ); // s = "-01"
var string s = string( -f2,  6, 0 ); // s = "-01123"

The tenth version of the string() constructor formats a string filled with aCount copies of the character specified in the parameter aChar. If the parameter aCount is <= 0 or the character aChar is a zero-character ('\0') the constructors returns an empty string. For example:

var char  ch    = '*';
var int32 count = 12;

var string s = string( ch,  count ); // s = "************"
var string s = string( ch, -count ); // s = ""

The last, eleventh version of the string() constructor doesn't accept any arguments. It simply returns an empty string. The function of this constructor corresponds thus to the string literal "".

var string text = string(); // text = ""