/*
Package netx includes extensions to the stdlib [net] module.

It provides many functions that should be significantly more helpful for those working with networking a significant amount.

Some functions may be "missing". This is by design; the corresponding functionality should be available in stdlib.

For example, while there is an [IsAddr4Compat] function, there is no "IsAddr4Mapped". This is because this can be accomplished via the following:

	var ip netip.Addr

	// ...

	ip.Is4In6()

	// ...

If you are looking for specific functionality in this library but are unable to find it,
this is because the functionality already exists in (in the author's opinion) a reasonably convenient
methodology via one of the following:

  - [net]
  - [net/netip]
  - [go4.org/netipx]

# IP Family/Versioning

There are different ways of expressing an IP address/network's version (e.g. IPv4, IPv6).

Some libraries expect an integer representation (e.g. 4, 6).

Some libraries expect a system/OS-constant instead (e.g. unix.AF_INET, unix.AF_INET6, windows.AF_INET, windows.AF_INET6).

The following functions are offered to assist with this translation:

  - [FamilyToVer]
  - [GetAddrFamily]
  - [GetIpFamily]
  - [IpVerStr]
  - [VerToFamily]

The following constants are offered to make cross-platform development more fluid (these are set according to the build target):

  - [AFUnspec]
  - [AFInet]
  - [AFInet6]

# IP Sets

This library provides convenience functions for getting a [netipx.IPSet] in single-entry functions:

  - [IPSetCombined]
  - [IPSetFrom]
  - [IPSetFromNative]
  - [MustIPSetCombined]
  - [MustIPSetFrom]
  - [MustIPSetFromNative]

# Canonical String Representation

Go's stdlib [net] and [net/netip] don't always properly display or handle the proper string formatting per RFC conventions.

The following functions assist with this:

  - [AddrRfc]
  - [IpRfc]
  - [IpRfcStr]
  - [IpStripRfcStr]
  - [IsBracketedIp6]
  - [IsPrefixNet]

# Netmask and CIDR Conversions

An IPv4 network size can be represented by both a netmask (e.g. "255.255.255.0") or a CIDR prefix length (e.g. "/24"),
as well as a numeric bitmask form (which is different from the prefix length).

This module offers functions that assist with easy translation between these formats:

  - [Cidr4ToIPMask]
  - [Cidr4ToMask]
  - [Cidr4ToStr]
  - [IPMask4ToCidr]
  - [IPMask4ToMask]
  - [IPMask4ToStr]
  - [Mask4StrToCidr]
  - [Mask4StrToIPMask]
  - [Mask4StrToMask]
  - [Mask4ToCidr]
  - [Mask4ToIPMask]
  - [Mask4ToStr]

# IPv4 Addresses as IPv6

There are two canonical ways of representing an IPv4 address as an IPv6 address, per RFC 4291 ([section 2.5.5]):

  - "IPv4-Compatible IPv6 Addresses" (RFC [4291 § 2.5.5.1]) — ::/96
  - "IPv4-Mapped IPv6 Addresses" (RFC [4291 § 2.5.5.2]) — ::ffff:0:0/96

The former (::/96) is considered deprecated, and there is only parsing support for it in Go stdlib.

There are a number of functions tailored for use with both of these formats in this module:

  - [Addr4in6Compat]
  - [Addr4in6Mapped]
  - [IP4MapPfx4to6]
  - [IP4MapPfx6to4]
  - [IsAddr4Compat]
  - [Pfx4in6Compat]
  - [Pfx4in6Mapped]
  - [UnmapAddr]
  - [UnmapPfx]

For more technical/detailed information, refer to the ./NOTES.adoc file in this module's
git repository, specifically the "IPv4 Addresses as IPv6" section.

# Miscellaneous Functions

Other functions that may be of use:

  - [IsPublic] — Note that this does not guarantee that it is a *valid* public IP address (especially in the case of IPv6),
    simply that it isn't in a non-WAN-routable prefix reserved by current standards.
  - [HasSubnet]

[section 2.5.5]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5
[4291 § 2.5.5.1]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.1
[4291 § 2.5.5.2]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2
*/
package netx