Struct DataSet 

pub struct DataSet { /* private fields */ }

Allows to define the NetCDF-3 data sets

Examples

Define a data set

use std::rc::Rc;
use netcdf3::{DataSet, Dimension, DataType, InvalidDataSet};

const LATITUDE_DIM_SIZE: usize = 180;
const LONGITUDE_DIM_SIZE: usize = 360;
const TIME_DIM_SIZE: usize = 24;
const AIR_TEMPERATURE_VAR_LEN: usize = LATITUDE_DIM_SIZE * LONGITUDE_DIM_SIZE * TIME_DIM_SIZE;

// First create the data set
// -------------------------
let mut data_set = DataSet::new();

// Define global attributes
// ------------------------
data_set.add_global_attr_u8("title",        String::from("Air temperature measurements").into_bytes().to_vec()).unwrap();
data_set.add_global_attr_u8("Conventions",  String::from("CF-1.8").into_bytes().to_vec()).unwrap();

// Define dimensions
// -----------------
data_set.add_fixed_dim("latitude",          LATITUDE_DIM_SIZE).unwrap();
data_set.add_fixed_dim("longitude",         LONGITUDE_DIM_SIZE).unwrap();
data_set.set_unlimited_dim("time",          TIME_DIM_SIZE).unwrap();

// Define variables and their attributes
// -------------------------------------
// latitude
data_set.add_var_f32("latitude",            &["latitude"]).unwrap();
data_set.add_var_attr_u8("latitude",        "standard_name", String::from("latitude").into_bytes()).unwrap();
data_set.add_var_attr_u8("latitude",        "long_name", String::from("LATITUDE").into_bytes()).unwrap();
data_set.add_var_attr_u8("latitude",        "units", String::from("degrees_north").into_bytes()).unwrap();
data_set.add_var_attr_u8("latitude",        "axis", String::from("Y").into_bytes()).unwrap();
// longitude
data_set.add_var_f32("longitude",           &["longitude"]).unwrap();
data_set.add_var_attr_u8("longitude",       "standard_name", String::from("longitude").into_bytes()).unwrap();
data_set.add_var_attr_u8("longitude",       "long_name", String::from("LONGITUDE").into_bytes()).unwrap();
data_set.add_var_attr_u8("longitude",       "units", String::from("degrees_east").into_bytes()).unwrap();
data_set.add_var_attr_u8("longitude",       "axis", String::from("X").into_bytes()).unwrap();
// time
data_set.add_var_f32("time",                &["time"]).unwrap();
data_set.add_var_attr_u8("time",            "standard_name", String::from("time").into_bytes()).unwrap();
data_set.add_var_attr_u8("time",            "long_name", String::from("TIME").into_bytes()).unwrap();
data_set.add_var_attr_u8("time",            "units", String::from("hours since 1970-01-01 00:00:00").into_bytes()).unwrap();
data_set.add_var_attr_u8("time",            "calendar", String::from("gregorian").into_bytes()).unwrap();
data_set.add_var_attr_u8("time",            "axis", String::from("T").into_bytes()).unwrap();
// air_temperature
data_set.add_var_f64("air_temperature",     &["time", "latitude", "longitude"]).unwrap();
data_set.add_var_attr_u8("air_temperature", "standard_name", String::from("air_temperature").into_bytes()).unwrap();
data_set.add_var_attr_u8("air_temperature", "long_name", String::from("AIR TEMPERATURE").into_bytes()).unwrap();
data_set.add_var_attr_u8("air_temperature", "units", String::from("Celsius").into_bytes()).unwrap();

Implementations

impl DataSet

pub fn new() -> DataSet

pub fn add_fixed_dim<T: AsRef<str>>( &mut self, dim_name: T, dim_size: usize, ) -> Result<(), InvalidDataSet>

Appends a new fixed size dimension in the dataset.

Returns a error if an other dimension with the same name is already defined.

pub fn set_unlimited_dim<T: AsRef<str>>( &mut self, dim_name: T, dim_size: usize, ) -> Result<(), InvalidDataSet>

Initializes the unlimited size dimension of the dataset.

