xHarbour Reference Documentation > Function Reference

Str()

Converts a numeric value to a character string.

Syntax

Str( <nNumber>   , ;
    [<nLength>]  , ;
    [<nDecimals>], ;
    [<lTrim>]      ) --> cString

Arguments

<nNumber>

A numeric value to convert to a character string.

<nLength>

An optional numeric value specifying the length of the return string, including sign and decimal places.

<nDecimals>

This is an optional numeric value indicating the number of decimal places to return.

<lTrim>

This parameter defaults to .F. (false). When .T. (true) is passed, the returned string has no leading spaces.

Return

The function returns <nNumber> formatted as a character string.

Description

Str() converts a numeric value to a character string. This is required when numeric values must be concatenated with character strings for formatted display, or when index keys containing Numeric and Character fields must be created.

If the length of the return string is specified too small, so that Int(<nNumber>) does not fit into the result, Str() returns a string filled with asterisks (*).

If only decimal places do not fit entirely, Str() rounds <nNumber> to the requested decimal places.

If both, <nLength> and <nDecimals>, are not specified, Str() obtains default values for both optional parameters as follows:

Formatting rules of Str()

Numeric value	Length of return string
Field variable	Field length plus decimals
Expressions/constants	Minimum of 10 digits plus decimals
Val()	Minimum of 3 digits
Day() and Month()	3 digits
Year()	5 digits
Recno()	7 digits

Note:  the number string is formatted without leading spaces when .T. (true) is specified for the fourth parameter.

Info

See also:	CStr(), NumToHex(), StrZero(), Transform(), Val()
Category:	Character functions , Conversion functions
Source:	rtl\str.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates formatting rules applied by Str()

   PROCEDURE Main
      LOCAL  nValue := 123.456

      ? Str( nValue )               // result:        123.456

      ? Str( nValue,  1 )           // result: *
      ? Str( nValue,  2 )           // result: **

      ? Str( nValue,  3 )           // result: 123
      ? Str( nValue,  4 )           // result:  123
      ? Str( nValue,  5 )           // result:   123

      ? Str( nValue,  5, 1 )        // result: 123.5
      ? Str( nValue,  6, 2 )        // result: 123.46
      ? Str( nValue,  7, 3 )        // result: 123.456
      ? Str( nValue,  8, 4 )        // result: 123.4560

      ? Str( nValue, 10, 0 )        // result:        123
      ? Str( nValue, 10, 1 )        // result:      123.5
      ? Str( nValue, 10, 2 )        // result:     123.46
      ? Str( nValue, 10, 3 )        // result:    123.456
      ? Str( nValue, 10, 4 )        // result:   123.4560
   RETURN