Top Description Fields Constructors Methods
org.apache.poi.util

public final Class StringUtil

extends Object
Class Inheritance
Annotations
@Internal
Static Imports
java.nio.charset.StandardCharsets.ISO_8859_1, .StandardCharsets.UTF_8
Collection of string handling utilities

Field Summary

Modifier and TypeField and Description
private static final int
DEFAULT_MAX_RECORD_LENGTH

private static int
MAX_RECORD_LENGTH

private static final int[]
symbolMap_f020

private static final int[]
symbolMap_f0a0

public static final Charset
UTF16LE

public static final Charset
UTF8

public static final Charset
WIN_1252

Constructor Summary

AccessConstructor and Description
private
StringUtil()

Method Summary

Modifier and TypeMethod and Description
public static int

Returns:

the number of occurrences, 0 if the CharSequence is null
countMatches(CharSequence
the CharSequence to check, may be null
haystack, char
the character to count the quantity of
needle)

Count number of occurrences of needle in haystack Has same signature as org.apache.commons.lang3.StringUtils#countMatches

public static boolean
endsWithIgnoreCase(String haystack, String suffix)

Tests if the string ends with the specified suffix, ignoring case consideration.

public static int

Returns:

the number of bytes that would be written by writeUnicodeString(LittleEndianOutput, String)
getEncodedSize(String value)

public static String

Returns:

String generated String instance by reading byte array (ISO-8859-1)
getFromCompressedUnicode(final byte[]
byte array to read
string, final int
offset to read byte array
offset, final int
length to read byte array
len)

Read 8 bit data (in ISO-8859-1 codepage) into a (unicode) Java String and return.

public static String

Returns:

String generated String instance by reading byte array (UTF-8)
getFromCompressedUTF8(final byte[]
byte array to read
string, final int
offset to read byte array
offset, final int
length to read byte array
len)

Read 8 bit data (in UTF-8 codepage) into a (unicode) Java String and return.

public static String

Returns:

the converted string, never null.
getFromUnicodeLE(final byte[]
the byte array to be converted
string, final int
the initial offset into the byte array. it is assumed that string[ offset ] and string[ offset + 1 ] contain the first 16-bit unicode character
offset, final int
the length of the final string
len)

Given a byte array of 16-bit unicode characters in Little Endian format (most important byte last), return a Java String representation of it.

public static String

Returns:

the converted string, never null
getFromUnicodeLE(byte[]
the byte array to be converted
string)

Given a byte array of 16-bit unicode characters in little endian format (most important byte last), return a Java String representation of it.

public static String

Returns:

the converted string, never null.
getFromUnicodeLE0Terminated(final byte[]
the byte array to be converted
string, final int
the initial offset into the byte array. it is assumed that string[ offset ] and string[ offset + 1 ] contain the first 16-bit unicode character
offset, final int
the max. length of the final string
len)

Given a byte array of 16-bit unicode characters in Little Endian format (most important byte last), return a Java String representation of it.

public static int

Returns:

the max record length allowed for StringUtil
getMaxRecordLength()

public static String

Returns:

the encoding we want to use, currently hardcoded to ISO-8859-1
getPreferredEncoding()

public static byte[]

Returns:

the byte array of 16-bit unicode characters
getToUnicodeLE(String
the string
string)

Convert String to 16-bit unicode characters in little endian format

public static boolean

Returns:

boolean result true:string has at least one multibyte character
hasMultibyte(String
string to check
value)

check the parameter has multibyte character

public static boolean

Returns:

true if the CharSequence is null, empty or whitespace only
isBlank(final CharSequence
the CharSequence to check, may be null
cs)

Checks if a CharSequence is empty (""), null or whitespace only.

public static boolean

Returns:

true if the CharSequence is not empty and not null and not whitespace only
isNotBlank(final CharSequence
the CharSequence to check, may be null
cs)

Checks if a CharSequence is not empty (""), not null and not whitespace only.

public static boolean
isUpperCase(char c)

public static String
join(Object[] array, String separator)

public static String
join(Object[] array)

public static String
join(String separator, Object... array)

public static int

Returns:

CharSequence length or 0 if the CharSequence is null.
length(final CharSequence
a CharSequence or null
cs)

Gets a CharSequence length or 0 if the CharSequence is null.

private static int
mapMsCodepoint(int cp)

public static String

Returns:

the string with mapped characters
mapMsCodepointString(String
the original string
string)

Some strings may contain encoded characters of the unicode private use area.

