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::ADD, item, index, $
AFTER=after, $
BEFORE=before, $
ERROR=error, $
NO_COPY=no_copy, $
REPLACE=replace
The ADD method adds a data item to the list.
Parameters
item: The data item to be added to the list. Required.
index: The location in the list where the data item is
to be added. If neither the AFTER or BEFORE keyword is
set, the item is added AFTER the item at the index location.
If index is missing, the index points to the last item in
the list. Optional.
Keywords
AFTER: If this keyword is set, the item is added after the
item at the current index.
BEFORE: If this keyword is set, the item is added before the
item at the current index.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
NO_COPY: If set, the item is transferred to the internal pointer using
a no copy method. This will cause the item variable to become undefined.
REPLACE: If this keyword is set, the item will replace the current item at
the index location.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::DELETE, index, ALL=all, DESTROY=destroy, ERROR=error
The DELETE method deletes an item from the list.
Parameters
index: The location in the list where the data item is
to be delete. If index is missing, the index points to
the last item in the list. Optional.
Keywords
ALL: If this keyword is set, all items in the list are deleted.
DESTROY: If the item at the node is an object or pointer, the
item will be destroyed before the node is deleted. This keyword
is turned on (set to 1) by default. Set to 0 to prevent destruction.
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::GET_COUNT
The GET_COUNT method returns the number of items in the list.
Return Value: The number of items stored in the linked list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_ITEM, index, $
ALL=all, $ ; This ASSUMES all items stored are the same type!!!
Dereference=dereference, $ ; Obsolete. Ignored. Always returns item.
ItemPtr=itemPtr, $ ; The pointer to the item, if needed. Output.
NO_COPY=no_copy, $ ; Copy from location with NO_COPY.
ERROR=errorMsg ; The error message. Null string if no error.
Parameters
index: The location in the list from which the data item is
to be retrieved. If not present, the last item in the list
is retrieved. Optional.
Keywords
DEREFERENCE: This keyword obsolete and only provided for backward compatibility.
ALL: Set this keyword to return an n-element array containing all the list
items. This requires that all list items be of the same type, and
if they are arrays, they have 7 dimensions or fewer. If index is passed,
it is ignored.
ITEMPTR: The pointer to the data item.
NO_COPY: If this keyword is set, the item is transferred from the data
pointer using a NO_COPY method. This will undefine the item at that
indexed locaton.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
Return Value: The data item at this index on the list.
If ALL is set, then an array containing all the data items is returned.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_NODE, index, ERROR=error
The GET_NODE method returns a pointer to the specified node
from the list. Parameters
index: The location in the list from which the data node is
to be retrieved. If not present, the last node in the list
is retrieved. The node is a structure with three fields:
Previous is a pointer to the previous node in the list.
Next is a pointer to the next node in the list. A null pointer
in the previous field indicates the first node on the list. A
null pointer in the next field indicates the last node on the
list. The item field is a pointer to the item stored in the
node. Optional.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
Return Value: A pointer to the specified node structure in
the linked list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::HELP, PRINT=print
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.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::MOVE_NODE, nodeIndex, location, BEFORE=before, ERROR=error
The MOVE_NODE method moves a list node from one location to another.
Parameters
nodeIndex: The location in the list of the node you are moving.
Required.
location: The location (index) you are moving the node to. If
location is missing, the location points to the node at the
end of the list.
Keywords
BEFORE: If this keyword is set, the node is added to the
list before the location node. Otherwise, it is added after
the location node.
ERROR: On return, if this is not a null string, an error occurred
and this value is set equal to the error message.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::REPLACE_ITEM, newItem, index, ERROR=error
Use 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=error
Use 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.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
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.