Audit integer types in the standard library

[nikomatsakis]

Below is a list of modules that contain text matching the regular expression \bu?int\b and which are intended to be stable. In some cases, these terms only appear in comments (which should still be fixed). In some cases, I have simply put .. after a directory to indicate all files within that directory. Please sign up for modules in comments below and I will endeavor to keep this list up to date with who is working on what (if you have sufficient privileges, feel free to edit the comment directly).

Guidelines to follow

These are the guidelines that we intend to follow in the standard library. These guidelines are not intended as universal guidelines to be used outside the standard library (though of course one might choose to do so).

1. Use unsigned values if the value should always be greater than or equal to zero, and signed values otherwise.
2. For indices, pointers, or other values which are tied to a data structure whose size is proportional to the size of memory, use usize or isize.
3. For cases where the acceptable domain of a value perfectly fits a fixed number of bits, use the appropriate fixed-size type. For example, a method like write_u16 would take a u16 argument.
4. Otherwise, use i32/u32 if the value has a narrow range and i64/u64 otherwise.

Examples:

• Vector indices and hashmap lengths use usize.
• The size of a file would be u64, as the maximum size of a file is not tied to addressable memory.
• Something like write_u16 takes a u16 (shocker, I know!)
• The radix of an integer would use u32.
  • You might expect u8, since a radix higher than 256 is not useful, but the domain of useful radices is actually much smaller than u8, so using u8 isn't providing a meaningful guarantee, and will simply increase friction.

Module listing

• libcollections/.. -- Gankro
• libcore/mem.rs -- @pnkfelix Audit core mem, nonzero, and cell modules for proper integer usage #22401
• libcore/ops.rs -- @nikomatsakis Audit the option and ptr types for proper integer usage #22294
• libcore/result.rs -- @nikomatsakis Audit the option and ptr types for proper integer usage #22294
• libcore/finally.rs -- @nikomatsakis Audit the option and ptr types for proper integer usage #22294
• libcore/marker.rs -- @nikomatsakis (no ints/uints)
• libcore/borrow.rs -- @pnkfelix Audit core borrow, cmp, default, and intrinsics modules for proper integer usage #22485
• libcore/fmt/.. @nick29581 int audit core::{hash, fmt}, std::sync #22700
• libcore/char.rs -- petrochenkov Audit integer types in libunicode, libcore/(char, str) and libstd/ascii #22339
• libcore/option.rs -- @nikomatsakis Audit the option and ptr types for proper integer usage #22294
• libcore/default.rs -- @pnkfelix Audit core borrow, cmp, default, and intrinsics modules for proper integer usage #22485
• libcore/ptr.rs -- @nikomatsakis Audit the option and ptr types for proper integer usage #22294
• libcore/clone.rs @brson ok. no use of ints
• libcore/cmp.rs -- @pnkfelix Audit core borrow, cmp, default, and intrinsics modules for proper integer usage #22485
• libcore/str/.. -- petrochenkov Audit integer types in libunicode, libcore/(char, str) and libstd/ascii #22339
• libcore/nonzero.rs -- @pnkfelix Audit core mem, nonzero, and cell modules for proper integer usage #22401
• libcore/cell.rs -- @pnkfelix Audit core mem, nonzero, and cell modules for proper integer usage #22401
• libcore/intrinsics.rs -- @pnkfelix Audit core borrow, cmp, default, and intrinsics modules for proper integer usage #22485
• libcore/num/.. @brson core: Audit num module for int/uint #22600 pow is covered by Make Int::pow() take exp as u32 instead usize #22087
• libcore/lib.rs @GuillaumeGomez
• libcore/atomic.rs @brson. ok. everything is ptr size. bool is implemented as usize, but intentionally.
• libcore/hash/.. @nick29581 int audit core::{hash, fmt}, std::sync #22700
• libcore/panicking.rs @GuillaumeGomez Replace uint by usize in libcore/panicking.rs #22507
• libcore/macros.rs fixed by Change column!() / line!() return type from usize to u32. #19284 #21769 (@nick29581 (not my patch though))
• libcore/raw.rs @brson. ok. one usize representing slice length
• libcore/slice.rs @brson. ok. all usizes for indexes or ranges
• libstd/sys/common/.. - not public
• libstd/sys/windows/.. - not public
• libstd/sys/unix/.. - not public
• libstd/collections/mod.rs -- Gankro
• libstd/ascii.rs -- petrochenkov Audit integer types in libunicode, libcore/(char, str) and libstd/ascii #22339
• libstd/thread.rs -- @GuillaumeGomez
• libstd/os.rs - will be #[deprecated]
• libstd/num/.. @gankro
• libstd/lib.rs -- @GuillaumeGomez
• libstd/thread_local/.. -- @vojtechkral
• libstd/failure.rs -- file no longer exists
• libstd/io/buffered.rs - will be #[deprecated]
• libstd/sync/.. @nick29581 int audit core::{hash, fmt}, std::sync #22700
• libunicode/.. Audit integer types in libunicode, libcore/(char, str) and libstd/ascii #22339

[nikomatsakis]

Nominating for the 1.0 beta milestone.

[Gankra]

I'll finish up collections. Looks like I just missed some docs stuff.

[pnkfelix]

1.0 beta, P-backcompat-lib.

[nikomatsakis]

cc @nick29581 @pnkfelix @aturon @alexcrichton @pcwalton @steveklabnik @wycats don't forget to sign up for somethin' ;)

[petrochenkov]

I'll take libunicode, char, str and ascii
EDIT: they are coupled with fmt and num, so I'm fixing some bits there too

[pnkfelix]

@nikomatsakis some of the uses of int/uint are just arising from what seem to be dummy types in examples in the documentation. For example this in cell.rs where the edges in a hypothetical graph structure are (uint, uint) (and edge.0/edge.1 are not being used for array indexing).

I sympathize with not wanting to jump into fully generic code in these examples.

But for consistency in the docs overall, what do we want our go-to type to be in these cases: u32, i32, or ... ? (I'm guessing i32 for consistency with integer fallback.

[Gankra]

Yes, my general rule when updating the docs is to try to have integer-fallback trigger and have i32 inferred, with explicit i32 when necessary.

So e.g. I use a lot of let vec: Vec<_> = [1, 2, 3, 4].iter().cloned().collect();

[nikomatsakis]

@pnkfelix as @gankro said, I've mostly used u32/i32 as my go to type for docs, if it seems that "generic integer" is all that's requested.

EDIT: Or, I thought I did. I guess I left some as usize in #22294 ...

[vojtechkral]

libcore/macros.rs → cc #19284 , which is tightly related to how types are used in codemap.rs: the Pos trait uses usize, BytePos uses u32 and CharPos uses usize. Why are these types chosen the way they are? Could they perhaps be changed so that #19284 is easier to fix?

EDIT: Anyway, once #19284 is fixed, libcore/macros.rs will have been taken care of, there are no other uints/ints in that file.

[vojtechkral]

May I take the remaining libstd/thread_local/.. ? EDIT: done...

[nikomatsakis]

Seems like it's time for someone to just finish all that remains in one fell swoop.

[GuillaumeGomez]

Everything has been taken already, no ?

[vojtechkral]

@GuillaumeGomez Looks like it.

[nikomatsakis]

@GuillaumeGomez yes I suppose you are correct, but there are several with no listed PR, all assigned to you or @vojtechkral, can you guys attest that those are in the pipeline now? I can't quite tell from all the various citations appearing everywhere.

[GuillaumeGomez]

All attributed to me have been merged.

[vojtechkral]

Mine too.

[nikomatsakis]

Great, thanks to you both!