The integer conversion operations were inlinable, but aren't getting
inlined in debug builds, which results in unreasonably poor
performance. Mark them as transparent so we don't end up with
unspecialized generic code in the hot path.
Fixes https://github.com/swiftlang/swift/issues/78501
* [stdlib] Remove docs from default implementations
Customized docs were not removed:
public static var isSigned: Bool
public static var max: Self
public static var min: Self
public var description: String
public var magnitude: Self
public init<T: BinaryInteger>(_ source: T)
public func distance(to other: Self) -> Int
public func advanced(by n: Int) -> Self
* [stdlib] Remove unused docs for "unsafe" methods
* [stdlib] Remove inherited "ReportingOverflow" docs
* [stdlib] Remove inherited docs for operators
Customized docs were not removed.
(`+`, `-`, `*`, `+=`, `-=`, `*=`)
Non-inherited docs were not removed.
(`&+`, `&-`, `&+=`, `&-=`, `&*=`)
* [stdlib] Reattach doc comments to their APIs
Use `rstrip()` to remove the trailing newline.
<https://docs.python.org/3/library/stdtypes.html#str.rstrip>
* [stdlib] Remove inherited docs from integer types
* [stdlib] Remove FIXME(ABI) comments
* [stdlib] Remove unused docs for operators
* [stdlib] Update example code for `-=` and `*=`
* [stdlib] Update internal gyb comments
* [stdlib] Move docs to BinaryInteger overrides
* [stdlib] Remove unused gyb code
* [stdlib] Fix `&-` and `&*` examples
These are provided for FixedWidthInteger & UnsignedInteger (the base implementation, following Knuth's Algorithm D) and SignedInteger (converting to magnitudes and calling the former). Previously no default implementations were available, requiring every type to implement these operations.
These defaults will not be optimal for large fixed-width integers, so types vending Int512 or similar integers should still provide their own implementations, but they are unconditionally available as a fallback, which simplifies the process of writing such types, and work well enough as a fallback for modest fixed-width integer types like Int64 or 32b or smaller platforms or Int128 on 64b platforms.
Additionally rework the concrete implementations to guarantee that we always trap when the quotient is not representable, and to improve performance for 64b integers on arm64_32, and added some new test coverage for these operations.
This isn't a "complete" port of the standard library for embedded Swift, but
something that should serve as a starting point for further iterations on the
stdlib.
- General CMake logic for building a library as ".swiftmodule only" (ONLY_SWIFTMODULE).
- CMake logic in stdlib/public/core/CMakeLists.txt to start building the embedded stdlib for a handful of hardcoded target triples.
- Lots of annotations throughout the standard library to make types, functions, protocols unavailable in embedded Swift (@_unavailableInEmbedded).
- Mainly this is about stdlib functionality that relies on existentials, type erasure, metatypes, reflection, string interpolations.
- We rely on function body removal of unavailable functions to eliminate the actual problematic SIL code (existentials).
- Many .swift files are not included in the compilation of embedded stdlib at all, to simplify the scope of the annotations.
- EmbeddedStubs.swift is used to stub out (as unavailable and fatalError'd) the missing functionality.
These were defined for both FixedWidthInteger and FixedWidthInteger & SignedInteger for source compatibility with Swift 3; the latter set probably should have been removed when we stabilized the ABI, but were not. We can't easily remove them entirely (because we need them for ABI stability now), but we can mark them unavailable so that the typechecker doesn't have to consider them..
Previously we said that a type conforming to SignedNumeric allows positive and negative values, but that's nonsense. A type conforms to signed numeric if it has a negate() operation; it doesn't even have to have a notion of positive or negative values (for examples, see complex numbers, quaternions, integers mod n, etc).
There's nothing useful to say about the type of .zero -- it's
constrained by the protocol to Self, so you don't have any choice what
it is when conforming to AdditiveArithmetic.
Fixes <rdar://problem/72592923> (SR-13983).
Allow the closed-range version of `FixedWidthInteger.random(in:using:)` to work for types larger than 64 bits when the entire valid range (`.min ... .max`) is passed in.
Also, closed ranges are never empty, so the unnecessary `!isEmpty` precondition has been removed.
* Provide a default implementation of multipliedFullWidth
Previously, [U]Int64 fatalErrored on 32b platforms, which is obviously undesirable. This PR provides a default implementation on FixedWidthInteger, which is not ideally efficient for all types, but is correct, and gives the optimizer all the information that it needs to generate good code in the important case of Int64 arithmetic on 32b platforms. There's still some minor room for improvement, but we'll call that an optimizer bug now.
* Clarify comments somewhat, remove `merge` nested function
I was only using `merge` in one place, so making it a function seems unnecessary. Also got rid of some trucatingIfNeeded inits where the compiler is able to reason that no checks are needed anyway.
* Add some basic test coverage specifically for multipliedFullWidth
* Fix typo, further clarify bounds comments.
* Make new defaulted implementation @_aEIC so we don't need availability.
* [docs] Update `trailingZeroBitCount` documentation
Document the required behavior for `trailingZeroBitCount` when the value is zero. Namely, in that scenario, `trailingZeroBitCount` should be equal to `bitWidth`.
* [docs] Address reviewer comments on `trailingZeroBitCount` docs
* Revise the Unicode scalar/Character properties
* Minor revisions to `compactMapValues` docs.
* Add documentation for AdditiveArithmetic, revise Numeric
* Apply minor style updates to count(where:).
* Revise string interpolation docs.
- Convert table of interpolation examples to a list of examples. Tables
aren't supported by Swift markup, so this wouldn't render properly in
Xcode or on the web.
- Add a description of what a user must implement in a custom
string interpolation type to get the behavior they want.
* Revise isMultiple(of:) docs.
- In particular, add emphasis to mathematical symbols and equations to
match how we document such things elsewhere.
- I'm using asterisks for single symbols, and underscores for equations
because it's easier to read in-source when you don't have to escape
multiplication within emphasis.
* Add some abstracts to the SIMD vector types.
- Adds a dictionary of spelled out numbers. Only numbers < 10
should be spelled out according to editorial.
- Adds abstracts to some of the basic members.
- Includes parameter descriptions for the xyzw properties and inits,
but not for the unlabeled initializers. Combined with the protocol
extension method abstracts, this should complete coverage of the concrete
types.
Within the (single) implementation of abs(_:), dynamically check whether
the numeric type and its `Magnitude` are of the same type and, if so,
return the result of `magnitude`. This ensures that we do the right thing
with respect to (e.g.) floating point values like -0.0, without resorting
to overloading of abs(_:).
The standard library has two versions of the `abs(_:)` function:
```
func abs<T : SignedNumeric>(_ x: T) -> T where T.Magnitude == T
func abs<T : SignedNumeric & Comparable>(_ x: T) -> T
```
The first is more specialized than the second because `T.Magnitude` is
known to conform to `Comparable`. Indeed, it’s a more specialized
implementation that returns `magnitude`.
However, this overload behaves oddly: in the expression `abs(-8)`, the type
checker will pick the first overload because it is more specialized. That’s
a general guiding principle for overloading: pick the most specialized
overload that works.
However, to select that overload, it needs to pick a type for the literal
“8” for which that overload works, and it chooses `Double`. The “obvious”
answer, `Int`, doesn’t work because `Int.Magnitude == UInt`.
There is a conflict between the two rules, here: we prefer more-specialized
overloads (but we’ll fall back to less-specialized if those don’t work) and we prefer to use `Int` for integer literals (but we’ll fall back to `Double` if it doesn’t work). We have a few options from a type-checker
perspective:
1. Consider the more-specialized-function rule to be more important
2. Consider the integer-literals-prefer-`Int` rule to be more important
3. Call the result ambiguous and make the user annotate it
The type checker currently does #1, although at some point in the past it
did #2. Moving forward, #1 is a better choice because it prunes the number
of overloads that need to be considered: if the more-specialized overload
succeeds its type-check, the others need not be considered. It’s also
easier to reason about than the literal-scoring approach, because there can
be a direct definition for “more specialized than” that can be reasoned
about.
I think we should dodge the issue by removing the more-specialized version
of `abs(_:)`. Its use of `magnitude` seems unlikely to provide a
significant performance benefit, and the presence of overloading either
forces us to consider both overloads always (which is bad for type checker
performance) or accept the regression that `abs(-8)` is `Double`. Better
to eliminate the overloading and, if needed in the future, find a better
way to introduce the more-specialized implementation without it being a
separate signature.
Fixes rdar://problem/42345366.
