CWIS Developer Documentation
Public Member Functions | Public Attributes | List of all members
PersistentDoublyLinkedList Class Reference

Persistent doubly-linked-list data structure, with its data stored in a specified database table. More...

Public Member Functions

 __construct ($ItemTableName, $ItemIdFieldName, $SqlCondition=NULL, $ItemTypeFieldName=NULL)
 Object constructor. More...
 
 SqlCondition ($Condition=NULL)
 Get or set/update SQL condition for referencing items in database. More...
 
 InsertBefore ($TargetItemOrItemId, $NewItemOrItemId, $TargetItemType=NULL, $NewItemType=NULL)
 Insert item into list before specified item. More...
 
 InsertAfter ($TargetItemOrItemId, $NewItemOrItemId, $TargetItemType=NULL, $NewItemType=NULL)
 Insert item into list after specified item. More...
 
 Prepend ($ItemOrItemId, $ItemType=NULL)
 Add item to beginning of list. More...
 
 Append ($ItemsOrItemIds, $ItemTypes=NULL)
 Add item(s) to end of list. More...
 
 GetIds ()
 Retrieve array of IDs of items in list, in the order that they appear in the list. More...
 
 GetCount ()
 Get number of items in list. More...
 
 Remove ($ItemId, $ItemType=NULL)
 Remove item from list. More...
 

Public Attributes

const UNINITIALIZED_ID = -1
 
const LISTEND_ID = -2
 

Detailed Description

Persistent doubly-linked-list data structure, with its data stored in a specified database table.

The specified table is usually also being used to store other information about the items being referenced by the list. Items in the list are assumed to have associated unique IDs, and anywhere item objects are passed in as parameters, the objects are assumed to have Id() methods that can be used to retrieve their associated IDs. More than one type of item can be included in a list, by use of the (optional) item type parameters. (Item IDs and types are assumed to be positive integers.)

Definition at line 21 of file PersistentDoublyLinkedList.php.

Constructor & Destructor Documentation

PersistentDoublyLinkedList::__construct (   $ItemTableName,
  $ItemIdFieldName,
  $SqlCondition = NULL,
  $ItemTypeFieldName = NULL 
)

Object constructor.

The specified database table must include an INT field containing IDs for the items being managed, and two other INT fields that have the same name with "Previous" and "Next" prepended to it (e.g. "ItemId", "PreviousItemId", and "NextItemId"). These additional INT fields should have a default value of -1. If mixed item types are to be included in the list, then the table must also include an INT field for the types of the items being managed, and two other INT fields that have the same name with "Previous" and "Next" prepended ("ItemType", "PreviousItemType", "NextItemType").

Parameters
string$ItemTableNameDatabase table in which to store list information.
string$ItemIdFieldNameDatabase field name for item IDs.
string$SqlConditionSQL condition for referencing items in database. (OPTIONAL) This is intended to be used to specify a conditional clause to be added to any SQL statements that are used to store or retrieve information about items within the list, usually with the goal of information about multiple lists being stored in the same table in the database. The condition should not include a leading WHERE or other leading SQL clause joining operator.
string$ItemTypeFieldNameDatabase field name for item types. (OPTIONAL)
See also
PersistentDoublyLinkedList::SqlCondition()

Definition at line 48 of file PersistentDoublyLinkedList.php.

References SqlCondition().

Member Function Documentation

PersistentDoublyLinkedList::Append (   $ItemsOrItemIds,
  $ItemTypes = NULL 
)

Add item(s) to end of list.

If an item is already present in the list, it is moved to the end of the list.

Parameters
mixed$ItemsOrItemIdsItem or array of items to add.
int$ItemTypesNumerical type of item or array of types of items to add. If supplied, the type(s) must either match whatever is supplied for the item ID(s)/object(s), or a single item type may be specified, which will be assumed for all items. (OPTIONAL)

Definition at line 261 of file PersistentDoublyLinkedList.php.

References GetIds(), and Remove().

Referenced by InsertAfter().

Here is the caller graph for this function:

