org.apache.flink.types

Class StringValue

java.lang.Object

org.apache.flink.types.StringValue

All Implemented Interfaces:

Serializable, Appendable, CharSequence, Comparable<StringValue>, IOReadableWritable, CopyableValue<StringValue>, Key<StringValue>, NormalizableKey<StringValue>, ResettableValue<StringValue>, Value

@Public
public class StringValue
extends Object
implements NormalizableKey<StringValue>, CharSequence, ResettableValue<StringValue>, CopyableValue<StringValue>, Appendable

Mutable string data type that implements the Key interface. StringValue encapsulates the basic functionality of a String, in a serializable and mutable way.

The mutability allows to reuse the object inside the user code, also across invocations. Reusing a StringValue object helps to increase the performance, as string objects are rather heavy-weight objects and incur a lot of garbage collection overhead, if created and destroyed en masse.

See Also:

NormalizableKey, String, CharSequence, Serialized Form

Constructor Summary

Constructors

Constructor and Description
StringValue() Initializes the encapsulated String object with an empty string.
StringValue(CharSequence value) Initializes this StringValue to the value of the given string.
StringValue(StringValue value) Initializes this StringValue to a copy the given StringValue.
StringValue(StringValue value, int offset, int len) Initializes the StringValue to a sub-string of the given StringValue.

Method Summary

Modifier and Type	Method and Description
Appendable	append(char c)
Appendable	append(CharSequence csq)
Appendable	append(CharSequence csq, int start, int end)
Appendable	append(StringValue csq)
Appendable	append(StringValue csq, int start, int end)
char	charAt(int index)
int	compareTo(StringValue other)
StringValue	copy() Performs a deep copy of this object into a new instance.
void	copy(DataInputView in, DataOutputView target) Copies the next serialized instance from source to target.
void	copyNormalizedKey(MemorySegment target, int offset, int len) Writes a normalized key for the given record into the target byte array, starting at the specified position an writing exactly the given number of bytes.
static void	copyString(DataInput in, DataOutput out)
void	copyTo(StringValue target) Performs a deep copy of this object into the target instance.
boolean	equals(Object obj) Compares the object on equality with another object.
int	find(CharSequence str) Finds any occurrence of the str character sequence in this StringValue.
int	find(CharSequence str, int start) Finds any occurrence of the str character sequence in this StringValue.
int	getBinaryLength() Gets the length of the data type when it is serialized, in bytes.
char[]	getCharArray() Returns this StringValue's internal character data.
int	getMaxNormalizedKeyLen() Gets the maximal length of normalized keys that the data type would produce to determine the order of instances solely by the normalized key.
String	getValue() Gets this StringValue as a String.
int	hashCode() All keys must override the hash-code function to generate proper deterministic hash codes, based on their contents.
int	length()
void	read(DataInputView in) Reads the object's internal data from the given data input view.
static String	readString(DataInput in)
void	setLength(int len) Sets a new length for the string.
void	setValue(char[] chars, int offset, int len) Sets the value of the StringValue to a substring of the given value.
void	setValue(CharBuffer buffer) Sets the contents of this string to the contents of the given CharBuffer.
void	setValue(CharSequence value) Sets the value of the StringValue to the given string.
void	setValue(CharSequence value, int offset, int len) Sets the value of the StringValue to a substring of the given string.
void	setValue(StringValue value) Sets the value of the StringValue to the given string.
void	setValue(StringValue value, int offset, int len) Sets the value of the StringValue to a substring of the given string.
void	setValueAscii(byte[] bytes, int offset, int len) Sets the value of this StringValue, assuming that the binary data is ASCII coded.
boolean	startsWith(CharSequence prefix) Checks whether this StringValue starts with the given prefix string.
boolean	startsWith(CharSequence prefix, int startIndex) Checks whether the substring, starting at the specified index, starts with the given prefix string.
CharSequence	subSequence(int start, int end)
StringValue	substring(int start) Returns a new StringValuestring that is a substring of this string.
StringValue	substring(int start, int end) Returns a new StringValuestring that is a substring of this string.
void	substring(StringValue target, int start) Copies a substring of this string into the given target StringValue.
void	substring(StringValue target, int start, int end) Copies a substring of this string into the given target StringValue.
String	toString()
void	write(DataOutputView out) Writes the object's internal data to the given data output view.
static void	writeString(CharSequence cs, DataOutput out)

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.CharSequence

chars, codePoints

Constructor Detail

StringValue

public StringValue()

Initializes the encapsulated String object with an empty string.

StringValue

public StringValue(CharSequence value)

Initializes this StringValue to the value of the given string.

Parameters:

value - The string containing the value for this StringValue.

StringValue

public StringValue(StringValue value)

Initializes this StringValue to a copy the given StringValue.

Parameters:

value - The initial value.

StringValue

