Skip to content

Annotate core helper nullability for Swift - #460

Merged
iziz merged 1 commit into
iziz:masterfrom
heymansmile:users/onlivan/EDAFRONT-52973-upstream-nullability
Nov 13, 2026
Merged

iziz merged 1 commit into
iziz:masterfrom
heymansmile:users/onlivan/EDAFRONT-52973-upstream-nullability

Conversation

@heymansmile

Copy link
Copy Markdown
Contributor

Summary

Swift currently imports these unannotated Objective-C APIs as implicitly unwrapped optionals. Add explicit nullability to 20 methods in three public headers so guaranteed results are nonoptional and lookups that can fail return optionals.

  • NBAsYouTypeFormatter (8 methods): both constructors and all six string results are nonnull; regions and string input remain nullable, and an injected metadata helper is required.
  • NBMetadataHelper (7 methods): the default initializer and two collection results are nonnull; the four lookup results are nullable.
  • NSArray+NBAdditions (5 methods): safe lookup results are nullable for missing indices and mismatched types.

Unaudited declarations and parameters keep their existing Swift imports. Three metadata-helper arguments remain unannotated because the implementation already declares them nonnull; narrowly scoped completeness-warning pragmas avoid conflicting annotations without changing the public parameter contract.

This PR changes only the three headers. Implementations, models, generics, existing NBPhoneNumberUtil contracts, and metadata are unchanged. Swift callers that relied on implicit unwrapping of nullable lookup results may need explicit optional handling.

Upstream / Metadata

  • Google libphonenumber ref for parity checks: v9.0.43.
  • Metadata updated: no.
  • Geocoding metadata updated: no.
  • Based on iziz/libPhoneNumber-iOS master at 91fcc7452b8baa55fc2f61519f24b1f87ae4716f.

Parity Checks

  • swift scripts/checkUpstreamTestParity.swift --upstream-ref v9.0.43
  • swift scripts/checkUpstreamAPIParity.swift --upstream-ref v9.0.43
Upstream JS tests: 173
Local ObjC tests: 182
Parity check passed: no upstream JS test names are missing locally.

Upstream JS public prototype methods: 66
Local ObjC public selectors: 93
API parity check passed: no tracked upstream JS public methods are missing locally.

Tests

Validation used a temporary local harness, outside this header-only diff:

  • Compiled all 12 Objective-C implementation files for arm64 macOS 12 and arm64 iOS Simulator 15 with -Werror=nullability-completeness: no warnings.
  • Typechecked the existing SwiftCore facade in Swift 6 mode on both targets.
  • Swift API Digester comparison: exactly 20 of 308 declarations changed on each target; excluded declarations and parameters are unchanged.
  • Positive Swift function-type checks fail before the change and pass after it on both targets.
  • Eight unsafe assignments of nullable lookup results compile before the change and are correctly rejected after it on both targets.
  • Runtime smoke checks cover both formatter constructors, nil/empty/unknown/GB/US regions, all six string methods, metadata lookups/collections, safe array access, and parsing/formatting. The same checks pass before and after:
Before: PASS: 219 runtime checks
After:  PASS: 219 runtime checks
  • git diff --check
  • Full upstream XCTest/Swift Testing suite, locale matrix, release builds, and thread sanitizer were not run.
  • Xcode scheme tests and application integration were not run.

Changelog

  • CHANGELOG.md is not changed; this contribution is limited to the three audited headers.

Notes

  • Objective-C selectors are unchanged.
  • No parsing, formatting, or metadata behavior is changed.

Annotate 20 methods across NBAsYouTypeFormatter, NBMetadataHelper and NSArray+NBAdditions. Preserve unaudited Swift imports and existing implementations.

@iziz iziz left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for taking the time to audit these APIs and verify how they import into Swift. Looks good to me!

@iziz
iziz merged commit b27567b into iziz:master Nov 13, 2026
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.

2 participants