Tidy docs image layout, tighten ISO-8859-1 usage, add ByteBuffer helper, and mark legacy Bytes APIs as deprecated

[peter-lawrey]

Functional changes

• Docs image relocation

  • Move documentation images from docs/images/** to src/main/docs/images/** so they live alongside the AsciiDoc sources and can be packaged/linked consistently:

    • Figure1.png, bytes2.jpg, IntelliJ data-view screenshots, and source/Figure1.svg.

  • All paths in README.adoc and other docs now expect the new src/main/docs/images/ location (consistent with other modules).

• More robust ByteBuffer handling across JDK versions

  • Introduce net.openhft.chronicle.bytes.internal.BufferUtil with helpers:

    • setPosition(ByteBuffer, int), setLimit(ByteBuffer, int), clear(ByteBuffer), flip(ByteBuffer).

  • Replace direct buffer.position()/limit()/clear() calls in core classes (NativeBytes, VanillaBytes, UncheckedNativeBytes, tests) with these helpers to keep the explicit (Buffer) cast in one place and avoid JDK-8 vs JDK-9+ bytecode quirks.

• Consistent ISO-8859-1 usage

  • Replace platform-default String.getBytes() and new String(byte[]) with explicit ISO_8859_1 in core code (Bytes, BytesStore, NativeBytesStore, BytesUtil) and tests.
  • This makes charset assumptions explicit and avoids surprise behaviour on non-default encodings.

• Safer and clearer string/byte parsing behaviour

  • ByteStringParser.parse8bit(Appendable, StopCharTester):

    • Still handles StringBuilder and Bytes directly, but now also supports any Appendable by buffering into a StringBuilder and copying via a safe helper (appendTo).

  • ByteStringParser.parse8bit(Appendable, StopCharsTester) given Appendable behaves similarly, falling back to StringBuilder for non-optimised appendables.

  • These paths now throw IORuntimeException if a foreign Appendable has an IOException during append, rather than silently ignoring it.

• Content-equals and vectorised mismatch behaviour tightened

  • BytesInternal.java11ContentEqualUsingVectorizedMismatch:

    • Now throws UnsupportedOperationException if either side is not backed by a HeapBytesStore, instead of returning null and silently falling back in the caller.
    • Any unexpected Throwable also results in an UnsupportedOperationException after logging, rather than returning null.

  • This makes failures around the Java-11 Arrays.mismatch path explicit and easier to diagnose; tests have been updated accordingly.

• Mapped file and bytes boundary behaviour more thoroughly exercised

  • Add tests to verify:

    • MappedBytes.zeroOut() clears bytes correctly when a custom page size is used and the range crosses page boundaries.
    • MappedFile/MappedBytesStore.safeLimit() and inside(long) remain coherent when the mapping page size differs from the OS default (new “page matrix” tests).

  • No changes to the production MappedFile API, but we now assert correctness under more configurations.

• Guarded / unchecked behaviour and overflow semantics

  • UncheckedBytesBehaviourTest now asserts unchecked writes can advance past ‘writeLimit’ without failing, while the checked view remains constrained.

  • NativeBytesOverflowTest and DecoratedBufferOverflowExceptionTest confirm:

    • When reference tracing is disabled, overflow paths still throw DecoratedBufferOverflowException but keep getCause() null.
    • When tracing is enabled, existing behaviour (enriched causes) is preserved.

• Bounds/loop correctness and minor behavioural fixes

  • Several small correctness improvements:

    • Bytes.indexOf(Bytes) and Bytes.indexOf(BytesStore, int) restructure internal variables to avoid subtle order-of-use bugs; the external contract is unchanged.
    • BytesUtil.combineDoubleNewline now has explicit default handling and early returns for non-matching cases, making the switch behaviour easier to reason about.
    • BinaryIntArrayReference.bindValueAt and BinaryLongArrayReference.bindValueAt now validate that the supplied IntValue/LongValue is the expected Binary*Reference subtype and throw IllegalArgumentException otherwise, instead of silently casting.
    • HeapBytesStore.appendAndReturnLength now consistently uses the original writePosition parameter for both reverseBytesFrom and length calculation, removing a redundant local and making the code easier to audit.

• Error-handling and warning improvements

  • PageUtil.parsePageSize now:

    • Emits a targeted WARN with the offending value on parse failure.
    • Returns DEFAULT_HUGE_PAGE_SIZE as before, but with clearer diagnostics.

  • Numerous tests now assert histogram and timing counters are actually updated (e.g. MappedUniqueTimeProviderTest, DistributedUniqueTimeProviderTest, jitter tests) instead of just printing metrics.

---

Non-functional changes

• API deprecation and clean-up

  • A large set of rarely used / test-only methods and legacy helpers are now marked @Deprecated with explicit removal targets “to be removed in 2027”, for example:

    • Formatting and parsing helpers (AppendableUtil.append(...) with custom Appendable & CharSequence, AppendableUtil.findUtf8Length(byte[]), StandardDecimaliser.toDecimal(...), MaximumPrecision constructor).
    • Legacy Boolean/number parsers (ByteStringParser.parseBoolean(...), parseFloat, parseLongDecimal, parseBigDecimal, lastNumberHadDigits(), various UTF-8 helpers and “not atomic” add-and-get methods).
    • Test-only or internal plumbing methods on Bytes, BytesStore, BytesRingBuffer, BytesIn, BytesOut, BytesContext, MappedFile, MappedBytes, DistributedUniqueTimeProvider, MappedUniqueTimeProvider, refs, compression, interning, histogram, and unsafe helpers.
    • StreamingInputStream / StreamingOutputStream default constructors and init(...) methods.
    • Internal 24-bit read/write methods, volatile float/double accessors, native read/write shortcuts and some histogram/big-decimal helpers are explicitly marked for future removal.

  • Call sites in tests are updated and annotated with @SuppressWarnings("deprecation") where appropriate so the current build stays clean while giving downstream users time to move away from these APIs.

• Javadoc and documentation polish

  • Improve class-level Javadoc on core types (Bytes, BytesStore, BytesIn, BytesOut, StreamingDataInput, RandomDataInput, RandomDataOutput, BytesRingBuffer, OffsetFormat, Invocation, NativeBytesStore, SingleMappedFile, ReentrantFileLock, etc.) to:

    • Clarify thread-safety expectations.
    • Explain off-heap vs on-heap behaviour, reference counting, and responsibilities for releaseLast().
    • Link to relevant AsciiDoc guides (architecture-overview.adoc, memory-management.adoc, domestic-overview.adoc).

  • Add/extend package-info.java for:

    • bytes.internal, bytes.algo, bytes.pool, bytes.ref, bytes.render, bytes.util, bytes.domestic, and the new bytes.internal.migration.
    • Each package now has a short, precise description, and explicitly marks internal packages as non-API.

  • Tests and examples (readme tests) are tweaked to use ISO_8859_1 where strings are converted, aligning with the project’s charset policy.

• Static analysis, determinism, and test robustness

  • Replace ad-hoc new Random() and SecureRandom invocations with seeded instances (new Random(1L) or similar) to make tests deterministic and friendlier to static analysis and CI.
  • Add small “usage nudge” blocks in tests where fields were previously only used reflectively (for example in BytesUtilTest’s trivially-copyable structs) to keep SpotBugs and other tools satisfied that these code paths are exercised.
  • Wrap streams and writers in try-with-resources throughout tests (ByteStringReaderWriterTest, BytesReleaseInvariantNonPerformantMethodsTest, ByteStoreTest, MappedFileTest, CanonicalPathUtilTest, etc.) to avoid resource warnings and make intent clearer.
  • Simplify or remove dead/commented-out code in tests (e.g. extra failure-case variants, unused streams) while preserving behavioural coverage.

• Minor style and clarity improvements

  • Promote many magic numbers to named final fields (for example SIZE in JLBH and jitter tests) and reformat loops and switch statements for readability.
  • Fix a handful of method names in tests to follow consistent naming (e.g. isDirectMemoryReturnsExpectedValue), and convert some JUnit 4 assertions to JUnit 5 where those tests already use JUnit 5 APIs.
  • Remove unused imports and helper methods that were only used to placate older JDKs (for example PropertyReplacer.convertStreamToString), now that all supported environments can use the main APIs.

Overall, this PR is primarily non-functional: it relocates documentation assets, tightens charset usage, introduces a central BufferUtil for JDK compatibility, and marks a broad set of legacy APIs as deprecated while adding tests and documentation to support long-term clean-up. The functional changes are small and targeted toward robustness (better exception signalling in vectorised equality, clearer align/zeroOut handling, safer parsing for generic Appendables, and well-defined overflow semantics).