public StringValue(StringValue value,
                   int offset,
                   int len)

Initializes the StringValue to a sub-string of the given StringValue.

Parameters:

value - The string containing the substring.

offset - The offset of the substring.

len - The length of the substring.

Method Detail

setLength

public void setLength(int len)

Sets a new length for the string.

Parameters:

len - The new length.

getCharArray

public char[] getCharArray()

Returns this StringValue's internal character data. The array might be larger than the string which is currently stored in the StringValue.

Returns:

The character data.

getValue

public String getValue()

Gets this StringValue as a String.

Returns:

A String resembling the contents of this StringValue.

setValue

public void setValue(CharSequence value)

Sets the value of the StringValue to the given string.

Parameters:

value - The new string value.

setValue

public void setValue(StringValue value)

Sets the value of the StringValue to the given string.

Specified by:

setValue in interface ResettableValue<StringValue>

Parameters:

value - The new string value.

setValue

public void setValue(StringValue value,
                     int offset,
                     int len)

Sets the value of the StringValue to a substring of the given string.

Parameters:

value - The new string value.

offset - The position to start the substring.

len - The length of the substring.

setValue

public void setValue(CharSequence value,
                     int offset,
                     int len)

Sets the value of the StringValue to a substring of the given string.

Parameters:

value - The new string value.

offset - The position to start the substring.

len - The length of the substring.

setValue

public void setValue(CharBuffer buffer)

Sets the contents of this string to the contents of the given CharBuffer. The characters between the buffer's current position (inclusive) and the buffer's limit (exclusive) will be stored in this string.

Parameters:

buffer - The character buffer to read the characters from.

setValue

public void setValue(char[] chars,
                     int offset,
                     int len)

Sets the value of the StringValue to a substring of the given value.

Parameters:

chars - The new string value (as a character array).

offset - The position to start the substring.

len - The length of the substring.

setValueAscii

public void setValueAscii(byte[] bytes,
                          int offset,
                          int len)

Sets the value of this StringValue, assuming that the binary data is ASCII coded. The n-th character of the StringValue corresponds directly to the n-th byte in the given array after the offset.

Parameters:

bytes - The binary character data.

offset - The offset in the array.

len - The number of bytes to read from the array.

substring

public StringValue substring(int start)

Returns a new StringValuestring that is a substring of this string. The substring begins at the given start index and ends at end of the string

Parameters:

start - The beginning index, inclusive.

Returns:

The substring.

Throws:

IndexOutOfBoundsException - Thrown, if the start is negative.

substring

public StringValue substring(int start,
                             int end)

Returns a new StringValuestring that is a substring of this string. The substring begins at the given start index and ends at end - 1.

Parameters:

start - The beginning index, inclusive.

end - The ending index, exclusive.

Returns:

The substring.

Throws:

IndexOutOfBoundsException - Thrown, if the start is negative, or the end is larger than the length.

substring

public void substring(StringValue target,
                      int start)

Copies a substring of this string into the given target StringValue. The substring begins at the given start index and ends at end of the string

Parameters:

target - The StringValue object to copy the substring to.

start - The beginning index, inclusive.

Throws:

IndexOutOfBoundsException - Thrown, if the start is negative.

substring

public void substring(StringValue target,
                      int start,
                      int end)

Copies a substring of this string into the given target StringValue. The substring begins at the given start index and ends at end - 1.

Parameters:

target - The StringValue object to copy the substring to.

start - The beginning index, inclusive.

end - The ending index, exclusive.

Throws:

IndexOutOfBoundsException - Thrown, if the start is negative, or the end is larger than the length.

find

public int find(CharSequence str)

Finds any occurrence of the str character sequence in this StringValue.

Returns:

The position of the first occurrence of the search string in the string value, or -1, if the character sequence was not found.

find

public int find(CharSequence str,
                int start)

Finds any occurrence of the str character sequence in this StringValue. The search starts at position start.

Returns:

The position of the first occurrence of the search string in the string value, or -1, if the character sequence was not found.

startsWith

public boolean startsWith(CharSequence prefix,
                          int startIndex)

Checks whether the substring, starting at the specified index, starts with the given prefix string.

Parameters:

prefix - The prefix character sequence.

startIndex - The position to start checking for the prefix.

Returns:

True, if this StringValue substring, starting at position startIndex has prefix as its prefix.

startsWith

public boolean startsWith(CharSequence prefix)

Checks whether this StringValue starts with the given prefix string.

Parameters:

prefix - The prefix character sequence.

Returns:

True, if this StringValue has prefix as its prefix.

append

public Appendable append(char c)

Specified by:

append in interface Appendable

append

public Appendable append(CharSequence csq)

Specified by:

append in interface Appendable

append

public Appendable append(CharSequence csq,
                         int start,
                         int end)

Specified by:

append in interface Appendable

