docs/en/target/foxringfuncsdoc.txt

   1 .. index::
   2      single: FoxRing Functions Reference; Introduction
   3
   4 ===========================
   5 FoxRing Functions Reference
   6 ===========================
   7
   8 As a FoxPro developer, I started writing a class with some of the functions I used in FoxPro.
   9
  10 The goal is to create as many functions as possible with the behavior similar to FoxPro functions.
  11
  12 Developer: Jose Rosado
  13
  14 .. index::
  15      pair: FoxRing Functions Reference; FoxRing functions
  16
  17 FoxRing functions
  18 =================
  19
  20 +-----------------------+-----------------------------------------------------------------------------------------------+
  21 | Function Name         |                               Description                                                     |
  22 +=======================+===============================================================================================+
  23 | frAbs()               | Returns the absolute value of the specified numeric expression.                               |
  24 +-----------------------+-----------------------------------------------------------------------------------------------+
  25 | frAddBs()             | Adds a backslash (if needed) to a path expression.                                            |
  26 +-----------------------+-----------------------------------------------------------------------------------------------+
  27 | frALines()            | Creates an Array with the content of the specified string.                                    |
  28 +-----------------------+-----------------------------------------------------------------------------------------------+
  29 | frAllTrim()           | Removes all leading and trailing spaces of the specified string.                              |
  30 +-----------------------+-----------------------------------------------------------------------------------------------+
  31 | frAsc()               | Returns the ANSI value for the leftmost character in a character expression.                  |
  32 +-----------------------+-----------------------------------------------------------------------------------------------+
  33 | frAt()                | Searches a character expression for the occurrence                                            |
  34 +-----------------------+-----------------------------------------------------------------------------------------------+
  35 |                       | of another character expression.                                                              |
  36 +-----------------------+-----------------------------------------------------------------------------------------------+
  37 | frAtC()               | Searches a character expression for the occurrence of another character expression without    |
  38 +-----------------------+-----------------------------------------------------------------------------------------------+
  39 |                       | regard for the case of these two expressions.                                                 |
  40 +-----------------------+-----------------------------------------------------------------------------------------------+
  41 | frBetween()           | Determines whether the value of an expression is inclusively between the values of two        |
  42 +-----------------------+-----------------------------------------------------------------------------------------------+
  43 |                       | expressions of the same type.                                                                 |
  44 +-----------------------+-----------------------------------------------------------------------------------------------+
  45 | frChr()               | Returns the character associated with the specified numeric ANSI code.                        |
  46 +-----------------------+-----------------------------------------------------------------------------------------------+
  47 | frEmpty()             | Determines whether an expression evaluates to empty.                                          |
  48 +-----------------------+-----------------------------------------------------------------------------------------------+
  49 | frFile()              | Checks if a file exists on disk.                                                              |
  50 +-----------------------+-----------------------------------------------------------------------------------------------+
  51 | frFileToStr()         | Returns the contents of a file as a character string.                                         |
  52 +-----------------------+-----------------------------------------------------------------------------------------------+
  53 | frForceExt()          | Returns a string with the old file name extension replaced by a new extension.                |
  54 +-----------------------+-----------------------------------------------------------------------------------------------+
  55 | frForcePath()         | Returns a file name with a new path name substituted for the old one.                         |
  56 +-----------------------+-----------------------------------------------------------------------------------------------+
  57 | frIif()               | Returns one of two values depending on the value of a logical expression.                     |
  58 +-----------------------+-----------------------------------------------------------------------------------------------+
  59 | frInList()            | Determines whether an expression matches another expression in a list.                        |
  60 +-----------------------+-----------------------------------------------------------------------------------------------+
  61 | frInt()               | Evaluates a numeric expression and returns the integer portion of the expression.             |
  62 +-----------------------+-----------------------------------------------------------------------------------------------+
  63 | frJustDrive()         | Returns the drive letter from a complete path.                                                |
  64 +-----------------------+-----------------------------------------------------------------------------------------------+
  65 | frJustExt()           | Returns the characters of a file extension from a complete path.                              |
  66 +-----------------------+-----------------------------------------------------------------------------------------------+
  67 | frJustFName()         | Returns the file name portion of a complete path and file name.                               |
  68 +-----------------------+-----------------------------------------------------------------------------------------------+
  69 | frJustPath()          | Returns the path portion of a complete path and file name.                                    |
  70 +-----------------------+-----------------------------------------------------------------------------------------------+
  71 | frJustStem()          | Returns the stem name (the file name before the extension)                                    |
  72 +-----------------------+-----------------------------------------------------------------------------------------------+
  73 |                       | from a complete path and file name.                                                           |
  74 +-----------------------+-----------------------------------------------------------------------------------------------+
  75 | frLen()               | Determines the number of characters in a character expression,                                |
  76 +-----------------------+-----------------------------------------------------------------------------------------------+
  77 |                       | indicating the length of the expression.                                                      |
  78 +-----------------------+-----------------------------------------------------------------------------------------------+
  79 | frListToString()      | Creates a string with the string elements of an Array.                                        |
  80 +-----------------------+-----------------------------------------------------------------------------------------------+
  81 | frLTrim()             | Removes all leading spaces or parsing characters from the                                     |
  82 +-----------------------+-----------------------------------------------------------------------------------------------+
  83 |                       | specified character expression.                                                               |
  84 +-----------------------+-----------------------------------------------------------------------------------------------+
  85 | frPadL()              | Returns a string from an expression, padded with spaces or characters to a                    |
  86 +-----------------------+-----------------------------------------------------------------------------------------------+
  87 |                       | specified length on the left side.                                                            |
  88 +-----------------------+-----------------------------------------------------------------------------------------------+
  89 | frPadR()              | Returns a string from an expression, padded with spaces or characters to a                    |
  90 +-----------------------+-----------------------------------------------------------------------------------------------+
  91 |                       | specified length on the right side.                                                           |
  92 +-----------------------+-----------------------------------------------------------------------------------------------+
  93 | frProper()            | Returns from a character expression a string capitalized as                                   |
  94 +-----------------------+-----------------------------------------------------------------------------------------------+
  95 |                       | appropriate for proper names.                                                                 |
  96 +-----------------------+-----------------------------------------------------------------------------------------------+
  97 | frReplicate()         | Returns a character string that contains a specified character                                |
  98 +-----------------------+-----------------------------------------------------------------------------------------------+
  99 |                       | expression repeated a specified number of times.                                              |
 100 +-----------------------+-----------------------------------------------------------------------------------------------+
 101 | frRTrim()             | Removes all trailing spaces or parsing characters from                                        |
 102 +-----------------------+-----------------------------------------------------------------------------------------------+
 103 |                       | the specified character expression.                                                           |
 104 +-----------------------+-----------------------------------------------------------------------------------------------+
 105 | frSetIfEmpty()        | Set a Value into a variable if the variable value is empty, null or zero.                     |
 106 +-----------------------+-----------------------------------------------------------------------------------------------+
 107 | frSetSeparatorTo()    | Specifies the character for the numeric place separator.                                      |
 108 +-----------------------+-----------------------------------------------------------------------------------------------+
 109 | frSpace()             | Returns a character string composed of a specified number of spaces.                          |
 110 +-----------------------+-----------------------------------------------------------------------------------------------+
 111 | frStr()               | Returns the character equivalent of a numeric expression.                                     |
 112 +-----------------------+-----------------------------------------------------------------------------------------------+
 113 | frStringToList()      | Creates a List with the content of the specified string.                                      |
 114 +-----------------------+-----------------------------------------------------------------------------------------------+
 115 | frStrTran()           | Searches a character expression for a second character expression and                         |
 116 +-----------------------+-----------------------------------------------------------------------------------------------+
 117 |                       | replaces each occurrence with a third character expression.                                   |
 118 +-----------------------+-----------------------------------------------------------------------------------------------+
 119 | frStuff()             | Returns a new character string replaced by a specified number of                              |
 120 +-----------------------+-----------------------------------------------------------------------------------------------+
 121 |                       | characteres in a character expression with another character expression.                      |
 122 +-----------------------+-----------------------------------------------------------------------------------------------+
 123 | frSubStr()            | Returns a character string from the given character expression,                               |
 124 +-----------------------+-----------------------------------------------------------------------------------------------+
 125 |                       | starting at a specified position in the character                                             |
 126 +-----------------------+-----------------------------------------------------------------------------------------------+
 127 |                       | expression and continuing for a specified number of characters.                               |
 128 +-----------------------+-----------------------------------------------------------------------------------------------+
 129 | frTransform()         | Returns a character string from an expression in a                                            |
 130 +-----------------------+-----------------------------------------------------------------------------------------------+
 131 |                       | format determined by a format code.                                                           |
 132 +-----------------------+-----------------------------------------------------------------------------------------------+
 133 | frVal()               | Returns a numeric value from a character expression composed of numbers.                      |
 134 +-----------------------+-----------------------------------------------------------------------------------------------+
 135 | frVarType()           | Returns the data type of an expression.                                                       |
 136 +-----------------------+-----------------------------------------------------------------------------------------------+
 137
 138 .. index::
 139      pair: FoxRing Functions Reference; frAbs() function
 140
 141 frAbs() function
 142 ================
 143
 144 .. code-block:: none
 145
 146          * Syntax       : lnReturnValue = frAbs(tnExpression)
 147          * Description  : Returns the absolute value of the specified numeric expression.
 148          *              :
 149          * Arguments    : <tnExpression>
 150          *              : Specifies the numeric expression whose absolute value frAbs()
 151          *              : returns.
 152          * Returns      : <lnReturnValue>
 153          *              : Returns the absolute value of the specified numeric expression.
 154
 155 .. index::
 156      pair: FoxRing Functions Reference; frAsc() function
 157
 158 frAsc() function
 159 ================
 160
 161 .. code-block:: none
 162
 163          * Syntax       : lnReturnValue = frAsc(tcExpression)
 164          * Description  : Returns the ANSI value for the leftmost character in
 165          *              : a character expression.
 166          * Arguments    : <tcExpression>
 167          *              : Specifies the character expression containing the character
 168          *              : whose ANSI value frAsc()
 169          *              : returns. Any characters after the first character in
 170          *              : tcExpression are ignored by frAsc().
 171          * Returns      : <lnReturnValue>
 172          *              : returns the position of the character in the character
 173          *              : table of the current code page.
 174          *              : Every character has a unique ANSI value in the
 175          *              : range from 0 to 255.
 176
 177 .. index::
 178      pair: FoxRing Functions Reference; frAddBs() function
 179
 180 frAddBs() function
 181 ==================
 182
 183 .. code-block:: none
 184
 185          * Syntax       : lcReturnValue = frAddBs(tcPath)
 186          * Description  : Adds a backslash (if needed) to a path expression.
 187          *              :
 188          * Arguments    : <tcPath>
 189          *              : Specifies the path name to which to add the backslash.
 190          *              :
 191          * Returns      : <lcReturnValue> The path with the backslash.
 192
 193 .. index::
 194      pair: FoxRing Functions Reference; frAt() function
 195
 196 frAt() function
 197 ===============
 198
 199 .. code-block:: none
 200
 201          * Syntax       : lnPos = frAt(tcToSearch, tcString, tnOccurrence)
 202          * Description  : Searches a character expression for the occurrence of
 203          *              : another character expression.
 204          *              : The search performed by frAt() is case-sensitive.
 205          *              :
 206          * Arguments    : <tcToSearch>
 207          *              : Specifies the character expression to search
 208          *              : for in <tcString>.
 209          *              : <tcString>
 210          *              : Specifies the character expression to search
 211          *              : for <tcToSearch>.
 212          *              : <tnOccurrence>
 213          *              : Specifies which occurrence, first, second, third,
 214          *              : and so on, of <tcToSearch> to search for
 215          *              : in <tcString>.
 216          *              : By default, frAt() searches for the first occurrence
 217          *              : of <tcToSearch> (tnOccurrence = 1).
 218          * Returns      : Numeric. frAt() returns an integer indicating the
 219          *              : position of the first character for a
 220          *              : character expression or memo field within another
 221          *              : character expression or memo field,
 222          *              : beginning from the leftmost character. If the
 223          *              : expression or field is not found, or if
 224          *              : <tnOccurrence> is greater than the number of
 225          *              : times <tcToSearch> occurs in  <tcString>, frAt()
 226          *              : returns 0.
 227
 228
 229 .. index::
 230      pair: FoxRing Functions Reference; frAtC() function
 231
 232 frAtC() function
 233 ================
 234
 235 .. code-block:: none
 236
 237          * Syntax       : lnPos = frAtC(tcToSearch, tcString, tnOccurrence)
 238          * Description  : Searches a character expression for the occurrence
 239          *              : of another character expression
 240          *              : without regard for the case of these two expressions.
 241          *              :
 242          * Arguments    : <tcToSearch>
 243          *              : Specifies the character expression to search
 244          *              : for in <tcString>.
 245          *              : <tcString>
 246          *              : Specifies the character expression to search
 247          *              : for <tcToSearch>.
 248          *              : <tnOccurrence>
 249          *              : Specifies which occurrence, first, second, third,
 250          *              : and so on, of <tcToSearch> to search for
 251          *              : in tcString.
 252          *              : By default, frAtC() searches for the first occurrence
 253          *              : of <tcToSearch> (tnOccurrence = 1).
 254          * Returns      : Numeric. frAtC() returns an integer indicating the
 255          *              : position of the first character for a
 256          *              : character expression or memo field within
 257          *              : another character expression or memo field,
 258          *              : beginning from the leftmost character. If the
 259          *              : expression or field is not found, or if
 260          *              : <tnOccurrence> is greater than the number of
 261          *              : times <tcToSearch> occurs in <tcString>, frAtC()
 262          *              : returns 0.
 263
 264 .. index::
 265      pair: FoxRing Functions Reference; frChr() function
 266
 267 frChr() function
 268 ================
 269
 270 .. code-block:: none
 271
 272          * Syntax       : lcReturnValue = frChr(tnExpression)
 273          * Description  : Returns the character associated with the specified numeric
 274          *              :  ANSI code.
 275          * Arguments    : <tnExpression>
 276          *              : Specifies a number between 0 and 255 whose equivalent ANSI
 277          *              : character frChr() returns.
 278          * Returns      : <lcReturnValue>
 279          *              : Returns a single character corresponding to the numeric
 280          *              : position of the character in the
 281          *              : character table of the current code page.
 282          *              :
 283          * Remarks      : tnExpression must be between 0 and 255
 284
 285 .. index::
 286      pair: FoxRing Functions Reference; frEmpty() function
 287
 288 frEmpty() function
 289 ==================
 290
 291 .. code-block:: none
 292
 293          * Syntax       : llReturnValue = frEmpty(tuExpression)
 294          * Description  : Determines whether an expression evaluates to empty.
 295          *              :
 296          * Arguments    : <tuExpression>
 297          *              : Specifies the expression that EMPTY() evaluates.
 298          *              : You can specify an expression with Character,
 299          *              : Numeric, or logical type.
 300          *              :
 301          * Returns      : <llReturnValue> Logical
 302
 303 .. index::
 304      pair: FoxRing Functions Reference; frFile() function
 305
 306 frFile() function
 307 ================
 308
 309 .. code-block:: none
 310
 311          * Syntax       : llReturnValue = frFile(tcFileName, tnFlag)
 312          * Description  : Checks if the specified file exists on disk.
 313          *              :
 314          * Arguments    : <tcFileName>
 315          *              : Specifies the name of the file to check.
 316          *              : tcFileName must include
 317          *              : the file extension. You can include a path with
 318          *              : the file name to
 319          *              : search for a file in a directory or on a drive
 320          *              : other than the current directory or drive.
 321          *              :
 322          *              : <tnFlag>
 323          *              : tnFlag was included for future compatibility.
 324          *              : In this version, It always returns true whenever
 325          *              : the file exists on disk.
 326          * Returns      : <llReturnValue> Logical
 327          *              : True if file exists on disk.
 328          *              : False if file doesn't exist on disk.
 329
 330 .. index::
 331      pair: FoxRing Functions Reference; frFileToStr() function
 332
 333 frFileToStr() function
 334 ======================
 335
 336 .. code-block:: none
 337
 338          * Syntax       : lcReturnValue = frFileToStr(tcFileName)
 339          * Description  : Returns the contents of a file as a character string.
 340          *              :
 341          * Arguments    : <tcFileName>
 342          *              : Specifies the name of the file whose contents are
 343          *              : returned as a character
 344          *              : string. If the file is in a directory other than
 345          *              : the current default directory,
 346          *              : include a path with the file name.
 347          *              :
 348          * Returns      : <lcReturnValue>
 349          *              : A character string with the content of the specified file.
 350          *              :
 351
 352 .. index::
 353      pair: FoxRing Functions Reference; frStr() function
 354
 355 frStr() function
 356 ================
 357
 358 .. code-block:: none
 359
 360          * Syntax       : lcReturnValue = frStr(tnValue, tnLen, tnDec)
 361          * Description  : Returns the character equivalent of a numeric expression.
 362          *              :
 363          * Arguments    : <tnValue>
 364          *              : Specifies the numeric expression to evaluate.
 365          *              :
 366          *              : <tnLen>
 367          *              : Specifies the length of the character string returned.
 368          *              : If tnLen is 0, tnLen defaults to 10 characters.
 369          *              : If tnLen < 0 returns one string with same length as the number.
 370          *              : Note
 371          *              : If the expression contains a decimal point,
 372          *              : the length includes one character for
 373          *              : the decimal point and one character
 374          *              : for each digit in the character string.
 375          *              :
 376          *              : <tnDec>
 377          *              : Specifies the number of decimal places in the
 378          *              : character string returned.
 379          *              : To specify the number of decimal places using
 380          *              : tnDec, you must include nLength. If nDecimalPlaces is omitted,
 381          *              : the number of decimal places defaults to zero (0).
 382          *              :
 383          * Returns      : Character data type. frStr() returns a character string
 384          *              : equivalent to the specified numeric expression.
 385          *              : Depending on certain conditions, frStr() can return the following:
 386          *              : If you specify fewer decimal places than exist in tnValue,
 387          *              : the return value is rounded up. To round results to the nearest
 388          *              : decimal place instead of upward, include the ROUND( ) function.
 389          *              : For more information, see ROUND( ) Function.
 390          *              : If nExpression is an integer, and nLength is less than
 391          *              : the number of digits in nExpression, frStr( ) returns a string of
 392          *              : asterisks, indicating numeric overflow.
 393          *              : If nExpression contains a decimal point, and nLength is equal
 394          *              : to or less than the number of digits to the left of the decimal
 395          *              : point, frStr( ) returns a string of asterisks,
 396          *              : indicating numeric overflow.
 397          *              : If nLength is greater than the length of the value evaluated
 398          *              : by nExpression, frStr( ) returns a character string padded with
 399          *              : leading spaces.
 400          *              : If nExpression has Numeric or Float type, and nLength
 401          *              : is less than the number of digits in nExpression, and , frStr( )
 402          *              : returns a value using scientific notation.
 403
 404 .. index::
 405      pair: FoxRing Functions Reference; frSetIfEmpty() function
 406
 407 frSetIfEmpty() function
 408 =======================
 409
 410 .. code-block:: none
 411
 412          * Syntax       : tuReturnValue = frSetIfEmpty(tuValue, tuNewValue)
 413          * Description  : Set a Value into a variable if the variable
 414          *              : value is empty, null or zero.
 415          * Arguments    : <tuValue>
 416          *              : The value to evaluate.
 417          *              :
 418          *              : <tuNewValue>
 419          *              : The value to set if tuValue is empty.
 420          *              :
 421          * Returns      : tuNewValue if tuValue is empty, otherwise
 422          *              : returns the original value.
 423          * Remarks      : This function doesn't exist in VFP.
 424
 425 .. index::
 426      pair: FoxRing Functions Reference; frSpace() function
 427
 428 frSpace() function
 429 ================
 430
 431 .. code-block:: none
 432
 433          * Syntax       : lcReturnValue = frSpace(tnSpaces)
 434          * Description  : Returns a character string composed of a
 435          *              : specified number of spaces.
 436          * Arguments    : <tnSpaces>
 437          *              : Specifies the number of spaces that frSpace() returns.
 438          *              :
 439          * Returns      : <lcReturnValue>
 440          *              : Character
 441
 442 .. index::
 443      pair: FoxRing Functions Reference; frInList() function
 444
 445 frInList() function
 446 ===================
 447
 448 .. code-block:: none
 449
 450          * Syntax       : llReturnValue = frInList(tuExpression, taList)
 451          * Description  : Determines whether an expression matches another
 452          *              : expression in a set of expressions.
 453          * Arguments    : <tuExpression>
 454          *              : Specifies the expression frInList() searches for in the List.
 455          *              :
 456          *              : <taList>
 457          *              : Specifies the List of expressions to search.
 458          *              : You must include at least one element in the list.
 459          *              : The expressions in the list of expressions needn't to be
 460          *              : of the same data type.
 461          *              :
 462          * Returns      : <luReturnValue> Null or logical value.
 463
 464 .. index::
 465      pair: FoxRing Functions Reference; frForcePath() function
 466
 467 frForcePath() function
 468 ======================
 469
 470 .. code-block:: none
 471
 472          * Syntax       : lcReturnValue = frForcePath(tcFileName, tcPath)
 473          * Description  : Returns a file name with a new path name
 474          *              : substituted for the old one.
 475          * Arguments    : <tcFileName>
 476          *              : Specifies the file name (with or without a path or extension),
 477          *              : which will get a new path.
 478          *              : <tcPath>
 479          *              : Specifies the new path for tcFileName.
 480          *              :
 481          * Returns      : <lcReturnValue>
 482          *              : Returns a file name with a new path name
 483          *              : substituted for the old one.
 484
 485 .. index::
 486      pair: FoxRing Functions Reference; frAllTrim() function
 487
 488 frAllTrim() function
 489 ====================
 490
 491 .. code-block:: none
 492
 493         Syntax  : lcReturnValue = frAllTrim(tcExpression, tcCharacter)
 494
 495
 496 .. index::
 497      pair: FoxRing Functions Reference; frLTrim() function
 498
 499 frLTrim() function
 500 ==================
 501
 502 .. code-block:: none
 503
 504         Syntax  : lcRet = frLTrim(tcExpression, tcCharacter)
 505
 506 .. index::
 507      pair: FoxRing Functions Reference; frJustDrive() function
 508
 509 frJustDrive() function
 510 ======================
 511
 512 .. code-block:: none
 513
 514          * Syntax       : lcReturnValue = frJustDrive(tcPath)
 515          * Description  : Returns the drive letter from a complete path.
 516          *              :
 517          * Arguments    : <tcPath>
 518          *              : Specifies the complete path name for
 519          *              : which you want only the drive.
 520          * Returns      : <lcReturnValue>
 521          *              : Returns the drive letter from a complete path.
 522
 523 .. index::
 524      pair: FoxRing Functions Reference; frJustExt() function
 525
 526 frJustExt() function
 527 ====================
 528
 529 .. code-block:: none
 530
 531          * Syntax       : lcReturnValue = frJustExt(tcPath)
 532          * Description  : Returns the characters of a file extension
 533          *              : from a complete path.
 534          * Arguments    : <tcPath>
 535          *              : Specifies the name, which may include the full path,
 536          *              : of the file for which you want only the extension.
 537          * Returns      : <lcReturnValue>
 538          *              : Returns the drive characters of a file extension
 539          *              : from a complete path.
 540
 541 .. index::
 542      pair: FoxRing Functions Reference; frJustStem() function
 543
 544 frJustStem() function
 545 =====================
 546
 547 .. code-block:: none
 548
 549          * Syntax       : lcReturnValue = frJustStem(tcPath)
 550          * Description  : Returns the stem name (the file name before the extension)
 551          *              : from a complete path and file name.
 552          * Arguments    : <tcPath>
 553          *              : Specifies the name (including path) of the file
 554          *              : for which you want only the stem.
 555          * Returns      : <lcReturnValue>
 556          *              : Returns the stem name of a file from a complete path.
 557
 558 .. index::
 559      pair: FoxRing Functions Reference; frRTrim() function
 560
 561 frRTrim() function
 562 ==================
 563
 564 .. code-block:: none
 565
 566          Syntax : lcRet = frRTrim(tcExpression, tcCharacter)
 567
 568 .. index::
 569      pair: FoxRing Functions Reference; frJustPath() function
 570
 571 frJustPath() function
 572 =====================
 573
 574 .. code-block:: none
 575
 576         Syntax  : tcReturnValue = frJustPath(tcExpression)
 577
 578 .. index::
 579      pair: FoxRing Functions Reference; frForceExt() function
 580
 581 frForceExt() function
 582 =====================
 583
 584 .. code-block:: none
 585
 586         Syntax  : tcReturnValue = frForceExt(tcFileName, tcNewExtension)
 587
 588 .. index::
 589      pair: FoxRing Functions Reference; frALines() function
 590
 591 frALines() function
 592 ===================
 593
 594 .. code-block:: none
 595
 596         Syntax  : tnReturnValue = frALines(taList, tcExpression, tcSeparator)
 597
 598 .. index::
 599      pair: FoxRing Functions Reference; frJustFName() function
 600
 601 frJustFName() function
 602 ================
 603
 604 .. code-block:: none
 605
 606         Syntax  : tcReturnValue = frJustFName(tcExpression)
 607
 608 .. index::
 609      pair: FoxRing Functions Reference; frPadL() function
 610
 611 frPadL() function
 612 =================
 613
 614 .. code-block:: none
 615
 616         Syntax  : tcReturnValue = frPadL(tcString, tnLen, tcChar)
 617
 618 .. index::
 619      pair: FoxRing Functions Reference; frPadR() function
 620
 621 frPadR() function
 622 =================
 623
 624 .. code-block:: none
 625
 626         Syntax  : tcReturnValue = frPadR(tcString, tnLen, tcChar)
 627
 628 .. index::
 629      pair: FoxRing Functions Reference; frProper() function
 630
 631 frProper() function
 632 ===================
 633
 634 .. code-block:: none
 635
 636          * Syntax       : tcReturnValue = frProper(tcExpression)
 637          * Description  : Returns from a character expression a string
 638          *              : capitalized as appropriate for proper names.
 639          * Arguments    : <tcExpression>
 640          *              : Specifies the character expression from which
 641          *              : frProper() returns a capitalized character string.
 642          * Returns      : <tcReturnValue>
 643
 644 .. index::
 645      pair: FoxRing Functions Reference; frReplicate() function
 646
 647 frReplicate() function
 648 ======================
 649
 650 .. code-block:: none
 651
 652         Syntax  : tcReturnValue = frReplicate(tcString, tnTimes)
 653
 654 .. index::
 655      pair: FoxRing Functions Reference; frLen() function
 656
 657 frLen() function
 658 ================
 659
 660 .. code-block:: none
 661
 662         Syntax  : tnReturnValue = frLen(tcString)
 663
 664 .. index::
 665      pair: FoxRing Functions Reference; frStuff() function
 666
 667 frStuff() function
 668 ==================
 669
 670 .. code-block:: none
 671
 672          * Syntax       : tcReturnValue = frStuff(tcExpression, tnStartRep,
 673                                                   tnCharRep, tcToReplace)
 674          * Description  : Returns a new character string replaced by a
 675          *              : specified number of characters in a character
 676          *              : expression with another character expression.
 677          *              :
 678          * Arguments    : <tcExpression>
 679          *              : Specify the character expression in which the replacement occurs.
 680          *              :
 681          *              : <tnStartRep>
 682          *              : Specify the position in <tcExpression> where the replacement begins.
 683          *              :
 684          *              : <tnCharRep>
 685          *              : Specifies the number of characters to be replaced.
 686          *              : If <tnCharRep> is 0, the replacement string
 687          *              : <tcToReplace> is inserted into <tcExpression>.
 688          *              :
 689          *              : <tcToReplace>
 690          *              : Specifies the replacement character expression.
 691          *              : If <tcToReplace> is an empty string, the number of
 692          *              : characters specified by <tnCharRep> are removed from <tcExpression>.
 693          *              :
 694          * Returns      : Character
 695
 696 .. index::
 697      pair: FoxRing Functions Reference; frSubStr() function
 698
 699 frSubStr() function
 700 ===================
 701
 702 .. code-block:: none
 703
 704         Syntax  : tcReturnValue = frSubStr(tcString, tnInitialPosition, tnNumberBytes)
 705
 706 .. index::
 707      pair: FoxRing Functions Reference; frStrTran() function
 708
 709 frStrTran() function
 710 ====================
 711
 712 .. code-block:: none
 713
 714         Syntax  : tcReturnValue = frStrTran(tcString, tcOldString, tcNewString)
 715
 716 .. index::
 717      pair: FoxRing Functions Reference; frListToString() function
 718
 719 frListToString() function
 720 =========================
 721
 722 .. code-block:: none
 723
 724          * Syntax       : lcRet = frListToString(taList)
 725          * Remarks      : This function doesn't exist in VFP.
 726
 727 .. index::
 728      pair: FoxRing Functions Reference; frInt() function
 729
 730 frInt() function
 731 ================
 732
 733 .. code-block:: none
 734
 735         Syntax          : lnInt = frInt(tnExpression)
 736
 737 .. index::
 738      pair: FoxRing Functions Reference; frStringToList() function
 739
 740 frStringToList() function
 741 =========================
 742
 743 .. code-block:: none
 744
 745          * Syntax       : laList = frStringToList(tcExpression)
 746          * Remarks      : This function doesn't exist in VFP.
 747
 748 .. index::
 749      pair: FoxRing Functions Reference; frIIf() function
 750
 751 frIIf() function
 752 ================
 753
 754 .. code-block:: none
 755
 756          * Syntax       : luReturnValue = frIIf(tlExpression, tuReturnIfTrue, tuReturnIfFalse)
 757          * Description  : Returns one of two values depending on the
 758          *              : value of a logical expression.
 759          * Arguments    : <tlExpression>
 760          *              : Specifies the logical expression that frIIf() evaluates.
 761          *              :
 762          *              : <tuReturnTrue>, <tuReturnFalse>
 763          *              : If tlExpression evaluates to True, tuReturnIfTrue is
 764          *              : returned and tuReturnIfFalse is not evaluated.
 765          *              : If tlExpression evaluates to False or Null, tuReturnIfFalse is
 766          *              : returned and tuReturnIfTrue is not evaluated.
 767          *              :
 768          * Returns      : <luReturnValue> Defined by <tuReturnIfTrue> or <tuReturnIfFalse>
 769
 770 .. index::
 771      pair: FoxRing Functions Reference; frVal() function
 772
 773 frVal() function
 774 ================
 775
 776 .. code-block:: none
 777
 778          * Syntax       : luReturnValue = frVal(tcExpression)
 779          * Description  : Returns a numeric value from a character expression
 780          *              : composed of numbers
 781          * Arguments    : <tcExpression>
 782          *              : Specifies a character expression composed of up to 16 numbers.
 783          *              :
 784          * Returns      : <tnValue>
 785          *              : Return a numeric value.
 786
 787 .. index::
 788      pair: FoxRing Functions Reference; frBetween() function
 789
 790 frBetween() function
 791 ====================
 792
 793 .. code-block:: none
 794
 795          * Syntax       : luReturnValue = frBetween(tuTestValue, tuLowValue, tuHighValue)
 796          * Description  : Determines whether the value of an expression
 797          *              : is inclusively between the
 798          *              : values of two expressions of the same type.
 799          *              :
 800          * Arguments    : <tuTestValue>
 801          *              : Specifies an expression to evaluate.
 802          *              :
 803          *              : <tuLowValue>
 804          *              : Specifies the lower value in the range.
 805          *              :
 806          *              : <tuHighValue>
 807          *              : Specifies the higher value in the range.
 808          *              :
 809          * Returns      : <luReturnValue>
 810          *              : Returns a logical oder null value.
 811
 812 .. index::
 813      pair: FoxRing Functions Reference; frSetSeparatorTo() function
 814
 815 frSetSeparatorTo() function
 816 ===========================
 817
 818 .. code-block:: none
 819
 820          * Syntax       : frSetSeparatorTo(tuExpression)
 821          * Description  : Specifies the character for the numeric place separator.
 822          *              :
 823          * Arguments    : <tuExpression>
 824          *              : Specifies the character for the numeric place separator.
 825          *              :
 826          *              : Use frSetSeparatorTo() to change the numeric place
 827          *              : separator from de default, for example space " " or a comma ",".
 828          *              : Issue frSetSeparatorTo(Null) to reset the value to its default.
 829          *              :
 830          * Returns      : None
 831
 832 .. index::
 833      pair: FoxRing Functions Reference; frTransform() function
 834
 835 frTransform() function
 836 ======================
 837
 838 .. code-block:: none
 839
 840          * Syntax       : tcReturnValue = frTransform(tuExpression, tcFormatCodes)
 841          * Description  : Returns a character string from an expression in a
 842          *              : format determined by a format code.
 843          * Arguments    : <tuExpression>
 844          *              : Specifies the expression to format.
 845          *              :
 846          *              : <tcFormatCodes>
 847          *              : Specifies one or more format codes that determine how to
 848          *              : format the expression.
 849          *              :
 850          * Returns      : <tcReturnValue>
 851
 852 The following table lists the available format codes for tcFormatCodes.
 853
 854 .. code-block:: none
 855
 856          --------------------------------------------------------------------------
 857           Format Code   Description
 858          --------------------------------------------------------------------------
 859           @!            Converts an entire character string to uppercase.
 860           @T            Trims leading and trailing spaces from character values.
 861           @B            Left-justifies Numeric data within the display region.
 862           @L            Pads numeric and string data with leading zeros.
 863           @C            Appends CR to positive numeric values to indicate a credit.
 864           @X            Appends DB to negative numeric values to indicate a debit.
 865          --------------------------------------------------------------------------
 866
 867 .. index::
 868      pair: FoxRing Functions Reference; frVarType() function
 869
 870 frVarType() function
 871 ====================
 872
 873 .. code-block:: none
 874
 875          * Syntax       : lcRet = frVarType(tuExpression)
 876          * Description  : Returns the data type of an expression.
 877          *              :
 878          * Arguments    : <tuExpression>
 879          *              : Expecifies the expression for which the data type is returned.
 880          *              :  frVartype() returns a
 881          *              : single character indicating the data type of the expression.
 882          *              : The following table lists the characteres that frVarType()
 883          *              : returns for each data type.
 884          *              :
 885          *              : -------------------   -------------------------------------
 886          *              : Return Value          Data Type
 887          *              : -------------------   -------------------------------------
 888          *              : C                     Character
 889          *              : N                     Numeric
 890          *              : A                     List
 891          *              : O                     Object
 892          *              : U                     Undefined type
 893          *              : -------------------   -------------------------------------
 894          *              :
 895          * Returns      : Character
 896
 897 .. index::
 898      pair: FoxRing Functions Reference; Example
 899
 900 Example
 901 =======
 902
 903 .. code-block:: ring
 904
 905         Load "foxring.ring"
 906
 907
 908         mf = new frFunctions
 909
 910         /*----------------------------------------------------------*/
 911          * frProper() samples
 912         /*----------------------------------------------------------*/
 913
 914         lcStr1 = "ring is a good language"
 915         ?mf.frProper(lcStr1)
 916         ?mf.frProper(Upper(lcStr1))
 917
 918
 919         /*----------------------------------------------------------*/
 920          * frStuff() samples
 921         /*----------------------------------------------------------*/
 922
 923         lcStr1 = "abcdefghijklm"
 924         lcStr2 = "12345"
 925
 926         // insert
 927         ?mf.frStuff(lcStr1, 4, 0, lcStr2)
 928         // replace
 929         ?mf.frStuff(lcStr1, 4, 3, lcStr2)
 930         // delete
 931         ?mf.frStuff(lcStr1, 4, 6, "")
 932         // replace and insert
 933         ?mf.frStuff(lcStr1, 4, 1, lcStr2)
 934         // replace and delete
 935         ?mf.frStuff(lcStr1, 4, 4, lcStr2)
 936         // replace, delete rest
 937         ?mf.frStuff(lcStr1, 4, Len(lcStr1), lcStr2)
 938
 939         /*----------------------------------------------------------*/
 940
 941
 942
 943         ?mf.frAbs(-45)
 944         ?mf.frAbs(10-30)
 945         ?mf.frAbs(30-10)
 946
 947         lcNumber1 = 40
 948         lcNumber2 = 2
 949
 950         ?mf.frAbs(lcNumber2-lcNumber1)
 951
 952
 953
 954
 955         lcCompletFileName = "C:\ring\docs\source\contribute.txt"
 956
 957         ?mf.frFile(lcCompletFileName, Null)
 958         if mf.frFile(lcCompletFileName, Null) {
 959           ?mf.frFileToStr(lcCompletFileName)
 960         else
 961           ?"File does not exist"
 962         }
 963
 964         lcNewPath = "C:\ring_2\docs\source\"
 965         ?mf.frJustExt(lcCompletFileName)
 966         ?mf.frJustDrive(lcCompletFileName)
 967         ?mf.frJustStem(lcCompletFileName)
 968         ?mf.frForcePath(lcCompletFileName, lcNewPath)
 969         ?mf.frTransform("    Ring is a good language    ",
 970                         "@! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!")
 971         ?mf.frAllTrim("    Ring is a good language    ", Null)
 972         ?mf._version
 973         lnValue = 3125.54
 974         ?mf.frTransform(lnValue, "@B")+ "Euros"
 975         ?mf.frTransform(lnValue, "@C 9999,999,999,999.999")
 976         mf.frSetSeparatorTo(" ")
 977         ?mf.frTransform(lnValue, "9999,999,999,999.999")
 978         ?mf.frInt(lnValue)
 979         ?mf.frForceExt("teste", "dbf")
 980         // Format "@L" Added into frTransform() function
 981         ?mf.frTransform("123", "@L 999999")
 982         ?mf.frTransform(123, "@L 999999")
 983