libtld: tld_email_list Class Reference

libtld  1.5.13
A library to determine the Top-Level Domain name of any URL.

The C++ side of the email list implementation. More...

Classes

struct  tld_email_t
 Parts of one email. More...
 

Public Types

typedef std::vector< tld_email_ttld_email_list_t
 A vector of email details. More...
 

Public Member Functions

 tld_email_list ()
 Initialize the tld_email_list object. More...
 
int count () const
 Return the number of emails recorded. More...
 
bool next (tld_email_t &e) const
 Retrieve a copy of the next email information. More...
 
bool next (tld_email *e) const
 Retrieve a copy of the next email information. More...
 
tld_result parse (const std::string &emails, int flags)
 Parse a new list of emails. More...
 
void rewind () const
 Rewind the reader to the start of the list. More...
 

Static Public Member Functions

static tld_email_field_type email_field_type (const std::string &name)
 Check whether a name represents a field with a list of emails. More...
 
static std::string quote_string (const std::string &name, char quote)
 Transform a name if it requires quotation. More...
 

Private Member Functions

void parse_all_emails ()
 Parse all the emails in f_input. More...
 

Private Attributes

tld_email_list_t f_email_list = tld_email_list_t()
 The list of emails. More...
 
int f_flags = 0
 The flags as passed to the parse() function. More...
 
std::string f_input = std::string()
 The input string of the last call to parse(). More...
 
std::string f_last_group = std::string()
 The last group read in the input. More...
 
int f_pos = 0
 The current position reading the emails. More...
 
tld_result f_result = TLD_RESULT_INVALID
 The result of the parse() function. More...
 

Detailed Description

Note that this structure is always used internally, even when the C version of the library is used to read emails from a string.

This class represents a list of emails as defined in a string and parsed by the parse() function. By default the list of emails is empty. The results of the parse can be retrieved using the next() function repetitively.

See also
parse()
next()

Definition at line 181 of file tld.h.

Member Typedef Documentation

This typedef creates a vector of emails that we use internally to store all the emails. We may later have additional functionality where this type becomes useful externally too. You are, of course, welcome to use it to store lists of emails.

Definition at line 197 of file tld.h.

Constructor & Destructor Documentation

tld_email_list::tld_email_list ( )

This function initializes the tld_email_list object appropriately.

By default a tld_email_list object is empty so the next() function returns false immediately and the count() function returns zero (0).

Definition at line 367 of file tld_emails.cpp.

Referenced by tld_email_alloc().

Member Function Documentation

int tld_email_list::count ( ) const

This function returns the number of times the next() function can be called to retrieve all the groups and emails. Note that this count include group entries (i.e. entries with a group name but no email addresses.)

Returns
The number of items in the list of emails, including groups.
See also
next()

Definition at line 791 of file tld_emails.cpp.

References f_email_list.

Referenced by email_to_vstring(), tld_email_list::tld_email_t::parse(), tld_email_list::tld_email_t::parse_group(), and tld_email_count().

tld_email_field_type tld_email_list::email_field_type ( const std::string &  name)
static

This function checks whether a given name represents (is used as) a list of email addresses.

All field names are expected to be ASCII. If any other characters appear then the function returns TLD_EMAIL_FIELD_TYPE_INVALID. The field name must also start with a letter (A-Z) and it cannot be empty.

When a field that does not represent an email address or a list thereof the function returns TLD_EMAIL_FIELD_TYPE_UNKNOWN.

In all other cases, the function return another TLD_EMAIL_FIELD_TYPE_...

Note that the field name may be followed by a colon character in which case the parser stops there.

Parameters
[in]nameThe name of the field to check.
Returns
One of the TLD_EMAIL_FIELD_TYPE_... values.

Definition at line 892 of file tld_emails.cpp.

References TLD_EMAIL_FIELD_TYPE_ADDRESS_LIST, TLD_EMAIL_FIELD_TYPE_ADDRESS_LIST_OPT, TLD_EMAIL_FIELD_TYPE_INVALID, TLD_EMAIL_FIELD_TYPE_MAILBOX, TLD_EMAIL_FIELD_TYPE_MAILBOX_LIST, and TLD_EMAIL_FIELD_TYPE_UNKNOWN.

bool tld_email_list::next ( tld_email_t e) const

This function reads the next email in your e parameter.

The function returns true when the email parameter could be set. It is very important that you check that return value because otherwise you cannot actually know whether you reached the end of the list.

Parameters
[out]eThe email object that receives the next item if there is one.
Returns
true if e was set, false otherwise and e is not modified.

Definition at line 821 of file tld_emails.cpp.

References f_email_list, and f_pos.

Referenced by email_to_vstring(), and tld_email_next().

bool tld_email_list::next ( tld_email e) const

This function reads the next email in your e parameter.

The function returns true when the email parameter could be set. It is very important that you check that return value because otherwise you cannot actually know whether you reached the end of the list.

Warning
The pointers saved in the tld_email structure are taken from the list of emails defined in the tld_email_list object. If the list is changed (by a call to the parse() function) then those pointers become invalid.
Parameters
[out]eThe email object that receives the next item if there is one.
Returns
true if e was set, false otherwise and e is not modified.

Definition at line 852 of file tld_emails.cpp.

References tld_email::f_canonicalized_email, tld_email::f_domain, f_email_list, tld_email::f_email_only, tld_email::f_fullname, tld_email::f_group, tld_email::f_original_email, f_pos, and tld_email::f_username.

tld_result tld_email_list::parse ( const std::string &  emails,
int  flags 
)

This function parses the list of emails as specified by emails. The result is TLD_RESULT_SUCCESS if all the email addresses were valid. Any other result means that the resulting list of email addresses will be completely empty.

