Struct netcdf3::Variable

pub struct Variable { /* fields omitted */ }

NetCDF-3 variable

Variable instances are managed by a DataSet.

DataSets allow to create, read, remove and rename Variables.

Examples

Create a variable

use netcdf3::{DataSet, Variable, DataType, DimensionType};

const VAR_NAME: &str = "var_1";
const DIM_NAME_1: &str = "dim_1";
const DIM_NAME_2: &str = "dim_2";
const DIM_SIZE_1: usize = 2;
const DIM_SIZE_2: usize = 3;
const DATA_F32: &'static [f32; 6] = &[0.0, 1.0, 2.0, 3.0, 4.0, 5.0];
const DATA_F32_LEN: usize = DATA_F32.len();

assert_eq!(DATA_F32_LEN, DIM_SIZE_1 * DIM_SIZE_2);

// Create a data set
let mut data_set: DataSet = DataSet::new();
// Define 2 dimensions
data_set.set_unlimited_dim(DIM_NAME_1, DIM_SIZE_1).unwrap();
data_set.add_fixed_dim(DIM_NAME_2, DIM_SIZE_2).unwrap();
// Define a `f32` variable
data_set.add_var_f32(VAR_NAME, &[DIM_NAME_1, DIM_NAME_2]).unwrap();
// Set a data vector
data_set.set_var_f32(VAR_NAME, DATA_F32.to_vec()).unwrap();

// Get values stored in the file header
assert_eq!(1,                                   data_set.num_vars());
assert_eq!(2,                                   data_set.num_dims());
assert_eq!(Some(DIM_SIZE_1),                    data_set.get_dim_size(DIM_NAME_1));
assert_eq!(true,                                data_set.has_unlimited_dim());
assert_eq!(true,                                data_set.has_dim(DIM_NAME_1));
assert_eq!(Some(DimensionType::UnlimitedSize),  data_set.get_dim_type(DIM_NAME_1));
assert_eq!(true,                                data_set.has_dim(DIM_NAME_2));
assert_eq!(Some(DIM_SIZE_2),                    data_set.get_dim_size(DIM_NAME_2));
assert_eq!(Some(DimensionType::FixedSize),      data_set.get_dim_type(DIM_NAME_2));
assert_eq!(true,                                data_set.has_var(VAR_NAME));
assert_eq!(Some(0),                             data_set.num_var_attrs(VAR_NAME));
assert_eq!(Some(DATA_F32_LEN),                  data_set.get_var_len(VAR_NAME));
assert_eq!(Some(DataType::F32),                 data_set.get_var_data_type(VAR_NAME));

// Get `f32` data thought the data set
assert_eq!(None,                data_set.get_var_i8(VAR_NAME));
assert_eq!(None,                data_set.get_var_u8(VAR_NAME));
assert_eq!(None,                data_set.get_var_i16(VAR_NAME));
assert_eq!(None,                data_set.get_var_i32(VAR_NAME));
assert_eq!(Some(&DATA_F32[..]), data_set.get_var_f32(VAR_NAME));
assert_eq!(None,                data_set.get_var_f64(VAR_NAME));
 
// Or through a reference to the variable
let var: &Variable = data_set.get_var(VAR_NAME).unwrap();
assert_eq!(VAR_NAME,                        var.name());
assert_eq!(true,                            var.is_record_var());
assert_eq!(2,                               var.num_dims());
assert_eq!(0,                               var.num_attrs());
assert_eq!(vec![DIM_NAME_1, DIM_NAME_2],    var.get_dim_names());
assert_eq!(DATA_F32_LEN,                    var.len());
assert_eq!(DataType::F32,                   var.data_type());

assert_eq!(None,                            var.get_i8());
assert_eq!(None,                            var.get_u8());
assert_eq!(None,                            var.get_i16());
assert_eq!(None,                            var.get_i32());
assert_eq!(Some(&DATA_F32[..]),             var.get_f32());
assert_eq!(None,                            var.get_f64());

Get a reference to a Variable

const VAR_NAME: &str = "var_1";

// Get a reference to a `Variable`
let var: &Variable = data_set.get_var(VAR_NAME).unwrap();

// Get a mutable reference to a `Variable`
let var: &mut Variable = data_set.get_var_mut(VAR_NAME).unwrap();

Rename a variable

use netcdf3::{DataSet, DataType};
const VAR_NAME_1: &str = "var_1";
const VAR_NAME_2: &str = "var_2";
const DIM_NAME: &str = "dim_1";
const VAR_DATA: [i32; 4] = [1, 2, 3, 4];
const VAR_DATA_LEN: usize = VAR_DATA.len();

