Add documentation for numeric value comparison within specified accuracy #165 #314

wangxingyu5529 · 2024-03-24T14:05:11Z

Add documentation about how to compare two numeric values within specified accuracy.

Motivation:

Issue #165. swift-testing doesn't have an analog of XCAssertEquals of specified accuracy. There is no such function in the standard library. It's unclear to users how they can compare two numeric values.

Resolves #165.

Modifications:

Added a comment in the #expect macro: should use isApproximatelyEqual in the swift-numerics.

Result:

Clearer to users what numeric value comparison is.

Checklist:

Code and documentation should follow the style of the Style Guide.
If public symbols are renamed or modified, DocC references should be updated.

grynspan

This is not the appropriate location for this documentation. It should be included in the migration document.

grynspan · 2024-03-26T16:22:26Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -355,6 +355,11 @@ their equivalents in the testing library:
 | `try XCTUnwrap(x)` | `try #require(x)` |
 | `XCTFail("…")` | `Issue.record("…")` |

+- Note: When comparing two numeric values within a specified accuracy, i.e. the


@medreisbach @chuckdude Can you advise?

I think the modifications suggested by @heckj look great.

heckj

suggestions for slightly tighter and direct phrasing

heckj · 2024-04-05T20:08:37Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -355,6 +355,11 @@ their equivalents in the testing library:
 | `try XCTUnwrap(x)` | `try #require(x)` |
 | `XCTFail("…")` | `Issue.record("…")` |

+- Note: When comparing two numeric values within a specified accuracy, i.e. the


Suggested change

- Note: When comparing two numeric values within a specified accuracy, i.e. the

- Note: To check that two numeric values are equivalent within a specified accuracy, as in the

heckj · 2024-04-05T20:09:11Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

@@ -355,6 +355,11 @@ their equivalents in the testing library:
 | `try XCTUnwrap(x)` | `try #require(x)` |
 | `XCTFail("…")` | `Issue.record("…")` |

