com.ibm.etools.iseries.util
Class StringNL

java.lang.Object
  com.ibm.etools.iseries.util.StringNL

public class StringNL
extends Object

String that allows substring and padding operations based on the EBCDIC byte positions rather than the Unicode characters. These would differ in the case of DBCS shift-in, shift-out and extended unicode character (EUC)

Nested Class Summary

class

StringNL.DbcsRepairEndingState Keep track of what happened to the last DBCS character during a truncation operation

Field Summary

protected boolean	_bBidi
protected boolean	_bIgnoringBiDiMarks
protected boolean	_bIsPureDbcs
protected boolean	_bIsVisual
protected boolean	_bMultiByte
protected byte[]	_bytes
protected int	_CCSID
protected byte[]	_state
protected String	_strEncoding
protected String	_string
static String	Copyright
static char	LRM
static String	LRMSTR
static char	RLM
static String	RLMSTR
protected byte	SOURCE_LRM
protected byte	SOURCE_RLM
protected static byte	SOURCE_SI
protected static byte	SOURCE_SO
protected static byte	STATE_DB1
protected static byte	STATE_DB2
protected static byte	STATE_LRM
protected static byte	STATE_RLM
protected static byte	STATE_SB
protected static byte	STATE_SI
protected static byte	STATE_SO
protected static char	TARGET_SI
protected static char	TARGET_SO

Constructor Summary

StringNL(byte[] bytesSource, String strEncoding, boolean bMultiByte, boolean bIsPureDbcs)
Convenience constructor that has a byte array input instead of a String input.

StringNL(String strEncoding, boolean bMultiByte)
Constructor for empty string.

StringNL(String strSource, int ccsid)
Main constructor if only know CCSID

StringNL(String strSource, int ccsid, boolean isVisual)
Main constructor if only know CCSID

StringNL(String strSource, int ccsid, boolean isVisual, boolean isPureDbcs)
Main constructor if only know CCSID

StringNL(String strSource, String strEncoding)
Main constructor.

StringNL(String strSource, String strEncoding, boolean bMultiByte)
Convenience constructor for strings that are known to be either multibyte or not.

StringNL(String strSource, String strEncoding, boolean bMultiByte, boolean bPureDbcs)
Convenience constructor for strings that are known to be either multibyte or not.

StringNL(String strSource, String strEncoding, int ccsid)
Main constructor with encoding and ccsid - checks if this is visual bidi

Method Summary

StringNL	alignLeft(int iByteLengthRequested) Removes spaces from the left side.
StringNL	alignNone(int iByteLengthRequested) No spaces are removed.
StringNL	alignRight(int iByteLengthRequested) Removes spaces from the right side.
char	byteCharAt(int location)
int	byteIndexOf(char c) Returns the byte index in the string of the specified character
int	byteLastIndexOf(char c) Returns the byte last index in the string of the specified character
char	charAt(int location) Returns the character at the location specified Use byteCharAt to retrieve charactre at a byte locations
String	convertFromLogicalToVisual(boolean stripDirectionalMarks) Converts the string passed to the constructor from logical BIDI format to visual.
String	convertFromVisualToLogical(boolean ensureRoundTrip) Converts the string passed to the constructor from visual BIDI format to logical.
protected void	createStateByteArray()
protected byte[]	createStateByteArray(byte[] bytes, boolean isPureDbcs) Creates an array the same length as the byte array.
StringNL	delete(int iEndByteIndex) Deletes the specified number of bytes from this string and returns a unicode version of the string taking into account that shift out and shift in characters occupy one byte position, and DBCS characters occupy two byte positions.
boolean	equals(StringNL strnlCompare) Compares two NL strings for equality.
int	getBidiCharIndexOfByte(int iTargetByteIndex) Return the index of the Unicode character that corresponds to the target EBCDIC byte index
int	getByteLength() Returns the byte length of the string if a multibyte string taking into account whether the encoding is multibyte and the encoding supports shift-out/shift-in.
byte[]	getBytes() Attempts to convert the string to a byte array with the given source encoding.
byte[]	getBytes(String source) Attempts to convert a string to a byte array with the given source encoding.
String	getEncoding() Retuns the encoding previously set.
String	getExpanded(boolean bPadDoubleByteCharacters, boolean bUseSpaces) Creates a line of DBCS unicode with shift-in / shift-out and optional padding characters.
String	getStyleString(String strStyle) Sets an Lpex line's color style.
boolean	hasDBCS() Returns whether the string has DBCS characters or not.
int	indexOfRightToLeftCharacter(int offset) Find the index of the RTL character after the offset
boolean	isFirstDbcsByteAt(int byteIndex)
boolean	isIgnoringBidiMarks() Check if ignoring bidirectional markers (ie is visual bidi)
boolean	isLowerCase() Returns whether this string is lower case.
boolean	isSecondDbcsByteAt(int byteIndex)
int	length()
static void	logString(String string)
static void	main(String[] args) Unit test application.
protected byte[]	repairEnding(byte[] bytes) Corrects the end of a mixed (single and double byte) string given a byte array.
protected byte[]	repairEnding(byte[] bytes, byte[] states, StringNL.DbcsRepairEndingState endingRepairState) Corrects the end of a double byte string given a byte array and a state array.
StringNL	substring(int iBeginByteIndex) Returns a unicode version of the substring starting at the given byte index to the end of the string.
StringNL	substring(int iBeginByteIndex, int iEndByteIndex) Returns a unicode version of the substring taking into account that shift out and shift in characters occupy one byte position, and DBCS characters occupy two byte positions.
String	toString() Returns the string equivalent of the NL string.
StringNL	trim() Remove spaces from both ends of the line
StringNL	truncate(int iByteLengthRequested) Truncates to requested byte length or less.
StringNL	truncate(int iByteLengthRequested, StringNL.DbcsRepairEndingState endingRepairState) Truncates to requested byte length or less.
protected byte[]	truncateBytes(byte[] bytesSource, int iByteLengthRequested, StringNL.DbcsRepairEndingState endingRepairState) Truncates the end of the byte array.