append

public Appendable append(StringValue csq)

append

public Appendable append(StringValue csq,
                         int start,
                         int end)

read

public void read(DataInputView in)
          throws IOException

Description copied from interface: IOReadableWritable

Reads the object's internal data from the given data input view.

Specified by:

read in interface IOReadableWritable

Parameters:

in - the input view to read the data from

Throws:

IOException - thrown if any error occurs while reading from the input stream

write

public void write(DataOutputView out)
           throws IOException

Description copied from interface: IOReadableWritable

Writes the object's internal data to the given data output view.

Specified by:

write in interface IOReadableWritable

Parameters:

out - the output view to receive the data.

Throws:

IOException - thrown if any error occurs while writing to the output stream

toString

public String toString()

Specified by:

toString in interface CharSequence

Overrides:

toString in class Object

compareTo

public int compareTo(StringValue other)

Specified by:

compareTo in interface Comparable<StringValue>

hashCode

public int hashCode()

Description copied from interface: Key

All keys must override the hash-code function to generate proper deterministic hash codes, based on their contents.

Specified by:

hashCode in interface Key<StringValue>

Overrides:

hashCode in class Object

Returns:

The hash code of the key

equals

public boolean equals(Object obj)

Description copied from interface: Key

Compares the object on equality with another object.

Specified by:

equals in interface Key<StringValue>

Overrides:

equals in class Object

Parameters:

obj - The other object to compare against.

Returns:

True, iff this object is identical to the other object, false otherwise.

length

public int length()

Specified by:

length in interface CharSequence

charAt

public char charAt(int index)

Specified by:

charAt in interface CharSequence

subSequence

public CharSequence subSequence(int start,
                                int end)

Specified by:

subSequence in interface CharSequence

getMaxNormalizedKeyLen

public int getMaxNormalizedKeyLen()

Description copied from interface: NormalizableKey

Gets the maximal length of normalized keys that the data type would produce to determine the order of instances solely by the normalized key. A value of Integer.MAX_VALUE is interpreted as infinite.

For example, 32 bit integers return four, while Strings (potentially unlimited in length) return Integer.MAX_VALUE.

Specified by:

getMaxNormalizedKeyLen in interface NormalizableKey<StringValue>

Returns:

The maximal length of normalized keys.

copyNormalizedKey

public void copyNormalizedKey(MemorySegment target,
                              int offset,
                              int len)

Description copied from interface: NormalizableKey

Writes a normalized key for the given record into the target byte array, starting at the specified position an writing exactly the given number of bytes. Note that the comparison of the bytes is treating the bytes as unsigned bytes: int byteI = bytes[i] & 0xFF;

If the meaningful part of the normalized key takes less than the given number of bytes, then it must be padded. Padding is typically required for variable length data types, such as strings. The padding uses a special character, either 0 or 0xff, depending on whether shorter values are sorted to the beginning or the end.

Specified by:

copyNormalizedKey in interface NormalizableKey<StringValue>

Parameters:

target - The memory segment to put the normalized key bytes into.

offset - The offset in the byte array where the normalized key's bytes should start.

len - The number of bytes to put.

getBinaryLength

public int getBinaryLength()

Description copied from interface: CopyableValue

Gets the length of the data type when it is serialized, in bytes.

Specified by:

getBinaryLength in interface CopyableValue<StringValue>

Returns:

The length of the data type, or -1, if variable length.

copyTo

public void copyTo(StringValue target)

Description copied from interface: CopyableValue

Performs a deep copy of this object into the target instance.

Specified by:

copyTo in interface CopyableValue<StringValue>

Parameters:

target - Object to copy into.

copy

public StringValue copy()

Description copied from interface: CopyableValue

Performs a deep copy of this object into a new instance.

This method is useful for generic user-defined functions to clone a CopyableValue when storing multiple objects. With object reuse a deep copy must be created and type erasure prevents calling new.

Specified by:

copy in interface CopyableValue<StringValue>

Returns:

New object with copied fields.

copy

public void copy(DataInputView in,
                 DataOutputView target)
          throws IOException

Description copied from interface: CopyableValue

Copies the next serialized instance from source to target.

This method is equivalent to calling IOReadableWritable.read(DataInputView) followed by IOReadableWritable.write(DataOutputView) but does not require intermediate deserialization.

Specified by:

copy in interface CopyableValue<StringValue>

Parameters:

in - Data source for serialized instance.

target - Data target for serialized instance.

Throws:

IOException

See Also:

IOReadableWritable

readString

public static String readString(DataInput in)
                         throws IOException

Throws:

IOException

writeString

public static final void writeString(CharSequence cs,
                                     DataOutput out)
                              throws IOException

Throws:

IOException

copyString

public static final void copyString(DataInput in,
                                    DataOutput out)
                             throws IOException

Throws:

IOException