Skip to content

Do not call the caller's typo a library defect - #1033

Merged
Rafael-SOWNet merged 7 commits into
masterfrom
fix/domain-typo-is-not-a-library-bug
Aug 23, 2026
Merged

Do not call the caller's typo a library defect#1033
Rafael-SOWNet merged 7 commits into
masterfrom
fix/domain-typo-is-not-a-library-bug

Conversation

@Rafael-SOWNet

Copy link
Copy Markdown
Collaborator

Entity.Set.SpecialSet.Create(string) and Entity.Set.SpecialSet.Create(Domain) are both public,
and both answered an input they did not recognise with AngouriBugException — whose message ends
"please report about it to the official repository". Somebody who writes "NN" is told their own
typo is a defect in this library and asked to file it.

UnrecognizedDomainException has existed for exactly this case since it was written, and nothing
threw it
.

The second overload is the sharper one: Domain.Any is a documented member of the public enum.
It means no restriction, which is not a set this library has a node for — Domains.IsWithinDomain
answers it before ever reaching Create — so the only way to hit that arm is from outside, with
valid public API, and the answer was "report this as a bug".

Measured, on a build of each side

                        2.3.0                              this branch
Create("NN")            AngouriBugException  ...please  →  UnrecognizedDomainException:
                        report about it to the official     Unrecognized domain NN
                        repository
Create(Domain.Any)      the same                        →  NotSufficientlySupportedException:
                                                           There is no special set for domain Any
Create((Domain)99)      the same                        →  NotSufficientlySupportedException:
                                                           There is no special set for domain 99
Create("RR")            RR                              →  RR

NotSufficientlySupportedException rather than a parse error for the second, because the caller's
value is well formed and this library has no set for it — which is what that type means per
Docs/Usage/Exceptions.md.

Both stay under AngouriMathBaseException, so the catch the documentation tells a caller to
write is unaffected, and a test pins that. Nothing inside the library reaches either arm: the only
other route into the string overload is a SPECIALSET token, every spelling of which the switch
lists.

Verification

  • 22 new tests in Sources/Tests/UnitTests/Core/UnknownDomainIsNotABugTest.cs, covering all ten
    accepted names, all five domains that are sets, both refusal paths, and the base-exception
    guarantee.
  • Full suite on this branch: 7555 passed / 0 failed / 14 skipped, against a master baseline of
    7533 / 0 / 14 — exactly the 22 added, nothing else moved.
  • BREAKING-CHANGES.md entry with both values, measured rather than read off the diff.

Merge order

Adds an ## Unreleased section to BREAKING-CHANGES.md, so it costs one mechanical conflict round
against any other branch that adds one — #1025 does. It also appends a file_header_template scope
to Sources/.editorconfig, which #1016, #1017, #1025 and #1027 also append to; all the entries
survive that resolution.

Found while documenting the exception hierarchy for
#746 item 11 (#1027), which correctly left
it alone because changing which type a site throws is a breaking change and that PR is not.

Related: #1028 is the same wrong claim in a different place — SumAll() on an empty sequence.

SpecialSet.Create(string) and SpecialSet.Create(Domain) are both public, and
both answered an input they did not recognise with AngouriBugException, whose
message asks the caller to report the problem to this repository. Somebody who
writes "NN" is told their own typo is a defect here.

The string overload now throws UnrecognizedDomainException, which has existed
for exactly this since it was written and which nothing threw. The Domain
overload throws NotSufficientlySupportedException, because Domain.Any is a
documented member of the enum -- it means no restriction, which is not a set
this library has a node for -- and a value cast in from outside the enum is not
one either. Neither is the library's fault and neither now says it is.

Both stay under AngouriMathBaseException, so the catch the documentation tells
a caller to write is unaffected, and a test pins that.

Measured on a build of each side, with every accepted name and every domain
that is a set checked to still answer:

  Create("NN")           AngouriBugException  ->  UnrecognizedDomainException
  Create(Domain.Any)     AngouriBugException  ->  NotSufficientlySupportedException
  Create((Domain)99)     AngouriBugException  ->  NotSufficientlySupportedException
  Create("RR")           RR                   ->  RR

Nothing inside the library reaches either arm: Domains.IsWithinDomain answers
Domain.Any before Create sees it, and the only other route into the string
overload is a SPECIALSET token, every spelling of which the switch lists.
#1027 improved this site's message and left it an AngouriBugException; this
branch changes what it throws. Merging kept both, which is two default arms in
one switch and does not compile. The point of this change is that neither site
is a library defect, so the AngouriBugException arms go and the messages that
say what the caller passed stay.
@Rafael-SOWNet
Rafael-SOWNet merged commit cd0b56b into master Aug 23, 2026
31 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant