.TH "KStringHandler" 3 "28 Jan 2004" "kdecore Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KStringHandler \- This class is \fInot\fP a substitute for the \fBQString\fP class. Class for manipulating words and sentences in strings.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <kstringhandler.h>\fP
.PP
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "\fBQString\fP \fBword\fP (const  \fBQString\fP &text, uint pos)"
.br
.RI "\fIReturns the nth word in the string if found Returns a EMPTY (not null) string otherwise. \fP"
.ti -1c
.RI "\fBQString\fP \fBword\fP (const  \fBQString\fP &text, const  char *range)"
.br
.RI "\fIReturns a range of words from that string. \fP"
.ti -1c
.RI "\fBQString\fP \fBinsword\fP (const  \fBQString\fP &text, const  \fBQString\fP &word, uint pos)"
.br
.RI "\fIInserts a word into the string, and returns a new string with the word included. \fP"
.ti -1c
.RI "\fBQString\fP \fBsetword\fP (const  \fBQString\fP &text, const  \fBQString\fP &word, uint pos)"
.br
.RI "\fIReplaces a word in the string, and returns a new string with the word included. \fP"
.ti -1c
.RI "\fBQString\fP \fBremrange\fP (const  \fBQString\fP &text, const  char *range)"
.br
.RI "\fIRemoves a word or ranges of words from the string, and returns a new string. \fP"
.ti -1c
.RI "\fBQString\fP \fBremword\fP (const  \fBQString\fP &text, uint pos)"
.br
.RI "\fIRemoves a word at the given index, and returns a new string. \fP"
.ti -1c
.RI "\fBQString\fP \fBremword\fP (const  \fBQString\fP &text, const  \fBQString\fP &word)"
.br
.RI "\fIRemoves a matching word from the string, and returns a new string. \fP"
.ti -1c
.RI "\fBQString\fP \fBcapwords\fP (const  \fBQString\fP &text)"
.br
.RI "\fICapitalizes each word in the string 'hello there' becomes 'Hello There' (string). \fP"
.ti -1c
.RI "\fBQStringList\fP \fBcapwords\fP (const  \fBQStringList\fP &list)"
.br
.RI "\fICapitalizes each word in the list [hello, there] becomes [Hello, There] (list). \fP"
.ti -1c
.RI "\fBQString\fP \fBreverse\fP (const  \fBQString\fP &text)"
.br
.RI "\fIReverses the order of the words in a string 'hello there' becomes 'there hello' (string). \fP"
.ti -1c
.RI "\fBQStringList\fP \fBreverse\fP (const  \fBQStringList\fP &list)"
.br
.RI "\fIReverses the order of the words in a list [hello, there] becomes [there, hello] (list). \fP"
.ti -1c
.RI "\fBQString\fP \fBljust\fP (const  \fBQString\fP &text, uint width)"
.br
.RI "\fILeft-justifies a string and returns a string at least 'width' characters wide. \fP"
.ti -1c
.RI "\fBQString\fP \fBrjust\fP (const  \fBQString\fP &text, uint width)"
.br
.RI "\fIRight-justifies a string and returns a string at least 'width' characters wide. \fP"
.ti -1c
.RI "\fBQString\fP \fBcenter\fP (const  \fBQString\fP &text, uint width)"
.br
.RI "\fICenters a string and returns a string at least 'width' characters wide. \fP"
.ti -1c
.RI "\fBQString\fP \fBlsqueeze\fP (const  \fBQString\fP &str, uint maxlen=40)"
.br
.RI "\fISubstitute characters at the beginning of a string by '...'. \fP"
.ti -1c
.RI "\fBQString\fP \fBcsqueeze\fP (const  \fBQString\fP &str, uint maxlen=40)"
.br
.RI "\fISubstitute characters at the middle of a string by '...'. \fP"
.ti -1c
.RI "\fBQString\fP \fBrsqueeze\fP (const  \fBQString\fP &str, uint maxlen=40)"
.br
.RI "\fISubstitute characters at the end of a string by '...'. \fP"
.ti -1c
.RI "bool \fBmatchFileName\fP (const  \fBQString\fP &filename, const  \fBQString\fP &pattern)"
.br
.RI "\fIMatch a filename. \fP"
.ti -1c
.RI "\fBQStringList\fP \fBperlSplit\fP (const  \fBQString\fP &sep, const  \fBQString\fP &s, uint max=0)"
.br
.RI "\fISplit a \fBQString\fP into a \fBQStringList\fP in a similar fashion to the static \fBQStringList\fP function in \fBQt\fP, except you can specify a maximum number of tokens. \fP"
.ti -1c
.RI "\fBQStringList\fP \fBperlSplit\fP (const  \fBQChar\fP &sep, const  \fBQString\fP &s, uint max=0)"
.br
.RI "\fISplit a \fBQString\fP into a \fBQStringList\fP in a similar fashion to the static \fBQStringList\fP function in \fBQt\fP, except you can specify a maximum number of tokens. \fP"
.ti -1c
.RI "\fBQStringList\fP \fBperlSplit\fP (const  \fBQRegExp\fP &sep, const  \fBQString\fP &s, uint max=0)"
.br
.RI "\fISplit a \fBQString\fP into a \fBQStringList\fP in a similar fashion to the static \fBQStringList\fP function in \fBQt\fP, except you can specify a maximum number of tokens. \fP"
.ti -1c
.RI "\fBQString\fP \fBtagURLs\fP (const  \fBQString\fP &text)"
.br
.RI "\fIThis method auto-detects URLs in strings, and adds HTML markup to them so that richtext or HTML-enabled widgets (such as \fBKActiveLabel\fP) will display the URL correctly. \fP"
.ti -1c
.RI "bool \fBmatchFilename\fP (const  \fBQString\fP &filename, const  \fBQString\fP &pattern)"
.br
.RI "\fI\fBThis class or method is obsolete, it is provided for compatibility only.\fP Use \fP"
.in -1c
.SH "Detailed Description"
.PP 
This class is \fInot\fP a substitute for the \fBQString\fP 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 (\fBsplit\fP() and \fBjoin\fP() ) 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.
.PP
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).
.PP
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 \fBword\fP(const \fBQString\fP&, int) and \fBremword\fP(const \fBQString\fP&, int) functions for more detail.
.PP
This class contains no data members of it own. All strings are cut on the fly and returned as new qstrings/qstringlists.
.PP
Quick example on how to use:
.PP
.PP
.nf

 KStringHandler kstr;
 \fBQString\fP line = 'This is a test of the strings';
