com.javaranch.common
Class Str

java.lang.Object
  |
  +--com.javaranch.common.Str

public class Str

extends java.lang.Object

A robust string processing class.

The Java String and StringBuffer classes are final. So it is not possible to inherit all of the functionality of one of those classes and enhance it with a few more methods.

This class attempts to provide all of the functionality found in both String and StringBuffer, plus provide a wide collection of additional functionality.

This class internally functions more like StringBuffer than String. If a Str object is appended and needs to grow beyond its current size, it will do so without programmer intervention. It also keeps a little extra buffer of size to accomodate small amounts of growth without needing memory re-allocation.

- - - - - - - - - - - - - - - - -

Copyright (c) 1998-2004 Paul Wheaton

You are welcome to do whatever you want to with this source file provided that you maintain this comment fragment (between the dashed lines). Modify it, change the package name, change the class name ... personal or business use ... sell it, share it ... add a copyright for the portions you add ...

My goal in giving this away and maintaining the copyright is to hopefully direct developers back to JavaRanch.

The original source can be found at JavaRanch

- - - - - - - - - - - - - - - - -

Author:

Paul Wheaton

Constructor Summary

Str()
The object has memory allocated to store an average size string.

Str(char[] c)
The object is inititialized to have an exact copy of the character array.

Str(int initialSize)
Set the object to have an initial capacity.

Str(int initialSize, int initialExtra)
Create an object with a specific initial capacity and to be able to grow by a specific increment.

Str(Str s)
A new object is created that is an exact copy of the provided Str object.

Str(java.lang.String s)
A new object is created that contains a copy of the provided String object.

Method Summary

