1// Copyright 2016 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef MOJO_PUBLIC_CPP_BINDINGS_ARRAY_TRAITS_H_
6#define MOJO_PUBLIC_CPP_BINDINGS_ARRAY_TRAITS_H_
7
8namespace mojo {
9
10// This must be specialized for any type |T| to be serialized/deserialized as
11// a mojom array.
12//
13// Usually you would like to do a partial specialization for a container (e.g.
14// vector) template. Imagine you want to specialize it for Container<>, you need
15// to implement:
16//
17//   template <typename T>
18//   struct ArrayTraits<Container<T>> {
19//     using Element = T;
20//     // These two statements are optional. Use them if you'd like to serialize
21//     // a container that supports iterators but does not support O(1) random
22//     // access and so GetAt(...) would be expensive.
23//     // using Iterator = T::iterator;
24//     // using ConstIterator = T::const_iterator;
25//
26//     // These two methods are optional. Please see comments in struct_traits.h
27//     static bool IsNull(const Container<T>& input);
28//     static void SetToNull(Container<T>* output);
29//
30//     static size_t GetSize(const Container<T>& input);
31//
32//     // These two methods are optional. They are used to access the
33//     // underlying storage of the array to speed up copy of POD types.
34//     static T* GetData(Container<T>& input);
35//     static const T* GetData(const Container<T>& input);
36//
37//     // The following six methods are optional if the GetAt(...) methods are
38//     // implemented. These methods specify how to read the elements of
39//     // Container in some sequential order specified by the iterator.
40//     //
41//     // Acquires an iterator positioned at the first element in the container.
42//     static ConstIterator GetBegin(const Container<T>& input);
43//     static Iterator GetBegin(Container<T>& input);
44//
45//     // Advances |iterator| to the next position within the container.
46//     static void AdvanceIterator(ConstIterator& iterator);
47//     static void AdvanceIterator(Iterator& iterator);
48//
49//     // Returns a reference to the value at the current position of
50//     // |iterator|.
51//     static const T& GetValue(ConstIterator& iterator);
52//     static T& GetValue(Iterator& iterator);
53//
54//     // These two methods are optional if the iterator methods are
55//     // implemented.
56//     static T& GetAt(Container<T>& input, size_t index);
57//     static const T& GetAt(const Container<T>& input, size_t index);
58//
59//     // Returning false results in deserialization failure and causes the
60//     // message pipe receiving it to be disconnected.
61//     static bool Resize(Container<T>& input, size_t size);
62//   };
63//
64template <typename T>
65struct ArrayTraits;
66
67}  // namespace mojo
68
69#endif  // MOJO_PUBLIC_CPP_BINDINGS_ARRAY_TRAITS_H_
70