Add trigger_data_matching to Flexible Event explainer

[apasel422]

Fixes #765.

[csharrison]

It might help to add an example. IIUC, if the trigger data is [1, 5, 1000] and modulus is used:

• Trigger data 1 will match 1
• Trigger data 4 will match 1
• Trigger data 5 will match nothing
• Trigger data 1001 will match nothing
• Trgger data 1003 will match 1

is that right?

[apasel422]

I was thinking it would be something like this:

uint32_t Modulus(uint64_t input, const std::vector<uint32_t>& allowed_trigger_data) {
  CHECK(!allowed_trigger_data.empty());
  CHECK(is_strictly_increasing(allowed_trigger_data));
  if (allowed_trigger_data.contains(input)) {
    return static_cast<uint32_t>(input);
  }
  return allowed_trigger_data[input % allowed_trigger_data.size()];
}

In other words, modulus always causes there to be a match. But if you have other suggestions, let me know. If we think modulus should only be used with contiguous ranges starting at 0, we could do that, since we're really only adding it for backwards compatibility with default trigger specs, which are contiguous and which use modulus today.

[csharrison]

I don't love this, because it has the input acting both as trigger_data and an index into the possible trigger data. I feel it could end up confusing.

I wonder if we should explore alternatives where the input as as either an index only, or a trigger_data only. The latter is what I had in mind in my above comment, but the former would look something like

uint32_t Modulus(uint64_t input, const std::vector<uint32_t>& allowed_trigger_data) {
  return allowed_trigger_data[input % allowed_trigger_data.length];
}

The problem IMO with this approach is that there is nothing indicating that the trigger_data in the trigger registration could possibly "merely" act as an index. It warrants a separation in the "type" of trigger_data on the source and trigger side.

[apasel422]

I'm certainly open to alternatives here. I agree that it is potentially confusing.