1 /* Copyright (c) 2017, Google Inc.
2  *
3  * Permission to use, copy, modify, and/or distribute this software for any
4  * purpose with or without fee is hereby granted, provided that the above
5  * copyright notice and this permission notice appear in all copies.
6  *
7  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
10  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
12  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
13  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
14 
15 #ifndef OPENSSL_HEADER_SSL_SPAN_H
16 #define OPENSSL_HEADER_SSL_SPAN_H
17 
18 #include <openssl/base.h>
19 
20 #if !defined(BORINGSSL_NO_CXX)
21 
22 extern "C++" {
23 
24 #include <stdlib.h>
25 
26 #include <algorithm>
27 #include <type_traits>
28 
29 BSSL_NAMESPACE_BEGIN
30 
31 template <typename T>
32 class Span;
33 
34 namespace internal {
35 template <typename T>
36 class SpanBase {
37   // Put comparison operator implementations into a base class with const T, so
38   // they can be used with any type that implicitly converts into a Span.
39   static_assert(std::is_const<T>::value,
40                 "Span<T> must be derived from SpanBase<const T>");
41 
42   friend bool operator==(Span<T> lhs, Span<T> rhs) {
43     // MSVC issues warning C4996 because std::equal is unsafe. The pragma to
44     // suppress the warning mysteriously has no effect, hence this
45     // implementation. See
46     // https://msdn.microsoft.com/en-us/library/aa985974.aspx.
47     if (lhs.size() != rhs.size()) {
48       return false;
49     }
50     for (T *l = lhs.begin(), *r = rhs.begin(); l != lhs.end() && r != rhs.end();
51          ++l, ++r) {
52       if (*l != *r) {
53         return false;
54       }
55     }
56     return true;
57   }
58 
59   friend bool operator!=(Span<T> lhs, Span<T> rhs) { return !(lhs == rhs); }
60 };
61 }  // namespace internal
62 
63 // A Span<T> is a non-owning reference to a contiguous array of objects of type
64 // |T|. Conceptually, a Span is a simple a pointer to |T| and a count of
65 // elements accessible via that pointer. The elements referenced by the Span can
66 // be mutated if |T| is mutable.
67 //
68 // A Span can be constructed from container types implementing |data()| and
69 // |size()| methods. If |T| is constant, construction from a container type is
70 // implicit. This allows writing methods that accept data from some unspecified
71 // container type:
72 //
73 // // Foo views data referenced by v.
74 // void Foo(bssl::Span<const uint8_t> v) { ... }
75 //
76 // std::vector<uint8_t> vec;
77 // Foo(vec);
78 //
79 // For mutable Spans, conversion is explicit:
80 //
81 // // FooMutate mutates data referenced by v.
82 // void FooMutate(bssl::Span<uint8_t> v) { ... }
83 //
84 // FooMutate(bssl::Span<uint8_t>(vec));
85 //
86 // You can also use the |MakeSpan| and |MakeConstSpan| factory methods to
87 // construct Spans in order to deduce the type of the Span automatically.
88 //
89 // FooMutate(bssl::MakeSpan(vec));
90 //
91 // Note that Spans have value type sematics. They are cheap to construct and
92 // copy, and should be passed by value whenever a method would otherwise accept
93 // a reference or pointer to a container or array.
94 template <typename T>
95 class Span : private internal::SpanBase<const T> {
96  private:
97   // Heuristically test whether C is a container type that can be converted into
98   // a Span by checking for data() and size() member functions.
99   //
100   // TODO(davidben): Switch everything to std::enable_if_t when we remove
101   // support for MSVC 2015. Although we could write our own enable_if_t and MSVC
102   // 2015 has std::enable_if_t anyway, MSVC 2015's SFINAE implementation is
103   // problematic and does not work below unless we write the ::type at use.
104   template <typename C>
105   using EnableIfContainer = std::enable_if<
106       std::is_convertible<decltype(std::declval<C>().data()), T *>::value &&
107       std::is_integral<decltype(std::declval<C>().size())>::value>;
108 
109   static const size_t npos = static_cast<size_t>(-1);
110 
111  public:
Span()112   constexpr Span() : Span(nullptr, 0) {}
Span(T * ptr,size_t len)113   constexpr Span(T *ptr, size_t len) : data_(ptr), size_(len) {}
114 
115   template <size_t N>
Span(T (& array)[N])116   constexpr Span(T (&array)[N]) : Span(array, N) {}
117 
118   template <
119       typename C, typename = typename EnableIfContainer<C>::type,
120       typename = typename std::enable_if<std::is_const<T>::value, C>::type>
Span(const C & container)121   Span(const C &container) : data_(container.data()), size_(container.size()) {}
122 
123   template <
124       typename C, typename = typename EnableIfContainer<C>::type,
125       typename = typename std::enable_if<!std::is_const<T>::value, C>::type>
Span(C & container)126   explicit Span(C &container)
127       : data_(container.data()), size_(container.size()) {}
128 
data()129   T *data() const { return data_; }
size()130   size_t size() const { return size_; }
empty()131   bool empty() const { return size_ == 0; }
132 
begin()133   T *begin() const { return data_; }
cbegin()134   const T *cbegin() const { return data_; }
end()135   T *end() const { return data_ + size_; }
cend()136   const T *cend() const { return end(); }
137 
front()138   T &front() const {
139     if (size_ == 0) {
140       abort();
141     }
142     return data_[0];
143   }
back()144   T &back() const {
145     if (size_ == 0) {
146       abort();
147     }
148     return data_[size_ - 1];
149   }
150 
151   T &operator[](size_t i) const {
152     if (i >= size_) {
153       abort();
154     }
155     return data_[i];
156   }
at(size_t i)157   T &at(size_t i) const { return (*this)[i]; }
158 
159   Span subspan(size_t pos = 0, size_t len = npos) const {
160     if (pos > size_) {
161       abort();  // absl::Span throws an exception here.
162     }
163     return Span(data_ + pos, std::min(size_ - pos, len));
164   }
165 
166  private:
167   T *data_;
168   size_t size_;
169 };
170 
171 template <typename T>
172 const size_t Span<T>::npos;
173 
174 template <typename T>
MakeSpan(T * ptr,size_t size)175 Span<T> MakeSpan(T *ptr, size_t size) {
176   return Span<T>(ptr, size);
177 }
178 
179 template <typename C>
180 auto MakeSpan(C &c) -> decltype(MakeSpan(c.data(), c.size())) {
181   return MakeSpan(c.data(), c.size());
182 }
183 
184 template <typename T>
MakeConstSpan(T * ptr,size_t size)185 Span<const T> MakeConstSpan(T *ptr, size_t size) {
186   return Span<const T>(ptr, size);
187 }
188 
189 template <typename C>
190 auto MakeConstSpan(const C &c) -> decltype(MakeConstSpan(c.data(), c.size())) {
191   return MakeConstSpan(c.data(), c.size());
192 }
193 
194 BSSL_NAMESPACE_END
195 
196 }  // extern C++
197 
198 #endif  // !defined(BORINGSSL_NO_CXX)
199 
200 #endif  // OPENSSL_HEADER_SSL_SPAN_H
201