This rmailaddr class provides an object-oriented eMail address. More...

#include <rmailaddr>

Collaboration diagram for randolf::rmailaddr:

Classes
struct	error_data
	Structure of errors (only used when exceptions are disabled). More...

Public Member Functions
	rmailaddr () noexcept
	Instantiate an empty rmailaddr that doesn't qualify as a properly-formatted internet eMail address (because the minimum length of a valid internet eMail address is 1 character).

	rmailaddr (const char *mailbox, int len=-1)
	Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

	rmailaddr (const char8_t *mailbox, int len=-1)
	Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

	rmailaddr (const std::string mailbox)
	Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

	rmailaddr (const std::u8string mailbox)
	Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

std::string	addr (int index=0)
	Access only the eMail address, without display-name, and without any sets of enclosing quotation-marks or enclosing angle-brackets, etc.

std::string	display_name (int index=0)
	Access an eMail address's display-name (the portion preceding the angle brackets). If there were no angle-brackets, then an empty string will be returned.

std::string	domain_part (int index=0)
	Access an eMail address's domain-part (the portion following the `@` sign).

std::string	email (int index=0)
	Access an eMail address (enclosed in angle-brackets), and preceded by the display-name (if one is available).

bool	empty ()
	Find out if this object doesn't hold any eMail addresses.

std::vector< error_data >	errors ()
	Return a list of errors that have been collected (instead of throwing exceptions).

rmailaddr *	errors_clear ()
	Clear the list of errors that have been collected (instead of throwing exceptions).

char	grade (const int index=0)
	Grade an eMail address, similar to traditional elementary school grades. For simplicity, grades "a" through "c" are passes, while grades "d" through "f" are failures, although if less strict then "d" should also qualify as a pass.

bool	has_any ()
	Find out whether this object holds any number of eMail addresses. If there are no eMail addresses, then this method returns `FALSE`.

bool	has_display_name (const int index=0)
	Indicates whether a display-name was included with this eMail address.

bool	has_multiple ()
	Find out whether this object holds multiple eMail addresses. If there is only one eMail address, or no eMail addresses at all, then this method returns `FALSE`.

bool	has_one ()
	Find out whether this object holds exactly one eMail address. If there are two or more eMail addresses, or no eMail addresses, then this method returns `FALSE`.

bool	is_policy_keep_comments ()
	Find out the state of this policy.

bool	is_policy_support_utf8 ()
	Find out the state of this policy.

bool	is_policy_tabs_to_spaces ()
	Find out the state of this policy.

bool	is_policy_throw_exceptions ()
	Find out the state of this policy.

bool	is_pure (const bool angle_flag=false, const int index=0)
	Indicates whether this is just an eMail address, without any other parts such as display-name, group constructs, comments, etc.

std::string	local_part (int index=0)
	Access an eMail address's local-part (the portion preceding the `@` sign).

std::u8string	operator[] (int index)
	Array-style access to eMail addresses. The first element is at index 0.

rmailaddr *	policy_keep_comments (bool policy_flag)
	Sets the policy for whether to keep comments that were embedded in eMail address group-construct, display-name, and local-part portions.

rmailaddr *	policy_support_utf8 (bool policy_flag)
	Sets the policy for whether to support UTF-8 characters.

rmailaddr *	policy_tabs_to_spaces (bool policy_flag)
	Sets the policy for whether to convert every tab character (ASCII charcter 9) to a space (ASCII character 32). This conversion occurs only once when the eMail address is initially specified in a constructor or by way of one of the set() methods (changing this policy after this point will not be applied to the current eMail address, but it will be in effect for future calls to any of the set() methods).

rmailaddr *	policy_throw_exceptions (bool policy_flag)
	Sets the policy for whether to throw exceptions when an error is encountered.

rmailaddr *	set (const char *mailbox, int len=-1)
	Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

rmailaddr *	set (const char8_t *mailbox, int len=-1)
	Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

rmailaddr *	set (const std::string mailbox)
	Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

rmailaddr *	set (const std::u8string mailbox)
	Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

int	size ()
	Find out how many eMail addresses this object holds.