public static void
putCompressedUnicode(String
the String containing the data to be written
input, byte[]
the byte array to which the data is to be written
output, int
an offset into the byte arrat at which the data is start when written
offset)

Takes a unicode (java) string, and returns it as 8 bit data (in ISO-8859-1 codepage).

public static void
putCompressedUnicode(String input, LittleEndianOutput out)

public static void
putUnicodeLE(String
the String containing the unicode data to be written
input, byte[]
the byte array to hold the uncompressed unicode, should be twice the length of the String
output, int
the offset to start writing into the byte array
offset)

Takes a unicode string, and returns it as little endian (most important byte last) bytes in the supplied byte array.

public static void
putUnicodeLE(String input, LittleEndianOutput out)

public static String

Returns:

ISO_8859_1 encoded result
readCompressedUnicode(LittleEndianInput
stream,
in, int
number pf chars
nChars)

public static String
readUnicodeLE(LittleEndianInput in, int nChars)

public static String
readUnicodeString(LittleEndianInput in)

InputStream in is expected to contain:

  1. ushort nChars
  2. byte is16BitFlag
  3. byte[]/char[] characterData
public static String
readUnicodeString(LittleEndianInput in, int nChars)

InputStream in is expected to contain:

  1. byte is16BitFlag
  2. byte[]/char[] characterData
public static String

Returns:

String with repeated character
repeat(final char
character to repeat
ch, final int
number of times to repeat char, negative treated as zero
repeat)

Returns padding using the specified delimiter repeated to a given length.

public static void
setMaxRecordLength(int
the max record length allowed for StringUtil
length)

public static boolean
startsWithIgnoreCase(String haystack, String prefix)

Tests if the string starts with the specified prefix, ignoring case consideration.

public static String
toLowerCase(char c)

public static String
toUpperCase(char c)

public static void
writeUnicodeString(LittleEndianOutput out, String value)

OutputStream out will get:

  1. ushort nChars
  2. byte is16BitFlag
  3. byte[]/char[] characterData
public static void
writeUnicodeStringFlagAndData(LittleEndianOutput out, String value)

OutputStream out will get:

  1. byte is16BitFlag
  2. byte[]/char[] characterData
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DEFAULT_MAX_RECORD_LENGTHback to summary
private static final int DEFAULT_MAX_RECORD_LENGTH
MAX_RECORD_LENGTHback to summary
private static int MAX_RECORD_LENGTH
symbolMap_f020back to summary
private static final int[] symbolMap_f020
symbolMap_f0a0back to summary
private static final int[] symbolMap_f0a0
UTF16LEback to summary
public static final Charset UTF16LE
UTF8back to summary
public static final Charset UTF8
WIN_1252back to summary
public static final Charset WIN_1252

Constructor Detail

StringUtilback to summary
private StringUtil()

Method Detail

countMatchesback to summary
public static int countMatches(CharSequence haystack, char needle)

Count number of occurrences of needle in haystack Has same signature as org.apache.commons.lang3.StringUtils#countMatches

Parameters
haystack:CharSequence

the CharSequence to check, may be null

needle:char

the character to count the quantity of

Returns:int

the number of occurrences, 0 if the CharSequence is null

endsWithIgnoreCaseback to summary
public static boolean endsWithIgnoreCase(String haystack, String suffix)

Tests if the string ends with the specified suffix, ignoring case consideration.

getEncodedSizeback to summary
public static int getEncodedSize(String value)
Returns:int

the number of bytes that would be written by writeUnicodeString(LittleEndianOutput, String)

getFromCompressedUnicodeback to summary
public static String getFromCompressedUnicode(final byte[] string, final int offset, final int len)

Read 8 bit data (in ISO-8859-1 codepage) into a (unicode) Java String and return. (In Excel terms, read compressed 8 bit unicode as a string)

Parameters
string:byte[]

byte array to read

offset:int

offset to read byte array

len:int

length to read byte array

Returns:String

String generated String instance by reading byte array (ISO-8859-1)

getFromCompressedUTF8back to summary
public static String getFromCompressedUTF8(final byte[] string, final int offset, final int len)

Read 8 bit data (in UTF-8 codepage) into a (unicode) Java String and return. (In Excel terms, read compressed 8 bit unicode as a string)

Parameters
string:byte[]

byte array to read

offset:int

offset to read byte array

len:int

length to read byte array

Returns:String

String generated String instance by reading byte array (UTF-8)

getFromUnicodeLEback to summary
public static String getFromUnicodeLE(final byte[] string, final int offset, final int len) throws ArrayIndexOutOfBoundsException, IllegalArgumentException

