patch [#34103] - listbase.patch, insertlinkbefore.patch

from Lawrence D'Oliveiro (ldo) 


notes from tracker:
use bool for return type from BLI_remlink_safe, necessitating including BLI_utildefines.h in BLI_listbase.h
get rid of duplicate BLI_insertlink, use BLI_insertlinkafter instead.

A few places which were using BLI_insertlinkafter (actually BLI_insertlink), when it would be simpler to use BLI_insertlinkbefore instead.

1 files changed, 90 insertions, 50 deletions

diff --git a/source/blender/blenlib/intern/listbase.c b/source/blender/blenlib/intern/listbase.c
index c60a9ae6bfc..348efaf40a9 100644
--- a/source/blender/blenlib/intern/listbase.c
+++ b/source/blender/blenlib/intern/listbase.c
@@ -28,9 +28,10 @@
 
 /** \file blender/blenlib/intern/listbase.c
  *  \ingroup bli
+ *
+ * Manipulations on ListBase structs
  */
 
-
 #include <string.h>
 #include <stdlib.h>
 
@@ -41,10 +42,11 @@
 
 #include "BLI_listbase.h"
 
-
 /* implementation */
 
-/* Ripped this from blender.c */
+/**
+ * moves the entire contents of \a src onto the end of \a dst.
+ */
 void BLI_movelisttolist(ListBase *dst, ListBase *src)
 {
 	if (src->first == NULL) return;
@@ -61,6 +63,9 @@ void BLI_movelisttolist(ListBase *dst, ListBase *src)
 	src->first = src->last = NULL;
 }
 
+/**
+ * Prepends \a vlink (assumed to begin with a Link) onto listbase.
+ */
 void BLI_addhead(ListBase *listbase, void *vlink)
 {
 	Link *link = vlink;
@@ -77,6 +82,9 @@ void BLI_addhead(ListBase *listbase, void *vlink)
 }
 
 
+/**
+ * Appends \a vlink (assumed to begin with a Link) onto listbase.
+ */
 void BLI_addtail(ListBase *listbase, void *vlink)
 {
 	Link *link = vlink;
@@ -93,6 +101,9 @@ void BLI_addtail(ListBase *listbase, void *vlink)
 }
 
 
+/**
+ * Removes \a vlink from \a listbase. Assumes it is linked into there!
+ */
 void BLI_remlink(ListBase *listbase, void *vlink)
 {
 	Link *link = vlink;
@@ -107,18 +118,24 @@ void BLI_remlink(ListBase *listbase, void *vlink)
 	if (listbase->first == link) listbase->first = link->next;
 }
 
-int BLI_remlink_safe(ListBase *listbase, void *vlink)
+/**
+ * Checks that \a vlink is linked into listbase, removing it from there if so.
+ */
+bool BLI_remlink_safe(ListBase *listbase, void *vlink)
 {
 	if (BLI_findindex(listbase, vlink) != -1) {
 		BLI_remlink(listbase, vlink);
-		return 1;
+		return true;
 	}
 	else {
-		return 0;
+		return false;
 	}
 }
 
 
+/**
+ * Removes \a vlink from listbase and disposes of it. Assumes it is linked into there!
+ */
 void BLI_freelinkN(ListBase *listbase, void *vlink)
 {
 	Link *link = vlink;
@@ -131,43 +148,11 @@ void BLI_freelinkN(ListBase *listbase, void *vlink)
 }
 
 
-void BLI_insertlink(ListBase *listbase, void *vprevlink, void *vnewlink)
-{
-	Link *prevlink = vprevlink;
-	Link *newlink = vnewlink;
-
-	/* newlink comes after prevlink */
-	if (newlink == NULL) return;
-	if (listbase == NULL) return;
-	
-	/* empty list */
-	if (listbase->first == NULL) {
-		
-		listbase->first = newlink;
-		listbase->last = newlink;
-		return;
-	}
-	
-	/* insert before first element */
-	if (prevlink == NULL) {
-		newlink->next = listbase->first;
-		newlink->prev = NULL;
-		newlink->next->prev = newlink;
-		listbase->first = newlink;
-		return;
-	}
-
-	/* at end of list */
-	if (listbase->last == prevlink)
-		listbase->last = newlink;
-
-	newlink->next = prevlink->next;
-	prevlink->next = newlink;
-	if (newlink->next) newlink->next->prev = newlink;
-	newlink->prev = prevlink;
-}
-
-/* This uses insertion sort, so NOT ok for large list */
+/**
+ * Sorts the elements of listbase into the order defined by cmp
+ * (which should return 1 iff its first arg should come after its second arg).
+ * This uses insertion sort, so NOT ok for large list.
+ */
 void BLI_sortlist(ListBase *listbase, int (*cmp)(void *, void *))
 {
 	Link *current = NULL;
@@ -193,6 +178,10 @@ void BLI_sortlist(ListBase *listbase, int (*cmp)(void *, void *))
 	}
 }
 
