Tracking Issue for `IpvNAddr::{BITS, to_bits, from_bits}` (`ip_bits`)

[clarfonthey]

Feature gate: #![feature(ip_bits)]

This is a tracking issue for IpvNAddr::{BITS, to_bits, from_bits}.

This API exists mostly so that users can be explicit about various bit operations which are useful for computing IP networks (see ACP linked below). For example, IpvNAddr::BITS - ip.to_bits().trailing_zeros() can be used to determine the network prefix length of a given address.

Additionally, since const traits are still a long ways out, this provides a const version of the conversions to/from integers that people can use in the meantime.

Public API

impl Ipv4Addr {
    pub const BITS: u32 = 32;
    pub const fn from_bits(bits: u32) -> Ipv4Addr;
    pub const fn to_bits(self) -> u32;
}

impl Ipv6Addr {
    pub const BITS: u32 = 128;
    pub const fn from_bits(bits: u128) -> Ipv4Addr;
    pub const fn to_bits(self) -> u128;
}

Steps / History

• API change proposal (ACP)¹: ACP: Extended logic for IP networks libs-team#235
• Implementation: Add BITS, from_bits, to_bits to IP addresses #113746
• Improve docs regarding endianness: Elaborate on ip_addr bit conversion endianness #118505
• Final comment period (FCP)²
• Stabilization PR: Stabilise IpvNAddr::{BITS, to_bits, from_bits} (ip_bits) #125551

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/api-change-proposals.html ↩

2. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[thomcc]

It would be nice to improve the docs here to be more specific about endianness, since we got questions about it in the PR after it landed.

[yungcomputerchair]

Is this ready for FCP now that the documentation issue has been addressed? Would love to see this stabilized.

[GrigorenkoPV]

The docs say this:

In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the libs team reviewers directly to request assistance.

So I hope it is okay if I ping @cuviper. (Terribly sorry if it is not.)

[cuviper]

It seems ready to me. Maybe @yungcomputerchair or @GrigorenkoPV can try writing a stabilization report?

(I don't think I can start the actual FCP since I'm not part of the libs-api team.)