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

 listget()           Return a generic list item
------------------------------------------------------------------------------
 Declaration
   pick.hdr

 Syntax
   func uint listget extern
   param value _LIST pList, ;
         value ulong pData, ;
         value uint  uItem

 Arguments
   pList is a list pointer.
   pData is the address of a buffer for storing data retrieved from the list.
   uItem is the number of the list item to retrieve.

 Return
   The length of the retrieved item in bytes.

 Description
   The listget() function retrieves an item from a generic list. The
   buffer given by the pData parameter must be large enough to hold the
   data object extracted from the list. Use the listitemlen() function to
   determine the necessary buffer size.

 Example
   #define EXAMPLE_LIST
   #include example.hdr

   typedef struct CUST
      char( 10 ) cName      // member length is 10 + 1 = 11 bytes
      uint       nAge       // member length is 2 bytes
      logical    lPaid      // member length is 2 bytes
   enddef                   // total length is 15 (#defined below)
   
   proc Test_listget
   vardef
      CUST     sCust        // an instance of the structure
      _LIST    pList        // pointer to the list
      uint     n            // counter
   enddef
   pList := pickinit()      // allocate list from dynamic memory
   
   // a list (or array) of structures is generated dynamically
   for n := 1 to 10         // prepare data for ten structures one by one
      sCust.cName := chr( 'A' + n - 1 )     // generate a one-letter "name"
      sCust.nAge  := 30 + n                 // generate a number
      sCust.lPaid := n < 6                  // generate a logical
      listput( pList, &sCust, sizeof( sCust ) ) // add structure to the list
   next
   
   // use the list
   for n := 1 to 10
      listget( pList, &sCust, n )           // retrieve an element
      ? "Item #", padl( istr( n ), 2, ' ' ), ;         // print the data
         sCust.cName, istr( sCust.nAge ), sCust.lPaid
   next
   
   pickclear( pList )                       // get back memory
   endproc

   proc main
   Test_listget()
   endproc