The Ring programming language version 1.9 book - Part 124 of 210

1. Ring Documentation, Release 1.9
* :
* Returns : <llReturnValue> Logical
89.9 frFile() function
* Syntax : llReturnValue = frFile(tcFileName, tnFlag)
* Description : Checks if the specified file exists on disk.
* :
* Arguments : <tcFileName>
* : Specifies the name of the file to check.
* : tcFileName must include
* : the file extension. You can include a path with
* : the file name to
* : search for a file in a directory or on a drive
* : other than the current directory or drive.
* :
* : <tnFlag>
* : tnFlag was included for future compatibility.
* : In this version, It always returns true whenever
* : the file exists on disk.
* Returns : <llReturnValue> Logical
* : True if file exists on disk.
* : False if file doesn't exist on disk.
89.10 frFileToStr() function
* Syntax : lcReturnValue = frFileToStr(tcFileName)
* Description : Returns the contents of a file as a character string.
* :
* Arguments : <tcFileName>
* : Specifies the name of the file whose contents are
* : returned as a character
* : string. If the file is in a directory other than
* : the current default directory,
* : include a path with the file name.
* :
* Returns : <lcReturnValue>
* : A character string with the content of the specified file.
* :
89.11 frStr() function
* Syntax : lcReturnValue = frStr(tnValue, tnLen, tnDec)
* Description : Returns the character equivalent of a numeric expression.
* :
* Arguments : <tnValue>
* : Specifies the numeric expression to evaluate.
* :
* : <tnLen>
* : Specifies the length of the character string returned.
* : If tnLen is 0, tnLen defaults to 10 characters.
89.9. frFile() function 1199

2. Ring Documentation, Release 1.9
* : If tnLen < 0 returns one string with same length as the number.
* : Note
* : If the expression contains a decimal point,
* : the length includes one character for
* : the decimal point and one character
* : for each digit in the character string.
* :
* : <tnDec>
* : Specifies the number of decimal places in the
* : character string returned.
* : To specify the number of decimal places using
* : tnDec, you must include nLength. If nDecimalPlaces is omitted,
* : the number of decimal places defaults to zero (0).
* :
* Returns : Character data type. frStr() returns a character string
* : equivalent to the specified numeric expression.
* : Depending on certain conditions, frStr() can return the following:
* : If you specify fewer decimal places than exist in tnValue,
* : the return value is rounded up. To round results to the nearest
* : decimal place instead of upward, include the ROUND( ) function.
* : For more information, see ROUND( ) Function.
* : If nExpression is an integer, and nLength is less than
* : the number of digits in nExpression, frStr( ) returns a string of
* : asterisks, indicating numeric overflow.
* : If nExpression contains a decimal point, and nLength is equal
* : to or less than the number of digits to the left of the decimal
* : point, frStr( ) returns a string of asterisks,
* : indicating numeric overflow.
* : If nLength is greater than the length of the value evaluated
* : by nExpression, frStr( ) returns a character string padded with
* : leading spaces.
* : If nExpression has Numeric or Float type, and nLength
* : is less than the number of digits in nExpression, and , frStr( )
* : returns a value using scientific notation.
89.12 frSetIfEmpty() function
* Syntax : tuReturnValue = frSetIfEmpty(tuValue, tuNewValue)
* Description : Set a Value into a variable if the variable
* : value is empty, null or zero.
* Arguments : <tuValue>
* : The value to evaluate.
* :
* : <tuNewValue>
* : The value to set if tuValue is empty.
* :
* Returns : tuNewValue if tuValue is empty, otherwise
* : returns the original value.
* Remarks : This function doesn't exist in VFP.
89.12. frSetIfEmpty() function 1200

