/src/PcapPlusPlus/Common++/header/MacAddress.h

Source
#pragma once

#include <algorithm>
#include <initializer_list>
#include <iterator>
#include <ostream>
#include <cstdint>
#include <string>
#include <array>
#include <memory>

#include "DeprecationUtils.h"

/// @file

/// @namespace pcpp
/// @brief The main namespace for the PcapPlusPlus lib
namespace pcpp
{

  /// @class MacAddress
  /// Represents L2 MAC addresses. Can be constructed from string or a series of 6 byte octets
  class MacAddress
  {
  public:
    /// Default constructor for this class.
    /// Initializes the address as 00:00:00:00:00:00.
    MacAddress() = default;

    /// A constructor that creates an instance of the class out of a byte array.
    /// The byte array length should be 6 (as MAC address is 6-byte long), and the remaining bytes are ignored.
    /// If the byte array is invalid, the constructor throws an exception.
    /// @param[in] addr A pointer to the byte array containing 6 bytes representing the MAC address
    /// @remarks This constructor assumes that the provided array is exactly 6 bytes long.
    /// Prefer using the constructor with size parameter if the array length is not guaranteed to be 6 bytes.
    explicit MacAddress(const uint8_t addr[6]) : MacAddress(addr, 6)
    {}

    /// @brief A constructor that creates an instance of the class out of a byte array of 6 bytes.
    /// @param[in] addr The address as a byte array in network byte order
    /// @param[in] size The size of the array in bytes
    /// @throws std::invalid_argument If the address pointer is null.
    /// @throws std::out_of_range If the provided size is smaller than 6 bytes.
    explicit MacAddress(const uint8_t* addr, size_t size);

    /// A constructor that creates an instance of the class out of a std::array.
    /// The array length should be 6 (as MAC address is 6-byte long).
    /// @param [in] addr A std::array containing 6 bytes representing the MAC address
    explicit MacAddress(const std::array<uint8_t, 6>& addr) : m_Address(addr)
    {}

    /// A constructor that creates an instance of the class out of a std::string.
    /// If the string doesn't represent a valid MAC address, the constructor throws an exception.
    /// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00"
    explicit MacAddress(const std::string& addr);

    /// A template constructor that creates an instance of the class out of a string convertible to std::string.
    /// If the string doesn't represent a valid MAC address, the constructor throws an exception.
    /// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00"
    template <typename T,
              typename = std::enable_if_t<std::is_convertible<T, std::string>::value && !std::is_array<T>::value>>
    MacAddress(const T& addr) : MacAddress(static_cast<std::string>(addr))
    {}

    /// A constructor that creates an instance of the class out of a char array holding a string.
    /// The string ends at the first null character or at the end of the array, whichever comes first, so an
    /// array without a null terminator is never read past its end.
    /// If the string doesn't represent a valid MAC address, the constructor throws an exception.
    /// @param[in] addr the char array holding the MAC address in format "00:00:00:00:00:00"
    template <size_t N>
    MacAddress(const char (&addr)[N]) : MacAddress(std::string(addr, std::find(addr, addr + N, '\0')))
    {}

    /// A constructor that creates an instance of 6 bytes representing the MAC address
    /// @param[in] firstOctet Represent the first octet in the address
    /// @param[in] secondOctet Represent the second octet in the address
    /// @param[in] thirdOctet Represent the third octet in the address
    /// @param[in] fourthOctet Represent the fourth octet in the address
    /// @param[in] fifthOctet Represent the fifth octet in the address
    /// @param[in] sixthOctet Represent the sixth octet in the address
    MacAddress(uint8_t firstOctet, uint8_t secondOctet, uint8_t thirdOctet, uint8_t fourthOctet, uint8_t fifthOctet,
               uint8_t sixthOctet)
        : m_Address{ firstOctet, secondOctet, thirdOctet, fourthOctet, fifthOctet, sixthOctet }
    {}

    /// A constructor that creates an instance out of the initializer list.
    /// The byte list length should be 6 (as MAC address is 6-byte long).
    /// If the list is invalid, the constructor throws an exception.
    /// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address
    MacAddress(std::initializer_list<uint8_t> octets)
    {
      if (octets.size() != m_Address.size())
      {
        throw std::invalid_argument("Invalid initializer list size, should be 6");
      }
      std::copy(octets.begin(), octets.end(), std::begin(m_Address));
    }

