RFR: 8170769 Provide a simple hexdump facility for binary data

[Stuart Marks]

Hi Vinnie,

Roger Riggs wrote:
>> The 'forEachOrdered' should not be necessary and may raise questions about why.
>> if there's no good reason, use 'forEach’.

Using forEachOrdered() is necessary. The dumpAsStream() method produces a 
stream; presumably it has a defined order that's the same as its input. The 
semantics of Stream.forEach() are extremely relaxed, and in particular it's not 
required to process stream elements in order, even if the stream is ordered. (In 
practice this is noticeable if the stream is run in parallel.)

I'd use forEachOrdered() both in the examples and also where you use it in 
implementations.

The methods that return streams should specify the important characteristics. 
Probably the ones most important one are that the returned stream is ordered and 
sequential. For the overloads that take fixed-size input, the resulting stream 
might also be SIZED.

I'm not convinced that the overloads that send output to an OutputStream pull 
their weight. They basically wrap the OutputStream in a PrintStream, which 
conveniently doesn't declare IOException, making it easy to use from a lambda 
passed to forEachOrdered(). If an error writing the output occurs, this is 
recorded by the PrintStream wrapper; however, the wrapper is then thrown away, 
making it impossible for the caller to check its error status.

The PrintStream wrapper also uses the platform default charset, and doesn't 
provide any way for the caller to override the charset.

Instead, you can just provide the Stream-returning methods, and let the user 
send the output to a PrintStream using forEachOrdered() as in your examples.

It might be nice to provide convenience APIs to send output elsewhere, but the 
problem is that it seems difficult to do so without losing control over things 
like error handling or charsets. In particular, since the hex formatter is 
producing strings, it seems like there should be an option to send the output to 
a Writer. Unfortunately it's difficult to do so from a Stream, because all the 
Writer methods throw IOException. However, solving this isn't hexdump's problem.

s'marks