kdecore Library API Documentation

KStringHandler Class Reference

This class is not a substitute for the QString class. Class for manipulating words and sentences in strings. More...

#include <kstringhandler.h>

List of all members.

Static Public Methods

QString word (const QString &text, uint pos)
 Returns the nth word in the string if found Returns a EMPTY (not null) string otherwise.

QString word (const QString &text, const char *range)
 Returns a range of words from that string.

QString insword (const QString &text, const QString &word, uint pos)
 Inserts a word into the string, and returns a new string with the word included.

QString setword (const QString &text, const QString &word, uint pos)
 Replaces a word in the string, and returns a new string with the word included.

QString remrange (const QString &text, const char *range)
 Removes a word or ranges of words from the string, and returns a new string.

QString remword (const QString &text, uint pos)
 Removes a word at the given index, and returns a new string.

QString remword (const QString &text, const QString &word)
 Removes a matching word from the string, and returns a new string.

QString capwords (const QString &text)
 Capitalizes each word in the string "hello there" becomes "Hello There" (string).

QStringList capwords (const QStringList &list)
 Capitalizes each word in the list [hello, there] becomes [Hello, There] (list).

QString reverse (const QString &text)
 Reverses the order of the words in a string "hello there" becomes "there hello" (string).

QStringList reverse (const QStringList &list)
 Reverses the order of the words in a list [hello, there] becomes [there, hello] (list).

QString ljust (const QString &text, uint width)
 Left-justifies a string and returns a string at least 'width' characters wide.

QString rjust (const QString &text, uint width)
 Right-justifies a string and returns a string at least 'width' characters wide.

QString center (const QString &text, uint width)
 Centers a string and returns a string at least 'width' characters wide.

QString lsqueeze (const QString &str, uint maxlen=40)
 Substitute characters at the beginning of a string by "...".

QString csqueeze (const QString &str, uint maxlen=40)
 Substitute characters at the middle of a string by "...".

QString rsqueeze (const QString &str, uint maxlen=40)
 Substitute characters at the end of a string by "...".

bool matchFileName (const QString &filename, const QString &pattern)
 Match a filename.

QStringList perlSplit (const QString &sep, const QString &s, uint max=0)
 Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt, except you can specify a maximum number of tokens.

QStringList perlSplit (const QChar &sep, const QString &s, uint max=0)
 Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt, except you can specify a maximum number of tokens.

QStringList perlSplit (const QRegExp &sep, const QString &s, uint max=0)
 Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt, except you can specify a maximum number of tokens.

QString tagURLs (const QString &text)
 This method auto-detects URLs in strings, and adds HTML markup to them so that richtext or HTML-enabled widgets (such as KActiveLabel) will display the URL correctly.

bool matchFilename (const QString &filename, const QString &pattern)


Detailed Description

This class is not a substitute for the QString class. Class for manipulating words and sentences in strings.

What I tried to do with this class is provide an easy way to cut/slice/splice words inside sentences in whatever order desired. While the main focus of this class are words (ie characters separated by spaces/tabs), the two core functions here (split() and join() ) will function given any char to use as a separator. This will make it easy to redefine what a 'word' means in the future if needed.

I freely stole some of the function names from python. I also think some of these were influenced by mIRC (yes, believe it if you will, I used to write a LOT of scripts in mIRC).

The ranges are a fairly powerful way of getting/stripping words from a string. These ranges function, for the large part, as they would in python. See the word(const QString&, int) and remword(const QString&, int) functions for more detail.

This class contains no data members of it own. All strings are cut on the fly and returned as new qstrings/qstringlists.

Quick example on how to use:

 KStringHandler kstr;
 QString line = "This is a test of the strings";

 cout << "1> " << kstr.word( line , "4:" ) << "
"; cout << "2> " << kstr.remrange( line , "2:5" ) << "
"; cout << "2> " << kstr.reverse( line ) << "
"; cout << "2> " << kstr.center( kstr.word( line , 4 ) , 15 ) << "
";

and so forth.

Author:
Ian Zepp <icszepp@islc.net>

Definition at line 66 of file kstringhandler.h.


Member Function Documentation

QString KStringHandler::word const QString   text,
uint    pos
[static]
 

Returns the nth word in the string if found Returns a EMPTY (not null) string otherwise.

Note that the FIRST index is 0.

Parameters:
the  the string to search for the words
pos  the position of the word to search
Returns:
the word, or an empty string if not found

Definition at line 26 of file kstringhandler.cpp.

References QStringList::split().

Referenced by capwords().

QString KStringHandler::word const QString   text,
const char *    range
[static]
 