    /// Overload of the comparison operator.
    /// @param[in] other The object to compare with
    /// @return True if addresses are equal, false otherwise
    bool operator==(const MacAddress& other) const
    {
      return m_Address == other.m_Address;
    }

    /// Overload of the not-equal operator
    /// @param[in] other The object to compare with
    /// @return True if addresses are not equal, false otherwise
    bool operator!=(const MacAddress& other) const
    {
      return !operator==(other);
    }

    /// Overload of the assignment operator.
    /// If the list is invalid, the constructor throws an exception.
    /// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address,
    /// the length of the list must be equal to 6
    MacAddress& operator=(std::initializer_list<uint8_t> octets)
    {
      if (octets.size() != sizeof(m_Address))
      {
        throw std::invalid_argument("Invalid initializer list size, should be 6");
      }

      std::copy(octets.begin(), octets.end(), m_Address.begin());
      return *this;
    }

    /// Returns the pointer to raw data
    /// @return The pointer to raw data
    const uint8_t* getRawData() const
    {
      return m_Address.data();
    }

    /// Returns a std::string representation of the address
    /// @return A string representation of the address
    std::string toString() const;

    /// @return A 6-byte integer representing the MAC address
    std::array<uint8_t, 6> toByteArray() const
    {
      return m_Address;
    }

    /// Allocates a byte array of length 6 and copies address value into it. Array deallocation is user
    /// responsibility
    /// @param[in] arr A pointer to where array will be allocated
    /// @throws std::invalid_argument If the buffer pointer is null.
    /// @deprecated Use copyToNewBuffer instead.
    PCPP_DEPRECATED("Use copyToNewBuffer instead.")
    void copyTo(uint8_t** arr) const
    {
      size_t unused = 0;
      copyToNewBuffer(arr, unused);
    }

    /// Gets a pointer to an already allocated byte array and copies the address value to it.
    /// This method assumes array allocated size is at least 6 (the size of a MAC address)
    /// @param[in] arr A pointer to the array which address will be copied to
    /// @remarks This method assumes that the provided array is at least 6 bytes long.
    /// Prefer using the copyTo(uint8_t* buffer, size_t size) method if the array length is not guaranteed to be 6
    /// bytes.
    void copyTo(uint8_t arr[6]) const
    {
      copyTo(arr, 6);
    }

    /// @brief Copies the address value to a user-provided buffer.
    ///
    /// This function supports querying. If the buffer is null and size is zero, it returns the required size.
    ///
    /// @param[in] buffer A pointer to the buffer where the address will be copied
    /// @param[in] size The size of the buffer in bytes
    /// @return The number of bytes copied to the buffer or the required size if the buffer is too small.
    /// @throws std::invalid_argument If the provided buffer is null and size is not zero.
    size_t copyTo(uint8_t* buffer, size_t size) const;

    /// @brief Allocates a new buffer and copies the address value to it.
    /// The user is responsible for deallocating the buffer.
    ///
    /// @param buffer A pointer to a pointer where the new buffer will be allocated
    /// @param size A reference to a size_t variable that will be updated with the size of the allocated buffer
    /// @return True if the buffer was successfully allocated and the address was copied, false otherwise.
    /// @throws std::invalid_argument If the buffer pointer is null.
    bool copyToNewBuffer(uint8_t** buffer, size_t& size) const;

    /// A static value representing a zero value of MAC address, meaning address of value "00:00:00:00:00:00"
    static const MacAddress Zero;
    /// A static value representing a broadcast MAC address, meaning address of value "ff:ff:ff:ff:ff:ff"
    static const MacAddress Broadcast;

  private:
    std::array<uint8_t, 6> m_Address{};
  };

  namespace literals
  {
    inline MacAddress operator""_mac(const char* addrString, size_t size)
    {
      return MacAddress(std::string(addrString, size));
    }
  }  // namespace literals

  inline std::ostream& operator<<(std::ostream& oss, const pcpp::MacAddress& macAddress)
  {
    oss << macAddress.toString();
    return oss;
  }
}  // namespace pcpp

Coverage Report

Created: 2026-11-12 06:50