.PP
.PP
.PP
.nf
 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';
 
.PP
.PP
and so forth.
.PP
\fBAuthor:\fP
.RS 4
Ian Zepp <icszepp@islc.net> 
.RE
.PP

.PP
Definition at line 66 of file kstringhandler.h.
.SH "Member Function Documentation"
.PP 
.SS "\fBQString\fP KStringHandler::word (const \fBQString\fP & text, uint pos)\fC [static]\fP"
.PP
Returns the nth word in the string if found Returns a EMPTY (not null) string otherwise. Note that the FIRST index is 0. 
.PP
\fBParameters:\fP
.RS 4
\fIthe\fP the string to search for the words 
.br
\fIpos\fP the position of the word to search 
.RE
.PP
\fBReturns:\fP
.RS 4
the word, or an empty string if not found 
.RE
.PP
Definition at line 26 of file kstringhandler.cpp.
.PP
References QStringList::split().
.PP
Referenced by capwords().
.SS "\fBQString\fP KStringHandler::word (const \fBQString\fP & text, const char * range)\fC [static]\fP"
.PP
Returns a range of words from that string. Ie: 
.IP "\(bu" 2
'0' returns the very first word 
.IP "\(bu" 2
'0:' returns the first to the last word 
.IP "\(bu" 2
'0:3' returns the first to fourth words 
.IP "\(bu" 2
':3' returns everything up to the fourth word
.PP
If you grok python, you're set. 
.PP
\fBParameters:\fP
.RS 4
\fIthe\fP the string to search for the words 
.br
\fIrange\fP the words to return (see description) 
.RE
.PP
\fBReturns:\fP
.RS 4
the words, or an empty string if not found 
.RE
.PP
Definition at line 36 of file kstringhandler.cpp.
.PP
References QString::ascii(), QString::find(), QString::isEmpty(), QString::left(), QString::remove(), QStringList::split(), and QString::stripWhiteSpace().
.SS "\fBQString\fP KStringHandler::insword (const \fBQString\fP & text, const \fBQString\fP & word, uint pos)\fC [static]\fP"
.PP
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 \fCpos\fP words in the original string, the new word will be appended to the end. 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the original text 
.br
\fIword\fP the word to insert 
.br
\fIpos\fP the position (in words) for the new word 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 104 of file kstringhandler.cpp.
.PP
References QString::isEmpty(), QStringList::join(), and QStringList::split().
.SS "\fBQString\fP KStringHandler::setword (const \fBQString\fP & text, const \fBQString\fP & word, uint pos)\fC [static]\fP"
.PP
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 \fCpos\fP words in the original string, the new word will be appended to the end. 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the original text 
.br
\fIword\fP the word to insert 
.br
\fIpos\fP the position (in words) for the new word 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 124 of file kstringhandler.cpp.
.PP
References QString::isEmpty(), QStringList::join(), and QStringList::split().
.SS "\fBQString\fP KStringHandler::remrange (const \fBQString\fP & text, const char * range)\fC [static]\fP"
.PP
Removes a word or ranges of words from the string, and returns a new string. The ranges definitions follow the definitions for the \fBword()\fP function.
.PP
.IP "\(bu" 2
'0' removes the very first word 
.IP "\(bu" 2
'0:' removes the first the the last word 
.IP "\(bu" 2
'0:3' removes the first to fourth words 
.IP "\(bu" 2
':3' removes everything up to the fourth word 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the original text 
.br
\fIrange\fP the words to remove (see description) 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP

.PP
Definition at line 146 of file kstringhandler.cpp.
.PP
References QString::ascii(), QString::find(), QString::isEmpty(), QStringList::join(), QString::left(), QString::remove(), and QStringList::split().
.SS "\fBQString\fP KStringHandler::remword (const \fBQString\fP & text, uint pos)\fC [static]\fP"
.PP
Removes a word at the given index, and returns a new string. The first index is zero (0). 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the original text 
.br
\fIpos\fP the position (in words) of thw word to delete 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 207 of file kstringhandler.cpp.
.PP
References QString::isEmpty(), QStringList::join(), and QStringList::split().
.SS "\fBQString\fP KStringHandler::remword (const \fBQString\fP & text, const \fBQString\fP & word)\fC [static]\fP"
.PP
Removes a matching word from the string, and returns a new string. Note that only ONE match is removed. 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the original text 
.br
\fIword\fP the word to remove 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 224 of file kstringhandler.cpp.
.PP
References QString::isEmpty(), QStringList::join(), and QStringList::split().
.SS "\fBQString\fP KStringHandler::capwords (const \fBQString\fP & text)\fC [static]\fP"
.PP
Capitalizes each word in the string 'hello there' becomes 'Hello There' (string). \fBParameters:\fP
.RS 4
\fItext\fP the text to capitalize 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 249 of file kstringhandler.cpp.
.PP
References QString::isEmpty(), and QStringList::split().
.SS "\fBQStringList\fP KStringHandler::capwords (const \fBQStringList\fP & list)\fC [static]\fP"
.PP
Capitalizes each word in the list [hello, there] becomes [Hello, There] (list). \fBParameters:\fP
.RS 4
\fIlist\fP the list to capitalize 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting list 
.RE
.PP
Definition at line 261 of file kstringhandler.cpp.
.PP
References QString::left(), QString::remove(), and word().
.SS "\fBQString\fP KStringHandler::reverse (const \fBQString\fP & text)\fC [static]\fP"
.PP
Reverses the order of the words in a string 'hello there' becomes 'there hello' (string). \fBParameters:\fP
.RS 4
\fItext\fP the text to reverse 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 285 of file kstringhandler.cpp.
.PP
References QString::isEmpty(), QStringList::join(), and QStringList::split().
.SS "\fBQStringList\fP KStringHandler::reverse (const \fBQStringList\fP & list)\fC [static]\fP"
.PP
Reverses the order of the words in a list [hello, there] becomes [there, hello] (list). \fBParameters:\fP
.RS 4
\fIlist\fP the list to reverse 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting list 
.RE
.PP
Definition at line 299 of file kstringhandler.cpp.
.SS "\fBQString\fP KStringHandler::ljust (const \fBQString\fP & text, uint width)\fC [static]\fP"
.PP
Left-justifies a string and returns a string at least 'width' characters wide. If the string is longer than the \fCwidth\fP, the original string is returned. It is never truncated. 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the text to justify 
.br
\fIwidth\fP the desired width of the new string 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 317 of file kstringhandler.cpp.
.PP
References QString::append(), QString::length(), and QString::stripWhiteSpace().
.SS "\fBQString\fP KStringHandler::rjust (const \fBQString\fP & text, uint width)\fC [static]\fP"
.PP
Right-justifies a string and returns a string at least 'width' characters wide. If the string is longer than the \fCwidth\fP, the original string is returned. It is never truncated. 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the text to justify 
.br
\fIwidth\fP the desired width of the new string 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 331 of file kstringhandler.cpp.
.PP
References QString::length(), QString::prepend(), and QString::stripWhiteSpace().
.SS "\fBQString\fP KStringHandler::center (const \fBQString\fP & text, uint width)\fC [static]\fP"
.PP
Centers a string and returns a string at least 'width' characters wide. If the string is longer than the \fCwidth\fP, the original string is returned. It is never truncated. 
.PP
\fBParameters:\fP
.RS 4
\fItext\fP the text to justify 
.br
\fIwidth\fP the desired width of the new string 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting string 
.RE
.PP
Definition at line 345 of file kstringhandler.cpp.
.PP
References QString::append(), QString::length(), QString::prepend(), and QString::stripWhiteSpace().
.SS "\fBQString\fP KStringHandler::lsqueeze (const \fBQString\fP & str, uint maxlen = 40)\fC [static]\fP"
.PP
Substitute characters at the beginning of a string by '...'. \fBParameters:\fP
.RS 4
\fIstr\fP is the string to modify 
.br
\fImaxlen\fP is the maximum length the modified string will have If the original string is shorter than 'maxlen', it is returned verbatim 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified string 
.RE
.PP
Definition at line 373 of file kstringhandler.cpp.
.PP
References QString::length(), and QString::right().
.SS "\fBQString\fP KStringHandler::csqueeze (const \fBQString\fP & str, uint maxlen = 40)\fC [static]\fP"
.PP
Substitute characters at the middle of a string by '...'. \fBParameters:\fP
.RS 4
\fIstr\fP is the string to modify 
.br
\fImaxlen\fP is the maximum length the modified string will have If the original string is shorter than 'maxlen', it is returned verbatim 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified string 
.RE
.PP
Definition at line 382 of file kstringhandler.cpp.
.PP
References QString::left(), QString::length(), and QString::right().
.SS "\fBQString\fP KStringHandler::rsqueeze (const \fBQString\fP & str, uint maxlen = 40)\fC [static]\fP"
.PP
Substitute characters at the end of a string by '...'. \fBParameters:\fP
.RS 4
\fIstr\fP is the string to modify 
.br
\fImaxlen\fP is the maximum length the modified string will have If the original string is shorter than 'maxlen', it is returned verbatim 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified string 
.RE
.PP
Definition at line 391 of file kstringhandler.cpp.
.PP
References QString::left(), and QString::length().
.SS "bool KStringHandler::matchFileName (const \fBQString\fP & filename, const \fBQString\fP & pattern)\fC [static]\fP"
.PP
Match a filename. \fBParameters:\fP
.RS 4
\fIfilename\fP is the real decoded filename (or dirname without trailing '/'). 
.br
\fIpattern\fP is a pattern like *.txt, *.tar.gz, Makefile.*, etc. Patterns with two asterisks like '*.*pk' are not supported. 
.RE
.PP
\fBReturns:\fP
.RS 4
true if the given filename matches the given pattern 
.RE
.PP
Definition at line 402 of file kstringhandler.cpp.
.PP
References QString::length(), and QString::unicode().
.PP
Referenced by matchFilename().
.SS "\fBQStringList\fP KStringHandler::perlSplit (const \fBQString\fP & sep, const \fBQString\fP & s, uint max = 0)\fC [static]\fP"
.PP
Split a \fBQString\fP into a \fBQStringList\fP in a similar fashion to the static \fBQStringList\fP function in \fBQt\fP, 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.
.PP
Example: 
.PP
.nf

 perlSplit('__', 'some__string__for__you__here', 4)
 \fBQStringList\fP contains: 'some', 'string', 'for', 'you__here'
 
