tld_email_list Class Reference

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_t >	tld_email_list_t
	A vector of email details.

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

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.
static std::string	quote_string (const std::string &name, char quote)
	Transform a name if it requires quotation.

Private Member Functions
void	parse_all_emails ()
	Parse all the emails in f_input.

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

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 222 of file tld.h.

Member Typedef Documentation

tld_email_list_t

tld_email_list::tld_email_list_t

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 238 of file tld.h.

Constructor & Destructor Documentation

tld_email_list()

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

count()

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 788 of file tld_emails.cpp.

References f_email_list.

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

email_field_type()

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]

name

The name of the field to check.

Returns

One of the TLD_EMAIL_FIELD_TYPE_... values.

Definition at line 889 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.

next() [1/2]

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]

e

The 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 849 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.

next() [2/2]

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]

e

The 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 818 of file tld_emails.cpp.

References f_email_list, and f_pos.

parse()

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]	emails	A list of email address to be parsed.
[in]	flags	A 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 392 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(), and tld_email_parse().

parse_all_emails()

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 415 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().

quote_string()

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_error

The function was called with an invalid quote parameter.

Parameters

[in]	str	The string to be quoted as required.
[in]	quote	The type of quotes to use with this string.

Returns

The input string with quotes if required.

Definition at line 713 of file tld_emails.cpp.

Referenced by tld_email_list::tld_email_t::parse().

rewind()

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 801 of file tld_emails.cpp.

References f_pos.

Member Data Documentation

f_email_list

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 258 of file tld.h.

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

f_flags

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 254 of file tld.h.

Referenced by parse().

f_input

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 253 of file tld.h.

Referenced by parse(), and parse_all_emails().

f_last_group

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 256 of file tld.h.

Referenced by parse(), and parse_all_emails().

f_pos

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 257 of file tld.h.

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

f_result

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 255 of file tld.h.

Referenced by parse(), and parse_all_emails().

---

The documentation for this class was generated from the following files:

• libtld/tld.h
• libtld/tld_emails.cpp