Skip to content

docs: align cross-language hashing guidance - #340

Merged
tisonkun merged 7 commits into
apache:mainfrom
tisonkun:docs/countmin-empty-inputs
Nov 10, 2026
Merged

tisonkun merged 7 commits into
apache:mainfrom
tisonkun:docs/countmin-empty-inputs

Conversation

@tisonkun

@tisonkun tisonkun commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Document recommended cross-language input conventions consistently for Count-Min, HLL, CPC, Theta, Tuple, Bloom, and XOR:

  • Use 64-bit integers directly and the appropriate integer-widening strategy for narrower values.
  • Use canonical_float for floating-point values and raw_bytes for UTF-8 strings and byte slices.
  • Skip empty string and byte-slice updates. Return zero for their Count-Min estimates and bounds, and false for membership queries, without querying the sketch or filter.

Keep encoding recommendations in each sketch's module documentation and describe the four encoding strategies in hash::value. Use consistent module documentation links from the public types and remove duplicate method-level encoding guidance.

Organize the Count-Min examples around configuration, updates, and frequency queries, followed by explicit caller-side handling of empty inputs. Keep legacy format compatibility details with the serialization methods. Cross-language interchange uses i64 counters, following the format discussion.

Differences in current implementations' empty-byte and signed-zero handling remain tracked in TCK discussion #20. This PR documents the recommended conventions without changing runtime behavior.

Validation: cargo x check, cargo x test (763 tests, including 147 doctests), and cargo x lint passed, including rustdoc link checks.

@tisonkun tisonkun changed the title docs(countmin): explain empty updates and queries docs: align cross-language hashing guidance Nov 9, 2026
@tisonkun
tisonkun merged commit c4fb158 into apache:main Nov 10, 2026
10 checks passed
@tisonkun
tisonkun deleted the docs/countmin-empty-inputs branch November 10, 2026 06:46
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