Returns a error if :

1. the unlimited size is already defined
2. if an other dimension with the same name is already defined

pub fn num_dims(&self) -> usize

Returns the number of dimensions defined in the data set.

pub fn has_dim(&self, dim_name: &str) -> bool

Returns :

• true if the dimension is defined.
• false otherwise.

pub fn get_dim(&self, dim_name: &str) -> Option<Rc<Dimension>>

Returns a reference to the dimension.

Returns None if the dimension is not defined.

pub fn get_dims(&self) -> Vec<Rc<Dimension>>

Returns the references of all the dimensions defined in the data set.

pub fn dim_names(&self) -> Vec<String>

Returns the names all the dimensions defined in the data set.

pub fn has_unlimited_dim(&self) -> bool

Returns true if the unlimited-size dimension exists.

pub fn get_unlimited_dim(&self) -> Option<Rc<Dimension>>

Returns the unlimited-size dimension if it is defined, otherwise return None.

Returns None if the unlimited-size dimension does not exist.

pub fn dim_size(&self, dim_name: &str) -> Option<usize>

Returns the length of the dimension.

Returns None if the dimension does not exist.

pub fn dim_type(&self, dim_name: &str) -> Option<DimensionType>

Returns the type of the dimension (fixed-size or unlimited-size).

Returns None if the dimension does not exist.

pub fn remove_dim( &mut self, dim_name: &str, ) -> Result<Rc<Dimension>, InvalidDataSet>

Removes and returns the dimension.

Returns an error if:

• the dimension is not already defined
• the dimension is yet used by a variable of the dataset

pub fn rename_dim( &mut self, old_dim_name: &str, new_dim_name: &str, ) -> Result<(), InvalidDataSet>

Rename the dimension or return en error if :

• no dimension named old_dim_name already exists
• an other dimension named new_dim_name already exists
• the new_dim_name is not a NetCDF-3 valid name

Nothing is done if old_dim_name and new_dim_name are the same.

pub fn get_dims_from_dim_ids( &self, dim_ids: &[usize], ) -> Result<Vec<Rc<Dimension>>, InvalidDataSet>

pub fn add_var<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], data_type: DataType, ) -> Result<(), InvalidDataSet>

Add a new variable in the dataset defined over named dimensions.

Examples

Add a 2D variable

use netcdf3::{DataSet, DataType};

let mut data_set = DataSet::new();
let _ = data_set.add_fixed_dim("latitude", 181).unwrap();
let _ = data_set.add_fixed_dim("longitude", 361).unwrap();
let _ = data_set.set_unlimited_dim("time", 2).unwrap();

assert_eq!(0, data_set.num_vars());
let _ = data_set.add_var("sea_level_temperature", &["latitude", "longitude"], DataType::F64).unwrap();
assert_eq!(1, data_set.num_vars());

Add a scalar variable

use netcdf3::{DataSet, DataType};

const SCALAR_VAR_NAME: &str = "scalar_var";

let mut data_set = DataSet::new();

assert_eq!(0,                   data_set.num_vars());
assert_eq!(None,                data_set.var_len(SCALAR_VAR_NAME));

let _ = data_set.add_var(SCALAR_VAR_NAME, &[] as &[&str] /* no dimensions*/, DataType::I32).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(Some(1),             data_set.var_len(SCALAR_VAR_NAME));

pub fn add_var_i8<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], ) -> Result<(), InvalidDataSet>

Add a new i8 type variable defined over named dimensions (see the add_var method).

pub fn add_var_u8<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], ) -> Result<(), InvalidDataSet>

Add a new u8 type variable defined over named dimensions (see the add_var method).

pub fn add_var_i16<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], ) -> Result<(), InvalidDataSet>

Add a new i16 type variable defined over named dimensions (see the add_var method).

pub fn add_var_i32<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], ) -> Result<(), InvalidDataSet>

Add a new i32 type variable defined over named dimensions (see the add_var method).

pub fn add_var_f32<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], ) -> Result<(), InvalidDataSet>

Add a new f32 type variable defined over named dimensions (see the add_var method).

