Merge pull request #13 from arduino/Language_content

ADD Serial.readString(),  Serial.readStringUntil(), UPDATE Serial.parseInt() and Stream.parseInt()

Author: agdl

Language/Functions/Communication/Serial/parseInt.adoc

@@ -12,16 +12,21 @@
 
 [float]
 === Description
-Looks for the next valid integer in the incoming serial stream. `parseInt()` inherits from the link:stream{ext-relative}[Stream] utility class.
+Looks for the next valid integer in the incoming serial `stream.parseInt()` inherits from the link:stream{ext-relative}[Stream] utility class.
 
-If no valid integer is found within one second (adjustable through link:serialTimeout{ext-relative}[Serial.setTimeout()] ) a default value of 0 will be returned.
+
+In particular:
+
+* Initial characters that are not digits or a minus sign, are skipped; +
+* Parsing stops when no characters have been read for a configurable time-out value, or a non-digit is read; +
+* If no valid digits were read when the time-out (see Serial.setTimeout()) occurs, 0 is returned;
 [%hardbreaks]
 
 
 [float]
 === Syntax
 `Serial.parseInt()`
-
+`Serial.parseInt(char skipChar)`
 
 _Arduino Mega only:_
 
@@ -32,11 +37,11 @@ _Arduino Mega only:_
 
 [float]
 === Parameters
-Nothing
+`skipChar`: used to skip the indicated char in the search. Used for example to skip thousands divider.
 
 [float]
 === Returns
-`int` : the next valid integer
+`long` : the next valid integer
 
 --
 // OVERVIEW SECTION ENDS

Language/Functions/Communication/Serial/readBytesUntil.adoc

@@ -53,7 +53,7 @@ Serial.readBytesUntil() reads characters from the serial buffer into an array. T
 // definitions (please add the tag #DEFINITION#), and examples of Projects and Tutorials
 // (please add the tag #EXAMPLE#)  ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄
 [role="language"]
-* #LANGUAGE# link:../stream{ext-relative}[stream] +
-* #LANGUAGE# link:../Stream/streamReadByteUntil{ext-relative}[stream.readByteUntil()]
+* #LANGUAGE# link:../stream{ext-relative}[Stream] +
+* #LANGUAGE# link:../Stream/streamReadByteUntil{ext-relative}[Stream.readByteUntil()]
 --
 // HOW TO USE SECTION ENDS

Language/Functions/Communication/Serial/readString.adoc

