libtld: tld_object Class Reference

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

Class used to ease the use o the tld() function in C++. More...

Collaboration diagram for tld_object:

Public Member Functions

 tld_object (const char *domain_name=NULL)
 Initialize a tld object with the specified domain. More...
 
 tld_object (const std::string &domain_name)
 Initialize a tld object with the specified domain. More...
 
tld_category category () const
 Retrieve the category of this URI. More...
 
std::string country () const
 The name of the country linked to that TLD. More...
 
std::string domain () const
 Retrieve the domain name of this TLD object. More...
 
std::string domain_only () const
 Retrieve the domain name only. More...
 
std::string full_domain () const
 Full domain name: domain and TLD. More...
 
bool is_valid () const
 Check whether this TLD object is valid. More...
 
tld_result result () const
 Check the result of the tld() command. More...
 
void set_domain (const char *domain_name)
 Change the domain of a tld object with the newly specified domain. More...
 
void set_domain (const std::string &domain_name)
 Change the domain of a tld object with the newly specified domain. More...
 
tld_status status () const
 Retrieve the current status of the TLD. More...
 
std::string sub_domains () const
 Retrieve the sub-domains of the URI. More...
 
std::string tld_only () const
 Return the TLD of the URI. More...
 

Private Attributes

std::string f_domain = std::string()
 The domain or URI as specified in the constructor or set_domain() function. More...
 
tld_info f_info = tld_info()
 The information of the domain of this tld_object. More...
 
tld_result f_result = TLD_RESULT_INVALID
 The result of the tld() function call. More...
 

Detailed Description

The tld_object class allows you to query the tld library and then check each part of the URI with simple calls instead of you having to determine the location of each part.

Definition at line 158 of file tld.h.

Constructor & Destructor Documentation

tld_object::tld_object ( const char *  domain_name = NULL)

This function initializes a TLD object with the specified domain name. This function accepts a null terminated C string pointer. The pointer can be set to NULL or point to an empty string in which case the constructor creates an empty TLD object. Note that an empty TLD object is considered invalid and if called some functions throw the invalid_domain exception.

Note
The string is expected to be UTF-8.
Parameters
[in]domain_nameThe domain to parse by this object.

Definition at line 56 of file tld_object.cpp.

References set_domain().

tld_object::tld_object ( const std::string &  domain_name)

This function initializes a TLD object with the specified domain name. This function accepts standard C++ strings. The string can be empty to create an empty TLD object. Note that an empty TLD object is considered invalid and if called some functions throw the invalid_domain exception.

Note
The string is expected to be UTF-8.
Parameters
[in]domain_nameThe domain to parse by this object.

Definition at line 74 of file tld_object.cpp.

References set_domain().

Member Function Documentation

tld_category tld_object::category ( ) const

This function is used to retrieve the category of the URI. The category is just informative and has no special bearing on the TLD, domain, and sub-domain parts.

The existing categories are:

  • TLD_CATEGORY_INTERNATIONAL – TLD names that can be used by anyone in the world
  • TLD_CATEGORY_PROFESSIONALS – TLD names reserved to professionals
  • TLD_CATEGORY_LANGUAGE – language based TLD
  • TLD_CATEGORY_GROUPS – group based TLD
  • TLD_CATEGORY_REGION – TLD representing a region (usually within a country)
  • TLD_CATEGORY_TECHNICAL – technical TLD names used to make it all work
  • TLD_CATEGORY_COUNTRY – country based TLD
  • TLD_CATEGORY_ENTREPRENEURIAL – TLD spawned of other official TLD names
  • TLD_CATEGORY_UNDEFINED – this value means the TLD was not defined
Returns
The category of the current URI or TLD_CATEGORY_UNDEFINED.

Definition at line 324 of file tld_object.cpp.

References tld_info::f_category, and f_info.

std::string tld_object::country ( ) const

This TLD represents a country and this is its name.

If the TLD does not represent a country then this function returns an empty string. If category() returns TLD_CATEGORY_COUNTRY then this function should always return a valid name.

Note
At a later time we may also include other names such as the language, group, or region that the TLD represents. At that time we'll certainly rename the function and field.
Returns
The name of the country or "" if undefined.

Definition at line 344 of file tld_object.cpp.

References tld_info::f_country, and f_info.

std::string tld_object::domain ( ) const

The TLD object keeps a copy of the domain name as specified with the constructor. This copy can be retrieved by this function. This is an exact copy of the input (i.e. no canonicalization.)

Returns
The domain as specified to the constructor or the set_domain() functions.

Definition at line 188 of file tld_object.cpp.

References f_domain.

std::string tld_object::domain_only ( ) const

This function returns the domain name without the TLD nor any sub-domains.

A domain name never includes any period.

Exceptions
invalid_domainThis exception is raised when this function is called with an invalid TLD object. This happens whenever you create the object or call set_domain() with an invalid URI. You should call is_valid() and if false, avoid calling this function.
Returns
The domain name without TLD or sub-domains.

Definition at line 266 of file tld_object.cpp.

References f_domain, f_info, tld_info::f_tld, and is_valid().

std::string tld_object::full_domain ( ) const

This function returns the domain name and the TLD as a string.

The result includes the domain name but no sub-domains.

To get the domain name with the sub-domains, call the domain() function instead. That function returns the domain as passed to this object (set_domain() or constructor).

Exceptions
invalid_domainThis exception is raised when this function is called with an invalid TLD object. This happens whenever you create the object or call set_domain() with an invalid URI. You should call is_valid() and if false, avoid calling this function.
Returns
The fully qualified domain name.

Definition at line 241 of file tld_object.cpp.

References f_domain, f_info, tld_info::f_tld, and is_valid().