pub fn add_var_f64<T: AsRef<str>>( &mut self, var_name: &str, dims_name: &[T], ) -> Result<(), InvalidDataSet>

Add a new f64 type variable defined over named dimensions (see the add_var method).

pub fn num_vars(&self) -> usize

Returns the number of defined variables.

pub fn has_var(&self, var_name: &str) -> bool

Returns :

• true if the variable is defined.
• false otherwise.

pub fn is_record_var(&self, var_name: &str) -> Option<bool>

pub fn var_len(&self, var_name: &str) -> Option<usize>

Returns the length (total number of elements) of the variable.

pub fn var_data_type(&self, var_name: &str) -> Option<DataType>

Returns the data type of the variable, or None.

pub fn get_var(&self, var_name: &str) -> Option<&Variable>

Returns a reference to the variable, or None.

pub fn get_var_mut(&mut self, var_name: &str) -> Option<&mut Variable>

Returns a mutable reference to the variable

pub fn get_vars(&self) -> Vec<&Variable>

Returns the references all the variables defined in the dataset.

pub fn get_var_names(&self) -> Vec<String>

Returns the names all the variables defined in the dataset.

pub fn rename_var( &mut self, old_var_name: &str, new_var_name: &str, ) -> Result<(), InvalidDataSet>

Renames a variable.

Nothing is do if old_var_name and new_var_name the same.

Returns an error if :

• no variable old_var_name exists
• an other variable new_var_name already exists
• new_var_name is a NetCDF-3 valid name

pub fn remove_var(&mut self, var_name: &str) -> Result<Variable, InvalidDataSet>

Remove the variable.

pub fn add_var_attr_i8( &mut self, var_name: &str, attr_name: &str, var_attr_value: Vec<i8>, ) -> Result<(), InvalidDataSet>

pub fn add_var_attr_u8( &mut self, var_name: &str, attr_name: &str, var_attr_value: Vec<u8>, ) -> Result<(), InvalidDataSet>

pub fn add_var_attr_string<T: AsRef<str>>( &mut self, var_name: &str, attr_name: &str, var_attr_value: T, ) -> Result<(), InvalidDataSet>

pub fn add_var_attr_i16( &mut self, var_name: &str, attr_name: &str, var_attr_value: Vec<i16>, ) -> Result<(), InvalidDataSet>

pub fn add_var_attr_i32( &mut self, var_name: &str, attr_name: &str, var_attr_value: Vec<i32>, ) -> Result<(), InvalidDataSet>

pub fn add_var_attr_f32( &mut self, var_name: &str, attr_name: &str, var_attr_value: Vec<f32>, ) -> Result<(), InvalidDataSet>

pub fn add_var_attr_f64( &mut self, var_name: &str, attr_name: &str, var_attr_value: Vec<f64>, ) -> Result<(), InvalidDataSet>

pub fn get_var_attr( &self, var_name: &str, attr_name: &str, ) -> Option<&Attribute>

Returns a reference of variable attribute.

pub fn get_var_attr_len(&self, var_name: &str, attr_name: &str) -> Option<usize>

Returns the length (number of elements) of the variable attribute.

pub fn get_var_attr_data_type( &self, var_name: &str, attr_name: &str, ) -> Option<DataType>

Returns the data type of the variable attribute.

pub fn get_var_attrs(&self, var_name: &str) -> Option<Vec<&Attribute>>

Returns all attributes of a variable.

Returns None if the variable is not defined.

pub fn has_var_attr(&self, var_name: &str, attr_name: &str) -> Option<bool>

Returns :

• true if the variable attribute is defined.
• false otherwise.

pub fn num_var_attrs(&self, var_name: &str) -> Option<usize>

Returns the number of attributes of the variable.

Returns None if the variable does not exist.

pub fn rename_var_attr( &mut self, var_name: &str, old_attr_name: &str, new_attr_name: &str, ) -> Result<(), InvalidDataSet>

Rename the variable attribute.

pub fn remove_var_attr( &mut self, var_name: &str, attr_name: &str, ) -> Result<Attribute, InvalidDataSet>

Remove the attribute from the variable.

