Update readBytesUntil.adoc #697
Conversation
As a side note, a function readBytesTill() which also copies the supplied terminator into the array (assuming it fits) would be convenient to add as it does allow to distinguish a time-out from a termination detection.
Added note that millis()/timer0 is being used.
| @@ -49,7 +49,7 @@ Data type: `size_t`. | |||
|
|
|||
| [float] | |||
| === Notes and Warnings | |||
| The terminator character is discarded from the serial buffer. | |||
| The terminator character is discarded from the serial buffer, unless the return value equals `length`. If the return value is less than `length`, it cannot be determined whether this is due to a time-out or due to the detection of the supplied terminator. This function relies on millis() which uses timer0's overflow interrupt. | |||
There was a problem hiding this comment.
unless the return value equals `length`.
I think this is a reasonable clarification to add to the documentation, but the approach of talking about the return value made it a bit hard for me to understand when I put my "beginner glasses" on. I think it can be reworded to be more clear.
What do you think about this:
unless the number of characters read equals
length.
If the return value is less than `length`, it cannot be determined whether this is due to a time-out or due to the detection of the supplied terminator.
I feel that this information is already provided by the main description:
The function terminates if the terminator character is detected, the determined length has been read, or it times out
This function relies on millis() which uses timer0's overflow interrupt.
Is this true for all architectures officially supported by Arduino?:
We need to be careful to not assume that Arduino == AVR because it's much more than that. However, we don't need to worry about covering 3rd party cores in the Arduino Language Reference. It is the responsibility of their authors to document where there are differences from the official Arduino documentation.
|
@per1234, I made some further changes for your consideration: the meaning of a returned 0 has been corrected, and the functional description has been improved by connecting two lines to indicate that "returns the characters up to the last character before the supplied terminator" only applies in case the supplied terminator was detected - it does not necessarily apply to a time out situation or a length limit detection. |
|
|
||
| `Serial.readBytesUntil()` returns the number of characters read into the buffer. A 0 means no valid data was found. | ||
| `Serial.readBytesUntil()` returns the number of characters read into the buffer. A 0 means that supplied length < = 0, or that a time out occured or a termination character was found before any other input. |
There was a problem hiding this comment.
| `Serial.readBytesUntil()` returns the number of characters read into the buffer. A 0 means that supplied length < = 0, or that a time out occured or a termination character was found before any other input. | |
| `Serial.readBytesUntil()` returns the number of characters read into the buffer. A 0 means that the `length` parameter <= 0, a time out occurred, or a termination character was found before any other input. |
|
Thanks so much @Arnold-n! |
As a side note, a function readBytesTill() which also copies the supplied terminator into the array (assuming it fits) would be convenient to add as it does allow to distinguish a time-out from a termination detection.