Returns a range of words from that string.

Ie:

  • "0" returns the very first word
  • "0:" returns the first to the last word
  • "0:3" returns the first to fourth words
  • ":3" returns everything up to the fourth word
If you grok python, you're set.
Parameters:
the  the string to search for the words
range  the words to return (see description)
Returns:
the words, or an empty string if not found

Definition at line 36 of file kstringhandler.cpp.

References QString::ascii(), QString::find(), QString::isEmpty(), QString::left(), QString::remove(), QStringList::split(), and QString::stripWhiteSpace().

QString KStringHandler::insword const QString   text,
const QString   word,
uint    pos
[static]
 

Inserts a word into the string, and returns a new string with the word included.

the first index is zero (0). If there are not pos words in the original string, the new word will be appended to the end.

Parameters:
text  the original text
word  the word to insert
pos  the position (in words) for the new word
Returns:
the resulting string

Definition at line 104 of file kstringhandler.cpp.

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

QString KStringHandler::setword const QString   text,
const QString   word,
uint    pos
[static]
 

Replaces a word in the string, and returns a new string with the word included.

the first index is zero (0). If there are not pos words in the original string, the new word will be appended to the end.

Parameters:
text  the original text
word  the word to insert
pos  the position (in words) for the new word
Returns:
the resulting string

Definition at line 124 of file kstringhandler.cpp.

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

QString KStringHandler::remrange const QString   text,
const char *    range
[static]
 

Removes a word or ranges of words from the string, and returns a new string.

The ranges definitions follow the definitions for the word() function.

  • "0" removes the very first word
  • "0:" removes the first the the last word
  • "0:3" removes the first to fourth words
  • ":3" removes everything up to the fourth word
Parameters:
text  the original text
range  the words to remove (see description)
Returns:
the resulting string

Definition at line 146 of file kstringhandler.cpp.

References QString::ascii(), QString::find(), QString::isEmpty(), QStringList::join(), QString::left(), QString::remove(), and QStringList::split().

QString KStringHandler::remword const QString   text,
uint    pos
[static]
 

Removes a word at the given index, and returns a new string.

The first index is zero (0).

Parameters:
text  the original text
pos  the position (in words) of thw word to delete
Returns:
the resulting string

Definition at line 207 of file kstringhandler.cpp.

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

QString KStringHandler::remword const QString   text,
const QString   word
[static]
 

Removes a matching word from the string, and returns a new string.

Note that only ONE match is removed.

Parameters:
text  the original text
word  the word to remove
Returns:
the resulting string

Definition at line 224 of file kstringhandler.cpp.

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

QString KStringHandler::capwords const QString   text [static]
 

Capitalizes each word in the string "hello there" becomes "Hello There" (string).

Parameters:
text  the text to capitalize
Returns:
the resulting string

Definition at line 249 of file kstringhandler.cpp.

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

QStringList KStringHandler::capwords const QStringList   list [static]
 

Capitalizes each word in the list [hello, there] becomes [Hello, There] (list).

Parameters:
list  the list to capitalize
Returns:
the resulting list

Definition at line 261 of file kstringhandler.cpp.

References QString::left(), QString::remove(), and word().

QString KStringHandler::reverse const QString   text [static]
 

Reverses the order of the words in a string "hello there" becomes "there hello" (string).

Parameters:
text  the text to reverse
Returns:
the resulting string

Definition at line 285 of file kstringhandler.cpp.

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

QStringList KStringHandler::reverse const QStringList   list [static]
 

Reverses the order of the words in a list [hello, there] becomes [there, hello] (list).

Parameters:
list  the list to reverse
Returns:
the resulting list

Definition at line 299 of file kstringhandler.cpp.

QString KStringHandler::ljust const QString   text,
uint    width
[static]
 

Left-justifies a string and returns a string at least 'width' characters wide.

If the string is longer than the width, the original string is returned. It is never truncated.

Parameters:
text  the text to justify
width  the desired width of the new string
Returns:
the resulting string

Definition at line 317 of file kstringhandler.cpp.

References QString::append(), QString::length(), and QString::stripWhiteSpace().

QString KStringHandler::rjust const QString   text,
uint    width
[static]
 

Right-justifies a string and returns a string at least 'width' characters wide.

If the string is longer than the width, the original string is returned. It is never truncated.

Parameters:
text  the text to justify
width  the desired width of the new string
Returns:
the resulting string

Definition at line 331 of file kstringhandler.cpp.

References QString::length(), QString::prepend(), and QString::stripWhiteSpace().

QString KStringHandler::center const QString   text,
uint    width
[static]
 

