4D Doc Center : String

4D v13.4


String ( expression {; format {; addTime}} ) -> Function result

Parameter	Type	Description
expression	Expression	Expression for which to return the string form (can be Real, Integer, Long Integer, Date, Time String, Text or Boolean)
format	String, Longint	Display format
addTime	Time	Time to add on if expression is a date
Function result	String	String form of the expression

Description

The String command returns the string form of the numeric, Date, Time, string or Boolean expression you pass in expression.

If you do not pass the optional format parameter, the string is returned with the appropriate default format. If you pass format, you can force the result string to be of a specific format.

The optional addTime parameter adds a time to a date in a combined format. It can only be used when the expression parameter is a date (see below).

Numeric Expressions
If expression is a numeric expression (Real, Integer, Long Integer), you can pass an optional string format. Following are some examples:

Example	Result
String(2^15) ` Use default format	32768 (Default format used here)
String(2^15;"###,##0 Inhabitants")	32,768 Inhabitants
String(1/3;"##0.00000")	0.33333
String(1/3) ` Use default format	0.3333333333333330000 (Default format used here)
String(Arctan(1)*4)	3.141592653589790000 (Default format used here)
String(Arctan(1)*4;"##0.00")	3.14
String(-1;"&x")	0xFFFFFFFF
String(-1;"&$")	$FFFFFFFF
String(0 ?+ 7;"&x")	0x0080
String(0 ?+ 7;"&$")	$80
String(0 ?+ 14;"&x")	0x4000
String(0 ?+ 14;"&$")	$4000
String(50,3;"&xml")	50.3
String(Num(1=1);"True;;False")	True
String(Num(1=2);"True;;False")	False

The format is specified in the same way as it would be for a number field on a form. See the section Display formats in the 4D Design Reference manual for more information about formatting numbers. You can also pass the name of a custom style in format. The custom style name must be preceded by the “|” character.

Date Expressions
If expression is a Date expression, the string is returned using the default format specified in the system.
In the format parameter, you can pass one of the constants described below (Date Display Formats theme).

In this case, you can also pass a time in the addTime parameter. This parameter lets you combine a date with a time so that you can generate time stamps in compliance with current standards (ISO Date GMT and Date RFC 1123 constants). These formats are particularly useful in the context of XML and Web processing. The addTime parameter can only be used when the expression parameter is a date.

Constant	Type	Value	Comment
Blank if null date	Longint	100	"" instead of 0
Date RFC 1123	Longint	10
Internal date abbreviated	Longint	6	Dec 29, 2006
Internal date long	Longint	5	December 29, 2006
Internal date short	Longint	7	12/29/2006
Internal date short special	Longint	4	12/29/06 (but 12/29/1896 or 12/29/2096)
ISO Date	Longint	8	2006-12-29T00:00:00 (deprecated)
ISO Date GMT	Longint	9	2010-09-13T16:11:53Z
System date abbreviated	Longint	2	Sun, Dec 29, 2006
System date long	Longint	3	Sunday, December 29, 2006
System date short	Longint	1	12/29/2006

Compatibility note: Starting with 4D v13.4, null dates converted to strings with the System date short format are returned in the form "!00/00/0000!". In previous versions of 4D, they are returned with two-digit years ("!00/00/00!").

Here are a few examples of simple formats (assuming that the current date is 12/29/2006):

 $vsResult:=String(Current date) //$vsResult gets "12/29/06"

 $vsResult:=String(Current date;Internal date long) // $vsResult gets "December 29, 2006"

 $vsResult:=String(Current date;ISO Date GMT) // $vsResult gets "2009-03-04T23:00:00" in France

Notes for combined date/time formats:

The ISO Date GMT format corresponds to the ISO8601 standard, containing a date and a time expressed with respect to the time zone (GMT).
$mydate:=String(Current date;ISO Date GMT;Current time) // returns, for instance, 2010-09-13T16:11:53Z

Note that the "Z" character at the end indicates the GMT format.
If you do not pass the addTime parameter, the command returns the date at midnight (local time) expressed in GMT time, which may cause the date to be moved forward or back depending on the local time zone:
$mydate:=String(!13/09/2010!;ISO Date GMT) // returns 2010-09-12T22:00:00Z in France
The ISO Date format is similar to the ISO Date GMT, except that it expresses the date and time without respect to the time zone. Note that since this format does not comply with the ISO8601 standard, its use should be reserved for very specific purposes.
$mydate:=String(!13/09/2010!;ISO Date) // returns 2010-09-13T00:00:00 regardless of the time zone $mydate:=String(Current date;ISO Date;Current time) // returns 2010-09-13T18:11:53
The Date RFC 1123 format formats a date/time combination according to the standard defined by RFC 822 and 1123. You need this format for example to set the expiration date for cookies in an HTTP header.
$mydate:=String(Current date;Date RFC 1123;Current time) // returns, for example Fri, 10 Sep 2010 13:07:20 GMT

The time expressed takes the time zone into account (GMT zone). If you only pass a date, the command returns the date at midnight (local time) expressed in GMT time which may cause the date to be moved forward or back depending on the local time zone:
$mydate:=String(Current date;Date RFC 1123) // returns Thu, 09 Sep 2010 22:00:00 GMT

Time Expressions
If expression is a Time expression, the string is returned using the default HH:MM:SS format. In the format parameter, you can pass one of the following constants (thème Time Display Formats theme):

Constant	Type	Value	Comment
Blank if null time	Longint	100	"" instead of 0
HH MM	Longint	2	01:02
HH MM AM PM	Longint	5	1:02 AM
HH MM SS	Longint	1	01:02:03
Hour Min	Longint	4	1 hour 2 minutes
Hour Min Sec	Longint	3	1 hour 2 minutes 3 seconds
ISO Time	Longint	8	0000-00-00T01:02:03
Min Sec	Longint	7	62 minutes 3 seconds
MM SS	Longint	6	62:03
System time long	Longint	11	1:02:03 AM HNEC (Mac only)
System time long abbreviated	Longint	10	1•02•03 AM (Mac only)
System time short	Longint	9	01:02:03

Notes:

The ISO Time format corresponds to the ISO8601 standard and contains, in theory, a date and a time. Since this format does not support combined dates/times; the date part is filled with 0s. This format expresses the local time.
The Blank if null constant must be added to the format; it indicates that in the case of a null value, 4D must return an empty string instead of zeros.

These examples assume that the current time is 5:30 PM and 45 seconds:

 $vsResult:=String(Current time) ` $vsResult gets "17:30:45"

 $vsResult:=String(Current time;Hour Min Sec) ` $vsResult gets "17 hours 30 minutes 45 seconds"

String Expressions
If expression is of the String or Text type, the command returns the same value as the one passed in the parameter. This can be useful more particularly in generic programming using pointers.
In this case, the format parameter, if passed, is ignored.

Boolean Expressions
If expression is of the Boolean type, the command returns the string “True” or “False” in the language of the application (for example, “Vrai” or “Faux” in a French version of 4D).
In this case, the format parameter, if passed, is ignored.