Line	Count	Source
1		#pragma once
2
3		#include <algorithm>
4		#include <initializer_list>
5		#include <iterator>
6		#include <ostream>
7		#include <cstdint>
8		#include <string>
9		#include <array>
10		#include <memory>
11
12		#include "DeprecationUtils.h"
13
14		/// @file
15
16		/// @namespace pcpp
17		/// @brief The main namespace for the PcapPlusPlus lib
18		namespace pcpp
19		{
20
21		/// @class MacAddress
22		/// Represents L2 MAC addresses. Can be constructed from string or a series of 6 byte octets
23		class MacAddress
24		{
25		public:
26		/// Default constructor for this class.
27		/// Initializes the address as 00:00:00:00:00:00.
28		MacAddress() = default;
29
30		/// A constructor that creates an instance of the class out of a byte array.
31		/// The byte array length should be 6 (as MAC address is 6-byte long), and the remaining bytes are ignored.
32		/// If the byte array is invalid, the constructor throws an exception.
33		/// @param[in] addr A pointer to the byte array containing 6 bytes representing the MAC address
34		/// @remarks This constructor assumes that the provided array is exactly 6 bytes long.
35		/// Prefer using the constructor with size parameter if the array length is not guaranteed to be 6 bytes.
36	1.33M	explicit MacAddress(const uint8_t addr[6]) : MacAddress(addr, 6)
37	1.33M	{}
38
39		/// @brief A constructor that creates an instance of the class out of a byte array of 6 bytes.
40		/// @param[in] addr The address as a byte array in network byte order
41		/// @param[in] size The size of the array in bytes
42		/// @throws std::invalid_argument If the address pointer is null.
43		/// @throws std::out_of_range If the provided size is smaller than 6 bytes.
44		explicit MacAddress(const uint8_t* addr, size_t size);
45
46		/// A constructor that creates an instance of the class out of a std::array.
47		/// The array length should be 6 (as MAC address is 6-byte long).
48		/// @param [in] addr A std::array containing 6 bytes representing the MAC address
49		explicit MacAddress(const std::array<uint8_t, 6>& addr) : m_Address(addr)
50	0	{}
51
52		/// A constructor that creates an instance of the class out of a std::string.
53		/// If the string doesn't represent a valid MAC address, the constructor throws an exception.
54		/// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00"
55		explicit MacAddress(const std::string& addr);
56
57		/// A template constructor that creates an instance of the class out of a string convertible to std::string.
58		/// If the string doesn't represent a valid MAC address, the constructor throws an exception.
59		/// @param[in] addr the string representing the MAC address in format "00:00:00:00:00:00"
60		template <typename T,
61		typename = std::enable_if_t<std::is_convertible<T, std::string>::value && !std::is_array<T>::value>>
62		MacAddress(const T& addr) : MacAddress(static_cast<std::string>(addr))
63		{}
64
65		/// A constructor that creates an instance of the class out of a char array holding a string.
66		/// The string ends at the first null character or at the end of the array, whichever comes first, so an
67		/// array without a null terminator is never read past its end.
68		/// If the string doesn't represent a valid MAC address, the constructor throws an exception.
69		/// @param[in] addr the char array holding the MAC address in format "00:00:00:00:00:00"
70		template <size_t N>
71	20	MacAddress(const char (&addr)[N]) : MacAddress(std::string(addr, std::find(addr, addr + N, '\0')))
72	20	{}
73
74		/// A constructor that creates an instance of 6 bytes representing the MAC address
75		/// @param[in] firstOctet Represent the first octet in the address
76		/// @param[in] secondOctet Represent the second octet in the address
77		/// @param[in] thirdOctet Represent the third octet in the address
78		/// @param[in] fourthOctet Represent the fourth octet in the address
79		/// @param[in] fifthOctet Represent the fifth octet in the address
80		/// @param[in] sixthOctet Represent the sixth octet in the address
81		MacAddress(uint8_t firstOctet, uint8_t secondOctet, uint8_t thirdOctet, uint8_t fourthOctet, uint8_t fifthOctet,
82		uint8_t sixthOctet)
83	20	: m_Address{ firstOctet, secondOctet, thirdOctet, fourthOctet, fifthOctet, sixthOctet }
84	20	{}
85
86		/// A constructor that creates an instance out of the initializer list.
87		/// The byte list length should be 6 (as MAC address is 6-byte long).
88		/// If the list is invalid, the constructor throws an exception.
89		/// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address
90		MacAddress(std::initializer_list<uint8_t> octets)
91	0	{
92	0	if (octets.size() != m_Address.size())
93	0	{
94	0	throw std::invalid_argument("Invalid initializer list size, should be 6");
95	0	}
96	0	std::copy(octets.begin(), octets.end(), std::begin(m_Address));
97	0	}
98
99		/// Overload of the comparison operator.
100		/// @param[in] other The object to compare with
101		/// @return True if addresses are equal, false otherwise
102		bool operator==(const MacAddress& other) const
103	51.8k	{
104	51.8k	return m_Address == other.m_Address;
105	51.8k	}
106
107		/// Overload of the not-equal operator
108		/// @param[in] other The object to compare with
109		/// @return True if addresses are not equal, false otherwise
110		bool operator!=(const MacAddress& other) const
111	51.8k	{
112	51.8k	return !operator==(other);
113	51.8k	}
114
115		/// Overload of the assignment operator.
116		/// If the list is invalid, the constructor throws an exception.
117		/// @param[in] octets An initializer list containing the values of type uint8_t representing the MAC address,
118		/// the length of the list must be equal to 6
119		MacAddress& operator=(std::initializer_list<uint8_t> octets)
120	0	{
121	0	if (octets.size() != sizeof(m_Address))
122	0	{
123	0	throw std::invalid_argument("Invalid initializer list size, should be 6");
124	0	}
125	0
126	0	std::copy(octets.begin(), octets.end(), m_Address.begin());
127	0	return *this;
128	0	}
129
130		/// Returns the pointer to raw data
131		/// @return The pointer to raw data
132		const uint8_t* getRawData() const
133	0	{
134	0	return m_Address.data();
135	0	}
136
137		/// Returns a std::string representation of the address
138		/// @return A string representation of the address
139		std::string toString() const;
140
141		/// @return A 6-byte integer representing the MAC address
142		std::array<uint8_t, 6> toByteArray() const
143	0	{
144	0	return m_Address;
145	0	}
146
147		/// Allocates a byte array of length 6 and copies address value into it. Array deallocation is user
148		/// responsibility
149		/// @param[in] arr A pointer to where array will be allocated
150		/// @throws std::invalid_argument If the buffer pointer is null.
151		/// @deprecated Use copyToNewBuffer instead.
152		PCPP_DEPRECATED("Use copyToNewBuffer instead.")
153		void copyTo(uint8_t** arr) const
154	0	{
155	0	size_t unused = 0;
156	0	copyToNewBuffer(arr, unused);
157	0	}
158
159		/// Gets a pointer to an already allocated byte array and copies the address value to it.
160		/// This method assumes array allocated size is at least 6 (the size of a MAC address)
161		/// @param[in] arr A pointer to the array which address will be copied to
162		/// @remarks This method assumes that the provided array is at least 6 bytes long.
163		/// Prefer using the copyTo(uint8_t* buffer, size_t size) method if the array length is not guaranteed to be 6
164		/// bytes.
165		void copyTo(uint8_t arr[6]) const
166	0	{
167	0	copyTo(arr, 6);
168	0	}
169
170		/// @brief Copies the address value to a user-provided buffer.
171		///
172		/// This function supports querying. If the buffer is null and size is zero, it returns the required size.
173		///
174		/// @param[in] buffer A pointer to the buffer where the address will be copied
175		/// @param[in] size The size of the buffer in bytes
176		/// @return The number of bytes copied to the buffer or the required size if the buffer is too small.
177		/// @throws std::invalid_argument If the provided buffer is null and size is not zero.
178		size_t copyTo(uint8_t* buffer, size_t size) const;
179
180		/// @brief Allocates a new buffer and copies the address value to it.
181		/// The user is responsible for deallocating the buffer.
182		///
183		/// @param buffer A pointer to a pointer where the new buffer will be allocated
184		/// @param size A reference to a size_t variable that will be updated with the size of the allocated buffer
185		/// @return True if the buffer was successfully allocated and the address was copied, false otherwise.
186		/// @throws std::invalid_argument If the buffer pointer is null.
187		bool copyToNewBuffer(uint8_t** buffer, size_t& size) const;
188
189		/// A static value representing a zero value of MAC address, meaning address of value "00:00:00:00:00:00"
190		static const MacAddress Zero;
191		/// A static value representing a broadcast MAC address, meaning address of value "ff:ff:ff:ff:ff:ff"
192		static const MacAddress Broadcast;
193
194		private:
195		std::array<uint8_t, 6> m_Address{};
196		};
197
198		namespace literals
199		{
200		inline MacAddress operator""_mac(const char* addrString, size_t size)
201	0	{
202	0	return MacAddress(std::string(addrString, size));
203	0	}
204		} // namespace literals
205
206		inline std::ostream& operator<<(std::ostream& oss, const pcpp::MacAddress& macAddress)
207	0	{
208	0	oss << macAddress.toString();
209	0	return oss;
210	0	}
211		} // namespace pcpp