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

 _itemFreeC()
 Frees a character string allocated by the Item API
------------------------------------------------------------------------------
 C Prototype

     #include "item.api"
     BOOL _itemFreeC(
                      BYTEP fpItemVal
                    )

 Arguments

     fpItemVal is a pointer returned by the Item API in response to an
     _itemGetC() call.

 Returns

     True if requested pointer was released.

 Description

     When _itemGetC() is asked to provide a character string from a character
     Item, it allocates memory for the string from one of several places.
     You need to call the _itemFreeC() function to release the memory once
     the string is no longer necessary.

     Warning!  Do not call _itemFreeC() unless the character string
     was retrieved through _itemGetC().  Calling _itemFreeC() with a NULL
     pointer, a pointer already freed, or a string not retrieved by
     _itemGetC() will result in a VM Integrity fault or other internal error.

 Examples

     /*
     *
     * CharCount( cString, cChar )
     *
     * Count occurrences of a single character
     * in a CA-Clipper string.  Version 1.00
     *
     */

     CLIPPER CharCount( void )
     {
        USHORT uiChars = 0;
        USHORT uiLen;
        USHORT i;
        HANDLE vmhString;

        BYTEP  cStringP;
        BYTE   cFindMe;

        ITEM   itemString, itemFindMe, itemRet;

        if (PCOUNT != 2)
        {
           _ret();               // NOTE: Withhold service
           return;               // Early return!
        }

        itemRet    = _itemPutNL( NULL, 0 );
        itemString = _itemParam( 1 );
        itemFindMe = _itemParam( 2 );

        if ( (_itemType( itemString ) == CHARACTER) &&
              (_itemType( itemFindMe ) == CHARACTER) )
        {
           _itemCopyC( itemFindMe, &cFindMe, 1 );

           vmhString = _xvalloc( _itemSize( itemString ), NULL );
           cStringP = _xvlock( vmhString );

           uiLen = _itemCopyC( itemString, cStringP, NULL );

           for( i = 0; i < uiLen; i++ )
           {
              if ( cStringP[i] == cFindMe )
                 uiChars++;
           }

           _xvunlock( vmhString );
           _xvfree( vmhString );

           itemRet = _itemPutNL( itemRet, (long)uiChars );

        }

        _itemReturn( itemRet );

        _itemRelease( itemRet );
        _itemRelease( itemString );
        _itemRelease( itemFindMe );

        return;
     }

 Files:  Library is CLIPPER.LIB, header file is Item.api.