* Added doxygen comments.

* Moved the index returning/expecting methods into a private section and
  implemented a Iterator class.


git-svn-id: file:///srv/svn/repos/haiku/trunk/current@494 a95241bf-73f2-0310-859d-f6bbb57e9c96

src/servers/registrar/AppInfoList.cpp

@@ -27,13 +27,30 @@
 #include "AppInfoList.h"
 #include "RosterAppInfo.h"
 
+/*!
+	\class AppInfoList
+	\brief A list of RosterAppInfos.
+
+	Features adding/removing of RosterAppInfos and method for finding
+	infos by signature, team ID, entry_ref or token.
+	The method It() returns an iterator, an instance of the basic
+	AppInfoList::Iterator class.
+*/
+
+
 // constructor
+/*!	\brief Creates an empty list.
+*/
 AppInfoList::AppInfoList()
 		   : fInfos()
 {
 }
 
-// constructor
+// destructor
+/*!	\brief Frees all resources associated with this object.
+
+	The RosterAppInfos the list contains are deleted.
+*/
 AppInfoList::~AppInfoList()
 {
 	// delete all infos
@@ -42,6 +59,11 @@ AppInfoList::~AppInfoList()
 }
 
 // AddInfo
+/*!	\brief Adds a RosterAppInfos to the list.
+	\param info The RosterAppInfo to be added
+	\return \c true on success, false if \a info is \c NULL or there's not
+			enough memory for this operation.
+*/
 bool
 AppInfoList::AddInfo(RosterAppInfo *info)
 {
@@ -52,20 +74,128 @@ AppInfoList::AddInfo(RosterAppInfo *info)
 }
 
 // RemoveInfo
-RosterAppInfo *
+/*!	\brief Removes a RosterAppInfos from the list.
-AppInfoList::RemoveInfo(int32 index)
+	\param info The RosterAppInfo to be removed
-{
+	\return \c true on success, false if \a info was not in the list.
-	return (RosterAppInfo*)fInfos.RemoveItem(index);
+*/
-}
-
-// RemoveInfo
 bool
 AppInfoList::RemoveInfo(RosterAppInfo *info)
 {
 	return fInfos.RemoveItem(info);
 }
 
+// InfoFor
+/*!	\brief Returns the RosterAppInfo with the supplied signature.
+
+	If the list contains more than one RosterAppInfo with the given signature,
+	it is undefined, which one is returned.
+
+	\param signature The signature
+	\return A RosterAppInfo with the supplied signature, or \c NULL, if
+			\a signature is \c NULL or the list doesn't contain an info with
+			this signature.
+*/
+RosterAppInfo *
+AppInfoList::InfoFor(const char *signature) const
+{
+	return InfoAt(IndexOf(signature));
+}
+
+// InfoFor
+/*!	\brief Returns the RosterAppInfo with the supplied team ID.
+	\param team The team ID
+	\return A RosterAppInfo with the supplied team ID, or \c NULL, if the list
+			doesn't contain an info with this team ID.
+*/
+RosterAppInfo *
+AppInfoList::InfoFor(team_id team) const
+{
+	return InfoAt(IndexOf(team));
+}
+
+// InfoFor
+/*!	\brief Returns the RosterAppInfo with the supplied entry_ref.
+
+	If the list contains more than one RosterAppInfo with the given entry_ref,
+	it is undefined, which one is returned.
+
+	\param ref The entry_ref
+	\return A RosterAppInfo with the supplied entry_ref, or \c NULL, if
+			\a ref is \c NULL or the list doesn't contain an info with
+			this entry_ref.
+*/
+RosterAppInfo *
+AppInfoList::InfoFor(const entry_ref *ref) const
+{
+	return InfoAt(IndexOf(ref));
+}
+
+// InfoForToken
+/*!	\brief Returns the RosterAppInfo with the supplied token.
+
+	If the list contains more than one RosterAppInfo with the given token,
+	it is undefined, which one is returned.
+
+	\param token The token
+	\return A RosterAppInfo with the supplied token, or \c NULL, if the list
+			doesn't contain an info with the token.
+*/
+RosterAppInfo *
+AppInfoList::InfoForToken(uint32 token) const
+{
+	return InfoAt(IndexOfToken(token));
+}
+
+// CountInfos
+/*!	\brief Returns the number of RosterAppInfos this list contains.
+	\return The number of RosterAppInfos this list contains.
+*/
+int32
+AppInfoList::CountInfos() const
+{
+	return fInfos.CountItems();
+}
+
+// It
+/*!	\brief Returns a list iterator.
+	\return A list iterator.
+*/
+AppInfoList::Iterator
+AppInfoList::It()
+{
+	return Iterator(this, 0);
+}
+
+// RemoveInfo
+/*!	\brief Removes a RosterAppInfo at a given index.
+	\param index The index of the info to be removed
+	\return A pointer to the removed RosterAppInfo, or \c NULL, if the index
+			is out of range.
+*/
+RosterAppInfo *
+AppInfoList::RemoveInfo(int32 index)
+{
+	return (RosterAppInfo*)fInfos.RemoveItem(index);
+}
+
+// InfoAt
+/*!	\brief Returns a RosterAppInfo at a given index.
+	\param index The index of the info to be returned
+	\return A pointer to the RosterAppInfo, or \c NULL, if the index
+			is out of range.
+*/
+RosterAppInfo *
+AppInfoList::InfoAt(int32 index) const
+{
+	return (RosterAppInfo*)fInfos.ItemAt(index);
+}
+
 // IndexOf