Str	after(int index) Get all of the substring that occurs after a particular character.
static java.lang.String	after(java.lang.String s, int index) Get all of the substring that occurs after a particular character.
void	append(char c) Add one character to the end of the string.
void	append(Str s) Append a string on to the end of your string.
void	append(java.lang.String s) Append a string on to the end of your string.
static double	atod(java.lang.String s) Like the ANSI c function atod().
static int	atoi(char c) Sort of like the ANSI c function atoi().
static int	atoi(java.lang.String s) Like the ANSI c function atoi().
Str	before(int index) Get all of the substring that occurs before a particular character.
static java.lang.String	before(java.lang.String s, int index) Get all of the substring that occurs before a particular character.
void	center(int newLen) Try to center the text in a pad of spaces.
static java.lang.String	center(java.lang.String s, int newLen) Try to center the text in a pad of spaces.
char	charAt(int Index) Used for compatibility with String and StringBuffer.
int	charCount(char c) Count how many times a particular character occurs within your string.
static java.lang.String	commaStr(double val) Converts a double to a string with commas inserted for thousands, millions, etc.
int	compareTo(Str s) A string comparison method that returns a numeric result.
int	compareTo(java.lang.String s) A string comparison method that returns a numeric result.
int	countDigits()
int	countRange(char low, char high) the number of digits that occur within this range.
void	delete(int index, int howMany) Remove characters from your string.
void	deleteFirst() Remove first character from the beginning of your string.
void	deleteFirst(int howMany) Remove characters from the beginning of your string.
void	deleteLast() Remove the last character from the end of your string.
void	deleteLast(int howMany) Remove characters from the end of your string.
boolean	endsWith(java.lang.String s) Does the string object end with this bit of text.
boolean	eq(Str s) Test for equality between your string and the string in s.
boolean	eq(java.lang.String s) Test for equality between your string and the string in s.
static boolean	equal(java.lang.String[] s1, java.lang.String[] s2) Uses String.equals(), but will consider that either or both arrays/strings might be null.
static boolean	equal(java.lang.String s1, java.lang.String s2) Uses String.equals(), but will consider that either or both strings might be null.
boolean	equals(java.lang.Object obj)
Str	extractWord() Extract and return the first word.
int	firstDigit() Returns the index of the first digit, or returns -1 if there are no digits.
void	forceNumeric() Force string to be the first number found.
static java.lang.String	formatDouble(double d, int decimalPlaces) Converts a double to a string with a specified number of decimal places.
Str	from(int index) Get all of the substring that occurs from a particular character to the end of the string.
static java.lang.String	from(java.lang.String s, int index) Get all of the substring that occurs from a particular character to the end of the string.
boolean	ge(Str s) Test for "greater than or equal to" between your string and the string in s.
boolean	ge(java.lang.String s) Test for "greater than or equal to" between your string and the string in s.
char	get(int Index) Retrieve a copy of one character.
Str	get(int index, int length) Retrieve a copy of a substring.
int	getCapacity() Get the number of characters this object can hold without doing a reallocation.
static char	getChar(java.lang.String s, int index) Just like String.charAt() except for null strings or for strings that are too short, an exception will not be thrown and instead, a null char will be returned.
char	getLast() Retrieve a copy of the last character.
boolean	gt(Str s) Test for "greater than" between your string and the string in s.
boolean	gt(java.lang.String s) Test for "greater than" between your string and the string in s.
int	hashCode()
int	indexOf(char c) Find the position within your string of a particular character.
int	indexOf(char c, int startPos) Find the position within your string of a particular character.
int	indexOf(java.lang.String s) Find the position within your string of a particular sequence of characters.
int	indexOf(java.lang.String s, int startPos) Find the position within your string of a particular sequence of characters.
int	indexOfIgnoreCase(char c) Find the position within your string of a particular character, ignoring case.
int	indexOfIgnoreCase(char c, int startPos) Find the position within your string of a particular character, ignoring case.
int	indexOfIgnoreCase(java.lang.String s) Find the position within your string of a particular sequence of characters, ignoring case.
int	indexOfIgnoreCase(java.lang.String s, int startPos) Find the position within your string of a particular sequence of characters, ignoring the case.
void	insert(char c, int index) Insert a character immediately before a particular character.
void	insert(java.lang.String s, int index) Insert a String object immediately before a particular character.
void	insert(Str s, int index) Insert a Str object immediately before a particular character.
boolean	isLower(int index) Is char at index lower case?
boolean	isUpper(int index) Is char at index upper case?
int	lastIndexOf(char c)
boolean	le(Str s) Test for "less than or equal to" between your string and the string in s.
boolean	le(java.lang.String s) Test for "less than or equal to" between your string and the string in s.
void	left(int newLen) Force the length of the string and keep text to the left.
static java.lang.String	left(java.lang.String s, int newLen) Force the length of the string and keep text to the left.
int	leftSpaceCount() Report how many leading spaces there are.
int	length() Get the current length of your string - not the same as the amount of memory allocated.
boolean	lt(Str s) Test for "less than" between your string and the string in s.
boolean	lt(java.lang.String s) Test for "less than" between your string and the string in s.
static java.lang.String	moneyStr(double d) Converts a double to a string with two decimal places.
boolean	ne(Str s) Test for "not equal" between your string and the string in s.
boolean	ne(java.lang.String s) Test for "not equal" between your string and the string in s.
static java.lang.String	normalize(java.lang.Object s) Return a string that is not null.
static java.lang.String	nowStr() Get the current local date and time.
char	pop() If you wish to treat your string like a stack, you can push and pop characters.
void	push(char c) If you wish to treat your string like a stack, you can push and pop characters.
void	removeDoubleSpaces() Eliminate all occurances of two more space in a row.
void	replace(char c1, char c2) Replace all instances of one character with another character.
void	replace(char c, java.lang.String s) Replace all instances of one character with a String object.
void	replace(java.lang.String s, char c) Search for a particular character sequence and replace it with one character.
void	replace(java.lang.String s1, java.lang.String s2) Search for a particular character sequence and replace it with a different character sequence.
void	reverse() Reverse the order of all the characters.
void	right(int newLen) Force the length of the string and keep text to the right.
static java.lang.String	right(java.lang.String s, int newLen) Force the length of the string and keep text to the right.
int	rightSpaceCount() Report how many trailing spaces there are.
void	set(int index, char c) Set one character in the string.
void	set(Str s) Force the contents of this object to be the same as another Str object.
void	set(java.lang.String s) Force the contents of this object to be the same as a String object.
void	setCapacity(int howMuch) Force this object to be able to hold a specific number of characters without reallocation.
void	setCharAt(int index, char c) Provided for compatibility with StringBuffer.
void	setExtra(int howMuch) Set how much extra to grow when growth is needed.
void	setLength(int newLen) Force the length of your string.
static Str	spaces(int quan) Create a Str object containing nothing but a quantity of spaces.
boolean	startsWith(java.lang.String s) Test to see if your string begins with a specific sequence of characters.
static Str	stringOf(int quan, char c) Create a Str object containing nothing but a quantity of one character.
Str	substring(int index, int length) Provided for compatibility with String and StringBuffer and the case mixing Sun provides.
Str	subString(int index, int length) Provided for compatibility with String and StringBuffer and the case mixing many people expect.
static java.lang.String	substring(java.lang.String s, int index, int length) Same as subString, but allows all lower case.
static java.lang.String	subString(java.lang.String s, int index, int length) A static sub-string method that works the way you expect it to work.
Str	through(int index) Get all of the substring that occurs through a particular character.
static java.lang.String	through(java.lang.String s, int index) Get all of the substring that occurs through a particular character.
static boolean	toBoolean(java.lang.String s) Try to convert a string to a boolean value.
char[]	toCharArray() Generate a character array that contains a copy of the string.
double	toDouble() Try to convert this string to a double value.
static double	toDouble(java.lang.String s) Try to convert a string to a double value.
int	toInt() Try to convert this string to an integer value.
static int	toInt(java.lang.String s) Try to convert a string to an integer value.
static int[]	toIntArray(java.lang.String[] values)
long	toLong() Try to convert this string to a long value.
static long	toLong(java.lang.String s) Try to convert a string to a long value.
void	toLower() All characters are forced to lower case.
void	toLower(int index) Char at index is forced to lower case.
java.lang.String	toString() Convert this Str object to a String object.
static java.lang.String[]	toStringArray(int[] values)
static java.sql.Timestamp	toTimestamp(java.lang.String s) Try to convert a string to a Timestamp object.
void	toUpper() All characters are forced to upper case.
void	toUpper(int index) Char at index is forced to upper case.
int	trailingDigits() Count the number of trailing digits.
static int	trailingDigits(java.lang.String s) Count the number of trailing digits.
void	trim() Trims all leading spaces and all trailing spaces.
static java.lang.String	trim(java.lang.String s) Return a string that is either null or has at least one character.
void	trimLead() Trims all leading spaces, no trailing spaces.
void	trimLeadWhitespace() Trims all leading spaces, newlines, returns and tabs.
void	trimTrail() Trims all trailing spaces, no leading spaces.
void	trimTrailTo(char c) Trims all characters from end of the string until a particular character is encountered.
void	trimTrailWhitespace() Trims all trailing spaces, newlines, returns and tabs.
void	trimWhitespace() Trims all leading spaces, newlines, returns and tabs and all trailing spaces, newlines, returns and tabs.
static java.lang.String	trimWhitespace(java.lang.String s)
static boolean	usable(java.lang.String s)
static Str	verboseMoney(double x) Convert a double to English ( 12.01 -> "twelve and 01/100" ).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Str

public Str(int initialSize)

Set the object to have an initial capacity.

Parameters:

initialSize - How many characters the object can initially hold.

Str

public Str(int initialSize,
           int initialExtra)

Create an object with a specific initial capacity and to be able to grow by a specific increment.

Parameters:

initialSize - How many characters the object can initially hold.

initialExtra - How many characters the object will grow by when more memory is needed.

Str

public Str()

The object has memory allocated to store an average size string.

Str

public Str(char[] c)

The object is inititialized to have an exact copy of the character array. Enough memory is allocated for some growth.

Parameters:

c - the character array to copy.

Str

public Str(Str s)

A new object is created that is an exact copy of the provided Str object.

Enough memory is allocated for some growth.

Parameters:

s - The Str object to copy.

Str

public Str(java.lang.String s)

A new object is created that contains a copy of the provided String object. Enough memory is allocated for some growth.

Parameters:

s - The String object to copy.

Method Detail

set

public void set(Str s)

Force the contents of this object to be the same as another Str object.

Parameters:

s - The Str object to copy.

set

public void set(java.lang.String s)

Force the contents of this object to be the same as a String object.

Parameters:

s - The String object to copy.

length

public int length()

Get the current length of your string - not the same as the amount of memory allocated.

Works just like the length() methods in String and StringBuffer.

Returns:

The current string length.

setLength

public void setLength(int newLen)

Force the length of your string.

If you want to empty your string, use setLength(0);

If you specify a number that is longer than the current string length, the new characters will be null characters.

Parameters:

newLen - what you want the new length of your string to be.

compareTo

public int compareTo(Str s)

A string comparison method that returns a numeric result.

A lot like the ANSI strcmp() function.

Parameters:

s - The Str object to compare to.

Returns:

0 If this is equal to s, a negative value if this is less than s, a positive value if this is greater than s.

compareTo

public int compareTo(java.lang.String s)

A string comparison method that returns a numeric result.

A lot like the ANSI strcmp() function.

Parameters:

s - the String object to compare to.

Returns:

0 if this is equal to s, a negative value if this is less than s, a positive value if this is greater than s.

eq

public boolean eq(Str s)

Test for equality between your string and the string in s.

This method is case sensitive.

Parameters:

s - The Str object to compare to.

