kdecore Library API Documentation

KStringHandler Class Reference

This class contains utility functions for handling strings. 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)
QString word (const QString &text, const char *range)
QString insword (const QString &text, const QString &word, uint pos)
QString setword (const QString &text, const QString &word, uint pos)
QString remrange (const QString &text, const char *range)
QString remword (const QString &text, uint pos)
QString remword (const QString &text, const QString &word)
QString capwords (const QString &text)
QStringList capwords (const QStringList &list)
QString reverse (const QString &text)
QStringList reverse (const QStringList &list)
QString ljust (const QString &text, uint width)
QString rjust (const QString &text, uint width)
QString center (const QString &text, uint width)
QString lsqueeze (const QString &str, uint maxlen=40)
QString lEmSqueeze (const QString &name, const QFontMetrics &fontMetrics, uint maxlen=30)
QString lPixelSqueeze (const QString &name, const QFontMetrics &fontMetrics, uint maxPixels)
QString csqueeze (const QString &str, uint maxlen=40)
QString cEmSqueeze (const QString &name, const QFontMetrics &fontMetrics, uint maxlen=30)
QString cPixelSqueeze (const QString &name, const QFontMetrics &fontMetrics, uint maxPixels)
QString rsqueeze (const QString &str, uint maxlen=40)
QString rEmSqueeze (const QString &name, const QFontMetrics &fontMetrics, uint maxlen=30)
QString rPixelSqueeze (const QString &name, const QFontMetrics &fontMetrics, uint maxPixels)
bool matchFileName (const QString &filename, const QString &pattern)
QStringList perlSplit (const QString &sep, const QString &s, uint max=0)
QStringList perlSplit (const QChar &sep, const QString &s, uint max=0)
QStringList perlSplit (const QRegExp &sep, const QString &s, uint max=0)
QString tagURLs (const QString &text)
QString obscure (const QString &str)
bool isUtf8 (const char *str)
QString from8Bit (const char *str)
KDE_DEPRECATED bool matchFilename (const QString &filename, const QString &pattern)


Detailed Description

This class contains utility functions for handling strings. Class for manipulating words and sentences in strings.

This class is not a substitute for the QString class. 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>
See also:
KShell

Definition at line 70 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:
text 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 27 of file kstringhandler.cpp.

References word().

Referenced by capwords(), and word().

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:
text 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 37 of file kstringhandler.cpp.

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

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 105 of file kstringhandler.cpp.

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

Referenced by insword().

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 125 of file kstringhandler.cpp.

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

Referenced by setword().

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 147 of file kstringhandler.cpp.

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

Referenced by remrange().

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 208 of file kstringhandler.cpp.

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

Referenced by remword().

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 225 of file kstringhandler.cpp.

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

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 250 of file kstringhandler.cpp.

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

Referenced by capwords().

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 262 of file kstringhandler.cpp.

References capwords(), 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 286 of file kstringhandler.cpp.

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

Referenced by reverse().

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 300 of file kstringhandler.cpp.

References reverse().

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 318 of file kstringhandler.cpp.

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

Referenced by ljust().

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 332 of file kstringhandler.cpp.

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

Referenced by rjust().

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 346 of file kstringhandler.cpp.

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

Referenced by center().

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 374 of file kstringhandler.cpp.

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

Referenced by lsqueeze().

QString KStringHandler::lEmSqueeze const QString name,
const QFontMetrics fontMetrics,
uint  maxlen = 30
[static]
 

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

Similar to method above, except that it truncates based on pixel width rather than the number of characters

Parameters:
name is the string to modify
fontMetrics is the font metrics to use to calculate character sizes
maxlen is the maximum length in ems the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string
Since:
3.2

Definition at line 401 of file kstringhandler.cpp.

References lEmSqueeze(), lPixelSqueeze(), and QFontMetrics::maxWidth().

Referenced by lEmSqueeze().

QString KStringHandler::lPixelSqueeze const QString name,
const QFontMetrics fontMetrics,
uint  maxPixels
[static]
 

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

Similar to method above, except that maxlen is the width in pixels to truncate to

Parameters:
name is the string to modify
fontMetrics is the font metrics to use to calculate character sizes
maxPixels is the maximum pixel length the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string
Since:
3.2

Definition at line 413 of file kstringhandler.cpp.

References QString::isEmpty(), lPixelSqueeze(), QFontMetrics::maxWidth(), QString::remove(), and QFontMetrics::width().

Referenced by lEmSqueeze(), and lPixelSqueeze().

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 383 of file kstringhandler.cpp.

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

Referenced by csqueeze().

QString KStringHandler::cEmSqueeze const QString name,
const QFontMetrics fontMetrics,
uint  maxlen = 30
[static]
 

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

Similar to method above, except that it truncates based on pixel width rather than the number of characters

Parameters:
name is the string to modify
fontMetrics is the font metrics to use to calculate character sizes
maxlen is the maximum length in ems the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string
Since:
3.2

