I would like to return to the issue of reading a byte of data from UART. From the discussion above (thanks to @VisualLab, @ccrause) it seems to me that there are 4 possibilities:
1. Leave the ReadChar function unchanged, being aware that #0 may mean there is no data in the buffer (quite comfortable, maybe good enough?)
0 is a valid value to transmit over serial, it cannot in general be reserved for status. If a user transmits for example a C style null terminated character string the end of string is a null character (0).
2. Add a Read function returning Int16, which is a more accurate translation of the Arduino code. Due to the type change, it may be more resource-consuming(?)
To be Arduino compatible this is the only option. However it is then the user's responsibility to only use the low byte for data. I do not prefer the Arduino route because to respect the result type
requires silliness:
int incomingByte = 0; // for incoming serial data
So to receive a single byte the user has to declare a 16 bit variable.
3. Add a function returning Boolean type and pasing value via parameter, according to my proposal (not very comfortable)
4. Add a function returning an enumerative type and passing value via parameter (more precise, not very comfortable), as proposed by @ccrause
These two options are actually similar, option 3 is merely when the status can only be two possible states, while option 4 is when there are more than two possible states (data read, not data, data but parity error). Since there is little to be done about a parity error[1] one could just as well drop the data in the receive method and pretend nothing was received, as per current implementation.
Another option is to consider Dzandaa's use case of first checking Serial.Available and then decide whether to call Read or not. This separates the logic into two methods which makes it a bit easier to implement, however the user now has to follow this pattern else run into issues at some point. Also the downside to this approach is that two method calls needs to be made before the received byte is available.
[1]
Not strictly true, but I'm considering single byte level errors since the Read method is not aware of any higher protocol. If a user wants to implement a more sophisticated error correction/recovery protocol the RXCompleteIRQ method needs to be overridden.