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 (const char *line, const size_t len=-1) noexcept
	Instantiate a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(bool) or the size_with_eol() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

	rline (const std::string &line, const size_t len=-1) noexcept
	Instantiate a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the `size(true)` or the `size_full()` method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

	rline (const std::string &line, const std::string &eol_sequence)
	Instantiate a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (the `size(true)` and `size_full()` methods obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

rline &	append (const char *line, const size_t len=-1)
	Add the specified string (without checking whether it contains any EoL character sequences) onto the line of text (before the EoL sequence).

rline &	append (const std::string &line, const size_t len=-1)
	Add the specified string (without checking whether it contains any EoL character sequences) onto the line of text (before the EoL sequence).

rline &	assign (const char *line, const size_t len=-1) noexcept
	Assign a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(bool) or the size_with_eol() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

rline &	assign (const std::string &line, const size_t len=-1) noexcept
	Assign a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(bool) or the size_with_eol() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

char	at (const int index)
	Array-style access to the underlying std::string (without the EoL sequence).

const char *	c_str () noexcept
	Returns a pointer to the underlying string array, without the EoL sequence.

rline &	clear () noexcept
	Reset all data and internal flags to the original state of the constructor that has no parameters.

char *	data () noexcept
	Returns a pointer to the underlying string array, without the EoL sequence.

std::string *	data_string () noexcept
	Returns a pointer to the underlying std::string object, without the EoL sequence.

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 (const bool detected=true) noexcept
	Obtain a copy of the EoL sequence that was detected.

rline &	eol (const char c1, const char c2=0) noexcept
	Define the EoL sequence to use when detecting an EoL sequence (also clears the detected EoL sequence, if present).

rline &	eol (const std::string &eol_sequence)
	Define the EoL sequence to use when detecting an EoL sequence (also clears the detected EoL sequence, if present).

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.

bool	has_LFCR (const bool detected=true) noexcept
	Indicate whether a broken EoL sequence detected of `<LFCR>` is being used as the EoL sequence.

rline &	insert (const int position, const std::string &str, const size_t len=-1)
	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 detected 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.

bool	operator!= (const std::string &s)
	Compare with the underlying std::string (without the EoL sequence).

bool	operator== (const std::string &s)
	Compare with the underlying std::string (without the EoL sequence).

char	operator[] (int index)
	Array-style access to the underlying 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 (const bool detected=true) noexcept
	Provides the length of the detected EoL sequence.

size_t	size_with_eol () noexcept
	Provides the length of the line of text, including the EoL sequence (if one is present).

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
2025-Jan-05 v1.00 Added c_str(), data(), and append(char*, int) methods, and the rline(std::string, std::string) constructor
2025-Jan-09 v1.00 Added eol(char, char) and eol(std::string) methods for configuring a specific EoL sequence
2025-Jan-12 v1.00 Changed std::length_error to std::invalid_argument in response to length being specified as a negative value so this can more easily be handled with seperate code; added the at() method, and [], ==, and != operators
2025-Jan-13 v1.00 Improved internal support for EoL flag indication
2025-Feb-03 v1.00 Increased use of references and pointers

Version: 1.00

Author: Randolf Richardson

Constructor & Destructor Documentation

◆ rline() [1/4]

randolf::rline::rline ( )

inlinenoexcept

Instantiate an empty rline, with no EoL sequences present.

◆ rline() [2/4]

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

inlinenoexcept

Instantiate a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(bool) or the size_with_eol() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

If no EoL sequence was encountered, the has_eol() method will return false even though the contents of the supplied line were copied (and are still accessible) – this is useful in loops reading lines of text that are too long to store in memory with a single allocation (and either interpreting the absorbed data somehow, or using a simple loop to skip through to the end of the line before issuing an error that indicates the total line length).

Note: If line is a nullptr then it will be treated as an empty string without an 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: assign; clear; has_eol; is_null; size; size_with_eol

Parameters

line	Line of text to embrace
len	Length of line (-1 == ASCIIZ string)

◆ rline() [3/4]

randolf::rline::rline	(	const std::string &	line,
		const size_t	len = -1 )

inlinenoexcept

Instantiate a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(true) or the size_full() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

If no EoL sequence was encountered, the has_eol() method will return false even though the contents of the supplied line were copied (and are still accessible) – this is useful in loops reading lines of text that are too long to store in memory with a single allocation (and either interpreting the absorbed data somehow, or using a simple loop to skip through to the end of the line before issuing an error that indicates the total line length).

See also: assign; has_eol; is_null; size; size_with_eol

Parameters

line	Line of text to embrace
len	Length of line (-1 == defer to length of line provided)

◆ rline() [4/4]

randolf::rline::rline	(	const std::string &	line,
		const std::string &	eol_sequence )

inline

Instantiate a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (the size(true) and size_full() methods obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

If no EoL sequence was encountered, the has_eol() method will return false even though the contents of the supplied line were copied (and are still accessible) – this is useful in loops reading lines of text that are too long to store in memory with a single allocation (and either interpreting the absorbed data somehow, or using a simple loop to skip through to the end of the line before issuing an error that indicates the total line length).

Exceptions

std::length_error if the EoL sequence is longer than 2 characters

See also: assign; has_eol; is_null; size; size_with_eol

Parameters

line	Line of text to embrace, without the EoL sequence characters
eol_sequence	The EoL sequence to impose as if it had been detected (may be only 1 or 2 characters long)

Member Function Documentation

◆ append() [1/2]

rline & randolf::rline::append	(	const char *	line,
		const size_t	len = -1 )

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

line	The string to insert
len	Length of line (-1 == ASCIIZ string)

◆ append() [2/2]

rline & randolf::rline::append	(	const std::string &	line,
		const size_t	len = -1 )

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

line	The string to insert
len	Length of line (-1 == defer to length of line provided)

◆ assign() [1/2]

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

inlinenoexcept

Assign a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(bool) or the size_with_eol() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

If no EoL sequence was encountered, the has_eol() method will return false even though the contents of the supplied line were copied (and are still accessible) – this is useful in loops reading lines of text that are too long to store in memory with a single allocation (and either interpreting the absorbed data somehow, or using a simple loop to skip through to the end of the line before issuing an error that indicates the total line length).

Note: If line is a nullptr then it will be treated as an empty string without an 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; clear; has_eol; insert; is_null; size; size_with_eol

Parameters

line	Line of text to embrace
len	Length of line (-1 == ASCIIZ string)

◆ assign() [2/2]

rline & randolf::rline::assign	(	const std::string &	line,
		const size_t	len = -1 )

inlinenoexcept

Assign a new rline based on the supplied line of text, ending early upon encountering the first EoL sequence (use either the size(bool) or the size_with_eol() method to obtain the total quantity of characters that were absorbed, including the EoL sequence {if present}).

If no EoL sequence was encountered, the has_eol() method will return false even though the contents of the supplied line were copied (and are still accessible) – this is useful in loops reading lines of text that are too long to store in memory with a single allocation (and either interpreting the absorbed data somehow, or using a simple loop to skip through to the end of the line before issuing an error that indicates the total line length).

Returns: The same rline object so as to facilitate stacking

See also: append; has_eol; insert; is_null; size; size_with_eol

Parameters

line	Line of text to embrace
len	Length of line (-1 == defer to length of line provided)

◆ at()

char randolf::rline::at ( const int index )

inline

Array-style access to the underlying std::string (without the EoL sequence).

The first element is at index 0.

Exceptions

std::out_of_range if the index is out-of-range

Returns: char

See also: operator[]

Parameters

index Index of character to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position)

◆ 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

◆ c_str()

const char * randolf::rline::c_str ( )

inlinenoexcept

Returns a pointer to the underlying string array, without the EoL sequence.

Returns: Pointer to buffer (null terminated)

See also: data

◆ data()

char * randolf::rline::data ( )

inlinenoexcept

Returns a pointer to the underlying string array, without the EoL sequence.

Returns: Pointer to buffer (not null terminated)

See also: c_str

◆ data_string()

std::string * randolf::rline::data_string ( )

inlinenoexcept

Returns a pointer to the underlying std::string object, without the EoL sequence.

Returns: Pointer to buffer (not null terminated)

See also: c_str

◆ 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
FALSE = Line of text is not empty

See also: has_eol(); is_null()

◆ eol() [1/3]

const std::string & randolf::rline::eol ( const bool detected = true )

inlinenoexcept

Obtain a copy of the EoL sequence that was detected.

Returns: The EoL sequence as a string

See also: get

Parameters

detected TRUE = return the detected EoL sequence (default)
FALSE = return the EoL sequence to use when detecting an EoL sequence

◆ eol() [2/3]

rline & randolf::rline::eol	(	const char	c1,
		const char	c2 = 0 )

inlinenoexcept

Define the EoL sequence to use when detecting an EoL sequence (also clears the detected EoL sequence, if present).

Note: This method is the most efficient eol method to use for defining the specific EoL sequence to use.

Returns: The same rline object so as to facilitate stacking

See also: eol

Parameters

c1	The first character of the EoL sequence (typically 10 or 13)`10` = LF (Line Feed) 13 = CR (Carriage Return) 0 = enable EoL sequence auto-detection (this is the default in all constructors, and is also set by the clear method)
c2	The second character of the EoL sequence (typically 10 or 13)`10` = LF (Line Feed) 13 = CR (Carriage Return) 0 = indicate that this is not a two-character EoL sequence

◆ eol() [3/3]

rline & randolf::rline::eol ( const std::string & eol_sequence )

inline

Define the EoL sequence to use when detecting an EoL sequence (also clears the detected EoL sequence, if present).

Exceptions

std::length_error if the EoL sequence is longer than 2 characters

Returns: The same rline object so as to facilitate stacking

See also: eol

Parameters

eol_sequence The EoL sequence (may be only 1 or 2 characters long; or 0 characters to enable EoL auto-detection, which is also the default in all constructors)

◆ 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 detected (default = FALSE)

◆ has_eol()

bool randolf::rline::has_eol ( )

inlinenoexcept

Indicate whether an EoL sequence was detected.

Returns: TRUE = EoL sequence is present
FALSE = No EoL sequence

See also: empty

◆ has_LFCR()

bool randolf::rline::has_LFCR ( const bool detected = true )

inlinenoexcept

Indicate whether a broken EoL sequence detected of <LFCR> is being used as the EoL sequence.

Returns: TRUE = Broken EoL sequence is present
FALSE = No broken EoL sequence

See also: empty

Parameters

detected TRUE = report on whether a broken EoL sequence was detected (default)
FALSE = report on whether a broken EoL sequence was specifically defined as the EoL sequence to detect

◆ insert()

rline & randolf::rline::insert	(	const int	position,
		const std::string &	str,
		const size_t	len = -1 )

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
len	Length of string (-1 == defer to length of string provided)

◆ is_null()

bool randolf::rline::is_null ( )

inlinenoexcept

Indicate whether this line is non-existent, which means there is no text and no detected 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
FALSE = 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; size_eol; size_with_eol

Parameters

include_eol Whether to include the EoL sequence (default = FALSE)

◆ size_eol()

size_t randolf::rline::size_eol ( const bool detected = true )

inlinenoexcept

Provides the length of the detected EoL sequence.

Returns: Number of bytes (0 = no EoL string)

See also: size

Parameters

detected TRUE = report on the size of the detected EoL sequence (default)
FALSE = report on the size of the EoL sequence to use when detecting an EoL sequence

◆ size_with_eol()

size_t randolf::rline::size_with_eol ( )

inlinenoexcept

Provides the length of the line of text, including the EoL sequence (if one is present).

Returns: Number of bytes

See also: length; size

◆ 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-

Returns: The line of text as an std::string object

See also: get

◆ operator!=()

bool randolf::rline::operator!= ( const std::string & s )

inline

Compare with the underlying std::string (without the EoL sequence).

Returns: TRUE = doesn't match
FALSE = match

Parameters

s	String to compare with

◆ operator==()

bool randolf::rline::operator== ( const std::string & s )

inline

Compare with the underlying std::string (without the EoL sequence).

Returns: TRUE = match
FALSE = doesn't match

Parameters

s	String to compare with

◆ operator[]()

char randolf::rline::operator[] ( int index )

inline

Array-style access to the underlying std::string (without the EoL sequence).

The first element is at index 0.

Exceptions

std::out_of_range if the index is out-of-range

Returns: char

See also: at

Parameters

index Index of character to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position)

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

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/4]

◆ rline() [2/4]

◆ rline() [3/4]

◆ rline() [4/4]

Member Function Documentation

◆ append() [1/2]

◆ append() [2/2]

◆ assign() [1/2]

◆ assign() [2/2]

◆ at()

◆ clear()

◆ c_str()

◆ data()

◆ data_string()

◆ empty()

◆ eol() [1/3]

◆ eol() [2/3]

◆ eol() [3/3]

◆ get()

◆ has_eol()

◆ has_LFCR()

◆ insert()

◆ is_null()

◆ length()

◆ size()

◆ size_eol()

◆ size_with_eol()

◆ operator std::string()

◆ operator!=()

◆ operator==()

◆ operator[]()

Friends And Related Symbol Documentation

◆ operator<<