Commit: b247fc7d4608df970b8ff853410ef907f75a1aa1
Author: Jacques Lucke
Date: Fri Jun 21 18:12:07 2019 +0200
Branches: functions
https://developer.blender.org/rBb247fc7d4608df970b8ff853410ef907f75a1aa1
comments for methods of SmallVector
===================================================================
M source/blender/blenlib/BLI_small_vector.hpp
===================================================================
diff --git a/source/blender/blenlib/BLI_small_vector.hpp
b/source/blender/blenlib/BLI_small_vector.hpp
index 9fb7d1f117b..19d15e7670d 100644
--- a/source/blender/blenlib/BLI_small_vector.hpp
+++ b/source/blender/blenlib/BLI_small_vector.hpp
@@ -1,12 +1,31 @@
-#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.
+ */
-/* This vector wraps a dynamically sized array of a specific type.
+/** \file
+ * \ingroup bli
+ *
+ * This vector wraps a dynamically sized array of a specific type.
* It supports small object optimization. That means, when the
* vector only contains a few elements, no extra memory allocation
* is performed. Instead, those elements are stored directly in
* the vector.
*/
+#pragma once
+
#include <algorithm>
#include <cstdlib>
#include <cstring>
@@ -34,6 +53,10 @@ template<typename T, uint N = 4> class SmallVector {
uint m_capacity = N;
public:
+ /**
+ * Create an empty vector.
+ * This does not do any memory allocation.
+ */
SmallVector()
{
m_elements = this->small_buffer();
@@ -41,6 +64,10 @@ template<typename T, uint N = 4> class SmallVector {
m_size = 0;
}
+ /**
+ * Create a vector with a specific size.
+ * The elements will be default initialized.
+ */
SmallVector(uint size) : SmallVector()
{
this->reserve(size);
@@ -50,6 +77,9 @@ template<typename T, uint N = 4> class SmallVector {
m_size = size;
}
+ /**
+ * Create a vector from an initializer list.
+ */
SmallVector(std::initializer_list<T> values) : SmallVector()
{
this->reserve(values.size());
@@ -57,11 +87,21 @@ template<typename T, uint N = 4> class SmallVector {
m_size = values.size();
}
+ /**
+ * Create a copy of another vector.
+ * The other vector will not be changed.
+ * If the other vector has less than N elements, no allocation will be made.
+ */
SmallVector(const SmallVector &other)
{
this->copy_from_other(other);
}
+ /**
+ * Steal the elements from another vector.
+ * This does not do an allocation.
+ * The other vector will have zero elements afterwards.
+ */
SmallVector(SmallVector &&other)
{
this->steal_from_other(other);
@@ -96,17 +136,30 @@ template<typename T, uint N = 4> class SmallVector {
return *this;
}
+ /**
+ * Make sure that enough memory is allocated to hold size elements.
+ * This won't necessarily make an allocation when size is small.
+ * The actual size of the vector does not change.
+ */
void reserve(uint size)
{
this->grow(size);
}
+ /**
+ * Afterwards the vector has 0 elements, but will still have
+ * memory to be refilled again.
+ */
void clear()
{
this->destruct_elements_but_keep_memory();
m_size = 0;
}
+ /**
+ * Afterwards the vector has 0 elements and any allocated memory
+ * will be freed.
+ */
void clear_and_make_small()
{
this->destruct_elements_and_free_memory();
@@ -114,6 +167,10 @@ template<typename T, uint N = 4> class SmallVector {
m_elements = this->small_buffer();
}
+ /**
+ * Insert a new element at the end of the vector.
+ * This might cause a reallocation with the capacity is exceeded.
+ */
void append(const T &value)
{
this->ensure_space_for_one();
@@ -128,6 +185,10 @@ template<typename T, uint N = 4> class SmallVector {
m_size++;
}
+ /**
+ * Insert the same element n times at the end of the vector.
+ * This might result in a reallocation internally.
+ */
void append_n_times(const T &value, uint n)
{
this->reserve(m_size + n);
@@ -135,6 +196,9 @@ template<typename T, uint N = 4> class SmallVector {
m_size += n;
}
+ /**
+ * Copy the elements of another vector to the end of this vector.
+ */
void extend(const SmallVector &other)
{
this->extend(other.begin(), other.size());
@@ -147,12 +211,19 @@ template<typename T, uint N = 4> class SmallVector {
m_size += amount;
}
+ /**
+ * Return a reference to the last element in the vector.
+ * This will assert when the vector is empty.
+ */
T &last() const
{
BLI_assert(m_size > 0);
return m_elements[m_size - 1];
}
+ /**
+ * Replace every element with a new value.
+ */
void fill(const T &value)
{
for (uint i = 0; i < m_size; i++) {
@@ -160,16 +231,26 @@ template<typename T, uint N = 4> class SmallVector {
}
}
+ /**
+ * Return how many values are currently stored in the vector.
+ */
uint size() const
{
return m_size;
}
+ /**
+ * Returns true when the vector contains no elements, otherwise false.
+ */
bool empty() const
{
return this->size() == 0;
}
+ /**
+ * Deconstructs the last element and decreases the size by one.
+ * This will assert when the vector is empty.
+ */
void remove_last()
{
BLI_assert(!this->empty());
@@ -177,6 +258,9 @@ template<typename T, uint N = 4> class SmallVector {
m_size--;
}
+ /**
+ * Remove the last element from the vector and return it.
+ */
T pop_last()
{
BLI_assert(!this->empty());
@@ -185,6 +269,10 @@ template<typename T, uint N = 4> class SmallVector {
return value;
}
+ /**
+ * Delete any element in the vector.
+ * The empty space will be filled by the previously last element.
+ */
void remove_and_reorder(uint index)
{
BLI_assert(this->is_index_in_range(index));
@@ -198,6 +286,10 @@ template<typename T, uint N = 4> class SmallVector {
m_size--;
}
+ /**
+ * Do a linear search to find the value in the vector.
+ * When found, return the first index, otherwise return -1.
+ */
int index(const T &value) const
{
for (uint i = 0; i < m_size; i++) {
@@ -208,11 +300,20 @@ template<typename T, uint N = 4> class SmallVector {
return -1;
}
+ /**
+ * Do a linear search to see of the value is in the vector.
+ * Return true when it exists, otherwise false.
+ */
bool contains(const T &value) const
{
return this->index(value) != -1;
}
+ /**
+ * Compare vectors element-wise.
+ * Return true when they have the same length and all elements
+ * compare equal, otherwise false.
+ */
static bool all_equal(const SmallVector &a, const SmallVector &b)
{
if (a.size() != b.size()) {
_______________________________________________
Bf-blender-cvs mailing list
[email protected]
https://lists.blender.org/mailman/listinfo/bf-blender-cvs