pub fn get_var_attr_i8(&self, var_name: &str, attr_name: &str) -> Option<&[i8]>

Returns the attribute value as a &[i8].

Also see the method Attribute::get_i8.

pub fn get_var_attr_u8(&self, var_name: &str, attr_name: &str) -> Option<&[u8]>

Returns the attribute value as a &[u8].

Also see the method Attribute::get_u8.8))

pub fn get_var_attr_as_string( &self, var_name: &str, attr_name: &str, ) -> Option<String>

Returns the attribute value as a String.

Also see the method Attribute::get_as_string

pub fn get_var_attr_i16( &self, var_name: &str, attr_name: &str, ) -> Option<&[i16]>

Returns the attribute value as a &[i16].

Also see the method Attribute::get_i16.

pub fn get_var_attr_i32( &self, var_name: &str, attr_name: &str, ) -> Option<&[i32]>

Returns the attribute value as a &[i32].

Also see the method Attribute::get_i32.

pub fn get_var_attr_f32( &self, var_name: &str, attr_name: &str, ) -> Option<&[f32]>

Returns the attribute value as a &[f32].

Also see the method Attribute::get_f32.

pub fn get_var_attr_f64( &self, var_name: &str, attr_name: &str, ) -> Option<&[f64]>

Returns the attribute value as a &[f64].