@@ -0,0 +1,65 @@
+:source-highlighter: pygments
+:pygments-style: arduino
+:ext-relative: adoc
+
+
+= readString()
+
+
+// OVERVIEW SECTION STARTS
+[#overview]
+--
+
+[float]
+=== Description
+`Serial.readString()` reads characters from the serial buffer into a string. The function terminates if it times out (see link:setTimeout{ext-relative}[setTimeout()]).
+
+This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:stream{ext-relative}[Stream class] main page for more information.
+
+[%hardbreaks]
+
+
+[float]
+=== Syntax
+`Serial.readString()`
+
+
+[float]
+=== Parameters
+Nothing
+
+[float]
+=== Returns
+A string read from the serial buffer
+
+--
+// OVERVIEW SECTION ENDS
+
+
+
+
+// HOW TO USE SECTION STARTS
+[#howtouse]
+--
+
+[float]
+=== See also
+// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#),
+// definitions (please add the tag #DEFINITION#), and examples of Projects and Tutorials
+// (please add the tag #EXAMPLE#)  ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄
+[role="language"]
+* #LANGUAGE# link:../serial{ext-relative}[Serial] +
+* #LANGUAGE# link:begin{ext-relative}[begin()] +
+* #LANGUAGE# link:end{ext-relative}[end()] +
+* #LANGUAGE# link:available{ext-relative}[available()] +
+* #LANGUAGE# link:read{ext-relative}[read()] +
+* #LANGUAGE# link:peek{ext-relative}[peek()] +
+* #LANGUAGE# link:flush{ext-relative}[flush()] +
+* #LANGUAGE# link:print{ext-relative}[print()] +
+* #LANGUAGE# link:println{ext-relative}[println()] +
+* #LANGUAGE# link:write{ext-relative}[write()] +
+* #LANGUAGE# link:serialEvent{ext-relative}[SerialEvent()] +
+* #LANGUAGE# link:../Stream/streamParsefloat{ext-relative}[Stream.parseFloat()]
+
+--
+// HOW TO USE SECTION ENDS

Language/Functions/Communication/Serial/readStringUntil.adoc

@@ -0,0 +1,65 @@
+:source-highlighter: pygments
+:pygments-style: arduino
+:ext-relative: adoc
+
+
+= readStringUntil()
+
+
+// OVERVIEW SECTION STARTS
+[#overview]
+--
+
+[float]
+=== Description
+`readStringUntil()` reads characters from the serial buffer into a string. The function terminates if it times out (see link:setTimeout{ext-relative}[setTimeout()]).
+
+This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:stream{ext-relative}[Stream class] main page for more information.
+
+[%hardbreaks]
+
+
+[float]
+=== Syntax
+`Serial.readString(terminator)`
+
+
+[float]
+=== Parameters
+`terminator` : the character to search for (`char`)
+
+[float]
+=== Returns
+The entire string read from the serial buffer, until the terminator character is detected
+
+--
+// OVERVIEW SECTION ENDS
+
+
+
+
+// HOW TO USE SECTION STARTS
+[#howtouse]
+--
+
+[float]
+=== See also
+// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#),
+// definitions (please add the tag #DEFINITION#), and examples of Projects and Tutorials
+// (please add the tag #EXAMPLE#)  ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄
+[role="language"]
+* #LANGUAGE# link:../serial{ext-relative}[Serial] +
+* #LANGUAGE# link:begin{ext-relative}[begin()] +
+* #LANGUAGE# link:end{ext-relative}[end()] +
+* #LANGUAGE# link:available{ext-relative}[available()] +
+* #LANGUAGE# link:read{ext-relative}[read()] +
+* #LANGUAGE# link:peek{ext-relative}[peek()] +
+* #LANGUAGE# link:flush{ext-relative}[flush()] +
+* #LANGUAGE# link:print{ext-relative}[print()] +
+* #LANGUAGE# link:println{ext-relative}[println()] +
+* #LANGUAGE# link:write{ext-relative}[write()] +
+* #LANGUAGE# link:serialEvent{ext-relative}[SerialEvent()] +
+* #LANGUAGE# link:../Stream/streamParsefloat{ext-relative}[Stream.parseFloat()]
+
+--
+// HOW TO USE SECTION ENDS

Language/Functions/Communication/Stream/streamParseInt.adoc

@@ -12,7 +12,13 @@
 
 [float]
 === Description
-`parseInt()` returns the first valid (long) integer number from the current position. Initial characters that are not integers (or the minus sign) are skipped. `parseInt()` is terminated by the first character that is not a digit.
+`parseInt()` returns the first valid (long) integer number from the current position. Initial characters that are not integers (or the minus sign) are skipped.
+
+In particular:
+
+* Initial characters that are not digits or a minus sign, are skipped; +
+* Parsing stops when no characters have been read for a configurable time-out value, or a non-digit is read; +
+* If no valid digits were read when the time-out (see link:setTimeout{ext-relative}[Stream.setTimeout()]) occurs, 0 is returned;
 
 This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:stream{ext-relative}[Stream class] main page for more information.
 [%hardbreaks]
@@ -22,16 +28,19 @@ This function is part of the Stream class, and is called by any class that inher
 === Syntax
 `stream.parseInt(list)`
 
+`stream.parseInt(''list', char skipchar')`
 
 [float]
 === Parameters
 `stream` : an instance of a class that inherits from Stream.
 
 `list` : the stream to check for ints (`char`)
 
+`skipChar`: used to skip the indicated char in the search. Used for example to skip thousands divider.
+
 [float]
 === Returns
-`int`
+`long`
 
 --
 // OVERVIEW SECTION ENDS