cd

KURL(3)                     Library Functions Manual                     KURL(3)



NAME
       KURL - Represents and parses a URL.


SYNOPSIS
       #include <kurl.h>

   Public Types
       enum AdjustementFlags { NoAdjustements =  0, StripFileProtocol =  1 }
       enum QueryItemsOptions { CaseInsensitiveKeys =  1 }
           Options for queryItems.

   Public Member Functions
       KURL ()
           Constructs an empty URL.
       ~KURL ()
           Destructs the KURL object.
       KURL (const  QString &url, int encoding_hint=0)
           Usual constructor, to construct from a string.
       KURL (const  char *url, int encoding_hint=0)
           Constructor taking a char * url, which is an _encoded_ representation
           of the URL, exactly like the usual constructor.
       KURL (const  QCString &url, int encoding_hint=0)
           Constructor taking a QCString url, which is an _encoded_
           representation of the URL, exactly like the usual constructor.
       KURL (const  KURL &u)
           Copy constructor.
       KURL (const  QUrl &u)
           Converts from a QUrl.
       KURL (const  KURL &_baseurl, const  QString &_rel_url, int
           encoding_hint=0)
           Constructor allowing relative URLs.
       QString protocol () const
           Returns the protocol for the URL (i.e., file, http, etc.).
       void setProtocol (const  QString &_txt)
           Sets the protocol for the URL (i.e., file, http, etc.).
       QString user () const
           Returns the decoded user name (login, user id, ...) included in the
           URL.
       void setUser (const  QString &_txt)
           Sets the user name (login, user id, ...) included in the URL.
       bool hasUser () const
           Test to see if this URL has a user name included in it.
       QString pass () const
           Returns the decoded password (corresponding to user()) included in
           the URL.
       void setPass (const  QString &_txt)
           Sets the password (corresponding to user()) included in the URL.
       bool hasPass () const
           Test to see if this URL has a password included in it.
       QString host () const
           Returns the decoded hostname included in the URL.
       void setHost (const  QString &_txt)
           Sets the hostname included in the URL.
       bool hasHost () const
           Test to see if this URL has a hostname included in it.
       unsigned short int port () const
           Returns the port number included in the URL.
       void setPort (unsigned short int _p)
           Sets the port number included in the URL.
       QString path () const
           Returns the current decoded path.
       QString path (int _trailing) const
       void setPath (const  QString &path)
           Sets the path of the URL.
       bool hasPath () const
           Test to see if this URL has a path is included in it.
       void cleanPath (bool cleanDirSeparator=true)
           Resolves '.' and '..' components in path.
       void adjustPath (int _trailing)
           Add or remove a trailing slash to/from the path.
       void setEncodedPathAndQuery (const  QString &_txt, int encoding_hint=0)
           This is useful for HTTP.
       void setEncodedPath (const  QString &_txt, int encoding_hint=0)
           Sets the (already encoded) path.
       QString encodedPathAndQuery (int _trailing=0, bool _no_empty_path=false,
           int encoding_hint=0) const
           Returns the encoded path and the query.
       void setQuery (const  QString &_txt, int encoding_hint=0)
       QString query () const
           Returns the query of the URL.
       QString ref () const
           The reference is never decoded automatically.
       void setRef (const  QString &_txt)
           Sets the reference part (everything after '#').
       bool hasRef () const
           Checks whether the URL has a reference part.
       QString htmlRef () const
           Returns the HTML reference (the part of the URL after '#').
       QString encodedHtmlRef () const
           Returns the HTML reference (the part of the URL after '#') in encoded
           form.
       void setHTMLRef (const  QString &_ref)
           Sets the HTML-style reference.
       bool hasHTMLRef () const
           Checks whether there is a HTML reference.
       bool isValid () const
           Checks whether the URL is well formed.
       bool isMalformed () const
           This class or method is obsolete, it is provided for compatibility
           only.
       bool isLocalFile () const
           Checks whether the file is local.
       void setFileEncoding (const  QString &encoding)
           Adds encoding information to url by adding a 'charset' parameter.
       QString fileEncoding () const
           Returns encoding information from url, the content of the 'charset'
           parameter.
       bool hasSubURL () const
           Checks whether the URL has any sub URLs.
       void addPath (const  QString &_txt)
           Adds to the current path.
       QString queryItem (const  QString &_item) const
           Returns the value of a certain query item.
       QMap< QString, QString > queryItems (int options=0) const
           Returns the list of query items as a map mapping keys to values.
       void addQueryItem (const  QString &_item, const  QString &_value, int
           encoding_hint=0)
           Add an additional query item.
       void removeQueryItem (const  QString &_item)
           Remove an item from the query.
       void setFileName (const  QString &_txt)
           Sets the filename of the path.
       QString fileName (bool _ignore_trailing_slash_in_path=true) const
           Returns the filename of the path.
       QString directory (bool _strip_trailing_slash_from_result=true, bool
           _ignore_trailing_slash_in_path=true) const
           Returns the directory of the path.
       bool cd (const  QString &_dir)
           Changes the directory by descending into the given directory.
       QString url (int _trailing=0, int encoding_hint=0) const
           Returns the URL as string.
       QString prettyURL (int _trailing=0) const
           Returns the URL as string in human-friendly format.
       QString htmlURL () const
           Returns the URL as string, escaped for HTML.
       QString prettyURL (int _trailing, AdjustementFlags _flags) const
           Returns the URL as string, escaped for HTML.
       bool isEmpty () const
           Test to see if the KURL is empty.
       KURL upURL () const
           This function is useful to implement the 'Up' button in a file
           manager for example.
       KURL & operator= (const  KURL &_u)
       KURL & operator= (const  QString &_url)
       KURL & operator= (const  char *_url)
       KURL & operator= (const  QUrl &u)
       bool operator== (const  KURL &_u) const
       bool operator== (const  QString &_u) const
       bool operator!= (const  KURL &_u) const
       bool operator!= (const  QString &_u) const
       bool cmp (const  KURL &u, bool ignore_trailing=false) const
           The same as equals(), just with a less obvious name.
       bool equals (const  KURL &u, bool ignore_trailing=false) const
           Compares this url with u.
       bool isParentOf (const  KURL &u) const
           Checks whether the given URL is parent of this URL.
       QString filename (bool _ignore_trailing_slash_in_path=true) const

   Static Public Member Functions
       List split (const  QString &_url)
           Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase A
           URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
           http://www.kde.org and tar:/kde/README.html#ref1.
       List split (const  KURL &_url)
           Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase A
           URL like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
           http://www.kde.org and tar:/kde/README.html#ref1.
       KURL join (const  List &_list)
           Reverses split().
       KURL fromPathOrURL (const  QString &text)
           Creates a KURL object from a QString representing either an absolute
           path or a real URL.
       QString encode_string (const  QString &str, int encoding_hint=0)
           Convenience function.
       QString encode_string_no_slash (const  QString &str, int encoding_hint=0)
           Convenience function.
       QString decode_string (const  QString &str, int encoding_hint=0)
           Convenience function.
       bool isRelativeURL (const  QString &_url)
           Convenience function.

   Protected Member Functions
       void reset ()
       void parse (const  QString &_url, int encoding_hint=0)

   Friends
       QDataStream & operator<< (QDataStream &s, const  KURL &a)
       QDataStream & operator>> (QDataStream &s, KURL &a)