Returns:

True if s is identical.

eq

public boolean eq(java.lang.String s)

Test for equality between your string and the string in s.

This method is case sensitive.

Parameters:

s - The String object to compare to.

Returns:

True if s is identical.

ne

public boolean ne(Str s)

Test for "not equal" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The Str object to compare to.

Returns:

False if s is identical.

ne

public boolean ne(java.lang.String s)

Test for "not equal" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The String object to compare to.

Returns:

False if s is identical.

lt

public boolean lt(Str s)

Test for "less than" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The Str object to compare to.

Returns:

True if your string is "less than" s.

lt

public boolean lt(java.lang.String s)

Test for "less than" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The String object to compare to.

Returns:

True if your string is "less than" s.

le

public boolean le(Str s)

Test for "less than or equal to" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The Str object to compare to.

Returns:

True if your string is "less than or equal to" s.

le

public boolean le(java.lang.String s)

Test for "less than or equal to" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The String object to compare to.

Returns:

True if your string is "less than or equal to" s.

ge

public boolean ge(Str s)

Test for "greater than or equal to" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The Str object to compare to.

Returns:

True if your string is "greater than or equal to" s.

ge

public boolean ge(java.lang.String s)

Test for "greater than or equal to" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The String object to compare to.

Returns:

True if your string is "greater than or equal to" s.

gt

public boolean gt(Str s)

Test for "greater than" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The Str object to compare to.

Returns:

True if your string is "greater than" s.

gt

public boolean gt(java.lang.String s)

Test for "greater than" between your string and the string in s.

This method is case sensitive.

Parameters:

s - The String object to compare to.

Returns:

True if your string is "greater than" s.

setExtra

public void setExtra(int howMuch)

Set how much extra to grow when growth is needed.

Smaller values will usually save memory, but frequent reallocation may take a lot of time.

Parameters:

howMuch - The number of extra characters to allocate when memory reallocation is required. Values must be greater than zero.

getCapacity

public int getCapacity()

Get the number of characters this object can hold without doing a reallocation.

Returns:

The number of characters this object can currently hold without reallocation.

setCapacity

public void setCapacity(int howMuch)

Force this object to be able to hold a specific number of characters without reallocation.

Any attempt to make the string grow bigger than this size will succeed.

Setting the capacity to be smaller than the current string size will result in trailing characters being clipped.

Parameters:

howMuch - How many characters will be the new capacity.

get

public char get(int Index)

Retrieve a copy of one character.

Parameters:

Index - Which character (0 is the first character).

Returns:

The retrieved character. Returns a null character if Index is outside of 0..length.

getLast

public char getLast()

Retrieve a copy of the last character.

Returns:

The retrieved character. Returns a null character if the string is empty.

charAt

public char charAt(int Index)

Used for compatibility with String and StringBuffer.

see get().

get

public Str get(int index,
               int length)

Retrieve a copy of a substring.

Parameters:

index - The character of the substring.

length - The length of the substring. Specifying a substring beyond the end of the string will return as much of the string as possible.

Returns:

A Str object containing the substring.

subString

public Str subString(int index,
                     int length)

Provided for compatibility with String and StringBuffer and the case mixing many people expect.

substring

public Str substring(int index,
                     int length)

Provided for compatibility with String and StringBuffer and the case mixing Sun provides.

before

public Str before(int index)

Get all of the substring that occurs before a particular character.

Parameters:

index - The character that marks the end of the substring. This character is not included in the substring.

Returns:

A Str object containing the substring.

through

public Str through(int index)

Get all of the substring that occurs through a particular character.

Parameters:

index - The character that marks the end of the substring. This character is included in the substring.

Returns:

A Str object containing the substring.

after

public Str after(int index)

Get all of the substring that occurs after a particular character.

Parameters:

index - The character that marks the beginning of the substring. This character is not included in the substring.

Returns:

A Str object containing the substring.

from

public Str from(int index)

Get all of the substring that occurs from a particular character to the end of the string.

Parameters:

index - The character that marks the beginning of the substring. This character is included in the substring.

Returns:

A Str object containing the substring.

toCharArray

public char[] toCharArray()

Generate a character array that contains a copy of the string.

Returns:

A new char array.

set

public void set(int index,
                char c)

Set one character in the string.

Parameters:

index - Which character to set. If index references a character beyond the last character of the string, the string will be lengthened and the last character will be set appropriately (undefined characters will be set to a null character).

c - The character to be placed at index.

setCharAt

public void setCharAt(int index,
                      char c)

Provided for compatibility with StringBuffer.

