//
//  File:   hzUrl.h
//
//  Legal Notice: This file is part of the HadronZoo C++ Class Library.
//
//  Copyright 2025 HadronZoo Project (http://www.hadronzoo.com)
//
//  The HadronZoo C++ Class Library is free software: You can redistribute it, and/or modify it under the terms of the GNU Lesser General Public License, as published by the Free
//  Software Foundation, either version 3 of the License, or any later version.
//
//  The HadronZoo C++ Class Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
//  A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
//
//  You should have received a copy of the GNU Lesser General Public License along with the HadronZoo C++ Class Library. If not, see http://www.gnu.org/licenses.
//

#ifndef hzUrl_h
#define hzUrl_h

//  Other Includes
#include "hzBasedefs.h"
#include "hzString.h"

/*
**  Universal Resource Locator (URL)
*/

class   hzUrl
{
    //  Category:   Data
    //
    //  hzUrl holds a URL (Universal Resource Locator) value.
    //
    //  For the avoidance of confusion, a URL is not the same as a URI (Universal Resource Identifier). URIs identify resources in a broader sense and can identify both offline and
    //  online resources. URLs locate resources online and specify the exact location. Thus, all URLs are a URI but not all URIs are URLs.
    //
    //  HadronZoo does not have a URI data type. The anticipation being that only URLs would be useful in webapps.
    //
    //  URL values have the following parts:-
    //
    //      - Protocol  Optional e.g. https://. If omitted the protocol is taken as https://, or http:// if the website in question does not support HTTPS
    //      - Domain    Compulsory e.g. www.hadronzoo.com. This can be specified as an IP address.
    //      - Port      Optional, e.g. ':8434'. Use is rare and the port is only needed if it differs from the standard port used by the protocol.
    //      - Resource  Optional, e.g. /contacts. If the resource is not stated, the website homepage is assumed.
    //
    //  To qualify as a URL, a string only needs to contain the domain. Note that the reource part can be complex. It need not be a simple set of one or more strings separated by a
    //  forward slash representing 'directories' relative to the root for the domain. The resource can go on to include additional qualifiers, consisting of one or more name-values
    //  pairs delimited by the query character. For this reason industy standards for URL maximum size, vary around the 2,000 mark.

    uint32_t    m_addr ;        //  Address of data and control space

public:
    //  Set methods (and validate). These accept both the standard forms and the filename form.
    void    Clear       (void) ;
    hzUrl&  SetValue    (const hzString domain, const hzString resource, bool secure = false, uint32_t port = 0) ;
    hzUrl&  operator=   (const char* cpStr) ;
    hzUrl&  operator=   (const hzString& S) ;
    hzUrl&  operator=   (const hzUrl& E) ;

    //  Constructors
    hzUrl   (void)                  { m_addr = 0 ; }
    hzUrl   (const hzUrl& op)       { m_addr = 0 ; operator=(op) ; }
    hzUrl   (const char* cpUrl)     { m_addr = 0 ; operator=(cpUrl) ; }
    hzUrl   (const hzString& url)   { m_addr = 0 ; operator=(url) ; }

    //  Destructors
    ~hzUrl  (void)  { Clear() ; }

    //  Internal use only
    uint32_t    _int_addr   (void) const    { return m_addr ; }
    void        _int_set    (uint32_t addr) { m_addr = addr ; }
    void        _int_clr    (void)          { m_addr = 0 ; }
    void        _inc_copy   (void) const ;
    void        _dec_copy   (void) const ;
    bool        valid       (void) const ;

    //  Get functions
    uint32_t    Length  (void) const ;  //  Return total length of URL (including the http:// or https:// sequence)
    uint32_t    Port    (void) const ;  //  Return port number
    bool        IsSSL   (void) const ;  //  Does the URL require SSL?

    //  Get value in a form suitable for a filename (for storage)
    hzString    Filename    (void) const ;

    //  Get part or whole value (not available in direct text due to internal format)
    hzString    Whole       (void) const ;
    hzString    Domain      (void) const ;
    hzString    Resource    (void) const ;

    //  Compare Operators (note that the domain is compared first)
    bool    operator==  (const hzUrl& E) const ;
    bool    operator<   (const hzUrl& E) const ;
    bool    operator<=  (const hzUrl& E) const ;
    bool    operator>   (const hzUrl& E) const ;
    bool    operator>=  (const hzUrl& E) const ;

    //  String compares
    bool    operator==  (const char* cpStr) const ;
    bool    operator!=  (const char* cpStr) const ;
    bool    operator==  (const hzString& S) const ;
    bool    operator!=  (const hzString& S) const ;

    //  Casting Operators
    bool        operator!   (void) const    { return m_addr ? false : true ; }
    const char* operator*   (void) const ;
    operator const char*    (void) const ;

    //  Friend operator functions
    friend  std::ostream&   operator<<  (std::ostream& os, const hzUrl& url) ;
    friend  std::ostream&   operator>>  (std::ostream& os, const hzUrl& url) ;
} ;

//  Convienent globals always at null
extern  const   hzUrl   _hz_null_hzUrl ;        //  Null URL

#endif  //  hzUrl_h