J020 Reading samples

When working with signal scripts, synchronization or searching,  users need to read sample data from signals and productions to compare and combine.

---

---

The interface IReadableSamples is the main interface to read sample data:

• To get the type of samples.
• Retrieve the available number of samples and their status.
• Fetch the domain position per sample and the index of a given domain position.
• Read the sample value.
• Create formatted text representation of samples.
• Handle groups.

Open JavaDoc Reference

---

---

What and where

A first overview about a signal can be taken using the following methods (derived from ISamples).

• getProcessType(): The process type defines how the samples are organized on the domain (Discrete: at any position; Continuous: at fixed positions with equal distance).
• getSignalType(): The signal type defines the data type of a signal (text, integer, float, ...).
• getSignalDescriptor(): The signal descriptor contains additional information about the signal.
• getCount(),isEmpty(),getGroups(): Provides the no of samples and groups.
• getDomainBase(): The domain of a signal may be Time,Frequency,Index,... . The domain base represents the the minimum distance between two samples (e.g. ns or ps).
• getStart(),getEnd(),getRate(): Used domain range and rate of the included samples.
• getStartUnits(),getEndUnits(),getRate()Units: Same as above, but as a multiple of its domain base (e.g. domain base=1ms; units = 100; -> domain value = 100ms).
• hasConflict(): Returns true if any included sample is marked to have a conflict.

public interface IReadableSamples extends IPackedSamples,ISampleConverter {
	...
	// derived from ISamples
	//
	// Signal and process type
	ProcessType getProcessType();
	SignalType getSignalType();
	SignalDescriptor getSignalDescriptor();
	//
	// no of sampels and groups
	boolean isEmpty();
	int getCount();
	int getGroups();
	//
	// domain base and range
	IDomainBase getDomainBase();
	DomainValue getStart();
	DomainValue getEnd();
	DomainValue getRate();
	long getStartUnits();
	long getEndUnits();
	long getRateUnits();
	//
	// are there any conflicts?
	boolean hasConflict();
	...
}

---

---

Indexed samples

Samples are indexed from 0 to count-1. A lot of method have the form xxxAt(int idx) and therefor refer to the sample at index idx. With the indexAt and units/positionAt methods you can shift between index and domain position. The index of a domain position belongs to the sample at the given domain position or the first one before.

// domain
int indexAt(long units);
int indexAt(DomainValue position);
long unitsAt(int idx);
DomainValue positionAt(int idx);
// status
boolean isNoneAt(int idx);
boolean isConflictAt(int idx);
...

A sample can be of type none, meaning it has no data or is not existing. A meaning of a "conflict" sample is use-case depended. If true, impulse will use conflict color (usually red) to paint the sample.

---

---

The sample value

Looking at the interface methods below you will find four types of value accessors:

• valueAt(int idx): The samples raw value (e.g Integer, int[], String, byte[]).
• compoundAt(int idx): The samples raw value packed into a class with related sample information (index, domain position, conflict flag, group information).
• packedAt(int idx): This method returns the binary representation of a sample value together with related sample information (index, domain position, conflict flag, group information).
• xxxValueAt(int idx), isXXXAt(int idx): Typed value of the sample at the given index, or null if there is no cast.

// value
Object valueAt(int idx);
CompoundValue compoundAt(int idx);
CompoundPack packedAt(int idx);
// typed value
//
// Logic
Logic logicValueAt(int idx);
int logicStateAt(int idx);
boolean isEdgeAt(int idx, int edge, ILogicDetector detector);
boolean isEdgeAt(int idx, int edge);
boolean isHighAt(int idx, ILogicDetector detector);
boolean isHighAt(int idx);   
boolean isLowAt(int idx, ILogicDetector detector);
boolean isLowAt(int idx);
// numerical
Number numberValueAt(int idx);
float floatValueAt(int idx);
double doubleValueAt(int idx);
BigDecimal bigDecimalValueAt(int idx);
long longValueAt(int idx);
int intValueAt(int idx);
BigIntegerteger bigIntValueAt(int idx);
// structured
Struct structValueAt(int idx);
// text
String stringValueAt(int idx);
// enumeration
Enumeration enumValueAt(int idx);
// binary data
byte[] bytesValueAt(int idx);
...

---

---

Formatted values

The text representation of a sample value can be read using the following methods.

• formatAt(int idx, int format): Formats sample idx using format 'format' ( ISample.FORMAT_...)
• defaultFormatAt(int idx): Returns the default format at index 'idx'.
• fhexAt,...: Formats sample idx using fixed formats (hex,dec,oct,..).

String formatAt(int idx, int format);
int defaultFormatAt(int idx);
String fhexAt(int idx);
String fdecAt(int idx);
String foctAt(int idx);
String fbinAt(int idx);
String fasciiAt(int idx);
...

---

---

Members

If a sample value contains a structure, like arrays and struct samples, you can use the interface IReadableMembers. You get an value object of type IReadableMembers:

• If you use the compoundAt(int idx) method.
• If the raw value is of type Struct or Transaction (Struct signal type).
• If you use a sample pointer (see next chapter).

The member value and formatting method are the same as above, just with the difference that they don't refer an index but a member (xxxOf(Object member)). The member object value can either be a string (for the name of the member, or an integer for its id (struct) or index (arrays).

The first section of IReadableMembers handles general member information:

• noOfMembers(): No of members in the given sample.
• nameOf(int member): Name of the member at given index (0--noOfMembers-1).
• hasMember(String member): Returns true if the value contains a member with the given name.
• memberWithContent(String content): Returns the first member that is marked to contain the given content.

public interface IReadableMembers extends ISample {
	
    
	// member information
	int noOfMembers();
	String nameOf(int member);
	boolean hasMember(String member);
	Object memberWithContent(String content);
    
    // member values
	Object valueOf(Object member);
	Logic logicValueOf(Object member);
	int logicStateOf(Object member);
	boolean isHighOf(Object member, ILogicDetector detector);
	boolean isLowOf(Object member, ILogicDetector detector);
	Number numberValueOf(Object member);
	float floatValueOf(Object member);
	double doubleValueOf(Object member);
	BigDecimal bigDecimalValueOf(Object member);
	long longValueOf(Object member);
	int intValueOf(Object member);
	BigInteger bigIntValueOf(Object member);
	String stringValueOf(Object member);
	Enumeration enumValueOf(Object member);
	byte[] bytesValueOf(Object member);
    
    // member formatting
	String formatOf(Object member, int format);
	int defaultFormatOf(Object member);
	String fhexOf(Object member);
	String fdecOf(Object member);
	String foctOf(Object member);
	String fbinOf(Object member);
	String fasciiOf(Object member);
}
Open JavaDoc Reference

The next chapter (J21 Iterating samples) shows how to iterate over the sample of multiple signals.

---