randolf.ca  1.00
Randolf Richardson's C++ classes
Loading...
Searching...
No Matches
randolf::rhostname Class Reference

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

#include <rhostname>

+ 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).
 
 rhostname (const char *hostname, const size_t len=0, const int flags=rlabel::HOSTNAME_DEFAULT)
 Instantiate an rhostname.
 
 rhostname (const std::string hostname, const int flags=rlabel::HOSTNAME_DEFAULT)
 Instantiate an rhostname.
 
rhostnameclear ()
 Clear this rhostname's underlying hostname and reset all states.
 
const bool is_fqdn () noexcept
 Find out whether this hostname is an FQDN (it has a final dot).
 
rhostnameis_fqdn (const bool mode) noexcept
 Specify whether this hostname is an FQDN (has a final dot).
 
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).
 
std::string label (const int index=0, const int flags=rlabel::HOSTNAME_DEFAULT)
 Extract a specific label from the underlying hostname.
 
uint labels ()
 Find out how many labels the underlying hostname is comprised of.
 
rhostnameset (const char *hostname, size_t len=0, const int flags=rlabel::HOSTNAME_DEFAULT)
 Replace this rhostname's underlying hostname with a new hostname.
 
rhostnameset (const std::string hostname, const int flags=rlabel::HOSTNAME_DEFAULT)
 Replace this rhostname's underlying hostname with a new hostname.
 
std::string to_dns_rr ()
 Convert the underlying hostname to a DNS RR and return it as an std::string.
 
std::string to_string (const int flags=rlabel::HOSTNAME_DEFAULT) noexcept
 Return as an std::string the hostname that this rhostname represents.
 
std::string to_utf8 ()
 Convert the underlying hostname to UTF-8 and return it as an std::string.
 
std::string to_xn ()
 Convert the underlying hostname to punycode and return it as an std::string.
 

Detailed Description

This rhostname class provides an object-oriented 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 when extracting 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-
This rhostname class provides an object-oriented internet hostname.
Definition rhostname:109

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-
rhostname * set(const std::string hostname, const int flags=rlabel::HOSTNAME_DEFAULT)
Replace this rhostname's underlying hostname with a new hostname.
Definition rhostname:407
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_argumentIf the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_rangeif 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
hostnameThe hostname as a std::string object
flagsrlabel::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_argumentIf the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_rangeif 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
hostnameThe hostname as a char* array
lenLength of hostname string (0 = ASCIIZ string)
flagsrlabel::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
modeTRUE = 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_rangeif 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
indexWhich 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)
flagsrlabel::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_argumentIf the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_rangeif 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
hostnameThe hostname as a std::string object
flagsrlabel::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_argumentIf the hostname is improperly formatted (flags can limit or eliminate conditions for throwing this exception)
std::out_of_rangeif 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
hostnameThe hostname as a char* array
lenLength of hostname string (0 = ASCIIZ string)
flagsrlabel::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
flagsrlabel::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: