.-
help for ^tostring^                                               (STB-56: dm80)
.-

Changing numeric variables into string variables
------------------------------------------------

    ^tostring^ varlist [^,^ { ^f^ormat^(^format^)^ | ^u^sedisplayformat } ^nod^ecode ] 


Description
-----------

^tostring^ changes numeric variables to string. The most compact string
format possible is used. Any existing string variables specified are 
left unchanged.


Remarks
-------

Precise changing of numeric data to string equivalents can be difficult 
given that Stata, like most software, holds numeric data to finite precision 
and in binary form. See the discussion in [U] 16.10. If no ^format( )^ is 
specified, ^tostring^ uses the format ^%12.0g^. This format is, in particular, 
sufficient to convert integers held as bytes, ints or longs to string 
equivalent without loss of precision. 

However, users will in many cases need to specify a format themselves, 
especially when the numeric data have fractional parts and for some reason 
a change to string is required.

Similarly, for non-integers or very large integers, repeated changes using 
^tostring^ and ^destring^ can result in loss of precision through rounding 
errors and are thus not recommended. 

^tostring^ is almost the reverse of ^destring^. ^destring^ by itself changes 
all string variables to numeric, as this is a common need. However, changing 
all numeric variables to string is probably only desired occasionally, so 
users of ^tostring^ are protected from accidentally changing all variables by 
the requirement for a varlist. However, if so desired, ^tostring _all^ changes 
all variables to string.


Options
-------

^format(^format^)^ specifies the use of a numeric format as an argument to
    the ^string( )^ function, which controls the conversion of the number 
    to string. For example, a format of ^%7.2f^ specifies that numbers are to 
    be rounded to 2 decimal places before conversion to string. 
    See Remarks above and help on @functions@ and @format@. 

^usedisplayformat^ specifies that the current display format should be 
    used for each individual variable.  For example, this option
    could be useful when using U.S. social security numbers.

^format( )^ and ^usedisplayformat^ cannot be used together. 

^nodecode^ specifies that numeric values of each variable should always 
    be used, even when value labels exist. The default is to decode any 
    value labels.


Examples
--------

    . ^tostring a b c^
    . ^tostring a, f(%7.2f)^
    . ^tostring a, nodecode^
    . ^tostring a, u^


Acknowledgements 
----------------

        Kit Baum, Ken Higbee and Thomas Steichen made very helpful comments. 


Authors
-------

        Nicholas J. Cox, University of Durham, U.K.
        n.j.cox@@durham.ac.uk

        Jeremy Wernow, Stata Corporation
        jbw@@stata.com


Also see
--------

On-line:  help for @destring@ (if installed), @functions@, @format@, 
          @recast@, @encode@, @decode@