Note that at this time it is not possible to only extra the list of valid emails from a list of valid and invalid emails.

Parameters
[in]emailsA list of email address to be parsed.
[in]flagsA set of flags to define what should be checked and what should be ignored. No flags are defined yet.
Returns
TLD_RESULT_SUCCESS when no errors were detected, TLD_RESULT_INVALID or some other value if any error occured.

Definition at line 395 of file tld_emails.cpp.

References f_email_list, f_flags, f_input, f_last_group, f_pos, f_result, parse_all_emails(), and TLD_RESULT_SUCCESS.

Referenced by check_uri(), email_to_vstring(), and tld_email_parse().

void tld_email_list::parse_all_emails ( )
private

This function reads all the emails found in the f_input string. It generates a list of emails segregated by group.

Definition at line 418 of file tld_emails.cpp.

References f_email_list, tld_email_list::tld_email_t::f_group, f_input, f_last_group, f_result, tld_email_list::tld_email_t::parse(), tld_email_list::tld_email_t::parse_group(), TLD_RESULT_INVALID, and TLD_RESULT_SUCCESS.

Referenced by parse().

std::string tld_email_list::quote_string ( const std::string &  str,
char  quote 
)
static

This function checks the quote parameter and react depending on what it is:

  • Quote is a Double Quote (") character

In this case, the characters are checked to see whether they all are atom characters, including spaces. If all are atoms, then the input str parameter is returned as is, otherwise it is returned between double quotes.

This is used for the display or full name.

  • Quote is a Single Quote (') character

In this case, the characters are checked to see whether they all are atom characters, including dots. If all are atoms, then the input str parameter is returned as is, otherwise it is returned between double quotes.

This is used for the username.

  • Quote is an opening square bracket character

In this case the character are checked to see whether they all are atom characters, including dots. If all are atoms, then the input str parameter is returned as is, otherwise it is returned between square brackets.

This is used for domain names.

  • Quote is an opening parenthesis character

In this case the characters are not checked because comments are always written between parenthesis. The quoting always happens. However, if the comment includes opening and closing parenthesis, then those are backslased.

This is used for comments.

Note that in effect this function cannot be used to create comments that include sub-comments.

  • Quote is another character.

In this case the function raises an exception.

Exceptions
std::logic_errorThe function was called with an invalid quote parameter.
Parameters
[in]strThe string to be quoted as required.
[in]quoteThe type of quotes to use with this string.
Returns
The input string with quotes if required.

Definition at line 716 of file tld_emails.cpp.

Referenced by email_to_vstring(), and tld_email_list::tld_email_t::parse().

void tld_email_list::rewind ( ) const

This function reset the reader position back to the beginning of the list of emails. The position increases each time the next() function returns true.

See also
next()

Definition at line 804 of file tld_emails.cpp.

References f_pos.

Referenced by email_to_vstring(), and tld_email_rewind().

Member Data Documentation

tld_email_list::f_email_list = tld_email_list_t()
private

This vector is the complete list of all the emails found while parsing the input string. Note that the parse() function clears the existing list each time it is called so new emails are not appended to an existing list. At the same time, the f_pos field is reset to zero.

By default the list is empty so calling next() immediately returns false and the count() function returns zero.

See also
count()
next()
parse()

Definition at line 217 of file tld.h.

Referenced by count(), next(), parse(), and parse_all_emails().

tld_email_list::f_flags = 0
private

This is the set of flags passed to the parse() funciton. These are used by the different parsing functions to determine what is allowed and what is not.

Note
In version 1.4.0 this parameter is not used and it should be set to zero to avoid surprises. Later I intend to add support to test for ASCII only, opposed to UTF-8, and a few other behaviors that may be useful when parsing emails.

Definition at line 213 of file tld.h.

Referenced by parse().

tld_email_list::f_input = std::string()
private

This is the exact input to the parse() function. It is used internally to hold the input string while parsing it.

Definition at line 212 of file tld.h.

Referenced by parse(), and parse_all_emails().

tld_email_list::f_last_group = std::string()
private

While reading a list of emails, a group is defined as a display name followed by a colon. That name is saved in this parameter as all the following emails will be assigned this group. Once the semi-colon is found, the f_last_group parameter is reset back to the empty string.

In the end, assuming no error occured, this parameter is always an empty string.

Definition at line 215 of file tld.h.

Referenced by parse(), and parse_all_emails().

tld_email_list::f_pos = 0
mutableprivate

This parameter is the index in the f_email_list field. It is reset to zero each time you call the parse() function and the rewind() function. The next() function increases it by one on each call until all the emails were read in which case it stops changing.

See also
next()
parse()
rewind()

Definition at line 216 of file tld.h.

Referenced by next(), parse(), and rewind().

tld_email_list::f_result = TLD_RESULT_INVALID
private

The result is stored in this parameter. By default this value is TLD_RESULT_SUCCESS. In most cases an error is represented by the TLD_RESULT_INVALID. If the domain of an email address is not correct, then other result values may be used.

Note that the parse() function stops as soon as an error occurs and that first error is what appears in f_result.

Definition at line 214 of file tld.h.

Referenced by parse(), and parse_all_emails().


The documentation for this class was generated from the following files:
  • /home/snapwebsites/BUILD/contrib/libtld/include/libtld/tld.h
  • /home/snapwebsites/snapcpp/contrib/libtld/src/tld_emails.cpp

This document is part of the Snap! Websites Project.

Copyright by Made to Order Software Corp.

Syndicate content

Snap! Websites
An Open Source CMS System in C++

Contact Us Directly