Package net.sourceforge.pmd.lang.document

Class Chars

java.lang.Object

net.sourceforge.pmd.lang.document.Chars

All Implemented Interfaces:

CharSequence

public final class Chars
extends Object
implements CharSequence

View on a string which doesn't copy the array for subsequence operations. This view is immutable. Since it uses a string internally it benefits from Java 9's compacting feature, it can also be efficiently created from a StringBuilder. When confronted with an instance of this interface, please don't create substrings unnecessarily. Both subSequence(int, int) and slice(int, int) can cut out a subsequence without copying the underlying byte array. The Pattern API also works perfectly on arbitrary CharSequences, not just on strings. Lastly some methods here provided provide mediated access to the underlying string, which for many use cases is much more optimal than using this CharSequence directly, eg appendChars(StringBuilder), writeFully(Writer).

See Also:

• Chars::wrap, the factory method

Field Summary

Fields

Modifier and Type	Field	Description
static final Chars	EMPTY	An empty Chars instance.

Method Summary

Modifier and Type	Method	Description
void	appendChars(StringBuilder sb)	Append this character sequence on the given stringbuilder.
void	appendChars(StringBuilder sb, int start, int end)	Appends the character range identified by start and end offset into the string builder.
char	charAt(int index)
boolean	contentEquals(CharSequence cs)	Like contentEquals(CharSequence, boolean), considering case distinctions.
boolean	contentEquals(CharSequence cs, boolean ignoreCase)	Returns true if this char sequence is logically equal to the parameter.
boolean	endsWith(String suffix)	See String.endsWith(String).
boolean	equals(Object o)
ByteBuffer	getBytes(Charset charset)	Returns the characters of this charsequence encoded with the given charset.
void	getChars(int srcBegin, char @NonNull [] cbuf, int dstBegin, int count)	Copies 'count' characters from index 'srcBegin' into the given array, starting at 'dstBegin'.
int	hashCode()
int	indexOf(int ch)	See String.indexOf(int)
int	indexOf(int ch, int fromIndex)	See String.indexOf(int, int).
int	indexOf(int ch, int fromIndex, int toIndex)	Search a character in a range of this Chars instance.
int	indexOf(String searched, int fromIndex)	See String.indexOf(String, int).
boolean	isEmpty()	Whether this slice is the empty string.
int	lastIndexOf(int ch, int fromIndex)	See String.lastIndexOf(int, int).
int	length()
Iterable<Chars>	lines()	Returns an iterable over the lines of this char sequence.
Stream<Chars>	lineStream()	Returns a stream of lines yielded by lines().
Reader	newReader()	Returns a new reader for the whole contents of this char sequence.
Chars	removePrefix(String charSeq)	Remove the prefix if it is present, otherwise returns this.
Chars	removeSuffix(String charSeq)	Remove the suffix if it is present, otherwise returns this.
Chars	slice(int off, int len)	Like subSequence(int, int) but with offset + length instead of start + end.
Chars	slice(TextRegion region)	Slice a region of text.
Iterable<Chars>	splits(Pattern regex)	Split this slice into subslices, like String.split(String), except it's iterated lazily.
boolean	startsWith(char prefix, int fromIndex)
boolean	startsWith(String prefix)	See String.startsWith(String).
boolean	startsWith(String prefix, int fromIndex)	See String.startsWith(String, int).
Chars	subSequence(int start)	Returns the subsequence that starts at the given offset and ends at the end of this string.
Chars	subSequence(int start, int end)
String	substring(int start)
String	substring(int start, int end)	Returns the substring between the given offsets.
@NonNull String	toString()
StringBuilder	toStringBuilder()	Returns a new stringbuilder containing the whole contents of this char sequence.
Chars	trim()	Like String.trim().
Chars	trimBlankLines()	Remove trailing and leading blank lines.
Chars	trimEnd()	Returns a subsequence which does not end with control characters (<= 32).
Chars	trimStart()	Returns a subsequence which does not start with control characters (<= 32).
static Chars	wrap(CharSequence chars)	Wraps the given char sequence into a Chars.
void	write(@NonNull Writer writer, int start, int count)	Write a range of characters to the given writer.
void	writeFully(@NonNull Writer writer)	Write all characters of this buffer into the given writer.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence

chars, codePoints

Field Details

EMPTY

public static final Chars EMPTY

An empty Chars instance.

Method Details

isEmpty

public boolean isEmpty()

Whether this slice is the empty string.

Specified by:

isEmpty in interface CharSequence

wrap

public static Chars wrap(CharSequence chars)

Wraps the given char sequence into a Chars. This may call CharSequence.toString(). If the sequence is already a Chars, returns it. This is the main factory method for this class. You can eg pass a StringBuilder if you want.

writeFully

public void writeFully(@NonNull Writer writer)
                throws IOException

Write all characters of this buffer into the given writer.

Parameters:

writer - A writer

Throws:

NullPointerException - If the writer is null

IOException

write

public void write(@NonNull Writer writer,
 int start,
 int count)
           throws IOException

Write a range of characters to the given writer.

Parameters:

writer - A writer

start - Start offset in this CharSequence

count - Number of characters

Throws:

IOException - If the writer throws

IndexOutOfBoundsException - See Writer.write(int)

getChars

public void getChars(int srcBegin,
 char @NonNull [] cbuf,
 int dstBegin,
 int count)

Copies 'count' characters from index 'srcBegin' into the given array, starting at 'dstBegin'.

