Defines which characters, when escaped, should be ignored (that is, left escaped without causing an error). This affects every character not defined as "to-be-escaped" (see ESConfig.getAPCToEscape()).
Source code: USCIgnore.java
When the same string is escaped in multiple phases, then it's most likely that something needs to be ignored. Otherwise, characters that should be unescaped in phase two (but not phase one) will cause an UnescapeStringException during phase one.
On the other hand, when there will only be one phase of escaping (or the current phase is definitely the final one), then you may want to generate an error when an incorrectly escaped character exists.
@version 0.9b @author Jeff Epstein, http://sourceforge.net/projects/xbnjava. **/ public class USCIgnore extends XBNObject implements Cloneable { private boolean bIgnoreAll = false; private char[] acIgnore = null; private APChar apcIgnore = null; /**Create a USCIgnore with default settings.
Equal to USCIgnore(true)
Create a USCIgnore.
Equal to USCIgnore(b_ignoreAll, (new char[] {}))
Create a USCIgnore.
Equal to USCIgnore(false, ac_ignore)
Create a USCIgnore.
@param b_ignoreAll Should all non-to-be-escaped chars be ignored (left escaped without causing an error)? If true, yes. If false, no. When true, ac_ignore must be zero elements in length. See doIgnoreAll. @param ac_ignore The specific array of chars to be ignored. May not be null. If zero elements in length, no specific characters are ignored. If more zero elements, then each character element should be unique, must not equal the escape character, nor any character defined as to-be-escaped (verifying that the characters are are not illegal is checked in the USConfig constructor, not here). When more than zero elements in length, b_ignoreAll must equal false. See getAPCIgnore. **/ protected USCIgnore(boolean b_ignoreAll, char[] ac_ignore) { throwAXIfNull(ac_ignore, "ac_ignore", sCNSTR); if(b_ignoreAll && ac_ignore.length > 0) { throwAX("constructor: b_ignoreAll is true, and ac_ignore.length is " + ac_ignore.length + ". When b_ignoreAll is true, ac_ignore.length must equal zero. When ac_ignore.length is greater than zero, b_ignoreAll must equal false."); } Arrays.sort(ac_ignore); bIgnoreAll = b_ignoreAll; acIgnore = ac_ignore; apcIgnore = new APChar(ac_ignore); } /**Should all non-should-be-escaped characters be ignored?
If this function returns true, then all escaped characters (not including the escape character and those defined as to-be-escaped) are ignored. If false, then specific characters may be ignored, but "every" one is not.
@return b_ignoreAll Exactly as provided to the constructor. **/ public final boolean doIgnoreAll() { return bIgnoreAll; } /**What specific non-to-be-escaped characters should be ignored?
When the length of the returned APChar is zero, then doIgnoreAll may return true or false. When the returned contains at least one element, doIgnoreAll always returns false.
@return An APChar of length one or more Containing individual characters to be ignored, when escaped. None of these characters are the escape character, nor are any a duplicate of those defined as getAPCToEscape.Is the provided character one that should be specifically ignored?
Use this in tandem with doIgnoreAll to truly determite whether a character should be ignored.
@param c_har The character to analyze for ignore-ness. @return(Arrays.binarySearch(ac_ignore, c_har) > -1), where ac_ignore is exactly as provided to the constructor.
**/
public final boolean isSpcfcIgnored(char c_har) {
return (Arrays.binarySearch(acIgnore, c_har) > -1);
}
/**
Is at least on character ignored?
@return(doIgnoreAll() || getAPCIgnore().getLength() > 0)
**/
public final boolean hasCharToIgnore() {
return (doIgnoreAll() || getAPCIgnore().getLength() > 0);
}
/**
Get some information about this USCIgnore.
**/ public String toString() { return this.getClass().getName() + ": doIgnoreAll()=" + doIgnoreAll() + ", getAPCIgnore=" + getAPCIgnore().getList("['", "', '", "']"); } /**Get a full (deep) copy of this USCIgnore.
@return(USCIgnore)clone()
**/
public final USCIgnore getEUSCUIClone() {
try {
return (USCIgnore)clone();
} catch(CloneNotSupportedException cnsx) {
throwAX("getEUSCUIClone [SHOULD NEVER HAPPEN!]: " + cnsx.toString());
}
//Never reached. Required for compile.
return null;
}
/**
Get a full (deep) copy of this USCIgnore as an Object.
**/ protected Object clone() throws CloneNotSupportedException { return new USCIgnore(bIgnoreAll, acIgnore, apcIgnore); } private USCIgnore(boolean b_ignoreAll, char[] ac_ignore, APChar apc_ignore) { bIgnoreAll = b_ignoreAll; acIgnore = ac_ignore; apcIgnore = apc_ignore.getAPCClone(); } }