+- Note: When comparing two numeric values within a specified accuracy, i.e. the
+analogue of [`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal)
+, please import [the swift-numerics package](https://github.com/apple/swift-numerics)


Suggested change

, please import [the swift-numerics package](https://github.com/apple/swift-numerics)

, import [the swift-numerics package](https://github.com/apple/swift-numerics)

I'd also reduce the link to just "swift-numerics" but that's not a hard rule, just my preference.

heckj · 2024-04-05T20:09:36Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

+- Note: When comparing two numeric values within a specified accuracy, i.e. the
+analogue of [`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal)
+, please import [the swift-numerics package](https://github.com/apple/swift-numerics)
+and use the ``isApproximatelyEqual()`` function.


Suggested change

and use the ``isApproximatelyEqual()`` function.

to use the ``isApproximatelyEqual()`` function.

This would sound odd. Simplified: "to do x, do y to do z".

Flip the whole ordering, which would make it more direct, something akin to:

"Import swift-numerics and use isApproximateEqual to compare two numeric values to within an accuracy bound you specify. Use this technique as a replacement for XCTAssertEqual(::accuracy)."

or something akin

That would be confusing since it would introduce instructions to import swift-numerics without a reader knowing why that was important. State the problem before the solution.

Yeah, you’re right. maybe lead with “swift-testing doesn’t include an exact duplicate of XCTAssertEqual(::accuracy)” and then jump into the direct advice.

grynspan · 2024-04-06T20:52:01Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

+- Note: To check that two numeric values are equivalent within a specified
+accuracy, as in the analogue of 
+[`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal)
+, please import [swift-numerics](https://github.com/apple/swift-numerics)


The comma needs to be on the same line as the link, otherwise it will be rendered with leading whitespace.

Remove the word "please" as overly colloquial.

grynspan · 2024-04-06T20:52:26Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

-analogue of [`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal)
-, please import [the swift-numerics package](https://github.com/apple/swift-numerics)
-and use the ``isApproximatelyEqual()`` function.
+- Note: To check that two numeric values are equivalent within a specified


Suggested change

- Note: To check that two numeric values are equivalent within a specified

To check that two numeric values are equivalent within a specified

The callout box is not necessary here.

grynspan · 2024-04-06T20:53:27Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

+accuracy, as in the analogue of 
+[`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal)
+, please import [swift-numerics](https://github.com/apple/swift-numerics)
+to use the ``isApproximatelyEqual()`` function.


Suggested change

to use the ``isApproximatelyEqual()`` function.

and use the ``isApproximatelyEqual()`` function.

I know @heckj suggested the opposite change, but "and" would be more grammatically correct in this position. (Sorry Joe!)

grynspan · 2024-04-06T20:54:28Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

-, please import [the swift-numerics package](https://github.com/apple/swift-numerics)
-and use the ``isApproximatelyEqual()`` function.
+- Note: To check that two numeric values are equivalent within a specified
+accuracy, as in the analogue of 


@chuckdude @medreisbach Does Apple style prefer "analogue" or "analog"?

/me places his bet on "analog" - the American english spelling

I suspect you're right, hence why I asked! 😃

You both win!

It's "analog", see https://support.apple.com/guide/applestyleguide/a-apsg3acde405/web.

medreisbach · 2024-04-11T20:25:38Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

+To check that two numeric values are equivalent within a specified
+accuracy, as in the analog of 
+[`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal),
+import [swift-numerics](https://github.com/apple/swift-numerics)
+and use the ``isApproximatelyEqual()`` function.


@grynspan @heckj What do you think about the following?

Suggested change

To check that two numeric values are equivalent within a specified

accuracy, as in the analog of

[`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal),

import [swift-numerics](https://github.com/apple/swift-numerics)

and use the ``isApproximatelyEqual()`` function.

The testing library doesn’t provide an equivalent of [`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal). To compare two numeric values within a specified accuracy, use ``isApproximatelyEqual()`` from [swift-numerics](https://github.com/apple/swift-numerics).

Drop "currently"—we're not planning to add an equivalent precisely because swift-numerics is the preferred solution. We don't anticipate a change here.

"an equivalent operation for" -> "an equivalent of"

"you can use" -> "use"?

Updated the recommended change to reflect Jonathan's feedback. I only suggested "you can use" instead of "use" because I wasn't sure how direct we wanted to be. If we feel this is the "preferred solution" then "use" works much better.

grynspan · 2024-04-13T23:21:43Z

Sources/Testing/Testing.docc/MigratingFromXCTest.md

+The testing library doesn’t provide an equivalent of
+[`XCTAssertEqual(_:_:accuracy:_:file:line:)`](https://developer.apple.com/documentation/xctest/3551607-xctassertequal).
+To compare two numeric values within a specified accuracy, 
+use ``isApproximatelyEqual()`` from [swift-numerics](https://github.com/apple/swift-numerics).


Suggested change

use ``isApproximatelyEqual()`` from [swift-numerics](https://github.com/apple/swift-numerics).

use `isApproximatelyEqual()` from [swift-numerics](https://github.com/apple/swift-numerics).

(DocC uses double backticks to refer to symbols in the same package or project.)

medreisbach

Looks good to me. Thanks for adding this and making those changes.

Add documentation for numeric value comparison swiftlang#165

c37bce0

wangxingyu5529 requested review from stmontgomery, grynspan, dennisweissmann, briancroom, SeanROlszewski and suzannaratcliff as code owners March 24, 2024 14:05

Add a blank line

6146f30

wangxingyu5529 mentioned this pull request Mar 24, 2024

Document the recommended pattern for performing floating point equality-with-accuracy expectations, analogous to XCTAssertEqual(_:_:accuracy:) #165

Closed

grynspan requested changes Mar 24, 2024

View reviewed changes

grynspan added documentation 📚 Improvements or additions to documentation enhancement New feature or request labels Mar 24, 2024

Move comment to the migration document

4998349

grynspan reviewed Mar 26, 2024

View reviewed changes

heckj reviewed Apr 5, 2024

View reviewed changes

Address comments on phrasing

02515ac

grynspan requested changes Apr 6, 2024

View reviewed changes

Address more comments

44ae5fd

medreisbach reviewed Apr 11, 2024

View reviewed changes

Paraphrase by stating the problem first

3dc931f

grynspan reviewed Apr 13, 2024

View reviewed changes

Use single backticks around isApproximatelyEqual

716cdff

medreisbach approved these changes Apr 23, 2024

View reviewed changes

grynspan approved these changes Apr 23, 2024

View reviewed changes

Merge branch 'main' into main

849d0fa

grynspan approved these changes Apr 24, 2024

View reviewed changes

grynspan merged commit 286de8c into swiftlang:main Apr 24, 2024

	- Note: When comparing two numeric values within a specified accuracy, i.e. the
	- Note: To check that two numeric values are equivalent within a specified accuracy, as in the

	, please import [the swift-numerics package](https://github.com/apple/swift-numerics)
	, import [the swift-numerics package](https://github.com/apple/swift-numerics)

	and use the ``isApproximatelyEqual()`` function.
	to use the ``isApproximatelyEqual()`` function.

	- Note: To check that two numeric values are equivalent within a specified
	To check that two numeric values are equivalent within a specified

	use ``isApproximatelyEqual()`` from [swift-numerics](https://github.com/apple/swift-numerics).
	use `isApproximatelyEqual()` from [swift-numerics](https://github.com/apple/swift-numerics).

Add documentation for numeric value comparison within specified accuracy #165 #314

Add documentation for numeric value comparison within specified accuracy #165 #314

Uh oh!

Conversation

wangxingyu5529 commented Mar 24, 2024 • edited by grynspan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation:

Modifications:

Result:

Checklist:

Uh oh!

grynspan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

heckj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grynspan Apr 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

medreisbach Apr 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

medreisbach left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

wangxingyu5529 commented Mar 24, 2024 •

edited by grynspan

Loading

grynspan Apr 6, 2024 •

edited

Loading

medreisbach Apr 11, 2024 •

edited

Loading

medreisbach left a comment •

edited

Loading