coyote: LINKEDLIST__DEFINE

NAME
LINKEDLIST
FILENAME
linkedlist__define.pro
PURPOSE
The purpose of this program is to implement a list that
is linked in both the forward and backward directions. There
is no restriction as to what can be stored in a linked list
node. The linked list is implemented as an object.
AUTHOR
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: david@idlcoyote.com
Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
CATEGORY
General programming.
CALLING SEQUENCE
mylist = Obj_New('LINKEDLIST', item)
OPTIONAL INPUTS
item: The first item added to the list. Items can be any
  valid IDL variable type.
COMMON BLOCKS
Are you kidding?!
RESTRICTIONS
Be sure to destroy the LINKEDLIST object when you are finished
with it: Obj_Destroy, mylist
Node index numbers start at 0 and go to n-1, where n is the
number of items in the list.
PUBLIC METHODS
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST
:REPLACE_ITEM, newItem, index, ERROR=errorUse this method to replace any item in the list with any other value.
This allows the caller to change an item without stepping through the
process of deleting an item then adding a new one.
Parameters:
   index:  The location of the node you are replacing
   newItem:  Any value of any data type.
  ERROR: On return, if this is not a null string, an error occurred
    and this value is set equal to the error message.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST
:HAVE_ITEM, index, ERROR=errorUse this method to check to see if an item exits at a particular location
on the list. Returns a 1 if the item is there, otherwise a 0.
Parameters:
   index:  The location of the node you are replacing
  ERROR: On return, if this is not a null string, an error occurred
    and this value is set equal to the error message.
The HELP method performs a HELP command on each item
in the linked list.
Keywords:
 PRINT: If this keyword is set, the PRINT command is used
   instead of the HELP command on the items in the list.
EXAMPLE
mylist = Obj_New("LINKEDLIST", 5)
mylist->Add, 10
mylist->Add, 7, 1, /Before
mylist->Add, 12
print, mylist->Get_Item(/All)
mylist->Add, 'Bob', 2, /Replace
mylist->Help
mylist->Delete, 0
mylist->Help, /Print
MODIFICATION HISTORY
Written by: David Fanning, 25 August 98.
25 August 99. Fixed several errors in various methods dealing with
    moving nodes from one place to another. DWF.
13 June 2001. DWF. Added DEREFERENCE to the GET_ITEM method to
    return the item itself, instead of the pointer to the item.
27 June 2001 Added REPLACE_ITEM method.  Ben Tupper.
7 April 2003. Added DESTROY keyword to DELETE method so that objects
   and pointers could be cleaned up properly when they are deleted
   from the linked list. DWF.
9 April 2003. Fixed a problem that occurs when deleting the last node. DWF.
3 Feb 2004. Make sure loop index vars are long.  Jeff Guerber
30 Jun 2004.  Added /ALL to GET_ITEM function.  Henry Throop, SWRI.
23 Nov 2004.  Fixed GET_ITEM, /ALL to accomodate structures and empty
   lists.  Henry Throop.
21 February 2011. A complete refurbishing to incorporate changes and to fix bugs
   I found in the SolarSoft version of this code. I've tried to make this compatible
   with the version distributed with SolarSoft to reduce problems caused by two versions
   of the software with the same name.
 9 December 2011. Fixed a problem with the ALL keyword on the Get_Item method. DWF.