// Create a data set and a variable
let mut data_set: DataSet = DataSet::new();
data_set.add_fixed_dim(DIM_NAME, VAR_DATA_LEN).unwrap();
data_set.add_var_i32::<&str>(VAR_NAME_1, &[DIM_NAME]).unwrap();
data_set.set_var_i32(VAR_NAME_1, VAR_DATA.to_vec()).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_NAME_1));
assert_eq!(Some(VAR_DATA_LEN),  data_set.get_var_len(VAR_NAME_1));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_NAME_1));
assert_eq!(Some(&VAR_DATA[..]), data_set.get_var_i32(VAR_NAME_1));
assert_eq!(false,               data_set.has_var(VAR_NAME_2));
assert_eq!(None,                data_set.get_var_len(VAR_NAME_2));
assert_eq!(None,                data_set.get_var_data_type(VAR_NAME_2));
assert_eq!(None,                data_set.get_var_i32(VAR_NAME_2));

// Rename the variable
data_set.rename_var(VAR_NAME_1, VAR_NAME_2).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(false,               data_set.has_var(VAR_NAME_1));
assert_eq!(None,                data_set.get_var_len(VAR_NAME_1));
assert_eq!(None,                data_set.get_var_data_type(VAR_NAME_1));
assert_eq!(None,                data_set.get_var_i32(VAR_NAME_1));
assert_eq!(true,                data_set.has_var(VAR_NAME_2));
assert_eq!(Some(VAR_DATA_LEN),  data_set.get_var_len(VAR_NAME_2));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_NAME_2));
assert_eq!(Some(&VAR_DATA[..]), data_set.get_var_i32(VAR_NAME_2));

Remove a variable

use netcdf3::{DataSet, DataType};

const DIM_NAME: &str = "dim_1";
const VAR_NAME: &str = "var_1";
const VAR_DATA: [i32; 4] = [1, 2, 3, 4];
const VAR_DATA_LEN: usize = VAR_DATA.len();

// Create a data set and a variable
let mut data_set: DataSet = DataSet::new();

data_set.add_fixed_dim(DIM_NAME, VAR_DATA_LEN).unwrap();
data_set.add_var_i32::<&str>(VAR_NAME, &[DIM_NAME]).unwrap();
data_set.set_var_i32(VAR_NAME, VAR_DATA.to_vec()).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_NAME));
assert_eq!(Some(VAR_DATA_LEN),  data_set.get_var_len(VAR_NAME));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_NAME));
assert_eq!(Some(&VAR_DATA[..]), data_set.get_var_i32(VAR_NAME));

// Remove the variable
data_set.remove_var(VAR_NAME).unwrap();

assert_eq!(0,       data_set.num_vars());
assert_eq!(false,   data_set.has_var(VAR_NAME));
assert_eq!(None,    data_set.get_var_len(VAR_NAME));
assert_eq!(None,    data_set.get_var_data_type(VAR_NAME));
assert_eq!(None,    data_set.get_var_i32(VAR_NAME));

Methods

impl Variable

pub fn name(&self) -> &str

Return the name of the variable.

pub fn data_type(&self) -> DataType

Returns the name of the variable.

pub fn len(&self) -> usize

Returns the total number of elements.

If the variable is a record variable then len = num_chunks * num_elements_per_chunk.

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

pub fn num_dims(&self) -> usize

Returns the number of dimensions.

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

Returns the list of the dimensions

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

Returns the list of the dimension names

pub fn is_record_var(&self) -> bool

Returns :

• true if the variable is defined over the unlimited size dimension, then has several records
• false otherwise

pub fn num_attrs(&self) -> usize

Returns the number of attributes.

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

Returns :

• true if the variable has the attribute
• false if not

pub fn num_elements_per_chunk(&self) -> usize

pub fn chunk_size(&self) -> usize

Returns the size of each chunk (the number of bytes) including zero-padding bytes.

pub fn num_chunks(&self) -> usize

Returns the number of chunks.

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

Returns all attributs defined in the dataset or in the variable.

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

Returns all attributs defined in the dataset or in the variable.

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

Returns a reference counter to the named attribute, return an error if the attribute is not already defined.

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

pub fn get_i8(&self) -> Option<&[i8]>

Returns a reference to the i8 data vector.

Returns None if :

• The variable is not a i8 data variable.
• The data are not initialized or not be loaded while the file reading.

Example

use netcdf3::{DataSet, DataType, InvalidDataSet};

const DIM_NAME: &str = "dim_1";

const VAR_I32_NAME: &str = "var_i8";
const DATA_I32: [i32; 3] = [1, 2, 3];
const DATA_I32_LEN: usize = DATA_I32.len();

// Create a new data set, one dimension
let mut data_set = DataSet::new();
data_set.add_fixed_dim(DIM_NAME, DATA_I32_LEN).unwrap();

