Skip to main content

netcdf_core/
lib.rs

1//! Shared NetCDF data model used by reader and writer crates.
2
3/// Errors produced by shared NetCDF model helpers.
4#[derive(Debug, thiserror::Error)]
5pub enum Error {
6    #[error("invalid data: {0}")]
7    InvalidData(String),
8}
9
10pub type Result<T> = std::result::Result<T, Error>;
11
12/// NetCDF file format.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum NcFormat {
15    Classic,
16    Offset64,
17    Cdf5,
18    Nc4,
19    Nc4Classic,
20}
21
22/// NetCDF-4 metadata reconstruction policy.
23#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
24pub enum NcMetadataMode {
25    #[default]
26    Strict,
27    Lossy,
28}
29
30/// NetCDF classic type codes.
31pub const NC_BYTE: u32 = 1;
32pub const NC_CHAR: u32 = 2;
33pub const NC_SHORT: u32 = 3;
34pub const NC_INT: u32 = 4;
35pub const NC_FLOAT: u32 = 5;
36pub const NC_DOUBLE: u32 = 6;
37pub const NC_UBYTE: u32 = 7;
38pub const NC_USHORT: u32 = 8;
39pub const NC_UINT: u32 = 9;
40pub const NC_INT64: u32 = 10;
41pub const NC_UINT64: u32 = 11;
42
43/// Default fill value for NC_BYTE variables when prefilled data is needed.
44pub const NC_FILL_BYTE: i8 = -127;
45/// Default fill value for NC_CHAR variables when prefilled data is needed.
46pub const NC_FILL_CHAR: u8 = 0;
47/// Default fill value for NC_SHORT variables when prefilled data is needed.
48pub const NC_FILL_SHORT: i16 = -32767;
49/// Default fill value for NC_INT variables when prefilled data is needed.
50pub const NC_FILL_INT: i32 = -2147483647;
51/// Default fill value for NC_FLOAT variables when prefilled data is needed.
52pub const NC_FILL_FLOAT: f32 = 9.969_21e36_f32;
53/// Default fill value for NC_DOUBLE variables when prefilled data is needed.
54pub const NC_FILL_DOUBLE: f64 = 9.969_209_968_386_869e36_f64;
55/// Default fill value for NC_UBYTE variables when prefilled data is needed.
56pub const NC_FILL_UBYTE: u8 = 255;
57/// Default fill value for NC_USHORT variables when prefilled data is needed.
58pub const NC_FILL_USHORT: u16 = 65535;
59/// Default fill value for NC_UINT variables when prefilled data is needed.
60pub const NC_FILL_UINT: u32 = 4294967295;
61/// Default fill value for NC_INT64 variables when prefilled data is needed.
62pub const NC_FILL_INT64: i64 = -9223372036854775806;
63/// Default fill value for NC_UINT64 variables when prefilled data is needed.
64pub const NC_FILL_UINT64: u64 = 18446744073709551614;
65
66/// A NetCDF dimension.
67#[derive(Debug, Clone, PartialEq, Eq)]
68pub struct NcDimension {
69    pub name: String,
70    pub size: u64,
71    pub is_unlimited: bool,
72}
73
74/// A field within a compound type.
75#[derive(Debug, Clone, PartialEq, Eq)]
76pub struct NcCompoundField {
77    pub name: String,
78    pub offset: u64,
79    pub dtype: NcType,
80}
81
82/// A typed integer value used by NetCDF-4 enum definitions and values.
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
84pub enum NcIntegerValue {
85    I8(i8),
86    U8(u8),
87    I16(i16),
88    U16(u16),
89    I32(i32),
90    U32(u32),
91    I64(i64),
92    U64(u64),
93}
94
95impl NcIntegerValue {
96    pub fn as_i128(self) -> Option<i128> {
97        match self {
98            NcIntegerValue::I8(value) => Some(value as i128),
99            NcIntegerValue::U8(value) => Some(value as i128),
100            NcIntegerValue::I16(value) => Some(value as i128),
101            NcIntegerValue::U16(value) => Some(value as i128),
102            NcIntegerValue::I32(value) => Some(value as i128),
103            NcIntegerValue::U32(value) => Some(value as i128),
104            NcIntegerValue::I64(value) => Some(value as i128),
105            NcIntegerValue::U64(value) => Some(i128::from(value)),
106        }
107    }
108
109    pub fn as_u128(self) -> Option<u128> {
110        match self {
111            NcIntegerValue::I8(value) => u128::try_from(value).ok(),
112            NcIntegerValue::U8(value) => Some(value as u128),
113            NcIntegerValue::I16(value) => u128::try_from(value).ok(),
114            NcIntegerValue::U16(value) => Some(value as u128),
115            NcIntegerValue::I32(value) => u128::try_from(value).ok(),
116            NcIntegerValue::U32(value) => Some(value as u128),
117            NcIntegerValue::I64(value) => u128::try_from(value).ok(),
118            NcIntegerValue::U64(value) => Some(value as u128),
119        }
120    }
121}
122
123/// A named member of a NetCDF-4 enum type.
124#[derive(Debug, Clone, PartialEq, Eq)]
125pub struct NcEnumMember {
126    pub name: String,
127    pub value: NcIntegerValue,
128}
129
130/// NetCDF data types.
131#[derive(Debug, Clone, PartialEq, Eq)]
132pub enum NcType {
133    Byte,
134    Char,
135    Short,
136    Int,
137    Float,
138    Double,
139    UByte,
140    UShort,
141    UInt,
142    Int64,
143    UInt64,
144    String,
145    Enum {
146        base: Box<NcType>,
147        members: Vec<NcEnumMember>,
148    },
149    Compound {
150        size: u32,
151        fields: Vec<NcCompoundField>,
152    },
153    Opaque {
154        size: u32,
155        tag: String,
156    },
157    Array {
158        base: Box<NcType>,
159        dims: Vec<u64>,
160    },
161    VLen {
162        base: Box<NcType>,
163    },
164}
165
166impl NcType {
167    pub fn size(&self) -> Result<usize> {
168        match self {
169            NcType::Byte | NcType::Char | NcType::UByte => Ok(1),
170            NcType::Short | NcType::UShort => Ok(2),
171            NcType::Int | NcType::UInt | NcType::Float => Ok(4),
172            NcType::Int64 | NcType::UInt64 | NcType::Double => Ok(8),
173            NcType::String => Ok(std::mem::size_of::<usize>()),
174            NcType::Enum { base, .. } => base.size(),
175            NcType::Compound { size, .. } => Ok(*size as usize),
176            NcType::Opaque { size, .. } => Ok(*size as usize),
177            NcType::Array { base, dims } => {
178                let base_size = base.size()?;
179                let count = dims.iter().try_fold(1usize, |acc, &dim| {
180                    let dim = usize::try_from(dim).map_err(|_| {
181                        Error::InvalidData(
182                            "NetCDF array type dimension exceeds platform usize capacity"
183                                .to_string(),
184                        )
185                    })?;
186                    acc.checked_mul(dim).ok_or_else(|| {
187                        Error::InvalidData(
188                            "NetCDF array type element count exceeds platform usize capacity"
189                                .to_string(),
190                        )
191                    })
192                })?;
193                base_size.checked_mul(count).ok_or_else(|| {
194                    Error::InvalidData(
195                        "NetCDF array type byte size exceeds platform usize capacity".to_string(),
196                    )
197                })
198            }
199            NcType::VLen { .. } => Ok(std::mem::size_of::<usize>()),
200        }
201    }
202
203    pub fn classic_type_code(&self) -> Option<u32> {
204        match self {
205            NcType::Byte => Some(NC_BYTE),
206            NcType::Char => Some(NC_CHAR),
207            NcType::Short => Some(NC_SHORT),
208            NcType::Int => Some(NC_INT),
209            NcType::Float => Some(NC_FLOAT),
210            NcType::Double => Some(NC_DOUBLE),
211            NcType::UByte => Some(NC_UBYTE),
212            NcType::UShort => Some(NC_USHORT),
213            NcType::UInt => Some(NC_UINT),
214            NcType::Int64 => Some(NC_INT64),
215            NcType::UInt64 => Some(NC_UINT64),
216            NcType::String
217            | NcType::Enum { .. }
218            | NcType::Compound { .. }
219            | NcType::Opaque { .. }
220            | NcType::Array { .. }
221            | NcType::VLen { .. } => None,
222        }
223    }
224
225    pub fn is_primitive(&self) -> bool {
226        matches!(
227            self,
228            NcType::Byte
229                | NcType::Char
230                | NcType::Short
231                | NcType::Int
232                | NcType::Float
233                | NcType::Double
234                | NcType::UByte
235                | NcType::UShort
236                | NcType::UInt
237                | NcType::Int64
238                | NcType::UInt64
239                | NcType::String
240        )
241    }
242}
243
244/// A decoded NetCDF-4 enum value.
245#[derive(Debug, Clone, PartialEq, Eq)]
246pub struct NcEnumValue {
247    /// The stored integer value.
248    pub value: NcIntegerValue,
249    /// The matching enum member name, if the stored value is declared by the type.
250    pub member: Option<String>,
251}
252
253/// A decoded field of a NetCDF-4 compound value.
254#[derive(Debug, Clone, PartialEq)]
255pub struct NcCompoundValueField {
256    pub name: String,
257    pub value: NcValue,
258}
259
260/// A decoded fixed-size NetCDF-4 array value.
261#[derive(Debug, Clone, PartialEq)]
262pub struct NcArrayValue {
263    pub dims: Vec<u64>,
264    pub values: Vec<NcValue>,
265}
266
267/// A decoded NetCDF-4 value.
268#[derive(Debug, Clone, PartialEq)]
269pub enum NcValue {
270    Byte(i8),
271    Char(u8),
272    Short(i16),
273    Int(i32),
274    Float(f32),
275    Double(f64),
276    UByte(u8),
277    UShort(u16),
278    UInt(u32),
279    Int64(i64),
280    UInt64(u64),
281    String(String),
282    Enum(NcEnumValue),
283    Opaque(Vec<u8>),
284    Compound(Vec<NcCompoundValueField>),
285    Array(NcArrayValue),
286    VLen(Vec<NcValue>),
287}
288
289/// A NetCDF attribute value.
290#[derive(Debug, Clone, PartialEq)]
291pub enum NcAttrValue {
292    Bytes(Vec<i8>),
293    Chars(String),
294    Shorts(Vec<i16>),
295    Ints(Vec<i32>),
296    Floats(Vec<f32>),
297    Doubles(Vec<f64>),
298    UBytes(Vec<u8>),
299    UShorts(Vec<u16>),
300    UInts(Vec<u32>),
301    Int64s(Vec<i64>),
302    UInt64s(Vec<u64>),
303    Strings(Vec<String>),
304    /// Decoded compound, opaque, or non-string variable-length attribute values.
305    UserDefined {
306        dtype: NcType,
307        values: Vec<NcValue>,
308    },
309}
310
311impl NcAttrValue {
312    pub fn as_string(&self) -> Option<String> {
313        match self {
314            NcAttrValue::Chars(s) => Some(s.clone()),
315            NcAttrValue::Strings(v) if v.len() == 1 => Some(v[0].clone()),
316            _ => None,
317        }
318    }
319
320    pub fn as_f64(&self) -> Option<f64> {
321        match self {
322            NcAttrValue::Bytes(v) => v.first().map(|&x| x as f64),
323            NcAttrValue::Shorts(v) => v.first().map(|&x| x as f64),
324            NcAttrValue::Ints(v) => v.first().map(|&x| x as f64),
325            NcAttrValue::Floats(v) => v.first().map(|&x| x as f64),
326            NcAttrValue::Doubles(v) => v.first().copied(),
327            NcAttrValue::UBytes(v) => v.first().map(|&x| x as f64),
328            NcAttrValue::UShorts(v) => v.first().map(|&x| x as f64),
329            NcAttrValue::UInts(v) => v.first().map(|&x| x as f64),
330            NcAttrValue::Int64s(v) => v.first().map(|&x| x as f64),
331            NcAttrValue::UInt64s(v) => v.first().map(|&x| x as f64),
332            NcAttrValue::Chars(_) | NcAttrValue::Strings(_) | NcAttrValue::UserDefined { .. } => {
333                None
334            }
335        }
336    }
337
338    pub fn as_f64_vec(&self) -> Option<Vec<f64>> {
339        match self {
340            NcAttrValue::Bytes(v) => Some(v.iter().map(|&x| x as f64).collect()),
341            NcAttrValue::Shorts(v) => Some(v.iter().map(|&x| x as f64).collect()),
342            NcAttrValue::Ints(v) => Some(v.iter().map(|&x| x as f64).collect()),
343            NcAttrValue::Floats(v) => Some(v.iter().map(|&x| x as f64).collect()),
344            NcAttrValue::Doubles(v) => Some(v.clone()),
345            NcAttrValue::UBytes(v) => Some(v.iter().map(|&x| x as f64).collect()),
346            NcAttrValue::UShorts(v) => Some(v.iter().map(|&x| x as f64).collect()),
347            NcAttrValue::UInts(v) => Some(v.iter().map(|&x| x as f64).collect()),
348            NcAttrValue::Int64s(v) => Some(v.iter().map(|&x| x as f64).collect()),
349            NcAttrValue::UInt64s(v) => Some(v.iter().map(|&x| x as f64).collect()),
350            NcAttrValue::Chars(_) | NcAttrValue::Strings(_) | NcAttrValue::UserDefined { .. } => {
351                None
352            }
353        }
354    }
355}
356
357/// A NetCDF attribute.
358#[derive(Debug, Clone, PartialEq)]
359pub struct NcAttribute {
360    pub name: String,
361    pub value: NcAttrValue,
362}
363
364/// A NetCDF variable. The offset fields are public for reader/writer crate
365/// interoperability; they are not portable semantic metadata.
366#[derive(Debug, Clone, PartialEq)]
367pub struct NcVariable {
368    pub name: String,
369    pub dimensions: Vec<NcDimension>,
370    pub dtype: NcType,
371    pub attributes: Vec<NcAttribute>,
372    #[doc(hidden)]
373    pub data_offset: u64,
374    #[doc(hidden)]
375    pub _data_size: u64,
376    #[doc(hidden)]
377    pub is_record_var: bool,
378    #[doc(hidden)]
379    pub record_size: u64,
380}
381
382impl NcVariable {
383    pub fn name(&self) -> &str {
384        &self.name
385    }
386
387    pub fn dimensions(&self) -> &[NcDimension] {
388        &self.dimensions
389    }
390
391    pub fn coordinate_dimension(&self) -> Option<&NcDimension> {
392        match self.dimensions.as_slice() {
393            [dim] if dim.name == self.name => Some(dim),
394            _ => None,
395        }
396    }
397
398    pub fn is_coordinate_variable(&self) -> bool {
399        self.coordinate_dimension().is_some()
400    }
401
402    pub fn is_coordinate_variable_for(&self, dimension_name: &str) -> bool {
403        self.coordinate_dimension()
404            .is_some_and(|dim| dim.name == dimension_name)
405    }
406
407    pub fn dtype(&self) -> &NcType {
408        &self.dtype
409    }
410
411    pub fn shape(&self) -> Vec<u64> {
412        self.dimensions.iter().map(|d| d.size).collect()
413    }
414
415    pub fn attributes(&self) -> &[NcAttribute] {
416        &self.attributes
417    }
418
419    pub fn attribute(&self, name: &str) -> Option<&NcAttribute> {
420        self.attributes.iter().find(|a| a.name == name)
421    }
422
423    pub fn ndim(&self) -> usize {
424        self.dimensions.len()
425    }
426
427    pub fn num_elements(&self) -> Result<u64> {
428        match self.dimensions.as_slice() {
429            [] => Ok(1),
430            [dim] => Ok(dim.size),
431            dimensions => {
432                let mut total = 1u64;
433                for dim in dimensions {
434                    total = total.checked_mul(dim.size).ok_or_else(|| {
435                        Error::InvalidData(
436                            "NetCDF variable element count overflows u64".to_string(),
437                        )
438                    })?;
439                }
440                Ok(total)
441            }
442        }
443    }
444}
445
446/// A NetCDF group.
447#[derive(Debug, Clone, PartialEq)]
448pub struct NcGroup {
449    pub name: String,
450    pub dimensions: Vec<NcDimension>,
451    pub variables: Vec<NcVariable>,
452    pub attributes: Vec<NcAttribute>,
453    pub groups: Vec<NcGroup>,
454}
455
456impl NcGroup {
457    pub fn variable(&self, name: &str) -> Option<&NcVariable> {
458        let (group_path, variable_name) = split_parent_path(name)?;
459        let group = self.group(group_path)?;
460        group.variables.iter().find(|v| v.name == variable_name)
461    }
462
463    pub fn dimension(&self, name: &str) -> Option<&NcDimension> {
464        let (group_path, dimension_name) = split_parent_path(name)?;
465        let group = self.group(group_path)?;
466        group.dimensions.iter().find(|d| d.name == dimension_name)
467    }
468
469    pub fn coordinate_variable(&self, name: &str) -> Option<&NcVariable> {
470        let (group_path, dimension_name) = split_parent_path(name)?;
471        let group = self.group(group_path)?;
472        group
473            .variables
474            .iter()
475            .find(|var| var.is_coordinate_variable_for(dimension_name))
476    }
477
478    pub fn coordinate_variables(&self) -> impl Iterator<Item = &NcVariable> {
479        self.variables
480            .iter()
481            .filter(|var| var.is_coordinate_variable())
482    }
483
484    pub fn attribute(&self, name: &str) -> Option<&NcAttribute> {
485        let (group_path, attribute_name) = split_parent_path(name)?;
486        let group = self.group(group_path)?;
487        group.attributes.iter().find(|a| a.name == attribute_name)
488    }
489
490    pub fn group(&self, name: &str) -> Option<&NcGroup> {
491        let trimmed = name.trim_matches('/');
492        if trimmed.is_empty() {
493            return Some(self);
494        }
495
496        let mut group = self;
497        for component in trimmed.split('/').filter(|part| !part.is_empty()) {
498            group = group.groups.iter().find(|child| child.name == component)?;
499        }
500
501        Some(group)
502    }
503}
504
505fn split_parent_path(path: &str) -> Option<(&str, &str)> {
506    let trimmed = path.trim_matches('/');
507    if trimmed.is_empty() {
508        return None;
509    }
510
511    match trimmed.rsplit_once('/') {
512        Some((group_path, leaf_name)) if !leaf_name.is_empty() => Some((group_path, leaf_name)),
513        Some(_) => None,
514        None => Some(("", trimmed)),
515    }
516}
517
518pub fn checked_usize_from_u64(value: u64, context: &str) -> Result<usize> {
519    usize::try_from(value)
520        .map_err(|_| Error::InvalidData(format!("{context} exceeds platform usize")))
521}
522
523pub fn checked_mul_u64(lhs: u64, rhs: u64, context: &str) -> Result<u64> {
524    lhs.checked_mul(rhs)
525        .ok_or_else(|| Error::InvalidData(format!("{context} exceeds u64 capacity")))
526}
527
528pub fn checked_shape_elements(shape: &[u64], context: &str) -> Result<u64> {
529    shape
530        .iter()
531        .try_fold(1u64, |acc, &dim| checked_mul_u64(acc, dim, context))
532}
533
534/// Compute the amount of padding needed to reach a 4-byte boundary.
535pub fn padding_to_4(len: usize) -> usize {
536    let rem = len % 4;
537    if rem == 0 {
538        0
539    } else {
540        4 - rem
541    }
542}
543
544/// Round up to the next 4-byte boundary.
545pub fn pad_to_4(len: usize) -> usize {
546    len + padding_to_4(len)
547}
548
549/// Hyperslab selection for reading/writing slices of NetCDF variables.
550#[derive(Debug, Clone, PartialEq, Eq)]
551pub struct NcSliceInfo {
552    pub selections: Vec<NcSliceInfoElem>,
553}
554
555/// A single dimension selection within a hyperslab.
556#[derive(Debug, Clone, PartialEq, Eq)]
557pub enum NcSliceInfoElem {
558    Index(u64),
559    Slice { start: u64, end: u64, step: u64 },
560}
561
562impl NcSliceInfo {
563    pub fn all(ndim: usize) -> Self {
564        NcSliceInfo {
565            selections: vec![
566                NcSliceInfoElem::Slice {
567                    start: 0,
568                    end: u64::MAX,
569                    step: 1,
570                };
571                ndim
572            ],
573        }
574    }
575}