org.kde.koala

Class KStringHandler

public class KStringHandler extends Object implements QtSupport

This class contains utility functions for handling strings. This class is not a substitute for the String 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(String, String ) and remword(String, uint) functions for more detail. This class contains no data members of its own. All strings are cut on the fly and returned as new qstrings/qstringlists. Quick example on how to use:
 KStringHandler kstr;
 String 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

See Also: KShell

UNKNOWN: Class for manipulating words and sentences in strings.

Constructor Summary
protected KStringHandler(Class dummy)
KStringHandler()
Method Summary
static Stringcapwords(String text)
Capitalizes each word in the string "hello there" becomes "Hello There" (string)
static ArrayListcapwords(String[] list)
Capitalizes each word in the list [hello, there] becomes [Hello, There] (list)
static Stringcenter(String text, int width)
Centers a string and returns a string at least 'width' characters wide.
static StringcEmSqueeze(String name, QFontMetrics fontMetrics, int maxlen)
Substitute characters in the middle of a string by "...".
static StringcEmSqueeze(String name, QFontMetrics fontMetrics)
static StringcPixelSqueeze(String name, QFontMetrics fontMetrics, int maxPixels)
Substitute characters in the middle of a string by "...".
static Stringcsqueeze(String str, int maxlen)
Substitute characters at the middle of a string by "...".
static Stringcsqueeze(String str)
voiddispose()
Delete the wrapped C++ instance ahead of finalize()
protected voidfinalize()
Deletes the wrapped C++ instance
static Stringfrom8Bit(String str)
Construct String from a c string, guessing whether it is UTF8- or Local8Bit-encoded.
static Stringinsword(String text, String word, int pos)
Inserts a word into the string, and returns a new string with the word included. the first index is zero (0).
booleanisDisposed()
Has the wrapped C++ instance been deleted?
static booleanisUtf8(String str)
Guess whether a string is UTF8 encoded.
static StringlEmSqueeze(String name, QFontMetrics fontMetrics, int maxlen)
Substitute characters at the beginning of a string by "...".
static StringlEmSqueeze(String name, QFontMetrics fontMetrics)
static StringlPixelSqueeze(String name, QFontMetrics fontMetrics, int maxPixels)
Substitute characters at the beginning of a string by "...".
static Stringlsqueeze(String str, int maxlen)
Substitute characters at the beginning of a string by "...".
static Stringlsqueeze(String str)
static booleanmatchFileName(String filename, String pattern)
Match a filename.
static Stringobscure(String str)
Obscure string by using a simple symmetric encryption.
static ArrayListperlSplit(String sep, String s, int max)
Split a String into an ArrayList in a similar fashion to the static ArrayList function in Qt, except you can specify a maximum number of tokens.
static ArrayListperlSplit(String sep, String s)
static ArrayListperlSplit(char sep, String s, int max)
Split a String into an ArrayList in a similar fashion to the static ArrayList function in Qt, except you can specify a maximum number of tokens.
static ArrayListperlSplit(char sep, String s)
static ArrayListperlSplit(QRegExp sep, String s, int max)
Split a String into an ArrayList in a similar fashion to the static ArrayList function in Qt, except you can specify a maximum number of tokens.
static ArrayListperlSplit(QRegExp sep, String s)
static Stringremrange(String text, String range)
Removes a word or ranges of words from the string, and returns a new string.
static Stringremword(String text, int pos)
Removes a word at the given index, and returns a new string.
static Stringremword(String text, String word)
Removes a matching word from the string, and returns a new string.
static Stringreverse(String text)
Reverses the order of the words in a string "hello there" becomes "there hello" (string)
static ArrayListreverse(String[] list)
Reverses the order of the words in a list [hello, there] becomes [there, hello] (list)
static StringrEmSqueeze(String name, QFontMetrics fontMetrics, int maxlen)
Substitute characters at the end of a string by "...".
static StringrEmSqueeze(String name, QFontMetrics fontMetrics)
static StringrPixelSqueeze(String name, QFontMetrics fontMetrics, int maxPixels)
Substitute characters at the end of a string by "...".
static Stringrsqueeze(String str, int maxlen)
Substitute characters at the end of a string by "...".
static Stringrsqueeze(String str)
static Stringsetword(String text, String word, int pos)
Replaces a word in the string, and returns a new string with the word included. the first index is zero (0).
static StringtagURLs(String 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.
static Stringword(String text, String range)
Returns a range of words from that string.

Constructor Detail

KStringHandler

protected KStringHandler(Class dummy)

KStringHandler

public KStringHandler()

Method Detail

capwords

public static String capwords(String text)
Capitalizes each word in the string "hello there" becomes "Hello There" (string)

Parameters: text the text to capitalize

Returns: the resulting string

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

capwords

public static ArrayList capwords(String[] list)
Capitalizes each word in the list [hello, there] becomes [Hello, There] (list)

Parameters: list the list to capitalize

Returns: the resulting list

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

center

public static String center(String text, int width)
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

UNKNOWN: Centers a string and returns a string at least 'width' characters wide.

cEmSqueeze

public static String cEmSqueeze(String name, QFontMetrics fontMetrics, int maxlen)
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

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

cEmSqueeze

public static String cEmSqueeze(String name, QFontMetrics fontMetrics)

cPixelSqueeze

public static String cPixelSqueeze(String name, QFontMetrics fontMetrics, int maxPixels)
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

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

csqueeze

public static String csqueeze(String str, int maxlen)
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

UNKNOWN: Substitute characters at the middle of a string by ".

csqueeze

public static String csqueeze(String str)

dispose

public void dispose()
Delete the wrapped C++ instance ahead of finalize()

finalize

protected void finalize()
Deletes the wrapped C++ instance

from8Bit

public static String from8Bit(String str)
Construct String from a c string, guessing whether it is UTF8- or Local8Bit-encoded.

Parameters: str the input string

Returns: the (hopefully correctly guessed) String representation of str

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

insword

public static String insword(String text, String word, int pos)
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

UNKNOWN: Inserts a word into the string, and returns a new string with the word included.

isDisposed

public boolean isDisposed()
Has the wrapped C++ instance been deleted?

isUtf8

public static boolean isUtf8(String str)
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.

UNKNOWN: Guess whether a string is UTF8 encoded.

lEmSqueeze

public static String lEmSqueeze(String name, QFontMetrics fontMetrics, int maxlen)
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

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

lEmSqueeze

public static String lEmSqueeze(String name, QFontMetrics fontMetrics)

lPixelSqueeze

public static String lPixelSqueeze(String name, QFontMetrics fontMetrics, int maxPixels)
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

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

lsqueeze

public static String lsqueeze(String str, int maxlen)
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

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

lsqueeze

public static String lsqueeze(String str)

matchFileName

public static boolean matchFileName(String filename, String pattern)
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

UNKNOWN: Match a filename.

obscure

public static String obscure(String str)
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

UNKNOWN: Obscure string by using a simple symmetric encryption.

perlSplit

public static ArrayList perlSplit(String sep, String s, int max)
Split a String into an ArrayList in a similar fashion to the static ArrayList 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)
		 ArrayList 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: An ArrayList containing tokens extracted from s.

