xbn.string
Class UtilChar

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.string.UtilChar

public class UtilChar

extends XBNObject

Random functions for analyzing and manipulating chars.

Source code: UtilChar.java. Unit tests: xbn_junit.string.JUTUtilChar.java.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

UtilChar()
Create a UtilChar.

Method Summary

int	binarySearch(char c_har, char[] a_char, boolean b_validateAOC) Get the array index at which the requested character exists.
void	crashIfAOCNotUnqAscOrd(String s_callingClsFnc, char[] a_char, String s_acDesc, boolean b_actuallyCheck) Verify that the provided char array is non-null, at least one element in length, unique and ordered ascending.
static char[]	getAOCHexLetters() Get an array of chars containing the letters used in hexidecimal numbers.
static char[]	getAOCInvisible() Get an array of chars containing non-visible characters.
static char[]	getAOCTabSpace() Get an array of chars containing the tab and space characters.
String	getHexDigitAsString(char c_har) Convert a given char to a hex digit, returning it as a string.
String	getVisible(char c_har) Get a string to visible represent this (potentially) invisible character.
boolean	isDigitOrIn(char c_har, char[] ac_legal) Is the provided character a digit, or other legal char?
boolean	isDigitOrIn(char c_har, char[] ac_legal, boolean b_validateAOC) Is the provided character a digit, or other legal char?
boolean	isHexidecimal(char c_har) Is the provided char a hex digit?
boolean	isIn(char c_har, char[] ac_legal) Is the provided char equal to any char in the provided array?
boolean	isIn(char c_har, char[] ac_legal, boolean b_validateAOC) Is the provided char equal to any char in the provided array?
boolean	isInvisible(char c_har) Is the provided char whitespace?
boolean	isLDOrIn(char c_har, char[] ac_legal) Is the provided character a letter, digit or other legal char?
boolean	isLDOrIn(char c_har, char[] ac_legal, boolean b_validateAOC) Is the provided character a letter, digit or other legal char?
boolean	isLegal(char c_har, boolean b_letterOkOpt, boolean b_digitOkOpt, char[] ac_legal, boolean b_validateAOC) Is the provided character an legal one?
boolean	isLetterOrIn(char c_har, char[] ac_legal) Is the provided character a letter, or other legal char?
boolean	isLetterOrIn(char c_har, char[] ac_legal, boolean b_validateAOC) Is the provided character a letter, or other legal char?
boolean	isNotDigitOrIn(char c_har, char[] ac_illegal) Is the provided character not a digit, or other illegal char?
boolean	isNotDigitOrIn(char c_har, char[] ac_illegal, boolean b_validateAOC) Is the provided character not a digit, or other illegal char?
boolean	isNotIllegal(char c_har, boolean b_letterBadOpt, boolean b_digitBadOpt, char[] ac_illegal, boolean b_validateAOC) Is the provided character not an illegal one?
boolean	isNotLDOrIn(char c_har, char[] ac_illegal) Is the provided character not a letter, digit or other illegal char?
boolean	isNotLDOrIn(char c_har, char[] ac_illegal, boolean b_validateAOC) Is the provided character not a letter, digit or other illegal char?
boolean	isNotLetterOrIn(char c_har, char[] ac_illegal) Is the provided character not a letter, or other illegal char?
boolean	isNotLetterOrIn(char c_har, char[] ac_illegal, boolean b_validateAOC) Is the provided character not a letter, or other illegal char?

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

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

Constructor Detail

UtilChar

public UtilChar()

Create a UtilChar.

This constructor does nothing.

Method Detail

isInvisible

public final boolean isInvisible(char c_har)

Is the provided char whitespace?

Returns:

isIn(c_har, getAOCInvisible(), true)

isHexidecimal

public final boolean isHexidecimal(char c_har)

Is the provided char a hex digit?

Returns:

isDigitOrIn(c_har, getAOCHexLetters(), true)

getHexDigitAsString

public final String getHexDigitAsString(char c_har)

Convert a given char to a hex digit, returning it as a string. Note that all returned letters (a through f) are uppercase.

Got the main idea for this from http://mindprod.com/jglosshex.html.

Parameters:

c_har - The character to translate.

isIn

public final boolean isIn(char c_har,
                          char[] ac_legal)

Is the provided char equal to any char in the provided array?

