CStr and
ToText are equivalent functions.
Description
The
CStr function converts Numbers, Currency, Date,
Time, and DateTime values to text strings.
Arguments
| |
---|
| x is a Boolean value
that is converted to a String, either "True" or "False".
|
Number and Currency values
| x is a Number or
Currency value to be converted into a text string; it can be a whole or
fractional value.
y is a whole number
indicating the number of decimal places to carry the value in x to (This
argument is optional.).
z is a single
character text string indicating the character to be used to separate thousands
in x. Default is the character specified in your International or Regional
settings control panel. (This argument is optional.)
w is a single
character text string indicating the character to be used as a decimal
separator in x. Default is the character specified in your International or
Regional settings control panel. (This argument is optional.)
|
Number and Currency values
(formatting)
| x is a Number or
Currency value to be converted into a text string; it can be a whole or
fractional value.
y is a text string
used to indicate the format for displaying the value in x.
z is a whole number
indicating the number of decimal places to carry the value in x to. (This
argument is optional.)
w is a single
character text string indicating the character to be used to separate thousands
in x. Default is the character specified in your International or Regional
settings control panel. (This argument is optional.)
q is a single
character text string indicating the character to be used as a decimal
separator in x. The default is the character specified in your International or
Regional settings control panel. (This argument is optional.)
|
| x is a Date value to
be converted into a text string.
y is a text string
that defines how the value in x is to be formatted. (This argument is
optional.)
|
| x is a Time value to
be converted into a text string.
y is a text string
that defines how the value in x is to be formatted. (This argument is
optional.)
z is a text string to
be used as a label for A.M. (morning) hours. (This argument is optional.)
w is a text string to
be used as a label for P.M. (evening) hours. (This argument is optional.)
|
| x is a DateTime value
to be converted into a text string.
y is a text string of
characters that indicate how the resulting text string will be formatted. (This
argument is optional.)
z is a text string to
be used as a label for A.M. (morning) hours. (This argument is optional.)
w is a text string to
be used as a label for P.M. (evening) hours. (This argument is optional.)
|
Action
The CStr function converts Numbers,
Currency, Date, Time, and DateTime values to text strings.
Typical uses
Use this function to convert a Number,
Currency, Date, Time, or DateTime value to a text string to appear as text in
your report (form letters, comments, and so on).
Examples
CStr ({Orders.Shipped})
Returns "True" if the value of
{Orders.Shipped} is True.
CStr(123.45)
Returns "123.45".
CStr(12345.6749,2)
Returns "12345.67".
CStr(12345.6750,2)
Returns "12345.68".
CStr(12345.4999,0)
Returns "12345".
CStr(12345.5000,0)
Returns "12346".
CStr({file.AMT} * {file.QUANTITY})
Returns "44,890.20" where Amt = 24.45
and Quantity = 1836.
CStr is useful when you want to build a
sentence by combining (concatenating) a converted number or other value with
other text strings:
"The base price of item # " + {file.ITEM NUMBER} + " is $" + CStr({file.BASE PRICE}) + "."
Prints the sentence "The base price of
item A1/4520/B12 is $50.00." where the Item number is A1/4520/B12 and the Base
Price is 50.00, converted to text and formatted with two decimal places.
CStr(CDate(1996, 11, 1), "yy MMM dd, dddd")
Returns "96 Nov 01, Friday".
CStr(CDateTime(1995,10,12,3,30,11),"HH:mm, yy MMMM ddd")
Returns "03:30, 95 October Thu".
CStr(CTime(12, 10, 10), "HH*mm*ss tt", "amStr", "pmStr")
Returns "12*10*10 pmStr".
Comments
Converting Boolean values:
The CStr function, when used with
Boolean values, is most useful for combining (concatenating) a Boolean value
with other text. Otherwise, a Boolean field can be formatted to appear as True
or False in your report simply by changing the format on the Boolean Tab of the
Format Editor.
Converting numbers and currency values:
If the number of decimal places is
specified, this function does not truncate the number when converted to text,
but rounds it to the number of decimal places specified. For more information
on the rounding procedure, see
Round.
Converting Date, Time, and DateTime
values:
Any character, with the exception of
the Date or Time format characters, can be used within the format string. For
example, you may wish to use a slash to separate the different elements (month,
day, year) of the date, as in "12/30/95", or you may wish to use a colon to
separate the different elements (hours, minutes, seconds) of the time, as in
"12:30:10".
If you wish to use any of the above
characters in the format string, they must appear in quotes. For example:
CStr(CDateTime(1995,10,12,13,20,22), "MM/dd/yy hh 'h' mm 'min' ss 'sec' tt",
'am', 'pm') = "10/12/95 01 h 20 min 22 sec pm"
Passing optional arguments:
Many arguments for the
CStr function have been specified as optional.
However, you can only leave an argument blank if all the arguments that follow
it are left blank as well. In other words, you cannot leave the y and z
arguments blank and provide an argument for w. It is possible, however, to
leave one, two, or all of the optional arguments blank, as long as no arguments
are supplied after the blank arguments. The following combinations are possible
when supplying arguments to the
CStr function:
Using the "t" or "tt" format
characters in a time format string provides default strings for indicating a.m.
(morning) and p.m. (evening) hours. "t" produces just a single character, "a"
or "p", while "tt" produces the entire string, "am" or "pm". You can pass your
own custom strings for indicating am/pm strings. (See the arguments for
converting Time and DateTime values with CStr in the Arguments section above.)
If you do pass your own am/pm strings, the "t" and "tt" format characters will
have the same effect on them (producing single character vs. multiple character
strings).