21 Internet protocol [internet]

21.5 Class ip::address_v4 [internet.address.v4]

The class address_v4 is a representation of an IPv4 address.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {
namespace ip {

  class address_v4
  {
  public:
    // [internet.address.v4.bytes], types:
    using uint_type = uint_least32_t;
    struct bytes_type;

    // [internet.address.v4.cons], constructors:
    constexpr address_v4() noexcept;
    constexpr address_v4(const address_v4& a) noexcept;
    constexpr address_v4(const bytes_type& bytes);
    explicit constexpr address_v4(uint_type val);

    // assignment:
    address_v4& operator=(const address_v4& a) noexcept;

    // [internet.address.v4.members], members:
    constexpr bool is_unspecified() const noexcept;
    constexpr bool is_loopback() const noexcept;
    constexpr bool is_multicast() const noexcept;
    constexpr bytes_type to_bytes() const noexcept;
    constexpr uint_type to_uint() const noexcept;
    template<class Allocator = allocator<char>>
      basic_string<char, char_traits<char>, Allocator>
        to_string(const Allocator& a = Allocator()) const;

    // [internet.address.v4.static], static members:
    static constexpr address_v4 any() noexcept;
    static constexpr address_v4 loopback() noexcept;
    static constexpr address_v4 broadcast() noexcept;
  };

  // [internet.address.v4.comparisons], address_v4 comparisons:
  constexpr bool operator==(const address_v4& a, const address_v4& b) noexcept;
  constexpr bool operator!=(const address_v4& a, const address_v4& b) noexcept;
  constexpr bool operator< (const address_v4& a, const address_v4& b) noexcept;
  constexpr bool operator> (const address_v4& a, const address_v4& b) noexcept;
  constexpr bool operator<=(const address_v4& a, const address_v4& b) noexcept;
  constexpr bool operator>=(const address_v4& a, const address_v4& b) noexcept;

  // [internet.address.v4.creation], address_v4 creation:
  constexpr address_v4 make_address_v4(const address_v4::bytes_type& bytes);
  constexpr address_v4 make_address_v4(address_v4::uint_type val);
  constexpr address_v4 make_address_v4(v4_mapped_t, const address_v6& a);
  address_v4 make_address_v4(const char* str);
  address_v4 make_address_v4(const char* str, error_code& ec) noexcept;
  address_v4 make_address_v4(const string& str);
  address_v4 make_address_v4(const string& str, error_code& ec) noexcept;
  address_v4 make_address_v4(string_view str);
  address_v4 make_address_v4(string_view str, error_code& ec) noexcept;

  // [internet.address.v4.io], address_v4 I/O:
  template<class CharT, class Traits>
    basic_ostream<CharT, Traits>& operator<<(
      basic_ostream<CharT, Traits>& os, const address_v4& addr);

} // namespace ip
} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

address_v4 satisfies the requirements for Destructible (C++ 2014 [destructible]), CopyConstructible (C++ 2014 [copyconstructible]), and CopyAssignable (C++ 2014 [copyassignable]).

21.5.1 Struct ip::address_v4::bytes_type [internet.address.v4.bytes]

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {
namespace ip {

  struct address_v4::bytes_type : array<unsigned char, 4>
  {
    template<class... T> explicit constexpr bytes_type(T... t)
      : array<unsigned char, 4>{{static_cast<unsigned char>(t)...}} {}
  };

} // namespace ip
} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

The ip::address_v4::bytes_type type is a standard-layout struct that provides a byte-level representation of an IPv4 address in network byte order.

21.5.2 ip::address_v4 constructors [internet.address.v4.cons]

constexpr address_v4() noexcept;

Postconditions: to_bytes() yields {0, 0, 0, 0} and to_uint() == 0.

constexpr address_v4(const bytes_type& bytes);

Remarks: out_of_range if any element of bytes is not in the range [0, 0xFF]. [ Note: For implementations where numeric_limits<unsigned char>::max() == 0xFF, no out-of-range detection is needed.  — end note ]

Postconditions: to_bytes() == bytes and to_uint() == (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3].

explicit constexpr address_v4(address_v4::uint_type val);

