From b8f152d3e2b9368717743ebcb1277239a6c00659 Mon Sep 17 00:00:00 2001
From: Steven Moreland <smoreland@google.com>
Date: Mon, 18 Dec 2017 16:14:13 -0800
Subject: [PATCH] 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
---
 libutils/include/utils/Atomic.h       | 2 ++
 libutils/include/utils/BitSet.h       | 2 ++
 libutils/include/utils/Condition.h    | 2 ++
 libutils/include/utils/Debug.h        | 2 ++
 libutils/include/utils/Flattenable.h  | 4 ++--
 libutils/include/utils/Functor.h      | 4 ++++
 libutils/include/utils/KeyedVector.h  | 2 ++
 libutils/include/utils/List.h         | 2 ++
 libutils/include/utils/Singleton.h    | 5 +++++
 libutils/include/utils/SortedVector.h | 2 ++
 libutils/include/utils/String16.h     | 2 ++
 libutils/include/utils/String8.h      | 2 ++
 libutils/include/utils/Thread.h       | 2 ++
 libutils/include/utils/Vector.h       | 2 ++
 libutils/include/utils/misc.h         | 4 +++-
 15 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/libutils/include/utils/Atomic.h b/libutils/include/utils/Atomic.h
index 7eb476c94..0f592fe04 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 8c612931d..8abfb1a07 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 3019a21d6..9bf82eb77 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 08893bdaa..5079894e2 100644
--- a/libutils/include/utils/Debug.h
+++ b/libutils/include/utils/Debug.h
@@ -29,6 +29,8 @@ template<> struct CompileTimeAssert<true> {};
 #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 070c71026..675e211e0 100644
--- a/libutils/include/utils/Flattenable.h
+++ b/libutils/include/utils/Flattenable.h
@@ -33,13 +33,13 @@ class FlattenableUtils {
 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 09ea614b6..3182a9c61 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 f93ad6e21..03bfe2701 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 403cd7f1e..daca016d4 100644
--- a/libutils/include/utils/List.h
+++ b/libutils/include/utils/List.h
@@ -37,6 +37,8 @@ namespace android {
  *
  * 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 9afedd4a0..bc47a5cac 100644
--- a/libutils/include/utils/Singleton.h
+++ b/libutils/include/utils/Singleton.h
@@ -39,6 +39,11 @@ namespace android {
 #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 5b2a23200..47c1376ce 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 15ed19fb8..5f0ce0691 100644
--- a/libutils/include/utils/String16.h
+++ b/libutils/include/utils/String16.h
@@ -37,6 +37,8 @@ namespace android {
 
 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 0225c6be6..94ac32fbb 100644
--- a/libutils/include/utils/String8.h
+++ b/libutils/include/utils/String8.h
@@ -32,6 +32,8 @@ namespace android {
 
 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 a261fc8d9..598298de5 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 7e00123f7..a1a0234e3 100644
--- a/libutils/include/utils/Vector.h
+++ b/libutils/include/utils/Vector.h
@@ -49,6 +49,8 @@ class SortedVector;
  * 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 6cccec387..af5ea0241 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