append

public void append(char c)

Add one character to the end of the string.

Parameters:

c - The character to append to the end of the string.

append

public void append(Str s)

Append a string on to the end of your string.

Parameters:

s - The Str object to be appended.

append

public void append(java.lang.String s)

Append a string on to the end of your string.

Parameters:

s - The String object to be appended.

insert

public void insert(char c,
                   int index)

Insert a character immediately before a particular character.

Parameters:

c - The character to be inserted.

index - Where to insert c. The character currently at index will me moved to the right.

insert

public void insert(Str s,
                   int index)

Insert a Str object immediately before a particular character.

Parameters:

s - The Str object to be inserted.

index - Where to insert s. The character currently at index will me moved to the right.

insert

public void insert(java.lang.String s,
                   int index)

Insert a String object immediately before a particular character.

Parameters:

s - The String object to be inserted.

index - Where to insert s. The character currently at index will me moved to the right.

delete

public void delete(int index,
                   int howMany)

Remove characters from your string.

Parameters:

index - Referencing the first character to be removed.

howMany - The number of characters to remove.

deleteFirst

public void deleteFirst(int howMany)

Remove characters from the beginning of your string.

Parameters:

howMany - The number of characters to remove.

deleteFirst

public void deleteFirst()

Remove first character from the beginning of your string.

deleteLast

public void deleteLast(int howMany)

Remove characters from the end of your string.

Parameters:

howMany - The number of characters to remove.

deleteLast

public void deleteLast()

Remove the last character from the end of your string.

push

public void push(char c)

If you wish to treat your string like a stack, you can push and pop characters.

Parameters:

c - The character that will be appended to the end of your string.

pop

public char pop()

If you wish to treat your string like a stack, you can push and pop characters.

Remember the old assembly programming pearl: May all your pushes be popped.

Returns:

The last character in your string. If there are no more characters in the string, a null character is returned.

startsWith

public boolean startsWith(java.lang.String s)

Test to see if your string begins with a specific sequence of characters.

This test is much faster than the equivalent in the regular expression library. And is also much faster than doing a substring comparison.

This test is case sensitive.

Parameters:

s - A String object representing the first few characters being tested for.

Returns:

True if s matches the beginning of your string exactly.

indexOf

public int indexOf(char c,
                   int startPos)

Find the position within your string of a particular character.

This method is case sensitive.

Parameters:

c - The character to search for.

startPos - The character position in your string to start looking for c.

Returns:

The position of the character that matches c where 0 is the first character of the string. -1 is returned if a matching character could not be found.

indexOfIgnoreCase

public int indexOfIgnoreCase(char c,
                             int startPos)

Find the position within your string of a particular character, ignoring case.

This method is not case sensitive.

Parameters:

c - The character to search for.

startPos - The character position in your string to start looking for c.

Returns:

The position of the character that matches c where 0 is the first character of the string. -1 is returned if a matching character could not be found.

indexOf

public int indexOf(java.lang.String s,
                   int startPos)

Find the position within your string of a particular sequence of characters.

This method is case sensitive.

Parameters:

s - A String object representing the character sequence to search for.

startPos - The character position in your string to start looking for s.

Returns:

-1 is returned if a match could not be found. Otherwise the position of the first character of the match is returned.

indexOfIgnoreCase

public int indexOfIgnoreCase(java.lang.String s,
                             int startPos)

Find the position within your string of a particular sequence of characters, ignoring the case.

This method is not case sensitive.

Parameters:

s - A String object representing the character sequence to search for.

startPos - The character position in your string to start looking for s.

Returns:

-1 is returned if a match could not be found. Otherwise the position of the first character of the match is returned.

indexOf

public int indexOf(char c)

Find the position within your string of a particular character.

This method is case sensitive. Searching begins with the first character in your string.

Parameters:

c - The character to search for.

Returns:

The position of the character that matches c. -1 is returned if a matching character could not be found.

indexOf

public int indexOf(java.lang.String s)

Find the position within your string of a particular sequence of characters.

This method is case sensitive. Searching begins with the first character in your string.

Parameters:

s - A String object representing the character sequence to search for.

Returns:

-1 is returned if a match could not be found. Otherwise the position of the first character of the match is returned.

indexOfIgnoreCase

public int indexOfIgnoreCase(char c)

Find the position within your string of a particular character, ignoring case.

This method is not case sensitive. Searching begins with the first character in your string.

Parameters:

c - The character to search for.

Returns:

The position of the character that matches c. -1 is returned if a matching character could not be found.

indexOfIgnoreCase

