Click above to get retro games delivered to your door ever month!

 V_STUFF()
 Delete and insert new data into an existing VLF
-------------------------------------------------------------------------------

 Syntax

    V_STUFF( <cOldPointer>,
             <nStart>,
             <nDelete>,
             <cNewString> )    ->    cNewPointer

 Arguments

    <cOldPointer> Is the pointer (usually stored in a DBF field),
    which points to the source string into which <cNewString> will be
    V_STUFF()ed.

    <nStart> is the starting position in the VLF where <cNewString>
    will be inserted.

    <nDelete> is the number of characters to delete from <cNewString>
    starting at <nStart>. Deletions are performed before insertions.

    <cNewString> is a string which will be inserted at the <nStart>
    position after the deletion of <nDelete> characters.

 Returns

    V_STUFF() returns a pointer which should be stored in the field
    with which the modified variable length data is to be associated.

    V_STUFF() returns (.F.) on error.  This causes the error system to
    be invoked with a "Data Type Mismatch".  Use V_ERROR() to fetch
    the specific error value (see Appendix B for a table of error
    descriptions).

 Description

    The V_STUFF() function works on VLFs much as Clipper's STUFF()
    works on strings. Working on VLFs, V_STUFF() will delete <nDelete>
    characters from the string pointed to by <cOldPointer> and then
    insert <cNewString> at the <nStart> position. V_STUFF() can,
    therefore, perform the following seven functions:

  . Insert: If <nDelete> is zero, V_STUFF() will not delete any
    characters before inserting <cNewString> at the <nStart> position.
    This effectively makes V_STUFF() an insert function.

  . Replace: If <nDelete> equals LEN( <cNewString> ), then
    V_STUFF() will effectively replace the data beginning at the
    <nStart> position. If the <cNewString> is always the same length
    as <nDelete> or if the comparison for equivalent length is easily
    tested, it is faster (less disk I/O) to use V_POKE().

  . Delete: If LEN( <cNewString> ) == 0 or <cNewString> is not
    passed, V_STUFF() will effectively delete <nDelete> characters
    beginning at the <nStart> position.

  . Replace and Insert: If <cNewString> is longer than <nDelete>,
    V_STUFF() will replace <nDelete> characters of the data pointed to
    by <cOldPointer> and insert the remaining length of <cNewString>.

  . Replace and Delete: If <cNewString> is shorter than <nDelete>,
    V_STUFF() will replace <nDelete> characters of the data pointed to
    by <cOldPointer> and then delete the remaining <nDelete>
    characters making the data shorter.

  . Replace and Delete rest: If <nDelete> is greater than or equal
    to the number of characters remaining after the <nStart> position
    of the data pointed to by <cOldPointer>, the old data is
    effectively trimmed at the <nStart> position before the
    <cNewString> is inserted.

  . Append: If <nStart> is equal to or greater than the length of
    the data pointed to by <cOldPointer>, the <nDelete> parameter is
    ignored and the <cNewString> data is appended to the end.

    +-------------------------- WARNING --------------------------+ 
    | V_STUFF() deletes the data associated with <cOldPointer>    | 
    | before returning <cNewPointer>.  Attempting to use          | 
    | <cOldPointer> after this function deletes the data that it  | 
    | points to can corrupt the DBV file.                         | 
    +-------------------------------------------------------------+ 

 Notes

    The big advantage to V_STUFF() is that its operation is disk based
    rather than memory based. This is, however, a double edged sword.
    On the one hand, it offers the ability to create a VLF that is
    larger than 65K (Clipper's largest character string size). On the
    other hand, if you are not aware that <cNewPointer> points to data
    that is larger than 65K, you may be surprised when V_RETRIEVE() or
    similar functions trim their return value to 65K.  Although
    V_RETRIEVE() can only return a maximum length of 65K, it can pick
    up any portion of a longer string as long as the portion itself is
    no longer than 65K (see V_REPLACE()).

    In all cases, V_STUFF() will move the data pointed to by
    <cOldPointer> to a new location in the DBV file. It is, therefore,
    less disk intensive to use V_POKE() where possible. V_POKE() does
    not delete or insert, but simply overwrites data leaving it at the
    same disk location within the DBV file.

 Examples

    // Open a DBF file and its associated DBV file.
    USE dbf_file
    V_USE( "dbv_file" )

    // Put a string away.
    cStr = "ABCDEF"
    REPLACE vlf WITH V_REPLACE( cStr, vlf )

    // Insert.
    REPLACE vlf WITH V_STUFF( vlf, 2, 0, 'xyz' )
    ? V_RETRIEVE( vlf )      // Result: AxyzBCDEF

    // Replace.
    REPLACE vlf WITH V_STUFF( vlf, 2, 3, 'qrs' )
    ? V_RETRIEVE( vlf )      // Result: AqrsBCDEF

    // Delete.
    REPLACE vlf WITH V_STUFF( vlf, 2, 3, '' )
    ? V_RETRIEVE( vlf )      // Result: ABCDEF

    // Replace and Insert.
    REPLACE vlf WITH V_STUFF( vlf, 2, 2, 'xyz' )
    ? V_RETRIEVE( vlf )      // Result: AxyzDEF

    // Replace and delete.
    REPLACE vlf WITH V_STUFF( vlf, 2, 4, 'qrs' )
    ? V_RETRIEVE( vlf )      // Result: AqrsEF

    // Replace and delete rest.
    REPLACE vlf WITH V_STUFF( vlf, 2, 10, 'xyz' )
    ? V_RETRIEVE( vlf )      // Result: Axyz

    // Append.
    REPLACE vlf WITH V_STUFF( vlf, 10, 0, 'qrs' )
    ? V_RETRIEVE( vlf )      // Result: Axyzqrs