Syntax 1 For formatting data
Description
Formats data, such as time or date values, according to a
format mask. You can convert and format date, DateTime, numeric,
and time data. You can also apply a display format to a string.
Syntax
|
1 |
<span>String</span> ( <span>data</span>, { <span>format</span> } ) |
|
Argument |
Description |
|---|---|
|
data |
The data you want returned as a string |
|
format (optional) |
A string whose value is the display masks The format can consist of more than one mask, depending on |
Return Values
String. Returns data in
the specified format if it succeeds and the empty string (“”) if
the datatype of data does not match the type
of display mask specified, format is not a
valid mask, or data is an incompatible datatype.
Usage
For date, DateTime, numeric, and time data, PowerBuilder uses
the system’s default format for the returned string if
you do not specify a format. For numeric data, the default format
is the [General] format.
For string data, a display format mask is required. (Otherwise,
the function would have nothing to do.)
The format can consist of one or more masks:
-
Formats for date, DateTime,
string, and time data can include one or two masks. The first mask
is the format for the data; the second mask is the format for a
null value. -
Formats for numeric data can have up to four masks.
A format with a single mask handles both positive and negative data.
If there are additional masks, the first mask is for positive values,
and the additional masks are for negative, zero, and null values.
To display additional characters as part of
the mask for a decimal value, you must precede each character with
a backslash. For example, to display a decimal number with two digits
of precision preceded by four asterisks, you must type a backslash
before each asterisk:
|
1 |
dec{2} amount<br>string = ls_result<br>amount = 123456.32<br>ls_result = string(amount,"****0.00") |
The resulting string is ****123456.32.
For more information on specifying display
formats, see the PowerBuilder Users Guide.
Note that, although a format can include color specifications, the colors
are ignored when you use String in PowerScript.
Colors appear only for display formats specified in the DataWindow
painter.
If the display format does not match the datatype, PowerBuilder
tries to apply the mask, which can produce unpredictable results.
Times and dates from a DataWindow control
When you call GetItemTime or GetItemString as
an argument for the String function and do not
specify a display format, the value is formatted as a DateTime value.
This statement returns a string like “2/26/03
00:00:00”:
|
1 |
String(dw_1.GetItemTime(1, "start_date")) |
International deployment
When you use String to format a date and
the month is displayed as text (for example, the display format
includes “mmm”), the month is in the language of the runtime DLLs
available when the application is run. If you have installed localized
runtime files in the development environment or on a user’s
machine, then on that machine, the month in the resulting string
is in the language of the localized files.
For information about the localized runtime
files, which are available in French, German, Italian, Spanish,
Dutch, Danish, Norwegian, and Swedish, see the chapter on internationalization
in Application Techniques.
Handling ANSI data
Since this function does not have an encoding argument to
allow you to specify the encoding of the data, the string returned
can contain garbage characters if the data has ANSI encoding. You
can handle this by converting the ANSI string returned from the String function
to a Unicode blob, and then converting the ANSI string in the blob
to a Unicode string, using the encoding parameters provided in the Blob and String conversion
functions:
|
1 |
ls_temp = String(long, "address" )<br>lb_blob = blob(ls_temp) //EncodingUTF16LE! is default<br>ls_result = string(lb_blob, EncodingANSI!) |
Message object
You can also use String to extract a string
from the Message object after calling TriggerEvent or PostEvent.
For more information, see the TriggerEvent or PostEvent functions.
Examples
This statement applies a display format to a date
value and returns Jan 31, 2002:
|
1 |
<span>String</span>(2002-01-31, "mmm dd, yyyy") |
This example applies a format to the value in order_date and
sets date1 to 6–11–02:
|
1 |
Date order_date = 2002-06-11 |
|
1 |
string date1 |
|
1 |
date1 = <span>String</span>(order_date,"m-d-yy") |
This example includes a format for a null date
value so that when order_date is null, date1 is
set to none:
|
1 |
Date order_date = 2002-06-11 |
|
1 |
string date1 |
|
1 |
SetNull(order_date) |
|
1 |
date1 = <span>String</span>(order_date, "m-d-yy;'none'") |
This statement applies a format to a DateTime value
and returns Jan 31, 2001 6 hrs and 8 min:
|
1 |
<span>String</span>(DateTime(2001-01-31, 06:08:00), & |
|
1 |
'mmm dd, yyyy h "hrs and" m "min"') |
This example builds a DateTime value from the system
date and time using the Today and Now functions.
The String function applies formatting and sets
the text of sle_date to that value,
for example, 6-11-02 8:06 pm:
|
1 |
DateTime sys_datetime |
|
1 |
string datetime1 |
|
1 |
sys_datetime = DateTime(Today(), Now()) |
|
1 |
sle_date.text = <span>String</span>(sys_datetime, & |
|
1 |
"m-d-yy h:mm am/pm;'none'") |
This statement applies a format to a numeric value
and returns $5.00:
|
1 |
<span>String</span>(5,"$#,##0.00") |
These statements set string1 to 0123:
|
1 |
integer nbr = 123 |
|
1 |
string string1 |
|
1 |
string1 = <span>String</span>(nbr,"0000;(000);****;empty") |
These statements set string1 to (123):
|
1 |
integer nbr = -123 |
|
1 |
string string1 |
|
1 |
string1 = <span>String</span>(nbr,"000;(000);****;empty") |
These statements set string1 to ****:
|
1 |
integer nbr = 0 |
|
1 |
string string1 |
|
1 |
string1 = <span>String</span>(nbr,"0000;(000);****;empty") |
These statements set string1 to "empty":
|
1 |
integer nbr |
|
1 |
string string1 |
|
1 |
SetNull(nbr) |
|
1 |
string1 = <span>String</span>(nbr,"0000;(000);****;empty") |
This statement formats string data and returns A-B-C.
The display format assigns a character in the source string to each @ and
inserts other characters in the format at the appropriate positions:
|
1 |
<span>String</span>("ABC", "@-@-@") |
This statement returns A*B:
|
1 |
<span>String</span>("ABC", "@*@") |
This statement returns ABC:
|
1 |
<span>String</span>("ABC", "@@@") |
This statement returns a space:
|
1 |
<span>String</span>("ABC", " ") |
This statement applies a display format to time data
and returns 6 hrs and 8 min:
|
1 |
<span>String</span>(06:08:02,'h "hrs and" m "min"') |
This statement returns 08:06:04:
pm
|
1 |
<span>String</span>(20:06:04,"hh:mm:ss am/pm") |
This statement returns 8:06:04:
am
|
1 |
<span>String</span>(08:06:04,"h:mm:ss am/pm") |
See Also
-
String method
for DataWindows in the DataWindow Reference or online Help