user58102: The documentation on Arduino's website shows SoftwareSerial::read() as returning a char. (link)
The header shows that the method returns an int. (link)
The cpp definition shows SoftwareSerial::read() returning the value from a buffer array of uint8_t values. (link)
Given all of this:

Why would the interface return an int instead of a uint8_t?
Why do the Arduino docs show it as returning a char?
Is it safe to send/receive 8-bits at a time using this library?

For (3) I'm using an HC-06 if that matters.

user47961: 
You'll see in the code just above your third link that the function can return a value of -1 if there is no data present. Thus a 16-bit value is used to cover the range of 8-bit uint8_ts, plus one extra value to show 'no valid data available'.
For simplicity, I guess.
Yes. This is what it's designed for.

In short, for all intents and purposes, only an 8-bit value is returned, but if you were to read into an int, you couldn't differentiate between a valid and invalid value.

user4143: 
The documentation on Arduino's website shows SoftwareSerial::read() as returning a char.

No it doesn't. There is nothing in the documentation that tells you the return type. There is only an example where the returned value is assigned to a char variable. That doesn't mean that it returns a char - it just means that whatever data type it does return can be invisibly cast to a char by the compiler.

The header shows that the method returns an int.

Indeed it does. That is because that is what it returns.

The cpp definition shows SoftwareSerial::read() returning the value from a buffer array of uint8_t values.

Yes, because the valid data that it deals with is 8 bits in size. Just because it handles 8 bit "valid" data doesn't mean that that's all it ever wants to return.  The "no data available" return value of -1 is obviously not something that is stored in the data. It's a status, not data. 


Why would the interface return an int instead of a uint8_t?

Because a uint8_t cannot encompass all the functionality stated in the "Returns" section:

the character read, or -1 if none is available

You can't return -1 in a uint8_t.

Why do the Arduino docs show it as returning a char?

It doesn't - as I mentioned above. It makes no claims at all about the returned data type.

Is it safe to send/receive 8-bits at a time using this library?

Yes. It performs serial data transfers using 8-N-1 by default. That's 8 data bits, no parity, and one stop bit. 

It's this kind of confusion with return types and bytes and integers and things that make people ask why they keep getting ÿÿÿÿÿÿ on the serial monitor. That's -1 cast as a char. I.e., "no data available" but they ignore that and treat everything returned as a char - most probably because the Arduino documentation shows an overly simplified example that ignores the possibility of a -1 being returned and treats everything as a char.
IMHO much of the Arduino documentation is somewhat sub-par and should not be taken literally - only as a rough guide for what is available. The same goes for much of their example code and projects.

58102: <p>The documentation on Arduino's website shows <code>SoftwareSerial::read()</code> as returning a <code>char</code>. (<a href="https://www.arduino.cc/en/Reference/SoftwareSerialRead" rel="nofollow noreferrer">link</a>)</p>

<p>The header shows that the method returns an <code>int</code>. (<a href="https://github.com/arduino/ArduinoCore-avr/blob/7a2e1cd815266fef3012a5c9b48f88d78551f838/libraries/SoftwareSerial/src/SoftwareSerial.h#L103" rel="nofollow noreferrer">link</a>)</p>

<p>The cpp definition shows <code>SoftwareSerial::read()</code> returning the value from a buffer array of <code>uint8_t</code> values. (<a href="https://github.com/arduino/ArduinoCore-avr/blob/7a2e1cd815266fef3012a5c9b48f88d78551f838/libraries/SoftwareSerial/src/SoftwareSerial.cpp#L402-L404" rel="nofollow noreferrer">link</a>)</p>

<p>Given all of this:</p>

<ol>
<li>Why would the interface return an <code>int</code> instead of a <code>uint8_t</code>?</li>
<li>Why do the Arduino docs show it as returning a <code>char</code>?</li>
<li>Is it safe to send/receive 8-bits at a time using this library?</li>
</ol>

<p>For (3) I'm using an HC-06 if that matters.</p>
 47961: <ol>
<li><p>You'll see in the code just above your third link that the function can return a value of <code>-1</code> if there is no data present. Thus a 16-bit value is used to cover the range of 8-bit <code>uint8_t</code>s, plus one extra value to show 'no valid data available'.</p></li>
<li><p>For simplicity, I guess.</p></li>
<li><p>Yes. This is what it's designed for.</p></li>
</ol>

<p>In short, for all intents and purposes, only an 8-bit value is returned, but if you were to read into an <code>int</code>, you couldn't differentiate between a valid and invalid value.</p>
 4143: <blockquote>
  <p>The documentation on Arduino's website shows SoftwareSerial::read() as returning a char.</p>
</blockquote>

<p>No it doesn't. There is nothing in the documentation that tells you the return type. There is only an example where the returned value is assigned to a <code>char</code> variable. That doesn't mean that it returns a char - it just means that whatever data type it does return can be invisibly cast to a <code>char</code> by the compiler.</p>

<blockquote>
  <p>The header shows that the method returns an int.</p>
</blockquote>

<p>Indeed it does. That is because that is what it returns.</p>

<blockquote>
  <p>The cpp definition shows SoftwareSerial::read() returning the value from a buffer array of uint8_t values.</p>
</blockquote>

<p>Yes, because the valid data that it deals with is 8 bits in size. Just because it handles 8 bit "valid" data doesn't mean that that's <em>all</em> it ever wants to return.  The "no data available" return value of -1 is obviously not something that is stored in the data. It's a status, not data. </p>

<hr>

<blockquote>
  <p>Why would the interface return an int instead of a uint8_t?</p>
</blockquote>

<p>Because a <code>uint8_t</code> cannot encompass all the functionality stated in the "Returns" section:</p>

<blockquote>
  <p>the character read, or -1 if none is available</p>
</blockquote>

<p>You can't return -1 in a <code>uint8_t</code>.</p>

<blockquote>
  <p>Why do the Arduino docs show it as returning a char?</p>
</blockquote>

<p>It doesn't - as I mentioned above. It makes no claims at all about the returned data type.</p>

<blockquote>
  <p>Is it safe to send/receive 8-bits at a time using this library?</p>
</blockquote>

<p>Yes. It performs serial data transfers using 8-N-1 by default. That's 8 data bits, no parity, and one stop bit. </p>

<hr>

<p>It's this kind of confusion with return types and bytes and integers and things that make people ask why they keep getting ÿÿÿÿÿÿ on the serial monitor. That's -1 cast as a char. I.e., "no data available" but they ignore that and treat everything returned as a <code>char</code> - most probably because the Arduino documentation shows an overly simplified example that ignores the possibility of a -1 being returned and treats everything as a <code>char</code>.</p>

<p>IMHO much of the Arduino documentation is somewhat sub-par and should not be taken literally - only as a rough guide for what is available. The same goes for much of their example code and projects.</p>
