randolf.ca  1.00
Randolf Richardson's C++ classes
Loading...
Searching...
No Matches
randolf::rline Class Reference

One line of text is stored in this class, with additional metadata to track whether the text was terminated by an EoL (End of Line) sequence, and, if so, what the EoL sequence was. More...

#include <rline>

+ Collaboration diagram for randolf::rline:

Public Member Functions

 rline () noexcept
 Instantiate an empty rline, with no EoL sequences present.
 
 rline (char *line, size_t len=-1) noexcept
 Instantiate a new rline based on the supplied line of text. Multiple lines embedded in the supplied string will be treated as a single line, and ignored therefore.
 
 rline (std::string line) noexcept
 Instantiate a new rline based on the supplied line of text. Multiple lines embedded in the supplied string will be treated as a single line, and ignored therefore.
 
rlineappend (const std::string str)
 Add the specified string (without checking whether it contains any EoL character sequences) onto the line of text (before the EoL sequence).
 
rlineassign (char *line, size_t len=-1) noexcept
 Assign a new line of text, the same way the constructor assigns it.
 
rlineassign (std::string line) noexcept
 Assign a new line of text, the same way the constructor assigns it.
 
rlineclear () noexcept
 Reset all data and internal flags to the original state of the constructor that has no parameters.
 
bool empty () noexcept
 Indicate whether the line of text is empty. Whether an EoL sequence is present is incidental since this only measures the size of the line of text without regard for the presence of an EoL sequence.
 
const std::string eol () noexcept
 Obtain a copy of the EoL sequence.
 
const std::string get (const bool include_eol=false) noexcept
 Obtain a copy of the entire line of text, without the EoL sequence (albeit by default, this can also be included by setting the include_eol flag).
 
bool has_eol () noexcept
 Indicate whether an EoL sequence was detected.
 
rlineinsert (int position, const std::string str)
 Insert the specified string (without checking whether it contains any EoL character sequences) into the line of text at the specified position.
 
bool is_null () noexcept
 Indicate whether this line is non-existent, which means there is no text and no EoL sequence. This is less than an an empty() string when it confirms that there literally are no characters at all.
 
size_t length (const bool include_eol=false) noexcept
 Provides the length of the line of text without the EoL sequence.
 
 operator std::string () const noexcept
 Convert this rline to an std::string without the EoL sequence.
 
size_t size (const bool include_eol=false) noexcept
 Provides the length of the line of text without the EoL sequence.
 
size_t size_eol () noexcept
 Provides the length of the EoL sequence.
 

Friends

std::ostream & operator<< (std::ostream &o, rline const &c)
 Support convenient streaming usage with std::cout, std::cerr, and friends.
 

Detailed Description

One line of text is stored in this class, with additional metadata to track whether the text was terminated by an EoL (End of Line) sequence, and, if so, what the EoL sequence was.

This is particularly useful for reading lines of text from a file or a socket without having to go to additional efforts to track whether the final line is terminated with an EoL sequence (since this class takes care of this detail).

By default, the EoL sequence may be <CR>, <LF>, <CRLF>, or <LFCR>.

Use case
One of the challenges with the std::string class is that it doesn't provide a way to differentiate between a empty line and NULL, unless one uses pointers to std::string objects and sets thoes pointers to nullptr which entails having to test for that, resulting in more code in various places to test for multiple conditions, thus providing opportunities for more unintended situations (a.k.a., bugs) ... and then there's the matter of how to handle the variety of EoL sequences that persist due to the diversity of Operating System standards, which complicates matters even more.

This class handles all of these details gracefully, and provides a thorough variety of clearly-documented methods that ensure consistency whilst handling the complexity of EoL sequences that may be 1 or 2 characters long and also differentiating between blank and NULL lines, all without causing significant increases in complexity in code.

History
  • 2024-Nov-16 v1.00 Initial version
Version
1.00
Author
Randolf Richardson

Constructor & Destructor Documentation

◆ rline() [1/3]

randolf::rline::rline ( )
inlinenoexcept

Instantiate an empty rline, with no EoL sequences present.

◆ rline() [2/3]

randolf::rline::rline ( char * line,
size_t len = -1 )
inlinenoexcept

Instantiate a new rline based on the supplied line of text. Multiple lines embedded in the supplied string will be treated as a single line, and ignored therefore.

Note
If line is a nullptr then it will be treated as an empty string without any EoL sequence instead of throwing a Null Pointer Exception. This provides an opportunity to write simpler code (see the is_null method for the way to check for this condition, which also happens to be the result of using the default constructor or calling clear).
See also
is_null
Parameters
lineLine of text to embrace
lenLength of line (-1 == ASCIIZ string)

◆ rline() [3/3]

randolf::rline::rline ( std::string line)
inlinenoexcept

Instantiate a new rline based on the supplied line of text. Multiple lines embedded in the supplied string will be treated as a single line, and ignored therefore.

Parameters
lineLine of text to embrace

Member Function Documentation

◆ append()

rline * randolf::rline::append ( const std::string str)
inline

Add the specified string (without checking whether it contains any EoL character sequences) onto the line of text (before the EoL sequence).