PersistentDoublyLinkedList::GetCount ( )

Get number of items in list.

Returns
int Count of items in list.

Definition at line 461 of file PersistentDoublyLinkedList.php.

References GetIds().

PersistentDoublyLinkedList::GetIds ( )

Retrieve array of IDs of items in list, in the order that they appear in the list.

Returns
Array of item IDs or (if mixed-item-type list) item IDs and types. When returning IDs and types, each element in the returned array is an associative array, with the indexes "ID" and "Type".

Definition at line 361 of file PersistentDoublyLinkedList.php.

References SqlCondition().

Referenced by Append(), GetCount(), and Prepend().

Here is the caller graph for this function:

PersistentDoublyLinkedList::InsertAfter (   $TargetItemOrItemId,
  $NewItemOrItemId,
  $TargetItemType = NULL,
  $NewItemType = NULL 
)

Insert item into list after specified item.

If the item is already present in the list, it is moved to the new location. If the target item is not found, the new item is added to the end of the list.

Parameters
mixed$TargetItemOrItemIdItem to insert after.
mixed$NewItemOrItemIdItem to insert.
int$TargetItemTypeType of item to insert after. (OPTIONAL)
int$NewItemTypeType of item to insert. (OPTIONAL)

Definition at line 150 of file PersistentDoublyLinkedList.php.

References Append(), and Remove().

PersistentDoublyLinkedList::InsertBefore (   $TargetItemOrItemId,
  $NewItemOrItemId,
  $TargetItemType = NULL,
  $NewItemType = NULL 
)

Insert item into list before specified item.

If the item is already present in the list, it is moved to the new location. If the target item is not found, the new item is added to the beginning of the list.

Parameters
mixed$TargetItemOrItemIdItem to insert before.
mixed$NewItemOrItemIdItem to insert.
int$TargetItemTypeType of item to insert before. (OPTIONAL)
int$NewItemTypeType of item to insert. (OPTIONAL)

Definition at line 88 of file PersistentDoublyLinkedList.php.

References Prepend(), and Remove().

PersistentDoublyLinkedList::Prepend (   $ItemOrItemId,
  $ItemType = NULL 
)

Add item to beginning of list.

If the item is already present in the list, it is moved to the new location.

Parameters
mixed$ItemOrItemIdItem to add.
int$ItemTypeNumerical type of item to add. (OPTIONAL)

Definition at line 210 of file PersistentDoublyLinkedList.php.

References GetIds(), and Remove().

Referenced by InsertBefore().

Here is the caller graph for this function:

PersistentDoublyLinkedList::Remove (   $ItemId,
  $ItemType = NULL 
)

Remove item from list.

If the item is not currently present in the list, then the call has no effect.

Parameters
int$ItemIdID of item to be removed.
int$ItemTypeNumerical type of item to be removed.
Returns
bool TRUE if item was removed or FALSE if item was not found.

Definition at line 474 of file PersistentDoublyLinkedList.php.

Referenced by Append(), InsertAfter(), InsertBefore(), and Prepend().

Here is the caller graph for this function:

PersistentDoublyLinkedList::SqlCondition (   $Condition = NULL)

Get or set/update SQL condition for referencing items in database.

This is intended to be used to specify a conditional clause to be added to any SQL statements that are used to store or retrieve information about items within the list, usually with the goal of information about multiple lists being stored in the same table in the database. The condition should not include a leading WHERE or other leading SQL clause joining operator.

Parameters
string$ConditionNew SQL condition clause. (OPTIONAL)
Returns
string Current SQL condition clause or NULL if no clause set.

Definition at line 73 of file PersistentDoublyLinkedList.php.

Referenced by __construct(), and GetIds().

Here is the caller graph for this function:

Member Data Documentation

const PersistentDoublyLinkedList::LISTEND_ID = -2

Definition at line 543 of file PersistentDoublyLinkedList.php.

const PersistentDoublyLinkedList::UNINITIALIZED_ID = -1

Definition at line 542 of file PersistentDoublyLinkedList.php.


The documentation for this class was generated from the following file: