kdecore Library API Documentation

KURL Class Reference

Represents and parses a URL. More...

#include <kurl.h>

List of all members.

Public Types

enum  QueryItemsOptions
 Options for queryItems. More...


Public Methods

 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
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, QStringqueryItems (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.

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.


Static Public Methods

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.htmlref1.

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.htmlref1.

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.


Detailed Description

Represents and parses a URL.

A prototypical URL looks like:

   protocol:/user:password@hostname:port/path/to/file.extreference
 

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 373 of file kurl.cpp.

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

KURL::~KURL  
 

Destructs the KURL object.

Definition at line 378 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 383 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 389 of file kurl.cpp.

References QString::fromLatin1(), and url().

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 395 of file kurl.cpp.

References QString::fromLatin1().

KURL::KURL const KURL &    u
 

Copy constructor.

Parameters:
u  the KURL to copy

Definition at line 401 of file kurl.cpp.

KURL::KURL const QUrl   u
 

Converts from a QUrl.

Parameters:
u  the QUrl

Definition at line 436 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 442 of file kurl.cpp.

References cleanPath(), QString::find(), QString::findRev(), QString::isEmpty(), QString::isNull(), isRelativeURL(), QString::length(), m_strHost, m_strProtocol, QString::mid(), ref(), QString::remove(), 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 1609 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 1616 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 1622 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 1628 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 1634 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 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 1103 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 1639 of file kurl.cpp.

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

Referenced by 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 1004 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 1041 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 1088 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 1072 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 1051 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 1649 of file kurl.cpp.

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

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

QString KURL::query  
 

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 1693 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  
 

Returns the HTML reference (the part of the URL after "#").

Returns:
The HTML-style reference.
See also:
split , hasSubURL , encodedHtmlRef

Definition at line 1560 of file kurl.cpp.

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

QString KURL::encodedHtmlRef  
 

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 1571 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 1582 of file kurl.cpp.

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

Referenced by cd(), and KURL().

bool KURL::hasHTMLRef  
 

Checks whether there is a HTML reference.

Returns:
true if the URL has an HTML-style reference.
See also:
htmlRef()

Definition at line 1597 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]
 

Deprecated:

Definition at line 423 of file kurl.h.

References isValid().

Referenced by equals(), and isParentOf().

bool KURL::isLocalFile  
 

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 1108 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 1118 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  
 

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 1147 of file kurl.cpp.

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

bool KURL::hasSubURL  
 

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 1172 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 1412 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 1800 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 or</or>ed together.
Returns:
the map of query items or the empty map if the url has no query items.
Since:
3.1

Definition at line 1769 of file kurl.cpp.

References decode_string(), QString::fromLatin1(), QMap< QString, QString >::insert(), QString::isEmpty(), QString::lower(), 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 1849 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 1826 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 965 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 1358 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 1440 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 1474 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 1191 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.

Definition at line 1241 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  
 

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.

Definition at line 1297 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.

Definition at line 1289 of file kurl.cpp.

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

bool KURL::isEmpty  
 

Test to see if the KURL is empty.

Returns:
true if the URL is empty

Definition at line 527 of file kurl.cpp.

References QString::isEmpty().

Referenced by setPath().

KURL KURL::upURL  
 

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 1526 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.
Deprecated:

Definition at line 901 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 906 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 933 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.htmlref1.

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 1334 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.htmlref1.

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 1302 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 1339 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 1860 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 1705 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 1710 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 1700 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 321 of file kurl.cpp.

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

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


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:20:47 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001