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.)

[dtolnay]

@rust-lang/libs-api:
@rfcbot fcp merge

• https://doc.rust-lang.org/nightly/std/net/struct.Ipv4Addr.html#associatedconstant.BITS
• https://doc.rust-lang.org/nightly/std/net/struct.Ipv4Addr.html#method.to_bits
• https://doc.rust-lang.org/nightly/std/net/struct.Ipv4Addr.html#method.from_bits
• https://doc.rust-lang.org/nightly/std/net/struct.Ipv6Addr.html#associatedconstant.BITS
• https://doc.rust-lang.org/nightly/std/net/struct.Ipv6Addr.html#method.to_bits
• https://doc.rust-lang.org/nightly/std/net/struct.Ipv6Addr.html#method.from_bits

These APIs were our own counterproposal to having leading_/trailing_zeros methods on the IP address types. See rust-lang/libs-team#235 (comment).

[rfcbot]

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[pronebird]

Can someone please clarify, impl From<u128> for Ipv6Addr is not marked as unstable although internally it calls into Ipv6Addr::from_bits which is marked unstable. Using the From implementation just works with stable compiler but using from_bits directly prints error[E0658]: use of unstable library feature 'ip_bits'. Is it just an oversight?

[GrigorenkoPV]

Can someone please clarify, impl From<u128> for Ipv6Addr is not marked as unstable although internally it calls into Ipv6Addr::from_bits which is marked unstable. Using the From implementation just works with stable compiler but using from_bits directly prints error[E0658]: use of unstable library feature 'ip_bits'. Is it just an oversight?

impl From<u128> for Ipv6Addr has been around since 1.26.0 and used to be implemented without using from_bits. But with the introduction of unstable from_bits the internal implementation got changed (both the compiler and the standard library do not hesitate do use unstable features internally). This affects neither the stability of the existing impl, nor its behavior, which is why this change is okay.

https://github.com/rust-lang/rust/pull/113746/files#diff-d0718870fd66d5eb2a63284de49bd959d2648c7d7fb90dfc26d9e264e700f5bdL1926-L1947

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[Rawk]

For example, IpvNAddr::BITS - ip.to_bits().trailing_zeros() can be used to determine the network prefix length of a given address.

Note that this is only true if address is a netmask. A valid network prefix can (and often does) include trailing zeroes.