Class StringDataInstance
- java.lang.Object
-
- ghidra.program.model.data.StringDataInstance
-
- Direct Known Subclasses:
StringDataInstance.StaticStringInstance
public class StringDataInstance extends java.lang.Object
Represents an instance of a string in aMemBuffer
.This class handles all the details of detecting a terminated string's length, converting the bytes in the membuffer into a java native String, and converting the raw String into a formatted human-readable version, according to the various
SettingsDefinition
s attached to the string data location.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
StringDataInstance.StaticStringInstance
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
DEFAULT_CHARSET_NAME
static int
MAX_STRING_LENGTH
static StringDataInstance
NULL_INSTANCE
AStringDataInstance
that represents a non-existent string.static java.lang.String
UNKNOWN
static java.lang.String
UNKNOWN_DOT_DOT_DOT
-
Constructor Summary
Constructors Modifier Constructor Description protected
StringDataInstance()
StringDataInstance(DataType dataType, Settings settings, MemBuffer buf, int length)
Creates a string instance using the data in theMemBuffer
and the settings pulled from thestring data type
.StringDataInstance(DataType dataType, Settings settings, MemBuffer buf, int length, boolean isArrayElement)
Creates a string instance using the data in theMemBuffer
and the settings pulled from thestring data type
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description byte[]
encodeReplacementFromCharRepresentation(java.lang.CharSequence repr)
Parse and encode a single character from its representation to replace the current valuebyte[]
encodeReplacementFromCharValue(char[] value)
Encode a single character to replace the current valuebyte[]
encodeReplacementFromStringRepresentation(java.lang.CharSequence repr)
Parse and encode a string from its representation to replace the current valuebyte[]
encodeReplacementFromStringValue(java.lang.CharSequence value)
Encode a string to replace the current valueAddress
getAddress()
Returns the address of theMemBuffer
.StringDataInstance
getByteOffcut(int byteOffset)
Returns a newStringDataInstance
that points to the string characters that start atbyteOffset
from the start of this instance.StringDataInstance
getCharOffcut(int offsetChars)
Create a newStringDataInstance
that points to a portion of this instance, starting at a character offset (whereever that may be) into the data.java.lang.String
getCharRepresentation()
Convert a char value (or sequence of char values) in memory into its canonical unicode representation, using attached charset and encoding information.static java.lang.String
getCharRepresentation(DataType dataType, byte[] bytes, Settings settings)
Returns a string representation of the character(s) contained in the byte array, suitable for display as a single character, or as a sequence of characters.java.lang.String
getCharsetName()
Returns the string name of the charset.int
getDataLength()
Returns the length of this string's data, in bytes.java.lang.String
getLabel(java.lang.String prefixStr, java.lang.String abbrevPrefixStr, java.lang.String defaultStr, DataTypeDisplayOptions options)
java.lang.String
getOffcutLabelString(java.lang.String prefixStr, java.lang.String abbrevPrefixStr, java.lang.String defaultStr, DataTypeDisplayOptions options, int byteOffset)
static StringDataInstance
getStringDataInstance(DataType dataType, MemBuffer buf, Settings settings, int length)
Returns a newStringDataInstance
using the bytes in the MemBuffer.static StringDataInstance
getStringDataInstance(Data data)
Returns a newStringDataInstance
using the bytes in the data codeunit.DataType
getStringDataTypeGuess()
Maps aStringDataInstance
(this type) to the String DataType that best can handle this type of data.int
getStringLength()
Returns the length, in bytes, of the string data object contained in theMemBuffer
, or -1 if the length could not be determined.java.lang.String
getStringRepresentation()
Returns a formatted version of the string returned bygetStringValue()
.java.lang.String
getStringValue()
Returns the string contained in the specifiedMemBuffer
, or null if all the bytes of the string could not be read.java.lang.String
getTranslatedValue()
Returns the value of the storedtranslated settings
string.static boolean
isChar(Data data)
Returns true if theData
instance is one of the many 'char' data types.boolean
isMissingNullTerminator()
Returns true if the string should have a trailing NULL character and doesn't.boolean
isShowTranslation()
Returns true if the user should be shown the translated value of the string instead of the real value.static boolean
isString(Data data)
Returns true if theData
instance is a 'string'.static boolean
isStringDataType(DataType dt)
Returns true if the specifiedDataType
is (or could be) a string.java.lang.String
toString()
-
-
-
Field Detail
-
NULL_INSTANCE
public static final StringDataInstance NULL_INSTANCE
AStringDataInstance
that represents a non-existent string.Methods on this instance generally return null.
-
MAX_STRING_LENGTH
public static final int MAX_STRING_LENGTH
- See Also:
- Constant Field Values
-
DEFAULT_CHARSET_NAME
public static final java.lang.String DEFAULT_CHARSET_NAME
- See Also:
- Constant Field Values
-
UNKNOWN
public static final java.lang.String UNKNOWN
- See Also:
- Constant Field Values
-
UNKNOWN_DOT_DOT_DOT
public static final java.lang.String UNKNOWN_DOT_DOT_DOT
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
StringDataInstance
protected StringDataInstance()
-
StringDataInstance
public StringDataInstance(DataType dataType, Settings settings, MemBuffer buf, int length)
Creates a string instance using the data in theMemBuffer
and the settings pulled from thestring data type
.- Parameters:
dataType
-DataType
of the string, either aAbstractStringDataType
derived type or anArrayStringable
element-of-char-array type.settings
-Settings
attached to the data location.buf
-MemBuffer
containing the data.length
- Length passed from the caller to the datatype. -1 indicates a 'probe' trying to detect the length of an unknown string, otherwise it will be the length of the containing field of the data instance.
-
StringDataInstance
public StringDataInstance(DataType dataType, Settings settings, MemBuffer buf, int length, boolean isArrayElement)
Creates a string instance using the data in theMemBuffer
and the settings pulled from thestring data type
.- Parameters:
dataType
-DataType
of the string, either aAbstractStringDataType
derived type or anArrayStringable
element-of-char-array type.settings
-Settings
attached to the data location.buf
-MemBuffer
containing the data.length
- Length passed from the caller to the datatype. -1 indicates a 'probe' trying to detect the length of an unknown string, otherwise it will be the length of the containing field of the data instance.isArrayElement
- boolean flag, true indicates that the specified dataType is an element in an array (ie. char[] vs. just a plain char), causing the string layout to be forced toStringLayoutEnum.NULL_TERMINATED_BOUNDED
-
-
Method Detail
-
isString
public static boolean isString(Data data)
Returns true if theData
instance is a 'string'.- Parameters:
data
-Data
instance to test, null ok.- Returns:
- boolean true if string data.
-
isStringDataType
public static boolean isStringDataType(DataType dt)
Returns true if the specifiedDataType
is (or could be) a string.Arrays of char-like elements (see
ArrayStringable
) are treated as string data types. The actual data instance needs to be inspected to determine if the array is an actual string.- Parameters:
dt
- DataType to test- Returns:
- boolean true if data type is or could be a string
-
isChar
public static boolean isChar(Data data)
Returns true if theData
instance is one of the many 'char' data types.- Parameters:
data
-Data
instance to test, null ok- Returns:
- boolean true if char data
-
getCharRepresentation
public static java.lang.String getCharRepresentation(DataType dataType, byte[] bytes, Settings settings)
Returns a string representation of the character(s) contained in the byte array, suitable for display as a single character, or as a sequence of characters.- Parameters:
dataType
- theDataType
of the element containing the bytes (most likely a ByteDataType)bytes
- the big-endian ordered bytes to convert to a char representationsettings
- theSettings
object for the location where the bytes came from, or null- Returns:
- formatted string (typically with quotes around the contents): single character: 'a', multiple characters: "a\x12bc"
-
getStringDataInstance
public static StringDataInstance getStringDataInstance(Data data)
Returns a newStringDataInstance
using the bytes in the data codeunit.- Parameters:
data
-Data
item- Returns:
- new
StringDataInstance
, never NULL. SeeNULL_INSTANCE
.
-
getStringDataInstance
public static StringDataInstance getStringDataInstance(DataType dataType, MemBuffer buf, Settings settings, int length)
Returns a newStringDataInstance
using the bytes in the MemBuffer.- Parameters:
dataType
-DataType
of the bytes in the buffer.buf
- memory buffer containing the bytes.settings
- the Settings objectlength
- the length of the data.- Returns:
- new
StringDataInstance
, never NULL. SeeNULL_INSTANCE
.
-
getCharsetName
public java.lang.String getCharsetName()
Returns the string name of the charset.- Returns:
- string charset name
-
getAddress
public Address getAddress()
Returns the address of theMemBuffer
.- Returns:
Address
of the MemBuffer.
-
getDataLength
public int getDataLength()
Returns the length of this string's data, in bytes.- Returns:
- number of bytes in this string.
-
getStringLength
public int getStringLength()
Returns the length, in bytes, of the string data object contained in theMemBuffer
, or -1 if the length could not be determined.This is not the same as the number of characters in the string, or the number of bytes occupied by the characters. For instance, pascal strings have a 1 or 2 byte length field that increases the size of the string data object beyond the characters in the string, and null terminated strings have don't include the null character, but its presence is included in the size of the string object.
For length-specified string data types that do not use null-terminators and with a known data instance length (ie. not a probe), this method just returns the value specified in the constructor
length
parameter, otherwise a null-terminator is searched for.When searching for a null-terminator, the constructor
length
parameter will be respected or ignored depending on theStringLayoutEnum
.When the length parameter is ignored (ie. "unbounded" searching), the search is limited to
MAX_STRING_LENGTH
bytes.The MemBuffer's endian'ness is used to determine which end of the padded character field contains our n-bit character which will be tested for null-ness. (not the endian'ness of the character set name - ie. "UTF-16BE")
- Returns:
- length of the string (NOT including null term if null term probe), in bytes, or -1 if no terminator found.
-
isMissingNullTerminator
public boolean isMissingNullTerminator()
Returns true if the string should have a trailing NULL character and doesn't.- Returns:
- boolean true if the trailing NULL character is missing, false if string type doesn't need a trailing NULL character or if it is present.
-
getStringValue
public java.lang.String getStringValue()
Returns the string contained in the specifiedMemBuffer
, or null if all the bytes of the string could not be read.This method deals in characters of size
charSize
, that might bepadded
to a larger size. The raw n-byte characters are converted into a Java String using a JavaCharset
or by using a custom Ghidra conversion. (see convertBytesToStringCustomCharset)The MemBuffer's endian'ness is used to determine which end of the
padded
field contains ourcharSize
character bytes which will be used to create the java String.- Returns:
- String containing the characters in buf or null if unable to read all
length
bytes from the membuffer.
-
getStringRepresentation
public java.lang.String getStringRepresentation()
Returns a formatted version of the string returned bygetStringValue()
.The resulting string will be formatted with quotes around the parts that contain plain ASCII alpha characters (and simple escape sequences), and out-of-range byte-ish values listed as comma separated hex-encoded values:
Example (quotes are part of result):
"Test\tstring",01,02,"Second\npart",00
- Returns:
- formatted String
-
getTranslatedValue
public java.lang.String getTranslatedValue()
Returns the value of the storedtranslated settings
string.- Returns:
- previously translated string.
-
isShowTranslation
public boolean isShowTranslation()
Returns true if the user should be shown the translated value of the string instead of the real value.- Returns:
- boolean true if should show previously translated value.
-
getCharRepresentation
public java.lang.String getCharRepresentation()
Convert a char value (or sequence of char values) in memory into its canonical unicode representation, using attached charset and encoding information.- Returns:
- String containing the representation of the char.
-
getLabel
public java.lang.String getLabel(java.lang.String prefixStr, java.lang.String abbrevPrefixStr, java.lang.String defaultStr, DataTypeDisplayOptions options)
-
getOffcutLabelString
public java.lang.String getOffcutLabelString(java.lang.String prefixStr, java.lang.String abbrevPrefixStr, java.lang.String defaultStr, DataTypeDisplayOptions options, int byteOffset)
-
getByteOffcut
public StringDataInstance getByteOffcut(int byteOffset)
Returns a newStringDataInstance
that points to the string characters that start atbyteOffset
from the start of this instance.If the requested offset is not valid, the base string instance (itself) will be returned instead of a new instance.
- Parameters:
byteOffset
- number of bytes from start of data instance to start new instance.- Returns:
- new StringDataInstance, or
this
if offset not valid.
-
getCharOffcut
public StringDataInstance getCharOffcut(int offsetChars)
Create a newStringDataInstance
that points to a portion of this instance, starting at a character offset (whereever that may be) into the data.- Parameters:
offsetChars
- number of characters from the beginning of the string to start the new StringDataInstance.- Returns:
- new
StringDataInstance
pointing to a subset of characters, or thethis
instance if there was an error.
-
getStringDataTypeGuess
public DataType getStringDataTypeGuess()
Maps aStringDataInstance
(this type) to the String DataType that best can handle this type of data.I dare myself to type Type one more time.
- Returns:
DataType
, defaulting toStringDataType
if no direct match found.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
encodeReplacementFromStringValue
public byte[] encodeReplacementFromStringValue(java.lang.CharSequence value) throws java.nio.charset.CharacterCodingException
Encode a string to replace the current value- Parameters:
value
- the value to encode- Returns:
- the encoded value
- Throws:
java.nio.charset.CharacterCodingException
- if a character could not be encoded
-
encodeReplacementFromStringRepresentation
public byte[] encodeReplacementFromStringRepresentation(java.lang.CharSequence repr) throws java.nio.charset.MalformedInputException, java.nio.charset.UnmappableCharacterException, StringRenderParser.StringParseException
Parse and encode a string from its representation to replace the current value- Parameters:
repr
- the representation of the string- Returns:
- the encoded value
- Throws:
StringRenderParser.StringParseException
- if the representation could not be parsedjava.nio.charset.UnmappableCharacterException
- if a character could not be encodedjava.nio.charset.MalformedInputException
- if the input contains invalid character sequences
-
encodeReplacementFromCharValue
public byte[] encodeReplacementFromCharValue(char[] value) throws java.nio.charset.CharacterCodingException
Encode a single character to replace the current value- Parameters:
value
- a single code point to encode- Returns:
- the encoded value
- Throws:
java.nio.charset.CharacterCodingException
- if the character could not be encoded
-
encodeReplacementFromCharRepresentation
public byte[] encodeReplacementFromCharRepresentation(java.lang.CharSequence repr) throws java.nio.charset.MalformedInputException, java.nio.charset.UnmappableCharacterException, StringRenderParser.StringParseException
Parse and encode a single character from its representation to replace the current value- Parameters:
repr
- the representation of a single character- Returns:
- the encoded value
- Throws:
StringRenderParser.StringParseException
- if the representation could not be parsedjava.nio.charset.UnmappableCharacterException
- if a character could not be encodedjava.nio.charset.MalformedInputException
- if the input contains invalid character sequences
-
-