Drake
type_specific_identifier.h
Go to the documentation of this file.
1 #pragma once
2 
3 #include <functional>
4 #include <string>
5 #include <utility>
6 
9 
10 namespace drake {
11 namespace maliput {
12 namespace api {
13 
14 /// %TypeSpecificIdentifier<T> represents an identifier specifically identifying
15 /// an entity of type `T`.
16 ///
17 /// A new %TypeSpecificIdentifier is constructed from a non-empty string;
18 /// TypeSpecificIdentifiers constructed from equal strings are considered to
19 /// be equal. There is currently no other semantic value attributed to the
20 /// contents of the string.
21 ///
22 /// Construction from empty strings is not allowed; there is no notion of
23 /// an "unassigned" value for a %TypeSpecificIdentifier. To represent a
24 /// possibly-unassigned %TypeSpecificIdentifier, use
25 /// drake::optional<TypeSpecificIdentifier<T>>.
26 ///
27 /// %TypeSpecificIdentifier is EqualityComparable (and provides == and !=
28 /// operators), but it is not LessThanComparable; there is no particular
29 /// ordering ascribed to %TypeSpecificIdentifier instances. However,
30 /// %TypeSpecificIdentifier does provide a strict weak ordering via a
31 /// specialization of std::less for use in ordered containers such as std::set
32 /// and std::map. This ordering may change in future implementations of
33 /// %TypeSpecificIdentifier.
34 ///
35 /// %TypeSpecificIdentifier also provides a specialization of std::hash to make
36 /// it easy to use with std::unordered_set and std::unordered_map.
37 template <typename T>
39  public:
41 
42  /// The type whose instances are identified by this TypeSpecificIdentifier.
43  typedef T identified_type;
44 
45  /// Constructs a %TypeSpecificIdentifier from the given `string`.
46  ///
47  /// @throws std::runtime_error if `string` is empty.
48  explicit TypeSpecificIdentifier(std::string string)
49  : string_(std::move(string)) {
50  DRAKE_THROW_UNLESS(!string_.empty());
51  }
52 
53  /// Returns the string representation of the %TypeSpecificIdentifier.
54  const std::string& string() const { return string_; }
55 
56  /// Tests for equality with another %TypeSpecificIdentifier.
57  bool operator==(const TypeSpecificIdentifier<T>& rhs) const {
58  return string_ == rhs.string_;
59  }
60 
61  /// Tests for inequality with another %TypeSpecificIdentifier, specifically
62  /// returning the opposite of operator==().
63  bool operator!=(const TypeSpecificIdentifier<T>& rhs) const {
64  return !(*this == rhs);
65  }
66 
67  private:
68  std::string string_;
69 };
70 
71 } // namespace api
72 } // namespace maliput
73 } // namespace drake
74 
75 
76 namespace std {
77 
78 /// Specialization of std::hash for TypeSpecificIdentifier<T>
79 template <typename T>
80 struct hash<drake::maliput::api::TypeSpecificIdentifier<T>> {
81  typedef std::size_t result_type;
83 
84  result_type operator()(const argument_type& id) const {
85  // NB: Per the GSG, our current style guide strictly prohibits
86  // creating new specializations of std::hash on the grounds that
87  // it is in general difficult to do that correctly. However,
88  // since this implementation is merely a wrapper around
89  // std::string with stricter type checking and since it merely
90  // invokes a C++ standard hash approved by the style guide, it has
91  // been granted an exception. If this implementation changes, the
92  // exception must be reevaluated. Conversely, if the (arguably
93  // maladaptive) prohibition is removed from our style guide, this
94  // notice can go away.
95  return hash<string>{}(id.string());
96  }
97 };
98 
99 /// Specialization of std::less for TypeSpecificIdentifier<T> providing a
100 /// strict weak ordering over TypeSpecificIdentifier<T> suitable for use with
101 /// ordered containers.
102 template <typename T>
103 struct less<drake::maliput::api::TypeSpecificIdentifier<T>> {
104  typedef std::size_t result_type;
107 
108  result_type operator()(const first_argument_type& lhs,
109  const second_argument_type& rhs) const {
110  return lhs.string() < rhs.string();
111  }
112 };
113 
114 } // namespace std
Provides a convenient wrapper to throw an exception when a condition is unmet.
Definition: automotive_demo.cc:88
std::size_t result_type
Definition: type_specific_identifier.h:81
STL namespace.
const std::string & string() const
Returns the string representation of the TypeSpecificIdentifier.
Definition: type_specific_identifier.h:54
#define DRAKE_THROW_UNLESS(condition)
Evaluates condition and iff the value is false will throw an exception with a message showing at leas...
Definition: drake_throw.h:23
drake::maliput::api::TypeSpecificIdentifier< T > second_argument_type
Definition: type_specific_identifier.h:106
std::size_t result_type
Definition: type_specific_identifier.h:104
bool operator==(const TypeSpecificIdentifier< T > &rhs) const
Tests for equality with another TypeSpecificIdentifier.
Definition: type_specific_identifier.h:57
result_type operator()(const first_argument_type &lhs, const second_argument_type &rhs) const
Definition: type_specific_identifier.h:108
TypeSpecificIdentifier<T> represents an identifier specifically identifying an entity of type T...
Definition: type_specific_identifier.h:38
#define DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN(Classname)
DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN defaults the special member functions for copy-construction, copy-assignment, move-construction, and move-assignment.
Definition: drake_copyable.h:57
drake::maliput::api::TypeSpecificIdentifier< T > first_argument_type
Definition: type_specific_identifier.h:105
result_type operator()(const argument_type &id) const
Definition: type_specific_identifier.h:84
bool operator!=(const TypeSpecificIdentifier< T > &rhs) const
Tests for inequality with another TypeSpecificIdentifier, specifically returning the opposite of oper...
Definition: type_specific_identifier.h:63
TypeSpecificIdentifier(std::string string)
Constructs a TypeSpecificIdentifier from the given string.
Definition: type_specific_identifier.h:48
drake::maliput::api::TypeSpecificIdentifier< T > argument_type
Definition: type_specific_identifier.h:82
Provides careful macros to selectively enable or disable the special member functions for copy-constr...
T identified_type
The type whose instances are identified by this TypeSpecificIdentifier.
Definition: type_specific_identifier.h:40