/* This file is part of the KDE libraries
Copyright (C) 1999 Ian Zepp (icszepp@islc.net)
Copyright (C) 2000 Rik Hemsley (rikkus)
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
#ifndef KSTRINGHANDLER_H
#define KSTRINGHANDLER_H
#include // for atoi()
#include
#include
#include // for the word ranges
/** General description of this class:
*
* This class is @em not a substitute for the @ref 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 (@ref split()
* and @ref 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 @ref word and @ref remword 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.
*
* @short Class for manipulating words and sentences in strings
* @author Ian Zepp
*/
class KStringHandler
{
public:
/** Returns the nth word in the string if found
* Returns a EMPTY (not null) string otherwise.
* Note that the FIRST index is 0
*/
static QString word( const QString &text , uint pos );
/** Returns a range of words from that string.
* Ie:
*
* "0" returns the very first word
* "0:" returns the first the 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.
*/
static QString word( const QString &text , const char *range );
/** Inserts a word into the string, and returns
* a new string with the word included. the first
* index is zero (0)
*/
static QString insword( const QString &text , const QString &word , uint pos );
/** Replaces a word in the string, and returns
* a new string with the word included. the first
* index is zero (0)
*/
static QString setword( const QString &text , const QString &word , uint pos );
/** 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
*/
static QString remrange( const QString &text , const char *range );
/** Removes a word at the given index, and returns a
* new string. The first index is zero (0)
*/
static QString remword( const QString &text , uint pos );
/** Removes a matching word from the string, and returns
* a new string. Note that only ONE match is removed.
*/
static QString remword( const QString &text , const QString &word );
/** Capitalizes each word in the string
* "hello there" becomes "Hello There" (string)
*/
static QString capwords( const QString &text );
/** Capitalizes each word in the list
* [hello, there] becomes [Hello, There] (list)
*/
static QStringList capwords( const QStringList &list );
/** Reverses the order of the words in a string
* "hello there" becomes "there hello" (string)
*/
static QString reverse( const QString &text );
/** Reverses the order of the words in a list
* [hello, there] becomes [there, hello] (list)
*/
static QStringList reverse( const QStringList &list );
/** These string justify a string along x, and returns a
* string at least 'width' characters wide, and justified.
* If the string is longer than the width, the original
* string is returned. It is never truncated.
* ljust Left justify
* rjust Right justify
* center Centers
*/
static QString ljust( const QString &text , uint width );
static QString rjust( const QString &text , uint width );
static QString center( const QString &text , uint width );
/** Substitute characters at the beginning of a string by "...".
* @return the modified string
* @param str is the string to modify
* @param maxlen is the maximum length the modified string will have
* If the original string is shorter than "maxlen", it is returned verbatim
*/
static QString lsqueeze( const QString & str, uint maxlen = 40 );
/** Substitute characters at the middle of a string by "...".
* @return the modified string
* @param str is the string to modify
* @param maxlen is the maximum length the modified string will have
* If the original string is shorter than "maxlen", it is returned verbatim
*/
static QString csqueeze( const QString & str, uint maxlen = 40 );
/** Substitute characters at the end of a string by "...".
* @return the modified string
* @param str is the string to modify
* @param maxlen is the maximum length the modified string will have
* If the original string is shorter than "maxlen", it is returned verbatim
*/
static QString rsqueeze( const QString & str, uint maxlen = 40 );
/**
* @return true if the given filename matches the given pattern
* @param filename is the real decoded filename (or dirname
* without trailing '/').
* @param pattern is a pattern like *.txt, *.tar.gz, Makefile.*, etc.
* Patterns with two asterisks like "*.*pk" are not supported.
*/
static bool matchFilename( const QString& filename, const QString& pattern );
/**
* 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"
*
* @return A QStringList containing tokens extracted from s.
* @param sep is the string to use to delimit s.
* @param max is the maximum number of extractions to perform, or 0.
*/
static 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. 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"
*
* @return A QStringList containing tokens extracted from s.
* @param sep is the character to use to delimit s.
* @param max is the maximum number of extractions to perform, or 0.
*/
static 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. 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 ?"
*
* @return A QStringList containing tokens extracted from s.
* @param sep is the regular expression to use to delimit s.
* @param max is the maximum number of extractions to perform, or 0.
*/
static QStringList perlSplit
(const QRegExp & sep, const QString & s, uint max = 0);
};
#endif
| Generated by: dfaure on kde.faure.org on Thu Jan 17 22:15:01 2002, using kdoc 2.0a53. |