Given a byte array of 16-bit unicode characters in Little Endian format (most important byte last), return a Java String representation of it.

{ 0x16, 0x00 } -0x16

Parameters
string:byte[]

the byte array to be converted

offset:int

the initial offset into the byte array. it is assumed that string[ offset ] and string[ offset + 1 ] contain the first 16-bit unicode character

len:int

the length of the final string

Returns:String

the converted string, never null.

Exceptions
ArrayIndexOutOfBoundsException:
if offset is out of bounds for the byte array (i.e., is negative or is greater than or equal to string.length)
IllegalArgumentException:
if len is too large (i.e., there is not enough data in string to create a String of that length)
getFromUnicodeLEback to summary
public static String getFromUnicodeLE(byte[] string)

Given a byte array of 16-bit unicode characters in little endian format (most important byte last), return a Java String representation of it.

{ 0x16, 0x00 } -0x16

Parameters
string:byte[]

the byte array to be converted

Returns:String

the converted string, never null

getFromUnicodeLE0Terminatedback to summary
public static String getFromUnicodeLE0Terminated(final byte[] string, final int offset, final int len) throws ArrayIndexOutOfBoundsException, IllegalArgumentException

Given a byte array of 16-bit unicode characters in Little Endian format (most important byte last), return a Java String representation of it. Scans the byte array for two continous 0 bytes and returns the string before.

#61881: there seem to be programs out there, which write the 0-termination also at the beginning of the string. Check if the next two bytes contain a valid ascii char and correct the _recdata with a '?' char

Parameters
string:byte[]

the byte array to be converted

offset:int

the initial offset into the byte array. it is assumed that string[ offset ] and string[ offset + 1 ] contain the first 16-bit unicode character

len:int

the max. length of the final string

Returns:String

the converted string, never null.

Exceptions
ArrayIndexOutOfBoundsException:
if offset is out of bounds for the byte array (i.e., is negative or is greater than or equal to string.length)
IllegalArgumentException:
if len is too large (i.e., there is not enough data in string to create a String of that length)
getMaxRecordLengthback to summary
public static int getMaxRecordLength()
Returns:int

the max record length allowed for StringUtil

getPreferredEncodingback to summary
public static String getPreferredEncoding()
Returns:String

the encoding we want to use, currently hardcoded to ISO-8859-1

getToUnicodeLEback to summary
public static byte[] getToUnicodeLE(String string)

Convert String to 16-bit unicode characters in little endian format

Parameters
string:String

the string

Returns:byte[]

the byte array of 16-bit unicode characters

hasMultibyteback to summary
public static boolean hasMultibyte(String value)

check the parameter has multibyte character

Parameters
value:String

string to check

Returns:boolean

boolean result true:string has at least one multibyte character

isBlankback to summary
public static boolean isBlank(final CharSequence cs)

Checks if a CharSequence is empty (""), null or whitespace only.

Whitespace is defined by Character#isWhitespace(char).

StringUtil.isBlank(null)      = true
StringUtil.isBlank("")        = true
StringUtil.isBlank(" ")       = true
StringUtil.isBlank("bob")     = false
StringUtil.isBlank("  bob  ") = false
copied from commons-lang3
Parameters
cs:CharSequence

the CharSequence to check, may be null

Returns:boolean

true if the CharSequence is null, empty or whitespace only

isNotBlankback to summary
public static boolean isNotBlank(final CharSequence cs)

Checks if a CharSequence is not empty (""), not null and not whitespace only.

Whitespace is defined by Character#isWhitespace(char).

StringUtil.isNotBlank(null)      = false
StringUtil.isNotBlank("")        = false
StringUtil.isNotBlank(" ")       = false
StringUtil.isNotBlank("bob")     = true
StringUtil.isNotBlank("  bob  ") = true
copied from commons-lang3
Parameters
cs:CharSequence

the CharSequence to check, may be null

Returns:boolean

true if the CharSequence is not empty and not null and not whitespace only

isUpperCaseback to summary
public static boolean isUpperCase(char c)
Annotations
@Internal
joinback to summary
public static String join(Object[] array, String separator)
Annotations
@Internal
joinback to summary
public static String join(Object[] array)
Annotations
@Internal
joinback to summary
public static String join(String separator, Object... array)
Annotations
@Internal
lengthback to summary
public static int length(final CharSequence cs)

Gets a CharSequence length or 0 if the CharSequence is null. copied from commons-lang3

Parameters
cs:CharSequence