Definition at line 438 of file kstringhandler.cpp.

References cEmSqueeze(), cPixelSqueeze(), and QFontMetrics::maxWidth().

Referenced by cEmSqueeze().

QString KStringHandler::cPixelSqueeze const QString name,
const QFontMetrics fontMetrics,
uint  maxPixels
[static]
 

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

Similar to method above, except that maxlen is the width in pixels to truncate to

Parameters:
name is the string to modify
fontMetrics is the font metrics to use to calculate character sizes
maxPixels is the maximum pixel length the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string
Since:
3.2

Definition at line 443 of file kstringhandler.cpp.

References cPixelSqueeze(), QString::insert(), QString::isEmpty(), QString::length(), QFontMetrics::maxWidth(), QString::remove(), and QFontMetrics::width().

Referenced by cEmSqueeze(), and cPixelSqueeze().

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 392 of file kstringhandler.cpp.

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

Referenced by rsqueeze().

QString KStringHandler::rEmSqueeze const QString name,
const QFontMetrics fontMetrics,
uint  maxlen = 30
[static]
 

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

Similar to method above, except that it truncates based on pixel width rather than the number of characters

Parameters:
name is the string to modify
fontMetrics is the font metrics to use to calculate character sizes
maxlen is the maximum length in ems the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string
Since:
3.2

Definition at line 469 of file kstringhandler.cpp.

References QFontMetrics::maxWidth(), rEmSqueeze(), and rPixelSqueeze().

Referenced by rEmSqueeze().

QString KStringHandler::rPixelSqueeze const QString name,
const QFontMetrics fontMetrics,
uint  maxPixels
[static]
 

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

Similar to method above, except that maxlen is the width in pixels to truncate to

Parameters:
name is the string to modify
fontMetrics is the font metrics to use to calculate character sizes
maxPixels is the maximum pixel length the modified string will have If the original string is shorter than "maxlen", it is returned verbatim
Returns:
the modified string
Since:
3.2

Definition at line 474 of file kstringhandler.cpp.

References QString::isEmpty(), QString::length(), QFontMetrics::maxWidth(), QString::remove(), rPixelSqueeze(), and QFontMetrics::width().

Referenced by rEmSqueeze(), and rPixelSqueeze().

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.*, *README*, etc. Patterns with two asterisks like "*.*pk" are not supported.
Returns:
true if the given filename matches the given pattern

Definition at line 502 of file kstringhandler.cpp.

References QString::find(), QString::length(), matchFileName(), QString::mid(), 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.
s is the input string
max is the maximum number of extractions to perform, or 0.
Returns:
A QStringList containing tokens extracted from s.

Definition at line 541 of file kstringhandler.cpp.

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

Referenced by perlSplit().

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 parts other parts can't"

Parameters:
sep is the character to use to delimit s.
s is the input string
max is the maximum number of extractions to perform, or 0.
Returns:
A QStringList containing tokens extracted from s.

Definition at line 567 of file kstringhandler.cpp.

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

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.
s is the input string
max is the maximum number of extractions to perform, or 0.
Returns:
A QStringList containing tokens extracted from s.

Definition at line 593 of file kstringhandler.cpp.

References QString::length(), QRegExp::matchedLength(), QString::mid(), perlSplit(), 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 620 of file kstringhandler.cpp.

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

Referenced by tagURLs().

QString KStringHandler::obscure const QString str  )  [static]
 

Obscure string by using a simple symmetric encryption.

Applying the function to a string obscured by this function will result in the original string.

The function can be used to obscure passwords stored to configuration files. Note that this won't give you any more security than preventing that the password is directly copied and pasted.

Parameters:
str string to be obscured
Returns:
obscured string
Since:
3.2

Definition at line 645 of file kstringhandler.cpp.

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

Referenced by obscure().

bool KStringHandler::isUtf8 const char *  str  )  [static]
 

Guess whether a string is UTF8 encoded.

Parameters:
str the string to check
Returns:
true if UTF8. If false, the string is probably in Local8Bit.
Since:
3.2

Definition at line 656 of file kstringhandler.cpp.

References isUtf8().

Referenced by from8Bit(), and isUtf8().

QString KStringHandler::from8Bit const char *  str  )  [static]
 

Construct QString from a c string, guessing whether it is UTF8- or Local8Bit-encoded.

Parameters:
str the input string
Returns:
the (hopefully correctly guessed) QString representation of str
Since:
3.2

Definition at line 738 of file kstringhandler.cpp.

References from8Bit(), and isUtf8().

Referenced by from8Bit().

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

Deprecated:
Use
See also:
matchFileName () instead.

Definition at line 433 of file kstringhandler.h.

References matchFilename().

Referenced by matchFilename().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdecore Library Version 3.2.3.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Mar 16 17:21:48 2005 by doxygen 1.3.7 written by Dimitri van Heesch, © 1997-2003