Methods inherited from class java.lang.Object

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

Field Detail

Copyright

public static final String Copyright

See Also:

Constant Field Values

_string

protected String _string

_strEncoding

protected String _strEncoding

_bytes

protected byte[] _bytes

_state

protected byte[] _state

_bMultiByte

protected boolean _bMultiByte

_bBidi

protected boolean _bBidi

_CCSID

protected int _CCSID

_bIgnoringBiDiMarks

protected boolean _bIgnoringBiDiMarks

_bIsVisual

protected boolean _bIsVisual

_bIsPureDbcs

protected boolean _bIsPureDbcs

SOURCE_SI

protected static final byte SOURCE_SI

See Also:

Constant Field Values

SOURCE_SO

protected static final byte SOURCE_SO

See Also:

Constant Field Values

TARGET_SI

protected static final char TARGET_SI

See Also:

Constant Field Values

TARGET_SO

protected static final char TARGET_SO

See Also:

Constant Field Values

STATE_SB

protected static final byte STATE_SB

See Also:

Constant Field Values

STATE_SO

protected static final byte STATE_SO

See Also:

Constant Field Values

STATE_DB1

protected static final byte STATE_DB1

See Also:

Constant Field Values

STATE_DB2

protected static final byte STATE_DB2

See Also:

Constant Field Values

STATE_SI

protected static final byte STATE_SI

See Also:

Constant Field Values

STATE_RLM

protected static final byte STATE_RLM

See Also:

Constant Field Values

STATE_LRM

protected static final byte STATE_LRM

See Also:

Constant Field Values

LRM

public static final char LRM

See Also:

Constant Field Values

RLM

public static final char RLM

See Also:

Constant Field Values

LRMSTR

public static final String LRMSTR

See Also:

Constant Field Values

RLMSTR

public static final String RLMSTR

See Also:

Constant Field Values

SOURCE_RLM

protected byte SOURCE_RLM

SOURCE_LRM

protected byte SOURCE_LRM

Constructor Detail

StringNL

public StringNL(String strEncoding,
                boolean bMultiByte)

Constructor for empty string.

StringNL

public StringNL(String strSource,
                int ccsid)

Main constructor if only know CCSID

StringNL

public StringNL(String strSource,
                int ccsid,
                boolean isVisual)

Main constructor if only know CCSID

Parameters:

strSource - the string

ccsid - the ccsid for the strinf

isVisual - true if the string is in visual order, false otherwise

Since:

6.0.1 //59962

StringNL

public StringNL(String strSource,
                int ccsid,
                boolean isVisual,
                boolean isPureDbcs)

Main constructor if only know CCSID

Parameters:

strSource - the string

ccsid - the ccsid for the strinf

isVisual - true if the string is in visual order, false otherwise

isPureDbcs - true if the string should not be bracketed by SI/SO

Since:

6.0.1 //59962

StringNL

public StringNL(String strSource,
                String strEncoding)

Main constructor.

StringNL

