/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 1999 Jose Lalin <dezac@corevia.com>
 *    MemoTran() documentation
 *    HardCR() documentation
 *
 * Copyright 2003 Alejandro de Garate <alex_degarate@hotmail.com>
 *    MemoRead() documentation
 *    MemoWrit() documentation
 *
 * Documentation for hb_MemoRead(), hb_MemoWrit()
 *
 * See COPYING.txt for licensing terms.
 *
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      MemoTran()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Strings
   $ONELINER$
      Converts hard and soft carriage returns within strings.
   $SYNTAX$
      MemoTran( <cString>, <cHard>, <cSoft> ) --> <cConvertedString>
   $ARGUMENTS$
      <cString> is a string of chars to convert.

      <cHard> is the character to replace hard returns with. If not
      specified defaults to semicolon.

      <cSoft> is the character to replace soft returns with. If not
      specified defaults to single space.
   $RETURNS$
      <cConvertedString> Transformed string.
   $DESCRIPTION$
      Returns a string/memo with carriage return chars converted to
      specified chars.
   $EXAMPLES$
      ? MemoTran( DATA->CNOTES )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $FILES$
      Library is core
   $SEEALSO$
      HardCR(), StrTran()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      HardCR()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Strings
   $ONELINER$
      Replace all soft carriage returns with hard carriages returns.
   $SYNTAX$
      HardCR( <cString> ) --> <cConvertedString>
   $ARGUMENTS$
      <cString> is a string of chars to convert.
   $RETURNS$
      <cConvertedString> Transformed string.
   $DESCRIPTION$
      Returns a string/memo with soft carriage return chars converted to
      hard carriage return chars.
   $EXAMPLES$
      ? HardCR( Data->CNOTES )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $FILES$
      Library is core
   $SEEALSO$
      MemoTran(), StrTran()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      MemoRead()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Strings
   $ONELINER$
      Return the text file's contents as a character string
   $SYNTAX$
      MemoRead( <cFileName> ) --> cString
   $ARGUMENTS$
      <cFileName> is the filename to read from disk.
                  It must include the file extension. If file to be read
                  lives in another directory, you must include the path.
   $RETURNS$
      Returns the contents of a text file as a character string.

      If <cFileName> cannot be found or read MEMOREAD returns an empty
      string ("").
   $DESCRIPTION$
      MemoRead() is a function that reads the content of a text file (till
      now) from disk (floppy, HD, CD-ROM, etc.) into a memory string.
      In that way you can manipulate as any character string or assigned
      to a memo field to be saved in a database.

      MemoRead() function is used together with MemoEdit() and MemoWrit()
      to get from disk text from several sources that would be edited,
      searched, replaced, displayed, etc.

      It is used to import data from other sources to our database.

      Note:
      MemoRead() does not use the settings SET DEFAULT or SET PATH to
      search for <cFileName>.
      It searches for <cFileName> in the current directory.

      Over a network, MemoRead() attempts to open <cFileName> in read-only
      mode and shared.  If the file is used in mode exclusive by another
      process, the function will returns a null string ("").
   $EXAMPLES$
      //  This example uses MemoRead() to assign the contents of a text
      //  file to a character variable for later search

      cFile   := "account.prg"
      cString := MemoRead( cFile )
      cCopyright := "Melina"

      IF At( "Melina", cString ) == 0            // check for copyright
         MemoWrit( cFile, cCopyright + cString ) // if not, add it!
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      MemoEdit(), MemoWrit(), REPLACE, hb_MemoRead()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_MemoRead()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Strings
   $ONELINER$
      Return the text file's contents as a character string
   $SYNTAX$
      hb_MemoRead( <cFileName> ) --> cString
   $ARGUMENTS$
      <cFileName> is the filename to read from disk.
                  It must include the file extension. If file to be read
                  lives in another directory, you must include the path.
   $RETURNS$
      Returns the contents of a text file as a character string.

      If <cFileName> cannot be found or read HB_MEMOREAD returns an empty
      string ("").
   $DESCRIPTION$
      hb_MemoRead() is a function that reads the content of a text file
      (till now) from disk (floppy, HD, CD-ROM, etc.) into a memory string.
      In that way you can manipulate as any character string or assigned
      to a memo field to be saved in a database.

      hb_MemoRead() function is used together with MemoEdit() and hb_MemoWrit()
      to get from disk text from several sources that would be edited,
      searched, replaced, displayed, etc.

      It is used to import data from other sources to our database.

      Note:
      hb_MemoRead() does not use the settings SET DEFAULT or SET PATH to
      search for <cFileName>.
      It searches for <cFileName> in the current directory.

      Over a network, hb_MemoRead() attempts to open <cFileName> in read-only
      mode and shared.  If the file is used in mode exclusive by another
      process, the function will returns a null string ("").

      hb_MemoRead() vs MemoRead():
      hb_MemoRead() is identical to MemoRead() except it won't truncate the
      last byte (on non-UNIX compatible systems) if it's a EOF char.
   $EXAMPLES$
      //  This example uses hb_MemoRead() to assign the contents of a text
      //  file to a character variable for later search

      cFile   := "account.prg"
      cString := hb_MemoRead( cFile )
      cCopyright := "Melina"

      IF At( "Melina", cString ) == 0               // check for copyright
         hb_MemoWrit( cFile, cCopyright + cString ) // if not, add it!
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      MemoEdit(), hb_MemoWrit(), REPLACE, MemoRead()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      MemoWrit()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Strings
   $ONELINER$
      Write a memo field or character string to a text file on disk
   $SYNTAX$
      MemoWrit( <cFileName>, <cString> ) --> lSuccess
   $ARGUMENTS$
      <cFileName> is the filename to be written to disk.
                  It must include the file extension. If file to be read
                  lives in another directory, you must include the path.

      <cString>   Is the memo field or character string, to be write to
                  <cFile>.
   $RETURNS$
      Function returns true (.T.) if the writing operation was successful;
      otherwise, it returns false (.F.).
   $DESCRIPTION$
      This a function that writes a memo field or character string to a
      text file on disk (floppy, HD, CD-ROM, etc.)
      If you not specified a path, MemoWrit() writes <cFileName> to the
      current directory. If <cFileName> exists, it is overwritten.

      There is a third parameter (optional), <lWriteEof>, (not found in
      CA-Cl*pper) which let to programmer change the default behavior of
      - always - to write the EOF character, Chr( 26 ) as in CA-Cl*pper.

      MemoWrit() function is used together with MemoRead() and MemoEdit()
      to save to disk text from several sources that was edited, searched,
      replaced, displayed, etc.

      Note that MemoWrit() do not use the directory settings SET DEFAULT.
   $EXAMPLES$
      //  This example uses MemoWrit() to write the contents of a character
      // variable to a text file.

      cFile   := "account.prg"
      cString := MemoRead( cFile )

      IF At( "Melina", cString ) == 0            // check for copyright
         MemoWrit( cFile, cCopyright + cString ) // if not, add it!
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      MemoEdit(), MemoRead(), hb_MemoWrit()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_MemoWrit()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Strings
   $ONELINER$
      Write a memo field or character string to a text file on disk
   $SYNTAX$
      hb_MemoWrit( <cFileName>, <cString>, [<lWriteEof>] ) --> lSuccess
   $ARGUMENTS$
      <cFileName> is the filename to be written to disk.
                  It must include the file extension. If file to be read
                  lives in another directory, you must include the path.

      <cString>   Is the memo field or character string, to be write to
                  <cFile>.

      <lWriteEof> Is a logic variable that settle if the "end of file"
                  character - Chr( 26 ) - is written to disk.
                  This parameter is optional. By default is true (.T.)
   $RETURNS$
      Function returns true (.T.) if the writing operation was successful;
      otherwise, it returns false (.F.).
   $DESCRIPTION$
      This a function that writes a memo field or character string to a
      text file on disk (floppy, HD, CD-ROM, etc.)
      If you not specified a path, hb_MemoWrit() writes <cFileName> to the
      current directory. If <cFileName> exists, it is overwritten.

      There is a third parameter (optional), <lWriteEof>, (not found in
      CA-Cl*pper) which let to programmer change the default behavior of
      - always - to write the EOF character, Chr( 26 ) as in CA-Cl*pper.

      If there is no third parameter, nothing change, EOF is written as
      in CA-Cl*pper, the same occurs when <lWriteEof> is set to .T.
      But, if <lWriteEof> is set to .F., EOF char is Not written to the
      end of the file.

      hb_MemoWrit() function is used together with hb_MemoRead() and
      MemoEdit() to save to disk text from several sources that was edited,
      searched, replaced, displayed, etc.

      Note that hb_MemoWrit() do not use the directory settings SET DEFAULT.

      hb_MemoWrit() vs MemoWrit():
      hb_MemoWrit() never writes the obsolete EOF char at the end of the file.
   $EXAMPLES$
      //  This example uses hb_MemoWrit() to write the contents of a character
      //  variable to a text file.

      cFile   := "account.prg"
      cString := hb_MemoRead( cFile )
      cCopyright := "Melina"

      IF At( "Melina", cString ) == 0               // check for copyright
         hb_MemoWrit( cFile, cCopyright + cString ) // if not, add it!
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      MemoEdit(), MemoRead(), hb_MemoWrit()
   $END$
 */