assert_eq!(0,       data_set.num_vars());
assert_eq!(false,   data_set.has_var(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_len(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_i8(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_u8(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_i16(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_i32(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_f32(VAR_I32_NAME));
assert_eq!(None,    data_set.get_var_f64(VAR_I32_NAME));

// Create a `i32` variable but don't set its values.
data_set.add_var_i32(VAR_I32_NAME, &[DIM_NAME]).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_I32_NAME));
assert_eq!(Some(DATA_I32_LEN),  data_set.get_var_len(VAR_I32_NAME));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i8(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_u8(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i16(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i32(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_f32(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_f64(VAR_I32_NAME));

// Set a data vector in the `i32` variable
data_set.set_var_i32(VAR_I32_NAME, DATA_I32.to_vec()).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_I32_NAME));
assert_eq!(Some(DATA_I32_LEN),  data_set.get_var_len(VAR_I32_NAME));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i8(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_u8(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i16(VAR_I32_NAME));
assert_eq!(Some(&DATA_I32[..]), data_set.get_var_i32(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_f32(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_f64(VAR_I32_NAME));

pub fn get_u8(&self) -> Option<&[u8]>

Returns a reference to the u8 data vector (refer to the method get_i8).

pub fn get_i16(&self) -> Option<&[i16]>

Returns a reference to the i16 data vector (refer to the method get_i8).

pub fn get_i32(&self) -> Option<&[i32]>

Returns a reference to the i32 data vector (refer to the method get_i8).

pub fn get_f32(&self) -> Option<&[f32]>

Returns a reference to the f32 data vector (refer to the method get_i8).

pub fn get_f64(&self) -> Option<&[f64]>

Returns a reference to the f64 data vector (refer to the method get_i8).

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

Set i8 data

Returns an error if :

• The length of the data vector is not equal to the variable length.
• The data type is not the same.

Example

use netcdf3::{DataSet, DataType, InvalidDataSet};

const DIM_NAME: &str = "dim_1";

const VAR_I32_NAME: &str = "var_i8";
const DATA_I32: [i32; 3] = [1, 2, 3];
const DATA_I32_LEN: usize = DATA_I32.len();

const DATA_F32: [f32; 3] = [1.0, 2.0, 3.0];
const DATA_F32_LEN: usize = DATA_F32.len();

assert_eq!(DATA_I32_LEN, DATA_F32_LEN);

// Create a new data set, one dimension, and one variable
let mut data_set = DataSet::new();
data_set.add_fixed_dim(DIM_NAME, DATA_I32_LEN).unwrap();
data_set.add_var_i32(VAR_I32_NAME, &[DIM_NAME]).unwrap();

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_I32_NAME));
assert_eq!(Some(DATA_I32_LEN),  data_set.get_var_len(VAR_I32_NAME));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i32(VAR_I32_NAME));

// Try to set a data vector with a wrong number of elements
assert_eq!(
    InvalidDataSet::VariableMismatchDataLength{
        var_name: String::from(VAR_I32_NAME),
        req: DATA_I32_LEN,
        get: DATA_I32_LEN - 1,
    },
    data_set.set_var_i32(VAR_I32_NAME, DATA_I32[0..(DATA_I32_LEN - 1)].to_vec()).unwrap_err()
);

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_I32_NAME));
assert_eq!(Some(DATA_I32_LEN),  data_set.get_var_len(VAR_I32_NAME));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i32(VAR_I32_NAME));

/// Try to set a data vector with a wrong datat type
assert_eq!(
    InvalidDataSet::VariableMismatchDataType{
        var_name: String::from(VAR_I32_NAME),
        req: DataType::I32,
        get: DataType::F32,
    },
    data_set.set_var_f32(VAR_I32_NAME, DATA_F32.to_vec()).unwrap_err()
);

assert_eq!(1,                   data_set.num_vars());
assert_eq!(true,                data_set.has_var(VAR_I32_NAME));
assert_eq!(Some(DATA_I32_LEN),  data_set.get_var_len(VAR_I32_NAME));
assert_eq!(Some(DataType::I32), data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(None,                data_set.get_var_i32(VAR_I32_NAME));

// Set a data vector with the valid number of elements and the valid data type
data_set.set_var_i32(VAR_I32_NAME, DATA_I32.to_vec()).unwrap();

assert_eq!(1,                       data_set.num_vars());
assert_eq!(true,                    data_set.has_var(VAR_I32_NAME));
assert_eq!(Some(DATA_I32_LEN),      data_set.get_var_len(VAR_I32_NAME));
assert_eq!(Some(DataType::I32),     data_set.get_var_data_type(VAR_I32_NAME));
assert_eq!(Some(&DATA_I32[..]),    data_set.get_var_i32(VAR_I32_NAME));

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

Set u8 data (refer to the method set_i8).

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

Set i16 data (refer to the method set_i8).

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

Set i32 data (refer to the method set_i8).

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

Set f32 data (refer to the method set_i8).

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

Set f64 data (refer to the method set_i8).

Trait Implementations

impl Clone for Variable

fn clone(&self) -> Variable

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Variable

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

Formats the value using the given formatter.

impl PartialEq<Variable> for Variable

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

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

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

This method tests for !=.

impl StructuralPartialEq for Variable