Loyc.Collections.Impl.IAListTreeObserver< K, T > Interface Template Reference

An interface that is called to notify observers when items or nodes in the tree of a class derived from AListBase<K,T> (e.g. AList or BList) are added or removed. More...

---

Source file:

• /Core/Loyc.Collections/ALists/IAListTreeObserver.cs

Inheritance diagram for Loyc.Collections.Impl.IAListTreeObserver< K, T >:

Remarks

An interface that is called to notify observers when items or nodes in the tree of a class derived from AListBase<K,T> (e.g. AList or BList) are added or removed.

Template Parameters

K
T

This interface is useful for keeping track of information about a collection that is impossible to track efficiently by any other means. It can be used to:

• - Maintain an inverse dictionary of items in an AList, so you can get the (integer) index of an item in O(log N) time. This was the original purpose for which the observer idea was developed.
• - Keep certain statistics about an unsorted list up-to-date efficiently, such as the maximum, minimum or average.
• - Connect AList/BList to Update Controls.

An observer object should be attached to only one list, because change notifications do not indicate which list is being changed.

When an A-list is cloned, observers do are not included in the clone.

IMPORTANT: unless otherwise noted, implementations of this interface must not throw exceptions because these methods are called during operations in progress. If you throw an exception, the tree can be left in an invalid state. Attach() can safety throw, but the exception will propagate out of the AListBase<K,T>.AddObserver method.

Public Member Functions
bool?	Attach (AListBase< K, T > list)
	Called when the observer is being attached to an AList. More...
void	Detach (AListBase< K, T > list, AListNode< K, T > root)
	Called when the observer is being detached from an AList. Detach(), unlike Attach(), is not paired with a call to RootChanged. More...
void	RootChanged (AListBase< K, T > list, AListNode< K, T > root, bool clear)
	Called when the root of the tree changes, or when the list is cleared. Also called after Attach(), but not after Detach(). More...
void	ItemAdded (T item, AListLeafBase< K, T > parent)
	Called when an item is added to a leaf node. More...
void	ItemRemoved (T item, AListLeafBase< K, T > parent)
	Called when an item is removed from a leaf node. More...
void	NodeAdded (AListNode< K, T > child, AListInnerBase< K, T > parent)
	Called when a child node is added to an inner node. More...
void	NodeRemoved (AListNode< K, T > child, AListInnerBase< K, T > parent)
	Called when a child node is removed from an inner node. More...
void	RemoveAll (AListNode< K, T > node)
	Called when all children are being removed from a node (leaf or inner) because the node is being split (AddAll will be called afterward for the two replacement nodes). Notifications are not sent for individual children. More...
void	AddAll (AListNode< K, T > node)
	Called when all children are being added to a node (leaf or inner). Notifications are not sent for individual children. More...
void	CheckPoint ()
	Called when a tree modification operation is completed. More...

Member Function Documentation

AddAll()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.AddAll

(

AListNode< K, T >

node

)

Called when all children are being added to a node (leaf or inner). Notifications are not sent for individual children.

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

Attach()

bool? Loyc.Collections.Impl.IAListTreeObserver< K, T >.Attach

(

AListBase< K, T >

list

)

Called when the observer is being attached to an AList.

Parameters

list	The list that the observer is being attached to.

Returns

Return true or false to cause notifications to be sent about all the nodes in the tree, via a depth-first search that calls AddAll for each node in the tree. Return true if you want AddAll to be called for children before their parents (roughly, leaves first). Use False if you want AddAll to be called for inner nodes before their children. If you return null, no notifications are sent except for RootChanged which will be called unconditionally.

If Attach() throws an exception, AListBase<K,T> will cancel the AddObserver() operation and it will not catch the exception.

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

CheckPoint()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.CheckPoint

(

)

Called when a tree modification operation is completed.

This is called after each modification operation (Add, Insert, Remove, Replace, etc.); the list will normally be in a read-only state ("frozen for concurrency") when this method is called, so do not initiate changes from here.

This method can safely throw an exception, and the list class will not swallow it. Note: if there are multiple observers, throwing an exception from one observers will prevent this notification from reaching other observers that have not been notified yet.

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

Detach()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.Detach	(	AListBase< K, T >	list,
		AListNode< K, T >	root
	)

Called when the observer is being detached from an AList. Detach(), unlike Attach(), is not paired with a call to RootChanged.

Parameters

list	List that is being detached.
root	Root node that is being detached.

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

Referenced by Loyc.Collections.AListBase< K, T >.RemoveObserver().

ItemAdded()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.ItemAdded	(	T	item,
		AListLeafBase< K, T >	parent
	)

Called when an item is added to a leaf node.

Note: this may be called as part of a move operation (remove+add)

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

ItemRemoved()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.ItemRemoved	(	T	item,
		AListLeafBase< K, T >	parent
	)

Called when an item is removed from a leaf node.

Note: this may be called as part of a move operation (remove+add)

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

NodeAdded()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.NodeAdded	(	AListNode< K, T >	child,
		AListInnerBase< K, T >	parent
	)

Called when a child node is added to an inner node.

Note: this may be called as part of a move operation (remove+add)

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

NodeRemoved()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.NodeRemoved	(	AListNode< K, T >	child,
		AListInnerBase< K, T >	parent
	)

Called when a child node is removed from an inner node.

Note: this may be called as part of a move operation (remove+add)

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

Referenced by Loyc.Collections.Impl.AListInnerBase< int, T >.HandleUndersized().

RemoveAll()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.RemoveAll

(

AListNode< K, T >

node

)

Called when all children are being removed from a node (leaf or inner) because the node is being split (AddAll will be called afterward for the two replacement nodes). Notifications are not sent for individual children.

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.

RootChanged()

void Loyc.Collections.Impl.IAListTreeObserver< K, T >.RootChanged	(	AListBase< K, T >	list,
		AListNode< K, T >	root,
		bool	clear
	)

Called when the root of the tree changes, or when the list is cleared. Also called after Attach(), but not after Detach().

Parameters

clear	true if the root is changing due to a Clear() operation. If this parameter is true, the observer should clear its own state. If this parameter is false but newRoot is null, it means that the list was cleared by removing all the items (rather than by calling Clear() on the list). In that case, if the observer still believes that any items exist in leaf nodes, it means that there is a bookkeeping error somewhere.
list	The list that changed.
root	The new root (null if the tree is cleared).

Implemented in Loyc.Collections.Impl.AListIndexer< K, T >, and Loyc.Collections.AListBase< K, T >.ObserverMgr.