bool tld_object::is_valid ( ) const

This function checks the result and status returned by the last call to the tld() function. This object is considered valid if and only if the result is TLD_RESULT_SUCCESS and the status is TLD_STATUS_VALID. At this point, any other result returns invalid and that prevents you from checking the object further (i.e. call the tld_only() function to retrieve the TLD of the specified URI.)

Returns
true if the result and status say this TLD object is valid.

Definition at line 175 of file tld_object.cpp.

References f_info, f_result, tld_info::f_status, TLD_RESULT_SUCCESS, and TLD_STATUS_VALID.

Referenced by domain_only(), full_domain(), sub_domains(), and tld_only().

tld_result tld_object::result ( ) const

This function returns the result that the tld() command produced when called with the domain as specified in a constructor or the set_domain() functions.

Valid resutls are:

  • TLD_RESULT_SUCCESS – the URI is valid and all the tld_object functions can be called
  • TLD_RESULT_INVALID – the TLD of this URI exists but the combination used is not acceptable
  • TLD_RESULT_NULL – the domain name is the empty string or NULL
  • TLD_RESULT_NO_TLD – the domain name does not even include one period
  • TLD_RESULT_BAD_URI – URI parsing failed (i.e. two periods one after another)
  • TLD_RESULT_NOT_FOUND – this domain TLD doesn't exist
Returns
The last result of the tld() function.

Definition at line 136 of file tld_object.cpp.

References f_result.

void tld_object::set_domain ( const char *  domain_name)

This function initializes this TLD object with the specified domain name. This function accepts a null terminated C string pointer. The pointer can be set to NULL or point to an empty string in which case the constructor creates an empty TLD object. Note that an empty TLD object is considered invalid and if called some functions throw the invalid_domain exception.

Note
The string is expected to be UTF-8.
Parameters
[in]domain_nameThe domain to parse by this object.

Definition at line 93 of file tld_object.cpp.

Referenced by tld_object().

void tld_object::set_domain ( const std::string &  domain_name)

This function initializes a TLD object with the specified domain name. This function accepts standard C++ strings. The string can be empty to create an empty TLD object. Note that an empty TLD object is considered invalid and if called some functions throw the invalid_domain exception.

Note
The string is expected to be UTF-8.
Parameters
[in]domain_nameThe domain to parse by this object.

Definition at line 111 of file tld_object.cpp.

References f_domain, f_info, f_result, and tld().

tld_status tld_object::status ( ) const

This function returns the status that the last tld() call generated. status() along with result() are used to determine whether a call to the TLD succeeded or not. See the is_valid() function too.

This function can be used to know why a domain name failed when parsed by the tld() function.

  • TLD_STATUS_VALID – This URI is valid and can be queried further.
  • TLD_STATUS_PROPOSED – This TLD was proposed but is not yet in used.
  • TLD_STATUS_DEPRECATED – This TLD was used and was deprecated.
  • TLD_STATUS_UNUSED – This TLD is simply not used.
  • TLD_STATUS_RESERVED – This TLD is currently reserved.
  • TLD_STATUS_INFRASTRUCTURE – This TLD represents an infrastructure object (.arpa)
  • TLD_STATUS_UNDEFINED – The status is undefined if the TLD cannot be found.
Returns
The status generated by the last tld() function call.

Definition at line 159 of file tld_object.cpp.

References f_info, and tld_info::f_status.

std::string tld_object::sub_domains ( ) const

This function returns the sub-domains found in the URI. This may be the empty string.

Exceptions
invalid_domainThis exception is raised when this function is called with an invalid TLD object. This happens whenever you create the object or call set_domain() with an invalid URI. You should call is_valid() and if false, avoid calling this function.
Returns
All the sub-domains found in the URI.

Definition at line 206 of file tld_object.cpp.

References f_domain, f_info, tld_info::f_tld, and is_valid().

std::string tld_object::tld_only ( ) const

This function returns the TLD part of the URI specified in the constructor or the set_domain() function.

The TLD is the part that represents a country, a region, a general TLD, etc. Generic TLDs have one period (.com, .info,) but in general you must expect TLDs with several period characters (.ca.us, .indiana.museum, .yawatahama.ehime.jp).

Exceptions
invalid_domainThis exception is raised when this function is called with an invalid TLD object. This happens whenever you create the object or call set_domain() with an invalid URI. You should call is_valid() and if false, avoid calling this function.
Returns
the TLD part of the URI specified in this TLD object.

Definition at line 295 of file tld_object.cpp.

References f_info, tld_info::f_tld, and is_valid().

Member Data Documentation

tld_object::f_domain = std::string()
private

This variable holds the original domain (URI) as passed to the tld_object constructor or set_domain() function.

You can retrieve that value with the domain() function. The tld_object never modifies that string.

Note that it can be an empty string.

See also
tld_object()
set_domain()
domain()

Definition at line 176 of file tld.h.

Referenced by domain(), domain_only(), full_domain(), set_domain(), and sub_domains().

tld_object::f_info = tld_info()
private

This variable holds the information as defined by a call to the tld() function. It holds information whether or not the domain is valid, empty, etc.

The structure gets reinitialized each time a call to set_domain() is made and those values are considered cached.

Definition at line 177 of file tld.h.

Referenced by category(), country(), domain_only(), full_domain(), is_valid(), set_domain(), status(), sub_domains(), and tld_only().

tld_object::f_result = TLD_RESULT_INVALID
private

This variable caches the result of the last tld() call with the URI as defined in the f_domain variable. The f_info also corresponds to this f_result.

The result is always initialized to a value or another by constructors and set_domain() methods.

Definition at line 178 of file tld.h.

Referenced by is_valid(), result(), and set_domain().


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_object.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