public int indexOfIgnoreCase(java.lang.String s)

Find the position within your string of a particular sequence of characters, ignoring case.

This method is not case sensitive. Searching begins with the first character in your string.

Parameters:

s - A String object representing the character sequence to search for.

Returns:

-1 is returned if a match could not be found. Otherwise the position of the first character of the match is returned.

lastIndexOf

public int lastIndexOf(char c)

endsWith

public boolean endsWith(java.lang.String s)

Does the string object end with this bit of text.

Parameters:

s - the suffix you are looking for.

firstDigit

public int firstDigit()

Returns the index of the first digit, or returns -1 if there are no digits.

replace

public void replace(char c1,
                    char c2)

Replace all instances of one character with another character.

All occurances are replaced.

Searching for the "next instance" of character will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

c1 - The character to search for.

c2 - The character that is to replace c1.

replace

public void replace(char c,
                    java.lang.String s)

Replace all instances of one character with a String object.

All occurances are replaced.

Searching for the "next instance" of character will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

c - The character to search for.

s - The String object that is to replace c.

replace

public void replace(java.lang.String s,
                    char c)

Search for a particular character sequence and replace it with one character.

All occurances are replaced.

Searching for the "next instance" of a character sequence will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

s - A String object representing a character sequence to search for.

c - The character that is to replace s.

replace

public void replace(java.lang.String s1,
                    java.lang.String s2)

Search for a particular character sequence and replace it with a different character sequence.

All occurances are replaced.

Searching for the "next instance" of a character sequence will begin immediately after the last replacement so that there is no chance of an infinite loop.

Parameters:

s1 - A String object representing a character sequence to search for.

s2 - A String object representing a character sequence that is to replace s1.

removeDoubleSpaces

public void removeDoubleSpaces()

Eliminate all occurances of two more space in a row.

When this method is done, there will not be an occurance of two spaces in a row. Anywhere that there was two or more spaces, there is now only one space.

charCount

public int charCount(char c)

Count how many times a particular character occurs within your string.

As dumb as this sounds, the method does end up getting used a lot.

Parameters:

c - The character to look for.

Returns:

The number of times the character occured in this string.

trimLead

public void trimLead()

Trims all leading spaces, no trailing spaces.

trimTrail

public void trimTrail()

Trims all trailing spaces, no leading spaces.

trim

public void trim()

Trims all leading spaces and all trailing spaces.

trimLeadWhitespace

public void trimLeadWhitespace()

Trims all leading spaces, newlines, returns and tabs.

trimTrailWhitespace

public void trimTrailWhitespace()

Trims all trailing spaces, newlines, returns and tabs.

trimWhitespace

public void trimWhitespace()

Trims all leading spaces, newlines, returns and tabs and all trailing spaces, newlines, returns and tabs.

trimTrailTo

public void trimTrailTo(char c)

Trims all characters from end of the string until a particular character is encountered.

The character being searched for is also trimmed.

Parameters:

c - The character to search for.

extractWord

public Str extractWord()

Extract and return the first word.

Space delimited (all double spaces are removed).

Returns:

A Str object representing the first word found in the string. No spaces are returned. If there are no words left, an empty Str object is returned.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Convert this Str object to a String object.

Overrides:

toString in class java.lang.Object

Returns:

A String object with an exact copy of your string.

forceNumeric

public void forceNumeric()

Force string to be the first number found.

Everything that is not a number, period or hyphen is converted to a space. The resulting string is the first word extracted.

toInt

public int toInt()

Try to convert this string to an integer value.

Returns:

Zero if the value is supposed to be zero or if there were any problems.

toLong

public long toLong()

Try to convert this string to a long value.

Returns:

Zero if the value is supposed to be zero or if there were any problems.

toDouble

public double toDouble()

Try to convert this string to a double value.

Returns:

Zero if the value is supposed to be zero or if there were any problems.

leftSpaceCount

public int leftSpaceCount()

Report how many leading spaces there are.

Returns:

the number of leading spaces in your string.

rightSpaceCount

public int rightSpaceCount()

Report how many trailing spaces there are.

Returns:

the number of trailing spaces in your string.

left

public void left(int newLen)

Force the length of the string and keep text to the left.

If the new length is longer, spaces will be added to the right.

If the new length is shorter, characters are chopped off from the right.

Useful for formatting text to be left justified.

Parameters:

newLen - The desired new length.

right

public void right(int newLen)

Force the length of the string and keep text to the right.

If the new length is longer, spaces will be added to the left.

If the new length is shorter, characters are chopped off from the right (not the left).