Returns
The same rline object so as to facilitate stacking
See also
assign
insert
Parameters
strThe string to insert

◆ assign() [1/2]

rline * randolf::rline::assign ( char * line,
size_t len = -1 )
inlinenoexcept

Assign a new line of text, the same way the constructor assigns it.

Note
If line is a nullptr then it will be treated as an empty string without any EoL sequence instead of throwing a Null Pointer Exception. This provides an opportunity to write simpler code (see the is_null method for the way to check for this condition, which also happens to be the result of using the default constructor or calling clear).
Returns
The same rline object so as to facilitate stacking
See also
append
insert
Parameters
lineLine of text to embrace
lenLength of line (-1 == ASCIIZ string)

◆ assign() [2/2]

rline * randolf::rline::assign ( std::string line)
inlinenoexcept

Assign a new line of text, the same way the constructor assigns it.

Returns
The same rline object so as to facilitate stacking
See also
append
insert
Parameters
lineLine of text to embrace

◆ clear()

rline * randolf::rline::clear ( )
inlinenoexcept

Reset all data and internal flags to the original state of the constructor that has no parameters.

Returns
The same rline object so as to facilitate stacking

◆ empty()

bool randolf::rline::empty ( )
inlinenoexcept

Indicate whether the line of text is empty. Whether an EoL sequence is present is incidental since this only measures the size of the line of text without regard for the presence of an EoL sequence.

Returns
TRUE = Line of text is empty@nFALSE = Line of text is not empty
See also
has_eol()
is_null()

◆ eol()

const std::string randolf::rline::eol ( )
inlinenoexcept

Obtain a copy of the EoL sequence.

Returns
The EoL sequence as a string
See also
get

◆ get()

const std::string randolf::rline::get ( const bool include_eol = false)
inlinenoexcept

Obtain a copy of the entire line of text, without the EoL sequence (albeit by default, this can also be included by setting the include_eol flag).

Returns
The line of text as a string
See also
eol
Parameters
include_eolWhether to include the EoL sequence (default = FALSE)

◆ has_eol()

bool randolf::rline::has_eol ( )
inlinenoexcept

Indicate whether an EoL sequence was detected.

Returns
TRUE = EoL sequence is present@nFALSE = No EoL sequence
See also
empty

◆ insert()

rline * randolf::rline::insert ( int position,
const std::string str )
inline

Insert the specified string (without checking whether it contains any EoL character sequences) into the line of text at the specified position.

Exceptions
std::out_of_rangeWhen the position (pos) provided is out of range (e.g., position is larger than the entire size of the string)
Returns
The same rline object so as to facilitate stacking
See also
append
assign
Parameters
positionWhere to insert the supplied string (0 = insert before first character; and use a negative number to set the position relative to the end of the line of text)
strThe string to insert

◆ is_null()

bool randolf::rline::is_null ( )
inlinenoexcept

Indicate whether this line is non-existent, which means there is no text and no EoL sequence. This is less than an an empty() string when it confirms that there literally are no characters at all.

Returns
TRUE = null string@nFALSE = not null (has text and/or an EoL sequence)
See also
empty

◆ length()

size_t randolf::rline::length ( const bool include_eol = false)
inlinenoexcept

Provides the length of the line of text without the EoL sequence.

This method is identital to the size method.

Returns
Number of bytes
See also
size
Parameters
include_eolWhether to include the EoL sequence (default = FALSE)

◆ size()

size_t randolf::rline::size ( const bool include_eol = false)
inlinenoexcept

Provides the length of the line of text without the EoL sequence.

This method is identital to the length method.

Returns
Number of bytes
See also
length
Parameters
include_eolWhether to include the EoL sequence (default = FALSE)

◆ size_eol()

size_t randolf::rline::size_eol ( )
inlinenoexcept

Provides the length of the EoL sequence.

Returns
Number of bytes (0 = no EoL string)

◆ operator std::string()

randolf::rline::operator std::string ( ) const
inlinenoexcept

Convert this rline to an std::string without the EoL sequence.

#include <iostream> // std::cout, std::cerr, std::endl, etc.
#include <string> // std::string
#include <randolf/rline>
int main(int argc, char *argv[]) {
randolf::rline rl("This is an example.\n");
std::string s = rl;
std::cout << "\"" << s << "\"" << std::endl;
return EXIT_SUCCESS;
} // -x- int main -x-
One line of text is stored in this class, with additional metadata to track whether the text was term...
Definition rline:41
Returns
The line of text as an std::string object
See also
get

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<< ( std::ostream & o,
rline const & c )
friend

Support convenient streaming usage with std::cout, std::cerr, and friends.

#include <iostream> // std::cout, std::cerr, std::endl, etc.
#include <string> // std::string
#include <randolf/rline>
int main(int argc, char *argv[]) {
randolf::rline rl("This is an example.\n");
std::cout << "\"" << rl << "\"" << std::endl;
return EXIT_SUCCESS;
} // -x- int main -x-
Returns
Line of text, without EoL sequence
Parameters
oOutput stream (provided automatically by std::cout and std::cerr)
cObject class (matched by compiler)

The documentation for this class was generated from the following file: