From 1be265e919e7853ece29f5cb93e7d71475f790f4 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Thu, 17 Jun 2021 13:59:37 -0400
Subject: [PATCH] Add release note for type adaptation (#1686) (#1690)

* Add release note for type adaptation

Signed-off-by: Audrow Nash <audrow@hey.com>

* Add examples and demos

Signed-off-by: Audrow Nash <audrow@hey.com>
(cherry picked from commit 41ecc64947801bcea0888fc5cbce023b66443f81)

Co-authored-by: Audrow Nash <audrow.nash@gmail.com>
---
 source/Releases/Release-Humble-Hawksbill.rst | 62 ++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/source/Releases/Release-Humble-Hawksbill.rst b/source/Releases/Release-Humble-Hawksbill.rst
index b064c325409..cf226b087d5 100644
--- a/source/Releases/Release-Humble-Hawksbill.rst
+++ b/source/Releases/Release-Humble-Hawksbill.rst
@@ -46,6 +46,68 @@ To come.
 Changes since the Galactic release
 ----------------------------------
 
+rclcpp
+^^^^^^
+
+Support Type Adaption for Publishers and Subscriptions
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+After defining a type adapter, custom data structures can be used directly by publishers and subscribers, which helps to avoid additional work for the programmer and potential sources of errors.
+This is especially useful when working with complex data types, such as when converting OpenCV's ``cv::Map`` to ROS's ``sensor_msgs/msg/Image`` type.
+
+Here is an example of a type adapter that converts ``std_msgs::msg::String`` to ``std::string``:
+
+.. code-block:: cpp
+
+   template<>
+   struct rclcpp::TypeAdapter<
+      std::string,
+      std_msgs::msg::String
+   >
+   {
+     using is_specialized = std::true_type;
+     using custom_type = std::string;
+     using ros_message_type = std_msgs::msg::String;
+
+     static
+     void
+     convert_to_ros_message(
+       const custom_type & source,
+       ros_message_type & destination)
+     {
+       destination.data = source;
+     }
+
+     static
+     void
+     convert_to_custom(
+       const ros_message_type & source,
+       custom_type & destination)
+     {
+       destination = source.data;
+     }
+   };
+
+And an example of how the type adapter can be used:
+
+.. code-block:: cpp
+
+   using MyAdaptedType = TypeAdapter<std::string, std_msgs::msg::String>;
+
+   // Publish a std::string
+   auto pub = node->create_publisher<MyAdaptedType>(...);
+   std::string custom_msg = "My std::string"
+   pub->publish(custom_msg);
+
+   // Pass a std::string to a subscription's callback
+   auto sub = node->create_subscription<MyAdaptedType>(
+     "topic",
+     10,
+     [](const std::string & msg) {...});
+
+To learn more, see the `publisher <https://github.com/ros2/examples/blob/b83b18598b198b4a5ba44f9266c1bb39a393fa17/rclcpp/topics/minimal_publisher/member_function_with_type_adapter.cpp>`_ and `subscription <https://github.com/ros2/examples/blob/b83b18598b198b4a5ba44f9266c1bb39a393fa17/rclcpp/topics/minimal_subscriber/member_function_with_type_adapter.cpp>`_) examples, as well as a more complex `demo <https://github.com/ros2/demos/pull/482>`_.
+For more details, see `REP 2007 <https://ros.org/reps/rep-2007.html>`_.
+
 ros2cli
 ^^^^^^^