+/*!	\brief Returns the list index of the supplied RosterAppInfo.
+	\param info The RosterAppInfo in question
+	\return The index of the supplied info, or -1, if \a info is \c NULL or not
+			contained in the list.
+*/
 int32
 AppInfoList::IndexOf(RosterAppInfo *info) const
 {
@@ -73,17 +203,36 @@ AppInfoList::IndexOf(RosterAppInfo *info) const
 }
 
 // IndexOf
+/*!	\brief Returns the list index of a RosterAppInfo with the supplied
+		   signature.
+
+	If the list contains more than one RosterAppInfo with the given signature,
+	it is undefined, which one is returned.
+
+	\param signature The signature
+	\return The index of the found RosterAppInfo, or -1, if \a signature is
+			\c NULL or the list doesn't contain an info with this signature.
+*/
 int32
 AppInfoList::IndexOf(const char *signature) const
 {
-	for (int32 i = 0; RosterAppInfo *info = InfoAt(i); i++) {
+	if (signature) {
-		if (!strcmp(info->signature, signature))
+		for (int32 i = 0; RosterAppInfo *info = InfoAt(i); i++) {
-			return i;
+			if (!strcmp(info->signature, signature))
+				return i;
+		}
 	}
 	return -1;
 }
 
 // IndexOf
+/*!	\brief Returns the list index of a RosterAppInfo with the supplied
+		   team ID.
+
+	\param team The team ID
+	\return The index of the found RosterAppInfo, or -1, if the list doesn't
+			contain an info with this team ID.
+*/
 int32
 AppInfoList::IndexOf(team_id team) const
 {
@@ -95,17 +244,36 @@ AppInfoList::IndexOf(team_id team) const
 }
 
 // IndexOf
+/*!	\brief Returns the list index of a RosterAppInfo with the supplied
+		   entry_ref.
+
+	If the list contains more than one RosterAppInfo with the given entry_ref,
+	it is undefined, which one is returned.
+
+	\param ref The entry_ref
+	\return The index of the found RosterAppInfo, or -1, if \a ref is
+			\c NULL or the list doesn't contain an info with this entry_ref.
+*/
 int32
 AppInfoList::IndexOf(const entry_ref *ref) const
 {
-	for (int32 i = 0; RosterAppInfo *info = InfoAt(i); i++) {
+	if (ref) {
-		if (info->ref == *ref)
+		for (int32 i = 0; RosterAppInfo *info = InfoAt(i); i++) {
-			return i;
+			if (info->ref == *ref)
+				return i;
+		}
 	}
 	return -1;
 }
 
 // IndexOfToken
+/*!	\brief Returns the list index of a RosterAppInfo with the supplied
+		   token.
+
+	\param token The token
+	\return The index of the found RosterAppInfo, or -1, if the list doesn't
+			contain an info with this token.
+*/
 int32
 AppInfoList::IndexOfToken(uint32 token) const
 {
@@ -116,45 +284,3 @@ AppInfoList::IndexOfToken(uint32 token) const
 	return -1;
 }
 
-// InfoAt
-RosterAppInfo *
-AppInfoList::InfoAt(int32 index) const
-{
-	return (RosterAppInfo*)fInfos.ItemAt(index);
-}
-
-// InfoFor
-RosterAppInfo *
-AppInfoList::InfoFor(const char *signature) const
-{
-	return InfoAt(IndexOf(signature));
-}
-
-// InfoFor
-RosterAppInfo *
-AppInfoList::InfoFor(team_id team) const
-{
-	return InfoAt(IndexOf(team));
-}
-
-// InfoFor
-RosterAppInfo *
-AppInfoList::InfoFor(const entry_ref *ref) const
-{
-	return InfoAt(IndexOf(ref));
-}
-
-// InfoForToken
-RosterAppInfo *
-AppInfoList::InfoForToken(uint32 token) const
-{
-	return InfoAt(IndexOfToken(token));
-}
-
-// CountInfos
-int32
-AppInfoList::CountInfos() const
-{
-	return fInfos.CountItems();
-}
-

src/servers/registrar/AppInfoList.h

@@ -34,23 +34,18 @@ class entry_ref;
 
 class RosterAppInfo;
 
+// AppInfoList
 class AppInfoList {
+public:
+	class Iterator;
+
 public:
 	AppInfoList();
 	virtual ~AppInfoList();
 
 	bool AddInfo(RosterAppInfo *info);
-
-	RosterAppInfo *RemoveInfo(int32 index);
 	bool RemoveInfo(RosterAppInfo *info);
 
-	int32 IndexOf(RosterAppInfo *info) const;
-	int32 IndexOf(const char *signature) const;
-	int32 IndexOf(team_id team) const;
-	int32 IndexOf(const entry_ref *ref) const;
-	int32 IndexOfToken(uint32 token) const;
-
-	RosterAppInfo *InfoAt(int32 index) const;
 	RosterAppInfo *InfoFor(const char *signature) const;
 	RosterAppInfo *InfoFor(team_id team) const;
 	RosterAppInfo *InfoFor(const entry_ref *ref) const;
@@ -58,8 +53,111 @@ public:
 
 	int32 CountInfos() const;
 
+	Iterator It();
+
+private:
+	RosterAppInfo *RemoveInfo(int32 index);
+
+	RosterAppInfo *InfoAt(int32 index) const;
+
+	int32 IndexOf(RosterAppInfo *info) const;
+	int32 IndexOf(const char *signature) const;
+	int32 IndexOf(team_id team) const;
+	int32 IndexOf(const entry_ref *ref) const;
+	int32 IndexOfToken(uint32 token) const;
+
+private:
+	friend class Iterator;
+
 private:
 	BList	fInfos;
 };
 
+// AppInfoList::Iterator
+class AppInfoList::Iterator {
+public:
+	inline Iterator(const Iterator &it)
+		: fList(it.fList),
+		  fIndex(it.fIndex),
+		  fCount(it.fCount)
+	{
+	}
+
+	inline ~Iterator() {}
+
+	inline bool IsValid() const
+	{
+		return (fIndex >= 0 && fIndex < fCount);
+	}
+
+	inline RosterAppInfo *Remove()
+	{
+		RosterAppInfo *info = fList->RemoveInfo(fIndex);
+		if (info)
+			fCount--;
+		return info;
+	}
+
+	inline Iterator &operator=(const Iterator &it)
+	{
+		fList = it.fList;
+		fIndex = it.fIndex;
+		fCount = it.fCount;
+		return *this;
+	}
+
+	inline Iterator &operator++()
+	{
+		fIndex++;
+		return *this;
+	}
+
+	inline Iterator operator++(int)
+	{
+		return Iterator(fList, fIndex + 1);
+	}
+
+	inline Iterator &operator--()
+	{
+		fIndex--;
+		return *this;
+	}
+
+	inline Iterator operator--(int)
+	{
+		return Iterator(fList, fIndex - 1);
+	}
+
+	inline bool operator==(const Iterator &it) const
+	{
+		return (fList == it.fList && fIndex == it.fIndex);
+	}
+
+	inline bool operator!=(const Iterator &it) const
+	{
+		return !(*this == it);
+	}
+
+	inline RosterAppInfo *operator*() const
+	{
+		return fList->InfoAt(fIndex);
+	}
+
+private:
+	friend class AppInfoList;
+
+private:
+	inline Iterator(AppInfoList *list, int32 index = 0)
+		: fList(list),
+		  fIndex(index),
+		  fCount(list->CountInfos())
+	{
+	}
+
+private:
+	AppInfoList	*fList;
+	int32		fIndex;
+	int32		fCount;
+};
+
 #endif	// APP_INFO_LIST_H