org.jtr.transliterate
Class CharacterReplacer

java.lang.Object
  |
  +--org.jtr.transliterate.CharacterReplacer

All Implemented Interfaces:

java.lang.Cloneable

public final class CharacterReplacer

extends java.lang.Object

implements java.lang.Cloneable

Main class for performing the transliteration operation.

Usage:

• Create a CharacterReplacer instance. Either use the String constructors, which will compile the patterns automatically, or the CharacterList constructors, which take pre-compiled patterns as their arguments.
• Call setFlags(int) if required. The flags available are equivalent to the Perl flags available for the transliterate operator. The flags are additive, meaning that more than one can be specified at a time. The flags themselves are defined in the CharacterParser class.
• Call doReplacement(java.lang.String) with the String or character array to be transliterated. The return value is a new string consisting of the transliterated source.
• If required, the number of matches can be determined from the getMatches() method.

Notes:

CharacterReplacer objects should not be considered thread-safe. In particular:

• If one thread performs a setFlags(int) method call while another thread is perfoming a doReplacement(java.lang.String) call, the results are undefined.
• If the getMatches() functionality is required, a doReplacement(java.lang.String) call should not be executed by more than one thread.

If thread safety is required, consider using the clone() method to create new instances.

Version:

$Id: CharacterReplacer.java,v 1.12 2005/03/16 11:56:36 run2000 Exp $

Author:

Nicholas Cull

Constructor Summary

CharacterReplacer(CharacterList cSourceChars)
Creates new CharacterReplacer using a pre-compiled CharacterList.

CharacterReplacer(CharacterList cSourceChars, CharacterList cDestChars)
Creates new CharacterReplacer using pre-compiled CharacterLists.

CharacterReplacer(java.lang.String aSourceChars)
Compiles a transliteration from a String object.

CharacterReplacer(java.lang.String aSourceChars, java.lang.String aDestChars)
Compiles a transliteration from String objects.

Method Summary

java.lang.Object	clone() Return a clone of the current CharacterReplacer.
java.lang.String	doReplacement(char[] aSourceString) Performs a transliteration on the given character array.
java.lang.String	doReplacement(java.lang.String aSourceString) Performs a transliteration operation on the given String.
int	getMatches() Gets the number of matches found by the most recent doReplacement(java.lang.String) method call.
void	setFlags(int nFlags) Sets or clears flags that are used during the transliteration process.

Methods inherited from class java.lang.Object

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

Constructor Detail

CharacterReplacer

public CharacterReplacer(CharacterList cSourceChars)

Creates new CharacterReplacer using a pre-compiled CharacterList.

Parameters:

cSourceChars - the match pattern to be compiled

Throws:

java.lang.IllegalArgumentException - cSourceChars is empty

NullPointerException - cSourceChars is null

CharacterReplacer

public CharacterReplacer(CharacterList cSourceChars,
                         CharacterList cDestChars)

Creates new CharacterReplacer using pre-compiled CharacterLists.

Parameters:

cSourceChars - the match pattern to be compiled

cDestChars - the replacement pattern to be compiled

Throws:

java.lang.IllegalArgumentException - cSourceChars is empty

NullPointerException - cSourceChars or cDestChars is null

CharacterReplacer

public CharacterReplacer(java.lang.String aSourceChars)
                  throws CharacterParseException

Compiles a transliteration from a String object.

Parameters:

aSourceChars - the match pattern to be compiled

Throws:

CharacterParseException - something went wrong parsing the source

java.lang.IllegalArgumentException - aSourceChars is empty

NullPointerException - aSourceChars is null

CharacterReplacer

public CharacterReplacer(java.lang.String aSourceChars,
                         java.lang.String aDestChars)
                  throws CharacterParseException

Compiles a transliteration from String objects.

Parameters:

aSourceChars - the match pattern to be compiled

aDestChars - the replacement pattern to be compiled

Throws:

CharacterParseException - something went wrong parsing either the source or destination

java.lang.IllegalArgumentException - aSourceChars is empty

NullPointerException - aSourceChars or aDestChars is null

Method Detail

doReplacement

public java.lang.String doReplacement(java.lang.String aSourceString)

Performs a transliteration operation on the given String. As a side-effect, once this method has been called, the number of substitutions performed can be determined by the getMatches() method.

Parameters:

aSourceString - the string to be transliterated

Returns:

the transliterated string

Throws:

NullPointerException - aSourceString is null

doReplacement

public java.lang.String doReplacement(char[] aSourceString)

Performs a transliteration on the given character array. As a side-effect, once this method has been called, the number of substitutions performed can be determined by the getMatches() method.

Parameters:

aSourceString - an array of characters to be transliterated

Returns:

a String consisting of the transliterated input

Throws:

NullPointerException - aSourceString is null

setFlags

public void setFlags(int nFlags)

Sets or clears flags that are used during the transliteration process. Three flags are defined for transliterations:

• COMPLEMENT_MASK—Anything not in the searchlist is matched.
• SQUASH_DUPLICATES_MASK—Any substitutions that result in a duplicate character are squashed down to a single instance of that character
• DELETE_UNREPLACEABLES_MASK—If the replacement list is shorter than the search list, any characters in the search list that don't have a corresponding value in the replacement list are deleted. By default, the last character in the replacement list is copied until the replacement list is long enough.

These flags are defined in the CharacterParser class.

getMatches

public int getMatches()

Gets the number of matches found by the most recent doReplacement(java.lang.String) method call. This number includes any characters matched, regardless of whether the resulting replacement character was the same as the search character.

Returns:

the number of matches found in the most recent replacement

clone

public java.lang.Object clone()

Return a clone of the current CharacterReplacer. This is particularly useful for situations where thread safety is important.

Overrides:

clone in class java.lang.Object

Returns:

a clone of the current object