org.kde.koala
Class KStringHandler

java.lang.Object
  extended by org.kde.koala.KStringHandler
All Implemented Interfaces:
org.kde.qt.QtSupport

public class KStringHandler
extends java.lang.Object
implements org.kde.qt.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

Constructor Summary
  KStringHandler()
           
protected KStringHandler(java.lang.Class dummy)
           
 
Method Summary
static java.lang.String capwords(java.lang.String text)
          Capitalizes each word in the string "hello there" becomes "Hello There" (string)
static java.util.ArrayList capwords(java.lang.String[] list)
          Capitalizes each word in the list [hello, there] becomes [Hello, There] (list)
static java.lang.String cEmSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics)
           
static java.lang.String cEmSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics, int maxlen)
          Substitute characters in the middle of a string by "...".
static java.lang.String center(java.lang.String text, int width)
          Centers a string and returns a string at least 'width' characters wide.
static java.lang.String cPixelSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics, int maxPixels)
          Substitute characters in the middle of a string by "...".
static java.lang.String csqueeze(java.lang.String str)
           
static java.lang.String csqueeze(java.lang.String str, int maxlen)
          Substitute characters at the middle of a string by "...".
 void dispose()
          Delete the wrapped C++ instance ahead of finalize()
protected  void finalize()
          Deletes the wrapped C++ instance
static java.lang.String from8Bit(java.lang.String str)
          Construct String from a c string, guessing whether it is UTF8- or Local8Bit-encoded.
static java.lang.String insword(java.lang.String text, java.lang.String word, int pos)
          Inserts a word into the string, and returns a new string with the word included.
 boolean isDisposed()
          Has the wrapped C++ instance been deleted?
static boolean isUtf8(java.lang.String str)
          Guess whether a string is UTF8 encoded.
static java.lang.String lEmSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics)
           
static java.lang.String lEmSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics, int maxlen)
          Substitute characters at the beginning of a string by "...".
static java.lang.String lPixelSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics, int maxPixels)
          Substitute characters at the beginning of a string by "...".
static java.lang.String lsqueeze(java.lang.String str)
           
static java.lang.String lsqueeze(java.lang.String str, int maxlen)
          Substitute characters at the beginning of a string by "...".
static boolean matchFileName(java.lang.String filename, java.lang.String pattern)
          Match a filename.
static java.lang.String obscure(java.lang.String str)
          Obscure string by using a simple symmetric encryption.
static java.util.ArrayList perlSplit(char sep, java.lang.String s)
           