.PP
.PP
\fBParameters:\fP
.RS 4
\fIsep\fP is the string to use to delimit s. 
.br
\fImax\fP is the maximum number of extractions to perform, or 0. 
.RE
.PP
\fBReturns:\fP
.RS 4
A \fBQStringList\fP containing tokens extracted from s. 
.RE
.PP
Definition at line 436 of file kstringhandler.cpp.
.PP
References QString::find(), QString::length(), and QString::mid().
.SS "\fBQStringList\fP KStringHandler::perlSplit (const \fBQChar\fP & sep, const \fBQString\fP & s, uint max = 0)\fC [static]\fP"
.PP
Split a \fBQString\fP into a \fBQStringList\fP in a similar fashion to the static \fBQStringList\fP function in \fBQt\fP, 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.
.PP
Example: 
.PP
.nf

 perlSplit(' ', 'kparts reaches the parts other parts can't', 3)
 \fBQStringList\fP contains: 'kparts', 'reaches', 'the pats other parts can't'
 
.PP
.PP
\fBParameters:\fP
.RS 4
\fIsep\fP is the character to use to delimit s. 
.br
\fImax\fP is the maximum number of extractions to perform, or 0. 
.RE
.PP
\fBReturns:\fP
.RS 4
A \fBQStringList\fP containing tokens extracted from s. 
.RE
.PP
Definition at line 462 of file kstringhandler.cpp.
.PP
References QString::find(), QString::length(), and QString::mid().
.SS "\fBQStringList\fP KStringHandler::perlSplit (const \fBQRegExp\fP & sep, const \fBQString\fP & s, uint max = 0)\fC [static]\fP"
.PP
Split a \fBQString\fP into a \fBQStringList\fP in a similar fashion to the static \fBQStringList\fP function in \fBQt\fP, 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.
.PP
Example: 
.PP
.nf

 perlSplit(\fBQRegExp\fP('[! ]', 'Split me up ! I'm bored ! OK ?', 3)
 \fBQStringList\fP contains: 'Split', 'me', 'up ! I'm bored, OK ?'
 
.PP
.PP
\fBParameters:\fP
.RS 4
\fIsep\fP is the regular expression to use to delimit s. 
.br
\fImax\fP is the maximum number of extractions to perform, or 0. 
.RE
.PP
\fBReturns:\fP
.RS 4
A \fBQStringList\fP containing tokens extracted from s. 
.RE
.PP
Definition at line 488 of file kstringhandler.cpp.
.PP
References QString::length(), QRegExp::matchedLength(), QString::mid(), and QRegExp::search().
.SS "\fBQString\fP KStringHandler::tagURLs (const \fBQString\fP & text)\fC [static]\fP"
.PP
This method auto-detects URLs in strings, and adds HTML markup to them so that richtext or HTML-enabled widgets (such as \fBKActiveLabel\fP) will display the URL correctly. \fBParameters:\fP
.RS 4
\fItext\fP the string which may contain URLs 
.RE
.PP
\fBReturns:\fP
.RS 4
the resulting text 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP
Definition at line 515 of file kstringhandler.cpp.
.PP
References QString::length(), QRegExp::matchedLength(), QString::mid(), QString::replace(), and QRegExp::search().
.SS "bool KStringHandler::matchFilename (const \fBQString\fP & filename, const \fBQString\fP & pattern)\fC [inline, static]\fP"
.PP
\fBThis class or method is obsolete, it is provided for compatibility only.\fP Use \fBSee also:\fP
.RS 4
\fBmatchFileName\fP () instead. 
.RE
.PP
Definition at line 310 of file kstringhandler.h.
.PP
References matchFileName().

.SH "Author"
.PP 
Generated automatically by Doxygen for kdecore Library from the source code.
