# kdecore Library API Documentation

Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Source Files

# 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:

- kstringhandler.h
- kstringhandler.cpp

This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 12:51:44 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001