[SR-7648] Add dedicated bitwise initializers to BinaryInteger

[lorentey]

Previous ID	SR-7648
Radar	None
Original Reporter	@lorentey
Type	New Feature

Additional Detail from JIRA

Votes	0
Component/s	Standard Library
Labels	New Feature
Assignee	None
Priority	Medium

md5: ee8ac7bc3cc99994b8ee663af146b48e

Issue Description:

To enable custom implementations of FixedWidthInteger, and to speed up and simplify generic code that needs to initialize integer types (especially those that are wider than UInt64) from arbitrary data, we should add dedicated initializers to BinaryInteger that take a specific word or a sequence of words in two's complement representation:

protocol BinaryInteger {
  init(truncatingWordIfNeeded word: UInt)
  init<W: Sequence>(truncatingWordsIfNeeded words: W) where W.Element == UInt
}

The new initializers should be public.

The single-word initializer is only there to provide a potential speed boost for the most common case. For FixedWidthInteger (and possibly also BinaryInteger itself), it seems possible to provide a default implementation for the sequence-based initializer using the single-word initializer and shifts, but it seems better to leave init(truncatingWordsIfNeeded: ) as a required initializer. (The default implementation would be quadratic for most big integer types.)

Note that for FixedWidthInteger, we currently require the underscored initializer FixedWidthInteger.init(_truncatingBits bits: UInt), without providing a default implementation. This makes it impossible to implement FixedWidthInteger using just the public API.

[lorentey]

This will need a swift-evolution pitch & proposal.

[lorentey]

A words-based initializer could also be useful for an improved version of the ExpressibleByIntegerLiteral protocol that would support integer literals of truly arbitrary widths.

[lorentey]

See #16413 (comment) for an example of a generic function where these initializers would come useful.

[xwu]

What is the difference between init(truncatingIfNeeded: UInt) and init(truncatingWordIfNeeded: UInt)?

[lorentey]

@xwu: They behave the same, but the former is a specialization of a generic requirement that can be implemented with the latter. (My suggested names above aren't great; perhaps init(word: UInt) and init<S>(words: S) would work just as well.)

(FixedWidthInteger.init<T>(truncatingIfNeeded: T) is currently implemented using .init(_truncatingBits: ), which is the single-word initializer.)