3. Ring Documentation, Release 1.9
89.13 frSpace() function
* Syntax : lcReturnValue = frSpace(tnSpaces)
* Description : Returns a character string composed of a
* : specified number of spaces.
* Arguments : <tnSpaces>
* : Specifies the number of spaces that frSpace() returns.
* :
* Returns : <lcReturnValue>
* : Character
89.14 frInList() function
* Syntax : llReturnValue = frInList(tuExpression, taList)
* Description : Determines whether an expression matches another
* : expression in a set of expressions.
* Arguments : <tuExpression>
* : Specifies the expression frInList() searches for in the List.
* :
* : <taList>
* : Specifies the List of expressions to search.
* : You must include at least one element in the list.
* : The expressions in the list of expressions needn't to be
* : of the same data type.
* :
* Returns : <luReturnValue> Null or logical value.
89.15 frForcePath() function
* Syntax : lcReturnValue = frForcePath(tcFileName, tcPath)
* Description : Returns a file name with a new path name
* : substituted for the old one.
* Arguments : <tcFileName>
* : Specifies the file name (with or without a path or extension),
* : which will get a new path.
* : <tcPath>
* : Specifies the new path for tcFileName.
* :
* Returns : <lcReturnValue>
* : Returns a file name with a new path name
* : substituted for the old one.
89.16 frAllTrim() function
Syntax : lcReturnValue = frAllTrim(tcExpression, tcCharacter)
89.13. frSpace() function 1201

4. Ring Documentation, Release 1.9
89.17 frLTrim() function
Syntax : lcRet = frLTrim(tcExpression, tcCharacter)
89.18 frJustDrive() function
* Syntax : lcReturnValue = frJustDrive(tcPath)
* Description : Returns the drive letter from a complete path.
* :
* Arguments : <tcPath>
* : Specifies the complete path name for
* : which you want only the drive.
* Returns : <lcReturnValue>
* : Returns the drive letter from a complete path.
89.19 frJustExt() function
* Syntax : lcReturnValue = frJustExt(tcPath)
* Description : Returns the characters of a file extension
* : from a complete path.
* Arguments : <tcPath>
* : Specifies the name, which may include the full path,
* : of the file for which you want only the extension.
* Returns : <lcReturnValue>
* : Returns the drive characters of a file extension
* : from a complete path.
89.20 frJustStem() function
* Syntax : lcReturnValue = frJustStem(tcPath)
* Description : Returns the stem name (the file name before the extension)
* : from a complete path and file name.
* Arguments : <tcPath>
* : Specifies the name (including path) of the file
* : for which you want only the stem.
* Returns : <lcReturnValue>
* : Returns the stem name of a file from a complete path.
89.21 frRTrim() function
Syntax : lcRet = frRTrim(tcExpression, tcCharacter)
89.17. frLTrim() function 1202

5. Ring Documentation, Release 1.9
89.22 frJustPath() function
Syntax : tcReturnValue = frJustPath(tcExpression)
89.23 frForceExt() function
Syntax : tcReturnValue = frForceExt(tcFileName, tcNewExtension)
89.24 frALines() function
Syntax : tnReturnValue = frALines(taList, tcExpression, tcSeparator)
89.25 frJustFName() function
Syntax : tcReturnValue = frJustFName(tcExpression)
89.26 frPadL() function
Syntax : tcReturnValue = frPadL(tcString, tnLen, tcChar)
89.27 frPadR() function
Syntax : tcReturnValue = frPadR(tcString, tnLen, tcChar)
89.28 frProper() function
* Syntax : tcReturnValue = frProper(tcExpression)
* Description : Returns from a character expression a string
* : capitalized as appropriate for proper names.
* Arguments : <tcExpression>
* : Specifies the character expression from which
* : frProper() returns a capitalized character string.
* Returns : <tcReturnValue>
89.29 frReplicate() function
Syntax : tcReturnValue = frReplicate(tcString, tnTimes)
89.22. frJustPath() function 1203

