Struct netcdf3::DataSet

pub struct DataSet { /* fields omitted */ }

NetCDF-3 data set

Examples

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

// Initialize the data vectors
// ---------------------------
let latitude_data: Vec<f32>         = (0..LATITUDE_DIM_SIZE).map(|x| x as f32).collect();
let longitude_data: Vec<f32>        = (0..LONGITUDE_DIM_SIZE).map(|x| x as f32).collect();
let time_data: Vec<f32>             = (438_300..(438_300 + TIME_DIM_SIZE)).map(|x| x as f32).collect(); // 2020, the 1st-january
let air_temperature_data: Vec<f64>  = (0..AIR_TEMPERATURE_VAR_LEN).map(|x| x as f64).collect();
 
// Set data in each variable
// -------------------------
data_set.set_var_f32("latitude",        latitude_data.clone()).unwrap();
data_set.set_var_f32("longitude",       longitude_data.clone()).unwrap();
data_set.set_var_f32("time",            time_data.clone()).unwrap();
data_set.set_var_f64("air_temperature", air_temperature_data.clone()).unwrap();

// Retrieve the `air_temperature` data from the data set
//------------------------------------------------------
assert_eq!(None,                                    data_set.get_var_i8("air_temperature"));
assert_eq!(None,                                    data_set.get_var_u8("air_temperature"));
assert_eq!(None,                                    data_set.get_var_i16("air_temperature"));
assert_eq!(None,                                    data_set.get_var_i32("air_temperature"));
assert_eq!(None,                                    data_set.get_var_f32("air_temperature"));
assert_eq!(Some(air_temperature_data.as_slice()),   data_set.get_var_f64("air_temperature"));

Methods

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 get_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 get_dim_size(&self, dim_name: &str) -> Option<usize>

Returns the length of the dimension.

Returns None if the dimension does not exist.

pub fn get_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_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 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 an empty variable

use netcdf3::{DataSet, DataType};

let mut data_set = DataSet::new();

assert_eq!(0, data_set.num_vars());
let _ = data_set.add_var("empty_variable", &[] as &[&str] /* no dimensions*/, DataType::U8).unwrap();
assert_eq!(1, data_set.num_vars());

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 get_var(&self, var_name: &str) -> Option<&Variable>

Returns a reference to the variable, or None.

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

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

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

Returns the data type of 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 get_var_i8(&self, var_name: &str) -> Option<&[i8]>

Returns the i8 values from the variable (see the method)

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

Returns the u8 values from the variable (see the method)

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

Returns the i16 values from the variable (see the method)

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

Returns the i32 values from the variable (see the method)

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

Returns the f32 values from the variable (see the method)

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

Returns the f64 values from the variable (see the method)

pub fn set_var_i8(
    &mut self,
    var_name: &str,
    data: Vec<i8>
) -> Result<(), InvalidDataSet>

Set i8 data into the variable. (see the method )

pub fn set_var_u8(
    &mut self,
    var_name: &str,
    data: Vec<u8>
) -> Result<(), InvalidDataSet>

Set u8 data into the variable. (see the method )

pub fn set_var_i16(
    &mut self,
    var_name: &str,
    data: Vec<i16>
) -> Result<(), InvalidDataSet>

Set i16 data into the variable. (see the method )

pub fn set_var_i32(
    &mut self,
    var_name: &str,
    data: Vec<i32>
) -> Result<(), InvalidDataSet>

Set i32 data into the variable. (see the method )

pub fn set_var_f32(
    &mut self,
    var_name: &str,
    data: Vec<f32>
) -> Result<(), InvalidDataSet>

Set f32 data into the variable. (see the method )

pub fn set_var_f64(
    &mut self,
    var_name: &str,
    data: Vec<f64>
) -> Result<(), InvalidDataSet>

Set f64 data into the variable. (see the method )

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_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 has_var_attr_len(&self, var_name: &str, attr_name: &str) -> Option<usize>

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

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

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

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(
    &mut self,
    var_name: &str,
    attr_name: &str
) -> Option<&[i8]>

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

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

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

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

pub fn get_var_attr_f64(
    &mut self,
    var_name: &str,
    attr_name: &str
) -> Option<&[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_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 i8 values the a global attribute (see the method)

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

Returns the u8 values the a global attribute (see the method)

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

Returns the i16 values the a global attribute (see the method)

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

Returns the i32 values the a global attribute (see the method)

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

Returns the f32 values the a global attribute (see the method)

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

Returns the f64 values the a global attribute (see the method)

pub fn num_bytes_per_record(&self) -> usize

pub fn num_records(&self) -> usize

Trait Implementations

impl Debug for DataSet

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

Formats the value using the given formatter.

impl PartialEq<DataSet> for DataSet

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralPartialEq for DataSet