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 Member Functions

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)
 This class or method is obsolete, it is provided for compatibility only. Use


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:" ) << "\n"; cout << "2> " << kstr.remrange( line , "2:5" ) << "\n"; cout << "2> " << kstr.reverse( line ) << "\n"; cout << "2> " << kstr.center( kstr.word( line , 4 ) , 15 ) << "\n";

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]
 

This class or method is obsolete, it is provided for compatibility only. 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.4.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Sun Feb 27 22:14:52 2005 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001