Remarks: out_of_range if val is not in the range [0, 0xFFFFFFFF]. [ Note: For implementations where numeric_limits<address_v4::uint_type>::max() == 0xFFFFFFFF, no out-of-range detection is needed.  — end note ]

Postconditions: to_uint() == val and to_bytes() is:

21.5.3 ip::address_v4 members [internet.address.v4.members]

constexpr bool is_unspecified() const noexcept;

Returns: to_uint() == 0.

constexpr bool is_loopback() const noexcept;

Returns: (to_uint() & 0xFF000000) == 0x7F000000.

constexpr bool is_multicast() const noexcept;

Returns: (to_uint() & 0xF0000000) == 0xE0000000.

constexpr bytes_type to_bytes() const noexcept;

Returns: A representation of the address in network byte order ([defs.net.byte.order]).

constexpr address_v4::uint_type to_uint() const noexcept;

Returns: A representation of the address in host byte order ([defs.host.byte.order]).

template<class Allocator = allocator<char>> basic_string<char, char_traits<char>, Allocator> to_string(const Allocator& a = Allocator()) const;

Returns: If successful, the textual representation of the address, determined as if by POSIX inet_ntop when invoked with address family AF_INET. Otherwise basic_string<char, char_traits<char>, Allocator>(a).

21.5.4 ip::address_v4 static members [internet.address.v4.static]

static constexpr address_v4 any() noexcept;

Returns: address_v4().

static constexpr address_v4 loopback() noexcept;

Returns: address_v4(0x7F000001).

static constexpr address_v4 broadcast() noexcept;

Returns: address_v4(0xFFFFFFFF).

21.5.5 ip::address_v4 comparisons [internet.address.v4.comparisons]

constexpr bool operator==(const address_v4& a, const address_v4& b) noexcept;

Returns: a.to_uint() == b.to_uint().

constexpr bool operator!=(const address_v4& a, const address_v4& b) noexcept;

Returns: !(a == b).

constexpr bool operator< (const address_v4& a, const address_v4& b) noexcept;

Returns: a.to_uint() < b.to_uint().

constexpr bool operator> (const address_v4& a, const address_v4& b) noexcept;

Returns: b < a.

constexpr bool operator<=(const address_v4& a, const address_v4& b) noexcept;

Returns: !(b < a).

constexpr bool operator>=(const address_v4& a, const address_v4& b) noexcept;

Returns: !(a < b).

21.5.6 ip::address_v4 creation [internet.address.v4.creation]

constexpr address_v4 make_address_v4(const address_v4::bytes_type& bytes);

Returns: address_v4(bytes).

constexpr address_v4 make_address_v4(address_v4::uint_type val);

Returns: address_v4(val).

constexpr address_v4 make_address_v4(v4_mapped_t, const address_v6& a);

Returns: An address_v4 object corresponding to the IPv4-mapped IPv6 address, as if computed by the following method:

address_v6::bytes_type v6b = a.to_bytes();
address_v4::bytes_type v4b(v6b[12], v6b[13], v6b[14], v6b[15]);
return address_v4(v4b);

Remarks: bad_address_cast if a.is_v4_mapped() is false.

address_v4 make_address_v4(const char* str); address_v4 make_address_v4(const char* str, error_code& ec) noexcept; address_v4 make_address_v4(const string& str); address_v4 make_address_v4(const string& str, error_code& ec) noexcept; address_v4 make_address_v4(string_view str); address_v4 make_address_v4(string_view str, error_code& ec) noexcept;

Effects: Converts a textual representation of an address into a corresponding address_v4 value, as if by POSIX inet_pton when invoked with address family AF_INET.

Returns: If successful, an address_v4 value corresponding to the string str. Otherwise address_v4().

Error conditions:

  • errc::invalid_argument — if str is not a valid textual representation of an IPv4 address.

21.5.7 ip::address_v4 I/O [internet.address.v4.io]

template<class CharT, class Traits> basic_ostream<CharT, Traits>& operator<<( basic_ostream<CharT, Traits>& os, const address_v4& addr);

Returns: os << addr.to_string().c_str().