[Bf-blender-cvs] [da5f1dd8e57] functions: comment methods of some more data structures
Jacques Lucke
noreply at git.blender.org
Fri Jun 21 18:54:30 CEST 2019
Commit: da5f1dd8e57533e58117d6d915e07af0f0e289a3
Author: Jacques Lucke
Date: Fri Jun 21 18:41:04 2019 +0200
Branches: functions
https://developer.blender.org/rBda5f1dd8e57533e58117d6d915e07af0f0e289a3
comment methods of some more data structures
===================================================================
M source/blender/blenlib/BLI_small_map.hpp
M source/blender/blenlib/BLI_small_set.hpp
M source/blender/blenlib/BLI_small_set_vector.hpp
M source/blender/blenlib/BLI_small_stack.hpp
===================================================================
diff --git a/source/blender/blenlib/BLI_small_map.hpp b/source/blender/blenlib/BLI_small_map.hpp
index 114b1f67381..e010fe4198d 100644
--- a/source/blender/blenlib/BLI_small_map.hpp
+++ b/source/blender/blenlib/BLI_small_map.hpp
@@ -1,10 +1,29 @@
-#pragma once
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
-/* An unordered map implementation with small object optimization.
+/** \file
+ * \ingroup bli
+ *
+ * An unordered map implementation with small object optimization.
* Similar to SmallSet, this builds on top of SmallVector
* and ArrayLookup to reduce what this code has to deal with.
*/
+#pragma once
+
#include "BLI_small_vector.hpp"
#include "BLI_array_lookup.hpp"
#include "BLI_array_ref.hpp"
@@ -29,8 +48,15 @@ template<typename K, typename V, uint N = 4> class SmallMap {
public:
class ValueIterator;
+ /**
+ * Create an empty map.
+ */
SmallMap() = default;
+ /**
+ * Insert a key-value pair in the map, when the key does not exist.
+ * Return true when the pair has been newly inserted, otherwise false.
+ */
bool add(const K &key, const V &value)
{
uint potential_index = m_entries.size();
@@ -41,6 +67,10 @@ template<typename K, typename V, uint N = 4> class SmallMap {
return newly_inserted;
}
+ /**
+ * Insert a new key-value pair in the map.
+ * This will assert when the key exists already.
+ */
void add_new(const K &key, const V &value)
{
BLI_assert(!this->contains(key));
@@ -49,11 +79,19 @@ template<typename K, typename V, uint N = 4> class SmallMap {
m_lookup.add_new(m_entries.begin(), index);
}
+ /**
+ * Return true when the key exists in the map, otherwise false.
+ */
bool contains(const K &key) const
{
return m_lookup.contains(m_entries.begin(), key);
}
+ /**
+ * Remove the key-value pair identified by the key from the map.
+ * Returns the corresponding value.
+ * This will assert when the key does not exist.
+ */
V pop(const K &key)
{
BLI_assert(this->contains(key));
@@ -72,11 +110,19 @@ template<typename K, typename V, uint N = 4> class SmallMap {
return value;
}
+ /**
+ * Return the value corresponding to the key.
+ * This will assert when the key does not exist.
+ */
V lookup(const K &key) const
{
return this->lookup_ref(key);
}
+ /**
+ * Return the value corresponding to the key.
+ * If the key does not exist, return the given default value.
+ */
V lookup_default(const K &key, V default_value) const
{
V *ptr = this->lookup_ptr(key);
@@ -88,6 +134,10 @@ template<typename K, typename V, uint N = 4> class SmallMap {
}
}
+ /**
+ * Return a reference to the value corresponding to a key.
+ * This will assert when the key does not exist.
+ */
V &lookup_ref(const K &key) const
{
V *ptr = this->lookup_ptr(key);
@@ -95,6 +145,10 @@ template<typename K, typename V, uint N = 4> class SmallMap {
return *ptr;
}
+ /**
+ * Return a pointer to the value corresponding to the key.
+ * Returns nullptr when the key does not exist.
+ */
V *lookup_ptr(const K &key) const
{
int index = m_lookup.find(m_entries.begin(), key);
@@ -106,6 +160,10 @@ template<typename K, typename V, uint N = 4> class SmallMap {
}
}
+ /**
+ * Return the pointer to the value corresponding to the key.
+ * If the key does not exist yet, insert the given key-value-pair first.
+ */
V *lookup_ptr_or_insert(const K &key, V initial_value)
{
V *ptr = this->lookup_ptr(key);
@@ -116,6 +174,11 @@ template<typename K, typename V, uint N = 4> class SmallMap {
return ptr;
}
+ /**
+ * Return a reference to the value corresponding to the key.
+ * If the key does not exist yet, the given function will be called
+ * with the given parameters, to create the value that will be stored for the key.
+ */
template<typename... Args>
V &lookup_ref_or_insert_func(const K &key, V (*create_value)(Args... args), Args &&... args)
{
@@ -127,11 +190,19 @@ template<typename K, typename V, uint N = 4> class SmallMap {
return this->lookup_ref(key);
}
+ /**
+ * Returns a reference to the value corresponding to the key.
+ * If the key does not exist yet, the given function will be called
+ * with the key as parameter, to create the value that will be stored for the key.
+ */
V &lookup_ref_or_insert_key_func(const K &key, V (*create_value)(const K &key))
{
return lookup_ref_or_insert_func(key, create_value, key);
}
+ /**
+ * Return the number of key-value pairs in the map.
+ */
uint size() const
{
return m_entries.size();
diff --git a/source/blender/blenlib/BLI_small_set.hpp b/source/blender/blenlib/BLI_small_set.hpp
index cdd32e1a7f3..273853a83f4 100644
--- a/source/blender/blenlib/BLI_small_set.hpp
+++ b/source/blender/blenlib/BLI_small_set.hpp
@@ -1,11 +1,30 @@
-#pragma once
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
-/* A unordered set implementation that supports small object optimization.
+/** \file
+ * \ingroup bli
+ *
+ * A unordered set implementation that supports small object optimization.
* It builds on top of SmallVector and ArrayLookup, so that
* it does not have to deal with memory management and the
* details of the hashing and probing algorithm.
*/
+#pragma once
+
#include "BLI_small_vector.hpp"
#include "BLI_array_lookup.hpp"
#include "BLI_array_ref.hpp"
@@ -18,8 +37,15 @@ template<typename T, uint N = 4> class SmallSet {
ArrayLookup<T, N> m_lookup;
public:
+ /**
+ * Create an empty set.
+ */
SmallSet() = default;
+ /**
+ * Create a set that contains any of the given values at least once.
+ * The size of the set might be small than the original array.
+ */
SmallSet(ArrayRef<T> values)
{
this->add_multiple(values);
@@ -33,16 +59,28 @@ template<typename T, uint N = 4> class SmallSet {
{
}
+ /**
+ * Return the number elements in the set.
+ */
uint size() const
{
return m_elements.size();
}
+ /**
+ * Return true when the value is in the set, otherwise false.
+ */
bool contains(const T &value) const
{
return m_lookup.contains(m_elements.begin(), value);
}
+ /**
+ * Insert a value in the set, that was not there before.
+ * This will assert when the value existed before.
+ * This method might be faster than "add".
+ * Furthermore, it should be used whenever applicable because it expresses the intent better.
+ */
void add_new(const T &value)
{
BLI_assert(!this->contains(value));
@@ -51,6 +89,10 @@ template<typename T, uint N = 4> class SmallSet {
m_lookup.add_new(m_elements.begin(), index);
}
+ /**
+ * Insert the value in the set if it did not exist before.
+ * Return false, when it existed before, otherwise true.
+ */
bool add(const T &value)
{
uint potential_index = m_elements.size();
@@ -61,6 +103,10 @@ template<typename T, uint N = 4> class SmallSet {
return newly_inserted;
}
+ /**
+ * Insert multiple values in the set.
+ * Any value that already exists will be skipped.
+ */
void add_multiple(ArrayRef<T> values)
{
for (T &value : values) {
@@ -68,6 +114,9 @@ template<typename T, uint N = 4> class SmallSet {
}
}
+ /**
+ * Remove and return any value from the set.
+ */
T pop()
{
BLI_assert(this->size() > 0);
@@ -77,6 +126,10 @@ template<typename T, uint N = 4> class SmallSet {
return value;
}
+ /**
+ * Remove the value from the set.
+ * This expects that the value existed before and will assert otherwise.
+ */
void remove(const T &value)
{
BLI_assert(this->contains(value));
@@ -93,22 +146,34 @@ template<typename T, uint N = 4> class SmallSet {
}
}
+ /**
+ * Return any of the elements of the set.
+ */
T any() const
{
BLI_assert(this->size() > 0);
return m_elements[0];
}
+ /**
+ * Convert all values in the set into a vector.
+ */
SmallVector<T> to_small_vector() const
{
return m_elements;
}
+ /**
+ * Return true when there is no value that exists in both sets, otherwise false.
+ */
static bool Disjoint(const SmallSet &a, const SmallSet &b)
{
return !SmallSet::Intersects(a, b);
}
+ /**
+ * Return true when there is at least one value that exists in both sets, otherwise false.
+ */
static bool Intersects(const SmallSet &a, const SmallSet &b)
{
for (const T &value : a) {
diff --git a/source/blender/blenlib/BLI_small_set_vector.hpp b/source/blender/blenlib/BLI_small_set_vector.hpp
index 7dfc4bc5ee4..7441e3daf88 100644
--- a/source/blender/blenlib/BLI_small_set_vector.hpp
+++ b/source/blender/blenlib/BLI_small_set_vector.hpp
@@ -1,10 +1,29 @@
-#pragma once
+/*
+ * This program is free software; y
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list