This rhostname class provides an object-oriented object that represents an internet hostname. More...

Collaboration diagram for randolf::rhostname:

Public Member Functions
	rhostname () noexcept
	Instantiate an empty rhostname that doesn't qualify as a properly-formatted hostname (because the minimum length of a valid hostname is 1 character). More...

	rhostname (const char *hostname, const size_t len=0, const int flags=rlabel::HOSTNAME_DEFAULT)
	Instantiate an rhostname. More...

	rhostname (const std::string hostname, const int flags=rlabel::HOSTNAME_DEFAULT)
	Instantiate an rhostname. More...

rhostname *	clear ()
	Clear this rhostname's underlying hostname and reset all states. More...

const bool	is_fqdn () noexcept
	Find out whether this hostname is an FQDN (it has a final dot). More...

rhostname *	is_fqdn (const bool mode) noexcept
	Specify whether this hostname is an FQDN (has a final dot). More...

const bool	is_utf8 () noexcept
	Find out whether this hostname is an internationalized internet domain name (it has at least one label that has at least one UTF8/punycode character). More...

std::string	label (const int index=0, const int flags=rlabel::HOSTNAME_DEFAULT)
	Extract a specific label from the underlying hostname. More...

uint	labels ()
	Find out how many labels the underlying hostname is comprised of. More...

rhostname *	set (const char *hostname, size_t len=0, const int flags=rlabel::HOSTNAME_DEFAULT)
	Replace this rhostname's underlying hostname with a new hostname. More...

rhostname *	set (const std::string hostname, const int flags=rlabel::HOSTNAME_DEFAULT)
	Replace this rhostname's underlying hostname with a new hostname. More...

std::string	to_dns_rr ()
	Convert the underlying hostname to a DNS RR and return it as an std::string. More...

std::string	to_string (const int flags=rlabel::HOSTNAME_DEFAULT) noexcept
	Return as an `std::string` the hostname that this `rhostname` represents. More...

std::string	to_utf8 ()
	Convert the underlying hostname to UTF-8 and return it as an std::string. More...

std::string	to_xn ()
	Convert the underlying hostname to punycode and return it as an std::string. More...

Detailed Description

This rhostname class provides an object-oriented object that represents an internet hostname.

Features

Some of the key features are:

constructors with sensible defaults help to simplify coding
documentation includes code samples (with #include lines as needed)
thread-safety is noted where it is absolutely available (or where some caution is warranted)
can handle ASCIIZ (C-strings) without needing to specify string length
can handle std::string (which tracks its own string length)

Use case

Validation of the format of a hostname from a variety of angles is helpful in ensuring that hostnames received from elsewhere comply with internet standards.

Background

I created this class to make it easier to write internet server daemons. I also use it in my rmailaddr class to handle the domain-part.

Getting started

Author: Randolf Richardson

Version: 1.00

History: 2023-Jan-17 v1.00 Initial version

Conventions: Lower-case letter "h" is regularly used in partial example code to represent an instantiated rhostname 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/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rhostname h("www.example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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-

Parameter stacking is supported (with methods that return rhostname*); in this example, notice that semicolons (";") and "h." 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/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rhostname h("www.example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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

◆ rhostname() [1/3]

randolf::rhostname::rhostname ( )

inlinenoexcept

Instantiate an empty rhostname that doesn't qualify as a properly-formatted hostname (because the minimum length of a valid hostname is 1 character).

Instantiating an empty rhostname 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/rhostname>
 
randolf::rhostname h; //   <-- Empty rhostname initialization (no exceptions)
 
int main(int argc, char *argv[]) {
  try {
    h.set("www.example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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-

See also: hostname

◆ rhostname() [2/3]

randolf::rhostname::rhostname	(	const std::string	hostname,
		const int	flags = `rlabel::HOSTNAME_DEFAULT`
	)

inline

Instantiate an rhostname.

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rhostname h("www.example.com");
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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_argument	If the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_range	if any DNS RR formatted label's size would require reaching beyond the end of the hostname provided (this is called a buffer overrun, which is a potential security risk that can also cause a segmentation fault)

See also: set()

Parameters

hostname	The hostname as a std::string object
flags	rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional) rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)

◆ rhostname() [3/3]

randolf::rhostname::rhostname	(	const char *	hostname,
		const size_t	len = `0`,
		const int	flags = `rlabel::HOSTNAME_DEFAULT`
	)

inline

Instantiate an rhostname.

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    char[] example = "www.example.com";
    randolf::rhostname h(example, 15);
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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_argument	If the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_range	if any DNS RR formatted label's size would require reaching beyond the end of the hostname provided (this is called a buffer overrun, which is a potential security risk that can also cause a segmentation fault)

See also: set()

Parameters

hostname	The hostname as a char* array
len	Length of hostname string (0 = ASCIIZ string)
flags	rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional) rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)

Member Function Documentation

◆ clear()

rhostname* randolf::rhostname::clear ( )

inline

Clear this rhostname's underlying hostname and reset all states.

Returns: The same rhostname object so as to facilitate stacking

◆ is_fqdn() [1/2]

const bool randolf::rhostname::is_fqdn ( )

inlinenoexcept

Find out whether this hostname is an FQDN (it has a final dot).

Threads: This method is thread-safe.

Returns: TRUE = hostname is an FQDN; FALSE = hostanem is not an FQDN

◆ is_fqdn() [2/2]

rhostname* randolf::rhostname::is_fqdn ( const bool mode )

inlinenoexcept

Specify whether this hostname is an FQDN (has a final dot).

Threads: This method is thread-safe.

Returns: The same rhostname object so as to facilitate stacking

Parameters

mode	TRUE = ensure this rhostname is an FQDN (has a final dot) FALSE = ensure this rhostname is not an FQDN (does not have a final dot)

◆ is_utf8()

const bool randolf::rhostname::is_utf8 ( )

inlinenoexcept

Find out whether this hostname is an internationalized internet domain name (it has at least one label that has at least one UTF8/punycode character).

Threads: This method is thread-safe.

Returns: TRUE = hostname is an internationalized internet domain name; FALSE = hostanem is not an internationalized internet domain name

◆ label()

std::string randolf::rhostname::label	(	const int	index = `0`,
		const int	flags = `rlabel::HOSTNAME_DEFAULT`
	)

inline

Extract a specific label from the underlying hostname.

The index parameter begins at 0 for the first label. If index is a negative integer, the counting begins at -1 for the last label.

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rhostname h("www.example.com", 15);
    std::cout << "Top level: " << h.label(-1) << std::endl;
    // Output will be:  Top level: com
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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::out_of_range if index is out of range (this is the exception that the std::vector::at method throws)

Returns: The specific label extracted from the hostname that this rhostname represents

See also: set()

Parameters

index	Which label to extract, with the first label beginning at index 0 (a negative index value starts from the end with -1 as the last label)
flags	rlabel::HOSTNAME_WITHOUT_EXCEPTIONS returns an empty `std::string` (`""`) instead of an exception being thrown rlabel::HOSTNAME_DNS_RR Convert label to DNS RR format rlabel::HOSTNAME_UTF8 Convert label to raw UTF-8 format (optional) rlabel::HOSTNAME_XN Convert label to punycode format (optional)

◆ labels()

uint randolf::rhostname::labels ( )

inline

Find out how many labels the underlying hostname is comprised of.

Returns: Number of labels

◆ set() [1/2]

rhostname* randolf::rhostname::set	(	const std::string	hostname,
		const int	flags = `rlabel::HOSTNAME_DEFAULT`
	)

inline

Replace this rhostname's underlying hostname with a new hostname.

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    char[] example = "www.example.com";
    randolf::rhostname h(example, 15);
    h.set("mail.example.net");
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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_argument	If the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_range	if any DNS RR formatted label's size would require reaching beyond the end of the hostname provided (this is called a buffer overrun, which is a potential security risk that can also cause a segmentation fault)

Returns: The same rhostname object so as to facilitate stacking

See also: rhostname()

Parameters

hostname	The hostname as a std::string object
flags	rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional) rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)

