J020 Reading samples

Content outdated

We are in the process of migrating all content to impulse version 2.0.

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


Screen Cast: J20 Reading samples


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.


toem

technical software and tooling

Company

Contact Us

This email address is being protected from spambots. You need JavaScript enabled to view it.