6. Ring Documentation, Release 1.9
89.30 frLen() function
Syntax : tnReturnValue = frLen(tcString)
89.31 frStuff() function
* Syntax : tcReturnValue = frStuff(tcExpression, tnStartRep,
tnCharRep, tcToReplace)
* Description : Returns a new character string replaced by a
* : specified number of characters in a character
* : expression with another character expression.
* :
* Arguments : <tcExpression>
* : Specify the character expression in which the replacement occurs.
* :
* : <tnStartRep>
* : Specify the position in <tcExpression> where the replacement begins.
* :
* : <tnCharRep>
* : Specifies the number of characters to be replaced.
* : If <tnCharRep> is 0, the replacement string
* : <tcToReplace> is inserted into <tcExpression>.
* :
* : <tcToReplace>
* : Specifies the replacement character expression.
* : If <tcToReplace> is an empty string, the number of
* : characters specified by <tnCharRep> are removed from <tcExpression>.
* :
* Returns : Character
89.32 frSubStr() function
Syntax : tcReturnValue = frSubStr(tcString, tnInitialPosition, tnNumberBytes)
89.33 frStrTran() function
Syntax : tcReturnValue = frStrTran(tcString, tcOldString, tcNewString)
89.34 frListToString() function
* Syntax : lcRet = frListToString(taList)
* Remarks : This function doesn't exist in VFP.
89.30. frLen() function 1204

7. Ring Documentation, Release 1.9
89.35 frInt() function
Syntax : lnInt = frInt(tnExpression)
89.36 frStringToList() function
* Syntax : laList = frStringToList(tcExpression)
* Remarks : This function doesn't exist in VFP.
89.37 frIIf() function
* Syntax : luReturnValue = frIIf(tlExpression, tuReturnIfTrue, tuReturnIfFalse)
* Description : Returns one of two values depending on the
* : value of a logical expression.
* Arguments : <tlExpression>
* : Specifies the logical expression that frIIf() evaluates.
* :
* : <tuReturnTrue>, <tuReturnFalse>
* : If tlExpression evaluates to True, tuReturnIfTrue is
* : returned and tuReturnIfFalse is not evaluated.
* : If tlExpression evaluates to False or Null, tuReturnIfFalse is
* : returned and tuReturnIfTrue is not evaluated.
* :
* Returns : <luReturnValue> Defined by <tuReturnIfTrue> or <tuReturnIfFalse>
89.38 frVal() function
* Syntax : luReturnValue = frVal(tcExpression)
* Description : Returns a numeric value from a character expression
* : composed of numbers
* Arguments : <tcExpression>
* : Specifies a character expression composed of up to 16 numbers.
* :
* Returns : <tnValue>
* : Return a numeric value.
89.39 frBetween() function
* Syntax : luReturnValue = frBetween(tuTestValue, tuLowValue, tuHighValue)
* Description : Determines whether the value of an expression
* : is inclusively between the
* : values of two expressions of the same type.
* :
* Arguments : <tuTestValue>
* : Specifies an expression to evaluate.
* :
* : <tuLowValue>
* : Specifies the lower value in the range.
89.35. frInt() function 1205

8. Ring Documentation, Release 1.9
* :
* : <tuHighValue>
* : Specifies the higher value in the range.
* :
* Returns : <luReturnValue>
* : Returns a logical oder null value.
89.40 frSetSeparatorTo() function
* Syntax : frSetSeparatorTo(tuExpression)
* Description : Specifies the character for the numeric place separator.
* :
* Arguments : <tuExpression>
* : Specifies the character for the numeric place separator.
* :
* : Use frSetSeparatorTo() to change the numeric place
* : separator from de default, for example space " " or a comma ",".
* : Issue frSetSeparatorTo(Null) to reset the value to its default.
* :
* Returns : None
89.41 frTransform() function
* Syntax : tcReturnValue = frTransform(tuExpression, tcFormatCodes)
* Description : Returns a character string from an expression in a
* : format determined by a format code.
* Arguments : <tuExpression>
* : Specifies the expression to format.
* :
* : <tcFormatCodes>
* : Specifies one or more format codes that determine how to
* : format the expression.
* :
* Returns : <tcReturnValue>
The following table lists the available format codes for tcFormatCodes.
--------------------------------------------------------------------------
Format Code Description
--------------------------------------------------------------------------
@! Converts an entire character string to uppercase.
@T Trims leading and trailing spaces from character values.
@B Left-justifies Numeric data within the display region.
@L Pads numeric and string data with leading zeros.
@C Appends CR to positive numeric values to indicate a credit.
@X Appends DB to negative numeric values to indicate a debit.
--------------------------------------------------------------------------
89.42 frVarType() function
89.40. frSetSeparatorTo() function 1206