UNKNOWN: Split a String into an ArrayList in a similar fashion to the static ArrayList function in Qt, except you can specify a maximum number of tokens.

perlSplit

public static ArrayList perlSplit(String sep, String s)

perlSplit

public static ArrayList perlSplit(char sep, String s, int max)
Split a String into an ArrayList in a similar fashion to the static ArrayList 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)
		 ArrayList 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: An ArrayList containing tokens extracted from s.

UNKNOWN: Split a String into an ArrayList in a similar fashion to the static ArrayList function in Qt, except you can specify a maximum number of tokens.

perlSplit

public static ArrayList perlSplit(char sep, String s)

perlSplit

public static ArrayList perlSplit(QRegExp sep, String s, int max)
Split a String into an ArrayList in a similar fashion to the static ArrayList 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)
		 ArrayList 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: An ArrayList containing tokens extracted from s.

UNKNOWN: Split a String into an ArrayList in a similar fashion to the static ArrayList function in Qt, except you can specify a maximum number of tokens.

perlSplit

public static ArrayList perlSplit(QRegExp sep, String s)

remrange

public static String remrange(String text, String range)
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

    UNKNOWN: Removes a word or ranges of words from the string, and returns a new string.

    remword

    public static String remword(String text, int pos)
    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

    UNKNOWN: Removes a word at the given index, and returns a new string.

    remword

    public static String remword(String text, String word)
    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

    UNKNOWN: Removes a matching word from the string, and returns a new string.

    reverse

    public static String reverse(String text)
    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

    UNKNOWN: Reverses the order of the words in a string "hello there" becomes "there hello" (string)

    reverse

    public static ArrayList reverse(String[] list)
    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

    UNKNOWN: Reverses the order of the words in a list [hello, there] becomes [there, hello] (list)

    rEmSqueeze

    public static String rEmSqueeze(String name, QFontMetrics fontMetrics, int maxlen)
    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

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

    rEmSqueeze

    public static String rEmSqueeze(String name, QFontMetrics fontMetrics)

    rPixelSqueeze

    public static String rPixelSqueeze(String name, QFontMetrics fontMetrics, int maxPixels)
    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

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

    rsqueeze

    public static String rsqueeze(String str, int maxlen)
    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

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

    rsqueeze

    public static String rsqueeze(String str)

    setword

    public static String setword(String text, String word, int pos)
    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

    UNKNOWN: Replaces a word in the string, and returns a new string with the word included.

    tagURLs

    public static String tagURLs(String 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.

    Parameters: text the string which may contain URLs

    Returns: the resulting text

    UNKNOWN: 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.

    word

    public static String word(String text, String range)
    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

    UNKNOWN: Returns a range of words from that string.