class KStringHandler

# class KStringHandler | Class for manipulating words and sentences in strings. More...
Definition | `#include <kstringhandler.h>`
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Static Methods

- static QString word ( const QString &text , uint pos )
- static QString word ( const QString &text , const char *range )
- static QString insword ( const QString &text , const QString &word , uint pos )
- static QString setword ( const QString &text , const QString &word , uint pos )
- static QString remrange ( const QString &text , const char *range )
- static QString remword ( const QString &text , uint pos )
- static QString remword ( const QString &text , const QString &word )
- static QString capwords ( const QString &text )
- static QStringList capwords ( const QStringList &list )
- static QString reverse ( const QString &text )
- static QStringList reverse ( const QStringList &list )
- static QString ljust ( const QString &text , uint width )
- static QString rjust ( const QString &text , uint width )
- static QString center ( const QString &text , uint width )
- static QString lsqueeze ( const QString & str, uint maxlen = 40 )
- static QString csqueeze ( const QString & str, uint maxlen = 40 )
- static QString rsqueeze ( const QString & str, uint maxlen = 40 )
- static bool matchFileName ( const QString& filename, const QString& pattern )
- static QStringList perlSplit (const QString & sep, const QString & s, uint max = 0)
- static QStringList perlSplit (const QChar & sep, const QString & s, uint max = 0)
- static QStringList perlSplit (const QRegExp & sep, const QString & s, uint max = 0)
- static QString tagURLs ( const QString& text )

## Detailed Description

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.

QString word ( const QString &text , uint pos ) | ### word

[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

QString word ( const QString &text , const char *range ) | ### word

[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

QString insword ( const QString &text , const QString &word , uint pos ) | ### insword

[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

QString setword ( const QString &text , const QString &word , uint pos ) | ### setword

[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

QString remrange ( const QString &text , const char *range ) | ### remrange

[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

QString remword ( const QString &text , uint pos ) | ### remword

[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

QString remword ( const QString &text , const QString &word ) | ### remword

[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

QString capwords ( const QString &text ) | ### capwords

[static]

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

Parameters:

text | the text to capitalize

Returns: the resulting string

QStringList capwords ( const QStringList &list ) | ### capwords

[static]

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

Parameters:

list | the list to capitalize

Returns: the resulting list

QString reverse ( const QString &text ) | ### reverse

[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

QStringList reverse ( const QStringList &list ) | ### reverse

[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

QString ljust ( const QString &text , uint width ) | ### ljust

[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

QString rjust ( const QString &text , uint width ) | ### rjust

[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

QString center ( const QString &text , uint width ) | ### center

[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

QString lsqueeze ( const QString & str, uint maxlen = 40 ) | ### lsqueeze

[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

QString csqueeze ( const QString & str, uint maxlen = 40 ) | ### csqueeze

[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

QString rsqueeze ( const QString & str, uint maxlen = 40 ) | ### rsqueeze

[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

bool matchFileName ( const QString& filename, const QString& pattern ) | ### matchFileName

[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

QStringList perlSplit (const QString & sep, const QString & s, uint max = 0) | ### perlSplit

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

QStringList perlSplit (const QChar & sep, const QString & s, uint max = 0) | ### perlSplit

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

QStringList perlSplit (const QRegExp & sep, const QString & s, uint max = 0) | ### perlSplit

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

QString tagURLs ( const QString& text ) | ### tagURLs

[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

- Author: Ian Zepp
- Generated: root on macppc.ports.openbsd.org on Sat Sep 6 10:36:15 2003, using kdoc 2.0a54.