mfbt/ArrayUtils.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /*
   8  * Implements various helper functions related to arrays.
   9  */
  10
  11 #ifndef mozilla_ArrayUtils_h
  12 #define mozilla_ArrayUtils_h
  13
  14 #include "mozilla/Assertions.h"
  15 #include "mozilla/Attributes.h"
  16
  17 #include <stddef.h>
  18
  19 #ifdef __cplusplus
  20
  21 #include "mozilla/Alignment.h"
  22 #include "mozilla/Array.h"
  23 #include "mozilla/TypeTraits.h"
  24
  25 namespace mozilla {
  26
  27 /*
  28  * Safely subtract two pointers when it is known that aEnd >= aBegin, yielding a
  29  * size_t result.
  30  *
  31  * Ordinary pointer subtraction yields a ptrdiff_t result, which, being signed,
  32  * has insufficient range to express the distance between pointers at opposite
  33  * ends of the address space. Furthermore, most compilers use ptrdiff_t to
  34  * represent the intermediate byte address distance, before dividing by
  35  * sizeof(T); if that intermediate result overflows, they'll produce results
  36  * with the wrong sign even when the correct scaled distance would fit in a
  37  * ptrdiff_t.
  38  */
  39 template<class T>
  40 MOZ_ALWAYS_INLINE size_t
  41 PointerRangeSize(T* aBegin, T* aEnd)
  42 {
  43   MOZ_ASSERT(aEnd >= aBegin);
  44   return (size_t(aEnd) - size_t(aBegin)) / sizeof(T);
  45 }
  46
  47 /*
  48  * Compute the length of an array with constant length.  (Use of this method
  49  * with a non-array pointer will not compile.)
  50  *
  51  * Beware of the implicit trailing '\0' when using this with string constants.
  52  */
  53 template<typename T, size_t N>
  54 MOZ_CONSTEXPR size_t
  55 ArrayLength(T (&aArr)[N])
  56 {
  57   return N;
  58 }
  59
  60 template<typename T, size_t N>
  61 MOZ_CONSTEXPR size_t
  62 ArrayLength(const Array<T, N>& aArr)
  63 {
  64   return N;
  65 }
  66
  67 /*
  68  * Compute the address one past the last element of a constant-length array.
  69  *
  70  * Beware of the implicit trailing '\0' when using this with string constants.
  71  */
  72 template<typename T, size_t N>
  73 MOZ_CONSTEXPR T*
  74 ArrayEnd(T (&aArr)[N])
  75 {
  76   return aArr + ArrayLength(aArr);
  77 }
  78
  79 template<typename T, size_t N>
  80 MOZ_CONSTEXPR T*
  81 ArrayEnd(Array<T, N>& aArr)
  82 {
  83   return &aArr[0] + ArrayLength(aArr);
  84 }
  85
  86 template<typename T, size_t N>
  87 MOZ_CONSTEXPR const T*
  88 ArrayEnd(const Array<T, N>& aArr)
  89 {
  90   return &aArr[0] + ArrayLength(aArr);
  91 }
  92
  93 namespace detail {
  94
  95 template<typename AlignType, typename Pointee>
  96 struct AlignedChecker
  97 {
  98   static void
  99   test(Pointee* aPtr)
 100   {
 101     MOZ_ASSERT((uintptr_t(aPtr) % MOZ_ALIGNOF(AlignType)) == 0,
 102                "performing a range-check with a misaligned pointer");
 103   }
 104 };
 105
 106 template<typename Pointee>
 107 struct AlignedChecker<void, Pointee>
 108 {
 109   static void
 110   test(Pointee* aPtr)
 111   {
 112   }
 113 };
 114
 115 } // namespace detail
 116
 117 /**
 118  * Determines whether |aPtr| points at an object in the range [aBegin, aEnd).
 119  *
 120  * |aPtr| must have the same alignment as |aBegin| and |aEnd|.  This usually
 121  * should be achieved by ensuring |aPtr| points at a |U|, not just that it
 122  * points at a |T|.
 123  *
 124  * It is a usage error for any argument to be misaligned.
 125  *
 126  * It's okay for T* to be void*, and if so U* may also be void*.  In the latter
 127  * case no argument is required to be aligned (obviously, as void* implies no
 128  * particular alignment).
 129  */
 130 template<typename T, typename U>
 131 inline typename EnableIf<IsSame<T, U>::value ||
 132                          IsBaseOf<T, U>::value ||
 133                          IsVoid<T>::value,
 134                          bool>::Type
 135 IsInRange(T* aPtr, U* aBegin, U* aEnd)
 136 {
 137   MOZ_ASSERT(aBegin <= aEnd);
 138   detail::AlignedChecker<U, T>::test(aPtr);
 139   detail::AlignedChecker<U, U>::test(aBegin);
 140   detail::AlignedChecker<U, U>::test(aEnd);
 141   return aBegin <= static_cast<U*>(aPtr) && static_cast<U*>(aPtr) < aEnd;
 142 }
 143
 144 /**
 145  * Convenience version of the above method when the valid range is specified as
 146  * uintptr_t values.  As above, |aPtr| must be aligned, and |aBegin| and |aEnd|
 147  * must be aligned with respect to |T|.
 148  */
 149 template<typename T>
 150 inline bool
 151 IsInRange(T* aPtr, uintptr_t aBegin, uintptr_t aEnd)
 152 {
 153   return IsInRange(aPtr,
 154                    reinterpret_cast<T*>(aBegin), reinterpret_cast<T*>(aEnd));
 155 }
 156
 157 namespace detail {
 158
 159 /*
 160  * Helper for the MOZ_ARRAY_LENGTH() macro to make the length a typesafe
 161  * compile-time constant even on compilers lacking constexpr support.
 162  */
 163 template <typename T, size_t N>
 164 char (&ArrayLengthHelper(T (&array)[N]))[N];
 165
 166 } /* namespace detail */
 167
 168 } /* namespace mozilla */
 169
 170 #endif /* __cplusplus */
 171
 172 /*
 173  * MOZ_ARRAY_LENGTH() is an alternative to mozilla::ArrayLength() for C files
 174  * that can't use C++ template functions and for static_assert() calls that
 175  * can't call ArrayLength() when it is not a C++11 constexpr function.
 176  */
 177 #ifdef __cplusplus
 178 #  define MOZ_ARRAY_LENGTH(array)   sizeof(mozilla::detail::ArrayLengthHelper(array))
 179 #else
 180 #  define MOZ_ARRAY_LENGTH(array)   (sizeof(array)/sizeof((array)[0]))
 181 #endif
 182
 183 #endif /* mozilla_ArrayUtils_h */