static java.util.ArrayList perlSplit(char sep, java.lang.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 java.util.ArrayList perlSplit(org.kde.qt.QRegExp sep, java.lang.String s)
           
static java.util.ArrayList perlSplit(org.kde.qt.QRegExp sep, java.lang.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 java.util.ArrayList perlSplit(java.lang.String sep, java.lang.String s)
           
static java.util.ArrayList perlSplit(java.lang.String sep, java.lang.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 java.lang.String remrange(java.lang.String text, java.lang.String range)
          Removes a word or ranges of words from the string, and returns a new string.
static java.lang.String rEmSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics)
           
static java.lang.String rEmSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics, int maxlen)
          Substitute characters at the end of a string by "...".
static java.lang.String remword(java.lang.String text, int pos)
          Removes a word at the given index, and returns a new string.
static java.lang.String remword(java.lang.String text, java.lang.String word)
          Removes a matching word from the string, and returns a new string.
static java.lang.String reverse(java.lang.String text)
          Reverses the order of the words in a string "hello there" becomes "there hello" (string)
static java.util.ArrayList reverse(java.lang.String[] list)
          Reverses the order of the words in a list [hello, there] becomes [there, hello] (list)
static java.lang.String rPixelSqueeze(java.lang.String name, org.kde.qt.QFontMetrics fontMetrics, int maxPixels)
          Substitute characters at the end of a string by "...".
static java.lang.String rsqueeze(java.lang.String str)
           
static java.lang.String rsqueeze(java.lang.String str, int maxlen)
          Substitute characters at the end of a string by "...".
static java.lang.String setword(java.lang.String text, java.lang.String word, int pos)
          Replaces a word in the string, and returns a new string with the word included.
static java.lang.String tagURLs(java.lang.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 java.lang.String word(java.lang.String text, java.lang.String range)
          Returns a range of words from that string.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KStringHandler

protected KStringHandler(java.lang.Class dummy)

KStringHandler

public KStringHandler()
Method Detail

word

public static java.lang.String word(java.lang.String text,
                                    java.lang.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

    insword

    public static java.lang.String insword(java.lang.String text,
                                           java.lang.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

    setword

    public static java.lang.String setword(java.lang.String text,
                                           java.lang.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

    remrange

    public static java.lang.String remrange(java.lang.String text,
                                            java.lang.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

    remword

    public static java.lang.String remword(java.lang.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

    remword

    public static java.lang.String remword(java.lang.String text,
                                           java.lang.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

    capwords

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

    Parameters:
    text - the text to capitalize
    Returns:
    the resulting string

    capwords

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

    Parameters:
    list - the list to capitalize
    Returns:
    the resulting list

    reverse

    public static java.lang.String reverse(java.lang.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

    reverse

    public static java.util.ArrayList reverse(java.lang.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

    center

    public static java.lang.String center(java.lang.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

    lsqueeze

    public static java.lang.String lsqueeze(java.lang.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

    lsqueeze

    public static java.lang.String lsqueeze(java.lang.String str)

    lEmSqueeze

    public static java.lang.String lEmSqueeze(java.lang.String name,
                                              org.kde.qt.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

    lEmSqueeze

    public static java.lang.String lEmSqueeze(java.lang.String name,
                                              org.kde.qt.QFontMetrics fontMetrics)

    lPixelSqueeze

    public static java.lang.String lPixelSqueeze(java.lang.String name,
                                                 org.kde.qt.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

    csqueeze

    public static java.lang.String csqueeze(java.lang.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

    csqueeze

    public static java.lang.String csqueeze(java.lang.String str)

    cEmSqueeze

    public static java.lang.String cEmSqueeze(java.lang.String name,
                                              org.kde.qt.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

    cEmSqueeze

    public static java.lang.String cEmSqueeze(java.lang.String name,
                                              org.kde.qt.QFontMetrics fontMetrics)

    cPixelSqueeze

    public static java.lang.String cPixelSqueeze(java.lang.String name,
                                                 org.kde.qt.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

    rsqueeze

    public static java.lang.String rsqueeze(java.lang.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

    rsqueeze

    public static java.lang.String rsqueeze(java.lang.String str)

    rEmSqueeze

    public static java.lang.String rEmSqueeze(java.lang.String name,
                                              org.kde.qt.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

    rEmSqueeze

    public static java.lang.String rEmSqueeze(java.lang.String name,
                                              org.kde.qt.QFontMetrics fontMetrics)

    rPixelSqueeze

    public static java.lang.String rPixelSqueeze(java.lang.String name,
                                                 org.kde.qt.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

    matchFileName

    public static boolean matchFileName(java.lang.String filename,
                                        java.lang.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

    perlSplit

    public static java.util.ArrayList perlSplit(java.lang.String sep,
                                                java.lang.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.

    perlSplit

    public static java.util.ArrayList perlSplit(java.lang.String sep,
                                                java.lang.String s)

    perlSplit

    public static java.util.ArrayList perlSplit(char sep,
                                                java.lang.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.

    perlSplit

    public static java.util.ArrayList perlSplit(char sep,
                                                java.lang.String s)

    perlSplit

    public static java.util.ArrayList perlSplit(org.kde.qt.QRegExp sep,
                                                java.lang.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.

    perlSplit

    public static java.util.ArrayList perlSplit(org.kde.qt.QRegExp sep,
                                                java.lang.String s)

    tagURLs

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

    obscure

    public static java.lang.String obscure(java.lang.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

    isUtf8

    public static boolean isUtf8(java.lang.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.

    from8Bit

    public static java.lang.String from8Bit(java.lang.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

    finalize

    protected void finalize()
                     throws java.lang.InternalError
    Deletes the wrapped C++ instance

    Overrides:
    finalize in class java.lang.Object
    Throws:
    java.lang.InternalError

    dispose

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


    isDisposed

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