◆ set() [2/2]

rhostname* randolf::rhostname::set	(	const char *	hostname,
		size_t	len = `0`,
		const int	flags = `rlabel::HOSTNAME_DEFAULT`
	)

inline

Replace this rhostname's underlying hostname with a new hostname.

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rhostname h("www.example.com", 15);
    h.set("mail.example.net");
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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_argument	If the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_range	if any DNS RR formatted label's size would require reaching beyond the end of the hostname provided (this is called a buffer overrun, which is a potential security risk that can also cause a segmentation fault)

Returns: The same rhostname object so as to facilitate stacking

See also: set()

Parameters

hostname	The hostname as a char* array
len	Length of hostname string (0 = ASCIIZ string)
flags	rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional) rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)

◆ to_dns_rr()

std::string randolf::rhostname::to_dns_rr ( )

inline

Convert the underlying hostname to a DNS RR and return it as an std::string.

Returns: A new std::string with the expected data

◆ to_string()

std::string randolf::rhostname::to_string ( const int flags = rlabel::HOSTNAME_DEFAULT )

inlinenoexcept

Return as an std::string the hostname that this rhostname represents.

Examples

#include <iostream>  // std::cout, std::cerr, std::endl, etc.
#include <stdexcept> // std::invalid_argument exception
 
#include <randolf/rhostname>
 
int main(int argc, char *argv[]) {
  try {
    randolf::rhostname h("www.example.com", 15);
    std::cout << "Hostname: " << h.to_string() << std::endl;
  } catch (const std::invalid_argument e) {
    std::cerr << "Hostname 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-

Returns: The hostname that this rhostname represents

See also: set()

Parameters

flags rlabel::HOSTNAME_FQDN_OPT includes the trailing period in the resulting std::string if is_fqdn is TRUE
rlabel::HOSTNAME_DNS_RR Convert all labels from DNS RR format
rlabel::HOSTNAME_UTF8 Convert all labels to raw UTF-8 format (optional)
rlabel::HOSTNAME_XN Convert all labels to punycode format (optional)

◆ to_utf8()

std::string randolf::rhostname::to_utf8 ( )

inline

Convert the underlying hostname to UTF-8 and return it as an std::string.

Returns: A new std::string with the expected data

◆ to_xn()

std::string randolf::rhostname::to_xn ( )

inline

Convert the underlying hostname to punycode and return it as an std::string.

Returns: A new std::string with the expected data

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

randolf/rhostname

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ rhostname() [1/3]

◆ rhostname() [2/3]

◆ rhostname() [3/3]

Member Function Documentation

◆ clear()

◆ is_fqdn() [1/2]

◆ is_fqdn() [2/2]

◆ is_utf8()

◆ label()

◆ labels()

◆ set() [1/2]

◆ set() [2/2]

◆ to_dns_rr()

◆ to_string()

◆ to_utf8()

◆ to_xn()