Detailed Description
       Represents and parses a URL.

       A prototypical URL looks like:

          protocol:/user:password:port/path/to/file.ext#reference


       KURL has some restrictions regarding the path encoding. KURL works internally with the decoded path and and encoded query. For example,

        http://localhost/cgi-bin/test%20me.pl?cmd=Hello%20you


        would result in a decoded path '/cgi-bin/test me.pl' and in the encoded query '?cmd=Hello%20you'. Since path is internally always encoded you may not use '%00' in the path, although this is OK for the query.

       Author:
           Torben Weis <weis@kde.org>

       Definition at line 52 of file kurl.h.

Member Enumeration Documentation
   enum KURL::QueryItemsOptions
       Options for queryItems. Currently, only one option is defined:

       Parameters:
           CaseInsensitiveKeys normalize query keys to lowercase.

       Since:
           3.1

       Definition at line 486 of file kurl.h.

Constructor & Destructor Documentation
   KURL::KURL ()
       Constructs an empty URL. Definition at line 400 of file kurl.cpp.

       Referenced by fromPathOrURL(), join(), KURL::List::List(), split(), and
       upURL().

   KURL::~KURL ()
       Destructs the KURL object. Definition at line 405 of file kurl.cpp.

   KURL::KURL (const QString & url, int encoding_hint = 0)
       Usual constructor, to construct from a string. Parameters:
           url A URL, not a filename. If the URL does not have a protocol part,
           'file:' is assumed. It is dangerous to feed unix filenames into this
           function, this will work most of the time but not always. For example
           '/home/Torben%20Weis' will be considered a URL pointing to the file
           '/home/Torben Weis' instead of to the file '/home/Torben%20Weis'.
           This means that if you have a usual UNIX like path you should not use
           this constructor. Instead create an empty url and set the path by
           using setPath().
           encoding_hint MIB of original encoding of URL.

       See also:
           QTextCodec::mibEnum()

       Definition at line 410 of file kurl.cpp.

   KURL::KURL (const char * url, int encoding_hint = 0)
       Constructor taking a char * url, which is an _encoded_ representation of
       the URL, exactly like the usual constructor. This is useful when then
       URL, in its encoded form, is strictly ascii.

       Parameters:
           url A encoded URL. If the URL does not have a protocol part, 'file:'
           is assumed.
           encoding_hint MIB of original encoding of URL.

       See also:
           QTextCodec::mibEnum()

       Definition at line 416 of file kurl.cpp.

       References QString::fromLatin1().

   KURL::KURL (const QCString & url, int encoding_hint = 0)
       Constructor taking a QCString url, which is an _encoded_ representation
       of the URL, exactly like the usual constructor. This is useful when then
       URL, in its encoded form, is strictly ascii.

       Parameters:
           url A encoded URL. If the URL does not have a protocol part, 'file:'
           is assumed.
           encoding_hint MIB of original encoding of URL.

       See also:
           QTextCodec::mibEnum()

       Definition at line 422 of file kurl.cpp.

       References QString::fromLatin1().

   KURL::KURL (const KURL & u)
       Copy constructor. Parameters:
           u the KURL to copy

       Definition at line 428 of file kurl.cpp.

   KURL::KURL (const QUrl & u)
       Converts from a QUrl. Parameters:
           u the QUrl

       Definition at line 463 of file kurl.cpp.

   KURL::KURL (const KURL & _baseurl, const QString & _rel_url, int
       encoding_hint = 0)
       Constructor allowing relative URLs. Parameters:
           _baseurl The base url.
           _rel_url A relative or absolute URL. If this is an absolute URL then
           _baseurl will be ignored. If this is a relative URL it will be
           combined with _baseurl. Note that _rel_url should be encoded too, in
           any case. So do NOT pass a path here (use setPath or addPath
           instead).
           encoding_hint MIB of original encoding of URL.

       See also:
           QTextCodec::mibEnum()

       Definition at line 469 of file kurl.cpp.

       References cleanPath(), QString::find(), QString::findRev(),
       QString::isEmpty(), QString::isNull(), isRelativeURL(),
       QString::length(), m_strHost, m_strPass, m_strProtocol, m_strUser, ref(),
       setHTMLRef(), QString::truncate(), and url().

