ucar.nc2

Class Structure

java.lang.Object

ucar.nc2.Variable

ucar.nc2.Structure

All Implemented Interfaces:

Comparable<VariableSimpleIF>, ProxyReader, VariableSimpleIF

Direct Known Subclasses:

Sequence, StructureDS

@Immutable
public class Structure
extends Variable

A Structure is a type of Variable that contains other Variables, like a struct in C. A Structure can be scalar or multidimensional.

A call to structure.read() will read all of the data in a Structure, including nested structures, and returns an Array of StructureData, with all of the data in memory. If there is a nested sequence, the sequence data may be read into memory all at once, or it may be read in increments as the iteration proceeds.

Generally, the programmer can assume that the data in one Structure are stored together, so that it is efficient to read an entire Structure, and then access the Variable data through the Arrays in the StructureData.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Structure.Builder<T extends Structure.Builder<T>>

Nested classes/interfaces inherited from class ucar.nc2.Variable

Variable.Cache

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	isSubset
protected com.google.common.collect.ImmutableList<Variable>	members

Fields inherited from class ucar.nc2.Variable

attributes, cache, dataType, dimensions, elementSize, hashCode, isVariableLength, ncfile, permitCaching, proxyReader, shape, spiObject

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Structure(Structure.Builder<?> builder, Group parentGroup)

Method Summary

Modifier and Type	Method and Description
protected Structure.Builder<?>	addLocalFieldsToBuilder(Structure.Builder<? extends Structure.Builder<?>> b)
static Structure.Builder<?>	builder() Get Builder for this class that allows subclassing.
Variable	findVariable(String shortName) Find the Variable member with the specified (short) name, or null if not found.
int	getElementSize() Get the size in bytes of one Structure.
String	getNameAndAttributes() Get String with name and attributes.
int	getNumberOfMemberVariables() Get the number of variables contained directly in this Structure.
StructureDataIterator	getStructureIterator() Deprecated. use readArray().iterator()
StructureDataIterator	getStructureIterator(int bufferSize) Deprecated. use readArray().iterator()
com.google.common.collect.ImmutableList<String>	getVariableNames() Get the (short) names of the variables contained directly in this Structure.
com.google.common.collect.ImmutableList<Variable>	getVariables() Get the variables contained directly in this Structure.
boolean	isSubset() Find if this was created from a subset() method.
StructureMembers	makeStructureMembers() Deprecated. use makeStructureMembersBuilder()
StructureMembers.Builder	makeStructureMembersBuilder()
StructureData	readStructure(int index) Deprecated. use readArray(Section)
ArrayStructure	readStructure(int start, int count) Deprecated. use readArray(Section)
Structure	select(List<String> memberNames) Create a subset of the Structure consisting only of the given member variables
Structure	select(String varName) Create a subset of the Structure consisting only of the one member variable
Structure.Builder<?>	toBuilder() Turn into a mutable Builder.
protected void	writeCDL(Formatter buf, Indent indent, boolean useFullName, boolean strict)

Methods inherited from class ucar.nc2.Variable

_read, _read, _readScalarData, addLocalFieldsToBuilder, attributes, compareTo, equals, extraInfo, findAttribute, findAttributeString, findDimensionIndex, getArrayType, getDatasetLocation, getDataType, getDescription, getDimension, getDimensions, getDimensionSet, getDimensionsString, getEnumTypedef, getFileTypeId, getFullName, getNameAndDimensions, getNameAndDimensions, getNetcdfFile, getParentGroup, getParentStructure, getRanges, getRank, getSection, getShape, getShape, getShapeAsSection, getShortName, getSize, getSizeToCache, getSPobject, getUnitsString, hasCachedData, hashCode, invalidateCache, isCaching, isCoordinateVariable, isMemberOfStructure, isMetadata, isScalar, isUnlimited, isVariableLength, lookupEnumString, proxyReadArray, proxyReadArray, read, read, read, read, read, readArray, readArray, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, readToStream, reallyRead, reallyRead, reduce, resetShape, section, section, setCachedData, setCaching, slice, toString, toStringDebug

Methods inherited from class java.lang.Object

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

Field Detail

members

protected final com.google.common.collect.ImmutableList<Variable> members

isSubset

protected final boolean isSubset

Constructor Detail

Structure

protected Structure(Structure.Builder<?> builder,
                    Group parentGroup)

Method Detail

findVariable

@Nullable
public Variable findVariable(String shortName)