std::string	tokens_to_string (const std::string filter="", const std::string prefix="", const std::string eol="\n")
	Generate a detailed output of all tokens that's useful for debugging.

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

Detailed Description

This rmailaddr class provides an object-oriented eMail address.

Features

Some of the key features are:

constructors with sensible defaults help to simplify coding
documentation includes code samples (with #include lines as needed)
can handle ASCIIZ without needing to specify string length
can handle std::string (which tracks its own string length)

Use case

Validation of the format of an eMail address is helpful in ensuring that eMail addresses received from elsewhere comply with internet standards.

Background

I created this class to make it easier to write internet server daemons and other software that needs to accept and/or handle eMail addresses. (This is a complete re-write of the version I wrote in Java 17 years ago in 2007, which includes a significant array of differences due to the improved parsing approaches I use now that are more efficient, and the need to make sure that UTF-8 characters and punycode are both handled in a transparent manner.)

Getting started

Author: Randolf Richardson

Version: 1.00

History: 2024-May-07 v1.00 Initial version

Conventions: Lower-case letter "m" is regularly used in partial example code to represent an instantiated rmailaddr object.

An ASCIIZ string is a C-string (char* array) that includes a terminating null (0) character at the end.

Notes

I use the term "ASCIIZ string" to indicate an array of characters that's terminated by a 0 (a.k.a., null). Although this is very much the same as a C-string, the difference is that in many API functions a C-string must often be accompanied by its length value. When referring to an ASCIIZ string, I'm intentionally indicating that the length of the string is not needed because the string is null-terminated. (This term was also commonly used in assembly language programming in the 1970s, 1980s, and 1990s, and as far as I know is still used by machine language programmers today.)

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rmailaddr m("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Parameter stacking is supported (with methods that return rmailaddr*); in this example, notice that semicolons (";") and "e." references are omittted (when compared with the above):

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rmailaddr m("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Constructor & Destructor Documentation

◆ rmailaddr() [1/5]

randolf::rmailaddr::rmailaddr ( )

inlinenoexcept

Instantiate an empty rmailaddr that doesn't qualify as a properly-formatted internet eMail address (because the minimum length of a valid internet eMail address is 1 character).

Instantiating an empty rmailaddr is particularly useful for header-file definitions; for example:

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
randolf::rmailaddr m; //   <-- Empty rmailaddr initialization (no exceptions)
 
int main(int argc, char *argv[]) {
  try {
    m.set("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

◆ rmailaddr() [2/5]

randolf::rmailaddr::rmailaddr	(	const char8_t *	mailbox,
		int	len = -1 )

inline

Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

Usage example:

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rmailaddr m("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

◆ rmailaddr() [3/5]

randolf::rmailaddr::rmailaddr	(	const char *	mailbox,
		int	len = -1 )

inline

Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

Usage example:

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rmailaddr m("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

See also: rmailaddr

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

◆ rmailaddr() [4/5]

randolf::rmailaddr::rmailaddr ( const std::string mailbox )

inline

Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

Usage example:

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rmailaddr m("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

See also: rmailaddr

Parameters

mailbox RFC-compliant eMail address

◆ rmailaddr() [5/5]

randolf::rmailaddr::rmailaddr ( const std::u8string mailbox )

inline

Instantiate an rmailaddr that qualifies as a properly-formatted internet eMail address (if it doesn't qualify, then an exception will be thrown).

Usage example:

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rmailaddr>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rmailaddr m("nobody@example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "eMail address format exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  } catch (const std::exception e) {
    std::cerr << "Other exception: " << e.what() << std::endl;
    return EXIT_FAILURE;
  }
  return EXIT_SUCCESS;
} // -x- int main -x-

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

See also: rmailaddr

Parameters

mailbox RFC-compliant eMail address

Member Function Documentation

◆ addr()

std::string randolf::rmailaddr::addr ( int index = 0 )

inline

Access only the eMail address, without display-name, and without any sets of enclosing quotation-marks or enclosing angle-brackets, etc.

See also: display_name; domain_part; email; local_part; operator[](int)

Exceptions

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

Returns: std::string with only the eMail address (no display-name, and no enclosing sets of quotation-marks or enclosing angle-brackets, etc.)

Parameters

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

◆ display_name()

std::string randolf::rmailaddr::display_name ( int index = 0 )

inline

Access an eMail address's display-name (the portion preceding the angle brackets). If there were no angle-brackets, then an empty string will be returned.

See also: addr; domain_part; email; local_part; operator[](int)

Returns: std::string with only the display-name (no quotation marks, etc.)

Parameters

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

◆ domain_part()

std::string randolf::rmailaddr::domain_part ( int index = 0 )

inline

Access an eMail address's domain-part (the portion following the @ sign).

See also: get; addr; display_name; email; local_part; operator[](int)

Returns: std::string with only the domain-part (no angle brackets, etc.)

Parameters

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

◆ email()

std::string randolf::rmailaddr::email ( int index = 0 )

inline

Access an eMail address (enclosed in angle-brackets), and preceded by the display-name (if one is available).

Note: If the original form of the display-name had a delimiting space before the eMail address, then that space will be present in the result here. If not, a space will not be inserted. (In other words, this aspect of the original full eMail address will be retained.)

See also: addr; display_name; domain_part; local_part; operator[](int)

Returns: std::string with display-name and eMail address (in angle-brackets)

Parameters

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

◆ empty()

bool randolf::rmailaddr::empty ( )

inline

Find out if this object doesn't hold any eMail addresses.

See also: has_any; has_multiple; has_one; size

Returns: TRUE = no eMail addresses
FALSE = one or more eMail addresses

◆ errors()

std::vector< error_data > randolf::rmailaddr::errors ( )

inline

Return a list of errors that have been collected (instead of throwing exceptions).

See also: errors_clear; policy_throw_exceptions

◆ errors_clear()

rmailaddr * randolf::rmailaddr::errors_clear ( )

inline

Clear the list of errors that have been collected (instead of throwing exceptions).

See also: errors; policy_throw_exceptions

Returns: The same rmailaddr object so as to facilitate stacking

◆ grade()

char randolf::rmailaddr::grade ( const int index = 0 )

inline

Grade an eMail address, similar to traditional elementary school grades. For simplicity, grades "a" through "c" are passes, while grades "d" through "f" are failures, although if less strict then "d" should also qualify as a pass.

Ratings:
   a = Angle-brackets surrounding eMail address (optional display-name)
   b = Bare eMail address (no display-name)
   c = Complex eMail address (groups; optional angle-brackets; optional display-name)
   d = Defective (because obsolete RFC standards were utilized)
   e = Errors (only when collecting errors instead of throwing exceptions)
   f = Failure (an exception was thrown, or eMail address is blank)

To test for a pass, use a comparison such as m.grade() <= 'c' (strict) or m.grade() <= 'd' (not strict).

Parameters

index eMail address index (default is 0 for the first eMail address)

◆ has_display_name()

bool randolf::rmailaddr::has_display_name ( const int index = 0 )

inline

Indicates whether a display-name was included with this eMail address.

Returns: TRUE = eMail address includes a display-name
FALSE = eMail address has no display-name

Parameters

index eMail address index (default is 0 for the first eMail address)

◆ has_any()

bool randolf::rmailaddr::has_any ( )

inline

Find out whether this object holds any number of eMail addresses. If there are no eMail addresses, then this method returns FALSE.

See also: empty; has_multiple; has_one; size

Returns: TRUE = one or more eMail addresses
FALSE = no eMail addresses

◆ has_multiple()

bool randolf::rmailaddr::has_multiple ( )

inline

Find out whether this object holds multiple eMail addresses. If there is only one eMail address, or no eMail addresses at all, then this method returns FALSE.

See also: empty; has_any; has_one; size

Returns: TRUE = two or more eMail addresses
FALSE = one eMail address
FALSE = no eMail addresses

◆ has_one()

bool randolf::rmailaddr::has_one ( )

inline

Find out whether this object holds exactly one eMail address. If there are two or more eMail addresses, or no eMail addresses, then this method returns FALSE.

See also: empty; has_any; has_multiple; size

Returns: TRUE = exactly one eMail address
FALSE = two or more eMail addresses
FALSE = no eMail addresses

◆ is_policy_keep_comments()

bool randolf::rmailaddr::is_policy_keep_comments ( )

inline

Find out the state of this policy.

See also: policy_keep_comments

Returns: policy status

◆ is_policy_tabs_to_spaces()

bool randolf::rmailaddr::is_policy_tabs_to_spaces ( )

inline

Find out the state of this policy.

See also: policy_tabs_to_spaces

Returns: policy status

◆ is_policy_throw_exceptions()

bool randolf::rmailaddr::is_policy_throw_exceptions ( )

inline

Find out the state of this policy.

See also: policy_throw_exceptions

Returns: policy status

◆ is_policy_support_utf8()

bool randolf::rmailaddr::is_policy_support_utf8 ( )

inline

Find out the state of this policy.

See also: policy_support_utf8

Returns: policy status

◆ is_pure()

bool randolf::rmailaddr::is_pure	(	const bool	angle_flag = false,
		const int	index = 0 )

inline

Indicates whether this is just an eMail address, without any other parts such as display-name, group constructs, comments, etc.

Returns: TRUE = eMail address includes a display-name
FALSE = eMail address has no display-name

Parameters

angle_flag	indicate wither angle-brackets are okay (default is FALSE so that the meaning of the word "pure" is not tainted)
index	eMail address index (default is 0 for the first eMail address)

◆ local_part()

std::string randolf::rmailaddr::local_part ( int index = 0 )

inline

Access an eMail address's local-part (the portion preceding the @ sign).

See also: addr; display_name; domain_part; email; operator[](int)

Returns: std::string with only the local-part (no angle brackets, etc.)

Parameters

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

◆ policy_keep_comments()

rmailaddr * randolf::rmailaddr::policy_keep_comments ( bool policy_flag )

inline

Sets the policy for whether to keep comments that were embedded in eMail address group-construct, display-name, and local-part portions.

Comments are excluded by default because most systems don't need them, but in the event that they are needed (or wanted), this policy makes it possible to make sure they aren't excluded during processing.

See also: set; is_policy_keep_comments

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

policy_flag FALSE = do not retain comments embedded in eMail addresses (deafult)
TRUE = retain comments embedded in eMail addresses

◆ policy_support_utf8()

rmailaddr * randolf::rmailaddr::policy_support_utf8 ( bool policy_flag )

inline

Sets the policy for whether to support UTF-8 characters.

Some older systems may not be able to handle 8-bit data that UTF-8 utilizes, in which case this policy makes it possible to easily reject incompatible eMail addresses before attempting to use them with such systems.

See also: set; is_policy_support_utf8

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

policy_flag TRUE = support UTF-8 characters in eMail addresses (deafult)
FALSE = do not support UTF-8 characters in eMail addresses

◆ policy_tabs_to_spaces()

rmailaddr * randolf::rmailaddr::policy_tabs_to_spaces ( bool policy_flag )

inline

Sets the policy for whether to convert every tab character (ASCII charcter 9) to a space (ASCII character 32). This conversion occurs only once when the eMail address is initially specified in a constructor or by way of one of the set() methods (changing this policy after this point will not be applied to the current eMail address, but it will be in effect for future calls to any of the set() methods).

There are some situations where a tab character can create problems, such as when interacting with certain older software or software that makes incorrect assumptions about how to parse an eMail address, and this policy makes it easy to accomodate such situations for the tab character, which some users may be including by using the tab key on their keyboards.

See also: set; is_policy_tabs_to_spaces

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

policy_flag TRUE = convert every tab character to a space
FALSE = do not convert tab characters to spaces (default)

◆ policy_throw_exceptions()

rmailaddr * randolf::rmailaddr::policy_throw_exceptions ( bool policy_flag )

inline

Sets the policy for whether to throw exceptions when an error is encountered.

When this flag is set, errors are tracked internally instead of throwing any exceptions, and will need to be retrieved using the errors() method, which is useful for analyzing an eMail address. (Enabling or disabling this flag does not erase the errors that are stored internally; you will need to use the errors_clear method for this.)

Warning: This policy is not meant for general use in the majority of applications; it is intended for technical analysis, which would be useful in diagnostic and research applications, or packet analysis applications like WireShark, or for advanced users who are interested in more techincal detail.

See also: errors; errors_clear; is_policy_throw_exceptions

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

policy_flag TRUE = throw exceptions (default)
FALSE = don't throw exceptions

◆ set() [1/4]

rmailaddr * randolf::rmailaddr::set	(	const char *	mailbox,
		int	len = -1 )

inline

Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

◆ set() [2/4]

rmailaddr * randolf::rmailaddr::set ( const std::string mailbox )

inline

Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox RFC-compliant eMail address

◆ set() [3/4]

rmailaddr * randolf::rmailaddr::set ( const std::u8string mailbox )

inline

Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox RFC-compliant eMail address

◆ set() [4/4]

rmailaddr * randolf::rmailaddr::set	(	const char8_t *	mailbox,
		int	len = -1 )

inline

Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any existing policies). Any existing eMail addresses will be cleared out. (This method is also used internally by most of this class's constructors.)

Exceptions

std::invalid_argument describing the problem, along with the byte offset where the problem originated from

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

See also: rmailaddr

Returns: The same rmailaddr object so as to facilitate stacking

Parameters

mailbox	RFC-compliant eMail address
len	Number of characters (-1 = ASCIIZ string)

◆ size()

int randolf::rmailaddr::size ( )

inline

Find out how many eMail addresses this object holds.

See also: empty; has_any; has_multiple; has_one

Returns: The number of eMail addresses

◆ tokens_to_string()

std::string randolf::rmailaddr::tokens_to_string	(	const std::string	filter = "",
		const std::string	prefix = "",
		const std::string	eol = "\n" )

inline

Generate a detailed output of all tokens that's useful for debugging.

Types:
   g = group name (beginning; includes colon)
   ; = group termination (semi-colon character)
   n = display name
   e = eMail address (includes angle brackets, if present)
   l = local-part
   d = domain-part
   c = comment (not implemented)
  \0 = not initialized (null; regard as "unknown"; this should never happen)

The difference between "token" and "p_token" is that "token" is the original and [mostly] unprocessed atom, while "p_token" has been processed with any sets of angle-brackets, sets of quotation-marks, comments, and whitespace removed. In nearly all instances, the value of "p_token" is what's needed.

Returns: std::string containing multi-line text (one token per line)

Parameters

filter	Filter (string containing characters for those types that are to be included {unrecognized types will be ignored}; the default is no filter)
prefix	Prefix (text to insert before the beginning of each line)
eol	End-of-Line sequence (default is "\n")

◆ operator[]()

std::u8string randolf::rmailaddr::operator[] ( int index )

inline

Array-style access to eMail addresses. The first element is at index 0.

See also: get; domain_part; local_part

Returns: std::u8string with only the eMail address (no angle brackets, etc.) as a native UTF-8 string

Parameters

index Index of eMail address to query for (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,
		rmailaddr const &	c )

friend

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

Returns: eMail address in human-readable form

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/rmailaddr

Classes

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ rmailaddr() [1/5]

◆ rmailaddr() [2/5]

◆ rmailaddr() [3/5]

◆ rmailaddr() [4/5]

◆ rmailaddr() [5/5]

Member Function Documentation

◆ addr()

◆ display_name()

◆ domain_part()

◆ email()

◆ empty()

◆ errors()

◆ errors_clear()

◆ grade()

◆ has_display_name()

◆ has_any()

◆ has_multiple()

◆ has_one()

◆ is_policy_keep_comments()

◆ is_policy_tabs_to_spaces()

◆ is_policy_throw_exceptions()

◆ is_policy_support_utf8()

◆ is_pure()

◆ local_part()

◆ policy_keep_comments()

◆ policy_support_utf8()

◆ policy_tabs_to_spaces()

◆ policy_throw_exceptions()

◆ set() [1/4]

◆ set() [2/4]

◆ set() [3/4]

◆ set() [4/4]

◆ size()

◆ tokens_to_string()

◆ operator[]()

Friends And Related Symbol Documentation

◆ operator<<