ucar.nc2

Class Sequence

java.lang.Object

ucar.nc2.CDMNode

ucar.nc2.Variable

ucar.nc2.Structure

ucar.nc2.Sequence

All Implemented Interfaces:

Comparable<VariableSimpleIF>, Iterable<Attribute>, AttributeContainer, ProxyReader, VariableSimpleIF

public class Sequence
extends Structure

Sequence is a one-dimensional Structure with indeterminate length. The only data access is through getStructureIterator(). However, read() will read in the entire data and return an in-memory ArraySequence.

Since:

Feb 23, 2008

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Sequence.Builder<T extends Sequence.Builder<T>> A builder of Sequences

Field Summary

Fields inherited from class ucar.nc2.Variable

defaultCoordsSizeToCache, defaultSizeToCache, permitCaching

Constructor Summary

Constructors

Constructor and Description
Sequence(NetcdfFile ncfile, Group group, Structure parent, String shortName) Deprecated. use Builder.

Method Summary

Modifier and Type	Method and Description
static Sequence.Builder<?>	builder() Get Builder for this class that allows subclassing.
StructureDataIterator	getStructureIterator(int bufferSize) Get an efficient iterator over all the data in the Structure.
Array	read(int[] origin, int[] shape) Read a section of the data for this Variable and return a memory resident Array.
Array	read(List<Range> ranges) Read a section of the data for this Variable from the netcdf file and return a memory resident Array.
Array	read(Section section) Read a section of the data for this Variable from the netcdf file and return a memory resident Array.
Array	read(String sectionSpec) Read data section specified by a "section selector", and return a memory resident Array.
StructureData	readStructure() Use this when this is a scalar Structure.
StructureData	readStructure(int index) Use this when this is a one dimensional array of Structures, or you are doing the index calculation yourself for a multidimension array.
ArrayStructure	readStructure(int start, int count) For rank 1 array of Structures, read count Structures and return the data as an ArrayStructure.
Variable	section(Section subsection) Create a new Variable that is a logical subsection of this Variable.
Variable	slice(int dim, int value) Create a new Variable that is a logical slice of this Variable, by fixing the specified dimension at the specified index value.
Sequence.Builder<?>	toBuilder() Turn into a mutable Builder.

Methods inherited from class ucar.nc2.Structure

addMemberVariable, calcElementSize, findVariable, getElementSize, getNameAndAttributes, getNumberOfMemberVariables, getStructureIterator, getVariableNames, getVariables, isCaching, isSubset, makeStructureMembers, removeMemberVariable, replaceMemberVariable, select, select, setCaching, setImmutable, setMemberVariables, setParentGroup

Methods inherited from class ucar.nc2.Variable

addAll, addAttribute, attributes, compareTo, createNewCache, equals, findAttribute, findAttributeDouble, findAttributeIgnoreCase, findAttributeInteger, findAttValueIgnoreCase, findDimensionIndex, getAttributes, getDAPName, getDAPName, getDatasetLocation, getDataType, getDescription, getDimension, getDimensions, getDimensionsAll, getDimensionsString, getEnumTypedef, getFileTypeId, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNameAndDimensions, getNetcdfFile, getParentGroup, getProxyReader, getRanges, getRank, getShape, getShape, getShapeAll, getShapeAsSection, getSize, getSizeToCache, getSPobject, getUnitsString, hasCachedData, hashCode, invalidateCache, isCoordinateVariable, isImmutable, isMetadata, isScalar, isUnknownLength, isUnlimited, isVariableLength, lookupEnumString, read, readScalarByte, readScalarDouble, readScalarFloat, readScalarInt, readScalarLong, readScalarShort, readScalarString, readToByteChannel, readToStream, reallyRead, reallyRead, reduce, remove, removeAttribute, removeAttributeIgnoreCase, resetDimensions, resetShape, section, setCachedData, setCachedData, setDataType, setDimension, setDimensions, setDimensions, setDimensionsAnonymous, setElementSize, setEnumTypedef, setIsScalar, setName, setProxyReader, setSizeToCache, setSPobject, setValues, setValues, toString, toStringDebug, writeCDL

Methods inherited from class ucar.nc2.CDMNode

annotate, annotation, getDODSName, getFullName, getFullNameEscaped, getGroup, getImmutable, getName, getParentStructure, getShortName, getSort, isMemberOfStructure, localhash, setDODSName, setParentStructure, setShortName, setSort, unwrap

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface ucar.nc2.VariableSimpleIF

getFullName, getName, getShortName

Methods inherited from interface ucar.nc2.AttributeContainer

getName, hasAttribute, iterator

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

Sequence

@Deprecated
public Sequence(NetcdfFile ncfile,
                            Group group,
                            Structure parent,
                            String shortName)

Deprecated. use Builder.

Sequence Constructor

Parameters:

ncfile - the containing NetcdfFile.

group - the containing group; if null, use rootGroup

parent - parent Structure, may be null

shortName - variable shortName, must be unique within the Group

Method Detail

getStructureIterator

public StructureDataIterator getStructureIterator(int bufferSize)
                                           throws IOException

Description copied from class: Structure

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();
  }
 

Overrides:

getStructureIterator in class Structure

Parameters:

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

Returns:

StructureDataIterator over type StructureData

Throws:

IOException - on read error

read

public Array read(int[] origin,
                  int[] shape)

Description copied from class: Variable

Read a section of the data for this Variable and return a memory resident Array. The Array has the same element type as the Variable, and the requested shape. Note that this does not do rank reduction, so the returned Array has the same rank as the Variable. Use Array.reduce() for rank reduction.

assert(origin[ii] + shape[ii]*stride[ii] <= Variable.shape[ii]);

Overrides:

read in class Variable

Parameters:

origin - int array specifying the starting index. If null, assume all zeroes.

shape - int array specifying the extents in each dimension. This becomes the shape of the returned Array.

Returns:

the requested data in a memory-resident Array

Throws:

UnsupportedOperationException - always

read

public Array read(String sectionSpec)

Description copied from class: Variable

Read data section specified by a "section selector", and return a memory resident Array. Uses Fortran 90 array section syntax.

Overrides:

read in class Variable

Parameters:

sectionSpec - specification string, eg "1:2,10,:,1:100:10". May optionally have ().

Returns:

the requested data in a memory-resident Array

Throws:

UnsupportedOperationException - always

See Also:

for sectionSpec syntax

read

public Array read(List<Range> ranges)

Description copied from class: Variable

Read a section of the data for this Variable from the netcdf file and return a memory resident Array.

Overrides:

read in class Variable

Parameters:

ranges - list of Range specifying the section of data to read.

Returns:

the requested data in a memory-resident Array

Throws:

UnsupportedOperationException - always

See Also:

Variable.read(Section)

read

public Array read(Section section)
           throws IOException

Description copied from class: Variable

Read a section of the data for this Variable from the netcdf file and return a memory resident Array. The Array has the same element type as the Variable, and the requested shape. Note that this does not do rank reduction, so the returned Array has the same rank as the Variable. Use Array.reduce() for rank reduction.

If the Variable is a member of an array of Structures, this returns only the variable's data in the first Structure, so that the Array shape is the same as the Variable. To read the data in all structures, use ncfile.readSectionSpec().

Note this only allows you to specify a subset of this variable. If the variable is nested in a array of structures and you want to subset that, use NetcdfFile.read(String sectionSpec, boolean flatten);

Overrides:

read in class Variable

Parameters:

section - list of Range specifying the section of data to read. Must be null or same rank as variable. If list is null, assume all data. Each Range corresponds to a Dimension. If the Range object is null, it means use the entire dimension.

Returns:

the requested data in a memory-resident Array

Throws:

IOException - if error

readStructure

public StructureData readStructure()

Description copied from class: Structure

Use this when this is a scalar Structure. Its the same as read(), but it extracts the single StructureData out of the Array.

Overrides:

readStructure in class Structure

Returns:

StructureData for a scalar

Throws:

UnsupportedOperationException - always

readStructure

public StructureData readStructure(int index)

Description copied from class: Structure

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

Overrides:

readStructure in class Structure

Parameters:

index - index into 1D array

Returns:

ith StructureData

Throws:

UnsupportedOperationException - always

readStructure

public ArrayStructure readStructure(int start,
                                    int count)

Description copied from class: Structure

For rank 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.

Overrides:

readStructure in class Structure

Parameters:

start - start at this index

count - return this many StructureData

Returns:

the StructureData recordsfrom start to start+count-1

Throws:

UnsupportedOperationException - always

slice

public Variable slice(int dim,
                      int value)

Description copied from class: Variable

Create a new Variable that is a logical slice of this Variable, by fixing the specified dimension at the specified index value. This reduces rank by 1. No data is read until a read method is called on it.

Overrides:

slice in class Variable

Parameters:

dim - which dimension to fix

value - at what index value

Returns:

a new Variable which is a logical slice of this Variable.

Throws:

UnsupportedOperationException - always

section

public Variable section(Section subsection)

Description copied from class: Variable

Create a new Variable that is a logical subsection of this Variable. No data is read until a read method is called on it.

Overrides:

section in class Variable

Parameters:

subsection - Section of this variable. Each Range in the section corresponds to a Dimension, and specifies the section of data to read in that Dimension. A Range object may be null, which means use the entire dimension.

Returns:

a new Variable which is a logical section of this Variable.

Throws:

UnsupportedOperationException - always

toBuilder

public Sequence.Builder<?> toBuilder()

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

Overrides:

toBuilder in class Structure

builder

public static Sequence.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"