Centers a string and returns a string at least 'width' characters wide.

If the string is longer than the width, the original string is returned. It is never truncated.

Parameters:
text  the text to justify
width  the desired width of the new string
Returns:
the resulting string

Definition at line 345 of file kstringhandler.cpp.

References QString::append(), QString::length(), QString::prepend(), and QString::stripWhiteSpace().

QString KStringHandler::lsqueeze const QString   str,
uint    maxlen = 40
[static]
 

Substitute characters at the beginning of a string by "...".

Parameters:
str  is the string to modify
maxlen  is the maximum length the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string

Definition at line 373 of file kstringhandler.cpp.

References QString::length(), and QString::right().

QString KStringHandler::csqueeze const QString   str,
uint    maxlen = 40
[static]
 

Substitute characters at the middle of a string by "...".

Parameters:
str  is the string to modify
maxlen  is the maximum length the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string

Definition at line 382 of file kstringhandler.cpp.

References QString::left(), QString::length(), and QString::right().

QString KStringHandler::rsqueeze const QString   str,
uint    maxlen = 40
[static]
 

Substitute characters at the end of a string by "...".

Parameters:
str  is the string to modify
maxlen  is the maximum length the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string

Definition at line 391 of file kstringhandler.cpp.

References QString::left(), and QString::length().

bool KStringHandler::matchFileName const QString   filename,
const QString   pattern
[static]
 

Match a filename.

Parameters:
filename  is the real decoded filename (or dirname without trailing '/').
pattern  is a pattern like *.txt, *.tar.gz, Makefile.*, etc. Patterns with two asterisks like "*.*pk" are not supported.
Returns:
true if the given filename matches the given pattern

Definition at line 402 of file kstringhandler.cpp.

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

Referenced by matchFilename().

QStringList KStringHandler::perlSplit const QString   sep,
const QString   s,
uint    max = 0
[static]
 

Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt, except you can specify a maximum number of tokens.

If max is specified (!= 0) then only that number of tokens will be extracted. The final token will be the remainder of the string.

Example:

 perlSplit("__", "some__string__for__you__here", 4)
 QStringList contains: "some", "string", "for", "you__here"
 
Parameters:
sep  is the string to use to delimit s.
max  is the maximum number of extractions to perform, or 0.
Returns:
A QStringList containing tokens extracted from s.

Definition at line 436 of file kstringhandler.cpp.

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

QStringList KStringHandler::perlSplit const QChar   sep,
const QString   s,
uint    max = 0
[static]
 

Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt, except you can specify a maximum number of tokens.

If max is specified (!= 0) then only that number of tokens will be extracted. The final token will be the remainder of the string.

Example:

 perlSplit(' ', "kparts reaches the parts other parts can't", 3)
 QStringList contains: "kparts", "reaches", "the pats other parts can't"
 
Parameters:
sep  is the character to use to delimit s.
max  is the maximum number of extractions to perform, or 0.
Returns:
A QStringList containing tokens extracted from s.

Definition at line 462 of file kstringhandler.cpp.

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

QStringList KStringHandler::perlSplit const QRegExp   sep,
const QString   s,
uint    max = 0
[static]
 

Split a QString into a QStringList in a similar fashion to the static QStringList function in Qt, except you can specify a maximum number of tokens.

If max is specified (!= 0) then only that number of tokens will be extracted. The final token will be the remainder of the string.

Example:

 perlSplit(QRegExp("[! ]", "Split me up ! I'm bored ! OK ?", 3)
 QStringList contains: "Split", "me", "up ! I'm bored, OK ?"
 
Parameters:
sep  is the regular expression to use to delimit s.
max  is the maximum number of extractions to perform, or 0.
Returns:
A QStringList containing tokens extracted from s.

Definition at line 488 of file kstringhandler.cpp.

References QString::length(), QRegExp::matchedLength(), QString::mid(), and QRegExp::search().

QString KStringHandler::tagURLs const QString   text [static]
 

This method auto-detects URLs in strings, and adds HTML markup to them so that richtext or HTML-enabled widgets (such as KActiveLabel) will display the URL correctly.

Parameters:
text  the string which may contain URLs
Returns:
the resulting text
Since:
3.1

Definition at line 515 of file kstringhandler.cpp.

References QString::length(), QRegExp::matchedLength(), QString::mid(), QString::replace(), and QRegExp::search().

bool KStringHandler::matchFilename const QString   filename,
const QString   pattern
[inline, static]
 

Deprecated:
Use
See also:
matchFileName () instead.

Definition at line 310 of file kstringhandler.h.

References matchFileName().


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