Skip to content

New EventCode API #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 5 commits into from
Feb 23, 2024
Merged

New EventCode API #32

merged 5 commits into from
Feb 23, 2024

Conversation

cbs228
Copy link
Owner

@cbs228 cbs228 commented Feb 18, 2024 •
edited
Loading

Previous versions of the EventCode API had two problems:

  1. The conversion from MessageHeader → EventCode was fallible, even though messages with unrecognized event codes should still be played.

  2. Since each SAME event code was its own EventCode, it was not possible to separate the phenomenon from the severity.

This PR is a major overhaul of all enums used to decode SAME event codes.

Originator

  • Improved detection of National Weather Service vs Environment Canada. The WeatherService enum variant is dropped.

  • Rename Originator::as_str() to Originator::as_code_str() for clarity

  • Support the "alternate" format code.

  • Originator is no longer From<&str>. Instead, it should be constructed via Originator::from_org_and_call().

SignificanceLevel

  • SignificanceLevel::from() constructs directly from significance code str. The conversion is now infallible.

    • A new SignificanceLevel::Unknown variant is returned when a significance level cannot be determined. It sorts higher than Warning.

    • The UnknownSignificanceLevel is no longer required and is removed.

  • Renamed SignificanceLevel::as_str() → SignificanceLevel::as_code_str(). This method returns a one-character significance code.

  • The following messages are upgraded to Statement:

    • ADR Administrative Message
    • NMN Network Message Notification

Phenomenon

  • The enum of all the SAME events is renamed to Phenomenon.

  • Phenomenon previously de-normalized into significance levels, like TornadoWatch and TornadoWarning, are represented as a single enum entry like Tornado.

  • Phenomenon from the 2022 revision of NWSI 10-1712 and more Canadian codes are added:

    • EAN: Renamed to National Emergency Message
    • NAT: National Audible Test
    • NST: National Silent Test
    • FSW: Flash Freeze Warning
    • FZW: Freeze Warning
    • HLS: Hurricane Local Statement
    • SQW: Snow Squall Warning

  • Add basic categories of Phenomenon

  • Fix bad code entry for ADR (Administrative Message)

EventCode

  • The EventCode is now a struct which represents the combination of a Phenomenon and a SignificanceLevel.

  • EventCode no longer convert directly to static str. Formatting requires either Display or to_string(). The human-readable string output for each SAME event code is largely unchanged. Remove EventCode::as_display_str() and replace with as_display_string().

  • The alternate formatter for EventCode now displays only the phenomenon, like Tornado, without the significance level

  • EventCode are now Ord by their significance levels

  • EventCode no longer convert back to their original SAME event code string. Use MessageHeader::event_str() instead.

This is an API-BREAKING change.

@cbs228
sameold: reorg message
bc3da1e 
Move `sameold::message::event` → `sameold::message::phenomenon`

Move SignificanceLevel and errors to
`sameold::message::significance`

These moves do not impact the external API.
@cbs228 cbs228 added enhancement New feature or request sameold Applies to sameold library samedec Applies to samedec binary labels Feb 18, 2024
@cbs228 cbs228 self-assigned this Feb 18, 2024
@cbs228 cbs228 force-pushed the feature/new_events branch from c6a1d8e to 5007830 Compare February 22, 2024 01:42
@cbs228
sameold: overhaul Originator API
d48c218 
* Drop enum variant `WeatherService`, which was previously emitted
  if sameold could not determine if the originator was the NWS or
  Environment Canda. It's actually easy to tell: in Canada, SAME
  is only ever transmitted on Weatherradio stations. This means
  the station callsign will be an `EC/…` station.

* Rename `Originator::as_str()` to `Originator::as_code_str()` for
  clarity

* Support the "alternate" format code.

* Originator is no longer `From<&str>`. Instead, it should be
  constructed via `Originator::from_org_and_call()`.

* Originator now implements Default

This is API-BREAKING for sameold. The samedec executable only
reports the Display value, which is largely unchanged, but a
`$SAMEDEC_ORIGINATOR` of "National Weather Service" will now be
emitted instead of "Weather Service."
@cbs228
sameold: message: infallible conversion to significance
79eb1f9 
* `SignificanceLevel::from()` constructs directly from
  significance code str. The conversion is infallible.
  A new `SignificanceLevel::Unknown` variant is returned
  when a significance level cannot be determined. It sorts
  higher than `Warning`.

* The conversion from `str` to `SignificanceLevel` is now
  infallible. A new `SignificanceLevel::Unknown` variant,
  which is the new Default, represents cases when the
  significance level cannot be determined.

* The UnknownSignificanceLevel is no longer required and
  is removed.

* Renamed `SignificanceLevel::as_str()` →
  `SignificanceLevel::as_code_str()`. This method returns a
  one-character significance code.

* The Unknown variant is the new Default.

This is an API-BREAKING change.
@cbs228 cbs228 force-pushed the feature/new_events branch from 5007830 to 1996c30 Compare February 22, 2024 03:09
@cbs228
sameold: message: EventCode API for more informative decodes
03ff745 
* The `EventCode` is now a struct which represents the combination
  of a `Phenomenon` and a `SignificanceLevel`.

  * The enum of all the SAME events is renamed to `Phenomenon`.

  * Phenomenon previously de-normalized into significance levels,
    like `TornadoWatch` and `TornadoWarning`, are represented as
    a single enum entry like `Tornado`.

  * Phenomenon from the 2022 revision of NWSI 10-1712 and more
    Canadian codes are added:

    * EAN: Renamed to National Emergency Message
    * NAT: National Audible Test
    * NST: National Silent Test
    * FSW: Flash Freeze Warning
    * FZW: Freeze Warning
    * HLS: Hurricane Local Statement
    * SQW: Snow Squall Warning

  * The alternate formatter for `EventCode` now displays only the
    phenomenon, like `Tornado`, without the significance level

* The conversion of `EventCode` from str is now infallible.
  Drop the `UnrecognizedEventCode` error.

* The `EventCodeIter` is not required and is dropped from the
  public API.

* Fix bad code entry for ADR (Administrative Message)

* Add dependency on `phf`

This is an API-BREAKING change.
@cbs228
samedec: update for breaking EventCode API
ec9f691 
The new API is simpler and doesn't require matches for errors.

The integration tests are also updated.
@cbs228 cbs228 force-pushed the feature/new_events branch from 1996c30 to ec9f691 Compare February 23, 2024 02:18
@cbs228 cbs228 merged commit c5292b4 into develop Feb 23, 2024
@cbs228 cbs228 deleted the feature/new_events branch February 23, 2024 02:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees

@cbs228 cbs228

Labels
enhancement New feature or request samedec Applies to samedec binary sameold Applies to sameold library
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@cbs228