Also see the method Attribute::get_f64(struct.Attribute.html#method.get_f64

pub fn get_global_attr(&self, attr_name: &str) -> Option<&Attribute>

Returns a reference to the global attribute.

pub fn get_global_attrs(&self) -> Vec<&Attribute>

Returns a reference of all global attributes.

pub fn get_global_attr_len(&self, attr_name: &str) -> Option<usize>

Returns the length (number of elements) of the global attribute.

pub fn get_global_attr_data_type(&self, attr_name: &str) -> Option<DataType>

Returns the data type of the global attribute.

pub fn num_global_attrs(&self) -> usize

Returns the number of global attributes.

pub fn has_global_attr(&self, attr_name: &str) -> bool

Returns :

• true if the global attribute is defined.
• false otherwise.

pub fn get_global_attr_names(&self) -> Vec<String>

Returns the number of global attributes.

pub fn add_global_attr_i8( &mut self, attr_name: &str, attr_data: Vec<i8>, ) -> Result<(), InvalidDataSet>

Adds a global i8 type attribute in the data set.

pub fn add_global_attr_u8( &mut self, attr_name: &str, attr_data: Vec<u8>, ) -> Result<(), InvalidDataSet>

Adds a global u8 type attribute in the data set.

pub fn add_global_attr_string<T: AsRef<str>>( &mut self, attr_name: &str, attr_data: T, ) -> Result<(), InvalidDataSet>

Adds a global u8 type attribute in the data set.

pub fn add_global_attr_i16( &mut self, attr_name: &str, attr_data: Vec<i16>, ) -> Result<(), InvalidDataSet>

Adds a global i16 type attribute in the data set.

pub fn add_global_attr_i32( &mut self, attr_name: &str, attr_data: Vec<i32>, ) -> Result<(), InvalidDataSet>

Adds a global i32 type attribute in the data set.

pub fn add_global_attr_f32( &mut self, attr_name: &str, attr_data: Vec<f32>, ) -> Result<(), InvalidDataSet>

Adds a global f32 type attribute in the data set.

pub fn add_global_attr_f64( &mut self, attr_name: &str, attr_data: Vec<f64>, ) -> Result<(), InvalidDataSet>

Add a global f64 type attribute in the data set.

pub fn rename_global_attr( &mut self, old_attr_name: &str, new_attr_name: &str, ) -> Result<(), InvalidDataSet>

pub fn remove_global_attr( &mut self, attr_name: &str, ) -> Result<Attribute, InvalidDataSet>

pub fn get_global_attr_i8(&self, attr_name: &str) -> Option<&[i8]>

Returns the attribute value as a &[i8].

Also see the method Attribute::get_i8.

pub fn get_global_attr_u8(&self, attr_name: &str) -> Option<&[u8]>

Returns the attribute value as a &[u8].

Also see the method Attribute::get_u8.

pub fn get_global_attr_as_string(&self, attr_name: &str) -> Option<String>

Returns the global attribute value as a String.

Also see the method Attribute::get_as_string

pub fn get_global_attr_i16(&self, attr_name: &str) -> Option<&[i16]>

Returns the attribute value as a &[i16].

Also see the method Attribute::get_i16(struct.Attribute.html#method.get_i16

pub fn get_global_attr_i32(&self, attr_name: &str) -> Option<&[i32]>

Returns the attribute value as a &[i32].

Also see the method Attribute::get_i32.

pub fn get_global_attr_f32(&self, attr_name: &str) -> Option<&[f32]>

Returns the attribute value as a &[f32].

Also see the method Attribute::get_f32.)

pub fn get_global_attr_f64(&self, attr_name: &str) -> Option<&[f64]>

Returns the attribute value as a &[f64].

Also see the method Attribute::get_f64

pub fn record_size(&self) -> Option<usize>

Returns the size (number of bytes) required by each record stored in the data file.

Returns None if the data set has not a unlimited-size dimension.

Example

use netcdf3::{DataSet, Variable};
const UNLIM_DIM_NAME: &str = "unlim_dim";
const UNLIM_DIM_SIZE: usize = 10;

const FIXED_DIM_NAME: &str = "fixed_dim";
const FIXED_DIM_SIZE: usize = 20;

const VAR_1D_NAME: &str = "var_1D";
const VAR_2D_NAME: &str = "var_2D";

// No *unlimited-size* dimension is defined
let mut data_set: DataSet = DataSet::new();
assert_eq!(false,   data_set.has_unlimited_dim());
assert_eq!(None,    data_set.record_size());

// The *unlimited-size* dimension is defined here, but no variable uses it
data_set.set_unlimited_dim(UNLIM_DIM_NAME, UNLIM_DIM_SIZE).unwrap();
assert_eq!(true,                                            data_set.has_unlimited_dim());
assert_eq!(Some(0),                                         data_set.record_size());

// First : Add a 1D variable (a vector) over the *unlimited-size* dimension
data_set.add_var_i8(VAR_1D_NAME, &[UNLIM_DIM_NAME]).unwrap();
const VAR_1D_CHUNK_SIZE: usize = 4;  // 1 useful byte + 3 zero-padding bytes
assert_eq!(true,                                            data_set.has_unlimited_dim());
assert_eq!(Some(VAR_1D_CHUNK_SIZE),                         data_set.record_size());

// Second : Add a 2D variable (a matrix) over the* unlimited-size* dimension
data_set.add_fixed_dim(FIXED_DIM_NAME, FIXED_DIM_SIZE).unwrap();
data_set.add_var_i8(VAR_2D_NAME, &[UNLIM_DIM_NAME, FIXED_DIM_NAME]).unwrap();
const VAR_2D_CHUNK_SIZE: usize = 20;  // 20 bytes

// Then: the record size has increased
assert_eq!(true,                                            data_set.has_unlimited_dim());
assert_eq!(Some(VAR_1D_CHUNK_SIZE + VAR_2D_CHUNK_SIZE),     data_set.record_size());

pub fn num_records(&self) -> Option<usize>

Returns the number of records stored in data file.

Returns None if the data set has not an unlimited-size dimension.

Example

use netcdf3::DataSet;
const UNLIM_DIM_NAME: &str = "unlim_dim";
const UNLIM_DIM_SIZE: usize = 10;

let mut data_set: DataSet = DataSet::new();

// No *unlimited-size* dimension is defined
assert_eq!(false,   data_set.has_unlimited_dim());
assert_eq!(None,    data_set.num_records());

// The *unlimited-size* dimension is defined here
data_set.set_unlimited_dim(UNLIM_DIM_NAME, UNLIM_DIM_SIZE);
assert_eq!(true,                    data_set.has_unlimited_dim());
assert_eq!(Some(UNLIM_DIM_SIZE),    data_set.num_records());

Trait Implementations

impl Debug for DataSet

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for DataSet

fn eq(&self, other: &DataSet) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for DataSet