Clarify and correct EndianUtils and SwappedDataInputStream API doc

[elharo]

Most of the methods in this class are badly named. Except for the swap methods, they all just read and write in little endian order. E.g. consider readSwappedInteger

    public static int readSwappedInteger(final InputStream input) throws IOException {
        final int value1 = read(input);
        final int value2 = read(input);
        final int value3 = read(input);
        final int value4 = read(input);
        return ((value1 & 0xff) << 0) + ((value2 & 0xff) << 8) + ((value3 & 0xff) << 16) + ((value4 & 0xff) << 24);
    }

This always reads four bytes from an input stream and always considers the first byte read to be the least significant. It would have been better named readLittleEndianInteger.

I'm tempted to deprecate the whole thing and replace it with something better named, but for now at least let's correct the Java doc.

@garydgregory

[garydgregory]

I think that using {@code _type_} would be better here.

[elharo]

Maybe. What's really confusing here is we need to distinguish two different "floats":

1. The Java float primitive in memory in the VM.
2. A 4 byte chunk read from an input stream or an array.

I'm not sure I've got this distinction clear enough yet. Let me play with it a bit more.

[elharo]

PTAL

[garydgregory]

We should be clear that the toggle is between big and little-endian. We'll then avoid the shadow of even thinking about middle-endian madness.

[elharo]

Good point. Curious, has any system ever actually used middle-endianess or is it just a theoretical possibility? Anyway, let me update this.

[garydgregory]

According to Wikipedia, PDP has something close also referred to PDP-endian!

[elharo]

Also corrected Javadoc for SwappedDataInputStream, which had all these problems and some more copy paste errors besides.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.99%. Comparing base (4bd93ec) to head (552d6ad).
Report is 975 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #566   +/-   ##
=========================================
  Coverage     85.98%   85.99%           
- Complexity     3496     3497    +1     
=========================================
  Files           231      231           
  Lines          8251     8253    +2     
  Branches        964      964           
=========================================
+ Hits           7095     7097    +2     
- Misses          865      866    +1     
+ Partials        291      290    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[garydgregory]

Hi @elharo

This is slightly confusing to me: The method returns a long (64-bit) but we are reading an 32-bit integer? Should we clarify this point? Something like "Reads a foo as a bar".

[elharo]

Since Java's ints are signed you can't fit the unsigned int values from ~2.2 billion to ~4 billion into an int, so you have to return a long. The long will always be <= 2^32, but might be greater than Integer.MAX_INT. Not sure how much of that to say here.

[garydgregory]

Makes sense, the comment already mentions "unsigned". TY for the clarification.