Line data Source code
1 : #ifndef HASHBROWNS_DATA_STRUCTURE_H
2 : #define HASHBROWNS_DATA_STRUCTURE_H
3 :
4 : #include <string>
5 : #include <memory>
6 : #include <functional>
7 :
8 : namespace hashbrowns {
9 :
10 : /**
11 : * @brief Abstract base class for all data structures in the benchmarking suite
12 : *
13 : * This polymorphic interface enables dynamic benchmarking without type switching.
14 : * All data structures implement these core operations for consistent measurement.
15 : *
16 : * Key design principles:
17 : * - Pure virtual interface for polymorphic behavior
18 : * - Consistent operation signatures across implementations
19 : * - Memory management handled by derived classes
20 : * - Exception safety through RAII principles
21 : */
22 : class DataStructure {
23 : public:
24 : /**
25 : * @brief Virtual destructor for proper cleanup in inheritance hierarchy
26 : */
27 121 : virtual ~DataStructure() = default;
28 :
29 : /**
30 : * @brief Insert a key-value pair into the data structure
31 : * @param key The integer key to insert
32 : * @param value The string value associated with the key
33 : * @throws std::bad_alloc if memory allocation fails
34 : * @throws std::invalid_argument if key is invalid for the structure
35 : */
36 : virtual void insert(int key, const std::string& value) = 0;
37 :
38 : /**
39 : * @brief Search for a value by key
40 : * @param key The key to search for
41 : * @param value Output parameter to store the found value
42 : * @return true if key found, false otherwise
43 : * @note value parameter is only modified if key is found
44 : */
45 : virtual bool search(int key, std::string& value) const = 0;
46 :
47 : /**
48 : * @brief Remove a key-value pair from the data structure
49 : * @param key The key to remove
50 : * @return true if key was found and removed, false otherwise
51 : */
52 : virtual bool remove(int key) = 0;
53 :
54 : /**
55 : * @brief Get the current number of elements in the structure
56 : * @return Number of key-value pairs currently stored
57 : */
58 : virtual size_t size() const = 0;
59 :
60 : /**
61 : * @brief Check if the data structure is empty
62 : * @return true if size() == 0, false otherwise
63 : */
64 : virtual bool empty() const = 0;
65 :
66 : /**
67 : * @brief Remove all elements from the data structure
68 : * @post size() == 0 && empty() == true
69 : */
70 : virtual void clear() = 0;
71 :
72 : /**
73 : * @brief Get the current memory usage in bytes (approximate)
74 : * @return Estimated memory footprint of the data structure
75 : * @note Used for memory usage analysis in benchmarks
76 : */
77 : virtual size_t memory_usage() const = 0;
78 :
79 : /**
80 : * @brief Get a human-readable name for this data structure type
81 : * @return String identifier (e.g., "DynamicArray", "LinkedList", "HashMap")
82 : */
83 : virtual std::string type_name() const = 0;
84 :
85 : /**
86 : * @brief Get theoretical time complexity for insert operation
87 : * @return String describing complexity (e.g., "O(1)", "O(n)")
88 : */
89 : virtual std::string insert_complexity() const = 0;
90 :
91 : /**
92 : * @brief Get theoretical time complexity for search operation
93 : * @return String describing complexity (e.g., "O(1)", "O(n)")
94 : */
95 : virtual std::string search_complexity() const = 0;
96 :
97 : /**
98 : * @brief Get theoretical time complexity for remove operation
99 : * @return String describing complexity (e.g., "O(1)", "O(n)")
100 : */
101 : virtual std::string remove_complexity() const = 0;
102 :
103 : protected:
104 : /**
105 : * @brief Protected default constructor - only derived classes can instantiate
106 : */
107 121 : DataStructure() = default;
108 :
109 : /**
110 : * @brief Protected copy constructor - derived classes control copying
111 : */
112 : DataStructure(const DataStructure&) = default;
113 :
114 : /**
115 : * @brief Protected copy assignment - derived classes control assignment
116 : */
117 : DataStructure& operator=(const DataStructure&) = default;
118 :
119 : /**
120 : * @brief Protected move constructor - derived classes control moving
121 : */
122 : DataStructure(DataStructure&&) = default;
123 :
124 : /**
125 : * @brief Protected move assignment - derived classes control move assignment
126 : */
127 : DataStructure& operator=(DataStructure&&) = default;
128 : };
129 :
130 : /**
131 : * @brief Smart pointer type for managing DataStructure instances
132 : *
133 : * This alias provides consistent memory management and polymorphic behavior
134 : * throughout the benchmarking framework.
135 : */
136 : using DataStructurePtr = std::unique_ptr<DataStructure>;
137 :
138 : /**
139 : * @brief Factory function signature for creating data structure instances
140 : *
141 : * Factory functions allow dynamic creation of different data structure types
142 : * based on string identifiers or other runtime parameters.
143 : */
144 : using DataStructureFactory = std::function<DataStructurePtr()>;
145 :
146 : } // namespace hashbrowns
147 :
148 : #endif // HASHBROWNS_DATA_STRUCTURE_H
|
