A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
data-rate.h
Go to the documentation of this file.
1//
2// Copyright (c) 2006 Georgia Tech Research Corporation
3//
4// SPDX-License-Identifier: GPL-2.0-only
5//
6// Author: Rajib Bhattacharjea<raj.b@gatech.edu>
7//
8
9#ifndef DATA_RATE_H
10#define DATA_RATE_H
11
12#include "ns3/attribute-helper.h"
13#include "ns3/attribute.h"
14#include "ns3/nstime.h"
15
16#include <iostream>
17#include <stdint.h>
18#include <string>
19
20namespace ns3
21{
22
23/**
24 * @ingroup network
25 * @defgroup datarate Data Rate
26 */
27/**
28 * @ingroup datarate
29 * @brief Class for representing data rates
30 *
31 * Allows for natural and familiar use of data rates. Allows construction
32 * from strings, natural multiplication e.g.:
33 * @code
34 * DataRate x("56kbps");
35 * double nBits = x*ns3::Seconds (19.2);
36 * uint32_t nBytes = 20;
37 * Time txtime = x.CalculateBytesTxTime (nBytes);
38 * @endcode
39 * This class also supports the regular comparison operators \c <, \c >,
40 * \c <=, \c >=, \c ==, and \c !=
41 *
42 * Data rate specifiers consist of
43 * * A numeric value,
44 * * An optional multiplier prefix and
45 * * A unit.
46 *
47 * Whitespace is allowed but not required between the numeric value and
48 * multiplier or unit.
49 *
50 * Supported multiplier prefixes:
51 *
52 * | Prefix | Value |
53 * | :------- | ----------: |
54 * | "k", "K" | 1000 |
55 * | "Ki" | 1024 |
56 * | "M" | 1000000 |
57 * | "Mi" | 1024 Ki |
58 * | "G" | 10^9 |
59 * | "Gi " | 1024 Mi |
60 *
61 * Supported unit strings:
62 *
63 * | Symbol | Meaning |
64 * | :------- | :---------- |
65 * | "b" | bits |
66 * | "B" | 8-bit bytes |
67 * | "s", "/s"| per second |
68 *
69 * Examples:
70 * * "56kbps" = 56,000 bits/s
71 * * "128 kb/s" = 128,000 bits/s
72 * * "8Kib/s" = 1 KiB/s = 8192 bits/s
73 * * "1kB/s" = 8000 bits/s
74 *
75 * @see attribute_DataRate
76 */
78{
79 public:
80 DataRate();
81 /**
82 * @brief Integer constructor
83 *
84 * Construct a data rate from an integer. This class only supports positive
85 * integer data rates in units of bits/s, meaning 1bit/s is the smallest
86 * non-trivial bitrate available.
87 * @param bps bit/s value
88 */
89 DataRate(uint64_t bps);
90 /**
91 * @brief String constructor
92 *
93 * Construct a data rate from a string. Many different unit strings are supported
94 * Supported unit strings:
95 * bps, b/s, Bps, B/s \n
96 * kbps, kb/s, Kbps, Kb/s, kBps, kB/s, KBps, KB/s, Kib/s, KiB/s \n
97 * Mbps, Mb/s, MBps, MB/s, Mib/s, MiB/s \n
98 * Gbps, Gb/s, GBps, GB/s, Gib/s, GiB/s \n
99 *
100 * Examples:
101 * "56kbps" = 56,000 bits/s \n
102 * "128 kb/s" = 128,000 bits/s \n
103 * "8Kib/s" = 1 KiB/s = 8192 bits/s \n
104 * "1kB/s" = 8000 bits/s
105 *
106 * @param rate string representing the desired rate
107 */
108 DataRate(std::string rate);
109
110 /**
111 * @return the DataRate representing the sum of this object with rhs
112 *
113 * @param rhs the DataRate to add to this DataRate
114 */
115 DataRate operator+(DataRate rhs) const;
116
117 /**
118 * @return the DataRate representing the sum of this object with rhs
119 *
120 * @param rhs the DataRate to add to this DataRate
121 */
123
124 /**
125 * @return the DataRate representing the difference of this object with rhs
126 *
127 * @param rhs the DataRate to subtract from this DataRate
128 */
129 DataRate operator-(DataRate rhs) const;
130
131 /**
132 * @return the DataRate representing the difference of this object with rhs
133 *
134 * @param rhs the DataRate to subtract from this DataRate
135 */
137
138 /**
139 * @brief Scales the DataRate
140 *
141 * Multiplies with double and is re-casted to an int
142 *
143 * @return DataRate object representing the product of this object with rhs
144 *
145 * @param rhs the double to multiply to this datarate
146 */
147 DataRate operator*(double rhs) const;
148
149 /**
150 * @brief Scales the DataRate
151 *
152 * Multiplies with double and is re-casted to an int
153 *
154 * @return DataRate object representing the product of this object with rhs
155 *
156 * @param rhs the double to multiply to this datarate
157 */
158 DataRate& operator*=(double rhs);
159
160 /**
161 * @brief Scales the DataRate
162 *
163 * @return DataRate object representing the product of this object with rhs
164 *
165 * @param rhs the uint64_t to multiply to this datarate
166 */
167 DataRate operator*(uint64_t rhs) const;
168
169 /**
170 * @brief Scales the DataRate
171 *
172 * @return DataRate object representing the product of this object with rhs
173 *
174 * @param rhs the uint64_t to multiply to this datarate
175 */
176 DataRate& operator*=(uint64_t rhs);
177
178 /**
179 * @return true if this rate is less than rhs
180 *
181 * @param rhs the datarate to compare to this datarate
182 */
183 bool operator<(const DataRate& rhs) const;
184
185 /**
186 * @return true if this rate is less than or equal to rhs
187 *
188 * @param rhs the datarate to compare to this datarate
189 */
190 bool operator<=(const DataRate& rhs) const;
191
192 /**
193 * @return true if this rate is greater than rhs
194 *
195 * @param rhs the datarate to compare to this datarate
196 */
197 bool operator>(const DataRate& rhs) const;
198
199 /**
200 * @return true if this rate is greater than or equal to rhs
201 *
202 * @param rhs the datarate to compare to this datarate
203 */
204 bool operator>=(const DataRate& rhs) const;
205
206 /**
207 * @return true if this rate is equal to rhs
208 *
209 * @param rhs the datarate to compare to this datarate
210 */
211 bool operator==(const DataRate& rhs) const;
212
213 /**
214 * @return true if this rate is not equal to rhs
215 *
216 * @param rhs the datarate to compare to this datarate
217 */
218 bool operator!=(const DataRate& rhs) const;
219
220 /**
221 * @brief Calculate transmission time
222 *
223 * Calculates the transmission time at this data rate
224 * @param bytes The number of bytes (not bits) for which to calculate
225 * @return The transmission time for the number of bytes specified
226 */
228
229 /**
230 * @brief Calculate transmission time
231 *
232 * Calculates the transmission time at this data rate
233 * @param bits The number of bits (not bytes) for which to calculate
234 * @return The transmission time for the number of bits specified
235 */
237
238 /**
239 * Get the underlying bitrate
240 * @return The underlying bitrate in bits per second
241 */
242 uint64_t GetBitRate() const;
243
244 private:
245 /**
246 * @brief Parse a string representing a DataRate into an uint64_t
247 *
248 * Allowed unit representations include all combinations of
249 *
250 * * An SI prefix: k, K, M, G
251 * * Decimal or kibibit (as in "Kibps", meaning 1024 bps)
252 * * Bits or bytes (8 bits)
253 * * "bps" or "/s"
254 *
255 * @param [in] s The string representation, including unit
256 * @param [in,out] v The location to put the value, in bits/sec.
257 * @return true if parsing was successful.
258 */
259 static bool DoParse(const std::string s, uint64_t* v);
260
261 // Uses DoParse
262 friend std::istream& operator>>(std::istream& is, DataRate& rate);
263
264 uint64_t m_bps; //!< data rate [bps]
265};
266
267/**
268 * @brief Stream insertion operator.
269 *
270 * @param os the stream
271 * @param rate the data rate
272 * @returns a reference to the stream
273 */
274std::ostream& operator<<(std::ostream& os, const DataRate& rate);
275
276/**
277 * @brief Stream extraction operator.
278 *
279 * @param is the stream
280 * @param rate the data rate
281 * @returns a reference to the stream
282 */
283std::istream& operator>>(std::istream& is, DataRate& rate);
284
286
287/**
288 * @brief Multiply datarate by a time value
289 *
290 * Calculates the number of bits that have been transmitted over a period of time
291 * @param lhs rate
292 * @param rhs time
293 * @return the number of bits over the period of time
294 */
295double operator*(const DataRate& lhs, const Time& rhs);
296/**
297 * @brief Multiply time value by a data rate
298 *
299 * Calculates the number of bits that have been transmitted over a period of time
300 * @param lhs time
301 * @param rhs rate
302 * @return the number of bits over the period of time
303 */
304double operator*(const Time& lhs, const DataRate& rhs);
305
306namespace TracedValueCallback
307{
308
309/**
310 * @ingroup network
311 * TracedValue callback signature for DataRate
312 *
313 * @param [in] oldValue original value of the traced variable
314 * @param [in] newValue new value of the traced variable
315 */
316typedef void (*DataRate)(DataRate oldValue, DataRate newValue);
317
318} // namespace TracedValueCallback
319
320} // namespace ns3
321
322#endif /* DATA_RATE_H */
Class for representing data rates.
Definition data-rate.h:78
DataRate & operator*=(double rhs)
Scales the DataRate.
Definition data-rate.cc:164
bool operator==(const DataRate &rhs) const
Definition data-rate.cc:208
bool operator<(const DataRate &rhs) const
Definition data-rate.cc:184
bool operator>(const DataRate &rhs) const
Definition data-rate.cc:196
bool operator!=(const DataRate &rhs) const
Definition data-rate.cc:214
bool operator>=(const DataRate &rhs) const
Definition data-rate.cc:202
DataRate operator-(DataRate rhs) const
Definition data-rate.cc:143
Time CalculateBitsTxTime(uint32_t bits) const
Calculate transmission time.
Definition data-rate.cc:227
static bool DoParse(const std::string s, uint64_t *v)
Parse a string representing a DataRate into an uint64_t.
Definition data-rate.cc:24
uint64_t m_bps
data rate [bps]
Definition data-rate.h:264
uint64_t GetBitRate() const
Get the underlying bitrate.
Definition data-rate.cc:234
bool operator<=(const DataRate &rhs) const
Definition data-rate.cc:190
DataRate & operator+=(DataRate rhs)
Definition data-rate.cc:136
DataRate operator+(DataRate rhs) const
Definition data-rate.cc:130
DataRate operator*(double rhs) const
Scales the DataRate.
Definition data-rate.cc:158
Time CalculateBytesTxTime(uint32_t bytes) const
Calculate transmission time.
Definition data-rate.cc:220
DataRate & operator-=(DataRate rhs)
Definition data-rate.cc:150
friend std::istream & operator>>(std::istream &is, DataRate &rate)
Stream extraction operator.
Definition data-rate.cc:260
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
#define ATTRIBUTE_HELPER_HEADER(type)
Declare the attribute value, accessor and checkers for class type
int64x64_t operator*(const int64x64_t &lhs, const int64x64_t &rhs)
Multiplication operator.
Definition int64x64.h:106
Every class exported by the ns3 library is enclosed in the ns3 namespace.
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
std::istream & operator>>(std::istream &is, Angles &a)
Definition angles.cc:172