BLI_heap: add an API function to directly read the top node value.

It is very commonly needed in loop conditions to check if
the items in the heap are good enough to continue.

2 files changed, 12 insertions, 0 deletions

diff --git a/source/blender/blenlib/BLI_heap.h b/source/blender/blenlib/BLI_heap.h
index 771b9dabe4d..35c8df3075c 100644
--- a/source/blender/blenlib/BLI_heap.h
+++ b/source/blender/blenlib/BLI_heap.h
@@ -43,6 +43,7 @@ void            BLI_heap_remove(Heap *heap, HeapNode *node) ATTR_NONNULL(1, 2);
 bool            BLI_heap_is_empty(const Heap *heap) ATTR_NONNULL(1);
 unsigned int    BLI_heap_len(const Heap *heap) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
 HeapNode       *BLI_heap_top(const Heap *heap) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
+float           BLI_heap_top_value(const Heap *heap) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1);
 void           *BLI_heap_pop_min(Heap *heap) ATTR_NONNULL(1);
 void            BLI_heap_node_value_update(Heap *heap, HeapNode *node, float value) ATTR_NONNULL(1, 2);
 void            BLI_heap_node_value_update_ptr(Heap *heap, HeapNode *node, float value, void *ptr) ATTR_NONNULL(1, 2);
diff --git a/source/blender/blenlib/intern/BLI_heap.c b/source/blender/blenlib/intern/BLI_heap.c
index 5658c1fd103..17a15f93266 100644
--- a/source/blender/blenlib/intern/BLI_heap.c
+++ b/source/blender/blenlib/intern/BLI_heap.c
@@ -318,6 +318,17 @@ HeapNode *BLI_heap_top(const Heap *heap)
 }
 
 /**
+ * Return the value of top node of the heap.
+ * This is the node with the lowest value.
+ */
+float BLI_heap_top_value(const Heap *heap)
+{
+	BLI_assert(heap->size != 0);
+
+	return heap->tree[0]->value;
+}
+
+/**
  * Pop the top node off the heap and return it's pointer.
  */
 void *BLI_heap_pop_min(Heap *heap)