+/**
+ * Inserts \a vnewlink immediately following \a vprevlink in \a listbase.
+ * Or, if \a vprevlink is NULL, puts \a vnewlink at the front of the list.
+ */
 void BLI_insertlinkafter(ListBase *listbase, void *vprevlink, void *vnewlink)
 {
 	Link *prevlink = vprevlink;
@@ -213,21 +202,28 @@ void BLI_insertlinkafter(ListBase *listbase, void *vprevlink, void *vnewlink)
 	if (prevlink == NULL) {
 		newlink->prev = NULL;
 		newlink->next = listbase->first;
-		((Link *)listbase->first)->prev = newlink;
+		newlink->next->prev = newlink;
 		listbase->first = newlink;
 		return;
 	}
 
 	/* at end of list */
-	if (listbase->last == prevlink) 
+	if (listbase->last == prevlink) {
 		listbase->last = newlink;
+	}
 
 	newlink->next = prevlink->next;
 	newlink->prev = prevlink;
 	prevlink->next = newlink;
-	if (newlink->next) newlink->next->prev = newlink;
+	if (newlink->next) {
+		newlink->next->prev = newlink;
+	}
 }
 
+/**
+ * Inserts \a vnewlink immediately preceding \a vnextlink in listbase.
+ * Or, if \a vnextlink is NULL, puts \a vnewlink at the end of the list.
+ */
 void BLI_insertlinkbefore(ListBase *listbase, void *vnextlink, void *vnewlink)
 {
 	Link *nextlink = vnextlink;
@@ -254,16 +250,22 @@ void BLI_insertlinkbefore(ListBase *listbase, void *vnextlink, void *vnewlink)
 	}
 
 	/* at beginning of list */
-	if (listbase->first == nextlink)
+	if (listbase->first == nextlink) {
 		listbase->first = newlink;
+	}
 
 	newlink->next = nextlink;
 	newlink->prev = nextlink->prev;
 	nextlink->prev = newlink;
-	if (newlink->prev) newlink->prev->next = newlink;
+	if (newlink->prev) {
+		newlink->prev->next = newlink;
+	}
 }
 
 
+/**
+ * Removes and disposes of the entire contents of listbase using direct free(3).
+ */
 void BLI_freelist(ListBase *listbase)
 {
 	Link *link, *next;
@@ -282,6 +284,9 @@ void BLI_freelist(ListBase *listbase)
 	listbase->last = NULL;
 }
 
+/**
+ * Removes and disposes of the entire contents of \a listbase using guardedalloc.
+ */
 void BLI_freelistN(ListBase *listbase)
 {
 	Link *link, *next;
@@ -300,6 +305,9 @@ void BLI_freelistN(ListBase *listbase)
 }
 
 
+/**
+ * Returns the number of elements in \a listbase.
+ */
 int BLI_countlist(const ListBase *listbase)
 {
 	Link *link;
@@ -315,6 +323,9 @@ int BLI_countlist(const ListBase *listbase)
 	return count;
 }
 
+/**
+ * Returns the nth element of \a listbase, numbering from 1.
+ */
 void *BLI_findlink(const ListBase *listbase, int number)
 {
 	Link *link = NULL;
@@ -330,6 +341,9 @@ void *BLI_findlink(const ListBase *listbase, int number)
 	return link;
 }
 
+/**
+ * Returns the nth-last element of \a listbase, numbering from 1.
+ */
 void *BLI_rfindlink(const ListBase *listbase, int number)
 {
 	Link *link = NULL;
@@ -345,6 +359,9 @@ void *BLI_rfindlink(const ListBase *listbase, int number)
 	return link;
 }
 
