src/mojo/public/cpp/bindings/type_converter.h

   1 // Copyright 2014 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_TYPE_CONVERTER_H_
   6 #define MOJO_PUBLIC_CPP_BINDINGS_TYPE_CONVERTER_H_
   7
   8 namespace mojo {
   9
  10 // Specialize to perform type conversion for Mojom-defined structs and arrays.
  11 // Here, T is the Mojom-defined struct or array, and U is some other non-Mojom
  12 // struct or array type.
  13 //
  14 // EXAMPLE:
  15 //
  16 // Suppose you have the following Mojom-defined struct:
  17 //
  18 //   module geometry {
  19 //   struct Point {
  20 //     int32 x;
  21 //     int32 y;
  22 //   };
  23 //   }
  24 //
  25 // Now, imagine you wanted to write a TypeConverter specialization for
  26 // gfx::Point. It might look like this:
  27 //
  28 //   namespace mojo {
  29 //   template <>
  30 //   class TypeConverter<geometry::Point, gfx::Point> {
  31 //    public:
  32 //     static geometry::Point ConvertFrom(const gfx::Point& input,
  33 //                                        Buffer* buf) {
  34 //       geometry::Point::Builder builder(buf);
  35 //       builder.set_x(input.x());
  36 //       builder.set_y(input.y());
  37 //       return builder.Finish();
  38 //     }
  39 //     static gfx::Point ConvertTo(const geometry::Point& input) {
  40 //       return gfx::Point(input.x(), input.y());
  41 //     }
  42 //   };
  43 //   }
  44 //
  45 // With the above TypeConverter defined, it is possible to write code like this:
  46 //
  47 //   void AcceptPoint(const geometry::Point& input) {
  48 //     // With an explicit cast using the .To<> method.
  49 //     gfx::Point pt = input.To<gfx::Point>();
  50 //
  51 //     mojo::AllocationScope scope;
  52 //     // With an explicit cast using the static From() method.
  53 //     geometry::Point output = geometry::Point::From(pt);
  54 //   }
  55 //
  56 // More "direct" conversions can be enabled by adding the following macro to the
  57 // TypeConverter specialization:
  58 //   MOJO_ALLOW_IMPLICIT_TYPE_CONVERSION();
  59 //
  60 // To be exact, this macro enables:
  61 // - converting constructor:
  62 //   T(const U& u, mojo::Buffer* buf = mojo::Buffer::current());
  63 // - assignment operator:
  64 //   T& operator=(const U& u);
  65 // - conversion operator:
  66 //   operator U() const;
  67 //
  68 // If the macro is added to TypeConverter<geometry::Point, gfx::Point>, for
  69 // example, it is possible to write code like this:
  70 //
  71 //   void SomeFunction(const gfx::Point& pt);
  72 //
  73 //   void AcceptPoint(const geometry::Point& input) {
  74 //     // Using the conversion operator.
  75 //     SomeFunction(input);
  76 //
  77 //     mojo::AllocationScope scope;
  78 //     // Using the converting constructor.
  79 //     geometry::Point output_1(pt);
  80 //
  81 //     geometry::Point output_2;
  82 //     // Using the assignment operator.
  83 //     output_2 = pt;
  84 //   }
  85 //
  86 // There is another macro to inherit implicit conversion settings from another
  87 // TypeConverter:
  88 //   MOJO_INHERIT_IMPLICIT_TYPE_CONVERSION(X, Y);
  89 //
  90 // It allows implicit conversions if and only if TypeConverter<X, Y> allows
  91 // implicit conversions. This is useful when defining TypeConverter for
  92 // container types.
  93 //
  94 // Although these macros are convenient, they make conversions less obvious.
  95 // Users may do conversions excessively without paying attention to the cost. So
  96 // please use them wisely.
  97 template <typename T, typename U> class TypeConverter {
  98   // static T ConvertFrom(const U& input, Buffer* buf);
  99   // static U ConvertTo(const T& input);
 100
 101   // Maybe (mutually exclusive):
 102   // MOJO_ALLOW_IMPLICIT_TYPE_CONVERSION();
 103   // MOJO_INHERIT_IMPLICIT_TYPE_CONVERSION(X, Y);
 104 };
 105
 106 }  // namespace mojo
 107
 108 #define MOJO_ALLOW_IMPLICIT_TYPE_CONVERSION() \
 109   static void AssertAllowImplicitTypeConversion() {}
 110
 111 #define MOJO_INHERIT_IMPLICIT_TYPE_CONVERSION(T, U) \
 112   static void AssertAllowImplicitTypeConversion() { \
 113     TypeConverter<T, U>::AssertAllowImplicitTypeConversion(); \
 114   }
 115
 116 #endif  // MOJO_PUBLIC_CPP_BINDINGS_TYPE_CONVERTER_H_