route.h
Go to the documentation of this file.
1 // *****************************************************************************
2 //
3 // Copyright (c) 2016, Southwest Research Institute® (SwRI®)
4 // All rights reserved.
5 //
6 // Redistribution and use in source and binary forms, with or without
7 // modification, are permitted provided that the following conditions are met:
8 // * Redistributions of source code must retain the above copyright
9 // notice, this list of conditions and the following disclaimer.
10 // * Redistributions in binary form must reproduce the above copyright
11 // notice, this list of conditions and the following disclaimer in the
12 // documentation and/or other materials provided with the distribution.
13 // * Neither the name of Southwest Research Institute® (SwRI®) nor the
14 // names of its contributors may be used to endorse or promote products
15 // derived from this software without specific prior written permission.
16 //
17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 // ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
21 // DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22 // (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23 // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24 // ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 //
28 // *****************************************************************************
29 #ifndef SWRI_ROUTE_UTIL_ROUTE_H_
30 #define SWRI_ROUTE_UTIL_ROUTE_H_
31 
32 #include <string>
33 #include <map>
34 #include <vector>
35 
36 #include <boost/lexical_cast.hpp>
37 
38 #include <marti_nav_msgs/Route.h>
40 
41 namespace swri_route_util
42 {
43 // The Route class provides a more friendly interface for working with
44 // the marti_nav_msgs::Route message. It provides native access to
45 // known properties and supports fast lookups of points by their ids.
46 //
47 // This class is optimized for a combination of simplicity, nice
48 // syntax, and performance for standard use cases. This means that
49 // some tradeoffs were made for less common use cases.
50 //
51 // In particular, findPointId() may take a long time when called with
52 // ids that do not exist in the route because of the behind-the-scenes
53 // caching. If this is an important use case and you are ABSOLUTELY
54 // sure that the points list has not been modified since the class was
55 // created from a message, you can avoid this performance hit by
56 // calling findPointIdConst() instead.
57 class Route
58 {
59  public:
60  // Create a new empty route.
61  Route();
62 
63  // Create a route from an existing marti_nav_msgs::Route message.
64  // Warning: If a route or a specific route point contains properties
65  // with duplicate keys, only one will be kept; the others are
66  // silently discarded. Don't use non-unique property keys.
67  Route(const marti_nav_msgs::Route &msg);
68 
69  // Create a marti_nav_msgs::Route from the route, in place version.
70  void toMsg(marti_nav_msgs::Route &msg) const;
71  // Create a marti_nav_msgs::Route from the route, returned as a
72  // shared pointer.
74 
75  // The header of the route. This is exposed as field to be
76  // consistent with typical ROS style.
77  std_msgs::Header header;
78 
79  // The points of the route. This is exposed as a field because it's
80  // much simpler (for me to write and you to use) than trying to
81  // replicate the entire vector interface.
82  std::vector<RoutePoint> points;
83 
84  // A route is considered invalid if it has no points.
85  bool valid() const;
86 
87  // Find a point index by its ID. For the common use case of looking
88  // up valid ids in a static route, this will be very fast. For less
89  // common cases like looking up valid ids in a route that has been
90  // modified, it may be slower. It is the slowest when looking up
91  // many invalid ids in any route. If there are multiple points with
92  // the requested key, it will return one of the points, but which
93  // one is undefined. Don't use non-unqiue ids.
94  bool findPointId(size_t &index, const std::string &id) const;
95 
96  // Find a point index by its ID, the less safe version. This
97  // version should only be used on Routes with a valid internal index
98  // (rebuildPointIndex() was called and points were never added,
99  // removed, reordered, or changed ids). This version will not
100  // rebuild the internal point index if an id is not found, so it is
101  // much faster for repeated invalid lookups. If the "static"
102  // assumption is violated, this version may incorrectly miss a valid
103  // id. It will never return a point with a different id than
104  // requested. Be sure you know what you're doing if you want to use
105  // this.
106  bool findPointIdConst(size_t &index, const std::string &id) const;
107 
108  // Rebuilds the internal point index. This is handled internally
109  // and exposed for very special use cases, which you probably do not
110  // need. Be sure you know what you're doing if you want to use this.
111  void rebuildPointIndex() const;
112 
113  // Native access to the route "name" property, which is required to
114  // exist.
115  std::string name() const;
116  void setName(const std::string &name);
117 
118  // Native access to the route "guid" property, which is required to
119  // exist.
120  std::string guid() const;
121  void setGuid(const std::string &guid);
122 
123  // The following methods provide general purpose access to route
124  // properties. They will also correctly map to properties that are
125  // exposed natively. Native methods (e.g. name(), guid()) are
126  // generally faster and safer and should be preferred when
127  // available.
128 
129  // Get a list of all the properties defined for this route,
130  // including native properties.
131  std::vector<std::string> getPropertyNames() const;
132 
133  // Get the value of a property. Returns an empty string if the
134  // property does not exist.
135  std::string getProperty(const std::string &name) const;
136  template <typename T>
137 
138  // Get the value of a property, lexically cast to a known type.
139  // Returns the lexical cast of an empty string if the property does
140  // not exist..
141  T getTypedProperty(const std::string &name) const;
142 
143  // Determine if the specified property is defined for the route.
144  bool hasProperty(const std::string &name) const;
145 
146  // Set the value of a property. If the property doesn't exist, it
147  // is added.
148  void setProperty(const std::string &name, const std::string &value);
149 
150  // Delete a property. If the property doesn't exist or is not
151  // deletable (e.g. name, guid), this method does nothing.
152  void deleteProperty(const std::string &name);
153 
154  public:
155  // The point index maps point ids to their index in the points
156  // vector. It is mutable because we want to support fast look ups
157  // on const Routes.
158  mutable std::map<std::string, size_t> point_index_;
159 
160  // Map containing generic properties.
161  std::map<std::string, std::string> properties_;
162 
163  // Storage for native properties.
164  std::string guid_;
165  std::string name_;
166 }; // class Route
167 
168 // Typedef shared pointers to make migrating from the message types to
169 // this interface more convenient.
172 
173 template<typename T>
174 inline
175 T Route::getTypedProperty(const std::string &name) const
176 {
177  return boost::lexical_cast<T>(getProperty(name));
178 }
179 } // namespace swri_route_util
180 
181 #include "route_serializer.h"
182 
183 #endif // SWRI_ROUTE_UTIL_ROUTE_H_
msg
void rebuildPointIndex() const
Definition: route.cpp:236
std::string guid() const
Definition: route.cpp:226
void setGuid(const std::string &guid)
Definition: route.cpp:231
std::vector< std::string > getPropertyNames() const
Definition: route.cpp:158
void setProperty(const std::string &name, const std::string &value)
Definition: route.cpp:195
T getTypedProperty(const std::string &name) const
Definition: route.h:175
std_msgs::Header header
Definition: route.h:77
std::map< std::string, std::string > properties_
Definition: route.h:161
bool valid() const
Definition: route.cpp:108
std::map< std::string, size_t > point_index_
Definition: route.h:158
marti_nav_msgs::RoutePtr toMsgPtr() const
Definition: route.cpp:101
void setName(const std::string &name)
Definition: route.cpp:221
std::string name_
Definition: route.h:165
std::string name() const
Definition: route.cpp:216
std::string guid_
Definition: route.h:164
bool findPointId(size_t &index, const std::string &id) const
Definition: route.cpp:113
bool hasProperty(const std::string &name) const
Definition: route.cpp:184
void toMsg(marti_nav_msgs::Route &msg) const
Definition: route.cpp:84
std::vector< RoutePoint > points
Definition: route.h:82
boost::shared_ptr< Route > RoutePtr
Definition: route.h:170
bool findPointIdConst(size_t &index, const std::string &id) const
Definition: route.cpp:143
std::string getProperty(const std::string &name) const
Definition: route.cpp:171
boost::shared_ptr< Route const > RouteConstPtr
Definition: route.h:171
void deleteProperty(const std::string &name)
Definition: route.cpp:206


swri_route_util
Author(s):
autogenerated on Tue Apr 6 2021 02:50:48