+/**
+ * Returns the position of \a vlink within \a listbase, numbering from 1, or -1 if not found.
+ */
 int BLI_findindex(const ListBase *listbase, const void *vlink)
 {
 	Link *link = NULL;
@@ -365,6 +382,10 @@ int BLI_findindex(const ListBase *listbase, const void *vlink)
 	return -1;
 }
 
+/**
+ * Finds the first element of \a listbase which contains the null-terminated
+ * string \a id at the specified offset, returning NULL if not found.
+ */
 void *BLI_findstring(const ListBase *listbase, const char *id, const int offset)
 {
 	Link *link = NULL;
@@ -383,6 +404,10 @@ void *BLI_findstring(const ListBase *listbase, const char *id, const int offset)
 	return NULL;
 }
 /* same as above but find reverse */
+/**
+ * Finds the last element of \a listbase which contains the
+ * null-terminated string \a id at the specified offset, returning NULL if not found.
+ */
 void *BLI_rfindstring(const ListBase *listbase, const char *id, const int offset)
 {
 	Link *link = NULL;
@@ -401,6 +426,10 @@ void *BLI_rfindstring(const ListBase *listbase, const char *id, const int offset
 	return NULL;
 }
 
+/**
+ * Finds the first element of \a listbase which contains a pointer to the
+ * null-terminated string \a id at the specified offset, returning NULL if not found.
+ */
 void *BLI_findstring_ptr(const ListBase *listbase, const char *id, const int offset)
 {
 	Link *link = NULL;
@@ -420,6 +449,10 @@ void *BLI_findstring_ptr(const ListBase *listbase, const char *id, const int off
 	return NULL;
 }
 /* same as above but find reverse */
+/**
+ * Finds the last element of \a listbase which contains a pointer to the
+ * null-terminated string \a id at the specified offset, returning NULL if not found.
+ */
 void *BLI_rfindstring_ptr(const ListBase *listbase, const char *id, const int offset)
 {
 	Link *link = NULL;
@@ -440,6 +473,8 @@ void *BLI_rfindstring_ptr(const ListBase *listbase, const char *id, const int of
 }
 
 void *BLI_findptr(const ListBase *listbase, const void *ptr, const int offset)
+/* finds the first element of listbase which contains the specified pointer value
+at the specified offset, returning NULL if not found. */
 {
 	Link *link = NULL;
 	const void *ptr_iter;
@@ -448,7 +483,7 @@ void *BLI_findptr(const ListBase *listbase, const void *ptr, const int offset)
 
 	for (link = listbase->first; link; link = link->next) {
 		/* exact copy of BLI_findstring(), except for this line */
-		ptr_iter = *((const char **)(((const char *)link) + offset));
+		ptr_iter = *((const void **)(((const char *)link) + offset));
 
 		if (ptr == ptr_iter) {
 			return link;
@@ -459,6 +494,8 @@ void *BLI_findptr(const ListBase *listbase, const void *ptr, const int offset)
 }
 /* same as above but find reverse */
 void *BLI_rfindptr(const ListBase *listbase, const void *ptr, const int offset)
+/* finds the last element of listbase which contains the specified pointer value
+at the specified offset, returning NULL if not found. */
 {
 	Link *link = NULL;
 	const void *ptr_iter;
@@ -467,7 +504,7 @@ void *BLI_rfindptr(const ListBase *listbase, const void *ptr, const int offset)
 
 	for (link = listbase->last; link; link = link->prev) {
 		/* exact copy of BLI_rfindstring(), except for this line */
-		ptr_iter = *((const char **)(((const char *)link) + offset));
+		ptr_iter = *((const void **)(((const char *)link) + offset));
 
 		if (ptr == ptr_iter) {
 			return link;
@@ -478,6 +515,8 @@ void *BLI_rfindptr(const ListBase *listbase, const void *ptr, const int offset)
 }
 
 int BLI_findstringindex(const ListBase *listbase, const char *id, const int offset)
+/* returns the 1-based index of the first element of listbase which contains the specified
+null-terminated string at the specified offset, or -1 if not found. */
 {
 	Link *link = NULL;
 	const char *id_iter;
@@ -499,6 +538,7 @@ int BLI_findstringindex(const ListBase *listbase, const char *id, const int offs
 }
 
 void BLI_duplicatelist(ListBase *dst, const ListBase *src)
+/* sets dst to a duplicate of the entire contents of src. dst may be the same as src. */
 {
 	struct Link *dst_link, *src_link;