Returns:

isIn(c_har, ac_legal, true)

isIn

public final boolean isIn(char c_har,
                          char[] ac_legal,
                          boolean b_validateAOC)

Is the provided char equal to any char in the provided array?

Returns:

isLegal(c_har, false, false, ac_legal, b_validateAOC)

isLetterOrIn

public final boolean isLetterOrIn(char c_har,
                                  char[] ac_legal)

Is the provided character a letter, or other legal char?

Returns:

isLegal(c_har, ac_legal, true)

isLetterOrIn

public final boolean isLetterOrIn(char c_har,
                                  char[] ac_legal,
                                  boolean b_validateAOC)

Is the provided character a letter, or other legal char?

Returns:

isLegal(c_har, true, false, ac_legal, b_validateAOC)

isDigitOrIn

public final boolean isDigitOrIn(char c_har,
                                 char[] ac_legal)

Is the provided character a digit, or other legal char?

Returns:

isDigitOrIn(c_har, ac_legal, true)

isDigitOrIn

public final boolean isDigitOrIn(char c_har,
                                 char[] ac_legal,
                                 boolean b_validateAOC)

Is the provided character a digit, or other legal char?

Returns:

isLegal(c_har, false, true, ac_legal, b_validateAOC)

isLDOrIn

public final boolean isLDOrIn(char c_har,
                              char[] ac_legal)

Is the provided character a letter, digit or other legal char?

Returns:

isLDOrIn(c_har, ac_legal, true)

isLDOrIn

public final boolean isLDOrIn(char c_har,
                              char[] ac_legal,
                              boolean b_validateAOC)

Is the provided character a letter, digit or other legal char?

Returns:

isLegal(c_har, true, true, ac_legal, b_validateAOC)

isLegal

public final boolean isLegal(char c_har,
                             boolean b_letterOkOpt,
                             boolean b_digitOkOpt,
                             char[] ac_legal,
                             boolean b_validateAOC)

Is the provided character an legal one?

Warning: This function will not work properly unless ac_legal conforms to all its restrictions.

Parameters:

c_har - The character to analyze.

b_letterOkOpt - If true, then it is legal for c_har to be equal to any letter (a-z, A-Z). If false, then it is not checked whether or not c_har is a letter (and is therefore optional). If b_digitOkOpt is false, and ac_legal is null, then this must be true.

b_digitOkOpt - If true, then it is legal for c_har to be equal to any digit (0-9). If false, then it is not checked whether or not c_har is a digit (and is therefore optional). If b_letterOkOpt is false, and ac_legal is null, then this must be true.

ac_legal - If non-null, this is assumed to be an ordered (ascending) and unique array of characters--beyond letters and digits--that are considered legal. If null, then no characters (beyond letters and digits) are considered legal. Although it will not cause an exception, unless a subset of letters/digits are legal, it is wasteful and redundant to put letters/digits in this array. Use b_letterOkOpt/b_digitOkOpt as appropriate. If b_letterOkOpt and b_digitOkOpt are false, then this must be non-null.

b_validateAOC - If true, then it is verified that ac_legal is valid crashIfAOCNotUnqAscOrd, but only after it is determined that c_har is not a letter/digit (when b_letterOkOpt and/or b_digitOkOpt equal true). Also note that this check does not care if letters or digits exist in ac_legal.

Returns:

true If c_har meets the above requirements.
false If otherwise.

getVisible

public final String getVisible(char c_har)

Get a string to visible represent this (potentially) invisible character.

Parameters:

c_har - The character to make visible.

Returns:

\\t If c_har equals '\t'
\\n If '\n'
\\f If '\f'
\\r If '\r'
(new Character(c_har)).toString() If otherwise.

isNotLetterOrIn

public final boolean isNotLetterOrIn(char c_har,
                                     char[] ac_illegal)

Is the provided character not a letter, or other illegal char?

Returns:

isNotLetterOrIn(c_har, ac_illegal, true)

isNotLetterOrIn

public final boolean isNotLetterOrIn(char c_har,
                                     char[] ac_illegal,
                                     boolean b_validateAOC)

Is the provided character not a letter, or other illegal char?

Returns:

isNotIllegal(c_har, true, false, ac_illegal, b_validateAOC)

isNotDigitOrIn