a CharSequence or null

Returns:int

CharSequence length or 0 if the CharSequence is null.

mapMsCodepointback to summary
private static int mapMsCodepoint(int cp)
mapMsCodepointStringback to summary
public static String mapMsCodepointString(String string)

Some strings may contain encoded characters of the unicode private use area. Currently the characters of the symbol fonts are mapped to the corresponding characters in the normal unicode range.

Parameters
string:String

the original string

Returns:String

the string with mapped characters

See Also
Private Use Area (symbol), Symbol font - Unicode alternatives for Greek and special characters in HTML
putCompressedUnicodeback to summary
public static void putCompressedUnicode(String input, byte[] output, int offset)

Takes a unicode (java) string, and returns it as 8 bit data (in ISO-8859-1 codepage). (In Excel terms, write compressed 8 bit unicode)

Parameters
input:String

the String containing the data to be written

output:byte[]

the byte array to which the data is to be written

offset:int

an offset into the byte arrat at which the data is start when written

putCompressedUnicodeback to summary
public static void putCompressedUnicode(String input, LittleEndianOutput out)
putUnicodeLEback to summary
public static void putUnicodeLE(String input, byte[] output, int offset)

Takes a unicode string, and returns it as little endian (most important byte last) bytes in the supplied byte array. (In Excel terms, write uncompressed unicode)

Parameters
input:String

the String containing the unicode data to be written

output:byte[]

the byte array to hold the uncompressed unicode, should be twice the length of the String

offset:int

the offset to start writing into the byte array

putUnicodeLEback to summary
public static void putUnicodeLE(String input, LittleEndianOutput out)
readCompressedUnicodeback to summary
public static String readCompressedUnicode(LittleEndianInput in, int nChars)
Parameters
in:LittleEndianInput

stream,

nChars:int

number pf chars

Returns:String

ISO_8859_1 encoded result

readUnicodeLEback to summary
public static String readUnicodeLE(LittleEndianInput in, int nChars)
readUnicodeStringback to summary
public static String readUnicodeString(LittleEndianInput in)

InputStream in is expected to contain:

  1. ushort nChars
  2. byte is16BitFlag
  3. byte[]/char[] characterData
For this encoding, the is16BitFlag is always present even if nChars==0.

This structure is also known as a XLUnicodeString.

readUnicodeStringback to summary
public static String readUnicodeString(LittleEndianInput in, int nChars)

InputStream in is expected to contain:

  1. byte is16BitFlag
  2. byte[]/char[] characterData
For this encoding, the is16BitFlag is always present even if nChars==0.
This method should be used when the nChars field is not stored as a ushort immediately before the is16BitFlag. Otherwise, readUnicodeString(LittleEndianInput) can be used.
repeatback to summary
public static String repeat(final char ch, final int repeat)

Returns padding using the specified delimiter repeated to a given length.

StringUtil.repeat('e', 0)  = ""
StringUtil.repeat('e', 3)  = "eee"
StringUtil.repeat('e', -2) = ""

Note

this method does not support padding with Unicode Supplementary Characters as they require a pair of chars to be represented.

copied from commons-lang3
Parameters
ch:char

character to repeat

repeat:int

number of times to repeat char, negative treated as zero

Returns:String

String with repeated character

setMaxRecordLengthback to summary
public static void setMaxRecordLength(int length)
Parameters
length:int

the max record length allowed for StringUtil

startsWithIgnoreCaseback to summary
public static boolean startsWithIgnoreCase(String haystack, String prefix)

Tests if the string starts with the specified prefix, ignoring case consideration.

toLowerCaseback to summary
public static String toLowerCase(char c)
Annotations
@Internal
toUpperCaseback to summary
public static String toUpperCase(char c)
Annotations
@Internal
writeUnicodeStringback to summary
public static void writeUnicodeString(LittleEndianOutput out, String value)

OutputStream out will get:

  1. ushort nChars
  2. byte is16BitFlag
  3. byte[]/char[] characterData
For this encoding, the is16BitFlag is always present even if nChars==0.
writeUnicodeStringFlagAndDataback to summary
public static void writeUnicodeStringFlagAndData(LittleEndianOutput out, String value)

OutputStream out will get:

  1. byte is16BitFlag
  2. byte[]/char[] characterData
For this encoding, the is16BitFlag is always present even if nChars==0.
This method should be used when the nChars field is not stored as a ushort immediately before the is16BitFlag. Otherwise, writeUnicodeString(LittleEndianOutput, String) can be used.