Useful for formatting text to be right justified.

Parameters:

newLen - The desired new length.

center

public void center(int newLen)

Try to center the text in a pad of spaces.

First, all leading and trailing spaces are removed.

If the new length is longer, spaces will be added to the left and right.

If the new length is shorter, the string is unchanged. In this case, the resulting string is longer than the new length!

Useful for formatting text to be centered.

Parameters:

newLen - The desired new length.

toUpper

public void toUpper()

All characters are forced to upper case.

toUpper

public void toUpper(int index)

Char at index is forced to upper case.

isUpper

public boolean isUpper(int index)

Is char at index upper case?

toLower

public void toLower()

All characters are forced to lower case.

toLower

public void toLower(int index)

Char at index is forced to lower case.

isLower

public boolean isLower(int index)

Is char at index lower case?

trailingDigits

public int trailingDigits()

Count the number of trailing digits.

Only values '0' through '9' are considered.

countRange

public int countRange(char low,
                      char high)

the number of digits that occur within this range. Pass in 'a' and 'c' with the string "abcdefg" and the result will be 3.

Parameters:

low - this char is included in the range

high - this char is included in the range

Returns:

the number of characters found within the range

countDigits

public int countDigits()

Returns:

the number of digits found in the string.

reverse

public void reverse()

Reverse the order of all the characters.

Designed to behave the same way as StringBuffer.reverse().

moneyStr

public static java.lang.String moneyStr(double d)

Converts a double to a string with two decimal places.

   Examples:   In       Out

               0.0      "0.00"
               1.9999   "2.00"
               222.2222 "222.22"
   

Parameters:

d - The double value.

Returns:

A String object with the formated number.

formatDouble

public static java.lang.String formatDouble(double d,
                                            int decimalPlaces)

Converts a double to a string with a specified number of decimal places.

Parameters:

d - The double value.

decimalPlaces - The number of decimal places needed.

Returns:

A String object with the formated number.

commaStr

public static java.lang.String commaStr(double val)

Converts a double to a string with commas inserted for thousands, millions, etc.

Fractional values are ignored.

Parameters:

val - The double value.

Returns:

A String object with the formated number.

atoi

public static int atoi(java.lang.String s)

Like the ANSI c function atoi().

Parameters:

s - The string that begins with a number.

Returns:

The integer that was extracted or 0 if any problems were encountered.

atoi

public static int atoi(char c)

Sort of like the ANSI c function atoi().

Instead of passing in a string, pass in a character.

Parameters:

c - The char containing a single digit.

Returns:

The integer that was extracted ( 0 through 9 ) or 0 if any problems were encountered.

atod

public static double atod(java.lang.String s)

Like the ANSI c function atod().

Parameters:

s - The string that begins with a number.

Returns:

The double that was extracted or 0.0 if any problems were encountered.

verboseMoney

public static Str verboseMoney(double x)

Convert a double to English ( 12.01 -> "twelve and 01/100" ).

   Examples:   In          Out

               0.0         "zero and 00/100"
               23.23       "twenty-three and 23/100"
               12345678.90 "twelve million three hundred forty-five thousand six hundred seventy-eight and 90/100"
   

Parameters:

x - The double to convert.

Returns:

The Str object containing the results.

nowStr

public static java.lang.String nowStr()

Get the current local date and time.

Returns:

A String object with the current local date and time.

stringOf

public static Str stringOf(int quan,
                           char c)

Create a Str object containing nothing but a quantity of one character.

Example: calling stringOf( 20 , '-' ) returns a string of 20 hyphens.

Parameters:

quan - The desired string length.

c - The desired character.

Returns:

The new Str object.

spaces

public static Str spaces(int quan)

Create a Str object containing nothing but a quantity of spaces.

Parameters:

quan - The number of spaces desired.

subString

public static java.lang.String subString(java.lang.String s,
                                         int index,
                                         int length)

A static sub-string method that works the way you expect it to work.

The Java substring thing is, IMO, twisted. This is the normal way to do substrings. Plus, this object makes the best of awkward requests without throwing an exception.

Parameters:

s - A String object that you want to extract a sub-string from.

index - Where the sub-string begins.

length - How long you want your sub-string to be.

substring

public static java.lang.String substring(java.lang.String s,
                                         int index,
                                         int length)

Same as subString, but allows all lower case.

before

public static java.lang.String before(java.lang.String s,
                                      int index)

Get all of the substring that occurs before a particular character.

Parameters:

s - The String object to extract the substring from.

index - The character that marks the end of the substring. This character is not included in the substring.

