====== TerraLib.Core: URI ======

The class **the::core::URI** provides support for handling URIs (uniform resource identifier) that is a string used to identify or name a resource on the Internet.

===== API =====

==== C++ ====

The API for URL manipulation in TerraLib is defined by the **URI** class, shown below:

<code cpp>
namespace te
{
  namespace core
  {
    /*!
      \class URI

      \brief A class for representing an Uniform Resource Identifier (URI).
     */
    class URI
    {
      public:

        /*! \brief Default constructor. */
        URI();

        /*!
          \brief A constructor from a string.

           This constructor check the URI enconding,
           then parse it and validate.

           \param uri A string with the URI to be parsed.

           \exception URIException when the given URI isn't valid.
         */
        explicit URI(const std::string& uri);

        /*! \brief Copy constructor. */
        URI(const URI& other);

        /*! Default destructor. */
        ~URI() = default;

        /*! \brief Assingment operator. */
        URI& operator=(const URI& other);

        /*!
          \brief Retrieving the full URI

          \return Returns the complete URI.
         */
        const std::string& uri() const;

        /*!
          \brief Retrieving the scheme

          \return Returns the URI scheme.
         */
        std::string scheme() const;

        /*!
          \brief Retrieving the user information

          \return Returns the URI user information.
         */
        std::string user() const;

        /*!
          \brief Retrieving the password information

          \return Returns the URI password information.
         */
        std::string password() const;

        /*!
          \brief Retrieving the host

          \return Returns the URI host.
         */
        std::string host() const;

        /*!
          \brief Retrieving the port

          \return Returns the URI port.
         */
        std::string port() const;

        /*!
          \brief Retrieving the path

          \return Returns the URI path.
         */
        std::string path() const;

        /*!
         \brief Retrieving the query

         \return Returns the URI query.
         */
        std::string query() const;

        /*!
          \brief Retrieving the fragment

          \return Returns the URI fragment.
         */
        std::string fragment() const;

        /*!
          \brief Return if the given URI is valid or not.

         \return Returns true if the given URI is valid.
         */
        bool isValid() const;

    };

  }  // end namespace core
}    // end namespace te
</code>

===== Examples =====

Here are some examples to illustrate the use of the URI class:

<code cpp>
// TerraLib
#include <terralib/core/uri/URI.h>

// STL
#include <cassert>
#include <cstdlib>
#include <iostream>

int main(int argc, char *argv[])
{
  {
    te::core::URI uri("http://www.dpi.inpe.br/terralib5/wiki/doku.php?id=wiki:documentation:devguide#modules");

    if(!uri.isValid())
    {
      std::cout << "Uri isn't valid!" << std::endl;
      return EXIT_FAILURE;
    }

    assert(uri.scheme() == "http");
    assert(uri.user() == "");
    assert(uri.password() == "");
    assert(uri.host() == "www.dpi.inpe.br");
    assert(uri.port() == "");
    assert(uri.path() == "/terralib5/wiki/doku.php");
    assert(uri.query() == "id=wiki:documentation:devguide");
    assert(uri.fragment() == "modules");
  }

  {
    std::string address("xmpp:example-node@example.com?message;subject=Hello%20World");

    te::core::URI uri(address);

    if(!uri.isValid())
    {
      std::cout << "Uri isn't valid!" << std::endl;
      return EXIT_FAILURE;
    }

    assert(uri.scheme() == "xmpp");
    assert(uri.user() == "");
    assert(uri.password() == "");
    assert(uri.host() == "");
    assert(uri.port() == "");
    assert(uri.path() == "example-node@example.com");
    assert(uri.query() == "message;subject=Hello%20World");
    assert(uri.fragment() == "");
  }

  {
    te::core::URI uri("ftp://user:password@ftp.dpi.inpe.br:21/path/");

    if(!uri.isValid())
    {
      std::cout << "Uri isn't valid!" << std::endl;
      return EXIT_FAILURE;
    }

    assert(uri.scheme() == "ftp");
    assert(uri.user() == "user");
    assert(uri.password() == "password");
    assert(uri.host() == "ftp.dpi.inpe.br");
    assert(uri.port() == "21");
    assert(uri.path() == "/path/");
    assert(uri.query() == "");
    assert(uri.fragment() == "");
  }

  {
    te::core::URI uri("InvalidURI");

    if(uri.isValid())
    {
      std::cout << "Uri isn't valid!" << std::endl;
      return EXIT_FAILURE;
    }
  }

  return EXIT_SUCCESS;
}
</code>

===== Additional References =====

  * [[https://pt.wikipedia.org/wiki/URI | URI]]