Skip to content

Commit

Permalink
Containers: rename *Array*::empty() to isEmpty().
Browse files Browse the repository at this point in the history 
I used this naming for the new String APIs already, plus all other APIs
returning a boolean were already named isSomething(). This was a weird
outlier, named like that only to match what STL did. However, taking
inspiration for *anything* from the STL is an increasingly bad idea, and
since `array.empty()` might as well suggest a meaning of "make the array
empty", it's better to just stop using that name altogether.
  • Loading branch information
@mosra
mosra committed Mar 9, 2022
1 parent cc429b4 commit 6bebd0e
Show file tree
Hide file tree
Showing 21 changed files with 219 additions and 113 deletions.
12 changes: 12 additions & 0 deletions doc/corrade-changelog.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,18 @@ namespace Corrade {

@subsection corrade-changelog-latest-deprecated Deprecated APIs

- @cpp Containers::Array::empty() @ce, @cpp ArrayView::empty() @ce,
@cpp StaticArray::empty() @ce, @cpp StaticArrayView::empty() @ce and
@cpp StridedArrayView::empty() @ce is deprecated in favor of
@ref Containers::Array::isEmpty,
@relativeref{Containers,ArrayView::isEmpty()},
@relativeref{Containers,StaticArray::isEmpty()},
@relativeref{Containers,StaticArrayView::isEmpty()} and
@relativeref{Containers,StridedArrayView::isEmpty()}. The original name was chosen only to match what STL did, but it could be confused with "make the
array empty" (i.e., what `clear()` does) and it was inconsistent with all
other APIs returning a @cpp bool @ce as well as the new
@ref Containers::String and @ref Containers::BasicStringView "StringView"
APIs, which all use `isSomething()` instead.
- @cpp Utility::Directory::isSandboxed() @ce is deprecated in favor of
@ref Utility::System::isSandboxed(), as that's the better place for this
API to live in
Expand Down
2 changes: 1 addition & 1 deletion doc/snippets/Containers.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,7 @@ static_cast<void>(e);
/* [ArrayView-usage-access] */
Containers::ArrayView<int> view = DOXYGEN_ELLIPSIS({});

if(!view.empty()) {
if(!view.isEmpty()) {
int min = view.front();
for(int i: view) if(i < min) min = i;

Expand Down
14 changes: 12 additions & 2 deletions src/Corrade/Containers/Array.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -517,8 +517,18 @@ class Array {
/** @brief Array size */
std::size_t size() const { return _size; }

/** @brief Whether the array is empty */
bool empty() const { return !_size; }
/**
* @brief Whether the array is empty
* @m_since_latest
*/
bool isEmpty() const { return !_size; }

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") bool empty() const { return !_size; }
#endif

/**
* @brief Pointer to first element
Expand Down
58 changes: 49 additions & 9 deletions src/Corrade/Containers/ArrayView.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ convertible to them:
@subsection Containers-ArrayView-usage-access Data access
The class provides the usual C++ container interface --- @ref data(),
@ref size() and @ref empty(); subscript access via @ref operator T*(), range
@ref size() and @ref isEmpty(); subscript access via @ref operator T*(), range
access via @ref begin() / @ref end(), and their overloads and acess to the
@ref front() and @ref back() element, if the view is non-empty. The view itself
is immutable and thus all member functions are @cpp const @ce, but if the
Expand Down Expand Up @@ -369,8 +369,18 @@ template<class T> class ArrayView {
/** @brief View size */
constexpr std::size_t size() const { return _size; }

/** @brief Whether the view is empty */
constexpr bool empty() const { return !_size; }
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr bool isEmpty() const { return !_size; }

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr bool empty() const { return !_size; }
#endif

/**
* @brief Pointer to the first element
Expand Down Expand Up @@ -621,8 +631,18 @@ template<> class ArrayView<void> {
/** @brief View size */
constexpr std::size_t size() const { return _size; }

/** @brief Whether the view is empty */
constexpr bool empty() const { return !_size; }
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr bool isEmpty() const { return !_size; }

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr bool empty() const { return !_size; }
#endif

private:
void* _data;
Expand Down Expand Up @@ -726,8 +746,18 @@ template<> class ArrayView<const void> {
/** @brief View size */
constexpr std::size_t size() const { return _size; }

/** @brief Whether the view is empty */
constexpr bool empty() const { return !_size; }
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr bool isEmpty() const { return !_size; }

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr bool empty() const { return !_size; }
#endif

private:
const void* _data;
Expand Down Expand Up @@ -1018,8 +1048,18 @@ template<std::size_t size_, class T> class StaticArrayView {
/** @brief View size */
constexpr std::size_t size() const { return size_; }

/** @brief Whether the view is empty */
constexpr bool empty() const { return !size_; }
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr bool isEmpty() const { return !size_; }

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr bool empty() const { return !size_; }
#endif

/**
* @brief Pointer to the first element
Expand Down
10 changes: 9 additions & 1 deletion src/Corrade/Containers/StaticArray.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -294,11 +294,19 @@ template<std::size_t size_, class T> class StaticArray {

/**
* @brief Whether the array is empty
* @m_since_latest
*
* Always @cpp true @ce (it's not possible to create a zero-sized C
* array).
*/
constexpr bool empty() const { return !size_; }
constexpr bool isEmpty() const { return !size_; }

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr bool empty() const { return !size_; }
#endif

/**
* @brief Pointer to the first element
Expand Down
60 changes: 48 additions & 12 deletions src/Corrade/Containers/StridedArrayView.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -585,11 +585,23 @@ template<unsigned dimensions, class T> class StridedArrayView {
*/
constexpr typename std::conditional<dimensions == 1, std::ptrdiff_t, const Stride&>::type stride() const { return _stride; }

/** @brief Whether the array is empty */
constexpr StridedDimensions<dimensions, bool> empty() const {
return emptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr StridedDimensions<dimensions, bool> isEmpty() const {
return isEmptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
}

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr StridedDimensions<dimensions, bool> empty() const {
return isEmptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
}
#endif

/**
* @brief Whether the view is contiguous from given dimension further
* @m_since{2020,06}
Expand Down Expand Up @@ -920,7 +932,7 @@ template<unsigned dimensions, class T> class StridedArrayView {
getting matched when pass */
constexpr /*implicit*/ StridedArrayView(const Size& size, const Stride& stride, ErasedType* data) noexcept: _data{data}, _size{size}, _stride{stride} {}

template<std::size_t ...sequence> constexpr StridedDimensions<dimensions, bool> emptyInternal(Implementation::Sequence<sequence...>) const {
template<std::size_t ...sequence> constexpr StridedDimensions<dimensions, bool> isEmptyInternal(Implementation::Sequence<sequence...>) const {
return StridedDimensions<dimensions, bool>{(_size._data[sequence] == 0)...};
}

Expand Down Expand Up @@ -1133,11 +1145,23 @@ template<unsigned dimensions> class StridedArrayView<dimensions, void> {
*/
constexpr typename std::conditional<dimensions == 1, std::ptrdiff_t, const Stride&>::type stride() const { return _stride; }

/** @brief Whether the array is empty */
constexpr StridedDimensions<dimensions, bool> empty() const {
return emptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr StridedDimensions<dimensions, bool> isEmpty() const {
return isEmptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
}

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr StridedDimensions<dimensions, bool> empty() const {
return isEmptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
}
#endif

private:
template<unsigned, class> friend class StridedArrayView;

Expand All @@ -1146,7 +1170,7 @@ template<unsigned dimensions> class StridedArrayView<dimensions, void> {
getting matched when pass */
constexpr /*implicit*/ StridedArrayView(const Size& size, const Stride& stride, void* data) noexcept: _data{data}, _size{size}, _stride{stride} {}

template<std::size_t ...sequence> constexpr StridedDimensions<dimensions, bool> emptyInternal(Implementation::Sequence<sequence...>) const {
template<std::size_t ...sequence> constexpr StridedDimensions<dimensions, bool> isEmptyInternal(Implementation::Sequence<sequence...>) const {
return StridedDimensions<dimensions, bool>{(_size._data[sequence] == 0)...};
}

Expand Down Expand Up @@ -1358,10 +1382,22 @@ template<unsigned dimensions> class StridedArrayView<dimensions, const void> {
*/
constexpr typename std::conditional<dimensions == 1, std::ptrdiff_t, const Stride&>::type stride() const { return _stride; }

/** @brief Whether the array is empty */
constexpr StridedDimensions<dimensions, bool> empty() const {
return emptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
/**
* @brief Whether the view is empty
* @m_since_latest
*/
constexpr StridedDimensions<dimensions, bool> isEmpty() const {
return isEmptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
}

#ifdef CORRADE_BUILD_DEPRECATED
/** @copybrief isEmpty()
* @m_deprecated_since_latest Use @ref isEmpty() instead.
*/
CORRADE_DEPRECATED("use isEmpty() instead") constexpr StridedDimensions<dimensions, bool> empty() const {
return isEmptyInternal(typename Implementation::GenerateSequence<dimensions>::Type{});
}
#endif

private:
template<unsigned, class> friend class StridedArrayView;
Expand All @@ -1376,7 +1412,7 @@ template<unsigned dimensions> class StridedArrayView<dimensions, const void> {
getting matched when pass */
constexpr /*implicit*/ StridedArrayView(const Size& size, const Stride& stride, const void* data) noexcept: _data{data}, _size{size}, _stride{stride} {}

template<std::size_t ...sequence> constexpr StridedDimensions<dimensions, bool> emptyInternal(Implementation::Sequence<sequence...>) const {
template<std::size_t ...sequence> constexpr StridedDimensions<dimensions, bool> isEmptyInternal(Implementation::Sequence<sequence...>) const {
return StridedDimensions<dimensions, bool>{(_size._data[sequence] == 0)...};
}

Expand Down
2 changes: 1 addition & 1 deletion src/Corrade/Containers/StringView.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ template<class T> Array3<BasicStringView<T>> BasicStringView<T>::partition(const
template<class T> String BasicStringView<T>::join(const ArrayView<const StringView> strings) const {
/* Calculate size of the resulting string including delimiters */
const std::size_t delimiterSize = size();
std::size_t totalSize = strings.empty() ? 0 : (strings.size() - 1)*delimiterSize;
std::size_t totalSize = strings.isEmpty() ? 0 : (strings.size() - 1)*delimiterSize;
for(const StringView& s: strings) totalSize += s.size();

/* Reserve memory for the resulting string */
Expand Down
4 changes: 2 additions & 2 deletions src/Corrade/Containers/Test/ArrayTest.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -532,11 +532,11 @@ void ArrayTest::convertToConstExternalView() {
void ArrayTest::emptyCheck() {
Array a;
CORRADE_VERIFY(!a);
CORRADE_VERIFY(a.empty());
CORRADE_VERIFY(a.isEmpty());

Array b(5);
CORRADE_VERIFY(b);
CORRADE_VERIFY(!b.empty());
CORRADE_VERIFY(!b.isEmpty());
}

void ArrayTest::access() {
Expand Down
Loading

0 comments on commit 6bebd0e

Please sign in to comment.