Parameters:

srcBegin - Start offset in this CharSequence

cbuf - Character array

dstBegin - Start index in the array

count - Number of characters to copy

Throws:

NullPointerException - If the array is null (may)

IndexOutOfBoundsException - See String.getChars(int, int, char[], int)

appendChars

public void appendChars(StringBuilder sb,
 int start,
 int end)

Appends the character range identified by start and end offset into the string builder. This is much more efficient than calling StringBuilder.append(CharSequence) with this as the parameter, especially on Java 9+.

Parameters:

start - Start index (inclusive)

end - End index (exclusive)

Throws:

IndexOutOfBoundsException - See StringBuilder.append(CharSequence, int, int)

appendChars

public void appendChars(StringBuilder sb)

Append this character sequence on the given stringbuilder. This is much more efficient than calling StringBuilder.append(CharSequence) with this as the parameter, especially on Java 9+.

Parameters:

sb - String builder

getBytes

public ByteBuffer getBytes(Charset charset)

Returns the characters of this charsequence encoded with the given charset.

indexOf

public int indexOf(String searched,
 int fromIndex)

See String.indexOf(String, int).

indexOf

public int indexOf(int ch)

See String.indexOf(int)

indexOf

public int indexOf(int ch,
 int fromIndex)

See String.indexOf(int, int).

indexOf

public int indexOf(int ch,
 int fromIndex,
 int toIndex)

Search a character in a range of this Chars instance.

Parameters:

ch - Character to search

fromIndex - From index (inclusive)

toIndex - To index (exclusive)

Throws:

AssertionError - if fromIndex > toIndex

lastIndexOf

public int lastIndexOf(int ch,
 int fromIndex)

See String.lastIndexOf(int, int).

startsWith

public boolean startsWith(String prefix,
 int fromIndex)

See String.startsWith(String, int).

startsWith

public boolean startsWith(String prefix)

See String.startsWith(String).

startsWith

public boolean startsWith(char prefix,
 int fromIndex)

endsWith

public boolean endsWith(String suffix)

See String.endsWith(String).

trimStart

public Chars trimStart()

Returns a subsequence which does not start with control characters (<= 32). This is consistent with String.trim().

trimEnd

public Chars trimEnd()

Returns a subsequence which does not end with control characters (<= 32). This is consistent with String.trim().

trim

public Chars trim()

Like String.trim().

trimBlankLines

public Chars trimBlankLines()

Remove trailing and leading blank lines. The resulting string does not end with a line terminator.

removeSuffix

public Chars removeSuffix(String charSeq)

Remove the suffix if it is present, otherwise returns this.

removePrefix

public Chars removePrefix(String charSeq)

Remove the prefix if it is present, otherwise returns this.

contentEquals

public boolean contentEquals(CharSequence cs,
 boolean ignoreCase)

Returns true if this char sequence is logically equal to the parameter. This means they're equal character-by-character. This is more general than equals(Object), which will only answer true if the parameter is a Chars.

Parameters:

cs - Another char sequence

ignoreCase - Whether to ignore case

Returns:

True if both sequences are logically equal

contentEquals

public boolean contentEquals(CharSequence cs)

Like contentEquals(CharSequence, boolean), considering case distinctions.

Parameters:

cs - A char sequence

Returns:

True if both sequences are logically equal, considering case

length

public int length()

Specified by:

length in interface CharSequence

charAt

public char charAt(int index)

Specified by:

charAt in interface CharSequence

subSequence

public Chars subSequence(int start,
 int end)

Specified by:

subSequence in interface CharSequence

subSequence

public Chars subSequence(int start)

Returns the subsequence that starts at the given offset and ends at the end of this string. Similar to String.substring(int).

slice

public Chars slice(TextRegion region)

Slice a region of text.

Parameters:

region - A region

Returns:

A Chars instance

Throws:

IndexOutOfBoundsException - If the region is not a valid range

slice

public Chars slice(int off,
 int len)

Like subSequence(int, int) but with offset + length instead of start + end.

Parameters:

off - Start of the slice (0 <= off < this.length())

len - Length of the slice (0 <= len <= this.length() - off)

Returns:

A Chars instance

Throws:

IndexOutOfBoundsException - If the parameters are not a valid range

substring

public String substring(int start,
 int end)

Returns the substring between the given offsets. given length.

Note: Unlike slice or subSequence, this method will create a new String which involves copying the backing char array. Don't use it unnecessarily.

Parameters:

start - Start offset (0 <= start < this.length())

end - End offset (start <= end <= this.length())

Returns:

A substring

Throws:

IndexOutOfBoundsException - If the parameters are not a valid range

See Also:

• String.substring(int, int)

substring

public String substring(int start)

toString

public @NonNull String toString()

Specified by:

toString in interface CharSequence

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

lines

public Iterable<Chars> lines()

Returns an iterable over the lines of this char sequence. The lines are yielded without line separators. Like BufferedReader.readLine(), a line delimiter is CR, LF or CR+LF.

lineStream

public Stream<Chars> lineStream()

Returns a stream of lines yielded by lines().

toStringBuilder

public StringBuilder toStringBuilder()

Returns a new stringbuilder containing the whole contents of this char sequence.

splits

public Iterable<Chars> splits(Pattern regex)

Split this slice into subslices, like String.split(String), except it's iterated lazily.

newReader

public Reader newReader()

Returns a new reader for the whole contents of this char sequence.