Returns:

A String object containing the substring.

through

public static java.lang.String through(java.lang.String s,
                                       int index)

Get all of the substring that occurs through a particular character.

Parameters:

s - The String object to extract the substring from.

index - The character that marks the end of the substring. This character is included in the substring.

Returns:

A String object containing the substring.

after

public static java.lang.String after(java.lang.String s,
                                     int index)

Get all of the substring that occurs after a particular character.

Parameters:

s - The String object to extract the substring from.

index - The character that marks the beginning of the substring. This character is not included in the substring.

Returns:

A String object containing the substring.

from

public static java.lang.String from(java.lang.String s,
                                    int index)

Get all of the substring that occurs from a particular character to the end of the string.

Parameters:

s - The String object to extract the substring from.

index - The character that marks the beginning of the substring. This character is included in the substring.

Returns:

A String object containing the substring.

left

public static java.lang.String left(java.lang.String s,
                                    int newLen)

Force the length of the string and keep text to the left.

If the new length is longer, spaces will be added to the right.

If the new length is shorter, characters are chopped off from the right.

Useful for formatting text to be left justified.

Parameters:

s - The String object to doAction.

newLen - The desired new length.

Returns:

The new string object.

right

public static java.lang.String right(java.lang.String s,
                                     int newLen)

Force the length of the string and keep text to the right.

If the new length is longer, spaces will be added to the left.

If the new length is shorter, characters are chopped off from the right (not the left).

Useful for formatting text to be right justified.

Parameters:

s - The String object to doAction.

newLen - The desired new length.

Returns:

The new string object.

center

public static java.lang.String center(java.lang.String s,
                                      int newLen)

Try to center the text in a pad of spaces.

First, all leading and trailing spaces are removed.

If the new length is longer, spaces will be added to the left and right.

If the new length is shorter, the string is unchanged. In this case, the resulting string is longer than the new length!

Useful for formatting text to be centered.

Parameters:

s - The String object to doAction.

newLen - The desired new length.

Returns:

The new string object.

trimWhitespace

public static java.lang.String trimWhitespace(java.lang.String s)

trailingDigits

public static int trailingDigits(java.lang.String s)

Count the number of trailing digits.

Only values '0' through '9' are considered.

usable

public static boolean usable(java.lang.String s)

Returns:

true if the string is not null and has at least one non whitespace character.

toInt

public static int toInt(java.lang.String s)

Try to convert a string to an integer value.

Returns:

Zero if the value is supposed to be zero or if there were any problems.

toLong

public static long toLong(java.lang.String s)

Try to convert a string to a long value.

Returns:

Zero if the value is supposed to be zero or if there were any problems.

toDouble

public static double toDouble(java.lang.String s)

Try to convert a string to a double value.

Returns:

Zero if the value is supposed to be zero or if there were any problems.

toTimestamp

public static java.sql.Timestamp toTimestamp(java.lang.String s)

Try to convert a string to a Timestamp object.

Returns:

null if null is passed in or were any format problems.

toBoolean

public static boolean toBoolean(java.lang.String s)

Try to convert a string to a boolean value.

Returns:

True if the first char of the string is 'T', 't', 'Y' or 'y'. Anything else (including null or empty string) returns false.

trim

public static java.lang.String trim(java.lang.String s)

Return a string that is either null or has at least one character. Note that this is a bit different than String.trim() or the instance method of this class. Those methods will never return a null. This method is useful if your goal is to reduce the number of objects for serialization. The inverse of this method is Str.normalize()

normalize

public static java.lang.String normalize(java.lang.Object s)

Return a string that is not null. If s is null, return "". Else return s. This method is useful if you could be passed a null string and you want to treat a null as an empty string. Frequently used when showing data that has been serialized and the empty strings were converted to null to save space.

equal

public static boolean equal(java.lang.String s1,
                            java.lang.String s2)

Uses String.equals(), but will consider that either or both strings might be null.

Returns:

true if the contents of both strings are the same or if both strings are null.

equal

public static boolean equal(java.lang.String[] s1,
                            java.lang.String[] s2)

Uses String.equals(), but will consider that either or both arrays/strings might be null.

Returns:

true if the contents of both arrays are the same or if both arrays are null.

toStringArray

public static java.lang.String[] toStringArray(int[] values)

toIntArray

public static int[] toIntArray(java.lang.String[] values)

getChar

public static char getChar(java.lang.String s,
                           int index)

Just like String.charAt() except for null strings or for strings that are too short, an exception will not be thrown and instead, a null char will be returned.