dpol1 commented on issue #3145:
URL: https://github.com/apache/hugegraph/issues/3145#issuecomment-5231624007
Contract notes for the LongEncoding corpus (PR #3146), the invariants worth
knowing before porting or refactoring:
**Alphabet and ordering.** `B64_SYMBOLS` = `0-9 A-Z _ a-z ~`, 64 chars in
ascending ASCII order. For canonical `encodeSortable` outputs, plain string
comparison gives numeric order: negatives (prefix `0`) sort before positives
because positive outputs always start with a length char >= `1`, the length
character orders different magnitudes within one sign, and the digits decide
between encodings of equal length.
**Length symbols.** `LENGTH_SYMBOLS` (`0-9A-F`) is exactly the first 16
characters of `B64_SYMBOLS`, and `decodeSortable` reads the declared length
through `B64_SYMBOLS.indexOf`, so the prefix relationship is load-bearing for
decoding: declared lengths from 0 to 63 are structurally accepted. Declared
length 0 is reachable only in the negative form `"00"`, since the initial
`str.length() >= 2` check rules out a bare positive length char.
**Wrapping is intentional.** `encodeSortable` maps negatives by `num +=
Long.MIN_VALUE` (overflow on purpose) and `decodeSortable` reverses it with
`value -= Long.MIN_VALUE`; the digit loop accumulates with multiply/add that
wrap silently. A port must use wrapping arithmetic (e.g.
`wrapping_add`/`wrapping_sub`/`wrapping_mul` in Rust), not checked arithmetic.
**Decode accepts more than encode produces.** Structurally valid input goes
up to 64 chars in the positive form and 65 with the negative prefix, and the
accumulation wraps rather than failing. Concrete case: `decodeSortable("00")`
returns `Long.MIN_VALUE`, while `encodeSortable(Long.MIN_VALUE)` produces
`"010"`. Round-trip equality holds encode->decode, not decode->encode.
**Empty-string edge.** `decodeB64("")` = 0, `decodeSignedB64("")` = 0,
`decodeSignedB64("-")` = 0. No exception.
**Specials.** `encodeSignedB64(Long.MIN_VALUE)` returns the literal
`"-80000000000"` (the b64 of 2^63). `encodeB64` rejects any negative input with
`IllegalArgumentException`.
**Error taxonomy.** `IllegalArgumentException` for argument/structural
precondition failures (input shorter than 2 chars, declared length not matching
the actual length, negative input to `encodeB64`); `NumberFormatException` for
any character outside the symbol table during digit decoding, including
non-ASCII BMP characters and surrogate code units; `NullPointerException` on
null. Exception classes are contract; messages deliberately are not.
**Domains.** Encode outputs are always pure ASCII. Decode input is arbitrary
UTF-16; the corpus exercises representative inputs on that side (non-ASCII BMP
chars, surrogate pairs, lone surrogates), not an exhaustive sweep.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