Find the Variable member with the specified (short) name, or null if not found.

getNumberOfMemberVariables

public int getNumberOfMemberVariables()

Get the number of variables contained directly in this Structure.

getElementSize

public int getElementSize()

Get the size in bytes of one Structure.

Overrides:

getElementSize in class Variable

Returns:

total number of bytes for the Variable

getVariables

public com.google.common.collect.ImmutableList<Variable> getVariables()

Get the variables contained directly in this Structure.

getVariableNames

public com.google.common.collect.ImmutableList<String> getVariableNames()

Get the (short) names of the variables contained directly in this Structure.

isSubset

public boolean isSubset()

Find if this was created from a subset() method.

makeStructureMembers

@Deprecated
public StructureMembers makeStructureMembers()

Deprecated. use makeStructureMembersBuilder()

Create a StructureMembers object that describes this Structure. CAUTION: Do not use for iterating over a StructureData or ArrayStructure - get the StructureMembers object directly from the StructureData or ArrayStructure.

Returns:

a StructureMembers object that describes this Structure.

makeStructureMembersBuilder

public StructureMembers.Builder makeStructureMembersBuilder()

select

public Structure select(List<String> memberNames)

Create a subset of the Structure consisting only of the given member variables

Parameters:

memberNames - list of Variable names, already a member

Returns:

Structure containing just those members

select

public Structure select(String varName)

Create a subset of the Structure consisting only of the one member variable

Parameters:

varName - name of member Variable

Returns:

containing just that member

readStructure

@Deprecated
public StructureData readStructure(int index)
                                         throws IOException,
                                                InvalidRangeException

Deprecated. use readArray(Section)

Use this when this is a scalar or one dimensional array of Structures, or you are doing the index calculation yourself for a multidimensional array. This will read only the ith structure, and return a StructureData.

Parameters:

index - linear index into the array

Returns:

ith StructureData

Throws:

IOException - on read error

InvalidRangeException - if index out of range

readStructure

@Deprecated
public ArrayStructure readStructure(int start,
                                                 int count)
                                          throws IOException,
                                                 InvalidRangeException

Deprecated. use readArray(Section)

For rank 0 or 1 array of Structures, read count Structures and return the data as an ArrayStructure. Use only when this is a one dimensional array of Structures.

Parameters:

start - start at this index

count - return this many StructureData

Returns:

the StructureData recordsfrom start to start+count-1

Throws:

IOException - on read error

InvalidRangeException - if start, count out of range

getStructureIterator

@Deprecated
public StructureDataIterator getStructureIterator()
                                                        throws IOException

Deprecated. use readArray().iterator()

Iterator over all the data in a Structure.

 StructureDataIterator ii = structVariable.getStructureIterator();
 while (ii.hasNext()) {
   StructureData sdata = ii.next();
 }
 

Returns:

StructureDataIterator over type StructureData

Throws:

IOException - on read error

See Also:

getStructureIterator(int bufferSize)

getStructureIterator

@Deprecated
public StructureDataIterator getStructureIterator(int bufferSize)
                                                        throws IOException

Deprecated. use readArray().iterator()

Get an efficient iterator over all the data in the Structure. This is the efficient way to get all the data, it can be much faster than reading one record at a time, and is optimized for large datasets. This is accomplished by buffering bufferSize amount of data at once.

 Example:

  StructureDataIterator ii = structVariable.getStructureIterator(100 * 1000);
  while (ii.hasNext()) {
    StructureData sdata = ii.next();
  }
 

Parameters:

bufferSize - size in bytes to buffer, set < 0 to use default size

Returns:

StructureDataIterator over type StructureData

Throws:

IOException - on read error

getNameAndAttributes

public String getNameAndAttributes()

Get String with name and attributes. Used in short descriptions like tooltips.

writeCDL

protected void writeCDL(Formatter buf,
                        Indent indent,
                        boolean useFullName,
                        boolean strict)

Overrides:

writeCDL in class Variable

toBuilder

public Structure.Builder<?> toBuilder()

Turn into a mutable Builder. Can use toBuilder().build() to copy.

Overrides:

toBuilder in class Variable

addLocalFieldsToBuilder

protected Structure.Builder<?> addLocalFieldsToBuilder(Structure.Builder<? extends Structure.Builder<?>> b)

builder

public static Structure.Builder<?> builder()

Get Builder for this class that allows subclassing.

See Also:

"https://community.oracle.com/blogs/emcmanus/2010/10/24/using-builder-pattern-subclasses"