randolf.ca
1.00
Randolf Richardson's C++ classes
|
This rmailaddr class provides an object-oriented eMail address. More...
#include <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. | |
This rmailaddr class provides an object-oriented eMail address.
Some of the key features are:
#include
lines as needed)std::string
(which tracks its own string length)Validation of the format of an eMail address is helpful in ensuring that eMail addresses received from elsewhere comply with internet standards.
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.)
An ASCIIZ string is a C-string (char* array) that includes a terminating null (0) character at the end.
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.)
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):
|
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:
|
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:
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
|
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:
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
|
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:
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
mailbox | RFC-compliant eMail address |
|
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:
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
mailbox | RFC-compliant eMail address |
|
inline |
Access only the eMail address, without display-name, and without any sets of enclosing quotation-marks or enclosing angle-brackets, etc.
std::out_of_range | if the index is out-of-range |
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) |
|
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.
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) |
|
inline |
Access an eMail address's domain-part (the portion following the @
sign).
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) |
|
inline |
Access an eMail address (enclosed in angle-brackets), and preceded by the display-name (if one is available).
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) |
|
inline |
Find out if this object doesn't hold any eMail addresses.
|
inline |
Return a list of errors that have been collected (instead of throwing exceptions).
|
inline |
Clear the list of errors that have been collected (instead of throwing exceptions).
|
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.
To test for a pass, use a comparison such as m.grade() <= 'c'
(strict) or m.grade() <= 'd'
(not strict).
index | eMail address index (default is 0 for the first eMail address) |
|
inline |
Indicates whether a display-name was included with this eMail address.
index | eMail address index (default is 0 for the first eMail address) |
|
inline |
Find out whether this object holds any number of eMail addresses. If there are no eMail addresses, then this method returns FALSE
.
|
inline |
|
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
.
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
Indicates whether this is just an eMail address, without any other parts such as display-name, group constructs, comments, etc.
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) |
|
inline |
Access an eMail address's local-part (the portion preceding the @
sign).
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) |
|
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.
policy_flag | FALSE = do not retain comments embedded in eMail addresses (deafult) TRUE = retain comments embedded in eMail addresses |
|
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.
policy_flag | TRUE = support UTF-8 characters in eMail addresses (deafult) FALSE = do not support UTF-8 characters in eMail addresses |
|
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.
policy_flag | TRUE = convert every tab character to a space FALSE = do not convert tab characters to spaces (default) |
|
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.)
policy_flag | TRUE = throw exceptions (default) FALSE = don't throw exceptions |
|
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.)
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
|
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.)
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
mailbox | RFC-compliant eMail address |
|
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.)
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
mailbox | RFC-compliant eMail address |
|
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.)
std::invalid_argument | describing the problem, along with the byte offset where the problem originated from |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
mailbox | RFC-compliant eMail address |
len | Number of characters (-1 = ASCIIZ string) |
|
inline |
Find out how many eMail addresses this object holds.
|
inline |
Generate a detailed output of all tokens that's useful for debugging.
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.
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") |
|
inline |
Array-style access to eMail addresses. The first element is at index 0.
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) |
|
friend |
Support convenient streaming usage with std::cout, std::cerr, and friends.
o | Output stream (provided automatically by std::cout and std::cerr) |
c | Object class (matched by compiler) |