9. Ring Documentation, Release 1.9
* Syntax : lcRet = frVarType(tuExpression)
* Description : Returns the data type of an expression.
* :
* Arguments : <tuExpression>
* : Expecifies the expression for which the data type is returned.
* : frVartype() returns a
* : single character indicating the data type of the expression.
* : The following table lists the characteres that frVarType()
* : returns for each data type.
* :
* : ------------------- -------------------------------------
* : Return Value Data Type
* : ------------------- -------------------------------------
* : C Character
* : N Numeric
* : A List
* : O Object
* : U Undefined type
* : ------------------- -------------------------------------
* :
* Returns : Character
89.43 Example
Load "foxring.ring"
mf = new frFunctions
/*----------------------------------------------------------*/
* frProper() samples
/*----------------------------------------------------------*/
lcStr1 = "ring is a good language"
?mf.frProper(lcStr1)
?mf.frProper(Upper(lcStr1))
/*----------------------------------------------------------*/
* frStuff() samples
/*----------------------------------------------------------*/
lcStr1 = "abcdefghijklm"
lcStr2 = "12345"
// insert
?mf.frStuff(lcStr1, 4, 0, lcStr2)
// replace
?mf.frStuff(lcStr1, 4, 3, lcStr2)
// delete
?mf.frStuff(lcStr1, 4, 6, "")
// replace and insert
?mf.frStuff(lcStr1, 4, 1, lcStr2)
// replace and delete
?mf.frStuff(lcStr1, 4, 4, lcStr2)
// replace, delete rest
89.43. Example 1207

10. Ring Documentation, Release 1.9
?mf.frStuff(lcStr1, 4, Len(lcStr1), lcStr2)
/*----------------------------------------------------------*/
?mf.frAbs(-45)
?mf.frAbs(10-30)
?mf.frAbs(30-10)
lcNumber1 = 40
lcNumber2 = 2
?mf.frAbs(lcNumber2-lcNumber1)
lcCompletFileName = "C:ringdocssourcecontribute.txt"
?mf.frFile(lcCompletFileName, Null)
if mf.frFile(lcCompletFileName, Null) {
?mf.frFileToStr(lcCompletFileName)
else
?"File does not exist"
}
lcNewPath = "C:ring_2docssource"
?mf.frJustExt(lcCompletFileName)
?mf.frJustDrive(lcCompletFileName)
?mf.frJustStem(lcCompletFileName)
?mf.frForcePath(lcCompletFileName, lcNewPath)
?mf.frTransform(" Ring is a good language ",
"@! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!")
?mf.frAllTrim(" Ring is a good language ", Null)
?mf._version
lnValue = 3125.54
?mf.frTransform(lnValue, "@B")+ "Euros"
?mf.frTransform(lnValue, "@C 9999,999,999,999.999")
mf.frSetSeparatorTo(" ")
?mf.frTransform(lnValue, "9999,999,999,999.999")
?mf.frInt(lnValue)
?mf.frForceExt("teste", "dbf")
// Format "@L" Added into frTransform() function
?mf.frTransform("123", "@L 999999")
?mf.frTransform(123, "@L 999999")
89.43. Example 1208