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.

rline *	append (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).

rline *	assign (char *line, size_t len=-1) noexcept
	Assign a new line of text, the same way the constructor assigns it.

rline *	assign (std::string line) noexcept
	Assign a new line of text, the same way the constructor assigns it.

rline *	clear () 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.

rline *	insert (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

line	Line of text to embrace
len	Length 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

line	Line 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

str	The 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

line	Line of text to embrace
len	Length 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

line	Line 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_eol Whether 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_range When 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

position	Where 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)
str	The 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_eol Whether 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_eol Whether 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[]) {
  rline rl("This is an example.\n");
  std::string s = rl;
  std::cout << "\"" << s << "\"" << std::endl;
  return EXIT_SUCCESS;
} // -x- int main -x-

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.

Returns: Line of text, without EoL sequence

Parameters

o	Output stream (provided automatically by std::cout and std::cerr)
c	Object class (matched by compiler)

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

randolf/rline

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ rline() [1/3]

◆ rline() [2/3]

◆ rline() [3/3]

Member Function Documentation

◆ append()

◆ assign() [1/2]

◆ assign() [2/2]

◆ clear()

◆ empty()

◆ eol()

◆ get()

◆ has_eol()

◆ insert()

◆ is_null()

◆ length()

◆ size()

◆ size_eol()

◆ operator std::string()

Friends And Related Symbol Documentation

◆ operator<<