Usage suggestions.
Providing alternative suggestions for using C++ stdlib types
instead of libutils types:
- higher interoperability
- fewer "legacy" quirks
- ability to use stl algorithms
- high optimization levels
Test: none
Change-Id: If81aa9982ca0ad229fa13c8142387906981b054d
diff --git a/libutils/include/utils/Atomic.h b/libutils/include/utils/Atomic.h
index 7eb476c..0f592fe 100644
--- a/libutils/include/utils/Atomic.h
+++ b/libutils/include/utils/Atomic.h
@@ -17,6 +17,8 @@
#ifndef ANDROID_UTILS_ATOMIC_H
#define ANDROID_UTILS_ATOMIC_H
+// DO NOT USE: Please instead use std::atomic
+
#include <cutils/atomic.h>
#endif // ANDROID_UTILS_ATOMIC_H
diff --git a/libutils/include/utils/BitSet.h b/libutils/include/utils/BitSet.h
index 8c61293..8abfb1a 100644
--- a/libutils/include/utils/BitSet.h
+++ b/libutils/include/utils/BitSet.h
@@ -22,6 +22,8 @@
/*
* Contains some bit manipulation helpers.
+ *
+ * DO NOT USE: std::bitset<32> or std::bitset<64> preferred
*/
namespace android {
diff --git a/libutils/include/utils/Condition.h b/libutils/include/utils/Condition.h
index 3019a21..9bf82eb 100644
--- a/libutils/include/utils/Condition.h
+++ b/libutils/include/utils/Condition.h
@@ -34,6 +34,8 @@
namespace android {
// ---------------------------------------------------------------------------
+// DO NOT USE: please use std::condition_variable instead.
+
/*
* Condition variable class. The implementation is system-dependent.
*
diff --git a/libutils/include/utils/Debug.h b/libutils/include/utils/Debug.h
index 08893bd..5079894 100644
--- a/libutils/include/utils/Debug.h
+++ b/libutils/include/utils/Debug.h
@@ -29,6 +29,8 @@
#define COMPILE_TIME_ASSERT(_exp) \
template class CompileTimeAssert< (_exp) >;
#endif
+
+// DO NOT USE: Please use static_assert instead
#define COMPILE_TIME_ASSERT_FUNCTION_SCOPE(_exp) \
CompileTimeAssert<( _exp )>();
diff --git a/libutils/include/utils/Flattenable.h b/libutils/include/utils/Flattenable.h
index 070c710..675e211 100644
--- a/libutils/include/utils/Flattenable.h
+++ b/libutils/include/utils/Flattenable.h
@@ -33,13 +33,13 @@
public:
template<size_t N>
static size_t align(size_t size) {
- COMPILE_TIME_ASSERT_FUNCTION_SCOPE( !(N & (N-1)) );
+ static_assert(!(N & (N - 1)), "Can only align to a power of 2.");
return (size + (N-1)) & ~(N-1);
}
template<size_t N>
static size_t align(void const*& buffer) {
- COMPILE_TIME_ASSERT_FUNCTION_SCOPE( !(N & (N-1)) );
+ static_assert(!(N & (N - 1)), "Can only align to a power of 2.");
uintptr_t b = uintptr_t(buffer);
buffer = reinterpret_cast<void*>((uintptr_t(buffer) + (N-1)) & ~(N-1));
return size_t(uintptr_t(buffer) - b);
diff --git a/libutils/include/utils/Functor.h b/libutils/include/utils/Functor.h
index 09ea614..3182a9c 100644
--- a/libutils/include/utils/Functor.h
+++ b/libutils/include/utils/Functor.h
@@ -21,6 +21,10 @@
namespace android {
+// DO NOT USE: please use
+// - C++ lambda
+// - class with well-defined and specific functionality and semantics
+
class Functor {
public:
Functor() {}
diff --git a/libutils/include/utils/KeyedVector.h b/libutils/include/utils/KeyedVector.h
index f93ad6e..03bfe27 100644
--- a/libutils/include/utils/KeyedVector.h
+++ b/libutils/include/utils/KeyedVector.h
@@ -30,6 +30,8 @@
namespace android {
+// DO NOT USE: please use std::map
+
template <typename KEY, typename VALUE>
class KeyedVector
{
diff --git a/libutils/include/utils/List.h b/libutils/include/utils/List.h
index 403cd7f..daca016 100644
--- a/libutils/include/utils/List.h
+++ b/libutils/include/utils/List.h
@@ -37,6 +37,8 @@
*
* Objects added to the list are copied using the assignment operator,
* so this must be defined.
+ *
+ * DO NOT USE: please use std::list<T>
*/
template<typename T>
class List
diff --git a/libutils/include/utils/Singleton.h b/libutils/include/utils/Singleton.h
index 9afedd4..bc47a5c 100644
--- a/libutils/include/utils/Singleton.h
+++ b/libutils/include/utils/Singleton.h
@@ -39,6 +39,11 @@
#pragma clang diagnostic ignored "-Wundefined-var-template"
#endif
+// DO NOT USE: Please use scoped static initialization. For instance:
+// MyClass& getInstance() {
+// static MyClass gInstance(...);
+// return gInstance;
+// }
template <typename TYPE>
class ANDROID_API Singleton
{
diff --git a/libutils/include/utils/SortedVector.h b/libutils/include/utils/SortedVector.h
index 5b2a232..47c1376 100644
--- a/libutils/include/utils/SortedVector.h
+++ b/libutils/include/utils/SortedVector.h
@@ -30,6 +30,8 @@
namespace android {
+// DO NOT USE: please use std::set
+
template <class TYPE>
class SortedVector : private SortedVectorImpl
{
diff --git a/libutils/include/utils/String16.h b/libutils/include/utils/String16.h
index 15ed19f..5f0ce06 100644
--- a/libutils/include/utils/String16.h
+++ b/libutils/include/utils/String16.h
@@ -37,6 +37,8 @@
class String8;
+// DO NOT USE: please use std::u16string
+
//! This is a string holding UTF-16 characters.
class String16
{
diff --git a/libutils/include/utils/String8.h b/libutils/include/utils/String8.h
index 0225c6b..94ac32f 100644
--- a/libutils/include/utils/String8.h
+++ b/libutils/include/utils/String8.h
@@ -32,6 +32,8 @@
class String16;
+// DO NOT USE: please use std::string
+
//! This is a string holding UTF-8 characters. Does not allow the value more
// than 0x10FFFF, which is not valid unicode codepoint.
class String8
diff --git a/libutils/include/utils/Thread.h b/libutils/include/utils/Thread.h
index a261fc8..598298d 100644
--- a/libutils/include/utils/Thread.h
+++ b/libutils/include/utils/Thread.h
@@ -36,6 +36,8 @@
namespace android {
// ---------------------------------------------------------------------------
+// DO NOT USE: please use std::thread
+
class Thread : virtual public RefBase
{
public:
diff --git a/libutils/include/utils/Vector.h b/libutils/include/utils/Vector.h
index 7e00123..a1a0234 100644
--- a/libutils/include/utils/Vector.h
+++ b/libutils/include/utils/Vector.h
@@ -49,6 +49,8 @@
* The main templated vector class ensuring type safety
* while making use of VectorImpl.
* This is the class users want to use.
+ *
+ * DO NOT USE: please use std::vector
*/
template <class TYPE>
diff --git a/libutils/include/utils/misc.h b/libutils/include/utils/misc.h
index 6cccec3..af5ea02 100644
--- a/libutils/include/utils/misc.h
+++ b/libutils/include/utils/misc.h
@@ -22,7 +22,9 @@
#include <utils/Endian.h>
-/* get #of elements in a static array */
+/* get #of elements in a static array
+ * DO NOT USE: please use std::vector/std::array instead
+ */
#ifndef NELEM
# define NELEM(x) ((int) (sizeof(x) / sizeof((x)[0])))
#endif