public StringNL(String strSource,
                String strEncoding,
                int ccsid)

Main constructor with encoding and ccsid - checks if this is visual bidi

Since:

6.0.1 59827

StringNL

public StringNL(String strSource,
                String strEncoding,
                boolean bMultiByte)

Convenience constructor for strings that are known to be either multibyte or not.

StringNL

public StringNL(String strSource,
                String strEncoding,
                boolean bMultiByte,
                boolean bPureDbcs)

Convenience constructor for strings that are known to be either multibyte or not.

StringNL

public StringNL(byte[] bytesSource,
                String strEncoding,
                boolean bMultiByte,
                boolean bIsPureDbcs)

Convenience constructor that has a byte array input instead of a String input.

Parameters:

bIsPureDbcs - - whether the bytesSource represents a Pure DBCS string without shift characters

Method Detail

alignLeft

public StringNL alignLeft(int iByteLengthRequested)

Removes spaces from the left side. Pads the string on the right side with spaces to the byte length. The Unicode equivalent will be shorter if the NL string contains shift-out, shift-in, or double byte characters.

alignNone

public StringNL alignNone(int iByteLengthRequested)

No spaces are removed. Pads the string on the right side with spaces to the requested byte length. The Unicode equivalent will be shorter if the NL string contains shift-out, shift-in, or double byte characters.

alignRight

public StringNL alignRight(int iByteLengthRequested)

Removes spaces from the right side. Pads the string on the left side with spaces to the byte length The Unicode equivalent will be shorter if the NL string contains shift-out, shift-in, or double byte characters.

createStateByteArray

protected void createStateByteArray()

createStateByteArray

protected byte[] createStateByteArray(byte[] bytes,
                                      boolean isPureDbcs)

Creates an array the same length as the byte array. Each entry of the state array contains the state of the entry in the byte array. The states are, single byte, shift-out, double byte one, double byte two, shift-in, LRM, or RLM. The array is created only for multibyte character strings.

equals

public boolean equals(StringNL strnlCompare)

Compares two NL strings for equality.

getByteLength

public int getByteLength()

Returns the byte length of the string if a multibyte string taking into account whether the encoding is multibyte and the encoding supports shift-out/shift-in. Otherwise returns the unicode string length.

getBytes

public byte[] getBytes()

Attempts to convert the string to a byte array with the given source encoding. If the source encoding is not supported, or the source encoding is not multibyte, a null is returned.

getBytes

public byte[] getBytes(String source)

Attempts to convert a string to a byte array with the given source encoding. If the source encoding is not supported, or the source encoding is not multibyte, a null is returned.

Since:

6.0.1 59898

getEncoding

public String getEncoding()

Retuns the encoding previously set.

getExpanded

public String getExpanded(boolean bPadDoubleByteCharacters,
                          boolean bUseSpaces)

Creates a line of DBCS unicode with shift-in / shift-out and optional padding characters. EBCDIC shift-out 0x0e, and shift-in 0x0f characters with 0x1e and 0x1f respectively. Optionally, the shift-in / shift-out and padding characters can be replaced by spaces.

getStyleString

public String getStyleString(String strStyle)

Sets an Lpex line's color style.

hasDBCS

public boolean hasDBCS()

Returns whether the string has DBCS characters or not.

isLowerCase

public boolean isLowerCase()

Returns whether this string is lower case.

main

public static void main(String[] args)

Unit test application.

repairEnding

protected byte[] repairEnding(byte[] bytes)

Corrects the end of a mixed (single and double byte) string given a byte array. A state array is created, and the array end is corrected.

repairEnding

protected byte[] repairEnding(byte[] bytes,
                              byte[] states,
                              StringNL.DbcsRepairEndingState endingRepairState)

Corrects the end of a double byte string given a byte array and a state array. The array is made valid by removing excessive end bytes. The end of the array is removed when the last byte is one of:

• shift-out
• first byte of double byte
• second byte of double byte

Parameters:

bytesLastChar - - array to contain the bytes of the last DBCS char if it is split by this truncate operation - if the array is null, then nothing is done

substring

public StringNL substring(int iBeginByteIndex)

Returns a unicode version of the substring starting at the given byte index to the end of the string.

substring

public StringNL substring(int iBeginByteIndex,
                          int iEndByteIndex)

Returns a unicode version of the substring taking into account that shift out and shift in characters occupy one byte position, and DBCS characters occupy two byte positions. The beginning of the substring is made valid using the following rules:

• If the first byte is a shift-in byte, the byte is dropped.
• If the first byte is the first byte of a double byte character, a shift-out byte is prepended.
• If the first byte is the second byte of a double byte character, the byte is dropped, and a shift-out byte is prepended.

As it is with String.substring, the end index is exclusive.

toString

public String toString()

Returns the string equivalent of the NL string.

Overrides:

toString in class Object

trim

public StringNL trim()

Remove spaces from both ends of the line

truncate

public StringNL truncate(int iByteLengthRequested,
                         StringNL.DbcsRepairEndingState endingRepairState)

Truncates to requested byte length or less.

Parameters:

iByteLengthRequested - - the requested length in EBCDIC bytes

chSplitLastChar - - if the end needed to be repaired

truncate

public StringNL truncate(int iByteLengthRequested)

Truncates to requested byte length or less.

getBidiCharIndexOfByte

public int getBidiCharIndexOfByte(int iTargetByteIndex)

Return the index of the Unicode character that corresponds to the target EBCDIC byte index

truncateBytes

protected byte[] truncateBytes(byte[] bytesSource,
                               int iByteLengthRequested,
                               StringNL.DbcsRepairEndingState endingRepairState)

Truncates the end of the byte array.

Parameters:

bytesSource - - the source array of EBCDIC bytes

iByteLengthRequested - - the number of EBCDIC bytes from the beginning of the source array to put into the target array

bRepairEnding - - whether to make sure that no DBCS char is split at the end and that shift-in chars are present if necessary

bytesLastChar - - array to contain the bytes of the last DBCS char if it is split by this truncate operation - if the array is null, then nothing is done

Returns:

the target array containing the desired number of bytes from the beginning of the source array

delete

public StringNL delete(int iEndByteIndex)

Deletes the specified number of bytes from this string and returns a unicode version of the string taking into account that shift out and shift in characters occupy one byte position, and DBCS characters occupy two byte positions. The string to return is made valid using the following rules:

• If the last byte (to be deleted) is a shift-in byte, the byte is dropped.
• If the last byte (to be deleted) is the first byte of a double byte character, a shift-out byte is prepended.
• If the last byte (to be deleted) is the second byte of a double byte character, a shift-out byte is prepended.

As it is with String.substring, the end index is exclusive.

convertFromVisualToLogical

public String convertFromVisualToLogical(boolean ensureRoundTrip)
                                  throws UnsupportedEncodingException

Converts the string passed to the constructor from visual BIDI format to logical.

Parameters:

ensureRoundTrip - true if you want to ensure the round trip (this means that BIDI directional marks would be added)

Returns:

The string in logical format.

Throws:

UnsupportedEncodingException - if CCSID is not specified in the constructor, then this exception is thrown.

Since:

6.0.1

convertFromLogicalToVisual

public String convertFromLogicalToVisual(boolean stripDirectionalMarks)
                                  throws UnsupportedEncodingException

Converts the string passed to the constructor from logical BIDI format to visual.

Parameters:

stripDirectionalMarks - true if you want to strip any BIDI directional marks.

Returns:

The string in visual format.

Throws:

UnsupportedEncodingException - if CCSID is not specified in the constructor, then this exception is thrown.

Since:

6.0.1

logString

public static void logString(String string)

indexOfRightToLeftCharacter

public int indexOfRightToLeftCharacter(int offset)

Find the index of the RTL character after the offset

Parameters:

offset -

Returns:

index of RTL character or -1

Since:

6.0.1 60039

isIgnoringBidiMarks

public boolean isIgnoringBidiMarks()

Check if ignoring bidirectional markers (ie is visual bidi)

Returns:

true if ignoring bidi marks

Since:

6.0.1 60039

byteIndexOf

public int byteIndexOf(char c)

Returns the byte index in the string of the specified character

Parameters:

c - the character to search

Returns:

the byte index of the character, -1 if not found

Since:

7.0

byteLastIndexOf

public int byteLastIndexOf(char c)

Returns the byte last index in the string of the specified character

Parameters:

c - the character to search

Returns:

the byte index of the character, -1 if not found

Since:

7.0

charAt

public char charAt(int location)

Returns the character at the location specified Use byteCharAt to retrieve charactre at a byte locations

Parameters:

location - The location to get the character of

Returns:

the character at the specified location

Since:

7.0

byteCharAt

public char byteCharAt(int location)

length

public int length()

isSecondDbcsByteAt

public boolean isSecondDbcsByteAt(int byteIndex)

isFirstDbcsByteAt

public boolean isFirstDbcsByteAt(int byteIndex)