.. _program_listing_file__tmp_ws_src_marti_common_swri_route_util_include_swri_route_util_route.h:

Program Listing for File route.h
================================

|exhale_lsh| :ref:`Return to documentation for file <file__tmp_ws_src_marti_common_swri_route_util_include_swri_route_util_route.h>` (``/tmp/ws/src/marti_common/swri_route_util/include/swri_route_util/route.h``)

.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS

.. code-block:: cpp

   // *****************************************************************************
   //
   // Copyright (c) 2016, Southwest Research Institute® (SwRI®)
   // All rights reserved.
   //
   // Redistribution and use in source and binary forms, with or without
   // modification, are permitted provided that the following conditions are met:
   //     * Redistributions of source code must retain the above copyright
   //       notice, this list of conditions and the following disclaimer.
   //     * Redistributions in binary form must reproduce the above copyright
   //       notice, this list of conditions and the following disclaimer in the
   //       documentation and/or other materials provided with the distribution.
   //     * Neither the name of Southwest Research Institute® (SwRI®) nor the
   //       names of its contributors may be used to endorse or promote products
   //       derived from this software without specific prior written permission.
   //
   // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
   // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   // ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
   // DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
   // (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
   // ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   //
   // *****************************************************************************
   #ifndef SWRI_ROUTE_UTIL_ROUTE_H_
   #define SWRI_ROUTE_UTIL_ROUTE_H_
   
   #include <string>
   #include <map>
   #include <vector>
   
   #include <boost/lexical_cast.hpp>
   
   #include <marti_nav_msgs/msg/route.hpp>
   #include <swri_route_util/route_point.h>
   
   namespace swri_route_util
   {
   // The Route class provides a more friendly interface for working with
   // the marti_nav_msgs::Route message.  It provides native access to
   // known properties and supports fast lookups of points by their ids.
   //
   // This class is optimized for a combination of simplicity, nice
   // syntax, and performance for standard use cases.  This means that
   // some tradeoffs were made for less common use cases.
   //
   // In particular, findPointId() may take a long time when called with
   // ids that do not exist in the route because of the behind-the-scenes
   // caching.  If this is an important use case and you are ABSOLUTELY
   // sure that the points list has not been modified since the class was
   // created from a message, you can avoid this performance hit by
   // calling findPointIdConst() instead.
   class Route
   {
    public:
     // Create a new empty route.
     Route() = default;
   
     // Create a route from an existing marti_nav_msgs::Route message.
     // Warning: If a route or a specific route point contains properties
     // with duplicate keys, only one will be kept; the others are
     // silently discarded.  Don't use non-unique property keys.
     explicit Route(const marti_nav_msgs::msg::Route &msg);
   
     // Create a marti_nav_msgs::Route from the route, in place version.
     void toMsg(marti_nav_msgs::msg::Route &msg) const;
     // Create a marti_nav_msgs::Route from the route, returned as a
     // shared pointer.
     marti_nav_msgs::msg::Route::SharedPtr toMsgPtr() const;
   
     // The header of the route. This is exposed as field to be
     // consistent with typical ROS style.
     std_msgs::msg::Header header;
   
     // The points of the route.  This is exposed as a field because it's
     // much simpler (for me to write and you to use) than trying to
     // replicate the entire vector interface.
     std::vector<RoutePoint> points;
   
     // A route is considered invalid if it has no points.
     bool valid() const;
     
     // Find a point index by its ID.  For the common use case of looking
     // up valid ids in a static route, this will be very fast.  For less
     // common cases like looking up valid ids in a route that has been
     // modified, it may be slower.  It is the slowest when looking up
     // many invalid ids in any route.  If there are multiple points with
     // the requested key, it will return one of the points, but which
     // one is undefined.  Don't use non-unqiue ids.
     bool findPointId(size_t &index, const std::string &id) const;
   
     // Find a point index by its ID, the less safe version.  This
     // version should only be used on Routes with a valid internal index
     // (rebuildPointIndex() was called and points were never added,
     // removed, reordered, or changed ids).  This version will not
     // rebuild the internal point index if an id is not found, so it is
     // much faster for repeated invalid lookups.  If the "static"
     // assumption is violated, this version may incorrectly miss a valid
     // id.  It will never return a point with a different id than
     // requested.  Be sure you know what you're doing if you want to use
     // this.
     bool findPointIdConst(size_t &index, const std::string &id) const;
   
     // Rebuilds the internal point index.  This is handled internally
     // and exposed for very special use cases, which you probably do not
     // need.  Be sure you know what you're doing if you want to use this.
     void rebuildPointIndex() const;
   
     // Native access to the route "name" property, which is required to
     // exist.
     std::string name() const;
     void setName(const std::string &name);
   
     // Native access to the route "guid" property, which is required to
     // exist.
     std::string guid() const;
     void setGuid(const std::string &guid);
   
     // The following methods provide general purpose access to route
     // properties.  They will also correctly map to properties that are
     // exposed natively.  Native methods (e.g.  name(), guid()) are
     // generally faster and safer and should be preferred when
     // available.
   
     // Get a list of all the properties defined for this route,
     // including native properties.
     std::vector<std::string> getPropertyNames() const;
   
     // Get the value of a property.  Returns an empty string if the
     // property does not exist.
     std::string getProperty(const std::string &name) const;
     template <typename T>
   
     // Get the value of a property, lexically cast to a known type.
     // Returns the lexical cast of an empty string if the property does
     // not exist..
     T getTypedProperty(const std::string &name) const;
   
     // Determine if the specified property is defined for the route.
     bool hasProperty(const std::string &name) const;
   
     // Set the value of a property.  If the property doesn't exist, it
     // is added.
     void setProperty(const std::string &name, const std::string &value);
   
     // Delete a property.  If the property doesn't exist or is not
     // deletable (e.g. name, guid), this method does nothing.
     void deleteProperty(const std::string &name);
   
    public:
     // The point index maps point ids to their index in the points
     // vector.  It is mutable because we want to support fast look ups
     // on const Routes.
     mutable std::map<std::string, size_t> point_index_;
   
     // Map containing generic properties.
     std::map<std::string, std::string> properties_;
   
     // Storage for native properties.
     std::string guid_;
     std::string name_;
   };  // class Route
   
   // Typedef shared pointers to make migrating from the message types to
   // this interface more convenient.
   typedef std::shared_ptr<Route> RoutePtr;
   typedef std::shared_ptr<Route const> RouteConstPtr;
   
   template<typename T>
   inline
   T Route::getTypedProperty(const std::string &name) const
   {
     return boost::lexical_cast<T>(getProperty(name));
   }
   } // namespace swri_route_util
   
   // #include "route_serializer.h"
   
   #endif  // SWRI_ROUTE_UTIL_ROUTE_H_