Adds Int(buffer:) initializer to FixedWidthInteger types

[natikgadzhi]

Motivation:

Makes it possible to make integers out of ByteBuffers directly with an initializer. I.e. UInt32(buffer: ByteBuffer(bytes: [0, 1, 2, 3])). Closes #3012.

Modifications:

• Adds the Int(buffer:) initializer in ByteBuffer-int.swift
• Adds tests in ByteBufferTest.swift. Holy hell this file is huge.
• Note that Int(buffer:) will crash if the buffer does not have enough bytes in it to represent the desired integer type.
• It also does not expose endianness and uses Endianness.host, to keep the public API clean and simple. It's a convenience initializer, so I thought keeping it minimal is a good idea.

Result:

Nicer direct initializer for integers from ByteBuffers.

[natikgadzhi]

Hmmmm. Unlike Array(buffer:), this will fail if there's not enough stuff in the Buffer. The other two just read whatever is readable, so they should not fail arbitrarily if the user didn't check the length.

Perhaps it's worth adding a check and making this throwing, or keeping this optional? Or documenting that the user should ensure the length of the buffer is enough?

[natikgadzhi]

I checked the docs for ByteBuffer, and they already explain that ByteBuffer can cast to/from "various unsigned int types", so I think that's enough.

[Lukasa]

This should definitely be failable, so that we can avoid the force-unwrap. We also want to add tests.

There's a separate question about whether this should be exactly the right size.

[natikgadzhi]

@weissi strong opinions on checking that the buffer size matches the int size exactly?

If we should verify the size match, the most straightforward way would be to check buffer.readableBytes == MemoryLayout<Self.self>.size, right?

[weissi]

I'm definitely in favour of checking that this is exactly the right size. It's weird to left garbage around, if that's expected readInteger is the right tool. Endianness should also be configurable (but defaulted to .host) Something like

var buffer = buffer
guard let value = buffer.readInteger(endianness: endianness, as: Self.self), buffer.readableBytes == 0 else {
    return nil
}
return value

[natikgadzhi]

Done. You did all the work for me.

I thought making it optional is a better choice than making it throwing — I don't think anyone need to capture the specific error, so no need to make an extra error type.

[weissi]

Thank you, I'm happy with this but @Lukasa or someone from the NIO should approve too.

[Lukasa]

This is a lovely patch @natikgadzhi, thank you so much! ✨

[Lukasa]

Ah dang, one quick note from the docs:

error: Return value documented for initializer returning void
   --> ../ByteBuffer-int.swift:146:9-146:117
144 |     ///   - endianness: The endianness to use when reading the integer, defaults to the host system's endianness.
145 |     ///
146 +     /// - Returns: The integer value read from the buffer, or nil if the buffer size did not match the integer type.
    |         ╰─suggestion: Remove return value documentation
147 |     @inlinable
148 |     public init?(buffer: ByteBuffer, endianness: Endianness = .host) {

Looks like you should change this to just say "this initializer will fail if the buffer size does not match the size of the integer type".

[natikgadzhi]

Ooops. That should do it. Deleted the whole returns line as the first line already matches "exactly the right size"