Member Function Documentation
   QString KURL::protocol () const [inline]
       Returns the protocol for the URL (i.e., file, http, etc.). Returns:
           the protocol of the URL, does not include the colon. If the URL is
           malformed, QString::null will be returned.

       Definition at line 168 of file kurl.h.

   void KURL::setProtocol (const QString & _txt)
       Sets the protocol for the URL (i.e., file, http, etc.). Parameters:
           _txt the new protocol of the URL (without colon)

       Definition at line 1643 of file kurl.cpp.

   QString KURL::user () const [inline]
       Returns the decoded user name (login, user id, ...) included in the URL.
       Returns:
           the user name or QString::null if there is no user name

       Definition at line 179 of file kurl.h.

   void KURL::setUser (const QString & _txt)
       Sets the user name (login, user id, ...) included in the URL. Special
       characters in the user name will appear encoded in the URL.

       Parameters:
           _txt the name of the user or QString::null to remove the user

       Definition at line 1650 of file kurl.cpp.

   bool KURL::hasUser () const [inline]
       Test to see if this URL has a user name included in it. Returns:
           true if the URL has an non-empty user name

       Definition at line 191 of file kurl.h.

       References QString::isEmpty().

       Referenced by prettyURL(), and url().

   QString KURL::pass () const [inline]
       Returns the decoded password (corresponding to user()) included in the
       URL. Returns:
           the password or QString::null if it does not exist

       Definition at line 197 of file kurl.h.

   void KURL::setPass (const QString & _txt)
       Sets the password (corresponding to user()) included in the URL. Special
       characters in the password will appear encoded in the URL. Note that a
       password can only appear in a URL string if you also set a user.

       Parameters:
           _txt the password to set or QString::null to remove the password

       See also:
           setUser

           hasUser

       Definition at line 1656 of file kurl.cpp.

   bool KURL::hasPass () const [inline]
       Test to see if this URL has a password included in it. Returns:
           true if there is a non-empty password set

       Definition at line 213 of file kurl.h.

       References QString::isEmpty().

       Referenced by url().

   QString KURL::host () const [inline]
       Returns the decoded hostname included in the URL. Returns:
           the name of the host or QString::null if no host is set

       Definition at line 219 of file kurl.h.

   void KURL::setHost (const QString & _txt)
       Sets the hostname included in the URL. Special characters in the hostname
       will appear encoded in the URL.

       Parameters:
           _txt the new name of the host or QString::null to remove the host

       Definition at line 1662 of file kurl.cpp.

   bool KURL::hasHost () const [inline]
       Test to see if this URL has a hostname included in it. Returns:
           true if the URL has a host

       Definition at line 231 of file kurl.h.

       References QString::isEmpty().

       Referenced by prettyURL(), and url().

   unsigned short int KURL::port () const [inline]
       Returns the port number included in the URL. Returns:
           the port number. If there is no port number specified in the URL,
           returns 0.

       Definition at line 238 of file kurl.h.

   void KURL::setPort (unsigned short int _p)
       Sets the port number included in the URL. Parameters:
           _p the new port number or 0 to have no port number

       Definition at line 1668 of file kurl.cpp.

   QString KURL::path () const [inline]
       Returns the current decoded path. This does not include the query.

       Returns:
           the path of the URL (without query), or QString::null if no path set.

       Definition at line 250 of file kurl.h.

       Referenced by KApplication::authorizeURLAction(), cd(),
       encodedPathAndQuery(), equals(), fileName(),
       KApplication::invokeMailer(), isParentOf(), path(), setFileName(), and
       upURL().

   QString KURL::path (int _trailing) const
       Parameters:
           _trailing May be ( -1, 0 +1 ). -1 strips a trailing '/', +1 adds a
           trailing '/' if there is none yet and 0 returns the path unchanged.
           If the URL has no path, then no '/' is added anyway. And on the other
           side: If the path is '/', then this character won't be stripped.
           Reason: 'ftp://weis@host' means something completely different than
           'ftp://weis@host/'. So adding or stripping the '/' would really alter
           the URL, while 'ftp://host/path' and 'ftp://host/path/' mean the same
           directory.

       Returns:
           The current decoded path. This does not include the query. Can be
           QString::null if no path is set.

       Definition at line 1137 of file kurl.cpp.

       References path().

   void KURL::setPath (const QString & path)
       Sets the path of the URL. The query is not changed by this function.

       Parameters:
           path The new path. This is considered to be decoded. This means: 3f
           does not become decoded and the ? does not indicate the start of the
           query part. Can be QString::null to delete the path.

       Definition at line 1673 of file kurl.cpp.

       References QString::isEmpty(), and isEmpty().

       Referenced by KApplication::authorizeURLAction(), cd(), fromPathOrURL(),
       KCmdLineArgs::makeURL(), KConfigINIBackEnd::parseConfigFiles(),
       KDesktopFile::readURL(), setFileName(), and KConfigINIBackEnd::sync().

   bool KURL::hasPath () const [inline]
       Test to see if this URL has a path is included in it. Returns:
           true if there is a path

       Definition at line 281 of file kurl.h.

       References QString::isEmpty().

   void KURL::cleanPath (bool cleanDirSeparator = true)
       Resolves '.' and '..' components in path. Some servers seem not to like
       the removal of extra '/' even though it is against the specification in
       RFC 2396.

       Parameters:
           cleanDirSeparator if true, occurrances of consecutive directory
           separators (e.g. /foo//bar) are cleaned up as well.

       Definition at line 1038 of file kurl.cpp.

       Referenced by KURL(), KCmdLineArgs::makeURL(), and setFileName().

   void KURL::adjustPath (int _trailing)
       Add or remove a trailing slash to/from the path. Parameters:
           _trailing May be ( -1, 0 +1 ). -1 strips a trailing '/', +1 adds a
           trailing '/' if there is none yet and 0 returns the path unchanged.
           If the URL has no path, then no '/' is added anyway. And on the other
           side: If the path is '/', then this character won't be stripped.
           Reason: 'ftp://weis@host' means something completely different than
           'ftp://weis@host/'. So adding or stripping the '/' would really alter
           the URL, while 'ftp://host/path' and 'ftp://host/path/' mean the same
           directory.

       Definition at line 1075 of file kurl.cpp.

       References QString::isEmpty().

   void KURL::setEncodedPathAndQuery (const QString & _txt, int encoding_hint =
       0)
       This is useful for HTTP. It looks first for '?' and decodes then. The
       encoded path is the concatenation of the current path and the query.

       Parameters:
           _txt the new path and query.
           encoding_hint MIB of original encoding of _txt .

       See also:
           QTextCodec::mibEnum()

       Definition at line 1122 of file kurl.cpp.

       References QString::find(), QString::left(), QString::length(),
       QString::right(), setEncodedPath(), and setQuery().

   void KURL::setEncodedPath (const QString & _txt, int encoding_hint = 0)
       Sets the (already encoded) path. Parameters:
           _txt the new path
           encoding_hint MIB of original encoding of _txt .

       See also:
           QTextCodec::mibEnum()

       Definition at line 1106 of file kurl.cpp.

       References KGlobal::staticQString().

       Referenced by setEncodedPathAndQuery(), and setFileName().

   QString KURL::encodedPathAndQuery (int _trailing = 0, bool _no_empty_path =
       false, int encoding_hint = 0) const
       Returns the encoded path and the query. Parameters:
           _trailing May be ( -1, 0 +1 ). -1 strips a trailing '/', +1 adds a
           trailing '/' if there is none yet and 0 returns the path unchanged.
           If the URL has no path, then no '/' is added anyway. And on the other
           side: If the path is '/', then this character won't be stripped.
           Reason: 'ftp://weis@host' means something completely different than
           'ftp://weis@host/'. So adding or stripping the '/' would really alter
           the URL, while 'ftp://host/path' and 'ftp://host/path/' mean the same
           directory.
           _no_empty_path If set to true then an empty path is substituted by
           '/'.
           encoding_hint MIB of desired encoding of URL.

       See also:
           QTextCodec::mibEnum()

       Returns:
           The concatenation if the encoded path , '?' and the encoded query.

       Definition at line 1085 of file kurl.cpp.

       References QString::isEmpty(), QString::isNull(), and path().

       Referenced by url().

   void KURL::setQuery (const QString & _txt, int encoding_hint = 0)
       Parameters:
           _txt This is considered to be encoded. This has a good reason: The
           query may contain the 0 character.

       The query should start with a '?'. If it doesn't '?' is prepended.

       Parameters:
           encoding_hint Reserved, should be 0.

       See also:
           QTextCodec::mibEnum()

       Definition at line 1683 of file kurl.cpp.

       References QString::latin1(), QString::length(), and QString::mid().

       Referenced by setEncodedPathAndQuery(), setFileEncoding(), and upURL().

   QString KURL::query () const
       Returns the query of the URL. The query may contain the 0 character. If a
       query is present it always starts with a '?'. A single '?' means an empty
       query. An empty string means no query.

       Returns:
           The encoded query, or QString::null if there is none.

       Definition at line 1727 of file kurl.cpp.

       References QString::isNull().

       Referenced by fileEncoding(), KApplication::invokeMailer(),
       setFileEncoding(), and upURL().

   QString KURL::ref () const [inline]
       The reference is never decoded automatically. Returns:
           the undecoded reference, or QString::null if there is none

       Definition at line 366 of file kurl.h.

       Referenced by encodedHtmlRef(), htmlRef(), KURL(), and split().

   void KURL::setRef (const QString & _txt) [inline]
       Sets the reference part (everything after '#'). Parameters:
           _txt The encoded reference (or QString::null to remove it).

       Definition at line 372 of file kurl.h.

   bool KURL::hasRef () const [inline]
       Checks whether the URL has a reference part. Returns:
           true if the URL has a reference part. In a URL like
           http://www.kde.org/kdebase.tar#tar:/README it would return true, too.

       Definition at line 380 of file kurl.h.

       References QString::isNull().

       Referenced by hasHTMLRef(), prettyURL(), and url().

   QString KURL::htmlRef () const
       Returns the HTML reference (the part of the URL after '#'). Returns:
           The HTML-style reference.

       See also:
           split

           hasSubURL

           encodedHtmlRef

       Definition at line 1594 of file kurl.cpp.

       References QValueList< KURL >::begin(), hasSubURL(), ref(), and split().

   QString KURL::encodedHtmlRef () const
       Returns the HTML reference (the part of the URL after '#') in encoded
       form. Returns:
           The HTML-style reference in its original form.

       Definition at line 1605 of file kurl.cpp.

       References QValueList< KURL >::begin(), hasSubURL(), ref(), and split().

   void KURL::setHTMLRef (const QString & _ref)
       Sets the HTML-style reference. Parameters:
           _ref The new reference. This is considered to be not encoded in
           contrast to setRef(). Use QString::null to remove it.

       See also:
           htmlRef()

       Definition at line 1616 of file kurl.cpp.

       References QValueList< KURL >::begin(), hasSubURL(), join(), and split().

       Referenced by cd(), and KURL().

   bool KURL::hasHTMLRef () const
       Checks whether there is a HTML reference. Returns:
           true if the URL has an HTML-style reference.

       See also:
           htmlRef()

       Definition at line 1631 of file kurl.cpp.

       References QValueList< KURL >::begin(), hasRef(), hasSubURL(), and
       split().

   bool KURL::isValid () const [inline]
       Checks whether the URL is well formed. Returns:
           false if the URL is malformed. This function does not test whether
           sub URLs are well-formed, too.

       Definition at line 419 of file kurl.h.

       Referenced by isMalformed().

   bool KURL::isMalformed () const [inline]
       This class or method is obsolete, it is provided for compatibility only.
       Definition at line 423 of file kurl.h.

       References isValid().

       Referenced by equals(), and isParentOf().

   bool KURL::isLocalFile () const
       Checks whether the file is local. Returns:
           true if the file is a plain local file and has no filter protocols
           attached to it.

       Definition at line 1142 of file kurl.cpp.

       References hasSubURL(), QString::isEmpty(), and KGlobal::staticQString().

       Referenced by fileEncoding(), and setFileEncoding().

   void KURL::setFileEncoding (const QString & encoding)
       Adds encoding information to url by adding a 'charset' parameter. If
       there is already a charset parameter, it will be replaced.

       Parameters:
           encoding the encoding to add or QString::null to remove the encoding.

       Definition at line 1152 of file kurl.cpp.

       References decode_string(), encode_string(), QString::isEmpty(),
       isLocalFile(), QStringList::join(), QString::mid(), query(), setQuery(),
       QStringList::split(), and QString::startsWith().

   QString KURL::fileEncoding () const
       Returns encoding information from url, the content of the 'charset'
       parameter. Returns:
           An encoding suitable for QTextCodec::codecForName() or QString::null
           if not encoding was specified.

       Definition at line 1181 of file kurl.cpp.

       References decode_string(), QString::isEmpty(), isLocalFile(),
       QString::mid(), query(), QStringList::split(), and QString::startsWith().

   bool KURL::hasSubURL () const
       Checks whether the URL has any sub URLs. See split() for examples for sub
       URLs.

       Returns:
           true if the file has at least one sub URL.

       See also:
           split

       Definition at line 1206 of file kurl.cpp.

       References QString::isEmpty(), and QString::startsWith().

       Referenced by cd(), encodedHtmlRef(), hasHTMLRef(), htmlRef(),
       isLocalFile(), setHTMLRef(), split(), and upURL().

   void KURL::addPath (const QString & _txt)
       Adds to the current path. Assumes that the current path is a directory.
       _txt is appended to the current path. The function adds '/' if needed
       while concatenating. This means it does not matter whether the current
       path has a trailing '/' or not. If there is none, it becomes appended. If
       _txt has a leading '/' then this one is stripped.

       Parameters:
           _txt The text to add. It is considered to be decoded.

       Definition at line 1446 of file kurl.cpp.

       References QString::isEmpty(), QString::length(), and QString::mid().

   QString KURL::queryItem (const QString & _item) const
       Returns the value of a certain query item. Parameters:
           _item Item whose value we want

       Returns:
           the value of the given query item name or QString::null if the
           specified item does not exist.

       Definition at line 1834 of file kurl.cpp.

       References decode_string(), QString::fromLatin1(), QString::length(),
       QString::replace(), and QStringList::split().

   QMap< QString, QString > KURL::queryItems (int options = 0) const
       Returns the list of query items as a map mapping keys to values.
       Parameters:
           options any of QueryItemsOptions ored together.

       Returns:
            the map of query items or the empty map if the url has no query
           items.

       Since:
            3.1

       Definition at line 1803 of file kurl.cpp.

       References decode_string(), QString::fromLatin1(), QMap< QString, QString
       >::insert(), QString::isEmpty(), KStdAction::name(), QString::replace(),
       and QStringList::split().

   void KURL::addQueryItem (const QString & _item, const QString & _value, int
       encoding_hint = 0)
       Add an additional query item. To replace an existing query item, the item
       should first be removed with removeQueryItem()

       Parameters:
           _item Name of item to add
           _value Value of item to add
           encoding_hint MIB of encoding to use for _value.

       See also:
           QTextCodec::mibEnum()

       Definition at line 1883 of file kurl.cpp.

       References QString::isEmpty().

   void KURL::removeQueryItem (const QString & _item)
       Remove an item from the query. Parameters:
           _item Item to be removed

       Definition at line 1860 of file kurl.cpp.

       References QStringList::join(), QString::length(), and
       QStringList::split().

   void KURL::setFileName (const QString & _txt)
       Sets the filename of the path. In comparison to addPath() this function
       does not assume that the current path is a directory. This is only
       assumed if the current path ends with '/'.

       Any reference is reset.

       Parameters:
           _txt The filename to be set. It is considered to be decoded. If the
           current path ends with '/' then _txt int just appended, otherwise all
           text behind the last '/' in the current path is erased and _txt is
           appended then. It does not matter whether _txt starts with '/' or
           not.

       Definition at line 999 of file kurl.cpp.

       References cleanPath(), encode_string(), QString::findRev(),
       QString::isEmpty(), QString::mid(), path(), QString::right(),
       setEncodedPath(), setPath(), and QString::truncate().

   QString KURL::fileName (bool _ignore_trailing_slash_in_path = true) const
       Returns the filename of the path. Parameters:
           _ignore_trailing_slash_in_path This tells whether a trailing '/'
           should be ignored. This means that the function would return 'torben'
           for file:/hallo/torben/ and file:/hallo/torben. If the flag is set to
           false, then everything behind the last '/' is considered to be the
           filename.

       Returns:
           The filename of the current path. The returned string is decoded.
           Null if there is no file (and thus no path).

       Definition at line 1392 of file kurl.cpp.

       References QString::contains(), QString::findRev(), QString::isEmpty(),
       QString::left(), QString::length(), QString::mid(), and path().

   QString KURL::directory (bool _strip_trailing_slash_from_result = true, bool
       _ignore_trailing_slash_in_path = true) const
       Returns the directory of the path. Parameters:
           _strip_trailing_slash_from_result tells whether the returned result
           should end with '/' or not. If the path is empty or just '/' then
           this flag has no effect.
           _ignore_trailing_slash_in_path means that file:/hallo/torben and
           file:/hallo/torben/' would both return /hallo/ or /hallo depending on
           the other flag

       Returns:
           The directory part of the current path. Everything between the last
           and the second last '/' is returned. For example file:/hallo/torben/
           would return '/hallo/torben/' while file:/hallo/torben would return
           'hallo/'. The returned string is decoded. QString::null is returned
           when there is no path.

       Definition at line 1474 of file kurl.cpp.

       References QString::findRev(), QString::isEmpty(), and QString::left().

       Referenced by KConfigINIBackEnd::parseConfigFiles(), and
       KConfigINIBackEnd::sync().

   bool KURL::cd (const QString & _dir)
       Changes the directory by descending into the given directory. It is
       assumed the current URL represents a directory. If dir starts with a '/'
       the current URL will be 'protocol://host/dir' otherwise _dir will be
       appended to the path. _dir can be '..' This function won't strip
       protocols. That means that when you are in file:/dir/dir2/my.tgz#tar:/
       and you do cd('..') you will still be in file:/dir/dir2/my.tgz#tar:/

       Parameters:
           _dir the directory to change to

       Returns:
           true if successful

       Definition at line 1508 of file kurl.cpp.

       References hasSubURL(), QDir::homeDirPath(), QString::isEmpty(), join(),
       QValueList< KURL >::last(), QString::length(), path(), QString::right(),
       setHTMLRef(), setPath(), and split().

       Referenced by upURL().

   QString KURL::url (int _trailing = 0, int encoding_hint = 0) const
       Returns the URL as string. Returns:
           The complete URL, with all escape sequences intact, encoded in a
           given charset. This is used in particular for encoding URLs in UTF-8
           before using them in a drag and drop operation.

       Parameters:
           _trailing This may be ( -1, 0 +1 ). -1 strips a trailing '/' from the
           path, +1 adds a trailing '/' if there is none yet and 0 returns the
           path unchanged.
           encoding_hint MIB of encoding to use.

       See also:
           QTextCodec::mibEnum()

       Definition at line 1225 of file kurl.cpp.

       References encodedPathAndQuery(), QString::find(), hasHost(), hasPass(),
       hasRef(), hasUser(), QString::isEmpty(), and QString::sprintf().

       Referenced by fromPathOrURL(), join(), KURL(), KDesktopFile::readURL(),
       and split().

   QString KURL::prettyURL (int _trailing = 0) const
       Returns the URL as string in human-friendly format. Example:
       http://localhost:8080/test.cgi?test=hello world&name=fred

       Returns:
           A human readable URL, with no non-necessary encodings/escaped
           characters. Password will not be shown.

       Definition at line 1275 of file kurl.cpp.

       References QString::find(), hasHost(), hasRef(), hasUser(),
       QString::isEmpty(), QString::isNull(), and QString::sprintf().

       Referenced by htmlURL(), and prettyURL().

   QString KURL::htmlURL () const
       Returns the URL as string, escaped for HTML. Returns:
           A human readable URL, with no non-necessary encodings/escaped
           characters which is html encoded for safe inclusion in html or rich
           text. Password will not be shown.

       Definition at line 1331 of file kurl.cpp.

       References QStyleSheet::escape(), and prettyURL().

   QString KURL::prettyURL (int _trailing, AdjustementFlags _flags) const
       Returns the URL as string, escaped for HTML. Example:
       http://localhost:8080/test.cgi?test=hello world&name=fred

       Returns:
           A human readable URL, with no non-necessary encodings/escaped
           characters. Password will not be shown.

       Definition at line 1323 of file kurl.cpp.

       References prettyURL(), QString::remove(), and QString::startsWith().

   bool KURL::isEmpty () const
       Test to see if the KURL is empty. Returns:
           true if the URL is empty

       Definition at line 561 of file kurl.cpp.

       References QString::isEmpty().

       Referenced by KApplication::authorizeURLAction(), and setPath().

   KURL KURL::upURL () const
       This function is useful to implement the 'Up' button in a file manager
       for example. cd() never strips a sub-protocol. That means that if you are
       in file:/home/x.tgz#gzip:/#tar:/ and hit the up button you expect to see
       file:/home. The algorithm tries to go up on the right-most URL. If that
       is not possible it strips the right most URL. It continues stripping
       URLs.

       Returns:
           a URL that is a level higher

       Definition at line 1560 of file kurl.cpp.

       References cd(), QValueList< KURL >::count(), QValueList< KURL
       >::fromLast(), hasSubURL(), QValueList< KURL >::isEmpty(),
       QString::isEmpty(), join(), KURL(), QValueList< KURL >::last(), path(),
       query(), QValueList< KURL >::remove(), setQuery(), and split().

   bool KURL::cmp (const KURL & u, bool ignore_trailing = false) const
       The same as equals(), just with a less obvious name. Compares this url
       with u.

       Parameters:
           ignore_trailing set to true to ignore trailing '/' characters.

       Returns:
           true if both urls are the same

       See also:
           operator==. This function should be used if you want to ignore
           trailing '/' characters. This class or method is obsolete, it is
           provided for compatibility only.

       Definition at line 935 of file kurl.cpp.

       References equals().

   bool KURL::equals (const KURL & u, bool ignore_trailing = false) const
       Compares this url with u. Parameters:
           ignore_trailing set to true to ignore trailing '/' characters.

       Returns:
           true if both urls are the same

       See also:
           operator==. This function should be used if you want to ignore
           trailing '/' characters.

       Since:
           3.1

       Definition at line 940 of file kurl.cpp.

       References isMalformed(), m_iPort, m_strHost, m_strPass, m_strProtocol,
       m_strQuery_encoded, m_strRef_encoded, m_strUser, and path().

       Referenced by cmp().

   bool KURL::isParentOf (const KURL & u) const
       Checks whether the given URL is parent of this URL. For instance,
       ftp://host/dir/ is a parent of ftp://host/dir/subdir/subsubdir/.

       Returns:
           true if this url is a parent of u (or the same URL as u)

       Definition at line 967 of file kurl.cpp.

       References QString::isEmpty(), isMalformed(), QString::length(), m_iPort,
       m_strHost, m_strPass, m_strProtocol, m_strQuery_encoded,
       m_strRef_encoded, m_strUser, path(), and QString::startsWith().

   KURL::List KURL::split (const QString & _url) [static]
       Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase A URL
       like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
       http://www.kde.org and tar:/kde/README.html#ref1. That means in turn that
       '#ref1' is an HTML-style reference and not a new sub URL. Since HTML-
       style references mark a certain position in a document this reference is
       appended to every URL. The idea behind this is that browsers, for
       example, only look at the first URL while the rest is not of interest to
       them.

       Parameters:
           _url The URL that has to be split.

       Returns:
           An empty list on error or the list of split URLs.

       See also:
           hasSubURL

       Definition at line 1368 of file kurl.cpp.

       References KURL().

       Referenced by cd(), encodedHtmlRef(), hasHTMLRef(), htmlRef(),
       setHTMLRef(), and upURL().

   KURL::List KURL::split (const KURL & _url) [static]
       Splits nested URLs like file:/home/weis/kde.tgz#gzip:/#tar:/kdebase A URL
       like http://www.kde.org#tar:/kde/README.hml#ref1 will be split in
       http://www.kde.org and tar:/kde/README.html#ref1. That means in turn that
       '#ref1' is an HTML-style reference and not a new sub URL. Since HTML-
       style references mark a certain position in a document this reference is
       appended to every URL. The idea behind this is that browsers, for
       example, only look at the first URL while the rest is not of interest to
       them.

       Returns:
           An empty list on error or the list of split URLs.

       Parameters:
           _url The URL that has to be split.

       See also:
           hasSubURL

       Definition at line 1336 of file kurl.cpp.

       References QValueList< KURL >::append(), QValueList< KURL >::begin(),
       QValueList< KURL >::end(), hasSubURL(), QValueList< KURL >::Iterator(),
       KURL(), m_strRef_encoded, ref(), and url().

   KURL KURL::join (const List & _list) [static]
       Reverses split(). Only the first URL may have a reference. This reference
       is considered to be HTML-like and is appended at the end of the resulting
       joined URL.

       Parameters:
           _list the list to join

       Returns:
           the joined URL

       Definition at line 1373 of file kurl.cpp.

       References QValueList< KURL >::ConstIterator(), QValueList< KURL
       >::end(), QValueList< KURL >::fromLast(), QValueList< KURL >::isEmpty(),
       KURL(), m_strRef_encoded, and url().

       Referenced by cd(), setHTMLRef(), and upURL().

   KURL KURL::fromPathOrURL (const QString & text) [static]
       Creates a KURL object from a QString representing either an absolute path
       or a real URL. Use this method instead of

        QString someDir = ...
        KURL url = someDir;


       Otherwise some characters (e.g. the '#') won't be encoded properly.

       Parameters:
           text the string representation of the URL to convert

       Returns:
           the new KURL

       Since:
           3.1

       Definition at line 1894 of file kurl.cpp.

       References QString::isEmpty(), KURL(), setPath(), and url().

   QString KURL::encode_string (const QString & str, int encoding_hint = 0)
       [static]
       Convenience function. Convert unicoded string to local encoding and use
       -style encoding for all common delimiters / non-ascii characters.

       Parameters:
           str String to encode (can be QString::null).
           encoding_hint MIB of encoding to use.

       See also:
           QTextCodec::mibEnum()

       Returns:
           the encoded string

       Definition at line 1739 of file kurl.cpp.

       Referenced by setFileEncoding(), and setFileName().

   QString KURL::encode_string_no_slash (const QString & str, int encoding_hint
       = 0) [static]
       Convenience function. Convert unicoded string to local encoding and use
       -style encoding for all common delimiters / non-ascii characters as well
       as the slash '/'.

       Parameters:
           str String to encode
           encoding_hint MIB of encoding to use.

       See also:
           QTextCodec::mibEnum()

       Definition at line 1744 of file kurl.cpp.

   QString KURL::decode_string (const QString & str, int encoding_hint = 0)
       [static]
       Convenience function. Decode -style encoding and convert from local
       encoding to unicode.

       Reverse of encode_string()

       Parameters:
           str String to decode (can be QString::null).
           encoding_hint MIB of original encoding of str .

       See also:
           QTextCodec::mibEnum()

       Definition at line 1734 of file kurl.cpp.

       Referenced by fileEncoding(), KApplication::invokeMailer(), queryItem(),
       queryItems(), and setFileEncoding().

   bool KURL::isRelativeURL (const QString & _url) [static]
       Convenience function. Returns whether '_url' is likely to be a 'relative'
       URL instead of an 'absolute' URL.

       Parameters:
           _url URL to examine

       Returns:
           true when the URL is likely to be 'relative', false otherwise.

       Definition at line 348 of file kurl.cpp.

       References QChar::latin1(), QString::length(), and QString::unicode().

       Referenced by KURL(), and KCmdLineArgs::makeURL().


Author
       Generated automatically by Doxygen for kdecore Library from the source
       code.




kdecore Library                    28 Jan 2004                           KURL(3)