randolf.ca  1.00
Randolf's C++ classes
randolf::rmailaddr Class Reference

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

+ 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). More...
 
 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). More...
 
 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). More...
 
 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). More...
 
 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). More...
 
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. More...
 
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. More...
 
std::string domain_part (int index=0)
 Access an eMail address's domain-part (the portion following the @ sign). More...
 
std::string email (int index=0)
 Access an eMail address (enclosed in angle-brackets), and preceded by the display-name (if one is available). More...
 
bool empty ()
 Find out if this object doesn't hold any eMail addresses. More...
 
std::vector< error_dataerrors ()
 Return a list of errors that have been collected (instead of throwing exceptions). More...
 
rmailaddrerrors_clear ()
 Clear the list of errors that have been collected (instead of throwing exceptions). More...
 
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. More...
 
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. More...
 
bool has_display_name (const int index=0)
 Indicates whether a display-name was included with this eMail address. More...
 
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. More...
 
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. More...
 
bool is_policy_keep_comments ()
 Find out the state of this policy. More...
 
bool is_policy_support_utf8 ()
 Find out the state of this policy. More...
 
bool is_policy_tabs_to_spaces ()
 Find out the state of this policy. More...
 
bool is_policy_throw_exceptions ()
 Find out the state of this policy. More...
 
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. More...
 
std::string local_part (int index=0)
 Access an eMail address's local-part (the portion preceding the @ sign). More...
 
std::u8string operator[] (int index)
 Array-style access to eMail addresses. The first element is at index 0. More...
 
rmailaddrpolicy_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. More...
 
rmailaddrpolicy_support_utf8 (bool policy_flag)
 Sets the policy for whether to support UTF-8 characters. More...
 
rmailaddrpolicy_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). More...
 
rmailaddrpolicy_throw_exceptions (bool policy_flag)
 Sets the policy for whether to throw exceptions when an error is encountered. More...
 
rmailaddrset (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.) More...
 
rmailaddrset (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.) More...
 
rmailaddrset (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.) More...
 
rmailaddrset (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.) More...
 
int size ()
 Find out how many eMail addresses this object holds. More...
 
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. More...
 

Friends

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

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-
This rmailaddr class provides an object-oriented eMail address.
Definition: rmailaddr:281

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 * set(const char *mailbox, int len=-1)
Set a new eMail address, resetting all internal flags, counters, and arrays (but not changing any exi...
Definition: rmailaddr:903

◆ 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_argumentdescribing the problem, along with the byte offset where the problem originated from
See also
rmailaddr
Parameters
mailboxRFC-compliant eMail address
lenNumber 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_argumentdescribing the problem, along with the byte offset where the problem originated from
See also
rmailaddr
rmailaddr
Parameters
mailboxRFC-compliant eMail address
lenNumber 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_argumentdescribing the problem, along with the byte offset where the problem originated from
See also
rmailaddr
rmailaddr
Parameters
mailboxRFC-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_argumentdescribing the problem, along with the byte offset where the problem originated from
See also
rmailaddr
rmailaddr
Parameters
mailboxRFC-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_rangeif the index if 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
indexIndex 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
indexIndex 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
indexIndex 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
indexIndex 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
indexeMail 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
indexeMail 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_flagindicate wither angle-brackets are okay (default is FALSE so that the meaning of the word "pure" is not tainted)
indexeMail 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
indexIndex 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_flagFALSE = 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_flagTRUE = 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_flagTRUE = 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_flagTRUE = 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_argumentdescribing 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
mailboxRFC-compliant eMail address
lenNumber 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_argumentdescribing 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
See also
rmailaddr
Returns
The same rmailaddr object so as to facilitate stacking
Parameters
mailboxRFC-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_argumentdescribing 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
See also
rmailaddr
Returns
The same rmailaddr object so as to facilitate stacking
Parameters
mailboxRFC-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_argumentdescribing 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
See also
rmailaddr
Returns
The same rmailaddr object so as to facilitate stacking
Parameters
mailboxRFC-compliant eMail address
lenNumber 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
filterFilter (string containing characters for those types that are to be included {unrecognized types will be ignored}; the default is no filter)
prefixPrefix (text to insert before the beginning of each line)
eolEnd-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
indexIndex 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 Function 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
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: