1#[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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum NcFormat {
15 Classic,
16 Offset64,
17 Cdf5,
18 Nc4,
19 Nc4Classic,
20}
21
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
24pub enum NcMetadataMode {
25 #[default]
26 Strict,
27 Lossy,
28}
29
30pub 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
43pub const NC_FILL_BYTE: i8 = -127;
45pub const NC_FILL_CHAR: u8 = 0;
47pub const NC_FILL_SHORT: i16 = -32767;
49pub const NC_FILL_INT: i32 = -2147483647;
51pub const NC_FILL_FLOAT: f32 = 9.969_21e36_f32;
53pub const NC_FILL_DOUBLE: f64 = 9.969_209_968_386_869e36_f64;
55pub const NC_FILL_UBYTE: u8 = 255;
57pub const NC_FILL_USHORT: u16 = 65535;
59pub const NC_FILL_UINT: u32 = 4294967295;
61pub const NC_FILL_INT64: i64 = -9223372036854775806;
63pub const NC_FILL_UINT64: u64 = 18446744073709551614;
65
66#[derive(Debug, Clone, PartialEq, Eq)]
68pub struct NcDimension {
69 pub name: String,
70 pub size: u64,
71 pub is_unlimited: bool,
72}
73
74#[derive(Debug, Clone, PartialEq, Eq)]
76pub struct NcCompoundField {
77 pub name: String,
78 pub offset: u64,
79 pub dtype: NcType,
80}
81
82#[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#[derive(Debug, Clone, PartialEq, Eq)]
125pub struct NcEnumMember {
126 pub name: String,
127 pub value: NcIntegerValue,
128}
129
130#[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#[derive(Debug, Clone, PartialEq, Eq)]
246pub struct NcEnumValue {
247 pub value: NcIntegerValue,
249 pub member: Option<String>,
251}
252
253#[derive(Debug, Clone, PartialEq)]
255pub struct NcCompoundValueField {
256 pub name: String,
257 pub value: NcValue,
258}
259
260#[derive(Debug, Clone, PartialEq)]
262pub struct NcArrayValue {
263 pub dims: Vec<u64>,
264 pub values: Vec<NcValue>,
265}
266
267#[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#[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 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#[derive(Debug, Clone, PartialEq)]
359pub struct NcAttribute {
360 pub name: String,
361 pub value: NcAttrValue,
362}
363
364#[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#[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
534pub 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
544pub fn pad_to_4(len: usize) -> usize {
546 len + padding_to_4(len)
547}
548
549#[derive(Debug, Clone, PartialEq, Eq)]
551pub struct NcSliceInfo {
552 pub selections: Vec<NcSliceInfoElem>,
553}
554
555#[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}