com.sage.accpac.sm
Class ASCIIComparer

java.lang.Object
  com.sage.accpac.sm.ASCIIComparer

@ThreadSafe
public final class ASCIIComparer
extends java.lang.Object

A class providing for ASCII handling of strings.

Frequently we perform tests to see if an input string is equal without regard to case to a pure ASCII string. See equalsIgnoreCase(String,String).

For simplicity we also like to convert strings to a consistent case (either lower or upper). See toLowerCase(String) and toUpperCase(String) for suitable functions.

Sometimes we know, by context, that we have an ASCII string that we can safely convert to lower case using e.g. toLowerCase(String), but sometimes we might not know. Rather than catching an exception we may prefer to use isASCII(String) to see if the argument is a valid string to pass to it.

In our frameworks we frequently use strings that are pure ASCII which makes it simpler to be well defined. In the System Manager core C code we have already noted that there is quite an improvement in performance by switching from the locale-specific case-insensitive comparisons to a specialised version that only allows for ASCII characters. The improvement in Java is less pronounced but the advantage is that it is more well-defined.

Thread safety

Thread-safe

Method Summary

static boolean	equalsIgnoreCase(java.lang.String firstString, java.lang.String secondString) returns true if and only if both strings are pure ASCII strings and they are equal without regard to case.
static boolean	isASCII(java.lang.String string) returns true if and only if the input is a pure ASCII string
static java.lang.String	toLowerCase(java.lang.String string) returns a String containing the lower case conversion of the pure ASCII input, throwing an exception if it is not pure ASCII.
static java.lang.String	toUpperCase(java.lang.String string) returns a String containing the lower case conversion of the pure ASCII input, throwing an exception if it is not pure ASCII.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

equalsIgnoreCase

public static boolean equalsIgnoreCase(java.lang.String firstString,
                                       java.lang.String secondString)

returns true if and only if both strings are pure ASCII strings and they are equal without regard to case.

It returns false if either string (or both) is not a pure ASCII string; it does not throw an exception. This means you do not need to test first of all to see if the string is ASCII before calling this function. (neither, however, can be null references).

A string is a pure ASCII string if all of the characters in it are in the range of ASCII characters (i.e. have code points between 0 and 127).

Why not use String.equalsIgnoreCase?

Why does this function exist? Why not simply use String.equalsIgnoreCase? Consider; do you know if there are any Unicode characters that are not pure ASCII characters but that convert to ASCII characters when changing case to lower case or to upper case? If there are any then String.equalsIgnoreCase can accept an input that you did not expect it to accept. This function is almost certainly closer to what you actually wanted.

Performance

Currently this method is actually faster than the String equalsIgnoreCase when operating on short pure ASCII input and faster than case-sensitive comparison.

On average on a reasonable computer a short string comparison takes of the order of 1 microsecond when comparing random strings.

Parameters:

firstString - the first string

secondString - the second string

Returns:

true if the two strings are both pure ASCII and are equal without regard to case.

Throws:

java.lang.NullPointerException - if either or both of the arguments are null references.

toLowerCase

public static java.lang.String toLowerCase(java.lang.String string)

returns a String containing the lower case conversion of the pure ASCII input, throwing an exception if it is not pure ASCII. Call isASCII(String) to check that the argument is pure ASCII.

Parameters:

string - the string to convert, which must not be a null reference and must consist only of ASCII characters.

Returns:

the lower case version of the string

Throws:

java.lang.IllegalArgumentException - if the string is not pure ASCII

java.lang.NullPointerException - if the string is a null reference

See Also:

isASCII(String)

toUpperCase

public static java.lang.String toUpperCase(java.lang.String string)

returns a String containing the lower case conversion of the pure ASCII input, throwing an exception if it is not pure ASCII. Call isASCII(String) to check that the argument is pure ASCII.

Parameters:

string - the string to convert, which must not be a null reference and must consist only of ASCII characters.

Returns:

the lower case version of the string

Throws:

java.lang.IllegalArgumentException - if the string is not pure ASCII

java.lang.NullPointerException - if the string is a null reference

See Also:

isASCII(String)

isASCII

public static boolean isASCII(java.lang.String string)

returns true if and only if the input is a pure ASCII string

Parameters:

string - the string to check

Returns:

true if and only if the input is a pure ASCII string

Throws:

java.lang.NullPointerException - if the string is a null reference