public final boolean isNotDigitOrIn(char c_har,
                                    char[] ac_illegal)

Is the provided character not a digit, or other illegal char?

Returns:

isNotDigitOrIn(c_har, ac_illegal, true)

isNotDigitOrIn

public final boolean isNotDigitOrIn(char c_har,
                                    char[] ac_illegal,
                                    boolean b_validateAOC)

Is the provided character not a digit, or other illegal char?

Returns:

isNotIllegal(c_har, false, true, ac_illegal, b_validateAOC)

isNotLDOrIn

public final boolean isNotLDOrIn(char c_har,
                                 char[] ac_illegal)

Is the provided character not a letter, digit or other illegal char?

Returns:

isNotLDOrIn(c_har, ac_illegal, true)

isNotLDOrIn

public final boolean isNotLDOrIn(char c_har,
                                 char[] ac_illegal,
                                 boolean b_validateAOC)

Is the provided character not a letter, digit or other illegal char?

Returns:

isNotIllegal(c_har, true, true, ac_illegal, b_validateAOC)

isNotIllegal

public final boolean isNotIllegal(char c_har,
                                  boolean b_letterBadOpt,
                                  boolean b_digitBadOpt,
                                  char[] ac_illegal,
                                  boolean b_validateAOC)

Is the provided character not an illegal one?

Parameters:

c_har - The character to analyze.

b_letterBadOpt - If true, then it is illegal for c_har to be equal to any letter (a-z, A-Z). If false, then it is okay (optional) for c_har to be a letter.

b_digitBadOpt - If true, then it is illegal for c_har to be equal to any digit (0-9). If false, then it is okay (optional) for c_har to be a digit.

ac_illegal - If non-null, this is an ordered (ascending) and unique array of characters--beyond letters and digits--that are considered illegal. If null, then no characters (beyond letters and digits) are considered illegal. Although it will not cause an exception, it is wasteful and redundant to put letters/digits in this array (exception: When only a subset of letters are illegal). Use b_letterBadOpt/b_digitBadOpt as appropriate.

b_validateAOC - If true, then it is verified that ac_illegal is valid crashIfAOCNotUnqAscOrd, but only after it is determined that c_har is not a letter/digit (when b_letterBadOpt/b_digitBadOpt equal true). Also note that this check does not care if letters or digits exist in ac_illegal.

Returns:

true If c_har meets the above requirements.
false If otherwise.

binarySearch

public final int binarySearch(char c_har,
                              char[] a_char,
                              boolean b_validateAOC)

Get the array index at which the requested character exists.

Parameters:

c_har - The char to search for.

a_char - The array of chars in which to search for c_har. Must be non-null, at least one element in length, and all values must be unique and ordered ascending.

b_validateAOC - If true, then a_char is analyzed to ensure it is valid. If false, it is assumed that a_char is valid. Use false with care.

Returns:

return Arrays.binarySearch(a_char, c_har)

crashIfAOCNotUnqAscOrd

public final void crashIfAOCNotUnqAscOrd(String s_callingClsFnc,
                                         char[] a_char,
                                         String s_acDesc,
                                         boolean b_actuallyCheck)

Verify that the provided char array is non-null, at least one element in length, unique and ordered ascending. If valid, do nothing. Otherwise throw an AssertException.

Parameters:

s_callingClsFnc - The class-plus-function from which a potential error message should appear like it is being generated from. May not be null.

a_char - The array of characters to analyze.

s_acDesc - The descriptive name of a_char, for the potential error message.

b_actuallyCheck - If true then actually check a_char. If false, this function does nothing.

getAOCTabSpace

public static final char[] getAOCTabSpace()

Get an array of chars containing the tab and space characters.

See getAOCInvisible, Character.isSpace and isWhitespace.

Returns:

(new char[] {'\t', ' '})

getAOCInvisible

public static final char[] getAOCInvisible()

Get an array of chars containing non-visible characters.

See getAOCTabSpace, Character.isSpace and isWhitespace.

Returns:

(new char[] {'\t', '\n', '\f', '\r', ' '})

getAOCHexLetters

public static final char[] getAOCHexLetters()

Get an array of chars containing the letters used in hexidecimal numbers.

Returns:

(new char[] {'A', 'B', 'C', 'D', 'E', 'F'}})